1BARMAN(1) Version 3.9.0 BARMAN(1)
2
6 barman - Backup and Recovery Manager for PostgreSQL
7
9 barman [OPTIONS] COMMAND
10
12 Barman is an administration tool for disaster recovery of PostgreSQL
13 servers written in Python and maintained by EnterpriseDB. Barman can
14 perform remote backups of multiple servers in business critical envi‐
15 ronments and helps DBAs during the recovery phase.
16
18 -h, --help
19 Show a help message and exit.
20 -v, --version
22 Show program version number and exit.
23 -c CONFIG, --config CONFIG
25 Use the specified configuration file.
26 --color {never,always,auto}, --colour {never,always,auto}
28 Whether to use colors in the output (default: auto)
29 -q, --quiet
31 Do not output anything. Useful for cron scripts.
32 -d, --debug
34 debug output (default: False)
35 --log-level {NOTSET,DEBUG,INFO,WARNING,ERROR,CRITICAL}
37 Override the default log level
38 -f {json,console}, --format {json,console}
40 output format (default: 'console')
41
43 Important: every command has a help option
44 archive-wal SERVER_NAME
46 Get any incoming xlog file (both through standard archive_com‐
47 mand and streaming replication, where applicable) and moves them
48 in the WAL archive for that server. If necessary, apply com‐
49 pression when requested by the user.
50 backup SERVER_NAME
52 Perform a backup of SERVER_NAME using parameters specified in
53 the configuration file. Specify all as SERVER_NAME to perform a
54 backup of all the configured servers. You can also specify
55 SERVER_NAME multiple times to perform a backup of the specified
56 servers -- e.g. barman backup SERVER_1_NAME SERVER_2_NAME.
57 --name a friendly name for this backup which can be used in
59 place of the backup ID in barman commands.
60 --immediate-checkpoint
62 forces the initial checkpoint to be done as quickly as
63 possible. Overrides value of the parameter immedi‐
64 ate_checkpoint, if present in the configuration file.
65 --no-immediate-checkpoint
67 forces to wait for the checkpoint. Overrides value of
68 the parameter immediate_checkpoint, if present in the
69 configuration file.
70 --reuse-backup [INCREMENTAL_TYPE]
72 Overrides reuse_backup option behaviour. Possible values
73 for INCREMENTAL_TYPE are:
74 • off: do not reuse the last available backup;
76 • copy: reuse the last available backup for a server and
78 create a copy of the unchanged files (reduce backup
79 time);
80 • link: reuse the last available backup for a server and
82 create a hard link of the unchanged files (reduce back‐
83 up time and space);
84 link is the default target if --reuse-backup is used and
86 INCREMENTAL_TYPE is not explicit.
87 --retry-times
89 Number of retries of base backup copy, after an error.
90 Used during both backup and recovery operations. Over‐
91 rides value of the parameter basebackup_retry_times, if
92 present in the configuration file.
93 --no-retry
95 Same as --retry-times 0
96 --retry-sleep
98 Number of seconds of wait after a failed copy, before
99 retrying. Used during both backup and recovery opera‐
100 tions. Overrides value of the parameter baseback‐
101 up_retry_sleep, if present in the configuration file.
102 -j, --jobs
104 Number of parallel workers to copy files during backup.
105 Overrides value of the parameter parallel_jobs, if
106 present in the configuration file.
107 --jobs-start-batch-period
109 The time period in seconds over which a single batch of
110 jobs will be started. Overrides the value of paral‐
111 lel_jobs_start_batch_period, if present in the configura‐
112 tion file. Defaults to 1 second.
113 --jobs-start-batch-size
115 Maximum number of parallel workers to start in a single
116 batch. Overrides the value of paral‐
117 lel_jobs_start_batch_size, if present in the configura‐
118 tion file. Defaults to 10 jobs.
119 --bwlimit KBPS
121 maximum transfer rate in kilobytes per second. A value
122 of 0 means no limit. Overrides 'bandwidth_limit' config‐
123 uration option. Default is undefined.
124 --wait, -w
126 wait for all required WAL files by the base backup to be
127 archived
128 --wait-timeout
130 the time, in seconds, spent waiting for the required WAL
131 files to be archived before timing out
132 --manifest
134 forces the creation of a backup manifest file at the end
135 of a backup. Overrides value of the parameter autogener‐
136 ate_manifest, from the configuration file. Works with
137 rsync backup method and strategies only
138 --no-manifest
140 disables the automatic creation of a backup manifest file
141 at the end of a backup. Overrides value of the parameter
142 autogenerate_manifest, from the configuration file.
143 Works with rsync backup method and strategies only
144 check-backup SERVER_NAME BACKUP_ID
146 Make sure that all the required WAL files to check the consis‐
147 tency of a physical backup (that is, from the beginning to the
148 end of the full backup) are correctly archived. This command is
149 automatically invoked by the cron command and at the end of ev‐
150 ery backup operation.
151 check-wal-archive SERVER_NAME
153 Check that the WAL archive destination for SERVER_NAME is safe
154 to use for a new PostgreSQL cluster. With no optional args (the
155 default) this will pass if the WAL archive is empty and fail
156 otherwise.
157 --timeline [TIMELINE]
159 A positive integer specifying the earliest timeline for
160 which associated WALs should cause the check to fail.
161 The check will pass if all WAL content in the archive re‐
162 lates to earlier timelines. If any WAL files are on this
163 timeline or greater then the check will fail.
164 check SERVER_NAME
166 Show diagnostic information about SERVER_NAME, including: Ssh
167 connection check, PostgreSQL version, configuration and backup
168 directories, archiving process, streaming process, replication
169 slots, etc. Specify all as SERVER_NAME to show diagnostic in‐
170 formation about all the configured servers.
171 --nagios
173 Nagios plugin compatible output
174 cron Perform maintenance tasks, such as enforcing retention policies
176 or WAL files management.
177 --keep-descriptors
179 Keep the stdout and the stderr streams of the Barman sub‐
180 processes attached to this one. This is useful for Dock‐
181 er based installations.
182 delete SERVER_NAME BACKUP_ID
184 Delete the specified backup. Backup ID shortcuts section below
185 for available shortcuts.
186 diagnose
188 Collect diagnostic information about the server where barman is
189 installed and all the configured servers, including: global con‐
190 figuration, SSH version, Python version, rsync version, as well
191 as current configuration and status of all servers.
192 generate-manifest SERVER_NAME BACKUP_ID
194 Generates a backup_manifest file for a backup_id.
195 get-wal [OPTIONS] SERVER_NAME WAL_NAME
197 Retrieve a WAL file from the xlog archive of a given server. By
198 default, the requested WAL file, if found, is returned as uncom‐
199 pressed content to STDOUT. The following options allow users to
200 change this behaviour:
201 -o OUTPUT_DIRECTORY
203 destination directory where the get-wal will deposit the
204 requested WAL
205 -P, --partial
207 retrieve also partial WAL files (.partial)
208 -z output will be compressed using gzip
210 -j output will be compressed using bzip2
212 -p SIZE
214 peek from the WAL archive up to SIZE WAL files, starting
215 from the requested one. 'SIZE' must be an integer >= 1.
216 When invoked with this option, get-wal returns a list of
217 zero to 'SIZE' WAL segment names, one per row.
218 -t, --test
220 test both the connection and the configuration of the re‐
221 quested PostgreSQL server in Barman for WAL retrieval.
222 With this option, the 'WAL_NAME' mandatory argument is
223 ignored.
224 keep SERVER_NAME BACKUP_ID
226 Flag the specified backup as an archival backup which should be
227 kept forever, regardless of any retention policies in effect.
228 See the Backup ID shortcuts section below for available short‐
229 cuts.
230 --target RECOVERY_TARGET
232 Specify the recovery target for the archival backup.
233 Possible values for RECOVERY_TARGET are:
234 • full: The backup can always be used to recover to the
236 latest point in time. To achieve this, Barman will re‐
237 tain all WALs needed to ensure consistency of the back‐
238 up and all subsequent WALs.
239 • standalone: The backup can only be used to recover the
241 server to its state at the time the backup was taken.
242 Barman will only retain the WALs needed to ensure con‐
243 sistency of the backup.
244 --status
246 Report the archival status of the backup. This will ei‐
247 ther be the recovery target of full or standalone for
248 archival backups or nokeep for backups which have not
249 been flagged as archival.
250 --release
252 Release the keep flag from this backup. This will remove
253 its archival status and make it available for deletion,
254 either directly or by retention policy.
255 list-backups SERVER_NAME
257 Show available backups for SERVER_NAME. This command is useful
258 to retrieve a backup ID. For example:
259 servername 20111104T102647 - Fri Nov 4 10:26:48 2011 - Size: 17.0 MiB - WAL Size: 100 B
261 In this case, *20111104T102647* is the backup ID.
263 list-files [OPTIONS] SERVER_NAME BACKUP_ID
265 List all the files in a particular backup, identified by the
266 server name and the backup ID. See the Backup ID shortcuts sec‐
267 tion below for available shortcuts.
268 --target TARGET_TYPE
270 Possible values for TARGET_TYPE are:
271 • data: lists just the data files;
273 • standalone: lists the base backup files, including re‐
275 quired WAL files;
276 • wal: lists all the WAL files between the start of the
278 base backup and the end of the log / the start of the
279 following base backup (depending on whether the speci‐
280 fied base backup is the most recent one available);
281 • full: same as data + wal.
283 The default value is standalone.
285 list-servers
287 Show all the configured servers, and their descriptions.
288 put-wal [OPTIONS] SERVER_NAME
290 Receive a WAL file from a remote server and securely store it
291 into the SERVER_NAME incoming directory. The WAL file is re‐
292 trieved from the STDIN, and must be encapsulated in a tar stream
293 together with a MD5SUMS file to validate it. This command is
294 meant to be invoked through SSH from a remote barman-wal-archive
295 utility (part of barman-cli package). Do not use this command
296 directly unless you take full responsibility of the content of
297 files.
298 -t, --test
300 test both the connection and the configuration of the re‐
301 quested PostgreSQL server in Barman to make sure it is
302 ready to receive WAL files.
303 rebuild-xlogdb SERVER_NAME
305 Perform a rebuild of the WAL file metadata for SERVER_NAME (or
306 every server, using the all shortcut) guessing it from the disk
307 content. The metadata of the WAL archive is contained in the
308 xlog.db file, and every Barman server has its own copy.
309 receive-wal SERVER_NAME
311 Start the stream of transaction logs for a server. The process
312 relies on pg_receivewal/pg_receivexlog to receive WAL files from
313 the PostgreSQL servers through the streaming protocol.
314 --stop stop the receive-wal process for the server
316 --reset
318 reset the status of receive-wal, restarting the streaming
319 from the current WAL file of the server
320 --create-slot
322 create the physical replication slot configured with the
323 slot_name configuration parameter
324 --drop-slot
326 drop the physical replication slot configured with the
327 slot_name configuration parameter
328 recover [OPTIONS] SERVER_NAME BACKUP_ID DESTINATION_DIRECTORY
330 Recover a backup in a given directory (local or remote, depend‐
331 ing on the --remote-ssh-command option settings). See the Back‐
332 up ID shortcuts section below for available shortcuts.
333 --target-tli TARGET_TLI
335 Recover the specified timeline. The special values cur‐
336 rent and latest can be used in addition to a numeric
337 timeline ID. The default behaviour for PostgreSQL ver‐
338 sions >= 12 is to recover to the latest timeline in the
339 WAL archive. The default for PostgreSQL versions < 12 is
340 to recover along the timeline which was current when the
341 backup was taken.
342 --target-time TARGET_TIME
344 Recover to the specified time.
345 You can use any valid unambiguous representation (e.g:
347 "YYYY-MM-DD HH:MM:SS.mmm").
348 --target-xid TARGET_XID
350 Recover to the specified transaction ID.
351 --target-lsn TARGET_LSN
353 Recover to the specified LSN (Log Sequence Number). Re‐
354 quires PostgreSQL 10 or above.
355 --target-name TARGET_NAME
357 Recover to the named restore point previously created
358 with the pg_create_restore_point(name).
359 --target-immediate
361 Recover ends when a consistent state is reached (end of
362 the base backup)
363 --exclusive
365 Set target (time, XID or LSN) to be non inclusive.
366 --target-action ACTION
368 Trigger the specified action once the recovery target is
369 reached. Possible actions are: pause, shutdown and pro‐
370 mote. This option requires a target to be defined, with
371 one of the above options.
372 --tablespace NAME:LOCATION
374 Specify tablespace relocation rule.
375 --remote-ssh-command SSH_COMMAND
377 This options activates remote recovery, by specifying the
378 secure shell command to be launched on a remote host.
379 This is the equivalent of the "ssh_command" server option
380 in the configuration file for remote recovery. Example:
381 'ssh postgres@db2'.
382 --retry-times RETRY_TIMES
384 Number of retries of data copy during base backup after
385 an error. Overrides value of the parameter baseback‐
386 up_retry_times, if present in the configuration file.
387 --no-retry
389 Same as --retry-times 0
390 --retry-sleep
392 Number of seconds of wait after a failed copy, before
393 retrying. Overrides value of the parameter baseback‐
394 up_retry_sleep, if present in the configuration file.
395 --bwlimit KBPS
397 maximum transfer rate in kilobytes per second. A value
398 of 0 means no limit. Overrides 'bandwidth_limit' config‐
399 uration option. Default is undefined.
400 -j , --jobs
402 Number of parallel workers to copy files during recovery.
403 Overrides value of the parameter parallel_jobs, if
404 present in the configuration file. Works only for
405 servers configured through rsync/SSH.
406 --jobs-start-batch-period
408 The time period in seconds over which a single batch of
409 jobs will be started. Overrides the value of paral‐
410 lel_jobs_start_batch_period, if present in the configura‐
411 tion file. Defaults to 1 second.
412 --jobs-start-batch-size
414 Maximum number of parallel workers to start in a single
415 batch. Overrides the value of paral‐
416 lel_jobs_start_batch_size, if present in the configura‐
417 tion file. Defaults to 10 jobs.
418 --get-wal, --no-get-wal
420 Enable/Disable usage of get-wal for WAL fetching during
421 recovery. Default is based on recovery_options setting.
422 --network-compression, --no-network-compression
424 Enable/Disable network compression during remote recov‐
425 ery. Default is based on network_compression configura‐
426 tion setting.
427 --standby-mode
429 Specifies whether to start the PostgreSQL server as a
430 standby. Default is undefined.
431 --recovery-staging-path STAGING_PATH
433 A path to a location on the recovery host (either the
434 barman server or a remote host if --remote-ssh-command is
435 also used) where files for a compressed backup will be
436 staged before being uncompressed to the destination di‐
437 rectory. Backups will be staged in their own directory
438 within the staging path according to the following naming
439 convention: "barman-staging-SERVER_NAME-BACKUP_ID". The
440 staging directory within the staging path will be removed
441 at the end of the recovery process. This option is re‐
442 quired when recovering from compressed backups and has no
443 effect otherwise.
444 --recovery-conf-filename RECOVERY_CONF_FILENAME
446 The name of the file where Barman should write the Post‐
447 greSQL recovery options when recovering backups for Post‐
448 greSQL versions 12 and later. This defaults to post‐
449 gresql.auto.conf however if --recovery-conf-filename is
450 used then recovery options will be written to RECOV‐
451 ERY_CONF_FILENAME instead. The default value is correct
452 for a typical PostgreSQL installation however if Post‐
453 greSQL is being managed by tooling which modifies the
454 configuration mechanism (for example postgresql.auto.conf
455 could be symlinked to /dev/null) then this option can be
456 used to write the recovery options to an alternative lo‐
457 cation.
458 --snapshot-recovery-instance INSTANCE_NAME
460 Name of the instance where the disks recovered from the
461 snapshots are attached. This option is required when re‐
462 covering backups made with backup_method = snapshot.
463 --gcp-zone ZONE_NAME
465 Name of the GCP zone where the instance and disks for
466 snapshot recovery are located. This option can be used
467 to override the value of gcp_zone in the Barman config.
468 --azure-resource-group RESOURCE_GROUP_NAME
470 Name of the Azure resource group containing the instance
471 and disks for snapshot recovery. This option can be used
472 to override the value of azure_resource_group in the Bar‐
473 man config.
474 --aws-region REGION_NAME
476 Name of the AWS region where the instance and disks for
477 snapshot recovery are located. This option can be used
478 to override the value of aws_region in the Barman config.
479 replication-status [OPTIONS] SERVER_NAME
481 Shows live information and status of any streaming client at‐
482 tached to the given server (or servers). Default behaviour can
483 be changed through the following options:
484 --minimal
486 machine readable output (default: False)
487 --target TARGET_TYPE
489 Possible values for TARGET_TYPE are:
490 • hot-standby: lists only hot standby servers
492 • wal-streamer: lists only WAL streaming clients, such as
494 pg_receivewal
495 • all: any streaming client (default)
497 show-backup SERVER_NAME BACKUP_ID
499 Show detailed information about a particular backup, identified
500 by the server name and the backup ID. See the Backup ID short‐
501 cuts section below for available shortcuts. For example:
502 Backup 20150828T130001:
504 Server Name : quagmire
505 Status : DONE
506 PostgreSQL Version : 90402
507 PGDATA directory : /srv/postgresql/9.4/main/data
508 Base backup information:
510 Disk usage : 12.4 TiB (12.4 TiB with WALs)
511 Incremental size : 4.9 TiB (-60.02%)
512 Timeline : 1
513 Begin WAL : 0000000100000CFD000000AD
514 End WAL : 0000000100000D0D00000008
515 WAL number : 3932
516 WAL compression ratio: 79.51%
517 Begin time : 2015-08-28 13:00:01.633925+00:00
518 End time : 2015-08-29 10:27:06.522846+00:00
519 Begin Offset : 1575048
520 End Offset : 13853016
521 Begin XLOG : CFD/AD180888
522 End XLOG : D0D/8D36158
523 WAL information:
525 No of files : 35039
526 Disk usage : 121.5 GiB
527 WAL rate : 275.50/hour
528 Compression ratio : 77.81%
529 Last available : 0000000100000D95000000E7
530 Catalog information:
532 Retention Policy : not enforced
533 Previous Backup : 20150821T130001
534 Next Backup : - (this is the latest base backup)
535 show-servers SERVER_NAME
537 Show information about SERVER_NAME, including: conninfo, back‐
538 up_directory, wals_directory and many more. Specify all as
539 SERVER_NAME to show information about all the configured
540 servers.
541 status SERVER_NAME
543 Show information about the status of a server, including: number
544 of available backups, archive_command, archive_status and many
545 more. For example:
546 Server quagmire:
548 Description: The Giggity database
549 Passive node: False
550 PostgreSQL version: 9.3.9
551 PostgreSQL Data directory: /srv/postgresql/9.3/data
552 PostgreSQL 'archive_command' setting: rsync -a %p barman@backup:/var/lib/barman/quagmire/incoming
553 Last archived WAL: 0000000100003103000000AD
554 Current WAL segment: 0000000100003103000000AE
555 Retention policies: enforced (mode: auto, retention: REDUNDANCY 2, WAL retention: MAIN)
556 No. of available backups: 2
557 First available backup: 20150908T003001
558 Last available backup: 20150909T003001
559 Minimum redundancy requirements: satisfied (2/1)
560 switch-wal SERVER_NAME
562 Execute pg_switch_wal() on the target server (from PostgreSQL
563 10), or pg_switch_xlog (for PostgreSQL 8.3 to 9.6).
564 --force
566 Forces the switch by executing CHECKPOINT before
567 pg_switch_xlog(). IMPORTANT: executing a CHECKPOINT
568 might increase I/O load on a PostgreSQL server. Use this
569 option with care.
570 --archive
572 Wait for one xlog file to be archived. If after a de‐
573 fined amount of time (default: 30 seconds) no xlog file
574 is archived, Barman will terminate with failure exit
575 code. Available also on standby servers.
576 --archive-timeout TIMEOUT
578 Specifies the amount of time in seconds (default: 30 sec‐
579 onds) the archiver will wait for a new xlog file to be
580 archived before timing out. Available also on standby
581 servers.
582 switch-xlog SERVER_NAME
584 Alias for switch-wal (kept for back-compatibility)
585 sync-backup SERVER_NAME BACKUP_ID
587 Command used for the synchronisation of a passive node with its
588 primary. Executes a copy of all the files of a BACKUP_ID that
589 is present on SERVER_NAME node. This command is available only
590 for passive nodes, and uses the primary_ssh_command option to
591 establish a secure connection with the primary node.
592 sync-info SERVER_NAME [LAST_WAL [LAST_POSITION]]
594 Collect information regarding the current status of a Barman
595 server, to be used for synchronisation purposes. Returns a JSON
596 output representing SERVER_NAME, that contains: all the success‐
597 fully finished backup, all the archived WAL files, the configu‐
598 ration, last WAL file been read from the xlog.db and the posi‐
599 tion in the file.
600 LAST_WAL
602 tells sync-info to skip any WAL file previous to that
603 (incremental synchronisation)
604 LAST_POSITION
606 hint for quickly positioning in the xlog.db file (incre‐
607 mental synchronisation)
608 sync-wals SERVER_NAME
610 Command used for the synchronisation of a passive node with its
611 primary. Executes a copy of all the archived WAL files that are
612 present on SERVER_NAME node. This command is available only for
613 passive nodes, and uses the primary_ssh_command option to estab‐
614 lish a secure connection with the primary node.
615 verify-backup SERVER_NAME BACKUP_ID
617 Executes pg_verifybackup against a backup manifest file (avail‐
618 able since Postgres 13). For rsync backups, it can be used with
619 generate-manifest command. Requires pg_verifybackup installed
620 on the backup server
621 verify SERVER_NAME BACKUP_ID
623 Alias for verify-backup
624
626 Rather than using the timestamp backup ID, you can use any of the fol‐
627 lowing shortcuts/aliases to identity a backup for a given server:
628 first Oldest available backup for that server, in chronological order.
630 last Latest available backup for that server, in chronological order.
632 latest same ast last.
634 oldest same ast first.
636 last-failed
638 Latest failed backup, in chronological order.
639
641 0 Success
642 Not zero
644 Failure
645
647 barman (5).
648
650 Barman has been extensively tested, and is currently being used in sev‐
651 eral production environments. However, we cannot exclude the presence
652 of bugs.
653 Any bug can be reported via the GitHub bug tracker. Along with the bug
655 submission, users can provide developers with diagnostics information
656 obtained through the barman diagnose command.
657
659 Barman maintainers (in alphabetical order):
660 • Abhijit Menon-Sen
662 • Didier Michel
664 • Michael Wallace
666 Past contributors (in alphabetical order):
668 • Anna Bellandi (QA/testing)
670 • Britt Cole (documentation reviewer)
672 • Carlo Ascani (developer)
674 • Francesco Canovai (QA/testing)
676 • Gabriele Bartolini (architect)
678 • Gianni Ciolli (QA/testing)
680 • Giulio Calacoci (developer)
682 • Giuseppe Broccolo (developer)
684 • Jane Threefoot (developer)
686 • Jonathan Battiato (QA/testing)
688 • Leonardo Cecchi (developer)
690 • Marco Nenciarini (project leader)
692 • Niccolò Fei (QA/testing)
694 • Rubens Souza (QA/testing)
696 • Stefano Bianucci (developer)
698
700 • Homepage: <https://www.pgbarman.org/>
701 • Documentation: <https://docs.pgbarman.org/>
703 • Professional support: <https://www.enterprisedb.com/>
705
707 Barman is the property of EnterpriseDB UK Limited and its code is dis‐
708 tributed under GNU General Public License v3.
709 © Copyright EnterpriseDB UK Limited 2011-2023
711
713 EnterpriseDB <https://www.enterprisedb.com>.
714Barman User manuals October 3, 2023 BARMAN(1)