Commands Reference#

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`#

Synopsis#

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.

Parameters#

-c / --config CONFIG

Specify the configuration file to be used. Defaults to /etc/barman.conf if not provided.

--color / --colour { never | always | auto }

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.

-d / --debug

Enable debug output. Default is false. Provides detailed logging information for troubleshooting.

-f / --format { json | console }

Specify the output format. Options are:

json: Output in JSON format.
console: Output in human-readable format (default).

-h / --help

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

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

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.

-q / --quiet

Suppress all output. Useful for cron jobs or automated scripts.

-v / --version

Show the program version number and exit.

Shortcuts#

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.

Exit Statuses#

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

Sub-Commands#

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`#

Synopsis#

archive-wal
    [ { -h | --help } ]
    SERVER_NAME

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node.
-h / --help: Show a help message and exit. Provides information about command usage.

`barman backup`#

Synopsis#

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 ... ]

Description#

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.

Parameters#

SERVER_NAME

Name of the server in barman node.

--bwlimit

Specify the maximum transfer rate in kilobytes per second. A value of 0 indicates no limit. This setting overrides the bandwidth_limit configuration option.

-h / --help

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

--incremental

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.

--immediate-checkpoint

Forces the initial checkpoint to be executed as soon as possible, overriding any value set for the immediate_checkpoint parameter in the configuration file.

-j / --jobs

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.

--jobs-start-batch-period

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.

--jobs-start-batch-size

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.

--keepalive-interval

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.

--manifest

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.

--name

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

--no-immediate-checkpoint

Forces the backup to wait for the checkpoint to be executed overriding any value set for the immediate_checkpoint parameter in the configuration file.

--no-manifest

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.

--no-retry

There will be no retry in case of an error. It is the same as setting --retry-times 0.

--retry-sleep

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.

--retry-times

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.

--reuse-backup

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 / -w

Wait for all necessary WAL files required by the base backup to be archived.

--wait-timeout

Specify the duration, in seconds, to wait for the required WAL files to be archived before timing out.

`barman check-backup`#

Synopsis#

check-backup
    [ { -h | --help } ]
    SERVER_NAME BACKUP_ID

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node.
BACKUP_ID: Id of the backup in barman catalog.
-h / --help: Show a help message and exit. Provides information about command usage.

`barman check`#

Synopsis#

check
    [ { -h | --help } ]
    [ --nagios ]
    SERVER_NAME [ SERVER_NAME ... ]

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node.
-h / --help: Show a help message and exit. Provides information about command usage.
--nagios: Nagios plugin compatible output.

`barman config-switch`#

Synopsis#

config-switch
    [ { -h | --help } ]
    SERVER_NAME { --reset | MODEL_NAME }

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node.
MODEL_NAME: Name of the model.
-h / --help: Show a help message and exit. Provides information about command usage.
--reset: Reset the server’s configurations.

`barman config-update`#

Synopsis#

config-update
    [ { -h | --help } ]
    STRING

Description#

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.

Parameters#

STRING: List of JSON formatted string.
-h / --help: Show a help message and exit. Provides information about command usage.

Example#

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

`barman cron`#

Synopsis#

cron
    [ { -h | --help } ]
    [ --keep-descriptors ]

Description#

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

Parameters#

-h / --help: Show a help message and exit. Provides information about command usage.
--keep-descriptors: 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`#

Synopsis#

delete
    [ { -h | --help } ]
    SERVER_NAME BACKUP_ID

Description#

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

Parameters#

SERVER_NAME: Name of the server in barman node
BACKUP_ID: Id of the backup in barman catalog.
-h / --help: Show a help message and exit. Provides information about command usage.

`barman diagnose`#

Synopsis#

diagnose
    [ { -h | --help } ]
    [ --show-config-source ]

Description#

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.

Parameters#

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

`barman generate-manifest`#

Synopsis#

generate-manifest
    [ { -h | --help } ]
    SERVER_NAME BACKUP_ID

Description#

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

Parameters#

SERVER_NAME: Name of the server in barman node
BACKUP_ID: Id of the backup in barman catalog.
-h / --help: Show a help message and exit. Provides information about command usage.

`barman get-wal`#

Synopsis#

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

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node
WAL_NAME: Id of the backup in barman catalog.
--bzip2 / -j: Output will be compressed using bzip2.
--gzip / -z / -x: Output will be compressed using gzip.
-h / --help: Show a help message and exit. Provides information about command usage.
--keep-compression: Do not uncompress the file content. The output will be the original compressed file.
--output-directory / -o: Destination directory where barman will store the WAL file.
--peek / -p: 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.
-P / --partial: Additionally, collect partial WAL files (.partial).
-t / --test: 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`#

Synopsis#

keep
    [ { -h | --help } ]
    { { -r | --release } | { -s | --status } | --target { full | standalone } }
    SERVER_NAME BACKUP_ID

Description#

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.

Parameters#

SERVER_NAME

Name of the server in barman node

BACKUP_ID

Id of the backup in barman catalog.

-h / --help

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

-r / --release

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.

-s / --status

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.

--target

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.

`barman list-backups`#

Synopsis#

list-backups
    [ { -h | --help } ]
    [ --minimal ]
    SERVER_NAME

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node
-h / --help: Show a help message and exit. Provides information about command usage.
--minimal: Machine readable output.

`barman list-files`#

Synopsis#

list-files
    [ { -h | --help } ]
    [ --target { data | full | standalone | wal } ]
    SERVER_NAME BACKUP_ID

Description#

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

Parameters#

SERVER_NAME

Name of the server in barman node

BACKUP_ID

Id of the backup in barman catalog.

-h / --help

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

--target

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.

`barman list-processes`#

Synopsis#

list-processes
    [ { -h | --help } ]
    SERVER_NAME

Description#

The list-processes sub-command outputs all active subprocesses for a Barman server. It displays the process identifier (PID) and the corresponding barman task for each active subprocess.

Parameters#

SERVER_NAME: Name of the server for which to list active subprocesses.
-h / --help: Displays a help message and exits.

`barman list-servers`#

Synopsis#

list-servers
    [ { -h | --help } ]
    [ --minimal ]

Description#

Display all configured servers along with their descriptions.

Parameters#

-h / --help: Show a help message and exit. Provides information about command usage.
--minimal: Machine readable output.

`barman lock-directory-cleanup`#

Synopsis#

lock-directory-cleanup
    [ { -h | --help } ]

Description#

Automatically removes unused lock files from the barman_lock_directory.

Parameters#

-h / --help: Show a help message and exit. Provides information about command usage.

`barman put-wal`#

Synopsis#

put-wal
    [ { -h | --help } ]
    [ { -t | --test } ]
    SERVER_NAME

Description#

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.

Parameters#

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

`barman rebuild-xlogdb`#

Synopsis#

rebuild-xlogdb
    [ { -h | --help } ]
    SERVER_NAME [ SERVER_NAME ... ]

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node.
-h / --help: Show a help message and exit. Provides information about command usage.

`barman recover`#

Note

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

`barman receive-wal`#

Synopsis#

receive-wal
    [ --create-slot ]
    [ --drop-slot ]
    [ { -h | --help } ]
    [ --reset ]
    [ --stop ]
    SERVER_NAME

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node.
--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.
-h / --help: Show a help message and exit. Provides information about command usage.
--reset: Reset the status of receive-wal, restarting the streaming from the current WAL file of the server.
--stop: Stop the process for the server.

Warning

The --stop option for the barman receive-wal command will be obsoleted in a future release. Users should favor using the terminate-process command instead, which is the new way of handling this feature.

`barman restore`#

Synopsis#

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

Description#

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.

Parameters#

SERVER_NAME

Name of the server in barman node

BACKUP_ID

Id of the backup in the barman catalog. Use auto to have Barman automatically find the most suitable backup for the restore operation.

DESTINATION_DIR

Destination directory to restore the backup.

--aws-region

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.

--azure-resource-group

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.

--bwlimit

Specify the maximum transfer rate in kilobytes per second. A value of 0 indicates no limit. This setting overrides the bandwidth_limit configuration option.

--exclusive

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

--gcp-zone

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.

--get-wal / --no-get-wal

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

-h / --help

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

-j / --jobs

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.

--jobs-start-batch-period

--jobs-start-batch-size

--local-staging-path

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.

--network-compression / --no-network-compression

Enable/disable network compression during remote restore. Default is based on network_compression configuration setting.

--no-retry

There will be no retry in case of an error. It is the same as setting --retry-times 0.

--recovery-conf-filename

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).

--recovery-staging-path

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.

--remote-ssh-command

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

--retry-sleep

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.

--retry-times

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.

--snapshot-recovery-instance

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.

--snapshot-recovery-zone (deprecated)

Zone containing the instance and disks for the snapshot recovery (deprecated: replaced by --gcp-zone)

--standby-mode

Whether to start the Postgres server as a standby.

--tablespace

Specify tablespace relocation rule. NAME is the tablespace name and LOCATION is the recovery host destination path to restore the tablespace.

--target-action

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.

--target-immediate

Recovery is completed when a consistent state is reached (end of the base backup).

--target-lsn

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

--target-name

Recover to the specified name of a restore point previously created with the pg_create_restore_point(name).

--target-time

Recover to the specified time. Use the format YYYY-MM-DD HH:MM:SS.mmm.

--target-tli

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.

--target-xid

Recover to the specified transaction ID.

--staging-wal-directory

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.

`barman replication-status`#

Synopsis#

replication-status
    [ { -h | --help } ]
    [ --minimal ]
    [ --source { backup-host | wal-host } ]
    [ --target { hot-standby | wal-streamer | all } ]
    SERVER_NAME [ SERVER_NAME ... ]

Description#

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.

Parameters#

SERVER_NAME

Name of the server in barman node

-h / --help

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

--minimal

Machine readable output.

--source

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.

--target

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.

`barman show-backup`#

Synopsis#

show-backup
    [ { -h | --help } ]
    SERVER_NAME BACKUP_ID

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node
BACKUP_ID: Id of the backup in barman catalog.
-h / --help: Show a help message and exit. Provides information about command usage.

`barman show-servers`#

Synopsis#

show-servers
    [ { -h | --help } ]
    SERVER_NAME [ SERVER_NAME ... ]

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node
-h / --help: Show a help message and exit. Provides information about command usage.

`barman status`#

Synopsis#

status
    [ { -h | --help } ]
    SERVER_NAME [ SERVER_NAME ... ]

Description#

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

Parameters#

SERVER_NAME: Name of the server in barman node
-h / --help: Show a help message and exit. Provides information about command usage.

`barman switch-wal`#

Synopsis#

switch-wal
    [ --archive ]
    [ --archive-timeout ]
    [ --force ]
    [ { -h | --help } ]
    SERVER_NAME [ SERVER_NAME ... ]

Description#

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).

Parameters#

SERVER_NAME: Name of the server in barman node
--archive: 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.
--archive-timeout: 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.
--force: 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.
-h / --help: Show a help message and exit. Provides information about command usage.

`barman switch-xlog`#

Description#

Alias for the switch-wal command.

`barman sync-backup`#

Synopsis#

sync-backup
    [ { -h | --help } ]
    SERVER_NAME BACKUP_ID

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node
BACKUP_ID: Id of the backup in barman catalog.
-h / --help: Show a help message and exit. Provides information about command usage.

`barman sync-info`#

Synopsis#

sync-info
    [ { -h | --help } ]
    [ --primary ]
    SERVER_NAME [ LAST_WAL [ LAST_POS ] ]

Description#

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.

Parameters#

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

`barman sync-wals`#

Synopsis#

sync-wals
    [ { -h | --help } ]
    SERVER_NAME

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node
-h / --help: Show a help message and exit. Provides information about command usage.

`barman terminate-process`#

Synopsis#

terminate-process SERVER_NAME TASK_NAME

Description#

The barman terminate-process command terminates an active Barman subprocess on a specified server. The target process is identified by its task name (for example, backup or receive-wal). Note that only processes that are running on the server level can be terminated, so global processes like cron or config-update can not be terminated by this command.

You can also use the output of barman list-processes to display all active processes for a given server and determine which tasks can be terminated. More details about this command can be found in barman list-processes.

Parameters#

SERVER_NAME: The name of the server where the subprocess is running.
TASK_NAME: The task name that identifies the subprocess to be terminated.

`barman verify-backup`#

Synopsis#

verify-backup
    [ { -h | --help } ]
    SERVER_NAME BACKUP_ID

Description#

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.

Parameters#

SERVER_NAME: Name of the server in barman node
BACKUP_ID: Id of the backup in barman catalog.
-h / --help: Show a help message and exit. Provides information about command usage.

`barman verify`#

Description#

Alias for verify-backup command.

`barman-cli` commands#

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`#

Synopsis#

barman-wal-archive
    [ { -h | --help } ]
    [ { -V | --version } ]
    [ { -U | --user } USER ]
    [ --port PORT ]
    [ { { -z | --gzip } | { -j | --bzip2 } | --xz | --snappy | --zstd | --lz4 } ]
    [ --compression-level COMPRESSION_LEVEL ]
    [ { -c | --config } CONFIG ]
    [ { -t | --test } ]
    [ --md5 ]
    BARMAN_HOST SERVER_NAME WAL_PATH

Description#

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.

Parameters#

SERVER_NAME: The server name configured in Barman for the Postgres server from which the WAL file is retrieved.
BARMAN_HOST: The host of the Barman server.
WAL_PATH: The value of the ‘%p’ keyword (according to archive_command).
-h / --help: Display a help message and exit.
-V / --version: Display the program’s version number and exit.
-U / --user: Specify the user for the SSH connection to the Barman server (defaults to barman).
--port: Define the port used for the SSH connection to the Barman server.
-z / --gzip: gzip-compress the WAL file before sending it to the Barman server.
-j / --bzip2: bzip2-compress the WAL file before sending it to the Barman server.
--xz: xz-compress the WAL file before sending it to the Barman server.
--snappy: snappy-compress the WAL file before sending it to the Barman server (requires the python-snappy Python library to be installed).
--zstd: zstd-compress the WAL file before sending it to the Barman server (requires the zstandard Python library to be installed).
--lz4: lz4-compress the WAL file before sending it to the Barman server (requires the lz4 Python library to be installed).
--compression-level: A compression level to be used by the selected compression algorithm. Valid values are integers within the supported range of the chosen algorithm or one of the predefined labels: low, medium, and high. The range of each algorithm as well as what level each predefined label maps to can be found in compression_level.
-c / --config: Specify the configuration file on the Barman server.
-t / --test: 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.
--md5: 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.

Note

When compression is enabled in barman-wal-archive, it takes precedence over the compression settings configured on the Barman server, if they differ.

Important

When compression is enabled in barman-wal-archive, it is performed on the client side, before the file is sent to Barman. Be mindful of the database server’s load and the chosen compression algorithm and level, as higher compression can delay WAL shipping, causing WAL files to accumulate.

`barman-wal-restore`#

Synopsis#

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

Description#

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.

Parameters#

SERVER_NAME: The server name configured in Barman for the Postgres server from which the WAL file is retrieved.
BARMAN_HOST: The host of the Barman server.
WAL_NAME: The value of the ‘%f’ keyword (according to restore_command).
WAL_DEST: The value of the ‘%p’ keyword (according to restore_command).
-h / --help: Display a help message and exit.
-V / --version: Display the program’s version number and exit.
-U / --user: Specify the user for the SSH connection to the Barman server (defaults to barman).
--port: Define the port used for the SSH connection to the Barman server.
-s / --sleep: Pause for SECONDS after a failed get-wal request (defaults to 0 - no wait).
-p / --parallel: Indicate the number of files to peek and transfer simultaneously (defaults to 0 - disabled).
--spool-dir: Specify the spool directory for WAL files (defaults to /var/tmp/walrestore).
-P / --partial: Include partial WAL files (.partial) in the retrieval.
-z / --gzip: Transfer WAL files compressed with gzip.
-j / --bzip2: Transfer WAL files compressed with bzip2.
--keep-compression: If specified, compressed files will be trasnfered as-is and decompressed on arrival on the client-side.
-c / --config: Specify the configuration file on the Barman server.
-t / --test: 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

Commands Reference#

barman#

Synopsis#

Parameters#

Shortcuts#

Exit Statuses#

Sub-Commands#

barman archive-wal#

Synopsis#

Description#

Parameters#

barman backup#

Synopsis#

Description#

Parameters#

barman check-backup#

Synopsis#

Description#

Parameters#

barman check#

Synopsis#

Description#

Parameters#

barman config-switch#

Synopsis#

Description#

Parameters#

barman config-update#

Synopsis#

Description#

Parameters#

Example#

barman cron#

Synopsis#

Description#

Parameters#

barman delete#

Synopsis#

Description#

Parameters#

barman diagnose#

Synopsis#

Description#

Parameters#

barman generate-manifest#

Synopsis#

Description#

Parameters#

barman get-wal#

Synopsis#

Description#

Parameters#

barman keep#

Synopsis#

Description#

Parameters#

barman list-backups#

Synopsis#

Description#

Parameters#

barman list-files#

Synopsis#

Description#

Parameters#

barman list-processes#

Synopsis#

Description#

Parameters#

barman list-servers#

Synopsis#

Description#

Parameters#

barman lock-directory-cleanup#

Synopsis#

Description#

Parameters#

barman put-wal#

Synopsis#

Description#

Parameters#

`barman`#

`barman archive-wal`#

`barman backup`#

`barman check-backup`#

`barman check`#

`barman config-switch`#

`barman config-update`#

`barman cron`#

`barman delete`#

`barman diagnose`#

`barman generate-manifest`#

`barman get-wal`#

`barman keep`#

`barman list-backups`#

`barman list-files`#

`barman list-processes`#

`barman list-servers`#

`barman lock-directory-cleanup`#

`barman put-wal`#

`barman rebuild-xlogdb`#

`barman recover`#

`barman receive-wal`#

`barman restore`#

`barman replication-status`#

`barman show-backup`#

`barman show-servers`#

`barman status`#

`barman switch-wal`#

`barman switch-xlog`#

`barman sync-backup`#

`barman sync-info`#

`barman sync-wals`#

`barman terminate-process`#

`barman verify-backup`#

`barman verify`#

`barman-cli` commands#

`barman-wal-archive`#

`barman-wal-restore`#