diff options
Diffstat (limited to 'doc/man/postmaster.1')
| -rw-r--r-- | doc/man/postmaster.1 | 323 |
1 files changed, 323 insertions, 0 deletions
diff --git a/doc/man/postmaster.1 b/doc/man/postmaster.1 new file mode 100644 index 00000000000..3baf9c15b2f --- /dev/null +++ b/doc/man/postmaster.1 @@ -0,0 +1,323 @@ +.\" 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. |