1BARMAN(5) Version 2.12 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 over SSH (requires ssh_command). If set to postgres
74 barman will use the pg_basebackup command to execute the backup.
75 If set to local-rsync, barman will assume to be running on the
76 same server as the the PostgreSQL instance and with the same us‐
77 er, then execute rsync for the file system copy. Global/Server.
78 backup_options
80 This option allows you to control the way Barman interacts with
81 PostgreSQL for backups. It is a comma-separated list of values
82 that accepts the following options:
83 · exclusive_backup (default when backup_method = rsync): barman
85 backup executes backup operations using the standard exclusive
86 backup approach (technically through pg_start_backup and
87 pg_stop_backup)
88 · concurrent_backup (default when backup_method = postgres): if
90 using PostgreSQL 9.2, 9.3, 9.4, and 9.5, Barman requires the
91 pgespresso module to be installed on the PostgreSQL server and
92 can be used to perform a backup from a standby server. Start‐
93 ing from PostgreSQL 9.6, Barman uses the new PostgreSQL API to
94 perform backups from a standby server.
95 · external_configuration: if present, any warning regarding ex‐
97 ternal configuration files is suppressed during the execution
98 of a backup.
99 Note that exclusive_backup and concurrent_backup are mutually
101 exclusive. Global/Server.
102 bandwidth_limit
104 This option allows you to specify a maximum transfer rate in
105 kilobytes per second. A value of zero specifies no limit (de‐
106 fault). Global/Server.
107 barman_home
109 Main data directory for Barman. Global.
110 barman_lock_directory
112 Directory for locks. Default: %(barman_home)s. Global.
113 basebackup_retry_sleep
115 Number of seconds of wait after a failed copy, before retrying
116 Used during both backup and recovery operations. Positive inte‐
117 ger, default 30. Global/Server.
118 basebackup_retry_times
120 Number of retries of base backup copy, after an error. Used
121 during both backup and recovery operations. Positive integer,
122 default 0. Global/Server.
123 basebackups_directory
125 Directory where base backups will be placed. Server.
126 check_timeout
128 Maximum execution time, in seconds per server, for a barman
129 check command. Set to 0 to disable the timeout. Positive inte‐
130 ger, default 30. Global/Server.
131 compression
133 Standard compression algorithm applied to WAL files. Possible
134 values are: gzip (requires gzip to be installed on the system),
135 bzip2 (requires bzip2), pigz (requires pigz), pygzip (Python's
136 internal gzip compressor) and pybzip2 (Python's internal bzip2
137 compressor). Global/Server.
138 conninfo
140 Connection string used by Barman to connect to the Postgres
141 server. This is a libpq connection string, consult the Post‐
142 greSQL manual (https://www.postgresql.org/docs/current/stat‐
143 ic/libpq-connect.html#LIBPQ-CONNSTRING) for more information.
144 Commonly used keys are: host, hostaddr, port, dbname, user,
145 password. Server.
146 create_slot
148 When set to auto and slot_name is defined, Barman automatically
149 attempts to create the replication slot if not present. When
150 set to manual (default), the replication slot needs to be manu‐
151 ally created. Global/Server.
152 custom_compression_filter
154 Customised compression algorithm applied to WAL files. Glob‐
155 al/Server.
156 custom_decompression_filter
158 Customised decompression algorithm applied to compressed WAL
159 files; this must match the compression algorithm. Global/Serv‐
160 er.
161 description
163 A human readable description of a server. Server.
164 errors_directory
166 Directory that contains WAL files that contain an error; usually
167 this is related to a conflict with an existing WAL file (e.g. a
168 WAL file that has been archived after a streamed one).
169 immediate_checkpoint
171 This option allows you to control the way PostgreSQL handles
172 checkpoint at the start of the backup. If set to false (de‐
173 fault), the I/O workload for the checkpoint will be limited, ac‐
174 cording to the checkpoint_completion_target setting on the Post‐
175 greSQL server. If set to true, an immediate checkpoint will be
176 requested, meaning that PostgreSQL will complete the checkpoint
177 as soon as possible. Global/Server.
178 incoming_wals_directory
180 Directory where incoming WAL files are archived into. Requires
181 archiver to be enabled. Server.
182 last_backup_maximum_age
184 This option identifies a time frame that must contain the latest
185 backup. If the latest backup is older than the time frame, bar‐
186 man check command will report an error to the user. If empty
187 (default), latest backup is always considered valid. Syntax for
188 this option is: "i (DAYS | WEEKS | MONTHS)" where i is a integer
189 greater than zero, representing the number of days | weeks |
190 months of the time frame. Global/Server.
191 log_file
193 Location of Barman's log file. Global.
194 log_level
196 Level of logging (DEBUG, INFO, WARNING, ERROR, CRITICAL). Glob‐
197 al.
198 max_incoming_wals_queue
200 Maximum number of WAL files in the incoming queue (in both
201 streaming and archiving pools) that are allowed before barman
202 check returns an error (that does not block backups). Glob‐
203 al/Server. Default: None (disabled).
204 minimum_redundancy
206 Minimum number of backups to be retained. Default 0. Glob‐
207 al/Server.
208 network_compression
210 This option allows you to enable data compression for network
211 transfers. If set to false (default), no compression is used.
212 If set to true, compression is enabled, reducing network usage.
213 Global/Server.
214 parallel_jobs
216 This option controls how many parallel workers will copy files
217 during a backup or recovery command. Default 1. Global/Server.
218 For backup purposes, it works only when backup_method is rsync.
219 path_prefix
221 One or more absolute paths, separated by colon, where Barman
222 looks for executable files. The paths specified in path_prefix
223 are tried before the ones specified in PATH environment vari‐
224 able. Global/server.
225 post_archive_retry_script
227 Hook script launched after a WAL file is archived by mainte‐
228 nance. Being this a retry hook script, Barman will retry the
229 execution of the script until this either returns a SUCCESS (0),
230 an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. In a post
231 archive scenario, ABORT_STOP has currently the same effects as
232 ABORT_CONTINUE. Global/Server.
233 post_archive_script
235 Hook script launched after a WAL file is archived by mainte‐
236 nance, after 'post_archive_retry_script'. Global/Server.
237 post_backup_retry_script
239 Hook script launched after a base backup. Being this a retry
240 hook script, Barman will retry the execution of the script until
241 this either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
242 ABORT_STOP (63) code. In a post backup scenario, ABORT_STOP has
243 currently the same effects as ABORT_CONTINUE. Global/Server.
244 post_backup_script
246 Hook script launched after a base backup, after 'post_back‐
247 up_retry_script'. Global/Server.
248 post_delete_retry_script
250 Hook script launched after the deletion of a backup. Being this
251 a retry hook script, Barman will retry the execution of the
252 script until this either returns a SUCCESS (0), an ABORT_CONTIN‐
253 UE (62) or an ABORT_STOP (63) code. In a post delete scenario,
254 ABORT_STOP has currently the same effects as ABORT_CONTINUE.
255 Global/Server.
256 post_delete_script
258 Hook script launched after the deletion of a backup, after
259 'post_delete_retry_script'. Global/Server.
260 post_recovery_retry_script
262 Hook script launched after a recovery. Being this a retry hook
263 script, Barman will retry the execution of the script until this
264 either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
265 ABORT_STOP (63) code. In a post recovery scenario, ABORT_STOP
266 has currently the same effects as ABORT_CONTINUE. Global/Serv‐
267 er.
268 post_recovery_script
270 Hook script launched after a recovery, after 'post_recov‐
271 ery_retry_script'. Global/Server.
272 post_wal_delete_retry_script
274 Hook script launched after the deletion of a WAL file. Being
275 this a retry hook script, Barman will retry the execution of the
276 script until this either returns a SUCCESS (0), an ABORT_CONTIN‐
277 UE (62) or an ABORT_STOP (63) code. In a post delete scenario,
278 ABORT_STOP has currently the same effects as ABORT_CONTINUE.
279 Global/Server.
280 post_wal_delete_script
282 Hook script launched after the deletion of a WAL file, after
283 'post_wal)delete_retry_script'. Global/Server.
284 pre_archive_retry_script
286 Hook script launched before a WAL file is archived by mainte‐
287 nance, after 'pre_archive_script'. Being this a retry hook
288 script, Barman will retry the execution of the script until this
289 either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
290 ABORT_STOP (63) code. Returning ABORT_STOP will propagate the
291 failure at a higher level and interrupt the WAL archiving opera‐
292 tion. Global/Server.
293 pre_archive_script
295 Hook script launched before a WAL file is archived by mainte‐
296 nance. Global/Server.
297 pre_backup_retry_script
299 Hook script launched before a base backup, after 'pre_back‐
300 up_script'. Being this a retry hook script, Barman will retry
301 the execution of the script until this either returns a SUCCESS
302 (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. Return‐
303 ing ABORT_STOP will propagate the failure at a higher level and
304 interrupt the backup operation. Global/Server.
305 pre_backup_script
307 Hook script launched before a base backup. Global/Server.
308 pre_delete_retry_script
310 Hook script launched before the deletion of a backup, after
311 'pre_delete_script'. Being this a retry hook script, Barman
312 will retry the execution of the script until this either returns
313 a SUCCESS (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63)
314 code. Returning ABORT_STOP will propagate the failure at a
315 higher level and interrupt the backup deletion. Global/Server.
316 pre_delete_script
318 Hook script launched before the deletion of a backup. Glob‐
319 al/Server.
320 pre_recovery_retry_script
322 Hook script launched before a recovery, after 'pre_recov‐
323 ery_script'. Being this a retry hook script, Barman will retry
324 the execution of the script until this either returns a SUCCESS
325 (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. Return‐
326 ing ABORT_STOP will propagate the failure at a higher level and
327 interrupt the recover operation. Global/Server.
328 pre_recovery_script
330 Hook script launched before a recovery. Global/Server.
331 pre_wal_delete_retry_script
333 Hook script launched before the deletion of a WAL file, after
334 'pre_wal_delete_script'. Being this a retry hook script, Barman
335 will retry the execution of the script until this either returns
336 a SUCCESS (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63)
337 code. Returning ABORT_STOP will propagate the failure at a
338 higher level and interrupt the WAL file deletion. Global/Serv‐
339 er.
340 pre_wal_delete_script
342 Hook script launched before the deletion of a WAL file. Glob‐
343 al/Server.
344 primary_ssh_command
346 Parameter that identifies a Barman server as passive. In a pas‐
347 sive node, the source of a backup server is a Barman installa‐
348 tion rather than a PostgreSQL server. If primary_ssh_command is
349 specified, Barman uses it to establish a connection with the
350 primary server. Empty by default, it can also be set globally.
351 recovery_options
353 Options for recovery operations. Currently only supports get-
354 wal. get-wal activates generation of a basic restore_command in
355 the resulting recovery configuration that uses the barman get-
356 wal command to fetch WAL files directly from Barman's archive of
357 WALs. Comma separated list of values, default empty. Glob‐
358 al/Server.
359 retention_policy
361 Policy for retention of periodic backups and archive logs. If
362 left empty, retention policies are not enforced. For redundancy
363 based retention policy use "REDUNDANCY i" (where i is an integer
364 > 0 and defines the number of backups to retain). For recovery
365 window retention policy use "RECOVERY WINDOW OF i DAYS" or "RE‐
366 COVERY WINDOW OF i WEEKS" or "RECOVERY WINDOW OF i MONTHS" where
367 i is a positive integer representing, specifically, the number
368 of days, weeks or months to retain your backups. For more de‐
369 tailed information, refer to the official documentation. De‐
370 fault value is empty. Global/Server.
371 retention_policy_mode
373 Currently only "auto" is implemented. Global/Server.
374 reuse_backup
376 This option controls incremental backup support. Global/Server.
377 Possible values are:
378 · off: disabled (default);
380 · copy: reuse the last available backup for a server and create
382 a copy of the unchanged files (reduce backup time);
383 · link: reuse the last available backup for a server and create
385 a hard link of the unchanged files (reduce backup time and
386 space). Requires operating system and file system support for
387 hard links.
388 slot_name
390 Physical replication slot to be used by the receive-wal command
391 when streaming_archiver is set to on. Requires PostgreSQL >=
392 9.4. Global/Server. Default: None (disabled).
393 ssh_command
395 Command used by Barman to login to the Postgres server via ssh.
396 Server.
397 streaming_archiver
399 This option allows you to use the PostgreSQL's streaming proto‐
400 col to receive transaction logs from a server. If set to on,
401 Barman expects to find pg_receivewal (known as pg_receivexlog
402 prior to PostgreSQL 10) in the PATH (see path_prefix option) and
403 that streaming connection for the server is working. This acti‐
404 vates connection checks as well as management (including com‐
405 pression) of WAL files. If set to off (default) barman will re‐
406 ly only on continuous archiving for a server WAL archive opera‐
407 tions, eventually terminating any running pg_receivexlog for the
408 server. Global/Server.
409 streaming_archiver_batch_size
411 This option allows you to activate batch processing of WAL files
412 for the streaming_archiver process, by setting it to a value >
413 0. Otherwise, the traditional unlimited processing of the WAL
414 queue is enabled. When batch processing is activated, the ar‐
415 chive-wal process would limit itself to maximum stream‐
416 ing_archiver_batch_size WAL segments per single run. Integer.
417 Global/Server.
418 streaming_archiver_name
420 Identifier to be used as application_name by the receive-wal
421 command. Only available with pg_receivewal (or pg_receivexlog
422 >= 9.3). By default it is set to barman_receive_wal. Glob‐
423 al/Server.
424 streaming_backup_name
426 Identifier to be used as application_name by the pg_basebackup
427 command. Only available with pg_basebackup >= 9.3. By default
428 it is set to barman_streaming_backup. Global/Server.
429 streaming_conninfo
431 Connection string used by Barman to connect to the Postgres
432 server via streaming replication protocol. By default it is set
433 to conninfo. Server.
434 streaming_wals_directory
436 Directory where WAL files are streamed from the PostgreSQL serv‐
437 er to Barman. Requires streaming_archiver to be enabled. Serv‐
438 er.
439 tablespace_bandwidth_limit
441 This option allows you to specify a maximum transfer rate in
442 kilobytes per second, by specifying a comma separated list of
443 tablespaces (pairs TBNAME:BWLIMIT). A value of zero specifies
444 no limit (default). Global/Server.
445 wal_retention_policy
447 Policy for retention of archive logs (WAL files). Currently on‐
448 ly "MAIN" is available. Global/Server.
449 wals_directory
451 Directory which contains WAL files. Server.
452
454 The script definition is passed to a shell and can return any exit
455 code.
456 The shell environment will contain the following variables:
458 BARMAN_CONFIGURATION
460 configuration file used by barman
461 BARMAN_ERROR
463 error message, if any (only for the 'post' phase)
464 BARMAN_PHASE
466 'pre' or 'post'
467 BARMAN_RETRY
469 1 if it is a retry script (from 1.5.0), 0 if not
470 BARMAN_SERVER
472 name of the server
473 Backup scripts specific variables:
475 BARMAN_BACKUP_DIR
477 backup destination directory
478 BARMAN_BACKUP_ID
480 ID of the backup
481 BARMAN_PREVIOUS_ID
483 ID of the previous backup (if present)
484 BARMAN_NEXT_ID
486 ID of the next backup (if present)
487 BARMAN_STATUS
489 status of the backup
490 BARMAN_VERSION
492 version of Barman
493 Archive scripts specific variables:
495 BARMAN_SEGMENT
497 name of the WAL file
498 BARMAN_FILE
500 full path of the WAL file
501 BARMAN_SIZE
503 size of the WAL file
504 BARMAN_TIMESTAMP
506 WAL file timestamp
507 BARMAN_COMPRESSION
509 type of compression used for the WAL file
510 Recovery scripts specific variables:
512 BARMAN_DESTINATION_DIRECTORY
514 the directory where the new instance is recovered
515 BARMAN_TABLESPACES
517 tablespace relocation map (JSON, if present)
518 BARMAN_REMOTE_COMMAND
520 secure shell command used by the recovery (if present)
521 BARMAN_RECOVER_OPTIONS
523 recovery additional options (JSON, if present)
524 Only in case of retry hook scripts, the exit code of the script is
526 checked by Barman. Output of hook scripts is simply written in the log
527 file.
528
530 Here is an example of configuration file:
531 [barman]
533 ; Main directory
534 barman_home = /var/lib/barman
535 ; System user
537 barman_user = barman
538 ; Log location
540 log_file = /var/log/barman/barman.log
541 ; Default compression level
543 ;compression = gzip
544 ; Incremental backup
546 reuse_backup = link
547 ; 'main' PostgreSQL Server configuration
549 [main]
550 ; Human readable description
551 description = "Main PostgreSQL Database"
552 ; SSH options
554 ssh_command = ssh postgres@pg
555 ; PostgreSQL connection string
557 conninfo = host=pg user=postgres
558 ; PostgreSQL streaming connection string
560 streaming_conninfo = host=pg user=postgres
561 ; Minimum number of required backups (redundancy)
563 minimum_redundancy = 1
564 ; Retention policy (based on redundancy)
566 retention_policy = REDUNDANCY 2
567
569 barman (1).
570
572 In alphabetical order:
573 · Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (architect)
575 · Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
577 · Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
579 · Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
581 · Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
583 · Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
585 · Britt Cole <britt.cole@2ndquadrant.com> (documentation)
587 · Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (project leader)
589 · Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
591 Past contributors:
593 · Carlo Ascani
595 · Stefano Bianucci
597 · Giuseppe Broccolo
599
601 · Homepage: <http://www.pgbarman.org/>
602 · Documentation: <http://docs.pgbarman.org/>
604 · Professional support: <https://www.2ndQuadrant.com/>
606
608 Barman is the property of 2ndQuadrant Limited and its code is distrib‐
609 uted under GNU General Public License v3.
610 Copyright (C) 2011-2020 2ndQuadrant Limited - https://www.2ndQuad‐
612 rant.com/.
613
615 2ndQuadrant Limited <https://www.2ndQuadrant.com>.
616Barman User manuals November 5, 2020 BARMAN(5)