git.gag.com Git - debian/amanda/blob - docs/chg-scsi.notes

   1 CHG-SCSI
   2
   3 Jason's new and improved chg-scsi documentation.  this documentation
   4 will also include an occasional reference to the mtx suite as I have
   5 attempted to use chg-zd-mtx.  I use mtx often as a fast query tool.
   6 Please also refer to docs/TAPE.CHANGERS for additional details.
   7
   8 My equipment list is as follows:
   9         Redhat 7.0 machine
  10                 - dual processor p-III
  11                 - sony dds3 tape drive
  12                 - lots of hard disk space
  13                 - Quantum/ATL L500 scsi changer
  14                         1 DLT tape drive (three possible)
  15                         barcode reader
  16                         fourteen tape slots
  17
  18 I base this documentation on the following:
  19         mtx version 1.2.16rel
  20         amanda version 2.4.3b3
  21         SCSI2 specification: X3T9.2/375R revision 10L
  22         Quantum/ATL Field Service Manual 6321101-03 Ver.3, rel.0
  23         Quantum dlt800 Tape system product manual 02 April, 2001 81-60118-04
  24         the SCSI bus and IDE interface 2nd ed by Friedhelm Schmidt
  25                 pub: Addision Wesley 1998
  26
  27 Note that quantum/atl's L-series changers follow the scsi command set,
  28 and do not use any proprietary commands.  thus, it was fairly simple to
  29 make this work.
  30
  31 I had to install amanda --with-suffixes and setup my server's client
  32 side of things using amanda-2.4.2p2 --with-suffixes.
  33
  34 Please note that my usage of "barcode" and "barcode reader" throughout
  35 this document really refers to "physical tape identification system".
  36 for example: the EEPROM in the AIT cartridge .
  37
  38 ------------------------
  39 command line options:
  40
  41 chg-scsi's command line options:
  42         -slot <param>
  43         -info
  44         -reset
  45         -eject
  46         -clean
  47         -label <param>
  48         -search <param>
  49         -status <param>
  50         -trace <param>
  51         -inventory
  52         -dumpdb
  53         -scan
  54         -genconf
  55
  56
  57 Note that chg-scsi is called by amanda in the context of whatever amanda
  58 configuration amanda is currently using.  In short, to call chg-scsi by
  59 hand, change to your amanda configuration directory, then run chg-scsi.
  60
  61 -slot <param> command:
  62
  63         this command takes either a slot number, or any one of the
  64         following:
  65                 current, next, prev, first, last, advance
  66
  67         It then loads the appropriate tape into the drive.
  68
  69         Note that if the tape is already loaded, no changer motion will
  70         happen.  No reading of the tape is done here.
  71
  72 -info command:
  73
  74         four numbers are printed:
  75         <slot# loaded> <number of slots> <reversable> <searchable>
  76
  77         with chg-scsi, the reversable number is always 1.  Searchable is
  78         set based on if a barcode reader is available and working
  79         correctly.
  80
  81 -reset command:
  82
  83         Tape is unloaded, and slot 0 is loaded.  No actual reset command
  84         is sent to the changer.
  85
  86 -eject command:
  87
  88         Tape is unloaded, and put back into its original slot.
  89
  90 -clean command:
  91
  92         Cleaning tape (if configured) is loaded into the tape.  It is
  93         probably unloaded when done.  I haven't looked closely at this
  94         yet.
  95
  96 -label <param> command:
  97
  98         This appears to take the currently loaded tape's barcode and
  99         write it to the labelfile with the given parameter as it's tape
 100         header.  I have not tested this.
 101
 102 -search <param> command:
 103
 104         this only should be used if a barcode reader is present, or
 105         emulate barcode is turned on.
 106
 107         the required parameter is an amanda tape label.  the label
 108         searched in the labelfile.  If a barcode is found, then that
 109         tape is loaded directly.
 110
 111         I believe the fallback is to search the entire magazine.
 112
 113 -status command:
 114
 115         the tape changer is queried, and the results are printed out.
 116         Values printed are what slots exist, are they full or empty, and
 117         what volume labels (barcodes) they are.
 118                 Q. what about changers that don't retain current slot?
 119                 A. this is what the "statfile" is for.
 120
 121 -trace command:
 122
 123         present only for a particular type of changer.
 124
 125 -inventory:  (this takes a LONG time to do)
 126
 127         1) unloads tape back to its slot
 128         2) issues command to changer to do an inventory of itself (read all
 129                 barcodes...)
 130         3) loads each tape, retrieves the barcode, and reads the amanda
 131                 label off of the tape itself
 132         4) stores/updates the label database file
 133
 134 -dumpdb:
 135
 136         prints out in human readable form the label database contents
 137         from the labelfile.
 138
 139 -scan:  (aka scanbus)
 140         scans the scsi generic interfaces (eg: linux sg), and prints out the
 141         device name and the device types.  I found that linux didn't
 142         classify either of my tape devices as generic, but this facility
 143         did.  USE THIS FOR FINDING VALUE OF scsitapedev.  Be certain
 144         though you have the correct tape drive: I came close to wreaking
 145         havoc with my dds3 drive while it was flushing amanda data...and
 146         my changer has a DLT drive!  Please refer to my configuration
 147         notes below.
 148
 149 -genconf:
 150
 151         prints out a SAMPLE changer.conf file.  Note that I said sample.
 152         except for that it also does a scanbus.  if you have more than
 153         one tape drive, please be certain it is correct as chg-scsi uses
 154         the first one it finds.
 155
 156         Please refer to my configuration notes below.
 157
 158 --------------------------------------------
 159
 160 changer.conf notes:
 161
 162 Here, I try to be a bit more clear on what these config values mean.
 163
 164 "number_configs" MUST be the first entry (not counting comments)
 165
 166 "emubarcode" will set this value in chg-scsi regardless of the value you
 167 try to assign it.  If you don't want "emubarcode" set, don't list it!
 168
 169 "havebarcode"
 170         have barcode is tempered by what devices chg-scsi is aware of.
 171         if chg-scsi doesn't know about your changer explicitly, it will
 172         default to a default changer.  the default changer has no
 173         barcode reader.
 174
 175         In a patch I plan to post, I have added a generic changer that
 176         does use a barcode.  set "changerident" to "genericbarcode" to
 177         use this.
 178
 179 "sleep"
 180         number of seconds for chg-scsi to wait for a "tape drive ready"
 181         command after loading a new tape.  Mine is 140 as I have a DLT
 182         tape drive, and my tape drive manual reports a max of 133
 183         seconds to be ready.
 184
 185 "config"
 186         this is a header telling chg-scsi that all values following, up
 187         to the next "config" line apply to this drive number.  It is
 188         this number that is refered to in your amanda.conf file as line
 189         "tapedev"
 190
 191 "drivenum"
 192         this is the tape drive number in your changer.  for a single
 193         tape drive, this is zero.  Mine can handle up to three, so I
 194         expect I could make this 0, 1, or 2.
 195
 196 "dev"
 197         the scsi device of your tape drive.  under linux, in my case
 198         it is /dev/nst1.  This MUST be defined.
 199
 200 "scsitapedev"
 201         the generic scsi device of your tape drive.  this is simply the
 202         generic interface to the device "dev" above.  This entry is
 203         optional.  In my case, it is /dev/sg2.  If this entry exists and
 204         is legitimate, then scsi commands are formed directly instead of
 205         using ioctl commands.
 206
 207 "startuse"
 208 "enduse"
 209         the start and end slots of your changer.  Note that these also
 210         start with zero.
 211
 212 "eject"
 213         chg-scsi tells the tape changer to eject.  You might need to
 214         explicitly tell the tape drive to unload first.  that's what
 215         this setting is for.  Have you ever removed a loaded VCR tape
 216         by hand?
 217
 218 "changerident"
 219         chg-scsi will first read the changer's identification from the
 220         return of the scsi "inquiry" command.  If changerident is set in
 221         the configuration file, the scsi inquiry's value is overridden.
 222         chg-scsi will attempt to match the value with its built-in
 223         changertypes.
 224
 225         "generic" is what the chg-scsi will default to
 226         "genericbarcode" is a hack of mine that forces the changer's
 227                 barcode reader to work.  Note that if your changer
 228                 uses a superset of the scsi command set, this probably
 229                 won't work.
 230         "L500" is another addition of mine that will enable a
 231                 quantum/atl L500 to work correctly.  It might even work
 232                 with an L200.
 233
 234         other values are (taken from the code)
 235                 C1553A (HP Auto Loader)
 236                 EXB-10e, EXB-120 (Exabyte Robot)
 237                 EXB-85058HE-0000 (Exabyte Tape)
 238                 TDS 1420 (Tandberg Robot)
 239                 VLS DLT, VLS SDX (ADIC VLS DLT Library)
 240                 FastStor DLT (ADIC FastStor DLT Library)
 241                 Scalar DLT 448 (ADIC DLT 448)
 242                 215 (Spectra Logic TreeFrog)
 243                 Quad 7 (Breece Hill)
 244                 DLT7000, DLT4000 (DLT Tape)
 245
 246 "debuglevel"
 247         setting this to "9:0" is very informative.
 248
 249 "statfile"
 250         stores which "slot" that the tape in the drive came from
 251
 252 "labelfile"
 253         binary file that stores the tape header and barcode information
 254
 255 cleanmax
 256 cleancart
 257 cleanfile
 258         I have my changer set to autoclean, and the slot the cleaning
 259         cartridge is in is not available for any other use.
 260
 261
 262 -----------------------------------------------
 263
 264 Amanda's actual usage of chg-scsi
 265
 266 this should be brief:
 267         amanda really only issues "slot next" type commands.  currently
 268         amanda doesn't ask chg-scsi to load "tape x with label
 269         Daily_set023".  the chg-scsi mechanism is there for use, and
 270         functions quite well for the user to load a particular tape.
 271         I understand they (the amanda team) is working on this.
 272
 273 -----------------------------------------------
 274
 275 Configuration notes:
 276
 277         (assuming one changer with one tape drive!)
 278
 279 in "amanda.conf":
 280
 281         set tpchanger to chg-scsi
 282         set changerfile to <pathname>/changer.conf
 283         set tapedev to 0
 284         set changerdev to /dev/<changer generic device>
 285                 - this value is usually listed in the system boot
 286                   messages or will be printed via syslog when the
 287                   appropriate kernel module is loaded.
 288                         eg: linux "modprobe sg"
 289
 290 in changer.conf:
 291         set number_configs to 1
 292         set dev to <non-rewinding tape device eg: /dev/nst1>
 293         set debug to 9:0
 294
 295 run "chg-scsi -scan" from your amanda configuration directory
 296         I get:
 297                 name /dev/sg0 Tape
 298                 Count 1
 299                 name /dev/sg1 Changer
 300                 Count 2
 301                 name /dev/sg2 Tape
 302                 Count 3
 303
 304         I set scsitapedev to "/dev/sg0" to test with, then ran "chg-scsi
 305         -info".  check the chg-scsi debug file for tapeidentification
 306         details.  this is where I discoverd that "sg0" was not the
 307         correct tape!
 308
 309         set scsitapedev to "/dev/<generic device>"
 310
 311         if you have no barcode, try "changerident generic"
 312         if you have a barcode reader try "changerident genericbarcode"
 313
 314
 315
 316 -----------------------------------------------
 317
 318 Hacking notes:
 319
 320 my hacks are:
 321         adding printout of "emubarcode" values in the debug file
 322
 323         added dlt8000 tape drive to ChangerIO[], and SenseType[]
 324         added genericbarcode to ChangerIO[], and SenseType[]
 325         added L500 to ChangerIO[], and SenseType[]
 326
 327
 328         added a couple of basic sensecodes listed in the scsi specs for
 329         the generic and genericbarcode tape changers.
 330
 331
 332
 333 My desires are:
 334         modify the sensecode code such that all scsi devices inherit the
 335         standard scsi codes and may override or append to them as
 336         needed.
 337
 338         modify the configuration reading code and the "inquiry" command
 339         to allow spaces.
 340                 eg: my changer displays the following ident data:
 341                 "L500   6320000" but I had to create a type called "L500"
 342                 or else the spaces would throw off the comparisons.
 343