Ubuntu Manpage: barman - Backup and Recovery Manager for PostgreSQL

NAME

       barman - Backup and Recovery Manager for PostgreSQL

DESCRIPTION

       Barman  is an administration tool for disaster recovery of PostgreSQL servers written in Python and main‐
       tained by 2ndQuadrant.  Barman can perform remote backups of multiple servers in business critical  envi‐
       ronments and helps DBAs during the recovery phase.

CONFIGURATION FILE LOCATIONS

       The system-level Barman configuration file is located at

              /etc/barman.conf

       or

              /etc/barman/barman.conf

       and is overridden on a per-user level by

              $HOME/.barman.conf

CONFIGURATION FILE SYNTAX

       The Barman configuration file is a plain INI file.  There is a general section called [barman] and a sec‐
       tion [servername] for each server you want to backup.  Rows starting with ; are comments.

CONFIGURATION FILE DIRECTORY

       Barman  supports the inclusion of multiple configuration files, through the configuration_files_directory
       option.  Included files must contain only server specifications, not global configurations.  If the value
       of configuration_files_directory is a directory, Barman reads all 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.

OPTIONS

active When set to true (default), the server is in full operational state. When set to false, the serv‐
er can be used for diagnostics, but any operational command such as backup execution or WAL
archiving is temporarily disabled. Setting active=false is a good practice when adding a new node
to Barman. Server.

archiver
This option allows you to activate log file shipping through PostgreSQL's archive_command for a
server. If set to true (default), Barman expects that continuous archiving for a server is in
place and will activate checks as well as management (including compression) of WAL files that
Postgres deposits in the incoming directory. Setting it to false, will disable standard continu‐
ous archiving for a server. Global/Server.

archiver_batch_size
This option allows you to activate batch processing of WAL files for the archiver process, by set‐
ting it to a value > 0. Otherwise, the traditional unlimited processing of the WAL queue is en‐
abled. When batch processing is activated, the archive-wal process would limit itself to maximum
archiver_batch_size WAL segments per single run. Integer. Global/Server.

backup_directory
Directory where backup data for a server will be placed. Server.

backup_method
Configure the method barman used for backup execution. If set to rsync (default), barman will ex‐
ecute backup using the rsync command. If set to postgres barman will use the pg_basebackup com‐
mand to execute the backup. Global/Server.

backup_options
This option allows you to control the way Barman interacts with PostgreSQL for backups. It is a
comma-separated list of values that accepts the following options:

• exclusive_backup (default when backup_method = rsync): barman backup executes backup operations
using the standard exclusive backup approach (technically through pg_start_backup and
pg_stop_backup)

• concurrent_backup (default when backup_method = postgres): if using PostgreSQL 9.2, 9.3, 9.4,
and 9.5, Barman requires the pgespresso module to be installed on the PostgreSQL server and can
be used to perform a backup from a standby server. Starting from PostgreSQL 9.6, Barman uses
the new PostgreSQL API to perform backups from a standby server.

• external_configuration: if present, any warning regarding external configuration files is sup‐
pressed during the execution of a backup.

Note that exclusive_backup and concurrent_backup are mutually exclusive. Global/Server.

bandwidth_limit
This option allows you to specify a maximum transfer rate in kilobytes per second. A value of ze‐
ro specifies no limit (default). Global/Server.

barman_home
Main data directory for Barman. Global.

barman_lock_directory
Directory for locks. Default: %(barman_home)s. Global.

basebackups_directory
Directory where base backups will be placed. Server.

basebackup_retry_sleep
Number of seconds of wait after a failed copy, before retrying Used during both backup and recov‐
ery operations. Positive integer, default 30. Global/Server.

basebackup_retry_times
Number of retries of base backup copy, after an error. Used during both backup and recovery oper‐
ations. Positive integer, default 0. Global/Server.

check_timeout
Maximum execution time, in seconds per server, for a barman check command. Set to 0 to disable
the timeout. Positive integer, default 30. Global/Server.

compression
Standard compression algorithm applied to WAL files. Possible values are: gzip (requires gzip to
be installed on the system), bzip2 (requires bzip2), pigz (requires pigz), pygzip (Python's inter‐
nal gzip compressor) and pybzip2 (Python's internal bzip2 compressor). Global/Server.

conninfo
Connection string used by Barman to connect to the Postgres server. This is a libpq connection
string, consult the PostgreSQL manual (https://www.postgresql.org/docs/current/static/libpq-con‐
nect.html#LIBPQ-CONNSTRING) for more information. Commonly used keys are: host, hostaddr, port,
dbname, user, password. Server.

custom_compression_filter
Customised compression algorithm applied to WAL files. Global/Server.

custom_decompression_filter
Customised decompression algorithm applied to compressed WAL files; this must match the compres‐
sion algorithm. Global/Server.

description
A human readable description of a server. Server.

errors_directory
Directory that contains WAL files that contain an error; usually this is related to a conflict
with an existing WAL file (e.g. a WAL file that has been archived after a streamed one).

immediate_checkpoint
This option allows you to control the way PostgreSQL handles checkpoint at the start of the back‐
up. If set to false (default), the I/O workload for the checkpoint will be limited, according to
the checkpoint_completion_target setting on the PostgreSQL server. If set to true, an immediate
checkpoint will be requested, meaning that PostgreSQL will complete the checkpoint as soon as pos‐
sible. Global/Server.

incoming_wals_directory
Directory where incoming WAL files are archived into. Requires archiver to be enabled. Server.

last_backup_maximum_age
This option identifies a time frame that must contain the latest backup. If the latest backup is
older than the time frame, barman check command will report an error to the user. If empty (de‐
fault), latest backup is always considered valid. Syntax for this option is: "i (DAYS | WEEKS |
MONTHS)" where i is a integer greater than zero, representing the number of days | weeks | months
of the time frame. Global/Server.

log_file
Location of Barman's log file. Global.

log_level
Level of logging (DEBUG, INFO, WARNING, ERROR, CRITICAL). Global.

max_incoming_wals_queue
Maximum number of WAL files in the incoming queue (in both streaming and archiving pools) that are
allowed before barman check returns an error (that does not block backups). Global/Server. De‐
fault: None (disabled).

minimum_redundancy
Minimum number of backups to be retained. Default 0. Global/Server.

network_compression
This option allows you to enable data compression for network transfers. If set to false (de‐
fault), no compression is used. If set to true, compression is enabled, reducing network usage.
Global/Server.

parallel_jobs
This option controls how many parallel workers will copy files during a backup or recovery com‐
mand. Default 1. Global/Server. For backup purposes, it works only when backup_method is rsync.

path_prefix
One or more absolute paths, separated by colon, where Barman looks for executable files. The
paths specified in path_prefix are tried before the ones specified in PATH environment variable.
Global/server.

post_archive_retry_script
Hook script launched after a WAL file is archived by maintenance. Being this a retry hook script,
Barman will retry the execution of the script until this either returns a SUCCESS (0), an
ABORT_CONTINUE (62) or an ABORT_STOP (63) code. In a post archive scenario, ABORT_STOP has cur‐
rently the same effects as ABORT_CONTINUE. Global/Server.

post_archive_script
Hook script launched after a WAL file is archived by maintenance, after
'post_archive_retry_script'. Global/Server.

post_backup_retry_script
Hook script launched after a base backup. Being this a retry hook script, Barman will retry the
execution of the script until this either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
ABORT_STOP (63) code. In a post backup scenario, ABORT_STOP has currently the same effects as
ABORT_CONTINUE. Global/Server.

post_backup_script
Hook script launched after a base backup, after 'post_backup_retry_script'. Global/Server.

pre_archive_retry_script
Hook script launched before a WAL file is archived by maintenance, after 'pre_archive_script'.
Being this a retry hook script, Barman will retry the execution of the script until this either
returns a SUCCESS (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. Returning ABORT_STOP
will propagate the failure at a higher level and interrupt the WAL archiving operation. Glob‐
al/Server.

pre_archive_script
Hook script launched before a WAL file is archived by maintenance. Global/Server.

pre_backup_retry_script
Hook script launched before a base backup, after 'pre_backup_script'. Being this a retry hook
script, Barman will retry the execution of the script until this either returns a SUCCESS (0), an
ABORT_CONTINUE (62) or an ABORT_STOP (63) code. Returning ABORT_STOP will propagate the failure
at a higher level and interrupt the backup operation. Global/Server.

pre_backup_script
Hook script launched before a base backup. Global/Server.

recovery_options
Options for recovery operations. Currently only supports get-wal. get-wal activates generation
of a basic restore_command in the resulting recovery.conf file that uses the barman get-wal com‐
mand to fetch WAL files directly from Barman's archive of WALs. Comma separated list of values,
default empty. Global/Server.

retention_policy
Policy for retention of periodic backups and archive logs. If left empty, retention policies are
not enforced. For redundancy based retention policy use "REDUNDANCY i" (where i is an integer > 0
and defines the number of backups to retain). For recovery window retention policy use "RECOVERY
WINDOW OF i DAYS" or "RECOVERY WINDOW OF i WEEKS" or "RECOVERY WINDOW OF i MONTHS" where i is a
positive integer representing, specifically, the number of days, weeks or months to retain your
backups. For more detailed information, refer to the official documentation. Default value is
empty. Global/Server.

retention_policy_mode
Currently only "auto" is implemented. Global/Server.

reuse_backup
This option controls incremental backup support. Global/Server. Possible values are: * off: dis‐
abled (default); * copy: reuse the last available backup for a server and create a copy of the un‐
changed files (reduce backup time); * link: reuse the last available backup for a server and cre‐
ate a hard link of the unchanged files (reduce backup time and space). Requires operating system
and file system support for hard links.

slot_name
Physical replication slot to be used by the receive-wal command when streaming_archiver is set to
on. Requires PostgreSQL >= 9.4. Global/Server. Default: None (disabled).

streaming_archiver
This option allows you to use the PostgreSQL's streaming protocol to receive transaction logs from
a server. If set to on, Barman expects to find pg_receivexlog in the PATH (see path_prefix op‐
tion) and that streaming connection for the server is working. This activates connection checks
as well as management (including compression) of WAL files. If set to off (default) barman will
rely only on continuous archiving for a server WAL archive operations, eventually terminating any
running pg_receivexlog for the server. Global/Server.

streaming_archiver_batch_size
This option allows you to activate batch processing of WAL files for the streaming_archiver
process, by setting it to a value > 0. Otherwise, the traditional unlimited processing of the WAL
queue is enabled. When batch processing is activated, the archive-wal process would limit itself
to maximum streaming_archiver_batch_size WAL segments per single run. Integer. Global/Server.

streaming_archiver_name
Identifier to be used as application_name by the receive-wal command. Only available with pg_re‐
ceivexlog >= 9.3. By default it is set to barman_receive_wal. Global/Server.

streaming_backup_name
Identifier to be used as application_name by the pg_basebackup command. Only available with
pg_basebackup >= 9.3. By default it is set to barman_streaming_backup. Global/Server.

streaming_conninfo
Connection string used by Barman to connect to the Postgres server via streaming replication pro‐
tocol. By default it is set to conninfo. Server.

streaming_wals_directory
Directory where WAL files are streamed from the PostgreSQL server to Barman. Requires stream‐
ing_archiver to be enabled. Server.

ssh_command
Command used by Barman to login to the Postgres server via ssh. Server.

tablespace_bandwidth_limit
This option allows you to specify a maximum transfer rate in kilobytes per second, by specifying a
comma separated list of tablespaces (pairs TBNAME:BWLIMIT). A value of zero specifies no limit
(default). Global/Server.

wal_retention_policy
Policy for retention of archive logs (WAL files). Currently only "MAIN" is available. Glob‐
al/Server.

wals_directory
Directory which contains WAL files. Server.

HOOK SCRIPTS

       The script definition is passed to a shell and can return any exit code.

       The shell environment will contain the following variables:

       BARMAN_CONFIGURATION
              configuration file used by barman

       BARMAN_ERROR
              error message, if any (only for the 'post' phase)

       BARMAN_PHASE
              'pre' or 'post'

       BARMAN_RETRY
              1 if it is a retry script (from 1.5.0), 0 if not

       BARMAN_SERVER
              name of the server

       Backup scripts specific variables:

       BARMAN_BACKUP_DIR
              backup destination directory

       BARMAN_BACKUP_ID
              ID of the backup

       BARMAN_PREVIOUS_ID
              ID of the previous backup (if present)

       BARMAN_STATUS
              status of the backup

       BARMAN_VERSION
              version of Barman

       Archive scripts specific variables:

       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

       Only in case of retry hook scripts, the exit code of the script is checked by  Barman.   Output  of  hook
       scripts is simply written in the log file.

EXAMPLE

       Here is an example of 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
              ;compression = gzip

              ; Incremental backup
              reuse_backup = link

              ; '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

              ; PostgreSQL streaming connection string
              streaming_conninfo = host=pg user=postgres

              ; Minimum number of required backups (redundancy)
              minimum_redundancy = 1

              ; Retention policy (based on redundancy)
              retention_policy = REDUNDANCY 2

AUTHORS

       In alphabetical order:

       • Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (architect)

       • Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)

       • Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)

       • Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)

       • Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)

       • Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)

       • Britt Cole <britt.cole@2ndquadrant.com> (documentation)

       • Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (project leader)

       • Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)

       Past contributors:

       • Carlo Ascani

       • Stefano Bianucci

       • Giuseppe Broccolo

RESOURCES

       • Homepage: <http://www.pgbarman.org/>

       • Documentation: <http://docs.pgbarman.org/>

       • Professional support: <https://www.2ndQuadrant.com/>

COPYING

       Barman  is  the  property of 2ndQuadrant Limited and its code is distributed under GNU General Public Li‐
       cense v3.

       Copyright (C) 2011-2017 2ndQuadrant Limited - https://www.2ndQuadrant.com/.

AUTHORS

       2ndQuadrant Limited <https://www.2ndQuadrant.com>.

Barman User manuals                            September 05, 2017                                      BARMAN(5)

NAME

DESCRIPTION

CONFIGURATION FILE LOCATIONS

CONFIGURATION FILE SYNTAX

CONFIGURATION FILE DIRECTORY

OPTIONS

HOOK SCRIPTS

EXAMPLE

SEE ALSO

AUTHORS

RESOURCES

COPYING

AUTHORS