NAME

vacuum.pl - Suck backup files across the network.


SYNOPSIS

    vacuum.pl [--test] [--verbose] [--usage|-?] [--help]
              [--from=<source-dir>] [--to=<dest-dir>]
              [--mode=(mv|cp)] [--prefix=<tag> ... ]
              [--since=<date-string>] [--min-free-left=<size>]


DESCRIPTION

This script selectively copies backup dumps over the network via ssh (though it can also be used to copy them locally). It only sees backup dump and tar files that follow the naming convention used by the backup.pl script, as described below. Furthermore, it only copies or moves those files that are both (a) still current and (b) do not already exist at the destination. A dump file is current if there is no more recent dump file with the same prefix at the same or lower dump level. If no such files exist, vacuum.pl exits without error, and without printing any messages.

When files are copied across the network (as opposed to being moved locally), vacuum.pl always does an md5sum on them to verify the copy, and the original is not deleted (if --mode=mv) unless the checksums match.

Each dump file name looks something like home-20021021-l9.dump or home-20051102-l0a.dump, or home-20051102-l0.1.dar for DAR, and consists of the following five components:

  1. A prefix tag (e.g. home), which is normally the last component of the directory where the partition is mounted. The tag is arbitrary and may consist of multiple words, as in usr-local; its purpose is solely to group all of the backups make for a given partition.

  2. The date the backup was made in "YYYYMMDD" format, e.g. '20021021'. We assume that if more than one backup is made per partition per day, the subsequent backups have increasing levels. Under no circumstances do we trust the file modification timestamp.

  3. The dump level, a digit from 0 to 9, with a lowercase "L" prefix, as in l9.

  4. An optional volume suffix. DAR creates these automatically, by appending .#.dar to the stem, where "#" is a number starting from one; all DAR backups always have an explicit volume suffix.

    If a dump backup requires two or more volumes, then alphabetic volume designators are assigned from 'a', as in home-20051102-l0a.dump, home-20051102-l0b.dump, home-20051102-l0c.dump, etc. This is only necessary for large backups that are later copied to physical media. [Note that mkisofs imposes a limit of 2147483646 bytes (= 2^31-2) on files burned to DVD-ROM; see the "DVDs created with too large files" thread at http://groups.google.com/group/mailing.comp.cdwrite/browse_thread/thread/423a083cc7ad8ee8/fecd18c0f8507901%23fecd18c0f8507901 for details. -- rgr, 4-Nov-05.]

  5. A file suffix (extension), which can be one of ".dump", ".dar", ".tar", ".tgz", or ".gtar" (for "GNU tar"). Files with other suffixes are assumed to be something other than backup dumps, and are not copied.

The prefix can be used to select a subset of backup files to transfer. Currently, there is no way to change the set of allowed suffixes.

The backup date and backup level that are encoded in the file name are used to decide which files are still current. We use the 'official' backup date in the names rather than the file date because the latter may get changed as an artifact of copying. See show-backups.pl, which can be used to show which backups are current.

vacuum.pl checks the free space on the destination end, and will refuse to copy in any of the following situations:

  1. If vacuum.pl can't run ls on either machine to establish the list of files that need to be transferred.

  2. If vacuum.pl can't run df to determine the current free space on the destination machine

  3. If the destination would not have at least 1GB of free space left over after copying all current files. The amount of required leftover space can be changed via the --min-free-left option.

  4. If the destination directory is NFS-mounted on the destination machine. In this case, you should vacuum directly onto the exporting machine.

For all of the above situations, vacuum.pl prints an error message and exits with a non-zero return code (courtesy of die).


OPTIONS

--test

If specified, no commands will be executed. Instead, the commands will just be echoed to STDERR.

--verbose

If specified, extra information messages are printed before and during the copy.

--usage

Prints a brief usage message.

--help

Prints a more detailed help message.

--from

Specified the source directory for the copy; required argument. May be specified positionally. Either --from or --to may be on a remote host, using ssh syntax, e.g. "user@host:/path/to/dir/", but not both.

--to

Specifies the destination directory for the copy; required argument. May also be specified positionally.

--mode

This can be either --mode=cp to specify 'copy' mode (the default), in which case the original file is always left in place, or --mode=mv to specify 'move' mode, in which case the source file is deleted after a successful copy.

--prefix

Specifies the dump file prefix tag; may be used to select a subset of files to transfer. May be specified more than once. Unfortunately, wildcards are not supported.

--since

Specifies a cutoff date of the form '2006' or '200611' or '20061209'. If specified, only dumps that are still current and are dated strictly after this date are copied. This is a good way to get current incrementals without also copying an older full dump.

Note that dump files before the cutoff are still used to determine which files are current. [This may be a misfeature. -- rgr, 12-Dec-06.]

--min-free-left

Specifies the minimum amount of free space to leave on the destination device after all copying is done, in megabytes; the default is 1024 (one gigabyte). If copying all of the requested files would require more than this, then no files will be copied.


USAGE AND EXAMPLES

[need some. -- rgr, 18-Aug-04.]


SEE ALSO

Dump/Restore at SourceForge (http://sourceforge.net/projects/dump/)
dump(8)
tar(1)
backup.pl (http://www.rgrjr.com/linux/backup.pl.html)
vacuum.pl (http://www.rgrjr.com/linux/vacuum.pl.html)
ssh(1)
System backups (http://www.rgrjr.com/linux/backup.html)


VERSION

 $Id$


BUGS

If you find any, please let me know.


COPYRIGHT

 Copyright (C) 2002-2005 by Bob Rogers <rogers@rgrjr.dyndns.org>.
 This script is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.


AUTHOR

Bob Rogers <rogers@rgrjr.dyndns.org>