Search
Varnish Enterprise

Client SSL/TLS termination

Description

The SSL/TLS addon in Varnish Enterprise is a complete setup for doing SSL/TLS (https) termination in front of Varnish Enterprise.

Varnish Enterprise SSL/TLS addon consists of a supported helper process (called “hitch”) that does SSL/TLS termination, and PROXY protocol support between the helper process and Varnish Enterprise.

Installation

The SSL/TLS addon can be installed with:

yum install varnish-plus-addon-ssl        # redhat systems

or

apt-get install varnish-plus-addon-ssl    # ubuntu based systems

This will download and install the addon from the Varnish Enterprise repositories.

Configuration


hitch-ports.png
Default hitch/Varnish port configuration

The SSL/TLS terminator, named hitch is already configured (versions >=1.4.5) to listen on all interfaces on port 443 in /etc/hitch/hitch.conf, and Varnish Enterprise is also packaged (>= 4.1.6) to listen on localhost:8443 that hitch uses as a backend.

The only configuration action needed is configuring the certificates, this is done in /etc/hitch/hitch.conf by editing the pem-file entry:

pem-file = "/etc/hitch/testcert.pem"

You can change this to point to your own certificate, and if you have more than one, simply add one pem-file statement per certificate.

Alternatively, to test your setup, you can generate a certificate using:

/etc/pki/tls/certs/make-dummy-cert /etc/hitch/testcert.pem

You can then persist and start the SSL/TLS helper process.

# persist
systemctl enable hitch        # on systemd machines
update-rc.d hitch defaults    # on Ubuntu Trusty
chkconfig hitch on            # on EL6

# start
service hitch start

Changing ports

Frontend

As explained, hitch will try to listen on port 443on all interfaces, as defined in /etc/hitch/hitch.conf:

frontend = {
    host = "*"
    port = "443"
}

Backend

The backend is specified as “[HOST]:port” for IPv4/IPv6 endpoints. By default hitch will find its backend at 127.0.0.1:8443 using the PROXY protocol. This is configured by the following lines:

backend = "[127.0.0.1]:8443"
write-proxy-v2 = on

Or it can be specified as a path to a UNIX domain socket(UDS):

backend = "/var/run/varnish.sock"

This configuration above must match the default configuration of Varnish Enterprise to listen on the same port, expecting the PROXY protocol:

For IPv4/IPv6 endpoints:

varnishd [...] -a 127.0.0.1:8443,PROXY

with UDS, the mode of the socket must be specified as well:

-a uds=/var/run/varnish.sock,proxy,user=varnish,group=varnish,mode=666

The -a argument can be specified multiple times in order to make varnish listen to multiple ports. This is useful when support for both http and https is needed. The following configuration will make varnish listen for HTTP on port 80 and PROXY on port 8443:

varnishd [...] -a :80 -a 127.0.0.1:8443,PROXY

Checking a request is secure

VCL code:

import std;
sub vcl_recv {
	# on PROXY connections the server.ip is the IP the client connected to.
	# (typically the DNS-visible SSL/TLS virtual IP)
	std.log("Client connected to " + server.ip);
	if (std.port(server.ip) == 443) {
		# client.ip for PROXY requests is set to the real client IP, not the
		# SSL/TLS terminating proxy.
		std.log("Real client connecting over SSL/TLS from " + client.ip);
	}
}

Availability

SSL/TLS addon was added to Varnish Enterprise starting from Varnish Enterprise 4.0.3r2.