vmware-cmd

From time to time, I see this question come up asking how one might be able to extract a certain piece of information from either ESX(i) or the management APIs (vSphere API) from within a virtual machine. The simple answer is you can not, by default the guest operating system has no idea of the underlying hypervisor nor does it have the access to the management APIs. This of course, assumes you are following VMware's best practices in isolated and segregating off your management network from your virtual machine network.

Having said that, there are certain bits of information that you can extract about your ESX(i) host from within the guestOS using some of the utilities that is installed with VMware Tools. The first utility is called VMware Toolbox command which can be found on both UNIX/Linux and Windows systems that have tools installed.

UNIX/Linux - /usr/bin/vmware-toolbox-cmd

Windows - C:\Program Files\VMware\VMware Tools\VMwareToolboxCmd.exe

This utility provide some information about ESX(i) and guestOS configuration including basic resource statistics.

One interesting sub-command is the resource statistics about both ESX(i) and guestOS such as speed of the hypervisor's CPUs or the current balloon, swap, memory limit, memory reservations, cpu limit or cpu reservations.

Here is an example of retrieving ESX(i) CPU speed.

As I mentioned before, you do not have access to the management network that your ESX(i) are on and that also means you do not have access to the vSphere APIs. What if you wanted to to associate a specific piece of information from ESX(i) and be able to access that piece of information from the guestOS? You can do so with the vmtoolsd (VMware Tools Daemon) utility.

UNIX/Linux - /usr/bin/vmtoolsd

Windows - C:\Program Files\VMware\VMware Tools\vmtoolsd.exe

This utility has an option called --cmd that allows you to run various commands including one that allows you to extract guest information using the "info-get" parameter. This guestinfo can be set using two methods:

1) Hard-coded within the virtual machine's .vmx configuration file
2) In VMX memory while a virtual machine is running within ESX(i)

Option 1 is pretty straight forward, you can add a custom attribute that has the following format:

guestinfo.[variable] = [value]

e.g.
guestinfo.provision.date = "01/11/2011"

You can use the vSphere Client to add this custom attribute while the virtual machine is powered off or you can manually edit the .vmx configuration file. If you use the latter, you will need to reload the VM's configuration, you can use vim-cmd vmsvc/reload.[vmid] to do so. One the VM is powered on, you can extract this piece of information, here is an example:

Option 2 is actually pretty interesting as the configuration of the custom guestinfo variable is not permanently stored. What I mean by this is the configuration is only persisted while the VM is running. This is interesting because if you have runtime information that potentially could change, this allows you to dynamically present this information to the guestOS. One use case could be set for management VMs such vCenter running in a VM and you wanted to know at any given time which ESX(i) host is currently managing it. This can be trivial with vCenter access, but what if the service is offline but the virtual machine is still running? Using the classic ESX Service Console command vmware-cmd you can loop through all powered on VMs and set some custom variables for example the current hostname of the ESX host managing the VM and version it is currently on.

The syntax for the command would be the following:

vmware-cmd [VM_VMX_PATH] setguestinfo [VARIABLE_NAME] [VARIABLE_VALUE]

e.g
vmware-cmd /vmfs/volumes/4a48004d-f9af7fa0-5bbf-003048d9586b/scofield/scofield.vmx setguestinfo hypervisor.hostname $(hostname)

Note: Notice, you do not need to append the keyword guestinfo, you just need to specify the variable name. Once you are in the guestOS, to access the custom variable, you will need to specify the full name which should be "guestinfo.[VARIABLE]"

As you can see this can be tedious to set for each and every VM, so let's automate this using a script that will go through all powered on VMs and set two custom variables called "hypervisor.hostname" which will set the current hostname of the ESX host and "hypervisor.build" which will retrieve the build of your ESX. To further automate this since you might have multiple ESX hosts running in a DRS cluster, you would store this script in a shared storage (VMFS and/or NFS) and setting up a cronjob that would run at some interval to always provide the latest information to the guestOS.

Here is an example of a shell scrip that does exactly that:

#!/bin/bash

IFS=$'\n'

for VM in $(vmware-cmd -l);
do
        VM_STATE=$(vmware-cmd "${VM}" getstate | awk -F "= " '{print $2}')
        if [ "${VM_STATE}" == "on" ]; then
                echo "Setting info for ${VM}"
                vmware-cmd "${VM}" setguestinfo hypervisor.hostname "$(hostname)"
                vmware-cmd "${VM}" setguestinfo hypervisor.build "$(vmware -v)"
        fi
done

unset IFS

You will want to save this script to your ESX host and make sure the script has executable permissions for it to execute. You will also create a cronjob based on how often you want the script to run and this needs to be configured for every ESX host that you would like to take part in this update.

Here is an example of running the script every hour:

0 * * * * /vmfs/volume/shared-storage/setGuestInfo.sh > /tmp/out

Note: I redirect the output to /tmp/out to ensure that script is in fact working and once you have, you can remove that all together.

Here is an example of extracting these two custom variables on both a Linux and Windows VM:

As I mentioned earlier, option 2 does not persist these custom variables with respect to the VM's configuration file. The variable configuration only takes affect when the VM is powered on and once it is powered off, the information is discarded. To support ESXi, you can use the various vSphere SDKs (vSphere SDK for Perl, PowerCLI, etc) but what you will find is that the behavior of setting this attribute is similar to that of the local vmware-cmd on classic ESX, it does not append the entry into the .vmx configuration file.

Here is a vSphere SDK for Perl script called addVMAdvParamOption.pl that can be used to guestinfo parameter for a given VM. Here is an example of this script:

If you are using vMA, you can also use the vCLI's vmware-cmd utility to set this variable. The format is slightly different than that of the classic ESX's vmware-cmd. Here is an example of this:

Notice, the variable name must include "guestinfo." keyword before specifying the variable name.

If you wanted to persist these configurations, you will need to adjust your provision workflow to append the variables into the VM's .vmx configuration file.