---
name: "barman"
section: "1"
platform: "linux"
package: "barman"
version: "3.13.3-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/barman"
---

# barman(1)

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:

## 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 ]
    [ { -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.

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

### 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 } ]
    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**.

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

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

  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.

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

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

### 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 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 ]
    [ { -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.

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

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