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