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 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 This option is also available in frontend blocks.
73 daemon = on|off
75 Run as daemon. Default is off.
76 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 If "*" is used as the host, then Hitch will bind on all interfaces for
84 the given port.
85 A frontend can be specified either in a single line:
87 frontend = "[HOST]:PORT[+CERT]"
89 Or in a frontend block:
91 frontend = {
93 host = "HOST"
94 port = "PORT"
95 <other frontend options>
96 }
97 group = <string>
99 If given, Hitch will change to this group after binding to listen sock‐
100 ets.
101 keepalive = <number>
103 Number of seconds a TCP socket is kept alive
104 backend-refresh = <number>
106 Number of seconds between periodic backend IP lookups, 0 to disable.
107 Default is 0.
108 ocsp-dir = <string>
110 Directory where Hitch will store and read OCSP responses for stapling.
111 Default is "/var/lib/hitch/".
112 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 If you have a manually pre-loaded OCSP staple, an alternative pem-file
118 syntax can be used for stapling:
119 pem-file = {
121 cert = "mycert.pem"
122 ocsp-resp-file = "ocsp-resp.der"
123 }
124 ocsp-connect-tmo = <number>
126 OCSP fetch connect timeout.
127 This does normally not need to be changed.
129 Default is 4.0 seconds.
131 ocsp-resp-tmo = <number>
133 OCSP fetch response timeout.
134 This does normally not need to be changed.
136 Default is 10 seconds.
138 ocsp-refresh-interval = <number>
140 OCSP refresh interval.
141 If the OCSP response does not carry any refresh information, use this
143 as the interval for refreshing.
144 Default is 1800 seconds.
146 ocsp-verify-staple = on|off
148 If set, OCSP responses will be verified against the certificate after
149 retrieval.
150 Default is off.
152 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 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 A file suitable for Hitch is a concatenation of a private key and a
161 corresponding certificate or certificate chain.
162 At least one PEM file is needed for Hitch to start, but it can be sup‐
164 plied on the command line.
165 This option is also available in a frontend declaration, to make a cer‐
167 tificate only available for a specific listen endpoint.
168 private-key = <string>
170 If set, the private key is read from specified location, not from the
171 cert file.
172 pem-file = {
174 cert = "mycert.pem"
175 private-key = "myprivate.key"
176 }
177 pem-dir = <string>
179 Specify a directory for loading x509 certificates.
180 A fallback certificate for non-SNI clients may be specified by also
182 including a separate pem-file definition.
183 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 pem-dir = "/etc/hitch/cert.d"
189 pem-dir-glob = <string>
191 Matching filter for filenames loaded from pem-dir.
192 Default is none (match any).
194 pem-dir-glob = "*.pem"
196 prefer-server-ciphers = on|off
198 Turns on or off enforcement of the cipher ordering set in Hitch.
199 This option is also available in frontend blocks.
201 Default is off.
203 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 This option is mutually exclusive with option write-proxy-v2, write-ip
209 and write-proxy-v1.
210 Default is off.
212 log-level = <num>
214 Log chattiness. 0=silence, 1=errors, 2=info/debug.
215 This setting can also be changed at run-time by editing the configura‐
217 tion file followed by a reload (SIGHUP).
218 Default is 0.
220 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 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 The default is TLSv1.2 and TLSv1.3.
230 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 This option is also available in frontend blocks.
239 sni-nomatch-abort = on|off
241 Abort handshake when the client submits an unrecognized SNI server
242 name.
243 This option is also available in a frontend declaration.
245 ssl-engine = <string>
247 Set the SSL engine. This is used with SSL accelerator cards. See the
248 OpenSSL documentation for legal values.
249 syslog = on|off
251 Send messages to syslog. Default is off.
252 syslog-facility = <string>
254 Set the syslog facility. Default is "daemon".
255 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 workers = <number>
261 Number of worker processes. One per CPU core is recommended.
262 write-ip = on|off
264 Report the client ip to the backend by writing IP before sending data.
265 This option is mutually exclusive with each of the options
267 write-proxy-v2, write-proxy-v1 and proxy-proxy.
268 Default is off.
270 write-proxy-v1 = on|off
272 Report client address using the PROXY protocol.
273 This option is mutually exclusive with option write-proxy-v2, write-ip
275 and proxy-proxy.
276 Default is off.
278 write-proxy-v2 = on|off
280 Report client address using PROXY v2 protocol.
281 This option is mutually exclusive with option write-ip, write-proxy-v1
283 and proxy-proxy.
284 Default is off.
286 proxy-tlv = on|off
288 Report the chosen cipher and protocol as part of the PROXYv2 header.
289 Default is on.
291 tcp-fastopen = on|off
293 Enable TCP Fast Open.
294 Default is off.
296
298 The following file shows the syntax needed to get started with:
299 frontend = {
301 host = "*"
302 port = "443"
303 }
304 backend = "[127.0.0.1]:6086" # 6086 is the default Varnish PROXY port.
305 workers = 4 # number of CPU cores
306 daemon = on
308 # We strongly recommend you create a separate non-privileged hitch
310 # user and group
311 user = "hitch"
312 group = "hitch"
313 # Enable to let clients negotiate HTTP/2 with ALPN. (default off)
315 # alpn-protos = "h2, http/1.1"
316 # run Varnish as backend over PROXY; varnishd -a :80 -a localhost:6086,PROXY ..
318 write-proxy-v2 = on # Write PROXY header
319
321 This manual was written by Pål Hermunn Johansen <‐
322 hermunn@varnish-software.com>
323 HITCH.CONF(5)