backup2disk

SYNOPSIS

backup2disk

[

--archivedir=DIR

] [

--backupdatadir=DIR

] [

--crossfilesystems=[yes|no

]

] [

--dereferencelinks=[yes|no

]

] [

--disablecompression=[yes|no

]

] [

--disableverify=[yes|no

]

] [

--excludefile=FILE

] [

--level=[0-2

]

] [

--mount=COMMAND

] [

--notification=[none|summary|list|verboselist

]

] [

--sendto=EMAIL

] [

sourcedir=DIR

] [ umount=COMMAND ]

DESCRIPTION

This manual page documents the backup2disk script, a tar-based archive utility that creates file archives on disk. The archive process is driven by a configuration file backup2disk.conf. Each configuration option may be overridden at runtime by specifying the command-line argument of the same name. Status information is recorded via logger; optionally, backup2disk sends an email notification when the backup is complete.

OPTIONS

--archivedir=DIR

Indicates where the archive will be stored. The directory must exist and be writable by the current user. The installation default is "/tmp".

--backupdatadir=DIR

Indicates where backup2disk will find timestamp files and exclude files. The directory must exist and be writable by the current user. The installation default is "$BACKUP2DISKHOME/data".

--crossfilesystems=[yes|no]

Indicates whether the backup should cross file systems. The value no is equivalent to tar --one-file-system. The installation default is "no".

--dereferencelinks=[yes|no]

Indicates whether symbolic links should be dereferenced. The value yes is equivalent to tar --dereference. The installation default is "no".

--disablecompression=[yes|no]

Indicates whether the archive should be compressed. The value no is equivalent to tar --gzip. The installation default is "no".

--disableverify=[yes|no]

Indicates whether the archive will be verified (read) after it is complete. The value no is equivalent to tar --list. The installation default is "no".

--excludefile=[none|default|FILE]

Indicates where backup2disk can obtain a list of directories and files to be excluded. The value none instructs backup2disk to include all files. The value default instructs backup2disk to use a default exclusion file in ${BACKUP2DISKHOME}/data. Specifying the name of a file is equivalent to tar --exclude-from. The installation default is "none".

--level=[0-2]

Indicates the type of archive. The value 0 indicates a full (time-insensitive) backup. The value 1 indicates an incremental backup including all files created or modified since the last level 0 backup. The value 2 indicates an incremental backup including all files created or modified since the last level 1 backup. The installation default is "0".

--mount=COMMAND

Specifies the command used to mount a remote device before the backup starts. There is no installation default.

--notification=[none|summary|list|verboselist]

Indicates the type of notification to be sent via email when the backup is complete. The value none indicates that no notification is to be sent. The value summary indicates that a summary notification (no file list) will be sent. The value list indicates that the notification should include a list of archived files (equivalent to tar --list). The value verboselist indicates that the notification should include a verbose list of archived files (equivalent to tar --list --verbose). The installation default is "verboselist".

--sendto=EMAIL

Indicates the email address to which backup2disk will send an email notification when the backup is complete. The installation default is "root@host" where host is the name of the current host.

--sourcedir=DIR

Indicates the directory to be archived. The directory must exist and be writable by the current user. The installation default is "/".

--umount=COMMAND

Specifies the command used to unmount a remote device after the backup is complete. There is no installation default.

ENVIRONMENT

backup2disk uses a single optional environment variable BACKUP2DISKHOME. When set, the value is used to determine where backup2disk will locate its configuration file and the default location of the data directory. When not set, BACKUP2DISKHOME is set equivalent to `dirname $0`.

CONFIGURATION FILE

By default, backup2disk looks for backup2disk.conf in its current directory (see ENVIRONMENT). backup2disk.conf contains one line for each command line option specifed in the format opt=value. When backup2disk starts, the configuration file is loaded to initialize the default backup environment. The value for each option is then overridden by the values specified on the command line. For more information, see the comments in backup2disk.conf. To force a given option to be specified on the command line, remove it from the configuration file. Since all options must have values, this will cause backup2disk to display a help message that lists the configured value as "missing".

OPERATION

Archive file names:

Since backup2disk generates tar archives on disk, it must take some necessary precautions to avoid overwriting a previous backup with a new one. To accomplish this, backup2disk mimics the directory structure of sourcedir under archivedir, and uses file names that are based on the number of seconds since January 1, 1970. For example, if the user executes the following command at noon on January 3, 2003:

backup2disk --archivedir=/tmp --sourcedir=/home/public/john --disablecompression=no

backup2disk will create an archive named 1041613200.tgz in /tmp/home/public/john.

Level 0, level 1 and level 2 backups:

backup2disk supports three levels of backups. A level 0 backup includes all files in sourcedir that have not been excluded via an entry in excludefile. A level 1 backup includes all files created or modified since the most recent level 0 backup for the same sourcedir. A level 2 backup includes all files created or modified since the most recent level 1 backup for the same sourcedir. To support this feature, backup2disk maintains source-dependent timestamps in backupdatadir. For example, assume backup commands were issued as follows:

At noon on January 1, 2003:    backup2disk --level=0 --sourcedir=/home/public/john
At noon on January 2, 2003:    backup2disk --level=1 --sourcedir=/home/public/john
At noon on January 3, 2003:    backup2disk --level=2 --sourcedir=/home/public/john

When the first backup completes, backup2disk creates a file named level0-~home~public~john-datestamp in backupdatadir that contains "Wed Jan 1 12:00:00 EST 2003". When the second backup starts, it reads level0-~home~public~john-datestamp and adds "--after-date 'Wed Jan 1 12:00:00 EST 2003'" to the arguments for the tar command; when the second backup completes, it creates a file named level1-~home~public~john-datestamp in backupdatadir that contains "Thu Jan 2 12:00:00 EST 2003". When the third backup starts, it reads level1-~home~public~john-datestamp and adds "--after-date 'Thu Jan 2 12:00:00 EST 2003'" to the arguments for the tar command.

For level 1 and level 2 backups, the timestamp file must exist. They will usually be created and maintained by normal backup procedures. However, they may be created manually using the date command. For example, assume you already have a full backup of /home/public/john performed at noon on January 1, 2003 and want to start using backup2disk to do level 1 backups. The following command will seed the level 0 timestamp:

date --date "2003-01-01 12:00:00" >/var/local/backup/data/level0-~home~public~john-datestamp

For more information, see the --after-date option for the tar commnad.

Exclusion filters:

Files and directories are excluded from a backup by listing them one per line in an exclusion file and specifying the name of the file as the argument to the --excludefile option. If an exclusion file is specified, backup2disk adds the name of the exclusion file as the argument for tar's --exclude-from option. If excludefile is "none", backup2disk will not include the --exclude-from option. If excludefile is "default", backup2disk will look for exclude-default in backupdatadir. If the exclusion file is not found or is not readable, backup2disk will exit with an error. For more information, see the --exclude-from option for the tar command.

KNOWN ISSUES

Backup levels and exclusion filters operate independently. A level 1 or level 2 backup always operates based on the timestamp of the previous backup whereas exclusion filters operate based on the contents of the exclusion file at the time the backup occurs. If files or directories are removed from the exclusion file immediately prior to a level 1 or level 2 backup, they will be included in the backup only if they were created or modified since the preceeding level 0 or level 1 backup. backup2dir does not evaluate the contents of existing archives to determine whether a file or directory should be added.

Immediately after installation, backup2disk's archives and data are stored in different directories. If the archive or data location is changed after backup2disk has been in operation for some period of time, the archives in archivedir may not be reflective of the timestamp and exclusion filters in backupdatadir.

backup2disk does not change the working directory; it is suggested however that sourcedir be specified as a fully-qualified path. The behavior for relative paths is undetermined.

If verification is enabled, a complete list of archived files will be printed twice to the console -- once during the backup and again during the verification; if backup2disk is invoked by cron, the console output will be mailed to root. If notification is set to list or verboselist, a complete list of archived files will be mailed via notifycommand to sendto; if sendto is root, this may result in root receiving duplicate lists for the same archive. Notifications for entire file system backups can result in large emails depending on the number of files included in the backup. There is currently no mechanism to verify that the email was actually delivered, received or read.