Using PowerShell and PowerCLI to work with host servers

Learn how to query your VMware host servers with this PowerShell Primer.

It is time for another PowerCLI tip! PowerCLI, you may recall, is a snap-in created for the Windows PowerShell...

scripting language. This snap-in enables you to quickly and easily automate all aspects of your vSphere environment. Today's article is about host servers.

Other PowerShell tips

VMware vSphere PowerCLI: Learn it, love it

Mastering PowerCLI: Using Get-VM to work with virtual machines

A host server in VMware parlance is the system which provides the virtualization services. It's also known as the hypervisor, which in this case is VMware or of course, ESX Server. PowerCLI can manage all versions of ESX server, starting with 3.0, and including the "thin" version known as ESXi version. At one point in time, you could use PowerCLI to manage VMware Server (the non-bare-metal hypervisor), but that feature went away for some strange reason.

Anyway, moving on -- let's talk about what you can do with host servers using PowerCLI. As of this writing, the shipping version of PowerCLI is 4.0 Update 1. This particular version was a huge upgrade from past versions, and one way to measure that is by looking at the list of cmdlets which are included. (PowerShell cmdlets are roughly analogous to internal commands in other command-shells such as cmd.exe or bash.)

Here is a one-liner in PowerShell which lists just the PowerCLI cmdlets which have the word "host" in the name: 

(Note that "PS >" indicates the shell prompt, and the text that immediately follows is what I typed. Everything else is output from a previously typed command.)


PS > get-command *host* -pssnapin vmware* | format-wide

Add-VMHost                                   Add-VmHostNtpServer
Apply-VMHostProfile                          Export-VMHostProfile
Get-VMHost                                   Get-VMHostAccount
Get-VMHostAdvancedConfiguration              Get-VMHostAvailableTimeZone
Get-VMHostDiagnosticPartition                Get-VMHostFirewallDefaultPolicy
Get-VMHostFirewallException                  Get-VMHostFirmware
Get-VMHostHba                                Get-VMHostModule
Get-VMHostNetwork                            Get-VMHostNetworkAdapter
Get-VMHostNtpServer                          Get-VMHostProfile
Get-VMHostService                            Get-VMHostSnmp
Get-VMHostStartPolicy                        Get-VMHostStorage
Get-VMHostSysLogServer                       Import-VMHostProfile
Install-VMHostPatch                          Move-VMHost
New-VMHostAccount                            New-VMHostNetworkAdapter
New-VMHostProfile                            Remove-VMHost
Remove-VMHostAccount                         Remove-VMHostNetworkAdapter
Remove-VMHostNtpServer                       Remove-VMHostProfile
Restart-VMHost                               Restart-VMHostService
Set-VMHost                                   Set-VMHostAccount
Set-VMHostAdvancedConfiguration              Set-VMHostDiagnosticPartition
Set-VMHostFirewallDefaultPolicy              Set-VMHostFirewallException
Set-VMHostFirmware                           Set-VMHostHba
Set-VMHostModule                             Set-VMHostNetwork
Set-VMHostNetworkAdapter                     Set-VMHostProfile
Set-VMHostService                            Set-VMHostSnmp
Set-VMHostStartPolicy                        Set-VMHostStorage
Set-VMHostSysLogServer                       Start-VMHost
Start-VMHostService                          Stop-VMHost
Stop-VMHostService                           Suspend-VMHost
Test-VMHostProfileCompliance                 Test-VMHostSnmp

That's sixty cmdlets! Unfortunately, I won't be able to go into detail on each cmdlet, but we can hit several of the most important ones. Also, don't forget that each cmdlet in PowerShell has built-in help. To access it, type "get-help", followed by the cmdlet name, or just the cmdlet name followed by "-?".

The first cmdlet that I'd like to talk about is Get-VMHost. As with all get-cmdlets, (if you'll allow me to coin that term), the point is to retrieve objects from a container. If you connect to a vCenter server with the Connect-VIServer cmdlet, and then run Get-VMHost by itself, then the results might look something like this:

PS > Connect-VIServer vlab.halr9000.com

Name                          Port                          User
----                          ----                          ----
vlab.halr9000.com             443                           hal

PS > Get-VMHost

Name            State      PowerState      Id CpuUsage CpuTotal  Memory  Memory
                                                   Mhz      Mhz UsageMB TotalMB
----            -----      ----------      -- -------- -------- ------- -------
atlesx01.hal... Connected  PoweredOn  ...-232      168     8000    2295    4094
atlesx02.hal... Connected  PoweredOn  ...-225      366     8000    2645    4094
atlesx03.hal... Connected  PoweredOn  ...t-10      350     8000    3264    4091

If you don't own a copy of vCenter, don't worry, you can still get a lot out of PowerCLI. In fact, PowerCLI will enable you to manage multiple ESX servers at once even without vCenter.

The Connect-VIServer command looks a little different, but the end result is very similar. (Sorry -- —no vMotion or templates, you still need vCenter for those features!)

Let's analyze the output you see above, and then we'll move on to some other ways to use this cmdlet. There are two commands executed here. The first is to establish the connection to my vCenter server. The second is simply running Get-VMHost by itself with no parameters. By doing so, you will see a list of all of the host servers (ESX or ESXi) which are connected to the vCenter. The output table has several columns indicating things like the server name, the connection status, and the power state. Following an informational ID field, you see four statistics which enable you to quickly gauge your system health.

Like most objects in PowerShell, there is more there than immediately meets the eye. For example, let's have a look at some other useful fields:

PS > get-vmhost | format-table name, manufacturer, model, numcpu, version, build -autosize

Name                Manufacturer          Model              Num Cpu Version Build
-----------------      ---------       ----------------    --------- ---------- --------
atlesx01.halr9000.com  Dell Inc.        PowerEdge SC1435      4       4.0.0   208167
atlesx02.halr9000.com  Dell Inc.        PowerEdge SC1435      4       4.0.0   219382
atlesx03.halr9000.com  Dell Inc.        PowerEdge SC1435      4       4.0.0   219382

So this begs the question: how do you know what fields are available in an object? Well, first I'll remind you that in PowerShell, everything is an object. Objects consist of members, and members can include properties and methods. Properties correspond to the field names you see in output like the table above. Methods are a topic for another article, but in short, they define the things you can do to an object -- —the actions.

Back to properties., here is a great way to list all of them. Note the use of the Format-Wide cmdlet to pack the names into two nice columns.

PS > get-vmhost | get-member -MemberType property | format-wide

Build                                        ConnectionState
CpuTotalMhz                                  CpuUsageMhz
CustomFields                                 HyperthreadingActive
Id                                           Manufacturer
MemoryTotalMB                                MemoryUsageMB
Model                                        Name
NumCpu                                       ParentId
PowerState                                   ProcessorType
State                                        TimeZone
Version                                      VMSwapfileDatastoreId

You can use the Name parameter on the Get-VMHost cmdlet to restrict the output to only those servers which match, —and you can use wildcards. And because of the way PowerShell's pipeline works, you can pass a VMHost object as input to the Get-VM cmdlet. The end result will show you a list of the virtual machines (VMs) which reside on the specified host server (or servers, if the wildcard matches more than one). For example:

PS > get-vmhost -name atlesx01* | get-vm

Name                 PowerState Num CPUs Memory (MB)
--------            ----------------- ------ --------  ------------------
ELGFIL01             PoweredOn  1        384
VMGVIC01             PoweredOn  1        512
VMGADC01             PoweredOn  1        384
VMGADC02             PoweredOn  1        384
ELGADC01             PoweredOn  1        512

I am going to end this tip by showing you how to work with the host server firewall. You can list firewall exceptions by using the Get-VMHostFirewallException cmdlet. If you type that cmdlet without any parameters you'll get an error because you must specify the host server to query. Here's how you do so:

PS > $vmhost = get-vmhost atlesx01*
PS > Get-VMHostFirewallException -Name 'FTP Server' -VMHost $vmhost

Name                 Enabled IncomingPorts  OutgoingPorts  Protocols  ServiceRunning
--------            ------------ --------------------  --------------------  -------------  --------------
FTP Server           False   21                            TCP

In this example I am also filtering the output by specifying the name of a firewall rule. If I left off the bit about FTP, then you would see a long list of all of the rules.

Once you know how to grab the firewall configuration, it is an easy thing to change it with the Set-VMHostFirewallException cmdlet. This cmdlet has two parameters:


  • Exception: This corresponds to the firewall rule to change. This parameter can be specified on the pipeline.
  • Enabled: This is a Boolean flag which if true, will enable the rule (thus poking a hole in the firewall). Setting this to false will disable the rule and close any corresponding ports.

Here is an example of enabling the FTP server firewall rule:

PS > $ftp = Get-VMHostFirewallException -Name 'FTP Server' -VMHost $vmhost
PS > $ftp | Set-VMHostFirewallException -Enabled:$true

Name                 Enabled IncomingPorts  OutgoingPorts  Protocols  ServiceRunning
--------            ------------ --------------------  --------------------  -------------- ---------------------
FTP Server           True    21                            TCP


Hal Rottenberg Hal Rottenberg is a Microsoft PowerShell MVP and VMware vExpert living in Woodstock, Georgia. He is well-known in system administrator circles for co-hosting the PowerScripting Podcast and heading up the PowerShellCommunity organization. He is also the author of a book titled "Managing VMware Infrastructure with PowerShell: TFM published by SAPIEN Press in 2009.

Next Steps

More resources on PowerShell and PowerCLI

VMware vSphere PowerCLI FAQ

Mastering PowerCLI commands to control VMware vCloud and vSphere

Managing VMware View 4.5 virtual desktops with PowerCLI

Dig Deeper on Scripting administrative tasks