README.md

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