VMware logo

VMware Infrastructure (VI) Perl Toolkit Appliance Guide


PRINT

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:

  1. Preface
  2. Preliminary Connectivity Check
  3. Installing the VI Perl Toolkit Virtual Appliance
  4. Using the the Perl Toolkit Virtual Appliance
  5. 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:

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:

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

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:

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.

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.

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 (requires VMware Store account log in and acceptance of license agreement):
    http://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:
  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:

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:

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>:~$

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

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

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/share/doc/vmware-viperl/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

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:

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

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

Opening the VMware Player lets you select an appliance—Click here to display larger image

  1. Select VMware-VI-Perl-Toolkit-Appliance.vmx.
  2. 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:

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:

  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>:~$

  3. 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:

  1. Launch your browser.
  2. 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.
    VI Perl Toolkit Virtual Appliance management page—Click to display larger image

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:

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:

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
ParameterVariableDescription
configVI_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).
passwordVI_PASSWORDPassword 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.
portnumberVI_PORTNUMBERPort used for server connection.
protocolVI_PROTOCOLProtocol used to connect to server. Default is HTTPS. If the server has been configured for HTTP, set to HTTP.
serverVI_SERVERESX Server or VirtualCenter Management Server host to which you want the application or script to connect. Default is localhost if none specified.
servicepathVI_SERVICEPATHService path for server connection. Default is /sdk/webService.
sessionfileVI_SESSIONFILEName of file containing the token saved from successful login. Alternative to specifying username and password. Sessions time out after 30 minutes of inactivity.
urlVI_URLComplete 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
usernameVI_USERNAMEUser account that has privileges to connect to the server.
verboseVI_VERBOSEIncrease 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