test

System Administration Guide: Devices and File Systems

Chapter 14 Configuring Solaris iSCSI Targets and Initiators (Tasks)

This chapter describes how to configure Solaris iSCSI targets, available starting in the Solaris Express 8/06 release. Solaris iSCSI initiators are available starting in the Solaris Express 2/05 release. For information about the procedures associated with configuring iSCSI targets and initiators, see Setting Up Solaris iSCSI Targets and Initiators (Task Map).

For information about Solaris iSCSI initiator features in the latest Solaris Express release, see What's New in Disk Management?

For information about the Solaris iSNS support in the Solaris Express Developer Edition 1/08 release, see Chapter 15, Configuring and Managing the Solaris Internet Storage Name Service (iSNS).

For troubleshooting Solaris iSCSI configuration problems, see Troubleshooting iSCSI Configuration Problems.

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:

http://www.ietf.org/rfc/rfc3720.txt

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:

Here are the benefits of using Solaris iSCSI targets and initiators:

Here are the current limitations or restrictions of using the Solaris iSCSI initiator software:

Solaris iSCSI Software and Hardware Requirements

Setting Up Solaris iSCSI Targets and Initiators (Task Map)

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. 

Solaris iSCSI Software and Hardware Requirements

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. 

Setting Up Your Solaris iSCSI Target Devices

 

Set up iSNS discovery on your Solaris iSCSI target, if an iSNS server is available. 

How to Configure iSNS Discovery for the Solaris iSCSI Target

3. Prepare for your Solaris iSCSI configuration. 

Make sure you have the correct software versions and hardware installed. 

How to Prepare for a Solaris iSCSI Configuration

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. 

How to Configure CHAP Authentication for Your iSCSI Initiator

   

How to Configure CHAP Authentication for Your iSCSI Target

 

Consider using a third-party RADIUS server to simplify CHAP management. 

How to Configure RADIUS for Your iSCSI Configuration

5. Configure the iSCSI target discovery method. 

Select the iSCSI target discovery method best suited for your environment. 

How to Configure iSCSI Target Discovery

6. (Optional) Remove discovered iSCSI targets. 

You might need to remove a discovered iSCSI target. 

How to Remove Discovered iSCSI Targets

7. Monitor your iSCSI configuration. 

Monitor your iSCSI configuration by using the iscsiadm command.

Monitoring Your iSCSI Configuration

8. (Optional) Modify your iSCSI configuration. 

You might want to modify your iSCSI target settings such as the header and data digest parameters. 

How to Modify iSCSI Initiator and Target Parameters

9. (Optional) Set up Solaris iSCSI multipathed devices. 

Determine whether you want to set up Solaris iSCSI multipathed devices. 

Setting Up Solaris iSCSI Multipathed Devices

 

Use this procedure to create multiple iSCSI sessions that connect to a single target. 

How to Enable Multiple iSCSI Sessions for a Target

Configuring Solaris iSCSI Targets and Initiators

Configuring your Solaris iSCSI targets and initiators involves the following steps:

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.

Term 

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.

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.

ProcedureHow 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.

  1. Become superuser.

  2. Verify that the iSCSI software packages are installed. 


    initiator# pkginfo SUNWiscsiu SUNWiscsir
system      SUNWiscsiu Sun iSCSI Device Driver (root)
system      SUNWiscsir Sun iSCSI Management Utilities (usr)

  3. Verify that you are running at least the Solaris Express 8/06 release.

  4. Confirm that your TCP/IP network is setup.

  5. 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 Troubleshooting iSCSI Configuration Problems.

    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 ZFS and Solaris iSCSI Improvements in Solaris ZFS Administration Guide.

After the target device is set up, use the iscsiadm command to identify your iSCSI targets, which will discover and use the iSCSI target device.

For more information, see iscsitadm(1M) and iscsiadm(1M).

The basic process is as follows:

ProcedureHow to Create an iSCSI Target

This procedure assumes that you are logged in to the local system that contains the iSCSI targets.

  1. Become superuser.

  2. Identify the backing store directory.

    For example:


    target# iscsitadm modify admin -d /export/sandbox

  3. Create an iSCSI target.

    For example:


    target# iscsitadm create target --size 2g sandbox

  4. Display information about the iSCSI target.

    For example:


    target# iscsitadm list target -v sandbox

  5. Set up your iSCSI initiator to discover and use this target.

    For more information, see How to Configure iSCSI Target Discovery.

ProcedureHow to Configure iSNS Discovery for the Solaris iSCSI Target

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.

  1. Become superuser.

  2. 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 targets.

  3. 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. For 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. Refer to the array vendor's documentation for instructions on setting up the secret key on the array.

iSCSI supports unidirectional and bidirectional authentication:

ProcedureHow to Configure CHAP Authentication for Your iSCSI Initiator

This procedure assumes that you are logged in to the local system where you want to securely access the configured iSCSI target device.

  1. Become superuser.

  2. Determine whether you want to configure unidirectional or bidirectional CHAP.

    • 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.

  3. 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
    Note –

    The CHAP secret length must be a minimum of 12 characters and a maximum of 16 characters.

  4. (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.

  5. 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.

  6. Select one of the following to enable or disable Bidirectional CHAP.

    • 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

  7. Bidirectional CHAP – Set the authentication method to CHAP on the target.

    For example:


    initiator# iscsiadm modify target-param --authentication CHAP eui.5000ABCD78945E2B

  8. 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

  9. Bidirectional CHAP - Set the CHAP name on the target.

    By 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

ProcedureHow to Configure CHAP Authentication for Your iSCSI Target

This procedure assumes that you are logged in to the local system that contains the iSCSI targets.

  1. Become superuser.

  2. 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

  3. 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

  4. 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.1986-03.com.sun: 01:00e081553307.4399f40e monster620

  5. 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

  6. 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

  7. 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:

ProcedureHow 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.

  1. Become superuser.

  2. 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

  3. Configure the initiator node with the shared secret of the RADIUS server.


    initiator# iscsiadm modify initiator-node --radius-shared-secret
    Note –

    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.

  4. 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 recovery.


empty RADIUS shared secret

Cause:

The RADIUS server is enabled on the initiator, but the RADIUS shared secret is not set.

Solution:

Configure the initiator with the RADIUS shared secret. For more information, see How to Configure RADIUS for Your iSCSI Configuration.


WARNING: RADIUS packet authentication failed

Cause:

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, see How to Configure RADIUS for Your iSCSI Configuration.

ProcedureHow 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.

  1. Become superuser.

  2. 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.

      For example:


      initiator# iscsiadm add static-config eui.5000ABCD78945E2B,10.0.0.1

    The iSCSI connection is not initiated until the discovery method is enabled. See the next step.

  3. 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

  4. Create the iSCSI device links for the local system.


    initiator# devfsadm -i iscsi

ProcedureHow 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.

  1. Become superuser.

  2. (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

  3. Remove an iSCSI device discovery entry using one of the following:

    • Remove an iSCSI SendTargets discovery entry.

      For example:


      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.5000ABCD78945E2B,10.0.0.1
    Note –

    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.

  4. 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 make the iSCSI drive available on reboot, create the file system, and add an entry to the /etc/vfstab file as you would with a UFS file system on a SCSI device.

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@w500000e010685cf1,0
       1. c0t2d0 <SUN72G cyl 14087 alt 2 hd 24 sec 424>
          /pci@8,600000/SUNW,qlc@4/fp@0,0/ssd@w500000e0106e3ba1,0
       2. c3t0d0 <ABCSTORAGE-100E-00-2.2 cyl 20813 alt 2 hd 16 sec 63>
          /iscsi/disk@0000iqn.2001-05.com.abcstorage%3A6-8a0900-477d70401-
           b0fff044352423a2-hostname-020000,0
       3. c3t1d0 <ABCSTORAGE-100E-00-2.2 cyl 20813 alt 2 hd 16 sec 63>
           /iscsi/disk@0000iqn.2001-05.com.abcstorage%3A6-8a0900-3fcd70401 
           -085ff04434f423a2-hostname-010000,0
.
.
.
      21. c4t60A98000686F694B2F59775733426B77d0 <ABCSTORAGE-LUN-0.2 cyl  
          4606 alt 2 hd 16 sec 256>
          /scsi_vhci/ssd@g60a98000686f694b2f59775733426b77
      22. c4t60A98000686F694B2F59775733434C41d0 <ABCSTORAGE-LUN-0.2 cyl  
          4606 alt 2 hd 16 sec 256>
          /scsi_vhci/ssd@g60a98000686f694b2f59775733434c41

ProcedureMonitoring Your iSCSI Configuration

You can display information about the iSCSI initiator and target devices by using the iscsiadm list command.

  1. Become superuser.

  2. Display information about the iSCSI initiator.

    For example:


    # iscsiadm list initiator-node
Initiator node name: iqn.1986-03.com.sun:01:0003ba4d233b.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

  3. Display information about which discovery methods are in use.

    For example:


    # iscsiadm list discovery
Discovery:
	Static: enabled
	Send Targets: enabled
	iSNS: enabled
Example 14–1 Displaying iSCSI Target Information

The following example shows how to display the parameter settings for a specific iSCSI target.


# iscsiadm list target-param iqn.1992-08.com.abcstorage:sn.33592219
        Target: iqn.1992-08.com.abcstorage:sn.33592219

The iscsiadm list target-param -v command displays the following information:

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.50060e8004275511 Target: eui.50060e8004275511
        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/-
        Configured Sessions: 1

The following example output displays the parameters that were negotiated between the target and the initiator.


# iscsiadm list target -v eui.50060e8004275511
Target: eui.50060e8004275511
        TPGT: 1
        ISID: 4000002a0000
        Connections: 1
                CID: 0
                  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:

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 – 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.

ProcedureHow 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.

  1. Become superuser.

  2. List the current parameters of the iSCSI initiator and target device.

    1. List the current parameters of the iSCSI initiator. For example:


      initiator# iscsiadm list initiator-node
Initiator node name: iqn.1986-03.com.sun:01:0003ba4d233b.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

    2. List the current parameters of the iSCSI target device. For example:


      initiator# iscsiadm list target-param -v iqn.1992-08.com.abcstorage:sn.84186266
Target: iqn.1992-08.com.abcstorage:sn.84186266
        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/-
         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 Example 14–1.

  3. 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.

  4. Verify that the parameter was modified.

    1. Display the updated parameter information for the iSCSI initiator. For example:


      initiator# iscsiadm list initiator-node
Initiator node name: iqn.1986-03.com.sun:01:0003ba4d233b.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.

    2. Display the updated parameter information for the iSCSI target device. For example:


      initiator# iscsiadm list target-param -v iqn.1992-08.com.abcstorage:sn.84186266
Target: iqn.1992-08.com.abcstorage:sn.84186266
        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: CRC32/-
                Data Digest: NONE/-
        Configured Sessions: 1

      Note that the header digest is now set to CRC32.

  5. Verify that the iSCSI initiator has reconnected to the iSCSI target. For example:


    initiator# iscsiadm list target -v iqn.1992-08.com.abcstorage:sn.84186266
Target: iqn.1992-08.com.abcstorage:sn.84186266
        TPGT: 2
        ISID: 4000002a0000
        Connections: 1
                CID: 0
                  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

  6. (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.1992-08.com.abcstorage:sn...

    For information about the iscsiadm remove target-param command, see iscsiadm(1M).

Setting Up Solaris iSCSI Multipathed Devices

Consider the following guidelines for using Solaris iSCSI multipathed (MPxIO) devices:

ProcedureHow 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 Setting Up Solaris iSCSI Multipathed Devices.

Review the following items before configuring multiple sessions for an iSCSI target:

  1. Become superuser.

  2. List the current parameters for the iSCSI initiator and target.

    1. List the current parameters for the iSCSI initiator. For example:


      initiator# iscsiadm list initiator-node
Initiator node name: iqn.1986-03.com.sun:01:0003ba4d233b.425c293c
Initiator node alias: zzr1200
        .
        .
        .
        Configured Sessions: 1

    2. List the current parameters of the iSCSI target device. For example:


      initiator# iscsiadm list target-param -v iqn.1992-08.com.abcstorage:sn.84186266
Target: iqn.1992-08.com.abcstorage:sn.84186266
        Alias: -
        .
        .
        .
        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.

  3. 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.

      For example:


      initiator# iscsiadm modify initiator-node -c 2

    • Apply the parameter to the iSCSI target.

      For example:


      initiator# iscsiadm modify target-param -c 2  iqn.1992-08.com.abcstorage:sn.84186266

    • 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 list. 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
      Note –

      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.

  4. Verify that the parameter was modified.

    1. Display the updated information for the initiator node. For example:


      initiator# iscsiadm list initiator-node
Initiator node name: iqn.1986-03.com.sun:01:0003ba4d233b.425c293c
Initiator node alias: zzr1200
        .
        .
        .
        Configured Sessions: 2

    2. Display the updated information for the target node. For example:


      initiator# iscsiadm list target-param -v iqn.1992-08.com.abcstorage:sn.84186266
Target: iqn.1992-08.com.abcstorage:sn.84186266
        Alias: -
        .
        .
        .
        Configured Sessions: 2

  5. 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 problems:

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 System

ProcedureHow to Troubleshoot iSCSI Connection Problems

  1. Become superuser.

  2. List your iSCSI target information.

    For example:


    initiator# iscsiadm list target
Target: iqn.2001-05.com.abcstorage:6-8a0900-37ad70401-bcfff02df8a421df-zzr1200-01
        TPGT: default
        ISID: 4000002a0000
        Connections: 0

  3. 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.

  4. 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.210000203787dfc0
		Target address:        10.0.0.1:11824
	Target name: eui.210000203787e07b
		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.1992-08.com.xyz:sn.1234566
                Target address:   10.20.57.161:3260, 1
        Target name: iqn.2003-10.com.abc:group-0:154:abc-65-01
                Target address:   10.20.56.206:3260, 1
        Target name: iqn.2003-10.com.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 System

ProcedureHow to Troubleshoot iSCSI Device or Disk Unavailability

  1. Become superuser.

  2. Identify the LUNs that were discovered on this target during enumeration.

    For example:


    # iscsiadm list target -S
Target: iqn.2001-05.com.abcstorage:6-8a0900-37ad70401-bcfff02df8a421df-zzr1200-01
        TPGT: default
        ISID: 4000002a0000
        Connections: 1
        LUN: 0
            Vendor:  ABCSTOR
            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#)
TYPE

Is either connection or session.

OID

Is the object ID of the connection or session. This ID is unique for an OS instance.

STRING

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.

Cause:

The device login failed due to some form of initiator error.


iscsi connection(OID) login failed - Initiator could not be successfully authenticated.

Cause:

The device could not successfully authenticate the initiator.

Solution:

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.

Cause:

The device cannot allow the initiator access to the iSCSI target device.

Solution:

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.

Cause:

The device does not provide access to the iSCSI target name (ITN) that you are requesting.

Solution:

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 provided.

Cause:

The device can no longer provide access to the iSCSI target name (ITN) that you are requesting.

Solution:

Verify that the initiator discovery information has been specified properly and that the storage device has been configured properly.


iscsi connection(OID) login failed - Requested iSCSI version range is not supported by the target.

Cause:

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).

Cause:

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).

Cause:

The storage device is reporting that the initiator or target name has not been properly specified.

Solution:

Properly specify the iSCSI initiator or target name.


iscsi connection(OID) login failed - Target hardware or software error.

Cause:

The storage device encountered a hardware or software error.

Solution:

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.

Cause:

The storage device is currently not operational.

Solution:

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.

Cause:

The storage device has insufficient resources.

Solution:

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

Cause:

The initiator was unable to initialize or set authentication properly.

Solution:

Verify that your initiator settings for authentication are properly configured.


iscsi connection(OID) login failed - unable to make login pdu

Cause:

The initiator was unable to make a login payload data unit (PDU) based on the initiator or storage device settings.

Solution:

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

Cause:

The initiator failed to transfer or receive a login payload data unit (PDU) across the network connection.

Solution:

Verify that the network connection is reachable.


iscsi connection(OID) login failed - received invalid login response (OP CODE)

Cause:

The storage device has responded to a login with an unexpected response.


iscsi connection(OID) login failed - login failed to authenticate with target

Cause:

The initiator was unable to authenticate the storage device.

Solution:

Verify that your initiator settings for authentication are properly configured.


iscsi connection(OID) login failed - initiator name is required

Cause:

An initiator name must be configured to perform all actions.

Solution:

Verify that the initiator name is configured.


iscsi connection(OID) login failed - authentication receive failed


iscsi connection(OID) login failed - authentication transmit failed

Cause:

The initiator was unable to transmit or receive authentication information.

Solution:

Verify network connectivity with the storage device or the RADIUS server, as applicable.


iscsi connection(OID) login failed - login redirection invalid

Cause:

The storage device attempted to redirect the initiator to an invalid destination.

Solution:

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>

Cause:

The initiator and target had a TPGT (target portal group tag) mismatch.

Solution:

Verify your TPGT discovery settings on the initiator or the storage device.


iscsi connection(OID) login failed - can't accept PARAMETER in security stage

Cause:

The device responded with an unsupported login parameter during the security phase of login.

Solution:

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

Cause:

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.

Solution:

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

Cause:

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.

Solution:

Verify that the initiator and device digest settings are compatible.


iscsi connection(OID) login failed - can't accept PARAMETER

Cause:

The initiator does not support this parameter.


iscsi connection(OID) login failed - can't accept MaxOutstandingR2T VALUE

Cause:

The initiator does not accept MaxOutstandingR2T of the noted VALUE.


iscsi connection(OID) login failed - can't accept MaxConnections VALUE

Cause:

The initiator does not accept the maximum connections of the noted VALUE.


iscsi connection(OID) login failed - can't accept ErrorRecoveryLevel VALUE

Cause:

The initiator does not accept an error recovery level of the noted VALUE.


iscsi session(OID) NAME offline

Cause:

All connections for this target NAME have been removed or have failed.


iscsi connection(OID) failure - unable to schedule enumeration

Cause:

The initiator was unable to enumerate the LUNs on this target.

Solution:

You can force LUN enumeration by running the devfsadm -i iscsi command. For more information, see devfsadm(1M).


iscsi connection(OID) unable to connect to target NAME (errno:ERRNO)

Cause:

The initiator failed to establish a network connection.

Solution:

For information about the specific ERRNO on the connection failure, see the /usr/include/sys/errno.h file.