VMware logo

VMware Infrastructure (VI) Perl Toolkit Appliance Guide

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 familiar with Perl (rather than with Java, C#, or other programming languages) can leverage the power of the VI API without the complexity of Web-services client development. Better still, the Perl Toolkit includes numerous ready-to-run Utility Applications that can be put to use immediately, or easily extended, along with a variety of sample scripts to help get you started creating your own new applications.

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

The VI Perl Toolkit is distributed in several formats, all available from VMware:

Windows and Linux installation wizards
Packaged as a Virtual Appliance
Source code bundle that can be used to make and install the VI Perl Toolkit on any platform that supports Perl.

This Appliance Guide includes these topics:

Preface
Preliminary Connectivity Check
Installing the VI Perl Toolkit Virtual Appliance
Using the the Perl Toolkit Virtual Appliance
Running the VI Perl Toolkit Utility Applications

Once you have the VI Perl Toolkit Appliance installed, you can run any of the Utility Applications, or write your own scripts.

See the VI Perl Toolkit Programming Guide for information about writing scripts.

Contacting VMware: VMware welcomes your suggestions for improving technical publications. You can email your feedback to docfeedback@vmware.com

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 Appliance 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:

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 VI Perl Toolkit 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.

Developer Resources	http://www.vmware.com/support/developer
Discussion forums	http://www.vmware.com/community
Product information	http://www.vmware.com/products/
User groups	http://www.vmware.com/vcommunity/usergroups.html
VMTN Knowledge Base	http://www.vmware.com/support/kb
VMware Infrastructure technical publications	http://www.vmware.com/support/pubs/vi_pubs.html
VMware Technology Network	http://www.vmtn.net

Contacting VMware

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

docfeedback@vmware.com

Installing the VI Perl Toolkit Virtual Appliance

The VI Perl Toolkit Virtual Appliance comprises a complete Linux distribution (Debian 3.1) with everything you need, pre-installed—Perl engine, VI Perl Toolkit components and pre-requisites, sample scripts, and Utility Applications. During the process of installing the Virtual Appliance, several accounts are created, including:

root
network
visdk

The password you create for root during the installation process is also used for the network account; the visdk user account has a default password of visdk.

You can run any of the Utility Applications as soon as the Virtual Appliance installation is complete:

Log on to the appliance as visdk
Navigate to the apps directory, located here:

/usr/lib/vmware-viperl/apps<

The next several sections describe the VI Perl Toolkit Virtual Appliance installation process in more detail.

Requirements for the VI Perl Toolkit Virtual Appliance

The VI Perl Toolkit Virtual Appliance can be installed in any of these VMware products: VMware Server, VMware Workstation, or VMware Player. You can obtain these from VMware’s website at:

VMware Host Product	Download Location
VMware Player	www.vmware.com/products/player
VMware Server	www.vmware.com/products/server
VMware Workstation	www.vmware.com/products/ws

If necessary, download and install one of the products listed in the table.

If you do not already have VMware Server or Workstation installed, consider downloading and using VMware Player—it’s free and can be installed in just a few minutes. The VI Perl Toolkit Virtual Appliance installation instructions that follow focus on using the VMware Player.

Installing the Virtual Appliance

These instructions assume that your host system already has one of the required VMware hosted products—VMware Server, VMware Workstation, or VMware Player— installed and running.

To install the VI Perl Toolkit Virtual Appliance:

Obtain the VI Perl Toolkit Virtual Appliance from VMware’s download page (requires VMware Store account log in and acceptance of license agreement):
http://http://www.vmware.com/download/home.html
Uncompress the downloaded archive into the “virtual machines” directory of the VMware hosted product. For example, for VMware Player, unzip into c:\Virtual Machines (assuming you accepted the defaults during VMware Player installation). As another example, the default sub-directories for VMware Server are as follows:

Linux: Windows:

/usr/vmware/virtualmachines/ C:\vmware\virtualmachines

(Note that you need root permissions to write to /usr/vmware/virtualmachines.)
Launch the VMware hosted product. When the console displays:
- Select File-->Open... from the console menu. The Open Virtual Machine selection box displays.
- Click Browse... to navigate to the directory containing the uncompressed archive.
- Navigate to the VMware-VI-Perl-Toolkit-Appliance.vmx file.
  - Click the filename to select it.
  - Click Open... to complete the process.
Start the virtual machine by selecting the “Start the Virtual machine” command, or by selecting the "Power On" button. In a few seconds, you’ll be prompted to perform a few minor setup tasks associated with deploying the appliance, including:
- Creating a password for root. (Remember this password—you will need it later to access the appliance management web interface, and to login to the appliance at the console.)
- Configuring the appliance network. By default, the appliance uses DHCP to obtain an IP address and configure a virtual adapter (eth0) for the appliance (using bridged network). (If you want to use a static IP address, you can configure it later, by using the Appliance’s management page.)
  - If your host system uses a proxy server to access the internet, enter the server address and port number at the prompt.

Linux:		Windows:
/usr/vmware/virtualmachines/		C:\vmware\virtualmachines

At the end of the process, you’ll see the VI Perl Toolkit running as a virtual machine in VMware Server, Workstation, or VMware Player. At this point, you can:

Log into the appliance and start working the VI Perl Toolkit scripts.
Connect to the appliance’s management page from a web browser on the host system or another system.

Note: In a production environment, you should change the default password for the visdk user immediately after the installation is complete. To change the default password for visdk:

Log in using the visdk user account with the default password, visdk.

<hostname> login: _
The Linux shell displays visdk@<hostname>:~$
At the Linux shell prompt, enter the passwd command to change the password: passwd initiates a series of prompts that guides you through the process, as shown here:

passwd
Changing password for visdk
(current) UNIX password:
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully
visdk@<hostname>:~$

Validating the VI Perl Toolkit Installation

After installing the VI Perl Toolkit Virtual Appliance, you can confirm successful installation by running any one of the Utility Applications.

Running a Sample Script

To navigate to the samples sub-directory

/usr/share/doc/vmware-viperl/samples

In the samples sub-directory, you’ll find several other sub-directories, including:

discovery
host
performance
vm

The datacenterlisting.pl (in the \samples\discovery folder), is a good place to start. It’s a basic discovery utility that obtains a list of hosts and virtual machines running at the specified server. You must pass to the script (as a parameter) the name of the ESX Server host or VirtualCenter Management Server host system.

To run the script:

Navigate to the /samples sub-directory:
/usr/share/doc/vmware-viperl/samples
Enter perl and the precise name of the script (capitalization must match), including the path within the /samples directory, passing any required parameters. For example, for the datacenterlisting script, you would enter:

perl discovery/datacenterlisting.pl --host 'servername_or_ip_address' --datacenter 'datacenter_name'

Or simply navigate to the /discovery before running the script, saving yourself from typing the directory name:

cd discovery
perl datacenterlisting.pl --server 'servername' --datacenter 'datacenter_name'

For example, running datacenterlisting.pl against a VirtualCenter Management Server might be as follows:

perl discovery/datacenterlisting.pl --server 10.17.152.252 --datacenter Primary_Datacenter --username Administrator --password password

If you are testing your setup against an ESX Server host, you must pass an empty string to the datacenter parameter, as in:

perl discovery/datacenterlisting.pl --server 10.17.152.252 --datacenter ' ' --username root --password password

3. Using the VI Perl Toolkit Virtual Appliance

The VI Perl Toolkit Virtual Appliance provides everything you need to get started using the VI Perl Toolkit in a simple, complete package that includes:

Complete Linux (Debian) distribution
VI Perl Toolkit runtime and other components described in “What’s In the VI Perl Toolkit,” including Utility Applications; additional sample scripts; and documentation.

This section provides basic information about about using the Virtual Appliance, to help get you started. Topics include:

Getting Around the VI Perl Toolkit Virtual Appliance with VMware Player
Logging into the VI Perl Toolkit Virtual Appliance
Accessing the VI Perl Toolkit Virtual Appliance Management Page
Copying Scripts to and from the Virtual Appliance

Getting Around the VI Perl Toolkit Virtual Appliance with VMware Player

Each time you start the VMware Player, you’ll see a browse dialog for selecting an appliance:

Select VMware-VI-Perl-Toolkit-Appliance.vmx.

Click Open to launch the virtual machine. The VMware Player splash screen displays, and soon you’ll see the VI Perl Toolkit Virtual Appliance console screen:

VI Perl Toolkit running in VMware Player—Click here to display larger image

Upon bootup, the VI Perl Toolkit Virtual Appliance console displays an information page (as shown in the screenshot above) that includes:

All network settings.
URLs for remotely administering the VI Perl Toolkit Virtual Appliance.
Information about how to re-configure the network settings, if necessary.

Assuming that the network is configured, the appliance also displays a login prompt. Login to the VI Perl Toolkit Virtual Appliance as you would any Linux host system, and navigate to the apps directory. Or, connect to the appliance management page from the network using a web browser.

Logging Into the VI Perl Toolkit Virtual Appliance

Once the appliance starts up and the console displays, simply login as you would in any Linux host. The default VI Perl Toolkit Virtual Appliance user accounts include root, network, and visdk.

In a production environment, you should change the default password for the visdk user. If you did not change the default password after initially installing the VI Perl Toolkit Virtual Appliance, you should do so now:

Log in using the visdk user account with the default password, visdk:
<hostname> login: _

The Linux shell displays visdk@<hostname>:~$
At the Linux shell prompt, enter the passwd command to change the password: passwd initiates a series of prompts that guides you through the process, as shown here:

passwd
Changing password for visdk
(current) UNIX password:
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully
visdk@<hostname>:~$
Navigate to the apps sub-directory to get started running the Utility Applications:
/usr/lib/vmware-viperl/apps<

Accessing the VI Perl Toolkit Virtual Appliance Management Page

The VI Perl Toolkit Virtual Appliance includes a web server management interface that lets you re-configure network settings for the appliance and setup automatic update capability. In addition, the web management page provides access to a simple CGI script built using the VI Perl Toolkit.

To open the CGI page:

Launch your browser.
Navigate to the VI Perl Toolkit Virtual Appliance management page using the secure (SSL-based authentication, https, rather than http).

https://<hostname>:8080

As with other VMware products, the SSL certificates installed in the VI Perl Toolkit Virtual Appliance built-in website are self-signed (by VMware), raising a few warning messages (about SSL certificate authority) in the browser. You can disregard these warnings and click OK to accept the certificate and proceed to the appliance’s built-in website, logging in as visdk when prompted for user name and password.

In a few seconds, the Virtual Appliance Configuration and Management page for the VI Perl Toolkit displays.

From this page, you can display and re-configure network settings (Network) for the Virtual Appliance, check for updates to the Virtual Appliance (Update), or view the online Help link. (The Help link displays a generic text-based help page for any VMware Virtual Appliance.)

Copying Scripts to and from the Virtual Appliance

The VI Perl Toolkit Virutal Appliance includes an SSH server running by default, so you can use file transfer utilities, such as scp (Linux) or WinSCP (Windows) to transfer exterrnal files to the Virtual Appliance. For example, you may want to copy Perl scripts from another environment to the Virtual Appliance.

Assuming the Virtual Appliance is running in VMware Player on Windows, you can use WinSCP (or other client application) to connect to the SSH server in the appliance:

Connect as root@ip-address-of-the-appliance (or as visdk@ip-address-of-the-appliance). The default password for visdk is visdk. The password for root is the password you created during installation. (Note that the IP address of the Virtual Appliance to which you must connect is displayed on the console, at bootup.)

4. Running the VI Perl Toolkit Utility Applications

Running any of the Utility Applications requires no knowledge of Perl or the VI API: Simply install the VI Perl Toolkit and you’re ready to go. Most of the VI Perl Toolkit Utility Applications are command-line tools that you execute from the Windows command prompt, or from the UNIX shell. The Utility Applications have been structured to use the VILib::Opts parameter-processing library, which includes built-in options to simplify passing many of the command-line options. The basic format is:

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.

Table 1: Built-in Parameters and Variables

Parameter	Variable	Description
config	VI_CONFIG	Specify non-default name or location for the VI Perl Toolkit configuration file. Default name and location for Linux is ~/.visdkrc and for Windows is %HOME%\visdk.rc.
help	~	Displays usage information about a script or application to standard output (command console).
password	VI_PASSWORD	Password for the specified username. Sucessful authentication with username and password returns a session object that can be saved and used for subsequent connections using the same or different script. See sessionfile.
portnumber	VI_PORTNUMBER	Port used for server connection.
protocol	VI_PROTOCOL	Protocol used to connect to server. Default is HTTPS. If the server has been configured for HTTP, set to HTTP.
server	VI_SERVER	ESX Server or VirtualCenter Management Server host to which you want the application or script to connect. Default is localhost if none specified.
servicepath	VI_SERVICEPATH	Service path for server connection. Default is /sdk/webService.
sessionfile	VI_SESSIONFILE	Name of file containing the token saved from successful login. Alternative to specifying username and password. Sessions time out after 30 minutes of inactivity.
url	VI_URL	Complete URL for SDK connection. An alternative to specifying protocol, server, and servicepath as individual connection parameters. For example, perl app_name.pl --url https://*myserver.mycompany.com/sdk --username root* --password mypassword
username	VI_USERNAME	User account that has privileges to connect to the server.
verbose	VI_VERBOSE	Increase loglevel. Use in conjunction with Util::trace subroutine to display additional debugging information. By default, value of --verbose (loglevel) is 0.
version	~	Displays script version information, if available.

To learn more about using a specific Utility Application, including available options:

See the online reference for the Utility Applications; or,
Run the script at the Windows command-line or Linux shell prompt with the --help flag, as in:
perl app_name.pl --help
The console will display a list of available parameters, required parameters, defaults (if any), and information about how to use them.

Note: Beyond the built-in parameters shown in Table 1, the VILib::Opts library also enables developers to define new parameters for use in their own custom scripts. See the VI Perl Toolkit Programming Guide and the VI Perl Toolkit Subroutine Reference for details.

In addition to the ready-to-run Utility Applications, the VI Perl Toolkit also provides subroutine (function) libraries that enable you to create your own custom scripts and applications targeting the VI API.

See the VI Perl Toolkit Programming Guide for information about writing your own scripts.

VI Perl Toolkit 1.0 | Released 30-Aug-2007 | Last updated 10-October-2007 4:30 pm