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 &quot;repmgr standby clone&quot;</secondary>
92    </indexterm>
93
94	<indexterm>
95     <primary>replication configuration</primary>
96     <secondary>customising with &quot;repmgr standby clone&quot;</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