# Backup Script
+A script for cloning systems using rsync.
+Copyright (c)2008-2015 Alexander Barton <alex@barton.de>
+
## Usage
- `-p`, `--progress`: Show progress, see rsync(1).
- `-n`, `--dry-run`: Test run only, don't copy any data.
-When no *system* is given, all defined systems are used.
+When no *system* is given, all defined systems are backed up.
### backup-script-wrapper
## Configuration
-All defauklt configuration variables are read from `/etc/backup-script.conf`,
-from `/etc/backup-script.d/backup-script.conf` (deprecated). The individual
-systems are configured using individual files in `/etc/backup-script.d/`, one
-for each system to backup (files ending in `*.sh` are skipped).
+All default configuration variables are read from the first file found of this
+list: `/usr/local/etc/backup-scrupt.conf`, `/etc/backup-script.conf` or
+from `/etc/backup-script.d/backup-script.conf` (deprecated).
+
+All systems which should be backed-up are configured using individual files
+in the configuration directory, which is `/usr/local/etc/backup-script.d/` or
+`/etc/backup-script.d/` by default (whichever is found first), and can be
+specified using the `conf_d` variable in the main configuration file.
+
+The must be one file for each system to backup (files ending in `*.sh` are
+skipped, as well as files named `backup-script.conf`). Please avoid spaces and
+other "special" characters! The filename is used as hostname for the system by
+default, but this can be overwritten using the `system` configuration variable.
Variables in `backup-script.conf` must be prefixed with `default_` to define
default values for all systems.
-All default can be overwritten in individual system configuration files.
+All defaults can be overwritten in the individual system configuration files.
For example:
- `/etc/backups-script.d/clientXY.example.com`: configuration for host 2
-## Configuration Variable
+## Configuration Variables
### system
Remote user. Default: `root`.
+### [default_]source_root
+
+Remote *root* directory, must end with a slash ("/") character! Default: "/".
+
+When saving the whole (remote) system ("/"), default excludes are set up
+automatically, which exclude standard system directories like /sys and /proc.
+
### [default_]target
Local backup directory. The backup of each system is stored in a folder named
Number of generations to keep. Default: 0 (none).
-On a *btrfs* target file systems (see `target` variable), this script can
-generate generations using *btrfs snapshots*: the script creates a new snapshot
-named with the timestamp for each generation inside of the system directory
+On a suitable target file systems (see `target` variable), this script can
+generate generations using snapshots: the script creates a new snapshot
+named with the time stamp for each generation inside of the system directory
inside of the target directory.
+Supported file systems are:
+
+ * *btrfs*:
+ All generations are btrfs subvolumes and named after the date and time.
+ * *ZFS*:
+ All generations are ZFS file systems. Latest generation is named `current`,
+ elders are links to the ZFS snapshot directories.
+
+The latest snapshot is always reachable using a symlink named `latest`
+inside the system directory.
+
### [default_]job_pre_exec
Optional script to execute before `rsync` starts. Default: none.
### [default_]job_post_exec
Optional script to execute after `rsync` exited. Default: none.
+
+### Compatibility Variables
+
+The following configurations variables used by the backup-pull(1) script in job
+definition files are automatically mapped to the new backup-script variables:
+
+* host -> system
+* source -> source_root
+* pre_exec -> job_pre_exec
+* post_exec -> job_post_exec
+
+
+## Exit codes
+
+- 1: Unspecific Error!
+- 2: Usage information has been shown.
+- 3: Can't read system definition
+- 4: PID-file exists!
+- 5: Pre-exec command failed!
+- 6: There have been systems with errors!
+- 7: Not all jobs were run!
+- 9: Aborted (CTRL-C)!