SearchVarnish Enterprise
In-Process TLS termination offers lower latency, improves data throughput (over 150Gbps), and removes the need for a separate TLS terminator greatly simplifying network topography.
Enabling TLS termination in Varnish is done either by specificing https as an option
to the -a parameter (e.g. -a :443,https) or in a separate configuration file, which is passed
to Varnish via the -A parameter.
Varnish offers a set of CLI commands for TLS that can be used to load and discard certificates.
Changes are performed in two steps, first actions are staged, then they are committed together as a transaction.
(You can also specify a number of certificates to load at start in a configuration file with -A, and then
do live updates using the CLI)
Staged and loaded certificates can be listed by running:
$ varnishadm tls.cert.list
tls.cert.list lists the frontend, the state (active or staged), the
certificate id and the expiration date. The frontend will be default if not
specified when loading the certificate.
Example list:
Frontend State Hostname Certificate ID Expiration date OCSP stapling
default active example.com cert0 Feb 29 13:38:00 2042 GMT true
default active www.example.com cert0 Feb 29 13:38:00 2042 GMT true
default staged www.example2.com cert0 Feb 29 13:37:00 2042 GMT true
A certificate is loaded by running:
$ varnishadm tls.cert.load MYID /etc/varnish/certs/mycert.pem
tls.cert.load takes an optional ID that used when discarding certificiates.
If not specified it will be generated and can later be found by listing the certificates
See the varnish-cli(7) manual page for more information and additional options.
A loaded certificate can be discarded by running:
$ varnishadm tls.cert.discard MYID
Staged changes gets committed by running:
$ varnishadm tls.cert.commit
Uncommitted changes can be rolled back by running:
$ varnishadm tls.cert.rollback
All loaded certificates will be reloaded from disk by running:
$ varnishadm tls.cert.reload
A successful reload is immediately committed. If an error is encountered during a reload, all changes will be rolled back and the previous state will be preserved.
Note: A reload is not allowed if there are uncommmitted changes to the TLS configuration.
The Varnish child needs to be running in order to load certificates over the CLI.
socket.close can be used to prevent any requests before all certificates
has been loaded.
Loading a certificate using a CLI file can look as following:
socket.close
start
tls.cert.load /etc/varnish/certs/mycert.pem
tls.cert.commit
socket.open
The configuration file format is based on Hitch’s config file. If you
have an existing Hitch configuration file, this can be passed to
Varnish and should work out of the box with the -A argument. For example:
$ varnishd -A /etc/hitch/hitch.conf -a :80 -s mse
Note: Varnish currently implements a subset of the settings available in Hitch. Not yet implemented configuration settings will be ignored.
The Varnish TLS configuration file consists of a series of option
assignments. Some options (pem-file, frontend) can be be set
several times, and the effect is that multiple certificate files and
listen endpoints are defined. Other options can only be assigned once.
The hash mark, or pound sign (#), is used as a comment
character. You can use it to annotate your config file. All text after
the comment character to the end of the line is ignored. Empty lines
are ignored.
An example minimal config may look like the following:
frontend = {
host = ""
port = "443"
}
pem-file = "/etc/varnish/certs/mycert.pem"
Options can either be in the top level of the configuration file
(global scope), or inside a frontend block. Options inside a
frontend block only affect the frontend, while options in the top
level sets defaults for all frontends.
Unless otherwise noted below, options can only be used in the top level.
This specifies the port and interface (the listen endpoint) that Varnish binds to when listening for connections. It is possible to define multiple frontends, and Varnish will bind to multiple ports and/or multiple interfaces.
If the host is specified as "*" or the empty string (""),
Varnish will bind on all interfaces for the given port.
A frontend can be specified either in a single line:
frontend = "[HOST]:PORT"
Or in a frontend block:
frontend = {
host = "HOST"
port = "PORT"
<other frontend options>
}
Multiple frontend definitions are permitted. If Varnish is
configured with a TLS configuration file, at least one frontend
definition is required.
Specifies an x509 certificate file. Can be specified multiple times to load multiple certificates.
pem-file can either be specified in a single line, where the
certificate, private key and optionally DH parameters are concatenated
into a single file,
pem-file = "/path/to/cert.pem"
or supplied as separate files in a pem-file block,
pem-file = {
cert = "/path/to/chain.pem"
private-key = "/path/to/priv.pem"
dhparam = "/path/to/dhparam.pem"
}
The certificate must be in PEM format, and must be sorted starting with the subject’s certificate first, followed by the intermediate CA certificate(s) if applicable.
Specifying DH parameters is recommended. These should be generated by running
$ openssl dhparam -out dh.pem 2048
Multiple certificates can be loaded by specifying multiple
pem-file definitions. Varnish will use Server Name Indication
(SNI) to decide which certificate is used.
If we are unable to find a match using SNI, or if the client did not
specify an SNI extension, the certificate specified last will be used
as a fallback (see also sni-nomatch-abort).
If pem-file is specified inside of a frontend block, the
certificate is only available for connections coming in via that
endpoint.
Specifies the list of ciphers to be used for secure
communication. Each cipher in the list must be separated by a colon
(:), in order of preference.
See ciphers(1) for further description of the format.
This option applies to TLSv1.2 and below. For TLSv1.3, see
ciphersuites.
This option is also available in a frontend block.
Specifies available ciphersuites for TLSv1.3. Similar to ciphers,
entries must be separated by colon (:) and sorted in order of
preference, e.g,
ciphersuites = "TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256"
This option is also available in a frontend block.
Specifies whether the server’s order of ciphers should be
enforced. true means the server chooses, false means the
client chooses.
This option is also available in a frontend block.
The SSL/TLS protocols to be used. This is an unquoted list of
tokens. Available tokens are SSLv3, TLSv1.0, TLSv1.1,
TLSv1.2 and TLSv1.3.
The default setting is:
tls-protos = TLSv1.2 TLSv1.3
This option is also available in a frontend block.
Sets the list of supported TLS curves.
ecdh-curve = "X25519:prime256v1:secp384r1"
Configures client certificate validation. The setting must be either
none, required or optional.
The default setting is client-verify = none, in which case Varnish
will not send a certificate request to the client.
If client-verify = require is configured, Varnish will only permit
connections that present a valid certificate. The certificate will be
verified using the CA provided in the client-verify-ca parameter.
If optional, Varnish will send certificate requests, but still
permit connections that do not present one.
For settings optional and required, we also require that the
client-verify-ca is configured.
This option is also available in a frontend block. If specified in
a frontend block, the client verification setting will only apply to
the pem-file records for that particular frontend.
Specifies a file containing the certificates of the CAs that will be used to verify a client certificate.
For multiple CAs, this file can be a concatenation of multiple pem-files for the relevant certificate authorities.
This option is also available in a frontend block.
Setting this to true will abort the connection when the client
submits an unrecognized SNI server name.
This option is also available in a frontend block.
Sets an openssl engine. This is used with an SSL accelerator card. See the OpenSSL documentation for legal values.
Only available in a frontend block. Specifies whether SNI matches
should be limited to certificates specified in the same frontend block
or not.
Defaults to true if there are no certificates specified for a
frontend, otherwise false.
Varnish supports automatic management and stapling of OCSP (Online Certificate Status Protocol) responses for TLS certificates.
By enabling the parameter tls_ocsp_auto, Varnish will automatically
fetch and load OCSP responses for all loaded certificates. The fetched
responses will be persisted to /var/lib/varnish-ocsp to avoid losing
the previously fetched responses in the event of a restart.
tls_ocsp_auto needs to be configured on startup by adding -p tls_ocsp_auto=on to the Varnish command line arguments.
Varnish will pay attention to the lifetime of the fetched OCSP response, and by default attempt to refresh an OCSP response after it has passed half of its lifetime.
These are regular Varnish parameters, settable from the command line
or from CLI param.set.
tls_ocsp_autoEnables automatic OCSP staple configuration. Must be configured from
the command line. Default value is off.
tls_ocsp_dirSpecifies the directory where Varnish keeps a persistent cache of OCSP
responses. Default value is /var/lib/varnish-ocsp.
tls_ocsp_fetch_limitSets the upper limit for the number of OCSP responses that can be fetched in parallel.
tls_ocsp_refresh_ratioDefines when to refresh an OCSP response, given as a ratio of the
response’s lifetime (i.e., the time between thisUpdate and nextUpdate
fields in the OCSP response). The default value here is 0.5,
meaning that the response will be refreshed after it has passed half
of its lifetime.
Client-side TLS is supported in Varnish Enterprise starting from
version 6.0.6r2 and is not supported on EL7 based platforms.
CLI support including dynamic reload functionality was added in 6.0.12r5.
OCSP support was added in 6.0.14r6.