Interactive Demo

Backup and Recovery: Single-Server Streaming - Installing and Configuring Barman

Suggest edits

In the previous step, we configured the PostgreSQL server, creating users for Barman to connect and manage backups. In this step, we'll install and configure Barman on the backup server.

This demo is interactive

You can follow along right in your browser. When you click "Start Now," Katacoda will load a Docker Compose environment with two container images representing a PostgreSQL 13 server with the Pagila database loaded (named pg) and a backup server for Barman (named backup).

Once you see a root@backup prompt, you can follow the steps below.

Clicking Start Now will load an interactive terminal in this window

This demonstration uses an Ubuntu environment, so the first step is to configure the PostgreSQL repository (details are on the PostgreSQL wiki)

  1. Install prerequesite software

    apt-get update
    apt-get install -y curl ca-certificates gnupg
    Output
    ...
    done
  2. Add PostgreSQL's authentication key

    curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
    Output
    % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                    Dload  Upload   Total   Spent    Left  Speed
    100  4812  100  4812    0     0  24426      0 --:--:-- --:--:-- --:--:-- 24426
    OK    
  3. Add the PostgreSQL repository to the list of sources, and update available packages

    sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
    apt-get update
    Output
    ...
    Reading package lists... Done

With the repository configured, we can use apt to install Barman and its dependencies:

apt-get -y install barman
Output
...
Processing triggers for systemd (245.4-4ubuntu3.4) ...
Processing triggers for libc-bin (2.31-0ubuntu9.1) ...
Further reading

For more details on installation (including instructions for other supported operating systems), see the Installation section in the Barman guide.

Configuration

All the important details for a Barman server go into a server configuration file, by default located in /etc/barman.d. These are in the classic INI format, with relevant settings in a section named after the server we're going to back up. We'll also use that name for the configuration file itself. Since the server we intend to back up is named "pg", we'll use that:

cat <<'EOF' >> /etc/barman.d/pg.conf
[pg]
description =  "Example of PostgreSQL Database (Streaming-Only)"
conninfo = host=pg user=barman dbname=pagila
streaming_conninfo = host=pg user=streaming_barman dbname=pagila
backup_method = postgres
streaming_archiver = on
slot_name = barman
create_slot = auto
EOF

Note that this references the users (barman and streaming_barman) that we created in step #1 - Database Server Configuration. Also of interest is the value for slot_name - this is a replication slot that will also have to be created on the server - but we can instruct Barman to do that for us by setting create_slot to auto.

The installation process created a brand-new barman user on the backup server, so let's switch to that for the rest of this:

su - barman

PostgreSQL Connection Password File

In order for Barman to connect via the user specified, we'll need to add the password we specified in the previous step to Barman's .pgpass file:

cat <<'EOF' >>~/.pgpass
pg:5432:*:barman:example-password
pg:5432:replication:streaming_barman:example-password
EOF
chmod 0600 ~/.pgpass

Each line in the .pgpass file needs to follow below format:

[db_host]:[db_port]:[db_name]:[db_user]:[db_password]

The database name [db_name] for the barman streaming user must be replication

Note the change in permissions - this is necessary to protect the visibility of the file. PostgreSQL won't use it unless permissions are restricted.

Further reading

For more details on configuration files, see: the Configuration section in the Barman guide.

Verifying the configuration

During installation, Barman will have installed a cron service that runs every minute to maintenance tasks. Since we only just gave it a configuration, let's make sure those tasks have run before continuing:

barman cron
Output
Starting WAL archiving for server pg
Starting streaming archiver for server pg

Now that the configuration is done and initialization has been performed, we can use Barman's check command to verify that it works:

barman check pg
Output
Server pg:
        WAL archive: FAILED (please make sure WAL shipping is setup)
        PostgreSQL: OK
        superuser or standard user with backup privileges: OK
        PostgreSQL streaming: OK
        wal_level: OK
        replication slot: OK
        directories: OK
        retention policy settings: OK
        backup maximum age: OK (no last_backup_maximum_age provided)
        compression settings: OK
        failed backups: OK (there are 0 failed backups)
        minimum redundancy requirements: OK (have 0 backups, expected at least 0)
        pg_basebackup: OK
        pg_basebackup compatible: OK
        pg_basebackup supports tablespaces mapping: OK
        systemid coherence: OK (no system Id stored on disk)
        pg_receivexlog: OK
        pg_receivexlog compatible: OK
        receive-wal running: OK
        archiver errors: OK

Uh-oh! WAL archive failed? Not a problem - that just means Barman hasn't seen any new WAL archives come in yet, which isn't surprising given this is an example database with no writes happening! We can trigger an archive manually and verify that this works:

barman switch-wal --archive --archive-timeout 60 pg
Output
The WAL file 000000010000000000000002 has been closed on server 'pg'
Waiting for the WAL file 000000010000000000000002 from server 'pg' (max: 60 seconds)
Processing xlog segments from streaming for pg
        000000010000000000000002

This forces WAL rotation and (with the --archive option) waits for the WAL to arrive. We'll give it 60 seconds (with the --archive-timeout option) to complete; if it doesn't complete within that amount of time, try again. For more detail on these commands and their options, refer to the Barman manual.

Once switch-wal has completed successfully, run the check again and you should see all checks passing:

barman check pg
Output
Server pg:
        PostgreSQL: OK
        superuser or standard user with backup privileges: OK
        PostgreSQL streaming: OK
        wal_level: OK
        replication slot: OK
        directories: OK
        retention policy settings: OK
        backup maximum age: OK (no last_backup_maximum_age provided)
        compression settings: OK
        failed backups: OK (there are 0 failed backups)
        minimum redundancy requirements: OK (have 0 backups, expected at least 0)
        pg_basebackup: OK
        pg_basebackup compatible: OK
        pg_basebackup supports tablespaces mapping: OK
        systemid coherence: OK (no system Id stored on disk)
        pg_receivexlog: OK
        pg_receivexlog compatible: OK
        receive-wal running: OK
        archiver errors: OK

Continue on with Step #3: Running Backups.


Could this page be better? Report a problem or suggest an addition!