POSTMASTER(1)                                       POSTMASTER(1)

NAME
       postmaster - Run the Postgres multi-user backend

SYNOPSIS
       postmaster [ -B nBuffers ] [ -D DataDir ] [ -i ]
       postmaster [ -B nBuffers ] [ -D DataDir ] [ -N nBackends ] [ -S ]
          [ -d [ DebugLevel ] [ -i ] [ -o BackendOptions ] [ -p port ]
       postmaster [ -n | -s ] ...

   INPUTS
       postmaster accepts the following command line arguments:

       -B nBuffers
              The  number  of shared-memory buffers for the post-
              master 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).

       -D DataDir
              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 PGDATA.  If PGDATA is not set,
              then  the directory used is $POSTGRESHOME/data.  If
              neither environment variable is set and  this  com-
              mand-line  option  is  not  specified,  the default
              directory that was set at compile-time is used.

       -N nBackends
              The maximum number of backend server processes that
              this postmaster is allowed to start. In the default
              configuration, this value is usually set to 32, and
              can be set as high as 1024 if your system will sup-
              port that many  processes.  Both  the  default  and
              upper  limit  values  can  be altered when building
              Postgres (see src/include/config.h).

       -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
              process group.  This should not be used in combina-
              tion with debugging options  because  any  messages
              printed  to  standard output and standard error are
              discarded.

       -d [ DebugLevel ]
              The optional  argument  DebugLevel  determines  the
              amount of debugging output the backend servers will
              produce.  If DebugLevel 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 spec-
              ified for backend servers to send  their  debugging
              output then this output will appear on the control-
              ling tty of their parent postmaster.

       -i     This enables TCP/IP or Internet domain socket  com-
              munication.   Without  this option, only local Unix
              domain socket communication is possible.

       -o BackendOptions
              The postgres options  specified  in  BackendOptions
              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 the value  of  the  PGPORT  environment
              variable, or if PGPORT is not set, then defaults to
              the value established when  Postgres  was  compiled
              (normally  5432).  If you specify a port other than
              the default port  then  all  frontend  applications
              (including  psql)  must specify the same port using
              either command-line options or PGPORT.

       A few command line options are available for debugging  in
       the  case  when  a backend dies abnormally.  These options
       control the behavior of the postmaster in this  situation,
       and  neither option is intended for use in ordinary opera-
       tion.

       The ordinary strategy for this situation is to notify  all
       other  backends  that  they must terminate and then reini-
       tialize the shared memory and semaphores. This is  because
       an  errant  backend could have corrupted some shared state
       before terminating.

       These special-case options are:

       -n     postmaster will not reinitialize shared data struc-
              tures.  A  knowledgable  system programmer can then
              use the shmemdoc program to examine  shared  memory
              and semaphore state.

       -s     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.

   OUTPUTS
       semget: No space left on device
              If  you  see  this message, you should run the ipc-
              clean command. After doing this, try starting post-
              master again. If this still doesn't work, you prob-
              ably need to configure your kernel for shared  mem-
              ory and semaphores as described in the installation
              notes. If you run multiple instances of  postmaster
              on  a  single  host, or have a kernel with particu-
              larly small shared memory and/or semaphore  limits,
              you may have to reconfigure your kernel to increase
              its shared memory or semaphore parameters.

              Tip: You may be able to postpone reconfiguring your
              kernel  by decreasing -B to reduce Postgres' shared
              memory consumption, or by  reducing  -N  to  reduce
              Postgres' semaphore consumption.

       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, or

              % ps -e | grep postmast

              for 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 spec-
              ifying  a  different  port using the -p option. You
              may also get this error if you terminate the  post-
              master  and  immediately  restart it using the same
              port; in this case, you must simply wait a few sec-
              onds  until  the  operating  system closes the port
              before trying again.  Finally,  you  may  get  this
              error  if you specify a port number that your oper-
              ating system considers to be reserved.   For  exam-
              ple,  many  versions  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 postmaster
              images are running, you will have to find the  own-
              ers of those processes to coordinate the assignment
              of port numbers and/or  removal  of  unused  shared
              memory segments.

DESCRIPTION
       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).  postmaster  does  not  itself  interact
       with  the  user and should be started as a background pro-
       cess.

       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.

NOTES
       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. Using

       % kill -KILL

       or its alternative form

       % kill -9

       will prevent 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 shared memory described earlier.

       Useful  utilities  for dealing with shared memory problems
       include ipcs(1), ipcrm(1), and ipcclean(1).

USAGE
       To start postmaster using default values, type:

       % nohup postmaster >logfile 2>&1 &

       This command will start up postmaster on the default  port
       (5432).  This is the simplest and most common way to start
       the postmaster.

       To start postmaster with a specific  port  and  executable
       name:

       % nohup postmaster -p 1234 &

       This   command  will  start  up  postmaster  communicating
       through the port 1234. In order to connect to  this  post-
       master using psql, you would need to run it as

       % psql -p 1234

       or set the environment variable PGPORT:

       % setenv PGPORT 1234
       % psql

Application               15 August 1999                        1