Configuring and Managing iSCSI Storage

The iSCSI architecture relies on two primary entities: the initiator (the client requesting storage) and the target (the server serving storage). Storage capacity is presented as LUNs.

In a physical iSCSI environment, the initiator is the server’s software that requests data, the LIO target is the physical storage appliance that hosts the data and the LUN (Logical Unit Number) represents the specific physical disk capacity assigned to the server.

The following are some of the common characteristics of iSCSI:

The common use cases for iSCSI include:

Figure 1: iCSI topology #

 

The targetcli tool is the primary command-line administration tool used to configure and manage the LIO (Linux-IO) target subsystem, which is the standard open-source storage target for the Linux kernel. It operates as an interactive shell with a hierarchical file-system-like structure and allows system administrators to export local storage resources—such as physical disks, files, or LVM (Logical Volumes) to remote clients via various fabrics, most notably iSCSI. It provides a unified interface to define back stores, creates IQNs (iSCSI Qualified Names), and establishes ACLs (Access Control Lists).

Similar to a conventional shell, you can traverse the targetcli functional hierarchy using the cd command and list contents with the ls command. While each directory has its own set of commands, these commands that are available in all directories. 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

To switch to the targetcli shell, run 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]
/>

targetcli supports the following back-ends:

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

/> 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 iscsiadm tool is used in Linux environments to manage and administer the Open-iSCSI implementation, acting as the primary interface for configuring and managing iSCSI connections. It allows administrators to discover targets on a network, log in or out of specific storage portals, and manage a local database of persistent iSCSI nodes. By communicating with the iscsid daemon, it facilitates the mapping of remote block storage devices over an IP network, making remote disks appear as local SCSI devices, such as /dev/sdb, to the operating system.

While iscsiadm operations logically require a running iscsid daemon to execute, you do not need to start it manually because systemd socket activation iscsid.socket automatically spawns the iscsid service on demand. When running the discovery the first time, the internal database of the iSCSI initiator is created in the directory /var/lib/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
10.44.171.99:3260,1 iqn.2006-02.com.example.iserv:systems

For each target defined on the iSCSI target, one line appears.

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.

All information 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 whether 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 command, for example:

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

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

Problem setting network portal IP_ADDRESS:3260

The journalctl command displays 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, 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    491520  7
  target_core_mod   598016  15 target_core_file,target_core_iblock,iscsi_target_mod,target_core_pscsi,
  target_core_user
  configfs          69632  3 iscsi_target_mod,target_core_mod
  scsi_common       16384  10 scsi_mod,target_core_iblock,iscsi_target_mod,sd_mod,target_core_mod,
  target_core_pscsi,libata,sg,target_core_user,sr_mod

If you use a firewall on the target server, you must open the iSCSI port that you are using to allow other systems to see the iSCSI LIO targets. TCP port 3260 is the port number for the iSCSI protocol, as defined by IANA (Internet Assigned Numbers Authority).

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.

Use the troubleshooting tips in this section when using LVM on iSCSI targets. When configuring the iSCSI initiator, ensure that the iSCSI service and target nodes are set to start automatically at boot. This ensures that iSCSI sessions are established during startup, allowing udev to initialize the block devices so that LVM can detect and activate the volume groups.

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.

When Open-iSCSI starts, it can mount the targets even when node.startup is set to manual in /etc/iscsi/iscsid.conf if the node database was edited manually.

Avoid manually viewing or modifying the node database files. Instead, use the iscsiadm command to query the target configuration:

> sudo  iscsiadm -m node -T TARGET_NAME | grep node.startup