diff --git a/docs/getting-started.md b/docs/getting-started.md index 02f2cbe9b..ac85e5073 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,6 @@ # Getting started - 1. [Download the latest release version][1] and extract the repository using `tar`: + 1. [Download the latest version of backup-utils][1] and extract the repository using `tar`: `tar -xzvf /path/to/github-backup-utils-vMAJOR.MINOR.PATCH.tar.gz` diff --git a/docs/requirements.md b/docs/requirements.md index b2a3d282a..c87a0775a 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -69,23 +69,23 @@ Please avoid using an NFS mount for the data directory (where backup data is sto Starting with Backup Utilities v2.13.0, version support is inline with that of the [GitHub Enterprise Server upgrade requirements][8] and as such, support is limited to three versions of GitHub Enterprise Server: the version that corresponds with the version -of Backup Utilities, and the two releases prior to it. +of Backup Utilities, and the two versions prior to it. For example, Backup Utilities v2.13.0 can be used to backup and restore all patch -releases from 2.11.0 to the latest patch release of GitHub Enterprise Server 2.13. +versions from 2.11.0 to the latest patch version of GitHub Enterprise Server 2.13. Backup Utilities v2.14.0 will be released when GitHub Enterprise Server 2.14.0 is released -and will then be used to backup all releases of GitHub Enterprise Server from 2.12.0 -to the latest patch release of GitHub Enterprise Server 2.14. +and will then be used to backup all versions of GitHub Enterprise Server from 2.12.0 +to the latest patch version of GitHub Enterprise Server 2.14. Backup Utilities v2.11.4 and earlier offer support for GitHub Enterprise Server 2.10 -and earlier releases up to GitHub Enterprise Server 2.2.0. Backup Utilities v2.11.0 and earlier +and earlier versions up to GitHub Enterprise Server 2.2.0. Backup Utilities v2.11.0 and earlier offer support for GitHub Enterprise Server 2.1.0 and earlier. -**Note**: You can restore a snapshot that's at most two feature releases behind +**Note**: You can restore a snapshot that's at most two feature versions behind the restore target's version of GitHub Enterprise Server. For example, to restore a snapshot of GitHub Enterprise Server 2.11, the target GitHub Enterprise Server appliance must be running GitHub Enterprise Server 2.12.x or 2.13.x. You can't restore a snapshot from -2.10 to 2.13, because that's three releases ahead. +2.10 to 2.13, because that's three versions ahead. **Note**: You _cannot_ restore a backup created from a newer version of GitHub Enterprise Server to an older version. For example, an attempt to restore a snapshot of GitHub Enterprise Server 2.21 to a GitHub Enterprise Server 2.20 environment will fail with an error of `Error: Snapshot can not be restored to an older release of GitHub Enterprise Server.`. diff --git a/docs/scheduling-backups.md b/docs/scheduling-backups.md index 0e00a5d67..3a7b0d12c 100644 --- a/docs/scheduling-backups.md +++ b/docs/scheduling-backups.md @@ -3,7 +3,16 @@ Regular backups should be scheduled using `cron(8)` or similar command scheduling service on the backup host. The backup frequency will dictate the worst case [recovery point objective (RPO)][1] in your backup plan. We recommend -hourly backups at the least. +hourly backups as a starting point. + +It's important to consider the duration of each backup operation on the +GitHub Enterprise Server (GHES) appliance. Backups of large datasets or +over slow network links can take more than an hour. Additionally, +maintenance queues are paused during a portion of a backup runs. +We recommend scheduling backups to allow sufficient time for jobs +waiting in maintenance queues to process between backup runs + +Only one backup may be in progress at a time. ## Example scheduling of backups @@ -19,7 +28,8 @@ storage. To schedule hourly backup snapshots with verbose informational output written to a log file and errors generating an email: -``` + +```shell MAILTO=admin@example.com 0 * * * * /opt/backup-utils/bin/ghe-backup -v 1>>/opt/backup-utils/backup.log 2>&1 @@ -27,13 +37,13 @@ MAILTO=admin@example.com To schedule nightly backup snapshots instead, use: -``` +```shell MAILTO=admin@example.com 0 0 * * * /opt/backup-utils/bin/ghe-backup -v 1>>/opt/backup-utils/backup.log 2>&1 ``` -## Example snapshot pruning +## Example snapshot pruning By default all expired and incomplete snapshots are deleted at the end of the main backup process `ghe-backup`. If pruning these snapshots takes a long time you can @@ -44,7 +54,7 @@ If this option is enabled you will need to schedule the pruning script `ghe-prun To schedule daily snapshot pruning, use: -``` +```shell MAILTO=admin@example.com 0 3 * * * /opt/backup-utils/share/github-backup-utils/ghe-prune-snapshots 1>>/opt/backup-utils/prune-snapshots.log 2>&1