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, HTTP/1 and SPDY.
  18
  19 .. describe:: <PRIVATE_KEY>
  20
  21
  22     Set path  to server's private key.   Required unless :option:`-p`\,
  23     :option:`--client` or :option:`\--frontend-no-tls` are given.
  24
  25 .. describe:: <CERT>
  26
  27     Set path  to server's certificate.  Required  unless :option:`-p`\,
  28     :option:`--client` or  :option:`\--frontend-no-tls` are given.  To  make OCSP
  29     stapling work, this must be 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>
  41
  42     Set  backend  host  and   port.   The  multiple  backend
  43     addresses are  accepted by repeating this  option.  UNIX
  44     domain socket  can be  specified by prefixing  path name
  45     with "unix:" (e.g., unix:/var/run/backend.sock)
  46
  47     Default: ``127.0.0.1,80``
  48
  49 .. option:: -f, --frontend=<HOST,PORT>
  50
  51     Set  frontend  host and  port.   If  <HOST> is  '\*',  it
  52     assumes  all addresses  including  both  IPv4 and  IPv6.
  53     UNIX domain  socket can  be specified by  prefixing path
  54     name with "unix:" (e.g., unix:/var/run/nghttpx.sock)
  55
  56     Default: ``*,3000``
  57
  58 .. option:: --backlog=<N>
  59
  60     Set listen backlog size.
  61
  62     Default: ``512``
  63
  64 .. option:: --backend-ipv4
  65
  66     Resolve backend hostname to IPv4 address only.
  67
  68 .. option:: --backend-ipv6
  69
  70     Resolve backend hostname to IPv6 address only.
  71
  72 .. option:: --backend-http-proxy-uri=<URI>
  73
  74     Specify      proxy       URI      in       the      form
  75     http://[<USER>:<PASS>@]<PROXY>:<PORT>.    If   a   proxy
  76     requires  authentication,  specify  <USER>  and  <PASS>.
  77     Note that  they must be properly  percent-encoded.  This
  78     proxy  is used  when the  backend connection  is HTTP/2.
  79     First,  make  a CONNECT  request  to  the proxy  and  it
  80     connects  to the  backend  on behalf  of nghttpx.   This
  81     forms  tunnel.   After  that, nghttpx  performs  SSL/TLS
  82     handshake with  the downstream through the  tunnel.  The
  83     timeouts when connecting and  making CONNECT request can
  84     be     specified    by     :option:`--backend-read-timeout`    and
  85     :option:`--backend-write-timeout` options.
  86
  87
  88 Performance
  89 ~~~~~~~~~~~
  90
  91 .. option:: -n, --workers=<N>
  92
  93     Set the number of worker threads.
  94
  95     Default: ``1``
  96
  97 .. option:: --read-rate=<SIZE>
  98
  99     Set maximum  average read  rate on  frontend connection.
 100     Setting 0 to this option means read rate is unlimited.
 101
 102     Default: ``0``
 103
 104 .. option:: --read-burst=<SIZE>
 105
 106     Set  maximum read  burst  size  on frontend  connection.
 107     Setting  0  to this  option  means  read burst  size  is
 108     unlimited.
 109
 110     Default: ``0``
 111
 112 .. option:: --write-rate=<SIZE>
 113
 114     Set maximum  average write rate on  frontend connection.
 115     Setting 0 to this option means write rate is unlimited.
 116
 117     Default: ``0``
 118
 119 .. option:: --write-burst=<SIZE>
 120
 121     Set  maximum write  burst size  on frontend  connection.
 122     Setting  0 to  this  option means  write  burst size  is
 123     unlimited.
 124
 125     Default: ``0``
 126
 127 .. option:: --worker-read-rate=<SIZE>
 128
 129     Set maximum average read rate on frontend connection per
 130     worker.  Setting  0 to  this option  means read  rate is
 131     unlimited.  Not implemented yet.
 132
 133     Default: ``0``
 134
 135 .. option:: --worker-read-burst=<SIZE>
 136
 137     Set maximum  read burst size on  frontend connection per
 138     worker.  Setting 0 to this  option means read burst size
 139     is unlimited.  Not implemented yet.
 140
 141     Default: ``0``
 142
 143 .. option:: --worker-write-rate=<SIZE>
 144
 145     Set maximum  average write  rate on  frontend connection
 146     per worker.  Setting  0 to this option  means write rate
 147     is unlimited.  Not implemented yet.
 148
 149     Default: ``0``
 150
 151 .. option:: --worker-write-burst=<SIZE>
 152
 153     Set maximum write burst  size on frontend connection per
 154     worker.  Setting 0 to this option means write burst size
 155     is unlimited.  Not implemented yet.
 156
 157     Default: ``0``
 158
 159 .. option:: --worker-frontend-connections=<N>
 160
 161     Set maximum number  of simultaneous connections frontend
 162     accepts.  Setting 0 means unlimited.
 163
 164     Default: ``0``
 165
 166 .. option:: --backend-http2-connections-per-worker=<N>
 167
 168     Set  maximum number  of HTTP/2  connections per  worker.
 169     The  default  value is  0,  which  means the  number  of
 170     backend addresses specified by :option:`-b` option.
 171
 172 .. option:: --backend-http1-connections-per-host=<N>
 173
 174     Set   maximum  number   of  backend   concurrent  HTTP/1
 175     connections per host.  This option is meaningful when :option:`-s`
 176     option is used.  To limit  the number of connections per
 177     frontend        for       default        mode,       use
 178     :option:`--backend-http1-connections-per-frontend`\.
 179
 180     Default: ``8``
 181
 182 .. option:: --backend-http1-connections-per-frontend=<N>
 183
 184     Set   maximum  number   of  backend   concurrent  HTTP/1
 185     connections per frontend.  This  option is only used for
 186     default mode.   0 means unlimited.  To  limit the number
 187     of connections  per host for  HTTP/2 or SPDY  proxy mode
 188     (-s option), use :option:`--backend-http1-connections-per-host`\.
 189
 190     Default: ``0``
 191
 192 .. option:: --rlimit-nofile=<N>
 193
 194     Set maximum number of open files (RLIMIT_NOFILE) to <N>.
 195     If 0 is given, nghttpx does not set the limit.
 196
 197     Default: ``0``
 198
 199 .. option:: --backend-request-buffer=<SIZE>
 200
 201     Set buffer size used to store backend request.
 202
 203     Default: ``16K``
 204
 205 .. option:: --backend-response-buffer=<SIZE>
 206
 207     Set buffer size used to store backend response.
 208
 209     Default: ``16K``
 210
 211
 212 Timeout
 213 ~~~~~~~
 214
 215 .. option:: --frontend-http2-read-timeout=<DURATION>
 216
 217     Specify  read  timeout  for  HTTP/2  and  SPDY  frontend
 218     connection.
 219
 220     Default: ``3m``
 221
 222 .. option:: --frontend-read-timeout=<DURATION>
 223
 224     Specify read timeout for HTTP/1.1 frontend connection.
 225
 226     Default: ``3m``
 227
 228 .. option:: --frontend-write-timeout=<DURATION>
 229
 230     Specify write timeout for all frontend connections.
 231
 232     Default: ``30s``
 233
 234 .. option:: --stream-read-timeout=<DURATION>
 235
 236     Specify  read timeout  for HTTP/2  and SPDY  streams.  0
 237     means no timeout.
 238
 239     Default: ``0``
 240
 241 .. option:: --stream-write-timeout=<DURATION>
 242
 243     Specify write  timeout for  HTTP/2 and SPDY  streams.  0
 244     means no timeout.
 245
 246     Default: ``0``
 247
 248 .. option:: --backend-read-timeout=<DURATION>
 249
 250     Specify read timeout for backend connection.
 251
 252     Default: ``3m``
 253
 254 .. option:: --backend-write-timeout=<DURATION>
 255
 256     Specify write timeout for backend connection.
 257
 258     Default: ``30s``
 259
 260 .. option:: --backend-keep-alive-timeout=<DURATION>
 261
 262     Specify keep-alive timeout for backend connection.
 263
 264     Default: ``2s``
 265
 266 .. option:: --listener-disable-timeout=<DURATION>
 267
 268     After accepting  connection failed,  connection listener
 269     is disabled  for a given  amount of time.   Specifying 0
 270     disables this feature.
 271
 272     Default: ``0``
 273
 274
 275 SSL/TLS
 276 ~~~~~~~
 277
 278 .. option:: --ciphers=<SUITE>
 279
 280     Set allowed  cipher list.  The  format of the  string is
 281     described in OpenSSL ciphers(1).
 282
 283 .. option:: -k, --insecure
 284
 285     Don't  verify   backend  server's  certificate   if  :option:`-p`\,
 286     :option:`--client`    or    :option:`\--http2-bridge`     are    given    and
 287     :option:`--backend-no-tls` is not given.
 288
 289 .. option:: --cacert=<PATH>
 290
 291     Set path to trusted CA  certificate file if :option:`-p`\, :option:`--client`
 292     or :option:`--http2-bridge` are given  and :option:`\--backend-no-tls` is not
 293     given.  The file must be  in PEM format.  It can contain
 294     multiple  certificates.    If  the  linked   OpenSSL  is
 295     configured to  load system  wide certificates,  they are
 296     loaded at startup regardless of this option.
 297
 298 .. option:: --private-key-passwd-file=<PATH>
 299
 300     Path  to file  that contains  password for  the server's
 301     private key.   If none is  given and the private  key is
 302     password protected it'll be requested interactively.
 303
 304 .. option:: --subcert=<KEYPATH>:<CERTPATH>
 305
 306     Specify  additional certificate  and  private key  file.
 307     nghttpx will  choose certificates based on  the hostname
 308     indicated  by  client  using TLS  SNI  extension.   This
 309     option  can  be  used  multiple  times.   To  make  OCSP
 310     stapling work, <CERTPATH> must be absolute path.
 311
 312 .. option:: --backend-tls-sni-field=<HOST>
 313
 314     Explicitly  set the  content of  the TLS  SNI extension.
 315     This will default to the backend HOST name.
 316
 317 .. option:: --dh-param-file=<PATH>
 318
 319     Path to file that contains  DH parameters in PEM format.
 320     Without  this   option,  DHE   cipher  suites   are  not
 321     available.
 322
 323 .. option:: --npn-list=<LIST>
 324
 325     Comma delimited list of  ALPN protocol identifier sorted
 326     in the  order of preference.  That  means most desirable
 327     protocol comes  first.  This  is used  in both  ALPN and
 328     NPN.  The parameter must be  delimited by a single comma
 329     only  and any  white spaces  are  treated as  a part  of
 330     protocol string.
 331
 332     Default: ``h2,h2-16,h2-14,spdy/3.1,http/1.1``
 333
 334 .. option:: --verify-client
 335
 336     Require and verify client certificate.
 337
 338 .. option:: --verify-client-cacert=<PATH>
 339
 340     Path  to file  that contains  CA certificates  to verify
 341     client certificate.  The file must be in PEM format.  It
 342     can contain multiple certificates.
 343
 344 .. option:: --client-private-key-file=<PATH>
 345
 346     Path to  file that contains  client private key  used in
 347     backend client authentication.
 348
 349 .. option:: --client-cert-file=<PATH>
 350
 351     Path to  file that  contains client certificate  used in
 352     backend client authentication.
 353
 354 .. option:: --tls-proto-list=<LIST>
 355
 356     Comma delimited list of  SSL/TLS protocol to be enabled.
 357     The following protocols  are available: TLSv1.2, TLSv1.1
 358     and   TLSv1.0.    The   name   matching   is   done   in
 359     case-insensitive   manner.    The  parameter   must   be
 360     delimited by  a single comma  only and any  white spaces
 361     are treated as a part of protocol string.
 362
 363     Default: ``TLSv1.2,TLSv1.1``
 364
 365 .. option:: --tls-ticket-key-file=<PATH>
 366
 367     Path  to file  that  contains 48  bytes  random data  to
 368     construct TLS  session ticket parameters.   This options
 369     can  be  used  repeatedly  to  specify  multiple  ticket
 370     parameters.  If several files  are given, only the first
 371     key is used to encrypt  TLS session tickets.  Other keys
 372     are accepted  but server  will issue new  session ticket
 373     with  first  key.   This allows  session  key  rotation.
 374     Please   note  that   key   rotation   does  not   occur
 375     automatically.   User should  rearrange files  or change
 376     options  values  and  restart  nghttpx  gracefully.   If
 377     opening or reading given file fails, all loaded keys are
 378     discarded and it is treated as if none of this option is
 379     given.  If this option is not given or an error occurred
 380     while  opening  or  reading  a file,  key  is  generated
 381     automatically and  renewed every 12hrs.  At  most 2 keys
 382     are stored in memory.
 383
 384 .. option:: --fetch-ocsp-response-file=<PATH>
 385
 386     Path to  fetch-ocsp-response script file.  It  should be
 387     absolute path.
 388
 389     Default: ``/usr/local/share/nghttp2/fetch-ocsp-response``
 390
 391 .. option:: --ocsp-update-interval=<DURATION>
 392
 393     Set interval to update OCSP response cache.
 394
 395     Default: ``4h``
 396
 397 .. option:: --no-ocsp
 398
 399     Disable OCSP stapling.
 400
 401
 402 HTTP/2 and SPDY
 403 ~~~~~~~~~~~~~~~
 404
 405 .. option:: -c, --http2-max-concurrent-streams=<N>
 406
 407     Set the maximum number of  the concurrent streams in one
 408     HTTP/2 and SPDY session.
 409
 410     Default: ``100``
 411
 412 .. option:: --frontend-http2-window-bits=<N>
 413
 414     Sets the  per-stream initial window size  of HTTP/2 SPDY
 415     frontend connection.  For HTTP/2,  the size is 2\*\*<N>-1.
 416     For SPDY, the size is 2\*\*<N>.
 417
 418     Default: ``16``
 419
 420 .. option:: --frontend-http2-connection-window-bits=<N>
 421
 422     Sets the  per-connection window size of  HTTP/2 and SPDY
 423     frontend   connection.    For   HTTP/2,  the   size   is
 424     2**<N>-1. For SPDY, the size is 2\*\*<N>.
 425
 426     Default: ``16``
 427
 428 .. option:: --frontend-no-tls
 429
 430     Disable SSL/TLS on frontend connections.
 431
 432 .. option:: --backend-http2-window-bits=<N>
 433
 434     Sets  the   initial  window   size  of   HTTP/2  backend
 435     connection to 2\*\*<N>-1.
 436
 437     Default: ``16``
 438
 439 .. option:: --backend-http2-connection-window-bits=<N>
 440
 441     Sets the  per-connection window  size of  HTTP/2 backend
 442     connection to 2\*\*<N>-1.
 443
 444     Default: ``16``
 445
 446 .. option:: --backend-no-tls
 447
 448     Disable SSL/TLS on backend connections.
 449
 450 .. option:: --http2-no-cookie-crumbling
 451
 452     Don't crumble cookie header field.
 453
 454 .. option:: --padding=<N>
 455
 456     Add  at most  <N> bytes  to  a HTTP/2  frame payload  as
 457     padding.  Specify 0 to  disable padding.  This option is
 458     meant for debugging purpose  and not intended to enhance
 459     protocol security.
 460
 461 .. option:: --no-server-push
 462
 463     Disable  HTTP/2  server  push.    Server  push  is  only
 464     supported  by default  mode and  HTTP/2 frontend.   SPDY
 465     frontend does not support server push.
 466
 467
 468 Mode
 469 ~~~~
 470
 471 .. describe:: (default mode)
 472
 473
 474     Accept  HTTP/2,  SPDY  and HTTP/1.1  over  SSL/TLS.   If
 475     :option:`--frontend-no-tls` is  used, accept HTTP/2  and HTTP/1.1.
 476     The  incoming HTTP/1.1  connection  can  be upgraded  to
 477     HTTP/2  through  HTTP  Upgrade.   The  protocol  to  the
 478     backend is HTTP/1.1.
 479
 480 .. option:: -s, --http2-proxy
 481
 482     Like default mode, but enable secure proxy mode.
 483
 484 .. option:: --http2-bridge
 485
 486     Like default  mode, but communicate with  the backend in
 487     HTTP/2 over SSL/TLS.  Thus  the incoming all connections
 488     are converted  to HTTP/2  connection and relayed  to the
 489     backend.  See :option:`--backend-http-proxy-uri` option if you are
 490     behind  the proxy  and want  to connect  to the  outside
 491     HTTP/2 proxy.
 492
 493 .. option:: --client
 494
 495     Accept  HTTP/2   and  HTTP/1.1  without   SSL/TLS.   The
 496     incoming HTTP/1.1  connection can be upgraded  to HTTP/2
 497     connection through  HTTP Upgrade.   The protocol  to the
 498     backend is HTTP/2.   To use nghttpx as  a forward proxy,
 499     use :option:`-p` option instead.
 500
 501 .. option:: -p, --client-proxy
 502
 503     Like :option:`--client`  option, but it also  requires the request
 504     path from frontend must be an absolute URI, suitable for
 505     use as a forward proxy.
 506
 507
 508 Logging
 509 ~~~~~~~
 510
 511 .. option:: -L, --log-level=<LEVEL>
 512
 513     Set the severity  level of log output.   <LEVEL> must be
 514     one of INFO, NOTICE, WARN, ERROR and FATAL.
 515
 516     Default: ``NOTICE``
 517
 518 .. option:: --accesslog-file=<PATH>
 519
 520     Set path to write access log.  To reopen file, send USR1
 521     signal to nghttpx.
 522
 523 .. option:: --accesslog-syslog
 524
 525     Send  access log  to syslog.   If this  option is  used,
 526     :option:`--accesslog-file` option is ignored.
 527
 528 .. option:: --accesslog-format=<FORMAT>
 529
 530     Specify  format  string  for access  log.   The  default
 531     format is combined format.   The following variables are
 532     available:
 533
 534     * $remote_addr: client IP address.
 535     * $time_local: local time in Common Log format.
 536     * $time_iso8601: local time in ISO 8601 format.
 537     * $request: HTTP request line.
 538     * $status: HTTP response status code.
 539     * $body_bytes_sent: the  number of bytes sent  to client
 540       as response body.
 541     * $http_<VAR>: value of HTTP  request header <VAR> where
 542       '_' in <VAR> is replaced with '-'.
 543     * $remote_port: client  port.
 544     * $server_port: server port.
 545     * $request_time: request processing time in seconds with
 546       milliseconds resolution.
 547     * $pid: PID of the running process.
 548     * $alpn: ALPN identifier of the protocol which generates
 549       the response.   For HTTP/1,  ALPN is  always http/1.1,
 550       regardless of minor version.
 551
 552
 553     Default: ``$remote_addr - - [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"``
 554
 555 .. option:: --errorlog-file=<PATH>
 556
 557     Set path to write error  log.  To reopen file, send USR1
 558     signal  to nghttpx.   stderr will  be redirected  to the
 559     error log file unless :option:`--errorlog-syslog` is used.
 560
 561     Default: ``/dev/stderr``
 562
 563 .. option:: --errorlog-syslog
 564
 565     Send  error log  to  syslog.  If  this  option is  used,
 566     :option:`--errorlog-file` option is ignored.
 567
 568 .. option:: --syslog-facility=<FACILITY>
 569
 570     Set syslog facility to <FACILITY>.
 571
 572     Default: ``daemon``
 573
 574
 575 HTTP
 576 ~~~~
 577
 578 .. option:: --add-x-forwarded-for
 579
 580     Append  X-Forwarded-For header  field to  the downstream
 581     request.
 582
 583 .. option:: --strip-incoming-x-forwarded-for
 584
 585     Strip X-Forwarded-For  header field from  inbound client
 586     requests.
 587
 588 .. option:: --no-via
 589
 590     Don't append to  Via header field.  If  Via header field
 591     is received, it is left unaltered.
 592
 593 .. option:: --no-location-rewrite
 594
 595     Don't rewrite  location header field  on :option:`--http2-bridge`\,
 596     :option:`--client`  and  default   mode.   For  :option:`\--http2-proxy`  and
 597     :option:`--client-proxy` mode,  location header field will  not be
 598     altered regardless of this option.
 599
 600 .. option:: --no-host-rewrite
 601
 602     Don't  rewrite  host  and :authority  header  fields  on
 603     :option:`--http2-bridge`\,   :option:`--client`   and  default   mode.    For
 604     :option:`--http2-proxy`  and  :option:`\--client-proxy` mode,  these  headers
 605     will not be altered regardless of this option.
 606
 607 .. option:: --altsvc=<PROTOID,PORT[,HOST,[ORIGIN]]>
 608
 609     Specify   protocol  ID,   port,  host   and  origin   of
 610     alternative service.  <HOST>  and <ORIGIN> are optional.
 611     They  are advertised  in  alt-svc header  field only  in
 612     HTTP/1.1  frontend.  This  option can  be used  multiple
 613     times   to   specify  multiple   alternative   services.
 614     Example: :option:`--altsvc`\=h2,443
 615
 616 .. option:: --add-response-header=<HEADER>
 617
 618     Specify  additional  header  field to  add  to  response
 619     header set.   This option just appends  header field and
 620     won't replace anything already  set.  This option can be
 621     used several  times to  specify multiple  header fields.
 622     Example: :option:`--add-response-header`\="foo: bar"
 623
 624 .. option:: --header-field-buffer=<SIZE>
 625
 626     Set maximum  buffer size for incoming  HTTP header field
 627     list.   This is  the sum  of  header name  and value  in
 628     bytes.
 629
 630     Default: ``64K``
 631
 632 .. option:: --max-header-fields=<N>
 633
 634     Set maximum number of incoming HTTP header fields, which
 635     appear in one request or response header field list.
 636
 637     Default: ``100``
 638
 639
 640 Debug
 641 ~~~~~
 642
 643 .. option:: --frontend-http2-dump-request-header=<PATH>
 644
 645     Dumps request headers received by HTTP/2 frontend to the
 646     file denoted  in <PATH>.  The  output is done  in HTTP/1
 647     header field format and each header block is followed by
 648     an empty line.  This option  is not thread safe and MUST
 649     NOT be used with option :option:`-n`\<N>, where <N> >= 2.
 650
 651 .. option:: --frontend-http2-dump-response-header=<PATH>
 652
 653     Dumps response headers sent  from HTTP/2 frontend to the
 654     file denoted  in <PATH>.  The  output is done  in HTTP/1
 655     header field format and each header block is followed by
 656     an empty line.  This option  is not thread safe and MUST
 657     NOT be used with option :option:`-n`\<N>, where <N> >= 2.
 658
 659 .. option:: -o, --frontend-frame-debug
 660
 661     Print HTTP/2 frames in  frontend to stderr.  This option
 662     is  not thread  safe and  MUST NOT  be used  with option
 663     :option:`-n`\=N, where N >= 2.
 664
 665
 666 Process
 667 ~~~~~~~
 668
 669 .. option:: -D, --daemon
 670
 671     Run in a background.  If :option:`-D` is used, the current working
 672     directory is changed to '*/*'.
 673
 674 .. option:: --pid-file=<PATH>
 675
 676     Set path to save PID of this program.
 677
 678 .. option:: --user=<USER>
 679
 680     Run this program as <USER>.   This option is intended to
 681     be used to drop root privileges.
 682
 683
 684 Misc
 685 ~~~~
 686
 687 .. option:: --conf=<PATH>
 688
 689     Load configuration from <PATH>.
 690
 691     Default: ``/etc/nghttpx/nghttpx.conf``
 692
 693 .. option:: -v, --version
 694
 695     Print version and exit.
 696
 697 .. option:: -h, --help
 698
 699     Print this help and exit.
 700
 701
 702
 703 The <SIZE> argument is an integer and an optional unit (e.g., 10K is
 704 10 * 1024).  Units are K, M and G (powers of 1024).
 705
 706 The <DURATION> argument is an integer and an optional unit (e.g., 1s
 707 is 1 second and 500ms is 500 milliseconds).  Units are h, m, s or ms
 708 (hours, minutes, seconds and milliseconds, respectively).  If a unit
 709 is omitted, a second is used as unit.
 710
 711 FILES
 712 -----
 713
 714 */etc/nghttpx/nghttpx.conf*
 715   The default configuration file path nghttpx searches at startup.
 716   The configuration file path can be changed using :option:`--conf`
 717   option.
 718
 719   Those lines which are staring ``#`` are treated as comment.
 720
 721   The option name in the configuration file is the long command-line
 722   option name with leading ``--`` stripped (e.g., ``frontend``).  Put
 723   ``=`` between option name and value.  Don't put extra leading or
 724   trailing spaces.
 725
 726   The options which do not take argument in the command-line *take*
 727   argument in the configuration file.  Specify ``yes`` as an argument
 728   (e.g., ``http2-proxy=yes``).  If other string is given, it is
 729   ignored.
 730
 731   To specify private key and certificate file which are given as
 732   positional arguments in command-line, use ``private-key-file`` and
 733   ``certificate-file``.
 734
 735   :option:`--conf` option cannot be used in the configuration file and
 736   will be ignored if specified.
 737
 738 SIGNALS
 739 -------
 740
 741 SIGQUIT
 742   Shutdown gracefully.  First accept pending connections and stop
 743   accepting connection.  After all connections are handled, nghttpx
 744   exits.
 745
 746 SIGUSR1
 747   Reopen log files.
 748
 749 SIGUSR2
 750   Fork and execute nghttpx.  It will execute the binary in the same
 751   path with same command-line arguments and environment variables.
 752   After new process comes up, sending SIGQUIT to the original process
 753   to perform hot swapping.
 754
 755 SERVER PUSH
 756 -----------
 757
 758 nghttpx supports HTTP/2 server push in default mode.  nghttpx looks
 759 for Link header field (`RFC 5988
 760 <http://tools.ietf.org/html/rfc5988>`_) in response headers from
 761 backend server and extracts URI-reference with parameter
 762 ``rel=preload`` (see `preload
 763 <http://w3c.github.io/preload/#interoperability-with-http-link-header>`_)
 764 and pushes those URIs to the frontend client. Here is a sample Link
 765 header field to initiate server push:
 766
 767 .. code-block:: http
 768
 769   Link: </fonts/font.woff>; rel=preload
 770   Link: </css/theme.css>; rel=preload
 771
 772 Currently, the following restrictions are applied for server push:
 773
 774 1. URI-reference must not contain authority.  If it exists, it is not
 775    pushed.  ``/fonts/font.woff`` and ``css/theme.css`` are eligible to
 776    be pushed.  ``https://example.org/fonts/font.woff`` and
 777    ``//example.org/css/theme.css`` are not.
 778
 779 2. The associated stream must have method "GET" or "POST".  The
 780    associated stream's status code must be 200.
 781
 782 These limitations may be loosened in the future release.
 783
 784 UNIX DOMAIN SOCKET
 785 ------------------
 786
 787 nghttpx supports UNIX domain socket with a filename for both frontend
 788 and backend connections.
 789
 790 Please note that current nghttpx implementation does not delete a
 791 socket with a filename.  And on start up, if nghttpx detects that the
 792 specified socket already exists in the file system, nghttpx first
 793 deletes it.  However, if SIGUSR2 is used to execute new binary and
 794 both old and new configurations use same filename, new binary does not
 795 delete the socket and continues to use it.
 796
 797 OCSP STAPLING
 798 -------------
 799
 800 OCSP query is done using external perl script ``fetch-ocsp-response``,
 801 which has been developed as part of h2o project
 802 (https://github.com/h2o/h2o).
 803
 804 The script file is usually installed under
 805 ``$(prefix)/share/nghttp2/`` directory.  The actual path to script can
 806 be customized using :option:`--fetch-ocsp-response-file` option.
 807
 808 SEE ALSO
 809 --------
 810
 811 :manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`h2load(1)`