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.

    Today in Linux there exists the potential for Scsi device name 
    slippage. For example, in the case of Scsi disks, devices
    and their  partitions are named as they are discovered, 
    disk1 is /sda, disk2 is /sdb and so on. Thru the use of 
    optional boot parameters limited control is available that 
    may influence the discovery order. Naming based on discovery
    order may be impacted by adding of additional disks or by disk 
    failures. Since linux startup scripts and configuration 
    information utilizes the assigned device names, these name 
    changes have the potential to create system failures. Alternative
    naming strategies are also available that create alias device
    nodes or symlinks that are based on a device's topology. Assignment
    of names using this technique are impacted as adapters are 
    added or removed or devices are assigned new scsi ids or are moved
    to another bus.

    The goal of this utility is to provide the capability to name a device
    based on it's characteristics. Using this methodology the device name
    is independant of it's discovery order or topology. 

    During device discovery/insertion, notifications generated by the 
    Linux hotplug subsystem are used as the stimulus for doing name 
    assignments. Hotplug scripts invoke the scsiname utility. This 
    utility will collect device information using the scsi generic (sg) 
    interfaces.
	
1. Version Notes
	1.0 Prereqs Scsi hotplug support provided by the scsimon patch 
	    (Doug Gilbert), http://www.torque.net/scsi/scsimon.html
	1.1 Your kernel must be built with hotplug enable enabled.
	1.2 Your kernel must be built with the scsi generic driver enabled.
	1.3 Your kernel must be built with the scsi monitor driver enabled.


2. Configuration and Build

    2.0 Install and build linux linux kernel with the scsimon patch.

	2.0.1 Download and install the linux-2.5.14 kernel
	    	/usr/src> tar -xvf linux-2.5.14.tar

	2.0.2 Apply the scsimon patch
		/usr/src/linux-2.5.14> patch -p1 < scsimon_252p9.diff

	      Note: Doug Gilbert's scsimon package is available from
		http://www.torque.net/scsi/scsimon.html. Follow the instructions
		available at that site for the latest information.


	      Note: If scsimon.c reports an error on line 825, comment the
		line and continue building.

	2.0.3 Set kernel hotplug, scsi monitor, and scsi generic options.
	    CONFIG_HOTPLUG=Y
	    CONFIG_CHR_DEV_SG=Y
	    CONFIG_CHR_DEV_SM=Y

	2.0.4 Build and install your kernel. Refresh lilo with your patched kernel. 
		Sample /etc/lilo.conf entry:
		image=/boot/bzImage-2.5.14
		label=linux-2.5.14
		initrd=/boot/initrd-2.5.14.img
		read-only

	2.0.5 Run /sbin/lilo 

   2.1 Install hotplug scripts

	2.1.0 If the hotplugging utlities are not installed on your machine, this 
		package and it's installation instructions are available at
		http://linux-hotplug.sourceforge.net/

	      Note: Installation should include /etc/hotplug scripts, /etc/rc.d
		init.d/hotplug, etc/rc*.d/ runlevel scripts,  and /sbin/hotplug.
		Since not all hotplug events can be processed during boot time
		it is important that the hotplug init script be setup at each
		runlevel to synthesize missed events.

   2.2 Install,build, and configure the scsiname utility

	2.2.0  Install the scsiname utility
	    /usr/src> tar -xzvf scsiname-0.1.0.tar.gz
	    /usr/src/scsiname-0.1.0> make install

	2.2.1 Copy the updated scsi hotplug scripts to your hotplug directory
	    /usr/src/scsiname-0.1.0> cp scsi.* /etc/hotplug/.

	2.2.1 Provide user configuration info in /etc/scsiname.conf
	    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.

	    If the user wishes to assign a persistent name for a device it is
	    necessary to provide configuration information in the /etc/scsiname.conf
	    file. (See UsersGuide)

3. More detailed Info
   	
	Refer to the UsersGuide provided with this archive to learn about more about the
	architecture and detailed usage of the scsiname utility.


4. 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
