View source for How to Remotely Run, List and Kill Programs Running in a VMware Virtual Machine

With the VMware ''vmrun'' command line tool, it is possible to remotely launch and kill programs on a guest operating system running inside a VMware Server or VMware Workstation virtual machine.

The ''vmrun'' command is installed by default with VMware Server and VMware Workstation. In the case of VMware Server 2.0, vmrun is installed in ''\Program Files\VMware\VMware Server'' on Windows hosts and ''/usr/bin'' on Linux.

Note that in order to perform these tasks, VMware Tools must be installed on the guest operating system. For details on installing VMware Tools refer to the [[Understanding and Installing VMware Tools]] chapter of the Virtuatopia [[VMware Server 2.0 Essentials]] online book.

== Understanding vmrun Command Line Syntax ==

The basic command line syntax for using ''vmrun'' varies slightly between VMware products, but can generally be summarized as follows:

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

The ''host authentication flags'' are required to provide host, login and password information for the host system. 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:

<table border="1" cellpadding="5" cellspacing="0" id="E3B" style="border-collapse: collapse; border-color:#cccccc; border-style: solid; border-width: 1px; margin-bottom:20px">
<tr bgcolor="#cccccc" style="color:black" valign="top">
<th>
<p>Flag</p>
</th>
<th>
<p>Description</p>
</th>
</tr>
<tr>
<td>
<p>'''-h'''</p>
</td>
<td>
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,  <nowiki>https://myhostname:8333/sdk</nowiki>.
</td>
</tr>

<tr bgcolor="#e9e9e6">
<td>'''-P'''</td>
<td>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.</td>
</tr>

<tr>
<td>
<p>'''-T'''</p>
</td>
<td>
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.
</td>
</tr>

<tr bgcolor="#e9e9e6">
<td>'''-u'''</td>
<td>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.</td>
</tr>

<tr>
<td>
<p>'''-p'''</p>
</td>
<td>
The password corresponding to the user name specified with ''-u'' as outlined above.
</td>
</tr>
</table>

The ''guest password flags'' are specified if the ''vmrun'' tool 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:

<table border="1" cellpadding="5" cellspacing="0" id="E3B" style="border-collapse: collapse; border-color:#cccccc; border-style: solid; border-width: 1px; margin-bottom:20px">
<tr bgcolor="#cccccc" style="color:black" valign="top">
<th>
<p>Flag</p>
</th>
<th>
<p>Description</p>
</th>
</tr>
<tr>
<td>
<p>'''-gu'''</p>
</td>
<td>
A suitable user name via which vmrun may log into the specified guest operating system
</td>
</tr>

<tr bgcolor="#e9e9e6">
<td>'''-gp'''</td>
<td>The corresponding password for the guest user specified using the ''-gu'' flag.</td>
</tr>
</table>

The ''command'' argument identifies to ''vmrun'' the task to be performed on the specified virtual machine. For example, ''start'', ''stop'' and ''reset'' are all valid commands. Other commands are available to perform tasks within a guest operating system, such as ''runProgramInGuest'' and ''deleteFileInGuest''.

The ''parameters'' arguments specify optional information required for a specific command. If, for example, the ''stop'' command is specified, the parameters argument is used to reference the .vmx file of the virtual machine which is to be powered off. In the case of running guest commands, both the ''.vmx'' file of the target 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:

<tt>"C:\VMware\VMachines\win2008.vmx"</tt>

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 corresponding ''.vmx'' file within that datastore. 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):

<tt>"[Vol1] win2008/win2008.vmx"</tt>

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:

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

== Listing the Programs Running in a VMware Guest ==

A listing of the current process running on a guest operating system running in a VMware virtual machine can be obtained using the ''listProcessesinGuest'' command. In order for this command to work, a valid guest user name and password must be provided. The following example show a typical command used to obtain a process listing from a Windows Server 2008 system, together with part of the output listing:

<pre>
vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu administrator -gp guestpasswd 
     listProcessesInGuest "[Vol1] win2008-1/win2008-1.vmx"

Process list: 39
pid=0, owner=, cmd=[System Process]
pid=4, owner=, cmd=System
pid=392, owner=, cmd=smss.exe
pid=468, owner=, cmd=csrss.exe
pid=512, owner=, cmd=csrss.exe
pid=520, owner=, cmd=wininit.exe
pid=548, owner=, cmd=winlogon.exe
pid=596, owner=, cmd=services.exe
.
.
.
</pre>

== Running a Program in a VMware Guest System ==

To run a program within a guest operating system, use the runProgramInGuest command, together with the path to the program which is to run. For example:

<pre>
vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu administrator -gp guestpaswd 
  runProgramInGuest "[Vol1] win2008-1/win2008-1.vmx" -activeWindow "c:\windows\system32\cmd.exe"
</pre>

Note that in order to run a graphical application on a Windows Vista or Windows Server 2008 guest, the ''-interactive'' command must be used. Without this command, the guest Windows system will display an ''Interactive services dialog detection'' warning dialog stating that the program cannot be displayed on the desktop. 

By default, graphical programs started using ''vmrun'' on Windows guests will start in a minimized state (in other words the program will appear in the Windows task bar, but will not be displayed on the desktop). To force the program to appear on the desktop when it starts, the ''-activeWindow'' flag must be used.  The following example shows the combined use of the ''-interactive'' and ''-activeWindow'' flags to run and display the Windows Notepad program on a Windows Server 2008 guest system:

<pre>
vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu administrator -gp guestpasswd 
     runProgramInGuest "[Vol1] win2008-1/win2008-1.vmx" 
     -activeWindow -interactive "c:\windows\system32\notepad.exe"
</pre>

== Terminating a Program Running in a VMware Guest ==

To terminate a program running in a guest operating system, use the ''listProcessesInGuest'' command described above to ascertain the process id (pid) of the program in question and use that id (2368 in the following example) together with the ''killProcessInGuest'' command:

<pre>
vmrun -T server -h https://xps:8333/sdk -u root -p mypassword -gu administrator -gp guestpasswd 
              killProcessInGuest "[Vol1] win2008-1/win2008-1.vmx" 2368
</pre>