Applying Chained SSL Certificates for VOS-based Applications (CUCM, IM&P, UCXN, UCCX, etc.)

One important task in a Jabber (and/or Collab Edge MRA deployment), or a UCCX deployment is to make sure that the clients trust the certificates that are presented by the services.  The current versions of Jabber force validation of certificates, as well as (obviously) web browsers used with Finesse.

I recently worked through applying trusted CA-signed certificates for a UCCX 10.5 Finesse desktop deployment.  The customer had deployed UCCX Finesse without installing valid certificates on the server which was casing a number of problems.

  1. Agent web-browser login issues (untrusted certificate)
  2. Finesse Gadget’s failing (like Team stats viewer)
  3. CUIC report errors (either direct CUIC web interface or gadgets in Finesse)

I’d highly recommend installing trusted certificates before going production with a system to avoid these errors.

Basic flow to deploy trusted SSL certificates

Begin by going to OS Admin and generating a certificate server request (CSR) for the server.  The CSR is then signed by a certificate authority (CA).

To have Jabber or the web browser trust the certificate it must be signed by a trusted public CA like Verisign, GoDaddy, Starfield, Thawte, etc., or by a private CA that’s been added to the trusted list of the computer/mobile device.  (e.g. Private CAs include MS Active Directory Certificate Service for a client that’s part of an AD domain, or an OpenSSL (ahem, if you still trust it…  ;-)) that’s been added to the client’s trust list.)  The most compatible, but more expensive option is to use a public CA to sign the server certificate request (CSR) as it is trusted inherently by the most clients.

One of the challenges we’re seeing from public CA’s is the CSR being signed with an intermediate certificate.  Usually the certificate chain involves the server certificate, an intermediate certificate and a root certificate.  In the past it was much more popular to have the server certificate linked directly to a root certificate.  This has been a problem historically for some servers that don’t know how to deal with intermediate or chained certificates.  Most VOS applications 9.0 and higher support chained certificates, but documentation is non-existent.

After having the CSR signed, you’ll want to request the certificates in Base64 encoded format (usually a .pem or .cer extension which is an ASCII File that has the —–BEGIN CERTIFICATE—– and —–END CERTIFICATE—– markers).  Normally you’ll receive a ZIP file with the server certificate, as well as a root certificate, or in the case of a chained certificate that has an intermediate certificate you may receive a bundle .pem/cer with the intermediate and root certificates.

The server certificate is easy to deal with, as it will typically have the name of the server in the filename and only include that certificate.

Figuring out how to split up the intermediate and root certificates from the bundle .pem/cer can be a challenge.  The file will normally include three certificates, delimited by the —–BEGIN CERTIFICATE—– and —–END CERTIFICATE—– for each certificate.

Typically they are chained in the bundle .pem/cer with the Root certificate first, the Intermediate second.  They may have another certificate at the bottom which is a Class 2 Certificate Authority identifier. This is not needed for the import of the certificates into UCCX.

Windows makes it easy to open the bundle and export just the certificates you want by double-clicking the .cer and looking at the chain and exporting the certificates.   On the Mac, I just take the text file and cut and paste it into separate files for each certificate and then manually open them in Keychain access to figure out which one is which.  Then I name each file appropriately (like root.cer and intermediate.cer).  Now I have all three certificates that I need — root, intermediate and server.

At this point to into OS Admin on the VOS box (UCCX in this example) and import them according to the documentation below.

UCCX 10.5 allows importing of chained certificates but the instructions are incorrect.

The instructions are located here –

They indicate the proper order of importing the certificates (1. Root; 2. Intermediate; 3. Server), but step 7b and 8b are incorrect.  It has outdated information indicating that the Root Certificate must be specified as in the screenshot below:



This field does not exist in UCCX 10.5, so ignore steps 7b and 8b.  It will automatically chain the certificates.

Once the certificates are uploaded, I bogged down in trying to restart individual services like tomcat and finesse which fixed the client cert errors, but the gadget and CUIC errors persisted.  The eventual fix was a complete server reboot, so I would suggest doing that immediately.


Choosing the correct OVA for deployment… it matters.

I’ve seen a couple customers run into an ugly issue that isn’t pleasant to resolve.

After upgrading their VOS (voice operating system)-based application (CUCM, CUC, CCX, etc.) to a new version the server boots and throws this warning/error:

VMware Installation: 2 vCPU Intel(R) Xeon(R) CPU E5640 @ 2.67GHz, disk 1: 80Gbytes, disk
2: 80Gbytes, 6144Mbytes RAM, ERROR-UNSUPPORTED: Partitions unaligned

The cause is all the cases that I’ve reviewed was the correct OVA not being used in the original deployment:

  1. Deploying without using an OVA at all (VMWare admin building the machine by hand)
  2. Deploying the incorrect OVA for the version of ESX you are on (e.g. vmv7 version with ESXi 5 rather than the correct vmv8 version).
  3. Deploying the incorrect OVA for the version of the application (e.g. deploying the CCX 10 OVA for the build of CCX9 and then upgrading to CCX10).

My process during a migration:

Know which version of the VOS app you are going to install; know the version of ESX you are running on and use the appropriate OVA.

For example if I had a production CUCM system on v9.1(2) and ESXi 5.5 and was replicating the CUCM system to a test environment to take it to v10.5, I must deploy the OVA for CUCM 9.1 vmv8 on the test environment.  I’d DRS out/in and then upgrade the test environment to v10.5.    (I would NOT deploy the v10.5 OVA for the 9.1 migration installation.)  This migration example would not require the use of the 10.5 OVA at all.

Now for CUCM I’d actaully use Prime Collaboration Deployment to make this process MUCH easier (which WOULD use the v10.5 OVA).  But for other apps like CUC or UCCX which don’t have PCD support yet, I’d use that process.

If you get a system with the error

ERROR-UNSUPPORTED: Partitions unaligned

The fix is ugly.

To correct the unaligned disk partitions you must:
1) Take a DRS backup of the system
2) Deploy a new virtual machine from an updated version of the OVA  and
perform a fresh install of the previously-unaligned virtual machine. Details can be found
on this Virtualization DocWiki page:
3) Perform a restore on the freshly-installed node, using the DRS backup taken in step 1

More Info:
If your virtual machine has unaligned disk partitions Cisco cannot provide support for
performance issues. The steps in the Workaround must be followed to put the virtual
machine in a supported state.

Once everything is on v10.x, RHEL6 (used in VOS 10.x)  automatically aligns partitions.  So this should not be an issue in the future once cured on your 9.x system.