diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 1ceee0fd0..c6b3ac555 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -4,7 +4,7 @@ Please provide the following information when submitting an issue (feature reque 2. PostgreSQL version: -3. Operating system/version - if you have more than one server (for example, a database server, a backup host server, one or more standbys), please specify each: +3. Operating system/version - if you have more than one server (for example, a database server, a repository host server, one or more standbys), please specify each: 4. Did you install pgBackRest from source or from a package? diff --git a/doc/xml/reference.xml b/doc/xml/reference.xml index e28b96918..8b45c36fe 100644 --- a/doc/xml/reference.xml +++ b/doc/xml/reference.xml @@ -137,7 +137,7 @@ Compression level for network transfer when compress=n. - Sets the zlib level to be used for protocol compression when compress=n and the database cluster is not on the same host as the backup. Protocol compression is used to reduce network traffic but can be disabled by setting compress-level-network=0. When compress=y the compress-level-network setting is ignored and compress-level is used instead so that the file is only compressed once. SSH compression is always disabled. + Sets the zlib level to be used for protocol compression when compress=n and the database cluster is not on the same host as the repository. Protocol compression is used to reduce network traffic but can be disabled by setting compress-level-network=0. When compress=y the compress-level-network setting is ignored and compress-level is used instead so that the file is only compressed once. SSH compression is always disabled. 0-9 1 @@ -246,7 +246,7 @@ Defines the user that will be used for operations on the repository host. Preferably this is not the postgres user but rather some other user like pgbackrest. If runs on the repository host the postgres user can be placed in the pgbackrest group so it has read permissions on the repository without being able to damage the contents accidentally. - backup-user + repo-user @@ -686,7 +686,7 @@ host for operating remotely via SSH. - Used for backups where the host is different from the backup host. + Used for backups where the host is different from the repository host. db.domain.com @@ -748,7 +748,7 @@ Commands are used to execute the various functions. Here the command options are listed exhaustively, that is, each option applicable to a command is listed with that command even if it applies to one or more other commands. This includes all the options that may also configured in pgbackrest.conf. - Non-boolean options configured in pgbackrest.conf can be reset to default on the command-line by using the reset- prefix. This feature may be used to restore a backup directly on a backup host. Normally, will error because it can see that the database host is remote and restores cannot be done remotely. By adding --reset-pg1-host on the command-line, will ignore the remote database host and restore locally. It may be necessary to pass a new --pg-path to force the restore to happen in a specific path, i.e. not the path used on the database host. + Non-boolean options configured in pgbackrest.conf can be reset to default on the command-line by using the reset- prefix. This feature may be used to restore a backup directly on a repository host. Normally, will error because it can see that the database host is remote and restores cannot be done remotely. By adding --reset-pg1-host on the command-line, will ignore the remote database host and restore locally. It may be necessary to pass a new --pg-path to force the restore to happen in a specific path, i.e. not the path used on the database host. The no- prefix may be used to set a boolean option to false on the command-line. @@ -867,7 +867,7 @@ Check the configuration. - The check command validates that and the archive_command setting are configured correctly for archiving and backups. It detects misconfigurations, particularly in archiving, that result in incomplete backups because required WAL segments did not reach the archive. The command can be run on the database or the backup host. The command may also be run on the standby host, however, since pg_switch_xlog()/pg_switch_wal() cannot be performed on the standby, the command will only test the repository configuration. + The check command validates that and the archive_command setting are configured correctly for archiving and backups. It detects misconfigurations, particularly in archiving, that result in incomplete backups because required WAL segments did not reach the archive. The command can be run on the database or the repository host. The command may also be run on the standby host, however, since pg_switch_xlog()/pg_switch_wal() cannot be performed on the standby, the command will only test the repository configuration. Note that pg_create_restore_point('pgBackRest Archive Check') and pg_switch_xlog()/pg_switch_wal() are called to force to archive a WAL segment. Restore points are only supported in >= 9.1 so for older versions the check command may fail if there has been no write activity since the last log rotation, therefore it is recommended that activity be generated by the user if there have been no writes since the last WAL switch before running the check command. @@ -1183,7 +1183,7 @@ Upgrade a stanza. - Immediately after upgrading to a newer major version, the pg-path for all configurations must be set to the new database location and the stanza-upgrade run on the backup host. If the database is offline use the --no-online option. + Immediately after upgrading to a newer major version, the pg-path for all configurations must be set to the new database location and the stanza-upgrade run on the repository host. If the database is offline use the --no-online option. @@ -1216,8 +1216,8 @@ To delete a stanza:
  • Shut down the cluster associated with the stanza (or use --force to override).
    • -
  • Run the stop command on the backup host (the host where the repository is mounted).
    • -
  • Run the stanza-delete command on the backup host.
    • +
  • Run the stop command on the repository host.
    • +
  • Run the stanza-delete command on the repository host.
Once the command successfully completes, it is the responsibility of the user to remove the stanza from all configuration files. diff --git a/doc/xml/user-guide.xml b/doc/xml/user-guide.xml index d01e21b62..ad5c7e5f6 100644 --- a/doc/xml/user-guide.xml +++ b/doc/xml/user-guide.xml @@ -100,10 +100,10 @@ {[host-pg-primary-image]} {[host-mount]} - backup - {[host-user]} - {[image-repo]}:{[host-os]}-base - {[host-mount]} + repo1 + {[host-user]} + {[image-repo]}:{[host-os]}-base + {[host-mount]} ls -1 {[backrest-repo-path]}/backup/demo | tail -5 | head -1 @@ -156,10 +156,10 @@ -

Exchange keys between {[host-backup]} and {[setup-ssh-host]}.

+

Exchange keys between {[host-repo1]} and {[setup-ssh-host]}.

- - Copy <host>{[setup-ssh-host]}</host> public key to <host>{[host-backup]}</host> + + Copy <host>{[setup-ssh-host]}</host> public key to <host>{[host-repo1]}</host> ssh root@{[setup-ssh-host]} cat {[pg-home-path]}/.ssh/id_rsa.pub | @@ -168,18 +168,18 @@ - Copy <host>{[host-backup]}</host> public key to <host>{[setup-ssh-host]}</host> + Copy <host>{[host-repo1]}</host> public key to <host>{[setup-ssh-host]}</host> - ssh root@{[host-backup]} cat {[br-home-path]}/.ssh/id_rsa.pub | + ssh root@{[host-repo1]} cat {[br-home-path]}/.ssh/id_rsa.pub | sudo -u postgres tee -a {[pg-home-path]}/.ssh/authorized_keys -

Test that connections can be made from {[host-backup]} to {[setup-ssh-host]} and vice versa.

+

Test that connections can be made from {[host-repo1]} to {[setup-ssh-host]} and vice versa.

- - Test connection from <host>{[host-backup]}</host> to <host>{[setup-ssh-host]}</host> + + Test connection from <host>{[host-repo1]}</host> to <host>{[setup-ssh-host]}</host> ssh postgres@{[setup-ssh-host]} @@ -188,10 +188,10 @@ - Test connection from <host>{[setup-ssh-host]}</host> to <host>{[host-backup]}</host> + Test connection from <host>{[setup-ssh-host]}</host> to <host>{[host-repo1]}</host> - ssh pgbackrest@{[host-backup]} + ssh pgbackrest@{[host-repo1]} -o StrictHostKeyChecking=no ls @@ -360,7 +360,7 @@

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.

-

Full Backup: copies the entire contents of the database cluster to the backup server. The first backup of the database cluster is always a Full Backup. 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.

+

Full Backup: copies the entire contents of the database cluster to the backup. The first backup of the database cluster is always a Full Backup. 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.

Differential Backup: copies only those database cluster files that have changed since the last full backup. 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.

@@ -396,12 +396,12 @@
- Upgrading + Upgrading {[project]}
- Upgrading from v1 to v2 + Upgrading {[project]} from v1 to v2 -

Upgrading from v1 to v2 is fairly straight-forward. The repository format has not changed and all non-deprecated options from v1 are accepted, so for most installations it is simply a matter of installing the new version.

+

Upgrading from 1.xx (v1) to 2.xx (v2) is fairly straight-forward. The repository format has not changed and all non-deprecated options from v1 are accepted, so for most installations it is simply a matter of installing the new version.

However, there are a few caveats:

@@ -622,7 +622,7 @@
- +
Configure Repository Encryption @@ -945,7 +945,7 @@

Although useful this feature may not be appropriate when another third-party backup solution is being used to take online backups as will not recognize that the other software is running and may terminate a backup started by that software. However, it would be unusual to run more than one third-party backup solution at the same time so this is not likely to be a problem.

-

Note that pg_dump and pg_base_backup do not take online backups so are not affected. It is safe to run them in conjunction with .

+

Note that pg_dump and pg_basebackup do not take online backups so are not affected. It is safe to run them in conjunction with .

@@ -1583,7 +1583,7 @@
- +
Delete a Stanza @@ -1620,22 +1620,22 @@
- -
- Dedicated Backup Host + +
+ Dedicated Repository Host -

The configuration described in Quickstart is suitable for simple installations but for enterprise configurations it is more typical to have a dedicated backup host. This separates the backups and WAL archive from the database server so database host failures have less impact. It is still a good idea to employ traditional backup software to backup the backup host.

+

The configuration described in Quickstart is suitable for simple installations but for enterprise configurations it is more typical to have a dedicated repository host where the backups and WAL archive files are stored. This separates the backups and WAL archive from the database server so database host failures have less impact. It is still a good idea to employ traditional backup software to backup the repository host.

Installation -

A new host named backup is created to store the cluster backups.

+

A new host named repository is created to store the cluster backups.

- +

The {[br-user]} user is created to own the repository. Any user can own the repository but it is best not to use postgres (if it exists) to avoid confusion.

- + Create <user>{[br-user]}</user> @@ -1650,13 +1650,13 @@ - {[host-backup]} + {[host-repo1]} {[br-user]} {[br-user]} - {[host-backup]} + {[host-repo1]} {[br-group]} {[br-group]} @@ -1669,8 +1669,8 @@ bogus !!! - - Create <host>{[host-backup]}</host> host key pair + + Create <host>{[host-repo1]}</host> host key pair mkdir -m 750 {[br-home-path]}/.ssh @@ -1686,19 +1686,19 @@
- +
Configuration - + Configure the <backrest/> repository path {[backrest-repo-path]} -

The backup host must be configured with the pg-primary host/user and database path. The primary will be configured as db1 to allow a standby to be added later.

+

The repository host must be configured with the pg-primary host/user and database path. The primary will be configured as db1 to allow a standby to be added later.

- + Configure <br-option>pg1-host</br-option>/<br-option>pg1-host-user</br-option> and <br-option>pg1-path</br-option> {[pg-path]} @@ -1712,14 +1712,14 @@ n -

The database host must be configured with the backup host/user. The default for the backup-user option is backrest. If the postgres user does restores on the backup host it is best not to also allow the postgres user to perform backups. However, the postgres user can read the repository directly if it is in the same group as the backrest user.

+

The database host must be configured with the repository host/user. The default for the repo1-host-user option is pgbackrest. If the postgres user does restores on the repository host it is best not to also allow the postgres user to perform backups. However, the postgres user can read the repository directly if it is in the same group as the pgbackrest user.

Configure <br-option>repo1-host</br-option>/<br-option>repo1-host-user</br-option> {[pg-path]} - {[host-backup]} + {[host-repo1]} detail @@ -1727,11 +1727,11 @@ n -

Commands are run the same as on a single host configuration except that some commands such as backup and expire are run from the backup host instead of the database host.

+

Commands are run the same as on a single host configuration except that some commands such as backup and expire are run from the repository host instead of the database host.

Create the stanza in the new repository.

- + Create the stanza @@ -1739,7 +1739,7 @@ -

Check that the configuration is correct on both the database and backup hosts. More information about the check command can be found in Check the Configuration.

+

Check that the configuration is correct on both the database and repository hosts. More information about the check command can be found in Check the Configuration.

Check the configuration @@ -1749,7 +1749,7 @@ - + Check the configuration @@ -1758,13 +1758,13 @@
- +
Perform a Backup -

To perform a backup of the cluster run with the backup command on the backup host.

+

To perform a backup of the cluster run with the backup command on the repository host.

- + Backup the {[postgres-cluster-demo]} cluster @@ -1772,10 +1772,10 @@ -

Since a new repository was created on the backup host the warning about the incremental backup changing to a full backup was emitted.

+

Since a new repository was created on the repository host the warning about the incremental backup changing to a full backup was emitted.

- +
Restore a Backup @@ -1803,7 +1803,7 @@

A new backup must be performed due to the timeline switch.

- + Backup the {[postgres-cluster-demo]} cluster @@ -1812,7 +1812,7 @@
- +
Asynchronous Archiving @@ -1883,12 +1883,12 @@
-
+
Parallel Backup / Restore

offers parallel processing to improve performance of compression and transfer. The number of processes to be used for this feature is set using the --process-max option.

- + Check the number of CPUs @@ -1901,7 +1901,7 @@

The restore command can and should use all available CPUs because during a restore the cluster is shut down and there is generally no other important work being done on the host. If the host contains multiple clusters then that should be considered when setting restore parallelism.

- + Perform a backup with single process @@ -1909,13 +1909,13 @@ - + Configure <backrest/> to use multiple <cmd>backup</cmd> processes 3 - + Perform a backup with multiple processes @@ -1923,7 +1923,7 @@ - + Get backup info for the {[postgres-cluster-demo]} cluster @@ -1936,7 +1936,7 @@
-
+
Starting and Stopping

Sometimes it is useful to prevent from running on a system. For example, when failing over from a primary to a standby it's best to prevent from running on the old primary in case gets restarted or can't be completely killed. This will also prevent from running on cron.

@@ -1951,7 +1951,7 @@

New processes will no longer run.

- + Attempt a backup @@ -1992,7 +1992,7 @@

New processes for the specified stanza will no longer run.

- + Attempt a backup @@ -2013,7 +2013,7 @@
-
+
Replication

Replication allows multiple copies of a 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.

@@ -2059,7 +2059,7 @@ {[pg-path]} - {[host-backup]} + {[host-repo1]} standby_mode=on @@ -2365,7 +2365,7 @@

can perform backups on a standby instead of the primary. Standby backups require the pg-standby host to be configured and the backup-standby option enabled. If more than one standby is configured then the first running standby found will be used for the backup.

- + Configure <br-option>pg2-host</br-option>/<br-option>pg2-host-user</br-option> and <br-option>pg2-path</br-option> {[pg-path]} @@ -2377,7 +2377,7 @@

Both the primary and standby databases are required to perform the backup, though the vast majority of the files will be copied from the standby to reduce load on the primary. The database hosts can be configured in any order. will automatically determine which is the primary and which is the standby.

- + Backup the {[postgres-cluster-demo]} cluster from <host>pg-standby</host> @@ -2505,7 +2505,7 @@ {[pg-path-upgrade]} - + Upgrade <br-option>pg1-path</br-option> and <br-option>pg2-path</br-option>, disable backup from standby {[pg-path-upgrade]} @@ -2525,7 +2525,7 @@

Before starting the new cluster, the stanza-upgrade command must be run on the server where the repository is located.

- + Upgrade the stanza @@ -2597,9 +2597,9 @@ -

Run the check on the backup host. The warning regarding the standby being down is expected since the standby cluster is down. Running this command demonstrates that the backup server is aware of the standby and is configured properly for the primary server.

+

Run the check on the repository host. The warning regarding the standby being down is expected since the standby cluster is down. Running this command demonstrates that the repository server is aware of the standby and is configured properly for the primary server.

- + Check configuration @@ -2609,7 +2609,7 @@

Run a full backup on the new cluster and then restore the standby from the backup. The backup type will automatically be changed to full if incr or diff is requested.

- + Run a full backup @@ -2653,7 +2653,7 @@

Backup from standby can be enabled now that the standby is restored.

- + Reenable backup from standby y diff --git a/src/config/define.auto.c b/src/config/define.auto.c index cdcb5779c..7e4adb130 100644 --- a/src/config/define.auto.c +++ b/src/config/define.auto.c @@ -51,9 +51,9 @@ static ConfigDefineCommandData configDefineCommandData[] = CFGDEFDATA_COMMAND_LI ( "The check command validates that pgBackRest and the archive_command setting are configured correctly for archiving " "and backups. It detects misconfigurations, particularly in archiving, that result in incomplete backups because " - "required WAL segments did not reach the archive. The command can be run on the database or the backup host. The " - "command may also be run on the standby host, however, since pg_switch_xlog()/pg_switch_wal() cannot be performed " - "on the standby, the command will only test the repository configuration.\n" + "required WAL segments did not reach the archive. The command can be run on the database or the repository host. " + "The command may also be run on the standby host, however, since pg_switch_xlog()/pg_switch_wal() cannot be " + "performed on the standby, the command will only test the repository configuration.\n" "\n" "Note that pg_create_restore_point('pgBackRest Archive Check') and pg_switch_xlog()/pg_switch_wal() are called to " "force PostgreSQL to archive a WAL segment. Restore points are only supported in PostgreSQL >= 9.1 so for older " @@ -151,8 +151,8 @@ static ConfigDefineCommandData configDefineCommandData[] = CFGDEFDATA_COMMAND_LI "To delete a stanza:\n" "\n" "* Shut down the PostgreSQL cluster associated with the stanza (or use --force to override).\n" - "* Run the stop command on the backup host (the host where the repository is mounted).\n" - "* Run the stanza-delete command on the backup host.\n" + "* Run the stop command on the repository host.\n" + "* Run the stanza-delete command on the repository host.\n" "\n" "Once the command successfully completes, it is the responsibility of the user to remove the stanza from all " "pgBackRest configuration files." @@ -167,8 +167,8 @@ static ConfigDefineCommandData configDefineCommandData[] = CFGDEFDATA_COMMAND_LI CFGDEFDATA_COMMAND_HELP_DESCRIPTION ( "Immediately after upgrading PostgreSQL to a newer major version, the pg-path for all pgBackRest configurations must " - "be set to the new database location and the stanza-upgrade run on the backup host. If the database is offline use " - "the --no-online option." + "be set to the new database location and the stanza-upgrade run on the repository host. If the database is offline " + "use the --no-online option." ) ) @@ -684,7 +684,7 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST CFGDEFDATA_OPTION_HELP_DESCRIPTION ( "Sets the zlib level to be used for protocol compression when compress=n and the database cluster is not on the same " - "host as the backup. Protocol compression is used to reduce network traffic but can be disabled by setting " + "host as the repository. Protocol compression is used to reduce network traffic but can be disabled by setting " "compress-level-network=0. When compress=y the compress-level-network setting is ignored and compress-level is " "used instead so that the file is only compressed once. SSH compression is always disabled." ) @@ -1615,7 +1615,7 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST CFGDEFDATA_OPTION_HELP_SUMMARY("PostgreSQL host for operating remotely via SSH.") CFGDEFDATA_OPTION_HELP_DESCRIPTION ( - "Used for backups where the PostgreSQL host is different from the backup host." + "Used for backups where the PostgreSQL host is different from the repository host." ) CFGDEFDATA_OPTION_COMMAND_LIST diff --git a/test/expect/real-help-001.log b/test/expect/real-help-001.log index 2fdc6d5a0..bf77d48c8 100644 --- a/test/expect/real-help-001.log +++ b/test/expect/real-help-001.log @@ -132,9 +132,9 @@ The check command validates that pgBackRest and the archive_command setting are configured correctly for archiving and backups. It detects misconfigurations, particularly in archiving, that result in incomplete backups because required WAL segments did not reach the archive. The command can be run on the database -or the backup host. The command may also be run on the standby host, however, -since pg_switch_xlog()/pg_switch_wal() cannot be performed on the standby, the -command will only test the repository configuration. +or the repository host. The command may also be run on the standby host, +however, since pg_switch_xlog()/pg_switch_wal() cannot be performed on the +standby, the command will only test the repository configuration. Note that pg_create_restore_point('pgBackRest Archive Check') and pg_switch_xlog()/pg_switch_wal() are called to force PostgreSQL to archive a