doc: Add missing GUCs to SSL SNI docs

The ssl_sni and hosts_file GUCs were missing from the configuration
section of the documentation, they were only described in the main
SSL SNI subsection.  This adds the GUCs to the relevant sections as
well as rewords the existing SSL SNI documentation to refer to the
settings along with a few smaller fixups.

Author: Daniel Gustafsson <daniel@yesql.se>
Reported-by: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Discussion: https://postgr.es/m/CAHGQGwESD2Pty+J1kP3mXmWwMKZ5uJmknZdJsSGrMSRR6CQBmw@mail.gmail.com

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 009295f20e935b0f9e28e2c896787a5ed6efb444..67da9a1de66b5d603df05a9b00df79e411d9a95c 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -507,9 +507,10 @@ include_dir 'conf.d'
      <para>
       In addition to the <filename>postgresql.conf</filename> file
       already mentioned, <productname>PostgreSQL</productname> uses
-      two other manually-edited configuration files, which control
+      three other manually-edited configuration files, which control
       client authentication (their use is discussed in <xref
-      linkend="client-authentication"/>).  By default, all three
+      linkend="client-authentication"/>) and SSL host configuration.
+      By default, all four
       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
@@ -579,6 +580,22 @@ include_dir 'conf.d'
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-hosts-file" xreflabel="hosts_file">
+      <term><varname>hosts_file</varname> (<type>string</type>)
+      <indexterm>
+       <primary><varname>hosts_file</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+         Specifies the configuration file for host-based SSL configuration
+         (customarily called <filename>pg_hosts.conf</filename>).
+         This parameter can only be set at server start. See also
+         <xref linkend="ssl-sni"/>.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="guc-external-pid-file" xreflabel="external_pid_file">
       <term><varname>external_pid_file</varname> (<type>string</type>)
       <indexterm>
@@ -620,10 +637,11 @@ include_dir 'conf.d'
      <para>
       If you wish, you can specify the configuration file names and locations
       individually using the parameters <varname>config_file</varname>,
-      <varname>hba_file</varname> and/or <varname>ident_file</varname>.
+      <varname>hba_file</varname>, <varname>ident_file</varname> and/or
+      <varname>hosts_file</varname>.
       <varname>config_file</varname> 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
+      set within the main configuration file.  If all four parameters plus
       <varname>data_directory</varname> are explicitly set, then it is not necessary
       to specify <option>-D</option> or <envar>PGDATA</envar>.
      </para>
@@ -1734,6 +1752,25 @@ include_dir 'conf.d'
        </para>
       </listitem>
      </varlistentry>
+
+     <varlistentry id="guc-ssl-sni" xreflabel="ssl_sni">
+      <term><varname>ssl_sni</varname> (<type>boolean</type>)
+      <indexterm>
+       <primary><varname>ssl_sni</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        Enables SNI configuration for SSL connections.  When set to <literal>on</literal>
+        host configuration from <xref linkend="guc-hosts-file"/> is used, see
+        <xref linkend="ssl-sni"/> for more details.
+       </para>
+       <para>
+        This parameter can only be set in the <filename>postgresql.conf</filename>
+        file or on the server command line.  The default is <literal>off</literal>.
+       </para>
+      </listitem>
+     </varlistentry>
     </variablelist>
     </sect2>
    </sect1>

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 8576ae325d4b5ec8c35889159ed710c9884b5d4a..b01e74638c429310762074946ef4d96e9697694c 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -2602,18 +2602,16 @@ openssl x509 -req -in server.csr -text -days 365 \
 
    <para>
     <productname>PostgreSQL</productname> can be configured for Server Name
-    Indication, <acronym>SNI</acronym>, using the <filename>pg_hosts.conf</filename>
-    configuration file. <productname>PostgreSQL</productname> inspects the TLS
-    hostname extension in the SSL connection handshake, and selects the right
-    TLS certificate, key and CA certificate to use for the connection based on
-    entries in the configuration file <filename>pg_hosts.conf</filename>.
+    Indication, <acronym>SNI</acronym>, using the <xref linkend="guc-ssl-sni"/>
+    configuration parameter. <productname>PostgreSQL</productname> inspects the
+    TLS hostname extension in the SSL connection handshake, and selects the
+    right certificate, key and CA certificate to use for the connection based
+    on entries in the <xref linkend="guc-hosts-file"/> configuration file.
    </para>
 
    <para>
-    SNI configuration is defined in the hosts configuration file,
-    <filename>pg_hosts.conf</filename>, which is stored in the cluster's
-    data directory.  The hosts configuration file contains lines of these
-    general forms:
+    The <xref linkend="guc-hosts-file"/> configuration file contains lines of
+    these general forms:
 <synopsis>
 <replaceable>hostname</replaceable> <replaceable>SSL_certificate</replaceable> <replaceable>SSL_key</replaceable> <optional> <replaceable>SSL_CA_certificate</replaceable> <optional> <replaceable>SSL_passphrase_cmd</replaceable> <optional> <replaceable>SSL_passphrase_cmd_reload</replaceable> </optional> </optional> </optional>
 <literal>include</literal> <replaceable>file</replaceable>
@@ -2622,8 +2620,9 @@ openssl x509 -req -in server.csr -text -days 365 \
 </synopsis>
     Comments, whitespace, line continuations, and inclusion directives are
     handled in the same way as
-    in <filename>pg_hba.conf</filename>.  <replaceable>hostname</replaceable>
-    is matched against the hostname TLS extension in the SSL handshake.
+    in <xref linkend="guc-hba-file"/>.  <replaceable>hostname</replaceable>
+    is matched case-insensitively against the <literal>hostname</literal> TLS
+    extension in the SSL handshake.
     <replaceable>SSL_certificate</replaceable>,
     <replaceable>SSL_key</replaceable>,
     <replaceable>SSL_CA_certificate</replaceable>,
@@ -2655,7 +2654,7 @@ openssl x509 -req -in server.csr -text -days 365 \
       <thead>
        <row>
         <entry>Host Entry</entry>
-        <entry>sslsni</entry>
+        <entry>Hostname extension</entry>
         <entry>Description</entry>
        </row>
       </thead>
@@ -2695,9 +2694,9 @@ openssl x509 -req -in server.csr -text -days 365 \
    </para>
 
    <para>
-    If <filename>pg_hosts.conf</filename> is empty or missing, then the SSL
+    If <xref linkend="guc-hosts-file"/> is empty or missing, then the SSL
     configuration in <filename>postgresql.conf</filename> will be used for all
-    connections. If <filename>pg_hosts.conf</filename> is non-empty then it
+    connections. If <xref linkend="guc-hosts-file"/> is non-empty then it
     will take precedence over certificate and key settings in
     <filename>postgresql.conf</filename>.
    </para>
@@ -2705,7 +2704,7 @@ openssl x509 -req -in server.csr -text -days 365 \
    <para>
     It is currently not possible to set different <literal>clientname</literal>
     values for the different certificates.  Any <literal>clientname</literal>
-    setting in <filename>pg_hba.conf</filename> will be applied during
+    setting in <xref linkend="guc-hba-file"/> will be applied during
     authentication regardless of which set of certificates have been loaded
     via an SNI enabled connection.
    </para>