This section describes the RAB user interface. At the moment, RAB is completely controlled by a simple command line program, called rab. The genaral synopsis is
rab [ options ] action [ arguments ] |
This short section lists all options which apply to each of the possible actions.
Verbose execution.
Debugging mode. Don't write any files and set the logging level to the highest possible value. Usually, this is used in conjunction with the -v option.
Use the file file as our global configuration file instead of the default /etc/rab.conf. This is only useful for debugging, and it is not intended as a normally used option.
Write message to the RAB logfile. If logging is disabled in /etc/rab.conf, then this option will be ignored.
Set the logging level to the argument n.
The action -V writes the RAB version number to standard output. If used with -v, the compile time defaults will be listed.
RAB expects to find a specific directory structure in it's data directory. When using the default data directory /var/lib/rab, this structure was already created when installing RAB. As already discussed, you may use the vardir variable in the global configuration file to change the data directory used.
The command rab -init will create the required directory structure. The data directory to be used is specified as arguments. If no argument was specified, rab tries to find a vardir variable in the global configuration file, and will use this value. When even this fails, the default /var/lib/rab will be used.
For each non existing configuration file, rab will create an almost empty dummy file.
This command expects exactly one argument, either on or off. In any case, rab will act as if the global configuration file contained a corresponding 'import on' or 'import off' configuration line, respectively. Then, rab will rewrite it's internal data files to reflect the new directory tree structure. This only makes sense immediately after editing /var/lib/rab/Directories.
The action -backup is used to actually create a backup. This means a first level backup, i.e. backup to a DVD RAM, or another removable medium. Eventually, RAB decides to make an additional checkpoint. The backup is interactive, i.e. rab will prompt you to insert the backup media. RAB is not intended to be used for an automated, unattended backup, so there is no way to circumvent prompting. Anyways, you usually just insert the medium requested and press 'y'. Alternatively, you may cancel the running backup by pressing 'c'. The key 'h' will print a short help message explaining each of the possible choices.
The arguments to rab -backup are zero, one or more directory names. Each of these directories must have an entry in the /var/lib/rab/Directories file. Rab will make a backup of all listed directories. The following options are recognized.
In addition to the directories listed on the command line, read a list of directories to be backed up from the file file. Each non empty line in file, which doesn't begin with a '#', is expected to be the absolute path of a directory. Of course, these directories must be described in /var/lib/rab/Directories. Rab recognizes if a directory is duplicated, and makes only one backup of the directory.
Make a backup of all directories listed in /var/lib/rab/Directories. All -F options and all command arguments will be ignored.
Print information about new, changed or removed files to the standard output.
Display progress messages while copying files to the backup medium.
Force a backup even if there wasn't any change in the directory.
Use the specified medium as backup medium.
Don't make a checkpoint.
Add the named directory to a RAB checkpoint CD if there is enough space left on the CD. There may be more than one -i option on the rab command line. There is no guarantee that the directory will actually be written to a CD. Rab will display status information about all directories specified with -i options before it exits.
Do not try to put additional directory trees found in /var/lib/rab/Directories on a RAB checkpoint CD. This option may be used to favor directories specified with an -i option.
Immediately before creating an ISO 9660 image file, provide the user running rab with a shell escape. Using this shell, he may modify the CD going to be created any way he likes. However, RAB will trust you not to remove or modify any backup data, it's your backup after all. When the shell terminates, rab will continue it's normal operation.
Ignore all interval configuration commands in either the /var/lib/rab/Directories file or in the global configuration file, respectively.
Check only mode. Calculate only the list of files and directories to be backed up, and write the result to standard output. In verbose mode, additional info will be printed.
To create a checkpoint, the action -checkpoint is used. Exactly like the -backup option, we expect a list of directories as argument, and we will create a checkpoint for these directories. If there are already enough checkpoints for a given directory, this directory will be omitted. What number of checkpoints constitutes 'enough' is configurable, as described above. It is possible that RAB selects some additional directories for a checkpoint.
If everything works as expected, rab will prompt you to insert one or more CD-R's, you press 'y', and the checkpoint will be written. Unfortunately, sometimes cdrecord(1) fails to write a CD. If this happens, rab displays an error message and asks you what should be done. The most simple thing to do, is to insert another blank CDR and to try again by pressing 'y'. However, sometimes you may like to investigate the failure in more detail. First, by pressing 'i', rab will show you the output written by cdrecord(1) while burning the CD. Then, you press 'm' to get a shell. The exact shell to be run is configurable using an environment variable, as described below. Rab will show you the ISO9660 image file to be written, and you may try to burn this image file manually. If this succeeds, terminate the shell to return to rab, and press 'd'. If the occured failure is due to a systematic error, you should think about modifying the cdrecord.sh script.
The following options are recognized.
This is like the -F option to -backup. We will read a list of directories from the file file. The file is expected to be in the format described above.
Make a checkpoint of all files listed in /var/lib/rab/Directories.
Print information about new, changed or removed files to the standard output.
Display progress while copying files to the CD build directory.
Create the checkpoint, even if there are already enough copies on CD.
Add the named directory to a RAB checkpoint CD if there is enough space left on the CD. There may be more than one -i option on the rab command line. There is no guarantee that the directory will actually be written to a CD. Rab will display status information about all directories specified with -i options before it exits.
Do not try to put additional directory trees found in /var/lib/rab/Directories on a RAB checkpoint CD. This option may be used to favor directories specified with an -i option.
Immediately before creating an ISO 9660 image file, provide the user running rab with a shell escape. Using this shell, he may modify the CD going to be created any way he likes. However, RAB will trust you not to remove or modify any backup data, it's your backup after all. When the shell terminates, rab will continue it's normal operation.
Ignore all interval configuration commands in either the /var/lib/rab/Directories file or in the global configuration file, respectively.
Check only mode. Only compute the list of directories for a checkpoint, and the number of CD's needed.
The action -config only checks the various RAB configuration files. We will print diagnostics to the standard output.
RAB does not provide any special functionality to restore files or directories from backup. There isn't any need for such stuff since all backup files are on normal block devices which can simply be mounted. This is the advantage of random access media, and RAB means Random Access Backup.
But there is one small problem, you have to know which medium contains the most recent copy of a given file or directory. Moreover, in the case of an archive directory, the backup may be spread over various directories. The action -locate is used to locate our backup copies.
The argument to rab -locate is a list of files we are looking for. Rab prints all information necessary to recover the data in question. We accept only one special option, namely
Show all backups RAB knows about.
The command rab -recover dir is used to recreate our configuration and internal data files after a crash. The argument dir is the mountpoint of the most recent backup medium. The medium should be already mounted at this directory. We will read a copy of the configuration data and write the files to their correct locations. When rab -recover is complete, you may use rab -locate to recover the user data.
Since a real filesystem failure is a rare event, we will not provide a more advanced recovering schema. In particular, RAB is not intended to recreate the base operating system, you should have this on a CD or DVD, anyway.
The rab program understands the following environment variables.
Full path of a shell to be used for shell escapes.
Full path of a shell to be used for shell escapes if RAB_SHELL is not set.
Pager command used to display longer text files. The value of RAB_PAGER shall be either an absolute path or the name of a program accessable by the current PATH environment variable.
Pager command used if RAB_PAGER is not set.
Directory to create temporary files in.
It is not required that any of these environment variables is set. Rab will use a compile time default if some environment variable is not set or contains an unusable value.