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