doc/nghttpx.1.rst

   1
   2 .. GENERATED by help2rst.py.  DO NOT EDIT DIRECTLY.
   3
   4 .. program:: nghttpx
   5
   6 nghttpx(1)
   7 ==========
   8
   9 SYNOPSIS
  10 --------
  11
  12 **nghttpx** [OPTIONS]... [<PRIVATE_KEY> <CERT>]
  13
  14 DESCRIPTION
  15 -----------
  16
  17 A reverse proxy for HTTP/3, HTTP/2, and HTTP/1.
  18
  19 .. describe:: <PRIVATE_KEY>
  20
  21
  22     Set  path  to  server's private  key.   Required  unless
  23     "no-tls" parameter is used in :option:`--frontend` option.
  24
  25 .. describe:: <CERT>
  26
  27     Set  path  to  server's  certificate.   Required  unless
  28     "no-tls"  parameter is  used in  :option:`--frontend` option.   To
  29     make OCSP stapling work, this must be an absolute path.
  30
  31
  32 OPTIONS
  33 -------
  34
  35 The options are categorized into several groups.
  36
  37 Connections
  38 ~~~~~~~~~~~
  39
  40 .. option:: -b, --backend=(<HOST>,<PORT>|unix:<PATH>)[;[<PATTERN>[:...]][[;<PARAM>]...]
  41
  42
  43     Set  backend  host  and   port.   The  multiple  backend
  44     addresses are  accepted by repeating this  option.  UNIX
  45     domain socket  can be  specified by prefixing  path name
  46     with "unix:" (e.g., unix:/var/run/backend.sock).
  47
  48     Optionally, if <PATTERN>s are given, the backend address
  49     is  only  used  if  request matches  the  pattern.   The
  50     pattern  matching is  closely  designed  to ServeMux  in
  51     net/http package of  Go programming language.  <PATTERN>
  52     consists of  path, host +  path or just host.   The path
  53     must start  with "*/*".  If  it ends with "*/*",  it matches
  54     all  request path  in  its subtree.   To  deal with  the
  55     request  to the  directory without  trailing slash,  the
  56     path which ends  with "*/*" also matches  the request path
  57     which  only  lacks  trailing  '*/*'  (e.g.,  path  "*/foo/*"
  58     matches request path  "*/foo*").  If it does  not end with
  59     "*/*", it  performs exact match against  the request path.
  60     If  host  is given,  it  performs  a match  against  the
  61     request host.   For a  request received on  the frontend
  62     listener with  "sni-fwd" parameter enabled, SNI  host is
  63     used instead of a request host.  If host alone is given,
  64     "*/*" is  appended to it,  so that it matches  all request
  65     paths  under the  host  (e.g., specifying  "nghttp2.org"
  66     equals  to "nghttp2.org/").   CONNECT method  is treated
  67     specially.  It  does not have  path, and we  don't allow
  68     empty path.  To workaround  this, we assume that CONNECT
  69     method has "*/*" as path.
  70
  71     Patterns with  host take  precedence over  patterns with
  72     just path.   Then, longer patterns take  precedence over
  73     shorter ones.
  74
  75     Host  can  include "\*"  in  the  left most  position  to
  76     indicate  wildcard match  (only suffix  match is  done).
  77     The "\*" must match at least one character.  For example,
  78     host    pattern    "\*.nghttp2.org"    matches    against
  79     "www.nghttp2.org"  and  "git.ngttp2.org", but  does  not
  80     match  against  "nghttp2.org".   The exact  hosts  match
  81     takes precedence over the wildcard hosts match.
  82
  83     If path  part ends with  "\*", it is treated  as wildcard
  84     path.  The  wildcard path  behaves differently  from the
  85     normal path.  For normal path,  match is made around the
  86     boundary of path component  separator,"*/*".  On the other
  87     hand, the wildcard  path does not take  into account the
  88     path component  separator.  All paths which  include the
  89     wildcard  path  without  last  "\*" as  prefix,  and  are
  90     strictly longer than wildcard  path without last "\*" are
  91     matched.  "\*"  must match  at least one  character.  For
  92     example,  the   pattern  "*/foo\**"  matches   "*/foo/*"  and
  93     "*/foobar*".  But it does not match "*/foo*", or "*/fo*".
  94
  95     If <PATTERN> is omitted or  empty string, "*/*" is used as
  96     pattern,  which  matches  all request  paths  (catch-all
  97     pattern).  The catch-all backend must be given.
  98
  99     When doing  a match, nghttpx made  some normalization to
 100     pattern, request host and path.  For host part, they are
 101     converted to lower case.  For path part, percent-encoded
 102     unreserved characters  defined in RFC 3986  are decoded,
 103     and any  dot-segments (".."  and ".")   are resolved and
 104     removed.
 105
 106     For   example,   :option:`-b`\'127.0.0.1,8080;nghttp2.org/httpbin/'
 107     matches the  request host "nghttp2.org" and  the request
 108     path "*/httpbin/get*", but does not match the request host
 109     "nghttp2.org" and the request path "*/index.html*".
 110
 111     The  multiple <PATTERN>s  can  be specified,  delimiting
 112     them            by           ":".             Specifying
 113     :option:`-b`\'127.0.0.1,8080;nghttp2.org:www.nghttp2.org'  has  the
 114     same  effect  to specify  :option:`-b`\'127.0.0.1,8080;nghttp2.org'
 115     and :option:`-b`\'127.0.0.1,8080;www.nghttp2.org'.
 116
 117     The backend addresses sharing same <PATTERN> are grouped
 118     together forming  load balancing  group.
 119
 120     Several parameters <PARAM> are accepted after <PATTERN>.
 121     The  parameters are  delimited  by  ";".  The  available
 122     parameters       are:      "proto=<PROTO>",       "tls",
 123     "sni=<SNI_HOST>",         "fall=<N>",        "rise=<N>",
 124     "affinity=<METHOD>",    "dns",    "redirect-if-not-tls",
 125     "upgrade-scheme",                        "mruby=<PATH>",
 126     "read-timeout=<DURATION>",   "write-timeout=<DURATION>",
 127     "group=<GROUP>",  "group-weight=<N>", "weight=<N>",  and
 128     "dnf".    The  parameter   consists   of  keyword,   and
 129     optionally followed by "="  and value.  For example, the
 130     parameter "proto=h2" consists of the keyword "proto" and
 131     value "h2".  The parameter "tls" consists of the keyword
 132     "tls"  without value.   Each parameter  is described  as
 133     follows.
 134
 135     The backend application protocol  can be specified using
 136     optional  "proto"   parameter,  and   in  the   form  of
 137     "proto=<PROTO>".  <PROTO> should be one of the following
 138     list  without  quotes:  "h2", "http/1.1".   The  default
 139     value of <PROTO> is  "http/1.1".  Note that usually "h2"
 140     refers to HTTP/2  over TLS.  But in this  option, it may
 141     mean HTTP/2  over cleartext TCP unless  "tls" keyword is
 142     used (see below).
 143
 144     TLS  can   be  enabled  by  specifying   optional  "tls"
 145     parameter.  TLS is not enabled by default.
 146
 147     With "sni=<SNI_HOST>" parameter, it can override the TLS
 148     SNI  field  value  with  given  <SNI_HOST>.   This  will
 149     default to the backend <HOST> name
 150
 151     The  feature  to detect  whether  backend  is online  or
 152     offline can be enabled  using optional "fall" and "rise"
 153     parameters.   Using  "fall=<N>"  parameter,  if  nghttpx
 154     cannot connect  to a  this backend <N>  times in  a row,
 155     this  backend  is  assumed  to be  offline,  and  it  is
 156     excluded from load balancing.  If <N> is 0, this backend
 157     never  be excluded  from load  balancing whatever  times
 158     nghttpx cannot connect  to it, and this  is the default.
 159     There is  also "rise=<N>" parameter.  After  backend was
 160     excluded from load balancing group, nghttpx periodically
 161     attempts to make a connection to the failed backend, and
 162     if the  connection is made  successfully <N> times  in a
 163     row, the backend is assumed to  be online, and it is now
 164     eligible  for load  balancing target.   If <N>  is 0,  a
 165     backend  is permanently  offline, once  it goes  in that
 166     state, and this is the default behaviour.
 167
 168     The     session     affinity    is     enabled     using
 169     "affinity=<METHOD>"  parameter.   If  "ip" is  given  in
 170     <METHOD>, client  IP based session affinity  is enabled.
 171     If "cookie"  is given in <METHOD>,  cookie based session
 172     affinity is  enabled.  If  "none" is given  in <METHOD>,
 173     session affinity  is disabled, and this  is the default.
 174     The session  affinity is  enabled per <PATTERN>.   If at
 175     least  one backend  has  "affinity"  parameter, and  its
 176     <METHOD> is not "none",  session affinity is enabled for
 177     all backend  servers sharing the same  <PATTERN>.  It is
 178     advised  to  set  "affinity" parameter  to  all  backend
 179     explicitly if session affinity  is desired.  The session
 180     affinity  may   break  if   one  of  the   backend  gets
 181     unreachable,  or   backend  settings  are   reloaded  or
 182     replaced by API.
 183
 184     If   "affinity=cookie"    is   used,    the   additional
 185     configuration                is                required.
 186     "affinity-cookie-name=<NAME>" must be  used to specify a
 187     name     of     cookie      to     use.      Optionally,
 188     "affinity-cookie-path=<PATH>" can  be used to  specify a
 189     path   which   cookie    is   applied.    The   optional
 190     "affinity-cookie-secure=<SECURE>"  controls  the  Secure
 191     attribute of a cookie.  The default value is "auto", and
 192     the Secure attribute is  determined by a request scheme.
 193     If a request scheme is "https", then Secure attribute is
 194     set.  Otherwise, it  is not set.  If  <SECURE> is "yes",
 195     the  Secure attribute  is  always set.   If <SECURE>  is
 196     "no", the Secure attribute is always omitted.
 197
 198     By default, name resolution of backend host name is done
 199     at  start  up,  or reloading  configuration.   If  "dns"
 200     parameter   is  given,   name  resolution   takes  place
 201     dynamically.  This is useful  if backend address changes
 202     frequently.   If  "dns"  is given,  name  resolution  of
 203     backend   host   name   at  start   up,   or   reloading
 204     configuration is skipped.
 205
 206     If "redirect-if-not-tls" parameter  is used, the matched
 207     backend  requires   that  frontend  connection   is  TLS
 208     encrypted.  If it isn't, nghttpx responds to the request
 209     with 308  status code, and  https URI the  client should
 210     use instead  is included in Location  header field.  The
 211     port number in  redirect URI is 443 by  default, and can
 212     be  changed using  :option:`--redirect-https-port` option.   If at
 213     least one  backend has  "redirect-if-not-tls" parameter,
 214     this feature is enabled  for all backend servers sharing
 215     the   same   <PATTERN>.    It    is   advised   to   set
 216     "redirect-if-no-tls"    parameter   to    all   backends
 217     explicitly if this feature is desired.
 218
 219     If "upgrade-scheme"  parameter is used along  with "tls"
 220     parameter, HTTP/2 :scheme pseudo header field is changed
 221     to "https" from "http" when forwarding a request to this
 222     particular backend.  This is  a workaround for a backend
 223     server  which  requires  "https" :scheme  pseudo  header
 224     field on TLS encrypted connection.
 225
 226     "mruby=<PATH>"  parameter  specifies  a  path  to  mruby
 227     script  file  which  is  invoked when  this  pattern  is
 228     matched.  All backends which share the same pattern must
 229     have the same mruby path.
 230
 231     "read-timeout=<DURATION>" and "write-timeout=<DURATION>"
 232     parameters  specify the  read and  write timeout  of the
 233     backend connection  when this  pattern is  matched.  All
 234     backends which share the same pattern must have the same
 235     timeouts.  If these timeouts  are entirely omitted for a
 236     pattern,            :option:`--backend-read-timeout`           and
 237     :option:`--backend-write-timeout` are used.
 238
 239     "group=<GROUP>"  parameter specifies  the name  of group
 240     this backend address belongs to.  By default, it belongs
 241     to  the unnamed  default group.   The name  of group  is
 242     unique   per   pattern.   "group-weight=<N>"   parameter
 243     specifies the  weight of  the group.  The  higher weight
 244     gets  more frequently  selected  by  the load  balancing
 245     algorithm.  <N> must be  [1, 256] inclusive.  The weight
 246     8 has 4 times more weight  than 2.  <N> must be the same
 247     for  all addresses  which  share the  same <GROUP>.   If
 248     "group-weight" is  omitted in an address,  but the other
 249     address  which  belongs  to  the  same  group  specifies
 250     "group-weight",   its    weight   is   used.     If   no
 251     "group-weight"  is  specified  for  all  addresses,  the
 252     weight of a group becomes 1.  "group" and "group-weight"
 253     are ignored if session affinity is enabled.
 254
 255     "weight=<N>"  parameter  specifies  the  weight  of  the
 256     backend  address  inside  a  group  which  this  address
 257     belongs  to.  The  higher  weight  gets more  frequently
 258     selected by  the load balancing algorithm.   <N> must be
 259     [1,  256] inclusive.   The  weight 8  has  4 times  more
 260     weight  than weight  2.  If  this parameter  is omitted,
 261     weight  becomes  1.   "weight"  is  ignored  if  session
 262     affinity is enabled.
 263
 264     If "dnf" parameter is  specified, an incoming request is
 265     not forwarded to a backend  and just consumed along with
 266     the  request body  (actually a  backend server  never be
 267     contacted).  It  is expected  that the HTTP  response is
 268     generated by mruby  script (see "mruby=<PATH>" parameter
 269     above).  "dnf" is an abbreviation of "do not forward".
 270
 271     Since ";" and ":" are  used as delimiter, <PATTERN> must
 272     not contain  these characters.  In order  to include ":"
 273     in  <PATTERN>,  one  has  to  specify  "%3A"  (which  is
 274     percent-encoded  from of  ":") instead.   Since ";"  has
 275     special  meaning  in shell,  the  option  value must  be
 276     quoted.
 277
 278
 279     Default: ``127.0.0.1,80``
 280
 281 .. option:: -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]
 282
 283     Set  frontend  host and  port.   If  <HOST> is  '\*',  it
 284     assumes  all addresses  including  both  IPv4 and  IPv6.
 285     UNIX domain  socket can  be specified by  prefixing path
 286     name  with  "unix:" (e.g.,  unix:/var/run/nghttpx.sock).
 287     This  option can  be used  multiple times  to listen  to
 288     multiple addresses.
 289
 290     This option  can take  0 or  more parameters,  which are
 291     described  below.   Note   that  "api"  and  "healthmon"
 292     parameters are mutually exclusive.
 293
 294     Optionally, TLS  can be disabled by  specifying "no-tls"
 295     parameter.  TLS is enabled by default.
 296
 297     If "sni-fwd" parameter is  used, when performing a match
 298     to select a backend server,  SNI host name received from
 299     the client  is used  instead of  the request  host.  See
 300     :option:`--backend` option about the pattern match.
 301
 302     To  make this  frontend as  API endpoint,  specify "api"
 303     parameter.   This   is  disabled  by  default.    It  is
 304     important  to  limit the  access  to  the API  frontend.
 305     Otherwise, someone  may change  the backend  server, and
 306     break your services,  or expose confidential information
 307     to the outside the world.
 308
 309     To  make  this  frontend  as  health  monitor  endpoint,
 310     specify  "healthmon"  parameter.   This is  disabled  by
 311     default.  Any  requests which come through  this address
 312     are replied with 200 HTTP status, without no body.
 313
 314     To accept  PROXY protocol  version 1  and 2  on frontend
 315     connection,  specify  "proxyproto" parameter.   This  is
 316     disabled by default.
 317
 318     To  receive   HTTP/3  (QUIC)  traffic,   specify  "quic"
 319     parameter.  It  makes nghttpx listen on  UDP port rather
 320     than  TCP   port.   UNIX   domain  socket,   "api",  and
 321     "healthmon"  parameters  cannot   be  used  with  "quic"
 322     parameter.
 323
 324
 325     Default: ``*,3000``
 326
 327 .. option:: --backlog=<N>
 328
 329     Set listen backlog size.
 330
 331     Default: ``65536``
 332
 333 .. option:: --backend-address-family=(auto|IPv4|IPv6)
 334
 335     Specify  address  family  of  backend  connections.   If
 336     "auto" is given, both IPv4  and IPv6 are considered.  If
 337     "IPv4" is  given, only  IPv4 address is  considered.  If
 338     "IPv6" is given, only IPv6 address is considered.
 339
 340     Default: ``auto``
 341
 342 .. option:: --backend-http-proxy-uri=<URI>
 343
 344     Specify      proxy       URI      in       the      form
 345     http://[<USER>:<PASS>@]<PROXY>:<PORT>.    If   a   proxy
 346     requires  authentication,  specify  <USER>  and  <PASS>.
 347     Note that  they must be properly  percent-encoded.  This
 348     proxy  is used  when the  backend connection  is HTTP/2.
 349     First,  make  a CONNECT  request  to  the proxy  and  it
 350     connects  to the  backend  on behalf  of nghttpx.   This
 351     forms  tunnel.   After  that, nghttpx  performs  SSL/TLS
 352     handshake with  the downstream through the  tunnel.  The
 353     timeouts when connecting and  making CONNECT request can
 354     be     specified    by     :option:`--backend-read-timeout`    and
 355     :option:`--backend-write-timeout` options.
 356
 357
 358 Performance
 359 ~~~~~~~~~~~
 360
 361 .. option:: -n, --workers=<N>
 362
 363     Set the number of worker threads.
 364
 365     Default: ``1``
 366
 367 .. option:: --single-thread
 368
 369     Run everything in one  thread inside the worker process.
 370     This   feature   is   provided  for   better   debugging
 371     experience,  or  for  the platforms  which  lack  thread
 372     support.   If  threading  is disabled,  this  option  is
 373     always enabled.
 374
 375 .. option:: --read-rate=<SIZE>
 376
 377     Set maximum  average read  rate on  frontend connection.
 378     Setting 0 to this option means read rate is unlimited.
 379
 380     Default: ``0``
 381
 382 .. option:: --read-burst=<SIZE>
 383
 384     Set  maximum read  burst  size  on frontend  connection.
 385     Setting  0  to this  option  means  read burst  size  is
 386     unlimited.
 387
 388     Default: ``0``
 389
 390 .. option:: --write-rate=<SIZE>
 391
 392     Set maximum  average write rate on  frontend connection.
 393     Setting 0 to this option means write rate is unlimited.
 394
 395     Default: ``0``
 396
 397 .. option:: --write-burst=<SIZE>
 398
 399     Set  maximum write  burst size  on frontend  connection.
 400     Setting  0 to  this  option means  write  burst size  is
 401     unlimited.
 402
 403     Default: ``0``
 404
 405 .. option:: --worker-read-rate=<SIZE>
 406
 407     Set maximum average read rate on frontend connection per
 408     worker.  Setting  0 to  this option  means read  rate is
 409     unlimited.  Not implemented yet.
 410
 411     Default: ``0``
 412
 413 .. option:: --worker-read-burst=<SIZE>
 414
 415     Set maximum  read burst size on  frontend connection per
 416     worker.  Setting 0 to this  option means read burst size
 417     is unlimited.  Not implemented yet.
 418
 419     Default: ``0``
 420
 421 .. option:: --worker-write-rate=<SIZE>
 422
 423     Set maximum  average write  rate on  frontend connection
 424     per worker.  Setting  0 to this option  means write rate
 425     is unlimited.  Not implemented yet.
 426
 427     Default: ``0``
 428
 429 .. option:: --worker-write-burst=<SIZE>
 430
 431     Set maximum write burst  size on frontend connection per
 432     worker.  Setting 0 to this option means write burst size
 433     is unlimited.  Not implemented yet.
 434
 435     Default: ``0``
 436
 437 .. option:: --worker-frontend-connections=<N>
 438
 439     Set maximum number  of simultaneous connections frontend
 440     accepts.  Setting 0 means unlimited.
 441
 442     Default: ``0``
 443
 444 .. option:: --backend-connections-per-host=<N>
 445
 446     Set  maximum number  of  backend concurrent  connections
 447     (and/or  streams in  case  of HTTP/2)  per origin  host.
 448     This option  is meaningful when :option:`--http2-proxy`  option is
 449     used.   The  origin  host  is  determined  by  authority
 450     portion of  request URI (or :authority  header field for
 451     HTTP/2).   To  limit  the   number  of  connections  per
 452     frontend        for       default        mode,       use
 453     :option:`--backend-connections-per-frontend`\.
 454
 455     Default: ``8``
 456
 457 .. option:: --backend-connections-per-frontend=<N>
 458
 459     Set  maximum number  of  backend concurrent  connections
 460     (and/or streams  in case of HTTP/2)  per frontend.  This
 461     option  is   only  used  for  default   mode.   0  means
 462     unlimited.  To limit the  number of connections per host
 463     with          :option:`--http2-proxy`         option,          use
 464     :option:`--backend-connections-per-host`\.
 465
 466     Default: ``0``
 467
 468 .. option:: --rlimit-nofile=<N>
 469
 470     Set maximum number of open files (RLIMIT_NOFILE) to <N>.
 471     If 0 is given, nghttpx does not set the limit.
 472
 473     Default: ``0``
 474
 475 .. option:: --rlimit-memlock=<N>
 476
 477     Set maximum number of bytes of memory that may be locked
 478     into  RAM.  If  0 is  given,  nghttpx does  not set  the
 479     limit.
 480
 481     Default: ``0``
 482
 483 .. option:: --backend-request-buffer=<SIZE>
 484
 485     Set buffer size used to store backend request.
 486
 487     Default: ``16K``
 488
 489 .. option:: --backend-response-buffer=<SIZE>
 490
 491     Set buffer size used to store backend response.
 492
 493     Default: ``128K``
 494
 495 .. option:: --fastopen=<N>
 496
 497     Enables  "TCP Fast  Open" for  the listening  socket and
 498     limits the  maximum length for the  queue of connections
 499     that have not yet completed the three-way handshake.  If
 500     value is 0 then fast open is disabled.
 501
 502     Default: ``0``
 503
 504 .. option:: --no-kqueue
 505
 506     Don't use  kqueue.  This  option is only  applicable for
 507     the platforms  which have kqueue.  For  other platforms,
 508     this option will be simply ignored.
 509
 510
 511 Timeout
 512 ~~~~~~~
 513
 514 .. option:: --frontend-http2-read-timeout=<DURATION>
 515
 516     Specify read timeout for HTTP/2 frontend connection.
 517
 518     Default: ``3m``
 519
 520 .. option:: --frontend-http3-read-timeout=<DURATION>
 521
 522     Specify read timeout for HTTP/3 frontend connection.
 523
 524     Default: ``3m``
 525
 526 .. option:: --frontend-read-timeout=<DURATION>
 527
 528     Specify read timeout for HTTP/1.1 frontend connection.
 529
 530     Default: ``1m``
 531
 532 .. option:: --frontend-write-timeout=<DURATION>
 533
 534     Specify write timeout for all frontend connections.
 535
 536     Default: ``30s``
 537
 538 .. option:: --frontend-keep-alive-timeout=<DURATION>
 539
 540     Specify   keep-alive   timeout   for   frontend   HTTP/1
 541     connection.
 542
 543     Default: ``1m``
 544
 545 .. option:: --stream-read-timeout=<DURATION>
 546
 547     Specify  read timeout  for HTTP/2  streams.  0  means no
 548     timeout.
 549
 550     Default: ``0``
 551
 552 .. option:: --stream-write-timeout=<DURATION>
 553
 554     Specify write  timeout for  HTTP/2 streams.  0  means no
 555     timeout.
 556
 557     Default: ``1m``
 558
 559 .. option:: --backend-read-timeout=<DURATION>
 560
 561     Specify read timeout for backend connection.
 562
 563     Default: ``1m``
 564
 565 .. option:: --backend-write-timeout=<DURATION>
 566
 567     Specify write timeout for backend connection.
 568
 569     Default: ``30s``
 570
 571 .. option:: --backend-connect-timeout=<DURATION>
 572
 573     Specify  timeout before  establishing TCP  connection to
 574     backend.
 575
 576     Default: ``30s``
 577
 578 .. option:: --backend-keep-alive-timeout=<DURATION>
 579
 580     Specify   keep-alive   timeout    for   backend   HTTP/1
 581     connection.
 582
 583     Default: ``2s``
 584
 585 .. option:: --listener-disable-timeout=<DURATION>
 586
 587     After accepting  connection failed,  connection listener
 588     is disabled  for a given  amount of time.   Specifying 0
 589     disables this feature.
 590
 591     Default: ``30s``
 592
 593 .. option:: --frontend-http2-setting-timeout=<DURATION>
 594
 595     Specify  timeout before  SETTINGS ACK  is received  from
 596     client.
 597
 598     Default: ``10s``
 599
 600 .. option:: --backend-http2-settings-timeout=<DURATION>
 601
 602     Specify  timeout before  SETTINGS ACK  is received  from
 603     backend server.
 604
 605     Default: ``10s``
 606
 607 .. option:: --backend-max-backoff=<DURATION>
 608
 609     Specify  maximum backoff  interval.  This  is used  when
 610     doing health  check against offline backend  (see "fail"
 611     parameter  in :option:`--backend`  option).   It is  also used  to
 612     limit  the  maximum   interval  to  temporarily  disable
 613     backend  when nghttpx  failed to  connect to  it.  These
 614     intervals are calculated  using exponential backoff, and
 615     consecutive failed attempts increase the interval.  This
 616     option caps its maximum value.
 617
 618     Default: ``2m``
 619
 620
 621 SSL/TLS
 622 ~~~~~~~
 623
 624 .. option:: --ciphers=<SUITE>
 625
 626     Set allowed  cipher list  for frontend  connection.  The
 627     format of the string is described in OpenSSL ciphers(1).
 628     This option  sets cipher suites for  TLSv1.2 or earlier.
 629     Use :option:`--tls13-ciphers` for TLSv1.3.
 630
 631     Default: ``ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256``
 632
 633 .. option:: --tls13-ciphers=<SUITE>
 634
 635     Set allowed  cipher list  for frontend  connection.  The
 636     format of the string is described in OpenSSL ciphers(1).
 637     This  option  sets  cipher   suites  for  TLSv1.3.   Use
 638     :option:`--ciphers` for TLSv1.2 or earlier.
 639
 640     Default: ``TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256``
 641
 642 .. option:: --client-ciphers=<SUITE>
 643
 644     Set  allowed cipher  list for  backend connection.   The
 645     format of the string is described in OpenSSL ciphers(1).
 646     This option  sets cipher suites for  TLSv1.2 or earlier.
 647     Use :option:`--tls13-client-ciphers` for TLSv1.3.
 648
 649     Default: ``ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256``
 650
 651 .. option:: --tls13-client-ciphers=<SUITE>
 652
 653     Set  allowed cipher  list for  backend connection.   The
 654     format of the string is described in OpenSSL ciphers(1).
 655     This  option  sets  cipher   suites  for  TLSv1.3.   Use
 656     :option:`--tls13-client-ciphers` for TLSv1.2 or earlier.
 657
 658     Default: ``TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256``
 659
 660 .. option:: --ecdh-curves=<LIST>
 661
 662     Set  supported  curve  list  for  frontend  connections.
 663     <LIST> is a  colon separated list of curve  NID or names
 664     in the preference order.  The supported curves depend on
 665     the  linked  OpenSSL  library.  This  function  requires
 666     OpenSSL >= 1.0.2.
 667
 668     Default: ``X25519:P-256:P-384:P-521``
 669
 670 .. option:: -k, --insecure
 671
 672     Don't  verify backend  server's  certificate  if TLS  is
 673     enabled for backend connections.
 674
 675 .. option:: --cacert=<PATH>
 676
 677     Set path to trusted CA  certificate file.  It is used in
 678     backend  TLS connections  to verify  peer's certificate.
 679     It is also used to  verify OCSP response from the script
 680     set by :option:`--fetch-ocsp-response-file`\.  The  file must be in
 681     PEM format.   It can contain multiple  certificates.  If
 682     the  linked OpenSSL  is configured  to load  system wide
 683     certificates, they  are loaded at startup  regardless of
 684     this option.
 685
 686 .. option:: --private-key-passwd-file=<PATH>
 687
 688     Path  to file  that contains  password for  the server's
 689     private key.   If none is  given and the private  key is
 690     password protected it'll be requested interactively.
 691
 692 .. option:: --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
 693
 694     Specify  additional certificate  and  private key  file.
 695     nghttpx will  choose certificates based on  the hostname
 696     indicated by client using TLS SNI extension.  If nghttpx
 697     is  built with  OpenSSL  >= 1.0.2,  the shared  elliptic
 698     curves (e.g., P-256) between  client and server are also
 699     taken into  consideration.  This allows nghttpx  to send
 700     ECDSA certificate  to modern clients, while  sending RSA
 701     based certificate to older  clients.  This option can be
 702     used  multiple  times.   To  make  OCSP  stapling  work,
 703     <CERTPATH> must be absolute path.
 704
 705     Additional parameter  can be specified in  <PARAM>.  The
 706     available <PARAM> is "sct-dir=<DIR>".
 707
 708     "sct-dir=<DIR>"  specifies the  path to  directory which
 709     contains        \*.sct        files        for        TLS
 710     signed_certificate_timestamp extension (RFC 6962).  This
 711     feature   requires   OpenSSL   >=   1.0.2.    See   also
 712     :option:`--tls-sct-dir` option.
 713
 714 .. option:: --dh-param-file=<PATH>
 715
 716     Path to file that contains  DH parameters in PEM format.
 717     Without  this   option,  DHE   cipher  suites   are  not
 718     available.
 719
 720 .. option:: --npn-list=<LIST>
 721
 722     Comma delimited list of  ALPN protocol identifier sorted
 723     in the  order of preference.  That  means most desirable
 724     protocol comes  first.  This  is used  in both  ALPN and
 725     NPN.  The parameter must be  delimited by a single comma
 726     only  and any  white spaces  are  treated as  a part  of
 727     protocol string.
 728
 729     Default: ``h2,h2-16,h2-14,http/1.1``
 730
 731 .. option:: --verify-client
 732
 733     Require and verify client certificate.
 734
 735 .. option:: --verify-client-cacert=<PATH>
 736
 737     Path  to file  that contains  CA certificates  to verify
 738     client certificate.  The file must be in PEM format.  It
 739     can contain multiple certificates.
 740
 741 .. option:: --verify-client-tolerate-expired
 742
 743     Accept  expired  client  certificate.   Operator  should
 744     handle  the expired  client  certificate  by some  means
 745     (e.g.,  mruby  script).   Otherwise, this  option  might
 746     cause a security risk.
 747
 748 .. option:: --client-private-key-file=<PATH>
 749
 750     Path to  file that contains  client private key  used in
 751     backend client authentication.
 752
 753 .. option:: --client-cert-file=<PATH>
 754
 755     Path to  file that  contains client certificate  used in
 756     backend client authentication.
 757
 758 .. option:: --tls-min-proto-version=<VER>
 759
 760     Specify minimum SSL/TLS protocol.   The name matching is
 761     done in  case-insensitive manner.  The  versions between
 762     :option:`--tls-min-proto-version` and  :option:`\--tls-max-proto-version` are
 763     enabled.  If the protocol list advertised by client does
 764     not  overlap  this range,  you  will  receive the  error
 765     message "unknown protocol".  If a protocol version lower
 766     than TLSv1.2 is specified, make sure that the compatible
 767     ciphers are  included in :option:`--ciphers` option.   The default
 768     cipher  list  only   includes  ciphers  compatible  with
 769     TLSv1.2 or above.  The available versions are:
 770     TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
 771
 772     Default: ``TLSv1.2``
 773
 774 .. option:: --tls-max-proto-version=<VER>
 775
 776     Specify maximum SSL/TLS protocol.   The name matching is
 777     done in  case-insensitive manner.  The  versions between
 778     :option:`--tls-min-proto-version` and  :option:`\--tls-max-proto-version` are
 779     enabled.  If the protocol list advertised by client does
 780     not  overlap  this range,  you  will  receive the  error
 781     message "unknown protocol".  The available versions are:
 782     TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
 783
 784     Default: ``TLSv1.3``
 785
 786 .. option:: --tls-ticket-key-file=<PATH>
 787
 788     Path to file that contains  random data to construct TLS
 789     session ticket  parameters.  If aes-128-cbc is  given in
 790     :option:`--tls-ticket-key-cipher`\, the  file must  contain exactly
 791     48    bytes.     If     aes-256-cbc    is    given    in
 792     :option:`--tls-ticket-key-cipher`\, the  file must  contain exactly
 793     80  bytes.   This  options  can be  used  repeatedly  to
 794     specify  multiple ticket  parameters.  If  several files
 795     are given,  only the  first key is  used to  encrypt TLS
 796     session  tickets.  Other  keys are  accepted but  server
 797     will  issue new  session  ticket with  first key.   This
 798     allows  session  key  rotation.  Please  note  that  key
 799     rotation  does  not  occur automatically.   User  should
 800     rearrange  files or  change options  values and  restart
 801     nghttpx gracefully.   If opening  or reading  given file
 802     fails, all loaded  keys are discarded and  it is treated
 803     as if none  of this option is given.  If  this option is
 804     not given or an error  occurred while opening or reading
 805     a file,  key is  generated every  1 hour  internally and
 806     they are  valid for  12 hours.   This is  recommended if
 807     ticket  key sharing  between  nghttpx  instances is  not
 808     required.
 809
 810 .. option:: --tls-ticket-key-memcached=<HOST>,<PORT>[;tls]
 811
 812     Specify address  of memcached  server to get  TLS ticket
 813     keys for  session resumption.   This enables  shared TLS
 814     ticket key between  multiple nghttpx instances.  nghttpx
 815     does not set TLS ticket  key to memcached.  The external
 816     ticket key generator is required.  nghttpx just gets TLS
 817     ticket  keys  from  memcached, and  use  them,  possibly
 818     replacing current set  of keys.  It is up  to extern TLS
 819     ticket  key generator  to rotate  keys frequently.   See
 820     "TLS SESSION  TICKET RESUMPTION" section in  manual page
 821     to know the data format in memcached entry.  Optionally,
 822     memcached  connection  can  be  encrypted  with  TLS  by
 823     specifying "tls" parameter.
 824
 825 .. option:: --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6)
 826
 827     Specify address  family of memcached connections  to get
 828     TLS ticket keys.  If "auto" is given, both IPv4 and IPv6
 829     are considered.   If "IPv4" is given,  only IPv4 address
 830     is considered.  If "IPv6" is given, only IPv6 address is
 831     considered.
 832
 833     Default: ``auto``
 834
 835 .. option:: --tls-ticket-key-memcached-interval=<DURATION>
 836
 837     Set interval to get TLS ticket keys from memcached.
 838
 839     Default: ``10m``
 840
 841 .. option:: --tls-ticket-key-memcached-max-retry=<N>
 842
 843     Set  maximum   number  of  consecutive   retries  before
 844     abandoning TLS ticket key  retrieval.  If this number is
 845     reached,  the  attempt  is considered  as  failure,  and
 846     "failure" count  is incremented by 1,  which contributed
 847     to            the            value            controlled
 848     :option:`--tls-ticket-key-memcached-max-fail` option.
 849
 850     Default: ``3``
 851
 852 .. option:: --tls-ticket-key-memcached-max-fail=<N>
 853
 854     Set  maximum   number  of  consecutive   failure  before
 855     disabling TLS ticket until next scheduled key retrieval.
 856
 857     Default: ``2``
 858
 859 .. option:: --tls-ticket-key-cipher=<CIPHER>
 860
 861     Specify cipher  to encrypt TLS session  ticket.  Specify
 862     either   aes-128-cbc   or  aes-256-cbc.    By   default,
 863     aes-128-cbc is used.
 864
 865 .. option:: --tls-ticket-key-memcached-cert-file=<PATH>
 866
 867     Path to client certificate  for memcached connections to
 868     get TLS ticket keys.
 869
 870 .. option:: --tls-ticket-key-memcached-private-key-file=<PATH>
 871
 872     Path to client private  key for memcached connections to
 873     get TLS ticket keys.
 874
 875 .. option:: --fetch-ocsp-response-file=<PATH>
 876
 877     Path to  fetch-ocsp-response script file.  It  should be
 878     absolute path.
 879
 880     Default: ``/usr/local/share/nghttp2/fetch-ocsp-response``
 881
 882 .. option:: --ocsp-update-interval=<DURATION>
 883
 884     Set interval to update OCSP response cache.
 885
 886     Default: ``4h``
 887
 888 .. option:: --ocsp-startup
 889
 890     Start  accepting connections  after initial  attempts to
 891     get OCSP responses  finish.  It does not  matter some of
 892     the  attempts  fail.  This  feature  is  useful if  OCSP
 893     responses   must    be   available    before   accepting
 894     connections.
 895
 896 .. option:: --no-verify-ocsp
 897
 898     nghttpx does not verify OCSP response.
 899
 900 .. option:: --no-ocsp
 901
 902     Disable OCSP stapling.
 903
 904 .. option:: --tls-session-cache-memcached=<HOST>,<PORT>[;tls]
 905
 906     Specify  address of  memcached server  to store  session
 907     cache.   This  enables   shared  session  cache  between
 908     multiple   nghttpx  instances.    Optionally,  memcached
 909     connection can be encrypted with TLS by specifying "tls"
 910     parameter.
 911
 912 .. option:: --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6)
 913
 914     Specify address family of memcached connections to store
 915     session cache.  If  "auto" is given, both  IPv4 and IPv6
 916     are considered.   If "IPv4" is given,  only IPv4 address
 917     is considered.  If "IPv6" is given, only IPv6 address is
 918     considered.
 919
 920     Default: ``auto``
 921
 922 .. option:: --tls-session-cache-memcached-cert-file=<PATH>
 923
 924     Path to client certificate  for memcached connections to
 925     store session cache.
 926
 927 .. option:: --tls-session-cache-memcached-private-key-file=<PATH>
 928
 929     Path to client private  key for memcached connections to
 930     store session cache.
 931
 932 .. option:: --tls-dyn-rec-warmup-threshold=<SIZE>
 933
 934     Specify the  threshold size for TLS  dynamic record size
 935     behaviour.  During  a TLS  session, after  the threshold
 936     number of bytes  have been written, the  TLS record size
 937     will be increased to the maximum allowed (16K).  The max
 938     record size will  continue to be used on  the active TLS
 939     session.  After  :option:`--tls-dyn-rec-idle-timeout` has elapsed,
 940     the record size is reduced  to 1300 bytes.  Specify 0 to
 941     always use  the maximum record size,  regardless of idle
 942     period.   This  behaviour  applies   to  all  TLS  based
 943     frontends, and TLS HTTP/2 backends.
 944
 945     Default: ``1M``
 946
 947 .. option:: --tls-dyn-rec-idle-timeout=<DURATION>
 948
 949     Specify TLS dynamic record  size behaviour timeout.  See
 950     :option:`--tls-dyn-rec-warmup-threshold`  for   more  information.
 951     This behaviour  applies to all TLS  based frontends, and
 952     TLS HTTP/2 backends.
 953
 954     Default: ``1s``
 955
 956 .. option:: --no-http2-cipher-block-list
 957
 958     Allow  block  listed  cipher suite  on  frontend  HTTP/2
 959     connection.                                          See
 960     https://tools.ietf.org/html/rfc7540#appendix-A  for  the
 961     complete HTTP/2 cipher suites block list.
 962
 963 .. option:: --client-no-http2-cipher-block-list
 964
 965     Allow  block  listed  cipher  suite  on  backend  HTTP/2
 966     connection.                                          See
 967     https://tools.ietf.org/html/rfc7540#appendix-A  for  the
 968     complete HTTP/2 cipher suites block list.
 969
 970 .. option:: --tls-sct-dir=<DIR>
 971
 972     Specifies the  directory where  \*.sct files  exist.  All
 973     \*.sct   files   in  <DIR>   are   read,   and  sent   as
 974     extension_data of  TLS signed_certificate_timestamp (RFC
 975     6962)  to  client.   These   \*.sct  files  are  for  the
 976     certificate   specified   in   positional   command-line
 977     argument <CERT>, or  certificate option in configuration
 978     file.   For   additional  certificates,   use  :option:`--subcert`
 979     option.  This option requires OpenSSL >= 1.0.2.
 980
 981 .. option:: --psk-secrets=<PATH>
 982
 983     Read list of PSK identity and secrets from <PATH>.  This
 984     is used for frontend connection.  The each line of input
 985     file  is  formatted  as  <identity>:<hex-secret>,  where
 986     <identity> is  PSK identity, and <hex-secret>  is secret
 987     in hex.  An  empty line, and line which  starts with '#'
 988     are skipped.  The default  enabled cipher list might not
 989     contain any PSK cipher suite.  In that case, desired PSK
 990     cipher suites  must be  enabled using  :option:`--ciphers` option.
 991     The  desired PSK  cipher suite  may be  block listed  by
 992     HTTP/2.   To  use  those   cipher  suites  with  HTTP/2,
 993     consider  to  use  :option:`--no-http2-cipher-block-list`  option.
 994     But be aware its implications.
 995
 996 .. option:: --client-psk-secrets=<PATH>
 997
 998     Read PSK identity and secrets from <PATH>.  This is used
 999     for backend connection.  The each  line of input file is
1000     formatted  as <identity>:<hex-secret>,  where <identity>
1001     is PSK identity, and <hex-secret>  is secret in hex.  An
1002     empty line, and line which  starts with '#' are skipped.
1003     The first identity and  secret pair encountered is used.
1004     The default  enabled cipher  list might not  contain any
1005     PSK  cipher suite.   In  that case,  desired PSK  cipher
1006     suites  must be  enabled using  :option:`--client-ciphers` option.
1007     The  desired PSK  cipher suite  may be  block listed  by
1008     HTTP/2.   To  use  those   cipher  suites  with  HTTP/2,
1009     consider   to  use   :option:`--client-no-http2-cipher-block-list`
1010     option.  But be aware its implications.
1011
1012 .. option:: --tls-no-postpone-early-data
1013
1014     By  default,   except  for  QUIC   connections,  nghttpx
1015     postpones forwarding  HTTP requests sent in  early data,
1016     including  those  sent in  partially  in  it, until  TLS
1017     handshake  finishes.  If  all backend  server recognizes
1018     "Early-Data"  header  field,  using  this  option  makes
1019     nghttpx  not postpone  forwarding request  and get  full
1020     potential of 0-RTT data.
1021
1022 .. option:: --tls-max-early-data=<SIZE>
1023
1024     Sets  the  maximum  amount  of 0-RTT  data  that  server
1025     accepts.
1026
1027     Default: ``16K``
1028
1029
1030 HTTP/2
1031 ~~~~~~
1032
1033 .. option:: -c, --frontend-http2-max-concurrent-streams=<N>
1034
1035     Set the maximum number of  the concurrent streams in one
1036     frontend HTTP/2 session.
1037
1038     Default: ``100``
1039
1040 .. option:: --backend-http2-max-concurrent-streams=<N>
1041
1042     Set the maximum number of  the concurrent streams in one
1043     backend  HTTP/2 session.   This sets  maximum number  of
1044     concurrent opened pushed streams.  The maximum number of
1045     concurrent requests are set by a remote server.
1046
1047     Default: ``100``
1048
1049 .. option:: --frontend-http2-window-size=<SIZE>
1050
1051     Sets  the  per-stream  initial  window  size  of  HTTP/2
1052     frontend connection.
1053
1054     Default: ``65535``
1055
1056 .. option:: --frontend-http2-connection-window-size=<SIZE>
1057
1058     Sets the  per-connection window size of  HTTP/2 frontend
1059     connection.
1060
1061     Default: ``65535``
1062
1063 .. option:: --backend-http2-window-size=<SIZE>
1064
1065     Sets  the   initial  window   size  of   HTTP/2  backend
1066     connection.
1067
1068     Default: ``65535``
1069
1070 .. option:: --backend-http2-connection-window-size=<SIZE>
1071
1072     Sets the  per-connection window  size of  HTTP/2 backend
1073     connection.
1074
1075     Default: ``2147483647``
1076
1077 .. option:: --http2-no-cookie-crumbling
1078
1079     Don't crumble cookie header field.
1080
1081 .. option:: --padding=<N>
1082
1083     Add  at most  <N> bytes  to  a HTTP/2  frame payload  as
1084     padding.  Specify 0 to  disable padding.  This option is
1085     meant for debugging purpose  and not intended to enhance
1086     protocol security.
1087
1088 .. option:: --no-server-push
1089
1090     Disable HTTP/2 server push.  Server push is supported by
1091     default mode and HTTP/2  frontend via Link header field.
1092     It is  also supported if  both frontend and  backend are
1093     HTTP/2 in default mode.  In  this case, server push from
1094     backend session is relayed  to frontend, and server push
1095     via Link header field is also supported.
1096
1097 .. option:: --frontend-http2-optimize-write-buffer-size
1098
1099     (Experimental) Enable write  buffer size optimization in
1100     frontend HTTP/2 TLS  connection.  This optimization aims
1101     to reduce  write buffer  size so  that it  only contains
1102     bytes  which can  send immediately.   This makes  server
1103     more responsive to prioritized HTTP/2 stream because the
1104     buffering  of lower  priority stream  is reduced.   This
1105     option is only effective on recent Linux platform.
1106
1107 .. option:: --frontend-http2-optimize-window-size
1108
1109     (Experimental)   Automatically  tune   connection  level
1110     window size of frontend  HTTP/2 TLS connection.  If this
1111     feature is  enabled, connection window size  starts with
1112     the   default  window   size,   65535  bytes.    nghttpx
1113     automatically  adjusts connection  window size  based on
1114     TCP receiving  window size.  The maximum  window size is
1115     capped      by      the     value      specified      by
1116     :option:`--frontend-http2-connection-window-size`\.     Since   the
1117     stream is subject to stream level window size, it should
1118     be adjusted using :option:`--frontend-http2-window-size` option as
1119     well.   This option  is only  effective on  recent Linux
1120     platform.
1121
1122 .. option:: --frontend-http2-encoder-dynamic-table-size=<SIZE>
1123
1124     Specify the maximum dynamic  table size of HPACK encoder
1125     in the frontend HTTP/2 connection.  The decoder (client)
1126     specifies  the maximum  dynamic table  size it  accepts.
1127     Then the negotiated dynamic table size is the minimum of
1128     this option value and the value which client specified.
1129
1130     Default: ``4K``
1131
1132 .. option:: --frontend-http2-decoder-dynamic-table-size=<SIZE>
1133
1134     Specify the maximum dynamic  table size of HPACK decoder
1135     in the frontend HTTP/2 connection.
1136
1137     Default: ``4K``
1138
1139 .. option:: --backend-http2-encoder-dynamic-table-size=<SIZE>
1140
1141     Specify the maximum dynamic  table size of HPACK encoder
1142     in the backend HTTP/2 connection.  The decoder (backend)
1143     specifies  the maximum  dynamic table  size it  accepts.
1144     Then the negotiated dynamic table size is the minimum of
1145     this option value and the value which backend specified.
1146
1147     Default: ``4K``
1148
1149 .. option:: --backend-http2-decoder-dynamic-table-size=<SIZE>
1150
1151     Specify the maximum dynamic  table size of HPACK decoder
1152     in the backend HTTP/2 connection.
1153
1154     Default: ``4K``
1155
1156
1157 Mode
1158 ~~~~
1159
1160 .. describe:: (default mode)
1161
1162
1163     Accept  HTTP/2,  and  HTTP/1.1 over  SSL/TLS.   "no-tls"
1164     parameter is  used in  :option:`--frontend` option,  accept HTTP/2
1165     and HTTP/1.1 over cleartext  TCP.  The incoming HTTP/1.1
1166     connection  can  be  upgraded  to  HTTP/2  through  HTTP
1167     Upgrade.
1168
1169 .. option:: -s, --http2-proxy
1170
1171     Like default mode, but enable forward proxy.  This is so
1172     called HTTP/2 proxy mode.
1173
1174
1175 Logging
1176 ~~~~~~~
1177
1178 .. option:: -L, --log-level=<LEVEL>
1179
1180     Set the severity  level of log output.   <LEVEL> must be
1181     one of INFO, NOTICE, WARN, ERROR and FATAL.
1182
1183     Default: ``NOTICE``
1184
1185 .. option:: --accesslog-file=<PATH>
1186
1187     Set path to write access log.  To reopen file, send USR1
1188     signal to nghttpx.
1189
1190 .. option:: --accesslog-syslog
1191
1192     Send  access log  to syslog.   If this  option is  used,
1193     :option:`--accesslog-file` option is ignored.
1194
1195 .. option:: --accesslog-format=<FORMAT>
1196
1197     Specify  format  string  for access  log.   The  default
1198     format is combined format.   The following variables are
1199     available:
1200
1201     * $remote_addr: client IP address.
1202     * $time_local: local time in Common Log format.
1203     * $time_iso8601: local time in ISO 8601 format.
1204     * $request: HTTP request line.
1205     * $status: HTTP response status code.
1206     * $body_bytes_sent: the  number of bytes sent  to client
1207       as response body.
1208     * $http_<VAR>: value of HTTP  request header <VAR> where
1209       '_' in <VAR> is replaced with '-'.
1210     * $remote_port: client  port.
1211     * $server_port: server port.
1212     * $request_time: request processing time in seconds with
1213       milliseconds resolution.
1214     * $pid: PID of the running process.
1215     * $alpn: ALPN identifier of the protocol which generates
1216       the response.   For HTTP/1,  ALPN is  always http/1.1,
1217       regardless of minor version.
1218     * $tls_cipher: cipher used for SSL/TLS connection.
1219     * $tls_client_fingerprint_sha256: SHA-256 fingerprint of
1220       client certificate.
1221     * $tls_client_fingerprint_sha1:  SHA-1   fingerprint  of
1222       client certificate.
1223     * $tls_client_subject_name:   subject  name   in  client
1224       certificate.
1225     * $tls_client_issuer_name:   issuer   name   in   client
1226       certificate.
1227     * $tls_client_serial:    serial    number   in    client
1228       certificate.
1229     * $tls_protocol: protocol for SSL/TLS connection.
1230     * $tls_session_id: session ID for SSL/TLS connection.
1231     * $tls_session_reused:  "r"   if  SSL/TLS   session  was
1232       reused.  Otherwise, "."
1233     * $tls_sni: SNI server name for SSL/TLS connection.
1234     * $backend_host:  backend  host   used  to  fulfill  the
1235       request.  "-" if backend host is not available.
1236     * $backend_port:  backend  port   used  to  fulfill  the
1237       request.  "-" if backend host is not available.
1238     * $method: HTTP method
1239     * $path:  Request  path  including query.   For  CONNECT
1240       request, authority is recorded.
1241     * $path_without_query:  $path   up  to  the   first  '?'
1242       character.    For   CONNECT  request,   authority   is
1243       recorded.
1244     * $protocol_version:   HTTP  version   (e.g.,  HTTP/1.1,
1245       HTTP/2)
1246
1247     The  variable  can  be  enclosed  by  "{"  and  "}"  for
1248     disambiguation (e.g., ${remote_addr}).
1249
1250
1251     Default: ``$remote_addr - - [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"``
1252
1253 .. option:: --accesslog-write-early
1254
1255     Write  access  log  when   response  header  fields  are
1256     received   from  backend   rather   than  when   request
1257     transaction finishes.
1258
1259 .. option:: --errorlog-file=<PATH>
1260
1261     Set path to write error  log.  To reopen file, send USR1
1262     signal  to nghttpx.   stderr will  be redirected  to the
1263     error log file unless :option:`--errorlog-syslog` is used.
1264
1265     Default: ``/dev/stderr``
1266
1267 .. option:: --errorlog-syslog
1268
1269     Send  error log  to  syslog.  If  this  option is  used,
1270     :option:`--errorlog-file` option is ignored.
1271
1272 .. option:: --syslog-facility=<FACILITY>
1273
1274     Set syslog facility to <FACILITY>.
1275
1276     Default: ``daemon``
1277
1278
1279 HTTP
1280 ~~~~
1281
1282 .. option:: --add-x-forwarded-for
1283
1284     Append  X-Forwarded-For header  field to  the downstream
1285     request.
1286
1287 .. option:: --strip-incoming-x-forwarded-for
1288
1289     Strip X-Forwarded-For  header field from  inbound client
1290     requests.
1291
1292 .. option:: --no-add-x-forwarded-proto
1293
1294     Don't append  additional X-Forwarded-Proto  header field
1295     to  the   backend  request.   If  inbound   client  sets
1296     X-Forwarded-Proto,                                   and
1297     :option:`--no-strip-incoming-x-forwarded-proto`  option  is  used,
1298     they are passed to the backend.
1299
1300 .. option:: --no-strip-incoming-x-forwarded-proto
1301
1302     Don't strip X-Forwarded-Proto  header field from inbound
1303     client requests.
1304
1305 .. option:: --add-forwarded=<LIST>
1306
1307     Append RFC  7239 Forwarded header field  with parameters
1308     specified in comma delimited list <LIST>.  The supported
1309     parameters  are "by",  "for", "host",  and "proto".   By
1310     default,  the value  of  "by" and  "for" parameters  are
1311     obfuscated     string.     See     :option:`--forwarded-by`    and
1312     :option:`--forwarded-for` options respectively.  Note that nghttpx
1313     does  not  translate non-standard  X-Forwarded-\*  header
1314     fields into Forwarded header field, and vice versa.
1315
1316 .. option:: --strip-incoming-forwarded
1317
1318     Strip  Forwarded   header  field  from   inbound  client
1319     requests.
1320
1321 .. option:: --forwarded-by=(obfuscated|ip|<VALUE>)
1322
1323     Specify the parameter value sent out with "by" parameter
1324     of Forwarded  header field.   If "obfuscated"  is given,
1325     the string is randomly generated at startup.  If "ip" is
1326     given,   the  interface   address  of   the  connection,
1327     including port number, is  sent with "by" parameter.  In
1328     case of UNIX domain  socket, "localhost" is used instead
1329     of address and  port.  User can also  specify the static
1330     obfuscated string.  The limitation is that it must start
1331     with   "_",  and   only   consists   of  character   set
1332     [A-Za-z0-9._-], as described in RFC 7239.
1333
1334     Default: ``obfuscated``
1335
1336 .. option:: --forwarded-for=(obfuscated|ip)
1337
1338     Specify  the   parameter  value  sent  out   with  "for"
1339     parameter of Forwarded header field.  If "obfuscated" is
1340     given, the string is  randomly generated for each client
1341     connection.  If "ip" is given, the remote client address
1342     of  the connection,  without port  number, is  sent with
1343     "for"  parameter.   In  case   of  UNIX  domain  socket,
1344     "localhost" is used instead of address.
1345
1346     Default: ``obfuscated``
1347
1348 .. option:: --no-via
1349
1350     Don't append to  Via header field.  If  Via header field
1351     is received, it is left unaltered.
1352
1353 .. option:: --no-strip-incoming-early-data
1354
1355     Don't strip Early-Data header  field from inbound client
1356     requests.
1357
1358 .. option:: --no-location-rewrite
1359
1360     Don't  rewrite location  header field  in default  mode.
1361     When :option:`--http2-proxy`  is used, location header  field will
1362     not be altered regardless of this option.
1363
1364 .. option:: --host-rewrite
1365
1366     Rewrite  host and  :authority header  fields in  default
1367     mode.  When  :option:`--http2-proxy` is  used, these  headers will
1368     not be altered regardless of this option.
1369
1370 .. option:: --altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1371
1372     Specify   protocol  ID,   port,  host   and  origin   of
1373     alternative service.  <HOST>,  <ORIGIN> and <PARAMS> are
1374     optional.   Empty <HOST>  and <ORIGIN>  are allowed  and
1375     they  are treated  as  nothing is  specified.  They  are
1376     advertised  in alt-svc  header  field  only in  HTTP/1.1
1377     frontend.   This option  can be  used multiple  times to
1378     specify multiple alternative services.
1379     Example: :option:`--altsvc`\="h2,443,,,ma=3600; persist=1'
1380
1381 .. option:: --http2-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1382
1383     Just like :option:`--altsvc` option, but  this altsvc is only sent
1384     in HTTP/2 frontend.
1385
1386 .. option:: --add-request-header=<HEADER>
1387
1388     Specify additional header field to add to request header
1389     set.  This  option just  appends header field  and won't
1390     replace anything  already set.  This option  can be used
1391     several  times   to  specify  multiple   header  fields.
1392     Example: :option:`--add-request-header`\="foo: bar"
1393
1394 .. option:: --add-response-header=<HEADER>
1395
1396     Specify  additional  header  field to  add  to  response
1397     header set.   This option just appends  header field and
1398     won't replace anything already  set.  This option can be
1399     used several  times to  specify multiple  header fields.
1400     Example: :option:`--add-response-header`\="foo: bar"
1401
1402 .. option:: --request-header-field-buffer=<SIZE>
1403
1404     Set maximum buffer size for incoming HTTP request header
1405     field list.  This is the sum of header name and value in
1406     bytes.   If  trailer  fields  exist,  they  are  counted
1407     towards this number.
1408
1409     Default: ``64K``
1410
1411 .. option:: --max-request-header-fields=<N>
1412
1413     Set  maximum  number  of incoming  HTTP  request  header
1414     fields.   If  trailer  fields exist,  they  are  counted
1415     towards this number.
1416
1417     Default: ``100``
1418
1419 .. option:: --response-header-field-buffer=<SIZE>
1420
1421     Set  maximum  buffer  size for  incoming  HTTP  response
1422     header field list.   This is the sum of  header name and
1423     value  in  bytes.  If  trailer  fields  exist, they  are
1424     counted towards this number.
1425
1426     Default: ``64K``
1427
1428 .. option:: --max-response-header-fields=<N>
1429
1430     Set  maximum number  of  incoming  HTTP response  header
1431     fields.   If  trailer  fields exist,  they  are  counted
1432     towards this number.
1433
1434     Default: ``500``
1435
1436 .. option:: --error-page=(<CODE>|*)=<PATH>
1437
1438     Set file path  to custom error page  served when nghttpx
1439     originally  generates  HTTP  error status  code  <CODE>.
1440     <CODE> must be greater than or equal to 400, and at most
1441     599.  If "\*"  is used instead of <CODE>,  it matches all
1442     HTTP  status  code.  If  error  status  code comes  from
1443     backend server, the custom error pages are not used.
1444
1445 .. option:: --server-name=<NAME>
1446
1447     Change server response header field value to <NAME>.
1448
1449     Default: ``nghttpx``
1450
1451 .. option:: --no-server-rewrite
1452
1453     Don't rewrite server header field in default mode.  When
1454     :option:`--http2-proxy` is used, these headers will not be altered
1455     regardless of this option.
1456
1457 .. option:: --redirect-https-port=<PORT>
1458
1459     Specify the port number which appears in Location header
1460     field  when  redirect  to  HTTPS  URI  is  made  due  to
1461     "redirect-if-not-tls" parameter in :option:`--backend` option.
1462
1463     Default: ``443``
1464
1465
1466 API
1467 ~~~
1468
1469 .. option:: --api-max-request-body=<SIZE>
1470
1471     Set the maximum size of request body for API request.
1472
1473     Default: ``32M``
1474
1475
1476 DNS
1477 ~~~
1478
1479 .. option:: --dns-cache-timeout=<DURATION>
1480
1481     Set duration that cached DNS results remain valid.  Note
1482     that nghttpx caches the unsuccessful results as well.
1483
1484     Default: ``10s``
1485
1486 .. option:: --dns-lookup-timeout=<DURATION>
1487
1488     Set timeout that  DNS server is given to  respond to the
1489     initial  DNS  query.  For  the  2nd  and later  queries,
1490     server is  given time based  on this timeout, and  it is
1491     scaled linearly.
1492
1493     Default: ``5s``
1494
1495 .. option:: --dns-max-try=<N>
1496
1497     Set the number of DNS query before nghttpx gives up name
1498     lookup.
1499
1500     Default: ``2``
1501
1502 .. option:: --frontend-max-requests=<N>
1503
1504     The number  of requests that single  frontend connection
1505     can process.  For HTTP/2, this  is the number of streams
1506     in  one  HTTP/2 connection.   For  HTTP/1,  this is  the
1507     number of keep alive requests.  This is hint to nghttpx,
1508     and it  may allow additional few  requests.  The default
1509     value is unlimited.
1510
1511
1512 Debug
1513 ~~~~~
1514
1515 .. option:: --frontend-http2-dump-request-header=<PATH>
1516
1517     Dumps request headers received by HTTP/2 frontend to the
1518     file denoted  in <PATH>.  The  output is done  in HTTP/1
1519     header field format and each header block is followed by
1520     an empty line.  This option  is not thread safe and MUST
1521     NOT be used with option :option:`-n`\<N>, where <N> >= 2.
1522
1523 .. option:: --frontend-http2-dump-response-header=<PATH>
1524
1525     Dumps response headers sent  from HTTP/2 frontend to the
1526     file denoted  in <PATH>.  The  output is done  in HTTP/1
1527     header field format and each header block is followed by
1528     an empty line.  This option  is not thread safe and MUST
1529     NOT be used with option :option:`-n`\<N>, where <N> >= 2.
1530
1531 .. option:: -o, --frontend-frame-debug
1532
1533     Print HTTP/2 frames in  frontend to stderr.  This option
1534     is  not thread  safe and  MUST NOT  be used  with option
1535     :option:`-n`\=N, where N >= 2.
1536
1537
1538 Process
1539 ~~~~~~~
1540
1541 .. option:: -D, --daemon
1542
1543     Run in a background.  If :option:`-D` is used, the current working
1544     directory is changed to '*/*'.
1545
1546 .. option:: --pid-file=<PATH>
1547
1548     Set path to save PID of this program.
1549
1550 .. option:: --user=<USER>
1551
1552     Run this program as <USER>.   This option is intended to
1553     be used to drop root privileges.
1554
1555 .. option:: --single-process
1556
1557     Run this program in a  single process mode for debugging
1558     purpose.  Without this option,  nghttpx creates at least
1559     2 processes: main and  worker processes.  If this option
1560     is  used, main  and  worker are  unified  into a  single
1561     process.   nghttpx still  spawns  additional process  if
1562     neverbleed  is used.   In the  single process  mode, the
1563     signal handling feature is disabled.
1564
1565 .. option:: --max-worker-processes=<N>
1566
1567     The maximum number of  worker processes.  nghttpx spawns
1568     new worker  process when  it reloads  its configuration.
1569     The previous worker  process enters graceful termination
1570     period and will terminate  when it finishes handling the
1571     existing    connections.     However,    if    reloading
1572     configurations  happen   very  frequently,   the  worker
1573     processes might be piled up if they take a bit long time
1574     to finish  the existing connections.  With  this option,
1575     if  the number  of  worker processes  exceeds the  given
1576     value,   the  oldest   worker   process  is   terminated
1577     immediately.  Specifying 0 means no  limit and it is the
1578     default behaviour.
1579
1580 .. option:: --worker-process-grace-shutdown-period=<DURATION>
1581
1582     Maximum  period  for  a   worker  process  to  terminate
1583     gracefully.  When  a worker  process enters  in graceful
1584     shutdown   period  (e.g.,   when  nghttpx   reloads  its
1585     configuration)  and  it  does not  finish  handling  the
1586     existing connections in the given  period of time, it is
1587     immediately terminated.  Specifying 0 means no limit and
1588     it is the default behaviour.
1589
1590
1591 Scripting
1592 ~~~~~~~~~
1593
1594 .. option:: --mruby-file=<PATH>
1595
1596     Set mruby script file
1597
1598 .. option:: --ignore-per-pattern-mruby-error
1599
1600     Ignore mruby compile error  for per-pattern mruby script
1601     file.  If error  occurred, it is treated as  if no mruby
1602     file were specified for the pattern.
1603
1604
1605 HTTP/3 and QUIC
1606 ~~~~~~~~~~~~~~~
1607
1608 .. option:: --frontend-quic-idle-timeout=<DURATION>
1609
1610     Specify an idle timeout for QUIC connection.
1611
1612     Default: ``30s``
1613
1614 .. option:: --frontend-quic-debug-log
1615
1616     Output QUIC debug log to */dev/stderr.*
1617
1618 .. option:: --quic-bpf-program-file=<PATH>
1619
1620     Specify a path to  eBPF program file reuseport_kern.o to
1621     direct  an  incoming  QUIC  UDP datagram  to  a  correct
1622     socket.
1623
1624     Default: ``/usr/local/lib/nghttp2/reuseport_kern.o``
1625
1626 .. option:: --frontend-quic-early-data
1627
1628     Enable early data on frontend QUIC connections.  nghttpx
1629     sends "Early-Data" header field to a backend server if a
1630     request is received in early  data and handshake has not
1631     finished.  All backend servers should deal with possibly
1632     replayed requests.
1633
1634 .. option:: --frontend-quic-qlog-dir=<DIR>
1635
1636     Specify a  directory where  a qlog  file is  written for
1637     frontend QUIC  connections.  A qlog file  is created per
1638     each QUIC  connection.  The  file name is  ISO8601 basic
1639     format, followed by "-", server Source Connection ID and
1640     ".qlog".
1641
1642 .. option:: --frontend-quic-require-token
1643
1644     Require an address validation  token for a frontend QUIC
1645     connection.   Server sends  a token  in Retry  packet or
1646     NEW_TOKEN frame in the previous connection.
1647
1648 .. option:: --frontend-quic-congestion-controller=<CC>
1649
1650     Specify a congestion controller algorithm for a frontend
1651     QUIC  connection.   <CC>  should be  either  "cubic"  or
1652     "bbr".
1653
1654     Default: ``cubic``
1655
1656 .. option:: --frontend-quic-secret-file=<PATH>
1657
1658     Path to file that contains secure random data to be used
1659     as QUIC keying materials.  It is used to derive keys for
1660     encrypting tokens and Connection IDs.  It is not used to
1661     encrypt  QUIC  packets.  Each  line  of  this file  must
1662     contain  exactly  136  bytes  hex-encoded  string  (when
1663     decoded the byte string is  68 bytes long).  The first 2
1664     bits of  decoded byte  string are  used to  identify the
1665     keying material.  An  empty line or a  line which starts
1666     '#'  is ignored.   The file  can contain  more than  one
1667     keying materials.  Because the  identifier is 2 bits, at
1668     most 4 keying materials are  read and the remaining data
1669     is discarded.  The first keying  material in the file is
1670     primarily  used for  encryption and  decryption for  new
1671     connection.  The other ones are used to decrypt data for
1672     the  existing connections.   Specifying multiple  keying
1673     materials enables  key rotation.   Please note  that key
1674     rotation  does  not  occur automatically.   User  should
1675     update  files  or  change  options  values  and  restart
1676     nghttpx gracefully.   If opening  or reading  given file
1677     fails, all loaded keying  materials are discarded and it
1678     is treated as if none of  this option is given.  If this
1679     option is not  given or an error  occurred while opening
1680     or  reading  a  file,  a keying  material  is  generated
1681     internally on startup and reload.
1682
1683 .. option:: --quic-server-id=<HEXSTRING>
1684
1685     Specify server  ID encoded in Connection  ID to identify
1686     this  particular  server  instance.   Connection  ID  is
1687     encrypted and  this part is  not visible in  public.  It
1688     must be 4  bytes long and must be encoded  in hex string
1689     (which is 8  bytes long).  If this option  is omitted, a
1690     random   server  ID   is   generated   on  startup   and
1691     configuration reload.
1692
1693 .. option:: --frontend-quic-initial-rtt=<DURATION>
1694
1695     Specify the initial RTT of the frontend QUIC connection.
1696
1697     Default: ``333ms``
1698
1699 .. option:: --no-quic-bpf
1700
1701     Disable eBPF.
1702
1703 .. option:: --frontend-http3-window-size=<SIZE>
1704
1705     Sets  the  per-stream  initial  window  size  of  HTTP/3
1706     frontend connection.
1707
1708     Default: ``256K``
1709
1710 .. option:: --frontend-http3-connection-window-size=<SIZE>
1711
1712     Sets the  per-connection window size of  HTTP/3 frontend
1713     connection.
1714
1715     Default: ``1M``
1716
1717 .. option:: --frontend-http3-max-window-size=<SIZE>
1718
1719     Sets  the  maximum  per-stream  window  size  of  HTTP/3
1720     frontend connection.  The window  size is adjusted based
1721     on the receiving rate of stream data.  The initial value
1722     is the  value specified  by :option:`--frontend-http3-window-size`
1723     and the window size grows up to <SIZE> bytes.
1724
1725     Default: ``6M``
1726
1727 .. option:: --frontend-http3-max-connection-window-size=<SIZE>
1728
1729     Sets the  maximum per-connection  window size  of HTTP/3
1730     frontend connection.  The window  size is adjusted based
1731     on the receiving rate of stream data.  The initial value
1732     is         the         value        specified         by
1733     :option:`--frontend-http3-connection-window-size`  and the  window
1734     size grows up to <SIZE> bytes.
1735
1736     Default: ``8M``
1737
1738 .. option:: --frontend-http3-max-concurrent-streams=<N>
1739
1740     Set the maximum number of  the concurrent streams in one
1741     frontend HTTP/3 connection.
1742
1743     Default: ``100``
1744
1745
1746 Misc
1747 ~~~~
1748
1749 .. option:: --conf=<PATH>
1750
1751     Load  configuration  from   <PATH>.   Please  note  that
1752     nghttpx always  tries to read the  default configuration
1753     file if :option:`--conf` is not given.
1754
1755     Default: ``/etc/nghttpx/nghttpx.conf``
1756
1757 .. option:: --include=<PATH>
1758
1759     Load additional configurations from <PATH>.  File <PATH>
1760     is  read  when  configuration  parser  encountered  this
1761     option.  This option can be used multiple times, or even
1762     recursively.
1763
1764 .. option:: -v, --version
1765
1766     Print version and exit.
1767
1768 .. option:: -h, --help
1769
1770     Print this help and exit.
1771
1772
1773
1774 The <SIZE> argument is an integer and an optional unit (e.g., 10K is
1775 10 * 1024).  Units are K, M and G (powers of 1024).
1776
1777 The <DURATION> argument is an integer and an optional unit (e.g., 1s
1778 is 1 second and 500ms is 500 milliseconds).  Units are h, m, s or ms
1779 (hours, minutes, seconds and milliseconds, respectively).  If a unit
1780 is omitted, a second is used as unit.
1781
1782 FILES
1783 -----
1784
1785 */etc/nghttpx/nghttpx.conf*
1786   The default configuration file path nghttpx searches at startup.
1787   The configuration file path can be changed using :option:`--conf`
1788   option.
1789
1790   Those lines which are staring ``#`` are treated as comment.
1791
1792   The option name in the configuration file is the long command-line
1793   option name with leading ``--`` stripped (e.g., ``frontend``).  Put
1794   ``=`` between option name and value.  Don't put extra leading or
1795   trailing spaces.
1796
1797   When specifying arguments including characters which have special
1798   meaning to a shell, we usually use quotes so that shell does not
1799   interpret them.  When writing this configuration file, quotes for
1800   this purpose must not be used.  For example, specify additional
1801   request header field, do this:
1802
1803   .. code-block:: text
1804
1805     add-request-header=foo: bar
1806
1807   instead of:
1808
1809   .. code-block:: text
1810
1811     add-request-header="foo: bar"
1812
1813   The options which do not take argument in the command-line *take*
1814   argument in the configuration file.  Specify ``yes`` as an argument
1815   (e.g., ``http2-proxy=yes``).  If other string is given, it is
1816   ignored.
1817
1818   To specify private key and certificate file which are given as
1819   positional arguments in command-line, use ``private-key-file`` and
1820   ``certificate-file``.
1821
1822   :option:`--conf` option cannot be used in the configuration file and
1823   will be ignored if specified.
1824
1825 Error log
1826   Error log is written to stderr by default.  It can be configured
1827   using :option:`--errorlog-file`.  The format of log message is as
1828   follows:
1829
1830   <datetime> <main-pid> <current-pid> <thread-id> <level> (<filename>:<line>) <msg>
1831
1832   <datetime>
1833     It is a combination of date and time when the log is written.  It
1834     is in ISO 8601 format.
1835
1836   <main-pid>
1837     It is a main process ID.
1838
1839   <current-pid>
1840     It is a process ID which writes this log.
1841
1842   <thread-id>
1843     It is a thread ID which writes this log.  It would be unique
1844     within <current-pid>.
1845
1846   <filename> and <line>
1847     They are source file name, and line number which produce this log.
1848
1849   <msg>
1850     It is a log message body.
1851
1852 SIGNALS
1853 -------
1854
1855 SIGQUIT
1856   Shutdown gracefully.  First accept pending connections and stop
1857   accepting connection.  After all connections are handled, nghttpx
1858   exits.
1859
1860 SIGHUP
1861   Reload configuration file given in :option:`--conf`.
1862
1863 SIGUSR1
1864   Reopen log files.
1865
1866 SIGUSR2
1867
1868   Fork and execute nghttpx.  It will execute the binary in the same
1869   path with same command-line arguments and environment variables.  As
1870   of nghttpx version 1.20.0, the new main process sends SIGQUIT to the
1871   original main process when it is ready to serve requests.  For the
1872   earlier versions of nghttpx, user has to send SIGQUIT to the
1873   original main process.
1874
1875   The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
1876   is usually used to execute new binary, and the main process is newly
1877   spawned.  On the other hand, the latter just reloads configuration
1878   file, and the same main process continues to exist.
1879
1880 .. note::
1881
1882   nghttpx consists of multiple processes: one process for processing
1883   these signals, and another one for processing requests.  The former
1884   spawns the latter.  The former is called main process, and the
1885   latter is called worker process.  If neverbleed is enabled, the
1886   worker process spawns neverbleed daemon process which does RSA key
1887   processing.  The above signal must be sent to the main process.  If
1888   the other processes received one of them, it is ignored.  This
1889   behaviour of these processes may change in the future release.  In
1890   other words, in the future release, the processes other than main
1891   process may terminate upon the reception of these signals.
1892   Therefore these signals should not be sent to the processes other
1893   than main process.
1894
1895 SERVER PUSH
1896 -----------
1897
1898 nghttpx supports HTTP/2 server push in default mode with Link header
1899 field.  nghttpx looks for Link header field (`RFC 5988
1900 <http://tools.ietf.org/html/rfc5988>`_) in response headers from
1901 backend server and extracts URI-reference with parameter
1902 ``rel=preload`` (see `preload
1903 <http://w3c.github.io/preload/#interoperability-with-http-link-header>`_)
1904 and pushes those URIs to the frontend client. Here is a sample Link
1905 header field to initiate server push:
1906
1907 .. code-block:: text
1908
1909   Link: </fonts/font.woff>; rel=preload
1910   Link: </css/theme.css>; rel=preload
1911
1912 Currently, the following restriction is applied for server push:
1913
1914 1. The associated stream must have method "GET" or "POST".  The
1915    associated stream's status code must be 200.
1916
1917 This limitation may be loosened in the future release.
1918
1919 nghttpx also supports server push if both frontend and backend are
1920 HTTP/2 in default mode.  In this case, in addition to server push via
1921 Link header field, server push from backend is forwarded to frontend
1922 HTTP/2 session.
1923
1924 HTTP/2 server push will be disabled if :option:`--http2-proxy` is
1925 used.
1926
1927 UNIX DOMAIN SOCKET
1928 ------------------
1929
1930 nghttpx supports UNIX domain socket with a filename for both frontend
1931 and backend connections.
1932
1933 Please note that current nghttpx implementation does not delete a
1934 socket with a filename.  And on start up, if nghttpx detects that the
1935 specified socket already exists in the file system, nghttpx first
1936 deletes it.  However, if SIGUSR2 is used to execute new binary and
1937 both old and new configurations use same filename, new binary does not
1938 delete the socket and continues to use it.
1939
1940 OCSP STAPLING
1941 -------------
1942
1943 OCSP query is done using external Python script
1944 ``fetch-ocsp-response``, which has been originally developed in Perl
1945 as part of h2o project (https://github.com/h2o/h2o), and was
1946 translated into Python.
1947
1948 The script file is usually installed under
1949 ``$(prefix)/share/nghttp2/`` directory.  The actual path to script can
1950 be customized using :option:`--fetch-ocsp-response-file` option.
1951
1952 If OCSP query is failed, previous OCSP response, if any, is continued
1953 to be used.
1954
1955 :option:`--fetch-ocsp-response-file` option provides wide range of
1956 possibility to manage OCSP response.  It can take an arbitrary script
1957 or executable.  The requirement is that it supports the command-line
1958 interface of ``fetch-ocsp-response`` script, and it must return a
1959 valid DER encoded OCSP response on success.  It must return exit code
1960 0 on success, and 75 for temporary error, and the other error code for
1961 generic failure.  For large cluster of servers, it is not efficient
1962 for each server to perform OCSP query using ``fetch-ocsp-response``.
1963 Instead, you can retrieve OCSP response in some way, and store it in a
1964 disk or a shared database.  Then specify a program in
1965 :option:`--fetch-ocsp-response-file` to fetch it from those stores.
1966 This could provide a way to share the OCSP response between fleet of
1967 servers, and also any OCSP query strategy can be applied which may be
1968 beyond the ability of nghttpx itself or ``fetch-ocsp-response``
1969 script.
1970
1971 TLS SESSION RESUMPTION
1972 ----------------------
1973
1974 nghttpx supports TLS session resumption through both session ID and
1975 session ticket.
1976
1977 SESSION ID RESUMPTION
1978 ~~~~~~~~~~~~~~~~~~~~~
1979
1980 By default, session ID is shared by all worker threads.
1981
1982 If :option:`--tls-session-cache-memcached` is given, nghttpx will
1983 insert serialized session data to memcached with
1984 ``nghttpx:tls-session-cache:`` + lowercase hex string of session ID
1985 as a memcached entry key, with expiry time 12 hours.  Session timeout
1986 is set to 12 hours.
1987
1988 By default, connections to memcached server are not encrypted.  To
1989 enable encryption, use ``tls`` keyword in
1990 :option:`--tls-session-cache-memcached` option.
1991
1992 TLS SESSION TICKET RESUMPTION
1993 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1994
1995 By default, session ticket is shared by all worker threads.  The
1996 automatic key rotation is also enabled by default.  Every an hour, new
1997 encryption key is generated, and previous encryption key becomes
1998 decryption only key.  We set session timeout to 12 hours, and thus we
1999 keep at most 12 keys.
2000
2001 If :option:`--tls-ticket-key-memcached` is given, encryption keys are
2002 retrieved from memcached.  nghttpx just reads keys from memcached; one
2003 has to deploy key generator program to update keys frequently (e.g.,
2004 every 1 hour).  The example key generator tlsticketupdate.go is
2005 available under contrib directory in nghttp2 archive.  The memcached
2006 entry key is ``nghttpx:tls-ticket-key``.  The data format stored in
2007 memcached is the binary format described below:
2008
2009 .. code-block:: text
2010
2011     +--------------+-------+----------------+
2012     | VERSION (4)  |LEN (2)|KEY(48 or 80) ...
2013     +--------------+-------+----------------+
2014                    ^                        |
2015                    |                        |
2016                    +------------------------+
2017                    (LEN, KEY) pair can be repeated
2018
2019 All numbers in the above figure is bytes.  All integer fields are
2020 network byte order.
2021
2022 First 4 bytes integer VERSION field, which must be 1.  The 2 bytes
2023 integer LEN field gives the length of following KEY field, which
2024 contains key.  If :option:`--tls-ticket-key-cipher`\=aes-128-cbc is
2025 used, LEN must be 48.  If
2026 :option:`--tls-ticket-key-cipher`\=aes-256-cbc is used, LEN must be
2027 80.  LEN and KEY pair can be repeated multiple times to store multiple
2028 keys.  The key appeared first is used as encryption key.  All the
2029 remaining keys are used as decryption only.
2030
2031 By default, connections to memcached server are not encrypted.  To
2032 enable encryption, use ``tls`` keyword in
2033 :option:`--tls-ticket-key-memcached` option.
2034
2035 If :option:`--tls-ticket-key-file` is given, encryption key is read
2036 from the given file.  In this case, nghttpx does not rotate key
2037 automatically.  To rotate key, one has to restart nghttpx (see
2038 SIGNALS).
2039
2040 CERTIFICATE TRANSPARENCY
2041 ------------------------
2042
2043 nghttpx supports TLS ``signed_certificate_timestamp`` extension (`RFC
2044 6962 <https://tools.ietf.org/html/rfc6962>`_).  The relevant options
2045 are :option:`--tls-sct-dir` and ``sct-dir`` parameter in
2046 :option:`--subcert`.  They takes a directory, and nghttpx reads all
2047 files whose extension is ``.sct`` under the directory.  The ``*.sct``
2048 files are encoded as ``SignedCertificateTimestamp`` struct described
2049 in `section 3.2 of RFC 69662
2050 <https://tools.ietf.org/html/rfc6962#section-3.2>`_.  This format is
2051 the same one used by `nginx-ct
2052 <https://github.com/grahamedgecombe/nginx-ct>`_ and `mod_ssl_ct
2053 <https://httpd.apache.org/docs/trunk/mod/mod_ssl_ct.html>`_.
2054 `ct-submit <https://github.com/grahamedgecombe/ct-submit>`_ can be
2055 used to submit certificates to log servers, and obtain the
2056 ``SignedCertificateTimestamp`` struct which can be used with nghttpx.
2057
2058 MRUBY SCRIPTING
2059 ---------------
2060
2061 .. warning::
2062
2063   The current mruby extension API is experimental and not frozen.  The
2064   API is subject to change in the future release.
2065
2066 .. warning::
2067
2068   Almost all string value returned from method, or attribute is a
2069   fresh new mruby string, which involves memory allocation, and
2070   copies.  Therefore, it is strongly recommended to store a return
2071   value in a local variable, and use it, instead of calling method or
2072   accessing attribute repeatedly.
2073
2074 nghttpx allows users to extend its capability using mruby scripts.
2075 nghttpx has 2 hook points to execute mruby script: request phase and
2076 response phase.  The request phase hook is invoked after all request
2077 header fields are received from client.  The response phase hook is
2078 invoked after all response header fields are received from backend
2079 server.  These hooks allows users to modify header fields, or common
2080 HTTP variables, like authority or request path, and even return custom
2081 response without forwarding request to backend servers.
2082
2083 There are 2 levels of mruby script invocations: global and
2084 per-pattern.  The global mruby script is set by :option:`--mruby-file`
2085 option and is called for all requests.  The per-pattern mruby script
2086 is set by "mruby" parameter in :option:`-b` option.  It is invoked for
2087 a request which matches the particular pattern.  The order of hook
2088 invocation is: global request phase hook, per-pattern request phase
2089 hook, per-pattern response phase hook, and finally global response
2090 phase hook.  If a hook returns a response, any later hooks are not
2091 invoked.  The global request hook is invoked before the pattern
2092 matching is made and changing request path may affect the pattern
2093 matching.
2094
2095 Please note that request and response hooks of per-pattern mruby
2096 script for a single request might not come from the same script.  This
2097 might happen after a request hook is executed, backend failed for some
2098 reason, and at the same time, backend configuration is replaced by API
2099 request, and then the request uses new configuration on retry.  The
2100 response hook from new configuration, if it is specified, will be
2101 invoked.
2102
2103 The all mruby script will be evaluated once per thread on startup, and
2104 it must instantiate object and evaluate it as the return value (e.g.,
2105 ``App.new``).  This object is called app object.  If app object
2106 defines ``on_req`` method, it is called with :rb:class:`Nghttpx::Env`
2107 object on request hook.  Similarly, if app object defines ``on_resp``
2108 method, it is called with :rb:class:`Nghttpx::Env` object on response
2109 hook.  For each method invocation, user can can access
2110 :rb:class:`Nghttpx::Request` and :rb:class:`Nghttpx::Response` objects
2111 via :rb:attr:`Nghttpx::Env#req` and :rb:attr:`Nghttpx::Env#resp`
2112 respectively.
2113
2114 .. rb:module:: Nghttpx
2115
2116 .. rb:const:: REQUEST_PHASE
2117
2118     Constant to represent request phase.
2119
2120 .. rb:const:: RESPONSE_PHASE
2121
2122     Constant to represent response phase.
2123
2124 .. rb:class:: Env
2125
2126     Object to represent current request specific context.
2127
2128     .. rb:attr_reader:: req
2129
2130         Return :rb:class:`Request` object.
2131
2132     .. rb:attr_reader:: resp
2133
2134         Return :rb:class:`Response` object.
2135
2136     .. rb:attr_reader:: ctx
2137
2138         Return Ruby hash object.  It persists until request finishes.
2139         So values set in request phase hook can be retrieved in
2140         response phase hook.
2141
2142     .. rb:attr_reader:: phase
2143
2144         Return the current phase.
2145
2146     .. rb:attr_reader:: remote_addr
2147
2148         Return IP address of a remote client.  If connection is made
2149         via UNIX domain socket, this returns the string "localhost".
2150
2151     .. rb:attr_reader:: server_addr
2152
2153         Return address of server that accepted the connection.  This
2154         is a string which specified in :option:`--frontend` option,
2155         excluding port number, and not a resolved IP address.  For
2156         UNIX domain socket, this is a path to UNIX domain socket.
2157
2158     .. rb:attr_reader:: server_port
2159
2160         Return port number of the server frontend which accepted the
2161         connection from client.
2162
2163     .. rb:attr_reader:: tls_used
2164
2165         Return true if TLS is used on the connection.
2166
2167     .. rb:attr_reader:: tls_sni
2168
2169         Return the TLS SNI value which client sent in this connection.
2170
2171     .. rb:attr_reader:: tls_client_fingerprint_sha256
2172
2173         Return the SHA-256 fingerprint of a client certificate.
2174
2175     .. rb:attr_reader:: tls_client_fingerprint_sha1
2176
2177         Return the SHA-1 fingerprint of a client certificate.
2178
2179     .. rb:attr_reader:: tls_client_issuer_name
2180
2181         Return the issuer name of a client certificate.
2182
2183     .. rb:attr_reader:: tls_client_subject_name
2184
2185         Return the subject name of a client certificate.
2186
2187     .. rb:attr_reader:: tls_client_serial
2188
2189         Return the serial number of a client certificate.
2190
2191     .. rb:attr_reader:: tls_client_not_before
2192
2193         Return the start date of a client certificate in seconds since
2194         the epoch.
2195
2196     .. rb:attr_reader:: tls_client_not_after
2197
2198         Return the end date of a client certificate in seconds since
2199         the epoch.
2200
2201     .. rb:attr_reader:: tls_cipher
2202
2203         Return a TLS cipher negotiated in this connection.
2204
2205     .. rb:attr_reader:: tls_protocol
2206
2207         Return a TLS protocol version negotiated in this connection.
2208
2209     .. rb:attr_reader:: tls_session_id
2210
2211         Return a session ID for this connection in hex string.
2212
2213     .. rb:attr_reader:: tls_session_reused
2214
2215         Return true if, and only if a SSL/TLS session is reused.
2216
2217     .. rb:attr_reader:: alpn
2218
2219         Return ALPN identifier negotiated in this connection.
2220
2221     .. rb:attr_reader:: tls_handshake_finished
2222
2223         Return true if SSL/TLS handshake has finished.  If it returns
2224         false in the request phase hook, the request is received in
2225         TLSv1.3 early data (0-RTT) and might be vulnerable to the
2226         replay attack.  nghttpx will send Early-Data header field to
2227         backend servers to indicate this.
2228
2229 .. rb:class:: Request
2230
2231     Object to represent request from client.  The modification to
2232     Request object is allowed only in request phase hook.
2233
2234     .. rb:attr_reader:: http_version_major
2235
2236         Return HTTP major version.
2237
2238     .. rb:attr_reader:: http_version_minor
2239
2240         Return HTTP minor version.
2241
2242     .. rb:attr_accessor:: method
2243
2244         HTTP method.  On assignment, copy of given value is assigned.
2245         We don't accept arbitrary method name.  We will document them
2246         later, but well known methods, like GET, PUT and POST, are all
2247         supported.
2248
2249     .. rb:attr_accessor:: authority
2250
2251         Authority (i.e., example.org), including optional port
2252         component .  On assignment, copy of given value is assigned.
2253
2254     .. rb:attr_accessor:: scheme
2255
2256         Scheme (i.e., http, https).  On assignment, copy of given
2257         value is assigned.
2258
2259     .. rb:attr_accessor:: path
2260
2261         Request path, including query component (i.e., /index.html).
2262         On assignment, copy of given value is assigned.  The path does
2263         not include authority component of URI.  This may include
2264         query component.  nghttpx makes certain normalization for
2265         path.  It decodes percent-encoding for unreserved characters
2266         (see https://tools.ietf.org/html/rfc3986#section-2.3), and
2267         resolves ".." and ".".  But it may leave characters which
2268         should be percent-encoded as is. So be careful when comparing
2269         path against desired string.
2270
2271     .. rb:attr_reader:: headers
2272
2273         Return Ruby hash containing copy of request header fields.
2274         Changing values in returned hash does not change request
2275         header fields actually used in request processing.  Use
2276         :rb:meth:`Nghttpx::Request#add_header` or
2277         :rb:meth:`Nghttpx::Request#set_header` to change request
2278         header fields.
2279
2280     .. rb:method:: add_header(key, value)
2281
2282         Add header entry associated with key.  The value can be single
2283         string or array of string.  It does not replace any existing
2284         values associated with key.
2285
2286     .. rb:method:: set_header(key, value)
2287
2288         Set header entry associated with key.  The value can be single
2289         string or array of string.  It replaces any existing values
2290         associated with key.
2291
2292     .. rb:method:: clear_headers
2293
2294         Clear all existing request header fields.
2295
2296     .. rb:method:: push(uri)
2297
2298         Initiate to push resource identified by *uri*.  Only HTTP/2
2299         protocol supports this feature.  For the other protocols, this
2300         method is noop.  *uri* can be absolute URI, absolute path or
2301         relative path to the current request.  For absolute or
2302         relative path, scheme and authority are inherited from the
2303         current request.  Currently, method is always GET.  nghttpx
2304         will issue request to backend servers to fulfill this request.
2305         The request and response phase hooks will be called for pushed
2306         resource as well.
2307
2308 .. rb:class:: Response
2309
2310     Object to represent response from backend server.
2311
2312     .. rb:attr_reader:: http_version_major
2313
2314         Return HTTP major version.
2315
2316     .. rb:attr_reader:: http_version_minor
2317
2318         Return HTTP minor version.
2319
2320     .. rb:attr_accessor:: status
2321
2322         HTTP status code.  It must be in the range [200, 999],
2323         inclusive.  The non-final status code is not supported in
2324         mruby scripting at the moment.
2325
2326     .. rb:attr_reader:: headers
2327
2328         Return Ruby hash containing copy of response header fields.
2329         Changing values in returned hash does not change response
2330         header fields actually used in response processing.  Use
2331         :rb:meth:`Nghttpx::Response#add_header` or
2332         :rb:meth:`Nghttpx::Response#set_header` to change response
2333         header fields.
2334
2335     .. rb:method:: add_header(key, value)
2336
2337         Add header entry associated with key.  The value can be single
2338         string or array of string.  It does not replace any existing
2339         values associated with key.
2340
2341     .. rb:method:: set_header(key, value)
2342
2343         Set header entry associated with key.  The value can be single
2344         string or array of string.  It replaces any existing values
2345         associated with key.
2346
2347     .. rb:method:: clear_headers
2348
2349         Clear all existing response header fields.
2350
2351     .. rb:method:: return(body)
2352
2353         Return custom response *body* to a client.  When this method
2354         is called in request phase hook, the request is not forwarded
2355         to the backend, and response phase hook for this request will
2356         not be invoked.  When this method is called in response phase
2357         hook, response from backend server is canceled and discarded.
2358         The status code and response header fields should be set
2359         before using this method.  To set status code, use
2360         :rb:attr:`Nghttpx::Response#status`.  If status code is not
2361         set, 200 is used.  To set response header fields,
2362         :rb:meth:`Nghttpx::Response#add_header` and
2363         :rb:meth:`Nghttpx::Response#set_header`.  When this method is
2364         invoked in response phase hook, the response headers are
2365         filled with the ones received from backend server.  To send
2366         completely custom header fields, first call
2367         :rb:meth:`Nghttpx::Response#clear_headers` to erase all
2368         existing header fields, and then add required header fields.
2369         It is an error to call this method twice for a given request.
2370
2371     .. rb:method:: send_info(status, headers)
2372
2373         Send non-final (informational) response to a client.  *status*
2374         must be in the range [100, 199], inclusive.  *headers* is a
2375         hash containing response header fields.  Its key must be a
2376         string, and the associated value must be either string or
2377         array of strings.  Since this is not a final response, even if
2378         this method is invoked, request is still forwarded to a
2379         backend unless :rb:meth:`Nghttpx::Response#return` is called.
2380         This method can be called multiple times.  It cannot be called
2381         after :rb:meth:`Nghttpx::Response#return` is called.
2382
2383 MRUBY EXAMPLES
2384 ~~~~~~~~~~~~~~
2385
2386 Modify request path:
2387
2388 .. code-block:: ruby
2389
2390     class App
2391       def on_req(env)
2392         env.req.path = "/apps#{env.req.path}"
2393       end
2394     end
2395
2396     App.new
2397
2398 Don't forget to instantiate and evaluate object at the last line.
2399
2400 Restrict permission of viewing a content to a specific client
2401 addresses:
2402
2403 .. code-block:: ruby
2404
2405     class App
2406       def on_req(env)
2407         allowed_clients = ["127.0.0.1", "::1"]
2408
2409         if env.req.path.start_with?("/log/") &&
2410            !allowed_clients.include?(env.remote_addr) then
2411           env.resp.status = 404
2412           env.resp.return "permission denied"
2413         end
2414       end
2415     end
2416
2417     App.new
2418
2419 API ENDPOINTS
2420 -------------
2421
2422 nghttpx exposes API endpoints to manipulate it via HTTP based API.  By
2423 default, API endpoint is disabled.  To enable it, add a dedicated
2424 frontend for API using :option:`--frontend` option with "api"
2425 parameter.  All requests which come from this frontend address, will
2426 be treated as API request.
2427
2428 The response is normally JSON dictionary, and at least includes the
2429 following keys:
2430
2431 status
2432   The status of the request processing.  The following values are
2433   defined:
2434
2435   Success
2436     The request was successful.
2437
2438   Failure
2439     The request was failed.  No change has been made.
2440
2441 code
2442   HTTP status code
2443
2444 Additionally, depending on the API endpoint, ``data`` key may be
2445 present, and its value contains the API endpoint specific data.
2446
2447 We wrote "normally", since nghttpx may return ordinal HTML response in
2448 some cases where the error has occurred before reaching API endpoint
2449 (e.g., header field is too large).
2450
2451 The following section describes available API endpoints.
2452
2453 POST /api/v1beta1/backendconfig
2454 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2455
2456 This API replaces the current backend server settings with the
2457 requested ones.  The request method should be POST, but PUT is also
2458 acceptable.  The request body must be nghttpx configuration file
2459 format.  For configuration file format, see `FILES`_ section.  The
2460 line separator inside the request body must be single LF (0x0A).
2461 Currently, only :option:`backend <--backend>` option is parsed, the
2462 others are simply ignored.  The semantics of this API is replace the
2463 current backend with the backend options in request body.  Describe
2464 the desired set of backend severs, and nghttpx makes it happen.  If
2465 there is no :option:`backend <--backend>` option is found in request
2466 body, the current set of backend is replaced with the :option:`backend
2467 <--backend>` option's default value, which is ``127.0.0.1,80``.
2468
2469 The replacement is done instantly without breaking existing
2470 connections or requests.  It also avoids any process creation as is
2471 the case with hot swapping with signals.
2472
2473 The one limitation is that only numeric IP address is allowed in
2474 :option:`backend <--backend>` in request body unless "dns" parameter
2475 is used while non numeric hostname is allowed in command-line or
2476 configuration file is read using :option:`--conf`.
2477
2478 GET /api/v1beta1/configrevision
2479 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2480
2481 This API returns configuration revision of the current nghttpx.  The
2482 configuration revision is opaque string, and it changes after each
2483 reloading by SIGHUP.  With this API, an external application knows
2484 that whether nghttpx has finished reloading its configuration by
2485 comparing the configuration revisions between before and after
2486 reloading.  It is recommended to disable persistent (keep-alive)
2487 connection for this purpose in order to avoid to send a request using
2488 the reused connection which may bound to an old process.
2489
2490 This API returns response including ``data`` key.  Its value is JSON
2491 object, and it contains at least the following key:
2492
2493 configRevision
2494   The configuration revision of the current nghttpx
2495
2496
2497 SEE ALSO
2498 --------
2499
2500 :manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`h2load(1)`