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

<h2>Autochangers -- General</h2>
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:
<ul>
  <li>A script that actually controls the autochanger according
      to commands sent by Bacula. We furnish such a script
      that works with <b>mtx</b> found in the <b>depkgs</b> distribution.
      This script works only with single drive autochangers.
      </li>
  <li>That each Volume (tape) to be used must be defined in the
      Catalog and have a Slot number assigned
      to it so that Bacula 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>
Bacula 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, Bacula 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 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).
Bacula supports only single drive autochangers. Bacula does
have code to operate multi-drive autochangers. However, 
the implementation is only partial. See below for more 
details.

<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 possession 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 cellspacing="2" cellpadding="2" border="3">
<tr> <th>OS</th> <th>Man.</th> <th>Media</th> <th>Model</th> <th>Slots</th> <th>Cap/Slot</th> </tr>
<tr> <td>Linux</td> <td>Adic</td> <td>LTO-1/2, SDLT 320</td> <td>Adic Scalar 24</td> <td>24</td><td>100GB</td></tr>
<tr> <td>Linux</td> <td>Adic</td> <td>LTO-2</td> <td>Adic FastStor 2, Sun Storedge L8</td> <td>8</td><td>200GB</td></tr>
<tr> <td>-</td> <td>Dell</td> <td>LTO-2</td> <td>PowerValut 132T/136T</td> <td>-</td><td>100GB</td></tr>
<tr> <td>Linux</td> <td>Exabyte</td> <td>VXA2</td> <td>VXA PacketLoader 1x10 2U</td> <td>10</td><td>80/160GB</td></tr>
<tr> <td>Linux Gentoo 1.4</td> <td>Exabyte</td> <td>AIT-2</td> <td>215A</td> <td>15 (2 drives)</td><td>50GB</td></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>Linux</td> <td>HP</td> <td>Ultrium-2/LTO</td> <td>MSL 6000/60030/5052</td> <td>28</td> <td>200/400GB</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>Linux</td> <td>HP (Compaq)</td> <td>DLT VI</td> <td>Compaq TL-895</td> <td>96+4 import export</td><td>35/70GB</td></tr>
<tr> <td>SuSE 9.0</td> <td>IBM</td> <td>LTO</td> <td>IBM 3581 Ultrium Tape Loader</td> <td>7</td><td>200/400GB</td></tr>
<tr> <td>-</td> <td>Overland</td> <td>LTO</td> <td>Overland LoaderXpress LTO</td> <td>10-19</td><td>100GB</td></tr>
<tr> <td>-</td> <td>Overland</td> <td>LTO</td> <td>Overland Neo2000 LTO</td> <td>26-30</td><td>100GB</td></tr>
<tr> <td>FreeBSD 4.9</td> <td>QUALSTAR TLS-4210 (Qualstar)</td> <td>AIT1: 36GB, AIT2: 50GB all uncomp</td> <td>QUALSTAR TLS-4210</td> <td>12</td><td>AIT1: 36GB, AIT2: 50GB all uncomp</td></tr>
<tr> <td>Linux</td> <td>Skydata> <td>DLT</td> <td>ATL-L200</td> <td>8</td><td>40/80</td></tr>
<tr> <td>-</td> <td>Sony</td> <td>DDS-4</td> <td>TSL-11000</td> <td>8</td><td>40GB</td></tr>
<tr> <td>FreeBSD 4.9-STABLE</td> <td>Sony</td> <td>AIT-1</td> <td>TSL-SA300C</td> <td>4</td><td>45/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>Tandberg</td> <td>DLT VI</td> <td>VS 640</td> <td>8?</td><td>35/70GB</td></tr>
<tr> <td>Linux 2.6.x</td> <td>Tandberg Data</td> <td>SLR100</td> <td>SLR100 Autoloader</td> <td>8</td><td>50/100GB</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>.

<a name="devices"></a>
<h2>Knowing What SCSI Devices You Have</h2>
Under Linux, you can
<pre>
cat /proc/scsi/scsi
</pre>
to see what
SCSI devices you have available. You can also:
<pre>
cat /proc/scsi/sg/device_hdr /proc/scsi/sg/devices
</pre>    
to find out how to specify their control address (<b>/dev/sg0</b> for the first,
<b>/dev/sg1</b> for the second, ...) on the <b>Changer Device = </b>
Bacula directive.
<p>Under FreeBSD, you can use:
<pre>
camcontrol devlist
</pre>
To list the SCSI devices as well as the <b>/dev/passn</b> that     
you will use on the Bacula <b>Changer Device = </b> 
directive.

<a name="scripts"></a>
<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.
   
<a name="Slots"></a>
<h2>Slots</h2>
To properly address autochangers, Bacula 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.  Bacula numbers
these slots from one to the number of cartridges contained in the
autochanger.
<p>
Bacula will not automatically use a Volume in your auotchanger
unless it is labeled and the slot number is stored in the catalog.
For each Volume in your changer, you will, using the Console program,
assign a slot. This information is kept in <b>Bacula's</b> catalog
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.  In addition, the console <b>mount</b>
command does not cause Bacula to operate the autochanger, it
only tells Bacula to read any tape that may be in the drive.

<a name="mult"></a>
<h2>Multiple Devices</h2>
Some autochangers have more than one read/write device (drive).  The
current implementation has limited support for multiple devices by
using the <b>Drive Index</b> directive in the Device resource of
the Storage daemon's configuration file. Drive numbers or the Device
Index are numbered beginning at zero, which is the default. To use the
second Drive in an autochanger, you need to define a second Device
resource and set the Drive Index to one for that device. In general,
the second device will have the same <b>Changer Device</b> (control
channel) as the first drive, but a different <b>Archive Device</b>.
<p>
The current implementation of Bacula does not coordinate between the two
drives, so you must make sure that Bacula doesn't attempt to mount
the same Volume on both drives at the same time. There are a number
of ways to do this. One was is to use different pools for each
drive.
<p>
Worse than the above, the <b>mtx</b> program apparently does not
prevent two accesses to the same control device at the same time,
which means that if Bacula happens to attempt to call the mtx-changer
script for two drives simultaneously, something will break.
<p>
A user supplied modified version of the mtx-changer script, which 
does locking to avoid this problem can be found in 
<b>examples/autochangers/locking-mtx-changer</b>.  If you are using
multiple drives, you will probably want to modify this script to
work for you.


<a name="ConfigRecords"></a>
<h2>Device Configuration Records</h2>
Configuration of autochangers within Bacula
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 Bacula 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.
      <p>On FreeBSD systems, the changer device will typically be on
      <b>/dev/pass0</b> through <b>/dev/passn</b>.     
      <p>On Solaris, the changer device will typically be some file 
      under <b>/dev/rdsk</b>.
     </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
      Bacula 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
      %d = changer drive index base 0
      %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 Bacula
     distribution) is:

    <pre>
Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d"
    </pre>

     Where you will need to adapt the <b>/etc/bacula</b> to be
     the actual path on your system where the mtx-changer script
     resides.
     Details of the three commands currently used by Bacula
     (loaded, load, unload) as well as the output expected by
     Bacula 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 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.
      <p>
      If the autoloader program fails to respond in this time, it
      will be killed and Bacula will request operator
      intervention.
    </dd>

   <dt>Drive Index = &lt;number&gt;</dt><dd>
      This record allows you to tell Bacula to use the second
      or subsequent drive in an autochanger with multiple drives.
      Since the drives are numbered from zero, the second 
      drive is defined by
      <pre>
Device Index = 1
      </pre>
      To use the second drive, you need a second Device resource definition
      in the Bacula configuration file. See the Multiple Drive section above
      in this chapter for more information.</dd>
</dl>

<a name="example"></a>
<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 = "/etc/bacula/mtx-changer %c %o %S %a %d"
  Autochanger = yes
  LabelMedia = no; 
  AutomaticMount = yes;
  AlwaysOpen = yes;
  Mount Anonymous Volumes = no;
}
</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>.

<a name="SpecifyingSlots"></a>
<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 Bacula
Console will automatically prompt you for the slot number and
whether or not the Volume is in the changer
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, Bacula will attempt to access
the autochanger only if a <b>slot</b> is non-zero in the
catalog Volume record (with the Volume name).
<p>
p>If your autochanger has barcode labels, you can label all the
Volumes in your autochanger one after another by using the 
<b>label barcodes</b> command. For each tape in the changer containing
a barcode, Bacula will mount the tape and then label it with the
same name as the barcode. An appropriate Media record will also be
created in the catalog.  Any barcode that begins with the same characters
as specified on the "CleaningPrefix=xxx" command, will be treated as a
cleaning tape, and will not be labeled.  For example with:
<pre>
Pool {
  Name ...
  Cleaning Prefix = "CLN"
}
</pre>
Any slot containing a barcode of CLNxxxx will be treated as a cleaning
tape and will not be mounted.


<a name="Magazines"></a>
<h2>Dealing with Multiple Magazines</h2>
If you have several magazines or if you insert or remove cartridges
from a magazine, you will need to notify Bacula of this. By doing
so, Bacula will as a preference, use Volumes that it knows to be
in the autochanger before accessing Volumes that are not in the
autochanger. This prevents unneeded operator intervention.
<p>
If your autochanger has barcodes (machine readable tape labels), the
task of informing Bacula is simple. Every time, you change a magazine,
or add or remove a cartridge from the magazine, simply do
<pre>
update slots
</pre>
in the Console program. This will cause Bacula to request the autochanger
to return the current Volume names in the magazine. This will be done without
actually accessing or reading the Volumes because the barcode reader does
this during inventory when the autochanger is first turned on.
Bacula will ensure that any Volumes that are
currently marked as being in the magazine are marked as no longer in
the magazine, and the new list of Volumes will be marked as being
in the magazine. In addition, the Slot numbers of the Volumes will be corrected
in Bacula's catalog if they are incorrect (added or moved).
<p>
If you do not have a barcode reader on your autochanger, you have
several alternatives. 
<ol>
 <li>You can manually set the Slot and InChanger flag using
     the <b>update volume</b> command in the Console (quite
     painful).</li>
 <li>You can issue a
<pre>
update slots scan
</pre>
     command that will cause Bacula to read the label on each
     of the cartridges in the magazine in turn and update the
     information (Slot, InChanger flag) in the catalog. This
     is quite effective but does take time to load each cartridge
     into the drive in turn and read the Volume label.</li>
  <li>You can modify the mtx-changer script so that it simulates
     an autochanger with barcodes. See below for more details.</li>
</ol>

<a name="simulating"></a>
<h2>Simulating Barcodes in your Autochanger</h2>
You can simulate barcodes in your autochanger by making the <b>mtx-changer</b>
script return the same information that an autochanger with barcodes would
do. This is done by commenting out the
one and only line in the <b>list)</b> case, which is:
<pre>
  ${MTX} -f $ctl status | grep " *Storage Element [0-9]*:.*Full" | awk "{print \$3 \$4}" | sed "s/Full *\(:VolumeTag=\)*//"
</pre>
at approximately line 99 by putting a # in column one of that line,
or by simply deleting it.  Then in its place add a new line that
prints the contents of a file.  For example:
<pre>
cat /etc/bacula/changer.volumes
</pre>
Be sure to include a full path to the file, which can have any name.
The contents of the file must be of the following format:
<pre>
1:Volume1
2:Volume2
3:Volume3
...
</pre>
Where the 1, 2, 3 are the slot numbers and Volume1, Volume2, ... are the
Volume names in those slots.  You can have multiple files that represent 
the Volumes in different magazines, and when you change magazines, simply 
copy the contents of the correct file into your <b>/etc/bacula/changer.volumes</b>
file. There is no need to stop and start Bacula when you change magazines,
simply put the correct data in the file, then run the <b>update slots</b>
command, and your autochanger will appear to Bacula to be an autochanger
with barcodes.

<a name="updateslots"></a>
<h2>The Full Form of the Update Slots Command</h2>
If you change only one cartridge in the magazine, you may not want to
scan all Volumes, so the <b>update slots</b> command (as well as the
<b>update slots scan</b> command) has the additional form:
<pre>
update slots=n1,n2,n3-n4, ... 
</pre>
where the keyword <b>scan</b> can be appended or not.
The n1,n2, ... represent Slot numbers to be updated and the form
n3-n4 represents a range of Slot numbers to be updates (e.g. 4-7 will 
update Slots 4,5,6, and 7). 
<p>
This form is particularly useful if you want to do a scan (time expensive) and
restrict the update to one or two slots.
<p>
For example, the command:
<pre>
update slots=1,6 scan
</pre>
will cause Bacula to load the Volume in Slot 1, read its Volume
label and update the Catalog. It will do the same for the Volume
in Slot 6.  The command:
<pre>
update slots=1-3,6
</pre>
will read the barcoded Volume names for slots 1,2,3 and 6 and make
the appropriate updates in the Catalog.  If you don't have a barcode
reader or have not modified the mtx-changer script as described above, the
above command will not find any Volume names so will do nothing.

<a name="FreeBSD"></a>
<h2>FreeBSD Issues</h2>
If you are having problems on FreeBSD when Bacula tries  
to select a tape, and the message is <b>Device not configured</b>,
this is because FreeBSD has made the tape device <b>/dev/nsa1</b>
disappear when there is no tape mounted in the autochanger
slot.  As a consequence, Bacula is unable to open the device.
The solution to the problem is to make sure that some tape
is loaded into the tape drive before starting Bacula.
This problem is correct in Bacula versions 1.32f-5 and later.
<p>
Please see the <a href="tapetesting.html#FreeBSDTapes">
Tape Testing</a> chapter of this manual for
<b>important</b> information concerning your tape drive 
before doing the autochanger testing.

<a name="AutochangerTesting"></a>
<h2>Testing the Autochanger and Adapting Your mtx-changer Script</h2>
Before attempting to use the autochanger with Bacula,
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>/etc/bacula/mtx-changer</b>):
<dl>
  <dt>Make sure Bacula is not running.</dt>

  <dt>/etc/bacula/mtx-changer &nbsp; /dev/sg0 &nbsp; list &nbsp; 0 &nbsp; /dev/nst0 &nbsp; 0</dt><dd>
   This command should print:
   <pre>
   1:
   2:
   3:
   ...
   </pre>
   or one number per line for each slot that is 
   occupied in your changer, and the number should be
   terminated by a colon (<b>:</b>). If your changer has
   barcodes, the barcode will follow the colon.
   If an error message is printed, you must resolve the
   problem (e.g. try a different SCSI control device name if <b>/dev/sg0</b>
   is incorrect. For example, on FreeBSD systems, the autochanger
   SCSI control device is generally <b>/dev/pass2</b>.</dd>

  <dt>/etc/bacula/mtx-changer &nbsp; /dev/sg0 &nbsp; slots &nbsp; 0 &nbsp; /dev/nst0 &nbsp; 0</dt><dd>
   This command should return the number of slots in your autochanger.

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

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

  <dt>/etc/bacula/mtx-changer &nbsp; /dev/sg0 &nbsp; loaded &nbsp; 0 &nbsp; /dev/nst0 &nbsp; 0</dt><dd>
   It should print "3"</dd>

  <dt>/etc/bacula/mtx-changer &nbsp; /dev/sg0 &nbsp; 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, 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 <b>mtx-changer</b> script
returns, Bacula will immediately rewind and read the tape.
If Bacula gets rewind I/O 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
/etc/bacula/mtx-changer /dev/sg0 unload
/etc/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 comes up with a small number of 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
regardless 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
/etc/bacula/mtx-changer /dev/sg0 unload
mt -f /dev/st0 offline
/etc/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.
<p>If Bacula complains &quot;Rewind error on /dev/nst0. 
ERR=Input/output error.&quot; you most likely need more sleep time in
your <b>mtx-changer</b> before returning to Bacula after a 
load command has been completed.

<a name="using"></a>
<h2>Using the Autochanger</h2>
Let's 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 Bacula access those tapes?
<p>
One strategy is to prelabel each of the tapes. Do so by
starting Bacula, 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 print 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 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:
<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 Bacula will unload the volume
(just labeled TestVolume1) before loading the next volume to be
labeled.
<p>
Once all your Volumes are labeled, Bacula 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>
+-------+----------+--------+---------+-------+--------+----------+-------+------+
| MedId | VolName  | MedTyp | VolStat | Bites | LstWrt | 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>


<a name="Barcodes"></a>
<h2>Barcode Support</h2>
Bacula provides barcode support with two Console
commands, <b>label barcodes</b> and <b>update slots</b>.
<p>
The <b>label barcodes</b> will cause Bacula 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 obtain the list of 
cassettes and their barcodes from <b>mtx-changer</b>. Then 
it will find each volume in turn in the catalog database corresponding to
to the barcodes and set its 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
one 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 Bacula from attempting to write on the
Volume.
                                              
<a name="interface"></a>
<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 uses 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>
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.

<p>

<page_prev name="Data Spooling" url="spooling.html">
<page_next name="Tips and Suggestions" url="tips.html">
