VMware Infrastructure (VI) Perl Toolkit Release Notes

VI Perl Toolkit Beta 2 Release Notes

Welcome to the beta 2 release of the VMware Infrastructure (VI) Perl Toolkit.

The VI Perl Toolkit provides an easy-to-use Perl scripting interface to VMware Infrastructure APIs. 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 APIs. 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?
• Obtaining the Software
• Current Documentation
• Requirements
• Resolved Issues
• Known Issues
• Installing the VI Perl Toolkit
• Running Utility Applications
• Experimental Support for Filtering Views

Known Issues

This beta 2 release of the VI Perl Toolkit has the following known issues:

• The vmtemplate Utility Application Requires URL Option and is Not Supported on ESX Server.  The vmtemplate.pl Utility Application, which creates a template from a virtual machine, can be used with VirtualCenter Server only—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.
  
  
• 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 directory structure was changed in VI Perl Toolkit beta 2. 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:

• Documentation on VMware Does 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 Filenames.  The VI Perl Toolkit Installation Guide and VI Perl Toolkit User’s Guide may contain incorrect filenames for the VI Perl Toolkit software installers. The correct filenames for the VI Perl Toolkit software installers are as follows:
  • VI Perl Toolkit Virtual Appliance [for VMware Server, VMware Player, or Workstation]:
    VMware-VI-Perl-Toolkit-Appliance-e.x.p-53507-i386.zip
  • VI Perl Toolkit Virtual Appliance [for ESX Server]:
    VMware-VI-Perl-Toolkit-Appliance-ESX-e.x.p-53507-i386.tar.gz
  • VI Perl Toolkit Windows Installer:
    VMware-VI-Perl-Toolkit-e.x.p-53183.exe
• 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 VI Perl Toolkit in the Virtual Appliance:
    /usr/local/share/doc/viperltoolkit/
  • Path to the Utility Applications in the VI Perl Toolkit Virtual Appliance:
    /usr/local/share/doc/viperltoolkit/apps
  • 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

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:

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.