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