Red Hat Enterprise Linux Diagnostics and Troubleshooting
Internet Small Computer System Interface (iSCSI) is a TCP/IP-based protocol for sending SCSI commands over IP networks. iSCSI emulates a high-performance local SCSI storage bus, enabling block-based storage devices on a server to appear as local devices on a client. As a storage area network (SAN) protocol, iSCSI extends SANs across local and wide area networks (LANs, WANs, and the Internet), providing location-independent data storage retrieval with distributed servers and arrays.
Table 5.1. iSCSI Component Terminology
| Term | Description |
|---|---|
initiator
| An iSCSI client, typically available as software. Hardware initiators are also available in the form of iSCSI Host Bus Adapters (HBAs). Initiators must have unique names (see IQN). |
target
| An iSCSI storage resource on an iSCSI server. A target provides one or more numbered block devices, commonly referred to as logical unit numbers (see LUN). Typically, a target provides one device and a server provides multiple targets. Targets must have unique names (see IQN). |
IQN
|
A unique worldwide name to identify initiators and targets. IQNs have the following format:
|
LUN
| A logical unit number that represents a block device provided by a target. Each target provides one or more LUNs. |
ACL
| An access control list that restricts access to LUNs based on an initiator's IQN. |
portal
| An IP address and port on a target or initiator to establish connections. Some iSCSI implementations use the terms portal and node interchangeably. |
TPG
| A target portal group that represents a complete configuration for a target, including portals, LUNs, and ACLs. While most targets use one TPG, advanced configurations might define multiple TPGs. |
The iSCSI protocol functions in a client-server configuration. The clients (initiators) send SCSI commands to servers (portals or nodes) that provide the clients with unformatted SCSI devices. These emulated devices appear identical to devices that are connected with physical SCSI or Fibre Channel cabling.
In Red Hat Enterprise Linux, iSCSI initiators are implemented in software; however, hardware initiators are also available. Hardware initiators can improve system performance by offloading Ethernet, TCP, and iSCSI processing to iSCSI Host Bus Adapters (HBAs).
Configuring the software iSCSI initiator requires installing the iscsi-initiator-utils package. This package includes the iscsi and iscsid services, and the /etc/iscsi/iscsid.conf and /etc/iscsi/initiatorname.iscsi configuration files.
iSCSI initiators require a unique iSCSI Qualified Name (IQN), with a default IQN provided in the /etc/iscsi/initiatorname.iscsi file. This file contains a randomly generated IQN with redhat.com as its domain name. However, administrators should change the IQN to their own domain and replace the randomly generated string with a specific name.
The /etc/iscsi/iscsid.conf file contains the default settings for iSCSI targets. These settings include iSCSI timeouts, retry parameters, and user names and passwords for authentication. Restart the iscsid service after changes to the /etc/iscsi/iscsid.conf file.
To discover targets, an iSCSI client must have network connectivity to the target server and be running the iscsi service. The iscsiadm utility, provided by the iscsi-initiator-utils package, is then used to discover, log in to, and list targets.
Note
These commands assume that targets are already configured on a remote server. iSCSI server configuration is outside the scope of this section.
Use iscsiadm for the following purposes:
To discover targets.
[root@host ~]# iscsiadm -m discovery -t st -p server.lab.example.com:3260
172.25.250.X:3260,1 iqn.2021-10.com.example.lab:target1To log in to targets.
[root@host ~]# iscsiadm -m node -T iqn.2021-10.com.example.lab:target1 -l
Logging in to [iface: default, target: iqn.2021-10.com.example.lab:target1, portal: 172.25.250.X,3260]
Login to [iface: default, target: iqn.2021-10.com.example.lab:target1, portal: 172.25.250.X,3260] successful.To list targets.
[root@host ~]# iscsiadm -m node
172.25.250.X:3260,1 iqn.2021-10.com.example.lab:target1When logged in to a target, the device appears locally on the client.
[root@host]#grep "Attached SCSI" /var/log/messagesOct 6 18:56:00 server kernel: sd 2:0:0:0: [sda] Attached SCSI disk [root@host]#lsblkNAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT sda 8:0 0 1G 0 disk ...output omitted...
During the discovery process, iscsiadm stores target information and settings in the /var/lib/etc/iscsi/nodes/ directory. These additional configuration files complement the default configurations in the /etc/iscsi/iscsid.conf file.
iSCSI uses ACLs to control which targets and LUNs initiators can access. Use Challenge-Handshake Authentication Protocol (CHAP) authentication to force initiators to provide a username and password before accessing LUNs. iSCSI ACLs are similar to Fibre Channel use of device worldwide numbers (WWNs) for soft zoning management restrictions. Although Fibre Channel switch-level compulsory port restriction (hard zoning) has no comparable iSCSI mechanism, Ethernet VLANs can provide similar isolation security.
By default, the iSCSI initiator in RHEL 8 is not configured with CHAP authentication. If password authentication is enabled and configured on the target, then matching authentication must be configured on the initiator. Authentication configuration settings are located in the /etc/iscsi/iscsid.conf file. For one-way authentication that verifies the initiator to the target server, use the username and password credentials. For two-way authentication that additionally verifies the target portal to the initiator, the username_in and password_in credentials are also required. In either case, the node.session.auth.authmethod value must be set to CHAP.
# Enable CHAP Authentication node.session.auth.authmethod = CHAP # One-way authentication: node.session.auth.username = <username> node.session.auth.password = <password> # Add for two-way authentication: node.session.auth.username_in = <username> node.session.auth.password_in = <password>
For no authentication, clear all credential values and comment out the node.session.auth lines.
iSCSI initiators rely on an IP network connection to reach iSCSI targets. Troubleshooting an iSCSI target discovery issue must begin with verifying network access. When networking is eliminated as a potential issue, investigate iSCSI access control and authentication issues next.
To ensure that connections are being made to the proper target host, use dig or a similar utility to verify that the domain name that iscsiadm requests correctly resolves to the target host's IP address.
[root@host ~]# dig server.lab.example.com
...output omitted...
;; ANSWER SECTION:
server.lab.example.com. 3600 IN A 172.25.250.X
...output omitted...When DNS is eliminated as a potential issue, examine whether configuration in the /etc/hosts and /etc/nsswitch.conf files on the initiator host is providing conflicting domain names.
If domain name resolution is working properly, then use ncat to test the connection to the target host's iSCSI port (3260 by default).
[root@host ~]# ncat -v target_server_ip 3260If the connection fails, then confirm that the target server is listening on the default iSCSI port and that firewalld is configured to allow iSCSI connections.
Confirm that the service is listening on port 3260.
[root@host ~]# ss -tln | grep 3260
LISTEN 0 256 0.0.0.0:3260 0.0.0.0:*Confirm that firewalld is configured to allow port 3260.
[root@host ~]# firewall-cmd --list-all | grep 3260
ports: 3260/tcpIf an initiator experiences an issue with logging in to an already discovered target, then the problem likely relates to access control or authentication. Access to iSCSI targets is granted via ACLs on the iSCSI server, which specify the names of initiators that are allowed access to specific LUNs. For a mismatch between the client's initiator name and the configured name on the server, a target login failure occurs. If the issue results from an incorrect initiator name on the client, then fix the name in the /etc/iscsi/initiatorname.iscsi file and restart the iscsid service to apply the change.
If the initiator name is correctly configured, then login failures can be attributed to an incorrect authentication configuration. To authenticate successfully, the initiator must be configured to use the authentication method that the target server requires. If the server is configured for CHAP authentication, then the initiator's CHAP configurations must be specified in /etc/iscsi/iscsid.conf.
To assess the cause for login failures, it can be useful to execute the login in debug mode with the -d option. Debug level can be set between 0 to 8, with level 8 being required to see authentication details.
[root@host ~]#iscsiadm -m node -T iqn.2021-10.com.example.lab:target1 -l -d8...output omitted...iscsiadm: updated 'node.session.auth.authmethod', 'None' => 'CHAP'...output omitted...
If the issue is due to an incorrect CHAP configuration on the client, then apply fixes in /etc/iscsi/iscsid.conf and restart the iscsid service.
The discovery process stores target node information and settings in the /var/lib/iscsi/nodes directory. Because the same target can exist on multiple portals, node records are stored for each portal. On discovery, a node record is written to /var/lib/iscsi/nodes and is used for subsequent logins.
When /etc/iscsi/iscsid.conf is changed after the initial login attempt, the login process continues with saved settings in /var/lib/iscsi/etc/nodes. To log in with newly configured settings, administrators can either modify existing settings under /var/lib/iscsi/nodes or remove all saved information from that directory.
Use iscsiadm to display existing settings for a target.
[root@host ~]# iscsiadm -m node -T iqn.2021-01.com.example.lab:target1
# BEGIN RECORD 6.2.0.873-30
node.name = iqn.2021-01.com.example.lab:target1
node.tpgt = 1
...output omitted...
node.conn.iscsi.HeaderDigest = None
node.conn[0].iscsi.IFMarker = No
node.conn.iscsi.OFMarker =+ NoTo modify existing settings, use the iscsiadm command with the -o update option. Additionally, use the -n option to specify the parameter to modify, and the -v option to specify the value for the parameter. This example disables CHAP authentication.
[root@host ~]# iscsiadm -m node -T iqn.2021-01.com.example.lab:target1 -o update -n node.session.auth.authmethod -v None [-p target_server[:port]]Alternatively, administrators can purge all node information from the cache. To purge existing node settings for a target, use the iscsiadm command with the -o delete option.
[root@host ~]# iscsiadm -m node -T iqn.2021-01.com.example.lab:iscsistorage -o delete [-p target_server[:port]]To purge settings for all known nodes, use the same command without specifying a target.
[root@host ~]# iscsiadm -m node -o delete [-p target_server[:port]]References
iscsiadm(8) man page Configuring an iSCSI Initiator
