postmaster.sgml

PostgreSQL7.4.6 for Linux

    </variablelist>
   </para>

   <para>
    Two additional command line options are available for debugging
    problems that cause a server process to die abnormally.  The
    ordinary strategy in this situation is to notify all other server
    processes that they must terminate and then reinitialize the
    shared memory and semaphores.  This is because an errant server
    process could have corrupted some shared state before terminating.
    These options select alternative behaviors of the
    <command>postmaster</command> in this situation.
    <emphasis>Neither option is intended for use in ordinary
    operation.</emphasis>
   </para>

   <para>
   </para>

   <para>
    These special-case options are:

    <variablelist>
     <varlistentry>
      <term><option>-n</option></term>
      <listitem>
       <para>
	<command>postmaster</command>
	will not reinitialize shared data structures.  A knowledgeable system
	programmer can then use a debugger
	to examine shared memory and semaphore state.
       </para>
     </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-s</option></term>
      <listitem>
       <para>
	<command>postmaster</command>
	will stop all other server processes by sending the signal
	<literal>SIGSTOP</literal>,
	but will not cause them to terminate.  This permits system programmers
	to collect core dumps from all server processes by hand.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

 </refsect1>

 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGCLIENTENCODING</envar></term>

    <listitem>
     <para>
      Default character encoding used by clients.  (The clients may
      override this individually.)  This value can also be set in the
      configuration file.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PGDATA</envar></term>

    <listitem>
     <para>
      Default data direction location
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PGDATESTYLE</envar></term>

    <listitem>
     <para>
      Default value of the <varname>DATESTYLE</varname> run-time
      parameter.  (The use of this environment variable is deprecated.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PGPORT</envar></term>

    <listitem>
     <para>
      Default port (preferably set in the configuration file)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>TZ</envar></term>

    <listitem>
     <para>
      Server time zone
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>others</term>

    <listitem>
     <para>
      Other environment variables may be used to designate alternative
      data storage locations.  See <xref linkend="manage-ag-alternate-locs"> for more
      information.
     </para>
    </listitem>
   </varlistentry>

  </variablelist>
 </refsect1>

 <refsect1>
   <title>Diagnostics</title>

   <para>
    A failure message mentioning <literal>semget</> or <literal>shmget</>
    probably indicates you need to configure your kernel to provide adequate
    shared memory and semaphores.  For more discussion see <xref
    linkend="kernel-resources">.
   </para>

   <tip>
    <para>
     You may be able to postpone reconfiguring your kernel by decreasing
     <varname>shared_buffers</varname> to reduce the shared memory consumption
     of <productname>PostgreSQL</>, and/or by reducing
     <varname>max_connections</varname> to reduce the semaphore consumption.
    </para>
   </tip>

   <para>
    A failure message suggesting that another postmaster is already running
    should be checked carefully, for example by using the command
<screen>
<prompt>$</prompt> <userinput>ps ax | grep postmaster</userinput>
</screen>
        or
<screen>
<prompt>$</prompt> <userinput>ps -ef | grep postmaster</userinput>
</screen>
    depending on your system.  If you are certain that no conflicting
    postmaster is running, you may remove the lock file mentioned in the
    message and try again.
   </para>

   <para>
    A failure message indicating inability to bind to a port may indicate
    that that port is already in use by some non-PostgreSQL process.
    You may also get this error if you terminate the
    <command>postmaster</command>
    and immediately restart it using the same port; in this case, you must
    simply wait a few seconds until the operating system closes the port
    before trying again.  Finally, you may get this error if you specify
    a port number that your operating system considers to be reserved.
    For example, many versions of Unix consider port numbers under 1024 to
    be <quote>trusted</quote>
    and only permit the Unix superuser to access them.
   </para>

 </refsect1>

 <refsect1>
  <title>Notes</title>
  
  <para>
   If at all possible, <emphasis>do not</emphasis> use
   <literal>SIGKILL</literal> to kill the
   <command>postmaster</command>.  Doing so will prevent
   <command>postmaster</command> from freeing the system
   resources (e.g., shared memory and semaphores) that it holds before
   terminating.  This may cause problems for starting a fresh
   <command>postmaster</command> run.
  </para>

  <para>
   To terminate the <command>postmaster</command> normally,
   the signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>,
   or <literal>SIGQUIT</literal> can be used.  The first will wait for
   all clients to terminate before quitting, the second will
   forcefully disconnect all clients, and the third will quit
   immediately without proper shutdown, resulting in a recovery run
   during restart.   The <literal>SIGHUP</literal> signal will 
   reload the server configuration files.
  </para>

  <para>
   The utility command <xref linkend="app-pg-ctl"> can be used to
   start and shut down the <command>postmaster</command>
   safely and comfortably.
  </para>

  <para>
   The <option>--</> options will not work on <systemitem
   class="osname">FreeBSD</> or <systemitem class="osname">OpenBSD</>.
   Use <option>-c</> instead. This is a bug in the affected operating
   systems; a future release of <productname>PostgreSQL</productname>
   will provide a workaround if this is not fixed.
  </para>

 </refsect1>

 <refsect1 id="app-postmaster-examples">
  <title>Examples</title>
  <para>
   To start <command>postmaster</command> in the background
   using default values, type:

<screen>
<prompt>$</prompt> <userinput>nohup postmaster &gt;logfile 2&gt;&amp;1 &lt;/dev/null &amp;</userinput>
</screen>
  </para>

  <para>
   To start <command>postmaster</command> with a specific
   port:
<screen>
<prompt>$</prompt> <userinput>postmaster -p 1234</userinput>
</screen>
   This command will start up <command>postmaster</command>
   communicating through the port 1234. In order to connect to this
   <command>postmaster</command> using <application>psql</>, you would need to
   run it as
<screen>
<prompt>$</prompt> <userinput>psql -p 1234</userinput>
</screen>
   or set the environment variable <envar>PGPORT</envar>:
<screen>
<prompt>$</prompt> <userinput>export PGPORT=1234</userinput>
<prompt>$</prompt> <userinput>psql</userinput>
</screen>
  </para>

  <para>
   Named run-time parameters can be set in either of these styles:
<screen>
<prompt>$</prompt> <userinput>postmaster -c sort_mem=1234</userinput>
<prompt>$</prompt> <userinput>postmaster --sort-mem=1234</userinput>
</screen>
   Either form overrides whatever setting might exist for <varname>SORT_MEM</>
   in <filename>postgresql.conf</>.  Notice that underscores in parameter
   names can be written as either underscore or dash on the command line.
  </para>

  <tip>
  <para>
   Except for short-term experiments,
   it's probably better practice to edit the setting in
   <filename>postgresql.conf</> than to rely on a command-line switch
   to set a parameter.
  </para>
  </tip>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <para>
   <xref linkend="app-initdb">,
   <xref linkend="app-pg-ctl">
  </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:
-->