vSphere cloned Linux VM won't boot? disk.EnableUUID parameter solves device name drift (Ubuntu tested)

Introduction: A Common Failure Scenario

Have you ever encountered this situation: after cloning or migrating an Ubuntu virtual machine on vSphere, the system suddenly fails to boot, or the mounted data disk disappears? Error messages often contain Gave up waiting for root device or Timed out waiting for device dev-sdaX.

Fundamentally, it is because the Linux kernel, through device names (such as /dev/sda,/dev/sdb) to identify disks, whereas vSphere by default Do not expose stable disk UUIDs to virtual machines. When virtual machine hardware configuration changes (such as adding/removing disks or changing controller order), or after cloning/migration, the SCSI order of disks may change, causing the original /dev/sda became /dev/sdb, so the system naturally cannot find the correct root file system.

This article describes how to use a vSphere advanced configuration parameter disk.EnableUUID, fundamentally solve this problem.

Problems solved

Question	Description
Cannot start after cloning	When cloning a virtual machine, the SCSI node numbers of disks may be reassigned, causing the in fstab /dev/sda1 Pointing to the wrong device.
Device name drift	After adding or removing a virtual disk,/dev/sda,/dev/sdb the corresponding relationship may change.
The app depends on the device identifier.	Some applications (such as databases, Oracle ASM, and ZFS) read the disk UUID directly to identify member disks; without this parameter, they will not work properly.
Automated operations and maintenance are difficult.	If tools such as Ansible and Terraform rely on fixed disk identifiers, they will fail when environments are inconsistent.

Turn on disk.EnableUUID = TRUE Afterward, vSphere generates a fixed, unchanging UUID for each virtual disk and passes it to the Guest OS through VMware Tools, so that it can in /dev/disk/by-uuid/ and /dev/disk/by-id/ Visible and stable under the path.

Brief description of the working principle

• If this parameter is not enabled: the Linux kernel can only see the device name (such as sda), unable to obtain the underlying VMware virtual disk UUID.

• After enabling this parameter: VMware Tools writes the disk UUID to scsi In the device's sysfs attributes, the system kernel can use this information to generate persistent by-uuid and by-id symbolic links.

How to enable: vSphere Web Console steps

• Shut down the virtual machine(Some versions allow online modification, but it is recommended to shut down before performing the operation.)

• In vSphere Client, right-click the virtual machine →Edit Settings.

• Switch to Virtual machine options Tab → Expand Advanced→ Click Configuration parameters other Edit configuration.

• Click Add parameter, input:

• Name:disk.EnableUUID

• Value:TRUE

TIP

If the parameter already exists but its value is FALSE, change to TRUE That will do.

• Click Confirm Save, then Start the virtual machine.

Verification method

Method 1: Check the by-uuid directory

Execute inside the Ubuntu virtual machine:

ls -l /dev/disk/by-uuid/

Before enabling, it may be empty or not contain the UUID of the virtual disk; after enabling, you should see something like:

lrwxrwxrwx 1 root root 10 Jun 11 10:00 12345678-9abc-def0-1234-56789abcdef0 -> ../../sda1

Method 2: Check the by-id directory

ls -l /dev/disk/by-id/

After successful activation, something similar to wwn-0x6000c29... or scsi-36000c29... persistent identifier of.

Method 3: Use the blkid command

sudo blkid

The output should include the UUID of the disk partition.

Method 4: View SCSI device properties (lowest-level verification)

cat /sys/block/sda/device/vpd_pg83

After successful enabling, the disk's WWN (World Wide Name) information will be displayed.

Use UUID in fstab for permanent mounting

After verifying that the UUID takes effect, modify /etc/fstab Replace the device name with UUID:

• View the UUID of the target partition:

blkid /dev/sda1

• Edit /etc/fstab:

sudo vim /etc/fstab

will be similar /dev/sda1 /boot ext4 defaults 0 2 change the line to:

UUID=12345678-9abc-def0-1234-56789abcdef0 /boot ext4 defaults 0 2

• Reload fstab and test:

sudo mount -a

Precautions and Frequently Asked Questions

Question	Solution
After enabling the parameter, the UUID is still not visible inside the virtual machine.	Ensure it is installed and running VMware Tools(open-vm-tools). Execute systemctl status open-vm-tools Check.
Will the UUID change after cloning a virtual machine?	will change. Each time you clone or deploy from a template, vSphere generates a new disk UUID. This is exactly the expected behavior: to avoid disk UUID conflicts between different virtual machines.
Can parameters be added without shutting down?	vSphere 6.7 and later versions support modifying some parameters online,disk.EnableUUID 通常需要Restart the virtual machine Only then can it take effect.
Do you need a Windows virtual machine?	Not required. Windows identifies disks using the disk signature (Disk Signature) and is not affected by this parameter.
Does it affect performance?	None. This parameter only affects how information is exposed and does not change the I/O path.

Summary

In a vSphere environment, enable for Ubuntu (and other Linux distributions) virtual machines disk.EnableUUID = TRUE is a Extremely low cost, high returns configuration changes. It can effectively avoid boot failures, mount errors, and other problems caused by device name drift, and is one of the best practices for building reliable virtualization infrastructure.

A one-sentence suggestion: From today on, enable by default for all Linux virtual machines disk.EnableUUID, and in /etc/fstab Use UUID for mounting—this will save you a lot of troubleshooting time.

Further reading

• VMware KB 1021525:disk.EnableUUID Parameter Details

• Ubuntu Community Documentation: Using UUID in fstab

• VitePress Official Documentation— the static site generator used in this article