VSCSISADMIN(8) BSD System Manager's Manual VSCSISADMIN(8)NAMEvscsisadmin — virtual SCSI server administration utility
SYNOPSISvscsisadmin-start [-adapter=adapter] [-adapter=adapter -bus=bus]
[-adapter=adapter -bus=bus -target=target] [-noisy] [-noisy] [-warn]
vscsisadmin-status [-noisy] [-noisy] [-warn]
vscsisadmin-stop [-path=path] [-adapter=adapter]
[-adapter=adapter -bus=bus] [-adapter=adapter -bus=bus -target=target]
[-noisy] [-noisy] [-warn]
vscsisadmin-help
vscsisadmin-version
DESCRIPTION
This is the IBM virtual SCSI server (ibmvscsis) administration utility.
This utility is responsible for configuring, starting, stopping, and
gathering status on the virtual SCSI server.
OPTIONS-help Output the vscsisadmin utility's help information, which gives a
brief synopsis of this manual page.
-noisy This directive is optional. Without a ‘-noisy’ directive the
vscsisadmin script is in silent mode by default (except in the
case of errors, warnings and output requests). The output ver‐
bosity of the script is managed by stacking ‘-noisy’ directives.
A single instance of ‘-noisy’ indicates that the utility should
output in status mode. A second instance of ‘-noisy’ indicates
that the utility should output in verbose mode. Verbose mode is
generally used for script tracing and won't be used by a casual
user unless problems arise.
-start Configure and start the virtual SCSI server based upon the
adapter:bus:target entries found in the configuration file
(denoted in the FILES section of this manual). This directive
will configure valid adapter:bus:target entries regardless of
whether they are to be active or inactive at startup. If the
vscsis target is already active this command will configure and
start the remaining valid targets specified in the configuration
file and leave the already active targets alone. For informa‐
tion on how to write a well formed configuration file
ibmvscsis.conf(8) is provided as an accompanying man page.
-start -adapter=adapter
This modified ‘-start’ directive will read the config file and
will only process those config file entries that are defined
under the specified adapter. An example follows:
vscsisadmin-start -adapter=30000005
-start -adapter=adapter -bus=bus
This modified ‘-start’ directive will read the config file and
will only process those config file entries that are defined
under the specified adapter and bus. An example follows:
vscsisadmin-start -adapter=30000005 -bus=0
-start -adapter=adapter -bus=bus -target=target
This modified ‘-start’ directive will read the config file and
will only process those config file entries that are defined
under the specified adapter, bus and target. An example fol‐
lows:
vscsisadmin-start -adapter=30000005 -bus=0 -target=2
-status Output a table of status on the virtual SCSI server. This table
pertains to the activity found in the ibmvscsis sysfs directory
and not only to the adapter:bus:target entries in the ibmvscsis
configuration file. Here is an example output:
ibmvscsis:30000008
* bus0:target0:/dev/sdd6
* bus0:target1:/dev/sdd7
* bus1:target0:/dev/sdd8
ibmvscsis:30000009
bus0:target1:/dev/loop0-->/var/vscsis/vdisk1
ibmvscsis:3000000a
ibmvscsis:3000000b
* bus0:target1:/dev/loop1-->/var/vscsis/vdisk2
In the status output each vscsis adapter has a block of data.
Within this block of data each target is preceded by the bus
number it is on. Following the target information is the device
path with which the target is associated. A loop file, if there
is one, may follow the device path. Preceding every entry may
be an asterisk. The presence of an asterisk indicates that the
target is currently active. No asterisk indicates that the tar‐
get is configured but not active.
Existent bus:target combinations that lack any device_path data
are left out of the status information because they aren't rele‐
vant.
A single inclusion of the ‘-noisy’ directive with the status
directive will not change the output of this utility. A second
‘-noisy’ inclusion will put the utility into verbose mode and
may increase the amount of output.
-stop The general behavior of the stop directive is that the vscsisad‐
min utility will walk the ibmvscsis driver sysfs tree and
silently deactivate all targets, detach all loop back devices,
and remove all targets and buses from all adapters under the
driver's care.
There are extended options for a more selective stop operation.
-stop -path=path
This is a robust stop operation which will determine whether to
stop a single target, all targets on an entire bus, or all tar‐
gets on an entire adapter. This is signalled through the selec‐
tion of a path to one of the three (vscsisadmin doesn't care if
the path contains a trailing '/'). Take the following three
examples:
vscsisadmin-stop \
-path=/sys/bus/vio/drivers/ibmvscsis/30000005/bus0/target0
vscsisadmin-stop \
-path=/sys/bus/vio/drivers/ibmvscsis/30000005/bus0/
vscsisadmin-stop \
-path=/sys/bus/vio/drivers/ibmvscsis/30000005/
Example one will cause vscsisadmin to deactivate a single tar‐
get. Example two will cause vscsisadmin to deactivate all tar‐
gets on an entire bus and remove all of the targets from the
bus. Example three will cause vscsisadmin to deactivate all
targets on all buses under the adapter and it will remove all
targets and all buses under the adapter.
-stop -adapter=adapter
This operation takes an adapter number in hexadecimal. It will
terminate all of the targets on all of the buses under the
adapter. It will also remove all targets on all buses and
remove all the buses under the adapter. An example follows:
vscsisadmin-stop -adapter=30000005
-stop -adapter=adapter -bus=bus
This operation takes an adapter number in hexadecimal and an
integer bus number. It will deactivate all of the targets under
the specified bus and will remove the targets from the bus. An
example follows:
vscsisadmin-stop -adapter=30000005 -bus=0
-stop -adapter=adapter -bus=bus -target=target
This operation takes an adapter number in hexadecimal, an inte‐
ger bus number, and an integer target number. It will only
deactivate the target specified. An example follows:
vscsisadmin-stop -adapter=30000005 -bus=0 -target=0
-version
Output the version number of the vscsisadmin utility.
-warn Warning messages are suppressed even when vscsisadmin is in ver‐
bose output mode unless the application was run with the ‘-warn’
flag. Warnings indicate that unexpected circumstances happened
during vscsisadmin operations. Warning messages are not severe
enough to terminate the running operation.
There are two scenarios when warnings are generated. The first
is when the vscsisadmin utility reads the config file and reads
an entry for an expected adapter, bus, target, or target
attributes that is not found in the ibmvscsis driver's sysfs
directory tree. This can be due to adapter being removed from
firmware without the removal of the adapter configuration entry
from the config file. The third scenario is when target config
entries contain "none". Such entries are ignored.
FILES
/etc/ibmvscsis.conf
This is the virtual SCSI server configuration file used by vsc‐
sisadmin to configure and manage ibmvscsis. This configuration
file has its own man page which describes how to properly write
a virtual SCSI server config.
/etc/init.d/ibmvscsis.sh
This is the virtual SCSI server start and stop automation init
script. This application invokes vscsisadmin internally and
presents a standard init script interface.
CAVEATS
start caveats
It is not advisable to manually create and activate targets
without adding corresponding config file entries.
stop caveats
Currently the virtual SCSI server doesn't support an interface
for determining if the partner vscsis adapter for each vscsis
adapter is actually in use. Therefore it can be VERY dangerous
to stop a running vscsi server before all partner partitions
have been halted. In the future this script will, by default,
not deactivate targets who are on actively connected adapters.
At that time a ‘-force’ directive can accompany a stop directive
to force deactivate such targets.
DEPENDENCIES
The vscsisadmin utility requires that the ibmvscsis driver module be
installed on the system, or built-in when the application is invoked.
This utility depends on the existence of the systool application for
querying the /sys file system and gathering data about the ibmvscsis
device driver. Execution of vscsisadmin will be stopped immediately if
systool is not present on the system.
SEE ALSOibmvscsis.sh(8), ibmvscsis.conf(8)AUTHOR(S)
Ryan S. Arnold ⟨rsa@us.ibm.com⟩
LINUX January 14, 2005 LINUX
