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