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. Since ";" has special meaning in
237 shell, the option value must be quoted.
238 Default: 127.0.0.1,80
240 -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]
242 Set frontend host and port. If <HOST> is '*', it assumes
243 all addresses including both IPv4 and IPv6. UNIX domain
244 socket can be specified by prefixing path name with "unix:"
245 (e.g., unix:/var/run/nghttpx.sock). This option can be used
246 multiple times to listen to multiple addresses.
247 This option can take 0 or more parameters, which are
249 described below. Note that "api" and "healthmon" parame‐
250 ters are mutually exclusive.
251 Optionally, TLS can be disabled by specifying "no-tls" parame‐
253 ter. TLS is enabled by default.
254 If "sni-fwd" parameter is used, when performing a match to
256 select a backend server, SNI host name received from the client
257 is used instead of the request host. See --backend option
258 about the pattern match.
259 To make this frontend as API endpoint, specify "api" parame‐
261 ter. This is disabled by default. It is important to
262 limit the access to the API frontend. Otherwise, someone
263 may change the backend server, and break your services, or
264 expose confidential information to the outside the world.
265 To make this frontend as health monitor endpoint, specify
267 "healthmon" parameter. This is disabled by default. Any
268 requests which come through this address are replied with 200
269 HTTP status, without no body.
270 To accept PROXY protocol version 1 on frontend connec‐
272 tion, specify "proxyproto" parameter. This is disabled by
273 default.
274 Default: *,3000
276 --backlog=<N>
278 Set listen backlog size.
279 Default: 65536
281 --backend-address-family=(auto|IPv4|IPv6)
283 Specify address family of backend connections. If "auto"
284 is given, both IPv4 and IPv6 are considered. If "IPv4" is
285 given, only IPv4 address is considered. If "IPv6" is given,
286 only IPv6 address is considered.
287 Default: auto
289 --backend-http-proxy-uri=<URI>
291 Specify proxy URI in the form
292 http://[<USER>:<PASS>@]<PROXY>:<PORT>. If a proxy
293 requires authentication, specify <USER> and <PASS>. Note
294 that they must be properly percent-encoded. This proxy is
295 used when the backend connection is HTTP/2. First, make a
296 CONNECT request to the proxy and it connects to the back‐
297 end on behalf of nghttpx. This forms tunnel. After that,
298 nghttpx performs SSL/TLS handshake with the downstream
299 through the tunnel. The timeouts when connecting and making
300 CONNECT request can be specified by
301 --backend-read-timeout and --backend-write-timeout options.
302 Performance
304 -n, --workers=<N>
305 Set the number of worker threads.
306 Default: 1
308 --single-thread
310 Run everything in one thread inside the worker process. This
311 feature is provided for better debugging experience,
312 or for the platforms which lack thread support. If
313 threading is disabled, this option is always enabled.
314 --read-rate=<SIZE>
316 Set maximum average read rate on frontend connection. Set‐
317 ting 0 to this option means read rate is unlimited.
318 Default: 0
320 --read-burst=<SIZE>
322 Set maximum read burst size on frontend connection. Set‐
323 ting 0 to this option means read burst size is unlimited.
324 Default: 0
326 --write-rate=<SIZE>
328 Set maximum average write rate on frontend connection. Set‐
329 ting 0 to this option means write rate is unlimited.
330 Default: 0
332 --write-burst=<SIZE>
334 Set maximum write burst size on frontend connection. Set‐
335 ting 0 to this option means write burst size is unlimited.
336 Default: 0
338 --worker-read-rate=<SIZE>
340 Set maximum average read rate on frontend connection per worker.
341 Setting 0 to this option means read rate is unlimited. Not
342 implemented yet.
343 Default: 0
345 --worker-read-burst=<SIZE>
347 Set maximum read burst size on frontend connection per worker.
348 Setting 0 to this option means read burst size is unlimited.
349 Not implemented yet.
350 Default: 0
352 --worker-write-rate=<SIZE>
354 Set maximum average write rate on frontend connection per
355 worker. Setting 0 to this option means write rate is unlim‐
356 ited. Not implemented yet.
357 Default: 0
359 --worker-write-burst=<SIZE>
361 Set maximum write burst size on frontend connection per worker.
362 Setting 0 to this option means write burst size is unlimited.
363 Not implemented yet.
364 Default: 0
366 --worker-frontend-connections=<N>
368 Set maximum number of simultaneous connections frontend
369 accepts. Setting 0 means unlimited.
370 Default: 0
372 --backend-connections-per-host=<N>
374 Set maximum number of backend concurrent connections (and/or
375 streams in case of HTTP/2) per origin host. This option is
376 meaningful when --http2-proxy option is used. The origin
377 host is determined by authority portion of request URI (or
378 :authority header field for HTTP/2). To limit the number
379 of connections per frontend for default
380 mode, use --backend-connections-per-frontend.
381 Default: 8
383 --backend-connections-per-frontend=<N>
385 Set maximum number of backend concurrent connections (and/or
386 streams in case of HTTP/2) per frontend. This option is
387 only used for default mode. 0 means unlimited. To limit
388 the number of connections per host with --http2-proxy
389 option, use --backend-connections-per-host.
390 Default: 0
392 --rlimit-nofile=<N>
394 Set maximum number of open files (RLIMIT_NOFILE) to <N>. If 0
395 is given, nghttpx does not set the limit.
396 Default: 0
398 --backend-request-buffer=<SIZE>
400 Set buffer size used to store backend request.
401 Default: 16K
403 --backend-response-buffer=<SIZE>
405 Set buffer size used to store backend response.
406 Default: 128K
408 --fastopen=<N>
410 Enables "TCP Fast Open" for the listening socket and limits
411 the maximum length for the queue of connections that have not
412 yet completed the three-way handshake. If value is 0 then fast
413 open is disabled.
414 Default: 0
416 --no-kqueue
418 Don't use kqueue. This option is only applicable for the
419 platforms which have kqueue. For other platforms, this option
420 will be simply ignored.
421 Timeout
423 --frontend-http2-read-timeout=<DURATION>
424 Specify read timeout for HTTP/2 frontend connection.
425 Default: 3m
427 --frontend-read-timeout=<DURATION>
429 Specify read timeout for HTTP/1.1 frontend connection.
430 Default: 1m
432 --frontend-write-timeout=<DURATION>
434 Specify write timeout for all frontend connections.
435 Default: 30s
437 --frontend-keep-alive-timeout=<DURATION>
439 Specify keep-alive timeout for frontend HTTP/1 connec‐
440 tion.
441 Default: 1m
443 --stream-read-timeout=<DURATION>
445 Specify read timeout for HTTP/2 streams. 0 means no time‐
446 out.
447 Default: 0
449 --stream-write-timeout=<DURATION>
451 Specify write timeout for HTTP/2 streams. 0 means no time‐
452 out.
453 Default: 1m
455 --backend-read-timeout=<DURATION>
457 Specify read timeout for backend connection.
458 Default: 1m
460 --backend-write-timeout=<DURATION>
462 Specify write timeout for backend connection.
463 Default: 30s
465 --backend-connect-timeout=<DURATION>
467 Specify timeout before establishing TCP connection to back‐
468 end.
469 Default: 30s
471 --backend-keep-alive-timeout=<DURATION>
473 Specify keep-alive timeout for backend HTTP/1 connec‐
474 tion.
475 Default: 2s
477 --listener-disable-timeout=<DURATION>
479 After accepting connection failed, connection listener is dis‐
480 abled for a given amount of time. Specifying 0 disables this
481 feature.
482 Default: 30s
484 --frontend-http2-setting-timeout=<DURATION>
486 Specify timeout before SETTINGS ACK is received from client.
487 Default: 10s
489 --backend-http2-settings-timeout=<DURATION>
491 Specify timeout before SETTINGS ACK is received from backend
492 server.
493 Default: 10s
495 --backend-max-backoff=<DURATION>
497 Specify maximum backoff interval. This is used when doing
498 health check against offline backend (see "fail" parameter in
499 --backend option). It is also used to limit the maximum
500 interval to temporarily disable backend when nghttpx failed
501 to connect to it. These intervals are calculated using expo‐
502 nential backoff, and consecutive failed attempts increase the
503 interval. This option caps its maximum value.
504 Default: 2m
506 SSL/TLS
508 --ciphers=<SUITE>
509 Set allowed cipher list for frontend connection. The format
510 of the string is described in OpenSSL ciphers(1). This option
511 sets cipher suites for TLSv1.2 or earlier. Use --tls13-ciphers
512 for TLSv1.3.
513 Default:
515 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
516 --tls13-ciphers=<SUITE>
518 Set allowed cipher list for frontend connection. The format
519 of the string is described in OpenSSL ciphers(1). This option
520 sets cipher suites for TLSv1.3. Use --ciphers for TLSv1.2
521 or earlier.
522 Default:
524 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
525 --client-ciphers=<SUITE>
527 Set allowed cipher list for backend connection. The format
528 of the string is described in OpenSSL ciphers(1). This option
529 sets cipher suites for TLSv1.2 or earlier. Use
530 --tls13-client-ciphers for TLSv1.3.
531 Default:
533 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
534 --tls13-client-ciphers=<SUITE>
536 Set allowed cipher list for backend connection. The format
537 of the string is described in OpenSSL ciphers(1). This option
538 sets cipher suites for TLSv1.3. Use
539 --tls13-client-ciphers for TLSv1.2 or earlier.
540 Default:
542 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
543 --ecdh-curves=<LIST>
545 Set supported curve list for frontend connections. <LIST>
546 is a colon separated list of curve NID or names in the prefer‐
547 ence order. The supported curves depend on the linked OpenSSL
548 library. This function requires OpenSSL >= 1.0.2.
549 Default: X25519:P-256:P-384:P-521
551 -k, --insecure
553 Don't verify backend server's certificate if TLS is enabled
554 for backend connections.
555 --cacert=<PATH>
557 Set path to trusted CA certificate file. It is used in backend
558 TLS connections to verify peer's certificate. It is also used
559 to verify OCSP response from the script set by
560 --fetch-ocsp-response-file. The file must be in PEM format.
561 It can contain multiple certificates. If the linked OpenSSL
562 is configured to load system wide certificates, they are
563 loaded at startup regardless of this option.
564 --private-key-passwd-file=<PATH>
566 Path to file that contains password for the server's private
567 key. If none is given and the private key is password pro‐
568 tected it'll be requested interactively.
569 --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
571 Specify additional certificate and private key file.
572 nghttpx will choose certificates based on the hostname indi‐
573 cated by client using TLS SNI extension. If nghttpx is built
574 with OpenSSL >= 1.0.2, the shared elliptic curves (e.g.,
575 P-256) between client and server are also taken into consider‐
576 ation. This allows nghttpx to send ECDSA certificate to mod‐
577 ern clients, while sending RSA based certificate to older
578 clients. This option can be used multiple times. To make
579 OCSP stapling work, <CERTPATH> must be absolute path.
580 Additional parameter can be specified in <PARAM>. The avail‐
582 able <PARAM> is "sct-dir=<DIR>".
583 "sct-dir=<DIR>" specifies the path to directory which con‐
585 tains *.sct files for TLS
586 signed_certificate_timestamp extension (RFC 6962). This feature
587 requires OpenSSL >= 1.0.2. See also --tls-sct-dir
588 option.
589 --dh-param-file=<PATH>
591 Path to file that contains DH parameters in PEM format. With‐
592 out this option, DHE cipher suites are not available.
593 --npn-list=<LIST>
595 Comma delimited list of ALPN protocol identifier sorted in the
596 order of preference. That means most desirable protocol comes
597 first. This is used in both ALPN and NPN. The parameter
598 must be delimited by a single comma only and any white spaces
599 are treated as a part of protocol string.
600 Default: h2,h2-16,h2-14,http/1.1
602 --verify-client
604 Require and verify client certificate.
605 --verify-client-cacert=<PATH>
607 Path to file that contains CA certificates to verify client
608 certificate. The file must be in PEM format. It can contain
609 multiple certificates.
610 --verify-client-tolerate-expired
612 Accept expired client certificate. Operator should handle
613 the expired client certificate by some means (e.g., mruby
614 script). Otherwise, this option might cause a security risk.
615 --client-private-key-file=<PATH>
617 Path to file that contains client private key used in backend
618 client authentication.
619 --client-cert-file=<PATH>
621 Path to file that contains client certificate used in backend
622 client authentication.
623 --tls-min-proto-version=<VER>
625 Specify minimum SSL/TLS protocol. The name matching is done in
626 case-insensitive manner. The versions between
627 --tls-min-proto-version and --tls-max-proto-version are
628 enabled. If the protocol list advertised by client does not
629 overlap this range, you will receive the error message
630 "unknown protocol". If a protocol version lower than TLSv1.2 is
631 specified, make sure that the compatible ciphers are included
632 in --ciphers option. The default cipher list only includes
633 ciphers compatible with TLSv1.2 or above. The available ver‐
634 sions are: TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
635 Default: TLSv1.2
637 --tls-max-proto-version=<VER>
639 Specify maximum SSL/TLS protocol. The name matching is done in
640 case-insensitive manner. The versions between
641 --tls-min-proto-version and --tls-max-proto-version are
642 enabled. If the protocol list advertised by client does not
643 overlap this range, you will receive the error message
644 "unknown protocol". The available versions are: TLSv1.3,
645 TLSv1.2, TLSv1.1, and TLSv1.0
646 Default: TLSv1.3
648 --tls-ticket-key-file=<PATH>
650 Path to file that contains random data to construct TLS session
651 ticket parameters. If aes-128-cbc is given in
652 --tls-ticket-key-cipher, the file must contain exactly 48
653 bytes. If aes-256-cbc is given in
654 --tls-ticket-key-cipher, the file must contain exactly 80
655 bytes. This options can be used repeatedly to specify
656 multiple ticket parameters. If several files are given, only
657 the first key is used to encrypt TLS session tickets. Other
658 keys are accepted but server will issue new session ticket
659 with first key. This allows session key rotation. Please
660 note that key rotation does not occur automatically. User
661 should rearrange files or change options values and restart
662 nghttpx gracefully. If opening or reading given file fails,
663 all loaded keys are discarded and it is treated as if none of
664 this option is given. If this option is not given or an error
665 occurred while opening or reading a file, key is generated
666 every 1 hour internally and they are valid for 12 hours.
667 This is recommended if ticket key sharing between nghttpx
668 instances is not required.
669 --tls-ticket-key-memcached=<HOST>,<PORT>[;tls]
671 Specify address of memcached server to get TLS ticket keys
672 for session resumption. This enables shared TLS ticket key
673 between multiple nghttpx instances. nghttpx does not set TLS
674 ticket key to memcached. The external ticket key generator is
675 required. nghttpx just gets TLS ticket keys from memcached,
676 and use them, possibly replacing current set of keys. It is
677 up to extern TLS ticket key generator to rotate keys fre‐
678 quently. See "TLS SESSION TICKET RESUMPTION" section in man‐
679 ual page to know the data format in memcached entry. Option‐
680 ally, memcached connection can be encrypted with TLS by
681 specifying "tls" parameter.
682 --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6)
684 Specify address family of memcached connections to get TLS
685 ticket keys. If "auto" is given, both IPv4 and IPv6 are consid‐
686 ered. If "IPv4" is given, only IPv4 address is considered.
687 If "IPv6" is given, only IPv6 address is considered.
688 Default: auto
690 --tls-ticket-key-memcached-interval=<DURATION>
692 Set interval to get TLS ticket keys from memcached.
693 Default: 10m
695 --tls-ticket-key-memcached-max-retry=<N>
697 Set maximum number of consecutive retries before aban‐
698 doning TLS ticket key retrieval. If this number is reached,
699 the attempt is considered as failure, and "failure" count
700 is incremented by 1, which contributed to the
701 value controlled --tls-ticket-key-memcached-max-fail
702 option.
703 Default: 3
705 --tls-ticket-key-memcached-max-fail=<N>
707 Set maximum number of consecutive failure before dis‐
708 abling TLS ticket until next scheduled key retrieval.
709 Default: 2
711 --tls-ticket-key-cipher=<CIPHER>
713 Specify cipher to encrypt TLS session ticket. Specify either
714 aes-128-cbc or aes-256-cbc. By default, aes-128-cbc is
715 used.
716 --tls-ticket-key-memcached-cert-file=<PATH>
718 Path to client certificate for memcached connections to get TLS
719 ticket keys.
720 --tls-ticket-key-memcached-private-key-file=<PATH>
722 Path to client private key for memcached connections to get TLS
723 ticket keys.
724 --fetch-ocsp-response-file=<PATH>
726 Path to fetch-ocsp-response script file. It should be abso‐
727 lute path.
728 Default: /usr/local/share/nghttp2/fetch-ocsp-response
730 --ocsp-update-interval=<DURATION>
732 Set interval to update OCSP response cache.
733 Default: 4h
735 --ocsp-startup
737 Start accepting connections after initial attempts to get
738 OCSP responses finish. It does not matter some of the
739 attempts fail. This feature is useful if OCSP responses
740 must be available before accepting connections.
741 --no-verify-ocsp
743 nghttpx does not verify OCSP response.
744 --no-ocsp
746 Disable OCSP stapling.
747 --tls-session-cache-memcached=<HOST>,<PORT>[;tls]
749 Specify address of memcached server to store session cache.
750 This enables shared session cache between multiple
751 nghttpx instances. Optionally, memcached connection can be
752 encrypted with TLS by specifying "tls" parameter.
753 --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6)
755 Specify address family of memcached connections to store session
756 cache. If "auto" is given, both IPv4 and IPv6 are considered.
757 If "IPv4" is given, only IPv4 address is considered. If "IPv6"
758 is given, only IPv6 address is considered.
759 Default: auto
761 --tls-session-cache-memcached-cert-file=<PATH>
763 Path to client certificate for memcached connections to store
764 session cache.
765 --tls-session-cache-memcached-private-key-file=<PATH>
767 Path to client private key for memcached connections to store
768 session cache.
769 --tls-dyn-rec-warmup-threshold=<SIZE>
771 Specify the threshold size for TLS dynamic record size behav‐
772 iour. During a TLS session, after the threshold number of
773 bytes have been written, the TLS record size will be increased
774 to the maximum allowed (16K). The max record size will con‐
775 tinue to be used on the active TLS session. After
776 --tls-dyn-rec-idle-timeout has elapsed, the record size is
777 reduced to 1300 bytes. Specify 0 to always use the maximum
778 record size, regardless of idle period. This behaviour
779 applies to all TLS based frontends, and TLS HTTP/2 back‐
780 ends.
781 Default: 1M
783 --tls-dyn-rec-idle-timeout=<DURATION>
785 Specify TLS dynamic record size behaviour timeout. See
786 --tls-dyn-rec-warmup-threshold for more information. This
787 behaviour applies to all TLS based frontends, and TLS HTTP/2
788 backends.
789 Default: 1s
791 --no-http2-cipher-black-list
793 Allow black listed cipher suite on frontend HTTP/2 connec‐
794 tion. See
795 https://tools.ietf.org/html/rfc7540#appendix-A for the com‐
796 plete HTTP/2 cipher suites black list.
797 --client-no-http2-cipher-black-list
799 Allow black listed cipher suite on backend HTTP/2 connec‐
800 tion. See
801 https://tools.ietf.org/html/rfc7540#appendix-A for the com‐
802 plete HTTP/2 cipher suites black list.
803 --tls-sct-dir=<DIR>
805 Specifies the directory where *.sct files exist. All *.sct
806 files in <DIR> are read, and sent as extension_data
807 of TLS signed_certificate_timestamp (RFC 6962) to client.
808 These *.sct files are for the certificate specified in
809 positional command-line argument <CERT>, or certificate
810 option in configuration file. For additional certificates,
811 use --subcert option. This option requires OpenSSL >= 1.0.2.
812 --psk-secrets=<PATH>
814 Read list of PSK identity and secrets from <PATH>. This is used
815 for frontend connection. The each line of input file is for‐
816 matted as <identity>:<hex-secret>, where <identity> is PSK
817 identity, and <hex-secret> is secret in hex. An empty line,
818 and line which starts with '#' are skipped. The default
819 enabled cipher list might not contain any PSK cipher suite. In
820 that case, desired PSK cipher suites must be enabled using
821 --ciphers option. The desired PSK cipher suite may be black
822 listed by HTTP/2. To use those cipher suites with
823 HTTP/2, consider to use --no-http2-cipher-black-list option.
824 But be aware its implications.
825 --client-psk-secrets=<PATH>
827 Read PSK identity and secrets from <PATH>. This is used for
828 backend connection. The each line of input file is formatted
829 as <identity>:<hex-secret>, where <identity> is PSK identity,
830 and <hex-secret> is secret in hex. An empty line, and line
831 which starts with '#' are skipped. The first identity and
832 secret pair encountered is used. The default enabled cipher
833 list might not contain any PSK cipher suite. In that case,
834 desired PSK cipher suites must be enabled using
835 --client-ciphers option. The desired PSK cipher suite may be
836 black listed by HTTP/2. To use those cipher suites with
837 HTTP/2, consider to use --client-no-http2-cipher-black-list
838 option. But be aware its implications.
839 --tls-no-postpone-early-data
841 By default, nghttpx postpones forwarding HTTP requests sent in
842 early data, including those sent in partially in it, until TLS
843 handshake finishes. If all backend server recognizes
844 "Early-Data" header field, using this option makes nghttpx not
845 postpone forwarding request and get full potential of 0-RTT
846 data.
847 --tls-max-early-data=<SIZE>
849 Sets the maximum amount of 0-RTT data that server
850 accepts.
851 Default: 16K
853 HTTP/2
855 -c, --frontend-http2-max-concurrent-streams=<N>
856 Set the maximum number of the concurrent streams in one fron‐
857 tend HTTP/2 session.
858 Default: 100
860 --backend-http2-max-concurrent-streams=<N>
862 Set the maximum number of the concurrent streams in one backend
863 HTTP/2 session. This sets maximum number of concurrent
864 opened pushed streams. The maximum number of concurrent
865 requests are set by a remote server.
866 Default: 100
868 --frontend-http2-window-size=<SIZE>
870 Sets the per-stream initial window size of HTTP/2 fron‐
871 tend connection.
872 Default: 65535
874 --frontend-http2-connection-window-size=<SIZE>
876 Sets the per-connection window size of HTTP/2 frontend connec‐
877 tion.
878 Default: 65535
880 --backend-http2-window-size=<SIZE>
882 Sets the initial window size of HTTP/2 backend connec‐
883 tion.
884 Default: 65535
886 --backend-http2-connection-window-size=<SIZE>
888 Sets the per-connection window size of HTTP/2 backend connec‐
889 tion.
890 Default: 2147483647
892 --http2-no-cookie-crumbling
894 Don't crumble cookie header field.
895 --padding=<N>
897 Add at most <N> bytes to a HTTP/2 frame payload as pad‐
898 ding. Specify 0 to disable padding. This option is meant for
899 debugging purpose and not intended to enhance protocol secu‐
900 rity.
901 --no-server-push
903 Disable HTTP/2 server push. Server push is supported by default
904 mode and HTTP/2 frontend via Link header field. It is also
905 supported if both frontend and backend are HTTP/2 in default
906 mode. In this case, server push from backend session is
907 relayed to frontend, and server push via Link header field is
908 also supported.
909 --frontend-http2-optimize-write-buffer-size
911 (Experimental) Enable write buffer size optimization in fron‐
912 tend HTTP/2 TLS connection. This optimization aims to reduce
913 write buffer size so that it only contains bytes which can
914 send immediately. This makes server more responsive to prior‐
915 itized HTTP/2 stream because the buffering of lower priority
916 stream is reduced. This option is only effective on recent
917 Linux platform.
918 --frontend-http2-optimize-window-size
920 (Experimental) Automatically tune connection level window
921 size of frontend HTTP/2 TLS connection. If this feature is
922 enabled, connection window size starts with the default win‐
923 dow size, 65535 bytes. nghttpx automatically adjusts
924 connection window size based on TCP receiving window size.
925 The maximum window size is capped by the value
926 specified by --frontend-http2-connection-window-size.
927 Since the stream is subject to stream level window size, it
928 should be adjusted using --frontend-http2-window-size option as
929 well. This option is only effective on recent Linux plat‐
930 form.
931 --frontend-http2-encoder-dynamic-table-size=<SIZE>
933 Specify the maximum dynamic table size of HPACK encoder in the
934 frontend HTTP/2 connection. The decoder (client) specifies the
935 maximum dynamic table size it accepts. Then the negotiated
936 dynamic table size is the minimum of this option value and the
937 value which client specified.
938 Default: 4K
940 --frontend-http2-decoder-dynamic-table-size=<SIZE>
942 Specify the maximum dynamic table size of HPACK decoder in the
943 frontend HTTP/2 connection.
944 Default: 4K
946 --backend-http2-encoder-dynamic-table-size=<SIZE>
948 Specify the maximum dynamic table size of HPACK encoder in the
949 backend HTTP/2 connection. The decoder (backend) specifies the
950 maximum dynamic table size it accepts. Then the negotiated
951 dynamic table size is the minimum of this option value and the
952 value which backend specified.
953 Default: 4K
955 --backend-http2-decoder-dynamic-table-size=<SIZE>
957 Specify the maximum dynamic table size of HPACK decoder in the
958 backend HTTP/2 connection.
959 Default: 4K
961 Mode
963 (default mode)
964 Accept HTTP/2, and HTTP/1.1 over SSL/TLS. "no-tls" parame‐
965 ter is used in --frontend option, accept HTTP/2 and HTTP/1.1
966 over cleartext TCP. The incoming HTTP/1.1 connection can be
967 upgraded to HTTP/2 through HTTP Upgrade.
968 -s, --http2-proxy
970 Like default mode, but enable forward proxy. This is so called
971 HTTP/2 proxy mode.
972 Logging
974 -L, --log-level=<LEVEL>
975 Set the severity level of log output. <LEVEL> must be one of
976 INFO, NOTICE, WARN, ERROR and FATAL.
977 Default: NOTICE
979 --accesslog-file=<PATH>
981 Set path to write access log. To reopen file, send USR1 signal
982 to nghttpx.
983 --accesslog-syslog
985 Send access log to syslog. If this option is used,
986 --accesslog-file option is ignored.
987 --accesslog-format=<FORMAT>
989 Specify format string for access log. The default format
990 is combined format. The following variables are available:
991 · $remote_addr: client IP address.
993 · $time_local: local time in Common Log format.
995 · $time_iso8601: local time in ISO 8601 format.
997 · $request: HTTP request line.
999 · $status: HTTP response status code.
1001 · $body_bytes_sent: the number of bytes sent to client as
1003 response body.
1004 · $http_<VAR>: value of HTTP request header <VAR> where '_' in
1006 <VAR> is replaced with '-'.
1007 · $remote_port: client port.
1009 · $server_port: server port.
1011 · $request_time: request processing time in seconds with mil‐
1013 liseconds resolution.
1014 · $pid: PID of the running process.
1016 · $alpn: ALPN identifier of the protocol which generates the
1018 response. For HTTP/1, ALPN is always http/1.1, regardless
1019 of minor version.
1020 · $tls_cipher: cipher used for SSL/TLS connection.
1022 · $tls_client_fingerprint_sha256: SHA-256 fingerprint of client
1024 certificate.
1025 · $tls_client_fingerprint_sha1: SHA-1 fingerprint of client
1027 certificate.
1028 · $tls_client_subject_name: subject name in client cer‐
1030 tificate.
1031 · $tls_client_issuer_name: issuer name in client cer‐
1033 tificate.
1034 · $tls_client_serial: serial number in client cer‐
1036 tificate.
1037 · $tls_protocol: protocol for SSL/TLS connection.
1039 · $tls_session_id: session ID for SSL/TLS connection.
1041 · $tls_session_reused: "r" if SSL/TLS session was reused.
1043 Otherwise, "."
1044 · $tls_sni: SNI server name for SSL/TLS connection.
1046 · $backend_host: backend host used to fulfill the
1048 request. "-" if backend host is not available.
1049 · $backend_port: backend port used to fulfill the
1051 request. "-" if backend host is not available.
1052 The variable can be enclosed by "{" and "}" for disam‐
1054 biguation (e.g., ${remote_addr}).
1055 Default: $remote_addr - - [$time_local] "$request" $status
1057 $body_bytes_sent "$http_referer" "$http_user_agent"
1058 --accesslog-write-early
1060 Write access log when response header fields are
1061 received from backend rather than when request trans‐
1062 action finishes.
1063 --errorlog-file=<PATH>
1065 Set path to write error log. To reopen file, send USR1 signal
1066 to nghttpx. stderr will be redirected to the error log file
1067 unless --errorlog-syslog is used.
1068 Default: /dev/stderr
1070 --errorlog-syslog
1072 Send error log to syslog. If this option is used,
1073 --errorlog-file option is ignored.
1074 --syslog-facility=<FACILITY>
1076 Set syslog facility to <FACILITY>.
1077 Default: daemon
1079 HTTP
1081 --add-x-forwarded-for
1082 Append X-Forwarded-For header field to the downstream
1083 request.
1084 --strip-incoming-x-forwarded-for
1086 Strip X-Forwarded-For header field from inbound client
1087 requests.
1088 --no-add-x-forwarded-proto
1090 Don't append additional X-Forwarded-Proto header field to the
1091 backend request. If inbound client sets X-For‐
1092 warded-Proto, and
1093 --no-strip-incoming-x-forwarded-proto option is used, they
1094 are passed to the backend.
1095 --no-strip-incoming-x-forwarded-proto
1097 Don't strip X-Forwarded-Proto header field from inbound client
1098 requests.
1099 --add-forwarded=<LIST>
1101 Append RFC 7239 Forwarded header field with parameters speci‐
1102 fied in comma delimited list <LIST>. The supported parameters
1103 are "by", "for", "host", and "proto". By default, the value
1104 of "by" and "for" parameters are obfuscated string.
1105 See --forwarded-by and --forwarded-for options respec‐
1106 tively. Note that nghttpx does not translate non-standard
1107 X-Forwarded-* header fields into Forwarded header field, and
1108 vice versa.
1109 --strip-incoming-forwarded
1111 Strip Forwarded header field from inbound client
1112 requests.
1113 --forwarded-by=(obfuscated|ip|<VALUE>)
1115 Specify the parameter value sent out with "by" parameter of For‐
1116 warded header field. If "obfuscated" is given, the string is
1117 randomly generated at startup. If "ip" is given, the inter‐
1118 face address of the connection, including port number, is
1119 sent with "by" parameter. In case of UNIX domain socket,
1120 "localhost" is used instead of address and port. User can also
1121 specify the static obfuscated string. The limitation is that it
1122 must start with "_", and only consists of character
1123 set [A-Za-z0-9._-], as described in RFC 7239.
1124 Default: obfuscated
1126 --forwarded-for=(obfuscated|ip)
1128 Specify the parameter value sent out with "for" parame‐
1129 ter of Forwarded header field. If "obfuscated" is given, the
1130 string is randomly generated for each client connection. If
1131 "ip" is given, the remote client address of the connection,
1132 without port number, is sent with "for" parameter. In case
1133 of UNIX domain socket, "localhost" is used instead of
1134 address.
1135 Default: obfuscated
1137 --no-via
1139 Don't append to Via header field. If Via header field is
1140 received, it is left unaltered.
1141 --no-strip-incoming-early-data
1143 Don't strip Early-Data header field from inbound client
1144 requests.
1145 --no-location-rewrite
1147 Don't rewrite location header field in default mode. When
1148 --http2-proxy is used, location header field will not be
1149 altered regardless of this option.
1150 --host-rewrite
1152 Rewrite host and :authority header fields in default mode.
1153 When --http2-proxy is used, these headers will not be altered
1154 regardless of this option.
1155 --altsvc=<PROTOID,PORT[,HOST,[ORIGIN]]>
1157 Specify protocol ID, port, host and origin of alter‐
1158 native service. <HOST> and <ORIGIN> are optional. They are
1159 advertised in alt-svc header field only in HTTP/1.1 fron‐
1160 tend. This option can be used multiple times to specify
1161 multiple alternative services. Example: --altsvc=h2,443
1162 --add-request-header=<HEADER>
1164 Specify additional header field to add to request header set.
1165 This option just appends header field and won't replace any‐
1166 thing already set. This option can be used several times
1167 to specify multiple header fields. Example:
1168 --add-request-header="foo: bar"
1169 --add-response-header=<HEADER>
1171 Specify additional header field to add to response header
1172 set. This option just appends header field and won't replace
1173 anything already set. This option can be used several times
1174 to specify multiple header fields. Example:
1175 --add-response-header="foo: bar"
1176 --request-header-field-buffer=<SIZE>
1178 Set maximum buffer size for incoming HTTP request header field
1179 list. This is the sum of header name and value in bytes. If
1180 trailer fields exist, they are counted towards this number.
1181 Default: 64K
1183 --max-request-header-fields=<N>
1185 Set maximum number of incoming HTTP request header fields.
1186 If trailer fields exist, they are counted towards this num‐
1187 ber.
1188 Default: 100
1190 --response-header-field-buffer=<SIZE>
1192 Set maximum buffer size for incoming HTTP response header
1193 field list. This is the sum of header name and value in
1194 bytes. If trailer fields exist, they are counted towards
1195 this number.
1196 Default: 64K
1198 --max-response-header-fields=<N>
1200 Set maximum number of incoming HTTP response header fields.
1201 If trailer fields exist, they are counted towards this num‐
1202 ber.
1203 Default: 500
1205 --error-page=(<CODE>|*)=<PATH>
1207 Set file path to custom error page served when nghttpx origi‐
1208 nally generates HTTP error status code <CODE>. <CODE> must
1209 be greater than or equal to 400, and at most 599. If "*" is
1210 used instead of <CODE>, it matches all HTTP status code. If
1211 error status code comes from backend server, the custom error
1212 pages are not used.
1213 --server-name=<NAME>
1215 Change server response header field value to <NAME>.
1216 Default: nghttpx
1218 --no-server-rewrite
1220 Don't rewrite server header field in default mode. When
1221 --http2-proxy is used, these headers will not be altered regard‐
1222 less of this option.
1223 --redirect-https-port=<PORT>
1225 Specify the port number which appears in Location header field
1226 when redirect to HTTPS URI is made due to "redi‐
1227 rect-if-not-tls" parameter in --backend option.
1228 Default: 443
1230 API
1232 --api-max-request-body=<SIZE>
1233 Set the maximum size of request body for API request.
1234 Default: 32M
1236 DNS
1238 --dns-cache-timeout=<DURATION>
1239 Set duration that cached DNS results remain valid. Note that
1240 nghttpx caches the unsuccessful results as well.
1241 Default: 10s
1243 --dns-lookup-timeout=<DURATION>
1245 Set timeout that DNS server is given to respond to the initial
1246 DNS query. For the 2nd and later queries, server is given
1247 time based on this timeout, and it is scaled linearly.
1248 Default: 5s
1250 --dns-max-try=<N>
1252 Set the number of DNS query before nghttpx gives up name lookup.
1253 Default: 2
1255 --frontend-max-requests=<N>
1257 The number of requests that single frontend connection can
1258 process. For HTTP/2, this is the number of streams in one
1259 HTTP/2 connection. For HTTP/1, this is the number of keep
1260 alive requests. This is hint to nghttpx, and it may allow
1261 additional few requests. The default value is unlimited.
1262 Debug
1264 --frontend-http2-dump-request-header=<PATH>
1265 Dumps request headers received by HTTP/2 frontend to the file
1266 denoted in <PATH>. The output is done in HTTP/1 header field
1267 format and each header block is followed by an empty line. This
1268 option is not thread safe and MUST NOT be used with option
1269 -n<N>, where <N> >= 2.
1270 --frontend-http2-dump-response-header=<PATH>
1272 Dumps response headers sent from HTTP/2 frontend to the file
1273 denoted in <PATH>. The output is done in HTTP/1 header field
1274 format and each header block is followed by an empty line. This
1275 option is not thread safe and MUST NOT be used with option
1276 -n<N>, where <N> >= 2.
1277 -o, --frontend-frame-debug
1279 Print HTTP/2 frames in frontend to stderr. This option is not
1280 thread safe and MUST NOT be used with option -n=N, where N
1281 >= 2.
1282 Process
1284 -D, --daemon
1285 Run in a background. If -D is used, the current working direc‐
1286 tory is changed to '/'.
1287 --pid-file=<PATH>
1289 Set path to save PID of this program.
1290 --user=<USER>
1292 Run this program as <USER>. This option is intended to be used
1293 to drop root privileges.
1294 --single-process
1296 Run this program in a single process mode for debugging pur‐
1297 pose. Without this option, nghttpx creates at least 2 pro‐
1298 cesses: master and worker processes. If this option is
1299 used, master and worker are unified into a single process.
1300 nghttpx still spawns additional process if neverbleed is used.
1301 In the single process mode, the signal handling feature is dis‐
1302 abled.
1303 Scripting
1305 --mruby-file=<PATH>
1306 Set mruby script file
1307 --ignore-per-pattern-mruby-error
1309 Ignore mruby compile error for per-pattern mruby script file.
1310 If error occurred, it is treated as if no mruby file were
1311 specified for the pattern.
1312 Misc
1314 --conf=<PATH>
1315 Load configuration from <PATH>. Please note that nghttpx
1316 always tries to read the default configuration file if --conf
1317 is not given.
1318 Default: /etc/nghttpx/nghttpx.conf
1320 --include=<PATH>
1322 Load additional configurations from <PATH>. File <PATH> is
1323 read when configuration parser encountered this option.
1324 This option can be used multiple times, or even recursively.
1325 -v, --version
1327 Print version and exit.
1328 -h, --help
1330 Print this help and exit.
1331 The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
1333 * 1024). Units are K, M and G (powers of 1024).
1334 The <DURATION> argument is an integer and an optional unit (e.g., 1s is
1336 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
1337 (hours, minutes, seconds and milliseconds, respectively). If a unit is
1338 omitted, a second is used as unit.
1339
1341 /etc/nghttpx/nghttpx.conf
1342 The default configuration file path nghttpx searches at startup.
1343 The configuration file path can be changed using --conf option.
1344 Those lines which are staring # are treated as comment.
1346 The option name in the configuration file is the long com‐
1348 mand-line option name with leading -- stripped (e.g., frontend).
1349 Put = between option name and value. Don't put extra leading or
1350 trailing spaces.
1351 When specifying arguments including characters which have spe‐
1353 cial meaning to a shell, we usually use quotes so that shell
1354 does not interpret them. When writing this configuration file,
1355 quotes for this purpose must not be used. For example, specify
1356 additional request header field, do this:
1357 add-request-header=foo: bar
1359 instead of:
1361 add-request-header="foo: bar"
1363 The options which do not take argument in the command-line take
1365 argument in the configuration file. Specify yes as an argument
1366 (e.g., http2-proxy=yes). If other string is given, it is
1367 ignored.
1368 To specify private key and certificate file which are given as
1370 positional arguments in command-line, use private-key-file and
1371 certificate-file.
1372 --conf option cannot be used in the configuration file and will
1374 be ignored if specified.
1375 Error log
1377 Error log is written to stderr by default. It can be configured
1378 using --errorlog-file. The format of log message is as follows:
1379 <datetime> <master-pid> <current-pid> <thread-id> <level>
1381 (<filename>:<line>) <msg>
1382 <datetime>
1384 It is a combination of date and time when the log is
1385 written. It is in ISO 8601 format.
1386 <master-pid>
1388 It is a master process ID.
1389 <current-pid>
1391 It is a process ID which writes this log.
1392 <thread-id>
1394 It is a thread ID which writes this log. It would be
1395 unique within <current-pid>.
1396 <filename> and <line>
1398 They are source file name, and line number which produce
1399 this log.
1400 <msg> It is a log message body.
1402
1404 SIGQUIT
1405 Shutdown gracefully. First accept pending connections and stop
1406 accepting connection. After all connections are handled,
1407 nghttpx exits.
1408 SIGHUP Reload configuration file given in --conf.
1410 SIGUSR1
1412 Reopen log files.
1413 SIGUSR2
1415 Fork and execute nghttpx. It will execute the binary in the same
1416 path with same command-line arguments and environment variables. As
1417 of nghttpx version 1.20.0, the new master process sends SIGQUIT to
1418 the original master process when it is ready to serve requests. For
1419 the earlier versions of nghttpx, user has to send SIGQUIT to the
1420 original master process.
1421 The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
1423 is usually used to execute new binary, and the master process is
1424 newly spawned. On the other hand, the latter just reloads configu‐
1425 ration file, and the same master process continues to exist.
1426 NOTE:
1428 nghttpx consists of multiple processes: one process for processing
1429 these signals, and another one for processing requests. The former
1430 spawns the latter. The former is called master process, and the
1431 latter is called worker process. If neverbleed is enabled, the
1432 worker process spawns neverbleed daemon process which does RSA key
1433 processing. The above signal must be sent to the master process.
1434 If the other processes received one of them, it is ignored. This
1435 behaviour of these processes may change in the future release. In
1436 other words, in the future release, the processes other than master
1437 process may terminate upon the reception of these signals. There‐
1438 fore these signals should not be sent to the processes other than
1439 master process.
1440
1442 nghttpx supports HTTP/2 server push in default mode with Link header
1443 field. nghttpx looks for Link header field (RFC 5988) in response
1444 headers from backend server and extracts URI-reference with parameter
1445 rel=preload (see preload) and pushes those URIs to the frontend client.
1446 Here is a sample Link header field to initiate server push:
1447 Link: </fonts/font.woff>; rel=preload
1449 Link: </css/theme.css>; rel=preload
1450 Currently, the following restriction is applied for server push:
1452 1. The associated stream must have method "GET" or "POST". The associ‐
1454 ated stream's status code must be 200.
1455 This limitation may be loosened in the future release.
1457 nghttpx also supports server push if both frontend and backend are
1459 HTTP/2 in default mode. In this case, in addition to server push via
1460 Link header field, server push from backend is forwarded to frontend
1461 HTTP/2 session.
1462 HTTP/2 server push will be disabled if --http2-proxy is used.
1464
1466 nghttpx supports UNIX domain socket with a filename for both frontend
1467 and backend connections.
1468 Please note that current nghttpx implementation does not delete a
1470 socket with a filename. And on start up, if nghttpx detects that the
1471 specified socket already exists in the file system, nghttpx first
1472 deletes it. However, if SIGUSR2 is used to execute new binary and both
1473 old and new configurations use same filename, new binary does not
1474 delete the socket and continues to use it.
1475
1477 OCSP query is done using external Python script fetch-ocsp-response,
1478 which has been originally developed in Perl as part of h2o project (‐
1479 https://github.com/h2o/h2o), and was translated into Python.
1480 The script file is usually installed under $(prefix)/share/nghttp2/
1482 directory. The actual path to script can be customized using
1483 --fetch-ocsp-response-file option.
1484 If OCSP query is failed, previous OCSP response, if any, is continued
1486 to be used.
1487 --fetch-ocsp-response-file option provides wide range of possibility to
1489 manage OCSP response. It can take an arbitrary script or executable.
1490 The requirement is that it supports the command-line interface of
1491 fetch-ocsp-response script, and it must return a valid DER encoded OCSP
1492 response on success. It must return exit code 0 on success, and 75 for
1493 temporary error, and the other error code for generic failure. For
1494 large cluster of servers, it is not efficient for each server to per‐
1495 form OCSP query using fetch-ocsp-response. Instead, you can retrieve
1496 OCSP response in some way, and store it in a disk or a shared database.
1497 Then specify a program in --fetch-ocsp-response-file to fetch it from
1498 those stores. This could provide a way to share the OCSP response
1499 between fleet of servers, and also any OCSP query strategy can be
1500 applied which may be beyond the ability of nghttpx itself or
1501 fetch-ocsp-response script.
1502
1504 nghttpx supports TLS session resumption through both session ID and
1505 session ticket.
1506 SESSION ID RESUMPTION
1508 By default, session ID is shared by all worker threads.
1509 If --tls-session-cache-memcached is given, nghttpx will insert serial‐
1511 ized session data to memcached with nghttpx:tls-session-cache: + lower‐
1512 case hex string of session ID as a memcached entry key, with expiry
1513 time 12 hours. Session timeout is set to 12 hours.
1514 By default, connections to memcached server are not encrypted. To
1516 enable encryption, use tls keyword in --tls-session-cache-memcached
1517 option.
1518 TLS SESSION TICKET RESUMPTION
1520 By default, session ticket is shared by all worker threads. The auto‐
1521 matic key rotation is also enabled by default. Every an hour, new
1522 encryption key is generated, and previous encryption key becomes
1523 decryption only key. We set session timeout to 12 hours, and thus we
1524 keep at most 12 keys.
1525 If --tls-ticket-key-memcached is given, encryption keys are retrieved
1527 from memcached. nghttpx just reads keys from memcached; one has to
1528 deploy key generator program to update keys frequently (e.g., every 1
1529 hour). The example key generator tlsticketupdate.go is available under
1530 contrib directory in nghttp2 archive. The memcached entry key is
1531 nghttpx:tls-ticket-key. The data format stored in memcached is the
1532 binary format described below:
1533 +--------------+-------+----------------+
1535 | VERSION (4) |LEN (2)|KEY(48 or 80) ...
1536 +--------------+-------+----------------+
1537 ^ |
1538 | |
1539 +------------------------+
1540 (LEN, KEY) pair can be repeated
1541 All numbers in the above figure is bytes. All integer fields are net‐
1543 work byte order.
1544 First 4 bytes integer VERSION field, which must be 1. The 2 bytes
1546 integer LEN field gives the length of following KEY field, which con‐
1547 tains key. If --tls-ticket-key-cipher=aes-128-cbc is used, LEN must be
1548 48. If --tls-ticket-key-cipher=aes-256-cbc is used, LEN must be 80.
1549 LEN and KEY pair can be repeated multiple times to store multiple keys.
1550 The key appeared first is used as encryption key. All the remaining
1551 keys are used as decryption only.
1552 By default, connections to memcached server are not encrypted. To
1554 enable encryption, use tls keyword in --tls-ticket-key-memcached
1555 option.
1556 If --tls-ticket-key-file is given, encryption key is read from the
1558 given file. In this case, nghttpx does not rotate key automatically.
1559 To rotate key, one has to restart nghttpx (see SIGNALS).
1560
1562 nghttpx supports TLS signed_certificate_timestamp extension (RFC 6962).
1563 The relevant options are --tls-sct-dir and sct-dir parameter in
1564 --subcert. They takes a directory, and nghttpx reads all files whose
1565 extension is .sct under the directory. The *.sct files are encoded as
1566 SignedCertificateTimestamp struct described in section 3.2 of RFC
1567 69662. This format is the same one used by nginx-ct and mod_ssl_ct.
1568 ct-submit can be used to submit certificates to log servers, and obtain
1569 the SignedCertificateTimestamp struct which can be used with nghttpx.
1570
1572 WARNING:
1573 The current mruby extension API is experimental and not frozen. The
1574 API is subject to change in the future release.
1575 WARNING:
1577 Almost all string value returned from method, or attribute is a
1578 fresh new mruby string, which involves memory allocation, and
1579 copies. Therefore, it is strongly recommended to store a return
1580 value in a local variable, and use it, instead of calling method or
1581 accessing attribute repeatedly.
1582 nghttpx allows users to extend its capability using mruby scripts.
1584 nghttpx has 2 hook points to execute mruby script: request phase and
1585 response phase. The request phase hook is invoked after all request
1586 header fields are received from client. The response phase hook is
1587 invoked after all response header fields are received from backend
1588 server. These hooks allows users to modify header fields, or common
1589 HTTP variables, like authority or request path, and even return custom
1590 response without forwarding request to backend servers.
1591 There are 2 levels of mruby script invocations: global and per-pattern.
1593 The global mruby script is set by --mruby-file option and is called for
1594 all requests. The per-pattern mruby script is set by "mruby" parameter
1595 in -b option. It is invoked for a request which matches the particular
1596 pattern. The order of hook invocation is: global request phase hook,
1597 per-pattern request phase hook, per-pattern response phase hook, and
1598 finally global response phase hook. If a hook returns a response, any
1599 later hooks are not invoked. The global request hook is invoked before
1600 the pattern matching is made and changing request path may affect the
1601 pattern matching.
1602 Please note that request and response hooks of per-pattern mruby script
1604 for a single request might not come from the same script. This might
1605 happen after a request hook is executed, backend failed for some rea‐
1606 son, and at the same time, backend configuration is replaced by API
1607 request, and then the request uses new configuration on retry. The
1608 response hook from new configuration, if it is specified, will be
1609 invoked.
1610 The all mruby script will be evaluated once per thread on startup, and
1612 it must instantiate object and evaluate it as the return value (e.g.,
1613 App.new). This object is called app object. If app object defines
1614 on_req method, it is called with Nghttpx::Env object on request hook.
1615 Similarly, if app object defines on_resp method, it is called with
1616 Nghttpx::Env object on response hook. For each method invocation, user
1617 can can access Nghttpx::Request and Nghttpx::Response objects via
1618 Nghttpx::Env#req and Nghttpx::Env#resp respectively.
1619 Nghttpx::REQUEST_PHASE
1621 Constant to represent request phase.
1622 Nghttpx::RESPONSE_PHASE
1624 Constant to represent response phase.
1625 class Nghttpx::Env
1627 Object to represent current request specific context.
1628 attribute [R] req
1630 Return Request object.
1631 attribute [R] resp
1633 Return Response object.
1634 attribute [R] ctx
1636 Return Ruby hash object. It persists until request fin‐
1637 ishes. So values set in request phase hook can be
1638 retrieved in response phase hook.
1639 attribute [R] phase
1641 Return the current phase.
1642 attribute [R] remote_addr
1644 Return IP address of a remote client. If connection is
1645 made via UNIX domain socket, this returns the string
1646 "localhost".
1647 attribute [R] server_addr
1649 Return address of server that accepted the connection.
1650 This is a string which specified in --frontend option,
1651 excluding port number, and not a resolved IP address.
1652 For UNIX domain socket, this is a path to UNIX domain
1653 socket.
1654 attribute [R] server_port
1656 Return port number of the server frontend which accepted
1657 the connection from client.
1658 attribute [R] tls_used
1660 Return true if TLS is used on the connection.
1661 attribute [R] tls_sni
1663 Return the TLS SNI value which client sent in this con‐
1664 nection.
1665 attribute [R] tls_client_fingerprint_sha256
1667 Return the SHA-256 fingerprint of a client certificate.
1668 attribute [R] tls_client_fingerprint_sha1
1670 Return the SHA-1 fingerprint of a client certificate.
1671 attribute [R] tls_client_issuer_name
1673 Return the issuer name of a client certificate.
1674 attribute [R] tls_client_subject_name
1676 Return the subject name of a client certificate.
1677 attribute [R] tls_client_serial
1679 Return the serial number of a client certificate.
1680 attribute [R] tls_client_not_before
1682 Return the start date of a client certificate in seconds
1683 since the epoch.
1684 attribute [R] tls_client_not_after
1686 Return the end date of a client certificate in seconds
1687 since the epoch.
1688 attribute [R] tls_cipher
1690 Return a TLS cipher negotiated in this connection.
1691 attribute [R] tls_protocol
1693 Return a TLS protocol version negotiated in this connec‐
1694 tion.
1695 attribute [R] tls_session_id
1697 Return a session ID for this connection in hex string.
1698 attribute [R] tls_session_reused
1700 Return true if, and only if a SSL/TLS session is reused.
1701 attribute [R] alpn
1703 Return ALPN identifier negotiated in this connection.
1704 attribute [R] tls_handshake_finished
1706 Return true if SSL/TLS handshake has finished. If it
1707 returns false in the request phase hook, the request is
1708 received in TLSv1.3 early data (0-RTT) and might be vul‐
1709 nerable to the replay attack. nghttpx will send
1710 Early-Data header field to backend servers to indicate
1711 this.
1712 class Nghttpx::Request
1714 Object to represent request from client. The modification to
1715 Request object is allowed only in request phase hook.
1716 attribute [R] http_version_major
1718 Return HTTP major version.
1719 attribute [R] http_version_minor
1721 Return HTTP minor version.
1722 attribute [R/W] method
1724 HTTP method. On assignment, copy of given value is
1725 assigned. We don't accept arbitrary method name. We
1726 will document them later, but well known methods, like
1727 GET, PUT and POST, are all supported.
1728 attribute [R/W] authority
1730 Authority (i.e., example.org), including optional port
1731 component . On assignment, copy of given value is
1732 assigned.
1733 attribute [R/W] scheme
1735 Scheme (i.e., http, https). On assignment, copy of given
1736 value is assigned.
1737 attribute [R/W] path
1739 Request path, including query component (i.e.,
1740 /index.html). On assignment, copy of given value is
1741 assigned. The path does not include authority component
1742 of URI. This may include query component. nghttpx makes
1743 certain normalization for path. It decodes per‐
1744 cent-encoding for unreserved characters (see
1745 https://tools.ietf.org/html/rfc3986#section-2.3), and
1746 resolves ".." and ".". But it may leave characters which
1747 should be percent-encoded as is. So be careful when com‐
1748 paring path against desired string.
1749 attribute [R] headers
1751 Return Ruby hash containing copy of request header
1752 fields. Changing values in returned hash does not change
1753 request header fields actually used in request process‐
1754 ing. Use Nghttpx::Request#add_header or
1755 Nghttpx::Request#set_header to change request header
1756 fields.
1757 add_header(key, value)
1759 Add header entry associated with key. The value can be
1760 single string or array of string. It does not replace
1761 any existing values associated with key.
1762 set_header(key, value)
1764 Set header entry associated with key. The value can be
1765 single string or array of string. It replaces any exist‐
1766 ing values associated with key.
1767 clear_headers()
1769 Clear all existing request header fields.
1770 push(uri)
1772 Initiate to push resource identified by uri. Only HTTP/2
1773 protocol supports this feature. For the other protocols,
1774 this method is noop. uri can be absolute URI, absolute
1775 path or relative path to the current request. For abso‐
1776 lute or relative path, scheme and authority are inherited
1777 from the current request. Currently, method is always
1778 GET. nghttpx will issue request to backend servers to
1779 fulfill this request. The request and response phase
1780 hooks will be called for pushed resource as well.
1781 class Nghttpx::Response
1783 Object to represent response from backend server.
1784 attribute [R] http_version_major
1786 Return HTTP major version.
1787 attribute [R] http_version_minor
1789 Return HTTP minor version.
1790 attribute [R/W] status
1792 HTTP status code. It must be in the range [200, 999],
1793 inclusive. The non-final status code is not supported in
1794 mruby scripting at the moment.
1795 attribute [R] headers
1797 Return Ruby hash containing copy of response header
1798 fields. Changing values in returned hash does not change
1799 response header fields actually used in response process‐
1800 ing. Use Nghttpx::Response#add_header or
1801 Nghttpx::Response#set_header to change response header
1802 fields.
1803 add_header(key, value)
1805 Add header entry associated with key. The value can be
1806 single string or array of string. It does not replace
1807 any existing values associated with key.
1808 set_header(key, value)
1810 Set header entry associated with key. The value can be
1811 single string or array of string. It replaces any exist‐
1812 ing values associated with key.
1813 clear_headers()
1815 Clear all existing response header fields.
1816 return(body)
1818 Return custom response body to a client. When this
1819 method is called in request phase hook, the request is
1820 not forwarded to the backend, and response phase hook for
1821 this request will not be invoked. When this method is
1822 called in response phase hook, response from backend
1823 server is canceled and discarded. The status code and
1824 response header fields should be set before using this
1825 method. To set status code, use
1826 Nghttpx::Response#status. If status code is not set, 200
1827 is used. To set response header fields,
1828 Nghttpx::Response#add_header and
1829 Nghttpx::Response#set_header. When this method is
1830 invoked in response phase hook, the response headers are
1831 filled with the ones received from backend server. To
1832 send completely custom header fields, first call
1833 Nghttpx::Response#clear_headers to erase all existing
1834 header fields, and then add required header fields. It
1835 is an error to call this method twice for a given
1836 request.
1837 send_info(status, headers)
1839 Send non-final (informational) response to a client.
1840 status must be in the range [100, 199], inclusive. head‐
1841 ers is a hash containing response header fields. Its key
1842 must be a string, and the associated value must be either
1843 string or array of strings. Since this is not a final
1844 response, even if this method is invoked, request is
1845 still forwarded to a backend unless
1846 Nghttpx::Response#return is called. This method can be
1847 called multiple times. It cannot be called after
1848 Nghttpx::Response#return is called.
1849 MRUBY EXAMPLES
1851 Modify request path:
1852 class App
1854 def on_req(env)
1855 env.req.path = "/apps#{env.req.path}"
1856 end
1857 end
1858 App.new
1860 Don't forget to instantiate and evaluate object at the last line.
1862 Restrict permission of viewing a content to a specific client
1864 addresses:
1865 class App
1867 def on_req(env)
1868 allowed_clients = ["127.0.0.1", "::1"]
1869 if env.req.path.start_with?("/log/") &&
1871 !allowed_clients.include?(env.remote_addr) then
1872 env.resp.status = 404
1873 env.resp.return "permission denied"
1874 end
1875 end
1876 end
1877 App.new
1879
1881 nghttpx exposes API endpoints to manipulate it via HTTP based API. By
1882 default, API endpoint is disabled. To enable it, add a dedicated fron‐
1883 tend for API using --frontend option with "api" parameter. All
1884 requests which come from this frontend address, will be treated as API
1885 request.
1886 The response is normally JSON dictionary, and at least includes the
1888 following keys:
1889 status The status of the request processing. The following values are
1891 defined:
1892 Success
1894 The request was successful.
1895 Failure
1897 The request was failed. No change has been made.
1898 code HTTP status code
1900 Additionally, depending on the API endpoint, data key may be present,
1902 and its value contains the API endpoint specific data.
1903 We wrote "normally", since nghttpx may return ordinal HTML response in
1905 some cases where the error has occurred before reaching API endpoint
1906 (e.g., header field is too large).
1907 The following section describes available API endpoints.
1909 POST /api/v1beta1/backendconfig
1911 This API replaces the current backend server settings with the
1912 requested ones. The request method should be POST, but PUT is also
1913 acceptable. The request body must be nghttpx configuration file for‐
1914 mat. For configuration file format, see FILES section. The line sepa‐
1915 rator inside the request body must be single LF (0x0A). Currently,
1916 only backend option is parsed, the others are simply ignored. The
1917 semantics of this API is replace the current backend with the backend
1918 options in request body. Describe the desired set of backend severs,
1919 and nghttpx makes it happen. If there is no backend option is found in
1920 request body, the current set of backend is replaced with the backend
1921 option's default value, which is 127.0.0.1,80.
1922 The replacement is done instantly without breaking existing connections
1924 or requests. It also avoids any process creation as is the case with
1925 hot swapping with signals.
1926 The one limitation is that only numeric IP address is allowed in
1928 backend in request body unless "dns" parameter is used while non
1929 numeric hostname is allowed in command-line or configuration file is
1930 read using --conf.
1931 GET /api/v1beta1/configrevision
1933 This API returns configuration revision of the current nghttpx. The
1934 configuration revision is opaque string, and it changes after each
1935 reloading by SIGHUP. With this API, an external application knows that
1936 whether nghttpx has finished reloading its configuration by comparing
1937 the configuration revisions between before and after reloading. It is
1938 recommended to disable persistent (keep-alive) connection for this pur‐
1939 pose in order to avoid to send a request using the reused connection
1940 which may bound to an old process.
1941 This API returns response including data key. Its value is JSON
1943 object, and it contains at least the following key:
1944 configRevision
1946 The configuration revision of the current nghttpx
1947
1949 nghttp(1), nghttpd(1), h2load(1)
1950
1952 Tatsuhiro Tsujikawa
1953
1955 2012, 2015, 2016, Tatsuhiro Tsujikawa
19561.38.0 Apr 18, 2019 NGHTTPX(1)