git.gag.com Git - debian/mtx/blob - mtx.1

   1 .\" mtx.1  Document copyright 2000 Eric Lee Green
   2 .\"  Program Copyright 1996, 1997 Leonard Zubkoff
   3 .\"  Copyright 2007-2008 by Robert Nelson <robertn@the-nelsons.org>
   4 .\"  Extensive changes 2000 by Eric Lee Green <eric@badtux.org>
   5 .\"
   6 .\" This is free documentation; you can redistribute it and/or
   7 .\" modify it under the terms of the GNU General Public License as
   8 .\" published by the Free Software Foundation; either version 2 of
   9 .\" the License, or (at your option) any later version.
  10 .\"
  11 .\" The GNU General Public License's references to "object code"
  12 .\" and "executables" are to be interpreted as the output of any
  13 .\" document formatting or typesetting system, including
  14 .\" intermediate and printed output.
  15 .\"
  16 .\" This manual is distributed in the hope that it will be useful,
  17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 .\" GNU General Public License for more details.
  20 .\"
  21 .\" You should have received a copy of the GNU General Public
  22 .\" License along with this manual; if not, write to the Free
  23 .\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
  24 .\" USA.
  25 .\"
  26 .TH MTX 1 MTX1.3
  27 .SH NAME
  28 mtx \- control SCSI media changer devices
  29 .SH SYNOPSIS
  30 mtx [-f <scsi-generic-device>] [nobarcode] [invert] [noattach] command [ command ... ]
  31 .SH DESCRIPTION
  32 The
  33 .B mtx
  34 command controls single or multi-drive SCSI media changers such as
  35 tape changers, autoloaders, tape libraries, or optical media jukeboxes.
  36 It can also be used with media changers that use the 'ATTACHED' API,
  37 presuming that they properly report the MChanger bit as required
  38 by the SCSI T-10 SMC specification.
  39 .SH OPTIONS
  40 The first argument, given following
  41 .B -f
  42 , is the SCSI generic device corresponding to your media changer.
  43 Consult your operating system's documentation for more information (for
  44 example, under Linux these are generally /dev/sg0 through /dev/sg15,
  45 under FreeBSD these are /dev/pass0 through /dev/passX,
  46 under SunOS it may be a file under /dev/rdsk).
  47 .P
  48 The 'invert' option will invert (flip) the media (for optical jukeboxes that
  49 allow such) before inserting it into the drive or returning it to the
  50 storage slot.
  51 .P
  52 The 'noattach' option forces the regular media changer API even if the
  53 media changer incorrectly reported that it uses the 'ATTACHED' API.
  54 .P
  55 The 'nobarcode' option forces the loader to not request barcodes even if
  56 the loader is capable of reporting them.
  57 .P
  58 Following these options there may follow
  59 one or more robotics control
  60 commands. Note that the 'invert' and 'noattach'
  61 options apply to ALL of robotics control
  62 commands.
  63
  64 .SH COMMANDS
  65 .TP 10
  66 .B --version
  67 Report the mtx version number (e.g. mtx 1.2.8) and exit.
  68
  69 .TP 10
  70 .B inquiry
  71 Report the product type (Medium Changer, Tape Drive, etc.), Vendor ID,
  72 Product ID, Revision, and whether this uses the Attached Changer API
  73 (some tape drives use this rather than reporting a Medium Changer on a
  74 separate LUN or SCSI address).
  75 .TP 10
  76 .B noattach
  77 Make further commands use the regular media changer API rather than the
  78 _ATTACHED API, no matter what the "Attached" bit said in the Inquiry info.
  79 Needed with some brain-dead changers that report Attached bit but don't respond
  80 to _ATTACHED API.
  81 .TP 10
  82 .B inventory
  83 Makes the robot arm go and check what elements are in the slots. This
  84 is needed for a few libraries like the Breece Hill ones that do not
  85 automatically check the tape inventory at system startup.
  86 .TP 10
  87 .B status
  88 Reports how many drives and storage elements are contained in the
  89 device. For each drive, reports whether it has media loaded in it, and
  90 if so, from which storage slot the media originated. For each storage
  91 slot, reports whether it is empty or full, and if the media changer
  92 has a bar code, MIC reader, or some other way of uniquely identifying
  93 media without loading it into a drive, this reports the volume tag
  94 and/or alternate volume tag for each piece of media.
  95 For historical reasons drives are numbered from 0 and storage slots are
  96 numbered from 1.
  97 .TP 10
  98 .B load <slotnum> [ <drivenum> ]
  99 Load media from slot <slotnum> into drive <drivenum>. Drive 0 is assumed
 100 if the drive number is omitted.
 101 .TP 10
 102 .B unload [<slotnum>] [ <drivenum> ]
 103 Unloads media from drive <drivenum> into slot <slotnum>. If <drivenum> is
 104 omitted, defaults to drive 0 (as do all commands).
 105 If <slotnum> is omitted, defaults to the slot
 106 that the drive was loaded from. Note that there's currently no way to
 107 say 'unload drive 1's media to the slot it came from', other than to
 108 explicitly use that slot number as the destination.
 109 .TP 10
 110 .B [eepos <operation>] transfer <slotnum> <slotnum>
 111 Transfers media from one slot to another, assuming that your mechanism is
 112 capable of doing so. Usually used to move media to/from an import/export
 113 port. 'eepos' is used to extend/retract the import/export
 114 tray on certain mid-range to high end tape libraries (if, e.g., the tray was
 115 slot 32, you might say say 'eepos 1 transfer 32 32' to extend the tray).
 116 Valid values for eepos <operation>
 117 are 0 (do nothing to the import/export tray), 1, and 2 (what 1 and 2 do varies
 118 depending upon the library, consult your library's SCSI-level
 119 documentation).
 120 .TP 10
 121 .B [eepos <operation>] [invert] [invert2] exchange <slotnum> <slotnum> [<slotnum>]
 122 Move medium from the first slot to the second slot, placing the medium
 123 currently in the second slot either back into the first slot or into the
 124 optional third slot.
 125
 126 .TP 10
 127 .B first  [<drivenum>]
 128 Loads drive <drivenum> from the first slot in the media
 129 changer. Unloads the drive if there is already media in it (note: you
 130 may need to eject the tape using your OS's tape control commands
 131 first).  Note that this command may not be what you want on large
 132 tape libraries -- e.g. on Exabyte 220, the first slot is usually a
 133 cleaning tape. If <drivenum> is omitted, defaults to first drive.
 134
 135 .TP 10
 136 .B last [<drivenum>]
 137 Loads drive <drivenum> from the last slot in the media changer. Unloads
 138 the drive if there is already a tape in it. (Note: you may need to eject
 139 the tape using your OS's tape control commands first).
 140 .TP 10
 141 .B next [<drivenum>]
 142 Unloads the drive and loads the next tape in sequence. If the drive was
 143 empty, loads the first tape into the drive.
 144 .TP 10
 145 .B position <slotnum>
 146 Positions the robot at a specific slot. Needed by some changers to
 147 move to and open the import/export, or mailbox, slot.
 148
 149 .SH AUTHORS
 150 The original 'mtx' program was written by Leonard Zubkoff and extensively
 151 revised for large multi-drive libraries with bar code readers
 152 by Eric Lee Green <eric@badtux.org>. See 'mtx.c' for other contributors.
 153 .SH BUGS AND LIMITATIONS
 154 .P
 155 You may need to do a 'mt offline' on the tape drive to eject the tape
 156 before you can issue the 'mtx unload' command. The Exabyte EZ-17 and 220
 157 in particular will happily sit there snapping the robot arm's claws around
 158 thin air trying to grab a tape that's not there.
 159 .P
 160 For some Linux distributions, you may need to re-compile the kernel to
 161 scan SCSI LUN's in order to detect the media changer. Check /proc/scsi/scsi
 162 to see what's going on.
 163 .P
 164 If you try to unload a tape to its 'source' slot, and said slot is
 165 full, it will instead put the tape into the first empty
 166 slot. Unfortunately the list of empty slots is not updated between
 167 commands on the command line, so if you try to unload another drive to
 168 a full 'source' slot during the same invocation of 'mtx', it will try
 169 to unload to the same (no longer empty) slot and will urp with a SCSI
 170 error.
 171 .P
 172
 173 This program reads the Mode Sense Element Address Assignment Page
 174 (SCSI) and requests data on all available elements. For larger
 175 libraries (more than a couple dozen elements)
 176 this sets a big Allocation_Size in the SCSI command block for the
 177 REQUEST_ELEMENT_STATUS command in order to be able to read the entire
 178 result of a big tape library. Some operating systems may not be able
 179 to handle this. Versions of Linux earlier than 2.2.6, in particular,
 180 may fail this request due to inability to find contiguous pages of
 181 memory for the SCSI transfer (later versions of Linux 'sg' device do
 182 scatter-gather so that this should no longer be a problem).
 183 .P
 184 The
 185 .B eepos
 186 command remains in effect for all further commands on a command
 187 line. Thus you might want to follow
 188 .B eepos 1 transfer 32 32
 189 with
 190 .B eepos 0
 191 as
 192 the next command (which clears the
 193 .B eepos
 194 bits).
 195 .P
 196 Need a better name for 'eepos' command! ('eepos' is the name of the bit
 197 field in the actual low-level SCSI command, and has nothing to do with what
 198 it does).
 199 .P
 200
 201 This program has only been tested on Linux with a limited number of
 202 tape loaders (a dual-drive Exabyte 220 tape library, with bar-code
 203 reader and 21 slots, an Exabyte EZ-17 7-slot autoloader, and a Seagate
 204 DDS-4 autochanger with 6 slots). It may not work on other operating systems
 205 with larger libraries,
 206 due to the big SCSI request size.
 207 Please see the projecdt page http://sourceforge.net/projects/mtx for information
 208 on reporting bugs, requesting features and the mailing list for peer support.
 209 .SH HINTS
 210 Under Linux,
 211 .B cat /proc/scsi/scsi
 212 will tell you what SCSI devices you have.
 213 You can then refer to them as
 214 .B /dev/sga,
 215 .B /dev/sgb,
 216 etc. by the order they
 217 are reported.
 218 .P
 219 Under FreeBSD,
 220 .B camcontrol devlist
 221 will tell you what SCSI devices you
 222 have, along with which
 223 .B pass
 224 device controls them.
 225 .P
 226 Under Solaris, set up your 'sgen' driver so that it'll look for
 227 tape changers (see /kernel/drv/sgen.conf and the sgen man page), type
 228 .B touch /reconfigure
 229 then reboot. You can find your changer in /devices by typing
 230 .B /usr/sbin/devfsadm -C
 231 to clean out no-longer-extant entries in your /devices directory, then
 232 .B find /devices -name \e\(**changer -print
 233 to find the device name. Set the symbolic link
 234 .B /dev/changer
 235 to point
 236 to that device name (if it is not doing so already).
 237 .P
 238 With BRU, set your mount and unmount commands as described on the BRU
 239 web site at http://www.bru.com to move to the next tape when backing up
 240 or restoring. With GNU
 241 .B tar,
 242 see
 243 .B mtx.doc
 244 for an example of how to use
 245 .B tar
 246 and
 247 .B mtx
 248 to make multi-tape backups.
 249
 250 .SH AVAILABILITY
 251 This version of
 252 .B mtx
 253 is currently being maintained by Robert Nelson <robertnelson@users.sourceforge.net> .
 254 The 'mtx' home page is http://mtx.sourceforge.net and the actual code is currently available
 255 there and via SVN from http://sourceforge.net/projects/mtx.
 256 .SH SEE ALSO
 257 .BR mt (1), loaderinfo (1), tapeinfo (1), scsitape (1), scsieject (1)