mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-21 15:53:24 +02:00
511 lines
16 KiB
Plaintext
511 lines
16 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.16 2000/11/22 01:41:13 momjian Exp $
|
|
Postgres documentation
|
|
-->
|
|
|
|
<refentry id="APP-POSTMASTER">
|
|
<docinfo>
|
|
<date>2000-11-12</date>
|
|
</docinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle id="APP-POSTMASTER-TITLE"><application>postmaster</application></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname id="postmaster-ref">postmaster</refname>
|
|
<refpurpose><productname>PostgreSQL</productname> multi-user database server</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>postmaster</command>
|
|
<arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
|
|
<arg>-B <replaceable>nbuffers</replaceable></arg>
|
|
<arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
|
|
<arg>-d <replaceable>debug-level</replaceable></arg>
|
|
<arg>-D <replaceable>datadir</replaceable></arg>
|
|
<arg>-F</arg>
|
|
<arg>-h <replaceable>hostname</replaceable></arg>
|
|
<arg>-i</arg>
|
|
<arg>-k <replaceable>filename</replaceable></arg>
|
|
<arg>-l</arg>
|
|
<arg>-N <replaceable>max-connections</replaceable></arg>
|
|
<arg>-o <replaceable>extra-options</replaceable></arg>
|
|
<arg>-p <replaceable>port</replaceable></arg>
|
|
<arg>-S</arg>
|
|
<group><arg>-n</arg><arg>-s</arg></group>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<application>postmaster</application> is the
|
|
<productname>PostgreSQL</productname> multi-user database server.
|
|
In order for a client application to access a database it connects
|
|
(over a network or locally) to a running
|
|
<application>postmaster</application>. The
|
|
<application>postmaster</application> then starts a separate server
|
|
process (<quote><xref linkend="app-postgres"
|
|
endterm="app-postgres-title"></quote>) to handle the connection.
|
|
The postmaster also manages the communication among server
|
|
processes.
|
|
</para>
|
|
|
|
<para>
|
|
By default the postmaster starts in the foreground and prints log
|
|
messages to the standard output. In practical applications the
|
|
postmaster should be started as a background process, perhaps at
|
|
boot time.
|
|
</para>
|
|
|
|
<para>
|
|
One postmaster always manages the data from exactly one database
|
|
cluster. A database cluster is a collection of databases that is
|
|
stored at a common file system location. When the postmaster
|
|
starts it needs to know the location of the database cluster files
|
|
(<quote>data area</quote>). This is done with the
|
|
<option>-D</option> invocation option or the <envar>PGDATA</envar>
|
|
environment variable, there is no default. More than one
|
|
postmaster process can run on a system at one time, as long as they
|
|
use different data areas and different port numbers (see below). A
|
|
data area is created with <xref linkend="app-initdb"
|
|
endterm="app-initdb-title">.
|
|
</para>
|
|
|
|
<refsect2 id="app-postmaster-options">
|
|
<title>Options</title>
|
|
<para>
|
|
<application>postmaster</application> accepts the following
|
|
command line arguments. For a detailed discussion of the options
|
|
consult the <citetitle>Administrator's Guide</citetitle>. You can
|
|
also save typing most of these options by setting up a
|
|
configuration file.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>-A 0|1</term>
|
|
<listitem>
|
|
<para>
|
|
Enables run-time assert checks, which is a debugging aid to
|
|
detect programming mistakes. This is only available if it was
|
|
enabled during compilation. If so, the default is on.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-B <replaceable class="parameter">nbuffers</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the number of shared buffers for use by the server
|
|
processes. This value defaults to 64 buffers, where each
|
|
buffer is 8 kB.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Sets a named run-time parameter. Consult the
|
|
<citetitle>Administrator's Guide</citetitle> for a list and
|
|
descriptions. Most of the other command line options are in
|
|
fact short forms of such a parameter assignment.
|
|
</para>
|
|
|
|
<para>
|
|
On some systems it is also possible to equivalently use
|
|
GNU-style long options in the form
|
|
<literal>--name=value</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-d <replaceable>debug-level</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the debug level. The higher this value is set, the more
|
|
debugging output is written to the server log. The default is
|
|
0, which means no debugging. Values up to 4 make sense.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-D <replaceable class="parameter">datadir</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the file system location of the data directory. See
|
|
discussion above.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-F</term>
|
|
<listitem>
|
|
<para>
|
|
Disables <function>fsync</function> calls for performance
|
|
improvement at the risk of data corruption. Read the detailed
|
|
documentation before using this!
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-h <replaceable class="parameter">hostname</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the TCP/IP hostname or address on which the
|
|
<application>postmaster</application> is to listen for
|
|
connections from client applications. Defaults to the value
|
|
of the <envar>PGHOST</envar> environment variable, or if
|
|
<envar>PGHOST</envar> is not set, it defaults to listening on
|
|
all configured addresses (including localhost).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-i</term>
|
|
<listitem>
|
|
<para>
|
|
Allows clients to connect via TCP/IP (Internet domain)
|
|
connections. Without this option, only local Unix domain
|
|
socket connections are accepted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-k <replaceable class="parameter">filename</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the directory for Unix domain socket on which the
|
|
<application>postmaster</application> is to listen for
|
|
connections from client applications. Defaults to the value
|
|
of the <envar>PGUNIXSOCKET</envar> environment variable, or if
|
|
<envar>PGUNIXSOCKET</envar> is not set, then defaults to a
|
|
file in <filename>/tmp</filename>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-l</term>
|
|
<listitem>
|
|
<para>
|
|
Enables secure connections using SSL. The <option>-i</option>
|
|
option is also required. You must have compiled with SSL
|
|
enabled to use this option.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-N <replaceable class="parameter">max-connections</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Sets the maximum number of client connections that this
|
|
postmaster will accept. By default, this value is 32, but it
|
|
can be set as high as 1024 if your system will support that
|
|
many processes. (Note that <option>-B</option> is required to
|
|
be at least twice <option>-N</option>.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-o <replaceable class="parameter">extra-options</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The command line-style options specified in <replaceable
|
|
class="parameter">EXTRA-OPTIONS</replaceable> are passed to
|
|
all backend server processes started by this
|
|
<application>postmaster</application>. See <xref
|
|
linkend="app-postgres" endterm="app-postgres-title"> for
|
|
possibilities. If the option string contains any spaces, the
|
|
entire string must be quoted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-p <replaceable class="parameter">port</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the TCP/IP port or local Unix domain socket file
|
|
extension on which the <application>postmaster</application>
|
|
is to listen for connections from client applications.
|
|
Defaults to the value of the <envar>PGPORT</envar> environment
|
|
variable, or if <envar>PGPORT</envar> is not set, then
|
|
defaults to the value established during compilation (normally
|
|
5432). If you specify a port other than the default port,
|
|
then all client applications must specify the same port using
|
|
either command-line options or <envar>PGPORT</envar>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-S</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies that the <application>postmaster</application>
|
|
process should start up in silent mode. That is, it will
|
|
disassociate from the user's (controlling) terminal, start its
|
|
own process group, and redirect its standard output and
|
|
standard error to <filename>/dev/null</filename>.
|
|
</para>
|
|
<para>
|
|
Using this switch discards all logging output, which is
|
|
probably not what you want, since it makes it very difficult
|
|
to troubleshoot problems. See below for a better way to start
|
|
the postmaster in the background.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Two additional command line options are available for debugging
|
|
problems that cause a backend to die abnormally. These options
|
|
control the behavior of the <application>postmaster</application>
|
|
in this situation, and <emphasis>neither option is intended for
|
|
use in ordinary operation</emphasis>.
|
|
</para>
|
|
|
|
<para>
|
|
The ordinary strategy for this situation is to notify all other
|
|
backends that they must terminate and then reinitialize the shared
|
|
memory and semaphores. This is because an errant backend could
|
|
have corrupted some shared state before terminating.
|
|
</para>
|
|
|
|
<para>
|
|
These special-case options are:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>-n</term>
|
|
<listitem>
|
|
<para>
|
|
<application>postmaster</application>
|
|
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>-s</term>
|
|
<listitem>
|
|
<para>
|
|
<application>postmaster</application>
|
|
will stop all other backend 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 backend processes by hand.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2 id="R2-APP-POSTMASTER-2">
|
|
<title>
|
|
Outputs
|
|
</title>
|
|
<para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><computeroutput>
|
|
semget: No space left on device
|
|
</computeroutput></term>
|
|
<listitem>
|
|
<para>
|
|
If you see this message, you should run the
|
|
<application>ipcclean</application>
|
|
command. After doing so, try starting
|
|
<application>postmaster</application>
|
|
again. If this still doesn't work, you probably need to configure
|
|
your kernel for shared memory and semaphores as described in the
|
|
installation notes. If you run multiple instances of
|
|
<application>postmaster</application>
|
|
on a single host, or have a kernel with particularly small shared memory
|
|
and/or semaphore limits, you may have to reconfigure your kernel to increase
|
|
its shared memory or semaphore parameters.
|
|
|
|
<tip>
|
|
<para>
|
|
You may be able to postpone
|
|
reconfiguring your kernel by decreasing -B to reduce
|
|
<productname>Postgres</productname>' shared memory
|
|
consumption, and/or by reducing -N to reduce Postgres' semaphore
|
|
consumption.
|
|
</para>
|
|
</tip>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><computeroutput>
|
|
StreamServerPort: cannot bind to port
|
|
</computeroutput></term>
|
|
<listitem>
|
|
<para>
|
|
If you see this message, you should make certain that there is no
|
|
other <application>postmaster</application>
|
|
process already running on the same port number. The easiest way to
|
|
determine this is by using the command
|
|
<programlisting>
|
|
$ ps -ax | grep postmaster
|
|
</programlisting>
|
|
on BSD-based systems, or
|
|
<programlisting>
|
|
$ ps -e | grep postmast
|
|
</programlisting>
|
|
for System V-like or POSIX-compliant systems such as HP-UX.
|
|
</para>
|
|
|
|
<para>
|
|
If you
|
|
are sure that no other
|
|
<application>postmaster</application>
|
|
processes are running and you still get this error, try specifying a
|
|
different port using the
|
|
<literal>-p</literal>
|
|
option. You may also get this error if you terminate the
|
|
<application>postmaster</application>
|
|
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 <firstterm>trusted</firstterm>
|
|
and only permit the Unix superuser to access them.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><computeroutput>
|
|
IpcMemoryAttach: shmat() failed: Permission denied
|
|
</computeroutput></term>
|
|
<listitem>
|
|
<para>
|
|
A likely explanation is that another user attempted to start a
|
|
<application>postmaster</application>
|
|
process on the same port which acquired shared resources and then
|
|
died. Since Postgres shared memory keys are based on the port number
|
|
assigned to the
|
|
<application>postmaster</application>,
|
|
such conflicts are likely if there is more than one installation on
|
|
a single host. If there are no other
|
|
<application>postmaster</application>
|
|
processes currently running (see above), run
|
|
<application>ipcclean</application>
|
|
and try again. If other <application>postmaster</application>
|
|
images
|
|
are running, you will have to find the owners of those processes to
|
|
coordinate the assignment of port numbers and/or removal of unused
|
|
shared memory segments.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
If at all possible, <emphasis>do not</emphasis> use
|
|
<literal>SIGKILL</literal> to kill the
|
|
<application>postmaster</application>. This will prevent
|
|
<application>postmaster</application> from freeing the system
|
|
resources (e.g., shared memory and semaphores) that it holds before
|
|
terminating.
|
|
</para>
|
|
|
|
<para>
|
|
To terminate the postmaster 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 lengthy shutdown, resulting in a recovery run
|
|
during restart.
|
|
</para>
|
|
|
|
<para>
|
|
The utility command <xref linkend="app-pg-ctl"> can be used to
|
|
start and shut down the postmaster safely and comfortably.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="app-postmaster-usage">
|
|
<title>Usage</title>
|
|
<para>
|
|
To start <application>postmaster</application> in the background
|
|
using default values, type:
|
|
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>nohup postmaster >logfile 2>&1 </dev/null &</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To start <application>postmaster</application> with a specific
|
|
port:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>postmaster -p 1234</userinput>
|
|
</screen>
|
|
This command will start up <application>postmaster</application>
|
|
communicating through the port 1234. In order to connect to this
|
|
<application>postmaster</application> using 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>
|
|
</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:
|
|
-->
|