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