An example

This section describes a complete example of using RAB. This example is not intended to use all features provided by RAB. Everything used in this example will be explained in more detail later in this document.

The situation

The following directories need to be backed up.

  1. The directory /home/foo/programming contains source to various programs. The user always wants a complete backup of these files but the various build object files should not be saved. Moreover, we do not want to save compiled binary programs or libraries.

  2. The directory /home/foo/data contains a set of mostly static data files. Some of these are pretty big, so this directory should be saved incrementally. As a small complication, some of these data files are generated and should not be saved. For each generated file data, there exists a corresponding source file data.src in the same directory.

  3. The directory /home/bar is the home directory of another user. We will need incremental backups of this directory, but excluding all hidden files and all hidden directories.

  4. The /etc directory should be completely saved. But our hypothetical user did not like the idea of a daily backup of /etc, the backup program shall look at /etc only once each 14 days.

  5. The final directory /usr/local/pictures is a collection of pictures to be saved incrementally.

Our hypothetical user is pretty sure that even a complete backup of all these directories will leave some unused space on the CD to be created. By a nice accident, it just happens there are two directories

  1. The directory /usr/local/tarballs contains a set of tarballs downloaded in the last days.

  2. Another directory /home/foo/done contains a completed project, the user would like to have a final archive of.

Both directories are a one time job, normally they should not be selected for backup. Ok, this is somewhat artificial.

We will need a partition with enough space to build a directory tree to be used by mkisofs(8), and to hold the created ISO9660 image file. On our hypothetical system, the directory /scratch may be used for this purpose. The computer is equipped with a DVD RAM device using the device file /dev/sr1. The CD writer has to be described as documented in cdrecord(1), let's assume you should use the option dev=0,0,0 with cdrecord(1). We also assume that the RAB package is already installed. When installing RAB, the directory structure rooted at /var/lib/rab was already created.

Creating /etc/rab.conf

The first thing to do, is to write the global configuration file used by RAB. In the setup given, we may use the following file.

# /etc/rab.conf - Global RAB configuration

# Directories used to build our mkisofs(8) directory tree and
# the ISO9660 image file, respectively.

builddir /scratch
isodir   /scratch

# The DVD RAM device file and the device string expected by
# the cdrecord(1) command.

dvd      /dev/sr1
cdwriter 0,0,0

Creating /var/lib/rab/Media

The next step is to tell RAB about the DVD RAM media used. In this example, we will use two media, called 'ram1' and 'ram2', respectively. We have to equip both media with a filesystem. For simplicity, we are just using an ext2 filesystem. For example, create a filesystem by
# mke2fs -v -m 0 -b 2048 /dev/sr1
but see mke2fs(8) for details. RAB uses a list of all media known in /var/lib/rab/Media, and in this example this file becomes

# /var/lib/rab/Media - Media list file

# Name  type  options
ram1    ext2  sync
ram2    ext2  sync

The third field is a mount option to be used when mounting this filesystem, see mount(8).

Creating /var/lib/rab/Directories

The final configuration file actually defines all directories to be backed up. In the example at hand, we may use the following file.

# /var/lib/rab/Directories - Directories to be backed up

section /home/foo/programming

# Include all subdirectories, recursively
directory full

# Exclude object files, static and shared libraries
exclude extension .o
exclude extension .a
exclude extension .so

# Exclude binary programs
exclude function binprog@rabstd #!

# Make full backups of this directory
type standard

# Create a CD backup each 14 days
checkpoint days 14

section /home/foo/data
directory full

# Make incremental backups
type archive

# Exclude generated data files
exclude function generated@rabstd .src

section /home/bar
directory full
type      archive

# Exclude hidden files
exclude function hidden@rabstd .

# Exclude hidden directories
excludedir function hidden@rabstd .

section /etc
directory full

# Exclude some of the generated files
exclude list issue motd mtab

# Check /etc only once each 2 weeks
interval 14

section /usr/local/pictures
directory full
type      archive

The lines beginning with 'exclude function' instruct RAB to use an external function to decide whether to exclude the file in question. Both functions used are in the library, an example installed with RAB.

Making backups

Now, everything is in place, and our example user can start making backups. As a first action, let's set a baseline and make a complete backup on CD. This is accomplished by running
rab -avp -checkpoint -i /usr/local/tarballs -i /home/foo/done
The option -checkpoint instructs rab to create a CD backup only. By default, rab expects you to specify a list of directory trees to be backed up, but the option -a tells it just to backup all directories found in the /var/lib/rab/Directories file. The other two options -v and -p produce verbose output and progress messages while creating your CD, respectively. Without these options, rab is pretty quite and tells you about errors only.

The two other directories /usr/local/tarballs and /home/foo/done were discussed above, our user needed those two on some CD. The two -i options tell rab to put these directories on the backup CD created unless there is not enough space left.

Normal backups are done with a similar command
rab -avp -backup
Finally, assume you just deleted the important file /home/foo/programming/something/complicated.c, and now you would like to know on which medium or on which CD the most recent backup of this file resides on. To get this information, run the command
rab -locate /home/foo/programming/something/complicated.c
and happily restore the file afterwards.