<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.4 1999/07/22 15:09:12 thomas Exp $
Postgres documentation
-->

<refentry id="APP-INITLOCATION">
 <refmeta>
  <refentrytitle id="APP-INITLOCATION-TITLE">
   <application>initlocation</application>
  </refentrytitle>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   <application>initlocation</application>
  </refname>
  <refpurpose>
   Create a secondary <productname>Postgres</productname> database storage area
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
  <synopsis>
initlocation [ --location=<replaceable class="parameter">er">al</replaceable>ble> | -D <replaceable class="parameter">altdir</replaceable> ]
    [ --username=<replaceable class="parameter">name</replaceable> | -u <replaceable class="parameter">name</replaceable> ]
    [ <replaceable class="parameter">altdir</replaceable> ]
  </synopsis>

  <refsect2 id="R2-APP-INITLOCATION-1">
   <refsect2info>
    <date>1998-10-02</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term>--location=<replaceable class="parameter">altdir</replaceable></term>
      <term>-D <replaceable class="parameter">altdir</replaceable></term>
      <term><replaceable class="parameter">altdir</replaceable></term>
      <listitem>
       <para>
	Where in your Unix filesystem do you want alternate databases to go?
	The top level directory is called the <envar>PGDATA</envar> directory, so you
	might want to point your first alternate location at
	<envar>PGDATA2</envar>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>--username=<replaceable class="parameter">name</replaceable></term>
      <term>-u <replaceable class="parameter">name</replaceable></term>
      <term><envar>PGUSER</envar></term>
      <listitem>
       <para>
	Who will be the Unix filesystem owner of this database storage area?
	The
	<productname>Postgres</productname> superuser is a Unix user 
	who owns all files that store the database
	system and also owns the postmaster and backend processes that access them.
	Usually, this is the user who should run <application>initlocation</application>
	and who will thus have ownership of the directories and files.
       </para>
       <note>
	<para>
	 Only the Unix superuser can create a database system with a
	 different user as the <productname>Postgres</productname> superuser.
	 Specifying a user other than the <productname>Postgres</productname> superuser
	 may lead to database security and data integrity problems. Refer to the
	 <citetitle><productname>PostgreSQL</productname> Administrator's Guide</citetitle>
	 for more information.
	</para>
       </note>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>

  <refsect2 id="R2-APP-INITLOCATION-2">
   <refsect2info>
    <date>1998-09-26</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
    <application>initlocation</application> will create directories in 
    the specified place.

    <variablelist>
     <varlistentry>
      <term><computeroutput>
We are initializing the database area with username postgres (uid=500).
This user will own all the files and must also own the server process.
Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
       </computeroutput></term>
      <listitem>
       <para>
	Successful completion.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>
We are initializing the database area with username postgres (uid=500).
This user will own all the files and must also own the server process.
Creating Postgres database system directory /usr/local/src/testlocation
mkdir: cannot make directory `<replaceable class="parameter">altdir</replaceable>': Permission denied
       </computeroutput></term>
      <listitem>
       <para>
	You do not have filesystem permission to write to the specified directory area.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>
Valid username not given.  You must specify the username for
the Postgres superuser for the database system you are
initializing, either with the --username option or by default
to the USER environment variable.
       </computeroutput></term>
      <listitem>
       <para>
	The username which you have specified is not the
	<productname>Postgres</productname> superuser.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>
Can't tell what username to use.  You don't have the USER
environment variable set to your username and didn't specify the
--username option
       </computeroutput></term>
      <listitem>
       <para>
	Specify the <option>--username</option> command line option.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-APP-INITLOCATION-1">
  <refsect1info>
   <date>1998-09-26</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <application>initlocation</application> 
   creates a new <productname>Postgres</productname> secondary database storage area. 
   A secondary storage area contains a required tree of directories with
   the correct file permissions on those directories.
  </para>
  <para>
   Creating a database storage area consists of creating the directories in which
   database data might live.
  </para>
  <para>
   There are two kinds of arguments for <application>initlocation</application>.

   First, you can specify an environment variable (e.g. <envar>PGDATA2</envar>).
   This environment variable should be known to the backend for later use in
   <command>CREATE DATABASE/WITH LOCATION</command>
   or 
   <command>createdb -D <replaceable class="parameter">altdir</replaceable></command>.
   However, <emphasis>the backend daemon must have this variable in it's
    environment</emphasis> for this to succeed.

   Second, you may be able to specify an explicit
   absolute path to the top directory of the storage area. However,this second
   option is possible only if explicitly enabled during the
   <productname>Postgres</productname> installation. It is usually disabled
   to alleviate security and data integrity concerns.
  </para>
  <note>
   <para>
    <productname>Postgres</productname> will add <filename>/base/</filename>
    to the specified path to create the storage area.
   </para>
   <para>
    The backend requires that any argument to <option>WITH LOCATION</option> which is
    in all uppercase and which has no path delimiters is an environment variable.
   </para>
  </note>
 </refsect1>

 <refsect1 id="R1-APP-INITLOCATION-2">
  <refsect1info>
   <date>1998-09-26</date>
  </refsect1info>
  <title>
   Usage
  </title>
  <para>
   To create a database in an alternate location, using an environment variable:

   <programlisting>
% setenv PGDATA2 /opt/postgres/data
% initlocation PGDATA2
% createdb -D PGDATA2
   </programlisting>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->
