Ubuntu Manpage: barman - Barman Commands

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 eligible  for │
                          │                       │ a   block-level   incremental  backup │
                          │                       │ using the --incremental option.       │
                          ├───────────────────────┼───────────────────────────────────────┤
                          │ 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 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.

barman backup
Synopsis
backup
[ --bwlimit KBPS ]
[ --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 [ ... ]

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.

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

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 eligible for │
│ │ a block-level incremental backup │
│ │ using the --incremental option. │
├───────────────────────┼───────────────────────────────────────┤
│ last-failed │ Most recent backup that failed, in │
│ │ chronological order. │
└───────────────────────┴───────────────────────────────────────┘

barman check
Synopsis
check [ --nagios ] 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.

--nagios
Nagios plugin compatible output.

barman config-switch
Synopsis
config-switch 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.

--reset
Reset the server's configurations.

barman config-update
Synopsis
config-update 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.

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

barman cron
Synopsis
cron [ --keep-descriptors ]

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

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

barman diagnose
Synopsis
diagnose

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.

barman generate-manifest
Synopsis
generate-manifest 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.

barman get-wal
Synopsis
get-wal
[ -j ]
[ -o OUTPUT_DIRECTORY ]
[ -p VALUE ]
[ { -P | --partial } ]
[ { -t | --test } ]
[ -z ]
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.

-j / --bzip2
Output will be compressed using bzip2.

-z / --gzip
Output will be compressed using gzip.

--keep-compression
Do not uncompress the file content. The output will be the original compressed file.

-o Destination directory where barman will store the WAL file.

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

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

--status
Report the archival status of the backup. The status will be either full or standalone for
archival backups, or nokeep for backups that have not been designated as archival.

--target
Define the recovery target for the archival backup. The possible values are:

• full: The backup can be used to recover to the most recent point in time. To support this,
Barman will keep all necessary WALs to maintain the backup's consistency as well as any
subsequent WALs.

• standalone: The backup can only be used to restore the server to its state at the time of the
backup. Barman will retain only the WALs required to ensure the backup's consistency.

barman list-backups
Synopsis
list-backups 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

barman list-files
Synopsis
list-files
[ --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.

--target
Define specific files to be listed. The possible values are:

• standalone (default): List the base backup files, including required WAL files.

• data: List just the data files.

• wal: List all the WAL files between the start of the base backup and the end of the log or the
start of the following base backup (depending on whether the specified base backup is the most
recent one available).

• full: same as data + wal.

barman list-servers
Synopsis
list-servers [ --minimal ]

Description
Display all configured servers along with their descriptions.

Parameters
--minimal
Machine readable output.

barman lock-directory-cleanup
Synopsis
lock-directory-cleanup

Description
Automatically removes unused lock files from the barman_lock_directory.

barman put-wal
Synopsis
put-wal [ { -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

-t / --test
Test both the connection and configuration of the specified Postgres server in Barman for WAL
retrieval.

barman rebuild-xlogdb
Synopsis
rebuild-xlogdb 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.

barman receive-wal
Synopsis
receive-wal
[ --create-slot ]
[ --drop-slot ]
[ --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.

--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 ]
[ { -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 ]
[ --standby-mode ]
[ --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 ]
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 barman catalog.

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.

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

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

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

barman replication-status
Synopsis
replication-status
[ --minimal ]
[ --source { backup-host | wal-host } ]
[ --target { hot-standby | wal-streamer | all } ]
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

--minimal
Machine readable output.

--source
The possible values are:

• backup-host (default): List clients using the backup connection information for a server.

• wal-host: List clients using the WAL streaming connection information for a server.

--target
The possible values are:

• hot-standby: List only hot standby servers.

• wal-streamer: List only WAL streaming clients, such as pg_receivewal.

• all (default): List all streaming clients.

barman show-backup
Synopsis
show-backup 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.

barman show-servers
Synopsis
show-servers 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

Shortcuts
┌──────────┬───────────────────────┐
│ Shortcut │ Description │
├──────────┼───────────────────────┤
│ all │ All available servers │
└──────────┴───────────────────────┘

barman status
Synopsis
status 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

barman switch-wal
Synopsis
switch-wal
[ --archive ]
[ --archive-timeout ]
[ --force ]
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.

barman switch-xlog
Description
Alias for the switch-wal command.

barman sync-backup
Synopsis
sync-backup 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.

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 eligible for │
│ │ a block-level incremental backup │
│ │ using the --incremental option. │
├───────────────────────┼───────────────────────────────────────┤
│ last-failed │ Most recent backup that failed, in │
│ │ chronological order. │
└───────────────────────┴───────────────────────────────────────┘

barman sync-info
Synopsis
sync-info [ --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).

barman sync-wals
Synopsis
sync-wals 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

barman verify-backup
Synopsis
verify-backup 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.

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 arguments WAL_NAME and WAL_DEST.

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

3.12                                              Dec 09, 2024                                         BARMAN(1)