Chg-scsi

From The Open Source Backup Wiki (Amanda, MySQL Backup, BackupPC)
Jump to navigationJump to search
Deprecated
This changer is deprecated; see amanda-changers(7)


This is "Jason's new and improved chg-scsi documentation", written by an unknown contributor, and replicated here in the hopes it can be useful.

This documentation will also include an occasional reference to the mtx suite as I have attempted to use chg-zd-mtx. I use mtx often as a fast query tool. Please also refer to Amanda_Tape_Changer_Support for additional details. My equipment list is as follows:

  • Redhat 7.0 machine
    • Dual Processor P-III
    • Sony DDS3 tape drive
    • lots of hard disk space
  • Quantum/ATL L500 SCSI changer
  • DLT tape drive (three possible)
  • barcode reader fourteen tape slots

I base this documentation on the following:

  • mtx version 1.2.16rel
  • Amanda version 2.4.3b3
  • SCSI2 specification: X3T9.2/375R revision 10L
  • Quantum/ATL Field Service Manual 6321101-03 Ver.3, rel.0
  • Quantum DLT800 Tape system product manual 02 April, 2001 81-60118-04
  • the SCSI bus and IDE interface 2nd ed by Friedhelm Schmidt pub: Addison- Wesley 1998

Note that Quantum/ATL's L-series changers follow the SCSI command set, and do not use any proprietary commands. Thus, it was fairly simple to make this work. I had to install Amanda --with-suffixes and setup my server's client side of things using Amanda-2.4.2p2 --with-suffixes.

Please note that my usage of "barcode" and "barcode reader" throughout this document really refers to "physical tape identification system". for example: the EEPROM in the AIT cartridge.

Command line options

chg-scsi's command line options:

 -slot <param>
 -info
 -reset
 -eject
 -clean
 -label <param>
 -search <param>
 -status <param>
 -trace <param>
 -inventory
 -dumpdb
 -scan
 -genconf

Note that chg-scsi is called by Amanda in the context of whatever Amanda configuration Amanda is currently using. In short, to call chg-scsi by hand, change to your Amanda configuration directory, then run chg-scsi.

-slot <param> command

this command takes either a slot number, or any one of the following: current, next, prev, first, last, advance. It then loads the appropriate tape into the drive. Note that if the tape is already loaded, no changer motion will happen. No reading of the tape is done here.

-info command

four numbers are printed: <slot# loaded> <number of slots> <reversable> <searchable> with chg-scsi, the reversable number is always 1. Searchable is set based on if a barcode reader is available and working correctly.

-reset command

Tape is unloaded, and slot 0 is loaded. No actual reset command is sent to the changer.

-eject command

Tape is unloaded, and put back into its original slot.

-clean command

Cleaning tape (if configured) is loaded into the tape. It is probably unloaded when done. I haven't looked closely at this yet.

-label <param> command

This appears to take the currently loaded tape's barcode and write it to the labelfile with the given parameter as it's tape header. I have not tested this.

-search <param> command

this only should be used if a barcode reader is present, or emulate barcode is turned on. the required parameter is an Amanda tape label. The label searched in the labelfile. If a barcode is found, then that tape is loaded directly. I believe the fallback is to search the entire magazine.

-status command

The tape changer is queried, and the results are printed out. Values printed are what slots exist, are they full or empty, and what volume labels (barcodes) they are. Q. what about changers that don't retain current slot? A. this is what the "statfile" is for.

-trace command

present only for a particular type of changer.

-inventory

(this takes a LONG time to do) unloads tape back to its slot issues command to changer to do an inventory of itself (read all barcodes...) loads each tape, retrieves the barcode, and reads the Amanda label off of the tape itself stores/updates the label database file

-dumpdb

prints out in human readable form the label database contents from the labelfile. -scan: (aka scanbus) scans the SCSI generic interfaces (eg: linux sg), and prints out the device name and the device types. I found that linux didn't classify either of my tape devices as generic, but this facility did. USE THIS FOR FINDING VALUE OF SCSItapedev. Be certain though you have the correct tape drive: I came close to wreaking havoc with my DDS3 drive while it was flushing Amanda data...and my changer has a DLT drive! Please refer to my configuration notes below.

-genconf

prints out a SAMPLE changer.conf file. Note that I said sample. except for that it also does a scanbus. if you have more than one tape drive, please be certain it is correct as chg-scsi uses the first one it finds. Please refer to my configuration notes below.

Notes about changer.conf

Here, I try to be a bit more clear on what these config values mean.

  • "number_configs" MUST be the first entry (not counting comments)
  • "emubarcode" will set this value in chg-scsi regardless of the value you try to assign it. If you don't want "emubarcode" set, don't list it!
  • "havebarcode" have barcode is tempered by what devices chg-scsi is aware of. if chg-scsi doesn't know about your changer explicitly, it will default to a default changer. the default changer has no barcode reader. In a patch I plan to post, I have added a generic changer that does use a barcode. set "changerident" to "genericbarcode" to use this.
  • "sleep" number of seconds for chg-scsi to wait for a "tape drive ready" command after loading a new tape. Mine is 140 as I have a DLT tape drive, and my tape drive manual reports a max of 133 seconds to be ready.
  • "config" this is a header telling chg-scsi that all values following, up to the next "config" line apply to this drive number. It is this number that is refered to in your amanda.conf file as line tapedev
  • "drivenum" this is the tape drive number in your changer. For a single tape drive, this is zero. Mine can handle up to three, so I expect I could make this 0, 1, or 2.
  • "dev" the SCSI device of your tape drive. under linux, in my case it is /dev/ nst1. This MUST be defined.
  • "SCSItapedev" The generic SCSI device of your tape drive. this is simply the generic interface to the device "dev" above. This entry is optional. In my case, it is /dev/sg2. If this entry exists and is legitimate, then SCSI commands are formed directly instead of using ioctl commands.
  • "startuse" "enduse" The start and end slots of your changer. Note that these also start with zero.
  • "eject" chg-scsi tells the tape changer to eject. You might need to explicitly tell the tape drive to unload first. That's what this setting is for. Have you ever removed a loaded VCR tape by hand?
  • "changerident" chg-scsi will first read the changer's identification from the return of the SCSI "inquiry" command. If changerident is set in the configuration file, the SCSI inquiry's value is overridden. chg-scsi will attempt to match the value with its built-in changertypes.
  • "generic" is what the chg-scsi will default to "genericbarcode" is a hack of mine that forces the changer's barcode reader to work. Note that if your changer uses a superset of the SCSI command set, this probably won't work.
  • "L500" is another addition of mine that will enable a quantum/atl L500 to work correctly. It might even work with an L200. other values are (taken from the code)
    • C1553A (HP Auto Loader)
    • EXB-10e, EXB-120 (Exabyte Robot)
    • EXB-85058HE-0000 (Exabyte Tape)
    • TDS 1420 (Tandberg Robot)
    • VLS DLT, VLS SDX (ADIC VLS DLT Library)
    • FastStor DLT (ADIC FastStor DLT Library)
    • Scalar DLT 448 (ADIC DLT 448)
    • 215 (Spectra Logic TreeFrog)
    • Quad 7 (Breece Hill)
    • DLT7000, DLT4000 (DLT Tape)
  • "debuglevel" setting this to "9:0" is very informative. "statfile" stores which "slot" that the tape in the drive came from "labelfile" binary file that stores the tape header and barcode information cleanmax cleancart cleanfile I have my changer set to autoclean, and the slot the cleaning cartridge is in is not available for any other use.

Amanda's actual usage of chg-scsi

this should be brief: Amanda really only issues "slot next" type commands. Currently Amanda doesn't ask chg-scsi to load "tape x with label Daily_set023". the chg-scsi mechanism is there for use, and functions quite well for the user to load a particular tape. I understand they (the Amanda team) are working on this.

Configuration notes

(assuming one changer with one tape drive!)

in amanda.conf:

  • set tpchanger to chg-scsi set changerfile to <pathname>/changer.conf set tapedev to 0 set changerdev to /dev/<changer generic device>
    • this value is usually listed in the system boot messages or will be printed via syslog when the appropriate kernel module is loaded. eg: linux modprobe sg

in changer.conf:

  • set number_configs to 1 set dev to <non-rewinding tape device, eg: /dev/nst1>
  • set debug to 9:0
  • run "chg-scsi -scan" from your Amanda configuration directory I get: name /dev/ sg0 Tape Count 1 name /dev/sg1 Changer Count 2 name /dev/sg2 Tape Count 3
  • I set SCSItapedev to /dev/sg0 to test with, then ran chg-scsi -info. Check the chg-scsi debug file for tapeidentification details. This is where I discoverd that "sg0" was not the correct tape!
  • set SCSItapedev to "/dev/<generic device>"
  • if you have no barcode, try "changerident generic" if you have a barcode reader try "changerident genericbarcode"

Hacking notes

My hacks are:

  • adding printout of "emubarcode" values in the debug file
  • added dlt8000 tape drive to ChangerIO[], and SenseType[]
  • added genericbarcode to ChangerIO[], and SenseType[]
  • added L500 to ChangerIO[], and SenseType[]
  • added a couple of basic sensecodes listed in the SCSI specs for the generic and genericbarcode tape changers.

My desires are:

  • modify the sensecode code such that all SCSI devices inherit the standard SCSI codes and may override or append to them as needed.
  • modify the configuration reading code and the inquiry command to allow spaces. eg: my changer displays the following ident data: "L500 6320000" but I had to create a type called "L500" or else the spaces would throw off the comparisons.

OLD Documentation

The following is the "old" documentation that "Jason" replaced.

The config and the syntax is the same as for chg-scsi-chio. New is the config type

emubarcode 1

With this option and the option labelfile chg-scsi will try to create an inventory. With this inventory it should be possible to use the search feature for loading tapes.

debuglevel x:y

This option will set the debug level and select for which part debug messages should be sent to the debug file. In case of problems you should set it to 9:0

havebarcode 1

This will force the program to read the barcodes, and don not try to figure out if there is an barcode reader available.

scsitapedev <devicename>

This device is used to control the tape, read status infos etc.

tapestatus <filename>

If this option is given on every eject/move the log pages of the tape device will be dumped in this file. There are 2 log pages were you can see how many read/write errors (corrected) are processed by the tape

labelfile <filename>

This file is used for the mapping from barcode labels to AMANDA volume labels. It is used if the changer has a barcode reader. To initialize run amtape show, this will add the mapping for the tapes in the magazine.

eject > 1

Use the mtio ioctl to eject the tape, use only if the standard (1) does not work, and send the debug output (/tmp/amanda/chg-scsi.debug) to [email protected]

changerident <ident>

With this it is possible to specify which internal driver to use for controlling/error handling of the robot

tapeident <ident>

Same as above but for the tape.

New command line option: -status [all|types|robot|sense|ModeSenseRobot|ModeSenseTape|fd]

<all> will show the result form all options. <types> will list the known driver types. <robot> will show the status of all elements (tape/robot/slots..) <sense> will show the result from a request sense <ModeSenseRobot> will show the sense page from the robot <ModeSenseTape> will show the sense page from the tape <fd> will show the devices which are open, and some info about it.

At the moment changer with tape and robot on the same SCSI id ( but on different luns) will run on the following platforms:

  • HP_UX 10.20
  • IRIX 6.x
  • Solaris
  • Linux
  • AIX
  • FreeBSD 3.0/4.0

Tape and robot on different IDs run native on

  • Linux
  • HP-UX 10.20
  • Irix 6.x
  • FreeBSD

Solaris

Tape and robot on different IDs with special modules run on: Solaris with sst kernel module, which is not any longer needed in solaris 2.8. See in the contrib/sst directory The configuration on solaris 2.8 with the sgen driver is done by creating the file /kernel/drv/sgen.conf

This file should contain at the beginning the following device-type-config-list="changer","sequential"

This will force the driver to attach only to the devices with type either changer (the robot) and sequential (the tape). Next you must tell the driver on which id it should check for devices (tape on id 5, robot on id 6 in this example),

name="sgen" class="scsi" target=5 lun=0; name="sgen" class="scsi" target=6 lun=0;

This will create the 2 device files /dev/scsi/sequential/c0t5d0 (scsitapedev option in chg-scsi.conf) /dev/scsi/changer/c0t6d0 (changer option in chg-scsi.conf)

So the complete sgen.conf looks like: device-type-config-list="changer","sequential name="sgen" class="scsi" target=5 lun=0; name="sgen" class="scsi" target=6 lun=0;

HP

You have to create the special device files for the pass throu interface. Check if the ctl driver is installed. Example:

# lsdev -C ctl
 Character     Block       Driver          Class
    203          -1         sctl            ctl

Next check on which bus your drives are connected. (ioscan) with the Character device num form the lsdev and the card instance from ioscan create the special file. Example:

mknod /dev/scsi/1 c 203 0x001000
                          ||||
                          ||| LUN of device
                          ||SCSI ID of the device
                          2 digit instance number from ioscan

FreeBSD 4.0

The syntax for the device files has changed. Now you have to tell chg-scsi the bus:target:lun combination. If you for example on your scsi bus 0 target 3 an robot the syntax is changerdev 0:3:0 To get this info you can use the camcontrol command, <camcontrl devlist> will give you a list of known devices. Don't specify dev and scsitapedev in your chg-scsi.conf !!, this will not work.

Linux

You need either sg (generic scsi) as module or it must be compiled into the kernel. If the sg driver doses not work try to use the ioctl interface. For that you have to undef the LINUX_CHG define in changer-src/scsi-linux.c Also you have to change the NORMAL_TIMEOUT in /usr/src/linux/drivers/scsi/scsi_ioctl.c from (10 * HZ) to (5 * 60 * HZ). On linux it does not run if you are using an aha1542 SCSI controller. The driver can not handle the extended request sense.

IRIX

You find the SCSI pass through interfaces for every device in /dev/scsi.

chg-scsi has been tested/run with the following devices: Exabyte 10h and eliant tape HP-Surestore 1200e and C1553A tape BreeceHill Q2.15 (EXB-120) and DLT7000 tape Powerstor L200 and DLT7000 ARCHIVE Python 28849-XXX TANDBERG TDS 1420 ADIC VLS DLT Library

It is now possible with a changer that has barcode reader to load tapes faster. Also amdump will find tapes faster. Every time a tape is labeled the information in the labelfile will be updated. To initialize the label mapping you can also do an amtape config show. This will put the mapping for all tapes in the magazine into the mapping file.

For all problems please contact [email protected]. Please include in your mail the debug file. (/tmp/amanda/chg-scsi.debug)