3.16.0 release

docs/backup.config-example

@@ -0,0 +1,147 @@
+# GitHub Enterprise Server backup configuration file
+
+# The hostname of the GitHub Enterprise Server appliance to back up. The host
+# must be reachable via SSH from the backup host.
+GHE_HOSTNAME="github.example.com"
+
+# Path to where backup data is stored. By default this is the "data"
+# directory next to this file but can be set to an absolute path
+# elsewhere for backing up to a separate partition / mount point.
+GHE_DATA_DIR="data"
+
+# The number of backup snapshots to retain. Old snapshots are pruned after each
+# successful ghe-backup run. This option should be tuned based on the frequency
+# of scheduled backup runs. If backups are scheduled hourly, snapshots will be
+# available for the past N hours; if backups are scheduled daily, snapshots will
+# be available for the past N days ...
+GHE_NUM_SNAPSHOTS=10
+
+# Pruning snapshots can be scheduled outside of the backup process.
+# If set to 'yes', snapshots will not be pruned by ghe-backup.
+# Instead, ghe-prune-snapshots will need to be invoked separately via cron
+#GHE_PRUNING_SCHEDULED=yes
+
+# If --incremental is used to generate incremental MySQL backups with ghe-backup,
+# then you need to specify how many cycles of full and incremental backups will be 
+# performed before the next full backup is created.
+# For example, if `GHE_INCREMENTAL_BACKUP_MAX` is set to 14, backup-utils will 
+# run 1 full backup and then 13 incremental backups before performing another full backup on the next cycle.
+#GHE_INCREMENTAL_MAX_BACKUPS=14
+
+# If GHE_ROUTE_VERIFICATION is set to true then ghe-repository-backup and
+# ghe-storage-backup will issue a warning if the repositories and objects in
+# the backup do not match the pre-backup inventory of routes.
+#GHE_ROUTE_VERIFICATION=false
+
+# If GHE_MANAGE_CONSOLE_PW_RESTORE is set to false then management-console password
+# will not be restored from backed-up snapshot data, it is restored by default
+#GHE_MANAGE_CONSOLE_PW_RESTORE=true
+
+# If GHE_SKIP_CHECKS is set to true (or if --skip-checks is used with ghe-backup) then ghe-host-check
+# disk space validation and software version checks on the backup-host will be disabled.
+#GHE_SKIP_CHECKS=false
+
+# Cluster filesystem to check if it's writable as part of ghe-host-check
+# By default it is /data/user/tmp but can be updated if needed
+#GHE_FILE_SYSTEM_WRITE_CHECK="/data/user/tmp"
+
+# The hostname of the GitHub appliance to restore. If you've set up a separate
+# GitHub appliance to act as a standby for recovery, specify its IP or hostname
+# here. The host to restore to may also be specified directly when running
+# ghe-restore so use of this variable isn't strictly required.
+#
+#GHE_RESTORE_HOST="github-standby.example.com"
+
+# If set to 'yes', ghe-restore will omit the restore of audit logs.
+#
+#GHE_RESTORE_SKIP_AUDIT_LOGS=no
+
+# If set to 'yes', backup and restore of Elasticsearch indices will be skipped
+#
+#GHE_SKIP_SEARCH_INDICES=no
+
+# When verbose output is enabled with `-v`, it's written to stdout by default. If
+# you'd prefer it to be written to a separate file, set this option.
+#
+#GHE_VERBOSE_LOG="/var/log/backup-verbose.log"
+
+# Any extra options passed to the SSH command.
+# In a single instance environment, nothing is required by default.
+# In a clustering environment, "-i abs-path-to-ssh-private-key" is required.
+#
+#GHE_EXTRA_SSH_OPTS=""
+#
+# All backup processes are ran with the lowest priority for scheduling by default.
+# To change throttling behaviour/allow higher priority for backup processes, set higher values for following variables.
+# default value for GHENICE=nice -n 19
+# default value for GHE_IONICE=ionice -c 3
+#GHE_NICE=""
+#GHE_IONICE=""
+
+# Any extra options passed to the rsync command. Nothing required by default.
+#
+#GHE_EXTRA_RSYNC_OPTS=""
+
+# If set to 'yes', rsync will be set to use compression during backups and restores transfers. Defaults to 'no'.
+#
+#GHE_RSYNC_COMPRESSION_ENABLED=yes
+
+# If enabled and set to 'no', rsync warning message during backups will be suppressed.
+#RSYNC_WARNING=no
+
+
+# If set to 'yes', logging output will be colorized.
+#
+#OUTPUT_COLOR=no
+
+# If set to 'no', GHE_DATA_DIR will not be created automatically
+# and restore/backup will exit 8
+#
+#GHE_CREATE_DATA_DIR=yes
+
+# If set to 'yes', git fsck will run on the repositories
+# and print some additional info.
+#
+# WARNING: do not enable this, only useful for debugging/development
+#GHE_BACKUP_FSCK=no
+
+# Cadence of MSSQL backups
+# <full>,<differential>,<transactionlog> all in minutes
+# e.g.
+#   - Full backup every week (10080 minutes)
+#   - Differential backup every day (1440 minutes)
+#   - Transactionlog backup every 15 minutes
+#
+#GHE_MSSQL_BACKUP_CADENCE=10080,1440,15
+
+# If set to 'yes', ghe-backup jobs will run in parallel. Defaults to 'no'.
+#
+#GHE_PARALLEL_ENABLED=yes
+
+# Sets the maximum number of jobs to run in parallel. Defaults to the number
+# of available processing units on the machine.
+#
+#GHE_PARALLEL_MAX_JOBS=2
+
+# Sets the maximum number of rsync jobs to run in parallel. Defaults to the
+# configured GHE_PARALLEL_MAX_JOBS, or the number of available processing 
+# units on the machine.
+#
+# GHE_PARALLEL_RSYNC_MAX_JOBS=3
+
+# When jobs are running in parallel wait as needed to avoid starting new jobs
+# when the system's load average is not below the specified percentage. Defaults to
+# unrestricted.
+#
+#GHE_PARALLEL_MAX_LOAD=50
+
+# When running an external mysql database, run this script to trigger a MySQL backup
+# rather than attempting to backup via backup-utils directly.
+#EXTERNAL_DATABASE_BACKUP_SCRIPT="/bin/false"
+
+# When running an external mysql database, run this script to trigger a MySQL restore
+# rather than attempting to backup via backup-utils directly.
+#EXTERNAL_DATABASE_RESTORE_SCRIPT="/bin/false"
+
+# If set to 'yes', Pages data will be included in backup and restore. Defaults to 'yes'
+#GHE_BACKUP_PAGES=no

docs/getting-started.md

@@ -7,7 +7,7 @@
     **Note**: you will need to use [Backup Utilities v2.11.x][2] or the `legacy` branch to
     backup and restore GitHub Enterprise Server 2.10 and earlier.
 
- 2. Copy the `backup.config-example` file to `backup.config` and modify as
+ 2. Copy the [`backup.config-example`][3] file to `backup.config` and modify as
     necessary. The `GHE_HOSTNAME` value must be set to the primary GitHub Enterprise Server
     hostname. Additional options are available and documented in the
     configuration file but none are required for basic backup functionality.
@@ -28,7 +28,7 @@
       with the `-i <abs path to private key>` SSH option.
 
  3. Add the backup host's SSH public key to the GitHub Enterprise Server appliance, in order to grant it administrative shell access.
-    See [Accessing the GitHub Enterprise Server administrative shell (SSH)][3] for instructions.
+    See [Accessing the GitHub Enterprise Server administrative shell (SSH)][4] for instructions.
 
  4. Run `bin/ghe-host-check` to verify SSH connectivity with the GitHub
     appliance.
@@ -37,4 +37,5 @@
 
 [1]: https://github.com/github/backup-utils/releases
 [2]: https://github.com/github/backup-utils/releases/tag/v2.11.4
-[3]: https://docs.github.com/enterprise-server/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh
+[3]: https://github.com/github/enterprise-backup-site/blob/master/docs/backup.config-example
+[4]: https://docs.github.com/enterprise-server/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh

docs/usage.md

@@ -13,7 +13,7 @@ These commands are run on the host you [installed][1] Backup Utilities on.
 
 You can supply your own configuration file or use the example configuration file as a template where you can set up your environment for backing up and restoring.
 
-An example configuration file with documentation on possible settings can found in [backup.config-example](../backup.config-example).
+An example configuration file with documentation on possible settings can found in [backup.config-example](backup.config-example).
 
 There are a number of command-line options that can also be passed to the `ghe-restore` command. Of particular note, if you use an external MySQL service but are restoring from a snapshot prior to enabling this, or vice versa, you must migrate the MySQL data outside of the context of backup-utils first, then pass the `--skip-mysql` flag to `ghe-restore`.