How to Create a Block Storage iSCSI Gateway

This article explains how to create an iSCSI gateway on a Debian server to host block storage over iSCSI.

Terms used in this guide:

• Target: The server hosting the iSCSI gateway and Block Storage
• Initiator: The server using Block Storage over iSCSI
• IQN: iSCSI Qualified Name. This is a standard format for defining how iSCSI targets and initiators are identified.

For example, you could use a Vultr cloud server as the Target, and a Bare Metal server as the Initiator.

Best Practices

• We highly recommend using a CPU Optimized plan with at least one vCPU for each Block Storage volume you'll mount.
• For security, you should use a Vultr VPC for all iSCSI connections. Also, unlike a public network connection, iSCSI traffic over a VPC does not count against your bandwidth quota, saving you potential expense.

Install the Target Server

This guide uses Debian, but the steps are similar for any Linux distribution that supports Open-iSCSI.

1. Deploy a new Debian 11 server as the Target.

2. Create a block storage subscription and attach it to the Target server.

3. SSH to the Target server as root.

4. Install targetcli and open-iscsi

    # apt install targetcli-fb open-iscsi
   

5. Enable the iSCSI daemon and start it.

    # systemctl enable iscsid.service --now
   

6. Run targetcli to enter the command line interface for iSCSI configuration. The prompt changes to /> after the command is run.

    # targetcli
    />

7. Navigate to the Block Storage backstore.

    /> cd backstores/block
   

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

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

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

11. Set the ACLs to enable bi-directional CHAP authentication.

    • The Initiator name can be whatever you want it to be. This guide uses initiator as the example name.
    • You should use strong, randomly-generated usernames and passwords. This guide uses weak names and passwords as examples only.

    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
    

12. Change to the root directory, save your targetcli configuration, and then exit.

     /iscsi/iqn.20.../tpg1/portals> cd /
     /> saveconfig
     /> exit
    

13. Enable the targetclid service. This step is required to reload the configuration when the Target server restarts.

     # systemctl enable targetclid.service --now
    

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

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

Configure the Initiator

1. SSH to your Initiator server as root, which can be any APT or RPM-based server that supports open-iscsi.

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

3. Open /etc/iscsi/initiatorname.iscsi in a text editor.

    # nano /etc/iscsi/initiatorname.iscsi
   

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

5. Save and exit the file.

6. Open /etc/iscsi/iscsid.conf in a text editor.

    # nano /etc/iscsi/iscsid.conf
   

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

8. Restart the iscsid service to set the new configuration.

    # systemctl restart iscsid.service
   

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

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

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

More Information

To learn more about iSCSI and targetcli, see:

• The Linux SCSI Target Wiki
• iSCSI tools for Linux