Web Services for Management Perl LibraryVMware ESX Server 3.5, VMware ESX Server 3i version 3.5, and VMware VirtualCenter 2.5
In the VMware Infrastructure (VI) Perl Toolkit 1.5, VMware® provides an early‐adopter Perl library so you can start integrating your virtual infrastructure into the Web Services for Management (WS‐Management) framework, a high‐level standard for network administration.
How Web Services for Management Fits Into the VMware InfrastructureThe VMware Infrastructure API provides an object model for VMware virtual systems. Built on top of this API, the VI Perl Toolkit is a high‐level programming interface that simplifies VMware infrastructure management. Although unrelated, the Web Services for Management library is delivered as part of the VI Perl Toolkit.
The VMware CIM SDK provides a Common Information Model (CIM) interface for developers building management applications. With the SDK, developers can write CIM‐compliant applications to explore virtual machines and associated resources on an ESX Server and elsewhere. The Web Services for Management library provides a connection between VMware infrastructure CIM objects and the industry standard framework.
Understanding Web Services for ManagementWeb Services for Management offers a common language for network entities to share data about themselves, so you can manage them more easily. This Perl library contains, as stub modules, interfaces for almost all VMware devices, and over a hundred methods to interact with CIM, another network management standard. VMware wants to help IT departments use these standard frameworks to centrally manage hardware, storage, operating systems, networks, and services.
Based on existing web services, Web Services for Management specifies a simple object access protocol (SOAP) for the management of servers, devices, storage, applications, and so forth. SOAP is a popular method for exchanging XML‐based messages over computer networks, usually by remote procedure call.
Distributed Management Task Force (DMTF) published the Web Services for Management (WS‐Management) 1.0.0a document in April 2006, authored by representatives from 15 major companies. In August 2006, DMTF published a related document describing bindings, or mappings, from the CIM to WS‐Management.
The Web Services for Management specification is extensive, so its power and functionality are more akin to HP OpenView or to Netconf (RFC 4741 from IETF) than to Simple Network Management Protocol (SNMP). Web Services for Management can simplify network administration by providing a common way for systems to access and exchange information sitewide, permitting remote administration of many entities on a network.
The Web Services for Management Perl library provides the stubs and SOAP interfaces to leverage the DMTF infrastructure to work with distributed VMware systems. The Web Services for Management Perl library is experimental and not supported for production use. This document describes version 0.1 of the library.
NOTE The Web Services for Management Perl library is currently experimental.
DMTF specifications for WS‐Management, CIM bindings: http://www.dmtf.org/standards/wsman
Open Management with CIM (OMC) project: http://developer.novell.com/wiki/index.php/OMC
Introduction to and specifications for Meta Object Facility (MOF): http://www.omg.org/mof/
Installing the Web Services for Management Perl LibraryThe Web Services for Management Perl library depends on the following Perl modules:
SOAP::Lite – At least version 0.67.
UUID – At least version 0.02.
Data::Dump – At least version 1.07.
Installing the Dependencies
If the system you are using is behind a firewall, make sure that your http_proxy and ftp_proxy environment variables are set properly before proceeding with the following instructions for Windows or Linux.
To Install Dependencies on a Windows System
1 Determine which version of Perl you are using by issuing the perl ‐v command.
For version 5.6, open a terminal window and type the following at the command prompt:
3 Issue the following command to install Data::Dump:
C:>ppm install Data-Dump
To Install Dependencies on a Linux System
1 Open a terminal window and enter the following commands for remote access to CPAN (comprehensive Perl archive network):
$ sudo -s# perl -MCPAN -e shell
2 Issue the following command at the CPAN prompt to install SOAP::Lite:
cpan> install SOAP::Lite
Answer any questions and the module installs.
3 Go to http://search.cpan.org, search for UUID, and download the latest source. Untar the downloaded file, open a terminal window, and go to the untarred directory. Issue the following commands to install UUID:
# make# make test# make install
If the make displays errors about missing items, install uuid-dev with apt-get on Debian‐based systems or e2fsprogs-dev[el] on other systems.
4 Open a terminal window and issue the following commands to install Data::Dump:
The Web Services for Management library is included in the VMware Infrastructure (VI) Perl Toolkit 1.5, available under http://vmware.com/support/developer on the VMware Web site.
In the VI Perl Toolkit applications tree, look for examples under Perl/samples/WSMan. Currently there are programs to check sensor health, get firmware revisions, list field‐replaceable units, and show power supplies.
Perl modules reside in Perl/lib/WSMan, and are documented in “API Reference for Perl Modules” on page 3.
Stubs that map CIM objects and Object Management with CIM (OMC) are in Perl/lib/WSMan/Stubs.
The CIM mappings are defined by DMTF. For information about the CIM infrastructure and schema, see the http://www.dmtf.org Web site under standards for CIM.
The OMC mappings are from the OMC project, which is coordinated from the Novell developer web site; see http://developer.novell.com/wiki/index.php/OMC‐faq for details.
Stubs (Perl modules) to manage most VMware devices are also in Perl/lib/WSMan/Stubs.
API Reference for Perl ModulesThe Web Services for Management Library consists of the following Perl modules:
“WSBasic.pm – Basic Services and CIM Binding Library” on page 3
“GenericOps.pm – Generic Operations for CIM” on page 7
“StubOps.pm – Object‐Oriented Wrapper for Generic Operations” on page 10
“Stubs Directory” on page 13
WSBasic.pm – Basic Services and CIM Binding Library
This module provides a class called WSBasic, which is used to construct SOAP messages for communication with the Web Services for Management server. All operations return the deserialized SOAP::SOM objects from which you can extract the fault‐code or the SOAP replies.
Under normal circumstances, you do not use this library directly. You generally use the GenericOps library built on top of this library to provide generic operations as defined by the DMTF standards. For GenericOps, see “GenericOps.pm – Generic Operations for CIM” on page 7. If you want to use the SOAP::SOM library directly, see the CPAN documentation for SOAP::SOM.
This argument provides the URL of the server running Web Services for Management service. You must specify the transport protocol by adding http or https prefix for HTTP (basic user‐password authentication) or HTTP with SSL encryption. This argument is mandatory.
port
This argument specifies the port on which the Web Services for Management server responds. This argument is mandatory.
path
This argument provides the path to the Web Services for Management server. This is combined with the address and port arguments to form the complete URL of the Web Services for Management server in the usual ʹhttp://address:port/pathʹ order. This argument is mandatory.
username
Provides the user name for the Web Services for Management server. This argument is mandatory.
password
Provides the password for the Web Services for Management server. This argument is mandatory.
namespace
Gives the default CIM namespace. This argument is optional, otherwise ‘root/cimv2’ is the default.
timeout
Specifies a timeout for the HTTP request, in case of slow servers. This argument is optional.
register_xml_ns
This method registers extra XML namepaces that might be required for proprietary tags in the SOAP message. Under normal circumstances, calling this is not required. The argument to this function is a hash containing prefixes to be used as keys, and relative URLs as values. For example, this line declares a prefix wsen with the URL http://www.dmtf.org/wsen in the global XML namespace:
This method registers extra CIM namepaces that the Web Services for Management server might require. By default, the constructor provides a set of namespaces for CIM classes. Review the server configuration files to see if other CIM namespaces are required. The usage is the same as for register_xml_ns.
Identify
This method performs the wsmid:Identify operation, which causes the Web Services for Management server to identify itself. The function takes no arguments. The method returns a SOAP::SOM object, which you can use to parse the results or do error correction.
This method is extremely versatile. Results are filtered differently depending on what optional arguments you pass in. Several arguments perform generic operations that are implemented in another class, as described in “GenericOps.pm – Generic Operations for CIM” on page 7. Other arguments implement enumeration for non‐standards‐compliant servers. This section discusses the most common arguments. The Enumerate method returns a SOAP::SOM object that can be used to either check for errors ($result->fault) or to parse the results ($result->result). The SOAP object includes header and data in XML format. Enumerate accepts the following arguments:
class_name
This argument allows you to specify the class that you wish to enumerate. This argument is the only mandatory argument to the Enumerate method, and is passed as a string.
namespace
Specifies the CIM namespace for the class. This argument is passed as a string. The default is usually ʹroot/cimv2ʹ but can change depending on the Web Services for Management server.
enummode
Allows you to specify an enumeration mode such as EnumerateEPR or EnumerateEPRandObject. This argument is passed as a string.
polymorphism
This option allows for various polymorphism modes such as IncludeSubClassProperties, ExcludeSubClassProperties, and None. This argument is passed as a string.
To understand other arguments that can be passed to the Enumerate method, look at the Perl code.
PullRelease
An overloaded method that provides either the Pull operation or the Release operation. Only the common arguments are discussed below. PullRelease takes these arguments:
enumid
Specifies the enumeration ID that the Pull or the Release operation should use. This argument is mandatory, and is passed as a string.
action
This argument specifies whether the method should perform a Pull operation or a Release operation. The possible values are Pull or Release. This argument is mandatory, and is passed as a string.
namespace
This argument specifies the namespace for the CIM class on which you are performing the action. This is optional except when required by CIM, and is passed as a string.
Get
Retrieves a particular instance of a class. It takes the following named arguments:
class_name
Specifies the class whose instance you wish to retrieve. This argument is mandatory and is passed as a string.
options
Passes keys for the particular instance on which you wish to perform a Get operation. The argument is mandatory and is passed as a hash containing the keys in name‐value pairs.
namespace
Specifies the namespace for particular CIM class. This argument is optional and is passed as a string.
The WSMan::WSBasic library requires the following modules:
SOAP::Lite – Version 0.65 or later is required by the library to form SOAP messages and to parse XML replies that are received from the Web Services for Management server.
UUID – Required to generate UUIDs for the SOAP messages.
Code Examples
You can use the library to do a simple Enumerate and Pull operation:
#!/usr/bin/perl -w use strict; use WSMan::WSBasic; #Import the module. my ($enumid, result, $client); #declaring variables. #Construct the client. $client = WSMan::WSBasic->new( path => 'wsman', username => 'wsman', password => 'secret', port => '8889', address => 'http://something.somewhere.com' ); #Invoke the Enumerate method. $result = $client->Enumerate(class_name => 'CIM_Processor', #namespace => 'root/cimv2' ); if($result->fault){ #If a fault occurred, then print the faultstring die $result->faultstring; } else{ #If no fault occurred then get the enumid. $enumid = $result->result; } $result = $client->PullRelease( class_name => 'CIM_Processor', enumid => $enumid, action => 'Pull', #namespace => 'root/cimv2' ); if($result->fault){ #If a fault occurred, then print the faultstring die $result->faultstring; } else{ # Do stuff with $result, which is a SOAP::SOM object containing a deserialized XML reply. # It is better to use the Generic Operations module, built on top of this module. }
To use one of the enumeration modes like EnumerateEPR or EnumerateEPRandObject, call the Enumerate operation with EnumerationMode enabled. This could also be done in the constructor call.
To perform operations on vendor specific classes, you must register them first with the client. The actual URL depends on your Web Services for Management software.
The GenericOps library implements some of the generic operations specified in the Web Services for Management CIM bindings published by the DMTF. At this time, not all generic operations are implemented, but the library is still very much a work in progress. For information about assembling more advanced features, see the WSBasic library, which provides primitive intrinsic Web Services for Management operations.
The following methods are defined by the GenericOps class:
new
Constructor that takes a hash argument containing key‐value pairs in the following form:
This argument provides the URL of the Web Services for Management server. You must specify the transport protocol by adding either the http prefix for HTTP (basic user‐password authentication) or the or https prefix for HTTP with SSL encryption. This argument is mandatory.
port
Specifies the port on which Web Services for Management responds. This argument is mandatory.
path
Provides the path to the Web Services for Management server. This is combined with the address and port arguments to form the complete URL of the Web Services for Management server in the usual ʹhttp://address:port/pathʹ order. This argument is mandatory.
username
Provides the user name for the Web Services for Management server. This argument is mandatory.
password
Provides the password for the Web Services for Management server. This argument is mandatory.
Gives the default CIM namespace. This argument is optional, otherwise ‘root/cimv2’ is the default.
timeout
Specifies a timeout for the HTTP request, in case of slow servers. This argument is optional.
register_xml_ns
This method registers extra XML namepaces that might be required for proprietary tags in the SOAP message. Under normal circumstances, calling this is not required, unless you are trying to extend the library itself. The argument to this function is a hash containing prefixes to be used as keys, and relative URLs as values. For example, this line declares a prefix wsen with the URL http://www.dmtf.org/wsen in the global XML namespace:
This method registers extra CIM namepaces that the Web Services for Management server might require. By default, the constructor provides a set of namespaces for CIM classes. Review the server configuration files to see if other CIM namespaces are required. The usage is the same as for register_xml_ns.
Identify
This method performs the wsmid:Identify operation, which causes the Web Services for Management server to identify itself. This is particularly useful to check whether the server is up and running. The function takes no arguments. The method either prints a fault string, if a fault occurs, or returns the reply sent by the server. The reply is a hash reference containing the parsed reply in key‐value pairs.
EnumerateInstances
Enumerates the instances of a given class. The method returns a list of hashes containing the parsed reply from the server, or prints a fault string from the server if an error occurs. The common way to use the method is as follows:
Enumerates only the key values of the instances of a given class. Like EnumerateInstances, this method returns a list of hashes containing the parsed reply from the server, with keys only, or prints a fault string if an error occurs. The call to this method is similar to EnumerateInstances.
EnumerateAssociatedInstances
Returns the instances related to the source object through an association. Results are filtered differently depending on optional arguments. A typical way to use the method is as follows
This argument takes the class name for which you wish to get the associated instances. This is one of only two required arguments for this method call.
This argument takes the selector‐set keys as a reference to a hash, which is required to identify the particular instance of the class mentioned in the class_name argument.
associationclassname
This argument takes the association class name by which the instances are associated. This argument is optional.
role
This argument takes the specified role that the object plays in the association class and filters the results according to the role. This argument is optional.
resultclassname
This argument takes the result class name, which should be present in the association, and returns only those instances. This argument is optional.
resultrole
Specifies the role that the result class plays in this instance and returns the results based on the filter. This argument is optional.
includeresult
Further filters query results based on properties of the instances. These properties can be passed in the form of a name‐value pair hash then passed as a reference to this hash in the includeresult named argument. This argument is optional.
namespace
Gives the default CIM namespace. This argument is optional, otherwise ‘root/cimv2’ is the default.
EnumerateAssociatedInstanceNames
This method returns objects with only the key values of the associated instance populated. The usage is the same as for EnumerateAssociatedInstances.
EnumerateAssociationInstances
Returns objects containing association instances of which the class is a part. The usage is the same as for EnumerateAssociatedInstances.
EnumerateAssociationInstanceNames
Returns objects containing key values of the association instances of which the class is a part. The usage is the same as for EnumerateAssociatedInstances.
GetInstance
This method gets a particular instance of a class. It prints the fault string or returns the result in a hash, and takes the following named arguments:
class_name
Specifies class name, passed as a string, whose instance you wish to get. This argument is mandatory.
options
Passes in keys for the instance on which you wish to perform the GetInstance operation. The argument is passed as a hash containing the keys in name‐value pairs. This argument is mandatory.
namespace
Gives the default CIM namespace. This argument is optional, otherwise ‘root/cimv2’ is the default.
Dependencies
The WSMan::GenericOps library requires the WSMan::WSBasic module.
The StubOps library provides a wrapper for generic operations so that replies to queries requested of the server can be returned as Perl objects rather than as hashes. Each of these objects has accessor methods associated with each object variable, and a set of common methods. These objects are basically Meta Object Facility (MOF) files compiled into Perl modules. MOF was developed by the Object Management Group (OMG). See “References for Further Reading” on page 2.
The following methods are defined by the StubOps class:
new
Constructor that takes a hash argument containing key‐value pairs in the following form:
This argument provides the URL of the Web Services for Management server. You must specify the transport protocol by adding either the http prefix for HTTP (basic user‐password authentication) or the or https prefix for HTTP with SSL encryption. This argument is mandatory.
port
Specifies the port on which Web Services for Management responds. This argument is mandatory.
path
Provides the path to the Web Services for Management server. This is combined with the address and port arguments to form the complete URL of the Web Services for Management server in the usual ʹhttp://address:port/pathʹ order. This argument is mandatory.
username
Provides the user name for the Web Services for Management server. This argument is mandatory.
password
Provides the password for the Web Services for Management server. This argument is mandatory.
Gives the default CIM namespace. This argument is optional, otherwise ‘root/cimv2’ is the default.
timeout
Specifies a timeout for the HTTP request, in case of slow servers. This argument is optional.
register_xml_ns
This method registers extra XML namepaces that might be required for proprietary tags in the SOAP message. Under normal circumstances, calling this is not required, unless you are trying to extend the library itself. The argument to this function is a hash containing prefixes to be used as keys, and relative URLs as values. For example, this line declares a prefix wsen with the URL http://www.dmtf.org/wsen in the global XML namespace:
This method registers extra CIM namepaces that the Web Services for Management server might require. By default, the constructor provides a set of namespaces for CIM classes. Review the server configuration files to see if other CIM namespaces are required. The usage is the same as for register_xml_ns.
Identify
This method performs the wsmid:Identify operation, which causes the Web Services for Management server to identify itself. This is particularly useful to check whether the server is up and running. The function takes no arguments. The method either prints a fault string, if a fault occurs, or returns the reply sent by the server. The reply is an object of the type IdentifyResponse. You can get all the key‐value pairs from the reply either by using the object as a normal hash, or if you know the names of the keys, using the get() method to obtain values by passing in the key names, in string form, as an argument to the method. For convenience, the object also contains the to_string() method to convert the whole object into a string.
EnumerateInstances
This method enumerates the instances of a given class. The method yields a list of objects returned by the server, or prints a fault string from the server if one occurs. A common way to use the method is as follows:
That query returns all instances of the CIM_Processor object returned by the server. For an explanation of methods that can be called on the returned objects, see descriptions under “Stubs Directory” on page 13.
EnumerateInstanceNames
Enumerates only the key values of instances of a given class. Like EnumerateInstances, this method yields a list of objects returned from the server, or prints a fault string if an error occurs. The objects returned have only the key values populated. The call to this method is similar to EnumerateInstances. For an explanation of methods that can be called on returned objects, see the descriptions under “Stubs Directory” on page 13.
EnumerateAssociatedInstances
Returns the instances related to the source object through an association. Results are filtered differently depending on optional arguments. A typical way to use the method is as follows:
This argument takes an instance of the class, which is the starting point of association traversal. Usually you get this object by performing an EnumerateInstances or EnumerateInstanceNames operation. The latter has only keys filled in, but that is enough. This argument is mandatory.
associationclassname
Takes the association class name by which the instances are associated. This argument is optional but might be required by some providers.
role
Takes the specified role that the object plays in the association class and filters the results according to the role. This argument is optional.
resultclassname
Takes the result class name, which should be present in the association, and returns only those instances. This argument is optional.
resultrole
Specifies the role that the result class should play in this instance and returns results based on the filter. This argument is optional and untested.
includeresult
Further filters query results based on properties of the instances. These properties can be passed in the form of a name‐value pair hash then passed as a reference to this hash in the includeresult named argument. This argument is optional and untested.
namespace
Gives the default CIM namespace. This argument is optional, otherwise ‘root/cimv2’ is the default.
EnumerateAssociatedInstanceNames
This method returns objects with only the key values of the associated instance populated. The usage is the same as for EnumerateAssociatedInstances.
EnumerateAssociationInstances
Returns the object containing association instances of which the class is a part. The usage is the same as for EnumerateAssociatedInstances.
EnumerateAssociationInstanceNames
Returns the object containing key values of the instances of which the class is a part. The usage is the same as for EnumerateAssociatedInstances.
GetInstance
This method gets a particular instance of a class. It returns the requested object, or prints the fault string, and takes the following named arguments:/
objectpath
Takes an instance of the class for which the instance is required. You get this object by performing an EnumerateInstances or EnumerateInstanceNames operation. The latter has only keys filled in, but that is enough. This argument is mandatory.
namespace
Allows you to specify the namespace for a particular CIM class, as a string. This argument is optional.
The WSMan::StubOps library requires the following modules:
WSMan::WSBasic
WSMan::GenericOps::Data::Dump
Stubs Directory
Location of Perl modules: Perl/lib/WSMan/Stubs
Name
The Stubs directory in the VMware installation folder contains Perl modules that are object‐oriented Perl representations of various MOF (Meta Object Facility) models.
Description
The Stubs directory contains most of the classes supported by VMware. They are compiled directly from MOF files into Perl classes. There are about 200 Perl modules in the Stubs directory and each of them is a meta‐object class translated into a Perl class. These modules are also called stubs in this document.
Under normal circumstances, you do not create instances of these stubs directly; they are used by methods in the StubOps module. See “StubOps.pm – Object‐Oriented Wrapper for Generic Operations” on page 10.
All the Stubs inherit class objects from Initializable.pm, which contains methods for initializing the classes as well as some common methods required by all classes.
Methods Common to All Stubs
The following methods are common to all stubs:
new
This method instantiates a particular class. The method can be invoked with no arguments, in which case all the fields in the class are initialized to undef. If you need to set the fields to a particular value, pass in the fields with the desired values as a hash containing the key value pairs.
clone
You can call this method on any of the instantiated objects and it returns an exact copy of the object. This may be used to provide a deep copy mechanism for the objects.
to_string
Use this method to serialize the object into a string. This string can be passed to the print function for display on standard output, or it can also be parsed by eval to produce a clone of the object.
get_selectorset
Use this method to return the key values that define a unique instance of the object. These values are returned as a hash reference.
accessors
Every stub has a separate accessor method for each of the variables in the class. The accessor name is the same as the variable name. If the accessor is called without any argument, it returns the present value of the variable. If the accessor is called with an argument, then the value of the variable is set to the passed‐in value and the modified value is returned. As an example consider Processor to be an instance of CIM_Processor. The CIM_Processor class has a class variable called DeviceID. To access the value of DeviceID, call the accessor method on the Processor instance as Processor->DeviceID, which returns the value of the DeviceID variable. To change the value of this variable, you call the accessor method as follows, which changes the present value to ʹ4.0ʹ and also returns this changed value:
Under normal circumstances, you are not required to instantiate any of the stubs. However, if the need arises, you can import stubs into your script with the following implied syntax: WSMan::Stubs::CIM_Processor. The catch is that after importing the module you must instantiate the new object as follows. Note the lack of leading package identifier WSMan::Stubs:: in this instantiation statement, a shortcut:
