You can manage VMCA (VMware Certificate Authority), VECS (VMware Endpoint Certificate Store), VMware Directory Service (vmdir), and Security Token Service (STS) certificates by using a set of CLIs. The vSphere Certificate Manager utility supports many related tasks as well, but the CLIs are required for manual certificate management and for managing other services.

You normally access the CLI tools for managing certificates and associated services by using SSH to connect to the appliance shell. See the VMware knowledge base article at https://kb.vmware.com/s/article/2100508 for more information.

Manual vSphere Certificate Replacement gives examples for replacing certificates using CLI commands.

Table 1. vSphere CLI Tools for Managing Certificates and Associated Services
CLI Description See
certool Generate and manage certificates and keys. Part of VMCAD, the VMware Certificate Management service.

certool Initialization Commands Reference

vecs-cli Manage the contents of VMware Certificate Store instances. Part of VMware Authentication Framework Daemon (VMAFD). vecs-cli Command Reference
dir-cli Create and update certificates in VMware Directory Service. Part of VMAFD. dir-cli Command Reference
sso-config.sh Manage STS certificates. Command-line help. Entering sso-config.sh with no options displays the command-line help.
service-control Start or stop services, for example as part of a certificate replacement workflow.

Run this command to stop services before running other CLI commands.

vSphere CLI Locations

By default, you find the CLIs in the following locations. 

/usr/lib/vmware-vmafd/bin/vecs-cli
/usr/lib/vmware-vmafd/bin/dir-cli
/usr/lib/vmware-vmca/bin/certool
/opt/vmware/bin/sso-config.sh
Note: The service-control command does not require that you specify the path.

Required Privileges for Running vSphere CLIs

Required privileges depend on the CLI that you are using and on the command that you want to run. For example, for most certificate management operations, you have to be an administrator for the local vCenter Single Sign-On domain (vsphere.local by default). Some commands are available for all users.

dir-cli
You must be a member of the Administrators group in the local domain (vsphere.local by default) to run dir-cli commands. If you do not specify a user name and password, you are prompted for the password for the administrator of the local vCenter Single Sign-On domain, administrator@vsphere.local by default.
vecs-cli
Initially, only the store owner and users with blanket access privileges have access to a store. Users in the Administrators group have blanket access privileges.
The MACHINE_SSL_CERT and TRUSTED_ROOTS stores are special stores. Only the root user or the administrator user, depending on the type of installation, has complete access.
certool
Most of the certool commands require that the user is in the Administrators group. All users can run the following commands.
  • genselfcacert
  • initscr
  • getdc
  • waitVMDIR
  • waitVMCA
  • genkey
  • viewcert

Changing the certool Configuration Options

When you run certool --gencert or certain other certificate initialization or management commands, the command reads all the values from a configuration file. You can edit the existing file, override the default configuration file with the -–config=<file name> option, or override values on the command line.

The configuration file, certool.cfg, is located in the /usr/lib/vmware-vmca/share/config/ directory by default.

The file has several fields with the following default values: 

Country = US
Name= Acme
Organization = AcmeOrg
OrgUnit = AcmeOrg Engineering
State = California 
Locality = Palo Alto
IPAddress = 127.0.0.1	
Email = email@acme.com
Hostname = server.acme.com
Note: The OU (organizationalUnitName) field is no longer mandatory.
You can change the values by specifying a modified file on the command line, or by overriding individual values on the command line, as follows.
  • Create a copy of the configuration file and edit the file. Use the --config command-line option to specify the file. Specify the full path to avoid path name issues. 
  • /usr/lib/vmware-vmca/bin/certool -–gencert --config /tmp/myconfig.cfg
  • Override individual values on the command line. For example, to override Locality, run this command: 
    /usr/lib/vmware-vmca/bin/certool -–gencert -–privkey=private.key –-Locality="Mountain View"
Specify --Name to replace the CN field of the Subject name of the certificate.
  • For solution user certificates, the name is <sol_user name>@<domain> by convention, but you can change the name if a different convention is used in your environment.
  • For machine SSL certificates, the FQDN of the machine is used.

    VMCA allows only one DNSName (in the Hostname field) and no other Alias options. If the IP address is specified by the user, it is stored in SubAltName as well.

Use the --Hostname parameter to specify the DNSName of a certificate's SubAltName.