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