postmaster.1
上传用户:blenddy
上传日期:2007-01-07
资源大小:6495k
文件大小:10k
- ." This is -*-nroff-*-
- ." XXX standard disclaimer belongs here....
- ." $Header: /usr/local/cvsroot/pgsql/src/man/Attic/postmaster.1,v 1.17 1999/05/22 17:47:48 tgl Exp $
- .TH POSTMASTER UNIX 05/19/99 PostgreSQL PostgreSQL
- .SH "NAME"
- postmaster - run the Postgres postmaster
- .SH "SYNOPSIS"
- .BR "postmaster"
- [c
- .BR "-B"
- n_buffers]
- [c
- .BR "-D"
- data_dir]
- [c
- .BR "-N"
- n_backends]
- .br
- .in +5n
- [c
- .BR "-S" c
- ]
- [c
- .BR "-a"
- system]
- [c
- .BR "-b"
- backend_pathname]
- [c
- .BR "-d"
- [debug_level]]
- [c
- .BR "-i" c
- ]
- [c
- .BR "-n" c
- ]
- [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 SysV 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.
- .PP
- .BR "Only one postmaster should be running at a time in a given
- Postgres installation."
- Here, an installation means a database directory and postmaster port number.
- You can run more than one postmaster on a machine only if each one has a
- separate directory and port number.
- .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 buffers, where each buffer is 8k bytes
- (or whatever BLCKSZ is set to in config.h).
- .TP
- .BR "-D" " data_dir"
- Specifies the directory to use as the root of the tree of database
- directories. If -D is not given, the default data directory name is
- the value of the environment variable
- .SM PGDATA.
- If
- .SM PGDATA
- is not set, then the directory used is
- .SM $POSTGRESHOMEc
- /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 "-N" " n_backends"
- .IR "n_backends"
- is the maximum number of backend server processes that this postmaster
- is allowed to start. In the stock configuration, this value defaults
- to 32, and can be set as high as 1024 if your system will support that
- many processes. Both the default and upper limit values can be altered
- when building Postgres (see src/include/config.h).
- .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"
- 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 .
- This option no longer has any effect! The pg_hba.conf configuration
- file now controls authentication.
- .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).
- This option is also obsolete, since the postmaster and backend are now
- a single executable --- the postmaster forks a backend but does not do
- an exec.
- .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 "-i"
- This enables TCP/IP or Internet domain socket communication.
- Without this option, only local Unix domain socket communication is
- possible.
- .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 operationfP.
- .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 TCP/IP port or local Unix domain socket file extension
- on which the
- .IR postmaster
- is to listen for connections from frontend applications. Defaults to
- the value of the
- .SM PGPORT
- environment variable, or if
- .SM PGPORT
- is not set, then the default value established when Postgres was
- compiled (normally 5432). 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 PGPORTc
- ) 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
- nohup postmaster >logfile 2>&1 &
- .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
- nohup postmaster -p 1234 -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 directory 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 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. (You may be able to postpone
- reconfiguring your kernel by reducing -B to reduce Postgres' shared memory
- consumption, or by reducing -N to reduce Postgres' semaphore consumption.)
- .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.