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"

Performing General Administrative Tasks with vmrun

The vmrun tool can be used to perform a number of general administrative tasks such as listing running virtual machines, installing VMware Tools in a guest operating system and registering virtual machines.

To list the currently running virtual machines on a VMware Server host:

vmrun -T server -h https://myhost:8333/sdk -u root -p mypassword list
Total running VMs: 2
[Vol1] win2008-1/win2008-1.vmx
[Vol1] CentOS 5.2/CentOS 5.2.vmx

The VMware Tools installation process may be initiated package may be installed from the command line as follows:

TO BE COMPLETED

vmrun -T server -h https://myhost:8333/sdk -u root -p mypassword -gu root -gp 3579xps 
            installTools "[Vol1] CentOS 5.2/CentOS 5.2.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. The virtual machine may started either with a GUI console visible, or no console using the gui and nogui options.

• stop - Powers off the specified virtual machine. The power off process can be specified as hard or soft.

• reset - Reboots the specified virtual machine. The reboot process can be specified as hard or soft.

• Suspend - Suspends a virtual machine allowing fast restart via the start command. The suspend process can be specified as hard or soft.

• pause - Pauses the specified virtual machine.

• unpause - Unpauses a paused virtual machine.

When the hard option is specified for the stop and suspend commands, the virtual machine state changes without giving the guest operating system the opportunity to execute shutdown or hibernate procedures (analogous to disconnecting the power to a physical computer system). To ensure an ordered power off or suspension, be sure to specify the soft option. For example, to power off a specific virtual machine residing on host named vmhost using the soft method:

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

Similarly, to subsequently start 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

Using vmrun to Work with Guest Operating Systems Files and Directories

A particularly powerful feature of vmrun is the ability to interact with files residing in a guest operating systems from either host, or a remote system. For example, vmrun can be used to identify the existence of a file in a specific virtual machine guest, delete a file, create a directory and copy files between guest and host. In each case, a user name and password valid for logging into the guest operating system must be provided using the -gu and -gp flags.

The following command require that VMware Tools be installed in the guest operating system. For more details on VMware Tools refer to the chapter entitled Understanding and Installing VMware Tools.

To check for the existence of a particular file:

vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu fred -gp guestpasswd 
           fileExistsInGuest "[Vol1] CentOS 5.2/CentOS 5.2.vmx" /home/fred/MyFile

The file exists.

To delete a file on a guest:

vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu fred -gp guestpasswd 
            deleteFileInGuest "[Vol1] CentOS 5.2/CentOS 5.2.vmx" /home/fred/MyFile

To create a new directory in a guest filesystem:

vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu fred -gp guestpasswd 
            createDirectoryInGuest "[Vol1] CentOS 5.2/CentOS 5.2.vmx" /home/nas/foo

To remove a directory from a guest filesystem:

vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu fred -gp guestpasswd 
            deleteDirectoryInGuest "[Vol1] CentOS 5.2/CentOS 5.2.vmx" /home/nas/foo

To list the files in a guest system directory:

vmrun -T server -h https://xps:8333/sdk -u root -p 3579xps -gu fred -gp guestpassword 
            listDirectoryInGuest "[Vol1] CentOS 5.2/CentOS 5.2.vmx" /home/fred
Directory list: 5
.esd_auth
.dmrc
.gconfd
.recently-used.xbel
Desktop

To copy a file from the host system to the guest operating system (i.e copy the file /home/fred/MyFile on the guest to /tmp/MyFile on the host):

 vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu fred -gp guestpasswd 
      copyFileFromGuestToHost "[Vol1] CentOS 5.2/CentOS 5.2.vmx" /home/fred/MyFile /tmp/MyFile

Conversely, the copy a file from the host to the guest:

 vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu fred -gp guestpasswd 
      copyFileFromHostToGuest "[Vol1] CentOS 5.2/CentOS 5.2.vmx" /tmp/MyFile /home/fred/MyFile 

To rename a file on the guest:

 vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu fred -gp guestpasswd 
      renameFileInGuest "[Vol1] CentOS 5.2/CentOS 5.2.vmx" /home/fred/MyFile /home/fred/MyNewFile

Capturing a Virtual Machine Screenshot

A screenshot of the console of a running virtual machine may be captured and written to a file on the host using the vmrun captureScreen. The name of the file to which the image is to written is supplied as a parameter to the command. Note that the image is created in PNG format, so the file should be given the appropriate .png filename extension. For example:

 vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu fred -gp guestpasswd captureScreen "[Vol1] CentOS 5.2/CentOS 5.2.vmx" /home/fred/images/vm_screen.png