PowerCLI, vCheck, and vCenter SSL/TLS secure channel errors

I have been struggling with a number of errors and warnings between PowerCLI and my vCenter servers. The warnings about my self-signed certificates are no big deal, but the errors of course are. The biggest error I have is a well-known issue documented in this vCheck issue on GitHub:

The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.

This happens intermittently, but frequently with the Get-HardDisk cmdlet which is used in most of the Snapshot related plugins. When it does happen, the vCheck plugin fails to return any meaningful data and normally errors pretty fast – run times for the full set of checks in my environment drops from ~120 minutes to ~8 minutes.

The issue goes back over 3 years and while there were a number of attempts to fix the issue, there was no single fix that worked for everyone, every time. Some would hide the issue till you hit a certain threshold and others would just make it far less likely to occur, but not eliminate it. I eventually opened an issue with VMware support and we found what I think is the solution.

Untrusted Certificates and CAs

I am using the provided certificates for my vCenters. These certificates have an expiry term of 10 years and are signed by a CA also provided by vCenter during the initial install. This is typically known as a self-signed certificate, but more specifically means the cert is not signed by a CA trusted by the client (if it was signed by Verisign but you removed the Verisign CAs from your Trusted CA store, it would be reported as a cert signed by an Untrusted CA and/or a self-signed certificate, depending on the application interfacing with it. I have decided to continue to use these certs as the process for attaching new certificates to a vCenter installation is hairy, to say the least.

This means that when I run Connect-VIServer against my vCenter, I receive the following note about the untrusted CA:

Be sure to use the FQDN to access your vCenter server, or this warning will be swallowed in favor of a “name mismatch” warning.

Generally speaking, most of us don’t care about this error because we are confident that we are connecting to our vCenter server and we tend to ignore this as a cause of problems. I certainly did. I don’t know the specifics surrounding it, but PowerCLI sometimes decides it doesn’t like the Untrusted CA and thus generates the error about Could not establish trust relationship. Sometimes, it’s cool and establishes it just fine. I believe it has something to do with resource exhaustion in tracking the connection, as one of the workarounds suggested on GitHub appeared to work for some by increasing the resources available to a PowerShell session. Regardless of the specifics, connecting to a Trusted CA does not have this issue. So our resolution is to use certificates signed by a Trusted CA!

As suggested above, you can attach new certificates directly from a Trusted CA to your vCenter, but it’s a tricky process. The other alternative is to trust the CA from your vCenter, which we’ll do here. Alternatively, if you want to attach new certs from an already-Trusted CA, check out KB2111219 and any number of blog posts that address this process and skip ahead to the Summary section.

Download and Install the Certificate Bundle

The first step to trusting the vCenter’s included CA is to download the certificate bundle. You can do this by visiting your vCenter on port 443, e.g. https://vcenter.example.com, and clicking on Download trusted root CA certificates:

You will receive a zip file that contains the certs in various formats. Since I’m on Windows, I burrow down to the certs\win directory where there are two CRT files and one CRL. Extract this in a folder somewhere. You only need the CRT that is paired with a CRL; the other CRT is for the ssoserver and that is not something PowerCLI cares about.

In vCenter 6.0, the cert bundle had no directories and just two files ending in .0 and .r0 (now found in the lin and mac directories) that correspond to .crt and .crl respectively, so just extract and rename the files if you that’s the case.

Now, we need to access the certificate store. This varies per OS and version. In Windows 7, you can find the store inside the Internet Options control panel on the Content tab by clicking the Certificates button. Click over to the Trusted Root Certification Authorities tab.

Click the Import button and browse to the CRT you stored earlier. When you import it, you’ll see the name CA – if you see ssoserver, you chose the wrong CRT file, try again with the other. You can now click on the imported CA called CA and click View to see the name. This is important when you have more than one vCenter, as they all import with the name CA, because that’s not confusing! You can see here this is the CA from my vCenter server called vcsa.nelson.va:

You want to repeat this process on any and all nodes that will use PowerCLI to connect to the vCenter in question, not just the server you run vCheck from.


With either your new certs or the new trust with the existing CA, you shouldn’t see the warning upon accessing your vCenter with Connection-VIServer. Close your PowerShell/PowerCLI sessions run that inside a brand new session and if you did things correctly, you will not see any yellow warning text:

When you run vCheck now, you should no longer see those random SSL/TLS errors! If you disabled some checks, like Phantom Snapshots, because they failed more often than they ran, this is a good time to review if you want to re-enable them. I hope this helps.

I will warn that this solution has only been tested for about a month, but I saw error rates drop from 70% to 0%. I could NOT get the errors to occur with the CA in place, but they would come back the moment I removed the CA. If you see the error return, please let me know in the comments or on twitter and I’ll be glad to share the ticket number reference for engaging support!

Many thanks to Isaac at VMware for this solution, and especially his insistence that I should import the CA even though I swore that couldn’t be the problem 🙂

Using PowerCLI from the PowerShell Gallery

As you’ve surely seen, I love me some PowerCLI. So I was really happy when I saw that PowerCLI is now available on the PowerShell Gallery! What this means is that it is no longer a package you install on a server, it’s a set of modules you load from the gallery. When there’s a new version available, you just go get it. Because it’s now a bunch of files, not only do you not need to go to vmware.com to find the download link, you can also install it without requiring administrative access! That’s pretty awesome when you’re a tenant on a system, and it’s pretty awesome for the owners of the system, too (no needing to punt all your PowerCLI users so the files aren’t locked during an upgrade). I fill both roles from time to time, so I’m really happy about this improvement! Read more about the change in this VMware PowerCLI Blog article by Kyle Ruddy.

The article will guide you through the setup just fine, so I won’t dwell on that part very much, but if you’ve followed my PowerShell Profile article, there’s one small change to make: uninstall the old version of PowerCLI, then edit your posh profiles with notepad $profile and remove whatever version of the profile you used. Leave anything else you have added and close it out. Remember to do this once in PowerShell and once in PowerShell ISE if you use both.

Now, install the modules as the blog article recommends.

Find-Module -Name VMware.PowerCLI
Install-Module -Name VMware.PowerCLI -Scope CurrentUser

That’s it, you’re done! The modules will automatically be loaded as needed. You should be able to start typing Connect-VIServer and see autocomplete working by tabbing it out in regular PowerShell, in the typeahead dialog in ISE, or however your PowerShell UI displays it. If you hit enter, the containing sub-modules are loaded immediately on-demand. You can import the entire suite of modules with Import-Module VMware.PowerCLI,in your profile if you’d like, but it adds about 10 seconds to PowerShell startup on my laptop for minimal gain vs on-demand loading. However, it does give you the look of the old PowerCLI desktop shortcut, if you so desire it.

If, for some reason, the module is not found by PowerShell after installation, check out the value of $env:PSModulePath. It should include %USERPROFILE%\Documents\WindowsPowerShell\Modules, e.g. `C:\Users\rnelson0\Documents\WindowsPowerShell\Modules`, which is where Install-Module installs the files to. If it does not, you’ll need to modify it. Mine was funky because I apparently edited the environment variable portion of my windows install, even though I don’t remember it.

To keep up with PowerCLI from the Gallery, just run Update-Module -Name VMware.PowerCLI once in a while. Easy peasy. Enjoy!

Getting started with vCheck

If you use vSphere and particularly vCenter, you’re probably at least familiar in passing with PowerCLI, a package of snap-ins and modules for PowerShell. This is my preferred language for interacting with the vSphere/vCenter APIs, since it has (IMO) the best documentation of the available languages and API SDKs. If not, I recommend downloading it and playing with it, it can really help you automate many of your repetitive tasks with less Flash and less right clicking.

One of the most popular tools built with PowerCLI is vCheck. It’s a framework for running a number of checks against your vSphere infrastructure and determining what operational issues are present – something every Ops team needs. It won’t replace a monitoring system such as vROps or even Nagios, but it augments such systems very well. For example, it can report on VMs that have ISOs attached, or where snapshots have been present for more than 7 days – issues that probably aren’t worth paging anyone out for, but need to be dealt with eventually. Many of us have built some homegrown solutions for this, maybe even with PowerCLI, but it is difficult to beat a tool designed to meet the needs of a large percentage of vSphere users, is actively developed by VMware employees, and is a framework that you can extend with instance-specific needs. You can always run your tools and vCheck together, too.

Let’s take a look at vCheck and how to get started with it today. We’ll download it, configure it, schedule it as a daily task, review how to enable and disable checks, and store your configuration in version control. This provides a solid base that you can tweak until it fits your specific needs just right.

Continue reading

Tag-based Veeam Backups

As I teased in Using vCenter tags with PowerCLI, I want to explore how to use tags  in a practical application. To refresh our memory, we looked at creating an Ownership category with individual tags in it, and limited VMs to having just one of the tags. We created a little script that defines our schema, in case we need to re-create it. We are going to work on a new category today for our backups. Specifically, Veeam backups, based on SDDC6282-SPO, Using vSphere tags for advanced policy-driven data protection as presented at VMworld 2015.

Defining Policy and Tags

To create our backup jobs, we need to know a few things that will translate into our tag schema. Our backup policies are defined by a combination of ownership, recovery point objective (RPO), and the retention period. For example, our Development group is okay with a 24 hour RPO and backups that are retained for a week. Operations may require a 4 or 8 hour RPO and require 30 days of backups. Each of those combinations will require a separate backup job. We can combine these tuples of information into individual tags so that Veeam can make use of them. We also need one more tag for VMs that do not need any backup at all. We can put all of this in a tag category called VeeamPolicy. Here’s what that might look like, again in PowerShell:

New-TagCategory -Name VeeamPolicy -Description "Veeam Backup Policy" -Cardinality Single -EntityType VirtualMachine
New-Tag -Name "NoRPO" -Category VeeamPolicy -Description "This VM has no backups"
New-Tag -Name "Development24h7d" -Category VeeamPolicy -Description "Development VMs with 24 hour RPO, 7 days retention"
New-Tag -Name "Operations8h30d" -Category VeeamPolicy -Description "Operations VM with 8 hour RPO, 30 day retention"
New-Tag -Name "Sales48h30d" -Category VeeamPolicy -Description "Sales VM with 48 hour RPO, 30 day retention"

Continue reading

Using vCenter tags with PowerCLI

I was recently introduced to some practical usage of vCenter tags. I used tags to build a fairly easy and dynamic set of sources for Veeam backup jobs, but before I get into that, I want to explain tags a little bit for those who are not familiar with them.

Tags are something that are pretty easy to understand conceptually. You create a category which contains a few tags. An object can receive one or multiple tags from a given category. Tags are managed by vCenter, not by vSphere, so require a license that provides vCenter for management. That’s a pretty simple explanation and list of requirements.

A Tag Category has a collection of Tags available within it. If the Category is “single cardinality”, it means that an object can only be assigned one tag in the category. This might be good for a category associated with ownership or recovery point objective (RPO). A Category can also be “multiple cardinality”, where a single object can be assigned multiple tags in a category. This would be helpful to associate applications with a VM, or a list of support teams that need notified if there is a planned impact or outage.

I’m going to show you how to manage Tags and Tag Categories with PowerCLI (Specifically with the PowerShell ISE and a profile to load PowerCLI), but you can manually create and manage them through the vSphere Web Client, under the Tags item on the left hand menu. You can create and delete and rename tags and categories there all day long, and you can right click on an object almost anywhere else and select Edit Tags to edit the assigned tags on it. When you view most objects, you’ll see an area in the Summary tab labeled Tags that will display and let you manage assignments.

Continue reading

PowerShell Command Add-On

Many of us use PowerCLI, which relies on PowerShell. The default PowerCLI environment is pretty plain, but you can also use the PowerShell ISE  and load the PowerCLI snap-ins in your profile. The ISE, or Integrated Scripting Environment, offers a lot of advantages to the regular PowerCLI or PowerShell interfaces: Intellitype, lots of keyboard shorts, and something called the Command Add-On.

First, let’s look at how to turn it on. Fire up the ISE. If you have Powershell pinned on your taskbar, you can right click and choose the ISE, or just hit the windows key and type ‘ISE’. You want the regular version of PowerShell ISE, not the “(x86)” version. Now that it’s open, go to View -> Show Command Add-On and select it:

fig 1

Continue reading

Use existing definitions as a baseline

Sometimes we spend way too long trying to define things in our head when we can get existing configurations from the system. It’s vital to have a full service definition or any promotion of the service through environments will turn up missing components and make your life hell. If you’re building a new service that looks similar to an old one, or evolves the old service, steal the old service’s definition and then modify it.


There are a number of ways to gather existing service definitions. If you’re building a new host and you have Enterprise Plus licenses, use Host Profiles. Export an existing host’s config to a host profile, uncheck the irrelevant portions, change what’s relevant but different, and apply to the new host. It might take a few tweaks, but you’ll get it right soon. Then export the new host’s config to a host profile and you’re good to go.

If you don’t have Enterprise Plus, take a look at PowerCLI. It will take more legwork, but there are a ton of cmdlets available to capture networking, storage, and other service definitions from existing hosts which you can then apply elsewhere.

Continue reading