Pre-requisites#

This section details some requirements and configurations necessary to set up a Barman environment depending on your use case.

Throughout this section, we assume the following hosts:

  • pghost: The host where Postgres is running.

  • barmanhost: The host where Barman will be set up.

Postgres users#

Barman requires a connection to your Postgres instance to gather information about the server. The recommended way to set up this connection is to create a dedicated user in Postgres named barman. This user should have the necessary privileges.

Note

The createuser commands executed below will prompt you for a password, which you are then advised to add to a password file named .pgpass under your Barman home directory on barmanhost. Aditionally, you can choose the client authentication method of your preference among those offered by Postgres. Check the official documentation for further details.

To create a superuser named barman in Postgres, run the following command on pghost:

createuser -s -P barman

Or, in case you opt for a user with only the required priviledges, follow these steps:

  1. On pghost, run this command to create a user named barman in Postgres:

createuser -P barman

  1. On pghost, in the psql interface, run the following statements:

GRANT EXECUTE ON FUNCTION pg_backup_start(text, boolean) to barman;
GRANT EXECUTE ON FUNCTION pg_backup_stop(boolean) to barman;
GRANT EXECUTE ON FUNCTION pg_switch_wal() to barman;
GRANT EXECUTE ON FUNCTION pg_create_restore_point(text) to barman;
GRANT pg_read_all_settings TO barman;
GRANT pg_read_all_stats TO barman;

In the case of using Postgres version 14 or a prior version, the functions pg_backup_start and pg_backup_stop will have different names and signatures. You will therefore need to replace the first two lines in the above block with:

GRANT EXECUTE ON FUNCTION pg_start_backup(text, boolean, boolean) to barman;
GRANT EXECUTE ON FUNCTION pg_stop_backup() to barman;
GRANT EXECUTE ON FUNCTION pg_stop_backup(boolean, boolean) to barman;

Note

In Postgres version 13 and below, the --force option of the barman switch-wal command does not work without a superuser. In Postgres version 15 or above, it is possible to grant the pg_checkpoint role to use it without a superuser by executing the statement GRANT pg_checkpoint TO barman;.

Postgres connection#

A connection to your Postgres instance is required regardless of which backup method you are using. This connection is required by Barman in order to coordinate its activities with the database server, as well as for monitoring purposes.

Make sure that barmanhost can connect to the database server as superuser or with a user with the required priviledges. You can find detailed information about setting up Postgres connections in the Postgres Client Authentication.

With your user created, run the following command on barmanhost to assert that it can connect to your Postgres instance:

psql -c 'SELECT version()' -U barman -h pghost postgres

postgres can be any available database through which Barman can connect to the Postgres instance.

If the above command succeeds, it means that it can successfully connect to the database server. Remember the connection parameters above as they are the ones you need to write on your server’s configuration file, in the conninfo parameter. In this context, this parameter would be as follows:

[my-server]
; ...
conninfo = host=pghost user=barman dbname=postgres application_name=myapp

application_name is an optional parameter.

Postgres client tools#

The Postgres client tools are required to interact with the Postgres server. The most commonly used tools by Barman are pg_basebackup and pg_receivewal. They are provided by the Postgres client package.

To install the Postgres client package on Debian or Ubuntu run the following command on the barmanhost:

sudo apt-get install postgresql-client

Alternatively, if the barmanhost is using RHEL, Rocky Linux, Alma Linux, follow this recipe:

sudo dnf install postgresql

Postgres streaming replication connection#

If you plan to use streaming backups or streaming of WAL files, you need to setup a streaming connection. Additionally, you also need to have the Postgres client tools installed, as shared in pre-requisites section.

We recommend creating a dedicated user in Postgres named streaming_barman. You can do so with the following command:

createuser -P --replication streaming_barman

Note

The createuser commands executed below prompt you for a password, which you are then advised to add to a password file named .pgpass under your Barman home directory on barmanhost. Aditionally, you can choose the client authentication method of your preference among those offered by Postgres. Check the official documentation for further details.

You can verify that the streaming connection works through the following command:

psql -U streaming_barman -h pghost -c "IDENTIFY_SYSTEM" replication=1

If the connection is working, you should see a response containing the system identifier, current timeline ID and current WAL flush location, for example:

      systemid       | timeline |  xlogpos   | dbname
---------------------+----------+------------+--------
7139870358166741016 |        1 | 1/330000D8 |
(1 row)

You also need to configure the max_wal_senders parameter in Postgres. The number of WAL senders depends on the Postgres architecture you have implemented. In this example, we are setting it to 2:

max_wal_senders = 2

This option represents the maximum number of concurrent streaming connections that Postgres is allowed to manage.

Another important parameter is max_replication_slots, which represents the maximum number of replication slots that Postgres is allowed to manage. This parameter is relevant if you are planning to use the streaming connection to receive WAL files over the streaming connection:

max_replication_slots = 2

The values proposed for max_replication_slots and max_wal_senders must be considered as examples, and the values you use in your actual setup must be chosen after a careful evaluation of the architecture. Please consult the Postgres documentation for guidelines and clarifications.

SSH connections#

If you plan to use Rsync backups or WAL archiving via archive_command, then SSH connections are required.

SSH is a protocol and a set of tools that allows you to open a remote shell to a remote server and copy files between the server and the local system. You can find more documentation about SSH usage in the article “SSH Essentials” by Digital Ocean.

SSH key exchange is a very common practice that is used to implement secure passwordless connections between users on different machines, and it’s needed to use Rsync for WAL archiving and backups.

SSH configuration of postgres user#

Unless you have done it before, you need to create an SSH key for the postgres user. Log in as postgres on pghost and run:

ssh-keygen -t rsa

As this key must be used to connect from hosts without providing a password, no passphrase should be entered during the key pair creation.

SSH configuration of barman user#

You also need to create an SSH key for the barman user. Log in as barman on barmanhost and run:

ssh-keygen -t rsa

Again, no passphrase should be entered.

From Postgres to Barman#

The SSH connection from pghost to barmanhost is needed to correctly archive WAL files using the archive_command.

To successfully connect from pghost to barmanhost, the postgres user`s public key has to be stored in the authorized keys of the barman user on barmanhost. This key is located in the postgres user home director in a file named .ssh/id_rsa.pub, and its content should be included in a file named .ssh/authorized_keys inside the home directory of the barman user on barmanhost. If the authorized_keys file doesn’t exist, create it using 600 as permissions.

The following command should succeed without any output if the SSH key pair exchange has been completed successfully:

ssh barman@barmanhost -C true

From Barman to Postgres#

The SSH connection between from barmanhost to pghost is used for the traditional backup using Rsync.

To successfully connect from barmanhost to pghost, the barman user`s public key has to be stored in the authorized keys of the postgres user on pghost. This key is located in the barman user home directory in a file named .ssh/id_rsa.pub, and its content should be included in a file named .ssh/authorized_keys inside the home directory of the postgres user on pghost. If the authorized_keys file doesn’t exist, create it using 600 as permissions.

The following command should succeed without any output if the SSH key pair exchange has been completed successfully:

ssh postgres@pghost -C true

WAL archiving via archive_command#

As stated in the WAL archiving strategies section, there are two options to archive wals with Barman. If you wish to use the streaming replication protocol to archive WAL files, refer to the WAL streaming concepts and Quick start section, specifically the Streaming backups with WAL streaming sub-section. Otherwise you can configure WAL archiving using the archive_command with barman-wal-archive or with Rsync/SSH.

Using barman-wal-archive#

Starting from Barman 2.6, the recommended approach for securely archiving Write-Ahead Log files is to utilize the barman-wal-archive command from the barman-cli package. Refer to the installation section on how to install this package.

Using barman-wal-archive instead of traditional methods like rsync or SSH minimizes the risk of data corruption during the transfer of WAL files to the Barman server. The conventional methods lack a guarantee that the file’s content is properly flushed and fsynced to disk at the destination.

The barman-wal-archive utility directly interacts with barman put-wal command. This command ensures that the received WAL file is fsynced and stored in the correct incoming directory for the respective server. The only parameter required for the archive_command is the server’s name, reducing the likelihood of misplacement.

To verify that barman-wal-archive can connect to the Barman server and that the Postgres server is correctly configured to accept incoming WAL files, execute the following command:

barman-wal-archive --test backup pg DUMMY

Here, backup refers to the Barman host, pg is the Postgres server’s name as configured in Barman, and DUMMY is a placeholder for the WAL file name which is ignored when using the -t option.

If the setup is correct, you should see:

Ready to accept WAL files for the server pg

Since the utility communicates via SSH, ensure that SSH key authentication is set up for the postgres user to log in as barman on the backup server. If your SSH connection uses a port other than the default (22), you can specify the port using the --port option.

Refer to the Rsync backups with WAL archiving to start working with it.

Using Rsync/SSH#

An alternative approach for configuring the archive_command is to utilize the rsync command via SSH. Here are the initial steps to set it up effectively for a Postgres server named pg, a Barman server named backup and a user named barman.

To locate the incoming WALs directory, use the following command and check for the incoming_wals_directory value:

barman show-servers pg | grep incoming_wals_directory

    incoming_wals_directory: /var/lib/barman/pg/incoming

Next, edit the postgresql.conf file for the Postgres instance on the pg host to enable archive mode:

archive_mode = on
wal_level = 'replica'
archive_command = 'rsync -a %p barman@backup:INCOMING_WALS_DIRECTORY/%f'

Be sure to replace the INCOMING_WALS_DIRECTORY placeholder with the actual path retrieved from the previous command. After making these changes, restart the Postgres server.

For added security in the archive_command process, consider implementing stricter checks. For instance, the following command ensures that the hostname matches before executing the rsync:

archive_command = 'test $(/bin/hostname --fqdn) = HOSTNAME \
    && rsync -a %p barman@backup:INCOMING_WALS_DIRECTORY/%f'

Replace HOSTNAME with the output from hostname --fqdn. This approach acts as a safeguard against potential issues when servers are cloned, preventing WAL files from being sent by recovered Postgres instances.