Ubuntu Manpage: barman - Backup and Recovery Manager for PostgreSQL

NAME

       barman - Backup and Recovery Manager for PostgreSQL

SYNOPSIS

       barman [OPTIONS] COMMAND

DESCRIPTION

       Barman  is  an  administration tool for disaster recovery of PostgreSQL servers written in
       Python and maintained by EnterpriseDB.  Barman can  perform  remote  backups  of  multiple
       servers in business critical environments and helps DBAs during the recovery phase.

OPTIONS

       -h, --help
              Show a help message and exit.

       -v, --version
              Show program version number and exit.

       -c CONFIG, --config CONFIG
              Use the specified configuration file.

       --color {never,always,auto}, --colour {never,always,auto}
              Whether to use colors in the output (default: auto)

       -q, --quiet
              Do not output anything.  Useful for cron scripts.

       -d, --debug
              debug output (default: False)

       --log-level {NOTSET,DEBUG,INFO,WARNING,ERROR,CRITICAL}
              Override the default log level

       -f {json,console}, --format {json,console}
              output format (default: 'console')

COMMANDS

Important: every command has a help option

archive-wal SERVER_NAME
Get any incoming xlog file (both through standard archive_command and streaming
replication, where applicable) and moves them in the WAL archive for that server.
If necessary, apply compression when requested by the user.

backup SERVER_NAME
Perform a backup of SERVER_NAME using parameters specified in the configuration
file. Specify all as SERVER_NAME to perform a backup of all the configured
servers. You can also specify SERVER_NAME multiple times to perform a backup of
the specified servers -- e.g. barman backup SERVER_1_NAME SERVER_2_NAME.

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

--immediate-checkpoint
forces the initial checkpoint to be done as quickly as possible. Overrides
value of the parameter immediate_checkpoint, if present in the configuration
file.

--no-immediate-checkpoint
forces to wait for the checkpoint. Overrides value of the parameter
immediate_checkpoint, if present in the configuration file.

--reuse-backup [INCREMENTAL_TYPE]
Overrides reuse_backup option behaviour. Possible values for
INCREMENTAL_TYPE are:

• off: do not reuse the last available backup;

• copy: reuse the last available backup for a server and create a copy of
the unchanged files (reduce backup time);

• link: reuse the last available backup for a server and create a hard link
of the unchanged files (reduce backup time and space);

link is the default target if --reuse-backup is used and INCREMENTAL_TYPE is
not explicit.

--retry-times
Number of retries of base backup copy, after an error. Used during both
backup and recovery operations. Overrides value of the parameter
basebackup_retry_times, if present in the configuration file.

--no-retry
Same as --retry-times 0

--retry-sleep
Number of seconds of wait after a failed copy, before retrying. Used during
both backup and recovery operations. Overrides value of the parameter
basebackup_retry_sleep, if present in the configuration file.

-j, --jobs
Number of parallel workers to copy files during backup. Overrides value of
the parameter parallel_jobs, if present in the configuration file.

--jobs-start-batch-period
The time period in seconds over which a single batch of jobs will be
started. Overrides the value of parallel_jobs_start_batch_period, if
present in the configuration file. Defaults to 1 second.

--jobs-start-batch-size
Maximum number of parallel workers to start in a single batch. Overrides
the value of parallel_jobs_start_batch_size, if present in the configuration
file. Defaults to 10 jobs.

--bwlimit KBPS
maximum transfer rate in kilobytes per second. A value of 0 means no limit.
Overrides 'bandwidth_limit' configuration option. Default is undefined.

--wait, -w
wait for all required WAL files by the base backup to be archived

--wait-timeout
the time, in seconds, spent waiting for the required WAL files to be
archived before timing out

check-backup SERVER_NAME BACKUP_ID
Make sure that all the required WAL files to check the consistency of a physical
backup (that is, from the beginning to the end of the full backup) are correctly
archived. This command is automatically invoked by the cron command and at the end
of every backup operation.

check-wal-archive SERVER_NAME
Check that the WAL archive destination for SERVER_NAME is safe to use for a new
PostgreSQL cluster. With no optional args (the default) this will pass if the WAL
archive is empty and fail otherwise.

--timeline [TIMELINE]
A positive integer specifying the earliest timeline for which associated
WALs should cause the check to fail. The check will pass if all WAL content
in the archive relates to earlier timelines. If any WAL files are on this
timeline or greater then the check will fail.

check SERVER_NAME
Show diagnostic information about SERVER_NAME, including: Ssh connection check,
PostgreSQL version, configuration and backup directories, archiving process,
streaming process, replication slots, etc. Specify all as SERVER_NAME to show
diagnostic information about all the configured servers.

--nagios
Nagios plugin compatible output

cron Perform maintenance tasks, such as enforcing retention policies or WAL files
management.

--keep-descriptors
Keep the stdout and the stderr streams of the Barman subprocesses attached
to this one. This is useful for Docker based installations.

delete SERVER_NAME BACKUP_ID
Delete the specified backup. Backup ID shortcuts section below for available
shortcuts.

diagnose
Collect diagnostic information about the server where barman is installed and all
the configured servers, including: global configuration, SSH version, Python
version, rsync version, as well as current configuration and status of all servers.

generate-manifest SERVER_NAME BACKUP_ID
Generates a backup_manifest file for a backup_id.

get-wal [OPTIONS] SERVER_NAME WAL_NAME
Retrieve a WAL file from the xlog archive of a given server. By default, the
requested WAL file, if found, is returned as uncompressed content to STDOUT. The
following options allow users to change this behaviour:

-o OUTPUT_DIRECTORY
destination directory where the get-wal will deposit the requested WAL

-P, --partial
retrieve also partial WAL files (.partial)

-z output will be compressed using gzip

-j output will be compressed using bzip2

-p SIZE
peek from the WAL archive up to SIZE WAL files, starting from the requested
one. 'SIZE' must be an integer >= 1. When invoked with this option,
get-wal returns a list of zero to 'SIZE' WAL segment names, one per row.

-t, --test
test both the connection and the configuration of the requested PostgreSQL
server in Barman for WAL retrieval. With this option, the 'WAL_NAME'
mandatory argument is ignored.

keep SERVER_NAME BACKUP_ID
Flag the specified backup as an archival backup which should be kept forever,
regardless of any retention policies in effect. See the Backup ID shortcuts
section below for available shortcuts.

--target RECOVERY_TARGET
Specify the recovery target for the archival backup. Possible values for
RECOVERY_TARGET are:

• full: The backup can always be used to recover to the latest point in
time. To achieve this, Barman will retain all WALs needed to ensure
consistency of the backup and all subsequent WALs.

• standalone: The backup can only be used to recover the server to its state
at the time the backup was taken. Barman will only retain the WALs needed
to ensure consistency of the backup.

--status
Report the archival status of the backup. This will either be the recovery
target of full or standalone for archival backups or nokeep for backups
which have not been flagged as archival.

--release
Release the keep flag from this backup. This will remove its archival
status and make it available for deletion, either directly or by retention
policy.

list-backups SERVER_NAME
Show available backups for SERVER_NAME. This command is useful to retrieve a
backup ID. For example:

servername 20111104T102647 - Fri Nov 4 10:26:48 2011 - Size: 17.0 MiB - WAL Size: 100 B

In this case, *20111104T102647* is the backup ID.

list-files [OPTIONS] SERVER_NAME BACKUP_ID
List all the files in a particular backup, identified by the server name and the
backup ID. See the Backup ID shortcuts section below for available shortcuts.

--target TARGET_TYPE
Possible values for TARGET_TYPE are:

• data: lists just the data files;

• standalone: lists the base backup files, including required WAL files;

• wal: lists all the WAL files between the start of the base backup and the
end of the log / 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.

The default value is standalone.

list-servers
Show all the configured servers, and their descriptions.

put-wal [OPTIONS] SERVER_NAME
Receive a WAL file from a remote server and securely store it into the SERVER_NAME
incoming directory. The WAL file is retrieved from the STDIN, and must be
encapsulated in a tar stream together with a MD5SUMS file to validate it. This
command is meant to be invoked through SSH from a remote barman-wal-archive utility
(part of barman-cli package). Do not use this command directly unless you take
full responsibility of the content of files.

-t, --test
test both the connection and the configuration of the requested PostgreSQL
server in Barman to make sure it is ready to receive WAL files.

rebuild-xlogdb SERVER_NAME
Perform a rebuild of the WAL file metadata for SERVER_NAME (or every server, using
the all shortcut) guessing it from the disk content. The metadata of the WAL
archive is contained in the xlog.db file, and every Barman server has its own copy.

receive-wal SERVER_NAME
Start the stream of transaction logs for a server. The process relies on
pg_receivewal/pg_receivexlog to receive WAL files from the PostgreSQL servers
through the streaming protocol.

--stop stop the receive-wal process for the server

--reset
reset the status of receive-wal, restarting the streaming from the current
WAL file of the server

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

recover [OPTIONS] SERVER_NAME BACKUP_ID DESTINATION_DIRECTORY
Recover a backup in a given directory (local or remote, depending on the
--remote-ssh-command option settings). See the Backup ID shortcuts section below
for available shortcuts.

--target-tli TARGET_TLI
Recover the specified timeline. The special values current and latest can
be used in addition to a numeric timeline ID. The default behaviour for
PostgreSQL versions >= 12 is to recover to the latest timeline in the WAL
archive. The default for PostgreSQL versions < 12 is to recover along the
timeline which was current when the backup was taken.

--target-time TARGET_TIME
Recover to the specified time.

You can use any valid unambiguous representation (e.g: "YYYY-MM-DD
HH:MM:SS.mmm").

--target-xid TARGET_XID
Recover to the specified transaction ID.

--target-lsn TARGET_LSN
Recover to the specified LSN (Log Sequence Number). Requires PostgreSQL 10
or above.

--target-name TARGET_NAME
Recover to the named restore point previously created with the
pg_create_restore_point(name).

--target-immediate
Recover ends when a consistent state is reached (end of the base backup)

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

--target-action ACTION
Trigger the specified action once the recovery target is reached. Possible
actions are: pause, shutdown and promote. This option requires a target to
be defined, with one of the above options.

--tablespace NAME:LOCATION
Specify tablespace relocation rule.

--remote-ssh-command SSH_COMMAND
This options activates remote recovery, by specifying the secure shell
command to be launched on a remote host. This is the equivalent of the
"ssh_command" server option in the configuration file for remote recovery.
Example: 'ssh postgres@db2'.

--retry-times RETRY_TIMES
Number of retries of data copy during base backup after an error. Overrides
value of the parameter basebackup_retry_times, if present in the
configuration file.

--no-retry
Same as --retry-times 0

--retry-sleep
Number of seconds of wait after a failed copy, before retrying. Overrides
value of the parameter basebackup_retry_sleep, if present in the
configuration file.

--bwlimit KBPS
maximum transfer rate in kilobytes per second. A value of 0 means no limit.
Overrides 'bandwidth_limit' configuration option. Default is undefined.

-j , --jobs
Number of parallel workers to copy files during recovery. Overrides value
of the parameter parallel_jobs, if present in the configuration file. Works
only for servers configured through rsync/SSH.

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

--network-compression, --no-network-compression
Enable/Disable network compression during remote recovery. Default is based
on network_compression configuration setting.

--standby-mode
Specifies whether to start the PostgreSQL server as a standby. Default is
undefined.

--recovery-staging-path STAGING_PATH
A path to a location on the recovery host (either the barman server or a
remote host if --remote-ssh-command is also used) 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 according to the following naming convention:
"barman-staging-SERVER_NAME-BACKUP_ID". The staging directory within the
staging path will be removed at the end of the recovery process. This
option is required when recovering from compressed backups and has no effect
otherwise.

--recovery-conf-filename RECOVERY_CONF_FILENAME
The name of the file where Barman should write the PostgreSQL recovery
options when recovering backups for PostgreSQL versions 12 and later. This
defaults to postgresql.auto.conf however if --recovery-conf-filename is used
then recovery options will be written to RECOVERY_CONF_FILENAME instead.
The default value is correct for a typical PostgreSQL installation however
if PostgreSQL is being managed by tooling which modifies the configuration
mechanism (for example postgresql.auto.conf could be symlinked to /dev/null)
then this option can be used to write the recovery options to an alternative
location.

--snapshot-recovery-instance INSTANCE_NAME
Name of the instance where the disks recovered from the snapshots are
attached. This option is required when recovering backups made with
backup_method = snapshot.

--gcp-zone ZONE_NAME
Name of the availability zone where the instance and disks for snapshot are
located. This option is required when recovering backups made with
backup_method = snapshot.

replication-status [OPTIONS] SERVER_NAME
Shows live information and status of any streaming client attached to the given
server (or servers). Default behaviour can be changed through the following
options:

--minimal
machine readable output (default: False)

--target TARGET_TYPE
Possible values for TARGET_TYPE are:

• hot-standby: lists only hot standby servers

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

• all: any streaming client (default)

show-backup SERVER_NAME BACKUP_ID
Show detailed information about a particular backup, identified by the server name
and the backup ID. See the Backup ID shortcuts section below for available
shortcuts. For example:

Backup 20150828T130001:
Server Name : quagmire
Status : DONE
PostgreSQL Version : 90402
PGDATA directory : /srv/postgresql/9.4/main/data

Base backup information:
Disk usage : 12.4 TiB (12.4 TiB with WALs)
Incremental size : 4.9 TiB (-60.02%)
Timeline : 1
Begin WAL : 0000000100000CFD000000AD
End WAL : 0000000100000D0D00000008
WAL number : 3932
WAL compression ratio: 79.51%
Begin time : 2015-08-28 13:00:01.633925+00:00
End time : 2015-08-29 10:27:06.522846+00:00
Begin Offset : 1575048
End Offset : 13853016
Begin XLOG : CFD/AD180888
End XLOG : D0D/8D36158

WAL information:
No of files : 35039
Disk usage : 121.5 GiB
WAL rate : 275.50/hour
Compression ratio : 77.81%
Last available : 0000000100000D95000000E7

Catalog information:
Retention Policy : not enforced
Previous Backup : 20150821T130001
Next Backup : - (this is the latest base backup)

show-servers SERVER_NAME
Show information about SERVER_NAME, including: conninfo, backup_directory,
wals_directory and many more. Specify all as SERVER_NAME to show information about
all the configured servers.

status SERVER_NAME
Show information about the status of a server, including: number of available
backups, archive_command, archive_status and many more. For example:

Server quagmire:
Description: The Giggity database
Passive node: False
PostgreSQL version: 9.3.9
PostgreSQL Data directory: /srv/postgresql/9.3/data
PostgreSQL 'archive_command' setting: rsync -a %p barman@backup:/var/lib/barman/quagmire/incoming
Last archived WAL: 0000000100003103000000AD
Current WAL segment: 0000000100003103000000AE
Retention policies: enforced (mode: auto, retention: REDUNDANCY 2, WAL retention: MAIN)
No. of available backups: 2
First available backup: 20150908T003001
Last available backup: 20150909T003001
Minimum redundancy requirements: satisfied (2/1)

switch-wal SERVER_NAME
Execute pg_switch_wal() on the target server (from PostgreSQL 10), or
pg_switch_xlog (for PostgreSQL 8.3 to 9.6).

--force
Forces the switch by executing CHECKPOINT before pg_switch_xlog().
IMPORTANT: executing a CHECKPOINT might increase I/O load on a PostgreSQL
server. Use this option with care.

--archive
Wait for one xlog file to be archived. If after a defined amount of time
(default: 30 seconds) no xlog file is archived, Barman will terminate with
failure exit code. Available also on standby servers.

--archive-timeout TIMEOUT
Specifies the amount of time in seconds (default: 30 seconds) the archiver
will wait for a new xlog file to be archived before timing out. Available
also on standby servers.

switch-xlog SERVER_NAME
Alias for switch-wal (kept for back-compatibility)

sync-backup SERVER_NAME BACKUP_ID
Command used for the synchronisation of a passive node with its primary. Executes
a copy of all the files of a BACKUP_ID that is present on SERVER_NAME node. This
command is available only for passive nodes, and uses the primary_ssh_command
option to establish a secure connection with the primary node.

sync-info SERVER_NAME [LAST_WAL [LAST_POSITION]]
Collect information regarding the current status of a Barman server, to be used for
synchronisation purposes. Returns a JSON output representing SERVER_NAME, that
contains: all the successfully finished backup, all the archived WAL files, the
configuration, last WAL file been read from the xlog.db and the position in the
file.

LAST_WAL
tells sync-info to skip any WAL file previous to that (incremental
synchronisation)

LAST_POSITION
hint for quickly positioning in the xlog.db file (incremental
synchronisation)

sync-wals SERVER_NAME
Command used for the synchronisation of a passive node with its primary. Executes
a copy of all the archived WAL files that are present on SERVER_NAME node. This
command is available only for passive nodes, and uses the primary_ssh_command
option to establish a secure connection with the primary node.

verify-backup SERVER_NAME BACKUP_ID
Executes pg_verifybackup against a backup manifest file (available since Postgres
13). For rsync backups, it can be used with generate-manifest command. Requires
pg_verifybackup installed on the backup server

verify SERVER_NAME BACKUP_ID
Alias for verify-backup

BACKUP ID SHORTCUTS

       Rather   than   using  the  timestamp  backup  ID,  you  can  use  any  of  the  following
       shortcuts/aliases to identity a backup for a given server:

       first  Oldest available backup for that server, in chronological order.

       last   Latest available backup for that server, in chronological order.

       latest same ast last.

       oldest same ast first.

       last-failed
              Latest failed backup, in chronological order.

EXIT STATUS

       0      Success

       Not zero
              Failure

BUGS

       Barman has been extensively tested, and is currently  being  used  in  several  production
       environments.  However, we cannot exclude the presence of bugs.

       Any  bug can be reported via the GitHub bug tracker.  Along with the bug submission, users
       can provide developers with diagnostics information obtained through  the  barman diagnose
       command.

AUTHORS

       Barman maintainers (in alphabetical order):

       • Abhijit Menon-Sen

       • Didier Michel

       • Michael Wallace

       Past contributors (in alphabetical order):

       • Anna Bellandi (QA/testing)

       • Britt Cole (documentation reviewer)

       • Carlo Ascani (developer)

       • Francesco Canovai (QA/testing)

       • Gabriele Bartolini (architect)

       • Gianni Ciolli (QA/testing)

       • Giulio Calacoci (developer)

       • Giuseppe Broccolo (developer)

       • Jane Threefoot (developer)

       • Jonathan Battiato (QA/testing)

       • Leonardo Cecchi (developer)

       • Marco Nenciarini (project leader)

       • Niccolò Fei (QA/testing)

       • Rubens Souza (QA/testing)

       • Stefano Bianucci (developer)

RESOURCES

       • Homepage: <https://www.pgbarman.org/>

       • Documentation: <https://docs.pgbarman.org/>

       • Professional support: <https://www.enterprisedb.com/>

COPYING

       Barman  is  the  property of EnterpriseDB UK Limited and its code is distributed under GNU
       General Public License v3.

       © Copyright EnterpriseDB UK Limited 2011-2023

AUTHORS

       EnterpriseDB <https://www.enterprisedb.com>.

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

COMMANDS

BACKUP ID SHORTCUTS

EXIT STATUS

SEE ALSO

BUGS

AUTHORS

RESOURCES

COPYING

AUTHORS