hitch-1.7.2.tar.gz: hitch-1.7.2/hitch.conf.5

"Fossies" - the Fresh Open Source Software Archive

Member "hitch-1.7.2/hitch.conf.5" (29 Nov 2021, 14607 Bytes) of package /linux/www/hitch-1.7.2.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

1 .\" Man page generated from reStructuredText. 2 . 3 .TH HITCH.CONF 5 "" "" "" 4 .SH NAME 5 Hitch.conf \- Configuration file for Hitch 6 . 7 .nr rst2man-indent-level 0 8 . 9 .de1 rstReportMargin 10 \\$1 \\n[an-margin] 11 level \\n[rst2man-indent-level] 12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] 13 - 14 \\n[rst2man-indent0] 15 \\n[rst2man-indent1] 16 \\n[rst2man-indent2] 17 .. 18 .de1 INDENT 19 .\" .rstReportMargin pre: 20 . RS \\$1 21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] 22 . nr rst2man-indent-level +1 23 .\" .rstReportMargin post: 24 .. 25 .de UNINDENT 26 . RE 27 .\" indent \\n[an-margin] 28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] 29 .nr rst2man-indent-level -1 30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] 31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u 32 .. 33 .SH DESCRIPTION 34 .sp 35 hitch.conf is the configuration file for \fIhitch(8)\fP\&. The configuration 36 file is loaded using the Hitch option \-\-config=, and can thus have 37 different names and can exist in different locations. 38 .sp 39 Almost all options available in hitch.conf can be specified or 40 overridden in the command line of Hitch, as described in hitch(8). 41 .sp 42 The Hitch configuration file consists of a series of option 43 assignments. Some options (pem\-file, frontend) can be be set several 44 times, and the effect is that multiple certificate files and 45 "listening frontends" are defined. Other options can only be assigned 46 once. 47 .sp 48 The hash mark, or pound sign ("#"), is used as a "comment" 49 character. You can use it to annotate your config file. All text after 50 the comment character to the end of the line is ignored. Empty lines 51 are ignored. 52 .SH OPTIONS 53 .sp 54 Options can either be in the top level of the configuration file 55 (global scope), or inside a \fIfrontend block\fP\&. Options inside a 56 frontend block only affect the frontend, while options in the top 57 level sets defaults for all frontends. 58 .sp 59 Unless otherwise noted below, options can only be used in the top 60 level. 61 .SS alpn\-protos = <protocol\-list> 62 .sp 63 Comma separated list of protocols supported by the backend in a quoted 64 string. The list is used select protocols when the client supports 65 Next Protocol Negotiation (NPN) or Application\-Layer Protocol 66 Negotiation (ALPN). If Hitch is compiled against a OpenSSL version 67 that does not support ALPN, only NPN will be used to select a 68 protocol. 69 .sp 70 The result of the NPN/ALPN negotiation will be communicated to the 71 backend if and only if write\-proxy\-v2 or proxy\-proxy is used. For 72 HTTP/2 to work with modern browsers, ALPN negotiation is required. 73 .SS backend = ... 74 .sp 75 The endpoint Hitch connects to when receiving a connection. Only 76 a single backend is supported. 77 .sp 78 This is either specified as "[HOST]:port" for IPv4/IPv6 endpoints: 79 .INDENT 0.0 80 .INDENT 3.5 81 .sp 82 .nf 83 .ft C 84 backend = "[localhost]:8080" 85 .ft P 86 .fi 87 .UNINDENT 88 .UNINDENT 89 .sp 90 Or it can be specified as a path to a UNIX domain socket: 91 .INDENT 0.0 92 .INDENT 3.5 93 .sp 94 .nf 95 .ft C 96 backend = "/path/to/sock" 97 .ft P 98 .fi 99 .UNINDENT 100 .UNINDENT 101 .SS backlog = <number> 102 .sp 103 Listen backlog size 104 .SS chroot = <string> 105 .sp 106 Chroot directory 107 .SS ciphers = ... 108 .sp 109 List of ciphers to use in the secure communication. Refer to the 110 OpenSSL documentation for a complete list of supported ciphers. 111 .sp 112 Each cipher in the list must be separated by a colon (\fB:\fP), in order 113 of preference. See \fBciphers(1)\fP for further description of the 114 format. 115 .sp 116 If not specified, OpenSSL will allow all ciphers. System 117 administrators are advised to either only support strong ciphers (as in 118 the example file below) or to pay close attention to security advisories 119 related OpenSSL\(aqs ciphers. 120 .sp 121 This option applies to TLSv1.2 and below. For TLSv1.3, see 122 \fBciphersuites\fP\&. 123 .sp 124 This option is also available in frontend blocks. 125 .SS ciphersuites = <string> 126 .sp 127 Specifies available ciphersuites for TLSv1.3. Similar to \fBciphers\fP, 128 entries must be separated by colon (\fB:\fP) and sorted in order of 129 preference. 130 .sp 131 This option is also available in frontend blocks. 132 .SS client\-verify = required|optional|none 133 .sp 134 Configures client certificate validation. The setting must be one of 135 \fBnone\fP, \fBrequired\fP or \fBoptional\fP\&. 136 .sp 137 The default setting is \fBclient\-verify = none\fP, in which case Hitch 138 will not send a certificate request to the client. 139 .sp 140 If \fBclient\-verify = require\fP is configured, Hitch will only permit 141 connections that present a valid certificate. The certificate will be 142 verified using the certificate provided in the \fBclient\-verify\-ca\fP 143 parameter. 144 .sp 145 If \fBoptional\fP, Hitch will send certificate requests, but still 146 permit connections that do not present one. 147 .sp 148 For settings \fBoptional\fP and \fBrequired\fP, we also require that the 149 \fBclient\-verify\-ca\fP is configured. 150 .sp 151 This option is also available in frontend blocks. If specified in a 152 frontend block, the client verification setting will only apply to the 153 \fBpem\-file\fP records for that particular frontend. 154 .SS client\-verify\-ca = <string> 155 .sp 156 Specifies a file containing the certificates of the CAs that will be 157 used to verify a client certificate. 158 .sp 159 For multiple CAs, this file can be a concatenation of multiple 160 pem\-files for the relevant certificate authorities. 161 .sp 162 This option is also available in frontend blocks. 163 .SS daemon = on|off 164 .sp 165 Run as daemon. Default is off. 166 .SS frontend = ... 167 .sp 168 This specifies the port and interface (the \fIlisten endpoint\fP) that 169 Hitch binds to when listening for connections. It is possible define 170 several frontends, and Hitch will bind to several ports and/or several 171 interfaces. 172 .sp 173 If "*" is used as the host, then Hitch will bind on all interfaces for 174 the given port. 175 .sp 176 A frontend can be specified either in a single line: 177 .INDENT 0.0 178 .INDENT 3.5 179 .sp 180 .nf 181 .ft C 182 frontend = "[HOST]:PORT[+CERT]" 183 .ft P 184 .fi 185 .UNINDENT 186 .UNINDENT 187 .sp 188 Or in a \fIfrontend block\fP: 189 .INDENT 0.0 190 .INDENT 3.5 191 .sp 192 .nf 193 .ft C 194 frontend = { 195 host = "HOST" 196 port = "PORT" 197 <other frontend options> 198 } 199 .ft P 200 .fi 201 .UNINDENT 202 .UNINDENT 203 .SS group = <string> 204 .sp 205 If given, Hitch will change to this group after binding to listen 206 sockets. 207 .SS keepalive = <number> 208 .sp 209 Number of seconds a TCP socket is kept alive 210 .SS backend\-refresh = <number> 211 .sp 212 Number of seconds between periodic backend IP lookups, 0 to disable. 213 Default is 0. 214 .SS ocsp\-dir = <string> 215 .sp 216 Directory where Hitch will store and read OCSP responses for 217 stapling. Default is "/var/lib/hitch/". 218 .sp 219 Directory must be readable and writable for the configured Hitch user, or 220 automatic retrieval and updating of OCSP responses will not take place. 221 .sp 222 If you have a manually pre\-loaded OCSP staple, an alternative 223 pem\-file syntax can be used for stapling: 224 .INDENT 0.0 225 .INDENT 3.5 226 .sp 227 .nf 228 .ft C 229 pem\-file = { 230 cert = "mycert.pem" 231 ocsp\-resp\-file = "ocsp\-resp.der" 232 } 233 .ft P 234 .fi 235 .UNINDENT 236 .UNINDENT 237 .SS ocsp\-connect\-tmo = <number> 238 .sp 239 OCSP fetch connect timeout. 240 .sp 241 This does normally not need to be changed. 242 .sp 243 Default is 4.0 seconds. 244 .SS ocsp\-resp\-tmo = <number> 245 .sp 246 OCSP fetch response timeout. 247 .sp 248 This does normally not need to be changed. 249 .sp 250 Default is 10 seconds. 251 .SS ocsp\-refresh\-interval = <number> 252 .sp 253 OCSP refresh interval. 254 .sp 255 If the OCSP response does not carry any refresh information, use this as the 256 interval for refreshing. 257 .sp 258 Default is 1800 seconds. 259 .SS ocsp\-verify\-staple = on|off 260 .sp 261 If set, OCSP responses will be verified against the certificate 262 after retrieval. 263 .sp 264 Default is off. 265 .SS pem\-file = <string> 266 .sp 267 Specify a SSL x509 certificate file. Server Name Indication (SNI) is 268 supported by using one certificate file per SNI name. 269 .sp 270 A file suitable for Hitch is a concatenation of a private key and a 271 corresponding certificate or certificate chain. 272 .sp 273 At least one PEM file is needed for Hitch to start, but it can be 274 supplied on the command line. 275 .sp 276 Certificates are used in the order they are listed; the last 277 certificate listed will be used if none of the others match. 278 .sp 279 In the event that we have multiple certificates that provide the same 280 SNI string, an error will be logged. The last loaded certificate will 281 in that case take precedence. 282 .sp 283 For partial overlap in names, e.g. if one certificate provides 284 "www.example.com" and another one "*.example.com", the most specific 285 match will always take precedence at SNI lookup. 286 .sp 287 This option is also available in a frontend declaration, to make a 288 certificate only available for a specific listen endpoint. 289 .SS private\-key = <string> 290 .sp 291 If set, the private key is read from specified location, not from the cert file. 292 .INDENT 0.0 293 .INDENT 3.5 294 .sp 295 .nf 296 .ft C 297 pem\-file = { 298 cert = "mycert.pem" 299 private\-key = "myprivate.key" 300 } 301 .ft P 302 .fi 303 .UNINDENT 304 .UNINDENT 305 .SS pem\-dir = <string> 306 .sp 307 Specify a directory for loading x509 certificates. 308 .sp 309 A fallback certificate for non\-SNI clients may be specified by also 310 including a separate \fBpem\-file\fP definition. 311 .sp 312 The files are processed in lexicographic order. In the absence of any 313 \fBpem\-file\fP definitions, the first file entry will be used as the 314 fallback default. 315 .INDENT 0.0 316 .INDENT 3.5 317 .sp 318 .nf 319 .ft C 320 pem\-dir = "/etc/hitch/cert.d" 321 .ft P 322 .fi 323 .UNINDENT 324 .UNINDENT 325 .SS pem\-dir\-glob = <string> 326 .sp 327 Matching filter for filenames loaded from \fBpem\-dir\fP\&. 328 .sp 329 Default is none (match any). 330 .INDENT 0.0 331 .INDENT 3.5 332 .sp 333 .nf 334 .ft C 335 pem\-dir\-glob = "*.pem" 336 .ft P 337 .fi 338 .UNINDENT 339 .UNINDENT 340 .SS prefer\-server\-ciphers = on|off 341 .sp 342 Turns on or off enforcement of the cipher ordering set in Hitch. 343 .sp 344 This option is also available in frontend blocks. 345 .sp 346 Default is off. 347 .SS proxy\-proxy = on|off 348 .sp 349 Proxy an incoming PROXY protocol header through to the 350 backend. Supports both version 1 and 2 of the PROXY protocol. 351 .sp 352 This option is mutually exclusive with option write\-proxy\-v2, write\-ip 353 and write\-proxy\-v1. 354 .sp 355 Default is off. 356 .SS log\-level = <num> 357 .sp 358 Log chattiness. 0=silence, 1=errors, 2=info/debug. 359 .sp 360 This setting can also be changed at run\-time by editing the 361 configuration file followed by a reload (SIGHUP). 362 .sp 363 Default is 0. 364 .SS quiet = on|off 365 .sp 366 If quiet is turned on, only error messages will be shown. This setting 367 is deprecated in favor of \fBlog\-level\fP\&. 368 .SS tls\-protos = ... 369 .sp 370 The SSL/TLS protocols to be used. This is an unquoted list of 371 tokens. Available tokens are SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 and 372 TLSv1.3. 373 .sp 374 The default is TLSv1.2 and TLSv1.3. 375 .sp 376 There are two deprecated options, ssl= and tls=, that also select 377 protocols. If "ssl=on" is used, then all protocols are selected. This 378 is known to be insecure, and is strongly discouraged. If "tls=on" is 379 used, the three TLS protocol versions will be used. Turning on SSLv3 380 and TLSv1.0 is not recommended \- support for these protocols are only 381 kept for backwards compatibility. 382 .sp 383 The availability of protocol versions depend on OpenSSL version and 384 system configuration. In particular for TLS 1.3, openssl 1.1.1 or 385 later is required. 386 .sp 387 For supporting legacy protocol versions you may also need to lower the 388 \fBMinProtocol\fP property in your OpenSSL configuration (typically 389 \fB/etc/ssl/openssl.cnf\fP). 390 .sp 391 This option is also available in frontend blocks. 392 .SS ecdh\-curve = <string> 393 .sp 394 Sets the list of supported TLS curves. A special value of \fBauto\fP 395 will leave it up to OpenSSL to automatically pick the most appropriate 396 curve for a client. 397 .INDENT 0.0 398 .INDENT 3.5 399 .sp 400 .nf 401 .ft C 402 ecdh\-curve = "X25519:prime256v1:secp384r1" 403 .ft P 404 .fi 405 .UNINDENT 406 .UNINDENT 407 .SS sni\-nomatch\-abort = on|off 408 .sp 409 Abort handshake when the client submits an unrecognized SNI server name. 410 .sp 411 This option is also available in a frontend declaration. 412 .SS ssl\-engine = <string> 413 .sp 414 Set the SSL engine. This is used with SSL accelerator cards. See the 415 OpenSSL documentation for legal values. 416 .SS syslog = on|off 417 .sp 418 Send messages to syslog. Default is off. 419 .SS syslog\-facility = <string> 420 .sp 421 Set the syslog facility. Default is "daemon". 422 .SS user = <string> 423 .sp 424 User to run as. If Hitch is started as root, it will insist on 425 changing to a user with lower rights after binding to sockets. 426 .SS workers = <number> 427 .sp 428 Number of worker processes. One per CPU core is recommended. 429 .SS write\-ip = on|off 430 .sp 431 Report the client ip to the backend by writing IP before sending 432 data. 433 .sp 434 This option is mutually exclusive with each of the options 435 write\-proxy\-v2, write\-proxy\-v1 and proxy\-proxy. 436 .sp 437 Default is off. 438 .SS write\-proxy\-v1 = on|off 439 .sp 440 Report client address using the PROXY protocol. 441 .sp 442 This option is mutually exclusive with option write\-proxy\-v2, write\-ip 443 and proxy\-proxy. 444 .sp 445 Default is off. 446 .SS write\-proxy\-v2 = on|off 447 .sp 448 Report client address using PROXY v2 protocol. 449 .sp 450 This option is mutually exclusive with option write\-ip, write\-proxy\-v1 451 and proxy\-proxy. 452 .sp 453 Default is off. 454 .SS proxy\-tlv = on|off 455 .sp 456 Report extra information as part of the PROXYv2 header. 457 .sp 458 Currently the following will be transmitted when proxy\-tlv is enabled: 459 .INDENT 0.0 460 .INDENT 3.5 461 .INDENT 0.0 462 .IP \(bu 2 463 Cipher 464 .IP \(bu 2 465 Protocol version 466 .IP \(bu 2 467 Client certificate verification result 468 .IP \(bu 2 469 Whether the client transmitted a certificate as part of this 470 connection/session (PP2_CLIENT_CERT_CONN, PP2_CLIENT_CERT_SESS) 471 .UNINDENT 472 .UNINDENT 473 .UNINDENT 474 .sp 475 Default is on. 476 .SS proxy\-client\-cert = on|off 477 .sp 478 Transmit the authenticated client certificate as part of the PROXYv2 479 header. 480 .sp 481 The PEM\-formatted client certificate will be transmitted as a TLV 482 field of type 0xe0. 483 .sp 484 This is a custom application\-specific type, requiring a a custom 485 handler at the recipient end. Note that using this feature will 486 inflate the size of the PROXY header substantially, possibly also 487 requiring tweaking at the receiving end. 488 .SS tcp\-fastopen = on|off 489 .sp 490 Enable TCP Fast Open. 491 .sp 492 Default is off. 493 .SH EXAMPLE 494 .\" example-start 495 . 496 .sp 497 The following file shows the syntax needed to get started with: 498 .INDENT 0.0 499 .INDENT 3.5 500 .sp 501 .nf 502 .ft C 503 frontend = { 504 host = "*" 505 port = "443" 506 } 507 backend = "[127.0.0.1]:6086" # 6086 is the default Varnish PROXY port. 508 workers = 4 # number of CPU cores 509 510 daemon = on 511 512 # We strongly recommend you create a separate non\-privileged hitch 513 # user and group 514 user = "hitch" 515 group = "hitch" 516 517 # Enable to let clients negotiate HTTP/2 with ALPN. (default off) 518 # alpn\-protos = "h2, http/1.1" 519 520 # run Varnish as backend over PROXY; varnishd \-a :80 \-a localhost:6086,PROXY .. 521 write\-proxy\-v2 = on # Write PROXY header 522 .ft P 523 .fi 524 .UNINDENT 525 .UNINDENT 526 .\" example-end 527 . 528 .SH AUTHOR 529 .sp 530 This manual was written by Pål Hermunn Johansen <\fI\%hermunn@varnish\-software.com\fP> 531 .\" Generated by docutils manpage writer. 532 .