xenial (1) nghttpx.1.gz

Provided by: nghttp2-proxy_1.7.1-1_amd64 bug

NAME

       nghttpx - HTTP/2 proxy

SYNOPSIS

       nghttpx [OPTIONS]... [<PRIVATE_KEY> <CERT>]

DESCRIPTION

       A reverse proxy for HTTP/2, HTTP/1 and SPDY.

       <PRIVATE_KEY>
              Set path  to server's private key.   Required unless -p, --client or --frontend-no-tls are given.

       <CERT> Set path  to server's certificate.  Required  unless -p, --client or  --frontend-no-tls are given.
              To  make OCSP stapling work, this must be absolute path.

OPTIONS

       The options are categorized into several groups.

   Connections
       -b, --backend=(<HOST>,<PORT>|unix:<PATH>)[;<PATTERN>[:...]]
              Set  backend  host  and   port.   The  multiple  backend addresses are  accepted by repeating this
              option.   UNIX  domain  socket   can  be   specified  by  prefixing  path name with "unix:" (e.g.,
              unix:/var/run/backend.sock).

              Optionally, if <PATTERN>s are given, the backend address is only  used   if  request  matches  the
              pattern.    If -s or -p  is  used,  <PATTERN>s   are  ignored.   The  pattern matching  is closely
              designed to  ServeMux in  net/http package of Go  programming  language.   <PATTERN>  consists  of
              path, host + path or  just host.  The path must start with "/".  If  it ends with "/", it  matches
              all request path in  its subtree.  To  deal with the request  to the directory  without   trailing
              slash,  the path  which ends with "/" also matches the  request path which only lacks trailing '/'
              (e.g., path  "/foo/" matches  request path "/foo").  If it does not  end  with  "/",  it  performs
              exact  match  against  the request path.   If host is  given, it performs exact match against  the
              request host.  If host alone  is given,  "/"  is  appended to   it,   so  that   it  matches   all
              request  paths  under  the   host  (e.g., specifying "nghttp2.org" equals to "nghttp2.org/").

              Patterns  with   host take  precedence over  patterns with just path.   Then, longer patterns take
              precedence over shorter  ones,  breaking  a  tie  by   the   order   of   the  appearance  in  the
              configuration.

              If  <PATTERN>  is  omitted, "/" is used  as pattern, which matches  all  request  paths (catch-all
              pattern).   The catch-all backend must be given.

              When doing  a match, nghttpx made  some normalization to pattern, request host and path.  For host
              part,  they  are  converted  to  lower case.  For path part, percent-encoded unreserved characters
              defined in RFC 3986  are decoded, and  any   dot-segments  (".."   and  ".")    are  resolved  and
              removed.

              For    example,    -b'127.0.0.1,8080;nghttp2.org/httpbin/' matches the  request host "nghttp2.org"
              and  the request path "/httpbin/get", but does not match the request host  "nghttp2.org"  and  the
              request path "/index.html".

              The   multiple  <PATTERN>s   can   be  specified,   delimiting  them             by           ":".
              Specifying -b'127.0.0.1,8080;nghttp2.org:www.nghttp2.org'   has   the  same   effect   to  specify
              -b'127.0.0.1,8080;nghttp2.org' and -b'127.0.0.1,8080;www.nghttp2.org'.

              The backend addresses sharing same <PATTERN> are grouped together forming  load balancing  group.

              Since  ";"  and  ":" are  used as delimiter, <PATTERN> must not  contain these  characters.  Since
              ";" has  special meaning in shell, the option value must be quoted.

              Default: 127.0.0.1,80

       -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)
              Set  frontend  host and  port.   If  <HOST> is  '*',  it assumes  all addresses   including   both
              IPv4 and  IPv6.  UNIX domain  socket can  be specified by  prefixing path name with "unix:" (e.g.,
              unix:/var/run/nghttpx.sock)

              Default: *,3000

       --backlog=<N>
              Set listen backlog size.

              Default: 512

       --backend-ipv4
              Resolve backend hostname to IPv4 address only.

       --backend-ipv6
              Resolve backend hostname to IPv6 address only.

       --backend-http-proxy-uri=<URI>
              Specify      proxy       URI      in        the       form  http://[<USER>:<PASS>@]<PROXY>:<PORT>.
              If    a    proxy requires  authentication,  specify  <USER>  and  <PASS>.  Note that  they must be
              properly  percent-encoded.  This proxy  is used  when the  backend connection  is HTTP/2.   First,
              make  a CONNECT  request  to  the proxy  and  it connects  to the  backend  on behalf  of nghttpx.
              This forms  tunnel.   After  that, nghttpx   performs   SSL/TLS  handshake  with   the  downstream
              through   the   tunnel.   The  timeouts  when  connecting  and   making  CONNECT  request  can  be
              specified    by     --backend-read-timeout    and --backend-write-timeout options.

       --accept-proxy-protocol
              Accept PROXY protocol version 1 on frontend connection.

   Performance
       -n, --workers=<N>
              Set the number of worker threads.

              Default: 1

       --read-rate=<SIZE>
              Set maximum  average read  rate on  frontend connection.  Setting 0 to this option means read rate
              is unlimited.

              Default: 0

       --read-burst=<SIZE>
              Set  maximum read  burst  size  on frontend  connection.  Setting  0  to this  option  means  read
              burst  size  is unlimited.

              Default: 0

       --write-rate=<SIZE>
              Set maximum  average write rate on  frontend connection.  Setting 0 to  this  option  means  write
              rate is unlimited.

              Default: 0

       --write-burst=<SIZE>
              Set  maximum write  burst size  on frontend  connection.  Setting  0 to  this  option means  write
              burst size  is unlimited.

              Default: 0

       --worker-read-rate=<SIZE>
              Set maximum average read rate on frontend connection per  worker.   Setting   0  to   this  option
              means read  rate is unlimited.  Not implemented yet.

              Default: 0

       --worker-read-burst=<SIZE>
              Set  maximum  read burst size on  frontend connection per worker.  Setting 0 to this  option means
              read burst size is unlimited.  Not implemented yet.

              Default: 0

       --worker-write-rate=<SIZE>
              Set maximum  average write  rate on  frontend connection per worker.  Setting  0  to  this  option
              means write rate is unlimited.  Not implemented yet.

              Default: 0

       --worker-write-burst=<SIZE>
              Set  maximum  write burst  size on frontend connection per worker.  Setting 0 to this option means
              write burst size is unlimited.  Not implemented yet.

              Default: 0

       --worker-frontend-connections=<N>
              Set maximum number  of simultaneous connections frontend accepts.  Setting 0 means unlimited.

              Default: 0

       --backend-http2-connections-per-worker=<N>
              Set   maximum   number   of  backend   HTTP/2   physical connections  per  worker.    If   pattern
              is   used   in   -b  option,  this  limit is applied  to each pattern group (in other  words, each
              pattern group  can have  maximum <N> HTTP/2  connections).  The   default   value   is  0,   which
              means   that  the value  is  adjusted  to the  number  of backend addresses.  If pattern  is used,
              this adjustment is done for each pattern group.

       --backend-http1-connections-per-host=<N>
              Set   maximum  number   of  backend   concurrent   HTTP/1  connections  per  origin  host.    This
              option  is  meaningful  when  -s  option   is  used.  The origin  host is determined by  authority
              portion  of request  URI  (or  :authority header  field  for  HTTP/2).   To limit  the  number  of
              connections   per  frontend   for   default  mode,   use --backend-http1-connections-per-frontend.

              Default: 8

       --backend-http1-connections-per-frontend=<N>
              Set    maximum   number   of  backend   concurrent  HTTP/1 connections per frontend.  This  option
              is only used for default mode.   0 means unlimited.  To  limit the number of connections  per host
              for  HTTP/2 or SPDY  proxy mode (-s option), use --backend-http1-connections-per-host.

              Default: 0

       --rlimit-nofile=<N>
              Set  maximum number of open files (RLIMIT_NOFILE) to <N>.  If 0 is given, nghttpx does not set the
              limit.

              Default: 0

       --backend-request-buffer=<SIZE>
              Set buffer size used to store backend request.

              Default: 16K

       --backend-response-buffer=<SIZE>
              Set buffer size used to store backend response.

              Default: 128K

       --fastopen=<N>
              Enables  "TCP Fast  Open" for  the listening  socket and limits the  maximum length for the  queue
              of  connections that have not yet completed the three-way handshake.  If value is 0 then fast open
              is disabled.

              Default: 0

   Timeout
       --frontend-http2-read-timeout=<DURATION>
              Specify  read  timeout  for  HTTP/2  and  SPDY  frontend connection.

              Default: 3m

       --frontend-read-timeout=<DURATION>
              Specify read timeout for HTTP/1.1 frontend connection.

              Default: 1m

       --frontend-write-timeout=<DURATION>
              Specify write timeout for all frontend connections.

              Default: 30s

       --stream-read-timeout=<DURATION>
              Specify  read timeout  for HTTP/2  and SPDY  streams.  0 means no timeout.

              Default: 0

       --stream-write-timeout=<DURATION>
              Specify write  timeout for  HTTP/2 and SPDY  streams.  0 means no timeout.

              Default: 0

       --backend-read-timeout=<DURATION>
              Specify read timeout for backend connection.

              Default: 1m

       --backend-write-timeout=<DURATION>
              Specify write timeout for backend connection.

              Default: 30s

       --backend-keep-alive-timeout=<DURATION>
              Specify keep-alive timeout for backend connection.

              Default: 2s

       --listener-disable-timeout=<DURATION>
              After accepting  connection failed,  connection listener is disabled  for a given  amount of time.
              Specifying 0 disables this feature.

              Default: 30s

   SSL/TLS
       --ciphers=<SUITE>
              Set allowed  cipher list.  The  format of the  string is described in OpenSSL ciphers(1).

       -k, --insecure
              Don't   verify   backend  server's  certificate   if  -p, --client    or    --http2-bridge     are
              given    and --backend-no-tls is not given.

       --cacert=<PATH>
              Set path to trusted CA  certificate  file  if  -p,  --client  or  --http2-bridge  are  given   and
              --backend-no-tls  is  not  given.   The  file  must  be   in  PEM format.  It can contain multiple
              certificates.    If  the  linked   OpenSSL  is configured  to   load  system   wide  certificates,
              they are loaded at startup regardless of this option.

       --private-key-passwd-file=<PATH>
              Path   to file  that contains  password for  the server's private key.   If none is  given and the
              private  key is password protected it'll be requested interactively.

       --subcert=<KEYPATH>:<CERTPATH>
              Specify  additional certificate  and  private key  file.  nghttpx will  choose certificates  based
              on   the  hostname  indicated  by  client  using TLS  SNI  extension.   This option  can  be  used
              multiple  times.   To  make  OCSP stapling work, <CERTPATH> must be absolute path.

       --backend-tls-sni-field=<HOST>
              Explicitly  set the  content of  the TLS  SNI extension.  This will default to  the  backend  HOST
              name.

       --dh-param-file=<PATH>
              Path  to  file  that contains  DH parameters in PEM format.  Without  this   option,  DHE   cipher
              suites   are  not available.

       --npn-list=<LIST>
              Comma delimited list of  ALPN protocol identifier sorted in the  order of preference.  That  means
              most  desirable  protocol comes  first.  This  is used  in both  ALPN and NPN.  The parameter must
              be  delimited by a single comma only  and any  white spaces  are  treated as  a part  of  protocol
              string.

              Default: h2,h2-16,h2-14,spdy/3.1,http/1.1

       --verify-client
              Require and verify client certificate.

       --verify-client-cacert=<PATH>
              Path   to file  that contains  CA certificates  to verify client certificate.  The file must be in
              PEM format.  It can contain multiple certificates.

       --client-private-key-file=<PATH>
              Path to  file that contains  client private key  used in backend client authentication.

       --client-cert-file=<PATH>
              Path to  file that  contains client certificate  used in backend client authentication.

       --tls-proto-list=<LIST>
              Comma delimited list of  SSL/TLS protocol to be enabled.  The following protocols  are  available:
              TLSv1.2,  TLSv1.1  and    TLSv1.0.     The    name    matching    is    done   in case-insensitive
              manner.    The  parameter   must   be delimited by  a single comma  only and any  white spaces are
              treated   as  a   part  of  protocol string.   If  the protocol list advertised by client does not
              overlap this list,  you  will  receive  the  error  message  "unknown protocol".

              Default: TLSv1.2,TLSv1.1

       --tls-ticket-key-file=<PATH>
              Path to file that  contains   random  data  to  construct  TLS  session  ticket   parameters.   If
              aes-128-cbc  is   given  in  --tls-ticket-key-cipher, the  file must  contain exactly 48    bytes.
              If     aes-256-cbc    is    given    in --tls-ticket-key-cipher, the  file must   contain  exactly
              80  bytes.   This  options  can be  used  repeatedly  to specify  multiple ticket  parameters.  If
              several files are given,  only the  first key is  used to  encrypt TLS  session   tickets.   Other
              keys  are   accepted  but   server will  issue new  session  ticket with  first key.   This allows
              session  key  rotation.  Please  note  that  key rotation  does  not  occur automatically.    User
              should  rearrange   files or  change options  values and  restart nghttpx gracefully.   If opening
              or reading  given file fails, all loaded  keys are discarded and  it is treated  as  if  none   of
              this option is given.  If  this option is not given or an error  occurred while opening or reading
              a file,  key is  generated every  1 hour  internally and they are  valid for  12 hours.   This  is
              recommended if ticket  key sharing  between  nghttpx  instances is  not required.

       --tls-ticket-key-memcached=<HOST>,<PORT>
              Specify   address  of   memcached  server   to  store   session cache.   This  enables  shared TLS
              ticket  key  between multiple nghttpx  instances.  nghttpx  does not   set  TLS  ticket   key   to
              memcached.    The   external  ticket  key generator  is required.   nghttpx just  gets TLS  ticket
              keys from  memcached, and  use them,  possibly replacing current set of keys.  It is  up to extern
              TLS  ticket  key  generator  to   rotate  keys  frequently.   See  "TLS SESSION TICKET RESUMPTION"
              section in  manual page to  know the data format in memcached entry.

       --tls-ticket-key-memcached-interval=<DURATION>
              Set interval to get TLS ticket keys from memcached.

              Default: 10m

       --tls-ticket-key-memcached-max-retry=<N>
              Set  maximum   number  of  consecutive   retries  before abandoning TLS ticket key  retrieval.  If
              this  number  is  reached,   the   attempt   is  considered  as  failure,  and "failure" count  is
              incremented by 1,  which  contributed  to             the             value             controlled
              --tls-ticket-key-memcached-max-fail option.

              Default: 3

       --tls-ticket-key-memcached-max-fail=<N>
              Set  maximum   number  of  consecutive   failure  before disabling TLS ticket until next scheduled
              key retrieval.

              Default: 2

       --tls-ticket-key-cipher=<CIPHER>
              Specify cipher  to encrypt TLS session  ticket.  Specify either   aes-128-cbc    or   aes-256-cbc.
              By   default, aes-128-cbc is used.

       --fetch-ocsp-response-file=<PATH>
              Path to  fetch-ocsp-response script file.  It  should be absolute path.

              Default: /usr/local/share/nghttp2/fetch-ocsp-response

       --ocsp-update-interval=<DURATION>
              Set interval to update OCSP response cache.

              Default: 4h

       --no-ocsp
              Disable OCSP stapling.

       --tls-session-cache-memcached=<HOST>,<PORT>
              Specify   address of  memcached server  to store  session cache.   This  enables   shared  session
              cache  between multiple nghttpx instances.

       --tls-dyn-rec-warmup-threshold=<SIZE>
              Specify the  threshold size for TLS  dynamic record size behaviour.  During  a TLS  session, after
              the  threshold  number  of bytes  have been written, the  TLS record size will be increased to the
              maximum allowed (16K).  The max record size will  continue to be used on  the active TLS  session.
              After  --tls-dyn-rec-idle-timeout has elapsed, the record size is reduced  to 1300 bytes.  Specify
              0 to always use  the maximum record size,  regardless of idle period.   This   behaviour   applies
              to  all  TLS  based frontends, and TLS HTTP/2 backends.

              Default: 1M

       --tls-dyn-rec-idle-timeout=<DURATION>
              Specify  TLS  dynamic  record   size  behaviour  timeout.  See --tls-dyn-rec-warmup-threshold  for
              more  information.  This behaviour  applies to all TLS  based frontends, and TLS HTTP/2 backends.

              Default: 1s

   HTTP/2 and SPDY
       -c, --http2-max-concurrent-streams=<N>
              Set the maximum number of  the concurrent streams in one HTTP/2 and SPDY session.

              Default: 100

       --frontend-http2-window-bits=<N>
              Sets the  per-stream initial window size  of HTTP/2 SPDY frontend connection.   For  HTTP/2,   the
              size is 2**<N>-1.  For SPDY, the size is 2**<N>.

              Default: 16

       --frontend-http2-connection-window-bits=<N>
              Sets  the   per-connection window size of  HTTP/2 and SPDY frontend   connection.    For   HTTP/2,
              the   size   is 2**<N>-1. For SPDY, the size is 2**<N>.

              Default: 16

       --frontend-no-tls
              Disable SSL/TLS on frontend connections.

       --backend-http2-window-bits=<N>
              Sets  the   initial  window   size  of   HTTP/2  backend connection to 2**<N>-1.

              Default: 16

       --backend-http2-connection-window-bits=<N>
              Sets the  per-connection window  size of  HTTP/2 backend connection to 2**<N>-1.

              Default: 16

       --backend-no-tls
              Disable SSL/TLS on backend connections.

       --http2-no-cookie-crumbling
              Don't crumble cookie header field.

       --padding=<N>
              Add  at most  <N> bytes  to  a HTTP/2  frame payload  as padding.  Specify 0 to  disable  padding.
              This option is meant for debugging purpose  and not intended to enhance protocol security.

       --no-server-push
              Disable  HTTP/2  server  push.   Server push is supported by default mode and HTTP/2  frontend via
              Link header field.  It is  also supported if  both frontend and  backend are HTTP/2 (which implies
              --http2-bridge  or  --client  mode).   In   this   case,   server  push from  backend  session  is
              relayed  to frontend,  and server  push via  Link header field is   also  supported.    HTTP  SPDY
              frontend  does not support server push.

   Mode
       (default mode)
              Accept  HTTP/2,  SPDY  and HTTP/1.1  over  SSL/TLS.   If --frontend-no-tls is  used, accept HTTP/2
              and HTTP/1.1.  The  incoming HTTP/1.1  connection  can  be  upgraded   to  HTTP/2   through   HTTP
              Upgrade.   The  protocol  to  the backend is HTTP/1.1.

       -s, --http2-proxy
              Like default mode, but enable secure proxy mode.

       --http2-bridge
              Like  default  mode, but communicate with  the backend in HTTP/2 over SSL/TLS.  Thus  the incoming
              all  connections  are  converted   to  HTTP/2   connection  and  relayed   to  the  backend.   See
              --backend-http-proxy-uri  option  if  you  are  behind   the  proxy   and want  to connect  to the
              outside HTTP/2 proxy.

       --client
              Accept  HTTP/2   and  HTTP/1.1  without   SSL/TLS.   The  incoming  HTTP/1.1   connection  can  be
              upgraded   to  HTTP/2  connection through  HTTP Upgrade.   The protocol  to the backend is HTTP/2.
              To use nghttpx as  a forward proxy, use -p option instead.

       -p, --client-proxy
              Like --client  option, but it also  requires the request path from frontend must  be  an  absolute
              URI, suitable for use as a forward proxy.

   Logging
       -L, --log-level=<LEVEL>
              Set  the  severity   level  of  log output.   <LEVEL> must be one of INFO, NOTICE, WARN, ERROR and
              FATAL.

              Default: NOTICE

       --accesslog-file=<PATH>
              Set path to write access log.  To reopen file, send USR1 signal to nghttpx.

       --accesslog-syslog
              Send  access log  to syslog.   If this  option is  used, --accesslog-file option is ignored.

       --accesslog-format=<FORMAT>
              Specify  format  string  for  access   log.    The   default  format  is  combined  format.    The
              following variables are available:

              • $remote_addr: client IP address.

              • $time_local: local time in Common Log format.

              • $time_iso8601: local time in ISO 8601 format.

              • $request: HTTP request line.

              • $status: HTTP response status code.

              • $body_bytes_sent: the  number of bytes sent  to client as response body.

              • $http_<VAR>: value of HTTP  request header <VAR> where '_' in <VAR> is replaced with '-'.

              • $remote_port: client  port.

              • $server_port: server port.

              • $request_time: request processing time in seconds with milliseconds resolution.

              • $pid: PID of the running process.

              • $alpn:  ALPN  identifier  of  the  protocol which generates the response.   For HTTP/1,  ALPN is
                always http/1.1, regardless of minor version.

              • $ssl_cipher: cipher used for SSL/TLS connection.

              • $ssl_protocol: protocol for SSL/TLS connection.

              • $ssl_session_id: session ID for SSL/TLS connection.

              • $ssl_session_reused:  "r"   if  SSL/TLS   session  was reused.  Otherwise, "."

              The  variable  can  be  enclosed  by  "{"  and  "}"  for disambiguation (e.g., ${remote_addr}).

              Default: $remote_addr  -  -  [$time_local]  "$request"  $status  $body_bytes_sent  "$http_referer"
              "$http_user_agent"

       --errorlog-file=<PATH>
              Set  path  to  write  error  log.  To reopen file, send USR1 signal  to nghttpx.   stderr will  be
              redirected  to the error log file unless --errorlog-syslog is used.

              Default: /dev/stderr

       --errorlog-syslog
              Send  error log  to  syslog.  If  this  option is  used, --errorlog-file option is ignored.

       --syslog-facility=<FACILITY>
              Set syslog facility to <FACILITY>.

              Default: daemon

   HTTP
       --add-x-forwarded-for
              Append  X-Forwarded-For header  field to  the downstream request.

       --strip-incoming-x-forwarded-for
              Strip X-Forwarded-For  header field from  inbound client requests.

       --add-forwarded=<LIST>
              Append RFC  7239 Forwarded header field  with parameters specified in comma delimited list <LIST>.
              The  supported  parameters   are  "by",  "for", "host",  and "proto".   By default,  the value  of
              "by"  and   "for"  parameters   are  obfuscated      string.      See      --forwarded-by      and
              --forwarded-for  options  respectively.   Note  that  nghttpx  does   not   translate non-standard
              X-Forwarded-*  header fields into Forwarded header field, and vice versa.

       --strip-incoming-forwarded
              Strip  Forwarded   header  field  from   inbound  client requests.

       --forwarded-by=(obfuscated|ip|<VALUE>)
              Specify the parameter value sent  out  with  "by"  parameter  of  Forwarded   header  field.    If
              "obfuscated"   is  given,  the  string  is randomly generated at startup.  If "ip" is given,   the
              interface    address   of    the   connection,  including   port  number,   is   sent   with  "by"
              parameter.   User can also specify the static obfuscated string.  The limitation  is that  it must
              start with  "_", and  only consists of  character set [A-Za-z0-9._-],  as described in RFC 7239.

              Default: obfuscated

       --forwarded-for=(obfuscated|ip)
              Specify  the   parameter  value  sent  out   with  "for" parameter of Forwarded header field.   If
              "obfuscated"  is  given, the string is  randomly generated for each client connection.  If "ip" is
              given, the remote client address of  the connection,  without port  number, is   sent  with  "for"
              parameter.

              Default: obfuscated

       --no-via
              Don't append to  Via header field.  If  Via header field is received, it is left unaltered.

       --no-location-rewrite
              Don't  rewrite   location  header  field   on --http2-bridge, --client  and  default   mode.   For
              --http2-proxy  and --client-proxy mode,  location header field will  not be altered regardless  of
              this option.

       --host-rewrite
              Rewrite   host   and   :authority   header   fields   on --http2-bridge,   --client   and  default
              mode.    For --http2-proxy   and   --client-proxy  mode,   these   headers  will  not  be  altered
              regardless of this option.

       --altsvc=<PROTOID,PORT[,HOST,[ORIGIN]]>
              Specify    protocol   ID,    port,   host    and   origin    of  alternative service.  <HOST>  and
              <ORIGIN> are optional.  They   are  advertised   in   alt-svc  header   field  only   in  HTTP/1.1
              frontend.   This   option  can   be  used   multiple  times   to   specify  multiple   alternative
              services.  Example: --altsvc=h2,443

       --add-request-header=<HEADER>
              Specify additional header field to add to request header set.  This  option just   appends  header
              field   and  won't  replace  anything   already set.  This option  can be used several  times   to
              specify  multiple   header  fields.  Example: --add-request-header="foo: bar"

       --add-response-header=<HEADER>
              Specify  additional  header  field to  add  to  response header set.   This  option  just  appends
              header  field  and won't replace anything already  set.  This option can be used several  times to
              specify multiple  header fields.  Example: --add-response-header="foo: bar"

       --header-field-buffer=<SIZE>
              Set maximum buffer size for incoming HTTP request header field list.  This is the  sum  of  header
              name and value in bytes.

              Default: 64K

       --max-header-fields=<N>
              Set   maximum  number  of incoming  HTTP  request  header fields, which  appear in one request  or
              response header field list.

              Default: 100

   Debug
       --frontend-http2-dump-request-header=<PATH>
              Dumps request headers received by HTTP/2 frontend to the file denoted  in <PATH>.  The  output  is
              done   in  HTTP/1  header  field  format and each header block is followed by an empty line.  This
              option  is not thread safe and MUST NOT be used with option -n<N>, where <N> >= 2.

       --frontend-http2-dump-response-header=<PATH>
              Dumps response headers sent  from HTTP/2 frontend to the file denoted  in <PATH>.  The  output  is
              done   in  HTTP/1  header  field  format and each header block is followed by an empty line.  This
              option  is not thread safe and MUST NOT be used with option -n<N>, where <N> >= 2.

       -o, --frontend-frame-debug
              Print HTTP/2 frames in  frontend to stderr.  This option is  not thread  safe and   MUST  NOT   be
              used  with option -n=N, where N >= 2.

   Process
       -D, --daemon
              Run in a background.  If -D is used, the current working directory is changed to '/'.

       --pid-file=<PATH>
              Set path to save PID of this program.

       --user=<USER>
              Run this program as <USER>.   This option is intended to be used to drop root privileges.

   Scripting
       --mruby-file=<PATH>
              Set mruby script file

   Misc
       --conf=<PATH>
              Load configuration from <PATH>.

              Default: /etc/nghttpx/nghttpx.conf

       --include=<PATH>
              Load  additional  configurations  from  <PATH>.  File <PATH> is  read  when  configuration  parser
              encountered  this option.  This option can be used multiple times, or even recursively.

       -v, --version
              Print version and exit.

       -h, --help
              Print this help and exit.

       The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10 * 1024).  Units are K,  M  and  G
       (powers of 1024).

       The  <DURATION>  argument  is  an  integer  and  an  optional unit (e.g., 1s is 1 second and 500ms is 500
       milliseconds).  Units are h, m, s or ms (hours, minutes, seconds and milliseconds, respectively).   If  a
       unit is omitted, a second is used as unit.

FILES

       /etc/nghttpx/nghttpx.conf
              The  default configuration file path nghttpx searches at startup.  The configuration file path can
              be changed using --conf option.

              Those lines which are staring # are treated as comment.

              The option name in the configuration file is the long command-line option  name  with  leading  --
              stripped  (e.g.,  frontend).   Put  =  between  option name and value.  Don't put extra leading or
              trailing spaces.

              When specifying arguments including characters which have special meaning to a shell,  we  usually
              use  quotes  so  that shell does not interpret them.  When writing this configuration file, quotes
              for this purpose must not be used.  For example, specify additional request header field, do this:

                 add-request-header=foo: bar

              instead of:

                 add-request-header="foo: bar"

              The options which do not take argument in the command-line  take  argument  in  the  configuration
              file.   Specify  yes  as  an  argument  (e.g.,  http2-proxy=yes).  If other string is given, it is
              ignored.

              To specify  private  key  and  certificate  file  which  are  given  as  positional  arguments  in
              command-line, use private-key-file and certificate-file.

              --conf option cannot be used in the configuration file and will be ignored if specified.

SIGNALS

       SIGQUIT
              Shutdown  gracefully.   First accept pending connections and stop accepting connection.  After all
              connections are handled, nghttpx exits.

       SIGUSR1
              Reopen log files.

       SIGUSR2
              Fork and execute nghttpx.  It will execute the binary in the  same  path  with  same  command-line
              arguments  and environment variables.  After new process comes up, sending SIGQUIT to the original
              process to perform hot swapping.

       NOTE:
          nghttpx consists of multiple processes: one process for processing these signals, and another one  for
          processing  requests.   The  former  spawns  the latter.  The former is called master process, and the
          latter is called worker process.  If neverbleed is  enabled,  the  worker  process  spawns  neverbleed
          daemon  process  which  does RSA key processing.  The above signal must be sent to the master process.
          If the other processes received one of them, it is ignored.  This behaviour  of  these  processes  may
          change  in the future release.  In other words, in the future release, the processes other than master
          process may terminate upon the reception of these signals.  Therefore these signals should not be sent
          to the processes other than master process.

SERVER PUSH

       nghttpx  supports  HTTP/2  server  push  in  default mode with Link header field.  nghttpx looks for Link
       header field (RFC 5988) in response headers from backend server and extracts URI-reference with parameter
       rel=preload  (see  preload)  and  pushes  those URIs to the frontend client. Here is a sample Link header
       field to initiate server push:

          Link: </fonts/font.woff>; rel=preload
          Link: </css/theme.css>; rel=preload

       Currently, the following restriction is applied for server push:

       1. The associated stream must have method "GET" or "POST".  The associated stream's status code  must  be
          200.

       This limitation may be loosened in the future release.

       nghttpx  also  supports server push if both frontend and backend are HTTP/2 (which implies --http2-bridge
       or --client).  In this case, in addition to server push via Link header field, server push  from  backend
       is relayed to frontend HTTP/2 session.

       HTTP/2 server push will be disabled if --http2-proxy or --client-proxy is used.

UNIX DOMAIN SOCKET

       nghttpx supports UNIX domain socket with a filename for both frontend and backend connections.

       Please  note  that current nghttpx implementation does not delete a socket with a filename.  And on start
       up, if nghttpx detects that the specified socket already exists in the file system, nghttpx first deletes
       it.   However,  if  SIGUSR2  is  used  to execute new binary and both old and new configurations use same
       filename, new binary does not delete the socket and continues to use it.

OCSP STAPLING

       OCSP query is done using external Python script fetch-ocsp-response, which has been originally  developed
       in Perl as part of h2o project (https://github.com/h2o/h2o), and was translated into Python.

       The script file is usually installed under $(prefix)/share/nghttp2/ directory.  The actual path to script
       can be customized using --fetch-ocsp-response-file option.

       If OCSP query is failed, previous OCSP response, if any, is continued to be used.

TLS SESSION RESUMPTION

       nghttpx supports TLS session resumption through both session ID and session ticket.

   SESSION ID RESUMPTION
       By default, session ID is shared by all worker threads.

       If --tls-session-cache-memcached is given, nghttpx will insert serialized session data to memcached  with
       nghttpx:tls-session-cache:  +  lowercased  hex string of session ID as a memcached entry key, with expiry
       time 12 hours.  Session timeout is set to 12 hours.

   TLS SESSION TICKET RESUMPTION
       By default, session ticket is shared by all worker threads.  The automatic key rotation is  also  enabled
       by  default.   Every  an  hour,  new  encryption  key  is  generated, and previous encryption key becomes
       decryption only key.  We set session timeout to 12 hours, and thus we keep at most 12 keys.

       If --tls-ticket-key-memcached is given, encryption keys are retrieved from memcached.  nghttpx just reads
       keys  from  memcached;  one  has to deploy key generator program to update keys frequently (e.g., every 1
       hour).  The example key generator tlsticketupdate.go is available  under  contrib  directory  in  nghttp2
       archive.   The memcached entry key is nghttpx:tls-ticket-key.  The data format stored in memcached is the
       binary format described below:

          +--------------+-------+----------------+
          | VERSION (4)  |LEN (2)|KEY(48 or 80) ...
          +--------------+-------+----------------+
                         ^                        |
                         |                        |
                         +------------------------+
                         (LEN, KEY) pair can be repeated

       All numbers in the above figure is bytes.  All integer fields are network byte order.

       First 4 bytes integer VERSION field, which must be 1.  The 2 bytes integer LEN field gives the length  of
       following KEY field, which contains key.  If --tls-ticket-key-cipher=aes-128-cbc is used, LEN must be 48.
       If --tls-ticket-key-cipher=aes-256-cbc is used, LEN must be  80.   LEN  and  KEY  pair  can  be  repeated
       multiple  times  to  store  multiple  keys.   The  key appeared first is used as encryption key.  All the
       remaining keys are used as decryption only.

       If --tls-ticket-key-file is given, encryption key is read from the given file.   In  this  case,  nghttpx
       does not rotate key automatically.  To rotate key, one has to restart nghttpx (see SIGNALS).

MRUBY SCRIPTING

       WARNING:
          The  current  mruby extension API is experimental and not frozen.  The API is subject to change in the
          future release.

       nghttpx allows users to extend its capability using mruby scripts.  nghttpx has 2 hook points to  execute
       mruby  script:  request  phase  and  response phase.  The request phase hook is invoked after all request
       header fields are received from client.  The response phase hook is invoked  after  all  response  header
       fields  are  received  from  backend server.  These hooks allows users to modify header fields, or common
       HTTP variables, like authority or request path,  and  even  return  custom  response  without  forwarding
       request to backend servers.

       To  specify  mruby script file, use --mruby-file option.  The script will be evaluated once per thread on
       startup, and it must instantiate object and evaluate it as the return value (e.g., App.new).  This object
       is  called  app  object.   If  app object defines on_req method, it is called with Nghttpx::Env object on
       request hook.  Similarly, if app object defines on_resp method, it is called with Nghttpx::Env object  on
       response  hook.   For  each method invocation, user can can access Nghttpx::Request and Nghttpx::Response
       objects via Nghttpx::Env#req and Nghttpx::Env#resp respectively.

       Nghttpx::REQUEST_PHASE
              Constant to represent request phase.

       Nghttpx::RESPONSE_PHASE
              Constant to represent response phase.

       class Nghttpx::Env
              Object to represent current request specific context.

              attribute [R] req
                     Return Request object.

              attribute [R] resp
                     Return Response object.

              attribute [R] ctx
                     Return Ruby hash object.  It persists until request finishes.  So  values  set  in  request
                     phase hoo can be retrieved in response phase hook.

              attribute [R] phase
                     Return the current phase.

              attribute [R] remote_addr
                     Return IP address of a remote client.

       class Nghttpx::Request
              Object  to  represent  request from client.  The modification to Request object is allowed only in
              request phase hook.

              attribute [R] http_version_major
                     Return HTTP major version.

              attribute [R] http_version_minor
                     Return HTTP minor version.

              attribute [R/W] method
                     HTTP method.  On assignment, copy of given value is assigned.  We  don't  accept  arbitrary
                     method  name.  We will document them later, but well known methods, like GET, PUT and POST,
                     are all supported.

              attribute [R/W] authority
                     Authority (i.e., example.org), including optional port component .  On assignment, copy  of
                     given value is assigned.

              attribute [R/W] scheme
                     Scheme (i.e., http, https).  On assignment, copy of given value is assigned.

              attribute [R/W] path
                     Request  path, including query component (i.e., /index.html).  On assignment, copy of given
                     value is assigned.  The path does not include authority component of URI.

              attribute [R] headers
                     Return Ruby hash containing copy of request header fields.   Changing  values  in  returned
                     hash  does  not  change  request  header  fields  actually used in request processing.  Use
                     Nghttpx::Request#add_header or Nghttpx::Request#set_header to change request header fields.

              add_header(key, value)
                     Add header entry associated with key.  The value can be single string or array  of  string.
                     It does not replace any existing values associated with key.

              set_header(key, value)
                     Set  header  entry associated with key.  The value can be single string or array of string.
                     It replaces any existing values associated with key.

              clear_headers()
                     Clear all existing request header fields.

              push uri
                     Initiate to push resource identified by uri.  Only HTTP/2 protocol supports  this  feature.
                     For  the  other  protocols, this method is noop.  uri can be absolute URI, absolute path or
                     relative path to the current request.  For absolute or relative path, scheme and  authority
                     are  inherited  from  the  current request.  Currently, method is always GET.  nghttpx will
                     issue request to backend servers to fulfill this request.  The request and  response  phase
                     hooks will be called for pushed resource as well.

       class Nghttpx::Response
              Object to represent response from backend server.

              attribute [R] http_version_major
                     Return HTTP major version.

              attribute [R] http_version_minor
                     Return HTTP minor version.

              attribute [R/W] status
                     HTTP  status  code.   It  must be in the range [200, 999], inclusive.  The non-final status
                     code is not supported in mruby scripting at the moment.

              attribute [R] headers
                     Return Ruby hash containing copy of response header fields.  Changing  values  in  returned
                     hash  does  not  change  response  header fields actually used in response processing.  Use
                     Nghttpx::Response#add_header or  Nghttpx::Response#set_header  to  change  response  header
                     fields.

              add_header(key, value)
                     Add  header  entry associated with key.  The value can be single string or array of string.
                     It does not replace any existing values associated with key.

              set_header(key, value)
                     Set header entry associated with key.  The value can be single string or array  of  string.
                     It replaces any existing values associated with key.

              clear_headers()
                     Clear all existing response header fields.

              return(body)
                     Return custom response body to a client.  When this method is called in request phase hook,
                     the request is not forwarded to the backend, and response phase hook for this request  will
                     not  be  invoked.  When this method is called in response phase hook, response from backend
                     server is canceled and discarded.  The status code and response header fields should be set
                     before  using this method.  To set status code, use :rb:meth To set response header fields,
                     use   Nghttpx::Response#status.    If   status   code   is   not   set,   200   is    used.
                     Nghttpx::Response#add_header and Nghttpx::Response#set_header.  When this method is invoked
                     in response phase hook, the response headers are filled with the ones received from backend
                     server.      To     send     completely     custom     header     fields,     first    call
                     Nghttpx::Response#clear_headers to erase all existing header fields, and then add  required
                     header fields.  It is an error to call this method twice for a given request.

   MRUBY EXAMPLES
       Modify request path:

          class App
            def on_req(env)
              env.req.path = "/apps#{env.req.path}"
            end
          end

          App.new

       Don't forget to instantiate and evaluate object at the last line.

       Restrict permission of viewing a content to a specific client addresses:

          class App
            def on_req(env)
              allowed_clients = ["127.0.0.1", "::1"]

              if env.req.path.start_with?("/log/") &&
                 !allowed_clients.include?(env.remote_addr) then
                env.resp.status = 404
                env.resp.return "permission denied"
              end
            end
          end

          App.new

SEE ALSO

       nghttp(1), nghttpd(1), h2load(1)

AUTHOR

       Tatsuhiro Tsujikawa

       2012, 2015, 2016, Tatsuhiro Tsujikawa