1<refentry id="repmgr-standby-register" xreflabel="repmgr standby register">
2  <indexterm>
3    <primary>repmgr standby register</primary>
4  </indexterm>
5
6  <refmeta>
7    <refentrytitle>repmgr standby register</refentrytitle>
8  </refmeta>
9
10  <refnamediv>
11    <refname>repmgr standby register</refname>
12    <refpurpose>add a standby's information to the &repmgr; metadata</refpurpose>
13  </refnamediv>
14
15  <refsect1>
16    <title>Description</title>
17    <para>
18      <command>repmgr standby register</command> adds a standby's information to
19      the &repmgr; metadata. This command needs to be executed to enable
20      promote/follow operations and to allow &repmgrd; to work with the node.
21      An existing standby can be registered using this command. Execute with the
22      <literal>--dry-run</literal> option to check what would happen without actually registering the
23      standby.
24    </para>
25
26    <note>
27      <para>
28        If providing the configuration file location with <literal>-f/--config-file</literal>,
29        avoid using a relative path, as &repmgr; stores the configuration file location
30        in the repmgr metadata for use when &repmgr; is executed remotely (e.g. during
31        <xref linkend="repmgr-standby-switchover"/>). &repmgr; will attempt to convert the
32          a relative path into an absolute one, but this may not be the same as the path you
33          would explicitly provide (e.g. <filename>./repmgr.conf</filename> might be converted
34          to <filename>/path/to/./repmgr.conf</filename>, whereas you'd normally write
35          <filename>/path/to/repmgr.conf</filename>).
36      </para>
37    </note>
38  </refsect1>
39
40  <refsect1 id="repmgr-standby-register-wait-start" xreflabel="repmgr standby register --wait-start">
41   <title>Waiting for the the standby to start</title>
42   <para>
43     By default, &repmgr; will wait 30 seconds for the standby to become available before
44     aborting with a connection error. This is useful when setting up a standby from a script,
45     as the standby may not have fully started up by the time <command>repmgr standby register</command>
46     is executed.
47   </para>
48   <para>
49     To change the timeout, pass the desired value with the <literal>--wait-start</literal> option.
50     A value of <literal>0</literal> will disable the timeout.
51   </para>
52   <para>
53     The timeout will be ignored if <literal>-F/--force</literal> was provided.
54   </para>
55  </refsect1>
56
57  <refsect1 id="repmgr-standby-register-wait-sync" xreflabel="repmgr standby register --wait-sync">
58   <title>Waiting for the registration to propagate to the standby</title>
59   <para>
60     Depending on your environment and workload, it may take some time for the standby's node record
61     to propagate from the primary to the standby. Some actions (such as starting
62     &repmgrd;) require that the standby's node record
63     is present and up-to-date to function correctly.
64   </para>
65   <para>
66    By providing the option <option>--wait-sync</option> to the
67    <command>repmgr standby register</command> command, &repmgr; will wait
68    until the record is synchronised before exiting. An optional timeout (in
69    seconds) can be added to this option (e.g. <option>--wait-sync=60</option>).
70   </para>
71  </refsect1>
72
73  <refsect1 id="repmgr-standby-register-inactive-node" xreflabel="Registering an inactive node">
74   <title>Registering an inactive node</title>
75   <para>
76    Under some circumstances you may wish to register a standby which is not
77    yet running; this can be the case when using provisioning tools to create
78    a complex replication cluster, or if the node was not cloned by &repmgr;.
79   </para>
80   <para>
81    In this case, by using the <option>-F/--force</option>
82    option and providing the connection parameters to the primary server,
83    the standby can be registered even if it has not yet been started.
84   </para>
85   <tip>
86     <para>
87       Connection parameters can either be provided either as a <literal>conninfo</literal> string
88       (e.g. <option>-d 'host=node1 user=repmgr'</option> or as individual connection parameters
89        (<option>-h/--host</option>, <option>-d/--dbname</option>,
90       <option>-U/--user</option>, <option>-p/--port</option> etc.).
91     </para>
92   </tip>
93
94   <para>
95    Similarly, with cascading replication it may be necessary to register
96    a standby whose upstream node has not yet been registered - in this case,
97    using <option>-F/--force</option> will result in the creation of an inactive placeholder
98    record for the upstream node, which will however later need to be registered
99    with the <option>-F/--force</option> option too.
100   </para>
101   <para>
102    When used with <command>repmgr standby register</command>, care should be taken that use of the
103    <option>-F/--force</option> option does not result in an incorrectly configured cluster.
104   </para>
105  </refsect1>
106
107  <refsect1 id="repmgr-standby-register-node-cloned-other-source">
108    <title>Registering a node not cloned by repmgr</title>
109    <para>
110      If you've cloned a standby using another method (e.g. <application>barman</application>'s
111     <command><ulink url="https://docs.pgbarman.org/#recover">barman recover</ulink></command>
112     command), register the node as detailed in section
113     <xref linkend="repmgr-standby-register-inactive-node"/> then execute
114     <link linkend="repmgr-standby-create-recovery-conf">repmgr standby clone --replication-conf-only</link>
115     to generate the appropriate replication configuration.
116    </para>
117  </refsect1>
118
119  <refsect1>
120
121    <title>Options</title>
122
123    <variablelist>
124
125      <varlistentry>
126        <term><option>--dry-run</option></term>
127        <listitem>
128          <para>
129            Check prerequisites but don't actually register the standby.
130          </para>
131        </listitem>
132      </varlistentry>
133
134
135      <varlistentry>
136       <term><option>-F</option>/<option>--force</option></term>
137        <listitem>
138          <para>
139            Overwrite an existing node record
140          </para>
141        </listitem>
142      </varlistentry>
143
144
145      <varlistentry>
146        <term><option>--upstream-node-id</option></term>
147        <listitem>
148          <para>
149            ID of the upstream node to replicate from (optional)
150          </para>
151        </listitem>
152      </varlistentry>
153
154      <varlistentry>
155        <term><option>--wait-start</option></term>
156        <listitem>
157          <para>
158            wait for the standby to start (timeout in seconds, default 30 seconds)
159          </para>
160        </listitem>
161      </varlistentry>
162
163     <varlistentry>
164        <term><option>--wait-sync</option></term>
165        <listitem>
166          <para>
167            wait for the node record to synchronise to the standby (optional timeout in seconds)
168          </para>
169        </listitem>
170      </varlistentry>
171
172
173    </variablelist>
174  </refsect1>
175
176  <refsect1 id="repmgr-standby-register-events">
177    <title>Event notifications</title>
178    <para>
179      A <literal>standby_register</literal> <link linkend="event-notifications">event notification</link>
180      will be generated immediately after the node record is updated on the primary.
181    </para>
182
183    <para>
184      If the <option>--wait-sync</option> option is provided, a <literal>standby_register_sync</literal>
185      event notification  will be generated immediately after the node record has synchronised to the
186      standby.
187    </para>
188
189    <para>
190      If provided, &repmgr; will substitute the placeholders <literal>%p</literal> with the node ID of the
191      primary node, <literal>%c</literal> with its <literal>conninfo</literal> string, and
192      <literal>%a</literal> with its node name.
193    </para>
194
195  </refsect1>
196
197</refentry>
198