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/3, 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 ad‐
29 dresses 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 to‐
99 gether 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-timeout=<DU‐
107 RATION>", "group=<GROUP>", "group-weight=<N>", "weight=<N>",
108 and "dnf". The parameter consists of keyword, and op‐
109 tionally followed by "=" and value. For example, the parameter
110 "proto=h2" consists of the keyword "proto" and value "h2". The
111 parameter "tls" consists of the keyword "tls" without value.
112 Each parameter is described as follows.
113 The backend application protocol can be specified using op‐
115 tional "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 at‐
138 tempts 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 en‐
153 abled for all backend servers sharing the same <PATTERN>. It
154 is advised to set "affinity" parameter to all backend ex‐
155 plicitly if session affinity is desired. The session affinity
156 may break if one of the backend gets unreachable, or
157 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 "affinity-cookie-se‐
165 cure=<SECURE>" controls the Secure attribute of a cookie.
166 The default value is "auto", and the Secure attribute is deter‐
167 mined by a request scheme. If a request scheme is "https", then
168 Secure attribute is set. Otherwise, it is not set. If <SE‐
169 CURE> is "yes", the Secure attribute is always set. If <SE‐
170 CURE> is "no", the Secure attribute is always omitted.
171 By default, name resolution of backend host name is done at
173 start up, or reloading configuration. If "dns" parameter
174 is given, name resolution takes place dynamically. This
175 is useful if backend address changes frequently. If "dns"
176 is given, name resolution of backend host name at
177 start up, or reloading configuration is skipped.
178 If "redirect-if-not-tls" parameter is used, the matched backend
180 requires that frontend connection is TLS encrypted. If
181 it isn't, nghttpx responds to the request with 308 status code,
182 and https URI the client should use instead is included in
183 Location header field. The port number in redirect URI is 443
184 by default, and can be changed using --redirect-https-port
185 option. If at least one backend has "redirect-if-not-tls"
186 parameter, this feature is enabled for all backend servers
187 sharing the same <PATTERN>. It is advised to set
188 "redirect-if-no-tls" parameter to all backends explic‐
189 itly if this feature is desired.
190 If "upgrade-scheme" parameter is used along with "tls" parame‐
192 ter, HTTP/2 :scheme pseudo header field is changed to "https"
193 from "http" when forwarding a request to this particular back‐
194 end. This is a workaround for a backend server which re‐
195 quires "https" :scheme pseudo header field on TLS encrypted
196 connection.
197 "mruby=<PATH>" parameter specifies a path to mruby script
199 file which is invoked when this pattern is matched. All
200 backends which share the same pattern must have the same mruby
201 path.
202 "read-timeout=<DURATION>" and "write-timeout=<DURATION>" parame‐
204 ters specify the read and write timeout of the backend con‐
205 nection when this pattern is matched. All backends which
206 share the same pattern must have the same timeouts. If these
207 timeouts are entirely omitted for a pattern,
208 --backend-read-timeout and --backend-write-timeout are
209 used.
210 "group=<GROUP>" parameter specifies the name of group this
212 backend address belongs to. By default, it belongs to the un‐
213 named default group. The name of group is unique per
214 pattern. "group-weight=<N>" parameter specifies the weight
215 of the group. The higher weight gets more frequently se‐
216 lected by the load balancing algorithm. <N> must be [1,
217 256] inclusive. The weight 8 has 4 times more weight than 2.
218 <N> must be the same for all addresses which share the same
219 <GROUP>. If "group-weight" is omitted in an address, but the
220 other address which belongs to the same group specifies
221 "group-weight", its weight is used. If no
222 "group-weight" is specified for all addresses, the weight
223 of a group becomes 1. "group" and "group-weight" are ignored if
224 session affinity is enabled.
225 "weight=<N>" parameter specifies the weight of the backend
227 address inside a group which this address belongs to.
228 The higher weight gets more frequently selected by the load
229 balancing algorithm. <N> must be [1, 256] inclusive. The
230 weight 8 has 4 times more weight than weight 2. If this
231 parameter is omitted, weight becomes 1. "weight" is ig‐
232 nored if session affinity is enabled.
233 If "dnf" parameter is specified, an incoming request is not
235 forwarded to a backend and just consumed along with the re‐
236 quest body (actually a backend server never be contacted).
237 It is expected that the HTTP response is generated by mruby
238 script (see "mruby=<PATH>" parameter above). "dnf" is an abbre‐
239 viation of "do not forward".
240 Since ";" and ":" are used as delimiter, <PATTERN> must not
242 contain these characters. In order to include ":" in <PAT‐
243 TERN>, one has to specify "%3A" (which is percent-encoded
244 from of ":") instead. Since ";" has special meaning in
245 shell, the option value must be quoted.
246 Default: 127.0.0.1,80
248 -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]
250 Set frontend host and port. If <HOST> is '*', it assumes
251 all addresses including both IPv4 and IPv6. UNIX domain
252 socket can be specified by prefixing path name with "unix:"
253 (e.g., unix:/var/run/nghttpx.sock). This option can be used
254 multiple times to listen to multiple addresses.
255 This option can take 0 or more parameters, which are de‐
257 scribed below. Note that "api" and "healthmon" parame‐
258 ters are mutually exclusive.
259 Optionally, TLS can be disabled by specifying "no-tls" parame‐
261 ter. TLS is enabled by default.
262 If "sni-fwd" parameter is used, when performing a match to se‐
264 lect a backend server, SNI host name received from the client
265 is used instead of the request host. See --backend option
266 about the pattern match.
267 To make this frontend as API endpoint, specify "api" parame‐
269 ter. This is disabled by default. It is important to
270 limit the access to the API frontend. Otherwise, someone
271 may change the backend server, and break your services, or
272 expose confidential information to the outside the world.
273 To make this frontend as health monitor endpoint, specify
275 "healthmon" parameter. This is disabled by default. Any
276 requests which come through this address are replied with 200
277 HTTP status, without no body.
278 To accept PROXY protocol version 1 and 2 on frontend connec‐
280 tion, specify "proxyproto" parameter. This is disabled by
281 default.
282 To receive HTTP/3 (QUIC) traffic, specify "quic" parame‐
284 ter. It makes nghttpx listen on UDP port rather than TCP
285 port. UNIX domain socket, "api", and "healthmon" param‐
286 eters cannot be used with "quic" parameter.
287 Default: *,3000
289 --backlog=<N>
291 Set listen backlog size.
292 Default: 65536
294 --backend-address-family=(auto|IPv4|IPv6)
296 Specify address family of backend connections. If "auto"
297 is given, both IPv4 and IPv6 are considered. If "IPv4" is
298 given, only IPv4 address is considered. If "IPv6" is given,
299 only IPv6 address is considered.
300 Default: auto
302 --backend-http-proxy-uri=<URI>
304 Specify proxy URI in the form
305 http://[<USER>:<PASS>@]<PROXY>:<PORT>. If a proxy re‐
306 quires authentication, specify <USER> and <PASS>. Note
307 that they must be properly percent-encoded. This proxy is
308 used when the backend connection is HTTP/2. First, make a
309 CONNECT request to the proxy and it connects to the back‐
310 end on behalf of nghttpx. This forms tunnel. After that,
311 nghttpx performs SSL/TLS handshake with the downstream
312 through the tunnel. The timeouts when connecting and making
313 CONNECT request can be specified by
314 --backend-read-timeout and --backend-write-timeout options.
315 Performance
317 -n, --workers=<N>
318 Set the number of worker threads.
319 Default: 1
321 --single-thread
323 Run everything in one thread inside the worker process. This
324 feature is provided for better debugging experience,
325 or for the platforms which lack thread support. If
326 threading is disabled, this option is always enabled.
327 --read-rate=<SIZE>
329 Set maximum average read rate on frontend connection. Set‐
330 ting 0 to this option means read rate is unlimited.
331 Default: 0
333 --read-burst=<SIZE>
335 Set maximum read burst size on frontend connection. Set‐
336 ting 0 to this option means read burst size is unlimited.
337 Default: 0
339 --write-rate=<SIZE>
341 Set maximum average write rate on frontend connection. Set‐
342 ting 0 to this option means write rate is unlimited.
343 Default: 0
345 --write-burst=<SIZE>
347 Set maximum write burst size on frontend connection. Set‐
348 ting 0 to this option means write burst size is unlimited.
349 Default: 0
351 --worker-read-rate=<SIZE>
353 Set maximum average read rate on frontend connection per worker.
354 Setting 0 to this option means read rate is unlimited. Not
355 implemented yet.
356 Default: 0
358 --worker-read-burst=<SIZE>
360 Set maximum read burst size on frontend connection per worker.
361 Setting 0 to this option means read burst size is unlimited.
362 Not implemented yet.
363 Default: 0
365 --worker-write-rate=<SIZE>
367 Set maximum average write rate on frontend connection per
368 worker. Setting 0 to this option means write rate is unlim‐
369 ited. Not implemented yet.
370 Default: 0
372 --worker-write-burst=<SIZE>
374 Set maximum write burst size on frontend connection per worker.
375 Setting 0 to this option means write burst size is unlimited.
376 Not implemented yet.
377 Default: 0
379 --worker-frontend-connections=<N>
381 Set maximum number of simultaneous connections frontend ac‐
382 cepts. Setting 0 means unlimited.
383 Default: 0
385 --backend-connections-per-host=<N>
387 Set maximum number of backend concurrent connections (and/or
388 streams in case of HTTP/2) per origin host. This option is
389 meaningful when --http2-proxy option is used. The origin
390 host is determined by authority portion of request URI (or
391 :authority header field for HTTP/2). To limit the number
392 of connections per frontend for default
393 mode, use --backend-connections-per-frontend.
394 Default: 8
396 --backend-connections-per-frontend=<N>
398 Set maximum number of backend concurrent connections (and/or
399 streams in case of HTTP/2) per frontend. This option is
400 only used for default mode. 0 means unlimited. To limit
401 the number of connections per host with --http2-proxy
402 option, use --backend-connections-per-host.
403 Default: 0
405 --rlimit-nofile=<N>
407 Set maximum number of open files (RLIMIT_NOFILE) to <N>. If 0
408 is given, nghttpx does not set the limit.
409 Default: 0
411 --rlimit-memlock=<N>
413 Set maximum number of bytes of memory that may be locked into
414 RAM. If 0 is given, nghttpx does not set the limit.
415 Default: 0
417 --backend-request-buffer=<SIZE>
419 Set buffer size used to store backend request.
420 Default: 16K
422 --backend-response-buffer=<SIZE>
424 Set buffer size used to store backend response.
425 Default: 128K
427 --fastopen=<N>
429 Enables "TCP Fast Open" for the listening socket and limits
430 the maximum length for the queue of connections that have not
431 yet completed the three-way handshake. If value is 0 then fast
432 open is disabled.
433 Default: 0
435 --no-kqueue
437 Don't use kqueue. This option is only applicable for the
438 platforms which have kqueue. For other platforms, this option
439 will be simply ignored.
440 Timeout
442 --frontend-http2-read-timeout=<DURATION>
443 Specify read timeout for HTTP/2 frontend connection.
444 Default: 3m
446 --frontend-http3-read-timeout=<DURATION>
448 Specify read timeout for HTTP/3 frontend connection.
449 Default: 3m
451 --frontend-read-timeout=<DURATION>
453 Specify read timeout for HTTP/1.1 frontend connection.
454 Default: 1m
456 --frontend-write-timeout=<DURATION>
458 Specify write timeout for all frontend connections.
459 Default: 30s
461 --frontend-keep-alive-timeout=<DURATION>
463 Specify keep-alive timeout for frontend HTTP/1 connec‐
464 tion.
465 Default: 1m
467 --stream-read-timeout=<DURATION>
469 Specify read timeout for HTTP/2 streams. 0 means no time‐
470 out.
471 Default: 0
473 --stream-write-timeout=<DURATION>
475 Specify write timeout for HTTP/2 streams. 0 means no time‐
476 out.
477 Default: 1m
479 --backend-read-timeout=<DURATION>
481 Specify read timeout for backend connection.
482 Default: 1m
484 --backend-write-timeout=<DURATION>
486 Specify write timeout for backend connection.
487 Default: 30s
489 --backend-connect-timeout=<DURATION>
491 Specify timeout before establishing TCP connection to back‐
492 end.
493 Default: 30s
495 --backend-keep-alive-timeout=<DURATION>
497 Specify keep-alive timeout for backend HTTP/1 connec‐
498 tion.
499 Default: 2s
501 --listener-disable-timeout=<DURATION>
503 After accepting connection failed, connection listener is dis‐
504 abled for a given amount of time. Specifying 0 disables this
505 feature.
506 Default: 30s
508 --frontend-http2-setting-timeout=<DURATION>
510 Specify timeout before SETTINGS ACK is received from client.
511 Default: 10s
513 --backend-http2-settings-timeout=<DURATION>
515 Specify timeout before SETTINGS ACK is received from backend
516 server.
517 Default: 10s
519 --backend-max-backoff=<DURATION>
521 Specify maximum backoff interval. This is used when doing
522 health check against offline backend (see "fail" parameter in
523 --backend option). It is also used to limit the maximum
524 interval to temporarily disable backend when nghttpx failed
525 to connect to it. These intervals are calculated using expo‐
526 nential backoff, and consecutive failed attempts increase the
527 interval. This option caps its maximum value.
528 Default: 2m
530 SSL/TLS
532 --ciphers=<SUITE>
533 Set allowed cipher list for frontend connection. The format
534 of the string is described in OpenSSL ciphers(1). This option
535 sets cipher suites for TLSv1.2 or earlier. Use --tls13-ciphers
536 for TLSv1.3.
537 Default:
539 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
540 --tls13-ciphers=<SUITE>
542 Set allowed cipher list for frontend connection. The format
543 of the string is described in OpenSSL ciphers(1). This option
544 sets cipher suites for TLSv1.3. Use --ciphers for TLSv1.2
545 or earlier.
546 Default:
548 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
549 --client-ciphers=<SUITE>
551 Set allowed cipher list for backend connection. The format
552 of the string is described in OpenSSL ciphers(1). This option
553 sets cipher suites for TLSv1.2 or earlier. Use
554 --tls13-client-ciphers for TLSv1.3.
555 Default:
557 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
558 --tls13-client-ciphers=<SUITE>
560 Set allowed cipher list for backend connection. The format
561 of the string is described in OpenSSL ciphers(1). This option
562 sets cipher suites for TLSv1.3. Use
563 --tls13-client-ciphers for TLSv1.2 or earlier.
564 Default:
566 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
567 --ecdh-curves=<LIST>
569 Set supported curve list for frontend connections. <LIST>
570 is a colon separated list of curve NID or names in the prefer‐
571 ence order. The supported curves depend on the linked OpenSSL
572 library. This function requires OpenSSL >= 1.0.2.
573 Default: X25519:P-256:P-384:P-521
575 -k, --insecure
577 Don't verify backend server's certificate if TLS is enabled
578 for backend connections.
579 --cacert=<PATH>
581 Set path to trusted CA certificate file. It is used in backend
582 TLS connections to verify peer's certificate. It is also used
583 to verify OCSP response from the script set by
584 --fetch-ocsp-response-file. The file must be in PEM format.
585 It can contain multiple certificates. If the linked OpenSSL
586 is configured to load system wide certificates, they are
587 loaded at startup regardless of this option.
588 --private-key-passwd-file=<PATH>
590 Path to file that contains password for the server's private
591 key. If none is given and the private key is password pro‐
592 tected it'll be requested interactively.
593 --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
595 Specify additional certificate and private key file.
596 nghttpx will choose certificates based on the hostname indi‐
597 cated by client using TLS SNI extension. If nghttpx is built
598 with OpenSSL >= 1.0.2, the shared elliptic curves (e.g.,
599 P-256) between client and server are also taken into consider‐
600 ation. This allows nghttpx to send ECDSA certificate to mod‐
601 ern clients, while sending RSA based certificate to older
602 clients. This option can be used multiple times. To make
603 OCSP stapling work, <CERTPATH> must be absolute path.
604 Additional parameter can be specified in <PARAM>. The avail‐
606 able <PARAM> is "sct-dir=<DIR>".
607 "sct-dir=<DIR>" specifies the path to directory which con‐
609 tains *.sct files for TLS
610 signed_certificate_timestamp extension (RFC 6962). This feature
611 requires OpenSSL >= 1.0.2. See also --tls-sct-dir op‐
612 tion.
613 --dh-param-file=<PATH>
615 Path to file that contains DH parameters in PEM format. With‐
616 out this option, DHE cipher suites are not available.
617 --npn-list=<LIST>
619 Comma delimited list of ALPN protocol identifier sorted in the
620 order of preference. That means most desirable protocol comes
621 first. This is used in both ALPN and NPN. The parameter
622 must be delimited by a single comma only and any white spaces
623 are treated as a part of protocol string.
624 Default: h2,h2-16,h2-14,http/1.1
626 --verify-client
628 Require and verify client certificate.
629 --verify-client-cacert=<PATH>
631 Path to file that contains CA certificates to verify client
632 certificate. The file must be in PEM format. It can contain
633 multiple certificates.
634 --verify-client-tolerate-expired
636 Accept expired client certificate. Operator should handle
637 the expired client certificate by some means (e.g., mruby
638 script). Otherwise, this option might cause a security risk.
639 --client-private-key-file=<PATH>
641 Path to file that contains client private key used in backend
642 client authentication.
643 --client-cert-file=<PATH>
645 Path to file that contains client certificate used in backend
646 client authentication.
647 --tls-min-proto-version=<VER>
649 Specify minimum SSL/TLS protocol. The name matching is done in
650 case-insensitive manner. The versions between
651 --tls-min-proto-version and --tls-max-proto-version are en‐
652 abled. If the protocol list advertised by client does not
653 overlap this range, you will receive the error message "un‐
654 known protocol". If a protocol version lower than TLSv1.2 is
655 specified, make sure that the compatible ciphers are included
656 in --ciphers option. The default cipher list only includes
657 ciphers compatible with TLSv1.2 or above. The available ver‐
658 sions are: TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
659 Default: TLSv1.2
661 --tls-max-proto-version=<VER>
663 Specify maximum SSL/TLS protocol. The name matching is done in
664 case-insensitive manner. The versions between
665 --tls-min-proto-version and --tls-max-proto-version are en‐
666 abled. If the protocol list advertised by client does not
667 overlap this range, you will receive the error message "un‐
668 known protocol". The available versions are: TLSv1.3, TLSv1.2,
669 TLSv1.1, and TLSv1.0
670 Default: TLSv1.3
672 --tls-ticket-key-file=<PATH>
674 Path to file that contains random data to construct TLS session
675 ticket parameters. If aes-128-cbc is given in
676 --tls-ticket-key-cipher, the file must contain exactly 48
677 bytes. If aes-256-cbc is given in
678 --tls-ticket-key-cipher, the file must contain exactly 80
679 bytes. This options can be used repeatedly to specify
680 multiple ticket parameters. If several files are given, only
681 the first key is used to encrypt TLS session tickets. Other
682 keys are accepted but server will issue new session ticket
683 with first key. This allows session key rotation. Please
684 note that key rotation does not occur automatically. User
685 should rearrange files or change options values and restart
686 nghttpx gracefully. If opening or reading given file fails,
687 all loaded keys are discarded and it is treated as if none of
688 this option is given. If this option is not given or an error
689 occurred while opening or reading a file, key is generated ev‐
690 ery 1 hour internally and they are valid for 12 hours.
691 This is recommended if ticket key sharing between nghttpx
692 instances is not required.
693 --tls-ticket-key-memcached=<HOST>,<PORT>[;tls]
695 Specify address of memcached server to get TLS ticket keys
696 for session resumption. This enables shared TLS ticket key
697 between multiple nghttpx instances. nghttpx does not set TLS
698 ticket key to memcached. The external ticket key generator is
699 required. nghttpx just gets TLS ticket keys from memcached,
700 and use them, possibly replacing current set of keys. It is
701 up to extern TLS ticket key generator to rotate keys fre‐
702 quently. See "TLS SESSION TICKET RESUMPTION" section in man‐
703 ual page to know the data format in memcached entry. Option‐
704 ally, memcached connection can be encrypted with TLS by
705 specifying "tls" parameter.
706 --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6)
708 Specify address family of memcached connections to get TLS
709 ticket keys. If "auto" is given, both IPv4 and IPv6 are consid‐
710 ered. If "IPv4" is given, only IPv4 address is considered.
711 If "IPv6" is given, only IPv6 address is considered.
712 Default: auto
714 --tls-ticket-key-memcached-interval=<DURATION>
716 Set interval to get TLS ticket keys from memcached.
717 Default: 10m
719 --tls-ticket-key-memcached-max-retry=<N>
721 Set maximum number of consecutive retries before aban‐
722 doning TLS ticket key retrieval. If this number is reached,
723 the attempt is considered as failure, and "failure" count
724 is incremented by 1, which contributed to the
725 value controlled --tls-ticket-key-memcached-max-fail
726 option.
727 Default: 3
729 --tls-ticket-key-memcached-max-fail=<N>
731 Set maximum number of consecutive failure before dis‐
732 abling TLS ticket until next scheduled key retrieval.
733 Default: 2
735 --tls-ticket-key-cipher=<CIPHER>
737 Specify cipher to encrypt TLS session ticket. Specify either
738 aes-128-cbc or aes-256-cbc. By default, aes-128-cbc is
739 used.
740 --tls-ticket-key-memcached-cert-file=<PATH>
742 Path to client certificate for memcached connections to get TLS
743 ticket keys.
744 --tls-ticket-key-memcached-private-key-file=<PATH>
746 Path to client private key for memcached connections to get TLS
747 ticket keys.
748 --fetch-ocsp-response-file=<PATH>
750 Path to fetch-ocsp-response script file. It should be abso‐
751 lute path.
752 Default: /usr/local/share/nghttp2/fetch-ocsp-response
754 --ocsp-update-interval=<DURATION>
756 Set interval to update OCSP response cache.
757 Default: 4h
759 --ocsp-startup
761 Start accepting connections after initial attempts to get
762 OCSP responses finish. It does not matter some of the at‐
763 tempts fail. This feature is useful if OCSP responses
764 must be available before accepting connections.
765 --no-verify-ocsp
767 nghttpx does not verify OCSP response.
768 --no-ocsp
770 Disable OCSP stapling.
771 --tls-session-cache-memcached=<HOST>,<PORT>[;tls]
773 Specify address of memcached server to store session cache.
774 This enables shared session cache between multiple
775 nghttpx instances. Optionally, memcached connection can be
776 encrypted with TLS by specifying "tls" parameter.
777 --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6)
779 Specify address family of memcached connections to store session
780 cache. If "auto" is given, both IPv4 and IPv6 are considered.
781 If "IPv4" is given, only IPv4 address is considered. If "IPv6"
782 is given, only IPv6 address is considered.
783 Default: auto
785 --tls-session-cache-memcached-cert-file=<PATH>
787 Path to client certificate for memcached connections to store
788 session cache.
789 --tls-session-cache-memcached-private-key-file=<PATH>
791 Path to client private key for memcached connections to store
792 session cache.
793 --tls-dyn-rec-warmup-threshold=<SIZE>
795 Specify the threshold size for TLS dynamic record size behav‐
796 iour. During a TLS session, after the threshold number of
797 bytes have been written, the TLS record size will be increased
798 to the maximum allowed (16K). The max record size will con‐
799 tinue to be used on the active TLS session. After
800 --tls-dyn-rec-idle-timeout has elapsed, the record size is re‐
801 duced to 1300 bytes. Specify 0 to always use the maximum
802 record size, regardless of idle period. This behaviour ap‐
803 plies to all TLS based frontends, and TLS HTTP/2 backends.
804 Default: 1M
806 --tls-dyn-rec-idle-timeout=<DURATION>
808 Specify TLS dynamic record size behaviour timeout. See
809 --tls-dyn-rec-warmup-threshold for more information. This
810 behaviour applies to all TLS based frontends, and TLS HTTP/2
811 backends.
812 Default: 1s
814 --no-http2-cipher-block-list
816 Allow block listed cipher suite on frontend HTTP/2 connec‐
817 tion. See
818 https://tools.ietf.org/html/rfc7540#appendix-A for the com‐
819 plete HTTP/2 cipher suites block list.
820 --client-no-http2-cipher-block-list
822 Allow block listed cipher suite on backend HTTP/2 connec‐
823 tion. See
824 https://tools.ietf.org/html/rfc7540#appendix-A for the com‐
825 plete HTTP/2 cipher suites block list.
826 --tls-sct-dir=<DIR>
828 Specifies the directory where *.sct files exist. All *.sct
829 files in <DIR> are read, and sent as extension_data
830 of TLS signed_certificate_timestamp (RFC 6962) to client.
831 These *.sct files are for the certificate specified in
832 positional command-line argument <CERT>, or certificate op‐
833 tion in configuration file. For additional certificates,
834 use --subcert option. This option requires OpenSSL >= 1.0.2.
835 --psk-secrets=<PATH>
837 Read list of PSK identity and secrets from <PATH>. This is used
838 for frontend connection. The each line of input file is for‐
839 matted as <identity>:<hex-secret>, where <identity> is PSK
840 identity, and <hex-secret> is secret in hex. An empty line,
841 and line which starts with '#' are skipped. The default en‐
842 abled cipher list might not contain any PSK cipher suite. In
843 that case, desired PSK cipher suites must be enabled using
844 --ciphers option. The desired PSK cipher suite may be block
845 listed by HTTP/2. To use those cipher suites with
846 HTTP/2, consider to use --no-http2-cipher-block-list option.
847 But be aware its implications.
848 --client-psk-secrets=<PATH>
850 Read PSK identity and secrets from <PATH>. This is used for
851 backend connection. The each line of input file is formatted
852 as <identity>:<hex-secret>, where <identity> is PSK identity,
853 and <hex-secret> is secret in hex. An empty line, and line
854 which starts with '#' are skipped. The first identity and se‐
855 cret pair encountered is used. The default enabled cipher
856 list might not contain any PSK cipher suite. In that case,
857 desired PSK cipher suites must be enabled using
858 --client-ciphers option. The desired PSK cipher suite may be
859 block listed by HTTP/2. To use those cipher suites with
860 HTTP/2, consider to use --client-no-http2-cipher-block-list
861 option. But be aware its implications.
862 --tls-no-postpone-early-data
864 By default, except for QUIC connections, nghttpx post‐
865 pones forwarding HTTP requests sent in early data, including
866 those sent in partially in it, until TLS handshake fin‐
867 ishes. If all backend server recognizes "Early-Data" header
868 field, using this option makes nghttpx not postpone for‐
869 warding request and get full potential of 0-RTT data.
870 --tls-max-early-data=<SIZE>
872 Sets the maximum amount of 0-RTT data that server ac‐
873 cepts.
874 Default: 16K
876 HTTP/2
878 -c, --frontend-http2-max-concurrent-streams=<N>
879 Set the maximum number of the concurrent streams in one front‐
880 end HTTP/2 session.
881 Default: 100
883 --backend-http2-max-concurrent-streams=<N>
885 Set the maximum number of the concurrent streams in one backend
886 HTTP/2 session. This sets maximum number of concurrent
887 opened pushed streams. The maximum number of concurrent re‐
888 quests are set by a remote server.
889 Default: 100
891 --frontend-http2-window-size=<SIZE>
893 Sets the per-stream initial window size of HTTP/2 front‐
894 end connection.
895 Default: 65535
897 --frontend-http2-connection-window-size=<SIZE>
899 Sets the per-connection window size of HTTP/2 frontend connec‐
900 tion.
901 Default: 65535
903 --backend-http2-window-size=<SIZE>
905 Sets the initial window size of HTTP/2 backend connec‐
906 tion.
907 Default: 65535
909 --backend-http2-connection-window-size=<SIZE>
911 Sets the per-connection window size of HTTP/2 backend connec‐
912 tion.
913 Default: 2147483647
915 --http2-no-cookie-crumbling
917 Don't crumble cookie header field.
918 --padding=<N>
920 Add at most <N> bytes to a HTTP/2 frame payload as pad‐
921 ding. Specify 0 to disable padding. This option is meant for
922 debugging purpose and not intended to enhance protocol secu‐
923 rity.
924 --no-server-push
926 Disable HTTP/2 server push. Server push is supported by default
927 mode and HTTP/2 frontend via Link header field. It is also
928 supported if both frontend and backend are HTTP/2 in default
929 mode. In this case, server push from backend session is re‐
930 layed to frontend, and server push via Link header field is
931 also supported.
932 --frontend-http2-optimize-write-buffer-size
934 (Experimental) Enable write buffer size optimization in front‐
935 end HTTP/2 TLS connection. This optimization aims to reduce
936 write buffer size so that it only contains bytes which can
937 send immediately. This makes server more responsive to prior‐
938 itized HTTP/2 stream because the buffering of lower priority
939 stream is reduced. This option is only effective on recent
940 Linux platform.
941 --frontend-http2-optimize-window-size
943 (Experimental) Automatically tune connection level window
944 size of frontend HTTP/2 TLS connection. If this feature is
945 enabled, connection window size starts with the default win‐
946 dow size, 65535 bytes. nghttpx automatically adjusts
947 connection window size based on TCP receiving window size.
948 The maximum window size is capped by the value
949 specified by --frontend-http2-connection-window-size.
950 Since the stream is subject to stream level window size, it
951 should be adjusted using --frontend-http2-window-size option as
952 well. This option is only effective on recent Linux plat‐
953 form.
954 --frontend-http2-encoder-dynamic-table-size=<SIZE>
956 Specify the maximum dynamic table size of HPACK encoder in the
957 frontend HTTP/2 connection. The decoder (client) specifies the
958 maximum dynamic table size it accepts. Then the negotiated
959 dynamic table size is the minimum of this option value and the
960 value which client specified.
961 Default: 4K
963 --frontend-http2-decoder-dynamic-table-size=<SIZE>
965 Specify the maximum dynamic table size of HPACK decoder in the
966 frontend HTTP/2 connection.
967 Default: 4K
969 --backend-http2-encoder-dynamic-table-size=<SIZE>
971 Specify the maximum dynamic table size of HPACK encoder in the
972 backend HTTP/2 connection. The decoder (backend) specifies the
973 maximum dynamic table size it accepts. Then the negotiated
974 dynamic table size is the minimum of this option value and the
975 value which backend specified.
976 Default: 4K
978 --backend-http2-decoder-dynamic-table-size=<SIZE>
980 Specify the maximum dynamic table size of HPACK decoder in the
981 backend HTTP/2 connection.
982 Default: 4K
984 Mode
986 (default mode)
987 Accept HTTP/2, and HTTP/1.1 over SSL/TLS. "no-tls" parame‐
988 ter is used in --frontend option, accept HTTP/2 and HTTP/1.1
989 over cleartext TCP. The incoming HTTP/1.1 connection can be
990 upgraded to HTTP/2 through HTTP Upgrade.
991 -s, --http2-proxy
993 Like default mode, but enable forward proxy. This is so called
994 HTTP/2 proxy mode.
995 Logging
997 -L, --log-level=<LEVEL>
998 Set the severity level of log output. <LEVEL> must be one of
999 INFO, NOTICE, WARN, ERROR and FATAL.
1000 Default: NOTICE
1002 --accesslog-file=<PATH>
1004 Set path to write access log. To reopen file, send USR1 signal
1005 to nghttpx.
1006 --accesslog-syslog
1008 Send access log to syslog. If this option is used,
1009 --accesslog-file option is ignored.
1010 --accesslog-format=<FORMAT>
1012 Specify format string for access log. The default format
1013 is combined format. The following variables are available:
1014 • $remote_addr: client IP address.
1016 • $time_local: local time in Common Log format.
1018 • $time_iso8601: local time in ISO 8601 format.
1020 • $request: HTTP request line.
1022 • $status: HTTP response status code.
1024 • $body_bytes_sent: the number of bytes sent to client as re‐
1026 sponse body.
1027 • $http_<VAR>: value of HTTP request header <VAR> where '_' in
1029 <VAR> is replaced with '-'.
1030 • $remote_port: client port.
1032 • $server_port: server port.
1034 • $request_time: request processing time in seconds with mil‐
1036 liseconds resolution.
1037 • $pid: PID of the running process.
1039 • $alpn: ALPN identifier of the protocol which generates the re‐
1041 sponse. For HTTP/1, ALPN is always http/1.1, regardless of
1042 minor version.
1043 • $tls_cipher: cipher used for SSL/TLS connection.
1045 • $tls_client_fingerprint_sha256: SHA-256 fingerprint of client
1047 certificate.
1048 • $tls_client_fingerprint_sha1: SHA-1 fingerprint of client
1050 certificate.
1051 • $tls_client_subject_name: subject name in client cer‐
1053 tificate.
1054 • $tls_client_issuer_name: issuer name in client cer‐
1056 tificate.
1057 • $tls_client_serial: serial number in client cer‐
1059 tificate.
1060 • $tls_protocol: protocol for SSL/TLS connection.
1062 • $tls_session_id: session ID for SSL/TLS connection.
1064 • $tls_session_reused: "r" if SSL/TLS session was reused.
1066 Otherwise, "."
1067 • $tls_sni: SNI server name for SSL/TLS connection.
1069 • $backend_host: backend host used to fulfill the re‐
1071 quest. "-" if backend host is not available.
1072 • $backend_port: backend port used to fulfill the re‐
1074 quest. "-" if backend host is not available.
1075 • $method: HTTP method
1077 • $path: Request path including query. For CONNECT re‐
1079 quest, authority is recorded.
1080 • $path_without_query: $path up to the first '?' charac‐
1082 ter. For CONNECT request, authority is recorded.
1083 • $protocol_version: HTTP version (e.g., HTTP/1.1, HTTP/2)
1085 The variable can be enclosed by "{" and "}" for disam‐
1087 biguation (e.g., ${remote_addr}).
1088 Default: $remote_addr - - [$time_local] "$request" $status
1090 $body_bytes_sent "$http_referer" "$http_user_agent"
1091 --accesslog-write-early
1093 Write access log when response header fields are re‐
1094 ceived from backend rather than when request transac‐
1095 tion finishes.
1096 --errorlog-file=<PATH>
1098 Set path to write error log. To reopen file, send USR1 signal
1099 to nghttpx. stderr will be redirected to the error log file
1100 unless --errorlog-syslog is used.
1101 Default: /dev/stderr
1103 --errorlog-syslog
1105 Send error log to syslog. If this option is used,
1106 --errorlog-file option is ignored.
1107 --syslog-facility=<FACILITY>
1109 Set syslog facility to <FACILITY>.
1110 Default: daemon
1112 HTTP
1114 --add-x-forwarded-for
1115 Append X-Forwarded-For header field to the downstream re‐
1116 quest.
1117 --strip-incoming-x-forwarded-for
1119 Strip X-Forwarded-For header field from inbound client re‐
1120 quests.
1121 --no-add-x-forwarded-proto
1123 Don't append additional X-Forwarded-Proto header field to the
1124 backend request. If inbound client sets X-For‐
1125 warded-Proto, and
1126 --no-strip-incoming-x-forwarded-proto option is used, they
1127 are passed to the backend.
1128 --no-strip-incoming-x-forwarded-proto
1130 Don't strip X-Forwarded-Proto header field from inbound client
1131 requests.
1132 --add-forwarded=<LIST>
1134 Append RFC 7239 Forwarded header field with parameters speci‐
1135 fied in comma delimited list <LIST>. The supported parameters
1136 are "by", "for", "host", and "proto". By default, the value
1137 of "by" and "for" parameters are obfuscated string.
1138 See --forwarded-by and --forwarded-for options respec‐
1139 tively. Note that nghttpx does not translate non-standard
1140 X-Forwarded-* header fields into Forwarded header field, and
1141 vice versa.
1142 --strip-incoming-forwarded
1144 Strip Forwarded header field from inbound client re‐
1145 quests.
1146 --forwarded-by=(obfuscated|ip|<VALUE>)
1148 Specify the parameter value sent out with "by" parameter of For‐
1149 warded header field. If "obfuscated" is given, the string is
1150 randomly generated at startup. If "ip" is given, the inter‐
1151 face address of the connection, including port number, is
1152 sent with "by" parameter. In case of UNIX domain socket, "lo‐
1153 calhost" is used instead of address and port. User can also
1154 specify the static obfuscated string. The limitation is that it
1155 must start with "_", and only consists of character
1156 set [A-Za-z0-9._-], as described in RFC 7239.
1157 Default: obfuscated
1159 --forwarded-for=(obfuscated|ip)
1161 Specify the parameter value sent out with "for" parame‐
1162 ter of Forwarded header field. If "obfuscated" is given, the
1163 string is randomly generated for each client connection. If
1164 "ip" is given, the remote client address of the connection,
1165 without port number, is sent with "for" parameter. In case
1166 of UNIX domain socket, "localhost" is used instead of ad‐
1167 dress.
1168 Default: obfuscated
1170 --no-via
1172 Don't append to Via header field. If Via header field is re‐
1173 ceived, it is left unaltered.
1174 --no-strip-incoming-early-data
1176 Don't strip Early-Data header field from inbound client re‐
1177 quests.
1178 --no-location-rewrite
1180 Don't rewrite location header field in default mode. When
1181 --http2-proxy is used, location header field will not be al‐
1182 tered regardless of this option.
1183 --host-rewrite
1185 Rewrite host and :authority header fields in default mode.
1186 When --http2-proxy is used, these headers will not be altered
1187 regardless of this option.
1188 --altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1190 Specify protocol ID, port, host and origin of alter‐
1191 native service. <HOST>, <ORIGIN> and <PARAMS> are optional.
1192 Empty <HOST> and <ORIGIN> are allowed and they are treated
1193 as nothing is specified. They are advertised in alt-svc
1194 header field only in HTTP/1.1 frontend. This option can be
1195 used multiple times to specify multiple alternative services.
1196 Example: --altsvc="h2,443,,,ma=3600; persist=1'
1197 --http2-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1199 Just like --altsvc option, but this altsvc is only sent in
1200 HTTP/2 frontend.
1201 --add-request-header=<HEADER>
1203 Specify additional header field to add to request header set.
1204 This option just appends header field and won't replace any‐
1205 thing already set. This option can be used several times
1206 to specify multiple header fields. Example:
1207 --add-request-header="foo: bar"
1208 --add-response-header=<HEADER>
1210 Specify additional header field to add to response header
1211 set. This option just appends header field and won't replace
1212 anything already set. This option can be used several times
1213 to specify multiple header fields. Example:
1214 --add-response-header="foo: bar"
1215 --request-header-field-buffer=<SIZE>
1217 Set maximum buffer size for incoming HTTP request header field
1218 list. This is the sum of header name and value in bytes. If
1219 trailer fields exist, they are counted towards this number.
1220 Default: 64K
1222 --max-request-header-fields=<N>
1224 Set maximum number of incoming HTTP request header fields.
1225 If trailer fields exist, they are counted towards this num‐
1226 ber.
1227 Default: 100
1229 --response-header-field-buffer=<SIZE>
1231 Set maximum buffer size for incoming HTTP response header
1232 field list. This is the sum of header name and value in
1233 bytes. If trailer fields exist, they are counted towards
1234 this number.
1235 Default: 64K
1237 --max-response-header-fields=<N>
1239 Set maximum number of incoming HTTP response header fields.
1240 If trailer fields exist, they are counted towards this num‐
1241 ber.
1242 Default: 500
1244 --error-page=(<CODE>|*)=<PATH>
1246 Set file path to custom error page served when nghttpx origi‐
1247 nally generates HTTP error status code <CODE>. <CODE> must
1248 be greater than or equal to 400, and at most 599. If "*" is
1249 used instead of <CODE>, it matches all HTTP status code. If
1250 error status code comes from backend server, the custom error
1251 pages are not used.
1252 --server-name=<NAME>
1254 Change server response header field value to <NAME>.
1255 Default: nghttpx
1257 --no-server-rewrite
1259 Don't rewrite server header field in default mode. When
1260 --http2-proxy is used, these headers will not be altered regard‐
1261 less of this option.
1262 --redirect-https-port=<PORT>
1264 Specify the port number which appears in Location header field
1265 when redirect to HTTPS URI is made due to "redi‐
1266 rect-if-not-tls" parameter in --backend option.
1267 Default: 443
1269 API
1271 --api-max-request-body=<SIZE>
1272 Set the maximum size of request body for API request.
1273 Default: 32M
1275 DNS
1277 --dns-cache-timeout=<DURATION>
1278 Set duration that cached DNS results remain valid. Note that
1279 nghttpx caches the unsuccessful results as well.
1280 Default: 10s
1282 --dns-lookup-timeout=<DURATION>
1284 Set timeout that DNS server is given to respond to the initial
1285 DNS query. For the 2nd and later queries, server is given
1286 time based on this timeout, and it is scaled linearly.
1287 Default: 5s
1289 --dns-max-try=<N>
1291 Set the number of DNS query before nghttpx gives up name lookup.
1292 Default: 2
1294 --frontend-max-requests=<N>
1296 The number of requests that single frontend connection can
1297 process. For HTTP/2, this is the number of streams in one
1298 HTTP/2 connection. For HTTP/1, this is the number of keep
1299 alive requests. This is hint to nghttpx, and it may allow ad‐
1300 ditional few requests. The default value is unlimited.
1301 Debug
1303 --frontend-http2-dump-request-header=<PATH>
1304 Dumps request headers received by HTTP/2 frontend to the file
1305 denoted in <PATH>. The output is done in HTTP/1 header field
1306 format and each header block is followed by an empty line. This
1307 option is not thread safe and MUST NOT be used with option
1308 -n<N>, where <N> >= 2.
1309 --frontend-http2-dump-response-header=<PATH>
1311 Dumps response headers sent from HTTP/2 frontend to the file
1312 denoted in <PATH>. The output is done in HTTP/1 header field
1313 format and each header block is followed by an empty line. This
1314 option is not thread safe and MUST NOT be used with option
1315 -n<N>, where <N> >= 2.
1316 -o, --frontend-frame-debug
1318 Print HTTP/2 frames in frontend to stderr. This option is not
1319 thread safe and MUST NOT be used with option -n=N, where N
1320 >= 2.
1321 Process
1323 -D, --daemon
1324 Run in a background. If -D is used, the current working direc‐
1325 tory is changed to '/'.
1326 --pid-file=<PATH>
1328 Set path to save PID of this program.
1329 --user=<USER>
1331 Run this program as <USER>. This option is intended to be used
1332 to drop root privileges.
1333 --single-process
1335 Run this program in a single process mode for debugging pur‐
1336 pose. Without this option, nghttpx creates at least 2 pro‐
1337 cesses: main and worker processes. If this option is used,
1338 main and worker are unified into a single process.
1339 nghttpx still spawns additional process if neverbleed is
1340 used. In the single process mode, the signal handling fea‐
1341 ture is disabled.
1342 --max-worker-processes=<N>
1344 The maximum number of worker processes. nghttpx spawns new
1345 worker process when it reloads its configuration. The previ‐
1346 ous worker process enters graceful termination period and will
1347 terminate when it finishes handling the existing connec‐
1348 tions. However, if reloading configurations happen
1349 very frequently, the worker processes might be piled up if
1350 they take a bit long time to finish the existing connections.
1351 With this option, if the number of worker processes exceeds
1352 the given value, the oldest worker process is termi‐
1353 nated immediately. Specifying 0 means no limit and it is the
1354 default behaviour.
1355 --worker-process-grace-shutdown-period=<DURATION>
1357 Maximum period for a worker process to terminate grace‐
1358 fully. When a worker process enters in graceful shutdown
1359 period (e.g., when nghttpx reloads its configuration)
1360 and it does not finish handling the existing connections in
1361 the given period of time, it is immediately terminated. Speci‐
1362 fying 0 means no limit and it is the default behaviour.
1363 Scripting
1365 --mruby-file=<PATH>
1366 Set mruby script file
1367 --ignore-per-pattern-mruby-error
1369 Ignore mruby compile error for per-pattern mruby script file.
1370 If error occurred, it is treated as if no mruby file were
1371 specified for the pattern.
1372 HTTP/3 and QUIC
1374 --frontend-quic-idle-timeout=<DURATION>
1375 Specify an idle timeout for QUIC connection.
1376 Default: 30s
1378 --frontend-quic-debug-log
1380 Output QUIC debug log to /dev/stderr.
1381 --quic-bpf-program-file=<PATH>
1383 Specify a path to eBPF program file reuseport_kern.o to direct
1384 an incoming QUIC UDP datagram to a correct socket.
1385 Default: /usr/local/lib/nghttp2/reuseport_kern.o
1387 --frontend-quic-early-data
1389 Enable early data on frontend QUIC connections. nghttpx sends
1390 "Early-Data" header field to a backend server if a request is
1391 received in early data and handshake has not finished. All
1392 backend servers should deal with possibly replayed requests.
1393 --frontend-quic-qlog-dir=<DIR>
1395 Specify a directory where a qlog file is written for front‐
1396 end QUIC connections. A qlog file is created per each QUIC
1397 connection. The file name is ISO8601 basic format, followed
1398 by "-", server Source Connection ID and ".qlog".
1399 --frontend-quic-require-token
1401 Require an address validation token for a frontend QUIC connec‐
1402 tion. Server sends a token in Retry packet or NEW_TOKEN
1403 frame in the previous connection.
1404 --frontend-quic-congestion-controller=<CC>
1406 Specify a congestion controller algorithm for a frontend QUIC
1407 connection. <CC> should be either "cubic" or "bbr".
1408 Default: cubic
1410 --frontend-quic-secret-file=<PATH>
1412 Path to file that contains secure random data to be used as QUIC
1413 keying materials. It is used to derive keys for encrypting to‐
1414 kens and Connection IDs. It is not used to encrypt QUIC pack‐
1415 ets. Each line of this file must contain exactly 136
1416 bytes hex-encoded string (when decoded the byte string is 68
1417 bytes long). The first 2 bits of decoded byte string are
1418 used to identify the keying material. An empty line or a
1419 line which starts '#' is ignored. The file can contain more
1420 than one keying materials. Because the identifier is 2 bits,
1421 at most 4 keying materials are read and the remaining data is
1422 discarded. The first keying material in the file is primarily
1423 used for encryption and decryption for new connection. The
1424 other ones are used to decrypt data for the existing connec‐
1425 tions. Specifying multiple keying materials enables key ro‐
1426 tation. Please note that key rotation does not occur auto‐
1427 matically. User should update files or change options
1428 values and restart nghttpx gracefully. If opening or read‐
1429 ing given file fails, all loaded keying materials are dis‐
1430 carded and it is treated as if none of this option is given.
1431 If this option is not given or an error occurred while opening
1432 or reading a file, a keying material is generated inter‐
1433 nally on startup and reload.
1434 --quic-server-id=<HEXSTRING>
1436 Specify server ID encoded in Connection ID to identify this
1437 particular server instance. Connection ID is encrypted and
1438 this part is not visible in public. It must be 4 bytes long
1439 and must be encoded in hex string (which is 8 bytes long). If
1440 this option is omitted, a random server ID is generated
1441 on startup and configuration reload.
1442 --frontend-quic-initial-rtt=<DURATION>
1444 Specify the initial RTT of the frontend QUIC connection.
1445 Default: 333ms
1447 --no-quic-bpf
1449 Disable eBPF.
1450 --frontend-http3-window-size=<SIZE>
1452 Sets the per-stream initial window size of HTTP/3 front‐
1453 end connection.
1454 Default: 256K
1456 --frontend-http3-connection-window-size=<SIZE>
1458 Sets the per-connection window size of HTTP/3 frontend connec‐
1459 tion.
1460 Default: 1M
1462 --frontend-http3-max-window-size=<SIZE>
1464 Sets the maximum per-stream window size of HTTP/3 front‐
1465 end connection. The window size is adjusted based on the re‐
1466 ceiving rate of stream data. The initial value is the value
1467 specified by --frontend-http3-window-size and the window size
1468 grows up to <SIZE> bytes.
1469 Default: 6M
1471 --frontend-http3-max-connection-window-size=<SIZE>
1473 Sets the maximum per-connection window size of HTTP/3 front‐
1474 end connection. The window size is adjusted based on the re‐
1475 ceiving rate of stream data. The initial value is the
1476 value specified by
1477 --frontend-http3-connection-window-size and the window size
1478 grows up to <SIZE> bytes.
1479 Default: 8M
1481 --frontend-http3-max-concurrent-streams=<N>
1483 Set the maximum number of the concurrent streams in one front‐
1484 end HTTP/3 connection.
1485 Default: 100
1487 Misc
1489 --conf=<PATH>
1490 Load configuration from <PATH>. Please note that nghttpx
1491 always tries to read the default configuration file if --conf
1492 is not given.
1493 Default: /etc/nghttpx/nghttpx.conf
1495 --include=<PATH>
1497 Load additional configurations from <PATH>. File <PATH> is
1498 read when configuration parser encountered this option.
1499 This option can be used multiple times, or even recursively.
1500 -v, --version
1502 Print version and exit.
1503 -h, --help
1505 Print this help and exit.
1506 The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
1508 * 1024). Units are K, M and G (powers of 1024).
1509 The <DURATION> argument is an integer and an optional unit (e.g., 1s is
1511 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
1512 (hours, minutes, seconds and milliseconds, respectively). If a unit is
1513 omitted, a second is used as unit.
1514
1516 /etc/nghttpx/nghttpx.conf
1517 The default configuration file path nghttpx searches at startup.
1518 The configuration file path can be changed using --conf option.
1519 Those lines which are staring # are treated as comment.
1521 The option name in the configuration file is the long com‐
1523 mand-line option name with leading -- stripped (e.g., frontend).
1524 Put = between option name and value. Don't put extra leading or
1525 trailing spaces.
1526 When specifying arguments including characters which have spe‐
1528 cial meaning to a shell, we usually use quotes so that shell
1529 does not interpret them. When writing this configuration file,
1530 quotes for this purpose must not be used. For example, specify
1531 additional request header field, do this:
1532 add-request-header=foo: bar
1534 instead of:
1536 add-request-header="foo: bar"
1538 The options which do not take argument in the command-line take
1540 argument in the configuration file. Specify yes as an argument
1541 (e.g., http2-proxy=yes). If other string is given, it is ig‐
1542 nored.
1543 To specify private key and certificate file which are given as
1545 positional arguments in command-line, use private-key-file and
1546 certificate-file.
1547 --conf option cannot be used in the configuration file and will
1549 be ignored if specified.
1550 Error log
1552 Error log is written to stderr by default. It can be configured
1553 using --errorlog-file. The format of log message is as follows:
1554 <datetime> <main-pid> <current-pid> <thread-id> <level> (<file‐
1556 name>:<line>) <msg>
1557 <datetime>
1559 It is a combination of date and time when the log is
1560 written. It is in ISO 8601 format.
1561 <main-pid>
1563 It is a main process ID.
1564 <current-pid>
1566 It is a process ID which writes this log.
1567 <thread-id>
1569 It is a thread ID which writes this log. It would be
1570 unique within <current-pid>.
1571 <filename> and <line>
1573 They are source file name, and line number which produce
1574 this log.
1575 <msg> It is a log message body.
1577
1579 SIGQUIT
1580 Shutdown gracefully. First accept pending connections and stop
1581 accepting connection. After all connections are handled,
1582 nghttpx exits.
1583 SIGHUP Reload configuration file given in --conf.
1585 SIGUSR1
1587 Reopen log files.
1588 SIGUSR2
1590 Fork and execute nghttpx. It will execute the binary in the same
1591 path with same command-line arguments and environment variables. As
1592 of nghttpx version 1.20.0, the new main process sends SIGQUIT to the
1593 original main process when it is ready to serve requests. For the
1594 earlier versions of nghttpx, user has to send SIGQUIT to the origi‐
1595 nal main process.
1596 The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
1598 is usually used to execute new binary, and the main process is newly
1599 spawned. On the other hand, the latter just reloads configuration
1600 file, and the same main process continues to exist.
1601 NOTE:
1603 nghttpx consists of multiple processes: one process for processing
1604 these signals, and another one for processing requests. The former
1605 spawns the latter. The former is called main process, and the lat‐
1606 ter is called worker process. If neverbleed is enabled, the worker
1607 process spawns neverbleed daemon process which does RSA key process‐
1608 ing. The above signal must be sent to the main process. If the
1609 other processes received one of them, it is ignored. This behaviour
1610 of these processes may change in the future release. In other
1611 words, in the future release, the processes other than main process
1612 may terminate upon the reception of these signals. Therefore these
1613 signals should not be sent to the processes other than main process.
1614
1616 nghttpx supports HTTP/2 server push in default mode with Link header
1617 field. nghttpx looks for Link header field (RFC 5988) in response
1618 headers from backend server and extracts URI-reference with parameter
1619 rel=preload (see preload) and pushes those URIs to the frontend client.
1620 Here is a sample Link header field to initiate server push:
1621 Link: </fonts/font.woff>; rel=preload
1623 Link: </css/theme.css>; rel=preload
1624 Currently, the following restriction is applied for server push:
1626 1. The associated stream must have method "GET" or "POST". The associ‐
1628 ated stream's status code must be 200.
1629 This limitation may be loosened in the future release.
1631 nghttpx also supports server push if both frontend and backend are
1633 HTTP/2 in default mode. In this case, in addition to server push via
1634 Link header field, server push from backend is forwarded to frontend
1635 HTTP/2 session.
1636 HTTP/2 server push will be disabled if --http2-proxy is used.
1638
1640 nghttpx supports UNIX domain socket with a filename for both frontend
1641 and backend connections.
1642 Please note that current nghttpx implementation does not delete a
1644 socket with a filename. And on start up, if nghttpx detects that the
1645 specified socket already exists in the file system, nghttpx first
1646 deletes it. However, if SIGUSR2 is used to execute new binary and both
1647 old and new configurations use same filename, new binary does not
1648 delete the socket and continues to use it.
1649
1651 OCSP query is done using external Python script fetch-ocsp-response,
1652 which has been originally developed in Perl as part of h2o project (‐
1653 https://github.com/h2o/h2o), and was translated into Python.
1654 The script file is usually installed under $(prefix)/share/nghttp2/ di‐
1656 rectory. The actual path to script can be customized using
1657 --fetch-ocsp-response-file option.
1658 If OCSP query is failed, previous OCSP response, if any, is continued
1660 to be used.
1661 --fetch-ocsp-response-file option provides wide range of possibility to
1663 manage OCSP response. It can take an arbitrary script or executable.
1664 The requirement is that it supports the command-line interface of
1665 fetch-ocsp-response script, and it must return a valid DER encoded OCSP
1666 response on success. It must return exit code 0 on success, and 75 for
1667 temporary error, and the other error code for generic failure. For
1668 large cluster of servers, it is not efficient for each server to per‐
1669 form OCSP query using fetch-ocsp-response. Instead, you can retrieve
1670 OCSP response in some way, and store it in a disk or a shared database.
1671 Then specify a program in --fetch-ocsp-response-file to fetch it from
1672 those stores. This could provide a way to share the OCSP response be‐
1673 tween fleet of servers, and also any OCSP query strategy can be applied
1674 which may be beyond the ability of nghttpx itself or fetch-ocsp-re‐
1675 sponse script.
1676
1678 nghttpx supports TLS session resumption through both session ID and
1679 session ticket.
1680 SESSION ID RESUMPTION
1682 By default, session ID is shared by all worker threads.
1683 If --tls-session-cache-memcached is given, nghttpx will insert serial‐
1685 ized session data to memcached with nghttpx:tls-session-cache: + lower‐
1686 case hex string of session ID as a memcached entry key, with expiry
1687 time 12 hours. Session timeout is set to 12 hours.
1688 By default, connections to memcached server are not encrypted. To en‐
1690 able encryption, use tls keyword in --tls-session-cache-memcached op‐
1691 tion.
1692 TLS SESSION TICKET RESUMPTION
1694 By default, session ticket is shared by all worker threads. The auto‐
1695 matic key rotation is also enabled by default. Every an hour, new en‐
1696 cryption key is generated, and previous encryption key becomes decryp‐
1697 tion only key. We set session timeout to 12 hours, and thus we keep at
1698 most 12 keys.
1699 If --tls-ticket-key-memcached is given, encryption keys are retrieved
1701 from memcached. nghttpx just reads keys from memcached; one has to de‐
1702 ploy key generator program to update keys frequently (e.g., every 1
1703 hour). The example key generator tlsticketupdate.go is available under
1704 contrib directory in nghttp2 archive. The memcached entry key is
1705 nghttpx:tls-ticket-key. The data format stored in memcached is the bi‐
1706 nary format described below:
1707 +--------------+-------+----------------+
1709 | VERSION (4) |LEN (2)|KEY(48 or 80) ...
1710 +--------------+-------+----------------+
1711 ^ |
1712 | |
1713 +------------------------+
1714 (LEN, KEY) pair can be repeated
1715 All numbers in the above figure is bytes. All integer fields are net‐
1717 work byte order.
1718 First 4 bytes integer VERSION field, which must be 1. The 2 bytes in‐
1720 teger LEN field gives the length of following KEY field, which contains
1721 key. If --tls-ticket-key-cipher=aes-128-cbc is used, LEN must be 48.
1722 If --tls-ticket-key-cipher=aes-256-cbc is used, LEN must be 80. LEN
1723 and KEY pair can be repeated multiple times to store multiple keys.
1724 The key appeared first is used as encryption key. All the remaining
1725 keys are used as decryption only.
1726 By default, connections to memcached server are not encrypted. To en‐
1728 able encryption, use tls keyword in --tls-ticket-key-memcached option.
1729 If --tls-ticket-key-file is given, encryption key is read from the
1731 given file. In this case, nghttpx does not rotate key automatically.
1732 To rotate key, one has to restart nghttpx (see SIGNALS).
1733
1735 nghttpx supports TLS signed_certificate_timestamp extension (RFC 6962).
1736 The relevant options are --tls-sct-dir and sct-dir parameter in
1737 --subcert. They takes a directory, and nghttpx reads all files whose
1738 extension is .sct under the directory. The *.sct files are encoded as
1739 SignedCertificateTimestamp struct described in section 3.2 of RFC
1740 69662. This format is the same one used by nginx-ct and mod_ssl_ct.
1741 ct-submit can be used to submit certificates to log servers, and obtain
1742 the SignedCertificateTimestamp struct which can be used with nghttpx.
1743
1745 WARNING:
1746 The current mruby extension API is experimental and not frozen. The
1747 API is subject to change in the future release.
1748 WARNING:
1750 Almost all string value returned from method, or attribute is a
1751 fresh new mruby string, which involves memory allocation, and
1752 copies. Therefore, it is strongly recommended to store a return
1753 value in a local variable, and use it, instead of calling method or
1754 accessing attribute repeatedly.
1755 nghttpx allows users to extend its capability using mruby scripts.
1757 nghttpx has 2 hook points to execute mruby script: request phase and
1758 response phase. The request phase hook is invoked after all request
1759 header fields are received from client. The response phase hook is in‐
1760 voked after all response header fields are received from backend
1761 server. These hooks allows users to modify header fields, or common
1762 HTTP variables, like authority or request path, and even return custom
1763 response without forwarding request to backend servers.
1764 There are 2 levels of mruby script invocations: global and per-pattern.
1766 The global mruby script is set by --mruby-file option and is called for
1767 all requests. The per-pattern mruby script is set by "mruby" parameter
1768 in -b option. It is invoked for a request which matches the particular
1769 pattern. The order of hook invocation is: global request phase hook,
1770 per-pattern request phase hook, per-pattern response phase hook, and
1771 finally global response phase hook. If a hook returns a response, any
1772 later hooks are not invoked. The global request hook is invoked before
1773 the pattern matching is made and changing request path may affect the
1774 pattern matching.
1775 Please note that request and response hooks of per-pattern mruby script
1777 for a single request might not come from the same script. This might
1778 happen after a request hook is executed, backend failed for some rea‐
1779 son, and at the same time, backend configuration is replaced by API re‐
1780 quest, and then the request uses new configuration on retry. The re‐
1781 sponse hook from new configuration, if it is specified, will be in‐
1782 voked.
1783 The all mruby script will be evaluated once per thread on startup, and
1785 it must instantiate object and evaluate it as the return value (e.g.,
1786 App.new). This object is called app object. If app object defines
1787 on_req method, it is called with Nghttpx::Env object on request hook.
1788 Similarly, if app object defines on_resp method, it is called with
1789 Nghttpx::Env object on response hook. For each method invocation, user
1790 can can access Nghttpx::Request and Nghttpx::Response objects via
1791 Nghttpx::Env#req and Nghttpx::Env#resp respectively.
1792 Nghttpx::REQUEST_PHASE
1794 Constant to represent request phase.
1795 Nghttpx::RESPONSE_PHASE
1797 Constant to represent response phase.
1798 class Nghttpx::Env
1800 Object to represent current request specific context.
1801 attribute [R] req
1803 Return Request object.
1804 attribute [R] resp
1806 Return Response object.
1807 attribute [R] ctx
1809 Return Ruby hash object. It persists until request fin‐
1810 ishes. So values set in request phase hook can be re‐
1811 trieved in response phase hook.
1812 attribute [R] phase
1814 Return the current phase.
1815 attribute [R] remote_addr
1817 Return IP address of a remote client. If connection is
1818 made via UNIX domain socket, this returns the string "lo‐
1819 calhost".
1820 attribute [R] server_addr
1822 Return address of server that accepted the connection.
1823 This is a string which specified in --frontend option,
1824 excluding port number, and not a resolved IP address.
1825 For UNIX domain socket, this is a path to UNIX domain
1826 socket.
1827 attribute [R] server_port
1829 Return port number of the server frontend which accepted
1830 the connection from client.
1831 attribute [R] tls_used
1833 Return true if TLS is used on the connection.
1834 attribute [R] tls_sni
1836 Return the TLS SNI value which client sent in this con‐
1837 nection.
1838 attribute [R] tls_client_fingerprint_sha256
1840 Return the SHA-256 fingerprint of a client certificate.
1841 attribute [R] tls_client_fingerprint_sha1
1843 Return the SHA-1 fingerprint of a client certificate.
1844 attribute [R] tls_client_issuer_name
1846 Return the issuer name of a client certificate.
1847 attribute [R] tls_client_subject_name
1849 Return the subject name of a client certificate.
1850 attribute [R] tls_client_serial
1852 Return the serial number of a client certificate.
1853 attribute [R] tls_client_not_before
1855 Return the start date of a client certificate in seconds
1856 since the epoch.
1857 attribute [R] tls_client_not_after
1859 Return the end date of a client certificate in seconds
1860 since the epoch.
1861 attribute [R] tls_cipher
1863 Return a TLS cipher negotiated in this connection.
1864 attribute [R] tls_protocol
1866 Return a TLS protocol version negotiated in this connec‐
1867 tion.
1868 attribute [R] tls_session_id
1870 Return a session ID for this connection in hex string.
1871 attribute [R] tls_session_reused
1873 Return true if, and only if a SSL/TLS session is reused.
1874 attribute [R] alpn
1876 Return ALPN identifier negotiated in this connection.
1877 attribute [R] tls_handshake_finished
1879 Return true if SSL/TLS handshake has finished. If it re‐
1880 turns false in the request phase hook, the request is re‐
1881 ceived in TLSv1.3 early data (0-RTT) and might be vulner‐
1882 able to the replay attack. nghttpx will send Early-Data
1883 header field to backend servers to indicate this.
1884 class Nghttpx::Request
1886 Object to represent request from client. The modification to
1887 Request object is allowed only in request phase hook.
1888 attribute [R] http_version_major
1890 Return HTTP major version.
1891 attribute [R] http_version_minor
1893 Return HTTP minor version.
1894 attribute [R/W] method
1896 HTTP method. On assignment, copy of given value is as‐
1897 signed. We don't accept arbitrary method name. We will
1898 document them later, but well known methods, like GET,
1899 PUT and POST, are all supported.
1900 attribute [R/W] authority
1902 Authority (i.e., example.org), including optional port
1903 component . On assignment, copy of given value is as‐
1904 signed.
1905 attribute [R/W] scheme
1907 Scheme (i.e., http, https). On assignment, copy of given
1908 value is assigned.
1909 attribute [R/W] path
1911 Request path, including query component (i.e., /in‐
1912 dex.html). On assignment, copy of given value is as‐
1913 signed. The path does not include authority component of
1914 URI. This may include query component. nghttpx makes
1915 certain normalization for path. It decodes percent-en‐
1916 coding for unreserved characters (see
1917 https://tools.ietf.org/html/rfc3986#section-2.3), and re‐
1918 solves ".." and ".". But it may leave characters which
1919 should be percent-encoded as is. So be careful when com‐
1920 paring path against desired string.
1921 attribute [R] headers
1923 Return Ruby hash containing copy of request header
1924 fields. Changing values in returned hash does not change
1925 request header fields actually used in request process‐
1926 ing. Use Nghttpx::Request#add_header or
1927 Nghttpx::Request#set_header to change request header
1928 fields.
1929 add_header(key, value)
1931 Add header entry associated with key. The value can be
1932 single string or array of string. It does not replace
1933 any existing values associated with key.
1934 set_header(key, value)
1936 Set header entry associated with key. The value can be
1937 single string or array of string. It replaces any exist‐
1938 ing values associated with key.
1939 clear_headers()
1941 Clear all existing request header fields.
1942 push(uri)
1944 Initiate to push resource identified by uri. Only HTTP/2
1945 protocol supports this feature. For the other protocols,
1946 this method is noop. uri can be absolute URI, absolute
1947 path or relative path to the current request. For abso‐
1948 lute or relative path, scheme and authority are inherited
1949 from the current request. Currently, method is always
1950 GET. nghttpx will issue request to backend servers to
1951 fulfill this request. The request and response phase
1952 hooks will be called for pushed resource as well.
1953 class Nghttpx::Response
1955 Object to represent response from backend server.
1956 attribute [R] http_version_major
1958 Return HTTP major version.
1959 attribute [R] http_version_minor
1961 Return HTTP minor version.
1962 attribute [R/W] status
1964 HTTP status code. It must be in the range [200, 999],
1965 inclusive. The non-final status code is not supported in
1966 mruby scripting at the moment.
1967 attribute [R] headers
1969 Return Ruby hash containing copy of response header
1970 fields. Changing values in returned hash does not change
1971 response header fields actually used in response process‐
1972 ing. Use Nghttpx::Response#add_header or
1973 Nghttpx::Response#set_header to change response header
1974 fields.
1975 add_header(key, value)
1977 Add header entry associated with key. The value can be
1978 single string or array of string. It does not replace
1979 any existing values associated with key.
1980 set_header(key, value)
1982 Set header entry associated with key. The value can be
1983 single string or array of string. It replaces any exist‐
1984 ing values associated with key.
1985 clear_headers()
1987 Clear all existing response header fields.
1988 return(body)
1990 Return custom response body to a client. When this
1991 method is called in request phase hook, the request is
1992 not forwarded to the backend, and response phase hook for
1993 this request will not be invoked. When this method is
1994 called in response phase hook, response from backend
1995 server is canceled and discarded. The status code and
1996 response header fields should be set before using this
1997 method. To set status code, use
1998 Nghttpx::Response#status. If status code is not set, 200
1999 is used. To set response header fields,
2000 Nghttpx::Response#add_header and
2001 Nghttpx::Response#set_header. When this method is in‐
2002 voked in response phase hook, the response headers are
2003 filled with the ones received from backend server. To
2004 send completely custom header fields, first call
2005 Nghttpx::Response#clear_headers to erase all existing
2006 header fields, and then add required header fields. It
2007 is an error to call this method twice for a given re‐
2008 quest.
2009 send_info(status, headers)
2011 Send non-final (informational) response to a client.
2012 status must be in the range [100, 199], inclusive. head‐
2013 ers is a hash containing response header fields. Its key
2014 must be a string, and the associated value must be either
2015 string or array of strings. Since this is not a final
2016 response, even if this method is invoked, request is
2017 still forwarded to a backend unless
2018 Nghttpx::Response#return is called. This method can be
2019 called multiple times. It cannot be called after
2020 Nghttpx::Response#return is called.
2021 MRUBY EXAMPLES
2023 Modify request path:
2024 class App
2026 def on_req(env)
2027 env.req.path = "/apps#{env.req.path}"
2028 end
2029 end
2030 App.new
2032 Don't forget to instantiate and evaluate object at the last line.
2034 Restrict permission of viewing a content to a specific client ad‐
2036 dresses:
2037 class App
2039 def on_req(env)
2040 allowed_clients = ["127.0.0.1", "::1"]
2041 if env.req.path.start_with?("/log/") &&
2043 !allowed_clients.include?(env.remote_addr) then
2044 env.resp.status = 404
2045 env.resp.return "permission denied"
2046 end
2047 end
2048 end
2049 App.new
2051
2053 nghttpx exposes API endpoints to manipulate it via HTTP based API. By
2054 default, API endpoint is disabled. To enable it, add a dedicated
2055 frontend for API using --frontend option with "api" parameter. All re‐
2056 quests which come from this frontend address, will be treated as API
2057 request.
2058 The response is normally JSON dictionary, and at least includes the
2060 following keys:
2061 status The status of the request processing. The following values are
2063 defined:
2064 Success
2066 The request was successful.
2067 Failure
2069 The request was failed. No change has been made.
2070 code HTTP status code
2072 Additionally, depending on the API endpoint, data key may be present,
2074 and its value contains the API endpoint specific data.
2075 We wrote "normally", since nghttpx may return ordinal HTML response in
2077 some cases where the error has occurred before reaching API endpoint
2078 (e.g., header field is too large).
2079 The following section describes available API endpoints.
2081 POST /api/v1beta1/backendconfig
2083 This API replaces the current backend server settings with the re‐
2084 quested ones. The request method should be POST, but PUT is also ac‐
2085 ceptable. The request body must be nghttpx configuration file format.
2086 For configuration file format, see FILES section. The line separator
2087 inside the request body must be single LF (0x0A). Currently, only
2088 backend option is parsed, the others are simply ignored. The semantics
2089 of this API is replace the current backend with the backend options in
2090 request body. Describe the desired set of backend severs, and nghttpx
2091 makes it happen. If there is no backend option is found in request
2092 body, the current set of backend is replaced with the backend option's
2093 default value, which is 127.0.0.1,80.
2094 The replacement is done instantly without breaking existing connections
2096 or requests. It also avoids any process creation as is the case with
2097 hot swapping with signals.
2098 The one limitation is that only numeric IP address is allowed in
2100 backend in request body unless "dns" parameter is used while non nu‐
2101 meric hostname is allowed in command-line or configuration file is read
2102 using --conf.
2103 GET /api/v1beta1/configrevision
2105 This API returns configuration revision of the current nghttpx. The
2106 configuration revision is opaque string, and it changes after each
2107 reloading by SIGHUP. With this API, an external application knows that
2108 whether nghttpx has finished reloading its configuration by comparing
2109 the configuration revisions between before and after reloading. It is
2110 recommended to disable persistent (keep-alive) connection for this pur‐
2111 pose in order to avoid to send a request using the reused connection
2112 which may bound to an old process.
2113 This API returns response including data key. Its value is JSON ob‐
2115 ject, and it contains at least the following key:
2116 configRevision
2118 The configuration revision of the current nghttpx
2119
2121 nghttp(1), nghttpd(1), h2load(1)
2122
2124 Tatsuhiro Tsujikawa
2125
2127 2012, 2015, 2016, Tatsuhiro Tsujikawa
21281.46.0 Oct 19, 2021 NGHTTPX(1)