varnish-tls-conf

Varnish TLS configuration file

Manual section:7

DESCRIPTION

Configuring TLS in Varnish is done in a separate configuration file, which is passed to Varnish via the -A parameter.

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.

Note that 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

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.

frontend = …

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 also be given a name, which will be referenced in logs.

A frontend can be specified either in a single line:

frontend = "[HOST]:PORT"

Or in a frontend block:

frontend = {
    host = "HOST"
    port = "PORT"
    name = "mylistener"
    <other frontend options>
}

Multiple frontend definitions are permitted. If Varnish is configured with a TLS configuration file, at least one frontend definition is required.

pem-file = …

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 pem-file block syntax also supports only specifying a cert argument pointing at a file containing certificate, private key and optionally DH parameters as described above.

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.

A certificate may be assigned an identifier for use in CLI certificate management operations by setting a name property,

pem-file = {
    cert = "/path/to/cert.pem"
    name = "mycert01"
}

Specifying DH parameters is recommended. This should preferably be one of the pre-defined DHE groups as specified in RFC 7919, as can be found here.

Alternatively DH parameters can 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.

Options ciphers and ciphersuites are also available in a pem-file block, and will have these settings apply specifically for that particular certificate. Specifying these options directly in the pem-file block will take precedence over any frontend or top-level specification.

ciphers = <string>

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 frontend and pem-file blocks.

ciphersuites = <string>

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 frontend and pem-file blocks.

prefer-server-ciphers = true|false

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.

tls-protos = …

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 is

tls-protos = TLSv1.2 TLSv1.3

This option is also available in a frontend block.

ecdh-curve = <string>

Sets the list of supported TLS curves.

ecdh-curve = "X25519:prime256v1:secp384r1"
client-verify = required|optional|none|optional_no_ca

Configures client certificate validation. The setting must be one of none, required, optional or optional_no_ca.

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 client-verify = 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.

If client-verify = optional_no_ca, Varnish will send certificate requests but does not require it to be signed by a trusted CA certificate. Varnish will still permit connections that do not present one.

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 specified for that particular frontend. If not specified in a frontend, the global setting will apply.

client-verify-ca = <string>

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.

sni-nomatch-abort = true|false

Setting this to true will abort the connection when the client submits an unrecognized SNI server name.

This behavior only applies for handshakes that involve an SNI extension. For the case where the client does not include a server name, the behavior is to use the default certificate.

This option is also available in a frontend block.

ssl-engine = <string>

Sets an openssl engine. This is used with an SSL accelerator card. See the OpenSSL documentation for legal values.

match-global-certs = true|false

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.