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/3, 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 ad‐
29              dresses 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 to‐
99              gether 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-timeout=<DU‐
107              RATION>",  "group=<GROUP>",   "group-weight=<N>",  "weight=<N>",
108              and "dnf".    The  parameter   consists   of  keyword,   and op‐
109              tionally followed by "="  and value.  For example, the parameter
110              "proto=h2"  consists of the keyword "proto" and value "h2".  The
111              parameter "tls" consists of the keyword  "tls"   without  value.
112              Each parameter  is described  as follows.
113
114              The  backend  application  protocol   can be specified using op‐
115              tional   "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 at‐
138              tempts  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 en‐
153              abled for all backend  servers sharing the same  <PATTERN>.   It
154              is  advised  to  set  "affinity" parameter  to  all  backend ex‐
155              plicitly if session affinity  is desired.  The session  affinity
156              may    break  if   one  of  the   backend  gets unreachable,  or
157              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 "affinity-cookie-se‐
165              cure=<SECURE>"  controls  the  Secure  attribute  of  a  cookie.
166              The default value is "auto", and the Secure attribute is  deter‐
167              mined by a request scheme.  If a request scheme is "https", then
168              Secure  attribute  is set.  Otherwise, it  is not set.  If  <SE‐
169              CURE> is "yes", the  Secure attribute  is  always set.   If <SE‐
170              CURE>   is "no",   the   Secure   attribute  is   always   omit‐
171              ted.   "affinity-cookie-stickiness=<STICKINESS>"        controls
172              stickiness    of     this   affinity.    If    <STICKINESS>   is
173              "loose", removing or adding a backend  server  might  break  the
174              affinity   and  the  request might  be forwarded  to a different
175              backend server.   If <STICKINESS> is "strict", removing the des‐
176              ignated  backend server breaks affinity, but adding  new backend
177              server does  not cause breakage.  If   the  designated   backend
178              server  becomes unavailable, new backend server is chosen  as if
179              the request does not have  an  affinity  cookie.    <STICKINESS>
180              defaults  to "loose".
181
182              By  default,  name  resolution  of  backend host name is done at
183              start  up,  or reloading  configuration.   If   "dns"  parameter
184              is   given,   name  resolution   takes  place dynamically.  This
185              is useful  if backend address changes  frequently.    If   "dns"
186              is  given,   name   resolution   of  backend    host   name   at
187              start   up,   or   reloading configuration is skipped.
188
189              If "redirect-if-not-tls" parameter  is used, the matched backend
190              requires    that   frontend  connection   is  TLS encrypted.  If
191              it isn't, nghttpx responds to the request with 308  status code,
192              and   https  URI  the  client should use instead  is included in
193              Location  header field.  The port number in  redirect URI is 443
194              by   default,  and  can be  changed using  --redirect-https-port
195              option.   If at least one   backend  has   "redirect-if-not-tls"
196              parameter,  this  feature  is  enabled   for all backend servers
197              sharing the   same   <PATTERN>.    It    is   advised   to   set
198              "redirect-if-no-tls"    parameter   to    all   backends explic‐
199              itly if this feature is desired.
200
201              If "upgrade-scheme"  parameter is used along  with "tls" parame‐
202              ter,  HTTP/2  :scheme  pseudo header field is changed to "https"
203              from "http" when forwarding a request to this  particular  back‐
204              end.   This  is   a  workaround for a backend server  which  re‐
205              quires  "https" :scheme  pseudo  header field on  TLS  encrypted
206              connection.
207
208              "mruby=<PATH>"   parameter  specifies  a  path  to  mruby script
209              file  which  is  invoked when  this  pattern  is  matched.   All
210              backends  which  share the same pattern must have the same mruby
211              path.
212
213              "read-timeout=<DURATION>" and "write-timeout=<DURATION>" parame‐
214              ters   specify the  read and  write timeout  of the backend con‐
215              nection  when this  pattern is   matched.   All  backends  which
216              share  the  same  pattern must have the same timeouts.  If these
217              timeouts     are    entirely    omitted    for    a     pattern,
218              --backend-read-timeout           and --backend-write-timeout are
219              used.
220
221              "group=<GROUP>"  parameter specifies  the name   of  group  this
222              backend  address belongs to.  By default, it belongs to  the un‐
223              named  default group.   The name   of  group   is  unique    per
224              pattern.    "group-weight=<N>"   parameter specifies the  weight
225              of  the group.  The  higher weight gets   more  frequently   se‐
226              lected   by   the  load   balancing algorithm.  <N> must be  [1,
227              256] inclusive.  The weight 8 has 4 times more weight   than  2.
228              <N>  must be the same for  all addresses  which  share the  same
229              <GROUP>.   If "group-weight" is  omitted in an address,  but the
230              other  address   which  belongs  to  the  same  group  specifies
231              "group-weight",    its     weight    is    used.       If     no
232              "group-weight"   is  specified  for  all  addresses,  the weight
233              of a group becomes 1.  "group" and "group-weight" are ignored if
234              session affinity is enabled.
235
236              "weight=<N>"  parameter  specifies  the  weight  of  the backend
237              address  inside  a  group  which   this   address  belongs   to.
238              The  higher  weight  gets more  frequently selected by  the load
239              balancing algorithm.   <N> must be [1,   256]  inclusive.    The
240              weight  8   has  4 times  more weight  than weight  2.  If  this
241              parameter  is omitted, weight  becomes  1.   "weight"   is   ig‐
242              nored  if  session affinity is enabled.
243
244              If  "dnf"  parameter  is   specified, an incoming request is not
245              forwarded to a backend  and just consumed along  with  the   re‐
246              quest  body   (actually  a  backend server  never be contacted).
247              It  is expected  that the HTTP  response is generated  by  mruby
248              script (see "mruby=<PATH>" parameter above).  "dnf" is an abbre‐
249              viation of "do not forward".
250
251              Since ";" and ":" are  used as  delimiter,  <PATTERN>  must  not
252              contain   these  characters.  In order  to include ":" in  <PAT‐
253              TERN>,  one  has  to  specify  "%3A"  (which  is percent-encoded
254              from  of   ":")  instead.    Since ";"  has special  meaning  in
255              shell,  the  option  value must  be quoted.
256
257              Default: 127.0.0.1,80
258
259       -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]
260              Set  frontend  host and  port.   If  <HOST> is  '*',  it assumes
261              all  addresses   including   both   IPv4 and  IPv6.  UNIX domain
262              socket can  be specified by  prefixing path name  with   "unix:"
263              (e.g.,   unix:/var/run/nghttpx.sock).  This  option can  be used
264              multiple times  to listen  to multiple addresses.
265
266              This option  can take  0 or  more  parameters,   which  are  de‐
267              scribed   below.    Note   that  "api"  and  "healthmon" parame‐
268              ters are mutually exclusive.
269
270              Optionally, TLS  can be disabled by  specifying "no-tls" parame‐
271              ter.  TLS is enabled by default.
272
273              If  "sni-fwd" parameter is  used, when performing a match to se‐
274              lect a backend server,  SNI host name received from  the  client
275              is  used   instead  of  the request  host.  See --backend option
276              about the pattern match.
277
278              To  make this  frontend as  API endpoint,  specify "api" parame‐
279              ter.   This   is  disabled  by  default.    It  is important  to
280              limit the  access  to  the API   frontend.   Otherwise,  someone
281              may  change   the  backend  server, and break your services,  or
282              expose confidential information to the outside the world.
283
284              To  make  this  frontend  as  health  monitor  endpoint, specify
285              "healthmon"   parameter.    This  is  disabled  by default.  Any
286              requests which come through  this address are replied  with  200
287              HTTP status, without no body.
288
289              To accept  PROXY protocol  version 1  and 2  on frontend connec‐
290              tion,  specify  "proxyproto" parameter.   This  is  disabled  by
291              default.
292
293              To  receive   HTTP/3  (QUIC)  traffic,   specify  "quic" parame‐
294              ter.  It  makes nghttpx listen on  UDP  port  rather  than   TCP
295              port.   UNIX   domain  socket,   "api",  and "healthmon"  param‐
296              eters  cannot   be  used  with  "quic" parameter.
297
298              Default: *,3000
299
300       --backlog=<N>
301              Set listen backlog size.
302
303              Default: 65536
304
305       --backend-address-family=(auto|IPv4|IPv6)
306              Specify  address  family  of  backend  connections.   If  "auto"
307              is  given,  both  IPv4   and  IPv6 are considered.  If "IPv4" is
308              given, only  IPv4 address is  considered.  If "IPv6"  is  given,
309              only IPv6 address is considered.
310
311              Default: auto
312
313       --backend-http-proxy-uri=<URI>
314              Specify        proxy         URI        in        the       form
315              http://[<USER>:<PASS>@]<PROXY>:<PORT>.     If    a    proxy  re‐
316              quires   authentication,   specify   <USER>   and  <PASS>.  Note
317              that  they must be properly  percent-encoded.   This  proxy   is
318              used   when the  backend connection  is HTTP/2.  First,  make  a
319              CONNECT  request  to  the proxy  and  it connects  to the  back‐
320              end  on behalf  of nghttpx.   This forms  tunnel.   After  that,
321              nghttpx   performs   SSL/TLS  handshake  with   the   downstream
322              through  the   tunnel.  The timeouts when connecting and  making
323              CONNECT     request     can     be          specified         by
324              --backend-read-timeout    and --backend-write-timeout options.
325
326   Performance
327       -n, --workers=<N>
328              Set the number of worker threads.
329
330              Default: 1
331
332       --single-thread
333              Run  everything  in one  thread inside the worker process.  This
334              feature   is   provided  for    better    debugging  experience,
335              or   for   the  platforms   which   lack   thread  support.   If
336              threading  is disabled,  this  option  is always enabled.
337
338       --read-rate=<SIZE>
339              Set maximum  average read  rate on  frontend  connection.   Set‐
340              ting 0 to this option means read rate is unlimited.
341
342              Default: 0
343
344       --read-burst=<SIZE>
345              Set   maximum  read  burst  size  on frontend  connection.  Set‐
346              ting  0  to this  option  means  read burst  size  is unlimited.
347
348              Default: 0
349
350       --write-rate=<SIZE>
351              Set maximum  average write rate on  frontend  connection.   Set‐
352              ting 0 to this option means write rate is unlimited.
353
354              Default: 0
355
356       --write-burst=<SIZE>
357              Set   maximum  write  burst size  on frontend  connection.  Set‐
358              ting  0 to  this  option means  write  burst size  is unlimited.
359
360              Default: 0
361
362       --worker-read-rate=<SIZE>
363              Set maximum average read rate on frontend connection per worker.
364              Setting   0 to  this option  means read  rate is unlimited.  Not
365              implemented yet.
366
367              Default: 0
368
369       --worker-read-burst=<SIZE>
370              Set maximum  read burst size on  frontend connection per worker.
371              Setting  0  to  this  option means read burst size is unlimited.
372              Not implemented yet.
373
374              Default: 0
375
376       --worker-write-rate=<SIZE>
377              Set maximum  average write  rate  on   frontend  connection  per
378              worker.   Setting   0 to this option  means write rate is unlim‐
379              ited.  Not implemented yet.
380
381              Default: 0
382
383       --worker-write-burst=<SIZE>
384              Set maximum write burst  size on frontend connection per worker.
385              Setting  0  to  this option means write burst size is unlimited.
386              Not implemented yet.
387
388              Default: 0
389
390       --worker-frontend-connections=<N>
391              Set maximum number  of  simultaneous  connections  frontend  ac‐
392              cepts.  Setting 0 means unlimited.
393
394              Default: 0
395
396       --backend-connections-per-host=<N>
397              Set  maximum number  of  backend concurrent  connections (and/or
398              streams in  case  of HTTP/2)  per origin  host.  This option  is
399              meaningful  when  --http2-proxy   option  is used.   The  origin
400              host  is  determined  by  authority portion of  request URI  (or
401              :authority   header field for HTTP/2).   To  limit  the   number
402              of    connections    per   frontend          for         default
403              mode,       use --backend-connections-per-frontend.
404
405              Default: 8
406
407       --backend-connections-per-frontend=<N>
408              Set  maximum number  of  backend concurrent  connections (and/or
409              streams  in case of HTTP/2)   per  frontend.   This  option   is
410              only  used  for  default   mode.   0  means unlimited.  To limit
411              the  number of connections per host with           --http2-proxy
412              option,          use --backend-connections-per-host.
413
414              Default: 0
415
416       --rlimit-nofile=<N>
417              Set  maximum  number of open files (RLIMIT_NOFILE) to <N>.  If 0
418              is given, nghttpx does not set the limit.
419
420              Default: 0
421
422       --rlimit-memlock=<N>
423              Set maximum number of bytes of memory that may  be  locked  into
424              RAM.  If  0 is  given,  nghttpx does  not set  the limit.
425
426              Default: 0
427
428       --backend-request-buffer=<SIZE>
429              Set buffer size used to store backend request.
430
431              Default: 16K
432
433       --backend-response-buffer=<SIZE>
434              Set buffer size used to store backend response.
435
436              Default: 128K
437
438       --fastopen=<N>
439              Enables   "TCP Fast  Open" for  the listening  socket and limits
440              the  maximum length for the  queue of connections that have  not
441              yet  completed the three-way handshake.  If value is 0 then fast
442              open is disabled.
443
444              Default: 0
445
446       --no-kqueue
447              Don't use  kqueue.  This  option is  only   applicable  for  the
448              platforms  which have kqueue.  For  other platforms, this option
449              will be simply ignored.
450
451   Timeout
452       --frontend-http2-read-timeout=<DURATION>
453              Specify read timeout for HTTP/2 frontend connection.
454
455              Default: 3m
456
457       --frontend-http3-read-timeout=<DURATION>
458              Specify read timeout for HTTP/3 frontend connection.
459
460              Default: 3m
461
462       --frontend-read-timeout=<DURATION>
463              Specify read timeout for HTTP/1.1 frontend connection.
464
465              Default: 1m
466
467       --frontend-write-timeout=<DURATION>
468              Specify write timeout for all frontend connections.
469
470              Default: 30s
471
472       --frontend-keep-alive-timeout=<DURATION>
473              Specify   keep-alive   timeout   for   frontend   HTTP/1 connec‐
474              tion.
475
476              Default: 1m
477
478       --stream-read-timeout=<DURATION>
479              Specify   read  timeout  for HTTP/2  streams.  0  means no time‐
480              out.
481
482              Default: 0
483
484       --stream-write-timeout=<DURATION>
485              Specify write  timeout for  HTTP/2 streams.  0  means  no  time‐
486              out.
487
488              Default: 1m
489
490       --backend-read-timeout=<DURATION>
491              Specify read timeout for backend connection.
492
493              Default: 1m
494
495       --backend-write-timeout=<DURATION>
496              Specify write timeout for backend connection.
497
498              Default: 30s
499
500       --backend-connect-timeout=<DURATION>
501              Specify   timeout  before  establishing TCP  connection to back‐
502              end.
503
504              Default: 30s
505
506       --backend-keep-alive-timeout=<DURATION>
507              Specify   keep-alive   timeout    for   backend   HTTP/1 connec‐
508              tion.
509
510              Default: 2s
511
512       --listener-disable-timeout=<DURATION>
513              After accepting  connection failed,  connection listener is dis‐
514              abled  for a given  amount of time.   Specifying 0 disables this
515              feature.
516
517              Default: 30s
518
519       --frontend-http2-setting-timeout=<DURATION>
520              Specify  timeout before  SETTINGS ACK  is received  from client.
521
522              Default: 10s
523
524       --backend-http2-settings-timeout=<DURATION>
525              Specify  timeout before  SETTINGS ACK  is received  from backend
526              server.
527
528              Default: 10s
529
530       --backend-max-backoff=<DURATION>
531              Specify  maximum backoff  interval.  This  is used   when  doing
532              health  check against offline backend  (see "fail" parameter  in
533              --backend  option).   It is  also used  to limit   the   maximum
534              interval  to  temporarily  disable backend  when nghttpx  failed
535              to  connect to  it.  These intervals are calculated  using expo‐
536              nential  backoff,  and  consecutive failed attempts increase the
537              interval.  This option caps its maximum value.
538
539              Default: 2m
540
541   SSL/TLS
542       --ciphers=<SUITE>
543              Set allowed  cipher list  for frontend  connection.  The  format
544              of  the  string is described in OpenSSL ciphers(1).  This option
545              sets cipher suites for  TLSv1.2 or earlier.  Use --tls13-ciphers
546              for TLSv1.3.
547
548              Default:
549              ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
550
551       --tls13-ciphers=<SUITE>
552              Set  allowed  cipher list  for frontend  connection.  The format
553              of the string is described in OpenSSL ciphers(1).  This   option
554              sets  cipher   suites  for  TLSv1.3.   Use --ciphers for TLSv1.2
555              or earlier.
556
557              Default:
558              TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
559
560       --client-ciphers=<SUITE>
561              Set  allowed cipher  list for  backend connection.   The  format
562              of  the  string is described in OpenSSL ciphers(1).  This option
563              sets   cipher   suites   for    TLSv1.2   or    earlier.     Use
564              --tls13-client-ciphers for TLSv1.3.
565
566              Default:
567              ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
568
569       --tls13-client-ciphers=<SUITE>
570              Set   allowed cipher  list for  backend connection.   The format
571              of the string is described in OpenSSL ciphers(1).  This   option
572              sets       cipher        suites      for      TLSv1.3.       Use
573              --tls13-client-ciphers for TLSv1.2 or earlier.
574
575              Default:
576              TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
577
578       --ecdh-curves=<LIST>
579              Set  supported  curve  list  for  frontend  connections.  <LIST>
580              is a  colon separated list of curve  NID or names in the prefer‐
581              ence order.  The supported curves depend on the  linked  OpenSSL
582              library.  This  function  requires OpenSSL >= 1.0.2.
583
584              Default: X25519:P-256:P-384:P-521
585
586       -k, --insecure
587              Don't  verify backend  server's  certificate  if TLS  is enabled
588              for backend connections.
589
590       --cacert=<PATH>
591              Set path to trusted CA  certificate file.  It is used in backend
592              TLS connections  to verify  peer's certificate.  It is also used
593              to    verify   OCSP   response   from   the   script   set    by
594              --fetch-ocsp-response-file.   The   file  must be in PEM format.
595              It can contain multiple  certificates.  If the   linked  OpenSSL
596              is  configured   to  load   system  wide certificates, they  are
597              loaded at startup  regardless of this option.
598
599       --private-key-passwd-file=<PATH>
600              Path  to file  that contains  password for  the server's private
601              key.    If  none is  given and the private  key is password pro‐
602              tected it'll be requested interactively.
603
604       --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
605              Specify   additional  certificate   and   private   key    file.
606              nghttpx  will   choose certificates based on  the hostname indi‐
607              cated by client using TLS SNI extension.  If nghttpx  is   built
608              with   OpenSSL   >=  1.0.2,   the shared  elliptic curves (e.g.,
609              P-256) between  client and server are also taken into  consider‐
610              ation.   This allows nghttpx  to send ECDSA certificate  to mod‐
611              ern clients, while   sending  RSA  based  certificate  to  older
612              clients.   This  option can be used  multiple  times.   To  make
613              OCSP  stapling  work, <CERTPATH> must be absolute path.
614
615              Additional parameter  can be specified in  <PARAM>.  The  avail‐
616              able <PARAM> is "sct-dir=<DIR>".
617
618              "sct-dir=<DIR>"   specifies  the   path to  directory which con‐
619              tains          *.sct           files           for           TLS
620              signed_certificate_timestamp extension (RFC 6962).  This feature
621              requires   OpenSSL   >=   1.0.2.    See   also --tls-sct-dir op‐
622              tion.
623
624       --dh-param-file=<PATH>
625              Path  to file that contains  DH parameters in PEM format.  With‐
626              out  this   option,  DHE   cipher  suites   are  not available.
627
628       --npn-list=<LIST>
629              Comma delimited list of  ALPN protocol identifier sorted in  the
630              order  of preference.  That  means most desirable protocol comes
631              first.  This  is used  in both  ALPN  and  NPN.   The  parameter
632              must be  delimited by a single comma only  and any  white spaces
633              are  treated as  a part  of protocol string.
634
635              Default: h2,h2-16,h2-14,http/1.1
636
637       --verify-client
638              Require and verify client certificate.
639
640       --verify-client-cacert=<PATH>
641              Path  to file  that contains  CA certificates  to verify  client
642              certificate.   The  file  must be in PEM format.  It can contain
643              multiple certificates.
644
645       --verify-client-tolerate-expired
646              Accept  expired  client  certificate.   Operator  should  handle
647              the  expired   client  certificate  by some  means (e.g.,  mruby
648              script).   Otherwise, this  option  might cause a security risk.
649
650       --client-private-key-file=<PATH>
651              Path to  file that contains  client private key  used in backend
652              client authentication.
653
654       --client-cert-file=<PATH>
655              Path to  file that  contains client certificate  used in backend
656              client authentication.
657
658       --tls-min-proto-version=<VER>
659              Specify minimum SSL/TLS protocol.   The name matching is done in
660              case-insensitive      manner.      The      versions     between
661              --tls-min-proto-version  and   --tls-max-proto-version  are  en‐
662              abled.   If  the  protocol  list  advertised  by client does not
663              overlap  this range,  you  will  receive the  error message "un‐
664              known  protocol".   If  a protocol version lower than TLSv1.2 is
665              specified, make sure that the compatible ciphers  are   included
666              in --ciphers option.   The default cipher  list  only   includes
667              ciphers  compatible  with TLSv1.2 or above.  The available  ver‐
668              sions are: TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
669
670              Default: TLSv1.2
671
672       --tls-max-proto-version=<VER>
673              Specify maximum SSL/TLS protocol.   The name matching is done in
674              case-insensitive     manner.      The      versions      between
675              --tls-min-proto-version  and   --tls-max-proto-version  are  en‐
676              abled.  If the protocol  list  advertised  by  client  does  not
677              overlap  this range,  you  will  receive the  error message "un‐
678              known protocol".  The available versions are: TLSv1.3,  TLSv1.2,
679              TLSv1.1, and TLSv1.0
680
681              Default: TLSv1.3
682
683       --tls-ticket-key-file=<PATH>
684              Path to file that contains  random data to construct TLS session
685              ticket    parameters.    If    aes-128-cbc    is     given    in
686              --tls-ticket-key-cipher,  the   file  must   contain  exactly 48
687              bytes.       If        aes-256-cbc       is       given       in
688              --tls-ticket-key-cipher,  the   file  must   contain  exactly 80
689              bytes.   This  options  can be   used   repeatedly   to  specify
690              multiple ticket  parameters.  If  several files are given,  only
691              the  first key is  used to  encrypt TLS session  tickets.  Other
692              keys  are  accepted but  server will  issue new  session  ticket
693              with  first key.   This allows  session  key  rotation.   Please
694              note  that  key rotation  does  not  occur automatically.   User
695              should rearrange  files or  change options  values and   restart
696              nghttpx  gracefully.   If opening  or reading  given file fails,
697              all loaded  keys are discarded and  it is treated as if none  of
698              this  option is given.  If  this option is not given or an error
699              occurred while opening or reading a file,  key is  generated ev‐
700              ery   1  hour   internally  and  they  are  valid for  12 hours.
701              This is  recommended if ticket  key  sharing   between   nghttpx
702              instances is  not required.
703
704       --tls-ticket-key-memcached=<HOST>,<PORT>[;tls]
705              Specify  address   of  memcached  server to get  TLS ticket keys
706              for  session resumption.   This enables  shared TLS  ticket  key
707              between   multiple  nghttpx instances.  nghttpx does not set TLS
708              ticket  key to memcached.  The external ticket key generator  is
709              required.   nghttpx just gets TLS ticket  keys  from  memcached,
710              and  use  them,  possibly replacing current set  of keys.  It is
711              up   to  extern  TLS ticket  key generator  to rotate  keys fre‐
712              quently.   See "TLS SESSION  TICKET RESUMPTION" section in  man‐
713              ual  page  to  know the data format in memcached entry.  Option‐
714              ally, memcached  connection  can  be  encrypted  with   TLS   by
715              specifying "tls" parameter.
716
717       --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6)
718              Specify  address   family  of  memcached connections  to get TLS
719              ticket keys.  If "auto" is given, both IPv4 and IPv6 are consid‐
720              ered.    If  "IPv4"  is given,  only IPv4 address is considered.
721              If "IPv6" is given, only IPv6 address is considered.
722
723              Default: auto
724
725       --tls-ticket-key-memcached-interval=<DURATION>
726              Set interval to get TLS ticket keys from memcached.
727
728              Default: 10m
729
730       --tls-ticket-key-memcached-max-retry=<N>
731              Set  maximum   number  of  consecutive   retries   before  aban‐
732              doning  TLS  ticket  key  retrieval.  If this number is reached,
733              the  attempt  is considered  as  failure,  and  "failure"  count
734              is  incremented  by  1,   which  contributed  to             the
735              value            controlled  --tls-ticket-key-memcached-max-fail
736              option.
737
738              Default: 3
739
740       --tls-ticket-key-memcached-max-fail=<N>
741              Set   maximum    number   of  consecutive   failure  before dis‐
742              abling TLS ticket until next scheduled key retrieval.
743
744              Default: 2
745
746       --tls-ticket-key-cipher=<CIPHER>
747              Specify cipher  to encrypt TLS session  ticket.  Specify  either
748              aes-128-cbc    or   aes-256-cbc.    By   default, aes-128-cbc is
749              used.
750
751       --tls-ticket-key-memcached-cert-file=<PATH>
752              Path to client certificate  for memcached connections to get TLS
753              ticket keys.
754
755       --tls-ticket-key-memcached-private-key-file=<PATH>
756              Path to client private  key for memcached connections to get TLS
757              ticket keys.
758
759       --fetch-ocsp-response-file=<PATH>
760              Path to  fetch-ocsp-response script file.  It  should  be  abso‐
761              lute path.
762
763              Default: /usr/local/share/nghttp2/fetch-ocsp-response
764
765       --ocsp-update-interval=<DURATION>
766              Set interval to update OCSP response cache.
767
768              Default: 4h
769
770       --ocsp-startup
771              Start   accepting  connections   after  initial  attempts to get
772              OCSP responses  finish.  It does not  matter some  of  the   at‐
773              tempts   fail.   This   feature   is   useful if  OCSP responses
774              must    be   available    before   accepting connections.
775
776       --no-verify-ocsp
777              nghttpx does not verify OCSP response.
778
779       --no-ocsp
780              Disable OCSP stapling.
781
782       --tls-session-cache-memcached=<HOST>,<PORT>[;tls]
783              Specify  address of  memcached server  to store  session  cache.
784              This    enables     shared   session   cache   between  multiple
785              nghttpx  instances.    Optionally,  memcached connection can  be
786              encrypted with TLS by specifying "tls" parameter.
787
788       --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6)
789              Specify address family of memcached connections to store session
790              cache.  If  "auto" is given, both  IPv4 and IPv6 are considered.
791              If "IPv4" is given,  only IPv4 address is considered.  If "IPv6"
792              is given, only IPv6 address is considered.
793
794              Default: auto
795
796       --tls-session-cache-memcached-cert-file=<PATH>
797              Path to client certificate  for memcached connections  to  store
798              session cache.
799
800       --tls-session-cache-memcached-private-key-file=<PATH>
801              Path  to  client private  key for memcached connections to store
802              session cache.
803
804       --tls-dyn-rec-warmup-threshold=<SIZE>
805              Specify the  threshold size for TLS  dynamic record size  behav‐
806              iour.   During   a  TLS  session, after  the threshold number of
807              bytes  have been written, the  TLS record size will be increased
808              to  the  maximum  allowed (16K).  The max record size will  con‐
809              tinue  to  be  used  on   the   active   TLS   session.    After
810              --tls-dyn-rec-idle-timeout  has  elapsed, the record size is re‐
811              duced  to 1300 bytes.  Specify 0  to  always  use   the  maximum
812              record  size,  regardless of idle period.   This  behaviour  ap‐
813              plies   to  all  TLS  based frontends, and TLS HTTP/2 backends.
814
815              Default: 1M
816
817       --tls-dyn-rec-idle-timeout=<DURATION>
818              Specify  TLS  dynamic  record   size  behaviour  timeout.    See
819              --tls-dyn-rec-warmup-threshold   for    more  information.  This
820              behaviour  applies to all TLS  based frontends, and  TLS  HTTP/2
821              backends.
822
823              Default: 1s
824
825       --no-http2-cipher-block-list
826              Allow  block  listed  cipher suite  on  frontend  HTTP/2 connec‐
827              tion.                                                        See
828              https://tools.ietf.org/html/rfc7540#appendix-A   for   the  com‐
829              plete HTTP/2 cipher suites block list.
830
831       --client-no-http2-cipher-block-list
832              Allow  block  listed  cipher  suite  on  backend  HTTP/2 connec‐
833              tion.                                                        See
834              https://tools.ietf.org/html/rfc7540#appendix-A   for   the  com‐
835              plete HTTP/2 cipher suites block list.
836
837       --tls-sct-dir=<DIR>
838              Specifies  the   directory where  *.sct files  exist.  All *.sct
839              files   in  <DIR>   are   read,   and  sent   as  extension_data
840              of   TLS  signed_certificate_timestamp  (RFC  6962)  to  client.
841              These   *.sct  files  are  for  the certificate   specified   in
842              positional    command-line  argument <CERT>, or  certificate op‐
843              tion in configuration file.    For    additional   certificates,
844              use  --subcert option.  This option requires OpenSSL >= 1.0.2.
845
846       --psk-secrets=<PATH>
847              Read list of PSK identity and secrets from <PATH>.  This is used
848              for frontend connection.  The each line of input file  is   for‐
849              matted   as   <identity>:<hex-secret>,  where <identity> is  PSK
850              identity, and <hex-secret>  is secret in hex.  An   empty  line,
851              and  line  which  starts with '#' are skipped.  The default  en‐
852              abled cipher list might not contain any PSK  cipher  suite.   In
853              that  case,  desired  PSK  cipher suites  must be  enabled using
854              --ciphers option.  The  desired PSK  cipher suite  may be  block
855              listed   by  HTTP/2.    To   use   those    cipher  suites  with
856              HTTP/2, consider  to  use  --no-http2-cipher-block-list  option.
857              But be aware its implications.
858
859       --client-psk-secrets=<PATH>
860              Read  PSK  identity  and  secrets from <PATH>.  This is used for
861              backend connection.  The each  line of input file  is  formatted
862              as  <identity>:<hex-secret>,   where <identity> is PSK identity,
863              and <hex-secret>  is secret in hex.  An  empty  line,  and  line
864              which  starts with '#' are skipped.  The first identity and  se‐
865              cret pair encountered is  used.   The  default   enabled  cipher
866              list  might not  contain any PSK  cipher suite.   In  that case,
867              desired   PSK    cipher   suites    must   be    enabled   using
868              --client-ciphers option.  The  desired PSK  cipher suite  may be
869              block listed  by HTTP/2.   To  use  those   cipher  suites  with
870              HTTP/2, consider   to  use   --client-no-http2-cipher-block-list
871              option.  But be aware its implications.
872
873       --tls-no-postpone-early-data
874              By  default,   except  for  QUIC   connections,   nghttpx  post‐
875              pones  forwarding   HTTP requests sent in  early data, including
876              those  sent in  partially  in  it, until   TLS  handshake   fin‐
877              ishes.   If  all backend  server recognizes "Early-Data"  header
878              field,  using  this  option  makes nghttpx  not  postpone   for‐
879              warding request  and get  full potential of 0-RTT data.
880
881       --tls-max-early-data=<SIZE>
882              Sets   the   maximum   amount   of 0-RTT  data  that  server ac‐
883              cepts.
884
885              Default: 16K
886
887       --tls-ktls
888              Enable    ktls.     For    server,   ktls    is    enable     if
889              --tls-session-cache-memcached is not configured.
890
891   HTTP/2
892       -c, --frontend-http2-max-concurrent-streams=<N>
893              Set  the maximum number of  the concurrent streams in one front‐
894              end HTTP/2 session.
895
896              Default: 100
897
898       --backend-http2-max-concurrent-streams=<N>
899              Set the maximum number of  the concurrent streams in one backend
900              HTTP/2  session.    This  sets   maximum  number   of concurrent
901              opened pushed streams.  The maximum  number  of  concurrent  re‐
902              quests are set by a remote server.
903
904              Default: 100
905
906       --frontend-http2-window-size=<SIZE>
907              Sets   the  per-stream  initial  window  size  of  HTTP/2 front‐
908              end connection.
909
910              Default: 65535
911
912       --frontend-http2-connection-window-size=<SIZE>
913              Sets the  per-connection window size of  HTTP/2 frontend connec‐
914              tion.
915
916              Default: 65535
917
918       --backend-http2-window-size=<SIZE>
919              Sets  the   initial  window   size  of   HTTP/2  backend connec‐
920              tion.
921
922              Default: 65535
923
924       --backend-http2-connection-window-size=<SIZE>
925              Sets the  per-connection window  size of  HTTP/2 backend connec‐
926              tion.
927
928              Default: 2147483647
929
930       --http2-no-cookie-crumbling
931              Don't crumble cookie header field.
932
933       --padding=<N>
934              Add   at  most   <N> bytes  to  a HTTP/2  frame payload  as pad‐
935              ding.  Specify 0 to  disable padding.  This option is meant  for
936              debugging  purpose   and  not intended to enhance protocol secu‐
937              rity.
938
939       --no-server-push
940              Disable HTTP/2 server push.  Server push is supported by default
941              mode  and  HTTP/2   frontend via Link header field.  It is  also
942              supported if  both frontend and  backend are HTTP/2  in  default
943              mode.   In   this  case, server push from backend session is re‐
944              layed  to frontend, and server push via  Link  header  field  is
945              also supported.
946
947       --frontend-http2-optimize-write-buffer-size
948              (Experimental)  Enable write  buffer size optimization in front‐
949              end HTTP/2 TLS  connection.  This optimization  aims  to  reduce
950              write  buffer   size so  that it  only contains bytes  which can
951              send immediately.   This makes  server more responsive to prior‐
952              itized  HTTP/2  stream because the buffering  of lower  priority
953              stream  is reduced.   This option is only  effective  on  recent
954              Linux platform.
955
956       --frontend-http2-optimize-window-size
957              (Experimental)    Automatically  tune   connection  level window
958              size of frontend  HTTP/2 TLS connection.   If  this  feature  is
959              enabled, connection window size  starts with the   default  win‐
960              dow   size,   65535  bytes.     nghttpx  automatically   adjusts
961              connection   window  size   based on TCP receiving  window size.
962              The maximum  window size is capped       by       the      value
963              specified         by    --frontend-http2-connection-window-size.
964              Since   the stream is subject to stream level  window  size,  it
965              should  be adjusted using --frontend-http2-window-size option as
966              well.   This option  is only  effective on  recent  Linux  plat‐
967              form.
968
969       --frontend-http2-encoder-dynamic-table-size=<SIZE>
970              Specify  the maximum dynamic  table size of HPACK encoder in the
971              frontend HTTP/2 connection.  The decoder (client) specifies  the
972              maximum   dynamic  table  size it  accepts.  Then the negotiated
973              dynamic table size is the minimum of this option value  and  the
974              value which client specified.
975
976              Default: 4K
977
978       --frontend-http2-decoder-dynamic-table-size=<SIZE>
979              Specify  the maximum dynamic  table size of HPACK decoder in the
980              frontend HTTP/2 connection.
981
982              Default: 4K
983
984       --backend-http2-encoder-dynamic-table-size=<SIZE>
985              Specify the maximum dynamic  table size of HPACK encoder in  the
986              backend HTTP/2 connection.  The decoder (backend) specifies  the
987              maximum  dynamic table  size it  accepts.  Then  the  negotiated
988              dynamic  table  size is the minimum of this option value and the
989              value which backend specified.
990
991              Default: 4K
992
993       --backend-http2-decoder-dynamic-table-size=<SIZE>
994              Specify the maximum dynamic  table size of HPACK decoder in  the
995              backend HTTP/2 connection.
996
997              Default: 4K
998
999   Mode
1000       (default mode)
1001              Accept  HTTP/2,  and  HTTP/1.1 over  SSL/TLS.   "no-tls" parame‐
1002              ter is  used in  --frontend option,  accept HTTP/2 and  HTTP/1.1
1003              over  cleartext  TCP.  The incoming HTTP/1.1 connection  can  be
1004              upgraded  to  HTTP/2  through  HTTP Upgrade.
1005
1006       -s, --http2-proxy
1007              Like default mode, but enable forward proxy.  This is so  called
1008              HTTP/2 proxy mode.
1009
1010   Logging
1011       -L, --log-level=<LEVEL>
1012              Set  the severity  level of log output.   <LEVEL> must be one of
1013              INFO, NOTICE, WARN, ERROR and FATAL.
1014
1015              Default: NOTICE
1016
1017       --accesslog-file=<PATH>
1018              Set path to write access log.  To reopen file, send USR1  signal
1019              to nghttpx.
1020
1021       --accesslog-syslog
1022              Send   access  log   to  syslog.    If  this   option  is  used,
1023              --accesslog-file option is ignored.
1024
1025       --accesslog-format=<FORMAT>
1026              Specify  format  string  for access  log.   The  default  format
1027              is combined format.   The following variables are available:
1028
1029              • $remote_addr: client IP address.
1030
1031              • $time_local: local time in Common Log format.
1032
1033              • $time_iso8601: local time in ISO 8601 format.
1034
1035              • $request: HTTP request line.
1036
1037              • $status: HTTP response status code.
1038
1039              • $body_bytes_sent:  the  number of bytes sent  to client as re‐
1040                sponse body.
1041
1042              • $http_<VAR>: value of HTTP  request header <VAR> where '_'  in
1043                <VAR> is replaced with '-'.
1044
1045              • $remote_port: client  port.
1046
1047              • $server_port: server port.
1048
1049              • $request_time:  request  processing  time in seconds with mil‐
1050                liseconds resolution.
1051
1052              • $pid: PID of the running process.
1053
1054              • $alpn: ALPN identifier of the protocol which generates the re‐
1055                sponse.   For HTTP/1,  ALPN is  always http/1.1, regardless of
1056                minor version.
1057
1058              • $tls_cipher: cipher used for SSL/TLS connection.
1059
1060              • $tls_client_fingerprint_sha256: SHA-256 fingerprint of  client
1061                certificate.
1062
1063              • $tls_client_fingerprint_sha1:   SHA-1   fingerprint  of client
1064                certificate.
1065
1066              • $tls_client_subject_name:   subject  name    in   client  cer‐
1067                tificate.
1068
1069              • $tls_client_issuer_name:    issuer    name    in   client cer‐
1070                tificate.
1071
1072              • $tls_client_serial:    serial    number    in     client  cer‐
1073                tificate.
1074
1075              • $tls_protocol: protocol for SSL/TLS connection.
1076
1077              • $tls_session_id: session ID for SSL/TLS connection.
1078
1079              • $tls_session_reused:  "r"   if  SSL/TLS   session  was reused.
1080                Otherwise, "."
1081
1082              • $tls_sni: SNI server name for SSL/TLS connection.
1083
1084              • $backend_host:  backend  host   used   to   fulfill   the  re‐
1085                quest.  "-" if backend host is not available.
1086
1087              • $backend_port:   backend   port    used   to  fulfill  the re‐
1088                quest.  "-" if backend host is not available.
1089
1090              • $method: HTTP method
1091
1092              • $path:  Request  path  including  query.    For   CONNECT  re‐
1093                quest, authority is recorded.
1094
1095              • $path_without_query:  $path   up  to  the   first  '?' charac‐
1096                ter.    For   CONNECT  request,   authority   is recorded.
1097
1098              • $protocol_version:   HTTP  version   (e.g.,  HTTP/1.1, HTTP/2)
1099
1100              The  variable  can  be  enclosed  by  "{"  and  "}"  for  disam‐
1101              biguation (e.g., ${remote_addr}).
1102
1103              Default:  $remote_addr  -  -  [$time_local]  "$request"  $status
1104              $body_bytes_sent "$http_referer" "$http_user_agent"
1105
1106       --accesslog-write-early
1107              Write  access  log  when   response   header   fields   are  re‐
1108              ceived    from  backend   rather   than  when   request transac‐
1109              tion finishes.
1110
1111       --errorlog-file=<PATH>
1112              Set path to write error  log.  To reopen file, send USR1  signal
1113              to  nghttpx.   stderr will  be redirected  to the error log file
1114              unless --errorlog-syslog is used.
1115
1116              Default: /dev/stderr
1117
1118       --errorlog-syslog
1119              Send  error  log   to   syslog.   If   this   option  is   used,
1120              --errorlog-file option is ignored.
1121
1122       --syslog-facility=<FACILITY>
1123              Set syslog facility to <FACILITY>.
1124
1125              Default: daemon
1126
1127   HTTP
1128       --add-x-forwarded-for
1129              Append   X-Forwarded-For  header   field  to  the downstream re‐
1130              quest.
1131
1132       --strip-incoming-x-forwarded-for
1133              Strip X-Forwarded-For  header field  from   inbound  client  re‐
1134              quests.
1135
1136       --no-add-x-forwarded-proto
1137              Don't append  additional X-Forwarded-Proto  header field to  the
1138              backend   request.     If    inbound     client    sets   X-For‐
1139              warded-Proto,                                                and
1140              --no-strip-incoming-x-forwarded-proto  option   is   used,  they
1141              are passed to the backend.
1142
1143       --no-strip-incoming-x-forwarded-proto
1144              Don't  strip X-Forwarded-Proto  header field from inbound client
1145              requests.
1146
1147       --add-forwarded=<LIST>
1148              Append RFC  7239 Forwarded header field  with parameters  speci‐
1149              fied  in  comma delimited list <LIST>.  The supported parameters
1150              are "by",  "for", "host",  and "proto".   By default,  the value
1151              of   "by"  and   "for"  parameters   are  obfuscated     string.
1152              See     --forwarded-by    and  --forwarded-for  options  respec‐
1153              tively.   Note  that  nghttpx  does  not  translate non-standard
1154              X-Forwarded-*  header fields into Forwarded  header  field,  and
1155              vice versa.
1156
1157       --strip-incoming-forwarded
1158              Strip   Forwarded    header   field   from   inbound  client re‐
1159              quests.
1160
1161       --forwarded-by=(obfuscated|ip|<VALUE>)
1162              Specify the parameter value sent out with "by" parameter of For‐
1163              warded  header field.   If "obfuscated"  is given, the string is
1164              randomly generated at startup.  If "ip" is given,   the   inter‐
1165              face    address  of   the  connection, including port number, is
1166              sent with "by" parameter.  In case of UNIX domain  socket,  "lo‐
1167              calhost"  is  used  instead of address and  port.  User can also
1168              specify the static obfuscated string.  The limitation is that it
1169              must  start  with    "_",  and   only   consists   of  character
1170              set [A-Za-z0-9._-], as described in RFC 7239.
1171
1172              Default: obfuscated
1173
1174       --forwarded-for=(obfuscated|ip)
1175              Specify  the   parameter  value  sent  out   with  "for" parame‐
1176              ter  of  Forwarded  header field.  If "obfuscated" is given, the
1177              string is  randomly generated for each  client  connection.   If
1178              "ip"  is  given,  the  remote client address of  the connection,
1179              without port  number, is  sent with "for"  parameter.   In  case
1180              of   UNIX   domain   socket,  "localhost" is used instead of ad‐
1181              dress.
1182
1183              Default: obfuscated
1184
1185       --no-via
1186              Don't append to  Via header field.  If  Via header field is  re‐
1187              ceived, it is left unaltered.
1188
1189       --no-strip-incoming-early-data
1190              Don't  strip  Early-Data  header   field from inbound client re‐
1191              quests.
1192
1193       --no-location-rewrite
1194              Don't  rewrite location  header field  in default   mode.   When
1195              --http2-proxy   is  used, location header  field will not be al‐
1196              tered regardless of this option.
1197
1198       --host-rewrite
1199              Rewrite  host and  :authority header  fields in   default  mode.
1200              When  --http2-proxy is  used, these  headers will not be altered
1201              regardless of this option.
1202
1203       --altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1204              Specify   protocol  ID,   port,  host   and  origin   of  alter‐
1205              native  service.   <HOST>,   <ORIGIN> and <PARAMS> are optional.
1206              Empty <HOST>  and <ORIGIN>  are allowed  and they   are  treated
1207              as   nothing  is   specified.   They  are advertised  in alt-svc
1208              header  field  only in  HTTP/1.1 frontend.   This option  can be
1209              used  multiple   times to specify multiple alternative services.
1210              Example: --altsvc="h2,443,,,ma=3600; persist=1"
1211
1212       --http2-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1213              Just like --altsvc option, but  this  altsvc  is  only  sent  in
1214              HTTP/2 frontend.
1215
1216       --add-request-header=<HEADER>
1217              Specify  additional  header  field to add to request header set.
1218              This  option just  appends header field  and won't replace  any‐
1219              thing   already  set.   This  option  can be used several  times
1220              to     specify     multiple      header     fields.     Example:
1221              --add-request-header="foo: bar"
1222
1223       --add-response-header=<HEADER>
1224              Specify   additional  header  field to  add  to  response header
1225              set.   This option just appends  header field and won't  replace
1226              anything  already   set.  This option can be used several  times
1227              to     specify    multiple      header     fields.      Example:
1228              --add-response-header="foo: bar"
1229
1230       --request-header-field-buffer=<SIZE>
1231              Set  maximum  buffer size for incoming HTTP request header field
1232              list.  This is the sum of header name and value in  bytes.    If
1233              trailer  fields  exist,  they  are  counted towards this number.
1234
1235              Default: 64K
1236
1237       --max-request-header-fields=<N>
1238              Set  maximum  number  of incoming  HTTP  request  header fields.
1239              If  trailer  fields exist,  they  are  counted towards this num‐
1240              ber.
1241
1242              Default: 100
1243
1244       --response-header-field-buffer=<SIZE>
1245              Set   maximum  buffer  size for  incoming  HTTP  response header
1246              field list.   This is the sum of   header  name  and  value   in
1247              bytes.   If   trailer   fields  exist, they  are counted towards
1248              this number.
1249
1250              Default: 64K
1251
1252       --max-response-header-fields=<N>
1253              Set  maximum number  of  incoming  HTTP response  header fields.
1254              If  trailer  fields exist,  they  are  counted towards this num‐
1255              ber.
1256
1257              Default: 500
1258
1259       --error-page=(<CODE>|*)=<PATH>
1260              Set file path  to custom error page  served when nghttpx  origi‐
1261              nally  generates  HTTP  error status  code  <CODE>.  <CODE> must
1262              be greater than or equal to 400, and at most 599.   If  "*"   is
1263              used  instead of <CODE>,  it matches all HTTP  status  code.  If
1264              error  status  code comes  from backend server, the custom error
1265              pages are not used.
1266
1267       --server-name=<NAME>
1268              Change server response header field value to <NAME>.
1269
1270              Default: nghttpx
1271
1272       --no-server-rewrite
1273              Don't  rewrite  server  header  field  in  default  mode.   When
1274              --http2-proxy is used, these headers will not be altered regard‐
1275              less of this option.
1276
1277       --redirect-https-port=<PORT>
1278              Specify  the  port number which appears in Location header field
1279              when  redirect   to   HTTPS   URI   is   made   due   to  "redi‐
1280              rect-if-not-tls" parameter in --backend option.
1281
1282              Default: 443
1283
1284       --require-http-scheme
1285              Always  require  http  or https scheme in HTTP request.  It also
1286              requires that  https scheme  must be   used  for   an  encrypted
1287              connection.  Otherwise,  http scheme  must be used.   This   op‐
1288              tion  is   recommended  for   a   server  deployment  which  di‐
1289              rectly  faces  clients and the services it provides only require
1290              http or https scheme.
1291
1292   API
1293       --api-max-request-body=<SIZE>
1294              Set the maximum size of request body for API request.
1295
1296              Default: 32M
1297
1298   DNS
1299       --dns-cache-timeout=<DURATION>
1300              Set duration that cached DNS results remain  valid.   Note  that
1301              nghttpx caches the unsuccessful results as well.
1302
1303              Default: 10s
1304
1305       --dns-lookup-timeout=<DURATION>
1306              Set timeout that  DNS server is given to  respond to the initial
1307              DNS  query.  For  the  2nd  and later  queries, server is  given
1308              time based  on this timeout, and  it is scaled linearly.
1309
1310              Default: 5s
1311
1312       --dns-max-try=<N>
1313              Set the number of DNS query before nghttpx gives up name lookup.
1314
1315              Default: 2
1316
1317       --frontend-max-requests=<N>
1318              The  number   of  requests  that single  frontend connection can
1319              process.  For HTTP/2, this  is the number  of  streams  in   one
1320              HTTP/2  connection.    For  HTTP/1,  this is  the number of keep
1321              alive requests.  This is hint to nghttpx, and it  may allow  ad‐
1322              ditional few  requests.  The default value is unlimited.
1323
1324   Debug
1325       --frontend-http2-dump-request-header=<PATH>
1326              Dumps  request  headers  received by HTTP/2 frontend to the file
1327              denoted  in <PATH>.  The  output is done  in HTTP/1 header field
1328              format and each header block is followed by an empty line.  This
1329              option  is not thread safe and MUST  NOT  be  used  with  option
1330              -n<N>, where <N> >= 2.
1331
1332       --frontend-http2-dump-response-header=<PATH>
1333              Dumps  response  headers  sent  from HTTP/2 frontend to the file
1334              denoted  in <PATH>.  The  output is done  in HTTP/1 header field
1335              format and each header block is followed by an empty line.  This
1336              option  is not thread safe and MUST  NOT  be  used  with  option
1337              -n<N>, where <N> >= 2.
1338
1339       -o, --frontend-frame-debug
1340              Print HTTP/2 frames in  frontend to stderr.  This option is  not
1341              thread  safe and  MUST NOT  be used  with option -n=N,  where  N
1342              >= 2.
1343
1344   Process
1345       -D, --daemon
1346              Run  in a background.  If -D is used, the current working direc‐
1347              tory is changed to '/'.
1348
1349       --pid-file=<PATH>
1350              Set path to save PID of this program.
1351
1352       --user=<USER>
1353              Run this program as <USER>.   This option is intended to be used
1354              to drop root privileges.
1355
1356       --single-process
1357              Run  this  program  in a  single process mode for debugging pur‐
1358              pose.  Without this option,  nghttpx creates  at  least  2  pro‐
1359              cesses:  main  and   worker processes.  If this option is  used,
1360              main   and   worker  are   unified   into  a   single   process.
1361              nghttpx  still   spawns   additional  process  if neverbleed  is
1362              used.   In the  single process  mode, the signal  handling  fea‐
1363              ture is disabled.
1364
1365       --max-worker-processes=<N>
1366              The  maximum  number  of   worker processes.  nghttpx spawns new
1367              worker  process when  it reloads  its configuration.  The previ‐
1368              ous  worker  process enters graceful termination period and will
1369              terminate  when it finishes  handling  the  existing     connec‐
1370              tions.      However,     if     reloading configurations  happen
1371              very  frequently,   the  worker processes might be piled  up  if
1372              they  take  a bit long time to finish  the existing connections.
1373              With  this option, if  the number  of  worker processes  exceeds
1374              the   given value,   the  oldest   worker   process  is   termi‐
1375              nated immediately.  Specifying 0 means no  limit and it  is  the
1376              default behaviour.
1377
1378       --worker-process-grace-shutdown-period=<DURATION>
1379              Maximum   period  for  a   worker  process  to  terminate grace‐
1380              fully.  When  a worker  process  enters   in  graceful  shutdown
1381              period   (e.g.,    when   nghttpx    reloads  its configuration)
1382              and  it  does not  finish  handling  the existing connections in
1383              the given  period of time, it is immediately terminated.  Speci‐
1384              fying 0 means no limit and it is the default behaviour.
1385
1386   Scripting
1387       --mruby-file=<PATH>
1388              Set mruby script file
1389
1390       --ignore-per-pattern-mruby-error
1391              Ignore mruby compile error  for per-pattern mruby  script  file.
1392              If  error   occurred,  it  is  treated as  if no mruby file were
1393              specified for the pattern.
1394
1395   HTTP/3 and QUIC
1396       --frontend-quic-idle-timeout=<DURATION>
1397              Specify an idle timeout for QUIC connection.
1398
1399              Default: 30s
1400
1401       --frontend-quic-debug-log
1402              Output QUIC debug log to /dev/stderr.
1403
1404       --quic-bpf-program-file=<PATH>
1405              Specify a path to  eBPF program file reuseport_kern.o to  direct
1406              an  incoming  QUIC  UDP datagram  to  a  correct socket.
1407
1408              Default: /usr/local/lib/nghttp2/reuseport_kern.o
1409
1410       --frontend-quic-early-data
1411              Enable  early  data on frontend QUIC connections.  nghttpx sends
1412              "Early-Data" header field to a backend server if  a  request  is
1413              received  in  early   data  and handshake has not finished.  All
1414              backend servers should deal with possibly replayed requests.
1415
1416       --frontend-quic-qlog-dir=<DIR>
1417              Specify a  directory where  a qlog  file is  written for  front‐
1418              end  QUIC   connections.   A qlog file  is created per each QUIC
1419              connection.  The  file name is  ISO8601 basic  format,  followed
1420              by "-", server Source Connection ID and ".sqlog".
1421
1422       --frontend-quic-require-token
1423              Require an address validation  token for a frontend QUIC connec‐
1424              tion.   Server sends  a token  in  Retry   packet  or  NEW_TOKEN
1425              frame in the previous connection.
1426
1427       --frontend-quic-congestion-controller=<CC>
1428              Specify  a  congestion  controller algorithm for a frontend QUIC
1429              connection.  <CC> should  be one of "cubic", "bbr", and "bbr2".
1430
1431              Default: cubic
1432
1433       --frontend-quic-secret-file=<PATH>
1434              Path to file that contains secure random data to be used as QUIC
1435              keying  materials.  It is used to derive keys for encrypting to‐
1436              kens and Connection IDs.  It is not used to encrypt  QUIC  pack‐
1437              ets.   Each   line   of   this  file  must contain  exactly  136
1438              bytes  hex-encoded  string  (when decoded the byte string is  68
1439              bytes  long).   The  first  2  bits of  decoded byte  string are
1440              used to  identify the keying material.   An   empty  line  or  a
1441              line which starts '#'  is ignored.   The file  can contain  more
1442              than  one keying materials.  Because the  identifier is 2  bits,
1443              at  most  4 keying materials are  read and the remaining data is
1444              discarded.  The first keying  material in the file is  primarily
1445              used  for   encryption and  decryption for  new connection.  The
1446              other ones are used to decrypt data for  the   existing  connec‐
1447              tions.    Specifying multiple  keying materials enables  key ro‐
1448              tation.   Please note  that key rotation  does  not  occur auto‐
1449              matically.    User   should  update   files  or  change  options
1450              values  and  restart nghttpx gracefully.   If opening  or  read‐
1451              ing   given  file  fails,  all loaded keying  materials are dis‐
1452              carded and it is treated as if none of  this  option  is  given.
1453              If this option is not  given or an error  occurred while opening
1454              or  reading  a  file,  a keying  material  is  generated  inter‐
1455              nally on startup and reload.
1456
1457       --quic-server-id=<HEXSTRING>
1458              Specify  server   ID  encoded in Connection  ID to identify this
1459              particular  server  instance.   Connection  ID  is encrypted and
1460              this  part is  not visible in  public.  It must be 4  bytes long
1461              and must be encoded  in hex string (which is 8  bytes long).  If
1462              this  option  is omitted, a random   server  ID   is   generated
1463              on  startup   and configuration reload.
1464
1465       --frontend-quic-initial-rtt=<DURATION>
1466              Specify the initial RTT of the frontend QUIC connection.
1467
1468              Default: 333ms
1469
1470       --no-quic-bpf
1471              Disable eBPF.
1472
1473       --frontend-http3-window-size=<SIZE>
1474              Sets  the  per-stream  initial  window  size  of  HTTP/3  front‐
1475              end connection.
1476
1477              Default: 256K
1478
1479       --frontend-http3-connection-window-size=<SIZE>
1480              Sets the  per-connection window size of  HTTP/3 frontend connec‐
1481              tion.
1482
1483              Default: 1M
1484
1485       --frontend-http3-max-window-size=<SIZE>
1486              Sets  the  maximum  per-stream  window  size  of  HTTP/3  front‐
1487              end  connection.   The window  size is adjusted based on the re‐
1488              ceiving rate of stream data.  The initial value  is  the   value
1489              specified   by  --frontend-http3-window-size and the window size
1490              grows up to <SIZE> bytes.
1491
1492              Default: 6M
1493
1494       --frontend-http3-max-connection-window-size=<SIZE>
1495              Sets the  maximum per-connection  window size  of HTTP/3  front‐
1496              end  connection.   The window  size is adjusted based on the re‐
1497              ceiving rate of stream data.  The initial value  is          the
1498              value                        specified                        by
1499              --frontend-http3-connection-window-size  and  the   window  size
1500              grows up to <SIZE> bytes.
1501
1502              Default: 8M
1503
1504       --frontend-http3-max-concurrent-streams=<N>
1505              Set  the maximum number of  the concurrent streams in one front‐
1506              end HTTP/3 connection.
1507
1508              Default: 100
1509
1510   Misc
1511       --conf=<PATH>
1512              Load  configuration  from   <PATH>.   Please  note  that nghttpx
1513              always   tries to read the  default configuration file if --conf
1514              is not given.
1515
1516              Default: /etc/nghttpx/nghttpx.conf
1517
1518       --include=<PATH>
1519              Load additional configurations  from  <PATH>.   File  <PATH>  is
1520              read   when   configuration   parser   encountered  this option.
1521              This option can be used multiple times, or even recursively.
1522
1523       -v, --version
1524              Print version and exit.
1525
1526       -h, --help
1527              Print this help and exit.
1528
1529       The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
1530       * 1024).  Units are K, M and G (powers of 1024).
1531
1532       The <DURATION> argument is an integer and an optional unit (e.g., 1s is
1533       1 second and 500ms is 500 milliseconds).  Units  are  h,  m,  s  or  ms
1534       (hours, minutes, seconds and milliseconds, respectively).  If a unit is
1535       omitted, a second is used as unit.
1536

FILES

1538       /etc/nghttpx/nghttpx.conf
1539              The default configuration file path nghttpx searches at startup.
1540              The configuration file path can be changed using --conf option.
1541
1542              Those lines which are staring # are treated as comment.
1543
1544              The  option  name  in  the  configuration  file is the long com‐
1545              mand-line option name with leading -- stripped (e.g., frontend).
1546              Put = between option name and value.  Don't put extra leading or
1547              trailing spaces.
1548
1549              When specifying arguments including characters which  have  spe‐
1550              cial  meaning  to  a  shell, we usually use quotes so that shell
1551              does not interpret them.  When writing this configuration  file,
1552              quotes  for this purpose must not be used.  For example, specify
1553              additional request header field, do this:
1554
1555                 add-request-header=foo: bar
1556
1557              instead of:
1558
1559                 add-request-header="foo: bar"
1560
1561              The options which do not take argument in the command-line  take
1562              argument  in the configuration file.  Specify yes as an argument
1563              (e.g., http2-proxy=yes).  If other string is given,  it  is  ig‐
1564              nored.
1565
1566              To  specify  private key and certificate file which are given as
1567              positional arguments in command-line, use  private-key-file  and
1568              certificate-file.
1569
1570              --conf  option cannot be used in the configuration file and will
1571              be ignored if specified.
1572
1573       Error log
1574              Error log is written to stderr by default.  It can be configured
1575              using --errorlog-file.  The format of log message is as follows:
1576
1577              <datetime>  <main-pid> <current-pid> <thread-id> <level> (<file‐
1578              name>:<line>) <msg>
1579
1580              <datetime>
1581                     It is a combination of date and  time  when  the  log  is
1582                     written.  It is in ISO 8601 format.
1583
1584              <main-pid>
1585                     It is a main process ID.
1586
1587              <current-pid>
1588                     It is a process ID which writes this log.
1589
1590              <thread-id>
1591                     It  is  a  thread  ID which writes this log.  It would be
1592                     unique within <current-pid>.
1593
1594              <filename> and <line>
1595                     They are source file name, and line number which  produce
1596                     this log.
1597
1598              <msg>  It is a log message body.
1599

SIGNALS

1601       SIGQUIT
1602              Shutdown  gracefully.  First accept pending connections and stop
1603              accepting  connection.   After  all  connections  are   handled,
1604              nghttpx exits.
1605
1606       SIGHUP Reload configuration file given in --conf.
1607
1608       SIGUSR1
1609              Reopen log files.
1610
1611       SIGUSR2
1612          Fork  and  execute  nghttpx.  It will execute the binary in the same
1613          path with same command-line arguments and environment variables.  As
1614          of nghttpx version 1.20.0, the new main process sends SIGQUIT to the
1615          original main process when it is ready to serve requests.   For  the
1616          earlier  versions of nghttpx, user has to send SIGQUIT to the origi‐
1617          nal main process.
1618
1619          The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
1620          is usually used to execute new binary, and the main process is newly
1621          spawned.  On the other hand, the latter just  reloads  configuration
1622          file, and the same main process continues to exist.
1623
1624       NOTE:
1625          nghttpx  consists  of multiple processes: one process for processing
1626          these signals, and another one for processing requests.  The  former
1627          spawns  the latter.  The former is called main process, and the lat‐
1628          ter is called worker process.  If neverbleed is enabled, the  worker
1629          process spawns neverbleed daemon process which does RSA key process‐
1630          ing.  The above signal must be sent to the  main  process.   If  the
1631          other processes received one of them, it is ignored.  This behaviour
1632          of these processes may change  in  the  future  release.   In  other
1633          words,  in the future release, the processes other than main process
1634          may terminate upon the reception of these signals.  Therefore  these
1635          signals should not be sent to the processes other than main process.
1636

SERVER PUSH

1638       nghttpx  supports  HTTP/2  server push in default mode with Link header
1639       field.  nghttpx looks for Link header  field  (RFC  5988)  in  response
1640       headers  from  backend server and extracts URI-reference with parameter
1641       rel=preload (see preload) and pushes those URIs to the frontend client.
1642       Here is a sample Link header field to initiate server push:
1643
1644          Link: </fonts/font.woff>; rel=preload
1645          Link: </css/theme.css>; rel=preload
1646
1647       Currently, the following restriction is applied for server push:
1648
1649       1. The associated stream must have method "GET" or "POST".  The associ‐
1650          ated stream's status code must be 200.
1651
1652       This limitation may be loosened in the future release.
1653
1654       nghttpx also supports server push if  both  frontend  and  backend  are
1655       HTTP/2  in  default mode.  In this case, in addition to server push via
1656       Link header field, server push from backend is  forwarded  to  frontend
1657       HTTP/2 session.
1658
1659       HTTP/2 server push will be disabled if --http2-proxy is used.
1660

UNIX DOMAIN SOCKET

1662       nghttpx  supports  UNIX domain socket with a filename for both frontend
1663       and backend connections.
1664
1665       Please note that current  nghttpx  implementation  does  not  delete  a
1666       socket  with  a filename.  And on start up, if nghttpx detects that the
1667       specified socket already exists  in  the  file  system,  nghttpx  first
1668       deletes it.  However, if SIGUSR2 is used to execute new binary and both
1669       old and new configurations use  same  filename,  new  binary  does  not
1670       delete the socket and continues to use it.
1671

OCSP STAPLING

1673       OCSP  query  is  done using external Python script fetch-ocsp-response,
1674       which has been originally developed in Perl as part of h2o  project  (‐
1675       https://github.com/h2o/h2o), and was translated into Python.
1676
1677       The script file is usually installed under $(prefix)/share/nghttp2/ di‐
1678       rectory.   The  actual  path  to  script  can   be   customized   using
1679       --fetch-ocsp-response-file option.
1680
1681       If  OCSP  query is failed, previous OCSP response, if any, is continued
1682       to be used.
1683
1684       --fetch-ocsp-response-file option provides wide range of possibility to
1685       manage  OCSP  response.  It can take an arbitrary script or executable.
1686       The requirement is that  it  supports  the  command-line  interface  of
1687       fetch-ocsp-response script, and it must return a valid DER encoded OCSP
1688       response on success.  It must return exit code 0 on success, and 75 for
1689       temporary  error,  and  the  other error code for generic failure.  For
1690       large cluster of servers, it is not efficient for each server  to  per‐
1691       form  OCSP  query using fetch-ocsp-response.  Instead, you can retrieve
1692       OCSP response in some way, and store it in a disk or a shared database.
1693       Then  specify  a program in --fetch-ocsp-response-file to fetch it from
1694       those stores.  This could provide a way to share the OCSP response  be‐
1695       tween fleet of servers, and also any OCSP query strategy can be applied
1696       which may be beyond the ability of  nghttpx  itself  or  fetch-ocsp-re‐
1697       sponse script.
1698

TLS SESSION RESUMPTION

1700       nghttpx  supports  TLS  session  resumption through both session ID and
1701       session ticket.
1702
1703   SESSION ID RESUMPTION
1704       By default, session ID is shared by all worker threads.
1705
1706       If --tls-session-cache-memcached is given, nghttpx will insert  serial‐
1707       ized session data to memcached with nghttpx:tls-session-cache: + lower‐
1708       case hex string of session ID as a memcached  entry  key,  with  expiry
1709       time 12 hours.  Session timeout is set to 12 hours.
1710
1711       By  default, connections to memcached server are not encrypted.  To en‐
1712       able encryption, use tls keyword in  --tls-session-cache-memcached  op‐
1713       tion.
1714
1715   TLS SESSION TICKET RESUMPTION
1716       By  default, session ticket is shared by all worker threads.  The auto‐
1717       matic key rotation is also enabled by default.  Every an hour, new  en‐
1718       cryption  key is generated, and previous encryption key becomes decryp‐
1719       tion only key.  We set session timeout to 12 hours, and thus we keep at
1720       most 12 keys.
1721
1722       If  --tls-ticket-key-memcached  is given, encryption keys are retrieved
1723       from memcached.  nghttpx just reads keys from memcached; one has to de‐
1724       ploy  key  generator  program  to update keys frequently (e.g., every 1
1725       hour).  The example key generator tlsticketupdate.go is available under
1726       contrib  directory  in  nghttp2  archive.   The  memcached entry key is
1727       nghttpx:tls-ticket-key.  The data format stored in memcached is the bi‐
1728       nary format described below:
1729
1730          +--------------+-------+----------------+
1731          | VERSION (4)  |LEN (2)|KEY(48 or 80) ...
1732          +--------------+-------+----------------+
1733                         ^                        |
1734                         |                        |
1735                         +------------------------+
1736                         (LEN, KEY) pair can be repeated
1737
1738       All  numbers in the above figure is bytes.  All integer fields are net‐
1739       work byte order.
1740
1741       First 4 bytes integer VERSION field, which must be 1.  The 2 bytes  in‐
1742       teger LEN field gives the length of following KEY field, which contains
1743       key.  If --tls-ticket-key-cipher=aes-128-cbc is used, LEN must  be  48.
1744       If  --tls-ticket-key-cipher=aes-256-cbc  is  used, LEN must be 80.  LEN
1745       and KEY pair can be repeated multiple times  to  store  multiple  keys.
1746       The  key  appeared  first is used as encryption key.  All the remaining
1747       keys are used as decryption only.
1748
1749       By default, connections to memcached server are not encrypted.  To  en‐
1750       able encryption, use tls keyword in --tls-ticket-key-memcached option.
1751
1752       If  --tls-ticket-key-file  is  given,  encryption  key is read from the
1753       given file.  In this case, nghttpx does not rotate  key  automatically.
1754       To rotate key, one has to restart nghttpx (see SIGNALS).
1755

CERTIFICATE TRANSPARENCY

1757       nghttpx supports TLS signed_certificate_timestamp extension (RFC 6962).
1758       The  relevant  options  are  --tls-sct-dir  and  sct-dir  parameter  in
1759       --subcert.   They  takes a directory, and nghttpx reads all files whose
1760       extension is .sct under the directory.  The *.sct files are encoded  as
1761       SignedCertificateTimestamp  struct  described  in  section  3.2  of RFC
1762       69662.  This format is the same one used by  nginx-ct  and  mod_ssl_ct.
1763       ct-submit can be used to submit certificates to log servers, and obtain
1764       the SignedCertificateTimestamp struct which can be used with nghttpx.
1765

MRUBY SCRIPTING

1767       WARNING:
1768          The current mruby extension API is experimental and not frozen.  The
1769          API is subject to change in the future release.
1770
1771       WARNING:
1772          Almost  all  string  value  returned  from method, or attribute is a
1773          fresh new  mruby  string,  which  involves  memory  allocation,  and
1774          copies.   Therefore,  it  is  strongly recommended to store a return
1775          value in a local variable, and use it, instead of calling method  or
1776          accessing attribute repeatedly.
1777
1778       nghttpx  allows  users  to  extend  its capability using mruby scripts.
1779       nghttpx has 2 hook points to execute mruby script:  request  phase  and
1780       response  phase.   The  request phase hook is invoked after all request
1781       header fields are received from client.  The response phase hook is in‐
1782       voked  after  all  response  header  fields  are  received from backend
1783       server.  These hooks allows users to modify header  fields,  or  common
1784       HTTP  variables, like authority or request path, and even return custom
1785       response without forwarding request to backend servers.
1786
1787       There are 2 levels of mruby script invocations: global and per-pattern.
1788       The global mruby script is set by --mruby-file option and is called for
1789       all requests.  The per-pattern mruby script is set by "mruby" parameter
1790       in -b option.  It is invoked for a request which matches the particular
1791       pattern.  The order of hook invocation is: global request  phase  hook,
1792       per-pattern  request  phase  hook, per-pattern response phase hook, and
1793       finally global response phase hook.  If a hook returns a response,  any
1794       later hooks are not invoked.  The global request hook is invoked before
1795       the pattern matching is made and changing request path may  affect  the
1796       pattern matching.
1797
1798       Please note that request and response hooks of per-pattern mruby script
1799       for a single request might not come from the same script.   This  might
1800       happen  after  a request hook is executed, backend failed for some rea‐
1801       son, and at the same time, backend configuration is replaced by API re‐
1802       quest,  and  then the request uses new configuration on retry.  The re‐
1803       sponse hook from new configuration, if it is  specified,  will  be  in‐
1804       voked.
1805
1806       The  all mruby script will be evaluated once per thread on startup, and
1807       it must instantiate object and evaluate it as the return  value  (e.g.,
1808       App.new).   This  object  is  called app object.  If app object defines
1809       on_req method, it is called with Nghttpx::Env object on  request  hook.
1810       Similarly,  if  app  object  defines  on_resp method, it is called with
1811       Nghttpx::Env object on response hook.  For each method invocation, user
1812       can  can  access  Nghttpx::Request  and  Nghttpx::Response  objects via
1813       Nghttpx::Env#req and Nghttpx::Env#resp respectively.
1814
1815       Nghttpx::REQUEST_PHASE
1816              Constant to represent request phase.
1817
1818       Nghttpx::RESPONSE_PHASE
1819              Constant to represent response phase.
1820
1821       class Nghttpx::Env
1822              Object to represent current request specific context.
1823
1824              attribute [R] req
1825                     Return Request object.
1826
1827              attribute [R] resp
1828                     Return Response object.
1829
1830              attribute [R] ctx
1831                     Return Ruby hash object.  It persists until request  fin‐
1832                     ishes.   So  values  set in request phase hook can be re‐
1833                     trieved in response phase hook.
1834
1835              attribute [R] phase
1836                     Return the current phase.
1837
1838              attribute [R] remote_addr
1839                     Return IP address of a remote client.  If  connection  is
1840                     made via UNIX domain socket, this returns the string "lo‐
1841                     calhost".
1842
1843              attribute [R] server_addr
1844                     Return address of server that  accepted  the  connection.
1845                     This  is  a  string which specified in --frontend option,
1846                     excluding port number, and not  a  resolved  IP  address.
1847                     For  UNIX  domain  socket,  this is a path to UNIX domain
1848                     socket.
1849
1850              attribute [R] server_port
1851                     Return port number of the server frontend which  accepted
1852                     the connection from client.
1853
1854              attribute [R] tls_used
1855                     Return true if TLS is used on the connection.
1856
1857              attribute [R] tls_sni
1858                     Return  the  TLS SNI value which client sent in this con‐
1859                     nection.
1860
1861              attribute [R] tls_client_fingerprint_sha256
1862                     Return the SHA-256 fingerprint of a client certificate.
1863
1864              attribute [R] tls_client_fingerprint_sha1
1865                     Return the SHA-1 fingerprint of a client certificate.
1866
1867              attribute [R] tls_client_issuer_name
1868                     Return the issuer name of a client certificate.
1869
1870              attribute [R] tls_client_subject_name
1871                     Return the subject name of a client certificate.
1872
1873              attribute [R] tls_client_serial
1874                     Return the serial number of a client certificate.
1875
1876              attribute [R] tls_client_not_before
1877                     Return the start date of a client certificate in  seconds
1878                     since the epoch.
1879
1880              attribute [R] tls_client_not_after
1881                     Return  the  end  date of a client certificate in seconds
1882                     since the epoch.
1883
1884              attribute [R] tls_cipher
1885                     Return a TLS cipher negotiated in this connection.
1886
1887              attribute [R] tls_protocol
1888                     Return a TLS protocol version negotiated in this  connec‐
1889                     tion.
1890
1891              attribute [R] tls_session_id
1892                     Return a session ID for this connection in hex string.
1893
1894              attribute [R] tls_session_reused
1895                     Return true if, and only if a SSL/TLS session is reused.
1896
1897              attribute [R] alpn
1898                     Return ALPN identifier negotiated in this connection.
1899
1900              attribute [R] tls_handshake_finished
1901                     Return true if SSL/TLS handshake has finished.  If it re‐
1902                     turns false in the request phase hook, the request is re‐
1903                     ceived in TLSv1.3 early data (0-RTT) and might be vulner‐
1904                     able to the replay attack.  nghttpx will send  Early-Data
1905                     header field to backend servers to indicate this.
1906
1907       class Nghttpx::Request
1908              Object  to  represent  request from client.  The modification to
1909              Request object is allowed only in request phase hook.
1910
1911              attribute [R] http_version_major
1912                     Return HTTP major version.
1913
1914              attribute [R] http_version_minor
1915                     Return HTTP minor version.
1916
1917              attribute [R/W] method
1918                     HTTP method.  On assignment, copy of given value  is  as‐
1919                     signed.   We don't accept arbitrary method name.  We will
1920                     document them later, but well known  methods,  like  GET,
1921                     PUT and POST, are all supported.
1922
1923              attribute [R/W] authority
1924                     Authority  (i.e.,  example.org),  including optional port
1925                     component .  On assignment, copy of given  value  is  as‐
1926                     signed.
1927
1928              attribute [R/W] scheme
1929                     Scheme (i.e., http, https).  On assignment, copy of given
1930                     value is assigned.
1931
1932              attribute [R/W] path
1933                     Request  path,  including  query  component  (i.e.,  /in‐
1934                     dex.html).   On  assignment,  copy  of given value is as‐
1935                     signed.  The path does not include authority component of
1936                     URI.   This  may  include query component.  nghttpx makes
1937                     certain normalization for path.  It  decodes  percent-en‐
1938                     coding      for      unreserved      characters      (see
1939                     https://tools.ietf.org/html/rfc3986#section-2.3), and re‐
1940                     solves  ".."  and ".".  But it may leave characters which
1941                     should be percent-encoded as is. So be careful when  com‐
1942                     paring path against desired string.
1943
1944              attribute [R] headers
1945                     Return  Ruby  hash  containing  copy  of  request  header
1946                     fields.  Changing values in returned hash does not change
1947                     request  header  fields actually used in request process‐
1948                     ing.       Use       Nghttpx::Request#add_header       or
1949                     Nghttpx::Request#set_header   to  change  request  header
1950                     fields.
1951
1952              add_header(key, value)
1953                     Add header entry associated with key.  The value  can  be
1954                     single  string  or  array of string.  It does not replace
1955                     any existing values associated with key.
1956
1957              set_header(key, value)
1958                     Set header entry associated with key.  The value  can  be
1959                     single string or array of string.  It replaces any exist‐
1960                     ing values associated with key.
1961
1962              clear_headers()
1963                     Clear all existing request header fields.
1964
1965              push(uri)
1966                     Initiate to push resource identified by uri.  Only HTTP/2
1967                     protocol supports this feature.  For the other protocols,
1968                     this method is noop.  uri can be absolute  URI,  absolute
1969                     path  or relative path to the current request.  For abso‐
1970                     lute or relative path, scheme and authority are inherited
1971                     from  the  current  request.  Currently, method is always
1972                     GET.  nghttpx will issue request to  backend  servers  to
1973                     fulfill  this  request.   The  request and response phase
1974                     hooks will be called for pushed resource as well.
1975
1976       class Nghttpx::Response
1977              Object to represent response from backend server.
1978
1979              attribute [R] http_version_major
1980                     Return HTTP major version.
1981
1982              attribute [R] http_version_minor
1983                     Return HTTP minor version.
1984
1985              attribute [R/W] status
1986                     HTTP status code.  It must be in the  range  [200,  999],
1987                     inclusive.  The non-final status code is not supported in
1988                     mruby scripting at the moment.
1989
1990              attribute [R] headers
1991                     Return Ruby  hash  containing  copy  of  response  header
1992                     fields.  Changing values in returned hash does not change
1993                     response header fields actually used in response process‐
1994                     ing.        Use      Nghttpx::Response#add_header      or
1995                     Nghttpx::Response#set_header to  change  response  header
1996                     fields.
1997
1998              add_header(key, value)
1999                     Add  header  entry associated with key.  The value can be
2000                     single string or array of string.  It  does  not  replace
2001                     any existing values associated with key.
2002
2003              set_header(key, value)
2004                     Set  header  entry associated with key.  The value can be
2005                     single string or array of string.  It replaces any exist‐
2006                     ing values associated with key.
2007
2008              clear_headers()
2009                     Clear all existing response header fields.
2010
2011              return(body)
2012                     Return  custom  response  body  to  a  client.  When this
2013                     method is called in request phase hook,  the  request  is
2014                     not forwarded to the backend, and response phase hook for
2015                     this request will not be invoked.  When  this  method  is
2016                     called  in  response  phase  hook,  response from backend
2017                     server is canceled and discarded.  The  status  code  and
2018                     response  header  fields  should be set before using this
2019                     method.       To      set      status      code,      use
2020                     Nghttpx::Response#status.  If status code is not set, 200
2021                     is   used.     To    set    response    header    fields,
2022                     Nghttpx::Response#add_header                          and
2023                     Nghttpx::Response#set_header.  When this  method  is  in‐
2024                     voked  in  response  phase hook, the response headers are
2025                     filled with the ones received from  backend  server.   To
2026                     send   completely   custom   header  fields,  first  call
2027                     Nghttpx::Response#clear_headers  to  erase  all  existing
2028                     header  fields,  and then add required header fields.  It
2029                     is an error to call this method twice  for  a  given  re‐
2030                     quest.
2031
2032              send_info(status, headers)
2033                     Send  non-final  (informational)  response  to  a client.
2034                     status must be in the range [100, 199], inclusive.  head‐
2035                     ers is a hash containing response header fields.  Its key
2036                     must be a string, and the associated value must be either
2037                     string  or  array  of strings.  Since this is not a final
2038                     response, even if this  method  is  invoked,  request  is
2039                     still      forwarded      to     a     backend     unless
2040                     Nghttpx::Response#return is called.  This method  can  be
2041                     called   multiple  times.   It  cannot  be  called  after
2042                     Nghttpx::Response#return is called.
2043
2044   MRUBY EXAMPLES
2045       Modify request path:
2046
2047          class App
2048            def on_req(env)
2049              env.req.path = "/apps#{env.req.path}"
2050            end
2051          end
2052
2053          App.new
2054
2055       Don't forget to instantiate and evaluate object at the last line.
2056
2057       Restrict permission of viewing a  content  to  a  specific  client  ad‐
2058       dresses:
2059
2060          class App
2061            def on_req(env)
2062              allowed_clients = ["127.0.0.1", "::1"]
2063
2064              if env.req.path.start_with?("/log/") &&
2065                 !allowed_clients.include?(env.remote_addr) then
2066                env.resp.status = 404
2067                env.resp.return "permission denied"
2068              end
2069            end
2070          end
2071
2072          App.new
2073

API ENDPOINTS

2075       nghttpx  exposes API endpoints to manipulate it via HTTP based API.  By
2076       default, API endpoint is disabled.   To  enable  it,  add  a  dedicated
2077       frontend for API using --frontend option with "api" parameter.  All re‐
2078       quests which come from this frontend address, will be  treated  as  API
2079       request.
2080
2081       The  response  is  normally  JSON dictionary, and at least includes the
2082       following keys:
2083
2084       status The status of the request processing.  The following values  are
2085              defined:
2086
2087              Success
2088                     The request was successful.
2089
2090              Failure
2091                     The request was failed.  No change has been made.
2092
2093       code   HTTP status code
2094
2095       Additionally,  depending  on the API endpoint, data key may be present,
2096       and its value contains the API endpoint specific data.
2097
2098       We wrote "normally", since nghttpx may return ordinal HTML response  in
2099       some  cases  where  the error has occurred before reaching API endpoint
2100       (e.g., header field is too large).
2101
2102       The following section describes available API endpoints.
2103
2104   POST /api/v1beta1/backendconfig
2105       This API replaces the current backend  server  settings  with  the  re‐
2106       quested  ones.   The request method should be POST, but PUT is also ac‐
2107       ceptable.  The request body must be nghttpx configuration file  format.
2108       For  configuration  file format, see FILES section.  The line separator
2109       inside the request body must be  single  LF  (0x0A).   Currently,  only
2110       backend option is parsed, the others are simply ignored.  The semantics
2111       of this API is replace the current backend with the backend options  in
2112       request  body.  Describe the desired set of backend severs, and nghttpx
2113       makes it happen.  If there is no backend option  is  found  in  request
2114       body,  the current set of backend is replaced with the backend option's
2115       default value, which is 127.0.0.1,80.
2116
2117       The replacement is done instantly without breaking existing connections
2118       or  requests.   It also avoids any process creation as is the case with
2119       hot swapping with signals.
2120
2121       The one limitation is that  only  numeric  IP  address  is  allowed  in
2122       backend  in  request  body unless "dns" parameter is used while non nu‐
2123       meric hostname is allowed in command-line or configuration file is read
2124       using --conf.
2125
2126   GET /api/v1beta1/configrevision
2127       This  API  returns  configuration revision of the current nghttpx.  The
2128       configuration revision is opaque string,  and  it  changes  after  each
2129       reloading by SIGHUP.  With this API, an external application knows that
2130       whether nghttpx has finished reloading its configuration  by  comparing
2131       the  configuration revisions between before and after reloading.  It is
2132       recommended to disable persistent (keep-alive) connection for this pur‐
2133       pose  in  order  to avoid to send a request using the reused connection
2134       which may bound to an old process.
2135
2136       This API returns response including data key.  Its value  is  JSON  ob‐
2137       ject, and it contains at least the following key:
2138
2139       configRevision
2140              The configuration revision of the current nghttpx
2141

SEE ALSO

2143       nghttp(1), nghttpd(1), h2load(1)
2144

AUTHOR

2146       Tatsuhiro Tsujikawa
2147
2149       2012, 2015, 2016, Tatsuhiro Tsujikawa
2150
2151
2152
2153
21541.55.1                           Jul 14, 2023                       NGHTTPX(1)
Impressum