Learning PowerCLI - Second Edition

You can install VMware PowerCLI 6.5 Release 1, the version used for writing this book, on the following 64-bit operating systems:

VMware PowerCLI 6.5 Release 1 is compatible with the following PowerShell versions:

If you want to work with VMware PowerCLI 6.5 Release 1, make sure that the following software is present on your system:

Before you can install PowerCLI, you have to download the PowerCLI installer from the VMware website. You will need a My VMware account to do this.

Perform the following steps to download PowerCLI:

Perform the following steps to install PowerCLI:

After installing PowerCLI, you will have a VMware PowerCLI icon on your desktop. If you installed PowerCLI on a 64-bit computer, you will also have a VMware PowerCLI (32-Bit) icon. Some PowerCLI commands only work in the 32-bit version of PowerCLI. So keep both versions.

If you are not connected to a vCenter or an ESXi server, you will get an error message if you try to run a PowerCLI cmdlet. Let's try to retrieve a list of all of your data centers using the following command:

PowerCLI C:\> Get-Datacenter

The output of the preceding command is as follows:

Get-Datacenter : 1/7/2017 1:37:17 PM    Get-Datacenter        You are
    not currently connected to any servers. Please connect first using a
    Connect cmdlet.
At line:1 char:1
+ Get-Datacenter
+ ~~~~~~~~~~~~~~
    + CategoryInfo          : ResourceUnavailable: (:) [Get-
                                  Datacenter], ViServerConnectionException
    + FullyQualifiedErrorId : Core_BaseCmdlet_NotConnectedError, 
                                  VMware.VimAutomation.ViCore.Cmdlets.
                                  Commands.GetDatacenter

You can see that this gives an error message. You first have to connect to a vCenter Server or an ESXi server using the Connect-VIServer cmdlet. If you have a vCenter Server, you only need to connect to the vCenter Server and not to the individual ESXi servers. It is possible to connect to multiple vCenter Servers or ESXi servers at once. The Connect-VIServer cmdlet has the following syntax. The syntax contains two parameter sets. The first parameter set is the default:

Connect-VIServer [-Server] <String[]> [-Port <Int32>] [-Protocol
    <String>] [-Credential <PSCredential>] [-User <String>] [-Password
    <String>] [-Session <String>] [-NotDefault] [-SaveCredentials]
    [-AllLinked] [-Force] [<CommonParameters>]

In the Default parameter set, the -Server parameter is required. The second parameter set can be used to select a server from a list of recently connected servers:

Connect-VIServer -Menu [<CommonParameters>]

In the Menu parameter set, the -Menu parameter is required. You cannot combine parameters from the Default parameter set with the Menu parameter set.

Let's first try to connect to a vCenter Server with the following command:

PowerCLI C:\> Connect-VIServer -Server 192.168.0.132

192.168.0.132 is the IP address of the vCenter Server in my home lab. Replace this IP address with the IP address or DNS name of your vCenter or ESXi server.

The preceding command will pop up a window in which you have to specify server credentials to connect to your server if your Windows session credentials don't have rights on your server. Enter values for User name and Password and click on OK.

If you specified valid credentials, you would get output similar to the following:

Name                           Port  User
----                           ----  ----
192.168.0.132                  443   root

You can also specify a username and password on the command line as follows:

PowerCLI C:\> Connect-VIServer -Server 192.168.0.132 -User admin
    -Password pass

You can also save the credentials in a variable with the following command:

PowerCLI C:\> $Credential = Get-Credential

The preceding command will pop up a window in which you can type the username and password.

You can now use the $Credential variable to connect to a server using the -Credential parameter, as follows:

PowerCLI C:\> Connect-VIServer -Server 192.168.0.132 -Credential
    $Credential

You can also use the PowerCLI credential store. This will be discussed in the  Using the credential store section, later in this chapter.

The default protocol that the Connect-VIServer cmdlet uses is HTTPS. If you want to make a connection with the HTTP protocol, you can do that with the following command:

PowerCLI C:\> Connect-VIServer -Server 192.168.0.132 -Protocol HTTP

If you have multiple vCenter Servers in Linked Mode, you can use the Connect-VIServer -AllLinked parameter to connect all of these vCenter Servers at once, as follows:

PowerCLI C:\> Connect-VIserver -Server 192.168.0.132 -Credential
    $Credential -AllLinked

The Connect-VIServer -Menu command gives you a list of previously connected servers from which you can pick one, as shown in the following command line:

PowerCLI C:\> Connect-VIServer -Menu
Select a server from the list (by typing its number and pressing
    Enter):
[1] 192.168.0.132 
[2] 192.168.0.133

Type the number of the server you want to connect to.

It is possible in PowerCLI to connect to multiple servers at once. You can do this by specifying more than one server, as follows:

PowerCLI C:\> Connect-VIServer -Server vCenter1,vCenter2

The first time you try to do this, you will get the following message:

Working with multiple default servers?


        Select [Y] if you want to work with more than one default
servers. In this case, every time when you connect to a different
server using Connect-VIServer, the new server connection is stored in
 an array variable together with the previously connected servers.
When you run a cmdlet and the target servers cannot be determined
from the specified parameters, the cmdlet runs against all servers
stored in the array variable.
    Select [N] if you want to work with a single default server. In
this case, when you run a cmdlet and the target servers cannot be
determined from the specified parameters, the cmdlet runs against the
 last connected server.

        WARNING: WORKING WITH MULTIPLE DEFAULT SERVERS WILL BE ENABLED BY
 DEFAULT IN A FUTURE RELEASE. You can explicitly set your own
preference at any time by using the DefaultServerMode parameter of
Set-PowerCLIConfiguration.

     [Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):

Press Enter or type Y to work with multiple default servers.

As the message says, you can always connect to multiple servers, but your commands will only work against the last server you connected to unless you have enabled working with multiple servers.

You can see the current value of DefaultVIServerMode with the Get-PowerCLIConfiguration cmdlet:

PowerCLI C:\> Get-PowerCLIConfiguration


    Scope    ProxyPolicy     DefaultVIServerMode InvalidCertificateAction
-----    -----------     ------------------- ------------------------
Session  UseSystemProxy  Multiple            Unset
User                     Multiple
AllUsers

If you want to change DefaultVIServerMode from single to multiple, you can do that with the Set-PowerCLIConfiguration cmdlet. This cmdlet has the following syntax:

Set-PowerCLIConfiguration [-ProxyPolicy <ProxyPolicy>]
    [-DefaultVIServerMode <DefaultVIServerMode>] [-InvalidCertificateAction 
    <BadCertificateAction>] [-ParticipateInCeip <Boolean>]
    [-CEIPDataTransferProxyPolicy <ProxyPolicy>] [-
    DisplayDeprecationWarnings <Boolean>] [-WebOperationTimeoutSeconds
    <Int32>] [-VMConsoleWindowBrowser <String>] [-Scope
    <ConfigurationScope>] [-WhatIf] [-Confirm] [<CommonParameters>]

You can change DefaultVIServerMode from single to multiple with the following command:

PowerCLI C:\> Set-PowerCLIConfiguration -DefaultVIServerMode Multiple
    -Scope User

All of the servers that you are currently connected to are stored in the variable $global:DefaultVIServers. If DefaultVIServerMode is set to multiple, your PowerCLI cmdlets will run against all servers stored in the $global:DefaultVIServers variable.

The last server you are connected to is stored in the variable $global:DefaultVIServer. If DefaultVIServerMode is set to single, your PowerCLI cmdlets will only run against the server stored in the $global:DefaultVIServer variable.

If your vCenter Server does not have valid server certificates, the Connect-VIserver cmdlet will display some warning messages, as shown in the following screenshot:

It is a good practice to supply your vCenter Server and ESXi servers with certificates signed by a certificate authority (CA). You can find information on how to do this in the VMware Knowledge Base article, Replacing default certificates with CA signed SSL certificates in vSphere 6.x (2111219) at http://kb.vmware.com/kb/2111219.

If you don't have valid certificates, you can suppress the warning messages using the Set-PowerCLIConfiguration cmdlet with the following command:

PowerCLI C:\ > Set-PowerCLIConfiguration -InvalidCertificateAction
    Ignore

The preceding command will modify InvalidCertificationAction in the AllUsers scope. You have to run this command using the Run as Administrator PowerCLI session. Otherwise, you will get the following error message:

Set-PowerCLIConfiguration : Only administrators can change settings for
    all users.
At line:1 char:1
+ Set-PowerCLIConfiguration -InvalidCertificateAction Ignore
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:)
                                  [Set-PowerCLIConfiguration],
                                  InvalidArgument
    + FullyQualifiedErrorId : VMware.VimAutomation.ViCore.Types.V1.
                                  ErrorHandling.InvalidArgument, VMware.
                                  VimAutomation.ViCore.Cmdlets.Commands.
                                  SetVIToolkitConfiguration

To disconnect from a vSphere server, you have to use the Disconnect-VIServer cmdlet. The Disconnect-VIServer cmdlet has the following syntax:

Disconnect-VIServer [[-Server] <VIServer[]>] [-Force]
    [-WhatIf] [-Confirm] [<CommonParameters>]

To disconnect all of your server connections, type the following command:

PowerCLI C:\> Disconnect-VIServer -Server * -Force

The output of the preceding command is as follows:

Confirm
Are you sure you want to perform this action?
Performing operation "Disconnect VIServer" on Target "User: 
    VSPHERE.LOCAL\Administrator, Server: 192.168.0.132, Port: 443".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend
    [?]  Help (default is "Y"):

Type Y or Enter to disconnect from the server.

If you don't want to be prompted with Are you sure you want to perform this action?, you can use the -Confirm:$false option as follows:

PowerCLI C:\> Disconnect-VIServer -Server * -Force
    -Confirm:$false

It may be that you want to disconnect only one session and not all. In that case, specify the server name or IP address of the server you want to disconnect. The following command only disconnects the latest session from server 192.168.0.132:

PowerCLI C:\> Disconnect-VIServer -Server 192.168.0.132

Disconnecting one or more sessions will also change the value of the $global:DefaultVIServers and $global:DefaultVIServer variables.

To see the current setting of InvalidCertificationAction, you can use the Get-PowerCLIConfiguration cmdlet. The syntax of this cmdlet is as follows:

Get-PowerCLIConfiguration [-Scope <ConfigurationScope>]
    [<CommonParameters>]

The following example will retrieve the PowerCLI configuration and shows the InvalidCertificateAction value for all scopes:

PowerCLI C:\> Get-PowerCLIConfiguration |
>> Select-Object -Property Scope, InvalidCertificateAction, 
    DisplayDeprecationWarnings |
>> Format-Table -AutoSize
>>


       Scope InvalidCertificateAction DisplayDeprecationWarnings
   ----- ------------------------ --------------------------
 Session                    Unset                       True
    User
AllUsers

As you can see in the output, there are three different scopes for which you can modify the PowerCLI configuration: Session, User, and AllUsers. The Set-PowerCLIConfiguration cmdlet will modify the AllUser scope if you don't specify a scope.

The DisplayDeprecationWarnings property shown in the preceding output will be discussed in the section,  Suppressing deprecated warnings , later in this chapter.

You will probably have also seen the following warning messages:

WARNING: The 'Description' property of VirtualMachine type is
    deprecated. Use the 'Notes' property instead.
WARNING: The 'HardDisks' property of VirtualMachine type is
    deprecated. Use 'Get-HardDisk' cmdlet instead.
WARNING: The 'NetworkAdapters' property of VirtualMachine type is
    deprecated. Use 'Get-NetworkAdapter' cmdlet instead.
WARNING: The 'UsbDevices' property of VirtualMachine type is
    deprecated. Use 'Get-UsbDevice' cmdlet instead.
WARNING: The 'CDDrives' property of VirtualMachine type is
    deprecated. Use 'Get-CDDrive' cmdlet instead.
WARNING: The 'FloppyDrives' property of VirtualMachine type is
    deprecated. Use 'Get-FloppyDrive' cmdlet instead.
WARNING: The 'Host' property of VirtualMachine type is deprecated.
    Use the 'VMHost' property instead.
WARNING: The 'HostId' property of VirtualMachine type is deprecated.
    Use the 'VMHostId' property instead.
WARNING: PowerCLI scripts should not use the 'Client' property. The
    property will be removed in a future release.

These warning messages show the properties that should not be used in your scripts because they are deprecated and might be removed in a future PowerCLI release. Personally, I like these warnings because they remind me of the properties that I should not use anymore. But if you don't like these warnings, you can stop them from appearing with the following command:

PowerCLI C:\> Set-PowerCLIConfiguration -DisplayDeprecationWarnings
    $false -Scope User

You can also use wildcard characters to select specific virtual machines. To display only the virtual machines that have names that start with an A or a, type the following command:

PowerCLI C:\> Get-VM -Name A*

Parameter values are not case sensitive. The asterisk (*) is a wildcard character that matches zero or more characters, starting at the specified position. Another wildcard character is the question mark (?), which matches any character at the specified position. To get all virtual machines with a three-letter name that ends with e, use the following command:

PowerCLI C:\> Get-VM -Name ??e

You can also specify some specific characters, as shown in the following command:

PowerCLI C:\> Get-VM -Name [bc]*

The preceding command displays all of the virtual machines that have names starting with b or c. You can also specify a range of characters, as shown in the following command:

PowerCLI C:\> Get-VM -Name *[0-4]

The preceding command lists all of the virtual machines that have names ending with 0, 1, 2, 3, or 4.

If you want to filter properties that don't have their own Get-VM parameter, you can pipe the output of the Get-VM cmdlet to the Where-Object cmdlet. Using the Where-Object cmdlet, you can set the filter on any property. Let's display a list of all of your virtual machines that have more than one virtual CPU using the following command:

PowerCLI C:\> Get-VM | Where-Object {$_.NumCPU -gt 1}

In this example, the Where-Object cmdlet has a PowerShell scriptblock as a parameter. A scriptblock is a PowerShell script surrounded by braces. In this scriptblock, you see $_. When using commands in the pipeline, $_ represents the current object. In the preceding example, $_ represents the virtual machine object that is passed through the pipeline. $_.NumCPU is the NumCPU property of the current virtual machine in the pipeline. -gt means greater than, so the preceding command shows all virtual machines' objects where the NumCPU property has a value greater than 1.

PowerShell V3 introduced a new, easier syntax for the Where-Object cmdlet. You don't have to use a scriptblock anymore. You can now use the following command:

PowerCLI C:\> Get-VM | Where-Object NumCPU -gt 1

Isn't the preceding command much more like simple English?

In the preceding section, Filtering objects, you saw an example of the -gt comparison operator. In the following table, we will show you all of the PowerShell comparison operators:

In the preceding table, you see three different operators for some functions. So what is the difference? The c variant is case sensitive. The two-letter variant and the i variant are case-insensitive. The i variant is made to make it clear that you want to use the case insensitive operator.

The Where-Object cmdlet has two aliases: ? and where. Therefore, both the following commands will display a list of all your virtual machines that have more than one virtual CPU:

PowerCLI C:\> Get-VM | ? {$_.NumCPU -gt 1}


PowerCLI C:\> Get-VM | Where NumCPU -gt 1

To see a list of all of the aliases that are defined for cmdlets, type the following command:

PowerCLI C:\> Get-Alias

You can create aliases using the New-Alias cmdlet. For example, to create an alias childs for the Get-ChildItem cmdlet, you can use the following command:

PowerCLI C:\> New-Alias -Name childs -Value Get-ChildItem

Instead of displaying the output of your PowerCLI commands in the PowerCLI console, you can also display the output in a grid view. A grid view is a popup that looks like a spreadsheet with rows and columns. To display the output of the Get-VMHost cmdlet in a grid view, type the following command:

PowerCLI C:\> Get-VMHost | Out-GridView

The preceding command opens the window of the following screenshot:

You can create filters to display only certain rows, and you can sort columns by clicking on the column header. You can also reorder columns by dragging and dropping them. In the following screenshot, we created a filter to show only the hosts with a CpuUsageMhz value greater than or equal to 22. We also changed the order of the ConnectionState and PowerState columns.

Isn't that cool?