VMware Infrastructure (VI) Perl Toolkit Installation Guide
PRINT INSTALLATION GUIDE
Released 7-August-2007 [Beta 2]
The VMware Infrastructure (VI) Perl Toolkit provides an easy-to-use Perl scripting interface to VMware Infrastructure (VI) APIs. 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 APIs 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 APIs.
For developers who have previously worked with the Scripting APIs (specifically, the VmPerl APIs), the VI Perl Toolkit is the tool-of-choice.
The VI Perl Toolkit is available in several formats:
- Windows installation wizard, available from
- Packaged as a Virtual Appliance, available from
- Source code bundles for Windows or Linux, available from
This Installation Guide includes these topics:
Validating the Installation
Assuming that you have the VI Perl Toolkit installed, see the VI Perl Toolkit Users Guide
for information about running and writing scripts.
Contacting VMware: VMware welcomes your suggestions for improving technical publications. You can email your feedback to
Preliminary Connnectivity Check
Before installing the VI Perl Toolkit , you should confirm the connection from your intended development workstation to the target server system: If issues arise after you install the VI Perl Toolkit , youll have one less factor to troubleshoot.
The quickest way to check connectivity is to launch a browser (on the host system you intend to use for VI Perl Toolkit scripting) and navigate to the Managed Object Browser (MOB), the web-based server application hosted on all ESX Server and VirtualCenter Server systems. The MOB lets you explore the objects on the system and obtain information about available properties and methodsits a great tool for learning about the VI API and object model in the context of live virtual machines running on host systems. Unless the ESX Server or VirtualCenter Management Server web server has been configured to support HTTP (rather than HTTPS), youll need a user name and password to log into the MOB (step 3, below).
To access the MOB on any ESX Server or VirtualCenter Management Server system:
- Launch a browser.
- Enter the fully-qualified domain name (or the IP address) for the ESX Server host or VirtualCenter Management Server:
Youll be notified that the VMware VI SDK Browser requires a username and password, with a prompt requring a user name and password.
- Enter the user account and password for the server systemtypically, root/password for the ESX Server system, and Administrator/password for VirtualCenter Management Server system. Or, obtain the user account and password information from your VMware system administrator.
After entering user account and password, you will see some preliminary warning messages regarding the authority of the SSL certificate, such as Website Certified by an Unknown Authority (assuming that the default server certificate provided by VMware has not been replaced. Also, note that the specific message text varies by web browser.) You can safely disregard such warnings and continue to logon to the MOBassuming that VMware is the certificate authority.
Note: If the ESX Server or VirtualCenter Management Server system has been configured to support regular HTTP (non-SSL) connections, you wont be prompted for user name and password, nor will you see any SSL-certificate-related warnings.
When youve 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 this example:
Assuming that you can connect to the MOB from your host system, you can now install the VI Perl Toolkit and successfully run scripts using this same server name, user account, and password.
Using the VI Perl Toolkit Windows Installer
The Windows installer includes the ActiveState Perl runtime and all required Perl modules and libraries. If you already have Perl installed on the target Windows system, you may be prompted to remove it. If you dont want to remove an existing Perl engine, consider installing the VI Perl Toolkit Virtual Appliance instead, or installing the VI Perl Toolkit manually.
To install the VI Perl Toolkit using the Windows installer:
- Download the installation file from the
VI Perl Toolkit Beta
- Launch the installer. A warning message about the installers digital signature may display. You can safely disregard the warning message.
- Click Yes to ignore the warning message and continue with the installation.
Note: If you already have Perl installed on your Windows system, the installer will remove it and install ActivePerl. If you do not want to overwrite an existing Perl installation with the version of ActiveState included with VI Perl Toolkit Windows installer, cancel the installation process.
The Welcome to the installation wizard for VMware VI Perl Toolkit displays.
- Click Next to continue. The Destination Folder dialog displays. You can click Change... to open a browse dialog and navigate to and select a different sub-directory for the installation rather than the default. The default location is:
cd \Program Files\VMware\VMware VI Perl Toolkit\Perl
- Click Next to continue. The Ready to Install the VMware VI Perl Toolkit components dialog displays.
- Click Install to proceed with the installation. The process takes several minutes to complete. When it does, you can test the installation by running one of the sample scripts.
- Navigate to the location of the VI Perl Toolkit Utility Applications (or to the samples sub-directory) to begin using any of the provided scripts. The Utility Applications are supported by VMware; any other samples included with the VI Perl Toolkit are not supported by VMware, but can be used as starting points for your own scripts.
Assuming you accepted the defaults during installation, the paths to the Utility Applications and samples sub-directories are as follows:
||C:\Program Files\VMware\VMware VI Perl Toolkit\Perl\apps|
|Sample Scripts:||C:\Program Files\VMware\VMware VI Perl Toolkit\Perl\samples
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-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 immediately start running sample scripts or creating your own scripts once the VI Perl Toolkit Virtual Appliance installation is complete. Simply
as visdk, navigate to the apps directory, and start using any of the provided management applications. The Utility Applications are located in this directory of the Virtual Appliance:
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 VMwares website at:
If necessary, download and install one of the products listed in the table (assuming you want to use the VI Perl Toolkit Virtual Appliance).
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.
Installing the Virtual Appliance
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:
Obtain the VI Perl Toolkit Virtual Appliance from VMwares download page:
- 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:
(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, youll be prompted to perform a few minor setup tasks associated with deploying the appliance, including:
Creating a password for root. (Remember this passwordyou 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 Appliances management page.)
- If your host system uses a proxy server to access the internet, enter the server address and port number at the prompt.
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:
See the VI Perl Toolkit Users Guide for details.
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:
Changing password for visdk
(current) UNIX password:
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully
Building and Installing the VI Perl Toolkit Manually
The VI Perl Toolkit can be installed on any platform that supports Perl. However, these installation instructions have been validated on Linux and Windows XP only.
Requirements for Manual Installations
- Perl 5.8
- Several supporting Perl modules:
- Crypt-SSLeay (0.51) [Crypt::SSLeay]
- Data-Dumper (2.102) [Data::Dumper]
- MethodMaker (2.0.8) [Class::MethodMaker]
- XML-LibXML (1.60) [XML::LibXML]
- libwww-perl (5.805) [LWP]
- VI Perl Toolkit package
Obtaining the pre-requisites and installing them is part of the platform-specific installation instructions that follow.
Installing the VI Perl Toolkit on Linux
Many Linux distributions include Perl and some or all of the required modules by default. However, if your Linux host is not already configured with the requirements, you must install them before you can install and use the VI Perl Toolkit .
Obtaining and Installing Pre-requisites
The instructions below guide you through the process of obtaining the modules from CPAN and building them on the host system, but you can also use the Perl Package Manager (PPM) to streamline the process.
- Launch your browser and navigate to the CPAN search page:
- Select Modules from the drop-down list.
- Enter the name of the module in the search text box. Spell and punctuate precisely, including colons when appropriate, as shown here:
- Click the CPAN Search button to initiate the search. Shortly, a results page displays listing one or more links to the module or library. Various versions and sub-packages may be included.
- Click the most appropriate link to display the download page for the module. The download page includes information about the module or library, links to source code, and a link to the downloadable archive file in the upper-right-hand corner of the page.
- Click the Download link to initiate the download. The browsers File Download dialog displays, enabling you to save the file to disk. Click the Save button and navigate to the sub-directory in which you want to save the download.
- Navigate to the /tmp directory and save the download.
After downloading any missing Perl libraries from the CPAN website, you can unpack and install them.
- Open a Linux shell session and navigate to the directory containing the downloaded packages.
- Unzip the package, if necessary. For example:
- Extract the files from the package. For example:
tar xf Class-MethodMaker-2.08.tar
- Navigate to the sub-directory containing the extracted files. For example:
- Review the README file. It contains (among other things) the name and description of the library, the minimum version of Perl required, and a list of required packages (if any).
- Read the INSTALL file for information about how to install the module.
- Follow the instructions in the modules INSTALL file. Note that you must typically perform the final step (make install) as the root user. Depending on your privileges (whether you can use sudo or not), follow one of these two approaches:
|Authorized to use sudo||Not authorized to use sudo|
sudo make install
Using CPAN Module to Install Linux
An alternative way to install any missing modules is to use the CPAN module thats part of the Perl distribution. To launch the CPAN shell:
perl -MCPAN -e shell
You will be prompted to provide some basic information, including the source from which to obtain the modules, where to build them, and so on. You can obtain the necessary Perl libraries from
CPAN (Comprehensive Perl Archive Network)
or another reliable source, and for most of the other prompts, simply accept the defaults. Shortly, the cpan> prompt displays:
To find the module:
cpan> i /pat/
where pat is a pattern, such as part of the name of the missing module.
Obtaining the VI Perl Toolkit Sourcecode
The VI Perl Toolkit source-code package comprises a single platform-independent compressed file, available from Sourceforge.
- Launch a browser and navigate to the VI Perl Toolkit download:
- Click the Download VMware Infrastructure (VI) Perl Toolkit button. The About VMware Infrastructure Toolkit page displays, listing packages available for download with information about release dates, file size, and dates. Find the VI Perl Toolkit Beta package from among those listed:
- Click the Download button to display a list of files available for download. Since the VI Perl Toolkit comprises a single platform-independent install, only one file is available:
- Click the file name to begin the download process. A dialog box displays, enabling you to save the file to disk.
- Navigate to the /tmp (or /temp, for Windows) sub-directory to save the file.
- Click Save to save the file.
- Open a Linux shell session.
- Change to the directory in which you downloaded the package.
- Unzip the package, if necessary (some systems may de-compress during download).
- Extract the files from the package.
tar xf filename.tar
- Change to the directory containing the extracted files.
- Review the README file for information about licensing, additional requirements, and late-breaking information.
Running the Installation Script
Assuming that the Linux host meets all requirements, you can run the Makefile.PL for the Toolkit.
If any of the Perl pre-requisites are missing, youll see warning messages, such as Warning: prerequisite Data::Dumper 2.121 not found. We have 2.12. Return to Obtaining and Installing Pre-requisites and finish installing all pre-requisites before proceeding.
- Build the Toolkit files.
- Verify that the build succeeded by running the test.
- Install the Toolkit files.
Installing the VI Perl Toolkit on Windows
To install the VI Perl Toolkit on Windows, you must obtain a Windows implementation of Perl and various libraries; install the VI Perl Toolkit ; and perform a few other basic setup tasks. From start to finish, the entire process takes about 15 minutes (or less, if you already have Perl installed).
These instructions (adapted from
Richard Garsthagens excellent HOW-TO, available on his Run-Virtual website) have been tested on a Windows XP system.
- Obtain and install ActivePerl 5.8, available from:
You will need to register at ActivePerls website to download the software.
Download ActivePerl Microsoft installer (.msi).
- Double-click on the filename to launch the wizard-driven installation process that also sets the required paths. During the installation process, just accept the defaults, including the default directory (C:\).
- Launch the Perl Package Manager (PPM) by running the batch file (ppm.bat) at the command prompt:
- From the PPM Edit menu, select Preferences... and add the path to the University of Winnipegs PPM (Perl library) as a repository from which to obtain modules and packages:
- Select these modules and packages:
As the required packages are installed, you may be prompted to install various other supporting packages. Accept any additional installations. The process may take a few minutes to complete, but its fairly simple.
- Obtain Microsofts nmake from:
The page that displays at the URL above is a support page that includes a link to nmake15.exe, which is a self-extracting compressed file that unpacks nmake.exe, nmake.err, and a readme.txt file.
- Scroll through the page that opens to find the link for nmake15.exe on the page.
- Click the nmake15.exe link. A save dialog displays.
- Select Save to Disk and click OK. A navigation dialog box displays.
- Navigate to the %SystemRoot% folder (typically, c:\WINDOWS) of your Windows host system) and click Save to download the nmake15.exe file to Windows system directory. When the download completes, open Windows Explorer and navigate to %SystemRoot% and find the nmake15.exe.
- Double-click the file to unpack its contents:
- Launch a Windows console session (cmd.exe).
- Navigate to the location of the VI Perl Toolkit download and run these commands:
The console displays progress:
Writing Makefile for VIPerlToolkit
- Enter nmake at the command prompt:
- Enter nmake install at the command prompt:
The console reports status as the VI Perl Toolkit components (VIRuntime.html, VIStub.html, VIRuntime.pm, and so on) are installed, and in a few seconds, the process completes.
Validating the VI Perl Toolkit Installation
After installing the VI Perl Toolkit Virtual Appliance (or installing manually on Linux or Windows), you can confirm successful installation by running any one of the Utility Applications, or by running one of the sample scripts.
Running a Sample Script
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:
- Navigate to the /samples sub-directory:
- 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:
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