Open topic with navigation

Disconnected: You’re looking at a local copy of the Appliance Controller Documentation Center. The most current version is online at www.quantum.com/accdocs.

# iSCSI Tasks and Commands

Use the following tasks to manage iSCSI connections.

Note: For a list of all the Appliance Controller commands, see the Command Index.

Note: iSCSI TCP connections are supported on Quantum-supplied NIC cards for Gen 2 and R630 systems connecting to H-series, F-series, and QXS storage arrays. Other non-Quantum-supplied cards, and other Quantum appliances do not natively support iSCSI connections.

iSCSI Configuration Workflow
After you have cabled the server to the storage array and performed all prerequisites, you can configure your iSCSI network.

1. Determine the storage array and server ports and IP address to be used for the iSCSI connections.

2. Configure the storage array as the iSCSI target.

3. Configure the server NIC port IP addresses as iSCSI initiator ports.

## iSCSI Tasks and Commands for Appliance Controller 3.1.0 and later

Prerequisites

The following commands require StorNext 7.0.2 (or later).

Background

Platform iSCSI Version 2 (V2) was introduced in StorNext Appliances Software Release 6.3.0. Platform iSCSI V2, had certain limitations, like initiator with only 2 subnets, or limited support of VLAN, that have been addressed along other enhancements in version 3 (V3). However, post release of Platform iSCSI V2, additional enhancements were made to version 2 to support F2000 product converged L2 networking along with iSER. These new additions to Platform iSCSI are also described in this section as part of Platform iSCSI version 3.

Platform iSCSI Version 3 (in addition to Version 2) supports:

- Creating initiators with one, and up to four subnets.

- Creating initiators using one, and up to four host physical interfaces.

- Initiator subnets may share the same host physical interfaces.

- Initiator subnets may each have their own assigned VLAN.

- Each initiator command has added help and manual command line options:

  - A command help provides summary information on the command parameters (see Display Usage Information for an iSCSI Command).

  - A command manual provides detailed information about the command, the command parameters, and examples of the command use (see Display Usage Information for an iSCSI Command).

- Creating initiators with an L2 converged network setup along with iSCSI over Extended RDMA (iSER) configuration for accessing Block Storage products, like F2000, with VLAN prioritized iSCSI over RDMA traffic through a network that may be shared with other data traffic present. This additional enhancement was made available in Platform iSCSI version 2 after its original release and is documented in this section.

Display Usage Information for an iSCSI Command

You can display information about the usage of each command, in summary form with help, and in detail form with manual. An example of each command line argument is shown below.

iscsiadm create help

Using a command, like create, with or without the optional help parameter provides information on the command call arguments and summary description of what the command does.

iscsiadm create manual

Using a command, like create, with the manual parameter provides a manual page with a detailed description of all the command call arguments, their purpose, example of the use of the command, and reference to other relevant command manuals.

Create a TCP or iSER iSCSI Initiator

Platform iSCSI version 2 provided for creating an initiator with two named subnets (using subnet_a, and subnet_b call arguments), and for applying an identical VLAN ID to both of those subnets (using vlan_id). See iSCSI Tasks and Commands for Appliance Controller 3.0.x and earlier for details of version 2 iSCSI initiator creation and deletion

An initiator is created by providing a name for it, and a set of one to four system interfaces and subnets and their IP addresses, and optionally VLAN, communication protocol, storage networking setup information, and VLAN priority map.

If all provided information is correct and does not have conflict with any other existing initiators or targets or external entities use of the provided IP addresses, an initiator structure is built, the initiator is added to iSCSI plugin list of initiators, and then the initiator interfaces are brought up. If the latter action is successful, the call silently returns. Otherwise, an operational error is returned, indicating an external networking issue that need to be resolved externally. Once the external networking issues relating to the initiator interface are resolved, an iscsiadm network start for the initiator need to be issued to make another attempt to bring up the initiator subnets.

If any error occurs or any conflicts found in the provided information for creating the initiator, an error is returned with as much detailed information collected by iSCSI plugin about the encountered error/issue.

1. Log in to the Appliance Controller CLI.
2. Enter:

        iscsiadm create
                 initiator=<initiator name>
                 (one, and up to four, subnet definition as below)
                 subnet=[<interface[.vlan_id],ipaddress>]
                 [netmask=<netmask value>]
                 [mtu=<mtu value>] [iproto=iser] [vlan_id=<vlan id>]
                 [priority_map=<priority map>]
                 [storage_network=[dedicated_net | converged_net_l2]] [force]

Parameters:

initiator=initiator-name | Call argument to provide the name for the initiator.
subnet=interface[.vlan_id],ipaddress | Call argument to provide the interface name, followed by an optional VLAN ID, and the IP address for the subnet interface. Minimum one, and up to four, subnet(s) may be provided. interface[.vlan_id] provides the network interface alias name optionally followed by the VLAN ID for the interface. The .vlan_id in the subnet specification here may not be used in conjunction with the general vlan_id call argument (see vlan_id below). ipaddress the IP address for the subnet interface.
netmask=<netmask value> | Call argument to optionally provide the netmask value for the network of the initiator subnets. Note: The default value is 255.255.255.0.
mtu=<mtu value> | Call argument to optionally provide the MTU (maximum transfer unit) size for the initiator subnets network. Valid values are: jumbo (for 9000 bytes) standard (for 1500 bytes) Or a number between 1500–9000 bytes. Note: The default value is jumbo.
iproto =[tcp | iser] | Call argument to optionally provide the iSCSI communication protocol for the initiator. The supported iSCSI communication protocols are tcp (SCSI over TCP, also known as iSCSI), and iser (iSCSI over Extended RDMA). Enter a value of tcp or iser, depending on how the interface is used. Note: Default value is tcp.
vlan_id=<vlan_id> | Call argument to optionally apply the provided VLAN ID value to all initiator subnet interfaces. This call argument may not be used in conjunction with VLAN IDs specified via subnet entries (see subnet above).
priority_map=<priority map> | Call argument to optionally provide the egress priority map for the VLANs on the initiator subnets. The VLAN egress priority map is entered with up to 8 comma separated x:y values, where: X: Is a socket priority queue group, between 0 and 7 inclusive; X values may not be repeated. Y: Is a traffic class number, between 0 and 7 inclusive; Y values may be repeated to tag multiple socket priority groups to the same traffic class. Note: The priority_map call argument may only be used in conjunction with defined VLAN for the initiator subnets. When the priority_map call argument is used, it also sets the storage_network value to converged_net_l2 for the initiator. The call to create the initiator fails if the given priority map is already used by another initiator, unless the force call argument is used to override that check and to assign a priority map that is already used by another initiator to the new initiator. Note: The default value is none (in other words, do not use priority map) unless you use the storage_network value converged_net_l2, see below.
storage_network=[dedicated_net | converged_net_l2 ] | Call argument to optionally provide the type of storage network environment of the initiator. dedicated_net: This is the default storage network type when not using priority_map call argument for the initiator. In this type of setting, the initiator subnets are assumed to be operating in a dedicated network, not shared with other data traffic. converged_net_l2: This is the default storage network type when using priority_map call argument to prioritize the initiator subnets VLANs traffic at the switch. In this type of setting, the initiator subnets are assumed to be operating in a network shared with other data traffic, but with the initiator subnets traffic being prioritized over other data traffic at the switch. In absence of the priority_map call argument and presence of VLAN specification and storage_network=converged_net_l2 call argument, the initiator is created with the default priority map of 0:5, if not already used (see the priority_map description above). Quantum recommends you use the priority_map call argument for setting up L2 converged networking for the initiator, instead of this call argument with its limited functionality.

Example: Create a TCP initiator

> `iscsiadm create initiator=platform subnet =p1p1,192.168.0.47 subnet=p1p2,192.168.1.47 netmask=255.255.255.0 mtu=jumbo`

Possible Errors

The following error messages are displayed when any of these conditions is encountered when configuring iSCSI:

Given initiator name is already used by another initiator.
Given Interface name does not exist, or is assigned to another initiator or application.
Given IP address is not well-formed, or is already taken by a local interface or is used by a remote host.
Given netmask is not well-formed.
Given MTU is not acceptable (value is not between 1500 and 9000).
Given VLAN ID is used by another initiator subnets, in absence of using ‘force’ call argument to override.
Given priority_map is used by another initiator, in absence of using ‘force’ call argument to override.

In absence of any of the above syntactic and availability errors, then initiator is created, and its interfaces are brought up.

However, the run-time related network connectivity and accessibility, which is subject to the interfaces being connected to network and the network being available, are not guaranteed. For this reason, after creation of an iSCSI initiator, the user must run the show status command to ensure that the interfaces are linked up to the network and fix the cabling or any other networking issues before proceeding to adding targets to the initiator.

Next Steps: after creation an iSCSI initiator

1. Ensure that the interfaces are linked up to the network using the show initiator status command.

2. Fix cabling or any other networking issues as described in the show initiator status output description table above before adding targets to the initiator.

Show Initiator Status Command

Run the following command to obtain detailed information on the platform initiator just created.

> iscsiadm show initiator=platform status

Initiator Status Output:

The following shows the output of the show initiator=platform status command above:

    Please be patient while run-time information is being collected.
    {
    "initiator": [
    {
    "interfaces": [ "p1p1",
    "p1p2"
    ],
    "iproto": [ "tcp"
    ],
    "iqn": "iqn.1994-05.com.redhat:ec9dbf9d80bb", "mtu": "9000",

    "name": "platform", "netmask": "255.255.255.0",
    "storage_network": { "priority_map": "",
    "storage_network_type": "dedicated_net", "vlan_id": ""
    },
    "subnet_count": 2, "subnets": [
    {
    "interface": { "link_state": "UP",
    "name": "p1p1:iscsia",
    "speed": "25GbE"
    },
    "network": {
    "ip_address": "192.168.0.47", "ip_state": "UP", "runtime_mtu": "9000", "runtime_speed": "10GbE"
    }
    },
    {
    "interface": { "link_state": "UP",
    "name": "p1p2:iscsib",
    "speed": "25GbE"
    },
    "network": {

    "ip_address": "192.168.1.47", "ip_state": "UP", "runtime_mtu": "9000", "runtime_speed": "10GbE"
    }
    }
    ],
    "targets": []
    }
    ]
    }

Show Initiator Status Output Description

The following table shows the components comprising the show initiator status command output, and detailed description for each.

interfaces | This list depicts the list of interfaces used by this initiator.
storage_network | This dictionary holds information about the initiator parameters related to the type of storage networking this initiator is built for. storage_network_type: When relevant options are not specified on the command line, the default value of this parameter is dedicated_net implying that on the created subnets, the only users are the initiator and its targets, and no other. vlan_id: The value of this parameter is set to what is provided on the command line with vlan_id call argument, or separately for each initiator subnet using [.vlan_id] as described before. priority_map: This is the priority map setting for the outgoing packets of the VLANs of this initiator from the host. It is only a valid argument for initiators with VLAN configuration for their subnets. The value of this parameter is a comma-separated list of from_prio:to_prio values, where from_prio is the in-kernel (socket buffer, or skb) priority value, and to_prio is the 802.1Q VLAN packet priority that will be set on outgoing traffic frames from the VLAN. The priority of each packet will be used by the switch for prioritizing egress traffic frames based on their respective priority settings for forwarding them out of the switch.
subnet_count | The number of subnets in the subnets list.
subnets | The list of initiator subnet dictionaries. Each subnet dictionary comprises of an interface and a network sub-dictionary.
interface | The interface dictionary comprises of: name: The name of the interface (for example, p1p1:iscsia). The subnet interface name is a virtual interface name, created on top of the provided interface name for the subnet. Virtual interface names will be assigned as iscsia, iscsib, and so on. The virtual interface names allow for: Uniquely identifying the subnets of the iSCSI initiator internally, and externally. Configuring multiple subnets of the initiator on the same physical interface. In case of using VLANs, as will be seen in further examples in this document, the interface name will include the VLAN ID as well (for example, p1p1.100:iscsia). link_state: The state of this interface, whether it has network access (UP), or not (DOWN). Note that the in most cases determining the link_state depends on the ip_state of network the interface being in UP state. speed: The throughput speed of the underlying network interface.
network | The network dictionary comprises of: ip_address: The IP address assigned to this subnet interface. ip_state: The IP network state of this interface, configured up (UP), or down (DOWN). runtime_mtu: The run-time MTU of the network interface. Note: When you change the MTU of an initiator (using the new API described later in this document), until the time the initiator network is restarted the run-time MTU of the network interface becomes out-of-sync with the newly assigned MTU of the initiator. runtime_speed: The run-time speed of the network interface. Note: The run-time speed of the network interface might be different than the supported throughput of the interface described above as interface speed, depending on the limitation on the cable connected to the port, or administrative configuration from the switch of the throughput speed available to the port. Note: The runtime_speed of all initiator subnets must be (made) identical for the initiator to provide a balanced iSCSI service. If/when using NIC ports and cables that do not necessarily offer the same runtime speed, their speeds need to be adjusted at the port on the switch where those cables are connected to make the runtime_speed of all of the netowrks identical for all iSCSI initiator subnets.

Example: Create an Initiator with Four subnets using Two Interfaces

Do the following to create an initiator with four subnets, each two subnets sharing the same interface:

> iscsiadm create initiator=init-with-4subs subnet=p1p1,192.168.0.47 subnet=p1p1,192.168.1.47 subnet=p1p2,192.168.2.47 subnet=p1p2,192.168.3.47 netmask=255.255.255.0

Please be patient while the initiator configuration is being created.

> iscsiadm show initiator=init-with-4subnets status

Please be patient while run-time information is being collected.

Output:

{

"initiator": [

{

"interfaces": [

"p1p1",

"p1p2"

],

"iproto": [

"tcp"

],

"iqn": "iqn.1994-05.com.redhat:ec9dbf9d80bb",

"mtu": "9000",

"name": "init-with-4subs",

"netmask": "255.255.255.0",

"storage_network": {

"priority_map": "",

"storage_network_type": "dedicated_net",

"vlan_id": ""

},

"subnet_count": 4,

"subnets": [

{

"interface": {

"link_state": "UP",

"name": "p1p1:iscsia",

"speed": "25GbE"

},

"network": {

"ip_address": "192.168.0.47",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

},

...

> iscsiadm show initiator status

Output:

{

"interface": {

"link_state": "UP",

"name": "p1p1:iscsib",

"speed": "25GbE"

},

"network": {

"ip_address": "192.168.1.47",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

},

{

"interface": {

"link_state": "UP",

"name": "p1p2:iscsic",

"speed": "25GbE"

},

"network": {

"ip_address": "192.168.2.47",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

},

{

"interface": {

"link_state": "UP",

"name": "p1p2:iscsid",

"speed": "25GbE"

},

"network": {

"ip_address": "192.168.3.47",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

}

],

"targets": []

}

]

}

In the above output, parts of the output show the use of p1p1 interface for the first two subnets iscsia and iscsib, and the use of p1p2 interface for subnets iscsic and iscsid.

Example: Create an Initiator with Two VLANs on its Two Subnets

Do the following to create an initiator with two subnets, each subnet with its own requested VLAN ID on its interface:

> iscsiadm create initiator=init-with-vlans subnet=p1p1.100,192.168.0.47 subnet=p1p2.200,192.168.1.47

Please be patient while the initiator configuration is being created.

> iscsiadm show initiator=init-with-vlans status

Please be patient while run-time information is being collected.

Output:

{

"initiator": [

{

"interfaces": [

"p1p1",

"p1p2"

],

"iproto": [

"tcp"

],

"iqn": "iqn.1994-05.com.redhat:ec9dbf9d80bb",

"mtu": "9000",

"name": "init-with-vlans",

"netmask": "255.255.255.0",

"storage_network": {

"priority_map": "",

"storage_network_type": "dedicated_net",

"vlan_id": ""

},

"subnet_count": 2,

"subnets": [

{

"interface": {

"link_state": "UP",

"name": "p1p1.100:iscsia",

"speed": "25GbE"

},

"network": {

"ip_address": "192.168.0.47",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

},

...

> iscsiadm show initiator status

Output:

{

"interface": {

"link_state": "UP",

"name": "p1p2.200:iscsib",

"speed": "25GbE"

},

"network": {

"ip_address": "192.168.1.47",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

}

]

}

]

}

The output above displays iscsia subnet with p1p1 interface is on vlan 100 and iscsib subnet with p1p2 interface is on vlan 200.

Note: For setting up an iSCSI network using VLANs, the entire communication path between the initiator and its targets must be setup for those VLANs. That means aside from the initiator, the switches in between the initiator and its targets must be setup for the iSCSI subnet VLANs traffic, and the targets interfaces must also be setup to use those same VLANs. So, when trying to add targets to an initiator using VLAN for its subnets, the provided IP addresses of the target must be accessible through the VLAN of the initiator subnet with the matching subnet IP address, and the target IP addresses be equally distributed among the initiator subnets..

Example: Create an Initiator with L2 Converged Network Setting

Do the following to create an initiator with two subnets, where each subnet is configured with the requested common VLAN , specified with vlan_id=100 call argument, on its interfaces and sets the priority map of frames going out of these subnet interfaces with the given priority of 6. The combination of presence of VLAN and priority map indicates the desire for, and would automatically set the interface network type to, L2 converged networking, without explicitly providing the storage_network=converged_net_l2 call argument:

> `iscsiadm create initiator=init-l2converged subnet=p1p1,192.168.0.47 subnet=p1p2,192.168.1.47 vlan_id=200 priority_map=0:6`

> iscsiadm show initiator=init-l2converged status

Output:

{

"initiator": [

{

"interfaces": [

"p1p1",

"p1p2"

],

"iproto": [

"tcp"

],

"iqn": "iqn.1994-05.com.redhat:ec9dbf9d80bb",

"mtu": "9000",

"name": "init-l2converged",

"netmask": "255.255.255.0",

"storage_network": {

"priority_map": "0:6",

"storage_network_type": "converged_net_l2",

"vlan_id": "200"

},

"subnet_count": 2,

"subnets": [

{

"interface": {

"link_state": "UP",

"name": "p1p1.200:iscsia",

"priority_map": "0:6",

"speed": "25GbE"

},

"network": {

"ip_address": "192.168.0.47",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

},

{

"interface": {

"link_state": "UP",

"name": "p1p2.200:iscsib",

"priority_map": "0:6",

"speed": "25GbE"

},

"network": {

"ip_address": "192.168.1.47",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

}

]

}

]

}

The output above displays the storage_network section with details of the L2 Converged Network setup for this initiator.

Important Information About Setting Up Iscsi Networks With L2 Converged Networking

Currently the L2 converged networking setup has been tested and only works with:

- Xcellis hardware (not on Xcellis VMs).

- Supported Mellanox CX-4/5 cards of Xcellis.

- Mellanox switches.

The Platform iSCSI communicates via DCBX with the switch for turning on Priority Flow Control (PFC), and setting the requested priority level 6 to on.

The L2 Converged Networking support for initiators was a post release addition to Platform iSCSI version 2 in support of F2000 targets and may be used for any similar target and is supported with Platform iSCSI version 3.

Note: There is a default setup priority map of 0:5 for when the create initiator command is called with storage_net=converged_net_l2 call argument without the priority_map call argument. This default form of creating L2 Converged Network for the initiator, plus the default use of VLAN 100 (this is no longer available in iSCSI version 3, i.e. the VLAN ID must be provided) was used for simplicity of setting up the network for F2000 targets and may only be used once. Therefore, if you prefer to use the same priority mapping for another initiator, the force call argument along with other unused VLAN IDs, using vlan_id call argument or VLANs specified per subnet interface settings, must be used.

Example: Use web services to create an iSCSI initiator

The following command to remote host 10.40.160.43, using appliance controller port (33777) to make a call to version v2 of the iscsiadm plugin to create an initiator named plat-iser for iSER communication with its targets, configured for an (implied) L2 converged storage networking environment using VLANs 100 and 200 and priority map of 0:6, with 4 subnets on 2 interfaces p1p1 and p1p2 is shown below.

> `curl --insecure -X PUT 'https://10.40.160.43:33777/api/v2/iscsiadm/initiator' -d '{ "initiator":"plat-iser", "subnets":["p1p1.100,192.168.1.43”,"p1p2.100,192.168.2.43", “p1p1.200, 192.168.3.43”, “p1p2.200,192.168.4.43”],”iproto:[“iser”], “priority_map”:”0:6” , "netmask":"255.255.255.0", "mtu":"jumbo"}'`

Note: The v2 after the api in the URL path is required to access Platform iSCSI version 3 webservices API. Previous 2 releases of iSCSI plugin used only version 1 for the webservice API of iSCSI plugin and took advantage of the default absence of v1 after api in the URL translating to webservices version 1.

Example: Create an Initiator with iSER Support

There are two types of iSCSI communication protocols supported between initiators and their targets. The classic iSCSI (SCSI over TCP), and iSER (iSCSI over Extended RDMA supported by Mellanox on Mellanox cards).

The most important condition for creating an initiator with iSER communication support is to use an interface of a NIC card that supports iSER. Currently, the following NIC cards support iSER:

- 13G Systems:

  - ConnectX-4 Lx 25G Ethernet card.

- 14G Systems:

  - ConnectX-4 Lx 25G Ethernet card.

  - ConnectX-4 100G Ethernet card or its replacement:

  - ConnectX-5 Ex 100G Ethernet card

Using these card interfaces, initiators created with iSER communication support will be able to accept targets with iSER support, and communicate with them using iSER, iSCSI over Extended RDMA.

Caution: Creating an initiator with iSER communication support option using interfaces of a NIC card that does not support iSER communication does not generate errors during its creation, but an iSER target added to this initiator fails to establish login sessions with a connection failure.

iscsiadm create initiator=<initiator name> (1 to 4) subnet=<interface,ipaddress> [netmask-<netmask value>] [mtu=<mtu value>] [iface=iser]

Where the optional iproto=iser call argument is used.

Example

Below, the p2p2 port is from a ConnectX-4 Lx card that is installed in slot 2 of a test system. This example also demonstrates the use of a single subnet initiator.

> iscsiadm create initiator=private subnet=p2p2,10.50.10.47 iproto=iser

The command creates the initiator with iSER support with the given private name, the given subnet_a and subnet_b networks being setup using p3p1 and p3p2 interfaces supporting iSER communication, and with the given IP addresses (with the default 255.255.255.0 netmask, and mtu 9000).

Verify the creation of the initiator with:

> iscsiadm show initiator=private status

Output:

    {
      "initiator": [
        {
          "interfaces": [
            "p2p2"
          ],
          "iproto": [
            "tcp",
            "iser"
          ],
          "iqn": "iqn.1994-05.com.redhat:b946aaf1c951",
          "mtu": "9000",
          "name": "private",
          "netmask": "255.255.255.0",
          "storage_network": {
            "priority_map": "",
            "storage_network_type": "dedicated_net",
            "vlan_id": ""
          },
          "subnet_count": 1,
          "subnets": [
            {
              "interface": {
                "link_state": "UP",
                "name": "p2p2:iscsia",
                "speed": "100GbE"
              },
              "network": {
                "ip_address": "10.50.10.47",
                "ip_state": "UP",
                "runtime_mtu": "9000",
                "runtime_speed": "100GbE"
              }
            }
          ]
        }
      ]
    }

Note: The iproto information for this initiator shows both tcp and iser, meaning the initiator accepts both classic iSCSI and iSER targets.

Example: Use web services to create a platform initiator with iSER communication

> curl --insecure -X PUT 'https://localhost:33777/api/v2/iscsiadm/initiator' -d '{"name":"private", "subnet":"p2p1,10.50.10.47", , "iproto":"iser"}'

Delete an iSCSI Initiator

Use the `iscsiadm delete initiator` command to delete multiple initiators at once, by providing their names in a comma-separated string as initiator call argument value. This command refuses to execute and delete any of the requested initiators if any of them have targets added to them. Use the optional force call argument to override that behavior; the command deletes all the requested initiators and removes all of their respective targets.

1. Log in to the Appliance Controller CLI.
2. Enter:

`iscsiadm delete initiator=[<name>[,<name>]*] [force]`

Parameters:

`<name>` | The initiator name. For deleting multiple initiators, add their names in a comma-separated string. For example, init1,init2.
`[force]` | Forces the deletion of the initiator, by terminating their targets sessions and removing them first before deleting the initiator itself.

Example:

To not delete an initiator that might have a target, enter:

> iscsiadm delete initiator=xcellishost

Validation failure: Cannot perform operation without force: some initiators have targets (E-2002)

To intentionally delete an iSCSI initiator with its targets, enter:

> iscsiadm delete initiator=xcellishost force

Enter the following to verify the status of the iSCSI configuration:

> iscsiadm show initiator=xcellishost status

Output:

The output shows the initiator list is empty of xcellishost initiator after its removal:

Please be patient while status information is being collected.

{

"initiator": []

}

Example: Use web services to delete an an iSCSI initiator

The following commands show deletion of the platform initiator in its two forms:

> `curl --insecure -X DELETE 'https://localhost:33777/api/v2/iscsiadm/initiator?name=platform'`

> `curl --insecure -X DELETE 'https://localhost:33777/api/v2/iscsiadm/initiator?name=platform&force=True'`

Create TCP or iSER iSCSI Targets

Each iSCSI target is added by providing a name for it and a comma-separated list of that target IP addresses. The iSCSI controller attempts to find an initiator among the already created initiators where the target IP addresses match that initiator subnets, and those target IP addresses equally distribute among the initiator subnets. Additionally, the iSCSI target communication protocol must match the communication protocol of the candidate initiator. Hence, the iproto=iser call argument is mandatory for adding iSER targets. If matching initiator is not found for the target, then an error is returned indicating the issue with that target addition.

After a matching initiator is found for the target, the target structure is created and added to the list of targets of that initiator and if the target IP addresses are accessible, the target sessions are logged into. If target IP addresses are not accessible by the initiator, then an operational error is returned, indicating an external network accessibility issue with the target that needs to be resolved externally. After the issues are resolved, you can use the iscsiadm session login command to log in to the target sessions.

1. Log in to the Appliance Controller CLI.
2. Enter:

`iscsiadm add target=<target name> ipaddrs=<target-IP-1>,<target-IP-2>[,<target-IP-3>,<target-IP-4>] [iproto=[tcp|iser]]`

Note: The optional iproto default value is tcp, which for tcp connections, this can be omitted. However, iproto=iser is required for adding targets using iSER communication protocol.

Parameters:

`<target name>` | The target name.
`<target-IP-1>` | The first IP address used for the target, For additional target IP addresses, add them after the first IP address.

Example: Creating an iSER target

For the examples below, in the absence of a physical array with iSCSI iSER support, a host-based iSCSI target was used. The host was installed with Linux SCSI target software (scsi-target-utils-1.0.55-4.el7.x86_64) that supports creating host-based SCSI targets. The following command, an in-memory LUN, and its iSCSI iSER target was created:

> `tgt-setup-lun -n tgt-iser -d /tmp/null -b null -t iser`

Note: This host-based iSCSI target with iSER support, will be accessible only through IP addresses 10.10.0.173 and 10.10.1.173 respectively of p3p1 and p3p2 ports of the host. These are the ports of a ConnectX-4 Lx 25G card, installed in slot 3 of this host, that does support iSER.

Run the following command to view the details of the created target with iSER support:

> `tgt-admin -s`

Output

Note: The target’s IQN appears on the initiator, once the initiator adds this target.

The following adds the target with name iser-target and IP addresses 10.10.0.171 and 10.10.1.171 and iSER interface support to the private initiator which has the matching subnets for this target.

> `iscsiadm add target=iser-target ipaddrs=10.10.0.171,10.10.1.171 iproto=iser`

Verify status of iSCSI configuration, including the new target. Enter:

> `iscsiadm show status`

Output

The provided output includes the status of each of the initiator interfaces and each of the target’s ports.

The output displays the iser-target with IQN value of iqn.2001-04.com.bhm2-2s-tgt-iser was added to the private initiator. All iSCSI communication between the two are carried over RDMA.

Example: Creating a TCP iSCSI target

To add an iSCSI target, enter:

> `iscsiadm add target=qxs-array-1 ipaddrs=192.168.0.223,192.168.1.223`

Note: Since this target uses TCP, you do not need to provide the iproto=tcp call argument, as the default is tcp.

Verify status of iSCSI configuration, including the new target. Enter:

> `iscsiadm show status`

Output

The provided output includes the status of each of the initiator interfaces and each of the target’s ports:

Example: Use web services to add an iSER target

The following command adds an iser-target target to the private initiator:

> curl --insecure -X PUT 'https://localhost:33777/api/v2/iscsiadm/target' -d ' {"name":"iser-target", "ipaddrs":"10.10.0.173,10.10.1.173", "iproto":"iser"}'

Example: Add a Target with 4 Subnets to an Initiator with 4 Subnets

The example below adds a target with the given name and the eight IP addresses, four subnets to the Platform iSCSI. This target is added to a platform initiator that has two interfaces and four subnets, as the two IP addresses of the target on each subnet matches one of the four subnets of the platform initiator. Since the communication interface for the target is not provided, it has the default tcp value which also matches that of the platform initiator.

To add an iSCSI target with 4 Subnets to an initiator with 4 Subnets, enter:

> `iscsiadm add target=tgt-4subs ipaddrs=192.168.0.10,192.168.1.10,192.168.2.10,192.168.3.10,192.168.0.20,192.168.1.20,192.168.2.20,192.168.3.20`

Verify status of iSCSI configuration, including the new target. Enter:

> `iscsiadm show status`

Please be patient while run-time information is being collected.

{

"initiator": [

{

"interfaces": [

"p1p2",

"p2p2"

],

"iproto": [

"tcp"

],

"iqn": "iqn.1994-05.com.redhat:1731b7db400",

"mtu": "9000",

"name": "platform",

"netmask": "255.255.255.0",

"storage_network": {

"priority_map": "",

"storage_network_type": "dedicated_net",

"vlan_id": ""

},

"subnet_count": 4,

"subnets": [

{

"interface": {

"link_state": "UP",

"name": "p1p2:iscsia",

"speed": "10GbE"

},

Iscsiadm show status

…

"network": {

"ip_address": "192.168.0.173",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

},

{

"interface": {

"link_state": "UP",

"name": "p1p2:iscsib",

"speed": "10GbE"

},

"network": {

"ip_address": "192.168.1.173",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

},

{

"interface": {

"link_state": "UP",

"name": "p2p2:iscsic",

"speed": "56GbE"

},

"network": {

"ip_address": "192.168.2.173",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

},

{

"interface": {

"link_state": "UP",

"name": "p2p2:iscsid",

"speed": "56GbE"

},

….

….

"network": {

"ip_address": "192.168.3.173",

"ip_state": "UP",

"runtime_mtu": "9000",

"runtime_speed": "10GbE"

}

}

],

"targets": [

{

"ip_addresses": [

"192.168.0.10",

"192.168.1.10",

"192.168.2.10",

"192.168.3.10",

"192.168.0.20",

"192.168.1.20",

"192.168.2.20",

"192.168.3.20"

],

"iproto": "tcp",

"iqn": "iqn.1995-03.com.dothill:01.array.00c0ff28d9c7",

"name": "tgt-4subs",

"subnet_count": 4,

"subnets": [

{

"initiator_interface": "p1p2:iscsia",

"initiator_ipaddress": "192.168.0.173",

"portal_count": 2,

"portals": [

{

"ip_address": "192.168.0.10",

"ip_state": "Accessible",

"session_state": "logged in"

},

{

"ip_address": "192.168.0.20",

"ip_state": "Accessible",

"session_state": "logged in"

}

]

},

….

….

{

"initiator_interface": "p1p2:iscsib",

"initiator_ipaddress": "192.168.1.173",

"portal_count": 2,

"portals": [

{

"ip_address": "192.168.1.10",

"ip_state": "Accessible",

"session_state": "logged in"

},

{

"ip_address": "192.168.1.20",

"ip_state": "Accessible",

"session_state": "logged in"

}

]

},

{

"initiator_interface": "p2p2:iscsic",

"initiator_ipaddress": "192.168.2.173",

"portal_count": 2,

"portals": [

{

"ip_address": "192.168.2.10",

"ip_state": "Accessible",

"session_state": "logged in"

},

{

"ip_address": "192.168.2.20",

"ip_state": "Accessible",

"session_state": "logged in"

}

]

},

….

….

{

"initiator_interface": "p2p2:iscsid",

"initiator_ipaddress": "192.168.3.173",

"portal_count": 2,

"portals": [

{

"ip_address": "192.168.3.10",

"ip_state": "Accessible",

"session_state": "logged in"

},

{

"ip_address": "192.168.3.20",

"ip_state": "Accessible",

"session_state": "logged in"

}

]

}

]

}

]

}

]

}

A detailed explanation of the above configuration is given below.

Initiator | The server where the initiator runs is the older generation 13G Xcellis platform.
Interfaces | The platform initiator has 2 interfaces: p1p2 is second port of a 10G NIC in slot 1 of the 13G XCellis which is an Intel 10G X520 card with runtime_speed of 10G. p2p2 is second port of a 56G NIC in slot 2 of the 13G Xcellis which is a Mellanox 56G ConnectX-3 card with runtime_speed of 10G. Note: The run-time operating speed of all ports are 10G. For a balanced iSCSI service by the initiator, it is important to make sure the operating speed of all initiator interfaces are set to the same (lowest denominator) speed.
subnets | 192.168.0.0 subnet via p1p2:iscia 192.168.1.0 subnet via p1p2:iscsib 192.168.2.0 subnet via p2p2:iscsic 192.168.3.0 subnet via p2p2:iscsid
Target | The target is a QXS array with 8 iSCSI interfaces, each two with IP addresses on different subnet.
IP Addresses | 192.168.0.0 subnet IP addresses: 192.168.0.10 192.168.0.20 192.168.1.0 subnet IP addresses: 192.168.1.10 192.168.1.20 192.168.2.0 subnet IP addresses: 192.168.2.10 192.168.2.20 192.168.3.0 subnet IP addresses: 192.168.3.10 192.168.3.20
Subnets | The subnets section of the target includes the interface and IP address of the initiator subnet and portal_count is number of target portals that subnet is connected to.
Portals | Each portal includes the ip_address of that portal, ip_state showing whether that address is accessible, and the session_state showing whether a session is logged into via that portal.

Example: Use web services to add a target with 4 subnets to an initiator with 4 subnets

> `curl -sk -X PUT -H Accept:application/json -H Content-Type:application/json https://10.40.163.173:33777/api/v2/iscsiadm/target --data '{"name":"tgt-4subs", "ipaddrs":"192.168.0.10,192.168.1.10,192.168.2.10,192.168.3.10,192.168.0.20,192.168.1.20,192.168.2.20,192.168.3.20","iproto":"tcp" }'`

Delete iSCSI Targets

1. Log in to the Appliance Controller CLI.
2. At the prompt, enter:

`iscsiadm remove target=[<name>[,<name>]*] | target initiator=<name>[,<name>]*]`

Differences between `iscsiadm remove target` and `iscsiadm remove target initiator`:

- target= is followed by a comma-separated list of names of targets to be removed. In this case targets may belong to any number of the registered initiators
- target initiator= is followed by a comma-separated list of names of initiators whose targets are to be removed. In this case all targets of each of the named initiators will be removed.

Parameter:

`<name>` | The target or initiator name.

Example: two different ways to remove the same target from a single initiator

Remove qxs-array-1 target from the xcellishost initiator:

Method 1:

`iscsiadm remove target=qxs-array-1`

This command would remove the qxs-array-1 target explicitly.

Method 2:

`iscsiadm remove target initiator=xcellishost`

This command would remove all targets of the xcellishost initiator, implicitly removing the qxs-array-1 target.

Example: verify configuration changes

For both methods, verify the configuration was changed. Enter:

`iscsiadm show status`

Output:

Note: The targets list for the xcellishost initiator is now empty.

Example: Use web services to delete iSCSI targets

The following command removes the qxs-array-1 target:

> `curl --insecure -X DELETE 'https://localhost:33777/api/v2/iscsiadm/target?target=qxs-array-1'`

The following command deletes targets of the initiator named platform:

> `curl --insecure -X DELETE 'https://localhost:33777/api/v2/iscsiadm/target?initiator=platform'`

iSCSI Network

Use the `iscsiadm network` command to stop, start, or restart an initiator network.

1. Log in to the Appliance Controller CLI.
2. At the prompt, enter:

`iscsiadm network [initiator=<name>[,<name>]]* [start|stop|restart] | initiator=<name> set mtu=<value>]`

The parameters are:

`<initiator=<name>` | The name of the initiator. For managing multiple initiators network, add a comma-separated list of initiator names . For managing all initiators network, do not provide this call argument.
`<start>` | Start iSCSI network services.
`<stop>` | Stop iSCSI network services.
`<restart>` | Restart iSCSI network services.
`<set mtu=<value>` | Set the named initiator’s MTU to the given value. Note: This command works for a single initiator whose name is provided using initiator=<name>. Note: This command sets the MTU value in the initiator configuration without affecting the run-time MTU used by its subnet interfaces. The new value only becomes effective for the run-time after a network restart that includes the initiator, or after a reboot.

Example:

The following command stops the private initiator subnet and network:

> `iscsiadm network initiator=private stop`

Example: Use web services to log out of a target session

The following command stops the private initiator subnet and network:

> `curl --insecure -X PUT 'https://localhost:33777/api/v2/iscsiadm/network/service' -d '{"initiator":"private", "action":"stop"}''`

Change the MTU Size Used by an Initiator

The following command sets the MTU size for the private initiator to 1500:

> `iscsiadm network initiator=private set mtu=1500`

The new MTU value is set in the initiator’s configuration record. It does not affect the run-time MTU of the initiator subnets, as bold-faced in the following example.

    > iscsiadm show initiator=private status
    Please be patient while run-time information is being collected.
    {
      "initiator": [
        {
          "interfaces": [
            "p2p2"
          ],
          "iproto": [
            "tcp",
            "iser"
          ],
          "iqn": "iqn.1994-05.com.redhat:b946aaf1c951",
          "mtu": "1500",
          "name": "private",
          "netmask": "255.255.255.0",
          "storage_network": {
            "priority_map": "",
            "storage_network_type": "dedicated_net",
            "vlan_id": ""
          },
          "subnet_count": 1,
          "subnets": [
            {
              "interface": {
                "link_state": "UP",
                "name": "p2p2:iscsia",
                "speed": "100GbE"
              },
              "network": {
                "ip_address": "10.50.10.47",
                "ip_state": "UP",
                "runtime_mtu": "9000",
                "runtime_speed": "100GbE"
              }
            }
          ]
        }
      ]
    }

It only become effective on the initiator subnet interfaces after a subsequent network restart for the initiator.

> iscsiadm network initiator=private restart

    > iscsiadm show initiator=private status
    Please be patient while run-time information is being collected.
    {
      "initiator": [
        {
          "interfaces": [
            "p2p2"
          ],
          "iproto": [
            "tcp",
            "iser"
          ],
          "iqn": "iqn.1994-05.com.redhat:b946aaf1c951",
          "mtu": "1500",
          "name": "private",
          "netmask": "255.255.255.0",
          "storage_network": {
            "priority_map": "",
            "storage_network_type": "dedicated_net",
            "vlan_id": ""
          },
          "subnet_count": 1,
          "subnets": [
            {
              "interface": {
                "link_state": "UP",
                "name": "p2p2:iscsia",
                "speed": "100GbE"
              },
              "network": {
                "ip_address": "10.50.10.47",
                "ip_state": "UP",
                "runtime_mtu": "1500",
                "runtime_speed": "100GbE"
              }
            }
          ]
        }
      ]
    }

iSCSI Session

Use the `iscsiadm session` command to log in, or log out (individually or in a group) of a target session.

1. Log in to the Appliance Controller CLI.
2. At the prompt, enter:

`iscsiadm session [target=<name>[,<name>]*] | [target] initiator=<name>[,<name>]*]] login|logout`

The parameters are:

`target=<name> | initiator=<name>` | Provide the name of the target or initiator. For managing multiple targets, add a comma-separated list of target names to target=. For managing targets of multiple initiators, add a comma-separated list of initiator names to initiator= call argument. Note: The target= and initiator= call arguments are mutually exclusive and may not be used at the same time.
`login` | Log in to the iSCSI session.
`logout` | Log out of the iSCSI session.

Example: `target logout`

The following command logs out of the target iser-target iSCSI sessions:

> `iscsiadm session target=iser-target logout`

The following command logs out of all targets of initiators platform and private iSCSI sessions:

> iscsiadm session initiator=platform,private logout

Example: Use web services to log out of a target session

The following command logs out of the iser-target target sessions:

> `curl --insecure -X PUT 'https://localhost:33777/api/v2/iscsiadm/session' -d '{"target":"iser-target", "action":"logout"}'`
iSCSI Session Timeout

Use the `iscsiadm session-timeout` command to set the timeout value, in seconds, for a session to wait to be re-established before an issued iSCSI command will be considered to have failed.

1. Log in to the Appliance Controller CLI.
2. At the prompt, enter:

`iscsiadm session-timeout <seconds>`

The parameter is:

`<seconds>` | The default value of this iSCSI parameter is set to 5 seconds. It is not recommended to lower this value. However, the value may be adjusted higher to match the slowest target access for successful completion of its SCSI commands.

Example: Set the iscsiadm session timeout

The following command will set the session's timeout value to 10 seconds:

> `iscsiadm session-timeout 10`

Example: Use web services to set the iscsiadm session timeout

The following command will set the session's timeout value to 10 seconds:

> `curl --insecure -X PUT 'https://localhost:33777/api/v2/iscsiadm/session/timeout' -d '{"timeout":10}'`
Show iSCSI Configurations

Use the `iscsiadm show` command to view the state of any and all initiators and targets and look for potential issues in the iSCSI communication between the initiators and their targets.

1. Log in to the Appliance Controller CLI.
2. At the prompt, enter:

`iscsiadm show [[initiator[=<iname>[,<iname>]*]]*] [with_target]] | [target[=<tname>[,<tname>]*]]*] [with_initiator]]] [status] | session-timeout`

The parameters are:

`initiator[=<iname>[,<iname>]*]` | A comma-separated list of initiator names. Note: You can specify the initiator call argument more than once.
`target[=<tname>[,<tname>]*]` | A comma-separated list of target names. Note: You can specify the target call argument more than once.
`session-timeout` | Show the current global iSCSI session timeout value in seconds. Note: You can only use one of initiator, target, or session_timout call arguments.
`with_target` | When used in combination with the initiator call argument, show the targets of initiators information.
`with_initiator` | When used in combination with the target call argument, show the initiators of targets information as well.
`status` | Show the run-time status of requested initiators or targets information as well.

Examples of `iscsiadm show` command usage

In its simplest form, the command shows the configuration information for all initiators and their targets (not including status information):

> iscsiadm show

When additionally, the status call argument is used, the command shows the configuration and run-time information for all initiators and their targets.

> iscsiadm show status

When additionally, the initiator call argument is used, the command shows the configuration and run-time information for all initiators (not including targets)

> iscsiadm show initiator status

When additionally, the name of an initiator is provided with the initiator call argument, the command shows the configuration and run-time information for the named initiator (not including targets)

> iscsiadm show initiator=platform status

When additionally, the with_target call argument is used, the command shows the configuration and run-time information for the named initiator and its targets.

> iscsiadm show initiator=platform status with_target

Similarly, the following show target commands show incrementally more information about the target(s)

> iscsiadm show target
> iscsiadm show target status
> iscsiadm show target=QXS1 status
> iscsiadm show target=QXS1 status with_initiator

Example `iscsiadm show status` command Output:

    > iscsiadm show status
    Please be patient while run-time information is being collected.
    {
      "initiator": [
        {
          "interfaces": [
            "p2p1"
          ],
          "iproto": [
            "tcp"
          ],
          "iqn": "iqn.1994-05.com.redhat:b946aaf1c951",
          "mtu": "9000",
          "name": "platform",
          "netmask": "255.255.255.0",
          "storage_network": {
            "priority_map": "",
            "storage_network_type": "dedicated_net",
            "vlan_id": ""
          },
          "subnet_count": 2,
          "subnets": [
            {
              "interface": {
                "link_state": "UP",
                "name": "p2p1:iscsia",
                "speed": "100GbE"
              },
              "network": {
                "ip_address": "192.168.0.47",
                "ip_state": "UP",
                "runtime_mtu": "9000",
                "runtime_speed": "100GbE"
              }
            },
            {
              "interface": {
                "link_state": "UP",
                "name": "p2p1:iscsib",
                "speed": "100GbE"
              },
              "network": {
                "ip_address": "192.168.1.47",
                "ip_state": "UP",
                "runtime_mtu": "9000",
                "runtime_speed": "100GbE"
              }
            }
          ],

     ...
          "targets": [
            {
              "ip_addresses": [
                "192.168.0.10",
                "192.168.0.20",
                "192.168.1.10",
                "192.168.1.20"
              ],
              "iproto": "tcp",
              "iqn": "iqn.1995-03.com.dothill:01.array.00c0ff28d9c7",
              "name": "QXS4",
              "subnet_count": 2,
              "subnets": [
                {
                  "initiator_interface": "p2p1:iscsia",
                  "initiator_ipaddress": "192.168.0.47",
                  "portal_count": 2,
                  "portals": [
                    {
                      "ip_address": "192.168.0.10",
                      "ip_state": "Accessible",
                      "session_state": "logged in"
                    },
                    {
                      "ip_address": "192.168.0.20",
                      "ip_state": "Accessible",
                      "session_state": "logged in"
                    }
                  ]
                },
                {
                  "initiator_interface": "p2p1:iscsib",
                  "initiator_ipaddress": "192.168.1.47",
                  "portal_count": 2,
                  "portals": [
                    {
                      "ip_address": "192.168.1.10",
                      "ip_state": "Accessible",
                      "session_state": "logged in"
                    },
                    {
                      "ip_address": "192.168.1.20",
                      "ip_state": "Accessible",
                      "session_state": "logged in"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }

Detailed Information on the Output of `iscsiadm show status` Command

The output includes a list of iSCSI initiators and their targets static and run-time configuration.

The new information in this output with respect to iSCSI version 2 are shown in the categorized tables below.

This example demonstrates some of the new capabilities of iSCSI version 3. The initiator uses 2 subnets on the single interface it uses. Where the target has four IP addresses divided into 2 portals each served by each of the two initiator subnets.

Table 1: Initiator Level Fields
Field | Value(s) | Description
--- | --- | ---
interfaces | p2p1 | List of interfaces used by the initiator.
iproto | tcp | List of communication protocols used by the initiator.
storage_network | See Table 2. | Dictionary of Storage networking setup parameters.
subnet_count | 2 | The number of subnets of this initiator.
subnets | See Table 3. | List of dictionaries of initiator subnets interfaces and networks.
targets | See Table 6. | List of dictionaries of initiator targets.

Table 2: Initiator Storage Network Level Fields
Field | Value(s) | Description
--- | --- | ---
priority_map | None | VLAN priority map used by initiator subnet interfaces.
storage_network_type | dedicated_net | The initiator’s storage networking type configuration: dedicated_net converged_net_l2
vlan_id | None | The single VLAN ID used on all the initiator subnet interfaces (if present).

Table 3: Initiator Subnet Level Fields
Field | Value(s) | Description
--- | --- | ---
interface | See Table 4. | Dictionary of subnet interface information.
network | See Table 5. | Dictionary of subnet network information.

Table 4: Initiator Subnet Interface Level Fields
Field | Value(s) | Description
--- | --- | ---
link_state | UP | The state of this network interface physical link.
name | p2p1:iscsia p2p1:iscsib | The alias name of the subnet interface. The name will include the VLAN ID if present, for example, p2p1.100:iscsia.
speed | 100G | The maximum throughput speed of the NIC port of this interface.

Table 5: Initiator Subnet Network Level Fields
Field | Value(s) | Description
--- | --- | ---
ip_address | 192.168.0.47 192.168.1.47 | The IP address of the interface.
ip_state | UP | The IP network configuration state of the interface (ifconfig).
runtime_mtu | 9000 | The maximum transfer unit size (bytes) used by the interface.
runtime_speed | 100G | The maximum available run-time throughput speed of this interface.

Table 6: Initiator Target Level Fields
Field | Value(s) | Description
--- | --- | ---
ip_addresses | 192.168.0.10 192.168.0.20 192.168.1.10 192.168.1.20 | The IP addresses of the target interfaces.
subnet_count | 2 | The number of initiator subnets this target is connected to.
subnets | See Table 7. | List of dictionaries of target-used subnet information.

Table 7: Initiator Target Subnet Level Fields
Field | Value(s) | Description
--- | --- | ---
initiator_interface | P2p1:iscsia P2p1:iscsib | The initiator interface serving this target subnet. The virtual interface name uniquely identifies the subnet.
initiator_ipaddress | 192.168.0.47 192.168.1.47 | The initiator interface IP address serving this target subnet.
portal_count | 2 | The number of target portals through this subnet.
portals | See Table 8. | List of dictionaries of portals.

Table 8: Initiator Target Subnet Portal Level Fields
Field | Value(s) | Description
--- | --- | ---
ip_address | 192.168.0.10 (using iscsia subnet) 192.168.0.20 (using iscsia subnet) 192.168.1.10 (using iscsib subnet) 192.168.1.20 (using iscsib subnet) | The IP address of the target portal served in this subnet.
ip_state | Accessible | The status of reaching this portal target IP address (using ping).
session_state | logged in | The state of this portal target session.

Automatic Platform iSCSI Version 1 and Version 2 Upgrade to Version 3

For systems running Appliance Controller 3.1.0 and later, Platform iSCSI version 1 and version 2 included in StorNext 7.0.1.1 (or earlier) are automatically upgraded to Platform iSCSI version 3 configuration format upon first reference to them from within the Appliance Controller with Platform iSCSI version 3. Quantum highly recommends that you do the following procedure immediately after your node is upgraded to Appliance Controller 3.1.0 and later; specifically, on a node with iSCSI access to its shared file system.

1. Log in to the Appliance Controller CLI.
2. At the prompt, enter either of the following commands to examine the old configurations in their new format:

`iscsiadm show`

Or:

`iscsiadm show status`

## iSCSI Tasks and Commands for Appliance Controller 3.0.x and earlier

Prerequisites

You can use the following commands with Appliance Controller 3.1.0 (or later) when StorNext 7.0.1 (or earlier) are installed.

Create a TCP or iSER iSCSI Initiator

Note: A separate subnet is required for each initiator interface.

1. Log in to the Appliance Controller CLI.
2. Enter:

`iscsiadm create initiator=<initiator name> subnet_a=<interface-a,ipaddress-a> subnet_b=<interface-b,ipaddress-b> [netmask-<netmask value>] [mtu=<mtu value>][iface=<interface type>] [vlan_id=<vlan_id>][storage_network=[dedicated_net|converged_net_l2 [priority_map=<priority map>]]]`

Parameters:

`initiator name` | The initiator name.
`subnet_a` | This will contain the interface and IP information for the first subnet in the configuration
`interface-a` | This is the logical name for the interface used for `subnet_a`.
`ipaddress-a` | This is the IP address of the interface used for `subnet_a`.
`subnet_b` | This will contain the interface and IP information for the second subnet in the configuration
`interface-b` | This is the logical name for the interface used for `subnet_b`.
`ipaddress-b` | This is the IP address of the interface used for `subnet_b`.
`<netmask value>` | The netmask value.
`<mtu value>` | The value of the supported mtu (maximum transfer unit) within the network. Valid values include the following (must enter `jumbo`, `standard`, or a number between 1500–9000 bytes): `jumbo`: jumbo frame support; mtu=9000 bytes `standard`: mtu=1500 bytes Note: The default value is `jumbo`
`<interface type>` (default value is `tcp`) | A value for `iproto=` should be specified. The supported iSCSI communication interfaces are tcp (SCSI over TCP, also known as iSCSI), and iser (iSCSI over Extended RDMA). Enter a value of tcp or iser, depending on how the interface will be configued.
`<vlan_id>` | Configure target node interfaces with the selected `vlan_id`, if supported. Otherwise, the target interfaces can be specified without the use of this parameter.
`<priority map>` | The VLAN egress priority map is entered with up to 8 comma separated x:y values, where: X: A socket priority queue group, between 0 and 7 inclusive; X values may not be repeated. Y: A traffic class number, between 0 and 7 inclusive; Y values may be repeated to tag multiple socket priority groups to the same traffic class.
* Note: In the `iscsiadm create initiator` command, for storage network, while this isn't an editable parameter, you still need to enter specifically either `dedicated_net` for initiator configuration for use in a dedicated network environment, or `converged_net_12`, for initiator configuration within a trust L2 converged network environment, with default `vlan_id=100`, and `priority_map=0:5`. The default storage network setting is `dedicated_net`.

Example: Create a TCP initiator

> `iscsiadm create initiator=xcellishost subnet_a=p1p1,192.168.0.171 subnet_b=192.168.1.171 netmask=255.255.255.0 mtu=jumbo`

Output:

Please be patient while the initiator configuration is being created.

The example above creates an initiator named "xcellishost", using interfaces p1p1 and p1p2, with IP addresses 192.168.0.171 and 192.168.1.171 (in that order), a netmask of 255.255.255.0, and a Maximum Transfer Unit (MTU) assigned as Jumbo (9000 bytes), and brings up those interfaces. If there are no configuration or network availability errors, the interfaces are brought up with the IP addresses that were just assigned.

Possible Errors

The following error messages are displayed when any of these conditions is encountered when configuring iSCSI:

- `Given initiator name is already used`
- `Given Interface name does not exist, or is assigned to another application`
- `Given IP address is not well-formed, or is already taken`
- `Given netmask is not well-formed`
- `Given MTU is not acceptable (value is not between 1500 and 9000)`

Next Steps: after creation an iSCSI initiator

1. Ensure that the interfaces are linked up to the network . Enter:

> `iscsiadm show initiator=platform status`

Results should look similar to this.

Output:

2. Fix cabling or any other networking issues before adding targets to the initiator.

Delete an iSCSI Initiator

1. Log in to the Appliance Controller CLI.
2. Enter:

`iscsiadm delete initiator=[<name>[,<name>]*] [force]`

Parameters:

`<name>` | The initiator name. For deleting multiple initiators, add their names in a comma-separated string. For example, init1,init2.
`[force]` | Forces the deletion of the initiator.

Example:

To delete an iSCSI initiator, enter:

> `iscsiadm delete initiator=xcellishost`

Verify the status of the iSCSI configuration. Enter:

> `iscsiadm show status`

Output:

If `xcellishost` was the only initator in the system and was deleted, the output should show the following, where no initiators are shown (as indicated by the empty value in parentheses):

Please be patient while status information is being collected.

{

"initiator": []

}

Create TCP or iSER iSCSI Targets

1. Log in to the Appliance Controller CLI.
2. Enter:

`iscsiadm add target=<target name> ipaddrs=<target-IP-1>,<target-IP-2>[,<target-IP-3>,<target-IP-4>] [iface=iser]`1

Note: 1 The optional "`iface`" default value is "`tcp`", however, for tcp connections, this can be omitted. This is required for "iser" communication targets.

Parameters:

`<target name>` | The target name.
`<target-IP-1>` | The first IP address used for the target, For additional target IP addresses, add them after the first IP address.

Example: Creating an iSER target

> `iscsiadm add target=iser-target ipaddrs=10.10.0.171,10.10.1.171 iface=iser`

Verify status of iSCSI configuration, including the new target. Enter:

> `iscsiadm show status`

Output

The provided output includes the status of each of the initiator interfaces and each of the target’s ports:

Example: creating a TCP iSCSI target

To add an iSCSI target, enter:

> `iscsiadm add target=qxs-array-1 ipaddrs=192.168.0.223,192.168.1.223`

Note: Since this target uses TCP, we do not need to define `iface=tcp`, it is set to `tcp` by default.

Verify status of iSCSI configuration, including the new target. Enter:

> `iscsiadm show status`

Output

The provided output includes the status of each of the initiator interfaces and each of the target’s ports:

Delete iSCSI Targets

1. Log in to the Appliance Controller CLI.
2. Enter:

`iscsiadm remove target=[<name>[,<name>]*] | target initiator=<name>[,<name>]*]`

Differences between `iscsiadm remove target` and `iscsiadm remove target initiator`:

- “target=” is followed by a comma-separated list of names of targets to be removed. In this case targets may belong to any number of the registered initiators
- “target initiator=” is followed by a comma-separated list of names of initiators whose targets are to be removed. In this case all targets of each of the named initiators will be removed.

Parameter:

`<name>` | The target or initiator name.

Example: two different ways to remove the same target from a single initiator

Remove "qxs-array-1" target from the "xcellishost" initiator:

Method 1:

`iscsiadm remove target=qxs-array-1`

This command would remove the "qxs-array-1" target explicitly.

Method 2:

`iscsiadm remove target initiator=xcellishost`

This command would remove all targets of the "xcellishost" initiator, implicitly removing the "qxs-array-1" target.

Example: verify configuration changes

For both methods, verify the configuration was changed. Enter:

`iscsiadm show status`

Output:

Note that the "targets" list for the "xcellishost" initiator is now empty.

iSCSI Network

1. Log in to the Appliance Controller CLI.
2. At the prompt, enter:

> `iscsiadm network [initiator=<name>[,<name>]]* <start|stop|restart>`

The parameters are:

`<name>` | The name of the initiator. For additional names, add after the first initiator name.
`<start>` | Starts iSCSI network services.
`<stop>` | Stops iSCSI network services.
`<restart>` | Restarts iSCSI network services.

Example:

The following command stops the "private" initiator subnet and network:

> `iscsiadm network initiator=private stop`

iSCSI Session

1. Log in to the Appliance Controller CLI.
2. At the prompt, enter:

> `iscsiadm session [target[=all|<name>[,<name>]*] | [target] initiator[=<name>[,<name>]*] login|logout`

The parameters are:

`<name>` | The name of the target or initiator. For additional names, add after the first initiator name.
`login` | Log in to the iSCSI session
`logout` | Log out of the iSCSI session

Additional information about target session login and logout commands:

1. For "`target=`", add a comma-separated list of names of targets to log in or out of their sessions. Targets may belong to any number of the registered initiators.
2. For "`target initiator=`", add a comma-separated list of initiator names to log in or out out of their targets. All targets of each of the named initiators will be logged in or out.

Example: `target logout`

The following command logs out of the"‘iser-target" target sessions:

> `iscsiadm session target=iser-target logout`

iSCSI Session Timeout

This command allows you to set the timeout value, in seconds, for a session to wait to be re-established before an issued iSCSI command will be considered to have failed.

1. Log in to the Appliance Controller CLI.
2. At the prompt, enter:

> `iscsiadm session-timeout <seconds>`

The parameter is:

`<seconds>` | The default value of this iSCSI parameter is set to 5 seconds. It is not recommended to lower this value. However, the value may be adjusted higher to match the slowest target access for successful completion of its SCSI commands.

Additional

Example: Set the iscsiadm session timeout

The following command will set the session's timeout value to 10 seconds:

> `iscsiadm session-timeout 10`

Show iSCSI Configurations

The `iscsiadm show` command is used to view the state of any and all initiators and targets and look for potential issues in the iSCSI communication between the initiators and their targets.

1. Log in to the Appliance Controller CLI.
2. At the prompt, enter:

> `iscsiadm show [[[[initiator[=<iname>[,<iname>]*]]*] [with_target]] | [target[=<tname>[,<tname>]*]]* [with_initiator] [status] | session-timeout`

The parameters are:

`<iname>` | The initiator name. For additional names, add after the first initiator name.
`with_target` | For each initiator, show its targets configuration information also.
`<tname>` | The target name. For additional names, add after the first target name.
`with_initiator` | For each target, show its initiator configuration information also..
`status` | Shows configuration and state information for initiators and/or their targets, depending on whether the `with_target`, `with_initiator`, or no initiator or target is specified.
`session-timeout` | Shows the current `iscsiadm session timeout` value.

Output: `iscsiadm show`

Output: `iscsiadm show status`
About the information shown in `iscsiadm show status`

1. For Initiator subnets:

- Interface: link_state: < UP | DOWN> – Shows whether the link is up or down
- Network: ip_state: < UP | DOWN> – Shows whether the IP address configuration of the interface is active or not

2. For Target subnets:

- Portal:ip_state: <Accessible|Inaccessible> – Shows whether this IP address is accessible (via ping) or not
- Session_state: < logged in | logged out> – Shows whether target session is logged in from this portal or not

6-68456-07_RevA | Initial publication date: Friday, December 22, 2017 | Last updated on Monday, January 12, 2026.

Open topic with navigation