kantver - Fotolia
Staying safe while manually modifying a VMX file
What happens when you can't make changes to a VM in the vSphere client? There's more than one way to tweak the configuration file.
For day-to-day management, an administrator does not go under the hood of the vSphere environment to modify the behavior of a virtual machine (VM). Usually, everything is done with the vSphere Web Client. But there may be a time when some manual intervention is needed to tune your virtual environment.
By following the guidelines in this article, an administrator can modify the VMX file for the VM to make the needed change, such as modifying a value or adding new parameters that cannot be done easily from either the vSphere desktop or Web clients.
Two possible scenarios for intervention
Why would you manually edit a VMX file? Let's say there is a customer who has upgraded the entire environment to vSphere 5.5 and upgraded all the VMs to hardware compatibility level 10. But what happens if the vSphere Web Client, the only client that can edit that VM, becomes inaccessible but the VM needs to be modified?
Let's say the VM port group needs to be moved to another network. One tool that can handle this is PowerShell, but not all administrators are familiar with PowerCLI scripting.
In another scenario, an administrator wants to add an advanced configuration to the VMs that cannot be done from the vSphere Web Client. For example, the administrator wants to change the working directory for the VMs to place snapshot files somewhere other than the default location, as described in VMware Knowledge Base article KB1002929.
The anatomy of a VMX file
The configuration for a VM is stored in a file with the extension of .VMX and is located in the VM's directory on a data store. It's a text file with a simple structure. Each line contains a parameter and the value for that parameter. Here is an example of a few lines from a configuration file:
virtualHW.version = "10"
displayName = "Win2008Main"
memSize = "4096"
scsi0.virtualDev = "pvscsi"
scsi0.present = "TRUE"
ethernet0.virtualDev = "vmxnet3"
ethernet0.networkName = "VM Network"
There are two methods for editing the configuration file, but for both methods, the necessary preparation steps are the same.
Step 1: Find the location of the VM
To access the VMX file on the data store of your ESXi host, we need to pinpoint where the VM resides. It can be as simple as looking at the summary of the VM, seen in Figure 1, and looking in the storage section of the Related Objects window.
The information from the image below might not be 100% correct. There can be multiple data stores listed because the configuration can be on a different location than the virtual disk files. Or the VM can be renamed which will change the display name but not the name of the VM folder and files. To be certain of the correct location, go to the VM configuration section and verify the location of the VM Config File field, as shown in Figure 2.
Step 2: Power off the VM
You can shut down the guest operating system or force the VM to power off if it does not contain the VMware Tools.
Step 3: Unregister the VM from your vCenter Inventory
Do this from the vSphere Web Client or vSphere Client on Windows by right-clicking the VM and selecting the option Remove from Inventory. The VM is then no longer listed but it remains on disk.
Method one: Download, modify and upload the VMX file
This method is the simplest. From the vSphere Web Client or vSphere Client on Windows, access the data store where the VM is located and browse the content. From there, browse to the VM directory and select the VMX file, as shown in Figure 3.
After downloading the file to your computer, create a backup of the file before making any changes.
You can modify the file on your computer with an editor such as Wordpad on Windows or another text editor. Note that some editors handle carriage returns and line feeds differently, such as Notepad. An editor that doesn't interpret these characters properly will list all content on a single line rather than separate ones.
After making the necessary changes to the file, upload the file to the same location. The last step is to register the VM again with vCenter by right-clicking the file and selecting the Register VM option from the menu.
Method two: Modify the VXM file directly from the command line
For this procedure, the administrator needs to be familiar with working in a command line interface (CLI).
First, open a command line session to your host either on the local console -- enabled from the Direct Console User Interface -- or through SSH. If you need guidance, there is helpful documentation from VMware called Getting Started with vSphere Command-Line Interfaces.
Use the cd command to browse to the VM directory located in /vmfs/volumes/your datastore/vm directory. You can list the files with the ls -l command, as in Figure 4 below.
Another tip: Use tab-completion to make your life simpler and prevent typing mistakes. After the cd command, type the first letter of the directory name and press tab to auto-complete the file name. Or press tab twice to display a list of choices if there is more than one.
After verifying the VMX file's location, you can modify it with an editor. Again, create a backup before making any changes. Use the cp command to copy the file; typically, I will give it a .BAK extension to indicate the file is a backup.
The editor that is available on almost everything with a command line is VI, so it's a good idea to find out how it works. VMware's Knowledge Base article KB1020302 explains how to modify a file with VI.
After finalizing changes to the file, register the VM in vCenter from the command line using this command:
vim-cmd solo/registervm path to the vmx file
In Figure 5 below, the output of the previous command is 139, which is the object identifier in the inventory, indicating the VM was registered successfully.
