  
#include "bacula_template.inc" title="Tape Testing" num=16

<h1>Testing Your Tape Drive With Bacula</h1>
This chapter is concerned with testing and configuring
your tape drive to make sure that it will work properly
with Bacula using the <b>btape</b> program.

<h3>Specifying the Configuration File</h3>
Starting with version 1.27, each of the <b>btape</b> program
requires a valid Storage daemon configuration
file (actually, the only part of the configuration file
that <b>btape</b> needs is
the <b>Device</b> resource definitions). 
This permits <b>btape</b> to find the configuration parameters
for your archive device (generally a tape drive). By
default, it reads <b>bacula-sd.conf</b> in the current directory,
but you may specify a different     
configuration file using the <b>-c</b> option.

<h3>Specifying a Device Name For a Tape</h3>
<b>btape</b>
<b>device-name</b> where the Volume can be found.
In the case of a tape, this is the
physical device name such as <b>/dev/nst0</b> or 
<b>/dev/rmt/0ubn</b> depending on your system. For the
program to work, it must find the identical name in
the Device resource of the configuration file. 
See below for specifying Volume names.

<h3>Specifying a Device Name For a File</h3>
If you are attempting to read or write
an archive file rather than
a tape, the <b>device-name</b> should be the full 
path to the archive location including
the filename. The filename (last part of the specification) will
be stripped and used as the Volume name, and the path
(first part before the filename) must have the same
entry in the configuration file.  So, the path is equivalent
to the archive device name, and the filename is equivalent
to the volume name.

<h1><a name="btape">btape</a></h1>
This program permits a number of elementary tape operations
via a tty command interface. 
The <b>test</b> command,
described below, can be very useful for testing older tape 
drive compatibility problems.
Aside from initial testing of tape drive compatibility
with <b>Bacula</b>, <b>btape</b> will be mostly used by
developers writing new tape drivers. 
<p>
<b>btape</b> can be dangerous to use with existing
<b>Bacula</b> tapes because it will relabel a tape or  
write on the tape if so requested regardless that   
the tape may contain valuable data, so please be
careful and use it only on blank tapes.


<p>To work properly, <b>btape</b> needs to read the Storage
daemon's configuration file. As a default, it will look for
<b>bacula-sd.conf</b> in the current directory. If your
configuration file is elsewhere, please use the <b>-c</b>
option to specify where.
<p>The physical device name must be specified
on the command line, and that this same device name must be present
in the Storage daemon's configuration file read by <b>btape</b>
<pre>
Usage: btape [-c config_file] [-d debug_level] [device_name]
       -c &lt;file&gt;   set configuration file to file
       -dnn        set debug level to nn
       -s          turn off signals
       -t          open the default tape device
       -?          print this message.
</pre>


<h3>Using btape to Verify your Tape Drive</h3>                 
<p>An important reason for this program is
to ensure that a Storage daemon configuration
file is defined so that <b>Bacula</b> will correctly read and write
tapes. 
<p>
It is highly recommended that you run the <b>test</b> command 
before running 
your first <b>Bacula</b> job to ensure that the parameters you
have defined for your storage device (tape drive) will permit
<b>Bacula</b> to function properly. You only need to mount
a blank tape, enter the command, and the output should be
reasonably self explanatory.
For example:
<pre>
(ensure that Bacula is not running)
./btape -c /usr/bin/bacula/bacula-sd.conf /dev/nst0
</pre>
The output will be:
<pre>
Tape block granularity is 1024 bytes.
btape: btape.c:376 Using device: /dev/nst0
*
</pre>
Enter the test command:
<pre>
test
</pre>
The output produced should be something similar to the following:
<pre>

=== Append files test ===

This test is essential to Bacula.

I'm going to write one record  in file 0,
                   two records in file 1,
             and three records in file 2

btape: btape.c:387 Rewound /dev/nst0
btape: btape.c:855 Wrote one record of 64412 bytes.
btape: btape.c:857 Wrote block to device.
btape: btape.c:410 Wrote EOF to /dev/nst0
btape: btape.c:855 Wrote one record of 64412 bytes.
btape: btape.c:857 Wrote block to device.
btape: btape.c:855 Wrote one record of 64412 bytes.
btape: btape.c:857 Wrote block to device.
btape: btape.c:410 Wrote EOF to /dev/nst0
btape: btape.c:855 Wrote one record of 64412 bytes.
btape: btape.c:857 Wrote block to device.
btape: btape.c:855 Wrote one record of 64412 bytes.
btape: btape.c:857 Wrote block to device.
btape: btape.c:855 Wrote one record of 64412 bytes.
btape: btape.c:857 Wrote block to device.
btape: btape.c:410 Wrote EOF to /dev/nst0
btape: btape.c:387 Rewound /dev/nst0
btape: btape.c:693 Now moving to end of media.
btape: btape.c:427 Moved to end of media
We should be in file 3. I am at file 3. This is correct!

Now the important part, I am going to attempt to append to the tape.

btape: btape.c:855 Wrote one record of 64412 bytes.
btape: btape.c:857 Wrote block to device.
btape: btape.c:410 Wrote EOF to /dev/nst0
btape: btape.c:387 Rewound /dev/nst0
Done appending, there should be no I/O errors

Doing Bacula scan of blocks:
1 block of 64448 bytes in file 1
End of File mark.
2 blocks of 64448 bytes in file 2
End of File mark.
3 blocks of 64448 bytes in file 3
End of File mark.
1 block of 64448 bytes in file 4
End of File mark.
Total files=4, blocks=7, bytes = 451136
End scanning the tape.
We should be in file 4. I am at file 4. This is correct!

The above Bacula scan should have output identical to what follows.
Please double check it ...
=== Sample correct output ===
1 block of 64448 bytes in file 1
End of File mark.
2 blocks of 64448 bytes in file 2
End of File mark.
3 blocks of 64448 bytes in file 3
End of File mark.
1 block of 64448 bytes in file 4
End of File mark.
Total files=4, blocks=7, bytes = 451136
=== End sample correct output ===

If the above scan output is not identical to the
sample output, you MUST correct the problem
or Bacula will not be able to write multiple Jobs to 
the tape.


=== Write, backup, and re-read test ===

I'm going to write three records and two eof's
then backup over the eof's and re-read the last record.
Bacula does this after writing the last block on the
tape to verify that the block was written correctly.
It is not an *essential* feature ...

btape: btape.c:387 Rewound /dev/nst0
btape: btape.c:597 Wrote first record of 64412 bytes.
btape: btape.c:608 Wrote second record of 64412 bytes.
btape: btape.c:619 Wrote third record of 64412 bytes.
btape: btape.c:410 Wrote EOF to /dev/nst0
btape: btape.c:410 Wrote EOF to /dev/nst0
btape: btape.c:631 Backspaced over two EOFs OK.
btape: btape.c:636 Backspace record OK.
btape: btape.c:658 
Block re-read correct. Test succeeded!
=== End Write, backup, and re-read test ===


=== End Append files test ===
</pre>

If you do not successfully complete the above test, please
resolve the problem(s) before attempting to use <b>Bacula</b>. 
Depending on your tape drive, the test may recommend that you
add certain records to your configuration. We strongly
recommend that you do so and then re-run the above test
to insure it works the first time.

<h3>Tips for Resolving Problems</h3>
<h4>Incorrect File Number</h4>
When <b>Bacula</b> moves to the end of the medium, it     
normally uses the <b>ioctl(MTEOM)</b> function. 
Then <b>Bacula</b> uses the <b>ioctl(MTIOCGET)</b> 
function to retrieve the current file position from the
<b>mt_fileno</b> field. Some SCSI 
tape drivers will use a fast means of seeking to the end
of the medium and in doing so, they will not know
the current file position and hence return a <b>-1</b>.
As a consequence, if you get <b>"This is NOT correct!"</b> in
the positioning tests, this may be the cause.  You must 
correct this condition in order for <b>Bacula</b> to work.
<p>There are two possible solutions to the above problem
of incorrect file number:
<ul>
  <li>Figure out how to configure your SCSI driver to
      keep track of the file position during the MTEOM
      request. This is the preferred solution.</li>
  <li>Modify the <b>Device</b> resource of your <b>bacula-sd.conf</b> file
      to include:
      <pre>Hardware End of File = no</pre>
      This will cause <b>Bacula</b> to use the MTFSF request to
      seek to the end of the medium, and <b>Bacula</b> will keep
      track of the file number itself. </li>
</ul>

<h4>Incorrect Number of Blocks</h4>
<b>Bacula's</b> preferred method of working with tape drives
(sequential devices) is to run in variable block mode. All
modern tape drives support this mode, but some older drives
(in particular the QIC drives) as well as the ATAPI ide-scsi
driver run only in fixed block mode.
<p>
Even in variable block mode, with the exception of the first 
record on the second or subsequent volume of a multi-volume
backup, <b>Bacula</b> will write blocks of a fixed size.
However, in reading a tape, <b>Bacula</b> will assume that for    
each read request, exactly one block from the tape will
be transferred. This the most common way that tape drives
work and is well supported by <b>Bacula</b>.
<p>Drives that run in fixed block mode can cause serious
problems for <b>Bacula</b> if the drive's block size does
not correspond exactly to <b>Bacula's</b> block size. 
In fixed block size mode, drivers may transmit a partial
block or multiple blocks for a single read request. From
<b>Bacula's</b> point of view, this destroys the concept
of tape blocks. In order for <b>Bacula</b> to run in fixed block
mode, you must include the following records in the
Storage daemon's Device resource definition:
<pre>
Minimum Block Size = nnn
Maximum Block Size = nnn
</pre>
where <b>nnn</b> must be the same for both records and must be identical
to the driver's fixed block size.
<p>
We recommend that you avoid this configuration if at all
possible.  In any case, as of version 1.27, it is not at all
clear that Bacula's handling of these fixed block drivers
really works.

<h3>Ensuring that the Tape Modes Are Properly Set -- <b>Linux Only</b></h3>
If you have a modern SCSI tape drive and you are having
problems with the <b>test</b> command as noted above, it
may be that some program has set one or more of the
your SCSI driver's options to non-default values. For
example, if your driver is set to work in SysV manner,
Bacula will not work correctly because it expects
BSD behavior.  To reset your tape drive to the default
values, you can try the following, but <b>ONLY</b> if you
have a SCSI tape drive on a <b>Linux</b> system:
<pre>
become super user
mt -f /dev/nst0 rewind
mt -f /dev/nst0 stoptions buffer-writes async-writes read-ahead
</pre>
The above command will clear all options and then
set those specified. None of the specified options are
required by Bacula, but a number of other options such
as SysV behavior must not be set.  On systems other than 
Linux, you will need to consult your <b>mt</b> man pages
or documentation to figure out how to do the same thing.
This should not really be necessary though -- for example,
on both Linux and Solaris systems, the default tape
driver options are compatible with Bacula.

<h3>Tape Modes on FreeBSD</h3>
Normally <b>Bacula</b> should run with: <b>mt -f /dev/nsa0 seteotmodel 2</b>,
and then according to what the <b>btape test</b> command returns,
you will probably need to set the following:
<pre>
Hardware End of Medium = no
BSF at EOM = yes
</pre>
but you should start the <b>test</b> command without these 
records and then add them if it requests you to do so.
Normally, you will also want <b>mt -f /dev/nsa0 comp on</b> to be
set.


<h3>Using btape to Simulate Bacula Filling a Tape</h3>
Because there are often problems with certain tape drives
or systems when end of tape conditions occur, <b>btape</b>
has a special command <b>fill</b> that causes it to write
random data to a tape until the tape fills. It then writes
at least one more <b>Bacula</b> block to a second tape.   
Finally, it reads back both tapes to ensure that the data
has been written in a way that <b>Bacula</b> can recover it.
<p>
This can be an extremely time consuming process (here is
is about 6 hours), and you must have two blank tapes available.
As this command is completely new, it is not well tested, and
has considerable room for improvement, especially during
the error checking in the read-back phase.
<p>
To begin this test, you enter the <b>fill</b> command and
follow the instructions.  

<h2>Tape Blocking Modes</h2>
SCSI tapes may either be written in <b>variable</b> or <b>fixed</b>
block sizes. Newer drives support both modes, but some drives such
as the QIC devices always use fixed block sizes. Bacula
attepts to fill and write complete blocks (default 65K), so
that in normal mode (variable block size), Bacula will always
write blocks of the same size except the last block of a Job.
If Bacula is configured to write fixed block sizes, it will pad
the last block of the Job to the correct size.

Bacula expects variable tape block size drives to behave as follows:
Each write to the drive results in a single record being written to the
tape.  Each read returns a single record.  If you request less byte than
are in the record, only those number of bytes will be returned, but the
entire logical record will have been read (the next read will retrieve
the next record).  Thus data from a single write is always returned in a
single read, and sequentially written records are returned by
sequential reads.
<p>
Bacula expects fixed block size tape drives to behave as follows:
If a write length is greater than the physical block size of the
drive, the write will be written as two blocks each of the fixed
physical size. This a single write may become multiple physical
records on the tape. (This is not a good situation). According to
the documentation, one may never write an amount of data that is not the
exact multipe  of the blocksize (it is not specified if an error occurs
or if the the last record is padded). When reading, it is my understanding
that each read request reads one physical record from the tape.  Due
to the complications of fixed block size tape drives, you should
avoid them if possible with Bacula, or you must be ABSOLUTELY certain
that you use fixed block sizes within Bacula that correspond to
the physical block size of the tape drive.  This will ensure that
Bacula has a one to one correspondence between what it writes and
the physical record on the tape.
<p>
Please note that Bacula will not function correctly if it writes
a block and that block is split into two or more physical records
on the tape. Bacula assumes that each write causes a single record
to be written, and that it can sequentially recover each of the
blocks it has written by using the same number of sequential reads
as it had written.


<hr>

<page_prev name="Utility Programs" url="progs.html">
<page_next name="When Bacula crashes (Kaboom)" url="kaboom.html">
