BARMAN(1)

NAME
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

  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 ]
        [ --cloud-staging-directory PATH ]
        [ --cloud-staging-max-size SIZE ]
        [ { -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.

--cloud-staging-directory
    A staging directory for when sending backups to a cloud object storage using backup_method = postgres. It is used as a temporary location for storing chunks of the backup before they are sent to the cloud. Defaults to /tmp/barman/cloud-staging.

--cloud-staging-max-size
    The maximum size that --cloud-staging-directory can grow to before Barman stops generating new backup chunks. This is used to prevent the staging directory from growing in case the speed of uploading chunks does not keep up with the speed of streaming them from Postgres. The default value is 30Gi.

    Extremely low values are discouraged as they may lead to performance degradation. We recommend a minimum of at least 10Gi. The optimal value will depend on the transfer speed of the backup to Barman and from Barman to the cloud, as well as the size of the backup.

    The accepted format is n{k|Ki|M|Mi|G|Gi|T|Ti} and case-sensitive, where n is an integer greater than zero, with an optional SI or IEC suffix. k stands for kilo with k = 1000, while Ki stands for kilobytes Ki = 1024. The rest of the options have the same reasoning for greater units of measure.

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

  Shortcuts

Use shortcuts instead of SERVER_NAME.
Shortcut | Description
all | All available servers

  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.

  Shortcuts

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

  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.

  Shortcuts

Use shortcuts instead of SERVER_NAME.
Shortcut | Description
all | All available servers

  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.

  Shortcuts

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

  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.

  Shortcuts

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

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

NOTE: Incremental backups are not eligible for the keep command. This restriction exists because incremental backups rely on their parent backups and cannot be used on their own for recovery. Keeping an incremental without its base would serve no purpose, as it is unusable independently.

If you attempt to apply keep to an incremental backup, Barman will return an error indicating that incremental backups cannot be kept.

Only the full base backup —the one that starts the backup chain— can be marked with keep.

  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.

  Shortcuts

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

  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.

  Shortcuts

Use shortcuts instead of SERVER_NAME.
Shortcut | Description
all | All available servers

  barman list-files

  Synopsis

    list-files
        [ { -h | --help } ]
        [ --target { data | full | standalone | wal } ]
        [ --list-empty-directories ]
        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.

--list-empty-directories
    Add empty directories to the listing.

  Shortcuts

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

  Shortcuts

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

  Synopsis

    receive-wal
        [ --create-slot ]
        [ --if-not-exists ]
        [ --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.

--if-not-exists
    Do not error out when --create-slot is specified and a slot with the specified name already exists.

--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 ]
        [ --staging-path STAGING_PATH ]
        [ --staging-location STAGING_LOCATION ]
        [ --combine-mode COMBINE_MODE ]
        [ --remote-ssh-command STRING ]
        [ --restore-command COMMAND ]
        [ --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.

--delta-restore / --no-delta-restore
    Enable/disable usage of delta-restore for a delta recovery. Default is based on recovery_options setting.

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

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

    Deprecated since version 3.15: --local-staging-path is deprecated and will be removed in a future release. Use --staging-path and --staging-location instead.

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

    Deprecated since version 3.15: --recovery-staging-path is deprecated and will be removed in a future release. Use --staging-path and --staging-location instead.

--staging-path
    A path where intermediate files are staged during restore. When restoring a compressed backup, it serves as a temporary location for decompression before copying to the final destination. When restoring an incremental backup, it is where backups are combined before copying to the final destination. This location must have enough space to store the decompressed/combined backup.

--staging-location
    Specifies whether --staging-path is a local or remote path. Valid values are local and remote.

--combine-mode
    Specifies a copy mode for pg_combinebackup when combining incremental backups during a restore.

    Options include:

•   copy (default): Use standard file copying when combining incremental backups.

•   link: Use hard links when combining incremental backups. Reconstruction of the synthetic backup might be faster (no file copying) and use less disk space.

•   clone: Use efficient file cloning (also known as “reflinks” on some systems) instead of copying files to the new data directory, which can result in near-instantaneous copying of the data files.

•   copy-file-range: Use the copy_file_range system call for efficient copying. On some file systems this gives results similar to clone, sharing physical disk blocks, while on others it may still copy blocks, but do so via an optimized path.

    Refer to the pg_combinebackup documentation for more details and restrictions of each mode.

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

--restore-command
    Specify a custom restore command to override Barman's default restore_command in the PostgreSQL recovery configuration. While the default restore_command built by Barman is suitable for most cases, this option allows you to specify an alternative command if your setup requires it. Can be used only when running a restore with get-wal mode.

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

  Shortcuts

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

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

  Shortcuts

Use shortcuts instead of SERVER_NAME.
Shortcut | Description
all | All available servers

  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.

  Shortcuts

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

  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.

  Shortcuts
Shortcut | Description
all | All available servers

  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.

  Shortcuts
Shortcut | Description
all | All available servers

  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.

  Shortcuts

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

  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.

  Shortcuts

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

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

AUTHOR
EnterpriseDB

COPYRIGHT
© Copyright EnterpriseDB UK Limited 2011-2025