1HITCH.CONF(5)                                                    HITCH.CONF(5)
2
3
4

NAME

6       Hitch.conf - Configuration file for Hitch
7

DESCRIPTION

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
13       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
16       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
21       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

OPTIONS

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
31       Unless otherwise noted below, options can  only  be  used  in  the  top
32       level.
33
34   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
41       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
45   backend = ...
46       The endpoint Hitch connects to when receiving a connection. Only a sin‐
47       gle backend is supported.
48
49       This is either specified as "[HOST]:port" for IPv4/IPv6 endpoints:
50
51          backend = "[localhost]:8080"
52
53       Or it can be specified as a path to a UNIX domain socket:
54
55          backend = "/path/to/sock"
56
57   backlog = <number>
58       Listen backlog size
59
60   chroot = <string>
61       Chroot directory
62
63   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
67       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
70       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
75       This  option  applies  to  TLSv1.2  and below. For TLSv1.3, see cipher‐
76       suites.
77
78       This option is also available in frontend blocks.
79
80   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
84       This option is also available in frontend blocks.
85
86   client-verify = required|optional|none
87       Configures  client  certificate  validation. The setting must be one of
88       none, required or optional.
89
90       The default setting is client-verify = none, in which case  Hitch  will
91       not send a certificate request to the client.
92
93       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
97       If  optional,  Hitch  will  send certificate requests, but still permit
98       connections that do not present one.
99
100       For  settings  optional  and  required,  we  also  require   that   the
101       client-verify-ca is configured.
102
103       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
107   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
111       For multiple  CAs,  this  file  can  be  a  concatenation  of  multiple
112       pem-files for the relevant certificate authorities.
113
114       This option is also available in frontend blocks.
115
116   daemon = on|off
117       Run as daemon. Default is off.
118
119   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
125       If "*" is used as the host, then Hitch will bind on all interfaces  for
126       the given port.
127
128       A frontend can be specified either in a single line:
129
130          frontend = "[HOST]:PORT[+CERT]"
131
132       Or in a frontend block:
133
134          frontend = {
135              host = "HOST"
136              port = "PORT"
137              <other frontend options>
138          }
139
140   group = <string>
141       If given, Hitch will change to this group after binding to listen sock‐
142       ets.
143
144   keepalive = <number>
145       Number of seconds a TCP socket is kept alive
146
147   backend-refresh = <number>
148       Number of seconds between periodic backend IP lookups,  0  to  disable.
149       Default is 0.
150
151   ocsp-dir = <string>
152       Directory  where Hitch will store and read OCSP responses for stapling.
153       Default is "/var/lib/hitch/".
154
155       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
159       If you have a manually pre-loaded OCSP staple, an alternative  pem-file
160       syntax can be used for stapling:
161
162          pem-file = {
163              cert = "mycert.pem"
164              ocsp-resp-file = "ocsp-resp.der"
165          }
166
167   ocsp-connect-tmo = <number>
168       OCSP fetch connect timeout.
169
170       This does normally not need to be changed.
171
172       Default is 4.0 seconds.
173
174   ocsp-resp-tmo = <number>
175       OCSP fetch response timeout.
176
177       This does normally not need to be changed.
178
179       Default is 10 seconds.
180
181   ocsp-refresh-interval = <number>
182       OCSP refresh interval.
183
184       If  the  OCSP response does not carry any refresh information, use this
185       as the interval for refreshing.
186
187       Default is 1800 seconds.
188
189   ocsp-verify-staple = on|off
190       If set, OCSP responses will be verified against the  certificate  after
191       retrieval.
192
193       Default is off.
194
195   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
199       A file suitable for Hitch is a concatenation of a  private  key  and  a
200       corresponding certificate or certificate chain.
201
202       At  least one PEM file is needed for Hitch to start, but it can be sup‐
203       plied on the command line.
204
205       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
208       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 precedence.
211
212       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 precedence at SNI lookup.
215
216       This option is also available in a frontend declaration, to make a cer‐
217       tificate only available for a specific listen endpoint.
218
219   private-key = <string>
220       If set, the private key is read from specified location, not  from  the
221       cert file.
222
223          pem-file = {
224              cert = "mycert.pem"
225              private-key = "myprivate.key"
226          }
227
228   pem-dir = <string>
229       Specify a directory for loading x509 certificates.
230
231       A fallback certificate for non-SNI clients may be specified by also in‐
232       cluding a separate pem-file definition.
233
234       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
238          pem-dir = "/etc/hitch/cert.d"
239
240   pem-dir-glob = <string>
241       Matching filter for filenames loaded from pem-dir.
242
243       Default is none (match any).
244
245          pem-dir-glob = "*.pem"
246
247   prefer-server-ciphers = on|off
248       Turns on or off enforcement of the cipher ordering set in Hitch.
249
250       This option is also available in frontend blocks.
251
252       Default is off.
253
254   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
258       This  option is mutually exclusive with option write-proxy-v2, write-ip
259       and write-proxy-v1.
260
261       Default is off.
262
263   log-level = <num>
264       Log chattiness. 0=silence, 1=errors, 2=info/debug.
265
266       This setting can also be changed at run-time by editing the  configura‐
267       tion file followed by a reload (SIGHUP).
268
269       Default is 0.
270
271   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
275   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
279       The default is TLSv1.2 and TLSv1.3.
280
281       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
288       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
292       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
296       This option is also available in frontend blocks.
297
298   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
303          ecdh-curve = "X25519:prime256v1:secp384r1"
304
305   sni-nomatch-abort = on|off
306       Abort handshake when the client  submits  an  unrecognized  SNI  server
307       name.
308
309       This option is also available in a frontend declaration.
310
311   ssl-engine = <string>
312       Set  the  SSL  engine. This is used with SSL accelerator cards. See the
313       OpenSSL documentation for legal values.
314
315   syslog = on|off
316       Send messages to syslog. Default is off.
317
318   syslog-facility = <string>
319       Set the syslog facility. Default is "daemon".
320
321   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
325   workers = <number>
326       Number of worker processes. One per CPU core is recommended.
327
328   write-ip = on|off
329       Report the client ip to the backend by writing IP before sending data.
330
331       This   option   is   mutually   exclusive  with  each  of  the  options
332       write-proxy-v2, write-proxy-v1 and proxy-proxy.
333
334       Default is off.
335
336   write-proxy-v1 = on|off
337       Report client address using the PROXY protocol.
338
339       This option is mutually exclusive with option write-proxy-v2,  write-ip
340       and proxy-proxy.
341
342       Default is off.
343
344   write-proxy-v2 = on|off
345       Report client address using PROXY v2 protocol.
346
347       This  option is mutually exclusive with option write-ip, write-proxy-v1
348       and proxy-proxy.
349
350       Default is off.
351
352   proxy-tlv = on|off
353       Report extra information as part of the PROXYv2 header.
354
355       Currently the following will be transmitted when proxy-tlv is enabled:
356
357          • Cipher
358
359          • Protocol version
360
361          • Client certificate verification result
362
363          • Whether the client transmitted a certificate as part of this  con‐
364            nection/session (PP2_CLIENT_CERT_CONN, PP2_CLIENT_CERT_SESS)
365
366       Default is on.
367
368   proxy-client-cert = on|off
369       Transmit  the  authenticated  client certificate as part of the PROXYv2
370       header.
371
372       The PEM-formatted client certificate will be transmitted as a TLV field
373       of type 0xe0.
374
375       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
380   tcp-fastopen = on|off
381       Enable TCP Fast Open.
382
383       Default is off.
384

EXAMPLE

386       The following file shows the syntax needed to get started with:
387
388          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
395          daemon = on
396
397          # We strongly recommend you create a separate non-privileged hitch
398          # user and group
399          user = "hitch"
400          group = "hitch"
401
402          # Enable to let clients negotiate HTTP/2 with ALPN. (default off)
403          # alpn-protos = "h2, http/1.1"
404
405          # run Varnish as backend over PROXY; varnishd -a :80 -a localhost:6086,PROXY ..
406          write-proxy-v2 = on             # Write PROXY header
407

AUTHOR

409       This   manual   was   written    by    Pål    Hermunn    Johansen    <‐
410       hermunn@varnish-software.com>
411
412
413
414
415                                                                 HITCH.CONF(5)
Impressum