From f8b3352fbc438581e13ed02e4d93559b4d2016c4 Mon Sep 17 00:00:00 2001
From: Tatsuo Ishii <ishii@postgresql.org>
Date: Fri, 17 Jan 2025 14:22:05 +0900
Subject: [PATCH] Doc: enhance client authentication chapter.

Add intro about pool_passwd. Previously there was only description on
pool_hba.conf in the overview page. A general guide to pool_passwd
will help users to understand this chapter.
---
 doc.ja/src/sgml/client-auth.sgml |  4 ++++
 doc/src/sgml/client-auth.sgml    | 20 ++++++++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/doc.ja/src/sgml/client-auth.sgml b/doc.ja/src/sgml/client-auth.sgml
index ab5bde966..996cc9f07 100644
--- a/doc.ja/src/sgml/client-auth.sgml
+++ b/doc.ja/src/sgml/client-auth.sgml
@@ -36,6 +36,10 @@
   このため、クライアントホストに基づく認証のため、<productname>Pgpool-II</productname>は<literal>pg_hba</literal>と同様にクライアント接続の認証処理を行う<literal>pool_hba</literal>のメカニズムを持っています。
  </para>
 
+ <para>
+  クライアントが<productname>Pgpool-II</productname>に接続する際の認証用のパスワードを管理するのが<filename>pool_passwd</filename>ファイルです（詳細は<xref linkend="guc-pool-passwd">をご覧ください。)<filename>pool_passwd</filename>に登録されるパスワードは、<productname>PostgreSQL</productname>に登録されるパスワードと一致している必要があります。<productname>PostgreSQL</productname>に登録されたパスワードを変更しても、<filename>pool_passwd</filename>のパスワードは自動変更されないことに注意してください。<link linkend="auth-scram">scram-shar-256認証</link>と<link linkend="auth-md5">MD5認証</link>では、<filename>pool_passwd</filename>にユーザ名とパスワードを登録するのが必須ですが、<link linkend="auth-password">clear text password認証</link>では必須ではありません。このため、<filename>pool_passwd</filename>のパスワードの保守を避けたい場合には、<link linkend="auth-password">clear text password認証</link>の検討をお勧めします。
+ </para>
+
  <sect1 id="auth-pool-hba-conf">
   <!--
   <title>The <filename>pool_hba.conf</filename> File</title>
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 6441be083..5096c8718 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -30,6 +30,26 @@
   <literal>pool_hba</literal> mechanism similar to the <literal>pg_hba</literal> mechanism for
   authenticating the incoming client connections.
  </para>
+ <para>
+  The <filename>pool_passwd</filename> file manages passwords for
+  authentication used when clients connect
+  to <productname>Pgpool-II</productname>
+  (see <xref linkend="guc-pool-passwd"> for more details). The
+  passwords registered on <filename>pool_passwd</filename> must match
+  with the passwords registered
+  on <productname>PostgreSQL</productname>. Note that passwords
+  changed on <productname>PostgreSQL</productname> are not
+  automatically sync to the passwords
+  on <filename>pool_passwd</filename>. <link linkend="auth-scram">scram-shar-256
+  authentication</link> and <link linkend="auth-md5">MD5
+  authentication</link> require that the user name and the password
+  have been already registered on <filename>pool_passwd</filename>,
+  while <link linkend="auth-password">clear text password
+  authentication</link> does not require that. Therefore, if you want
+  to avoid maintaining the <filename>pool_passwd</filename>, it would
+  be worth to check <link linkend="auth-password">clear text password
+  authentication</link>.
+ </para>
 
  <sect1 id="auth-pool-hba-conf">
   <title>The <filename>pool_hba.conf</filename> File</title>
-- 
2.39.5