1BARMAN(1) Version 3.0.1 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.
55 --immediate-checkpoint
57 forces the initial checkpoint to be done as quickly as
58 possible. Overrides value of the parameter immedi‐
59 ate_checkpoint, if present in the configuration file.
60 --no-immediate-checkpoint
62 forces to wait for the checkpoint. Overrides value of
63 the parameter immediate_checkpoint, if present in the
64 configuration file.
65 --reuse-backup [INCREMENTAL_TYPE]
67 Overrides reuse_backup option behaviour. Possible values
68 for INCREMENTAL_TYPE are:
69 • off: do not reuse the last available backup;
71 • copy: reuse the last available backup for a server and
73 create a copy of the unchanged files (reduce backup
74 time);
75 • link: reuse the last available backup for a server and
77 create a hard link of the unchanged files (reduce back‐
78 up time and space);
79 link is the default target if --reuse-backup is used and
81 INCREMENTAL_TYPE is not explicit.
82 --retry-times
84 Number of retries of base backup copy, after an error.
85 Used during both backup and recovery operations. Over‐
86 rides value of the parameter basebackup_retry_times, if
87 present in the configuration file.
88 --no-retry
90 Same as --retry-times 0
91 --retry-sleep
93 Number of seconds of wait after a failed copy, before
94 retrying. Used during both backup and recovery opera‐
95 tions. Overrides value of the parameter baseback‐
96 up_retry_sleep, if present in the configuration file.
97 -j, --jobs
99 Number of parallel workers to copy files during backup.
100 Overrides value of the parameter parallel_jobs, if
101 present in the configuration file.
102 --bwlimit KBPS
104 maximum transfer rate in kilobytes per second. A value
105 of 0 means no limit. Overrides 'bandwidth_limit' config‐
106 uration option. Default is undefined.
107 --wait, -w
109 wait for all required WAL files by the base backup to be
110 archived
111 --wait-timeout
113 the time, in seconds, spent waiting for the required WAL
114 files to be archived before timing out
115 check-backup SERVER_NAME BACKUP_ID
117 Make sure that all the required WAL files to check the consis‐
118 tency of a physical backup (that is, from the beginning to the
119 end of the full backup) are correctly archived. This command is
120 automatically invoked by the cron command and at the end of ev‐
121 ery backup operation.
122 check-wal-archive SERVER_NAME
124 Check that the WAL archive destination for SERVER_NAME is safe
125 to use for a new PostgreSQL cluster. With no optional args (the
126 default) this will pass if the WAL archive is empty and fail
127 otherwise.
128 --timeline [TIMELINE]
130 A positive integer specifying the earliest timeline for
131 which associated WALs should cause the check to fail.
132 The check will pass if all WAL content in the archive re‐
133 lates to earlier timelines. If any WAL files are on this
134 timeline or greater then the check will fail.
135 check SERVER_NAME
137 Show diagnostic information about SERVER_NAME, including: Ssh
138 connection check, PostgreSQL version, configuration and backup
139 directories, archiving process, streaming process, replication
140 slots, etc. Specify all as SERVER_NAME to show diagnostic in‐
141 formation about all the configured servers.
142 --nagios
144 Nagios plugin compatible output
145 cron Perform maintenance tasks, such as enforcing retention policies
147 or WAL files management.
148 --keep-descriptors
150 Keep the stdout and the stderr streams of the Barman sub‐
151 processes attached to this one. This is useful for Dock‐
152 er based installations.
153 delete SERVER_NAME BACKUP_ID
155 Delete the specified backup. Backup ID shortcuts section below
156 for available shortcuts.
157 diagnose
159 Collect diagnostic information about the server where barman is
160 installed and all the configured servers, including: global con‐
161 figuration, SSH version, Python version, rsync version, as well
162 as current configuration and status of all servers.
163 get-wal [OPTIONS] SERVER_NAME WAL_NAME
165 Retrieve a WAL file from the xlog archive of a given server. By
166 default, the requested WAL file, if found, is returned as uncom‐
167 pressed content to STDOUT. The following options allow users to
168 change this behaviour:
169 -o OUTPUT_DIRECTORY
171 destination directory where the get-wal will deposit the
172 requested WAL
173 -P, --partial
175 retrieve also partial WAL files (.partial)
176 -z output will be compressed using gzip
178 -j output will be compressed using bzip2
180 -p SIZE
182 peek from the WAL archive up to SIZE WAL files, starting
183 from the requested one. 'SIZE' must be an integer >= 1.
184 When invoked with this option, get-wal returns a list of
185 zero to 'SIZE' WAL segment names, one per row.
186 -t, --test
188 test both the connection and the configuration of the re‐
189 quested PostgreSQL server in Barman for WAL retrieval.
190 With this option, the 'WAL_NAME' mandatory argument is
191 ignored.
192 keep SERVER_NAME BACKUP_ID
194 Flag the specified backup as an archival backup which should be
195 kept forever, regardless of any retention policies in effect.
196 See the Backup ID shortcuts section below for available short‐
197 cuts.
198 --target RECOVERY_TARGET
200 Specify the recovery target for the archival backup.
201 Possible values for RECOVERY_TARGET are:
202 • full: The backup can always be used to recover to the
204 latest point in time. To achieve this, Barman will re‐
205 tain all WALs needed to ensure consistency of the back‐
206 up and all subsequent WALs.
207 • standalone: The backup can only be used to recover the
209 server to its state at the time the backup was taken.
210 Barman will only retain the WALs needed to ensure con‐
211 sistency of the backup.
212 --status
214 Report the archival status of the backup. This will ei‐
215 ther be the recovery target of full or standalone for
216 archival backups or nokeep for backups which have not
217 been flagged as archival.
218 --release
220 Release the keep flag from this backup. This will remove
221 its archival status and make it available for deletion,
222 either directly or by retention policy.
223 list-backups SERVER_NAME
225 Show available backups for SERVER_NAME. This command is useful
226 to retrieve a backup ID. For example:
227 servername 20111104T102647 - Fri Nov 4 10:26:48 2011 - Size: 17.0 MiB - WAL Size: 100 B
229 In this case, *20111104T102647* is the backup ID.
231 list-files [OPTIONS] SERVER_NAME BACKUP_ID
233 List all the files in a particular backup, identified by the
234 server name and the backup ID. See the Backup ID shortcuts sec‐
235 tion below for available shortcuts.
236 --target TARGET_TYPE
238 Possible values for TARGET_TYPE are:
239 • data: lists just the data files;
241 • standalone: lists the base backup files, including re‐
243 quired WAL files;
244 • wal: lists all the WAL files between the start of the
246 base backup and the end of the log / the start of the
247 following base backup (depending on whether the speci‐
248 fied base backup is the most recent one available);
249 • full: same as data + wal.
251 The default value is standalone.
253 list-servers
255 Show all the configured servers, and their descriptions.
256 put-wal [OPTIONS] SERVER_NAME
258 Receive a WAL file from a remote server and securely store it
259 into the SERVER_NAME incoming directory. The WAL file is re‐
260 trieved from the STDIN, and must be encapsulated in a tar stream
261 together with a MD5SUMS file to validate it. This command is
262 meant to be invoked through SSH from a remote barman-wal-archive
263 utility (part of barman-cli package). Do not use this command
264 directly unless you take full responsibility of the content of
265 files.
266 -t, --test
268 test both the connection and the configuration of the re‐
269 quested PostgreSQL server in Barman to make sure it is
270 ready to receive WAL files.
271 rebuild-xlogdb SERVER_NAME
273 Perform a rebuild of the WAL file metadata for SERVER_NAME (or
274 every server, using the all shortcut) guessing it from the disk
275 content. The metadata of the WAL archive is contained in the
276 xlog.db file, and every Barman server has its own copy.
277 receive-wal SERVER_NAME
279 Start the stream of transaction logs for a server. The process
280 relies on pg_receivewal/pg_receivexlog to receive WAL files from
281 the PostgreSQL servers through the streaming protocol.
282 --stop stop the receive-wal process for the server
284 --reset
286 reset the status of receive-wal, restarting the streaming
287 from the current WAL file of the server
288 --create-slot
290 create the physical replication slot configured with the
291 slot_name configuration parameter
292 --drop-slot
294 drop the physical replication slot configured with the
295 slot_name configuration parameter
296 recover [OPTIONS] SERVER_NAME BACKUP_ID DESTINATION_DIRECTORY
298 Recover a backup in a given directory (local or remote, depend‐
299 ing on the --remote-ssh-command option settings). See the Back‐
300 up ID shortcuts section below for available shortcuts.
301 --target-tli TARGET_TLI
303 Recover the specified timeline. The special values cur‐
304 rent and latest can be used in addition to a numeric
305 timeline ID. The default behaviour for PostgreSQL ver‐
306 sions >= 12 is to recover to the latest timeline in the
307 WAL archive. The default for PostgreSQL versions < 12 is
308 to recover along the timeline which was current when the
309 backup was taken.
310 --target-time TARGET_TIME
312 Recover to the specified time.
313 You can use any valid unambiguous representation (e.g:
315 "YYYY-MM-DD HH:MM:SS.mmm").
316 --target-xid TARGET_XID
318 Recover to the specified transaction ID.
319 --target-lsn TARGET_LSN
321 Recover to the specified LSN (Log Sequence Number). Re‐
322 quires PostgreSQL 10 or above.
323 --target-name TARGET_NAME
325 Recover to the named restore point previously created
326 with the pg_create_restore_point(name) (for PostgreSQL
327 9.1 and above users).
328 --target-immediate
330 Recover ends when a consistent state is reached (end of
331 the base backup)
332 --exclusive
334 Set target (time, XID or LSN) to be non inclusive.
335 --target-action ACTION
337 Trigger the specified action once the recovery target is
338 reached. Possible actions are: pause (PostgreSQL 9.1 and
339 above), shutdown (PostgreSQL 9.5 and above) and promote
340 (ditto). This option requires a target to be defined,
341 with one of the above options.
342 --tablespace NAME:LOCATION
344 Specify tablespace relocation rule.
345 --remote-ssh-command SSH_COMMAND
347 This options activates remote recovery, by specifying the
348 secure shell command to be launched on a remote host.
349 This is the equivalent of the "ssh_command" server option
350 in the configuration file for remote recovery. Example:
351 'ssh postgres@db2'.
352 --retry-times RETRY_TIMES
354 Number of retries of data copy during base backup after
355 an error. Overrides value of the parameter baseback‐
356 up_retry_times, if present in the configuration file.
357 --no-retry
359 Same as --retry-times 0
360 --retry-sleep
362 Number of seconds of wait after a failed copy, before
363 retrying. Overrides value of the parameter baseback‐
364 up_retry_sleep, if present in the configuration file.
365 --bwlimit KBPS
367 maximum transfer rate in kilobytes per second. A value
368 of 0 means no limit. Overrides 'bandwidth_limit' config‐
369 uration option. Default is undefined.
370 -j , --jobs
372 Number of parallel workers to copy files during recovery.
373 Overrides value of the parameter parallel_jobs, if
374 present in the configuration file. Works only for
375 servers configured through rsync/SSH.
376 --get-wal, --no-get-wal
378 Enable/Disable usage of get-wal for WAL fetching during
379 recovery. Default is based on recovery_options setting.
380 --network-compression, --no-network-compression
382 Enable/Disable network compression during remote recov‐
383 ery. Default is based on network_compression configura‐
384 tion setting.
385 --standby-mode
387 Specifies whether to start the PostgreSQL server as a
388 standby. Default is undefined.
389 --recovery-staging-path STAGING_PATH
391 A path to a location on the recovery host (either the
392 barman server or a remote host if --remote-ssh-command is
393 also used) where files for a compressed backup will be
394 staged before being uncompressed to the destination di‐
395 rectory. Backups will be staged in their own directory
396 within the staging path according to the following naming
397 convention: "barman-staging-SERVER_NAME-BACKUP_ID". The
398 staging directory within the staging path will be removed
399 at the end of the recovery process. This option is re‐
400 quired when recovering from compressed backups and has no
401 effect otherwise.
402 replication-status [OPTIONS] SERVER_NAME
404 Shows live information and status of any streaming client at‐
405 tached to the given server (or servers). Default behaviour can
406 be changed through the following options:
407 --minimal
409 machine readable output (default: False)
410 --target TARGET_TYPE
412 Possible values for TARGET_TYPE are:
413 • hot-standby: lists only hot standby servers
415 • wal-streamer: lists only WAL streaming clients, such as
417 pg_receivewal
418 • all: any streaming client (default)
420 show-backup SERVER_NAME BACKUP_ID
422 Show detailed information about a particular backup, identified
423 by the server name and the backup ID. See the Backup ID short‐
424 cuts section below for available shortcuts. For example:
425 Backup 20150828T130001:
427 Server Name : quagmire
428 Status : DONE
429 PostgreSQL Version : 90402
430 PGDATA directory : /srv/postgresql/9.4/main/data
431 Base backup information:
433 Disk usage : 12.4 TiB (12.4 TiB with WALs)
434 Incremental size : 4.9 TiB (-60.02%)
435 Timeline : 1
436 Begin WAL : 0000000100000CFD000000AD
437 End WAL : 0000000100000D0D00000008
438 WAL number : 3932
439 WAL compression ratio: 79.51%
440 Begin time : 2015-08-28 13:00:01.633925+00:00
441 End time : 2015-08-29 10:27:06.522846+00:00
442 Begin Offset : 1575048
443 End Offset : 13853016
444 Begin XLOG : CFD/AD180888
445 End XLOG : D0D/8D36158
446 WAL information:
448 No of files : 35039
449 Disk usage : 121.5 GiB
450 WAL rate : 275.50/hour
451 Compression ratio : 77.81%
452 Last available : 0000000100000D95000000E7
453 Catalog information:
455 Retention Policy : not enforced
456 Previous Backup : 20150821T130001
457 Next Backup : - (this is the latest base backup)
458 show-servers SERVER_NAME
460 Show information about SERVER_NAME, including: conninfo, back‐
461 up_directory, wals_directory and many more. Specify all as
462 SERVER_NAME to show information about all the configured
463 servers.
464 status SERVER_NAME
466 Show information about the status of a server, including: number
467 of available backups, archive_command, archive_status and many
468 more. For example:
469 Server quagmire:
471 Description: The Giggity database
472 Passive node: False
473 PostgreSQL version: 9.3.9
474 pgespresso extension: Not available
475 PostgreSQL Data directory: /srv/postgresql/9.3/data
476 PostgreSQL 'archive_command' setting: rsync -a %p barman@backup:/var/lib/barman/quagmire/incoming
477 Last archived WAL: 0000000100003103000000AD
478 Current WAL segment: 0000000100003103000000AE
479 Retention policies: enforced (mode: auto, retention: REDUNDANCY 2, WAL retention: MAIN)
480 No. of available backups: 2
481 First available backup: 20150908T003001
482 Last available backup: 20150909T003001
483 Minimum redundancy requirements: satisfied (2/1)
484 switch-wal SERVER_NAME
486 Execute pg_switch_wal() on the target server (from PostgreSQL
487 10), or pg_switch_xlog (for PostgreSQL 8.3 to 9.6).
488 --force
490 Forces the switch by executing CHECKPOINT before
491 pg_switch_xlog(). IMPORTANT: executing a CHECKPOINT
492 might increase I/O load on a PostgreSQL server. Use this
493 option with care.
494 --archive
496 Wait for one xlog file to be archived. If after a de‐
497 fined amount of time (default: 30 seconds) no xlog file
498 is archived, Barman will terminate with failure exit
499 code. Available also on standby servers.
500 --archive-timeout TIMEOUT
502 Specifies the amount of time in seconds (default: 30 sec‐
503 onds) the archiver will wait for a new xlog file to be
504 archived before timing out. Available also on standby
505 servers.
506 switch-xlog SERVER_NAME
508 Alias for switch-wal (kept for back-compatibility)
509 sync-backup SERVER_NAME BACKUP_ID
511 Command used for the synchronisation of a passive node with its
512 primary. Executes a copy of all the files of a BACKUP_ID that
513 is present on SERVER_NAME node. This command is available only
514 for passive nodes, and uses the primary_ssh_command option to
515 establish a secure connection with the primary node.
516 sync-info SERVER_NAME [LAST_WAL [LAST_POSITION]]
518 Collect information regarding the current status of a Barman
519 server, to be used for synchronisation purposes. Returns a JSON
520 output representing SERVER_NAME, that contains: all the success‐
521 fully finished backup, all the archived WAL files, the configu‐
522 ration, last WAL file been read from the xlog.db and the posi‐
523 tion in the file.
524 LAST_WAL
526 tells sync-info to skip any WAL file previous to that
527 (incremental synchronisation)
528 LAST_POSITION
530 hint for quickly positioning in the xlog.db file (incre‐
531 mental synchronisation)
532 sync-wals SERVER_NAME
534 Command used for the synchronisation of a passive node with its
535 primary. Executes a copy of all the archived WAL files that are
536 present on SERVER_NAME node. This command is available only for
537 passive nodes, and uses the primary_ssh_command option to estab‐
538 lish a secure connection with the primary node.
539
541 Rather than using the timestamp backup ID, you can use any of the fol‐
542 lowing shortcuts/aliases to identity a backup for a given server:
543 first Oldest available backup for that server, in chronological order.
545 last Latest available backup for that server, in chronological order.
547 latest same ast last.
549 oldest same ast first.
551 last-failed
553 Latest failed backup, in chronological order.
554
556 0 Success
557 Not zero
559 Failure
560
562 barman (5).
563
565 Barman has been extensively tested, and is currently being used in sev‐
566 eral production environments. However, we cannot exclude the presence
567 of bugs.
568 Any bug can be reported via the Github bug tracker. Along with the bug
570 submission, users can provide developers with diagnostics information
571 obtained through the barman diagnose command.
572
574 Barman maintainers (in alphabetical order):
575 • Abhijit Menon-Sen
577 • Jane Threefoot
579 • Michael Wallace
581 Past contributors (in alphabetical order):
583 • Anna Bellandi (QA/testing)
585 • Britt Cole (documentation reviewer)
587 • Carlo Ascani (developer)
589 • Francesco Canovai (QA/testing)
591 • Gabriele Bartolini (architect)
593 • Gianni Ciolli (QA/testing)
595 • Giulio Calacoci (developer)
597 • Giuseppe Broccolo (developer)
599 • Jonathan Battiato (QA/testing)
601 • Leonardo Cecchi (developer)
603 • Marco Nenciarini (project leader)
605 • Niccolò Fei (QA/testing)
607 • Rubens Souza (QA/testing)
609 • Stefano Bianucci (developer)
611
613 • Homepage: <https://www.pgbarman.org/>
614 • Documentation: <https://docs.pgbarman.org/>
616 • Professional support: <https://www.enterprisedb.com/>
618
620 Barman is the property of EnterpriseDB UK Limited and its code is dis‐
621 tributed under GNU General Public License v3.
622 © Copyright EnterpriseDB UK Limited 2011-2022
624
626 EnterpriseDB <https://www.enterprisedb.com>.
627Barman User manuals June 27, 2022 BARMAN(1)