Bacula 1.30 User's Guide | Chapter 13

Backing Up to Disk Volumes | Index | Tips and Suggestions

## General

Beginning with version 1.23, Bacula provides autochanger support for reading and writing tapes. In order to work with an autochanger, Bacula requires three things, each of which is explained in more detail after this list:

- A script that actually controls the autochanger according to commands sent by Bacula. We fournish such a script that works with mtx found in the depkgs distribution.
- That each Volume (tape) to be used must have a Slot number assigned to it so that Bacula knows where the Volume is in the autochanger. This is generally done with the label command. See below for more details.
- Modifications to your Storage daemon's Device configuration resource to identify that the device is a changer, as well as a few other parameters.
- Optionally, you can modify your Storage resource definition in the Director's configuration file so that you are automatically prompted for the Slot when labeling a Volume.

Bacula uses its own mtx-changer script to interface with a a program that actually does the tape changing. Thus in principle, mtx-changer can be adapted to function with any autochanger program. The current version of mtx-changer works with the mtx program.

As of version 1.30, Bacula supports autochangers with barcode readers. This support includes two new Console commands: label barcodes and update slots. For more details on these commands, see the "Barcode Support" section below.

Current Bacula autochanger support does not include cleaning, stackers, or silos. However, under certain conditions, you may be able to make Bacula work with stackers (gravity feed and such).

## Example Scripts

Please read the sections below so that you understand how autochangers work with Bacula. Although we supply a default mtx-changer script, your autochanger may require some additional changes. If you want to see examples of configuration files and scripts, please look in the <bacula-src>/examples/devices directory where you will find an example HP-autoloader.conf Bacula Device resource, and several mtx-changer scripts that have been modified to work with different autochangers.

## Slots

Some autochangers have more than one read/write device (drive). The current implementation, assumes the autochanger has only one device. To properly address autochangers, Bacula must know which Volume is in each slot of the autochanger. Slots are where the changer cartridges reside when not loaded into the drive. Bacula numbers these slots from one to the number of cartridges contained in the autochanger.

For each Volume in your changer, you will, using the Console program, assign a slot. This information is kept in Bacula's media database along with the other data for the volume. If no slot is given, or the slot is set to zero, Bacula will not attempt to use the autochanger even if all the necessary configuration records are present.

## Device Configuration Records

Configuration of autochangers within Bacula is done in the Device resource of the Storage daemon. Four records: Autochanger, Changer Device, Changer Command, and Maximum Changer Wait control how Bacula uses the autochanger.

These four records, permitted in Device resources, are described in detail below:

Autochanger = Yes|No
  The Autochanger record specifies that the current device is or is not an autochanger. The default is no.
Changer Device = <device-name>
  In addition to the Archive Device name, you must specify a Changer Device name. This is because most autochangers are controlled through a different device than is used for reading and writing the cartridges. For example, on Linux, one normally uses the generic SCSI interface for controlling the autochanger, but the standard SCSI interface for reading and writing the tapes. On Linux, for the Archive Device = /dev/nst0, you would typically have Changer Device = /dev/sg0. Note, some of the more advanced autochangers will locate the changer device on /dev/sg1. Such devices typically have several drives and a large number of tapes.
Changer Command = <command>
  This record is used to specify the external program to call and what arguments to pass to it. The command is assumed to be a standard program or shell script that can be executed by the operating system. This command is invoked each time that Bacula wishes to manipulate the autochanger. The following substitutions are made in the command before it is sent to the operating system for execution:

            %% = %
            %a = archive device name
            %c = changer device name
            %f = Client's name
            %j = Job name
            %o = command  (loaded, load, or unload)
            %s = Slot base 0
            %S = Slot base 1
            %v = Volume name

  An actual example for using mtx with the mtx-changer script (part of the Bacula distribution) is:

           Changer Command = "/usr/bin/mtx-changer %c %o %S %a"

  Details of the three commands currently used by Bacula (loaded, load, unload) as well as the output expected by Bacula are give in the Bacula Autochanger Interface section below.
Maximum Changer Wait = <time>
  This record is used to define the maximum amount of time that Bacula will wait for an autoloader to respond to a command (e.g. load). The default is set to 120 seconds. If you have a slow autoloader you may want to set it longer.

  If the autoloader program fails to respond in this time, it will be killed and Bacula will request operator intervention.

## An Example Configuration File

The following Device resource implements an autochanger:

    Device {
      Name = "Autochanger"
      Media Type = DDS-4
      Archive Device = /dev/nst0          # Normal archive device
      Changer Device = /dev/sg0           # Generic SCSI device name
      Changer Command = "/usr/bin/bacula/mtx-changer %c %o %S %a"
      Autochanger = yes
      LabelMedia = no;                    # lets Bacula label unlabeled media
      AutomaticMount = yes;               # when device opened, read it
      AlwaysOpen = yes;
      Mount Anonymous Volumes = no;       # Require Volumes in Catalog order
    }

where you will adapt the Archive Device, the Changer Device, and the path to the Changer Command to correspond to the values used on your system.

The above Device resource will work equally well for any standard tape drive (with device name /dev/nst0) since the extra autochanger commands will not be used unless a slot has been specified in the catalog record for the Volume to be used. See below for more details on the slot.

## Specifying Slots When Labeling

If you add an Autochanger = yes record to the Storage resource in your Director's configuration file, the Bacula Console will automatically prompt you for the slot number when you add or label tapes for that Storage device. You must also set Autochanger = yes in the Device resource as we have described above in order for the autochanger to be used. Please see the Storage Resource in the Director's chapter and the Device Resource in the Storage daemon chapter for more details on these records.

Thus all stages of dealing with tapes can be totally automated. It is also possible to set or change the Slot using the update command in the Console and selecting Volume Parameters to update.

Even though all the above configuration statements are specified and correct, Bacula will attempt to access the autochanger only if a slot is non-zero in the catalog Volume record (with the Volume name).

## Testing the Autochanger and Adapting Your mtx-changer Script

Before attempting to use the autochanger with Bacula, it is preferable to "hand-test" that the changer works. To do so, we suggest you do the following commands (assuming that the mtx-changer script is installed in /usr/bin/bacula/mtx-changer:

Make sure Bacula is not running.
/usr/bin/bacula/mtx-changer /dev/sg0 list
  This command should print "1 2 3 4 5 6" or one number for each slot that is occupied in your changer. If an error message is printed, you must resolve the problem (e.g. try a different device name if /dev/sg0 is incorrect. The more sophisticated autochangers will sometimes use use /dev/sg1 to control /dev/nst0).
/usr/bin/bacula/mtx-changer /dev/sg0 unload
  If a tape is loaded, this should cause it to be unloaded.
/usr/bin/bacula/mtx-changer /dev/sg0 load 3
  Assuming you have a tape in slot 3, it will be loaded into the read slot (0).
/usr/bin/bacula/mtx-changer /dev/sg0 loaded
  It should print "3"
/usr/bin/bacula/mtx-changer /dev/sg0 unload

Once all the above commands work correctly, assuming that you have the right Changer Command in your configuration, Bacula should be able to operate the changer. The only remaining area of problems will be if your autoloader needs some time to get the tape loaded after issuing the command. After the mtx-changer script returns, Bacula will immediately rewind and read the tape. If Bacula printers rewind errors after a tape change, you will probably need to insert a sleep 20 after the mtx command, but be careful to exit the script with a zero status by adding exit 0 after any additional commands you add to the script. This is because Bacula checks the return status of the script, which should be zero if all went well.

You can test whether or not you need a sleep by putting the following commands into a file and running it as a script:

    /usr/bin/bacula/mtx-changer /dev/sg0 unload
    /usr/bin/bacula/mtx-changer /dev/sg0 load 3
    mt -f /dev/st0 rewind
    mt -f /dev/st0 weof

If the above script runs, you probably have no timing problems. If it does not run, start by putting a sleep 30 or possibly a sleep 60 in the the script just after the mtx-changer load command. If that works, then you should move the sleep into the actual mtx-changer script so that it will be effective when Bacula runs.

A second problem that typically comes up with some autochangers is that they need to have the cartridge ejected before it can be removed. If this is the case, the load 3 will never succeed regarless of how long you wait. If this seems to be your problem, you can insert an eject just after the unload so that the script looks like:

    /usr/bin/bacula/mtx-changer /dev/sg0 unload
    mt -f /dev/st0 offline
    /usr/bin/bacula/mtx-changer /dev/sg0 load 3
    mt -f /dev/st0 rewind
    mt -f /dev/st0 weof

Obviously, if you need the offline command, you should move it into the mtx-changer script ensuring that you save the status of the mtx command or always force an exit 0 from the script, because Bacula checks the return status of the script.

As noted earlier, there are several scripts in <bacula-source>/examples/devices that implement the above features, so they may be a help to you in getting your script to work.

## Using the Autochanger

Lets assume that you have properly defined the necessary Storage daemon Device records, and you have added the Autochanger = yes record to the Storage resource in your Director's configuration file.

Now you fill your autochanger with say six blank tapes.

What do you do to make Bacula access those tapes?

One strategy is to prelabel each of the tapes. Do so by starting Bacula, then with the Console program, enter the label command:

    ./console
    Connecting to Director rufus:8101
    1000 OK: rufus-dir Version: 1.26 (4 October 2002)
    *label

it will then prints something like:

    Using default Catalog name=BackupDB DB=bacula
    The defined Storage resources are:
         1: Autochanger
         2: File
    Select Storage resource (1-2): 1

I select the autochanger (1), and it prints:

    Enter new Volume name: TestVolume1
    Enter slot (0 for none): 1

where I entered TestVolume1 for the tape name, and slot 1 for the slot. It then asks:

    Defined Pools:
         1: Default
         2: File
    Select the Pool (1-2): 1

I select the Default pool. This will be automatically done if you only have a single pool, then Bacula will proceed to unload any loaded volume, load the volume in slot 1 and label it. In this example, nothing was in the drive, so it printed:

    Connecting to Storage daemon Autochanger at localhost:9103 ...
    Sending label command ...
    3903 Issuing autochanger "load slot 1" command.
    3000 OK label. Volume=TestVolume1 Device=/dev/nst0
    Media record for Volume=TestVolume1 successfully created.
    Requesting mount Autochanger ...
    3001 Device /dev/nst0 is mounted with Volume TestVolume1
    You have messages.
    *

You may then proceed to label the other volumes. The messages will change slightly because Bacula will unload the volume (just labeled TestVolume1) before loading the next volume to be labeled.

Once all your Volumes are labeled, Bacula will automatically load them as they are needed.

To "see" how you have labeled your Volumes, simply enter the list volumes command from the Console program, which should print something like the following:

    *list volumes
    Using default Catalog name=BackupDB DB=bacula
    Defined Pools:
         1: Default
         2: File
    Select the Pool (1-2): 1

    +---------+----------+-----------+-----------+----------+------------+----------+-------+------+
    | MediaId | VolName  | MediaType | VolStatus | VolBytes | LstWritten | VolReten | Recyc | Slot |
    +---------+----------+-----------+-----------+----------+------------+----------+-------+------+
    | 1       | TestVol1 | DDS-4     | Append    | 0        | 0          | 30672000 | 0     | 1    |
    | 2       | TestVol2 | DDS-4     | Append    | 0        | 0          | 30672000 | 0     | 2    |
    | 3       | TestVol3 | DDS-4     | Append    | 0        | 0          | 30672000 | 0     | 3    |
    | ...                                                                                          |
    +---------+----------+-----------+-----------+----------+------------+----------+-------+------+

## Autochangers Known to Work with Bacula

I hesitate to call these "supported" autochangers because the only autochanger that I have in my possition and am able to test is the HP SureStore DAT40X6. All the other autochangers have been reported to work by Bacula users. Note, in the Capacity/Slot column below, I quote the Compressed capacity per tape (or Slot).

OS | Manufacturer | Media | Model | Slots | Capacity/Slot
--- | --- | --- | --- | --- | ---
Linux | HP | DDS-4 | SureStore DAT-40X6 | 6 | 40GB
??? | Sony | ??? | TLS-11000 | 8 | ????
??? | HP | DLT | A4853 DLT | 30 | 40/70GB
??? | Storagetek | DLT | Timberwolf DLT | 6 | 40/70
Solaris | Sun | 4mm DLT | Sun Desktop/Archive Python 29279 | 4 | 20GB
Linux | Adic | LTO-2,LTO-, SDLT 320 | Adic Scalar 24 | 24 | 100GB
Linux | Tandberg | DLT VI | VS 640 | 8? | 80GB

In principle, if mtx will operate your changer correctly, then it is just a question of adapting the mtx-changer script (or selecting one already adapted) for proper interfacing. You can find a list of autochangers supported by mtx at the following link: http://mtx.badtux.net/compatibility.php. The home page for the mtx project can be found at: http://mtx.badtux.net/.

## Barcode Support

Bacula provides barcode support with two Console commands, label barcodes and update slots.

The label barcodes will cause Bacula to read the barcodes of all the cassettes that are currently installed in the magazine (cassette holder) using the mtx-changer list command. Each cassette is mounted in turn and labeled with the same Volume name as the barcode.

The update slots command will first find the list of cassettes and their barcodes. Then it find the Volume corresponding to the barcodes in the catalog database and set their Slot to correspond to the value just read. If the Volume is not in the catalog, then nothing will be done. This command is useful for synchronizing Bacula with the current magazine in case you have changed magazines or in case you have moved cassettes from on slot to another.

The Cleaning Prefix statement can be used in the Pool resource to define a Volume name prefix, which if it matches that of the Volume (barcode) will cause that Volume to be marked with a VolStatus of Cleaning. This will prevent Bacula from attempting to write on the Volume.

## Bacula Autochanger Interface

Bacula calls the autochanger script that you specify on the Changer Device statement. Normally this script will be the mtx-changer script that we can provide, but it can in fact be any program. The only requirements are that the "commands" that Bacula sents are loaded, load, unload and list (slots may be used in the future). In addition, each of those commands must return the information in the precise format as specified below:

    - Currently the changer commands used are:
        loaded -- returns number of the slot that is loaded in
                  the drive or 0 if the drive is empty.
        load   -- loads a specified slot (note, some autochangers
                  require a 30 second pause after this command) into
                  the drive.
        unload -- unloads the device (returns cassette to its slot).
        list   -- returns one line for each cassette in the autochanger
                  in the format <slot>:<barcode>. Where
                  the slot is the non-zero integer representing
                  the slot number, and barcode is the barcode
                  associated with the cassette if it exists and if you
                  autoloader supports barcodes. Otherwise the barcode
                  field is blank.

    - Other changer commands defined but not yet used:
        slots  -- returns total number of slots in the autochanger.

Bacula checks the exit status of the program called, and if it is zero, the data is accepted. If the exit status is non-zero, Bacula ignores any information returned and treats the drive as if it is not an autochanger.

Backing Up to Disk Volumes | Index | Tips and Suggestions

Bacula 1.30 User's Guide The Network Backup Solution | Copyright © 2000-2003 Kern Sibbald and John Walker