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