DOKK / manpages / debian 13 / barman / barman.1.en
BARMAN(1) Barman BARMAN(1)

barman - Barman Commands

Barman has a command-line interface named barman, which is used basically to interact with Barman's backend.

Before jumping into each of the sub-commands of barman, be aware that barman has global options available for all of the sub-commands. These options can modify the behavior of the sub-commands and can be used as follows:

barman


    [ { -c | --config } CONFIG ]


    [ { --color | --colour } { never | always | auto } ]


    [ { -d | --debug } ]


    [ { -f | --format } { json | console } ]


    [ { -h | --help } ]


    [ --log-level { NOTSET | DEBUG | INFO | WARNING | ERROR | CRITICAL } ]


    [ { -q | --quiet } ]


    [ { -v | --version } ]


    [ SUBCOMMAND ]


NOTE:

This is the syntax for the synopsis:
  • Options between square brackets are optional.
  • Options between curly brackets represent a choose one of set operation.
  • Options with [ ... ] can be specified multiple times.
  • Things written in uppercase represent a literal that should be given a value to.

We will use this same syntax when describing barman sub-commands in the following sections.

Also, when describing sub-commands in the following sections, the commands' synopsis should be seen as a replacement for the SUBCOMMAND.



Specify the configuration file to be used. Defaults to /etc/barman.conf if not provided.
Control whether to use colors in the output. The default is auto. Options are:
  • never: Do not use color.
  • always: Always use color.
  • auto: Use color if the output is to a terminal.

Enable debug output. Default is false. Provides detailed logging information for troubleshooting.
Specify the output format. Options are:
  • json: Output in JSON format.
  • console: Output in human-readable format (default).

Show a help message and exit. Provides information about command usage.
Override the default logging level. Options are:
  • NOTSET: This is the default level when no specific logging level is set. It essentially means "no filtering" of log messages, allowing all messages to be processed according to the levels that are set in the configuration.
  • DEBUG: This level is used for detailed, diagnostic information, often useful for developers when diagnosing problems. It includes messages that are more granular and detailed, intended to help trace the execution of the program.
  • INFO: This level provides general information about the application's normal operation. It's used for messages that indicate the progress of the application or highlight key points in the execution flow that are useful but not indicative of any issues.
  • WARNING: This level indicates that something unexpected happened or that there might be a potential problem. It's used for messages that are not critical but could be of concern, signaling that attention might be needed.
  • ERROR: This level is used when an error occurs that prevents a particular operation from completing successfully. It's used to indicate significant issues that need to be addressed but do not necessarily stop the application from running.
  • CRITICAL: This is the highest level of severity, indicating a serious error that has likely caused the application to terminate or will have severe consequences if not addressed immediately. It's used for critical issues that demand urgent attention.

Suppress all output. Useful for cron jobs or automated scripts.
Show the program version number and exit.

For some commands, you can use the following shortcuts or aliases to identify a backup for a given server. Specifically, the all shortcut can be used to identify all servers:

Shortcut Description
all All available servers
first/oldest Oldest available backup for the server, in chronological order.
last/latest Most recent available backup for the server, in chronological order.
last-full/latest-full Most recent full backup taken with methods rsync or postgres.
last-failed Most recent backup that failed, in chronological order.

Status code 0 means success, while status code Non-Zero means failure.

barman exposes several handy operations. This section is intended to describe each of them.

In the following sections you can find a description of each command implemented by barman. Some of these commands may have more detailed information in another main section in this documentation. If that is the case, a reference is provided to help you quickly navigate to it.

barman archive-wal

archive-wal


    [ { -h | --help } ]


    SERVER_NAME


Fetch WAL files received from either the standard archive_command or streaming replication with pg_receivewal and store them in the server's WAL archive. If you have enabled compression in the configuration file, the WAL files will be compressed before they are archived.

Name of the server in barman node.
Show a help message and exit. Provides information about command usage.

barman backup

backup


    [ --bwlimit KBPS ]


    [ { -h | --help } ]


    [ --incremental BACKUP_ID ]


    [ --immediate-checkpoint ]


    [ { -j | --jobs } PARALLEL_WORKERS ]


    [ --jobs-start-batch-period PERIOD ]


    [ --jobs-start-batch-size SIZE ]


    [ --keepalive-interval SECONDS ]


    [ --manifest ]


    [ --name NAME ]


    [ --no-immediate-checkpoint ]


    [ --no-manifest ]


    [ --no-retry ]


    [ --retry-sleep SECONDS ]


    [ --retry-times NUMBER ]


    [ --reuse-backup { off | copy | link } ]


    [ { --wait | -w } ]


    [ --wait-timeout SECONDS ]


    SERVER_NAME [ SERVER_NAME ... ]


Execute a PostreSQL server backup. Barman will use the parameters specified in the Global and Server configuration files. Specify all shortcut instead of the server name to execute backups from all servers configured in the Barman node. You can also specify multiple server names in sequence to execute backups for specific servers.

Name of the server in barman node.
Specify the maximum transfer rate in kilobytes per second. A value of 0 indicates no limit. This setting overrides the bandwidth_limit configuration option.
Show a help message and exit. Provides information about command usage.
Execute a block-level incremental backup. You must provide a BACKUP_ID or a shortcut to a previous backup, which will serve as the parent backup for the incremental backup.

NOTE:

The backup to be and the parent backup must have backup_method=postgres.


Forces the initial checkpoint to be executed as soon as possible, overriding any value set for the immediate_checkpoint parameter in the configuration file.
Specify the number of parallel workers to use for copying files during the backup. This setting overrides the parallel_jobs parameter if it's specified in the configuration file.
Specify the time period, in seconds, for starting a single batch of jobs. This value overrides the parallel_jobs_start_batch_period parameter if it is set in the configuration file. The default is 1 second.
Specify the maximum number of parallel workers to initiate in a single batch. This value overrides the parallel_jobs_start_batch_size parameter if it is defined in the configuration file. The default is 10 workers.
Specify an interval, in seconds, for sending a heartbeat query to the server to keep the libpq connection active during a Rsync backup. The default is 60 seconds. A value of 0 disables the heartbeat.
Forces the creation of a backup manifest file upon completing a backup. Overrides the autogenerate_manifest parameter from the configuration file. Applicable only to rsync backup strategy.
Specify a friendly name for this backup which can be used in place of the backup ID in barman commands.
Forces the backup to wait for the checkpoint to be executed overriding any value set for the immediate_checkpoint parameter in the configuration file.
Disables the automatic creation of a backup manifest file upon completing a backup. This setting overrides the autogenerate_manifest parameter from the configuration file and applies only to rsync backup strategy.
There will be no retry in case of an error. It is the same as setting --retry-times 0.
Specify the number of seconds to wait after a failed copy before retrying. This setting applies to both backup and recovery operations and overrides the basebackup_retry_sleep parameter if it is defined in the configuration file.
Specify the number of times to retry the base backup copy in case of an error. This applies to both backup and recovery operations and overrides the basebackup_retry_times parameter if it is set in the configuration file.
Overrides the behavior of the reuse_backup option configured in the configuration file. The possible values are:
  • off: Do not reuse the last available backup.
  • copy: Reuse the last available backup for a server and create copies of unchanged files (reduces backup time).
  • link (default): Reuse the last available backup for a server and create hard links to unchanged files (saves both backup time and space).

NOTE:

This will only have any effect if the last available backup was executed with backup_method=rsync.


Wait for all necessary WAL files required by the base backup to be archived.
Specify the duration, in seconds, to wait for the required WAL files to be archived before timing out.

Use shortcuts instead of SERVER_NAME.

Shortcut Description
all All available servers

barman check-backup

check-backup


    [ { -h | --help } ]


    SERVER_NAME BACKUP_ID


Check that all necessary WAL files for verifying the consistency of a physical backup are properly archived. This command is automatically executed by the cron job and at the end of each backup operation. You can use a shortcut instead of BACKUP_ID.

Name of the server in barman node.
Id of the backup in barman catalog.
Show a help message and exit. Provides information about command usage.

Use shortcuts instead of BACKUP_ID.

Shortcut Description
first/oldest Oldest available backup for the server, in chronological order.
last/latest Most recent available backup for the server, in chronological order.
last-full/latest-full Most recent full backup taken with methods rsync or postgres.
last-failed Most recent backup that failed, in chronological order.

barman check

check


    [ { -h | --help } ]


    [ --nagios ]


    SERVER_NAME [ SERVER_NAME ... ]


Display status information about a server, such as SSH connection, Postgres version, configuration and backup directories, archiving and streaming processes, replication slots, and more. Use all as shortcut to show diagnostic information for all configured servers.

Name of the server in barman node.
Show a help message and exit. Provides information about command usage.
Nagios plugin compatible output.

Use shortcuts instead of SERVER_NAME.

Shortcut Description
all All available servers

barman config-switch

config-switch


    [ { -h | --help } ]


    SERVER_NAME { --reset | MODEL_NAME }


Apply a set of configuration overrides from the model to a server in Barman. The final configuration will combine or override the server's existing settings with the ones specified in the model. You can reset the server configurations with the --reset argument.

NOTE:

Only one model can be active at a time for a given server.


Name of the server in barman node.
Name of the model.
Show a help message and exit. Provides information about command usage.
Reset the server's configurations.

barman config-update

config-update


    [ { -h | --help } ]


    STRING


Create or update the configurations for servers and/or models in Barman. The parameter should be a JSON string containing an array of documents. Each document must include a scope key, which can be either server or model, and either a server_name or model_name key, depending on the scope value. Additionally, the document should include other keys representing Barman configuration options and their desired values.

NOTE:

The barman config-update command writes configuration options to a file named .barman.auto.conf, located in the barman_home directory. This configuration file has higher precedence and will override values from the global Barman configuration file (usually /etc/barman.conf) and from any included files specified in configuration_files_directory (typically files in /etc/barman.d). Be aware of this if you decide to manually modify configuration options in those files later.


List of JSON formatted string.
Show a help message and exit. Provides information about command usage.

JSON_STRING='[{“scope”: “server”, “server_name”: “my_server”, “archiver”: “on”, “streaming_archiver”: “off”}]'

barman cron

cron


    [ { -h | --help } ]


    [ --keep-descriptors ]


Carry out maintenance tasks, such as enforcing retention policies or managing WAL files.

Show a help message and exit. Provides information about command usage.
Keep the ^stdout^ and ^stderr^ streams of the Barman subprocesses connected to the main process. This is especially useful for Docker-based installations.

barman delete

delete


    [ { -h | --help } ]


    SERVER_NAME BACKUP_ID


Delete the specified backup. You can use a shortcut instead of BACKUP_ID.

Name of the server in barman node
Id of the backup in barman catalog.
Show a help message and exit. Provides information about command usage.

Use shortcuts instead of BACKUP_ID.

Shortcut Description
first/oldest Oldest available backup for the server, in chronological order.
last/latest Most recent available backup for the server, in chronological order.
last-full/latest-full Most recent full backup taken with methods rsync or postgres.
last-failed Most recent backup that failed, in chronological order.

barman diagnose

diagnose


    [ { -h | --help } ]


    [ --show-config-source ]


Display diagnostic information about the Barman node, which is the server where Barman is installed, as well as all configured Postgres servers. This includes details such as global configuration, SSH version, Python version, rsync version, the current configuration and status of all servers, and many more.

Show a help message and exit. Provides information about command usage.
Include the source file which provides the effective value for each configuration option.

barman generate-manifest

generate-manifest


    [ { -h | --help } ]


    SERVER_NAME BACKUP_ID


Generates a backup_manifest file for a backup. You can use a shortcut instead of BACKUP_ID.

Name of the server in barman node
Id of the backup in barman catalog.
Show a help message and exit. Provides information about command usage.

Use shortcuts instead of BACKUP_ID.

Shortcut Description
first/oldest Oldest available backup for the server, in chronological order.
last/latest Most recent available backup for the server, in chronological order.
last-full/latest-full Most recent full backup taken with methods rsync or postgres.
last-failed Most recent backup that failed, in chronological order.

barman get-wal

get-wal


    [ { --bzip | -j } ]


    [ { --gzip | -z | -x } ]


    [ { -h | --help } ]


    [ --keep-compression ]


    [ { --output-directory | -o } OUTPUT_DIRECTORY ]


    [ { --peek | -p } VALUE ]


    [ { -P | --partial } ]


    [ { -t | --test } ]


    SERVER_NAME WAL_NAME


Retrieve a WAL file from the xlog archive of a specified server. By default, if the requested WAL file is found, it is returned as uncompressed content to STDOUT.

Name of the server in barman node
Id of the backup in barman catalog.
Output will be compressed using bzip2.
Output will be compressed using gzip.
Show a help message and exit. Provides information about command usage.
Do not uncompress the file content. The output will be the original compressed file.
Destination directory where barman will store the WAL file.
Specify an integer value greater than or equal to 1 to retrieve WAL files from the specified WAL file up to the value specified by this parameter. When using this option, get-wal returns a list of zero to the specified WAL segment names, with one name per row.
Additionally, collect partial WAL files (.partial).
Test both the connection and configuration of the specified Postgres server in Barman for WAL retrieval. When this option is used, the required WAL_NAME argument is disregarded.

WARNING:

-z / --gzip and -j / --bzip2 options are deprecated and will be removed in the future. For WAL compression, please make sure to enable it directly on the Barman server via the compression configuration option.


barman keep

keep


    [ { -h | --help } ]


    { { -r | --release } | { -s | --status } | --target { full | standalone } }


    SERVER_NAME BACKUP_ID


Mark the specified backup with a target as an archival backup to be retained indefinitely, overriding any active retention policies. You can also check the keep status of a backup and release the keep mark from a backup. You can use a shortcut instead of BACKUP_ID.

Name of the server in barman node
Id of the backup in barman catalog.
Show a help message and exit. Provides information about command usage.
Release the keep mark from this backup. This will remove its archival status and make it available for deletion, either directly or by retention policy.
Report the archival status of the backup. The status will be either full or standalone for archival backups, or nokeep for backups that have not been designated as archival.
Define the recovery target for the archival backup. The possible values are:
  • full: The backup can be used to recover to the most recent point in time. To support this, Barman will keep all necessary WALs to maintain the backup's consistency as well as any subsequent WALs.
  • standalone: The backup can only be used to restore the server to its state at the time of the backup. Barman will retain only the WALs required to ensure the backup's consistency.


Use shortcuts instead of BACKUP_ID.

Shortcut Description
first/oldest Oldest available backup for the server, in chronological order.
last/latest Most recent available backup for the server, in chronological order.
last-full/latest-full Most recent full backup taken with methods rsync or postgres.
last-failed Most recent backup that failed, in chronological order.

barman list-backups

list-backups


    [ { -h | --help } ]


    [ --minimal ]


    SERVER_NAME


Display the available backups for a server. This command is useful for retrieving both the backup ID and the backup type. You can find details about this command in Catalog usage.

Name of the server in barman node
Show a help message and exit. Provides information about command usage.
Machine readable output.

Use shortcuts instead of SERVER_NAME.

Shortcut Description
all All available servers

barman list-files

list-files


    [ { -h | --help } ]


    [ --target { data | full | standalone | wal } ]


    SERVER_NAME BACKUP_ID


List all files in a specific backup. You can use a shortcut instead of BACKUP_ID.

Name of the server in barman node
Id of the backup in barman catalog.
Show a help message and exit. Provides information about command usage.
Define specific files to be listed. The possible values are:
  • standalone (default): List the base backup files, including required WAL files.
  • data: List just the data files.
  • wal: List all the WAL files between the start of the base backup and the end of the log or 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.


Use shortcuts instead of BACKUP_ID.

Shortcut Description
first/oldest Oldest available backup for the server, in chronological order.
last/latest Most recent available backup for the server, in chronological order.
last-full/latest-full Most recent full backup taken with methods rsync or postgres.
last-failed Most recent backup that failed, in chronological order.

barman list-servers

list-servers


    [ { -h | --help } ]


    [ --minimal ]


Display all configured servers along with their descriptions.

Show a help message and exit. Provides information about command usage.
Machine readable output.

barman lock-directory-cleanup

lock-directory-cleanup


    [ { -h | --help } ]


Automatically removes unused lock files from the barman_lock_directory.

Show a help message and exit. Provides information about command usage.

barman put-wal

put-wal


    [ { -h | --help } ]


    [ { -t | --test } ]


    SERVER_NAME


Receive a WAL file from a remote server and securely save it into the server incoming directory. The WAL file should be provided via STDIN, encapsulated in a tar stream along with a SHA256SUMS or MD5SUMS file for validation (sha256 is the default hash algorithm, but the user can choose md5 when setting the archive-command via barman-wal-archive). This command is intended to be executed via SSH from a remote barman-wal-archive utility (included in the barman-cli package). Avoid using this command directly unless you fully manage the content of the files.

Name of the server in barman node
Show a help message and exit. Provides information about command usage.
Test both the connection and configuration of the specified Postgres server in Barman for WAL retrieval.

barman rebuild-xlogdb

rebuild-xlogdb


    [ { -h | --help } ]


    SERVER_NAME [ SERVER_NAME ... ]


Rebuild the WAL file metadata for a server (or for all servers using the all shortcut) based on the disk content. The WAL archive metadata is stored in the xlog.db file, with each Barman server maintaining its own copy.

Name of the server in barman node.
Show a help message and exit. Provides information about command usage.

Use shortcuts instead of SERVER_NAME.

Shortcut Description
all All available servers

barman recover

NOTE:

This command is deprecated. Use the barman restore command instead.


barman receive-wal

receive-wal


    [ --create-slot ]


    [ --drop-slot ]


    [ { -h | --help } ]


    [ --reset ]


    [ --stop ]


    SERVER_NAME


Initiate the streaming of transaction logs for a server. This process uses pg_receivewal or pg_receivexlog to receive WAL files from Postgres servers via the streaming protocol.

Name of the server in barman node.
Create the physical replication slot configured with the slot_name configuration parameter.
Drop the physical replication slot configured with the slot_name configuration parameter.
Show a help message and exit. Provides information about command usage.
Reset the status of receive-wal, restarting the streaming from the current WAL file of the server.
Stop the process for the server.

barman restore

restore


    [ --aws-region AWS_REGION } ]


    [ --azure-resource-group AZURE_RESOURCE_GRP ]


    [ --bwlimit KBPS ]


    [ --exclusive ]


    [ --gcp-zone GCP_ZONE ]


    [ { --get-wal | --no-get-wal } ]


    [ { -h | --help } ]


    [ { -j | --jobs } PARALLEL_WORKERS ]


    [ --jobs-start-batch-period SECONDS ]


    [ --jobs-start-batch-size NUMBER ]


    [ --local-staging-path PATH ]


    [ { --network-compression | --no-network-compression } ]


    [ --no-retry ]


    [ --recovery-conf-filename FILENAME ]


    [ --recovery-staging-path PATH ]


    [ --remote-ssh-command STRING ]


    [ --retry-sleep SECONDS ]


    [ --retry-times NUMBER ]


    [ --snapshot-recovery-instance INSTANCE_NAME ]


    [ --snapshot-recovery-zone GCP_ZONE ]


    [ --standby-mode ]


    [ --tablespace NAME:LOCATION [ --tablespace NAME:LOCATION ... ] ]


    [ --target-action { pause | shutdown | promote } ]


    [ --target-immediate ]


    [ --target-lsn LSN ]


    [ --target-name RESTORE_POINT_NAME ]


    [ --target-time TIMESTAMP ]


    [ --target-tli TLI ]


    [ --target-xid XID ]


    [ --staging-wal-directory ]


    SERVER_NAME BACKUP_ID DESTINATION_DIR


Execute a PostreSQL server restore operation. Barman will restore the backup from a server in the destination directory. The restoration can be performed locally (on the barman node itself) or remotely (on another machine accessible via SSH). The location is determined by whether or not the --remote-ssh-command option is used. More information on this command can be found in the Recovery section. You can use a shortcut instead of BACKUP_ID.

Name of the server in barman node
Id of the backup in the barman catalog. Use auto to have Barman automatically find the most suitable backup for the restore operation.
Destination directory to restore the backup.
Specify the AWS region where the instance and disks for snapshot recovery are located. This option allows you to override the aws_region value in the Barman configuration.
Specify the Azure resource group containing the instance and disks for snapshot recovery. This option allows you to override the azure_resource_group value in the Barman configuration.
Specify the maximum transfer rate in kilobytes per second. A value of 0 indicates no limit. This setting overrides the bandwidth_limit configuration option.
Set target (time, XID or LSN) to be non inclusive.
Specify the GCP zone where the instance and disks for snapshot recovery are located. This option allows you to override the gcp_zone value in the Barman configuration.
Enable/disable usage of get-wal for WAL fetching during recovery. Default is based on recovery_options setting.
Show a help message and exit. Provides information about command usage.
Specify the number of parallel workers to use for copying files during the backup. This setting overrides the parallel_jobs parameter if it is specified in the configuration file.
Specify the time period, in seconds, for starting a single batch of jobs. This value overrides the parallel_jobs_start_batch_period parameter if it is set in the configuration file. The default is 1 second.
Specify the maximum number of parallel workers to initiate in a single batch. This value overrides the parallel_jobs_start_batch_size parameter if it is defined in the configuration file. The default is 10 workers.
Specify path on the Barman host where the chain of backups will be combined before being copied to the destination directory. The contents created within the staging path will be removed upon completion of the restore process. This option is necessary for restoring from block-level incremental backups and has no effect otherwise.
Enable/disable network compression during remote restore. Default is based on network_compression configuration setting.
There will be no retry in case of an error. It is the same as setting --retry-times 0.
Specify the name of the file where Barman should write recovery options when recovering backups for Postgres versions 12 and later. By default, this is set to postgresql.auto.conf. However, if --recovery-conf-filename is specified, recovery options will be written to the specified value instead. While the default value is suitable for most Postgres installations, this option allows you to specify an alternative location if Postgres is managed by tools that alter the configuration mechanism (for example, if postgresql.auto.conf is symlinked to /dev/null).
Specify a path on the recovery host 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, following the naming convention: barman-staging-SERVER_NAME-BACKUP_ID. This staging directory will be removed after the restore process is complete. This option is mandatory for restoring from compressed backups and has no effect otherwise.
This option enables remote restore by specifying the secure shell command to execute on a remote host. It functions similarly to the ssh_command server option in the configuration file for remote restore, that is, 'ssh USER@SERVER'.
Specify the number of seconds to wait after a failed copy before retrying. This setting applies to both backup and restore operations and overrides the basebackup_retry_sleep parameter if it is defined in the configuration file.
Specify the number of times to retry the base backup copy in case of an error. This applies to both backup and restore operations and overrides the basebackup_retry_times parameter if it is set in the configuration file.
Specify the name of the instance where the disks recovered from the snapshots are attached. This option is necessary when recovering backups created with backup_method=snapshot.
Zone containing the instance and disks for the snapshot recovery (deprecated: replaced by --gcp-zone)
Whether to start the Postgres server as a standby.
Specify tablespace relocation rule. NAME is the tablespace name and LOCATION is the recovery host destination path to restore the tablespace.
Trigger the specified action when the recovery target is reached. This option requires defining a target along with one of these actions. The possible values are:
  • pause: Once recovery target is reached, the server is started in pause state, allowing users to inspect the instance
  • promote: Once recovery target is reached, the server will exit the recovery operation and is promoted as a master.
  • shutdown: Once recovery target is reached, the server is shut down.

Recovery is completed when a consistent state is reached (end of the base backup).
Recover to the specified LSN (Log Sequence Number). Requires Postgres 10 or above.
Recover to the specified name of a restore point previously created with the pg_create_restore_point(name).
Recover to the specified time. Use the format YYYY-MM-DD HH:MM:SS.mmm.
Recover the specified timeline. You can use the special values current and latest in addition to a numeric timeline ID. For Postgres versions 12 and above, the default is to recover to the latest timeline in the WAL archive. For Postgres versions below 12, the default is to recover to the timeline that was current at the time the backup was taken.
Recover to the specified transaction ID.
A staging directory on the destination host for WAL files when performing PITR. If unspecified, it uses a barman_wal directory inside the destination directory.

Use shortcuts instead of BACKUP_ID.

Shortcut Description
first/oldest Oldest available backup for the server, in chronological order.
last/latest Most recent available backup for the server, in chronological order.
last-full/latest-full Most recent full backup taken with methods rsync or postgres.
last-failed Most recent backup that failed, in chronological order.

barman replication-status

replication-status


    [ { -h | --help } ]


    [ --minimal ]


    [ --source { backup-host | wal-host } ]


    [ --target { hot-standby | wal-streamer | all } ]


    SERVER_NAME [ SERVER_NAME ... ]


Display real-time information and status of any streaming clients connected to the specified server. Specify all shortcut to diplay information for all configured servers.

Name of the server in barman node
Show a help message and exit. Provides information about command usage.
Machine readable output.
The possible values are:
  • backup-host (default): List clients using the backup connection information for a server.
  • wal-host: List clients using the WAL streaming connection information for a server.

The possible values are:
  • hot-standby: List only hot standby servers.
  • wal-streamer: List only WAL streaming clients, such as pg_receivewal.
  • all (default): List all streaming clients.


Use shortcuts instead of SERVER_NAME.

Shortcut Description
all All available servers

barman show-backup

show-backup


    [ { -h | --help } ]


    SERVER_NAME BACKUP_ID


Display detailed information about a specific backup. You can find details about this command in Catalog usage. You can use a shortcut instead of BACKUP_ID.

Name of the server in barman node
Id of the backup in barman catalog.
Show a help message and exit. Provides information about command usage.

Use shortcuts instead of BACKUP_ID.

Shortcut Description
first/oldest Oldest available backup for the server, in chronological order.
last/latest Most recent available backup for the server, in chronological order.
last-full/latest-full Most recent full backup taken with methods rsync or postgres.
last-failed Most recent backup that failed, in chronological order.

barman show-servers

show-servers


    [ { -h | --help } ]


    SERVER_NAME [ SERVER_NAME ... ]


Display detailed information about a server, including conninfo, backup_directory, wals_directory, archive_command, and many more. To view information about all configured servers, specify the all shortcut instead of the server name.

Name of the server in barman node
Show a help message and exit. Provides information about command usage.

Shortcut Description
all All available servers

barman status

status


    [ { -h | --help } ]


    SERVER_NAME [ SERVER_NAME ... ]


Display information about a server's status, including details such as the state, Postgres version, WAL information, available backups and more.

Name of the server in barman node
Show a help message and exit. Provides information about command usage.

Shortcut Description
all All available servers

barman switch-wal

switch-wal


    [ --archive ]


    [ --archive-timeout ]


    [ --force ]


    [ { -h | --help } ]


    SERVER_NAME [ SERVER_NAME ... ]


Execute pg_switch_wal() on the target server (Postgres versions 10 and later) or pg_switch_xlog() (for Postgres versions 8.3 to 9.6).

Name of the server in barman node
Waits for one WAL file to be archived. If no WAL file is archived within a specified time (default: 30 seconds), Barman will terminate with a failure exit code. This option is also available on standby servers.
Specify the amount of time in seconds (default: 30 seconds) that the archiver will wait for a new WAL file to be archived before timing out. This option is also available on standby servers.
Forces the switch by executing a CHECKPOINT before pg_switch_wal().

NOTE:

Running a CHECKPOINT may increase I/O load on the Postgres server, so use this option cautiously.


Show a help message and exit. Provides information about command usage.

barman switch-xlog

Alias for the switch-wal command.

barman sync-backup

sync-backup


    [ { -h | --help } ]


    SERVER_NAME BACKUP_ID


This command synchronizes a passive node with its primary by copying all files from a backup present on the server node. It is available only for passive nodes and uses the primary_ssh_command option to establish a secure connection with the primary node. You can use a shortcut instead of BACKUP_ID.

Name of the server in barman node
Id of the backup in barman catalog.
Show a help message and exit. Provides information about command usage.

For some commands, instead of using the timestamp backup ID, you can use the following shortcuts or aliases to identify a backup for a given server:

Shortcut Description
first/oldest Oldest available backup for the server, in chronological order.
last/latest Most recent available backup for the server, in chronological order.
last-full/latest-full Most recent full backup taken with methods rsync or postgres.
last-failed Most recent backup that failed, in chronological order.

barman sync-info

sync-info


    [ { -h | --help } ]


    [ --primary ]


    SERVER_NAME [ LAST_WAL [ LAST_POS ] ]


Gather information about the current status of a Barman server for synchronization purposes.

This command returns a JSON output for a server that includes: all successfully completed backups, all archived WAL files, the configuration, the last WAL file read from xlog.db, and its position within the file.

Name of the server in barman node
Instructs sync-info to skip any WAL files that precede the specified file (for incremental synchronization).
Hint for quickly positioning in the xlog.db file (for incremental synchronization).
Show a help message and exit. Provides information about command usage.
Execute the sync-info on the primary node (if set).

barman sync-wals

sync-wals


    [ { -h | --help } ]


    SERVER_NAME


This command synchronizes a passive node with its primary by copying all archived WAL files from the server node. It is available only for passive nodes and utilizes the primary_ssh_command option to establish a secure connection with the primary node.

Name of the server in barman node
Show a help message and exit. Provides information about command usage.

barman verify-backup

verify-backup


    [ { -h | --help } ]


    SERVER_NAME BACKUP_ID


Runs pg_verifybackup on a backup manifest file (available since Postgres version 13). For rsync backups, it can be used after creating a manifest file using the generate-manifest command. Requires pg_verifybackup to be installed on the backup server. You can use a shortcut instead of BACKUP_ID.

Name of the server in barman node
Id of the backup in barman catalog.
Show a help message and exit. Provides information about command usage.

For some commands, instead of using the timestamp backup ID, you can use the following shortcuts or aliases to identify a backup for a given server:

Shortcut Description
first/oldest Oldest available backup for the server, in chronological order.
last/latest Most recent available backup for the server, in chronological order.
last-full/latest-full Most recent full backup taken with methods rsync or postgres.
last-failed Most recent backup that failed, in chronological order.

barman verify

Alias for verify-backup command.

The barman-cli package includes a collection of recommended client utilities that should be installed alongside the Postgres server. Here are the command references for both utilities.

barman-wal-archive

barman-wal-archive


    [ { -h | --help } ]


    [ { -V | --version } ]


    [ { -U | --user } USER ]


    [ --port PORT ]


    [ { -c | --config } CONFIG ]


    [ { -t | --test } ]


    [ --md5 ]


    BARMAN_HOST SERVER_NAME WAL_PATH


This script can be utilized in the archive_command of a Postgres server to transfer WAL files to a Barman host using the put-wal command (introduced in Barman 2.6). It establishes an SSH connection to the Barman host, enabling seamless integration of Barman within Postgres clusters for improved business continuity.

Exit Statuses are:

  • 0 for SUCCESS.
  • non-zero for FAILURE.

The server name configured in Barman for the Postgres server from which the WAL file is retrieved.
The host of the Barman server.
The value of the '%p' keyword (according to archive_command).
Display a help message and exit.
Display the program's version number and exit.
Specify the user for the SSH connection to the Barman server (defaults to barman).
Define the port used for the SSH connection to the Barman server.
Specify the configuration file on the Barman server.
Test the connection and configuration of the specified Postgres server in Barman to ensure it is ready to receive WAL files. This option ignores the mandatory argument WAL_PATH.
Use MD5 instead of SHA256 as the hash algorithm to calculate the checksum of the WAL file when transmitting it to the Barman server. This is used to maintain compatibility with older server versions, as older versions of Barman server used to support only MD5.

barman-wal-restore

barman-wal-restore


    [ { -h | --help } ]


    [ { -V | --version } ]


    [ { -U | --user } USER ]


    [ --port PORT ]


    [ { -s | --sleep } SECONDS ]


    [ { -p | --parallel } JOBS ]


    [ --spool-dir SPOOL_DIR ]


    [ { -P | --partial } ]


    [ { { -z | --gzip } | { -j | --bzip2 } | --keep-compression } ]


    [ { -c | --config } CONFIG ]


    [ { -t | --test } ]


    BARMAN_HOST SERVER_NAME WAL_NAME WAL_DEST


This script serves as a restore_command for Postgres servers, enabling the retrieval of WAL files through Barman's get-wal feature. It establishes an SSH connection to the Barman host and facilitates the integration of Barman within Postgres clusters, enhancing business continuity.

Exit Statuses are:

  • 0 for SUCCESS.
  • 1 for remote get-wal command FAILURE, likely because the requested WAL could not be found.
  • 2 for ssh connection FAILURE.
  • Any other non-zero for FAILURE.

The server name configured in Barman for the Postgres server from which the WAL file is retrieved.
The host of the Barman server.
The value of the '%f' keyword (according to restore_command).
The value of the '%p' keyword (according to restore_command).
Display a help message and exit.
Display the program's version number and exit.
Specify the user for the SSH connection to the Barman server (defaults to barman).
Define the port used for the SSH connection to the Barman server.
Pause for SECONDS after a failed get-wal request (defaults to 0 - no wait).
Indicate the number of files to peek and transfer simultaneously (defaults to 0 - disabled).
Specify the spool directory for WAL files (defaults to /var/tmp/walrestore).
Include partial WAL files (.partial) in the retrieval.
Transfer WAL files compressed with gzip.
Transfer WAL files compressed with bzip2.
If specified, compressed files will be trasnfered as-is and decompressed on arrival on the client-side.
Specify the configuration file on the Barman server.
Test the connection and configuration of the specified Postgres server in Barman to ensure it is ready to receive WAL files. This option ignores the mandatory arguments WAL_NAME and WAL_DEST.

WARNING:

-z / --gzip and -j / --bzip2 options are deprecated and will be removed in the future. For WAL compression, please make sure to enable it directly on the Barman server via the compression configuration option.


EnterpriseDB

© Copyright EnterpriseDB UK Limited 2011-2025

April 24, 2025 3.13