In our previous blog, we explored how to connect NFS storage and how file-level sharing fits into out lab environment. Today, we’re shifting gears to another powerful storage protocol available in TrueNAS Scale: iSCSI. While NFS is great for file-level sharing, iSCSI operates at the block level, making it a favorite for those looking to attach storage to a Linux VM that feels like a local physical disk.
We’ll start by exploring the "why" and "how" of iSCSI architecture, then move into a step-by-step Command Reference Guide to get your systems connected.
Block Storage vs File Storage
With NFS or SMB, you are working with file-level storage. You connect to a shared location and interact with files directly. iSCSI works differently. It presents raw storage blocks over the network. Once a system connects to it, that storage shows up as if it were a physical disk attached to the machine.
At that point, the system takes over completely. It decides how to partition it, how to format it, and how to use it. That shift is important. You are no longer just accessing storage. You are being handed a blank disk and told to do whatever you want with it.
Security and Identity: IQNs and CHAP
Because iSCSI presents raw blocks of data, security is handled differently than standard user permissions.
- IQN (iSCSI Qualified Name): Every client has a unique identity called an IQN. Instead of authenticating a "user," the storage server (the "Target") decides which specific machines are allowed to see the disk based on these names.
- Chap Authentication: To add a layer of security, we can use Chap. This is essentially a handshake where the client provides a secret (password) to the server. You can even set up "Mutual Chap," where the server also proves its identity to the client, ensuring a fully trusted connection.
The Role of the Client
It is important to remember that once the connection is established, the client "owns" the file system. TrueNAS simply presents the blocks. From that point on, the client is responsible for everything. It formats the disk, mounts it, and decides how it is used. This is very different from NFS or SMB, and it is important to understand that difference before moving forward.
Connecting from Linux
When you connect from a Linux system, the process is very hands-on, and honestly, that is a good thing. You install the iSCSI tools, discover the available targets, authenticate if needed, and then connect. Once the connection is made, the storage appears as a new disk on the system. From there, you can verify that it is present and decide how you want to use it.
One thing that can catch people off guard is that the connection is not persistent by default. If the system reboots, the connection is gone. Because of that, you need to explicitly configure it to reconnect automatically when the system boots.
Check Existing Disks (This lets you see the disks that are already attached before you begin.)
- lsblk
Install iSCSI Tools (You need the iSCSI tools installed so the client can communicate with the iSCSI server.)
- sudo apt install open-iscsi -y
Find Your Client IQN (This is where you can view the client IQN along with the local iSCSI configuration.)
- cd /etc/iscsi/
- cat /etc/iscsi/initiatorname.iscsi
Discover Available iSCSI Targets (This shows you the targets currently being presented by the storage server.)
- iscsiadm -m discovery -t sendtargets -p <TARGET_IP_OR_FQDN>
Configure CHAP Authentication (If CHAP is enabled on the storage server, you need to configure the username and password on the client before discovery or login will work. You may also need to remove any previously discovered nodes or targets and run discovery again to ensure the configuration is applied correctly to the intended target.)
- iscsiadm -m discoverydb -t sendtargets -p <TARGET_IP_OR_FQDN> --discover
- iscsiadm -m discoverydb -t sendtargets -p <TARGET_IP_OR_FQDN> --op update -n discovery.sendtargets.auth.authmethod -v CHAP
- iscsiadm -m discoverydb -t sendtargets -p <TARGET_IP_OR_FQDN> --op update -n discovery.sendtargets.auth.username -v <USERNAME>
- iscsiadm -m discoverydb -t sendtargets -p <TARGET_IP_OR_FQDN> --op update -n discovery.sendtargets.auth.password -v <PASSWORD>
Log Into a Target (Once authentication is configured, you can log in to one of the targets on the server.)
- iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP_OR_FQDN> --login
Verify That the New Disk Appears
After logging in, check to make sure the new disk is visible to the system.
- lsblk
If you are still unable to log in after adding the correct username and password, check the default configuration for that specific target. In some cases, the target may still be using a different saved setting than the one you just configured.
Enable Services for Persistence
One thing you do not want is having to manually log in every time the server reboots. To make sure the iSCSI disk reconnects automatically at boot, you need to enable the required services and update the target startup behavior. Keep in mind that this is configured per iSCSI target.
- sudo systemctl enable iscsid
- sudo systemctl enable open-iscsi
- sudo iscsiadm -m node -T <TARGET_IQN> -p <STORAGE_IP> -o update -n node.startup -v automatic
Connecting to Proxmox
On the Proxmox side, the idea is the same, but the implementation looks a little different. You add the iSCSI target as a storage source, and at that point Proxmox can see the raw disk, but it cannot use it yet.
The reason is simple. It is just a block device with no structure on top of it. To make that storage usable, you need to place something like LVM on top of the iSCSI disk. That gives Proxmox a storage layer it can actually work with for virtual machines. Once that is done, your VMs can live directly on that iSCSI-backed storage.
The process of adding iSCSI to Proxmox is a little more straightforward than mounting it directly inside a Linux server or VM. For the full step-by-step walkthrough, watch the video above.
Closing Thoughts
One of the things keep in mind is that when your storage lives on the network, your network and your storage become one system. You cannot treat them separately. To be honest there is no single “right” way to structure things. It depends on what you are building.
If you need shared file access, something like NFS might make sense. If you need raw performance and flexibility at the disk level, iSCSI is a strong option. The key is understanding what each approach gives you and making intentional decisions based on your goals. And just like everything else in this journey, you build it step by step.
