backup-script: Correctly detect empty system directories on Btrfs

[backup-script.git] / README.md

diff --git a/README.md b/README.md
index db48806cbbfc2979a5882c97b1253b5f2043f7e0..c24a330a6131118af51c860b233b694c33394a1c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,73 +1,94 @@
 # Backup Script
 
 # Backup Script
 

-A script for cloning systems using rsync.  
-Copyright (c)2008-2016 Alexander Barton <alex@barton.de>
+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-2022 Alexander Barton (<alex@barton.de>)  
+Homepage: <https://github.com/alexbarton/backup-script>
+
+## 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
 
 
 ## Usage
 
 ### backup-script
 

-Backup all or individual systems.
+Run all or individual backup jobs.

 
 

-Usage: `backup-script [<options>] [<system> [<system> [...]]]`
+Usage: `backup-script [<options>] [<job> [<job> [...]]]`

 
 Options:
 
 - `-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).
 
 Options:
 
 - `-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-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 [<backup-script-options-and-systems ...>]`
+Usage: `backup-script-wrapper [<backup-script-options-and-job-names ...>]`

 
 ### backup-status
 
 Show information about backups.
 
 
 ### backup-status
 
 Show information about backups.
 

-Usage: `backup-status [-q] [<system> [<system> [...]]]`
+Usage:
+
+- `backup-status [--errors|--latest] [--quick] [<job> [<job> [...]]]`
+- `backup-status --running`

 
 Options:
 
 
 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.
 
 
 ### backup-audit
 
 Show "relevant" differences in system configuration between backup generations.
 

-Usage: `backup-audit [-q] [-v] [<system> [<system> [...]]]`
+Usage: `backup-audit [-q] [-v] [<job> [<job> [...]]]`

 
 Options:
 
 
 Options:
 

-- `-q`: *quiet mode*, don't show systems without "relevant" changes.
-- `-v`: *verbose mode*, show all checks that are run.
+- `-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
 
 All default configuration variables are read from the first file found of this
 
 ## Configuration
 
 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
+list: `/usr/local/etc/backup-script.conf`, `/etc/backup-script.conf` or

 from `/etc/backup-script.d/backup-script.conf` (deprecated).
 
 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.
 
 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
 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:
 
 
 For example:
 


@@ -75,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
 
 - `/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
 
 
 ## Configuration Variables
 


@@ -99,7 +131,7 @@ Backup type to use. Default: `rsync`.
 
 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
 
 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
+"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).
 
 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).
 


@@ -121,8 +153,8 @@ Default: "running-config".
 
 ### [default_]target
 
 
 ### [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!
 
 *Note:* There is *no* default, you have to specify this variable, for example as
 `default_target` in the `backups-script.conf` file!


@@ -172,11 +204,11 @@ inside of the target directory.
 
 Supported file systems are:
 
 
 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.
 
 The latest snapshot is always reachable using a symlink named `latest`
 inside the system directory.


@@ -210,22 +242,23 @@ Optional script to execute after `rsync` exited. Default: none.
 
 ### Compatibility Variables
 
 
 ### 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
 
 
 ## Exit codes
 

+- 0: No error, success.

 - 1: Unspecific Error!
 - 2: Usage information has been shown.
 - 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!
 - 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)!
 - 7: Not all jobs were run!
 - 9: Aborted (CTRL-C)!