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>",
107 and "write-timeout=<DURATION>". The parameter consists of
108 keyword, and optionally followed by "=" and value. For exam‐
109 ple, the parameter "proto=h2" consists of the keyword
110 "proto" and value "h2". The parameter "tls" consists of
111 the keyword "tls" without value. Each parameter is
112 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 Since ";" and ":" are used as delimiter, <PATTERN> must not
213 contain these characters. Since ";" has special meaning in
214 shell, the option value must be quoted.
215 Default: 127.0.0.1,80
217 -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]
219 Set frontend host and port. If <HOST> is '*', it assumes
220 all addresses including both IPv4 and IPv6. UNIX domain
221 socket can be specified by prefixing path name with "unix:"
222 (e.g., unix:/var/run/nghttpx.sock). This option can be used
223 multiple times to listen to multiple addresses.
224 This option can take 0 or more parameters, which are
226 described below. Note that "api" and "healthmon" parame‐
227 ters are mutually exclusive.
228 Optionally, TLS can be disabled by specifying "no-tls" parame‐
230 ter. TLS is enabled by default.
231 If "sni-fwd" parameter is used, when performing a match to
233 select a backend server, SNI host name received from the client
234 is used instead of the request host. See --backend option
235 about the pattern match.
236 To make this frontend as API endpoint, specify "api" parame‐
238 ter. This is disabled by default. It is important to
239 limit the access to the API frontend. Otherwise, someone
240 may change the backend server, and break your services, or
241 expose confidential information to the outside the world.
242 To make this frontend as health monitor endpoint, specify
244 "healthmon" parameter. This is disabled by default. Any
245 requests which come through this address are replied with 200
246 HTTP status, without no body.
247 To accept PROXY protocol version 1 on frontend connec‐
249 tion, specify "proxyproto" parameter. This is disabled by
250 default.
251 Default: *,3000
253 --backlog=<N>
255 Set listen backlog size.
256 Default: 65536
258 --backend-address-family=(auto|IPv4|IPv6)
260 Specify address family of backend connections. If "auto"
261 is given, both IPv4 and IPv6 are considered. If "IPv4" is
262 given, only IPv4 address is considered. If "IPv6" is given,
263 only IPv6 address is considered.
264 Default: auto
266 --backend-http-proxy-uri=<URI>
268 Specify proxy URI in the form
269 http://[<USER>:<PASS>@]<PROXY>:<PORT>. If a proxy
270 requires authentication, specify <USER> and <PASS>. Note
271 that they must be properly percent-encoded. This proxy is
272 used when the backend connection is HTTP/2. First, make a
273 CONNECT request to the proxy and it connects to the back‐
274 end on behalf of nghttpx. This forms tunnel. After that,
275 nghttpx performs SSL/TLS handshake with the downstream
276 through the tunnel. The timeouts when connecting and making
277 CONNECT request can be specified by
278 --backend-read-timeout and --backend-write-timeout options.
279 Performance
281 -n, --workers=<N>
282 Set the number of worker threads.
283 Default: 1
285 --single-thread
287 Run everything in one thread inside the worker process. This
288 feature is provided for better debugging experience,
289 or for the platforms which lack thread support. If
290 threading is disabled, this option is always enabled.
291 --read-rate=<SIZE>
293 Set maximum average read rate on frontend connection. Set‐
294 ting 0 to this option means read rate is unlimited.
295 Default: 0
297 --read-burst=<SIZE>
299 Set maximum read burst size on frontend connection. Set‐
300 ting 0 to this option means read burst size is unlimited.
301 Default: 0
303 --write-rate=<SIZE>
305 Set maximum average write rate on frontend connection. Set‐
306 ting 0 to this option means write rate is unlimited.
307 Default: 0
309 --write-burst=<SIZE>
311 Set maximum write burst size on frontend connection. Set‐
312 ting 0 to this option means write burst size is unlimited.
313 Default: 0
315 --worker-read-rate=<SIZE>
317 Set maximum average read rate on frontend connection per worker.
318 Setting 0 to this option means read rate is unlimited. Not
319 implemented yet.
320 Default: 0
322 --worker-read-burst=<SIZE>
324 Set maximum read burst size on frontend connection per worker.
325 Setting 0 to this option means read burst size is unlimited.
326 Not implemented yet.
327 Default: 0
329 --worker-write-rate=<SIZE>
331 Set maximum average write rate on frontend connection per
332 worker. Setting 0 to this option means write rate is unlim‐
333 ited. Not implemented yet.
334 Default: 0
336 --worker-write-burst=<SIZE>
338 Set maximum write burst size on frontend connection per worker.
339 Setting 0 to this option means write burst size is unlimited.
340 Not implemented yet.
341 Default: 0
343 --worker-frontend-connections=<N>
345 Set maximum number of simultaneous connections frontend
346 accepts. Setting 0 means unlimited.
347 Default: 0
349 --backend-connections-per-host=<N>
351 Set maximum number of backend concurrent connections (and/or
352 streams in case of HTTP/2) per origin host. This option is
353 meaningful when --http2-proxy option is used. The origin
354 host is determined by authority portion of request URI (or
355 :authority header field for HTTP/2). To limit the number
356 of connections per frontend for default
357 mode, use --backend-connections-per-frontend.
358 Default: 8
360 --backend-connections-per-frontend=<N>
362 Set maximum number of backend concurrent connections (and/or
363 streams in case of HTTP/2) per frontend. This option is
364 only used for default mode. 0 means unlimited. To limit
365 the number of connections per host with --http2-proxy
366 option, use --backend-connections-per-host.
367 Default: 0
369 --rlimit-nofile=<N>
371 Set maximum number of open files (RLIMIT_NOFILE) to <N>. If 0
372 is given, nghttpx does not set the limit.
373 Default: 0
375 --backend-request-buffer=<SIZE>
377 Set buffer size used to store backend request.
378 Default: 16K
380 --backend-response-buffer=<SIZE>
382 Set buffer size used to store backend response.
383 Default: 128K
385 --fastopen=<N>
387 Enables "TCP Fast Open" for the listening socket and limits
388 the maximum length for the queue of connections that have not
389 yet completed the three-way handshake. If value is 0 then fast
390 open is disabled.
391 Default: 0
393 --no-kqueue
395 Don't use kqueue. This option is only applicable for the
396 platforms which have kqueue. For other platforms, this option
397 will be simply ignored.
398 Timeout
400 --frontend-http2-read-timeout=<DURATION>
401 Specify read timeout for HTTP/2 frontend connection.
402 Default: 3m
404 --frontend-read-timeout=<DURATION>
406 Specify read timeout for HTTP/1.1 frontend connection.
407 Default: 1m
409 --frontend-write-timeout=<DURATION>
411 Specify write timeout for all frontend connections.
412 Default: 30s
414 --frontend-keep-alive-timeout=<DURATION>
416 Specify keep-alive timeout for frontend HTTP/1 connec‐
417 tion.
418 Default: 1m
420 --stream-read-timeout=<DURATION>
422 Specify read timeout for HTTP/2 streams. 0 means no time‐
423 out.
424 Default: 0
426 --stream-write-timeout=<DURATION>
428 Specify write timeout for HTTP/2 streams. 0 means no time‐
429 out.
430 Default: 1m
432 --backend-read-timeout=<DURATION>
434 Specify read timeout for backend connection.
435 Default: 1m
437 --backend-write-timeout=<DURATION>
439 Specify write timeout for backend connection.
440 Default: 30s
442 --backend-connect-timeout=<DURATION>
444 Specify timeout before establishing TCP connection to back‐
445 end.
446 Default: 30s
448 --backend-keep-alive-timeout=<DURATION>
450 Specify keep-alive timeout for backend HTTP/1 connec‐
451 tion.
452 Default: 2s
454 --listener-disable-timeout=<DURATION>
456 After accepting connection failed, connection listener is dis‐
457 abled for a given amount of time. Specifying 0 disables this
458 feature.
459 Default: 30s
461 --frontend-http2-setting-timeout=<DURATION>
463 Specify timeout before SETTINGS ACK is received from client.
464 Default: 10s
466 --backend-http2-settings-timeout=<DURATION>
468 Specify timeout before SETTINGS ACK is received from backend
469 server.
470 Default: 10s
472 --backend-max-backoff=<DURATION>
474 Specify maximum backoff interval. This is used when doing
475 health check against offline backend (see "fail" parameter in
476 --backend option). It is also used to limit the maximum
477 interval to temporarily disable backend when nghttpx failed
478 to connect to it. These intervals are calculated using expo‐
479 nential backoff, and consecutive failed attempts increase the
480 interval. This option caps its maximum value.
481 Default: 2m
483 SSL/TLS
485 --ciphers=<SUITE>
486 Set allowed cipher list for frontend connection. The format
487 of the string is described in OpenSSL ciphers(1). This option
488 sets cipher suites for TLSv1.2 or earlier. Use --tls13-ciphers
489 for TLSv1.3.
490 Default:
492 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
493 --tls13-ciphers=<SUITE>
495 Set allowed cipher list for frontend connection. The format
496 of the string is described in OpenSSL ciphers(1). This option
497 sets cipher suites for TLSv1.3. Use --ciphers for TLSv1.2
498 or earlier.
499 Default:
501 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
502 --client-ciphers=<SUITE>
504 Set allowed cipher list for backend connection. The format
505 of the string is described in OpenSSL ciphers(1). This option
506 sets cipher suites for TLSv1.2 or earlier. Use
507 --tls13-client-ciphers for TLSv1.3.
508 Default:
510 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
511 --tls13-client-ciphers=<SUITE>
513 Set allowed cipher list for backend connection. The format
514 of the string is described in OpenSSL ciphers(1). This option
515 sets cipher suites for TLSv1.3. Use
516 --tls13-client-ciphers for TLSv1.2 or earlier.
517 Default:
519 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
520 --ecdh-curves=<LIST>
522 Set supported curve list for frontend connections. <LIST>
523 is a colon separated list of curve NID or names in the prefer‐
524 ence order. The supported curves depend on the linked OpenSSL
525 library. This function requires OpenSSL >= 1.0.2.
526 Default: X25519:P-256:P-384:P-521
528 -k, --insecure
530 Don't verify backend server's certificate if TLS is enabled
531 for backend connections.
532 --cacert=<PATH>
534 Set path to trusted CA certificate file. It is used in backend
535 TLS connections to verify peer's certificate. It is also used
536 to verify OCSP response from the script set by
537 --fetch-ocsp-response-file. The file must be in PEM format.
538 It can contain multiple certificates. If the linked OpenSSL
539 is configured to load system wide certificates, they are
540 loaded at startup regardless of this option.
541 --private-key-passwd-file=<PATH>
543 Path to file that contains password for the server's private
544 key. If none is given and the private key is password pro‐
545 tected it'll be requested interactively.
546 --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
548 Specify additional certificate and private key file.
549 nghttpx will choose certificates based on the hostname indi‐
550 cated by client using TLS SNI extension. If nghttpx is built
551 with OpenSSL >= 1.0.2, the shared elliptic curves (e.g.,
552 P-256) between client and server are also taken into consider‐
553 ation. This allows nghttpx to send ECDSA certificate to mod‐
554 ern clients, while sending RSA based certificate to older
555 clients. This option can be used multiple times. To make
556 OCSP stapling work, <CERTPATH> must be absolute path.
557 Additional parameter can be specified in <PARAM>. The avail‐
559 able <PARAM> is "sct-dir=<DIR>".
560 "sct-dir=<DIR>" specifies the path to directory which con‐
562 tains *.sct files for TLS
563 signed_certificate_timestamp extension (RFC 6962). This feature
564 requires OpenSSL >= 1.0.2. See also --tls-sct-dir
565 option.
566 --dh-param-file=<PATH>
568 Path to file that contains DH parameters in PEM format. With‐
569 out this option, DHE cipher suites are not available.
570 --npn-list=<LIST>
572 Comma delimited list of ALPN protocol identifier sorted in the
573 order of preference. That means most desirable protocol comes
574 first. This is used in both ALPN and NPN. The parameter
575 must be delimited by a single comma only and any white spaces
576 are treated as a part of protocol string.
577 Default: h2,h2-16,h2-14,http/1.1
579 --verify-client
581 Require and verify client certificate.
582 --verify-client-cacert=<PATH>
584 Path to file that contains CA certificates to verify client
585 certificate. The file must be in PEM format. It can contain
586 multiple certificates.
587 --verify-client-tolerate-expired
589 Accept expired client certificate. Operator should handle
590 the expired client certificate by some means (e.g., mruby
591 script). Otherwise, this option might cause a security risk.
592 --client-private-key-file=<PATH>
594 Path to file that contains client private key used in backend
595 client authentication.
596 --client-cert-file=<PATH>
598 Path to file that contains client certificate used in backend
599 client authentication.
600 --tls-min-proto-version=<VER>
602 Specify minimum SSL/TLS protocol. The name matching is done in
603 case-insensitive manner. The versions between
604 --tls-min-proto-version and --tls-max-proto-version are
605 enabled. If the protocol list advertised by client does not
606 overlap this range, you will receive the error message
607 "unknown protocol". If a protocol version lower than TLSv1.2 is
608 specified, make sure that the compatible ciphers are included
609 in --ciphers option. The default cipher list only includes
610 ciphers compatible with TLSv1.2 or above. The available ver‐
611 sions are: TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
612 Default: TLSv1.2
614 --tls-max-proto-version=<VER>
616 Specify maximum SSL/TLS protocol. The name matching is done in
617 case-insensitive manner. The versions between
618 --tls-min-proto-version and --tls-max-proto-version are
619 enabled. If the protocol list advertised by client does not
620 overlap this range, you will receive the error message
621 "unknown protocol". The available versions are: TLSv1.3,
622 TLSv1.2, TLSv1.1, and TLSv1.0
623 Default: TLSv1.3
625 --tls-ticket-key-file=<PATH>
627 Path to file that contains random data to construct TLS session
628 ticket parameters. If aes-128-cbc is given in
629 --tls-ticket-key-cipher, the file must contain exactly 48
630 bytes. If aes-256-cbc is given in
631 --tls-ticket-key-cipher, the file must contain exactly 80
632 bytes. This options can be used repeatedly to specify
633 multiple ticket parameters. If several files are given, only
634 the first key is used to encrypt TLS session tickets. Other
635 keys are accepted but server will issue new session ticket
636 with first key. This allows session key rotation. Please
637 note that key rotation does not occur automatically. User
638 should rearrange files or change options values and restart
639 nghttpx gracefully. If opening or reading given file fails,
640 all loaded keys are discarded and it is treated as if none of
641 this option is given. If this option is not given or an error
642 occurred while opening or reading a file, key is generated
643 every 1 hour internally and they are valid for 12 hours.
644 This is recommended if ticket key sharing between nghttpx
645 instances is not required.
646 --tls-ticket-key-memcached=<HOST>,<PORT>[;tls]
648 Specify address of memcached server to get TLS ticket keys
649 for session resumption. This enables shared TLS ticket key
650 between multiple nghttpx instances. nghttpx does not set TLS
651 ticket key to memcached. The external ticket key generator is
652 required. nghttpx just gets TLS ticket keys from memcached,
653 and use them, possibly replacing current set of keys. It is
654 up to extern TLS ticket key generator to rotate keys fre‐
655 quently. See "TLS SESSION TICKET RESUMPTION" section in man‐
656 ual page to know the data format in memcached entry. Option‐
657 ally, memcached connection can be encrypted with TLS by
658 specifying "tls" parameter.
659 --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6)
661 Specify address family of memcached connections to get TLS
662 ticket keys. If "auto" is given, both IPv4 and IPv6 are consid‐
663 ered. If "IPv4" is given, only IPv4 address is considered.
664 If "IPv6" is given, only IPv6 address is considered.
665 Default: auto
667 --tls-ticket-key-memcached-interval=<DURATION>
669 Set interval to get TLS ticket keys from memcached.
670 Default: 10m
672 --tls-ticket-key-memcached-max-retry=<N>
674 Set maximum number of consecutive retries before aban‐
675 doning TLS ticket key retrieval. If this number is reached,
676 the attempt is considered as failure, and "failure" count
677 is incremented by 1, which contributed to the
678 value controlled --tls-ticket-key-memcached-max-fail
679 option.
680 Default: 3
682 --tls-ticket-key-memcached-max-fail=<N>
684 Set maximum number of consecutive failure before dis‐
685 abling TLS ticket until next scheduled key retrieval.
686 Default: 2
688 --tls-ticket-key-cipher=<CIPHER>
690 Specify cipher to encrypt TLS session ticket. Specify either
691 aes-128-cbc or aes-256-cbc. By default, aes-128-cbc is
692 used.
693 --tls-ticket-key-memcached-cert-file=<PATH>
695 Path to client certificate for memcached connections to get TLS
696 ticket keys.
697 --tls-ticket-key-memcached-private-key-file=<PATH>
699 Path to client private key for memcached connections to get TLS
700 ticket keys.
701 --fetch-ocsp-response-file=<PATH>
703 Path to fetch-ocsp-response script file. It should be abso‐
704 lute path.
705 Default: /usr/local/share/nghttp2/fetch-ocsp-response
707 --ocsp-update-interval=<DURATION>
709 Set interval to update OCSP response cache.
710 Default: 4h
712 --ocsp-startup
714 Start accepting connections after initial attempts to get
715 OCSP responses finish. It does not matter some of the
716 attempts fail. This feature is useful if OCSP responses
717 must be available before accepting connections.
718 --no-verify-ocsp
720 nghttpx does not verify OCSP response.
721 --no-ocsp
723 Disable OCSP stapling.
724 --tls-session-cache-memcached=<HOST>,<PORT>[;tls]
726 Specify address of memcached server to store session cache.
727 This enables shared session cache between multiple
728 nghttpx instances. Optionally, memcached connection can be
729 encrypted with TLS by specifying "tls" parameter.
730 --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6)
732 Specify address family of memcached connections to store session
733 cache. If "auto" is given, both IPv4 and IPv6 are considered.
734 If "IPv4" is given, only IPv4 address is considered. If "IPv6"
735 is given, only IPv6 address is considered.
736 Default: auto
738 --tls-session-cache-memcached-cert-file=<PATH>
740 Path to client certificate for memcached connections to store
741 session cache.
742 --tls-session-cache-memcached-private-key-file=<PATH>
744 Path to client private key for memcached connections to store
745 session cache.
746 --tls-dyn-rec-warmup-threshold=<SIZE>
748 Specify the threshold size for TLS dynamic record size behav‐
749 iour. During a TLS session, after the threshold number of
750 bytes have been written, the TLS record size will be increased
751 to the maximum allowed (16K). The max record size will con‐
752 tinue to be used on the active TLS session. After
753 --tls-dyn-rec-idle-timeout has elapsed, the record size is
754 reduced to 1300 bytes. Specify 0 to always use the maximum
755 record size, regardless of idle period. This behaviour
756 applies to all TLS based frontends, and TLS HTTP/2 back‐
757 ends.
758 Default: 1M
760 --tls-dyn-rec-idle-timeout=<DURATION>
762 Specify TLS dynamic record size behaviour timeout. See
763 --tls-dyn-rec-warmup-threshold for more information. This
764 behaviour applies to all TLS based frontends, and TLS HTTP/2
765 backends.
766 Default: 1s
768 --no-http2-cipher-black-list
770 Allow black listed cipher suite on frontend HTTP/2 connec‐
771 tion. See
772 https://tools.ietf.org/html/rfc7540#appendix-A for the com‐
773 plete HTTP/2 cipher suites black list.
774 --client-no-http2-cipher-black-list
776 Allow black listed cipher suite on backend HTTP/2 connec‐
777 tion. See
778 https://tools.ietf.org/html/rfc7540#appendix-A for the com‐
779 plete HTTP/2 cipher suites black list.
780 --tls-sct-dir=<DIR>
782 Specifies the directory where *.sct files exist. All *.sct
783 files in <DIR> are read, and sent as extension_data
784 of TLS signed_certificate_timestamp (RFC 6962) to client.
785 These *.sct files are for the certificate specified in
786 positional command-line argument <CERT>, or certificate
787 option in configuration file. For additional certificates,
788 use --subcert option. This option requires OpenSSL >= 1.0.2.
789 --psk-secrets=<PATH>
791 Read list of PSK identity and secrets from <PATH>. This is used
792 for frontend connection. The each line of input file is for‐
793 matted as <identity>:<hex-secret>, where <identity> is PSK
794 identity, and <hex-secret> is secret in hex. An empty line,
795 and line which starts with '#' are skipped. The default
796 enabled cipher list might not contain any PSK cipher suite. In
797 that case, desired PSK cipher suites must be enabled using
798 --ciphers option. The desired PSK cipher suite may be black
799 listed by HTTP/2. To use those cipher suites with
800 HTTP/2, consider to use --no-http2-cipher-black-list option.
801 But be aware its implications.
802 --client-psk-secrets=<PATH>
804 Read PSK identity and secrets from <PATH>. This is used for
805 backend connection. The each line of input file is formatted
806 as <identity>:<hex-secret>, where <identity> is PSK identity,
807 and <hex-secret> is secret in hex. An empty line, and line
808 which starts with '#' are skipped. The first identity and
809 secret pair encountered is used. The default enabled cipher
810 list might not contain any PSK cipher suite. In that case,
811 desired PSK cipher suites must be enabled using
812 --client-ciphers option. The desired PSK cipher suite may be
813 black listed by HTTP/2. To use those cipher suites with
814 HTTP/2, consider to use --client-no-http2-cipher-black-list
815 option. But be aware its implications.
816 --tls-no-postpone-early-data
818 By default, nghttpx postpones forwarding HTTP requests sent in
819 early data, including those sent in partially in it, until TLS
820 handshake finishes. If all backend server recognizes
821 "Early-Data" header field, using this option makes nghttpx not
822 postpone forwarding request and get full potential of 0-RTT
823 data.
824 --tls-max-early-data=<SIZE>
826 Sets the maximum amount of 0-RTT data that server
827 accepts.
828 Default: 16K
830 HTTP/2
832 -c, --frontend-http2-max-concurrent-streams=<N>
833 Set the maximum number of the concurrent streams in one fron‐
834 tend HTTP/2 session.
835 Default: 100
837 --backend-http2-max-concurrent-streams=<N>
839 Set the maximum number of the concurrent streams in one backend
840 HTTP/2 session. This sets maximum number of concurrent
841 opened pushed streams. The maximum number of concurrent
842 requests are set by a remote server.
843 Default: 100
845 --frontend-http2-window-size=<SIZE>
847 Sets the per-stream initial window size of HTTP/2 fron‐
848 tend connection.
849 Default: 65535
851 --frontend-http2-connection-window-size=<SIZE>
853 Sets the per-connection window size of HTTP/2 frontend connec‐
854 tion.
855 Default: 65535
857 --backend-http2-window-size=<SIZE>
859 Sets the initial window size of HTTP/2 backend connec‐
860 tion.
861 Default: 65535
863 --backend-http2-connection-window-size=<SIZE>
865 Sets the per-connection window size of HTTP/2 backend connec‐
866 tion.
867 Default: 2147483647
869 --http2-no-cookie-crumbling
871 Don't crumble cookie header field.
872 --padding=<N>
874 Add at most <N> bytes to a HTTP/2 frame payload as pad‐
875 ding. Specify 0 to disable padding. This option is meant for
876 debugging purpose and not intended to enhance protocol secu‐
877 rity.
878 --no-server-push
880 Disable HTTP/2 server push. Server push is supported by default
881 mode and HTTP/2 frontend via Link header field. It is also
882 supported if both frontend and backend are HTTP/2 in default
883 mode. In this case, server push from backend session is
884 relayed to frontend, and server push via Link header field is
885 also supported.
886 --frontend-http2-optimize-write-buffer-size
888 (Experimental) Enable write buffer size optimization in fron‐
889 tend HTTP/2 TLS connection. This optimization aims to reduce
890 write buffer size so that it only contains bytes which can
891 send immediately. This makes server more responsive to prior‐
892 itized HTTP/2 stream because the buffering of lower priority
893 stream is reduced. This option is only effective on recent
894 Linux platform.
895 --frontend-http2-optimize-window-size
897 (Experimental) Automatically tune connection level window
898 size of frontend HTTP/2 TLS connection. If this feature is
899 enabled, connection window size starts with the default win‐
900 dow size, 65535 bytes. nghttpx automatically adjusts
901 connection window size based on TCP receiving window size.
902 The maximum window size is capped by the value
903 specified by --frontend-http2-connection-window-size.
904 Since the stream is subject to stream level window size, it
905 should be adjusted using --frontend-http2-window-size option as
906 well. This option is only effective on recent Linux plat‐
907 form.
908 --frontend-http2-encoder-dynamic-table-size=<SIZE>
910 Specify the maximum dynamic table size of HPACK encoder in the
911 frontend HTTP/2 connection. The decoder (client) specifies the
912 maximum dynamic table size it accepts. Then the negotiated
913 dynamic table size is the minimum of this option value and the
914 value which client specified.
915 Default: 4K
917 --frontend-http2-decoder-dynamic-table-size=<SIZE>
919 Specify the maximum dynamic table size of HPACK decoder in the
920 frontend HTTP/2 connection.
921 Default: 4K
923 --backend-http2-encoder-dynamic-table-size=<SIZE>
925 Specify the maximum dynamic table size of HPACK encoder in the
926 backend HTTP/2 connection. The decoder (backend) specifies the
927 maximum dynamic table size it accepts. Then the negotiated
928 dynamic table size is the minimum of this option value and the
929 value which backend specified.
930 Default: 4K
932 --backend-http2-decoder-dynamic-table-size=<SIZE>
934 Specify the maximum dynamic table size of HPACK decoder in the
935 backend HTTP/2 connection.
936 Default: 4K
938 Mode
940 (default mode)
941 Accept HTTP/2, and HTTP/1.1 over SSL/TLS. "no-tls" parame‐
942 ter is used in --frontend option, accept HTTP/2 and HTTP/1.1
943 over cleartext TCP. The incoming HTTP/1.1 connection can be
944 upgraded to HTTP/2 through HTTP Upgrade.
945 -s, --http2-proxy
947 Like default mode, but enable forward proxy. This is so called
948 HTTP/2 proxy mode.
949 Logging
951 -L, --log-level=<LEVEL>
952 Set the severity level of log output. <LEVEL> must be one of
953 INFO, NOTICE, WARN, ERROR and FATAL.
954 Default: NOTICE
956 --accesslog-file=<PATH>
958 Set path to write access log. To reopen file, send USR1 signal
959 to nghttpx.
960 --accesslog-syslog
962 Send access log to syslog. If this option is used,
963 --accesslog-file option is ignored.
964 --accesslog-format=<FORMAT>
966 Specify format string for access log. The default format
967 is combined format. The following variables are available:
968 · $remote_addr: client IP address.
970 · $time_local: local time in Common Log format.
972 · $time_iso8601: local time in ISO 8601 format.
974 · $request: HTTP request line.
976 · $status: HTTP response status code.
978 · $body_bytes_sent: the number of bytes sent to client as
980 response body.
981 · $http_<VAR>: value of HTTP request header <VAR> where '_' in
983 <VAR> is replaced with '-'.
984 · $remote_port: client port.
986 · $server_port: server port.
988 · $request_time: request processing time in seconds with mil‐
990 liseconds resolution.
991 · $pid: PID of the running process.
993 · $alpn: ALPN identifier of the protocol which generates the
995 response. For HTTP/1, ALPN is always http/1.1, regardless
996 of minor version.
997 · $tls_cipher: cipher used for SSL/TLS connection.
999 · $tls_client_fingerprint_sha256: SHA-256 fingerprint of client
1001 certificate.
1002 · $tls_client_fingerprint_sha1: SHA-1 fingerprint of client
1004 certificate.
1005 · $tls_client_subject_name: subject name in client cer‐
1007 tificate.
1008 · $tls_client_issuer_name: issuer name in client cer‐
1010 tificate.
1011 · $tls_client_serial: serial number in client cer‐
1013 tificate.
1014 · $tls_protocol: protocol for SSL/TLS connection.
1016 · $tls_session_id: session ID for SSL/TLS connection.
1018 · $tls_session_reused: "r" if SSL/TLS session was reused.
1020 Otherwise, "."
1021 · $tls_sni: SNI server name for SSL/TLS connection.
1023 · $backend_host: backend host used to fulfill the
1025 request. "-" if backend host is not available.
1026 · $backend_port: backend port used to fulfill the
1028 request. "-" if backend host is not available.
1029 The variable can be enclosed by "{" and "}" for disam‐
1031 biguation (e.g., ${remote_addr}).
1032 Default: $remote_addr - - [$time_local] "$request" $status
1034 $body_bytes_sent "$http_referer" "$http_user_agent"
1035 --accesslog-write-early
1037 Write access log when response header fields are
1038 received from backend rather than when request trans‐
1039 action finishes.
1040 --errorlog-file=<PATH>
1042 Set path to write error log. To reopen file, send USR1 signal
1043 to nghttpx. stderr will be redirected to the error log file
1044 unless --errorlog-syslog is used.
1045 Default: /dev/stderr
1047 --errorlog-syslog
1049 Send error log to syslog. If this option is used,
1050 --errorlog-file option is ignored.
1051 --syslog-facility=<FACILITY>
1053 Set syslog facility to <FACILITY>.
1054 Default: daemon
1056 HTTP
1058 --add-x-forwarded-for
1059 Append X-Forwarded-For header field to the downstream
1060 request.
1061 --strip-incoming-x-forwarded-for
1063 Strip X-Forwarded-For header field from inbound client
1064 requests.
1065 --no-add-x-forwarded-proto
1067 Don't append additional X-Forwarded-Proto header field to the
1068 backend request. If inbound client sets X-For‐
1069 warded-Proto, and
1070 --no-strip-incoming-x-forwarded-proto option is used, they
1071 are passed to the backend.
1072 --no-strip-incoming-x-forwarded-proto
1074 Don't strip X-Forwarded-Proto header field from inbound client
1075 requests.
1076 --add-forwarded=<LIST>
1078 Append RFC 7239 Forwarded header field with parameters speci‐
1079 fied in comma delimited list <LIST>. The supported parameters
1080 are "by", "for", "host", and "proto". By default, the value
1081 of "by" and "for" parameters are obfuscated string.
1082 See --forwarded-by and --forwarded-for options respec‐
1083 tively. Note that nghttpx does not translate non-standard
1084 X-Forwarded-* header fields into Forwarded header field, and
1085 vice versa.
1086 --strip-incoming-forwarded
1088 Strip Forwarded header field from inbound client
1089 requests.
1090 --forwarded-by=(obfuscated|ip|<VALUE>)
1092 Specify the parameter value sent out with "by" parameter of For‐
1093 warded header field. If "obfuscated" is given, the string is
1094 randomly generated at startup. If "ip" is given, the inter‐
1095 face address of the connection, including port number, is
1096 sent with "by" parameter. In case of UNIX domain socket,
1097 "localhost" is used instead of address and port. User can also
1098 specify the static obfuscated string. The limitation is that it
1099 must start with "_", and only consists of character
1100 set [A-Za-z0-9._-], as described in RFC 7239.
1101 Default: obfuscated
1103 --forwarded-for=(obfuscated|ip)
1105 Specify the parameter value sent out with "for" parame‐
1106 ter of Forwarded header field. If "obfuscated" is given, the
1107 string is randomly generated for each client connection. If
1108 "ip" is given, the remote client address of the connection,
1109 without port number, is sent with "for" parameter. In case
1110 of UNIX domain socket, "localhost" is used instead of
1111 address.
1112 Default: obfuscated
1114 --no-via
1116 Don't append to Via header field. If Via header field is
1117 received, it is left unaltered.
1118 --no-strip-incoming-early-data
1120 Don't strip Early-Data header field from inbound client
1121 requests.
1122 --no-location-rewrite
1124 Don't rewrite location header field in default mode. When
1125 --http2-proxy is used, location header field will not be
1126 altered regardless of this option.
1127 --host-rewrite
1129 Rewrite host and :authority header fields in default mode.
1130 When --http2-proxy is used, these headers will not be altered
1131 regardless of this option.
1132 --altsvc=<PROTOID,PORT[,HOST,[ORIGIN]]>
1134 Specify protocol ID, port, host and origin of alter‐
1135 native service. <HOST> and <ORIGIN> are optional. They are
1136 advertised in alt-svc header field only in HTTP/1.1 fron‐
1137 tend. This option can be used multiple times to specify
1138 multiple alternative services. Example: --altsvc=h2,443
1139 --add-request-header=<HEADER>
1141 Specify additional header field to add to request header set.
1142 This option just appends header field and won't replace any‐
1143 thing already set. This option can be used several times
1144 to specify multiple header fields. Example:
1145 --add-request-header="foo: bar"
1146 --add-response-header=<HEADER>
1148 Specify additional header field to add to response header
1149 set. This option just appends header field and won't replace
1150 anything already set. This option can be used several times
1151 to specify multiple header fields. Example:
1152 --add-response-header="foo: bar"
1153 --request-header-field-buffer=<SIZE>
1155 Set maximum buffer size for incoming HTTP request header field
1156 list. This is the sum of header name and value in bytes. If
1157 trailer fields exist, they are counted towards this number.
1158 Default: 64K
1160 --max-request-header-fields=<N>
1162 Set maximum number of incoming HTTP request header fields.
1163 If trailer fields exist, they are counted towards this num‐
1164 ber.
1165 Default: 100
1167 --response-header-field-buffer=<SIZE>
1169 Set maximum buffer size for incoming HTTP response header
1170 field list. This is the sum of header name and value in
1171 bytes. If trailer fields exist, they are counted towards
1172 this number.
1173 Default: 64K
1175 --max-response-header-fields=<N>
1177 Set maximum number of incoming HTTP response header fields.
1178 If trailer fields exist, they are counted towards this num‐
1179 ber.
1180 Default: 500
1182 --error-page=(<CODE>|*)=<PATH>
1184 Set file path to custom error page served when nghttpx origi‐
1185 nally generates HTTP error status code <CODE>. <CODE> must
1186 be greater than or equal to 400, and at most 599. If "*" is
1187 used instead of <CODE>, it matches all HTTP status code. If
1188 error status code comes from backend server, the custom error
1189 pages are not used.
1190 --server-name=<NAME>
1192 Change server response header field value to <NAME>.
1193 Default: nghttpx
1195 --no-server-rewrite
1197 Don't rewrite server header field in default mode. When
1198 --http2-proxy is used, these headers will not be altered regard‐
1199 less of this option.
1200 --redirect-https-port=<PORT>
1202 Specify the port number which appears in Location header field
1203 when redirect to HTTPS URI is made due to "redi‐
1204 rect-if-not-tls" parameter in --backend option.
1205 Default: 443
1207 API
1209 --api-max-request-body=<SIZE>
1210 Set the maximum size of request body for API request.
1211 Default: 32M
1213 DNS
1215 --dns-cache-timeout=<DURATION>
1216 Set duration that cached DNS results remain valid. Note that
1217 nghttpx caches the unsuccessful results as well.
1218 Default: 10s
1220 --dns-lookup-timeout=<DURATION>
1222 Set timeout that DNS server is given to respond to the initial
1223 DNS query. For the 2nd and later queries, server is given
1224 time based on this timeout, and it is scaled linearly.
1225 Default: 5s
1227 --dns-max-try=<N>
1229 Set the number of DNS query before nghttpx gives up name lookup.
1230 Default: 2
1232 --frontend-max-requests=<N>
1234 The number of requests that single frontend connection can
1235 process. For HTTP/2, this is the number of streams in one
1236 HTTP/2 connection. For HTTP/1, this is the number of keep
1237 alive requests. This is hint to nghttpx, and it may allow
1238 additional few requests. The default value is unlimited.
1239 Debug
1241 --frontend-http2-dump-request-header=<PATH>
1242 Dumps request headers received by HTTP/2 frontend to the file
1243 denoted in <PATH>. The output is done in HTTP/1 header field
1244 format and each header block is followed by an empty line. This
1245 option is not thread safe and MUST NOT be used with option
1246 -n<N>, where <N> >= 2.
1247 --frontend-http2-dump-response-header=<PATH>
1249 Dumps response headers sent from HTTP/2 frontend to the file
1250 denoted in <PATH>. The output is done in HTTP/1 header field
1251 format and each header block is followed by an empty line. This
1252 option is not thread safe and MUST NOT be used with option
1253 -n<N>, where <N> >= 2.
1254 -o, --frontend-frame-debug
1256 Print HTTP/2 frames in frontend to stderr. This option is not
1257 thread safe and MUST NOT be used with option -n=N, where N
1258 >= 2.
1259 Process
1261 -D, --daemon
1262 Run in a background. If -D is used, the current working direc‐
1263 tory is changed to '/'.
1264 --pid-file=<PATH>
1266 Set path to save PID of this program.
1267 --user=<USER>
1269 Run this program as <USER>. This option is intended to be used
1270 to drop root privileges.
1271 --single-process
1273 Run this program in a single process mode for debugging pur‐
1274 pose. Without this option, nghttpx creates at least 2 pro‐
1275 cesses: master and worker processes. If this option is
1276 used, master and worker are unified into a single process.
1277 nghttpx still spawns additional process if neverbleed is used.
1278 In the single process mode, the signal handling feature is dis‐
1279 abled.
1280 Scripting
1282 --mruby-file=<PATH>
1283 Set mruby script file
1284 --ignore-per-pattern-mruby-error
1286 Ignore mruby compile error for per-pattern mruby script file.
1287 If error occurred, it is treated as if no mruby file were
1288 specified for the pattern.
1289 Misc
1291 --conf=<PATH>
1292 Load configuration from <PATH>. Please note that nghttpx
1293 always tries to read the default configuration file if --conf
1294 is not given.
1295 Default: /etc/nghttpx/nghttpx.conf
1297 --include=<PATH>
1299 Load additional configurations from <PATH>. File <PATH> is
1300 read when configuration parser encountered this option.
1301 This option can be used multiple times, or even recursively.
1302 -v, --version
1304 Print version and exit.
1305 -h, --help
1307 Print this help and exit.
1308 The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
1310 * 1024). Units are K, M and G (powers of 1024).
1311 The <DURATION> argument is an integer and an optional unit (e.g., 1s is
1313 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
1314 (hours, minutes, seconds and milliseconds, respectively). If a unit is
1315 omitted, a second is used as unit.
1316
1318 /etc/nghttpx/nghttpx.conf
1319 The default configuration file path nghttpx searches at startup.
1320 The configuration file path can be changed using --conf option.
1321 Those lines which are staring # are treated as comment.
1323 The option name in the configuration file is the long com‐
1325 mand-line option name with leading -- stripped (e.g., frontend).
1326 Put = between option name and value. Don't put extra leading or
1327 trailing spaces.
1328 When specifying arguments including characters which have spe‐
1330 cial meaning to a shell, we usually use quotes so that shell
1331 does not interpret them. When writing this configuration file,
1332 quotes for this purpose must not be used. For example, specify
1333 additional request header field, do this:
1334 add-request-header=foo: bar
1336 instead of:
1338 add-request-header="foo: bar"
1340 The options which do not take argument in the command-line take
1342 argument in the configuration file. Specify yes as an argument
1343 (e.g., http2-proxy=yes). If other string is given, it is
1344 ignored.
1345 To specify private key and certificate file which are given as
1347 positional arguments in command-line, use private-key-file and
1348 certificate-file.
1349 --conf option cannot be used in the configuration file and will
1351 be ignored if specified.
1352 Error log
1354 Error log is written to stderr by default. It can be configured
1355 using --errorlog-file. The format of log message is as follows:
1356 <datetime> <master-pid> <current-pid> <thread-id> <level>
1358 (<filename>:<line>) <msg>
1359 <datetime>
1361 It is a combination of date and time when the log is
1362 written. It is in ISO 8601 format.
1363 <master-pid>
1365 It is a master process ID.
1366 <current-pid>
1368 It is a process ID which writes this log.
1369 <thread-id>
1371 It is a thread ID which writes this log. It would be
1372 unique within <current-pid>.
1373 <filename> and <line>
1375 They are source file name, and line number which produce
1376 this log.
1377 <msg> It is a log message body.
1379
1381 SIGQUIT
1382 Shutdown gracefully. First accept pending connections and stop
1383 accepting connection. After all connections are handled,
1384 nghttpx exits.
1385 SIGHUP Reload configuration file given in --conf.
1387 SIGUSR1
1389 Reopen log files.
1390 SIGUSR2
1392 Fork and execute nghttpx. It will execute the binary in the same
1393 path with same command-line arguments and environment variables. As
1394 of nghttpx version 1.20.0, the new master process sends SIGQUIT to
1395 the original master process when it is ready to serve requests. For
1396 the earlier versions of nghttpx, user has to send SIGQUIT to the
1397 original master process.
1398 The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
1400 is usually used to execute new binary, and the master process is
1401 newly spawned. On the other hand, the latter just reloads configu‐
1402 ration file, and the same master process continues to exist.
1403 NOTE:
1405 nghttpx consists of multiple processes: one process for processing
1406 these signals, and another one for processing requests. The former
1407 spawns the latter. The former is called master process, and the
1408 latter is called worker process. If neverbleed is enabled, the
1409 worker process spawns neverbleed daemon process which does RSA key
1410 processing. The above signal must be sent to the master process.
1411 If the other processes received one of them, it is ignored. This
1412 behaviour of these processes may change in the future release. In
1413 other words, in the future release, the processes other than master
1414 process may terminate upon the reception of these signals. There‐
1415 fore these signals should not be sent to the processes other than
1416 master process.
1417
1419 nghttpx supports HTTP/2 server push in default mode with Link header
1420 field. nghttpx looks for Link header field (RFC 5988) in response
1421 headers from backend server and extracts URI-reference with parameter
1422 rel=preload (see preload) and pushes those URIs to the frontend client.
1423 Here is a sample Link header field to initiate server push:
1424 Link: </fonts/font.woff>; rel=preload
1426 Link: </css/theme.css>; rel=preload
1427 Currently, the following restriction is applied for server push:
1429 1. The associated stream must have method "GET" or "POST". The associ‐
1431 ated stream's status code must be 200.
1432 This limitation may be loosened in the future release.
1434 nghttpx also supports server push if both frontend and backend are
1436 HTTP/2 in default mode. In this case, in addition to server push via
1437 Link header field, server push from backend is forwarded to frontend
1438 HTTP/2 session.
1439 HTTP/2 server push will be disabled if --http2-proxy is used.
1441
1443 nghttpx supports UNIX domain socket with a filename for both frontend
1444 and backend connections.
1445 Please note that current nghttpx implementation does not delete a
1447 socket with a filename. And on start up, if nghttpx detects that the
1448 specified socket already exists in the file system, nghttpx first
1449 deletes it. However, if SIGUSR2 is used to execute new binary and both
1450 old and new configurations use same filename, new binary does not
1451 delete the socket and continues to use it.
1452
1454 OCSP query is done using external Python script fetch-ocsp-response,
1455 which has been originally developed in Perl as part of h2o project (‐
1456 https://github.com/h2o/h2o), and was translated into Python.
1457 The script file is usually installed under $(prefix)/share/nghttp2/
1459 directory. The actual path to script can be customized using
1460 --fetch-ocsp-response-file option.
1461 If OCSP query is failed, previous OCSP response, if any, is continued
1463 to be used.
1464 --fetch-ocsp-response-file option provides wide range of possibility to
1466 manage OCSP response. It can take an arbitrary script or executable.
1467 The requirement is that it supports the command-line interface of
1468 fetch-ocsp-response script, and it must return a valid DER encoded OCSP
1469 response on success. It must return exit code 0 on success, and 75 for
1470 temporary error, and the other error code for generic failure. For
1471 large cluster of servers, it is not efficient for each server to per‐
1472 form OCSP query using fetch-ocsp-response. Instead, you can retrieve
1473 OCSP response in some way, and store it in a disk or a shared database.
1474 Then specify a program in --fetch-ocsp-response-file to fetch it from
1475 those stores. This could provide a way to share the OCSP response
1476 between fleet of servers, and also any OCSP query strategy can be
1477 applied which may be beyond the ability of nghttpx itself or
1478 fetch-ocsp-response script.
1479
1481 nghttpx supports TLS session resumption through both session ID and
1482 session ticket.
1483 SESSION ID RESUMPTION
1485 By default, session ID is shared by all worker threads.
1486 If --tls-session-cache-memcached is given, nghttpx will insert serial‐
1488 ized session data to memcached with nghttpx:tls-session-cache: + lower‐
1489 case hex string of session ID as a memcached entry key, with expiry
1490 time 12 hours. Session timeout is set to 12 hours.
1491 By default, connections to memcached server are not encrypted. To
1493 enable encryption, use tls keyword in --tls-session-cache-memcached
1494 option.
1495 TLS SESSION TICKET RESUMPTION
1497 By default, session ticket is shared by all worker threads. The auto‐
1498 matic key rotation is also enabled by default. Every an hour, new
1499 encryption key is generated, and previous encryption key becomes
1500 decryption only key. We set session timeout to 12 hours, and thus we
1501 keep at most 12 keys.
1502 If --tls-ticket-key-memcached is given, encryption keys are retrieved
1504 from memcached. nghttpx just reads keys from memcached; one has to
1505 deploy key generator program to update keys frequently (e.g., every 1
1506 hour). The example key generator tlsticketupdate.go is available under
1507 contrib directory in nghttp2 archive. The memcached entry key is
1508 nghttpx:tls-ticket-key. The data format stored in memcached is the
1509 binary format described below:
1510 +--------------+-------+----------------+
1512 | VERSION (4) |LEN (2)|KEY(48 or 80) ...
1513 +--------------+-------+----------------+
1514 ^ |
1515 | |
1516 +------------------------+
1517 (LEN, KEY) pair can be repeated
1518 All numbers in the above figure is bytes. All integer fields are net‐
1520 work byte order.
1521 First 4 bytes integer VERSION field, which must be 1. The 2 bytes
1523 integer LEN field gives the length of following KEY field, which con‐
1524 tains key. If --tls-ticket-key-cipher=aes-128-cbc is used, LEN must be
1525 48. If --tls-ticket-key-cipher=aes-256-cbc is used, LEN must be 80.
1526 LEN and KEY pair can be repeated multiple times to store multiple keys.
1527 The key appeared first is used as encryption key. All the remaining
1528 keys are used as decryption only.
1529 By default, connections to memcached server are not encrypted. To
1531 enable encryption, use tls keyword in --tls-ticket-key-memcached
1532 option.
1533 If --tls-ticket-key-file is given, encryption key is read from the
1535 given file. In this case, nghttpx does not rotate key automatically.
1536 To rotate key, one has to restart nghttpx (see SIGNALS).
1537
1539 nghttpx supports TLS signed_certificate_timestamp extension (RFC 6962).
1540 The relevant options are --tls-sct-dir and sct-dir parameter in
1541 --subcert. They takes a directory, and nghttpx reads all files whose
1542 extension is .sct under the directory. The *.sct files are encoded as
1543 SignedCertificateTimestamp struct described in section 3.2 of RFC
1544 69662. This format is the same one used by nginx-ct and mod_ssl_ct.
1545 ct-submit can be used to submit certificates to log servers, and obtain
1546 the SignedCertificateTimestamp struct which can be used with nghttpx.
1547
1549 WARNING:
1550 The current mruby extension API is experimental and not frozen. The
1551 API is subject to change in the future release.
1552 WARNING:
1554 Almost all string value returned from method, or attribute is a
1555 fresh new mruby string, which involves memory allocation, and
1556 copies. Therefore, it is strongly recommended to store a return
1557 value in a local variable, and use it, instead of calling method or
1558 accessing attribute repeatedly.
1559 nghttpx allows users to extend its capability using mruby scripts.
1561 nghttpx has 2 hook points to execute mruby script: request phase and
1562 response phase. The request phase hook is invoked after all request
1563 header fields are received from client. The response phase hook is
1564 invoked after all response header fields are received from backend
1565 server. These hooks allows users to modify header fields, or common
1566 HTTP variables, like authority or request path, and even return custom
1567 response without forwarding request to backend servers.
1568 There are 2 levels of mruby script invocations: global and per-pattern.
1570 The global mruby script is set by --mruby-file option and is called for
1571 all requests. The per-pattern mruby script is set by "mruby" parameter
1572 in -b option. It is invoked for a request which matches the particular
1573 pattern. The order of hook invocation is: global request phase hook,
1574 per-pattern request phase hook, per-pattern response phase hook, and
1575 finally global response phase hook. If a hook returns a response, any
1576 later hooks are not invoked. The global request hook is invoked before
1577 the pattern matching is made and changing request path may affect the
1578 pattern matching.
1579 Please note that request and response hooks of per-pattern mruby script
1581 for a single request might not come from the same script. This might
1582 happen after a request hook is executed, backend failed for some rea‐
1583 son, and at the same time, backend configuration is replaced by API
1584 request, and then the request uses new configuration on retry. The
1585 response hook from new configuration, if it is specified, will be
1586 invoked.
1587 The all mruby script will be evaluated once per thread on startup, and
1589 it must instantiate object and evaluate it as the return value (e.g.,
1590 App.new). This object is called app object. If app object defines
1591 on_req method, it is called with Nghttpx::Env object on request hook.
1592 Similarly, if app object defines on_resp method, it is called with
1593 Nghttpx::Env object on response hook. For each method invocation, user
1594 can can access Nghttpx::Request and Nghttpx::Response objects via
1595 Nghttpx::Env#req and Nghttpx::Env#resp respectively.
1596 Nghttpx::REQUEST_PHASE
1598 Constant to represent request phase.
1599 Nghttpx::RESPONSE_PHASE
1601 Constant to represent response phase.
1602 class Nghttpx::Env
1604 Object to represent current request specific context.
1605 attribute [R] req
1607 Return Request object.
1608 attribute [R] resp
1610 Return Response object.
1611 attribute [R] ctx
1613 Return Ruby hash object. It persists until request fin‐
1614 ishes. So values set in request phase hook can be
1615 retrieved in response phase hook.
1616 attribute [R] phase
1618 Return the current phase.
1619 attribute [R] remote_addr
1621 Return IP address of a remote client. If connection is
1622 made via UNIX domain socket, this returns the string
1623 "localhost".
1624 attribute [R] server_addr
1626 Return address of server that accepted the connection.
1627 This is a string which specified in --frontend option,
1628 excluding port number, and not a resolved IP address.
1629 For UNIX domain socket, this is a path to UNIX domain
1630 socket.
1631 attribute [R] server_port
1633 Return port number of the server frontend which accepted
1634 the connection from client.
1635 attribute [R] tls_used
1637 Return true if TLS is used on the connection.
1638 attribute [R] tls_sni
1640 Return the TLS SNI value which client sent in this con‐
1641 nection.
1642 attribute [R] tls_client_fingerprint_sha256
1644 Return the SHA-256 fingerprint of a client certificate.
1645 attribute [R] tls_client_fingerprint_sha1
1647 Return the SHA-1 fingerprint of a client certificate.
1648 attribute [R] tls_client_issuer_name
1650 Return the issuer name of a client certificate.
1651 attribute [R] tls_client_subject_name
1653 Return the subject name of a client certificate.
1654 attribute [R] tls_client_serial
1656 Return the serial number of a client certificate.
1657 attribute [R] tls_client_not_before
1659 Return the start date of a client certificate in seconds
1660 since the epoch.
1661 attribute [R] tls_client_not_after
1663 Return the end date of a client certificate in seconds
1664 since the epoch.
1665 attribute [R] tls_cipher
1667 Return a TLS cipher negotiated in this connection.
1668 attribute [R] tls_protocol
1670 Return a TLS protocol version negotiated in this connec‐
1671 tion.
1672 attribute [R] tls_session_id
1674 Return a session ID for this connection in hex string.
1675 attribute [R] tls_session_reused
1677 Return true if, and only if a SSL/TLS session is reused.
1678 attribute [R] alpn
1680 Return ALPN identifier negotiated in this connection.
1681 attribute [R] tls_handshake_finished
1683 Return true if SSL/TLS handshake has finished. If it
1684 returns false in the request phase hook, the request is
1685 received in TLSv1.3 early data (0-RTT) and might be vul‐
1686 nerable to the replay attack. nghttpx will send
1687 Early-Data header field to backend servers to indicate
1688 this.
1689 class Nghttpx::Request
1691 Object to represent request from client. The modification to
1692 Request object is allowed only in request phase hook.
1693 attribute [R] http_version_major
1695 Return HTTP major version.
1696 attribute [R] http_version_minor
1698 Return HTTP minor version.
1699 attribute [R/W] method
1701 HTTP method. On assignment, copy of given value is
1702 assigned. We don't accept arbitrary method name. We
1703 will document them later, but well known methods, like
1704 GET, PUT and POST, are all supported.
1705 attribute [R/W] authority
1707 Authority (i.e., example.org), including optional port
1708 component . On assignment, copy of given value is
1709 assigned.
1710 attribute [R/W] scheme
1712 Scheme (i.e., http, https). On assignment, copy of given
1713 value is assigned.
1714 attribute [R/W] path
1716 Request path, including query component (i.e.,
1717 /index.html). On assignment, copy of given value is
1718 assigned. The path does not include authority component
1719 of URI. This may include query component. nghttpx makes
1720 certain normalization for path. It decodes per‐
1721 cent-encoding for unreserved characters (see
1722 https://tools.ietf.org/html/rfc3986#section-2.3), and
1723 resolves ".." and ".". But it may leave characters which
1724 should be percent-encoded as is. So be careful when com‐
1725 paring path against desired string.
1726 attribute [R] headers
1728 Return Ruby hash containing copy of request header
1729 fields. Changing values in returned hash does not change
1730 request header fields actually used in request process‐
1731 ing. Use Nghttpx::Request#add_header or
1732 Nghttpx::Request#set_header to change request header
1733 fields.
1734 add_header(key, value)
1736 Add header entry associated with key. The value can be
1737 single string or array of string. It does not replace
1738 any existing values associated with key.
1739 set_header(key, value)
1741 Set header entry associated with key. The value can be
1742 single string or array of string. It replaces any exist‐
1743 ing values associated with key.
1744 clear_headers()
1746 Clear all existing request header fields.
1747 push(uri)
1749 Initiate to push resource identified by uri. Only HTTP/2
1750 protocol supports this feature. For the other protocols,
1751 this method is noop. uri can be absolute URI, absolute
1752 path or relative path to the current request. For abso‐
1753 lute or relative path, scheme and authority are inherited
1754 from the current request. Currently, method is always
1755 GET. nghttpx will issue request to backend servers to
1756 fulfill this request. The request and response phase
1757 hooks will be called for pushed resource as well.
1758 class Nghttpx::Response
1760 Object to represent response from backend server.
1761 attribute [R] http_version_major
1763 Return HTTP major version.
1764 attribute [R] http_version_minor
1766 Return HTTP minor version.
1767 attribute [R/W] status
1769 HTTP status code. It must be in the range [200, 999],
1770 inclusive. The non-final status code is not supported in
1771 mruby scripting at the moment.
1772 attribute [R] headers
1774 Return Ruby hash containing copy of response header
1775 fields. Changing values in returned hash does not change
1776 response header fields actually used in response process‐
1777 ing. Use Nghttpx::Response#add_header or
1778 Nghttpx::Response#set_header to change response header
1779 fields.
1780 add_header(key, value)
1782 Add header entry associated with key. The value can be
1783 single string or array of string. It does not replace
1784 any existing values associated with key.
1785 set_header(key, value)
1787 Set header entry associated with key. The value can be
1788 single string or array of string. It replaces any exist‐
1789 ing values associated with key.
1790 clear_headers()
1792 Clear all existing response header fields.
1793 return(body)
1795 Return custom response body to a client. When this
1796 method is called in request phase hook, the request is
1797 not forwarded to the backend, and response phase hook for
1798 this request will not be invoked. When this method is
1799 called in response phase hook, response from backend
1800 server is canceled and discarded. The status code and
1801 response header fields should be set before using this
1802 method. To set status code, use
1803 Nghttpx::Response#status. If status code is not set, 200
1804 is used. To set response header fields,
1805 Nghttpx::Response#add_header and
1806 Nghttpx::Response#set_header. When this method is
1807 invoked in response phase hook, the response headers are
1808 filled with the ones received from backend server. To
1809 send completely custom header fields, first call
1810 Nghttpx::Response#clear_headers to erase all existing
1811 header fields, and then add required header fields. It
1812 is an error to call this method twice for a given
1813 request.
1814 send_info(status, headers)
1816 Send non-final (informational) response to a client.
1817 status must be in the range [100, 199], inclusive. head‐
1818 ers is a hash containing response header fields. Its key
1819 must be a string, and the associated value must be either
1820 string or array of strings. Since this is not a final
1821 response, even if this method is invoked, request is
1822 still forwarded to a backend unless
1823 Nghttpx::Response#return is called. This method can be
1824 called multiple times. It cannot be called after
1825 Nghttpx::Response#return is called.
1826 MRUBY EXAMPLES
1828 Modify request path:
1829 class App
1831 def on_req(env)
1832 env.req.path = "/apps#{env.req.path}"
1833 end
1834 end
1835 App.new
1837 Don't forget to instantiate and evaluate object at the last line.
1839 Restrict permission of viewing a content to a specific client
1841 addresses:
1842 class App
1844 def on_req(env)
1845 allowed_clients = ["127.0.0.1", "::1"]
1846 if env.req.path.start_with?("/log/") &&
1848 !allowed_clients.include?(env.remote_addr) then
1849 env.resp.status = 404
1850 env.resp.return "permission denied"
1851 end
1852 end
1853 end
1854 App.new
1856
1858 nghttpx exposes API endpoints to manipulate it via HTTP based API. By
1859 default, API endpoint is disabled. To enable it, add a dedicated fron‐
1860 tend for API using --frontend option with "api" parameter. All
1861 requests which come from this frontend address, will be treated as API
1862 request.
1863 The response is normally JSON dictionary, and at least includes the
1865 following keys:
1866 status The status of the request processing. The following values are
1868 defined:
1869 Success
1871 The request was successful.
1872 Failure
1874 The request was failed. No change has been made.
1875 code HTTP status code
1877 Additionally, depending on the API endpoint, data key may be present,
1879 and its value contains the API endpoint specific data.
1880 We wrote "normally", since nghttpx may return ordinal HTML response in
1882 some cases where the error has occurred before reaching API endpoint
1883 (e.g., header field is too large).
1884 The following section describes available API endpoints.
1886 POST /api/v1beta1/backendconfig
1888 This API replaces the current backend server settings with the
1889 requested ones. The request method should be POST, but PUT is also
1890 acceptable. The request body must be nghttpx configuration file for‐
1891 mat. For configuration file format, see FILES section. The line sepa‐
1892 rator inside the request body must be single LF (0x0A). Currently,
1893 only backend option is parsed, the others are simply ignored. The
1894 semantics of this API is replace the current backend with the backend
1895 options in request body. Describe the desired set of backend severs,
1896 and nghttpx makes it happen. If there is no backend option is found in
1897 request body, the current set of backend is replaced with the backend
1898 option's default value, which is 127.0.0.1,80.
1899 The replacement is done instantly without breaking existing connections
1901 or requests. It also avoids any process creation as is the case with
1902 hot swapping with signals.
1903 The one limitation is that only numeric IP address is allowed in
1905 backend in request body unless "dns" parameter is used while non
1906 numeric hostname is allowed in command-line or configuration file is
1907 read using --conf.
1908 GET /api/v1beta1/configrevision
1910 This API returns configuration revision of the current nghttpx. The
1911 configuration revision is opaque string, and it changes after each
1912 reloading by SIGHUP. With this API, an external application knows that
1913 whether nghttpx has finished reloading its configuration by comparing
1914 the configuration revisions between before and after reloading. It is
1915 recommended to disable persistent (keep-alive) connection for this pur‐
1916 pose in order to avoid to send a request using the reused connection
1917 which may bound to an old process.
1918 This API returns response including data key. Its value is JSON
1920 object, and it contains at least the following key:
1921 configRevision
1923 The configuration revision of the current nghttpx
1924
1926 nghttp(1), nghttpd(1), h2load(1)
1927
1929 Tatsuhiro Tsujikawa
1930
1932 2012, 2015, 2016, Tatsuhiro Tsujikawa
19331.34.0 Oct 04, 2018 NGHTTPX(1)