This paper will describe the syntax and usage of the iSCSI Target CLI. This document therefore should be used as both input for the CLI man page and a guide towards implementation.
There are four commands which operation on four different objects. The commands are create, modify, remove, and list. The objects are target, initiator, admin, and tpgt. The following sections of this document are divided up amongst the four commands. Within those sections each object and it s options are described.
At a minimum two things must be done before an initiator can connect to the target. One is the setting of the base directory and the second is creating at least one target. There is no requirement that targets have Access Control Lists (ACLs) or target port group tags. They are purely optional.
If the administrator is familiar with Sun s iSCSI initiator one might ask where are the login parameter options. The target takes its cue for the parameters from what the initiator sends across. This way the administrator only has to set them in one location. The exception to this rule is the MaxRecvDataSegmentLength value. This allows the administrator of the target to limit the data sent by a possible overeager initiator.
The CLI may generate warning messages if it determines that an unwise configuration has been created. For example: A local initiator is created without a CHAP secret. That initiator is added to a targets Access Control List(ACL). If a target has an ACL list only those initiators within the ACL may complete the login phase. Now the administrator adds a second initiator to the ACL, but this initiator has a CHAP secret. This second initiator will be required to pass CHAP authentication, but the first will not. Since it s fairly easy to change an initiator name anyone could spoof the login process. So, either all initiators within a targets ACL should have a CHAP secret or none of them should so a warning is generated.
Help will be available at each level using --help or -? which will show the commands or object which are available. An option of --version or -V will display the command s current version data. For example:
-bash-3.00# ./iscsitadm --version
iscsitadm: Version 1.0
For more information, please see iscsitadm(1M)
-bash-3.00# ./iscsitadm --help
Usage: iscsitadm -?,-V,--help
Usage: iscsitadm create [-?] <OBJECT> [-?] [<OPERAND>]
Usage by OBJECT:
iscsitadm create target <OPTIONS> <local-target>
iscsitadm create initiator <OPTIONS> <local-initiator>
iscsitadm create tpgt <local-tpgt>
Usage: iscsitadm list [-?] <OBJECT> [-?] [<OPERAND>]
Usage by OBJECT:
iscsitadm list target [OPTIONS] [<local-target>]
iscsitadm list initiator [OPTIONS] [<local-initiator>]
iscsitadm list tpgt [OPTIONS] [<local-tpgt>]
Usage: iscsitadm modify [-?] <OBJECT> [-?] [<OPERAND>]
Usage by OBJECT:
iscsitadm modify target <OPTIONS> <local-target>
iscsitadm modify initiator <OPTIONS> <local-initiator>
iscsitadm modify admin <OPTIONS>
iscsitadm modify tpgt <OPTIONS> <local-tpgt>
Usage: iscsitadm delete [-?] <OBJECT> [-?] [<OPERAND>]
Usage by OBJECT:
iscsitadm delete target <OPTIONS> <local-target>
iscsitadm delete initiator <OPTIONS> <local-initiator>
iscsitadm delete tpgt <OPTIONS> <local-tpgt>
Usage: iscsitadm show [-?] <OBJECT> [-?] [<OPERAND>]
Usage by OBJECT:
iscsitadm show admin
iscsitadm show stats [OPTIONS] [<local-target>]
For more information, please see iscsitadm(1M)
iscsitadm <command> <object> --optional parameters
create [-?]
target [-?] --size <lun_size> [--lun <lun_number>] [--type <disk|tape|osd|raw>] [--backing-store <pathname>] <local_target>
target [-?] -s <lun_size> [-u <lun_number>] [-t <disk|tape|osd|raw>] [-b <pathname>]
<local_target>
Create a target using local_target as a reference. local_name is only
used within the context iscsitgt. --size is a number followed by a
single letter which is a multiplier. k = kilobyte, m = megabyte, g
= gigabyte, and t = terabyte. --lun is the logical unit number which
will default to 0 if not supplied. --type defines which emulation will
occur for the LUN. disk and tape should be fairly obvious, with
disk being the default. OSD is relatively new and will emulate an
Object Storage Device. A raw type indicates that the emulator will
use the uscsi interface and pass the command blocks directly to/from
the device. The use of raw also implies the option --backing-store
will be given. This is the full pathname to the device node normally
found in /dev and if --backing-store is used the size is optional and
will be determined by a READ_CAPACITY command or if the backing store
is a regular file the size will come from stat(2). If <local_target>
already exists a new TargetName will not be generated for this LUN. The
LUN will be created within the <local_target> storage hierarchy.
--backing-store can be used by the administrator to provide a different
location for the data. It s up to the administrator to allocate actual
storage instead of having the target create the data file.
initiator [-?] --iqn <iSCSI node name> <local_initiator>
initiator [-?] -n <iSCSI node name> <local_initiator>
To use access control lists the name of the initiator must be known.
Since the iSCSI initiator name can be quite long (223 bytes) and made
up from long list of numbers it s best to enter this information once
and then reference the initiator using a simplified name of
<local_initiator>.
tpgt [-?] <tpgt_number>
If this host has multiple NICs it may be desirable to limit the number
of connections that an initiator can use for a given target. First
thing that needs to be done is to create a TargetPortGroupTag which can
be any number from 1 to 65535. Once created the IP addresses of the
NICs can be added to this TPGT using the modify subcommand. Then the
TPGT can be itself added to the target. Since target portal group tags
are simple numbers we will not create a friendly name for them like
what was done for the target and initiators. It s felt that a simple is
easy enough to remember and nice and short.
modify [-?]
target [-?] --tpgt <local_tpgt> <local_target>
target [-?] -p <local_tpgt> <local_target>
Specify one or more target portal groups to use when initiators
reference this target during discovery.
target [-?] --acl <local_initiator> <local_target>
target [-?] -l <local_initiator> <local_target>
Add a local initiator to the list which can access this target. By
adding an initiator to a target all initiators from that point on
must be in the ACL.
target [-?] --alias <TargetAlias> <local_target>
target [-?] -a <TargetAlias> <local_target>
This will set the alias if it wasn t done during the creation of
the target or change an existing target s alias.
target [-?] --maxrecv <value> <local_target>
target [-?] -m <value> <local_target>
This will set the MaxRecvDataSegmentLength which can be any value
between 512 to (2 24 - 1). This helps to limit the amount of
memory used by the target.
initiator [-?] --chap-secret <local_initiator>
initiator [-?] -C <local_initiator>
This option will prompt the user to enter the value using
getpass-phrase( 3C). Associates the secret used for CHAP
authentication during login with the initiator.
initiator [-?] --chap-name <value> <local_initiator>
initiator [-?] -H <value> <local_initiator>
This is the CHAP username which is used during authentication.
tpgt [-?] --ip-address <address> <tpgt_number>
tpgt [-?] -i <address> <tpgt_number>
Add the NICs address to this group.
admin [-?] --base-directory <directory>
admin [-?] -d <directory>
The daemon needs to know the location of where to store the data
files which 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
admin [-?] -C
For bidirectional authentication this is the value used to generate
a response to the initiators challenge. The administrator will be
prompted to enter the value using getpassphrase(3C)
admin [-?] --chap-name <value>
admin [-?] -H <value>
The user name portion of the CHAP protocol.
admin [-?] --radius-access <enable/disable>
admin [-?] -R <enable/disable>
Even with a RADIUS server address defined the use of that server
must be enabled. In case something happens to the server and the
users wishes to fall back on the configuration file access to the
server may be disabled.
admin [-?] --radius-server <hostname:port>
admin [-?] -r <hostname:port>
Location of RADIUS server. hostname can be either a resolvable name
or an IP address.
admin [-?] --radius-secret
admin [-?] -P
Value used to initiate contact with the RADIUS server. See
getpass-phrase( 3C).
admin [-?] --isns-access <enable/disable>
admin [-?] -S <enable/disable>
iSNS servers broadcast their location so to use iSNS all that s
needed by the daemon is to enable it s use. NOTE: Is this a true
statement. Can we assume that if there are two servers it s not
possible to be tricked?
admin [-?] --fast-write-ack <enable/disable>
admin [-?] -f <enable/disable>
This should only be enabled if the system is connected to the power
grid through a UPS. Otherwise data corruption could occur if power
is lost and some writes which were acknowledge haven t been
completely flushed to the backing store.
delete
target [-?] --lun <lun_number> <local_target>
target [-?] -u <lun_number> <local_target>
Remove information about the specific LUN. LUN 0 must be the last
one removed and once that is removed information about the target
will also be removed from the system.
target [-?] --acl <local_initiator> <local_target>
target [-?] -l <local_initiator> <local_target>
Remove access to this target by the initiator. If the initiator is
currently logged into the target will send an asynchronous event
message to the initiator.
target [-?] --tpgt <local_tpgt> <local_target>
target [-?] -p <local_tpgt> <local_target>
Removes the target portal group from this target. Does not effect
existing connections.
initiator [-?] --all <local_initiator>
initiator [-?] -A <local_initiator>
Removes information about this initiator. Does not effect current
connections. This will search all targets finding those who
reference this initiator and perform the same action as defined by
"remove target --name <> --acl <>".
tpgt [-?] --all <tpgt_number>
tpgt [-?] -A <tpgt_number>
Removes all knowledge of this target port group from the system
including removal of the references by targets to this group.
tpgt [-?] --ip-address <address> <tpgt_number>
tpgt [-?] -i <address> <tpgt_number>
Remove a NICs address from this list. Does not affect current connections.
list [-?]
target [-?] [--verbose] [<local_target>]
target [-?] [-v|-s <num>] [<local_target>]
By default this will display a list of target local names followed
by the iSCSI TargetName as it was created. By specifying the
local_target the same information will be displayed just for that
target and can be used to validate that a local_target name is
correct. If the --verbose option is given then information
regarding the targets LUNs and current connections will be
displayed. iostat provides information on the number of SCSI
commands issued and sectors read and written. iostat takes a
number which is the seconds between updates.
initiator [-?] [--verbose] <local_intiator>
initiator [-?] [-v] <local_intiator>
Similar to target with the detailed information being different.
Detailed information will provide CHAP information, what target
portal groups this initiator belongs to, and any connections
available.
tpgt [-?] [--verbose] <tpgt_number>
tpgt [-?] [-v] <tpgt_number>
Similar to target with the detailed information being different.
Detailed information will consist of which NICs are part of this
tpgt.
show [-?]
stats [--interval <seconds> [--count <value>]] [<local_target>]
stats [-I <seconds> [-N <value>]] [<local_target>]
Displays statistics from the target.
admin
This will display information about the base directory used by the
target, CHAP, RADIUS, iSNS, and if fast writes are enabled.
Several usage cases will be shown below which involve creating, removing, and modifying targets and the various components. Only the short single letter options will be used in the examples.
The default location for the backing store plus some configuration files will be located in /zfs/data/targets.
This creates a target which will emulate a LBA device which has 10GB of storage available. This is the simplest form of creating a target. With the base directory setup and this single target it s possible to use the system as an iSCSI target. The default LUN is 0 when not specified on the command line.
Now we ve specified both the size and a backing store location. This means that the daemon is expected to create a LUN file at the named location of a given size. This might be useful for example when most of the LUN should be created in a default area using whatever redundancy is provided by the underlying file system. However occasionally the administrator wishes to create a special LUN on a potentially higher speed storage or one with better failover characteristics.
As the name implies this deletes LUN 0. Since SCSI requires that LUN 0 always be available LUN 0 must be the last one removed. When LUN 0 is removed all information regarding this target is also removed (e.g. if you added an initiator to the targets ACL the ACL is also removed, but not the initiator).
Say we wish to restrict access to the payroll target which was created above to a limited set of initiators. Since the initiator names can be quite long and prone to errors while typing, unless you re able to use cut and paste, we have the administrator first create a local name for each initiator.
Once this is done only the initiator multistrada is allowed to log into the daemon and access the payroll target. Of course, since the initiator is the one to tell us who they are, this isn t enough security so its probably a wise idea to add a CHAP secret and name for multistrada
This command will prompt the administrator for a secret to use. This must be the same secret which was setup on the initiator which we re locally calling multis-trada . If not, the target daemon will issue a challenge to multistrada when it at-tempts to login and the response will not match causing the target to drop the con-nection. If the administrator has many targets which need authentication it s probably best to setup a RADIUS several to administer the secrets.
Here is a sample output from the command with different options:
-bash-3.00# ./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
-bash-3.00# ./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
-bash-3.00# ./iscsitadm show admin
iscsitadm: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
-bash-3.00# ./iscsitadm show stats
operations bandwidth
device read write read write
-------------------- ----- ----- ----- -----
vol0 0 0 0K 0K
disk0 0 0 0K 0K