Preliminary steps

This section contains some preliminary steps that you need to undertake before setting up your PostgreSQL server in Barman.

Important

Before you proceed, it is important that you have made your decision in terms of WAL archiving and backup strategies, as outlined in the “Design and architecture” section. In particular, you should decide which WAL archiving methods to use, as well as the backup method.

PostgreSQL connection

You need to make sure that the backup server can connect to the PostgreSQL server on pg as superuser or, from PostgreSQL 10 or higher, that the correct set of privileges are granted to the user that connects to the database.

You can create a specific superuser in PostgreSQL, named barman , as follows:

postgres@pg$ createuser -s -P barman

Or create a normal user with the required set of privileges as follows:

postgres@pg$ createuser -P barman

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;
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 PostgreSQL 15 beta and any subsequent PostgreSQL versions the functions pg_start_backup and pg_stop_backup have been renamed and have different signatures. You will therefore need to replace the first three lines in the above block with:

GRANT EXECUTE ON FUNCTION pg_backup_start(text, boolean) to barman;
GRANT EXECUTE ON FUNCTION pg_backup_stop(boolean) to barman;

It is worth noting that without a real superuser, the --force option of the barman switch-wal command will not work.

Important

The above createuser command will prompt for a password, which you are then advised to add to the ~barman/.pgpass file on the backup server. For further information, please refer to The Password File .

This connection is required by Barman in order to coordinate its activities with the server, as well as for monitoring purposes.

You can choose your favourite client authentication method among those offered by PostgreSQL. More information can be found in the

Run the following command as the barman user on the backup host in order to verify that the backup host can connect to PostgreSQL on the pg host:

barman@backup$ psql -c SELECT version() -U barman -h pg postgres

Write down the above information (user name, host name and database name) and keep it for later. You will need it with in the conninfo option for your server configuration, like in this example:

[pg]
; ...
conninfo = host=pg user=barman dbname=postgres

Note

Barman honours the application_name connection option for PostgreSQL servers 9.0 or higher.

PostgreSQL WAL archiving and replication

Before you proceed, you need to properly configure PostgreSQL on pg to accept streaming replication connections from the Barman server. Please read the following sections in the PostgreSQL documentation:

One configuration parameter that is crucially important is the wal_level parameter. This parameter must be configured to ensure that all the useful information necessary for a backup to be coherent are included in the transaction log file.

wal_level = replica

For PostgreSQL 9.4 or higher, wal_level can also be set to logical , in case logical decoding is needed.

For PostgreSQL versions older than 9.6, wal_level must be set to hot_standby .

Restart the PostgreSQL server for the configuration to be refreshed.

PostgreSQL streaming connection

If you plan to use WAL streaming or streaming backup, you need to setup a streaming connection. We recommend creating a specific user in PostgreSQL, named streaming_barman , as follows:

postgres@pg$ createuser -P --replication streaming_barman

Important

The above command will prompt for a password, which you are then advised to add to the ~barman/.pgpass file on the backup server. For further information, please refer to The Password File .

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

barman@backup$ psql -U streaming_barman -h pg \
  -c "IDENTIFY_SYSTEM" \
  replication=1

Important

Please make sure you are able to connect via streaming replication before going any further.

You also need to configure the max_wal_senders parameter in the PostgreSQL configuration file. The number of WAL senders depends on the PostgreSQL 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 the server will be allowed to manage.

Another important parameter is max_replication_slots , which represents the maximum number of replication slots [1] ` that the server will be allowed to manage. This parameter is needed 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 will use in your actual setup must be chosen after a careful evaluation of the architecture. Please consult the PostgreSQL documentation for guidelines and clarifications.

SSH connections

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 for backups.

Note

This procedure is not needed if you plan to use the streaming connection only to archive transaction logs and backup your PostgreSQL server.

SSH configuration of postgres user

Unless you have done it before, you need to create an SSH key for the PostgreSQL user. Log in as postgres , in the pg host and type:

postgres@pg$ 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

As in the previous paragraph, you need to create an SSH key for the Barman user. Log in as barman in the backup host and type:

barman@backup$ ssh-keygen -t rsa

For the same reason, no passphrase should be entered.

From PostgreSQL to Barman

The SSH connection from the PostgreSQL server to the backup server is needed to correctly archive WAL files using the archive_command setting.

To successfully connect from the PostgreSQL server to the backup server, the PostgreSQL public key has to be configured into the authorized keys of the backup server for the barman user.

The public key to be authorized is stored inside the postgres 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 barman user in the backup server. 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:

postgres@pg$ ssh barman@backup -C true

The value of the archive_command configuration parameter will be discussed in the “WAL archiving via archivecommand section”.

From Barman to PostgreSQL

The SSH connection between the backup server and the PostgreSQL server is used for the traditional backup over rsync. Just as with the connection from the PostgreSQL server to the backup server, we should authorize the public key of the backup server in the PostgreSQL server for the postgres user.

The content of the file .ssh/id_rsa.pub in the barman server should be put in the file named .ssh/authorized_keys in the PostgreSQL server. The permissions of that file should be 600 .

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

barman@backup$ ssh postgres@pg -C true