public inbox for [email protected]
help / color / mirror / Atom feedFrom: Daniel Gustafsson <[email protected]>
To: Fujii Masao <[email protected]>
Cc: [email protected]
Subject: Re: pgsql: ssl: Serverside SNI support for libpq
Date: Mon, 13 Apr 2026 10:24:21 +0200
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
<CAHGQGwESD2Pty+J1kP3mXmWwMKZ5uJmknZdJsSGrMSRR6CQBmw@mail.gmail.com>
<[email protected]>
> On 10 Apr 2026, at 20:23, Daniel Gustafsson <[email protected]> wrote:
>
>> On 10 Apr 2026, at 18:34, Fujii Masao <[email protected]> wrote:
>>
>> On Wed, Mar 18, 2026 at 8:48 PM Daniel Gustafsson
>> <[email protected]> wrote:
>>>
>>> ssl: Serverside SNI support for libpq
>>
>> This commit introduced the hosts_file and ssl_sni GUCs and added them to
>> postgresql.conf.sample, but I don't see any descriptions for them
>> in config.sgml. Was that just an oversight?
>
> That was a mistake when adding the doc portions of the patch. Thanks for the
> report, I'll work on a patch.
Attached is what I have planned for this, it adds the GUCs as well as tidies up
the existing SSL SNI docs a bit.
--
Daniel Gustafsson
Attachments:
[application/octet-stream] v1-0001-doc-Add-missing-GUCs-to-SSL-SNI-docs.patch (8.3K, ../[email protected]/2-v1-0001-doc-Add-missing-GUCs-to-SSL-SNI-docs.patch)
download | inline diff:
From 1d70bf610bfe53b12c6f616261605fd23c4753fc Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <[email protected]>
Date: Mon, 13 Apr 2026 10:08:49 +0200
Subject: [PATCH v1] 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 <[email protected]>
Reported-by: Fujii Masao <[email protected]>
Discussion: https://postgr.es/m/CAHGQGwESD2Pty+J1kP3mXmWwMKZ5uJmknZdJsSGrMSRR6CQBmw@mail.gmail.com
---
doc/src/sgml/config.sgml | 45 +++++++++++++++++++++++++++++++++++----
doc/src/sgml/runtime.sgml | 29 ++++++++++++-------------
2 files changed, 55 insertions(+), 19 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 009295f20e9..67da9a1de66 100644
--- 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 8576ae325d4..b01e74638c4 100644
--- 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>
--
2.39.3 (Apple Git-146)
view thread (6+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected]
Subject: Re: pgsql: ssl: Serverside SNI support for libpq
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox