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 Cloud Infrastructure

Introduction

The following tutorial provides step-by-step procedures to configure an iSCSI target and initator on Oracle Cloud Infrastructure.

Objectives

To this lab, you:

Configure ol-server as an iSCSI target
Configure ol-client as an iSCSI initator

What Do You Need?

If you run the lab in your own environment, ensure the following:

Two fully patched systems with Oracle Linux installed
A minimum of two additional block devices

Note: When using the free lab environment, see Oracle Linux Lab Basics for connection and other usage instructions.

Configure a Security List Ingress Rule for the Virtual Cloud Network

Security lists control the traffic in and out of the various subnets associated with the VCN. When configuring iSCSI targets and initiators, you need to add an ingress rule allowing the instances access to the storage through TCP port 3260.

The required port is configured to the stateful ingress rules of the default security list for the Virtual Cloud Network (VCN).

From the server’s Instance details section of the Instance Information tab, click on the link beside Virtual cloud network to view the VCN details page.
Under Resources, click on Security Lists.
Click on the name of the default security list in the table.

Note: Under Resources, be certain to click Ingress Rules to display the current list of ingress rules.
Click Add Ingress Rules button.
In the Add Ingress Rules dialog, complete the following:
1. Leave Stateless box unchecked.
2. Source Type = CIDR
3. Source CIDR = 10.0.0.0/16
4. IP Protocol = TCP
5. Destination Port Range = 3260
Note: Carefully review your selections, and click Add Ingress Rules.
Verify you see port 3260 listed in the Ingress Rules list.

Configure (ol-server) as an iSCSI Server

In this practice you:

Enable the OCI Utilities
Install and enable the targetcli software package
Explore the targetcli command-line interface

Open a terminal and connect to your server (ol-server) instance.
Enable the OCI Utilites service.

The OCI Utilities come preinstalled on Oracle Linux instances. These utilities consist of a service daemon and related command line tools to help manage block volumes.

Refer to Oracle Cloud Infrastructure Documentation for more information on the additional features and tools provided by the OCI Utilities.
1. Use the lsblk command to view the available attached block volumes.
```
sudo lsblk
```
  The output should display sdb, sdc, and sdd block devies.
```
NAME               MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
sda                  8:0    0 46.6G  0 disk 
|-sda1               8:1    0  100M  0 part /boot/efi
|-sda2               8:2    0    1G  0 part /boot
`-sda3               8:3    0 45.5G  0 part 
  |-ocivolume-root   252:0  0 35.5G  0 lvm  /
  `-ocivolume-oled   252:1  0   10G  0 lvm  /var/oled
sdb                  8:16   0   50G  0 disk 
sdc                  8:32   0   50G  0 disk 
sdd                  8:48   0   50G  0 disk
```
2. If the above block devices do not appear, use the systemctl command to enable and start the ocid.service.
```
sudo systemctl enable ocid.service
```
```
sudo systemctl start ocid.service
```
3. Rerun the lsblk command to verify the block volumes are available.
Install and enable the targetcli software package.

The targetcli utility is the administration shell for creating, editing, and viewing the configuration of the kernel’s target subsystem. You execute targetcli to enter the configuration shell.
1. Verify targetcli package availablity.
```
sudo dnf list targetcli
```
  If the package is already installed, the output lists the package under Installed Packages, as follows:
```
Last metadata expiration check: 0:01:19 ago on Mon Jan 31 16:29:01 2022.
**Installed Packages**
targetcli.noarch                        2.1.53-2.el8                       @ol8_appstream
Available Packages
targetcli.src                           2.1.53-2.el8                        ol8_appstream 
[oracle@ol-server ~]$
```
2. If targetcli is installed, continue to the next step; otherwise, use the dnf command to install the targetcli software package.
```
sudo dnf -y install targetcli
```
3. Use the systemctl command to enable and start the target service.
  
  To enable:
```
sudo systemctl enable target.service
```
  To start:
```
sudo systemctl start target.service
```
Explore the targetcli command-line interface.
1. Run the targetcli command to access the command-line interface.
```
sudo targetcli
```
  The targetcli interface prompt displays, as shown. You enter commands at this prompt.
```
targetcli shell version 2.1.53
Copyright 2011-2013 by Datera, Inc and others. 
For help on commands, type 'help'.

/>
```
2. Use the help command to view 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 <command>.
3. Use the get command to view the available configuration groups.
```
get
```
  The only configuration group is global.
4. Use the get global command to view the configuration parameters.
```
get global
```
5. Use the ls command to display the object hierarchy.
```
ls
```
  The inital object hierarchy is empty.
6. Use the help create command to 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. Use the command cd /backstores/block to change to the /backstores/block directory.
```
cd /backstores/block
```
  Note: Tab completion is available in the shell.
8. Use the help create command to view the syntax of the create command.
  
  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 that 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, use the create command to create the following named backstore storage objects:
  - /dev/sdb - LUN_1
  - /dev/sdc - LUN_2
```
create name=LUN_1 dev=/dev/sdb
```
```
create name=LUN_2 dev=/dev/sdc
```
2. Use the ls command to view the new block backstore storage objects, as shown:
Create an iSCSI target.
1. Use the cd command to change to the /iscsi directory.
```
cd /iscsi
```
2. Use the help create command to get help on the create command.
```
help create
```
  The create command usage is different when issuing the command from the /iscsi directory.
  
  Note: The information on assigning WWNs (World Wide Nubmber) for the targets.
3. At the /iscsi> prompt, use the create command to create an IQN (iSCSI Qualified Name).
```
create
```
  The command returns information similar to the following:
```
/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 addtion, the command created a Target Portal Group (TPG): TPG 1.
4. Use the ls command to view the TPG hierarchy.
Add LUNs to the TPG
1. Use the cd command to change to the <IQN_OF_TPG1>/tpg1/luns directory and add LUNs to the target portal group. Remember, tab completion is available.
  
  Sample text:
```
cd iqn.2003-01.org.linux-iscsi.ol-server.x8664:sn.b87e2e47262c/tpg1/luns
```
2. Use the create help command for a description of the syntax.
  
  Note: That the create command in this directory creates a new LUN in the TPG.
3. Use the create command to create two LUNS as follows:
  - Create lun1 for /backstores/block/LUN_1
  - Create lun2 for /backstores/block/LUN_2
```
create /backstores/block/LUN_1 lun1
```
```
create /backstores/block/LUN_2 lun2
```
4. Use the ls command to view the LUNs.
Identify the network portal for TPG 1.

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 an iSCSI session is run.
1. Use the cd command to change to the portals subdirectory.
```
cd ../portals/
```
2. Use the ls command to display the default information.
```
/iscsi/iqn.20.../tpg1/portals> ls
o- portals ........................................................ [Portals: 1]
  o- 0.0.0.0:3260 ......................................................... [OK]
/iscsi/iqn.20.../tpg1/portals>
```
  A default portal was created when the IQN was created. 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 initator.

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

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) - Man Pages for more information on access control and authentication.
1. Use the cd command to change to the tpg1 directory.
```
cd ../
```
2. Disabled authenticaiton 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 http://www.linux-iscsi.org/Doc/LIO%20Admin%20Manual.pdf.
4. Enable dynamically generated initiator node ACLs at login time.
```
set attribute generate_node_acls=1
```
5. Enable the caching dynamically generated initiator node ACLs.
```
set attribute cache_dynamic_acls=1
```
6. Use the cd / command to change to the root directory.
7. Use the ls command to view the hierarchy.
8. Use saveconfig to save the configuration, and then exit to exit targetcli.
```
saveconfig
```
```
exit
```
  Note: The configuration is automatically saved to the /etc/target/saveconfig.json file. The /etc/target/saveconfig.json file stores the most recently saved configuration.
Configure the firewall to trust TCP port 3260.
1. Use the firewalld-cmd command to list the current configuration.
```
sudo firewall-cmd --list-all
```
2. Use the firewall-cmd command to open port 3260 in the firewalld configuration.
```
sudo firewall-cmd --permanent --add-port=3260/tcp
```
3. Use the firewall-cmd to reload the firewalld configuration.
```
sudo firewall-cmd --reload
```
4. Rerun the command firewall-cmd --list-all to verify port 3260 was added.

Configure (ol-client) as an iSCSI Initiator

An iSCSI client functions as an iSCSI initiator to access target devices on an iSCSI server. An iSCSI initiator sends iSCSI commands over an IP network.

This this practice, you:

Configure and start the iscsid service
Discover iSCSI targets by using the SendTargets discovery method
Query the Open-iSCSI persistent database
Observe the settings in the iSCSI initiator configuration file
Establish a TCP session between the target and the initiator

Configure and start the iscsid package.
1. Open a terminal and connect to your (ol-client) instance.
2. Verify iscsi-initiator-utils package availablity.
```
sudo dnf list iscsi-init*
```
  In this example, the output shows the package is already installed.
3. Use the command dnf install to install the package if necessary.
```
sudo dnf install -y iscsi-initiator-utils
```
4. Edit /etc/iscsi/initiatorname.iscsi and replace InitiatorName with the initiator name you configured on ol-server. For example, iqn.2003-01.org.linux-iscsi.ol-server.x8664:sn.b87e2e47262c
```
sudo vim /etc/iscsi/initiatorname.iscsi
```
  Sample command text:
```
InitiatorName=iqn.2003-01.org.linux-iscsi.ol-server.x8664:sn.b87e2e47262c
```
5. Use the systemctl command to enable and start the iscsid service.
```
sudo systemctl enable iscsid.service
```
```
sudo systemctl start iscsid.service
```
Discover the iSCSI target and explore the iSCSI persistent database.
1. Use the iscsiadm command to discover iSCSI targets by using the SendTargets discovery method. You specify the private IP address (portal IP of 10.0.0.150) from ol-server.
```
sudo iscsiadm -m discovery -t st -p 10.0.0.150
```
2. View the nodes and send_targets tables in the Open-iSCSI persistent database, /var/lib/iscsi.
```
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 contains the portal address and listening port of the target.
3. Use the iscsiadm command to query the send_targets table in the persistent database.
```
sudo iscsiadm -m discoverydb -t st -p 10.0.0.150
```
  Much of the information in the database is derived 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, use the fdisk command to display the current devices in /dev.
```
sudo fdisk -l /dev/sd*
```
  This output only lists three sda disk devices.
3. Use the iscsiadm command to log in and establish a session.
```
sudo iscsiadm -m node -l &
```
  Press Enter to return to the prompt.
4. Rerun the fdisk -l command to view the current devices.
  
  In addition to the three /sda disks, the output now lists the /dev/sdb and /dev/sdc disks.
5. Use the iscsiadm command to view active sessions with <printlevel> 3 to view addtional detail on the session.
```
sudo iscsiadm -m session -P 3
```
Test the usability of the iSCSI device.
1. Create a 1G partition on /dev/sdb using the fdisk command with the following parameters:
  - Command prompt: n for new
  - Primary partition: p or ENTER
  - Partition number: 1 or ENTER
  - First sector: 2048 or ENTER
  - Last sector: +1G
  - Command prompt: w to save
```
sudo fdisk /dev/sdb
```
2. Run the command fdisk -l to 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 using the mkdir command.
```
sudo mkdir /iscsi_dev
```
5. Use the mount command to mount the device to your mountpoint with the _netdev mount option.
```
sudo mount /dev/sdb1 -o _netdev /iscsi_dev/
```
6. Display the mounted file system.
```
sudo mount | grep iscsi
```
7. Copy files into the mounted file system, for example:
```
sudo cp /boot/vmlinuz* /iscsi_dev/
```
8. List the contents of the /iscsi_dev directory to validate the configuration.

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 Cloud Infrastructure

F52755-05

August 2024

Oracle and/or its affiliates.