Provided by: barman_3.6.0-1_all bug

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.

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

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

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