doc: additional details about repmgrd usage in Debian/Ubuntu

doc/appendix-packages.sgml

@@ -229,7 +229,7 @@
     <title>Debian/Ubuntu Packages</title>
     <indexterm>
       <primary>packages</primary>
-      <secondary>Debian/Ubuntupackages</secondary>
+      <secondary>Debian/Ubuntu packages</secondary>
     </indexterm>
     <para>
       &repmgr; <literal>.deb</literal> packages are provided via the
@@ -268,10 +268,14 @@
       <title>Debian/Ubuntu package details</title>
 
       <para>
-        The two tables below list relevant information, paths, commands etc. for the &repmgr; packages on
+        The table below lists relevant information, paths, commands etc. for the &repmgr; packages on
-        Debian 9.x ("Stretch") and Ubuntu 16.04 ("Xenial Xerus"). Substitute the appropriate PostgreSQL major
+        Debian 9.x ("Stretch"). Substitute the appropriate PostgreSQL major
         version number for your installation.
       </para>
+      <para>
+        See also <xref linkend="repmgrd-configuration-debian-ubuntu"> for some specifics related
+        to configuring the <application>repmgrd</application> daemon.
+      </para>
 
       <table id="debian-9-packages">
         <title>Debian 9.x packages</title>
@@ -315,8 +319,14 @@
             </row>
 
             <row>
-              <entry>repmgrd service command:</entry>
+              <entry>PostgreSQL service command:</entry>
               <entry><command>systemctl [start|stop|restart|reload] postgresql@10-main</command></entry>
+
+            </row>
+
+            <row>
+              <entry>repmgrd service command:</entry>
+              <entry><command>systemctl [start|stop|restart|reload] repmgrd</command></entry>
             </row>
 
             <row>
@@ -332,6 +342,19 @@
           </tbody>
         </tgroup>
       </table>
+      <note>
+        <para>
+          Instead of using the <application>systemd</application> service command directly,
+          it's recommended to execute <command>pg_ctlcluster</command> (as <literal>root</literal>,
+          either directly or via <command>sudo</command>), e.g.:
+          <programlisting>
+            <command>pg_ctlcluster 10 main [start|stop|restart|reload]</command></programlisting>
+        </para>
+        <para>
+          For pre-<application>systemd</application> systems, <command>pg_ctlcluster</command>
+          can be executed directly by the <literal>postgres</literal> user.
+        </para>
+      </note>
    </sect2>
 
   </sect1>

doc/configuration-service-commands.sgml

@@ -3,6 +3,10 @@
     <primary>repmgr.conf</primary>
     <secondary>service command settings</secondary>
   </indexterm>
+  <indexterm>
+    <primary>service command settings</primary>
+    <secondary>configuration in repmgr.conf</secondary>
+  </indexterm>
   <title>Service command settings</title>
 
   <para>

doc/install-packages.sgml

@@ -153,6 +153,12 @@
   Instructions can be found in the APT section of the PostgreSQL Wiki
   (<ulink url="https://wiki.postgresql.org/wiki/Apt">https://wiki.postgresql.org/wiki/Apt</ulink>).
   </para>
+  <para>
+    For more information on the package contents, including details of installation
+    paths and relevant <link linkend="configuration-service-commands">service commands</link>,
+    see the appendix section <xref linkend="packages-debian-ubuntu">.
+  </para>
+
  </sect2>
 
 </sect1>

doc/repmgrd-configuration.sgml

@@ -141,8 +141,93 @@
 
   </sect1>
 
- <sect1 id="repmgrd-connection-settings">
+  <sect1 id="repmgrd-daemon">
- <title>repmgrd connection settings</title>
+    <indexterm>
+      <primary>repmgrd</primary>
+      <secondary>starting and stopping</secondary>
+    </indexterm>
+    <title>repmgrd daemon</title>
+    <para>
+      If installed from a package, the <application>repmgrd</application> can be started
+      via the operating system's service command, e.g. in <application>systemd</application>
+      using <command>systemctl</command>.
+    </para>
+    <para>
+      See appendix <xref linkend="appendix-packages"> for details of service commands
+      for different distributions.
+    </para>
+    <para>
+      <application>repmgrd</application> can be started manually like this:
+      <programlisting>
+        repmgrd -f /etc/repmgr.conf --pid-file /tmp/repmgrd.pid --daemonize</programlisting>
+      and stopped with <command>kill `cat /tmp/repmgrd.pid`</command>. Adjust paths as appropriate.
+    </para>
+    <para>
+      To apply configuration file changes to a running <application>repmgrd</application>
+      daemon, execute the operating system's service reload command (for manually started
+      instances, execute <command>kill -HUP `cat /tmp/repmgrd.pid`</command>).
+      Note that only a subset of configuration file parameters can be changed on a
+      running <application>repmgrd</application> daemon.
+    </para>
+
+    <sect2 id="repmgrd-configuration-debian-ubuntu">
+      <indexterm>
+        <primary>repmgrd</primary>
+        <secondary>Debian/Ubuntu and daemon configuration</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>Debian/Ubuntu</primary>
+        <secondary>repmgrd daemon configuration</secondary>
+      </indexterm>
+
+      <title>repmgrd daemon configuration on Debian/Ubuntu</title>
+
+      <para>
+        If &repmgr; was installed from Debian/Ubuntu packages, additional configuration
+        is required before <application>repmgrd</application> is started as a daemon.
+      </para>
+      <para>
+        This is done via the file <filename>/etc/default/repmgrd</filename>, which by default
+        looks like this:
+        <programlisting>
+# default settings for repmgrd. This file is source by /bin/sh from
+# /etc/init.d/repmgrd
+
+# disable repmgrd by default so it won't get started upon installation
+# valid values: yes/no
+REPMGRD_ENABLED=no
+
+# configuration file (required)
+#REPMGRD_CONF="/path/to/repmgr.conf"
+
+# additional options
+#REPMGRD_OPTS=""
+
+# user to run repmgrd as
+#REPMGRD_USER=postgres
+
+# repmgrd binary
+#REPMGRD_BIN=/usr/bin/repmgrd
+
+# pid file
+#REPMGRD_PIDFILE=/var/run/repmgrd.pid</programlisting>
+      </para>
+      <para>
+        Set <varname>REPMGRD_ENABLED</varname> to <literal>yes</literal>, and <varname>REPMGRD_CONF</varname>
+        to the <filename>repmgr.conf</filename> file you are using.
+      </para>
+      <para>
+        If using <application>systemd</application>, you may need to execute <command>systemctl daemon-reload</command>.
+        Also, if you attempted to start <application>repmgrd</application> using <command>systemctl start repmgrd</command>,
+        you'll need to execute <command>systemctl stop repmgrd</command>. Because that's how <application>systemd</application>
+        rolls.
+      </para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="repmgrd-connection-settings">
+    <title>repmgrd connection settings</title>
  <para>
   In addition to the &repmgr; configuration settings, parameters in the
   <varname>conninfo</varname> string influence how &repmgr; makes a network connection to