Barman Backup and Recovery Manager for PostgreSQL Tutorial

3 February 2013 Gabriele Bartolini Marco Nenciarini Giulio Calacoci Gianni Ciolli Giuseppe Broccolo

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

Revision History
Revision 1.3.0 Version 1.3.0 Revision 1.2.3 Version 1.2.3 Revision 1.2.2 Version 1.2.2 Revision 1.2.1 Version 1.2.1 Revision 1.2.0 Version 1.2.0 Revision 1.1.2 Version 1.1.2 Revision 1.1.0 Version 1.1.0 Revision 1.0.0 First public release
Copyright 2011-2014, 2ndQuadrant Italia (Devise.IT S.r.l.) - http://www.2ndQuadrant.it/. All rights reserved. The PostgreSQL elephant logo "Slonik" is a registered trademark of the PostgreSQL Global Development Group.

3 February 2013

gb

5 September 2013

gib

24 June 2013

mn

17 June 2013

gb

31 January 2013

gb

29 November 2012

gb

12 October 2012

gb, mn

2 July 2012

gb, ca, mn, gc

Table of Contents
Introduction ............................................................................................................................... 4 Before you start ........................................................................................................................ 4 System requirements ......................................................................................................... 5 Installation ................................................................................................................................. 6 On RedHat/CentOS using RPM packages .......................................................................... 6 On Debian/Ubuntu using packages .................................................................................... 6 From sources .................................................................................................................... 6 Getting started .......................................................................................................................... 7 Prerequisites ..................................................................................................................... 7 Basic configuration ............................................................................................................ 8 Listing the servers ........................................................................................................... 10 Executing a full backup ................................................................................................... 10 Viewing the list of backups for a server ............................................................................ 11 Restoring a whole server ................................................................................................. 11 Remote recovery ............................................................................................................. 11 Relocating one or more tablespaces ................................................................................ 12 Restoring to a given point in time .................................................................................... 12 WAL compression ................................................................................................................... 13

Copyright 2014, 2ndQuadrant Italia

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

Limiting bandwidth usage ........................................................................................................ Network Compression .............................................................................................................. Backup ID shortcuts ................................................................................................................ Minimum redundancy safety .................................................................................................... Retention policies .................................................................................................................... Scope ............................................................................................................................. How they work ................................................................................................................ Configuration and syntax ................................................................................................. Available commands ................................................................................................................ General commands ......................................................................................................... Server commands ........................................................................................................... Backup commands .......................................................................................................... Hook scripts ............................................................................................................................ Backup scripts ................................................................................................................. WAL archive scripts ......................................................................................................... Support and sponsor opportunities ........................................................................................... Authors ................................................................................................................................... Links ....................................................................................................................................... License and Contributions .......................................................................................................

13 13 13 14 14 15 15 15 16 16 17 18 19 19 20 20 21 21 21

Copyright 2014, 2ndQuadrant Italia

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

Barman (backup and recovery manager) is an administration tool for disaster recovery of PostgreSQL servers written in Python. Barman can perform remote backups of multiple servers in business critical environments, and helps DBAs during the recovery phase. Barmans most wanted features include: backup catalogues, retention policies, remote recovery, archiving and compression of WAL files and of backups. Barman is written and maintained by PostgreSQL professionals 2ndQuadrant.

Introduction
In a perfect world, there would be no need for a backup. However it is important, especially in business environments, to be prepared for when the "unexpected" happens. In a database scenario, the unexpected could take any of the following forms: data corruption; system failure, including hardware failure; human error; natural disaster.

In such cases, any ICT manager or DBA should be able to repair the incident and recover the database in the shortest possible time. We normally refer to this discipline as Disaster recovery. This guide assumes that you are familiar with theoretical disaster recovery concepts, and you have a grasp of PostgreSQL fundamentals in terms of physical backup and disaster recovery. If not, we encourage you to read the PostgreSQL documentation or any of the recommended books on PostgreSQL. Professional training on this topic is another effective way of learning these concepts. At any time of the year you can find many courses available all over the world, delivered by PostgreSQL companies such as 2ndQuadrant. For now, you should be aware that any PostgreSQL physical/binary backup (not to be confused with the logical backups produced by the pg_dump utility) is composed of: a base backup; one or more WAL files (usually collected through continuous archiving). PostgreSQL offers the core primitives that allow DBAs to setup a really robust Disaster Recovery environment. However, it becomes complicated to manage multiple backups, from one or more PostgreSQL servers. Restoring a given backup is another task that any PostgreSQL DBA would love to see more automated and user friendly. With these goals in mind, 2ndQuadrant started the development of Barman for PostgreSQL. Barman is an acronym for "Backup and Recovery Manager". Currently Barman works only on Linux and Unix operating systems.

Before you start

The first step is to decide the architecture of your backup. In a simple scenario, you have one PostgreSQL instance (server) running on a host. You want your data continuously backed up to another server, called the backup server.

Copyright 2014, 2ndQuadrant Italia

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

Barman allows you to launch PostgreSQL backups directly from the backup server, using SSH connections. Furthermore, it allows you to centralise your backups in case you have more than one PostgreSQL server to manage. During this guide, we will assume that: there is one PostgreSQL instance on a host (called pg for simplicity) there is one backup server on another host (called backup) communication via SSH between the two servers is enabled the PostgreSQL server can be reached from the backup server as the postgres operating system user (or another user with PostgreSQL database superuser privileges, typically configured via ident authentication)

It is important to note that, for disaster recovery, these two servers must not share any physical resource except for the network. You can use Barman in geographical redundancy scenarios for better disaster recovery outcomes.

System requirements
Linux/Unix Python 2.6 or 2.7 Python modules: argcomplete argh >= 0.21.2 psycopg2 python-dateutil < 2.0 (since version 2.0 requires python3) distribute (optional) PostgreSQL >= 8.4 rsync >= 3.0.4

Important
The same major version of PostgreSQL should be installed on both servers.

Tip
Users of RedHat Enterprise Linux, CentOS and Scientific Linux are advised to install the 1 Extra Packages Enterprise Linux (EPEL) repository.

Note
Version 1.2.3 of Barman has been refactored for Python 3 support. Please consider it as experimental now and report any bug through the ticketing system on SourceForge or mailing list.

Further information at http://fedoraproject.org/wiki/EPEL

Copyright 2014, 2ndQuadrant Italia

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

Installation
On RedHat/CentOS using RPM packages
Barman can be installed on RHEL5 and RHEL6 Linux systems using RPM packages. Barman is available through the PostgreSQL Global Development Group RPM repository with Yum. You need to follow the instructions for your distribution (RedHat, CentOS, Fedora, etc.) and architecture that you can find at http://yum.postgresql.org/. Then, as root simply type:
yum install barman

On Debian/Ubuntu using packages

Barman can be installed on Debian and Ubuntu Linux systems using packages. It is available in the official repository for Debian Sid (unstable) and Ubuntu 12.10 (Quantal Quetzal).

Note
You can install an up-to-date version of Barman on many Debian and Ubuntu releases using the PostgreSQL Community APT repository at http://apt.postgresql.org/. Instructions can be found at https://wiki.postgresql.org/wiki/Apt. Installing Barman is as simple as typing as root user:
apt-get install barman

From sources
Create a system user called barman on the backup server. As barman user, download the sources and uncompress them. For a system-wide installation, type:
barman@backup$ ./setup.py build barman@backup# ./setup.py install # run this command with root privileges or sudo

For a local installation, type:

barman@backup$ ./setup.py install --user

Important
The --user option works only with python-distribute barman will be installed in your user directory (make sure that your PATH environment variable is set properly).

Copyright 2014, 2ndQuadrant Italia

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

Getting started
Prerequisites
SSH connection
Barman needs a bidirectional SSH connection between the barman user on the backup server and the postgres user. SSH must be configured such that there is no password prompt presented when connecting. on the pg server. As the barman user on the backup server, generate an SSH key with an empty password, and append the public key to the authorized_keys file of the postgres user on the pg server. The barman user on the backup server should then be able to perform the following operation without typing a password:
barman@backup$ ssh postgres@pg

The procedure must be repeated with sides swapped in order to allow the postgres user on the pg server to connect to the backup server as the barman user without typing a password:
postgres@pg$ ssh barman@backup

For further information, refer to OpenSSH documentation.

PostgreSQL connection
You need to make sure that the backup server allows connection to the PostgreSQL server on pg as superuser (postgres). You can choose your favourite client authentication method among those offered by PostgreSQL. More information can be found here: http://www.postgresql.org/docs/current/static/client-authentication.html
barman@backup$ psql -c 'SELECT version()' -U postgres -h pg

Note
As of version 1.1.2, Barman honours the application_name connection option for PostgreSQL servers 9.0 or higher.

Backup directory
Barman needs a main backup directory to store all the backups. Even though you can define a separate folder for each server you want to back up and for each type of resource (backup or WAL segments, for instance), we suggest that you adhere to the default rules and stick with the conventions that Barman chooses for you. You will see that the configuration file (as explained below) defines a barman_home variable, which is the directory where Barman will store all your backups by default. We choose /var/lib/barman as home directory for Barman:
barman@backup$ sudo mkdir /var/lib/barman

Copyright 2014, 2ndQuadrant Italia

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

barman@backup$ sudo chown barman:barman /var/lib/barman

Important
We assume that you have enough space, and that you have already thought about redundancy and safety of your disks.

Basic configuration
In the docs directory you will find a minimal configuration file. Use it as a template, and copy it to / etc/barman.conf, or to ~/.barman.conf. In general, the former applies to all the users on the backup server, while the latter applies only to the barman user; for the purpose of this tutorial there is no difference in using one or the other. From version 1.2.1, you can use /etc/barman/barman.conf as default system configuration file. The configuration file follows the standard INI format, and is split in: a section for general configuration (identified by the barman label) a section for each PostgreSQL server to be backed up (identified by the server label, e.g. main or 2 pg) As of version 1.1.2, you can now specify a directory for configuration files similarly to other Linux applications, using the configuration_files_directory option (empty by default). If the value of configuration_files_directory is a directory, Barman will read all the files with .conf extension that exist in that folder. For example, if you set it to /etc/barman.d, you can specify your PostgreSQL servers placing each section in a separate .conf file inside the /etc/barman.d folder. Otherwise, you can use Barmans standard way of specifying sections within the main configuration file.
; Barman, Backup and Recovery Manager for PostgreSQL ; http://www.pgbarman.org/ - http://www.2ndQuadrant.com/ ; ; Main configuration file [barman] ; Main directory barman_home = /var/lib/barman ; System user barman_user = barman ; Log location log_file = /var/log/barman/barman.log ; Default compression level: possible values are None (default), bzip2, gzip or custom ;compression = gzip ; Pre/post backup hook scripts ;pre_backup_script = env | grep ^BARMAN ;post_backup_script = env | grep ^BARMAN ; Pre/post archive hook scripts ;pre_archive_script = env | grep ^BARMAN ;post_archive_script = env | grep ^BARMAN

all and barman are reserved words and cannot be used as server labels

Copyright 2014, 2ndQuadrant Italia

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

; Directory of configuration files. Place your sections in separate files with .conf extension ; For example place the 'main' server section in /etc/barman.d/main.conf ;configuration_files_directory = /etc/barman.d ; Minimum number of required backups (redundancy) ;minimum_redundancy = 0 ; Global retention policy (REDUNDANCY or RECOVERY WINDOW) - default empty ;retention_policy = ; Global bandwidth limit in KBPS - default 0 (meaning no limit) ;bandwidth_limit = 4000 ; Immediate checkpoint for backup command ;immediate_checkpoint = false ; Enable network compression for data transfers ;network_compression = false ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ;; ; 'main' PostgreSQL Server configuration [main] ; Human readable description description = "Main PostgreSQL Database" ; SSH options ssh_command = ssh postgres@pg ; PostgreSQL connection string conninfo = host=pg user=postgres ; Minimum number of required backups (redundancy) ; minimum_redundancy = 1 ; Examples of retention policies ; ; ; ; ; ; Retention policy retention_policy Retention policy retention_policy Retention policy retention_policy (disabled) = (based on redundancy) = REDUNDANCY 2 (based on recovery window) = RECOVERY WINDOW OF 4 WEEKS

You can now test the configuration by executing:

barman@backup$ barman show-server main barman@backup$ barman check main

Write down the incoming_wals_directory, as printed by the barman show-server main command, because you will need it to setup continuous WAL archiving.

Important
Executing these two commands, saves you the time of manually creating backup directories for your servers.

Continuous WAL archiving

Edit the postgresql.conf file of the PostgreSQL instance on the pg database and activate the archive mode:

Copyright 2014, 2ndQuadrant Italia

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

wal_level = 'archive' # For PostgreSQL >= 9.0 archive_mode = on archive_command = 'rsync -a %p barman@backup:INCOMING_WALS_DIRECTORY/%f'

Make sure you change the INCOMING_WALS_DIRECTORY placeholder with the value returned by the barman show-server main command above. In case you use Hot Standby, wal_level must be set to hot_standby. Restart the PostgreSQL server. In order to test that continuous archiving is on and properly working, you need to check both the 3 PostgreSQL server and the backup server (in particular, that the WAL files are collected in the destination directory).

Listing the servers

The following command displays the list of all the available servers:
barman@backup$ barman list-server

Executing a full backup

To take a backup for the main server, issue the following command:
barman@backup$ barman backup main

As of version 1.1.0, you can serialise the backup of your managed servers by using the all target for the server:
barman@backup$ barman backup all

This will iterate through your available servers and sequentially take a backup for each of them.

Immediate Checkpoint
As of version 1.3.0, it is possible to use the immediate_checkpoint configuration global/server option (set to false by default). When issuing a backup, Barman normally waits for the checkpoint to happen on the PostgreSQL server (depending on the configuration settings for workload or time checkpoint control). This might take longer for a backup to start. By setting immediate_checkpoint to true, you can force the checkpoint on the Postgres server to happen immediately and start your backup copy process as soon as possible: At any time, you can override the configuration option behaviour, by issuing barman backup with any of these two options: --immediate-checkpoint, which forces an immediate checkpoint; --no-immediate-checkpoint, which forces to wait for the checkpoint to happen.
3

For more information, refer to the PostgreSQL documentation

Copyright 2014, 2ndQuadrant Italia

10

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

Viewing the list of backups for a server

To list all the available backups for a given server, issue:
barman@backup$ barman list-backup main

the format of the output is as in:

main - 20120529T092136 - Wed May 30 15:20:25 2012 - Size: 5.0 TiB - WAL Size: 845.0 GiB (tablespaces: tb_name:/home/tblspace/name, tb_temp:/home/tblspace/temp)

where 20120529T092136 is the ID of the backup and Wed May 30 15:20:25 2012 is the start time of the operation, Size is the size of the base backup and WAL Size is the size of WAL files archived. As of version 1.1.2, you can get a listing of the available backups for all your servers, using the all target for the server:
barman@backup$ barman list-backup all

Restoring a whole server

To restore a whole server issue the following command:
barman@backup$ barman recover main 20110920T185953 /path/to/recover/directory

where 20110920T185953 is the ID of the backup to be restored. When this command completes succesfully, /path/to/recover/directory contains a complete data directory ready to be started as a PostgreSQL database server. Here is an example of a command that starts the server:
barman@backup$ pg_ctl -D /path/to/recover/directory start

Important
If you run this command as user barman, it will become the database superuser. You can retrieve a list of backup IDs for a specific server with:
barman@backup$ barman list-backup srvpgsql

Important
Barman does not currently keep track of symbolic links inside PGDATA (except for tablespaces inside pg_tblspc). We encourage system administrators to keep track of symbolic links and to add them to the disaster recovery plans/procedures in case they need to be restored in their original location.

Remote recovery
Barman is able to recover a backup on a remote server through the --remote-ssh-command COMMAND option for the recover command.

Copyright 2014, 2ndQuadrant Italia

11

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

If this option is specified, barman uses COMMAND to connect to a remote host.

Note
The postgres user is normally used to recover on a remote host. There are some limitations when using remote recovery. It is important to be aware that: Barman needs at least 4GB of free space in the system temporary directory (usually /tmp); the SSH connection between Barman and the remote host must use public key exchange authentication method; the remote user must be able to create the required destination directories for PGDATA and, where applicable, tablespaces; there must be enough free space on the remote server to contain the base backup and the WAL files needed for recovery.

Relocating one or more tablespaces

Important
Relocating a tablespace is currently available only with local recovery. Barman is able to automatically relocate one or more tablespaces using the recover command with the --tablespace option. The option accepts a pair of values as arguments using the NAME:DIRECTORY format: name/identifier of the tablespace (NAME); destination directory (DIRECTORY). If the destination directory does not exists, Barman will try to create it (assuming you have enough privileges).

Restoring to a given point in time

Barman employs PostgreSQLs Point-in-Time Recovery (PITR) by allowing DBAs to specify a recovery target, either as a timestamp or as a transaction ID; you can also specify whether the recovery target should be included or not in the recovery. The recovery target can be specified using one of three mutually exclusive options: --target-time TARGET_TIME: to specify a timestamp --target-xid TARGET_XID: to specify a transaction ID --target-name TARGET_NAME: to specify a named restore point - previously created with the 4 pg_create_restore_point(name) function You can use the --exclusive option to specify whether to stop immediately before or immediately after the recovery target.
4

Only available for PostgreSQL 9.1 and above users

Copyright 2014, 2ndQuadrant Italia

12

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

Barman allows you to specify a target timeline for recovery, using the target-tli option. The notion of timeline goes beyond the scope of this document; you can find more details in the PostgreSQL documentation, or in one of 2ndQuadrants Recovery training courses.

WAL compression
The barman cron command (see below) will compress WAL files if the compression option is set in the configuration file. This option allows three values: gzip: for Gzip compression (requires gzip) bzip2: for Bzip2 compression (requires bzip2) custom: for custom compression, which requires you to set the following options as well: custom_compression_filter: a compression filter custom_decompression_filter: a decompression filter

Limiting bandwidth usage

From version 1.2.1 it is possible to limit the usage of I/O bandwidth through the bandwidth_limit option (global/per server), by specifying the maximum number of kilobytes per second. By default it is set to 0, meaning no limit. In case you have several tablespaces and you prefer to limit the I/O workload of your backup procedures on one or more tablespaces, you can use the tablespace_bandwidth_limit option (global/per server):
tablespace_bandwidth_limit = tbname:bwlimit[, tbname:bwlimit, ...]

The option accepts a comma separated list of pairs made up of the tablespace name and the bandwidth limit (in kilobytes per second). When backing up a server, Barman will try and locate any existing tablespace in the above option. If found, the specified bandwidth limit will be enforced. If not, the default bandwidth limit for that server will be applied.

Network Compression
From version 1.3.0 it is possible to reduce the size of transferred data using compression. It can be enabled using the network_compression option (global/per server):
network_compression = true|false

Setting this option to true will enable data compression during network transfers (for both backup and recovery). By default it is set to false.

Backup ID shortcuts
As of version 1.1.2, you can use any of the following shortcuts to identify a particular backup for a given server:

Copyright 2014, 2ndQuadrant Italia

13

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

latest: the latest available backup for that server, in chronological order. You can also use the last synonym. oldest: the oldest available backup for that server, in chronological order. You can also use the first synonym. These aliases can be used with any of the following commands: show-backup, delete, listfiles and recover.

Minimum redundancy safety

From version 1.2.0, you can define the minimum number of periodical backups for a PostgreSQL server. You can use the global/per server configuration option called minimum_redundancy for this purpose, by default set to 0. By setting this value to any number greater than 0, Barman makes sure that at any time you will have at least that number of backups in a server catalogue. This will protect you from accidental barman delete operations.

Important
Make sure that your policy retention settings do not collide with minimum redundancy requirements. Regularly check Barmans log for messages on this topic.

Retention policies
From version 1.2.0, Barman supports retention policies for backups. A backup retention policy is an user-defined policy that determines how long backups and related archive logs (Write Ahead Log segments) need to be retained for recovery procedures. Based on the users request, Barman retains the periodical backups required to satisfy the current retention policy, and any archived WAL files required for the complete recovery of those backups. Barman users can define a retention policy in terms of backup redundancy (how many periodical backups) or a recovery window (how long). Retention policy based on redundancy In a retention policy, the setting that determines how many periodical backups to keep. A redundancy-based retention policy is contrasted with retention policy that uses a recovery window. Retention policy based on recovery window A recovery window is one type of Barman backup retention policy, in which the DBA specifies a period of time and Barman ensures retention of backups and/or archived WAL files required for point-in-time recovery to any time during the recovery window. The interval always ends with the current time and extends back in time for the number of days specified by the user. For example, if the retention policy is set for a recovery window of seven days, and the current time is 9:30

Copyright 2014, 2ndQuadrant Italia

14

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

AM on Friday, Barman retains the backups required to allow point-in-time recovery back to 9:30 AM on the previous Friday.

Scope
Retention policies can be defined for: PostgreSQL periodical base backups: through the retention_policy configuration option; Archive logs, for Point-In-Time-Recovery: through the wal_retention_policy configuration option.

Important
In a temporal dimension, archive logs must be included in the time window of periodical backups. There are two typical use cases here: full or partial point-in-time recovery. Full point in time recovery scenario Base backups and archive logs share the same retention policy, allowing DBAs to recover at any point in time from the first available backup. Partial point in time recovery scenario Base backup retention policy is wider than that of archive logs, allowing users for example to keep full weekly backups of the last 6 months, but archive logs for the last 4 weeks (granting to recover at any point in time starting from the last 4 periodical weekly backups).

Important
Currently, Barman implements only the full point in time recovery scenario, by constraining the wal_retention_policy option to main.

How they work

Retention policies in Barman can be: automated: enforced by barman cron; manual: Barman simply reports obsolete backups and allows DBAs to delete them.

Important
Currently Barman does not implement manual enforcement. This feature will be available in future versions.

Configuration and syntax

Retention policies can be defined through the following configuration options: retention_policy: for base backup retention;

Copyright 2014, 2ndQuadrant Italia

15

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

wal_retention_policy: for archive logs retention; retention_policy_mode: can only be set to auto (retention policies are automatically enforced by the barman cron command). These configuration options can be defined both at a global level and a server level, allowing users maximum flexibility on a multi-server environment.

Syntax for retention_policy

The general syntax for a base backup retention policy through retention_policy is the following:
retention_policy = {REDUNDANCY value | RECOVERY WINDOW OF value {DAYS | WEEKS | MONTHS}}

Where: syntax is case insensitive; value is an integer and is > 0; in case of redundancy retention policy: value must be greater than or equal to the server minimum redundancy level (if not is is assigned to that value and a warning is generated); the first valid backup is the value-th backup in a reverse ordered time series; in case of recovery window policy: the point of recoverability is: current time - window; the first valid backup is the first available backup before the point of recoverability; its value in a reverse ordered time series must be greater than or equal to the server minimum redundancy level (if not is is assigned to that value and a warning is generated). By default, retention_policy is empty (no retention enforced).

Syntax for wal_retention_policy

Currently, the only allowed value for wal_retention_policy is the special value main, that maps the retention policy of archive logs to that of base backups.

Available commands
Barman commands are applied to three different levels: general commands, which apply to the backup catalogue server commands, which apply to a specific server (list available backups, execute a backup, etc.) backup commands, which apply to a specific backup in the catalogue (display information, issue a recovery, delete the backup, etc.) In the following sections the available commands will be described in detail.

General commands
List available servers
You can display the list of active servers that have been configured for your backup system with:

Copyright 2014, 2ndQuadrant Italia

16

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

barman list-server

Maintenance mode
You can perform maintenance operations, like compressing WAL files and moving them from the incoming directory to the archived one, with:
barman cron

This command enforces retention policies on those servers that have: retention_policy not empty and valid; retention_policy_mode set to auto.

Note
This command should be executed in a cron script.

Server commands
Show the configuration for a given server
You can show the configuration parameters for a given server with:
barman show-server <server_name>

Take a base backup

You can perform a full backup (base backup) for a given server with:
barman backup [--immediate-checkpoint] <server_name>

Tip
You can use barman backup all to sequentially backup all your configured servers.

Show available backups for a server

You can list the catalogue of available backups for a given server with:
barman list-backup <server_name>

Diagnostics check
You can check if the connection to a given server is properly working with:

Copyright 2014, 2ndQuadrant Italia

17

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

barman check <server_name>

Tip
You can use barman check all to check all your configured servers.

Rebuild the WAL archive

At any time, you can regenerate the content of the WAL archive for a specific server (or every server, using the all shortcut). The WAL archive is contained in the xlog.db file, and every Barman server has its own copy. From version 1.2.4 you can now rebuild the xlog.db file with the rebuild-xlogdb command. This will scan all the archived WAL files and regenerate the metadata for the archive.

Important
Users of Barman < 1.2.3 might have suffered from a bug due to bad locking in highly concurrent environments. You can now regenerate the WAL archive using the rebuildxlogdb command.
barman rebuild-xlogdb <server_name>

Backup commands

Note
Remember: a backup ID can be retrieved with server list <server_name>

Show backup information

You can show all the available information for a particular backup of a given server with:
barman show-backup <server_name> <backup_id>

From version 1.1.2, in order to show the latest backup, you can issue:
barman show-backup <server_name> latest

Delete a backup
You can delete a given backup with:
barman delete <server_name> <backup_id>

From version 1.1.2, in order to delete the oldest backup, you can issue:
barman delete <server_name> oldest

Copyright 2014, 2ndQuadrant Italia

18

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

Warning
Until retention policies are natively supported, you must use the oldest shortcut with extreme care and caution. Iteratively executing this command can easily wipe out your backup archive.

List backup files

You can list the files (base backup and required WAL files) for a given backup with:
barman list-files [--target TARGET_TYPE] <server_name> <backup_id>

With the --target TARGET_TYPE option, it is possible to choose the content of the list for a given backup. Possible values for TARGET_TYPE are: data: lists just the data files; standalone: lists the base backup files, including required WAL files; wal: lists all WAL files from the beginning of the base backup to the start of the following one (or until the end of the log); full: same as data + wal. The default value for TARGET_TYPE is standalone.

Important
The list-files command facilitates interaction with external tools, and therefore can be extremely useful to integrate Barman into your archiving procedures.

Hook scripts
Barman allows a database administrator to run hook scripts on these two events: before and after a backup before and after a WAL file is archived

Important
No check is performed on the exit code of a script. The result will be simply written in the log file.

Backup scripts
Version 1.1.0 introduced backup scripts. These scripts can be configured with the following global configuration options (which can be overridden on a per server basis):

Copyright 2014, 2ndQuadrant Italia

19

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

pre_backup_script: hook script launched before a base backup post_backup_script: hook script launched after a base backup The script definition is passed to a shell and can return any exit code. The shell environment will contain the following variables: BARMAN_BACKUP_DIR: backup destination directory BARMAN_BACKUP_ID: ID of the backup BARMAN_CONFIGURATION: configuration file used by barman BARMAN_ERROR: error message, if any (only for the post phase) BARMAN_PHASE: phase of the script, either pre or post BARMAN_PREVIOUS_ID: ID of the previous backup (if present) BARMAN_SERVER: name of the server BARMAN_STATUS: status of the backup BARMAN_VERSION: version of Barman (from 1.2.1)

WAL archive scripts

Version 1.3.0 introduced WAL archive hook scripts. Similarly to backup scripts, archive scripts can be configured with global configuration options (which can be overridden on a per server basis): pre_archive_script: hook script launched before a WAL file is archived by maintenance (usually barman cron) post_archive_script: hook script launched after a WAL file is archived by maintenance The script is executed through a shell and can return any exit code. Archive scripts share with backup scripts some environmental variables: BARMAN_CONFIGURATION: configuration file used by barman BARMAN_ERROR: error message, if any (only for the post phase) BARMAN_PHASE: phase of the script, either pre or post BARMAN_SERVER: name of the server

Following variables are specific to archive scripts: BARMAN_SEGMENT: name of the WAL file BARMAN_FILE: full path of the WAL file BARMAN_SIZE: size of the WAL file BARMAN_TIMESTAMP: WAL file timestamp BARMAN_COMPRESSION: type of compression used for the WAL file

Support and sponsor opportunities

Barman is free software, written and maintained by 2ndQuadrant. If you require support on using Barman, or if you need new features, please get in touch with 2ndQuadrant. You can sponsor the development of new features of Barman and PostgreSQL which will be made publicly available as open source. For further information, please visit our websites:

Copyright 2014, 2ndQuadrant Italia

20

Barman: Backup and Recovery Manager for PostgreSQL Tutorial

Barman website: http://www.pgbarman.org/ 2ndQuadrant website: http://www.2ndquadrant.com/ Useful information can be found in: the FAQ section of the website: http://www.pgbarman.org/faq/ the "Barman" category of 2ndQuadrants blog: http://blog.2ndquadrant.com/tag/barman/

Authors
In alphabetical order: Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (core team, project leader) Giuseppe Broccolo <giuseppe.broccolo@2ndquadrant.it> (core team, QA) Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (core team, developer) Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (core team, team leader)

Past contributors: Carlo Ascani

Links
check-barman: a Nagios plugin for Barman, written by Holger Hamann (https://github.com/ hamann/check-barman, MIT license)

License and Contributions

Barman is the exclusive property of 2ndQuadrant Italia and its code is distributed under GNU General Public License 3. Copyright 2011-2014 2ndQuadrant.it. Barman has been partially funded through 4CaaSt, a research project funded by the European Commissions Seventh Framework programme. Contributions to Barman are welcome, and will be listed in the file AUTHORS. 2ndQuadrant Italia requires that any contributions provide a copyright assignment and a disclaimer of any work-for-hire ownership claims from the employer of the developer. This lets us make sure that all of the Barman distribution remains free code. Please contact info@2ndQuadrant.it for a copy of the relevant Copyright Assignment Form.

Copyright 2014, 2ndQuadrant Italia

21