On Tue, Aug 2, 2022 at 08:08:07PM +0000, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html > Description: > > On the pg_hba.conf page, > https://www.postgresql.org/docs/current/auth-pg-hba-conf.html, the bulk of > the page involves the format of the file and what the fields mean. There are > a couple of sentences of usage information (how to reload the file after > changes) in the middle of the reference info. It's possible to overlook the > how-to info on the long page if you don't need the details about the file > contents, just that one tip about reloading. > > > The pg_hba.conf file is read on start-up and when the main server process > receives a SIGHUP signal. If you edit the file on an active system, you will > need to signal the postmaster (using pg_ctl reload, calling the SQL function > pg_reload_conf(), or using kill -HUP) to make it re-read the file. > > I suggest moving the usage info to one end of the page or the other, and > adding a subheading to clarify that the page covers more than the syntax of > the file contents. Possibilities: > > 21.1. The pg_hba.conf File > Client authentication is controlled... (same first paragraph as before) > > 21.1.1 Loading or Reloading the Configuration > The pg_hba.conf file is read on start-up... > Note: The preceding statement... > The system view pg_hba_file_rules can be helpful... > > 21.1.2 Contents of pg_hba.conf > The general format of the pg_hba.conf file is a set of records... > <all the other info about the format and contents of the file> > > Example 21.1. Example pg_hba.conf Entries > > or > > 21.1. The pg_hba.conf File > Client authentication is controlled... > The general format of the pg_hba.conf file is a set of records... > <all the other info about the format and contents of the file> > > Example 21.1. Example pg_hba.conf Entries > > 21.1.1 Loading or Reloading the Configuration > The pg_hba.conf file is read on start-up... > Note: The preceding statement... > The system view pg_hba_file_rules can be helpful...
This is a good point. I moved the reload sections for pg_hba.conf and pg_ident.conf up near the top of their sections in the attached patch. -- Bruce Momjian <br...@momjian.us> https://momjian.us EDB https://enterprisedb.com Only you can decide what is important to you.
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 2f1bd6fc8a..477f70a65d 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -73,6 +73,35 @@ however; see the <xref linkend="guc-hba-file"/> configuration parameter. </para> + <para> + The <filename>pg_hba.conf</filename> file is read on start-up and when + the main server process receives a + <systemitem>SIGHUP</systemitem><indexterm><primary>SIGHUP</primary></indexterm> + signal. If you edit the file on an + active system, you will need to signal the postmaster + (using <literal>pg_ctl reload</literal>, calling the SQL function + <function>pg_reload_conf()</function>, or using <literal>kill + -HUP</literal>) to make it re-read the file. + </para> + + <note> + <para> + The preceding statement is not true on Microsoft Windows: there, any + changes in the <filename>pg_hba.conf</filename> file are immediately + applied by subsequent new connections. + </para> + </note> + + <para> + The system view + <link linkend="view-pg-hba-file-rules"><structname>pg_hba_file_rules</structname></link> + can be helpful for pre-testing changes to the <filename>pg_hba.conf</filename> + file, or for diagnosing problems if loading of the file did not have the + desired effects. Rows in the view with + non-null <structfield>error</structfield> fields indicate problems in the + corresponding lines of the file. + </para> + <para> The general format of the <filename>pg_hba.conf</filename> file is a set of records, one per line. Blank lines are ignored, as is any @@ -733,35 +762,6 @@ openssl x509 -in myclient.crt -noout --subject -nameopt RFC2253 | sed "s/^subjec range of allowed client IP addresses. </para> - <para> - The <filename>pg_hba.conf</filename> file is read on start-up and when - the main server process receives a - <systemitem>SIGHUP</systemitem><indexterm><primary>SIGHUP</primary></indexterm> - signal. If you edit the file on an - active system, you will need to signal the postmaster - (using <literal>pg_ctl reload</literal>, calling the SQL function - <function>pg_reload_conf()</function>, or using <literal>kill - -HUP</literal>) to make it re-read the file. - </para> - - <note> - <para> - The preceding statement is not true on Microsoft Windows: there, any - changes in the <filename>pg_hba.conf</filename> file are immediately - applied by subsequent new connections. - </para> - </note> - - <para> - The system view - <link linkend="view-pg-hba-file-rules"><structname>pg_hba_file_rules</structname></link> - can be helpful for pre-testing changes to the <filename>pg_hba.conf</filename> - file, or for diagnosing problems if loading of the file did not have the - desired effects. Rows in the view with - non-null <structfield>error</structfield> fields indicate problems in the - corresponding lines of the file. - </para> - <tip> <para> To connect to a particular database, a user must not only pass the @@ -933,6 +933,28 @@ local db1,db2,@demodbs all md5 As for <filename>pg_hba.conf</filename>, the lines in this file can be include directives, following the same rules. </para> + + <para> + The <filename>pg_ident.conf</filename> file is read on start-up and + when the main server process receives a + <systemitem>SIGHUP</systemitem><indexterm><primary>SIGHUP</primary></indexterm> + signal. If you edit the file on an + active system, you will need to signal the postmaster + (using <literal>pg_ctl reload</literal>, calling the SQL function + <function>pg_reload_conf()</function>, or using <literal>kill + -HUP</literal>) to make it re-read the file. + </para> + + <para> + The system view + <link linkend="view-pg-ident-file-mappings"><structname>pg_ident_file_mappings</structname></link> + can be helpful for pre-testing changes to the + <filename>pg_ident.conf</filename> file, or for diagnosing problems if + loading of the file did not have the desired effects. Rows in the view with + non-null <structfield>error</structfield> fields indicate problems in the + corresponding lines of the file. + </para> + <para> There is no restriction regarding how many database users a given operating system user can correspond to, nor vice versa. Thus, entries @@ -999,27 +1021,6 @@ mymap /^(.*)@otherdomain\.com$ guest </para> </tip> - <para> - The <filename>pg_ident.conf</filename> file is read on start-up and - when the main server process receives a - <systemitem>SIGHUP</systemitem><indexterm><primary>SIGHUP</primary></indexterm> - signal. If you edit the file on an - active system, you will need to signal the postmaster - (using <literal>pg_ctl reload</literal>, calling the SQL function - <function>pg_reload_conf()</function>, or using <literal>kill - -HUP</literal>) to make it re-read the file. - </para> - - <para> - The system view - <link linkend="view-pg-ident-file-mappings"><structname>pg_ident_file_mappings</structname></link> - can be helpful for pre-testing changes to the - <filename>pg_ident.conf</filename> file, or for diagnosing problems if - loading of the file did not have the desired effects. Rows in the view with - non-null <structfield>error</structfield> fields indicate problems in the - corresponding lines of the file. - </para> - <para> A <filename>pg_ident.conf</filename> file that could be used in conjunction with the <filename>pg_hba.conf</filename> file in <xref