barman - Man Page

barman [Options] COMMAND

Barman is an administration tool for disaster recovery of PostgreSQL servers written in Python and maintained by EnterpriseDB. Barman can perform remote backups of multiple servers in business critical environments and helps DBAs during the recovery phase.

-h,  --help

Show a help message and exit.

-v,  --version

Show program version number and exit.

-c CONFIG, --config CONFIG

Use the specified configuration file.

--color {never,always,auto}, --colour {never,always,auto}

Whether to use colors in the output (default: auto)

-q,  --quiet

Do not output anything. Useful for cron scripts.

-d,  --debug

debug output (default: False)

--log-level {NOTSET,DEBUG,INFO,WARNING,ERROR,CRITICAL}

Override the default log level

-f {json,console}, --format {json,console}

output format (default: 'console')

Important: every command has a help option

archive-wal SERVER_NAME

Get any incoming xlog file (both through standard archive_command and streaming replication, where applicable) and moves them in the WAL archive for that server. If necessary, apply compression when requested by the user.

backup SERVER_NAME

Perform a backup of SERVER_NAME using parameters specified in the configuration file. Specify all as SERVER_NAME to perform a backup of all the configured servers. You can also specify SERVER_NAME multiple times to perform a backup of the specified servers -- e.g. barman backup SERVER_1_NAME SERVER_2_NAME.

--name

a friendly name for this backup which can be used in place of the backup ID in barman commands.

--immediate-checkpoint

forces the initial checkpoint to be done as quickly as possible. Overrides value of the parameter immediate_checkpoint, if present in the configuration file.

--no-immediate-checkpoint

forces to wait for the checkpoint. Overrides value of the parameter immediate_checkpoint, if present in the configuration file.

--incremental [BACKUP_ID]

performs a block-level incremental backup. A BACKUP_ID or backup ID shortcut of a previous backup must be provided, which references a previous backup in the catalog to be used as the parent backup from which the incremental is taken.

--reuse-backup [INCREMENTAL_TYPE]

Overrides reuse_backup option behaviour. Possible values for INCREMENTAL_TYPE are:

• off: do not reuse the last available backup;
• copy: reuse the last available backup for a server and create a copy of the unchanged files (reduce backup time);
• link: reuse the last available backup for a server and create a hard link of the unchanged files (reduce backup time and space);

link is the default target if --reuse-backup is used and INCREMENTAL_TYPE is not explicit.

--retry-times

Number of retries of base backup copy, after an error. Used during both backup and recovery operations. Overrides value of the parameter basebackup_retry_times, if present in the configuration file.

--no-retry

Same as --retry-times 0

--retry-sleep

Number of seconds of wait after a failed copy, before retrying. Used during both backup and recovery operations. Overrides value of the parameter basebackup_retry_sleep, if present in the configuration file.

-j, --jobs

Number of parallel workers to copy files during backup. Overrides value of the parameter parallel_jobs, if present in the configuration file.

--jobs-start-batch-period

The time period in seconds over which a single batch of jobs will be started. Overrides the value of parallel_jobs_start_batch_period, if present in the configuration file. Defaults to 1 second.

--jobs-start-batch-size

Maximum number of parallel workers to start in a single batch. Overrides the value of parallel_jobs_start_batch_size, if present in the configuration file. Defaults to 10 jobs.

--bwlimit KBPS

maximum transfer rate in kilobytes per second. A value of 0 means no limit. Overrides 'bandwidth_limit' configuration option. Default is undefined.

--wait, -w

wait for all required WAL files by the base backup to be archived

--wait-timeout

the time, in seconds, spent waiting for the required WAL files to be archived before timing out

--keepalive-interval

an interval, in seconds, at which a hearbeat query will be sent to the server to keep the libpq connection alive during an Rsync backup. Default is 60. A value of 0 disables it.

--manifest

forces the creation of a backup manifest file at the end of a backup. Overrides value of the parameter autogenerate_manifest, from the configuration file. Works with rsync backup method and strategies only

--no-manifest

disables the automatic creation of a backup manifest file at the end of a backup. Overrides value of the parameter autogenerate_manifest, from the configuration file. Works with rsync backup method and strategies only

check-backup SERVER_NAME BACKUP_ID

Make sure that all the required WAL files to check the consistency of a physical backup (that is, from the beginning to the end of the full backup) are correctly archived. This command is automatically invoked by the cron command and at the end of every backup operation.

check-wal-archive SERVER_NAME

Check that the WAL archive destination for SERVER_NAME is safe to use for a new PostgreSQL cluster. With no optional args (the default) this will pass if the WAL archive is empty and fail otherwise.

--timeline [TIMELINE]

A positive integer specifying the earliest timeline for which associated WALs should cause the check to fail. The check will pass if all WAL content in the archive relates to earlier timelines. If any WAL files are on this timeline or greater then the check will fail.

check SERVER_NAME

Show diagnostic information about SERVER_NAME, including: Ssh connection check, PostgreSQL version, configuration and backup directories, archiving process, streaming process, replication slots, etc. Specify all as SERVER_NAME to show diagnostic information about all the configured servers.

--nagios

Nagios plugin compatible output

config-switch SERVER_NAME MODEL_NAME

Apply a set of configuration overrides defined in the model MODEL_NAME to the Barman server SERVER_NAME. The final configuration is composed of the server configuration plus the overrides defined in the given model. Note: there can only be at most one model active at a time for a given server. config-update JSON_CHANGES

Create or update configuration of servers and/or models in Barman. JSON_CHANGES should be a JSON string containing an array of documents. Each document must contain the scope key, which can be either server or model, and either the server_name or model_name key, depending on the value of scope. Besides that, other keys are expected to be Barman configuration options along with their desired values.

cron

Perform maintenance tasks, such as enforcing retention policies or WAL files management.

--keep-descriptors

Keep the stdout and the stderr streams of the Barman subprocesses attached to this one. This is useful for Docker based installations.

delete SERVER_NAME BACKUP_ID

Delete the specified backup. Backup ID shortcuts section below for available shortcuts.

diagnose

Collect diagnostic information about the server where barman is installed and all the configured servers, including: global configuration, SSH version, Python version, rsync version, as well as current configuration and status of all servers.

generate-manifest SERVER_NAME BACKUP_ID

Generates a backup_manifest file for a backup_id.

get-wal [OPTIONS] SERVER_NAME WAL_NAME

Retrieve a WAL file from the xlog archive of a given server. By default, the requested WAL file, if found, is returned as uncompressed content to STDOUT. The following options allow users to change this behaviour:

-o OUTPUT_DIRECTORY

destination directory where the get-wal will deposit the requested WAL

-P, --partial

retrieve also partial WAL files (.partial)

-z

output will be compressed using gzip

-j

output will be compressed using bzip2

-p SIZE

peek from the WAL archive up to SIZE WAL files, starting from the requested one. 'SIZE' must be an integer >= 1. When invoked with this option, get-wal returns a list of zero to 'SIZE' WAL segment names, one per row.

-t, --test

test both the connection and the configuration of the requested PostgreSQL server in Barman for WAL retrieval. With this option, the 'WAL_NAME' mandatory argument is ignored.

keep SERVER_NAME BACKUP_ID

Flag the specified backup as an archival backup which should be kept forever, regardless of any retention policies in effect. See the Backup ID shortcuts section below for available shortcuts.

--target RECOVERY_TARGET

Specify the recovery target for the archival backup. Possible values for RECOVERY_TARGET are:

• full: The backup can always be used to recover to the latest point in time. To achieve this, Barman will retain all WALs needed to ensure consistency of the backup and all subsequent WALs.
• standalone: The backup can only be used to recover the server to its state at the time the backup was taken. Barman will only retain the WALs needed to ensure consistency of the backup.

--status

Report the archival status of the backup. This will either be the recovery target of full or standalone for archival backups or nokeep for backups which have not been flagged as archival.

--release

Release the keep flag from this backup. This will remove its archival status and make it available for deletion, either directly or by retention policy.

list-backups SERVER_NAME

Show available backups for SERVER_NAME. This command is useful to retrieve a backup ID and the backup type. For example:

servername 20111104T102647 - F - Fri Nov  4 10:26:48 2011 - Size: 17.0 MiB - WAL Size: 100 B

In this case, 20111104T102647 is the backup ID, and F is the backup type label for a full backup taken with pg_basebackup. The backup type label displayed by this command uses one of the following values: - F: for full backups taken with pg_basebackup - I: for incremental backups taken with pg_basebackup - R: for backups taken with rsync - S: for cloud snapshot backups list-files [Options] SERVER_NAME BACKUP_ID : List all the files in a particular backup, identified by the server name and the backup ID. See the Backup ID shortcuts section below for available shortcuts.

--target *TARGET_TYPE*
:    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 the WAL files between the start of the base
       backup and the end of the log / the start of the following base
       backup (depending on whether the specified base backup is the most
       recent one available);
     - *full*: same as data + wal.

    The default value is `standalone`.

list-servers

Show all the configured servers, and their descriptions.

lock-directory-cleanup

Automatically cleans up the barman_lock_directory from unused lock files.

put-wal [OPTIONS] SERVER_NAME

Receive a WAL file from a remote server and securely store it into the SERVER_NAME incoming directory. The WAL file is retrieved from the STDIN, and must be encapsulated in a tar stream together with a MD5SUMS file to validate it. This command is meant to be invoked through SSH from a remote barman-wal-archive utility (part of barman-cli package). Do not use this command directly unless you take full responsibility of the content of files.

-t, --test

test both the connection and the configuration of the requested PostgreSQL server in Barman to make sure it is ready to receive WAL files.

rebuild-xlogdb SERVER_NAME

Perform a rebuild of the WAL file metadata for SERVER_NAME (or every server, using the all shortcut) guessing it from the disk content. The metadata of the WAL archive is contained in the xlog.db file, and every Barman server has its own copy.

receive-wal SERVER_NAME

Start the stream of transaction logs for a server. The process relies on pg_receivewal/pg_receivexlog to receive WAL files from the PostgreSQL servers through the streaming protocol.

--stop

stop the receive-wal process for the server

--reset

reset the status of receive-wal, restarting the streaming from the current WAL file of the server

--create-slot

create the physical replication slot configured with the slot_name configuration parameter

--drop-slot

drop the physical replication slot configured with the slot_name configuration parameter

recover [OPTIONS] SERVER_NAME BACKUP_ID DESTINATION_DIRECTORY

Recover a backup in a given directory (local or remote, depending on the --remote-ssh-command option settings). See the Backup ID shortcuts section below for available shortcuts.

--target-tli TARGET_TLI

Recover the specified timeline. The special values current and latest can be used in addition to a numeric timeline ID. The default behaviour for PostgreSQL versions >= 12 is to recover to the latest timeline in the WAL archive. The default for PostgreSQL versions < 12 is to recover along the timeline which was current when the backup was taken.

--target-time TARGET_TIME

Recover to the specified time.

You can use any valid unambiguous representation (e.g: "YYYY-MM-DD HH:MM:SS.mmm").

--target-xid TARGET_XID

Recover to the specified transaction ID.

--target-lsn TARGET_LSN

Recover to the specified LSN (Log Sequence Number). Requires PostgreSQL 10 or above.

--target-name TARGET_NAME

Recover to the named restore point previously created with the pg_create_restore_point(name).

--target-immediate

Recover ends when a consistent state is reached (end of the base backup)

--exclusive

Set target (time, XID or LSN) to be non inclusive.

--target-action ACTION

Trigger the specified action once the recovery target is reached. Possible actions are: pause, shutdown and promote. This option requires a target to be defined, with one of the above options.

--tablespace NAME:LOCATION

Specify tablespace relocation rule.

--remote-ssh-command SSH_COMMAND

This options activates remote recovery, by specifying the secure shell command to be launched on a remote host. This is the equivalent of the "ssh_command" server option in the configuration file for remote recovery. Example: 'ssh postgres@db2'.

--retry-times RETRY_TIMES

Number of retries of data copy during base backup after an error. Overrides value of the parameter basebackup_retry_times, if present in the configuration file.

--no-retry

Same as --retry-times 0

--retry-sleep

Number of seconds of wait after a failed copy, before retrying. Overrides value of the parameter basebackup_retry_sleep, if present in the configuration file.

--bwlimit KBPS

maximum transfer rate in kilobytes per second. A value of 0 means no limit. Overrides 'bandwidth_limit' configuration option. Default is undefined.

-j , --jobs

Number of parallel workers to copy files during recovery. Overrides value of the parameter parallel_jobs, if present in the configuration file. Works only for servers configured through rsync/SSH.

--jobs-start-batch-period

The time period in seconds over which a single batch of jobs will be started. Overrides the value of parallel_jobs_start_batch_period, if present in the configuration file. Defaults to 1 second.

--jobs-start-batch-size

Maximum number of parallel workers to start in a single batch. Overrides the value of parallel_jobs_start_batch_size, if present in the configuration file. Defaults to 10 jobs.

--get-wal, --no-get-wal

Enable/Disable usage of get-wal for WAL fetching during recovery. Default is based on recovery_options setting.

--network-compression, --no-network-compression

Enable/Disable network compression during remote recovery. Default is based on network_compression configuration setting.

--standby-mode

Specifies whether to start the PostgreSQL server as a standby. Default is undefined.

--recovery-staging-path STAGING_PATH

A path to a location on the recovery host (either the barman server or a remote host if --remote-ssh-command is also used) where files for a compressed backup will be staged before being uncompressed to the destination directory. Backups will be staged in their own directory within the staging path according to the following naming convention: "barman-staging-SERVER_NAME-BACKUP_ID". The staging directory within the staging path will be removed at the end of the recovery process. This option is required when recovering from compressed backups and has no effect otherwise.

--local-staging-path STAGING_PATH

A path to a location on the barman host where the chain of backups will be combined before being copied to the destination directory. Contents created inside the staging path are removed at the end of the recovery process. This option is required when recovering from incremental backups (backup_method=postgres) and has no effect otherwise.

--recovery-conf-filename RECOVERY_CONF_FILENAME

The name of the file where Barman should write the PostgreSQL recovery options when recovering backups for PostgreSQL versions 12 and later. This defaults to postgresql.auto.conf however if --recovery-conf-filename is used then recovery options will be written to RECOVERY_CONF_FILENAME instead. The default value is correct for a typical PostgreSQL installation however if PostgreSQL is being managed by tooling which modifies the configuration mechanism (for example postgresql.auto.conf could be symlinked to /dev/null) then this option can be used to write the recovery options to an alternative location.

--snapshot-recovery-instance INSTANCE_NAME

Name of the instance where the disks recovered from the snapshots are attached. This option is required when recovering backups made with backup_method = snapshot.

--gcp-zone ZONE_NAME

Name of the GCP zone where the instance and disks for snapshot recovery are located. This option can be used to override the value of gcp_zone in the Barman config.

--azure-resource-group RESOURCE_GROUP_NAME

Name of the Azure resource group containing the instance and disks for snapshot recovery. This option can be used to override the value of azure_resource_group in the Barman config.

--aws-region REGION_NAME

Name of the AWS region where the instance and disks for snapshot recovery are located. This option can be used to override the value of aws_region in the Barman config.

replication-status [OPTIONS] SERVER_NAME

Shows live information and status of any streaming client attached to the given server (or servers). Default behaviour can be changed through the following options:

--minimal

machine readable output (default: False)

--target TARGET_TYPE

Possible values for TARGET_TYPE are:

• hot-standby: lists only hot standby servers
• wal-streamer: lists only WAL streaming clients, such as pg_receivewal
• all: any streaming client (default)

--source SOURCE_TYPE

Possible values for SOURCE_TYPE are:

• backup-host: list clients using the backup conninfo for a server (default)
• wal-host: list clients using the WAL streaming conninfo for a server

show-backup SERVER_NAME BACKUP_ID

Show detailed information about a particular backup, identified by the server name and the backup ID. See the Backup ID shortcuts section below for available shortcuts. The following example is from a block-level incremental backup (which requires Postgres version >= 17):

Backup 20240814T017504:
  Server Name            : quagmire
  Status                 : DONE
  PostgreSQL Version     : 90402
  PGDATA directory       : /srv/postgresql/9.4/main/data
  Estimated Cluster Size : 22.4 MiB

  Server information:
    Checksums            : on
    WAL summarizer       : on

  Base backup information:
    Backup Method        : postgres
    Backup Type          : incremental
    Backup Size          : 22.3 MiB (54.3 MiB with WALs)
    WAL Size             : 32.0 MiB
    Resources saved     : 19.5 MiB (86.80%)
    Timeline             : 1
    Begin WAL            : 0000000100000CFD000000AD
    End WAL              : 0000000100000D0D00000008
    WAL number           : 3932
    WAL compression ratio: 79.51%
    Begin time           : 2015-08-28 13:00:01.633925+00:00
    End time             : 2015-08-29 10:27:06.522846+00:00
    Copy time            : 1 second
    Estimated throughput : 2.0 MiB/s
    Begin Offset         : 1575048
    End Offset           : 13853016
    Begin XLOG           : CFD/AD180888
    End XLOG             : D0D/8D36158

  WAL information:
    No of files          : 35039
    Disk usage           : 121.5 GiB
    WAL rate             : 275.50/hour
    Compression ratio    : 77.81%
    Last available       : 0000000100000D95000000E7

  Catalog information:
    Retention Policy     : not enforced
    Previous Backup      : 20150821T130001
    Next Backup          : - (this is the latest base backup)
    Root Backup          : 20240814T015504
    Parent Backup        : 20240814T016504
    Backup chain size    : 3
    Children Backup(s)   : 20240814T018515

NOTE: Depending on the version of your Postgres Server and/or the type of the backup, the output of barman show-backup command may be different. For example, fields like "Root Backup", "Parent Backup", "Backup chain size", and "Children Backup(s)" only make sense when showing information about a block-level incremental backup taken with backup_method = postgres and using Postgres 17 or newer, thus those fields are omitted for other kind of backups or older versions of Postgres.

Also note that show-backup relies on the backup metadata so if a backup was created with Barman version 3.10 or earlier, the backup will not contain the fields added in version 3.11 (which are those added after the introduction of "incremental" backups in PostgreSQL 17).

These are the possible values for the field "Backup Type":

• rsync: for a backup taken with rsync;
• full: for a full backup taken with pg_basebackup;
• incremental: for an incremental backup taken with pg_basebackup;
• snapshot: for a snapshot-based backup taken in the cloud.

Below you can find a list of fields that may be shown or omitted depending on the type of the backup:

• Resources saved: available for "rsync" and "incremental" backups;
• Root Backup, Parent Backup, Backup chain size: available for "incremental" backups only;
• Children Backup(s): available for "full" and "incremental" backups;
• Snapshot information: available for "snapshot" backups only.

show-servers SERVER_NAME

Show information about SERVER_NAME, including: conninfo, backup_directory, wals_directory and many more. Specify all as SERVER_NAME to show information about all the configured servers.

status SERVER_NAME

Show information about the status of a server, including: number of available backups, archive_command, archive_status and many more. For example:

Server quagmire:
  Description: The Giggity database
  Passive node: False
  PostgreSQL version: 9.3.9
  PostgreSQL Data directory: /srv/postgresql/9.3/data
  PostgreSQL 'archive_command' setting: rsync -a %p barman@backup:/var/lib/barman/quagmire/incoming
  Last archived WAL: 0000000100003103000000AD
  Current WAL segment: 0000000100003103000000AE
  Retention policies: enforced (mode: auto, retention: REDUNDANCY 2, WAL retention: MAIN)
  No. of available backups: 2
  First available backup: 20150908T003001
  Last available backup: 20150909T003001
  Minimum redundancy requirements: satisfied (2/1)

switch-wal SERVER_NAME

Execute pg_switch_wal() on the target server (from PostgreSQL 10), or pg_switch_xlog (for PostgreSQL 8.3 to 9.6).

--force

Forces the switch by executing CHECKPOINT before pg_switch_xlog(). IMPORTANT: executing a CHECKPOINT might increase I/O load on a PostgreSQL server. Use this option with care.

--archive

Wait for one xlog file to be archived. If after a defined amount of time (default: 30 seconds) no xlog file is archived, Barman will terminate with failure exit code. Available also on standby servers.

--archive-timeout TIMEOUT

Specifies the amount of time in seconds (default: 30 seconds) the archiver will wait for a new xlog file to be archived before timing out. Available also on standby servers.

switch-xlog SERVER_NAME

Alias for switch-wal (kept for back-compatibility)

sync-backup SERVER_NAME BACKUP_ID

Command used for the synchronisation of a passive node with its primary. Executes a copy of all the files of a BACKUP_ID that is present on SERVER_NAME node. This command is available only for passive nodes, and uses the primary_ssh_command option to establish a secure connection with the primary node.

sync-info SERVER_NAME [LAST_WAL [LAST_POSITION]]

Collect information regarding the current status of a Barman server, to be used for synchronisation purposes. Returns a JSON output representing SERVER_NAME, that contains: all the successfully finished backup, all the archived WAL files, the configuration, last WAL file been read from the xlog.db and the position in the file.

LAST_WAL

tells sync-info to skip any WAL file previous to that (incremental synchronisation)

LAST_POSITION

hint for quickly positioning in the xlog.db file (incremental synchronisation)

sync-wals SERVER_NAME

Command used for the synchronisation of a passive node with its primary. Executes a copy of all the archived WAL files that are present on SERVER_NAME node. This command is available only for passive nodes, and uses the primary_ssh_command option to establish a secure connection with the primary node.

verify-backup SERVER_NAME BACKUP_ID

Executes pg_verifybackup against a backup manifest file (available since Postgres 13). For rsync backups, it can be used with generate-manifest command. Requires pg_verifybackup installed on the backup server

verify SERVER_NAME BACKUP_ID

Alias for verify-backup

Rather than using the timestamp backup ID, you can use any of the following shortcuts/aliases to identity a backup for a given server:

first

Oldest available backup for that server, in chronological order.

last

Latest available backup for that server, in chronological order.

latest

same ast last.

oldest

same ast first.

last-failed

Latest failed backup, in chronological order.

last-full

Latest full-backup eligible for a block-level incremental backup using the --incremental option.

latest-full

same as last-full # EXIT STATUS

0

Success

Not zero

Failure

barman (5).

Barman has been extensively tested, and is currently being used in several production environments. However, we cannot exclude the presence of bugs.

Any bug can be reported via the GitHub bug tracker. Along with the bug submission, users can provide developers with diagnostics information obtained through the barman diagnose command.

Barman maintainers (in alphabetical order):

• Abhijit Menon-Sen
• Didier Michel
• Michael Wallace

Past contributors (in alphabetical order):

• Anna Bellandi (QA/testing)
• Britt Cole (documentation reviewer)
• Carlo Ascani (developer)
• Francesco Canovai (QA/testing)
• Gabriele Bartolini (architect)
• Gianni Ciolli (QA/testing)
• Giulio Calacoci (developer)
• Giuseppe Broccolo (developer)
• Jane Threefoot (developer)
• Jonathan Battiato (QA/testing)
• Leonardo Cecchi (developer)
• Marco Nenciarini (project leader)
• Niccolò Fei (QA/testing)
• Rubens Souza (QA/testing)
• Stefano Bianucci (developer)

• Homepage: <https://www.pgbarman.org/>
• Documentation: <https://docs.pgbarman.org/>
• Professional support: <https://www.enterprisedb.com/>

Barman is the property of EnterpriseDB UK Limited and its code is distributed under GNU General Public License v3.

© Copyright EnterpriseDB UK Limited 2011-2023

EnterpriseDB <https://www.enterprisedb.com>.