1BARMAN(5)                        Version 2.10                        BARMAN(5)
2
3
4

NAME

6       barman - Backup and Recovery Manager for PostgreSQL
7

DESCRIPTION

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

CONFIGURATION FILE LOCATIONS

15       The system-level Barman configuration file is located at
16
17              /etc/barman.conf
18
19       or
20
21              /etc/barman/barman.conf
22
23       and is overridden on a per-user level by
24
25              $HOME/.barman.conf
26

CONFIGURATION FILE SYNTAX

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

CONFIGURATION FILE DIRECTORY

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

OPTIONS

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
49       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
58       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
66       backup_directory
67              Directory where backup data for a server will be placed.   Serv‐
68              er.
69
70       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
76       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
81              · 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
86              · 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
93              · external_configuration: if present, any warning regarding  ex‐
94                ternal  configuration files is suppressed during the execution
95                of a backup.
96
97              Note that exclusive_backup and  concurrent_backup  are  mutually
98              exclusive.  Global/Server.
99
100       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
105       barman_home
106              Main data directory for Barman.  Global.
107
108       barman_lock_directory
109              Directory for locks.  Default: %(barman_home)s.  Global.
110
111       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
116       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
121       basebackups_directory
122              Directory where base backups will be placed.  Server.
123
124       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
129       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
136       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
144       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
150       custom_compression_filter
151              Customised  compression  algorithm  applied to WAL files.  Glob‐
152              al/Server.
153
154       custom_decompression_filter
155              Customised decompression algorithm  applied  to  compressed  WAL
156              files;  this must match the compression algorithm.  Global/Serv‐
157              er.
158
159       description
160              A human readable description of a server.  Server.
161
162       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
167       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
176       incoming_wals_directory
177              Directory where incoming WAL files are archived into.   Requires
178              archiver to be enabled.  Server.
179
180       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
189       log_file
190              Location of Barman's log file.  Global.
191
192       log_level
193              Level of logging (DEBUG, INFO, WARNING, ERROR, CRITICAL).  Glob‐
194              al.
195
196       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
202       minimum_redundancy
203              Minimum  number  of  backups  to be retained.  Default 0.  Glob‐
204              al/Server.
205
206       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
212       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
217       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
223       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
231       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
235       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
242       post_backup_script
243              Hook script launched after  a  base  backup,  after  'post_back‐
244              up_retry_script'.  Global/Server.
245
246       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
254       post_delete_script
255              Hook script launched after  the  deletion  of  a  backup,  after
256              'post_delete_retry_script'.  Global/Server.
257
258       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
266       post_recovery_script
267              Hook  script  launched  after  a  recovery,  after  'post_recov‐
268              ery_retry_script'.  Global/Server.
269
270       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
278       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
282       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
291       pre_archive_script
292              Hook  script  launched  before a WAL file is archived by mainte‐
293              nance.  Global/Server.
294
295       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
303       pre_backup_script
304              Hook script launched before a base backup.  Global/Server.
305
306       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
314       pre_delete_script
315              Hook script launched before the deletion  of  a  backup.   Glob‐
316              al/Server.
317
318       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
326       pre_recovery_script
327              Hook script launched before a recovery.  Global/Server.
328
329       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
338       pre_wal_delete_script
339              Hook script launched before the deletion of a WAL  file.   Glob‐
340              al/Server.
341
342       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
349       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
357       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
369       retention_policy_mode
370              Currently only "auto" is implemented.  Global/Server.
371
372       reuse_backup
373              This option controls incremental backup support.  Global/Server.
374              Possible values are:
375
376              · off: disabled (default);
377
378              · copy: reuse the last available backup for a server and  create
379                a copy of the unchanged files (reduce backup time);
380
381              · 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
386       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
391       ssh_command
392              Command used by Barman to login to the Postgres server via  ssh.
393              Server.
394
395       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
407       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
416       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
422       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
427       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
432       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
437       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
443       wal_retention_policy
444              Policy for retention of archive logs (WAL files).  Currently on‐
445              ly "MAIN" is available.  Global/Server.
446
447       wals_directory
448              Directory which contains WAL files.  Server.
449

HOOK SCRIPTS

451       The  script  definition  is  passed  to a shell and can return any exit
452       code.
453
454       The shell environment will contain the following variables:
455
456       BARMAN_CONFIGURATION
457              configuration file used by barman
458
459       BARMAN_ERROR
460              error message, if any (only for the 'post' phase)
461
462       BARMAN_PHASE
463              'pre' or 'post'
464
465       BARMAN_RETRY
466              1 if it is a retry script (from 1.5.0), 0 if not
467
468       BARMAN_SERVER
469              name of the server
470
471       Backup scripts specific variables:
472
473       BARMAN_BACKUP_DIR
474              backup destination directory
475
476       BARMAN_BACKUP_ID
477              ID of the backup
478
479       BARMAN_PREVIOUS_ID
480              ID of the previous backup (if present)
481
482       BARMAN_NEXT_ID
483              ID of the next backup (if present)
484
485       BARMAN_STATUS
486              status of the backup
487
488       BARMAN_VERSION
489              version of Barman
490
491       Archive scripts specific variables:
492
493       BARMAN_SEGMENT
494              name of the WAL file
495
496       BARMAN_FILE
497              full path of the WAL file
498
499       BARMAN_SIZE
500              size of the WAL file
501
502       BARMAN_TIMESTAMP
503              WAL file timestamp
504
505       BARMAN_COMPRESSION
506              type of compression used for the WAL file
507
508       Recovery scripts specific variables:
509
510       BARMAN_DESTINATION_DIRECTORY
511              the directory where the new instance is recovered
512
513       BARMAN_TABLESPACES
514              tablespace relocation map (JSON, if present)
515
516       BARMAN_REMOTE_COMMAND
517              secure shell command used by the recovery (if present)
518
519       BARMAN_RECOVER_OPTIONS
520              recovery additional options (JSON, if present)
521
522       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

EXAMPLE

527       Here is an example of configuration file:
528
529              [barman]
530              ; Main directory
531              barman_home = /var/lib/barman
532
533              ; System user
534              barman_user = barman
535
536              ; Log location
537              log_file = /var/log/barman/barman.log
538
539              ; Default compression level
540              ;compression = gzip
541
542              ; Incremental backup
543              reuse_backup = link
544
545              ; 'main' PostgreSQL Server configuration
546              [main]
547              ; Human readable description
548              description =  "Main PostgreSQL Database"
549
550              ; SSH options
551              ssh_command = ssh postgres@pg
552
553              ; PostgreSQL connection string
554              conninfo = host=pg user=postgres
555
556              ; PostgreSQL streaming connection string
557              streaming_conninfo = host=pg user=postgres
558
559              ; Minimum number of required backups (redundancy)
560              minimum_redundancy = 1
561
562              ; Retention policy (based on redundancy)
563              retention_policy = REDUNDANCY 2
564

SEE ALSO

566       barman (1).
567

AUTHORS

569       In alphabetical order:
570
571       · Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (architect)
572
573       · Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
574
575       · Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
576
577       · Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
578
579       · Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
580
581       · Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
582
583       · Britt Cole <britt.cole@2ndquadrant.com> (documentation)
584
585       · Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (project leader)
586
587       · Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
588
589       Past contributors:
590
591       · Carlo Ascani
592
593       · Stefano Bianucci
594
595       · Giuseppe Broccolo
596

RESOURCES

598       · Homepage: <http://www.pgbarman.org/>
599
600       · Documentation: <http://docs.pgbarman.org/>
601
602       · Professional support: <https://www.2ndQuadrant.com/>
603

COPYING

605       Barman is the property of 2ndQuadrant Limited and its code is  distrib‐
606       uted under GNU General Public License v3.
607
608       Copyright  (C)  2011-2019  2ndQuadrant  Limited  - https://www.2ndQuad
609       rant.com/.
610

AUTHORS

612       2ndQuadrant Limited <https://www.2ndQuadrant.com>.
613
614
615
616Barman User manuals            December 5, 2019                      BARMAN(5)
Impressum