pgpool2.git / summary / log / commit / refs
commit 69c6a4cd5f49384a1d719e4e784ff84855f00a9d
Author: Bo Peng <pengbo@sraoss.co.jp>
Date: Thu Aug 08 06:35:36 2019 +0000
Doc: Update "Pgpool-II + Watchdog Setup Example" configuration example.
doc.ja/src/sgml/example-AWS.sgml | 398 +++++
doc.ja/src/sgml/example-Aurora.sgml | 148 ++
doc.ja/src/sgml/example-basic.sgml | 533 ++++++
doc.ja/src/sgml/example-cluster.sgml | 1495 +++++++++++++++++
doc.ja/src/sgml/example-watchdog.sgml | 501 ++++++
doc.ja/src/sgml/examples.sgml | 2884 +--------------------------------
doc.ja/src/sgml/filelist.sgml | 5 +
doc/src/sgml/example-AWS.sgml | 305 ++++
doc/src/sgml/example-Aurora.sgml | 95 ++
doc/src/sgml/example-basic.sgml | 349 ++++
doc/src/sgml/example-cluster.sgml | 1572 ++++++++++++++++++
doc/src/sgml/example-watchdog.sgml | 354 ++++
doc/src/sgml/examples.sgml | 2458 +---------------------------
doc/src/sgml/filelist.sgml | 7 +-
14 files changed, 5793 insertions(+), 5311 deletions(-)
diff --git a/doc.ja/src/sgml/example-AWS.sgml b/doc.ja/src/sgml/example-AWS.sgml
new file mode 100644
index 000000000..1da109669
--- /dev/null
+++ b/doc.ja/src/sgml/example-AWS.sgml
@@ -0,0 +1,398 @@
+<!-- doc/src/sgml/example-AWS.sgml -->
+
+<sect1 id="example-AWS">
+<!--
+ <title>AWS Configuration Example</title>
+-->
+ <title>AWS設定の例</title>
+
+<para>
+<!--
+ This tutorial explains the simple way to try "Watchdog"
+ on <ulink url="https://aws.amazon.com/">AWS</ulink> and using
+ the <ulink url="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html">
+ Elastic IP Address</ulink> as the Virtual IP for the high availability solution.
+ <note>
+ <para>
+ You can use watchdog with <productname>
+ Pgpool-II</productname> in any mode: replication mode,
+ master/slave mode and raw mode.
+ </para>
+ </note>
+-->
+このチュートリアルでは、<ulink url="https://aws.amazon.com/">AWS</ulink>上で"Watchdog"を使う簡単な例を示します。
+この例では、高可用性のために<ulink url="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html">Elastic IP Address</ulink>を仮想IPとして使います。
+ <note>
+ <para>
+ watchdogは、<productname>Pgpool-II</productname>のすべてのモード、すなわちレプリケーションモード、マスタ／スレーブモード、ローモードのいずれでも使えます。
+ </para>
+ </note>
+</para>
+
+ <sect2 id="example-AWS-setup">
+<!--
+ <title>AWS Setup</title>
+-->
+ <title>AWSのセットアップ</title>
+ <para>
+<!--
+ For this example, we will use two node <productname>
+ Pgpool-II</productname> watchdog cluster. So we will set up two
+ Linux Amazon EC2 instances and one Elastic IP address.
+ So for this example, do the following steps:
+-->
+この例では、2ノードの<productname>Pgpool-II</productname> watchdogクラスタを使います。
+そこで、2つのAmazon Linux EC2インスタンスを設定し、ひとつのElastic IPアドレスを使用します。
+以下のステップを実施してください。
+ </para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+<!--
+ Launch two Linux Amazon EC2 instances. For this example, we name these
+ instances as "instance-1" and "instance-2"
+-->
+Amazon Linux EC2インスタンスを2つ起動します。
+この例では、それぞれ"instance-1"と"instance-2"という名前を付けます。
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+<!--
+ Configure the security group for the instances and allow inbound traffic
+ on ports used by pgpool-II and watchdog.
+-->
+これらのインスタンスのセキュリティグループを設定し、Pgpool-IIとwatchdogが使用するポートへのインバウンドトラフィックを許可します。
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+<!--
+ Install the <productname>Pgpool-II</productname> on both instances.
+-->
+<productname>Pgpool-II</productname>を両方のインスタンスにインストールします。
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+<!--
+ Allocate an Elastic IP address.
+ For this example, we will use "35.163.178.3" as an Elastic IP address"
+-->
+Elastic IPアドレスを確保します。
+この例では、Elastic IPアドレスに"35.163.178.3"を設定します。
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+</sect2>
+
+ <sect2 id="example-AWS-pgpool-config">
+<!--
+ <title><productname>Pgpool-II</productname> configurations</title>
+-->
+ <title><productname>Pgpool-II</productname>の設定</title>
+ <para>
+<!--
+ Mostly the <productname>Pgpool-II</productname> configurations for this
+ example will be same as in the <xref linkend="example-watchdog">, except the
+ <xref linkend="guc-delegate-ip"> which we will not set in this example instead
+ we will use <xref linkend="guc-wd-escalation-command"> and
+ <xref linkend="guc-wd-de-escalation-command"> to switch the
+ Elastic IP address to the master/Active <productname>Pgpool-II</productname> node.
+-->
+この例の設定は<xref linkend="example-watchdog">とほとんど同じになりますが、<xref linkend="guc-delegate-ip">を設定せず、代わりに<xref linkend="guc-wd-escalation-command">と<xref linkend="guc-wd-de-escalation-command">を使ってmaster/Active <productname>Pgpool-II</productname>ノードのElastic IPアドレスを切り替えるのが異なります。
+ </para>
+
+ <sect3 id="example-AWS-pgpool-config-instance-1">
+<!--
+ <title><productname>Pgpool-II</productname> configurations on Instance-1</title>
+-->
+ <title>Instance-1における<productname>Pgpool-II</productname>の設定</title>
+ <para>
+
+ <programlisting>
+use_watchdog = on
+delegate_IP = ''
+wd_hostname = 'instance-1-private-ip'
+other_pgpool_hostname0 = 'instance-2-private-ip'
+other_pgpool_port0 = 9999
+other_wd_port0 = 9000
+wd_escalation_command = '$path_to_script/aws-escalation.sh'
+wd_de_escalation_command = '$path_to_script/aws-de-escalation.sh'
+ </programlisting>
+
+ </para>
+ </sect3>
+
+ <sect3 id="example-AWS-pgpool-config-instance-2">
+<!--
+ <title><productname>Pgpool-II</productname> configurations on Instance-2</title>
+-->
+ <title>Instance-2における<productname>Pgpool-II</productname>の設定</title>
+ <para>
+
+ <programlisting>
+use_watchdog = on
+delegate_IP = ''
+wd_hostname = 'instance-2-private-ip'
+other_pgpool_hostname0 = 'instance-1-private-ip'
+other_pgpool_port0 = 9999
+other_wd_port0 = 9000
+wd_escalation_command = '$path_to_script/aws-escalation.sh'
+wd_de_escalation_command = '$path_to_script/aws-de-escalation.sh'
+ </programlisting>
+
+ </para>
+ </sect3>
+</sect2>
+
+<sect2 id="example-AWS-pgpool-aws-escalation-instance">
+<!--
+<title>escalation and de-escalation Scripts</title>
+-->
+<title>エスカレーションおよびディエスカレーション用のスクリプト</title>
+ <para>
+<!--
+ Create the aws-escalation.sh and aws-de-escalation.sh scripts on both
+ instances and point the <xref linkend="guc-wd-escalation-command"> and
+ <xref linkend="guc-wd-de-escalation-command"> to the respective scripts.
+-->
+aws-escalation.shとaws-de-escalation.shスクリプトを2つのインスタンス上に作成し、<xref linkend="guc-wd-escalation-command">と<xref linkend="guc-wd-de-escalation-command">がそれぞれそれらを指すようにしてください。
+ </para>
+
+ <note>
+ <para>
+<!--
+ You may need to configure the AWS CLI first on all AWS instances
+ to enable the execution of commands used by wd-escalation.sh and wd-de-escalation.sh.
+ See <ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">configure AWS CLI</ulink>
+-->
+AWSインスタンス上でwd-escalation.shとwd-de-escalation.shで使用するコマンドが実行できるようにするために、AWS CLIの設定が必要になるかもしれません。
+<ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">configure AWS CLI</ulink>を参照してください。
+ </para>
+ </note>
+
+ <sect3 id="example-AWS-pgpool-aws-escalation-script">
+<!--
+ <title>escalation script</title>
+-->
+ <title>エスカレーションスクリプト</title>
+
+ <para>
+<!--
+ This script will be executed by the watchdog
+ to assign the Elastic IP on the instance when the watchdog becomes the active/master node.
+ Change the INSTANCE_ID and ELASTIC_IP values as per your AWS setup values.
+-->
+このスクリプトは、watchdogがactive/masterノードになったときに、Elastic IPをアサインするためにwatchdogが実行します。
+ </para>
+ <para>
+ <emphasis>aws-escalation.sh:</emphasis>
+ <programlisting>
+#! /bin/sh
+
+ELASTIC_IP=35.163.178.3
+ # replace it with the Elastic IP address you
+ # allocated from the aws console
+INSTANCE_ID=i-0a9b64e449b17ed4b
+ # replace it with the instance id of the Instance
+ # this script is installed on
+
+echo "Assigning Elastic IP $ELASTIC_IP to the instance $INSTANCE_ID"
+# bring up the Elastic IP
+aws ec2 associate-address --instance-id $INSTANCE_ID --public-ip $ELASTIC_IP
+
+exit 0
+ </programlisting>
+
+ </para>
+
+ </sect3>
+ <sect3 id="example-AWS-pgpool-aws-de-escalation-script">
+<!--
+ <title>de-escalation script</title>
+-->
+ <title>ディエスカレーションスクリプト</title>
+ <para>
+<!--
+ This script will be executed by watchdog
+ to remove the Elastic IP from the instance when the watchdog resign from the active/master node.
+-->
+このスクリプトは、watchdogがactive/masterノードを退任するときに、Elastic IPのアサインを解除するためにwatchdogが実行します。
+ </para>
+ <para>
+ <emphasis>aws-de-escalation.sh:</emphasis>
+ <programlisting>
+#! /bin/sh
+
+ELASTIC_IP=35.163.178.3
+ # replace it with the Elastic IP address you
+ # allocated from the aws console
+
+echo "disassociating the Elastic IP $ELASTIC_IP from the instance"
+# bring down the Elastic IP
+aws ec2 disassociate-address --public-ip $ELASTIC_IP
+exit 0
+ </programlisting>
+ </para>
+ </sect3>
+
+ <bibliography>
+<!--
+ <title>AWS Command References</title>
+-->
+ <title>AWSコマンドリファレンス</title>
+
+ <biblioentry>
+ <biblioset relation="article">
+ <title><ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">Configure AWS CLI</ulink></title>
+ </biblioset>
+ <biblioset relation="book">
+ <title>AWS Documentation: Configuring the AWS Command Line Interface</title>
+ </biblioset>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioset relation="article">
+ <title><ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/associate-address.html">associate-address</ulink></title>
+ </biblioset>
+ <biblioset relation="book">
+ <title>AWS Documentation: associate-address reference</title>
+ </biblioset>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioset relation="article">
+ <title><ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/disassociate-address.html">disassociate-address</ulink></title>
+ </biblioset>
+ <biblioset relation="book">
+ <title>AWS Documentation: disassociate-address reference</title>
+ </biblioset>
+ </biblioentry>
+
+ </bibliography>
+</sect2>
+
+<sect2 id="example-AWS-try">
+<!--
+ <title>Try it out</title>
+-->
+ <title>実行してみる</title>
+ <para>
+<!--
+ Start <productname>Pgpool-II</productname> on each server with "-n" switch
+ and redirect log messages to the pgpool.log file.
+ The log message of master/active <productname>Pgpool-II</productname> node
+ will show the message of Elastic IP assignment.
+-->
+それぞれのサーバ上で<productname>Pgpool-II</productname>を"-n"スイッチ付きで起動し、pgpool.logにログメッセージをリダイレクトします。
+master/active <productname>Pgpool-II</productname>ノードは、Elastic IPのアサインメッセージを表示します。
+ <programlisting>
+LOG: I am the cluster leader node. Starting escalation process
+LOG: escalation process started with PID:23543
+LOG: watchdog: escalation started
+<emphasis>
+Assigning Elastic IP 35.163.178.3 to the instance i-0a9b64e449b17ed4b
+{
+"AssociationId": "eipassoc-39853c42"
+}
+</emphasis>
+LOG: watchdog escalation successful
+LOG: watchdog escalation process with pid: 23543 exit with SUCCESS.
+ </programlisting>
+ </para>
+
+ <para>
+<!--
+ Confirm to ping to the Elastic IP address.
+-->
+Elastic IPアドレスにpingが通ることを確かめます。
+ <programlisting>
+[user@someserver]$ ping 35.163.178.3
+PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
+64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
+64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
+64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
+ </programlisting>
+ </para>
+
+ <para>
+<!--
+ Try to connect <productname>PostgreSQL</> by "psql -h ELASTIC_IP -p port".
+-->
+"psql -h ELASTIC_IP -p port"で<productname>PostgreSQL</>に接続してみます。
+ <programlisting>
+[user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
+ </programlisting>
+ </para>
+</sect2>
+
+<sect2 id="example-AWS-vip-switch">
+<!--
+ <title>Switching Elastic IP</title>
+-->
+ <title>Elastic IPの切換</title>
+ <para>
+<!--
+ To confirm if the Standby server acquires the Elastic IP when the
+ Active server becomes unavailable, Stop the <productname>Pgpool-II</productname>
+ on the Active server. Then, the Standby server should start using the Elastic IP address,
+ And the <productname>Pgpool-II</productname> log will show the below messages.
+-->
+アクティブなサーバが使用できなくなった時にスタンバイサーバがElastic IPを獲得できることを確認するために、アクティブサーバ上の<productname>Pgpool-II</productname>を停止します。
+すると、スタンバイサーバはElastic IPアドレスを使い始めるはずです。
+<productname>Pgpool-II</productname>のログには以下のようなメッセージが表示されます。
+ <programlisting>
+<emphasis>
+LOG: remote node "172.31.2.94:9999 [Linux ip-172-31-2-94]" is shutting down
+LOG: watchdog cluster has lost the coordinator node
+</emphasis>
+LOG: watchdog node state changed from [STANDBY] to [JOINING]
+LOG: watchdog node state changed from [JOINING] to [INITIALIZING]
+LOG: I am the only alive node in the watchdog cluster
+HINT: skipping stand for coordinator state
+LOG: watchdog node state changed from [INITIALIZING] to [MASTER]
+LOG: I am announcing my self as master/coordinator watchdog node
+LOG: I am the cluster leader node
+DETAIL: our declare coordinator message is accepted by all nodes
+LOG: I am the cluster leader node. Starting escalation process
+LOG: escalation process started with PID:23543
+LOG: watchdog: escalation started
+<emphasis>
+Assigning Elastic IP 35.163.178.3 to the instance i-0dd3e60734a6ebe14
+{
+"AssociationId": "eipassoc-39853c42"
+}
+</emphasis>
+LOG: watchdog escalation successful
+LOG: watchdog escalation process with pid: 61581 exit with SUCCESS.
+ </programlisting>
+<!--
+ Confirm to ping to the Elastic IP address again.
+-->
+Elastic IPアドレスにpingが通ることを再度確かめます。
+ <programlisting>
+[user@someserver]$ ping 35.163.178.3
+PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
+64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
+64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
+64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
+ </programlisting>
+ </para>
+ <para>
+<!--
+ Try to connect <productname>PostgreSQL</> by "psql -h ELASTIC_IP -p port".
+-->
+"psql -h ELASTIC_IP -p port"で<productname>PostgreSQL</>に接続してみます。
+ <programlisting>
+[user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
+ </programlisting>
+ </para>
+</sect2>
+</sect1>
diff --git a/doc.ja/src/sgml/example-Aurora.sgml b/doc.ja/src/sgml/example-Aurora.sgml
new file mode 100644
index 000000000..f1b330222
--- /dev/null
+++ b/doc.ja/src/sgml/example-Aurora.sgml
@@ -0,0 +1,148 @@
+<!-- doc/src/sgml/example-Aurora.sgml -->
+
+<sect1 id="example-Aurora">
+ <!--
+ <title>Aurora Configuration Example</title>
+ -->
+ <title>Auroraの設定例</title>
+
+ <para>
+<!--
+<productname>Amazon Aurora for PostgreSQL
+Compatibility</productname> (Aurora) is a managed service for
+<productname>PostgreSQL</productname>. From user's point of
+view, <productname>Aurora</productname> can be regarded as a
+streaming replication cluster with some exceptions. First,
+fail over and online recovery are managed
+by <productname>Aurora</productname>. So you don't need to
+set <xref linkend="guc-failover-command">, <xref linkend="guc-follow-master-command">,
+and recovery related parameters. In this section we explain
+how to set up <productname>Pgpool-II</productname> for Aurora.
+-->
+<productname>Amazon Aurora for PostgreSQL
+Compatibility</productname> (Aurora) は、<productname>PostgreSQL</productname>用のマネージドサービスです。
+ユーザから見ると、<productname>Aurora</productname>は、いくつか例外があるものの、ストリーミングレプリケーションのクラスタのように見えます。フェイルオーバやオンラインリカバリは<productname>Aurora</productname>によって管理されます。
+ですから、<xref linkend="guc-failover-command">、<xref linkend="guc-follow-master-command">、
+ それにオンラインリカバリ関連のパラメータは設定の必要がありません。
+ この章では、Aurora用の<productname>Pgpool-II</productname>設定を説明します。
+ </para>
+
+ <sect2 id="example-Aurora-config">
+<!--
+<title>Setting pgpool.conf for Aurora</title>
+-->
+<title>Auroraのためにpgpool.confを設定する</title>
+<para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <!--
+ Create <filename>pgpool.conf</filename>
+ from <filename>pgpool.conf.sample-stream</filename>.
+ -->
+ <filename>pgpool.conf.sample-stream</filename>をコピーして<filename>pgpool.conf</filename>を作ります。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <!--
+ Set <xref linkend="guc-sr-check-period"> to 0 to
+ disable streaming replication delay checking. This
+ is because <productname>Aurora</productname> does
+ not provide neccessary functions to check the
+ replication delay.
+ -->
+ <xref linkend="guc-sr-check-period">を0にして、ストリーミングレプリケーション遅延チェックを無効にします。
+ <productname>Aurora</productname>では、ストリーミングレプリケーションの遅延をチェックするための関数が提供されないためです。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <!--
+ Enable <xref linkend="guc-enable-pool-hba"> to on so
+ that md5 authentication is enabled
+ (<productname>Aurora</productname> always use md5
+ authentication).
+ -->
+ <xref linkend="guc-enable-pool-hba">をオンにし、md5認証を有効にします。
+ （<productname>Aurora</productname>では常にmd5認証が有効になっています)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <!--
+ Create <filename>pool_password</filename>. See <xref linkend="auth-md5">
+ for more details.
+ -->
+ <filename>pool_password</filename>を作成します。
+ 詳細は<xref linkend="auth-md5">をご覧ください。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <!--
+ Set <xref linkend="guc-backend-hostname">0 for the
+ Aurora writer node. Set
+ other <xref linkend="guc-backend-hostname"> for the
+ Aurora reader node. Set
+ appropreate <xref linkend="guc-backend-weight"> as
+ usual. You don't need to
+ set <xref linkend="guc-backend-data-directory">
+ -->
+ <xref linkend="guc-backend-hostname">0をAuroraのwriterノードに設定します。
+ 他の<xref linkend="guc-backend-hostname">はAuroraのreaderノードに設定します。
+ <xref linkend="guc-backend-data-directory">は設定の必要がありません。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <!--
+ Set <varname>ALWAYS_MASTER</varname> flag to
+ the <xref linkend="guc-backend-flag"> for the master
+ node.
+ -->
+ <xref linkend="guc-backend-hostname">0の<xref linkend="guc-backend-flag">の<varname>ALWAYS_MASTER</varname>をオンにします。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <!--
+ Enable health checking.
+ Set <xref linkend="guc-health-check-period"> to 5.
+ Set <xref linkend="guc-health-check-user">, <xref linkend="guc-health-check-password">,
+ <xref linkend="guc-health-check-user"> and
+ <xref linkend="guc-health-check-database"> to appropriate values.
+ Enable health check retry.
+ <productname>Aurora</productname> shutdowns all DB nodes while switching
+ over or failover. If the retry is not performed,
+ <productname>Pgpool-II</productname> thinks that all DB nodes are in down status
+ so that it is required to restart <productname>Pgpool-II</productname>.
+ Set <xref linkend="guc-health-check-max-retries"> to 20.
+ Set <xref linkend="guc-health-check-retry-delay"> to 1 to avoid the problem.
+ -->
+ ヘルスチェックを有効にします。
+ <xref linkend="guc-health-check-period">に5を設定します.
+ <xref linkend="guc-health-check-user">、<xref linkend="guc-health-check-password">、
+ <xref linkend="guc-health-check-user">、<xref linkend="guc-health-check-database">
+ に適切な値を設定します。
+ リトライを設定します。
+ <productname>Aurora</productname>は、スィッチングオーバやフェイルオーバの際に、一時的に全DBノードを停止します。
+ リトライを行わないと、<productname>Pgpool-II</productname>から見ると全DBノードがダウン状態になり、<productname>Pgpool-II</productname>の再起動が必要になります。
+ <xref linkend="guc-health-check-max-retries">を20に、<xref linkend="guc-health-check-retry-delay">を1にして、そのような問題を回避してください。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <!--
+ Disable <xref linkend="guc-failover-on-backend-error">
+ to avoid failover when connecting to the backend or
+ detecting errors on backend side while executing
+ queries for the same reasons above.
+ -->
+同様の理由により、接続時あるいは問い合わせ実行中のエラーによるフェイルオーバを避けるために、<xref linkend="guc-failover-on-backend-error">をオフにしてください。
+ </para>
+ </listitem>
+ </itemizedlist>
+</para>
+ </sect2>
+</sect1>
diff --git a/doc.ja/src/sgml/example-basic.sgml b/doc.ja/src/sgml/example-basic.sgml
new file mode 100644
index 000000000..a81fa8752
--- /dev/null
+++ b/doc.ja/src/sgml/example-basic.sgml
@@ -0,0 +1,533 @@
+<!-- doc/src/sgml/example-basic.sgml -->
+
+<sect1 id="example-basic">
+<!--
+<title>Basic Configuration Example</title>
+-->
+<title>基本設定の例</title>
+
+ <sect2 id="example-configs-begin">
+<!--
+ <title>Let's Begin!</title>
+-->
+ <title>さあ始めましょう</title>
+ <para>
+<!--
+ First, we must learn how to install and configure <productname>Pgpool-II</productname> and database nodes before using replication.
+-->
+ここでは、レプリケーションを行うための準備として、<productname>Pgpool-II</productname> のインストールや設定、データベースノードの準備について説明します。
+ </para>
+
+ <sect3 id="example-configs-begin-installing">
+<!--
+ <title>Installing <productname>Pgpool-II</productname></title>
+-->
+ <title><productname>Pgpool-II</productname>のインストール</title>
+ <para>
+<!--
+ Installing <productname>Pgpool-II</productname> is very easy.
+ In the directory which you have extracted the source tar ball,
+ execute the following commands.
+-->
+<productname>Pgpool-II</productname>のインストールはとても簡単です。
+ソースのtar ballを展開したディレクトリで以下のようにコマンドを実行します。
+ <programlisting>
+$ ./configure
+$ make
+$ make install
+ </programlisting>
+<!--
+ <command>configure</command> script collects your system information
+ and use it for the compilation procedure. You can pass command
+ line arguments to <command>configure</> script to change the default behavior,
+ such as the installation directory. <productname>Pgpool-II</productname>
+ will be installed to <literal>/usr/local</literal> directory by default.
+-->
+<link linkend="INSTALL-PGPOOL"><command>configure</command>スクリプト</link>はシステム情報を収集しコンパイル処理に利用します。
+<command>configure</>スクリプトにコマンドライン引数を指定することにより、インストール先ディレクトリなど、デフォルトの動作を変更することができます。
+デフォルトでは<productname>Pgpool-II</> は<literal>/usr/local</literal>ディレクトリ以下にインストールされます。
+ </para>
+ <para>
+<!--
+ <command>make</command> command compiles the source code, and
+ <command>make install</command> will install the executables.
+ You must have write permission on the installation directory.
+ In this tutorial, we will install <productname>Pgpool-II
+ </productname> in the default <literal>/usr/local</literal> directory.
+-->
+<command>make</command>コマンドはソースコードはコンパイルし、<command>make install</command>コマンドで実行可能ファイルがインストールされます。
+インストール先ディレクトリに書き込み権限を持っている必要があります。
+ここでは、<productname>Pgpool-II</productname>は<literal>/usr/local</literal>にインストールすることにします。
+ </para>
+ <note>
+ <para>
+<!--
+ <productname>Pgpool-II</productname> requires <literal>libpq</literal>
+ library in <productname>PostgreSQL</> 7.4 or later (version 3 protocol).
+-->
+<productname>Pgpool-II</>は<productname>PostgreSQL</> 7.4 以降の<literal>libpq</literal>ライブラリ(3.0 プロトコル)を必要とします。
+ </para>
+ </note>
+ <para>
+<!--
+ If the <command>configure</command> script displays the following error message, the
+ <literal>libpq</literal> library may not be installed, or it is not of version 3
+-->
+<command>configure</command>スクリプトが以下のエラーメッセージを表示した場合、<literal>libpq</literal>ライブラリがインストールされていないか、バージョンが3.0でない可能性があります。
+ <programlisting>
+configure: error: libpq is not installed or libpq is old
+ </programlisting>
+<!--
+ If the library is version 3, but the above message is still displayed, your
+ <literal>libpq</literal> library is probably not recognized by the <command>
+ configure</command> script.
+ The <command>configure</command> script searches for <literal>libpq</literal>
+ library under <literal>/usr/local/pgsql</literal>. If you have installed the
+ <productname>PostgreSQL</> in a directory other than <literal>/usr/local/pgsql</literal>, use
+ <literal>--with-pgsql</literal>, or <literal>--with-pgsql-includedir</literal>
+ and <literal>--with-pgsql-libdir</literal> command line options when you
+ execute <command>configure</command>.
+-->
+プロトコルのバージョンが3.0の<literal>libpq</literal>ライブラリがインストールされているにも係わらず上記のエラーメッセージが表示される場合、<command>configure</command>スクリプトに<literal>libpq</literal>ライブラリが認識されていない可能性があります。
+<command>configure</command>スクリプトは標準では<literal>/usr/local/pgsql</literal>ディレクトリ以下から<literal>libpq</literal>ライブラリを検索します。
+<productname>PostgreSQL</>のインストール先が<literal>/usr/local/pgsql</literal>ディレクトリ以下でなければ、<command>configure</command>スクリプトを実行する際にコマンドライン引数として<literal>--with-pgsql</literal>や<literal>--with-pgsql-includedir</literal>、<literal>--with-pgsql-libdir</literal>オプションを指定してください。
+ </para>
+ </sect3>
+
+ <sect3 id="example-configs-begin-config-files">
+<!--
+ <title>Configuration Files</title>
+-->
+ <title>設定ファイルの作成</title>
+ <para>
+<!--
+ <productname>Pgpool-II</productname> configuration parameters are saved in the
+ <literal>pgpool.conf</literal> file. The file is in <literal>"parameter = value"
+ </literal> per line format. When you install <productname>Pgpool-II</productname>,
+ <literal>pgpool.conf.sample</literal> is automatically created.
+ We recommend copying and renaming it to <literal>pgpool.conf</literal>, and edit
+ it as you like.
+-->
+<productname>Pgpool-II</>の設定パラメータは<literal>pgpool.conf</literal>ファイルに保存されてします。
+ファイルは、1 行ごとに<literal>パラメータ名 = 値</literal>という書式です。
+<productname>Pgpool-II</> をインストールすると、<literal>pgpool.conf.sample</literal>ファイルが作成されます。
+それを<literal>pgpool.conf</literal>というファイル名にコピーしてから編集するといいでしょう。
+ <programlisting>
+$ cp /usr/local/etc/pgpool.conf.sample /usr/local/etc/pgpool.conf
+ </programlisting>
+<!--
+ <productname>Pgpool-II</productname> only accepts connections from the localhost
+ using port 9999 by the default. If you wish to receive conenctions from other hosts,
+ set <xref linkend="guc-listen-addresses"> to <literal>'*'</literal>.
+-->
+<productname>Pgpool-II</> はデフォルトではローカルホストからのポート番号9999への接続のみを受け付けます。
+<productname>Pgpool-II</> と異なるホストからの接続を受け付けたい場合は、<xref linkend="guc-listen-addresses">を<literal>'*'</literal>に設定します。
+ <programlisting>
+listen_addresses = 'localhost'
+port = 9999
+ </programlisting>
+<!--
+ We will use the default parameters in this tutorial.
+-->
+ここではデフォルトのパラメータを使うことにします。
+ </para>
+ </sect3>
+
+ <sect3 id="example-configs-begin-config-pcp">
+<!--
+ <title>Configuring <acronym>PCP</acronym> Commands</title>
+-->
+ <title><acronym>PCP</acronym>コマンドの設定</title>
+
+ <para>
+<!--
+ <productname>Pgpool-II</productname> has an interface for administrative
+ purpose to retrieve information on database nodes, shutdown
+ <productname>Pgpool-II</productname>, etc. via network. To use
+ <acronym>PCP</acronym> commands, user authentication is required.
+ This authentication is different from <productname>PostgreSQL</>'s user authentication.
+ A user name and password need to be defined in the <literal>pcp.conf</literal>
+ file. In the file, a user name and password are listed as a pair on each line,
+ and they are separated by a colon (:). Passwords are encrypted in
+ <literal>md5</literal> hash format.
+-->
+<productname>Pgpool-II</productname>には、データベースノードの情報取得や<productname>Pgpool-II</productname>停止などをネットワーク越しに行える管理目的のインターフェイスがあります。
+<acronym>PCP</acronym>コマンドを使用するにはユーザ認証が必要になります。
+この認証は<productname>PostgreSQL</>ユーザの認証とは異なります。
+ユーザ名とパスワードが<literal>pcp.conf</literal>ファイルに定義されている必要があります。
+このファイルでは、1行ごとにユーザ名とパスワードがペアとしてリストされており、これらがコロン(:)で区切られています。
+パスワードは<literal>MD5</literal>ハッシュ形式で暗号化されている必要があります。
+
+ <programlisting>
+postgres:e8a48653851e28c69d0506508fb27fc5
+ </programlisting>
+
+<!--
+ When you install <productname>Pgpool-II</productname>, <literal>pcp.conf.sample
+ </literal> is automatically created. We recommend copying and renaming it
+ to <literal>pcp.conf</literal>, and edit it.
+-->
+<productname>Pgpool-II</> をインストールするとサンプルとして<literal>pcp.conf.sample</literal>が自動的に生成されます。
+それを<literal>pcp.conf</literal>というファイル名にコピーしてから編集するといいでしょう。
+ <programlisting>
+$ cp /usr/local/etc/pcp.conf.sample /usr/local/etc/pcp.conf
+ </programlisting>
+<!--
+ To encrypt your password into md5 hash format, use the <command>pg_md5</command>
+ command, which is installed as one of <productname>Pgpool-II</productname>'s
+ executables. <command>pg_md5</command> takes text as a command line argument,
+ and displays its md5-hashed text.
+ For example, give <literal>"postgres"</literal> as the command line argument,
+ and <command>pg_md5</command> displays md5-hashed text on its standard output.
+-->
+パスワードをMD5ハッシュ形式に変換する際には、<productname>Pgpool-II</>とともにインストールされる<command>pg_md5</command>コマンドを使用します。
+<command>pg_md5</command>コマンドは、コマンドライン引数として文字列を指定すると、それをMD5ハッシュ化したものを表示します。
+例えば、以下のようにコマンドライン引数として<literal>"postgres"</literal>を指定して実行すると、それをMD5ハッシュ化しテキストが標準出力に表示されます。
+ <programlisting>
+$ /usr/local/bin/pg_md5 postgres
+e8a48653851e28c69d0506508fb27fc5
+ </programlisting>
+<!--
+ PCP commands are executed via network, so the port number must be configured
+ with <xref linkend="guc-pcp-port"> parameter in <literal>pgpool.conf</literal> file.
+ We will use the default 9898 for <xref linkend="guc-pcp-port"> in this tutorial.
+-->
+PCPコマンドはネットワークを通して実行されるので、ポート番号を<literal>pgpool.conf</literal>ファイルの<xref linkend="guc-pcp-port">パラメータに設定します。
+ここでは、<xref linkend="guc-pcp-port">のデフォルトである9898を使用することにします。
+ <programlisting>
+pcp_port = 9898
+ </programlisting>
+ </para>
+ </sect3>
+
+
+ <sect3 id="example-configs-prep-db-nodes">
+<!--
+ <title>Preparing Database Nodes</title>
+-->
+ <title>データベースノードの準備</title>
+ <para>
+<!--
+ Now, we need to set up backend <productname>PostgreSQL</> servers for <productname>Pgpool-II
+ </productname>. These servers can be placed within the same host as
+ <productname>Pgpool-II</productname>, or on separate machines. If you decide
+ to place the servers on the same host, different port numbers must be assigned
+ for each server. If the servers are placed on separate machines,
+ they must be configured properly so that they can accept network
+ connections from <productname>Pgpool-II</productname>.
+-->
+次に、<productname>Pgpool-II</productname>のための<productname>PostgreSQL</>サーバを設定する必要があります。
+これらのサーバは、<productname>Pgpool-II</> と同じホストで起動しても、異なるホストであっても構いません。
+同じホストにサーバを配置するのならば、各サーバにそれぞれ異なるポート番号を割り合てなければなりません。
+異なるマシンで起動する場合は <productname>Pgpool-II</>からのネットワーク接続を受け入れられるよう適切に設定されている必要があります。
+<productname>Pgpool-II</> ではデータベースサーバごとにレプリケーションを行うので、チュートリアルのためのデータベースクラスタを作成したほうがいいでしょう。
+ <programlisting>
+backend_hostname0 = 'localhost'
+backend_port0 = 5432
+backend_weight0 = 1
+backend_hostname1 = 'localhost'
+backend_port1 = 5433
+backend_weight1 = 1
+backend_hostname2 = 'localhost'
+backend_port2 = 5434
+backend_weight2 = 1
+ </programlisting>
+
+<!--
+ For <xref linkend="guc-backend-hostname">, <xref linkend="guc-backend-port">,
+ <xref linkend="guc-backend-weight">, set the node's hostname, port number,
+ and ratio for load balancing. At the end of each parameter string,
+ node ID must be specified by adding positive integers starting with 0 (i.e. 0, 1, 2..).
+-->
+<xref linkend="guc-backend-hostname">、<xref linkend="guc-backend-port">、<xref linkend="guc-backend-weight">には、ノードのホスト名、ポート番号、負荷分散の割合を設定します。
+各パラメータ名の後ろには、ノードIDが0から始まる整数(すなわち、0, 1, 2, ...)で指定されていなければなりません。
+ </para>
+ <note>
+ <para>
+<!--
+ <xref linkend="guc-backend-weight"> parameters for all nodes are
+ set to 1, meaning that SELECT queries are equally distributed among
+ three servers.
+-->
+すべてのノードで<xref linkend="guc-backend-weight">パラメータが1に設定してるのは、SELECTクエリが３台のサーバで等しく分散されることを意味しています。
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 id="example-configs-start-stop-pgpool">
+<!--
+ <title>Starting/Stopping <productname>Pgpool-II</productname></title>
+-->
+ <title><productname>Pgpool-II</productname>の起動と停止</title>
+ <para>
+<!--
+ To fire up <productname>Pgpool-II</productname>, execute the following
+ command on a terminal.
+-->
+<productname>Pgpool-II</> を起動するにはターミナルで以下のコマンドを実行します。
+
+ <programlisting>
+$ pgpool
+ </programlisting>
+
+<!--
+ The above command, however, prints no log messages because <productname>
+ Pgpool-II</productname> detaches the terminal. If you want to show
+ <productname>Pgpool-II</productname> log messages, you pass <literal>-n</literal>
+ option to <command>pgpool</command> command so <productname>Pgpool-II</productname>
+ is executed as non-daemon process, and the terminal will not be detached.
+-->
+しかしこれでは、<productname>Pgpool-II</productname>が制御端末を切り離すため、ログが出力されません。
+<productname>Pgpool-II</productname>にログメッセージを表示させたい場合、<command>pgpool</command>コマンドに<literal>-n</literal>オプションを指定すると、<productname>Pgpool-II</productname>は非デーモンプロセスとして起動し、制御端末は切り離されません。
+ <programlisting>
+$ pgpool -n &
+ </programlisting>
+
+<!--
+ The log messages are printed on the terminal, so it is recommended to use the following options.
+-->
+コマンドを実行した端末にログメッセージが表示されるので、以下のようなオプションを使うことをお勧めします。
+ <programlisting>
+$ pgpool -n -d > /tmp/pgpool.log 2>&1 &
+ </programlisting>
+
+<!--
+ The <literal>-d</literal> option enables debug messages to be generated.
+ The above command keeps appending log messages to <literal>/tmp/pgpool.log
+ </literal>. If you need to rotate log files, pass the logs to a external
+ command which has log rotation function.
+ For example, you can use <ulink url="https://httpd.apache.org/docs/2.4/programs/rotatelogs.html">
+ <command>rotatelogs</command></ulink> from Apache2:
+-->
+-d オプションはデバッグメッセージの出力を有効にします。
+上記の例はファイルにリダイレクトさせているため、ログメッセージが<literal>/tmp/pgpool.log</literal>に追加され続けます。
+ログをローテートさせたい場合は、ローテート機能を持った外部コマンドにログを渡してください。
+たとえば、Apache2の<ulink url="https://httpd.apache.org/docs/2.4/programs/rotatelogs.html">rotatelogs</ulink>が使用できます。
+
+ <programlisting>
+$ pgpool -n 2>&1 | /usr/local/apache2/bin/rotatelogs \
+-l -f /var/log/pgpool/pgpool.log.%A 86400 &
+ </programlisting>
+
+<!--
+ This will generate a log file named <literal>"pgpool.log.Thursday"</literal>
+ then rotate it 00:00 at midnight. Rotatelogs adds logs to a file if it already
+ exists. To delete old log files before rotation, you could use cron:
+-->
+これにより毎日夜中の0時にログがローテートされ、<literal>pgpool.log.Thursday</literal>のような名前のログファイルが毎日作成されます。
+ただし、すでに同じ名前のファイルがある場合にはrotatelogsはログをそのファイルに追加してしまいます。
+cronを使うことで、古いログファイルをローテーションの前に削除することができます。
+
+ <programlisting>
+55 23 * * * /usr/bin/find /var/log/pgpool -type f -mtime +5 -exec /bin/rm -f '{}' \;
+ </programlisting>
+
+<!--
+ Please note that rotatelogs may exist as <literal>/usr/sbin/rotatelogs2</literal>
+ in some distributions. <literal>-f</literal> option generates a log file as soon as
+ <command>rotatelogs</command> starts and is available in apache2 2.2.9 or greater.
+ Also <ulink url="http://www.cronolog.org/">cronolog</ulink> can be used.
+-->
+注意：Linuxディストリビューションによっては、rotatelogsは<literal>/usr/sbin/rotatelogs2</literal>として存在しているかもしれません。
+<literal>-f</literal>オプションは<command>rotatelogs</command>が起動された直後に直ちにログファイルを作るオプションで、apache2 2.2.9以降でのみ有効です。
+<ulink url="http://www.cronlog.org/">cronolog</ulink>を使うこともできます。
+ <programlisting>
+$ pgpool -n 2>&1 | /usr/sbin/cronolog \
+--hardlink=/var/log/pgsql/pgpool.log \
+'/var/log/pgsql/%Y-%m-%d-pgpool.log' &
+ </programlisting>
+
+<!--
+ To stop <productname>Pgpool-II</> execute the following command.
+-->
+<productname>Pgpool-II</> を停止するには以下のコマンドを実行します。
+ <programlisting>
+$ pgpool stop
+ </programlisting>
+
+<!--
+ If any client is still connected, <productname>Pgpool-II</productname>
+ waits for it to disconnect, and then terminates itself. Run the following
+ command instead if you want to shutdown <productname>Pgpool-II</productname>
+ forcibly.
+-->
+<productname>Pgpool-II</> を停止する際にクライアントが接続している場合、<productname>Pgpool-II</productname>はその接続が切断されるまで待ってから停止します。
+<productname>Pgpool-II</>を強制的にシャットダウンしたい場合は、以下のコマンドを実行します。
+ <programlisting>
+$ pgpool -m fast stop
+ </programlisting>
+
+ </para>
+ </sect3>
+</sect2>
+
+ <sect2 id="example-configs-replication">
+<!--
+ <title>Your First Replication</title>
+-->
+ <title>初めてのレプリケーション</title>
+ <para>
+<!--
+ Replication (see <xref linkend="runtime-config-replication-mode">) enables
+ the same data to be copied to multiple database nodes.
+ In this section, we'll use three database nodes, which we have already set
+ up in <xref linkend="example-configs-begin">, and takes you step by step to
+ create a database replication system.
+ Sample data to be replicated will be generated by the
+ <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
+ <command>pgbench</command></ulink> benchmark program.
+-->
+レプリケーション（<xref linkend="runtime-config-replication-mode">を参照）では複数のデータベースノードに同じデータを複製して格納します。
+ここでは、<xref linkend="example-configs-begin">で準備した 3 台のデータベースノードを使用し、一歩一歩データベースクラスタシステムを作っていきましょう。
+複製させるサンプルのデータは<ulink url="https://www.postgresql.org/docs/current/static/pgbench.html"><command>pgbench</command></ulink>ベンチマークプログラムで生成することにします。
+ </para>
+
+ <sect3 id="example-configs-config-replication">
+<!--
+ <title>Configuring Replication</title>
+-->
+ <title>レプリケーションの設定</title>
+ <para>
+<!--
+ To enable the database replication function, set
+ <xref linkend="guc-replication-mode"> to on in <literal>pgpool.conf</literal> file.
+-->
+データベースノードのレプリケーションを有効にするには、<literal>pgpool.conf</literal>ファイルの<xref linkend="guc-replication-mode">をonに設定します。
+ <programlisting>
+replication_mode = true
+ </programlisting>
+<!--
+ When <xref linkend="guc-replication-mode"> is on, <productname>Pgpool-II</productname>
+ will send a copy of a received query to all the database nodes.
+ In addition, when <xref linkend="guc-load-balance-mode"> is set to true,
+ <productname>Pgpool-II</productname> will distribute <acronym>SELECT</acronym> queries
+ among the database nodes.
+-->
+<xref linkend="guc-replication-mode">をonに設定することにより、<productname>Pgpool-II</>は受信したクエリを全てのデータベースノードに送信します。
+対して実行され、同じデータが複製されて格納されるようになります。
+さらに、<xref linkend="guc-load-balance-mode">をonに設定することにより、<productname>Pgpool-II</>はSELECTクエリをデータベースノード間に振り分けます。
+ <programlisting>
+load_balance_mode = true
+ </programlisting>
+<!--
+ In this section, we will enable both <xref linkend="guc-replication-mode">
+ and <xref linkend="guc-load-balance-mode">.
+-->
+ここでは、<xref linkend="guc-replication-mode">、<xref linkend="guc-load-balance-mode">の両方を有効にします。
+ </para>
+ </sect3>
+
+ <sect3 id="example-configs-checking-replication">
+<!--
+ <title>Checking Replication</title>
+-->
+ <title>レプリケーションの確認</title>
+ <para>
+<!--
+ To reflect the above changes in <literal>pgpool.conf</literal>,
+ <productname>Pgpool-II</productname> must be restarted.
+ Please refer to "Starting/Stopping <productname>Pgpool-II</productname>"
+ <xref linkend="example-configs-start-stop-pgpool">.
+ After configuring <literal>pgpool.conf</literal> and restarting the
+ <productname>Pgpool-II</productname>, let's try the actual replication
+ and see if everything is working.
+ First, we need to create a database to be replicated. We will name it
+ <literal>"bench_replication"</literal>. This database needs to be created
+ on all the nodes. Use the
+ <ulink url="https://www.postgresql.org/docs/current/static/app-createdb.html">
+ <command>createdb</command></ulink> commands through
+ <productname>Pgpool-II</productname>, and the database will be created
+ on all the nodes.
+-->
+上記の<literal>pgpool.conf</literal>の変更を<productname>Pgpool-II</>に反映させるには<productname>Pgpool-II</>を再起動する必要があります。
+「<productname>Pgpool-II</> の起動と停止」<xref linkend="example-configs-start-stop-pgpool">を参照してください。
+<literal>pgpool.conf</literal>の設定と再起動がすんだら、実際にレプリケーションを試してうまく行くことを確認しましょう。
+まず、複製するデータベースを作成する必要があります。
+これを<literal>"bench_replication"</literal>と名づけましょう。
+このデータベースが全てのノードで作成される必要があります。
+<ulink url="https://www.postgresql.org/docs/current/static/app-createdb.html"><command>createdb</command></ulink>コマンドを<productname>Pgpool-II</>経由で実行すると、すべてのノードでデータベースが作成されます。
+ <programlisting>
+$ createdb -p 9999 bench_replication
+ </programlisting>
+<!--
+ Then, we'll execute <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
+ <command>pgbench</command></ulink> with <literal>-i</literal> option.
+ <literal>-i</literal> option initializes the database with pre-defined tables and data.
+-->
+そして<ulink url="https://www.postgresql.org/docs/current/static/pgbench.html"><command>pgbench</command></ulink>に<literal>-i</literal>オプションを指定して実行します。
+<literal>-i</literal>オプションにより、データベースは事前に定義されたテーブルとデータで初期化されます。
+ <programlisting>
+$ pgbench -i -p 9999 bench_replication
+ </programlisting>
+<!--
+ The following table is the summary of tables and data, which will be created by
+ <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
+ <command>pgbench -i</command></ulink>. If, on all the nodes, the listed tables and
+ data are created, replication is working correctly.
+-->
+<ulink url="https://www.postgresql.org/docs/current/static/pgbench.html"><command>pgbench -i</command></ulink>によって作成されるテーブルとデータを以下の表にまとめます。
+すべてのノードにおいてこれらのテーブルおよびデータが作成されていれば、正常にレプリケーションが動作していることになります。
+ </para>
+
+ <table id="example-configs-checking-replication-table">
+ <title>data summary</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+<!--
+ <entry>Table Name</entry>
+ <entry>Number of Rows</entry>
+-->
+ <entry>テーブル名</entry>
+ <entry>行数</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>pgbench_branches</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>pgbench_tellers</entry>
+ <entry>10</entry>
+ </row>
+
+ <row>
+ <entry>pgbench_accounts</entry>
+ <entry>100000</entry>
+ </row>
+
+ <row>
+ <entry>pgbench_history</entry>
+ <entry>0</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+<!--
+ Let's use a simple shell script to check the above on all the nodes.
+ The following script will display the number of rows in pgbench_branches,
+ pgbench_tellers, pgbench_accounts, and pgbench_history tables on all the nodes (5432, 5433, 5434).
+-->
+これをチェックするため、簡単なシェルスクリプトを実行してみましょう。
+以下のスクリプトはすべてのノード (ポート番号 5432、5433、5434) のデータベースにおけるpgbench_branches、pgbench_tellers、pgbench_accounts、pgbench_historyの行数が表示されます。
+ <programlisting>
+$ for port in 5432 5433 5434; do
+> echo $port
+> for table_name in pgbench_branches pgbench_tellers pgbench_accounts pgbench_history; do
+> echo $table_name
+> psql -c "SELECT count(*) FROM $table_name" -p $port bench_replication
+> done
+> done
+ </programlisting>
+
+ </para>
+ </sect3>
+</sect2>
+
+</sect1>
diff --git a/doc.ja/src/sgml/example-cluster.sgml b/doc.ja/src/sgml/example-cluster.sgml
new file mode 100644
index 000000000..fa5294523
--- /dev/null
+++ b/doc.ja/src/sgml/example-cluster.sgml
@@ -0,0 +1,1495 @@
+<!-- doc/src/sgml/example-cluster.sgml -->
+
+<sect1 id="example-cluster">
+<title><productname>Pgpool-II</productname> + Watchdogの構築の例</title>
+<para>
+ここでは、ストリーミングレプリケーション構成の<productname>PostgreSQL</productname>を<productname>Pgpool-II</productname>で管理するシステムの構成例を示します。この例では、3台の<productname>Pgpool-II</productname>を使って<productname>PostgreSQL</productname>を管理し、単一障害点やスプリットブレインの起きない堅牢なクラスタを運用することが可能です。
+</para>
+<para>
+この設定例では<productname>PostgreSQL</productname> 11を使っていますが、各種スクリプトは<productname>PostgreSQL</productname> 12で動作確認を行っています。
+</para>
+<sect2 id="example-cluster-requirement">
+ <title>前提条件</title>
+ <para>
+<productname>Pgpool-II</productname>サーバと<productname>PostgreSQL</productname>サーバが同じサブネットにあることを前提とします。
+ </para>
+</sect2>
+
+<sect2 id="example-cluster-structure">
+ <title>全体構成</title>
+ <para>
+今回は、Linuxサーバを3台用意し、それぞれのホスト名は 「server1」、「server2」、「server3」 とします。使用するOSはすべてCentOS 7.4とします。それぞれのサーバに<productname>PostgreSQL</productname>と<productname>Pgpool-II</productname>をインストールします。3台の<productname>PostgreSQL</productname>がストリーミングレプリケーション構成になります。全体構成図は以下の通りです。
+ </para>
+ <para>
+ <figure>
+ <title>全体構成図</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="cluster_40.gif">
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </para>
+ <note>
+ <para>
+「アクティブ」「スタンバイ」「Primary」「Standby」といった役割は固定されているものではなく、運用と共に変化することがあります。
+ </para>
+ </note>
+
+<table id="example-cluster-table-ip">
+ <title>ホスト名とIPアドレス</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>ホスト名</entry>
+ <entry>IPアドバイス</entry>
+ <entry>仮想IP</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>server1</entry>
+ <entry>192.168.137.101</entry>
+ <entry morerows="2">192.168.137.150</entry>
+ </row>
+ <row>
+ <entry>server2</entry>
+ <entry>192.168.137.102</entry>
+ </row>
+ <row>
+ <entry>server3</entry>
+ <entry>192.168.137.103</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<table id="example-cluster-table-postgresql-config">
+ <title>PostgreSQLのバージョンと設定情報</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>項目</entry>
+ <entry>値</entry>
+ <entry>説明</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>PostgreSQLバージョン</entry>
+ <entry>11.1</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>ポート番号</entry>
+ <entry>5432</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>$PGDATA</entry>
+ <entry>/var/lib/pgsql/11/data</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>アーカイブモード</entry>
+ <entry>有効</entry>
+ <entry>/var/lib/pgsql/archivedir</entry>
+ </row>
+ <row>
+ <entry>レプリケーションスロット</entry>
+ <entry>有効</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>自動起動</entry>
+ <entry>自動起動しない</entry>
+ <entry>-</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+
+<table id="example-cluster-table-pgpool-config">
+ <title>Pgpool-IIのバージョンと設定情報</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>項目</entry>
+ <entry>値</entry>
+ <entry>説明</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Pgpool-IIバージョン</entry>
+ <entry>4.1</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry morerows='3'>ポート番号</entry>
+ <entry>9999</entry>
+ <entry>Pgpool-IIが接続を受け付けるポート番号</entry>
+ </row>
+ <row>
+ <entry>9898</entry>
+ <entry>PCPプロセスが接続を受け付けるポート番号</entry>
+ </row>
+ <row>
+ <entry>9000</entry>
+ <entry>watchdogが接続を受け付けるポート番号</entry>
+ </row>
+ <row>
+ <entry>9694</entry>
+ <entry>Watchdogのハートビート信号を受信するUDPポート番号</entry>
+ </row>
+ <row>
+ <entry>設定ファイル</entry>
+ <entry>/etc/pgpool-II/pgpool.conf</entry>
+ <entry>Pgpool-IIの設定ファイル</entry>
+ </row>
+ <row>
+ <entry>Pgpool-II起動ユーザ</entry>
+ <entry>root</entry>
+ <entry>通常のユーザで<productname>Pgpool-II</productname>を起動する場合の設定方法は<xref linkend="TUTORIAL-WATCHDOG-START-STOP">をご参照ください。</entry>
+ </row>
+ <row>
+ <entry>Pgpool-II動作モード</entry>
+ <entry>ストリーミングレプリケーションモード</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>Watchdog機能</entry>
+ <entry>有効</entry>
+ <entry>ハードビート方式</entry>
+ </row>
+ <row>
+ <entry>自動起動</entry>
+ <entry>自動起動しない</entry>
+ <entry>-</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+</sect2>
+
+<sect2 id="example-cluster-installation">
+ <title>インストール</title>
+ <para>
+すべてのサーバに<productname>PostgreSQL</productname> 11.1と<productname>Pgpool-II</productname> 4.1をRPMからインストールします。
+ </para>
+ <para>
+<productname>PostgreSQL</productname>のインストールは<productname>PostgreSQL</productname>コミュニティのリポジトリを使います。
+ </para>
+ <programlisting>
+# yum install https://download.postgresql.org/pub/repos/yum/11/redhat/rhel-7-x86_64/pgdg-centos11-11-2.noarch.rpm
+# yum install postgresql11 postgresql11-libs postgresql11-devel postgresql11-server
+ </programlisting>
+
+ <para>
+<productname>Pgpool-II</productname>のインストールは<productname>Pgpool-II</productname>開発コミュニティが提供するYumリポジトリを用いてインストールします。
+ </para>
+ <programlisting>
+# yum install http://www.pgpool.net/yum/rpms/4.1/redhat/rhel-7-x86_64/pgpool-II-release-4.1-1.noarch.rpm
+# yum install pgpool-II-pg11-*
+ </programlisting>
+</sect2>
+
+<sect2 id="example-cluster-pre-setup">
+ <title>事前設定</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+<productname>PostgreSQL</productname>プライマリサーバのみでストリーミングレプリケーションの設定を行います。設定方法についてはここでは省略します。
+スタンバイサーバの設定は、プライマリが起動した状態で、<productname>Pgpool-II</productname>のオンラインリカバリ機能を使って行います。
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+この設定の例ではアーカイブリカバリを行うように設定します。
+ </para>
+ <para>
+まず、すべてのサーバにて<acronym>WAL</acronym>を格納するディレクトリ<filename>/var/lib/pgsql/archivedir</filename>を事前に作成します。この設定例では、Primaryサーバのみで<acronym>WAL</acronym>アーカイブをローカルで実施します。
+ </para>
+ <programlisting>
+[全サーバ]# su - postgres
+[全サーバ]$ mkdir /var/lib/pgsql/archivedir
+ </programlisting>
+
+ <para>
+次に<literal>server1</literal>にて、設定ファイル<filename>$PGDATA/postgresql.conf</filename>を以下のように編集します。
+<literal>pg_rewind</literal>を使うために<literal>wal_log_hints</literal>を有効にしておきます。
+プライマリが後でスタンバイになる可能性があるので、<varname>hot_standby = on</varname>にしておきます。
+
+ </para>
+ <programlisting>
+listen_addresses = '*'
+archive_mode = on
+archive_command = 'cp "%p" "/var/lib/pgsql/archivedir/%f"'
+max_wal_senders = 10
+max_replication_slots = 10
+wal_level = replica
+hot_standby = on
+wal_log_hints = on
+ </programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+Pgpool-IIのヘルスチェック及びレプリケーションの遅延チェックでPostgreSQLのユーザを設定する必要があります。セキュリティ上の理由で、この設定例ではスーパーユーザを使わないようにします。
+<productname>Pgpool-II</productname>のレプリケーションの遅延チェックとヘルスチェック用のユーザ<literal>pgpool</literal>を作成します。
+また、<productname>PostgreSQL</productname>プライマリサーバ<literal>server1</literal>でレプリケーション専用ユーザ<literal>repl</literal>を作成します。
+<productname>Pgpool-II</productname>4.0からSCRAM認証を利用できるようになりました。この設定例では、<literal>scram-sha-256</literal>認証方式を利用します。
+まず、<literal>password_encryption = 'scram-sha-256'</literal>に変更してから、ユーザを登録します。
+</para>
+
+<table id="example-cluster-user">
+ <title>ユーザ</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>ユーザ名</entry>
+ <entry>パスワード</entry>
+ <entry>備考</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>repl</entry>
+ <entry>repl</entry>
+ <entry>PostgreSQLのレプリケーション専用ユーザ</entry>
+ </row>
+ <row>
+ <entry>pgpool</entry>
+ <entry>pgpool</entry>
+ <entry>Pgpool-IIのレプリケーション遅延チェック、ヘルスチェック専用ユーザ</entry>
+ </row>
+ <row>
+ <entry>postgres</entry>
+ <entry>postgres</entry>
+ <entry>オンラインリカバリを実行するユーザ</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+ <programlisting>
+[server1]# psql -U postgres -p 5432
+postgres=# SET password_encryption = 'scram-sha-256';
+postgres=# CREATE ROLE pgpool WITH LOGIN;
+postgres=# CREATE ROLE repl WITH REPLICATION LOGIN;
+postgres=# \password pgpool
+postgres=# \password repl
+postgres=# \password postgres
+ </programlisting>
+
+ <para>
+<xref linkend="SQL-SHOW-POOL-NODES">コマンドでレプリケーション状態と同期レプリケーション状態を表示するには、<literal>pgpool</literal>ユーザにデフォルトロール<literal>pg_monitor</literal>を付与する必要があります (<productname>Pgpool-II</productname>4.1以降)。
+以下のコマンドで<literal>pgpool</literal>ユーザをそのグループに所属させます。
+ </para>
+ <programlisting>
+GRANT pg_monitor TO pgpool;
+ </programlisting>
+
+ <note>
+ <para>
+<xref linkend="guc-detach-false-primary">(<productname>Pgpool-II</productname> 4.1以降)を利用する予定がある場合、"pgpool" ロールは<productname>PostgreSQL</productname>のスーパーユーザーであるか、<literal>pg_monitor</literal>グループに所属する必要があります。
+ </para>
+ </note>
+
+ <para>
+<productname>Pgpool-II</productname>サーバと<productname>PostgreSQL</productname>バックエンドサーバが同じサブネットワークにあることを想定し、各ユーザが<literal>scram-sha-256</literal>認証方式で接続できるように、<filename>pg_hba.conf</filename>を編集しておきます。
+ </para>
+ <programlisting>
+host all all samenet scram-sha-256
+host replication all samenet scram-sha-256
+ </programlisting>
+ </listitem>
+
+ <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>とします。
+ </para>
+ <programlisting>
+[全サーバ]# cd ~/.ssh
+[全サーバ]# ssh-keygen -t rsa -f id_rsa_pgpool
+[全サーバ]# ssh-copy-id -i id_rsa_pgpool.pub postgres@server1
+[全サーバ]# ssh-copy-id -i id_rsa_pgpool.pub postgres@server2
+[全サーバ]# ssh-copy-id -i id_rsa_pgpool.pub postgres@server3
+
+[全サーバ]# su - postgres
+[全サーバ]$ cd ~/.ssh
+[全サーバ]$ ssh-keygen -t rsa -f id_rsa_pgpool
+[全サーバ]$ ssh-copy-id -i id_rsa_pgpool.pub postgres@server1
+[全サーバ]# ssh-copy-id -i id_rsa_pgpool.pub postgres@server2
+[全サーバ]# 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>コマンドを実行し、パスワード入力せずログインできることを確認してください。
+必要に応じて<filename>/etc/ssh/sshd_config</filename>を編集し、sshdを再起動してください。
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+<literal>repl</literal>ユーザのパスワード入力なしで、ストリーミングレプリケーションとオンラインリカバリを行うために、または<literal>postgres</literal>ユーザで<application>pg_rewind</application>を実行するために、すべてのサーバにて<literal>postgres</literal>ユーザのホームディレクト<filename>/var/lib/pgsql</filename> に<filename>.pgpass</filename>を作成・配置し、パーミッションを 600 に設定しておきます。
+ </para>
+ <programlisting>
+[全サーバ]# su - postgres
+[全サーバ]$ vi /var/lib/pgsql/.pgpass
+(以下を追加)
+server1:5432:replication:repl:<replユーザのパスワード>
+server2:5432:replication:repl:<replユーザのパスワード>
+server3:5432:replication:repl:<replユーザのパスワード>
+server1:5432:postgres:postgres:<postgresユーザのパスワード>
+server2:5432:postgres:postgres:<postgresユーザのパスワード>
+server3:5432:postgres:postgres:<postgresユーザのパスワード>
+[全サーバ]$ chmod 600 /var/lib/pgsql/.pgpass
+ </programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+<productname>Pgpool-II</productname>や<productname>PostgreSQL</productname>に接続する際には、ファイアーウォールによって目的のポートが開けられていなければなりません。<systemitem>CentOS/RHEL7</systemitem>の場合、以下のように設定します。
+ </para>
+ <programlisting>
+[全サーバ]# firewall-cmd --permanent --zone=public --add-service=postgresql
+[全サーバ]# firewall-cmd --permanent --zone=public --add-port=9999/tcp --add-port=9898/tcp --add-port=9000/tcp --add-port=9694/udp
+[全サーバ]# firewall-cmd --reload
+ </programlisting>
+ </listitem>
+
+ </itemizedlist>
+</sect2>
+
+<sect2 id="example-cluster-pgpool-config">
+ <title><productname>Pgpool-II</productname>の設定</title>
+ <sect3 id="example-cluster-pgpool-config-common">
+ <title>共通設定</title>
+ <para>
+以下の操作は<literal>server1</literal>, <literal>server2</literal>, <literal>server3</literal>での共通の設定です。
+ </para>
+ <para>
+RPMからインストールした場合、すべての<productname>Pgpool-II</productname>の設定ファイルは<filename>/etc/pgpool-II</filename>にあります。今回はストリーミングレプリケーションモードのテンプレートとして<filename>pgpool.conf.sample-stream</filename>サンプルファイルを使用します。
+ </para>
+ <programlisting>
+[全サーバ]# cp /etc/pgpool-II/pgpool.conf.sample-stream /etc/pgpool-II/pgpool.conf
+ </programlisting>
+ <para>
+<productname>Pgpool-II</productname>が全てのIPアドレスから接続を受け付けるように、<xref linkend="GUC-LISTEN-ADDRESSES">パラメータに<literal>'*'</literal>を設定します。
+ </para>
+ <programlisting>
+listen_addresses = '*'
+ </programlisting>
+ <para>
+レプリケーションの遅延チェックユーザ<xref linkend="GUC-SR-CHECK-USER">にpgpoolユーザを設定します。
+この設定例では、<xref linkend="GUC-SR-CHECK-PASSWORD">は<filename>pgpool.conf</filename>に指定せず、<xref linkend="GUC-POOL-PASSWD">ファイルに作成します。<productname>Pgpool-II</productname> 4.0から、<xref linkend="GUC-SR-CHECK-PASSWORD">が空白の場合、<productname>Pgpool-II</productname>は空のパスワードを使用する前にまず<xref linkend="GUC-POOL-PASSWD">ファイルから<xref linkend="GUC-SR-CHECK-USER">に指定したユーザのパスワードを取得できるか試みます。
+ </para>
+ <programlisting>
+sr_check_user = 'pgpool'
+sr_check_password = ''
+ </programlisting>
+ <para>
+自動フェイルオーバのため、ヘルスチェックを有効にします。<xref linkend="GUC-HEALTH-CHECK-PERIOD">のデフォルト値が0で、これはヘルスチェックが無効であることを意味します。
+また、ネットワークが不安定な場合には、バックエンドが正常であるにも関わらず、ヘルスチェックに失敗し、フェイルオーバや縮退運転が発生してしまう可能性があります。そのようなヘルスチェックの誤検知を防止するため、ヘルスチェックのリトライ回数を<varname>health_check_max_retries = 3</varname> に設定しておきます。
+<xref linkend="GUC-HEALTH-CHECK-USER">、<xref linkend="GUC-HEALTH-CHECK-PASSWORD">は前述の<xref linkend="GUC-SR-CHECK-USER">、<xref linkend="GUC-SR-CHECK-PASSWORD">と同様に設定します。
+ </para>
+ <programlisting>
+health_check_period = 5
+ # Health check period
+ # Disabled (0) by default
+health_check_timeout = 30
+ # Health check timeout
+ # 0 means no timeout
+health_check_user = 'pgpool'
+health_check_password = ''
+
+health_check_max_retries = 3
+ </programlisting>
+ <para>
+また、バックエンド情報を前述の<literal>server1</literal>、<literal>server2</literal>及び<literal>server3</literal>の設定に従って設定しておきます。複数バックエンドノードを定義する場合、以下のbackend_*などのパラメータ名の末尾にノードIDを表す数字を付加することで複数のバックエンドを指定することができます。
+ </para>
+ <programlisting>
+# - Backend Connection Settings -
+
+backend_hostname0 = 'server1'
+ # Host name or IP address to connect to for backend 0
+backend_port0 = 5432
+ # Port number for backend 0
+backend_weight0 = 1
+ # Weight for backend 0 (only in load balancing mode)
+backend_data_directory0 = '/var/lib/pgsql/11/data'
+ # Data directory for backend 0
+backend_flag0 = 'ALLOW_TO_FAILOVER'
+ # Controls various backend behavior
+ # ALLOW_TO_FAILOVER or DISALLOW_TO_FAILOVER
+backend_hostname1 = 'server2'
+backend_port1 = 5432
+backend_weight1 = 1
+backend_data_directory1 = '/var/lib/pgsql/11/data'
+backend_flag1 = 'ALLOW_TO_FAILOVER'
+
+backend_hostname2 = 'server3'
+backend_port2 = 5432
+backend_weight2 = 1
+backend_data_directory2 = '/var/lib/pgsql/11/data'
+backend_flag2 = 'ALLOW_TO_FAILOVER'
+ </programlisting>
+
+ <para>
+<xref linkend="SQL-SHOW-POOL-NODES">コマンドでレプリケーション状態と同期レプリケーション状態を表示するには、<xref linkend="GUC-BACKEND-APPLICATION-NAME">パラメータを設定する必要があります。ここではそれぞれのホスト名を設定します。(<productname>Pgpool-II</productname> 4.1以降)
+ <programlisting>
+...
+backend_application_name0 = 'server1'
+...
+backend_application_name1 = 'server2'
+...
+backend_application_name2 = 'server3'
+ </programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-failover">
+ <title>フェイルオーバの設定</title>
+ <para>
+<productname>PostgreSQL</productname>バックエンドノードがダウンした時に実行するスクリプトを<xref linkend="GUC-FAILOVER-COMMAND">に設定します。
+また、<productname>PostgreSQL</productname>サーバが3台の場合、プライマリノードのフェイルオーバ後に新しいプライマリからスレーブをリカバリするために<xref linkend="GUC-FOLLOW-MASTER-COMMAND">も設定する必要があります。<xref linkend="GUC-FOLLOW-MASTER-COMMAND">はプライマリノードのフェイルオーバ後に実行されます。<productname>PostgreSQL</productname>サーバが2台の場合、<xref linkend="GUC-FOLLOW-MASTER-COMMAND">の設定は不要です。
+ </para>
+ <para>
+それぞれの実行スクリプトの引数は、それぞれ実行時に<productname>Pgpool-II</productname>によってバックエンドの具体的な情報に置き換えられます。各引数の意味は<xref linkend="GUC-FAILOVER-COMMAND">をご参照ください。
+ </para>
+ <programlisting>
+failover_command = '/etc/pgpool-II/failover.sh %d %h %p %D %m %H %M %P %r %R %N %S'
+follow_master_command = '/etc/pgpool-II/follow_master.sh %d %h %p %D %m %M %H %P %r %R'
+ </programlisting>
+ <note>
+ <para>
+<emphasis>%N</emphasis>、<emphasis>%S</emphasis>は<productname>Pgpool-II</productname> 4.1で追加された引数です。
+<productname>Pgpool-II</productname> 4.0 または以前のバージョンを利用している場合、これらの引数を指定できないので、ご注意ください。
+ </para>
+ </note>
+ <para>
+<filename>/etc/pgpool-II/failover.sh</filename>及び<filename>/etc/pgpool-II/follow_master.sh</filename>を作成し、実行権限を与えておきます。
+ </para>
+ <programlisting>
+# vi /etc/pgpool-II/failover.sh
+# vi /etc/pgpool-II/follow_master.sh
+# chmod +x /etc/pgpool-II/{failover.sh,follow_master.sh}
+ </programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+/etc/pgpool-II/failover.sh
+ </para>
+ <programlisting>
+#!/bin/bash
+# This script is run by failover_command.
+
+set -o xtrace
+exec > >(logger -i -p local1.info) 2>&1
+
+# Special values:
+# %d = failed node id
+# %h = failed node hostname
+# %p = failed node port number
+# %D = failed node database cluster path
+# %m = new master node id
+# %H = new master node hostname
+# %M = old master node id
+# %P = old primary node id
+# %r = new master port number
+# %R = new master database cluster path
+# %N = old primary node hostname
+# %S = old primary node port number
+# %% = '%' character
+
+FAILED_NODE_ID="$1"
+FAILED_NODE_HOST="$2"
+FAILED_NODE_PORT="$3"
+FAILED_NODE_PGDATA="$4"
+NEW_MASTER_NODE_ID="$5"
+NEW_MASTER_NODE_HOST="$6"
+OLD_MASTER_NODE_ID="$7"
+OLD_PRIMARY_NODE_ID="$8"
+NEW_MASTER_NODE_PORT="$9"
+NEW_MASTER_NODE_PGDATA="${10}"
+OLD_PRIMARY_NODE_HOST="${11}"
+OLD_PRIMARY_NODE_PORT="${12}"
+
+PGHOME=/usr/pgsql-11
+
+
+logger -i -p local1.info failover.sh: start: failed_node_id=$FAILED_NODE_ID old_primary_node_id=$OLD_PRIMARY_NODE_ID failed_host=$FAILED_NODE_HOST new_master_host=$NEW_MASTER_NODE_HOST
+
+## Test passwrodless SSH
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ls /tmp > /dev/null
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.info failover.sh: passwrodless SSH to postgres@${NEW_MASTER_NODE_HOST} failed. Please setup passwrodless SSH.
+ exit 1
+fi
+
+## If Standby node is down, skip failover.
+if [ $FAILED_NODE_ID -ne $OLD_PRIMARY_NODE_ID ]; then
+ logger -i -p local1.info failover.sh: Standby node is down. Skipping failover.
+
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$OLD_PRIMARY_NODE_HOST -i ~/.ssh/id_rsa_pgpool "
+ ${PGHOME}/bin/psql -p $OLD_PRIMARY_NODE_PORT -c \"SELECT pg_drop_replication_slot('${FAILED_NODE_HOST}')\"
+ "
+
+ if [ $? -ne 0 ]; then
+ logger -i -p local1.error failover.sh: drop replication slot "${FAILED_NODE_HOST}" failed
+ exit 1
+ fi
+
+ exit 0
+fi
+
+## Promote Standby node.
+logger -i -p local1.info failover.sh: Primary node is down, promote standby node ${NEW_MASTER_NODE_HOST}.
+
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+ postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ${PGHOME}/bin/pg_ctl -D ${NEW_MASTER_NODE_PGDATA} -w promote
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.error failover.sh: new_master_host=$NEW_MASTER_NODE_HOST promote failed
+ exit 1
+fi
+
+logger -i -p local1.info failover.sh: end: new_master_node_id=$NEW_MASTER_NODE_ID started as the primary node
+exit 0
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+/etc/pgpool-II/follow_master.sh
+ </para>
+ <programlisting>
+#!/bin/bash
+# This script is run after failover_command to synchronize the Standby with the new Primary.
+# First try pg_rewind. If pg_rewind failed, use pg_basebackup.
+
+set -o xtrace
+exec > >(logger -i -p local1.info) 2>&1
+
+# Special values:
+# %d = failed node id
+# %h = failed node hostname
+# %p = failed node port number
+# %D = failed node database cluster path
+# %m = new master node id
+# %H = new master node hostname
+# %M = old master node id
+# %P = old primary node id
+# %r = new master port number
+# %R = new master database cluster path
+# %N = old primary node hostname
+# %S = old primary node port number
+# %% = '%' character
+
+FAILED_NODE_ID="$1"
+FAILED_NODE_HOST="$2"
+FAILED_NODE_PORT="$3"
+FAILED_NODE_PGDATA="$4"
+NEW_MASTER_NODE_ID="$5"
+OLD_MASTER_NODE_ID="$6"
+NEW_MASTER_NODE_HOST="$7"
+OLD_PRIMARY_NODE_ID="$8"
+NEW_MASTER_NODE_PORT="$9"
+NEW_MASTER_NODE_PGDATA="${10}"
+
+PGHOME=/usr/pgsql-11
+ARCHIVEDIR=/var/lib/pgsql/archivedir
+REPLUSER=repl
+PCP_USER=pgpool
+PGPOOL_PATH=/usr/bin
+PCP_PORT=9898
+
+logger -i -p local1.info follow_master.sh: start: Standby node ${FAILED_NODE_ID}
+
+## Test passwrodless SSH
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ls /tmp > /dev/null
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.info follow_master.sh: passwrodless SSH to postgres@${NEW_MASTER_NODE_HOST} failed. Please setup passwrodless SSH.
+ exit 1
+fi
+
+## Get PostgreSQL major version
+PGVERSION=`${PGHOME}/bin/initdb -V | awk '{print $3}' | sed 's/\..*//' | sed 's/\([0-9]*\)[a-zA-Z].*/\1/'`
+
+if [ $PGVERSION -ge 12 ]; then
+ RECOVERYCONF=${FAILED_NODE_PGDATA}/myrecovery.conf
+else
+ RECOVERYCONF=${FAILED_NODE_PGDATA}/recovery.conf
+fi
+
+## Check the status of Standby
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+postgres@${FAILED_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ${PGHOME}/bin/pg_ctl -w -D ${FAILED_NODE_PGDATA} status
+
+
+## If Standby is running, synchronize it with the new Primary.
+if [ $? -eq 0 ]; then
+
+ logger -i -p local1.info follow_master.sh: pg_rewind for $FAILED_NODE_ID
+
+ # Create replication slot "${FAILED_NODE_HOST}"
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool "
+ ${PGHOME}/bin/psql -p ${NEW_MASTER_NODE_PORT} -c \"SELECT pg_create_physical_replication_slot('${FAILED_NODE_HOST}');\"
+ "
+
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${FAILED_NODE_HOST} -i ~/.ssh/id_rsa_pgpool "
+
+ set -o errexit
+
+ ${PGHOME}/bin/pg_ctl -w -m f -D ${FAILED_NODE_PGDATA} stop
+
+ cat > ${RECOVERYCONF} << EOT
+primary_conninfo = 'host=${NEW_MASTER_NODE_HOST} port=${NEW_MASTER_NODE_PORT} user=${REPLUSER} application_name=${FAILED_NODE_HOST} passfile=''/var/lib/pgsql/.pgpass'''
+recovery_target_timeline = 'latest'
+restore_command = 'scp ${NEW_MASTER_NODE_HOST}:${ARCHIVEDIR}/%f %p'
+primary_slot_name = '${FAILED_NODE_HOST}'
+EOT
+
+ if [ ${PGVERSION} -ge 12 ]; then
+ touch ${FAILED_NODE_PGDATA}/standby.signal
+ else
+ echo \"standby_mode = 'on'\" >> ${RECOVERYCONF}
+ fi
+
+ ${PGHOME}/bin/pg_rewind -D ${FAILED_NODE_PGDATA} --source-server=\"user=postgres host=${NEW_MASTER_NODE_HOST} port=${NEW_MASTER_NODE_PORT}\"
+
+ "
+
+ if [ $? -ne 0 ]; then
+ logger -i -p local1.error follow_master.sh: end: pg_rewind failed. Try pg_basebackup.
+
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${FAILED_NODE_HOST} -i ~/.ssh/id_rsa_pgpool "
+
+ set -o errexit
+
+ # Execute pg_basebackup
+ rm -rf ${FAILED_NODE_PGDATA}
+ rm -rf ${ARCHIVEDIR}/*
+ ${PGHOME}/bin/pg_basebackup -h ${NEW_MASTER_NODE_HOST} -U $REPLUSER -p ${NEW_MASTER_NODE_PORT} -D ${FAILED_NODE_PGDATA} -X stream
+
+ if [ ${PGVERSION} -ge 12 ]; then
+ sed -i -e \"\\\$ainclude_if_exists = '$(echo ${RECOVERYCONF} | sed -e 's/\//\\\//g')'\" \
+ -e \"/^include_if_exists = '$(echo ${RECOVERYCONF} | sed -e 's/\//\\\//g')'/d\" ${FAILED_NODE_PGDATA}/postgresql.conf
+ fi
+
+ cat > ${RECOVERYCONF} << EOT
+primary_conninfo = 'host=${NEW_MASTER_NODE_HOST} port=${NEW_MASTER_NODE_PORT} user=${REPLUSER} application_name=${FAILED_NODE_HOST} passfile=''/var/lib/pgsql/.pgpass'''
+recovery_target_timeline = 'latest'
+restore_command = 'scp ${NEW_MASTER_NODE_HOST}:${ARCHIVEDIR}/%f %p'
+primary_slot_name = '${FAILED_NODE_HOST}'
+EOT
+
+ if [ ${PGVERSION} -ge 12 ]; then
+ touch ${FAILED_NODE_PGDATA}/standby.signal
+ else
+ echo \"standby_mode = 'on'\" >> ${RECOVERYCONF}
+ fi
+ "
+
+ if [ $? -ne 0 ]; then
+ # drop replication slot
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool "
+ ${PGHOME}/bin/psql -p ${NEW_MASTER_NODE_PORT} -c \"SELECT pg_drop_replication_slot('${FAILED_NODE_HOST}')\"
+ "
+
+ logger -i -p local1.error follow_master.sh: end: pg_basebackup failed
+ exit 1
+ fi
+ fi
+
+ # start Standby node on ${FAILED_NODE_HOST}
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+ postgres@${FAILED_NODE_HOST} -i ~/.ssh/id_rsa_pgpool $PGHOME/bin/pg_ctl -l /dev/null -w -D ${FAILED_NODE_PGDATA} start
+
+ # If start Standby successfully, attach this node
+ if [ $? -eq 0 ]; then
+
+ # Run pcp_attact_node to attach Standby node to Pgpool-II.
+ ${PGPOOL_PATH}/pcp_attach_node -w -h localhost -U $PCP_USER -p ${PCP_PORT} -n ${FAILED_NODE_ID}
+
+ if [ $? -ne 0 ]; then
+ logger -i -p local1.error follow_master.sh: end: pcp_attach_node failed
+ exit 1
+ fi
+
+ # If start Standby failed, drop replication slot "${FAILED_NODE_HOST}"
+ else
+
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool \
+ ${PGHOME}/bin/psql -p ${NEW_MASTER_NODE_PORT} -c "SELECT pg_drop_replication_slot('${FAILED_NODE_HOST}')"
+ logger -i -p local1.error follow_master.sh: end: follow master command failed
+ exit 1
+ fi
+
+else
+ logger -i -p local1.info follow_master.sh: failed_nod_id=${FAILED_NODE_ID} is not running. skipping follow master command
+ exit 0
+fi
+
+logger -i -p local1.info follow_master.sh: end: follow master command complete
+exit 0
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-online-recovery">
+ <title>オンラインリカバリの設定</title>
+ <para>
+続いて、オンラインリカバリを行うための<productname>PostgreSQL</productname>のユーザ名およびオンラインリカバリ時に呼び出されるコマンド<command>recovery_1st_stage</command>を設定します。
+オンラインリカバリで実行される<function>pgpool_recovery</function>関数は<productname>PostgreSQL</productname>のスーパーユーザ権限が必要なため、<varname>recovery_user</varname>に<emphasis>スーパーユーザ</emphasis>を指定しなければなりません。ここでは、postrgesユーザを指定します。
+オンラインリカバリ用のスクリプト<filename>recovery_1st_stage</filename>、<filename>pgpool_remote_start</filename>をプライマリサーバ(server1)のデータベースクラスタ配下に配置し、実行権限を与えておきます。
+ </para>
+ <programlisting>
+recovery_user = 'postgres'
+ # Online recovery user
+recovery_password = ''
+ # Online recovery password
+
+recovery_1st_stage_command = 'recovery_1st_stage'
+ </programlisting>
+ <programlisting>
+[server1]# su - postgres
+[server1]$ vi /var/lib/pgsql/11/data/recovery_1st_stage
+[server1]$ vi /var/lib/pgsql/11/data/pgpool_remote_start
+[server1]$ chmod +x /var/lib/pgsql/11/data/{recovery_1st_stage,pgpool_remote_start}
+ </programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+/var/lib/pgsql/11/data/recovery_1st_stage
+ </para>
+ <programlisting>
+#!/bin/bash
+# This script is executed by "recovery_1st_stage" to recovery a Standby node.
+
+set -o xtrace
+exec > >(logger -i -p local1.info) 2>&1
+
+PRIMARY_NODE_PGDATA="$1"
+DEST_NODE_HOST="$2"
+DEST_NODE_PGDATA="$3"
+PRIMARY_NODE_PORT="$4"
+DEST_NODE_ID="$5"
+DEST_NODE_PORT="$6"
+
+PRIMARY_NODE_HOST=$(hostname)
+PGHOME=/usr/pgsql-11
+ARCHIVEDIR=/var/lib/pgsql/archivedir
+REPLUSER=repl
+
+logger -i -p local1.info recovery_1st_stage: start: pg_basebackup for Standby node $DEST_NODE_ID
+
+## Test passwrodless SSH
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${DEST_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ls /tmp > /dev/null
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.info recovery_1st_stage: passwrodless SSH to postgres@${DEST_NODE_HOST} failed. Please setup passwrodless SSH.
+ exit 1
+fi
+
+## Get PostgreSQL major version
+PGVERSION=`${PGHOME}/bin/initdb -V | awk '{print $3}' | sed 's/\..*//' | sed 's/\([0-9]*\)[a-zA-Z].*/\1/'`
+if [ $PGVERSION -ge 12 ]; then
+ RECOVERYCONF=${DEST_NODE_PGDATA}/myrecovery.conf
+else
+ RECOVERYCONF=${DEST_NODE_PGDATA}/recovery.conf
+fi
+
+## Create replication slot "${DEST_NODE_HOST}"
+${PGHOME}/bin/psql -p ${PRIMARY_NODE_PORT} << EOQ
+SELECT pg_create_physical_replication_slot('${DEST_NODE_HOST}');
+EOQ
+
+## Execute pg_basebackup to recovery Standby node
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$DEST_NODE_HOST -i ~/.ssh/id_rsa_pgpool "
+
+ set -o errexit
+
+ rm -rf $DEST_NODE_PGDATA
+ rm -rf $ARCHIVEDIR/*
+
+ ${PGHOME}/bin/pg_basebackup -h $PRIMARY_NODE_HOST -U $REPLUSER -p $PRIMARY_NODE_PORT -D $DEST_NODE_PGDATA -X stream
+
+ if [ ${PGVERSION} -ge 12 ]; then
+ sed -i -e \"\\\$ainclude_if_exists = '$(echo ${RECOVERYCONF} | sed -e 's/\//\\\//g')'\" \
+ -e \"/^include_if_exists = '$(echo ${RECOVERYCONF} | sed -e 's/\//\\\//g')'/d\" ${DEST_NODE_PGDATA}/postgresql.conf
+ fi
+
+ cat > ${RECOVERYCONF} << EOT
+primary_conninfo = 'host=${PRIMARY_NODE_HOST} port=${PRIMARY_NODE_PORT} user=${REPLUSER} application_name=${DEST_NODE_HOST} passfile=''/var/lib/pgsql/.pgpass'''
+recovery_target_timeline = 'latest'
+restore_command = 'scp ${PRIMARY_NODE_HOST}:${ARCHIVEDIR}/%f %p'
+primary_slot_name = '${DEST_NODE_HOST}'
+EOT
+
+ if [ ${PGVERSION} -ge 12 ]; then
+ touch ${DEST_NODE_PGDATA}/standby.signal
+ else
+ echo \"standby_mode = 'on'\" >> ${RECOVERYCONF}
+ fi
+
+ sed -i \"s/#*port = .*/port = ${DEST_NODE_PORT}/\" ${DEST_NODE_PGDATA}/postgresql.conf
+"
+
+if [ $? -ne 0 ]; then
+
+ ${PGHOME}/bin/psql -p ${PRIMARY_NODE_PORT} << EOQ
+SELECT pg_drop_replication_slot('${DEST_NODE_HOST}');
+EOQ
+
+ logger -i -p local1.error recovery_1st_stage: end: pg_basebackup failed. online recovery failed
+ exit 1
+fi
+
+logger -i -p local1.info recovery_1st_stage: end: recovery_1st_stage complete
+exit 0
+</programlisting>
+ </listitem>
+ <listitem>
+
+ <para>
+/var/lib/pgsql/11/data/pgpool_remote_start
+ </para>
+<programlisting>
+#!/bin/bash
+# This script is run after recovery_1st_stage to start Standby node.
+
+set -o xtrace
+exec > >(logger -i -p local1.info) 2>&1
+
+PGHOME=/usr/pgsql-11
+DEST_NODE_HOST="$1"
+DEST_NODE_PGDATA="$2"
+
+
+logger -i -p local1.info pgpool_remote_start: start: remote start Standby node $DEST_NODE_HOST
+
+## Test passwrodless SSH
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${DEST_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ls /tmp > /dev/null
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.info pgpool_remote_start: passwrodless SSH to postgres@${DEST_NODE_HOST} failed. Please setup passwrodless SSH.
+ exit 1
+fi
+
+## Start Standby node
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$DEST_NODE_HOST -i ~/.ssh/id_rsa_pgpool "
+ $PGHOME/bin/pg_ctl -l /dev/null -w -D $DEST_NODE_PGDATA start
+"
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.error pgpool_remote_start: $DEST_NODE_HOST PostgreSQL start failed.
+ exit 1
+fi
+
+logger -i -p local1.info pgpool_remote_start: end: $DEST_NODE_HOST PostgreSQL started successfully.
+exit 0
+</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+また、オンラインリカバリ機能を使用するには、<function>pgpool_recovery</function>、<function>pgpool_remote_start</function>、<function>pgpool_switch_xlog</function>という関数が必要になるので、<literal>server1</literal>のtemplate1に<function>pgpool_recovery</function>をインストールしておきます。
+ </para>
+<programlisting>
+[server1]# su - postgres
+[server1]$ psql template1 -c "CREATE EXTENSION pgpool_recovery"
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-auth">
+ <title>クライアント認証の設定</title>
+ <para>
+<link linkend="EXAMPLE-CLUSTER-PRE-SETUP">事前設定</link>の章で、<productname>Pgpool-II</productname>と<productname>PostgreSQL</productname>の間に認証方式を<acronym>scram-sha-256</acronym>に設定しました。この設定例では、クライアントと<productname>Pgpool-II</productname>の間でも<acronym>scram-sha-256</acronym>認証方式を利用し接続するように設定します。
+<productname>Pgpool-II</productname>のクライアント認証の設定ファイルは<filename>pool_hba.conf</filename>と呼ばれ、RPMパッケージからインストールする場合、デフォルトでは<filename>/etc/pgpool-II</filename>配下にインストールされます。
+デフォルトでは<filename>pool_hba.conf</filename>による認証は無効になっているので、<filename>pgpool.conf</filename>では以下の設定をonに変更します。
+ </para>
+<programlisting>
+enable_pool_hba = on
+</programlisting>
+ <para>
+<filename>pool_hba.conf</filename>のフォーマットは<productname>PostgreSQL</productname>の<filename>pg_hba.conf</filename>とほとんど同じです。<literal>pgpool</literal>と<literal>postgres</literal>ユーザを<acronym>scram-sha-256</acronym>認証に設定します。
+ </para>
+<programlisting>
+host all pgpool 0.0.0.0/0 scram-sha-256
+host all postgres 0.0.0.0/0 scram-sha-256
+</programlisting>
+ <note>
+ <para>
+<productname>Pgpool-II</productname> 4.0の場合、<filename>pgpool.conf</filename>ファイル内の<xref linkend="guc-health-check-password">、
+<xref linkend="guc-sr-check-password">、<xref linkend="guc-wd-lifecheck-password">、
+<xref linkend="guc-recovery-password">にはAES256暗号化形式、平文形式しか指定できないので、
+ご注意ください。
+ </para>
+ </note>
+ <para>
+<productname>Pgpool-II</productname>のクライアント認証で用いるデフォルトのパスワードファイル名はpool_passwdです。
+<literal>scram-sha-256</literal>認証を利用する場合、<productname>Pgpool-II</productname>はそれらのパスワードを復号化するために復号鍵が必要となります。全サーバで復号鍵ファイルをrootユーザのホームディレクトリ配下に作成します。
+ </para>
+<programlisting>
+[全サーバ]# echo '任意の文字列' > ~/.pgpoolkey
+[全サーバ]# chmod 600 ~/.pgpoolkey
+</programlisting>
+ <para>
+「pg_enc -m -k /path/to/.pgpoolkey -u ユーザ名 -p」 コマンドを実行すると、ユーザ名と<literal>AES256</literal>で暗号化したパスワードのエントリが<xref linkend="GUC-POOL-PASSWD">に登録されます。
+<xref linkend="GUC-POOL-PASSWD"> がまだ存在しなければ、<filename>pgpool.conf</filename>と同じディレクトリ内に作成されます。
+ </para>
+<programlisting>
+[全サーバ]# pg_enc -m -k /root/.pgpoolkey -u pgpool -p
+db password: [pgpoolユーザのパスワード]
+[全サーバ]# pg_enc -m -k /root/.pgpoolkey -u postgres -p
+db password: [postgresユーザのパスワード]
+
+# cat /etc/pgpool-II/pool_passwd
+pgpool:AESheq2ZMZjynddMWk5sKP/Rw==
+postgres:AESHs/pWL5rtXy2IwuzroHfqg==
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-watchdog">
+ <title>Watchdogの設定</title>
+ <para>
+デフォルトでは<literal>watchdog</literal>機能が無効のため、<literal>server1</literal>、<literal>server2</literal>及び<literal>server3</literal>で<literal>watchdog</literal>を有効にします。
+ </para>
+<programlisting>
+use_watchdog = on
+</programlisting>
+ <para>
+アクティブ機が立ち上げる仮想IPをdelegate_IPに指定します。仮想 IP はまだ使われていないIPアドレスを指定してください。<literal>server1</literal>、<literal>server2</literal>及び<literal>server3</literal>の共通の設定です。
+ </para>
+<programlisting>
+delegate_IP = '192.168.137.150'
+</programlisting>
+
+ <para>
+仮想IPの起動/停止、ARPリクエストの送信を行う設定パラメータ<xref linkend="GUC-IF-UP-CMD">、<xref linkend="GUC-IF-DOWN-CMD">、<xref linkend="GUC-ARPING-CMD">に、ネットワーク環境に合わせてネットワークインターフェース名を設定します。
+今回の例で使ったネットワークインターフェースは「enp0s8」となっています。
+ </para>
+<programlisting>
+if_up_cmd = 'ip addr add $_IP_$/24 dev enp0s8 label enp0s8:0'
+ # startup delegate IP command
+if_down_cmd = 'ip addr del $_IP_$/24 dev enp0s8'
+ # shutdown delegate IP command
+arping_cmd = 'arping -U $_IP_$ -w 1 -I enp0s8'
+ # arping command
+</programlisting>
+
+ <para>
+ipコマンドやarpingコマンドのパスがデフォルトのパスと異なる場合、環境に合わせて<xref linkend="GUC-IF-CMD-PATH">や<xref linkend="GUC-ARPING-PATH">を設定しておいてください。
+ </para>
+<programlisting>
+if_cmd_path = '/sbin'
+ # path to the directory where if_up/down_cmd exists
+arping_path = '/usr/sbin'
+ # arping command path
+</programlisting>
+ <para>
+各watchdog が稼働するサーバ情報を設定しておきます。
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>server1</literal>の場合
+ </para>
+<programlisting>
+wd_hostname = 'server1'
+wd_port = 9000
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+<literal>server2</literal>の場合
+ </para>
+<programlisting>
+wd_hostname = 'server2'
+wd_port = 9000
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+<literal>server3</literal>の場合
+ </para>
+<programlisting>
+wd_hostname = 'server3'
+wd_port = 9000
+</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+各監視対象の<productname>Pgpool-II</productname>サーバ情報を設定しておきます。
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>server1</literal>の場合
+ </para>
+<programlisting>
+# - Other pgpool Connection Settings -
+
+other_pgpool_hostname0 = 'server2'
+ # Host name or IP address to connect to for other pgpool 0
+ # (change requires restart)
+other_pgpool_port0 = 9999
+ # Port number for other pgpool 0
+ # (change requires restart)
+other_wd_port0 = 9000
+ # Port number for other watchdog 0
+ # (change requires restart)
+other_pgpool_hostname1 = 'server3'
+other_pgpool_port1 = 9999
+other_wd_port1 = 9000
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+<literal>server2</literal>の場合
+ </para>
+<programlisting>
+# - Other pgpool Connection Settings -
+
+other_pgpool_hostname0 = 'server1'
+ # Host name or IP address to connect to for other pgpool 0
+ # (change requires restart)
+other_pgpool_port0 = 9999
+ # Port number for other pgpool 0
+ # (change requires restart)
+other_wd_port0 = 9000
+ # Port number for other watchdog 0
+ # (change requires restart)
+other_pgpool_hostname1 = 'server3'
+other_pgpool_port1 = 9999
+other_wd_port1 = 9000
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+<literal>server3</literal>の場合
+ </para>
+<programlisting>
+# - Other pgpool Connection Settings -
+
+other_pgpool_hostname0 = 'server1'
+ # Host name or IP address to connect to for other pgpool 0
+ # (change requires restart)
+other_pgpool_port0 = 9999
+ # Port number for other pgpool 0
+ # (change requires restart)
+other_wd_port0 = 9000
+ # Port number for other watchdog 0
+ # (change requires restart)
+other_pgpool_hostname1 = 'server2'
+other_pgpool_port1 = 9999
+other_wd_port1 = 9000
+</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ハートビート信号の送信先のホスト名とポート番号を指定します。
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>server1</literal>の場合
+ </para>
+<programlisting>
+heartbeat_destination0 = 'server2'
+ # Host name or IP address of destination 0
+ # for sending heartbeat signal.
+ # (change requires restart)
+heartbeat_destination_port0 = 9694
+ # Port number of destination 0 for sending
+ # heartbeat signal. Usually this is the
+ # same as wd_heartbeat_port.
+ # (change requires restart)
+heartbeat_device0 = ''
+ # Name of NIC device (such like 'eth0')
+ # used for sending/receiving heartbeat
+ # signal to/from destination 0.
+ # This works only when this is not empty
+ # and pgpool has root privilege.
+ # (change requires restart)
+
+heartbeat_destination1 = 'server3'
+heartbeat_destination_port1 = 9694
+heartbeat_device1 = ''
+
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+<literal>server2</literal>の場合
+ </para>
+<programlisting>
+heartbeat_destination0 = 'server1'
+ # Host name or IP address of destination 0
+ # for sending heartbeat signal.
+ # (change requires restart)
+heartbeat_destination_port0 = 9694
+ # Port number of destination 0 for sending
+ # heartbeat signal. Usually this is the
+ # same as wd_heartbeat_port.
+ # (change requires restart)
+heartbeat_device0 = ''
+ # Name of NIC device (such like 'eth0')
+ # used for sending/receiving heartbeat
+ # signal to/from destination 0.
+ # This works only when this is not empty
+ # and pgpool has root privilege.
+ # (change requires restart)
+
+heartbeat_destination1 = 'server3'
+heartbeat_destination_port1 = 9694
+heartbeat_device1 = ''
+
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+<literal>server3</literal>の場合
+ </para>
+<programlisting>
+heartbeat_destination0 = 'server1'
+ # Host name or IP address of destination 0
+ # for sending heartbeat signal.
+ # (change requires restart)
+heartbeat_destination_port0 = 9694
+ # Port number of destination 0 for sending
+ # heartbeat signal. Usually this is the
+ # same as wd_heartbeat_port.
+ # (change requires restart)
+heartbeat_device0 = ''
+ # Name of NIC device (such like 'eth0')
+ # used for sending/receiving heartbeat
+ # signal to/from destination 0.
+ # This works only when this is not empty
+ # and pgpool has root privilege.
+ # (change requires restart)
+
+heartbeat_destination1 = 'server2'
+heartbeat_destination_port1 = 9694
+heartbeat_device1 = ''
+</programlisting>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-sysconfig">
+ <title>/etc/sysconfig/pgpoolの設定</title>
+ <para>
+<productname>Pgpool-II</productname>を起動時に<filename>pgpool_status</filename>ファイルを無視させたい場合、<filename>/etc/sysconfig/pgpool</filename>の起動オプションOPTSに「-D」を追加します。
+ </para>
+<programlisting>
+[全サーバ]# vi /etc/sysconfig/pgpool
+(...省略...)
+OPTS=" -D -n"
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-log">
+ <title>ログの設定</title>
+ <para>
+この例では、<productname>Pgpool-II</productname>のログ出力は<literal>syslog</literal>を利用するように設定します。
+ </para>
+<programlisting>
+log_destination = 'syslog'
+ # Where to log
+ # Valid values are combinations of stderr,
+ # and syslog. Default to stderr.
+
+syslog_facility = 'LOCAL1'
+ # Syslog local facility. Default to LOCAL0
+</programlisting>
+ <para>
+全サーバではログファイルを作成します。
+ </para>
+<programlisting>
+[全サーバ]# mkdir /var/log/pgpool-II
+[全サーバ]# touch /var/log/pgpool-II/pgpool.log
+</programlisting>
+ <para>
+次に<literal>syslog</literal>の設定ファイルを以下のように編集します。
+ </para>
+<programlisting>
+[全サーバ]# vi /etc/rsyslog.conf
+...(省略)...
+*.info;mail.none;authpriv.none;cron.none;LOCAL1.none /var/log/messages
+LOCAL1.* /var/log/pgpool-II/pgpool.log
+</programlisting>
+ <para>
+また、<productname>Pgpool-II</productname>に関して<filename>/var/log/messages</filename>と同様のログローテーションを行うように、logrotateの設定を以下のように行います。
+ </para>
+<programlisting>
+[全サーバ]# vi /etc/logrotate.d/syslog
+...(省略)...
+/var/log/messages
+/var/log/pgpool-II/pgpool.log
+/var/log/secure
+</programlisting>
+
+ <para>
+設定が終わったら、rsyslogサービスを再起動します。
+ </para>
+<programlisting>
+[全サーバ]# systemctl restart rsyslog
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-pcp">
+ <title>PCPコマンドの設定</title>
+ <para>
+<literal>PCP</literal>コマンドを使用するにはユーザ認証が必要になるので、ユーザ名と<literal>md5</literal>ハッシュに変換されたパスワードを<filename>pcp.conf</filename>ファイルに設定します。
+ここではユーザ名に<literal>pgpool</literal>を使用し、以下のコマンドを実行することで、<ユーザ名:ハッシュ化されたパスワード>が<filename>/etc/pgpool-II/pcp.conf</filename>に追加されます。
+ </para>
+<programlisting>
+[全サーバ]# echo 'pgpool:'`pg_md5 PCPコマンドパスワード` >> /etc/pgpool-II/pcp.conf
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-pcppass">
+ <title>.pcppassの設定</title>
+ <para>
+前述の<literal>follow_master_command</literal>のスクリプトでパスワード入力なしで<literal>PCP</literal>コマンドを実行できるように、すべてのサーバで<productname>Pgpool-II</productname>の起動ユーザのホームディレクトリに<filename>.pcppass</filename>を作成します。
+ </para>
+<programlisting>
+[全サーバ]# echo 'localhost:9898:pgpool:pgpool' > ~/.pcppass
+[全サーバ]# chmod 600 ~/.pcppass
+</programlisting>
+ <para>
+ここで、<productname>Pgpool-II</productname>の設定は完了です。
+ </para>
+ </sect3>
+</sect2>
+
+<sect2 id="example-cluster-start-stop">
+ <title>システムの起動と停止</title>
+ <para>
+<productname>Pgpool-II</productname>の設定が完了したら、次に<productname>Pgpool-II</productname>を起動します。<productname>Pgpool-II</productname>を起動する前に、バックエンドの<productname>PostgreSQL</productname>をあらかじめ起動する必要があります。また、<productname>PostgreSQL</productname>を停止する場合、<productname>Pgpool-II</productname>を先に停止する必要があります。
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<productname>Pgpool-II</productname>の起動
+ </para>
+ <para>
+前述の<link linkend="EXAMPLE-CLUSTER-PRE-SETUP">事前設定</link>の章で<productname>Pgpool-II</productname>の自動起動が設定済なので、ここでシステム全体を再起動するか、以下のコマンドを実行してください。
+ </para>
+<programlisting>
+# systemctl start pgpool.service
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+<productname>Pgpool-II</productname>の停止
+ </para>
+<programlisting>
+# systemctl stop pgpool.service
+</programlisting>
+ </listitem>
+ </itemizedlist>
+</sect2>
+
+<sect2 id="example-cluster-try">
+ <title>動作確認</title>
+ <para>
+これから、動作確認を行います。まず、<literal>server1</literal>、<literal>server2</literal>、<literal>server3</literal>で以下のコマンドで<productname>Pgpool-II</productname>を起動します。
+ </para>
+<programlisting>
+# systemctl start pgpool.service
+</programlisting>
+
+ <sect3 id="example-cluster-try-standby">
+ <title>PostgreSQL スタンバイサーバを構築</title>
+ <para>
+まず、<productname>Pgpool-II</productname>のオンラインリカバリ機能を利用し、スタンバイサーバを構築します。<command>pcp_recovery_node</command>コマンドで実行される<varname>recovery_1st_stage_command</varname>パラメータに指定した<filename>recovery_1st_stage</filename>と<filename>pgpool_remote_start</filename>スプリクトが実行されるので、この 2つのスクリプトが現在稼働中のプライマリサーバ<literal>server1</literal>のデータベースクラスタの下に存在することを確認します。
+ </para>
+<programlisting>
+# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 1
+Password:
+pcp_recovery_node -- Command Successful
+
+# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 2
+Password:
+pcp_recovery_node -- Command Successful
+</programlisting>
+ <para>
+<literal>server2</literal>と<literal>server3</literal>の<productname>PostgreSQL</productname>がスタンバイとして起動されていることを確認します。
+ </para>
+<programlisting>
+# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
+Password for user pgpool:
+node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
+---------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
+0 | server1 | 5432 | up | 0.333333 | primary | 0 | false | 0 | | | 2019-08-06 11:13:17
+1 | server2 | 5432 | up | 0.333333 | standby | 0 | true | 0 | streaming | async | 2019-08-06 11:13:25
+2 | server3 | 5432 | up | 0.333333 | standby | 0 | false | 0 | streaming | async | 2019-08-06 11:14:20
+(3 rows)
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-try-watchdog">
+ <title>watchdogアクティブ/スタンバイの切り替え</title>
+ <para>
+<command>pcp_watchdog_info</command>で<productname>Pgpool-II</productname>の<application>watchdog</application>の情報を確認します。最初に起動した<productname>Pgpool-II</productname>が「MASTER」になります。
+ </para>
+<programlisting>
+# pcp_watchdog_info -h 192.168.137.150 -p 9898 -U pgpool
+Password:
+3 YES server1:9999 Linux server1 server1
+
+server1:9999 Linux server1 server1 9999 9000 4 MASTER #最初に起動されたサーバがMASTERになる
+server2:9999 Linux server2 server2 9999 9000 7 STANDBY #スタンバイとして稼働
+server3:9999 Linux server3 server3 9999 9000 7 STANDBY #スタンバイとして稼働
+</programlisting>
+ <para>
+アクティブである<literal>server1</literal>の<productname>Pgpool-II</productname>を停止し、<literal>server2</literal>または<literal>server3</literal>がスタンバイからアクティブに昇格することを確認します。<literal>server1</literal>を停止する方法は<productname>Pgpool-II</productname>を停止する、またはマシンをシャットダウンします。ここでは、<productname>Pgpool-II</productname>を停止します。
+ </para>
+<programlisting>
+[server1]# systemctl stop pgpool.service
+
+# pcp_watchdog_info -p 9898 -h 192.168.137.150 -U pgpool
+Password:
+3 YES server2:9999 Linux server2 server2
+
+server2:9999 Linux server2 server2 9999 9000 4 MASTER #server2がアクティブに昇格
+server1:9999 Linux server1 server1 9999 9000 10 SHUTDOWN #server1が停止された
+server3:9999 Linux server3 server3 9999 9000 7 STANDBY #スタンバイとして稼働
+</programlisting>
+ <para>
+先ほど停止した<productname>Pgpool-II</productname>を再起動し、スタンバイとして起動したことを確認します。
+ </para>
+<programlisting>
+[server1]# systemctl start pgpool.service
+
+[server1]# pcp_watchdog_info -p 9898 -h 192.168.137.150 -U pgpool
+Password:
+3 YES server2:9999 Linux server2 server2
+
+server2:9999 Linux server2 server2 9999 9000 4 MASTER
+server1:9999 Linux server1 server1 9999 9000 7 STANDBY
+server3:9999 Linux server3 server3 9999 9000 7 STANDBY
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-try-failover">
+ <title>自動フェイルオーバ</title>
+ <para>
+<command>psql</command>で仮想IPに接続し、バックエンドの情報を確認します。
+ </para>
+<programlisting>
+# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
+Password for user pgpool:
+node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
+---------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
+0 | server1 | 5432 | up | 0.333333 | primary | 0 | false | 0 | | | 2019-08-06 11:13:17
+1 | server2 | 5432 | up | 0.333333 | standby | 0 | true | 0 | streaming | async | 2019-08-06 11:13:25
+2 | server3 | 5432 | up | 0.333333 | standby | 0 | false | 0 | streaming | async | 2019-08-06 11:14:20
+(3 rows)
+</programlisting>
+ <para>
+次にプライマリである<literal>server1</literal>の<productname>PostgreSQL</productname>を停止し、フェイルオーバするかどうか確認してみます。
+ </para>
+<programlisting>
+[server1]$ pg_ctl -D /var/lib/pgsql/11/data -m immediate stop
+</programlisting>
+ <para>
+<literal>ノード1</literal>を停止後、フェイルオーバが発生し、<literal>server2</literal>がプライマリに昇格したことを確認します。
+ </para>
+<programlisting>
+# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
+Password for user pgpool:
+node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
+---------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
+0 | server1 | 5432 | down | 0.333333 | standby | 0 | false | 0 | | | 2019-08-06 11:36:03
+1 | server2 | 5432 | up | 0.333333 | primary | 0 | true | 0 | | | 2019-08-06 11:36:03
+2 | server3 | 5432 | up | 0.333333 | standby | 0 | false | 0 | streaming | async | 2019-08-06 11:36:15
+(3 rows)
+</programlisting>
+
+ <para>
+<literal>server3</literal>が新しいプライマリ<literal>server2</literal>のスタンバイとして起動されています。
+ </para>
+
+<programlisting>
+[server3]# psql -h server3 -p 5432 -U pgpool postgres -c "select pg_is_in_recovery()"
+pg_is_in_recovery
+-------------------
+t
+
+[server2]# psql -h server2 -p 5432 -U pgpool postgres -c "select pg_is_in_recovery()"
+pg_is_in_recovery
+-------------------
+f
+
+[server2]# psql -h server2 -p 5432 -U pgpool postgres -c "select * from pg_stat_replication" -x
+-[ RECORD 1 ]----+------------------------------
+pid | 11059
+usesysid | 16392
+usename | repl
+application_name | server3
+client_addr | 192.168.137.103
+client_hostname |
+client_port | 48694
+backend_start | 2019-08-06 11:36:07.479161+09
+backend_xmin |
+state | streaming
+sent_lsn | 0/75000148
+write_lsn | 0/75000148
+flush_lsn | 0/75000148
+replay_lsn | 0/75000148
+write_lag |
+flush_lag |
+replay_lag |
+sync_priority | 0
+sync_state | async
+reply_time | 2019-08-06 11:42:59.823961+09
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-try-online-recovery">
+<title>オンラインリカバリ</title>
+ <para>
+次に、<productname>Pgpool-II</productname>のオンラインリカバリ機能を利用し、先ほど停止した旧プライマリサーバをスタンバイとして復旧させます。<command>pcp_recovery_node</command>コマンドで実行される<varname>recovery_1st_stage_command</varname>パラメータに指定した<filename>recovery_1st_stage</filename>と<filename>pgpool_remote_start</filename>スプリクトが現在稼働中のプライマリサーバ<literal>server2</literal>のデータベースクラスタの下に存在することを確認します。
+ </para>
+<programlisting>
+# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 0
+Password:
+pcp_recovery_node -- Command Successful
+</programlisting>
+ <para>
+<literal>ノード1</literal>がスタンバイとして起動されたことを確認します。
+ </para>
+<programlisting>
+# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
+Password for user pgpool:
+node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
+---------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
+0 | server1 | 5432 | up | 0.333333 | standby | 0 | false | 0 | streaming | async | 2019-08-06 11:48:05
+1 | server2 | 5432 | up | 0.333333 | primary | 0 | false | 0 | | | 2019-08-06 11:36:03
+2 | server3 | 5432 | up | 0.333333 | standby | 0 | true | 0 | streaming | async | 2019-08-06 11:36:15
+(3 rows)
+</programlisting>
+ <para>
+以上で、動作確認が完了です。
+ </para>
+ </sect3>
+</sect2>
+</sect1>
diff --git a/doc.ja/src/sgml/example-watchdog.sgml b/doc.ja/src/sgml/example-watchdog.sgml
new file mode 100644
index 000000000..2b19979bc
--- /dev/null
+++ b/doc.ja/src/sgml/example-watchdog.sgml
@@ -0,0 +1,501 @@
+<!-- doc/src/sgml/example-watchdog.sgml -->
+
+<sect1 id="example-watchdog">
+<!--
+<title>Watchdog Configuration Example</title>
+-->
+<title>Watchdogの設定例</title>
+
+<para>
+<!--
+ This tutorial explains the simple way to try "Watchdog".
+ What you need is 2 Linux boxes on which <productname>
+ Pgpool-II</productname> is installed and a <productname>PostgreSQL</>
+ on the same machine or in the other one. It is enough
+ that 1 node for backend exists.
+ You can use watchdog with <productname>
+ Pgpool-II</productname> in any mode: replication mode,
+ master/slave mode and raw mode.
+-->
+ここではwatchdogの機能を簡単に試す方法を説明します。
+Linux マシン2台にそれぞれ <productname>Pgpool-II</> がインストールされているものとします。
+また、いずれかのマシンか第 3 のマシンに、<productname>PostgreSQL</> がインストールされて稼働しているものとします。
+バックエンドノードは1台でかまいません。
+<productname>Pgpool-II</> がどのモードで稼働していても（レプリケーションモードでもマスタースレーブモードでも）、watchdogを利用することができます。
+</para>
+<para>
+<!--
+ This example uses use "osspc16" as an Active node and
+ "osspc20" as a Standby node. "Someserver" means one of them.
+-->
+この例では、「osspc16」をActiveノードとして、「osspc20」をStandbyノードとして使います。
+「someserver」は、これらのどちらかということを意味しています。
+</para>
+
+ <sect2 id="example-watchdog-configuration">
+<!--
+ <title>Common configurations</title>
+-->
+ <title>共通設定</title>
+ <para>
+<!--
+ Set the following parameters in both of active and standby nodes.
+-->
+アクティブとスタンバイの両サーバで以下を設定します。
+ </para>
+
+ <sect3 id="example-watchdog-config-enable">
+<!--
+ <title>Enabling watchdog</title>
+-->
+ <title>Watchdogの有効化</title>
+ <para>
+<!--
+ First of all, set <xref linkend="guc-use-watchdog"> to on.
+-->
+まず、<xref linkend="guc-use-watchdog">をonにします。
+ <programlisting>
+use_watchdog = on
+ # Activates watchdog
+ </programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-config-upstream">
+<!--
+ <title>Configure Up stream servers</title>
+-->
+ <title>上位サーバの設定</title>
+ <para>
+<!--
+ Specify the up stream servers (e.g. application servers).
+ Leaving it blank is also fine.
+-->
+上流のサーバ（アプリケーションサーバなど）を指定します。
+空欄にしておいても構いません。
+ <programlisting>
+trusted_servers = ''
+ # trusted server list which are used
+ # to confirm network connection
+ # (hostA,hostB,hostC,...)
+ </programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-config-wd-comm">
+<!--
+ <title>Watchdog Communication</title>
+-->
+ <title>Watchdog通信</title>
+ <para>
+<!--
+ Specify the TCP port number for watchdog communication.
+-->
+watchdog通信を行うTCPポート番号を指定します。
+ <programlisting>
+wd_port = 9000
+ # port number for watchdog service
+ </programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-config-wd-vip">
+<!--
+ <title>Virtual IP</title>
+-->
+ <title>仮想IP</title>
+ <para>
+<!--
+ Specify the IP address to be used as a virtual IP address
+ in the <xref linkend="guc-delegate-IP">.
+-->
+仮想IPを<xref linkend="guc-delegate-IP">に設定します。
+ <programlisting>
+delegate_IP = '133.137.177.143'
+ # delegate IP address
+ </programlisting>
+ </para>
+ <note>
+ <para>
+<!--
+ Make sure the IP address configured as a Virtual IP should be
+ free and is not used by any other machine.
+-->
+仮想IPに設定されるIPアドレスは空いており他のマシンで使用されていないことを確認してください。
+ </para>
+ </note>
+ </sect3>
+</sect2>
+
+ <sect2 id="example-watchdog-configuration-each-server">
+<!--
+ <title>Individual Server Configurations</title>
+-->
+ <title>個々のサーバ設定</title>
+ <para>
+<!--
+ Next, set the following parameters for each <productname>
+ Pgpool-II</productname>.
+ Specify <xref linkend="guc-other-pgpool-hostname">,
+ <xref linkend="guc-other-pgpool-port"> and
+ <xref linkend="guc-other-wd-port"> with the values of
+ other <productname>Pgpool-II</productname> server values.
+-->
+次に、それぞれの<productname>Pgpool-II</>で以下のパラメータを設定します。
+<xref linkend="guc-other-pgpool-hostname">、<xref linkend="guc-other-pgpool-port">、<xref linkend="guc-other-wd-port">を他の<productname>Pgpool-II</>の値で設定します。
+ </para>
+
+ <sect3 id="example-watchdog-configuration-active-server">
+<!--
+ <title>Active (osspc16) Server configurations</title>
+-->
+ <title>Activeサーバの設定(osspc16)</title>
+ <para>
+ <programlisting>
+other_pgpool_hostname0 = 'osspc20'
+ # Host name or IP address to connect to for other pgpool 0
+other_pgpool_port0 = 9999
+ # Port number for other pgpool 0
+other_wd_port0 = 9000
+ # Port number for other watchdog 0
+ </programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-configuration-standby-server">
+<!--
+ <title>Standby (osspc20) Server configurations</title>
+-->
+ <title>Standbyサーバの設定(osspc20)</title>
+ <para>
+ <programlisting>
+other_pgpool_hostname0 = 'osspc16'
+ # Host name or IP address to connect to for other pgpool 0
+other_pgpool_port0 = 9999
+ # Port number for other pgpool 0
+other_wd_port0 = 9000
+ # Port number for other watchdog 0
+ </programlisting>
+ </para>
+ </sect3>
+</sect2>
+
+ <sect2 id="example-watchdog-start-server">
+<!--
+ <title>Starting <productname>Pgpool-II</productname></title>
+-->
+ <title><productname>Pgpool-II</productname>の起動</title>
+ <para>
+<!--
+ Start <productname>Pgpool-II</productname> on each servers from
+ <literal>root</literal> user with <literal>"-n"</literal> switch
+ and redirect log messages into pgpool.log file.
+-->
+両方のサーバで<productname>Pgpool-II</>を<literal>root</literal>ユーザで、<literal>"-n"</literal>オプションを付けて起動し、ログメッセージはpgpool.logファイルにリダイレクトします。
+ </para>
+
+ <sect3 id="example-watchdog-start-active-server">
+<!--
+ <title>Starting pgpool in Active server (osspc16)</title>
+-->
+ <title>ActiveサーバでのPgpool-II起動(osspc16)</title>
+ <para>
+<!--
+ First start the <productname>Pgpool-II</productname> on Active server.
+-->
+最初に、Active サーバで<productname>Pgpool-II</productname>を起動します。
+ <programlisting>
+[user@osspc16]$ su -
+[root@osspc16]# {installed_dir}/bin/pgpool -n -f {installed_dir}/etc/pgpool.conf > pgpool.log 2>&1
+ </programlisting>
+<!--
+ Log messages will show that <productname>Pgpool-II</productname>
+ has the virtual IP address and starts watchdog process.
+-->
+ログから、仮想IP アドレスを使用し、またwatchdogプロセス起動したことが確認できます。
+ <programlisting>
+LOG: I am announcing my self as master/coordinator watchdog node
+LOG: I am the cluster leader node
+DETAIL: our declare coordinator message is accepted by all nodes
+LOG: I am the cluster leader node. Starting escalation process
+LOG: escalation process started with PID:59449
+<emphasis>LOG: watchdog process is initialized
+LOG: watchdog: escalation started
+LOG: I am the master watchdog node</emphasis>
+DETAIL: using the local backend node status
+ </programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-start-standby-server">
+<!--
+ <title>Starting pgpool in Standby server (osspc20)</title>
+-->
+ <title>StandbyサーバでのPgpool-II起動(osspc20)</title>
+ <para>
+<!--
+ Now start the <productname>Pgpool-II</productname> on Standby server.
+-->
+次に、Standbyサーバで<productname>Pgpool-II</>を起動します。
+ <programlisting>
+[user@osspc20]$ su -
+[root@osspc20]# {installed_dir}/bin/pgpool -n -f {installed_dir}/etc/pgpool.conf > pgpool.log 2>&1
+ </programlisting>
+<!--
+ Log messages will show that <productname>Pgpool-II</productname>
+ has joind the watchdog cluster as standby watchdog.
+-->
+ログメッセージから<productname>Pgpool-II</productname>がwatchdogクラスタにスタンバイとして参加したことがわかります。
+ <programlisting>
+LOG: watchdog cluster configured with 1 remote nodes
+LOG: watchdog remote node:0 on Linux_osspc16_9000:9000
+LOG: interface monitoring is disabled in watchdog
+LOG: IPC socket path: "/tmp/.s.PGPOOLWD_CMD.9000"
+LOG: watchdog node state changed from [DEAD] to [LOADING]
+LOG: new outbound connection to Linux_osspc16_9000:9000
+LOG: watchdog node state changed from [LOADING] to [INITIALIZING]
+LOG: watchdog node state changed from [INITIALIZING] to [STANDBY]
+<emphasis>
+LOG: successfully joined the watchdog cluster as standby node
+DETAIL: our join coordinator request is accepted by cluster leader node "Linux_osspc16_9000"
+LOG: watchdog process is initialized
+</emphasis>
+ </programlisting>
+ </para>
+ </sect3>
+</sect2>
+
+<sect2 id="example-watchdog-try">
+<!--
+ <title>Try it out</title>
+-->
+ <title>動作確認</title>
+ <para>
+<!--
+ Confirm to ping to the virtual IP address.
+-->
+仮想 IP アドレスに、pingが通ることを確認します。
+ <programlisting>
+[user@someserver]$ ping 133.137.177.143
+PING 133.137.177.143 (133.137.177.143) 56(84) bytes of data.
+64 bytes from 133.137.177.143: icmp_seq=1 ttl=64 time=0.328 ms
+64 bytes from 133.137.177.143: icmp_seq=2 ttl=64 time=0.264 ms
+64 bytes from 133.137.177.143: icmp_seq=3 ttl=64 time=0.412 ms
+ </programlisting>
+<!--
+ Confirm if the Active server which started at first has the virtual IP address.
+-->
+先に<productname>Pgpool-II</>を起動したActiveサーバが、仮想IPアドレスを使っていることを確認します。
+ <programlisting>
+[root@osspc16]# ifconfig
+eth0 ...
+
+eth0:0 inet addr:133.137.177.143 ...
+
+lo ...
+ </programlisting>
+<!--
+ Confirm if the Standby server which started not at first doesn't have the virtual IP address.
+-->
+後から<productname>Pgpool-II</>を立ち上げたStandbサーバは、仮想IPアドレスを使っていないことを確認します。
+ <programlisting>
+[root@osspc20]# ifconfig
+eth0 ...
+
+lo ...
+ </programlisting>
+
+<!--
+ Try to connect <productname>PostgreSQL</> by "psql -h delegate_IP -p port".
+-->
+仮想IPアドレスを使って、<productname>PostgreSQL</> に接続をできることを確認します。
+ <programlisting>
+[user@someserver]$ psql -h 133.137.177.143 -p 9999 -l
+ </programlisting>
+ </para>
+</sect2>
+
+<sect2 id="example-watchdog-vip-switch">
+<!--
+ <title>Switching virtual IP</title>
+-->
+ <title>仮想IPの切り替え</title>
+ <para>
+<!--
+ Confirm how the Standby server works when the Active server can't provide its service.
+ Stop <productname>Pgpool-II</productname> on the Active server.
+-->
+Activeサーバがサービス供給不可な状態になったときに、Standbyがそれを引き継ぐのを確認します。
+Activeサーバの<productname>Pgpool-II</>を停止します。
+ <programlisting>
+[root@osspc16]# {installed_dir}/bin/pgpool stop
+ </programlisting>
+
+<!--
+ Then, the Standby server starts to use the virtual IP address. Log shows:
+-->
+するとStandbyサーバで、仮想IPアドレスを使用しはじめたというログメッセージが出力されます。
+
+ <programlisting>
+<emphasis>
+LOG: remote node "Linux_osspc16_9000" is shutting down
+LOG: watchdog cluster has lost the coordinator node
+</emphasis>
+LOG: watchdog node state changed from [STANDBY] to [JOINING]
+LOG: watchdog node state changed from [JOINING] to [INITIALIZING]
+LOG: I am the only alive node in the watchdog cluster
+HINT: skipping stand for coordinator state
+LOG: watchdog node state changed from [INITIALIZING] to [MASTER]
+LOG: I am announcing my self as master/coordinator watchdog node
+LOG: I am the cluster leader node
+DETAIL: our declare coordinator message is accepted by all nodes
+<emphasis>
+LOG: I am the cluster leader node. Starting escalation process
+LOG: watchdog: escalation started
+</emphasis>
+LOG: watchdog escalation process with pid: 59551 exit with SUCCESS.
+ </programlisting>
+
+<!--
+ Confirm to ping to the virtual IP address.
+-->
+仮想 IP アドレスに、pingが通ることを確認します。
+ <programlisting>
+[user@someserver]$ ping 133.137.177.143
+PING 133.137.177.143 (133.137.177.143) 56(84) bytes of data.
+64 bytes from 133.137.177.143: icmp_seq=1 ttl=64 time=0.328 ms
+64 bytes from 133.137.177.143: icmp_seq=2 ttl=64 time=0.264 ms
+64 bytes from 133.137.177.143: icmp_seq=3 ttl=64 time=0.412 ms
+ </programlisting>
+
+<!--
+ Confirm that the Active server doesn't use the virtual IP address any more.
+-->
+Activeではもう仮想IPアドレスが使われなくなったのを確認します。
+ <programlisting>
+[root@osspc16]# ifconfig
+eth0 ...
+
+lo ...
+ </programlisting>
+
+<!--
+ Confirm that the Standby server uses the virtual IP address.
+-->
+Standbyで仮想IP アドレスが使われていることを確認します。
+ <programlisting>
+[root@osspc20]# ifconfig
+eth0 ...
+
+eth0:0 inet addr:133.137.177.143 ...
+
+lo ...
+ </programlisting>
+
+<!--
+ Try to connect <productname>PostgreSQL</> by "psql -h delegate_IP -p port".
+-->
+仮想IPアドレスを使って、<productname>PostgreSQL</>に接続できることを確認します。
+ <programlisting>
+[user@someserver]$ psql -h 133.137.177.143 -p 9999 -l
+ </programlisting>
+
+ </para>
+</sect2>
+
+<sect2 id="example-watchdog-more">
+<!--
+ <title>More</title>
+-->
+ <title>応用</title>
+
+ <sect3 id="example-watchdog-more-lifecheck">
+<!--
+ <title>Lifecheck</title>
+-->
+ <title>死活監視</title>
+ <para>
+<!--
+ There are the parameters about watchdog's monitoring.
+ Specify the interval to check <xref linkend="guc-wd-interval"> and
+ the type of lifecheck <xref linkend="guc-wd-lifecheck-method">.
+ The <literal>hearbeat</literal> method specify the time to detect
+ a fault <xref linkend="guc-wd-heartbeat-deadtime">, the port number to
+ receive <xref linkend="guc-wd-heartbeat-port">, the interval to send
+ <xref linkend="guc-wd-heartbeat-keepalive">, the IP address or hostname
+ of destination <xref linkend="guc-heartbeat-destination"> and finally
+ the destination port number <xref linkend="guc-heartbeat-destination-port">.
+-->
+watchdog の監視方法について設定するパラメータがあります。
+監視間隔秒を指定する<xref linkend="guc-wd-interval">、死活監視のタイプを指定する<xref linkend="guc-wd-lifecheck-method">を記述します。
+<literal>heartbeat</literal>方式では、障害と判断する秒数を指定する<xref linkend="guc-wd-heartbeat-deadtime">、受信ポート番号を指定する<xref linkend="guc-wd-heartbeat-port">、ハートビート信号の送信間隔秒を指定する<xref linkend="guc-wd-heartbeat-keepalive">、送信先<xref linkend="guc-heartbeat-destination">、<xref linkend="guc-heartbeat-destination-port">を記述します。
+ <programlisting>
+wd_lifecheck_method = 'heartbeat'
+ # Method of watchdog lifecheck ('heartbeat' or 'query' or 'external')
+ # (change requires restart)
+wd_interval = 10
+ # lifecheck interval (sec) > 0
+wd_heartbeat_port = 9694
+ # Port number for receiving heartbeat signal
+ # (change requires restart)
+wd_heartbeat_keepalive = 2
+ # Interval time of sending heartbeat signal (sec)
+ # (change requires restart)
+wd_heartbeat_deadtime = 30
+ # Deadtime interval for heartbeat signal (sec)
+ # (change requires restart)
+heartbeat_destination0 = 'host0_ip1'
+ # Host name or IP address of destination 0
+ # for sending heartbeat signal.
+ # (change requires restart)
+heartbeat_destination_port0 = 9694
+ # Port number of destination 0 for sending
+ # heartbeat signal. Usually this is the
+ # same as wd_heartbeat_port.
+ # (change requires restart)
+ </programlisting>
+
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-more-vip-switching">
+<!--
+ <title>Switching virtual IP address</title>
+-->
+ <title>仮想IPの切り替え</title>
+ <para>
+<!--
+ There are the parameters for switching the virtual IP address.
+ Specify switching commands <xref linkend="guc-if-up-cmd">,
+ <xref linkend="guc-if-down-cmd">, the path to them
+ <xref linkend="guc-if-cmd-path">, the command executed after
+ switching to send ARP request <xref linkend="guc-arping-cmd">
+ and the path to it <xref linkend="guc-arping-path">.
+-->
+IP アドレスの切り替えコマンドについて設定するパラメータがあります。
+仮想 IP を切り替える際に使うコマンドとして<xref linkend="guc-if-up-cmd">、<xref linkend="guc-if-down-cmd">、そのパスを指定する<xref linkend="guc-if-cmd-path">を記述します。
+また、仮想IP切り替え後のARPリクエスト送信コマンドを指定する<xref linkend="guc-arping-cmd">、そのパスを指定する<xref linkend="guc-arping-path">を記述します。
+ <programlisting>
+if_cmd_path = '/sbin'
+ # path to the directory where if_up/down_cmd exists
+if_up_cmd = 'ip addr add $_IP_$/24 dev eth0 label eth0:0'
+ # startup delegate IP command
+if_down_cmd = 'ip addr del $_IP_$/24 dev eth0'
+ # shutdown delegate IP command
+
+arping_path = '/usr/sbin' # arping command path
+
+arping_cmd = 'arping -U $_IP_$ -w 1'
+ </programlisting>
+<!--
+ You can also bring up and bring down the virtual IP using arbitrary scripts
+ specified <xref linkend="guc-wd-escalation-command"> and
+ <xref linkend="guc-wd-de-escalation-command"> parameters.
+-->
+<xref linkend="guc-wd-escalation-command">および<xref linkend="guc-wd-de-escalation-command">パラメータに指定した任意のスクリプトで仮想IPの起動・停止を行うこともできます。
+
+ </para>
+ </sect3>
+
+ </sect2>
+</sect1>
diff --git a/doc.ja/src/sgml/examples.sgml b/doc.ja/src/sgml/examples.sgml
index 6db59b491..87d29fb86 100644
--- a/doc.ja/src/sgml/examples.sgml
+++ b/doc.ja/src/sgml/examples.sgml
@@ -2,2881 +2,29 @@
<part id="examples">
<!--
- <title>Examples</title>
+ <title>Examples</title>
-->
- <title>例集</title>
+ <title>例集</title>
- <partintro>
- <para>
+ <partintro>
+ <para>
<!--
- Various examples
+ Various examples
-->
様々な例
- </para>
+ </para>
- </partintro>
+ </partintro>
- <chapter id="example-configs">
+ <chapter id="example-configs">
<!--
- <title>Configuration Examples</title>
+ <title>Configuration Examples</title>
-->
- <title>設定の例</title>
-
- <sect1 id="example-basic">
-<!--
- <title>Basic Configuration Example</title>
--->
- <title>基本設定の例</title>
-
- <sect2 id="example-configs-begin">
-<!--
- <title>Let's Begin!</title>
--->
- <title>さあ始めましょう</title>
- <para>
-<!--
- First, we must learn how to install and configure <productname>Pgpool-II</productname> and database nodes before using replication.
--->
-ここでは、レプリケーションを行うための準備として、<productname>Pgpool-II</productname> のインストールや設定、データベースノードの準備について説明します。
- </para>
-
- <sect3 id="example-configs-begin-installing">
-<!--
- <title>Installing <productname>Pgpool-II</productname></title>
--->
- <title><productname>Pgpool-II</productname>のインストール</title>
- <para>
-<!--
- Installing <productname>Pgpool-II</productname> is very easy.
- In the directory which you have extracted the source tar ball,
- execute the following commands.
--->
-<productname>Pgpool-II</productname>のインストールはとても簡単です。
-ソースのtar ballを展開したディレクトリで以下のようにコマンドを実行します。
- <programlisting>
-$ ./configure
-$ make
-$ make install
- </programlisting>
-<!--
- <command>configure</command> script collects your system information
- and use it for the compilation procedure. You can pass command
- line arguments to <command>configure</> script to change the default behavior,
- such as the installation directory. <productname>Pgpool-II</productname>
- will be installed to <literal>/usr/local</literal> directory by default.
--->
-<link linkend="INSTALL-PGPOOL"><command>configure</command>スクリプト</link>はシステム情報を収集しコンパイル処理に利用します。
-<command>configure</>スクリプトにコマンドライン引数を指定することにより、インストール先ディレクトリなど、デフォルトの動作を変更することができます。
-デフォルトでは<productname>Pgpool-II</> は<literal>/usr/local</literal>ディレクトリ以下にインストールされます。
- </para>
- <para>
-<!--
- <command>make</command> command compiles the source code, and
- <command>make install</command> will install the executables.
- You must have write permission on the installation directory.
- In this tutorial, we will install <productname>Pgpool-II
- </productname> in the default <literal>/usr/local</literal> directory.
--->
-<command>make</command>コマンドはソースコードはコンパイルし、<command>make install</command>コマンドで実行可能ファイルがインストールされます。
-インストール先ディレクトリに書き込み権限を持っている必要があります。
-ここでは、<productname>Pgpool-II</productname>は<literal>/usr/local</literal>にインストールすることにします。
- </para>
- <note>
- <para>
-<!--
- <productname>Pgpool-II</productname> requires <literal>libpq</literal>
- library in <productname>PostgreSQL</> 7.4 or later (version 3 protocol).
--->
-<productname>Pgpool-II</>は<productname>PostgreSQL</> 7.4 以降の<literal>libpq</literal>ライブラリ(3.0 プロトコル)を必要とします。
- </para>
- </note>
- <para>
-<!--
- If the <command>configure</command> script displays the following error message, the
- <literal>libpq</literal> library may not be installed, or it is not of version 3
--->
-<command>configure</command>スクリプトが以下のエラーメッセージを表示した場合、<literal>libpq</literal>ライブラリがインストールされていないか、バージョンが3.0でない可能性があります。
- <programlisting>
-configure: error: libpq is not installed or libpq is old
- </programlisting>
-<!--
- If the library is version 3, but the above message is still displayed, your
- <literal>libpq</literal> library is probably not recognized by the <command>
- configure</command> script.
- The <command>configure</command> script searches for <literal>libpq</literal>
- library under <literal>/usr/local/pgsql</literal>. If you have installed the
- <productname>PostgreSQL</> in a directory other than <literal>/usr/local/pgsql</literal>, use
- <literal>--with-pgsql</literal>, or <literal>--with-pgsql-includedir</literal>
- and <literal>--with-pgsql-libdir</literal> command line options when you
- execute <command>configure</command>.
--->
-プロトコルのバージョンが3.0の<literal>libpq</literal>ライブラリがインストールされているにも係わらず上記のエラーメッセージが表示される場合、<command>configure</command>スクリプトに<literal>libpq</literal>ライブラリが認識されていない可能性があります。
-<command>configure</command>スクリプトは標準では<literal>/usr/local/pgsql</literal>ディレクトリ以下から<literal>libpq</literal>ライブラリを検索します。
-<productname>PostgreSQL</>のインストール先が<literal>/usr/local/pgsql</literal>ディレクトリ以下でなければ、<command>configure</command>スクリプトを実行する際にコマンドライン引数として<literal>--with-pgsql</literal>や<literal>--with-pgsql-includedir</literal>、<literal>--with-pgsql-libdir</literal>オプションを指定してください。
- </para>
- </sect3>
-
- <sect3 id="example-configs-begin-config-files">
-<!--
- <title>Configuration Files</title>
--->
- <title>設定ファイルの作成</title>
- <para>
-<!--
- <productname>Pgpool-II</productname> configuration parameters are saved in the
- <literal>pgpool.conf</literal> file. The file is in <literal>"parameter = value"
- </literal> per line format. When you install <productname>Pgpool-II</productname>,
- <literal>pgpool.conf.sample</literal> is automatically created.
- We recommend copying and renaming it to <literal>pgpool.conf</literal>, and edit
- it as you like.
--->
-<productname>Pgpool-II</>の設定パラメータは<literal>pgpool.conf</literal>ファイルに保存されてします。
-ファイルは、1 行ごとに<literal>パラメータ名 = 値</literal>という書式です。
-<productname>Pgpool-II</> をインストールすると、<literal>pgpool.conf.sample</literal>ファイルが作成されます。
-それを<literal>pgpool.conf</literal>というファイル名にコピーしてから編集するといいでしょう。
- <programlisting>
-$ cp /usr/local/etc/pgpool.conf.sample /usr/local/etc/pgpool.conf
- </programlisting>
-<!--
- <productname>Pgpool-II</productname> only accepts connections from the localhost
- using port 9999 by the default. If you wish to receive conenctions from other hosts,
- set <xref linkend="guc-listen-addresses"> to <literal>'*'</literal>.
--->
-<productname>Pgpool-II</> はデフォルトではローカルホストからのポート番号9999への接続のみを受け付けます。
-<productname>Pgpool-II</> と異なるホストからの接続を受け付けたい場合は、<xref linkend="guc-listen-addresses">を<literal>'*'</literal>に設定します。
- <programlisting>
-listen_addresses = 'localhost'
-port = 9999
- </programlisting>
-<!--
- We will use the default parameters in this tutorial.
--->
-ここではデフォルトのパラメータを使うことにします。
- </para>
- </sect3>
-
- <sect3 id="example-configs-begin-config-pcp">
-<!--
- <title>Configuring <acronym>PCP</acronym> Commands</title>
--->
- <title><acronym>PCP</acronym>コマンドの設定</title>
-
- <para>
-<!--
- <productname>Pgpool-II</productname> has an interface for administrative
- purpose to retrieve information on database nodes, shutdown
- <productname>Pgpool-II</productname>, etc. via network. To use
- <acronym>PCP</acronym> commands, user authentication is required.
- This authentication is different from <productname>PostgreSQL</>'s user authentication.
- A user name and password need to be defined in the <literal>pcp.conf</literal>
- file. In the file, a user name and password are listed as a pair on each line,
- and they are separated by a colon (:). Passwords are encrypted in
- <literal>md5</literal> hash format.
--->
-<productname>Pgpool-II</productname>には、データベースノードの情報取得や<productname>Pgpool-II</productname>停止などをネットワーク越しに行える管理目的のインターフェイスがあります。
-<acronym>PCP</acronym>コマンドを使用するにはユーザ認証が必要になります。
-この認証は<productname>PostgreSQL</>ユーザの認証とは異なります。
-ユーザ名とパスワードが<literal>pcp.conf</literal>ファイルに定義されている必要があります。
-このファイルでは、1行ごとにユーザ名とパスワードがペアとしてリストされており、これらがコロン(:)で区切られています。
-パスワードは<literal>MD5</literal>ハッシュ形式で暗号化されている必要があります。
-
- <programlisting>
-postgres:e8a48653851e28c69d0506508fb27fc5
- </programlisting>
-
-<!--
- When you install <productname>Pgpool-II</productname>, <literal>pcp.conf.sample
- </literal> is automatically created. We recommend copying and renaming it
- to <literal>pcp.conf</literal>, and edit it.
--->
-<productname>Pgpool-II</> をインストールするとサンプルとして<literal>pcp.conf.sample</literal>が自動的に生成されます。
-それを<literal>pcp.conf</literal>というファイル名にコピーしてから編集するといいでしょう。
- <programlisting>
-$ cp /usr/local/etc/pcp.conf.sample /usr/local/etc/pcp.conf
- </programlisting>
-<!--
- To encrypt your password into md5 hash format, use the <command>pg_md5</command>
- command, which is installed as one of <productname>Pgpool-II</productname>'s
- executables. <command>pg_md5</command> takes text as a command line argument,
- and displays its md5-hashed text.
- For example, give <literal>"postgres"</literal> as the command line argument,
- and <command>pg_md5</command> displays md5-hashed text on its standard output.
--->
-パスワードをMD5ハッシュ形式に変換する際には、<productname>Pgpool-II</>とともにインストールされる<command>pg_md5</command>コマンドを使用します。
-<command>pg_md5</command>コマンドは、コマンドライン引数として文字列を指定すると、それをMD5ハッシュ化したものを表示します。
-例えば、以下のようにコマンドライン引数として<literal>"postgres"</literal>を指定して実行すると、それをMD5ハッシュ化しテキストが標準出力に表示されます。
- <programlisting>
-$ /usr/local/bin/pg_md5 postgres
-e8a48653851e28c69d0506508fb27fc5
- </programlisting>
-<!--
- PCP commands are executed via network, so the port number must be configured
- with <xref linkend="guc-pcp-port"> parameter in <literal>pgpool.conf</literal> file.
- We will use the default 9898 for <xref linkend="guc-pcp-port"> in this tutorial.
--->
-PCPコマンドはネットワークを通して実行されるので、ポート番号を<literal>pgpool.conf</literal>ファイルの<xref linkend="guc-pcp-port">パラメータに設定します。
-ここでは、<xref linkend="guc-pcp-port">のデフォルトである9898を使用することにします。
- <programlisting>
-pcp_port = 9898
- </programlisting>
- </para>
- </sect3>
-
-
- <sect3 id="example-configs-prep-db-nodes">
-<!--
- <title>Preparing Database Nodes</title>
--->
- <title>データベースノードの準備</title>
- <para>
-<!--
- Now, we need to set up backend <productname>PostgreSQL</> servers for <productname>Pgpool-II
- </productname>. These servers can be placed within the same host as
- <productname>Pgpool-II</productname>, or on separate machines. If you decide
- to place the servers on the same host, different port numbers must be assigned
- for each server. If the servers are placed on separate machines,
- they must be configured properly so that they can accept network
- connections from <productname>Pgpool-II</productname>.
--->
-次に、<productname>Pgpool-II</productname>のための<productname>PostgreSQL</>サーバを設定する必要があります。
-これらのサーバは、<productname>Pgpool-II</> と同じホストで起動しても、異なるホストであっても構いません。
-同じホストにサーバを配置するのならば、各サーバにそれぞれ異なるポート番号を割り合てなければなりません。
-異なるマシンで起動する場合は <productname>Pgpool-II</>からのネットワーク接続を受け入れられるよう適切に設定されている必要があります。
- <productname>Pgpool-II</> ではデータベースサーバごとにレプリケーションを行うので、チュートリアルのためのデータベースクラスタを作成したほうがいいでしょう。
- <programlisting>
-backend_hostname0 = 'localhost'
-backend_port0 = 5432
-backend_weight0 = 1
-backend_hostname1 = 'localhost'
-backend_port1 = 5433
-backend_weight1 = 1
-backend_hostname2 = 'localhost'
-backend_port2 = 5434
-backend_weight2 = 1
- </programlisting>
-
-<!--
- For <xref linkend="guc-backend-hostname">, <xref linkend="guc-backend-port">,
- <xref linkend="guc-backend-weight">, set the node's hostname, port number,
- and ratio for load balancing. At the end of each parameter string,
- node ID must be specified by adding positive integers starting with 0 (i.e. 0, 1, 2..).
--->
-<xref linkend="guc-backend-hostname">、<xref linkend="guc-backend-port">、<xref linkend="guc-backend-weight">には、ノードのホスト名、ポート番号、負荷分散の割合を設定します。
-各パラメータ名の後ろには、ノードIDが0から始まる整数(すなわち、0, 1, 2, ...)で指定されていなければなりません。
- </para>
- <note>
- <para>
-<!--
- <xref linkend="guc-backend-weight"> parameters for all nodes are
- set to 1, meaning that SELECT queries are equally distributed among
- three servers.
--->
-すべてのノードで<xref linkend="guc-backend-weight">パラメータが1に設定してるのは、SELECTクエリが３台のサーバで等しく分散されることを意味しています。
- </para>
- </note>
- </sect3>
-
- <sect3 id="example-configs-start-stop-pgpool">
-<!--
- <title>Starting/Stopping <productname>Pgpool-II</productname></title>
--->
- <title><productname>Pgpool-II</productname>の起動と停止</title>
- <para>
-<!--
- To fire up <productname>Pgpool-II</productname>, execute the following
- command on a terminal.
--->
-<productname>Pgpool-II</> を起動するにはターミナルで以下のコマンドを実行します。
-
- <programlisting>
-$ pgpool
- </programlisting>
-
-<!--
- The above command, however, prints no log messages because <productname>
- Pgpool-II</productname> detaches the terminal. If you want to show
- <productname>Pgpool-II</productname> log messages, you pass <literal>-n</literal>
- option to <command>pgpool</command> command so <productname>Pgpool-II</productname>
- is executed as non-daemon process, and the terminal will not be detached.
--->
-しかしこれでは、<productname>Pgpool-II</productname>が制御端末を切り離すため、ログが出力されません。
-<productname>Pgpool-II</productname>にログメッセージを表示させたい場合、<command>pgpool</command>コマンドに<literal>-n</literal>オプションを指定すると、<productname>Pgpool-II</productname>は非デーモンプロセスとして起動し、制御端末は切り離されません。
- <programlisting>
-$ pgpool -n &
- </programlisting>
-
-<!--
- The log messages are printed on the terminal, so it is recommended to use the following options.
--->
-コマンドを実行した端末にログメッセージが表示されるので、以下のようなオプションを使うことをお勧めします。
- <programlisting>
-$ pgpool -n -d > /tmp/pgpool.log 2>&1 &
- </programlisting>
-
-<!--
- The <literal>-d</literal> option enables debug messages to be generated.
- The above command keeps appending log messages to <literal>/tmp/pgpool.log
- </literal>. If you need to rotate log files, pass the logs to a external
- command which has log rotation function.
- For example, you can use <ulink url="https://httpd.apache.org/docs/2.4/programs/rotatelogs.html">
- <command>rotatelogs</command></ulink> from Apache2:
--->
--d オプションはデバッグメッセージの出力を有効にします。
-上記の例はファイルにリダイレクトさせているため、ログメッセージが<literal>/tmp/pgpool.log</literal>に追加され続けます。
-ログをローテートさせたい場合は、ローテート機能を持った外部コマンドにログを渡してください。
-たとえば、Apache2の<ulink url="https://httpd.apache.org/docs/2.4/programs/rotatelogs.html">rotatelogs</ulink>が使用できます。
-
- <programlisting>
-$ pgpool -n 2>&1 | /usr/local/apache2/bin/rotatelogs \
- -l -f /var/log/pgpool/pgpool.log.%A 86400 &
- </programlisting>
-
-<!--
- This will generate a log file named <literal>"pgpool.log.Thursday"</literal>
- then rotate it 00:00 at midnight. Rotatelogs adds logs to a file if it already
- exists. To delete old log files before rotation, you could use cron:
--->
-これにより毎日夜中の0時にログがローテートされ、<literal>pgpool.log.Thursday</literal>のような名前のログファイルが毎日作成されます。
-ただし、すでに同じ名前のファイルがある場合にはrotatelogsはログをそのファイルに追加してしまいます。
-cronを使うことで、古いログファイルをローテーションの前に削除することができます。
-
- <programlisting>
-55 23 * * * /usr/bin/find /var/log/pgpool -type f -mtime +5 -exec /bin/rm -f '{}' \;
- </programlisting>
-
-<!--
- Please note that rotatelogs may exist as <literal>/usr/sbin/rotatelogs2</literal>
- in some distributions. <literal>-f</literal> option generates a log file as soon as
- <command>rotatelogs</command> starts and is available in apache2 2.2.9 or greater.
- Also <ulink url="http://www.cronolog.org/">cronolog</ulink> can be used.
--->
-注意：Linuxディストリビューションによっては、rotatelogsは<literal>/usr/sbin/rotatelogs2</literal>として存在しているかもしれません。
-<literal>-f</literal>オプションは<command>rotatelogs</command>が起動された直後に直ちにログファイルを作るオプションで、apache2 2.2.9以降でのみ有効です。
-<ulink url="http://www.cronlog.org/">cronolog</ulink>を使うこともできます。
- <programlisting>
-$ pgpool -n 2>&1 | /usr/sbin/cronolog \
- --hardlink=/var/log/pgsql/pgpool.log \
- '/var/log/pgsql/%Y-%m-%d-pgpool.log' &
- </programlisting>
-
-<!--
- To stop <productname>Pgpool-II</> execute the following command.
--->
-<productname>Pgpool-II</> を停止するには以下のコマンドを実行します。
- <programlisting>
-$ pgpool stop
- </programlisting>
-
-<!--
- If any client is still connected, <productname>Pgpool-II</productname>
- waits for it to disconnect, and then terminates itself. Run the following
- command instead if you want to shutdown <productname>Pgpool-II</productname>
- forcibly.
--->
-<productname>Pgpool-II</> を停止する際にクライアントが接続している場合、<productname>Pgpool-II</productname>はその接続が切断されるまで待ってから停止します。
-<productname>Pgpool-II</>を強制的にシャットダウンしたい場合は、以下のコマンドを実行します。
- <programlisting>
-$ pgpool -m fast stop
- </programlisting>
-
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="example-configs-replication">
-<!--
- <title>Your First Replication</title>
--->
- <title>初めてのレプリケーション</title>
- <para>
-<!--
- Replication (see <xref linkend="runtime-config-replication-mode">) enables
- the same data to be copied to multiple database nodes.
- In this section, we'll use three database nodes, which we have already set
- up in <xref linkend="example-configs-begin">, and takes you step by step to
- create a database replication system.
- Sample data to be replicated will be generated by the
- <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
- <command>pgbench</command></ulink> benchmark program.
--->
-レプリケーション（<xref linkend="runtime-config-replication-mode">を参照）では複数のデータベースノードに同じデータを複製して格納します。
-ここでは、<xref linkend="example-configs-begin">で準備した 3 台のデータベースノードを使用し、一歩一歩データベースクラスタシステムを作っていきましょう。
-複製させるサンプルのデータは<ulink url="https://www.postgresql.org/docs/current/static/pgbench.html"><command>pgbench</command></ulink>ベンチマークプログラムで生成することにします。
- </para>
-
- <sect3 id="example-configs-config-replication">
-<!--
- <title>Configuring Replication</title>
--->
- <title>レプリケーションの設定</title>
- <para>
-<!--
- To enable the database replication function, set
- <xref linkend="guc-replication-mode"> to on in <literal>pgpool.conf</literal> file.
--->
-データベースノードのレプリケーションを有効にするには、<literal>pgpool.conf</literal>ファイルの<xref linkend="guc-replication-mode">をonに設定します。
- <programlisting>
-replication_mode = true
- </programlisting>
-<!--
- When <xref linkend="guc-replication-mode"> is on, <productname>Pgpool-II</productname>
- will send a copy of a received query to all the database nodes.
- In addition, when <xref linkend="guc-load-balance-mode"> is set to true,
- <productname>Pgpool-II</productname> will distribute <acronym>SELECT</acronym> queries
- among the database nodes.
--->
-<xref linkend="guc-replication-mode">をonに設定することにより、<productname>Pgpool-II</>は受信したクエリを全てのデータベースノードに送信します。
-対して実行され、同じデータが複製されて格納されるようになります。
-さらに、<xref linkend="guc-load-balance-mode">をonに設定することにより、<productname>Pgpool-II</>はSELECTクエリをデータベースノード間に振り分けます。
- <programlisting>
-load_balance_mode = true
- </programlisting>
-<!--
- In this section, we will enable both <xref linkend="guc-replication-mode">
- and <xref linkend="guc-load-balance-mode">.
--->
-ここでは、<xref linkend="guc-replication-mode">、<xref linkend="guc-load-balance-mode">の両方を有効にします。
- </para>
- </sect3>
-
- <sect3 id="example-configs-checking-replication">
-<!--
- <title>Checking Replication</title>
--->
- <title>レプリケーションの確認</title>
- <para>
-<!--
- To reflect the above changes in <literal>pgpool.conf</literal>,
- <productname>Pgpool-II</productname> must be restarted.
- Please refer to "Starting/Stopping <productname>Pgpool-II</productname>"
- <xref linkend="example-configs-start-stop-pgpool">.
- After configuring <literal>pgpool.conf</literal> and restarting the
- <productname>Pgpool-II</productname>, let's try the actual replication
- and see if everything is working.
- First, we need to create a database to be replicated. We will name it
- <literal>"bench_replication"</literal>. This database needs to be created
- on all the nodes. Use the
- <ulink url="https://www.postgresql.org/docs/current/static/app-createdb.html">
- <command>createdb</command></ulink> commands through
- <productname>Pgpool-II</productname>, and the database will be created
- on all the nodes.
--->
-上記の<literal>pgpool.conf</literal>の変更を<productname>Pgpool-II</>に反映させるには<productname>Pgpool-II</>を再起動する必要があります。
-「<productname>Pgpool-II</> の起動と停止」<xref linkend="example-configs-start-stop-pgpool">を参照してください。
-<literal>pgpool.conf</literal>の設定と再起動がすんだら、実際にレプリケーションを試してうまく行くことを確認しましょう。
-まず、複製するデータベースを作成する必要があります。
-これを<literal>"bench_replication"</literal>と名づけましょう。
-このデータベースが全てのノードで作成される必要があります。
-<ulink url="https://www.postgresql.org/docs/current/static/app-createdb.html"><command>createdb</command></ulink>コマンドを<productname>Pgpool-II</>経由で実行すると、すべてのノードでデータベースが作成されます。
- <programlisting>
-$ createdb -p 9999 bench_replication
- </programlisting>
-<!--
- Then, we'll execute <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
- <command>pgbench</command></ulink> with <literal>-i</literal> option.
- <literal>-i</literal> option initializes the database with pre-defined tables and data.
--->
-そして<ulink url="https://www.postgresql.org/docs/current/static/pgbench.html"><command>pgbench</command></ulink>に<literal>-i</literal>オプションを指定して実行します。
-<literal>-i</literal>オプションにより、データベースは事前に定義されたテーブルとデータで初期化されます。
- <programlisting>
-$ pgbench -i -p 9999 bench_replication
- </programlisting>
-<!--
- The following table is the summary of tables and data, which will be created by
- <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
- <command>pgbench -i</command></ulink>. If, on all the nodes, the listed tables and
- data are created, replication is working correctly.
--->
-<ulink url="https://www.postgresql.org/docs/current/static/pgbench.html"><command>pgbench -i</command></ulink>によって作成されるテーブルとデータを以下の表にまとめます。
-すべてのノードにおいてこれらのテーブルおよびデータが作成されていれば、正常にレプリケーションが動作していることになります。
- </para>
-
- <table id="example-configs-checking-replication-table">
- <title>data summary</title>
- <tgroup cols="2">
- <thead>
- <row>
-<!--
- <entry>Table Name</entry>
- <entry>Number of Rows</entry>
--->
- <entry>テーブル名</entry>
- <entry>行数</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>pgbench_branches</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>pgbench_tellers</entry>
- <entry>10</entry>
- </row>
-
- <row>
- <entry>pgbench_accounts</entry>
- <entry>100000</entry>
- </row>
-
- <row>
- <entry>pgbench_history</entry>
- <entry>0</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <para>
-<!--
- Let's use a simple shell script to check the above on all the nodes.
- The following script will display the number of rows in pgbench_branches,
- pgbench_tellers, pgbench_accounts, and pgbench_history tables on all the nodes (5432, 5433, 5434).
--->
-これをチェックするため、簡単なシェルスクリプトを実行してみましょう。
-以下のスクリプトはすべてのノード (ポート番号 5432、5433、5434) のデータベースにおけるpgbench_branches、pgbench_tellers、pgbench_accounts、pgbench_historyの行数が表示されます。
- <programlisting>
-$ for port in 5432 5433 5434; do
-> echo $port
-> for table_name in pgbench_branches pgbench_tellers pgbench_accounts pgbench_history; do
-> echo $table_name
-> psql -c "SELECT count(*) FROM $table_name" -p $port bench_replication
-> done
-> done
- </programlisting>
-
- </para>
- </sect3>
- </sect2>
-
- </sect1>
-
- <sect1 id="example-watchdog">
-<!--
- <title>Watchdog Configuration Example</title>
--->
- <title>Watchdogの設定例</title>
-
- <para>
-<!--
- This tutorial explains the simple way to try "Watchdog".
- What you need is 2 Linux boxes on which <productname>
- Pgpool-II</productname> is installed and a <productname>PostgreSQL</>
- on the same machine or in the other one. It is enough
- that 1 node for backend exists.
- You can use watchdog with <productname>
- Pgpool-II</productname> in any mode: replication mode,
- master/slave mode and raw mode.
--->
-ここではwatchdogの機能を簡単に試す方法を説明します。
-Linux マシン2台にそれぞれ <productname>Pgpool-II</> がインストールされているものとします。
-また、いずれかのマシンか第 3 のマシンに、<productname>PostgreSQL</> がインストールされて稼働しているものとします。
-バックエンドノードは1台でかまいません。
-<productname>Pgpool-II</> がどのモードで稼働していても（レプリケーションモードでもマスタースレーブモードでも）、watchdogを利用することができます。
- </para>
- <para>
-<!--
- This example uses use "osspc16" as an Active node and
- "osspc20" as a Standby node. "Someserver" means one of them.
--->
-この例では、「osspc16」をActiveノードとして、「osspc20」をStandbyノードとして使います。
-「someserver」は、これらのどちらかということを意味しています。
- </para>
-
- <sect2 id="example-watchdog-configuration">
-<!--
- <title>Common configurations</title>
--->
- <title>共通設定</title>
- <para>
-<!--
- Set the following parameters in both of active and standby nodes.
--->
-アクティブとスタンバイの両サーバで以下を設定します。
- </para>
-
- <sect3 id="example-watchdog-config-enable">
-<!--
- <title>Enabling watchdog</title>
--->
- <title>Watchdogの有効化</title>
- <para>
-<!--
- First of all, set <xref linkend="guc-use-watchdog"> to on.
--->
-まず、<xref linkend="guc-use-watchdog">をonにします。
- <programlisting>
-use_watchdog = on
- # Activates watchdog
- </programlisting>
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-config-upstream">
-<!--
- <title>Configure Up stream servers</title>
--->
- <title>上位サーバの設定</title>
- <para>
-<!--
- Specify the up stream servers (e.g. application servers).
- Leaving it blank is also fine.
--->
-上流のサーバ（アプリケーションサーバなど）を指定します。
-空欄にしておいても構いません。
- <programlisting>
-trusted_servers = ''
- # trusted server list which are used
- # to confirm network connection
- # (hostA,hostB,hostC,...)
- </programlisting>
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-config-wd-comm">
-<!--
- <title>Watchdog Communication</title>
--->
- <title>Watchdog通信</title>
- <para>
-<!--
- Specify the TCP port number for watchdog communication.
--->
-watchdog通信を行うTCPポート番号を指定します。
- <programlisting>
-wd_port = 9000
- # port number for watchdog service
- </programlisting>
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-config-wd-vip">
-<!--
- <title>Virtual IP</title>
--->
- <title>仮想IP</title>
- <para>
-<!--
- Specify the IP address to be used as a virtual IP address
- in the <xref linkend="guc-delegate-IP">.
--->
-仮想IPを<xref linkend="guc-delegate-IP">に設定します。
- <programlisting>
-delegate_IP = '133.137.177.143'
- # delegate IP address
- </programlisting>
- </para>
- <note>
- <para>
-<!--
- Make sure the IP address configured as a Virtual IP should be
- free and is not used by any other machine.
--->
-仮想IPに設定されるIPアドレスは空いており他のマシンで使用されていないことを確認してください。
- </para>
- </note>
- </sect3>
- </sect2>
-
- <sect2 id="example-watchdog-configuration-each-server">
-<!--
- <title>Individual Server Configurations</title>
--->
- <title>個々のサーバ設定</title>
- <para>
-<!--
- Next, set the following parameters for each <productname>
- Pgpool-II</productname>.
- Specify <xref linkend="guc-other-pgpool-hostname">,
- <xref linkend="guc-other-pgpool-port"> and
- <xref linkend="guc-other-wd-port"> with the values of
- other <productname>Pgpool-II</productname> server values.
--->
-次に、それぞれの<productname>Pgpool-II</>で以下のパラメータを設定します。
-<xref linkend="guc-other-pgpool-hostname">、<xref linkend="guc-other-pgpool-port">、<xref linkend="guc-other-wd-port">を他の<productname>Pgpool-II</>の値で設定します。
- </para>
-
- <sect3 id="example-watchdog-configuration-active-server">
-<!--
- <title>Active (osspc16) Server configurations</title>
--->
- <title>Activeサーバの設定(osspc16)</title>
- <para>
- <programlisting>
-other_pgpool_hostname0 = 'osspc20'
- # Host name or IP address to connect to for other pgpool 0
-other_pgpool_port0 = 9999
- # Port number for other pgpool 0
-other_wd_port0 = 9000
- # Port number for other watchdog 0
- </programlisting>
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-configuration-standby-server">
-<!--
- <title>Standby (osspc20) Server configurations</title>
--->
- <title>Standbyサーバの設定(osspc20)</title>
- <para>
- <programlisting>
-other_pgpool_hostname0 = 'osspc16'
- # Host name or IP address to connect to for other pgpool 0
-other_pgpool_port0 = 9999
- # Port number for other pgpool 0
-other_wd_port0 = 9000
- # Port number for other watchdog 0
- </programlisting>
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="example-watchdog-start-server">
-<!--
- <title>Starting <productname>Pgpool-II</productname></title>
--->
- <title><productname>Pgpool-II</productname>の起動</title>
- <para>
-<!--
- Start <productname>Pgpool-II</productname> on each servers from
- <literal>root</literal> user with <literal>"-n"</literal> switch
- and redirect log messages into pgpool.log file.
--->
-両方のサーバで<productname>Pgpool-II</>を<literal>root</literal>ユーザで、<literal>"-n"</literal>オプションを付けて起動し、ログメッセージはpgpool.logファイルにリダイレクトします。
- </para>
-
- <sect3 id="example-watchdog-start-active-server">
-<!--
- <title>Starting pgpool in Active server (osspc16)</title>
--->
- <title>ActiveサーバでのPgpool-II起動(osspc16)</title>
- <para>
-<!--
- First start the <productname>Pgpool-II</productname> on Active server.
--->
-最初に、Active サーバで<productname>Pgpool-II</productname>を起動します。
- <programlisting>
-[user@osspc16]$ su -
-[root@osspc16]# {installed_dir}/bin/pgpool -n -f {installed_dir}/etc/pgpool.conf > pgpool.log 2>&1
- </programlisting>
-<!--
- Log messages will show that <productname>Pgpool-II</productname>
- has the virtual IP address and starts watchdog process.
--->
-ログから、仮想IP アドレスを使用し、またwatchdogプロセス起動したことが確認できます。
- <programlisting>
-LOG: I am announcing my self as master/coordinator watchdog node
-LOG: I am the cluster leader node
-DETAIL: our declare coordinator message is accepted by all nodes
-LOG: I am the cluster leader node. Starting escalation process
-LOG: escalation process started with PID:59449
-<emphasis>LOG: watchdog process is initialized
-LOG: watchdog: escalation started
-LOG: I am the master watchdog node</emphasis>
-DETAIL: using the local backend node status
- </programlisting>
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-start-standby-server">
-<!--
- <title>Starting pgpool in Standby server (osspc20)</title>
--->
- <title>StandbyサーバでのPgpool-II起動(osspc20)</title>
- <para>
-<!--
- Now start the <productname>Pgpool-II</productname> on Standby server.
--->
-次に、Standbyサーバで<productname>Pgpool-II</>を起動します。
- <programlisting>
-[user@osspc20]$ su -
-[root@osspc20]# {installed_dir}/bin/pgpool -n -f {installed_dir}/etc/pgpool.conf > pgpool.log 2>&1
- </programlisting>
-<!--
- Log messages will show that <productname>Pgpool-II</productname>
- has joind the watchdog cluster as standby watchdog.
--->
-ログメッセージから<productname>Pgpool-II</productname>がwatchdogクラスタにスタンバイとして参加したことがわかります。
- <programlisting>
-LOG: watchdog cluster configured with 1 remote nodes
-LOG: watchdog remote node:0 on Linux_osspc16_9000:9000
-LOG: interface monitoring is disabled in watchdog
-LOG: IPC socket path: "/tmp/.s.PGPOOLWD_CMD.9000"
-LOG: watchdog node state changed from [DEAD] to [LOADING]
-LOG: new outbound connection to Linux_osspc16_9000:9000
-LOG: watchdog node state changed from [LOADING] to [INITIALIZING]
-LOG: watchdog node state changed from [INITIALIZING] to [STANDBY]
-<emphasis>
-LOG: successfully joined the watchdog cluster as standby node
-DETAIL: our join coordinator request is accepted by cluster leader node "Linux_osspc16_9000"
-LOG: watchdog process is initialized
-</emphasis>
- </programlisting>
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="example-watchdog-try">
-<!--
- <title>Try it out</title>
--->
- <title>動作確認</title>
- <para>
-<!--
- Confirm to ping to the virtual IP address.
--->
-仮想 IP アドレスに、pingが通ることを確認します。
- <programlisting>
-[user@someserver]$ ping 133.137.177.143
-PING 133.137.177.143 (133.137.177.143) 56(84) bytes of data.
-64 bytes from 133.137.177.143: icmp_seq=1 ttl=64 time=0.328 ms
-64 bytes from 133.137.177.143: icmp_seq=2 ttl=64 time=0.264 ms
-64 bytes from 133.137.177.143: icmp_seq=3 ttl=64 time=0.412 ms
- </programlisting>
-<!--
- Confirm if the Active server which started at first has the virtual IP address.
--->
-先に<productname>Pgpool-II</>を起動したActiveサーバが、仮想IPアドレスを使っていることを確認します。
- <programlisting>
-[root@osspc16]# ifconfig
-eth0 ...
-
-eth0:0 inet addr:133.137.177.143 ...
-
-lo ...
- </programlisting>
-<!--
- Confirm if the Standby server which started not at first doesn't have the virtual IP address.
--->
-後から<productname>Pgpool-II</>を立ち上げたStandbサーバは、仮想IPアドレスを使っていないことを確認します。
- <programlisting>
-[root@osspc20]# ifconfig
-eth0 ...
-
-lo ...
- </programlisting>
-
-<!--
- Try to connect <productname>PostgreSQL</> by "psql -h delegate_IP -p port".
--->
-仮想IPアドレスを使って、<productname>PostgreSQL</> に接続をできることを確認します。
- <programlisting>
-[user@someserver]$ psql -h 133.137.177.143 -p 9999 -l
- </programlisting>
- </para>
- </sect2>
-
- <sect2 id="example-watchdog-vip-switch">
-<!--
- <title>Switching virtual IP</title>
--->
- <title>仮想IPの切り替え</title>
- <para>
-<!--
- Confirm how the Standby server works when the Active server can't provide its service.
- Stop <productname>Pgpool-II</productname> on the Active server.
--->
-Activeサーバがサービス供給不可な状態になったときに、Standbyがそれを引き継ぐのを確認します。
-Activeサーバの<productname>Pgpool-II</>を停止します。
- <programlisting>
-[root@osspc16]# {installed_dir}/bin/pgpool stop
- </programlisting>
-
-<!--
- Then, the Standby server starts to use the virtual IP address. Log shows:
--->
-するとStandbyサーバで、仮想IPアドレスを使用しはじめたというログメッセージが出力されます。
-
- <programlisting>
-<emphasis>
-LOG: remote node "Linux_osspc16_9000" is shutting down
-LOG: watchdog cluster has lost the coordinator node
-</emphasis>
-LOG: watchdog node state changed from [STANDBY] to [JOINING]
-LOG: watchdog node state changed from [JOINING] to [INITIALIZING]
-LOG: I am the only alive node in the watchdog cluster
-HINT: skipping stand for coordinator state
-LOG: watchdog node state changed from [INITIALIZING] to [MASTER]
-LOG: I am announcing my self as master/coordinator watchdog node
-LOG: I am the cluster leader node
-DETAIL: our declare coordinator message is accepted by all nodes
-<emphasis>
-LOG: I am the cluster leader node. Starting escalation process
-LOG: watchdog: escalation started
-</emphasis>
-LOG: watchdog escalation process with pid: 59551 exit with SUCCESS.
- </programlisting>
-
-<!--
- Confirm to ping to the virtual IP address.
--->
-仮想 IP アドレスに、pingが通ることを確認します。
- <programlisting>
-[user@someserver]$ ping 133.137.177.143
-PING 133.137.177.143 (133.137.177.143) 56(84) bytes of data.
-64 bytes from 133.137.177.143: icmp_seq=1 ttl=64 time=0.328 ms
-64 bytes from 133.137.177.143: icmp_seq=2 ttl=64 time=0.264 ms
-64 bytes from 133.137.177.143: icmp_seq=3 ttl=64 time=0.412 ms
- </programlisting>
-
-<!--
- Confirm that the Active server doesn't use the virtual IP address any more.
--->
-Activeではもう仮想IPアドレスが使われなくなったのを確認します。
- <programlisting>
-[root@osspc16]# ifconfig
-eth0 ...
-
-lo ...
- </programlisting>
-
-<!--
- Confirm that the Standby server uses the virtual IP address.
--->
-Standbyで仮想IP アドレスが使われていることを確認します。
- <programlisting>
-[root@osspc20]# ifconfig
-eth0 ...
-
-eth0:0 inet addr:133.137.177.143 ...
-
-lo ...
- </programlisting>
-
-<!--
- Try to connect <productname>PostgreSQL</> by "psql -h delegate_IP -p port".
--->
-仮想IPアドレスを使って、<productname>PostgreSQL</>に接続できることを確認します。
- <programlisting>
-[user@someserver]$ psql -h 133.137.177.143 -p 9999 -l
- </programlisting>
-
- </para>
- </sect2>
-
- <sect2 id="example-watchdog-more">
-<!--
- <title>More</title>
--->
- <title>応用</title>
-
- <sect3 id="example-watchdog-more-lifecheck">
-<!--
- <title>Lifecheck</title>
--->
- <title>死活監視</title>
- <para>
-<!--
- There are the parameters about watchdog's monitoring.
- Specify the interval to check <xref linkend="guc-wd-interval"> and
- the type of lifecheck <xref linkend="guc-wd-lifecheck-method">.
- The <literal>hearbeat</literal> method specify the time to detect
- a fault <xref linkend="guc-wd-heartbeat-deadtime">, the port number to
- receive <xref linkend="guc-wd-heartbeat-port">, the interval to send
- <xref linkend="guc-wd-heartbeat-keepalive">, the IP address or hostname
- of destination <xref linkend="guc-heartbeat-destination"> and finally
- the destination port number <xref linkend="guc-heartbeat-destination-port">.
--->
-watchdog の監視方法について設定するパラメータがあります。
-監視間隔秒を指定する<xref linkend="guc-wd-interval">、死活監視のタイプを指定する<xref linkend="guc-wd-lifecheck-method">を記述します。
-<literal>heartbeat</literal>方式では、障害と判断する秒数を指定する<xref linkend="guc-wd-heartbeat-deadtime">、受信ポート番号を指定する<xref linkend="guc-wd-heartbeat-port">、ハートビート信号の送信間隔秒を指定する<xref linkend="guc-wd-heartbeat-keepalive">、送信先<xref linkend="guc-heartbeat-destination">、<xref linkend="guc-heartbeat-destination-port">を記述します。
- <programlisting>
-wd_lifecheck_method = 'heartbeat'
- # Method of watchdog lifecheck ('heartbeat' or 'query' or 'external')
- # (change requires restart)
-wd_interval = 10
- # lifecheck interval (sec) > 0
-wd_heartbeat_port = 9694
- # Port number for receiving heartbeat signal
- # (change requires restart)
-wd_heartbeat_keepalive = 2
- # Interval time of sending heartbeat signal (sec)
- # (change requires restart)
-wd_heartbeat_deadtime = 30
- # Deadtime interval for heartbeat signal (sec)
- # (change requires restart)
-heartbeat_destination0 = 'host0_ip1'
- # Host name or IP address of destination 0
- # for sending heartbeat signal.
- # (change requires restart)
-heartbeat_destination_port0 = 9694
- # Port number of destination 0 for sending
- # heartbeat signal. Usually this is the
- # same as wd_heartbeat_port.
- # (change requires restart)
- </programlisting>
-
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-more-vip-switching">
-<!--
- <title>Switching virtual IP address</title>
--->
- <title>仮想IPの切り替え</title>
- <para>
-<!--
- There are the parameters for switching the virtual IP address.
- Specify switching commands <xref linkend="guc-if-up-cmd">,
- <xref linkend="guc-if-down-cmd">, the path to them
- <xref linkend="guc-if-cmd-path">, the command executed after
- switching to send ARP request <xref linkend="guc-arping-cmd">
- and the path to it <xref linkend="guc-arping-path">.
--->
-IP アドレスの切り替えコマンドについて設定するパラメータがあります。
-仮想 IP を切り替える際に使うコマンドとして<xref linkend="guc-if-up-cmd">、<xref linkend="guc-if-down-cmd">、そのパスを指定する<xref linkend="guc-if-cmd-path">を記述します。
-また、仮想IP切り替え後のARPリクエスト送信コマンドを指定する<xref linkend="guc-arping-cmd">、そのパスを指定する<xref linkend="guc-arping-path">を記述します。
- <programlisting>
-if_cmd_path = '/sbin'
- # path to the directory where if_up/down_cmd exists
-if_up_cmd = 'ip addr add $_IP_$/24 dev eth0 label eth0:0'
- # startup delegate IP command
-if_down_cmd = 'ip addr del $_IP_$/24 dev eth0'
- # shutdown delegate IP command
-
-arping_path = '/usr/sbin' # arping command path
-
-arping_cmd = 'arping -U $_IP_$ -w 1'
- </programlisting>
-<!--
- You can also bring up and bring down the virtual IP using arbitrary scripts
- specified <xref linkend="guc-wd-escalation-command"> and
- <xref linkend="guc-wd-de-escalation-command"> parameters.
--->
-<xref linkend="guc-wd-escalation-command">および<xref linkend="guc-wd-de-escalation-command">パラメータに指定した任意のスクリプトで仮想IPの起動・停止を行うこともできます。
-
- </para>
- </sect3>
-
- </sect2>
- </sect1>
-
- <sect1 id="example-cluster">
- <title><productname>Pgpool-II</productname> + Watchdogの構築の例</title>
- <para>
-ここでは、ストリーミングレプリケーション構成の<productname>PostgreSQL</productname>を<productname>Pgpool-II</productname>で管理するシステムの構成例を示します。この例では、3台の<productname>Pgpool-II</productname>を使って<productname>PostgreSQL</productname>を管理し、単一障害点やスプリットブレインの起きない堅牢なクラスタを運用することが可能です。
- </para>
- <sect2 id="example-cluster-requirement">
- <title>前提条件</title>
- <para>
-<productname>Pgpool-II</productname>サーバと<productname>PostgreSQL</productname>サーバが同じサブネットにあることを前提とします。
- </para>
- </sect2>
-
- <sect2 id="example-cluster-structure">
- <title>全体構成</title>
- <para>
-今回は、Linuxサーバを3台用意し、それぞれのホスト名は 「server1」、「server2」、「server3」 とします。使用するOSはすべてCentOS 7.4とします。それぞれのサーバに<productname>PostgreSQL</productname>と<productname>Pgpool-II</productname>をインストールします。3台の<productname>PostgreSQL</productname>がストリーミングレプリケーション構成になります。全体構成図は以下の通りです。
- </para>
- <para>
- <figure>
- <title>全体構成図</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="cluster_40.gif">
- </imageobject>
- </mediaobject>
- </figure>
- </para>
- <note>
- <para>
-「アクティブ」「スタンバイ」「Primary」「Standby」といった役割は固定されているものではなく、運用と共に変化することがあります。
- </para>
- </note>
-
- <table id="example-cluster-table-ip">
- <title>ホスト名とIPアドレス</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>ホスト名</entry>
- <entry>IPアドバイス</entry>
- <entry>仮想IP</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>server1</entry>
- <entry>192.168.137.101</entry>
- <entry morerows="2">192.168.137.150</entry>
- </row>
- <row>
- <entry>server2</entry>
- <entry>192.168.137.102</entry>
- </row>
- <row>
- <entry>server3</entry>
- <entry>192.168.137.103</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table id="example-cluster-table-postgresql-config">
- <title>PostgreSQLのバージョンと設定情報</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>項目</entry>
- <entry>値</entry>
- <entry>説明</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>PostgreSQLバージョン</entry>
- <entry>11.1</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>ポート番号</entry>
- <entry>5432</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>$PGDATA</entry>
- <entry>/var/lib/pgsql/11/data</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>アーカイブモード</entry>
- <entry>有効</entry>
- <entry>/var/lib/pgsql/archivedir</entry>
- </row>
- <row>
- <entry>自動起動</entry>
- <entry>自動起動しない</entry>
- <entry>-</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
-
- <table id="example-cluster-table-pgpool-config">
- <title>Pgpool-IIのバージョンと設定情報</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>項目</entry>
- <entry>値</entry>
- <entry>説明</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Pgpool-IIバージョン</entry>
- <entry>4.0.2</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry morerows='3'>ポート番号</entry>
- <entry>9999</entry>
- <entry>Pgpool-IIが接続を受け付けるポート番号</entry>
- </row>
- <row>
- <entry>9898</entry>
- <entry>PCPプロセスが接続を受け付けるポート番号</entry>
- </row>
- <row>
- <entry>9000</entry>
- <entry>watchdogが接続を受け付けるポート番号</entry>
- </row>
- <row>
- <entry>9694</entry>
- <entry>Watchdogのハートビート信号を受信するUDPポート番号</entry>
- </row>
- <row>
- <entry>設定ファイル</entry>
- <entry>/etc/pgpool-II/pgpool.conf</entry>
- <entry>Pgpool-IIの設定ファイル</entry>
- </row>
- <row>
- <entry>Pgpool-II起動ユーザ</entry>
- <entry>root</entry>
- <entry>通常のユーザで<productname>Pgpool-II</productname>を起動する場合の設定方法は<xref linkend="TUTORIAL-WATCHDOG-START-STOP">をご参照ください。</entry>
- </row>
- <row>
- <entry>Pgpool-II動作モード</entry>
- <entry>ストリーミングレプリケーションモード</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>Watchdog機能</entry>
- <entry>有効</entry>
- <entry>ハードビート方式</entry>
- </row>
- <row>
- <entry>自動起動</entry>
- <entry>自動起動しない</entry>
- <entry>-</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
-
- <sect2 id="example-cluster-installation">
- <title>インストール</title>
- <para>
-すべてのサーバに<productname>PostgreSQL</productname> 11.1と<productname>Pgpool-II</productname> 4.0.2をRPMからインストールします。
- </para>
- <para>
-<productname>PostgreSQL</productname>のインストールは<productname>PostgreSQL</productname>コミュニティのリポジトリを使います。
- </para>
- <programlisting>
-# yum install https://download.postgresql.org/pub/repos/yum/11/redhat/rhel-7-x86_64/pgdg-centos11-11-2.noarch.rpm
-# yum install postgresql11 postgresql11-libs postgresql11-devel postgresql11-server
- </programlisting>
-
- <para>
-<productname>Pgpool-II</productname>のインストールは<productname>Pgpool-II</productname>開発コミュニティが提供するYumリポジトリを用いてインストールします。
- </para>
- <programlisting>
-# yum install http://www.pgpool.net/yum/rpms/4.0/redhat/rhel-7-x86_64/pgpool-II-release-4.0-1.noarch.rpm
-# yum install pgpool-II-pg11-*
- </programlisting>
- </sect2>
-
- <sect2 id="example-cluster-pre-setup">
- <title>事前設定</title>
-
- <itemizedlist>
- <listitem>
- <para>
-<productname>PostgreSQL</productname>プライマリサーバのみでストリーミングレプリケーションの設定を行います。設定方法についてはここでは省略します。
-スタンバイサーバの設定は、プライマリが起動した状態で、<productname>Pgpool-II</productname>のオンラインリカバリ機能を使って行います。
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
-この設定の例ではアーカイブリカバリを行うように設定します。
- </para>
- <para>
-まず、すべてのサーバにて<acronym>WAL</acronym>を格納するディレクトリ<filename>/var/lib/pgsql/archivedir</filename>を事前に作成します。
- </para>
- <programlisting>
-[全サーバ]# su - postgres
-[全サーバ]$ mkdir /var/lib/pgsql/archivedir
- </programlisting>
-
- <para>
-次に<literal>server1</literal>にて、設定ファイル<filename>$PGDATA/postgresql.conf</filename>を以下のように編集します。
- </para>
- <programlisting>
-listen_addresses = '*'
-archive_mode = on
-archive_command = 'cp "%p" "/var/lib/pgsql/archivedir/%f"'
- </programlisting>
- </listitem>
-
- <listitem>
- <para>
-Pgpool-IIのヘルスチェック及びレプリケーションの遅延チェックでPostgreSQLのユーザを設定する必要があります。セキュリティ上の理由で、この設定例ではスーパーユーザを使わないようにします。
-<productname>Pgpool-II</productname>のレプリケーションの遅延チェックとヘルスチェック用のユーザ<literal>pgpool</literal>を作成します。
-また、<productname>PostgreSQL</productname>プライマリサーバ<literal>server1</literal>でレプリケーション専用ユーザ<literal>repl</literal>を作成します。
-<productname>Pgpool-II</productname>4.0からSCRAM認証を利用できるようになりました。この設定例では、<literal>scram-sha-256</literal>認証方式を利用します。
-まず、<literal>password_encryption = 'scram-sha-256'</literal>に変更してから、ユーザを登録します。
- </para>
-
- <table id="example-cluster-user">
- <title>ユーザ</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>ユーザ名</entry>
- <entry>パスワード</entry>
- <entry>備考</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>repl</entry>
- <entry>repl</entry>
- <entry>PostgreSQLのレプリケーション専用ユーザ</entry>
- </row>
- <row>
- <entry>pgpool</entry>
- <entry>pgpool</entry>
- <entry>Pgpool-IIのレプリケーション遅延チェック、ヘルスチェック専用ユーザ</entry>
- </row>
- <row>
- <entry>postgres</entry>
- <entry>postgres</entry>
- <entry>オンラインリカバリを実行するユーザ</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <programlisting>
-[server1]# psql -U postgres -p 5432
-postgres=# SET password_encryption = 'scram-sha-256';
-postgres=# CREATE ROLE pgpool WITH LOGIN;
-postgres=# CREATE ROLE repl WITH REPLICATION;
-postgres=# \password pgpool
-postgres=# \password repl
-postgres=# \password postgres
- </programlisting>
-
- <note>
- <para>
-<xref linkend="guc-detach-false-primary">を利用する予定がある場合、"pgpool" ロールは<productname>PostgreSQL</productname>のスーパーユーザーであるか、"pg_monitor" グループに所属する必要があります。
-"pgpool"ユーザをそのグループに所属させるには以下のようにします。
- <programlisting>
-GRANT pg_monitor TO pgpool;
- </programlisting>
- </para>
- </note>
-
- <para>
-<productname>Pgpool-II</productname>サーバと<productname>PostgreSQL</productname>バックエンドサーバが<literal>192.168.137.0/24</literal>のネットワークにあることを想定し、各ユーザが<literal>scram-sha-256</literal>認証方式で接続できるように、<filename>pg_hba.conf</filename>を編集しておきます。
- </para>
- <programlisting>
-host all pgpool 192.168.137.0/24 scram-sha-256
-host all all 0.0.0.0/0 scram-sha-256
-
-host replication repl 192.168.137.0/24 scram-sha-256
- </programlisting>
- </listitem>
-
- <listitem>
- <para>
-自動フェイルオーバ、オンラインリカバリ機能を利用するために3台のサーバでは、<literal>postgres</literal>ユーザがパスワードなしで双方向に<command>ssh</command>接続できる状態にする必要があります。
- </para>
- </listitem>
-
- <listitem>
- <para>
-<literal>repl</literal>ユーザのパスワード入力なしで、ストリーミングレプリケーションとオンラインリカバリを行うために、すべてのサーバにて<literal>postgres</literal>ユーザのホームディレクト<filename>/var/lib/pgsql</filename> に<filename>.pgpass</filename>を作成・配置し、パーミッションを 600 に設定しておきます。
- </para>
- <programlisting>
-[全サーバ]# su - postgres
-[全サーバ]$ vi /var/lib/pgsql/.pgpass
-(以下を追加)
-server1:5432:replication:repl:<replユーザのパスワード>
-server2:5432:replication:repl:<replユーザのパスワード>
-server3:5432:replication:repl:<replユーザのパスワード>
-[全サーバ]$ chmod 600 /var/lib/pgsql/.pgpass
- </programlisting>
- </listitem>
-
- <listitem>
- <para>
-<productname>Pgpool-II</productname>や<productname>PostgreSQL</productname>に接続する際には、ファイアーウォールによって目的のポートが開けられていなければなりません。<systemitem>CentOS/RHEL7</systemitem>の場合、以下のように設定します。
- </para>
- <programlisting>
-[全サーバ]# firewall-cmd --permanent --zone=public --add-service=postgresql
-[全サーバ]# firewall-cmd --permanent --zone=public --add-port=9999/tcp --add-port=9898/tcp --add-port=9000/tcp --add-port=9694/tcp
-[全サーバ]# firewall-cmd --permanent --zone=public --add-port=9999/udp --add-port=9898/udp --add-port=9000/udp --add-port=9694/udp
-[全サーバ]# firewall-cmd --reload
- </programlisting>
- </listitem>
-
- </itemizedlist>
- </sect2>
-
- <sect2 id="example-cluster-pgpool-config">
- <title><productname>Pgpool-II</productname>の設定</title>
- <sect3 id="example-cluster-pgpool-config-common">
- <title>共通設定</title>
- <para>
-以下の操作は<literal>server1</literal>, <literal>server2</literal>, <literal>server3</literal>での共通の設定です。
- </para>
- <para>
-RPMからインストールした場合、すべての<productname>Pgpool-II</productname>の設定ファイルは<filename>/etc/pgpool-II</filename>にあります。今回はストリーミングレプリケーションモードのテンプレートとして<filename>pgpool.conf.sample-stream</filename>サンプルファイルを使用します。
- </para>
- <programlisting>
-[全サーバ]# cp /etc/pgpool-II/pgpool.conf.sample-stream /etc/pgpool-II/pgpool.conf
- </programlisting>
- <para>
-<productname>Pgpool-II</productname>が全てのIPアドレスから接続を受け付けるように、<xref linkend="GUC-LISTEN-ADDRESSES">パラメータに<literal>'*'</literal>を設定します。
- </para>
- <programlisting>
-listen_addresses = '*'
- </programlisting>
- <para>
-レプリケーションの遅延チェックユーザ<xref linkend="GUC-SR-CHECK-USER">にpgpoolユーザを設定します。
-この設定例では、<xref linkend="GUC-SR-CHECK-PASSWORD">は<filename>pgpool.conf</filename>に指定せず、<xref linkend="GUC-POOL-PASSWD">ファイルに作成します。<productname>Pgpool-II</productname> 4.0から、<xref linkend="GUC-SR-CHECK-PASSWORD">が空白の場合、<productname>Pgpool-II</productname>は空のパスワードを使用する前にまず<xref linkend="GUC-POOL-PASSWD">ファイルから<xref linkend="GUC-SR-CHECK-USER">に指定したユーザのパスワードを取得できるか試みます。
- </para>
- <programlisting>
-sr_check_user = 'pgpool'
-sr_check_password = ''
- </programlisting>
- <para>
-自動フェイルオーバのため、ヘルスチェックを有効にします。<xref linkend="GUC-HEALTH-CHECK-PERIOD">のデフォルト値が0で、これはヘルスチェックが無効であることを意味します。
-また、ネットワークが不安定な場合には、バックエンドが正常であるにも関わらず、ヘルスチェックに失敗し、フェイルオーバや縮退運転が発生してしまう可能性があります。そのようなヘルスチェックの誤検知を防止するため、ヘルスチェックのリトライ回数を<varname>health_check_max_retries = 3</varname> に設定しておきます。
-<xref linkend="GUC-HEALTH-CHECK-USER">、<xref linkend="GUC-HEALTH-CHECK-PASSWORD">は前述の<xref linkend="GUC-SR-CHECK-USER">、<xref linkend="GUC-SR-CHECK-PASSWORD">と同様に設定します。
- </para>
- <programlisting>
-health_check_period = 5
- # Health check period
- # Disabled (0) by default
-health_check_timeout = 30
- # Health check timeout
- # 0 means no timeout
-health_check_user = 'pgpool'
-health_check_password = ''
-
-health_check_max_retries = 3
- </programlisting>
- <para>
-また、バックエンド情報を前述の<literal>server1</literal>、<literal>server2</literal>及び<literal>server3</literal>の設定に従って設定しておきます。複数バックエンドノードを定義する場合、以下のbackend_*などのパラメータ名の末尾にノードIDを表す数字を付加することで複数のバックエンドを指定することができます。
- </para>
- <programlisting>
-# - Backend Connection Settings -
-
-backend_hostname0 = 'server1'
- # Host name or IP address to connect to for backend 0
-backend_port0 = 5432
- # Port number for backend 0
-backend_weight0 = 1
- # Weight for backend 0 (only in load balancing mode)
-backend_data_directory0 = '/var/lib/pgsql/11/data'
- # Data directory for backend 0
-backend_flag0 = 'ALLOW_TO_FAILOVER'
- # Controls various backend behavior
- # ALLOW_TO_FAILOVER or DISALLOW_TO_FAILOVER
-backend_hostname1 = 'server2'
-backend_port1 = 5432
-backend_weight1 = 1
-backend_data_directory1 = '/var/lib/pgsql/11/data'
-backend_flag1 = 'ALLOW_TO_FAILOVER'
-
-backend_hostname2 = 'server3'
-backend_port2 = 5432
-backend_weight2 = 1
-backend_data_directory2 = '/var/lib/pgsql/11/data'
-backend_flag2 = 'ALLOW_TO_FAILOVER'
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-failover">
- <title>フェイルオーバの設定</title>
- <para>
-<productname>PostgreSQL</productname>バックエンドノードがダウンした時に実行するスクリプトを<xref linkend="GUC-FAILOVER-COMMAND">に設定します。
-また、<productname>PostgreSQL</productname>サーバが3台の場合、プライマリノードのフェイルオーバ後に新しいプライマリからスレーブをリカバリするために<xref linkend="GUC-FOLLOW-MASTER-COMMAND">も設定する必要があります。<xref linkend="GUC-FOLLOW-MASTER-COMMAND">はプライマリノードのフェイルオーバ後に実行されます。<productname>PostgreSQL</productname>サーバが2台の場合、<xref linkend="GUC-FOLLOW-MASTER-COMMAND">の設定は不要です。
- </para>
- <para>
-それぞれの実行スクリプトの引数は、それぞれ実行時に<productname>Pgpool-II</productname>によってバックエンドの具体的な情報に置き換えられます。各引数の意味は<xref linkend="GUC-FAILOVER-COMMAND">をご参照ください。
- </para>
- <programlisting>
-failover_command = '/etc/pgpool-II/failover.sh %d %h %p %D %m %H %M %P %r %R'
-follow_master_command = '/etc/pgpool-II/follow_master.sh %d %h %p %D %m %M %H %P %r %R'
- </programlisting>
- <para>
-<filename>/etc/pgpool-II/failover.sh</filename>及び<filename>/etc/pgpool-II/follow_master.sh</filename>を作成し、実行権限を与えておきます。
- </para>
- <programlisting>
-# vi /etc/pgpool-II/failover.sh
-# vi /etc/pgpool-II/follow_master.sh
-# chmod +x /etc/pgpool-II/{failover.sh,follow_master.sh}
- </programlisting>
-
- <itemizedlist>
- <listitem>
- <para>
-/etc/pgpool-II/failover.sh
- </para>
- <programlisting>
-#!/bin/bash
-# This script is run by failover_command.
-
-set -o xtrace
-exec > >(logger -i -p local1.info) 2>&1
-
-# Special values:
-# %d = node id
-# %h = host name
-# %p = port number
-# %D = database cluster path
-# %m = new master node id
-# %H = hostname of the new master node
-# %M = old master node id
-# %P = old primary node id
-# %r = new master port number
-# %R = new master database cluster path
-# %% = '%' character
-
-FAILED_NODE_ID="$1"
-FAILED_NODE_HOST="$2"
-FAILED_NODE_PORT="$3"
-FAILED_NODE_PGDATA="$4"
-NEW_MASTER_NODE_ID="$5"
-NEW_MASTER_NODE_HOST="$6"
-OLD_MASTER_NODE_ID="$7"
-OLD_PRIMARY_NODE_ID="$8"
-NEW_MASTER_NODE_PORT="$9"
-NEW_MASTER_NODE_PGDATA="${10}"
-
-PGHOME=/usr/pgsql-11
-
-logger -i -p local1.info failover.sh: start: failed_node_id=$FAILED_NODE_ID old_primary_node_id=$OLD_PRIMARY_NODE_ID \
- failed_host=$FAILED_NODE_HOST new_master_host=$NEW_MASTER_NODE_HOST
-
-# If standby node is down, skip failover.
-if [ $FAILED_NODE_ID -ne $OLD_PRIMARY_NODE_ID ]; then
- logger -i -p local1.info failover.sh: Standby node is down. Skipping failover.
- exit 0
-fi
-
-# Promote standby node.
-logger -i -p local1.info failover.sh: ssh: postgres@$NEW_MASTER_NODE_HOST pg_ctl promote
-if [ $UID -eq 0 ]; then
- su postgres -c "ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
- postgres@$NEW_MASTER_NODE_HOST ${PGHOME}/bin/pg_ctl -D ${NEW_MASTER_NODE_PGDATA} -w promote"
-else
- ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
- postgres@$NEW_MASTER_NODE_HOST ${PGHOME}/bin/pg_ctl -D ${NEW_MASTER_NODE_PGDATA} -w promote
-fi
-
-if [[ $? -ne 0 ]]; then
- logger -i -p local1.error failover.sh: new_master_host=$NEW_MASTER_NODE_HOST promote failed
- exit 1
-fi
-
-logger -i -p local1.info failover.sh: end: new_master_node_id=$NEW_MASTER_NODE_ID started as the primary node
-exit 0
- </programlisting>
- </listitem>
- </itemizedlist>
-
- <itemizedlist>
- <listitem>
- <para>
-/etc/pgpool-II/follow_master.sh
- </para>
- <programlisting>
-#!/bin/bash
-# This script is run after failover_command to recover the slave from the new primary.
-
-set -o xtrace
-exec > >(logger -i -p local1.info) 2>&1
-
-# special values: %d = node id
-# %h = host name
-# %p = port number
-# %D = database cluster path
-# %m = new master node id
-# %M = old master node id
-# %H = new master node host name
-# %P = old primary node id
-# %R = new master database cluster path
-# %r = new master port number
-# %% = '%' character
-FAILED_NODE_ID="$1"
-FAILED_NODE_HOST="$2"
-FAILED_NODE_PORT="$3"
-FAILED_NODE_PGDATA="$4"
-NEW_MASTER_NODE_ID="$5"
-OLD_MASTER_NODE_ID="$6"
-NEW_MASTER_NODE_HOST="$7"
-OLD_PRIMARY_NODE_ID="$8"
-NEW_MASTER_NODE_PORT="$9"
-NEW_MASTER_NODE_PGDATA="${10}"
-
-PGHOME=/usr/pgsql-11
-ARCHIVEDIR=/var/lib/pgsql/archivedir
-REPL_USER=repl
-PCP_USER=pgpool
-PGPOOL_PATH=/usr/bin
-PCP_PORT=9898
-
-
-# Recovery the slave from the new primary
-logger -i -p local1.info follow_master.sh: start: pg_basebackup for $FAILED_NODE_ID
-
-# Check the status of standby
-ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
- postgres@${FAILED_NODE_HOST} ${PGHOME}/bin/pg_ctl -w -D ${FAILED_NODE_PGDATA} status >/dev/null 2>&1
-
-# If slave is running, recover the slave from the new primary.
-if [[ $? -eq 0 ]]; then
-
- # Execute pg_basebackup at slave
- ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${FAILED_NODE_HOST} "
- ${PGHOME}/bin/pg_ctl -w -m f -D ${FAILED_NODE_PGDATA} stop
-
- rm -rf ${FAILED_NODE_PGDATA}
- ${PGHOME}/bin/pg_basebackup -h ${NEW_MASTER_NODE_HOST} -U ${REPL_USER} -p ${NEW_MASTER_NODE_PORT} -D ${FAILED_NODE_PGDATA} -X stream -R
-
- if [[ $? -ne 0 ]]; then
- logger -i -p local1.error follow_master.sh: end: pg_basebackup failed
- exit 1
- fi
- rm -rf ${ARCHIVEDIR}/*
-cat >> ${FAILED_NODE_PGDATA}/recovery.conf << EOT
-restore_command = 'scp ${NEW_MASTER_NODE_HOST}:${ARCHIVEDIR}/%f %p'
-EOT
- $PGHOME/bin/pg_ctl -l /dev/null -w -D ${FAILED_NODE_PGDATA} start
- "
-
- if [[ $? -eq 0 ]]; then
-
- # Run pcp_attact_node to attach this slave to Pgpool-II.
- ${PGPOOL_PATH}/pcp_attach_node -w -h localhost -U ${PCP_USER} -p ${PCP_PORT} -n ${FAILED_NODE_ID}
-
- if [[ $? -ne 0 ]]; then
- logger -i -p local1.error follow_master.sh: end: pcp_attach_node failed
- exit 1
- fi
- else
- logger -i -p local1.error follow_master.sh: end: follow master failed
- exit 1
- fi
-
-else
- logger -i -p local1.info follow_master.sh: failed_nod_id=${FAILED_NODE_ID} is not running. skipping follow master command.
- exit 0
-fi
-
-logger -i -p local1.info follow_master.sh: end: follow master is finished
-exit 0
- </programlisting>
- </listitem>
- </itemizedlist>
-
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-online-recovery">
- <title>オンラインリカバリの設定</title>
- <para>
-続いて、オンラインリカバリを行うための<productname>PostgreSQL</productname>のユーザ名およびオンラインリカバリ時に呼び出されるコマンド<command>recovery_1st_stage</command>を設定します。
-オンラインリカバリで実行される<function>pgpool_recovery</function>関数は<productname>PostgreSQL</productname>のスーパーユーザ権限が必要なため、<varname>recovery_user</varname>にスーパーユーザを指定しなければなりません。ここでは、postrgesユーザを指定します。
-オンラインリカバリ用のスクリプト<filename>recovery_1st_stage</filename>、<filename>pgpool_remote_start</filename>をプライマリサーバ(server1)のデータベースクラスタ配下に配置し、実行権限を与えておきます。
- </para>
- <programlisting>
-recovery_user = 'postgres'
- # Online recovery user
-recovery_password = ''
- # Online recovery password
-
-recovery_1st_stage_command = 'recovery_1st_stage'
- </programlisting>
- <programlisting>
-[server1]# su - postgres
-[server1]$ vi /var/lib/pgsql/11/data/recovery_1st_stage
-[server1]$ vi /var/lib/pgsql/11/data/pgpool_remote_start
-[server1]$ chmod +x /var/lib/pgsql/11/data/{recovery_1st_stage,pgpool_remote_start}
- </programlisting>
-
- <itemizedlist>
- <listitem>
- <para>
-/var/lib/pgsql/11/data/recovery_1st_stage
- </para>
- <programlisting>
-#!/bin/bash
-# This script is run by recovery_1st_stage to recovery the slave from the primary.
-
-set -o xtrace
-exec > >(logger -i -p local1.info) 2>&1
-
-PRIMARY_NODE_PGDATA="$1"
-DEST_NODE_HOST="$2"
-DEST_NODE_PGDATA="$3"
-PRIMARY_NODE_PGPORT=$4
-
-PRIMARY_NODE_HOST=$(hostname -s)
-PGHOME=/usr/pgsql-11
-ARCHIVEDIR=/var/lib/pgsql/archivedir
-REPLUSER=repl
-
-
-logger -i -p local1.info online_recovery.sh: start: pg_basebackup for $DEST_NODE_HOST
-
-# Run pg_basebackup to recovery the slave from the primary
-ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$DEST_NODE_HOST "
-rm -rf $DEST_NODE_PGDATA
-${PGHOME}/bin/pg_basebackup -h $PRIMARY_NODE_HOST -U $REPLUSER -p $PRIMARY_NODE_PGPORT -D $DEST_NODE_PGDATA -X stream -R
-"
-if [[ $? -ne 0 ]]; then
- logger -i -p local1.error online_recovery.sh: end: pg_basebackup failed. online recovery failed.
- exit 1
-fi
-
-ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$DEST_NODE_HOST "
-rm -rf $ARCHIVEDIR/*
-cat >> $DEST_NODE_PGDATA/recovery.conf << EOT
-restore_command = 'scp $PRIMARY_NODE_HOST:$archivedir/%f %p'
-EOT
-"
-
-if [[ $? -ne 0 ]]; then
- logger -i -p local1.error online_recovery.sh: end: online recovery failed
- exit 1
-else
- logger -i -p local1.info online_recovery.sh: end: online recovery is finished
- exit 0
-fi
- </programlisting>
- </listitem>
- <listitem>
-
- <para>
-/var/lib/pgsql/11/data/pgpool_remote_start
- </para>
- <programlisting>
-#!/bin/bash
-# This script is run to start slave node after recovery.
-
-set -o xtrace
-exec > >(logger -i -p local1.info) 2>&1
-
-PGHOME=/usr/pgsql-11
-DEST_HOST="$1"
-DEST_HOST_PGDATA="$2"
-
-
-logger -i -p local1.info pgpool_remote_start: start: remote start PostgreSQL@$DEST_HOST
-
-# Start slave node
-ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$DEST_HOST $PGHOME/bin/pg_ctl -l /dev/null -w -D $DEST_HOST_PGDATA start
-
-if [[ $? -ne 0 ]]; then
- logger -i -p local1.info pgpool_remote_start: $DEST_HOST start failed.
- exit 1
-fi
-
-logger -i -p local1.info pgpool_remote_start: end: $DEST_HOST PostgreSQL started successfully.
- </programlisting>
- </listitem>
- </itemizedlist>
-
- <para>
-また、オンラインリカバリ機能を使用するには、<function>pgpool_recovery</function>、<function>pgpool_remote_start</function>、<function>pgpool_switch_xlog</function>という関数が必要になるので、<literal>server1</literal>のtemplate1に<function>pgpool_recovery</function>をインストールしておきます。
- </para>
- <programlisting>
-[server1]# su - postgres
-[server1]$ psql template1 -c "CREATE EXTENSION pgpool_recovery"
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-auth">
- <title>クライアント認証の設定</title>
- <para>
-<link linkend="EXAMPLE-CLUSTER-PRE-SETUP">事前設定</link>の章で、<productname>Pgpool-II</productname>と<productname>PostgreSQL</productname>の間に認証方式を<acronym>scram-sha-256</acronym>に設定しました。この設定例では、クライアントと<productname>Pgpool-II</productname>の間でも<acronym>scram-sha-256</acronym>認証方式を利用し接続するように設定します。
-<filename>pgpool.conf</filename>ファイル内の<xref linkend="guc-health-check-password">、<xref linkend="guc-sr-check-password">、<xref linkend="guc-wd-lifecheck-password">、<xref linkend="guc-recovery-password">にはAES256暗号化形式、平文形式しか指定できないので、ご注意ください。
-<productname>Pgpool-II</productname>のクライアント認証の設定ファイルは<filename>pool_hba.conf</filename>と呼ばれ、RPMパッケージからインストールする場合、デフォルトでは<filename>/etc/pgpool-II</filename>配下にインストールされます。
-デフォルトでは<filename>pool_hba.conf</filename>による認証は無効になっているので、<filename>pgpool.conf</filename>では以下の設定をonに変更します。
- </para>
- <programlisting>
-enable_pool_hba = on
- </programlisting>
- <para>
-<filename>pool_hba.conf</filename>のフォーマットは<productname>PostgreSQL</productname>の<filename>pg_hba.conf</filename>とほとんど同じです。<literal>pgpool</literal>と<literal>postgres</literal>ユーザを<acronym>scram-sha-256</acronym>認証に設定します。
- </para>
- <programlisting>
-host all pgpool 0.0.0.0/0 scram-sha-256
-host all postgres 0.0.0.0/0 scram-sha-256
- </programlisting>
- <para>
-<productname>Pgpool-II</productname>のクライアント認証で用いるデフォルトのパスワードファイル名はpool_passwdです。
-<literal>scram-sha-256</literal>認証を利用する場合、<productname>Pgpool-II</productname>はそれらのパスワードを復号化するために復号鍵が必要となります。全サーバで復号鍵ファイルをrootユーザのホームディレクトリ配下に作成します。
- </para>
- <programlisting>
-[全サーバ]# echo '任意の文字列' > ~/.pgpoolkey
-[全サーバ]# chmod 600 ~/.pgpoolkey
- </programlisting>
- <para>
-「pg_enc -m -k /path/to/.pgpoolkey -u ユーザ名 -p」 コマンドを実行すると、ユーザ名と<literal>AES256</literal>で暗号化したパスワードのエントリが<xref linkend="GUC-POOL-PASSWD">に登録されます。
-<xref linkend="GUC-POOL-PASSWD"> がまだ存在しなければ、<filename>pgpool.conf</filename>と同じディレクトリ内に作成されます。
- </para>
- <programlisting>
-[全サーバ]# pg_enc -m -k /root/.pgpoolkey -u pgpool -p
-db password: [pgpoolユーザのパスワード]
-[全サーバ]# pg_enc -m -k /root/.pgpoolkey -u postgres -p
-db password: [postgresユーザのパスワード]
-
-# cat /etc/pgpool-II/pool_passwd
-pgpool:AESheq2ZMZjynddMWk5sKP/Rw==
-postgres:AESHs/pWL5rtXy2IwuzroHfqg==
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-watchdog">
- <title>Watchdogの設定</title>
- <para>
-デフォルトでは<literal>watchdog</literal>機能が無効のため、<literal>server1</literal>、<literal>server2</literal>及び<literal>server3</literal>で<literal>watchdog</literal>を有効にします。
- </para>
- <programlisting>
-use_watchdog = on
- </programlisting>
- <para>
-アクティブ機が立ち上げる仮想IPをdelegate_IPに指定します。仮想 IP はまだ使われていないIPアドレスを指定してください。<literal>server1</literal>、<literal>server2</literal>及び<literal>server3</literal>の共通の設定です。
- </para>
- <programlisting>
-delegate_IP = '192.168.137.150'
- </programlisting>
-
- <para>
-仮想IPの起動/停止、ARPリクエストの送信を行う設定パラメータ<xref linkend="GUC-IF-UP-CMD">、<xref linkend="GUC-IF-DOWN-CMD">、<xref linkend="GUC-ARPING-CMD">に、ネットワーク環境に合わせてネットワークインターフェース名を設定します。
-今回の例で使ったネットワークインターフェースは「enp0s8」となっています。
- </para>
- <programlisting>
-if_up_cmd = 'ip addr add $_IP_$/24 dev enp0s8 label enp0s8:0'
- # startup delegate IP command
-if_down_cmd = 'ip addr del $_IP_$/24 dev enp0s8'
- # shutdown delegate IP command
-arping_cmd = 'arping -U $_IP_$ -w 1 -I enp0s8'
- # arping command
- </programlisting>
-
- <para>
-ipコマンドやarpingコマンドのパスがデフォルトのパスと異なる場合、環境に合わせて<xref linkend="GUC-IF-CMD-PATH">や<xref linkend="GUC-ARPING-PATH">を設定しておいてください。
- </para>
- <programlisting>
-if_cmd_path = '/sbin'
- # path to the directory where if_up/down_cmd exists
-arping_path = '/usr/sbin'
- # arping command path
- </programlisting>
- <para>
-各watchdog が稼働するサーバ情報を設定しておきます。
- </para>
- <itemizedlist>
- <listitem>
- <para>
-<literal>server1</literal>の場合
- </para>
- <programlisting>
-wd_hostname = 'server1'
-wd_port = 9000
- </programlisting>
- </listitem>
- <listitem>
- <para>
-<literal>server2</literal>の場合
- </para>
- <programlisting>
-wd_hostname = 'server2'
-wd_port = 9000
- </programlisting>
- </listitem>
- <listitem>
- <para>
-<literal>server3</literal>の場合
- </para>
- <programlisting>
-wd_hostname = 'server3'
-wd_port = 9000
- </programlisting>
- </listitem>
- </itemizedlist>
-
- <para>
-各監視対象の<productname>Pgpool-II</productname>サーバ情報を設定しておきます。
- </para>
- <itemizedlist>
- <listitem>
- <para>
-<literal>server1</literal>の場合
- </para>
- <programlisting>
-# - Other pgpool Connection Settings -
-
-other_pgpool_hostname0 = 'server2'
- # Host name or IP address to connect to for other pgpool 0
- # (change requires restart)
-other_pgpool_port0 = 9999
- # Port number for other pgpool 0
- # (change requires restart)
-other_wd_port0 = 9000
- # Port number for other watchdog 0
- # (change requires restart)
-other_pgpool_hostname1 = 'server3'
-other_pgpool_port1 = 9999
-other_wd_port1 = 9000
- </programlisting>
- </listitem>
- <listitem>
- <para>
-<literal>server2</literal>の場合
- </para>
- <programlisting>
-# - Other pgpool Connection Settings -
-
-other_pgpool_hostname0 = 'server1'
- # Host name or IP address to connect to for other pgpool 0
- # (change requires restart)
-other_pgpool_port0 = 9999
- # Port number for other pgpool 0
- # (change requires restart)
-other_wd_port0 = 9000
- # Port number for other watchdog 0
- # (change requires restart)
-other_pgpool_hostname1 = 'server3'
-other_pgpool_port1 = 9999
-other_wd_port1 = 9000
- </programlisting>
- </listitem>
- <listitem>
- <para>
-<literal>server3</literal>の場合
- </para>
- <programlisting>
-# - Other pgpool Connection Settings -
-
-other_pgpool_hostname0 = 'server1'
- # Host name or IP address to connect to for other pgpool 0
- # (change requires restart)
-other_pgpool_port0 = 9999
- # Port number for other pgpool 0
- # (change requires restart)
-other_wd_port0 = 9000
- # Port number for other watchdog 0
- # (change requires restart)
-other_pgpool_hostname1 = 'server2'
-other_pgpool_port1 = 9999
-other_wd_port1 = 9000
- </programlisting>
- </listitem>
- </itemizedlist>
-
- <para>
-ハートビート信号の送信先のホスト名とポート番号を指定します。
- </para>
- <itemizedlist>
- <listitem>
- <para>
-<literal>server1</literal>の場合
- </para>
- <programlisting>
-heartbeat_destination0 = 'server2'
- # Host name or IP address of destination 0
- # for sending heartbeat signal.
- # (change requires restart)
-heartbeat_destination_port0 = 9694
- # Port number of destination 0 for sending
- # heartbeat signal. Usually this is the
- # same as wd_heartbeat_port.
- # (change requires restart)
-heartbeat_device0 = ''
- # Name of NIC device (such like 'eth0')
- # used for sending/receiving heartbeat
- # signal to/from destination 0.
- # This works only when this is not empty
- # and pgpool has root privilege.
- # (change requires restart)
-
-heartbeat_destination1 = 'server3'
-heartbeat_destination_port1 = 9694
-heartbeat_device1 = ''
-
- </programlisting>
- </listitem>
- <listitem>
- <para>
-<literal>server2</literal>の場合
- </para>
- <programlisting>
-heartbeat_destination0 = 'server1'
- # Host name or IP address of destination 0
- # for sending heartbeat signal.
- # (change requires restart)
-heartbeat_destination_port0 = 9694
- # Port number of destination 0 for sending
- # heartbeat signal. Usually this is the
- # same as wd_heartbeat_port.
- # (change requires restart)
-heartbeat_device0 = ''
- # Name of NIC device (such like 'eth0')
- # used for sending/receiving heartbeat
- # signal to/from destination 0.
- # This works only when this is not empty
- # and pgpool has root privilege.
- # (change requires restart)
-
-heartbeat_destination1 = 'server3'
-heartbeat_destination_port1 = 9694
-heartbeat_device1 = ''
-
- </programlisting>
- </listitem>
- <listitem>
- <para>
-<literal>server3</literal>の場合
- </para>
- <programlisting>
-heartbeat_destination0 = 'server1'
- # Host name or IP address of destination 0
- # for sending heartbeat signal.
- # (change requires restart)
-heartbeat_destination_port0 = 9694
- # Port number of destination 0 for sending
- # heartbeat signal. Usually this is the
- # same as wd_heartbeat_port.
- # (change requires restart)
-heartbeat_device0 = ''
- # Name of NIC device (such like 'eth0')
- # used for sending/receiving heartbeat
- # signal to/from destination 0.
- # This works only when this is not empty
- # and pgpool has root privilege.
- # (change requires restart)
-
-heartbeat_destination1 = 'server2'
-heartbeat_destination_port1 = 9694
-heartbeat_device1 = ''
- </programlisting>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-sysconfig">
- <title>/etc/sysconfig/pgpoolの設定</title>
- <para>
-<productname>Pgpool-II</productname>を起動時に<filename>pgpool_status</filename>ファイルを無視させたい場合、<filename>/etc/sysconfig/pgpool</filename>の起動オプションOPTSに「-D」を追加します。
- </para>
- <programlisting>
-[全サーバ]# vi /etc/sysconfig/pgpool
-(...省略...)
-OPTS=" -D -n"
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-log">
- <title>ログの設定</title>
- <para>
-この例では、<productname>Pgpool-II</productname>のログ出力は<literal>syslog</literal>を利用するように設定します。
- </para>
- <programlisting>
-log_destination = 'syslog'
- # Where to log
- # Valid values are combinations of stderr,
- # and syslog. Default to stderr.
-
-syslog_facility = 'LOCAL1'
- # Syslog local facility. Default to LOCAL0
- </programlisting>
- <para>
-全サーバではログファイルを作成します。
- </para>
- <programlisting>
-[全サーバ]# mkdir /var/log/pgpool-II
-[全サーバ]# touch /var/log/pgpool-II/pgpool.log
- </programlisting>
- <para>
-次に<literal>syslog</literal>の設定ファイルを以下のように編集します。
- </para>
- <programlisting>
-[全サーバ]# vi /etc/rsyslog.conf
-...(省略)...
-*.info;mail.none;authpriv.none;cron.none;LOCAL1.none /var/log/messages
-LOCAL1.* /var/log/pgpool-II/pgpool.log
- </programlisting>
- <para>
-また、<productname>Pgpool-II</productname>に関して<filename>/var/log/messages</filename>と同様のログローテーションを行うように、logrotateの設定を以下のように行います。
- </para>
- <programlisting>
-[全サーバ]# vi /etc/logrotate.d/syslog
-...(省略)...
-/var/log/messages
-/var/log/pgpool-II/pgpool.log
-/var/log/secure
- </programlisting>
-
- <para>
-設定が終わったら、rsyslogサービスを再起動します。
- </para>
- <programlisting>
-[全サーバ]# systemctl restart rsyslog
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-pcp">
- <title>PCPコマンドの設定</title>
- <para>
-<literal>PCP</literal>コマンドを使用するにはユーザ認証が必要になるので、ユーザ名と<literal>md5</literal>ハッシュに変換されたパスワードを<filename>pcp.conf</filename>ファイルに設定します。
-ここではユーザ名に<literal>pgpool</literal>を使用し、以下のコマンドを実行することで、<ユーザ名:ハッシュ化されたパスワード>が<filename>/etc/pgpool-II/pcp.conf</filename>に追加されます。
- </para>
- <programlisting>
-[全サーバ]# echo 'pgpool:'`pg_md5 PCPコマンドパスワード` >> /etc/pgpool-II/pcp.conf
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-pcppass">
- <title>.pcppassの設定</title>
- <para>
-前述の<literal>follow_master_command</literal>のスクリプトでパスワード入力なしで<literal>PCP</literal>コマンドを実行できるように、すべてのサーバで<productname>Pgpool-II</productname>の起動ユーザのホームディレクトリに<filename>.pcppass</filename>を作成します。
- </para>
- <programlisting>
-[全サーバ]# echo 'localhost:9898:pgpool:pgpool' > ~/.pcppass
-[全サーバ]# chmod 600 ~/.pcppass
- </programlisting>
- <para>
-ここで、<productname>Pgpool-II</productname>の設定は完了です。
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="example-cluster-start-stop">
- <title>システムの起動と停止</title>
- <para>
-<productname>Pgpool-II</productname>の設定が完了したら、次に<productname>Pgpool-II</productname>を起動します。<productname>Pgpool-II</productname>を起動する前に、バックエンドの<productname>PostgreSQL</productname>をあらかじめ起動する必要があります。また、<productname>PostgreSQL</productname>を停止する場合、<productname>Pgpool-II</productname>を先に停止する必要があります。
- </para>
- <itemizedlist>
- <listitem>
- <para>
-<productname>Pgpool-II</productname>の起動
- </para>
- <para>
-前述の<link linkend="EXAMPLE-CLUSTER-PRE-SETUP">事前設定</link>の章で<productname>Pgpool-II</productname>の自動起動が設定済なので、ここでシステム全体を再起動するか、以下のコマンドを実行してください。
- </para>
- <programlisting>
-# systemctl start pgpool.service
- </programlisting>
- </listitem>
- <listitem>
- <para>
-<productname>Pgpool-II</productname>の停止
- </para>
- <programlisting>
-# systemctl stop pgpool.service
- </programlisting>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2 id="example-cluster-try">
- <title>動作確認</title>
- <para>
-これから、動作確認を行います。まず、<literal>server1</literal>、<literal>server2</literal>、<literal>server3</literal>で以下のコマンドで<productname>Pgpool-II</productname>を起動します。
- </para>
- <programlisting>
-# systemctl start pgpool.service
- </programlisting>
-
- <sect3 id="example-cluster-try-standby">
- <title>PostgreSQL スタンバイサーバを構築</title>
- <para>
-まず、<productname>Pgpool-II</productname>のオンラインリカバリ機能を利用し、スタンバイサーバを構築します。<command>pcp_recovery_node</command>コマンドで実行される<varname>recovery_1st_stage_command</varname>パラメータに指定した<filename>recovery_1st_stage</filename>と<filename>pgpool_remote_start</filename>スプリクトが実行されるので、この 2つのスクリプトが現在稼働中のプライマリサーバ<literal>server1</literal>のデータベースクラスタの下に存在することを確認します。
- </para>
- <programlisting>
-# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 1
-Password:
-pcp_recovery_node -- Command Successful
-
-# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 2
-Password:
-pcp_recovery_node -- Command Successful
- </programlisting>
- <para>
-<literal>server2</literal>と<literal>server3</literal>の<productname>PostgreSQL</productname>がスタンバイとして起動されていることを確認します。
- </para>
- <programlisting>
-# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
-ユーザ pgpool のパスワード:
- node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | last_status_change
----------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+---------------------
- 0 | server1 | 5432 | up | 0.333333 | primary | 0 | false | 0 | 2019-02-18 11:26:31
- 1 | server2 | 5432 | up | 0.333333 | standby | 0 | true | 0 | 2019-02-18 11:27:49
- 2 | server3 | 5432 | up | 0.333333 | standby | 0 | false | 0 | 2019-02-18 11:27:49
-(3 行)
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-try-watchdog">
- <title>watchdogアクティブ/スタンバイの切り替え</title>
- <para>
-<command>pcp_watchdog_info</command>で<productname>Pgpool-II</productname>の<application>watchdog</application>の情報を確認します。最初に起動した<productname>Pgpool-II</productname>が「MASTER」になります。
- </para>
- <programlisting>
-# pcp_watchdog_info -h 192.168.137.150 -p 9898 -U pgpool
-Password:
-3 YES server1:9999 Linux server1 server1
-
-server1:9999 Linux server1 server1 9999 9000 4 MASTER #最初に起動されたサーバがMASTERになる
-server2:9999 Linux server2 server2 9999 9000 7 STANDBY #スタンバイとして稼働
-server3:9999 Linux server3 server3 9999 9000 7 STANDBY #スタンバイとして稼働
- </programlisting>
- <para>
-アクティブである<literal>server1</literal>の<productname>Pgpool-II</productname>を停止し、<literal>server2</literal>または<literal>server3</literal>がスタンバイからアクティブに昇格することを確認します。<literal>server1</literal>を停止する方法は<productname>Pgpool-II</productname>を停止する、またはマシンをシャットダウンします。ここでは、<productname>Pgpool-II</productname>を停止します。
- </para>
- <programlisting>
-[server1]# systemctl stop pgpool.service
-
-# pcp_watchdog_info -p 9898 -h 192.168.137.150 -U pgpool
-Password:
-3 YES server2:9999 Linux server2 server2
-
-server2:9999 Linux server2 server2 9999 9000 4 MASTER #server2がアクティブに昇格
-server1:9999 Linux server1 server1 9999 9000 10 SHUTDOWN #server1が停止された
-server3:9999 Linux server3 server3 9999 9000 7 STANDBY #スタンバイとして稼働
- </programlisting>
- <para>
-先ほど停止した<productname>Pgpool-II</productname>を再起動し、スタンバイとして起動したことを確認します。
- </para>
- <programlisting>
-[server1]# systemctl start pgpool.service
-
-[server1]# pcp_watchdog_info -p 9898 -h 192.168.137.150 -U pgpool
-Password:
-3 YES server2:9999 Linux server2 server2
-
-server2:9999 Linux server2 server2 9999 9000 4 MASTER
-server1:9999 Linux server1 server1 9999 9000 7 STANDBY
-server3:9999 Linux server3 server3 9999 9000 7 STANDBY
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-try-failover">
- <title>自動フェイルオーバ</title>
- <para>
-<command>psql</command>で仮想IPに接続し、バックエンドの情報を確認します。
- </para>
- <programlisting>
-# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
-ユーザ pgpool のパスワード:
- node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | last_status_change
----------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+---------------------
- 0 | server1 | 5432 | up | 0.333333 | primary | 0 | false | 0 | 2019-02-18 13:08:02
- 1 | server2 | 5432 | up | 0.333333 | standby | 0 | false | 0 | 2019-02-18 13:21:56
- 2 | server3 | 5432 | up | 0.333333 | standby | 0 | true | 0 | 2019-02-18 13:21:56
-(3 行)
- </programlisting>
- <para>
-次にプライマリである<literal>server1</literal>の<productname>PostgreSQL</productname>を停止し、フェイルオーバするかどうか確認してみます。
- </para>
- <programlisting>
-[server1]$ pg_ctl -D /var/lib/pgsql/11/data -m immediate stop
- </programlisting>
- <para>
-<literal>ノード1</literal>を停止後、フェイルオーバが発生し、<literal>server2</literal>がプライマリに昇格したことを確認します。
- </para>
- <programlisting>
-# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
-ユーザ pgpool のパスワード:
- node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | last_status_change
----------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+---------------------
- 0 | server1 | 5432 | down | 0.333333 | standby | 0 | false | 0 | 2019-02-18 13:22:25
- 1 | server2 | 5432 | up | 0.333333 | primary | 0 | true | 0 | 2019-02-18 13:22:25
- 2 | server3 | 5432 | up | 0.333333 | standby | 0 | false | 0 | 2019-02-18 13:22:28
-(3 行)
- </programlisting>
-
- <para>
-<literal>server3</literal>が新しいプライマリ<literal>server2</literal>のスタンバイとして起動されています。
- </para>
-
- <programlisting>
-[server3]# psql -h server3 -p 5432 -U pgpool postgres -c "select pg_is_in_recovery()"
-ユーザ pgpool のパスワード:
- pg_is_in_recovery
--------------------
- t
-(1 行)
-
-[server2]# su - postgres
-$ psql
-postgres=# select pg_is_in_recovery();
- pg_is_in_recovery
--------------------
- f
-(1 行)
-
-postgres=# select * from pg_stat_replication;
--[ RECORD 1 ]----+------------------------------
-pid | 11915
-usesysid | 16385
-usename | repl
-application_name | walreceiver
-client_addr | 192.168.137.103
-client_hostname |
-client_port | 37834
-backend_start | 2019-02-18 13:22:27.472038+09
-backend_xmin |
-state | streaming
-sent_lsn | 0/8E000060
-write_lsn | 0/8E000060
-flush_lsn | 0/8E000060
-replay_lsn | 0/8E000060
-write_lag |
-flush_lag |
-replay_lag |
-sync_priority | 0
-sync_state | async
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-try-online-recovery">
- <title>オンラインリカバリ</title>
- <para>
-次に、<productname>Pgpool-II</productname>のオンラインリカバリ機能を利用し、先ほど停止した旧プライマリサーバをスタンバイとして復旧させます。<command>pcp_recovery_node</command>コマンドで実行される<varname>recovery_1st_stage_command</varname>パラメータに指定した<filename>recovery_1st_stage</filename>と<filename>pgpool_remote_start</filename>スプリクトが現在稼働中のプライマリサーバ<literal>server2</literal>のデータベースクラスタの下に存在することを確認します。
- </para>
- <programlisting>
-# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 0
-Password:
-pcp_recovery_node -- Command Successful
- </programlisting>
- <para>
-<literal>ノード1</literal>がスタンバイとして起動されたことを確認します。
- </para>
- <programlisting>
-# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
-ユーザ pgpool のパスワード:
- node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | last_status_change
----------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+---------------------
- 0 | server1 | 5432 | up | 0.333333 | standby | 0 | false | 0 | 2019-02-18 13:27:44
- 1 | server2 | 5432 | up | 0.333333 | primary | 0 | false | 0 | 2019-02-18 13:22:25
- 2 | server3 | 5432 | up | 0.333333 | standby | 0 | true | 0 | 2019-02-18 13:22:28
-(3 行)
- </programlisting>
- <para>
-以上で、動作確認が完了です。
- </para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="example-AWS">
-<!--
- <title>AWS Configuration Example</title>
--->
- <title>AWS設定の例</title>
-
- <para>
-<!--
- This tutorial explains the simple way to try "Watchdog"
- on <ulink url="https://aws.amazon.com/">AWS</ulink> and using
- the <ulink url="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html">
- Elastic IP Address</ulink> as the Virtual IP for the high availability solution.
- <note>
- <para>
- You can use watchdog with <productname>
- Pgpool-II</productname> in any mode: replication mode,
- master/slave mode and raw mode.
- </para>
- </note>
--->
-このチュートリアルでは、<ulink url="https://aws.amazon.com/">AWS</ulink>上で"Watchdog"を使う簡単な例を示します。
-この例では、高可用性のために<ulink url="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html">Elastic IP Address</ulink>を仮想IPとして使います。
- <note>
- <para>
- watchdogは、<productname>Pgpool-II</productname>のすべてのモード、すなわちレプリケーションモード、マスタ／スレーブモード、ローモードのいずれでも使えます。
- </para>
- </note>
- </para>
-
- <sect2 id="example-AWS-setup">
-<!--
- <title>AWS Setup</title>
--->
- <title>AWSのセットアップ</title>
- <para>
-<!--
- For this example, we will use two node <productname>
- Pgpool-II</productname> watchdog cluster. So we will set up two
- Linux Amazon EC2 instances and one Elastic IP address.
- So for this example, do the following steps:
--->
-この例では、2ノードの<productname>Pgpool-II</productname> watchdogクラスタを使います。
-そこで、2つのAmazon Linux EC2インスタンスを設定し、ひとつのElastic IPアドレスを使用します。
-以下のステップを実施してください。
- </para>
- <itemizedlist>
-
- <listitem>
- <para>
-<!--
- Launch two Linux Amazon EC2 instances. For this example, we name these
- instances as "instance-1" and "instance-2"
--->
-Amazon Linux EC2インスタンスを2つ起動します。
-この例では、それぞれ"instance-1"と"instance-2"という名前を付けます。
- </para>
- </listitem>
-
- <listitem>
- <para>
-<!--
- Configure the security group for the instances and allow inbound traffic
- on ports used by pgpool-II and watchdog.
--->
-これらのインスタンスのセキュリティグループを設定し、Pgpool-IIとwatchdogが使用するポートへのインバウンドトラフィックを許可します。
- </para>
- </listitem>
-
- <listitem>
- <para>
-<!--
- Install the <productname>Pgpool-II</productname> on both instances.
--->
-<productname>Pgpool-II</productname>を両方のインスタンスにインストールします。
- </para>
- </listitem>
-
- <listitem>
- <para>
-<!--
- Allocate an Elastic IP address.
- For this example, we will use "35.163.178.3" as an Elastic IP address"
--->
-Elastic IPアドレスを確保します。
-この例では、Elastic IPアドレスに"35.163.178.3"を設定します。
- </para>
- </listitem>
-
- </itemizedlist>
-
- </sect2>
-
- <sect2 id="example-AWS-pgpool-config">
-<!--
- <title><productname>Pgpool-II</productname> configurations</title>
--->
- <title><productname>Pgpool-II</productname>の設定</title>
- <para>
-<!--
- Mostly the <productname>Pgpool-II</productname> configurations for this
- example will be same as in the <xref linkend="example-watchdog">, except the
- <xref linkend="guc-delegate-ip"> which we will not set in this example instead
- we will use <xref linkend="guc-wd-escalation-command"> and
- <xref linkend="guc-wd-de-escalation-command"> to switch the
- Elastic IP address to the master/Active <productname>Pgpool-II</productname> node.
--->
-この例の設定は<xref linkend="example-watchdog">とほとんど同じになりますが、<xref linkend="guc-delegate-ip">を設定せず、代わりに<xref linkend="guc-wd-escalation-command">と<xref linkend="guc-wd-de-escalation-command">を使ってmaster/Active <productname>Pgpool-II</productname>ノードのElastic IPアドレスを切り替えるのが異なります。
- </para>
-
- <sect3 id="example-AWS-pgpool-config-instance-1">
-<!--
- <title><productname>Pgpool-II</productname> configurations on Instance-1</title>
--->
- <title>Instance-1における<productname>Pgpool-II</productname>の設定</title>
- <para>
-
- <programlisting>
-use_watchdog = on
-delegate_IP = ''
-wd_hostname = 'instance-1-private-ip'
-other_pgpool_hostname0 = 'instance-2-private-ip'
-other_pgpool_port0 = 9999
-other_wd_port0 = 9000
-wd_escalation_command = '$path_to_script/aws-escalation.sh'
-wd_de_escalation_command = '$path_to_script/aws-de-escalation.sh'
- </programlisting>
-
- </para>
- </sect3>
-
- <sect3 id="example-AWS-pgpool-config-instance-2">
-<!--
- <title><productname>Pgpool-II</productname> configurations on Instance-2</title>
--->
- <title>Instance-2における<productname>Pgpool-II</productname>の設定</title>
- <para>
-
- <programlisting>
-use_watchdog = on
-delegate_IP = ''
-wd_hostname = 'instance-2-private-ip'
-other_pgpool_hostname0 = 'instance-1-private-ip'
-other_pgpool_port0 = 9999
-other_wd_port0 = 9000
-wd_escalation_command = '$path_to_script/aws-escalation.sh'
-wd_de_escalation_command = '$path_to_script/aws-de-escalation.sh'
- </programlisting>
-
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="example-AWS-pgpool-aws-escalation-instance">
-<!--
- <title>escalation and de-escalation Scripts</title>
--->
- <title>エスカレーションおよびディエスカレーション用のスクリプト</title>
- <para>
-<!--
- Create the aws-escalation.sh and aws-de-escalation.sh scripts on both
- instances and point the <xref linkend="guc-wd-escalation-command"> and
- <xref linkend="guc-wd-de-escalation-command"> to the respective scripts.
--->
-aws-escalation.shとaws-de-escalation.shスクリプトを2つのインスタンス上に作成し、<xref linkend="guc-wd-escalation-command">と<xref linkend="guc-wd-de-escalation-command">がそれぞれそれらを指すようにしてください。
- </para>
-
- <note>
- <para>
-<!--
- You may need to configure the AWS CLI first on all AWS instances
- to enable the execution of commands used by wd-escalation.sh and wd-de-escalation.sh.
- See <ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">configure AWS CLI</ulink>
--->
-AWSインスタンス上でwd-escalation.shとwd-de-escalation.shで使用するコマンドが実行できるようにするために、AWS CLIの設定が必要になるかもしれません。
-<ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">configure AWS CLI</ulink>を参照してください。
- </para>
- </note>
-
- <sect3 id="example-AWS-pgpool-aws-escalation-script">
-<!--
- <title>escalation script</title>
--->
- <title>エスカレーションスクリプト</title>
-
- <para>
-<!--
- This script will be executed by the watchdog
- to assign the Elastic IP on the instance when the watchdog becomes the active/master node.
- Change the INSTANCE_ID and ELASTIC_IP values as per your AWS setup values.
--->
-このスクリプトは、watchdogがactive/masterノードになったときに、Elastic IPをアサインするためにwatchdogが実行します。
- </para>
- <para>
- <emphasis>aws-escalation.sh:</emphasis>
- <programlisting>
-#! /bin/sh
-
-ELASTIC_IP=35.163.178.3
- # replace it with the Elastic IP address you
- # allocated from the aws console
-INSTANCE_ID=i-0a9b64e449b17ed4b
- # replace it with the instance id of the Instance
- # this script is installed on
-
-echo "Assigning Elastic IP $ELASTIC_IP to the instance $INSTANCE_ID"
-# bring up the Elastic IP
-aws ec2 associate-address --instance-id $INSTANCE_ID --public-ip $ELASTIC_IP
-
-exit 0
- </programlisting>
-
- </para>
-
- </sect3>
- <sect3 id="example-AWS-pgpool-aws-de-escalation-script">
-<!--
- <title>de-escalation script</title>
--->
- <title>ディエスカレーションスクリプト</title>
- <para>
-<!--
- This script will be executed by watchdog
- to remove the Elastic IP from the instance when the watchdog resign from the active/master node.
--->
-このスクリプトは、watchdogがactive/masterノードを退任するときに、Elastic IPのアサインを解除するためにwatchdogが実行します。
- </para>
- <para>
- <emphasis>aws-de-escalation.sh:</emphasis>
- <programlisting>
-#! /bin/sh
-
-ELASTIC_IP=35.163.178.3
- # replace it with the Elastic IP address you
- # allocated from the aws console
-
-echo "disassociating the Elastic IP $ELASTIC_IP from the instance"
-# bring down the Elastic IP
-aws ec2 disassociate-address --public-ip $ELASTIC_IP
-exit 0
- </programlisting>
- </para>
- </sect3>
-
- <bibliography>
-<!--
- <title>AWS Command References</title>
--->
- <title>AWSコマンドリファレンス</title>
-
- <biblioentry>
- <biblioset relation="article">
- <title><ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">Configure AWS CLI</ulink></title>
- </biblioset>
- <biblioset relation="book">
- <title>AWS Documentation: Configuring the AWS Command Line Interface</title>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset relation="article">
- <title><ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/associate-address.html">associate-address</ulink></title>
- </biblioset>
- <biblioset relation="book">
- <title>AWS Documentation: associate-address reference</title>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset relation="article">
- <title><ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/disassociate-address.html">disassociate-address</ulink></title>
- </biblioset>
- <biblioset relation="book">
- <title>AWS Documentation: disassociate-address reference</title>
- </biblioset>
- </biblioentry>
-
- </bibliography>
- </sect2>
-
- <sect2 id="example-AWS-try">
-<!--
- <title>Try it out</title>
--->
- <title>実行してみる</title>
- <para>
-<!--
- Start <productname>Pgpool-II</productname> on each server with "-n" switch
- and redirect log messages to the pgpool.log file.
- The log message of master/active <productname>Pgpool-II</productname> node
- will show the message of Elastic IP assignment.
--->
-それぞれのサーバ上で<productname>Pgpool-II</productname>を"-n"スイッチ付きで起動し、pgpool.logにログメッセージをリダイレクトします。
-master/active <productname>Pgpool-II</productname>ノードは、Elastic IPのアサインメッセージを表示します。
- <programlisting>
-LOG: I am the cluster leader node. Starting escalation process
-LOG: escalation process started with PID:23543
-LOG: watchdog: escalation started
-<emphasis>
-Assigning Elastic IP 35.163.178.3 to the instance i-0a9b64e449b17ed4b
-{
- "AssociationId": "eipassoc-39853c42"
-}
-</emphasis>
-LOG: watchdog escalation successful
-LOG: watchdog escalation process with pid: 23543 exit with SUCCESS.
- </programlisting>
- </para>
-
- <para>
-<!--
- Confirm to ping to the Elastic IP address.
--->
-Elastic IPアドレスにpingが通ることを確かめます。
- <programlisting>
-[user@someserver]$ ping 35.163.178.3
-PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
-64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
-64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
-64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
- </programlisting>
- </para>
-
- <para>
-<!--
- Try to connect <productname>PostgreSQL</> by "psql -h ELASTIC_IP -p port".
--->
-"psql -h ELASTIC_IP -p port"で<productname>PostgreSQL</>に接続してみます。
- <programlisting>
-[user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
- </programlisting>
- </para>
- </sect2>
-
- <sect2 id="example-AWS-vip-switch">
-<!--
- <title>Switching Elastic IP</title>
--->
- <title>Elastic IPの切換</title>
- <para>
-<!--
- To confirm if the Standby server acquires the Elastic IP when the
- Active server becomes unavailable, Stop the <productname>Pgpool-II</productname>
- on the Active server. Then, the Standby server should start using the Elastic IP address,
- And the <productname>Pgpool-II</productname> log will show the below messages.
--->
-アクティブなサーバが使用できなくなった時にスタンバイサーバがElastic IPを獲得できることを確認するために、アクティブサーバ上の<productname>Pgpool-II</productname>を停止します。
-すると、スタンバイサーバはElastic IPアドレスを使い始めるはずです。
-<productname>Pgpool-II</productname>のログには以下のようなメッセージが表示されます。
- <programlisting>
-<emphasis>
-LOG: remote node "172.31.2.94:9999 [Linux ip-172-31-2-94]" is shutting down
-LOG: watchdog cluster has lost the coordinator node
-</emphasis>
-LOG: watchdog node state changed from [STANDBY] to [JOINING]
-LOG: watchdog node state changed from [JOINING] to [INITIALIZING]
-LOG: I am the only alive node in the watchdog cluster
-HINT: skipping stand for coordinator state
-LOG: watchdog node state changed from [INITIALIZING] to [MASTER]
-LOG: I am announcing my self as master/coordinator watchdog node
-LOG: I am the cluster leader node
-DETAIL: our declare coordinator message is accepted by all nodes
-LOG: I am the cluster leader node. Starting escalation process
-LOG: escalation process started with PID:23543
-LOG: watchdog: escalation started
-<emphasis>
-Assigning Elastic IP 35.163.178.3 to the instance i-0dd3e60734a6ebe14
-{
- "AssociationId": "eipassoc-39853c42"
-}
-</emphasis>
-LOG: watchdog escalation successful
-LOG: watchdog escalation process with pid: 61581 exit with SUCCESS.
- </programlisting>
-<!--
- Confirm to ping to the Elastic IP address again.
--->
-Elastic IPアドレスにpingが通ることを再度確かめます。
- <programlisting>
-[user@someserver]$ ping 35.163.178.3
-PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
-64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
-64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
-64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
- </programlisting>
- </para>
- <para>
-<!--
- Try to connect <productname>PostgreSQL</> by "psql -h ELASTIC_IP -p port".
--->
-"psql -h ELASTIC_IP -p port"で<productname>PostgreSQL</>に接続してみます。
- <programlisting>
-[user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
- </programlisting>
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="example-Aurora">
- <!--
- <title>Aurora Configuration Example</title>
- -->
- <title>Auroraの設定例</title>
-
- <para>
-<!--
- <productname>Amazon Aurora for PostgreSQL
- Compatibility</productname> (Aurora) is a managed service for
- <productname>PostgreSQL</productname>. From user's point of
- view, <productname>Aurora</productname> can be regarded as a
- streaming replication cluster with some exceptions. First,
- fail over and online recovery are managed
- by <productname>Aurora</productname>. So you don't need to
- set <xref linkend="guc-failover-command">, <xref linkend="guc-follow-master-command">,
- and recovery related parameters. In this section we explain
- how to set up <productname>Pgpool-II</productname> for Aurora.
--->
- <productname>Amazon Aurora for PostgreSQL
- Compatibility</productname> (Aurora) は、<productname>PostgreSQL</productname>用のマネージドサービスです。
- ユーザから見ると、<productname>Aurora</productname>は、いくつか例外があるものの、ストリーミングレプリケーションのクラスタのように見えます。フェイルオーバやオンラインリカバリは<productname>Aurora</productname>によって管理されます。
- ですから、<xref linkend="guc-failover-command">、<xref linkend="guc-follow-master-command">、
- それにオンラインリカバリ関連のパラメータは設定の必要がありません。
- この章では、Aurora用の<productname>Pgpool-II</productname>設定を説明します。
- </para>
-
- <sect2 id="example-Aurora-config">
-<!--
- <title>Setting pgpool.conf for Aurora</title>
--->
- <title>Auroraのためにpgpool.confを設定する</title>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- <!--
- Create <filename>pgpool.conf</filename>
- from <filename>pgpool.conf.sample-stream</filename>.
- -->
- <filename>pgpool.conf.sample-stream</filename>をコピーして<filename>pgpool.conf</filename>を作ります。
- </para>
- </listitem>
- <listitem>
- <para>
- <!--
- Set <xref linkend="guc-sr-check-period"> to 0 to
- disable streaming replication delay checking. This
- is because <productname>Aurora</productname> does
- not provide neccessary functions to check the
- replication delay.
- -->
- <xref linkend="guc-sr-check-period">を0にして、ストリーミングレプリケーション遅延チェックを無効にします。
- <productname>Aurora</productname>では、ストリーミングレプリケーションの遅延をチェックするための関数が提供されないためです。
- </para>
- </listitem>
- <listitem>
- <para>
- <!--
- Enable <xref linkend="guc-enable-pool-hba"> to on so
- that md5 authentication is enabled
- (<productname>Aurora</productname> always use md5
- authentication).
- -->
- <xref linkend="guc-enable-pool-hba">をオンにし、md5認証を有効にします。
- （<productname>Aurora</productname>では常にmd5認証が有効になっています)
- </para>
- </listitem>
- <listitem>
- <para>
- <!--
- Create <filename>pool_password</filename>. See <xref linkend="auth-md5">
- for more details.
- -->
- <filename>pool_password</filename>を作成します。
- 詳細は<xref linkend="auth-md5">をご覧ください。
- </para>
- </listitem>
- <listitem>
- <para>
- <!--
- Set <xref linkend="guc-backend-hostname">0 for the
- Aurora writer node. Set
- other <xref linkend="guc-backend-hostname"> for the
- Aurora reader node. Set
- appropreate <xref linkend="guc-backend-weight"> as
- usual. You don't need to
- set <xref linkend="guc-backend-data-directory">
- -->
- <xref linkend="guc-backend-hostname">0をAuroraのwriterノードに設定します。
- 他の<xref linkend="guc-backend-hostname">はAuroraのreaderノードに設定します。
- <xref linkend="guc-backend-data-directory">は設定の必要がありません。
- </para>
- </listitem>
- <listitem>
- <para>
- <!--
- Set <varname>ALWAYS_MASTER</varname> flag to
- the <xref linkend="guc-backend-flag"> for the master
- node.
- -->
- <xref linkend="guc-backend-hostname">0の<xref linkend="guc-backend-flag">の<varname>ALWAYS_MASTER</varname>をオンにします。
- </para>
- </listitem>
- <listitem>
- <para>
- <!--
- Enable health checking.
- Set <xref linkend="guc-health-check-period"> to 5.
- Set <xref linkend="guc-health-check-user">, <xref linkend="guc-health-check-password">,
- <xref linkend="guc-health-check-user"> and
- <xref linkend="guc-health-check-database"> to appropriate values.
- Enable health check retry.
- <productname>Aurora</productname> shutdowns all DB nodes while switching
- over or failover. If the retry is not performed,
- <productname>Pgpool-II</productname> thinks that all DB nodes are in down status
- so that it is required to restart <productname>Pgpool-II</productname>.
- Set <xref linkend="guc-health-check-max-retries"> to 20.
- Set <xref linkend="guc-health-check-retry-delay"> to 1 to avoid the problem.
- -->
- ヘルスチェックを有効にします。
- <xref linkend="guc-health-check-period">に5を設定します.
- <xref linkend="guc-health-check-user">、<xref linkend="guc-health-check-password">、
- <xref linkend="guc-health-check-user">、<xref linkend="guc-health-check-database">
- に適切な値を設定します。
- リトライを設定します。
- <productname>Aurora</productname>は、スィッチングオーバやフェイルオーバの際に、一時的に全DBノードを停止します。
- リトライを行わないと、<productname>Pgpool-II</productname>から見ると全DBノードがダウン状態になり、<productname>Pgpool-II</productname>の再起動が必要になります。
- <xref linkend="guc-health-check-max-retries">を20に、<xref linkend="guc-health-check-retry-delay">を1にして、そのような問題を回避してください。
- </para>
- </listitem>
- <listitem>
- <para>
- <!--
- Disable <xref linkend="guc-failover-on-backend-error">
- to avoid failover when connecting to the backend or
- detecting errors on backend side while executing
- queries for the same reasons above.
- -->
-同様の理由により、接続時あるいは問い合わせ実行中のエラーによるフェイルオーバを避けるために、<xref linkend="guc-failover-on-backend-error">をオフにしてください。
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect2>
- </sect1>
-
- </chapter>
+ <title>設定の例</title>
+ &example-basic;
+ &example-watchdog;
+ &example-cluster;
+ &example-AWS;
+ &example-Aurora;
+ </chapter>
</part>
diff --git a/doc.ja/src/sgml/filelist.sgml b/doc.ja/src/sgml/filelist.sgml
index dc1e3cf47..016932218 100644
--- a/doc.ja/src/sgml/filelist.sgml
+++ b/doc.ja/src/sgml/filelist.sgml
@@ -67,6 +67,11 @@
<!ENTITY wal SYSTEM "wal.sgml">
<!ENTITY examples SYSTEM "examples.sgml">
+<!ENTITY example-basic SYSTEM "example-basic.sgml">
+<!ENTITY example-watchdog SYSTEM "example-watchdog.sgml">
+<!ENTITY example-cluster SYSTEM "example-cluster.sgml">
+<!ENTITY example-AWS SYSTEM "example-AWS.sgml">
+<!ENTITY example-Aurora SYSTEM "example-Aurora.sgml">
<!-- programmer's guide -->
<!ENTITY bgworker SYSTEM "bgworker.sgml">
diff --git a/doc/src/sgml/example-AWS.sgml b/doc/src/sgml/example-AWS.sgml
new file mode 100644
index 000000000..960bc1179
--- /dev/null
+++ b/doc/src/sgml/example-AWS.sgml
@@ -0,0 +1,305 @@
+<!-- doc/src/sgml/example-AWS.sgml -->
+
+<sect1 id="example-AWS">
+ <title>AWS Configuration Example</title>
+
+ <para>
+ This tutorial explains the simple way to try "Watchdog"
+ on <ulink url="https://aws.amazon.com/">AWS</ulink> and using
+ the <ulink url="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html">
+ Elastic IP Address</ulink> as the Virtual IP for the high availability solution.
+ <note>
+ <para>
+ You can use watchdog with <productname>
+ Pgpool-II</productname> in any mode: replication mode,
+ master/slave mode and raw mode.
+ </para>
+ </note>
+ </para>
+
+ <sect2 id="example-AWS-setup">
+ <title>AWS Setup</title>
+ <para>
+ For this example, we will use two node <productname>
+ Pgpool-II</productname> watchdog cluster. So we will set up two
+ Linux Amazon EC2 instances and one Elastic IP address.
+ So for this example, do the following steps:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Launch two Linux Amazon EC2 instances. For this example, we name these
+ instances as "instance-1" and "instance-2"
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Configure the security group for the instances and allow inbound traffic
+ on ports used by pgpool-II and watchdog.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Install the <productname>Pgpool-II</productname> on both instances.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Allocate an Elastic IP address.
+ For this example, we will use "35.163.178.3" as an Elastic IP address"
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </sect2>
+
+ <sect2 id="example-AWS-pgpool-config">
+ <title><productname>Pgpool-II</productname> configurations</title>
+ <para>
+ Mostly the <productname>Pgpool-II</productname> configurations for this
+ example will be same as in the <xref linkend="example-watchdog">, except the
+ <xref linkend="guc-delegate-ip"> which we will not set in this example instead
+ we will use <xref linkend="guc-wd-escalation-command"> and
+ <xref linkend="guc-wd-de-escalation-command"> to switch the
+ Elastic IP address to the maste/Active <productname>Pgpool-II</productname> node.
+ </para>
+
+ <sect3 id="example-AWS-pgpool-config-instance-1">
+ <title><productname>Pgpool-II</productname> configurations on Instance-1</title>
+ <para>
+
+<programlisting>
+use_watchdog = on
+delegate_IP = ''
+wd_hostname = 'instance-1-private-ip'
+other_pgpool_hostname0 = 'instance-2-private-ip'
+other_pgpool_port0 = 9999
+other_wd_port0 = 9000
+wd_escalation_command = '$path_to_script/aws-escalation.sh'
+wd_de_escalation_command = '$path_to_script/aws-de-escalation.sh'
+</programlisting>
+
+ </para>
+ </sect3>
+
+ <sect3 id="example-AWS-pgpool-config-instance-2">
+ <title><productname>Pgpool-II</productname> configurations on Instance-2</title>
+ <para>
+
+<programlisting>
+use_watchdog = on
+delegate_IP = ''
+wd_hostname = 'instance-2-private-ip'
+other_pgpool_hostname0 = 'instance-1-private-ip'
+other_pgpool_port0 = 9999
+other_wd_port0 = 9000
+wd_escalation_command = '$path_to_script/aws-escalation.sh'
+wd_de_escalation_command = '$path_to_script/aws-de-escalation.sh'
+</programlisting>
+
+ </para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="example-AWS-pgpool-aws-escalation-instance">
+ <title>escalation and de-escalation Scripts</title>
+ <para>
+ Create the aws-escalation.sh and aws-de-escalation.sh scripts on both
+ instances and point the <xref linkend="guc-wd-escalation-command"> and
+ <xref linkend="guc-wd-de-escalation-command"> to the respective scripts.
+ </para>
+
+ <note>
+ <para>
+ You may need to configure the AWS CLI first on all AWS instances
+ to enable the execution of commands used by wd-escalation.sh and wd-de-escalation.sh.
+ See <ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">configure AWS CLI</ulink>
+ </para>
+ </note>
+
+ <sect3 id="example-AWS-pgpool-aws-escalation-script">
+ <title>escalation script</title>
+
+ <para>
+ This script will be executed by the watchdog
+ to assign the Elastic IP on the instance when the watchdog becomes the active/master node.
+ Change the INSTANCE_ID and ELASTIC_IP values as per your AWS setup values.
+ </para>
+ <para>
+ <emphasis>aws-escalation.sh:</emphasis>
+<programlisting>
+#! /bin/sh
+
+ELASTIC_IP=35.163.178.3
+# replace it with the Elastic IP address you
+# allocated from the aws console
+INSTANCE_ID=i-0a9b64e449b17ed4b
+# replace it with the instance id of the Instance
+# this script is installed on
+
+echo "Assigning Elastic IP $ELASTIC_IP to the instance $INSTANCE_ID"
+# bring up the Elastic IP
+aws ec2 associate-address --instance-id $INSTANCE_ID --public-ip $ELASTIC_IP
+
+exit 0
+</programlisting>
+
+ </para>
+ </sect3>
+
+ <sect3 id="example-AWS-pgpool-aws-de-escalation-script">
+ <title>de-escalation script</title>
+
+ <para>
+ This script will be executed by watchdog
+ to remove the Elastic IP from the instance when the watchdog resign from the active/master node.
+ </para>
+ <para>
+ <emphasis>aws-de-escalation.sh:</emphasis>
+<programlisting>
+#! /bin/sh
+
+ELASTIC_IP=35.163.178.3
+# replace it with the Elastic IP address you
+# allocated from the aws console
+
+echo "disassociating the Elastic IP $ELASTIC_IP from the instance"
+# bring down the Elastic IP
+aws ec2 disassociate-address --public-ip $ELASTIC_IP
+exit 0
+</programlisting>
+ </para>
+ </sect3>
+
+ <bibliography>
+ <title>AWS Command References</title>
+
+ <biblioentry>
+ <biblioset relation="article">
+ <title><ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">Configure AWS CLI</ulink></title>
+ </biblioset>
+ <biblioset relation="book">
+ <title>AWS Documentation: Configuring the AWS Command Line Interface</title>
+ </biblioset>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioset relation="article">
+ <title><ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/associate-address.html">associate-address</ulink></title>
+ </biblioset>
+ <biblioset relation="book">
+ <title>AWS Documentation: associate-address reference</title>
+ </biblioset>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioset relation="article">
+ <title><ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/disassociate-address.html">disassociate-address</ulink></title>
+ </biblioset>
+ <biblioset relation="book">
+ <title>AWS Documentation: disassociate-address reference</title>
+ </biblioset>
+ </biblioentry>
+
+ </bibliography>
+ </sect2>
+
+ <sect2 id="example-AWS-try">
+ <title>Try it out</title>
+ <para>
+Start <productname>Pgpool-II</productname> on each server with "-n" switch
+ and redirect log messages to the pgpool.log file.
+ The log message of master/active <productname>Pgpool-II</productname> node
+ will show the message of Elastic IP assignment.
+<programlisting>
+LOG: I am the cluster leader node. Starting escalation process
+LOG: escalation process started with PID:23543
+LOG: watchdog: escalation started
+<emphasis>
+Assigning Elastic IP 35.163.178.3 to the instance i-0a9b64e449b17ed4b
+{
+"AssociationId": "eipassoc-39853c42"
+}
+</emphasis>
+LOG: watchdog escalation successful
+LOG: watchdog escalation process with pid: 23543 exit with SUCCESS.
+</programlisting>
+ </para>
+
+ <para>
+ Confirm to ping to the Elastic IP address.
+<programlisting>
+[user@someserver]$ ping 35.163.178.3
+PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
+64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
+64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
+64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
+</programlisting>
+ </para>
+
+ <para>
+ Try to connect <productname>PostgreSQL</productname> by "psql -h ELASTIC_IP -p port".
+<programlisting>
+[user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
+</programlisting>
+ </para>
+ </sect2>
+
+ <sect2 id="example-AWS-vip-switch">
+ <title>Switching Elastic IP</title>
+ <para>
+ To confirm if the Standby server acquires the Elastic IP when the
+ Active server becomes unavailable, Stop the <productname>Pgpool-II</productname>
+ on the Active server. Then, the Standby server should start using the Elastic IP address,
+ And the <productname>Pgpool-II</productname> log will show the below messages.
+
+<programlisting>
+<emphasis>
+LOG: remote node "172.31.2.94:9999 [Linux ip-172-31-2-94]" is shutting down
+LOG: watchdog cluster has lost the coordinator node
+</emphasis>
+LOG: watchdog node state changed from [STANDBY] to [JOINING]
+LOG: watchdog node state changed from [JOINING] to [INITIALIZING]
+LOG: I am the only alive node in the watchdog cluster
+HINT: skipping stand for coordinator state
+LOG: watchdog node state changed from [INITIALIZING] to [MASTER]
+LOG: I am announcing my self as master/coordinator watchdog node
+LOG: I am the cluster leader node
+DETAIL: our declare coordinator message is accepted by all nodes
+LOG: I am the cluster leader node. Starting escalation process
+LOG: escalation process started with PID:23543
+LOG: watchdog: escalation started
+<emphasis>
+Assigning Elastic IP 35.163.178.3 to the instance i-0dd3e60734a6ebe14
+{
+"AssociationId": "eipassoc-39853c42"
+}
+</emphasis>
+LOG: watchdog escalation successful
+LOG: watchdog escalation process with pid: 61581 exit with SUCCESS.
+</programlisting>
+
+ Confirm to ping to the Elastic IP address again.
+
+<programlisting>
+[user@someserver]$ ping 35.163.178.3
+PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
+64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
+64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
+64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
+</programlisting>
+ </para>
+ <para>
+ Try to connect <productname>PostgreSQL</productname> by "psql -h ELASTIC_IP -p port".
+<programlisting>
+[user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
+</programlisting>
+ </para>
+ </sect2>
+</sect1>
diff --git a/doc/src/sgml/example-Aurora.sgml b/doc/src/sgml/example-Aurora.sgml
new file mode 100644
index 000000000..e14d3ed48
--- /dev/null
+++ b/doc/src/sgml/example-Aurora.sgml
@@ -0,0 +1,95 @@
+<sect1 id="example-Aurora">
+ <title>Aurora Configuration Example</title>
+
+ <para>
+<productname>Amazon Aurora for PostgreSQL
+Compatibility</productname> (Aurora) is a managed service for
+<productname>PostgreSQL</productname>. From user's point of
+view, <productname>Aurora</productname> can be regarded as a
+streaming replication cluster with some exceptions. First,
+fail over and online recovery are managed
+by <productname>Aurora</productname>. So you don't need to
+set <xref linkend="guc-failover-command">, <xref linkend="guc-follow-master-command">,
+and recovery related parameters. In this section we explain
+how to set up <productname>Pgpool-II</productname> for Aurora.
+ </para>
+
+ <sect2 id="example-Aurora-config">
+<title>Setting pgpool.conf for Aurora</title>
+<para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Create <filename>pgpool.conf</filename>
+ from <filename>pgpool.conf.sample-stream</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set <xref linkend="guc-sr-check-period"> to 0 to
+ disable streaming replication delay checking. This
+ is because <productname>Aurora</productname> does
+ not provide neccessary functions to check the
+ replication delay.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Enable <xref linkend="guc-enable-pool-hba"> to on so
+ that md5 authentication is enabled
+ (<productname>Aurora</productname> always use md5
+ authentication).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create <filename>pool_password</filename>. See <xref linkend="auth-md5">
+ for more details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set <xref linkend="guc-backend-hostname">0 for the
+ Aurora writer node. Set
+ other <xref linkend="guc-backend-hostname"> for the
+ Aurora reader node. Set
+ appropreate <xref linkend="guc-backend-weight"> as
+ usual. You don't need to
+ set <xref linkend="guc-backend-data-directory">
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set <varname>ALWAYS_MASTER</varname> flag to
+ the <xref linkend="guc-backend-flag">
+ for <xref linkend="guc-backend-hostname">0.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Enable health checking.
+ Set <xref linkend="guc-health-check-period"> to 5.
+ Set <xref linkend="guc-health-check-user">, <xref linkend="guc-health-check-password">,
+ <xref linkend="guc-health-check-user"> and
+ <xref linkend="guc-health-check-database"> to appropriate values.
+ Enable health check retry.
+ <productname>Aurora</productname> shutdowns all DB nodes while switching
+ over or failover. If the retry is not performed,
+ <productname>Pgpool-II</productname> thinks that all DB nodes are in down status
+ so that it is required to restart <productname>Pgpool-II</productname>.
+ Set <xref linkend="guc-health-check-max-retries"> to 20.
+ Set <xref linkend="guc-health-check-retry-delay"> to 1 to avoid the problem.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Disable <xref linkend="guc-failover-on-backend-error">
+ to avoid failover when connecting to the backend or
+ detecting errors on backend side while executing
+ queries for the same reasons above.
+ </para>
+ </listitem>
+ </itemizedlist>
+</para>
+ </sect2>
+</sect1>
diff --git a/doc/src/sgml/example-basic.sgml b/doc/src/sgml/example-basic.sgml
new file mode 100644
index 000000000..887298d65
--- /dev/null
+++ b/doc/src/sgml/example-basic.sgml
@@ -0,0 +1,349 @@
+<!-- doc/src/sgml/example-basic.sgml -->
+<sect1 id="example-basic">
+ <title>Basic Configuration Example</title>
+
+ <sect2 id="example-configs-begin">
+ <title>Let's Begin!</title>
+ <para>
+ First, we must learn how to install and configure <productname>Pgpool-II</productname> and database nodes before using replication.
+ </para>
+
+ <sect3 id="example-configs-begin-installing">
+ <title>Installing <productname>Pgpool-II</productname></title>
+ <para>
+ Installing <productname>Pgpool-II</productname> is very easy.
+ In the directory which you have extracted the source tar ball,
+ execute the following commands.
+<programlisting>
+$ ./configure
+$ make
+$ make install
+</programlisting>
+ <command>configure</command> script collects your system information
+ and use it for the compilation procedure. You can pass command
+ line arguments to <command>configure</command> script to change the default behavior,
+ such as the installation directory. <productname>Pgpool-II</productname>
+ will be installed to <literal>/usr/local</literal> directory by default.
+ </para>
+ <para>
+ <command>make</command> command compiles the source code, and
+ <command>make install</command> will install the executables.
+ You must have write permission on the installation directory.
+ In this tutorial, we will install <productname>Pgpool-II
+ </productname> in the default <literal>/usr/local</literal> directory.
+ </para>
+ <note>
+ <para>
+ <productname>Pgpool-II</productname> requires <literal>libpq</literal>
+ library in <productname>PostgreSQL</productname> 7.4 or later (version 3 protocol).
+ </para>
+ </note>
+ <para>
+ If the <command>configure</command> script displays the following error message, the
+ <literal>libpq</literal> library may not be installed, or it is not of version 3
+<programlisting>
+configure: error: libpq is not installed or libpq is old
+</programlisting>
+ If the library is version 3, but the above message is still displayed, your
+ <literal>libpq</literal> library is probably not recognized by the <command>
+ configure</command> script.
+ The <command>configure</command> script searches for <literal>libpq</literal>
+ library under <literal>/usr/local/pgsql</literal>. If you have installed the
+ <productname>PostgreSQL</productname> in a directory other than <literal>/usr/local/pgsql</literal>, use
+ <literal>--with-pgsql</literal>, or <literal>--with-pgsql-includedir</literal>
+ and <literal>--with-pgsql-libdir</literal> command line options when you
+ execute <command>configure</command>.
+ </para>
+ </sect3>
+
+ <sect3 id="example-configs-begin-config-files">
+ <title>Configuration Files</title>
+ <para>
+ <productname>Pgpool-II</productname> configuration parameters are saved in the
+ <literal>pgpool.conf</literal> file. The file is in <literal>"parameter = value"
+ </literal> per line format. When you install <productname>Pgpool-II</productname>,
+ <literal>pgpool.conf.sample</literal> is automatically created.
+ We recommend copying and renaming it to <literal>pgpool.conf</literal>, and edit
+ it as you like.
+<programlisting>
+$ cp /usr/local/etc/pgpool.conf.sample /usr/local/etc/pgpool.conf
+</programlisting>
+ <productname>Pgpool-II</productname> only accepts connections from the localhost
+ using port 9999 by the default. If you wish to receive conenctions from other hosts,
+ set <xref linkend="guc-listen-addresses"> to <literal>'*'</literal>.
+<programlisting>
+listen_addresses = 'localhost'
+port = 9999
+</programlisting>
+ We will use the default parameters in this tutorial.
+ </para>
+ </sect3>
+
+ <sect3 id="example-configs-begin-config-pcp">
+ <title>Configuring <acronym>PCP</acronym> Commands</title>
+ <para>
+ <productname>Pgpool-II</productname> has an interface for administrative
+ purpose to retrieve information on database nodes, shutdown
+ <productname>Pgpool-II</productname>, etc. via network. To use
+ <acronym>PCP</acronym> commands, user authentication is required.
+ This authentication is different from <productname>PostgreSQL</productname>'s user authentication.
+ A user name and password need to be defined in the <literal>pcp.conf</literal>
+ file. In the file, a user name and password are listed as a pair on each line,
+ and they are separated by a colon (:). Passwords are encrypted in
+ <literal>md5</literal> hash format.
+
+<programlisting>
+postgres:e8a48653851e28c69d0506508fb27fc5
+</programlisting>
+
+ When you install <productname>Pgpool-II</productname>, <literal>pcp.conf.sample
+ </literal> is automatically created. We recommend copying and renaming it
+ to <literal>pcp.conf</literal>, and edit it.
+<programlisting>
+$ cp /usr/local/etc/pcp.conf.sample /usr/local/etc/pcp.conf
+</programlisting>
+ To encrypt your password into md5 hash format, use the <command>pg_md5</command>
+ command, which is installed as one of <productname>Pgpool-II</productname>'s
+ executables. <command>pg_md5</command> takes text as a command line argument,
+ and displays its md5-hashed text.
+ For example, give <literal>"postgres"</literal> as the command line argument,
+ and <command>pg_md5</command> displays md5-hashed text on its standard output.
+<programlisting>
+$ /usr/local/bin/pg_md5 postgres
+e8a48653851e28c69d0506508fb27fc5
+</programlisting>
+ PCP commands are executed via network, so the port number must be configured
+ with <xref linkend="guc-pcp-port"> parameter in <literal>pgpool.conf</literal> file.
+ We will use the default 9898 for <xref linkend="guc-pcp-port"> in this tutorial.
+<programlisting>
+pcp_port = 9898
+</programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-configs-prep-db-nodes">
+ <title>Preparing Database Nodes</title>
+ <para>
+ Now, we need to set up backend <productname>PostgreSQL</productname> servers for <productname>Pgpool-II
+ </productname>. These servers can be placed within the same host as
+ <productname>Pgpool-II</productname>, or on separate machines. If you decide
+ to place the servers on the same host, different port numbers must be assigned
+ for each server. If the servers are placed on separate machines,
+ they must be configured properly so that they can accept network
+ connections from <productname>Pgpool-II</productname>.
+
+<programlisting>
+backend_hostname0 = 'localhost'
+backend_port0 = 5432
+backend_weight0 = 1
+backend_hostname1 = 'localhost'
+backend_port1 = 5433
+backend_weight1 = 1
+backend_hostname2 = 'localhost'
+backend_port2 = 5434
+backend_weight2 = 1
+</programlisting>
+
+ For <xref linkend="guc-backend-hostname">, <xref linkend="guc-backend-port">,
+ <xref linkend="guc-backend-weight">, set the node's hostname, port number,
+ and ratio for load balancing. At the end of each parameter string,
+ node ID must be specified by adding positive integers starting with 0 (i.e. 0, 1, 2..).
+ </para>
+ <note>
+ <para>
+ <xref linkend="guc-backend-weight"> parameters for all nodes are
+ set to 1, meaning that SELECT queries are equally distributed among
+ three servers.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 id="example-configs-start-stop-pgpool">
+ <title>Starting/Stopping <productname>Pgpool-II</productname></title>
+ <para>
+ To fire up <productname>Pgpool-II</productname>, execute the following
+ command on a terminal.
+
+<programlisting>
+$ pgpool
+</programlisting>
+
+ The above command, however, prints no log messages because <productname>
+ Pgpool-II</productname> detaches the terminal. If you want to show
+ <productname>Pgpool-II</productname> log messages, you pass <literal>-n</literal>
+ option to <command>pgpool</command> command so <productname>Pgpool-II</productname>
+ is executed as non-daemon process, and the terminal will not be detached.
+<programlisting>
+$ pgpool -n &
+</programlisting>
+
+ The log messages are printed on the terminal, so it is recommended to use the following options.
+<programlisting>
+$ pgpool -n -d > /tmp/pgpool.log 2>&1 &
+</programlisting>
+
+ The <literal>-d</literal> option enables debug messages to be generated.
+ The above command keeps appending log messages to <literal>/tmp/pgpool.log
+ </literal>. If you need to rotate log files, pass the logs to a external
+ command which has log rotation function.
+ For example, you can use <ulink url="https://httpd.apache.org/docs/2.4/programs/rotatelogs.html">
+ <command>rotatelogs</command></ulink> from Apache2:
+<programlisting>
+$ pgpool -n 2>&1 | /usr/local/apache2/bin/rotatelogs \
+-l -f /var/log/pgpool/pgpool.log.%A 86400 &
+</programlisting>
+
+ This will generate a log file named <literal>"pgpool.log.Thursday"</literal>
+ then rotate it 00:00 at midnight. Rotatelogs adds logs to a file if it already
+ exists. To delete old log files before rotation, you could use cron:
+<programlisting>
+55 23 * * * /usr/bin/find /var/log/pgpool -type f -mtime +5 -exec /bin/rm -f '{}' \;
+</programlisting>
+
+ Please note that rotatelogs may exist as <literal>/usr/sbin/rotatelogs2</literal>
+ in some distributions. <literal>-f</literal> option generates a log file as soon as
+ <command>rotatelogs</command> starts and is available in apache2 2.2.9 or greater.
+ Also <ulink url="http://www.cronolog.org/">cronolog</ulink> can be used.
+<programlisting>
+$ pgpool -n 2>&1 | /usr/sbin/cronolog \
+--hardlink=/var/log/pgsql/pgpool.log \
+'/var/log/pgsql/%Y-%m-%d-pgpool.log' &
+</programlisting>
+
+ To stop <productname>Pgpool-II</productname> execute the following command.
+<programlisting>
+$ pgpool stop
+</programlisting>
+
+ If any client is still connected, <productname>Pgpool-II</productname>
+ waits for it to disconnect, and then terminates itself. Run the following
+ command instead if you want to shutdown <productname>Pgpool-II</productname>
+ forcibly.
+<programlisting>
+$ pgpool -m fast stop
+</programlisting>
+
+ </para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="example-configs-replication">
+ <title>Your First Replication</title>
+ <para>
+ Replication (see <xref linkend="runtime-config-replication-mode">) enables
+ the same data to be copied to multiple database nodes.
+ In this section, we'll use three database nodes, which we have already set
+ up in <xref linkend="example-configs-begin">, and takes you step by step to
+ create a database replication system.
+ Sample data to be replicated will be generated by the
+ <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
+ <command>pgbench</command></ulink> benchmark program.
+ </para>
+
+ <sect3 id="example-configs-config-replication">
+ <title>Configuring Replication</title>
+ <para>
+ To enable the database replication function, set
+ <xref linkend="guc-replication-mode"> to on in <literal>pgpool.conf</literal> file.
+<programlisting>
+replication_mode = true
+</programlisting>
+ When <xref linkend="guc-replication-mode"> is on, <productname>Pgpool-II</productname>
+ will send a copy of a received query to all the database nodes.
+ In addition, when <xref linkend="guc-load-balance-mode"> is set to true,
+ <productname>Pgpool-II</productname> will distribute <acronym>SELECT</acronym> queries
+ among the database nodes.
+<programlisting>
+load_balance_mode = true
+</programlisting>
+ In this section, we will enable both <xref linkend="guc-replication-mode">
+ and <xref linkend="guc-load-balance-mode">.
+ </para>
+ </sect3>
+
+ <sect3 id="example-configs-checking-replication">
+ <title>Checking Replication</title>
+ <para>
+ To reflect the above changes in <literal>pgpool.conf</literal>,
+ <productname>Pgpool-II</productname> must be restarted.
+ Please refer to "Starting/Stopping <productname>Pgpool-II</productname>"
+ <xref linkend="example-configs-start-stop-pgpool">.
+ After configuring <literal>pgpool.conf</literal> and restarting the
+ <productname>Pgpool-II</productname>, let's try the actual replication
+ and see if everything is working.
+ First, we need to create a database to be replicated. We will name it
+ <literal>"bench_replication"</literal>. This database needs to be created
+ on all the nodes. Use the
+ <ulink url="https://www.postgresql.org/docs/current/static/app-createdb.html">
+ <command>createdb</command></ulink> commands through
+ <productname>Pgpool-II</productname>, and the database will be created
+ on all the nodes.
+<programlisting>
+$ createdb -p 9999 bench_replication
+</programlisting>
+ Then, we'll execute <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
+ <command>pgbench</command></ulink> with <literal>-i</literal> option.
+ <literal>-i</literal> option initializes the database with pre-defined tables and data.
+<programlisting>
+$ pgbench -i -p 9999 bench_replication
+</programlisting>
+ The following table is the summary of tables and data, which will be created by
+ <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
+ <command>pgbench -i</command></ulink>. If, on all the nodes, the listed tables and
+ data are created, replication is working correctly.
+ </para>
+
+ <table id="example-configs-checking-replication-table">
+ <title>data summary</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Table Name</entry>
+ <entry>Number of Rows</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>pgbench_branches</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>pgbench_tellers</entry>
+ <entry>10</entry>
+ </row>
+
+ <row>
+ <entry>pgbench_accounts</entry>
+ <entry>100000</entry>
+ </row>
+
+ <row>
+ <entry>pgbench_history</entry>
+ <entry>0</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ Let's use a simple shell script to check the above on all the nodes.
+ The following script will display the number of rows in pgbench_branches,
+ pgbench_tellers, pgbench_accounts, and pgbench_history tables on all the nodes (5432, 5433, 5434).
+<programlisting>
+$ for port in 5432 5433 5434; do
+> echo $port
+> for table_name in pgbench_branches pgbench_tellers pgbench_accounts pgbench_history; do
+> echo $table_name
+> psql -c "SELECT count(*) FROM $table_name" -p $port bench_replication
+> done
+> done
+</programlisting>
+
+ </para>
+ </sect3>
+ </sect2>
+
+</sect1>
diff --git a/doc/src/sgml/example-cluster.sgml b/doc/src/sgml/example-cluster.sgml
new file mode 100644
index 000000000..7f31c933a
--- /dev/null
+++ b/doc/src/sgml/example-cluster.sgml
@@ -0,0 +1,1572 @@
+<sect1 id="example-cluster">
+ <title><productname>Pgpool-II</productname> + Watchdog Setup Example</title>
+ <para>
+ This section shows an example of streaming replication configuration using
+ <productname>Pgpool-II</productname>. In this example, we use 3
+ <productname>Pgpool-II</productname> servers to manage <productname>PostgreSQL</productname>
+ servers to create a robust cluster system and avoid the single point of failure or split brain.
+ </para>
+ <para>
+ <productname>PostgreSQL</productname> 11 is used in this configuration example,
+ but all scripts have been tested with <productname>PostgreSQL</productname> 12.
+ </para>
+ <sect2 id="example-cluster-requirement">
+ <title>Requirements</title>
+ <para>
+We assume that all the Pgpool-II servers and the <productname>PostgreSQL</productname> servers are in the same subnet.
+ </para>
+ </sect2>
+
+ <sect2 id="example-cluster-structure">
+ <title>Cluster System Configuration</title>
+ <para>
+ We use 3 servers with CentOS 7.4. Let these servers be <literal>server1</literal>,
+ <literal>server2</literal>, <literal>server3</literal>.
+ We install <productname>PostgreSQL</productname> and <productname>Pgpool-II</productname> on each server.
+ </para>
+ <para>
+ <figure>
+ <title>Cluster System Configuration</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="cluster_40.gif">
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </para>
+ <note>
+ <para>
+ The roles of <literal>Active</literal>, <literal>Standy</literal>, <literal>Primary</literal>,
+ <literal>Standby</literal> are not fixed and may be changed by further operations.
+ </para>
+ </note>
+ <table id="example-cluster-table-ip">
+ <title>Hostname and IP address</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Hostname</entry>
+ <entry>IP Address</entry>
+ <entry>Virtual IP</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>server1</entry>
+ <entry>192.168.137.101</entry>
+ <entry morerows="2">192.168.137.150</entry>
+ </row>
+ <row>
+ <entry>server2</entry>
+ <entry>192.168.137.102</entry>
+ </row>
+ <row>
+ <entry>server3</entry>
+ <entry>192.168.137.103</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table id="example-cluster-table-postgresql-config">
+ <title>PostgreSQL version and Configuration</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Item</entry>
+ <entry>Value</entry>
+ <entry>Detail</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>PostgreSQL Version</entry>
+ <entry>11.1</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>port</entry>
+ <entry>5432</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>$PGDATA</entry>
+ <entry>/var/lib/pgsql/11/data</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>Archive mode</entry>
+ <entry>on</entry>
+ <entry>/var/lib/pgsql/archivedir</entry>
+ </row>
+ <row>
+ <entry>Replication Slots</entry>
+ <entry>Enable</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>Start automatically</entry>
+ <entry>Disable</entry>
+ <entry>-</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table id="example-cluster-table-pgpool-config">
+ <title>Pgpool-II version and Configuration</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Item</entry>
+ <entry>Value</entry>
+ <entry>Detail</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Pgpool-II Version</entry>
+ <entry>4.1.0</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry morerows='3'>port</entry>
+ <entry>9999</entry>
+ <entry>Pgpool-II accepts connections</entry>
+ </row>
+ <row>
+ <entry>9898</entry>
+ <entry>PCP process accepts connections</entry>
+ </row>
+ <row>
+ <entry>9000</entry>
+ <entry>watchdog accepts connections</entry>
+ </row>
+ <row>
+ <entry>9694</entry>
+ <entry>UDP port for receiving Watchdog's heartbeat signal</entry>
+ </row>
+ <row>
+ <entry>Config file</entry>
+ <entry>/etc/pgpool-II/pgpool.conf</entry>
+ <entry>Pgpool-II config file</entry>
+ </row>
+ <row>
+ <entry>Pgpool-II start user</entry>
+ <entry>root</entry>
+ <entry>See <xref linkend="TUTORIAL-WATCHDOG-START-STOP"> to startup Pgpool-II with non-root user</entry>
+ </row>
+ <row>
+ <entry>Running mode</entry>
+ <entry>streaming replication mode</entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>Watchdog</entry>
+ <entry>on</entry>
+ <entry>Life check method: heartbeat</entry>
+ </row>
+ <row>
+ <entry>Start automatically</entry>
+ <entry>Disable</entry>
+ <entry>-</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
+
+ <sect2 id="example-cluster-installation">
+ <title>Installation</title>
+ <para>
+ In this example, we install <productname>Pgpool-II</productname> 4.1 and <productname>PostgreSQL</productname> 11.1 by using RPM packages.
+ </para>
+
+ <para>
+ Install <productname>PostgreSQL</productname> by using <productname>PostgreSQL</productname> YUM repository.
+ </para>
+<programlisting>
+# yum install https://download.postgresql.org/pub/repos/yum/11/redhat/rhel-7-x86_64/pgdg-centos11-11-2.noarch.rpm
+# yum install postgresql11 postgresql11-libs postgresql11-devel postgresql11-server
+</programlisting>
+ <para>
+ Install <productname>Pgpool-II</productname> by using Pgpool-II YUM repository.
+ </para>
+<programlisting>
+# yum install http://www.pgpool.net/yum/rpms/4.1/redhat/rhel-7-x86_64/pgpool-II-release-4.1-1.noarch.rpm
+# yum install pgpool-II-pg11-*
+</programlisting>
+ </sect2>
+
+ <sect2 id="example-cluster-pre-setup">
+ <title>Before Starting</title>
+ <para>
+ Before you start the configuration process, please check the following prerequisites.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Set up <productname>PostgreSQL</productname> streaming replication on the primary server.
+ In this example, we use WAL archiving.
+ </para>
+ <para>
+ First, we create the directory <filename>/var/lib/pgsql/archivedir</filename> to store
+ <acronym>WAL</acronym> segments on all servers. In this example, only Primary node archives
+ <acronym>WAL</acronym> locally.
+ </para>
+<programlisting>
+[all servers]# su - postgres
+[all servers]$ mkdir /var/lib/pgsql/archivedir
+</programlisting>
+
+ <para>
+ Then we edit the configuration file <filename>$PGDATA/postgresql.conf</filename>
+ on <literal>server1</literal> (primary) as follows. Enable <literal>wal_log_hints</literal>
+ to use <literal>pg_rewind</literal>.
+ Since the Primary may become a Standby later, we set <varname>hot_standby = on</varname>.
+ </para>
+<programlisting>
+listen_addresses = '*'
+archive_mode = on
+archive_command = 'cp "%p" "/var/lib/pgsql/archivedir/%f"'
+max_wal_senders = 10
+max_replication_slots = 10
+wal_level = replica
+hot_standby = on
+wal_log_hints = on
+</programlisting>
+ <para>
+We use the online recovery functionality of <productname>Pgpool-II</productname> to setup standby server after the primary server is started.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Because of the security reasons, we create a user <literal>repl</literal> solely used
+ for replication purpose, and a user <literal>pgpool</literal> for streaming
+ replication delay check and health check of <productname>Pgpool-II</productname>.
+ </para>
+
+ <table id="example-cluster-user">
+ <title>Users</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>User Name</entry>
+ <entry>Passowrd</entry>
+ <entry>Detail</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>repl</entry>
+ <entry>repl</entry>
+ <entry>PostgreSQL replication user</entry>
+ </row>
+ <row>
+ <entry>pgpool</entry>
+ <entry>pgpool</entry>
+ <entry>Pgpool-II health check and replication delay check user</entry>
+ </row>
+ <row>
+ <entry>postgres</entry>
+ <entry>postgres</entry>
+ <entry>User running online recovery</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+<programlisting>
+[server1]# psql -U postgres -p 5432
+postgres=# SET password_encryption = 'scram-sha-256';
+postgres=# CREATE ROLE pgpool WITH LOGIN;
+postgres=# CREATE ROLE repl WITH REPLICATION LOGIN;
+postgres=# \password pgpool
+postgres=# \password repl
+postgres=# \password postgres
+</programlisting>
+
+ <para>
+ If you want to show "replication_state" and "replication_sync_state" column in
+ <xref linkend="SQL-SHOW-POOL-NODES"> command result, role <literal>pgpool</literal>
+ needs to be PostgreSQL super user or or in <literal>pg_monitor</literal> group
+ (<productname>Pgpool-II</productname> 4.1 or later). Grant <literal>pg_monitor</literal>
+ to <literal>pgpool</literal>:
+ </para>
+<programlisting>
+GRANT pg_monitor TO pgpool;
+</programlisting>
+ <note>
+ <para>
+ If you plan to use <xref linkend="guc-detach-false-primary">(<productname>Pgpool-II</productname> 4.0 or later),
+ role "pgpool" needs to be <productname>PostgreSQL</productname> super user or
+ or in "pg_monitor" group to use this feature.
+ </para>
+ </note>
+ <para>
+ Assuming that all the <productname>Pgpool-II</productname> servers and the
+ <productname>PostgreSQL</productname> servers are in the same subnet and edit <filename>pg_hba.conf</filename> to
+ enable <literal>scram-sha-256</literal> authentication method.
+ </para>
+<programlisting>
+host all all samenet scram-sha-256
+host replication all samenet scram-sha-256
+</programlisting>
+ </listitem>
+
+ <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>.
+ </para>
+<programlisting>
+[all servers]# cd ~/.ssh
+[all servers]# ssh-keygen -t rsa -f id_rsa_pgpool
+[all servers]# ssh-copy-id -i id_rsa_pgpool.pub postgres@server1
+[all servers]# ssh-copy-id -i id_rsa_pgpool.pub postgres@server2
+[all servers]# ssh-copy-id -i id_rsa_pgpool.pub postgres@server3
+
+[all servers]# su - postgres
+[all servers]$ cd ~/.ssh
+[all servers]$ ssh-keygen -t rsa -f id_rsa_pgpool
+[all servers]$ ssh-copy-id -i id_rsa_pgpool.pub postgres@server1
+[all servers]$ ssh-copy-id -i id_rsa_pgpool.pub postgres@server2
+[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. Edit <filename>/etc/ssh/sshd_config</filename>
+ if necessary and restart sshd.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To allow <literal>repl</literal> user without specifying password for streaming
+ replication and online recovery, and execute <application>pg_rewind</application>
+ using <literal>postgres</literal>, we create the <filename>.pgpass</filename> file
+ in <literal>postgres</literal> user's home directory and change the permisson to
+ <literal>600</literal> on each <productname>PostgreSQL</productname> server.
+ </para>
+<programlisting>
+[all servers]# su - postgres
+[all servers]$ vi /var/lib/pgsql/.pgpass
+server1:5432:replication:repl:<repl user password>
+server2:5432:replication:repl:<repl user passowrd>
+server3:5432:replication:repl:<repl user passowrd>
+server1:5432:postgres:postgres:<postgres user passowrd>
+server2:5432:postgres:postgres:<postgres user passowrd>
+server3:5432:postgres:postgres:<postgres user passowrd>
+[all servers]$ chmod 600 /var/lib/pgsql/.pgpass
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+When connect to <productname>Pgpool-II</productname> and <productname>PostgreSQL</productname> servers, the target port must be accessible by enabling firewall management softwares. Following is an example for <systemitem>CentOS/RHEL7</systemitem>.
+ </para>
+<programlisting>
+[all servers]# firewall-cmd --permanent --zone=public --add-service=postgresql
+[all servers]# firewall-cmd --permanent --zone=public --add-port=9999/tcp --add-port=9898/tcp --add-port=9000/tcp --add-port=9694/udp
+[all servers]# firewall-cmd --reload
+</programlisting>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="example-cluster-pgpool-config">
+ <title><productname>Pgpool-II</productname> Configuration</title>
+ <sect3 id="example-cluster-pgpool-config-common">
+ <title>Common Settings</title>
+ <para>
+ Here are the common settings on <literal>server1</literal>, <literal>server2</literal> and <literal>server3</literal>.
+ </para>
+ <para>
+ When installing <productname>Pgpool-II</productname> from RPM, all the
+ <productname>Pgpool-II</productname> configuration files are in <filename>/etc/pgpool-II</filename>.
+ In this example, we copy the sample configuration file for streaming replicaton mode.
+ </para>
+<programlisting>
+# cp /etc/pgpool-II/pgpool.conf.sample-stream /etc/pgpool-II/pgpool.conf
+</programlisting>
+ <para>
+ To allow Pgpool-II to accept all incoming connections, we set <varname>listen_addresses = '*'</varname>.
+ </para>
+<programlisting>
+listen_addresses = '*'
+</programlisting>
+ <para>
+ Specify replication delay check user and password. In this example, we leave
+ <xref linkend="GUC-SR-CHECK-USER"> empty, and create the entry in <xref linkend="GUC-POOL-PASSWD">.
+ From <productname>Pgpool-II</productname> 4.0, if these parameters are left blank,
+ <productname>Pgpool-II</productname> will first try to get the password for that
+ specific user from <xref linkend="GUC-SR-CHECK-PASSWORD"> file before using the
+ empty password.
+ </para>
+<programlisting>
+sr_check_user = 'pgpool'
+sr_check_password = ''
+</programlisting>
+ <para>
+ Enable health check so that <productname>Pgpool-II</> performs failover. Also, if the network is unstable,
+ the health check fails even though the backend is running properly, failover or degenerate operation may occur.
+ In order to prevent such incorrect detection of health check, we set <varname>health_check_max_retries = 3</varname>.
+ Specify <xref linkend="GUC-HEALTH-CHECK-USER"> and <xref linkend="GUC-HEALTH-CHECK-PASSWORD"> in
+ the same way like <xref linkend="GUC-SR-CHECK-USER"> and <xref linkend="GUC-SR-CHECK-PASSWORD">.
+ </para>
+<programlisting>
+health_check_period = 5
+ # Health check period
+ # Disabled (0) by default
+health_check_timeout = 30
+ # Health check timeout
+ # 0 means no timeout
+health_check_user = 'pgpool'
+health_check_password = ''
+
+health_check_max_retries = 3
+</programlisting>
+ <para>
+ Specify the <productname>PostgreSQL</productname> backend informations.
+ Multiple backends can be specified by adding a number at the end of the parameter name.
+ </para>
+<programlisting>
+# - Backend Connection Settings -
+
+backend_hostname0 = 'server1'
+ # Host name or IP address to connect to for backend 0
+backend_port0 = 5432
+ # Port number for backend 0
+backend_weight0 = 1
+ # Weight for backend 0 (only in load balancing mode)
+backend_data_directory0 = '/var/lib/pgsql/11/data'
+ # Data directory for backend 0
+backend_flag0 = 'ALLOW_TO_FAILOVER'
+ # Controls various backend behavior
+ # ALLOW_TO_FAILOVER or DISALLOW_TO_FAILOVER
+backend_hostname1 = 'server2'
+backend_port1 = 5432
+backend_weight1 = 1
+backend_data_directory1 = '/var/lib/pgsql/11/data'
+backend_flag1 = 'ALLOW_TO_FAILOVER'
+
+backend_hostname2 = 'server3'
+backend_port2 = 5432
+backend_weight2 = 1
+backend_data_directory2 = '/var/lib/pgsql/11/data'
+backend_flag2 = 'ALLOW_TO_FAILOVER'
+</programlisting>
+ <para>
+ To show "replication_state" and "replication_sync_state" column in <xref linkend="SQL-SHOW-POOL-NODES">
+ command result, <xref linkend="GUC-BACKEND-APPLICATION-NAME"> parameter is required.
+ Here we specify each backend's hostname in these parameters. (<productname>Pgpool-II</productname> 4.1 or later)
+ </para>
+<programlisting>
+...
+backend_application_name0 = 'server1'
+...
+backend_application_name1 = 'server2'
+...
+backend_application_name2 = 'server3'
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-failover">
+ <title>Failover configuration</title>
+ <para>
+ Specify failover.sh script to be executed after failover in <varname>failover_command</varname>
+ parameter.
+ If we use 3 PostgreSQL servers, we need to specify follow_master_command to run after failover on the primary node failover.
+ In case of two PostgreSQL servers, follow_master_command setting is not necessary.
+ </para>
+ <para>
+ <productname>Pgpool-II</productname> replaces the following special characters with the backend specific
+ information while executing the scripts.
+ See <xref linkend="GUC-FAILOVER-COMMAND"> for more details about each character.
+ </para>
+<programlisting>
+failover_command = '/etc/pgpool-II/failover.sh %d %h %p %D %m %H %M %P %r %R %N %S'
+follow_master_command = '/etc/pgpool-II/follow_master.sh %d %h %p %D %m %M %H %P %r %R'
+</programlisting>
+ <note>
+ <para>
+ <emphasis>%N</emphasis> and <emphasis>%S</emphasis> are added in <productname>Pgpool-II</productname> 4.1.
+ Please note that these characters cannot be specified if using Pgpool-II 4.0 or earlier.
+ </para>
+ </note>
+ <para>
+ Create <filename>/etc/pgpool-II/failover.sh</filename>, and add execute permission.
+ </para>
+<programlisting>
+# vi /etc/pgpool-II/failover.sh
+# vi /etc/pgpool-II/follow_master.sh
+# chmod +x /etc/pgpool-II/{failover.sh,follow_master.sh}
+</programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ /etc/pgpool-II/failover.sh
+ </para>
+<programlisting>
+#!/bin/bash
+# This script is run by failover_command.
+
+set -o xtrace
+exec > >(logger -i -p local1.info) 2>&1
+
+# Special values:
+# %d = failed node id
+# %h = failed node hostname
+# %p = failed node port number
+# %D = failed node database cluster path
+# %m = new master node id
+# %H = new master node hostname
+# %M = old master node id
+# %P = old primary node id
+# %r = new master port number
+# %R = new master database cluster path
+# %N = old primary node hostname
+# %S = old primary node port number
+# %% = '%' character
+
+FAILED_NODE_ID="$1"
+FAILED_NODE_HOST="$2"
+FAILED_NODE_PORT="$3"
+FAILED_NODE_PGDATA="$4"
+NEW_MASTER_NODE_ID="$5"
+NEW_MASTER_NODE_HOST="$6"
+OLD_MASTER_NODE_ID="$7"
+OLD_PRIMARY_NODE_ID="$8"
+NEW_MASTER_NODE_PORT="$9"
+NEW_MASTER_NODE_PGDATA="${10}"
+OLD_PRIMARY_NODE_HOST="${11}"
+OLD_PRIMARY_NODE_PORT="${12}"
+
+PGHOME=/usr/pgsql-11
+
+
+logger -i -p local1.info failover.sh: start: failed_node_id=$FAILED_NODE_ID old_primary_node_id=$OLD_PRIMARY_NODE_ID failed_host=$FAILED_NODE_HOST new_master_host=$NEW_MASTER_NODE_HOST
+
+## Test passwrodless SSH
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ls /tmp > /dev/null
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.info failover.sh: passwrodless SSH to postgres@${NEW_MASTER_NODE_HOST} failed. Please setup passwrodless SSH.
+ exit 1
+fi
+
+## If Standby node is down, skip failover.
+if [ $FAILED_NODE_ID -ne $OLD_PRIMARY_NODE_ID ]; then
+ logger -i -p local1.info failover.sh: Standby node is down. Skipping failover.
+
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$OLD_PRIMARY_NODE_HOST -i ~/.ssh/id_rsa_pgpool "
+ ${PGHOME}/bin/psql -p $OLD_PRIMARY_NODE_PORT -c \"SELECT pg_drop_replication_slot('${FAILED_NODE_HOST}')\"
+ "
+
+ if [ $? -ne 0 ]; then
+ logger -i -p local1.error failover.sh: drop replication slot "${FAILED_NODE_HOST}" failed
+ exit 1
+ fi
+
+ exit 0
+fi
+
+## Promote Standby node.
+logger -i -p local1.info failover.sh: Primary node is down, promote standby node ${NEW_MASTER_NODE_HOST}.
+
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+ postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ${PGHOME}/bin/pg_ctl -D ${NEW_MASTER_NODE_PGDATA} -w promote
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.error failover.sh: new_master_host=$NEW_MASTER_NODE_HOST promote failed
+ exit 1
+fi
+
+logger -i -p local1.info failover.sh: end: new_master_node_id=$NEW_MASTER_NODE_ID started as the primary node
+exit 0
+</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ /etc/pgpool-II/follow_master.sh
+ </para>
+<programlisting>
+#!/bin/bash
+# This script is run after failover_command to synchronize the Standby with the new Primary.
+# First try pg_rewind. If pg_rewind failed, use pg_basebackup.
+
+set -o xtrace
+exec > >(logger -i -p local1.info) 2>&1
+
+# Special values:
+# %d = failed node id
+# %h = failed node hostname
+# %p = failed node port number
+# %D = failed node database cluster path
+# %m = new master node id
+# %H = new master node hostname
+# %M = old master node id
+# %P = old primary node id
+# %r = new master port number
+# %R = new master database cluster path
+# %N = old primary node hostname
+# %S = old primary node port number
+# %% = '%' character
+
+FAILED_NODE_ID="$1"
+FAILED_NODE_HOST="$2"
+FAILED_NODE_PORT="$3"
+FAILED_NODE_PGDATA="$4"
+NEW_MASTER_NODE_ID="$5"
+OLD_MASTER_NODE_ID="$6"
+NEW_MASTER_NODE_HOST="$7"
+OLD_PRIMARY_NODE_ID="$8"
+NEW_MASTER_NODE_PORT="$9"
+NEW_MASTER_NODE_PGDATA="${10}"
+
+PGHOME=/usr/pgsql-11
+ARCHIVEDIR=/var/lib/pgsql/archivedir
+REPLUSER=repl
+PCP_USER=pgpool
+PGPOOL_PATH=/usr/bin
+PCP_PORT=9898
+
+logger -i -p local1.info follow_master.sh: start: Standby node ${FAILED_NODE_ID}
+
+## Test passwrodless SSH
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ls /tmp > /dev/null
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.info follow_master.sh: passwrodless SSH to postgres@${NEW_MASTER_NODE_HOST} failed. Please setup passwrodless SSH.
+ exit 1
+fi
+
+## Get PostgreSQL major version
+PGVERSION=`${PGHOME}/bin/initdb -V | awk '{print $3}' | sed 's/\..*//' | sed 's/\([0-9]*\)[a-zA-Z].*/\1/'`
+
+if [ $PGVERSION -ge 12 ]; then
+RECOVERYCONF=${FAILED_NODE_PGDATA}/myrecovery.conf
+else
+RECOVERYCONF=${FAILED_NODE_PGDATA}/recovery.conf
+fi
+
+## Check the status of Standby
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+postgres@${FAILED_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ${PGHOME}/bin/pg_ctl -w -D ${FAILED_NODE_PGDATA} status
+
+
+## If Standby is running, synchronize it with the new Primary.
+if [ $? -eq 0 ]; then
+
+ logger -i -p local1.info follow_master.sh: pg_rewind for $FAILED_NODE_ID
+
+ # Create replication slot "${FAILED_NODE_HOST}"
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool "
+ ${PGHOME}/bin/psql -p ${NEW_MASTER_NODE_PORT} -c \"SELECT pg_create_physical_replication_slot('${FAILED_NODE_HOST}');\"
+ "
+
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${FAILED_NODE_HOST} -i ~/.ssh/id_rsa_pgpool "
+
+ set -o errexit
+
+ ${PGHOME}/bin/pg_ctl -w -m f -D ${FAILED_NODE_PGDATA} stop
+
+ cat > ${RECOVERYCONF} << EOT
+primary_conninfo = 'host=${NEW_MASTER_NODE_HOST} port=${NEW_MASTER_NODE_PORT} user=${REPLUSER} application_name=${FAILED_NODE_HOST} passfile=''/var/lib/pgsql/.pgpass'''
+recovery_target_timeline = 'latest'
+restore_command = 'scp ${NEW_MASTER_NODE_HOST}:${ARCHIVEDIR}/%f %p'
+primary_slot_name = '${FAILED_NODE_HOST}'
+EOT
+
+ if [ ${PGVERSION} -ge 12 ]; then
+ touch ${FAILED_NODE_PGDATA}/standby.signal
+ else
+ echo \"standby_mode = 'on'\" >> ${RECOVERYCONF}
+ fi
+
+ ${PGHOME}/bin/pg_rewind -D ${FAILED_NODE_PGDATA} --source-server=\"user=postgres host=${NEW_MASTER_NODE_HOST} port=${NEW_MASTER_NODE_PORT}\"
+
+ "
+
+ if [ $? -ne 0 ]; then
+ logger -i -p local1.error follow_master.sh: end: pg_rewind failed. Try pg_basebackup.
+
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${FAILED_NODE_HOST} -i ~/.ssh/id_rsa_pgpool "
+
+ set -o errexit
+
+ # Execute pg_basebackup
+ rm -rf ${FAILED_NODE_PGDATA}
+ rm -rf ${ARCHIVEDIR}/*
+ ${PGHOME}/bin/pg_basebackup -h ${NEW_MASTER_NODE_HOST} -U $REPLUSER -p ${NEW_MASTER_NODE_PORT} -D ${FAILED_NODE_PGDATA} -X stream
+
+ if [ ${PGVERSION} -ge 12 ]; then
+ sed -i -e \"\\\$ainclude_if_exists = '$(echo ${RECOVERYCONF} | sed -e 's/\//\\\//g')'\" \
+ -e \"/^include_if_exists = '$(echo ${RECOVERYCONF} | sed -e 's/\//\\\//g')'/d\" ${FAILED_NODE_PGDATA}/postgresql.conf
+ fi
+
+ cat > ${RECOVERYCONF} << EOT
+primary_conninfo = 'host=${NEW_MASTER_NODE_HOST} port=${NEW_MASTER_NODE_PORT} user=${REPLUSER} application_name=${FAILED_NODE_HOST} passfile=''/var/lib/pgsql/.pgpass'''
+recovery_target_timeline = 'latest'
+restore_command = 'scp ${NEW_MASTER_NODE_HOST}:${ARCHIVEDIR}/%f %p'
+primary_slot_name = '${FAILED_NODE_HOST}'
+EOT
+
+ if [ ${PGVERSION} -ge 12 ]; then
+ touch ${FAILED_NODE_PGDATA}/standby.signal
+ else
+ echo \"standby_mode = 'on'\" >> ${RECOVERYCONF}
+ fi
+ "
+
+ if [ $? -ne 0 ]; then
+ # drop replication slot
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool "
+ ${PGHOME}/bin/psql -p ${NEW_MASTER_NODE_PORT} -c \"SELECT pg_drop_replication_slot('${FAILED_NODE_HOST}')\"
+ "
+
+ logger -i -p local1.error follow_master.sh: end: pg_basebackup failed
+ exit 1
+ fi
+ fi
+
+ # start Standby node on ${FAILED_NODE_HOST}
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+ postgres@${FAILED_NODE_HOST} -i ~/.ssh/id_rsa_pgpool $PGHOME/bin/pg_ctl -l /dev/null -w -D ${FAILED_NODE_PGDATA} start
+
+ # If start Standby successfully, attach this node
+ if [ $? -eq 0 ]; then
+
+ # Run pcp_attact_node to attach Standby node to Pgpool-II.
+ ${PGPOOL_PATH}/pcp_attach_node -w -h localhost -U $PCP_USER -p ${PCP_PORT} -n ${FAILED_NODE_ID}
+
+ if [ $? -ne 0 ]; then
+ logger -i -p local1.error follow_master.sh: end: pcp_attach_node failed
+ exit 1
+ fi
+
+ # If start Standby failed, drop replication slot "${FAILED_NODE_HOST}"
+ else
+
+ ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${NEW_MASTER_NODE_HOST} -i ~/.ssh/id_rsa_pgpool \
+ ${PGHOME}/bin/psql -p ${NEW_MASTER_NODE_PORT} -c "SELECT pg_drop_replication_slot('${FAILED_NODE_HOST}')"
+
+ logger -i -p local1.error follow_master.sh: end: follow master command failed
+ exit 1
+ fi
+
+else
+ logger -i -p local1.info follow_master.sh: failed_nod_id=${FAILED_NODE_ID} is not running. skipping follow master command
+ exit 0
+fi
+
+logger -i -p local1.info follow_master.sh: end: follow master command complete
+exit 0
+</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-online-recovery">
+ <title>Pgpool-II Online Recovery Configurations</title>
+ <para>
+ Next, in order to perform online recovery with <productname>Pgpool-II</productname> we specify
+ the <productname>PostgreSQL</productname> user name and online recovery command
+ <command>recovery_1st_stage</command>.
+ Because <emphasis>Superuser</emphasis> privilege in <productname>PostgreSQL</productname>
+ is required for performing online recovery, we specify <literal>postgres</literal> user in <xref linkend="GUC-RECOVERY-USER">.
+ Then, we create <filename>recovery_1st_stage</filename> and <filename>pgpool_remote_start</filename>
+ in database cluster directory of <productname>PostgreSQL</productname> primary server (server1), and add execute permission.
+
+ </para>
+<programlisting>
+recovery_user = 'postgres'
+ # Online recovery user
+recovery_password = ''
+ # Online recovery password
+
+recovery_1st_stage_command = 'recovery_1st_stage'
+</programlisting>
+<programlisting>
+[server1]# su - postgres
+[server1]$ vi /var/lib/pgsql/11/data/recovery_1st_stage
+[server1]$ vi /var/lib/pgsql/11/data/pgpool_remote_start
+[server1]$ chmod +x /var/lib/pgsql/11/data/{recovery_1st_stage,pgpool_remote_start}
+</programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ /var/lib/pgsql/11/data/recovery_1st_stage
+ </para>
+<programlisting>
+#!/bin/bash
+# This script is executed by "recovery_1st_stage" to recovery a Standby node.
+
+set -o xtrace
+exec > >(logger -i -p local1.info) 2>&1
+
+PRIMARY_NODE_PGDATA="$1"
+DEST_NODE_HOST="$2"
+DEST_NODE_PGDATA="$3"
+PRIMARY_NODE_PORT="$4"
+DEST_NODE_ID="$5"
+DEST_NODE_PORT="$6"
+
+PRIMARY_NODE_HOST=$(hostname)
+PGHOME=/usr/pgsql-11
+ARCHIVEDIR=/var/lib/pgsql/archivedir
+REPLUSER=repl
+
+logger -i -p local1.info recovery_1st_stage: start: pg_basebackup for Standby node $DEST_NODE_ID
+
+## Test passwrodless SSH
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${DEST_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ls /tmp > /dev/null
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.info recovery_1st_stage: passwrodless SSH to postgres@${DEST_NODE_HOST} failed. Please setup passwrodless SSH.
+ exit 1
+fi
+
+## Get PostgreSQL major version
+PGVERSION=`${PGHOME}/bin/initdb -V | awk '{print $3}' | sed 's/\..*//' | sed 's/\([0-9]*\)[a-zA-Z].*/\1/'`
+if [ $PGVERSION -ge 12 ]; then
+ RECOVERYCONF=${DEST_NODE_PGDATA}/myrecovery.conf
+else
+ RECOVERYCONF=${DEST_NODE_PGDATA}/recovery.conf
+fi
+
+## Create replication slot "${DEST_NODE_HOST}"
+${PGHOME}/bin/psql -p ${PRIMARY_NODE_PORT} << EOQ
+SELECT pg_create_physical_replication_slot('${DEST_NODE_HOST}');
+EOQ
+
+## Execute pg_basebackup to recovery Standby node
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$DEST_NODE_HOST -i ~/.ssh/id_rsa_pgpool "
+
+ set -o errexit
+
+ rm -rf $DEST_NODE_PGDATA
+ rm -rf $ARCHIVEDIR/*
+
+ ${PGHOME}/bin/pg_basebackup -h $PRIMARY_NODE_HOST -U $REPLUSER -p $PRIMARY_NODE_PORT -D $DEST_NODE_PGDATA -X stream
+
+ if [ ${PGVERSION} -ge 12 ]; then
+ sed -i -e \"\\\$ainclude_if_exists = '$(echo ${RECOVERYCONF} | sed -e 's/\//\\\//g')'\" \
+ -e \"/^include_if_exists = '$(echo ${RECOVERYCONF} | sed -e 's/\//\\\//g')'/d\" ${DEST_NODE_PGDATA}/postgresql.conf
+ fi
+
+ cat > ${RECOVERYCONF} << EOT
+primary_conninfo = 'host=${PRIMARY_NODE_HOST} port=${PRIMARY_NODE_PORT} user=${REPLUSER} application_name=${DEST_NODE_HOST} passfile=''/var/lib/pgsql/.pgpass'''
+recovery_target_timeline = 'latest'
+restore_command = 'scp ${PRIMARY_NODE_HOST}:${ARCHIVEDIR}/%f %p'
+primary_slot_name = '${DEST_NODE_HOST}'
+EOT
+
+ if [ ${PGVERSION} -ge 12 ]; then
+ touch ${DEST_NODE_PGDATA}/standby.signal
+ else
+ echo \"standby_mode = 'on'\" >> ${RECOVERYCONF}
+ fi
+
+ sed -i \"s/#*port = .*/port = ${DEST_NODE_PORT}/\" ${DEST_NODE_PGDATA}/postgresql.conf
+"
+
+if [ $? -ne 0 ]; then
+
+ ${PGHOME}/bin/psql -p ${PRIMARY_NODE_PORT} << EOQ
+SELECT pg_drop_replication_slot('${DEST_NODE_HOST}');
+EOQ
+
+ logger -i -p local1.error recovery_1st_stage: end: pg_basebackup failed. online recovery failed
+ exit 1
+fi
+
+logger -i -p local1.info recovery_1st_stage: end: recovery_1st_stage complete
+exit 0
+</programlisting>
+ </listitem>
+ <listitem>
+
+ <para>
+ /var/lib/pgsql/11/data/pgpool_remote_start
+ </para>
+<programlisting>
+#!/bin/bash
+# This script is run after recovery_1st_stage to start Standby node.
+
+set -o xtrace
+exec > >(logger -i -p local1.info) 2>&1
+
+PGHOME=/usr/pgsql-11
+DEST_NODE_HOST="$1"
+DEST_NODE_PGDATA="$2"
+
+
+logger -i -p local1.info pgpool_remote_start: start: remote start Standby node $DEST_NODE_HOST
+
+## Test passwrodless SSH
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${DEST_NODE_HOST} -i ~/.ssh/id_rsa_pgpool ls /tmp > /dev/null
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.info pgpool_remote_start: passwrodless SSH to postgres@${DEST_NODE_HOST} failed. Please setup passwrodless SSH.
+ exit 1
+fi
+
+## Start Standby node
+ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$DEST_NODE_HOST -i ~/.ssh/id_rsa_pgpool "
+ $PGHOME/bin/pg_ctl -l /dev/null -w -D $DEST_NODE_PGDATA start
+"
+
+if [ $? -ne 0 ]; then
+ logger -i -p local1.error pgpool_remote_start: $DEST_NODE_HOST PostgreSQL start failed.
+ exit 1
+fi
+
+logger -i -p local1.info pgpool_remote_start: end: $DEST_NODE_HOST PostgreSQL started successfully.
+exit 0
+</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ In order to use the online recovery functionality, the functions of
+ <function>pgpool_recovery</function>, <function>pgpool_remote_start</function>,
+ <function>pgpool_switch_xlog</function> are required, so we need install
+ <function>pgpool_recovery</function> on template1 of <productname>PostgreSQL</productname> server
+ <literal>server1</literal>.
+ </para>
+<programlisting>
+[server1]# su - postgres
+[server1]$ psql template1 -c "CREATE EXTENSION pgpool_recovery"
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-auth">
+ <title>Client Authentication Configuration</title>
+ <para>
+ Because in the section <link linkend="EXAMPLE-CLUSTER-PRE-SETUP">Before Starting</link>,
+ we already set <productname>PostgreSQL</productname> authentication method to
+ <acronym>scram-sha-256</acronym>, it is necessary to set a client authentication by
+ <productname>Pgpool-II</productname> to connect to backend nodes.
+ When installing with RPM, the <productname>Pgpool-II</productname> configuration file
+ <filename>pool_hba.conf</filename> is in <filename>/etc/pgpool-II</filename>.
+ By default, pool_hba authentication is disabled, set <varname>enable_pool_hba = on</varname>
+ to enable it.
+ </para>
+<programlisting>
+enable_pool_hba = on
+</programlisting>
+ <para>
+ The format of <filename>pool_hba.conf</filename> file follows very closely PostgreSQL's
+ <filename>pg_hba.conf</filename> format. Set <literal>pgpool</literal> and <literal>postgres</literal> user's authentication method to <literal>scram-sha-256</literal>.
+ </para>
+<programlisting>
+host all pgpool 0.0.0.0/0 scram-sha-256
+host all postgres 0.0.0.0/0 scram-sha-256
+</programlisting>
+ <note>
+ <para>
+ Please note that in <productname>Pgpool-II</productname> 4.0 only AES encrypted password or clear text password
+ can be specified in <xref linkend="guc-health-check-password">, <xref linkend="guc-sr-check-password">,
+ <xref linkend="guc-wd-lifecheck-password">, <xref linkend="guc-recovery-password"> in <filename>pgpool.conf</filename>.
+ </para>
+ </note>
+ <para>
+ The default password file name for authentication is <xref linkend="GUC-POOL-PASSWD">.
+ To use <literal>scram-sha-256</literal> authentication, the decryption key to decrypt the passwords
+ is required. We create the .pgpoolkey file in root user's home directory.
+<programlisting>
+[all servers]# echo 'some string' > ~/.pgpoolkey
+[all servers]# chmod 600 ~/.pgpoolkey
+</programlisting>
+ </para>
+ <para>
+ Execute command <command>pg_enc -m -k /path/to/.pgpoolkey -u username -p</command> to regist user
+ name and <literal>AES</literal> encrypted password in file <filename>pool_passwd</filename>.
+ If <filename>pool_passwd</filename> doesn't exist yet, it will be created in the same directory as
+ <filename>pgpool.conf</filename>.
+ </para>
+<programlisting>
+[all servers]# pg_enc -m -k /root/.pgpoolkey -u pgpool -p
+db password: [pgpool user's password]
+[all servers]# pg_enc -m -k /root/.pgpoolkey -u postgres -p
+db password: [postgres user's passowrd]
+
+# cat /etc/pgpool-II/pool_passwd
+pgpool:AESheq2ZMZjynddMWk5sKP/Rw==
+postgres:AESHs/pWL5rtXy2IwuzroHfqg==
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-watchdog">
+ <title>Watchdog Configuration</title>
+ <para>
+ Enable watchdog functionality on <literal>server1</literal>, <literal>server2</literal>, <literal>server3</literal>.
+ </para>
+<programlisting>
+use_watchdog = on
+</programlisting>
+ <para>
+ Specify virtual IP address that accepts connections from clients on
+ <literal>server1</literal>, <literal>server2</literal>, <literal>server3</literal>.
+ Ensure that the IP address set to virtual IP isn't used yet.
+ </para>
+<programlisting>
+delegate_IP = '192.168.137.150'
+</programlisting>
+
+ <para>
+ To bring up/down the virtual IP and send the ARP requests, we set <xref linkend="GUC-IF-UP-CMD">, <xref linkend="GUC-IF-DOWN-CMD"> and <xref linkend="GUC-ARPING-CMD">.
+ The network interface used in this example is "enp0s8".
+ </para>
+<programlisting>
+if_up_cmd = 'ip addr add $_IP_$/24 dev enp0s8 label enp0s8:0'
+ # startup delegate IP command
+if_down_cmd = 'ip addr del $_IP_$/24 dev enp0s8'
+ # shutdown delegate IP command
+arping_cmd = 'arping -U $_IP_$ -w 1 -I enp0s8'
+ # arping command
+</programlisting>
+ <para>
+ Set <xref linkend="GUC-IF-CMD-PATH"> and <xref linkend="GUC-ARPING-PATH"> according to the
+ command path.
+ </para>
+<programlisting>
+if_cmd_path = '/sbin'
+ # path to the directory where if_up/down_cmd exists
+arping_path = '/usr/sbin'
+ # arping command path
+</programlisting>
+ <para>
+ Specify the hostname and port number of each <productname>Pgpool-II</productname> server.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>server1</literal>
+ </para>
+<programlisting>
+wd_hostname = 'server1'
+wd_port = 9000
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>server2</literal>
+ </para>
+<programlisting>
+wd_hostname = 'server2'
+wd_port = 9000
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>server3</literal>
+ </para>
+ <programlisting>
+wd_hostname = 'server3'
+wd_port = 9000
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Specify the hostname, <productname>Pgpool-II</productname> port number, and watchdog port number of monitored <productname>Pgpool-II</productname> servers on each <productname>Pgpool-II</productname> server.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>server1</literal>
+ </para>
+<programlisting>
+# - Other pgpool Connection Settings -
+
+other_pgpool_hostname0 = 'server2'
+ # Host name or IP address to connect to for other pgpool 0
+ # (change requires restart)
+other_pgpool_port0 = 9999
+ # Port number for other pgpool 0
+ # (change requires restart)
+other_wd_port0 = 9000
+ # Port number for other watchdog 0
+ # (change requires restart)
+other_pgpool_hostname1 = 'server3'
+other_pgpool_port1 = 9999
+other_wd_port1 = 9000
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>server2</literal>
+ </para>
+<programlisting>
+# - Other pgpool Connection Settings -
+
+other_pgpool_hostname0 = 'server1'
+ # Host name or IP address to connect to for other pgpool 0
+ # (change requires restart)
+other_pgpool_port0 = 9999
+ # Port number for other pgpool 0
+ # (change requires restart)
+other_wd_port0 = 9000
+ # Port number for other watchdog 0
+ # (change requires restart)
+other_pgpool_hostname1 = 'server3'
+other_pgpool_port1 = 9999
+other_wd_port1 = 9000
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>server3</literal>
+ </para>
+<programlisting>
+# - Other pgpool Connection Settings -
+
+other_pgpool_hostname0 = 'server1'
+ # Host name or IP address to connect to for other pgpool 0
+ # (change requires restart)
+other_pgpool_port0 = 9999
+ # Port number for other pgpool 0
+ # (change requires restart)
+other_wd_port0 = 9000
+ # Port number for other watchdog 0
+ # (change requires restart)
+other_pgpool_hostname1 = 'server2'
+other_pgpool_port1 = 9999
+other_wd_port1 = 9000
+</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Specify the hostname and port number of destination for sending heartbeat signal
+ on <literal>server1</literal>, <literal>server2</literal>, <literal>server3</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>server1</literal>
+ </para>
+<programlisting>
+heartbeat_destination0 = 'server2'
+ # Host name or IP address of destination 0
+ # for sending heartbeat signal.
+ # (change requires restart)
+heartbeat_destination_port0 = 9694
+ # Port number of destination 0 for sending
+ # heartbeat signal. Usually this is the
+ # same as wd_heartbeat_port.
+ # (change requires restart)
+heartbeat_device0 = ''
+ # Name of NIC device (such like 'eth0')
+ # used for sending/receiving heartbeat
+ # signal to/from destination 0.
+ # This works only when this is not empty
+ # and pgpool has root privilege.
+ # (change requires restart)
+
+heartbeat_destination1 = 'server3'
+heartbeat_destination_port1 = 9694
+heartbeat_device1 = ''
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>server2</literal>
+ </para>
+<programlisting>
+heartbeat_destination0 = 'server1'
+ # Host name or IP address of destination 0
+ # for sending heartbeat signal.
+ # (change requires restart)
+heartbeat_destination_port0 = 9694
+ # Port number of destination 0 for sending
+ # heartbeat signal. Usually this is the
+ # same as wd_heartbeat_port.
+ # (change requires restart)
+heartbeat_device0 = ''
+ # Name of NIC device (such like 'eth0')
+ # used for sending/receiving heartbeat
+ # signal to/from destination 0.
+ # This works only when this is not empty
+ # and pgpool has root privilege.
+ # (change requires restart)
+
+heartbeat_destination1 = 'server3'
+heartbeat_destination_port1 = 9694
+heartbeat_device1 = ''
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>server3</literal>
+ </para>
+<programlisting>
+heartbeat_destination0 = 'server1'
+ # Host name or IP address of destination 0
+ # for sending heartbeat signal.
+ # (change requires restart)
+heartbeat_destination_port0 = 9694
+ # Port number of destination 0 for sending
+ # heartbeat signal. Usually this is the
+ # same as wd_heartbeat_port.
+ # (change requires restart)
+heartbeat_device0 = ''
+ # Name of NIC device (such like 'eth0')
+ # used for sending/receiving heartbeat
+ # signal to/from destination 0.
+ # This works only when this is not empty
+ # and pgpool has root privilege.
+ # (change requires restart)
+
+heartbeat_destination1 = 'server2'
+heartbeat_destination_port1 = 9694
+heartbeat_device1 = ''
+</programlisting>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-sysconfig">
+ <title>/etc/sysconfig/pgpool Configuration</title>
+ <para>
+ If you want to ignore the <filename>pgpool_status</filename> file at startup of
+ <productname>Pgpool-II</productname>, add "- D" to the start option OPTS to
+ <filename>/etc/sysconfig/pgpool</filename>.
+ </para>
+<programlisting>
+[all servers]# vi /etc/sysconfig/pgpool
+...
+OPTS=" -D -n"
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-log">
+ <title>Logging</title>
+ <para>
+ In the example, we output <productname>Pgpool-II</productname>'s log to <literal>syslog</literal>.
+ </para>
+<programlisting>
+log_destination = 'syslog'
+ # Where to log
+ # Valid values are combinations of stderr,
+ # and syslog. Default to stderr.
+
+syslog_facility = 'LOCAL1'
+ # Syslog local facility. Default to LOCAL0
+</programlisting>
+ <para>
+ Create <productname>Pgpool-II</productname> log file.
+ </para>
+<programlisting>
+[all servers]# mkdir /var/log/pgpool-II
+[all servers]# touch /var/log/pgpool-II/pgpool.log
+</programlisting>
+ <para>
+ Edit config file of syslog <filename>/etc/rsyslog.conf</filename>.
+ </para>
+<programlisting>
+[all servers]# vi /etc/rsyslog.conf
+...
+*.info;mail.none;authpriv.none;cron.none;LOCAL1.none /var/log/messages
+LOCAL1.* /var/log/pgpool-II/pgpool.log
+</programlisting>
+ <para>
+ Setting logrotate same as <filename>/var/log/messages</filename>.
+ </para>
+<programlisting>
+[all servers]# vi /etc/logrotate.d/syslog
+...
+/var/log/messages
+/var/log/pgpool-II/pgpool.log
+/var/log/secure
+</programlisting>
+
+ <para>
+ Restart rsyslog service.
+ </para>
+<programlisting>
+[all servers]# systemctl restart rsyslog
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-pcp">
+ <title>PCP Command Configuration</title>
+ <para>
+ Since user authentication is required to use the <literal>PCP</literal> command,
+ specify user name and md5 encrypted password in <filename>pcp.conf</filename>.
+ Here we create the encrypted password for <literal>pgpool</literal> user, and add
+ "<literal>username:encrypted password</literal>" in <filename>/etc/pgpool-II/pcp.conf</filename>.
+ </para>
+<programlisting>
+[all servers]# echo 'pgpool:'`pg_md5 PCP passowrd` >> /etc/pgpool-II/pcp.conf
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-pgpool-config-pcppass">
+ <title>.pcppass</title>
+ <para>
+ Since follow_master_command script has to execute PCP command without entering the
+ password, we create <filename>.pcppass</filename> in the home directory of
+ <productname>Pgpool-II</productname> startup user (root user).
+ </para>
+<programlisting>
+[all servers]# echo 'localhost:9898:pgpool:pgpool' > ~/.pcppass
+[all servers]# chmod 600 ~/.pcppass
+</programlisting>
+ <para>
+ The settings of <productname>Pgpool-II</productname> is completed.
+ </para>
+ </sect3>
+
+</sect2>
+
+ <sect2 id="example-cluster-start-stop">
+ <title>Starting/Stopping Pgpool-II</title>
+ <para>
+ Next we start <productname>Pgpool-II</productname>. Before starting
+ <productname>Pgpool-II</productname>, please start
+ <productname>PostgreSQL</productname> servers first.
+ Also, when stopping <productname>PostgreSQL</productname>, it is necessary to
+ stop Pgpool-II first.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Starting <productname>Pgpool-II</productname>
+ </para>
+ <para>
+ In section <link linkend="EXAMPLE-CLUSTER-PRE-SETUP">Before Starting</link>,
+ we already set the auto-start of <productname>Pgpool-II</productname>. To start
+ <productname>Pgpool-II</productname>, restart the whole system or execute the following command.
+ </para>
+<programlisting>
+# systemctl start pgpool.service
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ Stopping <productname>Pgpool-II</productname>
+ </para>
+<programlisting>
+# systemctl stop pgpool.service
+</programlisting>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="example-cluster-try">
+ <title>How to use</title>
+ <para>
+ Let's start to use <productname>Pgpool-II</productname>.
+ First, let's start <productname>Pgpool-II</productname> on <literal>server1</literal>,
+ <literal>server2</literal>, <literal>server3</literal> by using the following command.
+ </para>
+<programlisting>
+# systemctl start pgpool.service
+</programlisting>
+
+ <sect3 id="example-cluster-try-standby">
+ <title>Set up PostgreSQL standby server</title>
+ <para>
+ First, we should set up <productname>PostgreSQL</productname> standby server by
+ using <productname>Pgpool-II</productname> online recovery functionality. Ensure
+ that <filename>recovery_1st_stage</filename> and <filename>pgpool_remote_start</filename>
+ scripts used by <command>pcp_recovery_node</command> command are in database
+ cluster directory of <productname>PostgreSQL</productname> primary server (<literal>server1</literal>).
+ </para>
+<programlisting>
+# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 1
+Password:
+pcp_recovery_node -- Command Successful
+
+# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 2
+Password:
+pcp_recovery_node -- Command Successful
+</programlisting>
+ <para>
+ After executing <command>pcp_recovery_node</command> command,
+ vertify that <literal>server2</literal> and <literal>server3</literal>
+ are started as <productname>PostgreSQL</productname> standby server.
+ </para>
+<programlisting>
+# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
+Password for user pgpool
+node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
+---------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
+0 | server1 | 5432 | up | 0.333333 | primary | 0 | false | 0 | | | 2019-08-06 11:13:17
+1 | server2 | 5432 | up | 0.333333 | standby | 0 | true | 0 | streaming | async | 2019-08-06 11:13:25
+2 | server3 | 5432 | up | 0.333333 | standby | 0 | false | 0 | streaming | async | 2019-08-06 11:14:20
+(3 rows)
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-try-watchdog">
+ <title>Switching active/standby watchdog</title>
+ <para>
+ Confirm the watchdog status by using <command>pcp_watchdog_info</command>. The <command>Pgpool-II</command> server which is started first run as <literal>MASTER</literal>.
+ </para>
+<programlisting>
+# pcp_watchdog_info -h 192.168.137.150 -p 9898 -U pgpool
+Password:
+3 YES server1:9999 Linux server1 server1
+
+server1:9999 Linux server1 server1 9999 9000 4 MASTER #The Pgpool-II server started first becames "MASTER".
+server2:9999 Linux server2 server2 9999 9000 7 STANDBY #run as standby
+server3:9999 Linux server3 server3 9999 9000 7 STANDBY #run as standby
+</programlisting>
+ <para>
+ Stop active server <literal>server1</literal>, then <literal>server2</literal> or
+ <literal>server3</literal> will be promoted to active server. To stop
+ <literal>server1</literal>, we can stop <productname>Pgpool-II</productname>
+ service or shutdown the whole system. Here, we stop <productname>Pgpool-II</productname> service.
+ </para>
+<programlisting>
+[server1]# systemctl stop pgpool.service
+
+# pcp_watchdog_info -p 9898 -h 192.168.137.150 -U pgpool
+Password:
+3 YES server2:9999 Linux server2 server2
+
+server2:9999 Linux server2 server2 9999 9000 4 MASTER #server2 is promoted to MASTER
+server1:9999 Linux server1 server1 9999 9000 10 SHUTDOWN #server1 is stopped
+server3:9999 Linux server3 server3 9999 9000 7 STANDBY #server3 runs as STANDBY
+</programlisting>
+ <para>
+ Start <productname>Pgpool-II</productname> (<literal>server1</literal>) which we have stopped again,
+ and vertify that <literal>server1</literal> runs as a standby.
+ </para>
+<programlisting>
+[server1]# systemctl start pgpool.service
+
+[server1]# pcp_watchdog_info -p 9898 -h 192.168.137.150 -U pgpool
+Password:
+3 YES server2:9999 Linux server2 server2
+
+server2:9999 Linux server2 server2 9999 9000 4 MASTER
+server1:9999 Linux server1 server1 9999 9000 7 STANDBY
+server3:9999 Linux server3 server3 9999 9000 7 STANDBY
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-try-failover">
+ <title>Failover</title>
+ <para>
+ First, use <command>psql</command> to connect to <productname>PostgreSQL</productname> via virtual IP,
+ and verify the backend informations.
+ </para>
+<programlisting>
+# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
+Password for user pgpool:
+node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
+---------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
+0 | server1 | 5432 | up | 0.333333 | primary | 0 | false | 0 | | | 2019-08-06 11:13:17
+1 | server2 | 5432 | up | 0.333333 | standby | 0 | true | 0 | streaming | async | 2019-08-06 11:13:25
+2 | server3 | 5432 | up | 0.333333 | standby | 0 | false | 0 | streaming | async | 2019-08-06 11:14:20
+(3 rows)
+</programlisting>
+ <para>
+ Next, stop primary <productname>PostgreSQL</productname> server
+ <literal>server1</literal>, and verify automatic failover.
+ </para>
+<programlisting>
+[server1]$ pg_ctl -D /var/lib/pgsql/11/data -m immediate stop
+</programlisting>
+ <para>
+ After stopping <productname>PostgreSQL</productname> on <literal>server1</literal>,
+ failover occurs and <productname>PostgreSQL</productname> on
+ <literal>server2</literal> becomes new primary DB.
+ </para>
+<programlisting>
+# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
+Password for user pgpool:
+node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
+---------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
+0 | server1 | 5432 | down | 0.333333 | standby | 0 | false | 0 | | | 2019-08-06 11:36:03
+1 | server2 | 5432 | up | 0.333333 | primary | 0 | true | 0 | | | 2019-08-06 11:36:03
+2 | server3 | 5432 | up | 0.333333 | standby | 0 | false | 0 | streaming | async | 2019-08-06 11:36:15
+(3 rows)
+</programlisting>
+ <para>
+ <literal>server3</literal> is running as standby of new primary <literal>server2</literal>.
+ </para>
+
+<programlisting>
+[server3]# psql -h server3 -p 5432 -U pgpool postgres -c "select pg_is_in_recovery()"
+pg_is_in_recovery
+-------------------
+t
+
+[server2]# psql -h server2 -p 5432 -U pgpool postgres -c "select pg_is_in_recovery()"
+pg_is_in_recovery
+-------------------
+f
+
+[server2]# psql -h server2 -p 5432 -U pgpool postgres -c "select * from pg_stat_replication" -x
+-[ RECORD 1 ]----+------------------------------
+pid | 11059
+usesysid | 16392
+usename | repl
+application_name | server3
+client_addr | 192.168.137.103
+client_hostname |
+client_port | 48694
+backend_start | 2019-08-06 11:36:07.479161+09
+backend_xmin |
+state | streaming
+sent_lsn | 0/75000148
+write_lsn | 0/75000148
+flush_lsn | 0/75000148
+replay_lsn | 0/75000148
+write_lag |
+flush_lag |
+replay_lag |
+sync_priority | 0
+sync_state | async
+reply_time | 2019-08-06 11:42:59.823961+09
+</programlisting>
+ </sect3>
+
+ <sect3 id="example-cluster-try-online-recovery">
+ <title>Online Recovery</title>
+ <para>
+ Here, we use <productname>Pgpool-II</productname> online recovery functionality to
+ restore <literal>server1</literal> (old primary server) as a standby. Before
+ restoring the old primary server, please ensure that
+ <filename>recovery_1st_stage</filename> and <filename>pgpool_remote_start</filename> scripts
+ exist in database cluster directory of current primary server <literal>server2</literal>.
+ </para>
+<programlisting>
+# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 0
+Password:
+pcp_recovery_node -- Command Successful
+</programlisting>
+ <para>
+ Then verify that <literal>server1</literal> is started as a standby.
+ </para>
+<programlisting>
+# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
+Password for user pgpool:
+node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
+---------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
+0 | server1 | 5432 | up | 0.333333 | standby | 0 | false | 0 | streaming | async | 2019-08-06 11:48:05
+1 | server2 | 5432 | up | 0.333333 | primary | 0 | false | 0 | | | 2019-08-06 11:36:03
+2 | server3 | 5432 | up | 0.333333 | standby | 0 | true | 0 | streaming | async | 2019-08-06 11:36:15
+(3 rows)
+</programlisting>
+ </sect3>
+ </sect2>
+</sect1>
diff --git a/doc/src/sgml/example-watchdog.sgml b/doc/src/sgml/example-watchdog.sgml
new file mode 100644
index 000000000..f553552b2
--- /dev/null
+++ b/doc/src/sgml/example-watchdog.sgml
@@ -0,0 +1,354 @@
+ <sect1 id="example-watchdog">
+ <title>Watchdog Configuration Example</title>
+
+ <para>
+ This tutorial explains the simple way to try "Watchdog".
+ What you need is 2 Linux boxes on which <productname>
+ Pgpool-II</productname> is installed and a <productname>PostgreSQL</productname>
+ on the same machine or in the other one. It is enough
+ that 1 node for backend exists.
+ You can use watchdog with <productname>
+ Pgpool-II</productname> in any mode: replication mode,
+ master/slave mode and raw mode.
+ </para>
+ <para>
+ This example uses use "osspc16" as an Active node and
+ "osspc20" as a Standby node. "Someserver" means one of them.
+ </para>
+
+ <sect2 id="example-watchdog-configuration">
+ <title>Common configurations</title>
+ <para>
+ Set the following parameters in both of active and standby nodes.
+ </para>
+
+ <sect3 id="example-watchdog-config-enable">
+ <title>Enabling watchdog</title>
+ <para>
+ First of all, set <xref linkend="guc-use-watchdog"> to on.
+ <programlisting>
+use_watchdog = on
+# Activates watchdog
+ </programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-config-upstream">
+ <title>Configure Up stream servers</title>
+ <para>
+ Specify the up stream servers (e.g. application servers).
+ Leaving it blank is also fine.
+ <programlisting>
+trusted_servers = ''
+ # trusted server list which are used
+ # to confirm network connection
+ # (hostA,hostB,hostC,...)
+ </programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-config-wd-comm">
+ <title>Watchdog Communication</title>
+ <para>
+ Specify the TCP port number for watchdog communication.
+ <programlisting>
+wd_port = 9000
+ # port number for watchdog service
+ </programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-config-wd-vip">
+ <title>Virtual IP</title>
+ <para>
+ Specify the IP address to be used as a virtual IP address
+ in the <xref linkend="guc-delegate-IP">.
+ <programlisting>
+delegate_IP = '133.137.177.143'
+# delegate IP address
+ </programlisting>
+ </para>
+ <note>
+ <para>
+ Make sure the IP address configured as a Virtual IP should be
+ free and is not used by any other machine.
+ </para>
+ </note>
+ </sect3>
+ </sect2>
+
+ <sect2 id="example-watchdog-configuration-each-server">
+ <title>Individual Server Configurations</title>
+ <para>
+ Next, set the following parameters for each <productname>
+ Pgpool-II</productname>.
+ Specify <xref linkend="guc-other-pgpool-hostname">,
+ <xref linkend="guc-other-pgpool-port"> and
+ <xref linkend="guc-other-wd-port"> with the values of
+ other <productname>Pgpool-II</productname> server values.
+ </para>
+
+ <sect3 id="example-watchdog-configuration-active-server">
+ <title>Active (osspc16) Server configurations</title>
+ <para>
+ <programlisting>
+other_pgpool_hostname0 = 'osspc20'
+ # Host name or IP address to connect to for other pgpool 0
+other_pgpool_port0 = 9999
+ # Port number for other pgpool 0
+other_wd_port0 = 9000
+ # Port number for other watchdog 0
+ </programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-configuration-standby-server">
+ <title>Standby (osspc20) Server configurations</title>
+ <para>
+ <programlisting>
+other_pgpool_hostname0 = 'osspc16'
+ # Host name or IP address to connect to for other pgpool 0
+other_pgpool_port0 = 9999
+ # Port number for other pgpool 0
+other_wd_port0 = 9000
+ # Port number for other watchdog 0
+ </programlisting>
+ </para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="example-watchdog-start-server">
+ <title>Starting <productname>Pgpool-II</productname></title>
+ <para>
+ Start <productname>Pgpool-II</productname> on each servers from
+ <literal>root</literal> user with <literal>"-n"</literal> switch
+ and redirect log messages into pgpool.log file.
+ </para>
+
+ <sect3 id="example-watchdog-start-active-server">
+ <title>Starting pgpool in Active server (osspc16)</title>
+ <para>
+ First start the <productname>Pgpool-II</productname> on Active server.
+ <programlisting>
+[user@osspc16]$ su -
+[root@osspc16]# {installed_dir}/bin/pgpool -n -f {installed_dir}/etc/pgpool.conf > pgpool.log 2>&1
+ </programlisting>
+ Log messages will show that <productname>Pgpool-II</productname>
+ has the virtual IP address and starts watchdog process.
+ <programlisting>
+LOG: I am announcing my self as master/coordinator watchdog node
+LOG: I am the cluster leader node
+DETAIL: our declare coordinator message is accepted by all nodes
+LOG: I am the cluster leader node. Starting escalation process
+LOG: escalation process started with PID:59449
+<emphasis>LOG: watchdog process is initialized
+LOG: watchdog: escalation started
+LOG: I am the master watchdog node</emphasis>
+ DETAIL: using the local backend node status
+ </programlisting>
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-start-standby-server">
+ <title>Starting pgpool in Standby server (osspc20)</title>
+ <para>
+ Now start the <productname>Pgpool-II</productname> on Standby server.
+ <programlisting>
+[user@osspc20]$ su -
+[root@osspc20]# {installed_dir}/bin/pgpool -n -f {installed_dir}/etc/pgpool.conf > pgpool.log 2>&1
+ </programlisting>
+ Log messages will show that <productname>Pgpool-II</productname>
+ has joind the watchdog cluster as standby watchdog.
+ <programlisting>
+LOG: watchdog cluster configured with 1 remote nodes
+LOG: watchdog remote node:0 on Linux_osspc16_9000:9000
+LOG: interface monitoring is disabled in watchdog
+LOG: IPC socket path: "/tmp/.s.PGPOOLWD_CMD.9000"
+LOG: watchdog node state changed from [DEAD] to [LOADING]
+LOG: new outbound connection to Linux_osspc16_9000:9000
+LOG: watchdog node state changed from [LOADING] to [INITIALIZING]
+LOG: watchdog node state changed from [INITIALIZING] to [STANDBY]
+<emphasis>
+LOG: successfully joined the watchdog cluster as standby node
+DETAIL: our join coordinator request is accepted by cluster leader node "Linux_osspc16_9000"
+LOG: watchdog process is initialized
+</emphasis>
+ </programlisting>
+ </para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="example-watchdog-try">
+ <title>Try it out</title>
+ <para>
+ Confirm to ping to the virtual IP address.
+ <programlisting>
+[user@someserver]$ ping 133.137.177.142
+PING 133.137.177.143 (133.137.177.143) 56(84) bytes of data.
+64 bytes from 133.137.177.143: icmp_seq=1 ttl=64 time=0.328 ms
+64 bytes from 133.137.177.143: icmp_seq=2 ttl=64 time=0.264 ms
+64 bytes from 133.137.177.143: icmp_seq=3 ttl=64 time=0.412 ms
+ </programlisting>
+ Confirm if the Active server which started at first has the virtual IP address.
+ <programlisting>
+[root@osspc16]# ifconfig
+eth0 ...
+
+eth0:0 inet addr:133.137.177.143 ...
+
+lo ...
+ </programlisting>
+ Confirm if the Standby server which started not at first doesn't have the virtual IP address.
+ <programlisting>
+[root@osspc20]# ifconfig
+eth0 ...
+
+lo ...
+ </programlisting>
+
+ Try to connect <productname>PostgreSQL</productname> by "psql -h delegate_IP -p port".
+ <programlisting>
+[user@someserver]$ psql -h 133.137.177.142 -p 9999 -l
+ </programlisting>
+ </para>
+ </sect2>
+
+ <sect2 id="example-watchdog-vip-switch">
+ <title>Switching virtual IP</title>
+ <para>
+ Confirm how the Standby server works when the Active server can't provide its service.
+ Stop <productname>Pgpool-II</productname> on the Active server.
+ <programlisting>
+[root@osspc16]# {installed_dir}/bin/pgpool stop
+ </programlisting>
+
+ Then, the Standby server starts to use the virtual IP address. Log shows:
+
+ <programlisting>
+<emphasis>
+LOG: remote node "Linux_osspc16_9000" is shutting down
+LOG: watchdog cluster has lost the coordinator node
+</emphasis>
+LOG: watchdog node state changed from [STANDBY] to [JOINING]
+LOG: watchdog node state changed from [JOINING] to [INITIALIZING]
+LOG: I am the only alive node in the watchdog cluster
+HINT: skipping stand for coordinator state
+LOG: watchdog node state changed from [INITIALIZING] to [MASTER]
+LOG: I am announcing my self as master/coordinator watchdog node
+LOG: I am the cluster leader node
+DETAIL: our declare coordinator message is accepted by all nodes
+<emphasis>
+LOG: I am the cluster leader node. Starting escalation process
+LOG: watchdog: escalation started
+</emphasis>
+LOG: watchdog escalation process with pid: 59551 exit with SUCCESS.
+ </programlisting>
+
+ Confirm to ping to the virtual IP address.
+ <programlisting>
+[user@someserver]$ ping 133.137.177.142
+PING 133.137.177.143 (133.137.177.143) 56(84) bytes of data.
+64 bytes from 133.137.177.143: icmp_seq=1 ttl=64 time=0.328 ms
+64 bytes from 133.137.177.143: icmp_seq=2 ttl=64 time=0.264 ms
+64 bytes from 133.137.177.143: icmp_seq=3 ttl=64 time=0.412 ms
+ </programlisting>
+
+ Confirm that the Active server doesn't use the virtual IP address any more.
+ <programlisting>
+[root@osspc16]# ifconfig
+eth0 ...
+
+lo ...
+ </programlisting>
+
+ Confirm that the Standby server uses the virtual IP address.
+ <programlisting>
+[root@osspc20]# ifconfig
+eth0 ...
+
+eth0:0 inet addr:133.137.177.143 ...
+
+lo ...
+ </programlisting>
+
+ Try to connect <productname>PostgreSQL</productname> by "psql -h delegate_IP -p port".
+ <programlisting>
+[user@someserver]$ psql -h 133.137.177.142 -p 9999 -l
+ </programlisting>
+
+ </para>
+ </sect2>
+
+ <sect2 id="example-watchdog-more">
+ <title>More</title>
+
+ <sect3 id="example-watchdog-more-lifecheck">
+ <title>Lifecheck</title>
+ <para>
+ There are the parameters about watchdog's monitoring.
+ Specify the interval to check <xref linkend="guc-wd-interval"> and
+ the type of lifecheck <xref linkend="guc-wd-lifecheck-method">.
+ The <literal>hearbeat</literal> method specify the time to detect
+ a fault <xref linkend="guc-wd-heartbeat-deadtime">, the port number to
+ receive <xref linkend="guc-wd-heartbeat-port">, the interval to send
+ <xref linkend="guc-wd-heartbeat-keepalive">, the IP address or hostname
+ of destination <xref linkend="guc-heartbeat-destination"> and finally
+ the destination port number <xref linkend="guc-heartbeat-destination-port">.
+ <programlisting>
+wd_lifecheck_method = 'heartbeat'
+ # Method of watchdog lifecheck ('heartbeat' or 'query' or 'external')
+ # (change requires restart)
+wd_interval = 10
+ # lifecheck interval (sec) > 0
+wd_heartbeat_port = 9694
+ # Port number for receiving heartbeat signal
+ # (change requires restart)
+wd_heartbeat_keepalive = 2
+ # Interval time of sending heartbeat signal (sec)
+ # (change requires restart)
+wd_heartbeat_deadtime = 30
+ # Deadtime interval for heartbeat signal (sec)
+ # (change requires restart)
+heartbeat_destination0 = 'host0_ip1'
+ # Host name or IP address of destination 0
+ # for sending heartbeat signal.
+ # (change requires restart)
+heartbeat_destination_port0 = 9694
+ # Port number of destination 0 for sending
+ # heartbeat signal. Usually this is the
+ # same as wd_heartbeat_port.
+ # (change requires restart)
+ </programlisting>
+
+ </para>
+ </sect3>
+
+ <sect3 id="example-watchdog-more-vip-switching">
+ <title>Switching virtual IP address</title>
+ <para>
+ There are the parameters for switching the virtual IP address.
+ Specify switching commands <xref linkend="guc-if-up-cmd">,
+ <xref linkend="guc-if-down-cmd">, the path to them
+ <xref linkend="guc-if-cmd-path">, the command executed after
+ switching to send ARP request <xref linkend="guc-arping-cmd">
+ and the path to it <xref linkend="guc-arping-path">.
+ <programlisting>
+if_cmd_path = '/sbin'
+ # path to the directory where if_up/down_cmd exists
+if_up_cmd = 'ip addr add $_IP_$/24 dev eth0 label eth0:0'
+ # startup delegate IP command
+if_down_cmd = 'ip addr del $_IP_$/24 dev eth0'
+ # shutdown delegate IP command
+
+arping_path = '/usr/sbin' # arping command path
+
+arping_cmd = 'arping -U $_IP_$ -w 1'
+ </programlisting>
+ You can also bring up and bring down the virtual IP using arbitrary scripts
+ specified <xref linkend="guc-wd-escalation-command"> and
+ <xref linkend="guc-wd-de-escalation-command"> parameters.
+ </para>
+ </sect3>
+
+ </sect2>
+ </sect1>
diff --git a/doc/src/sgml/examples.sgml b/doc/src/sgml/examples.sgml
index b83b22ac6..49c220f75 100644
--- a/doc/src/sgml/examples.sgml
+++ b/doc/src/sgml/examples.sgml
@@ -1,2446 +1,20 @@
<!-- doc/src/sgml/examples.sgml -->
<part id="examples">
- <title>Examples</title>
-
- <partintro>
- <para>
- Various examples
- </para>
-
- </partintro>
-
- <chapter id="example-configs">
- <title>Configuration Examples</title>
-
- <sect1 id="example-basic">
- <title>Basic Configuration Example</title>
-
- <sect2 id="example-configs-begin">
- <title>Let's Begin!</title>
- <para>
- First, we must learn how to install and configure <productname>Pgpool-II</productname> and database nodes before using replication.
- </para>
-
- <sect3 id="example-configs-begin-installing">
- <title>Installing <productname>Pgpool-II</productname></title>
- <para>
- Installing <productname>Pgpool-II</productname> is very easy.
- In the directory which you have extracted the source tar ball,
- execute the following commands.
- <programlisting>
-$ ./configure
-$ make
-$ make install
- </programlisting>
- <command>configure</command> script collects your system information
- and use it for the compilation procedure. You can pass command
- line arguments to <command>configure</command> script to change the default behavior,
- such as the installation directory. <productname>Pgpool-II</productname>
- will be installed to <literal>/usr/local</literal> directory by default.
- </para>
- <para>
- <command>make</command> command compiles the source code, and
- <command>make install</command> will install the executables.
- You must have write permission on the installation directory.
- In this tutorial, we will install <productname>Pgpool-II
- </productname> in the default <literal>/usr/local</literal> directory.
- </para>
- <note>
- <para>
- <productname>Pgpool-II</productname> requires <literal>libpq</literal>
- library in <productname>PostgreSQL</productname> 7.4 or later (version 3 protocol).
- </para>
- </note>
- <para>
- If the <command>configure</command> script displays the following error message, the
- <literal>libpq</literal> library may not be installed, or it is not of version 3
- <programlisting>
-configure: error: libpq is not installed or libpq is old
- </programlisting>
- If the library is version 3, but the above message is still displayed, your
- <literal>libpq</literal> library is probably not recognized by the <command>
- configure</command> script.
- The <command>configure</command> script searches for <literal>libpq</literal>
- library under <literal>/usr/local/pgsql</literal>. If you have installed the
- <productname>PostgreSQL</productname> in a directory other than <literal>/usr/local/pgsql</literal>, use
- <literal>--with-pgsql</literal>, or <literal>--with-pgsql-includedir</literal>
- and <literal>--with-pgsql-libdir</literal> command line options when you
- execute <command>configure</command>.
- </para>
- </sect3>
-
- <sect3 id="example-configs-begin-config-files">
- <title>Configuration Files</title>
- <para>
- <productname>Pgpool-II</productname> configuration parameters are saved in the
- <literal>pgpool.conf</literal> file. The file is in <literal>"parameter = value"
- </literal> per line format. When you install <productname>Pgpool-II</productname>,
- <literal>pgpool.conf.sample</literal> is automatically created.
- We recommend copying and renaming it to <literal>pgpool.conf</literal>, and edit
- it as you like.
- <programlisting>
-$ cp /usr/local/etc/pgpool.conf.sample /usr/local/etc/pgpool.conf
- </programlisting>
- <productname>Pgpool-II</productname> only accepts connections from the localhost
- using port 9999 by the default. If you wish to receive conenctions from other hosts,
- set <xref linkend="guc-listen-addresses"> to <literal>'*'</literal>.
- <programlisting>
-listen_addresses = 'localhost'
-port = 9999
- </programlisting>
- We will use the default parameters in this tutorial.
- </para>
- </sect3>
-
- <sect3 id="example-configs-begin-config-pcp">
- <title>Configuring <acronym>PCP</acronym> Commands</title>
- <para>
- <productname>Pgpool-II</productname> has an interface for administrative
- purpose to retrieve information on database nodes, shutdown
- <productname>Pgpool-II</productname>, etc. via network. To use
- <acronym>PCP</acronym> commands, user authentication is required.
- This authentication is different from <productname>PostgreSQL</productname>'s user authentication.
- A user name and password need to be defined in the <literal>pcp.conf</literal>
- file. In the file, a user name and password are listed as a pair on each line,
- and they are separated by a colon (:). Passwords are encrypted in
- <literal>md5</literal> hash format.
-
- <programlisting>
-postgres:e8a48653851e28c69d0506508fb27fc5
- </programlisting>
-
- When you install <productname>Pgpool-II</productname>, <literal>pcp.conf.sample
- </literal> is automatically created. We recommend copying and renaming it
- to <literal>pcp.conf</literal>, and edit it.
- <programlisting>
-$ cp /usr/local/etc/pcp.conf.sample /usr/local/etc/pcp.conf
- </programlisting>
- To encrypt your password into md5 hash format, use the <command>pg_md5</command>
- command, which is installed as one of <productname>Pgpool-II</productname>'s
- executables. <command>pg_md5</command> takes text as a command line argument,
- and displays its md5-hashed text.
- For example, give <literal>"postgres"</literal> as the command line argument,
- and <command>pg_md5</command> displays md5-hashed text on its standard output.
- <programlisting>
-$ /usr/local/bin/pg_md5 postgres
-e8a48653851e28c69d0506508fb27fc5
- </programlisting>
- PCP commands are executed via network, so the port number must be configured
- with <xref linkend="guc-pcp-port"> parameter in <literal>pgpool.conf</literal> file.
- We will use the default 9898 for <xref linkend="guc-pcp-port"> in this tutorial.
- <programlisting>
-pcp_port = 9898
- </programlisting>
- </para>
- </sect3>
-
-
- <sect3 id="example-configs-prep-db-nodes">
- <title>Preparing Database Nodes</title>
- <para>
- Now, we need to set up backend <productname>PostgreSQL</productname> servers for <productname>Pgpool-II
- </productname>. These servers can be placed within the same host as
- <productname>Pgpool-II</productname>, or on separate machines. If you decide
- to place the servers on the same host, different port numbers must be assigned
- for each server. If the servers are placed on separate machines,
- they must be configured properly so that they can accept network
- connections from <productname>Pgpool-II</productname>.
-
- <programlisting>
-backend_hostname0 = 'localhost'
-backend_port0 = 5432
-backend_weight0 = 1
-backend_hostname1 = 'localhost'
-backend_port1 = 5433
-backend_weight1 = 1
-backend_hostname2 = 'localhost'
-backend_port2 = 5434
-backend_weight2 = 1
- </programlisting>
-
- For <xref linkend="guc-backend-hostname">, <xref linkend="guc-backend-port">,
- <xref linkend="guc-backend-weight">, set the node's hostname, port number,
- and ratio for load balancing. At the end of each parameter string,
- node ID must be specified by adding positive integers starting with 0 (i.e. 0, 1, 2..).
- </para>
- <note>
- <para>
- <xref linkend="guc-backend-weight"> parameters for all nodes are
- set to 1, meaning that SELECT queries are equally distributed among
- three servers.
- </para>
- </note>
- </sect3>
-
- <sect3 id="example-configs-start-stop-pgpool">
- <title>Starting/Stopping <productname>Pgpool-II</productname></title>
- <para>
- To fire up <productname>Pgpool-II</productname>, execute the following
- command on a terminal.
-
- <programlisting>
-$ pgpool
- </programlisting>
-
- The above command, however, prints no log messages because <productname>
- Pgpool-II</productname> detaches the terminal. If you want to show
- <productname>Pgpool-II</productname> log messages, you pass <literal>-n</literal>
- option to <command>pgpool</command> command so <productname>Pgpool-II</productname>
- is executed as non-daemon process, and the terminal will not be detached.
- <programlisting>
-$ pgpool -n &
- </programlisting>
-
- The log messages are printed on the terminal, so it is recommended to use the following options.
- <programlisting>
-$ pgpool -n -d > /tmp/pgpool.log 2>&1 &
- </programlisting>
-
- The <literal>-d</literal> option enables debug messages to be generated.
- The above command keeps appending log messages to <literal>/tmp/pgpool.log
- </literal>. If you need to rotate log files, pass the logs to a external
- command which has log rotation function.
- For example, you can use <ulink url="https://httpd.apache.org/docs/2.4/programs/rotatelogs.html">
- <command>rotatelogs</command></ulink> from Apache2:
- <programlisting>
-$ pgpool -n 2>&1 | /usr/local/apache2/bin/rotatelogs \
--l -f /var/log/pgpool/pgpool.log.%A 86400 &
- </programlisting>
-
- This will generate a log file named <literal>"pgpool.log.Thursday"</literal>
- then rotate it 00:00 at midnight. Rotatelogs adds logs to a file if it already
- exists. To delete old log files before rotation, you could use cron:
- <programlisting>
-55 23 * * * /usr/bin/find /var/log/pgpool -type f -mtime +5 -exec /bin/rm -f '{}' \;
- </programlisting>
-
- Please note that rotatelogs may exist as <literal>/usr/sbin/rotatelogs2</literal>
- in some distributions. <literal>-f</literal> option generates a log file as soon as
- <command>rotatelogs</command> starts and is available in apache2 2.2.9 or greater.
- Also <ulink url="http://www.cronolog.org/">cronolog</ulink> can be used.
- <programlisting>
-$ pgpool -n 2>&1 | /usr/sbin/cronolog \
---hardlink=/var/log/pgsql/pgpool.log \
-'/var/log/pgsql/%Y-%m-%d-pgpool.log' &
- </programlisting>
-
- To stop <productname>Pgpool-II</productname> execute the following command.
- <programlisting>
-$ pgpool stop
- </programlisting>
-
- If any client is still connected, <productname>Pgpool-II</productname>
- waits for it to disconnect, and then terminates itself. Run the following
- command instead if you want to shutdown <productname>Pgpool-II</productname>
- forcibly.
- <programlisting>
-$ pgpool -m fast stop
- </programlisting>
-
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="example-configs-replication">
- <title>Your First Replication</title>
- <para>
- Replication (see <xref linkend="runtime-config-replication-mode">) enables
- the same data to be copied to multiple database nodes.
- In this section, we'll use three database nodes, which we have already set
- up in <xref linkend="example-configs-begin">, and takes you step by step to
- create a database replication system.
- Sample data to be replicated will be generated by the
- <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
- <command>pgbench</command></ulink> benchmark program.
- </para>
-
- <sect3 id="example-configs-config-replication">
- <title>Configuring Replication</title>
- <para>
- To enable the database replication function, set
- <xref linkend="guc-replication-mode"> to on in <literal>pgpool.conf</literal> file.
- <programlisting>
-replication_mode = true
- </programlisting>
- When <xref linkend="guc-replication-mode"> is on, <productname>Pgpool-II</productname>
- will send a copy of a received query to all the database nodes.
- In addition, when <xref linkend="guc-load-balance-mode"> is set to true,
- <productname>Pgpool-II</productname> will distribute <acronym>SELECT</acronym> queries
- among the database nodes.
- <programlisting>
-load_balance_mode = true
- </programlisting>
- In this section, we will enable both <xref linkend="guc-replication-mode">
- and <xref linkend="guc-load-balance-mode">.
- </para>
- </sect3>
-
- <sect3 id="example-configs-checking-replication">
- <title>Checking Replication</title>
- <para>
- To reflect the above changes in <literal>pgpool.conf</literal>,
- <productname>Pgpool-II</productname> must be restarted.
- Please refer to "Starting/Stopping <productname>Pgpool-II</productname>"
- <xref linkend="example-configs-start-stop-pgpool">.
- After configuring <literal>pgpool.conf</literal> and restarting the
- <productname>Pgpool-II</productname>, let's try the actual replication
- and see if everything is working.
- First, we need to create a database to be replicated. We will name it
- <literal>"bench_replication"</literal>. This database needs to be created
- on all the nodes. Use the
- <ulink url="https://www.postgresql.org/docs/current/static/app-createdb.html">
- <command>createdb</command></ulink> commands through
- <productname>Pgpool-II</productname>, and the database will be created
- on all the nodes.
- <programlisting>
-$ createdb -p 9999 bench_replication
- </programlisting>
- Then, we'll execute <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
- <command>pgbench</command></ulink> with <literal>-i</literal> option.
- <literal>-i</literal> option initializes the database with pre-defined tables and data.
- <programlisting>
-$ pgbench -i -p 9999 bench_replication
- </programlisting>
- The following table is the summary of tables and data, which will be created by
- <ulink url="https://www.postgresql.org/docs/current/static/pgbench.html">
- <command>pgbench -i</command></ulink>. If, on all the nodes, the listed tables and
- data are created, replication is working correctly.
- </para>
-
- <table id="example-configs-checking-replication-table">
- <title>data summary</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Table Name</entry>
- <entry>Number of Rows</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>pgbench_branches</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>pgbench_tellers</entry>
- <entry>10</entry>
- </row>
-
- <row>
- <entry>pgbench_accounts</entry>
- <entry>100000</entry>
- </row>
-
- <row>
- <entry>pgbench_history</entry>
- <entry>0</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <para>
- Let's use a simple shell script to check the above on all the nodes.
- The following script will display the number of rows in pgbench_branches,
- pgbench_tellers, pgbench_accounts, and pgbench_history tables on all the nodes (5432, 5433, 5434).
- <programlisting>
-$ for port in 5432 5433 5434; do
-> echo $port
-> for table_name in pgbench_branches pgbench_tellers pgbench_accounts pgbench_history; do
-> echo $table_name
-> psql -c "SELECT count(*) FROM $table_name" -p $port bench_replication
-> done
-> done
- </programlisting>
-
- </para>
- </sect3>
- </sect2>
-
- </sect1>
-
- <sect1 id="example-watchdog">
- <title>Watchdog Configuration Example</title>
-
- <para>
- This tutorial explains the simple way to try "Watchdog".
- What you need is 2 Linux boxes on which <productname>
- Pgpool-II</productname> is installed and a <productname>PostgreSQL</productname>
- on the same machine or in the other one. It is enough
- that 1 node for backend exists.
- You can use watchdog with <productname>
- Pgpool-II</productname> in any mode: replication mode,
- master/slave mode and raw mode.
- </para>
- <para>
- This example uses use "osspc16" as an Active node and
- "osspc20" as a Standby node. "Someserver" means one of them.
- </para>
-
- <sect2 id="example-watchdog-configuration">
- <title>Common configurations</title>
- <para>
- Set the following parameters in both of active and standby nodes.
- </para>
-
- <sect3 id="example-watchdog-config-enable">
- <title>Enabling watchdog</title>
- <para>
- First of all, set <xref linkend="guc-use-watchdog"> to on.
- <programlisting>
-use_watchdog = on
-# Activates watchdog
- </programlisting>
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-config-upstream">
- <title>Configure Up stream servers</title>
- <para>
- Specify the up stream servers (e.g. application servers).
- Leaving it blank is also fine.
- <programlisting>
-trusted_servers = ''
- # trusted server list which are used
- # to confirm network connection
- # (hostA,hostB,hostC,...)
- </programlisting>
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-config-wd-comm">
- <title>Watchdog Communication</title>
- <para>
- Specify the TCP port number for watchdog communication.
- <programlisting>
-wd_port = 9000
- # port number for watchdog service
- </programlisting>
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-config-wd-vip">
- <title>Virtual IP</title>
- <para>
- Specify the IP address to be used as a virtual IP address
- in the <xref linkend="guc-delegate-IP">.
- <programlisting>
-delegate_IP = '133.137.177.143'
-# delegate IP address
- </programlisting>
- </para>
- <note>
- <para>
- Make sure the IP address configured as a Virtual IP should be
- free and is not used by any other machine.
- </para>
- </note>
- </sect3>
- </sect2>
-
- <sect2 id="example-watchdog-configuration-each-server">
- <title>Individual Server Configurations</title>
- <para>
- Next, set the following parameters for each <productname>
- Pgpool-II</productname>.
- Specify <xref linkend="guc-other-pgpool-hostname">,
- <xref linkend="guc-other-pgpool-port"> and
- <xref linkend="guc-other-wd-port"> with the values of
- other <productname>Pgpool-II</productname> server values.
- </para>
-
- <sect3 id="example-watchdog-configuration-active-server">
- <title>Active (osspc16) Server configurations</title>
- <para>
- <programlisting>
-other_pgpool_hostname0 = 'osspc20'
- # Host name or IP address to connect to for other pgpool 0
-other_pgpool_port0 = 9999
- # Port number for other pgpool 0
-other_wd_port0 = 9000
- # Port number for other watchdog 0
- </programlisting>
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-configuration-standby-server">
- <title>Standby (osspc20) Server configurations</title>
- <para>
- <programlisting>
-other_pgpool_hostname0 = 'osspc16'
- # Host name or IP address to connect to for other pgpool 0
-other_pgpool_port0 = 9999
- # Port number for other pgpool 0
-other_wd_port0 = 9000
- # Port number for other watchdog 0
- </programlisting>
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="example-watchdog-start-server">
- <title>Starting <productname>Pgpool-II</productname></title>
- <para>
- Start <productname>Pgpool-II</productname> on each servers from
- <literal>root</literal> user with <literal>"-n"</literal> switch
- and redirect log messages into pgpool.log file.
- </para>
-
- <sect3 id="example-watchdog-start-active-server">
- <title>Starting pgpool in Active server (osspc16)</title>
- <para>
- First start the <productname>Pgpool-II</productname> on Active server.
- <programlisting>
-[user@osspc16]$ su -
-[root@osspc16]# {installed_dir}/bin/pgpool -n -f {installed_dir}/etc/pgpool.conf > pgpool.log 2>&1
- </programlisting>
- Log messages will show that <productname>Pgpool-II</productname>
- has the virtual IP address and starts watchdog process.
- <programlisting>
-LOG: I am announcing my self as master/coordinator watchdog node
-LOG: I am the cluster leader node
-DETAIL: our declare coordinator message is accepted by all nodes
-LOG: I am the cluster leader node. Starting escalation process
-LOG: escalation process started with PID:59449
-<emphasis>LOG: watchdog process is initialized
-LOG: watchdog: escalation started
-LOG: I am the master watchdog node</emphasis>
- DETAIL: using the local backend node status
- </programlisting>
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-start-standby-server">
- <title>Starting pgpool in Standby server (osspc20)</title>
- <para>
- Now start the <productname>Pgpool-II</productname> on Standby server.
- <programlisting>
-[user@osspc20]$ su -
-[root@osspc20]# {installed_dir}/bin/pgpool -n -f {installed_dir}/etc/pgpool.conf > pgpool.log 2>&1
- </programlisting>
- Log messages will show that <productname>Pgpool-II</productname>
- has joind the watchdog cluster as standby watchdog.
- <programlisting>
-LOG: watchdog cluster configured with 1 remote nodes
-LOG: watchdog remote node:0 on Linux_osspc16_9000:9000
-LOG: interface monitoring is disabled in watchdog
-LOG: IPC socket path: "/tmp/.s.PGPOOLWD_CMD.9000"
-LOG: watchdog node state changed from [DEAD] to [LOADING]
-LOG: new outbound connection to Linux_osspc16_9000:9000
-LOG: watchdog node state changed from [LOADING] to [INITIALIZING]
-LOG: watchdog node state changed from [INITIALIZING] to [STANDBY]
-<emphasis>
-LOG: successfully joined the watchdog cluster as standby node
-DETAIL: our join coordinator request is accepted by cluster leader node "Linux_osspc16_9000"
-LOG: watchdog process is initialized
-</emphasis>
- </programlisting>
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="example-watchdog-try">
- <title>Try it out</title>
- <para>
- Confirm to ping to the virtual IP address.
- <programlisting>
-[user@someserver]$ ping 133.137.177.142
-PING 133.137.177.143 (133.137.177.143) 56(84) bytes of data.
-64 bytes from 133.137.177.143: icmp_seq=1 ttl=64 time=0.328 ms
-64 bytes from 133.137.177.143: icmp_seq=2 ttl=64 time=0.264 ms
-64 bytes from 133.137.177.143: icmp_seq=3 ttl=64 time=0.412 ms
- </programlisting>
- Confirm if the Active server which started at first has the virtual IP address.
- <programlisting>
-[root@osspc16]# ifconfig
-eth0 ...
-
-eth0:0 inet addr:133.137.177.143 ...
-
-lo ...
- </programlisting>
- Confirm if the Standby server which started not at first doesn't have the virtual IP address.
- <programlisting>
-[root@osspc20]# ifconfig
-eth0 ...
-
-lo ...
- </programlisting>
-
- Try to connect <productname>PostgreSQL</productname> by "psql -h delegate_IP -p port".
- <programlisting>
-[user@someserver]$ psql -h 133.137.177.142 -p 9999 -l
- </programlisting>
- </para>
- </sect2>
-
- <sect2 id="example-watchdog-vip-switch">
- <title>Switching virtual IP</title>
- <para>
- Confirm how the Standby server works when the Active server can't provide its service.
- Stop <productname>Pgpool-II</productname> on the Active server.
- <programlisting>
-[root@osspc16]# {installed_dir}/bin/pgpool stop
- </programlisting>
-
- Then, the Standby server starts to use the virtual IP address. Log shows:
-
- <programlisting>
-<emphasis>
-LOG: remote node "Linux_osspc16_9000" is shutting down
-LOG: watchdog cluster has lost the coordinator node
-</emphasis>
-LOG: watchdog node state changed from [STANDBY] to [JOINING]
-LOG: watchdog node state changed from [JOINING] to [INITIALIZING]
-LOG: I am the only alive node in the watchdog cluster
-HINT: skipping stand for coordinator state
-LOG: watchdog node state changed from [INITIALIZING] to [MASTER]
-LOG: I am announcing my self as master/coordinator watchdog node
-LOG: I am the cluster leader node
-DETAIL: our declare coordinator message is accepted by all nodes
-<emphasis>
-LOG: I am the cluster leader node. Starting escalation process
-LOG: watchdog: escalation started
-</emphasis>
-LOG: watchdog escalation process with pid: 59551 exit with SUCCESS.
- </programlisting>
-
- Confirm to ping to the virtual IP address.
- <programlisting>
-[user@someserver]$ ping 133.137.177.142
-PING 133.137.177.143 (133.137.177.143) 56(84) bytes of data.
-64 bytes from 133.137.177.143: icmp_seq=1 ttl=64 time=0.328 ms
-64 bytes from 133.137.177.143: icmp_seq=2 ttl=64 time=0.264 ms
-64 bytes from 133.137.177.143: icmp_seq=3 ttl=64 time=0.412 ms
- </programlisting>
-
- Confirm that the Active server doesn't use the virtual IP address any more.
- <programlisting>
-[root@osspc16]# ifconfig
-eth0 ...
-
-lo ...
- </programlisting>
-
- Confirm that the Standby server uses the virtual IP address.
- <programlisting>
-[root@osspc20]# ifconfig
-eth0 ...
-
-eth0:0 inet addr:133.137.177.143 ...
-
-lo ...
- </programlisting>
-
- Try to connect <productname>PostgreSQL</productname> by "psql -h delegate_IP -p port".
- <programlisting>
-[user@someserver]$ psql -h 133.137.177.142 -p 9999 -l
- </programlisting>
-
- </para>
- </sect2>
-
- <sect2 id="example-watchdog-more">
- <title>More</title>
-
- <sect3 id="example-watchdog-more-lifecheck">
- <title>Lifecheck</title>
- <para>
- There are the parameters about watchdog's monitoring.
- Specify the interval to check <xref linkend="guc-wd-interval"> and
- the type of lifecheck <xref linkend="guc-wd-lifecheck-method">.
- The <literal>hearbeat</literal> method specify the time to detect
- a fault <xref linkend="guc-wd-heartbeat-deadtime">, the port number to
- receive <xref linkend="guc-wd-heartbeat-port">, the interval to send
- <xref linkend="guc-wd-heartbeat-keepalive">, the IP address or hostname
- of destination <xref linkend="guc-heartbeat-destination"> and finally
- the destination port number <xref linkend="guc-heartbeat-destination-port">.
- <programlisting>
-wd_lifecheck_method = 'heartbeat'
- # Method of watchdog lifecheck ('heartbeat' or 'query' or 'external')
- # (change requires restart)
-wd_interval = 10
- # lifecheck interval (sec) > 0
-wd_heartbeat_port = 9694
- # Port number for receiving heartbeat signal
- # (change requires restart)
-wd_heartbeat_keepalive = 2
- # Interval time of sending heartbeat signal (sec)
- # (change requires restart)
-wd_heartbeat_deadtime = 30
- # Deadtime interval for heartbeat signal (sec)
- # (change requires restart)
-heartbeat_destination0 = 'host0_ip1'
- # Host name or IP address of destination 0
- # for sending heartbeat signal.
- # (change requires restart)
-heartbeat_destination_port0 = 9694
- # Port number of destination 0 for sending
- # heartbeat signal. Usually this is the
- # same as wd_heartbeat_port.
- # (change requires restart)
- </programlisting>
-
- </para>
- </sect3>
-
- <sect3 id="example-watchdog-more-vip-switching">
- <title>Switching virtual IP address</title>
- <para>
- There are the parameters for switching the virtual IP address.
- Specify switching commands <xref linkend="guc-if-up-cmd">,
- <xref linkend="guc-if-down-cmd">, the path to them
- <xref linkend="guc-if-cmd-path">, the command executed after
- switching to send ARP request <xref linkend="guc-arping-cmd">
- and the path to it <xref linkend="guc-arping-path">.
- <programlisting>
-if_cmd_path = '/sbin'
- # path to the directory where if_up/down_cmd exists
-if_up_cmd = 'ip addr add $_IP_$/24 dev eth0 label eth0:0'
- # startup delegate IP command
-if_down_cmd = 'ip addr del $_IP_$/24 dev eth0'
- # shutdown delegate IP command
-
-arping_path = '/usr/sbin' # arping command path
-
-arping_cmd = 'arping -U $_IP_$ -w 1'
- </programlisting>
- You can also bring up and bring down the virtual IP using arbitrary scripts
- specified <xref linkend="guc-wd-escalation-command"> and
- <xref linkend="guc-wd-de-escalation-command"> parameters.
- </para>
- </sect3>
-
- </sect2>
- </sect1>
-
- <sect1 id="example-cluster">
- <title><productname>Pgpool-II</productname> + Watchdog Setup Example</title>
- <para>
-This section shows an example of streaming replication configuration using <productname>Pgpool-II</productname>. In this example, we use 3 <productname>Pgpool-II</productname> servers to manage <productname>PostgreSQL</productname> servers to create a robust cluster system and avoid the single point of failure or split brain.
- </para>
- <sect2 id="example-cluster-requirement">
- <title>Requirements</title>
- <para>
-We assume that all the Pgpool-II servers and the <productname>PostgreSQL</productname> servers are in the same subnet.
- </para>
- </sect2>
-
- <sect2 id="example-cluster-structure">
- <title>Cluster System Configuration</title>
- <para>
-We use 3 servers with CentOS 7.4. Let these servers be <literal>server1</literal>, <literal>server2</literal>, <literal>server3</literal>. We install <productname>PostgreSQL</productname> and <productname>Pgpool-II</productname> on each server.
- </para>
- <para>
- <figure>
- <title>Cluster System Configuration</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="cluster_40.gif">
- </imageobject>
- </mediaobject>
- </figure>
- </para>
- <note>
- <para>
- The roles of <literal>Active</literal>, <literal>Standy</literal>, <literal>Primary</literal>, <literal>Standby</literal> are not fixed and may be changed by further operations.
- </para>
- </note>
- <table id="example-cluster-table-ip">
- <title>Hostname and IP address</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Hostname</entry>
- <entry>IP Address</entry>
- <entry>Virtual IP</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>server1</entry>
- <entry>192.168.137.101</entry>
- <entry morerows="2">192.168.137.150</entry>
- </row>
- <row>
- <entry>server2</entry>
- <entry>192.168.137.102</entry>
- </row>
- <row>
- <entry>server3</entry>
- <entry>192.168.137.103</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table id="example-cluster-table-postgresql-config">
- <title>PostgreSQL version and Configuration</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Item</entry>
- <entry>Value</entry>
- <entry>Detail</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>PostgreSQL Version</entry>
- <entry>11.1</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>port</entry>
- <entry>5432</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>$PGDATA</entry>
- <entry>/var/lib/pgsql/11/data</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>Archive mode</entry>
- <entry>on</entry>
- <entry>/var/lib/pgsql/archivedir</entry>
- </row>
- <row>
- <entry>Start automatically</entry>
- <entry>Disable</entry>
- <entry>-</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
-
- <table id="example-cluster-table-pgpool-config">
- <title>Pgpool-II version and Configuration</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Item</entry>
- <entry>Value</entry>
- <entry>Detail</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Pgpool-II Version</entry>
- <entry>4.0.2</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry morerows='3'>port</entry>
- <entry>9999</entry>
- <entry>Pgpool-II accepts connections</entry>
- </row>
- <row>
- <entry>9898</entry>
- <entry>PCP process accepts connections</entry>
- </row>
- <row>
- <entry>9000</entry>
- <entry>watchdog accepts connections</entry>
- </row>
- <row>
- <entry>9694</entry>
- <entry>UDP port for receiving Watchdog's heartbeat signal</entry>
- </row>
- <row>
- <entry>Config file</entry>
- <entry>/etc/pgpool-II/pgpool.conf</entry>
- <entry>Pgpool-II config file</entry>
- </row>
- <row>
- <entry>Pgpool-II start user</entry>
- <entry>root</entry>
- <entry>See <xref linkend="TUTORIAL-WATCHDOG-START-STOP"> to startup Pgpool-II with non-root user</entry>
- </row>
- <row>
- <entry>Running mode</entry>
- <entry>streaming replication mode</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>Watchdog</entry>
- <entry>on</entry>
- <entry>Life check method: heartbeat</entry>
- </row>
- <row>
- <entry>Start automatically</entry>
- <entry>Disable</entry>
- <entry>-</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
-
- <sect2 id="example-cluster-installation">
- <title>Installation</title>
- <para>
-In this example, we install <productname>Pgpool-II</productname> 4.0.2 and <productname>PostgreSQL</productname> 11.1 by using RPM packages.
- </para>
-
- <para>
- Install <productname>PostgreSQL</productname> by using <productname>PostgreSQL</productname> YUM repository.
- </para>
- <programlisting>
-# yum install https://download.postgresql.org/pub/repos/yum/11/redhat/rhel-7-x86_64/pgdg-centos11-11-2.noarch.rpm
-# yum install postgresql11 postgresql11-libs postgresql11-devel postgresql11-server
- </programlisting>
- <para>
- Install <productname>Pgpool-II</productname> by using Pgpool-II YUM repository.
- </para>
- <programlisting>
-# yum install http://www.pgpool.net/yum/rpms/4.0/redhat/rhel-7-x86_64/pgpool-II-release-4.0-1.noarch.rpm
-# yum install pgpool-II-pg11-*
- </programlisting>
- </sect2>
-
- <sect2 id="example-cluster-pre-setup">
- <title>Before Starting</title>
- <para>
- Before you start the configuration process, please check the following prerequisites.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
-Set up <productname>PostgreSQL</productname> streaming replication on the primary server. In this example, we use WAL archiving.
- </para>
- <para>
-First, we create the directory <filename>/var/lib/pgsql/archivedir</filename> to store <acronym>WAL</acronym> segments on all servers.
- </para>
- <programlisting>
-[all servers]# su - postgres
-[all servers]$ mkdir /var/lib/pgsql/archivedir
- </programlisting>
-
- <para>
-Then we edit the configuration file <filename>$PGDATA/postgresql.conf</filename> on <literal>server1</literal> (primary) as follows.
- </para>
- <programlisting>
-listen_addresses = '*'
-archive_mode = on
-archive_command = 'cp "%p" "/var/lib/pgsql/archivedir/%f"'
- </programlisting>
- <para>
-We use the online recovery functionality of <productname>Pgpool-II</productname> to setup standby server after the primary server is started.
- </para>
- </listitem>
-
- <listitem>
- <para>
-Because of the security reasons, we create a user <literal>repl</literal> solely used
-for replication purpose, and a user <literal>pgpool</literal> for streaming
-replication delay check and health check of <productname>Pgpool-II</productname>.
- </para>
-
- <table id="example-cluster-user">
- <title>Users</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>User Name</entry>
- <entry>Passowrd</entry>
- <entry>Detail</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>repl</entry>
- <entry>repl</entry>
- <entry>PostgreSQL replication user</entry>
- </row>
- <row>
- <entry>pgpool</entry>
- <entry>pgpool</entry>
- <entry>Pgpool-II health check and replication delay check user</entry>
- </row>
- <row>
- <entry>postgres</entry>
- <entry>postgres</entry>
- <entry>User running online recovery</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <programlisting>
-[server1]# psql -U postgres -p 5432
-postgres=# SET password_encryption = 'scram-sha-256';
-postgres=# CREATE ROLE pgpool WITH LOGIN;
-postgres=# CREATE ROLE repl WITH REPLICATION;
-postgres=# \password pgpool
-postgres=# \password repl
-postgres=# \password postgres
- </programlisting>
-
- <note>
- <para>
- If you plan to
- use <xref linkend="guc-detach-false-primary">, role
- "pgpool" needs to
- be <productname>PostgreSQL</productname> super user or
- or in "pg_monitor" group to use this feature. To let
- "pgpool" role be in the group, you can do:
- <programlisting>
-GRANT pg_monitor TO pgpool;
- </programlisting>
- </para>
- </note>
-
- <para>
-Assuming that all the <productname>Pgpool-II</productname> servers and the
-<productname>PostgreSQL</productname> servers are in the network of
-<literal>192.168.137.0/24</literal>, and edit <filename>pg_hba.conf</filename> to
-enable <literal>scram-sha-256</literal> authentication method.
- </para>
- <programlisting>
-host all pgpool 192.168.137.0/24 scram-sha-256
-host all all 0.0.0.0/0 scram-sha-256
-
-host replication repl 192.168.137.0/24 scram-sha-256
- </programlisting>
- </listitem>
-
- <listitem>
- <para>
-To use the failover and online recovery of <productname>Pgpool-II</productname>, the settings that allow SSH without passowrd to other servers are necessary.
- </para>
- </listitem>
-
- <listitem>
- <para>
-To allow <literal>repl</literal> user without specifying password for streaming
-replication and online recovery, we create the <filename>.pgpass</filename> file
-in <literal>postgres</literal> user's home directory and change the permisson to
-<literal>600</literal> on each <productname>PostgreSQL</productname> server.
- </para>
- <programlisting>
-[all servers]# su - postgres
-[all servers]$ vi /var/lib/pgsql/.pgpass
-server1:5432:replication:repl:<repl user password>
-server2:5432:replication:repl:<repl user passowrd>
-server3:5432:replication:repl:<repl user passowrd>
-[all servers]$ chmod 600 /var/lib/pgsql/.pgpass
- </programlisting>
- </listitem>
-
- <listitem>
- <para>
-When connect to <productname>Pgpool-II</productname> and <productname>PostgreSQL</productname> servers, the target port must be accessible by enabling firewall management softwares. Following is an example for <systemitem>CentOS/RHEL7</systemitem>.
- </para>
- <programlisting>
-[all servers]# firewall-cmd --permanent --zone=public --add-service=postgresql
-[all servers]# firewall-cmd --permanent --zone=public --add-port=9999/tcp --add-port=9898/tcp --add-port=9000/tcp --add-port=9694/tcp
-[all servers]# firewall-cmd --permanent --zone=public --add-port=9999/udp --add-port=9898/udp --add-port=9000/udp --add-port=9694/udp
-[all servers]# firewall-cmd --reload
- </programlisting>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2 id="example-cluster-pgpool-config">
- <title><productname>Pgpool-II</productname> Configuration</title>
- <sect3 id="example-cluster-pgpool-config-common">
- <title>Common Settings</title>
- <para>
-Here are the common settings on <literal>server1</literal>, <literal>server2</literal> and <literal>server3</literal>.
- </para>
- <para>
-When installing <productname>Pgpool-II</productname> from RPM, all the
-<productname>Pgpool-II</productname> configuration files are in <filename>/etc/pgpool-II</filename>.
-In this example, we copy the sample configuration file for streaming replicaton mode.
- </para>
- <programlisting>
-# cp /etc/pgpool-II/pgpool.conf.sample-stream /etc/pgpool-II/pgpool.conf
- </programlisting>
- <para>
-To allow Pgpool-II to accept all incoming connections, we set <varname>listen_addresses = '*'</varname>.
- </para>
- <programlisting>
-listen_addresses = '*'
- </programlisting>
- <para>
-Specify replication delay check user and password. In this example, we leave
-<xref linkend="GUC-SR-CHECK-USER"> empty, and create the entry in <xref linkend="GUC-POOL-PASSWD">.
-From <productname>Pgpool-II</productname> 4.0, if these parameters are left blank,
-<productname>Pgpool-II</productname> will first try to get the password for that
-specific user from <xref linkend="GUC-SR-CHECK-PASSWORD"> file before using the
-empty password.
- </para>
- <programlisting>
-sr_check_user = 'pgpool'
-sr_check_password = ''
- </programlisting>
- <para>
-Enable health check so that <productname>Pgpool-II</> performs failover. Also, if the network is unstable,
-the health check fails even though the backend is running properly, failover or degenerate operation may occur.
-In order to prevent such incorrect detection of health check, we set <varname>health_check_max_retries = 3</varname>.
-Specify <xref linkend="GUC-HEALTH-CHECK-USER"> and <xref linkend="GUC-HEALTH-CHECK-PASSWORD"> in the same way like <xref linkend="GUC-SR-CHECK-USER"> and <xref linkend="GUC-SR-CHECK-PASSWORD">.
- </para>
- <programlisting>
-health_check_period = 5
- # Health check period
- # Disabled (0) by default
-health_check_timeout = 30
- # Health check timeout
- # 0 means no timeout
-health_check_user = 'pgpool'
-health_check_password = ''
-
-health_check_max_retries = 3
- </programlisting>
- <para>
-Specify the <productname>PostgreSQL</productname> backend informations.
-Multiple backends can be specified by adding a number at the end of the parameter name.
- </para>
- <programlisting>
-# - Backend Connection Settings -
-
-backend_hostname0 = 'server1'
- # Host name or IP address to connect to for backend 0
-backend_port0 = 5432
- # Port number for backend 0
-backend_weight0 = 1
- # Weight for backend 0 (only in load balancing mode)
-backend_data_directory0 = '/var/lib/pgsql/11/data'
- # Data directory for backend 0
-backend_flag0 = 'ALLOW_TO_FAILOVER'
- # Controls various backend behavior
- # ALLOW_TO_FAILOVER or DISALLOW_TO_FAILOVER
-backend_hostname1 = 'server2'
-backend_port1 = 5432
-backend_weight1 = 1
-backend_data_directory1 = '/var/lib/pgsql/11/data'
-backend_flag1 = 'ALLOW_TO_FAILOVER'
-
-backend_hostname2 = 'server3'
-backend_port2 = 5432
-backend_weight2 = 1
-backend_data_directory2 = '/var/lib/pgsql/11/data'
-backend_flag2 = 'ALLOW_TO_FAILOVER'
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-failover">
- <title>Failover configuration</title>
- <para>
-Specify failover.sh script to be executed after failover in <varname>failover_command</varname>
-parameter.
-If we use 3 PostgreSQL servers, we need to specify follow_master_command to run after failover on the primary node failover.
-In case of two PostgreSQL servers, follow_master_command setting is not necessary.
- </para>
- <programlisting>
-failover_command = '/etc/pgpool-II/failover.sh %d %h %p %D %m %H %M %P %r %R'
-follow_master_command = '/etc/pgpool-II/follow_master.sh %d %h %p %D %m %M %H %P %r %R'
- </programlisting>
- <para>
-Create <filename>/etc/pgpool-II/failover.sh</filename>, and add execute permission.
- </para>
- <programlisting>
-# vi /etc/pgpool-II/failover.sh
-# vi /etc/pgpool-II/follow_master.sh
-# chmod +x /etc/pgpool-II/{failover.sh,follow_master.sh}
- </programlisting>
-
- <itemizedlist>
- <listitem>
- <para>
-/etc/pgpool-II/failover.sh
- </para>
- <programlisting>
-#!/bin/bash
-# This script is run by failover_command.
-
-set -o xtrace
-exec > >(logger -i -p local1.info) 2>&1
-
-# Special values:
-# %d = node id
-# %h = host name
-# %p = port number
-# %D = database cluster path
-# %m = new master node id
-# %H = hostname of the new master node
-# %M = old master node id
-# %P = old primary node id
-# %r = new master port number
-# %R = new master database cluster path
-# %% = '%' character
-
-FAILED_NODE_ID="$1"
-FAILED_NODE_HOST="$2"
-FAILED_NODE_PORT="$3"
-FAILED_NODE_PGDATA="$4"
-NEW_MASTER_NODE_ID="$5"
-NEW_MASTER_NODE_HOST="$6"
-OLD_MASTER_NODE_ID="$7"
-OLD_PRIMARY_NODE_ID="$8"
-NEW_MASTER_NODE_PORT="$9"
-NEW_MASTER_NODE_PGDATA="${10}"
-
-PGHOME=/usr/pgsql-11
-
-logger -i -p local1.info failover.sh: start: failed_node_id=$FAILED_NODE_ID old_primary_node_id=$OLD_PRIMARY_NODE_ID \
- failed_host=$FAILED_NODE_HOST new_master_host=$NEW_MASTER_NODE_HOST
-
-# If standby node is down, skip failover.
-if [ $FAILED_NODE_ID -ne $OLD_PRIMARY_NODE_ID ]; then
- logger -i -p local1.info failover.sh: Standby node is down. Skipping failover.
- exit 0
-fi
-
-# Promote standby node.
-logger -i -p local1.info failover.sh: ssh: postgres@$NEW_MASTER_NODE_HOST pg_ctl promote
-if [ $UID -eq 0 ]; then
- su postgres -c "ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
- postgres@$NEW_MASTER_NODE_HOST ${PGHOME}/bin/pg_ctl -D ${NEW_MASTER_NODE_PGDATA} -w promote"
-else
- ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
- postgres@$NEW_MASTER_NODE_HOST ${PGHOME}/bin/pg_ctl -D ${NEW_MASTER_NODE_PGDATA} -w promote
-fi
-
-if [[ $? -ne 0 ]]; then
- logger -i -p local1.error failover.sh: new_master_host=$NEW_MASTER_NODE_HOST promote failed
- exit 1
-fi
-
-logger -i -p local1.info failover.sh: end: new_master_node_id=$NEW_MASTER_NODE_ID started as the primary node
-exit 0
- </programlisting>
- </listitem>
- </itemizedlist>
-
- <itemizedlist>
- <listitem>
- <para>
-/etc/pgpool-II/follow_master.sh
- </para>
- <programlisting>
-#!/bin/bash
-# This script is run after failover_command to recover the slave from the new primary.
-
-set -o xtrace
-exec > >(logger -i -p local1.info) 2>&1
-
-# special values: %d = node id
-# %h = host name
-# %p = port number
-# %D = database cluster path
-# %m = new master node id
-# %M = old master node id
-# %H = new master node host name
-# %P = old primary node id
-# %R = new master database cluster path
-# %r = new master port number
-# %% = '%' character
-FAILED_NODE_ID="$1"
-FAILED_NODE_HOST="$2"
-FAILED_NODE_PORT="$3"
-FAILED_NODE_PGDATA="$4"
-NEW_MASTER_NODE_ID="$5"
-OLD_MASTER_NODE_ID="$6"
-NEW_MASTER_NODE_HOST="$7"
-OLD_PRIMARY_NODE_ID="$8"
-NEW_MASTER_NODE_PORT="$9"
-NEW_MASTER_NODE_PGDATA="${10}"
-
-PGHOME=/usr/pgsql-11
-ARCHIVEDIR=/var/lib/pgsql/archivedir
-REPL_USER=repl
-PCP_USER=pgpool
-PGPOOL_PATH=/usr/bin
-PCP_PORT=9898
-
-
-# Recovery the slave from the new primary
-logger -i -p local1.info follow_master.sh: start: pg_basebackup for $FAILED_NODE_ID
-
-# Check the status of standby
-ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
- postgres@${FAILED_NODE_HOST} ${PGHOME}/bin/pg_ctl -w -D ${FAILED_NODE_PGDATA} status >/dev/null 2>&1
-
-# If slave is running, recover the slave from the new primary.
-if [[ $? -eq 0 ]]; then
-
- # Execute pg_basebackup at slave
- ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@${FAILED_NODE_HOST} "
- ${PGHOME}/bin/pg_ctl -w -m f -D ${FAILED_NODE_PGDATA} stop
-
- rm -rf ${FAILED_NODE_PGDATA}
- ${PGHOME}/bin/pg_basebackup -h ${NEW_MASTER_NODE_HOST} -U ${REPL_USER} -p ${NEW_MASTER_NODE_PORT} -D ${FAILED_NODE_PGDATA} -X stream -R
-
- if [[ $? -ne 0 ]]; then
- logger -i -p local1.error follow_master.sh: end: pg_basebackup failed
- exit 1
- fi
- rm -rf ${ARCHIVEDIR}/*
-cat >> ${FAILED_NODE_PGDATA}/recovery.conf << EOT
-restore_command = 'scp ${NEW_MASTER_NODE_HOST}:${ARCHIVEDIR}/%f %p'
-EOT
- $PGHOME/bin/pg_ctl -l /dev/null -w -D ${FAILED_NODE_PGDATA} start
- "
-
- if [[ $? -eq 0 ]]; then
-
- # Run pcp_attact_node to attach this slave to Pgpool-II.
- ${PGPOOL_PATH}/pcp_attach_node -w -h localhost -U ${PCP_USER} -p ${PCP_PORT} -n ${FAILED_NODE_ID}
-
- if [[ $? -ne 0 ]]; then
- logger -i -p local1.error follow_master.sh: end: pcp_attach_node failed
- exit 1
- fi
- else
- logger -i -p local1.error follow_master.sh: end: follow master failed
- exit 1
- fi
-
-else
- logger -i -p local1.info follow_master.sh: failed_nod_id=${FAILED_NODE_ID} is not running. skipping follow master command.
- exit 0
-fi
-
-logger -i -p local1.info follow_master.sh: end: follow master is finished
-exit 0
- </programlisting>
- </listitem>
- </itemizedlist>
-
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-online-recovery">
- <title>Pgpool-II Online Recovery Configurations</title>
- <para>
-Next, in order to perform online recovery with <productname>Pgpool-II</productname> we specify
-the <productname>PostgreSQL</productname> user name and online recovery command
-<command>recovery_1st_stage</command>.
-Because Supergroup privilege of PostgreSQL is required for online recovery, we specify postgres user to <xref linkend="GUC-RECOVERY-USER">.
-Then, we create <filename>recovery_1st_stage</filename> and <filename>pgpool_remote_start</filename>
-in database cluster directory of <productname>PostgreSQL</productname> primary server (server1), and add execute permission.
-
- </para>
- <programlisting>
-recovery_user = 'postgres'
- # Online recovery user
-recovery_password = ''
- # Online recovery password
-
-recovery_1st_stage_command = 'recovery_1st_stage'
- </programlisting>
- <programlisting>
-[server1]# su - postgres
-[server1]$ vi /var/lib/pgsql/11/data/recovery_1st_stage
-[server1]$ vi /var/lib/pgsql/11/data/pgpool_remote_start
-[server1]$ chmod +x /var/lib/pgsql/11/data/{recovery_1st_stage,pgpool_remote_start}
- </programlisting>
-
- <itemizedlist>
- <listitem>
- <para>
-/var/lib/pgsql/11/data/recovery_1st_stage
- </para>
- <programlisting>
-#!/bin/bash
-# This script is run by recovery_1st_stage to recovery the slave from the primary.
-
-set -o xtrace
-exec > >(logger -i -p local1.info) 2>&1
-
-PRIMARY_NODE_PGDATA="$1"
-DEST_NODE_HOST="$2"
-DEST_NODE_PGDATA="$3"
-PRIMARY_NODE_PGPORT=$4
-
-PRIMARY_NODE_HOST=$(hostname -s)
-PGHOME=/usr/pgsql-11
-ARCHIVEDIR=/var/lib/pgsql/archivedir
-REPLUSER=repl
-
-
-logger -i -p local1.info online_recovery.sh: start: pg_basebackup for $DEST_NODE_HOST
-
-# Run pg_basebackup to recovery the slave from the primary
-ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$DEST_NODE_HOST "
-rm -rf $DEST_NODE_PGDATA
-${PGHOME}/bin/pg_basebackup -h $PRIMARY_NODE_HOST -U $REPLUSER -p $PRIMARY_NODE_PGPORT -D $DEST_NODE_PGDATA -X stream -R
-"
-if [[ $? -ne 0 ]]; then
- logger -i -p local1.error online_recovery.sh: end: pg_basebackup failed. online recovery failed.
- exit 1
-fi
-
-ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$DEST_NODE_HOST "
-rm -rf $ARCHIVEDIR/*
-cat >> $DEST_NODE_PGDATA/recovery.conf << EOT
-restore_command = 'scp $PRIMARY_NODE_HOST:$archivedir/%f %p'
-EOT
-"
-
-if [[ $? -ne 0 ]]; then
- logger -i -p local1.error online_recovery.sh: end: online recovery failed
- exit 1
-else
- logger -i -p local1.info online_recovery.sh: end: online recovery is finished
- exit 0
-fi
- </programlisting>
- </listitem>
- <listitem>
-
- <para>
-/var/lib/pgsql/11/data/pgpool_remote_start
- </para>
- <programlisting>
-#!/bin/bash
-# This script is run to start slave node after recovery.
-
-set -o xtrace
-exec > >(logger -i -p local1.info) 2>&1
-
-PGHOME=/usr/pgsql-11
-DEST_HOST="$1"
-DEST_HOST_PGDATA="$2"
-
-
-logger -i -p local1.info pgpool_remote_start: start: remote start PostgreSQL@$DEST_HOST
-
-# Start slave node
-ssh -T -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null postgres@$DEST_HOST $PGHOME/bin/pg_ctl -l /dev/null -w -D $DEST_HOST_PGDATA start
-
-if [[ $? -ne 0 ]]; then
- logger -i -p local1.info pgpool_remote_start: $DEST_HOST start failed.
- exit 1
-fi
-
-logger -i -p local1.info pgpool_remote_start: end: $DEST_HOST PostgreSQL started successfully.
- </programlisting>
- </listitem>
- </itemizedlist>
-
- <para>
- In order to use the online recovery functionality, the functions of
- <function>pgpool_recovery</function>, <function>pgpool_remote_start</function>,
- <function>pgpool_switch_xlog</function> are required, so we need install
- <function>pgpool_recovery</function> on template1 of <productname>PostgreSQL</productname> server
- <literal>server1</literal>.
- </para>
- <programlisting>
-[server1]# su - postgres
-[server1]$ psql template1 -c "CREATE EXTENSION pgpool_recovery"
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-auth">
- <title>Client Authentication Configuration</title>
- <para>
-Because in the section <link linkend="EXAMPLE-CLUSTER-PRE-SETUP">Before Starting</link>,
-we already set <productname>PostgreSQL</productname> authentication method to
-<acronym>scram-sha-256</acronym>, it is necessary to set a client authentication by
-<productname>Pgpool-II</productname> to connect to backend nodes.
-Please note that only AES encrypted password or clear text password can be specified
-in <xref linkend="guc-health-check-password">, <xref linkend="guc-sr-check-password">,
-<xref linkend="guc-wd-lifecheck-password">, <xref linkend="guc-recovery-password"> in <filename>pgpool.conf</filename>.
-When installing with RPM,
-the <productname>Pgpool-II</productname> configuration file <filename>pool_hba.conf</filename>
-is in <filename>/etc/pgpool-II</filename>.
-By default, pool_hba authentication is disabled, and set <varname>enable_pool_hba = on</varname>
-to enable it.
- </para>
- <programlisting>
-enable_pool_hba = on
- </programlisting>
- <para>
-The format of <filename>pool_hba.conf</filename> file follows very closely PostgreSQL's
-<filename>pg_hba.conf</filename> format. Set <literal>pgpool</literal> and <literal>postgres</literal> user's authentication method to <literal>scram-sha-256</literal>.
- </para>
- <programlisting>
-host all pgpool 0.0.0.0/0 scram-sha-256
-host all postgres 0.0.0.0/0 scram-sha-256
- </programlisting>
- <para>
-The default password file name for authentication is <xref linkend="GUC-POOL-PASSWD">.
-To use <literal>scram-sha-256</literal> authentication, the decryption key to decrypt the passwords
-is required. We create the .pgpoolkey file in root user's home directory.
- <programlisting>
-[all servers]# echo 'some string' > ~/.pgpoolkey
-[all servers]# chmod 600 ~/.pgpoolkey
- </programlisting>
- </para>
- <para>
-Execute command <command>pg_enc -m -k /path/to/.pgpoolkey -u username -p</command> to regist user
-name and <literal>AES</literal> encrypted password in file <filename>pool_passwd</filename>.
-If <filename>pool_passwd</filename> doesn't exist yet, it will be created in the same directory as
-<filename>pgpool.conf</filename>.
- </para>
- <programlisting>
-[all servers]# pg_enc -m -k /root/.pgpoolkey -u pgpool -p
-db password: [pgpool user's password]
-[all servers]# pg_enc -m -k /root/.pgpoolkey -u postgres -p
-db password: [postgres user's passowrd]
-
-# cat /etc/pgpool-II/pool_passwd
-pgpool:AESheq2ZMZjynddMWk5sKP/Rw==
-postgres:AESHs/pWL5rtXy2IwuzroHfqg==
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-watchdog">
- <title>Watchdog Configuration</title>
- <para>
- Enable watchdog functionality on <literal>server1</literal>, <literal>server2</literal>, <literal>server3</literal>.
- </para>
- <programlisting>
-use_watchdog = on
- </programlisting>
- <para>
- Specify virtual IP address that accepts connections from clients on
- <literal>server1</literal>, <literal>server2</literal>, <literal>server3</literal>.
- Ensure that the IP address set to virtual IP isn't used yet.
- </para>
- <programlisting>
-delegate_IP = '192.168.137.150'
- </programlisting>
-
- <para>
- To bring up/down the virtual IP and send the ARP requests, we set <xref linkend="GUC-IF-UP-CMD">, <xref linkend="GUC-IF-DOWN-CMD"> and <xref linkend="GUC-ARPING-CMD">.
- The network interface used in this example is "enp0s8".
- </para>
- <programlisting>
-if_up_cmd = 'ip addr add $_IP_$/24 dev enp0s8 label enp0s8:0'
- # startup delegate IP command
-if_down_cmd = 'ip addr del $_IP_$/24 dev enp0s8'
- # shutdown delegate IP command
-arping_cmd = 'arping -U $_IP_$ -w 1 -I enp0s8'
- # arping command
- </programlisting>
- <para>
- Set <xref linkend="GUC-IF-CMD-PATH"> and <xref linkend="GUC-ARPING-PATH"> according to the
- command path.
- </para>
- <programlisting>
-if_cmd_path = '/sbin'
- # path to the directory where if_up/down_cmd exists
-arping_path = '/usr/sbin'
- # arping command path
- </programlisting>
- <para>
- Specify the hostname and port number of each <productname>Pgpool-II</productname> server.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>server1</literal>
- </para>
- <programlisting>
-wd_hostname = 'server1'
-wd_port = 9000
- </programlisting>
- </listitem>
- <listitem>
- <para>
- <literal>server2</literal>
- </para>
- <programlisting>
-wd_hostname = 'server2'
-wd_port = 9000
- </programlisting>
- </listitem>
- <listitem>
- <para>
- <literal>server3</literal>
- </para>
- <programlisting>
-wd_hostname = 'server3'
-wd_port = 9000
- </programlisting>
- </listitem>
- </itemizedlist>
-
- <para>
- Specify the hostname, <productname>Pgpool-II</productname> port number, and watchdog port number of monitored <productname>Pgpool-II</productname> servers on each <productname>Pgpool-II</productname> server.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>server1</literal>
- </para>
- <programlisting>
-# - Other pgpool Connection Settings -
-
-other_pgpool_hostname0 = 'server2'
- # Host name or IP address to connect to for other pgpool 0
- # (change requires restart)
-other_pgpool_port0 = 9999
- # Port number for other pgpool 0
- # (change requires restart)
-other_wd_port0 = 9000
- # Port number for other watchdog 0
- # (change requires restart)
-other_pgpool_hostname1 = 'server3'
-other_pgpool_port1 = 9999
-other_wd_port1 = 9000
- </programlisting>
- </listitem>
- <listitem>
- <para>
- <literal>server2</literal>
- </para>
- <programlisting>
-# - Other pgpool Connection Settings -
-
-other_pgpool_hostname0 = 'server1'
- # Host name or IP address to connect to for other pgpool 0
- # (change requires restart)
-other_pgpool_port0 = 9999
- # Port number for other pgpool 0
- # (change requires restart)
-other_wd_port0 = 9000
- # Port number for other watchdog 0
- # (change requires restart)
-other_pgpool_hostname1 = 'server3'
-other_pgpool_port1 = 9999
-other_wd_port1 = 9000
- </programlisting>
- </listitem>
- <listitem>
- <para>
- <literal>server3</literal>
- </para>
- <programlisting>
-# - Other pgpool Connection Settings -
-
-other_pgpool_hostname0 = 'server1'
- # Host name or IP address to connect to for other pgpool 0
- # (change requires restart)
-other_pgpool_port0 = 9999
- # Port number for other pgpool 0
- # (change requires restart)
-other_wd_port0 = 9000
- # Port number for other watchdog 0
- # (change requires restart)
-other_pgpool_hostname1 = 'server2'
-other_pgpool_port1 = 9999
-other_wd_port1 = 9000
- </programlisting>
- </listitem>
- </itemizedlist>
-
- <para>
- Specify the hostname and port number of destination for sending heartbeat signal
- on <literal>server1</literal>, <literal>server2</literal>, <literal>server3</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>server1</literal>
- </para>
- <programlisting>
-heartbeat_destination0 = 'server2'
- # Host name or IP address of destination 0
- # for sending heartbeat signal.
- # (change requires restart)
-heartbeat_destination_port0 = 9694
- # Port number of destination 0 for sending
- # heartbeat signal. Usually this is the
- # same as wd_heartbeat_port.
- # (change requires restart)
-heartbeat_device0 = ''
- # Name of NIC device (such like 'eth0')
- # used for sending/receiving heartbeat
- # signal to/from destination 0.
- # This works only when this is not empty
- # and pgpool has root privilege.
- # (change requires restart)
-
-heartbeat_destination1 = 'server3'
-heartbeat_destination_port1 = 9694
-heartbeat_device1 = ''
-
- </programlisting>
- </listitem>
- <listitem>
- <para>
- <literal>server2</literal>
- </para>
- <programlisting>
-heartbeat_destination0 = 'server1'
- # Host name or IP address of destination 0
- # for sending heartbeat signal.
- # (change requires restart)
-heartbeat_destination_port0 = 9694
- # Port number of destination 0 for sending
- # heartbeat signal. Usually this is the
- # same as wd_heartbeat_port.
- # (change requires restart)
-heartbeat_device0 = ''
- # Name of NIC device (such like 'eth0')
- # used for sending/receiving heartbeat
- # signal to/from destination 0.
- # This works only when this is not empty
- # and pgpool has root privilege.
- # (change requires restart)
-
-heartbeat_destination1 = 'server3'
-heartbeat_destination_port1 = 9694
-heartbeat_device1 = ''
-
- </programlisting>
- </listitem>
- <listitem>
- <para>
- <literal>server3</literal>
- </para>
- <programlisting>
-heartbeat_destination0 = 'server1'
- # Host name or IP address of destination 0
- # for sending heartbeat signal.
- # (change requires restart)
-heartbeat_destination_port0 = 9694
- # Port number of destination 0 for sending
- # heartbeat signal. Usually this is the
- # same as wd_heartbeat_port.
- # (change requires restart)
-heartbeat_device0 = ''
- # Name of NIC device (such like 'eth0')
- # used for sending/receiving heartbeat
- # signal to/from destination 0.
- # This works only when this is not empty
- # and pgpool has root privilege.
- # (change requires restart)
-
-heartbeat_destination1 = 'server2'
-heartbeat_destination_port1 = 9694
-heartbeat_device1 = ''
- </programlisting>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-sysconfig">
- <title>/etc/sysconfig/pgpool Configuration</title>
- <para>
- If you want to ignore the <filename>pgpool_status</filename> file at startup of
- <productname>Pgpool-II</productname>, add "- D" to the start option OPTS to
- <filename>/etc/sysconfig/pgpool</filename>.
- </para>
- <programlisting>
-[all servers]# vi /etc/sysconfig/pgpool
-...
-OPTS=" -D -n"
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-log">
- <title>Logging</title>
- <para>
-In the example, we output <productname>Pgpool-II</productname>'s log to <literal>syslog</literal>.
- </para>
- <programlisting>
-log_destination = 'syslog'
- # Where to log
- # Valid values are combinations of stderr,
- # and syslog. Default to stderr.
-
-syslog_facility = 'LOCAL1'
- # Syslog local facility. Default to LOCAL0
- </programlisting>
- <para>
- Create <productname>Pgpool-II</productname> log file.
- </para>
- <programlisting>
-[all servers]# mkdir /var/log/pgpool-II
-[all servers]# touch /var/log/pgpool-II/pgpool.log
- </programlisting>
- <para>
- Edit config file of syslog <filename>/etc/rsyslog.conf</filename>.
- </para>
- <programlisting>
-[all servers]# vi /etc/rsyslog.conf
-...
-*.info;mail.none;authpriv.none;cron.none;LOCAL1.none /var/log/messages
-LOCAL1.* /var/log/pgpool-II/pgpool.log
- </programlisting>
- <para>
- Setting logrotate same as <filename>/var/log/messages</filename>.
- </para>
- <programlisting>
-[all servers]# vi /etc/logrotate.d/syslog
-...
-/var/log/messages
-/var/log/pgpool-II/pgpool.log
-/var/log/secure
- </programlisting>
-
- <para>
- Restart rsyslog service.
- </para>
- <programlisting>
-[all servers]# systemctl restart rsyslog
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-pcp">
- <title>PCP Command Configuration</title>
- <para>
- Since user authentication is required to use the <literal>PCP</literal> command,
- specify user name and md5 encrypted password in <filename>pcp.conf</filename>.
- Here we create the encrypted password for <literal>pgpool</literal> user, and add
- "<literal>username:encrypted password</literal>" in <filename>/etc/pgpool-II/pcp.conf</filename>.
- </para>
- <programlisting>
-[all servers]# echo 'pgpool:'`pg_md5 PCP passowrd` >> /etc/pgpool-II/pcp.conf
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-pgpool-config-pcppass">
- <title>.pcppass</title>
- <para>
- Since follow_master_command script has to execute PCP command without entering the
- password, we create <filename>.pcppass</filename> in the home directory of
- <productname>Pgpool-II</productname> startup user (root user).
- </para>
- <programlisting>
-[all servers]# echo 'localhost:9898:pgpool:pgpool' > ~/.pcppass
-[all servers]# chmod 600 ~/.pcppass
- </programlisting>
- <para>
- The settings of <productname>Pgpool-II</productname> is completed.
- </para>
- </sect3>
-
- </sect2>
-
- <sect2 id="example-cluster-start-stop">
- <title>Starting/Stopping Pgpool-II</title>
- <para>
- Next we start <productname>Pgpool-II</productname>. Before starting
- <productname>Pgpool-II</productname>, please start
- <productname>PostgreSQL</productname> servers first.
- Also, when stopping <productname>PostgreSQL</productname>, it is necessary to
- stop Pgpool-II first.
- </para>
- <itemizedlist>
- <listitem>
- <para>
-Starting <productname>Pgpool-II</productname>
- </para>
- <para>
- In section <link linkend="EXAMPLE-CLUSTER-PRE-SETUP">Before Starting</link>, we already set the auto-start of <productname>Pgpool-II</productname>. To start <productname>Pgpool-II</productname>, restart the whole system or execute the following command.
- </para>
- <programlisting>
-# systemctl start pgpool.service
- </programlisting>
- </listitem>
- <listitem>
- <para>
- Stopping <productname>Pgpool-II</productname>
- </para>
- <programlisting>
-# systemctl stop pgpool.service
- </programlisting>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2 id="example-cluster-try">
- <title>How to use</title>
- <para>
- Let's start to use <productname>Pgpool-II</productname>.
- First, let's start <productname>Pgpool-II</productname> on <literal>server1</literal>,
- <literal>server2</literal>, <literal>server3</literal> by using the following command.
- </para>
- <programlisting>
-# systemctl start pgpool.service
- </programlisting>
-
- <sect3 id="example-cluster-try-standby">
- <title>Set up PostgreSQL standby server</title>
- <para>
- First, we should set up <productname>PostgreSQL</productname> standby server by
- using <productname>Pgpool-II</productname> online recovery functionality. Ensure
- that <filename>recovery_1st_stage</filename> and <filename>pgpool_remote_start</filename>
- scripts used by <command>pcp_recovery_node</command> command are in database
- cluster directory of <productname>PostgreSQL</productname> primary server (<literal>server1</literal>).
- </para>
- <programlisting>
-# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 1
-Password:
-pcp_recovery_node -- Command Successful
-
-# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 2
-Password:
-pcp_recovery_node -- Command Successful
- </programlisting>
- <para>
- After executing <command>pcp_recovery_node</command> command,
- vertify that <literal>server2</literal> and <literal>server3</literal>
- are started as <productname>PostgreSQL</productname> standby server.
- </para>
- <programlisting>
-# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
- node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | last_status_change
----------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+---------------------
- 0 | server1 | 5432 | up | 0.333333 | primary | 0 | false | 0 | 2019-02-18 11:26:31
- 1 | server2 | 5432 | up | 0.333333 | standby | 0 | true | 0 | 2019-02-18 11:27:49
- 2 | server3 | 5432 | up | 0.333333 | standby | 0 | false | 0 | 2019-02-18 11:27:49
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-try-watchdog">
- <title>Switching active/standby watchdog</title>
- <para>
- Confirm the watchdog status by using <command>pcp_watchdog_info</command>. The <command>Pgpool-II</command> server which is started first run as <literal>MASTER</literal>.
- </para>
- <programlisting>
-# pcp_watchdog_info -h 192.168.137.150 -p 9898 -U pgpool
-Password:
-3 YES server1:9999 Linux server1 server1
-
-server1:9999 Linux server1 server1 9999 9000 4 MASTER #The Pgpool-II server started first becames "MASTER".
-server2:9999 Linux server2 server2 9999 9000 7 STANDBY #run as standby
-server3:9999 Linux server3 server3 9999 9000 7 STANDBY #run as standby
- </programlisting>
- <para>
- Stop active server <literal>server1</literal>, then <literal>server2</literal> or
- <literal>server3</literal> will be promoted to active server. To stop
- <literal>server1</literal>, we can stop <productname>Pgpool-II</productname>
- service or shutdown the whole system. Here, we stop <productname>Pgpool-II</productname> service.
- </para>
- <programlisting>
-[server1]# systemctl stop pgpool.service
-
-# pcp_watchdog_info -p 9898 -h 192.168.137.150 -U pgpool
-Password:
-3 YES server2:9999 Linux server2 server2
-
-server2:9999 Linux server2 server2 9999 9000 4 MASTER #server2 is promoted to MASTER
-server1:9999 Linux server1 server1 9999 9000 10 SHUTDOWN #server1 is stopped
-server3:9999 Linux server3 server3 9999 9000 7 STANDBY #server3 runs as STANDBY
- </programlisting>
- <para>
-Start <productname>Pgpool-II</productname> (<literal>server1</literal>) which we have stopped again, and vertify that <literal>server1</literal> runs as a standby.
- </para>
- <programlisting>
-[server1]# systemctl start pgpool.service
-
-[server1]# pcp_watchdog_info -p 9898 -h 192.168.137.150 -U pgpool
-Password:
-3 YES server2:9999 Linux server2 server2
-
-server2:9999 Linux server2 server2 9999 9000 4 MASTER
-server1:9999 Linux server1 server1 9999 9000 7 STANDBY
-server3:9999 Linux server3 server3 9999 9000 7 STANDBY
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-try-failover">
- <title>Failover</title>
- <para>
-First, use <command>psql</command> to connect to <productname>PostgreSQL</productname> via virtual IP, and verify the backend informations.
- </para>
- <programlisting>
-# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
- node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | last_status_change
----------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+---------------------
- 0 | server1 | 5432 | up | 0.333333 | primary | 0 | false | 0 | 2019-02-18 13:08:02
- 1 | server2 | 5432 | up | 0.333333 | standby | 0 | false | 0 | 2019-02-18 13:21:56
- 2 | server3 | 5432 | up | 0.333333 | standby | 0 | true | 0 | 2019-02-18 13:21:56
- </programlisting>
- <para>
- Next, stop primary <productname>PostgreSQL</productname> server
- <literal>server1</literal>, and verify automatic failover.
- </para>
- <programlisting>
-[server1]$ pg_ctl -D /var/lib/pgsql/11/data -m immediate stop
- </programlisting>
- <para>
- After stopping <productname>PostgreSQL</productname> on <literal>server1</literal>,
- failover occurs and <productname>PostgreSQL</productname> on
- <literal>server2</literal> becomes new primary DB.
- </para>
- <programlisting>
-# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
- node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | last_status_change
----------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+---------------------
- 0 | server1 | 5432 | down | 0.333333 | standby | 0 | false | 0 | 2019-02-18 13:22:25
- 1 | server2 | 5432 | up | 0.333333 | primary | 0 | true | 0 | 2019-02-18 13:22:25
- 2 | server3 | 5432 | up | 0.333333 | standby | 0 | false | 0 | 2019-02-18 13:22:28
- </programlisting>
- <para>
-<literal>server3</literal> is running as standby of new primary <literal>server2</literal>.
- </para>
-
- <programlisting>
-[server3]# psql -h server3 -p 5432 -U pgpool postgres -c "select pg_is_in_recovery()"
- pg_is_in_recovery
--------------------
- t
-
-[server2]# su - postgres
-$ psql
-postgres=# select pg_is_in_recovery();
- pg_is_in_recovery
--------------------
- f
-
-postgres=# select * from pg_stat_replication;
--[ RECORD 1 ]----+------------------------------
-pid | 11915
-usesysid | 16385
-usename | repl
-application_name | walreceiver
-client_addr | 192.168.137.103
-client_hostname |
-client_port | 37834
-backend_start | 2019-02-18 13:22:27.472038+09
-backend_xmin |
-state | streaming
-sent_lsn | 0/8E000060
-write_lsn | 0/8E000060
-flush_lsn | 0/8E000060
-replay_lsn | 0/8E000060
-write_lag |
-flush_lag |
-replay_lag |
-sync_priority | 0
-sync_state | async
- </programlisting>
- </sect3>
-
- <sect3 id="example-cluster-try-online-recovery">
- <title>Online Recovery</title>
- <para>
- Here, we use <productname>Pgpool-II</productname> online recovery functionality to
- restore <literal>server1</literal> (old primary server) as a standby. Before
- restoring the old primary server, please ensure that
- <filename>recovery_1st_stage</filename> and <filename>pgpool_remote_start</filename> scripts
- exist in database cluster directory of current primary server <literal>server2</literal>.
- </para>
- <programlisting>
-# pcp_recovery_node -h 192.168.137.150 -p 9898 -U pgpool -n 0
-Password:
-pcp_recovery_node -- Command Successful
- </programlisting>
- <para>
- Then verify that <literal>server1</literal> is started as a standby.
- </para>
- <programlisting>
-# psql -h 192.168.137.150 -p 9999 -U pgpool postgres -c "show pool_nodes"
- node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | replication_delay | last_status_change
----------+----------+------+--------+-----------+---------+------------+-------------------+-------------------+---------------------
- 0 | server1 | 5432 | up | 0.333333 | standby | 0 | false | 0 | 2019-02-18 13:27:44
- 1 | server2 | 5432 | up | 0.333333 | primary | 0 | false | 0 | 2019-02-18 13:22:25
- 2 | server3 | 5432 | up | 0.333333 | standby | 0 | true | 0 | 2019-02-18 13:22:28
- </programlisting>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="example-AWS">
- <title>AWS Configuration Example</title>
-
- <para>
- This tutorial explains the simple way to try "Watchdog"
- on <ulink url="https://aws.amazon.com/">AWS</ulink> and using
- the <ulink url="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html">
- Elastic IP Address</ulink> as the Virtual IP for the high availability solution.
- <note>
- <para>
- You can use watchdog with <productname>
- Pgpool-II</productname> in any mode: replication mode,
- master/slave mode and raw mode.
- </para>
- </note>
- </para>
-
- <sect2 id="example-AWS-setup">
- <title>AWS Setup</title>
- <para>
- For this example, we will use two node <productname>
- Pgpool-II</productname> watchdog cluster. So we will set up two
- Linux Amazon EC2 instances and one Elastic IP address.
- So for this example, do the following steps:
- </para>
- <itemizedlist>
-
- <listitem>
- <para>
- Launch two Linux Amazon EC2 instances. For this example, we name these
- instances as "instance-1" and "instance-2"
- </para>
- </listitem>
-
- <listitem>
- <para>
- Configure the security group for the instances and allow inbound traffic
- on ports used by pgpool-II and watchdog.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Install the <productname>Pgpool-II</productname> on both instances.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Allocate an Elastic IP address.
- For this example, we will use "35.163.178.3" as an Elastic IP address"
- </para>
- </listitem>
-
- </itemizedlist>
-
- </sect2>
-
- <sect2 id="example-AWS-pgpool-config">
- <title><productname>Pgpool-II</productname> configurations</title>
- <para>
- Mostly the <productname>Pgpool-II</productname> configurations for this
- example will be same as in the <xref linkend="example-watchdog">, except the
- <xref linkend="guc-delegate-ip"> which we will not set in this example instead
- we will use <xref linkend="guc-wd-escalation-command"> and
- <xref linkend="guc-wd-de-escalation-command"> to switch the
- Elastic IP address to the maste/Active <productname>Pgpool-II</productname> node.
- </para>
-
- <sect3 id="example-AWS-pgpool-config-instance-1">
- <title><productname>Pgpool-II</productname> configurations on Instance-1</title>
- <para>
-
- <programlisting>
-use_watchdog = on
-delegate_IP = ''
-wd_hostname = 'instance-1-private-ip'
-other_pgpool_hostname0 = 'instance-2-private-ip'
-other_pgpool_port0 = 9999
-other_wd_port0 = 9000
-wd_escalation_command = '$path_to_script/aws-escalation.sh'
-wd_de_escalation_command = '$path_to_script/aws-de-escalation.sh'
- </programlisting>
-
- </para>
- </sect3>
-
- <sect3 id="example-AWS-pgpool-config-instance-2">
- <title><productname>Pgpool-II</productname> configurations on Instance-2</title>
- <para>
-
- <programlisting>
-use_watchdog = on
-delegate_IP = ''
-wd_hostname = 'instance-2-private-ip'
-other_pgpool_hostname0 = 'instance-1-private-ip'
-other_pgpool_port0 = 9999
-other_wd_port0 = 9000
-wd_escalation_command = '$path_to_script/aws-escalation.sh'
-wd_de_escalation_command = '$path_to_script/aws-de-escalation.sh'
- </programlisting>
-
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="example-AWS-pgpool-aws-escalation-instance">
- <title>escalation and de-escalation Scripts</title>
- <para>
- Create the aws-escalation.sh and aws-de-escalation.sh scripts on both
- instances and point the <xref linkend="guc-wd-escalation-command"> and
- <xref linkend="guc-wd-de-escalation-command"> to the respective scripts.
- </para>
-
- <note>
- <para>
- You may need to configure the AWS CLI first on all AWS instances
- to enable the execution of commands used by wd-escalation.sh and wd-de-escalation.sh.
- See <ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">configure AWS CLI</ulink>
- </para>
- </note>
-
- <sect3 id="example-AWS-pgpool-aws-escalation-script">
- <title>escalation script</title>
-
- <para>
- This script will be executed by the watchdog
- to assign the Elastic IP on the instance when the watchdog becomes the active/master node.
- Change the INSTANCE_ID and ELASTIC_IP values as per your AWS setup values.
- </para>
- <para>
- <emphasis>aws-escalation.sh:</emphasis>
- <programlisting>
-#! /bin/sh
-
-ELASTIC_IP=35.163.178.3
- # replace it with the Elastic IP address you
- # allocated from the aws console
-INSTANCE_ID=i-0a9b64e449b17ed4b
- # replace it with the instance id of the Instance
- # this script is installed on
-
-echo "Assigning Elastic IP $ELASTIC_IP to the instance $INSTANCE_ID"
-# bring up the Elastic IP
-aws ec2 associate-address --instance-id $INSTANCE_ID --public-ip $ELASTIC_IP
-
-exit 0
- </programlisting>
-
- </para>
-
- </sect3>
- <sect3 id="example-AWS-pgpool-aws-de-escalation-script">
- <title>de-escalation script</title>
-
- <para>
- This script will be executed by watchdog
- to remove the Elastic IP from the instance when the watchdog resign from the active/master node.
- </para>
- <para>
- <emphasis>aws-de-escalation.sh:</emphasis>
- <programlisting>
-#! /bin/sh
-
-ELASTIC_IP=35.163.178.3
- # replace it with the Elastic IP address you
- # allocated from the aws console
-
-echo "disassociating the Elastic IP $ELASTIC_IP from the instance"
-# bring down the Elastic IP
-aws ec2 disassociate-address --public-ip $ELASTIC_IP
-exit 0
- </programlisting>
- </para>
- </sect3>
-
- <bibliography>
- <title>AWS Command References</title>
-
- <biblioentry>
- <biblioset relation="article">
- <title><ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html">Configure AWS CLI</ulink></title>
- </biblioset>
- <biblioset relation="book">
- <title>AWS Documentation: Configuring the AWS Command Line Interface</title>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset relation="article">
- <title><ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/associate-address.html">associate-address</ulink></title>
- </biblioset>
- <biblioset relation="book">
- <title>AWS Documentation: associate-address reference</title>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset relation="article">
- <title><ulink url="http://docs.aws.amazon.com/cli/latest/reference/ec2/disassociate-address.html">disassociate-address</ulink></title>
- </biblioset>
- <biblioset relation="book">
- <title>AWS Documentation: disassociate-address reference</title>
- </biblioset>
- </biblioentry>
-
- </bibliography>
- </sect2>
-
- <sect2 id="example-AWS-try">
- <title>Try it out</title>
- <para>
- Start <productname>Pgpool-II</productname> on each server with "-n" switch
- and redirect log messages to the pgpool.log file.
- The log message of master/active <productname>Pgpool-II</productname> node
- will show the message of Elastic IP assignment.
- <programlisting>
-LOG: I am the cluster leader node. Starting escalation process
-LOG: escalation process started with PID:23543
-LOG: watchdog: escalation started
-<emphasis>
- Assigning Elastic IP 35.163.178.3 to the instance i-0a9b64e449b17ed4b
- {
- "AssociationId": "eipassoc-39853c42"
- }
-</emphasis>
-LOG: watchdog escalation successful
-LOG: watchdog escalation process with pid: 23543 exit with SUCCESS.
- </programlisting>
- </para>
-
- <para>
- Confirm to ping to the Elastic IP address.
- <programlisting>
-[user@someserver]$ ping 35.163.178.3
-PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
-64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
-64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
-64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
- </programlisting>
- </para>
-
- <para>
- Try to connect <productname>PostgreSQL</productname> by "psql -h ELASTIC_IP -p port".
- <programlisting>
-[user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
- </programlisting>
- </para>
- </sect2>
-
- <sect2 id="example-AWS-vip-switch">
- <title>Switching Elastic IP</title>
- <para>
- To confirm if the Standby server acquires the Elastic IP when the
- Active server becomes unavailable, Stop the <productname>Pgpool-II</productname>
- on the Active server. Then, the Standby server should start using the Elastic IP address,
- And the <productname>Pgpool-II</productname> log will show the below messages.
-
- <programlisting>
-<emphasis>
-LOG: remote node "172.31.2.94:9999 [Linux ip-172-31-2-94]" is shutting down
-LOG: watchdog cluster has lost the coordinator node
-</emphasis>
-LOG: watchdog node state changed from [STANDBY] to [JOINING]
-LOG: watchdog node state changed from [JOINING] to [INITIALIZING]
-LOG: I am the only alive node in the watchdog cluster
-HINT: skipping stand for coordinator state
-LOG: watchdog node state changed from [INITIALIZING] to [MASTER]
-LOG: I am announcing my self as master/coordinator watchdog node
-LOG: I am the cluster leader node
-DETAIL: our declare coordinator message is accepted by all nodes
-LOG: I am the cluster leader node. Starting escalation process
-LOG: escalation process started with PID:23543
-LOG: watchdog: escalation started
-<emphasis>
- Assigning Elastic IP 35.163.178.3 to the instance i-0dd3e60734a6ebe14
- {
- "AssociationId": "eipassoc-39853c42"
- }
-</emphasis>
-LOG: watchdog escalation successful
-LOG: watchdog escalation process with pid: 61581 exit with SUCCESS.
- </programlisting>
- Confirm to ping to the Elastic IP address again.
- <programlisting>
-[user@someserver]$ ping 35.163.178.3
-PING 35.163.178.3 (35.163.178.3) 56(84) bytes of data.
-64 bytes from 35.163.178.3: icmp_seq=1 ttl=64 time=0.328 ms
-64 bytes from 35.163.178.3: icmp_seq=2 ttl=64 time=0.264 ms
-64 bytes from 35.163.178.3: icmp_seq=3 ttl=64 time=0.412 ms
- </programlisting>
- </para>
- <para>
- Try to connect <productname>PostgreSQL</productname> by "psql -h ELASTIC_IP -p port".
- <programlisting>
-[user@someserver]$ psql -h 35.163.178.3 -p 9999 -l
- </programlisting>
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="example-Aurora">
- <title>Aurora Configuration Example</title>
-
- <para>
- <productname>Amazon Aurora for PostgreSQL
- Compatibility</productname> (Aurora) is a managed service for
- <productname>PostgreSQL</productname>. From user's point of
- view, <productname>Aurora</productname> can be regarded as a
- streaming replication cluster with some exceptions. First,
- fail over and online recovery are managed
- by <productname>Aurora</productname>. So you don't need to
- set <xref linkend="guc-failover-command">, <xref linkend="guc-follow-master-command">,
- and recovery related parameters. In this section we explain
- how to set up <productname>Pgpool-II</productname> for Aurora.
- </para>
-
- <sect2 id="example-Aurora-config">
- <title>Setting pgpool.conf for Aurora</title>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- Create <filename>pgpool.conf</filename>
- from <filename>pgpool.conf.sample-stream</filename>.
- </para>
- </listitem>
- <listitem>
- <para>
- Set <xref linkend="guc-sr-check-period"> to 0 to
- disable streaming replication delay checking. This
- is because <productname>Aurora</productname> does
- not provide neccessary functions to check the
- replication delay.
- </para>
- </listitem>
- <listitem>
- <para>
- Enable <xref linkend="guc-enable-pool-hba"> to on so
- that md5 authentication is enabled
- (<productname>Aurora</productname> always use md5
- authentication).
- </para>
- </listitem>
- <listitem>
- <para>
- Create <filename>pool_password</filename>. See <xref linkend="auth-md5">
- for more details.
- </para>
- </listitem>
- <listitem>
- <para>
- Set <xref linkend="guc-backend-hostname">0 for the
- Aurora writer node. Set
- other <xref linkend="guc-backend-hostname"> for the
- Aurora reader node. Set
- appropreate <xref linkend="guc-backend-weight"> as
- usual. You don't need to
- set <xref linkend="guc-backend-data-directory">
- </para>
- </listitem>
- <listitem>
- <para>
- Set <varname>ALWAYS_MASTER</varname> flag to
- the <xref linkend="guc-backend-flag">
- for <xref linkend="guc-backend-hostname">0.
- </para>
- </listitem>
- <listitem>
- <para>
- Enable health checking.
- Set <xref linkend="guc-health-check-period"> to 5.
- Set <xref linkend="guc-health-check-user">, <xref linkend="guc-health-check-password">,
- <xref linkend="guc-health-check-user"> and
- <xref linkend="guc-health-check-database"> to appropriate values.
- Enable health check retry.
- <productname>Aurora</productname> shutdowns all DB nodes while switching
- over or failover. If the retry is not performed,
- <productname>Pgpool-II</productname> thinks that all DB nodes are in down status
- so that it is required to restart <productname>Pgpool-II</productname>.
- Set <xref linkend="guc-health-check-max-retries"> to 20.
- Set <xref linkend="guc-health-check-retry-delay"> to 1 to avoid the problem.
- </para>
- </listitem>
- <listitem>
- <para>
- Disable <xref linkend="guc-failover-on-backend-error">
- to avoid failover when connecting to the backend or
- detecting errors on backend side while executing
- queries for the same reasons above.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect2>
- </sect1>
-
- </chapter>
+ <title>Examples</title>
+
+ <partintro>
+ <para>
+ Various examples
+ </para>
+ </partintro>
+
+ <chapter id="example-configs">
+ <title>Configuration Examples</title>
+ &example-basic;
+ &example-watchdog;
+ &example-cluster;
+ &example-AWS;
+ &example-Aurora;
+ </chapter>
</part>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 81a923bce..c705915c9 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -66,7 +66,12 @@
<!ENTITY user-manag SYSTEM "user-manag.sgml">
<!ENTITY wal SYSTEM "wal.sgml">
-<!ENTITY examples SYSTEM "examples.sgml">
+<!ENTITY examples SYSTEM "examples.sgml">
+<!ENTITY example-basic SYSTEM "example-basic.sgml">
+<!ENTITY example-watchdog SYSTEM "example-watchdog.sgml">
+<!ENTITY example-cluster SYSTEM "example-cluster.sgml">
+<!ENTITY example-AWS SYSTEM "example-AWS.sgml">
+<!ENTITY example-Aurora SYSTEM "example-Aurora.sgml">
<!-- programmer's guide -->
<!ENTITY bgworker SYSTEM "bgworker.sgml">
[parent: 3922c12c1f8e]