Renaming a virtual machine and its files in VMware ESXi and ESX (KB1029513)

Purpose

This article provides information on how to rename a virtual machine and its files via SSH, System Management Interface, or directly at its console.

Renaming a virtual machine using the vSphere Client only changes the display name, not the corresponding files on the datastore. It may be useful to also rename the virtual machine's files to maintain consistency.

Resolution

Note: Storage/Cold Storage vMotion or using the console renames only the folder names and not the files in ESXi 5.0. This behavior was changed to support Storage DRS on ESXi 5.0. For more information, see vSphere 5 Storage vMotion does not rename virtual machine files on completing migration (2008877).

A virtual machine's files may be renamed during a disk migration operation, such as Cold Storage Migration, or by manually renaming them in-place from the ESXi/ESX console. Select your preferred method.

Alternatively, a virtual machine could be cloned to a new virtual machine using the Clone method in vCenter Server or using vCenter Converter, and deleting the old virtual machine.

Renaming virtual machine files using Storage vMotion

A virtual machine's files can be renamed on the fly during a Storage vMotion initiated from the vSphere Client. The renaming occurs with no downtime.

To rename the files on ESXi/ESX 4.x and 3.5 hosts:

1. Log in to the VMware vSphere Client.
2. Locate the virtual machine in your host inventory.
3. Right-click the virtual machine and click Rename.
4. Change the virtual machine name as required.
5. Begin a Storage vMotion or an offline Storage Migration of the virtual machine. For more information, see:
   • ESXi/ESX 4.x – Migration with Storage vMotion section of the vSphere Datacenter Administration Guide.
   • ESXi/ESX 3.5 – Migration with Storage vMotion section of the Basic Administration Guide.
6. After the migration completes, the virtual machine files match the virtual machine name configured in step 4.
   Note: The Storage vMotion only changes the names of the virtual machine files when the destination datastore is different from the original.

Note: If a virtual machine directory already exists on the datastore with the same name, then the target virtual machine is placed in a new directory with _1 appended.

Renaming virtual machine files using Cold Storage Migration

The files of virtual machine can be renamed on the fly when a Cold Migration is initiated from the vSphere Client in ESX/ESXi 4.x. In ESXi 5.x, only the virtual machine's folder is renamed.

To rename the files:

1. Log into the VMware vSphere Client.
2. Locate the virtual machine in your host inventory.
3. Right-click the virtual machine and click Rename.
4. Change the virtual machine name as required.
5. Perform Cold migration to a new datastore of the virtual machine.
   
   For more information, see:
   • For ESXi/ESX 4.x, see Cold Migration in the vSphere Datacenter Administration Guide.
   • For ESXi/ESX 3.5, see Cold Migration in the Basic Administration Guide.
6. After the migration completes, the virtual machine files match the virtual machine name configured in Step 4.

Note: If a virtual machine directory already exists on the datastore with the same name, then the target virtual machine is placed in a new directory with _1 appended.

Renaming virtual machine files in-place using the console

Warning: Before proceeding, ensure that:

• The virtual machine has a current backup, and that it has been powered down.
• The virtual machine does not have snapshots or virtual disks shared with other virtual machines.

To manually rename the virtual machine's files:

1. Log into the VMware vSphere Client.
2. Locate the virtual machine in your host inventory.
3. Power down the virtual machine.
4. Right-click on the virtual machine and click Remove from inventory.
5. Open a console to the ESXi/ESX host. For more information, see Unable to connect to an ESX host using Secure Shell (SSH) (1003807) or Using Tech Support Mode in ESXi 4.1 and ESXi 5.x (1017910).
6. Navigate to the directory containing the virtual machine. For example:
   
   # cd /vmfs/volumes/DatastoreName/originalname
7. Rename the virtual disk (VMDK) files using the vmkfstools -E command. For more information, see Renaming a virtual machine disk (VMDK) via the vSphere Management Assistant (vMA) or vSphere CLI (vCLI) (1002491).
   
   # vmkfstools -E "originalname.vmdk" "newname.vmdk"
   
   Notes:
   • In some cases, it may be required to clone (copy) a virtual disk. To clone a virtual disk to a new virtual disk, run this command:
     
     # vmkfstools -i "originalname.vmdk" "newname.vmdk"
     
     This leaves the original virtual disk untouched. You need enough space available to clone the virtual disk in the destination directory. In the case of the command above, the new virtual disk is created in the current directory but a different directory can be specified.
   • You need not rename the originalname-flat.vmdk file after running the vmkfstools command. The vmkfstools command renames both VMDK files and updates the reference within the descriptor.
   • Do not use the cp or mv commands to rename virtual disk files. Instead, use VMware utilities such as vmkfstools.
8. Copy the virtual machine configuration file (.vmx) using the command:
   
   # cp "originalname.vmx" "newname.vmx"
9. Open the file new virtual machine configuration (for example, newname.vmx) in a text editor. For more information, see Editing configuration files in VMware ESXi and ESX (1017022).
   
   For example:
   
   # vi "newname.vmx"
10. Within the configuration file, modify all old instances of the virtual machine's file names to the new file names. At a minimum, modify these values (more may exist):
    
    nvram = " newname.nvram"
    displayName = " newname "
    extendedConfigFile = " newname .vmxf"
    scsi0:0.fileName = " newname .vmdk"
    [...]
    migrate.hostlog = "./ newname -UUID.hlog"
    
    Repeat this process for each virtual machine disk. For example:
    
    scsi0:1.fileName = " newname _1.vmdk"
    scsi0:2.fileName = " newname _2.vmdk"
    
    Correct the VMkernel swap file reference. For example:
    
    sched.swap.derivedName = "/vmfs/volumes/DatastoreUUID/ newname/ newname-UUID.vswp
    
    Note: Be sure to rename both the .vswp file and the directory name for the swap file, in bold above.
11. Correct any other remaining lines referencing the original path or file names.
12. Save the file and exit the editor.
13. Rename all the remaining files, except the .vmx configuration file, to the new names.
    
    For example:
    
    # mv "originalname.nvram" "newname.nvram"
14. Change directory to the parent directory:
    
    # cd ..
15. Rename the directory for the virtual machine:
    
    # mv "originalname" "newname"
16. Using the VMware vSphere Client, browse the datastore and navigate to the renamed virtual machine directory.
17. Right-click the virtual machine's new configuration file (for example, newname.vmx) and select Add to inventory.
    
    Alternatively, you can use this command to add the virtual machine to the inventory:
    
    For ESX:
    
    # vmware-cmd -s register "/vmfs/volumes/DatastoreName/newname/newname.vmx"
    
    For ESXi:
    
    # vim-cmd solo/registervm /vmfs/volumes/DatastoreName/newname/newname.vmx
18. Power on the virtual machine.
19. A question for the virtual machine displays in the Summary tab during power-on. Review the question by:
    • Clicking the Summary tab.
    • Right-clicking the virtual machine in your inventory and selecting Answer question.
      
      When prompted, select I moved it, then click OK.
      
      Warning: Selecting I copied it results in a change of the virtual machine's UUID and MAC address, which may have detrimental effects on guest applications that are sensitive to MAC address changes, and virtual machine backups that rely on UUIDs.
20. Optionally delete the original virtual machine configuration file.
    
    For example:
    
    # rm /vmfs/volumes/DatastoreName/newname/originalname.vmx