From: Tom Lane Date: Mon, 23 Mar 2026 19:33:51 +0000 (-0400) Subject: Doc: minor improvements to SNI documentation. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7c08a7e809721212b0c2b694cd19bd4379b8974f;p=thirdparty%2Fpostgresql.git Doc: minor improvements to SNI documentation. My attention was drawn to this new documentation by overlength-line complaints in the PDF docs builds: the synopsis for hostname lines was too wide. I initially thought of shortening the parameter names to fit, but it turns out that adding markup is enough to persuade DocBook to break the line, and that seems more helpful anyway. While here, I couldn't resist some copy-editing, mostly being consistent about whether to use Oxford commas or not. The biggest change was to re-order the entries in the hostname-values table to match the running text. --- diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index cb332913ab1..8576ae325d4 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -2606,21 +2606,22 @@ openssl x509 -req -in server.csr -text -days 365 \ configuration file. PostgreSQL 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 - the hosts which are defined in pg_hosts.conf. + entries in the configuration file pg_hosts.conf. SNI configuration is defined in the hosts configuration file, pg_hosts.conf, which is stored in the cluster's - data directory. The hosts configuration file contains lines of the general - forms: + data directory. The hosts configuration file contains lines of these + general forms: -hostname SSL_certificate SSL_key SSL_CA_certificate SSL_passphrase_cmd SSL_passphrase_cmd_reload +hostname SSL_certificate SSL_key SSL_CA_certificate SSL_passphrase_cmd SSL_passphrase_cmd_reload include file include_if_exists file include_dir directory - Comments, whitespace and line continuations are handled in the same way as + Comments, whitespace, line continuations, and inclusion directives are + handled in the same way as in pg_hba.conf. hostname is matched against the hostname TLS extension in the SSL handshake. SSL_certificate, @@ -2635,21 +2636,21 @@ openssl x509 -req -in server.csr -text -days 365 \ , and respectively. All fields except SSL_CA_certificate, - SSL_passphrase_cmd and + SSL_passphrase_cmd, and SSL_passphrase_cmd_reload are required. If - SSL_passphrase_cmd is defined but not - SSL_passphrase_cmd_reload then the default + SSL_passphrase_cmd is provided but not + SSL_passphrase_cmd_reload, then the default value for SSL_passphrase_cmd_reload is off. - hostname should either be set to the literal - hostname for the connection, /no_sni/ or *. + hostname can be either the literal + hostname for the connection, /no_sni/, or *. contains details on how these values are used. - Hostname setting values + Hostname field values @@ -2661,10 +2662,13 @@ openssl x509 -req -in server.csr -text -days 365 \ - * - Not required + hostname + Required - Default host, matches all connections. + Certificate and key to use for connections to the host specified in + the connection. Multiple hostnames can be defined by using a comma + separated list. The certificate and key will be used for connections + to all hosts in the list. @@ -2678,13 +2682,10 @@ openssl x509 -req -in server.csr -text -days 365 \ - hostname - Required + * + Not required - Certificate and key to use for connections to the host specified in - the connection. Multiple hostnames can be defined by using a comma - separated list. The certificate and key will be used for connections - to all hosts in the list. + Default host, matches all connections. @@ -2694,7 +2695,7 @@ openssl x509 -req -in server.csr -text -days 365 \ - If pg_hosts.conf is empty, or missing, then the SSL + If pg_hosts.conf is empty or missing, then the SSL configuration in postgresql.conf will be used for all connections. If pg_hosts.conf is non-empty then it will take precedence over certificate and key settings in @@ -2711,7 +2712,7 @@ openssl x509 -req -in server.csr -text -days 365 \ The CRL configuration in postgresql.conf is applied - on all connections regardless of if they use SNI or not. + to all connections regardless of whether they use SNI or not.