#
# $Id: scsidev.8,v 1.11.2.8 2004/02/18 10:08:59 garloff Exp $
#
.\" -*- nroff -*-
.TH SCSIDEV 8 "June 2003" "Version 2.29"
.SH NAME
scsidev \- populate /dev/scsi with device names that are persistent
against SCSI configuration changes.
.SH SYNOPSIS
.B scsidev
[
.B \-f
]
[
.B \-n
]
[
.B \-d
]
[
.B \-l
]
[
.B \-L
]
[
.B \-m mode
]
[
.B \-c mxms
]
[
.B \-A aliasfile
]
[
.B \-r
]
[
.B \-M
]
[
.B \-e
]
[
.B \-o
]
[
.B \-s
]
[
.B \-v
]
[
.B \-q
]
[
.B \-h
]
.SH DESCRIPTION
.B 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 filesystems 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.
.PP
.B 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.
.PP
Once this process is complete, then
.B 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.
.PP
The so called sanitizing can be influenced by the options 
.B \-f \-d \-n.
.PP
When you rescan the bus by using the 
.B rescan-scsi-bus.sh
script or manually by using commands like
.nf
echo "scsi add-single-device C B T U" >/proc/scsi/scsi
.fi
(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.
.PP
The device nodes that
.B 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 number).
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.
.SH OPTIONS
.TP
.I \-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.
.TP
.I \-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.
.TP
.I \-n
Don't touch device nodes for non-existing SCSI devices. 
This might have security implications and is therefore not recommended.
.TP
.I \-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.
.TP
.I \-L
Use symbolic names for the aliases assigned through the 
.B /etc/scsi.alias
settings (see below).
.TP
.I \-m mode
Specifies the mode (permissions) for new entries that need to be created.
.TP
.I \-c maxmiss
Normally, if 
.B 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.
.TP
.I \-A aliasfile
Use an alternative file instead of the default /etc/scsi.alias (see below).
.TP
.I \-r
.B 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
.B 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 
.B 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.
.TP
.I \-M
Multipath support.
.B 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.
.TP
.I \-e
Instructs 
.B 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.
.TP
.I \-o
Instructs 
.B scsidev 
to use scd instead of sr for the old names of CD-ROM devices 
(relevant for symlink mode).
.TP
.I \-s
Tells 
.B 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.
.TP
.I \-v
Verbosity.  Mainly used for debugging purposes.  Use multiple times for
more verbosity.
.TP
.I \-q
Be Quiet.  Only produce output, if there are errors.
.TP
.I \-h
Output short usage summary and copyright info and exit.
.SH ALIASES
It was intended that
.B 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.
.P
The general idea is that there is a configuration file
.B /etc/scsi.alias
which lists the aliases that
.B 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:
.nf
serial_number="DX908FK", devtype=disk, alias=fourgig
manufacturer=WANGTEK, devtype=tape, alias=qictape
id=2, devtype=generic, alias=cdwriter
.fi
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 devtype
must be one of disk, tape, osst, cdrom or generic.
.P
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:
.TP
.I 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.
.TP
.I 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.
.TP
.I 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.
.TP
.I 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
.B scsidev -s .
.TP
.I 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 
.B scsidev -s .
.TP
.I id=
Specifies the scsi id number for the device.
.TP
.I 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.
.TP
.I chan=
Specifies which channel (i.e. which bus) for host adapters that drive
multiple channels.
.TP
.I partition=
Specifies the partition number for disk drives.  If unspecified,
the alias will match all partitions on the disk.
.TP
.I hostid=
Specifies the host adapter id number (0x334 part of sdh4-334c0i0l0p1 for
example).
.TP
.I 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.
.TP
.I hostname=
Specifies the host adapter driver name. (Only the given chars need
to match, so you may omit the version number.)
.PP
Note that the specifiers which take string arguments can be quoted
if the string contains whitespace. 
.PP
For disks, aliases for all partitions will be created (unless partition=
is specified). The names get a 
.B -pN 
suffix (N indicating the number of
the partition. For tapes (st and osst type), the non-rewinding variant 
with an 
.B n
prepended will be created automatically.
.SH AUTHOR
.nf
.B scsidev
 ... was written by Eric Youngdale <eric@aib.com>
 ... was enhanced by Kurt Garloff <garloff@suse.de>
.fi
.SH BUGS
Probably there are ...
.PP
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.
.SH COPYRIGHT
This program is free software. You can use it under the terms of the 
.B GNU GPL
(General Public License) Version 2 (or any later version, at your option).
Note, that the GNU GPL implies, that there is 
.B NO WARRANTY 
at all.
Full text of the GPL can be found in /usr/share/common-licenses/GPL file.
.SH AVAILABILITY
.B scsidev
is available from 
.nf
.B http://www.suse.de/~garloff/linux/scsidev/
and
.B http://www.garloff.de/kurt/linux/scsidev/
and will also be put on standard anonymous ftp servers.
The old version is available from 
.B ftp://tsx-11.mit.edu/pub/linux/BETA/scsi/
.fi