.. role:: ref(emphasis)

.. _varnish-tls-conf(7):

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

.. _here: https://wiki.mozilla.org/Security/Archive/Server_Side_TLS_4.0#Pre-defined_DHE_groups

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.

client-verify-crl = <string>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Specifies a PEM-encoded CRL (Certificate Revocation List) file.
Clients presenting a certificate that appears in the CRL will have
their TLS handshake rejected.

The CRL file should contain CRLs issued by the CAs specified in
``client-verify-ca``. If the CRL does not cover all CAs, behavior
depends on the ``tls_crl_strict`` parameter:

- When ``tls_crl_strict`` is ``on`` (default), clients from CAs
  without a matching CRL are rejected.
- When ``tls_crl_strict`` is ``off``, clients from CAs without a
  matching CRL are accepted.

Expired or not yet valid CRLs are treated the same way: rejected
when strict, accepted when non-strict.

Note that this parameter only controls how missing, expired, or
not yet valid CRLs are handled. Certificates that appear in a CRL
are always rejected,
regardless of this setting.

Requires ``client-verify-ca`` to be configured.

This option is also available in a ``frontend`` block.

When using ``tls.cert.load``, the equivalent flag is ``-R crl-file``.

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``.

COPYRIGHT
=========

* Copyright (c) 2020 Varnish Software AS

* Author: Dag Haavi Finstad <daghf@varnish-software.com>
