Getting Started with vSphere Command-Line Interfaces

Getting Started with vSphere
Command-Line Interfaces
ESXi 6.5
vCenter Server 6.5
This document supports the version of each product listed and
supports all subsequent versions until the document is
replaced by a new edition. To check for more recent editions of
this document, see http://www.vmware.com/support/pubs.
EN-002351-00
Getting Started with vSphere Command-Line Interfaces
You can find the most up-to-date technical documentation on the VMware Web site at:
http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@vmware.com
Copyright © 2007–2017 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2
VMware, Inc.
Contents
About This Book 5
1 Managing vSphere with Command-Line Interfaces 7
Overview of vSphere Command-Line Interfaces 7
Using ESXCLI for Host Management 10
ESXCLI Syntax 10
Running ESXCLI Commands Installed as Part of vCLI 11
ESXCLI Command Support When Host and vCLI Versions Do Not Match 11
Using PowerCLI to Manage Hosts and Virtual Machines 12
Using DCLI to Manage vCenter Services 12
DCLI Syntax 13
vCLI Package Contents 13
2 Installing vCLI 15
Installation Overview 15
Overview of Linux Installation Process 16
Installing the vCLI Package on Red Hat Enterprise Linux 18
Installing Required Prerequisite Software for Red Hat Enterprise Linux 19
Installing the vCLI Package on RHEL with No Internet Access 19
Installing vCLI on Linux Systems with Internet Access 20
Installing Prerequisite Software for Linux Systems with Internet Access 20
Install the vCLI Package on a Linux System with Internet Access 22
Uninstall the vCLI Package on Linux 23
Installing and Uninstalling vCLI on Windows 23
Install the vCLI Package on Windows 23
Uninstall the vCLI Package on Windows 24
Enabling Certificate Verification 24
Deploying vMA 25
3 Running Host Management Commands in the ESXi Shell 27
ESXi Shell Access with the Direct Console 27
Enabling Local ESXi Shell Access 28
ESXi Shell Timeout 28
Use the Local ESXi Shell 29
Remote ESXi Shell Access with SSH 29
Enable SSH Access in the Direct Console 29
Enable SSH from the vSphere Web Client 29
Access the Remote ESXi Shell with SSH 30
Lockdown Mode 30
Run an ESXCLI Command in the ESXi Shell 30
VMware, Inc.
3
Getting Started with vSphere Command-Line Interfaces
4 Running vCLI Host Management Commands 33
Overview of Running vCLI Host Management Commands 34
Targeting the Host Directly 34
Targeting a Host That is Managed by a vCenter Server System 34
Protecting Passwords 34
Order of Precedence for vCLI Host Management Commands 35
Authenticating Through vCenter Server and vCenter Single Sign-On 36
Authenticating Directly to the Host 36
Create and Use a Session File 36
Using Environment Variables 37
Using a Configuration File 38
Using Command-Line Options 38
Using the Microsoft Windows Security Support Provider Interface 39
vCLI and Lockdown Mode 40
Trust Relationship Requirement for ESXCLI Commands 40
Download and Install the vCenter Server Certificate 40
Using the --cacertsfile Option 41
Using the --thumbprint Option 41
Use the Credential Store 41
Common Options for vCLI Host Management Command Execution 42
Using vCLI Commands in Scripts 44
Run Host Management Commands from a Windows System 45
Run Host Management Commands from a Linux System 45
5 Running DCLI Commands 47
Overview of Running DCLI Commands 47
DCLI Syntax 48
DCLI Options 48
Using DCLI Commands 50
Displaying Help Information for DCLI Commands 50
Running DCLI Commands Included in the vCLI Package 50
Running DCLI Commands on the vCenter Server Appliance 51
Using DCLI with a Credential Store File 51
Order of Precedence for DCLI Authentication 51
Input, Output, and Return Codes 52
Using DCLI with Variables 52
Using DCLI Interactive Mode 52
DCLI SSL Connection 53
DCLI History File 53
Index 55
4
VMware, Inc.
About This Book
Getting Started with vSphere Command-Line Interfaces gives an overview of command-line interfaces in
®
vSphere and gets you started with ESXi Shell commands and vCLI (VMware vSphere Command-Line
Interface) commands. This book also includes instructions for installing vCLI and a reference to connection
parameters.
Intended Audience
This book is for experienced Windows or Linux system administrators who are familiar with vSphere
administration tasks and data center operations.
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions
of terms as they are used in VMware technical documentation, go to
http://www.vmware.com/support/pubs.
Related Documentation
The documentation for vCLI is available in the vSphere Documentation Center and on the vCLI
documentation page. Go to http://www.vmware.com/support/developer/vcli.
n
vSphere Command-Line Interface Concepts and Examples presents usage examples for many host
management commands, and explains how to set up software and hardware iSCSI, add virtual
switches, place hosts in maintenance mode, and so on. The document includes the same example with
the ESXCLI command and with the vicfg- command.
n
vSphere Command-Line Interface Reference is a reference to both ESXCLI commands and vicfgcommands. The vicfg- command help is generated from the POD available for each command, run
pod2html for any vicfg- command to generate individual HTML files interactively. The ESXCLI
reference information is generated from the ESXCLI help.
n
DCLI Reference is a reference to DCLI commands for managing vCenter services.
The documentation for PowerCLI is available in the vSphere Documentation Center and on the PowerCLI
documentation page.
The vSphere SDK for Perl documentation explains how you can use the vSphere SDK for Perl and related
utility applications to manage your vSphere environment.
The vSphere Management Assistant Guide explains how to install and use the vSphere Management Assistant
(vMA). vMA is a virtual machine that includes vCLI and other prepackaged software. See “Deploying
vMA,” on page 25.
VMware, Inc.
5
Getting Started with vSphere Command-Line Interfaces
Background information for the tasks discussed in this book is available in the vSphere documentation set.
The vSphere documentation consists of the combined VMware vCenter Server and ESXi documentation.
6
VMware, Inc.
Managing vSphere with CommandLine Interfaces
1
vSphere supports several command-line interfaces for managing your virtual infrastructure including a set
of ESXi Shell commands, PowerCLI commands, and DCLI (Datacenter CLI) commands for management of
vCenter services. You can run commands locally, from an administration server, or from scripts.
You can choose the CLI best suited for your needs, and write scripts to automate your management tasks.
This chapter includes the following topics:
n
“Overview of vSphere Command-Line Interfaces,” on page 7
n
“Using ESXCLI for Host Management,” on page 10
n
“Using PowerCLI to Manage Hosts and Virtual Machines,” on page 12
n
“Using DCLI to Manage vCenter Services,” on page 12
n
“vCLI Package Contents,” on page 13
Overview of vSphere Command-Line Interfaces
vSphere includes commands for managing different aspects of your environment.
The following CLIs are available for managing hosts, either directly or through the vCenter Server system
that manages the host. You can also manage vCenter services by using DCLI.
VMware, Inc.
7
Getting Started with vSphere Command-Line Interfaces
Figure 1‑1. vSphere CLIs for Host and vCenter Services Management
Linux
vSphere
Management
Assistant
Windows
vCLI
vicfg-*
ESXCLI
DCLI
Others (esxtop, vimcmd, vsish, rvc...)
PowerCLI
API
vCenter Server
DCLI
API
API
ESXi
ESXi
ESXCLI
esxcfg-*
ESXCLI
esxcfg-*
The following command sets are available. For more information about each command set, see the
referenced documentation.
8
VMware, Inc.
Chapter 1 Managing vSphere with Command-Line Interfaces
Command Set
Description
See
ESXCLI
commands
Manage many aspects of an ESXi host. You can run ESXCLI commands
remotely or in the ESXi Shell.
n vCLI package - Install the vCLI package on the server of your choice,
or deploy a vSphere Management Assistant (vMA) virtual machine
and target the ESXi system that you want to manipulate. You can run
ESXCLI commands against a vCenter Server system and target the
host indirectly. Running against vCenter Server systems by using the
-vihost parameter is required if the host is in lockdown mode.
n ESXi Shell - Run ESXCLI commands in the local ESXi Shell to manage
that host.
You can also run ESXCLI commands from the VMware PowerCLI prompt
by using the Get-EsxCli cmdlet.
“Using ESXCLI for Host
Management,” on
page 10
Chapter 2, “Installing
vCLI,” on page 15
vSphere Command-Line
Concepts and Examples
vSphere Management
Assistant Guide
vSphere Command-Line
Interface Reference
vicfg- and
other vCLI
commands
Users can manage hosts remotely. Install the vCLI package on a Windows
or Linux system or deploy a vMA virtual machine, and target the ESXi
system that you want to manipulate.
Chapter 2, “Installing
vCLI,” on page 15
vSphere Command-Line
Concepts and Examples
vSphere Command-Line
Interface Reference
vicfg- commands are included in this release but are deprecated.
Migrate to ESXCLI where possible.
You can run the commands against ESXi systems or against a
vCenter Server system. If you target a vCenter Server system, use the -vihost option to specify the target ESXi system.
Note If the ESXi system is in strict lockdown mode, you must run
commands against the vCenter Server system that manages your ESXi
system.
esxcfgcommands
Available in the ESXi Shell. esxcfg- commands are included in this
release but are deprecated. Migrate to ESXCLI where possible.
Command-Line
Management of vSphere 5
and vSphere 6 for Service
Console Users
DCLI commands
Manage VMware SDDC services.
DCLI is a CLI client to the vSphere Automation SDK interface for
managing VMware SDDC services. A DCLI command talks to a
vSphere Automation API endpoint to locate relevant information, and
then runs the command and displays the result to the user.
You can run DCLI commands as follows.
n vCenter Server Appliance - Run DCLI commands from the
vCenter Server Appliance shell. See “Running DCLI Commands on
the vCenter Server Appliance,” on page 51.
n vCenter Server Windows command prompt - Install vCenter Server
on a supported Windows system and run DCLI commands from the
command prompt.
n vCLI package
n Open a command prompt on a Linux or Windows system on
which you installed vCLI. Enter commands into that command
prompt, specifying connection options. See Chapter 5, “Running
DCLI Commands,” on page 47.
n Access the vMA Linux console. DCLI does not support the vifastpass connections.
n Prepare scripts that include DCLI commands and run the scripts as
vCLI scripts from the vCenter Server Windows command prompt or
from the vCenter Server Appliance shell.
Chapter 5, “Running
DCLI Commands,” on
page 47
See the vSphere
Automation SDK
documentation for
information about
supported services and
how they interact.
VMware
PowerCLI
cmdlets
VMware PowerCLI provides a Windows PowerShell interface to the
vSphere API. PowerCLI includes PowerShell cmdlets for administering
vSphere components.
PowerCLI includes more than 500 cmdlets, a set of sample scripts, and a
function library for management and automation. The vSphere Image
Builder PowerCLI and vSphere Auto Deploy PowerCLI modules are
included when you install PowerCLI.
VMware PowerCLI
documentation
VMware, Inc.
9
Getting Started with vSphere Command-Line Interfaces
Command Set
Description
localcli
commands
Set of commands for use with VMware Technical Support. localcli
commands are equivalent to ESXCLI commands, but bypass the host
daemon (hostd) . The localcli commands are only for situations when
hostd is unavailable and cannot be restarted. After you run a localcli
command, you must restart hostd. Run ESXCLI commands after the
restart.
See
If you use a localcli command, an inconsistent system state and
potential failure might result.
pktcap-uw
utility
Enables you to monitor the traffic that flows through the physical
network adapters, the VMkernel adapters, and the virtual machine
adapters, and to analyze the packet information by using conventional
network analysis tools such as Wireshark.
vSphere Networking
documentation
dir-cli
vecs-cli
certool
Commands for managing the vCenter Single Sign-On and certificate
infrastructure.
vSphere Security
documentation
appliancesh
Enables you to configure and troubleshoot the vCenter Server Appliance
and to monitor the processes and services running in the appliance.
vCenter Server Appliance
Configuration
documentation
Using ESXCLI for Host Management
You can manage many aspects of an ESXi host by using commands from the ESXCLI command set. You can
run ESXCLI commands as vCLI commands, or run them in the ESXi Shell in troubleshooting situations.
You can also run ESXCLI commands from the PowerCLI shell by using the Get-EsxCli cmdlet. See the
PowerCLI User's Guide and the PowerCLI Cmdlet Reference.
The set of ESXCLI commands that are available on a host depends on the host configuration. The vSphere
Command-Line Interface Reference lists help information for all ESXCLI commands. You can run esxcli -server <MyESXi> --help before you run a command on a host to make sure that the command is defined on
the host that you are targeting.
ESXCLI Syntax
Each ESXCLI command uses the same syntax.
The following is the standard syntax structure of an ESXCLI command.
esxcli [dispatcher options] <namespace> [<namespace> ...] <cmd> [cmd options]
Syntax
Element
dispatcher
options
Description
Predefined options for connection information such as target host, user name, and so on. See Chapter 4,
“Running vCLI Host Management Commands,” on page 33. Not required when you run the
command in the ESXi Shell. If the target server is a vCenter Server system, specify the target ESXi host
before any ESXCLI namespaces, commands, and supported options.
Many ESXCLI commands generate output that you might want to use in your application. You can run
esxcli with the --formatter dispatcher option and send the resulting output as input to a parser.
Important Starting with vSphere 6.0, ESXCLI expects a trust relationship between the target host and
the system on which you run the command. You can establish this relationship in one of these ways:
n
n
Use the --cacertsfile option or VI_CACERTFILE variable.
Store the thumbprint in the session file.
Specify the thumbprint with the --thumbprint option or VI_THUMBPRINT variable.
You can pass in the thumbprint that is returned in the error if you trust the host that you are targeting.
See “Trust Relationship Requirement for ESXCLI Commands,” on page 40 for an example.
n
namespace
10
Groups ESXCLI commands. vSphere 5.0 and later support nested namespaces.
VMware, Inc.
Chapter 1 Managing vSphere with Command-Line Interfaces
Syntax
Element
command
Description
Reports on or modifies the state of the system.
The following examples show how you can use this element.
esxcli --server myESXi --username user1 --password 'my_password' storage nfs list
esxcli --server myVCServer --username user1 --password 'my_pwd' --vihost
myESXi.mycompany.com storage nfs list
options
Many commands support one or more of the options displayed in the help or the vCLI reference. For
some commands, multiple option values, separated by spaces, are possible.
The following example shows how you can use this element.
esxcli system module parameters set -m <module> -p "a=1 b=1 c=1"
Running ESXCLI Commands Installed as Part of vCLI
You can run an ESXCLI command, installed as part of vCLI, in the ESXi Shell for troubleshooting purposes
and remotely against a specific host or against a vCenter Server system.
When running an ESXCLI command, installed as part of vCLI, you have the following options.
n
Deploy the vMA appliance, which includes vCLI and ESXCLI, on an ESXi system and authenticate
against a set of target servers. You can then run ESXCLI commands against any target server by
specifying the --host dispatcher option. No additional authentication is required. See the vSphere
Management Assistant Guide.
n
Install the vCLI package on one of the supported Windows or Linux systems. The ESXCLI command set
is included. Specify connection options to run commands against an ESXi host directly, or target a
vCenter Server system and specify the ESXi host to run the command against. See Chapter 2, “Installing
vCLI,” on page 15.
Note Starting with vSphere 6.0, a trust relationship must exist between the host from which you run
ESXCLI commands and the target ESXi host or vCenter Server system. See “Trust Relationship
Requirement for ESXCLI Commands,” on page 40.
See Chapter 4, “Running vCLI Host Management Commands,” on page 33.
ESXCLI Command Support When Host and vCLI Versions Do Not Match
When you run an ESXCLI vCLI command, you must know the commands that are supported on the target
host specified with --server or as a vMA target.
The following examples demonstrate command support when versions do not match.
n
If you run commands against ESXi 4.x hosts, ESXCLI 4.x commands are supported.
n
If you run commands against ESXi 5.0 hosts, ESXCLI 5.0 commands are supported. ESXCLI 5.1
commands that were included in ESXCLI 5.0 are also supported.
n
If you run commands against ESXi 5.1 hosts, ESXCLI 5.1 and ESXCLI 5.0 commands are supported.
VMware partners might develop custom ESXCLI commands that you can run on hosts where the partner
VIB is installed.
Run esxcli --server <target> --help for a list of namespaces supported on the target. You can explore the
namespaces for additional help.
VMware, Inc.
11
Getting Started with vSphere Command-Line Interfaces
Using PowerCLI to Manage Hosts and Virtual Machines
VMware PowerCLI contains snap-ins and modules based on Microsoft PowerShell for automating vSphere
and vCloud Director administration. PowerCLI provides C# and PowerShell interfaces for vSphere and
other VMware product administration.
PowerCLI is based on Microsoft PowerShell and uses the PowerShell basic syntax and concepts. Microsoft
PowerShell is both a command-line and scripting environment, designed for Windows. It uses the .NET
object model and provides administrators with system administration and automation capabilities. To work
with PowerShell, you run commands, which are called cmdlets.
PowerShell supports features such as pipelines, wildcards, and easy access to command-line help.
You can use ESXCLI commands from the PowerCLI console, by using the following options.
n
Through the cmdlet that provides direct access to the ESXCLI namespaces, applications, and
commands.
n
Through .NET methods, which you use to create managed objects that correspond to specific ESXCLI
applications. To access the ESXCLI, you can call methods on these managed objects.
See the PowerCLI User’s Guide in the vSphere documentation center.
Using DCLI to Manage vCenter Services
With the DCLI command set, you can run virtual machine management, appliance management, content
library, and tagging commands.
You cannot manage services that are part of vSphere 5.5 or earlier from DCLI. DCLI is not a host
management CLI.
DCLI is a CLI client of the vSphere Automation SDK. The following workflow explains how DCLI works.
1
You run a DCLI command.
2
If you are not authenticated, DCLI prompts for a user name and password.
3
The command connects you to the vCenter Single Sign-On service and checks whether the user account
specified on the command-line or in a credential store file can authenticate.
4
If you can authenticate, DCLI communicates with the vCenter Server and runs the vSphere Automation
API that corresponds to the DCLI command. Different vCenter Server systems support different
services.
Note If the authenticated user account does not have permissions to run the DCLI command, you
receive an Unauthorized error message, even if the user credentials are correct.
5
DCLI displays the result or an error message.
You can run DCLI commands as follows.
12
n
vCLI package - Install the vCLI package on the server of your choice, or deploy a vMA virtual machine.
You can then run DCLI commands against an endpoint. See “Using DCLI Commands,” on page 50.
n
vCenter Server Appliance - Run DCLI commands from the vCenter Server Appliance shell. See
“Running DCLI Commands on the vCenter Server Appliance,” on page 51.
n
vCenter Server Windows command prompt - Install vCenter Server on a supported Windows system
and run DCLI commands from the command prompt.
VMware, Inc.
Chapter 1 Managing vSphere with Command-Line Interfaces
DCLI Syntax
Each DCLI command uses the same syntax.
The command name can be followed by DCLI connection and formatting options, each preceded by a plus
(+) sign. You also specify the namespace, the command, and the command options. Namespaces are nested.
Note The order in which DCLI options are provided on the command line is not important. However, you
must specify DCLI options with a plus (+) and command-specific options with a minus (-).
The syntax of a DCLI command is the following.
dcli +[DCLI options] <namespace> [<namespace> ...] <cmd> --[cmd option] [option value]
The following table describes the DCLI syntax elements.
Syntax Element
Description
DCLI options
Predefined options for connection information including the vSphere Automation SDK endpoint
and formatting options. Always preceded by a plus (+) sign.
Not required when you run the command in the vCenter Server Appliance shell or from the
command prompt of a vCenter Server Windows installation.
namespace
Groups DCLI commands. Namespaces correspond to the vSphere Automation SDK namespaces
and are nested.
command
Reports on or modifies the state of the system.
option and value
Command option and value pairs preceded by two minus signs (--).
Example
$dcli +server my_remote_vc +username user42 com vmware cis tagging tag list
vCLI Package Contents
vCLI is not a command set but a package of several command sets.
You usually install vCLI on an administration server and run scripts from there against other hosts or, for
DCLI, against vCenter Server systems. Some vCLI commands can also be run locally on the ESXi host or the
vCenter Server system.
When you install the vCLI package, the following command sets become available.
n
DCLI commands - These commands are available as part of vCLI, from the vCenter Server Appliance,
and from the command-prompt of a vCenter Server Windows installation.
n
Host Management commands - Includes the following command sets.
n
ESXCLI commands - The ESXCLI commands included in the vCLI package are equivalent to the
ESXCLI commands available in the ESXi Shell.
n
vicfg- commands - The vicfg- command set is similar to the deprecated esxcfg- command set in
the ESXi Shell. vicfg- commands are still included in this release but are deprecated. Migrate to
ESXCLI where possible.
n
Miscellaneous commands - A small set of commands for managing and monitoring ESXi hosts,
including vmkfstools and resxtop . In many cases, equivalent but slightly different commands are
available in the ESXi Shell.
Important ESXi Shell is intended for experienced users only. Minor errors in the shell can result in serious
problems. Instead of running commands directly in the ESXi Shell, use vCLI or PowerCLI.
VMware, Inc.
13
Getting Started with vSphere Command-Line Interfaces
You can run vCLI commands from a Windows or Linux system, or use vMA.
n
Install the vCLI command set on the Windows or Linux system from which you want to administer
your ESXi systems and run vCLI commands. See Chapter 2, “Installing vCLI,” on page 15.
n
Deploy a vMA virtual machine to an ESXi system and run vCLI commands from there.
After you have installed the vCLI package, you can run the host management commands in the set against
ESXi hosts. You can run the DCLI commands against a server by specifying the IP address or host name and
can manage the services associated with that server.
You must specify connection parameters when you run a vCLI command. The connection parameters differ
for DCLI commands and for other commands. See Chapter 4, “Running vCLI Host Management
Commands,” on page 33 and “Using DCLI Commands,” on page 50.
14
VMware, Inc.
Installing vCLI
2
You can install a vCLI package on a Linux or a Microsoft Windows system, or use vCLI as part of the
vSphere Management Assistant that can be deployed on an ESXi host.
This chapter includes the following topics:
n
“Installation Overview,” on page 15
n
“Overview of Linux Installation Process,” on page 16
n
“Installing the vCLI Package on Red Hat Enterprise Linux,” on page 18
n
“Installing vCLI on Linux Systems with Internet Access,” on page 20
n
“Uninstall the vCLI Package on Linux,” on page 23
n
“Installing and Uninstalling vCLI on Windows,” on page 23
n
“Enabling Certificate Verification,” on page 24
n
“Deploying vMA,” on page 25
Installation Overview
You can install a vCLI package on a supported platform or deploy the vMA virtual machine on an ESXi
host.
n
VMware, Inc.
Installable Package - Install a vCLI package on a physical or virtual machine. See “Installing the vCLI
Package on Red Hat Enterprise Linux,” on page 18, “Installing vCLI on Linux Systems with Internet
Access,” on page 20, and “Installing and Uninstalling vCLI on Windows,” on page 23.
15
Getting Started with vSphere Command-Line Interfaces
The vCLI installer installs both vSphere SDK for Perl and vCLI because many vCLI commands run on
top of the vSphere SDK for Perl. The content of the installer package differs for different platforms.
Platform
Installation Process
Windows
You must install required software. The installation package includes vCLI and vSphere SDK for
Perl.
Red Hat
Enterprise Linux
You must install required software. See “Installing Required Prerequisite Software for Red Hat
Enterprise Linux,” on page 19.
The installer for RHEL prompts you to choose whether you want to install additional modules
from the Internet or from the package.
n If you have Internet access, you can configure the installer to download Perl modules from
CPAN.
n The installer can instead install Perl modules that it does not find on your system from the
installer package.
SLES and
Ubuntu
You must install required software and you must have Internet access. See “Installing
Prerequisite Software for Linux Systems with Internet Access,” on page 20.
The installer downloads other Perl modules from CPAN.
After installation, you can run vCLI commands and vSphere SDK for Perl utility applications from the
operating system command line. Each time you run a command, you can specify the target server
connection options directly or indirectly. You can also write scripts and manage your vSphere
environment using those scripts.
n
vSphere Management Assistant (vMA) - Deploy vMA, a virtual machine that administrators can use to
run scripts that manage vSphere, on an ESXi host. vMA includes vCLI, vSphere SDK for Perl, and other
prepackaged software in a Linux environment.
vMA supports noninteractive login. If you establish an ESXi host as a target server, you can run vCLI
host management commands and vSphere SDK for Perl commands against that server without
additional authentication. If you establish a vCenter Server system as a target server, you can run most
vCLI commands against all ESXi systems that server manages without additional authentication. See
“Deploying vMA,” on page 25.
Overview of Linux Installation Process
The installation script for vCLI is supported on the Linux distributions that are listed in the Release Notes.
The vCLI package installer installs the vCLI scripts and the vSphere SDK for Perl. The installation proceeds
as follows.
1
The installer checks whether the following required prerequisite software are installed on the system.
Perl
Perl version 5.8.8 or version 5.10 must be installed on your system
OpenSSL
The vCLI requires SSL because most connections between the system on which you run the command
and the target vSphere system are encrypted with SSL.
The OpenSSL library (libssl-devel package) is not included in the default Linux distribution. See
“Installing Required Prerequisite Software for Red Hat Enterprise Linux,” on page 19 and “Installing
Prerequisite Software for Linux Systems with Internet Access,” on page 20.
LibXML2
Used for XML parsing. The vCLI client requires 2.6.26 or later. If you have an older version installed, you
must upgrade to 2.6.26 or later.
The libxml2 package is not included in the default Linux distribution. See “Installing Required
Prerequisite Software for Red Hat Enterprise Linux,” on page 19 and “Installing Prerequisite Software
for Linux Systems with Internet Access,” on page 20.
uuid
16
Included in uuid-devel for SLES 11 and in e2fsprogs-devel for other Linux platforms. Required by
the UUID Perl module.
VMware, Inc.
Chapter 2 Installing vCLI
2
If the required software is found, the installer proceeds. Otherwise, the installer stops and informs you
that you must install the software. See “Installing Required Prerequisite Software for Red Hat
Enterprise Linux,” on page 19 and “Installing Prerequisite Software for Linux Systems with Internet
Access,” on page 20 for instructions.
3
The installer checks whether the following Perl modules are found, and whether the correct version is
installed.
VMware, Inc.
n
Crypt-SSLeay-0.55 (0.55-0.9.7 or 0.55-0.9.8)
n
IO-Compress-Base-2.037
n
Compress-Zlib-2.037
n
IO-Compress-Zlib-2.037
n
Compress-Raw-Zlib-2.037
n
Archive-Zip-1.28
n
Data-Dumper-2.121
n
XML-LibXML-1.63
n
libwww-perl-5.805
n
LWP-Protocol-https-6.02
n
XML-LibXML-Common-0.13
n
XML-NamespaceSupport-1.09
n
XML-SAX-0.16
n
Data-Dump-1.15
n
URI-1.37
n
UUID-0.03
n
SOAP-Lite-0.710.08
n
HTML-Parser-3.60
n
version-0.78
n
Class-MethodMaker-2.10
n
JSON-PP-2.27203
n
Devel-StackTrace-131
n
Class-Data-Inheritable-0.08
n
Convert-ASN1-0.26
n
Cyrpt-OpenSSL-RSA-0.28
n
Crypt-X509-0.51
n
Exception-Class-1.37
n
MIME-Base64-3.14
n
UUID-Random-0.04
n
Socket6-023
n
IO-Socket-INET6-2.71
n
Net-INET6Glue-0.600_1
17
Getting Started with vSphere Command-Line Interfaces
Earlier versions of libwww-perl include the LWP-Protocol-https module. More recent versions of
libwww-perl do not include the LWP-Protocol-https module and you must install that module.
Note If you intend to run vCLI commands with SSL certification, verify that LWP::UserAgent 6.00 or
later is installed. The installer does not check this module, and earlier versions do not work with SSL.
4
The installer proceeds depending on the Linux distribution.
Linux
Distribution
5
Installer Behavior
RHEL (No
Internet access)
If no Internet access is available, and a module is not currently on your system, the installer
installs the module. If a different version of a module is found, the installer does not install it and
proceeds with the installation. At the end of the installation process, the installer informs you if
the version on the system does not match the recommended version, and recommends that you
install the version that vCLI was tested with. You can install the modules by using the package
installer for your platform, the installation CD, or CPAN.
Note The installer does not overwrite existing versions of recommended Perl modules. You
must update those modules manually.
All Linux
distributions
(Internet access)
The installer proceeds depending on whether the Perl modules are found.
n If a recommended Perl module is not found at all, the installer installs it using CPAN. You
must meet the installation prerequisites or the installer cannot install the Perl modules and
stops. See “Installing vCLI on Linux Systems with Internet Access,” on page 20.
n If an earlier version of a recommended module is found, the installer does not install a
different version from CPAN and proceeds with the installation. After completing the
installation, the installer displays a message that the version on the system does not match
the recommended version, and recommends that you install the version vCLI was tested
with. You can install the modules by using the package installer for your platform, the
installation CD, or CPAN.
n If a later version of a recommended module is found, the installer proceeds with the
installation and does not display a message after the installation.
Note The installer does not overwrite existing versions of recommended Perl modules. You
must update those modules manually.
After all required software and all prerequisite Perl modules are installed, you can install vCLI. See
“Installing Required Prerequisite Software for Red Hat Enterprise Linux,” on page 19 and “Installing
Prerequisite Software for Linux Systems with Internet Access,” on page 20.
If a previous version of vCLI, Remote CLI, or vSphere SDK for Perl is installed on your system, and you
install vCLI in a different directory, you must reset the PATH environment variable. You can reset the
variable, before or after the installation, by using the command appropriate for your distribution and shell,
for examplesetenv or export. If you do not reset the path, the system might still look for executable files in
the old location.
Installing the vCLI Package on Red Hat Enterprise Linux
vCLI is supported on Red Hat Enterprise Linux (RHEL) versions that are listed in the Release Notes. On
RHEL, the vSphere SDK for Perl installer prompts you to choose whether you want to install required Perl
modules from the installation package or from CPAN.
Follow these steps to install the software.
18
1
Install prerequisite software. See “Installing Required Prerequisite Software for Red Hat Enterprise
Linux,” on page 19.
2
When prompted, choose one of the following options.
n
Install additional prerequisite software from the installation package. See “Installing the vCLI
Package on RHEL with No Internet Access,” on page 19.
n
Install additional prerequisite software from CPAN. See “Install the vCLI Package on a Linux
System with Internet Access,” on page 22.
VMware, Inc.
Chapter 2 Installing vCLI
Installing Required Prerequisite Software for Red Hat Enterprise Linux
Prerequisite software on RHEL includes required software and recommended Perl modules.
Required Software
If required software is not installed, the vCLI installer stops. You can install the prerequisite software by
using yum, the RHEL package installer, or from the installation DVD, as follows.
Platform
Installation
RHEL 6.6 64-bit
yum install e2fsprogs-devel libuuid-devel
yum install glibc.i686
yum install perl-XML-LibXML
RHEL 7.1 64-bit
yum install e2fsprogs-devel libuuid-devel openssl-devel perl-devel
yum install glibc.i686 zlib.i686
yum install perl-XML-LibXML libncurses.so.5 perl-Crypt-SSLeay
Recommended Perl Modules
When the installer finishes, it might display a warning that the version of a module installed on your system
does not match the version with which vCLI was tested. Install the recommended version by using yum or
CPAN to resolve the issue. See “Overview of Linux Installation Process,” on page 16 for a complete list of
modules.
Note The installer does not overwrite existing Perl modules.
Installing the vCLI Package on RHEL with No Internet Access
Before you install vCLI, you must remove all previous versions of the software. The process differs from
simply uninstalling vCLI.
Remove Previous Versions of vCLI on RHEL
If you have earlier versions of vCLI installed on RHEL, you must remove those installations before installing
the latest version.
Procedure
1
Run the uninstall script, for example, if you installed vCLI in the default location, run the following
command.
/usr/bin/vmware-uninstall-vSphere-CLI.pl
2
Delete existing versions of vSphere-CLI.xxxx.tar.gz and delete the vmware-vsphere-cli-distrib
directory.
What to do next
Install vCLI on RHEL.
Install vCLI on RHEL with No Internet Access
You can install vCLI on a Red Hat Enterprise Linux system that has no previous vCLI versions installed.
Prerequisites
n
Remove previous vCLI installations.
n
Download the installation package.
VMware, Inc.
19
Getting Started with vSphere Command-Line Interfaces
Procedure
1
Untar the vCLI binary that you downloaded.
tar –zxvf VMware-vSphere-CLI-6.X.X-XXXXX.XXXX.x86_64.tar.gz
A vmware-vsphere-vcli-distrib directory is created.
2
Log in as superuser and run the installer.
/<location>/sudo vmware-vsphere-cli-distrib/vmware-install.pl
3
To accept the license terms, enter yes and press Enter.
4
To install Perl modules locally, enter yes and press Enter.
5
Specify an installation directory, or press Enter to accept the default, which is /usr/bin.
A complete installation process has the following result.
n
A success message appears.
n
The installer lists different version numbers for required modules, if any.
n
The prompt returns to the shell prompt.
If you accepted the defaults during installation, you can find the installed software in the following
locations.
n
vCLI scripts – /usr/bin
n
vSphere SDK for Perl utility applications – /usr/lib/vmware-vcli/apps
n
vSphere SDK for Perl sample scripts – /usr/share/doc/vmware-vcli/samples
What to do next
See the vSphere SDK for Perl documentation for a reference to all utility applications. After you install vCLI,
you can test the installation by running a vCLI command or vSphere SDK for Perl utility application from
the command prompt.
Installing vCLI on Linux Systems with Internet Access
Before you can install the vCLI package on a Linux system with Internet access, that system must meet
specific prerequisites.
n
Internet access - You must have Internet access when you run the installer because the installer uses
CPAN to install prerequisite Perl modules.
n
Development Tools and Libraries - You must install the Development Tools and Libraries for the Linux
platform that you are working with before you install vCLI and prerequisite Perl modules.
n
Proxy settings - If your system is using a proxy for Internet access, you must set the http:// and ftp://
proxies, as follows:
export http_proxy=<proxy_server>:port
export ftp_proxy=<proxy_server>:port
Installing Prerequisite Software for Linux Systems with Internet Access
If the prerequisite software is not installed, the installer stops and requests that you install it.
Installation of prerequisite software depends on the platform that you are using. See the Release Notes for the
supported versions of each Linux platform.
20
VMware, Inc.
Chapter 2 Installing vCLI
Platform
Installation
RHEL 6.6 64-bit
Find the required modules on the installation DVD, or use yum to install them.
yum install e2fsprogs-devel libuuid-devel
yum install glibc.i686
yum install perl-XML-LibXML
RHEL 7.1 64-bit
Find the required modules on the installation DVD, or use yum to install them.
yum install e2fsprogs-devel libuuid-devel openssl-devel perl-devel
yum install glibc.i686 zlib.i686
yum install perl-XML-LibXML libncurses.so.5 perl-Crypt-SSLeay
SUSE
Enterprise
Install the prerequisite packages from the SLES SDK DVD. When you insert the DVD, it offers to
autorun. Cancel the autorun and use the yast package installer to install OpenSSL or other missing
required packages.
n SLES 11 SP3 64-bit
n
yast -i openssl-devel libuuid-devel libuuid-devel-32bit
SLES 12 64-bit
yast -i openssl-devel libuuid-devel libuuid-devel-32bit e2fsprogs-devel
Some users might be authorized to use the Novell Customer Center and use yast to retrieve missing
packages from there.
Ubuntu 12.04
64-bit
1
2
Connect to the Internet.
Update the local repository of libraries from a terminal window.
3
sudo apt-get update
Install the required libraries from a terminal window.
sudo apt-get install ia32-libs build-essential gcc uuid uuid-dev perl libssldev perl-doc liburi-perl libxml-libxml-perl libcrypt-ssleay-perl
For Ubuntu 12.04 64-bit, the resxtop and ESXCLI commands do not work if you do not install the 32bit compatibility libraries.
Ubuntu 14.04
64-bit
1
2
Connect to the Internet.
Update the local repository of libraries from a terminal window.
3
sudo apt-get update
Install the required libraries from a terminal window.
sudo apt-get install lib32z1 lib32ncurses5 lib32bz2-1.0 gcc-multilib buildessential gcc uuid uuid-dev perl libssl-dev perl-doc liburi-perl libxml-libxmlperl libcrypt-ssleay-perl
For Ubuntu 14.04 64-bit, the resxtop and ESXCLI commands do not work if you do not install the 32bit compatibility libraries.
VMware, Inc.
21
Getting Started with vSphere Command-Line Interfaces
Platform
Installation
Ubuntu 15.10
64-bit
1
2
Connect to the Internet.
Update the local repository of libraries from a terminal window.
3
sudo apt-get update
Install the required libraries from a terminal window.
sudo apt-get install lib32z1 lib32ncurses5 build-essential uuid uuid-dev perl
libssl-dev perl-doc libxml-libxml-perl libcrypt-ssleay-perl libsoap-lite-perl
For Ubuntu 15.10 64-bit, the resxtop and ESXCLI commands do not work if you do not install the 32bit compatibility libraries.
Ubuntu 16.04
64-bit
1
2
Connect to the Internet.
Update the local repository of libraries from a terminal window.
3
sudo apt-get update
Install the required libraries from a terminal window.
sudo apt-get install lib32z1 lib32ncurses5 build-essential uuid uuid-dev
libssl-dev perl-doc libxml-libxml-perl libcrypt-ssleay-perl libsoap-lite-perl
libmodule-build-perl
For Ubuntu 16.04 64-bit, the resxtop and ESXCLI commands do not work if you do not install the 32bit compatibility libraries.
Install the vCLI Package on a Linux System with Internet Access
You can install the vCLI package and run a command to verify that installation was successful.
Prerequisites
Verify that you have installed the required prerequisite software.
Procedure
1
Download the vCLI Linux installer package.
You can find the installer in the Automation Tools and SDKs section of the Drivers & Tools tab of the
vSphere download page.
2
Log in as root.
3
Untar the vCLI binary that you downloaded.
Package
Command
64-bit
tar –zxvf VMware-vSphere-CLI-6.X.X-XXXXX.x86_64.tar.gz
32-bit
tar –zxvf VMware-vSphere-CLI-6.X.X-XXXXX.i386.tar.gz
A vmware-vsphere-vcli-distrib directory is created.
4
(Optional) If your server uses a proxy to access the Internet, and if your http:// and ftp:// proxy were not
set when you installed prerequisite software, set them now.
export http_proxy=<proxy_server>:port
export ftp_proxy=<proxy_server>:port
5
Run the installer.
sudo vmware-vsphere-cli-distrib/vmware-install.pl
6
To accept the license terms, enter yes and press Enter.
The installer connects to CPAN and installs prerequisite software. Establishing a connection might take
a long time.
22
VMware, Inc.
Chapter 2 Installing vCLI
7
On RHEL, when prompted to install precompiled Perl modules, enter no and press Enter to use CPAN.
The installer connects to CPAN and installs prerequisite software. Establishing a connection might take
a long time.
8
Specify an installation directory, or press Enter to accept the default, which is /usr/bin.
A complete installation process has the following result.
n
A success message appears.
n
The installer lists different version numbers for required modules, if any.
n
The prompt returns to the shell prompt.
If you accepted the defaults during installation, you can find the installed software in the following
locations.
n
vCLI scripts – /usr/bin
n
vSphere SDK for Perl utility applications – /usr/lib/vmware-vcli/apps
n
vSphere SDK for Perl sample scripts – /usr/share/doc/vmware-vcli/samples
What to do next
See the vSphere SDK for Perl documentation for a reference to all utility applications. After you install vCLI,
you can test the installation by running a vCLI command or vSphere SDK for Perl utility application from
the command prompt.
Uninstall the vCLI Package on Linux
You can use a script included in the installation to uninstall the vCLI package.
Procedure
1
Navigate to the directory where you installed vCLI.
The default directory is /usr/bin.
2
Run the vmware-uninstall-vSphere-CLI.pl script.
The command uninstalls vCLI and the vSphere SDK for Perl.
Installing and Uninstalling vCLI on Windows
Before you can run vCLI commands from your Windows system, you must install the vCLI package and test
the installation by running a command.
Install the vCLI Package on Windows
The vCLI installation package for Windows installs vSphere SDK for Perl and vSphere CLI, but does not
include the ActivePerl runtime from ActiveState Software.
The vCLI is supported on the Windows platforms that are listed in the Release Notes.
Important If you want to run ESXCLI commands included in vCLI from a Windows system, you must
have the Visual C++ 2008 redistributable for 32-bit installed on that system. Find vcredist_x86.exe for
Visual C++ 2008 and install it on your Windows system.
Prerequisites
Verify that you have ActivePerl or Strawberry Perl version 5.14 or later installed on your Windows system.
VMware, Inc.
23
Getting Started with vSphere Command-Line Interfaces
Procedure
1
Download the vCLI Windows installer package.
You can find the installer in the Automation Tools and SDKs section of the Drivers & Tools tab of the
vSphere download page.
2
Start the installer.
3
(Optional) If prompted to remove older versions of vSphere SDK for Perl or vCLI, you can either accept
or cancel the installation, and install the vCLI package on a different system.
Important The installer replaces both the vSphere SDK for Perl and vCLI. To keep an older version,
install this package on a different system.
4
Click Next in the Welcome page.
5
To install the vCLI in a nondefault directory, click Change and select an alternative directory.
The default location is C:\Program Files\VMware\VMware vSphere CLI.
6
Click Next.
7
Click Install to proceed with the installation.
The installation might take several minutes to complete.
8
Reboot your system.
If you do not reboot, path settings might not be correct on your Windows platform.
Uninstall the vCLI Package on Windows
You can uninstall the vCLI package by following the standard Windows procedure.
Procedure
1
Find the option for adding and removing programs on the Windows operating system that you are
using.
2
In the panel that appears, select VMware vSphere CLI and click Remove.
3
Click Yes when prompted.
The system uninstalls vCLI and vSphere SDK for Perl.
Enabling Certificate Verification
You can enable certificate verification by using variables.
The vSphere SDK for Perl and vCLI use Crypt::SSLEay to support certificate verification. Crypt::SSLEay
enables verification of certificates signed by a Certificate Authority (CA) if you set the following two
variables.
n
HTTPS_CA_FILE – The CA file.
n
HTTPS_CA_DIR – The CA directory.
See the Crypt::SSLEay documentation for details on setup.
Caution If the two environment variables HTTPS_CA_FILE and HTTPS_CA_DIR are set incorrectly or if a
problem with the certificate exists, vCLI commands do not complete, and do not display error or warning
messages. Use HTTPS_DEBUG for troubleshooting before running vCLI commands.
24
VMware, Inc.
Chapter 2 Installing vCLI
Deploying vMA
As an alternative to a package installation, you can deploy vMA on an ESXi host and run vCLI commands
from there.
vMA is a virtual machine that you can use to run scripts to manage ESXi systems. vMA includes a Linux
environment, vCLI, and other prepackaged software.
Setting up vMA consists of several tasks. For details about each task, see the vSphere Management Assistant
Guide.
1
Deploy vMA to an ESXi system that meets the hardware prerequisites.
See the vSphere Management Assistant Guide for prerequisites and deployment details.
2
Configure vMA.
When you boot vMA, you must specify the following required configuration information when
prompted.
n
Network information (the default is often acceptable)
n
Host name for vMA
n
Password for the vi-admin user. The vi-admin user has superuser privileges on vMA. You cannot
log in to vMA as the root user.
3
(Optional) Add a vCenter Server system or one or more ESXi systems as targets. You configure vMA for
Active Directory authentication and can then add ESXi and vCenter Server systems to vMA without
having to store passwords in the vMA credential store. See the vSphere Management Assistant Guide.
VMware, Inc.
25
Getting Started with vSphere Command-Line Interfaces
26
VMware, Inc.
Running Host Management
Commands in the ESXi Shell
3
Usually, installing vCLI and running commands from a remote system, with one or more hosts as targets, is
recommended. However, for maintenance and troubleshooting tasks you might prefer to run ESXCLI
commands in the ESXi Shell or connect to the ESXi Shell with SSH.
To run commands, you must first establish access to the ESXi Shell.
This chapter includes the following topics:
n
“ESXi Shell Access with the Direct Console,” on page 27
n
“Remote ESXi Shell Access with SSH,” on page 29
n
“Lockdown Mode,” on page 30
n
“Run an ESXCLI Command in the ESXi Shell,” on page 30
ESXi Shell Access with the Direct Console
An ESXi system includes a Direct Console User Interface (DCUI) that you can use to start and stop the
system and to perform a limited set of maintenance and troubleshooting tasks.
You can use the direct console to access the ESXi Shell, which is disabled by default. You can enable the
ESXi Shell in the direct console or by using the vSphere Web Client. You can enable local shell access or
remote shell access.
n
With local shell access, you can log in to the shell directly from the Direct Console. See “Enabling Local
ESXi Shell Access,” on page 28.
n
With remote shell (SSH) access you can connect to the host by using a shell such as PuTTY, specify a
user name and password, and run commands in the shell. See “Remote ESXi Shell Access with SSH,” on
page 29.
The ESXi Shell includes all ESXCLI commands, a set of deprecated esxcfg- commands, and a set of
commands for troubleshooting and remediation.
Important All ESXCLI commands that are available in the ESXi Shell are also included in the vCLI
package.
You can install the vCLI package on a supported Windows or Linux system or deploy the vMA virtual
appliance, and run commands against your ESXi hosts. Run commands in the ESXi Shell directly or through
SSH only in troubleshooting situations.
VMware, Inc.
27
Getting Started with vSphere Command-Line Interfaces
Enabling Local ESXi Shell Access
You can enable the ESXi Shell from the direct console or the vSphere Web Client.
Enable the ESXi Shell in the Direct Console
If you have access to the Direct Console Interface, you can enable the ESXi Shell from there.
Procedure
1
At the direct console of the ESXi host, press F2 and provide credentials when prompted.
2
Scroll to Troubleshooting Options and press Enter.
3
Select Enable ESXi Shell and press Enter.
On the left, Enable ESXi Shell changes to Disable ESXi Shell. On the right, ESXi Shell is Disabled
changes to ESXi Shell is Enabled.
4
Press Esc until you return to the main direct console screen.
What to do next
After you enable the ESXi Shell, you can use it from that monitor or through a serial port.
Enable the ESXi Shell from the vSphere Web Client
If you do not have access to the Direct Console Interface, you can enable the ESXi Shell from the
vSphere Web Client.
Procedure
1
Select the host, click Manage, and keep Settings selected.
2
Click Security Profile.
3
In the Services section, click Edit.
4
Select ESXi Shell.
5
n
To temporarily start or stop the service, click the Start or Stop button.
n
To change the Startup policy across reboots, select Start and stop with host and reboot the host.
Click OK.
What to do next
After you enable the ESXi Shell, you can use it through a serial port.
ESXi Shell Timeout
The ESXi Shell supports a timeout for ESXi Shell availability and a timeout for idle ESXi Shell sessions.
n
Availability timeout - The availability timeout setting is the amount of time that can elapse before you
must log in after the ESXi Shell is enabled. After the timeout period, the service is disabled and users
are not allowed to log in.
n
Idle timeout - If a user enables the ESXi Shell on a host, but forgets to log out of the session, the idle
session remains connected indefinitely.
You can set both timeout values from the Direct Console User Interface or from the vSphere Web Client. See
the vSphere Security document for detailed instructions.
28
VMware, Inc.
Chapter 3 Running Host Management Commands in the ESXi Shell
Use the Local ESXi Shell
After you enable the ESXi Shell in the direct console, you can use it from the main direct console screen or
remotely through a serial port.
Procedure
1
At the main direct console screen, press Alt-F1 to open a virtual console window to the host.
2
Provide credentials when prompted.
When you enter the password, characters are not displayed on the console.
3
Enter shell commands to perform management tasks.
4
To log out, enter exit in the shell.
5
To return to the direct console, press Alt-F2.
What to do next
See the vSphere Installation and Setup documentation for information on serial port setup.
Remote ESXi Shell Access with SSH
If SSH connections are enabled for your ESXi host, you can run shell commands by using a Secure Shell
client such as SSH or PuTTY.
Enable SSH Access in the Direct Console
By default, remote command execution is disabled on an ESXi host, and you cannot log in to the host by
using a remote shell. You can enable remote command execution from the direct console or from the
vSphere Web Client.
Prerequisites
Procedure
1
At the direct console of the ESXi host, press F2 and provide credentials when prompted.
2
Scroll to Troubleshooting Options and press Enter.
3
Choose Enable SSH and press Enter.
On the left, Enable SSH changes to Disable SSH. On the right, SSH is Disabled changes to SSH is
Enabled.
4
Press Esc until you return to the main direct console menu.
What to do next
After you have enabled SSH, you can log in to the ESXi Shell remotely and run ESXi Shell commands.
Enable SSH from the vSphere Web Client
By default, remote command execution is disabled on an ESXi host, and you cannot log in to the host by
using a remote shell. You can enable remote command execution from the direct console or from the
vSphere Web Client.
Procedure
1
Select the host, click Manage, and keep Settings selected.
2
Click Security Profile.
VMware, Inc.
29
Getting Started with vSphere Command-Line Interfaces
3
In the Services section, click Edit.
4
Select SSH.
5
n
To temporarily start or stop the service, click the Start or Stop button.
n
To change the Startup policy across reboots, select Start and stop with host and reboot the host.
Click OK.
What to do next
After you have enabled SSH, you can log in to the ESXi Shell remotely and run ESXi Shell commands.
Access the Remote ESXi Shell with SSH
If SSH is enabled on your ESXi host, you can run commands on that shell by using an SSH client.
Procedure
1
Open an SSH client.
2
Specify the IP address or domain name of the ESXi host.
Precise directions vary depending on the SSH client that you are using. See vendor documentation and
support.
3
Provide credentials when prompted.
Lockdown Mode
To increase the security of your ESXi hosts, you can put them in lockdown mode.
In lockdown mode, all operations must be performed through vCenter Server. By default, only the
vCenter Server system, represented by the vpxuser user, has authentication permissions. No other users can
perform operations against a host in lockdown mode.
vSphere 5.x and later supports normal lockdown mode, as discussed in the vSphere 5.x documentation
center. vSphere 6.0 and later supports more fine-grained management.
n
In normal lockdown mode, you can add users to the DCUI.Access advanced option, which can access
the Direct Console User Interface regardless of their privileges on the host. Starting with vSphere 6.0,
you can also use the vSphere Web Client to add Exception users, which can access the Direct Console
User Interface if they have host management privileges.
n
In strict lockdown mode, users cannot access the Direct Console User Interface. If vCenter Server
becomes unavailable, the host can no longer be managed.
When a host is in normal or strict lockdown mode, you cannot run vSphere CLI commands against the host
directly. Instead, you target the vCenter Server system that manages the host with the --server option and
specify the ESXi host with the --vihost option.
When you enable strict lockdown mode, the Direct Console User Interface service is disabled.
You can enable lockdown mode by using the Add Host wizard to add a host to vCenter Server, by using the
vSphere Web Client to manage a host, or by using the Direct Console User Interface (DCUI).
See the vSphere Security documentation for details on lockdown mode in vSphere 6.x.
Run an ESXCLI Command in the ESXi Shell
You can run ESXCLI commands in the ESXi Shell unless they are marked as internal in the online help.
The ESXi Shell is disabled by default. You must enable the ESXi Shell before you can run commands in the
shell. See “ESXi Shell Access with the Direct Console,” on page 27.
30
VMware, Inc.
Chapter 3 Running Host Management Commands in the ESXi Shell
Prerequisites
Verify that the ESXi Shell is enabled.
Procedure
1
Log in to the shell.
2
Run the command.
For example, to list NFS storage devices, run the following command.
esxcli storage nfs list
What to do next
You can use --help at any level of esxcli for help on available namespaces, commands, or options.
VMware, Inc.
31
Getting Started with vSphere Command-Line Interfaces
32
VMware, Inc.
Running vCLI Host Management
Commands
4
You can run vSphere Command-Line Interface (vCLI) host management commands from the command line
of the system where you installed the package, from the vMA command line, and from scripts.
Host management commands, which include ESXCLI and vicfg- commands, require at a minimum access
to the target server to run the commands on. Users must authenticate to the host, and can only perform
tasks that they are authorized to perform.
Note See Chapter 5, “Running DCLI Commands,” on page 47 for information about DCLI commands,
which you can use to manage vCenter Server services.
Important If an ESXi system that you target is in lockdown mode, you cannot run vCLI commands
against that system directly. You must target a vCenter Server system that manages the ESXi system and use
the --vihost option to specify the ESXi target. See “vCLI and Lockdown Mode,” on page 40.
This chapter includes the following topics:
n
“Overview of Running vCLI Host Management Commands,” on page 34
n
“Protecting Passwords,” on page 34
n
“Authenticating Through vCenter Server and vCenter Single Sign-On,” on page 36
n
“Authenticating Directly to the Host,” on page 36
n
“Trust Relationship Requirement for ESXCLI Commands,” on page 40
n
“Common Options for vCLI Host Management Command Execution,” on page 42
n
“Using vCLI Commands in Scripts,” on page 44
n
“Run Host Management Commands from a Windows System,” on page 45
n
“Run Host Management Commands from a Linux System,” on page 45
VMware, Inc.
33
Getting Started with vSphere Command-Line Interfaces
Overview of Running vCLI Host Management Commands
You can run vCLI commands interactively or in scripts, and you can target the host directly or target a
vCenter Server system that manages the host.
Targeting the Host Directly
You can target the host directly from an administration server on which you installed vCLI, by using vMA,
or by running scripts.
n
Open a command prompt on a Linux or Windows system on which you installed vCLI. Enter
commands into that command prompt, specifying connection options. See “Authenticating Directly to
the Host,” on page 36.
n
Access the vMA Linux console. Set up target servers and run vCLI commands against the targets
without additional authentication.
n
Prepare scripts that contain vCLI commands. Then run the scripts from a system that has the vCLI
package installed or from the vMA Linux console. See “Using vCLI Commands in Scripts,” on page 44.
Note Different command sets in the vCLI package require different connection options.
When you run commands against an ESXi host, you must be authenticated for that host.
Targeting a Host That is Managed by a vCenter Server System
When you target a host that is managed by a vCenter Server system, you can run commands in different
ways.
n
Specify the vCenter Single Sign-On service with the --psc option and, if multiple vCenter Server
systems are associated with the vCenter Single Sign-On service, the vCenter Server system with the
--server option. Specify also the host with the --vihost option.
n
Specify the vCenter Server system with the --server option and the ESXi host with the --vihost
option.
n
Specify only the ESXi host with the --vihost option.
When you can authenticate to a vCenter Single Sign-On service or to a vCenter Server system, you can target
all ESXi hosts that vCenter Server manages without additional authentication. See “Authenticating Through
vCenter Server and vCenter Single Sign-On,” on page 36.
Protecting Passwords
You can follow different password protection approaches depending on your environment setup.
Caution If you specify passwords in plain text, you risk exposing the password to other users. The
password might also become exposed in backup files. Do not provide plain-text passwords on production
systems.
Follow one of the following approaches for protecting passwords.
34
n
If you use a vCLI host management command interactively and do not specify a user name and
password, you are prompted for them. The screen does not echo the password that you enter.
n
For noninteractive use, you can create a session file using the save_session option. See “Create and Use
a Session File,” on page 36.
VMware, Inc.
Chapter 4 Running vCLI Host Management Commands
n
Target a vCenter Server system and authenticate to vCenter Single Sign-On. You can save the
corresponding session and use it for subsequent connections. See “Authenticating Through vCenter
Server and vCenter Single Sign-On,” on page 36.
n
Use variables or configuration files.
n
If you are running vCLI on a Windows system, you can use the --passthroughauth option. If the user
who runs the command with that option is a known Active Directory user, no password is required.
If you are running vMA, you can set up target servers and run most vCLI commands against target servers
without additional authentication. See the vSphere Management Assistant Guide.
With vCLI you can run scripts against multiple target servers from the same administration server. You
must have the correct privileges to perform the actions on each target, and you must authenticate to the
target.
Important Administrators can place ESXi hosts in lockdown mode for enhanced security. By default, even
the root user cannot run vCLI commands directly against ESXi hosts in lockdown mode. See “vCLI and
Lockdown Mode,” on page 40 and the vSphere Security documentation.
Order of Precedence for vCLI Host Management Commands
When you run a vCLI host management command, authentication happens in order of precedence.
The order of precedence is described in the following table. This order of precedence always applies. That
means, for example, that you cannot override an environment variable setting in a configuration file.
Note Available options and order of precedence are different for DCLI. See “Order of Precedence for DCLI
Authentication,” on page 51.
If you are authenticating through vCenter Single Sign-On, the order of precedence is preserved. For
example, information you specify on the command line overrides information in an environment variable.
Authentication
Description
See
Command line
Password (--password), session file
(--sessionfile), or configuration
file (--config) specified on the
command line.
“Create and Use a Session File,” on
page 36
Environment variable
Password specified in an
environment variable.
“Using Environment Variables,” on
page 37
Configuration file
Password specified in a configuration
file.
“Using a Configuration File,” on
page 38
Current account (Active Directory)
Current account information used to
establish an SSPI connection.
Available only on Windows.
“Using the Microsoft Windows
Security Support Provider Interface,”
on page 39
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.
VMware, Inc.
35
Getting Started with vSphere Command-Line Interfaces
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 SignOn 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.
The 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.
n
psc - Specifies the Platform Services Controller instance associated with the vCenter Server system that
manages the host.
n
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.
n
vihost - Specifies the ESXi host, as in earlier versions of vCLI.
Examples
vicfg-nics -l --username <sso_username> --password "<admin_pwd>" --server <vc_HOSTNAME_OR_IP> -psc <psc_HOSTNAME_OR_IP> --vihost <esxi_HOSTNAME_OR_IP>
esxcli --server vc_HOSTNAME_OR_IP> --vihost <esxi_HOSTNAME_OR_IP> --username USERNAME> -password <PASSWORD> --psc <psc_HOSTNAME_OR_IP> hardware clock get
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. For example,
you can save the session by running the following command.
vicfg-nics -l --username sso_username> --password "<admin_pwd>" --server vc_HOSTNAME_OR_IP> -psc <psc_HOSTNAME_OR_IP> --vihost <esxi_HOSTNAME_OR_IP>
Using a session file results in less overhead and better performance than connecting to the Platform Services
Controller repeatedly.
Authenticating Directly to the Host
vCLI offers several options for authenticating directly to the host.
Create and Use a Session File
You can create a session file with the save_session script.
The save_session 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.
Procedure
1
Navigate to the directory where the script is located.
The following examples show possible locations of the script.
36
VMware, Inc.
Chapter 4 Running vCLI Host Management Commands
2
Operating System
Command
Windows
cd C:\Program Files\VMware\VMware vSphere CLI\Perl\apps\session
Linux
cd /usr/share/lib/vmware-vcli/apps/session
Run save_session.
You can use the save_session.pl script or the --savesessionfile option to the vCLI command. You
must specify the server which to connect to and the name of a session file in which the script saves an
authentication cookie.
save_session --savesessionfile <location> --server <server>
The following examples show the correct syntax for each OS.
Operating System
Command
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>
Note 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>
The following examples show the correct syntax for each OS.
Operating System
Command
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
How you use environment variables depends on the operating system that you are using.
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,” on page 44 for an environment variable example.
VMware, Inc.
37
Getting Started with vSphere Command-Line Interfaces
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 “Common Options for vCLI Host Management
Command Execution,” on page 42.
Caution Limit read access to a configuration file that contains user credentials.
Pass in the configuration file when you run vCLI commands, by using the following syntax.
<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_PSC = XX.XXX.XXX.XX
VI_USERNAME = administrator@vsphere.local
VI_PASSWORD = admin_password
VI_PROTOCOL = https
VI_SERVER = my_vc
If you have set up your system to run this file, you can run scripts against the specified ESXi host afterwards.
Using Command-Line Options
You can pass in command-line options by 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_HOSTNAME_OR_IP> --username <privileged_user> --password <pw> --vihost
<esxi_HOSTNAME_OR_IP> <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_HOSTNAME_OR_IP> --username <privileged_user> --password <pw> -vihost <esxi_HOSTNAME_OR_IP> --<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$.
38
VMware, Inc.
Chapter 4 Running vCLI Host Management Commands
Example: Linux
esxcli --server <esxi_HOSTNAME_OR_IP> --username snow\-white --password dwarf\$ network ip
interface list
esxcli --server <esxi_HOSTNAME_OR_IP> --username snow\-white --password 'dwarf$' network ip
interface list
vicfg-mpath --server <esxi_HOSTNAME_OR_IP> --username snow\-white --password dwarf\$ --list
vicfg-mpath --server <esxi_HOSTNAME_OR_IP> --username 'snow-white' --password 'dwarf$' --list
Example: Windows
esxcli --server <esxi_HOSTNAME_OR_IP> --username "snow-white" --password "dwarf$" network ip
interface list
vicfg-mpath.pl --server <esxo_HOSTNAME_OR_IP> --username “snow-white” --password “dwarf$” --list
Using the Microsoft Windows Security Support Provider Interface
With the --passthroughauth option, which is available if you run vCLI commands from a Microsoft
Windows system, you can use the Microsoft Windows Security Support Provider Interface (SSPI).
You can refer to the Microsoft Web site for detailed information on SSPI.
You can use --passthroughauth to establish a connection with a vCenter Server system. After the connection
has been established, authentication for the vCenter Server system or any ESXi system that 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_HOSTNAME_OR_IP> --passthroughauth --passthroughauthpackage "Kerberos"
--vihost <esxi_HOSTNAME_OR_IP> network ip interface list
vicfg-mpath.pl --server <vc_HOSTNAME_OR_IP> --passthroughauth --passthroughauthpackage
"Kerberos" --vihost <esxi_HOSTNAME_OR_IP> --list
This example establishes a connection 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.
VMware, Inc.
39
Getting Started with vSphere Command-Line Interfaces
vCLI and Lockdown Mode
Lockdown mode can disable 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 Web 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.
n
vifs
n
vicfg-user
n
vicfg-cfgbackup
n
vihostupdate
n
vmkfstools
n
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.
Trust Relationship Requirement for ESXCLI Commands
Starting with vSphere 6.0, ESXCLI checks whether a trust relationship exists between the machine where
you run the ESXCLI command and the ESXi host. An error results if the trust relationship does not exist.
Download and Install the vCenter Server Certificate
You can download the vCenter Server root certificate by using a Web browser and add it to the trusted
certificates on the machine where you plan to run ESXCLI commands.
Procedure
1
Enter the URL of the vCenter Server system or vCenter Server Appliance into a Web browser.
2
Click the Download trusted root certificates link.
3
Change the extension of the downloaded file to .zip. (The file is a ZIP file of all certificates in the
TRUSTED_ROOTS store).
4
Extract the ZIP file.
A certificates folder is extracted. The folder includes files with the extension .0. .1, and so on, which are
certificates, and files with the extension .r0, r1, and so on which are CRL files associated with the
certificates.
5
Add the trusted root certificates to the list of trusted roots.
The process differs depending on the platform that you are on.
What to do next
You can now run ESXCLI commands against any host that is managed by the trusted vCenter Server system
without supplying additional information if you specify the vCenter Server system in the --server option
and the ESXi host in the --vihost option.
40
VMware, Inc.
Chapter 4 Running vCLI Host Management Commands
Using the --cacertsfile Option
Using a certificate to establish the trust relationship is the most secure option.
You can specify the certificate with the --cacertsfile parameter or the VI_CACERTFILE variable.
Using the --thumbprint Option
You can supply the thumbprint for the target ESXi host or vCenter Server system in the --thumbprint
parameter or the VI_THUMBPRINT variable.
When you run a command, ESXCLI first checks whether a certificate file is available. If not, ESXCLI checks
whether a thumbprint of the target server is available. If not, you receive an error of the following type.
Connect to sof-40583-srv failed. Server SHA-1 thumbprint: 5D:01:06:63:55:9D:DF:FE:38:81:6E:2C:FA:
71:BC:Usin63:82:C5:16:51 (not trusted).
You can run the command with the thumbprint to establish the trust relationship, or add the thumbprint to
the VI_THUMBPRINT variable. For example, using the thumbprint of the ESXi host above, you can run the
following command.
esxcli --server myESXi --username user1 --password 'my_password' --thumbprint 5D:
01:06:63:55:9D:DF:FE:38:81:6E:2C:FA:71:BC:63:82:C5:16:51 storage nfs list
Use the Credential Store
Your vCLI installation includes a credential store. You can establish trust for a user with the credential store.
You can manage the credential store with the credstore-admin utility application, which is located in
the /Perl/apps/general directory inside the VMware vSphere CLI directory.
Important Updating the credential store is a two-step process. First you add the user and password for
the server, and then you add the thumbprint for the server.
Procedure
1
Add the user and password for the target ESXi host to the local credential store.
credstore_admin.pl add --server <esxi_HOSTNAME_OR_IP> --username <user> --password <pwd>
2
Add the thumbprint for the target ESXi host. This thumbprint was returned in the error when you
attempted to connect to the host.
credstore_admin.pl add --server <esxi_HOSTNAME_OR_IP> --thumbprint <thumbprint>
3
If you are using a non-default credential store file, you must pass it in with the --credstore option.
If you do not use the --credstore option, the host becomes accessible without authentication.
VMware, Inc.
41
Getting Started with vSphere Command-Line Interfaces
Common Options for vCLI Host Management Command Execution
You can use connection options that are available for all vCLI host management commands and common
options that you can use when you run a vicfg- vCLI command.
vCLI Connection Options
The following table lists options that are available for all vCLI host management commands in alphabetical
order. The table includes options for use on the command line and variables for use in configuration files.
Options for executing DCLI commands are different.
Important Starting with vSphere 5.5, vCLI supports both IPv4 and IPv6 connections.
See “Run Host Management Commands from a Windows System,” on page 45 and “Run Host
Management Commands from a Linux System,” on page 45.
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 which encoding to use. Several encodings are supported.
n
n
utf8
cp936 (Simplified Chinese)
n
shftjis (Japanese)
n
iso-885901 (German)
You can use --encoding to specify the encoding for vCLI to 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
detailed information on 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 by using this option.
This option is supported only if you are running vCLI on a Windows system
and connecting to a vCenter Server system.
42
VMware, Inc.
Chapter 4 Running vCLI Host Management Commands
Option and Environment Variable
Description
--password <passwd>
VI_PASSWORD=<passwd>
n
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.
n
--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 is idle 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,” on page 36.
--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.
VMware, Inc.
43
Getting Started with vSphere Command-Line Interfaces
Option and Environment Variable
Description
--username <u_name>
VI_USERNAME=<u_name>
Uses the specified user name.
n
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.
n
--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.
vCLI Common Options
The following lists options not used as connection options that you can use when you run a vicfg- vCLI
command.
Option
Description
--help
Prints a brief usage message. The message first lists each command-specific option and then each of the
common options.
--verbose
Displays additional debugging information.
--version
Displays version information.
Using vCLI Commands in Scripts
Most administrators run scripts to perform the same task repeatedly or to perform a task on multiple hosts.
You can run vCLI commands from one administration server against multiple target servers.
For example, when a new data store becomes available in your environment, you must make that data store
available to each ESXi host. The following sample script illustrates how to make a NAS data store available
to three hosts (esxi_server_a, esx_server_b, and esxi_server_c).
The sample assumes that a configuration file /home/admin/.visdkrc.<hostname> exists for each host. For
example, the configuration file for esxi_server_a has the following contents.
VI_SERVER = esxi_server_a
VI_USERNAME = root
VI_PASSWORD = xysfdjkat
The script adds the NAS data store to each host defined in VIHOSTS.
#!/bin/bash
VI_CONFIG_FILE=/home/admin/viconfig
VIHOSTS=(esxi_server_a esx_server_b esxi_server_c)
for VIHOST in ${VIHOSTS[@]}
do
echo "Adding NAS datastore for ${VIHOST} ..."
44
VMware, Inc.
Chapter 4 Running vCLI Host Management Commands
esxcli --config ${VI_CONFIG_FILE} storage nfs add --host ${VIHOST} --share <share point> -volume-name <volume name>
esxcli --config ${VI_CONFIG_FILE} storage nfs list
done
Run Host Management Commands from a Windows System
After you install vCLI and reboot your system, you can test the installation by running a vCLI or SDK for
Perl command from the Windows command prompt.
Procedure
1
From the Windows Start menu, choose Programs > VMware > VMware vSphere CLI > Command
Prompt.
A command prompt shell for the location where vCLI is installed appears. You have easy access to vCLI
and to vSphere SDK for Perl commands from that location.
2
Run the command, passing in connection options and other options.
On Windows, the extension .pl is required for vicfg- commands, but not for ESXCLI.
<command>.pl <conn_options> <params>
The following examples show the difference between ESXCLI and vicfg- syntax.
esxcli --server <esxi_HOSTNAME_OR_IP> --username "snow-white" --password "dwarf$" network ip
interface list
vicfg-mpath.pl --server <esxi_HOSTNAME_OR_IP> --username "snow-white" --password "dwarf$" -list
The system prompts you for a user name and password.
Run Host Management Commands from a Linux System
After installation, you can run vCLI commands and vSphere SDK for Perl utility applications at the
command prompt.
Procedure
1
Open a command prompt.
2
(Optional) Change to the directory where you installed the vCLI.
Default is /usr/bin.
3
Run the command, including the connection options.
<command> <conn_options> <params>
Specify connection options in a configuration file or pass them on the command line. The extension .pl
is not required on Linux. The following examples show the difference between ESXCLI and vicfgsyntax.
esxcli --server <esxi_HOSTNAME_OR_IP> --username snow\-white --password dwarf\$ network ip
interface list
vicfg-mpath --server <esxi_HOSTNAME_OR_IP> --username snow\-white --password dwarf\$ --list
The system prompts you for a user name and password for the target server.
VMware, Inc.
45
Getting Started with vSphere Command-Line Interfaces
46
VMware, Inc.
Running DCLI Commands
5
You can run DCLI commands as vCLI commands, from the vCenter Server Appliance shell, and from the
command prompt of a vCenter Server Windows installation.
Important Authentication options for DCLI commands differ from options for vCLI host management
commands. Users who run DCLI commands to monitor and manage vCenter services must have the
appropriate privileges.
n
When you run DCLI commands included with vCLI, you must be a user who can authenticate to
vCenter Single Sign-On and who is also authorized to perform the service, for example, manage
vCenter tags.
n
When you run DCLI commands from the vCenter Server Appliance shell, DCLI enables you to run
some commands without additional authentication. However, for management of certain services, you
might be prompted for a user name and password.
This chapter includes the following topics:
n
“Overview of Running DCLI Commands,” on page 47
n
“Using DCLI Commands,” on page 50
n
“Input, Output, and Return Codes,” on page 52
n
“Using DCLI with Variables,” on page 52
n
“Using DCLI Interactive Mode,” on page 52
n
“DCLI SSL Connection,” on page 53
n
“DCLI History File,” on page 53
Overview of Running DCLI Commands
You can run DCLI commands interactively or in scripts in several ways.
n
Run DCLI commands locally from the vCenter Server Appliance shell.
n
Run DCLI commands locally from your vCenter Server Windows command prompt.
n
Run DCLI commands that are included in the vCLI package.
VMware, Inc.
n
Open a command prompt on a Linux or Windows system on which you installed vCLI. Enter
commands into that command prompt, specifying connection options.
n
Access the vMA Linux console. DCLI does not support the vi-fastpass connections available from
vMA.
47
Getting Started with vSphere Command-Line Interfaces
n
Prepare scripts that contain DCLI commands. Then run the scripts as vCLI scripts, from the
vCenter Server Windows command prompt, or from the vCenter Server Appliance shell. Use the
credential store options to authenticate. Passwords are not supported in scripts.
DCLI Syntax
Each DCLI command uses the same syntax.
The command name can be followed by DCLI connection and formatting options, each preceded by a plus
(+) sign. You also specify the namespace, the command, and the command options. Namespaces are nested.
Note The order in which DCLI options are provided on the command line is not important. However, you
must specify DCLI options with a plus (+) and command-specific options with a minus (-).
The syntax of a DCLI command is the following.
dcli +[DCLI options] <namespace> [<namespace> ...] <cmd> --[cmd option] [option value]
The following table describes the DCLI syntax elements.
Syntax Element
Description
DCLI options
Predefined options for connection information including the vSphere Automation SDK endpoint
and formatting options. Always preceded by a plus (+) sign.
Not required when you run the command in the vCenter Server Appliance shell or from the
command prompt of a vCenter Server Windows installation.
namespace
Groups DCLI commands. Namespaces correspond to the vSphere Automation SDK namespaces
and are nested.
command
Reports on or modifies the state of the system.
option and value
Command option and value pairs preceded by two minus signs (--).
Example
$dcli +server my_remote_vc +username user42 com vmware cis tagging tag list
DCLI Options
You can run each DCLI command with connection or formatting options preceded by a + sign.
For many of the options, you can instead use variables. See “Using DCLI with Variables,” on page 52.
dcli [+server SERVER_IP]
[+interactive]
[+prompt PROMPT]
[+skip-server-verification]
[+cacert-file CACERT_FILE]
[+more]
[+formatter {simple,table,xml,json,html,csv}]
[+loglevel {debug, info, warning, error}]
[+username USERNAME] [+password]
[+credstore-file CREDSTORE_FILE]
[+credstore-add | +credstore-remove | +credstore-list]
[+session-manager SESSION_MANAGER] [args [args ...]]
With these options you can provide the following information. If you are entering options in DCLI
interactive mode, tab completion is supported on both Linux and Windows systems. In all cases, you can
specify a partial option if the option is not ambiguous. For example, +i indicates interactive, but you have to
specify, at least, +credstore-a to disambiguate that option.
48
VMware, Inc.
Chapter 5 Running DCLI Commands
The following table describes the DCLI options.
Option
Description
Default
server
The vCenter Server system to which DCLI connects.
localhost
interactive
Runs DCLI in interactive shell mode, which supports tab
completion of commands, options, and some option values. It
also supports saving the command history across DCLI
sessions.
Interactive mode is faster because DCLI caches the list of
commands available on a vCenter Server system.
prompt
Prompt that the interactive shell uses.
dcli>
skip-serververification
Skips the server SSL verification process.
False
cacert-file
Specifies the certificate authority certificates for validating
SSL connections.
more
Displays page-wise output.
formatter
Output formatter, which has one of the following possible
values.
n simple
n table
n xml
n json
n html
n csv
Default is table for lists of structures
and simple for all other output.
loglevel
The log level, which has one of the following possible values.
n debug
n info
n warning
n error
info
username
If you run from the local shell, most DCLI commands do not
require the user name. If you are running vCLI commands,
the user you specify must be able to authenticate to the
vCenter Server system.
The user you specify must have the privileges to perform the
task, as specified through vCenter Server roles.
You are prompted for the password. The password is not
echoed to screen.
credstore-file
Path to the credential store file to use for credential store
operations or for reading login credentials.
Use this option only if the default credential store file name
does not work in your environment.
By default, the credential store file is in
the .dcli/.dcli_credstore directory inside the home
directory.
$HOME/.dcli/.dcli_credstore
credstore-add
Adds login credentials entered for a command to the DCLI
credential store file.
This option stores the server IP address, session manager,
username and password for the command being executed. If
an entry already exists, the command updates the entry.
dcli directory inside the home
directory.
VMware, Inc.
$HOME/.dcli
49
Getting Started with vSphere Command-Line Interfaces
Option
Description
credstoreremove
Removes an entry from the DCLI credential store file.
This option removes the entry for a specified server IP
address and user name if only one session manager is present
for a target server and user.
In rare cases, information about multiple session manager
entries is present. You must provide the session manager
with the session-manager option.
credstore-list
Lists all entries stored in the DCLI credential store file. Each
entry includes the server IP address, session manager, and
user name.
sessionmanager
Use this option if you use the credstore-remove option the
same user name and password are stored through multiple
session managers. Not usually required.
Default
Using DCLI Commands
You can display help information for DCLI commands, and run the commands from a system where vCLI is
installed, from the vCenter Server Appliance shell, or from a vCenter Server on Windows command prompt.
Displaying Help Information for DCLI Commands
You can display help for each namespace and command by using the --help command-line option. Because
the available commands depend entirely on the services that are available in the vCenter environment that
you are targeting, you must include the server for accurate help information.
Help returns the following information for a command.
n
Each input option
n
Whether the option is required
n
Input type
Example
dcli com vmware cis tagging tag create --help
usage: com vmware cis tagging tag create [-h] --name NAME --description DESCRIPTION --categoryid CATEGORY_ID
Creates a tag
Input Arguments:
-h, --help
--name NAME
show this help message and exit
required: The display name of the tag (string)
--description DESCRIPTION
required: The description of the tag (string)
--category-id CATEGORY_ID
required: The unique identifier of the parent category in which this tag
will be created (string)
Running DCLI Commands Included in the vCLI Package
You can run vCLI commands from an administration server on which you installed the vCLI package.
After installation, the VMware DCLI folder is available inside your vCLI installation path. You must open a
command prompt in your installation folder path and navigate to the VMware DCLI folder.
50
VMware, Inc.
Chapter 5 Running DCLI Commands
You must specify a server, user name, and password. If you specify credstore-add, DCLI creates a credential
store file on the local machine. As a result, you are no longer required to specify the user name and
password when you run DCLI commands again.
Running DCLI Commands on the vCenter Server Appliance
The root user on the vCenter Server Appliance can run DCLI commands from the appliance shell.
The following options are available.
n
Use SSH to connect to the shell or log in to the shell directly as the root user.
n
You can run commands individually, or start the interactive DCLI shell. The interactive shell has several
advantages including tab completion and a history file.
>dcli +interactive
n
You can list commands, display help for commands, and run commands. In the example below, the
interactive shell uses the default dcli> prompt.
dcli> com vmware vcenter vm list
Using DCLI with a Credential Store File
To avoid entering the user name and password each time you run a DCLI command, you can add the
current user and the associated password and server IP address to a credential store file by using the
credstore-add option on the command line.
Passwords are encrypted in the credential store file, but if you want to remove credential store information,
you can use +credstore-remove to do so.
By default, the credential store file is located in <homedir>/.dcli/.dcli_credstore, but you can change the
location with the +credstore-file option.
Examples
The following examples illustrate how you can interact with the credential store.
1
Add a new credential store entry.
dcli com vmware cis tagging tag list +credstore-add +username user1
2
Remove a credential store entry.
dcli +credstore-remove +server <server> +username user1
3
List all credential store entries.
dcli +credstore-list
Order of Precedence for DCLI Authentication
When you run a DCLI command, authentication happens in order of precedence, which always applies.
That means, for example, that you can override an environment variable setting from the command line.
If you are authenticating through vCenter Single Sign-On, the order of precedence is preserved.
The following table shows the DCLI authentication precedence order.
VMware, Inc.
51
Getting Started with vSphere Command-Line Interfaces
Authentication
Description
Command line
The user name and password specified on the command line take precedence, even if a credential
store exists.
Environment variable
A user name specified in an environment variable takes precedence over user names in the
credential store, but not over the command line.
Credential store
The user name and password retrieved from the credential store. A custom credential store file at
a non-default location has precedence over a file at the default location.
Input, Output, and Return Codes
DCLI supports the following input arguments.
Basic types
You can enter basic types like string, int, double, or boolean on the command
line.
List types
You can provide the same option multiple times on the command line and
DCLI treats it as a list.
Currently supported output formatter types are simple, xml, html, table, csv and json. You can change the
output format by passing the formatter option to DCLI.
For scripting purposes DCLI returns a non-zero error code for an unsuccessful command. To see the last
command status in interactive mode, run the $? command.
Using DCLI with Variables
You can predefine a set of variables in the environment where you run DCLI commands so you do not have
to pass the options every time you run a command. The following environment variables are supported.
Variables Supported by DCLI
Variable
DCLI_SERVER
Description
Set this variable to pass the server IP address.
Passing the server option on the command line overrides this variable.
DCLI_CACERTFILE
Set this variable to pass the path of a CA certificate file.
Passing the cacert-file option on the command line overrides this variable.
DCLI_USERNAME
Set this variable to pass the user name required for authentication.
Passing the username option on command line overrides this variable.
DCLI_CREDFILE
Set this variable to point to a DCLI credential store file. Default value is
~/.dcli/.dcli_credstore.
Passing the credstore-file option on the command line overrides variable.
DCLI_HISTFILE
Set this variable to point to a DCLI interactive shell history file path. Default value is
~/.dcli/.dcli_history.
DCLI_LOGFILE
Set this variable to specify the log file for DCLI.
Using DCLI Interactive Mode
DCLI supports interactive shell mode which you can activate by using dcli +interactive.
Interactive mode supports tab completion of namespaces, commands, command options, and option values
in case of enumeration values. With DCLI interactive mode you can also pass a partial command if it is
uniquely resolvable. For example, dcli> com vmware vcenter vm list can also be run as dcli> vm list.
52
VMware, Inc.
Chapter 5 Running DCLI Commands
Interactive mode is also a quicker way to browse various namespaces and commands, as DCLI caches the
list of namespaces and commands available on the server for faster access. DCLI interactive mode provides
specific shell commands which can be accessed by running dcli> help.
You can change the prompt for DCLI interactive mode by using dcli +interactive +prompt <user-prompt>
when entering interactive mode.
DCLI SSL Connection
DCLI uses a secure connection by default. If you use DCLI from a system that is not secured, you must use
the +skip-server-verification option to connect remotely to a vCenter Server system.
DCLI History File
DCLI maintains a history file for each DCLI client that runs in interactive mode. The file stores information
on a per-user basis and not on a per-client basis.
You can find the file at the following location.
Platform
Location
Windows
C:\Users\<username>\AppData\VMware\vapi\dcli.log
vCenter Server Appliance
/var/log/vmware/vapi/dcli.log
VMware, Inc.
53
Getting Started with vSphere Command-Line Interfaces
54
VMware, Inc.
Index
D
DCL
input 52
output 52
return codes 52
DCLI
authentication 51
credential store file 51
history file 53
interactive mode 52
managing vCenter services 12
run commands 47
running commands on the vCenter Server
Appliance 51
running vCLI package commands 50
security 53
variables 52
DCLI commands
help information 50
usage 50
DCLI options 48
DCLI Syntax 13, 48
E
enable certificate verification 24
environment variables usage, vCLI host
management commands 37
ESXCLI
command support on different versions 11
host management 10
running vCLI commands 11
syntax 10
ESXCLI trust relationship requirement 40
ESXi Shell
accessing with SSH 30
direct console access 27
enable local access 28
enabling local access from the vSphere Web
Client 28
enabling local access in the Direct Console 28
enabling SSH from the vSphere Web
Client 29
enabling SSH in the direct console 29
local usage 29
lockdown mode 30
remote access with SSH 29
VMware, Inc.
running ESXCLI commands 30
timeout 28
G
glossary 5
H
host management commands, ESXi Shell 27
I
installation
Linux process overview 16
overview 15
Red Hat Enterprise Linux 18
Red Hat Enterprise Linux prerequisites 19
Red Hat Enterprise Linux with no Internet
access 19
remove previous RHEL versions 19
vCLI prerequisite software on Linux with
Internet access 20
vCLI on Windows 23
vCLI on Linux with Internet access 20
vCLI on RHEL with no Internet access 19
installing
vCLI on Linux with Internet access 22
vCLI package on Windows 23
intended audience 5
interfaces 7
P
PowerCLI, usage 12
R
running DCLI commands, overview 47
U
uninstalling
vCLI package on Linux 23
vCLI package on Windows 24
V
vCLI, package contents 13
vCLI host management commands
cacertsfile usage 41
command execution options 42
command-line options usage 38
configuration file usage 38
55
Getting Started with vSphere Command-Line Interfaces
credential store usage 41
direct host authentication 36
direct host targeting 34
lockdown mode 40
managed host targeting 34
order of precedence 35
overview 34
password protection 34
running on Linux 45
running on Windows 45
scripts 44
session file creation 36
session file usage 36
thumbprint usage 41
vCenter Server authentication 36
vCenter Server certificate installation 40
vCenter Single Sign-On authentication 36
Windows SSPI usage 39
vMA, deployment 25
vSphere management with CLI 7
56
VMware, Inc.
Download PDF
Similar pages