Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

iscsiadm(8)

Name

iscsiadm - enable management of iSCSI initiators

Synopsis

iscsiadm subcommand direct-object [options] [operand]

Description

The iscsiadm command enables management of the iSCSI (Internet SCSI) initiator on a host. iscsiadm is implemented as a set of subcommands, many with their own options, which are described in the section for that subcommand. Options not associated with a particular subcommand are described under OPTIONS.

iscsiadm works only when the following service is online:

svc:/network/iscsi/initiator:default

The iscsiadm command supports the following subcommands, which are described in detail in subsections that follow:

add

Adds element(s) to an object.

list

Lists element(s) of an object.

modify

Modifies attributes of an object.

remove

Removes an element from an object.

The iscsiadm subcommands operate on a direct-object. These are described in the section for each subcommand.

The iscsiadm command supports the Internet Storage Name Service (iSNS) for the discovery of iSCSI targets. The command supports the Challenge Handshake Authentication Protocol (CHAP) for authentication.

add Subcommand

The syntax for the add subcommand is:

# iscsiadm add direct_object [operands...] 

The add subcommand adds the following direct_objects:

discovery-address discovery-address [...]

Adds a target to a list of discovery addresses. A discovery address (as in the syntax shown below) is an IP address:port combination used in a SendTargets discovery session. Using this discovery approach, a target device can inform an initiator of the target address and target name of each target exposed by that device. Connection to a target is not attempted unless the SendTargets method of discovery has been enabled on the host. You enable this method with the modify subcommand.

The discovery-address parameter is formatted as:

<IP address>[:port]

If port is not specified, the default of 3260 will be used.

isns-server isns-server [...]

Add an iSNS server to the list of iSNS server addresses. An iSNS server address (specified in the syntax shown below) is an IP address-port combination used in an iSNS discovery session. By using iSNS discovery, an iSNS server can provide an initiator with information about a portal and the name of each target that belongs to the same discovery domain as that of the initiator. Connection to the iSNS server is not attempted unless the iSNS method of discovery has been enabled on the host. You enable this method with the modify subcommand, described below.

The isns-server parameter is formatted as:

IP_address[:port]

If a port is not specified, the default of 3205 is used.

static-config static_target [...]

Adds a target to the list of statically configured targets. A connection to the target will not be attempted unless the static configuration method of discovery has been enabled.

The static_target parameter is formatted as:

<target-name>,<target address>[:port-number][,tpgt]

<target-name> can be up to 223 characters.

list Subcommand

The syntax for the list subcommand is:

# iscsiadm list direct-object [options]

The list subcommand displays data for the following direct-objects:

discovery

Lists the discovery methods and their current activation state, enabled or disabled. Discovery methods are:

  • iSNS (Internet Storage Name Service)

  • Static

  • SendTargets

initiator-node

Lists information for the initiator node on the host. The iSCSI initiator node represents a logical HBA and is a logical host connection point for iSCSI targets. The parameter values listed in the response are default parameter settings for the initiator. Each connected target for an initiator can have parameter values that differ from the parameter values on the initiator node.

static-config [static_target[, ...]]

Lists the target name and address for specified targets or, if no static targets are specified, all statically discovered targets.

target [–S] [–v] [target[, ...]]

Lists a target's current parameters, connection state, and which method was used for the target's discovery. Reports information for specified targets or, if no targets are specified, all targets that have been discovered or have had parameters modified by the modify target subcommand.

When used with the –S option for a specified target, this subcommand returns:

  • target name

  • logical unit number

  • vendor ID

  • product ID

  • OS device name (for example, /dev/rdsk/c0t2d0s0)

The –v options gives more details, such as the current login parameters, the detailed connection information, and the discovery method used to discover the target.

A return of NA as the discovery method parameter indicates that the target was created with a iscsiadm modify target-param command and does not exist as a discovered object. To remove such targets, use iscsiadm remove target-param.

The Max Receive Data Segment Length is returned from the target side during login process. It can be set only at the target side and is not subject to negotiation. This displayed value is observed by the initiator side when transferring PDU's to the target side.

target-param [–v] target [...]

Lists a target's default and user-defined parameters. The output has the Default/Configured format. Default stands for the default value of this parameter, and Configured stands for the configured value of this parameter.

For example, when "Max Receive Data Segment Length" displays 8192/65536, this means the target will observe the maximum configured limit 65536 to transfer PDU's to the initiator side.

discovery-address [–v] [discovery-address[, ...]]

Lists the discovery-address objects that have been added using the iscsiadm add discovery-address subcommand.

When used with the –v option, lists all known targets at a specified discovery-address. The –v option returns one or more target names along with zero or more target addresses and associated target portal group tags (TPGT), if applicable.

isns-server [–v] [isns-server[, ...]]

Lists the isns-server objects that have been added using the iscsiadm add isns-server subcommand.

When used with the –v option, this subcommand lists all known targets at a specified isns-server address. The –v option returns one of more target names along with zero or more target addresses and associated target portal group tags, if applicable.

modify Subcommand

The syntax for the modify subcommand is:

# iscsiadm modify direct_object [options] 

The modify subcommand supports the following direct_objects:

discovery [options]

Enabling a discovery method initiates a discovery using that method. Disabling a discovery method that is currently enabled does not affect connections to any targets that have already been discovered by that method.

Options for modify discovery are as follows:

–i, –iSNS enable | disable

Enable or disable iSNS discovery.

–s, –static enable | disable

Enable or disable static discovery.

–t, –sendtargets enable | disable

Enable or disable SendTargets discovery.

initiator-node [options]

Modifies an initiator's properties. If a target is currently connected, this operation can succeed. However, the modified set of parameters will not be in effect for that target until an existing connection session no longer exists and a new connection has been established. The options –C and –CHAP-secret require a CHAP secret entry in response to a prompt.

For iSCSI booting when the Solaris I/O multipathing feature (formerly known as Sun StorEdge Traffic Manager [STMS] or MPxIO) is disabled, you can modify only the following initiator-node options:

  • –r, –-radius-server

  • –R, –-radius-access

  • –P, –-radius-shared-secret

For iSCSI booting when the Solaris I/O multipathing feature is enabled, you can modify only the following initiator-node options:

  • –h, –-headerdigest

  • –d, –-datadigest

  • –c, –-configured-sessions

Options for modify initiator-node are as follows:

–A, –node-alias <initiator node alias>

Modifies the initiator node alias. Maximum length of 223 characters.

–a, –authentication chap | none

Sets the authentication mode.

–C, –CHAP-secret

Sets the CHAP secret value. There is no default value. Maximum length is 16 characters; minimum required length is 12 characters.

–c, –-configured-sessions <num_sessions> | <IP address>[,<IP address>...]

Sets the number of configured iSCSI sessions that will be created for each iSCSI target. The feature should be used in combination with the Solaris I/O multipathing feature described in scsi_vhci(4D).

–d, –-datadigest none | CRC32

Sets whether CRC32 is enabled to check SCSI data transfers.

–H, –CHAP-name CHAP name

Specifies a CHAP username. If you do not use this option, upon initialization, the CHAP name is set to the initiator node name. When the authentication method is set to CHAP (see –a/–authentication option, above), the CHAP username is displayed with the command iscsiadm list initiator-node.

–h, –-headerdigest none | CRC32

Sets whether CRC32 is enabled to check SCSI packet headers.

–m, –-max-connections number_connections

Modifies the maximum connection number for iSCSI sessions. The default value is 1. The maximum number of connections for each session is 65535.

–N, –node-name <initiator node name>

Modifies the initiator node name. Maximum of 223 characters.


Note - During Solaris installation, the initiator node name is set to a globally unique value. Changing this value can adversely affect operation within the iSCSI network.
–P, –-radius-shared-secret (exclusive)

Sets the RADIUS shared secret.

–R, –-radius-access enable | disable

Sets whether a RADIUS server will be used.

–r, –-radius-server <IP address>[:<port>]

Sets the IP address and port of the radius server to be used.

–T, –tunable-param <<tunable-prop>=<value>, ...>

Specify one or more tunable parameters for all targets that initiator node connected.


Note - These values should only be modified by an administrator with a good working knowledge of the parameter's impact within the iSCSI network.

Supported tunable-prop options are:

recv-login-rsp-timeout

Session Login Response Time

The recv-login-rsp-timeout option specifies how long iSCSI initiator will wait for the response of iSCSI session login request from the iSCSI target. Valid value is from 0 to 60*60, default to 60 seconds.

conn-login-max

Maximized Connection Retry Time

The conn-login-max option lets the iSCSI initiator reestablish the connection to the target in case of IO timeout or connection failure during the given time window. Valid value is from 0 to 60*60. The default value is 180 seconds.

polling-login-delay

Login Retry Time Interval

The polling-login-delay option specifies the time interval between each login retry when iSCSI initiator to target IO timeout or connection failure. Valid value is from 0 to 60*60. The default value is 60 seconds.

target-param [options] target

Modifies a target's parameters. If a target is currently connected, the modify operation will succeed, although the modified settings might not take effect for a few seconds. To confirm that these settings are active, use iscsiadm list target –v. If a specified target is not associated with any discovery method, a target object is created with the specified parameters. After using this command to modify a target's parameters, the new parameters will persist until they are modified or removed with a iscsiadm remove target-param command on that target. The options –C and –CHAP-secret require a CHAP secret entry in response to a prompt.

Options for modify target-param are as follows:

–B, –bi-directional-authentication enable | disable

Sets the bidirectional option. If set to enable, the initiator performs bidirectional authentication for the specified target.

–C, –CHAP-secret

Sets the target's CHAP secret value. There is no default value. Maximum acceptable length is 16 characters.

–c, –configured-sessions <num_sessions> | <IP address>[,<IP address>...]

Sets the number of configured iSCSI sessions that will be created for each iSCSI target. The feature should be used in combination with the Solaris I/O multipathing feature described in scsi_vhci(4D).

–d, –datadigest none | CRC32

Sets whether CRC32 is enabled or disabled for the data.

–H, –CHAP-name CHAP name

Sets a CHAP username. If you do not use this option, upon initialization, the CHAP name is set to the target name. When the authentication method is set to CHAP (see –a/–authentication option, under the initiator-node direct object, above), the CHAP username is displayed with the command iscsiadm list initiator-node.

–h, –headerdigest none | CRC32

Sets whether CRC32 is enabled or disabled for the header.

–p, –login-param

Specify one or more login parameter settings.


Note - These values should only be modified by an administrator with a good working knowledge of the parameter's impact within the iSCSI network.

The login parameters are derived from iSCSI proposed standard RFC 3720. Valid values are:

dataseqinorder

yes or no

defaulttime2retain

0–3600

defaulttime2wait

0–3600

firstburstlength

512 to 224–1

immediatedata

yes or no

initialr2t

yes or no

maxburstlength

512 to 224–1

datapduinorder

yes or no

maxoutstandingr2t

1 to 65535

maxrecvdataseglen

512 to 224–1

The initiator can set its own maxrecvdatasegmentlen by this option setting. During the login process, the initiator side sends this parameter to the target to declare its max receive segment length. This parameter setting can be displayed by the iscsiadm list target-param -v target command.

–T, –tunable-param <<tunable-prop>=<value>, ...>

Specify one or more tunable parameters for all targets that initiator node connected.


Note - Tunable values should only be modified by an administrator with a good working knowledge of the parameter's impact within the iSCSI network.

Supported tunable-prop options are:

recv-login-rsp-timeout

Session Login Response Time

The recv-login-rsp-timeout option specifies how long iSCSI initiator will wait for the response of iSCSI session login request from the iSCSI target. Valid value is from 0 to 60*60. The default value is 60 seconds.

conn-login-max

Maximized Connection Retry Time

The conn-login-max option lets the iSCSI initiator reestablish the connection to the target in case of IO timeout or connection failure during the given time window. Valid value is from 0 to 60*60, default to 180 seconds.

polling-login-delay

Login Retry Time Interval

The polling-login-delay option specifies the time interval between each login retry when iSCSI initiator to target IO timeout or connection failure. Valid value is from 0 to 60*60, default to 60 seconds.

remove Subcommand

The syntax for the remove subcommand is:

# iscsiadm remove direct_object 

The remove subcommand supports the following direct_objects:

discovery-address discovery-address, ...

Removes a target device from the list of discovery addresses. A discovery address (as in the syntax shown below) is an IP address-port combination used in a SendTargets discovery session. Using this discovery approach, a target device can inform an initiator of the target address and target name of each target exposed by that device. If any target exposed by the discovery address is currently mounted or there is active I/O on the device, an error of “logical unit in use” is returned and the operation fails. If the associated devices are not in use, they are removed.

discovery-address must be formatted as:

<IP address>[:<port>]

There are no options associated with this direct object.

isns-server isns-server, ...

Removes an iSNS server from the list of iSNS server addresses. An iSNS server address (specified in the syntax shown below) is an IP address-port combination used in an iSNS discovery session. By using iSNS discovery, an iSNS server can provide an initiator with information about a portal and the name of each target that belongs to the same discovery domain as that of the initiator. If any target discovered by means of iSNS is currently mounted or there is active I/O on the device, an error of “logical unit in use” is returned and the operation fails. If the associated devices are not in use, they are removed.

isns-server must be formatted as:

IP_address[:port]

There are no options associated with this direct object.

static-config static_target, ...

Removes a target from the list of statically discovered targets. If the target being removed is currently mounted or there is active I/O on the device, an error of “logical unit in use” is returned and the operation fails. If a device is not in use, it will be removed.

static_target must be formatted as:

<target-name>,<target-address>[:port-number][,tpgt]

There are no options associated with this direct object.

target-param target-name

Removes target specified by target-name. The target name is formatted as:

<target-name>

There are no options associated with this direct object. For iSCSI booting when the Solaris I/O multipathing feature (formerly known as Sun StorEdge Traffic Manager [STMS] or MPxIO) is enabled, you cannot remove the target.

Proper Use of Discovery Methods

Do not configure a target to be discovered by both static and dynamic discovery methods. The consequence of using redundant discovery methods might be slow performance when communicating with the iSCSI target device.

Options

The following generic options are supported:

–V, –version

Displays version information. Stops interpretation of subsequent arguments.

–?, –help

Displays help information. Can be used following an iscsiadm command with no arguments, following a subcommand, or following a subcommand-direct object combination. Responds with help information appropriate for your entry. For example, if you enter:

# iscsiadm modify initiator-node --help

...iscsiadm responds with a display of the options available for that combination of subcommand and direct object.

Examples

Example 1 Adding a Discovery Address

The following command uses the add subcommand to add a discovery address.

# iscsiadm add discovery-address 10.0.0.1:3260 10.0.0.2:3260
Example 2 Adding a Static Target

The following command uses the add subcommand to add a static target.

# iscsiadm add static-config \
iqn.1999-08.com.array:sn.01234567,10.0.0.1:3260
Example 3 Listing Current Discovery Settings

The following command uses the list subcommand to list current discovery settings.

# iscsiadm list discovery
        Discovery:
                Static: enabled
                Send Targets: disabled
                iSNS: enabled

Example 4 Obtaining Verbose Discovery Output

The following commands uses the –v option (one with, one without) with the list subcommand to obtain verbose output.

# iscsiadm list discovery-address
        Discovery Address: 10.0.0.1:3260
        Discovery Address: 10.0.0.2:3260

# iscsiadm list discovery-address -v 10.0.0.1:3260
        Discovery Address: 10.0.0.1:3260
                Target name: eui.210000203787d1f7
                        Target address:    10.0.0.1:3260
                Target name: eui.210000203787a693
                        Target address:    10.0.0.1:3260
Example 5 Displaying Information on the Initiator

The following command uses the list subcommand to display information on the initiator.

# iscsiadm list initiator-node
Initiator node name: iqn.1986-03.com.company.central.interopv20-1
Initiator node alias: interopv20-1
        Login Parameters (Default/Configured):
                Header Digest: NONE/NONE
                Data Digest: NONE/NONE
        Authentication Type: CHAP
                CHAP Name: iqn.1986-03.com.company.central.interopv20-1
        RADIUS Server: NONE
        RADIUS access: disabled
        Tunable Parameters (Default/Configured):
                Session Login Response Time: 60/-
                Maximum Connection Retry Time: 180/-
                Login Retry Time Interval: 60/-
        Configured Sessions: 1
Example 6 Displaying Static Configuration Information

The following command uses the list subcommand to display information about static configurations.

# iscsiadm list static-config
        Static target: eui.210000203787a693,10.0.0.1:3260
Example 7 Displaying Target Information

The following commands show the use of the list subcommand with various options to display information about targets.

# iscsiadm list target
Target: iqn.2004-05.com.abcStorage:Tgt-1
        Alias: -
        TPGT: 12288
        ISID: 4000002a0000
        Connections: 1

# iscsiadm list target -v iqn.2004-05.com.abcStorage:Tgt-1
Target: iqn.2004-05.com.abcStorage:Tgt-1
        Alias: -
        TPGT: 12288
        ISID: 4000002a0000
        Connections: 1
                CID: 0
                  IP address (Local): 10.4.52.158:32803
                  IP address (Peer): 10.4.49.70:3260        
                  Transport Type: socket
                  Discovery Method: SendTargets
                  Login Parameters (Negotiated):
                        Data Sequence In Order: yes
                        Data PDU In Order: yes
                        Default Time To Retain: 20
                        Default Time To Wait: 2
                        Error Recovery Level: 0
                        First Burst Length: 65536
                        Immediate Data: yes
                        Initial Ready To Transfer (R2T): yes
                        Max Burst Length: 262144
                        Max Outstanding R2T: 1
                        Max Receive Data Segment Length: 65536
                        Max Connections: 1
                        Header Digest: NONE
                        Data Digest: NONE
# iscsiadm list target -S iqn.2004-05.com.abcStorage:Tgt-1
Target: iqn.2004-05.com.abcStorage:Tgt-1
        Alias: -
        TPGT: 12288
        ISID: 4000002a0000
        Connections: 1
        LUN: 6
             Vendor:  ABCStorage
             Product: iSCSI Target
             OS Device Name: /dev/rdsk/c3t1d0s2
        LUN: 5
             Vendor:  ABCStorage
             Product: iSCSI Target
             OS Device Name: /dev/rdsk/c3t0d0s2
Example 8 Displaying Target Parameter Information

The following command uses the list subcommand to display target information for a specific target.

# iscsiadm list target-param -v iqn.2004-05.com.abcStorage:Tgt-1
Target: iqn.2004-05.com.abcStorage:Tgt-1
        Alias: -
        Bi-directional Authentication: disabled
        Authentication Type: NONE
        Login Parameters (Default/Configured):
                Data Sequence In Order: yes/-
                Data PDU In Order: yes/-
                Default Time To Retain: 20/-
                Default Time To Wait: 2/-
                Error Recovery Level: 0/-
                First Burst Length: 65536/-
                Immediate Data: yes/-
                Initial Ready To Transfer (R2T): yes/-
                Max Burst Length: 262144/-
                Max Outstanding R2T: 1/-
                Max Receive Data Segment Length: 65536/-
                Max Connections: 1/-
                Header Digest: NONE/-
                Data Digest: NONE/-
        Tunable Parameters (Default/Configured):
                Session Login Response Time: 60/-
                Maximum Connection Retry Time: 180/-
                Login Retry Time Interval: 60/-
        Configured Sessions: 1

Example 9 Enabling Static Discovery Method

The following command uses the modify subcommand to enable the static discovery method.

# iscsiadm modify discovery --static enable
Example 10 Setting the IP Address for the Radius Server

The following command uses the modify subcommand to set the IP address for the radius server, which will be used for CHAP authentication.

# iscsiadm modify initiator --radius-server 10.0.0.1
Example 11 Setting the Node Name for Initiator

The following command uses the modify subcommand to set the node name for the initiator node.

# iscsiadm modify initiator-node -N iqn.2004-10.com.SUN.host-1
Example 12 Setting Max Connections for the Initiator Node

The following command uses the modify subcommand to set the max connection number for the initiator node. This enables multiple connections to exist in one session.

# iscsiadm modify initiator-node -m 3
Example 13 Changing Target Parameters

The following command uses the modify subcommand to change the max connection number of the target parameters for a specified target.

# iscsiadm modify target-param -m 3 eui.210000203787a693
Example 14 Removing a Discovery Address

The following command uses the remove subcommand to remove a discovery address.

# iscsiadm remove discovery-address 10.0.0.1:3260
Example 15 Removing Target Parameters

The following command uses the remove subcommand to remove a set of target parameters.

# iscsiadm remove target-param eui.210000203787a693
Example 16 Modifying Maximum Connection Number

The following command modifies the maximum number of connections for each session in the initiator's property. The modified value will be used in all sessions, to all targets.

# iscsiadm modify initiator-node --max-connections 4

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/storage/iscsi/iscsi-initiator
Interface Stability
Committed

See Also

iscsi(4D), scsi_vhci(4D), attributes(7)

Notes

The iSCSI initiator service is managed by the service management facility, smf, under the service identifier svc:/network/iscsi/initiator:default. For more information, see the smf(7) man page.

This service can be enabled, disabled, or restarted by using the svcadm command. You can query the status of this service by using the svcs command.