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:
This Appliance Guide includes these topics:
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 firstname.lastname@example.org
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:
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:
VMware provides numerous support and educational resources. See the support page at:
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 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
Here are some links to various resources, including developer forums, user groups, and product pages.
|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|
VMware welcomes your suggestions for improving technical publications. You can email your feedback to:
The VI Perl Toolkit Virtual Appliance comprises a complete Linux distribution (Debian 3.1) with everything you need, pre-installedPerl 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:
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:
The next several sections describe the VI Perl Toolkit Virtual Appliance installation process in more detail.
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 VMwares website at:
|VMware Host Product||Download Location|
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 Playerits 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.
These instructions assume that your host system already has one of the required VMware hosted productsVMware Server, VMware Workstation, or VMware Player installed and running.
To install the VI Perl Toolkit Virtual Appliance:
At the end of the process, youll see the VI Perl Toolkit running as a virtual machine in VMware Server, Workstation, or VMware Player. At this point, you can:
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:
After installing the VI Perl Toolkit Virtual Appliance, you can confirm successful installation by running any one of the Utility Applications.
To navigate to the samples sub-directory
In the samples sub-directory, youll find several other sub-directories, including:
The datacenterlisting.pl (in the \samples\discovery folder), is a good place to start. Its 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:
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
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:
This section provides basic information about about using the Virtual Appliance, to help get you started. Topics include:
Each time you start the VMware Player, youll see a browse dialog for selecting an appliance:
Upon bootup, the VI Perl Toolkit Virtual Appliance console displays an information page (as shown in the screenshot above) that includes:
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.
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:
Changing password for visdk
(current) UNIX password:
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully
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:
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.)
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:
Running any of the Utility Applications requires no knowledge of Perl or the VI API: Simply install the VI Perl Toolkit and youre 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:
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
|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:
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.
Copyright © 2007 VMware, Inc. All rights reserved.
VI Perl Toolkit 1.0 | Released 30-Aug-2007 | Last updated 10-October-2007 4:30 pm