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