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
Targeting vCenter Server and Using vCenter Single Sign-On	If you are working in an environment that is managed by vCenter Single Sign-On, you can specify the vCenter Single Sign-On server and a user name, password, and target host.	Using a Session File
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.

Authenticating Through vCenter Server and vCenter Single Sign-On

For all ESXi hosts that are managed by a vCenter Server system that is integrated with vCenter Single Sign-On 6.0 and later, you can authenticate directly to the vCenter Server system, or you can authorize to vCenter Server through vCenter Single Sign-On.

Best practice is to authenticate through vCenter Single Sign-On. The vCenter Single Sign-On service is included in the Platform Services Controller. The Platform Services Controller can be embedded in your vCenter Server installation, or one Platform Services Controller can handle authentication, certificate management, and some other tasks for multiple vCenter Server systems.

Note You cannot use this approach if vCenter Server is integrated with vCenter Single Sign-On 5.0.

You use the --psc option and, optionally, the --server option.

■	psc - Specifies the Platform Services Controller instance associated with the vCenter Server system that manages the host.

■	server - Specifies the vCenter Server system that manages the host. Required if the Platform Services Controller instance is associated with more than one vCenter Server system.

■	vihost - Specifies the ESXi host, as in earlier versions of vCLI.

Example

vminfo.pl --server <vc_HOSTNAME_OR_IP> --psc <psc_HOSTNAME_OR_IP> --vihost <esxi_HOSTNAME_OR_IP>--username root --password vmware --vihost <esxi_host>

If the specified user is known to vCenter Single Sign-On, a session is created. You can save the session with the --savesessionfile argument, and later use that session with the --sessionfile argument.

Using a session file results in less overhead and better performance than connecting to the Platform Services Controller repeatedly.

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 <esxi_host>

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 SDK for Perl Commands. 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

The following table 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 SDK for Perl Commands

Option and Environment Variable	Description
--cacertsfile <certsfile> -t <certs_file> VI_CACERTFILE=<cert_file_path>	ESXCLI commands only. Used to specify the CA (Certificate Authority) certificate file, in PEM format, to verify the identity of the vCenter Server system or ESXi system to run the command on. In vCLI 6.0 and later, you can only run ESXCLI commands if a trust relationship exists between the host you are running the command on and the system you are targeting with the --server option (ESXi host or vCenter Server system). You can establish the trust relationship by specifying the CA certificate file or by passing in the thumbprint for each target server (ESXi host or vCenter Server system).
- -config <cfg_file_full_path> VI_CONFIG=<cfg_file_full_path>	Uses the configuration file at the specified location. Specify a path that is readable from the current directory.
- -credstore <credstore> VI_CREDSTORE=<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 vCLI. The vSphere SDK for Perl Programming Guide explains how to manage the credential store.
- -encoding <encoding> VI_ENCODING=<encoding>	Specifies the encoding to be used. Several encodings are supported. ■ utf8 ■ cp936 (Simplified Chinese) ■ shftjis (Japanese) ■ iso-885901 (German). You can use - -encoding to specify the encoding vCLI should map to when it is run on a foreign language system.
- -passthroughauth VI_PASSTHROUGHAUTH	If you specify this option, the system uses the Microsoft Windows Security Support Provider Interface (SSPI) for authentication. Trusted users 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 connecting to a vCenter Server system.
- -passthroughauthpackage <package> VI_PASSTHROUGHAUTHPACKAGE= <package>	Use this option with - -passthroughauth to specify a domain-level authentication protocol to be used by Windows. By default, SSPI uses the Negotiate protocol, which means that client and server try to negotiate a protocol that both support. If the vCenter Server system to which you are connecting is configured to use a specific protocol, you can specify that protocol using this option. This option is supported only if you are running vCLI on a Windows system and connecting to a vCenter Server system.
- -password <passwd> VI_PASSWORD=<passwd>	Uses the specified password (used with - -username) to log in to the server. ■ If - -server specifies a vCenter Server system, the user name and password apply to that server. If you can log in to the vCenter Server system, you need no additional authentication to run commands on the ESXi hosts that server manages. ■ If - -server specifies an ESXi host, the user name and password apply to that server. 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, the system prompts you and does not echo your input to the screen.
- -portnumber <number> VI_PORTNUMBER=<number>	Uses the specified port to connect to the system specified by --server. Default is 443.
- -protocol <HTTP|HTTPS> VI_PROTOCOL=<HTTP|HTTPS>	Uses the specified protocol to connect to the system specified by --server. Default is HTTPS.
--psc <hostname_or_IP> VI_PSC=<hostname_or_IP>	Host name or IP address of the Platform Services Controller instance that is associated with the vCenter Server system that manages the host. In many cases, the Platform Services Controller is embedded in the vCenter Server system, but external Platform Services Controller instances are supported as well. For those cases, use the --server option to specify the vCenter Server system that manages the host. This option implies user authentication with vCenter Single Sign-On. The user you specify must be able to authenticate to vCenter Single Sign-On.
- -savesessionfile <file> VI_SAVESESSIONFILE=<file>	Saves a session to the specified file. The session expires if it has been unused for 30 minutes.
- -server <server> VI_SERVER=<server>	Uses the specified ESXi or vCenter Server system. Default is localhost. If - -server points to a vCenter Server system, you can also specify the --psc option to log in to the vCenter Server system with vCenter Single Sign-On. Use the - -vihost option to specify the ESXi host that you want to run the command against. See Authenticating Through vCenter Server and vCenter Single Sign-On.
- -servicepath <path> VI_SERVICEPATH=<path>	Uses the specified service path to connect to the ESXi host. Default is /sdk/webService.
- -sessionfile <file> VI_SESSIONFILE=<file>	Uses the specified session file to load a previously saved session. The session must be unexpired.
--thumbprint <thumbprint> VI_THUMBPRINT=<thumbprint>	Expected SHA-1 host certificate thumbprint if no CA certificates file is provided in the --cacertsfile argument. The thumbprint is returned by the server in the error message if you attempt to run a command without specifying a thumbprint or certificate file.
- -url <url> VI_URL=<url>	Connects to the specified vSphere Web Services SDK URL.
- -username <u_name> VI_USERNAME=<u_name>	Uses the specified user name. ■ If - -server specifies a vCenter Server system, the user name and password apply to that server. If you can log in to the vCenter Server system, you need no additional authentication to run commands on the ESXi hosts that server manages. ■ If - -server specifies an 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, the system prompts you and does not echo your input to the screen.
- -vihost <host> -h <host>	When you run a vCLI command with the - -server option pointing to a vCenter Server system, use - -vihost to specify the ESXi host to run the command against. Note: This option is not supported for each command. If supported, the option is included when you run <cmd> --help.