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

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

Configuring the iSCSI Initiator

  1. Start YaST and launch Network Services > iSCSI Initiator.

  2. Switch to the Services tab.

  3. Under Service Start, specify how you want the iSCSI initiator 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 iscsi iscsid.

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

  5. Use either of the following methods to discover iSCSI targets on the network.

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 Section 13.0, iSNS for Linux.

  1. In YaST, select iSCSI Initiator, then select the Service tab.

  2. Specify the IP address of the iSNS server and port. The default port is 3205.

  3. Click OK to save and apply your changes.

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.

  1. In YaST, select iSCSI Initiator, then select the Discovered Targets tab.

  2. Click Discovery to open the iSCSI Initiator Discovery dialog.

  3. Enter the IP address and change the port if needed. The default port is 3260.

  4. If authentication is required, deselect No Authentication, then specify the credentials for Incoming or Outgoing authentication.

  5. Click Next to start the discovery and connect to the iSCSI target server.

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

  7. Click Next to finish the configuration.

    The target now appears in Connected Targets and the virtual iSCSI device is now available.

  8. Click OK to save and apply your changes.

  9. You can find the local device path for the iSCSI target device by using the lsscsi command.

Setting the Start-up Preference for iSCSI Target Devices

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

  2. Select the iSCSI target device that you want to manage.

  3. 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 Systems. Therefore it should not be used on these platforms, use Automatic instead.

  4. Click OK to save and apply your changes.

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

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