Mount iSCSI volume on Debian 12

Learn how to mount an Block Storage for Classic volume on Debian 12 with multipath I/O for redundant, high-performance storage access.

Follow the tutorial to mount an IBM Cloud® Block Storage for Classic volume on a virtual server with the Debian 12 operating system. You're going to create two connections from one network interface of your host to two target IP addresses of the storage array.

If you're using another Linux® operating system, refer to the Documentation of your specific distribution, and make sure that the multipath supports Asymmetric Logical Unit Access (ALUA) for path priority.

Before you begin

  1. Create a virtual server for Classic in the console, from the CLI, with the API, or Terraform.

  2. Order a block storage volume in the same datacenter.

  3. Make sure that the host is authorized to access the Block Storage for Classic volume. For more information, see Authorizing the host in the console Authorizing the host from the CLIAuthorizing the host with Terraform. After the authorization is complete, note the Username, Password, and Host IQN information.

  4. An active VPN connection is required to access to the private network of IBM Cloud and to interact with several services.

  5. Establish an SSH connection to your server. The IP address, username, and password can be found in the console. From the menu Menu icon, click Infrastructure VPC icon > Classic Infrastructure > Devices. Then, locate your server in the list and click its name to display its details.

If multiple hosts mount the same Block Storage for Classic volume without being cooperatively managed, your data is at risk for corruption. Volume corruption can occur if changes are made to the volume by multiple hosts at the same time. You need a cluster-aware, shared-disk file system to prevent data loss such as Microsoft Cluster Shared Volumes (CSV), Red Hat Global File System (GFS2), VMware® VMFS, and others. For more information, see your OS Documentation.

It's best to run storage traffic on a VLAN, which bypasses the firewall. Running storage traffic through software firewalls increases latency and adversely affects storage performance. For more information about routing storage traffic to its own VLAN interface, see the FAQs.

Install and configure the iSCSI utility

  1. Make sure that your system is updated:

    apt-get update
    
  2. Then, install open-iscsi.

    apt install open-iscsi
    

    When the package is installed, it creates the following two files.

    • /etc/iscsi/iscsid.conf
    • /etc/iscsi/initiatorname.iscsi
  3. Open /etc/iscsi/initiatorname.iscsi in an editor of your choice, and update the InitiatorName entry to match the host IQN that you see in the console.

    nano /etc/iscsi/initiatorname.iscsi
    
    GNU nano 7.2             /etc/iscsi/initiatorname.iscsi
    ## DO NOT EDIT OR REMOVE THIS FILE!
    ## If you remove this file, the iSCSI daemon will not start.
    ## If you change the InitiatorName, existing access control lists
    ## may reject this initiator.  The InitiatorName must be unique
    ## for each iSCSI initiator.  Do NOT duplicate iSCSI InitiatorNames.
    InitiatorName=iqn.2025-11.com.ibm:sl02su1414935-v154439822
    
  4. Open /etc/iscsi/iscsid.conf in an editor of your choice. Uncomment the following entries by removing the # at the start of each line, and update them by using the username and password from the IBM Cloud® console. Use uppercase for CHAP (Challenge-Handshake Authentication Protocol) names.

    node.session.auth.authmethod = CHAP
    node.session.auth.username = <Username-value-from-Portal>
    node.session.auth.password = <Password-value-from-Portal>
    discovery.sendtargets.auth.authmethod = CHAP
    discovery.sendtargets.auth.username = <Username-value-from-Portal>
    discovery.sendtargets.auth.password = <Password-value-from-Portal>
    

    Keep the other CHAP settings commented. IBM Cloud® storage uses only one-way authentication. Do not enable Mutual CHAP.

  5. Restart the iSCSI service so that the new initiator name and credentials take effect.

    systemctl restart iscsid.service
    

Install and configure the Multipath utility

  1. Install the multipath tools packages:

    apt install multipath-tools
    
    root@vm4classic:~# apt-get install multipath-tools
    Reading package lists... Done
    Building dependency tree... Done
    Reading state information... Done
    The following additional packages will be installed:
      kpartx libaio1 libsgutils2-1.46-2 liburcu8 sg3-utils sg3-utils-udev
    Suggested packages:
      multipath-tools-boot
    The following NEW packages will be installed:
      libaio1 libsgutils2-1.46-2 liburcu8 multipath-tools sg3-utils sg3-utils-udev
    The following packages will be upgraded:
      kpartx
    1 upgraded, 6 newly installed, 0 to remove and 64 not upgraded.
    Need to get 1,436 kB of archives.
    After this operation, 4,922 kB of additional disk space will be used.
    Do you want to continue? [Y/n] Y
    
  2. Edit the /etc/multipath.conf file with nano, vi, or another editor of your choice.

    nano /etc/multipath.conf
    
  3. Add the following minimum configuration.

    defaults {
    user_friendly_names no
    find_multipaths on
    max_fds max
    flush_on_last_del yes
    queue_without_daemon no
    dev_loss_tmo infinity
    fast_io_fail_tmo 5
    }
    # All data in the following section must be specific to your system.
    blacklist {
    wwid "SAdaptec*"
    devnode "^hd[a-z]"
    devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st)[0-9]*"
    devnode "^cciss.*"
    }
    devices {
    device {
    vendor "NETAPP"
    product "LUN"
    path_grouping_policy group_by_prio
    features "2 pg_init_retries 50"
    no_path_retry queue
    prio "alua"
    path_checker tur
    failback immediate
    path_selector "round-robin 0"
    hardware_handler "1 alua"
    rr_weight uniform
    rr_min_io 128
    }
    }
    

    The initial defaults section of the configuration file configures your system so that the names of the multipath devices are of the form /dev/mapper/mpath n, where mpath n is the WWID of the device.

  4. Save the configuration file and exit the editor.

  5. Restart the multipath service so that the new configuration is loaded. The service might already be running after the package is installed.

    systemctl restart multipathd.service
    

    If you need to edit the multipath configuration file after you started the multipath daemon, you must issue the systemctl reload multipathd.service command for the changes to take effect.

Discover the storage device and login

The iscsiadm utility is a command-line tool that is used for discovery and login to iSCSI targets, plus access and management of the open-iscsi database. For more information, see the iscsiadm(8) man page. In this step, discover the device by using the Target IP address that was obtained from the IBM Cloud® console.

  1. Run the discovery against the iSCSI array.

    Block Storage for Classic requires dynamic target discovery that uses the SendTargets method. Do not use static node configuration, as it is not scalable and can cause connectivity issues when changes are made to the storage (such as authorizing or deauthorizing hosts to LUNs). Dynamic discovery ensures that your host automatically detects any changes to the target portals.

    iscsiadm -m discovery -t sendtargets -p TARGET IP
    

    If the IP address information and access details are displayed, then the discovery is successful.

  2. Configure automatic login so that the sessions are re-established after a restart.

    iscsiadm -m node --op=update -n node.startup -v automatic
    iscsiadm -m node --op=update -n node.conn[0].startup -v automatic
    
  3. Log in to the iSCSI array.

    iscsiadm -m node --login
    

Verifying configuration

  1. Validate that the iSCSI session is established.

    iscsiadm -m session -o show
    
  2. Validate that multiple paths exist.

    multipath -ll
    

    If multipath is configured correctly, each volume has a single group, with a number of paths equal to the number of iSCSI sessions.

  3. List the partition tables for the connected device.

    fdisk -l | grep /dev/mapper
    

    By default the storage device attaches to /dev/mapper/<wwid>. WWID is persistent while the volume exists. The command reports something similar to the following example.

    Disk /dev/mapper/3600a0980383030523424457a4a695266: 73.0 GB, 73023881216 bytes
    

    In the example, the string 3600a0980383030523424457a4a695266 is the WWID. Your application ought to use the WWID. It's also possible to assign easier-to-read names by using "user_friendly_names" or "alias" keywords in multipath.conf. For more information, see the multipath.conf man page.

    The volume is now mounted and accessible on the host. You can create a file system next.

Creating a file system (optional)

Follow these steps to create a file system on the newly mounted volume. A file system is necessary for most applications to use the volume. Use fdisk for drives that are less than 2 TB and parted for a disk bigger than 2 TB.

Creating a file system with fdisk

  1. Get the disk name.

    fdisk -l | grep /dev/mapper
    

    The disk name that is returned looks similar to /dev/mapper/XXX.

  2. Create a partition on the disk.

    fdisk /dev/mapper/XXX
    

    The XXX represents the disk name that is returned in Step 1.

  3. Find the name of the new partition. The partition table of a multipath device might not be re-read automatically, so create the partition device with kpartx, and then list the devices.

    kpartx -a -p -part /dev/mapper/XXX
    ls /dev/mapper
    

    The new partition is listed as the disk name followed by -part1, similar to XXX-part1. The -p -part option gives the partition the same name that the system assigns after a restart, so the entry in /etc/fstab keeps working. Take a note of the partition name, you need it in the next step.

  4. Create a file system on the new partition.

    mkfs.ext3 /dev/mapper/XXX-part1
    
  5. Create a mount point for the file system, and mount it.

    • Create a directory called PerfDisk, or use another directory where you want to mount the file system.

      mkdir /PerfDisk
      
    • Mount the storage with the partition name.

      mount /dev/mapper/XXX-part1 /PerfDisk
      
    • Check that you see your new file system listed.

      df -h
      
  6. To enable automatic mounting on boot, add the new file system to the system's /etc/fstab file.

    • Append the following line to the end of /etc/fstab (with the partition name from Step 3).

      /dev/mapper/XXX-part1    /PerfDisk    ext3    defaults,_netdev    0    1
      

    For more information, see An introduction to the Linux /etc/fstab file.

Creating a file system with parted

On many Linux® distributions, parted comes preinstalled. However, if you need to you can install it by issuing the following command.

apt install parted

To create a file system with parted, follow these steps.

  1. Start the interactive parted shell.

    parted
    
  2. Create a partition on the disk.

    1. Select the disk that you want to partition by using the command select. Replace XXX with your new device name.

      select /dev/mapper/XXX
      

      You must run the select command before you create a partition. When you start parted without selecting a disk, it opens the first disk that it finds. On a server with an attached Block Storage for Classic volume, that disk can be one of the iSCSI paths to the volume (for example, /dev/sda) and not the multipath device. Do not partition /dev/sda, /dev/sdb, or any other path device directly. Always select the multipath device in /dev/mapper.

    2. Run print to confirm that you are on the correct disk. The output must show the /dev/mapper/XXX device and the size of your volume. If it doesn't, run select again before you continue.

      print
      
    3. Create a partition table.

      mklabel gpt
      
    4. Parted can be used to create primary and logical disk partitions, the steps that are involved are the same. To create a partition, the utility uses mkpart. You can give it other parameters like primary or logical depending on the partition type that you want to create.

      mkpart
      

      The listed units default to megabytes (MB). To create a 10-GB partition, you start from 1 and end at 10000. You can also change the sizing units to terabytes by entering unit TB if you want to.

    5. Exit parted with quit.

      quit
      
  3. Find the name of the new partition. The partition table of a multipath device might not be re-read automatically, so create the partition device with kpartx, and then list the devices.

    kpartx -a -p -part /dev/mapper/XXX
    ls /dev/mapper
    

    The new partition is listed as the disk name followed by -part1, similar to XXX-part1. The -p -part option gives the partition the same name that the system assigns after a restart, so the entry in /etc/fstab keeps working.

  4. Create a file system on the new partition.

    mkfs.ext3 /dev/mapper/XXX-part1
    

    It's important to select the correct disk and partition when you run this command. Verify the result by printing the partition table. Under the file system column, you can see ext3.

  5. Create a mount point for the file system and mount it.

    • Create a directory called PerfDisk, or use another directory where you want to mount the file system.

      mkdir /PerfDisk
      
    • Mount the storage with the partition name.

      mount /dev/mapper/XXX-part1 /PerfDisk
      
    • Check that you see your new file system listed.

      df -h
      
  6. To enable automatic mounting on boot, add the new file system to the system's /etc/fstab file.

    • Append the following line to the end of /etc/fstab (with the partition name from Step 3).

      /dev/mapper/XXX-part1    /PerfDisk    ext3    defaults,_netdev    0    1
      

    For more information, see An introduction to the Linux /etc/fstab file.

Managing user permissions to the content of the mounted volume

As a system administrator, you can manage the access to data on the mounted volume. After the file system is ready, you can refine access control by using the chown and chmod commands to assign read, write, and execute permissions to individual users and groups. For more information, see Red Hat's tutorial: How to manage Linux permissions for users, groups, and others.

Verifying MPIO configuration

If MPIO isn't configured correctly, your storage device might disconnect and appear offline when a network outage occurs or when IBM Cloud® teams perform maintenance. MPIO provides an extra level of connectivity during those events, and keeps an established session to the volume with active read/write operations.

  • To check whether multipath is picking up the devices, list the current configuration. If it is configured correctly, then a single group exists for each volume, with a number of paths equal to the number of iSCSI sessions.

    multipath -l
    
    root@server:~# multipath -l
    3600a09803830304f3124457a45757067 dm-1 NETAPP,LUN C-Mode
    size=20G features='1 queue_if_no_path' hwhandler='0' wp=rw
    |-+- policy='round-robin 0' prio=-1 status=active
    | `6:0:0:101 sdd 8:48 active ready running
    `-+- policy='round-robin 0' prio=-1 status=enabled
     `- 7:0:0:101 sde 8:64 active ready running
    

    The string 3600a09803830304f3124457a45757067 in the example is the unique WWID of the volume. Each volume is identified by its unique WWID, which is persistent while the volume exists.

  • Confirm that all the disks are present. In a correct configuration, you can expect two disks to show in the output with the same identifier, and a /dev/mapper listing of the same size with the same identifier. The /dev/mapper device is the one that multipath sets up.

    fdisk -l | grep Disk
    
    • Example output of a correct configuration.
    root@server:~# fdisk -l | grep Disk
    Disk /dev/sda: 500.1 GB, 500107862016 bytes Disk identifier: 0x0009170d
    Disk /dev/sdc: 21.5 GB, 21474836480 bytes Disk identifier: 0x2b5072d1
    Disk /dev/sdb: 21.5 GB, 21474836480 bytes Disk identifier: 0x2b5072d1
    Disk /dev/mapper/3600a09803830304f3124457a45757066: 21.5 GB, 21474836480 bytes Disk identifier: 0x2b5072d1
    

    The WWID is included in the device name that the multipath creates. The WWID is recommended to be used by your application.

    • Example output of an incorrect configuration. No /dev/mapper disk exists.
    root@server:~# fdisk -l | grep Disk
    Disk /dev/sda: 500.1 GB, 500107862016 bytes Disk identifier: 0x0009170d
    Disk /dev/sdc: 21.5 GB, 21474836480 bytes Disk identifier: 0x2b5072d1
    Disk /dev/sdb: 21.5 GB, 21474836480 bytes Disk identifier: 0x2b5072d1
    
  • To confirm that no local disks are included in the list of multipath devices, display the current configuration with verbosity level 3. The output of the following command displays the devices and also shows which ones were added to the blocklist.

    multipath -l -v 3 | grep sd
    
  • If a volume is provisioned and attached while the second path is down, the host might see a single path when the discovery scan is run for the first time. If you encounter this rare phenomenon, check the IBM Cloud® status page to see whether an event that impacts your host's ability to access the storage is in progress. If no events are reported, perform the discovery scan again to make sure that all paths are properly discovered. If an event is in progress, the storage can be attached with a single path. However, it's essential that paths are rescanned after the event is completed. If both paths are not discovered after the rescan, create a support case so it can be properly investigated.

Unmounting Block Storage for Classic volumes

  1. Remove the line for the volume from the /etc/fstab file so that the system doesn't try to mount it again. For example, delete the line that contains /PerfDisk.

  2. Unmount the file system.

    umount /PerfDisk
    
  3. If you do not have any other volumes in that target portal, you can log out of the target.

    iscsiadm -m node -T <TARGET NAME> -p <PORTAL IP:PORT> --logout
    

    A volume has two portals (two target IP addresses), and each portal has its own iSCSI session. The command logs out of only the portal that you specify, so you need to run it twice, once for each portal. Use the portal addresses from the volume details page in the console, or run iscsiadm -m session -o show to list the active sessions.

  4. If you do not have any other volumes in that target portal, delete the target portal record to prevent future login attempts.

    iscsiadm -m node -o delete -T <TARGET IQN> -p <PORTAL IP:PORT>
    

    Run this command twice as well, once for each portal. After both records are deleted, iscsiadm -m node reports No records found.

    For more information, see the iscsiadm manual.