vSphere SDK for Perl Release Notes

Released 21-May-2009

Build 161974 is the release build for the package that includes vSphere Command-Line Interface 4.0 and vSphere SDK for Perl 4.0.


vSphere SDK for Perl 4.0 Release Notes

Welcome to the vSphere SDK for Perl 4.0 release.

The vSphere SDK for Perl provides an easy-to-use Perl scripting interface to the vSphere Web Services API.

This document contains the following information:

See the vSphere Command-Line Interface Release Notes for information about vSphere CLI issues.

About the vSphere SDK for Perl 4.0

The vSphere SDK for Perl is a client-side Perl framework that provides an easy-to-use scripting interface to the vSphere API. Administrators and developers who are familiar with Perl can use the vSphere SDK for Perl to automate a wide variety of administrative, provisioning, and monitoring tasks in the vSphere environment. The vSphere SDK for Perl includes ready-to-use utility applications, which you can immediately put to use in your virtual datacenter.

The vSphere SDK for Perl installation includes the WS-Management Perl Library, which allows you to write scripts that retrieve CIM data from the ESX host using CIMOM, a service that provides standard CIM management functions over a WBEM (Web-Based Enterprise Management).

You can use the SDK to manage ESX 3.0.x, ESX/ESXi 3.5, ESX/ESXi 4.0, vCenter Server 2.5, and vCenter Server 4.0.

The SDK is tested and supported on the following platforms:

  • Linux:
    • Red Hat Enterprise Linux (RHEL) 5.2 (32 bit and 64 bit)
    • Ubuntu Desktop 8.04
    • SUSE Enterprise 10 (SP1)
    • vSphere Management Assistant (vMA) (64 bit only). See the vMA documentation for hardware requirements.
  • Windows
    • Windows Vista Enterprise SP1 (32 bit and 64 bit)
    • Windows XP SP 3 (32 bit and 64 bit)

What’s New in This Release?

This release of the vSphere SDK for Perl includes the following new features:

  • Support for vSphere Credential Store. You can use the vSphere SDK for Perl credential store library to automate the logon process for non-interactive client applications by storing the password in a secured local credential cache. At runtime, your applications can then access the credential cache. The /apps/general directory of your vSphere SDK for Perl installation includes an example. The vSphere SDK for Perl Programming Guide includes documentation.
  • Installer Change. vSphere SDK for Perl 4.0 is bundled with the vSphere Command-Line Interface (vSphere CLI). The vSphere CLI command set allows you to run common system administration commands against ESX/ESXI systems from an administration server of your choice. When you install vSphere SDK for Perl, both vSphere CLI and vSphere SDK for Perl are installed.
  • Documentation Updates . The vSphere SDK for Perl Programming Guide includes information about deploying and using vMA and about managing and using the credential store.

Resolved Issues

The following issues have been resolved in the vSphere SDK for Perl 4.0 release:

Filter Arguments for Some Utility Applications Do Not Work.  Using --maintenancemode 0 or --vmotion 0 with hostinfo.pl does nothing. Using --maintenancemode 1 or --vmotion 1 with hostinfo.pl returns no results.

When you use the --guestos filter with a utility application, the application returns nothing.

Resolution: This problem has been fixed.


Cannot Use hostops.pl to Move or Add Standalone Host to Datacenter Root Host Folder.  The moveintofolder and addstandalone operations for hostops.pl take a folder name as a destination, as an argument to the --folder command-line option. Omitting --folder should place the host into the datacenter's host folder. However, calling the hostops.pl operations moveintofolder and addstandalone without a folder name either fails or places the host into a random folder, which is not necessarily the host folder.

Resolution: This problem has been fixed.

Known Issues

The vSphere SDK for Perl 4.0 has the following known issues:

Obtaining Objects of Different Types Requires Multiple Calls to the Vim::get_views() Subroutine.  The Vim::get_views() subroutine takes a reference to an array of managed object references and returns a reference to an array of view objects. Although the array can contain multiple managed-object types, objects of only one type can be obtained at the same time.

Workaround:  You can call get_views() multiple times to obtain multiple object types. Or you can specify the appropriate base class as the view type (rather than a specific subclass) to access values of properties that are common across all objects based on the superclass. For example, view_type = 'ManagedEntity' allows you to retrieve all objects that extend from this base class (VirtualMachine, HostSystem, Folder, ResourcePool, and so on).


On Windows, Warnings During Startup if chcp Program Not Available.  On Windows operating systems, if the chcp program is not present or is not in your PATH environment variable, vSphere SDK for Perl programs display the following warning message on startup:

'chcp' is not recognized as an internal or external command, operable program or batch file.

If this happens, vSphere SDK for Perl uses a default character encoding. In some cases, some characters might not display correctly, but otherwise, programs function normally.

Workaround:  To avoid the message, make sure chcp is installed and in your PATH


Must Use Encoded Representation When Constructing Filters That Recognize Names Containing Certain Special Characters.  Based on what the vSphere Web Services API returns, a few property values, such as ManagedEntity.name, VirtualMachineConfigInfo.name, and VirtualMachineConfigSpec.name, are returned with the characters ’/’, ’\’, and ’%’ encoded as %2f, %5c, and %25.

For example, if you have a Folder named My%Folder, its name is returned as My%25Folder. If you want to construct a filter that recognizes names containing slashes or percent signs, you must use the encoded representation.

Workaround: To match a name that contains a percent sign, write:

filter => { name => qr/%25/ }

You cannot perform a match on percent sign alone, because a percent sign alone also matches other characters that are preceded by a percent escape character.

filter => { name => qr/%/ } # wrong;

You must use case-insensitive matching for escape character sequences that contain alpha characters:

filter => { name => qr/%2f/i } # matches %2f and %2F


Error running credstore_admin.pl on some SUSE 10 installations.  When you run the /apps/general/credstore_admin.pl script on a SUSE 10 system, the following error might result:

*** glibc detected *** /usr/bin/perl: free(): invalid pointer: 0x083d0339 ***

The probable cause for the error is that an older version of perl-XML-LibXML than the version included with the vSphere CLI / vSphere SDK for Perl package was already installed on the system. As a result, the installer did not add the required version of perl-XML-LibXML to the SUSE system.

Workaround: First uninstall the perl-XML-LibXML package, and then reinstall the vSphere CLI and vSphere SDK for Perl package. The required version of perl-XML-LibXML is installed by that installer.


Problem with extractlog.pl if virtual machine is not directly within datacenter.  The extractlog.pl utility application works only if the requested virtual machine is directly contained within its containing datacenter. If the virtual machine is located in a folder, including the normally invisible Discovered Virtual Machines folder, the application generates an invalid URL. No log is retrieved.

Workaround: Move the virtual machine in the inventory so that it is located directly within its datacenter.


List of hosts returned by hostinfo.pl is sometimes incomplete.  The hostinfo.pl utility application does not always return the correct list of hosts. When you call the application with no filtering arguments, it does not display hosts that are in maintenance mode or hosts that have VMotion enabled.

Workaround: No workaround


lcrypto installation error on some Linux platforms.  When you install the package that includes the vSphere SDK for Perl and the vSphere CLI, you might see the following error on some Linux platforms:

ld: cannot find -lcrypto Unable to link the Crypt::SSLeay Perl module. Secured connections will be unavailable until you install the Crypt::SSLeay module.

The error indicates that OpenSSL is not available on that system.

Workaround: Install OpenSSL, as described in the vSphere SDK for Perl Installation Guide.


find_entity_view and find_entity_views cannot retrieve the view for vSphere 4.0 objects.  You cannot call find_entity_view or find_entity_views with the view_type parameter pointing to an object introduced in vSphere 4.0. This includes the following objects:

  • Network
  • Datastore (not Datacenter)
  • VirtualApp
  • DistributedVirtualSwitch
  • VMwareDistributedVirtualSwitch
  • DistributedVirtualPortgroup

Workaround: You have these choices:

  • Load the entity's container, for example, Folder in the case of DistributedVirtualSwitch, and then use get_view to load the entity based on its managed object reference.
  • Use a vSphere Web Services SDK property collector.

Installing the vSphere SDK for Perl

Starting with vSphere 4.0, the vSphere Command-Line Interface (vSphere CLI) and the vSphere SDK for Perl are always installed together. VMware provides several different packaging options. See the vSphere SDK for Perl Installation Guide.

  • vSphere SDK for Perl Windows installer — Installs ActivePerl from ActiveState and all required Perl libraries for the vSphere SDK for Perl runtime.
  • vSphere SDK for Perl Linux installer — Perl script that requires Perl 5.8 (or subsequent version) and OpenSSL 0.9.7 (or OpenSSL 0.9.8). If your Linux distribution does not include the required version of SSL, you must install it using CPAN or the update mechanism for the distribution.
  • vMA (OVF file) — Virtual machine that includes vSphere SDK for Perl, vSphere CLI, and some other software.
  • vSphere SDK for Perl source code bundle — A .tar.gz bundle of all source code files for making and installing the vSphere SDK for Perl on any platform that supports Perl.

Note that upgrades between scripted and source code installations are not supported, that is, the source installer does not place the files in the same location as the scripted installer.

Last updated 19-May-2009