VSCSISADMIN(8)

NAME
vscsisadmin - virtual SCSI server administration utility

SYNOPSIS
vscsisadmin -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 verbosity 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 information 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 follows:

        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 target 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 relevant.

    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 vscsisadmin 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 targets on an entire adapter. This is signalled through the selection 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 target. Example two will cause vscsisadmin to deactivate all targets 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 integer 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 verbose 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 vscsisadmin 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 ALSO
ibmvscsis.sh(8), ibmvscsis.conf(8)

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