config.sgml

<!-- doc/src/sgml/config.sgml -->

<chapter id="runtime-config">
  <title>Server Configuration</title>

  <indexterm>
   <primary>configuration</primary>
   <secondary>of the server</secondary>
  </indexterm>

  <para>
   There are many configuration parameters that affect the behavior of
   the database system. In the first section of this chapter, we
   describe how to set configuration parameters. The subsequent sections
   discuss each parameter in detail.
  </para>

  <sect1 id="config-setting">
   <title>Setting Parameters</title>

   <sect2 id="config-setting-names-values">
    <title>Parameter Names and Values</title>

    <para>
     All parameter names are case-insensitive. Every parameter takes a
     value of one of five types: Boolean, integer, floating point,
     string or enum. Boolean values can be written as <literal>on</literal>,
     <literal>off</literal>, <literal>true</literal>,
     <literal>false</literal>, <literal>yes</literal>,
     <literal>no</literal>, <literal>1</literal>, <literal>0</literal>
     (all case-insensitive) or any unambiguous prefix of these.
    </para>

    <para>
     Some settings specify a memory or time value.  Each of these has an
     implicit unit, which is either kilobytes, blocks (typically eight
     kilobytes), milliseconds, seconds, or minutes.  Default units can be
     found by referencing <structname>pg_settings</>.<structfield>unit</>.
     For convenience,
     a different unit can also be specified explicitly.  Valid memory units
     are <literal>kB</literal> (kilobytes), <literal>MB</literal>
     (megabytes), and <literal>GB</literal> (gigabytes); valid time units
     are <literal>ms</literal> (milliseconds), <literal>s</literal>
     (seconds), <literal>min</literal> (minutes), <literal>h</literal>
     (hours), and <literal>d</literal> (days).  Note that the multiplier
     for memory units is 1024, not 1000.
    </para>

    <para>
     Parameters of type <quote>enum</> are specified in the same way as string
     parameters, but are restricted to a limited set of values.  The allowed
     values can be found
     from <structname>pg_settings</>.<structfield>enumvals</>.
     Enum parameter values are case-insensitive.
    </para>
   </sect2>

   <sect2 id="config-setting-configuration-file">
    <title>Setting Parameters via the Configuration File</title>

    <para>
     One way to set these parameters is to edit the file
     <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
     which is normally kept in the data directory.  (A default copy is
     installed there when the database cluster directory is
     initialized.)  An example of what this file might look like is:
<programlisting>
# This is a comment
log_connections = yes
log_destination = 'syslog'
search_path = '"$user", public'
shared_buffers = 128MB
</programlisting>
     One parameter is specified per line. The equal sign between name and
     value is optional. Whitespace is insignificant and blank lines are
     ignored. Hash marks (<literal>#</literal>) designate the remainder of the
     line as a comment.  Parameter values that are not simple identifiers or
     numbers must be single-quoted.  To embed a single quote in a parameter
     value, write either two quotes (preferred) or backslash-quote.
    </para>

    <para>
     <indexterm>
      <primary><literal>include</></primary>
      <secondary>in configuration file</secondary>
     </indexterm>
     In addition to parameter settings, the <filename>postgresql.conf</>
     file can contain <firstterm>include directives</>, which specify
     another file to read and process as if it were inserted into the
     configuration file at this point.  This feature allows a configuration
     file to be divided into physically separate parts.
     Include directives simply look like:
<programlisting>
include 'filename'
</programlisting>
     If the file name is not an absolute path, it is taken as relative to
     the directory containing the referencing configuration file.
     Inclusions can be nested.
    </para>

    <para>
     <indexterm>
      <primary><literal>include_if_exists</></primary>
      <secondary>in configuration file</secondary>
     </indexterm>
     There is also an <literal>include_if_exists</> directive, which acts
     the same as the <literal>include</> directive, except for the behavior
     when the referenced file does not exist or cannot be read.  A regular
     <literal>include</> will consider this an error condition, but
     <literal>include_if_exists</> merely logs a message and continues
     processing the referencing configuration file.
    </para>

    <para>
     <indexterm>
      <primary>SIGHUP</primary>
     </indexterm>
     The configuration file is reread whenever the main server process
     receives a
     <systemitem>SIGHUP</> signal (which is most easily sent by means
     of <literal>pg_ctl reload</>). The main server process
     also propagates this signal to all currently running server
     processes so that existing sessions also get the new
     value. Alternatively, you can send the signal to a single server
     process directly.  Some parameters can only be set at server start;
     any changes to their entries in the configuration file will be ignored
     until the server is restarted.  Invalid parameter settings in the
     configuration file are likewise ignored (but logged) during
     <systemitem>SIGHUP</> processing.
    </para>
   </sect2>

   <sect2 id="config-setting-other-methods">
    <title>Other Ways to Set Parameters</title>

    <para>
     A second way to set these configuration parameters is to give them
     as a command-line option to the <command>postgres</command> command,
     such as:
<programlisting>
postgres -c log_connections=yes -c log_destination='syslog'
</programlisting>
     Command-line options override any conflicting settings in
     <filename>postgresql.conf</filename>.  Note that this means you won't
     be able to change the value on-the-fly by editing
     <filename>postgresql.conf</filename>, so while the command-line
     method might be convenient, it can cost you flexibility later.
    </para>

    <para>
     Occasionally it is useful to give a command line option to
     one particular session only. The environment variable
     <envar>PGOPTIONS</envar> can be used for this purpose on the
     client side:
<programlisting>
env PGOPTIONS='-c geqo=off' psql
</programlisting>
     (This works for any <application>libpq</>-based client application, not
     just <application>psql</application>.) Note that this won't work for
     parameters that are fixed when the server is started or that must be
     specified in <filename>postgresql.conf</filename>.
    </para>

    <para>
     Furthermore, it is possible to assign a set of parameter settings to
     a user or a database.  Whenever a session is started, the default
     settings for the user and database involved are loaded.  The
     commands <xref linkend="sql-alterrole">
     and <xref linkend="sql-alterdatabase">,
     respectively, are used to configure these settings.  Per-database
     settings override anything received from the
     <command>postgres</command> command-line or the configuration
     file, and in turn are overridden by per-user settings; both are
     overridden by per-session settings.
    </para>

    <para>
     Some parameters can be changed in individual <acronym>SQL</acronym>
     sessions with the <xref linkend="SQL-SET">
     command, for example:
<screen>
SET ENABLE_SEQSCAN TO OFF;
</screen>
     If <command>SET</> is allowed, it overrides all other sources of
     values for the parameter. Some parameters cannot be changed via
     <command>SET</command>: for example, if they control behavior that
     cannot be changed without restarting the entire
     <productname>PostgreSQL</productname> server.  Also, some parameters
     require superuser permission to change via <command>SET</command> or
     <command>ALTER</>.
    </para>
   </sect2>

   <sect2 id="config-setting-examining">
    <title>Examining Parameter Settings</title>

    <para>
     The <xref linkend="SQL-SHOW">
     command allows inspection of the current values of all parameters.
    </para>

    <para>
     The virtual table <structname>pg_settings</structname> also allows
     displaying and updating session run-time parameters;  see <xref
     linkend="view-pg-settings"> for details and a description of the
     different variable types and when they can be changed.
     <structname>pg_settings</structname> is equivalent to <command>SHOW</>
     and <command>SET</>, but can be more convenient
     to use because it can be joined with other tables, or selected from using
     any desired selection condition. It also contains more information about
     each parameter than is available from <command>SHOW</>.
    </para>

   </sect2>
  </sect1>

   <sect1 id="runtime-config-file-locations">
    <title>File Locations</title>

     <para>
      In addition to the <filename>postgresql.conf</filename> file
      already mentioned, <productname>PostgreSQL</productname> uses
      two other manually-edited configuration files, which control
      client authentication (their use is discussed in <xref
      linkend="client-authentication">).  By default, all three
      configuration files are stored in the database cluster's data
      directory.  The parameters described in this section allow the
      configuration files to be placed elsewhere.  (Doing so can ease
      administration.  In particular it is often easier to ensure that
      the configuration files are properly backed-up when they are
      kept separate.)
     </para>

     <variablelist>
     <varlistentry id="guc-data-directory" xreflabel="data_directory">
      <term><varname>data_directory</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>data_directory</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
         Specifies the directory to use for data storage.
         This parameter can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-config-file" xreflabel="config_file">
      <term><varname>config_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>config_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
         Specifies the main server configuration file
         (customarily called <filename>postgresql.conf</>).
         This parameter can only be set on the <command>postgres</command> command line.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-hba-file" xreflabel="hba_file">
      <term><varname>hba_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>hba_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
         Specifies the configuration file for host-based authentication
         (customarily called <filename>pg_hba.conf</>).
         This parameter can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-ident-file" xreflabel="ident_file">
      <term><varname>ident_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>ident_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
         Specifies the configuration file for
         <xref linkend="auth-username-maps"> user name mapping
         (customarily called <filename>pg_ident.conf</>).
         This parameter can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-external-pid-file" xreflabel="external_pid_file">
      <term><varname>external_pid_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>external_pid_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies the name of an additional process-ID (PID) file that the
        server should create for use by server administration programs.
        This parameter can only be set at server start.
       </para>
      </listitem>
     </varlistentry>
     </variablelist>

     <para>
      In a default installation, none of the above parameters are set
      explicitly.  Instead, the
      data directory is specified by the <option>-D</option> command-line
      option or the <envar>PGDATA</envar> environment variable, and the
      configuration files are all found within the data directory.
     </para>

     <para>
      If you wish to keep the configuration files elsewhere than the
      data directory, the <command>postgres</command> <option>-D</option>
      command-line option or <envar>PGDATA</envar> environment variable
      must point to the directory containing the configuration files,
      and the <varname>data_directory</> parameter must be set in
      <filename>postgresql.conf</filename> (or on the command line) to show
      where the data directory is actually located.  Notice that
      <varname>data_directory</> overrides <option>-D</option> and
      <envar>PGDATA</envar> for the location
      of the data directory, but not for the location of the configuration
      files.
     </para>

     <para>
      If you wish, you can specify the configuration file names and locations
      individually using the parameters <varname>config_file</>,
      <varname>hba_file</> and/or <varname>ident_file</>.
      <varname>config_file</> can only be specified on the
      <command>postgres</command> command line, but the others can be
      set within the main configuration file.  If all three parameters plus
      <varname>data_directory</> are explicitly set, then it is not necessary
      to specify <option>-D</option> or <envar>PGDATA</envar>.
     </para>

     <para>
      When setting any of these parameters, a relative path will be interpreted
      with respect to the directory in which <command>postgres</command>
      is started.
     </para>
   </sect1>

   <sect1 id="runtime-config-connection">
    <title>Connections and Authentication</title>

    <sect2 id="runtime-config-connection-settings">
     <title>Connection Settings</title>

     <variablelist>

     <varlistentry id="guc-listen-addresses" xreflabel="listen_addresses">
      <term><varname>listen_addresses</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>listen_addresses</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
         Specifies the TCP/IP address(es) on which the server is
         to listen for connections from client applications.
         The value takes the form of a comma-separated list of host names
         and/or numeric IP addresses.  The special entry <literal>*</>
         corresponds to all available IP interfaces.  The entry
         <literal>0.0.0.0</> allows listening for all IPv4 addresses and
         <literal>::</> allows listening for all IPv6 addresses.
         If the list is empty, the server does not listen on any IP interface
         at all, in which case only Unix-domain sockets can be used to connect
         to it.
         The default value is <systemitem class="systemname">localhost</>,
         which allows only local TCP/IP <quote>loopback</> connections to be
         made.  While client authentication (<xref
         linkend="client-authentication">) allows fine-grained control
         over who can access the server, <varname>listen_addresses</varname>
         controls which interfaces accept connection attempts, which
         can help prevent repeated malicious connection requests on
         insecure network interfaces.  This parameter can only be set
         at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-port" xreflabel="port">
      <term><varname>port</varname> (<type>integer</type>)</term>
      <indexterm>
       <primary><varname>port</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        The TCP port the server listens on; 5432 by default.  Note that the
        same port number is used for all IP addresses the server listens on.
        This parameter can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-max-connections" xreflabel="max_connections">
      <term><varname>max_connections</varname> (<type>integer</type>)</term>
      <indexterm>
       <primary><varname>max_connections</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Determines the maximum number of concurrent connections to the
        database server. The default is typically 100 connections, but
        might be less if your kernel settings will not support it (as
        determined during <application>initdb</>).  This parameter can
        only be set at server start.
       </para>

       <para>
        Increasing this parameter might cause <productname>PostgreSQL</>
        to request more <systemitem class="osname">System V</> shared
        memory or semaphores than your operating system's default configuration
        allows. See <xref linkend="sysvipc"> for information on how to
        adjust those parameters, if necessary.
       </para>

       <para>
        When running a standby server, you must set this parameter to the
        same or higher value than on the master server. Otherwise, queries
        will not be allowed in the standby server.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-superuser-reserved-connections"
     xreflabel="superuser_reserved_connections">
      <term><varname>superuser_reserved_connections</varname>
      (<type>integer</type>)</term>
      <indexterm>
       <primary><varname>superuser_reserved_connections</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Determines the number of connection <quote>slots</quote> that
        are reserved for connections by <productname>PostgreSQL</>
        superusers.  At most <xref linkend="guc-max-connections">
        connections can ever be active simultaneously.  Whenever the
        number of active concurrent connections is at least
        <varname>max_connections</> minus
        <varname>superuser_reserved_connections</varname>, new
        connections will be accepted only for superusers, and no
        new replication connections will be accepted.
       </para>

       <para>
        The default value is three connections. The value must be less
        than the value of <varname>max_connections</varname>. This
        parameter can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-unix-socket-directory" xreflabel="unix_socket_directory">
      <term><varname>unix_socket_directory</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>unix_socket_directory</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies the directory of the Unix-domain socket on which the
        server is to listen for
        connections from client applications.  The default is normally
        <filename>/tmp</filename>, but can be changed at build time.
        This parameter can only be set at server start.
       </para>

       <para>
        In addition to the socket file itself, which is named
        <literal>.s.PGSQL.<replaceable>nnnn</></literal> where
        <replaceable>nnnn</> is the server's port number, an ordinary file
        named <literal>.s.PGSQL.<replaceable>nnnn</>.lock</literal> will be
        created in the <varname>unix_socket_directory</> directory.  Neither
        file should ever be removed manually.
       </para>

       <para>
        This parameter is irrelevant on Windows, which does not have
        Unix-domain sockets.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-unix-socket-group" xreflabel="unix_socket_group">
      <term><varname>unix_socket_group</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>unix_socket_group</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Sets the owning group of the Unix-domain socket.  (The owning
        user of the socket is always the user that starts the
        server.)  In combination with the parameter
        <varname>unix_socket_permissions</varname> this can be used as
        an additional access control mechanism for Unix-domain connections.
        By default this is the empty string, which uses the default
        group of the server user.  This parameter can only be set at
        server start.
       </para>

       <para>
        This parameter is irrelevant on Windows, which does not have
        Unix-domain sockets.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-unix-socket-permissions" xreflabel="unix_socket_permissions">
      <term><varname>unix_socket_permissions</varname> (<type>integer</type>)</term>
      <indexterm>
       <primary><varname>unix_socket_permissions</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Sets the access permissions of the Unix-domain socket.  Unix-domain
        sockets use the usual Unix file system permission set.
        The parameter value is expected to be a numeric mode
        specified in the format accepted by the
        <function>chmod</function> and <function>umask</function>
        system calls.  (To use the customary octal format the number
        must start with a <literal>0</literal> (zero).)
       </para>

       <para>
        The default permissions are <literal>0777</literal>, meaning
        anyone can connect. Reasonable alternatives are
        <literal>0770</literal> (only user and group, see also
        <varname>unix_socket_group</varname>) and <literal>0700</literal>
        (only user). (Note that for a Unix-domain socket, only write
        permission matters, so there is no point in setting or revoking
        read or execute permissions.)
       </para>

       <para>
        This access control mechanism is independent of the one
        described in <xref linkend="client-authentication">.
       </para>

       <para>
        This parameter can only be set at server start.
       </para>

       <para>
        This parameter is irrelevant on systems, notably Solaris as of Solaris
        10, that ignore socket permissions entirely.  There, one can achieve a
        similar effect by pointing <varname>unix_socket_directory</> to a
        directory having search permission limited to the desired audience.
        This parameter is also irrelevant on Windows, which does not have
        Unix-domain sockets.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-bonjour" xreflabel="bonjour">
      <term><varname>bonjour</varname> (<type>boolean</type>)</term>
      <indexterm>
       <primary><varname>bonjour</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Enables advertising the server's existence via
        <productname>Bonjour</productname>.  The default is off.
        This parameter can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-bonjour-name" xreflabel="bonjour_name">
      <term><varname>bonjour_name</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>bonjour_name</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies the <productname>Bonjour</productname> service
        name.  The computer name is used if this parameter is set to the
        empty string <literal>''</> (which is the default).  This parameter is
        ignored if the server was not compiled with
        <productname>Bonjour</productname> support.
        This parameter can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-tcp-keepalives-idle" xreflabel="tcp_keepalives_idle">
      <term><varname>tcp_keepalives_idle</varname> (<type>integer</type>)</term>
      <indexterm>
       <primary><varname>tcp_keepalives_idle</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies the number of seconds before sending a keepalive packet on
        an otherwise idle connection.  A value of 0 uses the system default.
        This parameter is supported only on systems that support the
        <symbol>TCP_KEEPIDLE</> or <symbol>TCP_KEEPALIVE</> symbols, and on
        Windows; on other systems, it must be zero.
        In sessions connected via a Unix-domain socket, this parameter is
        ignored and always reads as zero.
       </para>
       <note>
        <para>
         On Windows, a value of 0 will set this parameter to 2 hours,
         since Windows does not provide a way to read the system default value.
        </para>
       </note>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-tcp-keepalives-interval" xreflabel="tcp_keepalives_interval">
      <term><varname>tcp_keepalives_interval</varname> (<type>integer</type>)</term>
      <indexterm>
       <primary><varname>tcp_keepalives_interval</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies the number of seconds between sending keepalives on an
        otherwise idle connection.  A value of 0 uses the system default.
        This parameter is supported only on systems that support the
        <symbol>TCP_KEEPINTVL</> symbol, and on Windows; on other systems, it
        must be zero.
        In sessions connected via a Unix-domain socket, this parameter is
        ignored and always reads as zero.
       </para>
       <note>
        <para>
         On Windows, a value of 0 will set this parameter to 1 second,
         since Windows does not provide a way to read the system default value.
        </para>
       </note>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-tcp-keepalives-count" xreflabel="tcp_keepalives_count">
      <term><varname>tcp_keepalives_count</varname> (<type>integer</type>)</term>
      <indexterm>
       <primary><varname>tcp_keepalives_count</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies the number of keepalive packets to send on an otherwise idle
        connection.  A value of 0 uses the system default.  This parameter is
        supported only on systems that support the <symbol>TCP_KEEPCNT</>
        symbol; on other systems, it must be zero.
        In sessions connected via a Unix-domain socket, this parameter is
        ignored and always reads as zero.
       </para>
       <note>
        <para>
         This parameter is not supported on Windows, and must be zero.
        </para>
       </note>
      </listitem>
     </varlistentry>

     </variablelist>
     </sect2>
     <sect2 id="runtime-config-connection-security">
     <title>Security and Authentication</title>

     <variablelist>
     <varlistentry id="guc-authentication-timeout" xreflabel="authentication_timeout">
      <term><varname>authentication_timeout</varname> (<type>integer</type>)</term>
      <indexterm><primary>timeout</><secondary>client authentication</></indexterm>
      <indexterm><primary>client authentication</><secondary>timeout during</></indexterm>
      <indexterm>
       <primary><varname>authentication_timeout</> configuration parameter</primary>
      </indexterm>

      <listitem>
       <para>
        Maximum time to complete client authentication, in seconds. If a
        would-be client has not completed the authentication protocol in
        this much time, the server closes the connection. This prevents
        hung clients from occupying a connection indefinitely.
        The default is one minute (<literal>1m</>).
        This parameter can only be set in the <filename>postgresql.conf</>
        file or on the server command line.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-ssl" xreflabel="ssl">
      <term><varname>ssl</varname> (<type>boolean</type>)</term>
      <indexterm>
       <primary><varname>ssl</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Enables <acronym>SSL</> connections. Please read
        <xref linkend="ssl-tcp"> before using this. The default
        is <literal>off</>. This parameter can only be set at server
        start.  <acronym>SSL</> communication is only possible with
        TCP/IP connections.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-ssl-ca-file" xreflabel="ssl_ca_file">
      <term><varname>ssl_ca_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>ssl_ca_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies the name of the file containing the SSL server certificate
        authority (CA).  The default is empty, meaning no CA file is loaded,
        and client certificate verification is not performed.  (In previous
        releases of PostgreSQL, the name of this file was hard-coded
        as <filename>root.crt</filename>.)  Relative paths are relative to the
        data directory.  This parameter can only be set at server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-ssl-cert-file" xreflabel="ssl_cert_file">
      <term><varname>ssl_cert_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>ssl_cert_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies the name of the file containing the SSL server certificate.
        The default is <filename>server.crt</filename>.  Relative paths are
        relative to the data directory.  This parameter can only be set at
        server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-ssl-crl-file" xreflabel="ssl_crl_file">
      <term><varname>ssl_crl_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>ssl_crl_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies the name of the file containing the SSL server certificate
        revocation list (CRL).  The default is empty, meaning no CRL file is
        loaded.  (In previous releases of PostgreSQL, the name of this file was
        hard-coded as <filename>root.crl</filename>.)  Relative paths are
        relative to the data directory.  This parameter can only be set at
        server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-ssl-key-file" xreflabel="ssl_key_file">
      <term><varname>ssl_key_file</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>ssl_key_file</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies the name of the file containing the SSL server private key.
        The default is <filename>server.key</filename>.  Relative paths are
        relative to the data directory.  This parameter can only be set at
        server start.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-ssl-renegotiation-limit" xreflabel="ssl_renegotiation_limit">
      <term><varname>ssl_renegotiation_limit</varname> (<type>integer</type>)</term>
      <indexterm>
       <primary><varname>ssl_renegotiation_limit</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies how much data can flow over an <acronym>SSL</>-encrypted
        connection before renegotiation of the session keys will take
        place. Renegotiation decreases an attacker's chances of doing
        cryptanalysis when large amounts of traffic can be examined, but it
        also carries a large performance penalty. The sum of sent and received
        traffic is used to check the limit. If this parameter is set to 0,
        renegotiation is disabled. The default is <literal>0</>.
       </para>
       <note>
        <para>
         SSL libraries from before November 2009 are insecure when using SSL
         renegotiation, due to a vulnerability in the SSL protocol. As a
         stop-gap fix for this vulnerability, some vendors shipped SSL
         libraries incapable of doing renegotiation. If any such libraries
         are in use on the client or server, SSL renegotiation should be
         disabled.
        </para>
       </note>

       <warning>
        <para>
         Due to bugs in <productname>OpenSSL</> enabling ssl renegotiation, by
         configuring a non-zero <varname>ssl_renegotiation_limit</>, is likely
         to lead to problems like long-lived connections breaking.
        </para>
       </warning>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-ssl-ciphers" xreflabel="ssl_ciphers">
      <term><varname>ssl_ciphers</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>ssl_ciphers</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies a list of <acronym>SSL</> ciphers that are allowed to be
        used on secure connections. See the <application>openssl</>
        manual page for a list of supported ciphers.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-password-encryption" xreflabel="password_encryption">
      <term><varname>password_encryption</varname> (<type>boolean</type>)</term>
      <indexterm>
       <primary><varname>password_encryption</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        When a password is specified in <xref
        linkend="sql-createuser"> or
        <xref linkend="sql-alterrole">
        without writing either <literal>ENCRYPTED</> or
        <literal>UNENCRYPTED</>, this parameter determines whether the
        password is to be encrypted. The default is <literal>on</>
        (encrypt the password).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-krb-server-keyfile" xreflabel="krb_server_keyfile">
      <term><varname>krb_server_keyfile</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>krb_server_keyfile</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Sets the location of the Kerberos server key file. See
        <xref linkend="kerberos-auth"> or <xref linkend="gssapi-auth">
        for details. This parameter can only be set in the
        <filename>postgresql.conf</> file or on the server command line.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-krb-srvname" xreflabel="krb_srvname">
      <term><varname>krb_srvname</varname> (<type>string</type>)</term>
      <indexterm>
       <primary><varname>krb_srvname</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Sets the Kerberos service name. See <xref linkend="kerberos-auth">
        for details. This parameter can only be set in the
        <filename>postgresql.conf</> file or on the server command line.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-krb-caseins-users" xreflabel="krb_caseins_users">
      <term><varname>krb_caseins_users</varname> (<type>boolean</type>)</term>
      <indexterm>
       <primary><varname>krb_caseins_users</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Sets whether Kerberos and GSSAPI user names should be treated
        case-insensitively.
        The default is <literal>off</> (case sensitive). This parameter can only be
        set in the <filename>postgresql.conf</> file or on the server command line.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-db-user-namespace" xreflabel="db_user_namespace">
      <term><varname>db_user_namespace</varname> (<type>boolean</type>)</term>
      <indexterm>
       <primary><varname>db_user_namespace</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        This parameter enables per-database user names.  It is off by default.
        This parameter can only be set in the <filename>postgresql.conf</>
        file or on the server command line.
       </para>

       <para>
        If this is on, you should create users as <literal>username@dbname</>.
        When <literal>username</> is passed by a connecting client,
        <literal>@</> and the database name are appended to the user
        name and that database-specific user name is looked up by the
        server. Note that when you create users with names containing
        <literal>@</> within the SQL environment, you will need to
        quote the user name.
       </para>

       <para>
        With this parameter enabled, you can still create ordinary global
        users.  Simply append <literal>@</> when specifying the user
        name in the client, e.g. <literal>joe@</>.  The <literal>@</>
        will be stripped off before the user name is looked up by the
        server.
       </para>

       <para>
        <varname>db_user_namespace</> causes the client's and
        server's user name representation to differ.
        Authentication checks are always done with the server's user name
        so authentication methods must be configured for the
        server's user name, not the client's.  Because
        <literal>md5</> uses the user name as salt on both the
        client and server, <literal>md5</> cannot be used with
        <varname>db_user_namespace</>.
       </para>

       <note>
        <para>
         This feature is intended as a temporary measure until a
         complete solution is found.  At that time, this option will
         be removed.
        </para>
       </note>
      </listitem>
     </varlistentry>

    </variablelist>
    </sect2>
   </sect1>

   <sect1 id="runtime-config-resource">
    <title>Resource Consumption</title>

    <sect2 id="runtime-config-resource-memory">
     <title>Memory</title>

     <variablelist>
     <varlistentry id="guc-shared-buffers" xreflabel="shared_buffers">
      <term><varname>shared_buffers</varname> (<type>integer</type>)</term>
      <indexterm>
       <primary><varname>shared_buffers</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Sets the amount of memory the database server uses for shared
        memory buffers.  The default is typically 32 megabytes
        (<literal>32MB</>), but might be less if your kernel settings will
        not support it (as determined during <application>initdb</>).
        This setting must be at least 128 kilobytes.  (Non-default
        values of <symbol>BLCKSZ</symbol> change the minimum.)  However,
        settings significantly higher than the minimum are usually needed
        for good performance.  This parameter can only be set at server start.
       </para>

       <para>
        If you have a dedicated database server with 1GB or more of RAM, a
        reasonable starting value for <varname>shared_buffers</varname> is 25%
        of the memory in your system.  There are some workloads where even
        large settings for <varname>shared_buffers</varname> are effective, but
        because <productname>PostgreSQL</productname> also relies on the
        operating system cache, it is unlikely that an allocation of more than
        40% of RAM to <varname>shared_buffers</varname> will work better than a
        smaller amount.  Larger settings for <varname>shared_buffers</varname>
        usually require a corresponding increase in
        <varname>checkpoint_segments</varname>, in order to spread out the
        process of writing large quantities of new or changed data over a
        longer period of time.
       </para>

       <para>
        On systems with less than 1GB of RAM, a smaller percentage of RAM is
        appropriate, so as to leave adequate space for the operating system.
        Also, on Windows, large values for <varname>shared_buffers</varname>
        aren't as effective.  You may find better results keeping the setting
        relatively low and using the operating system cache more instead.  The
        useful range for <varname>shared_buffers</varname> on Windows systems
        is generally from 64MB to 512MB.
       </para>

       <para>
        Increasing this parameter might cause <productname>PostgreSQL</>
        to request more <systemitem class="osname">System V</> shared
        memory than your operating system's default configuration
        allows. See <xref linkend="sysvipc"> for information on how to
        adjust those parameters, if necessary.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="guc-temp-buffers" xreflabel="temp_buffers">
      <term><varname>temp_buffers</varname> (<type>integer</type>)</term>
      <indexterm>
       <primary><varname>temp_buffers</> configuration parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Sets the maximum number of temporary buffers used by each database
        session.  These are session-local buffers used only for access to
        temporary tables.  The default is eight megabytes
        (<literal>8MB</>).  The setting can be changed within individual