1BARMAN(1) Version 2.12 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 2ndQuadrant. 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 SERVER_NAME
124 Show diagnostic information about SERVER_NAME, including: Ssh
125 connection check, PostgreSQL version, configuration and backup
126 directories, archiving process, streaming process, replication
127 slots, etc. Specify all as SERVER_NAME to show diagnostic in‐
128 formation about all the configured servers.
129 --nagios
131 Nagios plugin compatible output
132 cron Perform maintenance tasks, such as enforcing retention policies
134 or WAL files management.
135 --keep-descriptors
137 Keep the stdout and the stderr streams of the Barman sub‐
138 processes attached to this one. This is useful for Dock‐
139 er based installations.
140 delete SERVER_NAME BACKUP_ID
142 Delete the specified backup. Backup ID shortcuts section below
143 for available shortcuts.
144 diagnose
146 Collect diagnostic information about the server where barman is
147 installed and all the configured servers, including: global con‐
148 figuration, SSH version, Python version, rsync version, as well
149 as current configuration and status of all servers.
150 get-wal [OPTIONS] SERVER_NAME WAL_NAME
152 Retrieve a WAL file from the xlog archive of a given server. By
153 default, the requested WAL file, if found, is returned as uncom‐
154 pressed content to STDOUT. The following options allow users to
155 change this behaviour:
156 -o OUTPUT_DIRECTORY
158 destination directory where the get-wal will deposit the
159 requested WAL
160 -P, --partial
162 retrieve also partial WAL files (.partial)
163 -z output will be compressed using gzip
165 -j output will be compressed using bzip2
167 -p SIZE
169 peek from the WAL archive up to SIZE WAL files, starting
170 from the requested one. 'SIZE' must be an integer >= 1.
171 When invoked with this option, get-wal returns a list of
172 zero to 'SIZE' WAL segment names, one per row.
173 -t, --test
175 test both the connection and the configuration of the re‐
176 quested PostgreSQL server in Barman for WAL retrieval.
177 With this option, the 'WAL_NAME' mandatory argument is
178 ignored.
179 list-backup SERVER_NAME
181 Show available backups for SERVER_NAME. This command is useful
182 to retrieve a backup ID. For example:
183 servername 20111104T102647 - Fri Nov 4 10:26:48 2011 - Size: 17.0 MiB - WAL Size: 100 B
185 In this case, *20111104T102647* is the backup ID.
187 list-files [OPTIONS] SERVER_NAME BACKUP_ID
189 List all the files in a particular backup, identified by the
190 server name and the backup ID. See the Backup ID shortcuts sec‐
191 tion below for available shortcuts.
192 --target TARGET_TYPE
194 Possible values for TARGET_TYPE are:
195 · data: lists just the data files;
197 · standalone: lists the base backup files, including re‐
199 quired WAL files;
200 · wal: lists all the WAL files between the start of the
202 base backup and the end of the log / the start of the
203 following base backup (depending on whether the speci‐
204 fied base backup is the most recent one available);
205 · full: same as data + wal.
207 The default value is standalone.
209 list-server
211 Show all the configured servers, and their descriptions.
212 put-wal [OPTIONS] SERVER_NAME
214 Receive a WAL file from a remote server and securely store it
215 into the SERVER_NAME incoming directory. The WAL file is re‐
216 trieved from the STDIN, and must be encapsulated in a tar stream
217 together with a MD5SUMS file to validate it. This command is
218 meant to be invoked through SSH from a remote barman-wal-archive
219 utility (part of barman-cli package). Do not use this command
220 directly unless you take full responsibility of the content of
221 files.
222 -t, --test
224 test both the connection and the configuration of the re‐
225 quested PostgreSQL server in Barman to make sure it is
226 ready to receive WAL files.
227 rebuild-xlogdb SERVER_NAME
229 Perform a rebuild of the WAL file metadata for SERVER_NAME (or
230 every server, using the all shortcut) guessing it from the disk
231 content. The metadata of the WAL archive is contained in the
232 xlog.db file, and every Barman server has its own copy.
233 receive-wal SERVER_NAME
235 Start the stream of transaction logs for a server. The process
236 relies on pg_receivewal/pg_receivexlog to receive WAL files from
237 the PostgreSQL servers through the streaming protocol.
238 --stop stop the receive-wal process for the server
240 --reset
242 reset the status of receive-wal, restarting the streaming
243 from the current WAL file of the server
244 --create-slot
246 create the physical replication slot configured with the
247 slot_name configuration parameter
248 --drop-slot
250 drop the physical replication slot configured with the
251 slot_name configuration parameter
252 recover [OPTIONS] SERVER_NAME BACKUP_ID DESTINATION_DIRECTORY
254 Recover a backup in a given directory (local or remote, depend‐
255 ing on the --remote-ssh-command option settings). See the Back‐
256 up ID shortcuts section below for available shortcuts.
257 --target-tli TARGET_TLI
259 Recover the specified timeline.
260 --target-time TARGET_TIME
262 Recover to the specified time.
263 You can use any valid unambiguous representation (e.g:
265 "YYYY-MM-DD HH:MM:SS.mmm").
266 --target-xid TARGET_XID
268 Recover to the specified transaction ID.
269 --target-lsn TARGET_LSN
271 Recover to the specified LSN (Log Sequence Number). Re‐
272 quires PostgreSQL 10 or above.
273 --target-name TARGET_NAME
275 Recover to the named restore point previously created
276 with the pg_create_restore_point(name) (for PostgreSQL
277 9.1 and above users).
278 --target-immediate
280 Recover ends when a consistent state is reached (end of
281 the base backup)
282 --exclusive
284 Set target (time, XID or LSN) to be non inclusive.
285 --target-action ACTION
287 Trigger the specified action once the recovery target is
288 reached. Possible actions are: pause (PostgreSQL 9.1 and
289 above), shutdown (PostgreSQL 9.5 and above) and promote
290 (ditto). This option requires a target to be defined,
291 with one of the above options.
292 --tablespace NAME:LOCATION
294 Specify tablespace relocation rule.
295 --remote-ssh-command SSH_COMMAND
297 This options activates remote recovery, by specifying the
298 secure shell command to be launched on a remote host.
299 This is the equivalent of the "ssh_command" server option
300 in the configuration file for remote recovery. Example:
301 'ssh postgres@db2'.
302 --retry-times RETRY_TIMES
304 Number of retries of data copy during base backup after
305 an error. Overrides value of the parameter baseback‐
306 up_retry_times, if present in the configuration file.
307 --no-retry
309 Same as --retry-times 0
310 --retry-sleep
312 Number of seconds of wait after a failed copy, before
313 retrying. Overrides value of the parameter baseback‐
314 up_retry_sleep, if present in the configuration file.
315 --bwlimit KBPS
317 maximum transfer rate in kilobytes per second. A value
318 of 0 means no limit. Overrides 'bandwidth_limit' config‐
319 uration option. Default is undefined.
320 -j , --jobs
322 Number of parallel workers to copy files during recovery.
323 Overrides value of the parameter parallel_jobs, if
324 present in the configuration file. Works only for
325 servers configured through rsync/SSH.
326 --get-wal, --no-get-wal
328 Enable/Disable usage of get-wal for WAL fetching during
329 recovery. Default is based on recovery_options setting.
330 --network-compression, --no-network-compression
332 Enable/Disable network compression during remote recov‐
333 ery. Default is based on network_compression configura‐
334 tion setting.
335 --standby-mode
337 Specifies whether to start the PostgreSQL server as a
338 standby. Default is undefined.
339 replication-status [OPTIONS] SERVER_NAME
341 Shows live information and status of any streaming client at‐
342 tached to the given server (or servers). Default behaviour can
343 be changed through the following options:
344 --minimal
346 machine readable output (default: False)
347 --target TARGET_TYPE
349 Possible values for TARGET_TYPE are:
350 · hot-standby: lists only hot standby servers
352 · wal-streamer: lists only WAL streaming clients, such as
354 pg_receivewal
355 · all: any streaming client (default)
357 show-backup SERVER_NAME BACKUP_ID
359 Show detailed information about a particular backup, identified
360 by the server name and the backup ID. See the Backup ID short‐
361 cuts section below for available shortcuts. For example:
362 Backup 20150828T130001:
364 Server Name : quagmire
365 Status : DONE
366 PostgreSQL Version : 90402
367 PGDATA directory : /srv/postgresql/9.4/main/data
368 Base backup information:
370 Disk usage : 12.4 TiB (12.4 TiB with WALs)
371 Incremental size : 4.9 TiB (-60.02%)
372 Timeline : 1
373 Begin WAL : 0000000100000CFD000000AD
374 End WAL : 0000000100000D0D00000008
375 WAL number : 3932
376 WAL compression ratio: 79.51%
377 Begin time : 2015-08-28 13:00:01.633925+00:00
378 End time : 2015-08-29 10:27:06.522846+00:00
379 Begin Offset : 1575048
380 End Offset : 13853016
381 Begin XLOG : CFD/AD180888
382 End XLOG : D0D/8D36158
383 WAL information:
385 No of files : 35039
386 Disk usage : 121.5 GiB
387 WAL rate : 275.50/hour
388 Compression ratio : 77.81%
389 Last available : 0000000100000D95000000E7
390 Catalog information:
392 Retention Policy : not enforced
393 Previous Backup : 20150821T130001
394 Next Backup : - (this is the latest base backup)
395 show-server SERVER_NAME
397 Show information about SERVER_NAME, including: conninfo, back‐
398 up_directory, wals_directory and many more. Specify all as
399 SERVER_NAME to show information about all the configured
400 servers.
401 status SERVER_NAME
403 Show information about the status of a server, including: number
404 of available backups, archive_command, archive_status and many
405 more. For example:
406 Server quagmire:
408 Description: The Giggity database
409 Passive node: False
410 PostgreSQL version: 9.3.9
411 pgespresso extension: Not available
412 PostgreSQL Data directory: /srv/postgresql/9.3/data
413 PostgreSQL 'archive_command' setting: rsync -a %p barman@backup:/var/lib/barman/quagmire/incoming
414 Last archived WAL: 0000000100003103000000AD
415 Current WAL segment: 0000000100003103000000AE
416 Retention policies: enforced (mode: auto, retention: REDUNDANCY 2, WAL retention: MAIN)
417 No. of available backups: 2
418 First available backup: 20150908T003001
419 Last available backup: 20150909T003001
420 Minimum redundancy requirements: satisfied (2/1)
421 switch-wal SERVER_NAME
423 Execute pg_switch_wal() on the target server (from PostgreSQL
424 10), or pg_switch_xlog (for PostgreSQL 8.3 to 9.6).
425 --force
427 Forces the switch by executing CHECKPOINT before
428 pg_switch_xlog(). IMPORTANT: executing a CHECKPOINT
429 might increase I/O load on a PostgreSQL server. Use this
430 option with care.
431 --archive
433 Wait for one xlog file to be archived. If after a de‐
434 fined amount of time (default: 30 seconds) no xlog file
435 is archived, Barman will terminate with failure exit
436 code. Available also on standby servers.
437 --archive-timeout TIMEOUT
439 Specifies the amount of time in seconds (default: 30 sec‐
440 onds) the archiver will wait for a new xlog file to be
441 archived before timing out. Available also on standby
442 servers.
443 switch-xlog SERVER_NAME
445 Alias for switch-wal (kept for back-compatibility)
446 sync-backup SERVER_NAME BACKUP_ID
448 Command used for the synchronisation of a passive node with its
449 primary. Executes a copy of all the files of a BACKUP_ID that
450 is present on SERVER_NAME node. This command is available only
451 for passive nodes, and uses the primary_ssh_command option to
452 establish a secure connection with the primary node.
453 sync-info SERVER_NAME [LAST_WAL [LAST_POSITION]]
455 Collect information regarding the current status of a Barman
456 server, to be used for synchronisation purposes. Returns a JSON
457 output representing SERVER_NAME, that contains: all the success‐
458 fully finished backup, all the archived WAL files, the configu‐
459 ration, last WAL file been read from the xlog.db and the posi‐
460 tion in the file.
461 LAST_WAL
463 tells sync-info to skip any WAL file previous to that
464 (incremental synchronisation)
465 LAST_POSITION
467 hint for quickly positioning in the xlog.db file (incre‐
468 mental synchronisation)
469 sync-wals SERVER_NAME
471 Command used for the synchronisation of a passive node with its
472 primary. Executes a copy of all the archived WAL files that are
473 present on SERVER_NAME node. This command is available only for
474 passive nodes, and uses the primary_ssh_command option to estab‐
475 lish a secure connection with the primary node.
476
478 Rather than using the timestamp backup ID, you can use any of the fol‐
479 lowing shortcuts/aliases to identity a backup for a given server:
480 first Oldest available backup for that server, in chronological order.
482 last Latest available backup for that server, in chronological order.
484 latest same ast last.
486 oldest same ast first.
488
490 0 Success
491 Not zero
493 Failure
494
496 barman (5).
497
499 Barman has been extensively tested, and is currently being used in sev‐
500 eral production environments. However, we cannot exclude the presence
501 of bugs.
502 Any bug can be reported via the Sourceforge bug tracker. Along the bug
504 submission, users can provide developers with diagnostics information
505 obtained through the barman diagnose command.
506
508 In alphabetical order:
509 · Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (architect)
511 · Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
513 · Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
515 · Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
517 · Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
519 · Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
521 · Britt Cole <britt.cole@2ndquadrant.com> (documentation)
523 · Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (project leader)
525 · Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
527 Past contributors:
529 · Carlo Ascani
531 · Stefano Bianucci
533 · Giuseppe Broccolo
535
537 · Homepage: <http://www.pgbarman.org/>
538 · Documentation: <http://docs.pgbarman.org/>
540 · Professional support: <http://www.2ndQuadrant.com/>
542
544 Barman is the property of 2ndQuadrant Limited and its code is distrib‐
545 uted under GNU General Public License v3.
546 Copyright (C) 2011-2020 2ndQuadrant Limited - <http://www.2ndQuad‐
548 rant.com/>.
549
551 2ndQuadrant Limited <https://www.2ndQuadrant.com>.
552Barman User manuals November 5, 2020 BARMAN(1)