3 A script for backing up data using `ssh`(1), `rsync`(1), and `scp`(1).
4 Can handle backup generations on *btrfs* and *ZFS*.
6 Copyright (c)2008-2022 Alexander Barton (<alex@barton.de>)
7 Homepage: <https://github.com/alexbarton/backup-script>
11 Call the scripts located in `./bin` directly from the source folder, or run
12 `make install` to install them to `/usr/local/sbin`.
14 You can set `PREFIX` to use an other path prefix than `/usr/local` like this:
15 `make PREFIX=/opt/backup-script install`.
21 Run all or individual backup jobs.
23 Usage: `backup-script [<options>] [<job> [<job> [...]]]`
27 - `-n`, `--dry-run`: Test run only, don't copy any data.
28 - `-p`, `--progress`: Show progress, see rsync(1).
29 - `-t TAG`, `--tag TAG`: Only run jobs with tag TAG (see "tags" variable below).
30 - `-x`, `--no-exec`: Don't run global setup-, pre-, and post-exec commands.
32 When no *job* is given, all defined jobs are run.
34 ### backup-script-wrapper
36 Backup all systems ("run all jobs") and mail the report to "root".
38 Usage: `backup-script-wrapper [<backup-script-options-and-job-names ...>]`
42 Show information about backups.
46 - `backup-status [--errors|--latest] [--quick] [<job> [<job> [...]]]`
47 - `backup-status --running`
51 - `-e`, `--errors`: only show current backups with errors (implies `--latest`).
52 - `-l`, `--latest`: only show latest backup generations.
53 - `-q`, `--quick`: *quick mode*, don't calculate backup sizes.
54 - `-r`, `--running`: check if an `backup-script` task is currently running.
56 When no *job* is given, all defined jobs are listed.
60 Show "relevant" differences in system configuration between backup generations.
62 Usage: `backup-audit [-q] [-v] [<job> [<job> [...]]]`
66 - `-d`, `--dirs`: compare two backup directories (not jobs).
67 - `-q`, `--quiet`: *quite mode*, only list jobs with changes or errors.
68 - `-v`, `--verbose`: *verbose mode*, show all checks that are run.
70 When no *job* is given, all defined jobs are checked.
74 All default configuration variables are read from the first file found of this
75 list: `/usr/local/etc/backup-script.conf`, `/etc/backup-script.conf` or
76 from `/etc/backup-script.d/backup-script.conf` (deprecated).
78 All jobs that should be backed-up are configured using individual files
79 in the configuration directory, which is `/usr/local/etc/backup-script.d/` or
80 `/etc/backup-script.d/` by default (whichever is found first), and can be
81 specified using the `conf_d` variable in the main configuration file.
83 The must be one job file for each system to backup (files ending in `*.sh` are
84 skipped, as well as files named `backup-script.conf`). Please avoid spaces and
85 other "special" characters! The filename is used as hostname for the system by
86 default, but this can be overwritten using the `system` configuration variable.
88 Variables in `backup-script.conf` must be prefixed with `default_` to define
89 default values for all jobs.
91 All defaults can be overwritten in the individual job configuration files.
95 - `/etc/backups-script.conf`: defaults for all hosts
96 - `/etc/backups-script.d/host01.example.net`: configuration for host 1
97 - `/etc/backups-script.d/clientXY.example.com`: configuration for host 2
101 The following global configuration options exist:
103 - `setup_exec`: Script to run *before* creating the lock file etc.
104 - `pre_exec`: Pre-execution script, run before all jobs.
105 - `post_exec`: Post-execution script, run after all jobs.
107 In Addition, all job configuration options (see below) that have a "default_XXX"
108 variant can be used and define default values for all jobs that don't overwrite
111 ## Configuration Variables
115 System host name. Default: file name.
117 *Note:* There is no `default_system` variable!
119 ### [default_]backup_type
121 Backup type to use. Default: `rsync`.
123 - `rsync`: system backup using rsync(1).
124 Use `source_root` to specify the root directory to save.
126 - `scp`: file backup using scp(1).
127 Use `files` to specify the files to copy.
129 - `disabled`: job is disabled and will not be run. This becomes accounted as
130 "success" in the summary and exit code of the backup script.
132 Please note that neither `ssh_args_add`, `rsync_args_add`, `compress`, nor any
133 "exclude" parameters are supported when using the "scp" backup type! And There
134 "scp" backup type never *deletes* files from the backup store; so if you reduce
135 the list of files to backup, old files will still be kept, because they were
136 already saved in an older generation (but no longer updated).
140 Remote user. Default: `root`.
142 ### [default_]source_root
144 Remote *root* directory, must end with a slash ("/") character! Default: "/".
146 When saving the whole (remote) system ("/"), default excludes are set up
147 automatically, which exclude standard system directories like /sys and /proc.
151 Space separated list of files to copy when using the "scp" `backup_type`.
152 Default: "running-config".
156 Local backup directory. The backup data of each job is stored in a folder named
157 like the job (see `system` variable) inside of this target directory.
159 *Note:* There is *no* default, you have to specify this variable, for example as
160 `default_target` in the `backups-script.conf` file!
162 ### [default_]ssh_args_add
164 Additional parameters for `ssh`. Default: none.
166 ### [default_]rsync_args_add
168 Additional parameters for `rsync`. Default: none.
170 ### [default_]exclude_args_add
172 Additional (exclude) parameters for `rsync`. Default: none.
174 *Deprecated! Use "exclude_dirs_add" instead!*
176 ### [default_]exclude_dirs_add
178 Additional directory path names to exclude from the backup. Use full path names
179 separated by spaces. Default: none.
181 ### [default_]compress
183 Enable (1) or disable (0) rsync transfer compression. Default: 1 (on).
187 Enable (1) or disable (0) ping'ing the target system to make sure that it is
188 reachable before calling `rsync`. Default: 1 (on).
192 Enable (1) or disable (0) *local mode*: when local mode is in effect, `rsync` is
193 called without using `ssh`, which is a good idea when saving the local system.
194 Default: 0 (off; use ssh).
196 ### [default_]generations
198 Number of generations to keep. Default: 0 (none).
200 On a suitable target file systems (see `target` variable), this script can
201 generate generations using snapshots: the script creates a new snapshot
202 named with the time stamp for each generation inside of the system directory
203 inside of the target directory.
205 Supported file systems are:
208 All generations are btrfs subvolumes and named after the date and time.
210 All generations are ZFS file systems. Latest generation is named `current`,
211 elders are links to the ZFS snapshot directories.
213 The latest snapshot is always reachable using a symlink named `latest`
214 inside the system directory.
216 ### [default_]io_timeout
218 The maximum I/O timeout in seconds. If no data is transferred for the specified
219 time then rsync will abort. Default: 1800 (30 minutes).
223 Comma-separated list of tags of this job. All uppercase tag names are reserved
224 and become set automatically on runtime:
226 - NONE: Jobs with no other tags at all.
227 - ALL: Matches all jobs, regardless of their tags (see `-t`/`--tags` option).
228 - LOCAL: All jobs running on "localhost".
232 ### [default_]job_pre_exec
234 Optional script to execute before `rsync` starts. Default: none.
236 When the `job_pre_exec` script returns an error (exit code is not 0), the backup
239 ### [default_]job_post_exec
241 Optional script to execute after `rsync` exited. Default: none.
243 ### Compatibility Variables
245 The following job configurations variables used by the outdated backup-pull(1)
246 script in job definition files are automatically mapped to the new backup-script
250 - `source` -> `source_root`
251 - `pre_exec` -> `job_pre_exec`
252 - `post_exec` -> `job_post_exec`
256 - 0: No error, success.
257 - 1: Unspecific Error!
258 - 2: Usage information has been shown.
259 - 3: Can't read job definition
260 - 4: PID-file exists!
261 - 5: Pre-exec command failed!
262 - 6: There have been jobs with errors!
263 - 7: Not all jobs were run!
264 - 9: Aborted (CTRL-C)!