VMware vSphere PowerCLI

VMware vSphere PowerCLI extends PowerShell with cmdlets specifically for managing VMware servers. PowerCLI includes more cmdlets than PowerShell itself ships with, giving administrators broad access to VMware’s internals. The downside of this wealth of tools is that it’s easy to get lost inside PowerCLI if you don’t start with specific goals in mind.

In this article, I walk through an entire PowerCLI working session that includes connecting to a server, performing some basic monitoring and management tasks, and disconnecting. The steps for using PowerCLI are always basically the same, so my example not only provides you with a framework for understanding PowerCLI but also demonstrates essential PowerCLI features. I also direct you to some of the most useful resources for discovering how to use PowerCLI for more specific tasks.

Prerequisites

To manage a VMware environment with PowerShell, your environment must meet three requirements. First, you need to have a VMware server environment available. VMware PowerCLI works with VMware ESX or ESXi 3.0 and later, as well as any VMware Server, VMware vCenter Server, or VMware vSphere product, version 2 or later.

Second, you need a workstation with PowerShell 2.0 installed; this is where you’ll install PowerCLI. As of press time, the current version of VMware vSphere PowerCLI is 4.1.1. To get the installation package, go to the VMware vSphere PowerCLI homepage. Alternatively, you can go to the VMware Download Center and search for PowerCLI. If you haven’t already registered with VMware, you’ll need to do so—the download is free. Please be aware that there’s a similarly named but distinct product: vSphere CLI. Although vSphere CLI also allows command-line VMware management, vSphere CLI is a traditional console application, not the PowerShell toolkit. Make sure you download PowerCLI.

The third requirement is that you need access to the VMware server from the workstation you’ll use for management. This might seem self-evident, but I mention it separately because there’s minimal work for remote access to a VMware server. If you have access to the VMware server’s network via VPN or similar technology, there’s nothing specific you need to configure for access; you simply need to connect to the server’s network. If you don’t have VPN access but can configure port forwarding on the router for the VMware server’s network, log on to the router and forward a port on the public side of the router to the VMware server’s management port (443 by default). You can then use the public IP address or DNS name of the network and the public port number to connect to the server.

Loading PowerCLI

In general, you don’t need to worry about the details of loading PowerCLI. The VMware PowerCLI installer provides you with a startup shortcut on the Start menu under VMware, VMware vSphere PowerCLI. When you start PowerShell from that shortcut, PowerShell automatically runs a configuration script that loads the PowerCLI snap-in (among other things). If you always use the VMware PowerCLI shortcut to start a PowerCLI session, you can skip to the next section.

If not using the shortcut, you can load the PowerCLI snap-in directly at a PowerShell prompt; you just need to know its name (i.e., VMware.VimAutomation.Core). Use this name with PowerShell’s Add-PSSnapin cmdlet, like this:

Add-PSSnapin VMware.VimAutomation.Core

PowerShell will automatically find the snap-in and load it for you. This works from a script as well. If you try to use this command on a machine without PowerCLI installed, you’ll get an error message similar to this: “The Windows PowerShell snap-in ‘VMware.Vim.Automation.Core’ is not installed on this machine.” (As an aside for scripters, after running this command you can see if it succeeded by checking the value of the $? variable; it will be false if the snap-in didn’t load.)

If you’re loading the snap-in yourself instead of using the PowerCLI shortcut, I suggest that you at least glance at the configuration script. This script, Initialize-PowerCLIEnvironment.ps1, is in PowerCLI’s installation folder. Beyond loading the snap-in and customizing the PowerShell interface, the configuration script also defines several PowerCLI-specific aliases and functions.

Connecting to a VMware Server

After you start the Power CLI session, use the Connect-VIServer cmdlet to connect to the VMware server you’re managing. This step is typically very simple; you just use the Connect-VIServer cmdlet with the server name or address:

Connect-VIServer -Server 192.168.1.21

PowerShell will then prompt you for credentials to let you connect to the VMware server using a standard PowerShell credentials dialog such as the one that Figure 1 shows.

Figure 1: Entering PowerShell credentials

There’s one situation in which this approach might not work. Suppose you’re tunneling through the Internet to the remote VMware server. The best standard solution to this problem isn’t to do something with PowerCLI, but to set up a secure VPN to the remote site. If that’s not an option, however, you can handle it with some router reconfiguration and the Connect-VIServer cmdlet.

Configure the remote site’s router to forward an available port on its Internet side to port 443 on the VMware server on the private side. Connect-VIServer lets you specify an alternative port for situations like this.

As an example, suppose the VMware server is on a remote LAN. Because that LAN also has a mail server, there’s a well-known name we can use to get to the router: mail.net.test. After connecting to the router and setting it to forward port 51234 on the outside to the VMware server’s port 443, we’d use Connect-VIServer like this:

Connect-VIServer -Server mail.net.test -Port 51234

At this point, we’re ready to actually do something on a VMware server. In the next few sections we’ll examine some basic tasks that are particularly useful or that provide a foundation for understanding more of the VMware infrastructure.

Checking Health and Performance

PowerCLI has a handful of cmdlets for quickly inspecting server logs and current statistics. The cmdlet for accessing logs is simply named Get-Log. However, you’ll typically need to use the Get-LogType cmdlet first.

The reason for this is that VMware servers don’t have a static set of logs. ESX and ESXi servers have a restricted set of logs because there are fewer core services on them compared with a full vSphere server, and even those logs exist in multiples because VMware rotates log files and retains backups. In the simplest case, you’ll have a short collection (like the one in Figure 2, from an ESXi server). To get only the hostd log entries, you’d use the command

Get-Log -Key hostd

Figure 2: ESXi server logs

PowerCLI returns this as a blob of entry values, so to see the literal text in the hostd log, you need to expand the returned Entries value. You can expand Entries like this:

(Get-Log -Key hostd).Entries

In fact, if you really want to get all the existing log entries, no matter how many logs or entries there are, you can pipe Get-LogType into Get-Log and expand the entries for each log:

Get-LogType | Get-Log | ForEach-Object \{ $_.Entries\}

However, this can be very resource intensive, particularly for the server—and especially if you’re looking at an ESX or ESXi server. If you won’t be prefiltering the log entries and are really using this approach to get an idea of what’s going on with a server overall, it might be better to use Get-Log’s bundling feature. It will take as long as displaying the logs interactively, but you only have to do it once. Furthermore, this technique will also give you a complete set of server configuration files. All you need to do is run Get-Log with the Bundle parameter and specify a path on your local machine where you want to save the logs. This path must already exist; if you want to save the log bundle to C:tmpServer1, you must create the folder C:tmpServer1 yourself. The command you’d use looks like this:

Get-Log -Bundle -DestinationPath c:tmpServer1

When PowerCLI finishes bundling the logs and saving them, it returns a file name for the archive where they’re stored. This is a standard zip file if you’re using vCenter. Because ESX and ESXi servers use standard Linux infrastructure tools, the archive will be a tarred and gzipped file, with a .tgz extension; you can open these archives with WinZip or 7-Zip.

The log files give you information about significant events (and about machine configuration, if you use the Bundle feature). In contrast, you can use the Stat cmdlets to get statistics that give you a feel for system performance.

VMware servers automatically monitor a range of performance statistics for servers, virtual machines (VMs), resource pools, clusters, and hosts. We’ll look at the nonserver entities in the next section because you need to get references to those entities to look at their statistics. For the currently connected server, however, you don’t need to do anything complicated to find out what statistics VMware tracks. To see the statistic types, just enter the command

Get-StatType

This command returns a list of the names or MetricIds of statistical quantities that VMware tracks. This list can be overwhelming, particularly because the list can contain duplicates. You can get a clean listing by using

Get-StatType | Sort-Object -Unique

Figure 3 shows the initial output from this command; although still lengthy, the list is abbreviated and alphabetized. You can use one or more of these names, or a wildcard variant with Get-Stat, to retrieve server statistics. Either of the following is a legitimate statistic name specification:

Get-Stat -Stat cpu.usage.average
Get-Stat -Stat cpu.u*.average

Figure 3: List of statistic types

Get-Stat is useful without enumerating statistic types, however. You can simply enter

Get-Stat

to retrieve core CPU, disk, memory, and network usage statistics for the server.

Listing Virtual Machines

You can use a simple command to register VMs on a VMware server. To retrieve every VM registered on the currently connected server, whether running or not, use the command

Get-VM

This command returns a list of VMware machine objects; the default display will show each machine’s name, PowerState, CPU count, and memory size. The Get-VM cmdlet supports several parameters you can use to filter the output. The one I most commonly use is the Name parameter. You can specify single or multiple names, possibly containing wildcard values. The following command will return all the VMs whose names begin with either XP or Vista:

Get-VM -Name XP*,Vista*

The Name parameter is useful for returning all machines in an installation, or a handful based on name pattern. However, if you work with a sizable VMware infrastructure, you should explore the other parameters for Get-VM in the Help documentation; you can filter the data returned against one or more specific data stores, data centers, folders, or clusters.

Creating New Machines, Clones, and Snapshots

Machine population management is a huge topic. However, some basic cases are simple to demonstrate (and are in the Help documentation as well, along with cases that are more complex).

When setting up new production VMs, I usually start from a template. All you need is the template name and name for the new machine. Working from the Windows XP Professional VMware template named XppTemplate and creating a new guest named Xpp05 works like this:

New-VM -Template XppTemplate -Name Xpp05

Cloning uses the New-VM cmdlet as well, only you specify an existing VM rather than a template. This will be a full copy of the original system (there’s no way to create a linked clone via cmdlets). To clone the VM named Xpp05 to a new test system named XpTesting, use this command:

New-VM -VM Xpp05 -Name XpTesting

Finally, to take an immediate snapshot of XpTesting so I can roll back to it if necessary, I use New-Snapshot:

New-Snapshot -VM XpTesting -Name Creation

This command creates a snapshot named Creation.

Cycling Virtual Machines

VMware has cmdlets for managing machine states. For most of them, you can only perform the tasks gracefully if you installed VMware Tools within the VM.

To start a VM, use the Start-VM cmdlet. You can start the machine Xpp05 like this:

Start-VM -VM Xpp05

The other operations are where VMware Tools makes a difference. Without VMware Tools installed on the guest OS, you would restart, suspend, or shut down Xpp05 with the following commands:

Restart-VM -VM Xpp05
Suspend-VM -VM Xpp05
Stop-VM -VM Xpp05

If you do have VMware Tools installed on the guest, VMware can tell the OS to initiate the changes instead of forcing them. To restart, suspend, or shut down the commands via VMware Tools, you would use the following commands:

Restart-VMGuest -VM Xpp05
Suspend-VMGuest -VM Xpp05
Shutdown-VMGuest -VM Xpp05

Be warned: Although the VMGuest cmdlets are polite to the guest OS, they don’t warn connected users about state changes. If you shut down running machines with any of these cmdlets, an interactive user will either see what looks like an unstoppable OS shutdown (with Shutdown-VMGuest) or will simply see the session disappear (if using Stop-VM).

Moving Running Virtual Machines

If you have multiple VMware servers, it’s possible to move running VMs in correctly configured shared storage from one server to another using VMware VMotion. Suppose you have a VM named XP17 on VMware host VH1. You have a connection to server VH1, and you need to move XP17 to VMware host VH2. All you need to do is get the VM object, then use that object and the target host address to make the move, like this:

Move-VM -Destination VH2 -VM XP17

Suppressing Confirmations for PowerCLI Cmdlets

If you’ve stepped through at least a few of the PowerCLI examples here, you’ve probably noticed that when you do something that could affect either your connection to a VMware server or a user’s session on a machine, the PowerCLI cmdlet you’re using will give you a confirmation prompt. This can get irritating in scripts if you need them to run even partially unattended.

For any cmdlet that has confirmation prompts, you can suppress the prompts if you explicitly set the Confirm parameter to false. You need to know one detail in order to use Confirm this way; you must join the parameter name to the $false value with a colon (:) so it looks like -Confirm:$false. For example, to suppress Restart-VMGuest’s confirmation prompt, you need to use it like this:

Restart-VMGuest -VM Xpp05 -Confirm:$false

This is necessary because the Confirm parameter is a switch parameter. The name by itself with no argument tells PowerShell that you want a confirmation prompt. By using the colon you explicitly tell PowerShell that the value after the colon is an argument to the parameter.

Disconnecting from the Server

A last step that’s valuable in scripts—and in interactive PowerCLI sessions if you’re trying to work as cleanly as possible—is to shut down the server connection explicitly. Just use

Disconnect-VIServer

When you do this, the current server connection will be closed.

Although PowerShell and VMware will eventually clean up connections anyway without this step, I strongly recommend getting in the habit of using it, particularly in scripts designed to perform complete tasks on a server. Explicitly closing the connection does release resources immediately and reduces the risk of accidentally misapplying operations to the wrong server.

Getting Help: PowerCLI Resources

Although we’ve stepped through a complete VMware administration session, we’ve only touched on a handful of the simpler cmdlets you can use and very few of the tasks you can accomplish in PowerCLI. Several resources can help you get up to speed with using PowerCLI quickly.

PowerCLI’s cmdlets are documented internally just as the native PowerShell cmdlets are, so you can use Get-Help and Get-Command to explore the cmdlets in general or specifically from within a PowerCLI session. PowerCLI also provides the analogous PowerCLI-specific commands Get-VICommand and Get-PowerCLIHelp.

The standard PowerCLI installation includes references that you can use outside of PowerCLI. If you look in the Start menu’s VMware vSphere PowerCLI folder, you’ll find a link to a Windows Help file called vSphere PowerCLI Cmdlets Reference; this is a searchable graphical interface version of the console-based cmdlet help. In the same location you can also find the PDF-based vSphere PowerCLI Administration Guide, which provides an extended walkthrough of using PowerCLI.

Finally, there’s a dynamic and extremely helpful PowerCLI user community. PowerCLI itself also contains a Get-PowerCLICommunity cmdlet that automatically opens a browser window on this community site. Both user community experts and VMware developers participate in the community’s web-based discussions; the site also features a growing collection of scripts and other useful PowerCLI documents.