Home > Blogs > VIX API Blog > Author Archives: Carter Shanklin

Author Archives: Carter Shanklin

PowerWF: Build workflows that use VIX and more!

It's been a while so I thought I'd dust off the old VIX blog to talk about a new tool out there called PowerWF.

PowerWF has also posted quite a log of screencasts that can help you get a sense of the product. My brief description would be that PowerWF is a workflow builder based on Windows Workflow Foundation and specializing on workflow for virtual environments. The current version gives you more than 200 actions, including Windows Workflow Foundation (which gives you things like flow control for workflows), VIX (which gives you the ability to manage VMs as well as run programs within them), Secure Shell, and others. Here's a little taste of the VIX activities.

Untitled 

For some more info you might want to head over to Eric Sloof's blog or you can visit PowerWF directly. It seems PowerWF will also be adding support for PowerCLI within the next week or two, which should be pretty exciting for all you vSphere admins out there, so stay tuned.

Call VIX more easily from .NET (plus PowerShell goodness)

A lot of great new VIX stuff is coming up from all over, this time it's Daniel Doubrovkine on the VIX community telling us about a library he's created that makes calling VIX from .NET really easy. If you're a .NET minded individual this stuff will make your life a lot easier, and it supports everything VIX supports, Workstation, Server as well as ESX.

 

Below I offer just a small bit of proof about just how easy it really is by using it in a PowerShell script I whipped together in about 20 minutes. This script is designed to work with ESX and requires the VI Toolkit (for Windows) to be installed.

 

The script is basically yet another example of restarting a service in a guest, which you might as well be my version of "Hello World", still I'm really excited to see how much easier it's getting to manage your guests with VMware software.

 

Thanks Daniel!

 

# Before using this sample, download the Daniel Doubrovkine's VIX

# interoperability library from

# http://www.codeproject.com/KB/library/VMWareTasks.aspx

# and change the variable below to point to it.

$vestrisDir = "C:\Vestris.VMWareTasks"

 

# Run a script inside a VM using VIX. This should work against ESX 3.5

# U2 or higher, as well as VMware Server and Workstation. See below

# for an example.

function Invoke-Script {

    param ($hostCred, $guestCred, $vm, $command, $args)

 

    $vmo = get-vm $vm

    $vmView = $vmo | get-view

    $vmx = $vmView.config.files.vmpathname

 

    $hostNet  = $hostCred.GetNetworkCredential()

    $guestNet = $guestCred.GetNetworkCredential()

 

    add-type -path "$vestrisDir\1.0\Bin\Vestris.VMWareLib.dll"

    add-type -path "$vestrisDir\1.0\Bin\Interop.VixCOM.dll"

    $myHost = new-object vestris.vmwarelib.vmwarevirtualhost

    $myHost.ConnectToVMWareVIServer("https://" +

        $defaultVIServer.Name + "/sdk", 0, $hostNet.UserName,

        $hostNet.Password)

    $vm = $myHost.Open($vmx)

    $vm.Login($guestNet.UserName, $guestNet.Password)

    $vm.Execute($command, $args)

}

 

# Login stuff.

$ip = read-host "Enter the IP of your VC / ESX server"

write-host "Enter login and password to VC / ESX"

$hostCred = get-credential

write-host "Enter login and password to your VM"

$guestCred = get-credential

 

# Connect to ESX/VC

connect-viserver $ip -credential $hostCred

 

# This sample restarts the print spooler.

$command = "c:\windows\system32\net.exe"

$args    = "restart spooler"

Invoke-Script -hostCred $hostCred -guestCred $guestCred `

    -vm "Windows2k3SP2" -command $command -args $args

More VIX goodness, this time changing routes on Windows and Linux.

Cody Bunch over at Professional VMware has done it again, this time showing us how to add and delete routes on both Windows and Linux.

Those of us who follow Cody's blog are all wondering what tomorrow's big news is, my guess is we'll finally learn how many turtles you can fit on a rock.

You can also follow Cody on Twitter if you're in to that sort of thing.

Change a VM’s IP address with vmrun

Cody Bunch over at Professional VMware has an example that shows you how to change your IP address using vmrun. If you look carefully you'll see that despite getting an error as vmrun exits, he does manage to successfully change his IP address, so it seems to be fairly benign.

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.

VIX 1.6.2 Released!

Last week we released VIX 1.6.2, which officially adds support for remotely managing VMs on ESX servers, either directly or when accessed through vCenter (formerly known as VirtualCenter).

There's been quite a proliferation of VIX versions lately, so some comments are in order. VIX 1.6.0 and 1.6.1 managed VMware Workstation and VMware Server, respectively. These packages were distributed within the products and cannot be downloaded separately. 1.6.2 adds support for ESX / vCenter and is available for download separately.

If you're trying to make sense of all of this, here's a table that should help:

 

Release

Supported Products

 

VIX 1.6.0

Workstation 6.5.0

 

VIX 1.6.1

VMware Server 2.0

 

VIX 1.6.2

ESX, ESXi and vCenter

 

VIX 1.6.3

Workstation 6.5.1

There are some important compatibility notes, as well as other helpful information in our release notes. One thing the release notes don't mention is that VIX 1.6.2 should work against VMware Server 2.0, although it is not tested very rigorously. Still it may be good to do development and testing using 1.6.2, managing a remote VMware Server system, but think twice before doing anything production related.

In the next post I'll give some examples of how you can get going with VIX quickly and easily using vmrun.

Starting and stopping services inside VMs.

We launched our VI Toolkit for Windows 1.0 a little over a week ago and it’s been a bit of a time sink. Now that I’m looking to direct some attention toward some of the other things I deal with around here, this blog should start looking a bit more lively.

As I mentioned a long time ago in my first post, VIX provides some capabilities that you can’t get through any of our other APIs, specifically the ability to perform some very useful guest operations. In this post I’m going to examine how we can use some of these guest calls to run programs inside of VMs.

In this week’s edition: starting and stopping services with VIX.

This week I’ve got a sample of how you can use VIX to start and restart services inside of VMs. The key APIs here are APIs that let you log into a VM guest and run a program inside the VM guest. Here’s the code I use so you can play along at home. To run this code you’ll need 3 things:

  1. A compatible VMware product to run it against.
  2. A VM with VMware tools installed.
  3. VIX with Perl support. If you want to run this code against ESX like I do, you’ll need VIX 1.5, which you can get from the VMware Server 2.0 Beta or VMware Workstation 6.5 Beta.

The specific example I’ll cover here is that of starting the print service inside a Windows VM running on an ESXi server. Here’s a screenshot of my environment:

Vixshot1_2

Using the script above, here’s the command I can use to start the print spooler.

Vixshot2

Notice that this script requires two logins: first we must log into the host, then we must login to the VM itself to run the program. If you’re running this against a local VMware Workstation or Server, you don’t need to authenticate to the VM host, but you will still need a login to the VM guest. After executing this script, here’s what I see on the command line:

Vixshot3_2

There are some pretty ugly warnings there, but it gets the job done. In addition, we see the output of the command I executed so we know it was successful After hitting F5 in the guest console, here’s the "after" screenshot from the VI Client.

Vixshot4

As you can see, the service is started. Of course the script lets you run arbitrary commands, it’s not really specific to service management, there are a lot of things you can do with it. A few examples would be:

  1. Editing configuration files.
  2. Setting IP addresses on VMs that may not be networked.
  3. Lots, lots more.

Some assembly required.

This example is in Perl for two reasons, 1) It’s possible to run it on either Windows or Linux and 2) I have no idea how to write VB Script. If you’re on Linux, installing the VIX Perl module is fairly straightforward, but if you’re on Windows it can be very tricky since it requires a compilation environment that can be difficult to set up properly. To try to help for Windows users I’ve create an ActiveState PPM module that might work for you if you’re using ActiveState Perl. If anyone tries it, let me know your experiences — good or bad.

What is VIX and why does it matter?

Hi and welcome to the VMware VIX API blog. On this blog we’ll talk about what VIX is, how it can help you, giving you resources for using VIX, and providing lots of examples.

What is the VIX API?

VIX is an API that lets you programmatically control the products that host VMware VMs, and control the VMs themselves. If you’re considering learning more about the VIX API, chances are it’s because you need some form of automation. After all, if you deal with only a handful of VMs, it’s a lot easier to just use the GUI for eveything than it is to spend the time and effort to learn how to use a programming interface. But, if you’re spending lots of time managing all your VMs under VMware Server or Workstation, or even VMware ESX, learning VIX can help you be a lot more productive by automating the tasks you do every day.

Does any of this sound familiar?

If you’ve been researching VMware APIs, you might have heard a speech like the one above more than one time. VMware has gotten to the point where we have a somewhat dizzying array of APIs, and many of them sound like they do the same things. Let’s try to shed some light on this problem by first talking about what APIs can manage what products, then we’ll move to what sets VIX apart from other APIs and when you should use it in favor of others.

Matrix_3

There are a lot of caveats and footnotes that this simple diagram glosses over, but it’s good enough for our purposes. The key points are that, if you’re looking to automate management of VMware Workstation or Server, VIX is your best (sometimes only) bet. In addition, if you’re building solutions for ESX, you’ll find that VIX makes a powerful complement to the VI API (more on this below).

What kinds of things can VIX do?

A full listing of VIX’s capabilities is available in the VIX reference guide. A few of the highlights of what you can do with VIX include:

  1. Registering and unregistering VMs.
  2. Powering VMs on and off.
  3. Managing VM snapshots.
  4. Adding and removing VM shared folders.
  5. Copying files into and out of the VM guest.
  6. Starting and stopping processes within the guest.

A special note on managing VMware ESX with VIX.

Starting with VIX 1.5 and VMware ESX 3.5 update 1, it is possible to manage VMware ESX using VIX. My background is almost exclusively with VMware ESX and VMware VirtualCenter, and that tends to be my comfort zone. If you’ve used the VI API, you’re probably wondering why you should look at VIX. The reason is pretty simple, the VIX API provides critical functionality that the VI API lacks, for instance:

  1. VIX allows you to copy files in and out of guests.
  2. VIX allows you to start and stop processes within guests.
  3. With a bit of trickery you can run programs in the guest and get their output (more on this in another post).

In short, VIX allows you to treat the VM as more than just a black box, something none of the other APIs can do today. Before joining VMware, I worked for Opsware before it was acquired by HP, and specifically on software to manage VMware. We had a few important problems that we were never able to solve very well, such as "how do you install an agent onto a VM?", or "how do you start or stop a service within a VM?". There aren’t any good solutions when you use the VI API, but all of this stuff is easy when you have VIX.

Getting VIX.

The latest released version of VIX is 1.1.4, available on the VIX API landing page. I’ve also been talking about VIX 1.5. Currently, VIX 1.5 is not available as a standalone download. Instead you’ve got to download it from the VMware Server Beta 2.0 site. Later, VIX 1.5 will also be available as a standalone download.

What language bindings are available for the VIX API?

The VIX download provides support for 3 languages: C, Perl and COM. If those are not your thing, there are also some open-source projects, not endorsed in any way by VMware, that provide Java and Python bindings.

What resources are available for VIX?

First, you should familiarize yourself with the VIX documentation. Second is our VIX Community. A third resource I would recommend if you’re looking for a good source of examples is Eric Hammersley’s Professional VMware Server, which has a good chapter on VIX from the VMware Server perspective.