1BARMAN(5) Version 2.8 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 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 primary_ssh_command
337 Parameter that identifies a Barman server as passive. In a pas‐
338 sive node, the source of a backup server is a Barman installa‐
339 tion rather than a PostgreSQL server. If primary_ssh_command is
340 specified, Barman uses it to establish a connection with the
341 primary server. Empty by default, it can also be set globally.
342 recovery_options
344 Options for recovery operations. Currently only supports get-
345 wal. get-wal activates generation of a basic restore_command in
346 the resulting recovery.conf file that uses the barman get-wal
347 command to fetch WAL files directly from Barman’s archive of
348 WALs. Comma separated list of values, default empty. Glob‐
349 al/Server.
350 retention_policy
352 Policy for retention of periodic backups and archive logs. If
353 left empty, retention policies are not enforced. For redundancy
354 based retention policy use “REDUNDANCY i” (where i is an integer
355 > 0 and defines the number of backups to retain). For recovery
356 window retention policy use “RECOVERY WINDOW OF i DAYS” or “RE‐
357 COVERY WINDOW OF i WEEKS” or “RECOVERY WINDOW OF i MONTHS” where
358 i is a positive integer representing, specifically, the number
359 of days, weeks or months to retain your backups. For more de‐
360 tailed information, refer to the official documentation. De‐
361 fault value is empty. Global/Server.
362 retention_policy_mode
364 Currently only “auto” is implemented. Global/Server.
365 reuse_backup
367 This option controls incremental backup support. Global/Server.
368 Possible values are:
369 · off: disabled (default);
371 · copy: reuse the last available backup for a server and create
373 a copy of the unchanged files (reduce backup time);
374 · link: reuse the last available backup for a server and create
376 a hard link of the unchanged files (reduce backup time and
377 space). Requires operating system and file system support for
378 hard links.
379 slot_name
381 Physical replication slot to be used by the receive-wal command
382 when streaming_archiver is set to on. Requires PostgreSQL >=
383 9.4. Global/Server. Default: None (disabled).
384 ssh_command
386 Command used by Barman to login to the Postgres server via ssh.
387 Server.
388 streaming_archiver
390 This option allows you to use the PostgreSQL’s streaming proto‐
391 col to receive transaction logs from a server. If set to on,
392 Barman expects to find pg_receivewal (known as pg_receivexlog
393 prior to PostgreSQL 10) in the PATH (see path_prefix option) and
394 that streaming connection for the server is working. This acti‐
395 vates connection checks as well as management (including com‐
396 pression) of WAL files. If set to off (default) barman will re‐
397 ly only on continuous archiving for a server WAL archive opera‐
398 tions, eventually terminating any running pg_receivexlog for the
399 server. Global/Server.
400 streaming_archiver_batch_size
402 This option allows you to activate batch processing of WAL files
403 for the streaming_archiver process, by setting it to a value >
404 0. Otherwise, the traditional unlimited processing of the WAL
405 queue is enabled. When batch processing is activated, the ar‐
406 chive-wal process would limit itself to maximum stream‐
407 ing_archiver_batch_size WAL segments per single run. Integer.
408 Global/Server.
409 streaming_archiver_name
411 Identifier to be used as application_name by the receive-wal
412 command. Only available with pg_receivewal (or pg_receivexlog
413 >= 9.3). By default it is set to barman_receive_wal. Glob‐
414 al/Server.
415 streaming_backup_name
417 Identifier to be used as application_name by the pg_basebackup
418 command. Only available with pg_basebackup >= 9.3. By default
419 it is set to barman_streaming_backup. Global/Server.
420 streaming_conninfo
422 Connection string used by Barman to connect to the Postgres
423 server via streaming replication protocol. By default it is set
424 to conninfo. Server.
425 streaming_wals_directory
427 Directory where WAL files are streamed from the PostgreSQL serv‐
428 er to Barman. Requires streaming_archiver to be enabled. Serv‐
429 er.
430 tablespace_bandwidth_limit
432 This option allows you to specify a maximum transfer rate in
433 kilobytes per second, by specifying a comma separated list of
434 tablespaces (pairs TBNAME:BWLIMIT). A value of zero specifies
435 no limit (default). Global/Server.
436 wal_retention_policy
438 Policy for retention of archive logs (WAL files). Currently on‐
439 ly “MAIN” is available. Global/Server.
440 wals_directory
442 Directory which contains WAL files. Server.
443
445 The script definition is passed to a shell and can return any exit
446 code.
447 The shell environment will contain the following variables:
449 BARMAN_CONFIGURATION
451 configuration file used by barman
452 BARMAN_ERROR
454 error message, if any (only for the `post' phase)
455 BARMAN_PHASE
457 `pre' or `post'
458 BARMAN_RETRY
460 1 if it is a retry script (from 1.5.0), 0 if not
461 BARMAN_SERVER
463 name of the server
464 Backup scripts specific variables:
466 BARMAN_BACKUP_DIR
468 backup destination directory
469 BARMAN_BACKUP_ID
471 ID of the backup
472 BARMAN_PREVIOUS_ID
474 ID of the previous backup (if present)
475 BARMAN_NEXT_ID
477 ID of the next backup (if present)
478 BARMAN_STATUS
480 status of the backup
481 BARMAN_VERSION
483 version of Barman
484 Archive scripts specific variables:
486 BARMAN_SEGMENT
488 name of the WAL file
489 BARMAN_FILE
491 full path of the WAL file
492 BARMAN_SIZE
494 size of the WAL file
495 BARMAN_TIMESTAMP
497 WAL file timestamp
498 BARMAN_COMPRESSION
500 type of compression used for the WAL file
501 Recovery scripts specific variables:
503 BARMAN_DESTINATION_DIRECTORY
505 the directory where the new instance is recovered
506 BARMAN_TABLESPACES
508 tablespace relocation map (JSON, if present)
509 BARMAN_REMOTE_COMMAND
511 secure shell command used by the recovery (if present)
512 BARMAN_RECOVER_OPTIONS
514 recovery additional options (JSON, if present)
515 Only in case of retry hook scripts, the exit code of the script is
517 checked by Barman. Output of hook scripts is simply written in the log
518 file.
519
521 Here is an example of configuration file:
522 [barman]
524 ; Main directory
525 barman_home = /var/lib/barman
526 ; System user
528 barman_user = barman
529 ; Log location
531 log_file = /var/log/barman/barman.log
532 ; Default compression level
534 ;compression = gzip
535 ; Incremental backup
537 reuse_backup = link
538 ; 'main' PostgreSQL Server configuration
540 [main]
541 ; Human readable description
542 description = "Main PostgreSQL Database"
543 ; SSH options
545 ssh_command = ssh postgres@pg
546 ; PostgreSQL connection string
548 conninfo = host=pg user=postgres
549 ; PostgreSQL streaming connection string
551 streaming_conninfo = host=pg user=postgres
552 ; Minimum number of required backups (redundancy)
554 minimum_redundancy = 1
555 ; Retention policy (based on redundancy)
557 retention_policy = REDUNDANCY 2
558
560 barman (1).
561
563 In alphabetical order:
564 · Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (architect)
566 · Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
568 · Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
570 · Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
572 · Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
574 · Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
576 · Britt Cole <britt.cole@2ndquadrant.com> (documentation)
578 · Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (project leader)
580 · Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
582 Past contributors:
584 · Carlo Ascani
586 · Stefano Bianucci
588 · Giuseppe Broccolo
590
592 · Homepage: <http://www.pgbarman.org/>
593 · Documentation: <http://docs.pgbarman.org/>
595 · Professional support: <https://www.2ndQuadrant.com/>
597
599 Barman is the property of 2ndQuadrant Limited and its code is distrib‐
600 uted under GNU General Public License v3.
601 Copyright (C) 2011-2019 2ndQuadrant Limited - https://www.2ndQuad‐
603 rant.com/.
604
606 2ndQuadrant Limited <https://www.2ndQuadrant.com>.
607Barman User manuals May 17, 2019 BARMAN(5)