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.
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.
Password (- -password), session file (- -sessionfile), or configuration file (- -config) specified on the command line.
vSphere Web Services SDK Programming Guide and vSphere SDK for Perl Programming Guide.
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
For example:
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:
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.
<command> - -sessionfile <sessionfile_location> <command_options>
For example:
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>
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.
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_PASSWORD = my_password
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.
The following examples connect to the server as user snow-white with password dwarf$.
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
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.
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:
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.