.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "BARMAN" "5" "January 24, 2024" "Barman User manuals" "Version 3.10.0"
.hy
.SH NAME
.PP
barman \- Backup and Recovery Manager for PostgreSQL
.SH DESCRIPTION
.PP
Barman is an administration tool for disaster recovery of PostgreSQL
servers written in Python and maintained by EnterpriseDB.
Barman can perform remote backups of multiple servers in business
critical environments and helps DBAs during the recovery phase.
.SH CONFIGURATION FILE LOCATIONS
.PP
The system\-level Barman configuration file is located at
.IP
.nf
\f[C]
/etc/barman.conf
\f[]
.fi
.PP
or
.IP
.nf
\f[C]
/etc/barman/barman.conf
\f[]
.fi
.PP
and is overridden on a per\-user level by
.IP
.nf
\f[C]
$HOME/.barman.conf
\f[]
.fi
.SH CONFIGURATION FILE SYNTAX
.PP
The Barman configuration file is a plain \f[C]INI\f[] file.
There is a general section called \f[C][barman]\f[] and a section
\f[C][servername]\f[] for each server you want to backup.
Rows starting with \f[C];\f[] are comments.
.SH CONFIGURATION FILE DIRECTORY
.PP
Barman supports the inclusion of multiple configuration files, through
the \f[C]configuration_files_directory\f[] option.
Included files must contain only server specifications, not global
configurations.
If the value of \f[C]configuration_files_directory\f[] is a directory,
Barman reads all files with \f[C]\&.conf\f[] extension that exist in
that folder.
For example, if you set it to \f[C]/etc/barman.d\f[], you can specify
your PostgreSQL servers placing each section in a separate
\f[C]\&.conf\f[] file inside the \f[C]/etc/barman.d\f[] folder.
.SH OPTIONS
.TP
.B active
When set to \f[C]true\f[] (default), the server is in full operational
state.
When set to \f[C]false\f[], the server can be used for diagnostics, but
any operational command such as backup execution or WAL archiving is
temporarily disabled.
When adding a new server to Barman, we suggest setting active=false at
first, making sure that barman check shows no problems, and only then
activating the server.
This will avoid spamming the Barman logs with errors during the initial
setup.
.RS
.PP
Scope: Server/Model.
.RE
.TP
.B archiver
This option allows you to activate log file shipping through
PostgreSQL\[aq]s \f[C]archive_command\f[] for a server.
If set to \f[C]true\f[], Barman expects that continuous archiving for a
server is in place and will activate checks as well as management
(including compression) of WAL files that Postgres deposits in the
\f[I]incoming\f[] directory.
Setting it to \f[C]false\f[] (default), will disable standard continuous
archiving for a server.
Note: If neither \f[C]archiver\f[] nor \f[C]streaming_archiver\f[] are
set, Barman will automatically set this option to \f[C]true\f[].
This is in order to maintain parity with deprecated behaviour where
\f[C]archiver\f[] would be enabled by default.
This behaviour will be removed from the next major Barman version.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B archiver_batch_size
This option allows you to activate batch processing of WAL files for the
\f[C]archiver\f[] process, by setting it to a value > 0.
Otherwise, the traditional unlimited processing of the WAL queue is
enabled.
When batch processing is activated, the \f[C]archive\-wal\f[] process
would limit itself to maximum \f[C]archiver_batch_size\f[] WAL segments
per single run.
Integer.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B autogenerate_manifest
This option enables the auto\-generation of backup manifest files for
rsync based backups and strategies.
The manifest file is a JSON file containing the list of files contained
in the backup.
It is generated at the end of the backup process and stored in the
backup directory.
The manifest file generated follows the format described in the
postgesql documentation, and is compatible with the
\f[C]pg_verifybackup\f[] tool.
The option is ignored if the backup method is not rsync.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B aws_profile
The name of the AWS profile to use when authenticating with AWS (e.g.
INI section in AWS credentials file).
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B aws_region
The name of the AWS region containing the EC2 VM and storage volumes
defined by \f[C]snapshot_instance\f[] and \f[C]snapshot_disks\f[].
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B azure_credential
The credential type (either \f[C]azure\-cli\f[] or
\f[C]managed\-identity\f[]) to use when authenticating with Azure.
If this is omitted then the default Azure authentication flow will be
used.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B azure_resource_group
The name of the Azure resource group to which the compute instance and
disks defined by \f[C]snapshot_instance\f[] and \f[C]snapshot_disks\f[]
belong.
Required when the \f[C]snapshot\f[] value is specified for
\f[C]backup_method\f[] and \f[C]snapshot_provider\f[] is set to
\f[C]azure\f[].
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B azure_subscription_id
The ID of the Azure subscription which owns the instance and storage
volumes defined by \f[C]snapshot_instance\f[] and
\f[C]snapshot_disks\f[].
Required when the \f[C]snapshot\f[] value is specified for
\f[C]backup_method\f[] and \f[C]snapshot_provider\f[] is set to
\f[C]azure\f[].
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B backup_compression
The compression to be used during the backup process.
Only supported when \f[C]backup_method\ =\ postgres\f[].
Can either be unset or \f[C]gzip\f[],\f[C]lz4\f[], \f[C]zstd\f[] or
\f[C]none\f[].
If unset then no compression will be used during the backup.
Use of this option requires that the CLI application for the specified
compression algorithm is available on the Barman server (at backup time)
and the PostgreSQL server (at recovery time).
Note that the \f[C]lz4\f[] and \f[C]zstd\f[] algorithms require
PostgreSQL 15 (beta) or later.
Note that \f[C]none\f[] compression will create an archive not
compressed.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B backup_compression_format
The format pg_basebackup should use when writing compressed backups to
disk.
Can be set to either \f[C]plain\f[] or \f[C]tar\f[].
If unset then a default of \f[C]tar\f[] is assumed.
The value \f[C]plain\f[] can only be used if the server is running
PostgreSQL 15 or later \f[I]and\f[] if
\f[C]backup_compression_location\f[] is \f[C]server\f[].
Only supported when \f[C]backup_method\ =\ postgres\f[].
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B backup_compression_level
An integer value representing the compression level to use when
compressing backups.
Allowed values depend on the compression algorithm specified by
\f[C]backup_compression\f[].
Only supported when \f[C]backup_method\ =\ postgres\f[].
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B backup_compression_location
The location (either \f[C]client\f[] or \f[C]server\f[]) where
compression should be performed during the backup.
The value \f[C]server\f[] is only allowed if the server is running
PostgreSQL 15 or later.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B backup_compression_workers
The number of compression threads to be used during the backup process.
Only supported when \f[C]backup_compression\ =\ zstd\f[] is set.
Default value is 0.
In this case default compression behavior will be used.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B backup_directory
Directory where backup data for a server will be placed.
.RS
.PP
Scope: Server.
.RE
.TP
.B backup_method
Configure the method barman used for backup execution.
If set to \f[C]rsync\f[] (default), barman will execute backup using the
\f[C]rsync\f[] command over SSH (requires \f[C]ssh_command\f[]).
If set to \f[C]postgres\f[] barman will use the \f[C]pg_basebackup\f[]
command to execute the backup.
If set to \f[C]local\-rsync\f[], barman will assume to be running on the
same server as the PostgreSQL instance and with the same user, then
execute \f[C]rsync\f[] for the file system copy.
If set to \f[C]snapshot\f[], barman will use the API for the cloud
provider defined in the \f[C]snapshot_provider\f[] option to create
snapshots of disks specified in the \f[C]snapshot_disks\f[] option and
save only the backup label and metadata to its own storage.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B backup_options
This option allows you to control the way Barman interacts with
PostgreSQL for backups.
It is a comma\-separated list of values that accepts the following
options:
.RS
.IP \[bu] 2
\f[C]concurrent_backup\f[] (default): \f[C]barman\ backup\f[] executes
backup operations using concurrent backup which is the recommended
backup approach for PostgreSQL versions >= 9.6 and uses the PostgreSQL
API.
\f[C]concurrent_backup\f[] can also be used to perform a backup from a
standby server.
.IP \[bu] 2
\f[C]exclusive_backup\f[] (PostgreSQL versions older than 15 only):
\f[C]barman\ backup\f[] executes backup operations using the deprecated
exclusive backup approach (technically through \f[C]pg_start_backup\f[]
and \f[C]pg_stop_backup\f[])
.IP \[bu] 2
\f[C]external_configuration\f[]: if present, any warning regarding
external configuration files is suppressed during the execution of a
backup.
.PP
Note that \f[C]exclusive_backup\f[] and \f[C]concurrent_backup\f[] are
mutually exclusive.
.PP
Scope: Global/Server/Model.
.RE
.TP
.B bandwidth_limit
This option allows you to specify a maximum transfer rate in kilobytes
per second.
A value of zero specifies no limit (default).
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B barman_home
Main data directory for Barman.
.RS
.PP
Scope: Global.
.RE
.TP
.B barman_lock_directory
Directory for locks.
Default: \f[C]%(barman_home)s\f[].
.RS
.PP
Scope: Global.
.RE
.TP
.B basebackup_retry_sleep
Number of seconds of wait after a failed copy, before retrying Used
during both backup and recovery operations.
Positive integer, default 30.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B basebackup_retry_times
Number of retries of base backup copy, after an error.
Used during both backup and recovery operations.
Positive integer, default 0.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B basebackups_directory
Directory where base backups will be placed.
.RS
.PP
Scope: Server.
.RE
.TP
.B check_timeout
Maximum execution time, in seconds per server, for a barman check
command.
Set to 0 to disable the timeout.
Positive integer, default 30.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B cluster
Name of the Barman cluster associated with a Barman server or model.
Used by Barman to group servers and configuration models that can be
applied to them.
Can be omitted for servers, in which case it defaults to the server
name.
Must be set for configuration models, so Barman knows the set of servers
which can apply a given model.
.RS
.PP
Scope: Server/Model.
.RE
.TP
.B compression
Standard compression algorithm applied to WAL files.
Possible values are: \f[C]gzip\f[] (requires \f[C]gzip\f[] to be
installed on the system), \f[C]bzip2\f[] (requires \f[C]bzip2\f[]),
\f[C]pigz\f[] (requires \f[C]pigz\f[]), \f[C]pygzip\f[] (Python\[aq]s
internal gzip compressor) and \f[C]pybzip2\f[] (Python\[aq]s internal
bzip2 compressor).
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B config_changes_queue
Barman uses a queue to apply configuration changes requested through
\f[C]barman\ config\-update\f[] command.
This allows it to serialize multiple requests of configuration changes,
and also retry an operation which has been abruptly terminated.
This configuration option allows you to specify where in the filesystem
the queue should be written.
By default Barman writes to a file named \f[C]cfg_changes.queue\f[]
under \f[C]barman_home\f[].
.RS
.PP
Scope: global.
.RE
.TP
.B conninfo
Connection string used by Barman to connect to the Postgres server.
This is a libpq connection string, consult the PostgreSQL
manual (https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING)
for more information.
Commonly used keys are: host, hostaddr, port, dbname, user, password.
.RS
.PP
Scope: Server/Model.
.RE
.TP
.B create_slot
When set to \f[C]auto\f[] and \f[C]slot_name\f[] is defined, Barman
automatically attempts to create the replication slot if not present.
When set to \f[C]manual\f[] (default), the replication slot needs to be
manually created.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B custom_compression_filter
Customised compression algorithm applied to WAL files.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B custom_compression_magic
Customised compression magic which is checked in the beginning of a WAL
file to select the custom algorithm.
If you are using a custom compression filter then setting this will
prevent barman from applying the custom compression to WALs which have
been pre\-compressed with that compression.
If you do not configure this then custom compression will still be
applied but any pre\-compressed WAL files will be compressed again
during WAL archive.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B custom_decompression_filter
Customised decompression algorithm applied to compressed WAL files; this
must match the compression algorithm.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B description
A human readable description of a server.
.RS
.PP
Scope: Server/Model.
.RE
.TP
.B errors_directory
Directory that contains WAL files that contain an error; usually this is
related to a conflict with an existing WAL file (e.g.
a WAL file that has been archived after a streamed one).
.RS
.PP
Scope: Server.
.RE
.TP
.B forward_config_path
Parameter which determines whether a passive node should forward its
configuration file path to its primary node during cron or sync\-info
commands.
Set to true if you are invoking barman with the \f[C]\-c/\-\-config\f[]
option and your configuration is in the same place on both the passive
and primary barman servers.
Defaults to false.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B gcp_project
The ID of the GCP project which owns the instance and storage volumes
defined by \f[C]snapshot_instance\f[] and \f[C]snapshot_disks\f[].
Required when the \f[C]snapshot\f[] value is specified for
\f[C]backup_method\f[] and \f[C]snapshot_provider\f[] is set to
\f[C]gcp\f[].
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B gcp_zone
The name of the availability zone where the compute instance and disks
to be backed up in a snapshot backup are located.
Required when the \f[C]snapshot\f[] value is specified for
\f[C]backup_method\f[] and \f[C]snapshot_provider\f[] is set to
\f[C]gcp\f[].
.RS
.PP
Scope: Server/Model.
.RE
.TP
.B immediate_checkpoint
This option allows you to control the way PostgreSQL handles checkpoint
at the start of the backup.
If set to \f[C]false\f[] (default), the I/O workload for the checkpoint
will be limited, according to the \f[C]checkpoint_completion_target\f[]
setting on the PostgreSQL server.
If set to \f[C]true\f[], an immediate checkpoint will be requested,
meaning that PostgreSQL will complete the checkpoint as soon as
possible.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B incoming_wals_directory
Directory where incoming WAL files are archived into.
Requires \f[C]archiver\f[] to be enabled.
.RS
.PP
Scope: Server.
.RE
.TP
.B last_backup_maximum_age
This option identifies a time frame that must contain the latest backup.
If the latest backup is older than the time frame, barman check command
will report an error to the user.
If empty (default), latest backup is always considered valid.
Syntax for this option is: "i (DAYS | WEEKS | MONTHS)" where i is an
integer greater than zero, representing the number of days | weeks |
months of the time frame.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B last_backup_minimum_size
This option identifies lower limit to the acceptable size of the latest
successful backup.
If the latest backup is smaller than the specified size, barman check
command will report an error to the user.
If empty (default), latest backup is always considered valid.
Syntax for this option is: "i (k|Ki|M|Mi|G|Gi|T|Ti)" where i is an
integer greater than zero, with an optional SI or IEC suffix.
k=kilo=1000, Ki=Kibi=1024 and so forth.
Note that the suffix is case\-sensitive.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B last_wal_maximum_age
This option identifies a time frame that must contain the latest WAL
file archived.
If the latest WAL file is older than the time frame, barman check
command will report an error to the user.
If empty (default), the age of the WAL files is not checked.
Syntax is the same as last_backup_maximum_age (above).
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B lock_directory_cleanup
enables automatic cleaning up of the \f[C]barman_lock_directory\f[] from
unused lock files.
.RS
.PP
Scope: Global.
.RE
.TP
.B log_file
Location of Barman\[aq]s log file.
.RS
.PP
Scope: Global.
.RE
.TP
.B log_level
Level of logging (DEBUG, INFO, WARNING, ERROR, CRITICAL).
.RS
.PP
Scope: Global.
.RE
.TP
.B max_incoming_wals_queue
Maximum number of WAL files in the incoming queue (in both streaming and
archiving pools) that are allowed before barman check returns an error
(that does not block backups).
Default: None (disabled).
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B minimum_redundancy
Minimum number of backups to be retained.
Default 0.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B model
By default any section configured in the Barman configuration files
define the configuration for a Barman server.
If you set \f[C]model\ =\ true\f[] in a section, that turns that section
into a configuration model for a given \f[C]cluster\f[].
Cannot be set as \f[C]false\f[].
.RS
.PP
Scope: Model.
.RE
.TP
.B network_compression
This option allows you to enable data compression for network transfers.
If set to \f[C]false\f[] (default), no compression is used.
If set to \f[C]true\f[], compression is enabled, reducing network usage.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B parallel_jobs
This option controls how many parallel workers will copy files during a
backup or recovery command.
Default 1.
For backup purposes, it works only when \f[C]backup_method\f[] is
\f[C]rsync\f[].
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B parallel_jobs_start_batch_period
The time period in seconds over which a single batch of jobs will be
started.
Default: 1 second.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B parallel_jobs_start_batch_size
Maximum number of parallel jobs to start in a single batch.
Default: 10 jobs.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B path_prefix
One or more absolute paths, separated by colon, where Barman looks for
executable files.
The paths specified in \f[C]path_prefix\f[] are tried before the ones
specified in \f[C]PATH\f[] environment variable.
.RS
.PP
Scope: Global/server/Model.
.RE
.TP
.B post_archive_retry_script
Hook script launched after a WAL file is archived by maintenance.
Being this a \f[I]retry\f[] hook script, Barman will retry the execution
of the script until this either returns a SUCCESS (0), an ABORT_CONTINUE
(62) or an ABORT_STOP (63) code.
In a post archive scenario, ABORT_STOP has currently the same effects as
ABORT_CONTINUE.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B post_archive_script
Hook script launched after a WAL file is archived by maintenance, after
\[aq]post_archive_retry_script\[aq].
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B post_backup_retry_script
Hook script launched after a base backup.
Being this a \f[I]retry\f[] hook script, Barman will retry the execution
of the script until this either returns a SUCCESS (0), an ABORT_CONTINUE
(62) or an ABORT_STOP (63) code.
In a post backup scenario, ABORT_STOP has currently the same effects as
ABORT_CONTINUE.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B post_backup_script
Hook script launched after a base backup, after
\[aq]post_backup_retry_script\[aq].
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B post_delete_retry_script
Hook script launched after the deletion of a backup.
Being this a \f[I]retry\f[] hook script, Barman will retry the execution
of the script until this either returns a SUCCESS (0), an ABORT_CONTINUE
(62) or an ABORT_STOP (63) code.
In a post delete scenario, ABORT_STOP has currently the same effects as
ABORT_CONTINUE.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B post_delete_script
Hook script launched after the deletion of a backup, after
\[aq]post_delete_retry_script\[aq].
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B post_recovery_retry_script
Hook script launched after a recovery.
Being this a \f[I]retry\f[] hook script, Barman will retry the execution
of the script until this either returns a SUCCESS (0), an ABORT_CONTINUE
(62) or an ABORT_STOP (63) code.
In a post recovery scenario, ABORT_STOP has currently the same effects
as ABORT_CONTINUE.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B post_recovery_script
Hook script launched after a recovery, after
\[aq]post_recovery_retry_script\[aq].
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B post_wal_delete_retry_script
Hook script launched after the deletion of a WAL file.
Being this a \f[I]retry\f[] hook script, Barman will retry the execution
of the script until this either returns a SUCCESS (0), an ABORT_CONTINUE
(62) or an ABORT_STOP (63) code.
In a post delete scenario, ABORT_STOP has currently the same effects as
ABORT_CONTINUE.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B post_wal_delete_script
Hook script launched after the deletion of a WAL file, after
\[aq]post_wal_delete_retry_script\[aq].
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B pre_archive_retry_script
Hook script launched before a WAL file is archived by maintenance, after
\[aq]pre_archive_script\[aq].
Being this a \f[I]retry\f[] hook script, Barman will retry the execution
of the script until this either returns a SUCCESS (0), an ABORT_CONTINUE
(62) or an ABORT_STOP (63) code.
Returning ABORT_STOP will propagate the failure at a higher level and
interrupt the WAL archiving operation.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B pre_archive_script
Hook script launched before a WAL file is archived by maintenance.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B pre_backup_retry_script
Hook script launched before a base backup, after
\[aq]pre_backup_script\[aq].
Being this a \f[I]retry\f[] hook script, Barman will retry the execution
of the script until this either returns a SUCCESS (0), an ABORT_CONTINUE
(62) or an ABORT_STOP (63) code.
Returning ABORT_STOP will propagate the failure at a higher level and
interrupt the backup operation.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B pre_backup_script
Hook script launched before a base backup.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B pre_delete_retry_script
Hook script launched before the deletion of a backup, after
\[aq]pre_delete_script\[aq].
Being this a \f[I]retry\f[] hook script, Barman will retry the execution
of the script until this either returns a SUCCESS (0), an ABORT_CONTINUE
(62) or an ABORT_STOP (63) code.
Returning ABORT_STOP will propagate the failure at a higher level and
interrupt the backup deletion.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B pre_delete_script
Hook script launched before the deletion of a backup.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B pre_recovery_retry_script
Hook script launched before a recovery, after
\[aq]pre_recovery_script\[aq].
Being this a \f[I]retry\f[] hook script, Barman will retry the execution
of the script until this either returns a SUCCESS (0), an ABORT_CONTINUE
(62) or an ABORT_STOP (63) code.
Returning ABORT_STOP will propagate the failure at a higher level and
interrupt the recover operation.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B pre_recovery_script
Hook script launched before a recovery.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B pre_wal_delete_retry_script
Hook script launched before the deletion of a WAL file, after
\[aq]pre_wal_delete_script\[aq].
Being this a \f[I]retry\f[] hook script, Barman will retry the execution
of the script until this either returns a SUCCESS (0), an ABORT_CONTINUE
(62) or an ABORT_STOP (63) code.
Returning ABORT_STOP will propagate the failure at a higher level and
interrupt the WAL file deletion.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B pre_wal_delete_script
Hook script launched before the deletion of a WAL file.
.RS
.PP
Scope: Global/Server.
.RE
.TP
.B primary_checkpoint_timeout
This defines the amount of seconds that Barman will wait at the end of a
backup if no new WAL files are produced, before forcing a checkpoint on
the primary server.
.RS
.PP
If not set or set to 0, Barman will not force a checkpoint on the
primary, and wait indefinitely for new WAL files to be produced.
.PP
The value of this option should be greater of the value of the
\f[C]archive_timeout\f[] set on the primary server.
.PP
This option works only if \f[C]primary_conninfo\f[] option is set, and
it is ignored otherwise.
.PP
Scope: Server/Model.
.RE
.TP
.B primary_conninfo
The connection string used by Barman to connect to the primary Postgres
server during backup of a standby Postgres server.
Barman will use this connection to carry out any required WAL switches
on the primary during the backup of the standby.
This allows backups to complete even when
\f[C]archive_mode\ =\ always\f[] is set on the standby and write traffic
to the primary is not sufficient to trigger a natural WAL switch.
.RS
.PP
If primary_conninfo is set then it \f[I]must\f[] be pointing to a
primary Postgres instance and conninfo \f[I]must\f[] be pointing to a
standby Postgres instance.
Furthermore both instances must share the same systemid.
If these conditions are not met then \f[C]barman\ check\f[] will fail.
.PP
The primary_conninfo value must be a libpq connection string; consult
the PostgreSQL
manual (https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING)
for more information.
Commonly used keys are: host, hostaddr, port, dbname, user, password.
.PP
Scope: Server/Model.
.RE
.TP
.B primary_ssh_command
Parameter that identifies a Barman server as \f[C]passive\f[].
In a passive node, the source of a backup server is a Barman
installation rather than a PostgreSQL server.
If \f[C]primary_ssh_command\f[] is specified, Barman uses it to
establish a connection with the primary server.
Empty by default, it can also be set globally.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B recovery_options
Options for recovery operations.
Currently only supports \f[C]get\-wal\f[].
\f[C]get\-wal\f[] activates generation of a basic
\f[C]restore_command\f[] in the resulting recovery configuration that
uses the \f[C]barman\ get\-wal\f[] command to fetch WAL files directly
from Barman\[aq]s archive of WALs.
Comma separated list of values, default empty.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B recovery_staging_path
A path to a location on the recovery host (either the barman server or a
remote host if \-\-remote\-ssh\-command is also used) where files for a
compressed backup will be staged before being uncompressed to the
destination directory.
Backups will be staged in their own directory within the staging path
according to the following naming convention:
"barman\-staging\-SERVER_NAME\-BACKUP_ID".
The staging directory within the staging path will be removed at the end
of the recovery process.
This option is \f[I]required\f[] when recovering from compressed backups
and has no effect otherwise.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B retention_policy
Policy for retention of periodic backups and archive logs.
If left empty, retention policies are not enforced.
For redundancy based retention policy use "REDUNDANCY i" (where i is an
integer > 0 and defines the number of backups to retain).
For recovery window retention policy use "RECOVERY WINDOW OF i DAYS" or
"RECOVERY WINDOW OF i WEEKS" or "RECOVERY WINDOW OF i MONTHS" where i is
a positive integer representing, specifically, the number of days, weeks
or months to retain your backups.
For more detailed information, refer to the official documentation.
Default value is empty.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B retention_policy_mode
Currently only "auto" is implemented.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B reuse_backup
This option controls incremental backup support.
Possible values are:
.RS
.IP \[bu] 2
\f[C]off\f[]: disabled (default);
.IP \[bu] 2
\f[C]copy\f[]: reuse the last available backup for a server and create a
copy of the unchanged files (reduce backup time);
.IP \[bu] 2
\f[C]link\f[]: reuse the last available backup for a server and create a
hard link of the unchanged files (reduce backup time and space).
Requires operating system and file system support for hard links.
.PP
Scope: Global/Server/Model.
.RE
.TP
.B slot_name
Physical replication slot to be used by the \f[C]receive\-wal\f[]
command when \f[C]streaming_archiver\f[] is set to \f[C]on\f[].
Default: None (disabled).
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B snapshot_disks
A comma\-separated list of disks which should be included in a backup
taken using cloud snapshots.
Required when the \f[C]snapshot\f[] value is specified for
\f[C]backup_method\f[].
.RS
.PP
Scope: Server/Model.
.RE
.TP
.B snapshot_instance
The name of the VM or compute instance where the storage volumes are
attached.
Required when the \f[C]snapshot\f[] value is specified for
\f[C]backup_method\f[].
.RS
.PP
Scope: Server/Model.
.RE
.TP
.B snapshot_provider
The name of the cloud provider which should be used to create snapshots.
Required when the \f[C]snapshot\f[] value is specified for
\f[C]backup_method\f[].
Supported values: \f[C]gcp\f[].
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B ssh_command
Command used by Barman to login to the Postgres server via ssh.
.RS
.PP
Scope: Server/Model.
.RE
.TP
.B streaming_archiver
This option allows you to use the PostgreSQL\[aq]s streaming protocol to
receive transaction logs from a server.
If set to \f[C]on\f[], Barman expects to find \f[C]pg_receivewal\f[]
(known as \f[C]pg_receivexlog\f[] prior to PostgreSQL 10) in the PATH
(see \f[C]path_prefix\f[] option) and that streaming connection for the
server is working.
This activates connection checks as well as management (including
compression) of WAL files.
If set to \f[C]off\f[] (default) barman will rely only on continuous
archiving for a server WAL archive operations, eventually terminating
any running \f[C]pg_receivexlog\f[] for the server.
Note: If neither \f[C]streaming_archiver\f[] nor \f[C]archiver\f[] are
set, Barman will automatically set \f[C]archiver\f[] to \f[C]true\f[].
This is in order to maintain parity with deprecated behaviour where
\f[C]archiver\f[] would be enabled by default.
This behaviour will be removed from the next major Barman version.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B streaming_archiver_batch_size
This option allows you to activate batch processing of WAL files for the
\f[C]streaming_archiver\f[] process, by setting it to a value > 0.
Otherwise, the traditional unlimited processing of the WAL queue is
enabled.
When batch processing is activated, the \f[C]archive\-wal\f[] process
would limit itself to maximum \f[C]streaming_archiver_batch_size\f[] WAL
segments per single run.
Integer.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B streaming_archiver_name
Identifier to be used as \f[C]application_name\f[] by the
\f[C]receive\-wal\f[] command.
Only available with \f[C]pg_receivewal\f[] (or \f[C]pg_receivexlog\f[]
>= 9.3).
By default it is set to \f[C]barman_receive_wal\f[].
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B streaming_backup_name
Identifier to be used as \f[C]application_name\f[] by the
\f[C]pg_basebackup\f[] command.
By default it is set to \f[C]barman_streaming_backup\f[].
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B streaming_conninfo
Connection string used by Barman to connect to the Postgres server via
streaming replication protocol.
By default it is set to \f[C]conninfo\f[].
.RS
.PP
Scope: Server/Model.
.RE
.TP
.B streaming_wals_directory
Directory where WAL files are streamed from the PostgreSQL server to
Barman.
Requires \f[C]streaming_archiver\f[] to be enabled.
.RS
.PP
Scope: Server.
.RE
.TP
.B tablespace_bandwidth_limit
This option allows you to specify a maximum transfer rate in kilobytes
per second, by specifying a comma separated list of tablespaces (pairs
TBNAME:BWLIMIT).
A value of zero specifies no limit (default).
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B wal_conninfo
A connection string which, if set, will be used by Barman to connect to
the Postgres server when checking the status of the replication slot
used for receiving WALs.
If left unset then Barman will use the connection string defined by
\f[C]wal_streaming_conninfo\f[].
If \f[C]wal_conninfo\f[] is set but \f[C]wal_streaming_conninfo\f[] is
unset then \f[C]wal_conninfo\f[] will be ignored.
.RS
.PP
Scope: Server/Model.
.RE
.TP
.B wal_retention_policy
Policy for retention of archive logs (WAL files).
Currently only "MAIN" is available.
.RS
.PP
Scope: Global/Server/Model.
.RE
.TP
.B wal_streaming_conninfo
A connection string which, if set, will be used by Barman to connect to
the Postgres server when receiving WAL segments via the streaming
replication protocol.
If left unset then Barman will use the connection string defined by
\f[C]streaming_conninfo\f[] for receiving WAL segments.
.RS
.PP
Scope: Server/Model.
.RE
.TP
.B wals_directory
Directory which contains WAL files.
.RS
.PP
Scope: Server.
.RE
.SH HOOK SCRIPTS
.PP
The script definition is passed to a shell and can return any exit code.
.PP
The shell environment will contain the following variables:
.TP
.B \f[C]BARMAN_CONFIGURATION\f[]
configuration file used by barman
.RS
.RE
.TP
.B \f[C]BARMAN_ERROR\f[]
error message, if any (only for the \[aq]post\[aq] phase)
.RS
.RE
.TP
.B \f[C]BARMAN_PHASE\f[]
\[aq]pre\[aq] or \[aq]post\[aq]
.RS
.RE
.TP
.B \f[C]BARMAN_RETRY\f[]
\f[C]1\f[] if it is a \f[I]retry script\f[] (from 1.5.0), \f[C]0\f[] if
not
.RS
.RE
.TP
.B \f[C]BARMAN_SERVER\f[]
name of the server
.RS
.RE
.PP
Backup scripts specific variables:
.TP
.B \f[C]BARMAN_BACKUP_DIR\f[]
backup destination directory
.RS
.RE
.TP
.B \f[C]BARMAN_BACKUP_ID\f[]
ID of the backup
.RS
.RE
.TP
.B \f[C]BARMAN_PREVIOUS_ID\f[]
ID of the previous backup (if present)
.RS
.RE
.TP
.B \f[C]BARMAN_NEXT_ID\f[]
ID of the next backup (if present)
.RS
.RE
.TP
.B \f[C]BARMAN_STATUS\f[]
status of the backup
.RS
.RE
.TP
.B \f[C]BARMAN_VERSION\f[]
version of Barman
.RS
.RE
.PP
Archive scripts specific variables:
.TP
.B \f[C]BARMAN_SEGMENT\f[]
name of the WAL file
.RS
.RE
.TP
.B \f[C]BARMAN_FILE\f[]
full path of the WAL file
.RS
.RE
.TP
.B \f[C]BARMAN_SIZE\f[]
size of the WAL file
.RS
.RE
.TP
.B \f[C]BARMAN_TIMESTAMP\f[]
WAL file timestamp
.RS
.RE
.TP
.B \f[C]BARMAN_COMPRESSION\f[]
type of compression used for the WAL file
.RS
.RE
.PP
Recovery scripts specific variables:
.TP
.B \f[C]BARMAN_DESTINATION_DIRECTORY\f[]
the directory where the new instance is recovered
.RS
.RE
.TP
.B \f[C]BARMAN_TABLESPACES\f[]
tablespace relocation map (JSON, if present)
.RS
.RE
.TP
.B \f[C]BARMAN_REMOTE_COMMAND\f[]
secure shell command used by the recovery (if present)
.RS
.RE
.TP
.B \f[C]BARMAN_RECOVER_OPTIONS\f[]
recovery additional options (JSON, if present)
.RS
.RE
.PP
Only in case of retry hook scripts, the exit code of the script is
checked by Barman.
Output of hook scripts is simply written in the log file.
.SH EXAMPLE
.PP
Here is an example of configuration file:
.IP
.nf
\f[C]
[barman]
;\ Main\ directory
barman_home\ =\ /var/lib/barman

;\ System\ user
barman_user\ =\ barman

;\ Log\ location
log_file\ =\ /var/log/barman/barman.log

;\ Default\ compression\ level
;compression\ =\ gzip

;\ Incremental\ backup
reuse_backup\ =\ link

;\ \[aq]main\[aq]\ PostgreSQL\ Server\ configuration
[main]
;\ Human\ readable\ description
description\ =\ \ "Main\ PostgreSQL\ Database"

;\ SSH\ options
ssh_command\ =\ ssh\ postgres\@pg

;\ PostgreSQL\ connection\ string
conninfo\ =\ host=pg\ user=postgres

;\ PostgreSQL\ streaming\ connection\ string
streaming_conninfo\ =\ host=pg\ user=postgres

;\ Minimum\ number\ of\ required\ backups\ (redundancy)
minimum_redundancy\ =\ 1

;\ Retention\ policy\ (based\ on\ redundancy)
retention_policy\ =\ REDUNDANCY\ 2
\f[]
.fi
.SH SEE ALSO
.PP
\f[C]barman\f[] (1).
.SH AUTHORS
.PP
Barman maintainers (in alphabetical order):
.IP \[bu] 2
Abhijit Menon\-Sen
.IP \[bu] 2
Jane Threefoot
.IP \[bu] 2
Michael Wallace
.PP
Past contributors (in alphabetical order):
.IP \[bu] 2
Anna Bellandi (QA/testing)
.IP \[bu] 2
Britt Cole (documentation reviewer)
.IP \[bu] 2
Carlo Ascani (developer)
.IP \[bu] 2
Francesco Canovai (QA/testing)
.IP \[bu] 2
Gabriele Bartolini (architect)
.IP \[bu] 2
Gianni Ciolli (QA/testing)
.IP \[bu] 2
Giulio Calacoci (developer)
.IP \[bu] 2
Giuseppe Broccolo (developer)
.IP \[bu] 2
Jonathan Battiato (QA/testing)
.IP \[bu] 2
Leonardo Cecchi (developer)
.IP \[bu] 2
Marco Nenciarini (project leader)
.IP \[bu] 2
Niccolò Fei (QA/testing)
.IP \[bu] 2
Rubens Souza (QA/testing)
.IP \[bu] 2
Stefano Bianucci (developer)
.SH RESOURCES
.IP \[bu] 2
Homepage: <https://www.pgbarman.org/>
.IP \[bu] 2
Documentation: <https://docs.pgbarman.org/>
.IP \[bu] 2
Professional support: <https://www.enterprisedb.com/>
.SH COPYING
.PP
Barman is the property of EnterpriseDB UK Limited and its code is
distributed under GNU General Public License v3.
.PP
© Copyright EnterpriseDB UK Limited 2011\-2023
.SH AUTHORS
EnterpriseDB <https://www.enterprisedb.com>.