BARMAN(1)

📦

version 3.20.1 · 10 versions

3.20.1 · epel 10, fedora 43, fedora 44 (latest)
3.19.1 · nixpkgs unstable, ubuntu stonking
3.14.1 · nixos 26.05, ubuntu questing
3.15.0 · fedora 43
2.18 · ubuntu jammy
3.17.0 · fedora 44
3.4.0 · debian bookworm
3.10.0 · ubuntu noble
3.18.0 · epel 9, ubuntu resolute
3.13.3 · debian trixie

🌸 BARMAN — barman Commands 💅

okay bestie so like. barman is a command-line interface named barman, and honestly? it's the main character of the whole Barman situation — you use it basically to interact with Barman's backend. no cap.

but before we dive into each and every sub-command (and there are so many, we're getting there), you need to know that barman has global options that work for all of the sub-commands. they change how the sub-commands behave, and you use them like this:

👑 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: so this is how you read the synopsis syntax, bestie — memorize it, it comes back <em>everywhere</em>: - Options between square brackets are optional — you can skip them, it's fine. - Options between curly brackets represent a choose one of set operation — pick exactly one, no collecting them all. - Options with [ ... ] can be specified multiple times. - Things written in UPPERCASE represent a literal that should be given a value to. We're gonna use this exact same syntax when describing the barman sub-commands in the following sections, so like. keep it in your pocket. 🎀 Also — when describing sub-commands in the following sections, the commands' synopsis should be seen as a replacement for the SUBCOMMAND slot. slay.

🔧 Parameters

-c / --config CONFIG — specify the configuration file to be used. Defaults to /etc/barman.conf if not provided. it's giving "I know where I live" energy.
--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. like turning the lights all the way up. 🔥
-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. bestie behavior honestly 🫶
--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. shhh. 🤫
-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:

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. that's it, that's the whole vibe check. ✅ / ❌

💜 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. iykyk 📖

🧚 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. lowkey elegant.

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 the 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. go off, queen 👑

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. non-negotiable, bestie.

--immediate-checkpoint — bestie, this one forces the initial checkpoint to happen ASAP, overriding whatever immediate_checkpoint parameter you set in the config file. It's giving "we're not waiting around" energy. 💅
-j / --jobs — tells Barman how many parallel workers to use for copying files during the backup. This overrides the parallel_jobs parameter if you've got it set in the configuration file. More workers = more hands on deck 🫶
--jobs-start-batch-period — sets the time period, in seconds, for starting a single batch of jobs. This value overrides the parallel_jobs_start_batch_period parameter if it's set in the configuration file. The default is 1 second.
--jobs-start-batch-size — sets the maximum number of parallel workers to kick off in a single batch. Overrides the parallel_jobs_start_batch_size parameter if it's defined in the configuration file. The default is 10 workers.
--keepalive-interval — the interval, in seconds, for sending a heartbeat query to the server so the libpq connection stays active during a Rsync backup. The default is 60 seconds. Set it to 0 and the heartbeat is disabled, periodt.
--manifest — forces a backup manifest file to be created once a backup completes. Overrides the autogenerate_manifest parameter from the configuration file. Heads up: this only applies to the rsync backup strategy. 🌈
--name — give this backup a cute friendly name 🎀 which you can then use in place of the backup ID in barman commands.
--no-immediate-checkpoint — forces the backup to wait for the checkpoint to be executed, overriding whatever value you set for the immediate_checkpoint parameter in the configuration file. The opposite twin of --immediate-checkpoint, iykyk.
--no-manifest — disables the automatic creation of a backup manifest file when a backup completes. Overrides the autogenerate_manifest parameter from the configuration file, and applies only to the rsync backup strategy.
--no-retry — no retries if there's an error. Literally the same as setting --retry-times 0. 💀
--retry-sleep — how many seconds to wait after a failed copy before retrying. This applies to both backup and recovery operations, and overrides the basebackup_retry_sleep parameter if it's defined in the configuration file.
--retry-times — how many times to retry the base backup copy if there's an error. Applies to both backup and recovery operations, and overrides the basebackup_retry_times parameter if it's set in the configuration file.
--reuse-backup — overrides the behavior of the reuse_backup option you 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 (this 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. No cap.

--wait / -w — wait for all the necessary WAL files required by the base backup to be archived. ⏳
--wait-timeout — how long, in seconds, to wait for the required WAL files to be archived before timing out.

✨ Shortcuts ✨

Use shortcuts instead of SERVER_NAME:

all — All available servers 🌸

🦋 barman check-archived-wal-range 🦋

Synopsis

check-archived-wal-range
    [ { -h | --help } ]
    SERVER_NAME BEGIN_WAL END_WAL

Description

Checks that every single WAL segment in the range from BEGIN_WAL to END_WAL (inclusive, bestie — both ends count) is present in the WAL archive of the specified server. If any segments are missing, they get listed and the command exits with a non-zero status. Exits with status 0 when the sequence is complete. ✅

This command scans the WAL archive directory directly, so it's reflecting the actual state of the storage, not Barman's internal index. It's giving honest-to-a-fault energy, and we love that. 💖

Parameters

SERVER_NAME — Name of the server in barman node.
BEGIN_WAL — Name of the first WAL segment in the range to verify (inclusive).
END_WAL — Name of the last WAL segment in the range to verify (inclusive).
-h / --help — Show a help message and exit. Provides information about command usage.

💜 barman check-backup 💜

Synopsis

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

Description

Checks that all the necessary WAL files for verifying the consistency of a physical backup are properly archived. This command runs automatically via the cron job and at the end of every backup operation. Oh, and you can use a shortcut instead of BACKUP_ID — details below, bestie. 👇

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:

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

Displays status information about a server — SSH connection, Postgres version, configuration and backup directories, archiving and streaming processes, replication slots, and more. It's the vibe check for your whole setup, fr fr. 🌈

Use all as a shortcut to show diagnostic information for every configured server.

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:

all — All available servers 🌸

☁️ barman cloud-wal-archive ☁️

Synopsis

cloud-wal-archive
    [ { -h | --help } ]
    [ { -p | --parallel } PARALLEL ]
    SERVER_NAME WAL_PATH

Description

Pushes a WAL file from the local disk up to a configured cloud object storage. This command is meant to be used in the archive_command of a Postgres server when you're using the local-to-cloud backup method for taking base backups. 🚀

Note: the compression algorithm and level used for the WAL files can be configured in the Barman server configuration file. If you don't specify anything, the WAL file gets uploaded with no compression at all.

Parameters

SERVER_NAME — The name of the Postgres server for which the WAL file is being archived.
WAL_PATH — The value of the %p keyword (according to archive_command).
-h / --help — Show a help message and exit. Provides information about command usage.
-p / --parallel — Number of WALs to archive in parallel. When you set this to a value greater than 1, up to parallel - 1 additional WAL files that are ready in pg_wal/archive_status get uploaded concurrently in background processes after the primary WAL has been successfully archived. This can reduce the WAL archival backlog during periods of high WAL generation. Defaults to the cloud_wal_archive_parallel server configuration value, which itself defaults to 0 (disabled). 🦋

🧚 barman cloud-wal-restore 🧚

Synopsis

cloud-wal-restore
    [ { -h | --help } ]
    [ { -p | --parallel } PARALLEL ]
    [ --spool-dir SPOOL_DIR ]
    SERVER_NAME WAL_NAME WAL_DEST

Description

Pulls a WAL file from a configured cloud object storage back down to the local disk. This command is meant to be used as restore_command in Postgres when you're restoring WALs from a cloud object storage. 💫

This command requires the server to have cloud storage configured via wals_directory pointing to a cloud URL (e.g., s3://barman/wals).

Parameters 🧚

SERVER_NAME — the name of the Postgres server whose WAL file is getting restored. Like, which server, bestie, we need the deets.
WAL_NAME — the value of the %f keyword (per restore_command). Yes, that %f.
WAL_DEST — the value of the %p keyword (per restore_command).
-h / --help — show a help message and dip. ✨
-p / --parallel — how many WAL files to peek and download in parallel. Set it above 1 and it fetches the WAL file you asked for plus the next N - 1 files at the same time. Those extra files get staged in the spool directory so the next restore requests can be served immediately from local storage. Default is 0 (disabled). Very demure, very mindful, very off by default.
--spool-dir — the directory used to stage those extra WALs when you're using --parallel. Default is /var/tmp/walrestore.

💡 Tip: when you use --parallel and both the pg_wal directory and the spool directory live on the same filesystem, WAL files get served faster — because they're renamed instead of copied. Cheaper, quicker, iconic.

barman config-switch 💅

Synopsis

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

Description

Applies a set of configuration overrides from the model onto a server in Barman. The final config will combine — or override — the server's existing settings with the ones you specified in the model. And if you ever want to undo the whole thing, you can reset the server configurations with the --reset argument. Clean slate energy. 🧼

📌 Note: only one model can be active at a time for a given server. That's it. One. Pick your fave.

Parameters

SERVER_NAME — name of the server in barman node.
MODEL_NAME — name of the model.
-h / --help — show a help message and exit. Gives you the info about command usage.
--reset — reset the server's configurations.

barman config-update 🎀

Synopsis

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

Description

Creates or updates the configurations for servers and/or models in Barman. The parameter has to be a JSON string containing an array of documents. Every document must include a scope key — which can be either server or model — plus either a server_name or a model_name key, depending on what the scope value is. On top of that, the document should include the other keys representing Barman configuration options and the values you want them to have.

⚠️ 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). So like… be aware of this if you decide to manually modify configuration options in those files later. It will absolutely win the argument. 😭

Parameters

STRING — list of JSON formatted string.
-h / --help — show a help message and exit. Gives you the info 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

Carries out the maintenance tasks — think enforcing retention policies, managing WAL files, all that unglamorous but absolutely necessary backstage work. The main character is not on stage but she is running the show. 👑

Parameters

-h / --help — show a help message and exit. Gives you the info about command usage.
--keep-descriptors — keeps 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

Deletes the specified backup. And yes, you can use a shortcut instead of BACKUP_ID — see below, bestie, we got you.

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. Gives you the info about command usage.

Shortcuts ✂️

Use these instead of BACKUP_ID:

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

Displays diagnostic information about the Barman node — that's the server where Barman is installed — plus all the configured Postgres servers. The receipts include things like global configuration, SSH version, Python version, rsync version, the current configuration and status of all servers, and many more. It's giving full-body scan for your setup. 🔍

Parameters

-h / --help — show a help message and exit. Gives you the info about command usage.
--show-config-source — include the source file which provides the effective value for each configuration option. So you know exactly where a setting came from. No more "who set this??" mysteries. 🕵️

barman export-backup 📦

Synopsis

export-backup
    [ { -h | --help } ]
    [ --compression { gzip | bzip2 | xz } ]
    [ --compression-level COMPRESSION_LEVEL ]
    SERVER_NAME BACKUP_ID OUTPUT_DIRECTORY

Description

Exports the specified backup as a single tarball, suitable for hand-off to an external archival system. The tarball is self-contained: it bundles the backup data files, any tablespaces, the WAL segments required to bring the backup to a consistent state, and the Barman metadata needed to re-register the backup with barman import-backup later. Everything in one bag. 👜✨

The generated file is named using the pattern backup-export-SERVER_NAME-BACKUP_ID-TIMESTAMP-CHECKSUM.tar[.gz|.bz2|.xz].

⚠️ The filename is part of the integrity contract — do not rename the tarball, or barman import-backup will refuse it. Not "might", will. Respect the name, fr fr.

Only full backups in DONE state on a server using local storage can be exported. See Backup export and import for the full feature description.

Parameters

SERVER_NAME — name of the server in barman node.
BACKUP_ID — id of the backup in barman catalog.
OUTPUT_DIRECTORY — existing directory where the exported tarball will be written. Must be writable and executable by the user running Barman. 👀
--compression {gzip | bzip2 | xz} — compress the outer tarball using the given algorithm. By default the tarball is not compressed. Heads up: compression applies only to the outer tarball — data files and WAL segments stored inside are not recompressed, and any pre-existing WAL compression is preserved through the associated xlog.db metadata.
--compression-level COMPRESSION_LEVEL — compression level to pass to the chosen algorithm. Valid levels are 1-9 for gzip and bzip2, and 0-9 for xz. Defaults to the algorithm's own default level. Requires --compression to be set.

📌 Note: passing an explicit --compression-level requires Python 3.12 or newer for gzip/bzip2 and Python 3.14 or newer for xz. On older interpreters the option is accepted, a warning is emitted, and the algorithm's default level is used instead. So it won't crash — it'll just side-eye you and do its own thing. 🙈

barman generate-manifest 🧾

Synopsis

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

Description

Generates a backup_manifest file for a backup. And yes, 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. Gives you the info about command usage.

Shortcuts 💫

Bestie, when a command wants a BACKUP_ID, you can slide in one of these little magic words instead 👇

first / oldest — the oldest available backup for the server, in chronological order. like, the grandma of the backup fam 👵
last / latest — the most recent available backup for the server, in chronological order. the baby of the fam 🍼
last-full / latest-full — the most recent full backup taken with methods rsync or postgres.
last-failed — the 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

Grab a WAL file out of the xlog archive of a server you name. By default, if the WAL file you asked for is actually there, it comes back to you as uncompressed content on 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 import-backup

Synopsis

import-backup
    [ { -h | --help } ]
    SERVER_NAME INPUT_TARBALL

Description

Register a previously exported backup tarball back into the Barman catalog of SERVER_NAME. The tarball is expected to be the output of barman export-backup (or a file restored to disk verbatim by an external archival system from such an export). After a successful import, the backup is fully usable: it appears in barman list-backups, its metadata is available via barman show-backup, and it can be restored with barman restore. 🎀

Imported backups are automatically protected from retention by applying the KEEP:STANDALONE annotation (see barman keep). If you want the imported backup to participate in retention again, remove the annotation explicitly.

Import is performed atomically: the tarball is extracted into a staging directory under basebackups_directory, verified end-to-end, and only then moved into place. If any step fails, the staging area is cleaned up and the catalog and WAL archive are left untouched. See this section Backup export and import for the full feature description. 🦋

Parameters

SERVER_NAME — Name of the server in barman node.
INPUT_TARBALL — Path to the export tarball to import.

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 💅

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 🫶

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 ✨

okay so this one lists all the files inside a specific backup. and bestie, you can totally use a shortcut instead of BACKUP_ID — no need to memorise the actual id, iykyk 💅

🎀 Parameters 🎀

SERVER_NAME — name of the server in barman node.
BACKUP_ID — id of the backup in barman catalog.
-h / --help — shows a help message and dips. gives you the info about how to use the command.
--target — define specific files to be listed. the possible values are:
- standalone (default) — lists the base backup files, and it includes the required WAL files too.
- data — just the data files.
- wal — lists 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 (which one it is depends on whether the base backup you specified is the most recent one available).
- full — same as data + wal.
--list-empty-directories — adds empty directories to the listing. 🫶

🦋 Shortcuts 🦋

use shortcuts instead of BACKUP_ID:

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 Postgres server. for every active subprocess it shows you the process identifier (PID) and the corresponding barman task. so like, a little receipt of everything currently doing stuff 🧚

🎀 Parameters 🎀

SERVER_NAME — name of the Postgres 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 ✨

displays all configured servers along with their descriptions. it's giving roster reveal ✨

🎀 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. little janitor behaviour, we love a clean house 🧹

🎀 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. no cap — it's not a toy.

🎀 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 lives in the xlog.db file, and each Barman server keeps its own copy. so like, one xlog.db per server, no sharing bestie 💅

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

all — all available servers.

💀 `barman recover` 💀

⚠️ Note: this command is deprecated. use the barman restore command instead. like, respectfully, retire her.

🦋 `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. streaming era, we're obsessed 🔥

🎀 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. she's on her way out, bestie 😭

🌸 `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 ]
    [ --partial-wal ]
    [ --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 ]
    [ --skip-archive-wal ]
    [ --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 PostgreSQL server restore operation. Barman will restore the backup from a server into the destination directory.

the restoration can happen locally (on the barman node itself) or remotely (on another machine accessible via SSH). which one you get is determined by whether or not you use the --remote-ssh-command option.

more info on this command lives in the Recovery section. and yes bestie, 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. main character energy fr ✨
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 lets you 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 lets you 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 — turns delta-restore on or off for a delta recovery, bestie. Whether it's on by default depends on your recovery_options setting, so go check that before you come for me 💅
--exclusive — makes the target (that's time, XID or LSN, pick your fighter) non-inclusive. So the boundary itself doesn't count. Rude but valid 🚫
--gcp-zone — tells Barman which GCP zone the instance and disks for snapshot recovery live in. This one lets you override the gcp_zone value from your Barman configuration. Cloud girlies, this is for you ✨
--get-wal / --no-get-wal — enables or disables using get-wal for fetching WAL during recovery. The default is, once again, based on your recovery_options setting.

okay IMPORTANT note bestie 📢 When wals_directory is configured to use cloud storage (like S3, Azure, GCS), restores always require get-wal for WAL fetching. So if you specify --no-get-wal or just leave get-wal out of recovery_options, Barman will lowkey ignore you, automatically enable get-wal for the restore anyway, and issue a warning. It's giving "mother knows best" 😭

--partial-wal — copies .partial WAL files to the recovery destination with the .partial suffix stripped. Barman looks at two sources here: .partial files sitting in the streaming_wals_directory (those were written by pg_receivewal), and .partial files in the main WAL archive (archived during standby promotion, and they might be compressed or encrypted, ngl).

This one is only applicable when you're using --no-get-wal. When --get-wal is in play, .partial files are already handled transparently and this option does literally nothing. It also does nothing when --target-immediate is used, because recovery stops at the first consistent state — before any partial WAL would even be needed. The math is mathing 🧮

See Partial WAL files during recovery <#recovery-partial-wal-files> for the full details.

-h / --help — shows a help message and dips. Gives you the info about how to use the command. Iconic, essential, no notes 👑
-j / --jobs — how many parallel workers to use for copying files during the backup. This overrides the parallel_jobs parameter if you set it in the config file. More workers = more chaos = go off 🏃‍♀️
--jobs-start-batch-period — the time period, in seconds, for starting a single batch of jobs. Overrides the parallel_jobs_start_batch_period parameter if it's set in your config. The default is 1 second ⏱️
--jobs-start-batch-size — the maximum number of parallel workers to kick off in a single batch. Overrides the parallel_jobs_start_batch_size parameter if it's defined in the config file. The default is 10 workers 🫶
--local-staging-path — the path on the Barman host where the whole chain of backups gets combined before being copied over to the destination directory. Everything created inside the staging path gets removed once the restore process finishes. This option is necessary for restoring from block-level incremental backups, and has zero 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. Don't get attached bestie, it's leaving 💀

--network-compression / --no-network-compression — enables or disables network compression during a remote restore. Default is based on the network_compression configuration setting.
--no-retry — there will be no retry in case of an error. It's exactly the same as setting --retry-times 0. One shot, one opportunity 🎯
--recovery-conf-filename — 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. But if you pass --recovery-conf-filename, the recovery options get written to whatever value you give instead. The default works for most Postgres installs, but this option lets you point somewhere else if Postgres is managed by tools that mess with the configuration mechanism — for example, if postgresql.auto.conf is symlinked to /dev/null. Sneaky little setups out here 🙈
--recovery-staging-path — a path on the recovery host where files for a compressed backup get staged before being decompressed to the destination directory. Backups get staged in their own directory inside the staging path, following this naming convention: barman-staging-SERVER_NAME-BACKUP_ID. That staging directory is removed after the restore process completes. 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. Same energy as its sibling above 🥲

--staging-path — a path where intermediate files get staged during a restore. When you're restoring a compressed backup, it acts as the temporary spot for decompression before the files get copied to the final destination. When you're restoring an incremental backup, it's where the backups get combined before being copied to the final destination. This location must have enough space to hold the decompressed/combined backup, so don't skimp 💾
--staging-location — specifies whether your --staging-path is a local or remote path. Those are the two valid values, periodt 📍
--combine-mode — specifies the copy mode for pg_combinebackup when combining incremental backups during a restore.

Options include:

copy (default): use standard file copying when combining incremental backups. The classic, the safe pick 💖
link: use hard links when combining incremental backups. Reconstructing the synthetic backup might be faster (no file copying involved) and use less disk space. Efficient queen 🔗
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. That's not a typo, near-instantaneous ⚡
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. Nerdy and valid 🧚

Refer to the pg_combinebackup documentation <https://www.postgresql.org/docs/current/app-pgcombinebackup.html> for more details and the restrictions of each mode.

--remote-ssh-command — this enables remote restore by specifying the secure shell command to execute on a remote host. It works just like the ssh_command server option in the configuration file for remote restore, i.e. 'ssh USER@SERVER'. Remote besties, we ride 🛰️
--restore-command — a custom restore command to override Barman's default restore_command in the PostgreSQL recovery configuration. Barman's default is suitable for most cases, but this option lets you specify an alternative command if your setup needs one. Can only be used when running a restore with get-wal mode, though. Rules are rules 💅
--retry-sleep — the number of seconds to wait after a failed copy before retrying. Applies to both backup and restore operations, and overrides the basebackup_retry_sleep parameter if it's defined in your config file. Give it a lil breather 😮‍💨
--retry-times — the number of times to retry the base backup copy in case of an error. Applies to both backup and restore operations, and overrides the basebackup_retry_times parameter if it's set in the config file. Persistence is a love language 🔁
--snapshot-recovery-instance — the name of the instance where the disks recovered from the snapshots get attached. This option is necessary when you're recovering backups created with backup_method=snapshot 📸
--snapshot-recovery-zone (deprecated) — zone containing the instance and disks for the snapshot recovery. Deprecated, bestie: it's been replaced by --gcp-zone. Do not use 🚫
--standby-mode — whether to start the Postgres server as a standby. Simple as that, standing by 🧍
--tablespace — specify a tablespace relocation rule. NAME is the tablespace name, and LOCATION is the recovery host destination path where that tablespace gets restored. Moving furniture but make it databases 🪑
--target-action — triggers the specified action when the recovery target is reached. Heads up: this option requires you to define a target along with one of these actions. The possible values are:
- pause: once the recovery target is reached, the server starts in pause state, letting users inspect the instance. Look but don't touch 👀
- promote: once the recovery target is reached, the server exits the recovery operation and is promoted as a master. Glow up, level up 👑
- shutdown: once the recovery target is reached, the server is shut down. Lights off, goodnight 💤
--target-immediate — recovery is completed when a consistent state is reached (that's the end of the base backup). Done and dusted ✅
--target-lsn — recover to the specified LSN (Log Sequence Number). Requires Postgres 10 or above, no exceptions 🔢
--target-name — recover to the specified name of a restore point that was previously created with pg_create_restore_point(name). Named targets, so cute 🏷️
--target-time — recover to the specified time. Use the format YYYY-MM-DD HH:MM:SS.mmm. Format matters, bestie, don't freestyle the milliseconds ⏰
--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. Timeline lore 📜
--target-xid — recover to the specified transaction ID 🆔
--skip-archive-wal — skips archiving staged WAL files before starting the restore. By default, barman restore archives any WAL files in the server's incoming/streaming directory before restoring, which reduces RPO in DR scenarios. Use this option when you want to skip that step entirely 🚀
--staging-wal-directory — a staging directory on the destination host for WAL files when you're performing PITR. If you don't specify it, Barman uses a barman_wal directory inside the destination directory. Default behavior, but make it a choice 🌸

Shortcuts 🎀

Use shortcuts instead of BACKUP_ID.

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 🦋

Displays 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. (fr fr, that's the server's name)
-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.

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 <#catalog-usage-show-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.

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 🎯

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 🎯

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 ✨

(okay bestie, yes, it's the shortcut table again — same energy as before, but for these commands specifically, so let's run it back 💅)

So instead of typing out a whole timestamp backup ID, you can vibe-check a backup for a given server using these shortcuts aka aliases:

first/oldest — the oldest available backup for that server, in chronological order. the OG. 🧚
last/latest — the most recent available backup for that server, chronological order, freshest of the fresh. ✨
last-full/latest-full — the most recent full backup taken with methods rsync or postgres. 👑
last-failed — the most recent backup that failed, in chronological order. it's giving sad girl hours but we still need to know 😭

🌀 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 hands you back a JSON output for a server, and that JSON is packed, bestie — it includes:

all successfully completed backups
all archived WAL files
the configuration
the last WAL file read from xlog.db
and its position within that 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 (this is the incremental synchronization vibe 🔁).
LAST_POS — A hint for quickly positioning in the xlog.db file (again, 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. Lowkey important: it is available only for passive nodes, and it 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. 🎯

Heads up fr fr: only processes that are running at the server level can be terminated. So global processes like cron or config-update can not be terminated by this command. no cap, they're built different.

You can also use the output of barman list-processes to display all active processes for a given server and figure out which tasks can actually be terminated. More details about this command can be found in barman list-processes <#commands-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 — see the shortcuts above, bestie, they got you. 💖

Starting with Postgres 18, tar-format backups taken with the postgres backup method can also be verified, including those compressed with gzip, lz4 or zstd. 🎀

Real talk though: verifying tar or compressed backups requires pg_verifybackup from Postgres 18 or newer to be available on the backup server — otherwise the command will fail with an error. And encrypted backups are not supported by this command. periodt.

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:

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. that's it, that's the whole thing, it's the same command wearing a cuter name 💜

💖 BARMAN-CLI COMMANDS 💖

okay so listen, the barman-cli package comes with a whole lil squad of recommended client utilities that you genuinely should install right alongside your Postgres server. they're not optional vibes, they're the moment. here's the command reference for both of them 🫶

🦋 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 ]
    [ { -p | --parallel } JOBS ]
    [ --prefetch-cache-dir PREFETCH_CACHE_DIR ]
    BARMAN_HOST SERVER_NAME WAL_PATH

✨ Description

bestie this script is the main character of your archive_command. you drop it in there and it ships WAL files over to a Barman host using the put-wal command (which showed up in Barman 2.6, iconic). it opens an SSH connection to the Barman host, so Barman just slots right into your Postgres clusters and business continuity gets so much better 💅

the exit statuses are giving:

0 for SUCCESS 🎉
non-zero for FAILURE 😭

🎀 Parameters

SERVER_NAME — the server name you configured in Barman for the Postgres server that the WAL file is being pulled from.
BARMAN_HOST — the host of the Barman server. yes literally just the host.
WAL_PATH — the value of the '%p' keyword (per archive_command).
-h / --help — shows you a help message and dips out.
-V / --version — prints the program's version number and dips out.
-U / --user — picks the user for the SSH connection to the Barman server (defaults to barman).
--port — defines the port used for that SSH connection to the Barman server.
-z / --gzip — gzip-compresses the WAL file before it gets sent to the Barman server.
-j / --bzip2 — bzip2-compresses the WAL file before sending it to the Barman server.
--xz — xz-compresses the WAL file before sending it to the Barman server.
--snappy — snappy-compresses the WAL file before sending it to the Barman server (this one needs the python-snappy Python library installed, no cap).
--zstd — zstd-compresses the WAL file before sending it to the Barman server (needs the zstandard Python library installed).
--lz4 — lz4-compresses the WAL file before sending it to the Barman server (needs the lz4 Python library installed).
--compression-level — the compression level the selected algorithm should use. valid values are integers inside the supported range of whatever algorithm you picked, or one of the predefined labels: low, medium, and high. the range for each algorithm, plus what level each predefined label maps to, lives over in compression_level <#configuration-options-compression-level>.
-c / --config — points at the configuration file on the Barman server.
-t / --test — tests the connection and configuration of the Postgres server you named in Barman, to make sure it's ready to receive WAL files. heads up: this option ignores the mandatory argument WAL_PATH.
--md5 — uses MD5 instead of SHA256 as the hash algorithm when calculating the checksum of the WAL file on its way to the Barman server. this exists to keep compatibility with older server versions, because older Barman servers only ever supported MD5. throwback fr.
-p / --parallel — the maximum number of WAL files to archive in parallel. defaults to 0 (aka no parallelism, one at a time, chill vibes).
--prefetch-cache-dir — the directory where cache metadata gets stored when you're using --parallel. defaults to /tmp/barman-SERVER_NAME-COMPUTED_HASH.

Note: when compression is enabled in barman-wal-archive, it takes precedence over the compression settings configured on the Barman server, if they differ. like, it wins. periodt.

Important: when compression is enabled in barman-wal-archive, it happens on the client side, before the file is sent to Barman. so pls be mindful of your database server's load and of the compression algorithm and level you chose — heavier compression can delay WAL shipping, and then WAL files just start piling up 😭

🌸 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 one is your restore_command, bestie. it lets Postgres servers pull WAL files back through Barman's get-wal feature. it opens an SSH connection to the Barman host and makes Barman fit into your Postgres clusters like it was always meant to be there, which is honestly great for business continuity 💜

the exit statuses are:

0 for SUCCESS 🎉
1 for remote get-wal command FAILURE — usually because the WAL you asked for could not be found 🙈
2 for ssh connection FAILURE 💀
any other non-zero for FAILURE

🎀 Parameters

SERVER_NAME — the server name you configured in Barman for the Postgres server the WAL file is being retrieved from.
BARMAN_HOST — the host of the Barman server.
WAL_NAME — the value of the '%f' keyword (per restore_command).
WAL_DEST — the value of the '%p' keyword (per restore_command).
-h / --help — shows a help message and exits.
-V / --version — prints the program's version number and exits.
-U / --user — the user for the SSH connection to the Barman server (defaults to barman).
--port — defines the port used for the SSH connection to the Barman server.
-s / --sleep — pauses for SECONDS after a failed get-wal request (defaults to 0 — no wait at all).
-p / --parallel — the number of WAL files to fetch in parallel. default is 0 (disabled). when you set it to a value greater than 1, it fetches the WAL file you asked for plus the next N - 1 files at the same time. those extra files get staged in a local spool directory (see --spool-dir) so the restore requests that come after can be served immediately straight from local storage. it's giving prepared. it's giving ahead of the game. ✨
--spool-dir — the directory used to stage those extra WALs fetched when you're using --parallel. default is /var/tmp/walrestore.
-P / --partial — includes partial WAL files (.partial) in the retrieval.
-z / --gzip — transfers WAL files compressed with gzip.
-j / --bzip2 — transfers WAL files compressed with bzip2.
--keep-compression — if you specify this, compressed files get transferred exactly as they are and decompressed on arrival on the client side.
-c / --config — points at the configuration file on the Barman server.
-t / --test — tests the connection and configuration of the Postgres server you specified in Barman to make sure it's ready to receive WAL files. heads up again: this option ignores the mandatory arguments WAL_NAME and WAL_DEST.

Warning: -z / --gzip and -j / --bzip2 are deprecated and are gonna get removed in the future, nooo 😭. for WAL compression, pls make sure to enable it directly on the Barman server through the compression configuration option instead. we're moving on, it's for the best.

📝 Author

EnterpriseDB

©️ Copyright

and that's the whole page, bestie!! you made it to the end of BARMAN(1) 🥳 this version is 3.20, dated Sep 29, 2026, and yes we're all a little obsessed. go archive some WALs, go restore some WALs, go be the main character of your own business continuity plan. mwah 💋💅✨

📦 where this page comes from

epel 10: barman 3.20.1-1.el10_3 · GPL-3.0-only
fedora 43: barman 3.20.1-1.fc43 · GPL-3.0-only
fedora 43: barman 3.20.1-3.fc43 · GPL-3.0-only
fedora 44: barman 3.20.1-1.fc44 · GPL-3.0-only
fedora 44: barman 3.20.1-3.fc44 · GPL-3.0-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms