Provided by: hitch_1.5.0-1_amd64 bug

NAME

       Hitch.conf - Configuration file for Hitch

DESCRIPTION

       hitch.conf  is the configuration file for hitch(8). The configuration file is loaded using
       the Hitch option --config=, and can thus have different names and can exist  in  different
       locations.

       Almost  all  options available in hitch.conf can be specified or overridden in the command
       line of Hitch, as described in hitch(8).

       The Hitch configuration file consists of a series of  option  assignments.   Some  options
       (pem-file,  frontend)  can  be  be  set  several  times,  and  the effect is that multiple
       certificate files and "listening  frontends"  are  defined.  Other  options  can  only  be
       assigned once.

       The  hash  mark,  or pound sign ("#"), is used as a "comment" character. You can use it to
       annotate your config file. All text after the comment character to the end of the line  is
       ignored. Empty lines are ignored.

OPTIONS

       Options can either be in the top level of the configuration file (global scope), or inside
       a frontend block. Options inside a frontend block only affect the frontend, while  options
       in the top level sets defaults for all frontends.

       Unless otherwise noted below, options can only be used in the top level.

   alpn-protos = <protocol-list>
       Comma separated list of protocols supported by the backend in a quoted string. The list is
       used select protocols  when  the  client  supports  Next  Protocol  Negotiation  (NPN)  or
       Application-Layer  Protocol  Negotiation  (ALPN).  If  Hitch is compiled against a OpenSSL
       version that does not support ALPN, only NPN will be used to select a protocol.

       The result of the NPN/ALPN negotiation will be communicated to the backend if and only  if
       write-proxy-v2  or  proxy-proxy  is  used.  For  HTTP/2 to work with modern browsers, ALPN
       negotiation is required.

   backend = ...
       The endpoint Hitch connects to when receiving a  connection.  Only  a  single  backend  is
       supported.

       This is either specified as "[HOST]:port" for IPv4/IPv6 endpoints:

          backend = "[localhost]:8080"

       Or it can be specified as a path to a UNIX domain socket:

          backend = "/path/to/sock"

   backlog = <number>
       Listen backlog size

   chroot = <string>
       Chroot directory

   ciphers = ...
       List of ciphers to use in the secure communication. Refer to the OpenSSL documentation for
       a complete list of supported ciphers.

       If not specified, OpenSSL will allow all ciphers. System  administrators  are  advised  to
       either  only  support  strong  ciphers  (as  in  the  example  file below) or to pay close
       attention to security advisories related OpenSSL's ciphers.

       This option is also available in frontend blocks.

   daemon = on|off
       Run as daemon. Default is off.

   frontend = ...
       This specifies the port and interface (the listen  endpoint)  that  Hitch  binds  to  when
       listening for connections. It is possible define several frontends, and Hitch will bind to
       several ports and/or several interfaces.

       If "*" is used as the host, then Hitch will bind on all interfaces for the given port.

       A frontend can be specified either in a single line:

          frontend = "[HOST]:PORT[+CERT]"

       Or in a frontend block:

          frontend = {
              host = "HOST"
              port = "PORT"
              <other frontend options>
          }

   group = <string>
       If given, Hitch will change to this group after binding to listen sockets.

   keepalive = <number>
       Number of seconds a TCP socket is kept alive

   backend-refresh = <number>
       Number of seconds between periodic backend IP lookups, 0 to disable.  Default is 0.

   ocsp-dir = <string>
       Directory where Hitch will  store  and  read  OCSP  responses  for  stapling.  Default  is
       "/var/lib/hitch/".

       Directory  must  be  readable  and  writable  for  the configured Hitch user, or automatic
       retrieval and updating of OCSP responses will not take place.

       If you have a manually pre-loaded OCSP staple, an alternative pem-file syntax can be  used
       for stapling:

          pem-file = {
              cert = "mycert.pem"
              ocsp-resp-file = "ocsp-resp.der"
          }

   ocsp-connect-tmo = <number>
       OCSP fetch connect timeout.

       This does normally not need to be changed.

       Default is 4.0 seconds.

   ocsp-resp-tmo = <number>
       OCSP fetch response timeout.

       This does normally not need to be changed.

       Default is 10 seconds.

   ocsp-refresh-interval = <number>
       OCSP refresh interval.

       If  the OCSP response does not carry any refresh information, use this as the interval for
       refreshing.

       Default is 1800 seconds.

   ocsp-verify-staple = on|off
       If set, OCSP responses will be verified against the certificate after retrieval.

       Default is off.

   pem-file = <string>
       Specify a SSL x509 certificate file. Server Name Indication (SNI) is  supported  by  using
       one certificate file per SNI name.

       Certificates  are  used  in the order they are listed; the last certificate listed will be
       used if none of the others match.

       A file suitable for Hitch is  a  concatenation  of  a  private  key  and  a  corresponding
       certificate or certificate chain.

       At  least one PEM file is needed for Hitch to start, but it can be supplied on the command
       line.

       This option is also available in a  frontend  declaration,  to  make  a  certificate  only
       available for a specific listen endpoint.

   private-key = <string>
       If set, the private key is read from specified location, not from the cert file.

          pem-file = {
              cert = "mycert.pem"
              private-key = "myprivate.key"
          }

   pem-dir = <string>
       Specify a directory for loading x509 certificates.

       A  fallback  certificate for non-SNI clients may be specified by also including a separate
       pem-file definition.

       The  files  are  processed  in  lexicographic  order.  In  the  absence  of  any  pem-file
       definitions, the first file entry will be used as the fallback default.

          pem-dir = "/etc/hitch/cert.d"

   pem-dir-glob = <string>
       Matching filter for filenames loaded from pem-dir.

       Default is none (match any).

          pem-dir-glob = "*.pem"

   prefer-server-ciphers = on|off
       Turns on or off enforcement of the cipher ordering set in Hitch.

       This option is also available in frontend blocks.

       Default is off.

   proxy-proxy = on|off
       Proxy  an  existing  PROXY  protocol  header  through  this request. At the moment this is
       equivalent to write-proxy-v2.

       This option is mutually exclusive with option write-proxy-v2, write-ip and write-proxy-v1.

       Default is off.

   log-level = <num>
       Log chattiness. 0=silence, 1=errors, 2=info/debug.

       This setting can also be changed at run-time by editing the configuration file followed by
       a reload (SIGHUP).

       Default is 0.

   quiet = on|off
       If  quiet  is  turned on, only error messages will be shown. This setting is deprecated in
       favor of log-level.

   tls-protos = ...
       The SSL/TLS protocols to be used. This is an unquoted list of tokens. Available tokens are
       SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 and TLSv1.3.

       The default is TLSv1.2 and TLSv1.3.

       There  are  two deprecated options, ssl= and tls=, that also select protocols. If "ssl=on"
       is used, then all protocols are selected. This is known to be insecure,  and  is  strongly
       discouraged. If "tls=on" is used, the three TLS protocol versions will be used. Turning on
       SSLv3 and TLSv1.0 is not recommended - support for  these  protocols  are  only  kept  for
       backwards compatibility.

       This option is also available in frontend blocks.

   sni-nomatch-abort = on|off
       Abort handshake when the client submits an unrecognized SNI server name.

       This option is also available in a frontend declaration.

   ssl-engine = <string>
       Set the SSL engine. This is used with SSL accelerator cards. See the OpenSSL documentation
       for legal values.

   syslog = on|off
       Send messages to syslog. Default is off.

   syslog-facility = <string>
       Set the syslog facility. Default is "daemon".

   user = <string>
       User to run as. If Hitch is started as root, it will insist on changing  to  a  user  with
       lower rights after binding to sockets.

   workers = <number>
       Number of worker processes. One per CPU core is recommended.

   write-ip = on|off
       Report the client ip to the backend by writing IP before sending data.

       This  option is mutually exclusive with each of the options write-proxy-v2, write-proxy-v1
       and proxy-proxy.

       Default is off.

   write-proxy-v1 = on|off
       Report client address using the PROXY protocol.

       This option is mutually exclusive with option write-proxy-v2, write-ip and proxy-proxy.

       Default is off.

   write-proxy-v2 = on|off
       Report client address using PROXY v2 protocol.

       This option is mutually exclusive with option write-ip, write-proxy-v1 and proxy-proxy.

       Default is off.

   proxy-tlv = on|off
       Report the chosen cipher and protocol as part of the PROXYv2 header.

       Default is on.

EXAMPLE

       The following file shows the syntax needed to get started with:

          frontend = {
              host = "*"
              port = "443"
          }
          backend = "[127.0.0.1]:6086"    # 6086 is the default Varnish PROXY port.
          workers = 4                     # number of CPU cores

          daemon = on

          # We strongly recommend you create a separate non-privileged hitch
          # user and group
          user = "hitch"
          group = "hitch"

          # Enable to let clients negotiate HTTP/2 with ALPN. (default off)
          # alpn-protos = "h2, http/1.1"

          # run Varnish as backend over PROXY; varnishd -a :80 -a localhost:6086,PROXY ..
          write-proxy-v2 = on             # Write PROXY header

AUTHOR

       This manual was written by Pål Hermunn Johansen <hermunn@varnish-software.com>

                                                                                    HITCH.CONF(5)