~ubuntu-branches/ubuntu/trusty/postgresql-9.3/trusty-security : contents of doc/src/sgml/html/server-start.html at revision 21

~ubuntu-branches/ubuntu/trusty/postgresql-9.3/trusty-security : (revision 21)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Starting the Database Server</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.3.10 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Server Setup and Operation"
HREF="runtime.html"><LINK
REL="PREVIOUS"
TITLE="Creating a Database Cluster"
HREF="creating-cluster.html"><LINK
REL="NEXT"
TITLE="Managing Kernel Resources"
HREF="kernel-resources.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2015-10-05T19:31:56"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.3.10 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Creating a Database Cluster"
HREF="creating-cluster.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="runtime.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 17. Server Setup and Operation</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Managing Kernel Resources"
HREF="kernel-resources.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="SERVER-START"
>17.3. Starting the Database Server</A
></H1
><P
>   Before anyone can access the database, you must start the database
   server. The database server program is called
   <TT
CLASS="COMMAND"
>postgres</TT
>.
   The <TT
CLASS="COMMAND"
>postgres</TT
> program must know where to
   find the data it is supposed to use. This is done with the
   <TT
CLASS="OPTION"
>-D</TT
> option. Thus, the simplest way to start the
   server is:
</P><PRE
CLASS="SCREEN"
>$ <KBD
CLASS="USERINPUT"
>postgres -D /usr/local/pgsql/data</KBD
></PRE
><P>
   which will leave the server running in the foreground. This must be
   done while logged into the <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> user
   account. Without <TT
CLASS="OPTION"
>-D</TT
>, the server will try to use
   the data directory named by the environment variable <TT
CLASS="ENVAR"
>PGDATA</TT
>.
   If that variable is not provided either, it will fail.
  </P
><P
>   Normally it is better to start <TT
CLASS="COMMAND"
>postgres</TT
> in the
   background.  For this, use the usual Unix shell syntax:
</P><PRE
CLASS="SCREEN"
>$ <KBD
CLASS="USERINPUT"
>postgres -D /usr/local/pgsql/data &gt;logfile 2&gt;&amp;1 &amp;</KBD
></PRE
><P>
   It is important to store the server's <SPAN
CLASS="SYSTEMITEM"
>stdout</SPAN
> and
   <SPAN
CLASS="SYSTEMITEM"
>stderr</SPAN
> output somewhere, as shown above. It will help
   for auditing purposes and to diagnose problems. (See <A
HREF="logfile-maintenance.html"
>Section 23.3</A
> for a more thorough discussion of log
   file handling.)
  </P
><P
>   The <TT
CLASS="COMMAND"
>postgres</TT
> program also takes a number of other
   command-line options. For more information, see the
   <A
HREF="app-postgres.html"
><SPAN
CLASS="APPLICATION"
>postgres</SPAN
></A
> reference page
   and <A
HREF="runtime-config.html"
>Chapter 18</A
> below.
  </P
><P
>   This shell syntax can get tedious quickly.  Therefore the wrapper
   program
   <A
HREF="app-pg-ctl.html"
><SPAN
CLASS="APPLICATION"
>pg_ctl</SPAN
></A
>
   is provided to simplify some tasks.  For example:
</P><PRE
CLASS="PROGRAMLISTING"
>pg_ctl start -l logfile</PRE
><P>
   will start the server in the background and put the output into the
   named log file. The <TT
CLASS="OPTION"
>-D</TT
> option has the same meaning
   here as for <TT
CLASS="COMMAND"
>postgres</TT
>. <TT
CLASS="COMMAND"
>pg_ctl</TT
>
   is also capable of stopping the server.
  </P
><P
>   Normally, you will want to start the database server when the
   computer boots.
   Autostart scripts are operating-system-specific.
   There are a few distributed with
   <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> in the
   <TT
CLASS="FILENAME"
>contrib/start-scripts</TT
> directory. Installing one will require
   root privileges.
  </P
><P
>   Different systems have different conventions for starting up daemons
   at boot time. Many systems have a file
   <TT
CLASS="FILENAME"
>/etc/rc.local</TT
> or
   <TT
CLASS="FILENAME"
>/etc/rc.d/rc.local</TT
>. Others use <TT
CLASS="FILENAME"
>init.d</TT
> or
   <TT
CLASS="FILENAME"
>rc.d</TT
> directories. Whatever you do, the server must be
   run by the <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> user account
   <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>and not by root</I
></SPAN
> or any other user. Therefore you
   probably should form your commands using
   <TT
CLASS="LITERAL"
>su postgres -c '...'</TT
>.  For example:
</P><PRE
CLASS="PROGRAMLISTING"
>su postgres -c 'pg_ctl start -D /usr/local/pgsql/data -l serverlog'</PRE
><P>
  </P
><P
>   Here are a few more operating-system-specific suggestions. (In each
   case be sure to use the proper installation directory and user
   name where we show generic values.)

   <P
></P
></P><UL
><LI
><P
>      For <SPAN
CLASS="PRODUCTNAME"
>FreeBSD</SPAN
>, look at the file
      <TT
CLASS="FILENAME"
>contrib/start-scripts/freebsd</TT
> in the
      <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> source distribution.
      
     </P
></LI
><LI
><P
>      On <SPAN
CLASS="PRODUCTNAME"
>OpenBSD</SPAN
>, add the following lines
      to the file <TT
CLASS="FILENAME"
>/etc/rc.local</TT
>:
      
</P><PRE
CLASS="PROGRAMLISTING"
>if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then
    su -l postgres -c '/usr/local/pgsql/bin/pg_ctl start -s -l /var/postgresql/log -D /usr/local/pgsql/data'
    echo -n ' postgresql'
fi</PRE
><P>
     </P
></LI
><LI
><P
>      On <SPAN
CLASS="PRODUCTNAME"
>Linux</SPAN
> systems either add
      
</P><PRE
CLASS="PROGRAMLISTING"
>/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data</PRE
><P>
      to <TT
CLASS="FILENAME"
>/etc/rc.d/rc.local</TT
>
      or <TT
CLASS="FILENAME"
>/etc/rc.local</TT
> or look at the file
      <TT
CLASS="FILENAME"
>contrib/start-scripts/linux</TT
> in the
      <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> source distribution.
     </P
></LI
><LI
><P
>      On <SPAN
CLASS="PRODUCTNAME"
>NetBSD</SPAN
>, use either the
      <SPAN
CLASS="PRODUCTNAME"
>FreeBSD</SPAN
> or
      <SPAN
CLASS="PRODUCTNAME"
>Linux</SPAN
> start scripts, depending on
      preference.
      
     </P
></LI
><LI
><P
>      On <SPAN
CLASS="PRODUCTNAME"
>Solaris</SPAN
>, create a file called
      <TT
CLASS="FILENAME"
>/etc/init.d/postgresql</TT
> that contains
      the following line:
      
</P><PRE
CLASS="PROGRAMLISTING"
>su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data"</PRE
><P>
      Then, create a symbolic link to it in <TT
CLASS="FILENAME"
>/etc/rc3.d</TT
> as
      <TT
CLASS="FILENAME"
>S99postgresql</TT
>.
     </P
></LI
></UL
><P>

  </P
><P
>    While the server is running, its
    <ACRONYM
CLASS="ACRONYM"
>PID</ACRONYM
> is stored in the file
    <TT
CLASS="FILENAME"
>postmaster.pid</TT
> in the data directory. This is
    used to prevent multiple server instances from
    running in the same data directory and can also be used for
    shutting down the server.
   </P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="SERVER-START-FAILURES"
>17.3.1. Server Start-up Failures</A
></H2
><P
>     There are several common reasons the server might fail to
     start. Check the server's log file, or start it by hand (without
     redirecting standard output or standard error) and see what error
     messages appear. Below we explain some of the most common error
     messages in more detail.
    </P
><P
></P><PRE
CLASS="SCREEN"
>LOG:  could not bind IPv4 socket: Address already in use
HINT:  Is another postmaster already running on port 5432? If not, wait a few seconds and retry.
FATAL:  could not create TCP/IP listen socket</PRE
><P>
     This usually means just what it suggests: you tried to start
     another server on the same port where one is already running.
     However, if the kernel error message is not <SAMP
CLASS="COMPUTEROUTPUT"
>Address
     already in use</SAMP
> or some variant of that, there might
     be a different problem. For example, trying to start a server
     on a reserved port number might draw something like:
</P><PRE
CLASS="SCREEN"
>$ <KBD
CLASS="USERINPUT"
>postgres -p 666</KBD
>
LOG:  could not bind IPv4 socket: Permission denied
HINT:  Is another postmaster already running on port 666? If not, wait a few seconds and retry.
FATAL:  could not create TCP/IP listen socket</PRE
><P>
    </P
><P
>     A message like:
</P><PRE
CLASS="SCREEN"
>FATAL:  could not create shared memory segment: Invalid argument
DETAIL:  Failed system call was shmget(key=5440001, size=4011376640, 03600).</PRE
><P>
     probably means your kernel's limit on the size of shared memory is
     smaller than the work area <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>
     is trying to create (4011376640 bytes in this example). Or it could
     mean that you do not have System-V-style shared memory support
     configured into your kernel at all. As a temporary workaround, you
     can try starting the server with a smaller-than-normal number of
     buffers (<A
HREF="runtime-config-resource.html#GUC-SHARED-BUFFERS"
>shared_buffers</A
>). You will eventually want
     to reconfigure your kernel to increase the allowed shared memory
     size. You might also see this message when trying to start multiple
     servers on the same machine, if their total space requested
     exceeds the kernel limit.
    </P
><P
>     An error like:
</P><PRE
CLASS="SCREEN"
>FATAL:  could not create semaphores: No space left on device
DETAIL:  Failed system call was semget(5440126, 17, 03600).</PRE
><P>
     does <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> mean you've run out of disk
     space. It means your kernel's limit on the number of <SPAN
CLASS="SYSTEMITEM"
>System V</SPAN
> semaphores is smaller than the number
     <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> wants to create. As above,
     you might be able to work around the problem by starting the
     server with a reduced number of allowed connections
     (<A
HREF="runtime-config-connection.html#GUC-MAX-CONNECTIONS"
>max_connections</A
>), but you'll eventually want to
     increase the kernel limit.
    </P
><P
>     If you get an <SPAN
CLASS="QUOTE"
>"illegal system call"</SPAN
> error, it is likely that
     shared memory or semaphores are not supported in your kernel at
     all. In that case your only option is to reconfigure the kernel to
     enable these features.
    </P
><P
>     Details about configuring <SPAN
CLASS="SYSTEMITEM"
>System V</SPAN
>
     <ACRONYM
CLASS="ACRONYM"
>IPC</ACRONYM
> facilities are given in <A
HREF="kernel-resources.html#SYSVIPC"
>Section 17.4.1</A
>.
    </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="CLIENT-CONNECTION-PROBLEMS"
>17.3.2. Client Connection Problems</A
></H2
><P
>     Although the error conditions possible on the client side are quite
     varied and application-dependent, a few of them might be directly
     related to how the server was started. Conditions other than
     those shown below should be documented with the respective client
     application.
    </P
><P
></P><PRE
CLASS="SCREEN"
>psql: could not connect to server: Connection refused
        Is the server running on host "server.joe.com" and accepting
        TCP/IP connections on port 5432?</PRE
><P>
     This is the generic <SPAN
CLASS="QUOTE"
>"I couldn't find a server to talk
     to"</SPAN
> failure. It looks like the above when TCP/IP
     communication is attempted. A common mistake is to forget to
     configure the server to allow TCP/IP connections.
    </P
><P
>     Alternatively, you'll get this when attempting Unix-domain socket
     communication to a local server:
</P><PRE
CLASS="SCREEN"
>psql: could not connect to server: No such file or directory
        Is the server running locally and accepting
        connections on Unix domain socket "/tmp/.s.PGSQL.5432"?</PRE
><P>
    </P
><P
>     The last line is useful in verifying that the client is trying to
     connect to the right place. If there is in fact no server
     running there, the kernel error message will typically be either
     <SAMP
CLASS="COMPUTEROUTPUT"
>Connection refused</SAMP
> or
     <SAMP
CLASS="COMPUTEROUTPUT"
>No such file or directory</SAMP
>, as
     illustrated. (It is important to realize that
     <SAMP
CLASS="COMPUTEROUTPUT"
>Connection refused</SAMP
> in this context
     does <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> mean that the server got your
     connection request and rejected it. That case will produce a
     different message, as shown in <A
HREF="client-authentication-problems.html"
>Section 19.4</A
>.) Other error messages
     such as <SAMP
CLASS="COMPUTEROUTPUT"
>Connection timed out</SAMP
> might
     indicate more fundamental problems, like lack of network
     connectivity.
    </P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="creating-cluster.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="kernel-resources.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Creating a Database Cluster</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="runtime.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Managing Kernel Resources</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>