Applies to SUSE Linux Enterprise Server 15 SP6

15 Mass storage over IP networks: iSCSI #

One of the primary tasks of a computer center, or any site that supports servers, is to provide adequate disk capacity. Fibre Channel is often used for this purpose. iSCSI (Internet SCSI) solutions provide a lower-cost alternative to Fibre Channel that can leverage commodity servers and Ethernet networking equipment. Linux iSCSI provides iSCSI initiator and iSCSI LIO target software for connecting Linux servers to central storage systems.

Figure 15.1: iSCSI SAN with an iSNS server #

Note: LIO

LIO is the standard open source multiprotocol SCSI target for Linux. LIO replaced the STGT (SCSI Target) framework as the standard unified storage target in Linux with Linux kernel version 2.6.38 and later. In SUSE Linux Enterprise Server 12 the iSCSI LIO Target Server replaces the iSCSI Target Server from previous versions.

iSCSI is a storage networking protocol that simplifies data transfers of SCSI packets over TCP/IP networks between block storage devices and servers. iSCSI target software runs on the target server and defines the logical units as iSCSI target devices. iSCSI initiator software runs on different servers and connects to the target devices to make the storage devices available on that server.

The iSCSI LIO target server and iSCSI initiator servers communicate by sending SCSI packets at the IP level in your LAN. When an application running on the initiator server starts an inquiry for an iSCSI LIO target device, the operating system produces the necessary SCSI commands. The SCSI commands are then embedded in IP packets and encrypted as necessary by software that is commonly known as the iSCSI initiator. The packets are transferred across the internal IP network to the corresponding iSCSI remote station, called the iSCSI LIO target server, or simply the iSCSI target.

Many storage solutions provide access over iSCSI, but it is also possible to run a Linux server that provides an iSCSI target. In this case, it is important to set up a Linux server that is optimized for file system services. For more information about RAID, also see Chapter 7, Software RAID configuration.

15.1 Installing the iSCSI LIO target server and iSCSI initiator #

While the iSCSI initiator is installed by default (packages open-iscsi and yast2-iscsi-client), the iSCSI LIO target packages need to be installed manually.

Important: Initiator and target on the same server

While it is possible to run initiator and target in the same system, this setup is not recommended.

To install the iSCSI LIO Target Server, run the following command in a terminal:

> sudo zypper in yast2-iscsi-lio-server

In case you need to install the iSCSI initiator or any of its dependencies, run the command sudo zypper in yast2-iscsi-client.

Alternatively, use the YaST Software Management module for installation.

Any packages required in addition to the ones mentioned above will either be automatically pulled in by the installer, or be installed when you first run the respective YaST module.

15.2 Setting up an iSCSI LIO target server #

This section describes how to use YaST to configure an iSCSI LIO Target Server and set up iSCSI LIO target devices. You can use any iSCSI initiator software to access the target devices.

15.2.1 iSCSI LIO target service start-up and firewall settings #

The iSCSI LIO Target service is by default configured to be started manually. You can configure the service to start automatically at boot time. If you use a firewall on the server and you want the iSCSI LIO targets to be available to other computers, you must open a port in the firewall for each adapter that you want to use for target access. TCP port 3260 is the port number for the iSCSI protocol, as defined by IANA (Internet Assigned Numbers Authority).

Start YaST and launch Network Services › iSCSI LIO Target.
Switch to the Service tab.
Under Service Start, specify how you want the iSCSI LIO target service to be started:
- When booting: The service starts automatically on server restart.
- Manually: (Default) You must start the service manually after a server restart by running sudo systemctl start targetcli. The target devices are not available until you start the service.
If you use a firewall on the server and you want the iSCSI LIO targets to be available to other computers, open port 3260 in the firewall for each adapter interface that you want to use for target access. If the port is closed for all of the network interfaces, the iSCSI LIO targets are not available to other computers.
If you do not use a firewall on the server, the firewall settings are disabled. In this case skip the following steps and leave the configuration dialog with Finish or switch to another tab to continue with the configuration.
1. On the Services tab, select the Open Port in Firewall check box to enable the firewall settings.
2. Click Firewall Details to view or configure the network interfaces to use. All available network interfaces are listed, and all are selected by default. Deselect all interfaces on which the port should not be opened. Save your settings with OK.
Click Finish to save and apply the iSCSI LIO Target service settings.

15.2.2 Configuring authentication for discovery of iSCSI LIO targets and initiators #

The iSCSI LIO Target Server software supports the PPP-CHAP (Point-to-Point Protocol Challenge Handshake Authentication Protocol), a three-way authentication method defined in the Internet Engineering Task Force (IETF) RFC 1994 (https://datatracker.ietf.org/doc/html/rfc1994). The server uses this authentication method for the discovery of iSCSI LIO targets and initiators, not for accessing files on the targets. If you do not want to restrict the access to the discovery, use No Authentication. The No Discovery Authentication option is enabled by default. Without requiring authentication all iSCSI LIO targets on this server can be discovered by any iSCSI initiator on the same network.

If authentication is needed for a more secure configuration, you can use incoming authentication, outgoing authentication, or both. Authentication by Initiators requires an iSCSI initiator to prove that it has the permissions to run a discovery on the iSCSI LIO target. The initiator must provide the incoming user name and password. Authentication by Targets requires the iSCSI LIO target to prove to the initiator that it is the expected target. The iSCSI LIO target must provide the outgoing user name and password to the iSCSI initiator. The password needs to be different for incoming and outgoing discovery. If authentication for discovery is enabled, its settings apply to all iSCSI LIO target groups.

Important: Security

We recommend that you use authentication for target and initiator discovery in production environments for security reasons.

To configure authentication preferences for iSCSI LIO targets:

Start YaST and launch Network Services › iSCSI LIO Target.
Switch to the Global tab.
By default, authentication is disabled (No Discovery Authentication). To enable Authentication, select Authentication by Initiators, Outgoing Authentication or both.
Provide credentials for the selected authentication method(s). The user name and password pair must be different for incoming and outgoing discovery.
Click Finish to save and apply the settings.

15.2.3 Preparing the storage space #

Before you configure LUNs for your iSCSI Target servers, you must prepare the storage you want to use. You can use the entire unformatted block device as a single LUN, or you can subdivide a device into unformatted partitions and use each partition as a separate LUN. The iSCSI target configuration exports the LUNs to iSCSI initiators.

You can use the Partitioner in YaST or the command line to set up the partitions. Refer to Section 11.1, “Using the Expert Partitioner” for details. iSCSI LIO targets can use unformatted partitions with Linux, Linux LVM, or Linux RAID file system IDs.

Important: Do not mount iSCSI target devices

After you set up a device or partition for use as an iSCSI target, you never access it directly via its local path. Do not mount the partitions on the target server.

15.2.3.1 Partitioning devices in a virtual environment #

You can use a virtual machine guest server as an iSCSI LIO Target Server. This section describes how to assign partitions to a Xen virtual machine. You can also use other virtual environments that are supported by SUSE Linux Enterprise Server.

In a Xen virtual environment, you must assign the storage space you want to use for the iSCSI LIO target devices to the guest virtual machine, then access the space as virtual disks within the guest environment. Each virtual disk can be a physical block device, such as an entire disk, partition, or volume, or it can be a file-backed disk image where the virtual disk is a single image file on a larger physical disk on the Xen host server. For the best performance, create each virtual disk from a physical disk or a partition. After you set up the virtual disks for the guest virtual machine, start the guest server, then configure the new blank virtual disks as iSCSI target devices by following the same process as for a physical server.

File-backed disk images are created on the Xen host server, then assigned to the Xen guest server. By default, Xen stores file-backed disk images in the /var/lib/xen/images/VM_NAME directory, where VM_NAME is the name of the virtual machine.

15.2.4 Setting up an iSCSI LIO target group #

You can use YaST to configure iSCSI LIO target devices. YaST uses the targetcli software. iSCSI LIO targets can use partitions with Linux, Linux LVM, or Linux RAID file system IDs.

Important: Partitions

Before you begin, choose the partitions you wish to use for back-end storage. The partitions do not have to be formatted—the iSCSI client can format them when connected, overwriting all existing formatting.

Start YaST and launch Network Services › iSCSI LIO Target.
Switch to the Targets tab.
Click Add, then define a new iSCSI LIO target group and devices:
The iSCSI LIO Target software automatically completes the Target, Identifier, Portal Group, IP Address, and Port Number fields. Use Authentication is selected by default.
1. If you have multiple network interfaces, use the IP address drop-down box to select the IP address of the network interface to use for this target group. To make the server accessible under all addresses, choose Bind All IP Addresses.
2. Deselect Use Authentication if you do not want to require initiator authentication for this target group (not recommended).
3. Click Add. Enter the path of the device or partition or Browse to add it. Optionally specify a name, then click OK. The LUN number is automatically generated, beginning with 0. A name is automatically generated if you leave the field empty.
4. (Optional) Repeat the previous steps to add targets to this target group.
5. After all desired targets have been added to the group, click Next.
On the Modify iSCSI Target Initiator Setup page, configure information for the initiators that are permitted to access LUNs in the target group:
After you specify at least one initiator for the target group, the Edit LUN, Edit Auth, Delete, and Copy buttons are enabled. You can use Add or Copy to add initiators for the target group:
Modify iSCSI target: options #
- Add: Add a new initiator entry for the selected iSCSI LIO target group.
- Edit LUN: Configure which LUNs in the iSCSI LIO target group to map to a selected initiator. You can map each of the allocated targets to a preferred initiator.
- Edit auth: Configure the preferred authentication method for a selected initiator. You can specify no authentication, or you can configure incoming authentication, outgoing authentication, or both.
- Delete: Remove a selected initiator entry from the list of initiators allocated to the target group.
- Copy: Add a new initiator entry with the same LUN mappings and authentication settings as a selected initiator entry. This allows you to easily allocate the same shared LUNs, in turn, to each node in a cluster.
1. Click Add, specify the initiator name, select or deselect the Import LUNs from TPG check box, then click OK to save the settings.
2. Select an initiator entry, click Edit LUN, modify the LUN mappings to specify which LUNs in the iSCSI LIO target group to allocate to the selected initiator, then click OK to save the changes.
  If the iSCSI LIO target group consists of multiple LUNs, you can allocate one or multiple LUNs to the selected initiator. By default, each of the available LUNs in the group are assigned to an initiator LUN.
  To modify the LUN allocation, perform one or more of the following actions:
  - Add: Click Add to create a new Initiator LUN entry, then use the Change drop-down box to map a target LUN to it.
  - Delete: Select the Initiator LUN entry, then click Delete to remove a target LUN mapping.
  - Change: Select the Initiator LUN entry, then use the Change drop-down box to select which Target LUN to map to it.
  Typical allocation plans include the following:
  - A single server is listed as an initiator. All of the LUNs in the target group are allocated to it.
    You can use this grouping strategy to logically group the iSCSI SAN storage for a given server.
  - Multiple independent servers are listed as initiators. One or multiple target LUNs are allocated to each server. Each LUN is allocated to only one server.
    You can use this grouping strategy to logically group the iSCSI SAN storage for a given department or service category in the data center.
  - Each node of a cluster is listed as an initiator. All of the shared target LUNs are allocated to each node. All nodes are attached to the devices, but for most file systems, the cluster software locks a device for access and mounts it on only one node at a time. Shared file systems (such as OCFS2) make it possible for multiple nodes to concurrently mount the same file structure and to open the same files with read and write access.
    You can use this grouping strategy to logically group the iSCSI SAN storage for a given server cluster.
3. Select an initiator entry, click Edit Auth, specify the authentication settings for the initiator, then click OK to save the settings.
  You can require No Discovery Authentication, or you can configure Authentication by Initiators, Outgoing Authentication, or both. You can specify only one user name and password pair for each initiator. The credentials can be different for incoming and outgoing authentication for an initiator. The credentials can be different for each initiator.
4. Repeat the previous steps for each iSCSI initiator that can access this target group.
5. After the initiator assignments are configured, click Next.
Click Finish to save and apply the settings.

15.2.5 Modifying an iSCSI LIO target group #

You can modify an existing iSCSI LIO target group as follows:

Add or remove target LUN devices from a target group
Add or remove initiators for a target group
Modify the initiator LUN-to-target LUN mappings for an initiator of a target group
Modify the user name and password credentials for an initiator authentication (incoming, outgoing, or both)

To view or modify the settings for an iSCSI LIO target group:

Start YaST and launch Network Services › iSCSI LIO Target.
Switch to the Targets tab.
Select the iSCSI LIO target group to be modified, then click Edit.
On the Modify iSCSI Target LUN Setup page, add LUNs to the target group, edit the LUN assignments, or remove target LUNs from the group. After all desired changes have been made to the group, click Next.
For option information, see Modify iSCSI target: options.
On the Modify iSCSI Target Initiator Setup page, configure information for the initiators that are permitted to access LUNs in the target group. After all desired changes have been made to the group, click Next.
Click Finish to save and apply the settings.

15.2.6 Deleting an iSCSI LIO target group #

Deleting an iSCSI LIO target group removes the definition of the group, and the related setup for initiators, including LUN mappings and authentication credentials. It does not destroy the data on the partitions. To give initiators access again, you can allocate the target LUNs to a different or new target group, and configure the initiator access for them.

Start YaST and launch Network Services › iSCSI LIO Target.
Switch to the Targets tab.
Select the iSCSI LIO target group to be deleted, then click Delete.
When you are prompted, click Continue to confirm the deletion, or click Cancel to cancel it.
Click Finish to save and apply the settings.

15.3 Configuring iSCSI initiator #

The iSCSI initiator can be used to connect to any iSCSI target. This is not restricted to the iSCSI target solution explained in Section 15.2, “Setting up an iSCSI LIO target server”. The configuration of iSCSI initiator involves two major steps: the discovery of available iSCSI targets and the setup of an iSCSI session. Both can be done with YaST.

15.3.1 Using YaST for the iSCSI initiator configuration #

The iSCSI Initiator Overview in YaST is divided into three tabs:

Service:: The Service tab can be used to enable the iSCSI initiator at boot time. It also offers to set a unique Initiator Name and an iSNS server to use for the discovery.
Connected targets:: The Connected Targets tab gives an overview of the currently connected iSCSI targets. Like the Discovered Targets tab, it also gives the option to add new targets to the system.
Discovered targets:: The Discovered Targets tab provides the possibility of manually discovering iSCSI targets in the network.

15.3.1.1 Configuring the iSCSI initiator #

Start YaST and launch Network Services › iSCSI Initiator.
Switch to the Service tab.
Under After writing configuration, define what to do if there is a configuration change. Bear in mind that available options depend on the service current status.
The Keep current state option keeps the service in the same status.
In the After reboot menu specify action that will take place after reboot:
- Start on boot - to start the service automatically on boot.
- Start on demand - the associated socket will be running and if needed, the service will be started.
- Do not start - the service is not started automatically.
- Keep current settings - the service configuration is not changed.
Specify or verify the Initiator Name.
Specify a well-formed iSCSI qualified name (IQN) for the iSCSI initiator on this server. The initiator name must be globally unique on your network. The IQN uses the following general format:
```
iqn.yyyy-mm.com.mycompany:n1:n2
```
where n1 and n2 are alphanumeric characters. For example:
```
iqn.1996-04.de.suse:01:a5dfcea717a
```
The Initiator Name is automatically completed with the corresponding value from the /etc/iscsi/initiatorname.iscsi file on the server.
If the server has iBFT (iSCSI Boot Firmware Table) support, the Initiator Name is completed with the corresponding value in the IBFT, and you are not able to change the initiator name in this interface. Use the BIOS Setup to modify it instead. The iBFT is a block of information containing various parameters useful to the iSCSI boot process, including iSCSI target and initiator descriptions for the server.
Use either of the following methods to discover iSCSI targets on the network.
- iSNS: To use iSNS (Internet Storage Name Service) for discovering iSCSI targets, continue with Section 15.3.1.2, “Discovering iSCSI targets by using iSNS”.
- Discovered targets: To discover iSCSI target devices manually, continue with Section 15.3.1.3, “Discovering iSCSI targets manually”.

15.3.1.2 Discovering iSCSI targets by using iSNS #

Before you can use this option, you must have already installed and configured an iSNS server in your environment. For information, see Chapter 14, iSNS for Linux.

In YaST, select iSCSI Initiator, then select the Service tab.
Specify the IP address of the iSNS server and port. The default port is 3205.
Click OK to save and apply your changes.

15.3.1.3 Discovering iSCSI targets manually #

Repeat the following process for each of the iSCSI target servers that you want to access from the server where you are setting up the iSCSI initiator.

In YaST, select iSCSI Initiator, then select the Discovered Targets tab.
Click Discovery to open the iSCSI Initiator Discovery dialog.
Enter the IP address and change the port if needed. The default port is 3260.
If authentication is required, deselect No Discovery Authentication, then specify the credentials for Authentication by Initiator or Authentication by Targets.
Click Next to start the discovery and connect to the iSCSI target server.
If credentials are required, after a successful discovery, use Connect to activate the target.
You are prompted for authentication credentials to use the selected iSCSI target.
Click Next to finish the configuration.
The target now appears in Connected Targets and the virtual iSCSI device is now available.
Click OK to save and apply your changes.
You can find the local device path for the iSCSI target device by using the lsscsi command.

15.3.1.4 Setting the start-up preference for iSCSI target devices #

In YaST, select iSCSI Initiator, then select the Connected Targets tab to view a list of the iSCSI target devices that are currently connected to the server.
Select the iSCSI target device that you want to manage.
Click Toggle Start-Up to modify the setting:
Automatic: This option is used for iSCSI targets that are to be connected when the iSCSI service itself starts up. This is the typical configuration.
Onboot: This option is used for iSCSI targets that are to be connected during boot; that is, when root (/) is on iSCSI. As such, the iSCSI target device will be evaluated from the initrd on server boots. This option is ignored on platforms that cannot boot from iSCSI, such as IBM Z. Therefore it should not be used on these platforms; use Automatic instead.
Click OK to save and apply your changes.

15.3.2 Setting up the iSCSI initiator manually #

Both the discovery and the configuration of iSCSI connections require a running iscsid. When running the discovery the first time, the internal database of the iSCSI initiator is created in the directory /etc/iscsi/.

If your discovery is password protected, provide the authentication information to iscsid. Because the internal database does not exist when doing the first discovery, it cannot be used now. Instead, the configuration file /etc/iscsid.conf must be edited to provide the information. To add your password information for the discovery, add the following lines to the end of /etc/iscsid.conf:

discovery.sendtargets.auth.authmethod = CHAP
discovery.sendtargets.auth.username = USERNAME
discovery.sendtargets.auth.password = PASSWORD

The discovery stores all received values in an internal persistent database. In addition, it displays all detected targets. Run this discovery with the following command:

> sudo iscsiadm -m discovery --type=st --portal=TARGET_IP

The output should look like the following:

10.44.171.99:3260,1 iqn.2006-02.com.example.iserv:systems

To discover the available targets on an iSNS server, use the following command:

sudo iscsiadm --mode discovery --type isns --portal TARGET_IP

For each target defined on the iSCSI target, one line appears. For more information about the stored data, see Section 15.3.3, “The iSCSI initiator databases”.

The special --login option of iscsiadm creates all needed devices:

> sudo iscsiadm -m node -n iqn.2006-02.com.example.iserv:systems --login

The newly generated devices show up in the output of lsscsi and can now be mounted.

15.3.3 The iSCSI initiator databases #

All information that was discovered by the iSCSI initiator is stored in two database files that reside in /etc/iscsi. There is one database for the discovery of targets and one for the discovered nodes. When accessing a database, you first must select if you want to get your data from the discovery or from the node database. Do this with the -m discovery and -m node parameters of iscsiadm. Using iscsiadm with one of these parameters gives an overview of the stored records:

> sudo iscsiadm -m discovery
10.44.171.99:3260,1 iqn.2006-02.com.example.iserv:systems

The target name in this example is iqn.2006-02.com.example.iserv:systems. This name is needed for all actions that relate to this special data set. To examine the content of the data record with the ID iqn.2006-02.com.example.iserv:systems, use the following command:

> sudo iscsiadm -m node --targetname iqn.2006-02.com.example.iserv:systems
node.name = iqn.2006-02.com.example.iserv:systems
node.transport_name = tcp
node.tpgt = 1
node.active_conn = 1
node.startup = manual
node.session.initial_cmdsn = 0
node.session.reopen_max = 32
node.session.auth.authmethod = CHAP
node.session.auth.username = joe
node.session.auth.password = ********
node.session.auth.username_in = EMPTY
node.session.auth.password_in = EMPTY
node.session.timeo.replacement_timeout = 0
node.session.err_timeo.abort_timeout = 10
node.session.err_timeo.reset_timeout = 30
node.session.iscsi.InitialR2T = No
node.session.iscsi.ImmediateData = Yes
....

To edit the value of one of these variables, use the command iscsiadm with the update operation. For example, if you want iscsid to log in to the iSCSI target when it initializes, set the variable node.startup to the value automatic:

sudo iscsiadm -m node -n iqn.2006-02.com.example.iserv:systems \
-p ip:port --op=update --name=node.startup --value=automatic

Remove obsolete data sets with the delete operation. If the target iqn.2006-02.com.example.iserv:systems is no longer a valid record, delete this record with the following command:

> sudo iscsiadm -m node -n iqn.2006-02.com.example.iserv:systems \
-p ip:port --op=delete

Important: No confirmation

Use this option with caution because it deletes the record without any additional confirmation prompt.

To get a list of all discovered targets, run the sudo iscsiadm -m node command.

15.4 Setting up software targets using targetcli-fb #

targetcli is a shell for managing the configuration of the LinuxIO (LIO) target subsystem. The shell can be called interactively, or you can execute one command at a time, much like a conventional shell. Similar to a conventional shell, you can traverse the targetcli functional hierarchy using the cd command and list contents with the ls command.

The available commands depend on the current directory. While each directory has its own set of commands, there are also commands that are available in all directories (for example, the cd and ls commands).

targetcli commands have the following format:

[DIRECTORY] command [ARGUMENTS]

You can use the help command in any directory to view a list of available commands or information about any command in particular.

The targetcli tool is part of the targetcli-fb package. This package is available in the official SUSE Linux Enterprise Server software repository, and it can be installed using the following command:

> sudo zypper install targetcli-fb

After the targetcli-fb package has been installed, enable the targetcli service:

> sudo systemctl enable targetcli
> sudo systemctl start targetcli

To switch to the targetcli shell, run the targetcli as root:

> sudo targetcli

You can then run the ls command to see the default configuration.

/> ls
o- / ............................ [...]
  o- backstores ................. [...]
  | o- block ..... [Storage Objects: 0]
  | o- fileio .... [Storage Objects: 0]
  | o- pscsi ..... [Storage Objects: 0]
  | o- ramdisk ... [Storage Objects: 0]
  | o- rbd ....... [Storage Objects: 0]
  o- iscsi ............... [Targets: 0]
  o- loopback ............ [Targets: 0]
  o- vhost ............... [Targets: 0]
  o- xen-pvscsi .......... [Targets: 0]
/>

As the output of the ls command indicates, there are no configured back-ends. So the first step is to configure one of the supported software targets.

targetcli supports the following back-ends:

fileio, local image file
block, block storage on a dedicated disk or partition
pscsi, SCSI pass-through devices
ramdisk, memory-based back-end
rbd, Ceph RADOS block devices

To familiarize yourself with the functionality of targetcli, set up a local image file as a software target using the create command:

/backstores/fileio create test-disc /alt/test.img 1G

This creates a 1 GB test.img image in the specified location (in this case /alt). Run ls, and you should see the following result:

/> ls
o- / ........................................................... [...]
  o- backstores ................................................ [...]
  | o- block .................................... [Storage Objects: 0]
  | o- fileio ................................... [Storage Objects: 1]
  | | o- test-disc ... [/alt/test.img (1.0GiB) write-back deactivated]
  | |   o- alua ......     .......................... [ALUA Groups: 1]
  | |     o- default_tg_pt_gp      .... [ALUA state: Active/optimized]
  | o- pscsi .................................... [Storage Objects: 0]
  | o- ramdisk .................................. [Storage Objects: 0]
  | o- rbd ...................................... [Storage Objects: 0]
  o- iscsi .............................................. [Targets: 0]
  o- loopback ........................................... [Targets: 0]
  o- vhost .............................................. [Targets: 0]
  o- xen-pvscsi ......................................... [Targets: 0]
/>

The output indicates that there is now a file-based backstore, under the /backstores/fileio directory, called test-disc, which is linked to the created file /alt/test.img. Note that the new backstore is not yet activated.

The next step is to connect an iSCSI target front-end to the back-end storage. Each target must have an IQN (iSCSI Qualified Name). The most commonly used IQN format is as follows:

iqn.YYYY-MM.NAMING-AUTHORITY:UNIQUE-NAME

The following parts of an IQN are required:

YYYY-MM, the year and month when the naming authority was established
NAMING-AUTHORITY, reverse-syntax of the Internet Domain Name of the naming authority
UNIQUE-NAME, a domain-unique name chosen by the naming authority

For example, for the domain open-iscsi.com, the IQN can be as follows:

iqn.2005-03.com.open-iscsi:UNIQUE-NAME

When creating an iSCSI target, the targetcli command allows you to assign your own IQN, as long as it follows the specified format. You can also let the command create an IQN for you by omitting a name when creating the target, for example:

/> iscsi/ create

Run the ls command again:

/> ls
o- / ............................................................... [...]
  o- backstores .................................................... [...]
  | o- block ........................................ [Storage Objects: 0]
  | o- fileio ....................................... [Storage Objects: 1]
  | | o- test-disc ....... [/alt/test.img (1.0GiB) write-back deactivated]
  | |   o- alua ......................................... [ALUA Groups: 1]
  | |     o- default_tg_pt_gp ............. [ALUA state: Active/optimized]
  | o- pscsi ........................................ [Storage Objects: 0]
  | o- ramdisk ...................................... [Storage Objects: 0]
  | o- rbd .......................................... [Storage Objects: 0]
  o- iscsi .................................................. [Targets: 1]
  | o- iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456 ... [TPGs: 1]
  |   o- tpg1 ..................................... [no-gen-acls, no-auth]
  |     o- acls ................................................ [ACLs: 0]
  |     o- luns ................................................ [LUNs: 0]
  |     o- portals .......................................... [Portals: 1]
  |       o- 0.0.0.0:3260 ........................................... [OK]
  o- loopback ............................................... [Targets: 0]
  o- vhost .................................................. [Targets: 0]
  o- xen-pvscsi ............................................. [Targets: 0]
/>

The output shows the created iSCSI target node with its automatically generated IQN iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456

Note that targetcli has also created and enabled the default target portal group tpg1. This is done because the variables auto_add_default_portal and auto_enable_tpgt at the root level are set to true by default.

The command also created the default portal with the 0.0.0.0 IPv4 wildcard. This means that any IPv4 address can access the configured target.

The next step is to create a LUN (Logical Unit Number) for the iSCSI target. The best way to do this is to let targetcli assign its name and number automatically. Switch to the directory of the iSCSI target, and then use the create command in the lun directory to assign a LUN to the backstore.

/> cd /iscsi/iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456/
/iscsi/iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456> cd tpg1
/iscsi/iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456/tpg1> luns/
create /backstores/fileio/test-disc

Run the ls command to see the changes:

/iscsi/iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456/tpg1> ls
o- tpg1 .............................................. [no-gen-acls, no-auth]
      o- acls ..................................................... [ACLs: 0]
      o- luns ..................................................... [LUNs: 1]
      | o- lun0 ....... [fileio/test-disc (/alt/test.img) (default_tg_pt_gp)]
      o- portals ............................................... [Portals: 1]
        o- 0.0.0.0:3260 ................................................ [OK]

There is now an iSCSI target that has a 1 GB file-based backstore. The target has the iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456 name, and it can be accessed from any network port of the system.

Finally, you need to ensure that initiators have access to the configured target. One way to do this is to create an ACL rule for each initiator that allows them to connect to the target. In this case, you must list each desired initiator using its IQN. The IQNs of the existing initiators can be found in the /etc/iscsi/initiatorname.iscsi file. Use the following command to add the desired initiator (in this case, it's iqn.1996-04.de.suse:01:54cab487975b):

/iscsi/iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456/tpg1> acls/ create iqn.1996-04.de.suse:01:54cab487975b
Created Node ACL for iqn.1996-04.de.suse:01:54cab487975b
Created mapped LUN 0.
/iscsi/iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456/tpg1>

Alternatively, you can run the target in a demo mode with no access restrictions. This method is less secure, but it can be useful for demonstration purposes and running on closed networks. To enable the demo mode, use the following commands:

/iscsi/iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456/tpg1> set attribute generate_node_acls=1
/iscsi/iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456/tpg1> set attribute demo_mode_write_protect=0

The last step is to save the created configuration using the saveconfig command available in the root directory:

/> saveconfig /etc/target/example.json

If at some point you need to restore configuration from the saved file, you need to clear the current configuration first. Keep in mind that clearing the current configuration results in data loss unless you save your configuration first. Use the following command to clear and reload the configuration:

/> clearconfig
As a precaution, confirm=True needs to be set
/> clearconfig confirm=true
All configuration cleared
/> restoreconfig /etc/target/example.json
Configuration restored from /etc/target/example.json
/>

To test whether the configured target is working, connect to it using the open-iscsi iSCSI initiator installed on the same system (replace HOSTNAME with the host name of the local machine):

> iscsiadm -m discovery -t st -p HOSTNAME

This command returns a list of found targets, for example:

192.168.20.3:3260,1 iqn.2003-01.org.linux-iscsi.e83.x8664:sn.8b35d04dd456

You can then connect to the listed target using the login iSCSI command. This makes the target available as a local disk.

15.5 Using iSCSI disks when installing #

Booting from an iSCSI disk on AMD64/Intel 64 and IBM POWER architectures is supported when iSCSI-enabled firmware is used.

To use iSCSI disks during installation, it is necessary to add the following parameter to the boot parameter line:

withiscsi=1

During installation, an additional screen appears that provides the option to attach iSCSI disks to the system and use them in the installation process.

Note: Mount point support

iSCSI devices will appear asynchronously during the boot process. While the initrd guarantees that those devices are set up correctly for the root file system, there are no such guarantees for any other file systems or mount points like /usr. Hence any system mount points like /usr or /var are not supported. To use those devices, ensure correct synchronization of the respective services and devices.

15.6 Troubleshooting iSCSI #

This section describes some known issues and possible solutions for iSCSI target and iSCSI initiator issues.

15.6.1 Portal error when setting up target LUNs on an iSCSI LIO target server #

When adding or editing an iSCSI LIO target group, you get an error:

Problem setting network portal IP_ADDRESS:3260

The /var/log/YasT2/y2log log file contains the following error:

find: `/sys/kernel/config/target/iscsi': No such file or directory

This problem occurs if the iSCSI LIO Target Server software is not currently running. To resolve this issue, exit YaST, manually start iSCSI LIO at the command line with systemctl start targetcli, then try again.

You can also enter the following to check if configfs, iscsi_target_mod, and target_core_mod are loaded. A sample response is shown.

> sudo lsmod | grep iscsi
iscsi_target_mod      295015  0
target_core_mod       346745  4
iscsi_target_mod,target_core_pscsi,target_core_iblock,target_core_file
configfs               35817  3 iscsi_target_mod,target_core_mod
scsi_mod              231620  16
iscsi_target_mod,target_core_pscsi,target_core_mod,sg,sr_mod,mptctl,sd_mod,
scsi_dh_rdac,scsi_dh_emc,scsi_dh_alua,scsi_dh_hp_sw,scsi_dh,libata,mptspi,
mptscsih,scsi_transport_spi

15.6.2 iSCSI LIO targets are not visible from other computers #

If you use a firewall on the target server, you must open the iSCSI port that you are using to allow other computers to see the iSCSI LIO targets. For information, see Section 15.2.1, “iSCSI LIO target service start-up and firewall settings”.

15.6.3 Data packets dropped for iSCSI traffic #

A firewall might drop packets if it gets too busy. The default for the SUSE Firewall is to drop packets after three minutes. If you find that iSCSI traffic packets are being dropped, consider configuring the SUSE Firewall to queue packets instead of dropping them when it gets too busy.

15.6.4 Using iSCSI volumes with LVM #

Use the troubleshooting tips in this section when using LVM on iSCSI targets.

15.6.4.1 Check if the iSCSI initiator discovery occurs at boot #

When you set up the iSCSI Initiator, ensure that you enable discovery at boot time so that udev can discover the iSCSI devices at boot time and set up the devices to be used by LVM.

15.6.4.2 Check that iSCSI target discovery occurs at boot #

Remember that udev provides the default setup for devices. Ensure that all of the applications that create devices are started at boot time so that udev can recognize and assign devices for them at system start-up. If the application or service is not started until later, udev does not create the device automatically as it would at boot time.

15.6.5 iSCSI targets are mounted when the configuration file is set to manual #

When Open-iSCSI starts, it can mount the targets even if the node.startup option is set to manual in the /etc/iscsi/iscsid.conf file if you manually modified the configuration file.

Check the /etc/iscsi/nodes/TARGET_NAME/IP_ADDRESS,PORT/default file. It contains a node.startup setting that overrides the /etc/iscsi/iscsid.conf file. Setting the mount option to manual by using the YaST interface also sets node.startup = manual in the /etc/iscsi/nodes/TARGET_NAME/IP_ADDRESS,PORT/defaultfiles.

15.7 iSCSI LIO target terminology #

backstore: A physical storage object that provides the actual storage underlying an iSCSI endpoint.
CDB (command descriptor block): The standard format for SCSI commands. CDBs are commonly 6, 10, or 12 bytes long, though they can be 16 bytes or of variable length.
CHAP (challenge handshake authentication protocol): A point-to-point protocol (PPP) authentication method used to confirm the identity of one computer to another. After the Link Control Protocol (LCP) connects the two computers, and the CHAP method is negotiated, the authenticator sends a random Challenge to the peer. The peer issues a cryptographically hashed Response that depends upon the Challenge and a secret key. The authenticator verifies the hashed Response against its own calculation of the expected hash value, and either acknowledges the authentication or terminates the connection. CHAP is defined in the RFC 1994.
CID (connection identifier): A 16‐bit number, generated by the initiator, that uniquely identifies a connection between two iSCSI devices. This number is presented during the login phase.
endpoint: The combination of an iSCSI Target Name with an iSCSI TPG (IQN + Tag).
EUI (extended unique identifier): A 64‐bit number that uniquely identifies every device in the world. The format consists of 24 bits that are unique to a given company, and 40 bits assigned by the company to each device it builds.
initiator: The originating end of an SCSI session. Typically a controlling device such as a computer.
IPS (Internet protocol storage): The class of protocols or devices that use the IP protocol to move data in a storage network. FCIP (Fibre Channel over Internet Protocol), iFCP (Internet Fibre Channel Protocol), and iSCSI (Internet SCSI) are all examples of IPS protocols.
IQN (iSCSI qualified name): A name format for iSCSI that uniquely identifies every device in the world (for example: iqn.5886.com.acme.tapedrive.sn‐a12345678).
ISID (initiator session identifier): A 48‐bit number, generated by the initiator, that uniquely identifies a session between the initiator and the target. This value is created during the login process, and is sent to the target with a Login PDU.
MCS (multiple connections per session): A part of the iSCSI specification that allows multiple TCP/IP connections between an initiator and a target.
MPIO (multipath I/O): A method by which data can take multiple redundant paths between a server and storage.
network portal: The combination of an iSCSI endpoint with an IP address plus a TCP (Transmission Control Protocol) port. TCP port 3260 is the port number for the iSCSI protocol, as defined by IANA (Internet Assigned Numbers Authority).
SAM (SCSI architectural model): A document that describes the behavior of SCSI in general terms, allowing for different types of devices communicating over various media.
target: The receiving end of an SCSI session, typically a device such as a disk drive, tape drive, or scanner.
target group (TG): A list of SCSI target ports that are all treated the same when creating views. Creating a view can help simplify LUN (logical unit number) mapping. Each view entry specifies a target group, host group, and a LUN.
target port: The combination of an iSCSI endpoint with one or more LUNs.
target port group (TPG): A list of IP addresses and TCP port numbers that determines which interfaces a specific iSCSI target will listen to.
target session identifier (TSID): A 16‐bit number, generated by the target, that uniquely identifies a session between the initiator and the target. This value is created during the login process, and is sent to the initiator with a Login Response PDU (protocol data units).

15.8 More information #

The iSCSI protocol has been available for several years. There are many reviews comparing iSCSI with SAN solutions, benchmarking performance, and there also is documentation describing hardware solutions. For more information, see the Open-iSCSI project home page at https://www.open-iscsi.com/.

Additionally, see the man pages for iscsiadm, iscsid, and the example configuration file /etc/iscsid.conf.