X-Git-Url: https://arthur.barton.de/gitweb/?p=backup-script.git;a=blobdiff_plain;f=README.md;h=47ec27a91819dc27d1d52b6355126ed3deb3e16d;hp=66d79aaa5d9cdc952fb1d1cae75af7d030dc5e22;hb=HEAD;hpb=710262ec600d1779191a4dd4402877fd4a390dad diff --git a/README.md b/README.md index 66d79aa..4f6ec52 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,73 @@ # Backup Script -A script for cloning systems using rsync. -Copyright (c)2008-2015 Alexander Barton +A script for backing up data using `ssh`(1), `rsync`(1), and `scp`(1). +Can handle backup generations on *btrfs* and *ZFS*. +Copyright (c)2008-2020 Alexander Barton () +Homepage: + +## Installation + +Call the scripts located in `./bin` directly from the source folder, or run +`make install` to install them to `/usr/local/sbin`. + +You can set `PREFIX` to use an other path prefix than `/usr/local` like this: +`make PREFIX=/opt/backup-script install`. ## Usage ### backup-script -Backup all or individual systems. +Run all or individual backup jobs. -Usage: `backup-script [] [ [ [...]]]` +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). +- `-x`, `--no-exec`: Don't run global setup-, pre-, and post-exec commands. -When no *system* is given, all defined systems are backed up. +When no *job* is given, all defined jobs are run. ### backup-script-wrapper -Backup all systems and mail the report to "root". +Backup all systems ("run all jobs") and mail the report to "root". -Usage: `backup-script-wrapper` +Usage: `backup-script-wrapper []` ### backup-status Show information about backups. -Usage: `backup-status [-q] [ [ [...]]]` +Usage: + +- `backup-status [--errors|--latest] [--quick] [ [ [...]]]` +- `backup-status --running` Options: -- `-q`: *quick mode*, don't calculate backup sizes. +- `-e`, `--errors`: only show current backups with errors (implies `--latest`). +- `-l`, `--latest`: only show latest backup generations. +- `-q`, `--quick`: *quick mode*, don't calculate backup sizes. +- `-r`, `--running`: check if an `backup-script` task is currently running. + +When no *job* is given, all defined jobs are listed. + +### backup-audit + +Show "relevant" differences in system configuration between backup generations. +Usage: `backup-audit [-q] [-v] [ [ [...]]]` + +Options: + +- `-d`, `--dirs`: compare two backup directories (not jobs). +- `-q`, `--quiet`: *quite mode*, only list jobs with changes or errors. +- `-v`, `--verbose`: *verbose mode*, show all checks that are run. + +When no *job* is given, all defined jobs are checked. ## Configuration @@ -42,20 +75,20 @@ 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 +All jobs that 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 +The must be one job 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. +default values for all jobs. -All defaults can be overwritten in the individual system configuration files. +All defaults can be overwritten in the individual job configuration files. For example: @@ -63,6 +96,17 @@ For example: - `/etc/backups-script.d/host01.example.net`: configuration for host 1 - `/etc/backups-script.d/clientXY.example.com`: configuration for host 2 +### Global Settings + +The following global configuration options exist: + +- `setup_exec`: Script to run _before_ creating the lock file etc. +- `pre_exec`: Pre-execution script, run before all jobs. +- `post_exec`: Post-execution script, run after all jobs. + +In Addition, all job configuration options (see below) that have a "default_XXX" +variant can be used and define default values for all jobs that don't overwrite +them individually. ## Configuration Variables @@ -72,6 +116,25 @@ 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. + +- `disabled`: job is disabled and will not be run. This becomes accounted as + "success" in the summary and exit code of the backup script. + +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`. @@ -83,10 +146,15 @@ 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 -like the system (see `system` variable) inside of this target directory. +Local backup directory. The backup data of each job is stored in a folder named +like the job (see `system` variable) inside of this target directory. *Note:* There is *no* default, you have to specify this variable, for example as `default_target` in the `backups-script.conf` file! @@ -103,9 +171,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 @@ -129,15 +204,31 @@ 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. +- *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. @@ -151,22 +242,23 @@ 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 +The following job configurations variables used by the outdated 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 +- 0: No error, success. - 1: Unspecific Error! - 2: Usage information has been shown. -- 3: Can't read system definition +- 3: Can't read job definition - 4: PID-file exists! - 5: Pre-exec command failed! -- 6: There have been systems with errors! +- 6: There have been jobs with errors! - 7: Not all jobs were run! - 9: Aborted (CTRL-C)!