1<sect1 id="configuration-file" xreflabel="configuration file">
2
3  <title>Configuration file</title>
4
5  <indexterm>
6    <primary>repmgr.conf</primary>
7  </indexterm>
8
9  <indexterm>
10    <primary>configuration</primary>
11    <secondary>repmgr.conf</secondary>
12  </indexterm>
13
14  <para>
15    <application>repmgr</application> and &repmgrd;
16    use a common configuration file, by default called
17    <filename>repmgr.conf</filename> (although any name can be used if explicitly specified).
18    <filename>repmgr.conf</filename> must contain a number of required parameters, including
19    the database connection string for the local node and the location
20    of its data directory; other values will be inferred from defaults if
21    not explicitly supplied. See section <xref linkend="configuration-file-settings"/>
22    for more details.
23  </para>
24
25  <sect2 id="configuration-file-format" xreflabel="configuration file format">
26
27    <title>Configuration file format</title>
28
29    <indexterm>
30      <primary>repmgr.conf</primary>
31      <secondary>format</secondary>
32    </indexterm>
33
34
35
36    <para>
37      <filename>repmgr.conf</filename> is a plain text file with one parameter/value
38      combination per line.
39    </para>
40    <para>
41      Whitespace is insignificant (except within a quoted parameter value) and blank lines are ignored.
42      Hash marks (<literal>#</literal>) designate the remainder of the line as a comment.
43      Parameter values that are not simple identifiers or numbers should be single-quoted.
44    </para>
45    <para>
46      To embed a single quote in a parameter value, write either two quotes (preferred) or backslash-quote.
47    </para>
48
49    <para>
50      Example of a valid <filename>repmgr.conf</filename> file:
51      <programlisting>
52# repmgr.conf
53
54node_id=1
55node_name= node1
56conninfo ='host=node1 dbname=repmgr user=repmgr connect_timeout=2'
57data_directory = '/var/lib/pgsql/12/data'</programlisting>
58
59    </para>
60
61    <note>
62      <para>
63        Beginning with <link linkend="release-5.0">repmgr 5.0</link>, configuration
64        file parsing has been tightened up and now matches the way PostgreSQL
65        itself parses configuration files.
66      </para>
67      <para>
68        This means <filename>repmgr.conf</filename> files used with earlier &repmgr;
69        versions may need slight modification before they can be used with &repmgr; 5
70        and later.
71      </para>
72      <para>
73        The main change is that &repmgr; requires most string values to be
74        enclosed in single quotes. For example, this was previously valid:
75          <programlisting>
76conninfo=host=node1 user=repmgr dbname=repmgr connect_timeout=2</programlisting>
77          but must now be changed to:
78          <programlisting>
79conninfo='host=node1 user=repmgr dbname=repmgr connect_timeout=2'</programlisting>
80      </para>
81    </note>
82
83
84    <sect3 id="configuration-file-include-directives" xreflabel="configuration file include directives">
85
86      <title>Configuration file include directives</title>
87
88      <indexterm>
89        <primary>repmgr.conf</primary>
90        <secondary>include directives</secondary>
91      </indexterm>
92      <para>
93        From &repmgr; 5.2, the configuration file can contain the following include directives:
94        <itemizedlist spacing="compact" mark="bullet">
95          <listitem>
96            <simpara>
97              <option>include</option>: include the specified file,
98              either as an absolute path or path relative to the current file
99            </simpara>
100          </listitem>
101
102          <listitem>
103            <simpara>
104              <option>include_if_exists</option>: include the specified file.
105              The file is specified as an absolute path or path relative to the current file.
106              However, if it does not exist, an error will not be raised.
107            </simpara>
108          </listitem>
109
110          <listitem>
111            <simpara>
112              <option>include_dir</option>: include files in the specified directory
113              which have the <filename>.conf</filename> suffix.
114              The directory is specified either as an absolute path or path
115              relative to the current file
116            </simpara>
117          </listitem>
118
119        </itemizedlist>
120      </para>
121      <para>
122        These behave in exactly the same way as the PostgreSQL configuration file processing;
123        see the <ulink url="https://www.postgresql.org/docs/current/config-setting.html#CONFIG-INCLUDES">PostgreSQL documentation</ulink>
124        for additional details.
125      </para>
126    </sect3>
127
128  </sect2>
129
130
131  <sect2 id="configuration-file-items" xreflabel="configuration file items">
132
133    <title>Configuration file items</title>
134    <para>
135      The following sections document some sections of the configuration file:
136       <itemizedlist>
137          <listitem>
138            <simpara>
139              <xref linkend="configuration-file-settings"/>
140            </simpara>
141          </listitem>
142
143          <listitem>
144            <simpara>
145              <xref linkend="configuration-file-optional-settings"/>
146            </simpara>
147          </listitem>
148
149          <listitem>
150            <simpara>
151              <xref linkend="configuration-file-log-settings"/>
152            </simpara>
153          </listitem>
154
155
156          <listitem>
157            <simpara>
158              <xref linkend="configuration-file-service-commands"/>
159            </simpara>
160          </listitem>
161
162       </itemizedlist>
163
164    </para>
165    <para>
166      For a full list of annotated configuration items, see the file
167      <ulink url="https://raw.githubusercontent.com/2ndQuadrant/repmgr/master/repmgr.conf.sample">repmgr.conf.sample</ulink>.
168    </para>
169    <para>
170      For &repmgrd;-specific settings, see <xref linkend="repmgrd-configuration"/>.
171    </para>
172
173    <note>
174      <para>
175        The following parameters in the configuration file can be overridden with
176        command line options:
177        <itemizedlist>
178          <listitem>
179            <simpara>
180              <literal>-L/--log-level</literal> overrides <literal>log_level</literal> in
181              <filename>repmgr.conf</filename>
182            </simpara>
183          </listitem>
184          <listitem>
185            <simpara>
186              <literal>-b/--pg_bindir</literal> overrides <literal>pg_bindir</literal> in
187              <filename>repmgr.conf</filename>
188            </simpara>
189          </listitem>
190        </itemizedlist>
191      </para>
192    </note>
193
194  </sect2>
195
196  <sect2 id="configuration-file-location" xreflabel="configuration file location">
197  <title>Configuration file location</title>
198
199  <indexterm>
200    <primary>repmgr.conf</primary>
201    <secondary>location</secondary>
202  </indexterm>
203
204
205  <para>
206   The configuration file will be searched for in the following locations:
207   <itemizedlist spacing="compact" mark="bullet">
208    <listitem>
209     <para>a configuration file specified by the <literal>-f/--config-file</literal> command line option</para>
210    </listitem>
211    <listitem>
212     <para>
213      a location specified by the package maintainer (if <application>repmgr</application>
214      as installed from a package and the package maintainer has specified the configuration
215      file location)
216     </para>
217    </listitem>
218    <listitem>
219     <para><filename>repmgr.conf</filename> in the local directory</para>
220    </listitem>
221    <listitem>
222      <para><filename>/etc/repmgr.conf</filename></para>
223    </listitem>
224    <listitem>
225     <para>the directory reported by <application>pg_config --sysconfdir</application></para>
226    </listitem>
227   </itemizedlist>
228  </para>
229
230  <para>
231    In examples provided in this documentation, it is assumed the configuration file is located
232    at <filename>/etc/repmgr.conf</filename>. If &repmgr; is installed from a package, the
233    configuration file will probably be located at another location specified by the packager;
234    see appendix <xref linkend="appendix-packages"/> for configuration file locations in
235    different packaging systems.
236  </para>
237
238  <para>
239   Note that if a file is explicitly specified with <literal>-f/--config-file</literal>,
240   an error will be raised if it is not found or not readable, and no attempt will be made to
241   check default locations; this is to prevent <application>repmgr</application> unexpectedly
242   reading the wrong configuration file.
243  </para>
244
245  <note>
246    <para>
247      If providing the configuration file location with <literal>-f/--config-file</literal>,
248      avoid using a relative path, particularly when executing <xref linkend="repmgr-primary-register"/>
249      and <xref linkend="repmgr-standby-register"/>, as &repmgr; stores the configuration file location
250      in the repmgr metadata for use when &repmgr; is executed remotely (e.g. during
251      <xref linkend="repmgr-standby-switchover"/>). &repmgr; will attempt to convert the
252      a relative path into an absolute one, but this may not be the same as the path you
253      would explicitly provide (e.g. <filename>./repmgr.conf</filename> might be converted
254      to <filename>/path/to/./repmgr.conf</filename>, whereas you'd normally write
255      <filename>/path/to/repmgr.conf</filename>).
256    </para>
257   </note>
258  </sect2>
259
260  <sect2 id="configuration-file-postgresql-major-upgrades" xreflabel="configuration file and PostgreSQL major version upgrades">
261    <title>Configuration file and PostgreSQL major version upgrades</title>
262
263    <indexterm>
264      <primary>repmgr.conf</primary>
265      <secondary>ostgreSQL major version upgrades</secondary>
266    </indexterm>
267
268    <para>
269      When upgrading the PostgreSQL cluster to a new major version, <filename>repmgr.conf</filename>
270      will probably needed to be updated.
271    </para>
272    <para>
273      Usually <option>pg_bindir</option> and <option>data_directory</option> will need to be modified,
274      particularly if the default package locations are used, as these usually change.
275    </para>
276
277     <para>
278       It's also possible the location of <filename>repmgr.conf</filename> itself will change
279       (e.g. from <filename>/etc/repmgr/11/repmgr.conf</filename> to <filename>/etc/repmgr/12/repmgr.conf</filename>).
280       This is stored as part of the &repmgr; metadata and is used by &repmgr; to execute &repmgr; remotely
281       (e.g. during a <link linkend="performing-switchover">switchover operation</link>).
282     </para>
283     <para>
284       If the content and/or location of <filename>repmgr.conf</filename> has changed, the &repmgr; metadata
285       needs to be updated to reflect this. The &repmgr; metadata can be updated on each node with:
286       <itemizedlist spacing="compact" mark="bullet">
287         <listitem>
288           <simpara>
289             <link linkend="repmgr-primary-register">
290               <command>repmgr primary register --force -f /path/to/repmgr.conf</command>
291             </link>
292           </simpara>
293         </listitem>
294
295         <listitem>
296           <simpara>
297             <link linkend="repmgr-standby-register">
298               <command>repmgr standby register --force -f /path/to/repmgr.conf</command>
299             </link>
300           </simpara>
301         </listitem>
302
303
304         <listitem>
305           <simpara>
306             <link linkend="repmgr-witness-register">
307               <command>repmgr witness register --force -f /path/to/repmgr.conf -h primary_host</command>
308             </link>
309           </simpara>
310         </listitem>
311       </itemizedlist>
312     </para>
313
314   </sect2>
315 </sect1>
316