POSTMASTER(UNIX)
NAME
postmaster - run the Postgres postmaster
SYNOPSIS
postmaster [-B n_buffers] [-D data_dir] [-S] [-a system]
[-b backend_pathname] [-d [debug_level]] [-i] [-n]
[-o backend_options] [-p port] [-s]
DESCRIPTION
The postmaster manages the communication between frontend
and backend processes, as well as allocating the shared
buffer pool and semaphores (on machines without a test-
and-set instruction). The postmaster does not itself
interact with the user and should be started as a back-
ground process. Only one postmaster should be run on a
machine.
The postmaster understands the following command-line
options:
-B n_buffers
n_buffers is the number of shared-memory buffers for
the postmaster to allocate and manage for the backend
server processes that it starts. This value defaults
to 64, and each buffer is 8k bytes.
-D data_dir
Specifies the directory to use as the root of the
tree of database directories. This directory uses
the value of the environment variable PGDATA. If
PGDATA is not set, then the directory used is $POST-
GRESHOME/data. If neither environment variable is
set and this command-line option is not specified,
the default directory that was set at compile-time is
used.
-S Specifies that the postmaster process should start up
in silent mode. That is, it will disassociate from
the user's (controlling) tty and start its own pro-
cess group. This should not be used in combination
with debugging options because any messages printed
to standard output and standard error are discarded.
-a system
Specifies whether or not to use the authentication
system system (see pgintro(1)) for frontend applica-
tions to use in connecting to the postmaster process.
Specify system to enable a system, or nosystem to
disable a system. For example, to permit users to
use Kerberos authentication, use -a kerberos; to deny
any unauthenticated connections, use -a nounauth .
This option no longer has any effect.
-b backend_pathname
backend_pathname is the full pathname of the Postgres
backend server executable file that the postmaster
will invoke when it receives a connection from a
frontend application. If this option is not used,
then the postmaster tries to find this executable
file in the directory in which its own executable is
located (this is done by looking at the pathname
under which the postmaster was invoked. If no path-
name was specified, then the PATH environment vari-
able is searched for an executable named "postgres").
-d [debug_level]
The optional argument debug_level determines the
amount of debugging output the backend servers will
produce. If debug_level is one, the postmaster will
trace all connection traffic, and nothing else. For
levels two and higher, debugging is turned on in the
backend process and the postmaster displays more
information, including the backend environment and
process traffic. Note that if no file is specified
for backend servers to send their debugging output
then this output will appear on the controlling tty
of their parent postmaster.
-i This enables TCP/IP or Internet domain socket commu-
nication. Without this option, only local Unix
domain socket communication is possible.
-n, -s
The -s and -n options control the behavior of the
postmaster when a backend dies abnormally. Neither
option is intended for use in ordinary operation.
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.
If the -s option is supplied, then the postmaster
will stop all other backend processes by sending the
signal SIGSTOP, but will not cause them to terminate.
This permits system programmers to collect core dumps
from all backend processes by hand.
If the -n option is supplied, then the postmaster
does not reinitialize shared data structures. A
knowledgable system programmer can then use the
shmemdoc program to examine shared memory and
semaphore state.
-o backend_options
The postgres(1) options specified in backend_options
are passed to all backend server processes started by
this postmaster. If the option string contains any
spaces, the entire string must be quoted.
-p port
Specifies the TCP/IP port or local Unix domain socket
file extension on which the postmaster is to listen
for connections from frontend applications. Defaults
to 5432, or the value of the PGPORT environment vari-
able (if set). If you specify a port other than the
default port then all frontend application users must
specify the same port (using command-line options or
PGPORT) when starting any libpq application, includ-
ing psql.
WARNINGS
If at all possible, do not use SIGKILL when killing the
postmaster. SIGHUP, SIGINT, or SIGTERM (the default sig-
nal for kill(1)) should be used instead. Hence, avoid
kill -KILL
or its alternative form
kill -9
as this will prevent the postmaster from freeing the sys-
tem resources (e.g., shared memory and semaphores) that it
holds before dying. This prevents you from having to deal
with the problem with shmat(2) described below.
EXAMPLES
# start postmaster using default values
nohup postmaster >logfile 2>&1 &
This command will start up postmaster on the default port
(5432) and will search $PATH to find an executable file
called "postgres". This is the simplest and most common
way to start the postmaster.
# start with specific port and executable name
nohup postmaster -p -b /usr/postgres/bin/postgres &
This command will start up a postmaster communicating
through the port 1234, and will attempt to use the backend
located at "/usr/postgres/bin/postgres". In order to con-
nect to this postmaster using psql, you would need to
either specify -p 1234 on the psql command-line or set the
environment variable PGPORT to 1234.
SEE ALSO
ipcs(1) ipcrm(1) ipcclean(1) psql(1) postgres(1)
DIAGNOSTICS
FindBackend: could not find a backend to execute...
If you see this message, you do not have the post-
gres executable in your path. Add the directoy in
which postgres resides to your path.
semget: No space left on device
If you see this message, you should run the ipc-
clean command. After doing this, try starting the
postmaster again. If this still doesn't work, you
probably need to configure your kernel for shared
memory and semaphores as described in the installa-
tion notes. If you run multiple postmasters on a
single host, or have reduced the shared memory and
semaphore parameters from the defaults in the
generic kernel, you may have to go back and
increase the shared memory and semaphores config-
ured into your kernel.
StreamServerPort: cannot bind to port
If you see this message, you should be certain that
there is no other postmaster process already run-
ning. The easiest way to determine this is by
using the command
ps -ax | grep postmaster
on BSD-based systems
ps -e | grep postmast
(the equivalent syntax is on System V-like or
POSIX-compliant systems such as HP-UX). If you are
sure that no other postmaster processes are running
and you still get this error, try specifying a dif-
ferent port using the -p option. You may also get
this error if you terminate the postmaster 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 ver-
sions of Unix consider port numbers under 1024 to
be "trusted" and only permit the Unix superuser to
access them.
IpcMemoryAttach: shmat() failed: Permission denied
A likely explanation is that another user attempted
to start a postmaster 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 postmaster, such con-
flicts are likely if there is more than one instal-
lation on a single host. If there are no other
postmaster processes currently running (see above),
run ipcclean and try again. If other postmasters
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.