1HITCH.CONF(5) HITCH.CONF(5)
2
6 Hitch.conf - Configuration file for Hitch
7
9 hitch.conf is the configuration file for hitch(8). The configuration
10 file is loaded using the Hitch option --config=, and can thus have dif‐
11 ferent names and can exist in different locations.
12 Almost all options available in hitch.conf can be specified or overrid‐
14 den in the command line of Hitch, as described in hitch(8).
15 The Hitch configuration file consists of a series of option assign‐
17 ments. Some options (pem-file, frontend) can be be set several times,
18 and the effect is that multiple certificate files and "listening front‐
19 ends" are defined. Other options can only be assigned once.
20 The hash mark, or pound sign ("#"), is used as a "comment" character.
22 You can use it to annotate your config file. All text after the comment
23 character to the end of the line is ignored. Empty lines are ignored.
24
26 Options can either be in the top level of the configuration file
27 (global scope), or inside a frontend block. Options inside a frontend
28 block only affect the frontend, while options in the top level sets de‐
29 faults for all frontends.
30 Unless otherwise noted below, options can only be used in the top
32 level.
33 alpn-protos = <protocol-list>
35 Comma separated list of protocols supported by the backend in a quoted
36 string. The list is used select protocols when the client supports Next
37 Protocol Negotiation (NPN) or Application-Layer Protocol Negotiation
38 (ALPN). If Hitch is compiled against a OpenSSL version that does not
39 support ALPN, only NPN will be used to select a protocol.
40 The result of the NPN/ALPN negotiation will be communicated to the
42 backend if and only if write-proxy-v2 or proxy-proxy is used. For
43 HTTP/2 to work with modern browsers, ALPN negotiation is required.
44 backend = ...
46 The endpoint Hitch connects to when receiving a connection. Only a sin‐
47 gle backend is supported.
48 This is either specified as "[HOST]:port" for IPv4/IPv6 endpoints:
50 backend = "[localhost]:8080"
52 Or it can be specified as a path to a UNIX domain socket:
54 backend = "/path/to/sock"
56 backlog = <number>
58 Listen backlog size
59 chroot = <string>
61 Chroot directory
62 ciphers = ...
64 List of ciphers to use in the secure communication. Refer to the
65 OpenSSL documentation for a complete list of supported ciphers.
66 Each cipher in the list must be separated by a colon (:), in order of
68 preference. See ciphers(1) for further description of the format.
69 If not specified, OpenSSL will allow all ciphers. System administrators
71 are advised to either only support strong ciphers (as in the example
72 file below) or to pay close attention to security advisories related
73 OpenSSL's ciphers.
74 This option applies to TLSv1.2 and below. For TLSv1.3, see cipher‐
76 suites.
77 This option is also available in frontend blocks.
79 ciphersuites = <string>
81 Specifies available ciphersuites for TLSv1.3. Similar to ciphers, en‐
82 tries must be separated by colon (:) and sorted in order of preference.
83 This option is also available in frontend blocks.
85 client-verify = required|optional|none
87 Configures client certificate validation. The setting must be one of
88 none, required or optional.
89 The default setting is client-verify = none, in which case Hitch will
91 not send a certificate request to the client.
92 If client-verify = require is configured, Hitch will only permit con‐
94 nections that present a valid certificate. The certificate will be ver‐
95 ified using the certificate provided in the client-verify-ca parameter.
96 If optional, Hitch will send certificate requests, but still permit
98 connections that do not present one.
99 For settings optional and required, we also require that the
101 client-verify-ca is configured.
102 This option is also available in frontend blocks. If specified in a
104 frontend block, the client verification setting will only apply to the
105 pem-file records for that particular frontend.
106 client-verify-ca = <string>
108 Specifies a file containing the certificates of the CAs that will be
109 used to verify a client certificate.
110 For multiple CAs, this file can be a concatenation of multiple
112 pem-files for the relevant certificate authorities.
113 This option is also available in frontend blocks.
115 daemon = on|off
117 Run as daemon. Default is off.
118 frontend = ...
120 This specifies the port and interface (the listen endpoint) that Hitch
121 binds to when listening for connections. It is possible define several
122 frontends, and Hitch will bind to several ports and/or several inter‐
123 faces.
124 If "*" is used as the host, then Hitch will bind on all interfaces for
126 the given port.
127 A frontend can be specified either in a single line:
129 frontend = "[HOST]:PORT[+CERT]"
131 Or in a frontend block:
133 frontend = {
135 host = "HOST"
136 port = "PORT"
137 <other frontend options>
138 }
139 group = <string>
141 If given, Hitch will change to this group after binding to listen sock‐
142 ets.
143 keepalive = <number>
145 Number of seconds a TCP socket is kept alive
146 backend-refresh = <number>
148 Number of seconds between periodic backend IP lookups, 0 to disable.
149 Default is 0.
150 ocsp-dir = <string>
152 Directory where Hitch will store and read OCSP responses for stapling.
153 Default is "/var/lib/hitch/".
154 Directory must be readable and writable for the configured Hitch user,
156 or automatic retrieval and updating of OCSP responses will not take
157 place.
158 If you have a manually pre-loaded OCSP staple, an alternative pem-file
160 syntax can be used for stapling:
161 pem-file = {
163 cert = "mycert.pem"
164 ocsp-resp-file = "ocsp-resp.der"
165 }
166 ocsp-connect-tmo = <number>
168 OCSP fetch connect timeout.
169 This does normally not need to be changed.
171 Default is 4.0 seconds.
173 ocsp-resp-tmo = <number>
175 OCSP fetch response timeout.
176 This does normally not need to be changed.
178 Default is 10 seconds.
180 ocsp-refresh-interval = <number>
182 OCSP refresh interval.
183 If the OCSP response does not carry any refresh information, use this
185 as the interval for refreshing.
186 Default is 1800 seconds.
188 ocsp-verify-staple = on|off
190 If set, OCSP responses will be verified against the certificate after
191 retrieval.
192 Default is off.
194 pem-file = <string>
196 Specify a SSL x509 certificate file. Server Name Indication (SNI) is
197 supported by using one certificate file per SNI name.
198 A file suitable for Hitch is a concatenation of a private key and a
200 corresponding certificate or certificate chain.
201 At least one PEM file is needed for Hitch to start, but it can be sup‐
203 plied on the command line.
204 Certificates are used in the order they are listed; the last certifi‐
206 cate listed will be used if none of the others match.
207 In the event that we have multiple certificates that provide the same
209 SNI string, an error will be logged. The last loaded certificate will
210 in that case take precendence.
211 For partial overlap in names, e.g. if one certificate provides "www.ex‐
213 ample.com" and another one "*.example.com", the most specific match
214 will always take precendence at SNI lookup.
215 This option is also available in a frontend declaration, to make a cer‐
217 tificate only available for a specific listen endpoint.
218 private-key = <string>
220 If set, the private key is read from specified location, not from the
221 cert file.
222 pem-file = {
224 cert = "mycert.pem"
225 private-key = "myprivate.key"
226 }
227 pem-dir = <string>
229 Specify a directory for loading x509 certificates.
230 A fallback certificate for non-SNI clients may be specified by also in‐
232 cluding a separate pem-file definition.
233 The files are processed in lexicographic order. In the absence of any
235 pem-file definitions, the first file entry will be used as the fallback
236 default.
237 pem-dir = "/etc/hitch/cert.d"
239 pem-dir-glob = <string>
241 Matching filter for filenames loaded from pem-dir.
242 Default is none (match any).
244 pem-dir-glob = "*.pem"
246 prefer-server-ciphers = on|off
248 Turns on or off enforcement of the cipher ordering set in Hitch.
249 This option is also available in frontend blocks.
251 Default is off.
253 proxy-proxy = on|off
255 Proxy an incoming PROXY protocol header through to the backend. Sup‐
256 ports both version 1 and 2 of the PROXY protocol.
257 This option is mutually exclusive with option write-proxy-v2, write-ip
259 and write-proxy-v1.
260 Default is off.
262 log-level = <num>
264 Log chattiness. 0=silence, 1=errors, 2=info/debug.
265 This setting can also be changed at run-time by editing the configura‐
267 tion file followed by a reload (SIGHUP).
268 Default is 0.
270 quiet = on|off
272 If quiet is turned on, only error messages will be shown. This setting
273 is deprecated in favor of log-level.
274 tls-protos = ...
276 The SSL/TLS protocols to be used. This is an unquoted list of tokens.
277 Available tokens are SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 and TLSv1.3.
278 The default is TLSv1.2 and TLSv1.3.
280 There are two deprecated options, ssl= and tls=, that also select pro‐
282 tocols. If "ssl=on" is used, then all protocols are selected. This is
283 known to be insecure, and is strongly discouraged. If "tls=on" is used,
284 the three TLS protocol versions will be used. Turning on SSLv3 and
285 TLSv1.0 is not recommended - support for these protocols are only kept
286 for backwards compatibility.
287 The availability of protocol versions depend on OpenSSL version and
289 system configuration. In particular for TLS 1.3, openssl 1.1.1 or later
290 is required.
291 For supporting legacy protocol versions you may also need to lower the
293 MinProtocol property in your OpenSSL configuration (typically
294 /etc/ssl/openssl.cnf).
295 This option is also available in frontend blocks.
297 ecdh-curve = <string>
299 Sets the list of supported TLS curves. A special value of auto will
300 leave it up to OpenSSL to automatically pick the most appropriate curve
301 for a client.
302 ecdh-curve = "X25519:prime256v1:secp384r1"
304 sni-nomatch-abort = on|off
306 Abort handshake when the client submits an unrecognized SNI server
307 name.
308 This option is also available in a frontend declaration.
310 ssl-engine = <string>
312 Set the SSL engine. This is used with SSL accelerator cards. See the
313 OpenSSL documentation for legal values.
314 syslog = on|off
316 Send messages to syslog. Default is off.
317 syslog-facility = <string>
319 Set the syslog facility. Default is "daemon".
320 user = <string>
322 User to run as. If Hitch is started as root, it will insist on changing
323 to a user with lower rights after binding to sockets.
324 workers = <number>
326 Number of worker processes. One per CPU core is recommended.
327 write-ip = on|off
329 Report the client ip to the backend by writing IP before sending data.
330 This option is mutually exclusive with each of the options
332 write-proxy-v2, write-proxy-v1 and proxy-proxy.
333 Default is off.
335 write-proxy-v1 = on|off
337 Report client address using the PROXY protocol.
338 This option is mutually exclusive with option write-proxy-v2, write-ip
340 and proxy-proxy.
341 Default is off.
343 write-proxy-v2 = on|off
345 Report client address using PROXY v2 protocol.
346 This option is mutually exclusive with option write-ip, write-proxy-v1
348 and proxy-proxy.
349 Default is off.
351 proxy-tlv = on|off
353 Report extra information as part of the PROXYv2 header.
354 Currently the following will be transmitted when proxy-tlv is enabled:
356 • Cipher
358 • Protocol version
360 • Client certificate verification result
362 • Whether the client transmitted a certificate as part of this con‐
364 nection/session (PP2_CLIENT_CERT_CONN, PP2_CLIENT_CERT_SESS)
365 Default is on.
367 proxy-client-cert = on|off
369 Transmit the authenticated client certificate as part of the PROXYv2
370 header.
371 The PEM-formatted client certificate will be transmitted as a TLV field
373 of type 0xe0.
374 This is a custom application-specific type, requiring a a custom han‐
376 dler at the recipient end. Note that using this feature will inflate
377 the size of the PROXY header substantially, possibly also requiring
378 tweaking at the receiving end.
379 tcp-fastopen = on|off
381 Enable TCP Fast Open.
382 Default is off.
384
386 The following file shows the syntax needed to get started with:
387 frontend = {
389 host = "*"
390 port = "443"
391 }
392 backend = "[127.0.0.1]:6086" # 6086 is the default Varnish PROXY port.
393 workers = 4 # number of CPU cores
394 daemon = on
396 # We strongly recommend you create a separate non-privileged hitch
398 # user and group
399 user = "hitch"
400 group = "hitch"
401 # Enable to let clients negotiate HTTP/2 with ALPN. (default off)
403 # alpn-protos = "h2, http/1.1"
404 # run Varnish as backend over PROXY; varnishd -a :80 -a localhost:6086,PROXY ..
406 write-proxy-v2 = on # Write PROXY header
407
409 This manual was written by Pål Hermunn Johansen <‐
410 hermunn@varnish-software.com>
411 HITCH.CONF(5)