How to Safely Rename a KVM Virtual Machine: A Step-by-Step Guide
As your virtualization environment grows, maintaining a clear and consistent naming convention for your virtual machines (VMs) becomes essential for effective management. Whether you’re reorganizing your infrastructure or correcting a typo, you might find yourself needing to rename a KVM virtual machine.
However, you’ll quickly discover that there is no direct virsh rename command. The process is more involved, requiring you to manipulate the VM’s XML configuration file. While it requires care, following a structured process ensures you can rename your VM without losing data or breaking its configuration.
This guide provides a safe, step-by-step method for renaming a KVM domain (the term virsh uses for a VM) using the virsh command-line tool.
Prerequisites
Before you begin, ensure you have:
- Root or sudo access to the KVM host server.
- The current name of the virtual machine you intend to rename.
- Familiarity with a command-line text editor like
nanoorvim.
You can list all existing VMs, including their current states, with the following command:
virsh list --all
Step 1: Shut Down the Virtual Machine
First and foremost, you must shut down the target VM. Attempting to modify a running VM’s configuration can lead to file corruption and an unstable state.
Use the virsh shutdown command to gracefully power down the machine. Replace old-vm-name with the actual name of your VM.
virsh shutdown old-vm-name
Verify that the VM has been successfully shut down by running virsh list --all again. Its state should be listed as “shut off.” If it doesn’t shut down, you may need to use the destroy command, which is equivalent to unplugging the power cord.
virsh destroy old-vm-name
Step 2: Export the VM’s XML Configuration
With the VM offline, you need to export its current configuration to an XML file. This file contains all the settings for the VM, including its name, memory, CPU allocation, and disk paths.
Use the virsh dumpxml command to save the configuration. It’s a good practice to name the file after the new name you plan to use.
virsh dumpxml old-vm-name > new-vm-name.xml
Step 3: Edit the Configuration File to Change the Name
Now, open the newly created XML file (new-vm-name.xml) with your preferred text editor.
nano new-vm-name.xml
Near the top of the file, you will find the <name> tag. This defines the VM’s current name. Change the content within this tag to your desired new name.
<!-- Find this line -->
<name>old-vm-name</name>
<!-- And change it to this -->
<name>new-vm-name</name>
Save and close the file.
Step 4: Rename the Virtual Disk File (Recommended)
For consistency and to avoid future confusion, it’s highly recommended to also rename the VM’s virtual disk file (e.g., the .qcow2 file).
First, locate the virtual disk path by examining the XML file you just edited. Look for the <disk> section and the <source file='...'/> tag.
<disk type='file' device='disk'>
<driver name='qemu' type='qcow2'/>
<source file='/var/lib/libvirt/images/old-vm-name.qcow2'/>
...
</disk>
Once you have the path, use the mv command to rename the file.
mv /var/lib/libvirt/images/old-vm-name.qcow2 /var/lib/libvirt/images/new-vm-name.qcow2
After renaming the disk file, you must update the XML configuration to point to the new file path. Open new-vm-name.xml again and update the <source file='...'/> line to reflect the change.
<!-- Change the source file path to match the new disk name -->
<source file='/var/lib/libvirt/images/new-vm-name.qcow2'/>
Save and exit the file one last time.
Step 5: Undefine the Old Virtual Machine
Now it’s time to remove the old VM’s configuration from libvirt. The undefine command removes the registration of the VM.
This is a critical step. If you skip this, you will get an error when trying to define the new VM, as libvirt will detect a conflict with the existing UUID.
virsh undefine old-vm-name
Important: The undefine command only removes the XML configuration. It does not delete the virtual disk file, so your data is safe.
Step 6: Define the New Virtual Machine from the Edited XML
With the old configuration removed, you can now import, or “define,” the new configuration using your modified XML file.
virsh define new-vm-name.xml
If the command executes successfully, you’ll see a message like Domain new-vm-name defined from new-vm-name.xml.
Step 7: Start and Verify the Renamed VM
Your virtual machine has now been successfully renamed. You can start it using its new name:
virsh start new-vm-name
Finally, verify that the VM is running correctly and appears with its new name in the list:
virsh list --all
You can now also safely delete the temporary XML configuration file (new-vm-name.xml) to keep your directory clean.
By following these steps carefully, you can confidently rename your KVM virtual machines while ensuring data integrity and a clean, manageable virtualization environment.
Source: https://kifarunix.com/how-to-rename-kvm-virtual-machine-with-virsh-command/
