The vSphere Web Client and Legacy “Script” Plugins

If you develop and maintain a vCenter server plug-in that extends the vSphere client to support management of your company’s ESX-based products then you have an uphill battle in front of you. I’ve (sadly) come to the conclusion that the only thing that keeps VMware in business today is market share. It’s certainly not great developer documentation and support.

To be clear, they have lots of developer documentation; unfortunately, much of it is less than truthful and it’s often too sparse to be useful. Nevertheless, most of us stumble along managing to make our plug-ins work, but never being really sure we’re doing exactly the right thing in any of the required steps.

VMware is soon to release ESXi 5.5 and surrounding vSphere infrastructure. This new version of vSphere deprecates the Windows thick client – prematurely, in my mind. I know why they’re doing it: They’ve taken a lot of abuse in the industry during the last 5 years about being too Windows-centric with respect to vSphere management tools.

They’ve needed to move to a web-based architecture. To this end, some time ago they began working on the vSphere Web Client – a management client much like the vSphere Windows thick client except, of course, that its rendered in a browser and is, thus, fairly portable. Unfortunately, the web services framework they chose was Adobe Flash and they jumped in with both feet before they realized that Flash was on it’s way out the door in favor of html 5.

VMware specifies two types of “legacy” plug-ins – those designed to be used with the vSphere Windows client:

  1. C# client-side plug-ins. These actually run within the process context of the Windows client itself. They can be deployed by a server, so they’re available for download and installation at the click of a button within the client but they are written in C# and run within the client’s process address space on your Windows work station.
  2. So-called “script” plug-ins, where the term “script” refers to html or xml script, I suppose – it’s a terrible name. What it actually means is that you have a web server running in a VM somewhere providing content to be displayed in an embedded browser window within the client.

This browser embedding mentioned in 2 above is done solely by virtue of the fact that Microsoft Internet Explorer is mostly COM objects wrapped in a simple GUI application. These COM objects may be used by any process, and are documented by Microsoft so they may also be used within third-party applications – such as the vSphere Windows client. (In fact, the specific COM interface used is the one providing Internet Explorer 7 functionality, so to test your plug-in within a normal browser, you should probably enable IE 7 compatibility mode.)

Not all script plug-ins provide a GUI interface, but all of the extension points supported within the client operate on the principle of sending a URL off to a server somewhere and either rendering reply data, or expecting the receiving server to perform some remote operation based on the URL content (path, query string, fragments, etc.).

With the advent of the Web Client, a new type of plug-in is now supported (nay, expected!) by VMware. Essentially, these plug-ins are a combination of a back-end web service that contains business logic and a Flash application that runs within a Web Client Flash frame in the browser.

The Web Client supports the newer Flash-based plug-ins, of course, but it also supports legacy script plug-ins. Given that most people don’t have the time or inclination to rewrite yet another pre-destined-for-doom version of their plug-in, this article focuses on getting your existing legacy script plug-in to work in the Web Client.

VMware Documentation

Read the following VMware documentation pages on getting your legacy script plug-in to work in the Web Client:

http://pubs.vmware.com/vsphere-51/index.jsp#com.vmware.wcsdk.pg.doc/LegacyPlugins_Appendix.16.1.html

Also read the three sub pages beneath this page: Enabling Script Plug-in Support…, Where Script Plug-in Extensions Appear…, and Known Issues…. When you’ve done this, come back and we’ll focus on explaining and debunking the content of these pages. (Chances are pretty good that if you’re here, you’ve already read these pages and are now looking for the real documentation.)

Make note of the extension point differences in the Where Script Plug-in Extensions Appear… page. Assure yourself that your plug-in will provide mission critical functionality in the Web Client before you go any further. Some of the legacy extension points are simply not supported and there’s nothing to be done about this except find a different way to provide your functionality.

Enabling Script Plug-in Support in the Web Client

The first thing to note is that script plug-in support is disabled by default in the Web Client. Explain to your customers that they’ll have to modify a configuration file on the server on which their web client service is running – usually the same as their vCenter server. (Don’t concern yourself overly with this requirement – various groups within VMware provide only legacy script plug-ins and themselves recommend enabling script plug-ins in the Web Client.) The documentation is accurate here – simply have them add the following line to their webclient.properties file, as documented:

  scriptPlugin.enabled = true

If your plug-in only supports unsecure (http) traffic, you’ll also need to have your customers add the allowHttp = true line to the properties file. If you prefer secure plug-in traffic (and you probably should) then you won’t need this step, but you will want to read on because the VMware documentation gets a bit murky from here on in.

The second paragraph on the Enabling Script Plug-in Support… page is one of the fuzzy places. It indicates that you “must add the SHA1 thumbprint of the server where the scriptConfig.xml file is located.” Huh? What server? What’s a scriptConfig.xml file? The SHA1 thumbprint of what… a file… a certificate… a server… some data somewhere? Is a thumbprint the same as a fingerprint? Lots of questions, no answers…

At this point we opened a support ticket with VMware and were told to add the thumbprint string to the registration document you pass to the ExtensionManager when you register your plug-in with vCenter. A quick look in the Managed Object Browser (mob) showed that there is indeed a serverThumbprint field in the server sub-record of the registration document. It didn’t take too much effort to figure out where you assigned that value in the vim web services SDK. The problem still remained: What exactly is a server thumbprint?

I surmised from past experience that perhaps the thumbprint was the ssh server’s rsa fingerprint – the series of hexadecimal octets that shows up when you first attempt to ssh into a linux system – in this case the plug-in server. I queried and was told that was exactly correct. This bit of misinformation kept us busy for a week. A particularly sharp member of my team then considered other types of SHA1 fingerprints and discovered that if you use the following command line:

     openssl x509 -fingerprint -noout -in certificate-pem-file

You can get a SHA1 fingerprint value from any PEM certificate file. In this case, the certificate that makes the most sense is the one presented by your plug-in’s web service. And it turns out this is the value you must use. (See this great stackoverflow article for openssl C/C++ code that queries a certificate for its SHA1 fingerprint.)

Of course, this means that you will have to reregister your plug-in extension with the ExtensionManager any time you change your plug-in web service’s server certificate, but this doesn’t normally happen often.

Final Thoughts

On the Known Issues… page most of the content is clear, but note the second bullet point:

  • When using a script plug-in at a secure URL (HTTPS) in the Chrome or Firefox browsers, you must load the script plug-in page in an external tab at least once before it appears inside the vSphere Web Client.

The reason for this is that the Web Client doesn’t have very mature support for server certificates that are not signed by a well-known CA, or where the corporate CA hasn’t been imported into the browser’s trust store. In the Windows thick client, when you access a plug-in with a self-signed certificate, you see popups that warn you and ask if you’d like to continue. The Web Client simply fails to display the plug-in content if the plug-in server’s certificate is not signed by a CA in the browser’s trust store.

A quick work-around is to open another tab in the browser (or another instance of the same browser) and navigate to your plug-in server’s main page and accept the certificate using the browser’s built-in certificate management mechanism. Once this is done, the Web Client will accept the plug-in’s certificate because the browser has already accepted it.