Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1qwpYJ-00EWsv-2D for pgsql-docs@arkaria.postgresql.org; Sat, 28 Oct 2023 20:04:59 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.94.2) (envelope-from ) id 1qwpYG-005Syx-Lh for pgsql-docs@arkaria.postgresql.org; Sat, 28 Oct 2023 20:04:56 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1qwpYF-005Syp-W7 for pgsql-docs@lists.postgresql.org; Sat, 28 Oct 2023 20:04:56 +0000 Received: from momjian.us ([72.94.173.45]) by makus.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1qwpY8-002mD0-Hu for pgsql-docs@lists.postgresql.org; Sat, 28 Oct 2023 20:04:54 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=momjian.us; s=2023062407; h=In-Reply-To:Content-Type:MIME-Version:References:Message-ID: Subject:To:From:Date:Sender:Reply-To:Cc:Content-Transfer-Encoding:Content-ID: Content-Description; bh=egPSViPodeq5cT9UPjnKadUrWizKsfC9KOBXTHt1Vrc=; b=oFcjc OiNDhGWO+G0lFzujaw5KbEezNNcLC8U3WUZRxgPcnmtDr4lQXd29QUMkMnuIBy/j/hMVFvtR+CwWZ qGKVCl/WxRhZuY9BRpz4VJFwu7AR4DCb6d2rwg7oJrCfoTx6V9fjLTtm/qwXraKjhgiRugV4yG/rm aSMcWEQu4RbhgHdu0uuz5K7t6qwHepT1SeqjDsz4qD7eZaJSYc2n9WRoSxX68werp7Rz6/5Sm7Izq S2yL63mRNCsItMF3u+VIv0A7GFhnq4i2i6FtHoCkpRKqeifeRlDFd4LaUMV3bUoA8khFrvwl8msdv bNEQrixB5gSLWnsrZCzum3vTC2CKA==; Received: from bruce by momjian.us with local (Exim 4.96) (envelope-from ) id 1qwpY7-0099CL-1F; Sat, 28 Oct 2023 16:04:47 -0400 Date: Sat, 28 Oct 2023 16:04:47 -0400 From: Bruce Momjian To: johrss@amazon.com, pgsql-docs@lists.postgresql.org Subject: Re: Usage instructions for pg_hba.conf file Message-ID: References: <165947088723.651.7641196693246068619@wrigleys.postgresql.org> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="WKTVmT5xiCwa21DZ" Content-Disposition: inline In-Reply-To: <165947088723.651.7641196693246068619@wrigleys.postgresql.org> List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --WKTVmT5xiCwa21DZ Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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... > > > 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... > > > 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 https://momjian.us EDB https://enterprisedb.com Only you can decide what is important to you. --WKTVmT5xiCwa21DZ Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="hba.diff" 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 configuration parameter. + + The pg_hba.conf file is read on start-up and when + the main server process receives a + SIGHUPSIGHUP + 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. + + + + + The preceding statement is not true on Microsoft Windows: there, any + changes in the pg_hba.conf file are immediately + applied by subsequent new connections. + + + + + The system view + pg_hba_file_rules + can be helpful for pre-testing changes to the pg_hba.conf + file, or for diagnosing problems if loading of the file did not have the + desired effects. Rows in the view with + non-null error fields indicate problems in the + corresponding lines of the file. + + The general format of the pg_hba.conf 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. - - The pg_hba.conf file is read on start-up and when - the main server process receives a - SIGHUPSIGHUP - 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. - - - - - The preceding statement is not true on Microsoft Windows: there, any - changes in the pg_hba.conf file are immediately - applied by subsequent new connections. - - - - - The system view - pg_hba_file_rules - can be helpful for pre-testing changes to the pg_hba.conf - file, or for diagnosing problems if loading of the file did not have the - desired effects. Rows in the view with - non-null error fields indicate problems in the - corresponding lines of the file. - - 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 pg_hba.conf, the lines in this file can be include directives, following the same rules. + + + The pg_ident.conf file is read on start-up and + when the main server process receives a + SIGHUPSIGHUP + 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. + + + + The system view + pg_ident_file_mappings + can be helpful for pre-testing changes to the + pg_ident.conf file, or for diagnosing problems if + loading of the file did not have the desired effects. Rows in the view with + non-null error fields indicate problems in the + corresponding lines of the file. + + 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 - - The pg_ident.conf file is read on start-up and - when the main server process receives a - SIGHUPSIGHUP - 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. - - - - The system view - pg_ident_file_mappings - can be helpful for pre-testing changes to the - pg_ident.conf file, or for diagnosing problems if - loading of the file did not have the desired effects. Rows in the view with - non-null error fields indicate problems in the - corresponding lines of the file. - - A pg_ident.conf file that could be used in conjunction with the pg_hba.conf file in