VMware

VIX 1.6.2 Released! | Main | Change a VM's IP address with vmrun

December 09, 2008

Managing VM guests using vmrun.

The easiest way to get started with VIX is by using the vmrun command which is packaged inside of VIX. It's a command-line executable that doesn't require a development environment, and is pretty easy to use once you get the hang of it.

Since I mostly use ESX, I want to take an ESX-centric view of using vmrun in this post, and I'm also going to focus on what you can do to the guest operating system within VMs. Specifically I'm going to address two use cases that I think are pretty important and useful:

  1. Installing an agent within a VM.
  2. Restarting a service on a Windows VM.

First, you'll need to install VIX 1.6.2. On Windows you'll find vmrun in %PROGRAMFILES%\VMware\VMware VIX. On Linux it should be available in your path, so you can just run it from anywhere. Next, make sure you've got an ESX 3.5 update 2 or higher server to run commands against. In addition, you'll need a VM whose operating system is running an up-to-date copy of VMware tools.

If you type vmrun with no arguments you'll get a listing of all the things vmrun can do, but I want to focus on guest operations, which are listed below.

Table 1: Guest operations supported by vmrun.

Operation Description Supported on ESX?
runProgramInGuest Run a program in Guest OS Yes
fileExistsInGuest Check if a file exists in Guest OS Yes
setSharedFolderState Modify a Host-Guest shared folder No
addSharedFolder Add a Host-Guest shared folder No
removeSharedFolder Remove a Host-Guest shared folder No
listProcessesInGuest List running processes in Guest OS Yes
killProcessInGuest Kill a process in Guest OS Yes
runScriptInGuest Run a script in Guest OS Yes
deleteFileInGuest Delete a file in Guest OS Yes
createDirectoryInGuest Create a directory in Guest OS Yes
deleteDirectoryInGuest Delete a directory in Guest OS Yes
listDirectoryInGuest List a directory in Guest OS Yes
copyFileFromHostToGuest Copy a file from host OS to guest OS Yes
copyFileFromGuestToHost Copy a file from guest OS to host OS Yes
renameFileInGuest Rename a file in Guest OS Yes
captureScreen Capture the screen of the VM to a local file No
writeVariable Write a variable in the VM state No
readVariable Read a variable in the VM state No

Use case: Installing an agent in your VM.

Installing agents is an integral part of managing large numbers of systems, whether physical or virtual. Usually you want to bake your agents into your OS image, but occasionally a new agent will come along that needs to be deployed to existing systems. This example shows how you can copy an agent from your desktop to your VM and install it. The only thing you need is an agent that can be installed without user intervention (which is the norm for agents anyway).

Please note: Commands should be entered all on one line, it's split up here just for the sake if fitting it into the blog.

Example 1: Copying an MSI file from your desktop to your VM.

vmrun -T esx -h https://esx.example.com/sdk
  -u root -p secretpw -gu user -gp userpw
copyFileFromHostToGuest "[storage1] Windows/Windows.vmx"
  "c:\program files\my agent software\agent.msi" c:\agent.msi

One thing to point out here is that, despite the command saying "From Host to Guest" the file is actually being copied from the same system where vmrun is invoked (for example your laptop or workstation).

Next we use runProgramInGuest to install the MSI.

Example 2: Invoke the MSI file we copied above.

vmrun -T esx -h https://esx.example.com/sdk
  -u root -p secretpw -gu user -gp userpw
  runProgramInGuest "[storage1] Windows/Windows.vmx"
  c:\agent.msi

Use case: Restarting a service on Windows.

This one's really easy so I'll just show it without explanation.

Example 3: Restart a service on Windows.

vmrun -T esx -h https://esx.example.com/sdk
  -u root -p secretpw -gu user -gp userpw
  runProgramInGuest "[storage1] Windows/Windows.vmx"
  c:\windows\system32\net.exe restart dhcp

If Linux is more your style, tweak the last part to say something like /etc/init.d/sshd restart and you'll be restarting Linux services just as easily.

How do I get the path to my VMX file?

The hardest part about dealing with vmrun when you're managing ESX is knowing where your VMX file is. To get this you have to either log in to your ESX system and locate the VMX file, or you can use the VI API. Within the VI API, the VirtualMachine object contains a data structure called VirtualMachineFileInfo. The vmPathName property of this structure tells you the path to your VMX file. Not very pretty, but over time you'll see us rolling out some more convenient ways to access the functionality VIX provides. In the meantime there's a lot of really useful stuff you can do with tools like vmrun.

TrackBack

TrackBack URL for this entry:
http://www.typepad.com/services/trackback/6a00d8341c328153ef0105364df0dc970b

Listed below are links to weblogs that reference Managing VM guests using vmrun.:

Comments

Kelvin Nicholson

I've really had some fun after finding out about VIX, even for little hacky tasks: http://www.kelvinism.com/howtos/beginning-scripting-esxi/

Thanks for releasing another useful tool!

Tejas

Does copyFileFromHostToGuest() this Vix API copy security information also? (ACL, EA)

Carter Shanklin

@Tejas

Not in the current releases. We are working on ACL, so stay tuned.

Caine Chow

I'm just getting into VMWare and ESX and trying to use vmrun on a windows 2008 box to list vms on an ESX4 server.

I am using vmrun 1.8 with the following:

vmrun -T esx -h https://66.1.1.122/sdk -u root -p list

But I get "Unable to connect to host. Error: The specified version was not found" I haven't seen this anywhere on the net yet and was hoping that you may have seen it before.

Any help you can give is much appreciated.

Chris

I was wondering if copyFileFromHostToGuest will ever support the copying of a folder and all subfolders and files.

I am trying to find a way to do this but have had no luck yet.

igferne

what are the differences between vmrun and VIX API??

Avinash Gaonkar

Hi all,
When i use the following command to copy a file from vmware host to Linux guest, i encounter "Error: Invalid user name or password for the guest OS"

Following is the command used.please let me know if i am missing some parameters.I used same command to copy file to a windows guest and it worked fine.

vmrun -T esx -h https://X.X.X.X/sdk -u root -p Netmagic001 -gu netmagic -gp Netmagic001 copyFileFromHostToGuest "[ha-datacenter/NMESXN1_SR] vyatta-vmware-esx4_VC6.1-2010.08/vyatta-vmware-esx4_VC6.1-2010.08.vmx" install.log.syslog /home/netmagic/install.log
Error: Invalid user name or password for the guest OS

Rajiv M

Is there a hacky fix or workaround for read/write variables from/to the guest OS. I've been trying really hard to obtain the IP address of the virtual machine, by reading the guest variable "ip" which is supposed to be populated by VMWare Tools.

FYI, I'm attempting this implementation of the VIX API with VIX 1.6.2 and running it on VM images hosted on an ESX 4.0 server.

Any help would be much appreciated.Thanks.

Roger

igferne, you shouldnt post your username and passwords in public forums.

Roger

sorry, it was meant for Avinash Gaonkar

Post a comment

If you have a TypeKey or TypePad account, please Sign In.

About this Blog

This blog discusses VMware VIX API for automating VM and guest operations on VMware Server, Workstation and ESX.

Subscribe via RSS  

Community


Discussions and resources for:

VIX API Community

VMware Developer Community

Twitter


Facebook

YouTube


    VMware Blogs