Scsi Naming (scsiname) module (Experimental)
Version 0.1.0	
Mike Sullivan	
sullivam@us.ibm.com
5/28/2002	

0. Description

    The purpose of the Scsi Naming (scsiname) utility is to manage
    the /dev namespace so that names of scsi devices remain
    the same even if their discovery order or bus topology
    changes.

    The scsiname utility receives linux hotplugging events. When
    it receives an event it performs the following:
   	- Interfaces through the scsi generic (sg) interface to 
	  collect the characteristics for the registering device.
   	- Reads the user provided configuration information in  
	  /etc/scsiname.conf (optional) to determine what to name 
          the device.
	- Performs matching of user configuration info against the
	  characteristics collected through sg. 
	- When a match is found, the user configured action is
	  performed. THE FOLLOWING ACTIONS ARE SUPPORTED:
		a. Creation of a symlink to an existing /dev node entry.
		b. Creation of a /dev node entry using the configured name.

1. Version Notes
   1.1 Patches for this version of scsiname utility have been applied and
	tested against the 2.5.14 version of the kernel.:
   1.2 Your kernel must be built with Hotplugging, Scsi Generic (sg) device,
	and Scsi Monitor (scsimon) device enabled.
   1.3 Support for ext2 label comparisions are supported.


2. Configuration

   The simplest configuration is one where discovered scsi devices
   are automatically named by the scsiname utility. The names selected are 
   based on information obtained from the device using the sg interface and
   should be consistent across boots.

   2.1 /etc/scsiname.conf options

	The scsiname.conf file can be provided with configuration information
	that can be used to identify and name a device. Parameters supported:

	- name
	    The name of a scsi device is created from the information it returns
	    on Scsi Inquiry commands. The scsiname utility attempts to utilize
	    information from the vital product data pages to create a unique
	    identifier. Pages used include:
	      page 0x83 (Device Identification)
	      page 0x80 (Unit Serial number)

	- vendor
	    The vendor identification returned in the Standard Inquiry data page.

	- model
	    The product identification field number returned in the Standard 
	    Inquiry.

	- rev
	    The production revision level returned in the Standard Inquiry.

	- e2label
	    The ext2label read from the ext2 partition

	- uuid
	    The uuid read from the ext2 partition    
	
	- major
	    The major number assigned by the kernel to this device.

	- minor
	    The minor number assigned by the kernel to this device.

	- host
	    The host number assigned by the kernel to this device.

	- bus
	    The bus number assigned by the kernel to this device.

	- target
	    The target number assigned by the kernel to this device.

	- lun	
	    The lun number assigned by the kernel to this device.

	- part
	    The partition number assigned by the kernel to the 
	    partition found on this device.

	- e2label
	    The ext2label information stored on this device's partition.

	- alias
	    The user provided name to be used to create a /dev node for
	    this device.

	- symlink
	    The user provided name to be used to create a symlink to an
	    existing /dev node for this device.

	Note: The major, minor, host, bus, target, and lun parameters values
		are assigned by the kernel based on discovery order and may
		change as devices are added or removed from the system. 
		Therefore, it is not recommended that these parameters be 
		used to identify a device for persistent name assignment.

   2.1 /etc/scsiname.conf sample

	# Entry to create a device node for my disk
	name=UIBM-PCCODGHS6800BA25GKdisc
	vendor=IBM-PCCO
	model=DGHS18Y*
	rev=04F0
	alias=/dev/z_scsi/disc1

	# Entry to create a symlink to partition 2 of my disk
	name=UIBM-PCCODGHS6800BA25GKpart2
	vendor=IBM-PCCO
	model=DGHS18Y*
	rev=04F0
	symlink=/dev/z_scsi/partition2


   2.2 /etc/scsiname.conf notes

	- regexp wildcard formats are supported
	- Entries are delimited by a blank line
	

3. Invocations

    The scsiname utility is typically invoked from the /etc/hotplug/scsi.agent
    and /etc/hotplug/scsi.rc scripts. 

    3.0 From /etc/hotplug/scsi.agent when a single device is being added

	scsiname add <host> <bus> <target> <lun> <part>

	    The host, bus, target, lun, and part values are assigned by the
	    kernel to the device being added. See /proc/scsi/scsi for values
	    for your system.

    3.1 From /etc/hotplug/scsi.rc during system initialization to resynthesize
	lost hotplug events
	
	scsiname add all


    3.2 By users to examine parameters available for use in creating their
	/etc/scsiname.conf file (optional)

	scsiname list


4. Debug
   4.1 Trace utility

	To enable tracing rebuild the scsiname utility  with the 
	#define SCSINAME_DEBUG statement added at the top of the scsiname.h

	The collection of Trace information is supported in two ways:
	1. In main.c, setting no_log=TRUE; will print trace messages to the console.
	2. In main.c, setting no_log=FALSE; will write trace messages to /etc/reg.trc.

5. Things To Do
   3.1 Expansion of label support to other volume types

6. Bugs/Issues/Recommendations


Appendix A. References

	A.1 Linux Hotplugging Project
	    http://linux-hotplug.sourceforge.net/

	A.2 Doug Gilberts Scsimon Driver
	    http://www.torque.net/scsi/scsimon.html