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, 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: .. code:: bash postgres@pg$ createuser -s -P barman Or create a normal user with the required set of privileges as follows: .. code:: bash postgres@pg$ createuser -P barman .. code:: sql 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 PostgreSQL version 14 or a prior version, the functions ``pg_backup_start`` and ``pg_backup_stop`` had different names and different signatures. You will therefore need to replace the first two lines in the above block with: .. code:: sql 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; It is worth noting that with PostgreSQL version 13 and below without a real superuser, the ``--force`` option of the ``barman switch-wal`` command will not work. If you are running PostgreSQL version 15 or above, you can grant the ``pg_checkpoint`` role, so you can use this feature without a superuser: .. code:: sql GRANT pg_checkpoint TO barman; .. 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 `Client Authentication `_ . 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: .. code:: bash 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: .. code:: ini [pg] ; ... conninfo = host=pg user=barman dbname=postgres application_name=myapp .. NOTE:: `application_name` is optional. 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: - `Role attributes `_ - `The pg_hba.conf file `_ - `Setting up standby servers using streaming replication `_ 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. .. code:: ini wal_level = replica|logical 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: .. code:: bash 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: .. code:: bash barman@backup$ psql -U streaming_barman -h pg \ -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) .. 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`` : .. code:: ini 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: .. code:: ini 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 :ref:`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: .. code:: bash 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: .. code:: bash 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: .. code:: bash 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. .. code:: bash barman@backup$ ssh postgres@pg -C true .. [1] Replication slots have been introduced in PostgreSQL 9.4. See section “WAL Streaming / Replication slots” for details.