1<refentry id="repmgr-standby-clone"> 2 <indexterm> 3 <primary>repmgr standby clone</primary> 4 <seealso>cloning</seealso> 5 </indexterm> 6 7 <refmeta> 8 <refentrytitle>repmgr standby clone</refentrytitle> 9 </refmeta> 10 11 <refnamediv> 12 <refname>repmgr standby clone</refname> 13 <refpurpose>clone a PostgreSQL standby node from another PostgreSQL node</refpurpose> 14 </refnamediv> 15 16 <refsect1> 17 <title>Description</title> 18 <para> 19 <command>repmgr standby clone</command> clones a PostgreSQL node from another 20 PostgreSQL node, typically the primary, but optionally from any other node in 21 the cluster or from Barman. It creates the replication configuration required 22 to attach the cloned node to the primary node (or another standby, if cascading replication 23 is in use). 24 </para> 25 <note> 26 <simpara> 27 <command>repmgr standby clone</command> does not start the standby, and after cloning 28 a standby, the command <command>repmgr standby register</command> must be executed to 29 notify &repmgr; of its existence. 30 </simpara> 31 </note> 32 33 </refsect1> 34 35 36 <refsect1 id="repmgr-standby-clone-config-file-copying" xreflabel="Copying configuration files"> 37 <title>Handling configuration files</title> 38 39 <para> 40 Note that by default, all configuration files in the source node's data 41 directory will be copied to the cloned node. Typically these will be 42 <filename>postgresql.conf</filename>, <filename>postgresql.auto.conf</filename>, 43 <filename>pg_hba.conf</filename> and <filename>pg_ident.conf</filename>. 44 These may require modification before the standby is started. 45 </para> 46 <para> 47 In some cases (e.g. on Debian or Ubuntu Linux installations), PostgreSQL's 48 configuration files are located outside of the data directory and will 49 not be copied by default. &repmgr; can copy these files, either to the same 50 location on the standby server (provided appropriate directory and file permissions 51 are available), or into the standby's data directory. This requires passwordless 52 SSH access to the primary server. Add the option <option>--copy-external-config-files</option> 53 to the <command>repmgr standby clone</command> command; by default files will be copied to 54 the same path as on the upstream server. Note that the user executing <command>repmgr</command> 55 must have write access to those directories. 56 </para> 57 <para> 58 To have the configuration files placed in the standby's data directory, specify 59 <literal>--copy-external-config-files=pgdata</literal>, but note that 60 any include directives in the copied files may need to be updated. 61 </para> 62 63 <note> 64 <para> 65 When executing <command>repmgr standby clone</command> with the 66 <option>--copy-external-config-files</option> aand <option>--dry-run</option> 67 options, &repmgr; will check the SSH connection to the source node, but 68 will not verify whether the files can actually be copied. 69 </para> 70 <para> 71 During the actual clone operation, a check will be made before the database itself 72 is cloned to determine whether the files can actually be copied; if any problems are 73 encountered, the clone operation will be aborted, enabling the user to fix 74 any issues before retrying the clone operation. 75 </para> 76 </note> 77 78 <tip> 79 <simpara> 80 For reliable configuration file management we recommend using a 81 configuration management tool such as Ansible, Chef, Puppet or Salt. 82 </simpara> 83 </tip> 84 85 </refsect1> 86 87 <refsect1 id="repmgr-standby-clone-recovery-conf"> 88 <title>Customising replication configuration</title> 89 <indexterm> 90 <primary>recovery.conf</primary> 91 <secondary>customising with "repmgr standby clone"</secondary> 92 </indexterm> 93 94 <indexterm> 95 <primary>replication configuration</primary> 96 <secondary>customising with "repmgr standby clone"</secondary> 97 </indexterm> 98 99 100 <para> 101 By default, &repmgr; will create a minimal replication configuration 102 containing following parameters: 103 </para> 104 105 <itemizedlist spacing="compact" mark="bullet"> 106 107 <listitem> 108 <simpara><varname>primary_conninfo</varname></simpara> 109 </listitem> 110 111 <listitem> 112 <simpara><varname>primary_slot_name</varname> (if replication slots in use)</simpara> 113 </listitem> 114 115 </itemizedlist> 116 117 <para> 118 For PostgreSQL 11 and earlier, these parameters will also be set: 119 </para> 120 121 <itemizedlist spacing="compact" mark="bullet"> 122 <listitem> 123 <simpara><varname>standby_mode</varname> (always <literal>'on'</literal>)</simpara> 124 </listitem> 125 126 <listitem> 127 <simpara><varname>recovery_target_timeline</varname> (always <literal>'latest'</literal>)</simpara> 128 </listitem> 129 </itemizedlist> 130 131 132 <para> 133 The following additional parameters can be specified in <filename>repmgr.conf</filename> 134 for inclusion in the replication configuration: 135 </para> 136 137 <itemizedlist spacing="compact" mark="bullet"> 138 139 <listitem> 140 <simpara><varname>restore_command</varname></simpara> 141 </listitem> 142 143 <listitem> 144 <simpara><varname>archive_cleanup_command</varname></simpara> 145 </listitem> 146 147 <listitem> 148 <simpara><varname>recovery_min_apply_delay</varname></simpara> 149 </listitem> 150 151 </itemizedlist> 152 153 <note> 154 <para> 155 We recommend using <ulink url="https://www.pgbarman.org/">Barman</ulink> to manage 156 WAL file archiving. For more details on combining &repmgr; and <application>Barman</application>, 157 in particular using <varname>restore_command</varname> to configure Barman as a backup source of 158 WAL files, see <xref linkend="cloning-from-barman"/>. 159 </para> 160 </note> 161 162 </refsect1> 163 164 <refsect1 id="repmgr-standby-clone-wal-management"> 165 <title>Managing WAL during the cloning process</title> 166 <para> 167 When initially cloning a standby, you will need to ensure 168 that all required WAL files remain available while the cloning is taking 169 place. To ensure this happens when using the default <command>pg_basebackup</command> method, 170 &repmgr; will set <command>pg_basebackup</command>'s <literal>--wal-method</literal> 171 parameter to <literal>stream</literal>, 172 which will ensure all WAL files generated during the cloning process are 173 streamed in parallel with the main backup. Note that this requires two 174 replication connections to be available (&repmgr; will verify sufficient 175 connections are available before attempting to clone, and this can be checked 176 before performing the clone using the <literal>--dry-run</literal> option). 177 </para> 178 <para> 179 To override this behaviour, in <filename>repmgr.conf</filename> set 180 <command>pg_basebackup</command>'s <literal>--wal-method</literal> 181 parameter to <literal>fetch</literal>: 182 <programlisting> 183 pg_basebackup_options='--wal-method=fetch'</programlisting> 184 185 and ensure that <literal>wal_keep_segments</literal> (PostgreSQL 13 and later: 186 <literal>wal_keep_size</literal>) is set to an appropriately high value. Note 187 however that this is not a particularly reliable way of ensuring sufficient 188 WAL is retained and is not recommended. 189 See the <ulink url="https://www.postgresql.org/docs/current/app-pgbasebackup.html"> 190 pg_basebackup</ulink> documentation for details. 191 </para> 192 193 <note> 194 <simpara> 195 If using PostgreSQL 9.6 or earlier, replace <literal>--wal-method</literal> 196 with <literal>--xlog-method</literal>. 197 </simpara> 198 </note> 199 </refsect1> 200 201 <refsect1 id="repmgr-standby-clone-wal-directory"> 202 203 <title>Placing WAL files into a different directory</title> 204 205 <para> 206 To ensure that WAL files are placed in a directory outside of the main data 207 directory (e.g. to keep them on a separate disk for performance reasons), 208 specify the location with <option>--waldir</option> 209 (PostgreSQL 9.6 and earlier: <option>--xlogdir</option>) in 210 the <filename>repmgr.conf</filename> parameter <option>pg_basebackup_options</option>, 211 e.g.: 212 <programlisting> 213pg_basebackup_options='--waldir=/path/to/wal-directory'</programlisting> 214 This setting will also be honored by &repmgr; when cloning from Barman 215 (&repmgr; 5.2 and later). 216 </para> 217 218 </refsect1> 219 220<!-- don't rename this id as it may be used in external links --> 221 <refsect1 id="repmgr-standby-create-recovery-conf"> 222 223 <title>Using a standby cloned by another method</title> 224 225 <indexterm> 226 <primary>replication configuration</primary> 227 <secondary>generating for a standby cloned by another method</secondary> 228 </indexterm> 229 230 <indexterm> 231 <primary>recovery.conf</primary> 232 <secondary>generating for a standby cloned by another method</secondary> 233 </indexterm> 234 235 <para> 236 &repmgr; supports standbys cloned by another method (e.g. using <application>barman</application>'s 237 <command><ulink url="https://docs.pgbarman.org/#recover">barman recover</ulink></command> command). 238 </para> 239 <para> 240 To integrate the standby as a &repmgr; node, once the standby has been cloned, 241 ensure the <filename>repmgr.conf</filename> 242 file is created for the node, and that it has been registered using 243 <command><link linkend="repmgr-standby-register">repmgr standby register</link></command>. 244 </para> 245 <tip> 246 <para> 247 To register a standby which is not running, execute 248 <link linkend="repmgr-standby-register">repmgr standby register --force</link> 249 and provide the connection details for the primary. 250 </para> 251 <para> 252 See <xref linkend="repmgr-standby-register-inactive-node"/> for more details. 253 </para> 254 </tip> 255 <para> 256 Then execute the command <command>repmgr standby clone --replication-conf-only</command>. 257 This will create the <filename>recovery.conf</filename> file needed to attach 258 the node to its upstream (in PostgreSQL 12 and later: append replication configuration 259 to <filename>postgresql.auto.conf</filename>), and will also create a replication slot on the 260 upstream node if required. 261 </para> 262 <para> 263 Note that the upstream node must be running. In PostgreSQL 11 and earlier, an existing 264 <filename>recovery.conf</filename> will not be overwritten unless the 265 <option>-F/--force</option> option is provided. 266 </para> 267 <para> 268 Execute <command>repmgr standby clone --replication-conf-only --dry-run</command> 269 to check the prerequisites for creating the recovery configuration, 270 and display the contents of the configuration which would be added without actually 271 making any changes. 272 </para> 273 274 </refsect1> 275 276 <refsect1> 277 278 <title>Options</title> 279 280 <variablelist> 281 282 <varlistentry> 283 <term><option>-d, --dbname=CONNINFO</option></term> 284 <listitem> 285 <para> 286 Connection string of the upstream node to use for cloning. 287 </para> 288 </listitem> 289 </varlistentry> 290 291 <varlistentry> 292 <term><option>--dry-run</option></term> 293 <listitem> 294 <para> 295 Check prerequisites but don't actually clone the standby. 296 </para> 297 <para> 298 If <option>--replication-conf-only</option> specified, the contents of 299 the generated recovery configuration will be displayed 300 but not written. 301 </para> 302 </listitem> 303 </varlistentry> 304 305 <varlistentry> 306 <term><option>-c, --fast-checkpoint</option></term> 307 <listitem> 308 <para> 309 Force fast checkpoint (not effective when cloning from Barman). 310 </para> 311 </listitem> 312 </varlistentry> 313 314 <varlistentry> 315 <term><option>--copy-external-config-files[={samepath|pgdata}]</option></term> 316 <listitem> 317 <para> 318 Copy configuration files located outside the data directory on the source 319 node to the same path on the standby (default) or to the 320 PostgreSQL data directory. 321 </para> 322 </listitem> 323 </varlistentry> 324 325 <varlistentry> 326 <term><option>--no-upstream-connection</option></term> 327 <listitem> 328 <para> 329 When using Barman, do not connect to upstream node. 330 </para> 331 </listitem> 332 </varlistentry> 333 334 <varlistentry> 335 <term><option>-R, --remote-user=USERNAME</option></term> 336 <listitem> 337 <para> 338 Remote system username for SSH operations (default: current local system username). 339 </para> 340 </listitem> 341 </varlistentry> 342 343 <varlistentry> 344 <term><option>--replication-conf-only</option></term> 345 <listitem> 346 <para> 347 Create recovery configuration for a previously cloned instance. 348 </para> 349 <para> 350 In PostgreSQL 11 and earlier, the replication configuration will be 351 written to <filename>recovery.conf</filename>. 352 </para> 353 <para> 354 In PostgreSQL 12 and later, the replication configuration will be 355 written to <filename>postgresql.auto.conf</filename>. 356 </para> 357 </listitem> 358 </varlistentry> 359 360 <varlistentry> 361 <term><option>--replication-user</option></term> 362 <listitem> 363 <para> 364 User to make replication connections with (optional, not usually required). 365 </para> 366 </listitem> 367 </varlistentry> 368 369 <varlistentry> 370 <term><option>--superuser</option></term> 371 <listitem> 372 <para> 373 If the &repmgr; user is not a superuser, the name of a valid superuser must 374 be provided with this option. 375 </para> 376 </listitem> 377 </varlistentry> 378 379 380 <varlistentry> 381 <term><option>--upstream-conninfo</option></term> 382 <listitem> 383 <para> 384 <literal>primary_conninfo</literal> value to include in the recovery configuration 385 when the intended upstream server does not yet exist. 386 </para> 387 <para> 388 Note that &repmgr; may modify the provided value, in particular to set the 389 correct <literal>application_name</literal>. 390 </para> 391 </listitem> 392 </varlistentry> 393 394 <varlistentry> 395 <term><option>--upstream-node-id</option></term> 396 <listitem> 397 <para> 398 ID of the upstream node to replicate from (optional, defaults to primary node) 399 </para> 400 </listitem> 401 </varlistentry> 402 403 <varlistentry> 404 <term><option>--verify-backup</option></term> 405 <listitem> 406 <para> 407 <!-- update link after Pg13 release --> 408 Verify a cloned node using the 409 <ulink url="https://www.postgresql.org/docs/13/app-pgverifybackup.html">pg_verifybackup</ulink> 410 utility (PostgreSQL 13 and later). 411 </para> 412 <para> 413 This option can currently only be used when cloning directly from an upstream 414 node. 415 </para> 416 </listitem> 417 </varlistentry> 418 419 <varlistentry> 420 <term><option>--without-barman </option></term> 421 <listitem> 422 <para> 423 Do not use Barman even if configured. 424 </para> 425 </listitem> 426 </varlistentry> 427 428 </variablelist> 429 </refsect1> 430 431 <refsect1 id="repmgr-standby-clone-events"> 432 <title>Event notifications</title> 433 <para> 434 A <literal>standby_clone</literal> <link linkend="event-notifications">event notification</link> will be generated. 435 </para> 436 </refsect1> 437 438 <refsect1> 439 <title>See also</title> 440 <para> 441 See <xref linkend="cloning-standbys"/> for details about various aspects of cloning. 442 </para> 443 </refsect1> 444</refentry> 445 446