1BARMAN(1) Version 2.10 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 -f {json,console}, --format {json,console}
37 output format (default: 'console')
38
40 Important: every command has a help option
41 archive-wal SERVER_NAME
43 Get any incoming xlog file (both through standard archive_com‐
44 mand and streaming replication, where applicable) and moves them
45 in the WAL archive for that server. If necessary, apply com‐
46 pression when requested by the user.
47 backup SERVER_NAME
49 Perform a backup of SERVER_NAME using parameters specified in
50 the configuration file. Specify all as SERVER_NAME to perform a
51 backup of all the configured servers.
52 --immediate-checkpoint
54 forces the initial checkpoint to be done as quickly as
55 possible. Overrides value of the parameter immedi‐
56 ate_checkpoint, if present in the configuration file.
57 --no-immediate-checkpoint
59 forces to wait for the checkpoint. Overrides value of
60 the parameter immediate_checkpoint, if present in the
61 configuration file.
62 --reuse-backup [INCREMENTAL_TYPE]
64 Overrides reuse_backup option behaviour. Possible values
65 for INCREMENTAL_TYPE are:
66 · off: do not reuse the last available backup;
68 · copy: reuse the last available backup for a server and
70 create a copy of the unchanged files (reduce backup
71 time);
72 · link: reuse the last available backup for a server and
74 create a hard link of the unchanged files (reduce back‐
75 up time and space);
76 link is the default target if --reuse-backup is used and
78 INCREMENTAL_TYPE is not explicited.
79 --retry-times
81 Number of retries of base backup copy, after an error.
82 Used during both backup and recovery operations. Over‐
83 rides value of the parameter basebackup_retry_times, if
84 present in the configuration file.
85 --no-retry
87 Same as --retry-times 0
88 --retry-sleep
90 Number of seconds of wait after a failed copy, before
91 retrying. Used during both backup and recovery opera‐
92 tions. Overrides value of the parameter baseback‐
93 up_retry_sleep, if present in the configuration file.
94 -j, --jobs
96 Number of parallel workers to copy files during backup.
97 Overrides value of the parameter parallel_jobs, if
98 present in the configuration file.
99 --bwlimit KBPS
101 maximum transfer rate in kilobytes per second. A value
102 of 0 means no limit. Overrides 'bandwidth_limit' config‐
103 uration option. Default is undefined.
104 --wait, -w
106 wait for all required WAL files by the base backup to be
107 archived
108 --wait-timeout
110 the time, in seconds, spent waiting for the required WAL
111 files to be archived before timing out
112 check-backup SERVER_NAME BACKUP_ID
114 Make sure that all the required WAL files to check the consis‐
115 tency of a physical backup (that is, from the beginning to the
116 end of the full backup) are correctly archived. This command is
117 automatically invoked by the cron command and at the end of ev‐
118 ery backup operation.
119 check SERVER_NAME
121 Show diagnostic information about SERVER_NAME, including: Ssh
122 connection check, PostgreSQL version, configuration and backup
123 directories, archiving process, streaming process, replication
124 slots, etc. Specify all as SERVER_NAME to show diagnostic in‐
125 formation about all the configured servers.
126 --nagios
128 Nagios plugin compatible output
129 cron Perform maintenance tasks, such as enforcing retention policies
131 or WAL files management.
132 --keep-descriptors
134 Keep the stdout and the stderr streams of the Barman sub‐
135 processes attached to this one. This is useful for Dock‐
136 er based installations.
137 delete SERVER_NAME BACKUP_ID
139 Delete the specified backup. Backup ID shortcuts section below
140 for available shortcuts.
141 diagnose
143 Collect diagnostic information about the server where barman is
144 installed and all the configured servers, including: global con‐
145 figuration, SSH version, Python version, rsync version, as well
146 as current configuration and status of all servers.
147 get-wal [OPTIONS] SERVER_NAME WAL_NAME
149 Retrieve a WAL file from the xlog archive of a given server. By
150 default, the requested WAL file, if found, is returned as uncom‐
151 pressed content to STDOUT. The following options allow users to
152 change this behaviour:
153 -o OUTPUT_DIRECTORY
155 destination directory where the get-wal will deposit the
156 requested WAL
157 -P, --partial
159 retrieve also partial WAL files (.partial)
160 -z output will be compressed using gzip
162 -j output will be compressed using bzip2
164 -p SIZE
166 peek from the WAL archive up to SIZE WAL files, starting
167 from the requested one. 'SIZE' must be an integer >= 1.
168 When invoked with this option, get-wal returns a list of
169 zero to 'SIZE' WAL segment names, one per row.
170 -t, --test
172 test both the connection and the configuration of the re‐
173 quested PostgreSQL server in Barman for WAL retrieval.
174 With this option, the 'WAL_NAME' mandatory argument is
175 ignored.
176 list-backup SERVER_NAME
178 Show available backups for SERVER_NAME. This command is useful
179 to retrieve a backup ID. For example:
180 servername 20111104T102647 - Fri Nov 4 10:26:48 2011 - Size: 17.0 MiB - WAL Size: 100 B
182 In this case, *20111104T102647* is the backup ID.
184 list-files [OPTIONS] SERVER_NAME BACKUP_ID
186 List all the files in a particular backup, identified by the
187 server name and the backup ID. See the Backup ID shortcuts sec‐
188 tion below for available shortcuts.
189 --target TARGET_TYPE
191 Possible values for TARGET_TYPE are:
192 · data: lists just the data files;
194 · standalone: lists the base backup files, including re‐
196 quired WAL files;
197 · wal: lists all the WAL files between the start of the
199 base backup and the end of the log / the start of the
200 following base backup (depending on whether the speci‐
201 fied base backup is the most recent one available);
202 · full: same as data + wal.
204 The default value is standalone.
206 list-server
208 Show all the configured servers, and their descriptions.
209 put-wal [OPTIONS] SERVER_NAME
211 Receive a WAL file from a remote server and securely store it
212 into the SERVER_NAME incoming directory. The WAL file is re‐
213 trieved from the STDIN, and must be encapsulated in a tar stream
214 together with a MD5SUMS file to validate it. This command is
215 meant to be invoked through SSH from a remote barman-wal-archive
216 utility (part of barman-cli package). Do not use this command
217 directly unless you take full responsibility of the content of
218 files.
219 -t, --test
221 test both the connection and the configuration of the re‐
222 quested PostgreSQL server in Barman to make sure it is
223 ready to receive WAL files.
224 rebuild-xlogdb SERVER_NAME
226 Perform a rebuild of the WAL file metadata for SERVER_NAME (or
227 every server, using the all shortcut) guessing it from the disk
228 content. The metadata of the WAL archive is contained in the
229 xlog.db file, and every Barman server has its own copy.
230 receive-wal SERVER_NAME
232 Start the stream of transaction logs for a server. The process
233 relies on pg_receivewal/pg_receivexlog to receive WAL files from
234 the PostgreSQL servers through the streaming protocol.
235 --stop stop the receive-wal process for the server
237 --reset
239 reset the status of receive-wal, restarting the streaming
240 from the current WAL file of the server
241 --create-slot
243 create the physical replication slot configured with the
244 slot_name configuration parameter
245 --drop-slot
247 drop the physical replication slot configured with the
248 slot_name configuration parameter
249 recover [OPTIONS] SERVER_NAME BACKUP_ID DESTINATION_DIRECTORY
251 Recover a backup in a given directory (local or remote, depend‐
252 ing on the --remote-ssh-command option settings). See the Back‐
253 up ID shortcuts section below for available shortcuts.
254 --target-tli TARGET_TLI
256 Recover the specified timeline.
257 --target-time TARGET_TIME
259 Recover to the specified time.
260 You can use any valid unambiguous representation (e.g:
262 "YYYY-MM-DD HH:MM:SS.mmm").
263 --target-xid TARGET_XID
265 Recover to the specified transaction ID.
266 --target-lsn TARGET_LSN
268 Recover to the specified LSN (Log Sequence Number). Re‐
269 quires PostgreSQL 10 or above.
270 --target-name TARGET_NAME
272 Recover to the named restore point previously created
273 with the pg_create_restore_point(name) (for PostgreSQL
274 9.1 and above users).
275 --target-immediate
277 Recover ends when a consistent state is reached (end of
278 the base backup)
279 --exclusive
281 Set target (time, XID or LSN) to be non inclusive.
282 --target-action ACTION
284 Trigger the specified action once the recovery target is
285 reached. Possible actions are: pause (PostgreSQL 9.1 and
286 above), shutdown (PostgreSQL 9.5 and above) and promote
287 (ditto). This option requires a target to be defined,
288 with one of the above options.
289 --tablespace NAME:LOCATION
291 Specify tablespace relocation rule.
292 --remote-ssh-command SSH_COMMAND
294 This options activates remote recovery, by specifying the
295 secure shell command to be launched on a remote host.
296 This is the equivalent of the "ssh_command" server option
297 in the configuration file for remote recovery. Example:
298 'ssh postgres@db2'.
299 --retry-times RETRY_TIMES
301 Number of retries of data copy during base backup after
302 an error. Overrides value of the parameter baseback‐
303 up_retry_times, if present in the configuration file.
304 --no-retry
306 Same as --retry-times 0
307 --retry-sleep
309 Number of seconds of wait after a failed copy, before
310 retrying. Overrides value of the parameter baseback‐
311 up_retry_sleep, if present in the configuration file.
312 --bwlimit KBPS
314 maximum transfer rate in kilobytes per second. A value
315 of 0 means no limit. Overrides 'bandwidth_limit' config‐
316 uration option. Default is undefined.
317 -j , --jobs
319 Number of parallel workers to copy files during recovery.
320 Overrides value of the parameter parallel_jobs, if
321 present in the configuration file. Works only for
322 servers configured through rsync/SSH.
323 --get-wal, --no-get-wal
325 Enable/Disable usage of get-wal for WAL fetching during
326 recovery. Default is based on recovery_options setting.
327 --network-compression, --no-network-compression
329 Enable/Disable network compression during remote recov‐
330 ery. Default is based on network_compression configura‐
331 tion setting.
332 --standby-mode
334 Specifies whether to start the PostgreSQL server as a
335 standby. Default is undefined.
336 replication-status [OPTIONS] SERVER_NAME
338 Shows live information and status of any streaming client at‐
339 tached to the given server (or servers). Default behaviour can
340 be changed through the following options:
341 --minimal
343 machine readable output (default: False)
344 --target TARGET_TYPE
346 Possible values for TARGET_TYPE are:
347 · hot-standby: lists only hot standby servers
349 · wal-streamer: lists only WAL streaming clients, such as
351 pg_receivewal
352 · all: any streaming client (default)
354 show-backup SERVER_NAME BACKUP_ID
356 Show detailed information about a particular backup, identified
357 by the server name and the backup ID. See the Backup ID short‐
358 cuts section below for available shortcuts. For example:
359 Backup 20150828T130001:
361 Server Name : quagmire
362 Status : DONE
363 PostgreSQL Version : 90402
364 PGDATA directory : /srv/postgresql/9.4/main/data
365 Base backup information:
367 Disk usage : 12.4 TiB (12.4 TiB with WALs)
368 Incremental size : 4.9 TiB (-60.02%)
369 Timeline : 1
370 Begin WAL : 0000000100000CFD000000AD
371 End WAL : 0000000100000D0D00000008
372 WAL number : 3932
373 WAL compression ratio: 79.51%
374 Begin time : 2015-08-28 13:00:01.633925+00:00
375 End time : 2015-08-29 10:27:06.522846+00:00
376 Begin Offset : 1575048
377 End Offset : 13853016
378 Begin XLOG : CFD/AD180888
379 End XLOG : D0D/8D36158
380 WAL information:
382 No of files : 35039
383 Disk usage : 121.5 GiB
384 WAL rate : 275.50/hour
385 Compression ratio : 77.81%
386 Last available : 0000000100000D95000000E7
387 Catalog information:
389 Retention Policy : not enforced
390 Previous Backup : 20150821T130001
391 Next Backup : - (this is the latest base backup)
392 show-server SERVER_NAME
394 Show information about SERVER_NAME, including: conninfo, back‐
395 up_directory, wals_directory and many more. Specify all as
396 SERVER_NAME to show information about all the configured
397 servers.
398 status SERVER_NAME
400 Show information about the status of a server, including: number
401 of available backups, archive_command, archive_status and many
402 more. For example:
403 Server quagmire:
405 Description: The Giggity database
406 Passive node: False
407 PostgreSQL version: 9.3.9
408 pgespresso extension: Not available
409 PostgreSQL Data directory: /srv/postgresql/9.3/data
410 PostgreSQL 'archive_command' setting: rsync -a %p barman@backup:/var/lib/barman/quagmire/incoming
411 Last archived WAL: 0000000100003103000000AD
412 Current WAL segment: 0000000100003103000000AE
413 Retention policies: enforced (mode: auto, retention: REDUNDANCY 2, WAL retention: MAIN)
414 No. of available backups: 2
415 First available backup: 20150908T003001
416 Last available backup: 20150909T003001
417 Minimum redundancy requirements: satisfied (2/1)
418 switch-wal SERVER_NAME
420 Execute pg_switch_wal() on the target server (from PostgreSQL
421 10), or pg_switch_xlog (for PostgreSQL 8.3 to 9.6).
422 --force
424 Forces the switch by executing CHECKPOINT before
425 pg_switch_xlog(). IMPORTANT: executing a CHECKPOINT
426 might increase I/O load on a PostgreSQL server. Use this
427 option with care.
428 --archive
430 Wait for one xlog file to be archived. If after a de‐
431 fined amount of time (default: 30 seconds) no xlog file
432 is archived, Barman will teminate with failure exit code.
433 Available also on standby servers.
434 --archive-timeout TIMEOUT
436 Specifies the amount of time in seconds (default: 30 sec‐
437 onds) the archiver will wait for a new xlog file to be
438 archived before timing out. Available also on standby
439 servers.
440 switch-xlog SERVER_NAME
442 Alias for switch-wal (kept for back-compatibility)
443 sync-backup SERVER_NAME BACKUP_ID
445 Command used for the synchronisation of a passive node with its
446 primary. Executes a copy of all the files of a BACKUP_ID that
447 is present on SERVER_NAME node. This command is available only
448 for passive nodes, and uses the primary_ssh_command option to
449 establish a secure connection with the primary node.
450 sync-info SERVER_NAME [LAST_WAL [LAST_POSITION]]
452 Collect information regarding the current status of a Barman
453 server, to be used for synchronisation purposes. Returns a JSON
454 output representing SERVER_NAME, that contains: all the success‐
455 fully finished backup, all the archived WAL files, the configu‐
456 ration, last WAL file been read from the xlog.db and the posi‐
457 tion in the file.
458 LAST_WAL
460 tells sync-info to skip any WAL file previous to that
461 (incremental synchronisation)
462 LAST_POSITION
464 hint for quickly positioning in the xlog.db file (incre‐
465 mental synchronisation)
466 sync-wals SERVER_NAME
468 Command used for the synchronisation of a passive node with its
469 primary. Executes a copy of all the archived WAL files that are
470 present on SERVER_NAME node. This command is available only for
471 passive nodes, and uses the primary_ssh_command option to estab‐
472 lish a secure connection with the primary node.
473
475 Rather than using the timestamp backup ID, you can use any of the fol‐
476 lowing shortcuts/aliases to identity a backup for a given server:
477 first Oldest available backup for that server, in chronological order.
479 last Latest available backup for that server, in chronological order.
481 latest same ast last.
483 oldest same ast first.
485
487 0 Success
488 Not zero
490 Failure
491
493 barman (5).
494
496 Barman has been extensively tested, and is currently being used in sev‐
497 eral production environments. However, we cannot exclude the presence
498 of bugs.
499 Any bug can be reported via the Sourceforge bug tracker. Along the bug
501 submission, users can provide developers with diagnostics information
502 obtained through the barman diagnose command.
503
505 In alphabetical order:
506 · Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (architect)
508 · Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
510 · Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
512 · Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
514 · Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
516 · Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
518 · Britt Cole <britt.cole@2ndquadrant.com> (documentation)
520 · Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (project leader)
522 · Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
524 Past contributors:
526 · Carlo Ascani
528 · Stefano Bianucci
530 · Giuseppe Broccolo
532
534 · Homepage: <http://www.pgbarman.org/>
535 · Documentation: <http://docs.pgbarman.org/>
537 · Professional support: <http://www.2ndQuadrant.com/>
539
541 Barman is the property of 2ndQuadrant Limited and its code is distrib‐
542 uted under GNU General Public License v3.
543 Copyright (C) 2011-2019 2ndQuadrant Limited - <http://www.2ndQuad‐
545 rant.com/>.
546
548 2ndQuadrant Limited <https://www.2ndQuadrant.com>.
549Barman User manuals December 5, 2019 BARMAN(1)