1<chapter id="configuration" xreflabel="Configuration">
2  <title>repmgr configuration</title>
3
4  <sect1 id="configuration-prerequisites" xreflabel="Prerequisites for configuration">
5    <title>Prerequisites for configuration</title>
6
7    <indexterm>
8      <primary>configuration</primary>
9      <secondary>prerequisites</secondary>
10    </indexterm>
11
12    <indexterm>
13      <primary>configuration</primary>
14      <secondary>ssh</secondary>
15    </indexterm>
16
17    <para>
18     Following software must be installed on both servers:
19     <itemizedlist spacing="compact" mark="bullet">
20      <listitem>
21       <simpara><application>PostgreSQL</application></simpara>
22      </listitem>
23      <listitem>
24       <simpara>
25        <application>repmgr</application>
26       </simpara>
27      </listitem>
28     </itemizedlist>
29    </para>
30
31    <para>
32      At network level, connections between the PostgreSQL port (default: <literal>5432</literal>)
33      must be possible between all nodes.
34    </para>
35
36    <para>
37      Passwordless <command>SSH</command> connectivity between all servers in the replication cluster
38      is not required, but is necessary in the following cases:
39      <itemizedlist>
40        <listitem>
41          <simpara>if you need &repmgr; to copy configuration files from outside the PostgreSQL
42            data directory (as is the case with e.g. <link linkend="packages-debian-ubuntu">Debian packages</link>);
43            in this case <command>rsync</command> must also be installed on all servers.
44          </simpara>
45        </listitem>
46        <listitem>
47          <simpara>to perform <link linkend="performing-switchover">switchover operations</link></simpara>
48        </listitem>
49        <listitem>
50          <simpara>
51            when executing <command><link linkend="repmgr-cluster-matrix">repmgr cluster matrix</link></command>
52            and <command><link linkend="repmgr-cluster-crosscheck">repmgr cluster crosscheck</link></command>
53          </simpara>
54        </listitem>
55      </itemizedlist>
56    </para>
57
58    <tip>
59      <simpara>
60        Consider setting <varname>ConnectTimeout</varname> to a low value in your SSH configuration.
61        This will make it faster to detect any SSH connection errors.
62      </simpara>
63    </tip>
64
65  <sect2 id="configuration-postgresql" xreflabel="PostgreSQL configuration">
66      <title>PostgreSQL configuration for &repmgr;</title>
67
68    <indexterm>
69      <primary>configuration</primary>
70      <secondary>PostgreSQL</secondary>
71    </indexterm>
72
73    <indexterm>
74      <primary>PostgreSQL configuration</primary>
75    </indexterm>
76
77    <para>
78      The following PostgreSQL configuration parameters may need to be changed in order
79      for &repmgr; (and replication itself) to function correctly.
80    </para>
81    <variablelist>
82
83
84      <varlistentry>
85
86        <term><option>hot_standby</option></term>
87        <listitem>
88
89          <indexterm>
90            <primary>hot_standby</primary>
91            <secondary>PostgreSQL configuration</secondary>
92          </indexterm>
93
94          <para>
95            <option>hot_standby</option> must always be set to <literal>on</literal>, as &repmgr; needs
96            to be able to connect to each server it manages.
97          </para>
98          <para>
99            Note that <option>hot_standby</option> defaults to <literal>on</literal> from PostgreSQL 10
100            and later; in PostgreSQL 9.6 and earlier, the default was <literal>off</literal>.
101          </para>
102          <para>
103            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-HOT-STANDBY">hot_standby</ulink>.
104          </para>
105        </listitem>
106      </varlistentry>
107
108      <varlistentry>
109
110        <term><option>wal_level</option></term>
111
112        <listitem>
113
114          <indexterm>
115            <primary>wal_level</primary>
116            <secondary>PostgreSQL configuration</secondary>
117          </indexterm>
118
119          <para>
120            <option>wal_level</option> must be one of <option>replica</option> or <option>logical</option>
121            (PostgreSQL 9.5 and earlier: one of <option>hot_standby</option> or <option>logical</option>).
122          </para>
123          <para>
124            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</ulink>.
125          </para>
126        </listitem>
127      </varlistentry>
128
129      <varlistentry>
130
131        <term><option>max_wal_senders</option></term>
132
133        <listitem>
134
135          <indexterm>
136            <primary>max_wal_senders</primary>
137            <secondary>PostgreSQL configuration</secondary>
138          </indexterm>
139
140          <para>
141            <option>max_wal_senders</option> must be set to a value of <literal>2</literal> or greater.
142            In general you will need one WAL sender for each standby which will attach to the PostgreSQL
143            instance; additionally &repmgr; will require two free WAL senders in order to clone further
144            standbys.
145          </para>
146          <para>
147            <option>max_wal_senders</option> should be set to an appropriate value on all PostgreSQL
148            instances in the replication cluster which may potentially become a primary server or
149            (in cascading replication) the upstream server of a standby.
150          </para>
151         <para>
152            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</ulink>.
153          </para>
154          <note>
155            <para>
156              From <productname>PostgreSQL 12</productname>, <option>max_wal_senders</option>
157              <emphasis>must</emphasis> be set to the same or a higher value as the primary node
158              (at the time the node was cloned), otherwise the standby will refuse
159              to start (unless <option>hot_standby</option> is set to <literal>off</literal>, which
160              will prevent the node from accepting queries).
161            </para>
162          </note>
163
164        </listitem>
165      </varlistentry>
166
167      <varlistentry>
168
169        <term><option>max_replication_slots</option></term>
170
171        <listitem>
172
173          <indexterm>
174            <primary>max_replication_slots</primary>
175            <secondary>PostgreSQL configuration</secondary>
176          </indexterm>
177
178          <para>
179            If you are intending to use replication slots, <option>max_replication_slots</option>
180            must be set to a non-zero value.
181          </para>
182          <para>
183            <option>max_replication_slots</option> should be set to an appropriate value on all PostgreSQL
184            instances in the replication cluster which may potentially become a primary server or
185            (in cascading replication) the upstream server of a standby.
186          </para>
187          <para>
188            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-REPLICATION-SLOTS">max_replication_slots</ulink>.
189          </para>
190        </listitem>
191      </varlistentry>
192
193
194      <varlistentry>
195
196        <term><option>wal_log_hints</option></term>
197        <listitem>
198          <indexterm>
199            <primary>wal_log_hints</primary>
200            <secondary>PostgreSQL configuration</secondary>
201          </indexterm>
202
203
204          <para>If you are intending to use <application>pg_rewind</application>,
205            and the cluster was not initialised using data checksums, you may want to consider enabling
206            <option>wal_log_hints</option>.
207          </para>
208          <para>
209            For more details see <xref linkend="repmgr-node-rejoin-pg-rewind"/>.
210          </para>
211          <para>
212            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-WAL-LOG-HINTS">wal_log_hints</ulink>.
213          </para>
214        </listitem>
215      </varlistentry>
216
217      <varlistentry>
218
219        <term><option>archive_mode</option></term>
220
221        <listitem>
222
223          <indexterm>
224            <primary>archive_mode</primary>
225            <secondary>PostgreSQL configuration</secondary>
226          </indexterm>
227
228          <para>
229            We suggest setting <option>archive_mode</option> to <literal>on</literal> (and
230            <option>archive_command</option> to <literal>/bin/true</literal>; see below)
231            even if you are currently not planning to use WAL file archiving.
232          </para>
233          <para>
234            This will make it simpler to set up WAL file archiving if it is ever required,
235            as changes to <option>archive_mode</option> require a full PostgreSQL server
236            restart, while <option>archive_command</option> changes can be applied via a normal
237            configuration reload.
238          </para>
239          <para>
240            However, &repmgr; itself does not require WAL file archiving.
241          </para>
242          <para>
243            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-ARCHIVE-MODE">archive_mode</ulink>.
244          </para>
245        </listitem>
246      </varlistentry>
247
248      <varlistentry>
249
250        <term><option>archive_command</option></term>
251
252        <listitem>
253
254          <indexterm>
255            <primary>archive_command</primary>
256            <secondary>PostgreSQL configuration</secondary>
257          </indexterm>
258
259          <para>
260            If you have set  <option>archive_mode</option> to <literal>on</literal> but are not currently planning
261            to use WAL file archiving, set <option>archive_command</option> to a command which does nothing but returns
262            <literal>true</literal>, such as <command>/bin/true</command>. See above for details.
263          </para>
264          <para>
265            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</ulink>.
266          </para>
267        </listitem>
268      </varlistentry>
269
270
271      <varlistentry>
272
273        <term><option>wal_keep_segments</option> / <option>wal_keep_size</option></term>
274
275        <listitem>
276
277          <indexterm>
278            <primary>wal_keep_segments</primary>
279            <secondary>PostgreSQL configuration</secondary>
280          </indexterm>
281
282
283          <indexterm>
284            <primary>wal_keep_size</primary>
285            <secondary>PostgreSQL configuration</secondary>
286          </indexterm>
287
288          <para>
289            Normally there is no need to set <option>wal_keep_segments</option>
290            (PostgreSQL 13 and later: <varname>wal_keep_size</varname>; default: <literal>0</literal>),
291            as it is <emphasis>not</emphasis> a reliable way of ensuring that all required WAL
292            segments are available to standbys. Replication slots and/or an archiving solution
293            such as Barman are recommended to ensure standbys have a reliable
294            source of WAL segments at all times.
295          </para>
296          <para>
297            The only reason ever to set  <option>wal_keep_segments</option> / <option>wal_keep_size</option>
298            is you have you have configured <option>pg_basebackup_options</option>
299            in <filename>repmgr.conf</filename> to include the setting <literal>--wal-method=fetch</literal>
300            (PostgreSQL 9.6 and earlier: <literal>--xlog-method=fetch</literal>)
301            <emphasis>and</emphasis> you have <emphasis>not</emphasis> set <option>restore_command</option>
302            in <filename>repmgr.conf</filename> to fetch WAL files from a reliable source such as Barman,
303            in which case you'll need to set <option>wal_keep_segments</option>
304            to a sufficiently high number to ensure that all WAL files required by the standby
305            are retained. However we do not recommend WAL retention in this way.
306          </para>
307          <para>
308            PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-KEEP-SEGMENTS">wal_keep_segments</ulink>.
309            <!--
310             PostgreSQL documentation: <ulink url="https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-KEEP-SIZE">wal_keep_size</ulink>.
311              -->
312          </para>
313        </listitem>
314      </varlistentry>
315
316    </variablelist>
317    <para>
318      See also the <link linkend="quickstart-postgresql-configuration">PostgreSQL configuration</link> section in the
319      <link linkend="quickstart">Quick-start guide</link>.
320    </para>
321  </sect2>
322
323
324  </sect1>
325
326
327  &configuration-file;
328  &configuration-file-required-settings;
329  &configuration-file-optional-settings;
330  &configuration-file-log-settings;
331  &configuration-file-service-commands;
332  &configuration-permissions;
333  &configuration-password-management;
334
335</chapter>
336