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