1NGHTTPX(1)                          nghttp2                         NGHTTPX(1)
2
3
4

NAME

6       nghttpx - HTTP/2 proxy
7

SYNOPSIS

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

DESCRIPTION

12       A reverse proxy for HTTP/2, and HTTP/1.
13
14       <PRIVATE_KEY>
15              Set    path   to   server's  private   key.    Required   unless
16              "no-tls" parameter is used in --frontend option.
17
18       <CERT> Set   path   to   server's   certificate.     Required    unless
19              "no-tls"   parameter  is   used in  --frontend option.   To make
20              OCSP stapling work, this must be an absolute path.
21

OPTIONS

23       The options are categorized into several groups.
24
25   Connections
26       -b,                       --backend=(<HOST>,<PORT>|unix:<PATH>)[;[<PAT‐
27       TERN>[:...]][[;<PARAM>]...]
28              Set    backend   host   and    port.    The   multiple   backend
29              addresses are  accepted by repeating this  option.  UNIX  domain
30              socket   can  be  specified by prefixing  path name with "unix:"
31              (e.g., unix:/var/run/backend.sock).
32
33              Optionally, if <PATTERN>s are  given,  the  backend  address  is
34              only   used   if   request  matches  the  pattern.   The pattern
35              matching is  closely  designed  to ServeMux  in net/http package
36              of   Go programming language.  <PATTERN> consists of  path, host
37              +  path or just host.   The path must start  with "/".   If   it
38              ends  with  "/",  it matches all  request path  in  its subtree.
39              To  deal with  the request  to the  directory without   trailing
40              slash,   the path which ends  with "/" also matches  the request
41              path which  only  lacks  trailing  '/'   (e.g.,   path   "/foo/"
42              matches request path  "/foo").  If it does  not end with "/", it
43              performs exact match against  the request path.   If   host   is
44              given,   it  performs  a match  against  the request host.   For
45              a  request received on  the frontend  listener  with   "sni-fwd"
46              parameter  enabled, SNI  host is used instead of a request host.
47              If host alone is given, "/" is  appended  to  it,   so  that  it
48              matches   all  request paths  under the  host  (e.g., specifying
49              "nghttp2.org" equals  to "nghttp2.org/").   CONNECT  method   is
50              treated specially.  It  does not have  path, and we  don't allow
51              empty path.  To workaround  this, we assume that CONNECT  method
52              has "/" as path.
53
54              Patterns  with   host  take  precedence over  patterns with just
55              path.   Then, longer  patterns  take   precedence  over  shorter
56              ones.
57
58              Host   can   include "*"  in  the  left most  position  to indi‐
59              cate  wildcard match  (only suffix  match is   done).   The  "*"
60              must match at least one character.  For example, host    pattern
61              "*.nghttp2.org"     matches     against  "www.nghttp2.org"   and
62              "git.ngttp2.org",  but  does  not match  against  "nghttp2.org".
63              The exact  hosts  match takes precedence over the wildcard hosts
64              match.
65
66              If  path   part ends with  "*", it is treated  as wildcard path.
67              The  wildcard path  behaves differently  from the  normal  path.
68              For normal path,  match is made around the boundary of path com‐
69              ponent  separator,"/".  On the other hand,  the  wildcard   path
70              does  not take  into account the path component  separator.  All
71              paths which  include the wildcard  path  without  last   "*"  as
72              prefix,   and   are  strictly longer than wildcard  path without
73              last "*" are matched.  "*"  must match  at least one  character.
74              For  example,   the    pattern   "/foo*"  matches   "/foo/"  and
75              "/foobar".  But it does not match "/foo", or "/fo".
76
77              If <PATTERN> is omitted or  empty string, "/" is  used  as  pat‐
78              tern,   which  matches  all request  paths  (catch-all pattern).
79              The catch-all backend must be given.
80
81              When doing  a match, nghttpx made  some  normalization  to  pat‐
82              tern,  request host and path.  For host part, they are converted
83              to lower case.  For path part, percent-encoded unreserved  char‐
84              acters   defined in RFC 3986  are decoded, and any  dot-segments
85              (".."  and ".")   are resolved and removed.
86
87              For   example,   -b'127.0.0.1,8080;nghttp2.org/httpbin/' matches
88              the   request  host  "nghttp2.org" and  the request path "/http‐
89              bin/get", but does not match the request host "nghttp2.org"  and
90              the request path "/index.html".
91
92              The   multiple  <PATTERN>s   can  be specified,  delimiting them
93              by                       ":".                         Specifying
94              -b'127.0.0.1,8080;nghttp2.org:www.nghttp2.org'   has   the  same
95              effect    to   specify     -b'127.0.0.1,8080;nghttp2.org'    and
96              -b'127.0.0.1,8080;www.nghttp2.org'.
97
98              The   backend  addresses  sharing  same  <PATTERN>  are  grouped
99              together forming  load balancing  group.
100
101              Several parameters <PARAM> are accepted  after  <PATTERN>.   The
102              parameters  are   delimited  by  ";".  The  available parameters
103              are:        "proto=<PROTO>",         "tls",    "sni=<SNI_HOST>",
104              "fall=<N>",         "rise=<N>",  "affinity=<METHOD>",     "dns",
105              "redirect-if-not-tls",                         "upgrade-scheme",
106              "mruby=<PATH>",     "read-timeout=<DURATION>",      "write-time‐
107              out=<DURATION>",   "group=<GROUP>",    "group-weight=<N>",   and
108              "weight=<N>".   The   parameter   consists    of   keyword,  and
109              optionally followed by  "=" and value.  For  example, the param‐
110              eter  "proto=h2"   consists  of  the keyword  "proto" and  value
111              "h2".  The parameter "tls" consists of the keyword "tls" without
112              value.  Each parameter is described as follows.
113
114              The   backend  application  protocol   can  be  specified  using
115              optional   "proto"    parameter,   and    in   the    form    of
116              "proto=<PROTO>".   <PROTO>  should  be one of the following list
117              without  quotes:  "h2",  "http/1.1".    The   default  value  of
118              <PROTO> is  "http/1.1".  Note that usually "h2" refers to HTTP/2
119              over TLS.  But in this  option, it may mean HTTP/2  over cleart‐
120              ext TCP unless  "tls" keyword is used (see below).
121
122              TLS  can   be  enabled  by  specifying   optional  "tls" parame‐
123              ter.  TLS is not enabled by default.
124
125              With "sni=<SNI_HOST>" parameter, it can  override  the  TLS  SNI
126              field   value   with  given  <SNI_HOST>.   This  will default to
127              the backend <HOST> name
128
129              The  feature  to detect  whether  backend  is online  or offline
130              can  be  enabled   using  optional "fall" and "rise" parameters.
131              Using  "fall=<N>"  parameter,  if  nghttpx cannot connect  to  a
132              this  backend  <N>   times in  a row, this  backend  is  assumed
133              to be  offline,  and  it  is excluded from load  balancing.   If
134              <N>  is 0, this backend never  be excluded  from load  balancing
135              whatever  times nghttpx cannot connect  to it, and this  is  the
136              default.   There  is  also "rise=<N>" parameter.  After  backend
137              was excluded from load  balancing  group,  nghttpx  periodically
138              attempts  to make a connection to the failed backend, and if the
139              connection is made  successfully <N> times  in a row, the  back‐
140              end  is  assumed to  be online, and it is now eligible  for load
141              balancing target.   If <N>  is 0,   a  backend   is  permanently
142              offline,  once   it goes  in that state, and this is the default
143              behaviour.
144
145              The     session     affinity    is     enabled     using "affin‐
146              ity=<METHOD>"   parameter.    If   "ip"  is  given  in <METHOD>,
147              client  IP based session affinity  is enabled.  If "cookie"   is
148              given  in  <METHOD>,  cookie based session affinity is  enabled.
149              If  "none" is given  in <METHOD>, session affinity  is disabled,
150              and this  is the default.  The session  affinity is  enabled per
151              <PATTERN>.   If at least  one backend  has  "affinity"   parame‐
152              ter,  and   its  <METHOD>  is  not  "none",  session affinity is
153              enabled for all backend  servers sharing  the  same   <PATTERN>.
154              It  is  advised  to  set  "affinity" parameter  to  all  backend
155              explicitly if session affinity  is desired.  The session  affin‐
156              ity  may   break  if   one  of  the   backend  gets unreachable,
157              or   backend  settings  are   reloaded  or replaced by API.
158
159              If   "affinity=cookie"    is   used,    the   additional config‐
160              uration                  is                  required.   "affin‐
161              ity-cookie-name=<NAME>" must be  used to specify a  name      of
162              cookie          to         use.          Optionally,     "affin‐
163              ity-cookie-path=<PATH>" can  be used to  specify a path    which
164              cookie       is      applied.       The      optional    "affin‐
165              ity-cookie-secure=<SECURE>"  controls  the  Secure attribute  of
166              a cookie.  The default value is "auto", and the Secure attribute
167              is  determined by a request scheme.   If  a  request  scheme  is
168              "https",  then  Secure  attribute is set.  Otherwise, it  is not
169              set.  If  <SECURE> is "yes", the  Secure attribute   is   always
170              set.    If  <SECURE>   is  "no",  the Secure attribute is always
171              omitted.
172
173              By default, name resolution of backend  host  name  is  done  at
174              start   up,   or reloading  configuration.   If  "dns" parameter
175              is  given,   name  resolution   takes  place dynamically.   This
176              is  useful   if  backend address changes frequently.   If  "dns"
177              is given,  name   resolution   of  backend    host    name    at
178              start   up,   or   reloading configuration is skipped.
179
180              If "redirect-if-not-tls" parameter  is used, the matched backend
181              requires   that  frontend  connection   is  TLS  encrypted.   If
182              it isn't, nghttpx responds to the request with 308  status code,
183              and  https URI the  client should use instead   is  included  in
184              Location  header field.  The port number in  redirect URI is 443
185              by  default, and can be   changed  using   --redirect-https-port
186              option.    If  at  least one  backend has  "redirect-if-not-tls"
187              parameter, this feature is  enabled   for  all  backend  servers
188              sharing the   same   <PATTERN>.    It    is   advised   to   set
189              "redirect-if-no-tls"    parameter   to    all   backends explic‐
190              itly if this feature is desired.
191
192              If "upgrade-scheme"  parameter is used along  with "tls" parame‐
193              ter, HTTP/2 :scheme pseudo header field is  changed  to  "https"
194              from  "http"  when forwarding a request to this particular back‐
195              end.   This  is   a  workaround  for  a  backend  server   which
196              requires  "https" :scheme  pseudo  header field on TLS encrypted
197              connection.
198
199              "mruby=<PATH>"  parameter  specifies  a  path  to  mruby  script
200              file   which   is  invoked when  this  pattern  is matched.  All
201              backends which share the same pattern must have the  same  mruby
202              path.
203
204              "read-timeout=<DURATION>" and "write-timeout=<DURATION>" parame‐
205              ters  specify the  read and  write timeout  of the backend  con‐
206              nection   when  this   pattern  is  matched.  All backends which
207              share the same pattern must have the same  timeouts.   If  these
208              timeouts      are    entirely    omitted    for    a    pattern,
209              --backend-read-timeout           and --backend-write-timeout are
210              used.
211
212              "group=<GROUP>"   parameter  specifies   the name  of group this
213              backend address belongs to.  By  default,  it  belongs  to   the
214              unnamed   default  group.    The name  of group  is unique   per
215              pattern.   "group-weight=<N>"   parameter specifies the   weight
216              of   the  group.   The   higher  weight  gets   more  frequently
217              selected  by  the load  balancing algorithm.  <N> must  be   [1,
218              256]  inclusive.   The weight 8 has 4 times more weight  than 2.
219              <N> must be the same for  all addresses  which  share the   same
220              <GROUP>.   If "group-weight" is  omitted in an address,  but the
221              other address  which  belongs  to  the  same   group   specifies
222              "group-weight",     its      weight    is    used.      If    no
223              "group-weight"  is  specified  for  all  addresses,  the  weight
224              of a group becomes 1.  "group" and "group-weight" are ignored if
225              session affinity is enabled.
226
227              "weight=<N>"  parameter  specifies  the  weight  of  the backend
228              address   inside   a   group   which  this  address belongs  to.
229              The  higher  weight  gets more  frequently selected by  the load
230              balancing  algorithm.    <N>  must be [1,  256] inclusive.   The
231              weight 8  has  4 times  more weight  than weight  2.   If   this
232              parameter   is  omitted,  weight   becomes   1.    "weight"   is
233              ignored  if  session affinity is enabled.
234
235              Since ";" and ":" are  used as  delimiter,  <PATTERN>  must  not
236              contain  these   characters.  Since  ";" has  special meaning in
237              shell, the option value must be quoted.
238
239              Default: 127.0.0.1,80
240
241       -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]
242              Set  frontend  host and  port.   If  <HOST> is  '*',  it assumes
243              all  addresses   including   both   IPv4 and  IPv6.  UNIX domain
244              socket can  be specified by  prefixing path name  with   "unix:"
245              (e.g.,   unix:/var/run/nghttpx.sock).  This  option can  be used
246              multiple times  to listen  to multiple addresses.
247
248              This option   can  take   0  or   more  parameters,   which  are
249              described  below.   Note   that  "api"  and  "healthmon" parame‐
250              ters are mutually exclusive.
251
252              Optionally, TLS  can be disabled by  specifying "no-tls" parame‐
253              ter.  TLS is enabled by default.
254
255              If  "sni-fwd"  parameter  is   used,  when performing a match to
256              select a backend server,  SNI host name received from the client
257              is  used   instead  of  the request  host.  See --backend option
258              about the pattern match.
259
260              To  make this  frontend as  API endpoint,  specify "api" parame‐
261              ter.   This   is  disabled  by  default.    It  is important  to
262              limit the  access  to  the API   frontend.   Otherwise,  someone
263              may  change   the  backend  server, and break your services,  or
264              expose confidential information to the outside the world.
265
266              To  make  this  frontend  as  health  monitor  endpoint, specify
267              "healthmon"   parameter.    This  is  disabled  by default.  Any
268              requests which come through  this address are replied  with  200
269              HTTP status, without no body.
270
271              To  accept   PROXY  protocol   version  1   on  frontend connec‐
272              tion,  specify  "proxyproto" parameter.   This  is  disabled  by
273              default.
274
275              Default: *,3000
276
277       --backlog=<N>
278              Set listen backlog size.
279
280              Default: 65536
281
282       --backend-address-family=(auto|IPv4|IPv6)
283              Specify   address  family  of  backend  connections.   If "auto"
284              is given, both IPv4  and IPv6  are  considered.   If  "IPv4"  is
285              given,  only   IPv4 address is  considered.  If "IPv6" is given,
286              only IPv6 address is considered.
287
288              Default: auto
289
290       --backend-http-proxy-uri=<URI>
291              Specify       proxy        URI        in         the        form
292              http://[<USER>:<PASS>@]<PROXY>:<PORT>.       If      a     proxy
293              requires  authentication,  specify  <USER>  and   <PASS>.   Note
294              that   they  must  be properly  percent-encoded.  This proxy  is
295              used  when the  backend connection  is HTTP/2.  First,  make   a
296              CONNECT  request  to  the proxy  and  it connects  to the  back‐
297              end  on behalf  of nghttpx.   This forms  tunnel.   After  that,
298              nghttpx    performs   SSL/TLS  handshake  with   the  downstream
299              through the  tunnel.  The timeouts when connecting  and   making
300              CONNECT      request      can     be         specified        by
301              --backend-read-timeout    and --backend-write-timeout options.
302
303   Performance
304       -n, --workers=<N>
305              Set the number of worker threads.
306
307              Default: 1
308
309       --single-thread
310              Run everything in one  thread inside the worker  process.   This
311              feature    is    provided   for   better   debugging experience,
312              or  for   the  platforms   which   lack   thread  support.    If
313              threading  is disabled,  this  option  is always enabled.
314
315       --read-rate=<SIZE>
316              Set  maximum   average read  rate on  frontend connection.  Set‐
317              ting 0 to this option means read rate is unlimited.
318
319              Default: 0
320
321       --read-burst=<SIZE>
322              Set  maximum read  burst  size  on frontend   connection.   Set‐
323              ting  0  to this  option  means  read burst  size  is unlimited.
324
325              Default: 0
326
327       --write-rate=<SIZE>
328              Set  maximum   average write rate on  frontend connection.  Set‐
329              ting 0 to this option means write rate is unlimited.
330
331              Default: 0
332
333       --write-burst=<SIZE>
334              Set  maximum write  burst size  on frontend   connection.   Set‐
335              ting  0 to  this  option means  write  burst size  is unlimited.
336
337              Default: 0
338
339       --worker-read-rate=<SIZE>
340              Set maximum average read rate on frontend connection per worker.
341              Setting  0 to  this option  means read  rate is unlimited.   Not
342              implemented yet.
343
344              Default: 0
345
346       --worker-read-burst=<SIZE>
347              Set maximum  read burst size on  frontend connection per worker.
348              Setting 0 to this  option means read burst  size  is  unlimited.
349              Not implemented yet.
350
351              Default: 0
352
353       --worker-write-rate=<SIZE>
354              Set  maximum   average  write   rate on  frontend connection per
355              worker.  Setting  0 to this option  means write rate  is  unlim‐
356              ited.  Not implemented yet.
357
358              Default: 0
359
360       --worker-write-burst=<SIZE>
361              Set maximum write burst  size on frontend connection per worker.
362              Setting 0 to this option means write burst  size  is  unlimited.
363              Not implemented yet.
364
365              Default: 0
366
367       --worker-frontend-connections=<N>
368              Set   maximum   number   of  simultaneous  connections  frontend
369              accepts.  Setting 0 means unlimited.
370
371              Default: 0
372
373       --backend-connections-per-host=<N>
374              Set  maximum number  of  backend concurrent  connections (and/or
375              streams in  case  of HTTP/2)  per origin  host.  This option  is
376              meaningful when --http2-proxy  option  is  used.    The   origin
377              host   is  determined  by  authority portion of  request URI (or
378              :authority  header field for HTTP/2).   To  limit  the    number
379              of    connections    per   frontend          for         default
380              mode,       use --backend-connections-per-frontend.
381
382              Default: 8
383
384       --backend-connections-per-frontend=<N>
385              Set  maximum number  of  backend concurrent  connections (and/or
386              streams   in  case  of  HTTP/2)   per frontend.  This option  is
387              only  used  for  default   mode.   0  means unlimited.  To limit
388              the   number of connections per host with          --http2-proxy
389              option,          use --backend-connections-per-host.
390
391              Default: 0
392
393       --rlimit-nofile=<N>
394              Set maximum number of open files (RLIMIT_NOFILE) to <N>.   If  0
395              is given, nghttpx does not set the limit.
396
397              Default: 0
398
399       --backend-request-buffer=<SIZE>
400              Set buffer size used to store backend request.
401
402              Default: 16K
403
404       --backend-response-buffer=<SIZE>
405              Set buffer size used to store backend response.
406
407              Default: 128K
408
409       --fastopen=<N>
410              Enables   "TCP Fast  Open" for  the listening  socket and limits
411              the  maximum length for the  queue of connections that have  not
412              yet  completed the three-way handshake.  If value is 0 then fast
413              open is disabled.
414
415              Default: 0
416
417       --no-kqueue
418              Don't use  kqueue.  This  option is  only   applicable  for  the
419              platforms  which have kqueue.  For  other platforms, this option
420              will be simply ignored.
421
422   Timeout
423       --frontend-http2-read-timeout=<DURATION>
424              Specify read timeout for HTTP/2 frontend connection.
425
426              Default: 3m
427
428       --frontend-read-timeout=<DURATION>
429              Specify read timeout for HTTP/1.1 frontend connection.
430
431              Default: 1m
432
433       --frontend-write-timeout=<DURATION>
434              Specify write timeout for all frontend connections.
435
436              Default: 30s
437
438       --frontend-keep-alive-timeout=<DURATION>
439              Specify   keep-alive   timeout   for   frontend   HTTP/1 connec‐
440              tion.
441
442              Default: 1m
443
444       --stream-read-timeout=<DURATION>
445              Specify   read  timeout  for HTTP/2  streams.  0  means no time‐
446              out.
447
448              Default: 0
449
450       --stream-write-timeout=<DURATION>
451              Specify write  timeout for  HTTP/2 streams.  0  means  no  time‐
452              out.
453
454              Default: 1m
455
456       --backend-read-timeout=<DURATION>
457              Specify read timeout for backend connection.
458
459              Default: 1m
460
461       --backend-write-timeout=<DURATION>
462              Specify write timeout for backend connection.
463
464              Default: 30s
465
466       --backend-connect-timeout=<DURATION>
467              Specify   timeout  before  establishing TCP  connection to back‐
468              end.
469
470              Default: 30s
471
472       --backend-keep-alive-timeout=<DURATION>
473              Specify   keep-alive   timeout    for   backend   HTTP/1 connec‐
474              tion.
475
476              Default: 2s
477
478       --listener-disable-timeout=<DURATION>
479              After accepting  connection failed,  connection listener is dis‐
480              abled  for a given  amount of time.   Specifying 0 disables this
481              feature.
482
483              Default: 30s
484
485       --frontend-http2-setting-timeout=<DURATION>
486              Specify  timeout before  SETTINGS ACK  is received  from client.
487
488              Default: 10s
489
490       --backend-http2-settings-timeout=<DURATION>
491              Specify  timeout before  SETTINGS ACK  is received  from backend
492              server.
493
494              Default: 10s
495
496       --backend-max-backoff=<DURATION>
497              Specify  maximum backoff  interval.  This  is used   when  doing
498              health  check against offline backend  (see "fail" parameter  in
499              --backend  option).   It is  also used  to limit   the   maximum
500              interval  to  temporarily  disable backend  when nghttpx  failed
501              to  connect to  it.  These intervals are calculated  using expo‐
502              nential  backoff,  and  consecutive failed attempts increase the
503              interval.  This option caps its maximum value.
504
505              Default: 2m
506
507   SSL/TLS
508       --ciphers=<SUITE>
509              Set allowed  cipher list  for frontend  connection.  The  format
510              of  the  string is described in OpenSSL ciphers(1).  This option
511              sets cipher suites for  TLSv1.2 or earlier.  Use --tls13-ciphers
512              for TLSv1.3.
513
514              Default:
515              ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256
516
517       --tls13-ciphers=<SUITE>
518              Set  allowed  cipher list  for frontend  connection.  The format
519              of the string is described in OpenSSL ciphers(1).  This   option
520              sets  cipher   suites  for  TLSv1.3.   Use --ciphers for TLSv1.2
521              or earlier.
522
523              Default:
524              TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
525
526       --client-ciphers=<SUITE>
527              Set  allowed cipher  list for  backend connection.   The  format
528              of  the  string is described in OpenSSL ciphers(1).  This option
529              sets   cipher   suites   for    TLSv1.2   or    earlier.     Use
530              --tls13-client-ciphers for TLSv1.3.
531
532              Default:
533              ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256
534
535       --tls13-client-ciphers=<SUITE>
536              Set   allowed cipher  list for  backend connection.   The format
537              of the string is described in OpenSSL ciphers(1).  This   option
538              sets       cipher        suites      for      TLSv1.3.       Use
539              --tls13-client-ciphers for TLSv1.2 or earlier.
540
541              Default:
542              TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
543
544       --ecdh-curves=<LIST>
545              Set  supported  curve  list  for  frontend  connections.  <LIST>
546              is a  colon separated list of curve  NID or names in the prefer‐
547              ence order.  The supported curves depend on the  linked  OpenSSL
548              library.  This  function  requires OpenSSL >= 1.0.2.
549
550              Default: X25519:P-256:P-384:P-521
551
552       -k, --insecure
553              Don't  verify backend  server's  certificate  if TLS  is enabled
554              for backend connections.
555
556       --cacert=<PATH>
557              Set path to trusted CA  certificate file.  It is used in backend
558              TLS connections  to verify  peer's certificate.  It is also used
559              to    verify   OCSP   response   from   the   script   set    by
560              --fetch-ocsp-response-file.   The   file  must be in PEM format.
561              It can contain multiple  certificates.  If the   linked  OpenSSL
562              is  configured   to  load   system  wide certificates, they  are
563              loaded at startup  regardless of this option.
564
565       --private-key-passwd-file=<PATH>
566              Path  to file  that contains  password for  the server's private
567              key.    If  none is  given and the private  key is password pro‐
568              tected it'll be requested interactively.
569
570       --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
571              Specify   additional  certificate   and   private   key    file.
572              nghttpx  will   choose certificates based on  the hostname indi‐
573              cated by client using TLS SNI extension.  If nghttpx  is   built
574              with   OpenSSL   >=  1.0.2,   the shared  elliptic curves (e.g.,
575              P-256) between  client and server are also taken into  consider‐
576              ation.   This allows nghttpx  to send ECDSA certificate  to mod‐
577              ern clients, while   sending  RSA  based  certificate  to  older
578              clients.   This  option can be used  multiple  times.   To  make
579              OCSP  stapling  work, <CERTPATH> must be absolute path.
580
581              Additional parameter  can be specified in  <PARAM>.  The  avail‐
582              able <PARAM> is "sct-dir=<DIR>".
583
584              "sct-dir=<DIR>"   specifies  the   path to  directory which con‐
585              tains          *.sct           files           for           TLS
586              signed_certificate_timestamp extension (RFC 6962).  This feature
587              requires   OpenSSL   >=    1.0.2.     See    also  --tls-sct-dir
588              option.
589
590       --dh-param-file=<PATH>
591              Path  to file that contains  DH parameters in PEM format.  With‐
592              out  this   option,  DHE   cipher  suites   are  not available.
593
594       --npn-list=<LIST>
595              Comma delimited list of  ALPN protocol identifier sorted in  the
596              order  of preference.  That  means most desirable protocol comes
597              first.  This  is used  in both  ALPN  and  NPN.   The  parameter
598              must be  delimited by a single comma only  and any  white spaces
599              are  treated as  a part  of protocol string.
600
601              Default: h2,h2-16,h2-14,http/1.1
602
603       --verify-client
604              Require and verify client certificate.
605
606       --verify-client-cacert=<PATH>
607              Path  to file  that contains  CA certificates  to verify  client
608              certificate.   The  file  must be in PEM format.  It can contain
609              multiple certificates.
610
611       --verify-client-tolerate-expired
612              Accept  expired  client  certificate.   Operator  should  handle
613              the  expired   client  certificate  by some  means (e.g.,  mruby
614              script).   Otherwise, this  option  might cause a security risk.
615
616       --client-private-key-file=<PATH>
617              Path to  file that contains  client private key  used in backend
618              client authentication.
619
620       --client-cert-file=<PATH>
621              Path to  file that  contains client certificate  used in backend
622              client authentication.
623
624       --tls-min-proto-version=<VER>
625              Specify minimum SSL/TLS protocol.   The name matching is done in
626              case-insensitive      manner.      The      versions     between
627              --tls-min-proto-version   and     --tls-max-proto-version    are
628              enabled.   If  the  protocol  list advertised by client does not
629              overlap  this range,  you   will   receive  the   error  message
630              "unknown protocol".  If a protocol version lower than TLSv1.2 is
631              specified, make sure that the compatible ciphers  are   included
632              in --ciphers option.   The default cipher  list  only   includes
633              ciphers  compatible  with TLSv1.2 or above.  The available  ver‐
634              sions are: TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
635
636              Default: TLSv1.2
637
638       --tls-max-proto-version=<VER>
639              Specify maximum SSL/TLS protocol.   The name matching is done in
640              case-insensitive     manner.      The      versions      between
641              --tls-min-proto-version    and     --tls-max-proto-version   are
642              enabled.  If the protocol list advertised  by  client  does  not
643              overlap   this  range,   you   will   receive the  error message
644              "unknown  protocol".   The  available  versions  are:   TLSv1.3,
645              TLSv1.2, TLSv1.1, and TLSv1.0
646
647              Default: TLSv1.3
648
649       --tls-ticket-key-file=<PATH>
650              Path to file that contains  random data to construct TLS session
651              ticket    parameters.    If    aes-128-cbc    is     given    in
652              --tls-ticket-key-cipher,  the   file  must   contain  exactly 48
653              bytes.       If        aes-256-cbc       is       given       in
654              --tls-ticket-key-cipher,  the   file  must   contain  exactly 80
655              bytes.   This  options  can be   used   repeatedly   to  specify
656              multiple ticket  parameters.  If  several files are given,  only
657              the  first key is  used to  encrypt TLS session  tickets.  Other
658              keys  are  accepted but  server will  issue new  session  ticket
659              with  first key.   This allows  session  key  rotation.   Please
660              note  that  key rotation  does  not  occur automatically.   User
661              should rearrange  files or  change options  values and   restart
662              nghttpx  gracefully.   If opening  or reading  given file fails,
663              all loaded  keys are discarded and  it is treated as if none  of
664              this  option is given.  If  this option is not given or an error
665              occurred while opening or reading a  file,   key  is   generated
666              every   1  hour   internally  and they are  valid for  12 hours.
667              This is  recommended if ticket  key  sharing   between   nghttpx
668              instances is  not required.
669
670       --tls-ticket-key-memcached=<HOST>,<PORT>[;tls]
671              Specify  address   of  memcached  server to get  TLS ticket keys
672              for  session resumption.   This enables  shared TLS  ticket  key
673              between   multiple  nghttpx instances.  nghttpx does not set TLS
674              ticket  key to memcached.  The external ticket key generator  is
675              required.   nghttpx just gets TLS ticket  keys  from  memcached,
676              and  use  them,  possibly replacing current set  of keys.  It is
677              up   to  extern  TLS ticket  key generator  to rotate  keys fre‐
678              quently.   See "TLS SESSION  TICKET RESUMPTION" section in  man‐
679              ual  page  to  know the data format in memcached entry.  Option‐
680              ally, memcached  connection  can  be  encrypted  with   TLS   by
681              specifying "tls" parameter.
682
683       --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6)
684              Specify  address   family  of  memcached connections  to get TLS
685              ticket keys.  If "auto" is given, both IPv4 and IPv6 are consid‐
686              ered.    If  "IPv4"  is given,  only IPv4 address is considered.
687              If "IPv6" is given, only IPv6 address is considered.
688
689              Default: auto
690
691       --tls-ticket-key-memcached-interval=<DURATION>
692              Set interval to get TLS ticket keys from memcached.
693
694              Default: 10m
695
696       --tls-ticket-key-memcached-max-retry=<N>
697              Set  maximum   number  of  consecutive   retries   before  aban‐
698              doning  TLS  ticket  key  retrieval.  If this number is reached,
699              the  attempt  is considered  as  failure,  and  "failure"  count
700              is  incremented  by  1,   which  contributed  to             the
701              value            controlled  --tls-ticket-key-memcached-max-fail
702              option.
703
704              Default: 3
705
706       --tls-ticket-key-memcached-max-fail=<N>
707              Set   maximum    number   of  consecutive   failure  before dis‐
708              abling TLS ticket until next scheduled key retrieval.
709
710              Default: 2
711
712       --tls-ticket-key-cipher=<CIPHER>
713              Specify cipher  to encrypt TLS session  ticket.  Specify  either
714              aes-128-cbc    or   aes-256-cbc.    By   default, aes-128-cbc is
715              used.
716
717       --tls-ticket-key-memcached-cert-file=<PATH>
718              Path to client certificate  for memcached connections to get TLS
719              ticket keys.
720
721       --tls-ticket-key-memcached-private-key-file=<PATH>
722              Path to client private  key for memcached connections to get TLS
723              ticket keys.
724
725       --fetch-ocsp-response-file=<PATH>
726              Path to  fetch-ocsp-response script file.  It  should  be  abso‐
727              lute path.
728
729              Default: /usr/local/share/nghttp2/fetch-ocsp-response
730
731       --ocsp-update-interval=<DURATION>
732              Set interval to update OCSP response cache.
733
734              Default: 4h
735
736       --ocsp-startup
737              Start   accepting  connections   after  initial  attempts to get
738              OCSP responses   finish.   It  does  not   matter  some  of  the
739              attempts   fail.   This   feature  is  useful if  OCSP responses
740              must    be   available    before   accepting connections.
741
742       --no-verify-ocsp
743              nghttpx does not verify OCSP response.
744
745       --no-ocsp
746              Disable OCSP stapling.
747
748       --tls-session-cache-memcached=<HOST>,<PORT>[;tls]
749              Specify  address of  memcached server  to store  session  cache.
750              This    enables     shared   session   cache   between  multiple
751              nghttpx  instances.    Optionally,  memcached connection can  be
752              encrypted with TLS by specifying "tls" parameter.
753
754       --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6)
755              Specify address family of memcached connections to store session
756              cache.  If  "auto" is given, both  IPv4 and IPv6 are considered.
757              If "IPv4" is given,  only IPv4 address is considered.  If "IPv6"
758              is given, only IPv6 address is considered.
759
760              Default: auto
761
762       --tls-session-cache-memcached-cert-file=<PATH>
763              Path to client certificate  for memcached connections  to  store
764              session cache.
765
766       --tls-session-cache-memcached-private-key-file=<PATH>
767              Path  to  client private  key for memcached connections to store
768              session cache.
769
770       --tls-dyn-rec-warmup-threshold=<SIZE>
771              Specify the  threshold size for TLS  dynamic record size  behav‐
772              iour.   During   a  TLS  session, after  the threshold number of
773              bytes  have been written, the  TLS record size will be increased
774              to  the  maximum  allowed (16K).  The max record size will  con‐
775              tinue  to  be  used  on   the   active   TLS   session.    After
776              --tls-dyn-rec-idle-timeout  has  elapsed,  the  record  size  is
777              reduced  to 1300 bytes.  Specify 0 to always  use   the  maximum
778              record  size,   regardless  of  idle  period.    This  behaviour
779              applies   to  all  TLS  based frontends, and  TLS  HTTP/2  back‐
780              ends.
781
782              Default: 1M
783
784       --tls-dyn-rec-idle-timeout=<DURATION>
785              Specify   TLS  dynamic  record   size  behaviour  timeout.   See
786              --tls-dyn-rec-warmup-threshold  for   more   information.   This
787              behaviour   applies  to all TLS  based frontends, and TLS HTTP/2
788              backends.
789
790              Default: 1s
791
792       --no-http2-cipher-black-list
793              Allow  black  listed  cipher suite  on  frontend  HTTP/2 connec‐
794              tion.                                                        See
795              https://tools.ietf.org/html/rfc7540#appendix-A   for   the  com‐
796              plete HTTP/2 cipher suites black list.
797
798       --client-no-http2-cipher-black-list
799              Allow  black  listed  cipher  suite  on  backend  HTTP/2 connec‐
800              tion.                                                        See
801              https://tools.ietf.org/html/rfc7540#appendix-A   for   the  com‐
802              plete HTTP/2 cipher suites black list.
803
804       --tls-sct-dir=<DIR>
805              Specifies the  directory where  *.sct files  exist.   All  *.sct
806              files    in  <DIR>   are   read,   and  sent   as extension_data
807              of  TLS signed_certificate_timestamp  (RFC  6962)   to   client.
808              These   *.sct  files  are  for  the certificate   specified   in
809              positional    command-line  argument  <CERT>,  or    certificate
810              option  in configuration file.   For   additional  certificates,
811              use  --subcert option.  This option requires OpenSSL >= 1.0.2.
812
813       --psk-secrets=<PATH>
814              Read list of PSK identity and secrets from <PATH>.  This is used
815              for  frontend connection.  The each line of input file  is  for‐
816              matted  as  <identity>:<hex-secret>,  where <identity>  is   PSK
817              identity,  and  <hex-secret>  is secret in hex.  An  empty line,
818              and line which   starts  with  '#'  are  skipped.   The  default
819              enabled  cipher list might not contain any PSK cipher suite.  In
820              that case, desired PSK cipher suites   must  be   enabled  using
821              --ciphers option.  The  desired PSK  cipher suite  may be  black
822              listed  by HTTP/2.    To   use   those    cipher   suites   with
823              HTTP/2, consider  to  use  --no-http2-cipher-black-list  option.
824              But be aware its implications.
825
826       --client-psk-secrets=<PATH>
827              Read PSK identity and secrets from <PATH>.   This  is  used  for
828              backend  connection.   The each  line of input file is formatted
829              as <identity>:<hex-secret>,  where <identity> is  PSK  identity,
830              and  <hex-secret>   is  secret  in hex.  An empty line, and line
831              which  starts with '#' are  skipped.   The  first  identity  and
832              secret  pair  encountered  is used.  The default  enabled cipher
833              list might not  contain any PSK  cipher suite.   In  that  case,
834              desired   PSK    cipher   suites    must   be    enabled   using
835              --client-ciphers option.  The  desired PSK  cipher suite  may be
836              black listed  by HTTP/2.   To  use  those   cipher  suites  with
837              HTTP/2, consider   to  use   --client-no-http2-cipher-black-list
838              option.  But be aware its implications.
839
840       --tls-no-postpone-early-data
841              By default,  nghttpx postpones forwarding  HTTP requests sent in
842              early data, including those sent in partially in it,  until  TLS
843              handshake   finishes.    If   all   backend   server  recognizes
844              "Early-Data" header  field, using this option makes nghttpx  not
845              postpone   forwarding  request   and get full potential of 0-RTT
846              data.
847
848       --tls-max-early-data=<SIZE>
849              Sets   the   maximum   amount   of  0-RTT   data   that   server
850              accepts.
851
852              Default: 16K
853
854   HTTP/2
855       -c, --frontend-http2-max-concurrent-streams=<N>
856              Set  the  maximum number of  the concurrent streams in one fron‐
857              tend HTTP/2 session.
858
859              Default: 100
860
861       --backend-http2-max-concurrent-streams=<N>
862              Set the maximum number of  the concurrent streams in one backend
863              HTTP/2  session.    This  sets   maximum  number   of concurrent
864              opened  pushed  streams.   The  maximum  number  of   concurrent
865              requests are set by a remote server.
866
867              Default: 100
868
869       --frontend-http2-window-size=<SIZE>
870              Sets   the   per-stream  initial  window  size  of  HTTP/2 fron‐
871              tend connection.
872
873              Default: 65535
874
875       --frontend-http2-connection-window-size=<SIZE>
876              Sets the  per-connection window size of  HTTP/2 frontend connec‐
877              tion.
878
879              Default: 65535
880
881       --backend-http2-window-size=<SIZE>
882              Sets  the   initial  window   size  of   HTTP/2  backend connec‐
883              tion.
884
885              Default: 65535
886
887       --backend-http2-connection-window-size=<SIZE>
888              Sets the  per-connection window  size of  HTTP/2 backend connec‐
889              tion.
890
891              Default: 2147483647
892
893       --http2-no-cookie-crumbling
894              Don't crumble cookie header field.
895
896       --padding=<N>
897              Add   at  most   <N> bytes  to  a HTTP/2  frame payload  as pad‐
898              ding.  Specify 0 to  disable padding.  This option is meant  for
899              debugging  purpose   and  not intended to enhance protocol secu‐
900              rity.
901
902       --no-server-push
903              Disable HTTP/2 server push.  Server push is supported by default
904              mode  and  HTTP/2   frontend via Link header field.  It is  also
905              supported if  both frontend and  backend are HTTP/2  in  default
906              mode.   In   this  case,  server  push  from  backend session is
907              relayed  to frontend, and server push via Link header  field  is
908              also supported.
909
910       --frontend-http2-optimize-write-buffer-size
911              (Experimental)  Enable  write  buffer size optimization in fron‐
912              tend HTTP/2 TLS  connection.  This optimization aims  to  reduce
913              write  buffer   size so  that it  only contains bytes  which can
914              send immediately.   This makes  server more responsive to prior‐
915              itized  HTTP/2  stream because the buffering  of lower  priority
916              stream  is reduced.   This option is only  effective  on  recent
917              Linux platform.
918
919       --frontend-http2-optimize-window-size
920              (Experimental)    Automatically  tune   connection  level window
921              size of frontend  HTTP/2 TLS connection.   If  this  feature  is
922              enabled, connection window size  starts with the   default  win‐
923              dow   size,   65535  bytes.     nghttpx  automatically   adjusts
924              connection   window  size   based on TCP receiving  window size.
925              The maximum  window size is capped       by       the      value
926              specified         by    --frontend-http2-connection-window-size.
927              Since   the stream is subject to stream level  window  size,  it
928              should  be adjusted using --frontend-http2-window-size option as
929              well.   This option  is only  effective on  recent  Linux  plat‐
930              form.
931
932       --frontend-http2-encoder-dynamic-table-size=<SIZE>
933              Specify  the maximum dynamic  table size of HPACK encoder in the
934              frontend HTTP/2 connection.  The decoder (client) specifies  the
935              maximum   dynamic  table  size it  accepts.  Then the negotiated
936              dynamic table size is the minimum of this option value  and  the
937              value which client specified.
938
939              Default: 4K
940
941       --frontend-http2-decoder-dynamic-table-size=<SIZE>
942              Specify  the maximum dynamic  table size of HPACK decoder in the
943              frontend HTTP/2 connection.
944
945              Default: 4K
946
947       --backend-http2-encoder-dynamic-table-size=<SIZE>
948              Specify the maximum dynamic  table size of HPACK encoder in  the
949              backend HTTP/2 connection.  The decoder (backend) specifies  the
950              maximum  dynamic table  size it  accepts.  Then  the  negotiated
951              dynamic  table  size is the minimum of this option value and the
952              value which backend specified.
953
954              Default: 4K
955
956       --backend-http2-decoder-dynamic-table-size=<SIZE>
957              Specify the maximum dynamic  table size of HPACK decoder in  the
958              backend HTTP/2 connection.
959
960              Default: 4K
961
962   Mode
963       (default mode)
964              Accept  HTTP/2,  and  HTTP/1.1 over  SSL/TLS.   "no-tls" parame‐
965              ter is  used in  --frontend option,  accept HTTP/2 and  HTTP/1.1
966              over  cleartext  TCP.  The incoming HTTP/1.1 connection  can  be
967              upgraded  to  HTTP/2  through  HTTP Upgrade.
968
969       -s, --http2-proxy
970              Like default mode, but enable forward proxy.  This is so  called
971              HTTP/2 proxy mode.
972
973   Logging
974       -L, --log-level=<LEVEL>
975              Set  the severity  level of log output.   <LEVEL> must be one of
976              INFO, NOTICE, WARN, ERROR and FATAL.
977
978              Default: NOTICE
979
980       --accesslog-file=<PATH>
981              Set path to write access log.  To reopen file, send USR1  signal
982              to nghttpx.
983
984       --accesslog-syslog
985              Send   access  log   to  syslog.    If  this   option  is  used,
986              --accesslog-file option is ignored.
987
988       --accesslog-format=<FORMAT>
989              Specify  format  string  for access  log.   The  default  format
990              is combined format.   The following variables are available:
991
992              · $remote_addr: client IP address.
993
994              · $time_local: local time in Common Log format.
995
996              · $time_iso8601: local time in ISO 8601 format.
997
998              · $request: HTTP request line.
999
1000              · $status: HTTP response status code.
1001
1002              · $body_bytes_sent:  the   number  of  bytes  sent  to client as
1003                response body.
1004
1005              · $http_<VAR>: value of HTTP  request header <VAR> where '_'  in
1006                <VAR> is replaced with '-'.
1007
1008              · $remote_port: client  port.
1009
1010              · $server_port: server port.
1011
1012              · $request_time:  request  processing  time in seconds with mil‐
1013                liseconds resolution.
1014
1015              · $pid: PID of the running process.
1016
1017              · $alpn: ALPN identifier of the  protocol  which  generates  the
1018                response.    For HTTP/1,  ALPN is  always http/1.1, regardless
1019                of minor version.
1020
1021              · $tls_cipher: cipher used for SSL/TLS connection.
1022
1023              · $tls_client_fingerprint_sha256: SHA-256 fingerprint of  client
1024                certificate.
1025
1026              · $tls_client_fingerprint_sha1:   SHA-1   fingerprint  of client
1027                certificate.
1028
1029              · $tls_client_subject_name:   subject  name    in   client  cer‐
1030                tificate.
1031
1032              · $tls_client_issuer_name:    issuer    name    in   client cer‐
1033                tificate.
1034
1035              · $tls_client_serial:    serial    number    in     client  cer‐
1036                tificate.
1037
1038              · $tls_protocol: protocol for SSL/TLS connection.
1039
1040              · $tls_session_id: session ID for SSL/TLS connection.
1041
1042              · $tls_session_reused:  "r"   if  SSL/TLS   session  was reused.
1043                Otherwise, "."
1044
1045              · $tls_sni: SNI server name for SSL/TLS connection.
1046
1047              · $backend_host:   backend   host    used   to    fulfill    the
1048                request.  "-" if backend host is not available.
1049
1050              · $backend_port:    backend    port    used   to   fulfill   the
1051                request.  "-" if backend host is not available.
1052
1053              The  variable  can  be  enclosed  by  "{"  and  "}"  for  disam‐
1054              biguation (e.g., ${remote_addr}).
1055
1056              Default:  $remote_addr  -  -  [$time_local]  "$request"  $status
1057              $body_bytes_sent "$http_referer" "$http_user_agent"
1058
1059       --accesslog-write-early
1060              Write   access   log   when    response   header   fields    are
1061              received    from  backend   rather   than  when   request trans‐
1062              action finishes.
1063
1064       --errorlog-file=<PATH>
1065              Set path to write error  log.  To reopen file, send USR1  signal
1066              to  nghttpx.   stderr will  be redirected  to the error log file
1067              unless --errorlog-syslog is used.
1068
1069              Default: /dev/stderr
1070
1071       --errorlog-syslog
1072              Send  error  log   to   syslog.   If   this   option  is   used,
1073              --errorlog-file option is ignored.
1074
1075       --syslog-facility=<FACILITY>
1076              Set syslog facility to <FACILITY>.
1077
1078              Default: daemon
1079
1080   HTTP
1081       --add-x-forwarded-for
1082              Append    X-Forwarded-For   header   field  to   the  downstream
1083              request.
1084
1085       --strip-incoming-x-forwarded-for
1086              Strip  X-Forwarded-For   header  field  from    inbound   client
1087              requests.
1088
1089       --no-add-x-forwarded-proto
1090              Don't append  additional X-Forwarded-Proto  header field to  the
1091              backend   request.     If    inbound     client    sets   X-For‐
1092              warded-Proto,                                                and
1093              --no-strip-incoming-x-forwarded-proto  option   is   used,  they
1094              are passed to the backend.
1095
1096       --no-strip-incoming-x-forwarded-proto
1097              Don't  strip X-Forwarded-Proto  header field from inbound client
1098              requests.
1099
1100       --add-forwarded=<LIST>
1101              Append RFC  7239 Forwarded header field  with parameters  speci‐
1102              fied  in  comma delimited list <LIST>.  The supported parameters
1103              are "by",  "for", "host",  and "proto".   By default,  the value
1104              of   "by"  and   "for"  parameters   are  obfuscated     string.
1105              See     --forwarded-by    and  --forwarded-for  options  respec‐
1106              tively.   Note  that  nghttpx  does  not  translate non-standard
1107              X-Forwarded-*  header fields into Forwarded  header  field,  and
1108              vice versa.
1109
1110       --strip-incoming-forwarded
1111              Strip    Forwarded     header   field   from    inbound   client
1112              requests.
1113
1114       --forwarded-by=(obfuscated|ip|<VALUE>)
1115              Specify the parameter value sent out with "by" parameter of For‐
1116              warded  header field.   If "obfuscated"  is given, the string is
1117              randomly generated at startup.  If "ip" is given,   the   inter‐
1118              face    address  of   the  connection, including port number, is
1119              sent with "by" parameter.   In  case  of  UNIX  domain   socket,
1120              "localhost" is used instead of address and  port.  User can also
1121              specify the static obfuscated string.  The limitation is that it
1122              must  start  with    "_",  and   only   consists   of  character
1123              set [A-Za-z0-9._-], as described in RFC 7239.
1124
1125              Default: obfuscated
1126
1127       --forwarded-for=(obfuscated|ip)
1128              Specify  the   parameter  value  sent  out   with  "for" parame‐
1129              ter  of  Forwarded  header field.  If "obfuscated" is given, the
1130              string is  randomly generated for each  client  connection.   If
1131              "ip"  is  given,  the  remote client address of  the connection,
1132              without port  number, is  sent with "for"  parameter.   In  case
1133              of   UNIX   domain   socket,  "localhost"  is  used  instead  of
1134              address.
1135
1136              Default: obfuscated
1137
1138       --no-via
1139              Don't append to  Via header field.   If   Via  header  field  is
1140              received, it is left unaltered.
1141
1142       --no-strip-incoming-early-data
1143              Don't   strip  Early-Data  header   field  from  inbound  client
1144              requests.
1145
1146       --no-location-rewrite
1147              Don't  rewrite location  header field  in default   mode.   When
1148              --http2-proxy   is  used,  location  header   field  will not be
1149              altered regardless of this option.
1150
1151       --host-rewrite
1152              Rewrite  host and  :authority header  fields in   default  mode.
1153              When  --http2-proxy is  used, these  headers will not be altered
1154              regardless of this option.
1155
1156       --altsvc=<PROTOID,PORT[,HOST,[ORIGIN]]>
1157              Specify   protocol  ID,   port,  host   and  origin   of  alter‐
1158              native  service.   <HOST>  and <ORIGIN> are optional.  They  are
1159              advertised  in  alt-svc header  field only  in  HTTP/1.1   fron‐
1160              tend.   This  option can  be used  multiple times   to   specify
1161              multiple   alternative   services.  Example: --altsvc=h2,443
1162
1163       --add-request-header=<HEADER>
1164              Specify additional header field to add to  request  header  set.
1165              This   option just  appends header field  and won't replace any‐
1166              thing  already set.  This option  can  be  used  several   times
1167              to     specify     multiple      header     fields.     Example:
1168              --add-request-header="foo: bar"
1169
1170       --add-response-header=<HEADER>
1171              Specify  additional  header  field to  add  to  response  header
1172              set.    This option just appends  header field and won't replace
1173              anything already  set.  This option can be used  several   times
1174              to      specify     multiple      header    fields.     Example:
1175              --add-response-header="foo: bar"
1176
1177       --request-header-field-buffer=<SIZE>
1178              Set maximum buffer size for incoming HTTP request  header  field
1179              list.   This  is the sum of header name and value in bytes.   If
1180              trailer  fields  exist,  they  are  counted towards this number.
1181
1182              Default: 64K
1183
1184       --max-request-header-fields=<N>
1185              Set  maximum  number  of incoming  HTTP  request  header fields.
1186              If  trailer  fields exist,  they  are  counted towards this num‐
1187              ber.
1188
1189              Default: 100
1190
1191       --response-header-field-buffer=<SIZE>
1192              Set  maximum  buffer  size for  incoming  HTTP  response  header
1193              field  list.    This  is  the  sum of  header name and value  in
1194              bytes.  If  trailer  fields  exist, they   are  counted  towards
1195              this number.
1196
1197              Default: 64K
1198
1199       --max-response-header-fields=<N>
1200              Set  maximum number  of  incoming  HTTP response  header fields.
1201              If  trailer  fields exist,  they  are  counted towards this num‐
1202              ber.
1203
1204              Default: 500
1205
1206       --error-page=(<CODE>|*)=<PATH>
1207              Set  file path  to custom error page  served when nghttpx origi‐
1208              nally  generates  HTTP  error status  code  <CODE>.  <CODE> must
1209              be  greater  than  or equal to 400, and at most 599.  If "*"  is
1210              used instead of <CODE>,  it matches all HTTP  status  code.   If
1211              error  status  code comes  from backend server, the custom error
1212              pages are not used.
1213
1214       --server-name=<NAME>
1215              Change server response header field value to <NAME>.
1216
1217              Default: nghttpx
1218
1219       --no-server-rewrite
1220              Don't  rewrite  server  header  field  in  default  mode.   When
1221              --http2-proxy is used, these headers will not be altered regard‐
1222              less of this option.
1223
1224       --redirect-https-port=<PORT>
1225              Specify the port number which appears in Location  header  field
1226              when   redirect   to   HTTPS   URI   is   made   due   to "redi‐
1227              rect-if-not-tls" parameter in --backend option.
1228
1229              Default: 443
1230
1231   API
1232       --api-max-request-body=<SIZE>
1233              Set the maximum size of request body for API request.
1234
1235              Default: 32M
1236
1237   DNS
1238       --dns-cache-timeout=<DURATION>
1239              Set duration that cached DNS results remain  valid.   Note  that
1240              nghttpx caches the unsuccessful results as well.
1241
1242              Default: 10s
1243
1244       --dns-lookup-timeout=<DURATION>
1245              Set timeout that  DNS server is given to  respond to the initial
1246              DNS  query.  For  the  2nd  and later  queries, server is  given
1247              time based  on this timeout, and  it is scaled linearly.
1248
1249              Default: 5s
1250
1251       --dns-max-try=<N>
1252              Set the number of DNS query before nghttpx gives up name lookup.
1253
1254              Default: 2
1255
1256       --frontend-max-requests=<N>
1257              The  number   of  requests  that single  frontend connection can
1258              process.  For HTTP/2, this  is the number  of  streams  in   one
1259              HTTP/2  connection.    For  HTTP/1,  this is  the number of keep
1260              alive requests.  This is hint to  nghttpx,  and  it   may  allow
1261              additional few  requests.  The default value is unlimited.
1262
1263   Debug
1264       --frontend-http2-dump-request-header=<PATH>
1265              Dumps  request  headers  received by HTTP/2 frontend to the file
1266              denoted  in <PATH>.  The  output is done  in HTTP/1 header field
1267              format and each header block is followed by an empty line.  This
1268              option  is not thread safe and MUST  NOT  be  used  with  option
1269              -n<N>, where <N> >= 2.
1270
1271       --frontend-http2-dump-response-header=<PATH>
1272              Dumps  response  headers  sent  from HTTP/2 frontend to the file
1273              denoted  in <PATH>.  The  output is done  in HTTP/1 header field
1274              format and each header block is followed by an empty line.  This
1275              option  is not thread safe and MUST  NOT  be  used  with  option
1276              -n<N>, where <N> >= 2.
1277
1278       -o, --frontend-frame-debug
1279              Print HTTP/2 frames in  frontend to stderr.  This option is  not
1280              thread  safe and  MUST NOT  be used  with option -n=N,  where  N
1281              >= 2.
1282
1283   Process
1284       -D, --daemon
1285              Run  in a background.  If -D is used, the current working direc‐
1286              tory is changed to '/'.
1287
1288       --pid-file=<PATH>
1289              Set path to save PID of this program.
1290
1291       --user=<USER>
1292              Run this program as <USER>.   This option is intended to be used
1293              to drop root privileges.
1294
1295       --single-process
1296              Run  this  program  in a  single process mode for debugging pur‐
1297              pose.  Without this option,  nghttpx creates at  least  2   pro‐
1298              cesses:   master   and  worker   processes.   If  this option is
1299              used, master  and worker  are unified  into  a  single  process.
1300              nghttpx  still  spawns additional process if neverbleed is used.
1301              In  the single process mode, the signal handling feature is dis‐
1302              abled.
1303
1304   Scripting
1305       --mruby-file=<PATH>
1306              Set mruby script file
1307
1308       --ignore-per-pattern-mruby-error
1309              Ignore  mruby  compile error  for per-pattern mruby script file.
1310              If error  occurred, it is treated as   if  no  mruby  file  were
1311              specified for the pattern.
1312
1313   Misc
1314       --conf=<PATH>
1315              Load  configuration  from   <PATH>.   Please  note  that nghttpx
1316              always  tries to read the  default configuration file if  --conf
1317              is not given.
1318
1319              Default: /etc/nghttpx/nghttpx.conf
1320
1321       --include=<PATH>
1322              Load  additional  configurations  from  <PATH>.   File <PATH> is
1323              read  when  configuration   parser   encountered   this  option.
1324              This option can be used multiple times, or even recursively.
1325
1326       -v, --version
1327              Print version and exit.
1328
1329       -h, --help
1330              Print this help and exit.
1331
1332       The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
1333       * 1024).  Units are K, M and G (powers of 1024).
1334
1335       The <DURATION> argument is an integer and an optional unit (e.g., 1s is
1336       1  second  and  500ms  is  500  milliseconds).  Units are h, m, s or ms
1337       (hours, minutes, seconds and milliseconds, respectively).  If a unit is
1338       omitted, a second is used as unit.
1339

FILES

1341       /etc/nghttpx/nghttpx.conf
1342              The default configuration file path nghttpx searches at startup.
1343              The configuration file path can be changed using --conf option.
1344
1345              Those lines which are staring # are treated as comment.
1346
1347              The option name in the  configuration  file  is  the  long  com‐
1348              mand-line option name with leading -- stripped (e.g., frontend).
1349              Put = between option name and value.  Don't put extra leading or
1350              trailing spaces.
1351
1352              When  specifying  arguments including characters which have spe‐
1353              cial meaning to a shell, we usually use  quotes  so  that  shell
1354              does  not interpret them.  When writing this configuration file,
1355              quotes for this purpose must not be used.  For example,  specify
1356              additional request header field, do this:
1357
1358                 add-request-header=foo: bar
1359
1360              instead of:
1361
1362                 add-request-header="foo: bar"
1363
1364              The  options which do not take argument in the command-line take
1365              argument in the configuration file.  Specify yes as an  argument
1366              (e.g.,  http2-proxy=yes).   If  other  string  is  given,  it is
1367              ignored.
1368
1369              To specify private key and certificate file which are  given  as
1370              positional  arguments  in command-line, use private-key-file and
1371              certificate-file.
1372
1373              --conf option cannot be used in the configuration file and  will
1374              be ignored if specified.
1375
1376       Error log
1377              Error log is written to stderr by default.  It can be configured
1378              using --errorlog-file.  The format of log message is as follows:
1379
1380              <datetime>  <master-pid>   <current-pid>   <thread-id>   <level>
1381              (<filename>:<line>) <msg>
1382
1383              <datetime>
1384                     It  is  a  combination  of  date and time when the log is
1385                     written.  It is in ISO 8601 format.
1386
1387              <master-pid>
1388                     It is a master process ID.
1389
1390              <current-pid>
1391                     It is a process ID which writes this log.
1392
1393              <thread-id>
1394                     It is a thread ID which writes this  log.   It  would  be
1395                     unique within <current-pid>.
1396
1397              <filename> and <line>
1398                     They  are source file name, and line number which produce
1399                     this log.
1400
1401              <msg>  It is a log message body.
1402

SIGNALS

1404       SIGQUIT
1405              Shutdown gracefully.  First accept pending connections and  stop
1406              accepting   connection.   After  all  connections  are  handled,
1407              nghttpx exits.
1408
1409       SIGHUP Reload configuration file given in --conf.
1410
1411       SIGUSR1
1412              Reopen log files.
1413
1414       SIGUSR2
1415          Fork and execute nghttpx.  It will execute the binary  in  the  same
1416          path with same command-line arguments and environment variables.  As
1417          of nghttpx version 1.20.0, the new master process sends  SIGQUIT  to
1418          the original master process when it is ready to serve requests.  For
1419          the earlier versions of nghttpx, user has to  send  SIGQUIT  to  the
1420          original master process.
1421
1422          The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
1423          is usually used to execute new binary, and  the  master  process  is
1424          newly  spawned.  On the other hand, the latter just reloads configu‐
1425          ration file, and the same master process continues to exist.
1426
1427       NOTE:
1428          nghttpx consists of multiple processes: one process  for  processing
1429          these  signals, and another one for processing requests.  The former
1430          spawns the latter.  The former is called  master  process,  and  the
1431          latter  is  called  worker  process.   If neverbleed is enabled, the
1432          worker process spawns neverbleed daemon process which does  RSA  key
1433          processing.   The  above  signal must be sent to the master process.
1434          If the other processes received one of them, it  is  ignored.   This
1435          behaviour  of  these processes may change in the future release.  In
1436          other words, in the future release, the processes other than  master
1437          process  may  terminate upon the reception of these signals.  There‐
1438          fore these signals should not be sent to the  processes  other  than
1439          master process.
1440

SERVER PUSH

1442       nghttpx  supports  HTTP/2  server push in default mode with Link header
1443       field.  nghttpx looks for Link header  field  (RFC  5988)  in  response
1444       headers  from  backend server and extracts URI-reference with parameter
1445       rel=preload (see preload) and pushes those URIs to the frontend client.
1446       Here is a sample Link header field to initiate server push:
1447
1448          Link: </fonts/font.woff>; rel=preload
1449          Link: </css/theme.css>; rel=preload
1450
1451       Currently, the following restriction is applied for server push:
1452
1453       1. The associated stream must have method "GET" or "POST".  The associ‐
1454          ated stream's status code must be 200.
1455
1456       This limitation may be loosened in the future release.
1457
1458       nghttpx also supports server push if  both  frontend  and  backend  are
1459       HTTP/2  in  default mode.  In this case, in addition to server push via
1460       Link header field, server push from backend is  forwarded  to  frontend
1461       HTTP/2 session.
1462
1463       HTTP/2 server push will be disabled if --http2-proxy is used.
1464

UNIX DOMAIN SOCKET

1466       nghttpx  supports  UNIX domain socket with a filename for both frontend
1467       and backend connections.
1468
1469       Please note that current  nghttpx  implementation  does  not  delete  a
1470       socket  with  a filename.  And on start up, if nghttpx detects that the
1471       specified socket already exists  in  the  file  system,  nghttpx  first
1472       deletes it.  However, if SIGUSR2 is used to execute new binary and both
1473       old and new configurations use  same  filename,  new  binary  does  not
1474       delete the socket and continues to use it.
1475

OCSP STAPLING

1477       OCSP  query  is  done using external Python script fetch-ocsp-response,
1478       which has been originally developed in Perl as part of h2o  project  (‐
1479       https://github.com/h2o/h2o), and was translated into Python.
1480
1481       The  script  file  is  usually installed under $(prefix)/share/nghttp2/
1482       directory.   The  actual  path  to  script  can  be  customized   using
1483       --fetch-ocsp-response-file option.
1484
1485       If  OCSP  query is failed, previous OCSP response, if any, is continued
1486       to be used.
1487
1488       --fetch-ocsp-response-file option provides wide range of possibility to
1489       manage  OCSP  response.  It can take an arbitrary script or executable.
1490       The requirement is that  it  supports  the  command-line  interface  of
1491       fetch-ocsp-response script, and it must return a valid DER encoded OCSP
1492       response on success.  It must return exit code 0 on success, and 75 for
1493       temporary  error,  and  the  other error code for generic failure.  For
1494       large cluster of servers, it is not efficient for each server  to  per‐
1495       form  OCSP  query using fetch-ocsp-response.  Instead, you can retrieve
1496       OCSP response in some way, and store it in a disk or a shared database.
1497       Then  specify  a program in --fetch-ocsp-response-file to fetch it from
1498       those stores.  This could provide a way  to  share  the  OCSP  response
1499       between  fleet  of  servers,  and  also  any OCSP query strategy can be
1500       applied  which  may  be  beyond  the  ability  of  nghttpx  itself   or
1501       fetch-ocsp-response script.
1502

TLS SESSION RESUMPTION

1504       nghttpx  supports  TLS  session  resumption through both session ID and
1505       session ticket.
1506
1507   SESSION ID RESUMPTION
1508       By default, session ID is shared by all worker threads.
1509
1510       If --tls-session-cache-memcached is given, nghttpx will insert  serial‐
1511       ized session data to memcached with nghttpx:tls-session-cache: + lower‐
1512       case hex string of session ID as a memcached  entry  key,  with  expiry
1513       time 12 hours.  Session timeout is set to 12 hours.
1514
1515       By  default,  connections  to  memcached  server are not encrypted.  To
1516       enable encryption, use  tls  keyword  in  --tls-session-cache-memcached
1517       option.
1518
1519   TLS SESSION TICKET RESUMPTION
1520       By  default, session ticket is shared by all worker threads.  The auto‐
1521       matic key rotation is also enabled by  default.   Every  an  hour,  new
1522       encryption  key  is  generated,  and  previous  encryption  key becomes
1523       decryption only key.  We set session timeout to 12 hours, and  thus  we
1524       keep at most 12 keys.
1525
1526       If  --tls-ticket-key-memcached  is given, encryption keys are retrieved
1527       from memcached.  nghttpx just reads keys from  memcached;  one  has  to
1528       deploy  key  generator program to update keys frequently (e.g., every 1
1529       hour).  The example key generator tlsticketupdate.go is available under
1530       contrib  directory  in  nghttp2  archive.   The  memcached entry key is
1531       nghttpx:tls-ticket-key.  The data format stored  in  memcached  is  the
1532       binary format described below:
1533
1534          +--------------+-------+----------------+
1535          | VERSION (4)  |LEN (2)|KEY(48 or 80) ...
1536          +--------------+-------+----------------+
1537                         ^                        |
1538                         |                        |
1539                         +------------------------+
1540                         (LEN, KEY) pair can be repeated
1541
1542       All  numbers in the above figure is bytes.  All integer fields are net‐
1543       work byte order.
1544
1545       First 4 bytes integer VERSION field, which must  be  1.   The  2  bytes
1546       integer  LEN  field gives the length of following KEY field, which con‐
1547       tains key.  If --tls-ticket-key-cipher=aes-128-cbc is used, LEN must be
1548       48.   If  --tls-ticket-key-cipher=aes-256-cbc  is used, LEN must be 80.
1549       LEN and KEY pair can be repeated multiple times to store multiple keys.
1550       The  key  appeared  first is used as encryption key.  All the remaining
1551       keys are used as decryption only.
1552
1553       By default, connections to memcached  server  are  not  encrypted.   To
1554       enable   encryption,  use  tls  keyword  in  --tls-ticket-key-memcached
1555       option.
1556
1557       If --tls-ticket-key-file is given, encryption  key  is  read  from  the
1558       given  file.   In this case, nghttpx does not rotate key automatically.
1559       To rotate key, one has to restart nghttpx (see SIGNALS).
1560

CERTIFICATE TRANSPARENCY

1562       nghttpx supports TLS signed_certificate_timestamp extension (RFC 6962).
1563       The  relevant  options  are  --tls-sct-dir  and  sct-dir  parameter  in
1564       --subcert.  They takes a directory, and nghttpx reads all  files  whose
1565       extension  is .sct under the directory.  The *.sct files are encoded as
1566       SignedCertificateTimestamp struct  described  in  section  3.2  of  RFC
1567       69662.   This  format  is the same one used by nginx-ct and mod_ssl_ct.
1568       ct-submit can be used to submit certificates to log servers, and obtain
1569       the SignedCertificateTimestamp struct which can be used with nghttpx.
1570

MRUBY SCRIPTING

1572       WARNING:
1573          The current mruby extension API is experimental and not frozen.  The
1574          API is subject to change in the future release.
1575
1576       WARNING:
1577          Almost all string value returned from  method,  or  attribute  is  a
1578          fresh  new  mruby  string,  which  involves  memory  allocation, and
1579          copies.  Therefore, it is strongly recommended  to  store  a  return
1580          value  in a local variable, and use it, instead of calling method or
1581          accessing attribute repeatedly.
1582
1583       nghttpx allows users to extend  its  capability  using  mruby  scripts.
1584       nghttpx  has  2  hook points to execute mruby script: request phase and
1585       response phase.  The request phase hook is invoked  after  all  request
1586       header  fields  are  received  from client.  The response phase hook is
1587       invoked after all response header  fields  are  received  from  backend
1588       server.   These  hooks  allows users to modify header fields, or common
1589       HTTP variables, like authority or request path, and even return  custom
1590       response without forwarding request to backend servers.
1591
1592       There are 2 levels of mruby script invocations: global and per-pattern.
1593       The global mruby script is set by --mruby-file option and is called for
1594       all requests.  The per-pattern mruby script is set by "mruby" parameter
1595       in -b option.  It is invoked for a request which matches the particular
1596       pattern.   The  order of hook invocation is: global request phase hook,
1597       per-pattern request phase hook, per-pattern response  phase  hook,  and
1598       finally  global response phase hook.  If a hook returns a response, any
1599       later hooks are not invoked.  The global request hook is invoked before
1600       the  pattern  matching is made and changing request path may affect the
1601       pattern matching.
1602
1603       Please note that request and response hooks of per-pattern mruby script
1604       for  a  single request might not come from the same script.  This might
1605       happen after a request hook is executed, backend failed for  some  rea‐
1606       son,  and  at  the  same time, backend configuration is replaced by API
1607       request, and then the request uses new  configuration  on  retry.   The
1608       response  hook  from  new  configuration,  if  it is specified, will be
1609       invoked.
1610
1611       The all mruby script will be evaluated once per thread on startup,  and
1612       it  must  instantiate object and evaluate it as the return value (e.g.,
1613       App.new).  This object is called app object.   If  app  object  defines
1614       on_req  method,  it is called with Nghttpx::Env object on request hook.
1615       Similarly, if app object defines on_resp  method,  it  is  called  with
1616       Nghttpx::Env object on response hook.  For each method invocation, user
1617       can can  access  Nghttpx::Request  and  Nghttpx::Response  objects  via
1618       Nghttpx::Env#req and Nghttpx::Env#resp respectively.
1619
1620       Nghttpx::REQUEST_PHASE
1621              Constant to represent request phase.
1622
1623       Nghttpx::RESPONSE_PHASE
1624              Constant to represent response phase.
1625
1626       class Nghttpx::Env
1627              Object to represent current request specific context.
1628
1629              attribute [R] req
1630                     Return Request object.
1631
1632              attribute [R] resp
1633                     Return Response object.
1634
1635              attribute [R] ctx
1636                     Return  Ruby hash object.  It persists until request fin‐
1637                     ishes.  So values  set  in  request  phase  hook  can  be
1638                     retrieved in response phase hook.
1639
1640              attribute [R] phase
1641                     Return the current phase.
1642
1643              attribute [R] remote_addr
1644                     Return  IP  address of a remote client.  If connection is
1645                     made via UNIX domain  socket,  this  returns  the  string
1646                     "localhost".
1647
1648              attribute [R] server_addr
1649                     Return  address  of  server that accepted the connection.
1650                     This is a string which specified  in  --frontend  option,
1651                     excluding  port  number,  and  not a resolved IP address.
1652                     For UNIX domain socket, this is a  path  to  UNIX  domain
1653                     socket.
1654
1655              attribute [R] server_port
1656                     Return  port number of the server frontend which accepted
1657                     the connection from client.
1658
1659              attribute [R] tls_used
1660                     Return true if TLS is used on the connection.
1661
1662              attribute [R] tls_sni
1663                     Return the TLS SNI value which client sent in  this  con‐
1664                     nection.
1665
1666              attribute [R] tls_client_fingerprint_sha256
1667                     Return the SHA-256 fingerprint of a client certificate.
1668
1669              attribute [R] tls_client_fingerprint_sha1
1670                     Return the SHA-1 fingerprint of a client certificate.
1671
1672              attribute [R] tls_client_issuer_name
1673                     Return the issuer name of a client certificate.
1674
1675              attribute [R] tls_client_subject_name
1676                     Return the subject name of a client certificate.
1677
1678              attribute [R] tls_client_serial
1679                     Return the serial number of a client certificate.
1680
1681              attribute [R] tls_client_not_before
1682                     Return  the start date of a client certificate in seconds
1683                     since the epoch.
1684
1685              attribute [R] tls_client_not_after
1686                     Return the end date of a client  certificate  in  seconds
1687                     since the epoch.
1688
1689              attribute [R] tls_cipher
1690                     Return a TLS cipher negotiated in this connection.
1691
1692              attribute [R] tls_protocol
1693                     Return  a TLS protocol version negotiated in this connec‐
1694                     tion.
1695
1696              attribute [R] tls_session_id
1697                     Return a session ID for this connection in hex string.
1698
1699              attribute [R] tls_session_reused
1700                     Return true if, and only if a SSL/TLS session is reused.
1701
1702              attribute [R] alpn
1703                     Return ALPN identifier negotiated in this connection.
1704
1705              attribute [R] tls_handshake_finished
1706                     Return true if SSL/TLS handshake  has  finished.   If  it
1707                     returns  false  in the request phase hook, the request is
1708                     received in TLSv1.3 early data (0-RTT) and might be  vul‐
1709                     nerable   to   the  replay  attack.   nghttpx  will  send
1710                     Early-Data header field to backend  servers  to  indicate
1711                     this.
1712
1713       class Nghttpx::Request
1714              Object  to  represent  request from client.  The modification to
1715              Request object is allowed only in request phase hook.
1716
1717              attribute [R] http_version_major
1718                     Return HTTP major version.
1719
1720              attribute [R] http_version_minor
1721                     Return HTTP minor version.
1722
1723              attribute [R/W] method
1724                     HTTP method.  On  assignment,  copy  of  given  value  is
1725                     assigned.   We  don't  accept  arbitrary method name.  We
1726                     will document them later, but well  known  methods,  like
1727                     GET, PUT and POST, are all supported.
1728
1729              attribute [R/W] authority
1730                     Authority  (i.e.,  example.org),  including optional port
1731                     component .   On  assignment,  copy  of  given  value  is
1732                     assigned.
1733
1734              attribute [R/W] scheme
1735                     Scheme (i.e., http, https).  On assignment, copy of given
1736                     value is assigned.
1737
1738              attribute [R/W] path
1739                     Request   path,   including   query   component    (i.e.,
1740                     /index.html).   On  assignment,  copy  of  given value is
1741                     assigned.  The path does not include authority  component
1742                     of URI.  This may include query component.  nghttpx makes
1743                     certain  normalization  for  path.    It   decodes   per‐
1744                     cent-encoding     for    unreserved    characters    (see
1745                     https://tools.ietf.org/html/rfc3986#section-2.3),     and
1746                     resolves ".." and ".".  But it may leave characters which
1747                     should be percent-encoded as is. So be careful when  com‐
1748                     paring path against desired string.
1749
1750              attribute [R] headers
1751                     Return  Ruby  hash  containing  copy  of  request  header
1752                     fields.  Changing values in returned hash does not change
1753                     request  header  fields actually used in request process‐
1754                     ing.       Use       Nghttpx::Request#add_header       or
1755                     Nghttpx::Request#set_header   to  change  request  header
1756                     fields.
1757
1758              add_header(key, value)
1759                     Add header entry associated with key.  The value  can  be
1760                     single  string  or  array of string.  It does not replace
1761                     any existing values associated with key.
1762
1763              set_header(key, value)
1764                     Set header entry associated with key.  The value  can  be
1765                     single string or array of string.  It replaces any exist‐
1766                     ing values associated with key.
1767
1768              clear_headers()
1769                     Clear all existing request header fields.
1770
1771              push(uri)
1772                     Initiate to push resource identified by uri.  Only HTTP/2
1773                     protocol supports this feature.  For the other protocols,
1774                     this method is noop.  uri can be absolute  URI,  absolute
1775                     path  or relative path to the current request.  For abso‐
1776                     lute or relative path, scheme and authority are inherited
1777                     from  the  current  request.  Currently, method is always
1778                     GET.  nghttpx will issue request to  backend  servers  to
1779                     fulfill  this  request.   The  request and response phase
1780                     hooks will be called for pushed resource as well.
1781
1782       class Nghttpx::Response
1783              Object to represent response from backend server.
1784
1785              attribute [R] http_version_major
1786                     Return HTTP major version.
1787
1788              attribute [R] http_version_minor
1789                     Return HTTP minor version.
1790
1791              attribute [R/W] status
1792                     HTTP status code.  It must be in the  range  [200,  999],
1793                     inclusive.  The non-final status code is not supported in
1794                     mruby scripting at the moment.
1795
1796              attribute [R] headers
1797                     Return Ruby  hash  containing  copy  of  response  header
1798                     fields.  Changing values in returned hash does not change
1799                     response header fields actually used in response process‐
1800                     ing.        Use      Nghttpx::Response#add_header      or
1801                     Nghttpx::Response#set_header to  change  response  header
1802                     fields.
1803
1804              add_header(key, value)
1805                     Add  header  entry associated with key.  The value can be
1806                     single string or array of string.  It  does  not  replace
1807                     any existing values associated with key.
1808
1809              set_header(key, value)
1810                     Set  header  entry associated with key.  The value can be
1811                     single string or array of string.  It replaces any exist‐
1812                     ing values associated with key.
1813
1814              clear_headers()
1815                     Clear all existing response header fields.
1816
1817              return(body)
1818                     Return  custom  response  body  to  a  client.  When this
1819                     method is called in request phase hook,  the  request  is
1820                     not forwarded to the backend, and response phase hook for
1821                     this request will not be invoked.  When  this  method  is
1822                     called  in  response  phase  hook,  response from backend
1823                     server is canceled and discarded.  The  status  code  and
1824                     response  header  fields  should be set before using this
1825                     method.       To      set      status      code,      use
1826                     Nghttpx::Response#status.  If status code is not set, 200
1827                     is   used.     To    set    response    header    fields,
1828                     Nghttpx::Response#add_header                          and
1829                     Nghttpx::Response#set_header.   When   this   method   is
1830                     invoked  in response phase hook, the response headers are
1831                     filled with the ones received from  backend  server.   To
1832                     send   completely   custom   header  fields,  first  call
1833                     Nghttpx::Response#clear_headers  to  erase  all  existing
1834                     header  fields,  and then add required header fields.  It
1835                     is an error  to  call  this  method  twice  for  a  given
1836                     request.
1837
1838              send_info(status, headers)
1839                     Send  non-final  (informational)  response  to  a client.
1840                     status must be in the range [100, 199], inclusive.  head‐
1841                     ers is a hash containing response header fields.  Its key
1842                     must be a string, and the associated value must be either
1843                     string  or  array  of strings.  Since this is not a final
1844                     response, even if this  method  is  invoked,  request  is
1845                     still      forwarded      to     a     backend     unless
1846                     Nghttpx::Response#return is called.  This method  can  be
1847                     called   multiple  times.   It  cannot  be  called  after
1848                     Nghttpx::Response#return is called.
1849
1850   MRUBY EXAMPLES
1851       Modify request path:
1852
1853          class App
1854            def on_req(env)
1855              env.req.path = "/apps#{env.req.path}"
1856            end
1857          end
1858
1859          App.new
1860
1861       Don't forget to instantiate and evaluate object at the last line.
1862
1863       Restrict  permission  of  viewing  a  content  to  a  specific   client
1864       addresses:
1865
1866          class App
1867            def on_req(env)
1868              allowed_clients = ["127.0.0.1", "::1"]
1869
1870              if env.req.path.start_with?("/log/") &&
1871                 !allowed_clients.include?(env.remote_addr) then
1872                env.resp.status = 404
1873                env.resp.return "permission denied"
1874              end
1875            end
1876          end
1877
1878          App.new
1879

API ENDPOINTS

1881       nghttpx  exposes API endpoints to manipulate it via HTTP based API.  By
1882       default, API endpoint is disabled.  To enable it, add a dedicated fron‐
1883       tend  for  API  using  --frontend  option  with  "api"  parameter.  All
1884       requests which come from this frontend address, will be treated as  API
1885       request.
1886
1887       The  response  is  normally  JSON dictionary, and at least includes the
1888       following keys:
1889
1890       status The status of the request processing.  The following values  are
1891              defined:
1892
1893              Success
1894                     The request was successful.
1895
1896              Failure
1897                     The request was failed.  No change has been made.
1898
1899       code   HTTP status code
1900
1901       Additionally,  depending  on the API endpoint, data key may be present,
1902       and its value contains the API endpoint specific data.
1903
1904       We wrote "normally", since nghttpx may return ordinal HTML response  in
1905       some  cases  where  the error has occurred before reaching API endpoint
1906       (e.g., header field is too large).
1907
1908       The following section describes available API endpoints.
1909
1910   POST /api/v1beta1/backendconfig
1911       This  API  replaces  the  current  backend  server  settings  with  the
1912       requested  ones.   The  request  method should be POST, but PUT is also
1913       acceptable.  The request body must be nghttpx configuration  file  for‐
1914       mat.  For configuration file format, see FILES section.  The line sepa‐
1915       rator inside the request body must be  single  LF  (0x0A).   Currently,
1916       only  backend  option  is  parsed,  the others are simply ignored.  The
1917       semantics of this API is replace the current backend with  the  backend
1918       options  in  request body.  Describe the desired set of backend severs,
1919       and nghttpx makes it happen.  If there is no backend option is found in
1920       request  body,  the current set of backend is replaced with the backend
1921       option's default value, which is 127.0.0.1,80.
1922
1923       The replacement is done instantly without breaking existing connections
1924       or  requests.   It also avoids any process creation as is the case with
1925       hot swapping with signals.
1926
1927       The one limitation is that  only  numeric  IP  address  is  allowed  in
1928       backend  in  request  body  unless  "dns"  parameter  is used while non
1929       numeric hostname is allowed in command-line or  configuration  file  is
1930       read using --conf.
1931
1932   GET /api/v1beta1/configrevision
1933       This  API  returns  configuration revision of the current nghttpx.  The
1934       configuration revision is opaque string,  and  it  changes  after  each
1935       reloading by SIGHUP.  With this API, an external application knows that
1936       whether nghttpx has finished reloading its configuration  by  comparing
1937       the  configuration revisions between before and after reloading.  It is
1938       recommended to disable persistent (keep-alive) connection for this pur‐
1939       pose  in  order  to avoid to send a request using the reused connection
1940       which may bound to an old process.
1941
1942       This API returns response  including  data  key.   Its  value  is  JSON
1943       object, and it contains at least the following key:
1944
1945       configRevision
1946              The configuration revision of the current nghttpx
1947

SEE ALSO

1949       nghttp(1), nghttpd(1), h2load(1)
1950

AUTHOR

1952       Tatsuhiro Tsujikawa
1953
1955       2012, 2015, 2016, Tatsuhiro Tsujikawa
1956
1957
1958
1959
19601.40.0                           Nov 15, 2019                       NGHTTPX(1)
Impressum