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