1BARMAN(5)                         Version 2.8                        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       custom_compression_filter
145              Customised compression algorithm applied to  WAL  files.   Glob‐
146              al/Server.
147
148       custom_decompression_filter
149              Customised  decompression  algorithm  applied  to compressed WAL
150              files; this must match the compression algorithm.   Global/Serv‐
151              er.
152
153       description
154              A human readable description of a server.  Server.
155
156       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
161       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
170       incoming_wals_directory
171              Directory  where incoming WAL files are archived into.  Requires
172              archiver to be enabled.  Server.
173
174       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
183       log_file
184              Location of Barman’s log file.  Global.
185
186       log_level
187              Level of logging (DEBUG, INFO, WARNING, ERROR, CRITICAL).  Glob‐
188              al.
189
190       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
196       minimum_redundancy
197              Minimum number of backups to be  retained.   Default  0.   Glob‐
198              al/Server.
199
200       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
206       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
211       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
217       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
225       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
229       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
236       post_backup_script
237              Hook  script  launched  after  a  base backup, after `post_back‐
238              up_retry_script'.  Global/Server.
239
240       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
248       post_delete_script
249              Hook  script  launched  after  the  deletion  of a backup, after
250              `post_delete_retry_script'.  Global/Server.
251
252       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
260       post_recovery_script
261              Hook  script  launched  after  a  recovery,  after  `post_recov‐
262              ery_retry_script'.  Global/Server.
263
264       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
272       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
276       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
285       pre_archive_script
286              Hook script launched before a WAL file is  archived  by  mainte‐
287              nance.  Global/Server.
288
289       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
297       pre_backup_script
298              Hook script launched before a base backup.  Global/Server.
299
300       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
308       pre_delete_script
309              Hook  script  launched  before  the deletion of a backup.  Glob‐
310              al/Server.
311
312       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
320       pre_recovery_script
321              Hook script launched before a recovery.  Global/Server.
322
323       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
332       pre_wal_delete_script
333              Hook  script  launched before the deletion of a WAL file.  Glob‐
334              al/Server.
335
336       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
343       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
351       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
363       retention_policy_mode
364              Currently only “auto” is implemented.  Global/Server.
365
366       reuse_backup
367              This option controls incremental backup support.  Global/Server.
368              Possible values are:
369
370              · off: disabled (default);
371
372              · copy:  reuse the last available backup for a server and create
373                a copy of the unchanged files (reduce backup time);
374
375              · 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
380       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
385       ssh_command
386              Command  used by Barman to login to the Postgres server via ssh.
387              Server.
388
389       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
401       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
410       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
416       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
421       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
426       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
431       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
437       wal_retention_policy
438              Policy for retention of archive logs (WAL files).  Currently on‐
439              ly “MAIN” is available.  Global/Server.
440
441       wals_directory
442              Directory which contains WAL files.  Server.
443

HOOK SCRIPTS

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

EXAMPLE

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

SEE ALSO

560       barman (1).
561

AUTHORS

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

RESOURCES

592       · Homepage: <http://www.pgbarman.org/>
593
594       · Documentation: <http://docs.pgbarman.org/>
595
596       · Professional support: <https://www.2ndQuadrant.com/>
597

COPYING

599       Barman  is the property of 2ndQuadrant Limited and its code is distrib‐
600       uted under GNU General Public License v3.
601
602       Copyright (C)  2011-2019  2ndQuadrant  Limited  -  https://www.2ndQuad
603       rant.com/.
604

AUTHORS

606       2ndQuadrant Limited <https://www.2ndQuadrant.com>.
607
608
609
610Barman User manuals              May 17, 2019                        BARMAN(5)
Impressum