From 26b7c255de3c9aa53b66c88a3a69e31f011f7dca Mon Sep 17 00:00:00 2001
From: Bo Peng <pengbo@sraoss.co.jp>
Date: Tue, 11 Jul 2023 15:10:20 +0900
Subject: [PATCH] Doc: Enhance SSH public key authentication setting section in
 "8.2. Pgpool-II + Watchdog Setup Example".

---
 doc.ja/src/sgml/example-cluster.sgml | 52 ++++++++++++++++++--
 doc/src/sgml/example-cluster.sgml    | 71 ++++++++++++++++++++++++----
 2 files changed, 111 insertions(+), 12 deletions(-)

diff --git a/doc.ja/src/sgml/example-cluster.sgml b/doc.ja/src/sgml/example-cluster.sgml
index d726327ef..3f3372fff 100644
--- a/doc.ja/src/sgml/example-cluster.sgml
+++ b/doc.ja/src/sgml/example-cluster.sgml
@@ -402,7 +402,17 @@ host    replication     all             samenet                 scram-sha-256
 
    <listitem>
     <para>
-     自動フェイルオーバ、オンラインリカバリ機能を利用するには、<productname>Pgpool-II</productname>起動ユーザ(デフォルトでは<literal>root</literal>)と<literal>postgres</literal>ユーザ間、<literal>postgres</literal>ユーザと<literal>postgres</literal>ユーザ間が双方向に<emphasis>パスワードなし</emphasis>で<literal>SSH</literal>接続できる状態になっている必要があります。全サーバで以下のコマンドを実行し、<literal>SSH</literal>の設定を行います。生成される鍵ファイル名は<literal>id_rsa_pgpool</literal>とします。
+     自動フェイルオーバ、オンラインリカバリ機能を利用するには、すべての<productname>Pgpool-II</productname>ノード間で<productname>Pgpool-II</productname>の起動ユーザ（デフォルトは<literal>postgres</literal>ユーザ。Pgpool-II 4.0以前、デフォルトは<literal>root</literal>ユーザ）および<productname>PostgreSQL</productname>の起動ユーザ（デフォルトは<literal>postgres</literal>ユーザ）として双方向にSSH公開鍵認証（パスワードなし）で接続できるように設定する必要があります。 
+    </para>
+    <para>
+     まず、全サーバで<literal>postgres</literal>ユーザのパスワードを設定します。
+    </para>
+    <programlisting>
+[全サーバ]# passwd postgres
+    </programlisting>
+    <para>
+     全サーバで以下のコマンドを実行し、SSH公開鍵の登録を行います。
+     この設定例では生成される鍵ファイル名は<literal>id_rsa_pgpool</literal>とします。
     </para>
     <programlisting>
 [全サーバ]# mkdir ~/.ssh
@@ -423,9 +433,45 @@ host    replication     all             samenet                 scram-sha-256
 [全サーバ]$ ssh-copy-id -i id_rsa_pgpool.pub postgres@server3
     </programlisting>
     <para>
-     設定後、<literal>root</literal>ユーザ及び<literal>postgres</literal>ユーザから<command>ssh postgres@serverX -i ~/.ssh/id_rsa_pgpool</command>コマンドを実行し、パスワード入力せずログインできることを確認してください。
-     <command>ssh-copy-id</command>の実行に失敗する場合は、<literal>postgres</literal> ユーザのパスワードを設定し、一時的にパスワード認証を有効化するなどしてください。
+     設定後、<productname>Pgpool-II</productname>の起動ユーザでおよび<productname>PostgreSQL</productname>の起動ユーザで<command>ssh postgres@serverX -i ~/.ssh/id_rsa_pgpool</command>コマンドを実行し、パスワード入力せずログインできることを確認してください。
     </para>
+
+    <note>
+     <para>
+      公開鍵認証によるログインに失敗した場合には、以下を確認してください。
+      <itemizedlist>
+       <listitem>
+        <para>
+         <filename>/etc/ssh/sshd_config</filename>で公開鍵認証が許可されていることを確認します。
+        </para>
+       </listitem>
+      </itemizedlist>
+      <programlisting>
+PubkeyAuthentication yes
+      </programlisting>
+      <itemizedlist>
+       <listitem>
+        <para>
+         SSHのパスワード認証を無効化している場合は、ssh-copy-idの実行に失敗するので、一時的に<filename>/etc/ssh/sshd_config</filename>内のPasswordAuthenticationをyesに変更するなどしてください。
+        </para>
+       </listitem>
+      </itemizedlist>
+      <programlisting>
+PasswordAuthentication yes
+      </programlisting>
+      <itemizedlist>
+       <listitem>
+        <para>
+         SELinuxを有効化している場合は、SSH公開鍵認証(パスワードなし)が失敗する可能性があるので、すべてのサーバで以下のコマンドを実行する必要があります。
+        </para>
+       </listitem>
+      </itemizedlist>
+      <programlisting>
+[全サーバ]# su - postgres
+[全サーバ]$ restorecon -Rv ~/.ssh
+      </programlisting>
+     </para>
+    </note>
    </listitem>
 
    <listitem>
diff --git a/doc/src/sgml/example-cluster.sgml b/doc/src/sgml/example-cluster.sgml
index 87af178fe..034422de0 100644
--- a/doc/src/sgml/example-cluster.sgml
+++ b/doc/src/sgml/example-cluster.sgml
@@ -409,11 +409,23 @@ host    replication     all             samenet                 scram-sha-256
    <listitem>
     <para>
      To use the automated failover and online recovery of <productname>Pgpool-II</productname>, 
-     the settings that allow <emphasis>passwordless</emphasis> SSH to all backend servers
-     between <productname>Pgpool-II</productname> execution user (default root user)
-     and <literal>postgres</literal> user and between <literal>postgres</literal> user
-     and <literal>postgres</literal> user are necessary. Execute the following command on all servers
-     to set up passwordless <literal>SSH</literal>. The generated key file name is <literal>id_rsa_pgpool</literal>.
+     it is requried to allow <emphasis>SSH public key authentication
+     (passwordless SSH login)</emphasis> to all backend servers
+     as <productname>Pgpool-II</productname> startup user
+     (default is <literal>postgres</literal>. Pgpool-II 4.0 or before, default is <literal>root</literal>)
+     and <productname>PostgreSQL</productname> startup user (default is <literal>postgres</literal>).
+    </para>
+    <para>
+     First, set <literal>postgres</literal> user's passwrod.
+    </para>
+    <programlisting>
+[all servers]# passwd postgres
+    </programlisting>
+    <para>
+     Execute the following command on all servers
+     to set up passwordless <literal>SSH</literal>.
+     In this example, we assume that the generated key file name is
+     <literal>id_rsa_pgpool</literal>.
     </para>
     <programlisting>
 [all servers]# mkdir ~/.ssh
@@ -434,11 +446,52 @@ host    replication     all             samenet                 scram-sha-256
 [all servers]$ ssh-copy-id -i id_rsa_pgpool.pub postgres@server3
     </programlisting>
     <para>
-     After setting, use <command>ssh postgres@serverX -i ~/.ssh/id_rsa_pgpool</command> command to
-     make sure that you can log in without entering a password. If you fail
-     executing <command>ssh-copy-id</command>, set a password for <literal>postgres</literal> user
-     and temporarily allow password authentication for example.
+     After setting SSH, make sure that you can run
+     <command>ssh postgres@serverX -i ~/.ssh/id_rsa_pgpool</command> command
+     as <productname>Pgpool-II</productname> startup user and
+     <productname>PostgreSQL</productname> startup user to
+     log in without entering a password. 
     </para>
+
+    <note>
+     <para>
+      If you failed to login using SSH public key authentication, please check the following:
+      <itemizedlist>
+       <listitem>
+        <para>
+         Ensure the public key authentication option <literal>PubkeyAuthentication</literal> are allowed in <filename>/etc/ssh/sshd_config</filename>:
+        </para>
+       </listitem>
+      </itemizedlist>
+      <programlisting>
+PubkeyAuthentication yes
+      </programlisting>
+      <itemizedlist>
+       <listitem>
+        <para>
+         if the password authentication is disabled, you can fail to run
+         <command>ssh-copy-id</command>, temporarily add the following
+         configuration in <filename>/etc/ssh/sshd_config</filename>.
+        </para>
+       </listitem>
+      </itemizedlist>
+      <programlisting>
+PasswordAuthentication yes
+      </programlisting>
+      <itemizedlist>
+       <listitem>
+        <para>
+         If SELinux is enabled, SSH public key authentication (passwordless SSH) may fail.
+         You need to run the following command on all servers.
+        </para>
+       </listitem>
+      </itemizedlist>
+      <programlisting>
+[all servers]# su - postgres
+[all servers]$ restorecon -Rv ~/.ssh
+      </programlisting>
+     </para>
+    </note>
    </listitem>
 
    <listitem>
-- 
2.39.5