VMware Infrastructure (VI) Perl Toolkit 1.5 Release Notes

Released 17-January-2008

VI Perl Toolkit 1.5 Release Notes

Welcome to the VMware Infrastructure (VI) Perl Toolkit 1.5 release.

The VI Perl Toolkit provides an easy-to-use Perl scripting interface to the VMware Infrastructure API. Administrators and developers who are familiar with Perl can easily leverage the power of the VI API. Better still, the VI Perl Toolkit includes numerous utility applications, which are ready-to-run applications that you can immediately put to use in your virtual datacenter.

This document contains the following information:

What’s New in This Release?

This release of the VI Perl Toolkit includes the following new features:

  • Connectivity to the newer versions of ESX Server. You can use the VI Perl Toolkit 1.5 to administer ESX Server 3.5 hosts, ESX Server 3i hosts, and Virtual Center version 2.5. You can also still manage all the servers that VI Perl Toolkit 1.0 can manage.
  • Supported Platforms. The toolkit is tested and supported on the following platforms:
    • Linux:
      • Red Hat Enterprise Linux (RHEL) 5
      • Ubuntu Desktop 7.1
      • SUSE Enterprise Server 10 (SP1)
      • Fedora Core 8
    • Windows
      • Windows XP (SP 2)
      • Windows 2003 Server (SP2)
  • Virtual Appliance in OVF Format. The virtual appliance is now available in OVF (Open Virtual Machine) Format, which you can import into ESX Server 3 hosts using the VMware Infrastructure client version 2.5.
  • Revised, Reorganized Documentation. The VI Perl Toolkit documentation has been revised and includes the following:
    • VI Perl Toolkit Installation Guide (PDF). Includes instructions for package installation, for installing and using the virtual appliance, and relevant information for installation from source code.
    • VI Perl Toolkit Programming Guide (PDF). Explains how you can modify existing scripts or write new scripts. Includes discussion of how to find and manipulate VI API objects using VI Perl Toolkit subroutines. Includes subroutine reference.
    • Subroutine Reference. Now included in the Programming Guide PDF for easy search.
    • VI Perl Toolkit Utility Applications Reference. HTML documentation for each of the utility applications included with the toolkit.
  • Web Services for Management Library (experimental). An experimental Web Services for Management Library is included with this version of the VI Perl Toolkit. You can use that library to access VMware CIM SDK profiles, the same way you can access VMware Infrastructure SDK objects using the VI Perl Toolkit. You can download the Web Services for Management technical note (PDF) for more information.
  • Miscellaneous Changes.
    • The save_session.pl and load_session.pl scripts are now fully tested utility applications.
    • The vmdisk.pl script is now called vdiskcreate.pl
    • Two new subroutines named Vim::clear_session() and Vim::get_service_instance() have been added.
    • A new subroutine Vim::get_session_id() allows you to retrieve the session ID for the current session.
    • The Vim::load_session() subroutine has been enhanced so you can now connect to the server using a session ID you retrieved with Vim::get_session_id().

Obtaining the Software

Obtain the VI Perl Toolkit software from the Management SDKs download page at:


Resolved Issues

This release of the VI Perl Toolkit resolves the following issues:

  • Server Now Prompts For Passwords, Which Are Not Readable
    When you run a script and don’t specify the password using an environment variable or command-line parameter, the server prompts you for a password. For security reasons, this password is not visible on the screen when you type it in.
  • Silent Install on Windows Now Implemented
    The Windows installer for the VI Perl Toolkit now supports a silent, non-interactive installation option.
  • Windows Installer Warning Message Now Suppressed
    When you launch the VI Perl Toolkit installer, a benign warning message about the software’s digital signature used to display. This warning message does not appear any more.
  • VI Perl Toolkit now treats the values true and TRUE and false and FALSE the same way.
  • VI Perl scripts no longer prompt for a host connection when you execute the script with --version, --usage, or --help.
  • The Vim::load_session() subroutine used to require a complete service url as the input parameter. You can now supply a session file saved by a previous call to Vim::save_session instead.
  • Creating an option without specifying its type results in error message during parse.
  • Error-handling code in VI Perl Toolkit scripts should include appropriate call to Util::disconnect() or Vim::logout()
    If a call to the server throws an exception, the session to the server should be terminated to avoid session leaks. Be sure to wrap your calls to the VI Perl Toolkit subroutines in error handling code, and call Util::disconnect() or Vim::logout(), whichever is appropriate for the particular script.

Known Issues

The VI Perl Toolkit 1.5 release has the following known issues:

  • Must Use Encoded Representation When Constructing Filters That Recognize Names Containing Certain Special Characters
    Description:  Based on what the VI 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 percent-escaped characters.:
    filter => { name => qr/%/ } # wrong;

    You must use case-insensitive matching for escapes containing alpha characters:
    filter => { name => qr/%2f/i } # matches %2f and %2F
  • Obtaining objects of different types requires multiple calls to the Vim::get_views() subroutine
    Description:  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, ComputeResource, ClusterComputeResource).
  • Outdated index.html file included in installation
    Description:  When you install the VI Perl Toolkit package, an index.html file becomes available as part of the installation. All internal links for this file are broken, and the external link points to the documentation for VI Perl Toolkit 1.0.

    Workaround:  You can view all documentation from http://www.vmware.com/support/developer/viperltoolkit.

Installing the VI Perl Toolkit

VMware provides several different packaging options for the VI Perl Toolkit:

  • VI Perl Toolkit Virtual Appliance as an OVF file.
  • VI Perl Toolkit Windows installer —(Installs ActiveState’s ActivePerl and all required Perl libraries for the VI Perl Toolkit runtime.
  • VI Perl Toolkit Linux installer. The Linux installer is a Perl script that requires Perl 5.8 (or subsequent version) and OpenSSL 0.9.7 (or OpenSSL 0.9.8).
  • VI Perl Toolkit—Source code bundle (a .tar.gz bundle of all source code files for making and installing the VI Perl Toolkit on any platform that supports Perl, such as Linux and Windows).

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 14-January-2008 5:30 pm