Rename virtual machine files and folders on vSAN Datastore.

Products

• VMware vSAN

Issue/Introduction

Symptoms:

• VM display name has been changed and would like to change the files name to match the display name on vSAN datastore.

• Renaming a virtual machine file or folder on vSAN (formerly known as Virtual SAN) Datastore using datastore browser does not work.

• Rename task fails with error: Error caused by file [vsanDatastore] <VM Name>

• Before executing any setAttr commands, confirm the target object is the correct VM namespace:
Run: /usr/lib/vmware/osfs/bin/objtool getAttr -u <UUID>

• Inspect the output for Object path and Object class.

• Ensure Object path does not contain .vsan.stats or other system-level directories.

• Ensure Object class is vmnamespace.

• If the object appears to be a system component, do not proceed.

Environment

VMware vSAN 8.x

VMware vSAN 9.x 

Cause

Renaming of virtual machine files and folders on vSAN Datastore is currently not supported.

Resolution

To work around this issue, use one of these options:

Rename VM files and folders using Storage vMotion

1. This option can be used if no downtime is available for the virtual machine.

2. Use storage vMotion (requires another datastore - VMFS or NFS) to migrate the virtual machine to a new location and then migrate it back to vSAN Datastore. For more information, see Renaming a virtual machine and its files in VMware ESXi

Rename the VM Namespace object (VM Folder Name) using objtool from ESXi CLI:

 

⚠️ IMPORTANT: These steps require the virtual machine to be powered off. Ensure a healthy backup of the VM exists before proceeding. Use objtool with caution as improper usage can impact object accessibility.

1. Unregister virtual machine from the vCenter Server.

2. Connect to ESXi host via SSH and navigate to the vSAN datastore:

   For Example: $ cd /vmfs/volumes/vsan:526a4992########-######7f0####1

3. List the contents of the datastore and take note of Namespace UUID of the virtual machine.

   $ ls -l
lrwxr-xr-x 1 root root 36 <DATE><time> TestVM -> ########-####-####-####-########a80e

   Note: In the above example, the Namespace uuid is ########-####-####-####-########a80e.

4. Run the below command to create a new folder with the Namespace UUID.

   For the above example, run:

   $ /usr/lib/vmware/osfs/bin/objtool setAttr -u ########-####-####-####-########a80e -n "NewTestVM"
Object set attribute succeeded

5. The old virtual machine folder (TestVM) would now be renamed to NewTestVM

   Note: Replace the Namespace UUID with the one in your setup.

   There might be a delay of few minutes in reflecting this change. To refresh immediately restart the vSAN OSFSD service from SSH by running the command /etc/init.d/osfsd restart

6. Register the virtual machine from the new folder using Datastore Browser.

Rename VM folder using Datastore Browser.

 

⚠️ IMPORTANT: These steps require the virtual machine to be powered off. Ensure a healthy backup of the VM exists before proceeding. Use objtool with caution as improper usage can impact object accessibility.

1. Power-Off the virtual machine.

2. Un-register the virtual machine from vCenter Server Inventory.

3. Connect to the ESXi host via SSH and navigate to the vSAN datastore: cd /vmfs/volumes/vsan:#######-######-####-####
4. List the contents of the datastore to identify the Namespace UUID: ls -l
5. Run the verification command: /usr/lib/vmware/osfs/bin/objtool getAttr -u <UUID>

6. Create a new directory on the vSAN Datastore with the name virtual machine has to be renamed.

7. Move or copy the virtual machine files to the new directory using the Datastore browser.

8. Once the files are moved to new folder, use objtool utility to fix the object attributes for the UUID to see from new folder. Use the instructions in the KB Moving vSAN VMDKS from one Namespace Folder to another does not update the Object Path Attribute to fix the attributes.

9. Re-register the virtual machine using the VMX file in the new virtual machine folder.

Change the VMDK names on vSAN datastore.

In order to change the VMDK names and append the attributes, follow the instructions in the KB Moving vSAN VMDKS from one Namespace Folder to another does not update the Object Path Attribute.

Additional Information

If you need any further assistance on this contact-broadcom-support.