pgbackrest.git / summary / log / commit / refs
commit 7c95a2f4de43905bc7b22afbc8d70432156bc033
Author: David Steele <david@pgmasters.net>
Date: Sat Sep 09 04:50:00 2017 +0000
Updates to installation documentation.
* Add trusted SSH configuration.
* Add full installation where required and remove doc containers that included parts of the installation.
doc/xml/release.xml | 8 +
doc/xml/user-guide.xml | 520 +++++++++++++-----------
test/lib/pgBackRestTest/Common/ContainerTest.pm | 45 --
3 files changed, 297 insertions(+), 276 deletions(-)
diff --git a/doc/xml/release.xml b/doc/xml/release.xml
index 133702ab9..c3704d6a9 100644
--- a/doc/xml/release.xml
+++ b/doc/xml/release.xml
@@ -28,6 +28,14 @@
<release-item>
<p>Rename <proper>master</proper> to <proper>primary</proper> in documentation to align with <postgres/> convention.</p>
</release-item>
+
+ <release-item>
+ <p>Add trusted SSH configuration.</p>
+ </release-item>
+
+ <release-item>
+ <p>Add full installation where required and remove doc containers that included parts of the installation.</p>
+ </release-item>
</release-refactor-list>
</release-doc-list>
</release>
diff --git a/doc/xml/user-guide.xml b/doc/xml/user-guide.xml
index 33128f17f..8f22dcc63 100644
--- a/doc/xml/user-guide.xml
+++ b/doc/xml/user-guide.xml
@@ -23,10 +23,16 @@
<variable key="pg-version-upgrade" keyword="default">9.5</variable>
<variable key="pg-version-upgrade" keyword="co6">9.6</variable>
+ <variable key="pg-home-path">/home/postgres</variable>
+
<variable key="perl-lib-path">/usr/share/perl5</variable>
<variable key="perl-bin-path">/usr/bin</variable>
<variable key="backrest-repo-path">/var/lib/pgbackrest</variable>
+ <variable key="br-user">backrest</variable>
+ <variable key="br-group">{[br-user]}</variable>
+ <variable key="br-home-path">/home/{[br-user]}</variable>
+
<variable key="postgres-cluster-demo">demo</variable>
<variable key="backrest-config-demo">/etc/{[project-exe]}.conf</variable>
@@ -56,7 +62,7 @@
<variable key="postgres-hba-demo-upgrade" keyword="default">/etc/postgresql/{[pg-version-upgrade]}/{[postgres-cluster-demo]}/pg_hba.conf</variable>
<variable key="postgres-hba-demo-upgrade" keyword="co6">{[db-path-upgrade]}/pg_hba.conf</variable>
- <variable key="postgres-pgpass">/home/postgres/.pgpass</variable>
+ <variable key="postgres-pgpass">{[pg-home-path]}/.pgpass</variable>
<variable key="postgres-log-demo" keyword="default">/var/log/postgresql/postgresql-{[pg-version]}-{[postgres-cluster-demo]}.log</variable>
<variable key="postgres-log-demo" keyword="co6">{[db-path]}/pg_log/postgresql.log</variable>
@@ -78,7 +84,7 @@
<variable key="host-db-primary">db-primary</variable>
<variable key="host-db-primary-user">{[host-user]}</variable>
- <variable key="host-db-primary-image">{[image-repo]}:{[host-os]}-doc-db</variable>
+ <variable key="host-db-primary-image">{[image-repo]}:{[host-os]}-base</variable>
<variable key="host-db-primary-mount">{[host-mount]}</variable>
<variable key="host-db-standby">db-standby</variable>
@@ -88,7 +94,7 @@
<variable key="host-backup">backup</variable>
<variable key="host-backup-user">{[host-user]}</variable>
- <variable key="host-backup-image">{[image-repo]}:{[host-os]}-doc-backup</variable>
+ <variable key="host-backup-image">{[image-repo]}:{[host-os]}-base</variable>
<variable key="host-backup-mount">{[host-mount]}</variable>
<!-- Commands for various operations -->
@@ -98,7 +104,7 @@
<variable key="test-table-data">Important Data</variable>
<!-- Database cluster commmands -->
- <variable key="db-cluster-wait">sleep 1</variable>
+ <variable key="db-cluster-wait">sleep 2</variable>
<variable key="db-cluster-create" keyword="default">pg_createcluster {[pg-version]} {[postgres-cluster-demo]}</variable>
<variable key="db-cluster-create" keyword="co6">service postgresql-{[pg-version]} initdb</variable>
@@ -125,91 +131,70 @@
<variable key="db-cluster-check-upgrade" keyword="co6">service postgresql-{[pg-version-upgrade]} status</variable>
</variable-list>
- <!-- SECTION => INTRODUCTION -->
- <section id="introduction">
- <title>Introduction</title>
-
- <p>This user guide is intended to be followed sequentially from beginning to end &mdash; each section depends on the last. For example, the <link section="/backup">Backup</link> section relies on setup that is performed in the <link section="/quickstart">Quick Start</link> section. Once <backrest/> is up and running then skipping around is possible but following the user guide in order is recommended the first time through.</p>
-
- <p>Although the examples are targeted at {[user-guide-os]} and <postgres/> {[pg-version]}, it should be fairly easy to apply this guide to any Unix distribution and <postgres/> version. Note that only 64-bit distributions are currently supported due to 64-bit operations in the Perl code. The only OS-specific commands are those to create, start, stop, and drop <postgres/> clusters. The <backrest/> commands will be the same on any Unix system though the locations to install Perl libraries and executables may vary.
-
- Configuration information and documentation for PostgreSQL can be found in the <postgres/> <link url='http://www.postgresql.org/docs/{[pg-version]}/static/index.html'>Manual</link>.</p>
-
- <p>A somewhat novel approach is taken to documentation in this user guide. Each command is run on a virtual machine when the documentation is built from the XML source. This means you can have a high confidence that the commands work correctly in the order presented. Output is captured and displayed below the command when appropriate. If the output is not included it is because it was deemed not relevant or was considered a distraction from the narrative.</p>
-
- <p>All commands are intended to be run as an unprivileged user that has sudo privileges for both the <user>root</user> and <user>postgres</user> users. It's also possible to run the commands directly as their respective users without modification and in that case the <cmd>sudo</cmd> commands can be stripped off.</p>
- </section>
+ <!-- ======================================================================================================================= -->
+ <block-define id="setup-ssh-intro">
+ <p><backrest/> requires trusted (no password) SSH to enable communication between the hosts.</p>
+ </block-define>
- <!-- SECTION => CONCEPTS -->
- <section id="concept">
- <title>Concepts</title>
+ <block-define id="setup-ssh">
+ <execute-list host="{[setup-ssh-host]}">
+ <title>Create <host>{[setup-ssh-host]}</host> host key pair</title>
- <p>The following concepts are defined as they are relevant to <backrest/>, <postgres/>, and this user guide.</p>
-
- <!-- SECTION => CONCEPTS - BACKUP -->
- <section id="backup">
- <title>Backup</title>
-
- <p>A backup is a consistent copy of a database cluster that can be restored to recover from a hardware failure, to perform Point-In-Time Recovery, or to bring up a new standby.</p>
-
- <p><b>Full Backup</b>: <backrest/> copies the entire contents of the database cluster to the backup server. The first backup of the database cluster is always a Full Backup. <backrest/> is always able to restore a full backup directly. The full backup does not depend on any files outside of the full backup for consistency.</p>
-
- <p><b>Differential Backup</b>: <backrest/> copies only those database cluster files that have changed since the last full backup. <backrest/> restores a differential backup by copying all of the files in the chosen differential backup and the appropriate unchanged files from the previous full backup. The advantage of a differential backup is that it requires less disk space than a full backup, however, the differential backup and the full backup must both be valid to restore the differential backup.</p>
+ <execute user="postgres">
+ <exe-cmd>mkdir -m 750 -p {[pg-home-path]}/.ssh</exe-cmd>
+ </execute>
+ <execute user="postgres">
+ <exe-cmd>ssh-keygen -f {[pg-home-path]}/.ssh/id_rsa -t rsa -b 4096 -N ""</exe-cmd>
+ </execute>
+ </execute-list>
- <p><b>Incremental Backup</b>: <backrest/> copies only those database cluster files that have changed since the last backup (which can be another incremental backup, a differential backup, or a full backup). As an incremental backup only includes those files changed since the prior backup, they are generally much smaller than full or differential backups. As with the differential backup, the incremental backup depends on other backups to be valid to restore the incremental backup. Since the incremental backup includes only those files since the last backup, all prior incremental backups back to the prior differential, the prior differential backup, and the prior full backup must all be valid to perform a restore of the incremental backup. If no differential backup exists then all prior incremental backups back to the prior full backup, which must exist, and the full backup itself must be valid to restore the incremental backup.</p>
- </section>
+ <p>Exchange keys between <host>{[host-backup]}</host> and <host>{[setup-ssh-host]}</host>.</p>
- <!-- SECTION => CONCEPTS - RESTORE -->
- <section id="restore">
- <title>Restore</title>
+ <execute-list host="{[host-backup]}">
+ <title>Copy <host>{[setup-ssh-host]}</host> public key to <host>{[host-backup]}</host></title>
- <p>A restore is the act of copying a backup to a system where it will be started as a live database cluster. A restore requires the backup files and one or more WAL segments in order to work correctly.</p>
- </section>
+ <execute user="root" err-suppress="y">
+ <exe-cmd>ssh root@{[setup-ssh-host]} cat {[pg-home-path]}/.ssh/id_rsa.pub |
+ sudo -u backrest tee -a {[br-home-path]}/.ssh/authorized_keys</exe-cmd>
+ </execute>
+ </execute-list>
- <!-- SECTION => CONCEPTS - WAL -->
- <section id="wal">
- <title>Write Ahead Log (WAL)</title>
+ <execute-list host="{[setup-ssh-host]}">
+ <title>Copy <host>{[host-backup]}</host> public key to <host>{[setup-ssh-host]}</host></title>
- <p>WAL is the mechanism that <postgres/> uses to ensure that no committed changes are lost. Transactions are written sequentially to the WAL and a transaction is considered to be committed when those writes are flushed to disk. Afterwards, a background process writes the changes into the main database cluster files (also known as the heap). In the event of a crash, the WAL is replayed to make the database consistent.</p>
+ <execute user="root" err-suppress="y">
+ <exe-cmd>ssh root@{[host-backup]} cat {[br-home-path]}/.ssh/id_rsa.pub |
+ sudo -u postgres tee -a {[pg-home-path]}/.ssh/authorized_keys</exe-cmd>
+ </execute>
+ </execute-list>
- <p>WAL is conceptually infinite but in practice is broken up into individual 16MB files called segments. WAL segments follow the naming convention <id>0000000100000A1E000000FE</id> where the first 8 hexadecimal digits represent the timeline and the next 16 digits are the logical sequence number (LSN).</p>
+ <p>Test that connections can be made from <host>{[host-backup]}</host> to <host>{[setup-ssh-host]}</host> and vice versa.</p>
- </section>
- </section>
+ <execute-list host="{[host-backup]}">
+ <title>Test connection from <host>{[host-backup]}</host> to <host>{[setup-ssh-host]}</host></title>
- <!-- SECTION => INSTALLATION -->
- <section id="installation">
- <title>Installation</title>
+ <execute user="backrest" err-suppress="y">
+ <exe-cmd>ssh postgres@{[setup-ssh-host]}</exe-cmd>
+ <exe-cmd-extra>-o StrictHostKeyChecking=no ls</exe-cmd-extra>
+ </execute>
+ </execute-list>
- <!-- Create S3 server first to allow it time to boot before being used -->
- <host-add name="{[host-s3-server]}" user="root" image="{[image-repo]}:{[host-os]}-s3-server" os="{[host-os]}">
- </host-add>
+ <execute-list host="{[setup-ssh-host]}">
+ <title>Test connection from <host>{[setup-ssh-host]}</host> to <host>{[host-backup]}</host></title>
- <host-add name="{[host-db-primary]}" user="{[host-db-primary-user]}" image="{[host-db-primary-image]}" os="{[host-os]}" mount="{[host-db-primary-mount]}">
- <execute user="root">
- <exe-cmd>mkdir /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/bin /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/build /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/lib /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/libc /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/src /root/pgbackrest-release-{[version]}</exe-cmd>
+ <execute user="postgres" err-suppress="y">
+ <exe-cmd>ssh backrest@{[host-backup]}</exe-cmd>
+ <exe-cmd-extra>-o StrictHostKeyChecking=no ls</exe-cmd-extra>
</execute>
- </host-add>
+ </execute-list>
+ </block-define>
- <p keyword="default"><backrest/> is written in Perl which is included with {[user-guide-os]} by default. The <id>DBD::Pg</id> module must also be installed.</p>
+ <!-- ======================================================================================================================= -->
+ <block-define id="br-install">
+ <p keyword="default"><backrest/> is written in Perl which is included with {[user-guide-os]} by default. Some additional modules must also be installed but they are available as standard packages.</p>
- <execute-list host="{[host-db-primary]}" keyword="default">
- <title>Install the <id>DBD::Pg</id> module</title>
+ <execute-list host="{[br-install-host]}" keyword="default">
+ <title>Install required Perl packages</title>
<execute user="root">
<exe-cmd>apt-get install libdbd-pg-perl libio-socket-ssl-perl libxml-libxml-perl</exe-cmd>
@@ -219,7 +204,7 @@
<p keyword="co6"><backrest/> is written in Perl which is not included with {[user-guide-os]} by default, however all required modules are available as standard packages.</p>
- <execute-list host="{[host-db-primary]}" keyword="co6">
+ <execute-list host="{[br-install-host]}" keyword="co6">
<title>Install required Perl packages</title>
<execute user="root">
@@ -229,48 +214,42 @@
</execute>
</execute-list>
- <p keyword="default">{[user-guide-os]} packages for <backrest/> are available, but if they are not provided on your distribution/version it is easy to download the source and install manually.</p>
+ <p keyword="default">{[user-guide-os]} packages for <backrest/> are available at <link url="https://www.postgresql.org/download/linux/ubuntu/">apt.postgresql.org</link>. If they are not provided for your distribution/version it is easy to download the source and install manually.</p>
<p keyword="co6">{[user-guide-os]} packages for <backrest/> are available from <link url="{[crunchy-url-base]}">Crunchy Data</link> or <link url="http://yum.postgresql.org">yum.postgresql.org</link>, but it is also easy to download the source and install manually.</p>
- <execute-list host="{[host-db-primary]}">
+ <execute-list host="{[br-install-host]}">
<title>Download version <id>{[version]}</id> of <backrest/></title>
+ <!-- This is shown to the user but never actually run for the very good reason that the release is not available before the documentation is built -->
<execute user="root" skip="y">
<exe-cmd>wget -q -O -
{[github-url-release]}/{[version]}.tar.gz |
sudo tar zx -C /root</exe-cmd>
</execute>
- </execute-list>
-
- <p>If <backrest/> has been installed before it's best to be sure that no prior copies of it are still installed. Depending on how old the version of pgBackRest is it may have been installed in a few different locations. The following commands will remove all prior versions of pgBackRest.</p>
-
- <execute-list host="{[host-db-primary]}">
- <title>Remove prior <backrest/> installations</title>
- <execute user="root">
- <exe-cmd>rm -f /usr/bin/pgbackrest</exe-cmd>
+ <!-- These commands simulate what the command above would do if it could be run -->
+ <execute user="root" show="n">
+ <exe-cmd>mkdir /root/pgbackrest-release-{[version]}</exe-cmd>
</execute>
- <execute user="root">
- <exe-cmd>rm -f /usr/bin/pg_backrest</exe-cmd>
+ <execute user="root" show="n">
+ <exe-cmd>cp -r /backrest/bin /root/pgbackrest-release-{[version]}</exe-cmd>
</execute>
- <execute user="root">
- <exe-cmd>rm -rf /usr/lib/perl5/BackRest</exe-cmd>
+ <execute user="root" show="n">
+ <exe-cmd>cp -r /backrest/build /root/pgbackrest-release-{[version]}</exe-cmd>
</execute>
- <execute user="root">
- <exe-cmd>rm -rf {[perl-lib-path]}/BackRest</exe-cmd>
+ <execute user="root" show="n">
+ <exe-cmd>cp -r /backrest/lib /root/pgbackrest-release-{[version]}</exe-cmd>
</execute>
- <execute user="root">
- <exe-cmd>rm -rf /usr/lib/perl5/pgBackRest</exe-cmd>
+ <execute user="root" show="n">
+ <exe-cmd>cp -r /backrest/libc /root/pgbackrest-release-{[version]}</exe-cmd>
</execute>
- <execute user="root">
- <exe-cmd>rm -rf {[perl-lib-path]}/pgBackRest</exe-cmd>
+ <execute user="root" show="n">
+ <exe-cmd>cp -r /backrest/src /root/pgbackrest-release-{[version]}</exe-cmd>
</execute>
</execute-list>
- <p>The new version can now be installed.</p>
-
- <execute-list host="{[host-db-primary]}">
+ <execute-list host="{[br-install-host]}">
<title>Install <backrest/></title>
<execute user="root">
@@ -293,7 +272,7 @@
<exe-cmd>mkdir -m 770 /var/log/pgbackrest</exe-cmd>
</execute>
<execute user="root">
- <exe-cmd>chown postgres:postgres /var/log/pgbackrest</exe-cmd>
+ <exe-cmd>chown {[br-install-user]}:{[br-install-group]} /var/log/pgbackrest</exe-cmd>
</execute>
<execute user="root">
<exe-cmd>touch {[backrest-config-demo]}</exe-cmd>
@@ -302,7 +281,7 @@
<exe-cmd>chmod 640 {[backrest-config-demo]}</exe-cmd>
</execute>
<execute user="root">
- <exe-cmd>chown postgres:postgres {[backrest-config-demo]}</exe-cmd>
+ <exe-cmd>chown {[br-install-user]}:{[br-install-group]} {[backrest-config-demo]}</exe-cmd>
</execute>
</execute-list>
@@ -323,6 +302,117 @@
<exe-cmd>make -C /root/pgbackrest-release-{[version]}/libc install</exe-cmd>
</execute>
</execute-list> -->
+ </block-define>
+
+ <block-define id="br-install-repo">
+ <execute-list host="{[br-install-host]}">
+ <title>Create the <backrest/> repository</title>
+
+ <execute user="root">
+ <exe-cmd>mkdir {[backrest-repo-path]}</exe-cmd>
+ </execute>
+ <execute user="root">
+ <exe-cmd>chmod 750 {[backrest-repo-path]}</exe-cmd>
+ </execute>
+ <execute user="root">
+ <exe-cmd>chown {[br-install-user]}:{[br-install-group]} {[backrest-repo-path]}</exe-cmd>
+ </execute>
+ </execute-list>
+ </block-define>
+
+ <!-- SECTION => INTRODUCTION -->
+ <section id="introduction">
+ <title>Introduction</title>
+
+ <p>This user guide is intended to be followed sequentially from beginning to end &mdash; each section depends on the last. For example, the <link section="/backup">Backup</link> section relies on setup that is performed in the <link section="/quickstart">Quick Start</link> section. Once <backrest/> is up and running then skipping around is possible but following the user guide in order is recommended the first time through.</p>
+
+ <p>Although the examples are targeted at {[user-guide-os]} and <postgres/> {[pg-version]}, it should be fairly easy to apply this guide to any Unix distribution and <postgres/> version. Note that only 64-bit distributions are currently supported due to 64-bit operations in the Perl code. The only OS-specific commands are those to create, start, stop, and drop <postgres/> clusters. The <backrest/> commands will be the same on any Unix system though the locations to install Perl libraries and executables may vary.
+
+ Configuration information and documentation for PostgreSQL can be found in the <postgres/> <link url='http://www.postgresql.org/docs/{[pg-version]}/static/index.html'>Manual</link>.</p>
+
+ <p>A somewhat novel approach is taken to documentation in this user guide. Each command is run on a virtual machine when the documentation is built from the XML source. This means you can have a high confidence that the commands work correctly in the order presented. Output is captured and displayed below the command when appropriate. If the output is not included it is because it was deemed not relevant or was considered a distraction from the narrative.</p>
+
+ <p>All commands are intended to be run as an unprivileged user that has sudo privileges for both the <user>root</user> and <user>postgres</user> users. It's also possible to run the commands directly as their respective users without modification and in that case the <cmd>sudo</cmd> commands can be stripped off.</p>
+ </section>
+
+ <!-- SECTION => CONCEPTS -->
+ <section id="concept">
+ <title>Concepts</title>
+
+ <p>The following concepts are defined as they are relevant to <backrest/>, <postgres/>, and this user guide.</p>
+
+ <!-- SECTION => CONCEPTS - BACKUP -->
+ <section id="backup">
+ <title>Backup</title>
+
+ <p>A backup is a consistent copy of a database cluster that can be restored to recover from a hardware failure, to perform Point-In-Time Recovery, or to bring up a new standby.</p>
+
+ <p><b>Full Backup</b>: <backrest/> copies the entire contents of the database cluster to the backup server. The first backup of the database cluster is always a Full Backup. <backrest/> is always able to restore a full backup directly. The full backup does not depend on any files outside of the full backup for consistency.</p>
+
+ <p><b>Differential Backup</b>: <backrest/> copies only those database cluster files that have changed since the last full backup. <backrest/> restores a differential backup by copying all of the files in the chosen differential backup and the appropriate unchanged files from the previous full backup. The advantage of a differential backup is that it requires less disk space than a full backup, however, the differential backup and the full backup must both be valid to restore the differential backup.</p>
+
+ <p><b>Incremental Backup</b>: <backrest/> copies only those database cluster files that have changed since the last backup (which can be another incremental backup, a differential backup, or a full backup). As an incremental backup only includes those files changed since the prior backup, they are generally much smaller than full or differential backups. As with the differential backup, the incremental backup depends on other backups to be valid to restore the incremental backup. Since the incremental backup includes only those files since the last backup, all prior incremental backups back to the prior differential, the prior differential backup, and the prior full backup must all be valid to perform a restore of the incremental backup. If no differential backup exists then all prior incremental backups back to the prior full backup, which must exist, and the full backup itself must be valid to restore the incremental backup.</p>
+ </section>
+
+ <!-- SECTION => CONCEPTS - RESTORE -->
+ <section id="restore">
+ <title>Restore</title>
+
+ <p>A restore is the act of copying a backup to a system where it will be started as a live database cluster. A restore requires the backup files and one or more WAL segments in order to work correctly.</p>
+ </section>
+
+ <!-- SECTION => CONCEPTS - WAL -->
+ <section id="wal">
+ <title>Write Ahead Log (WAL)</title>
+
+ <p>WAL is the mechanism that <postgres/> uses to ensure that no committed changes are lost. Transactions are written sequentially to the WAL and a transaction is considered to be committed when those writes are flushed to disk. Afterwards, a background process writes the changes into the main database cluster files (also known as the heap). In the event of a crash, the WAL is replayed to make the database consistent.</p>
+
+ <p>WAL is conceptually infinite but in practice is broken up into individual 16MB files called segments. WAL segments follow the naming convention <id>0000000100000A1E000000FE</id> where the first 8 hexadecimal digits represent the timeline and the next 16 digits are the logical sequence number (LSN).</p>
+
+ </section>
+ </section>
+
+ <!-- SECTION => INSTALLATION -->
+ <section id="installation">
+ <title>Installation</title>
+
+ <!-- Create S3 server first to allow it time to boot before being used -->
+ <host-add name="{[host-s3-server]}" user="root" image="{[image-repo]}:{[host-os]}-s3-server" os="{[host-os]}"/>
+
+ <p>A new host named <host>db-primary</host> is created to contain the demo cluster and run <backrest/> examples.</p>
+
+ <host-add name="{[host-db-primary]}" user="{[host-db-primary-user]}" image="{[host-db-primary-image]}" os="{[host-os]}" mount="{[host-db-primary-mount]}"/>
+
+ <p>If <backrest/> has been installed before it's best to be sure that no prior copies of it are still installed. Depending on how old the version of pgBackRest is it may have been installed in a few different locations. The following commands will remove all prior versions of pgBackRest.</p>
+
+ <execute-list host="{[host-db-primary]}">
+ <title>Remove prior <backrest/> installations</title>
+
+ <execute user="root">
+ <exe-cmd>rm -f /usr/bin/pgbackrest</exe-cmd>
+ </execute>
+ <execute user="root">
+ <exe-cmd>rm -f /usr/bin/pg_backrest</exe-cmd>
+ </execute>
+ <execute user="root">
+ <exe-cmd>rm -rf /usr/lib/perl5/BackRest</exe-cmd>
+ </execute>
+ <execute user="root">
+ <exe-cmd>rm -rf {[perl-lib-path]}/BackRest</exe-cmd>
+ </execute>
+ <execute user="root">
+ <exe-cmd>rm -rf /usr/lib/perl5/pgBackRest</exe-cmd>
+ </execute>
+ <execute user="root">
+ <exe-cmd>rm -rf {[perl-lib-path]}/pgBackRest</exe-cmd>
+ </execute>
+ </execute-list>
+
+ <block id="br-install">
+ <block-variable-replace key="br-install-host">{[host-db-primary]}</block-variable-replace>
+ <block-variable-replace key="br-install-user">postgres</block-variable-replace>
+ <block-variable-replace key="br-install-group">postgres</block-variable-replace>
+ </block>
<p><backrest/> should now be properly installed but it is best to check. If any dependencies were missed then you will get an error when running <backrest/> from the command line.</p>
@@ -342,7 +432,7 @@
<p>The Quick Start section will cover basic configuration of <backrest/> and <postgres/> and introduce the <cmd>backup</cmd>, <cmd>restore</cmd>, and <cmd>info</cmd> commands.</p>
<!-- SECTION => QUICKSTART - SETUP DEMO CLUSTER -->
- <section id="setup-demo-cluster" depend="/quickstart">
+ <section id="setup-demo-cluster">
<title>Setup Demo Cluster</title>
<p>Creating the demo cluster is optional but is strongly recommended, especially for new users, since the example commands in the user guide reference the demo cluster; the examples assume the demo cluster is running on the default port (i.e. 5432). The cluster will not be started until a later section because there is still some configuration to do.</p>
@@ -419,19 +509,11 @@
<p>For this demonstration the repository will be stored on the same host as the <postgres/> server. This is the simplest configuration and is useful in cases where traditional backup software is employed to backup the database host.</p>
- <execute-list host="{[host-db-primary]}">
- <title>Create the <backrest/> repository</title>
-
- <execute user="root">
- <exe-cmd>mkdir {[backrest-repo-path]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>chmod 750 {[backrest-repo-path]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>chown postgres:postgres {[backrest-repo-path]}</exe-cmd>
- </execute>
- </execute-list>
+ <block id="br-install-repo">
+ <block-variable-replace key="br-install-host">{[host-db-primary]}</block-variable-replace>
+ <block-variable-replace key="br-install-user">postgres</block-variable-replace>
+ <block-variable-replace key="br-install-group">postgres</block-variable-replace>
+ </block>
<p>The repository path must be configured so <backrest/> knows where to find it.</p>
@@ -1433,60 +1515,68 @@
<p>The configuration described in <link section="/quickstart">Quickstart</link> is suitable for simple installations but for enterprise configurations it is more typical to have a dedicated <host>backup</host> host. This separates the backups and WAL archive from the database server so <host>database</host> host failures have less impact. It is still a good idea to employ traditional backup software to backup the <host>backup</host> host.</p>
- <!-- SECTION => BACKUP HOST - INSTALL/CONFIGURE -->
- <section id="install-config">
- <title>Installation and Configuration</title>
+ <section id="install">
+ <title>Installation</title>
- <host-add name="{[host-backup]}" user="{[host-backup-user]}" image="{[host-backup-image]}" os="{[host-os]}" mount="{[host-backup-mount]}">
- <execute user="root">
- <exe-cmd>cp -r /backrest/lib/pgBackRest {[perl-lib-path]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>find {[perl-lib-path]}/pgBackRest -type f -exec chmod 644 {} +</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>find {[perl-lib-path]}/pgBackRest -type d -exec chmod 755 {} +</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp /backrest/bin/{[project-exe]} {[perl-bin-path]}/{[project-exe]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>chmod 755 {[perl-bin-path]}/{[project-exe]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>mkdir -m 770 /var/log/pgbackrest</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>chown backrest:postgres /var/log/pgbackrest</exe-cmd>
- </execute>
+ <p>A new host named <host>backup</host> is created to store the cluster backups.</p>
- <!-- LibC installation -->
- <!-- <execute user="root">
- <exe-cmd>mkdir /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/bin /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/build /root/pgbackrest-release-{[version]}</exe-cmd>
+ <host-add name="{[host-backup]}" user="{[host-backup-user]}" image="{[host-backup-image]}" os="{[host-os]}" mount="{[host-backup-mount]}"/>
+
+ <p>The <user>{[br-user]}</user> user is created to own the <backrest/> repository. Any user can own the repository but it is best not to use <user>postgres</user> (if it exists) to avoid confusion.</p>
+
+ <execute-list host="{[host-backup]}">
+ <title>Create <user>{[br-user]}</user></title>
+
+ <execute keyword="default" user="root">
+ <exe-cmd>adduser --disabled-password --gecos "" {[br-user]}</exe-cmd>
</execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/lib /root/pgbackrest-release-{[version]}</exe-cmd>
+ <execute keyword="co6" user="root">
+ <exe-cmd>groupadd {[br-group]}</exe-cmd>
</execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/libc /root/pgbackrest-release-{[version]}</exe-cmd>
+ <execute keyword="co6" user="root">
+ <exe-cmd>adduser -g{[br-group]} -n {[br-user]}</exe-cmd>
</execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/src /root/pgbackrest-release-{[version]}</exe-cmd>
+ </execute-list>
+
+ <block id="br-install">
+ <block-variable-replace key="br-install-host">{[host-backup]}</block-variable-replace>
+ <block-variable-replace key="br-install-user">{[br-user]}</block-variable-replace>
+ <block-variable-replace key="br-install-group">{[br-user]}</block-variable-replace>
+ </block>
+
+ <block id="br-install-repo">
+ <block-variable-replace key="br-install-host">{[host-backup]}</block-variable-replace>
+ <block-variable-replace key="br-install-user">{[br-group]}</block-variable-replace>
+ <block-variable-replace key="br-install-group">{[br-group]}</block-variable-replace>
+ </block>
+ </section>
+
+ <section id="setup-ssh">
+ <title>Setup Trusted SSH</title>
+
+ <block id="setup-ssh-intro">
+ <block-variable-replace key="bogus">bogus !!!</block-variable-replace>
+ </block>
+
+ <execute-list host="{[host-backup]}">
+ <title>Create <host>{[host-backup]}</host> host key pair</title>
+
+ <execute user="backrest">
+ <exe-cmd>mkdir -m 750 {[br-home-path]}/.ssh</exe-cmd>
</execute>
- <execute user="root">
- <exe-cmd>sh -c 'cd /root/pgbackrest-release-{[version]}/libc &&
- perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none'</exe-cmd>
+ <execute user="backrest">
+ <exe-cmd>ssh-keygen -f {[br-home-path]}/.ssh/id_rsa -t rsa -b 4096 -N ""</exe-cmd>
</execute>
- <execute user="root" err-suppress="y">
- <exe-cmd>make -C /root/pgbackrest-release-{[version]}/libc install</exe-cmd>
- </execute> -->
- </host-add>
+ </execute-list>
+
+ <block id="setup-ssh">
+ <block-variable-replace key="setup-ssh-host">{[host-db-primary]}</block-variable-replace>
+ </block>
+ </section>
+
+ <!-- SECTION => BACKUP HOST - INSTALL/CONFIGURE -->
+ <section id="config">
+ <title>Configuration</title>
<backrest-config host="{[host-backup]}" show="n" owner="backrest:postgres" file="{[backrest-config-demo]}">
<title>Configure the <backrest/> repository path</title>
@@ -1494,7 +1584,7 @@
<backrest-config-option section="global" key="repo-path">{[backrest-repo-path]}</backrest-config-option>
</backrest-config>
- <p>For this example a new host named <host>backup</host> has been created to store the cluster backups. Follow the instructions in <link section="/installation">Installation</link> to install <backrest/>, <link section="/quickstart/create-repository">Create the Repository</link> to create the <backrest/> repository and <link section="/quickstart/create-stanza">Create the Stanza</link> to create the stanza. The <host>backup</host> host must also be configured with the <host>db-primary</host> host/user and database path. The primary will be configured as <id>db1</id> to allow a standby to be added later.</p>
+ <p>The <host>backup</host> host must be configured with the <host>db-primary</host> host/user and database path. The primary will be configured as <id>db1</id> to allow a standby to be added later.</p>
<backrest-config host="{[host-backup]}" owner="backrest:postgres" file="{[backrest-config-demo]}">
<title>Configure <br-option>db1-host</br-option>/<br-option>db1-user</br-option> and <br-option>db1-path</br-option></title>
@@ -1622,7 +1712,7 @@
</section>
<!-- SECTION => BACKUP HOST - ASYNCHRONOUS ARCHIVING -->
- <section id="async-archiving" depend="install-config">
+ <section id="async-archiving" depend="config">
<title>Asynchronous Archiving</title>
<p>The <br-option>archive-async</br-option> option offloads WAL archiving to a separate process (or processes) to improve throughput. It works by <quote>looking ahead</quote> to see which WAL segments are ready to be archived beyond the request that <postgres/> is currently making via the <code>archive_command</code>. WAL segments are transferred to the archive directly from the <path>pg_xlog</path>/<path>pg_wal</path> directory and success is only returned by the <code>archive_command</code> when the WAL segment has been safely stored in the archive.</p>
@@ -1692,7 +1782,7 @@
</section>
<!-- SECTION => PARALLEL BACKUP-RESTORE -->
- <section id="parallel-backup-restore" depend="backup-host/install-config">
+ <section id="parallel-backup-restore" depend="backup-host/config">
<title>Parallel Backup / Restore</title>
<p><backrest/> offers parallel processing to improve performance of compression and transfer. The number of processes to be used for this feature is set using the <br-option>--process-max</br-option> option.</p>
@@ -1745,7 +1835,7 @@
</section>
<!-- SECTION => START/STOP -->
- <section id="start-stop" depend="/backup-host/install-config">
+ <section id="start-stop" depend="/backup-host/config">
<title>Starting and Stopping</title>
<p>Sometimes it is useful to prevent <backrest/> from running on a system. For example, when failing over from a primary to a standby it's best to prevent <backrest/> from running on the old primary in case <postgres/> gets restarted or can't be completely killed. This will also prevent <backrest/> from running on <id>cron</id>.</p>
@@ -1827,81 +1917,49 @@
<p>Replication allows multiple copies of a <postgres/> cluster (called standbys) to be created from a single primary. The standbys are useful for balancing reads and to provide redundancy in case the primary host fails.</p>
- <!-- SECTION => REPLICATION - HOT-STANDBY -->
- <section id="hot-standby">
- <title>Hot Standby</title>
+ <!-- SECTION => REPLICATION - INSTALLATION -->
+ <section id="installation">
+ <title>Installation</title>
- <p>A hot standby performs replication using the WAL archive and allows read-only queries.</p>
+ <p>A new host named <host>db-standby</host> is created to run the standby.</p>
- <p>A new host named <host>db-standby</host> will be created to run the standby. Follow the instructions in <link section="/installation">Installation</link> to install <backrest/> and <link section="/quickstart/setup-demo-cluster">Setup Demo Cluster</link> to setup the demo cluster.</p>
+ <host-add name="{[host-db-standby]}" user="{[host-db-standby-user]}" image="{[host-db-standby-image]}" os="{[host-os]}" mount="{[host-db-standby-mount]}"/>
- <host-add name="{[host-db-standby]}" user="{[host-db-standby-user]}" image="{[host-db-standby-image]}" os="{[host-os]}" mount="{[host-db-standby-mount]}">
- <!-- Install packages -->
- <execute user="root" keyword="default">
- <exe-cmd>apt-get -y install libdbd-pg-perl</exe-cmd>
- </execute>
+ <block id="br-install">
+ <block-variable-replace key="br-install-host">{[host-db-standby]}</block-variable-replace>
+ <block-variable-replace key="br-install-user">postgres</block-variable-replace>
+ <block-variable-replace key="br-install-group">postgres</block-variable-replace>
+ </block>
- <execute user="root" keyword="co6">
- <exe-cmd>yum -y install perl perl-Time-HiRes perl-parent
- perl-JSON perl-Digest-SHA perl-DBD-Pg</exe-cmd>
- </execute>
+ <p>The demo cluster must be created even though it will be overwritten later.</p>
- <!-- Install backrest -->
- <execute user="root">
- <exe-cmd>cp -r /backrest/lib/pgBackRest {[perl-lib-path]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>find {[perl-lib-path]}/pgBackRest -type f -exec chmod 644 {} +</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>find {[perl-lib-path]}/pgBackRest -type d -exec chmod 755 {} +</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp /backrest/bin/{[project-exe]}
- {[perl-bin-path]}/{[project-exe]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>chmod 755 {[perl-bin-path]}/{[project-exe]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>mkdir -m 770 /var/log/pgbackrest</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>chown postgres:postgres /var/log/pgbackrest</exe-cmd>
- </execute>
+ <execute-list host="{[host-db-standby]}">
+ <title>Create demo cluster</title>
- <!-- LibC installation -->
- <!-- <execute user="root">
- <exe-cmd>mkdir /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/bin /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/build /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/lib /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/libc /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
- <execute user="root">
- <exe-cmd>cp -r /backrest/src /root/pgbackrest-release-{[version]}</exe-cmd>
- </execute>
<execute user="root">
- <exe-cmd>sh -c 'cd /root/pgbackrest-release-{[version]}/libc &&
- perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none'</exe-cmd>
- </execute>
- <execute user="root" err-suppress="y">
- <exe-cmd>make -C /root/pgbackrest-release-{[version]}/libc install</exe-cmd>
- </execute> -->
-
- <!-- Start the cluster -->
- <execute user="root" output="y" filter="n">
<exe-cmd>{[db-cluster-create]}</exe-cmd>
</execute>
- </host-add>
+ </execute-list>
+ </section>
+
+ <!-- SECTION => REPLICATION - SETUP-SSH -->
+ <section id="setup-ssh">
+ <title>Setup Trusted SSH</title>
+
+ <block id="setup-ssh-intro">
+ <block-variable-replace key="bogus">bogus !!!</block-variable-replace>
+ </block>
+
+ <block id="setup-ssh">
+ <block-variable-replace key="setup-ssh-host">{[host-db-standby]}</block-variable-replace>
+ </block>
+ </section>
+
+ <!-- SECTION => REPLICATION - HOT-STANDBY -->
+ <section id="hot-standby">
+ <title>Hot Standby</title>
+
+ <p>A hot standby performs replication using the WAL archive and allows read-only queries.</p>
<postgres-config host="{[host-db-standby]}" keyword="default" file="{[postgres-config-demo]}" show="n">
<title>Set options</title>
diff --git a/test/lib/pgBackRestTest/Common/ContainerTest.pm b/test/lib/pgBackRestTest/Common/ContainerTest.pm
index e5ae8a7c0..d86e4f662 100755
--- a/test/lib/pgBackRestTest/Common/ContainerTest.pm
+++ b/test/lib/pgBackRestTest/Common/ContainerTest.pm
@@ -664,51 +664,6 @@ sub containerBuild
containerWrite(
$oStorageDocker, $strTempPath, $strOS, 'Test', $strImageParent, $strImage, $strCopy, $strScript, $bVmForce);
}
-
- # Db doc image
- ########################################################################################################################
- if (!$bDeprecated)
- {
- $strImageParent = containerRepo() . ":${strOS}-base";
- $strImage = "${strOS}-doc-db";
-
- $strScript = sshSetup($strOS, POSTGRES_USER, POSTGRES_GROUP, $$oVm{$strOS}{&VM_CONTROL_MASTER});
-
- containerWrite(
- $oStorageDocker, $strTempPath, $strOS, "Db Doc", $strImageParent, $strImage, $strCopy, $strScript, $bVmForce);
- }
-
- # Backup doc image
- ###########################################################################################################################
- if (!$bDeprecated)
- {
- $strImageParent = containerRepo() . ":${strOS}-base";
- $strImage = "${strOS}-doc-backup";
- $strCopy = undef;
-
- $strScript .= sectionHeader() .
- "# Create pgbackrest user\n" .
- ' ' . userCreate($strOS, BACKREST_USER, BACKREST_USER_ID, TEST_GROUP);
-
- $strScript .=
- sshSetup($strOS, BACKREST_USER, TEST_GROUP, $$oVm{$strOS}{&VM_CONTROL_MASTER});
-
- #-----------------------------------------------------------------------------------------------------------------------
- $strScript .= sectionHeader() .
- "# Create pgbackrest.conf\n" .
- " touch /etc/pgbackrest.conf && \\\n" .
- " chmod 640 /etc/pgbackrest.conf && \\\n" .
- " chown " . BACKREST_USER . ":" . POSTGRES_GROUP . " /etc/pgbackrest.conf";
-
- $strScript .= sectionHeader() .
- "# Setup repository\n" .
- " mkdir /var/lib/pgbackrest && \\\n" .
- " chown -R " . BACKREST_USER . ":" . POSTGRES_GROUP . " /var/lib/pgbackrest && \\\n" .
- " chmod 750 /var/lib/pgbackrest";
-
- containerWrite(
- $oStorageDocker, $strTempPath, $strOS, 'Backup Doc', $strImageParent, $strImage, $strCopy, $strScript, $bVmForce);
- }
}
&log(INFO, "Build Complete");
[parent: 4bcef7020ee2]