Restrict Access to the Docker API with Auto-Generated Certificates
As a convenience,
vic-machine create provides the option of automatically generating a client certificate, server certificate, and certificate authority (CA) as appropriate when you deploy a VCH. The generated certificates are functional, but they do not allow for fine control over aspects such as expiration, intermediate certificate authorities, and so on. To use more finely configured certificates, see Restrict Access to the Docker API with Custom Certificates.
VCHs accept client certificates if they are signed by a CA that you provide by specifying one or more instances of the
--tls-ca option. In the case of the certificates that
vic-machine create generates,
vic-machine create creates a CA and uses it to create and sign a single client certificate.
When using the Docker client, the client validates the server either by using CAs that are present in the root certificate bundle of the client system, or that are provided explicitly by using the
--tlscacert option when running Docker commands. As a part of this validation, the server certificate must explicitly state at least one of the following, and must match the name or address that the client uses to access the server:
- The FQDN used to communicate with the server
- The IP address used to communicate with the server
- A wildcard domain that matches all of the FQDNs in a specific subdomain. For an example of a domain wildcard, see https://en.wikipedia.org/wiki/Wildcard_certificate#Example.
This topic includes the following sections.
vic-machine create options in this section allow you to deploy a VCH that uses auto-generated certificates to validate client connections.
Certain options in this section are exposed in the
vic-machine create help if you run
vic-machine create --extended-help, or
vic-machine create -x.
Short name: None
The FQDN or IP address to embed in an auto-generated server certificate. Specify an FQDN, IP address, or a domain wildcard. If you provide a custom server certificate by using the
--tls-server-cert option, you can use
--tls-cname as a sanity check to ensure that the certificate is valid for the deployment.
If you do not specify
--tls-cname but you do set a static address for the VCH on the client network interface,
vic-machine create uses that address for the Common Name, with the same results as if you had specified
--tls-cname=x.x.x.x. For information about setting a static IP address on the client network, see Specify a Static IP Address for the VCH Endpoint VM.
When you specify the
vic-machine create performs the following actions during the deployment of the VCH:
- Checks for an existing certificate in either a folder that has the same name as the VCH that you are deploying, or in a location that you specify in the
--tls-cert-pathoption. If a valid certificate exists that includes the same Common Name attribute as the one that you specify in
vic-machine createreuses it. Reusing certificates allows you to delete and recreate VCHs for which you have already distributed the certificates to container developers.
- If certificates are present in the certificate folder that include a different Common Name attribute to the one that you specify in
- If a certificate folder does not exist,
vic-machine createcreates a folder with the same name as the VCH, or creates a folder in the location that you specify in the
- If valid certificates do not already exist,
vic-machine createcreates the following trusted CA, server, and client certificate/key pairs in the certificate folder:
- Creates a browser-friendly PFX client certificate,
cert.pfx, to use to authenticate connections to the VCH Admin portal for the VCH.
NOTE: The folder and file permissions for the generated certificate and key are readable only by the user who created them.
vic-machine create with the
--tls-cname option also creates an environment file named
vch_name.env, that contains Docker environment variables that container developers can use to configure their Docker client environment:
- Activates TLS client verification.
- The path to the client certificates.
- The address of the VCH.
You must provide copies of the
key.pem client certificate files and the environment file to container developers so that they can connect Docker clients to the VCH. If you deploy the VCH with the
--tls-cname option, container developers must configure the client appropriately with one of the following options:
- By using the
tlskeyoptions in Docker commands, adding
tlscacertif a custom CA was used to sign the server certificate.
- By setting the
DOCKER_TLS_VERIFY=1Docker environment variables.
For more information about how to connect Docker clients to VCHs, see Configure the Docker Client for Use with vSphere Integrated Containers.
Short name: none
--tls-cert-path is a folder in the current directory, that takes its name from the VCH name that you specify in the
--name option. If specified,
vic-machine create checks in
--tls-cert-path for existing certificates with the standard names and uses those certificates if they are present:
vic-machine create does not find existing certificates with the standard names in the folder you specify in
--tls-cert-path, or if you do not specify certificates directly by using the
vic-machine create generates certificates. Generated certificates are saved in the
--tls-cert-path folder with the standard names listed.
vic-machine create additionally generates other certificates:
key.pemfor client certificates, if required.
ca-key.pem, the private key for the certificate authority.
The size of the key for
vic-machine create to use when it creates auto-generated trusted certificates. If you specify
--tls-cname, you can optionally specify
--certificate-key-size. If not specified,
vic-machine create creates keys with default size of 2048 bits. It is not recommended to use key sizes of less than 2048 bits.
Short name: None
A list of identifiers to record in certificates generated by
vic-machine. If you specify
--tls-cname, you can optionally use
--organization to add basic descriptive information to the server certificate. This information is visible to clients if they inspect the server certificate. If not specified,
vic-machine create uses the name of the VCH as the
client-ip-address is used for
CommonName but not for
This example deploys a VCH that implements client authentication with trusted auto-generated TLS certificates that are signed by a CA.
To automatically generate a server certificate that can pass client verification, you must specify the Common Name (CN) for the certificate by using the
--tls-cname option. The CN should be the FQDN or IP address of the server, or a domain with a wildcard. The CN value must match the name or address that clients will use to connect to the server.
If you specify an existing CA file with which to validate clients, you must also provide an existing server certificate that is compatible with the
--tls-cname value or the IP address of the client interface.
This example deploys a VCH with the following configuration:
- Specifies the user, password, datacenter, image store, cluster, bridge network, and name for the VCH.
- Provides a wildcard domain
*.example.orgas the FQDN for the VCH, for use as the Common Name in the certificate. This assumes that there is a DHCP server offering IP addresses on VM Network, and that those addresses have corresponding DNS entries such as
- Specifies a folder in which to store the auto-generated certificates.
- Sets the certificate's
O) field to
- Generates a certificate with a key size of 3072 bits.
vic-machine-operating_system create --target 'Administrator@vsphere.local':password@vcenter_server_address/dc1 --compute-resource cluster1 --image-store datastore1 --bridge-network vch1-bridge --tls-cname *.example.org --tls-cert-path path_to_cert_folder --organization 'My Organization' --certificate-key-size 3072 --thumbprint certificate_thumbprint --name vch1
The Docker API for this VCH will be accessible at https://dhcp-a-b-c.example.org:2376.
You can also deploy a VCH to use custom server certificates in combination with auto-generated client certificates, as demonstrated in the example Combine Custom Server Certificates and Auto-Generated Client Certificates.