Controlling VMware Virtual Machines from the Command Line with vmrun

For all the ease of use provided by VMware Server's graphical tools, perhaps the most powerful tool supplied with various VMware products is a little known command line utility called vmrun. Installed as standard with VMware Server, vmrun allows almost total control over virtual machines from the command line, either locally on the VMware Server host, or remotely over a network or internet connection. Capabilities of vmrun include starting, stopping, pausing, resuming and resetting virtual machines, executing commands within guest operating systems and taking snapshots. The primary goal of this chapter is to focus on these and other features of vmrun.

The Basics and Syntax of vmrun

The vmrun tool is installed by default with the VMware Server and VMware Workstation products. Assuming that a standard installation is performed, the vmrun executable is located in \Program Files\VMware\VMware Server on Windows hosts and /usr/bin on Linux.

The basic command line syntax for using vmrun varies between host platforms and VMware product, can be gnerally summarized as follows:

vmrun <host authentication flags> <guest authentication flags> <command> <parameters>

The host authentication flags are required to provide host information and the login and password for the host system to perform management tasks on the virtual machines. These are essentially the same credentials that would be used when accessing the VI Web Access management interface. These flags are required only on VMware Server hosts, and are not needed for VMware Workstation:

Flag	Description
-h	The https URL of the host to which vmrun is required to connect. Must also include the /sdk sub-directory and, optionally the port number (unless the -p flag below is used). For example, https://myhostname:8333/sdk.
-P	The port number used by the host for virtual machine management. By default this will be 8333. If the port is specified in the URL (see above) this flag is not required.
-T	The type of VMware product which is running on the host. Options are ws for VMware Workstation, server to VMware Server 2 and server1 for VMware Server 1.
-u	The user name on the host to be used to log into the VMware management interface. The same as the user name that would used when logging in using the VI Web Access interface.
-p	The password corresponding to the user name specified with -u as outlined above.

The guest password flags are specified if vmrun is required to log into the guest operating system to perform tasks such as work with guest files or execute commands. If such operations are not required, these flags may be omitted from the command line:

Flag	Description
-gu	A suitable user name via which vmrun may log into the specified guest operating system
-gp	The corresponding password for the guest user specified using the -gu flag.

The command argument instructs vmrun on the task to be performed. For example, start, stop and reset are all valid commands. As are the commands to perform tasks within a guest operating system, such as runProgramInGuest and deleteFileInGuest.

The parameters arguments specify additional information required for a specific command. If, for example, the start command is specified, the parameters argument is used to reference the .vmx file of the virtual machine which is to be started. In the case of running guest commands, both the .vmx file of the taregt virtual machine and the path to the program to be executed must be provided as parameters.

When specifying the virtual machine on which a command is to be executed, the location of the virtual machine .vmx configuration file must be provided. For VMware Workstation, this involves specifying the full path of the file. For example:

"C:\VMware\VMachines\win2008.vmx"

In the case of VMware Server 2.0, which introduced the concept of datastores, the name of the datastore in which the virtual machines resides must be provided together with the path of the .vmx file which that store. For example, to reference a virtual machine stored in the win2008 sub-directory of the Vol1 datastore, the vmrun path parameter would be defined as follows (note that the datastore name is enclosed in square brackets and separated from the sub-directory by a space character):

"[Vol1] win2008/win2008.vmx

Bringing all of these different command line arguments together, a typical vmrun' command to start a virtual machine on a host named vmhost running VMware Server 2 might appear as follows:

 vmrun -T server -h https://vmhost:8333/sdk -u root -p mypassword stop "[Vol1] win2008/win2008.vmx"

Controlling Virtual Machine Power States with vmrun

The power states of virtual machines can be controlled either locally or remotely using the vmrun tool. The commands associated with these tasks are as follows:

• start - Powers on the specified virtual machine

• stop' - Powers off the specified virtual machine

• reset - Reboots the specified virtual machine

• pause - Pauses the specified virtual machine

• unpause - Unpauses a paused virtual machine

For example, to start a specific virtual machine residing on host named vmhost:

 vmrun -T server -h https://vmhost:8333/sdk -u root -p mypassword stop "[Vol1] win2008/win2008.vmx"

Similarly, to subsequently reboot the same virtual machine:

 vmrun -T server -h https://vmhost:8333/sdk -u root -p mypassword reset "[Vol1] win2008/win2008.vmx"

Virtual Machine Snapshots with vmrun

VMware allows snapshots of virtual machines to be taken, whereby the state of a virtual machine (including the guest operating system) may be saved and then restored at a later date. This feature is particularly useful when performing operating system or application testing. Whilst snapshots may be taken and restored using the VI Web Access interface, it is often quicker and more convenient to use the vmrun tool. As with other vmrun commands, the appropriate authentication, host and virtual machine arguments must be provided along with a snapshot name.

The following example takes a snapshot (named MySnapshot) of a virtual machine using the snapshot command:

 vmrun -T server -h https://xps:8333/sdk -u root -p mypassword snapshot "[Vol1] CentOS 5.2/CentOS 5.2.vmx" MySnapshot

The corresponding command to revert the virtual machine to the snapshot state uses the revertToSnapshot command and would read as follows:

 vmrun -T server -h https://xps:8333/sdk -u root -p mypassword revertToSnapshot "[Vol1] CentOS 5.2/CentOS 5.2.vmx" MySnapshot

Note that if the virtual machine is running at the time the revertToSnapshot command is issued, the virtual machine will be placed into the suspended state while the restoration process is performed. To resume the suspended virtual machine using the restored state, it may be resumed using the vmrun start command as follows:

 vmrun -T server -h https://xps:8333/sdk -u root -p mypassword start "[Vol1] CentOS 5.2/CentOS 5.2.vmx"

Finally, an existing snapshot may be deleted using the deleteSnapshot command:

vmrun -T server -h https://xps:8333/sdk -u root -p mypassword deleteSnapshot "[Vol1] CentOS 5.2/CentOS 5.2.vmx" MySnapshot