Varnish Controller


With the introduction of version 6.0.0, the controller now includes support for reloadable certificates. This functionality builds upon the capabilities initially presented in Varnish (see In-Process TLS). Through the agents, the controller can now upload certificates into Varnish, and this feature has also been implemented in the router making a single vclgroup deployment, including certificates, seamless.


Certificates can be associated with domains, and these domains are then linked to a VCLGroup. During the deployment of the VCLGroup, each certificate is applied on both the agent and router(if the router is used) through Server Name Indication (SNI). This guarantees that, for every domain, the designated certificate is loaded explicitly for its corresponding SNI. Additionally, for routing purposes, there is an option to attach a certificate specifically for the agents BaseURL, and there is the possibility to add a default certificate that overrides the certificate that can be added via the command line. This certificate will be served when there is no SNI-match and for the management port.

In the controller, a certificate serves as a container housing the actual certificate, key, and configuration details such as ciphers and TLS versions. When the actual certificate is updated, these changes are immediately reflected to the components the certificate is connected to.

Supported certificates

The controller supports x.509 certificates in unencrypted PEM format. These certificates can be linked to a particular domain, which must correspond to an entry in the Subject Alternative Name (SAN) list of the certificate. This alignment is achieved through either an exact match or a wildcard match.


Currently the controller supports two types of certificate storage, these are database or disk.


The certificate and key are stored in the database. Following the upload, direct user access to the certificate and private key is not possible via the CLI/API/UI. Only the certificate context, which includes details like expiration dates, Subject Alternative Names (SANs), and configuration, is available. Granting the controller access to the certificate context through the ‘database’ option empowers it to assist in tasks such as domain matching, displaying expiration dates, and more.


Only the paths to the certificate and key are stored in the database. During deployment, the agent or router searches for the certificate at the specified absolute path. Both the agent, varnish, and the router require direct access to the file. This method is more passive, as the controller does not retrieve the certificate content, and therefore, lacks access to the certificate context, including details such as expiry, SANs, etc.

Changes made to the certificate source on disk are automatically recognized by the agent or router. The updated certificate is utilized for incoming connections. Importantly, this option does not engage the controller in supporting domain matching, displaying expiry dates, or similar functionalities.

When a disk certificate is linked to a deployed VCLGroup (via a domain), modifying the paths to the certificate/private key is prohibited. This restriction is enforced through the API, requiring the VCLGroup to be undeployed first. This precaution prevents scenarios where the specified path is nonexistent or the certificate is not located at the assigned path.


For each certificate, the TLS version and cipher suites can be specified. This provides the flexibility to choose which cipher suites are allowed, offering control and customization based on specific requirements or preferences.

TLS Version

The controller currently accommodates TLS versions ranging from TLSv1.1 to TLSv1.3.

Cipher suites

Available cipher suites can be found via ciphersuites command:

$ vcli certificates ciphersuites
|               TLSv1.1                |                    TLSv1.2                    |           TLSv1.3            |
| TLS_RSA_WITH_AES_128_CBC_SHA         | TLS_RSA_WITH_AES_128_CBC_SHA                  | TLS_AES_128_GCM_SHA256       |
| TLS_RSA_WITH_AES_256_CBC_SHA         | TLS_RSA_WITH_AES_256_CBC_SHA                  | TLS_AES_256_GCM_SHA384       |
| TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | TLS_RSA_WITH_AES_256_GCM_SHA384               |                              |
| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA   | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA          |                              |
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA   | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA          |                              |
|                                      | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA            |                              |
|                                      | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA            |                              |
|                                      | TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256       |                              |
|                                      | TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384       |                              |
|                                      | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256         |                              |
|                                      | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384         |                              |
|                                      | TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256   |                              |
|                                      | TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 |                              |

Routing with certificates

When the router is activated, certificates are deployed to it in alignment with the certificates deployed in Varnish. Consequently, for each domain being routed with an active certificate, the respective certificate will be served based on the Server Name Indication (SNI) present in the client hello.

BaseURL certificate for routing.

Every routed request is directed towards the corresponding agent’s BaseURL, and it is possible to enable TLS for this by attaching a certificate to the agent. The certificate must align with the agent’s BaseURL. Utilizing a TLS certificate for the agent’s BaseURL ensures that health checks from the router are conducted over TLS.

Default certificate

The router originally supported command-line configuration for a single certificate. An enhancement now permits dynamic override or replacement of this certificate during runtime. This newly introduced capability enables the use of a replacement certificate as the default. Specifically, this certificate is served to requests that do not match any domain Server Name Indication (SNI) and to requests directed towards the management interface.

Important notes

To ensure that no other certificate will be served when there is no SNI match, sni-nomatch-abort can be used. This can be configured in the varnish instance.