granicus.if.org Git - postgresql/blob - src/man/postmaster.1

   1 .\" This is -*-nroff-*-
   2 .\" XXX standard disclaimer belongs here....
   3 .\" $Header: /cvsroot/pgsql/src/man/Attic/postmaster.1,v 1.14 1999/02/21 03:17:31 tgl Exp $
   4 .TH POSTMASTER UNIX 02/20/99 PostgreSQL PostgreSQL
   5 .SH "NAME"
   6 postmaster - run the Postgres postmaster
   7 .SH "SYNOPSIS"
   8 .BR "postmaster"
   9 [\c
  10 .BR "-B"
  11 n_buffers]
  12 [\c
  13 .BR "-D"
  14 data_dir]
  15 [\c
  16 .BR "-S" \c
  17 ]
  18 [\c
  19 .BR "-a"
  20 system]
  21 [\c
  22 .BR "-N"
  23 n_backends]
  24 .br
  25 .in +5n
  26 [\c
  27 .BR "-b"
  28 backend_pathname]
  29 [\c
  30 .BR "-d"
  31 [debug_level]]
  32 [\c
  33 .BR "-i" \c
  34 ]
  35 [\c
  36 .BR "-n" \c
  37 ]
  38 .br
  39 [\c
  40 .BR "-o"
  41 backend_options]
  42 [\c
  43 .BR "-p"
  44 port]
  45 [\c
  46 .BR "-s" \c
  47 ]
  48 .in -5n
  49 .SH "DESCRIPTION"
  50 The
  51 .IR "postmaster"
  52 manages the communication between frontend and backend processes, as
  53 well as allocating the shared buffer pool and semaphores (on machines
  54 without a test-and-set instruction).  The
  55 .IR postmaster
  56 does not itself interact with the user and should be started as a
  57 background process.
  58 .BR "Only one postmaster should be run on a machine."
  59 .PP
  60 The
  61 .IR "postmaster"
  62 understands the following command-line options:
  63 .TP 5n
  64 .BR "-B" " n_buffers"
  65 .IR "n_buffers"
  66 is the number of shared-memory buffers for the
  67 .IR "postmaster"
  68 to allocate and manage for the backend server processes that it
  69 starts.  This value defaults to 64, and each buffer is 8k bytes.
  70 .TP
  71 .BR "-D" " data_dir"
  72 Specifies the directory to use as the root of the tree of database
  73 directories.  This directory uses the value of the environment
  74 variable
  75 .SM PGDATA.
  76 If
  77 .SM PGDATA
  78 is not set, then the directory used is
  79 .SM $POSTGRESHOME\c
  80 /data.  If neither environment variable is set and this command-line
  81 option is not specified, the default directory that was
  82 set at compile-time is used.
  83 .TP
  84 .BR "-S"
  85 Specifies that the
  86 .IR "postmaster"
  87 process should start up in silent mode.  That is, it will disassociate
  88 from the user's (controlling) tty and start its own process group.
  89 This should not be used in combination with debugging options because
  90 any messages printed to standard output and standard error are
  91 discarded.
  92 .TP
  93 .BR "-a" " system"
  94 Specifies whether or not to use the authentication system
  95 .IR "system"
  96 for frontend applications to use in connecting to the
  97 .IR postmaster
  98 process.  Specify
  99 .IR "system"
 100 to enable a system, or
 101 .BI "no" "system"
 102 to disable a system.  For example, to permit users to use
 103 .IR Kerberos
 104 authentication, use
 105 .BR "-a kerberos" ;
 106 to deny any unauthenticated
 107 connections, use
 108 .BR "-a nounauth .
 109 This option no longer has any effect.
 110 .TP
 111 .BR "-N" " n_backends"
 112 .IR "n_backends"
 113 is the maximum number of backend server processes that this postmaster
 114 is allowed to start.  In the stock configuration, this value defaults
 115 to 64, and can be set as high as 1024 if your system will support that
 116 many processes. Both the default and upper limit values can be altered
 117 when building Postgres.
 118 .TP
 119 .BR "-b" " backend_pathname"
 120 .IR "backend_pathname"
 121 is the full pathname of the Postgres backend server executable file that
 122 the
 123 .IR "postmaster"
 124 will invoke when it receives a connection from a frontend application.
 125 If this option is not used, then the
 126 .IR postmaster
 127 tries to find this executable file in the directory in which its own
 128 executable is located (this is done by looking at the pathname under
 129 which the
 130 .IR "postmaster"
 131 was invoked.  If no pathname was specified, then the
 132 .SM PATH
 133 environment variable is searched for an executable named
 134 \*(lqpostgres\*(rq).
 135 .TP
 136 .BR "-d" " [debug_level]"
 137 The optional argument
 138 .IR debug_level
 139 determines the amount of debugging output the backend servers will
 140 produce.
 141 If
 142 .I debug_level
 143 is one, the postmaster will trace all connection traffic,
 144 and nothing else.
 145 For levels two and higher,
 146 debugging is turned on in the backend process and the postmaster
 147 displays more information,
 148 including the backend environment and process traffic.
 149 Note that if no file is specified for backend servers to
 150 send their debugging output then this output will appear on the
 151 controlling tty of their parent
 152 .IR postmaster .
 153 .TP
 154 .BR "-i"
 155 This enables TCP/IP or Internet domain socket communication.
 156 Without this option, only local Unix domain socket communication is
 157 possible.
 158 .TP
 159 .BR "-n" ", " "-s"
 160 The
 161 .IR "-s" " and " "-n"
 162 options control the behavior of the
 163 .IR "postmaster"
 164 when a backend dies abnormally.  \fBNeither option is intended for use in
 165 ordinary operation\fP.
 166 .IP
 167 The ordinary strategy for this situation is to notify all other
 168 backends that they must terminate and then reinitialize the shared
 169 memory and semaphores.  This is because an errant backend could have
 170 corrupted some shared state before terminating.
 171 .IP
 172 If the
 173 .IR "-s"
 174 option is supplied, then the
 175 .IR "postmaster"
 176 will stop all other backend processes by sending the signal
 177 .SM SIGSTOP,
 178 but will not cause them to terminate.  This permits system programmers
 179 to collect core dumps from all backend processes by hand.
 180 .IP
 181 If the
 182 .IR "-n"
 183 option is supplied, then the
 184 .IR "postmaster"
 185 does not reinitialize shared data structures.  A knowledgable system
 186 programmer can then use the
 187 .IR shmemdoc
 188 program to examine shared memory and semaphore state.
 189 .TP
 190 .BR "-o" " backend_options"
 191 The
 192 .IR postgres(1)
 193 options specified in
 194 .IR "backend_options"
 195 are passed to all backend server processes started by this
 196 .IR postmaster .
 197 If the option string contains any spaces, the entire string must be
 198 quoted.
 199 .TP
 200 .BR "-p" " port"
 201 Specifies the TCP/IP port or local Unix domain socket file extension
 202 on which the
 203 .IR postmaster
 204 is to listen for connections from frontend applications.  Defaults to
 205 5432, or the value of the
 206 .SM PGPORT
 207 environment variable (if set).  If you specify a port other than the
 208 default port then all frontend application users must specify the same
 209 port (using command-line options or
 210 .SM PGPORT\c
 211 ) when starting any libpq application, including psql.
 212 .SH "WARNINGS"
 213 If at all possible,
 214 .BR "do not"
 215 use
 216 .SM SIGKILL
 217 when killing the
 218 .IR "postmaster" "."
 219 .SM SIGHUP,
 220 .SM SIGINT,
 221 or
 222 .SM SIGTERM
 223 (the default signal for
 224 .IR "kill" "(1))"
 225 should be used instead.  Hence, avoid
 226 .nf
 227 kill -KILL
 228 .fi
 229 or its alternative form
 230 .nf
 231 kill -9
 232 .fi
 233 as this will prevent the
 234 .IR postmaster
 235 from freeing the system resources (e.g., shared memory and semaphores)
 236 that it holds before dying.  This prevents you from having to deal with
 237 the problem with
 238 .IR shmat(2)
 239 described below.
 240 .SH "EXAMPLES"
 241 .nf
 242
 243 # start postmaster using default values
 244 nohup postmaster >logfile 2>&1 &
 245
 246 .fi
 247 This command will start up
 248 .IR "postmaster"
 249 on the default port (5432) and will search
 250 .SM $PATH
 251 to find an executable file called \*(lqpostgres\*(rq.  This is the
 252 simplest and most common way to start the
 253 .IR "postmaster" .
 254 .nf
 255
 256 # start with specific port and executable name
 257 nohup postmaster -p -b /usr/postgres/bin/postgres &
 258
 259 .fi
 260 This command will start up a
 261 .IR "postmaster"
 262 communicating through the port 1234, and will attempt to use the
 263 backend located at \*(lq/usr/postgres/bin/postgres\*(rq.  In order to
 264 connect to this
 265 .IR "postmaster"
 266 using psql, you would need to either
 267 specify
 268 .BR "-p 1234"
 269 on the
 270 .IR "psql"
 271 command-line or set the environment variable
 272 .SM PGPORT
 273 to 1234.
 274 .SH "SEE ALSO"
 275 ipcs(1),
 276 ipcrm(1),
 277 ipcclean(1),
 278 psql(1),
 279 postgres(1),
 280 .SH "DIAGNOSTICS"
 281 .TP
 282 .BR "FindBackend: could not find a backend to execute..."
 283 If you see this message, you do not have the
 284 .IR "postgres"
 285 executable in your path.  Add the directoy in which postgres resides to
 286 your path.
 287 .TP
 288 .BR "semget: No space left on device"
 289 If you see this message, you should run the
 290 .IR "ipcclean"
 291 command.  After doing this, try starting the
 292 .IR "postmaster"
 293 again.  If this still doesn't work, you probably need to configure
 294 your kernel for shared memory and semaphores as described in the
 295 installation notes.  If you run multiple
 296 .IR postmaster s
 297 on a single host, or have reduced the shared memory and semaphore
 298 parameters from the defaults in the generic kernel, you may have to
 299 go back and increase the shared memory and semaphores configured
 300 into your kernel.
 301 .TP
 302 .BR "StreamServerPort: cannot bind to port"
 303 If you see this message, you should be certain that there is no other
 304 .IR "postmaster"
 305 process already running.  The easiest way to determine this is by
 306 using the command
 307 .nf
 308 ps -ax | grep postmaster
 309 .fi
 310 on BSD-based systems
 311 .nf
 312 ps -e | grep postmast
 313 .fi
 314 (the equivalent syntax is on System V-like or POSIX-compliant systems such as HP-UX).  If you
 315 are sure that no other
 316 .IR "postmaster"
 317 processes are running and you still get this error, try specifying a
 318 different port using the
 319 .BR "-p"
 320 option.  You may also get this error if you terminate the
 321 .IR "postmaster"
 322 and immediately restart it using the same port; in this case, you must
 323 simply wait a few seconds until the operating system closes the port
 324 before trying again.  Finally, you may get this error if you specify
 325 a port number that your operating system considers to be reserved.
 326 For example, many versions of Unix consider port numbers under 1024 to
 327 be \*(lqtrusted\*(rq and only permit the Unix superuser to access them.
 328 .TP
 329 .BR "IpcMemoryAttach: shmat() failed: Permission denied"
 330 A likely explanation is that another user attempted to start a
 331 .IR "postmaster"
 332 process on the same port which acquired shared resources and then
 333 died.  Since Postgres shared memory keys are based on the port number
 334 assigned to the
 335 .IR "postmaster" ,
 336 such conflicts are likely if there is more than one installation on
 337 a single host.  If there are no other
 338 .IR "postmaster"
 339 processes currently running (see above), run
 340 .IR "ipcclean"
 341 and try again.  If other
 342 .IR "postmaster" s
 343 are running, you will have to find the owners of those processes to
 344 coordinate the assignment of port numbers and/or removal of unused
 345 shared memory segments.