Vmware Getting Started With VSphere Command Line Interfaces V Center Server 6.0 Sphere Esxi Vcenter 60 Interface Qg En
User Manual: vmware vCenter Server - 6.0 - Getting Started with vSphere Command-Line Interfaces Free User Guide for VMware vCenter Software, Manual
Open the PDF directly: View PDF .
Page Count: 46
Download | |
Open PDF In Browser | View PDF |
Getting Started with vSphere Command-Line Interfaces ESXi 6.0 vCenter Server 6.0 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--001469-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–2015 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 8 Using ESXCLI for Host Management 10 ESXCLI Syntax 10 Running ESXCLI vCLI Commands 10 ESXCLI Command Support when Host and vCLI Version Do Not Match 11 Using PowerCLI to Manage Hosts and Virtual Machines 11 Using DCLI to Manage vCenter Services 11 DCLI Syntax 12 vCLI Package Contents 12 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 18 Installing the vCLI Package on RHEL (No Internet Access) 18 Installing vCLI on Linux Systems with Internet Access 19 Installing Required Prerequisite Software for Linux Systems with Internet Access 19 Installing the vCLI Package on a Linux System with Internet Access 20 Uninstalling the vCLI Package on Linux 21 Installing and Uninstalling vCLI on Windows 21 Uninstalling the vCLI Package on Windows 22 Enabling Certificate Verification 22 Deploying vMA 22 3 Running Host Management Commands in the ESXi Shell 23 ESXi Shell Access with the Direct Console 23 Enabling Local ESXi Shell Access 23 ESXi Shell Timeout 24 Using the ESXi Shell 24 Remote ESXi Shell Access with SSH 24 Enabling SSH for the ESXi Shell 25 Using the ESXi Shell with SSH 25 Lockdown Mode 26 Running ESXCLI Commands in the ESXi Shell 26 4 Running vCLI Host Management Commands 27 Overview of Running vCLI Host Management Commands 27 Targeting the Host Directly 27 Target a Host That is Managed by a vCenter Server System 28 Protecting Passwords 28 Order of Precedence for vCLI Host Management Commands 29 Authenticating Through vCenter Server and vCenter Single Sign‐On 29 Examples 29 VMware, Inc. 3 Getting Started with vSphere Command-Line Interfaces Authenticating Directly to the Host 30 Using a Session File 30 Using Environment Variables 30 Using a Configuration File 31 Using Command‐Line Options 31 Using Microsoft Windows Security Support Provider Interface 32 vCLI and Lockdown Mode 32 Trust Relationship Requirement for ESXCLI Commands 33 Downloading and Installing the vCenter Server Certificate 33 Using the ‐‐cacertsfile Option 33 Using the ‐‐thumbprint Option 33 Using the Credential Store 34 Common Options for vCLI Host Management Command Execution 34 Using vCLI Commands in Scripts 36 Running Host Management Commands from a Windows System 37 Running Host Management Commands from a Linux System 37 5 Running DCLI Commands 39 Overview of Running DCLI Commands 39 DCLI Syntax 40 DCLI Options 40 Running DCLI Commands 41 Displaying Help Information for DCLI Commands 41 Running DCLI Commands Included in the vCLI Package 42 Running DCLI Commands on the vCenter Server Appliance 42 Using DCLI with a Credential Store File 42 Order of Precedence for DCLI Authentication 43 Input, Output, and Return Codes 43 Using DCLI with Variables 43 DCLI History File 44 4 VMware, Inc. About This Book Getting Started with vSphere Command‐Line Interfaces gives an overview of command‐line interfaces in vSphere 5.0 and later 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. Document Feedback VMware welcomes your suggestions for improving our documentation. If you have comments, send your feedback to docfeedback@vmware.com. 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. Command‐Line Management in vSphere 5 and vSphere 6 for Service Console Users is a technical note for users who are currently using ESX service console commands, scripts, agents, or logs. You learn how to transition to an off‐host implementation or to use the ESXi Shell in special cases. 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. vSphere Command‐Line Interface Reference is a reference to both ESXCLI commands and vicfg- commands. 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. 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. VMware, Inc. 5 Getting Started with vSphere Command-Line Interfaces 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 22. 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. Technical Support and Education Resources The following sections describe the technical support resources available to you. To access the current version of this book and other books, go to http://www.vmware.com/support/pubs. Online and Telephone Support To use online support to submit technical support requests, view your product and contract information, and register your products, go to http://www.vmware.com/support. Customers with appropriate support contracts should use telephone support for the fastest response on priority 1 issues. Go to http://www.vmware.com/support/phone_support. Support Offerings To find out how VMware support offerings can help meet your business needs, go to http://www.vmware.com/support/services. VMware Professional Services VMware Education Services courses offer extensive hands‐on labs, case study examples, and course materials designed to be used as on‐the‐job reference tools. Courses are available onsite, in the classroom, and live online. For onsite pilot programs and implementation best practices, VMware Consulting Services provides offerings to help you assess, plan, build, and manage your virtual environment. To access information about education classes, certification programs, and consulting services, go to http://www.vmware.com/services. 6 VMware, Inc. 1 Managing vSphere with Command-Line Interfaces 1 vSphere supports several command‐line interfaces for managing your virtual infrastructure including a set of ESXi Shell commands, PowerCLI commands, and DCLI 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: “Overview of vSphere Command‐Line Interfaces” on page 8 “Using ESXCLI for Host Management” on page 10 “Using PowerCLI to Manage Hosts and Virtual Machines” on page 11 “Using DCLI to Manage vCenter Services” on page 11 “vCLI Package Contents” on page 12 VMware, Inc. 7 Getting Started with vSphere Command-Line Interfaces 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. Linux vSphere Management Assistant Windows vCLI vicfg-* ESXCLI Others (esxtop, vimcmd, vsish, rvc...) PowerCLI API vCenter Server API API ESXi ESXi ESXCLI esxcfg-* ESXCLI esxcfg-* Figure 1-1. vSphere CLIs for host management. The following command sets are available and are discussed either in this manual or other VMware documentation. Command set Description See ESXCLI commands Manage many aspects of an ESXi host. You can run ESXCLI commands remotely or in the ESXi Shell. “Using ESXCLI for Host Management” on page 10 “Installing vCLI” on page 15 vCLI package. Install the vCLI package on the server of your choice, or deploy a vMA virtual machine and target the ESXi system that you want 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. ESXi Shell. Run ESXCLI commands in the local ESXi shell to manage that host. vSphere Command‐Line Concepts and Examples vSphere Management Assistant Guide vSphere Command‐Line Interface Reference You can also run ESXCLI commands from the vSphere PowerCLI prompt by using the Get-EsxCli cmdlet. vicfg- and other vCLI commands Allow users to 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 manipulate. 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. “Installing vCLI” on page 15 vSphere Command‐Line Concepts and Examples vSphere Command‐Line Interface Reference Note: If the ESXi system is in strict lockdown mode, you must run commands against the vCenter Server system that manages your ESXi system. 8 VMware, Inc. Chapter 1 Managing vSphere with Command-Line Interfaces Command set Description See esxcfg- commands Available in the ESXi Shell. esxcfg- commands are still 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. “Running DCLI Commands” on page 39 DCLI is a CLI client to the vCloud Suite SDK interface for managing VMware SDDC services. A DCLI command talks to a vCloud Suite API endpoint to locate relevant information, and then executes the command and displays result to the user. You can run DCLI commands as follows. vCenter Server appliance. Run DCLI commands from the vCenter Server Appliance shell. See “Running DCLI Commands on the vCenter Server Appliance” on page 42. vCenter Server Windows command prompt. Install vCenter Server on a supported Windows system and run DCLI commands from the command prompt. vCLI package. VMware PowerCLI cmdlets 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 “Running DCLI Commands” on page 41. Access the vMA Linux console. DCLI does not support the vi‐fastpass connections. See the vCloud Suite SDK documentation for information about currently supported services and how they interact. 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. VMware vSphere PowerCLI provides a Windows PowerShell interface to the vSphere API. vSphere PowerCLI includes PowerShell cmdlets for administering vSphere components. VMware PowerCLI documentation set. vSphere PowerCLI includes more than 370 cmdlets, a set of sample scripts, and a function library for management and automation. The vSphere Image Builder PowerCLI and the vSphere Auto Deploy PowerCLI are included when you install vSphere PowerCLI. localcli commands Set of commands for use with VMware Technical Support. localcli commands are equivalent to ESXCLI commands, but bypass the hoste 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. Warning: If you use a localcli command, an inconsistent system state and potential failure can result. pktcap-uw utility Enables you to monitor the traffic that flows through physical network adapters, VMkernel adapters, and virtual machine adapters, and to analyze the packet information by using conventional network analysis tools such as Wireshark. vSphere Networking documentation dir-cli Commands for managing the vCenter Single Sign‐On and certificate infrastructure. vSphere Security documentation 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 vecs-cli certool appliancesh VMware, Inc. 9 Getting Started with vSphere Command-Line Interfaces Using ESXCLI for Host Management You can manage many aspects of an ESXi host with commands in 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 vSphere PowerCLI Administration Guide and the vSphere PowerCLI 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--help before you run a command on a host to make sure that the command is defined on the host you are targeting. ESXCLI Syntax Each ESXCLI command uses the same syntax. esxcli [dispatcher options] [ ...] [cmd options] dispatcher options. Predefined options for connection information such as target host, user name, and so on. See Chapter 4, “Running vCLI Host Management Commands,” on page 27. 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 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: 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 you are targeting. See “Trust Relationship Requirement for ESXCLI Commands” on page 33 for an example. namespace. Groups ESXCLI commands. vSphere 5.0 and later support nested namespaces. command. Reports on or modifies state on the system. Examples 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 options, displayed in the help or the vCLI Reference. For some commands, multiple option values, separated by spaces, are possible. Example esxcli system module parameters set -m -p "a=1 b=1 c=1" Running ESXCLI vCLI Commands You can run an ESXCLI vCLI command in the ESXi Shell for troubleshooting and remotely against a specific host or against a vCenter Server system. You have the following choices: 10 Deploy the vMA appliance 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. VMware, Inc. Chapter 1 Managing vSphere with Command-Line Interfaces 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 “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 Appendix 4, “Trust Relationship Requirement for ESXCLI Commands,” on page 33. See Chapter 4, “Running vCLI Host Management Commands,” on page 27. ESXCLI Command Support when Host and vCLI Version Do Not Match When you run an ESXCLI vCLI command, you must know the commands supported on the target host specified with --server or as a vMA target. For example: If you run commands against ESXi 4.x hosts, ESXCLI 4.x commands are supported. 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. 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 --help for a list of namespaces supported on the target. You can drill down into the namespaces for additional help. Using PowerCLI to Manage Hosts and Virtual Machines VMware vSphere PowerCLI contains snap‐ins and modules based on Microsoft PowerShell for automating vSphere and vCloud Director administration. PowerCLI provides C# and PowerShell interfaces to vSphere and other VMware product administration. vSphere 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 vSphere PowerCLI console, as follows: Through the cmdlet, which provides direct access to the ESXCLI namespaces, applications, and commands. 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. NOTE To run an ESXCLI command from PowerCLI, you must provide values for all parameters. If you want to omit a given parameter, pass $null as its argument. See the vSphere PowerCLI User’s Guide in the vSphere documentation center. Using DCLI to Manage vCenter Services The DCLI command set allows you to manage vCenter services that are new in vSphere 6.0. You cannot manage services that were part of vSphere 5.5 from DCLI. DCLI is not a host management CLI. DCLI (Datacenter CLI) is a CLI client of the vCloud Suite SDK. DCLI works like this: 1 VMware, Inc. The user runs a command in the DCLI directory and specifies a user name. 11 Getting Started with vSphere Command-Line Interfaces 2 If the user is not yet authenticated, DCLI prompts for a password. 3 The user specifies a password. 4 The command connects to the vCenter Single Sign‐On service and checks whether the user specified on the command‐line or in a certificate store file can authenticate. 5 If the user can authenticate, DCLI communicates with the vCenter Server and execute the vCloud Suite SDK command that corresponds to the DCLI command. Different vCenter Server systems support different services. 6 DCLI displays the result or an error to the user. You can run DCLI commands as follows. 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 “Running DCLI Commands” on page 41. vCenter Server appliance. Run DCLI commands from the vCenter Server Appliance shell. See “Running DCLI Commands on the vCenter Server Appliance” on page 42. vCenter Server Windows command prompt. Install vCenter Server on a supported Windows system and run DCLI commands from the command prompt. DCLI Syntax Each DCLI command uses the same syntax. The command name can be followed by connection and formatting options, each preceded by a + sign. You also specify the name space, the command, and the command options. Name spaces 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 (‐). dcli +[DCLI options] [ ...] --[cmd option] [option value] DCLI options. Predefined options for connection information including the vCloud Suite SDK endpoint and formatting options. Always preceded by a + 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 vCloud Suite SDK namespaces and are nested. command. Reports on or modifies state on the system. option and value. Command option and value pairs. Example $dcli +server 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. 12 DCLI Commands. The DCLI commands are new in vSphere 6.0, and are available for managing vCenter services that are new in vSphere 6.0. These commands are available as part of vCLI, from the vCenter Server Virtual Appliance, and from the command‐prompt of a vCenter Server Windows installation. Host Management Commands. Includes the following command sets. VMware, Inc. Chapter 1 Managing vSphere with Command-Line Interfaces ESXCLI commands. The ESXCLI commands included in the vCLI package are equivalent to the ESXCLI commands available in the ESXi Shell. vicfg‐ commands. The vicfg- command set is similar to the deprecated esxcfg- command set in the ESXi Shell. 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. You can run vCLI commands from a Windows or Linux system, or use vMA. 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 “Installing vCLI” on page 15. 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 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 “Running vCLI Host Management Commands” on page 27 and “Running DCLI Commands” on page 41. VMware, Inc. 13 Getting Started with vSphere Command-Line Interfaces 14 VMware, Inc. 2 2 Installing vCLI You can install a vCLI package on a Linux or a Microsoft Windows system, or deploy the vSphere Management Assistant (vMA) on an ESXi host. This chapter includes the following topics: “Installation Overview” on page 15 “Overview of Linux Installation Process” on page 16 “Installing the vCLI Package on Red Hat Enterprise Linux” on page 18 “Installing vCLI on Linux Systems with Internet Access” on page 19 “Uninstalling the vCLI Package on Linux” on page 21 “Installing and Uninstalling vCLI on Windows” on page 21 “Uninstalling the vCLI Package on Windows” on page 22 “Enabling Certificate Verification” on page 22 “Deploying vMA” on page 22 Installation Overview You can install a vCLI package on a supported platform or deploy the vMA virtual machine on an ESXi host. 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 19, and “Installing and Uninstalling vCLI on Windows” on page 21. 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 contents of the installer package differs for different platforms. Platform Installation Process Windows The installation package includes vCLI, vSphere SDK for Perl, and prerequisite Perl modules. Red Hat Enterprise Linux You must install required software. See “Installing Required Prerequisite Software for Red Hat Enterprise Linux” on page 18. The installer for RHEL prompts you whether you want to install other missing modules from the Internet or from the package. SLES and Ubuntu If you have Internet access, you can have the installer download Perl modules from CPAN. The installer can instead install Perl modules that it does not find on your system from the installer package. You must install required software and you must have Internet access. See “Installing Required Prerequisite Software for Linux Systems with Internet Access” on page 19. The installer downloads other Perl modules from CPAN. VMware, Inc. 15 Getting Started with vSphere Command-Line Interfaces 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 specify the target server connection options directly or indirectly. You can also write scripts and manage your vSphere environment using those scripts. 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 22. 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 packages 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 18 and “Installing Required Prerequisite Software for Linux Systems with Internet Access” on page 19. LibXML2 Used for XML parsing. The vCLI client requires 2.6.26 or higher version. If you have an older version installed, please upgrade to 2.6.26 or higher. The libxml2 package is not included in the default Linux distribution. See “Installing Required Prerequisite Software for Red Hat Enterprise Linux” on page 18 and “Installing Required Prerequisite Software for Linux Systems with Internet Access” on page 19. uuid 16 Included in uuid-devel for SLES 11 and in e2fsprogs-devel for other Linux platforms. Required by the UUID Perl module. 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 18 and “Installing Required Prerequisite Software for Linux Systems with Internet Access” on page 19 for instructions. 3 The installer checks whether the following Perl modules are found, and whether the correct version is installed. Crypt‐SSLeay‐0.55 (0.55‐0.9.7 or 0.55‐0.9.8) IO‐Compress‐Base‐2.037 Compress‐Zlib‐2.037 IO‐Compress‐Zlib‐2.037 Compress‐Raw‐Zlib‐2.037 Archive‐Zip‐1.28 Data‐Dumper‐2.121 XML‐LibXML‐1.63 libwww‐perl‐5.805 LWP‐Protocol‐https‐6.02 XML‐LibXML‐Common‐0.13 XML‐NamespaceSupport‐1.09 VMware, Inc. Chapter 2 Installing vCLI XML‐SAX‐0.16 Data‐Dump‐1.15 URI‐1.37 UUID‐0.03 SOAP‐Lite‐0.710.08 HTML‐Parser‐3.60 version‐0.78 Class‐MethodMaker‐2.10 JSON‐PP‐2.27203 Devel‐StackTrace‐131 Class‐Data‐Inheritable‐0.08 Convert‐ASN1‐0.26 Cyrpt‐OpenSSL‐RSA‐0.28 Crypt‐X509‐0.51 Exception‐Class‐1.37 MIME‐Base64‐3.14 UUID‐Random‐0.04 Socket6‐023 IO‐Socket‐INET6‐2.71 Net‐INET6Glue‐0.600_1 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 have to install that module. NOTE If you intend to run vCLI commands with SSL certification, be sure to check 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 Installer behavior RHEL (No Internet access) On RHEL, the installer allows you to install Perl modules with CPAN if Internet access is available. If no Internet access is available, and a module is not currently on your system, the installer installs it. If a different version of a module is found, the installer does not install it and proceeds with 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 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 explicitly update those modules yourself. All Linux distributions (Internet access) The installer proceeds depending on whether the Perl modules are found. 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 19. If a lower version of a recommended module is found, the installer does not install a different version from CPAN and proceeds with installation. After completing 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 using the package installer for your platform, the installation CD, or CPAN. If a higher version of a recommended module is found, the installer proceeds with installation and does not display a message after installation. Note: The installer does not overwrite existing versions of recommended Perl modules. You must explicitly update those modules yourself. VMware, Inc. 17 Getting Started with vSphere Command-Line Interfaces 5 After all required software and all prerequisite Perl modules are installed, you can install vCLI. See “Installing the vCLI Package on Red Hat Enterprise Linux” on page 18 and “Installing the vCLI Package on a Linux System 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 do so before or after the installation, using the command appropriate for your distribution and shell (setenv, export, and so on). If you do not reset the path, the system might still look for executables in the old location. Installing the vCLI Package on Red Hat Enterprise Linux vCLI is supported on Red Hat Enterprise Linux versions that are listed in the Release Notes. On RHEL, the vSphere SDK for Perl installer prompts you whether you want to install required Perl modules from the installation package or from CPAN. Follow these steps to install the software. 1 Install required prerequisite software. See “Installing Required Prerequisite Software for Red Hat Enterprise Linux” on page 18. 2 When prompted, direct the installer to install additional prerequisites from the installation package (see “Installing the vCLI Package on RHEL (No Internet Access)” on page 18) or from CPAN (see “Installing the vCLI Package on a Linux System with Internet Access” on page 20). 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 prerequisites using yum, the RHEL package installer (recommended), or from the installation DVD, as follows: RHEL 6.3 32 bit yum install e2fsprogs-devel libuuid-devel yum install perl-XML-LibXML RHEL 6.3 64 bit yum install e2fsprogs-devel libuuid-devel yum install glibc.i686 yum install perl-XML-LibXML Recommended Perl Modules When the installer finishes, it might issue a warning that the version of a module installed on your system does not match the version with which vCLI was tested. Install that version 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 (No Internet Access) Before you install vCLI, you must remove all previous versions of that software. The process differs from simply uninstalling vCLI. To remove previous versions of vCLI 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 18 Delete existing versions of vSphere-CLI.xxxx.tar.gz and delete the vmware-vsphere-cli-distrib directory. VMware, Inc. Chapter 2 Installing vCLI To install vCLI on RHEL 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: / /sudo vmware-vsphere-cli-distrib/vmware-install.pl 3 To accept the license terms, type yes and press Enter. 4 To install Perl modules locally, type 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: A success message appears. The installer lists different version numbers for required modules (if any). The prompt returns to the shell prompt. If you accepted the defaults during installation, you can find the installed software in the following locations: vCLI scripts – /usr/bin vSphere SDK for Perl utility applications – /usr/lib/vmware-vcli/apps vSphere SDK for Perl sample scripts – /usr/share/doc/vmware-vcli/samples See the vSphere SDK for Perl documentation for a reference to all utility applications. After you install the vCLI, you can test the installation by running a command from the command prompt. See “Running Host Management Commands from a Linux System” on page 37. 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 following prerequisites. Internet access. You must have Internet access when you run the installer because the installer uses CPAN to install prerequisite Perl modules. 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. 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= :port export ftp_proxy= :port Installing Required Prerequisite Software for Linux Systems with Internet Access If required 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. VMware, Inc. 19 Getting Started with vSphere Command-Line Interfaces Table 2-1. Installing Required Prerequisite Software Platform Installation RHEL 6.3 32 bit Find the required modules on the installation DVD, or use yum to install them. yum install e2fsprogs-devel libuuid-devel yum install perl-XML-LibXML RHEL 6.3 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 SUSE Enterprise Install the prerequisite packages from the SLES SDK DVD. When you insert the DVD, it offers to auto run. Cancel the auto run dialog box and use the yast package installer to install OpenSSL or other missing required packages. SLES 11 64 bit. yast -i openssl-devel libuuid-devel libuuid-devel-32bit SLES 11 32 bit. yast -i openssl-devel libuuid-devel Some users might be authorized to use the Novell Customer Center and use yast to retrieve missing packages from there. Ubuntu 1. Connect to the Internet. 2. Update the local repository of libraries from a terminal window. sudo apt-get update 3. Install the required libraries from a terminal window. 32 bit. sudo apt-get install build-essential gcc uuid uuid-dev perl libssl-dev perl-doc liburi-perl libxml-libxml-perl libcrypt-ssleay-perl 64 bit. sudo apt-get install ia32-libs build-essential gcc uuid uuid-dev perl libssl-dev perl-doc liburi-perl libxml-libxml-perl libcrypt-ssleay-perl For Ubuntu 10.04 64 bit, the resxtop and ESXCLI commands do not work if you do not install the 32‐bit compatibility libraries. Installing the vCLI Package on a Linux System with Internet Access Install the vCLI package and run a command to verify installation was successful. To install vCLI 1 Log in as root. 2 Untar the vCLI binary that you downloaded. tar –zxvf VMware-vSphere-CLI-6.X.X-XXXXX.i386.tar.gz A vmware-vsphere-vcli-distrib directory is created. 3 (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= :port export ftp_proxy= :port 4 Run the installer: sudo vmware-vsphere-cli-distrib/vmware-install.pl 5 To accept the license terms, type yes and press Enter. The installer connects to CPAN and installs prerequisite software. Establishing a connection might take a long time. 6 On RHEL, when prompted to install precompiled Perl modules, type no and press Enter to use CPAN The installer connects to CPAN and installs prerequisite software. Establishing a connection might take a long time. 7 20 Specify an installation directory, or press Enter to accept the default, which is /usr/bin. VMware, Inc. Chapter 2 Installing vCLI A complete installation process has the following result: A success message appears. The installer lists different version numbers for required modules (if any). The prompt returns to the shell prompt. If you accepted the defaults during installation, you can find the installed software in the following locations: vCLI scripts – /usr/bin vSphere SDK for Perl utility applications – /usr/lib/vmware-vcli/apps vSphere SDK for Perl sample scripts – /usr/share/doc/vmware-vcli/samples 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. Uninstalling the vCLI Package on Linux You can use a script included in the installation to uninstall the vCLI package. To uninstall vCLI on Linux 1 Change to the directory where you installed vCLI (default 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. The vCLI installation package for Windows includes the ActivePerl runtime from ActiveState Software and required Perl modules and libraries. 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. To install the vCLI Package on Windows 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 the directory. The default location is C:\Program Files\VMware\VMware vSphere CLI. 6 VMware, Inc. Click Next. 21 Getting Started with vSphere Command-Line Interfaces 7 Click Install to proceed with the installation. The installation might take several minutes to complete. 8 Reboot your system. Without reboot, path settings might not be correct on your Windows platform. Uninstalling the vCLI Package on Windows You can uninstall the vCLI package as you would other programs. To uninstall vCLI on Windows 1 Find the option for adding and removing programs on the Windows operating system you are using. 2 In the panel that appears, select VMware vSphere CLI, and click Remove. 3 Click Yes when prompted. The system uninstalls the vSphere SDK for Perl, the vCLI, and all prerequisite software. Enabling Certificate Verification The vSphere SDK for Perl and vCLI use Crypt::SSLEay to support certificate verification. Crypt::SSLEay allows verification of certificates signed by a Certificate Authority (CA) if you set the following two variables: HTTPS_CA_FILE – The CA file. 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 print error or warning messages. Use HTTPS_DEBUG for troubleshooting before running vCLI commands. 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 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 a few tasks. The vSphere Management Assistant Guide discusses each task in detail. 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: 3 22 Network information (the default is often acceptable) Host name for vMA. 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. (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. 3f Running Host Management Commands in the ESXi Shell 3 In most cases, 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. You first establish access, and can then run commands. “ESXi Shell Access with the Direct Console” on page 23 “Remote ESXi Shell Access with SSH” on page 24 “Lockdown Mode” on page 26 “Running ESXCLI Commands in the ESXi Shell” on page 26 ESXi Shell Access with the Direct Console An ESXi system includes a Direct Console User Interface (DCUI) that allows you to start and stop the system and to perform a limited set of maintenance and troubleshooting tasks. The direct console allows access to 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: Local shell access allows you to log in to the shell directly from the Direct Console. See “Enabling Local ESXi Shell Access” on page 23. Remote shell (SSH) access allows you to connect to the host 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 24. 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. VMware recommends you 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. Enabling Local ESXi Shell Access You can enable the ESXi Shell from the direct console or from the vSphere Web Client or the vSphere Client. If you have access to the direct console, you can enable the ESXi Shell from there. To enable the ESXi Shell in the direct console 1 At the direct console of the ESXi host, press F2 and provide credentials when prompted. 2 Scroll to Troubleshooting Options and press Enter. VMware, Inc. 23 Getting Started with vSphere Command-Line Interfaces 3 Choose 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. If you do not have access to the Direct Console Interface, you can enable the ESXi Shell from the vSphere Web Client. To enable the ESXi Shell from the vSphere Web Client or the vSphere Client 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 To temporarily start or stop the service, click the Start or Stop button. To change the Startup policy across reboots, select Start and stop with host and reboot the host. Click OK. After you have enabled the ESXi Shell, you can use it from that monitor or 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. 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. 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, from the vSphere Web Client, or from the vSphere Client. See the vSphere Security document in the vSphere Documentation Center for detailed instructions. Using the 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. To use the local ESXi Shell 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 type the password, characters are not displayed on the console. 3 Enter shell commands to perform management tasks. 4 To log out, type exit in the shell. 5 To return to the direct console, type Alt‐F2. See 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. 24 VMware, Inc. Chapter 3 Running Host Management Commands in the ESXi Shell Enabling SSH for the ESXi Shell By default, remote command execution is disabled on an ESXi host, and you cannot log in to the host using a remote shell. You can enable remote command execution from the direct console or from the vSphere Web Client. To enable SSH access in the direct console 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 once. 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 screen. To enable SSH from the vSphere Client 1 Select the host and click the Configuration tab. 2 Click Security Profile in the Software panel. 3 In the Services section, click Properties. 4 Select SSH and click Options. 5 Change the SSH options. 6 To change the Startup policy across reboots, click Start and stop with host and reboot the host. To temporarily start or stop the service, click the Start or Stop button. Click OK. To enable SSH from the vSphere Web Client 1 Select the host, click Manage, and keep Settings selected. 2 Click Security Profile. 3 In the Services section, click Edit. 4 Select SSH. 5 To temporarily start or stop the service, click the Start or Stop button. To change the Startup policy across reboots, select Start and stop with host and reboot the host. Click OK. After you have enabled SSH, you log in to the ESXi Shell remotely and run ESXi Shell commands. Using the ESXi Shell with SSH If SSH is enabled on your ESXi host, you can run commands on that shell using an SSH client. To access the remote ESXi Shell 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 VMware, Inc. Provide credentials when prompted. 25 Getting Started with vSphere Command-Line Interfaces 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 finer grained management: 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. 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 using the Add Host wizard to add a host to vCenter Server, using the vSphere Web Client to manage a host, or using the Direct Console User Interface (DCUI). See the vSphere Security documentation for details on Lockdown Mode in vSphere 6.0. Running ESXCLI Commands in the ESXi Shell ESXCLI commands in the ESXi Shell are fully supported 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 23. To run an ESXCLI command in the shell 1 Log in to the shell. 2 Run the command. For example, to list NAS storage devices, run the following command. esxcli storage nfs list You can use --help at any level of esxcli for help on available namespaces, commands, or options. 26 VMware, Inc. 4f 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 the target server to run the command on. Users must authenticate to the host, and can only perform tasks that they are authorized to perform. NOTE See “Running DCLI Commands” on page 39 for information about DCLI commands, which you can use to manage vCenter Server services. This chapter includes the following topics: “Overview of Running vCLI Host Management Commands” on page 27 “Protecting Passwords” on page 28 “Authenticating Through vCenter Server and vCenter Single Sign‐On” on page 29 “Authenticating Directly to the Host” on page 30 “Trust Relationship Requirement for ESXCLI Commands” on page 33 “Common Options for vCLI Host Management Command Execution” on page 34 “Using vCLI Commands in Scripts” on page 36 “Running Host Management Commands from a Windows System” on page 37 “Running Host Management Commands from a Linux System” on page 37 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 32. 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, use vMA, or run scripts. 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 30. VMware, Inc. 27 Getting Started with vSphere Command-Line Interfaces Access the vMA Linux console. Set up target servers and run vCLI commands against the targets without additional authentication. 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 36. 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. Target 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. Specify the vCenter Single Sign‐On service with --psc and, if multiple vCenter Server systems are associated with the vCenter Single Sign‐On service, the vCenter Server system with --server. Specify also the host with --vihost. Specify the vCenter Server system with --server and the ESXi host with --vihost. Specify only the ESXi host with --vihost. 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 29. Protecting Passwords 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. 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 you type. For noninteractive use, you can create a session file using the save_session option. See “Using a Session File” on page 30. 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 29. Use variables or configuration files. If you are running 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. vCLI allows you to 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, not even the root user can run vCLI commands directly against ESXi hosts in lockdown mode. See “vCLI and Lockdown Mode” on page 32 and the vSphere Security documentation. 28 VMware, Inc. Chapter 4 Running vCLI Host Management Commands Order of Precedence for vCLI Host Management Commands When you run a vCLI host management command, authentication happens in the order of precedence shown in Table 4‐1. 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 43. 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. Table 4-1. vCLI Authentication Precedence Authentication Description See Command line Password (--password), session file (--sessionfile), or configuration file (--config) specified on the command line. “Using a Session File” on page 30 Environment variable Password specified in an environment variable. “Using Environment Variables” on page 30 Configuration file Password specified in a configuration file. “Using a Configuration File” on page 31 Current account (Active Directory) Current account information used to establish an SSPI connection. Available only on Windows. “Using Microsoft Windows Security Support Provider Interface” on page 32 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. Authenticating Through vCenter Server and vCenter Single Sign-On For all ESXi hosts that are managed by a vCenter Server system that is integrated with vCenter Single Sign‐On 6.0 and later, you can authenticate directly to the vCenter Server system, or you can authorize to vCenter Server through vCenter Single Sign‐On. Best practice is to authenticate through vCenter Single Sign‐On. The vCenter Single Sign‐On service is included in the Platform Services Controller. The Platform Services Controller can be embedded in your vCenter Server installation, or one Platform Services Controller can handle authentication, certificate management, and some other tasks for multiple vCenter Server systems. NOTE You cannot use this approach if vCenter Server is integrated with vCenter Single Sign‐On 5.0. You use the --psc option and, optionally, the --server option. psc ‐ Specifies the Platform Services Controller instance associated with the vCenter Server system that manages the host. server ‐ Specifies the vCenter Server system that manages the host. Required if the Platform Services Controller instance is associated with more than one vCenter Server system. vihost ‐ Specifies the ESXi host, as in earlier versions of vCLI. Examples vicfg-nics -l --username --password " " --server --psc --vihost esxcli --server --vihost --username --password --psc 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 this command: VMware, Inc. 29 Getting Started with vSphere Command-Line Interfaces vicfg-nics -l --username --password " " --server --psc --vihost 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. Using a Session File You can create a session file with the save_session script. The script is in the /apps/session directory of the vSphere SDK for Perl, which is included in the vCLI package. You can use the session file, which does not reveal password information, when you run vCLI commands. If the session file is not used for 30 minutes, it expires. If you use a session file, other connection options are ignored. To create and use a session file 1 Connect to the directory where the script is located. For example: 2 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 to connect to and the name of a session file in which the script saves an authentication cookie. save_session --savesessionfile --server For example: Windows: save_session.pl --savesessionfile C:\Temp\my_session --server my_server --username --password Linux: save_session --savesessionfile /tmp/vimsession --server --username --password If you specify a server, but no user name or password, the script prompts you. 3 When you run vCLI commands, pass in the session file using the --sessionfile option. --sessionfile For example: Windows: esxcli --sessionfile C:\Temp\my_session network ip interface list vicfg-mpath.pl --sessionfile C:\Temp\my_session --list Linux: esxcli --sessionfile /tmp/vimsession network ip interface list vicfg-mpath --sessionfile /tmp/vimsession --list Using Environment Variables On Linux, you can set environment variables in a Linux bash profile or on the command line by using a command like the following: export VI_SERVER= 30 VMware, Inc. Chapter 4 Running vCLI Host Management Commands 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= IMPORTANT Do not use escape characters in environment variables. See “Using vCLI Commands in Scripts” on page 36 for an environment variable example. Using a Configuration File You can use a text file that contains variable names and settings as a configuration file. Variables corresponding to the options are shown in Table 4‐2, “vCLI Connection Options,” on page 34. CAUTION Limit read access to a configuration file that contains user credentials. Pass in the configuration file when you run vCLI commands, as follows: --config
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.6 Linearized : No Language : en XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:08:04 Creator Tool : FrameMaker 11.0 Modify Date : 2015:06:16 15:51:44+03:00 Create Date : 2015:06:16 15:40:07Z Metadata Date : 2015:06:16 15:51:44+03:00 Format : application/pdf Title : Getting Started with vSphere Command-Line Interfaces Creator : VMware Inc. Description : Overview of command-line interfaces. Information on installing vCLI and running vCLI commands. Producer : Acrobat Distiller 9.5.5 (Windows) Keywords : vSphere CLI, vCLI, vMA, esxcli, vicfg- commands Document ID : uuid:8cf18c90-ff5f-4e32-b6d4-4c2aa0d87443 Instance ID : uuid:2b957b54-4b55-467c-99c8-d311fd225686 Page Layout : SinglePage Page Mode : UseOutlines Page Count : 46 Author : VMware Inc. Subject : Overview of command-line interfaces. Information on installing vCLI and running vCLI commands.EXIF Metadata provided by EXIF.tools