Skip to content
RunEntLinux
RunEntLinux
Docs networkNetwork
Search RunEntLinux

Searches general documentation on RunEntLinux. Each distribution has its own documentation search.

    Browse this documentation

    iSCSI & Stratis

    Applies to CentOS Stream 9 & 10 / AlmaLinux 9.x & 10.x / Rocky Linux 9.x & 10.x

    This page covers two block storage solutions commonly used on enterprise Linux. iSCSI lets you share a disk on one server over the network to another server, which mounts it and uses it just like a local disk. Stratis is the local storage management tool provided by RHEL, layering pooling, thin provisioning, and snapshots on top of XFS and device-mapper, which is simpler to use than traditional LVM plus a filesystem.

    What You Will Learn

    Section titled “What You Will Learn”
    • The roles of the iSCSI target and initiator
    • How to build an iSCSI target with targetcli and persist the configuration
    • How to discover and log in to a remote block device from the initiator, and enable automatic login at boot
    • How to create storage pools, filesystems, and snapshots with Stratis
    • How to make a Stratis filesystem mount reliably at boot

    Prerequisites

    Section titled “Prerequisites”
    • Two systems running EL 9.x or EL 10.x (the iSCSI part needs one target host and one initiator host)
    • sudo privileges
    • A spare disk or partition on the target (such as /dev/sdb)
    • Network connectivity between the two hosts

    Part 1: iSCSI Network Block Storage

    Section titled “Part 1: iSCSI Network Block Storage”

    iSCSI (Internet SCSI) transports SCSI commands over an ordinary TCP/IP network, presenting a remote disk to the client as a block device. It involves two roles:

    • target: the server, which provides block devices. Each target is identified by an IQN (iSCSI Qualified Name).
    • initiator: the client, which connects to a target and mounts the remote block device locally. After login, a new block device (such as /dev/sdb) appears.
    iSCSI target (192.168.1.10)               iSCSI initiator (192.168.1.20)
    /dev/sdb ──> backstore ──> LUN  ──network──>  /dev/sdb (appears after login)
                IQN + ACL                         partition / format / mount

    Install targetcli

    Section titled “Install targetcli”
    Install the target tool
    $ sudo dnf install targetcli

    Configure the iSCSI target

    Section titled “Configure the iSCSI target”

    targetcli is an interactive shell. Once inside, you organize the configuration using filesystem-like paths. The example below uses a spare disk /dev/sdb as the backend storage.

    1. Enter the targetcli interactive shell:

      Start targetcli
      $ sudo targetcli

    2. Create a backstore. You can use a whole device (block) or an ordinary file (fileio):

      targetcli: create a block backstore
      /> backstores/block create disk1 /dev/sdb

      If you have no spare disk, use a file as the backend instead:

      targetcli: create a fileio backstore (optional)
      /> backstores/fileio create disk1 /var/lib/iscsi_disks/disk1.img 5G

    3. Create an iSCSI target, which automatically generates an IQN:

      targetcli: create a target
      /> iscsi/ create iqn.2026-06.com.example:target1

    4. Attach the backstore to the target as a LUN:

      targetcli: create a LUN
      /> iscsi/iqn.2026-06.com.example:target1/tpg1/luns create /backstores/block/disk1

      Match the LUN path to the backstore type you created in the previous step: use /backstores/block/disk1 for a block backstore, or /backstores/fileio/disk1 for a fileio backstore.

    5. Configure an ACL so that only the specified initiator IQN may connect. The initiator’s IQN comes from its /etc/iscsi/initiatorname.iscsi:

      targetcli: create an ACL
      /> iscsi/iqn.2026-06.com.example:target1/tpg1/acls create iqn.2026-06.com.example:client1

    6. Exit. On exit, the configuration is saved automatically to /etc/target/saveconfig.json:

      targetcli: exit and save
      /> exit

    Persistence and start at boot

    Section titled “Persistence and start at boot”

    The target service loads the configuration from /etc/target/saveconfig.json at boot. Be sure to enable it, otherwise all your configuration is lost after a reboot:

    Enable and start the target service
    $ sudo systemctl enable --now target

    Open the firewall

    Section titled “Open the firewall”

    iSCSI uses 3260/tcp, which must be allowed on the target:

    Allow the iSCSI port
    $ sudo firewall-cmd --permanent --add-port=3260/tcp
    $ sudo firewall-cmd --reload

    Part 2: Stratis Local Storage Management

    Section titled “Part 2: Stratis Local Storage Management”

    Stratis is the local storage management solution provided by RHEL and compatible distributions. Under the hood it uses XFS and device-mapper to handle the tedious configuration automatically, while exposing a simple command line that lets you manage pools, filesystems, and snapshots as objects, with thin provisioning built in.

    It has two parts: the background service stratisd does the actual storage management, while the command-line tool stratis (from stratis-cli) takes your commands.

    Install and enable

    Section titled “Install and enable”
    Install Stratis
    $ sudo dnf install stratisd stratis-cli
    Enable and start stratisd
    $ sudo systemctl enable --now stratisd

    Create a pool and a filesystem

    Section titled “Create a pool and a filesystem”

    1. Create a storage pool named pool1 from a spare disk:

      Create a pool
      $ sudo stratis pool create pool1 /dev/sdb

    2. Create a filesystem named data1 in the pool:

      Create a filesystem
      $ sudo stratis filesystem create pool1 data1

    3. The filesystem’s device path is /dev/stratis/<pool>/<filesystem>. List them to confirm:

      List pools and filesystems
      $ stratis pool list
      $ stratis filesystem list

    Mount and auto-mount at boot

    Section titled “Mount and auto-mount at boot”

    You can mount it temporarily first to test:

    Temporary mount
    $ sudo mkdir -p /mnt/data
    $ sudo mount /dev/stratis/pool1/data1 /mnt/data

    For auto-mount at boot, you must use the UUID and add the systemd dependency. First find the filesystem’s UUID:

    Find the filesystem UUID
    $ sudo lsblk --output=UUID /dev/stratis/pool1/data1

    Then add this to /etc/fstab (note x-systemd.requires=stratisd.service):

    /etc/fstab
    UUID=<the UUID from the previous step>  /mnt/data  xfs  defaults,x-systemd.requires=stratisd.service  0  0

    Verify the fstab entry is correct (so you catch errors without rebooting):

    Verify fstab
    $ sudo umount /mnt/data
    $ sudo systemctl daemon-reload
    $ sudo mount -a
    $ df -hT /mnt/data

    Snapshots

    Section titled “Snapshots”

    Stratis snapshots are based on thin provisioning, so they are fast to create and take almost no space initially:

    Create a snapshot
    $ sudo stratis filesystem snapshot pool1 data1 data1-snap

    A snapshot is itself an independent filesystem that you can mount separately to recover data:

    Mount the snapshot to inspect data
    $ sudo mkdir -p /mnt/snap
    $ sudo mount /dev/stratis/pool1/data1-snap /mnt/snap

    Grow the pool

    Section titled “Grow the pool”

    When the pool runs low on space, add another disk to it with no data migration required:

    Add a disk to the pool
    $ sudo stratis pool add-data pool1 /dev/sdc

    FAQ

    Section titled “FAQ”

    targetcli configuration is lost after a reboot

    Section titled “targetcli configuration is lost after a reboot”

    The most common causes are not saving the configuration when exiting targetcli, or not enabling the target service. Confirm two things: that you ran saveconfig inside targetcli (or exited normally with exit), and that sudo systemctl enable --now target is in place.

    Save the current configuration manually
    $ sudo targetcli saveconfig

    iSCSI login fails

    Section titled “iSCSI login fails”

    Troubleshoot in order:

    • Whether the IQN in the initiator’s /etc/iscsi/initiatorname.iscsi matches the IQN configured in the target’s ACL exactly (spelling and case must match).
    • Whether the target’s firewall allows 3260/tcp.
    • Whether the network is reachable (ping the target IP) and whether iscsiadm -m discovery returns the target list.

    Stratis filesystem fails to mount at boot

    Section titled “Stratis filesystem fails to mount at boot”

    Almost always the fstab entry is missing x-systemd.requires=stratisd.service. Add this option so the mount waits until stratisd is ready. Also confirm you are using the UUID rather than the /dev/stratis/... path.

    Can I use fdisk/LVM directly on disks in a Stratis pool

    Section titled “Can I use fdisk/LVM directly on disks in a Stratis pool”

    No. The physical devices in a pool are managed exclusively by Stratis, and all operations must go through the stratis command. Using other tools directly will corrupt the metadata.

    Further Reading

    Section titled “Further Reading”