Random Access Backup
Prev		Next

Configuration

Most of the configuration and all the data files used by RAB are located in the directory /var/lib/rab. We are going to describe the configuration files in this directory. The data files may be savely ignored.

The Directories file

The file Directories contains the description of all the directories to be saved by RAB. Directories is a simple text file. Empty lines and lines beginning with the character '#' are ignored. Basically, the Directories file consists of a series of sections, and each section describes one directory. A new section begins with a line of the form
section directory
where directory is the full path of the directory described by this section. There is no way to mark the end of a section, the section ends if either the end of the Directories file is reached, or a new section begins.

Currently, only the ordinary files in a directory are saved. There is no way to backup symbolic links. It is possible to exclude some files from the backup. This is accomplished by placing an exclude command in the section of the directory. The synopsis is
exclude option [ args ]
Here, option specifies the mechanism to use. You may use more than one exclude command in a section. The possible values for option are given in the following list.

extension

The argument args is a extension to be ignored. For example, to exclude all compiled object files in a directory use

exclude extension .o

list

Here, args is a list of files in the directory, and these files will be excluded. It is not an error if some of the listed files do not exist.

function

An external function is used to decide which files will be excluded. The synopsis is
exclude function fct@library arg
The function fct in the shared library library will be called for each file in the directory. The function fct expects three arguments, the directory in question, the current filename and the argument arg. All of these arguments are treated as strings. The argument arg extends to the end of the line. If the functions returns a value different from zero, the file will be excluded. The interface to the shared libraries used by RAB will be described later.

file

Here the argument args is the name of a file. If a file with this name exists in the directory, it will be read. The lines in the file are expected to be of the form
option [ args ]
Empty lines and lines beginning with the character '#' are ignored. Each of the above lines is treated as if the current section contains a line 'exclude options [args]', but 'exclude function' must not occur. Moreover, nested 'exclude file' commands are not supported.

As already mentioned, only regular files are saved. The following command specifies the handling of subdirectories.
directory option [ args ]
It is possible. to use more than one directory command in a section. The following values of option are possible.

list: Args is a list of subdirectories of the current directory which will be saved. Anything which applies to files in the current directory, aplies to the named subdirectories, too. In particular, if the current section contains a command 'exclude file arg', the subdirectories will be searched for a file named arg. File options of the other commands are handled similarly.
recursive: This option is similar to list, but it aplies recursively to subdirectories of the named directories.
file: This option is similar to the file option of the exclude command. We will read the named file, if such a file exists, and interpret it as a list of directory commands. This additional file must not contain any nested file commands.
full: This is equivalent with 'directory recursive .'.

Sometimes, when using a recursive subdirectory, some directories will be scheduled for backup which are not really meant to be saved. For example, when saving the home directory of some user, you probably would like to exclude subdirectories like .netscape. These things are achieved by a configuration command
excludedir option [ args ].
Possible values for option are exactly like the options to the exclude configuration command, i.e. option is expected to be one of extension, list, function, file. Please, see the description of exclude for each of these option values.

We already mentioned that there are two different types of directories. The normal directory type is called a standard directory, and the other type is an archive directory. These two types differ only in a few aspects. Most important, in an archive directory it is assumed that the files in the directory do not change, or at least not that often. There may be new files or old files are removed but usually nothing else happens. Moreover, standard directories are always completely backed up. Archive directories, on the other hand, are saved incrementally. In fact, you may think of archive directories as 'incremental directories'.

To specify the type of a directory, we use the command
type [ standard | archive ]
Obviously, this specifies whether the directory is a standard directory or an archive.

By default, each directory tree will be considered for backups to removable media and for CD checkpoints. To overwrite this default, use the command
only [ backup | checkpoint | both ]
With either argument backup or checkpoint, RAB will only do backups to a removable medium or to a CD, respectively. The other possible argument, both, just instructs RAB to use the default, i.e. both kinds of backup will be done.

As described in the previous section, you may write some backups using the tar(1) command. To configure a directory tree to use tar(1) put the following configuration command in the section of this directory tree.
tarball [ backup | checkpoint | both | none ]
Of course, then RAB will use tar(1) for backups to removable media, for CD checkpoints, for both of them or for none of them, respectively. The default value is none.

The next few commands are used to control the checkpoint behaviour of the current directory. A checkpoint simply is a CD backup. The central command is
checkpoint option number
Here, the argument option is one of the following.

file: Here number is the minimum number of files changed to force a checkpoint. If number is the special value none, this reason to trigger a checkpoint will be disabled.
days: Number is the maximal number of days between two checkpoints of this directory. Analogously to the file command, you may specify the special value none to disable this feature.
save: We don't write a new checkpoint if there was no change in the directory, and we already have number backups on CD. In particular, if number equals zero, no checkpoint is written unless the directory changed. Again, the special value none disables this feature.
complete: This command applies to archive directories only. You may specify it for a standard directory, but this hasn't any effect. When writing a checkpoint to a CD, each numberth time, we will write a complete copy of the directory in question. In particular, if number is zero no complete copy will be created, unless specifically ordered.

You may also arrange for any directory tree to be considered only once in a given interval of days. The configuration command
interval number
tells RAB to check this directory each number days only. Of course, this is the minimal number of days to wait until the directory will be checked for the next time, i.e. you don't have to run RAB on a specific day.

Overlapping directory trees

Obviously, each directory really should be contained in at most one of the directory trees defined in the /var/lib/rab/Directories file. RAB does not really enforce this constraint, the only thing explicitely forbidden is to have two directory trees rooted at the very same directory. If /var/lib/rab/Directories accidentily contains overlapping directory trees, RAB will still work. Some backup records may be lost in this process, so you really should correct such an error. Every time, RAB detects an overlap, it will write a warning to it's logfile.

It is not necessarily an error if one directory tree starts at some subdirectory of another directory tree, since you may use the excludedir configuration command to exclude this directory. For example, the following /var/lib/rab/Directories fragment is perfectly ok.
# # Homedirectory of user foo # section /home/foo directory full excludedir list special # # Subdirectory of /home/foo to be handled specially # section /home/foo/special ...
When reorganizing the directory structure used in /var/lib/rab/Directories, RAB will automatically move affected backup records to their new location. For example, assume you decide to end the special handling of /home/foo/special. So you remove the excludedir command in the section on /home/foo, and the entire /home/foo/special section. The next time RAB is running, all backup records of files in /home/foo/special will be moved to the remaining directory tree /home/foo. This behaviour may be disabled in the global configuration file.

The Media file

The file /var/lib/rab/Media is used to keep track of our backup media. Each backup medium is described by a unique name. You shouldn't reuse names after disposal of an old medium. A name can be an arbitrary alphanumeric string. It isn't necessary to use intelligent names, '1', '2', and so on qualifies as a name.

The Media file is a simple text file. Empty lines and lines beginning with '#' are ignored. Each of the remaining lines is supposed to describe one of your backup media. The expected format is as follows.
name type options
The very first argument name is the name of the medium. Each medium contains an usual file system and type is the type of this file system. This should be one of the values accepted with the -t option of the mount(8) command. Similarly, options is a valid value for the -o option of mount(8).

If you are planning to use a another hard drive for backups, RAB provides you with two possible options to achieve this. First, you may use a dedicated partition for backups, and insert this file system in the Media file, as above. Unfortunately, you will have to specify the device file corresponding to the partition chosen as dvd in the global configuration file. Moreover, the partition must not be mounted when running rab. Ok, this is a hack and will be fixed in a future version.

The second method uses a directory dir located on a file system already mounted. Then, include the line
name LINK dir
in the Media file. Whenever using the medium name, RAB will use the directory dir instead. In particular, you will not be asked to insert this medium.

You are allowed to add new media to the Media file, or to remove old media from the file. RAB uses an internal list of all known backup media, and recognizes a change in this list. Of course, this doesn't happen immediatetly after removal of the medium from /var/lib/rab/Media, but the next time you run the rab command.

The global configuration file

In the previous section, we listed all of the possible per directory configuration. If one of these isn't specified for a given directory, a global default will be used. Usually, these defaults will be read from the configuration file /etc/rab.conf. This file can contain all of the commands possible in the Directories file. If a value isn't even defined in /etc/rab.conf a compile time default value is used instead.

Empty lines and lines beginning with '#' are ignored. Additionaly, the following commands are recognized:

vardir path

The argument path specifies an absolute path, and this directory will be used instead of the default /var/lib/rab. Path must be an existing directory. Usually, you shouldn't use this command.

libdir path

Path is an absolute directory path, and we will look for shared libraries in this directory. Of course, this doesn't apply to the libraries linked to the RAB programs, but to the libraries used with the exclude function command in the Directories file. If /etc/rab.conf contains more than one of these lines, shared libraries will be searched in all paths specified.

In any case, we will also look in the default directory /usr/local/lib/rab/lib.

builddir path

Path is a directory used to build a temporary directory tree, which is going to be written to a CD.

isodir path

Path is a directory used to create an ISO image for use by cdrecord(1).

dvd device

The argument device is the device file of your DVD RAM drive. For example, 'dvd /dev/sr1'.

cdwriter device

This is the device string as expected by the cdrecord(1) command. You should really specify this value, the default value is almost certainly useless.

logfile file

Use file as our logfile. The argument file must be an absolute path.

loglevel n

The numeric argument n specifies the maximal loglevel which is actually written to the logfile. For example, if n equals '2' then only messages with level one or two are logged. In particular, the argument value '0' completely disables logging. In fact, we will not even create an empty logfile.

delete off

By default, sometimes we will remove old backups from a DVD RAM to make the storage available for new data. Moreover, if a backup already in progress fails for some reason, the data already written will be removed. This is intended to guarantee a clean state in case of an error.

However, you are not required to trust RAB with your old data, and the command 'delete off' will disable all automatic file deletion. By the way, the command 'delete on' is accepted, too, and will enforce the default behaviour. When using this option, you are required to manage the DVD RAM on your own. It is always possible to remove a complete backup directory, RAB will recognize this and adjusts it's data files accordingly.

import off

Don't automatically move old backup records to other directory trees. Usually, this setting isn't that usefull. However, you may use this configuration command to manually control reorganization of /var/lib/rab/Directories when using the -import option to rab(8).