Backend SSL/TLS

Description

Varnish Enterprise has support for using SSL/TLS on backend connections. This means that any miss, pass or piped requests handled by Varnish Enterprise will be encrypted https requests when sent over the network to a backend/origin server.

VCL example

backend default {
	.host = "backend.example.com";
	.port = "443";
	.ssl = 1;				# Turn on SSL support
	.ssl_sni = 1;			# Use SNI extension  (default: 1)
	.ssl_verify_peer = 1;	# Verify the peer's certificate chain (default: 1)
	.ssl_verify_host = 1;	# Verify the host name in the peer's certificate (default: 0)
}

Backend SSL/TLS usage is enabled by setting .ssl = 1 in the backend definition. The port used will default to 443 unless set explicitly.

By default the connections will have an SNI extension name provided during negotiation. This defaults to the .host attribute, unless if the .host_header attribute is set in which case that will be used instead.

Configuration

• .ssl

  Set this true (1) to enable SSL/TLS for this backend.

• .ssl_sni [default: 1]

  Set this to false (0) to disable the use of the Server Name Indication (SNI) extension for backend TLS connections. SNI allows a backend to serve multiple TLS domains over a single IP and port. The SNI name defaults to the backend .host value, unless .host_header is defined, in which case it will be used as the SNI name.

• .ssl_verify_peer [default: 1]

  Set this to false (0) to disable verification of the peer’s certificate chain. This allows a backend to use a self signed certificate.

• .ssl_verify_host [default: 0]

  Set this to true (1) to enable verification of the peer’s certificate identity. The identity in the certificate is verified against the name configured in the host attribute, unless host_header is set in which case that is used instead. If disabled, this allows a backend to use an invalid certificate.

• .host_header

  A host header to add to probes and regular backend requests if they have no such header. Also used for SNI and certificate host verification.

• .certificate

  Specifies a client certificate to be used. The string is a client certificate identifier, and must match the ID of a loaded certificate. Failure to resolve a certificate will not fail loading the VCL, but it will produce 503 responses until a matching certificate is loaded. See below for more details.

If running a custom CA, the certificates used to verify the connections can be changed by setting the SSL_CERT_FILE and SSL_CERT_DIR environment variables. SSL_CERT_FILE can point to a single pem file containing a chain of certificates, while the SSL_CERT_DIR can be a comma-separated list of directories containing pem file with symlinks by their hash key (see the man page of c_rehash from the OpenSSL library for more information).

Client certificate configuration

Loading a client certificate for backend connections can be done either as a command line option on varnishd startup, or it can be done live on a running setup using a CLI command.

The certificate file must be in PEM format, and must contain a private key and a certificate. Optionally, it may also contain any number of intermediate certificates, if applicable.

Loading client certificates on startup

Loading a client certificate on startup can be done using the -z argument when starting Varnish, via -z id=certfile. Using e.g. -z mycert=/path/to/mycert.pem will load the certificate PEM file /path/to/mycert.pem under the ID mycert.

The -z argument can be specified multiple times to load multiple certificates.

varnishadm: backend.cert.load

Client certificates can also be loaded in a running setup using varnishadm’s backend.cert.load command.

varnish> backend.cert.load mycert /path/to/mycert.pem
200
Certificate 'mycert' initialized

A certificate can at any point be reloaded by issuing a backend.cert.load with an already existing ID. The reload will take effect immediately, with no VCL or daemon reload necessary.

varnishadm: backend.cert.list

varnishadm’s backend.cert.list command will produce a list of the currently loaded certificates.

varnish> backend.cert.list
200
active       1  mycert     /path/to/cert/mycert.pem       Aug 31 08:39:15 2022 GMT
active       1  othercert  /path/to/cert/othercert.pem    Sep 17 12:01:13 2021 GMT

The included timestamp is the certificate’s notAfter property, and is included merely for informational purposes.

varnishadm: backend.cert.discard

backend.cert.discard is used to discard a loaded certificate.

varnish> backend.cert.discard mycert
200
Certificate 'mycert' discarded successfully

A discarded certificate may linger for some time waiting for ongoing backend transactions to finish before it is discarded. Discarded yet lingering certificates will show up as dying (as opposed to active) in the backend.cert.list listing.

Installation

Support for backend SSL/TLS is built into in supported versions of Varnish Cache Plus, and does not require any extra installation steps.

Backend SSL/TLS introduces a requirement for OpenSSL which is maintained and updated through the operating system. When using this functionality it is important to follow security best practices and keep the systems update to avoid loss of confidentiality.

Availability

Backend SSL/TLS support was added to Varnish Enterprise starting from Varnish Cache Plus 4.0.3r3, and is also available in all versions of Varnish Enterprise 4.1 and 6.0.

Support for client certificates for backend connections was added in version 6.0.7r1.