README.md

   1 # Backup Script
   2
   3 A script for backing up data using `ssh`(1), `rsync`(1), and `scp`(1).
   4 Can handle backup generations on *btrfs* and *ZFS*.
   5
   6 Copyright (c)2008-2020 Alexander Barton (<alex@barton.de>)
   7 Homepage: <https://github.com/alexbarton/backup-script>
   8
   9 ## Installation
  10
  11 Call the scripts located in `./bin` directly from the source folder, or run
  12 `make install` to install them to `/usr/local/sbin`.
  13
  14 You can set `PREFIX` to use an other path prefix than `/usr/local` like this:
  15 `make PREFIX=/opt/backup-script install`.
  16
  17 ## Usage
  18
  19 ### backup-script
  20
  21 Run all or individual backup jobs.
  22
  23 Usage: `backup-script [<options>] [<job> [<job> [...]]]`
  24
  25 Options:
  26
  27 - `-n`, `--dry-run`: Test run only, don't copy any data.
  28 - `-p`, `--progress`: Show progress, see rsync(1).
  29 - `-t TAG`, `--tag TAG`: Only run jobs with tag TAG (see "tags" variable below).
  30 - `-x`, `--no-exec`: Don't run global setup-, pre-, and post-exec commands.
  31
  32 When no *job* is given, all defined jobs are run.
  33
  34 ### backup-script-wrapper
  35
  36 Backup all systems ("run all jobs") and mail the report to "root".
  37
  38 Usage: `backup-script-wrapper [<backup-script-options-and-job-names ...>]`
  39
  40 ### backup-status
  41
  42 Show information about backups.
  43
  44 Usage:
  45
  46 - `backup-status [--errors|--latest] [--quick] [<job> [<job> [...]]]`
  47 - `backup-status --running`
  48
  49 Options:
  50
  51 - `-e`, `--errors`: only show current backups with errors (implies `--latest`).
  52 - `-l`, `--latest`: only show latest backup generations.
  53 - `-q`, `--quick`: *quick mode*, don't calculate backup sizes.
  54 - `-r`, `--running`: check if an `backup-script` task is currently running.
  55
  56 When no *job* is given, all defined jobs are listed.
  57
  58 ### backup-audit
  59
  60 Show "relevant" differences in system configuration between backup generations.
  61
  62 Usage: `backup-audit [-q] [-v] [<job> [<job> [...]]]`
  63
  64 Options:
  65
  66 - `-d`, `--dirs`: compare two backup directories (not jobs).
  67 - `-q`, `--quiet`: *quite mode*, only list jobs with changes or errors.
  68 - `-v`, `--verbose`: *verbose mode*, show all checks that are run.
  69
  70 When no *job* is given, all defined jobs are checked.
  71
  72 ## Configuration
  73
  74 All default configuration variables are read from the first file found of this
  75 list: `/usr/local/etc/backup-scrupt.conf`, `/etc/backup-script.conf` or
  76 from `/etc/backup-script.d/backup-script.conf` (deprecated).
  77
  78 All jobs that should be backed-up are configured using individual files
  79 in the configuration directory, which is `/usr/local/etc/backup-script.d/` or
  80 `/etc/backup-script.d/` by default (whichever is found first), and can be
  81 specified using the `conf_d` variable in the main configuration file.
  82
  83 The must be one job file for each system to backup (files ending in `*.sh` are
  84 skipped, as well as files named `backup-script.conf`). Please avoid spaces and
  85 other "special" characters! The filename is used as hostname for the system by
  86 default, but this can be overwritten using the `system` configuration variable.
  87
  88 Variables in `backup-script.conf` must be prefixed with `default_` to define
  89 default values for all jobs.
  90
  91 All defaults can be overwritten in the individual job configuration files.
  92
  93 For example:
  94
  95 - `/etc/backups-script.conf`: defaults for all hosts
  96 - `/etc/backups-script.d/host01.example.net`: configuration for host 1
  97 - `/etc/backups-script.d/clientXY.example.com`: configuration for host 2
  98
  99 ### Global Settings
 100
 101 The following global configuration options exist:
 102
 103 - `setup_exec`: Script to run _before_ creating the lock file etc.
 104 - `pre_exec`: Pre-execution script, run before all jobs.
 105 - `post_exec`: Post-execution script, run after all jobs.
 106
 107 In Addition, all job configuration options (see below) that have a "default_XXX"
 108 variant can be used and define default values for all jobs that don't overwrite
 109 them individually.
 110
 111 ## Configuration Variables
 112
 113 ### system
 114
 115 System host name. Default: file name.
 116
 117 *Note:* There is no `default_system` variable!
 118
 119 ### [default_]backup_type
 120
 121 Backup type to use. Default: `rsync`.
 122
 123 - `rsync`: system backup using rsync(1).
 124   Use `source_root` to specify the root directory to save.
 125
 126 - `scp`: file backup using scp(1).
 127   Use `files` to specify the files to copy.
 128
 129 - `disabled`: job is disabled and will not be run. This becomes accounted as
 130   "success" in the summary and exit code of the backup script.
 131
 132 Please note that neither `ssh_args_add`, `rsync_args_add`, `compress`, nor any
 133 "exclude" parameters are supported when using the "scp" backup type! And There
 134 "scp" backup type never _deletes_ files from the backup store; so if you reduce
 135 the list of files to backup, old files will still be kept, because they were
 136 already saved in an older generation (but no longer updated).
 137
 138 ### [default_]user
 139
 140 Remote user. Default: `root`.
 141
 142 ### [default_]source_root
 143
 144 Remote *root* directory, must end with a slash ("/") character! Default: "/".
 145
 146 When saving the whole (remote) system ("/"), default excludes are set up
 147 automatically, which exclude standard system directories like /sys and /proc.
 148
 149 ### [default_]files
 150
 151 Space separated list of files to copy when using the "scp" `backup_type`.
 152 Default: "running-config".
 153
 154 ### [default_]target
 155
 156 Local backup directory. The backup data of each job is stored in a folder named
 157 like the job (see `system` variable) inside of this target directory.
 158
 159 *Note:* There is *no* default, you have to specify this variable, for example as
 160 `default_target` in the `backups-script.conf` file!
 161
 162 ### [default_]ssh_args_add
 163
 164 Additional parameters for `ssh`. Default: none.
 165
 166 ### [default_]rsync_args_add
 167
 168 Additional parameters for `rsync`. Default: none.
 169
 170 ### [default_]exclude_args_add
 171
 172 Additional (exclude) parameters for `rsync`. Default: none.
 173
 174 *Deprecated! Use "exclude_dirs_add" instead!*
 175
 176 ### [default_]exclude_dirs_add
 177
 178 Additional directory path names to exclude from the backup. Use full path names
 179 separated by spaces. Default: none.
 180
 181 ### [default_]compress
 182
 183 Enable (1) or disable (0) rsync transfer compression. Default: 1 (on).
 184
 185 ### [default_]ping
 186
 187 Enable (1) or disable (0) ping'ing the target system to make sure that it is
 188 reachable before calling `rsync`. Default: 1 (on).
 189
 190 ### [default_]local
 191
 192 Enable (1) or disable (0) *local mode*: when local mode is in effect, `rsync` is
 193 called without using `ssh`, which is a good idea when saving the local system.
 194 Default: 0 (off; use ssh).
 195
 196 ### [default_]generations
 197
 198 Number of generations to keep. Default: 0 (none).
 199
 200 On a suitable target file systems (see `target` variable), this script can
 201 generate generations using snapshots: the script creates a new snapshot
 202 named with the time stamp for each generation inside of the system directory
 203 inside of the target directory.
 204
 205 Supported file systems are:
 206
 207 - *btrfs*:
 208   All generations are btrfs subvolumes and named after the date and time.
 209 - *ZFS*:
 210   All generations are ZFS file systems. Latest generation is named `current`,
 211   elders are links to the ZFS snapshot directories.
 212
 213 The latest snapshot is always reachable using a symlink named `latest`
 214 inside the system directory.
 215
 216 ### [default_]io_timeout
 217
 218 The maximum I/O timeout in seconds. If no data is transferred for the specified
 219 time then rsync will abort. Default: 1800 (30 minutes).
 220
 221 ### [default_]tags
 222
 223 Comma-separated list of tags of this job. All uppercase tag names are reserved
 224 and become set automatically on runtime:
 225
 226 - NONE: Jobs with no other tags at all.
 227 - ALL: Matches all jobs, regardless of their tags (see `-t`/`--tags` option).
 228 - LOCAL: All jobs running on "localhost".
 229
 230 Default: NONE.
 231
 232 ### [default_]job_pre_exec
 233
 234 Optional script to execute before `rsync` starts. Default: none.
 235
 236 When the `job_pre_exec` script returns an error (exit code is not 0), the backup
 237 run is skipped!
 238
 239 ### [default_]job_post_exec
 240
 241 Optional script to execute after `rsync` exited. Default: none.
 242
 243 ### Compatibility Variables
 244
 245 The following job configurations variables used by the outdated backup-pull(1)
 246 script in job definition files are automatically mapped to the new backup-script
 247 variables:
 248
 249 - `host` -> `system`
 250 - `source` -> `source_root`
 251 - `pre_exec` -> `job_pre_exec`
 252 - `post_exec` -> `job_post_exec`
 253
 254 ## Exit codes
 255
 256 - 0: No error, success.
 257 - 1: Unspecific Error!
 258 - 2: Usage information has been shown.
 259 - 3: Can't read job definition
 260 - 4: PID-file exists!
 261 - 5: Pre-exec command failed!
 262 - 6: There have been jobs with errors!
 263 - 7: Not all jobs were run!
 264 - 9: Aborted (CTRL-C)!