.\" Automatically generated by Pandoc 2.5 .\" .TH "BARMAN" "5" "February 4, 2019" "Barman User manuals" "Version 2.6" .hy .SH NAME .PP barman \- Backup and Recovery Manager for PostgreSQL .SH DESCRIPTION .PP Barman is an administration tool for disaster recovery of PostgreSQL servers written in Python and maintained by 2ndQuadrant. Barman can perform remote backups of multiple servers in business critical environments and helps DBAs during the recovery phase. .SH CONFIGURATION FILE LOCATIONS .PP The system\-level Barman configuration file is located at .IP .nf \f[C] /etc/barman.conf \f[R] .fi .PP or .IP .nf \f[C] /etc/barman/barman.conf \f[R] .fi .PP and is overridden on a per\-user level by .IP .nf \f[C] $HOME/.barman.conf \f[R] .fi .SH CONFIGURATION FILE SYNTAX .PP The Barman configuration file is a plain \f[C]INI\f[R] file. There is a general section called \f[C][barman]\f[R] and a section \f[C][servername]\f[R] for each server you want to backup. Rows starting with \f[C];\f[R] are comments. .SH CONFIGURATION FILE DIRECTORY .PP Barman supports the inclusion of multiple configuration files, through the \f[C]configuration_files_directory\f[R] option. Included files must contain only server specifications, not global configurations. If the value of \f[C]configuration_files_directory\f[R] is a directory, Barman reads all files with \f[C].conf\f[R] extension that exist in that folder. For example, if you set it to \f[C]/etc/barman.d\f[R], you can specify your PostgreSQL servers placing each section in a separate \f[C].conf\f[R] file inside the \f[C]/etc/barman.d\f[R] folder. .SH OPTIONS .TP .B active When set to \f[C]true\f[R] (default), the server is in full operational state. When set to \f[C]false\f[R], the server can be used for diagnostics, but any operational command such as backup execution or WAL archiving is temporarily disabled. Setting \f[C]active=false\f[R] is a good practice when adding a new node to Barman. Server. .TP .B archiver This option allows you to activate log file shipping through PostgreSQL\[aq]s \f[C]archive_command\f[R] for a server. If set to \f[C]true\f[R] (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 \f[I]incoming\f[R] directory. Setting it to \f[C]false\f[R], will disable standard continuous archiving for a server. Global/Server. .TP .B archiver_batch_size This option allows you to activate batch processing of WAL files for the \f[C]archiver\f[R] 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 \f[C]archive\-wal\f[R] process would limit itself to maximum \f[C]archiver_batch_size\f[R] WAL segments per single run. Integer. Global/Server. .TP .B backup_directory Directory where backup data for a server will be placed. Server. .TP .B backup_method Configure the method barman used for backup execution. If set to \f[C]rsync\f[R] (default), barman will execute backup using the \f[C]rsync\f[R] command. If set to \f[C]postgres\f[R] barman will use the \f[C]pg_basebackup\f[R] command to execute the backup. Global/Server. .TP .B 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: .RS .IP \[bu] 2 \f[C]exclusive_backup\f[R] (default when \f[C]backup_method = rsync\f[R]): \f[C]barman backup\f[R] executes backup operations using the standard exclusive backup approach (technically through \f[C]pg_start_backup\f[R] and \f[C]pg_stop_backup\f[R]) .IP \[bu] 2 \f[C]concurrent_backup\f[R] (default when \f[C]backup_method = postgres\f[R]): if using PostgreSQL 9.2, 9.3, 9.4, and 9.5, Barman requires the \f[C]pgespresso\f[R] 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. .IP \[bu] 2 \f[C]external_configuration\f[R]: if present, any warning regarding external configuration files is suppressed during the execution of a backup. .PP Note that \f[C]exclusive_backup\f[R] and \f[C]concurrent_backup\f[R] are mutually exclusive. Global/Server. .RE .TP .B bandwidth_limit This option allows you to specify a maximum transfer rate in kilobytes per second. A value of zero specifies no limit (default). Global/Server. .TP .B barman_home Main data directory for Barman. Global. .TP .B barman_lock_directory Directory for locks. Default: \f[C]%(barman_home)s\f[R]. Global. .TP .B basebackup_retry_sleep Number of seconds of wait after a failed copy, before retrying Used during both backup and recovery operations. Positive integer, default 30. Global/Server. .TP .B basebackup_retry_times Number of retries of base backup copy, after an error. Used during both backup and recovery operations. Positive integer, default 0. Global/Server. .TP .B basebackups_directory Directory where base backups will be placed. Server. .TP .B 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. .TP .B compression Standard compression algorithm applied to WAL files. Possible values are: \f[C]gzip\f[R] (requires \f[C]gzip\f[R] to be installed on the system), \f[C]bzip2\f[R] (requires \f[C]bzip2\f[R]), \f[C]pigz\f[R] (requires \f[C]pigz\f[R]), \f[C]pygzip\f[R] (Python\[aq]s internal gzip compressor) and \f[C]pybzip2\f[R] (Python\[aq]s internal bzip2 compressor). Global/Server. .TP .B 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-connect.html#LIBPQ-CONNSTRING) for more information. Commonly used keys are: host, hostaddr, port, dbname, user, password. Server. .TP .B custom_compression_filter Customised compression algorithm applied to WAL files. Global/Server. .TP .B custom_decompression_filter Customised decompression algorithm applied to compressed WAL files; this must match the compression algorithm. Global/Server. .TP .B description A human readable description of a server. Server. .TP .B 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). .TP .B immediate_checkpoint This option allows you to control the way PostgreSQL handles checkpoint at the start of the backup. If set to \f[C]false\f[R] (default), the I/O workload for the checkpoint will be limited, according to the \f[C]checkpoint_completion_target\f[R] setting on the PostgreSQL server. If set to \f[C]true\f[R], an immediate checkpoint will be requested, meaning that PostgreSQL will complete the checkpoint as soon as possible. Global/Server. .TP .B incoming_wals_directory Directory where incoming WAL files are archived into. Requires \f[C]archiver\f[R] to be enabled. Server. .TP .B 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 (default), latest backup is always considered valid. Syntax for this option is: \[dq]i (DAYS | WEEKS | MONTHS)\[dq] where i is a integer greater than zero, representing the number of days | weeks | months of the time frame. Global/Server. .TP .B log_file Location of Barman\[aq]s log file. Global. .TP .B log_level Level of logging (DEBUG, INFO, WARNING, ERROR, CRITICAL). Global. .TP .B 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. Default: None (disabled). .TP .B minimum_redundancy Minimum number of backups to be retained. Default 0. Global/Server. .TP .B network_compression This option allows you to enable data compression for network transfers. If set to \f[C]false\f[R] (default), no compression is used. If set to \f[C]true\f[R], compression is enabled, reducing network usage. Global/Server. .TP .B parallel_jobs This option controls how many parallel workers will copy files during a backup or recovery command. Default 1. Global/Server. For backup purposes, it works only when \f[C]backup_method\f[R] is \f[C]rsync\f[R]. .TP .B path_prefix One or more absolute paths, separated by colon, where Barman looks for executable files. The paths specified in \f[C]path_prefix\f[R] are tried before the ones specified in \f[C]PATH\f[R] environment variable. Global/server. .TP .B post_archive_retry_script Hook script launched after a WAL file is archived by maintenance. Being this a \f[I]retry\f[R] 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 currently the same effects as ABORT_CONTINUE. Global/Server. .TP .B post_archive_script Hook script launched after a WAL file is archived by maintenance, after \[aq]post_archive_retry_script\[aq]. Global/Server. .TP .B post_backup_retry_script Hook script launched after a base backup. Being this a \f[I]retry\f[R] 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. .TP .B post_backup_script Hook script launched after a base backup, after \[aq]post_backup_retry_script\[aq]. Global/Server. .TP .B post_delete_retry_script Hook script launched after the deletion of a backup. Being this a \f[I]retry\f[R] 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 delete scenario, ABORT_STOP has currently the same effects as ABORT_CONTINUE. Global/Server. .TP .B post_delete_script Hook script launched after the deletion of a backup, after \[aq]post_delete_retry_script\[aq]. Global/Server. .TP .B post_recovery_retry_script Hook script launched after a recovery. Being this a \f[I]retry\f[R] 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 recovery scenario, ABORT_STOP has currently the same effects as ABORT_CONTINUE. Global/Server. .TP .B post_recovery_script Hook script launched after a recovery, after \[aq]post_recovery_retry_script\[aq]. Global/Server. .TP .B post_wal_delete_retry_script Hook script launched after the deletion of a WAL file. Being this a \f[I]retry\f[R] 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 delete scenario, ABORT_STOP has currently the same effects as ABORT_CONTINUE. Global/Server. .TP .B post_wal_delete_script Hook script launched after the deletion of a WAL file, after \[aq]post_wal)delete_retry_script\[aq]. Global/Server. .TP .B pre_archive_retry_script Hook script launched before a WAL file is archived by maintenance, after \[aq]pre_archive_script\[aq]. Being this a \f[I]retry\f[R] 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. Global/Server. .TP .B pre_archive_script Hook script launched before a WAL file is archived by maintenance. Global/Server. .TP .B pre_backup_retry_script Hook script launched before a base backup, after \[aq]pre_backup_script\[aq]. Being this a \f[I]retry\f[R] 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. .TP .B pre_backup_script Hook script launched before a base backup. Global/Server. .TP .B pre_delete_retry_script Hook script launched before the deletion of a backup, after \[aq]pre_delete_script\[aq]. Being this a \f[I]retry\f[R] 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 deletion. Global/Server. .TP .B pre_delete_script Hook script launched before the deletion of a backup. Global/Server. .TP .B pre_recovery_retry_script Hook script launched before a recovery, after \[aq]pre_recovery_script\[aq]. Being this a \f[I]retry\f[R] 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 recover operation. Global/Server. .TP .B pre_recovery_script Hook script launched before a recovery. Global/Server. .TP .B pre_wal_delete_retry_script Hook script launched before the deletion of a WAL file, after \[aq]pre_wal_delete_script\[aq]. Being this a \f[I]retry\f[R] 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 file deletion. Global/Server. .TP .B pre_wal_delete_script Hook script launched before the deletion of a WAL file. Global/Server. .TP .B primary_ssh_command Parameter that identifies a Barman server as \f[C]passive\f[R]. In a passive node, the source of a backup server is a Barman installation rather than a PostgreSQL server. If \f[C]primary_ssh_command\f[R] is specified, Barman uses it to enstablish a connection with the primary server. Empty by default, it can also be set globally. .TP .B recovery_options Options for recovery operations. Currently only supports \f[C]get\-wal\f[R]. \f[C]get\-wal\f[R] activates generation of a basic \f[C]restore_command\f[R] in the resulting \f[C]recovery.conf\f[R] file that uses the \f[C]barman get\-wal\f[R] command to fetch WAL files directly from Barman\[aq]s archive of WALs. Comma separated list of values, default empty. Global/Server. .TP .B 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 \[dq]REDUNDANCY i\[dq] (where i is an integer > 0 and defines the number of backups to retain). For recovery window retention policy use \[dq]RECOVERY WINDOW OF i DAYS\[dq] or \[dq]RECOVERY WINDOW OF i WEEKS\[dq] or \[dq]RECOVERY WINDOW OF i MONTHS\[dq] 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. .TP .B retention_policy_mode Currently only \[dq]auto\[dq] is implemented. Global/Server. .TP .B reuse_backup This option controls incremental backup support. Global/Server. Possible values are: .RS .IP \[bu] 2 \f[C]off\f[R]: disabled (default); .IP \[bu] 2 \f[C]copy\f[R]: reuse the last available backup for a server and create a copy of the unchanged files (reduce backup time); .IP \[bu] 2 \f[C]link\f[R]: reuse the last available backup for a server and create a hard link of the unchanged files (reduce backup time and space). Requires operating system and file system support for hard links. .RE .TP .B slot_name Physical replication slot to be used by the \f[C]receive\-wal\f[R] command when \f[C]streaming_archiver\f[R] is set to \f[C]on\f[R]. Requires PostgreSQL >= 9.4. Global/Server. Default: None (disabled). .TP .B ssh_command Command used by Barman to login to the Postgres server via ssh. Server. .TP .B streaming_archiver This option allows you to use the PostgreSQL\[aq]s streaming protocol to receive transaction logs from a server. If set to \f[C]on\f[R], Barman expects to find \f[C]pg_receivewal\f[R] (known as \f[C]pg_receivexlog\f[R] prior to PostgreSQL 10) in the PATH (see \f[C]path_prefix\f[R] option) 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 \f[C]off\f[R] (default) barman will rely only on continuous archiving for a server WAL archive operations, eventually terminating any running \f[C]pg_receivexlog\f[R] for the server. Global/Server. .TP .B streaming_archiver_batch_size This option allows you to activate batch processing of WAL files for the \f[C]streaming_archiver\f[R] 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 \f[C]archive\-wal\f[R] process would limit itself to maximum \f[C]streaming_archiver_batch_size\f[R] WAL segments per single run. Integer. Global/Server. .TP .B streaming_archiver_name Identifier to be used as \f[C]application_name\f[R] by the \f[C]receive\-wal\f[R] command. Only available with \f[C]pg_receivewal\f[R] (or \f[C]pg_receivexlog\f[R] >= 9.3). By default it is set to \f[C]barman_receive_wal\f[R]. Global/Server. .TP .B streaming_backup_name Identifier to be used as \f[C]application_name\f[R] by the \f[C]pg_basebackup\f[R] command. Only available with \f[C]pg_basebackup\f[R] >= 9.3. By default it is set to \f[C]barman_streaming_backup\f[R]. Global/Server. .TP .B streaming_conninfo Connection string used by Barman to connect to the Postgres server via streaming replication protocol. By default it is set to \f[C]conninfo\f[R]. Server. .TP .B streaming_wals_directory Directory where WAL files are streamed from the PostgreSQL server to Barman. Requires \f[C]streaming_archiver\f[R] to be enabled. Server. .TP .B 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. .TP .B wal_retention_policy Policy for retention of archive logs (WAL files). Currently only \[dq]MAIN\[dq] is available. Global/Server. .TP .B wals_directory Directory which contains WAL files. Server. .SH HOOK SCRIPTS .PP The script definition is passed to a shell and can return any exit code. .PP The shell environment will contain the following variables: .TP .B \f[C]BARMAN_CONFIGURATION\f[R] configuration file used by barman .TP .B \f[C]BARMAN_ERROR\f[R] error message, if any (only for the \[aq]post\[aq] phase) .TP .B \f[C]BARMAN_PHASE\f[R] \[aq]pre\[aq] or \[aq]post\[aq] .TP .B \f[C]BARMAN_RETRY\f[R] \f[C]1\f[R] if it is a \f[I]retry script\f[R] (from 1.5.0), \f[C]0\f[R] if not .TP .B \f[C]BARMAN_SERVER\f[R] name of the server .PP Backup scripts specific variables: .TP .B \f[C]BARMAN_BACKUP_DIR\f[R] backup destination directory .TP .B \f[C]BARMAN_BACKUP_ID\f[R] ID of the backup .TP .B \f[C]BARMAN_PREVIOUS_ID\f[R] ID of the previous backup (if present) .TP .B \f[C]BARMAN_NEXT_ID\f[R] ID of the next backup (if present) .TP .B \f[C]BARMAN_STATUS\f[R] status of the backup .TP .B \f[C]BARMAN_VERSION\f[R] version of Barman .PP Archive scripts specific variables: .TP .B \f[C]BARMAN_SEGMENT\f[R] name of the WAL file .TP .B \f[C]BARMAN_FILE\f[R] full path of the WAL file .TP .B \f[C]BARMAN_SIZE\f[R] size of the WAL file .TP .B \f[C]BARMAN_TIMESTAMP\f[R] WAL file timestamp .TP .B \f[C]BARMAN_COMPRESSION\f[R] type of compression used for the WAL file .PP Recovery scripts specific variables: .TP .B \f[C]BARMAN_DESTINATION_DIRECTORY\f[R] the directory where the new instance is recovered .TP .B \f[C]BARMAN_TABLESPACES\f[R] tablespace relocation map (JSON, if present) .TP .B \f[C]BARMAN_REMOTE_COMMAND\f[R] secure shell command used by the recovery (if present) .TP .B \f[C]BARMAN_RECOVER_OPTIONS\f[R] recovery additional options (JSON, if present) .PP 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. .SH EXAMPLE .PP Here is an example of configuration file: .IP .nf \f[C] [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 ; \[aq]main\[aq] PostgreSQL Server configuration [main] ; Human readable description description = \[dq]Main PostgreSQL Database\[dq] ; SSH options ssh_command = ssh postgres\[at]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 \f[R] .fi .SH SEE ALSO .PP \f[C]barman\f[R] (1). .SH AUTHORS .PP In alphabetical order: .IP \[bu] 2 Gabriele Bartolini (architect) .IP \[bu] 2 Jonathan Battiato (QA/testing) .IP \[bu] 2 Giulio Calacoci (developer) .IP \[bu] 2 Francesco Canovai (QA/testing) .IP \[bu] 2 Leonardo Cecchi (developer) .IP \[bu] 2 Gianni Ciolli (QA/testing) .IP \[bu] 2 Britt Cole (documentation) .IP \[bu] 2 Marco Nenciarini (project leader) .IP \[bu] 2 Rubens Souza (QA/testing) .PP Past contributors: .IP \[bu] 2 Carlo Ascani .IP \[bu] 2 Stefano Bianucci .IP \[bu] 2 Giuseppe Broccolo .SH RESOURCES .IP \[bu] 2 Homepage: .IP \[bu] 2 Documentation: .IP \[bu] 2 Professional support: .SH COPYING .PP Barman is the property of 2ndQuadrant Limited and its code is distributed under GNU General Public License v3. .PP Copyright (C) 2011\-2019 2ndQuadrant Limited \- https://www.2ndQuadrant.com/. .SH AUTHORS 2ndQuadrant Limited .