<!-- doc/src/sgml/config.sgml -->

<sect1 id="runtime-watchdog-config">
 <title>Watchdog</title>

 <indexterm zone="runtime-watchdog-config">
  <primary>configuring watchdog</primary>
 </indexterm>
 <para>
  Watchdog configuration parameters are described in pgpool.conf.
  There is sample configuration in the WATCHDOG section of
  <filename>pgpool.conf.sample</filename> file.
  All following options are required to be specified in watchdog process.
 </para>

 <sect2 id="config-enable-watchdog">
  <title>Enable watchdog</title>

  <variablelist>
   <varlistentry id="guc-use-watchdog" xreflabel="use_watchdog">
    <term><varname>use_watchdog</varname> (<type>boolean</type>)
     <indexterm>
      <primary><varname>use_watchdog</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      If on, activates the watchdog. Default is off
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
     <para>
      <productname>Pgpool-II</productname> 4.1 or earlier, because it is required to specify
      its own pgpool node information and the destination pgpool nodes information, the
      settings are different per pgpool node.
      Since <productname>Pgpool-II</productname> 4.2, all configuration parameters are
      identical on all hosts. If watchdog feature is enabled, to distinguish which host
      is which, a <filename>pgpool_node_id</filename> file is required.
      You need to create a <filename>pgpool_node_id</filename> file and specify the
      pgpool (watchdog) node number (e.g. 0, 1, 2 ...) to identify pgpool (watchdog) host.
     </para>
     <example id="example-pgpool-node-id-1">
      <title>pgpool_node_id configuration</title>
      <para>
       If you have 3 pgpool nodes with hostname server1, server2 and server3, create the
       <filename>pgpool_node_id</filename> file on each host as follows.
       When installing <productname>Pgpool-II</productname> using RPM,
       <filename>pgpool.conf</filename> is installed under <filename>/etc/pgpool-II/</filename>.
      </para>
      <itemizedlist>
       <listitem>
        <para>
         <literal>server1</literal>
        </para>
        <programlisting>
[server1]# cat /etc/pgpool-II/pgpool_node_id
0
        </programlisting>
       </listitem>
       <listitem>
        <para>
         <literal>server2</literal>
        </para>
        <programlisting>
[server2]# cat /etc/pgpool-II/pgpool_node_id
1
        </programlisting>
       </listitem>
       <listitem>
        <para>
         <literal>server3</literal>
        </para>
        <programlisting>
[server3]# cat /etc/pgpool-II/pgpool_node_id
2
        </programlisting>
       </listitem>
      </itemizedlist>
     </example>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect2>

 <sect2 id="config-communication-watchdog">
  <title>Watchdog communication</title>

  <variablelist>

   <varlistentry id="guc-hostname" xreflabel="hostname">
    <term><varname>hostnameX</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>hostnameX</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the hostname or IP (IPv4 or IPv6) address of
      <productname>Pgpool-II</productname> server.
      This is used for sending/receiving queries and packets,
      and also as an identifier of the watchdog node.
      The number at the end of the parameter name is referred
      as "pgpool node id", and it starts from 0 (e.g. hostname0).
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-listen-address" xreflabel="wd_listen_address">
    <term><varname>wd_listen_address</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>wd_listen_address</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the hostname or IP (IPv4 or IPv6) address which watchdog will listen on.
      Default is <literal>''</literal> (empty). Specify only one address here.
      If a value other than the default value is set,
      the value of hostnameX of the local node will be ignored and a socket
      that listens on the address specified in wd_listen_address will be created.
      For <varname>wd_listen_address</varname>, specifying <literal>*</literal> will listen on all addresses.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-port" xreflabel="wd_port">
    <term><varname>wd_portX</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>wd_portX</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the port number to be used by watchdog
      process to listen for connections. Default is 9000.
      The number at the end of the parameter name is referred
      as "pgpool node id", and it starts from 0 (e.g. wd_port0).
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-listen-port" xreflabel="wd_listen_port">
    <term><varname>wd_listen_port</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>wd_listen_port</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the port number which watchdog will listen on.
      Default is 0. Specify only one address here.
      If a value other than the default value is set,
      the value of wd_portX of the local node will be ignored and a socket
      that listens on the port specified in wd_listen_port will be created.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-pgpool-port" xreflabel="pgpool_port">
    <term><varname>pgpool_portX</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>pgpool_portX</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the <productname>Pgpool-II</productname> port number.
      Default is 9999.
      The number at the end of the parameter name is referred
      as "pgpool node id", and it starts from 0 (e.g. pgpool_port0).
     </para>
     <para>
      This parameter can only be set at server start.
     </para>

     <example id="example-watchdog-1">
      <title>Watchdog configuration</title>
      <para>
       If you have 3 pgpool nodes with hostname server1, server2 and server3,
       you can configure <xref linkend="guc-hostname">,
       <xref linkend="guc-wd-port"> and <xref linkend="guc-pgpool-port"> like below:
    <programlisting>
hostname0 = 'server1'
wd_port0 = 9000
pgpool_port0 = 9999

hostname1 = 'server2'
wd_port1 = 9000
pgpool_port1 = 9999

hostname2 = 'server3'
wd_port2 = 9000
pgpool_port2 = 9999
    </programlisting>
      </para>
     </example>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-authkey" xreflabel="wd_authkey">
    <term><varname>wd_authkey</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>wd_authkey</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the authentication key used for all watchdog communications.
      All <productname>Pgpool-II</productname> must have the same key.
      Packets from watchdog having different key will get rejected.
      This authentication is also applied to the heartbeat signals
      when the <literal>heartbeat</> mode is used as a lifecheck method.
     </para>
     <para>
      Since in <productname>Pgpool-II</productname><emphasis>V3.5</emphasis> or beyond
      <varname>wd_authkey</varname> is also used to authenticate
      the watchdog IPC clients,
      all clients communicating with <productname>Pgpool-II</productname>
      watchdog process needs to provide this wd_authkey value
      for <literal>"IPCAuthKey"</literal> key in the JSON data
      of the command.
     </para>
     <para>
      Default is <literal>''</literal> (empty) which means disables
      the watchdog authentication.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect2>

 <sect2 id="config-watchdog-upstream-connections">
  <title>Upstream server connection</title>

  <para>
   Upstream servers are the clients (DB clients) served by
   <productname>Pgpool-II</productname>.
   Even if <productname>Pgpool-II</productname> is alive and
   connected to <productname>PostgreSQL</productname>, 
   if the link with the upstream server is broken,
   <productname>Pgpool-II</productname> cannot provide services.
   Therefore, the watchdog also monitors connections to upstream servers
   from the <productname>Pgpool-II</productname>.
  </para>

  <variablelist>

   <varlistentry id="guc-trusted-servers" xreflabel="trusted_servers">
    <term><varname>trusted_servers</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>trusted_servers</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the list of trusted servers to check the upstream connections.
      For example, the list of upstream servers or routers between
      <productname>Pgpool-II</productname> and upstream servers.
      Each server in the list is required to respond to ping.
      Specify a comma separated list of servers such as
      <literal>"hostA,hostB,hostC"</literal>.
      If none of the server are reachable, watchdog will regard it as
      failure of the <productname>Pgpool-II</productname>.
      Therefore, it is recommended to specify multiple servers.
      Please note that you should not assign PostgreSQL servers to this parameter.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-trusted-server-command" xreflabel="trusted_server_command">
    <term><varname>trusted_server_command</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>trusted_server_command</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies a user command to run when <productname>Pgpool-II</productname> check
      that trusted servers respond to ping. Any %h in the string is replaced by each host
      name specified <varname>trusted_servers</varname>. Default is
      <literal>ping -q -c3 %h</literal>.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect2>

 <sect2 id="config-watchdog-vip-control">
  <title>Virtual IP control</title>

  <variablelist>

   <varlistentry id="guc-delegate-ip" xreflabel="delegate_ip">
    <term><varname>delegate_ip</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>delegate_ip</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the virtual IP address (VIP) of
      <productname>Pgpool-II</productname> that is connected from
      client servers (application servers etc.).  When a
      <productname>Pgpool-II</productname> is switched from standby to
      leader, the <productname>Pgpool-II</productname> takes over this
      VIP. <emphasis>VIP will not be brought up in case the quorum
      does not exist</emphasis>. Default is <literal>''</literal>(empty): which
      means virtual IP will never be brought up.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-if-cmd-path" xreflabel="if_cmd_path">
    <term><varname>if_cmd_path</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>if_cmd_path</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the path to the command that <productname>Pgpool-II</productname>
      will use to switch the virtual IP on the system.
      Set only the path of the directory containing the binary,
      such as <literal>"/sbin"</literal> or such directory.
      If <xref linkend="guc-if-up-cmd"> or <xref linkend="guc-if-down-cmd"> starts with "/",
      this parameter will be ignored.
      Default is <literal>/sbin</literal>.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-if-up-cmd" xreflabel="if_up_cmd">
    <term><varname>if_up_cmd</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>if_up_cmd</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the command to bring up the virtual IP.
      Set the command and parameters such as
      <literal>"ip addr add $_IP_$/24 dev eth0 label eth0:0"</literal>.
      Since root privilege is required to execute this command,
      use <command>setuid</command> on <command>ip</command> command or
      allow <productname>Pgpool-II</productname> startup user (<literal>postgres</literal> user by default)
      to run <command>sudo</command> command without a password, and specify it such as
      <literal>"/usr/bin/sudo /sbin/ip addr add $_IP_$/24 dev eth0 label eth0:0"</literal>.
      <literal>$_IP_$</literal> will get replaced by the IP address
      specified in the <xref linkend="guc-delegate-ip">.
     </para>
     <para>
      Default is <literal>/usr/bin/sudo /sbin/ip addr add $_IP_$/24 dev eth0 label eth0:0</literal>.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-if-down-cmd" xreflabel="if_down_cmd">
    <term><varname>if_down_cmd</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>if_down_cmd</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the command to bring down the virtual IP.
      Set the command and parameters such as
      <literal>"ip addr del $_IP_$/24 dev eth0"</literal>.
      Since root privilege is required to execute this command,
      use <command>setuid</command> on <command>ip</command> command or
      allow <productname>Pgpool-II</productname> startup user (<literal>postgres</literal> user by default)
      to run <command>sudo</command> command without a password, and specify it such as
      <literal>"/usr/bin/sudo /sbin/ip addr del $_IP_$/24 dev eth0"</literal>.
      <literal>$_IP_$</literal> will get replaced by the IP address
      specified in the <xref linkend="guc-delegate-ip">.
     </para>
     <para>
      Default is <literal>/usr/bin/sudo /sbin/ip addr del $_IP_$/24 dev eth0</literal>.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-arping-path" xreflabel="arping_path">
    <term><varname>arping_path</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>arping_path</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the path to the command that <productname>Pgpool-II</productname>
      will use to send the ARP requests after the virtual IP switch.
      Set only the path of the directory containing the binary,
      such as <literal>"/usr/sbin"</literal> or such directory.
      If <xref linkend="guc-arping-cmd"> starts with "/",
      this parameter will be ignored.
      Default is <literal>/usr/sbin</literal>.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-arping-cmd" xreflabel="arping_cmd">
    <term><varname>arping_cmd</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>arping_cmd</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the command to use for sending the ARP requests
      after the virtual IP switch.
      Set the command and parameters such as
      <literal>"arping -U $_IP_$ -w 1 -I eth0"</literal>.
      Since root privilege is required to execute this command,
      use <command>setuid</command> on <command>ip</command> command or
      allow <productname>Pgpool-II</productname> startup user (<literal>postgres</literal> user by default)
      to run <command>sudo</command> command without a password, and specify it such as
      <literal>"/usr/bin/sudo /usr/sbin/arping -U $_IP_$ -w 1 -I eth0"</literal>.
      <literal>$_IP_$</literal> will get replaced by
      the IP address specified in the <varname>delegate_ip</varname>.
     </para>
     <para>
      Default is <literal>/usr/bin/sudo /usr/sbin/arping -U $_IP_$ -w 1 -I eth0</literal>.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-ping-path" xreflabel="ping_path">
    <term><varname>ping_path</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>ping_path</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the path of a ping command to check startup of the virtual IP.
      Set the only path of the directory containing the ping utility,
      such as <literal>"/bin"</literal> or such directory.
      Default is <literal>/bin</literal>.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect2>

 <sect2 id="config-watchdog-escalation-de-escalation">
  <title>Behaviour on escalation and de-escalation</title>

  <para>
   Configuration about behavior when <productname>Pgpool-II</productname>
   escalates to leader (virtual IP holder)
  </para>

  <variablelist>

   <varlistentry id="guc-clear-memqcache-on-escalation" xreflabel="clear_memqcache_on_escalation">
    <term><varname>clear_memqcache_on_escalation</varname> (<type>boolean</type>)
     <indexterm>
      <primary><varname>clear_memqcache_on_escalation</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      When set to on, watchdog clears all the query cache in the shared memory
      when pgpool-II escalates to leader. This prevents the new leader <productname>Pgpool-II</productname>
      from using old query caches inconsistent to the old leader.
     </para>
     <para>
      Default is on.
     </para>
     <para>
      This works only if <xref linkend="guc-memqcache-method">
       is <literal>'shmem'</literal>.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-escalation-command" xreflabel="wd_escalation_command">
    <term><varname>wd_escalation_command</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>wd_escalation_command</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Watchdog executes this command on the node that is escalated
      to the leader watchdog.
     </para>
     <para>
      This command is executed just before bringing up the
      virtual IP if that is configured on the node.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-de-escalation-command" xreflabel="wd_de_escalation_command">
    <term><varname>wd_de_escalation_command</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>wd_de_escalation_command</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Watchdog executes this command on the leader <productname>Pgpool-II</productname>
      watchdog node when that node resigns from the leader node responsibilities.
      A leader watchdog node can resign from being a leader node,
      when the leader node <productname>Pgpool-II</productname> shuts down, detects a network
      blackout or detects the lost of <indexterm><primary>quorum</primary></indexterm><firstterm>quorum</firstterm>.
     </para>
     <para>
      This command is executed before bringing down the virtual/floating IP address
      if it is configured on the watchdog node.
     </para>
     <para>
      <varname>wd_de_escalation_command</varname> is not available prior to
      <productname>Pgpool-II </productname><emphasis>V3.5</emphasis>.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect2>

 <sect2 id="config-watchdog-failover-behavior">
  <title>Controlling the Failover behavior</title>

  <para>
   These settings are used to control the behavior of backend node failover when the watchdog is enabled.
   The effect of these configurations is limited to the failover/degenerate requests initiated by
   <productname>Pgpool-II</productname> internally, while the user initiated detach backend requests
   (using PCP command) by-pass these configuration settings.
  </para>

  <variablelist>

   <varlistentry id="guc-failover-when-quorum-exists" xreflabel="failover_when_quorum_exists">
    <term><varname>failover_when_quorum_exists</varname> (<type>boolean</type>)
     <indexterm>
      <primary><varname>failover_when_quorum_exists</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      When enabled, <productname>Pgpool-II</productname> will consider <indexterm><primary>quorum</primary></indexterm>quorum when it performs the degenerate/failover on backend node.
     </para>
     <para>
      We can say that "quorum exists" if the number of live
      watchdog nodes (that is number
      of <productname>Pgpool-II</productname> nodes) can be a
      majority against the total number of watchdog nodes. For
      example, suppose number of watchdog nodes is 5. If number of
      live nodes is greater than or equal to 3, then quorum
      exists. On the other hand if number of live nodes is 2 or
      lower, quorum does not exist since it never be
      majority.
     </para>
     <para>
      If the quorum exists, <productname>Pgpool-II</productname>
      could work better on failure detection because even if a
      watchdog node mistakenly detects a failure of backend node,
      it would be denied by other major watchdog nodes.
      <productname>Pgpool-II</productname> works that way
      when <xref linkend="guc-failover-require-consensus"> is on
       (the default), but you can change it so that immediate
       failover happens when a failure is detected.
       A <productname>Pgpool-II</productname> node which mistakenly
       detects failure of backend node will quarantine the backend
       node.
     </para>
     <para>
      The existence of quorum can be shown by invoking <xref linkend="pcp-watchdog-info"> command with <literal>--verbose</literal> option.
       If <literal>Quorum state</literal> is <literal>QUORUM EXIST</literal> or <literal>QUORUM IS ON THE EDGE</literal>, then the quorum exists.
       If <literal>Quorum state</literal> is <literal>QUORUM ABSENT</literal>, then the quorum does not exist.
     </para>
     <para>
      In the absence of the
      quorum, <productname>Pgpool-II</productname> node that
      detects the backend failure will quarantine the failed
      backend node until the quorum exists again.
     </para>
     <para>
      Although it is possible to force detaching the quarantine
      node by using <command>pcp_detach_node</command> command, it
      is not possible to attach the node again by
      using <command>pcp_attach_node</command> command.
     </para>
     <para>
      The <indexterm><primary>quarantine</primary></indexterm>
      quarantine nodes behaves similar to the detached backend nodes
      but unlike failed/degenerated backends the quarantine status is
      not propagated to the other <productname>Pgpool-II</productname>
      nodes in the watchdog cluster, So even if the backend node is in
      the quarantine state on one <productname>Pgpool-II</productname>
      node, other <productname>Pgpool-II</productname> nodes may still
      continue to use that backend.
     </para>
     <para>
      Although there are many similarities in quarantine and failover operations, but they both differ in a very
      fundamental way. The quarantine operations does not executes the <xref linkend="guc-failover-command">
       and silently detaches the problematic node, so in the case when the primary backend node is quarantined, the
       <productname>Pgpool-II</productname> will not promote the standby to take over the primary node responsibilities
       and until the primary node is quarantined the <productname>Pgpool-II</productname> will not have
       any usable primary backend node.
     </para>
     <para>
      Moreover, unlike for the failed nodes,
      <productname>Pgpool-II</productname> keeps the health-check
      running on the quarantined nodes and as soon as the quarantined
      node becomes reachable again it gets automatically
      re-attached. Note that this is only applied to
      <productname>Pgpool-II </productname><emphasis>V4.1</emphasis>
      or greater. If you are using previous versions you need to
      re-attach the quarantined node by using <xref
      linkend="pcp-attach-node"> when the connectivity issue is
      solved.
     </para>
     <para>
      From <productname>Pgpool-II </productname><emphasis>V4.1</emphasis> onward, if the watchdog-leader node
      fails to build the consensus for primary backend node failover and the primary backend node gets into a
      quarantine state, then it resigns from its leader responsibilities and lowers its wd_priority
      for next leader election and let the cluster elect some different new leader.
      <note>
       <para>
	When the leader node fails to build the consensus for standby backend node failure, it takes no action
	and similarly quarantined standby backend nodes on watchdog-leader do not trigger a new leader election.
       </para>
      </note>
     </para>
     <para>
      If this parameter is off, failover will be triggered even if
      quorum does not exist.
     </para>
     <para>
      Default is on.
     </para>
     <para>
      <varname>failover_when_quorum_exists</varname> is not available prior to
      <productname>Pgpool-II </productname><emphasis>V3.7</emphasis>.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
     <note>
      <para>
       enabling <varname>failover_when_quorum_exists</varname> is not allowed in native replication mode.
      </para>
     </note>
   </listitem>
   </varlistentry>

   <varlistentry id="guc-failover-require-consensus" xreflabel="failover_require_consensus">
    <term><varname>failover_require_consensus</varname> (<type>boolean</type>)
     <indexterm>
      <primary><varname>failover_require_consensus</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      When enabled, <productname>Pgpool-II</productname> will perform the degenerate/failover on a
      backend node if the watchdog quorum exists and at-least minimum number of nodes necessary
      for the quorum vote for the failover.
     </para>
     <para>
      For example, in a three node watchdog cluster, the failover will only be performed until at
      least two nodes ask for performing the failover on the particular backend node.
     </para>
     <para>
      If this parameter is off, failover will be triggered even if
      there's no consensus.
     </para>
     <para>
      Default is on.
     </para>

     <caution>
      <para>
       When <varname>failover_require_consensus</varname> is
       enabled, <productname>Pgpool-II</productname> does not
       execute the failover until it get enough votes from
       other <productname>Pgpool-II</productname> nodes. So it is
       strongly recommended to enable the backend health check on
       all
       <productname>Pgpool-II</productname> nodes to ensure
       proper detection of backend node failures.  For more
       details of health check,
       see <xref linkend="runtime-config-health-check">.
      </para>
     </caution>

     <note>
      <para>
       enabling <varname>failover_require_consensus</varname> is not allowed in native replication mode.
      </para>
     </note>

     <para>
      <varname>failover_require_consensus</varname> is not available prior to
      <productname>Pgpool-II </productname><emphasis>V3.7</emphasis>. and it is only
      effective when <xref linkend="guc-failover-when-quorum-exists"> is enabled
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-allow-multiple-failover-requests-from-node" xreflabel="allow_multiple_failover_requests_from_node">
    <term><varname>allow_multiple_failover_requests_from_node</varname> (<type>boolean</type>)
     <indexterm>
      <primary><varname>allow_multiple_failover_requests_from_node</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      This parameter works in connection with the
      <xref linkend="guc-failover-require-consensus">. When enabled, a single <productname>Pgpool-II</productname>
       node can cast multiple votes for the failover.
     </para>
     <para>
      For example, in a three node watchdog cluster, if one <productname>Pgpool-II</productname> node sends two
      failover requests for a particular backend node failover, Both requests will be counted as a separate
      vote in the favor of the failover and <productname>Pgpool-II</productname> will execute the failover,
      even if it does not get the vote from any other <productname>Pgpool-II</productname> node.
     </para>
     <para>
      For example, if an error found in a health check round does
      not get enough vote and the error still persists, next round
      of health check will give one more vote.  This parameter is
      useful if you want to detect a persistent error which might
      not be found by other watchdog nodes.
     </para>
     <para>
      Default is off.
     </para>
     <para>
      <varname>allow_multiple_failover_requests_from_node</varname> is not available prior to
      <productname>Pgpool-II </productname><emphasis>V3.7</emphasis>. and it is only
      effective when both <xref linkend="guc-failover-when-quorum-exists"> and
       <xref linkend="guc-failover-require-consensus"> are enabled
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-enable-consensus-with-half-votes" xreflabel="enable_consensus_with_half_votes">
    <term><varname>enable_consensus_with_half_votes</varname> (<type>boolean</type>)
     <indexterm>
      <primary><varname>enable_consensus_with_half_votes</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      This parameter configures how the majority rule computation
      is made by <productname>Pgpool-II</productname> for calculating
      the quorum and resolving the consensus for failover.
     </para>
     <note>
      <para>
       This parameter affects not only the failover behavior of the
       backend but the quorum and the failover behavior of
       <productname>Pgpool-II</productname> itself.
      </para>
     </note>
     <para>
      When enabled the existence of quorum and consensus on failover requires only half of
      the total number of votes configured in the cluster. Otherwise, both of these
      decisions require at least one more vote than half of the total number of votes.
      For failover, this parameter works in conjunction with the
      <xref linkend="guc-failover-require-consensus">. In both cases, whether making a
      decision of quorum existence or building the consensus on failover this
      parameter only comes into play when the watchdog cluster is configured for even
      number of <productname>Pgpool-II</productname> nodes.
      The majority rule decision in the watchdog cluster having an odd number of participants.
      It is not affected by the value of this configuration parameter.
     </para>
     <para>
      For example, when this parameter is enabled in a two node watchdog
      cluster, one <productname>Pgpool-II</productname> node needs to
      be alive to make the quorum exist. If the parameter is off, two
      nodes need to be alive to make quorum exist.
     </para>
     <para>
      When this parameter is enabled in a four node watchdog cluster,
      two <productname>Pgpool-II</productname> node needs to be alive
      to make the quorum exist. If the parameter is off, three nodes
      need to be alive to make quorum exist.
     </para>
     <para>
      By enabling this parameter, you should aware that you take a
      risk to make split-brain happen. For example, in four node
      cluster consisted of node A, B, C and D, it is possible that the
      cluster goes into two separated networks (A, B) and (C, D). For
      (A, B) and (C, D) the quorum still exist since for both groups
      there are two live nodes out of 4. The two groups choose their
      own leader watchdog, which is a split-brain.
     </para>
     <para>
      Default is off.
     </para>
     <para>
      <varname>enable_consensus_with_half_votes</varname> is not available
      prior to <productname>Pgpool-II
      </productname><emphasis>V4.1</emphasis>. The prior versions work
      as if the parameter is on.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

  </variablelist>
 </sect2>

 <sect2 id="config-watchdog-cluster-membership">
  <title>Controlling the watchdog cluster membership </title>

  <para>
	By default the watchdog cluster consists of all watchdog nodes
	that are defined in the <filename>pgpool.conf</filename> file
	irrespective of the current state of the node. Whether the node
	is <literal>LOST</literal>, <literal>SHUTDOWN</literal>
	or never started, the node is considered as the member of the
	watchdog cluster definition as long as it is configured in the
	configuration file.
	All the majority rule computations for identifying the existence
	of a quorum and resolving the consensus are made based on the
	number of watchdog nodes that makes up the watchdog cluster.
  </para>

  <para>
	<productname>Pgpool-II</productname> <emphasis>V4.3</emphasis> enables
	dynamic cluster definition by introducing the concept of
	<emphasis>Member</emphasis> and <emphasis>Nonmember</emphasis>.
	If the node's membership gets revoked from the watchdog cluster,
	then the cluster re-calibrate itself dynamically to adjust all
	subsequent majority rule computations.
	</para>
	<para>
	All majority rule computations are done based on the number of
	member watchdog nodes instead of total number of configured nodes.
  </para>

  <para>
	For example: In a five node cluster (<filename>pgpool.conf</filename> has five
	watchdog nodes defined) at-least three nodes need to be alive to make the quorum.
	With the dynamic cluster membership mechanism the cluster can re-adjust
	itself to only count the <emphasis>MEMBER</emphasis> nodes
	(Member node doesn't necessarily need to be alive).
	That means effectively a single alive node
	can also fulfill the quorum requirements (depending on the membership criteria settings)
	if at some point in time the cluster only has one or two member nodes.
  </para>
  <para>
	<caution>
		<para>
		Using the dynamic cluster membership has an associated risk of causing a split-brain.
		So it is strongly recommended to carefully review if the setup requires the dynamic cluster
		membership and consider using conservative values for related settings.
		</para>
	</caution>
  </para>
  <para>
  These settings configures when the node is marked as Nonmember.
  Leaving all these settings to default values retains the
  pre <emphasis>V4.3</emphasis> behaviour.
  </para>

  <variablelist>

   <varlistentry id="guc-wd-remove-shutdown-nodes" xreflabel="wd_remove_shutdown_nodes">
    <term><varname>wd_remove_shutdown_nodes</varname> (<type>boolean</type>)
     <indexterm>
      <primary><varname>wd_remove_shutdown_nodes</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
	 When enabled, the <literal>SHUTDOWN</literal> nodes are immediately marked as Nonmember
	 and removed from the cluster. If the previously shutdown node starts again,
	 it gets added to cluster automatically.
     </para>
	 <para> Default is off. </para>
	</listitem>
   </varlistentry>


   <varlistentry id="guc-wd-lost-node-removal-timeout" xreflabel="wd_lost_node_removal_timeout">
    <term><varname>wd_lost_node_removal_timeout</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>wd_lost_node_removal_timeout</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Timeout in seconds to mark the <literal>LOST</literal> watchdog node as
	  Nonmember and remove from the cluster.
	  When LOST node re-connects to the cluster, its cluster membership is restored.
     </para>
	 <para>
	 Setting the timeout to <literal>0</literal> disables the removal
	 of LOST nodes from cluster.
	 </para>
	 <para> Default is 0. </para>

	</listitem>
   </varlistentry>

   <varlistentry id="guc-wd-no-show-node-removal-timeout" xreflabel="wd_no_show_node_removal_timeout">
    <term><varname>wd_no_show_node_removal_timeout</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>wd_no_show_node_removal_timeout</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Timeout in seconds to mark the node as Nonmember if it doesn't show up
	  at cluster initialisation. Nonmember node becomes the cluster Member as
	  soon as it starts up and connects to the cluster.
	 </para>
	 <para>
	 Setting the timeout to <literal>0</literal> disables the removal
	 of <literal>NO-SHOW</literal> nodes from cluster.
	 </para>
	 <para> Default is 0. </para>

	</listitem>
  </varlistentry>

  </variablelist>
 </sect2>

 <sect2 id="config-watchdog-lifecheck">
  <title>Life checking <productname>Pgpool-II</productname> </title>

  <para>
   Watchdog checks pgpool-II status periodically. This is called "life check".
  </para>

  <variablelist>

   <varlistentry id="guc-wd-lifecheck-method" xreflabel="wd_lifecheck_method">
    <term><varname>wd_lifecheck_method</varname> (<type>enum</type>)
     <indexterm>
      <primary><varname>wd_lifecheck_method</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the method of life check. This can be either of <literal>heartbeat</literal> (default),
      <literal>query</literal> or <literal>external</literal>.
     </para>
     <para>
      <literal>heartbeat</literal>: In this mode, watchdog sends the heartbeat signals (<acronym>UDP</acronym> packets)
      periodically to other <productname>Pgpool-II</productname>. Similarly watchdog also receives the signals
      from other <productname>Pgpool-II</productname> .
      If there are no signal for a certain period, watchdog regards is as failure
      of the <productname>Pgpool-II</productname> .
     </para>
     <para>
      <literal>query</literal>: In this mode, watchdog sends the monitoring queries
      to other <productname>Pgpool-II</productname> and checks the response.
      When installation location between <productname>Pgpool-II</productname>
      servers is far, <literal>query</literal> may be useful.
      <caution>
       <para>
        In query mode, you need to set <xref linkend="guc-num-init-children">
	 large enough if you plan to use watchdog.
	 This is because the watchdog process connects to
	 <productname>Pgpool-II</productname> as a client.
       </para>
      </caution>
     </para>
     <para>
      <literal>external</literal>: This mode disables the built
      in lifecheck of <productname>Pgpool-II</productname> watchdog
      and relies on external system to provide node health checking
      of local and remote watchdog nodes.
     </para>

     <para>
      <literal>external</literal> mode is not available in versions prior to
      <productname>Pgpool-II</productname> <emphasis>V3.5</emphasis>.
     </para>

     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-monitoring-interfaces-list" xreflabel="wd_monitoring_interfaces_list">
    <term><varname>wd_monitoring_interfaces_list</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>wd_monitoring_interfaces_list</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specify a comma separated list of network device names, to be monitored by the watchdog process
      for the network link state. If all network interfaces in the list becomes inactive
      (disabled or cable unplugged), the watchdog will consider it as a complete network failure
      and the <productname>Pgpool-II</productname> node will commit the suicide.
      Specifying an <literal>''</literal>(empty) list disables the network interface monitoring.
      Setting it to <literal>'any'</literal> enables the monitoring on all available network interfaces
      except the loopback. Default is <literal>''</literal> empty list (monitoring disabled).
     </para>

     <para>
      <varname>wd_monitoring_interfaces_list</varname> is not available in versions prior to
      <productname>Pgpool-II</productname> <emphasis>V3.5</emphasis>.
     </para>

     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-interval" xreflabel="wd_interval">
    <term><varname>wd_interval</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>wd_interval</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the interval between life checks of <productname>Pgpool-II</productname>
      in seconds. (A number greater than or equal to 1) Default is 10.
     </para>

     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-priority" xreflabel="wd_priority">
    <term><varname>wd_priority</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>wd_priority</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      This parameter can be used to elevate the local watchdog node priority in the elections
      to select leader watchdog node.
      The node with the higher <varname>wd_priority</varname> value will get selected
      as leader watchdog node when cluster will be electing its new leader node
      in the event of old leader watchdog node failure.
      <varname>wd_priority</varname> is also valid at the time of cluster startup.
      When some watchdog nodes start up at same time,a node with the higher <varname>wd_priority</varname>
      value is selected as a leader node.
      So we should start watchdog nodes in order of <varname>wd_priority</varname> priority to prevent
      unintended nodes from being selected as leader.
      If <varname>wd_priority</varname> of each nodes has the same value,
      leader node will be decided on base of starting time of watchdog.
     </para>
     <para>
      <varname>wd_priority</varname> is not available in versions prior to
      <productname>Pgpool-II</productname> <emphasis>V3.5</emphasis>.
     </para>

     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-ipc-socket-dir" xreflabel="wd_ipc_socket_dir">
    <term><varname>wd_ipc_socket_dir</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>wd_ipc_socket_dir</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      The directory where the <acronym>UNIX</acronym> domain socket
      accepting <productname>Pgpool-II</productname>
      watchdog <acronym>IPC</acronym> connections will be created.
      Default is <literal>'/tmp'</literal>.
      Be aware that this socket might be deleted by a cron job.
      We recommend to set this value to <literal>'/var/run'</literal> or such directory.
     </para>
     <para>
      <varname>wd_ipc_socket_dir</varname> is not available in versions prior to
      <productname>Pgpool-II</productname> <emphasis>V3.5</emphasis>.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

  </variablelist>
 </sect2>

 <sect2 id="config-watchdog-lifecheck-heartbeat">
  <title>Lifecheck Heartbeat mode configuration</title>
  <variablelist>
   <varlistentry id="guc-heartbeat-hostname" xreflabel="heartbeat_hostname">
    <term><varname>heartbeat_hostnameX</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>heartbeat_hostnameX</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the <acronym>IP (IPv4 or IPv6)</acronym> address or <acronym>hostname</acronym>
	  for sending and receiving the heartbeat signals.
      The number at the end of the parameter name is referred
      as "pgpool node id", and it starts from 0 (e.g. heartbeat_hostname0).
	  You can specify multiple <acronym>IP</acronym> address or <acronym>hostname</acronym>
      by separating them using semicolon (;).
     </para>
     <para>
      <varname>heartbeat_hostnameX</varname> is only applicable if the
      <xref linkend="guc-wd-lifecheck-method"> is set to <literal>'heartbeat'</literal>
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-heartbeat-listen-addresses" xreflabel="wd_heartbeat_listen_addresses">
    <term><varname>wd_heartbeat_listen_addresses</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>wd_heartbeat_listen_addresses</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the <acronym>IP (IPv4 or IPv6)</acronym> address or <acronym>hostname</acronym>
	    which heartbeat process will listen on.
      Default is <literal>''</literal> (empty).
	    You can specify multiple <acronym>IP</acronym> address or <acronym>hostname</acronym>
      by separating them using semicolon (;).
      If a value other than the default value is set,
      the value of heartbeat_hostnameX of the local node will be ignored and a socket
      that listens on the address specified in wd_heartbeat_listen_addresses will be created.
      For <varname>wd_heartbeat_listen_addresses</varname>, specifying <literal>*</literal> will listen on all addresses.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-heartbeat-port" xreflabel="heartbeat_port">
    <term><varname>heartbeat_portX</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>heartbeat_portX</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the port number for sending and receiving the heartbeat signals.
      Specify only one port number here. Default is 9694.
      The number at the end of the parameter name is referred
      as "pgpool node id", and it starts from 0 (e.g. heartbeat_port0).
     </para>
     <para>
      <varname>heartbeat_portX</varname> is only applicable if the
      <xref linkend="guc-wd-lifecheck-method"> is set to <literal>'heartbeat'</literal>
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-heartbeat-listen-port" xreflabel="wd_heartbeat_listen_port">
    <term><varname>wd_heartbeat_listen_port</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>wd_heartbeat_listen_port</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the port number which heartbeat process will listen on.
      Specify only one port number here. Default is 0.
      If a value other than the default value is set,
      the value of heartbeat_portX of the local node will be ignored and a socket
      that listens on the port specified in wd_heartbeat_listen_port will be created.
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-heartbeat-device" xreflabel="heartbeat_device">
    <term><varname>heartbeat_deviceX</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>heartbeat_deviceX</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the network device name for sending and receiving the heartbeat signals.
      The number at the end of the parameter name is referred
      as "pgpool node id", and it starts from 0 (e.g. heartbeat_device0).
	  You can specify multiple network devices by separating them using semicolon (;).
     </para>
     <para>
      <varname>heartbeat_deviceX</varname> is only applicable if
      <productname>Pgpool-II</productname> is started with root
      privilege. If not, leave it as an empty string ('').
     </para>
     <para>
      <varname>heartbeat_deviceX</varname> is only applicable if the
      <xref linkend="guc-wd-lifecheck-method"> is set to <literal>'heartbeat'</literal>
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
     <example id="example-heartbeat-1">
      <title>Heartbeat configuration</title>
      <para>
       If you have 3 pgpool nodes with hostname server1, server2 and server3,
       you can configure <xref linkend="guc-heartbeat-hostname">,
       <xref linkend="guc-heartbeat-port"> and <xref linkend="guc-heartbeat-device"> like below:
	<programlisting>
     heartbeat_hostname0 = 'server1'
     heartbeat_port0 = 9694
     heartbeat_device0 = ''

     heartbeat_hostname1 = 'server2'
     heartbeat_port1 = 9694
     heartbeat_device1 = ''

     heartbeat_hostname2 = 'server3'
     heartbeat_port2 = 9694
     heartbeat_device2 = ''
	</programlisting>
      </para>
     </example>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-heartbeat-keepalive" xreflabel="wd_heartbeat_keepalive">
    <term><varname>wd_heartbeat_keepalive</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>wd_heartbeat_keepalive</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the interval time in seconds between sending the heartbeat signals.
      Default is 2.
      <varname>wd_heartbeat_keepalive</varname> is only applicable if the
      <xref linkend="guc-wd-lifecheck-method"> is set to <literal>'heartbeat'</literal>
     </para>

     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-heartbeat-deadtime" xreflabel="wd_heartbeat_deadtime">
    <term><varname>wd_heartbeat_deadtime</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>wd_heartbeat_deadtime</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the time in seconds before marking the remote watchdog node as failed/dead node,
      if no heartbeat signal is received within that time.
      Default is <literal>30</literal>
      <varname>wd_heartbeat_deadtime</varname> is only applicable if the
      <xref linkend="guc-wd-lifecheck-method"> is set to <literal>'heartbeat'</literal>
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect2>

 <sect2 id="config-watchdog-lifecheck-query">
  <title>Lifecheck Query mode configuration</title>
  <variablelist>

   <varlistentry id="guc-wd-life-point" xreflabel="wd_life_point">
    <term><varname>wd_life_point</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>wd_life_point</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the number of times to retry a failed life check of pgpool-II.
      Valid value could be a number greater than or equal to 1.
      Default is 3.
     </para>
     <para>
      <varname>wd_life_point</varname> is only applicable if the
      <xref linkend="guc-wd-lifecheck-method"> is set to <literal>'query'</literal>
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-lifecheck-query" xreflabel="wd_lifecheck_query">
    <term><varname>wd_lifecheck_query</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>wd_lifecheck_query</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the query to use for the life check of remote <productname>Pgpool-II</productname>.
      Default is <literal>"SELECT 1"</literal>.
     </para>
     <para>
      <varname>wd_lifecheck_query</varname> is only applicable if the
      <xref linkend="guc-wd-lifecheck-method"> is set to <literal>'query'</literal>
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-lifecheck-dbname" xreflabel="wd_lifecheck_dbname">
    <term><varname>wd_lifecheck_dbname</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>wd_lifecheck_dbname</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the database name for the connection used for the
      life check of remote <productname>Pgpool-II</productname>.
      Default is <literal>"template1"</literal>.
     </para>
     <para>
      <varname>wd_lifecheck_dbname</varname> is only applicable if the
      <xref linkend="guc-wd-lifecheck-method"> is set to <literal>'query'</literal>
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-lifecheck-user" xreflabel="wd_lifecheck_user">
    <term><varname>wd_lifecheck_user</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>wd_lifecheck_user</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the user name for the connection used for the life
      check of remote <productname>Pgpool-II</productname>.
      Default is <literal>''</literal>(empty).
     </para>
     <para>
      <varname>wd_lifecheck_user</varname> is only applicable if the
      <xref linkend="guc-wd-lifecheck-method"> is set to <literal>'query'</literal>
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="guc-wd-lifecheck-password" xreflabel="wd_lifecheck_password">
    <term><varname>wd_lifecheck_password</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>wd_lifecheck_password</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the password for the user used for the life check of remote <productname>Pgpool-II</productname>.
     </para>
     <para>
      If <varname>wd_lifecheck_password</varname> is left blank <productname>Pgpool-II</productname>
      will first try to get the password for <xref linkend="guc-wd-lifecheck-user"> from
       <xref linkend="guc-pool-passwd"> file before using the empty password.
     </para>
     <para>
      You can also specify AES256-CBC encrypted password in <varname>wd_lifecheck_password</varname> field.
      To specify the <literal>AES</literal> encrypted password, password string must be prefixed with
      <literal>AES</literal> after encrypting (using <literal>aes-256-cbc</literal> algorithm) and
      encoding to <literal>base64</literal>.
     </para>
     <para>
      To specify the unencrypted clear text password, prefix the password string with
      <literal>TEXT</literal>. For example if you want to set <literal>mypass</literal> as
      a password, you should specify <literal>TEXTmypass</literal> in the password field.
      In the absence of a valid prefix, <productname>Pgpool-II</productname> will considered
      the string as a plain text password.
     </para>
     <para>
      You can also use <xref linkend="PG-ENC"> utility to create the correctly formatted
       <literal>AES</literal> encrypted password strings.
       <note>
	<para>
	 <productname>Pgpool-II</productname> will require a valid decryption key at the
	 startup to use the encrypted passwords.
	 see <xref linkend="auth-aes-decryption-key"> for more details on providing the
	  decryption key to <productname>Pgpool-II</productname>
	</para>
       </note>
     </para>
     <para>
      <varname>wd_lifecheck_password</varname> is only applicable if the
      <xref linkend="guc-wd-lifecheck-method"> is set to <literal>'query'</literal>
     </para>
     <para>
      This parameter can only be set at server start.
     </para>
     <para>
      Default is <literal>''</literal>(empty).
     </para>
    </listitem>
   </varlistentry>

  </variablelist>
 </sect2>
</sect1>
