&& Chapter 14 Configuring Oracle Solaris iSCSI Targets
and Initiators (Tasks)System Administration Guide: Devices and File SystemsChapter&14 Configuring Oracle Solaris iSCSI Targets
and Initiators (Tasks)
This chapter describes how to configure Solaris iSCSI targets and initiators,
available in the Oracle Solaris release. For information about the procedures
associated with configuring iSCSI targets and initiators, see .
For information about Solaris iSCSI initiator features in the latest Solaris
10 release, see
For troubleshooting Solaris iSCSI configuration problems, see .
iSCSI Technology (Overview)
iSCSI is an acronym for Internet SCSI (Small Computer System Interface),
an Internet Protocol (IP)-based storage networking standard for linking data
storage subsystems. This networking standard was developed by the Internet
Engineering Task Force (IETF). For more information about the iSCSI technology,
see RFC 3720:
By carrying SCSI commands over IP networks, the iSCSI protocol enables
you to access block devices from across the network as if they were connected
to the local system.
If you want to use storage devices in your existing TCP/IP network,
the following solutions are available:
iSCSI block devices or tape & Translates SCSI commands
and data from the block level into IP packets. Using iSCSI in your network
is advantageous when you need to have block-level access between one system
and the target device, such as a tape device or a database. Access to a block-level
device is not locked so that you could have multiple users or systems accessing
a block-level device such as an iSCSI target device.
NFS & Transfers file data over IP. The advantage of
using NFS in your network is that you can share file data across many systems.
Access to file data is locked appropriately when many users are accessing
data that is available in an NFS environment.
Here are the benefits of using Solaris iSCSI targets and initiators:
The iSCSI protocol runs across existing Ethernet networks.
You can use any supported network interface card (NIC), Ethernet
hub, or Ethernet switch.
One IP port can handle multiple iSCSI target devices.
You can use existing infrastructure and management tools for
IP networks.
You might have existing Fibre-Channel devices that can be
connected to clients without the cost of Fibre-Channel HBAs. In addition,
systems with dedicated arrays can now export replicated storage with ZFS or
UFS file systems.
There is no upper limit on the maximum number of configured
iSCSI target devices.
The protocol can be used to connect to Fibre Channel or iSCSI
Storage Area Network (SAN) environments with the appropriate hardware.
Here are the current limitations or restrictions of using the Solaris
iSCSI initiator software:
Support for iSCSI devices that use SLP is not currently available.
Boot support for iSCSI devices is not currently available.
iSCSI targets cannot be configured as dump devices.
iSCSI supports multiple connections per session, but the current
Solaris implementation only supports a single connection per session.
For more information, see RFC 3720.
Transferring large amounts of data over your existing network
can have an impact on performance.
Solaris iSCSI Software and Hardware Requirements
Solaris iSCSI software and devices
Solaris 10 release (at least the 1/06 release)
for Solaris iSCSI initiator software
Solaris 10 release (at least the 8/07 release)
for Solaris iSCSI target software
The following Solaris
10 software packages:
SUNWiscsir & Sun iSCSI Device Driver
SUNWiscsiu & Sun iSCSI Management
Utilities (usr)
SUNWiscsitgtr & Sun iSCSI Target
Device Driver (root)
SUNWiscsitgtu & Sun iSCSI Target
Management Utilities (usr)
Any supported NIC
Setting Up Solaris iSCSI Targets and Initiators (Task
Description&
For Instructions&
1. Identify the iSCSI software and hardware requirements.&
Identify the software and hardware requirements for setting up an iSCSI-based
storage network.&
2. Set up your iSCSI target devices.&
Connect and set up your Solaris iSCSI target devices.&
In addition, you can set up third-party target devices. See your vendor's
documentation for setup instructions.&
Set up iSNS discovery on your Solaris iSCSI target, if an iSNS server
is available.&
3. Prepare for your Solaris iSCSI configuration.&
Make sure you have the correct software versions and hardware installed.&
4. (Optional) Set up authentication in your Solaris iSCSI configuration.&
Decide whether you want to use authentication in your Solaris iSCSI
configuration:&
Consider using unidirectional CHAP or bidirectional CHAP.&
Consider using a third-party RADIUS server to simplify CHAP management.&
5. Configure the iSCSI target discovery method.&
Select the iSCSI target discovery method best suited for your environment.&
6. (Optional) Remove discovered iSCSI targets.&
You might need to remove a discovered iSCSI target.&
7. Access iSCSI disks.&
You can access your iSCSI disks with the format utility.
You can also enable the iSCSI disks to be available automatically after the
system is rebooted.
8. Monitor your iSCSI configuration.&
Monitor your iSCSI configuration by using the iscsiadm command.
9. (Optional) Modify your iSCSI configuration.&
You might want to modify your iSCSI target settings such as the header
and data digest parameters.&
10. (Optional) Set up Solaris iSCSI multipathed devices.&
Determine whether you want to set up Solaris iSCSI multipathed devices.&
Use this procedure to create multiple iSCSI sessions that connect to
a single target.&
Configuring Solaris iSCSI Targets and Initiators
Configuring your Solaris iSCSI targets and initiators involves the following
Identifying the hardware and software requirements
Configuring your IP network
Connecting and setting up your iSCSI target device
(Optional) Configuring iSCSI authentication between the iSCSI
initiator and the iSCSI target, if necessary
Configuring the iSCSI target discovery method
Creating file systems on your iSCSI disks
Monitoring your iSCSI configuration
The iSCSI configuration information is stored in the /etc/iscsi directory.
This information requires no administration.
iSCSI Terminology
Review the following terminology before configuring iSCSI targets and
initiators.
Description&
Initiator&
The driver that initiates SCSI requests to the iSCSI target.&
Target device&
The iSCSI storage component.&
Discovery&
The process that presents the initiator with a list of available targets.&
Discovery method &
The way in which the iSCSI targets can be found. Three methods are currently
available:&
Internet Storage Name Service (iSNS) &
Potential targets are discovered by interacting with one or
more iSNS servers.
SendTargets & Potential targets are discovered by using
a discovery-address.
Static & Static target addressing is configured.
Configuring Dynamic or Static Target Discovery
Determine whether you want to configure one of the dynamic device discovery
methods or use static iSCSI initiator targets to perform device discovery.
Dynamic device discovery &
If an iSCSI node exposes many targets, such as an iSCSI to Fibre-Channel bridge,
you can supply the iSCSI node IP address/port combination and allow the iSCSI
initiator to use the SendTargets features to perform device discovery.
Two dynamic device discovery methods are available:
SendTargets - If an iSCSI node exposes a large number of targets,
such as an iSCSI to Fibre-Channel bridge, you can supply the iSCSI node IP
address/port combination and allow the iSCSI initiator to use the SendTargets
features to perform the device discovery.
iSNS - iSNS (Internet Storage Name Service) allows the iSCSI
initiator to discover the targets to which it has access using as little configuration
information as possible. It also provides state change notification to notify
the iSCSI initiator when changes in the operational state of storage nodes
occur. To use the iSNS discovery method, you can supply the iSNS server address/port
combination and allow the iSCSI initiator to query the iSNS servers that you
specified to perform the device discovery. The default port for the iSNS server
is 3205. For more information about iSNS, see RFC 4171:
The iSNS discovery service provides an administrative model to discover
all targets in a network.
Static device discovery &
If an iSCSI node has few targets or if you want to restrict the targets that
the initiator attempts to access, you can statically configure the target-name by using the following static target address naming convention:
target,target-address[:port-number]
You can determine the static target address from the array's management
Note & Do not configure an iSCSI target to be discovered by both static
and dynamic device discovery methods.
The consequence of using redundant
discovery methods might be slow performance when the initiator is communicating
with the iSCSI target device.
How to Prepare for a Solaris iSCSI Configuration
This procedure assumes that you are logged in to the local system where
you want to access a configured iSCSI target device.
Become superuser.
Verify that the iSCSI software packages are installed.
initiator# pkginfo SUNWiscsiu SUNWiscsir
SUNWiscsiu Sun iSCSI Device Driver (root)
SUNWiscsir Sun iSCSI Management Utilities (usr)
Verify that you are running at least the Solaris
Confirm that your TCP/IP network is setup.
Connect your iSCSI target devices and confirm that they are configured.
For example, determine if the iSCSI target device is reachable
by using the telnet command to connect to the iSCSI target
device using port 3260. If the connection is refused, see .
For information about connecting your third-party iSCSI target devices,
see your vendor documentation.
Setting Up Your Solaris iSCSI Target Devices
You can use the iscsitadm command to set up and manage
your Solaris iSCSI target devices, which can be disk or tape devices. For
the device that you select as your iSCSI target, you must provide an equivalently
sized ZFS or UFS file system as the backing store for the iSCSI daemon.
For information about setting up a Solaris iSCSI target device with
ZFS, see .
After the target device is set up, use the iscsiadm command
to identify your iSCSI targets, which will discover and use the iSCSI target
For more information, see
The basic process is as follows:
Identify the backing store directory & For each target
and logical unit that is created, the iSCSI daemon needs to store some information.
By default, the backing store for this device is also located in the base
directory. So, if the host system has a large ZFS pool to use, it might be
easiest to allow the daemon to store everything in that location. If the backing
store needs to be spread out, it's possible to specify the backing store location
during the creation of each logical unit.
Create the iSCSI target & By default, the CLI assumes
that the requested device type is an LBA of logical unit 0. If a pass through
mode is desired for character devices, the -raw option must
be used. After the creation of the first LUN, other LUNs might be created
for the same iSCSI target by specifying -lun number.
The daemon starts a background task that initializes the LUN to zeros.
If, during that initialization, the underlying file system becomes 100 percent
full, the daemon removes the target. During this initialization, the LUN is
marked as being offline and cannot be used by an initiator. During this time,
however, it is possible to have an initiator discover this LUN. The Solaris
initiator waits until it receives an Inventory Change notification
and then automatically brings the device online.
How to Create an iSCSI Target
This procedure assumes that you are logged in to the local system that
contains the iSCSI targets.
Become superuser.
Identify the backing store directory.
For example:
target# iscsitadm modify admin -d /export/sandbox
Create an iSCSI target.
For example:
target# iscsitadm create target --size 2g sandbox
Display information about the iSCSI target.
For example:
target# iscsitadm list target -v sandbox
Set up your iSCSI initiator to discover and use this target.
For more information, see .
How to Configure iSNS Discovery for the Solaris iSCSI
If your network includes a third-party iSNS server or a Sun iSNS server,
you can set up iSNS target discovery on your Solaris iSCSI targets.
This procedure assumes that you are logged in to the local system where
you want to access a configured iSCSI target device.
Become superuser.
Add the iSNS server information.
For example:
initiator# iscsitadm modify admin --isns-server ip-address or hostname[:port]
Identify the ip-address of the iSNS server
in your network.
This step adds the iSNS server information to all of the Solaris iSCSI
Enable iSNS server discovery.
For example:
initiator# iscsitadm modify admin --isns-access enable
This step enables iSNS discovery for all of the Solaris iSCSI targets.
Configuring Authentication in Your iSCSI-Based
Storage Network
Setting up authentication for your iSCSI devices is optional.
In a secure environment, authentication is not required because only
trusted initiators can access the targets.
In a less secure environment, the target cannot determine if a connection
request is truly from a given host. In that case, the target can authenticate
an initiator by using the Challenge-Handshake Authentication Protocol (CHAP).
CHAP authentication uses the notion of a challenge and response, which
means that the target challenges the initiator to prove its identity.
the challenge/response method to work, the target must know the initiator's
secret key, and the initiator must be set up to respond to a challenge.
to the array vendor's documentation for instructions on setting up the secret
key on the array.
iSCSI supports unidirectional and bidirectional authentication:
Unidirectional authentication enables
the target to authenticate the identity of the initiator.
Bidirectional authentication adds a second
level of security by enabling the initiator to authenticate the identity of
the target.
How to Configure CHAP Authentication for Your iSCSI
This procedure assumes that you are logged in to the local system where
you want to securely access the configured iSCSI target device.
Become superuser.
Determine whether you want to configure unidirectional or bidirectional
Unidirectional authentication, the default method, enables
the target to validate the initiator. Complete steps 3&5 only.
Bidirectional authentication adds a second level of security
by enabling the initiator to authenticate the target. Complete steps 3&9.
Unidirectional CHAP & Set the secret key on the initiator.
For example, the following command initiates a dialogue to define the
CHAP secret key.
initiator# iscsiadm modify initiator-node --CHAP-secret
The CHAP secret length must be a minimum of 12 characters and
a maximum of 16 characters.
(Optional) Unidirectional CHAP & Set the CHAP
name on the initiator.
By default, the initiator's CHAP name is
set to the initiator node name.
You can use the following command to change the initiator's CHAP name.
initiator# iscsiadm modify initiator-node --CHAP-name new-CHAP-name
In the Solaris environment, the CHAP name is always set to the initiator
node name by default. The CHAP name can be set to any length text that is
less than 512 bytes. The 512-byte length limit is a Solaris limitation. However,
if you do not set the CHAP name, it is set to the initiator node name upon
initialization.
Unidirectional CHAP & Enable CHAP authentication on the
initiator after the secret has been set.
initiator# iscsiadm modify initiator-node --authentication CHAP
CHAP requires that the initiator
node have both a user name and a password. The user name is typically used
by the target to look up the secret for the given username.
Select one of the following to enable or disable Bidirectional
Bidirectional CHAP & Enable bidirectional authentication
parameters on the target.
For example:
initiator# iscsiadm modify target-param -B enable eui.5000ABCD78945E2B
Disable bidirectional CHAP. For example:
initiator# iscsiadm modify target-param -B disable eui.5000ABCD78945E2B
Bidirectional CHAP & Set the authentication method to CHAP
on the target.
For example:
initiator# iscsiadm modify target-param --authentication CHAP eui.5000ABCD78945E2B
Bidirectional CHAP & Set the target device secret key on
the target.
For example, the following command initiates a dialogue
to define the CHAP secret key:
initiator# iscsiadm modify target-param --CHAP-secret eui.5000ABCD78945E2B
Bidirectional CHAP - Set the CHAP name on the target.
default, the target's CHAP name is set to the target name.
You can use the following command to change the target's CHAP name:
initiator# iscsiadm modify target-param --CHAP-name target-CHAP-name
How to Configure CHAP Authentication for Your iSCSI
This procedure assumes that you are logged in to the local system that
contains the iSCSI targets.
Become superuser.
Set the CHAP secret name for the target.
A convention
is to use the host name for the secret name. For example:
target# iscsitadm modify admin -H stormpike
Specify the CHAP secret.
The CHAP secret must be between
12 and 16 characters. For example:
target# iscsitadm modify admin -C
Enter secret: xxxxxx
Re-enter secret: xxxxxx
Create an initiator object that will be associated with one or
more targets.
This step is done so that you can associate a friendly
name (normally the host name, in this case monster620)
with the IQN value, instead of typing it in every time. For example:
# iscsitadm create initiator -n iqn..sun: 01:00e99f40e monster620
Provide the same CHAP name that was used on the initiator.
This name can be different from the friendly name that was used for
the initiator object. For example:
target# iscsitadm modify initiator -H monster620 monster620
Use the same CHAP secret that was used on the initiator.
For example:
target# iscsitadm modify initiator -C monster620
Enter secret: xxxxxx
Re-enter secret: xxxxxx
Associate the initiator object with one or more targets.
For example:
target# iscsitadm modify target -l monster620 sandbox
Using a Third-Party RADIUS Server to Simplify
CHAP Management in Your iSCSI Configuration
You can use a third-party RADIUS server to simplify CHAP secret management.
A RADIUS server is a centralized authentication service. While you must still
specify the initiator's CHAP secret, you are no longer required to specify
each target's CHAP secret on each initiator when using bidirectional authentication
with a RADIUS server.
For more information, see:
How to Configure RADIUS for Your iSCSI Configuration
This procedure assumes that you are logged in to the local system where
you want to securely access the configured iSCSI target device.
Become superuser.
Configure the initiator node with the IP address and port (the
default port is 1812) of the RADIUS server.
For example:
initiator# iscsiadm modify initiator-node --radius-server 10.0.0.72:1812
Configure the initiator node with the shared secret of the RADIUS
initiator# iscsiadm modify initiator-node --radius-shared-secret
The Solaris iSCSI implementation requires that the RADIUS server
is configured with a shared secret before the Solaris iSCSI software can interact
with the RADIUS server.
Enable the RADIUS server.
initiator# iscsiadm modify initiator-node --radius-access enable
Solaris iSCSI and RADIUS Server Error Messages
This section describes the error messages that are related to a Solaris
iSCSI and RADIUS server configuration, along with potential solutions for
empty RADIUS shared secret
The RADIUS server is enabled on the initiator,
but the RADIUS shared secret is not set.
Configure the initiator with the RADIUS shared
secret. For more information, see .
WARNING: RADIUS packet authentication
The initiator failed to authenticate the RADIUS
data packet. This error can occur if the shared secret configured on the initiator
node is different from the shared secret on the RADIUS server.
Reconfigure
the initiator with the correct RADIUS shared secret. For more information,
How to Configure iSCSI Target Discovery
This procedure assumes that you are logged in to the local system where
you want to configure access to an iSCSI target device.
Become superuser.
Configure the target device to be discovered dynamically or statically
using one of the following methods:
Configure the device to be dynamically discovered (SendTargets).
For example:
initiator# iscsiadm add discovery-address 10.0.0.1:3260
Configure the device to be dynamically discovered (iSNS).
For example:
initiator# iscsiadm add iSNS-server 10.0.0.1:3205
Configure the device to be statically discovered.
initiator# iscsiadm add static-config eui.5000ABCD.0.0.1
The iSCSI connection is not initiated until the discovery method is
enabled. See the next step.
Enable the iSCSI target discovery method using one of the following:
If you have configured a dynamically discovered (SendTargets)
device, enable the SendTargets discovery method.
initiator# iscsiadm modify discovery --sendtargets enable
If you have configured a dynamically discovered (iSNS) device,
enable the iSNS discovery method.
initiator# iscsiadm modify discovery --iSNS enable
If you have configured static targets, enable the static target
discovery method.
initiator# iscsiadm modify discovery --static enable
Create the iSCSI device links for the local system.
initiator# devfsadm -i iscsi
How to Remove Discovered iSCSI Targets
After removing a discovery address, iSNS server, or static configuration,
or after disabling a discovery method, the associated targets are logged out.
If these associated targets are still in use, for example, they have mounted
file systems, the logout of these devices will fail, and they will remain
on the active target list.
This optional procedure assumes that you are logged in to the local
system where access to an iSCSI target device has already been configured.
Become superuser.
(Optional) Disable an iSCSI target discovery method
using one of the following:
If you need to disable the SendTargets discovery method, use
the following command:
initiator# iscsiadm modify discovery --sendtargets disable
If you need to disable the iSNS discovery method, use the
following command:
initiator# iscsiadm modify discovery --iSNS disable
If you need to disable the static target discovery method,
use the following command:
initiator# iscsiadm modify discovery --static disable
Remove an iSCSI device discovery entry using one of the following:
Remove an iSCSI SendTargets discovery entry.
initiator# iscsiadm remove discovery-address 10.0.0.1:3260
Remove an iSCSI iSNS discovery entry.
For example:
# iscsiadm remove isns-server 10.0.0.1:3205
Remove a static iSCSI discovery entry.
For example:
initiator# iscsiadm remove static-config eui.5000ABCD.0.0.1
If you attempt to disable or remove a discovery entry that has
an associated logical unit in use, the disable or remove operation fails with
the following message:
logical unit in use
If this errors occurs, stop all associated I/O on the logical unit,
unmount the file systems, and so on.
Then, repeat the disable or remove operation.
Remove the iSCSI target device.
Remove a target by
specifying the logical unit number (LUN). If
you did not specify a LUN when
the target was created, a value of 0 was used. LUN
0 must be the last LUN
removed if multiple LUNs are associated with a target.
For example:
initiator# iscsitadm delete target --lun 0 sandbox
Accessing iSCSI Disks
If you want to access the iSCSI disks upon reboot, create the file system
on the disk, and add an /etc/vfstab entry as you would
with a UFS
file system on a SCSI device. Then, create a new SMF service
for mounting iSCSI disks that depends on the iSCSI initiator service. For
more information, see .
After the devices have been discovered by the Solaris iSCSI initiator,
the login negotiation occurs automatically. The Solaris iSCSI driver determines
the number of available LUNs and creates the device nodes. Then, the iSCSI
devices can be treated as any other SCSI device.
You can view the iSCSI disks on the local system by using the format utility.
In the following format output, disks 2 and 3 are
iSCSI LUNs that are not under MPxIO control. Disks 21 and 22 are iSCSI LUNs
under MPxIO control.
initiator# format
AVAILABLE DISK SELECTIONS:
0. c0t1d0 &SUN72G cyl 14087 alt 2 hd 24 sec 424&
/pci@8,600000/SUNW,qlc@4/fp@0,0/ssd@w685cf1,0
1. c0t2d0 &SUN72G cyl 14087 alt 2 hd 24 sec 424&
/pci@8,600000/SUNW,qlc@4/fp@0,0/ssd@w6e3ba1,0
2. c3t0d0 &ABCSTORAGE-100E-00-2.2 cyl 20813 alt 2 hd 16 sec 63&
/iscsi/disk@0000iqn..abcstorage%3A6-8a01-
b0fff-hostname-
3. c3t1d0 &ABCSTORAGE-100E-00-2.2 cyl 20813 alt 2 hd 16 sec 63&
/iscsi/disk@0000iqn..abcstorage%3A6-8a0900-3fcd70401
-085ff-hostname-
21. c4t60AB2FB77d0 &ABCSTORAGE-LUN-0.2 cyl
4606 alt 2 hd 16 sec 256&
/scsi_vhci/ssd@g60ab2fb77
22. c4t60AB2FC41d0 &ABCSTORAGE-LUN-0.2 cyl
4606 alt 2 hd 16 sec 256&
/scsi_vhci/ssd@g60ab2fc41
How to Access iSCSI Disks Upon Reboot
Follow the steps below to access iSCSI disks after the system is rebooted.
Add entries for the iSCSI LUN(s) to the /etc/vfstab file.
Set the mount at boot option to no.
at boot options
/dev/dsk/c3tB555F495B00d0s0
Create an SMF service manifest that automatically mounts the iSCSI
LUN after the system is rebooted.
For example, create an XML manifest
file, /var/svc/manifest/network/iscsi/iscsimount.xml,
with the following contents:
&?xml version="1.0"?&
&!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1"&
&service_bundle type="manifest" name="iscsimount"&
name="iscsimount"
type="service"
version="1" &
&single_instance/&
We depend on the iscsi initiator service
&dependency
name="client"
type="service"
grouping="require_all"
restart_on="none"&
&service_fmri value="svc:/network/iscsi/initiator"/&
&/dependency&
&instance name="default" enabled="false"&
&!-- mount iSCSI volumes --&
&exec_method
type="method"
name="start"
exec="/var/tmp/iscsi_mount"
timeout_seconds="60"/&
&!-- umount iSCSI volumes --&
&exec_method
type="method"
name="stop"
exec="/var/tmp/iscsi_umount"
timeout_seconds="60" /&
&property_group name="startd" type="framework"&
&propval name="duration" type="astring" value="transient"/&
&/property_group&
&/instance&
&template&
&common_name&
&loctext xml:lang="C"&
iSCSI Mount Service
&/loctext&
&/common_name&
&/template&
&/service&
&/service_bundle&
Create the following files in the /var/tmp directory.
The following sample bash shell scripts mount and umount iSCSI disks from the /mnt directory.
bash-4.0# cat /var/tmp/iscsi_mount
#!/usr/bin/bash
mount /mnt
#Add multiple iscsi lun(s) to mount
bash-4.0# cat /var/tmp/iscsi_umount
#!/usr/bin/bash
umount /mnt
#Add multiple iscsi lun(s) to umount
Set execute permission on these scripts. For example:
bash-4.0# chmod u+x /var/tmp/iscsi_mount
bash-4.0# chmod u+x /var/tmp/iscsi_umount
Import the manifest.
# svccfg import /var/svc/manifest/network/iscsi/iscsimount.xml
# svccfg enable iscsimount
After this service is enabled, you might get the following messages
when the system is shut down or rebooted:
iscsi: NOTICE: iscsi session(4) - session logout failed (1)
iscsi: NOTICE: iscsi discovery failure - SendTargets method is not enabled
iscsi: NOTICE: iscsi discovery failure - iSNS method is not enabled
You can safely ignore these messages or you can run the following command
just prior to reboot to avoid the messages:
# svcadm disable -t iscsimount
After the devices have been discovered by the Solaris iSCSI initiator,
the login negotiation occurs automatically. The Solaris iSCSI driver determines
the number of available LUNs and creates the device nodes. Then, the iSCSI
devices can be treated as any other SCSI device.
Monitoring Your iSCSI Configuration
You can display information about the iSCSI initiator and target devices
by using the iscsiadm list command.
Become superuser.
Display information about the iSCSI initiator.
# iscsiadm list initiator-node
Initiator node name: iqn..sun:01:b.425c293c
Initiator node alias: zzr1200
Login Parameters (Default/Configured):
Header Digest: NONE/-
Data Digest: NONE/-
Authentication Type: NONE
RADIUS Server: NONE
RADIUS access: unknown
Configured Sessions: 1
Display information about which discovery methods are in use.
# iscsiadm list discovery
Discovery:
Static: enabled
Send Targets: enabled
iSNS: enabled
Example&14&1
Displaying iSCSI Target InformationThe following example shows how to display the parameter settings for
a specific iSCSI target.
# iscsiadm list target-param iqn..abcstorage:sn.
Target: iqn..abcstorage:sn.
The iscsiadm list target-param -v command displays
the following information:
The authentication settings for the target
The default settings for the target login parameters
The configured value for each login parameter
The iscsiadm list target-param -v command displays
the default parameter value before the / designator
and the configured parameter value after the / designator.
If you have not configured any parameters, the configured parameter value
displays as a hyphen (-). For more information, see the
following examples.
# iscsiadm list target-param -v eui.5511 Target: eui.5511
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/-
Configured Sessions: 1
The following example output displays the parameters that were negotiated
between the target and the initiator.
# iscsiadm list target -v eui.5511
Target: eui.5511
Connections: 1
IP address (Local): 172.90.101.71:32813
IP address (Peer): 172.90.101.40:3260
Discovery Method: Static
Login Parameters (Negotiated):
Data Sequence In Order: yes
Data PDU In Order: yes
Default Time To Retain: 0
Default Time To Wait: 3
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
Modifying iSCSI Initiator and Target Parameters
You can modify parameters on both the iSCSI initiator and the iSCSI
target device. However, the only parameters that can be modified on the iSCSI
initiator are the following:
iSCSI initiator node name & You can change the initiator
node name to a different name. If you change the initiator node name, the
targets that were discovered by iSNS might be removed from the initiator's
target list, depending on the discovery domain configuration on the iSNS server
at the time when the name was changed. For more information, see .
Header digest & NONE, the default value or CRC32.
Data digest & NONE, the default value or CRC32.
Authentication and CHAP secret & For more information
about setting up authentication, see .
Configured sessions & For more information about configuring
multiple sessions, see .
The iSCSI driver provides default values for the iSCSI initiator and
iSCSI target device parameters. If you modify the parameters of the iSCSI
initiator, the modified parameters are inherited by the iSCSI target device,
unless the iSCSI target device already has different values.
Caution & Ensure that the target software supports the parameter to be
modified. Otherwise, you might be unable to log in to the iSCSI target device.
See your array documentation for a list of supported parameters.
Modifying iSCSI parameters should be done when I/O between the initiator
and the target is complete. The iSCSI driver reconnects the session after
the changes are made by using the iscsiadm modify command.
How to Modify iSCSI Initiator and Target
Parameters
The first part of this procedure illustrates how modified parameters
of the iSCSI initiator are inherited by the iSCSI target device. The second
part of this procedure shows how to actually modify parameters on the iSCSI
target device.
This optional procedure assumes that you are logged in to the local
system where access to an iSCSI target device has already been configured.
Become superuser.
List the current parameters of the iSCSI initiator and target
List the current parameters of the iSCSI initiator. For example:
initiator# iscsiadm list initiator-node
Initiator node name: iqn..sun:01:b.425c293c
Initiator node alias: zzr1200
Login Parameters (Default/Configured):
Header Digest: NONE/-
Data Digest: NONE/-
Authentication Type: NONE
RADIUS Server: NONE
RADIUS access: unknown
Configured Sessions: 1
List the current parameters of the iSCSI target device. For example:
initiator# iscsiadm list target-param -v iqn..abcstorage:sn.
Target: iqn..abcstorage:sn.
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/-
Configured Sessions: 1
Note that both header digest and data digest parameters are currently
set to NONE for both the iSCSI initiator and the iSCSI target device.
To review the default parameters of the iSCSI target device, see the iscsiadm list target-param output in .
Modify the parameter of the iSCSI initiator.
For example,
set the header digest to CRC32.
initiator# iscsiadm modify initiator-node -h CRC32
If you change the initiator node name, the targets that were discovered
by iSNS might be logged out and removed from the initiator's target list,
if the new name does not belong to the same discovery domain as that of the
targets. However, if the targets are in use, they are not removed.
For example,
if a file is open or a file system is mounted on these targets, the targets
will not removed.
You might also see new targets after the name change if these targets
and the new initiator node name belong to the same discovery domain.
Verify that the parameter was modified.
Display the updated parameter information for the iSCSI initiator.
For example:
initiator# iscsiadm list initiator-node
Initiator node name: iqn..sun:01:b.425c293c
Initiator node alias: zzr1200
Login Parameters (Default/Configured):
Header Digest: NONE/CRC32
Data Digest: NONE/-
Authentication Type: NONE
RADIUS Server: NONE
RADIUS access: unknown
Configured Sessions: 1
Note that the header digest is now set to CRC32.
Display the updated parameter information for the iSCSI target
device. For example:
initiator# iscsiadm list target-param -v iqn..abcstorage:sn.
Target: iqn..abcstorage:sn.
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: CRC32/-
Data Digest: NONE/-
Configured Sessions: 1
Note that the header digest is now set to CRC32.
Verify that the iSCSI initiator has reconnected to the iSCSI target.
For example:
initiator# iscsiadm list target -v iqn..abcstorage:sn.
Target: iqn..abcstorage:sn.
Connections: 1
IP address (Local): nnn.nn.nn.nnn:64369
IP address (Peer): nnn.nn.nn.nnn:3260
Discovery Method: SendTargets
Login Parameters (Negotiated):
Header Digest: CRC32
Data Digest: NONE
(Optional) Unset an iSCSI initiator parameter or an iSCSI target
device parameter.
You can unset a parameter by setting it back
to its default setting by using the iscsiadm modify command.
Or, you can use the iscsiadm remove command to reset all
target properties to the default settings.
The iscsiadm modify target-param command changes
only the parameters that are specified on the command line.
The following example shows how to reset the header digest to NONE:
initiator# iscsiadm modify target-param -h none iqn..abcstorage:sn...
For information about the iscsiadm remove target-param command,
Setting Up Solaris iSCSI Multipathed Devices
Consider the following guidelines for using Solaris iSCSI multipathed
(MPxIO) devices:
Solaris iSCSI and MPxIO &
MPxIO supports target port aggregation and availability in Solaris iSCSI configurations
that configure multiple sessions per target (MS/T) on the iSCSI initiator.
Use IPMP for aggregation and failover of two or more NICs.
A basic configuration for an iSCSI host is a server with two
NICs that are dedicated to iSCSI traffic. The NICs are configured by using
IPMP. Additional NICs are provided for non-iSCSI traffic to optimize performance.
Active multipathing can only be achieved by using the Solaris
iSCSI MS/T feature, and the failover and redundancy of an IPMP configuration.
If one NIC fails in an IPMP configuration, IPMP handles the
failover. The MPxIO driver does not notice the failure. In a non-IPMP configuration,
the MPxIO driver fails and offlines the path.
If one target port fails in an IPMP configuration, the MPxIO
driver notices the failure and provides the failover. In a non-IPMP configuration,
the MPxIO driver notices the failure and provides the failover.
For more information about using the Solaris iSCSI MS/T feature with
IPMP and multipathing, see SunSolve Infodoc 207607, Understanding
an iSCSI MS/T multi-path configuration.
For information about configuring multiple sessions per target,
For information about configuring IPMP, see .
Solaris iSCSI, Fibre-Channel (FC),
and MPxIO & The MPxIO driver provides the following behavior
in more complex iSCSI/FC configurations:
If you have dual iSCSI to FC bridges in an FC SAN, iSCSI presents
target paths to MPxIO. MPxIO matches the unique SCSI per LUN identifier, and
if they are identical, presents one path to the iSCSI driver.
If you have a configuration that connects a target by using
both iSCSI and FC, the MPxIO driver can provide different transports to the
same device. In this configuration, MPxIO utilizes both paths.
If you are using iSCSI and FC in combination with MPxIO, make
sure that the MPxIO settings in the /kernel/drv/fp.conf file
and the /kernel/drv/iscsi.conf files match the MPxIO
configuration that you want supported. For example, in fp.conf,
you can determine whether MPxIO is enabled globally on the HBA or on a per-port
Third-party hardware considerations&
Find out if your third-party HBA is qualified to work with Solaris iSCSI and
If you are using a third-party HBA, you might need to ask
your third-party HBA vendor for the symmetric-option information for the /kernel/drv/scsi_vhci.conf file.
How to Enable Multiple iSCSI Sessions for a Target
This procedure can be used to create multiple iSCSI sessions that connect
to a single target. This scenario is useful with iSCSI target devices that
support login redirection or have multiple target portals in the same target
portal group. Use iSCSI multiple sessions per target with Solaris SCSI Multipathing
(MPxIO). You can also achieve higher bandwidth if you utilize multiple NICs
on the host side to connect to multiple portals on the same target.
The MS/T feature creates two or more sessions on the target by varying
the initiator's session ID (ISID). Enabling this feature creates two SCSI
layer paths on the network so that multiple targets are exposed through the
iSCSI layer to the Solaris I/O layer. The MPxIO driver handles the reservations
across these paths.
For more information about how iSCSI interacts with MPxIO paths, see .
Review the following items before configuring multiple sessions for
an iSCSI target:
A typical MS/T configuration has two or more configured-sessions.
However, if your storage supports multiple TPGTs and if you are
using SendTarget discovery on your host system, then the number of configured
sessions can be set to 1. SendTarget discovery automatically detects the existence
of multiple paths and multiple target sessions are created.
Confirm that the mxpio configuration parameter
is enabled in the /kernel/drv/iscsi.conf file.
# cd /kernel/drv
# grep mpxio iscsi.conf
iscsi.conf:mpxio-disable="no";
Confirm that the multiple network connections are configured
by using IPMP.
Confirm that the multiple network connections are available.
# ifconfig -a
Become superuser.
List the current parameters for the iSCSI initiator and target.
List the current parameters for the iSCSI initiator. For example:
initiator# iscsiadm list initiator-node
Initiator node name: iqn..sun:01:b.425c293c
Initiator node alias: zzr1200
Configured Sessions: 1
List the current parameters of the iSCSI target device. For example:
initiator# iscsiadm list target-param -v iqn..abcstorage:sn.
Target: iqn..abcstorage:sn.
Configured Sessions: 1
The configured sessions value is the number of configured iSCSI sessions
that will be created for each target name in a target portal group.
Select one of the following to modify the number of configured
sessions either at the initiator node to apply to all targets or at a target
level to apply to a specific target.
The number of sessions for
a target must be between 1 and 4.
Apply the parameter to the iSCSI initiator node.
initiator# iscsiadm modify initiator-node -c 2
Apply the parameter to the iSCSI target.
For example:
initiator# iscsiadm modify target-param -c 2
iqn..abcstorage:sn.
Bind configured sessions to one or more local IP addresses.
Configured sessions can also be bound to a specific local IP address.
Using this method, one or more local IP addresses are supplied in a comma-separated
Each IP address represents an iSCSI session. This method can also be
done at the initiator-node or target-param level.
For example:
initiator# iscsiadm modify initiator-node -c 10.0.0.1,10.0.0.2
If the specified IP address is not routable, the address is ignored
and the default Solaris route and IP address is used for this session.
Verify that the parameter was modified.
Display the updated information for the initiator node. For example:
initiator# iscsiadm list initiator-node
Initiator node name: iqn..sun:01:b.425c293c
Initiator node alias: zzr1200
Configured Sessions: 2
Display the updated information for the target node. For example:
initiator# iscsiadm list target-param -v iqn..abcstorage:sn.
Target: iqn..abcstorage:sn.
Configured Sessions: 2
List the multiple paths by using the mpathadm list lu command
to confirm that the OS device name matches the iscsiadm list output,
and that the path count is 2 or more.
Troubleshooting iSCSI Configuration Problems
The following tools are available to troubleshoot general iSCSI configuration
snoop & This tool has been updated
to support iSCSI packets.
wireshark & This product is available
Both tools can filter iSCSI packets on port 3260.
The following sections describe various iSCSI troubleshooting and error
message resolution scenarios.
No Connections to the iSCSI Target From the Local
How to Troubleshoot iSCSI Connection Problems
Become superuser.
List your iSCSI target information.
For example:
initiator# iscsiadm list target
Target: iqn..abcstorage:6-8a401-bcfff02df8a421df-zzr1200-01
TPGT: default
Connections: 0
If no connections are listed in the iscsiadm list target output,
check the /var/adm/messages file for possible reasons
why the connection failed.
You can also verify whether the connection
is accessible by using the ping command or by connecting
to the storage device's iSCSI port by using the telnet command
to ensure that the iSCSI service is available. The default port is 3260.
In addition, check the storage device's log file for errors.
If your target is not listed in the iscsiadm list target output,
check the /var/adm/messages file for possible causes.
If you are using SendTargets as the discovery method, try listing the discovery-address using the -v option to ensure
that the expected targets are visible to the host. For example:
initiator# iscsiadm list discovery-address -v 10.0.0.1
Discovery Address: 10.0.0.1:3260
Target name: eui.dfc0
Target address:
10.0.0.1:11824
Target name: eui.e07b
Target address:
10.0.0.1:11824
If you are using iSNS as the discovery method, try enabling the iSNS
discovery method and listing the isns-server using
the -v option to ensure that the expected targets are visible
to the host. For example:
initiator# iscsiadm list isns-server -v
iSNS Server IP Address: 10.20.56.56:3205
Target name: iqn..xyz:sn.1234566
Target address:
10.20.57.161:3260, 1
Target name: iqn..abc:group-0:154:abc-65-01
Target address:
10.20.56.206:3260, 1
Target name: iqn..abc:group-0:154:abc-65-02
Target address:
10.20.56.206:3260, 1
iSCSI Device or Disk Is Not Available on the Local
How to Troubleshoot iSCSI Device or Disk Unavailability
Become superuser.
Identify the LUNs that were discovered on this target during enumeration.
For example:
# iscsiadm list target -S
Target: iqn..abcstorage:6-8a401-bcfff02df8a421df-zzr1200-01
TPGT: default
Connections: 1
Product: 0010
OS Device Name: /dev/rdsk/c3t34d0s2
The -S option shows which LUNs were discovered on this
target during enumeration. If you think a LUN should be listed but it is not,
review the /var/adm/messages file to see if an error
was reported. Check the storage device's log files for errors. Also, ensure
that any storage device LUN masking is properly configured.
Use LUN Masking When Using the iSNS Discovery Method
Avoid using the iSNS discovery domain as the means to control storage
authorization to specific initiators. Use LUN masking instead
if you want to make sure that only authorized initiators can access a LUN.
If you remove a target from a discovery domain while the target is in
use, the iSCSI initiator does not log out from this target. If you do not
want this initiator to access this target (and the associated LUNs), you must
use LUN masking. Removing the target from the discovery domain is not sufficient.
General iSCSI Error Messages
This section describes the iSCSI messages that might be found in the /var/adm/messages file and potential solutions for recovery.
The message format is as follows:
iscsi TYPE (OID) STRING (STATUS-CLASS#/STATUS-DETAIL#)
Is either connection or session.
Is the object ID of the connection or session. This ID is
unique for an OS instance.
Is a description of the condition.
STATUS-CLASS#/STATUS-DETAIL#
These values are returned in an iSCSI login response as defined
by RFC 3720.
iscsi connection(OID)
login failed - Miscellaneous iSCSI initiator errors.
The device login failed due to some form of
initiator error.
iscsi connection(OID)
login failed - Initiator could not be successfully authenticated.
The device could not successfully authenticate
the initiator.
If applicable, verify that the settings for
CHAP names, CHAP passwords, or the RADIUS server are correct.
iscsi connection(OID)
login failed - Initiator is not allowed access to the given target.
The device cannot allow the initiator access
to the iSCSI target device.
Verify your initiator name and confirm that
it is properly masked or provisioned by the storage device.
iscsi connection(OID)
login failed - Requested ITN does not exist at this address.
The device does not provide access to the iSCSI
target name (ITN) that you are requesting.
Verify that the initiator discovery information
is specified properly and that the storage device is configured properly.
iscsi connection(OID)
login failed - Requested ITN has been removed and no forwarding address is
The device can no longer provide access to the
iSCSI target name (ITN) that you are requesting.
Verify that the initiator discovery information
has been specified properly and that the storage device has been configured
iscsi connection(OID)
login failed - Requested iSCSI version range is not supported by the target.
The initiator's iSCSI version is not supported
by the storage device.
iscsi connection(OID)
login failed - No more connections can be accepted on this Session ID (SSID).
The storage device cannot accept another connection
for this initiator node to the iSCSI target device.
iscsi connection(OID)
login failed - Missing parameters (e.g., iSCSI initiator and/or target name).
The storage device is reporting that the initiator
or target name has not been properly specified.
Properly specify the iSCSI initiator or target
iscsi connection(OID)
login failed - Target hardware or software error.
The storage device encountered a hardware or
software error.
Consult the storage documentation, or contact
the storage vendor for further assistance.
iscsi connection(OID)
login failed - iSCSI service or target is not currently operational.
The storage device is currently not
operational.
Consult the storage documentation, or contact
the storage vendor for further assistance.
iscsi connection(OID)
login failed - Target has insufficient session, connection or other resources.
The storage device has insufficient resources.
Consult the storage documentation, or contact
the storage vendor for further assistance.
iscsi connection(OID)
login failed - unable to initialize authentication
iscsi connection(OID) login failed - unable to set authentication
iscsi connection(OID) login failed - unable
to set username
iscsi connection(OID) login failed - unable
to set password
iscsi connection(OID) login failed - unable
to set ipsec
iscsi connection(OID) login failed - unable
to set remote authentication
The initiator was unable to initialize or set
authentication properly.
Verify that your initiator settings for authentication
are properly configured.
iscsi connection(OID)
login failed - unable to make login pdu
The initiator was unable to make a login payload
data unit (PDU) based on the initiator or storage device settings.
Try resetting any target login parameters
or other nondefault settings.
iscsi connection(OID)
login failed - failed to transfer login
iscsi connection(OID) login failed - failed to receive login response
The initiator failed to transfer or receive
a login payload data unit (PDU) across the network connection.
Verify that the network connection is reachable.
iscsi connection(OID)
login failed - received invalid login response (OP CODE)
The storage device has responded to a login
an unexpected response.
iscsi connection(OID)
login failed - login failed to authenticate with target
The initiator was unable to authenticate the
storage device.
Verify that your initiator settings for authentication
are properly configured.
iscsi connection(OID)
login failed - initiator name is required
An initiator name must be configured to perform
all actions.
Verify that the initiator name is configured.
iscsi connection(OID)
login failed - authentication receive failed
iscsi connection(OID) login failed - authentication transmit failed
The initiator was unable to transmit or receive
authentication information.
Verify network connectivity with the storage
device or the RADIUS server, as applicable.
iscsi connection(OID)
login failed - login redirection invalid
The storage device attempted to redirect the
initiator to an invalid destination.
Consult the storage documentation, or contact
the storage vendor for further assistance.
iscsi connection(OID)
login failed - target protocol group tag mismatch, expected &TPGT&, received &TPGT&
The initiator and target had a TPGT (target
portal group tag) mismatch.
Verify your TPGT discovery settings on the
initiator or the storage device.
iscsi connection(OID)
login failed - can't accept PARAMETER in security
The device responded with an unsupported login
parameter during the security phase of login.
The parameter name is noted for reference.
Consult the storage documentation, or contact the storage vendor for further
assistance.
iscsi connection(OID)
login failed - HeaderDigest=CRC32 is required, can't accept VALUE
iscsi connection(OID) login failed - DataDigest=CRC32
is required, can't accept VALUE
The initiator is only configured to accept a HeaderDigest or DataDigest that is set to CRC32 for this target. The device returned the value of VALUE.
Verify that the initiator and device digest
settings are compatible.
iscsi connection(OID)
login failed - HeaderDigest=None is required, can't accept VALUE
iscsi connection(OID) login failed - DataDigest=None
is required, can't accept VALUE
The initiator is only configured to accept a HeaderDigest or DataDigest that is set to NONE
for this target. The device returned the value of VALUE.
Verify that the initiator and device digest
settings are compatible.
iscsi connection(OID)
login failed - can't accept PARAMETER
The initiator does not support this parameter.
iscsi connection(OID)
login failed - can't accept MaxOutstandingR2T VALUE
The initiator does not accept MaxOutstandingR2T of the noted VALUE.
iscsi connection(OID)
login failed - can't accept MaxConnections VALUE
The initiator does not accept the maximum connections
of the noted VALUE.
iscsi connection(OID)
login failed - can't accept ErrorRecoveryLevel VALUE
The initiator does not accept an error recovery
level of the noted VALUE.
iscsi session(OID) NAME offline
All connections for this target NAME have
been removed or have failed.
iscsi connection(OID)
failure - unable to schedule enumeration
The initiator was unable to enumerate the LUNs
on this target.
You can force LUN enumeration by running
the devfsadm -i iscsi command. For more information, see .
iscsi connection(OID)
unable to connect to target NAME (errno:ERRNO)
The initiator failed to establish a network
connection.
For information about the specific ERRNO on the connection failure, see the /usr/include/sys/errno.h file.}