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