1BARMAN(1) Version 2.5 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
31 Important: every command has a help option
32 archive-wal SERVER_NAME
34 Get any incoming xlog file (both through standard archive_com‐
35 mand and streaming replication, where applicable) and moves them
36 in the WAL archive for that server. If necessary, apply com‐
37 pression when requested by the user.
38 backup SERVER_NAME
40 Perform a backup of SERVER_NAME using parameters specified in
41 the configuration file. Specify all as SERVER_NAME to perform a
42 backup of all the configured servers.
43 --immediate-checkpoint
45 forces the initial checkpoint to be done as quickly as
46 possible. Overrides value of the parameter immedi‐
47 ate_checkpoint, if present in the configuration file.
48 --no-immediate-checkpoint
50 forces to wait for the checkpoint. Overrides value of
51 the parameter immediate_checkpoint, if present in the
52 configuration file.
53 --reuse-backup [INCREMENTAL_TYPE]
55 Overrides reuse_backup option behaviour. Possible values
56 for INCREMENTAL_TYPE are:
57 · off: do not reuse the last available backup;
59 · copy: reuse the last available backup for a server and
61 create a copy of the unchanged files (reduce backup
62 time);
63 · link: reuse the last available backup for a server and
65 create a hard link of the unchanged files (reduce back‐
66 up time and space);
67 link is the default target if --reuse-backup is used and
69 INCREMENTAL_TYPE is not explicited.
70 --retry-times
72 Number of retries of base backup copy, after an error.
73 Used during both backup and recovery operations. Over‐
74 rides value of the parameter basebackup_retry_times, if
75 present in the configuration file.
76 --no-retry
78 Same as --retry-times 0
79 --retry-sleep
81 Number of seconds of wait after a failed copy, before
82 retrying. Used during both backup and recovery opera‐
83 tions. Overrides value of the parameter baseback‐
84 up_retry_sleep, if present in the configuration file.
85 -j , --jobs
87 Number of parallel workers to copy files during backup.
88 Overrides value of the parameter parallel_jobs, if
89 present in the configuration file.
90 check-backup SERVER_NAME BACKUP_ID
92 Make sure that all the required WAL files to check the consis‐
93 tency of a physical backup (that is, from the beginning to the
94 end of the full backup) are correctly archived. This command is
95 automatically invoked by the cron command and at the end of ev‐
96 ery backup operation.
97 check SERVER_NAME
99 Show diagnostic information about SERVER_NAME, including: Ssh
100 connection check, PostgreSQL version, configuration and backup
101 directories, archiving process, streaming process, replication
102 slots, etc. Specify all as SERVER_NAME to show diagnostic in‐
103 formation about all the configured servers.
104 --nagios
106 Nagios plugin compatible output
107 cron Perform maintenance tasks, such as enforcing retention policies
109 or WAL files management.
110 delete SERVER_NAME BACKUP_ID
112 Delete the specified backup. Backup ID shortcuts section below
113 for available shortcuts.
114 diagnose
116 Collect diagnostic information about the server where barman is
117 installed and all the configured servers, including: global con‐
118 figuration, SSH version, Python version, rsync version, as well
119 as current configuration and status of all servers.
120 get-wal [OPTIONS] SERVER_NAME WAL_ID
122 Retrieve a WAL file from the xlog archive of a given server. By
123 default, the requested WAL file, if found, is returned as uncom‐
124 pressed content to STDOUT. The following options allow users to
125 change this behaviour:
126 -o OUTPUT_DIRECTORY
128 destination directory where the get-wal will deposit the
129 requested WAL
130 -z output will be compressed using gzip
132 -j output will be compressed using bzip2
134 -p SIZE
136 peek from the WAL archive up to SIZE WAL files, starting
137 from the requested one. 'SIZE' must be an integer >= 1.
138 When invoked with this option, get-wal returns a list of
139 zero to 'SIZE' WAL segment names, one per row.
140 list-backup SERVER_NAME
142 Show available backups for SERVER_NAME. This command is useful
143 to retrieve a backup ID. For example:
144 servername 20111104T102647 - Fri Nov 4 10:26:48 2011 - Size: 17.0 MiB - WAL Size: 100 B
146 In this case, *20111104T102647* is the backup ID.
148 list-files [OPTIONS] SERVER_NAME BACKUP_ID
150 List all the files in a particular backup, identified by the
151 server name and the backup ID. See the Backup ID shortcuts sec‐
152 tion below for available shortcuts.
153 --target TARGET_TYPE
155 Possible values for TARGET_TYPE are:
156 · data: lists just the data files;
158 · standalone: lists the base backup files, including re‐
160 quired WAL files;
161 · wal: lists all the WAL files between the start of the
163 base backup and the end of the log / the start of the
164 following base backup (depending on whether the speci‐
165 fied base backup is the most recent one available);
166 · full: same as data + wal.
168 The default value is standalone.
170 list-server
172 Show all the configured servers, and their descriptions.
173 rebuild-xlogdb SERVER_NAME
175 Perform a rebuild of the WAL file metadata for SERVER_NAME (or
176 every server, using the all shortcut) guessing it from the disk
177 content. The metadata of the WAL archive is contained in the
178 xlog.db file, and every Barman server has its own copy.
179 receive-wal SERVER_NAME
181 Start the stream of transaction logs for a server. The process
182 relies on pg_receivewal/pg_receivexlog to receive WAL files from
183 the PostgreSQL servers through the streaming protocol.
184 --stop stop the receive-wal process for the server
186 --reset
188 reset the status of receive-wal, restarting the streaming
189 from the current WAL file of the server
190 --create-slot
192 create the physical replication slot configured with the
193 slot_name configuration parameter
194 --drop-slot
196 drop the physical replication slot configured with the
197 slot_name configuration parameter
198 recover [OPTIONS] SERVER_NAME BACKUP_ID DESTINATION_DIRECTORY
200 Recover a backup in a given directory (local or remote, depend‐
201 ing on the --remote-ssh-command option settings). See the Back‐
202 up ID shortcuts section below for available shortcuts.
203 --target-tli TARGET_TLI
205 Recover the specified timeline.
206 --target-time TARGET_TIME
208 Recover to the specified time.
209 You can use any valid unambiguous representation (e.g:
211 "YYYY-MM-DD HH:MM:SS.mmm").
212 --target-xid TARGET_XID
214 Recover to the specified transaction ID.
215 --target-name TARGET_NAME
217 Recover to the named restore point previously created
218 with the pg_create_restore_point(name) (for PostgreSQL
219 9.1 and above users).
220 --target-immediate
222 Recover ends when a consistent state is reached (end of
223 the base backup)
224 --exclusive
226 Set target xid to be non inclusive.
227 --target-action ACTION
229 Trigger the specified action once the recovery target is
230 reached. Possible actions are: pause (PostgreSQL 9.1 and
231 above), shutdown (PostgreSQL 9.5 and above) and promote
232 (ditto). This option requires a target to be defined,
233 with one of the above options.
234 --tablespace NAME:LOCATION
236 Specify tablespace relocation rule.
237 --remote-ssh-command SSH_COMMAND
239 This options activates remote recovery, by specifying the
240 secure shell command to be launched on a remote host.
241 This is the equivalent of the "ssh_command" server option
242 in the configuration file for remote recovery. Example:
243 'ssh postgres@db2'.
244 --retry-times RETRY_TIMES
246 Number of retries of data copy during base backup after
247 an error. Overrides value of the parameter baseback‐
248 up_retry_times, if present in the configuration file.
249 --no-retry
251 Same as --retry-times 0
252 --retry-sleep
254 Number of seconds of wait after a failed copy, before
255 retrying. Overrides value of the parameter baseback‐
256 up_retry_sleep, if present in the configuration file.
257 -j , --jobs
259 Number of parallel workers to copy files during recovery.
260 Overrides value of the parameter parallel_jobs, if
261 present in the configuration file. Works only for
262 servers configured through rsync/SSH.
263 --get-wal, --no-get-wal
265 Enable/Disable usage of get-wal for WAL fetching during
266 recovery. Default is based on recovery_options setting.
267 --network-compression, --no-network-compression
269 Enable/Disable network compression during remote recov‐
270 ery. Default is based on network_compression configura‐
271 tion setting.
272 --standby-mode
274 Specifies whether to start the PostgreSQL server as a
275 standby. Default is undefined.
276 replication-status [OPTIONS] SERVER_NAME
278 Shows live information and status of any streaming client at‐
279 tached to the given server (or servers). Default behaviour can
280 be changed through the following options:
281 --minimal
283 machine readable output (default: False)
284 --target TARGET_TYPE
286 Possible values for TARGET_TYPE are:
287 · hot-standby: lists only hot standby servers
289 · wal-streamer: lists only WAL streaming clients, such as
291 pg_receivewal
292 · all: any streaming client (default)
294 show-backup SERVER_NAME BACKUP_ID
296 Show detailed information about a particular backup, identified
297 by the server name and the backup ID. See the Backup ID short‐
298 cuts section below for available shortcuts. For example:
299 Backup 20150828T130001:
301 Server Name : quagmire
302 Status : DONE
303 PostgreSQL Version : 90402
304 PGDATA directory : /srv/postgresql/9.4/main/data
305 Base backup information:
307 Disk usage : 12.4 TiB (12.4 TiB with WALs)
308 Incremental size : 4.9 TiB (-60.02%)
309 Timeline : 1
310 Begin WAL : 0000000100000CFD000000AD
311 End WAL : 0000000100000D0D00000008
312 WAL number : 3932
313 WAL compression ratio: 79.51%
314 Begin time : 2015-08-28 13:00:01.633925+00:00
315 End time : 2015-08-29 10:27:06.522846+00:00
316 Begin Offset : 1575048
317 End Offset : 13853016
318 Begin XLOG : CFD/AD180888
319 End XLOG : D0D/8D36158
320 WAL information:
322 No of files : 35039
323 Disk usage : 121.5 GiB
324 WAL rate : 275.50/hour
325 Compression ratio : 77.81%
326 Last available : 0000000100000D95000000E7
327 Catalog information:
329 Retention Policy : not enforced
330 Previous Backup : 20150821T130001
331 Next Backup : - (this is the latest base backup)
332 show-server SERVER_NAME
334 Show information about SERVER_NAME, including: conninfo, back‐
335 up_directory, wals_directory and many more. Specify all as
336 SERVER_NAME to show information about all the configured
337 servers.
338 status SERVER_NAME
340 Show information about the status of a server, including: number
341 of available backups, archive_command, archive_status and many
342 more. For example:
343 Server quagmire:
345 Description: The Giggity database
346 Passive node: False
347 PostgreSQL version: 9.3.9
348 pgespresso extension: Not available
349 PostgreSQL Data directory: /srv/postgresql/9.3/data
350 PostgreSQL 'archive_command' setting: rsync -a %p barman@backup:/var/lib/barman/quagmire/incoming
351 Last archived WAL: 0000000100003103000000AD
352 Current WAL segment: 0000000100003103000000AE
353 Retention policies: enforced (mode: auto, retention: REDUNDANCY 2, WAL retention: MAIN)
354 No. of available backups: 2
355 First available backup: 20150908T003001
356 Last available backup: 20150909T003001
357 Minimum redundancy requirements: satisfied (2/1)
358 switch-wal SERVER_NAME
360 Execute pg_switch_wal() on the target server (from PostgreSQL
361 10), or pg_switch_xlog (for PostgreSQL 8.3 to 9.6).
362 --force
364 Forces the switch by executing CHECKPOINT before
365 pg_switch_xlog(). IMPORTANT: executing a CHECKPOINT
366 might increase I/O load on a PostgreSQL server. Use this
367 option with care.
368 --archive
370 Wait for one xlog file to be archived. If after a de‐
371 fined amount of time (default: 30 seconds) no xlog file
372 is archived, Barman will teminate with failure exit code.
373 Available also on standby servers.
374 --archive-timeout TIMEOUT
376 Specifies the amount of time in seconds (default: 30 sec‐
377 onds) the archiver will wait for a new xlog file to be
378 archived before timing out. Available also on standby
379 servers.
380 switch-xlog SERVER_NAME
382 Alias for switch-wal (kept for back-compatibility)
383
385 Rather than using the timestamp backup ID, you can use any of the fol‐
386 lowing shortcuts/aliases to identity a backup for a given server:
387 first Oldest available backup for that server, in chronological order.
389 last Latest available backup for that server, in chronological order.
391 latest same ast last.
393 oldest same ast first.
395
397 0 Success
398 Not zero
400 Failure
401
403 barman (5).
404
406 Barman has been extensively tested, and is currently being used in sev‐
407 eral production environments. However, we cannot exclude the presence
408 of bugs.
409 Any bug can be reported via the Sourceforge bug tracker. Along the bug
411 submission, users can provide developers with diagnostics information
412 obtained through the barman diagnose command.
413
415 In alphabetical order:
416 · Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (architect)
418 · Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
420 · Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
422 · Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
424 · Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
426 · Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
428 · Britt Cole <britt.cole@2ndquadrant.com> (documentation)
430 · Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (project leader)
432 · Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
434 Past contributors:
436 · Carlo Ascani
438 · Stefano Bianucci
440 · Giuseppe Broccolo
442
444 · Homepage: <http://www.pgbarman.org/>
445 · Documentation: <http://docs.pgbarman.org/>
447 · Professional support: <http://www.2ndQuadrant.com/>
449
451 Barman is the property of 2ndQuadrant Limited and its code is distrib‐
452 uted under GNU General Public License v3.
453 Copyright (C) 2011-2018 2ndQuadrant Limited - <http://www.2ndQuad‐
455 rant.com/>.
456
458 2ndQuadrant Limited <https://www.2ndQuadrant.com>.
459Barman User manuals October 23, 2018 BARMAN(1)