Commit bddf1882 authored by Marco Nenciarini's avatar Marco Nenciarini

New upstream version 2.0

parent 92a658f6
......@@ -2,7 +2,7 @@ Barman Core Team (in alphabetical order):
* Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (project leader)
* Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
* Stefano Bianucci (developer)
* Stefano Bianucci (developer, intern from University of Florence)
* Giuseppe Broccolo <giuseppe.broccolo@2ndquadrant.it> (QA/testing)
* Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
* Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
......
2016-09-26 Marco Nenciarini <marco.nenciarini@2ndquadrant.it>
Update the ChangeLog file
2016-09-26 Gabriele Bartolini <gabriele.bartolini@2ndQuadrant.it>
Update architecture diagrams
2016-09-26 Marco Nenciarini <marco.nenciarini@2ndquadrant.it>
Review of example configurations in doc/barman.d/
2016-09-26 Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it>
Fix image size in manual
2016-09-26 Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it>
Set version to 2.0
2016-09-25 Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it>
General review of the manual before 2.0 release
2016-09-23 Giulio Calacoci <giulio.calacoci@2ndquadrant.it>
Add section `Upgrade from Barman 1.X` to manual.
2016-09-23 Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it>
Improve documentation of get-wal command
This patch improves the documentation of the get-wal command for the
local recovery, specifying that the command must be executed as `barman`
user and not as the user which is running the PostgreSQL server.
It also includes details about the barman-wal-restore command.
2016-09-23 Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it>
Update INSTALL, README and TODO files
2016-09-23 Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it>
Add Windows server documentation
Add a Windows server section in the "Setup a new server in Barman"
chapter.
2016-09-21 Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it>
Fix wrongly named max_replication_slots configuration parameter
2016-09-20 Marco Nenciarini <marco.nenciarini@2ndquadrant.it>
Update the ChangeLog file
......
......@@ -2,4 +2,5 @@ Barman INSTALL instructions
Copyright (C) 2011-2016 2ndQuadrant Italia Srl
For further information, see the "Installation" section in the
doc/barman-tutorial.en.md file.
official manual of Barman or the Markdown source file:
doc/manual/16-installation.en.md.
Barman News - History of user-visible changes
Copyright (C) 2011-2016 2ndQuadrant Italia Srl
Version 2.0b1 - 20 Sep 2016
Version 2.0 - 27 Sep 2016
- Support for pg_basebackup and base backups over the PostgreSQL
streaming replication protocol with backup_method=postgres
......@@ -19,21 +19,23 @@ Version 2.0b1 - 20 Sep 2016
servers using the standard rsync method of backup. Concurrent backup
was only possible for PostgreSQL 9.2 to 9.5 versions through the
pgespresso extension. The new backup API will make pgespresso
redundant in the future in this context
redundant in the future
- If properly configured, Barman can be configured as a synchronous
standby in terms of WAL streaming. By properly setting the
- If properly configured, Barman can function as a synchronous standby
in terms of WAL streaming. By properly setting the
streaming_archiver_name in the synchronous_standby_names priority
list on the master, and enabling replication slot support, the
receive-wal command can now be part of a PostgreSQL synchronous
replication cluster, bringing RPO=0 (PostgreSQL 9.5.5 or
higher required).
higher required)
- Introduce barman-wal-restore, a standard and robust script written
in Python that can be used as restore_command in recovery.conf files
of any standby server of a cluster. It supports remote parallel
fetching of WAL files by efficiently invoking get-wal through Ssh.
Currently available as a contrib script
fetching of WAL files by efficiently invoking get-wal through SSH.
Currently available as a separate project called barman-cli. The
barman-cli package is required for remote recovery when get-wal is
listed in recovery_options
- Control the maximum execution time of the check command through the
check_timeout global/server configuration option (30 seconds
......@@ -49,8 +51,12 @@ Version 2.0b1 - 20 Sep 2016
- The show-backup command is now aware of timelines and properly
displays which timelines can be used as recovery targets for a given
base backup. Internally, Barman is now capable of parsing
.history files.
base backup. Internally, Barman is now capable of parsing .history
files
- Improved the logic behind the retry mechanism when copy operations
experience problems. This involves backup (rsync and postgres) as
well as remote recovery (rsync)
- Code refactoring involving remote command and physical copy
interfaces
......@@ -63,6 +69,8 @@ Version 2.0b1 - 20 Sep 2016
available
- Fix misleading message on pg_receivexlog termination
Version 1.6.1 - 23 May 2016
- Add --peek option to get-wal command to discover existing WAL files
from the Barman's archive
......
Metadata-Version: 1.1
Name: barman
Version: 2.0b1
Version: 2.0
Summary: Backup and Recovery Manager for PostgreSQL
Home-page: http://www.pgbarman.org/
Author: 2ndQuadrant Italia Srl
Author-email: info@2ndquadrant.it
License: GPL-3.0
Description: Barman (Backup and Recovery Manager) is an open source administration
Description: Barman (Backup and Recovery Manager) is an open-source administration
tool for disaster recovery of PostgreSQL servers written in Python.
It allows your organisation to perform remote backups of multiple servers
in business critical environments and help DBAs during the recovery
phase. Barman's most requested features include backup catalogues,
incremental backup, retention policies, remote backup and recovery,
archiving and compression of WAL files and backups.
It allows your organisation to perform remote backups of multiple
servers in business critical environments to reduce risk and help DBAs
during the recovery phase.
Barman is written and maintained by PostgreSQL professionals 2ndQuadrant.
Barman is distributed under GNU GPL 3 and maintained by 2ndQuadrant.
Platform: Linux
Platform: Mac OS X
......
# Barman, Backup and Recovery Manager for PostgreSQL
Barman (Backup and Recovery Manager) is an open source administration
Barman (Backup and Recovery Manager) is an open-source administration
tool for disaster recovery of PostgreSQL servers written in Python.
It allows your organisation to perform remote backups of multiple
servers in business critical environments and to help DBAs during
the recovery phase.
servers in business critical environments to reduce risk and help DBAs
during the recovery phase.
Barman's most requested features include backup catalogues, incremental
backup, retention policies, remote backup and recovery, archiving and
compression of WAL files and backups.
Barman is maintained by 2ndQuadrant and is distributed under GNU GPL 3.
Barman is distributed under GNU GPL 3 and maintained by 2ndQuadrant.
For further information, look at the "Web resources" section below.
......@@ -21,23 +17,27 @@ Here you can find a description of files and directory distributed
with Barman:
* AUTHORS : development team of Barman
* NEWS : release notes
* ChangeLog : log of changes
* LICENSE : GNU GPL3 details
* TODO : our wishlist for Barman
* barman : sources in Python
* doc : tutorial and man pages
* rpm : SPEC files for RHEL distributions
* scripts : auxiliary scripts
* tests : unit tests
## Web resources
* Website : http://www.pgbarman.org/
* Download : http://sourceforge.net/projects/pgbarman/files/
* Documentation : http://www.pgbarman.org/documentation/
* Man page, section 1 : http://docs.pgbarman.org/barman.1.html
* Man page, section 5 : http://docs.pgbarman.org/barman.5.html
* Community support : http://www.pgbarman.org/support/
* Professional support : http://www.2ndquadrant.com/
* Client utilities : https://github.com/2ndquadrant-it/barman-cli
* pgespresso extension : https://github.com/2ndquadrant-it/pgespresso
......
Metadata-Version: 1.1
Name: barman
Version: 2.0b1
Version: 2.0
Summary: Backup and Recovery Manager for PostgreSQL
Home-page: http://www.pgbarman.org/
Author: 2ndQuadrant Italia Srl
Author-email: info@2ndquadrant.it
License: GPL-3.0
Description: Barman (Backup and Recovery Manager) is an open source administration
Description: Barman (Backup and Recovery Manager) is an open-source administration
tool for disaster recovery of PostgreSQL servers written in Python.
It allows your organisation to perform remote backups of multiple servers
in business critical environments and help DBAs during the recovery
phase. Barman's most requested features include backup catalogues,
incremental backup, retention policies, remote backup and recovery,
archiving and compression of WAL files and backups.
It allows your organisation to perform remote backups of multiple
servers in business critical environments to reduce risk and help DBAs
during the recovery phase.
Barman is written and maintained by PostgreSQL professionals 2ndQuadrant.
Barman is distributed under GNU GPL 3 and maintained by 2ndQuadrant.
Platform: Linux
Platform: Mac OS X
......
......@@ -61,6 +61,7 @@ doc/manual/23-wal_streaming.en.md
doc/manual/24-wal_archiving.en.md
doc/manual/25-streaming_backup.en.md
doc/manual/26-rsync_backup.en.md
doc/manual/27-windows-support.en.md
doc/manual/41-global-commands.en.md
doc/manual/42-server-commands.en.md
doc/manual/43-backup-commands.en.md
......
{"is_release": true, "git_version": "da973a4"}
\ No newline at end of file
{"is_release": true, "git_version": "b6bec3e"}
\ No newline at end of file
......@@ -19,4 +19,4 @@
This module contains the current Barman version.
'''
__version__ = '2.0b1'
__version__ = '2.0'
.\" Automatically generated by Pandoc 1.17.2
.\" Automatically generated by Pandoc 1.17.1
.\"
.TH "BARMAN" "1" "September 20, 2016" "Barman User manuals" "Version 2.0b1"
.TH "BARMAN" "1" "September 27, 2016" "Barman User manuals" "Version 2.0"
.hy
.SH NAME
.PP
......@@ -508,7 +508,9 @@ In alphabetical order:
.IP \[bu] 2
Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (project leader)
.IP \[bu] 2
Stefano Bianucci <stefano.bianucci@2ndquadrant.it> (developer)
Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
.IP \[bu] 2
Stefano Bianucci (developer, intern from University of Florence)
.IP \[bu] 2
Giuseppe Broccolo <giuseppe.broccolo@2ndquadrant.it> (QA/testing)
.IP \[bu] 2
......@@ -520,7 +522,11 @@ Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
.IP \[bu] 2
Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
.IP \[bu] 2
Britt Cole <britt.cole@2ndquadrant.it> (documentation)
.IP \[bu] 2
Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (lead developer)
.IP \[bu] 2
Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
.PP
Past contributors:
.IP \[bu] 2
......
% BARMAN(1) Barman User manuals | Version 2.0b1
% BARMAN(1) Barman User manuals | Version 2.0
% 2ndQuadrant Italy <http://www.2ndQuadrant.it>
% September 20, 2016
% September 27, 2016
# NAME
......@@ -373,14 +373,17 @@ the `barman diagnose` command.
In alphabetical order:
- Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (project leader)
- Stefano Bianucci <stefano.bianucci@2ndquadrant.it> (developer)
- Giuseppe Broccolo <giuseppe.broccolo@2ndquadrant.it> (QA/testing)
- Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
- Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
- Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
- Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
- Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (lead developer)
* Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (project leader)
* Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
* Stefano Bianucci (developer, intern from University of Florence)
* Giuseppe Broccolo <giuseppe.broccolo@2ndquadrant.it> (QA/testing)
* Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
* Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
* Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
* Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
* Britt Cole <britt.cole@2ndquadrant.it> (documentation)
* Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (lead developer)
* Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
Past contributors:
......
.\" Automatically generated by Pandoc 1.17.1
.\"
.TH "BARMAN" "5" "September 20, 2016" "Barman User manuals" "Version 2.0b1"
.TH "BARMAN" "5" "September 27, 2016" "Barman User manuals" "Version 2.0"
.hy
.SH NAME
.PP
......@@ -71,7 +71,7 @@ Server.
.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[] (default), Barman expects that continous
If set to \f[C]true\f[] (default), 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.
......@@ -652,7 +652,9 @@ In alphabetical order:
.IP \[bu] 2
Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (project leader)
.IP \[bu] 2
Stefano Bianucci <stefano.bianucci@2ndquadrant.it> (developer)
Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
.IP \[bu] 2
Stefano Bianucci (developer, intern from University of Florence)
.IP \[bu] 2
Giuseppe Broccolo <giuseppe.broccolo@2ndquadrant.it> (QA/testing)
.IP \[bu] 2
......@@ -664,7 +666,11 @@ Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
.IP \[bu] 2
Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
.IP \[bu] 2
Britt Cole <britt.cole@2ndquadrant.it> (documentation)
.IP \[bu] 2
Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (lead developer)
.IP \[bu] 2
Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
.PP
Past contributors:
.IP \[bu] 2
......
% BARMAN(5) Barman User manuals | Version 2.0b1
% BARMAN(5) Barman User manuals | Version 2.0
% 2ndQuadrant Italy <http://www.2ndQuadrant.it>
% September 20, 2016
% September 27, 2016
# NAME
barman - Backup and Recovery Manager for PostgreSQL
......@@ -56,7 +56,7 @@ active
archiver
: This option allows you to activate log file shipping through PostgreSQL's
`archive_command` for a server. If set to `true` (default), Barman expects
that continous archiving for a server is in place and will activate
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 *incoming* directory. Setting it to `false`,
will disable standard continuous archiving for a server. Global/Server.
......@@ -436,14 +436,17 @@ retention_policy = REDUNDANCY 2
In alphabetical order:
- Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (project leader)
- Stefano Bianucci <stefano.bianucci@2ndquadrant.it> (developer)
- Giuseppe Broccolo <giuseppe.broccolo@2ndquadrant.it> (QA/testing)
- Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
- Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
- Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
- Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
- Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (lead developer)
* Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> (project leader)
* Jonathan Battiato <jonathan.battiato@2ndquadrant.it> (QA/testing)
* Stefano Bianucci (developer, intern from University of Florence)
* Giuseppe Broccolo <giuseppe.broccolo@2ndquadrant.it> (QA/testing)
* Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
* Francesco Canovai <francesco.canovai@2ndquadrant.it> (QA/testing)
* Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
* Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
* Britt Cole <britt.cole@2ndquadrant.it> (documentation)
* Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (lead developer)
* Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
Past contributors:
......
......@@ -2,12 +2,12 @@
; http://www.pgbarman.org/ - http://www.2ndQuadrant.com/
;
; Template configuration file for a server using
; Ssh connections and rsync for copy.
; SSH connections and rsync for copy.
;
[ssh]
; Human readable description
description = "Example of PostgreSQL Database (via Ssh)"
description = "Example of PostgreSQL Database (via SSH)"
; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; SSH options (mandatory)
......@@ -17,10 +17,10 @@ ssh_command = ssh postgres@pg
; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; PostgreSQL connection string (mandatory)
; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
conninfo = host=pg user=barman
conninfo = host=pg user=barman dbname=postgres
; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Backup settings (via rsync over Ssh)
; Backup settings (via rsync over SSH)
; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
backup_method = rsync
; Incremental backup support: possible values are None (default), link or copy
......@@ -36,4 +36,4 @@ archiver = on
;archiver_batch_size = 50
; PATH setting for this server
;path_prefix = "/usr/pgsql-9.3/bin"
;path_prefix = "/usr/pgsql-9.6/bin"
......@@ -12,7 +12,7 @@ description = "Example of PostgreSQL Database (Streaming-Only)"
; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; PostgreSQL connection string (mandatory)
; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
conninfo = host=pg user=barman
conninfo = host=pg user=barman dbname=postgres
; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; PostgreSQL streaming connection string
......
% Manual
% 2ndQuadrant Italia
% September 20, 2016 (v2.0b1)
% September 27, 2016 (v2.0)
**Barman** (Backup and Recovery Manager) is an open-source administration tool for disaster recovery of PostgreSQL servers written in Python. It allows your organisation to perform remote backups of multiple servers in business critical environments to reduce risk and help DBAs during the recovery phase.
......
......@@ -25,7 +25,7 @@ Within business continuity, it is important to familiarise with two fundamental
In a few words, RPO represents the maximum amount of data you can afford to lose, while RTO represents the maximum down-time you can afford for your service.
Understandably, we all want **RPO=0** (*"zero data loss"*) and **RTO=0** (*zero down-time*, utopia) - even if it is our grandmothers's recipes book that we are serving.
Understandably, we all want **RPO=0** (*"zero data loss"*) and **RTO=0** (*zero down-time*, utopia) - even if it is our grandmothers's recipe website.
In reality, a careful cost analysis phase allows you to determine your business continuity requirements.
Fortunately, with an open source stack composed of **Barman** and **PostgreSQL**, you can achieve RPO=0 thanks to synchronous streaming replication. RTO is more the focus of a *High Availability* solution, like [**repmgr**] [repmgr]. Therefore, by integrating Barman and repmgr, you can dramatically reduce RTO to nearly zero.
......@@ -37,11 +37,11 @@ In any case, it is important for us to emphasise more on cultural aspects relate
Our mission with Barman is to promote a culture of disaster recovery that:
- focuses on backup procedures
- focuses even more on recovery procedures (hence the name Barman with the 'B' and the 'R')
- focuses even more on recovery procedures
- relies on education and training on strong theoretical and practical concepts of PostgreSQL's crash recovery, backup, Point-In-Time-Recovery, and replication for your team members
- promotes testing your backups (only a backup that is tested can be considered to be valid), either manually or automatically (be creative with Barman's hook scripts!)
- fosters regular practice of recovery procedures, by all members of your devops team (yes, developers too, not just system administrators and DBAs)
- solicites to regularly scheduled drills and disaster recovery simulations with your team every 3-6 months
- solicites to regularly scheduled drills and disaster recovery simulations with the team every 3-6 months
- relies on continuous monitoring of PostgreSQL and Barman, and that is able to promptly identify any anomalies
Moreover, do everything you can to prepare yourself and your team for when the disaster happens (yes, *when*), because when it happens:
......
......@@ -36,7 +36,7 @@ Remember that no decision is forever. You can start this way and adapt over time
Another relevant feature that was first introduced by Barman is support for multiple servers. Barman can store backup data coming from multiple PostgreSQL instances, even with different versions, in a centralised way. [^recver]
[^recver]: The same [requirements for PostgreSQL's PITR] [requirements_recovery] apply for recovery.
[^recver]: The same [requirements for PostgreSQL's PITR][requirements_recovery] apply for recovery, as detailed in the section _"Requirements for recovery"_.
As a result, you can model complex disaster recovery architectures, forming a "star schema", where PostgreSQL servers rotate around a central Barman server.
......@@ -49,7 +49,7 @@ From this point forward, for the sake of simplicity, this guide will assume a ba
## Streaming backup vs rsync/SSH
Traditionally, Barman has always operated remotely via SSH, taking advantage of `rsync` for physical backup operations. Version 2 introduces native support for PostgreSQL's streaming replication protocol for backup operations, via `pg_basebackup`. [^fmatrix]
Traditionally, Barman has always operated remotely via SSH, taking advantage of `rsync` for physical backup operations. Version 2.0 introduces native support for PostgreSQL's streaming replication protocol for backup operations, via `pg_basebackup`. [^fmatrix]
[^fmatrix]: Check in the "Feature matrix" which PostgreSQL versions support streaming replication backups with Barman.
......@@ -64,7 +64,7 @@ Traditional backup via `rsync`/SSH is available for all versions of PostgreSQL s
The reason why we recommend streaming backup is that, based on our experience, it is easier to setup than the traditional one. Also, streaming backup allows you to backup a PostgreSQL server on Windows[^windows], and makes life easier when working with Docker.
[^windows]: Backup of a PostgreSQL server on Windows is possible, but it is still experimental because it is not yet part of our continuous integration system.
[^windows]: Backup of a PostgreSQL server on Windows is possible, but it is still experimental because it is not yet part of our continuous integration system. See section _"How to setup a Windows based server"_ for details.
## Standard archiving, WAL streaming ... or both
......@@ -85,14 +85,14 @@ In order to make life easier for you, below we summarise the two most typical sc
Bear in mind that this is a decision that you must make for every single server that you decide to back up with Barman. This means that you can have heterogeneous setups within the same installation.
As mentioned before, we will only worry about the PostgreSQL server (`pg`) and the Barman server (`backup`). However, in real life, your architecture will most likely contain other technologies such as repmgr, pgBouncer, Nagios/Icinga, etc.
As mentioned before, we will only worry about the PostgreSQL server (`pg`) and the Barman server (`backup`). However, in real life, your architecture will most likely contain other technologies such as repmgr, pgBouncer, Nagios/Icinga, and so on.
### Scenario 1: Backup via streaming protocol
If you are using PostgreSQL 9.4 or higher, and your database falls under a general use case scenario, you will likely end up deciding for a streaming backup installation - see figure \ref{scenario1-design} below.
If you are using PostgreSQL 9.4 or higher, and your database falls under a general use case scenario, you will likely end up deciding on a streaming backup installation - see figure \ref{scenario1-design} below.
<!-- TODO: This way of referencing won't work in HTML -->
![Streaming-only backup (Scenario 1)\label{scenario1-design}](../images/barman-architecture-scenario1.png){ width=10cm }
![Streaming-only backup (Scenario 1)\label{scenario1-design}](../images/barman-architecture-scenario1.png){ width=80% }
In this scenario, you will need to configure:
......@@ -103,7 +103,7 @@ This setup, in Barman's terminology, is known as **streaming-only** setup, as it
However, as mentioned before, you can configure standard archiving as well and implement a more robust architecture - see figure \ref{scenario1b-design} below.
![Streaming backup with WAL archiving (Scenario 1b)\label{scenario1b-design}](../images/barman-architecture-scenario1b.png){ width=10cm }
![Streaming backup with WAL archiving (Scenario 1b)\label{scenario1b-design}](../images/barman-architecture-scenario1b.png){ width=80% }
This alternate approach requires:
......@@ -123,7 +123,7 @@ The _traditional_ setup of `rsync` over SSH is the only available option for:
- network compression during backups
- finer control of bandwidth usage, including on a tablespace basis
![Scenario 2 - Backup via rsync/SSH](../images/barman-architecture-scenario2.png){ width=10cm }
![Scenario 2 - Backup via rsync/SSH](../images/barman-architecture-scenario2.png){ width=80% }
In this scenario, you will need to configure:
......@@ -133,6 +133,6 @@ In this scenario, you will need to configure:
Starting from PostgreSQL 9.2, you can add a streaming replication connection that is used for WAL streaming and significantly reduce RPO. This more robust implementation is depicted in figure \ref{scenario2b-design}.
![Backup via rsync/SSH with WAL streaming (Scenario 2b)\label{scenario2b-design}](../images/barman-architecture-scenario2b.png){ width=10cm }
![Backup via rsync/SSH with WAL streaming (Scenario 2b)\label{scenario2b-design}](../images/barman-architecture-scenario2b.png){ width=80% }
<!-- TODO - Add a section on architecture for recovery? -->
......@@ -14,12 +14,12 @@
- PostgreSQL >= 8.3
- rsync >= 3.0.4 (optional for PostgreSQL >= 9.2)
> **Important:**
> **IMPORTANT:**
> Users of RedHat Enterprise Linux, CentOS and Scientific Linux are
> required to install the
> [Extra Packages Enterprise Linux (EPEL) repository] [epel].
> **Note:**
> **NOTE:**
> Python 3 support is experimental. Report any bug through
> the ticketing system on Github or the mailing list.
......
......@@ -2,7 +2,7 @@
# Installation
> **Important:**
> **IMPORTANT:**
> The recommended way to install Barman is by using the available
> packages for your GNU/Linux distribution.
......@@ -36,10 +36,10 @@ It is directly available in the official repository for Debian and Ubuntu, howev
If you want to have the latest version of Barman, the recommended method is to install it through the [PostgreSQL Community APT repository] [aptpgdg].
Instructions can be found in the [APT section of the PostgreSQL Wiki] [aptpgdgwiki].
> **Note:**
> **NOTE:**
> Thanks to the direct involvement of Barman developers in the
> PostgreSQL Community APT repository project, you will have access to
> the most updated versions of Barman.
> PostgreSQL Community APT repository project, you will always have access
> to the most updated versions of Barman.
Installing Barman is as easy. As `root` user simply type:
......@@ -75,4 +75,24 @@ barman@backup$ ./setup.py install --user
The `barman` application will be installed in your user directory ([make sure that your `PATH` environment variable is set properly] [setup_user]).
[Barman is also available on the Python Package Index (PyPI)] [pypi] and can be installed through `pip`.
\ No newline at end of file
[Barman is also available on the Python Package Index (PyPI)] [pypi] and can be installed through `pip`.
## Upgrading from Barman 1.X
Version 2.0 requires that users explicitly configure
their archiving strategy. Before, the file based
archiver, controlled by `archiver`, was enabled by default.
When you upgrade your Barman installation to 2.0, make sure
you add the following line either globally or for any server
that requires it:
``` ini
archiver = on
```
Additionally, for a few releases, Barman will transparently set
`archiver = on` with any server that has not explicitly set
an archiving strategy and emit a warning.
Besides that, version 2.0 is fully compatible with older ones.
......@@ -45,10 +45,10 @@ There are two reserved words that cannot be used as server names in Barman:
- `barman`: identifier of the global section
- `all`: a handy shortcut that allows you to execute some commands on every server managed by Barman in sequence
Barman implements the **convention over configuration** design paradigm, which attempts to reduce the number of options that you are required to configure without losing flexibility. Therefore, some server options can be defined at global level and overridden at server level, allowing users to specify a generic behaviour and refine it for one or more servers. These options have a global/server scope.
Barman implements the **convention over configuration** design paradigm, which attempts to reduce the number of options that you are required to configure without losing flexibility. Therefore, some server options can be defined at global level and overridden at server level, allowing users to specify a generic behavior and refine it for one or more servers. These options have a global/server scope.
For a list of all the available configurations
and their scope, please refer to [section 5 of the man page] [man5].
and their scope, please refer to [section 5 of the 'man' page] [man5].
``` bash
man 5 barman
......
......@@ -2,8 +2,11 @@
# Setup of a new server in Barman
As mentioned in the _"Design and architecture"_ section, we will use the following conventions:
As mentioned in the _"Design and architecture"_ section, we will use the
following conventions:
- `pg` as server ID and host name where PostgreSQL is installed
- `backup` as host name where Barman is located
- `barman` as the user running Barman on the `backup` server (identified by
the parameter `barman_user` in the configuration)
- `postgres` as the user running PostgreSQL on the `pg` server
......@@ -76,8 +76,9 @@ wal_level = 'replica'
```
For PostgreSQL versions older than 9.6, `wal_level` must be set to
`hot_standby`. Restart the PostgreSQL server for the configuration to
be refreshed.
`hot_standby`.
Restart the PostgreSQL server for the configuration to be refreshed.
### PostgreSQL streaming connection
......@@ -104,8 +105,9 @@ barman@backup$ psql -U streaming_barman -h pg \
replication=1
```
Please make sure you are able to connect via streaming replication
before going any further.
> **IMPORTANT:**
> Please make sure you are able to connect via streaming replication
> before going any further.
You also need to configure the `max_wal_senders` parameter in the
PostgreSQL configuration file:
......@@ -115,22 +117,24 @@ max_wal_senders = 2
```
This option represents the maximum number of concurrent streaming
connection that the server will be allowed to manage.
connections that the server will be allowed to manage.
Another important parameter is `max_replication_slot`, which represent
the maximum number of replication slots that the server will be
allowed to manage. This parameter is needed if you are planning to use
the streaming connection to receive WAL files over the streaming
Another important parameter is `max_replication_slots`, which
represents the maximum number of replication slots [^replslot94]
that the server will be allowed to manage.
This parameter is needed if you are planning to
use the streaming connection to receive WAL files over the streaming
connection:
``` ini
max_replication_slots = 2
```
The `max_replication_slot` option represents the maximum number of
replication slots that the server will be allowed to manage.
[^replslot94]: Replication slots have been introduced in PostgreSQL 9.4.
See section _"WAL Streaming / Replication slots"_ for
details.
The values proposed for `max_replication_slot` and `max_wal_senders`
The values proposed for `max_replication_slots` and `max_wal_senders`
must be considered as examples, and the values you will use in your
actual setup must be choosen after a careful evaluation of the
architecture. Please consult the PostgreSQL documentation for
......@@ -140,17 +144,18 @@ guidelines and clarifications.
### SSH connections
SSH is a protocol and a set of tools that allows you to open a remote
shell to remote server and copy files between the server and the local
shell to a remote server and copy files between the server and the local
system. You can find more documentation about SSH usage in the article
[SSH Essentials][ssh_essentials] by Digital Ocean.
["SSH Essentials"][ssh_essentials] by Digital Ocean.
SSH key exchange is a very common practice that is used to implement
secure passwordless connections between users on different machines,
and it's needed to use `rsync` for WAL archiving and for backups.
This procedure is not needed if you plan to use the streaming
connection only to archive transaction logs and backup your PostgreSQL
server.
> **NOTE:**
> This procedure is not needed if you plan to use the streaming
> connection only to archive transaction logs and backup your PostgreSQL
> server.
[ssh_essentials]: https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys
......@@ -189,7 +194,7 @@ To successfully connect from the PostgreSQL server to the backup
server, the PostgreSQL public key has to be configured into the
authorized keys of the backup server for the `barman` user.
The public key to be authorized is stored inside the postgres user
The public key to be authorized is stored inside the `postgres` user
home directory in a file named `.ssh/id_rsa.pub`, and its content
should be included in a file named `.ssh/authorized_keys` inside the
home directory of the `barman` user in the backup server. If the
......@@ -215,7 +220,7 @@ connection from the PostgreSQL server to the backup server, we should
authorize the public key of the backup server in the PostgreSQL server
for the `postgres` user.
The content of the file `.ssh/id_rsa.pub` in the barman server should
The content of the file `.ssh/id_rsa.pub` in the `barman` server should
be put in the file named `.ssh/authorized_keys` in the PostgreSQL
server. The permissions of that file should be `600`.
......
......@@ -9,7 +9,7 @@ available from PostgreSQL 9.2 which exploits the native streaming
replication protocol and continuously receives transaction logs from a
PostgreSQL server (master or standby).
> **Important:**
> **IMPORTANT:**
> Barman requires that `pg_receivexlog` is installed on the same
> server. For PostgreSQL 9.2 servers, you need `pg_receivexlog` of
> version 9.2 installed alongside Barman. For PostgreSQL 9.3 and
......@@ -34,7 +34,7 @@ However, users can manually execute the `receive-wal` command:
barman receive-wal <server_name>
```
> **Note:**
> **NOTE:**
> The `receive-wal` command is a foreground process.
Transaction logs are streamed directly in the directory specified by the
......@@ -50,7 +50,7 @@ PostgreSQL server.
### Replication slots
> **Important:** replication slots are available since PostgreSQL 9.4
> **IMPORTANT:** replication slots are available since PostgreSQL 9.4
Replication slots are an automated way to ensure that the PostgreSQL
server will not remove WAL files until they were received by all
......@@ -64,10 +64,9 @@ You can even base your backup architecture on streaming connection
only. This scenario is useful to configure Docker-based PostgreSQL
servers and even to work with PostgreSQL servers running on Windows.
In this moment, the Windows support is still experimental, as it is
not yet part of our continuous integration system.