iscsitadm(1M) System Administration Commands iscsitadm(1M)NAMEiscsitadm - administer iSCSI targets
SYNOPSISiscsitadm create [-? | --help] object [-? | --help]
[options] operand
iscsitadm modify [-? | --help] object [-? | --help]
[options] operand
iscsitadm delete [-? | --help] object [-? | --help]
[options] operand
iscsitadm list [-? | --help] object [-? | --help] [options]
operand
iscsitadm show [-? | --help] admin
iscsitadm show [-? | --help] object [-? | --help] [options]
[operand]
iscsitadm -? --help
DESCRIPTION
The iscsitadm command enables you to manage Internet SCSI (iSCSI) tar‐
get nodes. It is a companion to iscsiadm(1M), which enables you to man‐
age iSCSI initiator nodes.
The iscsitadm command has the following subcommands:
create Creates a target using a local target as a reference.
modify Modifies a target or a list of targets.
delete Deletes a target or a list of targets.
list Lists names and information about targets.
show Displays target-related statistics.
The preceding subcommands work on the following objects:
target An iSCSI target node, or list of target nodes.
initiator An iSCSI initiator node, or list of initiator nodes.
admin Stores administrative information, such as server loca‐
tions and passwords.
tpgt Stands for TargetPortGroupTag. A number that represents a
list of connections that an initiator can use for a given
target.
stats Displays statistics; can accept interval and count values.
Used only with the show subcommand.
These objects are discussed in greater detail under the options
descriptions for each subcommand.
As indicated in the SYNOPSIS, iscsitadm has two levels of help. If you
invoke -? or --help following a subcommand, the command displays avail‐
able operands, options, and objects. If you invoke an help option fol‐
lowing an object, iscsitadm displays options and operands.
OPTIONS
The iscsitadm options and objects are discussed below in the context of
each subcommand. Note that the help options (-? or --help) are invoked
as shown in the SYNOPSIS. See EXAMPLES.
create Options
The following are the options and objects for the create subcommand:
target --size|-z lun_size [--lun number]
[--type disk|tape|raw] [--backing-store|-b pathname] local_name
Create a target using local_name as a reference. local_name is only
used within the context iscsitgtd. --size is a multiplier and is
specified as a number followed by a single letter. The letter is
one of:
k kilobyte
m megabyte
g gigabyte
t terabyte
--lun specifies the logical unit number. --type specifies which
type of emulation will occur for the LUN. disk and tape are the
familiar devices. raw indicates that the emulator will use the
uSCSI interface and pass the command blocks directly to and from
the device. The use of raw also implies the option --backing-store
will be entered. The argument to this option is the full pathname
to the device node normally found in /dev. If you use --backing-
store, the size of the store is determined by a SCSI READ_CAPACITY
command or, if the backing store is a regular file, by stat(2).
If local_name already exists, a new target name is not generated
for this LUN. The LUN is created within the local_name storage
hierarchy. You can use the --backing-store option to specify a dif‐
ferent location for the data. If you use --backing-store, it is up
to you to allocate actual storage instead of having the target cre‐
ate the data file.
initiator --iqn|-n iSCSI_node_name local_initiator
To use access control lists you must know the name of the initia‐
tor. Since the iSCSI initiator name can be quite long (223 bytes)
and made up of a long list of numbers, it is best to enter this
information once and then refer to the initiator using a simplified
name of local_initiator.
tpgt tpgt_number
If a host has multiple NICs, you might want to limit the number of
connections that an initiator can use for a given target. To estab‐
lish this limit, you must first create a TargetPortGroupTag (TPGT),
which can be any number from 1 to 65535. Once this tag is created,
the IP addresses of the NICs can be added to the TPGT, using the
modify subcommand. Then, the TPGT can itself be added to the tar‐
get.
modify Options
The following are the options and objects for the modify subcommand:
target --tpgt|-p local_tpgt local_target
Specifies one or more target portal groups to use when initiators
reference local_target during discovery.
target --acl|-l local_initiator local_target
Adds to the list a local initiator that can access local_target. By
adding an initiator to a target all initiators from that point on
must be in the ACL.
target --alias|-a TargetAlias local_target
Sets the alias if it was not done during the creation of the target
or change an existing target's alias.
target --maxrecv|-m value local_target
Sets the MaxRecvDataSegmentLength, which can be any value between
512 to (2^24 - 1). You can use this option to limit the amount of
memory used by the target.
initiator --chap-secret|-C local_initiator
Prompts the user to enter the value, using getpassphrase(3C). Asso‐
ciates the secret used for CHAP authentication during login with
local_initiator.
initiator --chap-name|-H value local_initiator
Specifies the CHAP username used during authentication.
tpgt --ip-address|-i address tpgt_number
Adds the NIC's address to tpgt_number.
admin --base-directory|-d directory
Sets the location of where to store the data files that represent
the individual LUNs. This should be done before any other function
is performed. Otherwise, an error will be generated when attempting
to set a persistent value.
admin --chap-secret|-C
Upon entering this option, you will be prompted to enter the value
using getpassphrase(3C). For bidirectional authentication, this is
the value used to generate a response to the initiator's challenge.
admin --chap-name|-H value
Specifies the user name portion of the CHAP protocol.
admin --radius-access|-R enable | disable
Enables or disables the use of the RADIUS server. Even with a
RADIUS server address defined, the use of that server must be
enabled. If the server becomes inaccessible and you need to fall
back on configuration file access, you can use this option to dis‐
able the server.
admin --radius-server|-r hostname:port
Location of RADIUS server. hostname can be either a resolvable name
or an IP address.
admin --radius-secret|-P
Used to initiate contact with the RADIUS server. Interaction with
server uses getpassphrase(3C).
admin --isns-access|-S enable | disable
Enables or disables access to an iSNS server. iSNS servers broad‐
cast their locations.
admin --isns-server|-s hostname
Location of the iSNS server. "hostname" can be either a resolvable
host name or an IP address.
admin --fast-write-ack|-f enable | disable
Enables or disables fast-write acknowledgment. You should enable
this option only if a system is connected to the power grid through
a UPS. Otherwise, data corruption could occur if power is lost and
some writes that were acknowledged have not been completely flushed
to the backing store.
delete Options
The following are the options and objects for the delete subcommand:
target --lun|-u lun_number local_target
Removes information about the LUN identified by lun_number. This
includes the data that is stored in the LUNs.
target --acl|-l local_initiator local_target
Remove access to local_target by local_initiator. If the initiator
is currently logged into the target, this option sends an asynchro‐
nous event message to the initiator.
target --tpgt|-p local_tpgt local_target
Removes the local_tpgt from local_target. Does not affect existing
connections.
initiator --all|-A local_initiator
Removes information about local_initiator. Does not affect current
connections. This option search all targets, seeking those that
reference local_initiator. On these, it performs the action defined
by the command:
# iscsitadm delete target --acl local_initiator target
tpgt --all|-A tpgt_number
Removes from the system all knowledge of the target portal group
identified by tpgt_number. This includes removal of the references
by targets to this group.
tpgt --ip-address|-i address tpgt_number
Removes a NIC's address from the target portal group identified by
tpgt_number. Does not affect current connections.
list Options
The following are the options and objects for the list subcommand:
target [--verbose] [local_target]
target [-v|-s num] [local_target]
By default, displays a list of target local names followed by the
iSCSI TargetName, as it was created. By specifying local_target,
the same information is displayed for that target and can be used
to validate the name of local_target. With the --verbose option,
information about the target's LUNs and current connections is dis‐
played.
You can use the iostat(1M) command to obtain information on the
number of SCSI commands issued and sectors read and written.
initiator [--verbose|-v] local_initiator
Displays detailed information about local_initiator. Among this
data is CHAP information, what target portal groups this initiator
belongs to, and any available connections.
tpgt [--verbose|-v] tpgt_number
Displays detailed information about target group identified by
tpgt_number. Among this data is the list of NICs that are a part of
this target group.
show Options
The following are the options and objects for the show subcommand:
admin
Displays a list of administrative information, including the base
directory used by the target, CHAP, RADIUS, iSNS, and if fast
writes are enabled.
stats [--interval|-I seconds [--count|-N value]] [local_target]
Displays statistics for all available targets, unless you specify
local_target, in which case, displays statistics only for
local_target. If you use --interval, displays statistics for an
interval specified by seconds. If you do not specify --count, the
display continues until you enter a Control-C.
EXAMPLES
Example 1 Invoking Help
All of the commands shown below are valid ways of invoking help.
# iscsitadm -?
# iscsitadm modify -?
# iscsitadm modify target -?
# iscsitadm--help
# iscsitadm create --help
# iscsitadm create tpgt --help
Example 2 Establishing Backing Store
The following command establishes the default location for the backing
store. In addition to the backing store, certain configuration files
will be stored in the same location.
# iscsitadm modify admin --base-directory /zfs/data/targets
The short form of the --base-directory option is -d.
Example 3 Simplest-Case Target Creation
The following command creates a target that will emulate an LBA device
that has 10 GB of storage available. With the base directory set up and
as well as a single target, it is possible to use the system as an
iSCSI target. Note that because the LUN is not specified on the command
line, it reverts to the default, 0.
# iscsitadm create target --size 10g play_area
The short form of the --size option is -z.
Example 4 Creating with Both Size and Backing Store
The following iscsitadm create command specifies LUN size and a backing
store location. The result of this command is that the daemon will cre‐
ate a LUN file at the named location, of the specified size (20 GB).
# iscsitadm create target -z 20g -b /zfs/mirror/data/payroll payroll
A target such as the one created by the preceding command might be use‐
ful, for example, when most of the LUN can be created in a default
area, using whatever redundancy is provided by the underlying file sys‐
tem. Alternatively, you might want to create a special LUN on a higher
speed storage medium or one with better failover characteristics.
The long form of the -z option is --size. The long form of the -b
option is --backing-store
Example 5 Specifying a Local Name for a SCSI Initiator
Consider that you want to restrict access to the payroll target, cre‐
ated in the previous example, to a limited set of initiators. Because
the initiator names can be quite long (and therefore prone to be
entered incorrectly), you create a local name for each initiator, as in
the command below.
# iscsitadm create initiator --iqn \
iqn.1986-03.com.example[node name continues...] multistrada
The short form of the --iqn option is -q.
Example 6 Granting an Initiator Access to a Target
Upon completion of the command below, only the initiator multistrada is
allowed to log into the daemon and access the payroll target. This
presents a potential gap in security, which is addressed in the follow‐
ing example.
# iscsitadm modify target --acl multistrada payroll
The short form of the --acl option is -l.
Example 7 Adding CHAP Secret and Name for an Initiator
The initiator is allowed to identify itself. Because of this, it is
prudent to add a CHAP secret an name for an initiator. This is accom‐
plished with the following command.
# iscsitadm modify initiator -C multistrada
The preceding command prompts you for a secret to use. This must be the
same secret that was setup on the initiator with the local name of mul‐
tistrada. If it is not, the target daemon will issue a challenge to
multistrada when it attempts to login. A non-matching response will
cause the target to drop the connection. If you have many targets that
require authentication, it is probably best to setup a RADIUS server to
administer the secrets.
The long form of the -C option is --chap-secret.
Example 8 Displaying Target Information
The following commands displays information about iSCSI targets.
# iscsitadm list target
Target: vol0
iSCSI Name: iqn.1986-03.com.sun:01:00093d12170c.434c5250.vol0
Target: disk0
iSCSI Name: iqn.1986-03.com.sun:01:00093d12170c.434c6f05.disk0
The following command differs from the preceding in that it uses the
verbose (-v) option and it specifies a single target.
# iscsitadm list target -v vol0
Target: vol0
iSCSI Name: iqn.1986-03.com.sun:01:00093d12170c.434c5250.vol0
ACL list:
TPGT list:
LUN information:
LUN: 0
GUID: 010000093d12170c00002a00434c5251
VID: SUN
PID: SOLARIS
Type: raw
Size: 0x1400000 blocks
Example 9 Displaying Administrative Information
The following command uses the show subcommand to display administra‐
tive information.
# iscsitadm show admin
iscsitadm:
Base Directory: /zfs/stress/play/targets
CHAP Name: Not set
RADIUS Access: Not set
RADIUS Server: Not set
iSNS Access: Not set
Fast Write ACK: Not set
Example 10 Displaying Statistics
The following command uses the show subcommand to display statistics.
# iscsitadm show stats
operations bandwidth
device read write read write
----------------------------------------
vol0 0 0 0K 0K
disk0 0 0 0K 0K
EXIT STATUS
0 Command successful.
>0 An error occurred.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWiscsitgtu │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Volatile │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOiostat(1M), iscsiadm(1M), getpassphrase(3C), attributes(5), rbac(5),
smf(5)NOTES
This command set is considered to be experimental. Future releases,
both minor and micro, might introduce incompatible changes to the com‐
mand set. A future release will stabilize the command set. Any future
changes in stability level will be reflected in the ATTRIBUTES section
of this man page.
The iSCSI Target daemon, iscsitgtd, is managed by the service manage‐
ment facility (smf(5)), under the fault management resource identifier
(FMRI):
svc:/system/iscsitgt:default
Use iscsitadm to perform administrative actions, such as are performed
by the create, modify, and delete subcommands, on iSCSI Target proper‐
ties. Such actions require that you become superuser or assume the Pri‐
mary Administrator role. See rbac(5).
SunOS 5.10 31 Oct 2008 iscsitadm(1M)
