Author: Evan Burkey
Last Updated: Wed, May 18, 2022This article explains how to create an iSCSI gateway on a Debian server to host block storage over iSCSI.
Terms used in this guide:
For example, you could use a Vultr cloud server as the Target, and a Bare Metal server as the Initiator.
This guide uses Debian, but the steps are similar for any Linux distribution that supports Open-iSCSI.
Install targetcli
and open-iscsi
# apt install targetcli-fb open-iscsi
Enable the iSCSI daemon and start it.
# systemctl enable iscsid.service --now
Run targetcli
to enter the command line interface for iSCSI configuration. The prompt changes to />
after the command is run.
# targetcli
/>
Navigate to the Block Storage backstore.
/> cd backstores/block
For each mounted Block Storage volume, create a backstore. Here is an example that creates one backstore for a subscription at /dev/vdb
, named vdb
.
/backstores/block> create vdb /dev/vdb
Create the Target IQN. The IQN name format is iqn.YEAR-MONTH.domain:targetname
. The domain is reversed as a convention, so a domain of example.com
is expressed as com.example
. The target name can be whatever you want it to be. This example uses target
.
/backstores/block> cd /iscsi
/iscsi> create iqn.2022-05.com.example:target
Create a LUN mapping to the block device.
/iscsi> cd iqn.2022-05.com.example:target/tpg1/luns
/iscsi/iqn.20..et/tpg1/luns> create /backstores/block/vdb
Set the ACLs to enable bi-directional CHAP authentication.
initiator
as the example name.The example Initiator username is initiator_user
and the password is initiator_password
. The example Target username is target_user
and the password is target_password
.
/iscsi/iqn.20..et/tpg1/luns> cd ../acls
/iscsi/iqn.20..et/tpg1/acls> create iqn.2022-05.com.example:initiator
/iscsi/iqn.20..et/tpg1/acls> cd iqn.2022-05.com.example:initiator/
/iscsi/iqn.20..om:initiator> set auth userid=initiator_user
/iscsi/iqn.20..om:initiator> set auth password=initiator_password
/iscsi/iqn.20..om:initiator> set auth mutual_userid=target_user
/iscsi/iqn.20..om:initiator> set auth mutual_password=target_password
Change to the root directory, save your targetcli
configuration, and then exit.
/iscsi/iqn.20.../tpg1/portals> cd /
/> saveconfig
/> exit
Enable the targetclid
service. This step is required to reload the configuration when the Target server restarts.
# systemctl enable targetclid.service --now
Verify the iSCSI service is listening on port 3260 with the following command. IP address 0.0.0.0 means the service is listening on all interfaces.
# ss -napt | grep 3260
LISTEN 0 256 0.0.0.0:3260 0.0.0.0:*
Configure the firewall to open port 3260 to the Initiator. Debian 11 uses ufw
as its default firewall. Substitute the Initiator's IP address for 10.10.10.123 used in this example. We strongly recommend you only enable a private network interface that is connected to a Vultr VPC.
# ufw allow from 10.10.10.123 to any port 3260
open-iscsi
.On the Initiator, install open-iscsi
and start the iscsid
service.
APT-based Linux
# apt install -y open-iscsi
# systemctl enable iscsid.service --now
RPM-based Linux
# yum -y install iscsi-initiator-utils
# systemctl enable iscsid.service --now
Open /etc/iscsi/initiatorname.iscsi
in a text editor.
# nano /etc/iscsi/initiatorname.iscsi
Set the iSCSI Initiator name to match the name you set on the iSCSI Target server. For example, this guide uses iqn.2022-05.com.example:initiator
.
InitiatorName=iqn.2022-05.com.example:initiator
Save and exit the file.
Open /etc/iscsi/iscsid.conf
in a text editor.
# nano /etc/iscsi/iscsid.conf
Edit the file as shown to configure authentication.
# Uncomment the following line to enable CHAP
node.session.auth.authmethod = CHAP
# Uncomment the following line to enable strong authentication algorithms
node.session.auth.chap_algs = SHA3-256,SHA256,SHA1,MD5
# Uncomment and specify the username and password you set on the target server
node.session.auth.username = initiator_user
node.session.auth.password = initiator_password
# Uncomment and specify the mutual username and password you set earlier
node.session.auth.username_in = target_user
node.session.auth.password_in = target_password
# Optional: Setup automatic reconnect after a reboot by changing `node.startup` from `manual` to `automatic`
node.startup = automatic
Restart the iscsid
service to set the new configuration.
# systemctl restart iscsid.service
Discover the target on the Initiator.
# iscsiadm -m discovery -t st -p 10.10.10.123
10.10.10.123:3260,1 iqn.2022-05.com.example:target
Log in to the Target server. This is only required once; the iscsid.service
you created earlier will restart the connection when the machine is rebooted.
# iscsiadm -m node --login
Logging in to [iface: default, target: iqn.2022-05.com.example:target, portal: 10.10.10.123,3260]
Login to [iface: default, target: iqn.2022-05.com.example:target, portal: 10.10.10.123,3260] successful.
The disk should now be mounted over iSCSI on the Initiator. You can check this with lsblk
. In this example, sda
is the target.
# lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sda 8:0 0 100G 0 disk
sr0 11:0 1 1024M 0 rom
vda 254:0 0 55G 0 disk
ââvda1 254:1 0 55G 0 part /
The Block Storage volume is now available to the Initiator over iSCSI, and you can mount it to the Linux filesystem like any other block device. For more information, see the "Mount Block Storage" topic.
To learn more about iSCSI and targetcli
, see: