mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-10-06 21:16:49 +02:00
324 lines
8.9 KiB
Groff
324 lines
8.9 KiB
Groff
|
.\" This is -*-nroff-*-
|
||
|
.\" XXX standard disclaimer belongs here....
|
||
|
.\" $Header: /cvsroot/pgsql/doc/man/Attic/postmaster.1,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
|
||
|
.TH POSTMASTER UNIX 11/05/95 Postgres95 Postgres95
|
||
|
.SH "NAME"
|
||
|
postmaster \(em run the Postgres postmaster
|
||
|
.SH "SYNOPSIS"
|
||
|
.BR "postmaster"
|
||
|
[\c
|
||
|
.BR "-B"
|
||
|
n_buffers]
|
||
|
[\c
|
||
|
.BR "-D"
|
||
|
data_dir]
|
||
|
[\c
|
||
|
.BR "-S" \c
|
||
|
]
|
||
|
[\c
|
||
|
.BR "-a"
|
||
|
system]
|
||
|
.br
|
||
|
.in +5n
|
||
|
[\c
|
||
|
.BR "-b"
|
||
|
backend_pathname]
|
||
|
[\c
|
||
|
.BR "-d"
|
||
|
[debug_level]]
|
||
|
[\c
|
||
|
.BR "-n" \c
|
||
|
]
|
||
|
.br
|
||
|
[\c
|
||
|
.BR "-o"
|
||
|
backend_options]
|
||
|
[\c
|
||
|
.BR "-p"
|
||
|
port]
|
||
|
[\c
|
||
|
.BR "-s" \c
|
||
|
]
|
||
|
.in -5n
|
||
|
.SH "DESCRIPTION"
|
||
|
The
|
||
|
.IR "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
|
||
|
.IR postmaster
|
||
|
does not itself interact with the user and should be started as a
|
||
|
background process.
|
||
|
.BR "Only one postmaster should be run on a machine."
|
||
|
.PP
|
||
|
The
|
||
|
.IR "postmaster"
|
||
|
understands the following command-line options:
|
||
|
.TP 5n
|
||
|
.BR "-B" " n_buffers"
|
||
|
.IR "n_buffers"
|
||
|
is the number of shared-memory buffers for the
|
||
|
.IR "postmaster"
|
||
|
to allocate and manage for the backend server processes that it
|
||
|
starts. This value defaults to 64.
|
||
|
.TP
|
||
|
.BR "-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
|
||
|
.SM PGDATA.
|
||
|
If
|
||
|
.SM PGDATA
|
||
|
is not set, then the directory used is
|
||
|
.SM $POSTGRESHOME\c
|
||
|
/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.
|
||
|
.TP
|
||
|
.BR "-S"
|
||
|
Specifies that the
|
||
|
.IR "postmaster"
|
||
|
process should start up in silent mode. That is, it will disassociate
|
||
|
from the user's (controlling) tty and start its own process group.
|
||
|
This should not be used in combination with debugging options because
|
||
|
any messages printed to standard output and standard error are
|
||
|
discarded.
|
||
|
.TP
|
||
|
.BR "-a" " system"
|
||
|
Specifies whether or not to use the authentication system
|
||
|
.IR "system"
|
||
|
(see
|
||
|
.IR introduction (1))
|
||
|
for frontend applications to use in connecting to the
|
||
|
.IR postmaster
|
||
|
process. Specify
|
||
|
.IR "system"
|
||
|
to enable a system, or
|
||
|
.BI "no" "system"
|
||
|
to disable a system. For example, to permit users to use
|
||
|
.IR Kerberos
|
||
|
authentication, use
|
||
|
.BR "-a kerberos" ;
|
||
|
to deny any unauthenticated
|
||
|
connections, use
|
||
|
.BR "-a nounauth .
|
||
|
The default is site-specific.
|
||
|
.TP
|
||
|
.BR "-b" " backend_pathname"
|
||
|
.IR "backend_pathname"
|
||
|
is the full pathname of the Postgres backend server executable file that
|
||
|
the
|
||
|
.IR "postmaster"
|
||
|
will invoke when it receives a connection from a frontend application.
|
||
|
If this option is not used, then the
|
||
|
.IR 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
|
||
|
.IR "postmaster"
|
||
|
was invoked. If no pathname was specified, then the
|
||
|
.SM PATH
|
||
|
environment variable is searched for an executable named
|
||
|
\*(lqpostgres\*(rq).
|
||
|
.TP
|
||
|
.BR "-d" " [debug_level]"
|
||
|
The optional argument
|
||
|
.IR debug_level
|
||
|
determines the amount of debugging output the backend servers will
|
||
|
produce.
|
||
|
If
|
||
|
.I 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
|
||
|
.IR postmaster .
|
||
|
.TP
|
||
|
.BR "-n" ", " "-s"
|
||
|
The
|
||
|
.IR "-s" " and " "-n"
|
||
|
options control the behavior of the
|
||
|
.IR "postmaster"
|
||
|
when a backend dies abnormally. \fBNeither option is intended for use in
|
||
|
ordinary operation\fP.
|
||
|
.IP
|
||
|
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.
|
||
|
.IP
|
||
|
If the
|
||
|
.IR "-s"
|
||
|
option is supplied, then the
|
||
|
.IR "postmaster"
|
||
|
will stop all other backend processes by sending the signal
|
||
|
.SM SIGSTOP,
|
||
|
but will not cause them to terminate. This permits system programmers
|
||
|
to collect core dumps from all backend processes by hand.
|
||
|
.IP
|
||
|
If the
|
||
|
.IR "-n"
|
||
|
option is supplied, then the
|
||
|
.IR "postmaster"
|
||
|
does not reinitialize shared data structures. A knowledgable system
|
||
|
programmer can then use the
|
||
|
.IR shmemdoc
|
||
|
program to examine shared memory and semaphore state.
|
||
|
.TP
|
||
|
.BR "-o" " backend_options"
|
||
|
The
|
||
|
.IR postgres (1)
|
||
|
options specified in
|
||
|
.IR "backend_options"
|
||
|
are passed to all backend server processes started by this
|
||
|
.IR postmaster .
|
||
|
If the option string contains any spaces, the entire string must be
|
||
|
quoted.
|
||
|
.TP
|
||
|
.BR "-p" " port"
|
||
|
Specifies the Internet TCP port on which the
|
||
|
.IR postmaster
|
||
|
is to listen for connections from frontend applications. Defaults to
|
||
|
5432, or the value of the
|
||
|
.SM PGPORT
|
||
|
environment variable (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
|
||
|
.SM PGPORT\c
|
||
|
) when starting any libpq application, including psql.
|
||
|
.SH "WARNINGS"
|
||
|
If at all possible,
|
||
|
.BR "do not"
|
||
|
use
|
||
|
.SM SIGKILL
|
||
|
when killing the
|
||
|
.IR "postmaster" "."
|
||
|
.SM SIGHUP,
|
||
|
.SM SIGINT,
|
||
|
or
|
||
|
.SM SIGTERM
|
||
|
(the default signal for
|
||
|
.IR "kill" "(1))"
|
||
|
should be used instead. Hence, avoid
|
||
|
.nf
|
||
|
kill -KILL
|
||
|
.fi
|
||
|
or its alternative form
|
||
|
.nf
|
||
|
kill -9
|
||
|
.fi
|
||
|
as this will prevent the
|
||
|
.IR postmaster
|
||
|
from freeing the system resources (e.g., shared memory and semaphores)
|
||
|
that it holds before dying. This prevents you from having to deal with
|
||
|
the problem with
|
||
|
.IR shmat (2)
|
||
|
described below.
|
||
|
.SH "EXAMPLES"
|
||
|
.nf
|
||
|
# start postmaster using default values
|
||
|
postmaster -S
|
||
|
.fi
|
||
|
This command will start up
|
||
|
.IR "postmaster"
|
||
|
on the default port (5432) and will search
|
||
|
.SM $PATH
|
||
|
to find an executable file called \*(lqpostgres\*(rq. This is the
|
||
|
simplest and most common way to start the
|
||
|
.IR "postmaster" .
|
||
|
.nf
|
||
|
# start with specific port and executable name
|
||
|
postmaster -p -b /usr/postgres/bin/postgres &
|
||
|
.fi
|
||
|
This command will start up a
|
||
|
.IR "postmaster"
|
||
|
communicating through the port 1234, and will attempt to use the
|
||
|
backend located at \*(lq/usr/postgres/bin/postgres\*(rq. In order to
|
||
|
connect to this
|
||
|
.IR "postmaster"
|
||
|
using psql, you would need to either
|
||
|
specify
|
||
|
.BR "-p 1234"
|
||
|
on the
|
||
|
.IR "psql"
|
||
|
command-line or set the environment variable
|
||
|
.SM PGPORT
|
||
|
to 1234.
|
||
|
.SH "SEE ALSO"
|
||
|
ipcs(1),
|
||
|
ipcrm(1),
|
||
|
ipcclean(1),
|
||
|
psql(1),
|
||
|
postgres(1),
|
||
|
.SH "DIAGNOSTICS"
|
||
|
.TP
|
||
|
.BR "FindBackend: could not find a backend to execute..."
|
||
|
If you see this message, you do not have the
|
||
|
.IR "postgres"
|
||
|
executable in your path. Add the directoy in which postgres resides to
|
||
|
your path.
|
||
|
.TP
|
||
|
.BR "semget: No space left on device"
|
||
|
If you see this message, you should run the
|
||
|
.IR "ipcclean"
|
||
|
command. After doing this, try starting the
|
||
|
.IR "postmaster"
|
||
|
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
|
||
|
.IR postmaster s
|
||
|
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 configured
|
||
|
into your kernel.
|
||
|
.TP
|
||
|
.BR "StreamServerPort: cannot bind to port"
|
||
|
If you see this message, you should be certain that there is no other
|
||
|
.IR "postmaster"
|
||
|
process already running. The easiest way to determine this is by
|
||
|
using the command
|
||
|
.nf
|
||
|
ps -ax | grep postmaster
|
||
|
.fi
|
||
|
on BSD-based systems
|
||
|
.nf
|
||
|
ps -e | grep postmast
|
||
|
.fi
|
||
|
(the equivalent syntax is on System V-like or POSIX-compliant systems such as HP-UX). If you
|
||
|
are sure that no other
|
||
|
.IR "postmaster"
|
||
|
processes are running and you still get this error, try specifying a
|
||
|
different port using the
|
||
|
.BR "-p"
|
||
|
option. You may also get this error if you terminate the
|
||
|
.IR "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 versions of Unix consider port numbers under 1024 to
|
||
|
be \*(lqtrusted\*(rq and only permit the Unix superuser to access them.
|
||
|
.TP
|
||
|
.BR "IpcMemoryAttach: shmat() failed: Permission denied"
|
||
|
A likely explanation is that another user attempted to start a
|
||
|
.IR "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
|
||
|
.IR "postmaster" ,
|
||
|
such conflicts are likely if there is more than one installation on
|
||
|
a single host. If there are no other
|
||
|
.IR "postmaster"
|
||
|
processes currently running (see above), run
|
||
|
.IR "ipcclean"
|
||
|
and try again. If other
|
||
|
.IR "postmaster" s
|
||
|
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.
|