1BARMAN(5) Version 3.0.1 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 EnterpriseDB. 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. When adding a new server
47 to Barman, we suggest setting active=false at first, making sure
48 that barman check shows no problems, and only then activating
49 the server. This will avoid spamming the Barman logs with er‐
50 rors during the initial setup.
51 archiver
53 This option allows you to activate log file shipping through
54 PostgreSQL's archive_command for a server. If set to true (de‐
55 fault), Barman expects that continuous archiving for a server is
56 in place and will activate checks as well as management (includ‐
57 ing compression) of WAL files that Postgres deposits in the in‐
58 coming directory. Setting it to false, will disable standard
59 continuous archiving for a server. Global/Server.
60 archiver_batch_size
62 This option allows you to activate batch processing of WAL files
63 for the archiver process, by setting it to a value > 0. Other‐
64 wise, the traditional unlimited processing of the WAL queue is
65 enabled. When batch processing is activated, the archive-wal
66 process would limit itself to maximum archiver_batch_size WAL
67 segments per single run. Integer. Global/Server.
68 backup_compression
70 The compression to be used during the backup process. Only sup‐
71 ported when backup_method = postgres. Can either be unset or
72 gzip. If unset then no compression will be used during the
73 backup. Global/Server.
74 backup_compression_format
76 The format pg_basebackup should use when writing compressed
77 backups to disk. Can be set to either plain or tar. If unset
78 then a default of tar is assumed. The value plain can only be
79 used if the server is running PostgreSQL 15 or later and if
80 backup_compression_location is server. Only supported when
81 backup_method = postgres. Global/Server.
82 backup_compression_level
84 An integer value representing the compression level to use when
85 compressing backups. Allowed values depend on the compression
86 algorithm specified by backup_compression. Only supported when
87 backup_method = postgres. Global/Server.
88 backup_compression_location
90 The location (either client or server) where compression should
91 be performed during the backup. The value server is only al‐
92 lowed if the server is running PostgreSQL 15 or later. Glob‐
93 al/Server.
94 backup_directory
96 Directory where backup data for a server will be placed. Serv‐
97 er.
98 backup_method
100 Configure the method barman used for backup execution. If set
101 to rsync (default), barman will execute backup using the rsync
102 command over SSH (requires ssh_command). If set to postgres
103 barman will use the pg_basebackup command to execute the backup.
104 If set to local-rsync, barman will assume to be running on the
105 same server as the the PostgreSQL instance and with the same us‐
106 er, then execute rsync for the file system copy. Global/Server.
107 backup_options
109 This option allows you to control the way Barman interacts with
110 PostgreSQL for backups. It is a comma-separated list of values
111 that accepts the following options:
112 • concurrent_backup (default): barman backup executes backup op‐
114 erations using concurrent backup which is the recommended
115 backup approach for PostgreSQL versions >= 9.6 and uses the
116 PostgreSQL API. If using PostgreSQL 9.2, 9.3, 9.4, or 9.5,
117 Barman requires the pgespresso module to be installed on the
118 PostgreSQL server. concurrent_backup can also be used to per‐
119 form a backup from a standby server.
120 • exclusive_backup (PostgreSQL versions older than 15 only):
122 barman backup executes backup operations using the deprecated
123 exclusive backup approach (technically through pg_start_backup
124 and pg_stop_backup)
125 • external_configuration: if present, any warning regarding ex‐
127 ternal configuration files is suppressed during the execution
128 of a backup.
129 Note that exclusive_backup and concurrent_backup are mutually
131 exclusive. Global/Server.
132 bandwidth_limit
134 This option allows you to specify a maximum transfer rate in
135 kilobytes per second. A value of zero specifies no limit (de‐
136 fault). Global/Server.
137 barman_home
139 Main data directory for Barman. Global.
140 barman_lock_directory
142 Directory for locks. Default: %(barman_home)s. Global.
143 basebackup_retry_sleep
145 Number of seconds of wait after a failed copy, before retrying
146 Used during both backup and recovery operations. Positive inte‐
147 ger, default 30. Global/Server.
148 basebackup_retry_times
150 Number of retries of base backup copy, after an error. Used
151 during both backup and recovery operations. Positive integer,
152 default 0. Global/Server.
153 basebackups_directory
155 Directory where base backups will be placed. Server.
156 check_timeout
158 Maximum execution time, in seconds per server, for a barman
159 check command. Set to 0 to disable the timeout. Positive inte‐
160 ger, default 30. Global/Server.
161 compression
163 Standard compression algorithm applied to WAL files. Possible
164 values are: gzip (requires gzip to be installed on the system),
165 bzip2 (requires bzip2), pigz (requires pigz), pygzip (Python's
166 internal gzip compressor) and pybzip2 (Python's internal bzip2
167 compressor). Global/Server.
168 conninfo
170 Connection string used by Barman to connect to the Postgres
171 server. This is a libpq connection string, consult the Post‐
172 greSQL manual (https://www.postgresql.org/docs/current/stat‐
173 ic/libpq-connect.html#LIBPQ-CONNSTRING) for more information.
174 Commonly used keys are: host, hostaddr, port, dbname, user,
175 password. Server.
176 create_slot
178 When set to auto and slot_name is defined, Barman automatically
179 attempts to create the replication slot if not present. When
180 set to manual (default), the replication slot needs to be manu‐
181 ally created. Global/Server.
182 custom_compression_filter
184 Customised compression algorithm applied to WAL files. Glob‐
185 al/Server.
186 custom_compression_magic
188 Customised compression magic which is checked in the beginning
189 of a WAL file to select the custom algorithm. If you are using
190 a custom compression filter then setting this will prevent bar‐
191 man from applying the custom compression to WALs which have been
192 pre-compressed with that compression. If you do not configure
193 this then custom compression will still be applied but any
194 pre-compressed WAL files will be compressed again during WAL ar‐
195 chive. Global/Server.
196 custom_decompression_filter
198 Customised decompression algorithm applied to compressed WAL
199 files; this must match the compression algorithm. Global/Serv‐
200 er.
201 description
203 A human readable description of a server. Server.
204 errors_directory
206 Directory that contains WAL files that contain an error; usually
207 this is related to a conflict with an existing WAL file (e.g. a
208 WAL file that has been archived after a streamed one).
209 forward_config_path
211 Parameter which determines whether a passive node should forward
212 its configuration file path to its primary node during cron or
213 sync-info commands. Set to true if you are invoking barman with
214 the -c/--config option and your configuration is in the same
215 place on both the passive and primary barman servers. Defaults
216 to false.
217 immediate_checkpoint
219 This option allows you to control the way PostgreSQL handles
220 checkpoint at the start of the backup. If set to false (de‐
221 fault), the I/O workload for the checkpoint will be limited, ac‐
222 cording to the checkpoint_completion_target setting on the Post‐
223 greSQL server. If set to true, an immediate checkpoint will be
224 requested, meaning that PostgreSQL will complete the checkpoint
225 as soon as possible. Global/Server.
226 incoming_wals_directory
228 Directory where incoming WAL files are archived into. Requires
229 archiver to be enabled. Server.
230 last_backup_maximum_age
232 This option identifies a time frame that must contain the latest
233 backup. If the latest backup is older than the time frame, bar‐
234 man check command will report an error to the user. If empty
235 (default), latest backup is always considered valid. Syntax for
236 this option is: "i (DAYS | WEEKS | MONTHS)" where i is a integer
237 greater than zero, representing the number of days | weeks |
238 months of the time frame. Global/Server.
239 last_backup_minimum_size
241 This option identifies lower limit to the acceptable size of the
242 latest successful backup. If the latest backup is smaller than
243 the specified size, barman check command will report an error to
244 the user. If empty (default), latest backup is always consid‐
245 ered valid. Syntax for this option is: "i
246 (k|Ki|M|Mi|G|Gi|T|Ti)" where i is an integer greater than zero,
247 with an optional SI or IEC suffix. k=kilo=1000, Ki=Kibi=1024
248 and so forth. Note that the suffix is case-sensitive. Glob‐
249 al/Server.
250 last_wal_maximum_age
252 This option identifies a time frame that must contain the latest
253 WAL file archived. If the latest WAL file is older than the
254 time frame, barman check command will report an error to the us‐
255 er. If empty (default), the age of the WAL files is not
256 checked. Syntax is the same as last_backup_maximum_age (above).
257 Global/Server. log_file
258 Location of Barman's log file. Global.
259 log_level
261 Level of logging (DEBUG, INFO, WARNING, ERROR, CRITICAL). Glob‐
262 al.
263 max_incoming_wals_queue
265 Maximum number of WAL files in the incoming queue (in both
266 streaming and archiving pools) that are allowed before barman
267 check returns an error (that does not block backups). Glob‐
268 al/Server. Default: None (disabled).
269 minimum_redundancy
271 Minimum number of backups to be retained. Default 0. Glob‐
272 al/Server.
273 network_compression
275 This option allows you to enable data compression for network
276 transfers. If set to false (default), no compression is used.
277 If set to true, compression is enabled, reducing network usage.
278 Global/Server.
279 parallel_jobs
281 This option controls how many parallel workers will copy files
282 during a backup or recovery command. Default 1. Global/Server.
283 For backup purposes, it works only when backup_method is rsync.
284 path_prefix
286 One or more absolute paths, separated by colon, where Barman
287 looks for executable files. The paths specified in path_prefix
288 are tried before the ones specified in PATH environment vari‐
289 able. Global/server.
290 post_archive_retry_script
292 Hook script launched after a WAL file is archived by mainte‐
293 nance. Being this a retry hook script, Barman will retry the
294 execution of the script until this either returns a SUCCESS (0),
295 an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. In a post
296 archive scenario, ABORT_STOP has currently the same effects as
297 ABORT_CONTINUE. Global/Server.
298 post_archive_script
300 Hook script launched after a WAL file is archived by mainte‐
301 nance, after 'post_archive_retry_script'. Global/Server.
302 post_backup_retry_script
304 Hook script launched after a base backup. Being this a retry
305 hook script, Barman will retry the execution of the script until
306 this either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
307 ABORT_STOP (63) code. In a post backup scenario, ABORT_STOP has
308 currently the same effects as ABORT_CONTINUE. Global/Server.
309 post_backup_script
311 Hook script launched after a base backup, after 'post_back‐
312 up_retry_script'. Global/Server.
313 post_delete_retry_script
315 Hook script launched after the deletion of a backup. Being this
316 a retry hook script, Barman will retry the execution of the
317 script until this either returns a SUCCESS (0), an ABORT_CONTIN‐
318 UE (62) or an ABORT_STOP (63) code. In a post delete scenario,
319 ABORT_STOP has currently the same effects as ABORT_CONTINUE.
320 Global/Server.
321 post_delete_script
323 Hook script launched after the deletion of a backup, after
324 'post_delete_retry_script'. Global/Server.
325 post_recovery_retry_script
327 Hook script launched after a recovery. Being this a retry hook
328 script, Barman will retry the execution of the script until this
329 either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
330 ABORT_STOP (63) code. In a post recovery scenario, ABORT_STOP
331 has currently the same effects as ABORT_CONTINUE. Global/Serv‐
332 er.
333 post_recovery_script
335 Hook script launched after a recovery, after 'post_recov‐
336 ery_retry_script'. Global/Server.
337 post_wal_delete_retry_script
339 Hook script launched after the deletion of a WAL file. Being
340 this a retry hook script, Barman will retry the execution of the
341 script until this either returns a SUCCESS (0), an ABORT_CONTIN‐
342 UE (62) or an ABORT_STOP (63) code. In a post delete scenario,
343 ABORT_STOP has currently the same effects as ABORT_CONTINUE.
344 Global/Server.
345 post_wal_delete_script
347 Hook script launched after the deletion of a WAL file, after
348 'post_wal_delete_retry_script'. Global/Server.
349 pre_archive_retry_script
351 Hook script launched before a WAL file is archived by mainte‐
352 nance, after 'pre_archive_script'. Being this a retry hook
353 script, Barman will retry the execution of the script until this
354 either returns a SUCCESS (0), an ABORT_CONTINUE (62) or an
355 ABORT_STOP (63) code. Returning ABORT_STOP will propagate the
356 failure at a higher level and interrupt the WAL archiving opera‐
357 tion. Global/Server.
358 pre_archive_script
360 Hook script launched before a WAL file is archived by mainte‐
361 nance. Global/Server.
362 pre_backup_retry_script
364 Hook script launched before a base backup, after 'pre_back‐
365 up_script'. Being this a retry hook script, Barman will retry
366 the execution of the script until this either returns a SUCCESS
367 (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. Return‐
368 ing ABORT_STOP will propagate the failure at a higher level and
369 interrupt the backup operation. Global/Server.
370 pre_backup_script
372 Hook script launched before a base backup. Global/Server.
373 pre_delete_retry_script
375 Hook script launched before the deletion of a backup, after
376 'pre_delete_script'. Being this a retry hook script, Barman
377 will retry the execution of the script until this either returns
378 a SUCCESS (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63)
379 code. Returning ABORT_STOP will propagate the failure at a
380 higher level and interrupt the backup deletion. Global/Server.
381 pre_delete_script
383 Hook script launched before the deletion of a backup. Glob‐
384 al/Server.
385 pre_recovery_retry_script
387 Hook script launched before a recovery, after 'pre_recov‐
388 ery_script'. Being this a retry hook script, Barman will retry
389 the execution of the script until this either returns a SUCCESS
390 (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63) code. Return‐
391 ing ABORT_STOP will propagate the failure at a higher level and
392 interrupt the recover operation. Global/Server.
393 pre_recovery_script
395 Hook script launched before a recovery. Global/Server.
396 pre_wal_delete_retry_script
398 Hook script launched before the deletion of a WAL file, after
399 'pre_wal_delete_script'. Being this a retry hook script, Barman
400 will retry the execution of the script until this either returns
401 a SUCCESS (0), an ABORT_CONTINUE (62) or an ABORT_STOP (63)
402 code. Returning ABORT_STOP will propagate the failure at a
403 higher level and interrupt the WAL file deletion. Global/Serv‐
404 er.
405 pre_wal_delete_script
407 Hook script launched before the deletion of a WAL file. Glob‐
408 al/Server.
409 primary_ssh_command
411 Parameter that identifies a Barman server as passive. In a pas‐
412 sive node, the source of a backup server is a Barman installa‐
413 tion rather than a PostgreSQL server. If primary_ssh_command is
414 specified, Barman uses it to establish a connection with the
415 primary server. Empty by default, it can also be set globally.
416 recovery_options
418 Options for recovery operations. Currently only supports
419 get-wal. get-wal activates generation of a basic restore_com‐
420 mand in the resulting recovery configuration that uses the bar‐
421 man get-wal command to fetch WAL files directly from Barman's
422 archive of WALs. Comma separated list of values, default empty.
423 Global/Server.
424 recovery_staging_path
426 A path to a location on the recovery host (either the barman
427 server or a remote host if --remote-ssh-command is also used)
428 where files for a compressed backup will be staged before being
429 uncompressed to the destination directory. Backups will be
430 staged in their own directory within the staging path according
431 to the following naming convention: "barman-staging-SERV‐
432 ER_NAME-BACKUP_ID". The staging directory within the staging
433 path will be removed at the end of the recovery process. This
434 option is required when recovering from compressed backups and
435 has no effect otherwise. Global/Server.
436 retention_policy
438 Policy for retention of periodic backups and archive logs. If
439 left empty, retention policies are not enforced. For redundancy
440 based retention policy use "REDUNDANCY i" (where i is an integer
441 > 0 and defines the number of backups to retain). For recovery
442 window retention policy use "RECOVERY WINDOW OF i DAYS" or "RE‐
443 COVERY WINDOW OF i WEEKS" or "RECOVERY WINDOW OF i MONTHS" where
444 i is a positive integer representing, specifically, the number
445 of days, weeks or months to retain your backups. For more de‐
446 tailed information, refer to the official documentation. De‐
447 fault value is empty. Global/Server.
448 retention_policy_mode
450 Currently only "auto" is implemented. Global/Server.
451 reuse_backup
453 This option controls incremental backup support. Global/Server.
454 Possible values are:
455 • off: disabled (default);
457 • copy: reuse the last available backup for a server and create
459 a copy of the unchanged files (reduce backup time);
460 • link: reuse the last available backup for a server and create
462 a hard link of the unchanged files (reduce backup time and
463 space). Requires operating system and file system support for
464 hard links.
465 slot_name
467 Physical replication slot to be used by the receive-wal command
468 when streaming_archiver is set to on. Requires PostgreSQL >=
469 9.4. Global/Server. Default: None (disabled).
470 ssh_command
472 Command used by Barman to login to the Postgres server via ssh.
473 Server.
474 streaming_archiver
476 This option allows you to use the PostgreSQL's streaming proto‐
477 col to receive transaction logs from a server. If set to on,
478 Barman expects to find pg_receivewal (known as pg_receivexlog
479 prior to PostgreSQL 10) in the PATH (see path_prefix option) and
480 that streaming connection for the server is working. This acti‐
481 vates connection checks as well as management (including com‐
482 pression) of WAL files. If set to off (default) barman will re‐
483 ly only on continuous archiving for a server WAL archive opera‐
484 tions, eventually terminating any running pg_receivexlog for the
485 server. Global/Server.
486 streaming_archiver_batch_size
488 This option allows you to activate batch processing of WAL files
489 for the streaming_archiver process, by setting it to a value >
490 0. Otherwise, the traditional unlimited processing of the WAL
491 queue is enabled. When batch processing is activated, the ar‐
492 chive-wal process would limit itself to maximum stream‐
493 ing_archiver_batch_size WAL segments per single run. Integer.
494 Global/Server.
495 streaming_archiver_name
497 Identifier to be used as application_name by the receive-wal
498 command. Only available with pg_receivewal (or pg_receivexlog
499 >= 9.3). By default it is set to barman_receive_wal. Glob‐
500 al/Server.
501 streaming_backup_name
503 Identifier to be used as application_name by the pg_basebackup
504 command. Only available with pg_basebackup >= 9.3. By default
505 it is set to barman_streaming_backup. Global/Server.
506 streaming_conninfo
508 Connection string used by Barman to connect to the Postgres
509 server via streaming replication protocol. By default it is set
510 to conninfo. Server.
511 streaming_wals_directory
513 Directory where WAL files are streamed from the PostgreSQL serv‐
514 er to Barman. Requires streaming_archiver to be enabled. Serv‐
515 er.
516 tablespace_bandwidth_limit
518 This option allows you to specify a maximum transfer rate in
519 kilobytes per second, by specifying a comma separated list of
520 tablespaces (pairs TBNAME:BWLIMIT). A value of zero specifies
521 no limit (default). Global/Server.
522 wal_retention_policy
524 Policy for retention of archive logs (WAL files). Currently on‐
525 ly "MAIN" is available. Global/Server.
526 wals_directory
528 Directory which contains WAL files. Server.
529
531 The script definition is passed to a shell and can return any exit
532 code.
533 The shell environment will contain the following variables:
535 BARMAN_CONFIGURATION
537 configuration file used by barman
538 BARMAN_ERROR
540 error message, if any (only for the 'post' phase)
541 BARMAN_PHASE
543 'pre' or 'post'
544 BARMAN_RETRY
546 1 if it is a retry script (from 1.5.0), 0 if not
547 BARMAN_SERVER
549 name of the server
550 Backup scripts specific variables:
552 BARMAN_BACKUP_DIR
554 backup destination directory
555 BARMAN_BACKUP_ID
557 ID of the backup
558 BARMAN_PREVIOUS_ID
560 ID of the previous backup (if present)
561 BARMAN_NEXT_ID
563 ID of the next backup (if present)
564 BARMAN_STATUS
566 status of the backup
567 BARMAN_VERSION
569 version of Barman
570 Archive scripts specific variables:
572 BARMAN_SEGMENT
574 name of the WAL file
575 BARMAN_FILE
577 full path of the WAL file
578 BARMAN_SIZE
580 size of the WAL file
581 BARMAN_TIMESTAMP
583 WAL file timestamp
584 BARMAN_COMPRESSION
586 type of compression used for the WAL file
587 Recovery scripts specific variables:
589 BARMAN_DESTINATION_DIRECTORY
591 the directory where the new instance is recovered
592 BARMAN_TABLESPACES
594 tablespace relocation map (JSON, if present)
595 BARMAN_REMOTE_COMMAND
597 secure shell command used by the recovery (if present)
598 BARMAN_RECOVER_OPTIONS
600 recovery additional options (JSON, if present)
601 Only in case of retry hook scripts, the exit code of the script is
603 checked by Barman. Output of hook scripts is simply written in the log
604 file.
605
607 Here is an example of configuration file:
608 [barman]
610 ; Main directory
611 barman_home = /var/lib/barman
612 ; System user
614 barman_user = barman
615 ; Log location
617 log_file = /var/log/barman/barman.log
618 ; Default compression level
620 ;compression = gzip
621 ; Incremental backup
623 reuse_backup = link
624 ; 'main' PostgreSQL Server configuration
626 [main]
627 ; Human readable description
628 description = "Main PostgreSQL Database"
629 ; SSH options
631 ssh_command = ssh postgres@pg
632 ; PostgreSQL connection string
634 conninfo = host=pg user=postgres
635 ; PostgreSQL streaming connection string
637 streaming_conninfo = host=pg user=postgres
638 ; Minimum number of required backups (redundancy)
640 minimum_redundancy = 1
641 ; Retention policy (based on redundancy)
643 retention_policy = REDUNDANCY 2
644
646 barman (1).
647
649 Barman maintainers (in alphabetical order):
650 • Abhijit Menon-Sen
652 • Jane Threefoot
654 • Michael Wallace
656 Past contributors (in alphabetical order):
658 • Anna Bellandi (QA/testing)
660 • Britt Cole (documentation reviewer)
662 • Carlo Ascani (developer)
664 • Francesco Canovai (QA/testing)
666 • Gabriele Bartolini (architect)
668 • Gianni Ciolli (QA/testing)
670 • Giulio Calacoci (developer)
672 • Giuseppe Broccolo (developer)
674 • Jonathan Battiato (QA/testing)
676 • Leonardo Cecchi (developer)
678 • Marco Nenciarini (project leader)
680 • Niccolò Fei (QA/testing)
682 • Rubens Souza (QA/testing)
684 • Stefano Bianucci (developer)
686
688 • Homepage: <https://www.pgbarman.org/>
689 • Documentation: <https://docs.pgbarman.org/>
691 • Professional support: <https://www.enterprisedb.com/>
693
695 Barman is the property of EnterpriseDB UK Limited and its code is dis‐
696 tributed under GNU General Public License v3.
697 © Copyright EnterpriseDB UK Limited 2011-2022
699
701 EnterpriseDB <https://www.enterprisedb.com>.
702Barman User manuals June 27, 2022 BARMAN(5)