Note:

• This tutorial is available in an Oracle-provided free lab environment.
• It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.

Configure an iSCSI Target and Initiator on Oracle Linux

Introduction

Oracle Linux uses the Linux-IO Target (LIO) to provide the block-storage SCSI target for FCoE, iSCSI, and Mellanox InfiniBand (iSER and SRP). For iSCSI (Internet Small Computer System Interface), an iSCSI target is a server, storage array, or device that hosts storage resources and provides them as SCSI block devices (LUNs) accessible over an IP network to iSCSI initiators.

An iSCSI initiator is a client device that uses the iSCSI protocol to send SCSI commands to an iSCSI target over an IP network, essentially acting as a client in a storage network.

Objectives

In this tutorial, you’ll learn how to:

• Configure an iSCSI target
• Configure an iSCSI Initiator

Prerequisites

• Two Oracle Linux systems running the UEK kernel

• Each system should have Oracle Linux installed and configured with:

  • a non-root user with sudo permissions

• Attach two 50GB block volumes to one instance as read-write for use as iSCSI block devices

• OCI Ingress Rules allowing TCP and UDP traffic on port 3260. Security lists control the traffic in and out of the various subnets associated with the VCN.

Deploy Oracle Linux

Note: If running in your own tenancy, read the linux-virt-labs GitHub project README.md and complete the prerequisites before deploying the lab environment.

1. Open a terminal on the Luna Desktop.

2. Clone the linux-virt-labs GitHub project.

   git clone https://github.com/oracle-devrel/linux-virt-labs.git
   

3. Change into the working directory.

   cd linux-virt-labs/ol
   

4. Install the required collections.

   ansible-galaxy collection install -r requirements.yml
   

5. Update the Oracle Linux instance configuration.

   cat << EOF | tee instances.yml > /dev/null
   compute_instances:
     1:
       instance_name: "ol-sys0"
       type: "server"
       add_bv: true
     2:
       instance_name: "ol-sys1"
       type: "server"
   passwordless_ssh: true
   block_count: 2
   use_iscsi: true
   EOF
   

6. Deploy the lab environment.

   ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e "@instances.yml" 
   

   The free lab environment requires the extra variable local_python_interpreter, which sets ansible_python_interpreter for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules.

   The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command.

   Important: Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of Oracle Linux is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab.

Install the Target CLI

This package is an administration shell for configuring iSCSI, FCoE, and other SCSI targets using the TCM/LIO kernel target subsystem. TCM is another name for LIO, which is an in-kernel iSCSI target or server.

1. Open a terminal and connect using SSH to the ol-sys0 instance.

   ssh oracle@<ip_address_of_instance>
   

2. List the attached block volumes.

   lsblk
   

   The sda device is the boot device, while sdb and above are additional block volumes attached to the Oracle Linux instance.

3. Install the iSCSI administrative shell package.

   sudo dnf install -y targetcli
   

4. Enable and start the target service.

   sudo systemctl enable --now target.service
   

Configure an iSCSI Target

Explore the CLI

1. Access the target command-line interface.

   sudo targetcli
   

   The terminal shows the targetcli prompt, which you can use to enter commands.

   Example Output:

   targetcli shell version 2.1.53
   Copyright 2011-2013 by Datera, Inc and others. 
   For help on commands, type 'help'.
   
   />
   

2. Show the available commands.

   help
   

   The available commands depend on the current path or target path in which you want to run a command. Each path contains a different set of commands. You can get command-specific help by entering help followed by the command.

3. View the available configuration groups.

   get
   

   The only configuration group is global.

4. View the configuration parameters.

   get global
   

5. Display the object hierarchy.

   ls
   

   The initial object hierarchy is empty.

6. View the syntax of the create command.

   help create
   

   The output returns the following message, “Cannot find help topic create”. The create command is not available from the current root-level directory.

7. Change to the /backstores/block directory.

   cd /backstores/block
   

   Note: Tab completion is available in the shell.

8. Retry viewing the syntax of the create command.

   help create
   

   This time, the output displays the syntax of the create command.

   SYNTAX
   ======
   create name dev [readonly] [wwn] 
   
   
   DESCRIPTION
   ===========
   
   Creates an Block Storage object. "dev" is the path to the TYPE_DISK block device to use.
   

Create Backstore Block Storage Objects

Backstores are the different kinds of local storage resources the kernel target uses to “back” the iSCSI devices it exports to client systems. The mappings to local storage resources that each backstore creates are called storage objects.

1. At the /backstores/block> prompt, create two backstore storage objects.

   create name=LUN_1 dev=/dev/sdb
   

   create name=LUN_2 dev=/dev/sdc
   

2. List the new block backstore storage objects.

   ls
   

Create an iSCSI Target

1. Change to the /iscsi directory.

   cd /iscsi
   

2. Get help on the create command.

   help create
   

   The create command usage differs when you issue the command from the /iscsi directory.

   Note: The information on assigning WWNs (World Wide Nubmber) for the targets.

3. Create an IQN (iSCSI Qualified Name).

   create
   

   Example Output:

   /iscsi> create
   Created target iqn.2003-01.org.linux-iscsi.ol-server.x8664:sn.b87e2e47262c.
   Created TPG 1.
   Global pref auto_add_default_portal=true
   Created default portal listening on all IPs (0.0.0.0), port 3260.
   /iscsi>
   

   Note: In this example, the command created an IQN of iqn.2003-01.org.linux-iscsi.ol-server.x8664 with a target name of sn.b87e2e47262c. In addition, the command created a Target Portal Group (TPG) of TPG 1.

4. List the TPG hierarchy.

   ls
   

Add LUNs to the Target Portal Group

1. Use tab completion to change to the LUNs directory and add LUNs to the target portal group.

   Start typing iqn, then press TAB. Then type tpg1/luns and press Enter.

   Example Output:

   cd iqn.2003-01.org.linux-iscsi.ol-sys0.x8664:sn.b87e2e47262c/tpg1/luns
   

2. Create two LUNs.

   create /backstores/block/LUN_1 lun1
   

   create /backstores/block/LUN_2 lun2
   

3. List the LUNs.

   ls
   

Identify the TPG Network Portal

In a TPG, a network portal is identified by its IP address and listening TCP port. The network portal opens a network path within an iSCSI node over which it runs an iSCSI session.

1. Change to the portals subdirectory.

   cd ../portals/
   

2. Display the default portal information.

   ls
   

   When creating an IQN, it makes a default portal. The default portal IP of 0.0.0.0:3260 allows the iSCSI server to listen on all IPv4 addresses on TCP port 3260. If you ever want to change or add another address, you must delete the current portal address before creating another one.

Configure Access Rights for the Initiator

iSCSI supports authentication using the CHAP protocol. CHAP, or Challenge-Handshake Authentication Protocol, uses a username and password. Initiators might require valid authentication credentials for the target, and the target, in return, might require valid credentials for the initiator. You can set the authentication at the TPG level or per-ACL.

For this tutorial, you use set attribute commands to change this behavior by modifying the following parameter settings at the TPG level. Refer to the targetcli (8) manual pages for more access control and authentication information.

1. Change to the tpg1 directory.

   cd ../
   

2. Disable authentication by clearing the TPG authentication attribute.

   set attribute authentication=0
   

3. Disable write protection for LUNs exported.

   set attribute demo_mode_write_protect=0
   

   Caution The demonstration mode is inherently insecure. For information about configuring secure authentication modes, see the iscsiadm(8) and iscsid(8) manual pages or https://docs.kernel.org/target/tcmu-design.html.

4. Enable dynamically generated initiator node ACLs at login time.

   set attribute generate_node_acls=1
   

5. Enable the caching of dynamically generated initiator node ACLs.

   set attribute cache_dynamic_acls=1
   

Save the Configuration

1. Change to the root directory.

   cd /
   

2. View the hierarchy.

   ls
   

3. Save the configuration.

   saveconfig
   

4. Exit the CLI.

   exit
   

   Note: Exiting the shell saves the configuration automatically to the /etc/target/saveconfig.json file. The /etc/target/saveconfig.json file stores the most recently saved configuration.

Configure the Oracle Linux Firewall

1. List the current configuration.

   sudo firewall-cmd --list-all
   

2. Open port 3260 in the firewall configuration.

   sudo firewall-cmd --permanent --add-port=3260/tcp
   

3. Reload the firewall configuration.

   sudo firewall-cmd --reload
   

4. Verify the addition of the port.

   sudo firewall-cmd --list-all
   

5. Disconnect from the ol-sys0 instance.

   exit
   

Install the iSCSI Connection Daemon

1. Open a terminal and connect using SSH to the ol-sys1 instance.

   ssh oracle@<ip_address_of_instance>
   

2. Install the iSCSI daemon and utilities package.

   sudo dnf install -y iscsi-initiator-utils
   

3. Get the iSCSI target WWN from the ol-sys0 host and assign the value to a variable.

   WWN=$(ssh ol-sys0 "sudo cat /etc/target/saveconfig.json | jq -r '.targets[0].wwn'")
   

4. Edit /etc/iscsi/initiatorname.iscsi and replace InitiatorName with the initiator name (WWN from ol-sys0).

   sudo sed -i "/InitiatorName=/ s/=.*/=$WWN/" /etc/iscsi/initiatorname.iscsi
   

5. Enable and start the iSCSI daemon service.

   sudo systemctl enable --now iscsid.service
   

Configure an iSCSI Initiator

Discover the iSCSI Target and Explore the iSCSI Persistent Database

1. Discover iSCSI targets by using the SendTargets discovery method.

   You specify the private IP address of the portal IP from ol-sys0, which we gather over SSH.

   sudo iscsiadm -m discovery -t st -p $(ssh ol-sys0 hostname -i)
   

2. View the nodes and send_targets tables in the Open-iSCSI persistent database.

   ls /var/lib/iscsi/nodes/
   

   ls /var/lib/iscsi/send_targets/
   

   The nodes file contains the IQN of the iSCSI target, and the send_targets files contain the target’s portal address and listening port.

3. Query the send_targets table in the persistent database.

   sudo iscsiadm -m discoverydb -t st -p $(ssh ol-sys0 hostname -i)
   

   The database derives much of its information from the settings in the iSCSI initiator configuration file, /etc/iscsi/iscsid.conf.

Establish a TCP Session Between the iSCSI Target and the Initiator

1. Use the iscsiadm command to view active sessions.

   sudo iscsiadm -m session
   

   iSCSI target LUNs are not available until you log in. Logging in establishes an active session.

2. To demonstrate, display the current devices in /dev.

   sudo fdisk -l /dev/sd*
   

   This output only lists three sda disk devices.

3. Log in and establish a session.

   sudo iscsiadm -m node -l &
   

   Press Enter to return to the prompt.

4. Rerun the command to display the current list of devices.

   sudo fdisk -l /dev/sd*
   

   The output now shows /dev/sdb and /dev/sdc in addition to the three /sda disks.

5. View the active sessions with <printlevel> 3 to view additional details on the session.

   sudo iscsiadm -m session -P 3
   

Test the Usability of the iSCSI Device.

1. Create a 1G partition on /dev/sdb.

   sudo sfdisk /dev/sdb << EOF
   start= 2048, size= 1G
   EOF
   

2. View the /dev/sdb* devices.

   sudo fdisk -l /dev/sdb*
   

   The output lists the /dev/sdb1 disk device.

3. Create an ext4 file system on /dev/sdb1.

   sudo mkfs -t ext4 /dev/sdb1
   

4. Create a mountpoint directory.

   sudo mkdir /iscsi_dev
   

5. Mount the device to your mount point with the _netdev mount option.

   sudo mount /dev/sdb1 -o _netdev /iscsi_dev/
   

6. Display the mounted file system.

   sudo mount | grep iscsi
   

7. Create files in the mounted file system.

   for i in {1..5};
   do
     sudo dd if=/dev/urandom of=/iscsi_dev/file${i} bs=1M count=1;
   done
   

8. List the contents of the /iscsi_dev directory to validate the configuration.

   sudo ls -al /iscsi_dev
   

Next Steps

This tutorial introduced you to using iSCSI targets and initiators and the benefits of using iSCSI storage. Check out the Oracle Linux documentation to learn more about iSCSI and find additional learning opportunities at the Oracle Linux Training Station.

Related Links

• Oracle Linux Documentation
• Working With Linux I-O Storage
• Oracle Learning Library
• Oracle Linux Training Station

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

---

Title and Copyright Information

<

Configure an iSCSI Target and Initiator on Oracle Linux

F52755-06

Copyright ©2022, Oracle and/or its affiliates.