VMware

VMware Infrastructure (VI) Perl Toolkit 1.0 Release Notes

Released 6-September-2007
Updated 18-September-2007

VI Perl Toolkit 1.0 Release Notes

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

The VI Perl Toolkit provides an easy-to-use Perl scripting interface to the VMware Infrastructure API. Administrators and developers who may be more familiar with Perl (rather than with Java, C#, or other programming languages) can easily leverage the power of the VI API. Better still, the Perl Toolkit includes numerous Utility Applications, a suite of ready-to-run administrative-operations applications that can immediately be 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:

Obtaining the Software

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

http://www.vmware.com/download/sdk/index.html

Current Documentation

The VI Perl Toolkit documentation may be updated after the release. Check the links below for the most current information.

Requirements

To use the VI Perl Toolkit, you need access to an ESX Server (3.x) or VirtualCenter Management Server (2.x) system. ESX Server 2.5.x is also supported as long as it is being managed by a VirtualCenter Management Server 2.x system.

See the VI Perl Toolkit Installation Guide for complete requirements for installing on Windows or Linux using the respective installation wizards.

See the VI Perl Toolkit Appliance Guide for requirements for installing the VI Perl Toolkit Appliance.

Resolved Issues

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

  • VILib::Util Package Includes get_inventory_path Subroutine.  The VI Perl Toolkit beta 1 included a subroutine, get_inventory_path, that was not documented. Documentation for all subroutines is now contained in the VI Perl Toolkit Subroutine Reference in this release.
  • Using Vim::update_view_data Subroutine No Longer Generates Error Message. In the beta version of the VI Perl Toolkit, the subroutine update_view_data resulted in the following error messages:

    Use of uninitialized value in string ne
    at c:/Perl/site/lib/VMware/VIM2Runtime.pm line 496...
    Use of uninitialized value in string eq
    at c:/Perl/site/lib/VMware/VIM2Runtime.pm line 516...

    The issue has been resolved.

Known Issues

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

  • Passwords Entered at the Command Prompt are Readable. The passwords submitted to the server from the VI Perl Toolkit Utility Applications can be read by the process list function on Linux, and can be read by anyone walking by your machine while you enter commands at the console. To minimize the potential security threat, be sure to create user accounts for use with VI Perl Toolkit applications—do not run these applications as the root user. In addition, you can use the VI_PASSWORD environment variable, to avoid submitting the password with the script invocation.

  • Silent Install on Windows Not Implemented. The VI Perl installer for Windows does not implement silent installation feature. You must install the VI Perl Toolkit on Windows interactively, following the wizard.

  • Windows Installer Generates Bogus Warning Message. When you launch the VI Perl Toolkit installer, a warning message about the software’s digital signature displays. You can safely disregard this message and click Yes to continue with the installation.

  • Obtaining Objects of Different Types Requires Multiple Calls to the get_views() Subroutine. The 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.

    As a workaround, you can use multiple get_views invocations to obtain multiple object types. Or, specify the appropriate base class as the view type (rather than a specific sub-class) to access values of properties that are common across all objects based on the superclass. For example, view_type => 'ManagedEntity' will enable you to obtain all objects that extend from this base class—the seven managed entity managed object types (VirtualMachine, HostSystem, Folder, ResourcePool, ComputeResource, ClusterComputeResource).

  • Creating an Option without Specifying its Type Results in Error Message During Parse. Be sure to always specify a type for any custom options you create, to avoid raising the following error message:
    Use of uninitialized value in concatenation (.)
    or string at C:/Perl/site/lib/VMware/VILib.pm line nnn


    For example, to create a command-line parameter that requires a string value be entered for datacenter name, you would specify string type as shown below:
    my %opts = (
        datacenter => {
        type => "=s",
        variable => "VI_DATACENTER",
        help => "Datacenter name",
        required => 1,
      },
    );

    See “Creating Custom Options” in the VI Perl Toolkit User’s Guide for more information about creating custom options.

  • Error-handling Code in VI Perl Toolkit Scripts Should Include Appropriate Call to disconnect() or 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 disconnect() or logout(), whichever is appropriate for the particular script.

  • Directory Structure May be Different Than That Described in Various Documents. The structure is as follows:

    Program Files
        \Perl
            \lib
                \VMware
                 VILib.pm
                 VIM2Runtime.pm
                 VIM2Stub.pm
                 VIRuntime.pm
        \VMware
            \VMware VI perl Toolkit
                \apps
                \doc
                \samples

Documentation Issues

The VI Perl Toolkit documentation has several known issues:

  • Chapter 5, “Porting VmPerl (Scripting API) Applications to the VI Perl Toolkit”, contains incorrect information and has been removed from the VI Perl Toolkit Programming Guide (as of 18-Sept-2007).
  • Names of Guides in the Various Installation Packages Were Changed Just Prior to Release. You may see references to guides or other documentation that does not exist, since the names of some of the guides were changed just prior to release. The online documentation for the VI Perl Toolkit is the most current.

  • Image Files Missing from the Appliance Guide. Several graphics are missing from the Appliance Guide included with the software download. The complete, update Appliance Guide is available online.

  • Documentation for vmtemplate Utility Application Is Not Complete.  The vmtemplate.pl Utility Application, which creates a template from a virtual machine, can be used with VirtualCenter Server only—since it uses the VMotion technology (which requires VirtualCenter), it cannot be run directly against an ESX Server system. Furthermore, the URL for the VirtualCenter Server must be passed as an option to the command-line, at runtime. These facts are not clear in the documentation for vmtemplate.

  • Documentation on VMware May Not Match Documentation on Sourceforge.  VI Perl Toolkit documentation available on the open source Sourceforge website is out-of-synch with the documentation available on the VMware technical publications website and will remain so, since it refers to items (such as the VI Perl Toolkit Virtual Appliance) that will not be available through Sourceforge. Instructions about building and installing the VI Perl Toolkit from the source code available on Sourceforge may be incorrect and more difficult to follow than the instructions for installing the Virtual Appliance or using the Windows installer, available from VMware.

  • Incorrect Release Dates.  Release dates in the various publications available on Sourceforge, or in any of the VI Perl Toolkit downloads, may vary from the actual release date and from the documentation available on the VMware technical publications website.

  • Incorrect Sub-directory or Path Names.  The VI Perl Toolkit Installation Guide and VI Perl Toolkit User’s Guide may contain incorrect sub-directory names. The correct sub-directory paths are as follows:
    • Path to the Utility Applications in the VI Perl Toolkit Virtual Appliance:
      /usr/lib/vmware-viperl/apps
    • Path to samples in the VI Perl Toolkit Virtual Appliance:
      /usr/share/doc/vmware-viperl/samples
    • Path to VI Perl Toolkit Utility Applications as installed using the Windows installer:
      C:\Program Files\VMware\VMware VI Perl Toolkit\Perl\apps
    • Path to VI Perl Toolkit sample scripts as installed using the Windows installer:
      C:\Program Files\VMware\VMware VI Perl Toolkit\Perl\samples

Installing the VI Perl Toolkit

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

  • VI Perl Toolkit Virtual Appliance—Hosted (for use on VMware Server, VMware Workstation, or VMware Player).
  • VI Perl Toolkit Virtual Appliance—ESX (for use on ESX Server systems).
  • VI Perl Toolkit—Windows (Installer for Windows)—(Installs ActiveState’s ActivePerl and all required Perl libraries for the VI Perl Toolkit runtime. If the target system already has an existing Perl installation, you will be prompted to remove it before you can proceed. If you don’t want to remove an existing Perl installation, consider using the VI Perl Toolkit Virtual Appliance instead.)
  • VI Perl Toolkit—Installer for Linux distributions—Ubuntu Desktop 7.04; Fedora Core 7; and Suse Enterprise Server 10 SP1. 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—Sourcecode bundle (a .tar.gz bundle comprising all source code files for making and installing the VI Perl Toolkit on any platform that supports Perl, such as Linux and Windows).

VI Perl Toolkit Virtual Appliance for ESX Server—Installation Notes

Before powering on the Appliance on an ESX Server system, you must use the VMware Infrastructure Client (VI Client) to edit the virtual machine configuration, as follows:

  • Select the network interface card
  • Change the network associated with the NIC to a network available on the ESX Server system
  • Click OK to save the changes to the VM configuration
  • Power on the VM

Running the Utility Applications

The basic command-line syntax to run any script is:

perl path\filename.pl --optionname value [...]

For example, to run the datacenterlisting script, located in \samples\discovery directory:

C:\>cd program files\vmware\vmware vi perl toolkit\perl\samples
C:\Program Files\VMware\VMware VI Perl Toolkit\Perl\samples>

perl .\samples\discovery\datacenterlisting.pl --server servername --datacenter datacentername

 

See the VI Perl Toolkit Utility Application Reference for information about running Utility Applications.

See the VI Perl Toolkit Programming Guide for information about writing your own scripts.

Uninstalling the VI Perl Toolkit

To uninstall the VI Perl Toolkit from a Windows workstation, use the Add or Remove Programs control panel.

Experimental Support for Filtering Views Selectively Using Properties

The view subroutines—get_view(), get_views(), find_entity_view(), and find_entity_views()—can accept a properties argument that comprises a list of property paths for retrieval from the server. Property paths can be full paths, and can include nested properties—they do not need to be top-level managed object properties.

Note:  This feature is experimental, and may be changed or removed in the future.

For example, to populate a virtual machine view with power-state information only, you can write:

my $vm_view = Vim::find_entity_view(
            view_type => 'VirtualMachine',
            filter => { 'name' => 'foo' },
            properties => [ 'runtime.powerState' ]
            );

To retrieve properties from a filtered view, you should use the view’s get_property method. For example:

my $state = $vm_view->get_property('runtime.powerState');

Note that you can also get subproperties of the retrieved property:

my $vm_view = Vim::find_entity_view(
            view_type => 'VirtualMachine',
            filter => { 'name' => 'foo' },
            properties => [ 'config.hardware' ]);
my $memsize = $vm_view->get_property('config.hardware.memoryMB');

And that get_property works with fully-populated views as well. So:

my $vm_view = Vim::find_entity_view(
            view_type => 'VirtualMachine',
            filter => { 'name' => 'foo' });
my $memsize = $vm_view->get_property('config.hardware.memoryMB');

Is equivalent to:

my $vm_view = Vim::find_entity_view(
            view_type => 'VirtualMachine',
            filter => { 'name' => 'foo' });
my $memsize = $vm_view->config->hardware->memoryMB;

When using a filtered view, any attempts to read a property that wasn’t retrieved from the server will act the same as if the property were unset.

Using property filters is intended primarily to optimize performance, by reducing latency and network bandwidth associated with retrieving full views of a large number of objects. In general, you should start with full views and switch to filtered views only when tuning application performance.

Last updated 18-September-2007 9:00 am