1HITCH.CONF(5) HITCH.CONF(5)
2
3
4
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
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 fron‐
19 tends" 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
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
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 If not specified, OpenSSL will allow all ciphers. System administrators
68 are advised to either only support strong ciphers (as in the example
69 file below) or to pay close attention to security advisories related
70 OpenSSL's ciphers.
71
72 This option is also available in frontend blocks.
73
74 daemon = on|off
75 Run as daemon. Default is off.
76
77 frontend = ...
78 This specifies the port and interface (the listen endpoint) that Hitch
79 binds to when listening for connections. It is possible define several
80 frontends, and Hitch will bind to several ports and/or several inter‐
81 faces.
82
83 If "*" is used as the host, then Hitch will bind on all interfaces for
84 the given port.
85
86 A frontend can be specified either in a single line:
87
88 frontend = "[HOST]:PORT[+CERT]"
89
90 Or in a frontend block:
91
92 frontend = {
93 host = "HOST"
94 port = "PORT"
95 <other frontend options>
96 }
97
98 group = <string>
99 If given, Hitch will change to this group after binding to listen sock‐
100 ets.
101
102 keepalive = <number>
103 Number of seconds a TCP socket is kept alive
104
105 backend-refresh = <number>
106 Number of seconds between periodic backend IP lookups, 0 to disable.
107 Default is 0.
108
109 ocsp-dir = <string>
110 Directory where Hitch will store and read OCSP responses for stapling.
111 Default is "/var/lib/hitch/".
112
113 Directory must be readable and writable for the configured Hitch user,
114 or automatic retrieval and updating of OCSP responses will not take
115 place.
116
117 If you have a manually pre-loaded OCSP staple, an alternative pem-file
118 syntax can be used for stapling:
119
120 pem-file = {
121 cert = "mycert.pem"
122 ocsp-resp-file = "ocsp-resp.der"
123 }
124
125 ocsp-connect-tmo = <number>
126 OCSP fetch connect timeout.
127
128 This does normally not need to be changed.
129
130 Default is 4.0 seconds.
131
132 ocsp-resp-tmo = <number>
133 OCSP fetch response timeout.
134
135 This does normally not need to be changed.
136
137 Default is 10 seconds.
138
139 ocsp-refresh-interval = <number>
140 OCSP refresh interval.
141
142 If the OCSP response does not carry any refresh information, use this
143 as the interval for refreshing.
144
145 Default is 1800 seconds.
146
147 ocsp-verify-staple = on|off
148 If set, OCSP responses will be verified against the certificate after
149 retrieval.
150
151 Default is off.
152
153 pem-file = <string>
154 Specify a SSL x509 certificate file. Server Name Indication (SNI) is
155 supported by using one certificate file per SNI name.
156
157 Certificates are used in the order they are listed; the last certifi‐
158 cate listed will be used if none of the others match.
159
160 A file suitable for Hitch is a concatenation of a private key and a
161 corresponding certificate or certificate chain.
162
163 At least one PEM file is needed for Hitch to start, but it can be sup‐
164 plied on the command line.
165
166 This option is also available in a frontend declaration, to make a cer‐
167 tificate only available for a specific listen endpoint.
168
169 private-key = <string>
170 If set, the private key is read from specified location, not from the
171 cert file.
172
173 pem-file = {
174 cert = "mycert.pem"
175 private-key = "myprivate.key"
176 }
177
178 pem-dir = <string>
179 Specify a directory for loading x509 certificates.
180
181 A fallback certificate for non-SNI clients may be specified by also
182 including a separate pem-file definition.
183
184 The files are processed in lexicographic order. In the absence of any
185 pem-file definitions, the first file entry will be used as the fallback
186 default.
187
188 pem-dir = "/etc/hitch/cert.d"
189
190 pem-dir-glob = <string>
191 Matching filter for filenames loaded from pem-dir.
192
193 Default is none (match any).
194
195 pem-dir-glob = "*.pem"
196
197 prefer-server-ciphers = on|off
198 Turns on or off enforcement of the cipher ordering set in Hitch.
199
200 This option is also available in frontend blocks.
201
202 Default is off.
203
204 proxy-proxy = on|off
205 Proxy an existing PROXY protocol header through this request. At the
206 moment this is equivalent to write-proxy-v2.
207
208 This option is mutually exclusive with option write-proxy-v2, write-ip
209 and write-proxy-v1.
210
211 Default is off.
212
213 log-level = <num>
214 Log chattiness. 0=silence, 1=errors, 2=info/debug.
215
216 This setting can also be changed at run-time by editing the configura‐
217 tion file followed by a reload (SIGHUP).
218
219 Default is 0.
220
221 quiet = on|off
222 If quiet is turned on, only error messages will be shown. This setting
223 is deprecated in favor of log-level.
224
225 tls-protos = ...
226 The SSL/TLS protocols to be used. This is an unquoted list of tokens.
227 Available tokens are SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 and TLSv1.3.
228
229 The default is TLSv1.2 and TLSv1.3.
230
231 There are two deprecated options, ssl= and tls=, that also select pro‐
232 tocols. If "ssl=on" is used, then all protocols are selected. This is
233 known to be insecure, and is strongly discouraged. If "tls=on" is used,
234 the three TLS protocol versions will be used. Turning on SSLv3 and
235 TLSv1.0 is not recommended - support for these protocols are only kept
236 for backwards compatibility.
237
238 This option is also available in frontend blocks.
239
240 sni-nomatch-abort = on|off
241 Abort handshake when the client submits an unrecognized SNI server
242 name.
243
244 This option is also available in a frontend declaration.
245
246 ssl-engine = <string>
247 Set the SSL engine. This is used with SSL accelerator cards. See the
248 OpenSSL documentation for legal values.
249
250 syslog = on|off
251 Send messages to syslog. Default is off.
252
253 syslog-facility = <string>
254 Set the syslog facility. Default is "daemon".
255
256 user = <string>
257 User to run as. If Hitch is started as root, it will insist on changing
258 to a user with lower rights after binding to sockets.
259
260 workers = <number>
261 Number of worker processes. One per CPU core is recommended.
262
263 write-ip = on|off
264 Report the client ip to the backend by writing IP before sending data.
265
266 This option is mutually exclusive with each of the options
267 write-proxy-v2, write-proxy-v1 and proxy-proxy.
268
269 Default is off.
270
271 write-proxy-v1 = on|off
272 Report client address using the PROXY protocol.
273
274 This option is mutually exclusive with option write-proxy-v2, write-ip
275 and proxy-proxy.
276
277 Default is off.
278
279 write-proxy-v2 = on|off
280 Report client address using PROXY v2 protocol.
281
282 This option is mutually exclusive with option write-ip, write-proxy-v1
283 and proxy-proxy.
284
285 Default is off.
286
287 proxy-tlv = on|off
288 Report the chosen cipher and protocol as part of the PROXYv2 header.
289
290 Default is on.
291
293 The following file shows the syntax needed to get started with:
294
295 frontend = {
296 host = "*"
297 port = "443"
298 }
299 backend = "[127.0.0.1]:6086" # 6086 is the default Varnish PROXY port.
300 workers = 4 # number of CPU cores
301
302 daemon = on
303
304 # We strongly recommend you create a separate non-privileged hitch
305 # user and group
306 user = "hitch"
307 group = "hitch"
308
309 # Enable to let clients negotiate HTTP/2 with ALPN. (default off)
310 # alpn-protos = "h2, http/1.1"
311
312 # run Varnish as backend over PROXY; varnishd -a :80 -a localhost:6086,PROXY ..
313 write-proxy-v2 = on # Write PROXY header
314
316 This manual was written by Pål Hermunn Johansen <‐
317 hermunn@varnish-software.com>
318
319
320
321
322 HITCH.CONF(5)