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 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
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 ]
The argument args is a extension to be ignored. For example, to exclude all compiled object files in a directory use
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.
An external function is used to decide which files will be excluded. The synopsis is
exclude function fct@library arg
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 ]
As already mentioned, only regular files are saved. The following command specifies the handling of subdirectories.
directory option [ args ]
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.
This option is similar to list, but it aplies recursively to subdirectories of the named directories.
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.
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 ].
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 ]
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 ]
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 ]
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 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.
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.
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.
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
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 ...
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
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
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.
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:
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.
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.
Path is a directory used to build a temporary directory tree, which is going to be written to a CD.
Path is a directory used to create an ISO image for use by cdrecord(1).
The argument device is the device file of your DVD RAM drive. For example, 'dvd /dev/sr1'.
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.
Use file as our logfile. The argument file must be an absolute path.
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.
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.
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).