HITCH.CONF(5)

✨ HITCH.CONF(5) ✨

okay bestie, welcome to hitch.conf — the configuration file for hitch(8), and honestly? it's giving ✨main character energy✨ for your TLS terminators. let's get into it 💅

---

🌸 NAME 🌸

Hitch.conf — the configuration file for Hitch, no cap 🎀

---

💖 DESCRIPTION 💖

so hitch.conf is literally the configuration file for hitch(8). you load it up with Hitch's --config= option, which means bestie, you can name it whatever you want and stash it wherever you want. it's flexible like that 🦋

almost every option you can put in hitch.conf can also be specified or overridden right there on Hitch's command line — all the deets live in hitch(8).

the config file is just a whole series of option assignments. some options (pem-file, frontend) can be set multiple times, and the vibe is: every time you set them, you're defining another certificate file and another "listening frontend". other options? one assignment only, periodt.

the hash mark, aka the pound sign ("#"), is your comment character 👑 use it to annotate your config file all you want — everything from the comment character to the end of the line gets ignored. empty lines? also ignored. iconic behaviour, honestly.

---

🌈 OPTIONS 🌈

options can live either at the top level of the config file (that's the global scope, bestie) or inside a frontend block. options inside a frontend block only affect that frontend, while top-level options set the defaults for all frontends 💫

unless it says otherwise below, an option can only be used at the top level. iykyk.

🧚 alpn-protos = <protocol-list>

a comma separated list of protocols the backend supports, wrapped in a quoted string. this list is what selects protocols when the client supports Next Protocol Negotiation (NPN) or Application-Layer Protocol Negotiation (ALPN). if Hitch was compiled against an OpenSSL version that doesn't support ALPN, then only NPN gets used to pick a protocol 🙈

the result of the NPN/ALPN negotiation gets communicated to the backend if and only if write-proxy-v2 or proxy-proxy is used. and for HTTP/2 to work with modern browsers? ALPN negotiation is required, no way around it 💅

🍓 backend = ...

the endpoint Hitch connects to whenever it receives a connection. only a single backend is supported, so pick your fave.

you can specify it as "[HOST]:port" for IPv4/IPv6 endpoints:

backend = "[localhost]:8080"

or you can give it a path to a UNIX domain socket:

backend = "/path/to/sock"

if the chroot setting is in effect, the UNIX domain socket path gets resolved at runtime from within the chroot, and you must specify the path it's accessible from inside the chroot. like, for a /run/hitch chroot and a /run/hitch/sock UNIX domain socket, you'd configure the backend argument as /sock. sneaky but important 🎀

🌸 backlog = <number>

listen backlog size

💜 chroot = <string>

chroot directory

✨ ciphers = ...

the list of ciphers to use in the secure communication. hit up the OpenSSL documentation for the complete list of supported ciphers.

each cipher in the list has to be separated by a colon (:), sorted in order of preference. see ciphers(1) for more on the format.

if you don't specify this, OpenSSL will allow all ciphers. system admins are advised to either only support strong ciphers (like in the example file below) or to pay very close attention to security advisories about OpenSSL's ciphers. stay safe out there 🫶

this option applies to TLSv1.2 and below. for TLSv1.3, go look at ciphersuites.

this option is also available in frontend blocks 👑

🎀 ciphersuites = <string>

specifies the available ciphersuites for TLSv1.3. similar to ciphers, entries must be separated by a colon (:) and sorted in order of preference.

this option is also available in frontend blocks 💫

🦋 client-verify = required|optional|none

configures client certificate validation. the setting must be one of none, required or optional.

the default is client-verify = none, and in that case Hitch will not send a certificate request to the client.

if client-verify = require is configured, Hitch will only permit connections that present a valid certificate. that certificate gets verified using the certificate provided in the client-verify-ca parameter.

if it's optional, Hitch will send certificate requests, but still permit connections that don't present one. chill like that.

for the optional and required settings, we also require that client-verify-ca is configured. non-negotiable bestie.

this option is also available in frontend blocks and pem-file blocks. if you specify it in a frontend block, the client verification setting will only apply to the pem-file records for that particular frontend. and you can refine it even further by using the option in a pem-file block — that has the effect of having it only apply to that particular pem-file record. so precise 💅

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

💖 daemon = on|off

run as daemon. default is off.

👑 frontend = ...

this specifies the port and interface (the listen endpoint) that Hitch binds to when listening for connections. you can totally define several frontends, and Hitch will bind to several ports and/or several interfaces. the more the merrier ✨

if "*" is used as the host, then Hitch will bind on all interfaces for the given port.

a frontend can be specified either on a single line:

frontend = "[HOST]:PORT[+CERT]"

or in a frontend block:

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

🧚 group = <string>

if given, Hitch will change to this group after binding to listen sockets.

🍓 keepalive = <number>

number of seconds a TCP socket is kept alive

💜 backend-refresh = <number>

number of seconds between periodic backend IP lookups, 0 to disable. default is 0.

🌸 ocsp-dir = <string>

directory where Hitch will store and read OCSP responses for stapling. default is "/var/lib/hitch/".

the directory must be readable and writable for the configured Hitch user, or automatic retrieval and updating of OCSP responses will not take place. so check those perms bestie 🔥

if you have a manually pre-loaded OCSP staple, an alternative pem-file syntax can be used for stapling:

pem-file = {
    cert = "mycert.pem"
    ocsp-resp-file = "ocsp-resp.der"
}

✨ ocsp-connect-tmo = <number>

OCSP fetch connect timeout.

this does normally not need to be changed.

default is 4.0 seconds.

🎀 ocsp-resp-tmo = <number>

OCSP fetch response timeout.

this does normally not need to be changed.

default is 10 seconds.

🦋 ocsp-refresh-interval = <number>

OCSP refresh interval.

if the OCSP response doesn't carry any refresh information, use this as the interval for refreshing.

default is 1800 seconds.

🌈 ocsp-verify-staple = on|off

if set, OCSP responses will be verified against the certificate after retrieval.

default is off.

💖 pem-file = <string>

specify a SSL x509 certificate file. Server Name Indication (SNI) is supported by using one certificate file per SNI name 💅

a file suitable for Hitch is a concatenation of a private key and a corresponding certificate or certificate chain.

at least one PEM file is needed for Hitch to start, but it can be supplied on the command line. so you're not forced to put it here, but you gotta have one somewhere.

certificates are used in the order they are listed; the last certificate listed will be used if none of the others match. last one standing, iconic.

in the event that we have multiple certificates that provide the same SNI string, an error will be logged. the last loaded certificate will in that case take precedence.

for partial overlap in names, e.g. if one certificate provides "www.example.com" and another one "*.example.com", the most specific match will always take precedence at SNI lookup. no cap.

this option is also available in a frontend declaration, to make a certificate only available for a specific listen endpoint.

👑 private-key = <string>

if set, the private key is read from the specified location, not from the cert file.

pem-file = {
    cert = "mycert.pem"
    private-key = "myprivate.key"
}

🧚 pem-dir = <string>

specify a directory for loading x509 certificates.

a fallback certificate for non-SNI clients may be specified by also including a separate pem-file definition.

the files are processed in lexicographic order. in the absence of any pem-file definitions, the first file entry will be used as the fallback default.

pem-dir = "/etc/hitch/cert.d"

🍓 pem-dir-glob = <string>

matching filter for filenames loaded from pem-dir.

default is none (match any).

pem-dir-glob = "*.pem"

💜 prefer-server-ciphers = on|off

turns on or off enforcement of the cipher ordering set in Hitch.

this option is also available in frontend blocks.

default is off.

🌸 proxy-proxy = on|off

proxy an incoming PROXY protocol header through to the backend. supports both version 1 and 2 of the PROXY protocol.

this option is mutually exclusive with the options write-proxy-v2, write-ip and write-proxy-v1. pick a lane bestie 😤

default is off.

✨ log-level = <num>

log chattiness. 0=silence, 1=errors, 2=info/debug.

this setting can also be changed at run-time by editing the configuration file followed by a reload (SIGHUP). live edits, we love to see it 💅

default is 0.

🎀 quiet = on|off

if quiet is turned on, only error messages will be shown. this setting is deprecated in favor of log-level. 👀

🦋 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 TLSv1.2 and TLSv1.3.

there are two deprecated options, ssl= and tls=, that also select protocols. if "ssl=on" is used, then all protocols are selected. this is known to be insecure, and is strongly discouraged. do not do this, bestie, i'm begging 😭 if "tls=on" is used, the three TLS protocol versions will be used. turning on SSLv3 and TLSv1.0 is not recommended — support for these protocols is only kept for backwards compatibility.

the availability of protocol versions depends on the OpenSSL version and system configuration. in particular for TLS 1.3, openssl 1.1.1 or later is required.

for supporting legacy protocol versions you may also need to lower the MinProtocol property in your OpenSSL configuration (typically /etc/ssl/openssl.cnf).

this option is also available in frontend blocks.

🌈 ecdh-curve = <string>

sets the list of supported TLS curves. a special value of auto will leave it up to OpenSSL to automatically pick the most appropriate curve for a client.

ecdh-curve = "X25519:prime256v1:secp384r1"

💖 sni-nomatch-abort = on|off

abort the handshake when the client submits an unrecognized SNI server name. bye felicia 💅

this option is also available in a frontend declaration.

👑 ssl-engine = <string>

set the SSL engine. this is used with SSL accelerator cards. see the OpenSSL documentation for legal values.

🧚 syslog = on|off

send messages to syslog. default is off.

🍓 syslog-facility = <string>

set the syslog facility. default is "daemon".

• user = <string> — the user to run as, bestie. If Hitch gets started as root, it will insist on changing to a user with lower rights after binding to sockets. Like, it's not staying root, no cap. 💅
• workers = <number>|auto — how many worker processes you want. One per CPU core is the recommended vibe. Using auto value creates 1 worker per CPU core. Slay. ✨
• write-ip = on|off — report the client ip to the backend by writing IP before sending data. 📝

This option is mutually exclusive with each of the options write-proxy-v2, write-proxy-v1 and proxy-proxy. So like, pick one, okay? 🙅‍♀️

Default is off.

• write-proxy-v1 = on|off — report client address using the PROXY protocol. 📡

This option is mutually exclusive with option write-proxy-v2, write-ip and proxy-proxy. Don't mix them, fr fr.

Default is off.

• write-proxy-v2 = on|off — report client address using PROXY v2 protocol. 💫

This option is mutually exclusive with option write-ip, write-proxy-v1 and proxy-proxy. You already know. 😌

Default is off.

• proxy-tlv = on|off — report extra information as part of the PROXYv2 header. 🔍

Currently the following will be transmitted when proxy-tlv is enabled:

• Cipher
• Protocol version
• Client certificate verification result
• Whether the client transmitted a certificate as part of this connection/session (PP2_CLIENT_CERT_CONN, PP2_CLIENT_CERT_SESS)

Default is on.

• proxy-client-cert = on|off — transmit the authenticated client certificate as part of the PROXYv2 header. 🔐

The PEM-formatted client certificate will be transmitted as a TLV field of type 0xe0.

This is a custom application-specific type, requiring a a custom handler at the recipient end. (Yes, double "a", we don't judge. 💀) Note that using this feature will inflate the size of the PROXY header substantially, possibly also requiring tweaking at the receiving end.

• tcp-fastopen = on|off — enable TCP Fast Open. 🚀

Default is off.

• backend-connect-timeout = <number> — configures the backend connect timeout. ⏱️
• ssl-handshake-timeout = <number> — configures the TLS handshake timeout. ⏳

---

🌟 EXAMPLE 🌟

The following file shows the syntax needed to get started with:

          frontend = {
              host = "*"
              port = "443"
          }
          backend = "[127.0.0.1]:6086"    # 6086 is the default Varnish PROXY port.
          workers = 4                     # number of CPU cores

          daemon = on

          # We strongly recommend you create a separate non-privileged hitch
          # user and group
          user = "hitch"
          group = "hitch"

          # Enable to let clients negotiate HTTP/2 with ALPN. (default off)
          # alpn-protos = "h2, http/1.1"

          # run Varnish as backend over PROXY; varnishd -a :80 -a localhost:6086,PROXY ..
          write-proxy-v2 = on             # Write PROXY header

👑 AUTHOR 👑

This manual was written by Pål Hermunn Johansen <hermunn@varnish-software.com>. Give them a round of applause, bestie! 👏💖

---

That's a wrap on HITCH.CONF(5) — the Hitch config manual, with its source/version and date chillin' in the footer like always. You're officially a Hitch config main character now. Byeee! 💅✨🦋