opensolaris iscsitadm man page on unix.com

iscsitadm(1M) System Administration Commands iscsitadm(1M)

NAME
iscsitadm - administer iSCSI targets

SYNOPSIS
iscsitadm 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) target nodes. It is a companion to iscsiadm(1M), which enables you to
manage 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 locations 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
available operands, options, and objects. If you invoke an help option following 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 famil-
iar 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 hierar-
chy. You can use the --backing-store option to specify a different location for the data. If you use --backing-store, it is up to you
to allocate actual storage instead of having the target create the data file.

initiator --iqn|-n iSCSI_node_name local_initiator

To use access control lists you must know the name of the initiator. 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 target.

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). Associates 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 disable 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 broadcast 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 ref-
erence 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, informa-
tion about the target's LUNs and current connections is displayed.

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_tar-
get. If you use --interval, displays statistics for an interval specified by seconds. If you do not specify --count, the display con-
tinues 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 com-
mand line, it reverts to the default, 0.

# iscsitadm create target --size 10g playarea

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
create 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 useful, for example, when most of the LUN can be created in a default
area, using whatever redundancy is provided by the underlying file system. 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, created 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 following 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
multistrada. 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 administrative 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:

SEE ALSO
iostat(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 sec-
tion of this man page.

The iSCSI Target daemon, iscsitgtd, is managed by the service management 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 prop-
erties. Such actions require that you become superuser or assume the Primary Administrator role. See rbac(5).

SunOS 5.11 5 Feb 2009 iscsitadm(1M)

opensolaris man page for iscsitadm