vSphere 5.5 Install Pt. 19: ESXi SSL Certificate

12-22-2013 2-49-19 PMAfter a bit of a delay, I’m finally publishing how to update your ESXi SSL certificate. The process is pretty much unchanged from the 4.x era, but what is new is my Toolkit script. It has been updated to include ESXi certificate support. This is accomplished all in PowerShell, and does NOT require SSH be enabled on the host. It uses the HTTP PUT command to upload the two required files. This should also run successfully against older ESXi hosts, but I haven’t tested it.

Blog Series

SQL 2012 AlwaysOn Failover Cluster for vCenter
vSphere 5.5 Install Pt. 1: Introduction 
vSphere 5.5 Install Pt. 2: SSO 5.5 Reborn 

vSphere 5.5 Install Pt. 3: vCenter Upgrade Best Practices and Tips
vSphere 5.5 Install Pt. 4: ESXi 5.5 Upgrade Best Practices and Tips 
vSphere 5.5 Install Pt. 5: SSL Deep Dive
vSphere 5.5 Install Pt. 6: SSL Certificate Template
vSphere 5.5 Install Pt. 7: Install SSO
vSphere 5.5 Install Pt. 8: Online SSL Minting
vSphere 5.5 Install Pt. 9: Offline SSL Minting 
vSphere 5.5 Install Pt. 10: Update SSO Certificate
vSphere 5.5 Install Pt. 11: Install Web Client
vSphere 5.5 Install Pt. 12: Configure SSO
vSphere 5.5 Install Pt. 13: Install Inventory Service
vSphere 5.5 Install Pt. 14: Create Databases
vSphere 5.5 Install Pt. 15: Install vCenter
vSphere 5.5 Install Pt. 16: vCenter SSL
vSphere 5.5 Install Pt. 17: Install VUM
vSphere 5.5 Install Pt. 18: VUM SSL
vSphere 5.5 Install Pt. 19: ESXi SSL

Permalink to this series: vexpert.me/Derek55
Permalink to the Toolkit script: vexpert.me/toolkit55

Introduction

Download my vCenter 5.5 Toolkit v1.5 or later from here. It was just updated for this post, so if you’ve been following along and already have the script, you will need the updated version for the ESXi features. At this point I’ll make the following assumptions: 1) You’ve installed ESXi 5.x 2) Created a DNS entry for your ESXi host 3) ESXi host is reachable on the network via the FQDN (e.g. ESX01.yourdomain.com) 4) The host you run the Toolkit script on has HTTPS access to the ESXi host(s).

VMware HA can get confused with updated thumbprints when you replace the SSL certificate if the host was already added to vCenter. For this reason I recommend either updating the host SSL certificate prior to adding to vCenter, or disconnect the host in vCenter, update the certificate, and reconnect in vCenter. Should you run into SSL thumbprint errors, you may see a message like the one below. For more information you can checkout KB 2006210.

12-22-2013 4-02-36 PM

The script is fairly agile, and can produce ESXi certificates via a variety of methods. You can also feed it a CSV file of hosts, and mass produce certificates as well. Each method has its own section below. I suggest reading through all methods so you know what options you have and get the complete picture.

Online Minting Method

1. Open an elevated PowerShell prompt and run the Toolkit script. You will see the following menu items. Version 1.5 and later has a new “ESXi Hosts” section with several options. Like the other modules, the script supports an online Microsoft CA, an online Microsoft CA that requires manual approval, or creating the CSRs to use with a non-Microsoft CA.

In this first example let’s assume you have an online Microsoft CA that does not require manual certificate approval. Select Option 11.

12-22-2013 3-03-31 PM

2. You are now presented with a second menu. Here you can manually enter the ESXi hostnames, or read in a CSV if you have lots of hosts to prepare certificates for. Let’s first go for the manual host entry and select Option 1.

12-22-2013 3-13-05 PM

3. After selecting Option 1 you are prompted to enter the hostname(s) of the ESXi servers. Be sure to use the FQDN of your ESXi host(s). Comma separate the hosts if you input more than one. Assuming you haven’t run the script before it will then ask you for the root credentials of the ESXi host. The credentials must be the same for all hosts, and you only need to enter it once no matter how many hosts you are updating.

12-22-2013 3-15-58 PM

4. After you enter the root credentials you should get yellow status messages for each ESXi host that the certificates were successfully uploaded to. There is some error trapping, so errors like incorrect credentials or invalid hostnames will throw an exception message, but continue with other hosts.

5. At this point I recommend rebooting the ESXi host. Yes, technically you can restart the ESXi management agent but I feel better with a full reboot. After the reboot open your favorite browser and go to the FQDN of your ESXi host. You should not get any SSL errors. You can also open the certificate properties and verify it came from your trusted CA.

12-22-2013 4-18-16 PM

You can now add your ESXi host to vCenter. Find your cluster in vCenter, then right click on it and select Add Host. Enter the FQDN of your ESXi host and run through the rest of the wizard. It should now be added, and the proper thumbprint stored in the database.

12-22-2013 3-33-25 PM

Offline Minting Method

1. Run my Toolkit script but this time select option 12. This will only create the CSRs, which you will then submit to your own CA and download the minted certificate. Again here I selected option 1 to manually enter the ESXi hostname.

12-22-2013 4-25-56 PM

2. If you look in the certificate directory path (configurable in the script), you will see a folder with the FQDN of your ESXi host. If you open that folder you will see three files. Take the CSR and submit it to your CA. Download a BASE64 encoded certificate (not a certificate chain) and save it as rui.crt in the same folder.

12-22-2013 4-27-07 PM

3. Re-run the Toolkit script but this time select option 13. Re-enter the hostname(s) that you created certificates for. Enter the root credentials if they are not already cached. You should get a yellow status message for each ESXi host if it is successful.

12-22-2013 4-31-44 PM

4. Go back to Step 5 in the Online Minting section to reboot your host, validate the certificate is correct, and reconnect the ESXi host to vCenter.

Manual Approval Method

1. Run my Toolkit script using option 11. This will proceed just like the online method, but it will display RequestIDs that your CA administrator must approve. I selected option 1 on the sub-menu to manually enter the ESXi hostname.

12-22-2013 4-59-17 PM

2. Note in yellow the RequestID(s) and have your CA administrator approve them.  After it is approved, re-run the Toolkit script but select option 13 from the main menu. Re-enter the same ESXi hostname(s) or CSV file that you used for the original request. You should see a status message showing the certificate(s) were downloaded and then successfully uploaded to each ESXi host.

12-22-2013 5-02-27 PM

3. Go back to Step 5 in the Online Minting section to reboot your host, validate the certificate is correct, and reconnect the ESXi host to vCenter.

CSV Input File

If you have several hosts that you need to update certificates on, then you don’t really want to be typing in all the hostnames. So this script will also accept a formatted text file of ESXi hosts names. The input file can be used with ALL minting methods (online, offline, manual approval). The file is very simple. Each line should have the FQDN of a single ESXi host. There is no limit to the number of hosts you can put in the file.

12-22-2013 5-07-13 PM

To use this file merely select Option 2 on the sub-menu (Read ESXi hosts from CSV file) and input the path to your text file. You can see a sample use case below, where I’m using manually approved certificates.

12-22-2013 5-09-59 PM

Summary

As you can see, the Toolkit script is now fairly complete, although delayed a bit longer than I had originally planned. It certainly is not foolproof, but does have some error checking. No doubt there will be some circumstances where it will fail. Should you need to manually copy the certificate files to the host using something like WinSCP, copy the rui.crt and rui.key files to /etc/vmware/ssl on the ESXi host. Be sure to use ASCII/text mode to avoid translation issues. Also, if you wish to delete the cached root credentials (I would suggest this after completing the certificate upgrades), then remove the root-credentials file from your Certificate directory.

Comments

  1. James Davis says:

    Thank you for the outstanding detail in the articles. I have discovered an issue that I am unable to resolve. When I import an .iso into update manager I get a certificate prompt issued by VMware. This is the only prompt I have received after using your script and following the instructions. Is this something you have you seen?

  2. Fleetside58 says:

    Hi Derek,

    With the help of this massive blog, I was able to get vCenter 5.5 with SSO up and running solid for months. Thanks a ton.

    However, I panicked when I logged in to the web client with my windows session authentication to see an empty inventory. After many attempts and restarting services and rebooting and web research, I resigned myself to using 'administrator@vsphere.local' for any remote web client connections, or the Vcenter service account I created on the vCenter machine itself.

    To my knowledge;
    1.) Nothing with the cert server is amiss, but I wouldn't rule that out.
    2.) Every AD account that previously had access yields an empty inventory, with the exception of the AD service account.
    3.) No one but myself performs maintenance, as we are a two-person, three-host server shop.

    My concern is that I go tooling around and do something that breaks SSO even further. Where should I start looking? Any input would be a big help.

    Thanks

  3. As always Derek, I thank you again for such a great writeup. Not nearly as challenging as the 5.1 series.

  4. There's no official migration tool, but you can check out https://labs.vmware.com/flings/inventorysnapshot for a possible way to help migrate vCenter objects. For the other areas, that's a complex answer that would need close analysis of your legacy and new environments. You should also thoroughly test the migration process.

  5. I would get the infrastructure healthy, then do any acquisition related work.

Speak Your Mind

*

© 2014 - Sitemap