# Configuration file

repmgr and &repmgrd; use a common configuration file, by default called `repmgr.conf` (although any name can be used if explicitly specified). `repmgr.conf` must contain a number of required parameters, including the database connection string for the local node and the location of its data directory; other values will be inferred from defaults if not explicitly supplied. See section configuration-file-settings for more details.

## Configuration file format

`repmgr.conf` is a plain text file with one parameter/value combination per line.

Whitespace is insignificant (except within a quoted parameter value) and blank lines are ignored. Hash marks (`#`) designate the remainder of the line as a comment. Parameter values that are not simple identifiers or numbers should be single-quoted.

To embed a single quote in a parameter value, write either two quotes (preferred) or backslash-quote.

Example of a valid `repmgr.conf` file:

    # repmgr.conf

    node_id=1
    node_name= node1
    conninfo ='host=node1 dbname=repmgr user=repmgr connect_timeout=2'
    data_directory = '/var/lib/pgsql/12/data'

Beginning with repmgr 5.0, configuration file parsing has been tightened up and now matches the way PostgreSQL itself parses configuration files.

This means `repmgr.conf` files used with earlier &repmgr; versions may need slight modification before they can be used with &repmgr; 5 and later.

The main change is that &repmgr; requires most string values to be enclosed in single quotes. For example, this was previously valid:

    conninfo=host=node1 user=repmgr dbname=repmgr connect_timeout=2

but must now be changed to:

    conninfo='host=node1 user=repmgr dbname=repmgr connect_timeout=2'

### Configuration file include directives

From &repmgr; 5.2, the configuration file can contain the following include directives:

- `include`: include the specified file, either as an absolute path or path relative to the current file

- `include_if_exists`: include the specified file. The file is specified as an absolute path or path relative to the current file. However, if it does not exist, an error will not be raised.

- `include_dir`: include files in the specified directory which have the `.conf` suffix. The directory is specified either as an absolute path or path relative to the current file

These behave in exactly the same way as the PostgreSQL configuration file processing; see the PostgreSQL documentation for additional details.

## Configuration file items

The following sections document some sections of the configuration file:

- configuration-file-settings

- configuration-file-optional-settings

- configuration-file-log-settings

- configuration-file-service-commands

For a full list of annotated configuration items, see the file repmgr.conf.sample.

For &repmgrd;-specific settings, see repmgrd-configuration.

The following parameters in the configuration file can be overridden with command line options:

- `-L/--log-level` overrides `log_level` in `repmgr.conf`

- `-b/--pg_bindir` overrides `pg_bindir` in `repmgr.conf`

## Configuration file location

The configuration file will be searched for in the following locations:

- a configuration file specified by the `-f/--config-file` command line option

- a location specified by the package maintainer (if repmgr as installed from a package and the package maintainer has specified the configuration file location)

- `repmgr.conf` in the local directory

- `/etc/repmgr.conf`

- the directory reported by pg_config --sysconfdir

In examples provided in this documentation, it is assumed the configuration file is located at `/etc/repmgr.conf`. If &repmgr; is installed from a package, the configuration file will probably be located at another location specified by the packager; see appendix appendix-packages for configuration file locations in different packaging systems.

Note that if a file is explicitly specified with `-f/--config-file`, an error will be raised if it is not found or not readable, and no attempt will be made to check default locations; this is to prevent repmgr unexpectedly reading the wrong configuration file.

If providing the configuration file location with `-f/--config-file`, avoid using a relative path, particularly when executing repmgr-primary-register and repmgr-standby-register, as &repmgr; stores the configuration file location in the repmgr metadata for use when &repmgr; is executed remotely (e.g. during repmgr-standby-switchover). &repmgr; will attempt to convert the a relative path into an absolute one, but this may not be the same as the path you would explicitly provide (e.g. `./repmgr.conf` might be converted to `/path/to/./repmgr.conf`, whereas you'd normally write `/path/to/repmgr.conf`).

## Configuration file and PostgreSQL major version upgrades

When upgrading the PostgreSQL cluster to a new major version, `repmgr.conf` will probably needed to be updated.

Usually `pg_bindir` and `data_directory` will need to be modified, particularly if the default package locations are used, as these usually change.

It's also possible the location of `repmgr.conf` itself will change (e.g. from `/etc/repmgr/11/repmgr.conf` to `/etc/repmgr/12/repmgr.conf`). This is stored as part of the &repmgr; metadata and is used by &repmgr; to execute &repmgr; remotely (e.g. during a switchover operation).

If the content and/or location of `repmgr.conf` has changed, the &repmgr; metadata needs to be updated to reflect this. The &repmgr; metadata can be updated on each node with:

- `repmgr primary register --force -f /path/to/repmgr.conf`

- `repmgr standby register --force -f /path/to/repmgr.conf`

- `repmgr witness register --force -f /path/to/repmgr.conf -h primary_host`