vSphere SDK for Perl 5.1
Release Notes

Released 10 Sept 2012

Build 780721 is the 5.1 release of the vSphere SDK for Perl.

vSphere SDK for Perl 5.1

Welcome to the vSphere SDK for Perl 5.1 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

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). The installation also includes the vSphere CLI command set.

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

What’s New in This Release?

The WSMan::StubsOps module was deprecated in the vSphere 5.0 release and will be removed. All SDK for Perl samples that are using WSMan::StubOps in vSphere 4.1 are using WSMan::GenericOps in vSphere 5.0 and later.  

Installing vSphere SDK for Perl

The SDK for Perl Linux installer behaves differently for RHEL and for other Linux distributions.

Installing vSphere SDK for Perl on RHEL

On RHEL, the vSphere SDK for Perl installer prompts you whether you want to install required Perl modules from the installation package or from CPAN. You can install from the package if you do not have Internet access.

  1. Uninstall any existing versions of vSphere SDK for Perl by running <install_dir>/vmware-uninstall-vSphere-CLI.pl. The default installation directory is /usr/bin.
  2. Delete any existing versions of: the SDK for Perl installation
     rm -rf <install_dir>/vmware-vsphere-cli-distrib
  3. Download and untar vSphere SDK for Perl 5.1.
  4. When prompted, choose Yes to install the missing Perl modules from the vCLI package.

The vSphere SDK for Perl Linux installer stops installation if required modules cannot be found on your Linux system. The installer installs other missing Perl modules, but does not overwrite existing versions of those modules. See the vSphere SDK for Perl Installation Guide.

Installing vSphere SDK for Perl on Other Linux Distributions

For other supported Linux distributions, the SDK for Perl installer works the way it did for SDK for Perl 5.0. If you have Internet access, you can also direct the RHEL installer to follow this procedure.

  • Explicitly uninstalling previous versions of the software is no longer required.
  • You must have access to the Internet to successfully install vSphere SDK for Perl.
  • You must set your http:// and ftp:// proxies, as follows:
    export http_proxy=http://<proxy_server>:port
    export ftp_proxy=http://<proxy_server>:port
  • The installer installs missing Perl modules from CPAN, but does not overwrite existing versions of those modules.

Note: Downloading modules from CPAN can take a long time.

See the vSphere SDK for Perl Installation Guide.

The vSphere SDK for Perl Windows installer works as before and installs the vSphere SDK for Perl, the vSphere CLI, and all prerequisite software including Active Perl 5.8.8. If you do not want to overwrite an existing Active Perl installation, exit the installer and use a different system for installing the software.

Important: Reboot your Windows system after installation. If you don't, ActivePerl might report that it cannot find some of the Perl modules.

Supported Platforms

SDK for Perl 5.1 is supported on the following Linux platforms:

  • Red Hat Enterprise Linux (RHEL) 5.5 (32 bit and 64 bit)
  • SLES 10 SP1 (32 bit and 64 bit)
  • SLES 11 (32 bit and 64 bit)
  • SLES 11 SP1 (32 bit and 64 bit)
  • Ubuntu 10.04 (32 bit and 64 bit)

SDK for Perl is supported on the following Windows platforms:

  • Windows 7 (32 bit and 64 bit)
  • Windows Vista Enterprise SP1 (32 bit and 64 bit)
  • Windows 2008 (64 bit)

The vSphere Management Assistant (vMA) is included vSphere SDK for Perl. You can deploy vMA on ESXi 5.1 systems. You cannot upgrade an existing version of vMA to include vCLI or vSphere SDK 5.0 or vCLI or vSphere SDK 5.1 by running the vCLI installer inside vMA.

Resolved Issues

  • 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.

  • Class::MethodMaker included with 4.1 installer does not work with Perl 5.10 The vSphere CLI and vSphere SDK for Perl installation package includes Class::MethodMaker 2.10. That module works fine with Perl 5.8.8, but does not work with Perl 5.10. Note that the vCLI and vSphere SDK for Perl do not require this module, but your scripts might require it.

  • 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.

  • 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.

  • 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.

Known Issues

vSphere SDK for Perl 5.1 has the following known issues:

  • On Linux, installing vSphere SDK for Perl on systems where vSphere CLI is installed results in unusable installation.
    If you install the vSphere SDK for Perl on a Linux system, and if vSphere CLI is already installed on that system, both products are not usable after the installer completes. This problem occurs regardless of the version of the two installers.

    Workaround: Do not install the vSphere SDK for Perl bundle. The vSphere SDK for Perl software is included in the vSphere CLI bundle. Install the vSphere CLI bundle.

  • Missing DLL error during first command execution after installation (Windows). A vSphere SDK for Perl installation on Windows completes successfully. However, when you later run a script, errors about missing DLLs might result. For example:
    libxml2.dll wasn't found

    Workaround: Reboot your Windows system.

  • 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 (rather than a specific subclass) as the view type 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).

  • 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