Specifying Authentication Information

vCLI allows you to run against multiple target servers from the same administration server. You must have the correct privileges to perform the actions on each target.

Important vCLI 4.1 and later allows administrators to place ESXi hosts in lockdown mode for enhanced security. Only a vCLI command or a vSphere Client connected to a vCenter Server system can make changes to ESXi hosts in lockdown mode. No users, not even the root user, can run vCLI commands against ESXi hosts in lockdown mode. See vCLI and Lockdown Mode and the Datacenter Administration Guide.

Order of Precedence for vCLI Authentication

When you run a vCLI command, authentication happens in the order of precedence shown in vCLI Authentication Precedence. This order of precedence always applies. That means, for example, that you cannot override an environment variable setting in a configuration file.

vCLI 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
Environment variable	Password specified in an environment variable.	Using Environment Variables
Configuration file	Password specified in a configuration file.	Using a Configuration File
Current account (Active Directory)	Current account information used to establish an SSPI connection. Available only on Windows.	Using Microsoft Windows Security Support Provider Interface
Credential store	Password retrieved from the credential store.	vSphere Web Services SDK Programming Guide and vSphere SDK for Perl Programming Guide.
Prompt the user for a password.	Password is not echoed to screen.

Using a Session File

You can create a session file with the save_session script. The script is in the /apps/session directory of the vSphere SDK for Perl, which is included in the vCLI package. You can use the session file, which does not reveal password information, when you run vCLI commands. If the session file is not used for 30 minutes, it expires.

If you use a session file, other connection options are ignored.

To create and use a session file

1	Connect to the directory where the script is located.

For example:

Windows:	cd C:\Program Files\VMware\VMware vSphere CLI\Perl\apps\session
Linux:	cd /usr/share/lib/vmware-vcli/apps/session

2	Run save_session.

You can use the save_session.pl script or the --savesessionfile option to the vCLI command. You must specify the server to connect to and the name of a session file in which the script saves an authentication cookie.

save_session - -savesessionfile <location> - -server <server>

For example:

Windows:	save_session.pl - -savesessionfile C:\Temp\my_session - -server my_server - -username <username> - -password <password>
Linux:	save_session - -savesessionfile /tmp/vimsession - -server <servername_or_address> - -username <username> - -password <password>

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

3	When you run vCLI commands, pass in the session file using the - -sessionfile option.

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

For example:

Windows:	esxcli - -sessionfile C:\Temp\my_session network ip interface list vicfg-mpath.pl --sessionfile C:\Temp\my_session - -list
Linux:	esxcli - -sessionfile /tmp/vimsession network ip interface list vicfg-mpath - -sessionfile /tmp/vimsession - -list

Using Environment Variables

On Linux, you can set environment variables in a Linux bash profile or on the command line by using a command like the following:

export VI_SERVER=<your_server_name_or_address>

On Windows, you can set environment variables in the Environment properties dialog box of the System control panel. For the current session, you can set environment variables at the command line by using a command like the following:

set VI_SERVER=<your_server_name_or_address>

Important Do not use escape characters in environment variables.

See Using vCLI Commands in Scripts for an environment variable example.

Using a Configuration File

You can use a text file that contains variable names and settings as a configuration file. Variables corresponding to the options are shown in vCLI Connection Options.

Caution Limit read access to a configuration file that contains user credentials.

Pass in the configuration file when you run vCLI commands, as follows:

<command> - -config <my_saved_config> <option>

For example:

esxcli --config <my_saved_config> network ip interface list

vicfg-mpath - -config <my_saved_config> - -list

If you have multiple vCenter Server or ESXi systems and you administer each system individually, you can create multiple configuration files with different names. 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.

The following example illustrates the contents of a configuration file:

VI_SERVER = XX.XXX.XXX.XX

VI_USERNAME = root

VI_PASSWORD = my_password

VI_PROTOCOL = https

VI_PORTNUMBER = 443

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

Using Command-Line Options

You can pass in command-line options using option name and option value pairs in most cases. For ESXCLI commands, you can use long or short options. An equal sign between option name and option value is optional.

esxcli - -server <vc_server> - -username <privileged_user> - -password <pw> - -vihost <esx_host> <namespace> [<namespace]...> <command> - -<option_name=option_value>

For other vCLI commands, use long or short options. An equal sign is not supported.

<vicfg- command> - -server <vc_server> - -username <privileged_user> - -password <pw> - -vihost <esx_host> - -<option_name option_value>

Some options, such as - -help, have no value.

Important Enclose passwords and other text with special characters in quotation marks. When running commands on Windows, use double quotes (“ “). When running commands on Linux, use single quotes (‘ ‘) or a backslash (\) as an escape character.

The following examples connect to the server as user snow-white with password dwarf$.

Linux

esxcli - -server <server> - -username snow\-white - -password dwarf\$ network ip interface list

esxcli - -server <server> - -username snow\-white - -password ‘dwarf$’ network ip interface list

vicfg-mpath - -server <server> - -username snow\-white - -password dwarf\$ --list

vicfg-mpath - -server <server> - -username ‘snow-white’ - -password ‘dwarf$’ --list

Windows

esxcli --server <server> - -username “snow-white” - -password “dwarf$” network ip interface list

vicfg-mpath.pl - -server <server> - -username “snow-white” - -password “dwarf$” --list

Using Microsoft Windows Security Support Provider Interface

The - -passthroughauth option, which is available if you run vCLI commands from a Microsoft Windows system, allows you to use the Microsoft Windows Security Support Provider Interface (SSPI). See the Microsoft Web site for a detailed discussion of SSPI.

You can use - -passthroughauth to establish a connection with a vCenter Server system (vCenter Server system or VirtualCenter Server 3.5 Update 2 or later). After the connection has been established, authentication for the vCenter Server system or any ESXi system it manages is no longer required. Using - -passthroughauth passes the credentials of the user who runs the command to the target vCenter Server system. No additional authentication is required if the user who runs the command is known by the computer from which you access the vCenter Server system and by the computer running the vCenter Server software.

If vCLI commands and the vCenter Server software run on the same computer, the user needs only a local account to run the command. If the vCLI command and the vCenter Server software run on different machines, the user who runs the command must have an account in a domain trusted by both machines.

SSPI supports several protocols. By default, it selects the Negotiate protocol, where client and server try to find a protocol that both support. You can use - -passthroughauthpackage to explicitly specify a protocol that is supported by SSPI. Kerberos, the Windows standard for domain-level authentication, is used frequently. If the vCenter Server system is configured to accept only a specific protocol, specifying the protocol with - -passthroughauthpackage might be required for successful authentication. If you use - -passthroughauth, you do not have to specify authentication information by using other options.

Example

esxcli - -server <vc_server> - -passthroughauth - -passthroughauthpackage “Kerberos”

- -vihost my_esx network ip interface list

 

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

- -vihost my_esx - -list

Connects to a server that is set up to use SSPI. When a trusted user runs the command, the system calls the ESXCLI command or vicfg-mpath with the - -list option. The system does not prompt for a user name and password.

vCLI and Lockdown Mode

Lockdown mode disables all direct root access to ESXi machines. To make changes to ESXi systems in lockdown mode you must go through a vCenter Server system that manages the ESXi system. You can use the vSphere Client or vCLI commands that support the --vihost option. The following commands cannot run against vCenter Server systems and are therefore not available in lockdown mode:

■	vicfg-snmp

■

vifs

■	vicfg-user

■	vicfg-cfgbackup

■	vihostupdate

■	vmkfstools

■	vicfg-ipsec

If you have problems running a command on an ESXi host directly (without specifying a vCenter Server target), check whether lockdown mode is enabled on that host. See the vSphere Security documentation.