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