postmaster.sgml 19 KB
Newer Older
1
<!--
2
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.33 2002/10/11 23:03:48 petere Exp $
3
PostgreSQL documentation
4 5
-->

6
<refentry id="app-postmaster">
7
 <refmeta>
8 9
  <refentrytitle id="APP-POSTMASTER-TITLE"><application>postmaster</application></refentrytitle>
  <manvolnum>1</manvolnum>
10 11
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>
12

13
 <refnamediv>
14
  <refname id="postmaster-ref">postmaster</refname>
15
  <refpurpose><productname>PostgreSQL</productname> multiuser database server</refpurpose>
16
 </refnamediv>
17

18
 <refsynopsisdiv>
19 20 21 22 23 24 25 26 27 28
  <cmdsynopsis>
   <command>postmaster</command>
   <arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
   <arg>-B <replaceable>nbuffers</replaceable></arg>
   <arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
   <arg>-d <replaceable>debug-level</replaceable></arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-F</arg>
   <arg>-h <replaceable>hostname</replaceable></arg>
   <arg>-i</arg>
29
   <arg>-k <replaceable>directory</replaceable></arg>
30 31 32 33 34
   <arg>-l</arg>
   <arg>-N <replaceable>max-connections</replaceable></arg>
   <arg>-o <replaceable>extra-options</replaceable></arg>
   <arg>-p <replaceable>port</replaceable></arg>
   <arg>-S</arg>
35
   <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
36 37 38 39 40 41 42 43 44
   <group><arg>-n</arg><arg>-s</arg></group>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <application>postmaster</application> is the
45
   <productname>PostgreSQL</productname> multiuser database server.
46 47 48 49
   In order for a client application to access a database it connects
   (over a network or locally) to a running
   <application>postmaster</application>.  The
   <application>postmaster</application> then starts a separate server
50 51 52
   process (<quote><xref linkend="app-postgres"></quote>) to handle
   the connection.  The <application>postmaster</application> also
   manages the communication among server processes.
53 54 55
  </para>

  <para>
56 57 58 59
   By default the <application>postmaster</application> starts in the
   foreground and prints log messages to the standard output.  In
   practical applications the <application>postmaster</application>
   should be started as a background process, perhaps at boot time.
60 61 62
  </para>

  <para>
63 64 65 66 67 68 69 70 71 72 73
   One <application>postmaster</application> always manages the data
   from exactly one database cluster.  A database cluster is a
   collection of databases that is stored at a common file system
   location.  When the postmaster starts it needs to know the location
   of the database cluster files (<quote>data area</quote>).  This is
   done with the <option>-D</option> invocation option or the
   <envar>PGDATA</envar> environment variable; there is no default.
   More than one postmaster process can run on a system at one time,
   as long as they use different data areas and different
   communication ports (see below).  A data area is created with <xref
   linkend="app-initdb">.
74
  </para>
75 76 77 78
 </refsect1>

 <refsect1 id="app-postmaster-options">
  <title>Options</title>
79

80
   <para>
81 82 83 84 85
    <application>postmaster</application> accepts the following
    command line arguments.  For a detailed discussion of the options
    consult the <citetitle>Administrator's Guide</citetitle>.  You can
    also save typing most of these options by setting up a
    configuration file.
86 87 88
    
    <variablelist>
     <varlistentry>
89
      <term>-A 0|1</term>
90 91
      <listitem>
       <para>
92 93 94
        Enables run-time assert checks, which is a debugging aid to
        detect programming mistakes.  This is only available if it was
        enabled during compilation.  If so, the default is on.
95 96 97 98 99
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
100
      <term>-B <replaceable class="parameter">nbuffers</replaceable></term>
101 102
      <listitem>
       <para>
103 104 105
	Sets the number of shared buffers for use by the server
	processes.  This value defaults to 64 buffers, where each
	buffer is 8 kB.
106 107 108 109 110
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
111
      <term>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></term>
112 113
      <listitem>
       <para>
114 115 116
        Sets a named run-time parameter. Consult the
        <citetitle>Administrator's Guide</citetitle> for a list and
        descriptions.  Most of the other command line options are in
117 118
        fact short forms of such a parameter assignment.  <option>-c</>
	can appear multiple times to set multiple parameters.
119 120 121 122 123
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
124
      <term>-d <replaceable>debug-level</replaceable></term>
125 126
      <listitem>
       <para>
127
        Sets the debug level.  The higher this value is set, the more
128 129
        debugging output is written to the server log.  Values are from
	1 to 5.
130 131 132 133 134
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
135
      <term>-D <replaceable class="parameter">datadir</replaceable></term>
136 137
      <listitem>
       <para>
138 139
	Specifies the file system location of the data directory.  See
	discussion above.
140 141 142 143
       </para>
      </listitem>
     </varlistentry>

144
     <varlistentry>
145
      <term>-F</term>
146 147
      <listitem>
       <para>
148
        Disables <function>fsync</function> calls for performance
149
        improvement, at the risk of data corruption in event of a
150
        system crash.  This parameter corresponds to setting
151
        <literal>fsync=false</> in <filename>postgresql.conf</>. Read the detailed
152 153 154 155 156
        documentation before using this!
       </para>
       <para>
        <option>--fsync=true</option> has the opposite effect
        of this option.
157
       </para>
158 159 160 161 162 163
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-h <replaceable class="parameter">hostname</replaceable></term>
      <listitem>
164
       <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
165
	Specifies the TCP/IP host name or address on which the
166
	<application>postmaster</application> is to listen for
167
	connections from client applications.  Defaults to
Peter Eisentraut's avatar
Peter Eisentraut committed
168 169
	listening on all configured addresses (including
        <systemitem class="systemname">localhost</systemitem>).
170 171 172 173
       </para>
      </listitem>
     </varlistentry>

174
     <varlistentry>
175
      <term>-i</term>
176 177
      <listitem>
       <para>
178 179
        Allows clients to connect via TCP/IP (Internet domain)
	connections.  Without this option, only local Unix domain
180
        socket connections are accepted. This option corresponds
181
        to setting <literal>tcpip_socket=true</> in <filename>postgresql.conf</>.
182 183 184 185
       </para>
       <para>
        <option>--tcpip_socket=false</option> has the opposite
        effect of this option.
186 187 188 189
       </para>
      </listitem>
     </varlistentry>

190
     <varlistentry>
191
      <term>-k <replaceable class="parameter">directory</replaceable></term>
192 193
      <listitem>
       <para>
194
	Specifies the directory of the Unix-domain socket on which the
195
	<application>postmaster</application> is to listen for
196 197
	connections from client applications.  The default is normally
	<filename>/tmp</filename>, but can be changed at build time.
198
       </para>
199 200 201 202 203 204
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-l</term>
      <listitem>
205
       <para>
206 207 208
	Enables secure connections using SSL.  The <option>-i</option>
	option is also required.  You must have compiled with SSL
	enabled to use this option.
209 210 211 212
       </para>
      </listitem>
     </varlistentry>

213
     <varlistentry>
214
      <term>-N <replaceable class="parameter">max-connections</replaceable></term>
215 216
      <listitem>
       <para>
217
	Sets the maximum number of client connections that this
218
	<application>postmaster</application> will accept.  By
219 220
	default, this value is 32, but it can be set as high as your
	system will support.  (Note that
221
	<option>-B</option> is required to be at least twice
222 223 224
	<option>-N</option>.  See the <citetitle>Administrator's
	Guide</citetitle> for a discussion of system resource requirements
	for large numbers of client connections.)
225 226 227 228
       </para>
      </listitem>
     </varlistentry>

229
     <varlistentry>
230
      <term>-o <replaceable class="parameter">extra-options</replaceable></term>
231 232
      <listitem>
       <para>
233
	The command line-style options specified in <replaceable
234
	class="parameter">extra-options</replaceable> are passed to
235 236
	all backend server processes started by this
	<application>postmaster</application>.  See <xref
237 238
	linkend="app-postgres"> for possibilities.  If the option
	string contains any spaces, the entire string must be quoted.
239 240 241 242 243
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
244
      <term>-p <replaceable class="parameter">port</replaceable></term>
245 246
      <listitem>
       <para>
247 248 249 250 251 252 253 254 255
	Specifies the TCP/IP port or local Unix domain socket file
	extension on which the <application>postmaster</application>
	is to listen for connections from client applications.
	Defaults to the value of the <envar>PGPORT</envar> environment
	variable, or if <envar>PGPORT</envar> is not set, then
	defaults to the value established during compilation (normally
	5432).  If you specify a port other than the default port,
	then all client applications must specify the same port using
	either command-line options or <envar>PGPORT</envar>.
256 257 258
       </para>
      </listitem>
     </varlistentry>
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273

     <varlistentry>
      <term>-S</term>
      <listitem>
       <para>
	Specifies that the <application>postmaster</application>
	process should start up in silent mode.  That is, it will
	disassociate from the user's (controlling) terminal, start its
	own process group, and redirect its standard output and
	standard error to <filename>/dev/null</filename>.
       </para>
       <para>
        Using this switch discards all logging output, which is
	probably not what you want, since it makes it very difficult
	to troubleshoot problems.  See below for a better way to start
274
	the <application>postmaster</application> in the background.
275
       </para>
276 277 278 279
       <para>
        <option>--silent_mode=false</option> has the opposite effect
        of this option.
       </para>
280 281 282
      </listitem>
     </varlistentry>

283 284 285 286
     <varlistentry>
      <term>--<replaceable>name</replaceable>=<replaceable>value</replaceable></term>
      <listitem>
       <para>
287 288 289
        Sets a named run-time parameter; a shorter form of
        <option>-c</>.
       </para>
290 291 292
      </listitem>
     </varlistentry>

293 294 295 296
    </variablelist>
   </para>

   <para>
297 298 299 300 301
    Two additional command line options are available for debugging
    problems that cause a backend to die abnormally.  These options
    control the behavior of the <application>postmaster</application>
    in this situation, and <emphasis>neither option is intended for
    use in ordinary operation</emphasis>.
302 303 304 305 306
   </para>

   <para>
    The ordinary strategy for this situation is to notify all other
    backends that they must terminate and then reinitialize the shared
307 308
    memory and semaphores.  This is because an errant backend could
    have corrupted some shared state before terminating.
309 310 311 312 313 314 315
   </para>

   <para>
    These special-case options are:

    <variablelist>
     <varlistentry>
316
      <term>-n</term>
317 318 319
      <listitem>
       <para>
	<application>postmaster</application>
320 321 322
	will not reinitialize shared data structures.  A knowledgeable system
	programmer can then use a debugger
	to examine shared memory and semaphore state.
323 324 325 326 327
       </para>
     </listitem>
    </varlistentry>

    <varlistentry>
328
      <term>-s</term>
329 330 331 332 333 334 335 336 337 338 339 340 341
      <listitem>
       <para>
	<application>postmaster</application>
	will stop all other backend processes by sending the signal
	<literal>SIGSTOP</literal>,
	but will not cause them to terminate.  This permits system programmers
	to collect core dumps from all backend processes by hand.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

342 343 344 345 346 347 348 349 350 351 352 353
 </refsect1>

 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGCLIENTENCODING</envar></term>

    <listitem>
     <para>
      Default character encoding used by clients.  (The clients may
354
      override this individually.)  This value can also be set in the
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385
      configuration file.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PGDATA</envar></term>

    <listitem>
     <para>
      Default data direction location
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PGDATASTYLE</envar></term>

    <listitem>
     <para>
      Default value of the <literal>datestyle</literal> run-time
      parameter.  (The use of this environment variable is deprecated.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PGPORT</envar></term>

    <listitem>
     <para>
386
      Default port (preferably set in the configuration file)
387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>TZ</envar></term>

    <listitem>
     <para>
      Server time zone
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>others</term>

    <listitem>
     <para>
      Other environment variables may be used to designate alternative
      data storage locations.  See the <citetitle>Administrator's
      Guide</citetitle> for more information.
     </para>
    </listitem>
   </varlistentry>

  </variablelist>
 </refsect1>

 <refsect1>
   <title>Diagnostics</title>
418 419 420 421
   <para>

    <variablelist>
     <varlistentry>
422 423 424
      <term><computeroutput>
semget: No space left on device
       </computeroutput></term>
425 426 427 428
      <listitem>
       <para>
	If you see this message, you should run the
	<application>ipcclean</application>
429
	command.  After doing so, try starting
430 431 432 433 434 435 436 437 438 439 440 441
	<application>postmaster</application>
	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 instances of
	<application>postmaster</application>
	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.

	<tip>
	 <para>
	  You may be able to postpone
Peter Eisentraut's avatar
Peter Eisentraut committed
442 443 444
	  reconfiguring your kernel by decreasing <option>-B</option> to reduce
	  the shared memory consumption of <productname>PostgreSQL</>,
	  and/or by reducing <option>-N</option> to reduce the semaphore
445 446 447 448 449 450 451 452
	  consumption.
	 </para>
	</tip>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
453 454 455
      <term><computeroutput>
StreamServerPort: cannot bind to port
       </computeroutput></term>
456 457
      <listitem>
       <para>
458 459 460 461
	If you see this message, you should make certain that there is no
	other <application>postmaster</application>
	process already running on the same port number.  The easiest way to
	determine this is by using the command
462 463 464 465 466 467 468 469
<screen>
<prompt>$</prompt> <userinput>ps ax | grep postmaster</userinput>
</screen>
        or
<screen>
<prompt>$</prompt> <userinput>ps -e | grep postmaster</userinput>
</screen>
	depending on your system.
470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492
       </para>

       <para>
	If you 
	are sure that no other
	<application>postmaster</application>
	processes are running and you still get this error, try specifying a
	different port using the
	<literal>-p</literal>
	option.  You may also get this error if you terminate the
	<application>postmaster</application>
	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 <firstterm>trusted</firstterm>
	and only permit the Unix superuser to access them.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
493
 </refsect1>
494

495 496 497
 <refsect1>
  <title>Notes</title>
  
498
  <para>
499 500 501 502 503 504
   If at all possible, <emphasis>do not</emphasis> use
   <literal>SIGKILL</literal> to kill the
   <application>postmaster</application>.  This will prevent
   <application>postmaster</application> from freeing the system
   resources (e.g., shared memory and semaphores) that it holds before
   terminating.
505 506 507
  </para>

  <para>
508 509 510
   To terminate the <application>postmaster</application> normally,
   the signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>,
   or <literal>SIGQUIT</literal> can be used.  The first will wait for
511 512
   all clients to terminate before quitting, the second will
   forcefully disconnect all clients, and the third will quit
513
   immediately without proper shutdown, resulting in a recovery run
514
   during restart.
515 516 517
  </para>

  <para>
518
   The utility command <xref linkend="app-pg-ctl"> can be used to
519 520
   start and shut down the <application>postmaster</application>
   safely and comfortably.
521
  </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
522 523

  <para>
524 525
   The <option>--</> options will not work on <systemitem
   class="osname">FreeBSD</> or <systemitem class="osname">OpenBSD</>.
Peter Eisentraut's avatar
Peter Eisentraut committed
526
   Use <option>-c</> instead. This is a bug in the affected operating
527 528
   systems; a future release of <productname>PostgreSQL</productname>
   will provide a workaround if this is not fixed.
Peter Eisentraut's avatar
Peter Eisentraut committed
529 530
  </para>

531 532
 </refsect1>

533 534
 <refsect1 id="app-postmaster-examples">
  <title>Examples</title>
535 536 537
  <para>
   To start <application>postmaster</application> in the background
   using default values, type:
538

539 540 541
<screen>
<prompt>$</prompt> <userinput>nohup postmaster &gt;logfile 2&gt;&amp;1 &lt;/dev/null &amp;</userinput>
</screen>
542 543 544
  </para>

  <para>
545 546 547 548 549
   To start <application>postmaster</application> with a specific
   port:
<screen>
<prompt>$</prompt> <userinput>postmaster -p 1234</userinput>
</screen>
550
   This command will start up <application>postmaster</application>
551
   communicating through the port 1234. In order to connect to this
552
   <application>postmaster</application> using <application>psql</>, you would need to
553 554 555 556
   run it as
<screen>
<prompt>$</prompt> <userinput>psql -p 1234</userinput>
</screen>
557
   or set the environment variable <envar>PGPORT</envar>:
558 559 560 561
<screen>
<prompt>$</prompt> <userinput>export PGPORT=1234</userinput>
<prompt>$</prompt> <userinput>psql</userinput>
</screen>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
562
  </para>
563 564

  <para>
565
   Named run-time parameters can be set in either of these styles:
566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582
<screen>
<prompt>$</prompt> <userinput>postmaster -c sort_mem=1234</userinput>
<prompt>$</prompt> <userinput>postmaster --sort-mem=1234</userinput>
</screen>
   Either form overrides whatever setting might exist for <literal>sort_mem</>
   in <filename>postgresql.conf</>.  Notice that underscores in parameter
   names can be written as either underscore or dash on the command line.
  </para>

  <tip>
  <para>
   Except for short-term experiments,
   it's probably better practice to edit the setting in
   <filename>postgresql.conf</> than to rely on a command-line switch
   to set a parameter.
  </para>
  </tip>
583
 </refsect1>
584 585 586 587 588 589 590 591 592

 <refsect1>
  <title>See Also</title>

  <para>
   <xref linkend="app-initdb">,
   <xref linkend="app-pg-ctl">
  </para>
 </refsect1>
593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->