pgBackRest site configuration#

pgBackRest satellite component can be enabled through site settings by defining a pgbackrest key, e.g.:

   execpath: /usr/local/bin/pgbackrest
     mode: path
     path: /backups


The repository key is required, along with the mode one underneath.


See settings schema for further information about available configuration and their model.

pgBackRest integration in pglift supports two repository modes:

  1. a local repository, configured with a path key as in the above example, and,

  2. a remote repository.

Site configuration#

In any repository mode, running the site-configure command is required after settings definition in order to (at least) install base pgbackrest configuration file and directories.

The base pgBackRest configuration is installed site-wise from a template (which may be overridden). The default pgbackrest.conf template file contains:

lock-path = {lockpath}
log-path = {logpath}
spool-path = {spoolpath}

PostgreSQL configuration is handled through parameters set in postgresql.conf file as documented in PostgreSQL site configuration. The default values for those parameters are:

wal_level = replica
archive_mode = on
archive_command = '{execpath} --config-path={configpath} --stanza={stanza} --pg1-path={datadir} archive-push %p'

and can be overridden by providing a postgresql/pgbackrest.conf template file in site configuration directory (see configuration templates).

Local repository mode#

In this mode, site settings must contain a repository.path key and repository.mode must have path as value as in the above example.

Upon instance creation, pgBackRest is set up by:

  • adding some configuration to PostgreSQL,

  • writing a pgBackRest configuration file for this instance, and,

  • initializing the pgBackRest stanza in the repository.

Remote repository mode#

In this mode, you can either use TLS with client certificates or passwordless SSH to enable communication between the hosts.


To enable TLS support, repository.mode must be set to host-tls. And a few more information must be provided.

   configpath: /conf/pgbackrest
     mode: host-tls
     cn: backup-srv
       ca_cert: /etc/ssl/certs/my-ca.crt
       cert: /etc/ssl/certs/local.crt
       key: /etc/ssl/private/local.key

Upon site configuration, through invocation of the site-configure command, in addition to the base site configuration, a pgBackRest TLS server is configured and started. This server will be consumed by pgBackRest client commands such as pgbackrest backup, typically run on configured The certificate key in above settings will be used to configure this (on site) server.


The process started during site-configure should be kept running alongside all instances on site and thus probably get started on boot. As such, it is best to use a service manager such as systemd in this context.

Upon instance creation, in addition to WAL archiving configuration on PostgreSQL side, the local stanza configuration is written on site.

Typically, further configuration will be needed on the remote repository host to:

  • add or extend the stanza configuration, typically at least (where emphasized lines are to be determined from the database host server, managed by pglift):

    pg1-host = pghost1
    pg1-host-type = tls
    pg1-host-config-path = /conf/pgbackrest
    pg1-host-ca-file = ...
    pg1-host-cert-file = ...
    pg1-host-key-file = ...
    pg1-path = /srv/pgsql/15/main/data
    pg1-user = backup
    pg1-socket-path = /run/user/100/pglift/postgresql
  • run pgbackrest stanza-create, in case of a new stanza, or pgbackrest stanza-upgrade if upgrading, and

  • run a pgbackrest check to make sure things are working as expected.

Finally, it’s usually a good idea to run a pgbackrest check on the database host as well:

$ export $(pglift instance env main)
$ pgbackrest check

Passwordless SSH#

To enable SSH support, the repository mode must be set to host-ssh.

   configpath: /conf/pgbackrest
     mode: host-ssh

For it to work, pgbackrest user needs to be able to connect from the repository host to the database host via SSH. And the user running pglift needs to be able to do the same from database host to repository host. Basically, this needs SSH keys to be exchanged between database host and repository host.

Please refer to pgBackRest documentation.