SCSIDEV(8)						      System Manager's Manual							SCSIDEV(8)

# # $Id: scsidev.8,v 1.11.2.8 2004/02/18 10:08:59 garloff Exp $ #

NAME

       scsidev - populate /dev/scsi with device names that are persistent against SCSI configuration changes.

SYNOPSIS

       scsidev [ -f ] [ -n ] [ -d ] [ -l ] [ -L ] [ -m mode ] [ -c mxms ] [ -A aliasfile ] [ -r ] [ -M ] [ -e ] [ -o ] [ -s ] [ -v ] [ -q ] [ -h ]

DESCRIPTION

       scsidev	is  a  utility that is used to guarantee that the same device node can be used for the same scsi device, no matter what other scsi
       devices are added or removed from the scsi chain.  The need for this tool arose because device numbers are  assigned  dynamically  at  boot
       time,  and  if a new disk were added to the system (or if some disk didn't spin up), then fixed device nodes would cause the wrong filesys-
       tems to be mounted, checked, etc.  This can also result in security holes, as some device nodes may have  permissions  that  allow  general
       users access to the raw device, and if the mappings were to change, users would be able to access different devices.

       scsidev	is  designed  to be used once each time the system boots.  It will scan all of the detected devices on the system, and determine a
       immutable name that will represent the device.  It first checks to see if a node by this name already exists - if this is the case, then it
       checks  to  see if the major/minor numbers are correct.	If a change in the minor number is required, then a new device is created with the
       correct major/minor numbers, and in addition, any ownership and permissions for the old device are applied to the new device.

       Once this process is complete, then scsidev will scan all of the entries in the /dev/scsi directory, and see if any of them are for devices
       nodes  which  were added for devices that are not active.  The permissions of inactive devices are stored in a .shadow. file and the device
       node is removed as a security precaution, since these might have permissions that would allow people to access devices that they should not
       be  able to access.  This is the default behaviour and is considered ideal for most cases, as it preserves the ownership and permissions of
       the files and is secure.

       The so called sanitizing can be influenced by the options -f -d -n.

       When you rescan the bus by using the rescan-scsi-bus.sh script or manually by using commands like
       echo "scsi add-single-device C B T U" >/proc/scsi/scsi
       (C = Controller (host) no., B = Bus (Channel), T = Target (SCSI ID), U = Unit (SCSI LUN)) after the system is booted, then you will have to
       rerun scsidev so that the device nodes for the newly detected devices are properly updated.

       The  device  nodes that scsidev creates look something like "sdh4-334c0i0l0p1".	In this case, the various components of the name represent
       physical attributes about the device or the host adapter to which it is connected.  To begin with, the "h4" indicates that it is  connected
       to  an Adaptec 1542.  The "-334" is a means of identifying which 1542 the device is attached to (since linux supports more than one 1542 in
       the system at the same time) and (in this case) corresponds to the IO Port number (hex) of the controller (this is the host adapter id num-
       ber).   The  "c0"  represents the channel number (since some host adapters can drive multiple scsi busses).  The "i0l0" indicates that this
       device is scsi ID 0, with lun 0.  Finally the "p1" indicated partition number 1.

OPTIONS

       -f     Flush everything from /dev/scsi prior to scanning the detected devices.  This means that new device nodes will be  created  even	if
	      the old ones were OK.

       -d     Sanitize	by  deletion.  The  .shadow. backup files will not be created, so you loose all non-default ownership/permissions that may
	      have been set.

       -n     Don't touch device nodes for non-existing SCSI devices.  This might have security implications and is therefore not recommended.

       -l     Symbolic link mode.  Instead of creating nodes, symbolic links are created which point to the older /dev/sda1 types of device nodes.
	      When using this option, the permissions of the /dev/XXX device nodes will be changed to match the ones stored in /dev/scsi/YYY file,
	      if present.

       -L     Use symbolic names for the aliases assigned through the /etc/scsi.alias settings (see below).

       -m mode
	      Specifies the mode (permissions) for new entries that need to be created.

       -c maxmiss
	      Normally, if scsidev fails to open a generic scsi device, it finishes its scan for devices. With	this  option,  it  goes  on  until
	      maxmiss missing devices were found.  This is only used, if you don't have the /proc/scsi/scsi extensions for large disks.

       -A aliasfile
	      Use an alternative file instead of the default /etc/scsi.alias (see below).

       -r     scsidev  does  first probe the generic and then -- if appropriate -- the other highlevel devices (st, sd, sr). For removable devices
	      (sd, sr, osst), this will fail, if no medium is inserted, so scsidev can not ensure, that the device actually corresponds to the one
	      reported by the sg interface. After the first device scan, the situation is clear and scsidev will do the right guesses. So using -r
	      in bootup scripts is safe. After you removed devices from your SCSI config, it isn't safe any longer.  This is only needed,  if  you
	      don't have the /proc/scsi/scsi extensions for large disks.

       -M     Multipath support.  scsidev normally does complain if a line in scsi.alias matches more than one device and does not create an alias
	      then. With multipatch support on, it just creates the alias for the first device found matching the description  in  the	scsi.alias
	      description.

       -e     Instructs  scsidev  to  use  devfs  like names, i.e. using the cbtu (controller, bus, target unit) characters instead of hcil (host,
	      channel, scsi Id, scsi Lun) to build the device name.

       -o     Instructs scsidev to use scd instead of sr for the old names of CD-ROM devices (relevant for symlink mode).

       -s     Tells scsidev
	       to print out the device serial numbers of all detected devices on the system. This string can be useful for  forming  aliases.	If
	      supported, also the WWID is printed.

       -v     Verbosity.  Mainly used for debugging purposes.  Use multiple times for more verbosity.

       -q     Be Quiet.  Only produce output, if there are errors.

       -h     Output short usage summary and copyright info and exit.

ALIASES

       It  was intended that scsidev be useful without any configuration at all.  There are times when it is much more convenient to have symbolic
       names for various devices.  These symbolic names should track devices as they get moved from controller to another, or even if the SCSI	id
       number is changed.

       The  general  idea is that there is a configuration file /etc/scsi.alias which lists the aliases that scsidev will attempt to create.  Each
       line represents a separate alias, and consists of a series of tokens.  Here are a couple of example entries:
       serial_number="DX908FK", devtype=disk, alias=fourgig
       manufacturer=WANGTEK, devtype=tape, alias=qictape
       id=2, devtype=generic, alias=cdwriter
       The minimum requirements are that each line have a alias and a devtype field.  The alias will be used to build the pathnames, and the  dev-
       type must be one of disk, tape, osst, cdrom or generic.

       The  additional	qualifiers  are optional, and you must specify a sufficient number of them such that the alias will match only one device.
       The allowable qualifiers are:

       manufacturer=
	      Specifies the name of the manufacturer.  This is the same string that is printed	at  boot  time,  and  is  also	available  through
	      /proc/scsi.

       model= Specifies  the  model  number  of  the  device.  This is the same string that is printed at boot time, and is also available through
	      /proc/scsi.

       rev=   Specifies the revision string of the device. This is the same string that is printed at boot time, and  is  also	available  through
	      /proc/scsi.

       serial_number=
	      Specifies the serial number of the device.  Not all devices implement this, but for those that do it provides a convenient mechanism
	      to uniquely identify a device no matter where it is found on the scsi chain. The serial number is the one reported in  INQUIRY  page
	      0x80 with EVPD=1. It is displayed by scsidev -s .

       wwid=  Specifies  the  WWID number of a device. This is a 64bit world wide unique number, which is supported by SCSI-3 devices and reported
	      via INQUIRY page 0x83 with EVPD=1. If supported, it's displayed by scsidev -s .

       id=    Specifies the scsi id number for the device.

       lun=   Specifies the lun for the device.  Most devices have a lun of 0, and it is only special devices such as cd changers  that  implement
	      multiple lun devices.

       chan=  Specifies which channel (i.e. which bus) for host adapters that drive multiple channels.

       partition=
	      Specifies the partition number for disk drives.  If unspecified, the alias will match all partitions on the disk.

       hostid=
	      Specifies the host adapter id number (0x334 part of sdh4-334c0i0l0p1 for example).

       hostnum=
	      Specifies  the  unique  number  that each host adpater driver returns.  Generally this number is always 0 except for cases where the
	      driver supports more than one device of a given type on the system.

       hostname=
	      Specifies the host adapter driver name. (Only the given chars need to match, so you may omit the version number.)

       Note that the specifiers which take string arguments can be quoted if the string contains whitespace.

       For disks, aliases for all partitions will be created (unless partition= is specified). The names get a -pN suffix (N indicating the number
       of the partition. For tapes (st and osst type), the non-rewinding variant with an n prepended will be created automatically.

AUTHOR

       scsidev
	... was written by Eric Youngdale <eric@aib.com>
	... was enhanced by Kurt Garloff <garloff@suse.de>

BUGS

       Probably there are ...

       The  BIOS  and  LILO  do not have the knowledge about the SCSI devices at boot time, so you still have to ensure, your kernel can be loaded
       when you insert a new disk.

COPYRIGHT

       This program is free software. You can use it under the terms of the GNU GPL (General Public License) Version 2 (or any later  version,	at
       your  option).	Note, that the GNU GPL implies, that there is NO WARRANTY at all.  Full text of the GPL can be found in /usr/share/common-
       licenses/GPL file.

AVAILABILITY

       scsidev is available from
       http://www.suse.de/~garloff/linux/scsidev/
       and
       http://www.garloff.de/kurt/linux/scsidev/
       and will also be put on standard anonymous ftp servers.
       The old version is available from
       ftp://tsx-11.mit.edu/pub/linux/BETA/scsi/

Version 2.29							     June 2003								SCSIDEV(8)