IBMVSCSIS.CONF(8) BSD System Manager's Manual IBMVSCSIS.CONF(8)NAMEibmvscsis.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 tar‐
get 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 hexadec‐
imal 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 num‐
ber 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 set‐
tings 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 ele‐
ment 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 automati‐
cally configured in lieu of omitted elements.
The first is that all targets are activated by default unless an "inac‐
tive" 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 ele‐
ments where ‘vdisk’ is a large flat file created especially for this pur‐
pose:
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 ALSOibmvscsis.sh(8), vscsisadmin(8)AUTHOR(S)
Ryan S. Arnold ⟨rsa@us.ibm.com⟩
LINUX January 14, 2005 LINUX
