VMware Infrastructure (VI) Perl Toolkit 1.6 Release Notes

Released 25-July-2008

VI Perl Toolkit 1.6 Release Notes

Welcome to the VMware Infrastructure (VI) Perl Toolkit 1.6 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:

  • Supported Platforms. The toolkit is tested and supported on the following platforms:
    • Linux:
      • Red Hat Enterprise Linux (RHEL) 5.1 (32-bit and 64-bit)
      • Ubuntu Desktop 7.10
      • VI Perl Toolkit appliance (32-bit only)
    • Windows
      • Windows Vista SP1 (32-bit and 64-bit)
      • Windows XP SP 2 (32-bit and 64-bit)
  • Support for Windows Security Support Provider Interface (SSPI). When you invoke a Perl Toolkit script, you can use the --passthroughauth command-line option to log in to a VirtualCenter Server version 2.5 Update 2 or later that is running Windows SSPI. Using --passthroughauth passes the credentials of the executing user to the server. If the executing user is known by both the machine from which you access the VirtualCenter Server and the machine running the VirtualCenter Server, no additional authentication is required. Documentation is included in the VI Perl Toolkit Programming Guide.
  • 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.
    • The subroutine Opts::get_config() allows you to check whether a configuration file was parsed correctly. See the Programming Guide for more information.
  • Documentation. The VI Perl Toolkit documentation has been updated to include information about the Web Services for Management Library. The following documents are available:
    • 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.

Known Issues

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

  • 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).
  • On Windows, Warnings During Startup if chcp Program Not Available

    Description:  On Windows operating systems, if the chcp program is not present or is not in your PATH environment variable, Perl Toolkit 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, Perl Toolkit uses a default character encoding. In some cases, some characters might not display correctly, but otherwise, programs function normally.

    Workaround:  Make sure chcp is installed and in your PATH

  • Hostops Utility Application Might Signal Maintenance Mode Errors if Virtual Machines Are Powered On

    Description: If you use the hostops utility application to move a host, and if any of the virtual machines on that host are powered on, errors about maintenance mode issues might result.

    Workaround: Make sure all virtual machines on the host are powered off before attempting the move operation.

    Use the following command to power off a single virtual machine on the target host.

    vmcontrol.pl --username --password --vmname xyz --operation poweroff

    Use the following command to power off all the virtual machines on a host. You can use this command can be used only if all the virtual machines are powered on.

    vmcontrol.pl --username --password --host --operation poweroff

  • Filter Arguments for Some Utility Applications Do Not Work

    Description: 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.

    Workaround: No workaround.

  • Cannot Use hostops.pl to Move or Add Standalone Host to Datacenter Root Host Folder

    Description: 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 moveintofolder and addstandalone operations without a folder name either fails or places the host into a random folder, which is not necessarily the host folder.

    Workaround: No workaround.
  • 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 the Software

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


Installing the VI Perl Toolkit

VMware provides several different packaging options for the VI Perl Toolkit. See the VI Perl Toolkit Installation Guide for detailed installation instructions.

  • 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 — 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 the distribution's update mechanism or CPAN. See the VI Perl Toolkit Installation Guide.
  • VI Perl Toolkit virtual appliance (OVF file) — Includes both the VMware Infrastructure Remote CLI and the VI Perl Toolkit. The virtual appliance is intended only for development but not for production. Note that you cannot establish ssh connections to the virtual appliance using the existing root account. If you need ssh access, create a separate user and give that user ssh permissions.
  • 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.

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 11-July-2008