VMware logo

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 VMware
  • Packaged as a Virtual Appliance, available from VMware
  • Source code bundles for Windows or Linux, available from Sourceforge

This Installation Guide includes these topics:

Assuming that you have the VI Perl Toolkit installed, see the VI Perl Toolkit User’s Guide for information about running and writing scripts.

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

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 , you’ll 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 methods—it’s 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), you’ll 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:

  1. Launch a browser.
  2. Enter the fully-qualified domain name (or the IP address) for the ESX Server host or VirtualCenter Management Server:

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

    You’ll be notified that the “VMware VI SDK Browser requires a username and password,” with a prompt requring a user name and password.

  3. Enter the user account and password for the server system—typically, 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 MOB—assuming 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 won’t be prompted for user name and password, nor will you see any SSL-certificate-related warnings.

When you’ve 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:

Connect to a VirtualCenter Server MOB to obtain information about the MORef (ManagedObjectReference) for the ServiceInstance—Click to enlarge this image

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 don’t 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:

  1. Download the installation file from the VI Perl Toolkit Beta page:

  2. Launch the installer. A warning message about the installer’s digital signature may display. You can safely disregard the warning message.
  3. Click Yes to ignore the warning message and continue with the installation.

    NoteIf 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.
  4. 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
  5. Click Next to continue. The Ready to Install the VMware VI Perl Toolkit components dialog displays.
  6. 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.
  7. 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:

    Utility Applications: 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-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 immediately start running sample scripts or creating your own scripts once the VI Perl Toolkit Virtual Appliance installation is complete. Simply logon 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:

/usr/local/share/doc/viperltoolkit/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 ProductDownload Location
VMware Playerwww.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 (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 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:

  1. Obtain the VI Perl Toolkit Virtual Appliance from VMware’s download page:
    http://www.vmware.com/download/home.html
  2. 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.)
  3. 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.
  4. 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.

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:

See the VI Perl Toolkit User’s 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:

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

    <hostname> login: _
    The Linux shell displays visdk@<hostname>:~$
  2. 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>:~$

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.

  1. Launch your browser and navigate to the CPAN search page:
    http://search.cpan.org/

  2. Select Modules from the drop-down list.
  3. Enter the name of the module in the search text box. Spell and punctuate precisely, including colons when appropriate, as shown here:

    Module, library:
    Crypt-SSLeay (0.51)
    Data-Dumper (2.102)
    MethodMaker (2.0.8)
    XML-LibXML (1.58)
    libwww-perl (5.805)
    Search for:
    Crypt::SSLeay
    Data::Dumper
    Class::MethodMaker
    XML::LibXML
    LWP
    CPAN Search page
  4. 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.
  5. 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.
  6. Click the Download link to initiate the download. The browser’s 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.
  7. 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.
  8. Open a Linux shell session and navigate to the directory containing the downloaded packages.
    cd /tmp
  9. Unzip the package, if necessary. For example:
    gunzip Class-MethodMaker-2.08.tar.gz
  10. Extract the files from the package. For example:
    tar xf Class-MethodMaker-2.08.tar
  11. Navigate to the sub-directory containing the extracted files. For example:
    cd Class-MethodMaker-2.08
  12. 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).
    less README
  13. Read the INSTALL file for information about how to install the module.
    less INSTALL
  14. Follow the instructions in the module’s 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 sudoNot authorized to use sudo
    ./configure
    make
    make test
    sudo make install
    ./configure
    make
    make test
    su root
    make install

Using CPAN Module to Install Linux

An alternative way to install any missing modules is to use the CPAN module that’s 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:

cpan>

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.

  1. Launch a browser and navigate to the VI Perl Toolkit download:
    http://sourceforge.net/projects/viperltoolkit/
  2. 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:
    viperltoolkit-beta1
  3. 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:
    viperltoolkit-beta1.tgz
  4. Click the file name to begin the download process. A dialog box displays, enabling you to save the file to disk.
  5. Navigate to the /tmp (or /temp, for Windows) sub-directory to save the file.
  6. Click Save to save the file.
  7. Open a Linux shell session.
  8. Change to the directory in which you downloaded the package.
    cd /tmp
  9. Unzip the package, if necessary (some systems may de-compress during download).
    gunzip filename.tar.gz
  10. Extract the files from the package.
    tar xf filename.tar
  11. Change to the directory containing the extracted files.
    cd viperltoolkit
  12. Review the README file for information about licensing, additional requirements, and late-breaking information.
    less README

Running the Installation Script

Assuming that the Linux host meets all requirements, you can run the Makefile.PL for the Toolkit.

cd /tmp/viperltoolkit
perl Makefile.PL

If any of the Perl pre-requisites are missing, you’ll 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.

  1. Build the Toolkit files.
    make
  2. Verify that the build succeeded by running the test.
    make test
  3. Install the Toolkit files.
    make install

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 Garsthagen’s excellent HOW-TO, available on his Run-Virtual website) have been tested on a Windows XP system.

  1. Obtain and install ActivePerl 5.8, available from:
    http://www.activestate.com/store/freedownload.aspx?prdGuid=81fbce82-6bd5-49bc-a915-08d58c2648ca

    You will need to register at ActivePerl’s 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:\).
  2. Launch the Perl Package Manager (PPM) by running the batch file (ppm.bat) at the command prompt:
    c:\Perl\bin>ppm
  3. From the PPM Edit menu, select Preferences... and add the path to the University of Winnipeg’s PPM (Perl library) as a repository from which to obtain modules and packages:

    http://theoryx5.uwinnipeg.ca/ppms/

  4. Select these modules and packages:
    • XML-LibXML-Common
    • XML-LibXML
    • Crypt-SSLeay
    • Data-Dumper
    • Class-MethodMaker

    Perl Package Manager (PPM) Screenshot—Click to display larger image

    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 it’s fairly simple.
  5. Obtain Microsoft’s nmake from:
    http://support.microsoft.com/kb/132084
    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.
  6. Scroll through the page that opens to find the link for nmake15.exe on the page.
  7. Click the nmake15.exe link. A save dialog displays.
  8. 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:
      • nmake.exe
      • nmake.err
      • readme.txt
  9. Launch a Windows console session (cmd.exe).
  10. Navigate to the location of the VI Perl Toolkit download and run these commands:

    C:\viperltoolkit>perl Makefile.pl

    The console displays progress:
    Writing Makefile for VIPerlToolkit
  11. Enter nmake at the command prompt:
    C:\viperltoolkit>nmake

  12. Enter nmake install at the command prompt:
    C:\viperltoolkit>nmake install

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

  1. Navigate to the /samples sub-directory:
    /usr/local/share/doc/viperltoolkit/samples

  2. 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

Copyright © 2007 VMware, Inc. All rights reserved.

Last updated 2-Aug-2007 2:45 pm