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 fron‐
19 tends" 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
29 defaults 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,
82 entries must be separated by colon (:) and sorted in order of prefer‐
83 ence.
84 This option is also available in frontend blocks.
86 client-verify = required|optional|none
88 Configures client certificate validation. The setting must be one of
89 none, required or optional.
90 The default setting is client-verify = none, in which case Hitch will
92 not send a certificate request to the client.
93 If client-verify = require is configured, Hitch will only permit con‐
95 nections that present a valid certificate. The certificate will be ver‐
96 ified using the certificate provided in the client-verify-ca parameter.
97 If optional, Hitch will send certificate requests, but still permit
99 connections that do not present one.
100 For settings optional and required, we also require that the
102 client-verify-ca is configured.
103 This option is also available in frontend blocks. If specified in a
105 frontend block, the client verification setting will only apply to the
106 pem-file records for that particular frontend.
107 client-verify-ca = <string>
109 Specifies a file containing the certificates of the CAs that will be
110 used to verify a client certificate.
111 For multiple CAs, this file can be a concatenation of multiple
113 pem-files for the relevant certificate authorities.
114 This option is also available in frontend blocks.
116 daemon = on|off
118 Run as daemon. Default is off.
119 frontend = ...
121 This specifies the port and interface (the listen endpoint) that Hitch
122 binds to when listening for connections. It is possible define several
123 frontends, and Hitch will bind to several ports and/or several inter‐
124 faces.
125 If "*" is used as the host, then Hitch will bind on all interfaces for
127 the given port.
128 A frontend can be specified either in a single line:
130 frontend = "[HOST]:PORT[+CERT]"
132 Or in a frontend block:
134 frontend = {
136 host = "HOST"
137 port = "PORT"
138 <other frontend options>
139 }
140 group = <string>
142 If given, Hitch will change to this group after binding to listen sock‐
143 ets.
144 keepalive = <number>
146 Number of seconds a TCP socket is kept alive
147 backend-refresh = <number>
149 Number of seconds between periodic backend IP lookups, 0 to disable.
150 Default is 0.
151 ocsp-dir = <string>
153 Directory where Hitch will store and read OCSP responses for stapling.
154 Default is "/var/lib/hitch/".
155 Directory must be readable and writable for the configured Hitch user,
157 or automatic retrieval and updating of OCSP responses will not take
158 place.
159 If you have a manually pre-loaded OCSP staple, an alternative pem-file
161 syntax can be used for stapling:
162 pem-file = {
164 cert = "mycert.pem"
165 ocsp-resp-file = "ocsp-resp.der"
166 }
167 ocsp-connect-tmo = <number>
169 OCSP fetch connect timeout.
170 This does normally not need to be changed.
172 Default is 4.0 seconds.
174 ocsp-resp-tmo = <number>
176 OCSP fetch response timeout.
177 This does normally not need to be changed.
179 Default is 10 seconds.
181 ocsp-refresh-interval = <number>
183 OCSP refresh interval.
184 If the OCSP response does not carry any refresh information, use this
186 as the interval for refreshing.
187 Default is 1800 seconds.
189 ocsp-verify-staple = on|off
191 If set, OCSP responses will be verified against the certificate after
192 retrieval.
193 Default is off.
195 pem-file = <string>
197 Specify a SSL x509 certificate file. Server Name Indication (SNI) is
198 supported by using one certificate file per SNI name.
199 A file suitable for Hitch is a concatenation of a private key and a
201 corresponding certificate or certificate chain.
202 At least one PEM file is needed for Hitch to start, but it can be sup‐
204 plied on the command line.
205 Certificates are used in the order they are listed; the last certifi‐
207 cate listed will be used if none of the others match.
208 In the event that we have multiple certificates that provide the same
210 SNI string, an error will be logged. The last loaded certificate will
211 in that case take precendence.
212 For partial overlap in names, e.g. if one certificate provides
214 "www.example.com" and another one "*.example.com", the most specific
215 match will always take precendence at SNI lookup.
216 This option is also available in a frontend declaration, to make a cer‐
218 tificate only available for a specific listen endpoint.
219 private-key = <string>
221 If set, the private key is read from specified location, not from the
222 cert file.
223 pem-file = {
225 cert = "mycert.pem"
226 private-key = "myprivate.key"
227 }
228 pem-dir = <string>
230 Specify a directory for loading x509 certificates.
231 A fallback certificate for non-SNI clients may be specified by also
233 including a separate pem-file definition.
234 The files are processed in lexicographic order. In the absence of any
236 pem-file definitions, the first file entry will be used as the fallback
237 default.
238 pem-dir = "/etc/hitch/cert.d"
240 pem-dir-glob = <string>
242 Matching filter for filenames loaded from pem-dir.
243 Default is none (match any).
245 pem-dir-glob = "*.pem"
247 prefer-server-ciphers = on|off
249 Turns on or off enforcement of the cipher ordering set in Hitch.
250 This option is also available in frontend blocks.
252 Default is off.
254 proxy-proxy = on|off
256 Proxy an existing PROXY protocol header through this request. At the
257 moment this is equivalent to write-proxy-v2.
258 This option is mutually exclusive with option write-proxy-v2, write-ip
260 and write-proxy-v1.
261 Default is off.
263 log-level = <num>
265 Log chattiness. 0=silence, 1=errors, 2=info/debug.
266 This setting can also be changed at run-time by editing the configura‐
268 tion file followed by a reload (SIGHUP).
269 Default is 0.
271 quiet = on|off
273 If quiet is turned on, only error messages will be shown. This setting
274 is deprecated in favor of log-level.
275 tls-protos = ...
277 The SSL/TLS protocols to be used. This is an unquoted list of tokens.
278 Available tokens are SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 and TLSv1.3.
279 The default is TLSv1.2 and TLSv1.3.
281 There are two deprecated options, ssl= and tls=, that also select pro‐
283 tocols. If "ssl=on" is used, then all protocols are selected. This is
284 known to be insecure, and is strongly discouraged. If "tls=on" is used,
285 the three TLS protocol versions will be used. Turning on SSLv3 and
286 TLSv1.0 is not recommended - support for these protocols are only kept
287 for backwards compatibility.
288 The availability of protocol versions depend on OpenSSL version and
290 system configuration. In particular for TLS 1.3, openssl 1.1.1 or later
291 is required.
292 For supporting legacy protocol versions you may also need to lower the
294 MinProtocol property in your OpenSSL configuration (typically
295 /etc/ssl/openssl.cnf).
296 This option is also available in frontend blocks.
298 ecdh-curve = <string>
300 Sets the list of supported TLS curves. A special value of auto will
301 leave it up to OpenSSL to automatically pick the most appropriate curve
302 for a client.
303 ecdh-curve = "X25519:prime256v1:secp384r1"
305 sni-nomatch-abort = on|off
307 Abort handshake when the client submits an unrecognized SNI server
308 name.
309 This option is also available in a frontend declaration.
311 ssl-engine = <string>
313 Set the SSL engine. This is used with SSL accelerator cards. See the
314 OpenSSL documentation for legal values.
315 syslog = on|off
317 Send messages to syslog. Default is off.
318 syslog-facility = <string>
320 Set the syslog facility. Default is "daemon".
321 user = <string>
323 User to run as. If Hitch is started as root, it will insist on changing
324 to a user with lower rights after binding to sockets.
325 workers = <number>
327 Number of worker processes. One per CPU core is recommended.
328 write-ip = on|off
330 Report the client ip to the backend by writing IP before sending data.
331 This option is mutually exclusive with each of the options
333 write-proxy-v2, write-proxy-v1 and proxy-proxy.
334 Default is off.
336 write-proxy-v1 = on|off
338 Report client address using the PROXY protocol.
339 This option is mutually exclusive with option write-proxy-v2, write-ip
341 and proxy-proxy.
342 Default is off.
344 write-proxy-v2 = on|off
346 Report client address using PROXY v2 protocol.
347 This option is mutually exclusive with option write-ip, write-proxy-v1
349 and proxy-proxy.
350 Default is off.
352 proxy-tlv = on|off
354 Report extra information as part of the PROXYv2 header.
355 Currently the following will be transmitted when proxy-tlv is enabled:
357 · Cipher
359 · Protocol version
361 · Client certificate verification result
363 · Whether the client transmitted a certificate as part of this con‐
365 nection/session (PP2_CLIENT_CERT_CONN, PP2_CLIENT_CERT_SESS)
366 Default is on.
368 tcp-fastopen = on|off
370 Enable TCP Fast Open.
371 Default is off.
373
375 The following file shows the syntax needed to get started with:
376 frontend = {
378 host = "*"
379 port = "443"
380 }
381 backend = "[127.0.0.1]:6086" # 6086 is the default Varnish PROXY port.
382 workers = 4 # number of CPU cores
383 daemon = on
385 # We strongly recommend you create a separate non-privileged hitch
387 # user and group
388 user = "hitch"
389 group = "hitch"
390 # Enable to let clients negotiate HTTP/2 with ALPN. (default off)
392 # alpn-protos = "h2, http/1.1"
393 # run Varnish as backend over PROXY; varnishd -a :80 -a localhost:6086,PROXY ..
395 write-proxy-v2 = on # Write PROXY header
396
398 This manual was written by Pål Hermunn Johansen <‐
399 hermunn@varnish-software.com>
400 HITCH.CONF(5)