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 ## Configuration Variables
  80
  81 ### system
  82
  83 System host name. Default: file name.
  84
  85 *Note:* There is no `default_system` variable!
  86
  87 ### [default_]backup_type
  88
  89 Backup type to use. Default: `rsync`.
  90
  91 - `rsync`: system backup using rsync(1).
  92   Use `source_root` to specify the root directory to save.
  93
  94 - `scp`: file backup using scp(1).
  95   Use `files` to specify the files to copy.
  96
  97 - `disabled`: job is disabled and will not be run. This becomes accounted as
  98   "success" in the summary and exit code of the backup script.
  99
 100 Please note that neither `ssh_args_add`, `rsync_args_add`, `compress`, nor any
 101 "exclude" parameters are supported when using the "scp" backup type! And There
 102 "scp" backup type never _deletes_ files from the backup store; so if you reduce
 103 the list of files to backup, old files will still be kept, because they were
 104 already saved in an older generation (but no longer updated).
 105
 106 ### [default_]user
 107
 108 Remote user. Default: `root`.
 109
 110 ### [default_]source_root
 111
 112 Remote *root* directory, must end with a slash ("/") character! Default: "/".
 113
 114 When saving the whole (remote) system ("/"), default excludes are set up
 115 automatically, which exclude standard system directories like /sys and /proc.
 116
 117 ### [default_]files
 118
 119 Space separated list of files to copy when using the "scp" `backup_type`.
 120 Default: "running-config".
 121
 122 ### [default_]target
 123
 124 Local backup directory. The backup of each system is stored in a folder named
 125 like the system (see `system` variable) inside of this target directory.
 126
 127 *Note:* There is *no* default, you have to specify this variable, for example as
 128 `default_target` in the `backups-script.conf` file!
 129
 130 ### [default_]ssh_args_add
 131
 132 Additional parameters for `ssh`. Default: none.
 133
 134 ### [default_]rsync_args_add
 135
 136 Additional parameters for `rsync`. Default: none.
 137
 138 ### [default_]exclude_args_add
 139
 140 Additional (exclude) parameters for `rsync`. Default: none.
 141
 142 *Deprecated! Use "exclude_dirs_add" instead!*
 143
 144 ### [default_]exclude_dirs_add
 145
 146 Additional directory path names to exclude from the backup. Use full path names
 147 separated by spaces. Default: none.
 148
 149 ### [default_]compress
 150
 151 Enable (1) or disable (0) rsync transfer compression. Default: 1 (on).
 152
 153 ### [default_]ping
 154
 155 Enable (1) or disable (0) ping'ing the target system to make sure that it is
 156 reachable before calling `rsync`. Default: 1 (on).
 157
 158 ### [default_]local
 159
 160 Enable (1) or disable (0) *local mode*: when local mode is in effect, `rsync` is
 161 called without using `ssh`, which is a good idea when saving the local system.
 162 Default: 0 (off; use ssh).
 163
 164 ### [default_]generations
 165
 166 Number of generations to keep. Default: 0 (none).
 167
 168 On a suitable target file systems (see `target` variable), this script can
 169 generate generations using snapshots: the script creates a new snapshot
 170 named with the time stamp for each generation inside of the system directory
 171 inside of the target directory.
 172
 173 Supported file systems are:
 174
 175  * *btrfs*:
 176    All generations are btrfs subvolumes and named after the date and time.
 177  * *ZFS*:
 178    All generations are ZFS file systems. Latest generation is named `current`,
 179    elders are links to the ZFS snapshot directories.
 180
 181 The latest snapshot is always reachable using a symlink named `latest`
 182 inside the system directory.
 183
 184 ### [default_]io_timeout
 185
 186 The maximum I/O timeout in seconds. If no data is transferred for the specified
 187 time then rsync will abort. Default: 1800 (30 minutes).
 188
 189 ### [default_]tags
 190
 191 Comma-separated list of tags of this job. All uppercase tag names are reserved
 192 and become set automatically on runtime:
 193
 194 - NONE: Jobs with no other tags at all.
 195 - ALL: Matches all jobs, regardless of their tags (see `-t`/`--tags` option).
 196 - LOCAL: All jobs running on "localhost".
 197
 198 Default: NONE.
 199
 200 ### [default_]job_pre_exec
 201
 202 Optional script to execute before `rsync` starts. Default: none.
 203
 204 When the `job_pre_exec` script returns an error (exit code is not 0), the backup
 205 run is skipped!
 206
 207 ### [default_]job_post_exec
 208
 209 Optional script to execute after `rsync` exited. Default: none.
 210
 211 ### Compatibility Variables
 212
 213 The following configurations variables used by the backup-pull(1) script in job
 214 definition files are automatically mapped to the new backup-script variables:
 215
 216 * host -> system
 217 * source -> source_root
 218 * pre_exec -> job_pre_exec
 219 * post_exec -> job_post_exec
 220
 221
 222 ## Exit codes
 223
 224 - 1: Unspecific Error!
 225 - 2: Usage information has been shown.
 226 - 3: Can't read system definition
 227 - 4: PID-file exists!
 228 - 5: Pre-exec command failed!
 229 - 6: There have been systems with errors!
 230 - 7: Not all jobs were run!
 231 - 9: Aborted (CTRL-C)!