vSphere SDK for Perl Common Options

A number of options are available for any vSphere SDK for Perl script. Most of these options allow you to specify the host or hosts to connect to. Most options require an option value.

perl <app_name>.pl --<option_name> <option_value>

For example, to power on a virtual machine using the vmcontrol.pl utility application, you must specify the name of the virtual machine to power on, as follows:

perl vmcontrol.pl --server <myserver> --username <admin> --password <mypassword> --operation poweron --vmname <virtual_machine_name>

Run any application or sample without any options or with --help to see its parameters and execution examples. Information about common and script-specific options is included.

Important If the host you are targeting is in lockdown mode, you cannot execute Perl scripts against the host.

Specifying Options

You can specify the common options in several ways, discussed in this section.

When you run a vSphere CLI command, authentication happens in the following order of precedence:

vSphere CLI Authentication Precedence 

Authentication	Description	See
Command line	Password (--password), session file (--sessionfile), or configuration file (--config) specified on the command line.	Using a Session File
Configuration file	Passwords specified in a .visdkrc configuration file.	Using a Configuration File
Environment variable	Password specified in an environment variable.	Setting Environment Variables
Credential store	Password retrieved from the credential store.	Credential Store Perl Library
Current account (Active Directory)	Current account information used to establish an SSPI connection. Windows only.	.Using Microsoft Windows Security Support Provider Interface (SSPI)
Prompt the user for a password.

This order of precedence always applies. That means, for example, that you cannot override an environment variable setting in a configuration file.

Using a Session File

The save_session.pl script in the apps/session directory illustrates how to create a session file. You can modify the script and include it in your own application, or create a session file using the script on the command line, and then pass in that session file when running vSphere SDK for Perl commands. See Saving Sessions.

The session file does not reveal password information. If a session file is not used for 30 minutes, the session expires.

To create and use a session file

1	Connect to the directory where the script is located, for example, on Windows:

cd C:\Program Files\VMware\VMware vSphere CLI\Perl\apps\session

2	Run save_session.pl. You must supply connection parameters and the name of a session file in which the script can save an authentication cookie.

perl save_session.pl --savesessionfile <location> --server <server>

For example:

perl save_session.pl --savesessionfile C:\Temp\my_session --server my_server

If you specify a server but no user name or password, the script prompts you.

3	You can now run scripts in the \apps or \samples directory or your own scripts and pass in the session file using the --sessionfile parameter as follows:

<command> --sessionfile <sessionfile_location> <command_options>

For example:

perl hostinfo.pl --sessionfile C:\Temp\my_session

Note If you use a session file, any other connection parameters are ignored.

You can use the code in the \apps\session\save_session.pl utility application inside your own vSphere SDK for Perl application. If a call to the server throws an exception, your application should terminate the session to avoid session leaks. You could do this with an error handler that runs disconnect() or logout(), for example:

eval {

# ... insert program here ...

};

if (@$) {

print "Fatal error: $@";

Util::disconnect();

exit(1);

}

You can also use the _END_ pseudo-signal handler to perform a disconnect, as follows:

$SIG{__END__} = sub { Util::disconnect(); }

Passing Parameters at the Command Line

Pass parameters at the command line using option name and option value pairs (some options have no value).

--<optionname> <optionvalue>

The following example connects to the server as user snow-white with password dwarf$. The first example (Linux) uses an escape character before each special character, the other examples use single quotes (Linux) and double quotes (Windows).

Linux

vminfo.pl --server <server> --username snow\-white --password dwarf\$ --vmname <name>

vminfo.pl --server <server> --username ‘snow-white’ --password ‘dwarf$’ --vmname <name>

Windows

vminfo.pl --server <server> --username “snow-white” --password “dwarf$” --vmname <name>

Setting Environment Variables

You can set environment variables in a Linux profile, in the Environment properties dialog box of the Microsoft Windows System control panel, or, for the current session, at the command line. Environment variables are listed when you run a command with --help.

The following example shows the contents of a /root/.visdkrc file that uses environment variables:

VI_SERVER = <server>

VI_USERNAME = <usr>

VI_PASSWORD = <root_password>

VI_PROTOCOL = https

VI_PORTNUMBER = 443

Do not escape special characters in the file that specifies environment variables.

If you have set up your system to run this file, you can run scripts on the specified server afterwards.

Using a Configuration File

A configuration file is a text file that contains variable names and settings. Variables corresponding to the connection options are shown in Options Available for all vSphere SDK for Perl Scripts. Use --config if the configuration information is saved in a different file than ./visdkrc. If you specify --config, the system ignores the ./visdkrc settings.

Caution Limit read access to a configuration file, especially if it contains user credentials.

You can use the --config option to run a script with the configuration file, for example:

connect.pl --config <my_saved_config> --list

Using a configuration file is useful for repeatedly entering connection details. If you have multiple vCenter Server or ESX/ESXi systems and you administer each system individually, you can create multiple configuration files with different names. When you want to run a command or a set of commands on a server, you pass in the --config option with the appropriate filename at the command line.

Using Microsoft Windows Security Support Provider Interface (SSPI)

You can use the --passthroughauth command-line argument to log in to a vCenter Server system (vCenter Server version 2.5 Update 2 or later). Using --passthroughauth passes the credentials of the executing user to the server. If the executing user is known by both the machine from which you access the vCenter Server system and the machine running the vCenter Server system, no additional authentication is required.

Note Using SSPI is supported only when you run commands from Windows, and use a vCenter Server system as the target server.

If SDK commands and the vCenter Server system run on the same machine, a local account for the executing user works. If they run on different machines, then the executing user must have an account in a domain trusted by both machines.

SSPI supports a number of protocols. By default, it selects the Negotiate protocol, which indicates that client and server attempt to find a mutually supported protocol. Alternatively, you can use --passthroughauthpackage to specify another protocol supported by SSPI. Kerberos, the Windows standard for domain-level authentication, is commonly chosen.

If the vCenter Server system is configured to accept only a specific protocol, specifying the protocol to vSphere SDK for Perl commands with --passthroughauthpackage might be required for successful authentication to the server. If you use --passthroughauth, you do not have to specify authentication information in any other way. For example, to run connect.pl on the server, you can use the following command at the command line.

<command> <login_params> --passthroughauth

See the Microsoft Web site for a detailed discussion of SSPI.

The following example connects to a server that has been set up to use SSPI. When you run the command, the system calls vminfo.pl with the --vmname option. The system does not prompt for a user name and password because the current user is known to the server.

vminfo.pl --server <vc_server> --passthroughauth --passthroughauthpackage “Kerberos”

--vihost my_esx --vmname <name>

Common Options Reference

Options Available for all vSphere SDK for Perl Scripts lists options that are available for all vSphere SDK for Perl scripts. Use the parameter on the command line and the variable or the parameter in configuration files.

Options Available for all vSphere SDK for Perl Scripts 

Parameter and Environment Variable	Description
--config <config_file> VI_CONFIG=<config_file>	Uses the vSphere SDK for Perl configuration file at the specified location. Important: You must specify a path that is readable from the current directory.
--credstore <credstore> VI_CREDSTORE	Name of a credential store file. Defaults to <HOME>/.vmware/credstore/vicredentials.xml on Linux and <APPDATA>/VMware/credstore/vicredentials.xml on Windows. Commands for setting up the credential store are included in the vSphere SDK for Perl, which is installed with the vSphere CLI. The vSphere SDK for Perl Programming Guide explains how to use the credential store.
--encoding <encoding> VI_ENCODING=<encoding>	Specifies the encoding to be used. One of cp936 (Simplified Chinese), ISO-8859-1 (German), or Shift_JIS (Japanese). You can use --encoding to specify the encoding vSphere SDK for Perl should map to when it is run on a foreign language system.
--help	Prints a brief usage message. The message lists first each command-specific option and then the common options.
--passthroughauth VI_PASSTHROUGHAUTH	When the vSphere SDK for Perl runs, the system uses the Microsoft Windows Security Support Provider Interface (SSPI) for authentication. You are not prompted for a user name and password. See the Microsoft Web site for a detailed discussion of SSPI. This option is supported only if you are running vSphere SDK for Perl on a Windows system and connecting to a vCenter Server system.
--passthroughauthpackage <package> VI_PASSTHROUGHAUTHPACKAGE= <package>	When used in conjunction with --passthroughauth, specifies a domain-level authentication protocol to be used by Windows. By default, SSPI uses the Negotiate protocol, which means that client and server attempt to negotiate a mutually supported protocol. If the vCenter Server system to which you are connecting is configured to use a specific protocol, you can specify that protocol using this parameter. This option is supported only if you are running vSphere SDK for Perl on a Windows system and connecting to a vCenter Server system.
--password <passwd> VI_PASSWORD=<passwd>	Password (used in conjunction with --username) for log in to the server. ■ If --server specifies a vCenter Server system, the user name and password apply to that server. No passwords are then needed to run on the ESX/ESXi hosts that server manages. ■ If --server specifies an ESX/ESXi system, the user name and password apply to that system. Note: Use the empty string (' ' on Linux and “ “ on Windows) to indicate no password. If you do not specify a user name and password on the command line, and authentication is not set up by other means, you are prompted.
--portnumber <number> VI_PORTNUMBER=<number>	Port to connect to the ESX/ESXi host. Default is 443.
--protocol <HTTP|HTTPS> VI_PROTOCOL=<HTTP|HTTPS>	Protocol to connect to the ESX/ESXi host. Default is HTTPS.
--savesessionfile <file> VI_SAVESESSIONFILE=<file>	Saves a session to the specified file. The session expires if it has been unused for thirty minutes.
--server <server> VI_SERVER=<server>	vSphere server to use. Default is localhost.
--servicepath <path> VI_SERVICEPATH=<path>	Service path to use to connect to the ESX/ESXi host. Default is /sdk/webService.
--sessionfile <file> VI_SESSIONFILE=<file>	Session file to use to load a previously saved session. The session must be unexpired.
--url <url> VI_URL=<url>	vSphere Web Services SDK URL to connect to.
--username <u_name> VI_USERNAME=<u_name>	User name to use to log in. ■ If --server specifies a vCenter Server system, the user name and password apply to that server. No passwords are then needed to run on the ESX/ESXi hosts that server manages. ■ If --server specifies an ESX/ESXi system, the user name and password apply to that system. If you do not specify a user name and password on the command line, you are prompted.
--verbose	Displays additional debugging information.
--version	Displays version information.