1BARMAN(5) Version 2.5 BARMAN(5)
2
6 barman - Backup and Recovery Manager for PostgreSQL
7
9 Barman is an administration tool for disaster recovery of PostgreSQL
10 servers written in Python and maintained by 2ndQuadrant. Barman can
11 perform remote backups of multiple servers in business critical envi‐
12 ronments and helps DBAs during the recovery phase.
13
15 The system-level Barman configuration file is located at
16 /etc/barman.conf
18 or
20 /etc/barman/barman.conf
22 and is overridden on a per-user level by
24 $HOME/.barman.conf
26
28 The Barman configuration file is a plain INI file. There is a general
29 section called [barman] and a section [servername] for each server you
30 want to backup. Rows starting with ; are comments.
31
33 Barman supports the inclusion of multiple configuration files, through
34 the configuration_files_directory option. Included files must contain
35 only server specifications, not global configurations. If the value of
36 configuration_files_directory is a directory, Barman reads all files
37 with .conf extension that exist in that folder. For example, if you
38 set it to /etc/barman.d, you can specify your PostgreSQL servers plac‐
39 ing each section in a separate .conf file inside the /etc/barman.d
40 folder.
41
43 active When set to true (default), the server is in full operational
44 state. When set to false, the server can be used for diagnos‐
45 tics, but any operational command such as backup execution or
46 WAL archiving is temporarily disabled. Setting active=false is
47 a good practice when adding a new node to Barman. Server.
48 archiver
50 This option allows you to activate log file shipping through
51 PostgreSQL's archive_command for a server. If set to true (de‐
52 fault), Barman expects that continuous archiving for a server is
53 in place and will activate checks as well as management (includ‐
54 ing compression) of WAL files that Postgres deposits in the in‐
55 coming directory. Setting it to false, will disable standard
56 continuous archiving for a server. Global/Server.
57 archiver_batch_size
59 This option allows you to activate batch processing of WAL files
60 for the archiver process, by setting it to a value > 0. Other‐
61 wise, the traditional unlimited processing of the WAL queue is
62 enabled. When batch processing is activated, the archive-wal
63 process would limit itself to maximum archiver_batch_size WAL
64 segments per single run. Integer. Global/Server.
65 backup_directory
67 Directory where backup data for a server will be placed. Serv‐
68 er.
69 backup_method
71 Configure the method barman used for backup execution. If set
72 to rsync (default), barman will execute backup using the rsync
73 command. If set to postgres barman will use the pg_basebackup
74 command to execute the backup. Global/Server.
75 backup_options
77 This option allows you to control the way Barman interacts with
78 PostgreSQL for backups. It is a comma-separated list of values
79 that accepts the following options:
80 · exclusive_backup (default when backup_method = rsync): bar‐
82 man backup executes backup operations using the standard ex‐
83 clusive backup approach (technically through pg_start_backup
84 and pg_stop_backup)
85 · concurrent_backup (default when backup_method = postgres): if
87 using PostgreSQL 9.2, 9.3, 9.4, and 9.5, Barman requires the
88 pgespresso module to be installed on the PostgreSQL server and
89 can be used to perform a backup from a standby server. Start‐
90 ing from PostgreSQL 9.6, Barman uses the new PostgreSQL API to
91 perform backups from a standby server.
92 · external_configuration: if present, any warning regarding ex‐
94 ternal configuration files is suppressed during the execution
95 of a backup.
96 Note that exclusive_backup and concurrent_backup are mutually
98 exclusive. Global/Server.
99 bandwidth_limit
101 This option allows you to specify a maximum transfer rate in
102 kilobytes per second. A value of zero specifies no limit (de‐
103 fault). Global/Server.
104 barman_home
106 Main data directory for Barman. Global.
107 barman_lock_directory
109 Directory for locks. Default: %(barman_home)s. Global.
110 basebackup_retry_sleep
112 Number of seconds of wait after a failed copy, before retrying
113 Used during both backup and recovery operations. Positive inte‐
114 ger, default 30. Global/Server.
115 basebackup_retry_times
117 Number of retries of base backup copy, after an error. Used
118 during both backup and recovery operations. Positive integer,
119 default 0. Global/Server.
120 basebackups_directory
122 Directory where base backups will be placed. Server.
123 check_timeout
125 Maximum execution time, in seconds per server, for a barman
126 check command. Set to 0 to disable the timeout. Positive inte‐
127 ger, default 30. Global/Server.
128 compression
130 Standard compression algorithm applied to WAL files. Possible
131 values are: gzip (requires gzip to be installed on the system),
132 bzip2 (requires bzip2), pigz (requires pigz), pygzip (Python's
133 internal gzip compressor) and pybzip2 (Python's internal bzip2
134 compressor). Global/Server.
135 conninfo
137 Connection string used by Barman to connect to the Postgres
138 server. This is a libpq connection string, consult the Post‐
139 greSQL manual (https://www.postgresql.org/docs/current/stat‐
140 ic/libpq-connect.html#LIBPQ-CONNSTRING) for more information.
141 Commonly used keys are: host, hostaddr, port, dbname, user,
142 password. Server.
143 custom_compression_filter
145 Customised compression algorithm applied to WAL files. Glob‐
146 al/Server.
147 custom_decompression_filter
149 Customised decompression algorithm applied to compressed WAL
150 files; this must match the compression algorithm. Global/Serv‐
151 er.
152 description
154 A human readable description of a server. Server.
155 errors_directory
157 Directory that contains WAL files that contain an error; usually
158 this is related to a conflict with an existing WAL file (e.g. a
159 WAL file that has been archived after a streamed one).
160 immediate_checkpoint
162 This option allows you to control the way PostgreSQL handles
163 checkpoint at the start of the backup. If set to false (de‐
164 fault), the I/O workload for the checkpoint will be limited, ac‐
165 cording to the checkpoint_completion_target setting on the Post‐
166 greSQL server. If set to true, an immediate checkpoint will be
167 requested, meaning that PostgreSQL will complete the checkpoint
168 as soon as possible. Global/Server.
169 incoming_wals_directory
171 Directory where incoming WAL files are archived into. Requires
172 archiver to be enabled. Server.
173 last_backup_maximum_age
175 This option identifies a time frame that must contain the latest
176 backup. If the latest backup is older than the time frame, bar‐
177 man check command will report an error to the user. If empty
178 (default), latest backup is always considered valid. Syntax for
179 this option is: "i (DAYS | WEEKS | MONTHS)" where i is a integer
180 greater than zero, representing the number of days | weeks |
181 months of the time frame. Global/Server.
182 log_file
184 Location of Barman's log file. Global.
185 log_level
187 Level of logging (DEBUG, INFO, WARNING, ERROR, CRITICAL). Glob‐
188 al.
189 max_incoming_wals_queue
191 Maximum number of WAL files in the incoming queue (in both
192 streaming and archiving pools) that are allowed before barman
193 check returns an error (that does not block backups). Glob‐
194 al/Server. Default: None (disabled).
195 minimum_redundancy
197 Minimum number of backups to be retained. Default 0. Glob‐
198 al/Server.
199 network_compression
201 This option allows you to enable data compression for network
202 transfers. If set to false (default), no compression is used.
203 If set to true, compression is enabled, reducing network usage.
204 Global/Server.
205 parallel_jobs
207 This option controls how many parallel workers will copy files
208 during a backup or recovery command. Default 1. Global/Server.
209 For backup purposes, it works only when backup_method is rsync.
210 path_prefix
212 One or more absolute paths, separated by colon, where Barman
213 looks for executable files. The paths specified in path_prefix
214 are tried before the ones specified in PATH environment vari‐
215 able. Global/server.
216 post_archive_retry_script
218 Hook script launched after a WAL file is archived by mainte‐
219 nance. Being this a retry hook script, Barman will retry the
220 execution of the script until this either returns a SUCCESS (0),
221 an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. In a post
222 archive scenario, ABORT_STOP has currently the same effects as
223 ABORT_CONTINUE. Global/Server.
224 post_archive_script
226 Hook script launched after a WAL file is archived by mainte‐
227 nance, after 'post_archive_retry_script'. Global/Server.
228 post_backup_retry_script
230 Hook script launched after a base backup. Being this a retry
231 hook script, Barman will retry the execution of the script until
232 this either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
233 ABORT_STOP (63) code. In a post backup scenario, ABORT_STOP has
234 currently the same effects as ABORT_CONTINUE. Global/Server.
235 post_backup_script
237 Hook script launched after a base backup, after 'post_back‐
238 up_retry_script'. Global/Server.
239 post_delete_retry_script
241 Hook script launched after the deletion of a backup. Being this
242 a retry hook script, Barman will retry the execution of the
243 script until this either returns a SUCCESS (0), an ABORT_CONTIN‐
244 UE (62) or an ABORT_STOP (63) code. In a post delete scenario,
245 ABORT_STOP has currently the same effects as ABORT_CONTINUE.
246 Global/Server.
247 post_delete_script
249 Hook script launched after the deletion of a backup, after
250 'post_delete_retry_script'. Global/Server.
251 post_recovery_retry_script
253 Hook script launched after a recovery. Being this a retry hook
254 script, Barman will retry the execution of the script until this
255 either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
256 ABORT_STOP (63) code. In a post recovery scenario, ABORT_STOP
257 has currently the same effects as ABORT_CONTINUE. Global/Serv‐
258 er.
259 post_recovery_script
261 Hook script launched after a recovery, after 'post_recov‐
262 ery_retry_script'. Global/Server.
263 post_wal_delete_retry_script
265 Hook script launched after the deletion of a WAL file. Being
266 this a retry hook script, Barman will retry the execution of the
267 script until this either returns a SUCCESS (0), an ABORT_CONTIN‐
268 UE (62) or an ABORT_STOP (63) code. In a post delete scenario,
269 ABORT_STOP has currently the same effects as ABORT_CONTINUE.
270 Global/Server.
271 post_wal_delete_script
273 Hook script launched after the deletion of a WAL file, after
274 'post_wal)delete_retry_script'. Global/Server.
275 pre_archive_retry_script
277 Hook script launched before a WAL file is archived by mainte‐
278 nance, after 'pre_archive_script'. Being this a retry hook
279 script, Barman will retry the execution of the script until this
280 either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
281 ABORT_STOP (63) code. Returning ABORT_STOP will propagate the
282 failure at a higher level and interrupt the WAL archiving opera‐
283 tion. Global/Server.
284 pre_archive_script
286 Hook script launched before a WAL file is archived by mainte‐
287 nance. Global/Server.
288 pre_backup_retry_script
290 Hook script launched before a base backup, after 'pre_back‐
291 up_script'. Being this a retry hook script, Barman will retry
292 the execution of the script until this either returns a SUCCESS
293 (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. Return‐
294 ing ABORT_STOP will propagate the failure at a higher level and
295 interrupt the backup operation. Global/Server.
296 pre_backup_script
298 Hook script launched before a base backup. Global/Server.
299 pre_delete_retry_script
301 Hook script launched before the deletion of a backup, after
302 'pre_delete_script'. Being this a retry hook script, Barman
303 will retry the execution of the script until this either returns
304 a SUCCESS (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63)
305 code. Returning ABORT_STOP will propagate the failure at a
306 higher level and interrupt the backup deletion. Global/Server.
307 pre_delete_script
309 Hook script launched before the deletion of a backup. Glob‐
310 al/Server.
311 pre_recovery_retry_script
313 Hook script launched before a recovery, after 'pre_recov‐
314 ery_script'. Being this a retry hook script, Barman will retry
315 the execution of the script until this either returns a SUCCESS
316 (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. Return‐
317 ing ABORT_STOP will propagate the failure at a higher level and
318 interrupt the recover operation. Global/Server.
319 pre_recovery_script
321 Hook script launched before a recovery. Global/Server.
322 pre_wal_delete_retry_script
324 Hook script launched before the deletion of a WAL file, after
325 'pre_wal_delete_script'. Being this a retry hook script, Barman
326 will retry the execution of the script until this either returns
327 a SUCCESS (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63)
328 code. Returning ABORT_STOP will propagate the failure at a
329 higher level and interrupt the WAL file deletion. Global/Serv‐
330 er.
331 pre_wal_delete_script
333 Hook script launched before the deletion of a WAL file. Glob‐
334 al/Server.
335 recovery_options
337 Options for recovery operations. Currently only supports
338 get-wal. get-wal activates generation of a basic restore_com‐
339 mand in the resulting recovery.conf file that uses the bar‐
340 man get-wal command to fetch WAL files directly from Barman's
341 archive of WALs. Comma separated list of values, default empty.
342 Global/Server.
343 retention_policy
345 Policy for retention of periodic backups and archive logs. If
346 left empty, retention policies are not enforced. For redundancy
347 based retention policy use "REDUNDANCY i" (where i is an integer
348 > 0 and defines the number of backups to retain). For recovery
349 window retention policy use "RECOVERY WINDOW OF i DAYS" or "RE‐
350 COVERY WINDOW OF i WEEKS" or "RECOVERY WINDOW OF i MONTHS" where
351 i is a positive integer representing, specifically, the number
352 of days, weeks or months to retain your backups. For more de‐
353 tailed information, refer to the official documentation. De‐
354 fault value is empty. Global/Server.
355 retention_policy_mode
357 Currently only "auto" is implemented. Global/Server.
358 reuse_backup
360 This option controls incremental backup support. Global/Server.
361 Possible values are:
362 · off: disabled (default);
364 · copy: reuse the last available backup for a server and create
366 a copy of the unchanged files (reduce backup time);
367 · link: reuse the last available backup for a server and create
369 a hard link of the unchanged files (reduce backup time and
370 space). Requires operating system and file system support for
371 hard links.
372 slot_name
374 Physical replication slot to be used by the receive-wal command
375 when streaming_archiver is set to on. Requires PostgreSQL >=
376 9.4. Global/Server. Default: None (disabled).
377 ssh_command
379 Command used by Barman to login to the Postgres server via ssh.
380 Server.
381 streaming_archiver
383 This option allows you to use the PostgreSQL's streaming proto‐
384 col to receive transaction logs from a server. If set to on,
385 Barman expects to find pg_receivewal (known as pg_receivexlog
386 prior to PostgreSQL 10) in the PATH (see path_prefix option) and
387 that streaming connection for the server is working. This acti‐
388 vates connection checks as well as management (including com‐
389 pression) of WAL files. If set to off (default) barman will re‐
390 ly only on continuous archiving for a server WAL archive opera‐
391 tions, eventually terminating any running pg_receivexlog for the
392 server. Global/Server.
393 streaming_archiver_batch_size
395 This option allows you to activate batch processing of WAL files
396 for the streaming_archiver process, by setting it to a value >
397 0. Otherwise, the traditional unlimited processing of the WAL
398 queue is enabled. When batch processing is activated, the ar‐
399 chive-wal process would limit itself to maximum stream‐
400 ing_archiver_batch_size WAL segments per single run. Integer.
401 Global/Server.
402 streaming_archiver_name
404 Identifier to be used as application_name by the receive-wal
405 command. Only available with pg_receivewal (or pg_receivexlog
406 >= 9.3). By default it is set to barman_receive_wal. Glob‐
407 al/Server.
408 streaming_backup_name
410 Identifier to be used as application_name by the pg_basebackup
411 command. Only available with pg_basebackup >= 9.3. By default
412 it is set to barman_streaming_backup. Global/Server.
413 streaming_conninfo
415 Connection string used by Barman to connect to the Postgres
416 server via streaming replication protocol. By default it is set
417 to conninfo. Server.
418 streaming_wals_directory
420 Directory where WAL files are streamed from the PostgreSQL serv‐
421 er to Barman. Requires streaming_archiver to be enabled. Serv‐
422 er.
423 tablespace_bandwidth_limit
425 This option allows you to specify a maximum transfer rate in
426 kilobytes per second, by specifying a comma separated list of
427 tablespaces (pairs TBNAME:BWLIMIT). A value of zero specifies
428 no limit (default). Global/Server.
429 wal_retention_policy
431 Policy for retention of archive logs (WAL files). Currently on‐
432 ly "MAIN" is available. Global/Server.
433 wals_directory
435 Directory which contains WAL files. Server.
436
438 The script definition is passed to a shell and can return any exit
439 code.
440 The shell environment will contain the following variables:
442 BARMAN_CONFIGURATION
444 configuration file used by barman
445 BARMAN_ERROR
447 error message, if any (only for the 'post' phase)
448 BARMAN_PHASE
450 'pre' or 'post'
451 BARMAN_RETRY
453 1 if it is a retry script (from 1.5.0), 0 if not
454 BARMAN_SERVER
456 name of the server
457 Backup scripts specific variables:
459 BARMAN_BACKUP_DIR
461 backup destination directory
462 BARMAN_BACKUP_ID
464 ID of the backup
465 BARMAN_PREVIOUS_ID
467 ID of the previous backup (if present)
468 BARMAN_NEXT_ID
470 ID of the next backup (if present)
471 BARMAN_STATUS
473 status of the backup
474 BARMAN_VERSION
476 version of Barman
477 Archive scripts specific variables:
479 BARMAN_SEGMENT
481 name of the WAL file
482 BARMAN_FILE
484 full path of the WAL file
485 BARMAN_SIZE
487 size of the WAL file
488 BARMAN_TIMESTAMP
490 WAL file timestamp
491 BARMAN_COMPRESSION
493 type of compression used for the WAL file
494 Recovery scripts specific variables:
496 BARMAN_DESTINATION_DIRECTORY
498 the directory where the new instance is recovered
499 BARMAN_TABLESPACES
501 tablespace relocation map (JSON, if present)
502 BARMAN_REMOTE_COMMAND
504 secure shell command used by the recovery (if present)
505 BARMAN_RECOVER_OPTIONS
507 recovery additional options (JSON, if present)
508 Only in case of retry hook scripts, the exit code of the script is
510 checked by Barman. Output of hook scripts is simply written in the log
511 file.
512
514 Here is an example of configuration file:
515 [barman]
517 ; Main directory
518 barman_home = /var/lib/barman
519 ; System user
521 barman_user = barman
522 ; Log location
524 log_file = /var/log/barman/barman.log
525 ; Default compression level
527 ;compression = gzip
528 ; Incremental backup
530 reuse_backup = link
531 ; 'main' PostgreSQL Server configuration
533 [main]
534 ; Human readable description
535 description = "Main PostgreSQL Database"
536 ; SSH options
538 ssh_command = ssh postgres@pg
539 ; PostgreSQL connection string
541 conninfo = host=pg user=postgres
542 ; PostgreSQL streaming connection string
544 streaming_conninfo = host=pg user=postgres
545 ; Minimum number of required backups (redundancy)
547 minimum_redundancy = 1
548 ; Retention policy (based on redundancy)
550 retention_policy = REDUNDANCY 2
551
553 barman (1).
554
556 In alphabetical order:
557 · Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (architect)
559 · Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
561 · Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
563 · Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
565 · Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
567 · Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
569 · Britt Cole <britt.cole@2ndquadrant.com> (documentation)
571 · Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (project leader)
573 · Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
575 Past contributors:
577 · Carlo Ascani
579 · Stefano Bianucci
581 · Giuseppe Broccolo
583
585 · Homepage: <http://www.pgbarman.org/>
586 · Documentation: <http://docs.pgbarman.org/>
588 · Professional support: <https://www.2ndQuadrant.com/>
590
592 Barman is the property of 2ndQuadrant Limited and its code is distrib‐
593 uted under GNU General Public License v3.
594 Copyright (C) 2011-2018 2ndQuadrant Limited - https://www.2ndQuad‐
596 rant.com/.
597
599 2ndQuadrant Limited <https://www.2ndQuadrant.com>.
600Barman User manuals October 23, 2018 BARMAN(5)