1NGHTTPX(1) nghttp2 NGHTTPX(1)
2
6 nghttpx - HTTP/2 proxy
7
9 nghttpx [OPTIONS]... [<PRIVATE_KEY> <CERT>]
10
12 A reverse proxy for HTTP/2, and HTTP/1.
13 <PRIVATE_KEY>
15 Set path to server's private key. Required unless
16 "no-tls" parameter is used in --frontend option.
17 <CERT> Set path to server's certificate. Required unless
19 "no-tls" parameter is used in --frontend option. To make
20 OCSP stapling work, this must be an absolute path.
21
23 The options are categorized into several groups.
24 Connections
26 -b, --backend=(<HOST>,<PORT>|unix:<PATH>)[;[<PAT‐
27 TERN>[:...]][[;<PARAM>]...]
28 Set backend host and port. The multiple backend
29 addresses are accepted by repeating this option. UNIX domain
30 socket can be specified by prefixing path name with "unix:"
31 (e.g., unix:/var/run/backend.sock).
32 Optionally, if <PATTERN>s are given, the backend address is
34 only used if request matches the pattern. The pattern
35 matching is closely designed to ServeMux in net/http package
36 of Go programming language. <PATTERN> consists of path, host
37 + path or just host. The path must start with "/". If it
38 ends with "/", it matches all request path in its subtree.
39 To deal with the request to the directory without trailing
40 slash, the path which ends with "/" also matches the request
41 path which only lacks trailing '/' (e.g., path "/foo/"
42 matches request path "/foo"). If it does not end with "/", it
43 performs exact match against the request path. If host is
44 given, it performs a match against the request host. For
45 a request received on the frontend listener with "sni-fwd"
46 parameter enabled, SNI host is used instead of a request host.
47 If host alone is given, "/" is appended to it, so that it
48 matches all request paths under the host (e.g., specifying
49 "nghttp2.org" equals to "nghttp2.org/"). CONNECT method is
50 treated specially. It does not have path, and we don't allow
51 empty path. To workaround this, we assume that CONNECT method
52 has "/" as path.
53 Patterns with host take precedence over patterns with just
55 path. Then, longer patterns take precedence over shorter
56 ones.
57 Host can include "*" in the left most position to indi‐
59 cate wildcard match (only suffix match is done). The "*"
60 must match at least one character. For example, host pattern
61 "*.nghttp2.org" matches against "www.nghttp2.org" and
62 "git.ngttp2.org", but does not match against "nghttp2.org".
63 The exact hosts match takes precedence over the wildcard hosts
64 match.
65 If path part ends with "*", it is treated as wildcard path.
67 The wildcard path behaves differently from the normal path.
68 For normal path, match is made around the boundary of path com‐
69 ponent separator,"/". On the other hand, the wildcard path
70 does not take into account the path component separator. All
71 paths which include the wildcard path without last "*" as
72 prefix, and are strictly longer than wildcard path without
73 last "*" are matched. "*" must match at least one character.
74 For example, the pattern "/foo*" matches "/foo/" and
75 "/foobar". But it does not match "/foo", or "/fo".
76 If <PATTERN> is omitted or empty string, "/" is used as pat‐
78 tern, which matches all request paths (catch-all pattern).
79 The catch-all backend must be given.
80 When doing a match, nghttpx made some normalization to pat‐
82 tern, request host and path. For host part, they are converted
83 to lower case. For path part, percent-encoded unreserved char‐
84 acters defined in RFC 3986 are decoded, and any dot-segments
85 (".." and ".") are resolved and removed.
86 For example, -b'127.0.0.1,8080;nghttp2.org/httpbin/' matches
88 the request host "nghttp2.org" and the request path "/http‐
89 bin/get", but does not match the request host "nghttp2.org" and
90 the request path "/index.html".
91 The multiple <PATTERN>s can be specified, delimiting them
93 by ":". Specifying
94 -b'127.0.0.1,8080;nghttp2.org:www.nghttp2.org' has the same
95 effect to specify -b'127.0.0.1,8080;nghttp2.org' and
96 -b'127.0.0.1,8080;www.nghttp2.org'.
97 The backend addresses sharing same <PATTERN> are grouped
99 together forming load balancing group.
100 Several parameters <PARAM> are accepted after <PATTERN>. The
102 parameters are delimited by ";". The available parameters
103 are: "proto=<PROTO>", "tls", "sni=<SNI_HOST>",
104 "fall=<N>", "rise=<N>", "affinity=<METHOD>", "dns",
105 "redirect-if-not-tls", "upgrade-scheme",
106 "mruby=<PATH>", "read-timeout=<DURATION>", "write-time‐
107 out=<DURATION>", "group=<GROUP>", "group-weight=<N>", and
108 "weight=<N>". The parameter consists of keyword, and
109 optionally followed by "=" and value. For example, the param‐
110 eter "proto=h2" consists of the keyword "proto" and value
111 "h2". The parameter "tls" consists of the keyword "tls" without
112 value. Each parameter is described as follows.
113 The backend application protocol can be specified using
115 optional "proto" parameter, and in the form of
116 "proto=<PROTO>". <PROTO> should be one of the following list
117 without quotes: "h2", "http/1.1". The default value of
118 <PROTO> is "http/1.1". Note that usually "h2" refers to HTTP/2
119 over TLS. But in this option, it may mean HTTP/2 over cleart‐
120 ext TCP unless "tls" keyword is used (see below).
121 TLS can be enabled by specifying optional "tls" parame‐
123 ter. TLS is not enabled by default.
124 With "sni=<SNI_HOST>" parameter, it can override the TLS SNI
126 field value with given <SNI_HOST>. This will default to
127 the backend <HOST> name
128 The feature to detect whether backend is online or offline
130 can be enabled using optional "fall" and "rise" parameters.
131 Using "fall=<N>" parameter, if nghttpx cannot connect to a
132 this backend <N> times in a row, this backend is assumed
133 to be offline, and it is excluded from load balancing. If
134 <N> is 0, this backend never be excluded from load balancing
135 whatever times nghttpx cannot connect to it, and this is the
136 default. There is also "rise=<N>" parameter. After backend
137 was excluded from load balancing group, nghttpx periodically
138 attempts to make a connection to the failed backend, and if the
139 connection is made successfully <N> times in a row, the back‐
140 end is assumed to be online, and it is now eligible for load
141 balancing target. If <N> is 0, a backend is permanently
142 offline, once it goes in that state, and this is the default
143 behaviour.
144 The session affinity is enabled using "affin‐
146 ity=<METHOD>" parameter. If "ip" is given in <METHOD>,
147 client IP based session affinity is enabled. If "cookie" is
148 given in <METHOD>, cookie based session affinity is enabled.
149 If "none" is given in <METHOD>, session affinity is disabled,
150 and this is the default. The session affinity is enabled per
151 <PATTERN>. If at least one backend has "affinity" parame‐
152 ter, and its <METHOD> is not "none", session affinity is
153 enabled for all backend servers sharing the same <PATTERN>.
154 It is advised to set "affinity" parameter to all backend
155 explicitly if session affinity is desired. The session affin‐
156 ity may break if one of the backend gets unreachable,
157 or backend settings are reloaded or replaced by API.
158 If "affinity=cookie" is used, the additional config‐
160 uration is required. "affin‐
161 ity-cookie-name=<NAME>" must be used to specify a name of
162 cookie to use. Optionally, "affin‐
163 ity-cookie-path=<PATH>" can be used to specify a path which
164 cookie is applied. The optional "affin‐
165 ity-cookie-secure=<SECURE>" controls the Secure attribute of
166 a cookie. The default value is "auto", and the Secure attribute
167 is determined by a request scheme. If a request scheme is
168 "https", then Secure attribute is set. Otherwise, it is not
169 set. If <SECURE> is "yes", the Secure attribute is always
170 set. If <SECURE> is "no", the Secure attribute is always
171 omitted.
172 By default, name resolution of backend host name is done at
174 start up, or reloading configuration. If "dns" parameter
175 is given, name resolution takes place dynamically. This
176 is useful if backend address changes frequently. If "dns"
177 is given, name resolution of backend host name at
178 start up, or reloading configuration is skipped.
179 If "redirect-if-not-tls" parameter is used, the matched backend
181 requires that frontend connection is TLS encrypted. If
182 it isn't, nghttpx responds to the request with 308 status code,
183 and https URI the client should use instead is included in
184 Location header field. The port number in redirect URI is 443
185 by default, and can be changed using --redirect-https-port
186 option. If at least one backend has "redirect-if-not-tls"
187 parameter, this feature is enabled for all backend servers
188 sharing the same <PATTERN>. It is advised to set
189 "redirect-if-no-tls" parameter to all backends explic‐
190 itly if this feature is desired.
191 If "upgrade-scheme" parameter is used along with "tls" parame‐
193 ter, HTTP/2 :scheme pseudo header field is changed to "https"
194 from "http" when forwarding a request to this particular back‐
195 end. This is a workaround for a backend server which
196 requires "https" :scheme pseudo header field on TLS encrypted
197 connection.
198 "mruby=<PATH>" parameter specifies a path to mruby script
200 file which is invoked when this pattern is matched. All
201 backends which share the same pattern must have the same mruby
202 path.
203 "read-timeout=<DURATION>" and "write-timeout=<DURATION>" parame‐
205 ters specify the read and write timeout of the backend con‐
206 nection when this pattern is matched. All backends which
207 share the same pattern must have the same timeouts. If these
208 timeouts are entirely omitted for a pattern,
209 --backend-read-timeout and --backend-write-timeout are
210 used.
211 "group=<GROUP>" parameter specifies the name of group this
213 backend address belongs to. By default, it belongs to the
214 unnamed default group. The name of group is unique per
215 pattern. "group-weight=<N>" parameter specifies the weight
216 of the group. The higher weight gets more frequently
217 selected by the load balancing algorithm. <N> must be [1,
218 256] inclusive. The weight 8 has 4 times more weight than 2.
219 <N> must be the same for all addresses which share the same
220 <GROUP>. If "group-weight" is omitted in an address, but the
221 other address which belongs to the same group specifies
222 "group-weight", its weight is used. If no
223 "group-weight" is specified for all addresses, the weight
224 of a group becomes 1. "group" and "group-weight" are ignored if
225 session affinity is enabled.
226 "weight=<N>" parameter specifies the weight of the backend
228 address inside a group which this address belongs to.
229 The higher weight gets more frequently selected by the load
230 balancing algorithm. <N> must be [1, 256] inclusive. The
231 weight 8 has 4 times more weight than weight 2. If this
232 parameter is omitted, weight becomes 1. "weight" is
233 ignored if session affinity is enabled.
234 Since ";" and ":" are used as delimiter, <PATTERN> must not
236 contain these characters. In order to include ":" in <PAT‐
237 TERN>, one has to specify "%3A" (which is percent-encoded
238 from of ":") instead. Since ";" has special meaning in
239 shell, the option value must be quoted.
240 Default: 127.0.0.1,80
242 -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]
244 Set frontend host and port. If <HOST> is '*', it assumes
245 all addresses including both IPv4 and IPv6. UNIX domain
246 socket can be specified by prefixing path name with "unix:"
247 (e.g., unix:/var/run/nghttpx.sock). This option can be used
248 multiple times to listen to multiple addresses.
249 This option can take 0 or more parameters, which are
251 described below. Note that "api" and "healthmon" parame‐
252 ters are mutually exclusive.
253 Optionally, TLS can be disabled by specifying "no-tls" parame‐
255 ter. TLS is enabled by default.
256 If "sni-fwd" parameter is used, when performing a match to
258 select a backend server, SNI host name received from the client
259 is used instead of the request host. See --backend option
260 about the pattern match.
261 To make this frontend as API endpoint, specify "api" parame‐
263 ter. This is disabled by default. It is important to
264 limit the access to the API frontend. Otherwise, someone
265 may change the backend server, and break your services, or
266 expose confidential information to the outside the world.
267 To make this frontend as health monitor endpoint, specify
269 "healthmon" parameter. This is disabled by default. Any
270 requests which come through this address are replied with 200
271 HTTP status, without no body.
272 To accept PROXY protocol version 1 and 2 on frontend connec‐
274 tion, specify "proxyproto" parameter. This is disabled by
275 default.
276 Default: *,3000
278 --backlog=<N>
280 Set listen backlog size.
281 Default: 65536
283 --backend-address-family=(auto|IPv4|IPv6)
285 Specify address family of backend connections. If "auto"
286 is given, both IPv4 and IPv6 are considered. If "IPv4" is
287 given, only IPv4 address is considered. If "IPv6" is given,
288 only IPv6 address is considered.
289 Default: auto
291 --backend-http-proxy-uri=<URI>
293 Specify proxy URI in the form
294 http://[<USER>:<PASS>@]<PROXY>:<PORT>. If a proxy
295 requires authentication, specify <USER> and <PASS>. Note
296 that they must be properly percent-encoded. This proxy is
297 used when the backend connection is HTTP/2. First, make a
298 CONNECT request to the proxy and it connects to the back‐
299 end on behalf of nghttpx. This forms tunnel. After that,
300 nghttpx performs SSL/TLS handshake with the downstream
301 through the tunnel. The timeouts when connecting and making
302 CONNECT request can be specified by
303 --backend-read-timeout and --backend-write-timeout options.
304 Performance
306 -n, --workers=<N>
307 Set the number of worker threads.
308 Default: 1
310 --single-thread
312 Run everything in one thread inside the worker process. This
313 feature is provided for better debugging experience,
314 or for the platforms which lack thread support. If
315 threading is disabled, this option is always enabled.
316 --read-rate=<SIZE>
318 Set maximum average read rate on frontend connection. Set‐
319 ting 0 to this option means read rate is unlimited.
320 Default: 0
322 --read-burst=<SIZE>
324 Set maximum read burst size on frontend connection. Set‐
325 ting 0 to this option means read burst size is unlimited.
326 Default: 0
328 --write-rate=<SIZE>
330 Set maximum average write rate on frontend connection. Set‐
331 ting 0 to this option means write rate is unlimited.
332 Default: 0
334 --write-burst=<SIZE>
336 Set maximum write burst size on frontend connection. Set‐
337 ting 0 to this option means write burst size is unlimited.
338 Default: 0
340 --worker-read-rate=<SIZE>
342 Set maximum average read rate on frontend connection per worker.
343 Setting 0 to this option means read rate is unlimited. Not
344 implemented yet.
345 Default: 0
347 --worker-read-burst=<SIZE>
349 Set maximum read burst size on frontend connection per worker.
350 Setting 0 to this option means read burst size is unlimited.
351 Not implemented yet.
352 Default: 0
354 --worker-write-rate=<SIZE>
356 Set maximum average write rate on frontend connection per
357 worker. Setting 0 to this option means write rate is unlim‐
358 ited. Not implemented yet.
359 Default: 0
361 --worker-write-burst=<SIZE>
363 Set maximum write burst size on frontend connection per worker.
364 Setting 0 to this option means write burst size is unlimited.
365 Not implemented yet.
366 Default: 0
368 --worker-frontend-connections=<N>
370 Set maximum number of simultaneous connections frontend
371 accepts. Setting 0 means unlimited.
372 Default: 0
374 --backend-connections-per-host=<N>
376 Set maximum number of backend concurrent connections (and/or
377 streams in case of HTTP/2) per origin host. This option is
378 meaningful when --http2-proxy option is used. The origin
379 host is determined by authority portion of request URI (or
380 :authority header field for HTTP/2). To limit the number
381 of connections per frontend for default
382 mode, use --backend-connections-per-frontend.
383 Default: 8
385 --backend-connections-per-frontend=<N>
387 Set maximum number of backend concurrent connections (and/or
388 streams in case of HTTP/2) per frontend. This option is
389 only used for default mode. 0 means unlimited. To limit
390 the number of connections per host with --http2-proxy
391 option, use --backend-connections-per-host.
392 Default: 0
394 --rlimit-nofile=<N>
396 Set maximum number of open files (RLIMIT_NOFILE) to <N>. If 0
397 is given, nghttpx does not set the limit.
398 Default: 0
400 --backend-request-buffer=<SIZE>
402 Set buffer size used to store backend request.
403 Default: 16K
405 --backend-response-buffer=<SIZE>
407 Set buffer size used to store backend response.
408 Default: 128K
410 --fastopen=<N>
412 Enables "TCP Fast Open" for the listening socket and limits
413 the maximum length for the queue of connections that have not
414 yet completed the three-way handshake. If value is 0 then fast
415 open is disabled.
416 Default: 0
418 --no-kqueue
420 Don't use kqueue. This option is only applicable for the
421 platforms which have kqueue. For other platforms, this option
422 will be simply ignored.
423 Timeout
425 --frontend-http2-read-timeout=<DURATION>
426 Specify read timeout for HTTP/2 frontend connection.
427 Default: 3m
429 --frontend-read-timeout=<DURATION>
431 Specify read timeout for HTTP/1.1 frontend connection.
432 Default: 1m
434 --frontend-write-timeout=<DURATION>
436 Specify write timeout for all frontend connections.
437 Default: 30s
439 --frontend-keep-alive-timeout=<DURATION>
441 Specify keep-alive timeout for frontend HTTP/1 connec‐
442 tion.
443 Default: 1m
445 --stream-read-timeout=<DURATION>
447 Specify read timeout for HTTP/2 streams. 0 means no time‐
448 out.
449 Default: 0
451 --stream-write-timeout=<DURATION>
453 Specify write timeout for HTTP/2 streams. 0 means no time‐
454 out.
455 Default: 1m
457 --backend-read-timeout=<DURATION>
459 Specify read timeout for backend connection.
460 Default: 1m
462 --backend-write-timeout=<DURATION>
464 Specify write timeout for backend connection.
465 Default: 30s
467 --backend-connect-timeout=<DURATION>
469 Specify timeout before establishing TCP connection to back‐
470 end.
471 Default: 30s
473 --backend-keep-alive-timeout=<DURATION>
475 Specify keep-alive timeout for backend HTTP/1 connec‐
476 tion.
477 Default: 2s
479 --listener-disable-timeout=<DURATION>
481 After accepting connection failed, connection listener is dis‐
482 abled for a given amount of time. Specifying 0 disables this
483 feature.
484 Default: 30s
486 --frontend-http2-setting-timeout=<DURATION>
488 Specify timeout before SETTINGS ACK is received from client.
489 Default: 10s
491 --backend-http2-settings-timeout=<DURATION>
493 Specify timeout before SETTINGS ACK is received from backend
494 server.
495 Default: 10s
497 --backend-max-backoff=<DURATION>
499 Specify maximum backoff interval. This is used when doing
500 health check against offline backend (see "fail" parameter in
501 --backend option). It is also used to limit the maximum
502 interval to temporarily disable backend when nghttpx failed
503 to connect to it. These intervals are calculated using expo‐
504 nential backoff, and consecutive failed attempts increase the
505 interval. This option caps its maximum value.
506 Default: 2m
508 SSL/TLS
510 --ciphers=<SUITE>
511 Set allowed cipher list for frontend connection. The format
512 of the string is described in OpenSSL ciphers(1). This option
513 sets cipher suites for TLSv1.2 or earlier. Use --tls13-ciphers
514 for TLSv1.3.
515 Default:
517 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
518 --tls13-ciphers=<SUITE>
520 Set allowed cipher list for frontend connection. The format
521 of the string is described in OpenSSL ciphers(1). This option
522 sets cipher suites for TLSv1.3. Use --ciphers for TLSv1.2
523 or earlier.
524 Default:
526 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
527 --client-ciphers=<SUITE>
529 Set allowed cipher list for backend connection. The format
530 of the string is described in OpenSSL ciphers(1). This option
531 sets cipher suites for TLSv1.2 or earlier. Use
532 --tls13-client-ciphers for TLSv1.3.
533 Default:
535 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
536 --tls13-client-ciphers=<SUITE>
538 Set allowed cipher list for backend connection. The format
539 of the string is described in OpenSSL ciphers(1). This option
540 sets cipher suites for TLSv1.3. Use
541 --tls13-client-ciphers for TLSv1.2 or earlier.
542 Default:
544 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
545 --ecdh-curves=<LIST>
547 Set supported curve list for frontend connections. <LIST>
548 is a colon separated list of curve NID or names in the prefer‐
549 ence order. The supported curves depend on the linked OpenSSL
550 library. This function requires OpenSSL >= 1.0.2.
551 Default: X25519:P-256:P-384:P-521
553 -k, --insecure
555 Don't verify backend server's certificate if TLS is enabled
556 for backend connections.
557 --cacert=<PATH>
559 Set path to trusted CA certificate file. It is used in backend
560 TLS connections to verify peer's certificate. It is also used
561 to verify OCSP response from the script set by
562 --fetch-ocsp-response-file. The file must be in PEM format.
563 It can contain multiple certificates. If the linked OpenSSL
564 is configured to load system wide certificates, they are
565 loaded at startup regardless of this option.
566 --private-key-passwd-file=<PATH>
568 Path to file that contains password for the server's private
569 key. If none is given and the private key is password pro‐
570 tected it'll be requested interactively.
571 --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
573 Specify additional certificate and private key file.
574 nghttpx will choose certificates based on the hostname indi‐
575 cated by client using TLS SNI extension. If nghttpx is built
576 with OpenSSL >= 1.0.2, the shared elliptic curves (e.g.,
577 P-256) between client and server are also taken into consider‐
578 ation. This allows nghttpx to send ECDSA certificate to mod‐
579 ern clients, while sending RSA based certificate to older
580 clients. This option can be used multiple times. To make
581 OCSP stapling work, <CERTPATH> must be absolute path.
582 Additional parameter can be specified in <PARAM>. The avail‐
584 able <PARAM> is "sct-dir=<DIR>".
585 "sct-dir=<DIR>" specifies the path to directory which con‐
587 tains *.sct files for TLS
588 signed_certificate_timestamp extension (RFC 6962). This feature
589 requires OpenSSL >= 1.0.2. See also --tls-sct-dir
590 option.
591 --dh-param-file=<PATH>
593 Path to file that contains DH parameters in PEM format. With‐
594 out this option, DHE cipher suites are not available.
595 --npn-list=<LIST>
597 Comma delimited list of ALPN protocol identifier sorted in the
598 order of preference. That means most desirable protocol comes
599 first. This is used in both ALPN and NPN. The parameter
600 must be delimited by a single comma only and any white spaces
601 are treated as a part of protocol string.
602 Default: h2,h2-16,h2-14,http/1.1
604 --verify-client
606 Require and verify client certificate.
607 --verify-client-cacert=<PATH>
609 Path to file that contains CA certificates to verify client
610 certificate. The file must be in PEM format. It can contain
611 multiple certificates.
612 --verify-client-tolerate-expired
614 Accept expired client certificate. Operator should handle
615 the expired client certificate by some means (e.g., mruby
616 script). Otherwise, this option might cause a security risk.
617 --client-private-key-file=<PATH>
619 Path to file that contains client private key used in backend
620 client authentication.
621 --client-cert-file=<PATH>
623 Path to file that contains client certificate used in backend
624 client authentication.
625 --tls-min-proto-version=<VER>
627 Specify minimum SSL/TLS protocol. The name matching is done in
628 case-insensitive manner. The versions between
629 --tls-min-proto-version and --tls-max-proto-version are
630 enabled. If the protocol list advertised by client does not
631 overlap this range, you will receive the error message
632 "unknown protocol". If a protocol version lower than TLSv1.2 is
633 specified, make sure that the compatible ciphers are included
634 in --ciphers option. The default cipher list only includes
635 ciphers compatible with TLSv1.2 or above. The available ver‐
636 sions are: TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
637 Default: TLSv1.2
639 --tls-max-proto-version=<VER>
641 Specify maximum SSL/TLS protocol. The name matching is done in
642 case-insensitive manner. The versions between
643 --tls-min-proto-version and --tls-max-proto-version are
644 enabled. If the protocol list advertised by client does not
645 overlap this range, you will receive the error message
646 "unknown protocol". The available versions are: TLSv1.3,
647 TLSv1.2, TLSv1.1, and TLSv1.0
648 Default: TLSv1.3
650 --tls-ticket-key-file=<PATH>
652 Path to file that contains random data to construct TLS session
653 ticket parameters. If aes-128-cbc is given in
654 --tls-ticket-key-cipher, the file must contain exactly 48
655 bytes. If aes-256-cbc is given in
656 --tls-ticket-key-cipher, the file must contain exactly 80
657 bytes. This options can be used repeatedly to specify
658 multiple ticket parameters. If several files are given, only
659 the first key is used to encrypt TLS session tickets. Other
660 keys are accepted but server will issue new session ticket
661 with first key. This allows session key rotation. Please
662 note that key rotation does not occur automatically. User
663 should rearrange files or change options values and restart
664 nghttpx gracefully. If opening or reading given file fails,
665 all loaded keys are discarded and it is treated as if none of
666 this option is given. If this option is not given or an error
667 occurred while opening or reading a file, key is generated
668 every 1 hour internally and they are valid for 12 hours.
669 This is recommended if ticket key sharing between nghttpx
670 instances is not required.
671 --tls-ticket-key-memcached=<HOST>,<PORT>[;tls]
673 Specify address of memcached server to get TLS ticket keys
674 for session resumption. This enables shared TLS ticket key
675 between multiple nghttpx instances. nghttpx does not set TLS
676 ticket key to memcached. The external ticket key generator is
677 required. nghttpx just gets TLS ticket keys from memcached,
678 and use them, possibly replacing current set of keys. It is
679 up to extern TLS ticket key generator to rotate keys fre‐
680 quently. See "TLS SESSION TICKET RESUMPTION" section in man‐
681 ual page to know the data format in memcached entry. Option‐
682 ally, memcached connection can be encrypted with TLS by
683 specifying "tls" parameter.
684 --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6)
686 Specify address family of memcached connections to get TLS
687 ticket keys. If "auto" is given, both IPv4 and IPv6 are consid‐
688 ered. If "IPv4" is given, only IPv4 address is considered.
689 If "IPv6" is given, only IPv6 address is considered.
690 Default: auto
692 --tls-ticket-key-memcached-interval=<DURATION>
694 Set interval to get TLS ticket keys from memcached.
695 Default: 10m
697 --tls-ticket-key-memcached-max-retry=<N>
699 Set maximum number of consecutive retries before aban‐
700 doning TLS ticket key retrieval. If this number is reached,
701 the attempt is considered as failure, and "failure" count
702 is incremented by 1, which contributed to the
703 value controlled --tls-ticket-key-memcached-max-fail
704 option.
705 Default: 3
707 --tls-ticket-key-memcached-max-fail=<N>
709 Set maximum number of consecutive failure before dis‐
710 abling TLS ticket until next scheduled key retrieval.
711 Default: 2
713 --tls-ticket-key-cipher=<CIPHER>
715 Specify cipher to encrypt TLS session ticket. Specify either
716 aes-128-cbc or aes-256-cbc. By default, aes-128-cbc is
717 used.
718 --tls-ticket-key-memcached-cert-file=<PATH>
720 Path to client certificate for memcached connections to get TLS
721 ticket keys.
722 --tls-ticket-key-memcached-private-key-file=<PATH>
724 Path to client private key for memcached connections to get TLS
725 ticket keys.
726 --fetch-ocsp-response-file=<PATH>
728 Path to fetch-ocsp-response script file. It should be abso‐
729 lute path.
730 Default: /usr/local/share/nghttp2/fetch-ocsp-response
732 --ocsp-update-interval=<DURATION>
734 Set interval to update OCSP response cache.
735 Default: 4h
737 --ocsp-startup
739 Start accepting connections after initial attempts to get
740 OCSP responses finish. It does not matter some of the
741 attempts fail. This feature is useful if OCSP responses
742 must be available before accepting connections.
743 --no-verify-ocsp
745 nghttpx does not verify OCSP response.
746 --no-ocsp
748 Disable OCSP stapling.
749 --tls-session-cache-memcached=<HOST>,<PORT>[;tls]
751 Specify address of memcached server to store session cache.
752 This enables shared session cache between multiple
753 nghttpx instances. Optionally, memcached connection can be
754 encrypted with TLS by specifying "tls" parameter.
755 --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6)
757 Specify address family of memcached connections to store session
758 cache. If "auto" is given, both IPv4 and IPv6 are considered.
759 If "IPv4" is given, only IPv4 address is considered. If "IPv6"
760 is given, only IPv6 address is considered.
761 Default: auto
763 --tls-session-cache-memcached-cert-file=<PATH>
765 Path to client certificate for memcached connections to store
766 session cache.
767 --tls-session-cache-memcached-private-key-file=<PATH>
769 Path to client private key for memcached connections to store
770 session cache.
771 --tls-dyn-rec-warmup-threshold=<SIZE>
773 Specify the threshold size for TLS dynamic record size behav‐
774 iour. During a TLS session, after the threshold number of
775 bytes have been written, the TLS record size will be increased
776 to the maximum allowed (16K). The max record size will con‐
777 tinue to be used on the active TLS session. After
778 --tls-dyn-rec-idle-timeout has elapsed, the record size is
779 reduced to 1300 bytes. Specify 0 to always use the maximum
780 record size, regardless of idle period. This behaviour
781 applies to all TLS based frontends, and TLS HTTP/2 back‐
782 ends.
783 Default: 1M
785 --tls-dyn-rec-idle-timeout=<DURATION>
787 Specify TLS dynamic record size behaviour timeout. See
788 --tls-dyn-rec-warmup-threshold for more information. This
789 behaviour applies to all TLS based frontends, and TLS HTTP/2
790 backends.
791 Default: 1s
793 --no-http2-cipher-black-list
795 Allow black listed cipher suite on frontend HTTP/2 connec‐
796 tion. See
797 https://tools.ietf.org/html/rfc7540#appendix-A for the com‐
798 plete HTTP/2 cipher suites black list.
799 --client-no-http2-cipher-black-list
801 Allow black listed cipher suite on backend HTTP/2 connec‐
802 tion. See
803 https://tools.ietf.org/html/rfc7540#appendix-A for the com‐
804 plete HTTP/2 cipher suites black list.
805 --tls-sct-dir=<DIR>
807 Specifies the directory where *.sct files exist. All *.sct
808 files in <DIR> are read, and sent as extension_data
809 of TLS signed_certificate_timestamp (RFC 6962) to client.
810 These *.sct files are for the certificate specified in
811 positional command-line argument <CERT>, or certificate
812 option in configuration file. For additional certificates,
813 use --subcert option. This option requires OpenSSL >= 1.0.2.
814 --psk-secrets=<PATH>
816 Read list of PSK identity and secrets from <PATH>. This is used
817 for frontend connection. The each line of input file is for‐
818 matted as <identity>:<hex-secret>, where <identity> is PSK
819 identity, and <hex-secret> is secret in hex. An empty line,
820 and line which starts with '#' are skipped. The default
821 enabled cipher list might not contain any PSK cipher suite. In
822 that case, desired PSK cipher suites must be enabled using
823 --ciphers option. The desired PSK cipher suite may be black
824 listed by HTTP/2. To use those cipher suites with
825 HTTP/2, consider to use --no-http2-cipher-black-list option.
826 But be aware its implications.
827 --client-psk-secrets=<PATH>
829 Read PSK identity and secrets from <PATH>. This is used for
830 backend connection. The each line of input file is formatted
831 as <identity>:<hex-secret>, where <identity> is PSK identity,
832 and <hex-secret> is secret in hex. An empty line, and line
833 which starts with '#' are skipped. The first identity and
834 secret pair encountered is used. The default enabled cipher
835 list might not contain any PSK cipher suite. In that case,
836 desired PSK cipher suites must be enabled using
837 --client-ciphers option. The desired PSK cipher suite may be
838 black listed by HTTP/2. To use those cipher suites with
839 HTTP/2, consider to use --client-no-http2-cipher-black-list
840 option. But be aware its implications.
841 --tls-no-postpone-early-data
843 By default, nghttpx postpones forwarding HTTP requests sent in
844 early data, including those sent in partially in it, until TLS
845 handshake finishes. If all backend server recognizes
846 "Early-Data" header field, using this option makes nghttpx not
847 postpone forwarding request and get full potential of 0-RTT
848 data.
849 --tls-max-early-data=<SIZE>
851 Sets the maximum amount of 0-RTT data that server
852 accepts.
853 Default: 16K
855 HTTP/2
857 -c, --frontend-http2-max-concurrent-streams=<N>
858 Set the maximum number of the concurrent streams in one fron‐
859 tend HTTP/2 session.
860 Default: 100
862 --backend-http2-max-concurrent-streams=<N>
864 Set the maximum number of the concurrent streams in one backend
865 HTTP/2 session. This sets maximum number of concurrent
866 opened pushed streams. The maximum number of concurrent
867 requests are set by a remote server.
868 Default: 100
870 --frontend-http2-window-size=<SIZE>
872 Sets the per-stream initial window size of HTTP/2 fron‐
873 tend connection.
874 Default: 65535
876 --frontend-http2-connection-window-size=<SIZE>
878 Sets the per-connection window size of HTTP/2 frontend connec‐
879 tion.
880 Default: 65535
882 --backend-http2-window-size=<SIZE>
884 Sets the initial window size of HTTP/2 backend connec‐
885 tion.
886 Default: 65535
888 --backend-http2-connection-window-size=<SIZE>
890 Sets the per-connection window size of HTTP/2 backend connec‐
891 tion.
892 Default: 2147483647
894 --http2-no-cookie-crumbling
896 Don't crumble cookie header field.
897 --padding=<N>
899 Add at most <N> bytes to a HTTP/2 frame payload as pad‐
900 ding. Specify 0 to disable padding. This option is meant for
901 debugging purpose and not intended to enhance protocol secu‐
902 rity.
903 --no-server-push
905 Disable HTTP/2 server push. Server push is supported by default
906 mode and HTTP/2 frontend via Link header field. It is also
907 supported if both frontend and backend are HTTP/2 in default
908 mode. In this case, server push from backend session is
909 relayed to frontend, and server push via Link header field is
910 also supported.
911 --frontend-http2-optimize-write-buffer-size
913 (Experimental) Enable write buffer size optimization in fron‐
914 tend HTTP/2 TLS connection. This optimization aims to reduce
915 write buffer size so that it only contains bytes which can
916 send immediately. This makes server more responsive to prior‐
917 itized HTTP/2 stream because the buffering of lower priority
918 stream is reduced. This option is only effective on recent
919 Linux platform.
920 --frontend-http2-optimize-window-size
922 (Experimental) Automatically tune connection level window
923 size of frontend HTTP/2 TLS connection. If this feature is
924 enabled, connection window size starts with the default win‐
925 dow size, 65535 bytes. nghttpx automatically adjusts
926 connection window size based on TCP receiving window size.
927 The maximum window size is capped by the value
928 specified by --frontend-http2-connection-window-size.
929 Since the stream is subject to stream level window size, it
930 should be adjusted using --frontend-http2-window-size option as
931 well. This option is only effective on recent Linux plat‐
932 form.
933 --frontend-http2-encoder-dynamic-table-size=<SIZE>
935 Specify the maximum dynamic table size of HPACK encoder in the
936 frontend HTTP/2 connection. The decoder (client) specifies the
937 maximum dynamic table size it accepts. Then the negotiated
938 dynamic table size is the minimum of this option value and the
939 value which client specified.
940 Default: 4K
942 --frontend-http2-decoder-dynamic-table-size=<SIZE>
944 Specify the maximum dynamic table size of HPACK decoder in the
945 frontend HTTP/2 connection.
946 Default: 4K
948 --backend-http2-encoder-dynamic-table-size=<SIZE>
950 Specify the maximum dynamic table size of HPACK encoder in the
951 backend HTTP/2 connection. The decoder (backend) specifies the
952 maximum dynamic table size it accepts. Then the negotiated
953 dynamic table size is the minimum of this option value and the
954 value which backend specified.
955 Default: 4K
957 --backend-http2-decoder-dynamic-table-size=<SIZE>
959 Specify the maximum dynamic table size of HPACK decoder in the
960 backend HTTP/2 connection.
961 Default: 4K
963 Mode
965 (default mode)
966 Accept HTTP/2, and HTTP/1.1 over SSL/TLS. "no-tls" parame‐
967 ter is used in --frontend option, accept HTTP/2 and HTTP/1.1
968 over cleartext TCP. The incoming HTTP/1.1 connection can be
969 upgraded to HTTP/2 through HTTP Upgrade.
970 -s, --http2-proxy
972 Like default mode, but enable forward proxy. This is so called
973 HTTP/2 proxy mode.
974 Logging
976 -L, --log-level=<LEVEL>
977 Set the severity level of log output. <LEVEL> must be one of
978 INFO, NOTICE, WARN, ERROR and FATAL.
979 Default: NOTICE
981 --accesslog-file=<PATH>
983 Set path to write access log. To reopen file, send USR1 signal
984 to nghttpx.
985 --accesslog-syslog
987 Send access log to syslog. If this option is used,
988 --accesslog-file option is ignored.
989 --accesslog-format=<FORMAT>
991 Specify format string for access log. The default format
992 is combined format. The following variables are available:
993 · $remote_addr: client IP address.
995 · $time_local: local time in Common Log format.
997 · $time_iso8601: local time in ISO 8601 format.
999 · $request: HTTP request line.
1001 · $status: HTTP response status code.
1003 · $body_bytes_sent: the number of bytes sent to client as
1005 response body.
1006 · $http_<VAR>: value of HTTP request header <VAR> where '_' in
1008 <VAR> is replaced with '-'.
1009 · $remote_port: client port.
1011 · $server_port: server port.
1013 · $request_time: request processing time in seconds with mil‐
1015 liseconds resolution.
1016 · $pid: PID of the running process.
1018 · $alpn: ALPN identifier of the protocol which generates the
1020 response. For HTTP/1, ALPN is always http/1.1, regardless
1021 of minor version.
1022 · $tls_cipher: cipher used for SSL/TLS connection.
1024 · $tls_client_fingerprint_sha256: SHA-256 fingerprint of client
1026 certificate.
1027 · $tls_client_fingerprint_sha1: SHA-1 fingerprint of client
1029 certificate.
1030 · $tls_client_subject_name: subject name in client cer‐
1032 tificate.
1033 · $tls_client_issuer_name: issuer name in client cer‐
1035 tificate.
1036 · $tls_client_serial: serial number in client cer‐
1038 tificate.
1039 · $tls_protocol: protocol for SSL/TLS connection.
1041 · $tls_session_id: session ID for SSL/TLS connection.
1043 · $tls_session_reused: "r" if SSL/TLS session was reused.
1045 Otherwise, "."
1046 · $tls_sni: SNI server name for SSL/TLS connection.
1048 · $backend_host: backend host used to fulfill the
1050 request. "-" if backend host is not available.
1051 · $backend_port: backend port used to fulfill the
1053 request. "-" if backend host is not available.
1054 · $method: HTTP method
1056 · $path: Request path including query. For CONNECT
1058 request, authority is recorded.
1059 · $path_without_query: $path up to the first '?' charac‐
1061 ter. For CONNECT request, authority is recorded.
1062 · $protocol_version: HTTP version (e.g., HTTP/1.1, HTTP/2)
1064 The variable can be enclosed by "{" and "}" for disam‐
1066 biguation (e.g., ${remote_addr}).
1067 Default: $remote_addr - - [$time_local] "$request" $status
1069 $body_bytes_sent "$http_referer" "$http_user_agent"
1070 --accesslog-write-early
1072 Write access log when response header fields are
1073 received from backend rather than when request trans‐
1074 action finishes.
1075 --errorlog-file=<PATH>
1077 Set path to write error log. To reopen file, send USR1 signal
1078 to nghttpx. stderr will be redirected to the error log file
1079 unless --errorlog-syslog is used.
1080 Default: /dev/stderr
1082 --errorlog-syslog
1084 Send error log to syslog. If this option is used,
1085 --errorlog-file option is ignored.
1086 --syslog-facility=<FACILITY>
1088 Set syslog facility to <FACILITY>.
1089 Default: daemon
1091 HTTP
1093 --add-x-forwarded-for
1094 Append X-Forwarded-For header field to the downstream
1095 request.
1096 --strip-incoming-x-forwarded-for
1098 Strip X-Forwarded-For header field from inbound client
1099 requests.
1100 --no-add-x-forwarded-proto
1102 Don't append additional X-Forwarded-Proto header field to the
1103 backend request. If inbound client sets X-For‐
1104 warded-Proto, and
1105 --no-strip-incoming-x-forwarded-proto option is used, they
1106 are passed to the backend.
1107 --no-strip-incoming-x-forwarded-proto
1109 Don't strip X-Forwarded-Proto header field from inbound client
1110 requests.
1111 --add-forwarded=<LIST>
1113 Append RFC 7239 Forwarded header field with parameters speci‐
1114 fied in comma delimited list <LIST>. The supported parameters
1115 are "by", "for", "host", and "proto". By default, the value
1116 of "by" and "for" parameters are obfuscated string.
1117 See --forwarded-by and --forwarded-for options respec‐
1118 tively. Note that nghttpx does not translate non-standard
1119 X-Forwarded-* header fields into Forwarded header field, and
1120 vice versa.
1121 --strip-incoming-forwarded
1123 Strip Forwarded header field from inbound client
1124 requests.
1125 --forwarded-by=(obfuscated|ip|<VALUE>)
1127 Specify the parameter value sent out with "by" parameter of For‐
1128 warded header field. If "obfuscated" is given, the string is
1129 randomly generated at startup. If "ip" is given, the inter‐
1130 face address of the connection, including port number, is
1131 sent with "by" parameter. In case of UNIX domain socket,
1132 "localhost" is used instead of address and port. User can also
1133 specify the static obfuscated string. The limitation is that it
1134 must start with "_", and only consists of character
1135 set [A-Za-z0-9._-], as described in RFC 7239.
1136 Default: obfuscated
1138 --forwarded-for=(obfuscated|ip)
1140 Specify the parameter value sent out with "for" parame‐
1141 ter of Forwarded header field. If "obfuscated" is given, the
1142 string is randomly generated for each client connection. If
1143 "ip" is given, the remote client address of the connection,
1144 without port number, is sent with "for" parameter. In case
1145 of UNIX domain socket, "localhost" is used instead of
1146 address.
1147 Default: obfuscated
1149 --no-via
1151 Don't append to Via header field. If Via header field is
1152 received, it is left unaltered.
1153 --no-strip-incoming-early-data
1155 Don't strip Early-Data header field from inbound client
1156 requests.
1157 --no-location-rewrite
1159 Don't rewrite location header field in default mode. When
1160 --http2-proxy is used, location header field will not be
1161 altered regardless of this option.
1162 --host-rewrite
1164 Rewrite host and :authority header fields in default mode.
1165 When --http2-proxy is used, these headers will not be altered
1166 regardless of this option.
1167 --altsvc=<PROTOID,PORT[,HOST,[ORIGIN]]>
1169 Specify protocol ID, port, host and origin of alter‐
1170 native service. <HOST> and <ORIGIN> are optional. They are
1171 advertised in alt-svc header field only in HTTP/1.1 fron‐
1172 tend. This option can be used multiple times to specify
1173 multiple alternative services. Example: --altsvc=h2,443
1174 --add-request-header=<HEADER>
1176 Specify additional header field to add to request header set.
1177 This option just appends header field and won't replace any‐
1178 thing already set. This option can be used several times
1179 to specify multiple header fields. Example:
1180 --add-request-header="foo: bar"
1181 --add-response-header=<HEADER>
1183 Specify additional header field to add to response header
1184 set. This option just appends header field and won't replace
1185 anything already set. This option can be used several times
1186 to specify multiple header fields. Example:
1187 --add-response-header="foo: bar"
1188 --request-header-field-buffer=<SIZE>
1190 Set maximum buffer size for incoming HTTP request header field
1191 list. This is the sum of header name and value in bytes. If
1192 trailer fields exist, they are counted towards this number.
1193 Default: 64K
1195 --max-request-header-fields=<N>
1197 Set maximum number of incoming HTTP request header fields.
1198 If trailer fields exist, they are counted towards this num‐
1199 ber.
1200 Default: 100
1202 --response-header-field-buffer=<SIZE>
1204 Set maximum buffer size for incoming HTTP response header
1205 field list. This is the sum of header name and value in
1206 bytes. If trailer fields exist, they are counted towards
1207 this number.
1208 Default: 64K
1210 --max-response-header-fields=<N>
1212 Set maximum number of incoming HTTP response header fields.
1213 If trailer fields exist, they are counted towards this num‐
1214 ber.
1215 Default: 500
1217 --error-page=(<CODE>|*)=<PATH>
1219 Set file path to custom error page served when nghttpx origi‐
1220 nally generates HTTP error status code <CODE>. <CODE> must
1221 be greater than or equal to 400, and at most 599. If "*" is
1222 used instead of <CODE>, it matches all HTTP status code. If
1223 error status code comes from backend server, the custom error
1224 pages are not used.
1225 --server-name=<NAME>
1227 Change server response header field value to <NAME>.
1228 Default: nghttpx
1230 --no-server-rewrite
1232 Don't rewrite server header field in default mode. When
1233 --http2-proxy is used, these headers will not be altered regard‐
1234 less of this option.
1235 --redirect-https-port=<PORT>
1237 Specify the port number which appears in Location header field
1238 when redirect to HTTPS URI is made due to "redi‐
1239 rect-if-not-tls" parameter in --backend option.
1240 Default: 443
1242 API
1244 --api-max-request-body=<SIZE>
1245 Set the maximum size of request body for API request.
1246 Default: 32M
1248 DNS
1250 --dns-cache-timeout=<DURATION>
1251 Set duration that cached DNS results remain valid. Note that
1252 nghttpx caches the unsuccessful results as well.
1253 Default: 10s
1255 --dns-lookup-timeout=<DURATION>
1257 Set timeout that DNS server is given to respond to the initial
1258 DNS query. For the 2nd and later queries, server is given
1259 time based on this timeout, and it is scaled linearly.
1260 Default: 5s
1262 --dns-max-try=<N>
1264 Set the number of DNS query before nghttpx gives up name lookup.
1265 Default: 2
1267 --frontend-max-requests=<N>
1269 The number of requests that single frontend connection can
1270 process. For HTTP/2, this is the number of streams in one
1271 HTTP/2 connection. For HTTP/1, this is the number of keep
1272 alive requests. This is hint to nghttpx, and it may allow
1273 additional few requests. The default value is unlimited.
1274 Debug
1276 --frontend-http2-dump-request-header=<PATH>
1277 Dumps request headers received by HTTP/2 frontend to the file
1278 denoted in <PATH>. The output is done in HTTP/1 header field
1279 format and each header block is followed by an empty line. This
1280 option is not thread safe and MUST NOT be used with option
1281 -n<N>, where <N> >= 2.
1282 --frontend-http2-dump-response-header=<PATH>
1284 Dumps response headers sent from HTTP/2 frontend to the file
1285 denoted in <PATH>. The output is done in HTTP/1 header field
1286 format and each header block is followed by an empty line. This
1287 option is not thread safe and MUST NOT be used with option
1288 -n<N>, where <N> >= 2.
1289 -o, --frontend-frame-debug
1291 Print HTTP/2 frames in frontend to stderr. This option is not
1292 thread safe and MUST NOT be used with option -n=N, where N
1293 >= 2.
1294 Process
1296 -D, --daemon
1297 Run in a background. If -D is used, the current working direc‐
1298 tory is changed to '/'.
1299 --pid-file=<PATH>
1301 Set path to save PID of this program.
1302 --user=<USER>
1304 Run this program as <USER>. This option is intended to be used
1305 to drop root privileges.
1306 --single-process
1308 Run this program in a single process mode for debugging pur‐
1309 pose. Without this option, nghttpx creates at least 2 pro‐
1310 cesses: master and worker processes. If this option is
1311 used, master and worker are unified into a single process.
1312 nghttpx still spawns additional process if neverbleed is used.
1313 In the single process mode, the signal handling feature is dis‐
1314 abled.
1315 Scripting
1317 --mruby-file=<PATH>
1318 Set mruby script file
1319 --ignore-per-pattern-mruby-error
1321 Ignore mruby compile error for per-pattern mruby script file.
1322 If error occurred, it is treated as if no mruby file were
1323 specified for the pattern.
1324 Misc
1326 --conf=<PATH>
1327 Load configuration from <PATH>. Please note that nghttpx
1328 always tries to read the default configuration file if --conf
1329 is not given.
1330 Default: /etc/nghttpx/nghttpx.conf
1332 --include=<PATH>
1334 Load additional configurations from <PATH>. File <PATH> is
1335 read when configuration parser encountered this option.
1336 This option can be used multiple times, or even recursively.
1337 -v, --version
1339 Print version and exit.
1340 -h, --help
1342 Print this help and exit.
1343 The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
1345 * 1024). Units are K, M and G (powers of 1024).
1346 The <DURATION> argument is an integer and an optional unit (e.g., 1s is
1348 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
1349 (hours, minutes, seconds and milliseconds, respectively). If a unit is
1350 omitted, a second is used as unit.
1351
1353 /etc/nghttpx/nghttpx.conf
1354 The default configuration file path nghttpx searches at startup.
1355 The configuration file path can be changed using --conf option.
1356 Those lines which are staring # are treated as comment.
1358 The option name in the configuration file is the long com‐
1360 mand-line option name with leading -- stripped (e.g., frontend).
1361 Put = between option name and value. Don't put extra leading or
1362 trailing spaces.
1363 When specifying arguments including characters which have spe‐
1365 cial meaning to a shell, we usually use quotes so that shell
1366 does not interpret them. When writing this configuration file,
1367 quotes for this purpose must not be used. For example, specify
1368 additional request header field, do this:
1369 add-request-header=foo: bar
1371 instead of:
1373 add-request-header="foo: bar"
1375 The options which do not take argument in the command-line take
1377 argument in the configuration file. Specify yes as an argument
1378 (e.g., http2-proxy=yes). If other string is given, it is
1379 ignored.
1380 To specify private key and certificate file which are given as
1382 positional arguments in command-line, use private-key-file and
1383 certificate-file.
1384 --conf option cannot be used in the configuration file and will
1386 be ignored if specified.
1387 Error log
1389 Error log is written to stderr by default. It can be configured
1390 using --errorlog-file. The format of log message is as follows:
1391 <datetime> <master-pid> <current-pid> <thread-id> <level>
1393 (<filename>:<line>) <msg>
1394 <datetime>
1396 It is a combination of date and time when the log is
1397 written. It is in ISO 8601 format.
1398 <master-pid>
1400 It is a master process ID.
1401 <current-pid>
1403 It is a process ID which writes this log.
1404 <thread-id>
1406 It is a thread ID which writes this log. It would be
1407 unique within <current-pid>.
1408 <filename> and <line>
1410 They are source file name, and line number which produce
1411 this log.
1412 <msg> It is a log message body.
1414
1416 SIGQUIT
1417 Shutdown gracefully. First accept pending connections and stop
1418 accepting connection. After all connections are handled,
1419 nghttpx exits.
1420 SIGHUP Reload configuration file given in --conf.
1422 SIGUSR1
1424 Reopen log files.
1425 SIGUSR2
1427 Fork and execute nghttpx. It will execute the binary in the same
1428 path with same command-line arguments and environment variables. As
1429 of nghttpx version 1.20.0, the new master process sends SIGQUIT to
1430 the original master process when it is ready to serve requests. For
1431 the earlier versions of nghttpx, user has to send SIGQUIT to the
1432 original master process.
1433 The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
1435 is usually used to execute new binary, and the master process is
1436 newly spawned. On the other hand, the latter just reloads configu‐
1437 ration file, and the same master process continues to exist.
1438 NOTE:
1440 nghttpx consists of multiple processes: one process for processing
1441 these signals, and another one for processing requests. The former
1442 spawns the latter. The former is called master process, and the
1443 latter is called worker process. If neverbleed is enabled, the
1444 worker process spawns neverbleed daemon process which does RSA key
1445 processing. The above signal must be sent to the master process.
1446 If the other processes received one of them, it is ignored. This
1447 behaviour of these processes may change in the future release. In
1448 other words, in the future release, the processes other than master
1449 process may terminate upon the reception of these signals. There‐
1450 fore these signals should not be sent to the processes other than
1451 master process.
1452
1454 nghttpx supports HTTP/2 server push in default mode with Link header
1455 field. nghttpx looks for Link header field (RFC 5988) in response
1456 headers from backend server and extracts URI-reference with parameter
1457 rel=preload (see preload) and pushes those URIs to the frontend client.
1458 Here is a sample Link header field to initiate server push:
1459 Link: </fonts/font.woff>; rel=preload
1461 Link: </css/theme.css>; rel=preload
1462 Currently, the following restriction is applied for server push:
1464 1. The associated stream must have method "GET" or "POST". The associ‐
1466 ated stream's status code must be 200.
1467 This limitation may be loosened in the future release.
1469 nghttpx also supports server push if both frontend and backend are
1471 HTTP/2 in default mode. In this case, in addition to server push via
1472 Link header field, server push from backend is forwarded to frontend
1473 HTTP/2 session.
1474 HTTP/2 server push will be disabled if --http2-proxy is used.
1476
1478 nghttpx supports UNIX domain socket with a filename for both frontend
1479 and backend connections.
1480 Please note that current nghttpx implementation does not delete a
1482 socket with a filename. And on start up, if nghttpx detects that the
1483 specified socket already exists in the file system, nghttpx first
1484 deletes it. However, if SIGUSR2 is used to execute new binary and both
1485 old and new configurations use same filename, new binary does not
1486 delete the socket and continues to use it.
1487
1489 OCSP query is done using external Python script fetch-ocsp-response,
1490 which has been originally developed in Perl as part of h2o project (‐
1491 https://github.com/h2o/h2o), and was translated into Python.
1492 The script file is usually installed under $(prefix)/share/nghttp2/
1494 directory. The actual path to script can be customized using
1495 --fetch-ocsp-response-file option.
1496 If OCSP query is failed, previous OCSP response, if any, is continued
1498 to be used.
1499 --fetch-ocsp-response-file option provides wide range of possibility to
1501 manage OCSP response. It can take an arbitrary script or executable.
1502 The requirement is that it supports the command-line interface of
1503 fetch-ocsp-response script, and it must return a valid DER encoded OCSP
1504 response on success. It must return exit code 0 on success, and 75 for
1505 temporary error, and the other error code for generic failure. For
1506 large cluster of servers, it is not efficient for each server to per‐
1507 form OCSP query using fetch-ocsp-response. Instead, you can retrieve
1508 OCSP response in some way, and store it in a disk or a shared database.
1509 Then specify a program in --fetch-ocsp-response-file to fetch it from
1510 those stores. This could provide a way to share the OCSP response
1511 between fleet of servers, and also any OCSP query strategy can be
1512 applied which may be beyond the ability of nghttpx itself or
1513 fetch-ocsp-response script.
1514
1516 nghttpx supports TLS session resumption through both session ID and
1517 session ticket.
1518 SESSION ID RESUMPTION
1520 By default, session ID is shared by all worker threads.
1521 If --tls-session-cache-memcached is given, nghttpx will insert serial‐
1523 ized session data to memcached with nghttpx:tls-session-cache: + lower‐
1524 case hex string of session ID as a memcached entry key, with expiry
1525 time 12 hours. Session timeout is set to 12 hours.
1526 By default, connections to memcached server are not encrypted. To
1528 enable encryption, use tls keyword in --tls-session-cache-memcached
1529 option.
1530 TLS SESSION TICKET RESUMPTION
1532 By default, session ticket is shared by all worker threads. The auto‐
1533 matic key rotation is also enabled by default. Every an hour, new
1534 encryption key is generated, and previous encryption key becomes
1535 decryption only key. We set session timeout to 12 hours, and thus we
1536 keep at most 12 keys.
1537 If --tls-ticket-key-memcached is given, encryption keys are retrieved
1539 from memcached. nghttpx just reads keys from memcached; one has to
1540 deploy key generator program to update keys frequently (e.g., every 1
1541 hour). The example key generator tlsticketupdate.go is available under
1542 contrib directory in nghttp2 archive. The memcached entry key is
1543 nghttpx:tls-ticket-key. The data format stored in memcached is the
1544 binary format described below:
1545 +--------------+-------+----------------+
1547 | VERSION (4) |LEN (2)|KEY(48 or 80) ...
1548 +--------------+-------+----------------+
1549 ^ |
1550 | |
1551 +------------------------+
1552 (LEN, KEY) pair can be repeated
1553 All numbers in the above figure is bytes. All integer fields are net‐
1555 work byte order.
1556 First 4 bytes integer VERSION field, which must be 1. The 2 bytes
1558 integer LEN field gives the length of following KEY field, which con‐
1559 tains key. If --tls-ticket-key-cipher=aes-128-cbc is used, LEN must be
1560 48. If --tls-ticket-key-cipher=aes-256-cbc is used, LEN must be 80.
1561 LEN and KEY pair can be repeated multiple times to store multiple keys.
1562 The key appeared first is used as encryption key. All the remaining
1563 keys are used as decryption only.
1564 By default, connections to memcached server are not encrypted. To
1566 enable encryption, use tls keyword in --tls-ticket-key-memcached
1567 option.
1568 If --tls-ticket-key-file is given, encryption key is read from the
1570 given file. In this case, nghttpx does not rotate key automatically.
1571 To rotate key, one has to restart nghttpx (see SIGNALS).
1572
1574 nghttpx supports TLS signed_certificate_timestamp extension (RFC 6962).
1575 The relevant options are --tls-sct-dir and sct-dir parameter in
1576 --subcert. They takes a directory, and nghttpx reads all files whose
1577 extension is .sct under the directory. The *.sct files are encoded as
1578 SignedCertificateTimestamp struct described in section 3.2 of RFC
1579 69662. This format is the same one used by nginx-ct and mod_ssl_ct.
1580 ct-submit can be used to submit certificates to log servers, and obtain
1581 the SignedCertificateTimestamp struct which can be used with nghttpx.
1582
1584 WARNING:
1585 The current mruby extension API is experimental and not frozen. The
1586 API is subject to change in the future release.
1587 WARNING:
1589 Almost all string value returned from method, or attribute is a
1590 fresh new mruby string, which involves memory allocation, and
1591 copies. Therefore, it is strongly recommended to store a return
1592 value in a local variable, and use it, instead of calling method or
1593 accessing attribute repeatedly.
1594 nghttpx allows users to extend its capability using mruby scripts.
1596 nghttpx has 2 hook points to execute mruby script: request phase and
1597 response phase. The request phase hook is invoked after all request
1598 header fields are received from client. The response phase hook is
1599 invoked after all response header fields are received from backend
1600 server. These hooks allows users to modify header fields, or common
1601 HTTP variables, like authority or request path, and even return custom
1602 response without forwarding request to backend servers.
1603 There are 2 levels of mruby script invocations: global and per-pattern.
1605 The global mruby script is set by --mruby-file option and is called for
1606 all requests. The per-pattern mruby script is set by "mruby" parameter
1607 in -b option. It is invoked for a request which matches the particular
1608 pattern. The order of hook invocation is: global request phase hook,
1609 per-pattern request phase hook, per-pattern response phase hook, and
1610 finally global response phase hook. If a hook returns a response, any
1611 later hooks are not invoked. The global request hook is invoked before
1612 the pattern matching is made and changing request path may affect the
1613 pattern matching.
1614 Please note that request and response hooks of per-pattern mruby script
1616 for a single request might not come from the same script. This might
1617 happen after a request hook is executed, backend failed for some rea‐
1618 son, and at the same time, backend configuration is replaced by API
1619 request, and then the request uses new configuration on retry. The
1620 response hook from new configuration, if it is specified, will be
1621 invoked.
1622 The all mruby script will be evaluated once per thread on startup, and
1624 it must instantiate object and evaluate it as the return value (e.g.,
1625 App.new). This object is called app object. If app object defines
1626 on_req method, it is called with Nghttpx::Env object on request hook.
1627 Similarly, if app object defines on_resp method, it is called with
1628 Nghttpx::Env object on response hook. For each method invocation, user
1629 can can access Nghttpx::Request and Nghttpx::Response objects via
1630 Nghttpx::Env#req and Nghttpx::Env#resp respectively.
1631 Nghttpx::REQUEST_PHASE
1633 Constant to represent request phase.
1634 Nghttpx::RESPONSE_PHASE
1636 Constant to represent response phase.
1637 class Nghttpx::Env
1639 Object to represent current request specific context.
1640 attribute [R] req
1642 Return Request object.
1643 attribute [R] resp
1645 Return Response object.
1646 attribute [R] ctx
1648 Return Ruby hash object. It persists until request fin‐
1649 ishes. So values set in request phase hook can be
1650 retrieved in response phase hook.
1651 attribute [R] phase
1653 Return the current phase.
1654 attribute [R] remote_addr
1656 Return IP address of a remote client. If connection is
1657 made via UNIX domain socket, this returns the string
1658 "localhost".
1659 attribute [R] server_addr
1661 Return address of server that accepted the connection.
1662 This is a string which specified in --frontend option,
1663 excluding port number, and not a resolved IP address.
1664 For UNIX domain socket, this is a path to UNIX domain
1665 socket.
1666 attribute [R] server_port
1668 Return port number of the server frontend which accepted
1669 the connection from client.
1670 attribute [R] tls_used
1672 Return true if TLS is used on the connection.
1673 attribute [R] tls_sni
1675 Return the TLS SNI value which client sent in this con‐
1676 nection.
1677 attribute [R] tls_client_fingerprint_sha256
1679 Return the SHA-256 fingerprint of a client certificate.
1680 attribute [R] tls_client_fingerprint_sha1
1682 Return the SHA-1 fingerprint of a client certificate.
1683 attribute [R] tls_client_issuer_name
1685 Return the issuer name of a client certificate.
1686 attribute [R] tls_client_subject_name
1688 Return the subject name of a client certificate.
1689 attribute [R] tls_client_serial
1691 Return the serial number of a client certificate.
1692 attribute [R] tls_client_not_before
1694 Return the start date of a client certificate in seconds
1695 since the epoch.
1696 attribute [R] tls_client_not_after
1698 Return the end date of a client certificate in seconds
1699 since the epoch.
1700 attribute [R] tls_cipher
1702 Return a TLS cipher negotiated in this connection.
1703 attribute [R] tls_protocol
1705 Return a TLS protocol version negotiated in this connec‐
1706 tion.
1707 attribute [R] tls_session_id
1709 Return a session ID for this connection in hex string.
1710 attribute [R] tls_session_reused
1712 Return true if, and only if a SSL/TLS session is reused.
1713 attribute [R] alpn
1715 Return ALPN identifier negotiated in this connection.
1716 attribute [R] tls_handshake_finished
1718 Return true if SSL/TLS handshake has finished. If it
1719 returns false in the request phase hook, the request is
1720 received in TLSv1.3 early data (0-RTT) and might be vul‐
1721 nerable to the replay attack. nghttpx will send
1722 Early-Data header field to backend servers to indicate
1723 this.
1724 class Nghttpx::Request
1726 Object to represent request from client. The modification to
1727 Request object is allowed only in request phase hook.
1728 attribute [R] http_version_major
1730 Return HTTP major version.
1731 attribute [R] http_version_minor
1733 Return HTTP minor version.
1734 attribute [R/W] method
1736 HTTP method. On assignment, copy of given value is
1737 assigned. We don't accept arbitrary method name. We
1738 will document them later, but well known methods, like
1739 GET, PUT and POST, are all supported.
1740 attribute [R/W] authority
1742 Authority (i.e., example.org), including optional port
1743 component . On assignment, copy of given value is
1744 assigned.
1745 attribute [R/W] scheme
1747 Scheme (i.e., http, https). On assignment, copy of given
1748 value is assigned.
1749 attribute [R/W] path
1751 Request path, including query component (i.e.,
1752 /index.html). On assignment, copy of given value is
1753 assigned. The path does not include authority component
1754 of URI. This may include query component. nghttpx makes
1755 certain normalization for path. It decodes per‐
1756 cent-encoding for unreserved characters (see
1757 https://tools.ietf.org/html/rfc3986#section-2.3), and
1758 resolves ".." and ".". But it may leave characters which
1759 should be percent-encoded as is. So be careful when com‐
1760 paring path against desired string.
1761 attribute [R] headers
1763 Return Ruby hash containing copy of request header
1764 fields. Changing values in returned hash does not change
1765 request header fields actually used in request process‐
1766 ing. Use Nghttpx::Request#add_header or
1767 Nghttpx::Request#set_header to change request header
1768 fields.
1769 add_header(key, value)
1771 Add header entry associated with key. The value can be
1772 single string or array of string. It does not replace
1773 any existing values associated with key.
1774 set_header(key, value)
1776 Set header entry associated with key. The value can be
1777 single string or array of string. It replaces any exist‐
1778 ing values associated with key.
1779 clear_headers()
1781 Clear all existing request header fields.
1782 push(uri)
1784 Initiate to push resource identified by uri. Only HTTP/2
1785 protocol supports this feature. For the other protocols,
1786 this method is noop. uri can be absolute URI, absolute
1787 path or relative path to the current request. For abso‐
1788 lute or relative path, scheme and authority are inherited
1789 from the current request. Currently, method is always
1790 GET. nghttpx will issue request to backend servers to
1791 fulfill this request. The request and response phase
1792 hooks will be called for pushed resource as well.
1793 class Nghttpx::Response
1795 Object to represent response from backend server.
1796 attribute [R] http_version_major
1798 Return HTTP major version.
1799 attribute [R] http_version_minor
1801 Return HTTP minor version.
1802 attribute [R/W] status
1804 HTTP status code. It must be in the range [200, 999],
1805 inclusive. The non-final status code is not supported in
1806 mruby scripting at the moment.
1807 attribute [R] headers
1809 Return Ruby hash containing copy of response header
1810 fields. Changing values in returned hash does not change
1811 response header fields actually used in response process‐
1812 ing. Use Nghttpx::Response#add_header or
1813 Nghttpx::Response#set_header to change response header
1814 fields.
1815 add_header(key, value)
1817 Add header entry associated with key. The value can be
1818 single string or array of string. It does not replace
1819 any existing values associated with key.
1820 set_header(key, value)
1822 Set header entry associated with key. The value can be
1823 single string or array of string. It replaces any exist‐
1824 ing values associated with key.
1825 clear_headers()
1827 Clear all existing response header fields.
1828 return(body)
1830 Return custom response body to a client. When this
1831 method is called in request phase hook, the request is
1832 not forwarded to the backend, and response phase hook for
1833 this request will not be invoked. When this method is
1834 called in response phase hook, response from backend
1835 server is canceled and discarded. The status code and
1836 response header fields should be set before using this
1837 method. To set status code, use
1838 Nghttpx::Response#status. If status code is not set, 200
1839 is used. To set response header fields,
1840 Nghttpx::Response#add_header and
1841 Nghttpx::Response#set_header. When this method is
1842 invoked in response phase hook, the response headers are
1843 filled with the ones received from backend server. To
1844 send completely custom header fields, first call
1845 Nghttpx::Response#clear_headers to erase all existing
1846 header fields, and then add required header fields. It
1847 is an error to call this method twice for a given
1848 request.
1849 send_info(status, headers)
1851 Send non-final (informational) response to a client.
1852 status must be in the range [100, 199], inclusive. head‐
1853 ers is a hash containing response header fields. Its key
1854 must be a string, and the associated value must be either
1855 string or array of strings. Since this is not a final
1856 response, even if this method is invoked, request is
1857 still forwarded to a backend unless
1858 Nghttpx::Response#return is called. This method can be
1859 called multiple times. It cannot be called after
1860 Nghttpx::Response#return is called.
1861 MRUBY EXAMPLES
1863 Modify request path:
1864 class App
1866 def on_req(env)
1867 env.req.path = "/apps#{env.req.path}"
1868 end
1869 end
1870 App.new
1872 Don't forget to instantiate and evaluate object at the last line.
1874 Restrict permission of viewing a content to a specific client
1876 addresses:
1877 class App
1879 def on_req(env)
1880 allowed_clients = ["127.0.0.1", "::1"]
1881 if env.req.path.start_with?("/log/") &&
1883 !allowed_clients.include?(env.remote_addr) then
1884 env.resp.status = 404
1885 env.resp.return "permission denied"
1886 end
1887 end
1888 end
1889 App.new
1891
1893 nghttpx exposes API endpoints to manipulate it via HTTP based API. By
1894 default, API endpoint is disabled. To enable it, add a dedicated fron‐
1895 tend for API using --frontend option with "api" parameter. All
1896 requests which come from this frontend address, will be treated as API
1897 request.
1898 The response is normally JSON dictionary, and at least includes the
1900 following keys:
1901 status The status of the request processing. The following values are
1903 defined:
1904 Success
1906 The request was successful.
1907 Failure
1909 The request was failed. No change has been made.
1910 code HTTP status code
1912 Additionally, depending on the API endpoint, data key may be present,
1914 and its value contains the API endpoint specific data.
1915 We wrote "normally", since nghttpx may return ordinal HTML response in
1917 some cases where the error has occurred before reaching API endpoint
1918 (e.g., header field is too large).
1919 The following section describes available API endpoints.
1921 POST /api/v1beta1/backendconfig
1923 This API replaces the current backend server settings with the
1924 requested ones. The request method should be POST, but PUT is also
1925 acceptable. The request body must be nghttpx configuration file for‐
1926 mat. For configuration file format, see FILES section. The line sepa‐
1927 rator inside the request body must be single LF (0x0A). Currently,
1928 only backend option is parsed, the others are simply ignored. The
1929 semantics of this API is replace the current backend with the backend
1930 options in request body. Describe the desired set of backend severs,
1931 and nghttpx makes it happen. If there is no backend option is found in
1932 request body, the current set of backend is replaced with the backend
1933 option's default value, which is 127.0.0.1,80.
1934 The replacement is done instantly without breaking existing connections
1936 or requests. It also avoids any process creation as is the case with
1937 hot swapping with signals.
1938 The one limitation is that only numeric IP address is allowed in
1940 backend in request body unless "dns" parameter is used while non
1941 numeric hostname is allowed in command-line or configuration file is
1942 read using --conf.
1943 GET /api/v1beta1/configrevision
1945 This API returns configuration revision of the current nghttpx. The
1946 configuration revision is opaque string, and it changes after each
1947 reloading by SIGHUP. With this API, an external application knows that
1948 whether nghttpx has finished reloading its configuration by comparing
1949 the configuration revisions between before and after reloading. It is
1950 recommended to disable persistent (keep-alive) connection for this pur‐
1951 pose in order to avoid to send a request using the reused connection
1952 which may bound to an old process.
1953 This API returns response including data key. Its value is JSON
1955 object, and it contains at least the following key:
1956 configRevision
1958 The configuration revision of the current nghttpx
1959
1961 nghttp(1), nghttpd(1), h2load(1)
1962
1964 Tatsuhiro Tsujikawa
1965
1967 2012, 2015, 2016, Tatsuhiro Tsujikawa
19681.43.0 Feb 02, 2021 NGHTTPX(1)