Virtualization Pro

January 14, 2008  4:23 AM

Printing a VI server’s inventory

Kutz Profile: Akutz

Here is a quick Perl script I wrote to print out your VI server’s (VC or ESX) inventory. I know what you’re thinking, “Um, aren’t there already examples that do this?” Yes and no. See, most examples you find, including VMware’s own, will print out all the VMs or the VI hierarchy as defined by the SDK. My script prints out the inventory based on the hierarchy that is displayed in the VI client. Here is some example output:

[0]akutz@amends:$ --server --username akutz --password mypassword 
[Folder] foo 
  [Datacenter] foo_dc 
[Datacenter] austin 
  [ClusterComputeResource] garage 
    [ResourcePool] coldair 
      [ResourcePool] hotair 
        [ResourcePool] rp2 
        [VirtualMachine] purple.lostcreations.local1 
      [ResourcePool] wheel 
        [ResourcePool] rp3 
    [ResourcePool] rp4 
    [HostSystem] mandy.lostcreations.local 
    [HostSystem] morning.lostcreations.local

The printinventory script, and others, can be found on my web site or you can browse directly to the printinventory code view.

Why should the inventory you see be any different that what the VI client shows you? Sometimes it is helpful to be able to produce the same output as another program. Especially if you’re attempting to mimic that program’s functionality. Coming up, ivi.

January 10, 2008  7:17 PM

VI SDK examples, logging out in style with Java

Kutz Profile: Akutz

Over the past few weeks many users have begun to e-mail me asking for not just help with the VI SDK, but code examples as well. I am more than happy to help, but I want to be able to help as many people as I can. To that end I have decided to post all of my code examples online for everyone’s benefit. You can access these examples at Examples will generally be available in C#, Java, and VIPerl. If you have an idea for an example, or a language you would like to see it in, please let me know!

The first example that I have posted is how to log into and out of the VI SDK Web service. There are examples in C#, VI Perl, and Java. With Java though there is a catch. See, you cannot actually successfully logout of the VI Web service with Java — it will throw an exception. This is a known bug according to some of VMware’s own code examples — they say that the logout function is not yet implemented.

However, this is not acceptable for anyone writing, oh, I don’t know, an OS-agnostic version of the VirtualInfrastructure client in Java. There has to be a way to force the session to log off. Well there is, but before I tell you what it is I will tell you the methods I first attempted at that failed:

Method 1

The first thing that I tried was to use the TerminateSession method and terminate my own session. Unfortunately terminating your own session is prohibited (I *could* on the other hand terminate someone else’s).

Method 2

The second hair-brained scheme I came up with was using the CreateScheduledTask method to invoke a script on the remote server that would terminate my session given my session ID. Unfortunately I was simply not able to get this to work. I tried it in C#, Java, and VI Perl, but I could not get a task created with action type RunScriptAction. Please let me know if you can get this to work.

Method 3

The method that finally worked involves TerminateSession in VI Perl. Using a VI Perl script I wrote called I terminate my own session by invoking said Perl script from within the Java example. It isn’t pretty, but it works. And until VMware fixes their stuff, it will have to do.

Hope this helps!

January 9, 2008  5:14 PM

Provisioning for networking redundancy with VMware ESX, VirtualCenter 2.5

Rick Vanover Rick Vanover Profile: Rick Vanover

When planning your next VMware ESX server installation that will be managed by VirtualCenter 2.5, make sure you provision for redundant networking for the ESX service console port. VirtualCenter 2.5 gives you a warning if you only have one interface assigned as the role of service console port, but earlier versions of VirtualCenter did not give this message. It is recommended, but not required, to have redundant networking for the service console port. If you only have one interface assigned, VirtualCenter will display the following indicator on the cluster:

Virtual Center 2.5 Management Network Redundancy

Protect against hiding other errors

If (like me) you upgraded to VirtualCenter 2.5 and had only one interface assigned for the service console port role, this error will remain present on your cluster indefinitely. This is only a warning, but the problem with this situation is that should a new error arise, you would not know because the indicator on the cluster is always displayed and you would not notice it as new. I had this happen on ESX 3.01 and 3.02 hosts. I expect 3.5 hosts to behave in the same fashion.

If you have recently upgraded to VirtualCenter 2.5 and now have this error message displaying, one thing you can consider doing is taking one of your interfaces from a teamed vswitch for a virtual machine network that does not need redundancy (like a test network) and reconfiguring it on the network and within VirtualCenter to be on the same network as the service console port. Once it is available, bring it in as a standby member to clear the warning.

January 3, 2008  7:46 PM

Use disconnected network adapters for build and stage: Save yourself

Rick Vanover Rick Vanover Profile: Rick Vanover

In VMware ESX, you can configure a guest operating system to have its network adapter disconnected at power on. This is critically important for a phase of a physical to virtual (P2V) migration where the system is migrated yet there are some offline tasks to be done. This can also be during a build before you go live. This configuration will present the virtual hardware inventory to the guest operating system – but it will appear as if the cable were unplugged. In this situation, you can configure all of your IP addressing (though you could not test it), DNS information, and other environment factors entirely offline of your network. Should you need some files or other access, a CD-ROM image would be a good way to prep up the system. I use the term “Stage Configure” for a virtual machine that is being prepped for prime time, and when I am complete with the configuration the option is reverted back to connect at power on (the default). This would include computer names, network configuration, services management for Windows systems, some benchmarks on performance, as well as any other local configuration elements.

To configure a virtual machine to not have its network connected at power-on, edit the settings of a virtual machine and deselect the option as shown in the figure below:

Configuration of Network Interface

Once you are done with your staging configuration, power off the virtual machine and change the option back to connecting at power on.

Extra Step in Protection

With VMware ESX, it is simply too easy to accidentally cause conflicts that may arise from having a candidate virtual machine on the network too early and performing its intended tasks. Errors can be a duplicate IP address, the application on the virtual machine picking up data simultaneously as the live system, formatting issues from a newer version of a business system feeding results to another system, and many other situations.

January 2, 2008  9:45 PM

Introducing Monét

Kutz Profile: Akutz

Monét (as in “Count de…”) stands for “Monitors Events and Tasks” and monitors an ESX or VirtualCenter server, recording tasks to standard out, a syslog server, or a Windows event log server. For example, the following is an example of the VI Perl version of Monét monitoring my VirtualCenter server, including its own logon and logout events:

[0]akutz@amends:akutz$ --username akutz --password mypassword --server --monitorType both --monitorSelf --syslogServer

The above command would produce the following output on the command line:

Monitoring server. Press any key to quit...
Jan 1 17:17:11 amends monet: TYPE=event; CHAINID=11682; KEY=11682; USER=LOSTCREATIONS\akutz; DESCRIPTION=User LOSTCREATIONS\akutz@ logged in

Additionally, the following log would be recorded on the syslog server in the /var/log/monet.log file:

Jan 1 17:17:11 amends monet: TYPE=event; CHAINID=11682; KEY=11682; USER=LOSTCREATIONS\akutz; DESCRIPTION=User LOSTCREATIONS\akutz@ logged in

Monét enables IT administrator to rely upon their existing monitoring software to pay attention to the activities of VMware ESX and VirtualCenter. Combined with a log analysis tool like Splunk, an IT administrator could easily determine when the most VMotion operations are occurring, which VM administrator is using the system the most, or even how many VMs have been created in a given date range.

Perhaps most importantly, Monét is a good example for developers who are interested in creating applications with the VI3 SDK framework and the VI Perl Toolkit. This application teaches several important VI3 SDK concepts: creating property filters, waiting on updates, and creating multi-threaded VI3 SDK utilities. In my spare time I am also working on new versions of Monét implemented in Java, managed C++, and Visual Basic.NET.

You can read more about and download Monét from my website at

December 20, 2007  1:40 PM

Layer-2 network security with .NET and Perl

Kutz Profile: Akutz

I’ve written several articles on SearchServerVirtualization about the VI3 SDK and how to make the most of it with .NET. There is an as-yet unpublished article on how to implement Layer-2 network security with .NET using a program I wrote called gnicmod. Consider it part 4 in my series of leveraging the SDK with .NET. I will update this blog entry with a link to the article once it has been published. In the meantime, I wrote the same program again, but using Perl and the VI Perl Toolkit. I am going to start providing both .NET and Perl examples for all the programs and SDK articles I write in order to attempt to reach the widest audience (Java fans please forgive me).

Many information security and networking offices implement security at a Layer-2 level: they will shut networking ports off if they suspect abuse or have evidence of a compromised system. Like oil and water, Layer-2 security does not mix with virtualization, particularly with ESX and 802.1q and port groups. Shutting a single port off will simply result in VMs rearping on a new port, causing another port to be shut off, and so on. What is needed is the ability to shut off a VM’s virtual port. This blog details my Perl script, — a VI Perl utility designed to modify a VM’s virtual networking device’s connected and connectOnStart properties. The command is pretty simple. Per its documentation, here are some examples:

       Disconnect a VM’s guest’s NIC and do not allow it to be connnected on
       start.  −−server vcms.lostcreations.local −−username akutz
       −−password mypassword −−ipAddress

       Connect a VM’s guest’s NIC whose IP address has changed.  −−server vcms.lostcreations.local −−username akutz
       −−password mypassword −−name purple.lostcreations.local  −−connected

For a complete set of documentation you can take a look at the command’s man page. But enough of stuff documentation, let’s take a look at the script!

#!/usr/bin/perl -w
# Schley Andrew Kutz 

use strict;
use warnings;

use FindBin;
use lib "$FindBin::Bin/../";

use VMware::VIM2Runtime;
use VMware::VILib;
use XML::LibXML;
use AppUtil::XMLInputUtil;
use AppUtil::HostUtil;
use AppUtil::VMUtil;

# Get the necessary files from
# I recommend that you download these files and edit this portion
# of the script so that you do not have to pull them from mys server
# every time.
my $str_vmreconfig_xml = '/tmp/vmreconfig.xml';
my $str_vmreconfig_xsd = '/tmp/vmreconfig.xsd';
my $str_vmreconfig_xml_url = '';
my $str_vmreconfig_xsd_url = '';
if ( ! -e $str_vmreconfig_xml ) { system( "wget -qO $str_vmreconfig_xml $str_vmreconfig_xml_url" ); }
if ( ! -e $str_vmreconfig_xsd ) { system( "wget -qO $str_vmreconfig_xsd $str_vmreconfig_xsd_url" ); }

$Util::script_version = "1.0";

my %opts = (
        ipAddress => {
        type => "=s",
        help => "The IP address of VM.",
        required => 1,
        name => {
        type => "=s",
        help => "The name of the VM.",
        connected => {
        type => "",
        help => "This flag indicates that the network card should be in a connected state.",
        connectOnStart => {
        type => "",
        help => "This flag indicate that the network card should be connected when the VM boots.",


# Logon and save the session token to a file.
my $str_session_file = ".vipersession" . rand(1000);
Vim::save_session ( session_file => $str_session_file );

# Don't let prying eyes have access to your session token!
system( "chmod 0400 $str_session_file" );

my $str_entity_type = 'VirtualMachine';
my $str_ip_address = Opts::get_option( 'ipAddress' );
my $str_vm_name = Opts::get_option( 'name' );
my $int_connected = Opts::option_is_set( 'connected' );
my $int_connect_on_start = Opts::option_is_set( 'connectOnStart' );

# Find the VM by its IP address
my $o_entity_view = Vim::find_entity_view( view_type => $str_entity_type, filter => { 'guest.ipAddress' => $str_ip_address });

# If the VM could not be found at all then let the user know
if ( !$o_entity_view )
        Util::trace(0, "Could not find VM by IP address: $str_ip_address\n" );
        if ( $str_vm_name )
                Util::trace(0, "Finding VM by name: $str_vm_name\n" );
                $o_entity_view = Vim::find_entity_view( view_type => $str_entity_type, filter => { '' => $str_vm_name });
                if ( !$o_entity_view ) { Util::trace(0, "Could not find VM by name: $str_vm_name\n" ); }

# If the VM was found then let's configure its guest's NIC!
if ( $o_entity_view )
        # Get the name of the VM.
        my $str_vm_name = $o_entity_view->name;
        Util::trace(0, "Found $str_entity_type: $str_vm_name\n");

        # Get the name of the ESX host that is running this VM.
        my $o_esx_host = Vim::get_view( mo_ref=>$o_entity_view->summary->runtime->host );
        my $str_esx_host_name = $o_esx_host->name;

        # Report what this command is going to do.
        Util::trace(0, "Setting NIC properties to connected=$int_connected and connectOnStart=$int_connect_on_start\n");

        # Loop through the VM guest's NICs in order to find
        # the device ID of the NIC that has the IP address
        # we want to turn off/on. Store a reference to that
        # NIC's deviceConfigId so we can use it later to
        # compare it to the VM guest's virtual devices.
        my $arr_guest_nic_info = $o_entity_view->guest->net;

        # If no IP address was found that matched then use the 
        # first IP address. This happens when the VM is already
        # disconnected and has a private address that is not
        # what the user specified from the command line, but
        # the VM was discoveredy anyway because the user used
        # the 'name' option.
        my $int_device_id = @$arr_guest_nic_info[ 0 ]->deviceConfigId;
        foreach ( @$arr_guest_nic_info )
                if ( $_->ipAddress->[ 0 ] eq $str_ip_address )
                        $int_device_id = $_->deviceConfigId;

        # Find the virtual device that has the same key value
        # as that of the NIC which has the IP address we are
        # looking for.
        my $arr_vm_hardware_devices = $o_entity_view->config->hardware->device;
        my $str_vm_guest_nic_name;
        foreach ( @$arr_vm_hardware_devices )
                if ( $_->key eq $int_device_id )
                        $str_vm_guest_nic_name = $_->deviceInfo->label;

        # Prepare the vmreconfig.xml file that will be used to change
        # the VM guest's NIC proeprties.
        my $str_vm_guest_nic_name_connect = $int_connected ? $str_vm_guest_nic_name : "";
        my $str_vm_guest_nic_name_disconnect = $int_connected ? "" : $str_vm_guest_nic_name;
        my $str_vm_guest_nic_name_power_on = $int_connect_on_start ? $str_vm_guest_nic_name : "";
        my $str_vm_guest_nic_power_on_flag = $str_vm_guest_nic_name_power_on ? ( $int_connect_on_start ? "true" : "false" ) : "";
        my $str_vmreconfig_xml_tmp = "/tmp/vmreconfig.xml" . rand(1000);
        system( "sed " .
                "-e 's/\\\$str_vm_name/$str_vm_name/g' " .
                "-e 's/\\\$str_host_name/$str_esx_host_name/g' " .
                "-e 's/\\\$str_vm_guest_nic_name_connect/$str_vm_guest_nic_name_connect/g' " .
                "-e 's/\\\$str_vm_guest_nic_name_disconnect/$str_vm_guest_nic_name_disconnect/g' " .
                "-e 's/\\\$str_vm_guest_nic_name_power_on/$str_vm_guest_nic_name_power_on/g' " .
                "-e 's/\\\$str_vm_guest_nic_power_on_flag/$str_vm_guest_nic_power_on_flag/g' " .
                "$str_vmreconfig_xml > $str_vmreconfig_xml_tmp" );

        # Reconfigure the VM
        system( " " .
                "--server " . Opts::get_option( 'server' ) . " " .
                "--sessionfile $str_session_file " .
                "--filename $str_vmreconfig_xml_tmp " .
                "--schema $str_vmreconfig_xsd" );

        # Delete the temporary XML config file.
        unlink $str_vmreconfig_xml_tmp;

# Delete the session token file.
unlink $str_session_file;

# Logout of the session. This also invalidates the VM session token, FYI.

If you have any questions about the script feel free to e-mail me. Hope this helps!

December 19, 2007  7:13 AM

VMware ESX resource usage: Check out esxtop

Rick Vanover Rick Vanover Profile: Rick Vanover

I came across another nice tool in ESX 3.02 that gives a quick view of the resources in use – and the virtual machines position within the usage. If you have used much Unix or Linux, you have probably come across the top package. While top is not a very fancy package, it is available in ESX – and it does not really provide much useful information. ESX, however, provides a utility called esxtop that shows summary information on resources and the virtual machine inventory on the host. Take the following image example:


This gives a nice view of the resources being used by the ESX host – in VMware’s talk. One nice feature is that esxtop gives a nice safeguard in that the refresh interval minimum is two seconds. Old school top could have a refresh interval of 0 seconds by typing “s” to specify seconds, and entering zero. Then top would be the highest offender and quickly chew up resources. Interpreting this screen takes some pre-reading. For example, at the top of the screen, there is a value for CPU load average. The value of .25 indicates that this system averages only 25% utilization. If I were to see this system with a value of 1 – it would be fully utilized on average. Dig into the ESX Resource Management Guide online for some more options and configuration variables. Exiting esxtop is simple enough by entering “q” to return to the x shell.

December 19, 2007  7:11 AM

Virtual Center 2.5 – An IT pro’s first look

Rick Vanover Rick Vanover Profile: Rick Vanover

So I had the chance to install VMware Virtual Center 2.5, or VC 2.5 from the release of the series of updates, last week. I expected the VC upgrade to be rather uneventful. The upgrade was uneventful, but there are some new key differences that you should be aware of with the new interface and what things may look life after the install.

New safegaurds and upgrade process

The default configuration after the VC upgrade has put in some safeguards that accompany you in tasks you may be familiar using. One example within the VMware Infrastructure Client is putting a server into maintenance mode. You will get some more questions related to the virtual machines that are off or suspended if you want them migrated to another host, (That is a good idea should another person or automatic process want to power on a virtual machine when it is in maintenance mode). This appears via a new tab and process called DRS Recommendations for most configurations of a VMware cluster. From there you can follow the recommendations of migrating guests to another host.

During the upgrade, all of my virtual machines ran fine and were not effected by the configuration. The only issue I had was that one ESX host, a 3.01 host, would not re-add back into the Virtual Infrastructure client. The message I had was something about the virtual center agent service failing to install. I did some poking around and found that I could bounce the existing management service on the ESX host to allow the new VC agent to install. I did the following:

[root@vm-esxdev0001 root]# service mgmt-vmware stop[root@vm-esxdev0001 root]# service mgmt-vmware stop

This had my heart stop for a bit as I stopped the service, but there were no availability issues to my virtual machines running on this host, vm-esxdev001.

Resource Pools, Clusters, Datacenters, and VMware Host Inventory

Depending on your upgrade type, you may need to recreate these elements after the VC upgrade. So it would be a good idea to have your current configuration documented so that you can re-add them if necessary. And yet another reminder to make sure your ESX resource pools are configured correctly. And this would be the time to reconfigure any of the configuration parameters should that be required.

VMware Resources

VMware provides a consolidated upgrade guide for ESX 3.5 and Virtual Center 2.5 and a good compatibility matrix for versions of ESX and Virtual Center. Be sure to read the compatiblity matrix before doing anything. Depending on your configuration – an ESX upgrade may do you no good with certain versions of Virtual Center. This is why I started with the Virtual Center upgrade.

December 17, 2007  4:39 PM

Reconfiguring vmreconfig

Kutz Profile: Akutz

The Perl script,, is designed to reconfigure a virtual machine (VM). You can read more about it here. The tool can be used to make changes to the state of the VM. For example, you want to turn off a VM’s guest network interface card (NIC). You would use the command in conjunction with an XML file that contains the necessary options to turn off the NIC.

The command might look like: --username akutz --password mypassword --server vcms.lostcreations.local --filename vmgnicoff.xml

And the XML file might look like:

<?xml version="1.0"?>
          <Name>VM Network</Name>
          <Name>VM Network</Name>

This is where the trouble begins. The are a few problems with (and I suspect with the other VI Perl tools as well; I will be documenting their issues as I use them):

– Poor error messages
– Schema is poorly designed
– Incomplete Perl modules
– Documentation is misleading

Poor Error Messages

When you execute the above command here is the error you will receive

Error in 'vmgnicoff.xml':
Element 'Reconfigure-Virtual-Machine' [CT local]: The element content is not valid.

This doesn’t really tell us all that much, does it? This is common with the VI Perl scripts. After some digging we are able to figure out that this problem has something to do with the XML schema file.

Poorly Designed Schema

The vmreconfig.xsd XML schema document (XSD) file included with the VI Perl Toolkit is poorly designed. It requires that every element be present in the file even when not in use. If you were to open the XML file in an XML editor and link the provided schema file you get a warning that the “AddDevice” node is not present? Well, we are not trying to add a device, so why should we need it? It turns out that the schema file does not implement the “minOccurs” attribute on its node definitions (even though the Perl script can cope with the absence of these elements). The solution is to go through the schema file and add a “minOccurs=’0′” attribute to the appropriate locations. You can download a copy of the schema I’ve already marked up for this purpose here.

Now you can use the simpler, easier-to-read XML that is printed above.

Incomplete Perl Modules

However, the next time you run the command you will possibly receive yet another error:

Can't locate object method "new" via package "XML::LibXML::XPathContext" (perhaps you forgot to load "XML::LibXML::XPathContext"?)

This error occurs because some OSs do not have the XPathContext Perl module installed by default. To install this module from CPAN simply type:

sudo cpan XML::LibXML::XPathContext

That solves that problem.

Misleading Documentation

The last issue you can run into is the VMware documentation itself. The online documentation for clearly implies that the name that should be used with a network adapter is the name of the network it is associated with. The documentation uses the example “VM Network”. This is the default name of a port group created for use by VMs in ESX. In fact, if you use this name when attempting to make changes to a network device you will receive this message:

No reconfiguration performed as there is no device config spec created.

You must specify the name of the network adapter, not the network it belongs to.

In Summary

To make turn off and disconnect a VMs network adapter download my updated vmreconfig.xsd schema file and use the following XML:

<?xml version="1.0"?>
          <Name>Network Adapter 1</Name>
          <Name>Network Adapter 1</Name>

Hope this helps!

December 14, 2007  8:18 PM

Generating the XML necessary to create VMs with the VI Perl Toolkit

Kutz Profile: Akutz

It is a pain in the rear to generate XML on the fly. There just is not a fun way of doing it. Unfortunately this is what is required when creating, cloning, and altering VMs with the VI Perl toolkit. I went ahead and creating a very simple Perl script that will take HTML GET variables from the query string and build the necessary HTML. I also created an extremely simple HTML form to try out the script. Alternatively, you could call the script from Perl using the command wget. For example:

wget -O vmcreate.xml ""

This command will turn your input into a properly formatted XML file called vmcreate.xml that can be used with the VI Perl Toolkit command,, in order to create a VM.

The script takes the following input variables:

name: The name of the VM to create.
host: The host to initially create the VM on.
datacenter: The datacenter to create the VM in.
guestId: The guest ID of the VM. E.g. Windows 2003
datastore: The datastore to place the VM’s files in.
disksize: The size of the VM’s hard disk in megabytes.
memory: The amount of memory to allocate to the VM in megabytes.
numberOfProcessor: The number of processors to allocate to the VM.
nicNetwork: The name of the port group to assign the VM to.
nicPoweron: Whether or not the NIC is powered on (0=off,1=on)

Hope this helps!

Forgot Password

No problem! Submit your e-mail address below. We'll send you an e-mail containing your password.

Your password has been sent to: