Ubuntu Multipath Configuration for Single VIOS to Dual VIOS Migration

This process helps identify and configure Ubuntu systems to seamlessly transition from a Single VIOS to a Dual VIOS environment using multipathing.

Kyndryl Cloud Uplift recommends creating a template of the LPAR prior to performing the following procedure. This should always be done when making significant changes, especially storage related changes so that recovery is easy.

Check Configuration

After powering on the Ubuntu system on a Single VIOS host, perform the following checks. 

Log in to the Ubuntu System as root

Run the following command to verify whether the VM is booted in Single VIOS or Dual VIOS mode by checking the available SCSI hosts.

# ls /sys/class/scsi_host/ 

If the VM is booted with Single VIOS, the output will show a single SCSI host (or one host per disk controller). 

Example:  host0

If the VM is booted with Dual VIOS, the output will show two SCSI hosts (or double the number based on disk controllers). 

Example:  host0 host1

Run the following command to determine whether multipath is enabled:

# multipath -ll

Sample Expected Output

If Configured Correctly:

mpatha (23231626562323333) dm-0 IBM,2107900 
|-+- policy='round-robin 0' prio=1 status=active 
| `- 0:0:0:0 sda 8:0 active ready running 
`-+- policy='round-robin 0' prio=1 status=enabled 
  `- 1:0:0:0 sdf 8:80 active ready running

Sample Unexpected Output

If not configured:

# multipath -ll 

If multipath devices are not visible or the command returns empty output, proceed with the configuration steps below.

Phase 1 — Install and Configure multipath-tools

Step 1.1 — Install multipath packages

Run the following commands to install the required multipath packages:

# apt-get update 
# apt-get install -y multipath-tools multipath-tools-boot 
# systemctl enable multipathd 
# systemctl start multipathd

Verify the packages are installed:

# dpkg -l | grep -i multipath

Expected Output

The output should display both packages:

# multipath-tools 
# multipath-tools-boot 

If the packages are not installed, repeat the installation commands above in step 1.1.

Phase 2 — Create multipath Configuration

Step 2.1 — Find Disk WWIDs

Examine the block device tree by running the following command:

# lsblk

Sample Output

NAME                      MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS 
loop0                       7:0    0 44.5M  1 loop /snap/snapd/26867 
loop1                       7:1    0 64.3M  1 loop /snap/core20/2380 
loop2                       7:2    0 79.2M  1 loop /snap/lxd/28377 
loop3                       7:3    0 79.2M  1 loop /snap/lxd/29380 
sda                         8:0    0 150G  0 disk 
├─sda1                      8:1    0   8M  0 part 
├─sda2                      8:2    0   2G  0 part /boot 
└─sda3                      8:3    0 148G  0 part 
  └─ubuntu--vg-ubuntu--lv 253:0    0  74G  0 lvm  /

In this example, the system contains a single OS disk using a single path (sda).

Run the following command to obtain the WWID of the OS disk:

# /lib/udev/scsi_id --page=0x83 --whitelisted /dev/sda

Repeat the above command for additional disks such as /dev/sdb, /dev/sdc, etc.

Record the WWID values for use in the multipath configuration file.

Step 2.2 — Configure multipath.conf

Create or update the /etc/multipath.conf file.

Edit the file using vi or nano:

# vi /etc/multipath.conf

Add the following configuration:

defaults { 
    user_friendly_names yes 
    find_multipaths yes 
    path_grouping_policy multibus 
    path_selector "round-robin 0" 
    path_checker tur 
    failback immediate 
    no_path_retry 5 
    rr_min_io 100 
    features "1 queue_if_no_path" 
    enable_foreign "^$" 
} 
 
blacklist_exceptions { 
    wwid "WWID_OF_OS_DISK" 
    wwid "WWID_OF_DATA_DISK_1" 
    wwid "WWID_OF_DATA_DISK_2" 
    # Add additional WWIDs here as required 
}

Replace the WWID_OF_* placeholders with the actual WWID values collected in the previous step.

Step 2.3 — Enable LVM multipath component detection

Check the current LVM configuration:

# grep -E "multipath_component|use_devicesfile" /etc/lvm/lvm.conf

If multipath_component_detection is not set to 1, run the following command:

# sed -i '/^devices {/a \    multipath_component_detection = 1' /etc/lvm/lvm.conf

Verify the configuration:

# grep multipath_component_detection /etc/lvm/lvm.conf

Expected Output

# multipath_component_detection = 1

This setting ensures LVM recognizes underlying SCSI devices as components of a multipath device and uses /dev/mapper/mpathX devices instead of raw /dev/sdX devices.

Phase 3 — Configure /etc/fstab

Step 3.1 — Use UUID for the /boot partition

The /boot partition must use a UUID entry instead of a raw device name to ensure successful booting during VIOS transitions.

Identify the UUID:

# lsblk -f | grep boot

Example Output

├─sda2 ext4 1.0 d1deee7b-0a72-47e8-8916-830c37596bc0 1.5G 15% /boot

Edit /etc/fstab:

# vi /etc/fstab

Example correct entry:

UUID=d1deee7b-0a72-47e8-8916-830c37596bc0 /boot ext4 defaults 0 1

Step 3.2 — Verify /etc/fstab syntax

Validate the filesystem table configuration:

# mount -a --fake

Check for errors:

# findmnt --verify

Phase 4 — Rebuild initramfs and Update GRUB

This is a critical step. The initramfs must include the updated multipath configuration so that multipath services start during early boot before LVM activation occurs.

Step 4.1 — Rebuild initramfs

Rebuild initramfs for all installed kernels:

# update-initramfs -u -k all

Step 4.2 — Update GRUB

Run the following command:

# update-grub

Step 4.3 — Verify multipath modules are included

Run:

# lsinitramfs /boot/initrd.img-$(uname -r) | grep -i multipath

Expected Output

usr/lib/modules/5.15.0-177-generic/kernel/drivers/md/dm-multipath.ko.zst 
usr/sbin/multipathd 
etc/multipath.conf

Phase 5 — Reboot the VM

Reboot the Ubuntu VM:

# shutdown -r now

After the system powers back on, boot the VM on a Dual VIOS-enabled PHN and perform the validation checks.

Final Result

Your Ubuntu VM should now be configured for multipathing and capable of seamlessly transitioning between Single VIOS and Dual VIOS environments.

This configuration is typically required only once unless:

• The VM is cloned or templated 
• The VM is migrated to another environment or region 
• Storage configuration changes occur