vSphere SDK for Perl 4.1
Release Notes

Released 13 Jul 2010

Build 254719 is the 4.1 release of the vSphere SDK for Perl.

vSphere SDK for Perl 4.1 Release Notes

Welcome to the vSphere SDK for Perl 4.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).

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

What’s New in This Release?

This release of the vSphere SDK for Perl does not include new functionality. The Linux installer for vSphere SDK for Perl and vSphere CLI has changed, as discussed next. The updated vSphere SDK for Perl Installation Guide reflects the new behavior.

Supported Platforms

You can install vSphere CLI on the following Windows platforms:

  • Windows XP SP3 32 bit
  • Windows 2003 32 bit
  • Windows Vista Enterprise SP1 32 bit
  • Windows 2008 64 bit

You can install vSphere CLI on the following Linux platforms:

  • Red Hat Enterprise Linux (RHEL) 5.2 (32 bit and 64 bit)
  • SLES 10 (32 bit and 64 bit)
  • SLES 11 (32 bit and 64 bit)
  • Ubuntu 9.04 (32 bit and 64 bit)

vSphere CLI is also included in the vSphere Management Assistant (vMA), a virtual machine which includes prepackaged software. Developers and administrators can use vMA to run agents and scripts to manage ESX and ESXi systems. vMA 4.1 includes vSphere CLI 4.1 running on a CentOS system.

Installing vSphere SDK for Perl

The vSphere SDL for Perl Linux installer has changed.

To install vSphere SDK for Perl

  1. Uninstall any existing versions of vSphere CLI by running <install_dir>/vmware-uninstall-vSphere-CLI.pl. The default installation directory is /usr/bin.
  2. Delete any existing versions of vSphere-CLI.tar.gz:
     rm -rf <install_dir>/vmware-vsphere-cli-distrib
  3. Download and untar vSphere CLI 4.1.

The vSphere CLI 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 Command-Line Interface Installation and Scripting Guide

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

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

Upgrades between scripted and source code installations are not supported. The source installer does not place the files in the same location as the scripted installer.

Resolved Issues

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

  • Updated 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
  • Resolution: This problem has been fixed.

  • 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 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.1 has the following known issues:

  • Problems with resxtop on SLES 11 using libstdc++.so.6.0.14 On recent versions of SLES 11 the following symbolic link exists:
    /usr/lib/libstdc++.so.6 -> libstdc++.so.6.0.14
    resxtop does not start with libstdc++.so.6.0.14.

    Workaround: resxtop was tested with libstdc++.so.6.0.10. Create the following symbolic link in /usr/lib/vmware/vcli/lib32 to resolve the issue:
    /usr/lib/vmware/vcli/lib32/libstdc++.so.6 -> /usr/lib/libstdc++.so.6.0.10
    The link is required because /usr/lib/vmware/vcli/lib32 is first in the LD_LIBRARY_PATH for resxtop.

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

    Workaround: If your Perl script requires Class::MethodMaker, and you are using Perl 5.10, install a more recent version of Class-MethodMaker using your platform's package installer, or using CPAN.

  • Problems with resxtop and esxcli on Ubuntu 9.04 64 bit. When you install vSphere CLI on Ubuntu 9.04 64 bit, and then attempt to run resxtop or an esxcli command, the following error results: No such file or directory. The reason is that in contrast to other 64 bit Linux distributions, Ubuntu 9.04 does not have 32-bit compatibility libraries installed by default.

    Workaround: Follow the steps in the vSphere Command-Line Interface Installation and Scripting Guide, which instruct you to install a number of non-default prerequisite software, as follows:

    1. sudo apt-get update
    2. sudo apt-get install libssl-dev perl-doc liburi-perl libxml-libxml-perl libcrypt-ssleay-perl ia32-libs
  • On Ubuntu 9.04, SSL_connect messages result from running vmware_cmd. When you run vmware-cmd on an Ubuntu 9.04 system, SSL_connect: messages are displayed. The messages do not affect command execution.

    Workaround:Run the following command to make sure all required modules are up to date:
    sudo apt-get install libssl-dev perl-doc liburi-perl libxml-libxml-perl libcrypt-ssleay-perl

  • On Ubuntu 9.04, message "no packages found matching libxml-libxml-perl". On Ubuntu 9.04, the following message might display when your run the installer:
    No packages found matching libxml-libxml-perl In which directory do you want to install the executable files? [/usr/bin] The message indicates that the libxml module is not up to date.

    Workaround: Run the following command to make sure all required modules are up to date:
    sudo apt-get install libssl-dev perl-doc liburi-perl libxml-libxml-perl libcrypt-ssleay-perl
    See the vSphere CLI Installation and Scripting Guide for more information on required and recommended Perl modules.

  • 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:
    lib2xml.dll wasn't found

    Workaround: Reboot your Windows system.

  • 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

  • Obtaining ibjects 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

  • 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 using the appropriate installation process for your Linux platform.