1<sect1 id="configuration-file-service-commands" xreflabel="service command settings">
2  <title>Service command settings</title>
3
4  <indexterm>
5    <primary>repmgr.conf</primary>
6    <secondary>service command settings</secondary>
7  </indexterm>
8  <indexterm>
9    <primary>service command settings</primary>
10    <secondary>configuration in repmgr.conf</secondary>
11  </indexterm>
12
13  <para>
14    In some circumstances, &repmgr; (and &repmgrd;) need to
15    be able to stop, start or restart PostgreSQL. &repmgr; commands which need to do this
16    include <link linkend="repmgr-standby-follow"><command>repmgr standby follow</command></link>,
17    <link linkend="repmgr-standby-switchover"><command>repmgr standby switchover</command></link> and
18    <link linkend="repmgr-node-rejoin"><command>repmgr node rejoin</command></link>.
19  </para>
20  <para>
21    By default, &repmgr; will use PostgreSQL's <command>pg_ctl</command> utility to control the PostgreSQL
22    server. However this can lead to various problems, particularly when PostgreSQL has been
23    installed from packages, and especially so if <application>systemd</application> is in use.
24  </para>
25
26
27  <note>
28    <para>
29      If using <application>systemd</application>, ensure you have <varname>RemoveIPC</varname> set to <literal>off</literal>.
30      See the <ulink url="https://wiki.postgresql.org/wiki/Systemd">systemd</ulink>
31      entry in the <ulink url="https://wiki.postgresql.org/wiki/Main_Page">PostgreSQL wiki</ulink> for details.
32    </para>
33  </note>
34
35
36  <para>
37    With this in mind, we recommend to <emphasis>always</emphasis> configure &repmgr; to use the
38    available system service commands.
39  </para>
40
41  <para>
42    To do this, specify the appropriate command for each action
43    in <filename>repmgr.conf</filename> using the following configuration
44    parameters:
45    <programlisting>
46    service_start_command
47    service_stop_command
48    service_restart_command
49    service_reload_command</programlisting>
50  </para>
51
52  <note>
53    <para>
54      &repmgr; will not apply <option>pg_bindir</option> when executing any of these commands;
55      these can be user-defined scripts so must always be specified with the full path.
56    </para>
57  </note>
58
59  <note>
60    <para>
61      It's also possible to specify a <varname>service_promote_command</varname>.
62      This is intended for systems which provide a package-level promote command,
63      such as Debian's <application>pg_ctlcluster</application>, to promote the
64      PostgreSQL from standby to primary.
65    </para>
66    <para>
67      If your packaging system does not provide such a command, it can be left empty,
68      and &repmgr; will generate the appropriate `pg_ctl ... promote` command.
69    </para>
70    <para>
71      Do not confuse this with <varname>promote_command</varname>, which is used
72      by &repmgrd; to execute <xref linkend="repmgr-standby-promote"/>.
73    </para>
74  </note>
75
76  <para>
77    To confirm which command &repmgr; will execute for each action, use
78    <command><link linkend="repmgr-node-service">repmgr node service --list-actions --action=...</link></command>, e.g.:
79    <programlisting>
80      repmgr -f /etc/repmgr.conf node service --list-actions --action=stop
81      repmgr -f /etc/repmgr.conf node service --list-actions --action=start
82      repmgr -f /etc/repmgr.conf node service --list-actions --action=restart
83      repmgr -f /etc/repmgr.conf node service --list-actions --action=reload</programlisting>
84  </para>
85
86  <para>
87     These commands will be executed by the system user which &repmgr; runs as (usually <literal>postgres</literal>)
88     and will probably require passwordless sudo access to be able to execute the command.
89  </para>
90  <para>
91    For example, using <application>systemd</application> on CentOS 7, the service commands can be
92    set as follows:
93    <programlisting>
94      service_start_command   = 'sudo systemctl start postgresql-9.6'
95      service_stop_command    = 'sudo systemctl stop postgresql-9.6'
96      service_restart_command = 'sudo systemctl restart postgresql-9.6'
97      service_reload_command  = 'sudo systemctl reload postgresql-9.6'</programlisting>
98    and <filename>/etc/sudoers</filename> should be set as follows:
99    <programlisting>
100      Defaults:postgres !requiretty
101      postgres ALL = NOPASSWD: /usr/bin/systemctl stop postgresql-9.6, \
102        /usr/bin/systemctl start postgresql-9.6, \
103        /usr/bin/systemctl restart postgresql-9.6, \
104        /usr/bin/systemctl reload postgresql-9.6</programlisting>
105  </para>
106
107  <important>
108    <indexterm>
109      <primary>pg_ctlcluster</primary>
110      <secondary>service command settings</secondary>
111    </indexterm>
112    <para>
113      Debian/Ubuntu users: instead of calling <command>sudo systemctl</command> directly, use
114      <command>sudo pg_ctlcluster</command>, e.g.:
115    <programlisting>
116      service_start_command   = 'sudo pg_ctlcluster 9.6 main start'
117      service_stop_command    = 'sudo pg_ctlcluster 9.6 main stop'
118      service_restart_command = 'sudo pg_ctlcluster 9.6 main restart'
119      service_reload_command  = 'sudo pg_ctlcluster 9.6 main reload'</programlisting>
120      and set <filename>/etc/sudoers</filename> accordingly.
121    </para>
122    <para>
123      While <command>pg_ctlcluster</command> will work when executed as user <literal>postgres</literal>,
124      it's strongly recommended to use <command>sudo pg_ctlcluster</command> on <application>systemd</application>
125      systems, to ensure <application>systemd</application> has a correct picture of
126      the PostgreSQL application state.
127    </para>
128
129  </important>
130
131</sect1>
132