Basic vSphere SDK for Perl Script

vSphere SDK for Perl scripts retrieve objects, such as virtual machines, from the server and work with these objects. vSphere SDK for Perl scripts follow the basic pattern shown in Basic vSphere SDK for Perl Script (simpleclient.pl).

Important The sample script does not use filters or property filters for efficiency. See Refining vSphere SDK for Perl Scripts for information about those topics.

Basic vSphere SDK for Perl Script (simpleclient.pl) 

Code element	Discussed in
#!/usr/bin/perl use strict; use warnings; use VMware::VIRuntime;	Step 1: Import the vSphere SDK for Perl Modules.
my %opts = (       entity => {       type => "=s",       variable => "VI_ENTITY",       help => "ManagedEntity type: HostSystem, etc",       required => 1,       }, );   Opts::add_options(%opts); Opts::parse(); Opts::validate();	Step 2: (Optional) Define Script-Specific Command-Line Options.
Util::connect();	Step 3: Connect to the Server.
# Obtain 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);	Step 4: Obtain View Objects of Server-Side Managed Objects.
# Process the findings and output to the console   foreach my $entity_view (@$entity_views) {    my $entity_name = $entity_view->name;    Util::trace(0, "Found $entity_type:    $entity_name\n"); }	Step 5: Process Views and Report Results.
# Disconnect from the server Util::disconnect();	Step 6: Close the Server Connection.

Step 1: Import the vSphere SDK for Perl Modules

All vSphere SDK for Perl scripts must use the VMware::VIRuntime module:

use VMware::VIRuntime;

This module handles all client-side infrastructure details. For example, it transparently maps data types and provides local Perl interfaces to server-side objects. The module also loads subroutines that you can use to connect to a vCenter Server or ESX/ESXi system and to retrieve views. Views are the client-side Perl objects that encapsulate the properties and operations of server-side managed objects. The subroutines are organized into different packages:

■	The Opts package subroutines handle built-in options and creating custom options.

■	The Util package subroutines facilitate routine tasks, such as setting up and closing connections to the server.

■	The Vim package subroutines access server-side managed objects, instantiate local proxy objects (views), update properties, and run local methods that result in operations on remote servers.

See vSphere SDK for Perl Subroutine Reference.

Step 2: (Optional) Define Script-Specific Command-Line Options

When you run a script from the command line, you usually specify connection information and might also specify other information such as a virtual machine that you want to power off or a host for which you need status information. vSphere SDK for Perl lets you specify these options in a variety of ways. See Specifying Options.

A number of common command-line options, most of them connection options, are already defined for all utility applications (see Options Available for All SDK for Perl Commands). In addition, most applications have application-specific options you pass to the script at execution time.

The vSphere SDK for Perl has defined all common options using attributes and subroutines specified in the VILib::Opts package. You can similarly use the VILib::Opts package to create custom options for your own applications and scripts, to simplify use of your script, or to allow users to specify other information.

Example: Basic vSphere SDK for Perl Script (simpleclient.pl) defines an entity option that must be made available to the script at runtime. The option specifies which of the available entity types is passed as a parameter to the Vim::find_entity_views() subroutine for further processing. Any direct or indirect subclass of ManagedEntity is a valid option (for example HostSystem, ResourcePool, or VirtualMachine). The example creates and parses a new command-line option.

1	The example declares the option as a hash. The hash key is the option name, and the value is a hashref containing Getopt::Long-style option attributes. See Attributes for Defining New Options for attribute details.

Example: Basic vSphere SDK for Perl Script (simpleclient.pl) creates a required command-line option that accepts a string value, as follows:

my %opts = (

entity => {

type => "=s",

variable => "VI_ENTITY",

help => "ManagedEntity type: HostSystem, etc",

required => 1,

},

);

Attributes for Defining New Options lists all attributes you can use to define command-line options. The code fragment in Step 1: Import the vSphere SDK for Perl Modules above uses only type, variable, help, and required. For related information, see the documentation for the Getopt::Long module.

Attributes for Defining New Options 

Attribute	Description
default	Default value used if the option is not explicitly set. An unset option with no default returns undef to the calling script.
func	Enables creating derived options. Set func to an external code reference to run the code when the SDK queries the value of the option.
help	Descriptive text explaining the option, displayed in the script’s help message.
required	If this attribute is set to 1, users must provide a value for this option or the script exits and display the help message. Set to 1 to require a value. Set to 0 if the value is optional.
variable	Allows you to specify the option in an environment variable or a configuration file. See Specifying Options.
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. The default numeric value is 0. The default string value is " " (empty string). You can use one of the following: ■ Equal sign (=) — mandatory ■ Colon (:) — optional ■ s — string ■ i — integer ■ f — float

2	The example adds the option to the default options using the Opts::add_options() subroutine:

Opts::add_options(%opts);

3	The example parses and validates the options before connecting to the server, as follows:

Opts::parse();

Opts::validate();

In Example: Basic vSphere SDK for Perl Script (simpleclient.pl), the entity option is required, so the script cannot run unless the user passes in the option name and value (see Specifying Options).

The Vim::find_entity_views() subroutine uses the value the user passes in later in the script. The value must be one of the managed-entity types listed as view_type parameter supported by Vim::find_entity_views().

Note Your script must call Opts::parse() and Opts::validate() to process the options available for all scripts, even if you do not define script-specific command-line options.

When you attempt to run a script and do not supply all necessary options, the vSphere SDK for Perl displays usage help for the script, as in the following example:

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, VirtualMachine...

Step 3: Connect to the Server

The vSphere API is hosted as a secure Web service on a vCenter Server and ESX/ESXi system. By default, the Web service is available over HTTPS. Clients must provide valid credentials to connect to the service. Depending on the specifics of your server, you might have to enter only a user name and password. You might need other information. See Options Available for All SDK for Perl Commands.

A call to Util::connect() connects to the server.

When a script reaches the call to Util::connect(), the vSphere SDK for Perl runtime checks the environment variables, configuration file contents, and command-line entries (in this order) for connection options. If the options are not defined, the runtime uses the defaults (localhost and no user name and password) to set up the connection.

Step 4: Obtain View Objects of Server-Side Managed Objects

When you call the subroutines in the Vim package to retrieve entities from the host, the vSphere SDK for Perl runtime creates the corresponding Perl objects (view objects) locally.

Example: Basic vSphere SDK for Perl Script (simpleclient.pl) uses the Opts::get_option() subroutine to assign to $entity_type the string value of the parameter that the user passes in when executing the script. Example: Basic vSphere SDK for Perl Script (simpleclient.pl) then uses $entity_type 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 Vim::find_entity_views() subroutine creates a local Perl object (an array of references) from the server-side managed object of the specified entity type.

Important This object is static and must be explicitly updated when the corresponding server-side object changes.

Step 5: Process Views and Report Results

The last part of the script processes the views. For this step, you must know the view objects’ properties and methods, so you must understand the server-side objects. See Understanding Server-Side Objects for an introduction. For in-depth information about server-side objects, see the vSphere API Reference Guide which is included on the vSphere SDK for Perl documentation page.

Because views are Perl objects, you use Perl object-oriented syntax to process the views. Example: Basic vSphere SDK for Perl Script (simpleclient.pl) loops through the array of entities returned (@$entity_views) and accesses the name property of each entity by calling $entity_view->name. The example then prints the name of each entity to the console.

See Understanding Server-Side Objects.

Step 6: Close the Server Connection

To log out and exit, use the Util::disconnect() subroutine. Example: Sample Script (Commented Version) shows the complete listing for simpleclient.pl.

Example: Sample Script (Commented Version)

#!/usr/bin/perl

 

# The simpleclient.pl script outputs a list of all the entities of the specified managed-entity

# type (ClusterComputeResource, ComputeResource, Datacenter, Datastore, Folder, HostSystem,

# Network, ResourcePool, VirtualMachine, or VirtualService) found on the target vCenter Server or

# ESX system. Script users must provide logon credentials and the managed entity type. The script

# leverages the Util::trace() subroutine to display the found entities of the specified type.

 

use strict;

use warnings;

use VMware::VIRuntime;

 

# Defining attributes for a required option named 'entity' that

# accepts a string.

#

my %opts = (

entity => {

type => "=s",

variable => "VI_ENTITY",

help => "ManagedEntity type: HostSystem, etc",

required => 1,

},

);

Opts::add_options(%opts);

 

# Parse all connection options (both built-in and custom), and then

# connect to the server

Opts::parse();

Opts::validate();

Util::connect();

 

# Obtain 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);

 

# Process the findings and output to the console

 

foreach my $entity_view (@$entity_views) {

my $entity_name = $entity_view->name;

Util::trace(0, "Found $entity_type: $entity_name\n");

}

 

# Disconnect from the server

Util::disconnect();

 

To run the simpleclient.pl script

1	Open a command prompt or console.

2	Change to the directory that contains the simpleclient.pl script.

3	Run the script using the following syntax:

perl simpleclient.pl <conn_params> --entity <EntityType>

For example:

perl simpleclient.pl --server aquarium.mycomp.com --username abalone --password tank --entity HostSystem

Found HostSystem: abcd-42.shellfish.vmware.com