How to Set Up an Iscsi Target and Initiator with Chap Authentication on Ubuntu Server

ByAkensai

Learning how to set up an iSCSI target and initiator with CHAP authentication on Ubuntu Server is a valuable skill for any Linux administrator. iSCSI (Internet Small Computer Systems Interface) lets you share block storage over a standard TCP/IP network. This means one server can expose a storage device, and another server can use it as if it were a locally attached disk. CHAP (Challenge Handshake Authentication Protocol) adds a layer of security by requiring credentials before the initiator can connect. In this tutorial, you will configure both sides of the connection on Ubuntu Server. You will install and configure the target (the server sharing storage), set up the initiator (the client connecting to it), and lock it all down with CHAP authentication. By the end, you will have a working, authenticated iSCSI connection ready for production use.

Prerequisites for Setting Up an iSCSI Target and Initiator

Before you start, make sure you have the following in place.

Hardware and software requirements:

  • Two Ubuntu Server machines (20.04 or 22.04 LTS recommended)
  • One machine acts as the target (storage server)
  • One machine acts as the initiator (client)
  • Both machines must be on the same network and able to ping each other
  • Root or sudo access on both machines
  • A spare disk or partition on the target machine (e.g., /dev/sdb)

Assumed knowledge: You should be comfortable using the Linux terminal, editing files with a text editor like nano, and managing services with systemctl.

Estimated time: 30–45 minutes.

Make note of both IP addresses before you begin. In this tutorial, the target IP is 192.168.1.10 and the initiator IP is 192.168.1.20. Replace these with your actual values throughout.

For background on iSCSI concepts, the Ubuntu Server documentation is a great starting point.

How to Set Up an iSCSI Target and Initiator: Step-by-Step Guide

You might also find this useful: How to Set Up Nginx Reverse Proxy with Docker Containers for Multiple Applications

Follow these steps carefully. Complete the target configuration first, then move to the initiator.

Step 1: Install the iSCSI target software

On the target machine, install the tgt package.

sudo apt update
sudo apt install tgt -y

Once installed, start and enable the service.

sudo systemctl start tgt
sudo systemctl enable tgt

Step 2: Create a storage backing file or use a block device

You can use a raw disk like /dev/sdb or create a file-backed store. This example creates a 10GB file.

sudo mkdir -p /var/lib/iscsi-storage
sudo dd if=/dev/zero of=/var/lib/iscsi-storage/disk01.img bs=1M count=10240

This creates a 10GB image file at /var/lib/iscsi-storage/disk01.img.

Step 3: Configure the iSCSI target

Create a new target configuration file.

sudo nano /etc/tgt/conf.d/iscsi-target.conf

Add the following content. Replace the IQN name if you prefer a custom identifier.

<target iqn.2024-01.com.akensai:storage.target01>
    backing-store /var/lib/iscsi-storage/disk01.img
    initiator-address 192.168.1.20
    incominguser iscsi-user StrongPassword123
    outgoinguser iscsi-target StrongPassword456
</target>

Here, incominguser sets the CHAP credentials the initiator must provide. The outgoinguser sets mutual CHAP credentials. Save and close the file.

Restart the target service to apply changes.

sudo systemctl restart tgt

Verify the target is running correctly.

sudo tgtadm --mode target --op show

You should see your target listed with the LUN (Logical Unit Number) attached.

Step 4: Install the iSCSI initiator software

Switch to the initiator machine now. Install the open-iscsi package.

sudo apt update
sudo apt install open-iscsi -y

Start and enable the service.

sudo systemctl start iscsid
sudo systemctl enable iscsid

Step 5: Configure CHAP credentials on the initiator

Edit the main iscsid configuration file.

sudo nano /etc/iscsi/iscsid.conf

Find and update the following lines. Uncomment them if they are commented out.

node.session.auth.authmethod = CHAP
node.session.auth.username = iscsi-user
node.session.auth.password = StrongPassword123
node.session.auth.username_in = iscsi-target
node.session.auth.password_in = StrongPassword456

These values must match exactly what you set on the target. Save the file.

Step 6: Discover and log in to the iSCSI target

Run a discovery scan against the target IP address.

sudo iscsiadm -m discovery -t sendtargets -p 192.168.1.10

You should see output like this.

192.168.1.10:3260,1 iqn.2024-01.com.akensai:storage.target01

Now log in to the target.

sudo iscsiadm -m node --login

Step 7: Verify the connection and format the disk

Check that the new disk appeared on the initiator.

lsblk

You should see a new device, likely /dev/sdb. Format it with ext4.

sudo mkfs.ext4 /dev/sdb

Mount it to a directory.

sudo mkdir /mnt/iscsi-disk
sudo mount /dev/sdb /mnt/iscsi-disk

Your iSCSI disk is now mounted and ready to use. To make the mount persistent across reboots, add it to /etc/fstab. You can also configure automatic iSCSI login at boot by running sudo iscsiadm -m node -o update -n node.startup -v automatic.

Troubleshooting Common iSCSI and CHAP Authentication Issues

Even with careful setup, things can go wrong. Here are the most common problems and how to fix them.

Problem: Discovery returns no targets
Check that the tgt service is running on the target machine. Also confirm that port 3260 is open in your firewall.

sudo ufw allow 3260/tcp

Problem: Login fails with authentication error
Double-check that the CHAP usernames and passwords in /etc/iscsi/iscsid.conf match exactly what is in the target config. Passwords are case-sensitive. Restart both services after any changes.

sudo systemctl restart tgt       # on target
sudo systemctl restart iscsid    # on initiator

Problem: Disk doesn’t appear after login
Run dmesg | tail -20 on the initiator to check for kernel messages. You may need to rescan for new block devices.

sudo iscsiadm -m session --rescan

Problem: Connection drops after reboot
Make sure you set the node startup to automatic as shown in Step 7. Also verify the open-iscsi service is enabled.

sudo systemctl enable open-iscsi

For more detailed troubleshooting, the iscsiadm man page covers every available option and flag.

Conclusion

You now know how to set up an iSCSI target and initiator with CHAP authentication on Ubuntu Server from start to finish. You installed and configured the tgt target software, created a backing store, set up CHAP credentials on both sides, and successfully connected the initiator. The result is a secure, network-attached block storage connection you can use for virtual machines, backups, or shared data. From here, you might explore multipath I/O for redundancy, or look into setting up LVM on top of your iSCSI volume for flexible storage management. This setup scales well and gives you a solid foundation for more advanced storage configurations on your Ubuntu infrastructure.

Similar Posts