Understanding Server-Side Objects

When you run a vSphere SDK for Perl script, your goal is to access and potentially analyze or modify server-side objects. You need the name of the vSphere API objects and often their properties and method names. For example, if you want to power off a virtual machine, you must know how to find the corresponding object, what the name of the power off method is, and how to run that method.

The vSphere API Reference Guide gives reference documentation for all vSphere API objects. Some users might also find the vSphere Web Services SDK Programmer’s Guide helpful for understanding how the vSphere API objects interact. The guides are available from the VMware APIs and SDKs Documentation page.

This section first introduces the Managed Object Browser (MOB), which allows you to browse all objects on a remote host. The rest of the section discusses how to work with these server-side objects. You learn how to find the objects, access and modify properties, and how to run a method on the server.

Use the Managed Object Browser to Explore Server-Side Objects

The MOB is a Web-based server application hosted on all ESX/ESXi and vCenter Server systems. The MOB lets you explore the objects on the system and obtain information about available properties and methods. It is a useful tool for investigating server-side objects and for learning about the vSphere object model.

To access the MOB on any ESX/ESXi or vCenter Server system

1	Start a Web browser.

2	Connect to the MOB using the fully-qualified domain name (or the IP address) of the ESX/ESXi or vCenter Server system, as follows:

https://<hostname.yourcompany.com>/mob

The browser prompts you for a user name and password for the host.

3	Enter the user name and password.

After you enter the user name and password, the host might display warning messages regarding the SSL certificate authority, such as Website Certified by an Unknown Authority. If VMware is the certificate authority, you can disregard such warnings and continue to log in to the MOB.

When you are successfully connected to the MOB, the browser displays the managed object reference for the service (ManagedObjectReference:ServiceInstance), available properties (with values), and methods, as shown in Managed Object Browser.

Managed Object Browser

Types of Managed Objects and the Managed Object Hierarchy

A managed object is the primary type of object in the vSphere object model. A managed object is a data type available on the server that consists of properties and operations. Each managed object has properties and provides various services (operations or methods). ExtensibleManagedObject Hierarchy shows the ExtensibleManagedObject hierarchy as an example. See Managed Entities in the Inventory.

ExtensibleManagedObject Hierarchy

Managed objects define the entities in the inventory and also common administrative and management 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). See the vSphere API Reference.

A managed object reference (represented by a ManagedObjectReference) identifies a specific managed object on the server, encapsulates the state and methods of that server-side object, and makes the state and methods available to client applications. Clients run methods (operations) on the server by passing the appropriate managed object reference to the server as part of the method invocation.

Managed Object Hierarchy

The ServiceContent server-side object provides access to all other server-side objects. Each property of the ServiceContent object is a reference to a specific managed object. You must know those property names to access the other objects. You can use the MOB (see Use the Managed Object Browser to Explore Server-Side Objects) or use the API Reference documentation.

The vSphere API Reference Guide contains definitions of all server-side objects and their properties and methods. You can therefore use the vSphere API Reference Guide to identify the list of parameters and operations that you can use with specific vSphere SDK for Perl views that you create and manipulate in your code.

To view documentation for server-side objects

1	Find the vSphere API Reference Guide, available from the VMware APIs and SDKs Documentation page.

2	Click All Types to see a list of all managed object types.

3	Find the ServiceContent object.

ServiceContent provides access services, such as PerformanceManager, and to inventory objects, which allow you to access the entities in the virtual datacenter such as hosts (HostSystem) and virtual machines (VirtualMachine). ServiceContent properties also allow access to other managed objects, for example:

■	The rootFolder property is a ManagedObjectReference to a Folder managed object type.

■	The perfManager property is a ManagedObjectReference to a specific instance of a PerformanceManager managed object type, and so on.

The vSphere Client displays the hierarchy of inventory objects. The vSphere Client uses the information about the objects (the properties and the relationships among them) for the display. For information about the vSphere Client and how to work with its display, see the documents in the vSphere online library

Managed Entities in the Inventory

The inventory consists of the managed entities on the server. A managed entity is a managed object that extends the ManagedEntity managed object type. ManagedEntity is an abstract class that defines the base properties and operations for vSphere managed objects such as datacenters and hosts. See ExtensibleManagedObject Hierarchy for an overview. The following managed object types extend the ManagedEntity superclass:

■	Datacenter – Contains other managed entities, including folders, virtual machines, and host systems. A vCenter Server instance can support multiple datacenters, but an ESX/ESXi host supports only one datacenter.

■	Datastore – Represents logical storage volumes on which to store virtual machine files and other data.

■	Distributed Virtual Switch – Interface for the VMware distributed virtual switch (DVS).

■	Folder – Contains references to other entities, for example, other folders (Folder) or hosts (HostSystem).

■	HostSystem – Provides access to a virtualization host platform.

■	Network – Abstraction for a physical or virtual network (VLAN).

■	VirtualMachine – Represents a single virtual machine.

■	ResourcePool – Allows you to combine CPU and memory resources from multiple hosts and to establish rules for dividing those resources among all virtual machines associated with these hosts.

■	ClusterComputeResource – Represents a cluster of HostSystem objects. Administrators create clusters to combine the CPU and memory resources of hosts and to set up VMware HA or VMware DRS for those clusters. See the Resource Management Guide, which is part of the vSphere documentation set.

■	ComputeResource – Abstracts a host system’s physical resources and allows you to associate those resources with the virtual machines that run on the host.

■	VirtualService – Container for one or more virtual machines an associated object package using open virtual format (OVF).

Managed entities offer specific operations that vary depending on the entity type. For example, a VirtualMachine managed entity provides operations for creating, monitoring, and controlling virtual machines. You can power a virtual machine on or off (PowerOnVM, PowerOffVM) and you can capture state (Snapshot). A HostSystem entity provides operations for entering and exiting maintenance mode (EnterMaintenanceMode_Task, ExitMaintenanceMode_Task) and for rebooting the server (RebootHost_Task).

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

Accessing Server-Side Inventory Objects

The vSphere SDK for Perl provides subroutines for accessing server-side inventory objects and other managed objects that provide functionality to the server as a whole.

Example: Sample Script (Commented Version) obtains all entities of a specific type from the inventory. The entity type is passed as a parameter to the Vim::find_entity_views() subroutine, which returns an array of references to view objects that map to the corresponding server-side entities.

Example: Following Changes in a Log File starts at the level of the entire service and uses the Vim::get_service_content() subroutine to obtain an instance of the ServiceContent object:

my $content = Vim::get_service_content();

You can use the ServiceContent object to retrieve a local view of the services provided by the server, as in this example:

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

Example: Following Changes in a Log File shows how these two calls form the basis of a script that follows changes in the log file, which can be accessed as the logfile property of the diagnosticManager.

Example: Following Changes in a Log File

#!/usr/bin/perl

#

# Copyright 2007 VMware, Inc. All rights reserved.

#

# This script creates a Perl object reference to the ServiceContent data

# object, and then creates a reference to the diagnosticManager. The script

# follows ('tails') the log as it changes.

use strict;

use warnings;

 

use VMware::VIRuntime;

 

# read/validate options and connect to the server

Opts::parse();

Opts::validate();

Util::connect();

 

# get ServiceContent

my $content = Vim::get_service_content();

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

# Obtain the last line of the logfile by setting an arbitrarily large

# line number as the starting point

my $log = $diagMgr->BrowseDiagnosticLog(

   key => "hostd",

   start => "999999999");

my $lineEnd = $log->lineEnd;

 

# Get the last 5 lines of the log first, and then check every 2 seconds

# to see if the log size has increased.

my $start = $lineEnd - 5;

 

# Disconnect on receipt of an interrupt signal while in the infinite loop below.

$SIG{INT} = sub { Util::disconnect();

exit;

};

 

while (1) {

 $log = $diagMgr->BrowseDiagnosticLog(

   key => "hostd",

   start => $start);

 if ($log->lineStart != 0) {

  foreach my $line (@{$log->lineText}) {

  # next if ($line =~ /verbose\]/);

  print "$line\n";

  }

 }

 $start = $log->lineEnd + 1;

 sleep 2;

}