diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/byteback-backup.txt | 69 | ||||
| -rw-r--r-- | man/byteback-prune.txt | 47 | ||||
| -rw-r--r-- | man/byteback-restore.txt | 174 |
3 files changed, 290 insertions, 0 deletions
diff --git a/man/byteback-backup.txt b/man/byteback-backup.txt new file mode 100644 index 0000000..15c448f --- /dev/null +++ b/man/byteback-backup.txt @@ -0,0 +1,69 @@ +NAME + + byteback-backup - Back up this system to a byteback-enabled server + +OPTIONS + + --destination, -d <s> Backup destination (i.e. user@host:/path). + --source, -s <s+> Source paths (default: /) + --exclude, -x <s+> Paths to exclude + --retry-number, -r <i>: Number of retries on error (default: 3) + --io-timeout, -i <i>: Number of seconds to allow I/O timeout for (default: 10800) + --retry-delay, -e <i>: Number of seconds between retries after an error (default: 300) + --ssh-key, -k <s> SSH key filename (default: /etc/byteback/key) + --verbose, -v Show debugging messages + --help, -h Show this message + +Additional excludes can be specified using /etc/byteback/rsync_filter, which is +an rsync filter file. See the rsync man page for information on how this +works. + +DESCRIPTION + +You can set "byteback-backup" on a daily cron job to start backing up +the server on a regular basis. + +Without any further options this will copy every file from the root +downwards. + +It currently excludes /tmp, /var/tmp, /var/cache/apt/archives, +/swap.file and /var/backups/localhost which (on Bytemark systems) do +not need to be part of any backup. To specify which locations are +excluded, add them to /etc/byteback/excludes, one per line. The +filesystems /dev, /proc, /run and /sys are always excluded. + +It is possible to configure a full rsync filter by creating the file +/etc/byteback/rsync_filter, which is parsed to rsync via the --filter +flag. Note that excludes on the command line take precedence, unless +the filter starts with an exclamation mark, which resets everything. +If you do this, you'll need to specify /proc, /sys, etc manually. See +the rsync manpage for more information about filters. + +It is also possible to add extra rsync flags to the configuration. +The following flags are always set: + + --archive --numeric-ids --delete-excluded --delete-during --inplace --relative + +If you wish to add to that (e.g. --xattrs --acl --hard-links) then +simply add them to /etc/byteback/rsync_flags. These extra flags get +appended after the default flags above, so they take precedence. + +When the backup has completed successfully, the server will take a +snapshot so that the client can't alter the backups, and then "prune" +the backup snapshots to ensure that the next backup is likely to run +OK. + +If the backup is interrupted or dies unexpected, running +"byteback-backup" will cause the backup to be resumed, with rsync +saving the work of re-copying any files that hadn't changed. By +default this will happen automatically up to 5 times, with a 10 minute +pause in between each attempt. + +SEE ALSO + + byteback-restore(1), byteback-prune(1) + +AUTHOR + + Patrick J Cherry <patrick@bytemark.co.uk> + diff --git a/man/byteback-prune.txt b/man/byteback-prune.txt new file mode 100644 index 0000000..f8074e2 --- /dev/null +++ b/man/byteback-prune.txt @@ -0,0 +1,47 @@ +NAME + + byteback-prune - Prune old byteback backup directories to ensure there's enough space + +OPTIONS + + --minpercent, -m <i> Start prune when disk has less than this %age free (default: 5) + --maxpercent, -a <i> Stop prune when disk has more than this %age free (default: 10) + --list, -l List backups in pruning order, no other action + --prune, -p Prune the next backup if necessary + --prune-force, -r Prune the next backup regardless + --order, -o <s> Order backups by 'age' or 'importance' (default: importance) + --verbose, -v Show debugging messages + --help, -h Show this message + +DESCRIPTION + +Unless you are backing up a very small amount of data, backups will +always need pruning, i.e. old backups must be deleted to make way for +newer ones. + +This program deals with this operation by deleting old backups until a +certain amount of free space is achieved, which is currently fixed at +10% free. This can be changed by setting the --maxpercent option. + + * midday today; + * midday on the previous 6 days; + * midday on the previous 4 Sundays; + * midday on every fourth Sunday before that, where the "fourth + Sunday" is calculated as every fourth Sunday in the Unix epoch, + i.e. every fourth Sunday since Sunday 4th Jan 1970. + +So when you ask the pruner to run, the backup closest to the present +time will be the last one to be deleted. The backup closes to "1 day +ago" will be the second-last, and so on. We score every backup in +this way until we end up with a "least important" snapshot to delete. + +The pruner will not delete backups younger than 7 days. + +SEE ALSO + + byteback-backup(1), byteback-restore(1), byteback-receive(1) + +AUTHOR + + Patrick J Cherry <patrick@bytemark.co.uk> + diff --git a/man/byteback-restore.txt b/man/byteback-restore.txt new file mode 100644 index 0000000..d4ff01e --- /dev/null +++ b/man/byteback-restore.txt @@ -0,0 +1,174 @@ +NAME + +byteback-restore - Restore a file to this system from a byteback-enabled server + +SYNOPSIS + +byteback-restore [ --restore | --list ] [ --snapshot s ] + [ --destination d ] [ --io-timeout i ] [ --ssh-key k ] + [ --list-all ] [ --help ] [ --verbose ] pattern pattern.. + +OPTIONS + + --list, -l List or find files + --restore, -r Restore files + --snapshot, -s s The snaphot to use. (Default: *) + --destination, -d s Backup destination (i.e. user@host:/path). The default is read from /etc/bytebackde + --io-timeout, -i i Number of seconds to allow I/O timeout for (default: 300) + --ssh-key, -k s SSH key filename (default: /etc/byteback/key) + --all, -a List/restore all versrions of each file + --verbose, -v Show debugging messages. + --help, -h Show a brief usage message. + +DESCRIPTION + +Firstly the pattern argument. This is expanded relative to the current directory, +if it is not an absolute path, before being globbed. It is best to quote the +pattern to avoid premature shell expansion. Multiple patterns can be supplied. + +To list files that could be restored, just give a pattern. The --list flag can +be used for clairty, but it is entirely optional. + +To restore files, use the --restore flag. Restores are always done into the +current working directory. See EXAMPLES below. + +GLOBBING + +The following character are "globbed": + + - "*" matches any filename. + - "**" matches directories recursively. + - "?" matches any single character. + - "[set]" matches any set of characters, working in the same way as regular expressions. + - "{a,b}" matches either literal "a" or literal "b" + - "\\" escapes the next metacharacter. + +Note that to match "dotfiles", the pattern "{*,.*}" should be used. + +The full glob syntax is documented in the Ruby documentation for the Dir#glob +method. + +EXAMPLES + +To list the latest copies of the files available, just call the command with +no flags.. The --list flag is optional. + + # byteback-restore '/home/patch/.bash*' + snapshot modestring size uid gid mtime path + ---------------------------------------------------------------------------------------- + current -rw------- 47931 1000 1000 2015-11-29 09:26:10 +0000 /home/patch/.bash_history + current -rw-r--r-- 220 1000 1000 2014-03-10 10:13:33 +0000 /home/patch/.bash_logout + current -rw-r--r-- 3638 1000 1000 2015-07-30 16:33:30 +0100 /home/patch/.bashrc + +To list all different available versions of a file, use --all. + + # byteback-restore --all '/home/patch/.bashrc' + snapshot modestring size uid gid mtime path + ---------------------------------------------------------------------------------------------- + 2015-07-17T15:11+0100 -rw-r--r-- 3637 1000 1000 2014-03-10 10:13:33 +0000 /home/patch/.bashrc + current -rw-r--r-- 3638 1000 1000 2015-07-30 16:33:30 +0100 /home/patch/.bashrc + +To list every single copy of a file, use --verbose. Notice that a number of +these entries match on size and mtime. + + # byteback-restore --verbose '/home/patch/.bashrc' + ssh -o BatchMode=yes -o ConnectionAttempts=5 -o ConnectTimeout=30 -o ServerAliveInterval=60 -o TCPKeepAlive=yes -x -a -i /etc/byteback/key -l byteback backups.default.cherry.uk0.bigv.io byteback-receive --snapshot * --list --verbose /home/patch/.bashrc + snapshot modestring size uid gid mtime path + ---------------------------------------------------------------------------------------------- + 2015-04-30T11:44+0100 -rw-r--r-- 3637 1000 1000 2014-03-10 10:13:33 +0000 /home/patch/.bashrc + 2015-05-05T15:05+0100 -rw-r--r-- 3637 1000 1000 2014-03-10 10:13:33 +0000 /home/patch/.bashrc + 2015-07-17T15:11+0100 -rw-r--r-- 3637 1000 1000 2014-03-10 10:13:33 +0000 /home/patch/.bashrc + 2015-11-25T11:14+0000 -rw-r--r-- 3638 1000 1000 2015-07-30 16:33:30 +0100 /home/patch/.bashrc + 2015-11-26T13:38+0000 -rw-r--r-- 3638 1000 1000 2015-07-30 16:33:30 +0100 /home/patch/.bashrc + 2015-11-27T10:48+0000 -rw-r--r-- 3638 1000 1000 2015-07-30 16:33:30 +0100 /home/patch/.bashrc + 2015-11-30T15:37+0000 -rw-r--r-- 3638 1000 1000 2015-07-30 16:33:30 +0100 /home/patch/.bashrc + current -rw-r--r-- 3638 1000 1000 2015-07-30 16:33:30 +0100 /home/patch/.bashrc + +Restoring is always to the current directory, and into directories named after the snapshots. +This next command restores the last copies of the files shown in the first +listing above into the "current" directory, as they were all from the "current" +snapshot. + + # byteback-restore --restore '/home/patch/.bash*' + Restoring: + snapshot modestring size uid gid mtime path + ---------------------------------------------------------------------------------------- + current -rw------- 47931 1000 1000 2015-11-29 09:26:10 +0000 /home/patch/.bash_history + current -rw-r--r-- 220 1000 1000 2014-03-10 10:13:33 +0000 /home/patch/.bash_logout + current -rw-r--r-- 3638 1000 1000 2015-07-30 16:33:30 +0100 /home/patch/.bashrc + +Using find(1), we can see the files restored. Note that the permissions on the +parent directory have been set correctly. + + # find current/ -ls + 422049 4 drwxr-xr-x 3 root root 4096 Nov 16 16:04 current/ + 422050 4 drwxr-xr-x 3 root root 4096 Mar 12 2014 current/home + 422885 4 drwxr-xr-x 2 patch patch 4096 Nov 29 09:26 current/home/patch + 422886 4 -rw-r--r-- 1 patch patch 220 Mar 10 2014 current/home/patch/.bash_logout + 422887 4 -rw-r--r-- 1 patch patch 3638 Jul 30 16:33 current/home/patch/.bashrc + +To restore the files from a specific snapshot, use the --snapshot flag. + + # byteback-restore --restore --snapshot '2015-07-17T15:11+0100' '/home/patch/.bash*' + Restoring: + snapshot modestring size uid gid mtime path + ----------------------------------------------------------------------------------------------------- + 2015-07-17T15:11+0100 -rw------- 38504 1000 1000 2015-07-17 13:42:17 +0100 /home/patch/.bash_history + 2015-07-17T15:11+0100 -rw-r--r-- 220 1000 1000 2014-03-10 10:13:33 +0000 /home/patch/.bash_logout + 2015-07-17T15:11+0100 -rw-r--r-- 3637 1000 1000 2014-03-10 10:13:33 +0000 /home/patch/.bashrc + +These have been restored into the 2015-07-17T15:11+0100 directory. + + # find 2015-07-17T15:11+0100 -type f -ls + 422911 4 -rw-r--r-- 1 patch patch 220 Mar 10 2014 2015-07-17T15:11+0100/home/patch/.bash_logout + 422913 40 -rw------- 1 patch patch 38504 Jul 17 13:42 2015-07-17T15:11+0100/home/patch/.bash_history + 422912 4 -rw-r--r-- 1 patch patch 3637 Mar 10 2014 2015-07-17T15:11+0100/home/patch/.bashrc + +Finally, to restore all available copies of the files, use the --all flag. +This will restore all copies shown when --list is used with the --all flag. + + # byteback-restore --restore --all '/home/patch/.bashrc' + Restoring: + snapshot modestring size uid gid mtime path + ----------------------------------------------------------------------------------------------------- + 2015-07-17T15:11+0100 -rw-r--r-- 3637 1000 1000 2014-03-10 10:13:33 +0000 /home/patch/.bashrc + current -rw-r--r-- 3638 1000 1000 2015-07-30 16:33:30 +0100 /home/patch/.bashrc + +We now have two versions of the same file, in different restore directories. + + # find -type f -ls + 946020 4 -rw-r--r-- 1 patch patch 3637 Mar 10 2014 ./2015-07-17T15:11+0100/home/patch/.bashrc + 422893 4 -rw-r--r-- 1 patch patch 3638 Jul 30 16:33 ./current/home/patch/.bashrc + +CAVEATS + +If a pattern given matches a directory, then the whole directory will be +restored recursively, not just the directory itself. This can be shown by +adding the --verbose flag. + + # byteback-restore --verbose --restore '/home/patch' + rsync --archive --numeric-ids --inplace --relative --compress --timeout 300 --rsh ssh -o BatchMode=yes -x -a -i /etc/byteback/key -l byteback --verbose --rsync-path byteback-restore --fake-super --snapshot * byteback@backups.default.cherry.uk0.bigv.io:/home/patch . + Restoring: + snapshot modestring size uid gid mtime path + ------------------------------------------------------------------------- + current drwxr-xr-x 5152 1000 1000 2015-11-29 09:26:22 +0000 /home/patch + rsync --fake-super --server --sender -vlogDtprRze.iLsfx --timeout=300 --numeric-ids --inplace --exclude=. . ./current/home/patch + receiving incremental file list + current/home/patch/ + current/home/patch/.mrconfig + current/home/patch/.pam_environment + current/home/patch/.plan + current/home/patch/.profile + current/home/patch/.psql_history + etc... + + +SEE ALSO + +byteback-receive(1), byteback-prune(1), http://ruby-doc.org/core/Dir.html#method-c-glob + +AUTHOR + +Patrick J Cherry <patrick@bytemark.co.uk> + + |