How do I use iSCSI to mount an FSx for ONTAP iSCSI LUN on an EC2 Linux instance?

Resolution

Note: The following resolution is for Amazon EC2 instances that run Amazon Linux 2023 (AL2023), Amazon Linux 2 (AL2), Red Hat Enterprise Linux (RHEL) 8, and CentOS 8.

Prerequisites:

• The EC2 instance allows outbound traffic on TCP port 3260.
• The NetApp ONTAP file system allows inbound traffic on TCP port 3260.
• Configure the required iSCSI file systems and instances.
  Note: The requirements for AL2 instances are the same as for AL2023 instances.

Use iSCSI to mount your file system on your instance

Complete the following steps:

1. To install the required packages, run the following command:

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

2. To configure multipath for the file system, run the following commands:

   sudo mpathconf --enable --with_multipathd y
   sudo systemctl start multipathd
   sudo systemctl enable multipathd

3. To retrieve the addresses of the block storage interfaces for the storage virtual machine (SVM), use the ONTAP command line interface (CLI). Run the following command on the FSx ONTAP file system:

   network interface show -vserver svm_name

   Note: Replace svm_name with your SVM name.
   Example output:

               Logical               Status         Network            Current                    Current Is 
   Vserver     Interface             Admin/Oper     Address/Mask       Node                       Port    Home
   ----------- ----------            ----------     ------------------ -------------              ------- ----
   svm_name
               iscsi_1               up/up          iscsi_1_IP/X       FSxId0123456789abcdef8-01  e0e     true
               iscsi_2               up/up          iscsi_2_IP/X       FSxId0123456789abcdef8-02  e0e     true
   2 entries were displayed.

4. To discover iSCSI targets, run the following command on the EC2 instance to find the target initiator:

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

   Note: Replace iscsi_1_IP with the iscsi_1 IP address that you received from the previous command.
   Example output:

   iscsi_1:3260,1029 iqn.1992-08.com.netapp:sn.1234567890abcdef:vs.3 
   iscsi_2:3260,1028 iqn.1992-08.com.netapp:sn.1234567890abcdef:vs.3

   In the preceding example output, the target initiator is iqn.1992-08.com.netapp:sn.1234567890abcdef:vs.3.

5. (Optional) To establish 8 sessions in each initiator in each ONTAP node in each Availability Zone, run the following command:

   sudo iscsiadm --mode node -T iqn.1992-08.com.netapp:sn.1234567890abcdef:vs.3 --op update -n node.session.nr_sessions -v 8

   Note: Replace iqn.1992-08.com.netapp:sn.1234567890abcdef:vs.3 with your target initiator.

6. To log in to the iSCSI target, run the following command:

   sudo iscsiadm -m node -T iqn.1992-08.com.netapp:sn.1234567890abcdef:vs.3 -l

   Note: Replace iqn.1992-08.com.netapp:sn.1234567890abcdef:vs.3 with your target initiator.

7. To find the multipath device, run the following command:

   sudo multipath -ll

   Example output:

   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

   In the preceding example output, the symbolic link is 3600a09806c5742314e5d52766e79614f. You can find the symbolic link under the /dev/mapper/wwid path, where wwid is the unique identifier for your LUN across devices.

8. To create a file system, run the following command:

   sudo mkfs.xfs /dev/mapper/wwid

   Note: Replace wwid with the unique identifier for your LUN.

9. To create a mount point and mount to it, run the following commands:

   sudo mkdir /mnt/fsx-iscsi
   sudo mount /dev/mapper/wwid /mnt/fsx-iscsi

10. (Optional) To configure automatic mount during boot, run the following commands to activate the iSCSI service:

    sudo systemctl enable iscsid
    sudo systemctl enable iscsi

    Then, add the following line to the /etc/fstab file:

    /dev/mapper/wwid /mnt/fsx-iscsi xfs _netdev,x-systemd.automount,x-systemd.requires=network-online.target 0 0

    Note: Replace wwid with the unique identifier for your LUN and /mnt/fsx-iscsi with your file path.

11. Create a systemd service file for iSCSI login with the /etc/systemd/system/ file path.
    Example file:

    [Unit]
    Description=iSCSI connection to FSx
    After=network.target
    
    [Service]
    Type=oneshot
    RemainAfterExit=yes
    ExecStart=/sbin/iscsiadm -m node -T iqn.1992-08.com.netapp:sn.1234567890abcdef:vs.3 -p iscsi_1_IP -l
    ExecStop=/sbin/iscsiadm -m node -T iqn.1992-08.com.netapp:sn.1234567890abcdef:vs.3 -p iscsi_1_IP -u
    
    [Install]
    WantedBy=multi-user.target

    Note: Replace iscsi_1_IP with your iscsi_1 IP address and region with your AWS Region.

12. To activate and start the service, run the following commands:

    sudo systemctl enable iscsi-fsx.service
    sudo systemctl start iscsi-fsx.service
    sudo systemctl status iscsi-fsx.service

Troubleshoot ISCSI mount issues

Important: It's a best practice to create a NetApp account. You must have a NetApp account to access the NetApp knowledge base.

Troubleshoot the EC2 Linux server

If you experience issues when you mount your file system, then take the following troubleshooting actions:

• To check the connectivity on the required port, run the following command:

  telnet iscsi_1_IP 3260

  Note: Replace iscsi_1_IP with your iscsi_1 IP address.

• To check whether iSCSI discovery works as expected, run the following command:

  sudo iscsiadm -m discovery --op update -t sendtargets -p iscsi_1_IP

  Note: Replace iscsi_1_IP with your iscsi_1 IP address.

• To check the status of active iSCSI sessions and identify issues, run the following command:

  sudo iscsiadm -m session

• To verify that multipath works as expected, run the following command:

  sudo multipath -ll

• To check the logs for errors, run one of the following commands:

  dmesg | grep iSCSI 

  -or-

  journalctl -u iscsid

To further troubleshoot mount issues, see Troubleshoot iSCSI LUNs not visible on the host on the NetApp website.

Troubleshoot the FSx for ONTAP server

To verify that the iSCSI service is running, run the following commands:

vserver iscsi show
iscsi session show

To check your LUN configuration for issues, run the following command:

lun show -vserver vserver_name

Note: Replace vserver_name with your server name.

To verify that you correctly configured storage access, run the following command to view the mapping between LUNs and initiator groups:

lun mapping show

To check the igroup configuration and confirm that it includes your initiator, run the following command:

igroup show -instance