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