jammy (1) mtx.1.gz

Provided by: mtx_1.3.12-14build2_amd64 bug

NAME

       mtx - control SCSI media changer devices

SYNOPSIS

       mtx [-f <scsi-generic-device>] [nobarcode] [invert] [noattach] command [ command ... ]

DESCRIPTION

       The  mtx  command  controls single or multi-drive SCSI media changers such as tape changers, autoloaders,
       tape libraries, or optical media jukeboxes.  It can also  be  used  with  media  changers  that  use  the
       'ATTACHED'  API,  presuming  that  they properly report the MChanger bit as required by the SCSI T-10 SMC
       specification.

OPTIONS

       The first argument, given following -f , is the SCSI generic device corresponding to your media  changer.
       Consult  your  operating  system's documentation for more information (for example, under Linux these are
       generally /dev/sg0 through /dev/sg15, under FreeBSD these are /dev/pass0 through /dev/passX, under  SunOS
       it may be a file under /dev/rdsk).

       The 'invert' option will invert (flip) the media (for optical jukeboxes that allow such) before inserting
       it into the drive or returning it to the storage slot.

       The 'noattach' option forces the regular media changer API even if the media changer incorrectly reported
       that it uses the 'ATTACHED' API.

       The  'nobarcode'  option  forces  the  loader  to  not  request barcodes even if the loader is capable of
       reporting them.

       Following these options there may follow one or more robotics control commands. Note  that  the  'invert'
       and 'noattach' options apply to ALL of robotics control commands.

COMMANDS

       --version Report the mtx version number (e.g. mtx 1.2.8) and exit.

       inquiry   Report  the  product  type (Medium Changer, Tape Drive, etc.), Vendor ID, Product ID, Revision,
                 and whether this uses the Attached Changer API (some tape drives use this rather than reporting
                 a Medium Changer on a separate LUN or SCSI address).

       noattach  Make  further  commands  use  the  regular  media changer API rather than the _ATTACHED API, no
                 matter what the "Attached" bit said in the Inquiry info.  Needed with some brain-dead  changers
                 that report Attached bit but don't respond to _ATTACHED API.

       inventory Makes  the  robot  arm  go  and  check what elements are in the slots. This is needed for a few
                 libraries like the Breece Hill ones that do not  automatically  check  the  tape  inventory  at
                 system startup.

       status    Reports  how  many  drives  and  storage  elements are contained in the device. For each drive,
                 reports whether it has media loaded in it, and  if  so,  from  which  storage  slot  the  media
                 originated.  For  each  storage  slot,  reports  whether  it is empty or full, and if the media
                 changer has a bar code, MIC reader, or some other way of  uniquely  identifying  media  without
                 loading it into a drive, this reports the volume tag and/or alternate volume tag for each piece
                 of media.  For historical reasons drives are numbered from 0 and  storage  slots  are  numbered
                 from 1.

       load <slotnum> [ <drivenum> ]
                 Load media from slot <slotnum> into drive <drivenum>. Drive 0 is assumed if the drive number is
                 omitted.

       unload [<slotnum>] [ <drivenum> ]
                 Unloads media from drive <drivenum> into slot <slotnum>. If <drivenum> is omitted, defaults  to
                 drive 0 (as do all commands).  If <slotnum> is omitted, defaults to the slot that the drive was
                 loaded from. Note that there's currently no way to say 'unload drive 1's media to the  slot  it
                 came from', other than to explicitly use that slot number as the destination.

       [eepos <operation>] transfer <slotnum> <slotnum>
                 Transfers  media from one slot to another, assuming that your mechanism is capable of doing so.
                 Usually used to move media to/from an import/export port. 'eepos' is used to extend/retract the
                 import/export tray on certain mid-range to high end tape libraries (if, e.g., the tray was slot
                 32, you might say say 'eepos 1 transfer 32 32' to extend the tray).   Valid  values  for  eepos
                 <operation>  are  0  (do  nothing  to the import/export tray), 1, and 2 (what 1 and 2 do varies
                 depending upon the library, consult your library's SCSI-level documentation).

       [eepos <operation>] [invert] [invert2] exchange <slotnum> <slotnum> [<slotnum>]
                 Move medium from the first slot to the second slot, placing the medium currently in the  second
                 slot either back into the first slot or into the optional third slot.

       first [<drivenum>]
                 Loads  drive <drivenum> from the first slot in the media changer. Unloads the drive if there is
                 already media in it (note: you may need to eject the tape using your OS's tape control commands
                 first).   Note  that  this  command may not be what you want on large tape libraries -- e.g. on
                 Exabyte 220, the first slot is usually a cleaning tape. If <drivenum> is omitted,  defaults  to
                 first drive.

       last [<drivenum>]
                 Loads  drive  <drivenum> from the last slot in the media changer. Unloads the drive if there is
                 already a tape in it. (Note: you may need to eject  the  tape  using  your  OS's  tape  control
                 commands first).

       previous [<drivenum>]
                 Unloads  the  drive  and loads the previous tape in sequence. If the drive was empty, loads the
                 first tape into the drive.

       next [<drivenum>]
                 Unloads the drive and loads the next tape in sequence. If the drive was empty, loads the  first
                 tape into the drive.

       position <slotnum>
                 Positions  the  robot  at  a  specific  slot.  Needed  by some changers to move to and open the
                 import/export, or mailbox, slot.

       eject     Eject the tape currently in the drive.

AUTHORS

       The original 'mtx' program was written by Leonard Zubkoff and extensively revised for  large  multi-drive
       libraries with bar code readers by Eric Lee Green <eric@badtux.org>. See 'mtx.c' for other contributors.

BUGS AND LIMITATIONS

       You  may  need  to  do  a  'mt offline' on the tape drive to eject the tape before you can issue the 'mtx
       unload' command. The Exabyte EZ-17 and 220 in particular will happily sit there snapping the robot  arm's
       claws around thin air trying to grab a tape that's not there.

       For some Linux distributions, you may need to re-compile the kernel to scan SCSI LUN's in order to detect
       the media changer. Check /proc/scsi/scsi to see what's going on.

       If you try to unload a tape to its 'source' slot, and said slot is full, it will  instead  put  the  tape
       into  the  first empty slot. Unfortunately the list of empty slots is not updated between commands on the
       command line, so if you try to unload another drive to a full 'source' slot during the same invocation of
       'mtx', it will try to unload to the same (no longer empty) slot and will urp with a SCSI error.

       This  program  reads  the  Mode  Sense  Element  Address  Assignment Page (SCSI) and requests data on all
       available elements.  For  larger  libraries  (more  than  a  couple  dozen  elements)  this  sets  a  big
       Allocation_Size  in  the SCSI command block for the REQUEST_ELEMENT_STATUS command in order to be able to
       read the entire result of a big tape library. Some operating systems may not  be  able  to  handle  this.
       Versions  of  Linux  earlier  than  2.2.6,  in particular, may fail this request due to inability to find
       contiguous pages of memory for the SCSI transfer (later versions of Linux 'sg' device  do  scatter-gather
       so that this should no longer be a problem).

       The  eepos  command  remains in effect for all further commands on a command line. Thus you might want to
       follow eepos 1 transfer 32 32 with eepos 0 as the next command (which clears the eepos bits).

       Need a better name for 'eepos' command! ('eepos' is the name of the bit field  in  the  actual  low-level
       SCSI command, and has nothing to do with what it does).

       This  program  has  only been tested on Linux with a limited number of tape loaders (a dual-drive Exabyte
       220 tape library, with bar-code reader and 21 slots, an Exabyte EZ-17 7-slot autoloader,  and  a  Seagate
       DDS-4 autochanger with 6 slots). It may not work on other operating systems with larger libraries, due to
       the big SCSI  request  size.   Please  see  the  projecdt  page  http://sourceforge.net/projects/mtx  for
       information on reporting bugs, requesting features and the mailing list for peer support.

HINTS

       Under Linux, cat /proc/scsi/scsi will tell you what SCSI devices you have.  You can then refer to them as
       /dev/sga, /dev/sgb, etc. by the order they are reported.

       Under FreeBSD, camcontrol devlist will tell you what SCSI devices you have, along with which pass  device
       controls them.

       Under  Solaris, set up your 'sgen' driver so that it'll look for tape changers (see /kernel/drv/sgen.conf
       and the sgen man page), type touch /reconfigure then reboot. You can find your  changer  in  /devices  by
       typing  /usr/sbin/devfsadm -C to clean out no-longer-extant entries in your /devices directory, then find
       /devices -name \∗changer -print to find the device name. Set the symbolic link /dev/changer to  point  to
       that device name (if it is not doing so already).

       With  BRU,  set your mount and unmount commands as described on the BRU web site at http://www.bru.com to
       move to the next tape when backing up or restoring. With GNU tar, see mtx.doc for an example  of  how  to
       use tar and mtx to make multi-tape backups.

AVAILABILITY

       This version of mtx is currently being maintained by Robert Nelson <robertnelson@users.sourceforge.net> .
       The 'mtx' home page is http://mtx.sourceforge.net and the actual code is currently  available  there  and
       via SVN from http://sourceforge.net/projects/mtx.

SEE ALSO

       mt(1),loaderinfo(1),tapeinfo(1),scsitape(1),scsieject(1)

                                                     MTX1.3                                               MTX(1)