Replace the vCenter Machine SSL Certificate (7 & 8)

vCenter's Machine SSL certificate is the certificate clients see on the vSphere Client and the API endpoint. It is separate from ESXi host certificates, the internal solution-user certificates, the STS signing certificate and the root of VMCA (vCenter's built-in certificate authority). vCenter keeps its certificates in the VMware Endpoint Certificate Store (VECS).

Before you beginCopy Anchor Link

• Back up. Take a file-based backup and powered-off snapshots of the vCenter Server Appliance. Taking a powered-off snapshot means shutting vCenter down briefly: vCenter management is unavailable during that time, but running VMs are not affected. In Enhanced Linked Mode (several vCenters sharing one SSO domain), snapshot every vCenter in the domain together, following Broadcom's coordinated offline-snapshot guidance.

• Disable vCenter High Availability (vCHA) if it is configured, and set it up again after the replacement.

• Check the PNID. The Primary Network Identifier is the name vCenter was installed with; the certificate must match it:

  Copy Text

  /usr/lib/vmware-vmafd/bin/vmafd-cli get-pnid --server-name localhost

• Get the right certificate. The SAN must contain the PNID. Broadcom does not support wildcard certificates for vCenter Server. From an internal Microsoft CA, request it with a template for TLS server certificates (Server Authentication), and download the certificate and the CA chain Base64-encoded (PEM) - the DER format does not work in these dialogs.

• Access. Certificate Manager needs an SSH session as the appliance root user. Keep console access as well.

Each vCenter in Enhanced Linked Mode has its own Machine SSL certificate. Replace them one vCenter at a time.

Choose one workflowCopy Anchor Link

We recommend the vSphere Client on vCenter 8.0 Update 2 and later. Whichever you choose, stay in it from CSR to import: a CSR generated in the vSphere Client must be completed in the vSphere Client, and a Certificate Manager CSR and key must be imported through Certificate Manager.

Replace it in the vSphere ClientCopy Anchor Link

1. Go to Home > Administration > Certificates > Certificate Management and open the Machine SSL tab.

2. Click Generate Certificate Signing Request (CSR). Submit the CSR to your CA - the private key stays in vCenter.

3. When you have the signed certificate, click Import and Replace Certificate on the same tab and choose Replace with external CA certificate where CSR is generated from vCenter Server (private key embedded).

4. Upload two files:

   • Machine SSL Certificate: the signed certificate only (for example machine_name_ssl.cer).
   • Chain of trusted root certificates: the intermediate certificate(s) followed by the root certificate, in one file (for example chain.cer).

   If you paste the certificates as text, remove trailing spaces after the END CERTIFICATE lines - they make the import fail.

5. Replace. From vCenter 8.0 Update 2, no service restart is needed after a successful replacement; on earlier versions vCenter restarts its services automatically and the vSphere Client is unavailable for several minutes.

If the CSR and key were created outside vCenter, choose the dialog's option for an external CA certificate that requires the private key, and upload the key as well.

Replace it with Certificate ManagerCopy Anchor Link

1. Start Certificate Manager as root:

   Copy Text

   /usr/lib/vmware-vmca/bin/certificate-manager

2. In the main menu, select 1 (Replace the Machine SSL certificate with a Custom CA Certificate) and enter the [email protected] password.

3. In the submenu, select 1 to generate the Certificate Signing Request and key for the Machine SSL certificate, and enter a directory for the files. On vCenter 8.0 Update 2 and later, do not use /tmp - files there lead to INVALID_KEY errors. Use a directory such as /root/certs. If you already hit INVALID_KEY, generate the CSR and key again in another directory.

4. Submit vmca_issued_csr.csr to your CA.

5. Build the certificate file for the import. It must contain the complete chain, leaf first and root last:

   Copy Text

   -----BEGIN CERTIFICATE-----
   (Machine SSL certificate)
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   (intermediate certificate, if any)
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   (root certificate)
   -----END CERTIFICATE-----

6. Start Certificate Manager again, select 1 in the main menu, and in the submenu choose to continue importing custom certificates. Certificate Manager asks for three files: the certificate file from step 5, the private key generated in step 3, and the signing CA certificate (the root). Confirm with Y.

7. Wait until Certificate Manager reports completion. It updates VECS and restarts the vCenter services, so the vSphere Client and API are unavailable for several minutes. Do not interrupt it.

Only relevant for vCenter 6.7 and older: an external Platform Services Controller has its own Machine SSL certificate, so repeat the procedure there. vCenter 7 and 8 have no external PSC.

Product-specific considerationsCopy Anchor Link

A Machine SSL replacement does not replace ESXi host certificates. Starting with vCenter 8.0 Update 3h, vCenter can renew VMCA-issued Machine SSL certificates automatically (when vpxd.certmgmt.mode is vmca, five days before expiry). That does not cover certificates from your own or a public CA, which you still replace as described here.

Broadcom's vCert script (KB 385107) covers many certificate operations, including expired certificates. Broadcom states it is intended to be used at the direction of Broadcom support, so treat it as a support tool rather than your routine renewal path.

Verify the new certificateCopy Anchor Link

service-control --status --all
/usr/lib/vmware-vmafd/bin/vecs-cli entry list --store MACHINE_SSL_CERT --text
openssl s_client -connect vcenter.example.com:443 -servername vcenter.example.com -showcerts </dev/null

Check that all services are running, and that the certificate in VECS and on the wire has the expected subject, SAN, issuer and expiry date. Then open the vSphere Client and the API by the PNID, log in, open a VM console, and check Enhanced Linked Mode peers and integrations such as backup software.

RollbackCopy Anchor Link

• vSphere Client: if the replacement succeeded but causes problems, import the previous certificate again with the option that requires the private key. This is only possible if you have the old certificate and key - vCenter does not keep an exportable copy for you.
• Certificate Manager: main menu option 7 (Revert last performed operation by re-publishing old certificates) puts the previous certificates back. Use it before starting any other certificate operation.
• If vCenter does not recover: revert the coordinated powered-off snapshots of all vCenters in the SSO domain. Reverting only one linked vCenter can leave replication between them inconsistent.

Common problemsCopy Anchor Link

• The SAN does not contain the PNID, or the certificate is a wildcard.
• The Certificate Manager file is missing the root, or the chain is in the wrong order.
• The CSR was generated in one workflow and the certificate imported in the other.
• The CSR and key were written to /tmp on 8.0 Update 2 or later, causing INVALID_KEY.
• vCHA was still enabled during the replacement.
• An SSO administrator was used where the appliance root account is required.
• The certificate was downloaded from the CA in DER instead of Base64.
• An integration pins the old certificate's fingerprint and must be updated.

Automating certificate replacement with aethercertCopy Anchor Link

The aethercert vCenter target replaces the vCenter Machine SSL certificate and key through the vSphere Automation API. It does not replace ESXi, VMCA root, or solution-user certificates.

See Deploy targets for the fields this preset takes, what it needs on the host, and how far it has been verified.

SourcesCopy Anchor Link

• Broadcom KB 316601: replace vCenter Machine SSL with a custom CA certificate (Certificate Manager)
• Broadcom KB 403973: Machine SSL replacement via the vSphere Client
• Broadcom KB 318946: using vSphere Certificate Manager
• Broadcom KB 396907: Machine SSL replacement and auto-renewal in vCenter 8.x
• Broadcom KB 385107: vCert