.\" Automatically generated by Pandoc 2.5 .\" .TH "BARMAN" "1" "February 4, 2019" "Barman User manuals" "Version 2.6" .hy .SH NAME .PP barman \- Backup and Recovery Manager for PostgreSQL .SH SYNOPSIS .PP barman [\f[I]OPTIONS\f[R]] \f[I]COMMAND\f[R] .SH DESCRIPTION .PP 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. .SH OPTIONS .TP .B \-v, \-\-version Show program version number and exit. .TP .B \-q, \-\-quiet Do not output anything. Useful for cron scripts. .TP .B \-h, \-\-help Show a help message and exit. .TP .B \-c \f[I]CONFIG\f[R], \-\-config \f[I]CONFIG\f[R] Use the specified configuration file. .TP .B \-\-color \f[I]{never,always,auto}\f[R], \-\-colour \f[I]{never,always,auto}\f[R] Whether to use colors in the output (default: \f[I]auto\f[R]) .SH COMMANDS .PP Important: every command has a help option .TP .B archive\-wal \f[I]SERVER_NAME\f[R] Get any incoming xlog file (both through standard \f[C]archive_command\f[R] and streaming replication, where applicable) and moves them in the WAL archive for that server. If necessary, apply compression when requested by the user. .TP .B backup \f[I]SERVER_NAME\f[R] Perform a backup of \f[C]SERVER_NAME\f[R] using parameters specified in the configuration file. Specify \f[C]all\f[R] as \f[C]SERVER_NAME\f[R] to perform a backup of all the configured servers. .RS .TP .B \-\-immediate\-checkpoint forces the initial checkpoint to be done as quickly as possible. Overrides value of the parameter \f[C]immediate_checkpoint\f[R], if present in the configuration file. .TP .B \-\-no\-immediate\-checkpoint forces to wait for the checkpoint. Overrides value of the parameter \f[C]immediate_checkpoint\f[R], if present in the configuration file. .TP .B \-\-reuse\-backup [INCREMENTAL_TYPE] Overrides \f[C]reuse_backup\f[R] option behaviour. Possible values for \f[C]INCREMENTAL_TYPE\f[R] are: .RS .IP \[bu] 2 \f[I]off\f[R]: do not reuse the last available backup; .IP \[bu] 2 \f[I]copy\f[R]: reuse the last available backup for a server and create a copy of the unchanged files (reduce backup time); .IP \[bu] 2 \f[I]link\f[R]: reuse the last available backup for a server and create a hard link of the unchanged files (reduce backup time and space); .PP \f[C]link\f[R] is the default target if \f[C]\-\-reuse\-backup\f[R] is used and \f[C]INCREMENTAL_TYPE\f[R] is not explicited. .RE .TP .B \-\-retry\-times Number of retries of base backup copy, after an error. Used during both backup and recovery operations. Overrides value of the parameter \f[C]basebackup_retry_times\f[R], if present in the configuration file. .TP .B \-\-no\-retry Same as \f[C]\-\-retry\-times 0\f[R] .TP .B \-\-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 \f[C]basebackup_retry_sleep\f[R], if present in the configuration file. .TP .B \-j , \-\-jobs Number of parallel workers to copy files during backup. Overrides value of the parameter \f[C]parallel_jobs\f[R], if present in the configuration file. .RE .TP .B check\-backup \f[I]SERVER_NAME\f[R] \f[I]BACKUP_ID\f[R] 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 \f[C]cron\f[R] command and at the end of every backup operation. .TP .B check \f[I]SERVER_NAME\f[R] Show diagnostic information about \f[C]SERVER_NAME\f[R], including: Ssh connection check, PostgreSQL version, configuration and backup directories, archiving process, streaming process, replication slots, etc. Specify \f[C]all\f[R] as \f[C]SERVER_NAME\f[R] to show diagnostic information about all the configured servers. .RS .TP .B \-\-nagios Nagios plugin compatible output .RE .TP .B cron Perform maintenance tasks, such as enforcing retention policies or WAL files management. .TP .B delete \f[I]SERVER_NAME\f[R] \f[I]BACKUP_ID\f[R] Delete the specified backup. Backup ID shortcuts section below for available shortcuts. .TP .B diagnose Collect diagnostic information about the server where barman is installed and all the configured servers, including: global configuration, SSH version, Python version, \f[C]rsync\f[R] version, as well as current configuration and status of all servers. .TP .B get\-wal \f[I][OPTIONS]\f[R] \f[I]SERVER_NAME\f[R] \f[I]WAL_ID\f[R] Retrieve a WAL file from the \f[C]xlog\f[R] archive of a given server. By default, the requested WAL file, if found, is returned as uncompressed content to \f[C]STDOUT\f[R]. The following options allow users to change this behaviour: .RS .TP .B \-o \f[I]OUTPUT_DIRECTORY\f[R] destination directory where the \f[C]get\-wal\f[R] will deposit the requested WAL .TP .B \-z output will be compressed using gzip .TP .B \-j output will be compressed using bzip2 .TP .B \-p \f[I]SIZE\f[R] peek from the WAL archive up to \f[I]SIZE\f[R] WAL files, starting from the requested one. \[aq]SIZE\[aq] must be an integer >= 1. When invoked with this option, get\-wal returns a list of zero to \[aq]SIZE\[aq] WAL segment names, one per row. .RE .TP .B list\-backup \f[I]SERVER_NAME\f[R] Show available backups for \f[C]SERVER_NAME\f[R]. This command is useful to retrieve a backup ID. For example: .IP .nf \f[C] servername 20111104T102647 \- Fri Nov 4 10:26:48 2011 \- Size: 17.0 MiB \- WAL Size: 100 B \f[R] .fi .IP .nf \f[C] In this case, *20111104T102647* is the backup ID. \f[R] .fi .TP .B list\-files \f[I][OPTIONS]\f[R] \f[I]SERVER_NAME\f[R] \f[I]BACKUP_ID\f[R] 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. .RS .TP .B \-\-target \f[I]TARGET_TYPE\f[R] Possible values for TARGET_TYPE are: .RS .IP \[bu] 2 \f[I]data\f[R]: lists just the data files; .IP \[bu] 2 \f[I]standalone\f[R]: lists the base backup files, including required WAL files; .IP \[bu] 2 \f[I]wal\f[R]: 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); .IP \[bu] 2 \f[I]full\f[R]: same as data + wal. .PP The default value is \f[C]standalone\f[R]. .RE .RE .TP .B list\-server Show all the configured servers, and their descriptions. .TP .B put\-wal \f[I]SERVER_NAME\f[R] Receive a WAL file from a remote server and securely store it into the \f[C]SERVER_NAME\f[R] incoming directory. The WAL file is retrieved from the \f[C]STDIN\f[R], and must be encapsulated in a tar stream together with a \f[C]MD5SUMS\f[R] file to validate it. This command is meant to be invoked through SSH from a remote \f[C]barman\-wal\-archive\f[R] utility (part of barman\-cli). Do not use this command directly unless you take full responsibility of the content of files. .TP .B rebuild\-xlogdb \f[I]SERVER_NAME\f[R] Perform a rebuild of the WAL file metadata for \f[C]SERVER_NAME\f[R] (or every server, using the \f[C]all\f[R] shortcut) guessing it from the disk content. The metadata of the WAL archive is contained in the \f[C]xlog.db\f[R] file, and every Barman server has its own copy. .TP .B receive\-wal \f[I]SERVER_NAME\f[R] Start the stream of transaction logs for a server. The process relies on \f[C]pg_receivewal\f[R]/\f[C]pg_receivexlog\f[R] to receive WAL files from the PostgreSQL servers through the streaming protocol. .RS .TP .B \-\-stop stop the receive\-wal process for the server .TP .B \-\-reset reset the status of receive\-wal, restarting the streaming from the current WAL file of the server .TP .B \-\-create\-slot create the physical replication slot configured with the \f[C]slot_name\f[R] configuration parameter .TP .B \-\-drop\-slot drop the physical replication slot configured with the \f[C]slot_name\f[R] configuration parameter .RE .TP .B recover \f[I][OPTIONS]\f[R] \f[I]SERVER_NAME\f[R] \f[I]BACKUP_ID\f[R] \f[I]DESTINATION_DIRECTORY\f[R] Recover a backup in a given directory (local or remote, depending on the \f[C]\-\-remote\-ssh\-command\f[R] option settings). See the Backup ID shortcuts section below for available shortcuts. .RS .TP .B \-\-target\-tli \f[I]TARGET_TLI\f[R] Recover the specified timeline. .TP .B \-\-target\-time \f[I]TARGET_TIME\f[R] Recover to the specified time. .RS .PP You can use any valid unambiguous representation (e.g: \[dq]YYYY\-MM\-DD HH:MM:SS.mmm\[dq]). .RE .TP .B \-\-target\-xid \f[I]TARGET_XID\f[R] Recover to the specified transaction ID. .TP .B \-\-target\-name \f[I]TARGET_NAME\f[R] Recover to the named restore point previously created with the \f[C]pg_create_restore_point(name)\f[R] (for PostgreSQL 9.1 and above users). .TP .B \-\-target\-immediate Recover ends when a consistent state is reached (end of the base backup) .TP .B \-\-exclusive Set target xid to be non inclusive. .TP .B \-\-target\-action \f[I]ACTION\f[R] Trigger the specified action once the recovery target is reached. Possible actions are: \f[C]pause\f[R] (PostgreSQL 9.1 and above), \f[C]shutdown\f[R] (PostgreSQL 9.5 and above) and \f[C]promote\f[R] (ditto). This option requires a target to be defined, with one of the above options. .TP .B \-\-tablespace \f[I]NAME:LOCATION\f[R] Specify tablespace relocation rule. .TP .B \-\-remote\-ssh\-command \f[I]SSH_COMMAND\f[R] This options activates remote recovery, by specifying the secure shell command to be launched on a remote host. This is the equivalent of the \[dq]ssh_command\[dq] server option in the configuration file for remote recovery. Example: \[aq]ssh postgres\[at]db2\[aq]. .TP .B \-\-retry\-times \f[I]RETRY_TIMES\f[R] Number of retries of data copy during base backup after an error. Overrides value of the parameter \f[C]basebackup_retry_times\f[R], if present in the configuration file. .TP .B \-\-no\-retry Same as \f[C]\-\-retry\-times 0\f[R] .TP .B \-\-retry\-sleep Number of seconds of wait after a failed copy, before retrying. Overrides value of the parameter \f[C]basebackup_retry_sleep\f[R], if present in the configuration file. .TP .B \-j , \-\-jobs Number of parallel workers to copy files during recovery. Overrides value of the parameter \f[C]parallel_jobs\f[R], if present in the configuration file. Works only for servers configured through \f[C]rsync\f[R]/SSH. .TP .B \-\-get\-wal, \-\-no\-get\-wal Enable/Disable usage of \f[C]get\-wal\f[R] for WAL fetching during recovery. Default is based on \f[C]recovery_options\f[R] setting. .TP .B \-\-network\-compression, \-\-no\-network\-compression Enable/Disable network compression during remote recovery. Default is based on \f[C]network_compression\f[R] configuration setting. .TP .B \-\-standby\-mode Specifies whether to start the PostgreSQL server as a standby. Default is undefined. .RE .TP .B replication\-status \f[I][OPTIONS]\f[R] \f[I]SERVER_NAME\f[R] 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: .RS .TP .B \-\-minimal machine readable output (default: False) .TP .B \-\-target \f[I]TARGET_TYPE\f[R] Possible values for TARGET_TYPE are: .RS .IP \[bu] 2 \f[I]hot\-standby\f[R]: lists only hot standby servers .IP \[bu] 2 \f[I]wal\-streamer\f[R]: lists only WAL streaming clients, such as pg_receivewal .IP \[bu] 2 \f[I]all\f[R]: any streaming client (default) .RE .RE .TP .B show\-backup \f[I]SERVER_NAME\f[R] \f[I]BACKUP_ID\f[R] 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: .IP .nf \f[C] 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) \f[R] .fi .TP .B show\-server \f[I]SERVER_NAME\f[R] Show information about \f[C]SERVER_NAME\f[R], including: \f[C]conninfo\f[R], \f[C]backup_directory\f[R], \f[C]wals_directory\f[R] and many more. Specify \f[C]all\f[R] as \f[C]SERVER_NAME\f[R] to show information about all the configured servers. .TP .B status \f[I]SERVER_NAME\f[R] Show information about the status of a server, including: number of available backups, \f[C]archive_command\f[R], \f[C]archive_status\f[R] and many more. For example: .IP .nf \f[C] 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 \[aq]archive_command\[aq] setting: rsync \-a %p barman\[at]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) \f[R] .fi .TP .B switch\-wal \f[I]SERVER_NAME\f[R] Execute pg_switch_wal() on the target server (from PostgreSQL 10), or pg_switch_xlog (for PostgreSQL 8.3 to 9.6). .RS .TP .B \-\-force Forces the switch by executing CHECKPOINT before pg_switch_xlog(). \f[I]IMPORTANT:\f[R] executing a CHECKPOINT might increase I/O load on a PostgreSQL server. Use this option with care. .TP .B \-\-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. .TP .B \-\-archive\-timeout \f[I]TIMEOUT\f[R] 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. .RE .TP .B switch\-xlog \f[I]SERVER_NAME\f[R] Alias for switch\-wal (kept for back\-compatibility) .TP .B sync\-backup \f[I]SERVER_NAME\f[R] \f[I]BACKUP_ID\f[R] Command used for the synchronisation of a passive node with its primary. Executes a copy of all the files of a \f[C]BACKUP_ID\f[R] that is present on \f[C]SERVER_NAME\f[R] node. This command is available only for passive nodes, and uses the \f[C]primary_ssh_command\f[R] option to enstablish a secure connection with the primary node. .TP .B sync\-info \f[I]SERVER_NAME\f[R] [\f[I]LAST_WAL\f[R] [\f[I]LAST_POSITION\f[R]]] Collect information regarding the current status of a Barman server, to be used for synchronisation purposes. Returns a JSON output representing \f[C]SERVER_NAME\f[R], that contains: all the successfully finished backup, all the archived WAL files, the configuration, last WAL file been read from the \f[C]xlog.db\f[R] and the position in the file. .RS .TP .B LAST_WAL tells sync\-info to skip any WAL file previous to that (incremental synchronisation) .TP .B LAST_POSITION hint for quickly positioning in the \f[C]xlog.db\f[R] file (incremental synchronisation) .RE .TP .B sync\-wals \f[I]SERVER_NAME\f[R] 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 \f[C]SERVER_NAME\f[R] node. This command is available only for passive nodes, and uses the \f[C]primary_ssh_command\f[R] option to enstablish a secure connection with the primary node. .SH BACKUP ID SHORTCUTS .PP Rather than using the timestamp backup ID, you can use any of the following shortcuts/aliases to identity a backup for a given server: .TP .B first Oldest available backup for that server, in chronological order. .TP .B last Latest available backup for that server, in chronological order. .TP .B latest same ast \f[I]last\f[R]. .TP .B oldest same ast \f[I]first\f[R]. .SH EXIT STATUS .TP .B 0 Success .TP .B Not zero Failure .SH SEE ALSO .PP \f[C]barman\f[R] (5). .SH BUGS .PP Barman has been extensively tested, and is currently being used in several production environments. However, we cannot exclude the presence of bugs. .PP Any bug can be reported via the Sourceforge bug tracker. Along the bug submission, users can provide developers with diagnostics information obtained through the \f[C]barman diagnose\f[R] command. .SH AUTHORS .PP In alphabetical order: .IP \[bu] 2 Gabriele Bartolini (architect) .IP \[bu] 2 Jonathan Battiato (QA/testing) .IP \[bu] 2 Giulio Calacoci (developer) .IP \[bu] 2 Francesco Canovai (QA/testing) .IP \[bu] 2 Leonardo Cecchi (developer) .IP \[bu] 2 Gianni Ciolli (QA/testing) .IP \[bu] 2 Britt Cole (documentation) .IP \[bu] 2 Marco Nenciarini (project leader) .IP \[bu] 2 Rubens Souza (QA/testing) .PP Past contributors: .IP \[bu] 2 Carlo Ascani .IP \[bu] 2 Stefano Bianucci .IP \[bu] 2 Giuseppe Broccolo .SH RESOURCES .IP \[bu] 2 Homepage: .IP \[bu] 2 Documentation: .IP \[bu] 2 Professional support: .SH COPYING .PP Barman is the property of 2ndQuadrant Limited and its code is distributed under GNU General Public License v3. .PP Copyright (C) 2011\-2019 2ndQuadrant Limited \- . .SH AUTHORS 2ndQuadrant Limited .