X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=README.md;h=c6602d818e80eec8bc4549b88a1fccefaed1b018;hb=51e8c14f812714bb1bdad1d119be56ca79cb2076;hp=9c8332e5bc585d9adc66f5370367b7607fda8900;hpb=1228c73a2de75d9aea62cb916bd34a35f3682335;p=backup-script.git diff --git a/README.md b/README.md index 9c8332e..c6602d8 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # Backup Script +A script for cloning systems using rsync. +Copyright (c)2008-2016 Alexander Barton + ## Usage @@ -11,10 +14,11 @@ Usage: `backup-script [] [ [ [...]]]` Options: -- `-p`, `--progress`: Show progress, see rsync(1). - `-n`, `--dry-run`: Test run only, don't copy any data. +- `-p`, `--progress`: Show progress, see rsync(1). +- `-t TAG`, `--tag TAG`: Only run jobs with tag TAG (see "tags" variable below). -When no *system* is given, all defined systems are used. +When no *system* is given, all defined systems are backed up. ### backup-script-wrapper @@ -35,15 +39,24 @@ Options: ## 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: @@ -52,7 +65,7 @@ For example: - `/etc/backups-script.d/clientXY.example.com`: configuration for host 2 -## Configuration Variable +## Configuration Variables ### system @@ -60,10 +73,38 @@ System host name. Default: file name. *Note:* There is no `default_system` variable! +### [default_]backup_type + +Backup type to use. Default: `rsync`. + +- `rsync`: system backup using rsync(1). + Use `source_root` to specify the root directory to save. + +- `scp`: file backup using scp(1). + Use `files` to specify the files to copy. + +Please note that neither `ssh_args_add`, `rsync_args_add`, `compress`, nor any +"exclude" parameters are supported when using the "scp" backup type! And There +"scp" backup type never _deletes_ files from the backup store; so if you reduce +the list of files to backup, old files will still be kept, because they were +already saved in an older generation (but no longer updated). + ### [default_]user 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_]files + +Space separated list of files to copy when using the "scp" `backup_type`. +Default: "running-config". + ### [default_]target Local backup directory. The backup of each system is stored in a folder named @@ -84,9 +125,16 @@ Additional parameters for `rsync`. Default: none. Additional (exclude) parameters for `rsync`. Default: none. +*Deprecated! Use "exclude_dirs_add" instead!* + +### [default_]exclude_dirs_add + +Additional directory path names to exclude from the backup. Use full path names +separated by spaces. Default: none. + ### [default_]compress -Enable (1) or disable (0) compression. Default: 1 (on). +Enable (1) or disable (0) rsync transfer compression. Default: 1 (on). ### [default_]ping @@ -103,11 +151,38 @@ Default: 0 (off; use ssh). 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_]io_timeout + +The maximum I/O timeout in seconds. If no data is transferred for the specified +time then rsync will abort. Default: 1800 (30 minutes). + +### [default_]tags + +Comma-separated list of tags of this job. All uppercase tag names are reserved +and become set automatically on runtime: + +- NONE: Jobs with no other tags at all. +- ALL: Matches all jobs, regardless of their tags (see `-t`/`--tags` option). +- LOCAL: All jobs running on "localhost". + +Default: NONE. + ### [default_]job_pre_exec Optional script to execute before `rsync` starts. Default: none. @@ -118,3 +193,25 @@ run is skipped! ### [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)!