STMFADM(8) Maintenance Commands and Procedures STMFADM(8)

NAME

stmfadm - SCSI target mode framework command line interface

SYNOPSIS

stmfadm add-hg-member -g host-group initiator...
stmfadm add-tg-member -g target-group target...
stmfadm add-view [-h host-group] [-n lu-number] [-t target-group]
lu-name
stmfadm create-hg group-name
stmfadm create-lu [-p property=value]... [-s size] lu-file
stmfadm create-tg group-name
stmfadm delete-hg group-name
stmfadm delete-lu [-k] lu-name
stmfadm delete-tg group-name
stmfadm import-lu lu-file
stmfadm list-hg [-v] [host-group]...
stmfadm list-lu [-v] [lu-name]...
stmfadm list-state
stmfadm list-target [-v] [target]...
stmfadm list-tg [-v] [target-group]...
stmfadm list-view -l lu-name [view]...
stmfadm modify-lu [-f] [-p property=value]... [-s size] lu-arg
stmfadm offline-lu lu-name
stmfadm offline-target target
stmfadm online-lu lu-name
stmfadm online-target target
stmfadm remove-hg-member -g host-group initiator...
stmfadm remove-tg-member -g target-group target...
stmfadm remove-view [-a] -l lu-name view...

DESCRIPTION

The stmfadm command configures logical units within the SCSI Target
Mode Framework (STMF) framework. The framework and this man page use
the following terminology:

initiator
A device responsible for issuing SCSI I/O commands to a SCSI
target and logical unit.

target A device responsible for receiving SCSI I/O commands for a
logical unit.

logical unit
A device within a target responsible for executing SCSI I/O
commands.

logical unit number
The identifier of a logical unit within a target.

host group
An host group is a set of one or more initiators that are
combined for the purposes of being applied to a view (see
below). An initiator cannot be a member of more than one host
group.

target group
A target group is a set of one or more SCSI target ports that
are treated the same when creating a view (see below). The set
of logical units that a particular SCSI initiator can see is
determined by the combined set of views.

Each logical unit has a set of view entries, and each view
entry specifies a target group, host group, and a LUN. An
initiator from that host group, when connecting through that
target group, is able to identify and connect to that logical
unit using the specified LUN. You can use views to restrict
the set of logical units that a specific initiator can see, and
assign the set of LUNs that will be used.

view A view defines the association of a host group, a target group,
and a logical unit number with a specified logical unit. Any
view entry added to a logical unit must not be in conflict with
existing view entries for that logical unit. A view entry is
considered to be in conflict when an attempt is made to
duplicate the association of any given host, target and logical
unit number.

Logical Unit Properties

The following logical unit properties can be set only when creating LU
using create-lu subcommand:

blk=num
Specifies the block size for the device. The default is 512.

guid=string
32 hexadecimal ASCII characters representing a valid NAA
Registered Extended Identifier. The default is set by the STMF
to a generated value.

meta=path
Metadata file name. When specified, will be used to hold the
SCSI metadata for the logical unit. There is no default.

oui=string
Organizational Unique Identifier. Six hexadecimal ASCII
characters representing the IEEE OUI company ID assignment.
This will be used to generate the device identifier (GUID).
The default is 00144F.

pid=string
16 bytes ASCII string defining Product ID per SCSI SPC-3. This
value will be reflected in the Standard INQUIRY data returned
for the device. The default is COMSTAR.

serial=string
Serial Number. Specifies the SCSI Vital Product Data Serial
Number (page 80h). It is a character value up to 252 bytes in
length. There is no default value.

vid=string
8 bytes ASCII string defining Vendor ID per SCSI SPC-3. This
value will be reflected in the Standard INQUIRY data returned
for the device. The default is SUN.

The following logical unit properties can be set when creating LU using
create-lu subcommand or modified using modify-lu subcommand:

alias=string
Up to 255 characters, representing a user-defined name for the
device. The default is the name of the backing store.

mgmt-url=string
Up to 1024 characters representing a Management Network Address
URL. More than one URL can be passed as a single parameter by
using space-delimited URLs enclosed inside a single pair of
quotation marks (").

wcd=true|false
Write-back cache disable. Determines write-back cache disable
behavior. The default is the write-back cache setting of the
backing store device specified by the lu-file argument.

wp=true|false
Write-protect bit. Determines whether the device reports as
write-protected. The default is false.

Subcommands

The stmfadm command supports the subcommands listed below.

stmfadm add-hg-member -g host-group initiator...
Add a host group member to a host group.

An initiator cannot be a member of more than one host group.

-g,--group-name host-group
Specifies group name. host-group must be an existing
group created using the create-hg subcommand.

stmfadm add-tg-member -g target-group target...
Add a target group member to a target group.

A target cannot be a member of more than one target group.

-g,--group-name target-group
Specifies group name. target-group must be an existing
group created using the create-tg subcommand.

stmfadm add-view [-h host-group] [-n lu-number] [-t target-group]
lu-name
Add a logical unit view entry to a logical unit lu-name, where
lu-name is the STMF name for the logical unit as displayed by
the list-lu subcommand. The add-view subcommand provides the
user with a mechanism to implement access control for a logical
unit and also provides a means of assigning a logical unit
number to a logical unit for a given set of initiators and
targets. A logical unit will not be available to any
initiators until at least one view is applied. Each view entry
gets assigned an entry name, which can be used to reference the
entry in the list-view and remove-view subcommands.

-h,--host-group host-group
host-group is the name of an host group previously
created using create-hg subcommand. If this option is
not specified, the logical unit will be available to
all initiators that log in to the STMF framework.

-n,--lun lu-number
lu-number is an integer in the range 0-16383 to be
assigned to the logical unit for this view entry. If
this option is not specified, a logical unit number
will be assigned by the STMF framework.

-t,--target-group target-group
target-group is the name of a target group previously
created using create-tg subcommand. If this option is
not specified, the logical unit will be available
through all targets.

stmfadm create-hg group-name
Create a host group with the name group-name. group-name is a
string of Unicode characters with a maximum length of 255. The
group name must be unique within the STMF system.

stmfadm create-lu [-p property=value]... [-s size] lu-file
Create a logical unit that can be registered with STMF.
lu-file is the file to be used as the backing store for the
logical unit. If the -s option is not specified, the size of
the specified lu-file will be used as the size of the logical
unit.

Logical units registered with the STMF require space for the
metadata to be stored. When a zvol is specified as the backing
store device, the default will be to use a special property of
the zvol to contain the metadata. For all other devices, the
default behavior will be to use the first 64k of the device.
An alternative approach would be to use the meta property in a
create-lu subcommand to specify an alternate file to contain
the metadata. It is advisable to use a file that can provide
sufficient storage of the logical unit metadata, preferably
64k.

-p,--lu-prop property=value
Set specified logical unit property. Check Logical
Unit Properties for the list of available properties.

-s,--size size
size is an integer followed by one of the following
letters, to indicate a unit of size: k, m, g, t, p, e,
specifying kilobyte, megabyte, gigabyte, terabyte,
petabyte and exabyte respectively.

stmfadm create-tg group-name
Create a target group with the name group-name. group-name is
a string of Unicode characters with a maximum length of 255.
The group name must be unique within the STMF system.

stmfadm delete-hg group-name
Delete the host group identified by group-name.

stmfadm delete-lu [-k] lu-name
Delete an existing logical unit that was created using
create-lu subcommand. This effectively unloads the logical
unit from the STMF framework. Any existing data on the logical
unit remains intact.

-k,--keep-views
Keep view entries for this logical unit.

stmfadm delete-tg group-name
Delete the target group identified by group-name.

stmfadm import-lu lu-file
Import and load a logical unit into the STMF that was
previously created using create-lu subcommand and was then
deleted from the STMF using delete-lu subcommand. On success,
the logical unit is again made available to the STMF. lu-file
is the filename used in the create-lu subcommand. If this
logical unit is using a separate metadata file, the filename in
the meta property value that was used in the create-lu
subcommand must be used here.

stmfadm list-hg [-v] [host-group]...
List information for the host group in the system referenced by
host-group. If host-group is not specified, all host groups in
the system will be listed.

-v,--verbose
Display all host group members.

stmfadm list-lu [-v] [lu-name]...
List information for the logical unit in the system referenced
by lu-name. If lu-name is not specified, all logical units in
the system will be listed.

-v,--verbose
Display verbose information about the logical unit.

stmfadm list-state
List the operational and configuration state of the STMF.

stmfadm list-target [-v] [target]...
List information for the target port in the system referenced
by target. If target name is not specified, all target ports
in the system will be listed.

-v,--verbose
Display verbose information about the target along with
SCSI session information for logged-in initiators.

stmfadm list-tg [-v] [target-group]...
List information for the target group in the system referenced
by target-group. If target-group is not specified, all target
groups in the system will be listed.

-v,--verbose
Display all group members.

stmfadm list-view -l lu-name [view]...
List the view entry for the logical unit referenced by lu-name.
If view is not specified, all view entries for the specified
logical unit will be listed.

-l,--lu-name lu-name
Specify logical unit.

stmfadm modify-lu [-f] [-p property=value]... [-s size] lu-arg
Modify attributes of a logical unit created using the create-lu
subcommand. If -f is not specified, lu-arg is interpreted as
lu-name.

-f,--file
If specified, lu-arg is interpreted as file name. This
provides the ability to modify a logical unit that is
not currently imported into the STMF.

-p,--lu-prop property
Modify specified logical unit property. See Logical
Unit Properties for the list of available properties.

-s,--size size
size is an integer followed by one of the following
letters, to indicate a unit of size: k, m, g, t, p, e,
specifying kilobyte, megabyte, gigabyte, terabyte,
petabyte and exabyte respectively.

stmfadm offline-lu lu-name
Offline a logical unit currently registered with the STMF.

stmfadm offline-target target-name
Offline the specified target.

stmfadm online-lu lu-name
Online a logical unit currently registered with the STMF.

stmfadm online-target target
Online the specified target.

stmfadm remove-hg-member -g host-group initiator
Remove specified initiator from host group

-g,--group-name host-group
Specifies group name. host-group must be an existing
group created using the create-hg subcommand.

stmfadm remove-tg-member -g target-group target
Remove specified target from target group.

-g,--group-name taget-group
Specifies group name. target-group must be an existing
group created using the create-tg subcommand.

stmfadm remove-view [-a] -l lu-name view...
Remove one or more view entries from a logical unit.

-a,--all
Remove all view entries for this logical unit.

-l,--lu-name
Specify logical unit.

EXAMPLES

Example 1 Creating a Host group with Two Initiator Ports
The following commands use the create-hg and add-hg-member
subcommands to create a host group and add two initiator ports
to that host group.

# stmfadm create-hg HostA
# stmfadm add-hg-member -g HostA wwn.210105b0000d92d0

Example 2 Adding a View Entry to a Logical Unit
The following command uses the add-view subcommand to allow
access from HostA to a logical unit.

# stmfadm add-view -h HostA 6000AE40C5000000000046FC4FEA001C

Example 3 Listing a View Entry
The following command uses the list-view subcommand to list all
view entries for the specified logical unit.

# stmfadm list-view -l 6000AE40C5000000000046FC4FEA001C
View Entry: 0
Host group : HostA
Target group : All
LUN : 0

INTERFACE STABILITY

Committed

SEE ALSO

attributes(7), sbdadm(8)

illumos March 1, 2016 illumos