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