"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 .