Linux iSCSI with FSx for ONTAP: Source Setup and Multipath Example

This source is derived from the AWS guide for Amazon FSx for NetApp ONTAP, although its title omits that platform scope. Its availability-zone, session and throughput examples are not universal on-premises ONTAP defaults. Prepare an appropriate Linux host, authorized SVM management access, an existing intended LUN and reachable iSCSI data endpoints. Package/service commands vary by distribution.

The official English AWS procedure is the version-specific reference. For FSx, check the actual VPC/security-group, host placement and supported filesystem requirements. The stored example covers client setup, igroup/LUN mapping and mounting; it does not create the underlying filesystem or LUN.

1. Install and configure the Linux initiator

Install the source’s multipath and initiator packages:

~$ sudo yum install -y device-mapper-multipath iscsi-initiator-utils

The source changes the session replacement timeout from 120 to 5 seconds for its multipath/failover design. Check that setting against the supported host/target profile; it affects other matching sessions too:

~$ sudo sed -i 's/node.session.timeo.replacement_timeout = .*/node.session.timeo.replacement_timeout = 5/' /etc/iscsi/iscsid.conf; sudo cat /etc/iscsi/iscsid.conf | grep node.session.timeo.replacement_timeout

Start iscsid using the command appropriate to the installed service manager, then check it:

~$ sudo service iscsid start

~$ sudo systemctl start iscsid

~$ sudo systemctl status iscsid.service

Complete archived status output, including its original timestamp/timezone and disabled-startup field:

iscsid.service - Open-iSCSI 
    Loaded: loaded (/usr/lib/systemd/system/iscsid.service; disabled; vendor preset: disabled) 
    Active: active (running) since Fri 2021-09-02 00:00:00 UTC; 1min ago
    Docs: man:iscsid(8)
    man:iscsiadm(8)
    Process: 14658 ExecStart=/usr/sbin/iscsid (code=exited, status=0/SUCCESS)
    Main PID: 14660 (iscsid)
    CGroup: /system.slice/iscsid.service
    ├─14659 /usr/sbin/iscsid
    └─14660 /usr/sbin/iscsid

A running service and a disabled boot-start setting are different states. Configure supported boot persistence separately when needed. Enable/configure multipath and read the host initiator IQN:

~$ sudo mpathconf --enable --with_multipathd y

~$ sudo cat /etc/iscsi/initiatorname.iscsi

InitiatorName=iqn.1994-05.com.redhat:abcdef12345

2. Configure the SVM igroup and LUN mapping

Connect to the actual management endpoint with an account authorized for the target system. The source uses an admin placeholder; FSx roles can differ:

~$ ssh admin@your_management_ONTAP_ip

Create an iSCSI igroup with the Linux host’s actual initiator IQN:

::> lun igroup create -vserver svm_name -igroup igroup_name -initiator host_initiator_name -protocol iscsi -ostype linux

The source permits comma-separated initiators for multiple hosts. Mapping an ordinary ext4 LUN to several independent writers is not made safe by an igroup; use a supported clustered/shared-storage design if multiple hosts require access.

::> lun igroup show

Vserver   Igroup       Protocol OS Type  Initiators
--------- ------------ -------- -------- ------------------------------------
svm_name  igroup_name  iscsi    linux    iqn.1994-05.com.redhat:abcdef12345

Map the existing intended LUN to that igroup. svm_name identifies the SVM, vol_name its volume, lun_name the LUN, igroup_name the authorized initiators and lun_id the mapping-specific logical-unit number:

::> lun mapping create -vserver svm_name -path /vol/vol_name/lun_name -igroup igroup_name -lun-id lun_id

Inspect the LUN state, mapping and serial:

::> lun show -path /vol/vol_name/lun_name -fields state,mapped,serial-hex

Vserver    Path                           serial-hex               state    mapped
 --------- ------------------------------- ------------------------ -------- --------
 svm_name  /vol/vol_name/lun_name          6c5742314e5d52766e796150 online   mapped

Save the real serial/WWID for later correlation. The source’s serial-hex output ends in 6150, but its later multipath WWID example ends in 614f. Those examples are inconsistent and must not be concatenated/treated as the same verified device identity.

List SVM interfaces and identify the actual iSCSI data addresses:

::> network interface show -vserver svm_name

Logical               Status     Network            Current                    Current Is 
Vserver     Interface             Admin/Oper Address/Mask       Node                       Port    Home
----------- ----------            ---------- ------------------ -------------              ------- ----
svm_name
            iscsi_1               up/up      172.31.0.143/20    FSxId0123456789abcdef8-01  e0e     true
            iscsi_2               up/up      172.31.21.81/20    FSxId0123456789abcdef8-02  e0e     true
            nfs_smb_management_1 
                                  up/up      198.19.250.177/20  FSxId0123456789abcdef8-01  e0e     true
3 entries were displayed.

The archived iSCSI interfaces are 172.31.0.143 and 172.31.21.81. The nfs_smb_management_1 address is a different interface, not an interchangeable iSCSI target portal.

3. Discover and log in to the target

~$ sudo iscsiadm --mode discovery --op update --type sendtargets --portal iscsi_1_IP

172.31.0.143:3260,1029 iqn.1992-08.com.netapp:sn.9cfa2c41207a11ecac390182c38bc256:vs.3
172.31.21.81:3260,1028 iqn.1992-08.com.netapp:sn.9cfa2c41207a11ecac390182c38bc256:vs.3

Use the discovered target IQN in the source’s target_initiator placeholder. Despite its misleading name, it means the target, not the Linux host’s initiator IQN.

The source optionally requests 8 sessions per node and cites an archived 5 Gbps per-client-session / 40 Gbps aggregate example. These are platform/network examples, not guaranteed throughput or universally recommended session counts:

~$ sudo iscsiadm --mode node -T target_initiator --op update -n node.session.nr_sessions -v 8

~$ sudo iscsiadm --mode node -T target_initiator --login

Logging in to [iface: default, target: iqn.1992-08.com.netapp:sn.9cfa2c41207a11ecac390182c38bc256:vs.3, portal: 172.31.14.66,3260] (multiple)
Login to [iface: default, target: iqn.1992-08.com.netapp:sn.9cfa2c41207a11ecac390182c38bc256:vs.3, portal: 172.31.14.66,3260] successful.

The printed login portal 172.31.14.66 differs from the two discovery addresses. The output is truncated and is not proof that every desired path logged in. The source also switches from an 8-session setting to a 4-session counting example; use the actual configured session/path count, not either number as a universal expected count.

4. Verify the multipath device

~$ sudo multipath -ll

3600a09806c5742314e5d52766e79614f dm-xyz NETAPP  ,LUN C-Mode      
size=10G features='4 queue_if_no_path pg_init_retries 50 retain_attached_hw_handle' hwhandler='0' wp=rw
|-+- policy='service-time 0' prio=50 status=active
| |- 0:0:0:1 sda     8:0   active ready running
| |- 1:0:0:1 sdc     8:32  active ready running
| |- 3:0:0:1 sdg     8:96  active ready running
| `- 4:0:0:1 sdh     8:112 active ready running
`-+- policy='service-time 0' prio=10 status=enabled
  |- 2:0:0:1 sdb     8:16  active ready running
  |- 7:0:0:1 sdf     8:80  active ready running
  |- 6:0:0:1 sde     8:64  active ready running
  `- 5:0:0:1 sdd     8:48  active ready running

The source’s 10 G map contains two priority groups, 50 active and 10 enabled, with four listed paths in each group. The path rows themselves show active/ready/running in both groups; path-group status and per-path state are distinct. Equal path counts are an example topology, not a universal health rule.

Use the actual stable /dev/mapper/WWID map or a validated alias, not a guessed /dev/dm-xyz number or one individual /dev/sdX path. The source’s WWID/serial mismatch above must be resolved against the real device before any write.

5. Optional friendly alias

The source shows a multipath configuration template. Replace the entire WWID with the actual verified map identifier and choose a unique valid alias:

multipaths {
    multipath {
        wwid 3600a0980serial_hex
        alias device_name
    }
}

The 3600a0980 prefix in that template is specific to its illustrated NetApp SCSI identifier construction, not a universal transform for arbitrary storage. Prefer the actual WWID reported for the connected LUN. The source also supplies this complete shell helper:

#!/bin/bash
SN=serial_hex
ALIAS=device_name
CONF=/etc/multipath.conf
grep -q '^multipaths {' $CONF
UNCOMMENTED=$?
if [ $UNCOMMENTED -eq 0 ]
then
        sed -i '/^multipaths {/a\\tmultipath {\n\t\twwid 3600a0980'"${SN}"'\n\t\talias '"${ALIAS}"'\n\t}\n' $CONF
else
        printf "multipaths {\n\tmultipath {\n\t\twwid 3600a0980$SN\n\t\talias $ALIAS\n\t}\n}" >> $CONF
fi

That archived helper only detects a column-zero, exact-format multipaths { line and appends an entry. It does not validate WWID/alias, parse all legal configuration layouts, detect duplicate maps or make a backup. Review/merge the configuration explicitly and validate the complete file rather than repeatedly executing it as a general parser. It writes /etc/multipath.conf; the source’s later multipathd.conf mention is a typo.

~$ systemctl restart multipathd.service

6. Partition and create a filesystem only on the intended new LUN

Partition-table writes and mkfs can destroy existing data. Continue only for a verified new/empty LUN whose identity and ownership are established. An existing filesystem should be identified and mounted using its proper procedure instead.

~$ ls /dev/mapper/device_name

The source prints /dev/device_name as the response to that ls command, which is inconsistent with the queried mapper path. Confirm the actual /dev/mapper/device_name symlink/map before use.

~$ sudo fdisk /dev/mapper/device_name

Welcome to fdisk (util-linux 2.30.2). 
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.
Device does not contain a recognized partition table.
Created a new DOS disklabel with disk identifier 0x66595cb0.

fdisk edits the partition table; it does not itself create ext4. The source refers to a first partition on a 10 GB example ending at sector 20971519 and committing with w, but omits the complete interactive choices. Choose a supported partition layout and verify it before writing; these example sector/count values are not portable. Determine the actual multipath partition node; partition_name is a placeholder, not a fixed concatenation rule.

~$ sudo mkfs.ext4 /dev/mapper/partition_name

Complete archived ext4 creation output:

mke2fs 1.42.9 (28-Dec-2013)
Discarding device blocks: done 
Filesystem label=
OS type: Linux
Block size=4096 (log=2)
Fragment size=4096 (log=2)
Stride=0 blocks, Stripe width=16 blocks
655360 inodes, 2621184 blocks
131059 blocks (5.00%) reserved for the super user
First data block=0
Maximum filesystem blocks=2151677952
80 block groups
32768 blocks per group, 32768 fragments per group
8192 inodes per group
Superblock backups stored on blocks: 
     32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632
Allocating group tables: done 
Writing inode tables: done 
Creating journal (32768 blocks): done
Writing superblocks and filesystem accounting information: done

7. Mount and optionally test the filesystem

Create the mount point after verifying the parent path. The source’s mkdir is shown below; it requires its parent to exist:

~$ sudo mkdir /directory_path/mount_point

~$ sudo mount -t ext4 /dev/mapper/partition_name /directory_path/mount_point

Optional ownership change, only for the intended user/group:

~$ sudo chown username:username /directory_path/mount_point

The source’s write/read smoke test has an inconsistent cat path. Here both commands use the same mounted directory:

echo "Hello world!" > /directory_path/mount_point/HelloWorld.txt
cat /directory_path/mount_point/HelloWorld.txt
Hello world!

Only verified command results establish that the real LUN is mounted and usable. The archived sample output is not a new success result, a complete boot-persistent mount configuration, or a tested failover outcome.