Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MTX(1)			    General Commands Manual			MTX(1)

       mtx - control SCSI media	changer	devices

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

       The mtx command controls	single or multi-drive SCSI media changers such
       as  tape	 changers, autoloaders,	tape libraries,	or optical media juke-
       boxes.  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.

       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

       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.

       --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  ad-

       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  _AT-

       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 with-
		 out 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 com-
		 mands).  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 destina-

       [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/re-
		 tract 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 val-
		 ues for eepos <operation> are 0 (do nothing to	the import/ex-
		 port  tray),  1, and 2	(what 1	and 2 do varies	depending upon
		 the library, consult  your  library's	SCSI-level  documenta-

       [eepos  <operation>]  [invert]  [invert2]  exchange <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).

       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	chang-
		 ers to	move to	and open the import/export, or mailbox,	slot.

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

       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. Unfortu-
       nately 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  li-
       braries	(more  than  a	couple dozen elements) this sets a big Alloca-
       tion_Size in the	SCSI command block for the REQUEST_ELEMENT_STATUS com-
       mand  in	 order	to be able to read the entire result of	a big tape li-
       brary. 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  com-
       mand  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 for
       information on reporting	bugs, requesting features and the mailing list
       for peer	support.

       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 typ-
       ing /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 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.

       This  version  of  mtx  is  currently being maintained by Robert	Nelson
       <>  .	 The  'mtx'   home   page   is  and	the actual code	is currently available
       there and via SVN from


				    MTX1.3				MTX(1)


Want to link to this manual page? Use this URL:

home | help