
#include "bacula_template.inc" title="Using Autochangers" num=13

<h2>General</h2>
Beginning with version 1.23, <b>Bacula</b> provides autochanger support
for reading and writing tapes.  In order to work with an autochanger,
<b>Bacula</b> requires three things, each of which is explained
in more detail after this list:
<ul>
  <li>A script that actually controls the autochanger according
      to commands sent by <b>Bacula</b>. We fournish such a script
      that works with <b>mtx</b> found in the <b>depkgs</b> distribution.
      </li>
  <li>That each Volume (tape) to be used must have a Slot number assigned
      to it so that <b>Bacula</b> knows where the Volume is in the
      autochanger. This is generally done with the <b>label</b>
      command. See below for more details.
      </li>
   <li>Modifications to your Storage daemon's Device configuration
       resource to identify that the device is a changer, as well
       as a few other parameters.</li>
   <li>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.
</ul>
<p>
<b>Bacula</b> uses its own <b>mtx-changer</b> script to interface with a
a program that actually does the tape changing.  Thus in principle, 
<b>mtx-changer</b> can be adapted to function with any autochanger
program.  The current version of <b>mtx-changer</b> works with the
<b>mtx</b> program.

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

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


<h2>Example Scripts</h2>
Please read the sections below so that you understand
how autochangers work with Bacula. Although we supply
a default <b>mtx-changer</b> script, your autochanger
may require some additional changes. If you want to see
examples of configuration files and scripts, please
look in the <b>&lt;bacula-src&gt;/examples/devices</b> directory
where you will find an example <b>HP-autoloader.conf</b> Bacula
Device resource, and several <b>mtx-changer</b> scripts that have
been modified to work with different autochangers.
   
<h2>Slots</h2>
Some autochangers have more than one read/write device (drive).  The
current implementation, assumes the autochanger has only one device.  To
properly address autochangers, <b>Bacula</b> must know which Volume is
in each <b>slot</b> of the autochanger.  Slots are where the changer
cartridges reside when not loaded into the drive.  <b>Bacula</b> numbers
these slots from one to the number of cartridges contained in the
autochanger.
<p>
For each Volume in your changer, you will, using the Console program,
assign a slot. This information is kept in <b>Bacula's</b> media
database along with the other data for the volume.  If no slot is
given, or the slot is set to zero, <b>Bacula</b> will not attempt
to use the autochanger even if all the necessary configuration
records are present.

<h2>Device Configuration Records</h2>
Configuration of autochangers within <b>Bacula</b>
is done in the Device 
resource of the Storage daemon. Four
records: <b>Autochanger</b>, <b>Changer Device</b>, <b>Changer Command</b>,
and <b>Maximum Changer Wait</b> control
how <b>Bacula</b> uses the autochanger.
<p>These four records, permitted in <b>Device</b> resources,
are described in detail below:

<dl>
  <dt>Autochanger = <em>Yes|No</em></dt> <dd>
      The <b>Autochanger</b> record specifies that the current device
      is or is not an autochanger. The default is <b>no</b>.
      </dd>

  <dt>Changer Device = &lt;device-name&gt;</dt><dd>
      In addition to the Archive Device name, you must specify a
      <b>Changer Device</b> 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 <b>Archive Device = /dev/nst0</b>,
      you would typically have <b>Changer Device = /dev/sg0</b>.
      Note, some of the more advanced autochangers will locate the
      changer device on <b>/dev/sg1</b>. Such devices typically have
      several drives and a large number of tapes.
     </dd>

  <dt>Changer Command = &lt;command&gt;</dt><dd>
      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
      <b>Bacula</b> wishes to manipulate the autochanger.
      The following substitutions are made in the <b>command</b>
      before it is sent to the operating system for execution:
     <pre>
      %% = %
      %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
     </pre>

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

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

     Details of the three commands currently used by <b>Bacula</b>
     (loaded, load, unload) as well as the output expected by
     <b>Bacula</b> are give in the <b>Bacula Autochanger Interface</b>
     section below.
   </dd>

  <dt>Maximum Changer Wait = &lt;time&gt;</dt><dd>
      This record is used to define the maximum amount of time
      that <b>Bacula</b> 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.
      <p>
      If the autoloader program fails to respond in this time, it
      will be killed and <b>Bacula</b> will request operator
      intervention.
    </dd>
</dl>

<h2>An Example Configuration File</h2>
The following <b>Device</b> resource implements an
autochanger:
<pre>
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
}
</pre>
where you will adapt the <b>Archive Device</b>, the
<b>Changer Device</b>, and
the path to the <b>Changer Command</b>
to correspond to the values used on your system.
<p>The above <b>Device</b> resource will work equally well for any
standard tape drive (with device name <b>/dev/nst0</b>) since
the extra autochanger commands will not be used unless a
<b>slot</b> has been specified in the catalog record for
the Volume to be used.  See below for more details on the <b>slot</b>.

<h2>Specifying Slots When Labeling</h2>
If you add an <b>Autochanger = yes</b> record to the
Storage resource in your Director's configuration file, the <b>Bacula</b>
Console will automatically prompt you for the slot number
when you <b>add</b> or <b>label</b> tapes for that Storage device. 
You must also set
<b>Autochanger = yes</b> in the Device resource as we have described
above in order for the autochanger
to be used. Please see the <a href="dirdconf.html#Autochanger">Storage
Resource</a> in the Director's chapter and the 
<a href="storedconf.html#Autochanger">Device
Resource</a> in the Storage daemon chapter for more details on these
records.
<p>
Thus all stages of dealing with tapes can be totally automated.
It is also possible to set or change the Slot using the <b>update</b>
command in the Console and selecting <b>Volume Parameters</b> to update.
<p>
Even though all the above configuration statements are 
specified and correct, <b>Bacula</b> will attempt to access
the autochanger only if a <b>slot</b> is non-zero in the
catalog Volume record (with the Volume name).

<h2>Testing the Autochanger and Adapting Your mtx-changer Script</h2>
Before attempting to use the autochanger with <b>Bacula</b>,
it is preferable to &quot;hand-test&quot; that the
changer works.  To do so, we suggest you do the following
commands (assuming that the <b>mtx-changer</b> script is
installed in <b>/usr/bin/bacula/mtx-changer</b>:
<dl>
  <dt>Make sure Bacula is not running.</dt>

  <dt>/usr/bin/bacula/mtx-changer /dev/sg0 list</dt><dd>
   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 <b>/dev/sg0</b>
   is incorrect. The more sophisticated autochangers will
   sometimes use use /dev/sg1 to control /dev/nst0).</dd>


  <dt>/usr/bin/bacula/mtx-changer /dev/sg0 unload</dt><dd>
   If a tape is loaded, this should cause
   it to be unloaded.</dd>

  <dt>/usr/bin/bacula/mtx-changer /dev/sg0 load 3</dt> <dd>
   Assuming you have a tape in slot 3,
   it will be loaded into the read slot (0).</dd>

  <dt>/usr/bin/bacula/mtx-changer /dev/sg0 loaded</dt><dd>
   It should print "3"</dd>

  <dt>/usr/bin/bacula/mtx-changer /dev/sg0 unload</dt><dd></dt>
</dl>
Once all the above commands work correctly, assuming that
you have the right <b>Changer Command</b> in your
configuration, <b>Bacula</b> 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 <b>mtx-changer</b> 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 <b>sleep 20</b> after the <b>mtx</b>
command, but be careful to exit the script with a zero status
by adding <b>exit 0</b> 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.
<p>You can test whether or not you need a <b>sleep</b> by
putting the following commands into a file and running it 
as a script:
<pre>
#!/bin/sh
/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
</pre>
If the above script runs, you probably have no timing problems.
If it does not run, start by putting a <b>sleep 30</b> or possibly
a <b>sleep 60</b> in the the script just after the mtx-changer load
command.  If that works, then you should move the sleep into the
actual <b>mtx-changer</b> script so that it will be effective when
Bacula runs.
<p>
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 <b>load 3</b> 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:
<pre>
#!/bin/sh
/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
</pre>
Obviously, if you need the <b>offline</b> command, you should move it
into the mtx-changer script ensuring that you save the status of the
<b>mtx</b> command or always force an <b>exit 0</b> from the script,
because Bacula checks the return status of the script.
<p>
As noted earlier, there are several scripts in 
<b>&lt;bacula-source&gt;/examples/devices</b> that implement the
above features, so they may be a help to you in getting your
script to work.

<h2>Using the Autochanger</h2>
Lets assume that you have properly defined the necessary
Storage daemon Device records, and you have added the
<b>Autochanger = yes</b> record to the Storage resource
in your Director's configuration file.  
<p>
Now you fill your autochanger with say six blank tapes.
<p>What do you do to make <b>Bacula</b> access those tapes?
<p>
One strategy is to prelabel each of the tapes. Do so by
starting <b>Bacula</b>, then with the Console program, enter
the <b>label</b> command:
<pre>
./console
Connecting to Director rufus:8101
1000 OK: rufus-dir Version: 1.26 (4 October 2002)
*<b>label</b>
</pre>
it will then prints something like:
<pre>
Using default Catalog name=BackupDB DB=bacula
The defined Storage resources are:
     1: Autochanger
     2: File
Select Storage resource (1-2): <b>1</b>
</pre>
I select the autochanger (1), and it prints:
<pre>
Enter new Volume name: <b>TestVolume1</b>
Enter slot (0 for none): <b>1</b>
</pre>
where I entered <b>TestVolume1</b> for the tape name, and slot <b>1</b>
for the slot. It then asks:
<pre>
Defined Pools:
     1: Default
     2: File
Select the Pool (1-2): <b>1</b>
</pre>
I select the Default pool. This will be automatically done if
you only have a single pool, then <b>Bacula</b> 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:
<pre>
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.
*
</pre>
You may then proceed to label the other volumes. The messages will       
change slightly because <b>Bacula</b> will unload the volume
(just labeled TestVolume1) before loading the next volume to be
labeled.
<p>
Once all your Volumes are labeled, <b>Bacula</b> will automatically
load them as they are needed.
<p>To &quot;see&quot; how you have labeled your Volumes, simply
enter the <b>list volumes</b> command from the Console program,
which should print something like the following:
<pre>
*<b>list volumes</b>
Using default Catalog name=BackupDB DB=bacula
Defined Pools:
     1: Default
     2: File
Select the Pool (1-2): <b>1</b>
<font size=-2>
+---------+----------+-----------+-----------+----------+------------+----------+-------+------+
| 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    |
| ...                                                                                          |
+---------+----------+-----------+-----------+----------+------------+----------+-------+------+
</font>
</pre>

<h2><a name="Models">Autochangers Known to Work with Bacula</a></h2>
I hesitate to call these &quot;supported&quot; 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).
<p>
<table border="2" cellpading="2">
<tr> <th>OS</th> <th>Manufacturer</th> <th>Media</th> <th>Model</th> <th>Slots</th> <th>Capacity/Slot</th> </tr>
<tr> <td>Linux</td> <td>HP</td> <td>DDS-4</td> <td>SureStore DAT-40X6</td> <td>6</td> <td>40GB</td></tr>
<tr> <td>???</td> <td>Sony</td> <td>???</td> <td>TLS-11000</td> <td>8</td><td>????</td></tr>
<tr> <td>???</td> <td>HP</td> <td>DLT</td> <td>A4853 DLT</td> <td>30</td><td>40/70GB</td></tr>
<tr> <td>???</td> <td>Storagetek</td> <td>DLT</td> <td>Timberwolf DLT</td> <td>6</td><td>40/70</td></tr>
<tr> <td>Solaris</td> <td>Sun</td> <td>4mm DLT</td> <td>Sun Desktop/Archive Python 29279</td> <td>4</td><td>20GB</td></tr>
<tr> <td>Linux</td> <td>Adic</td> <td>LTO-2,LTO-, SDLT 320</td> <td>Adic Scalar 24</td> <td>24</td><td>100GB</td></tr>
<tr> <td>Linux</td> <td>Tandberg</td> <td>DLT VI</td> <td>VS 640</td> <td>8?</td><td>80GB</td></tr>
</table>
<p>
In principle, if <b>mtx</b> will operate your changer correctly,
then it is just a question of adapting the <b>mtx-changer</b>  script (or 
selecting one already adapted) for proper interfacing.
You can find a list of autochangers supported by <b>mtx</b>
at the following link: <a href="http://mtx.badtux.net/compatibility.php">
http://mtx.badtux.net/compatibility.php</a>.  The home page for the
<b>mtx</b> project can be found at: <a href="http://mtx.badtux.net/">
http://mtx.badtux.net/</a>.

<h2>Barcode Support</h2>
<b>Bacula</b> provides barcode support with two Console
commands, <b>label barcodes</b> and <b>update slots</b>.
<p>
The <b>label barcodes</b> will cause <b>Bacula</b> to read
the barcodes of all the cassettes that are currently installed
in the magazine (cassette holder) using the <b>mtx-changer</b>
<b>list</b> command. Each cassette is mounted in turn and labeled
with the same Volume name as the barcode.
<p>
The <b>update slots</b> 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 <b>Bacula</b> with the current magazine in case you
have changed magazines or in case you have moved cassettes from
on slot to another.
<p>
The <b>Cleaning Prefix</b> 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 <b>Cleaning</b>.
This will prevent <b>Bacula</b> from attempting to write on the
Volume.
                                              
<h2>Bacula Autochanger Interface</h2>
Bacula calls the autochanger script that you specify on the
<b>Changer Device</b> statement. Normally this script will
be the <b>mtx-changer</b> script that we can provide, but it
can in fact be any program. The only requirements are that
the &quot;commands&quot; that Bacula sents are <b>loaded</b>,
<b>load</b>, <b>unload</b> and <b>list</b> (<b>slots</b> may
be used in the future). In addition, each of those commands
must return the information in the precise format as specified
below:
<pre>
- 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 &lt;slot&gt;:&lt;barcode&gt;. Where
              the <b>slot</b> is the non-zero integer representing
              the slot number, and <b>barcode</b> 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.
</pre>
<b>Bacula</b> 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.

<p>

<page_prev name="Backing Up to Disk Volumes" url="disk.html">
<page_next name="Tips and Suggestions" url="tips.html">
