BARMAN(1)

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 2ndQuadrant. 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)

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

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

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

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

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.

list-backup 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-server
    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.

    --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) (for PostgreSQL 9.1 and above users).

    --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 (PostgreSQL 9.1 and above), shutdown (PostgreSQL 9.5 and above) and promote (ditto). 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.

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-server 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
      pgespresso extension: Not available
      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 teminate 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.

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.

EXIT STATUS

0   Success

Not zero
    Failure

SEE ALSO

barman (5).

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 Sourceforge bug tracker. Along the bug submission, users can provide developers with diagnostics information obtained through the barman diagnose command.

AUTHORS

In alphabetical order:

•   Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (architect)

•   Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)

•   Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)

•   Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)

•   Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)

•   Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)

•   Britt Cole <britt.cole@2ndquadrant.com> (documentation)

•   Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (project leader)

•   Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)

Past contributors:

•   Carlo Ascani

•   Stefano Bianucci

•   Giuseppe Broccolo

RESOURCES

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

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

•   Professional support: <http://www.2ndQuadrant.com/>

COPYING

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

Copyright (C) 2011-2019 2ndQuadrant Limited - <http://www.2ndQuadrant.com/>.

AUTHORS
2ndQuadrant Limited <https://www.2ndQuadrant.com>.