1BARMAN(5) Version 2.10 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): barman
82 backup executes backup operations using the standard exclusive
83 backup approach (technically through pg_start_backup and
84 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 create_slot
145 When set to auto and slot_name is defined, Barman automatically
146 attempts to create the replication slot if not present. When
147 set to manual (default), the replication slot needs to be manu‐
148 ally created. Global/Server.
149 custom_compression_filter
151 Customised compression algorithm applied to WAL files. Glob‐
152 al/Server.
153 custom_decompression_filter
155 Customised decompression algorithm applied to compressed WAL
156 files; this must match the compression algorithm. Global/Serv‐
157 er.
158 description
160 A human readable description of a server. Server.
161 errors_directory
163 Directory that contains WAL files that contain an error; usually
164 this is related to a conflict with an existing WAL file (e.g. a
165 WAL file that has been archived after a streamed one).
166 immediate_checkpoint
168 This option allows you to control the way PostgreSQL handles
169 checkpoint at the start of the backup. If set to false (de‐
170 fault), the I/O workload for the checkpoint will be limited, ac‐
171 cording to the checkpoint_completion_target setting on the Post‐
172 greSQL server. If set to true, an immediate checkpoint will be
173 requested, meaning that PostgreSQL will complete the checkpoint
174 as soon as possible. Global/Server.
175 incoming_wals_directory
177 Directory where incoming WAL files are archived into. Requires
178 archiver to be enabled. Server.
179 last_backup_maximum_age
181 This option identifies a time frame that must contain the latest
182 backup. If the latest backup is older than the time frame, bar‐
183 man check command will report an error to the user. If empty
184 (default), latest backup is always considered valid. Syntax for
185 this option is: "i (DAYS | WEEKS | MONTHS)" where i is a integer
186 greater than zero, representing the number of days | weeks |
187 months of the time frame. Global/Server.
188 log_file
190 Location of Barman's log file. Global.
191 log_level
193 Level of logging (DEBUG, INFO, WARNING, ERROR, CRITICAL). Glob‐
194 al.
195 max_incoming_wals_queue
197 Maximum number of WAL files in the incoming queue (in both
198 streaming and archiving pools) that are allowed before barman
199 check returns an error (that does not block backups). Glob‐
200 al/Server. Default: None (disabled).
201 minimum_redundancy
203 Minimum number of backups to be retained. Default 0. Glob‐
204 al/Server.
205 network_compression
207 This option allows you to enable data compression for network
208 transfers. If set to false (default), no compression is used.
209 If set to true, compression is enabled, reducing network usage.
210 Global/Server.
211 parallel_jobs
213 This option controls how many parallel workers will copy files
214 during a backup or recovery command. Default 1. Global/Server.
215 For backup purposes, it works only when backup_method is rsync.
216 path_prefix
218 One or more absolute paths, separated by colon, where Barman
219 looks for executable files. The paths specified in path_prefix
220 are tried before the ones specified in PATH environment vari‐
221 able. Global/server.
222 post_archive_retry_script
224 Hook script launched after a WAL file is archived by mainte‐
225 nance. Being this a retry hook script, Barman will retry the
226 execution of the script until this either returns a SUCCESS (0),
227 an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. In a post
228 archive scenario, ABORT_STOP has currently the same effects as
229 ABORT_CONTINUE. Global/Server.
230 post_archive_script
232 Hook script launched after a WAL file is archived by mainte‐
233 nance, after 'post_archive_retry_script'. Global/Server.
234 post_backup_retry_script
236 Hook script launched after a base backup. Being this a retry
237 hook script, Barman will retry the execution of the script until
238 this either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
239 ABORT_STOP (63) code. In a post backup scenario, ABORT_STOP has
240 currently the same effects as ABORT_CONTINUE. Global/Server.
241 post_backup_script
243 Hook script launched after a base backup, after 'post_back‐
244 up_retry_script'. Global/Server.
245 post_delete_retry_script
247 Hook script launched after the deletion of a backup. Being this
248 a retry hook script, Barman will retry the execution of the
249 script until this either returns a SUCCESS (0), an ABORT_CONTIN‐
250 UE (62) or an ABORT_STOP (63) code. In a post delete scenario,
251 ABORT_STOP has currently the same effects as ABORT_CONTINUE.
252 Global/Server.
253 post_delete_script
255 Hook script launched after the deletion of a backup, after
256 'post_delete_retry_script'. Global/Server.
257 post_recovery_retry_script
259 Hook script launched after a recovery. Being this a retry hook
260 script, Barman will retry the execution of the script until this
261 either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
262 ABORT_STOP (63) code. In a post recovery scenario, ABORT_STOP
263 has currently the same effects as ABORT_CONTINUE. Global/Serv‐
264 er.
265 post_recovery_script
267 Hook script launched after a recovery, after 'post_recov‐
268 ery_retry_script'. Global/Server.
269 post_wal_delete_retry_script
271 Hook script launched after the deletion of a WAL file. Being
272 this a retry hook script, Barman will retry the execution of the
273 script until this either returns a SUCCESS (0), an ABORT_CONTIN‐
274 UE (62) or an ABORT_STOP (63) code. In a post delete scenario,
275 ABORT_STOP has currently the same effects as ABORT_CONTINUE.
276 Global/Server.
277 post_wal_delete_script
279 Hook script launched after the deletion of a WAL file, after
280 'post_wal)delete_retry_script'. Global/Server.
281 pre_archive_retry_script
283 Hook script launched before a WAL file is archived by mainte‐
284 nance, after 'pre_archive_script'. Being this a retry hook
285 script, Barman will retry the execution of the script until this
286 either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
287 ABORT_STOP (63) code. Returning ABORT_STOP will propagate the
288 failure at a higher level and interrupt the WAL archiving opera‐
289 tion. Global/Server.
290 pre_archive_script
292 Hook script launched before a WAL file is archived by mainte‐
293 nance. Global/Server.
294 pre_backup_retry_script
296 Hook script launched before a base backup, after 'pre_back‐
297 up_script'. Being this a retry hook script, Barman will retry
298 the execution of the script until this either returns a SUCCESS
299 (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. Return‐
300 ing ABORT_STOP will propagate the failure at a higher level and
301 interrupt the backup operation. Global/Server.
302 pre_backup_script
304 Hook script launched before a base backup. Global/Server.
305 pre_delete_retry_script
307 Hook script launched before the deletion of a backup, after
308 'pre_delete_script'. Being this a retry hook script, Barman
309 will retry the execution of the script until this either returns
310 a SUCCESS (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63)
311 code. Returning ABORT_STOP will propagate the failure at a
312 higher level and interrupt the backup deletion. Global/Server.
313 pre_delete_script
315 Hook script launched before the deletion of a backup. Glob‐
316 al/Server.
317 pre_recovery_retry_script
319 Hook script launched before a recovery, after 'pre_recov‐
320 ery_script'. Being this a retry hook script, Barman will retry
321 the execution of the script until this either returns a SUCCESS
322 (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. Return‐
323 ing ABORT_STOP will propagate the failure at a higher level and
324 interrupt the recover operation. Global/Server.
325 pre_recovery_script
327 Hook script launched before a recovery. Global/Server.
328 pre_wal_delete_retry_script
330 Hook script launched before the deletion of a WAL file, after
331 'pre_wal_delete_script'. Being this a retry hook script, Barman
332 will retry the execution of the script until this either returns
333 a SUCCESS (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63)
334 code. Returning ABORT_STOP will propagate the failure at a
335 higher level and interrupt the WAL file deletion. Global/Serv‐
336 er.
337 pre_wal_delete_script
339 Hook script launched before the deletion of a WAL file. Glob‐
340 al/Server.
341 primary_ssh_command
343 Parameter that identifies a Barman server as passive. In a pas‐
344 sive node, the source of a backup server is a Barman installa‐
345 tion rather than a PostgreSQL server. If primary_ssh_command is
346 specified, Barman uses it to establish a connection with the
347 primary server. Empty by default, it can also be set globally.
348 recovery_options
350 Options for recovery operations. Currently only supports get-
351 wal. get-wal activates generation of a basic restore_command in
352 the resulting recovery configuration that uses the barman get-
353 wal command to fetch WAL files directly from Barman's archive of
354 WALs. Comma separated list of values, default empty. Glob‐
355 al/Server.
356 retention_policy
358 Policy for retention of periodic backups and archive logs. If
359 left empty, retention policies are not enforced. For redundancy
360 based retention policy use "REDUNDANCY i" (where i is an integer
361 > 0 and defines the number of backups to retain). For recovery
362 window retention policy use "RECOVERY WINDOW OF i DAYS" or "RE‐
363 COVERY WINDOW OF i WEEKS" or "RECOVERY WINDOW OF i MONTHS" where
364 i is a positive integer representing, specifically, the number
365 of days, weeks or months to retain your backups. For more de‐
366 tailed information, refer to the official documentation. De‐
367 fault value is empty. Global/Server.
368 retention_policy_mode
370 Currently only "auto" is implemented. Global/Server.
371 reuse_backup
373 This option controls incremental backup support. Global/Server.
374 Possible values are:
375 · off: disabled (default);
377 · copy: reuse the last available backup for a server and create
379 a copy of the unchanged files (reduce backup time);
380 · link: reuse the last available backup for a server and create
382 a hard link of the unchanged files (reduce backup time and
383 space). Requires operating system and file system support for
384 hard links.
385 slot_name
387 Physical replication slot to be used by the receive-wal command
388 when streaming_archiver is set to on. Requires PostgreSQL >=
389 9.4. Global/Server. Default: None (disabled).
390 ssh_command
392 Command used by Barman to login to the Postgres server via ssh.
393 Server.
394 streaming_archiver
396 This option allows you to use the PostgreSQL's streaming proto‐
397 col to receive transaction logs from a server. If set to on,
398 Barman expects to find pg_receivewal (known as pg_receivexlog
399 prior to PostgreSQL 10) in the PATH (see path_prefix option) and
400 that streaming connection for the server is working. This acti‐
401 vates connection checks as well as management (including com‐
402 pression) of WAL files. If set to off (default) barman will re‐
403 ly only on continuous archiving for a server WAL archive opera‐
404 tions, eventually terminating any running pg_receivexlog for the
405 server. Global/Server.
406 streaming_archiver_batch_size
408 This option allows you to activate batch processing of WAL files
409 for the streaming_archiver process, by setting it to a value >
410 0. Otherwise, the traditional unlimited processing of the WAL
411 queue is enabled. When batch processing is activated, the ar‐
412 chive-wal process would limit itself to maximum stream‐
413 ing_archiver_batch_size WAL segments per single run. Integer.
414 Global/Server.
415 streaming_archiver_name
417 Identifier to be used as application_name by the receive-wal
418 command. Only available with pg_receivewal (or pg_receivexlog
419 >= 9.3). By default it is set to barman_receive_wal. Glob‐
420 al/Server.
421 streaming_backup_name
423 Identifier to be used as application_name by the pg_basebackup
424 command. Only available with pg_basebackup >= 9.3. By default
425 it is set to barman_streaming_backup. Global/Server.
426 streaming_conninfo
428 Connection string used by Barman to connect to the Postgres
429 server via streaming replication protocol. By default it is set
430 to conninfo. Server.
431 streaming_wals_directory
433 Directory where WAL files are streamed from the PostgreSQL serv‐
434 er to Barman. Requires streaming_archiver to be enabled. Serv‐
435 er.
436 tablespace_bandwidth_limit
438 This option allows you to specify a maximum transfer rate in
439 kilobytes per second, by specifying a comma separated list of
440 tablespaces (pairs TBNAME:BWLIMIT). A value of zero specifies
441 no limit (default). Global/Server.
442 wal_retention_policy
444 Policy for retention of archive logs (WAL files). Currently on‐
445 ly "MAIN" is available. Global/Server.
446 wals_directory
448 Directory which contains WAL files. Server.
449
451 The script definition is passed to a shell and can return any exit
452 code.
453 The shell environment will contain the following variables:
455 BARMAN_CONFIGURATION
457 configuration file used by barman
458 BARMAN_ERROR
460 error message, if any (only for the 'post' phase)
461 BARMAN_PHASE
463 'pre' or 'post'
464 BARMAN_RETRY
466 1 if it is a retry script (from 1.5.0), 0 if not
467 BARMAN_SERVER
469 name of the server
470 Backup scripts specific variables:
472 BARMAN_BACKUP_DIR
474 backup destination directory
475 BARMAN_BACKUP_ID
477 ID of the backup
478 BARMAN_PREVIOUS_ID
480 ID of the previous backup (if present)
481 BARMAN_NEXT_ID
483 ID of the next backup (if present)
484 BARMAN_STATUS
486 status of the backup
487 BARMAN_VERSION
489 version of Barman
490 Archive scripts specific variables:
492 BARMAN_SEGMENT
494 name of the WAL file
495 BARMAN_FILE
497 full path of the WAL file
498 BARMAN_SIZE
500 size of the WAL file
501 BARMAN_TIMESTAMP
503 WAL file timestamp
504 BARMAN_COMPRESSION
506 type of compression used for the WAL file
507 Recovery scripts specific variables:
509 BARMAN_DESTINATION_DIRECTORY
511 the directory where the new instance is recovered
512 BARMAN_TABLESPACES
514 tablespace relocation map (JSON, if present)
515 BARMAN_REMOTE_COMMAND
517 secure shell command used by the recovery (if present)
518 BARMAN_RECOVER_OPTIONS
520 recovery additional options (JSON, if present)
521 Only in case of retry hook scripts, the exit code of the script is
523 checked by Barman. Output of hook scripts is simply written in the log
524 file.
525
527 Here is an example of configuration file:
528 [barman]
530 ; Main directory
531 barman_home = /var/lib/barman
532 ; System user
534 barman_user = barman
535 ; Log location
537 log_file = /var/log/barman/barman.log
538 ; Default compression level
540 ;compression = gzip
541 ; Incremental backup
543 reuse_backup = link
544 ; 'main' PostgreSQL Server configuration
546 [main]
547 ; Human readable description
548 description = "Main PostgreSQL Database"
549 ; SSH options
551 ssh_command = ssh postgres@pg
552 ; PostgreSQL connection string
554 conninfo = host=pg user=postgres
555 ; PostgreSQL streaming connection string
557 streaming_conninfo = host=pg user=postgres
558 ; Minimum number of required backups (redundancy)
560 minimum_redundancy = 1
561 ; Retention policy (based on redundancy)
563 retention_policy = REDUNDANCY 2
564
566 barman (1).
567
569 In alphabetical order:
570 · Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (architect)
572 · Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
574 · Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
576 · Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
578 · Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
580 · Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
582 · Britt Cole <britt.cole@2ndquadrant.com> (documentation)
584 · Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (project leader)
586 · Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
588 Past contributors:
590 · Carlo Ascani
592 · Stefano Bianucci
594 · Giuseppe Broccolo
596
598 · Homepage: <http://www.pgbarman.org/>
599 · Documentation: <http://docs.pgbarman.org/>
601 · Professional support: <https://www.2ndQuadrant.com/>
603
605 Barman is the property of 2ndQuadrant Limited and its code is distrib‐
606 uted under GNU General Public License v3.
607 Copyright (C) 2011-2019 2ndQuadrant Limited - https://www.2ndQuad‐
609 rant.com/.
610
612 2ndQuadrant Limited <https://www.2ndQuadrant.com>.
613Barman User manuals December 5, 2019 BARMAN(5)