From 82515a9733cad52ff2bebed8581d9139fc45a8f5 Mon Sep 17 00:00:00 2001
From: Ian Barwick <ian@2ndquadrant.com>
Date: Thu, 17 Sep 2020 15:44:56 +0900
Subject: [PATCH] doc: document new parameters for
 "failover_validation_command"

---
 HISTORY                            |  4 +++-
 doc/appendix-release-notes.xml     | 32 ++++++++++++++++++++++++++++++
 doc/repmgrd-automatic-failover.xml |  7 ++++---
 doc/repmgrd-configuration.xml      | 15 +++++++++++---
 4 files changed, 51 insertions(+), 7 deletions(-)

diff --git a/HISTORY b/HISTORY
index f5beb371..5aff447b 100644
--- a/HISTORY
+++ b/HISTORY
@@ -1,7 +1,9 @@
 5.2.0   2020-??-??
         repmgr: improve database connection failure error checking on the
           demotion candidate during "standby switchover" (Ian)
-        repmgr: add option --verify-backup to "standby clone"
+        repmgr: add option --verify-backup to "standby clone" (Ian)
+        repmgrd: add additional optional parameters to "failover_validation command"
+          (spaskalev; GitHub #651)
 
 5.1.0   2020-04-13
         repmgr: remove BDR 2.x support
diff --git a/doc/appendix-release-notes.xml b/doc/appendix-release-notes.xml
index 7c752f1f..95c97e2d 100644
--- a/doc/appendix-release-notes.xml
+++ b/doc/appendix-release-notes.xml
@@ -45,6 +45,38 @@
         </itemizedlist>
       </para>
     </sect2>
+    <sect2>
+      <title>repmgrd enhancements</title>
+      <para>
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              Following additional parameters can be provided to <varname>failover_validation_command</varname>:
+              <itemizedlist spacing="compact" mark="bullet">
+                <listitem>
+                  <simpara><literal>%n</literal>: node ID</simpara>
+                </listitem>
+                <listitem>
+                  <simpara><literal>%a</literal>: node name</simpara>
+                </listitem>
+                <listitem>
+                  <simpara><literal>%v</literal>: number of visible nodes</simpara>
+                </listitem>
+                <listitem>
+                  <simpara><literal>%u</literal>: number of shared upstream nodes</simpara>
+                </listitem>
+                <listitem>
+                  <simpara><literal>%t</literal>: total number of nodes</simpara>
+                </listitem>
+              </itemizedlist>
+
+            </para>
+          </listitem>
+        </itemizedlist>
+      </para>
+    </sect2>
+
   </sect1>
 
   <sect1 id="release-5.1.0">
diff --git a/doc/repmgrd-automatic-failover.xml b/doc/repmgrd-automatic-failover.xml
index b46f9902..d8308e8e 100644
--- a/doc/repmgrd-automatic-failover.xml
+++ b/doc/repmgrd-automatic-failover.xml
@@ -331,11 +331,12 @@
     To use this, <option>failover_validation_command</option> in <filename>repmgr.conf</filename>
     to a script executable by the <literal>postgres</literal> system user, e.g.:
     <programlisting>
-      failover_validation_command=/path/to/script.sh %n %a</programlisting>
+      failover_validation_command=/path/to/script.sh %n</programlisting>
   </para>
   <para>
-    The <literal>%n</literal> parameter will be replaced with the node ID, and the
-    <literal>%a</literal> parameter will be replaced by the node name when the script is executed.
+    The <literal>%n</literal> parameter will be replaced with the node ID when the script is
+    executed. A number of other parameters are also available, see section
+    &quot;<xref linkend="repmgrd-automatic-failover-configuration-optional"/>&quot; for details.
   </para>
   <para>
     This script must return an exit code of <literal>0</literal> to indicate the node should promote itself.
diff --git a/doc/repmgrd-configuration.xml b/doc/repmgrd-configuration.xml
index ddea8307..647a1f94 100644
--- a/doc/repmgrd-configuration.xml
+++ b/doc/repmgrd-configuration.xml
@@ -325,7 +325,7 @@
 
     </sect2>
 
-    <sect2 id="repmgrd-automatic-failover-configuration-optional">
+    <sect2 id="repmgrd-automatic-failover-configuration-optional" xreflabel="Optional configuration for automatic failover">
       <title>Optional configuration for automatic failover</title>
 
       <para>
@@ -370,8 +370,8 @@
               </para>
             </note>
             <para>
-              One or both of the following parameter placeholders
-			  should be provided, which will be replaced by repmgrd with the appropriate
+              One or more of the following parameter placeholders
+			  may be provided, which will be replaced by repmgrd with the appropriate
 	          value:
               <itemizedlist spacing="compact" mark="bullet">
                 <listitem>
@@ -380,6 +380,15 @@
                 <listitem>
                   <simpara><literal>%a</literal>: node name</simpara>
                 </listitem>
+                <listitem>
+                  <simpara><literal>%v</literal>: number of visible nodes</simpara>
+                </listitem>
+                <listitem>
+                  <simpara><literal>%u</literal>: number of shared upstream nodes</simpara>
+                </listitem>
+                <listitem>
+                  <simpara><literal>%t</literal>: total number of nodes</simpara>
+                </listitem>
               </itemizedlist>
             </para>
             <para>