.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 2017 Nexenta Systems, Inc.
.\"
.Dd March 1, 2016
.Dt STMFADM 8
.Os
.Sh NAME
.Nm stmfadm
.Nd SCSI target mode framework command line interface
.Sh SYNOPSIS
.Nm
.Cm add-hg-member
.Fl g Ar host-group
.Ar initiator Ns ...
.Nm
.Cm add-tg-member
.Fl g Ar target-group
.Ar target Ns ...
.Nm
.Cm add-view
.Op Fl h Ar host-group
.Op Fl n Ar lu-number
.Op Fl t Ar target-group
.Ar lu-name
.Nm
.Cm create-hg
.Ar group-name
.Nm
.Cm create-lu
.Oo Fl p Ar property Ns = Ns Ar value Oc Ns ...
.Op Fl s Ar size
.Ar lu-file
.Nm
.Cm create-tg
.Ar group-name
.Nm
.Cm delete-hg
.Ar group-name
.Nm
.Cm delete-lu
.Op Fl k
.Ar lu-name
.Nm
.Cm delete-tg
.Ar group-name
.Nm
.Cm import-lu
.Ar lu-file
.Nm
.Cm list-hg
.Op Fl v
.Oo Ar host-group Oc Ns ...
.Nm
.Cm list-lu
.Op Fl v
.Oo Ar lu-name Oc Ns ...
.Nm
.Cm list-state
.Nm
.Cm list-target
.Op Fl v
.Oo Ar target Oc Ns ...
.Nm
.Cm list-tg
.Op Fl v
.Oo Ar target-group Oc Ns ...
.Nm
.Cm list-view
.Fl l Ar lu-name
.Oo Ar view Oc Ns ...
.Nm
.Cm modify-lu
.Op Fl f
.Oo Fl p Ar property Ns = Ns Ar value Oc Ns ...
.Op Fl s Ar size
.Ar lu-arg
.Nm
.Cm offline-lu
.Ar lu-name
.Nm
.Cm offline-target
.Ar target
.Nm
.Cm online-lu
.Ar lu-name
.Nm
.Cm online-target
.Ar target
.Nm
.Cm remove-hg-member
.Fl g Ar host-group
.Ar initiator Ns ...
.Nm
.Cm remove-tg-member
.Fl g Ar target-group
.Ar target Ns ...
.Nm
.Cm remove-view
.Op Fl a
.Fl l Ar lu-name
.Ar view Ns ...
.Sh DESCRIPTION
The
.Nm
command configures logical units within the SCSI Target Mode Framework
.Pq STMF
framework.
The framework and this man page use the following terminology:
.Bl -tag -width Ds
.It Sy initiator
A device responsible for issuing SCSI I/O commands to a SCSI target and logical
unit.
.It Sy target
A device responsible for receiving SCSI I/O commands for a logical unit.
.It Sy logical unit
A device within a target responsible for executing SCSI I/O commands.
.It Sy logical unit number
The identifier of a logical unit within a target.
.It Sy host group
An host group is a set of one or more initiators that are combined for the
purposes of being applied to a
.Sy view
.Pq see below .
An initiator cannot be a member of more than one host group.
.It Sy target group
A target group is a set of one or more SCSI target ports that are treated the
same when creating a
.Sy view
.Pq see below .
The set of logical units that a particular SCSI initiator can see is determined
by the combined set of views.
.Pp
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.
.It Sy 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.
.El
.Ss Logical Unit Properties
The following logical unit properties can be set only when creating LU using
.Cm create-lu
subcommand:
.Bl -tag -width Ds
.It Sy blk Ns = Ns Ar num
Specifies the block size for the device.
The default is 512.
.It Sy guid Ns = Ns Ar string
32 hexadecimal ASCII characters representing a valid NAA Registered Extended
Identifier.
The default is set by the STMF to a generated value.
.It Sy meta Ns = Ns Ar path
Metadata file name.
When specified, will be used to hold the SCSI metadata for the logical unit.
There is no default.
.It Sy oui Ns = Ns Ar string
Organizational Unique Identifier.
Six hexadecimal ASCII characters representing the IEEE OUI company ID
assignment.
This will be used to generate the device identifier
.Pq GUID .
The default is
.Sy 00144F .
.It Sy pid Ns = Ns Ar 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
.Sy COMSTAR .
.It Sy serial Ns = Ns Ar string
Serial Number.
Specifies the SCSI Vital Product Data Serial Number
.Pq page 80h .
It is a character value up to 252 bytes in length.
There is no default value.
.It Sy vid Ns = Ns Ar 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
.Sy SUN .
.El
.Pp
The following logical unit properties can be set when creating LU using
.Cm create-lu
subcommand or modified using
.Cm modify-lu
subcommand:
.Bl -tag -width Ds
.It Sy alias Ns = Ns Ar string
Up to 255 characters, representing a user-defined name for the device.
The default is the name of the backing store.
.It Sy mgmt-url Ns = Ns Ar 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
.Pq Sy \(dq .
.It Sy wcd Ns = Ns Sy true Ns | Ns Sy 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
.Ar lu-file
argument.
.It Sy wp Ns = Ns Sy true Ns | Ns Sy false
Write-protect bit.
Determines whether the device reports as write-protected.
The default is
.Sy false .
.El
.Ss Subcommands
The
.Nm
command supports the subcommands listed below.
.Bl -tag -width Ds
.It Xo
.Nm
.Cm add-hg-member
.Fl g Ar host-group
.Ar initiator Ns ...
.Xc
Add a host group member to a host group.
.Pp
An initiator cannot be a member of more than one host group.
.Bl -tag -width Ds
.It Fl g Ns \&, Ns Fl -group-name Ar host-group
Specifies group name.
.Ar host-group
must be an existing group created using the
.Cm create-hg
subcommand.
.El
.It Xo
.Nm
.Cm add-tg-member
.Fl g Ar target-group
.Ar target Ns ...
.Xc
Add a target group member to a target group.
.Pp
A target cannot be a member of more than one target group.
.Bl -tag -width Ds
.It Fl g Ns \&, Ns Fl -group-name Ar target-group
Specifies group name.
.Ar target-group
must be an existing group created using the
.Cm create-tg
subcommand.
.El
.It Xo
.Nm
.Cm add-view
.Op Fl h Ar host-group
.Op Fl n Ar lu-number
.Op Fl t Ar target-group
.Ar lu-name
.Xc
Add a logical unit view entry to a logical unit
.Ar lu-name ,
where
.Ar lu-name
is the STMF name for the logical unit as displayed by the
.Cm list-lu
subcommand.
The
.Cm 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
.Cm list-view
and
.Cm remove-view
subcommands.
.Bl -tag -width Ds
.It Fl h Ns \&, Ns Fl -host-group Ar host-group
.Ar host-group
is the name of an host group previously created using
.Cm 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.
.It Fl n Ns \&, Ns Fl -lun Ar lu-number
.Ar 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.
.It Fl t Ns \&, Ns Fl -target-group Ar target-group
.Ar target-group
is the name of a target group previously created using
.Cm create-tg
subcommand.
If this option is not specified, the logical unit will be available through all
targets.
.El
.It Xo
.Nm
.Cm create-hg
.Ar group-name
.Xc
Create a host group with the name
.Ar group-name .
.Ar group-name
is a string of Unicode characters with a maximum length of 255.
The group name must be unique within the STMF system.
.It Xo
.Nm
.Cm create-lu
.Oo Fl p Ar property Ns = Ns Ar value Oc Ns ...
.Op Fl s Ar size
.Ar lu-file
.Xc
Create a logical unit that can be registered with STMF.
.Ar lu-file
is the file to be used as the backing store for the logical unit.
If the
.Fl s
option is not specified, the size of the specified
.Ar lu-file
will be used as the size of the logical unit.
.Pp
Logical units registered with the STMF require space for the metadata to be
stored.
When a
.Sy zvol
is specified as the backing store device, the default will be to use a special
property of the
.Sy 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
.Sy meta
property in a
.Cm 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.
.Bl -tag -width Ds
.It Fl p Ns \&, Ns Fl -lu-prop Ar property Ns = Ns Ar value
Set specified logical unit property.
Check
.Sx Logical Unit Properties
for the list of available properties.
.It Fl s Ns \&, Ns Fl -size Ar size
.Ar size
is an integer followed by one of the following letters, to indicate a unit of
size:
.Sy k , m , g , t , p , e ,
specifying kilobyte, megabyte, gigabyte, terabyte, petabyte and exabyte
respectively.
.El
.It Xo
.Nm
.Cm create-tg
.Ar group-name
.Xc
Create a target group with the name
.Ar group-name .
.Ar group-name
is a string of Unicode characters with a maximum length of 255.
The group name must be unique within the STMF system.
.It Xo
.Nm
.Cm delete-hg
.Ar group-name
.Xc
Delete the host group identified by
.Ar group-name .
.It Xo
.Nm
.Cm delete-lu
.Op Fl k
.Ar lu-name
.Xc
Delete an existing logical unit that was created using
.Cm create-lu
subcommand.
This effectively unloads the logical unit from the STMF framework.
Any existing data on the logical unit remains intact.
.Bl -tag -width Ds
.It Fl k Ns \&, Ns Fl -keep-views
Keep view entries for this logical unit.
.El
.It Xo
.Nm
.Cm delete-tg
.Ar group-name
.Xc
Delete the target group identified by
.Ar group-name .
.It Xo
.Nm
.Cm import-lu
.Ar lu-file
.Xc
Import and load a logical unit into the STMF that was previously created using
.Cm create-lu
subcommand and was then deleted from the STMF using
.Cm delete-lu
subcommand.
On success, the logical unit is again made available to the STMF.
.Ar lu-file
is the filename used in the
.Cm create-lu
subcommand.
If this logical unit is using a separate metadata file, the filename in the
.Sy meta
property value that was used in the
.Cm create-lu
subcommand must be used here.
.It Xo
.Nm
.Cm list-hg
.Op Fl v
.Oo Ar host-group Oc Ns ...
.Xc
List information for the host group in the system referenced by
.Ar host-group .
If
.Ar host-group
is not specified, all host groups in the system will be listed.
.Bl -tag -width Ds
.It Fl v Ns \&, Ns Fl -verbose
Display all host group members.
.El
.It Xo
.Nm
.Cm list-lu
.Op Fl v
.Oo Ar lu-name Oc Ns ...
.Xc
List information for the logical unit in the system referenced by
.Ar lu-name .
If
.Ar lu-name
is not specified, all logical units in the system will be listed.
.Bl -tag -width Ds
.It Fl v Ns \&, Ns Fl -verbose
Display verbose information about the logical unit.
.El
.It Xo
.Nm
.Cm list-state
.Xc
List the operational and configuration state of the STMF.
.It Xo
.Nm
.Cm list-target
.Op Fl v
.Oo Ar target Oc Ns ...
.Xc
List information for the target port in the system referenced by
.Ar target .
If target name is not specified, all target ports in the system will be listed.
.Bl -tag -width Ds
.It Fl v Ns \&, Ns Fl -verbose
Display verbose information about the target along with SCSI session information
for logged-in initiators.
.El
.It Xo
.Nm
.Cm list-tg
.Op Fl v
.Oo Ar target-group Oc Ns ...
.Xc
List information for the target group in the system referenced by
.Ar target-group .
If
.Ar target-group
is not specified, all target groups in the system will be listed.
.Bl -tag -width Ds
.It Fl v Ns \&, Ns Fl -verbose
Display all group members.
.El
.It Xo
.Nm
.Cm list-view
.Fl l Ar lu-name
.Oo Ar view Oc Ns ...
.Xc
List the view entry for the logical unit referenced by
.Ar lu-name .
If
.Ar view
is not specified, all view entries for the specified logical unit will be
listed.
.Bl -tag -width Ds
.It Fl l Ns \&, Ns Fl -lu-name Ar lu-name
Specify logical unit.
.El
.It Xo
.Nm
.Cm modify-lu
.Op Fl f
.Oo Fl p Ar property Ns = Ns Ar value Oc Ns ...
.Op Fl s Ar size
.Ar lu-arg
.Xc
Modify attributes of a logical unit created using the
.Cm create-lu
subcommand.
If
.Fl f
is not specified,
.Ar lu-arg
is interpreted as
.Ar lu-name.
.Bl -tag -width Ds
.It Fl f Ns \&, Ns Fl -file
If specified,
.Ar lu-arg
is interpreted as file name.
This provides the ability to modify a logical unit that is not currently
imported into the STMF.
.It Fl p Ns \&, Ns Fl -lu-prop Ar property
Modify specified logical unit property.
See
.Sx Logical Unit Properties
for the list of available properties.
.It Fl s Ns \&, Ns Fl -size Ar size
.Ar size
is an integer followed by one of the following letters, to indicate a unit of
size:
.Sy k , m , g , t , p , e ,
specifying kilobyte, megabyte, gigabyte, terabyte, petabyte and exabyte
respectively.
.El
.It Xo
.Nm
.Cm offline-lu
.Ar lu-name
.Xc
Offline a logical unit currently registered with the STMF.
.It Xo
.Nm
.Cm offline-target
.Ar target-name
.Xc
Offline the specified target.
.It Xo
.Nm
.Cm online-lu
.Ar lu-name
.Xc
Online a logical unit currently registered with the STMF.
.It Xo
.Nm
.Cm online-target
.Ar target
.Xc
Online the specified target.
.It Xo
.Nm
.Cm remove-hg-member
.Fl g Ar host-group
.Ar initiator
.Xc
Remove specified
.Ar initiator
from host group
.Bl -tag -width Ds
.It Fl g Ns \&, Ns Fl -group-name Ar host-group
Specifies group name.
.Ar host-group
must be an existing group created using the
.Cm create-hg
subcommand.
.El
.It Xo
.Nm
.Cm remove-tg-member
.Fl g Ar target-group
.Ar target
.Xc
Remove specified
.Ar target
from target group.
.Bl -tag -width Ds
.It Fl g Ns \&, Ns Fl -group-name Ar taget-group
Specifies group name.
.Ar target-group
must be an existing group created using the
.Cm create-tg
subcommand.
.El
.It Xo
.Nm
.Cm remove-view
.Op Fl a
.Fl l Ar lu-name
.Ar view Ns ...
.Xc
Remove one or more view entries from a logical unit.
.Bl -tag -width Ds
.It Fl a Ns \&, Ns Fl -all
Remove all view entries for this logical unit.
.It Fl l Ns \&, Ns Fl -lu-name
Specify logical unit.
.El
.El
.Sh EXAMPLES
.Bl -tag -width Ds
.It Sy Example 1 No Creating a Host group with Two Initiator Ports
The following commands use the
.Cm create-hg
and
.Cm add-hg-member
subcommands to create a host group and add two initiator ports to that host
group.
.Bd -literal
# stmfadm create-hg HostA
# stmfadm add-hg-member -g HostA wwn.210105b0000d92d0
.Ed
.It Sy Example 2 No Adding a View Entry to a Logical Unit
The following command uses the
.Cm add-view
subcommand to allow access from
.Sy HostA
to a logical unit.
.Bd -literal
# stmfadm add-view -h HostA 6000AE40C5000000000046FC4FEA001C
.Ed
.It Sy Example 3 No Listing a View Entry
The following command uses the
.Cm list-view
subcommand to list all view entries for the specified logical unit.
.Bd -literal
# stmfadm list-view -l 6000AE40C5000000000046FC4FEA001C
View Entry: 0
    Host group   : HostA
    Target group : All
    LUN          : 0
.Ed
.El
.Sh INTERFACE STABILITY
.Sy Committed
.Sh SEE ALSO
.Xr attributes 7 ,
.Xr sbdadm 8