From 8773543e1026a8fbff856a6e0653a41e8e0d51e5 Mon Sep 17 00:00:00 2001
From: Ian Barwick <ian@2ndquadrant.com>
Date: Mon, 11 Feb 2019 10:55:10 +0900
Subject: [PATCH] doc: update "daemon (start|stop)" documentation

Clarify various aspects related to configuration.
---
 doc/repmgr-daemon-start.sgml   | 60 +++++++++++++++++++++++++---------
 doc/repmgr-daemon-stop.sgml    | 47 +++++++++++++++++++++++++-
 doc/repmgrd-configuration.sgml | 38 ++++++++++++++++++++-
 3 files changed, 127 insertions(+), 18 deletions(-)

diff --git a/doc/repmgr-daemon-start.sgml b/doc/repmgr-daemon-start.sgml
index 17371f0f..03013818 100644
--- a/doc/repmgr-daemon-start.sgml
+++ b/doc/repmgr-daemon-start.sgml
@@ -28,29 +28,18 @@
       started. This behaviour can be overridden by specifying a diffent value using the <option>--wait</option>
       option, or disabled altogether with the <option>--no-wait</option> option.
     </para>
-  </refsect1>
-
-  <refsect1>
-    <title>Configuration</title>
-    <para>
-      <command>repmgr daemon start</command> will execute the command defined by the
-      <varname>repmgrd_service_start_command</varname> parameter in <filename>repmgr.conf</filename>.
-      This must be set to a shell command which will start <application>repmgrd</application>;
-      if &repmgr; was installed from a package, this will be the service command defined by the
-      package. For more details see <link linkend="appendix-packages">Appendix: &repmgr; package details</link>.
-    </para>
 
     <important>
       <para>
-        If &repmgr; was installed from a system package, and you do not configure
-        <varname>repmgrd_service_start_command</varname> to an appropriate service command, this may
-        result in the system becoming confused about the state of the <application>repmgrd</application>
-        service; this is particularly the case with <literal>systemd</literal>.
+        The <filename>repmgr.conf</filename> parameter <varname>repmgrd_service_start_command</varname>
+        must be set for <command>repmgr daemon start</command> to work; see section
+        <xref linkend="repmgr-daemon-start-configuration"> for details.
       </para>
     </important>
-
   </refsect1>
 
+
+
   <refsect1>
 
     <title>Options</title>
@@ -100,6 +89,45 @@
     </variablelist>
   </refsect1>
 
+  <refsect1 id="repmgr-daemon-start-configuration" xreflabel="repmgr daemon start configuration">
+    <title>Configuration file settings</title>
+    <para>
+     The following parameter in <filename>repmgr.conf</filename> is relevant
+     to <command>repmgr daemon start</command>:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <indexterm>
+          <primary>repmgrd_service_start_command</primary>
+          <secondary>with &quot;repmgr daemon start&quot;</secondary>
+        </indexterm>
+
+        <term><option>repmgrd_service_start_command</option></term>
+        <listitem>
+          <para>
+            <command>repmgr daemon start</command> will execute the command defined by the
+            <varname>repmgrd_service_start_command</varname> parameter in <filename>repmgr.conf</filename>.
+            This must be set to a shell command which will start <application>repmgrd</application>;
+            if &repmgr; was installed from a package, this will be the service command defined by the
+            package. For more details see <link linkend="appendix-packages">Appendix: &repmgr; package details</link>.
+          </para>
+          <important>
+            <para>
+              If &repmgr; was installed from a system package, and you do not configure
+              <varname>repmgrd_service_start_command</varname> to an appropriate service command, this may
+              result in the system becoming confused about the state of the <application>repmgrd</application>
+              service; this is particularly the case with <literal>systemd</literal>.
+            </para>
+          </important>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+  </refsect1>
+
+
   <refsect1>
     <title>Exit codes</title>
     <para>
diff --git a/doc/repmgr-daemon-stop.sgml b/doc/repmgr-daemon-stop.sgml
index 5c56ed39..12abca20 100644
--- a/doc/repmgr-daemon-stop.sgml
+++ b/doc/repmgr-daemon-stop.sgml
@@ -36,6 +36,13 @@
       </para>
     </note>
 
+   <important>
+      <para>
+        The <filename>repmgr.conf</filename> parameter <varname>repmgrd_service_stop_command</varname>
+        must be set for <command>repmgr daemon stop</command> to work; see section
+        <xref linkend="repmgr-daemon-stop-configuration"> for details.
+      </para>
+    </important>
   </refsect1>
 
   <refsect1>
@@ -107,6 +114,44 @@
     </variablelist>
   </refsect1>
 
+  <refsect1 id="repmgr-daemon-stop-configuration" xreflabel="repmgr daemon stop configuration">
+    <title>Configuration file settings</title>
+    <para>
+     The following parameter in <filename>repmgr.conf</filename> is relevant
+     to <command>repmgr daemon stop</command>:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <indexterm>
+          <primary>repmgrd_service_stop_command</primary>
+          <secondary>with &quot;repmgr daemon stop&quot;</secondary>
+        </indexterm>
+
+        <term><option>repmgrd_service_stop_command</option></term>
+        <listitem>
+          <para>
+            <command>repmgr daemon stop</command> will execute the command defined by the
+            <varname>repmgrd_service_stop_command</varname> parameter in <filename>repmgr.conf</filename>.
+            This must be set to a shell command which will stop <application>repmgrd</application>;
+            if &repmgr; was installed from a package, this will be the service command defined by the
+            package. For more details see <link linkend="appendix-packages">Appendix: &repmgr; package details</link>.
+          </para>
+          <important>
+            <para>
+              If &repmgr; was installed from a system package, and you do not configure
+              <varname>repmgrd_service_stop_command</varname> to an appropriate service command, this may
+              result in the system becoming confused about the state of the <application>repmgrd</application>
+              service; this is particularly the case with <literal>systemd</literal>.
+            </para>
+          </important>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+  </refsect1>
+
   <refsect1>
     <title>Exit codes</title>
     <para>
@@ -148,7 +193,7 @@
   <refsect1>
     <title>See also</title>
     <para>
-      <xref linkend="repmgr-daemon-start">, <xref linkend="repmgr-daemon-status">
+      <xref linkend="repmgr-daemon-start">, <xref linkend="repmgr-daemon-status">, <xref linkend="repmgrd-daemon">
     </para>
   </refsect1>
 
diff --git a/doc/repmgrd-configuration.sgml b/doc/repmgrd-configuration.sgml
index b911e92b..993c0bc5 100644
--- a/doc/repmgrd-configuration.sgml
+++ b/doc/repmgrd-configuration.sgml
@@ -103,7 +103,7 @@
       </para>
     </sect2>
 
-    <sect2 id="repmgrd-service-configuration">
+    <sect2 id="postgresql-service-configuration">
       <indexterm>
         <primary>repmgrd</primary>
         <secondary>PostgreSQL service configuration</secondary>
@@ -126,6 +126,42 @@
       </para>
     </sect2>
 
+    <sect2 id="repmgrd-service-configuration">
+      <indexterm>
+        <primary>repmgrd</primary>
+        <secondary>repmgrd service configuration</secondary>
+      </indexterm>
+      <title>repmgrd service configuration</title>
+      <para>
+        If you are intending to use the <link linkend="repmgr-daemon-start"><command>repmgr daemon start</command></link>
+        and <link linkend="repmgr-daemon-stop"><command>repmgr daemon stop</command></link> commands, the following
+        parameters <emphasis>must</emphasis> be set in <filename>repmgr.conf</filename>:
+        <itemizedlist spacing="compact" mark="bullet">
+
+          <listitem>
+            <simpara><varname>repmgrd_service_start_command</varname></simpara>
+          </listitem>
+
+          <listitem>
+            <simpara><varname>repmgrd_service_stop_command</varname></simpara>
+          </listitem>
+
+        </itemizedlist>
+
+      </para>
+      <para>
+        Example (for &repmgr; with PostgreSQL 11 on CentOS 7):
+        <programlisting>
+repmgrd_service_start_command='sudo systemctl repmgr11 start'
+repmgrd_service_stop_command='sudo systemctl repmgr11 stop'
+</programlisting>
+      </para>
+      <para>
+        For more details see the reference page for each command.
+      </para>
+    </sect2>
+
+
     <sect2 id="repmgrd-monitoring-configuration" xreflabel="repmgrd monitoring configuration">
       <indexterm>
         <primary>repmgrd</primary>