IBMVSCSIS.CONF(8)

NAME
ibmvscsis.conf - virtual SCSI server configuration file

DESCRIPTION
This is the manual page for ibmvscsis.conf which is the IBM virtual SCSI server configuration file. This file denotes the SCSI bus and SCSI target configurations for each vscsis host adapter that the IBM virtual SCSI server manages. This configuration is read by the vscsisadmin utility which interacts with the ibmvscsis driver to create, configure, active, and deactivate properly configured targets.

This manual page serves as documentation on the configuration options supported by the vscsisadmin utility and how they must be presented in the ibmvscsis.conf configuration file to exhibit well-formed-ness.

FILES
The configuration file should be located in the following location on the file system:

/etc/ibmvscsis.conf

If this file doesn't exist, it should be created manually and contain entries for every vscsis adapter exposed by firmware to the ibmvscsis driver.

CONFIGURATION
The ibmvscsis.conf configuration file is built upon adapter:bus:target headers which describe SCSI target entries and a corresponding entry body built of elements. These elements denote the entry validity state, the entry activity state, the entry type, the device path and an optional loop file path.

  ENTRY HEADER
The following is an example of a config file entry header:

    	ibmvscsis:30000005:bus0:target0

This header is made up of the ibmvscsis identifier followed by a hexadecimal adapter number. Following the adapter number is a bus and target number.

The adapter number must correspond to a vscsis adapter found at /sys/bus/vio/drivers/ibmvscsis in sysfs. To verify that the adapter number is indeed a vscsis adapter the string, ‘v-scsi-host’ will appear under the name attribute in the adapter entry.

The bus and target numbers that appear in entry headers define the bus and targets that the vscsisadmin utility will create when the vscsi server is configured. Each header entry defines the configuration settings for a single target.

If the adapter specified in the configuration file doesn't exist in sysfs when the vscsi server is configured all of the elements in the entry body will be ignored.

  VALIDITY STATES
A SCSI target entry can be configured to demonstrate one of two possible visibility states. It can be either a valid entry or a placeholder entry. A placeholder entry contains the ‘none’ element as the only element in the entry body as the following example demonstrates:

    	ibmvscsis:30000005:bus0:target0
    		none

A valid entry contains at least the device_path element. Any entry which doesn't contain a device_path element is considered invalid and is ignored when the vscsi server is configured. A minimally configured valid entry example follows:

    	ibmvscsis:30000005:bus0:target0
    		device_path="/dev/sdd1"

The device_path element in this example indicates that the vscsi server is providing partition ‘sdd1’ as the block device managed by said target.

  DEFAULT ASSUMPTIONS
The vscsisadmin script assumes two default settings which are automatically configured in lieu of omitted elements.

The first is that all targets are activated by default unless an "inactive" element indicates otherwise. Please reference the ACTIVITY STATE sub section for further details on the activity state default and the method to override it.

The second default assumption is that the target device type is a block device. Excluding the "type" element from the entry is tantamount to declaring it a block device as the following example indicates:

    	ibmvscsis:30000005:bus0:target0
    		device_path="/dev/sdb1"
    		#defaults to type="b"

It is strongly recommended that type="b" element be included in the entry body anyway, for clarity as the following example shows:

    	ibmvscsis:30000005:bus0:target0
    		device_path="/dev/sdb1"
    		type="b"

In the future when other device types are supported the type element will indicate which type to set for each target.

  ACTIVITY STATES
An entry can be either active or inactive. The activity state dictates whether the vscsisadmin utility activates the target once it has been configured. By default every entry is in the active state. In order to tell the vscsisadmin script to configure the target but not activate it the ‘inactive’ element must be included in the entry body as indicated by the following example:

    	ibmvscsis:30000005:bus0:target0
    		device_path="/dev/sdb1"
    		type="b"
    		inactive

The ‘inactive’ element can be placed anywhere within the entry body, though placing it as the last element is customary.

  LOOP DEVICE CONFIGURATION
In order to direct the vscsi server to use a flat file as a SCSI target the file must be set up as a loop file and a special device called a loop device must be mapped by the file system as the device point attachment for the loop file. The vscsisadmin utility can create the loop file-to-device mapping automatically if the configuration file entry contains the loop_file element. The following example demonstrates the required elements where ‘vdisk’ is a large flat file created especially for this purpose:

    	ibmvscsis:30000005:bus0:target1
    		loop_file="var/vscsis/vdisk/"
    		device_path="/dev/loop1"
    		type="b"

The loop_file element may be placed anywhere in the entry though it is customary to place it preceding the device_path element. When the vscsi server is stopped the vscsisadmin utility will automatically detach any loop file-to-device mappings which match a target's device_path element.

The vscsisadmin script will check for the loop file on the file system before it attempts to configure target. If the loop file doesn't exist the target entry is ignored and the target will remain unconfigured.

  ELEMENT ORDERING
Configuration elements may be placed in any order in the entry body though there are customary places for certain elements that facilitate visual clarity.

  ENTRY ORDERING
The vscsisadmin utility should be smart enough to create the proper ibmvscsis configuration regardless of the order that the entries appear in the configuration file. It is still recommended that entries follow a least-to-greatest pattern.

Since each entry represents a target under a bus and adapter, targets are always listed in ascending order under their own bus. Each successive bus (and its target entries) should be listed in ascending order under its adapter. Finally each successive adapter (and its bus:target entries) should be listed in ascending order. The following ordering, sans entry elements, demonstrates the ordering criteria.

    	#same adapter, targets on the same bus
    	ibmvscsis:30000003:bus0:target0
    	ibmvscsis:30000003:bus0:target1
    	ibmvscsis:30000003:bus0:target2
    	#same adapter as previous, each target on a different bus
    	ibmvscsis:30000003:bus1:target0
    	ibmvscsis:30000003:bus2:target0
    	#new adapter, each target on the same bus.
    	ibmvscsis:30000004:bus0:target1
    	ibmvscsis:30000004:bus0:target2
    	#new adapter and each target on a different bus
    	ibmvscsis:30000005:bus0:target0
    	ibmvscsis:30000005:bus1:target0
    	ibmvscsis:30000005:bus2:target0

EXAMPLES
An example, well-formed /etc/ibmvscsis.conf configuration follows:

    	ibmvscsis:30000003:bus0:target0
    		device_path="/dev/sdd1"
    		type="b"
    	ibmvscsis:30000004:bus0:target0
    		device_path="/dev/sdd2"
    		#you can exclude the 'type="b"' as well
    	ibmvscsis:30000005:bus0:target0
    		device_path="/dev/sdd3"
    		type="b"
    	ibmvscsis:30000006:bus0:target0
    		device_path="/dev/sdd5"
    		type="b"
    	ibmvscsis:30000006:bus0:target1
    		device_path="/dev/sdd6"
    		type="b"
    	ibmvscsis:30000007:bus0:target0
    		none
    	ibmvscsis:30000008:bus0:target0
    		device_path="/dev/sdd7"
    		type="b"
    		inactive
    	ibmvscsis:30000008:bus1:target0
    		loop_file="/var/vscsi/vdisk1"
    		device_path="/dev/loop0"
    		type="b"
    	ibmvscsis:30000009:bus0:target0
    		none
    	ibmvscsis:3000000a:bus0:target0
    		loop_file="/var/vscsi/vdisk2"
    		device_path="/dev/loop1"
    		type="b"
    		inactive
    	ibmvscsis:3000000b:bus0:target0
    		loop_file="/var/vscsi/vdisk3"
    		device_path="/dev/loop2"
    		type="b"
    	ibmvscsis:3000000c:bus0:target0
    		loop_file="/var/vscsi/vdisk4"
    		device_path="/dev/loop3"
    		type="b"

SEE ALSO
ibmvscsis.sh(8), vscsisadmin(8)

AUTHOR(S)
Ryan S. Arnold <rsa@us.ibm.com>