Before you begin
Before proceeding, ensure that you are aware of these points:
- If you are running the vCenter Server services in a virtual machine, take a snapshot of the virtual machine before starting the process to expedite recovery times in case of failure. Ensure to also remove the snapshot after the process completes successfully.
- Updating certificates for third-party components such as load balancers and on non-Window OS machines must be done manually.
- Any character input containing the ^ (caret) character are not allowed.
- If the path or file name of the tool or new certificates contain any of the special characters, such as ^ (caret), % (percent), & (ampersand), ; (semicolon), or ) (closing bracket), the tool fails and either exits, throws an exception, or reports that the certificate or key files are not found.
- You must shut down any dependent solutions that are running in the environment to prevent failures of these services. The solutions that are to be shut down while updating the certificates include:
- VMware Site Recovery Manager
- vSphere Data Recovery
- vCloud Director
- Any third-party solution which may be connecting to vCenter Server,
Before performing these steps, ensure that:
- You have reviewed the Known Issues section of this article.
- You have a vSphere 5.5 environment.
- The vSphere 5.5 environment is pre-installed for all components for which you want to install certificates.
- You have reviewed the Key Usage Extensions for the
Web Server
template in your Certificate Authority server and it has digitalSignature
, keyEncipherment
and dataEncipherment
enabled for the certificate generation. - You are not using wild card certificates. In vSphere 5.x, each certificate must be unique and as a result, it does not support wild card certificates.
Installing or upgrading the SSL Certificate Automation Tool
You must install and deploy the SSL Certificate Automation Tool on each machine on which a vSphere component resides. However, you can use the tool on a single machine to do the initial planning.
There are three possible configurations for installing the SSL Certificate Automation Tool:
- Single machine (all services in one machine)
All services are located on the same machine. In this case, the SSL Certificate Automation Tool must be deployed in one machine.
- Multiple machines (machine per service)
Each service is located on a different machine. In this case, the SSL Certificate Automation Tool must be deployed on each machine running one of the seven services.
- Mixed mode (multiple services per machine)
Some services are run on one machine, but others run on a different machine. In this case, the SSL Certificate Automation Tool must be deployed on all the machines which have services that are to be updated, and machines where there are deployed services communicating with the ones that are to be updated. Use the Update Steps Planner to determine the exact order of the steps for deployment.
Installing the SSL Certificate Automation ToolTo install the SSL Certificate Automation Tool:
Note: Ensure that the installation path for the SSL Certificate Automation tool does not contain any spaces.
- Download the SSL Certificate Automation Tool from the VMware Download Center. This download is located in the Drivers and Tools section of the vSphere and vCloud Suite download pages.
- Copy the tool to each machine on which a vSphere component resides.
- Use an unzipping utility, unzip the file into any directory, preserving the directory structure.
Upgrading the SSL Certificate Automation ToolUpgrading to a newer version of the SSL Certificate Automation Tool is simple because no installation is required. To upgrade the SSL Certificate Automation Tool from a previous version:
Note: Ensure that the installation path for the SSL Certificate Automation tool does not contain any spaces.
- Download the SSL Certificate Automation Tool from the VMware Download Center. This download is located in the Drivers and Tools section of the vSphere and vCloud Suite download pages.
- Copy the tool to each machine on which a vSphere component resides.
- Use an unzipping utility to unzip the file into a different directory than the previous one that the tool was using, preserving the directory structure.
Note: VMware also recommends removing the older version of the tool to avoid confusion. To remove the older version, delete the folder where the older tool resides.
Using the SSL Certificate Automation Tool
After the tool is installed, you can use it to update certificates. Before beginning, however, it is possible to predefine default values to partially automate the process. Although it is not required, this can help avoid errors in the subsequent configuration steps. If you are not predefining the default values, proceed to the
Running the Update Steps Planner section.
Predefining default valuesPredefining the default values in the tool helps prevent typing errors and save time. This lets the tool automatically include specific information that you have defined as the default, instead of prompting you for it. For security reasons, only passwords cannot be saved when defining default values.
To predefine default values:
- Open the
ssl-environment.bat
file in a text editor, such as Notepad. By default, this file is located in the root of the tool directory. - For each relevant component you want to update, enter the required parameters and the option parameters you want to change. For example, for vCenter Server you can edit the
vc_cert_chain
, vc_private_key
and vc_username
parameters.
When you include the information in the ssl-environment.bat
file, the SSL Certificate Automation Tool saves this information and uses it to automatically pre-fill required input during certificate updates, trust updates, and rollback operations.
- After you have entered all the information, save and close the
ssl-environment.bat
file in the tools directory.
Note: The values created by ssl-environment.bat
file are read-only when the tool starts up. If you run the ssl-environment.bat
file while the SSL Certificate Automation Tool is running, the values are not read.
Running the Update Steps Planner
The Update Steps Planner is an option that allows you to determine the order in which you should proceed to properly update the SSL configuration. VMware recommends that you follow the steps presented in the Update Steps Planner exactly as they are presented to ensure that the configuration is properly updated.
To run the Update Steps Planner:
- Log in to any machine on which the SSL Certificate Automation Tool is installed.
- From a command line, navigate to the location where you unzipped the tool.
- Run this command:
ssl-updater.bat
- At the main menu, choose Plan your steps to update SSL certificates to determine the steps needed to update the SSL certificates.
- Enter the numbers representing the services to update.
To update more than one SSL certificate, separate the numbers with a comma. For example, to update the SSL certificates on Single Sign-On, vCenter Server, and the vSphere Web Client, type:
1,3,4
To update the certificate on all services that are supported by the tool, type 8
. The menu selections show all of the supported services.
Note: The vSphere Web Client and the Log Browser reside on the same machine.
- The Update Steps Planner shows what you need to do and the order in which to do it. Perform the tasks in the order the Planner presents.
Note: When using the Update Steps Planner, enter all of the services you update. If you enter the services separately, the Planner cannot correctly determine the order of the steps. Performing the steps in the incorrect order can cause the update process to fail. To ensure that you have the order correct, leave the console open to the full list of steps or save the list to a text file. This allows you to track your progress.
- After making a copy of the output, type
9
to return to the main menu.
After completing these steps, proceed to the
Updating SSL Certificates and trusts section, unless you need to generate Certificate Requests beforehand.
Generating Certificate Requests
The SSL Certificate Automation Tool provides the functionality to create certificate requests. This functionality helps prevent common configuration issues when generating supported certificates for use with the vCenter Server services.
For instructions on using the new certificate request functionality and generating supported certificates for the vCenter Server services, see
Generating certificates for use with the VMware SSL Certificate Automation Tool (2044696).
Note: The SSL Certificate Automation Tool provides the functionality to create certificate requests and does not create the final certificate. The certificate requests must be provided to a Certificate Authority (CA) to produce the final, signed certificate before proceeding to the next step.
Updating SSL Certificates and trusts
The Update Steps Planner shows the exact steps that must be followed (given the services selected) to ensure successful completion. To simplify the process, the services are listed individually in the main menu with the trust and certificate update options for each specific service.
For example, to update the Inventory Service configuration, choose
Inventory Service from the menu. You are then prompted with the
Update the Inventory Service Trust to Single Sign-On and
Update the Inventory Service SSL Certificate options in this menu.
The workflow is simple and you must run these commands one after another.
Note: The Ctrl+C option to cancel the current command does not work while running the tool.
After you select an option, enter the information when prompted, such as the locations of the new SSL chain and private key and passwords.
Note: Include the full path to the
chain.pem file for the certificate update to work correctly. For example:
C:\VMware\SSO\Certs\chain.pemWhen complete, the operation proceeds and either a success message is presented or an error explaining the problem is reported. For more information on troubleshooting failures, see the
Troubleshooting section of this article.
After a step is successful, proceed to the next step as described in the Update Steps Planner. You might need to navigate to a different machine to continue the process. If this is necessary, deploy and start the tool on the applicable machine.
Note: Keep the tool running on each machine to save time and to avoid re-entering input because the Update Steps Planner might require that you return to that machine for a later step.
After all the steps provided by the Update Steps Planner are complete, you have successfully updated your certificates. Proceed to the
Exiting the SSL Certificate Automation Tool section.
Exiting the SSL Certificate Automation Tool
After you have completed your update plan, you can select the appropriate menu options to exit from the tool. Closing the command prompt window also stops the current session and any incomplete or in-process actions are lost.
Note: The Ctrl+C option to cancel the current command does not work while running the tool. You must either close the window and launch the tool again or enter invalid data to force a failure.
Troubleshooting
If a specific update command fails, there are several options that you can use to troubleshoot.
RollbackThe SSL Certificate Automation Tool has a built-in rollback functionality. During the update operation, each action taken backs up the original state that the service configuration was in. If, for any reason, the update is not successful, you might need to roll back the failed step.
For each service, there is an option to rollback the configuration. Run this command to restore the state of the configuration that was in place before beginning the update process. The SSL Certificate Automation Tool automatically saves a copy of the existing certificate configuration in a backup folder, ensuring that you can roll back to the previously used certificate to keep the entire system up and running.
Note: After rolling back the vCenter Server certificate, you must update the vCenter Server trust to the VMware Update Manager again.
The SSL Certificate Automation Tool logTo determine the cause of a failure, updates and actions are logged for each command. By default, the logs are available in the
/log
directory within the directory to which the SSL Certificate Automation Tool has been extracted. If your corporate policy or environment requires it, you can change the log folder before starting the tool. Set the default log directory using the
LOGS_FOLDER
variable in the
ssl-environment.bat
file.
To review the log:
- Open the
SSL_Certificate_Automation_Tool_Directory/logs
directory. - Locate the log for the action you want to verify. For example, the
sso-update-ssl.log
file. If there are multiple logs for the same action, use the log file date and time to determine the correct log file to use. - Open the log file with any text editor and search for the error during the execution.
After you have identified the issue by searching the log file, correct the problem and execute the failed step again.
For more information, see the
Known Issues section.
Known Issues
This section lists known issues when using the SSL Certificate Automation Tool. Ensure that you review this list to determine if your environment may be affected:
- No error when you replace the certificate for a service with a certificate already in use by a service.
If you are using the Certificate Automation Tool to replace certificates, and you respond to the prompts by replacing an existing certificate with a certificate already in use by a service, the tool does not display an error message. The tool proceeds with the replacement. Because each service must have a unique certificate in the vCenter Server installation on Windows, authentication does not work properly.
Currently, there is no workaround.
- SSL Certificate Update fails if vCenter Single Sign-On Password contains spaces or special characters such as &, ^, %, <.
If the vCenter Single Sign-On password has a space or any special characters, such as &, ^, %, or <, the configuration of the Inventory service fails.
To work around this issue, change the vCenter Single Sign-On password so it does not contain a space or any of the special characters &, ^, %, < in it.<br> - If the certificate chain file for vCenter Single Sign-On is out-of-order, you see an error similar to:
Certificate chain is incomplete: the root authority certificate is not present and could not be detected automatically. The presence of the root certificate is required so the other service can establish trust to this service. Try adding the authority certificate manually.
To resolve this issue, ensure that the certificate chain file for vCenter Single Sign-On is created in the correct order. For more information, see Generating certificates for use with the VMware SSL Certificate Automation Tool (2044696).
- vCenter Server to vCenter Single Sign-On Trust operation fails causing the tool to exit abruptly.
If there are spaces in the path used for the certificates, the vCenter Server to Single Sign-On Trust update operation fails, causing the tool to abruptly exit.
To work around this issue, remove spaces in the path to the SSL certificates.
- CSR Generation fails if the SSL certificate Automation Tool folder name contains spaces.
Ensure that the name of the directory in which the SSL Certificate Automation Tool is extracted and the specified CSR directory above do not have spaces. If not, the CSR Generation fails.
- If the path to the certificate chains is incorrect, you see the error:
Exception in thread "main" java.io.FileNotFoundException: C:\certs\wrongfile\rui.crt (The system cannot find the file specified)
at java.io.FileInputStream.open(Native Method)
at java.io.FileInputStream.<init>(Unknown Source)
This is an expected behavior.
To resolve this issue, correct the path to the chain file and run the step again.
- When connecting to the VMware Inventory service in Linked Mode Configurations, you see the error:
Client Not authenticated
When updating all certificates while running in a Linked mode configuration, you may not be able to log in to the inventory service for 10 minutes after the certificates have been updated. After this time, authentication is successful and functionality is restored.
- SSL Certificate Automation Tool may fail if custom ports are used for components.
If custom ports are used for the installation of vCenter Server services, configuration of certificates with the SSL Certificate Automation Tool may fail. This is a known issue.
To work around this issue, use the default ports.