VMware Infrastructure (VI) Perl Toolkit Programming Guide

PRINT

The VMware Infrastructure (VI) Perl Toolkit provides an easy-to-use Perl scripting interface to the VMware Infrastructure (VI) API. Administrators and developers who may be more comfortable with Perl (rather than with Java, C#, or other programming languages) can easily leverage the power of the VI API for managing their virtual infrastructure. Better still, the VI Perl Toolkit includes numerous ready-to-run Utility Applications that can be put to use immediately.

The VI Perl Toolkit is a client-side framework from VMware that simplifies the programming effort associated with the VI API and server-side object model. For developers who have previously worked with the Scripting API (specifically, the VmPerl API), the VI Perl Toolkit is the tool of choice.

For information about installing the VI Perl Toolkit, see the VI Perl Toolkit Installation Guide.

This Programming Guide includes these topics:

1. Preface
   • Technical Support
   • Online Support
   • VMware Education Services
   • Resources for Developers
   • Contacting VMware
2. Introduction to the VI Perl Toolkit
   • What’s in the VI Perl Toolkit?
   • Requirements
   • Subroutine Libraries and Table of Built-in Options
3. Developing VI Perl Toolkit Scripts
   • Basic VI Perl Toolkit Script Pattern
   • Working with Views
   • Invoking Methods
     • Non-blocking and Blocking Operations
4. Advanced Topics
   • Creating and Using Filters
   • Handling Errors
   • Saving and Using Multiple Sessions
   • Learning About View Object Structure Using Data::Dumper
5. VI Perl Toolkit Subroutine Reference Table
6. Glossary

1. Preface

The VI Perl Toolkit simplifies access to the VMware Infrastructure API (VI API)—the Web-services-based API for programmatically managing virtual infrastructure components. This Programming Guide:

• Helps you get started running the Utility Applications, production-ready applications that can be used, as shipped, to manage and monitor your virtual intrastructure. (By examing the source code for these utilities, you can also learn about creating your own applications.)
• Introduces important concepts, such as “view” objects, the client-side Perl objects that serve as proxies to server side objects;
• Discusses server-side objects (object model and the VI API) from the perspective of a developer using the VI Perl Toolkit;
• Steps you through the process of writing basic scripts as demonstrated in some of the additional sample scripts provided with the VI Perl Toolkit.

Using any of the Utility Applications requires only minimal understanding of the server-side object model and the VI API. However, writing your own scripts requires some basic knowledge of Perl. For more information about Perl, see:

• Perl.org
• Perl CPAN (Comprehensive Perl Archive Network)
• Perl Documentation

Technical Support and Education Resources

VMware provides numerous support and educational resources. See the support page at:

http://www.vmware.com/support/services

Online Support

You can submit questions or post comments to the VMware Management APIs (VI SDK, VI Perl, CIM SDK) discussion forum, which is monitored by VMware technical support and product teams.

VMware Education Services

VMware education services offers technical training that includes extensive hands-on labs, case study examples, and course materials designed to be used as on-the-job reference tools. For more information about VMware Education Services, go to

http://mylearn1.vmware.com/mgrreg/index.cfm

Resources for Developers

Here are some links to various resources, including developer forums, user groups, and product pages.

Contacting VMware

VMware welcomes your suggestions for improving technical publications. You can email your feedback to:

docfeedback@vmware.com

2. Introduction to the VI Perl Toolkit

The VI Perl Toolkit lets you automate a wide variety of virtual-infrastructure administrative, provisioning, and monitoring tasks. For example, you can quickly obtain a list of all virtual machines in your virtual data center and obtain performance statistics. If a host system is over-burdened, you can migrate virtual machines as needed, to better distribute the load.

As a Perl interface, the VI Perl Toolkit brings the power of VMware Infrastructure API to anyone familiar with the scripting capabilities of Perl. You’ll have full access to the VI API and object model, albeit through an easy-to-use Perl interface. In addition, for handling some of the most common management and automation tasks, the VI Perl Toolkit includes several Utility Applications that can be integrated into your management environment, as is—you don’t need to learn anything about the VI Perl Toolkit or its underpinnings to use these Utility Applications.

What’s in the VI Perl Toolkit?

The VI Perl Toolkit provides:

• VI Perl Toolkit Runtime—Client-side runtime components that include:
  • A complete Perl binding of the VI API that provides access to all operations and data structures available in the VI API and object model. The data-type mapping between server-side and client-side objects is handled transparently.
  • VMware Perl modules (VIRuntime.pl, VILib.pl) that provide subroutines for basic functionality, including:
    • Connecting to one or more ESX Server or VirtualCenter Server host systems
    • Discovering virtual machines and other managed entities
    • Reporting on specified properties
    • Managing virtual machine life-cycle
    • handling sessions
• VI Perl Toolkit Utility Applications—Complete management applications that can be run, as is, in your VMware virtual datacenter. In most cases, you must simply pass the application a few simple parameters—server name, for example (see Running the Utility Applications for details). See VI Perl Toolkit Utility Applications for the complete list and reference documentation. Here are two examples of the Utility Applications included with the VI Perl Toolkit:
  • hostops—Perform a wide range of host operations, including:
    • Setting a host into maintenance mode
    • Exiting from maintenance mode
    • Adding a standalone host to a VirtualCenter inventory
    • Disconnecting a host from an inventory
    • Reconnecting a host to an inventory
    • Rebooting a host
    • Shutting-down a host
  • sharesmanager—View or change shares on a virtual machine. (Shares specify memory-reservation priority for multiple virtual machines on a server.) Using the shares utility without any parameters returns the current shares setting for the specified virtual machine. You can specify CPU, Memory (or both) parameters to change the shares values on the virtual machine.
• Sample Scripts—The VI Perl Toolkit includes several sample scripts that you can quickly adapt to your own needs, and use to learn more about the VI Perl Toolkit’s functionality. However, unlike the Utility Applications, the sample scripts are not supported by VMware. In addition, the sample scripts typically require Perl scripting skill to customize them.

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.

Subroutine Libraries

The VI Perl Toolkit includes several subroutine libraries, one of which includes built-in options to simplify passing command-line syntax. The Utility Applications all use this VILib::Opts library.

perl app_name.pl --optionname optionvalue

You will need to know the server name, username, and password to run the applications. Depending on the nature of the application, you may also need to pass other parameters to the command line. For example, powering-on virtual machines using the vmcontrol Utility Application requires you to provide the name of the virtual machine whose power status you want to change:

perl vmcontrol.pl --server myserver --username admin --password password --operation poweron --vmname myvmname

You can provide the required parameters to VI Perl Toolkit utility applications in several different ways:

• Pass parameters at the command line, using the required option flag followed by the value for the option:
  --optionname optionvalue
  
  
• Set as environment variables in a Linux profile; in the Environment properties dialog of the Windows System control panel; or at the command-line, for the current session:
  set VI_SERVER=your_server_name
  
  
• Create a configuration file (a plaintext file) that contains variable names (for the parameters) and settings. Variables for the built-in options are shown in Table 1, below. Any option with the variable attribute set in the Perl script or application (.pl) can also be specified in a configuration file.
  
  VI_PROTOCOL=https
  VI_SERVER=prod01.vmware.com
  VI_SERVICEPATH=/sdk
  VI_USERNAME=Administrator
  VI_PASSWORD=*******
  

The VI Perl Toolkit runtime processes options set in the config file first, environment variables next, and command-line entries last. As shown in the example above, you can use a combination of these three approaches.

For example, assuming that most of your administrative chores take place through a central VirtualCenter Management Server, you can create a configuration file for executing applications and avoid repeatedly entering connection details. If you have multiple VirtualCenter Management Server or ESX Server systems and you need to administer them individually, you can create multiple configuration files using different names for each and then simply pass the --config option with the appropriate filename when you run the applications.

Furthermore, each option can be set in multiple ways. Since command-line flags take precedence over environment variables, and environment variables take precedence over settings in the configuration file, you can easily over-ride any parameter when necessary.

3. Developing VI Perl Toolkit Scripts

To develop VI Perl Toolkit scripts, you must have basic familiarity with Perl scripting techniques. You will also need some basic understanding of the VI API and the server-side object model: It is this object model that is abstracted by the VI Perl Toolkit runtime. Some of the basics are covered in this section.

Topics in this section include:

• Basic VI Perl Toolkit Script Pattern
• Working with Views

Basic VI Perl Toolkit Script Pattern

Generally, you should follow common Perl approaches for filename, imports, and general processing flow. Use the appropriate filename extension for the type of script or application you are creating (.pl for Perl library, .pm for Perl module, for example), with the proper declarations.

Step 1: Import the VI Perl Toolkit Modules

Any Perl script you write using the toolkit should include these these two modules:

These two modules, directly or indirectly, handle all client-side infrastructure details—for example, transparently mapping data types and providing local Perl interfaces to objects on the remote service. They also provide subroutines for connecting to ESX Server and VirtualCenter Management Server systems, and for obtaining views, the client-side Perl objects that encapsulate the properties and operations of server-side managed objects and entities. These subroutines are organized into three different packages:

• The Vim package, which includes subroutines for accessing server-side managed objects, instantiating local proxy objects (views), updating properties, invoking local methods to effect operations on remote operations, use subroutines from
• The Util package, which includes subroutines to facilitate routine tasks, such as seting up and closing connections to the server.
• The Opts package, which includes subroutines for handling built-in options and creating custom options.

See VI Perl Toolkit Subroutines Reference for complete details.

The basic syntax for invoking any of the subroutines from these packages is to use the parameter name followed by its value:

• Vim::subroutine(argument_name=>value, argument_name=>value, );
• Util::subroutine(argument_name=>value, argument_name=>value, );
• Opts::subroutine(argument_name=>value, argument_name=>value, );

Step 2: Create Custom Options [Optional]

All the options specified in the Utility Applications have been defined using attributes and subroutines specified in the VILib::Opts package. You can use this same library to create your own custom options for your applications and scripts, to simplify use of your script, or to provide more flexibility beyond that provided with the built-in options listed in Table 1: Built-in Parameters and Variables.

For example, as shown in Listing 1, the ’entity’ option requires script users to specify at runtime which of the 7 entity types will be passed as a parameter to the get_entity_views() subroutine for further processing.

1. Define the option as a hash—a series of key-value pairs that define the option attributes and specifications. (In other programming languages, a hash is called an associative array, so the key name is used to reference and access associated value (order is not important). See Table 2 for attribute details.) Listing 1 creates a required command-line option that will accept a string value for entity name:
   
   my %opts = (
       entity => {
       type => "=s",
       variable => "VI_ENTITY",
       help => "Enter one of the 7 managed entity types: HostSystem, VirtualCenter, etc.",
       required => 1,
     },
   );
   
2. Add the hash to the script using the Opts::add_options subroutine:
   Opts::add_options(%opts);
   
   Table 2: Attributes for Defining New Options
   

   Attribute	Description
   default	Default value used if the option isn’t explicitly set; an unset option with no default returns undef.
   func	Enables creating “derived options.” Set func to an external code reference to execute the code when the value of the option is queried.
   help	Descriptive text explaining the meaning of the option, displayed in the script’s help message.
   required	If this attribute is set to 1, a value must be provided for this option or the script will exit and display the help message. Set to 1 to require a value. Set to 0 if value is optional.
   variable	Enables an option to be read from an environment variable or the configuration file.
   type	Uses Perl Getopt-style syntax to specify option type and whether the option is required or optional. Use double-quotes to indicate that option doesn’t accept a value (identifies it as a flag). Default numeric value is 0. Default string value is " " (empty string). Mandatory Optional String Integer Float = : s i f

   
   
3. Parse and validate the options, prior to connecting to the server:
   
   Opts::parse();
   Opts::validate();
   
   
   

The entity option defined above is required, so the script will not be able to run unless the user passes in a string value. The string value passed as a parameter will be used in the Vim::find_entity_views() subroutine later in the script, and must be one of the 7 managed-entity types listed as view_type parameter supported by Vim::find_entity_views().

Attempting to run the script without all the necessary options displays usage help for the script, as shown in this example:

C:\viperltoolkit>perl simpleclient.pl
Required command option 'entity' not specified

Common VI options:
. . .

Command-specific options:
--entity (required)
ManagedEntity type: ClusterComputeResource, ComputeResource, Datacenter,
Folder, HostSystem, ResourcePool, or VirtualMachine

Step 3: Connect to the Server

The VI API is hosted as a secure web service on VirtualCenter Server and ESX Server systems: by default, the web service is available over HTTPS, so clients must provide valid credentials to connect to the service. (If your server has been re-configured for HTTP, you do not have to provide logon credentials.) Depending on the specifics of the server you are using for your script development, you may need to enter a username and password only. Or, if the built-in parameter defaults (see Table 1: Built-in Parameters and Variables) are not correct for your specific configuration, you may need to enter servername and other details.

Note that, as shown in the subroutine reference, the VI Perl Toolkit provides two different subroutines for establishing a connection:

• The Vim::login() subroutine has been available since the alpha release of the VI Perl Toolkit. This subroutine is still supported, but it does not take advantage of the built-in parameters available in the Opts library, so you must handle all the setup details to create a connection in your script, manually.
• The Util::connect() subroutine takes advantage of the built-in options for server name and various other connection details shown in Table 1: Built-in Parameters and Variables. It’s the preferred approach for new VI Perl Toolkit scripts.

Using Util::connect() in your code is a simple one-line entry, after parsing and validating:

Util::connect();

When the script is run, the VI Perl Toolkit runtime checks the environment variables, configuration file contents, and command-line entries (in this order) for the necessary connection-setup details. If none of these overrides are available, the runtime uses the defaults (see Table 1 ) to setup the connection.

Both subroutines return a session token that you can save to a file and then use in subsequent connections to the same or to different servers. See Saving and Using Sessions for details.

Step 4: Obtain Views of Server-Side Managed Objects

The subroutines in the Vim package let you create Perl objects and references for working with server-side objects of interest. In the simpleclient.pl shown in Listing 1, the Opts::get_option subroutine is used to obtain the string value of the parameter that is passed with the script when it is executed. This string value is then used as the view_type parameter in the subsequent call to Vim::find_entity_views().

# get all inventory objects of the specified type
my $entity_type = Opts::get_option('entity');
my $entity_views = Vim::find_entity_views(view_type => $entity_type);

The find_entity_views subroutine creates the Perl object (an array of references) from the server-side managed object of the specified entity type.

Step 5: Process Views and Report Results

Here’s where the true purpose of the script becomes clear, in the actual processing of the views. Knowledge of server-side objects is useful here because in order to invoke methods, obtain information about objects (is a virtual machine on or off, for example), you must have some understanding of where in the returned objects the properties and methods reside.

You’ll use the VI API Reference Guide to determine the available properties and methods.

Remember that views are Perl objects, and so you’ll use Perl object-oriented syntax to process the views. In this example, the “processing” involves looping through the array of entities returned (@$entity_views) and accessing the name property of the entity (using the method call, $entity_view->name), and then printing out to the console the name of each entity as it’s found.

foreach my $entity_view (@$entity_views) {
      my $entity_name = $entity_view->name;
      Util::trace(0, "Found $entity_type: $entity_name\n");
}

Additional background information about views is provided in Working with Views .

Step 6: Close the Server Connection

To logout and exit, use the Vim::logout() subroutine.

Util::disconnect();

To run the simpleclient.pl script:

1. Open command-prompt or console
2. Navigate to a directory that has path set to VI Perl Toolkit installation
3. Enter as follows:
   
   perl simpleclient.pl --server myServerFQDN --username my_username --password password --entity HostSystem

For example:

C:\viperltoolkit>perl simpleclient.pl --server myserver.vmware.com --username Administrator --password password --entity HostSystem

Found HostSystem: lgto-1s-dhcp214.eng.vmware.com

Working with Views

A VI Perl Toolkit view is a client-side Perl object that comprises a static copy of the properties and operations of one or more managed objects on the server. Before delving into VI Perl Toolkit views in more detail, you should understand some of the server-side object model basics—it is this server-side object model that the VI Perl Toolkit abstracts.

VI Object Model Basics (Server-side Object Model)

A managed object is the primary type of object provided in the virtual infrastructure object model. A managed object is a data type that comprises properties and operations available on the server. Each managed object type provides various services (operations, or methods) and properties. Basically, the various managed object types define common administrative and management services that one would expect to use in a typical datacenter—services such as managing performance (PerformanceManager), finding entities that exist in the inventory (SearchIndex), disseminating and controlling licenses (LicenseManager), and configuring alarms to respond to certain events (AlarmManager).

Another important construct of the server-side object model is the managed object reference ( ManagedObjectReference ), which is essentially the mechanism that enables distributed computing for VMware virtual infrastructure. A managed object reference identifies a specific managed object on the server, and encapsulates the state and methods of specific server-side objects and makes these properties and methods available to client applications. Clients invoke methods (operations) on the server by passing the appropriate managed object reference to the server, as part of the method invocation.

Managed objects comprise both operations and properties. Each property is defined as a specific data type. Data types include:

• A simple data type, such as a string, boolean, or integer (or other numeric) datatype. For example, the ManagedEntity managed object has a name property that takes a string.
• An array of simple data types or data objects. For example, a HostSystem managed object contains an array of virtual machines that are hosted by that physical machine.
• An enumerated list (enumeration, or simply, enum) of predefined values. The values can be a collection of simple data types or data objects. For example, a virtual machine’s power state can be one of only three possible string values—poweredOn, poweredOff, or suspended.
• Complex data types, called data objects, that have been specifically defined as part of the virtual infrastructure object model. For example, AboutInfo, Action, and ServiceContent are all data objects.

ServiceContent is the “largest grained” object on the server, providing access to everything the server offers, through well over a dozen properties that comprise references to specific managed objects.

For example, the rootFolder property is a ManagedObjectReference to a Folder managed object type; the perfManager is a ManagedObjectReference to a specific instance of a PerformanceManager managed object type, and so on. These managed object types define the typical administrative and management services one would expect to use in any datacenter, virtual or otherwise—services such as managing performance (PerformanceManager), finding entities that exist in the inventory (SearchIndex), disseminating and controlling licenses (LicenseManager), and configuring alarms to respond to certain events (AlarmManager), for example.

In addition to providing services to the server as a whole, the ServiceContent object also contains references to so-called inventory objects—objects that are specific instances of entities, such as hosts and the virtual machines that run on them, that effectively comprise an “inventory” of manageable virtual-datacenter components.

The inventory comprises the collection of all managed entities on the server. A managed entity is simply a managed object that extends the ManagedEntity managed object type: ManagedEntity is an abstract class that defines the base properties and operations for the managed objects that comprise the virtual infrastructure—the same type of manageable components found in a physical world, such as datacenters and hosts. The current virtual infrastructure has 7 managed object types that extend the ManagedEntity superclass:

• ClusterComputeResource— Abstracts a cluster of HostSystem objects as a unified compute resource for virtual machines.
• ComputeResource —An object that abstracts the physical resources of a host system and enables them to be associated with the virtual machines that run on the host.
• Datacenter —Contains other managed entities, including folders, virtual machines, host systems. VirtualCenter Server instances can support multiple datacenters, but ESX Server supports only one datacenter (although it’s not visible through the VI Client).
• Folder —Contains references to other entities of the same type (for example, other folders (Folder), or several hosts (HostSystem).
• HostSystem —Comprises a single physical machine
• ResourcePool —Divides physical resources among virtual machines
• VirtualMachine —Comprises a single virtual machine

Managed entities offer specific operations that vary, depending on the entity type. For example, a virtual machine managed entity (VirtualMachine) provides operations for creating, monitoring, and controlling virtual machines, including power operations (PowerOnVM, PowerOffVM) and capturing state (Snapshot). On the other hand, a host system managed entity ( HostSystem) provides different operations for entering and exiting maintenance mode (EnterMaintenanceMode_Task, ExitMaintenanceMode_Task), or rebooting the server (RebootHost_Task).

The ManagedEntity base class includes several properties (such as a name property, whose data type is a string) that are inherited by each subclass. ManagedEntity also includes only a few operations that are inherited by each sub-class (Destroy_Task, Reload, for example). So since both VirtualMachine and HostSystem extend the ManagedEntity base class, each has a name property that it inherits from the superclass.

The VI API Reference Guide contains the definition of all server-side objects, their properties and methods. You’ll use the VI API Reference Guide to identify the list of parameters and operations that you can use with specific VI Perl Toolkit views that you create and manipulate in your code.

An Example

The VI Perl Toolkit provides subroutines for accessing server-side objects from the inventory (managed entities) and other managed objects that provide functionality to the server as a whole. The example in Listing 1 obtains all entities of a specific type from the inventory. The entity type is passed as a parameter to the find_entity_views subroutine, which returns an array of references to view objetcs that map to the specific server-side entity. Listing 3 is a bit different in that it starts from a higher level, that of the entire service; it uses the get_service_content() subroutine to obtain an instance of the ServiceContent object:

my $content = Vim::get_service_content();

Once you’ve obtained a ServiceContent object, you can obtain a local view to the services provided by that specific server. Here’s and example of obtaining reference to a managed object:

my $diagMgr = Vim::get_view(mo_ref => $content->diagnosticManager);

Listing 3 shows how these two calls form the basis of a script that “tails” (follows changes) in the logfile, which is a property of the diagnosticManager.

View Basics

VI Perl Toolkit views have several characteristics that you should keep in mind as you write your own scripts. Specifically, a view:

• Is a Perl object
• Includes properties and methods that correlate to the properties and operations of the server-side managed object
• Is a static copy of one or more server-side managed objects, and as such (static), is not updated automatically as the state of objects on the server changes.
• Includes additional methods (beyond the operations offered in the server-side managed object), specifically:
  • An accessor method for each managed object property
  • A blocking method (as well as the non-blocking version) for each non-blocking operation provided by the server-side managed object

The VI Perl Toolkit maps properties from managed objects into client-side view objects as follows:

• Simple property types (strings, booleans, numeric datatypes, such as integers, floats, and the like) convert directly to properties of the same name in the view.
• Arrays of properties convert to arrays of properties of the same name
• An accessor (“getter” method) is created from each simple property type (string, boolean, numeric datatype), including inherited properties. The accessor method name is the same as the property name.

The VI Perl Toolkit simplifies many programming chores. For example, the VI Perl Toolkit automatically:

• Provides a _this parameter (with the managed object reference of the object being used to invoke the operation) when one is required for a specific method invocation
• Supports passing a view object (in place of a managed object referece) as a parameter to methods that take managed object references as required parameter.

The VI Perl Toolkit provides subroutines to access all properties, regardless of their “depth” inside a composite object structure, and provides a subroutine that updates the state of any client-side view objects with current data, from the server.

Accessing Property Values

VI Perl Toolkit view objects are Perl objects. When you obtain a view and manipulate its properties or invoke its methods in a script, you do so using Perl’s object-oriented syntax. To access a simple property from a view, invoke the method name (same as the property name) on the Perl object, as follows:

$view_name->property_name

As shown in Listing 1, the name property of the entity view is accessed by invoking the name method.

my $entity_name = $entity_view->name;

To retrieve the value of a property defined as an enumeration, you must dereference its val from within the containing object, by qualifying the property with ->val.

So, for example, since the power state of a virtual machine (powerState) is “nested” inside (“is a a member of”) the runtime data object, you must dereference the two containing objects—the view object and the runtime data object and the value (val) itself, in order to retrieve the value of powerState,as in:

$vm_view->runtime->powerState->val

Runtime.powerState is an enumeration (enum) and so you need to qualify it as runtime.powerState->val to retrieve is property.

Modifying Property Values

To modify an existing data object, change its property values by passing the new value:

$data_object->property (new value);

where $data_object is a blessed reference to a Perl object or class name, and property is a method call on the object.

For example, to change the force property,

$host_connect_spec->force ('false');

To change the value of a property that has been defined as an enumeration (enum), you must pass the new value to the method defined for the property in the Perl object, as in:

$data_object->property->val (new value)

$vm_view->runtime->powerState->val ("poweredOff")

Creating Data Objects

To create a new managed object with specific properties—for example, a virtual machine on a specific host—you must create the appropriate data objects that define the managed object and then construct the managed object using the data objects, simple types, and enumeration values, as defined in the VI API Reference Guide for the object.

The client-side object (or objects) that you build-up in this way can then be passed, along with the appropriate managed object reference, to create new server-side managed objects on the server.

The one thing you will need is a managed object reference (mo_ref) for the managed object on the server.

To create a data object:

$var = new DataobjectType (param1 => value, param2 => value …)

For example, adding a host requires several parameters, including a HostConnectSpec data object. Start by creating a HostConnectSpec data object:

$host_connect_spec = new HostConnectSpec (
            force => 'true',
            hostName => 'my host',
            userName => 'user',
            password => 'pwd');

To set the value of a property that has been defined as an enumeration, you must pass the new value to the data object as follows:

$ref = new enum_type (val => value);

For example, to change the power state:

$power_state = new VirtualMachinePowerState (val => 'poweredOff');

Understanding Operations and Methods

One of the key functions of the VI Perl Toolkit runtime is to map server-side operations to client-side Perl view methods.

Invoking Methods

After obtaining a view of a managed object, you can invoke methods on that view to effectively make use of the services provided by the managed object. Client-side view objects are Perl objects; to invoke methods, you specify the parameter for the object method by name:

$vm->MigrateVM (name => 'productionVM');

The type of parameter (simple type, data object, or managed object reference) that you’ll need to pass to the method depends on the operation as defined in the VI API.

See the VI API Reference Guide for information about specific parameters and data types.

Blocking operations are invoked as methods on a view object. For example, to suspend a virtual machine:

Any operation that is defined for a managed object can be invoked as a method on a corresponding view object.

Since the VI Perl Toolkit creates an accessor/mutator method for each property defined in the managed object, you can reference the name of any property as a method call of the view (a Perl object):

my $network_name = $network_view->name

As mentioned in View Basics , one of the convenience features of the VI Perl Toolkit is that you can pass a view to a method that requires a ManagedObjectReference (rather than a managed object reference). For example, assuming you have view of a host ($host), you can pass the view ($host) to the powerOn method, in place of the managed object reference argument:

Updating View Objects

The values of properties in any view represent the state of the server side objects at the time the view was created, and as mentioned previously, these property values are not updated automatically. However, in a production environment, the state of managed objects on the server is likely to be changing constantly. If your client script depends on the server-side view being in a particular state—poweredOn or poweredOff, for example—then you must either check the state prior to acting on the client view object, or you must refresh the state of the view object. The VI Perl Toolkit library provides the update_view_data subroutine to refresh the values of client-side views with server-side values.

To refresh a view’s data, use the update_view_data() subroutine.

4. Advanced Topics

This section includes these advanced topics:

• Creating and Using Filters
• Handling Errors
• Saving and Using Sessions
• Learning About Object Structure by Using Data::Dumper

Creating and Using Filters

One of the more powerful features of the VI Perl Toolkit is the ability to define and use filters to select specific objects based on property values. For example, instead of obtaining all virtual machines from an ESX Server system, you can obtain only those virtual machines whose names begin with a certain prefix. Filters use regular expressions for pattern matching (see Filters and Regular Expressions for details). You can apply one or more filters to the find_entity_views (and find_entity_view) subroutines to quickly select a subset of objects based on property values.

To create a filter based on a simple property, such as a string, you must first find the property in the VI API Reference to find the property name, and set the filter for the specific possible value:

filter => { 'property_name' => property_value, ... }

Filters and Regular Expressions

The filter construct is a standard Perl programming pattern; it supports regular expressions, so the syntax model above means

Matching is based on regular expression matching.

^myspecificmachine$

Use dot notation to specify the property name in the filter definition, as shown in Listing 5.

For properties that are nested inside a data object, you must use dot notation. For example:

filter => {'object_name.method_name' => 'property_value', ... }

If you pass multiple filters to find_entity_views (or find_entity_view), only those managed objects matching all criteria are returned.

For example, the filter parameter specfied in Listing 6 includes a second filter definition—status must be poweredOn—so only those virtual machines whose guest operating system is Windows—the config property’s guestFullName property includes the string “Windows”—and that are actually running will be returned.

Handling Errors

Be sure to embed your calls to the VI Perl Toolkit subroutines inside appropriate conditional logic, to handle possible empty or non-existent return values and other issues. Using conditional logic around any of the access subroutines—find_entity_view, find_entity_views, get_view, get_views, for example—is generally a good practice.

For example, as shown in Listing 7 (excerpted from the \scripts\discovery\datacenterlisting.pl sample script), you can use simple conditional logic to handle null or empty results, by gracefully exiting the script and notifying the user (via console display) that the requested datacenter wasn’t found (lines 28 and 29):

As standard practice, you should include error-handling code in your scripts. Errors fall into one of these three basic categories:

• SOAP and other types of faults returned by the server.
• Internal errors that propagate through the various VI Perl Toolkit runtime layers.
• Other errors, including logic errors in your code or manipulating client-side view objects that are out-of-synch with their server-side counterparts.

However, regardless of the root cause, the VI Perl Toolkit runtime is designed to stop processing scripts whenever errors such as these occur.

SOAP Faults

Since the VI API is hosted as a Web service, your scripts should include handlers for any possible SOAP faults (you’ll find these in the VI API ReferenceGuide for the managed object), to avoid having your script terminate with a error message. If your script doesn’t include fault handling code and a fault is received during script execution, the script terminates with an error message.

The VI Perl Toolkit translates all server-generated faults (including non-SOAP-specific faults) into a Perl object named SoapFault that contains information about the server-side fault.

You can trap both server-generated faults and client-errors using Perl’s eval function, which uses a special variable, $@, to hold the value of any exception raised. The name of the fault is located in the detail property of the Perl error object:

$@->detail

Listing 8 shows a basic approach to error handling.

Saving and Using Sessions

The VI Perl Toolkit library includes several subroutines that let you save and re-use sessions, enabling you to maintain sessions across scripts and use multiple sessions within the same script—for example, to copy information from one server to another.

Using sessions can also enhance security: Instead of storing passwords in scripts, you can instead invoke the connect() subroutine in your script using the name of the session file. The session file contains a token so the password information isn’t exposed or readable.

The session file is an object that’s returned by the login subroutine. Save the object to a sessionfile and then use the session file in another script.

$session1 = Vim->new(service_url => 'https://<hostname1>/sdk');
$session1->login(
        user_name => 'user',
        password => 'secret');


$session2 = Vim->new(service_url => 'https://<hostname2>/sdk');
$session2->login(
        user_name => 'user',
        password => 'secret');

You can then use the session object to reference all functions.

$session1->find_entity_views

To use sessions, you must first login to the server using Vim::login or Util::connect subroutines. Then you can use the vim::save_session and vim::load_session to maintain this connection across multiple scripts. The session remains active until either a logout or disconnect operation is invoked, or until it times out (after 30 minutes, by default).

Learning About Object Structure Using Data::Dumper

The VI Perl Toolkit transparently uses the Data::Dumper Perl module (a standard library) to create the client-side proxy (stub) components known as view objects (views). If you want to learn more about these Perl objects (and how they relate to the VI object model), you can use Data::Dumper as demonstrated in Listing 9.

Lines 12 through 14 set parameters of Data::Dumper that make its output more easily understood:

• Sortkeys causes it to order the name-value pairs alphabetically by name, making it easier for you to find things.
• Deepcopy enables deep copying of structures, so that cross-referencing is done only when necessary.
• Indent set to 2 causes Dumper to take hash key length into account in the output, making for a more readable format.

The sample output produced by line 23 [Listing 9] shows the AboutInfo object’s properties

$VAR1 = bless( {
    'apiType' => 'HostAgent',
    'apiVersion' => '2.0.0',
    'build' => '31178',
    'fullName' => 'VMware ESX Server 3.0.1 build-31178',
    'localeBuild' => '000',
    'localeVersion' => 'INTL',
    'name' => 'VMware ESX Server',
    'osType' => 'vmnix-x86',
    'productLineId' => 'esx',
    'vendor' => 'VMware, Inc.',
    'version' => '3.0.1'
    }, 'AboutInfo' );

This shows the content of the properties of object referred to by the product property of the config property of the summary property of the HostSystem managed object of this server. Perl’s Dumper module writes out the object in a form that can be used with eval to get back a copy of the original structure. The bless keyword indicates that the values between parentheses comprise a Perl object.

Line 19 [Listing 9] gets the HostSystem view and line 21 prints the name associated with that host.

The config property has more values than just those printed by line 23. Line 25 prints out the entire config object. The config object printed by line 25 [Listing 9], the product property is an object. The bless function returns a reference to the product object, which is itself nested inside the config object.

$VAR1 = bless( {
      'name' => 'test-system.eng.vmware.com',
      'port' => 'nnn',
      'product' => bless( {
            'apiType' => 'HostAgent',
            'apiVersion' => '2.0.0',
            'build' => '31178',
            'fullName' => 'VMware ESX Server 3.0.1 build-31178',
            'localeBuild' => '000',
            'localeVersion' => 'INTL',
            'name' => 'VMware ESX Server',
            'osType' => 'vmnix-x86',
            'productLineId' => 'esx',
            'vendor' => 'VMware, Inc.',
            'version' => '3.0.1'
            }, 'AboutInfo' ),
      'vmotionEnabled' => 'false'
      }, 'HostConfigSummary' );

Not shown is the output from line 27 of Listing 9, which prints the structure of the entire summary object of the host view. There are a number of nested objects, including two objects that are nested two levels deep. The product object is nested inside the config object, and the connectionState object is nested inside the runtime object.

5. VI Perl Toolkit Subroutine Reference

Table 6 lists subroutines available through the various VI Perl Toolkit runtime modules and libraries. Unless otherwise noted, parameters listed below are required.

6. Glossary

Copyright © 2007 VMware, Inc. All rights reserved.

VI Perl Toolkit 1.0 | Released 30-Aug-2007 | Last updated 11-October-2007 5:45 pm