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 --backend-request-buffer=<SIZE>
413 Set buffer size used to store backend request.
414 Default: 16K
416 --backend-response-buffer=<SIZE>
418 Set buffer size used to store backend response.
419 Default: 128K
421 --fastopen=<N>
423 Enables "TCP Fast Open" for the listening socket and limits
424 the maximum length for the queue of connections that have not
425 yet completed the three-way handshake. If value is 0 then fast
426 open is disabled.
427 Default: 0
429 --no-kqueue
431 Don't use kqueue. This option is only applicable for the
432 platforms which have kqueue. For other platforms, this option
433 will be simply ignored.
434 Timeout
436 --frontend-http2-read-timeout=<DURATION>
437 Specify read timeout for HTTP/2 frontend connection.
438 Default: 3m
440 --frontend-http3-read-timeout=<DURATION>
442 Specify read timeout for HTTP/3 frontend connection.
443 Default: 3m
445 --frontend-read-timeout=<DURATION>
447 Specify read timeout for HTTP/1.1 frontend connection.
448 Default: 1m
450 --frontend-write-timeout=<DURATION>
452 Specify write timeout for all frontend connections.
453 Default: 30s
455 --frontend-keep-alive-timeout=<DURATION>
457 Specify keep-alive timeout for frontend HTTP/1 connec‐
458 tion.
459 Default: 1m
461 --stream-read-timeout=<DURATION>
463 Specify read timeout for HTTP/2 streams. 0 means no time‐
464 out.
465 Default: 0
467 --stream-write-timeout=<DURATION>
469 Specify write timeout for HTTP/2 streams. 0 means no time‐
470 out.
471 Default: 1m
473 --backend-read-timeout=<DURATION>
475 Specify read timeout for backend connection.
476 Default: 1m
478 --backend-write-timeout=<DURATION>
480 Specify write timeout for backend connection.
481 Default: 30s
483 --backend-connect-timeout=<DURATION>
485 Specify timeout before establishing TCP connection to back‐
486 end.
487 Default: 30s
489 --backend-keep-alive-timeout=<DURATION>
491 Specify keep-alive timeout for backend HTTP/1 connec‐
492 tion.
493 Default: 2s
495 --listener-disable-timeout=<DURATION>
497 After accepting connection failed, connection listener is dis‐
498 abled for a given amount of time. Specifying 0 disables this
499 feature.
500 Default: 30s
502 --frontend-http2-setting-timeout=<DURATION>
504 Specify timeout before SETTINGS ACK is received from client.
505 Default: 10s
507 --backend-http2-settings-timeout=<DURATION>
509 Specify timeout before SETTINGS ACK is received from backend
510 server.
511 Default: 10s
513 --backend-max-backoff=<DURATION>
515 Specify maximum backoff interval. This is used when doing
516 health check against offline backend (see "fail" parameter in
517 --backend option). It is also used to limit the maximum
518 interval to temporarily disable backend when nghttpx failed
519 to connect to it. These intervals are calculated using expo‐
520 nential backoff, and consecutive failed attempts increase the
521 interval. This option caps its maximum value.
522 Default: 2m
524 SSL/TLS
526 --ciphers=<SUITE>
527 Set allowed cipher list for frontend connection. The format
528 of the string is described in OpenSSL ciphers(1). This option
529 sets cipher suites for TLSv1.2 or earlier. Use --tls13-ciphers
530 for TLSv1.3.
531 Default:
533 ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256
534 --tls13-ciphers=<SUITE>
536 Set allowed cipher list for frontend connection. The format
537 of the string is described in OpenSSL ciphers(1). This option
538 sets cipher suites for TLSv1.3. Use --ciphers for TLSv1.2
539 or earlier.
540 Default:
542 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
543 --client-ciphers=<SUITE>
545 Set allowed cipher list for backend connection. The format
546 of the string is described in OpenSSL ciphers(1). This option
547 sets cipher suites for TLSv1.2 or earlier. Use
548 --tls13-client-ciphers for TLSv1.3.
549 Default:
551 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
552 --tls13-client-ciphers=<SUITE>
554 Set allowed cipher list for backend connection. The format
555 of the string is described in OpenSSL ciphers(1). This option
556 sets cipher suites for TLSv1.3. Use
557 --tls13-client-ciphers for TLSv1.2 or earlier.
558 Default:
560 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
561 --ecdh-curves=<LIST>
563 Set supported curve list for frontend connections. <LIST>
564 is a colon separated list of curve NID or names in the prefer‐
565 ence order. The supported curves depend on the linked OpenSSL
566 library. This function requires OpenSSL >= 1.0.2.
567 Default: X25519:P-256:P-384:P-521
569 -k, --insecure
571 Don't verify backend server's certificate if TLS is enabled
572 for backend connections.
573 --cacert=<PATH>
575 Set path to trusted CA certificate file. It is used in backend
576 TLS connections to verify peer's certificate. It is also used
577 to verify OCSP response from the script set by
578 --fetch-ocsp-response-file. The file must be in PEM format.
579 It can contain multiple certificates. If the linked OpenSSL
580 is configured to load system wide certificates, they are
581 loaded at startup regardless of this option.
582 --private-key-passwd-file=<PATH>
584 Path to file that contains password for the server's private
585 key. If none is given and the private key is password pro‐
586 tected it'll be requested interactively.
587 --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
589 Specify additional certificate and private key file.
590 nghttpx will choose certificates based on the hostname indi‐
591 cated by client using TLS SNI extension. If nghttpx is built
592 with OpenSSL >= 1.0.2, the shared elliptic curves (e.g.,
593 P-256) between client and server are also taken into consider‐
594 ation. This allows nghttpx to send ECDSA certificate to mod‐
595 ern clients, while sending RSA based certificate to older
596 clients. This option can be used multiple times. To make
597 OCSP stapling work, <CERTPATH> must be absolute path.
598 Additional parameter can be specified in <PARAM>. The avail‐
600 able <PARAM> is "sct-dir=<DIR>".
601 "sct-dir=<DIR>" specifies the path to directory which con‐
603 tains *.sct files for TLS
604 signed_certificate_timestamp extension (RFC 6962). This feature
605 requires OpenSSL >= 1.0.2. See also --tls-sct-dir op‐
606 tion.
607 --dh-param-file=<PATH>
609 Path to file that contains DH parameters in PEM format. With‐
610 out this option, DHE cipher suites are not available.
611 --npn-list=<LIST>
613 Comma delimited list of ALPN protocol identifier sorted in the
614 order of preference. That means most desirable protocol comes
615 first. This is used in both ALPN and NPN. The parameter
616 must be delimited by a single comma only and any white spaces
617 are treated as a part of protocol string.
618 Default: h2,h2-16,h2-14,http/1.1
620 --verify-client
622 Require and verify client certificate.
623 --verify-client-cacert=<PATH>
625 Path to file that contains CA certificates to verify client
626 certificate. The file must be in PEM format. It can contain
627 multiple certificates.
628 --verify-client-tolerate-expired
630 Accept expired client certificate. Operator should handle
631 the expired client certificate by some means (e.g., mruby
632 script). Otherwise, this option might cause a security risk.
633 --client-private-key-file=<PATH>
635 Path to file that contains client private key used in backend
636 client authentication.
637 --client-cert-file=<PATH>
639 Path to file that contains client certificate used in backend
640 client authentication.
641 --tls-min-proto-version=<VER>
643 Specify minimum SSL/TLS protocol. The name matching is done in
644 case-insensitive manner. The versions between
645 --tls-min-proto-version and --tls-max-proto-version are en‐
646 abled. If the protocol list advertised by client does not
647 overlap this range, you will receive the error message "un‐
648 known protocol". If a protocol version lower than TLSv1.2 is
649 specified, make sure that the compatible ciphers are included
650 in --ciphers option. The default cipher list only includes
651 ciphers compatible with TLSv1.2 or above. The available ver‐
652 sions are: TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
653 Default: TLSv1.2
655 --tls-max-proto-version=<VER>
657 Specify maximum SSL/TLS protocol. The name matching is done in
658 case-insensitive manner. The versions between
659 --tls-min-proto-version and --tls-max-proto-version are en‐
660 abled. If the protocol list advertised by client does not
661 overlap this range, you will receive the error message "un‐
662 known protocol". The available versions are: TLSv1.3, TLSv1.2,
663 TLSv1.1, and TLSv1.0
664 Default: TLSv1.3
666 --tls-ticket-key-file=<PATH>
668 Path to file that contains random data to construct TLS session
669 ticket parameters. If aes-128-cbc is given in
670 --tls-ticket-key-cipher, the file must contain exactly 48
671 bytes. If aes-256-cbc is given in
672 --tls-ticket-key-cipher, the file must contain exactly 80
673 bytes. This options can be used repeatedly to specify
674 multiple ticket parameters. If several files are given, only
675 the first key is used to encrypt TLS session tickets. Other
676 keys are accepted but server will issue new session ticket
677 with first key. This allows session key rotation. Please
678 note that key rotation does not occur automatically. User
679 should rearrange files or change options values and restart
680 nghttpx gracefully. If opening or reading given file fails,
681 all loaded keys are discarded and it is treated as if none of
682 this option is given. If this option is not given or an error
683 occurred while opening or reading a file, key is generated ev‐
684 ery 1 hour internally and they are valid for 12 hours.
685 This is recommended if ticket key sharing between nghttpx
686 instances is not required.
687 --tls-ticket-key-memcached=<HOST>,<PORT>[;tls]
689 Specify address of memcached server to get TLS ticket keys
690 for session resumption. This enables shared TLS ticket key
691 between multiple nghttpx instances. nghttpx does not set TLS
692 ticket key to memcached. The external ticket key generator is
693 required. nghttpx just gets TLS ticket keys from memcached,
694 and use them, possibly replacing current set of keys. It is
695 up to extern TLS ticket key generator to rotate keys fre‐
696 quently. See "TLS SESSION TICKET RESUMPTION" section in man‐
697 ual page to know the data format in memcached entry. Option‐
698 ally, memcached connection can be encrypted with TLS by
699 specifying "tls" parameter.
700 --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6)
702 Specify address family of memcached connections to get TLS
703 ticket keys. If "auto" is given, both IPv4 and IPv6 are consid‐
704 ered. If "IPv4" is given, only IPv4 address is considered.
705 If "IPv6" is given, only IPv6 address is considered.
706 Default: auto
708 --tls-ticket-key-memcached-interval=<DURATION>
710 Set interval to get TLS ticket keys from memcached.
711 Default: 10m
713 --tls-ticket-key-memcached-max-retry=<N>
715 Set maximum number of consecutive retries before aban‐
716 doning TLS ticket key retrieval. If this number is reached,
717 the attempt is considered as failure, and "failure" count
718 is incremented by 1, which contributed to the
719 value controlled --tls-ticket-key-memcached-max-fail
720 option.
721 Default: 3
723 --tls-ticket-key-memcached-max-fail=<N>
725 Set maximum number of consecutive failure before dis‐
726 abling TLS ticket until next scheduled key retrieval.
727 Default: 2
729 --tls-ticket-key-cipher=<CIPHER>
731 Specify cipher to encrypt TLS session ticket. Specify either
732 aes-128-cbc or aes-256-cbc. By default, aes-128-cbc is
733 used.
734 --tls-ticket-key-memcached-cert-file=<PATH>
736 Path to client certificate for memcached connections to get TLS
737 ticket keys.
738 --tls-ticket-key-memcached-private-key-file=<PATH>
740 Path to client private key for memcached connections to get TLS
741 ticket keys.
742 --fetch-ocsp-response-file=<PATH>
744 Path to fetch-ocsp-response script file. It should be abso‐
745 lute path.
746 Default: /usr/local/share/nghttp2/fetch-ocsp-response
748 --ocsp-update-interval=<DURATION>
750 Set interval to update OCSP response cache.
751 Default: 4h
753 --ocsp-startup
755 Start accepting connections after initial attempts to get
756 OCSP responses finish. It does not matter some of the at‐
757 tempts fail. This feature is useful if OCSP responses
758 must be available before accepting connections.
759 --no-verify-ocsp
761 nghttpx does not verify OCSP response.
762 --no-ocsp
764 Disable OCSP stapling.
765 --tls-session-cache-memcached=<HOST>,<PORT>[;tls]
767 Specify address of memcached server to store session cache.
768 This enables shared session cache between multiple
769 nghttpx instances. Optionally, memcached connection can be
770 encrypted with TLS by specifying "tls" parameter.
771 --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6)
773 Specify address family of memcached connections to store session
774 cache. If "auto" is given, both IPv4 and IPv6 are considered.
775 If "IPv4" is given, only IPv4 address is considered. If "IPv6"
776 is given, only IPv6 address is considered.
777 Default: auto
779 --tls-session-cache-memcached-cert-file=<PATH>
781 Path to client certificate for memcached connections to store
782 session cache.
783 --tls-session-cache-memcached-private-key-file=<PATH>
785 Path to client private key for memcached connections to store
786 session cache.
787 --tls-dyn-rec-warmup-threshold=<SIZE>
789 Specify the threshold size for TLS dynamic record size behav‐
790 iour. During a TLS session, after the threshold number of
791 bytes have been written, the TLS record size will be increased
792 to the maximum allowed (16K). The max record size will con‐
793 tinue to be used on the active TLS session. After
794 --tls-dyn-rec-idle-timeout has elapsed, the record size is re‐
795 duced to 1300 bytes. Specify 0 to always use the maximum
796 record size, regardless of idle period. This behaviour ap‐
797 plies to all TLS based frontends, and TLS HTTP/2 backends.
798 Default: 1M
800 --tls-dyn-rec-idle-timeout=<DURATION>
802 Specify TLS dynamic record size behaviour timeout. See
803 --tls-dyn-rec-warmup-threshold for more information. This
804 behaviour applies to all TLS based frontends, and TLS HTTP/2
805 backends.
806 Default: 1s
808 --no-http2-cipher-block-list
810 Allow block listed cipher suite on frontend HTTP/2 connec‐
811 tion. See
812 https://tools.ietf.org/html/rfc7540#appendix-A for the com‐
813 plete HTTP/2 cipher suites block list.
814 --client-no-http2-cipher-block-list
816 Allow block listed cipher suite on backend 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 --tls-sct-dir=<DIR>
822 Specifies the directory where *.sct files exist. All *.sct
823 files in <DIR> are read, and sent as extension_data
824 of TLS signed_certificate_timestamp (RFC 6962) to client.
825 These *.sct files are for the certificate specified in
826 positional command-line argument <CERT>, or certificate op‐
827 tion in configuration file. For additional certificates,
828 use --subcert option. This option requires OpenSSL >= 1.0.2.
829 --psk-secrets=<PATH>
831 Read list of PSK identity and secrets from <PATH>. This is used
832 for frontend connection. The each line of input file is for‐
833 matted as <identity>:<hex-secret>, where <identity> is PSK
834 identity, and <hex-secret> is secret in hex. An empty line,
835 and line which starts with '#' are skipped. The default en‐
836 abled cipher list might not contain any PSK cipher suite. In
837 that case, desired PSK cipher suites must be enabled using
838 --ciphers option. The desired PSK cipher suite may be block
839 listed by HTTP/2. To use those cipher suites with
840 HTTP/2, consider to use --no-http2-cipher-block-list option.
841 But be aware its implications.
842 --client-psk-secrets=<PATH>
844 Read PSK identity and secrets from <PATH>. This is used for
845 backend connection. The each line of input file is formatted
846 as <identity>:<hex-secret>, where <identity> is PSK identity,
847 and <hex-secret> is secret in hex. An empty line, and line
848 which starts with '#' are skipped. The first identity and se‐
849 cret pair encountered is used. The default enabled cipher
850 list might not contain any PSK cipher suite. In that case,
851 desired PSK cipher suites must be enabled using
852 --client-ciphers option. The desired PSK cipher suite may be
853 block listed by HTTP/2. To use those cipher suites with
854 HTTP/2, consider to use --client-no-http2-cipher-block-list
855 option. But be aware its implications.
856 --tls-no-postpone-early-data
858 By default, except for QUIC connections, nghttpx post‐
859 pones forwarding HTTP requests sent in early data, including
860 those sent in partially in it, until TLS handshake fin‐
861 ishes. If all backend server recognizes "Early-Data" header
862 field, using this option makes nghttpx not postpone for‐
863 warding request and get full potential of 0-RTT data.
864 --tls-max-early-data=<SIZE>
866 Sets the maximum amount of 0-RTT data that server ac‐
867 cepts.
868 Default: 16K
870 HTTP/2
872 -c, --frontend-http2-max-concurrent-streams=<N>
873 Set the maximum number of the concurrent streams in one front‐
874 end HTTP/2 session.
875 Default: 100
877 --backend-http2-max-concurrent-streams=<N>
879 Set the maximum number of the concurrent streams in one backend
880 HTTP/2 session. This sets maximum number of concurrent
881 opened pushed streams. The maximum number of concurrent re‐
882 quests are set by a remote server.
883 Default: 100
885 --frontend-http2-window-size=<SIZE>
887 Sets the per-stream initial window size of HTTP/2 front‐
888 end connection.
889 Default: 65535
891 --frontend-http2-connection-window-size=<SIZE>
893 Sets the per-connection window size of HTTP/2 frontend connec‐
894 tion.
895 Default: 65535
897 --backend-http2-window-size=<SIZE>
899 Sets the initial window size of HTTP/2 backend connec‐
900 tion.
901 Default: 65535
903 --backend-http2-connection-window-size=<SIZE>
905 Sets the per-connection window size of HTTP/2 backend connec‐
906 tion.
907 Default: 2147483647
909 --http2-no-cookie-crumbling
911 Don't crumble cookie header field.
912 --padding=<N>
914 Add at most <N> bytes to a HTTP/2 frame payload as pad‐
915 ding. Specify 0 to disable padding. This option is meant for
916 debugging purpose and not intended to enhance protocol secu‐
917 rity.
918 --no-server-push
920 Disable HTTP/2 server push. Server push is supported by default
921 mode and HTTP/2 frontend via Link header field. It is also
922 supported if both frontend and backend are HTTP/2 in default
923 mode. In this case, server push from backend session is re‐
924 layed to frontend, and server push via Link header field is
925 also supported.
926 --frontend-http2-optimize-write-buffer-size
928 (Experimental) Enable write buffer size optimization in front‐
929 end HTTP/2 TLS connection. This optimization aims to reduce
930 write buffer size so that it only contains bytes which can
931 send immediately. This makes server more responsive to prior‐
932 itized HTTP/2 stream because the buffering of lower priority
933 stream is reduced. This option is only effective on recent
934 Linux platform.
935 --frontend-http2-optimize-window-size
937 (Experimental) Automatically tune connection level window
938 size of frontend HTTP/2 TLS connection. If this feature is
939 enabled, connection window size starts with the default win‐
940 dow size, 65535 bytes. nghttpx automatically adjusts
941 connection window size based on TCP receiving window size.
942 The maximum window size is capped by the value
943 specified by --frontend-http2-connection-window-size.
944 Since the stream is subject to stream level window size, it
945 should be adjusted using --frontend-http2-window-size option as
946 well. This option is only effective on recent Linux plat‐
947 form.
948 --frontend-http2-encoder-dynamic-table-size=<SIZE>
950 Specify the maximum dynamic table size of HPACK encoder in the
951 frontend HTTP/2 connection. The decoder (client) specifies the
952 maximum dynamic table size it accepts. Then the negotiated
953 dynamic table size is the minimum of this option value and the
954 value which client specified.
955 Default: 4K
957 --frontend-http2-decoder-dynamic-table-size=<SIZE>
959 Specify the maximum dynamic table size of HPACK decoder in the
960 frontend HTTP/2 connection.
961 Default: 4K
963 --backend-http2-encoder-dynamic-table-size=<SIZE>
965 Specify the maximum dynamic table size of HPACK encoder in the
966 backend HTTP/2 connection. The decoder (backend) specifies the
967 maximum dynamic table size it accepts. Then the negotiated
968 dynamic table size is the minimum of this option value and the
969 value which backend specified.
970 Default: 4K
972 --backend-http2-decoder-dynamic-table-size=<SIZE>
974 Specify the maximum dynamic table size of HPACK decoder in the
975 backend HTTP/2 connection.
976 Default: 4K
978 Mode
980 (default mode)
981 Accept HTTP/2, and HTTP/1.1 over SSL/TLS. "no-tls" parame‐
982 ter is used in --frontend option, accept HTTP/2 and HTTP/1.1
983 over cleartext TCP. The incoming HTTP/1.1 connection can be
984 upgraded to HTTP/2 through HTTP Upgrade.
985 -s, --http2-proxy
987 Like default mode, but enable forward proxy. This is so called
988 HTTP/2 proxy mode.
989 Logging
991 -L, --log-level=<LEVEL>
992 Set the severity level of log output. <LEVEL> must be one of
993 INFO, NOTICE, WARN, ERROR and FATAL.
994 Default: NOTICE
996 --accesslog-file=<PATH>
998 Set path to write access log. To reopen file, send USR1 signal
999 to nghttpx.
1000 --accesslog-syslog
1002 Send access log to syslog. If this option is used,
1003 --accesslog-file option is ignored.
1004 --accesslog-format=<FORMAT>
1006 Specify format string for access log. The default format
1007 is combined format. The following variables are available:
1008 • $remote_addr: client IP address.
1010 • $time_local: local time in Common Log format.
1012 • $time_iso8601: local time in ISO 8601 format.
1014 • $request: HTTP request line.
1016 • $status: HTTP response status code.
1018 • $body_bytes_sent: the number of bytes sent to client as re‐
1020 sponse body.
1021 • $http_<VAR>: value of HTTP request header <VAR> where '_' in
1023 <VAR> is replaced with '-'.
1024 • $remote_port: client port.
1026 • $server_port: server port.
1028 • $request_time: request processing time in seconds with mil‐
1030 liseconds resolution.
1031 • $pid: PID of the running process.
1033 • $alpn: ALPN identifier of the protocol which generates the re‐
1035 sponse. For HTTP/1, ALPN is always http/1.1, regardless of
1036 minor version.
1037 • $tls_cipher: cipher used for SSL/TLS connection.
1039 • $tls_client_fingerprint_sha256: SHA-256 fingerprint of client
1041 certificate.
1042 • $tls_client_fingerprint_sha1: SHA-1 fingerprint of client
1044 certificate.
1045 • $tls_client_subject_name: subject name in client cer‐
1047 tificate.
1048 • $tls_client_issuer_name: issuer name in client cer‐
1050 tificate.
1051 • $tls_client_serial: serial number in client cer‐
1053 tificate.
1054 • $tls_protocol: protocol for SSL/TLS connection.
1056 • $tls_session_id: session ID for SSL/TLS connection.
1058 • $tls_session_reused: "r" if SSL/TLS session was reused.
1060 Otherwise, "."
1061 • $tls_sni: SNI server name for SSL/TLS connection.
1063 • $backend_host: backend host used to fulfill the re‐
1065 quest. "-" if backend host is not available.
1066 • $backend_port: backend port used to fulfill the re‐
1068 quest. "-" if backend host is not available.
1069 • $method: HTTP method
1071 • $path: Request path including query. For CONNECT re‐
1073 quest, authority is recorded.
1074 • $path_without_query: $path up to the first '?' charac‐
1076 ter. For CONNECT request, authority is recorded.
1077 • $protocol_version: HTTP version (e.g., HTTP/1.1, HTTP/2)
1079 The variable can be enclosed by "{" and "}" for disam‐
1081 biguation (e.g., ${remote_addr}).
1082 Default: $remote_addr - - [$time_local] "$request" $status
1084 $body_bytes_sent "$http_referer" "$http_user_agent"
1085 --accesslog-write-early
1087 Write access log when response header fields are re‐
1088 ceived from backend rather than when request transac‐
1089 tion finishes.
1090 --errorlog-file=<PATH>
1092 Set path to write error log. To reopen file, send USR1 signal
1093 to nghttpx. stderr will be redirected to the error log file
1094 unless --errorlog-syslog is used.
1095 Default: /dev/stderr
1097 --errorlog-syslog
1099 Send error log to syslog. If this option is used,
1100 --errorlog-file option is ignored.
1101 --syslog-facility=<FACILITY>
1103 Set syslog facility to <FACILITY>.
1104 Default: daemon
1106 HTTP
1108 --add-x-forwarded-for
1109 Append X-Forwarded-For header field to the downstream re‐
1110 quest.
1111 --strip-incoming-x-forwarded-for
1113 Strip X-Forwarded-For header field from inbound client re‐
1114 quests.
1115 --no-add-x-forwarded-proto
1117 Don't append additional X-Forwarded-Proto header field to the
1118 backend request. If inbound client sets X-For‐
1119 warded-Proto, and
1120 --no-strip-incoming-x-forwarded-proto option is used, they
1121 are passed to the backend.
1122 --no-strip-incoming-x-forwarded-proto
1124 Don't strip X-Forwarded-Proto header field from inbound client
1125 requests.
1126 --add-forwarded=<LIST>
1128 Append RFC 7239 Forwarded header field with parameters speci‐
1129 fied in comma delimited list <LIST>. The supported parameters
1130 are "by", "for", "host", and "proto". By default, the value
1131 of "by" and "for" parameters are obfuscated string.
1132 See --forwarded-by and --forwarded-for options respec‐
1133 tively. Note that nghttpx does not translate non-standard
1134 X-Forwarded-* header fields into Forwarded header field, and
1135 vice versa.
1136 --strip-incoming-forwarded
1138 Strip Forwarded header field from inbound client re‐
1139 quests.
1140 --forwarded-by=(obfuscated|ip|<VALUE>)
1142 Specify the parameter value sent out with "by" parameter of For‐
1143 warded header field. If "obfuscated" is given, the string is
1144 randomly generated at startup. If "ip" is given, the inter‐
1145 face address of the connection, including port number, is
1146 sent with "by" parameter. In case of UNIX domain socket, "lo‐
1147 calhost" is used instead of address and port. User can also
1148 specify the static obfuscated string. The limitation is that it
1149 must start with "_", and only consists of character
1150 set [A-Za-z0-9._-], as described in RFC 7239.
1151 Default: obfuscated
1153 --forwarded-for=(obfuscated|ip)
1155 Specify the parameter value sent out with "for" parame‐
1156 ter of Forwarded header field. If "obfuscated" is given, the
1157 string is randomly generated for each client connection. If
1158 "ip" is given, the remote client address of the connection,
1159 without port number, is sent with "for" parameter. In case
1160 of UNIX domain socket, "localhost" is used instead of ad‐
1161 dress.
1162 Default: obfuscated
1164 --no-via
1166 Don't append to Via header field. If Via header field is re‐
1167 ceived, it is left unaltered.
1168 --no-strip-incoming-early-data
1170 Don't strip Early-Data header field from inbound client re‐
1171 quests.
1172 --no-location-rewrite
1174 Don't rewrite location header field in default mode. When
1175 --http2-proxy is used, location header field will not be al‐
1176 tered regardless of this option.
1177 --host-rewrite
1179 Rewrite host and :authority header fields in default mode.
1180 When --http2-proxy is used, these headers will not be altered
1181 regardless of this option.
1182 --altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1184 Specify protocol ID, port, host and origin of alter‐
1185 native service. <HOST>, <ORIGIN> and <PARAMS> are optional.
1186 Empty <HOST> and <ORIGIN> are allowed and they are treated
1187 as nothing is specified. They are advertised in alt-svc
1188 header field only in HTTP/1.1 frontend. This option can be
1189 used multiple times to specify multiple alternative services.
1190 Example: --altsvc="h2,443,,,ma=3600; persist=1'
1191 --http2-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1193 Just like --altsvc option, but this altsvc is only sent in
1194 HTTP/2 frontend.
1195 --add-request-header=<HEADER>
1197 Specify additional header field to add to request header set.
1198 This option just appends header field and won't replace any‐
1199 thing already set. This option can be used several times
1200 to specify multiple header fields. Example:
1201 --add-request-header="foo: bar"
1202 --add-response-header=<HEADER>
1204 Specify additional header field to add to response header
1205 set. This option just appends header field and won't replace
1206 anything already set. This option can be used several times
1207 to specify multiple header fields. Example:
1208 --add-response-header="foo: bar"
1209 --request-header-field-buffer=<SIZE>
1211 Set maximum buffer size for incoming HTTP request header field
1212 list. This is the sum of header name and value in bytes. If
1213 trailer fields exist, they are counted towards this number.
1214 Default: 64K
1216 --max-request-header-fields=<N>
1218 Set maximum number of incoming HTTP request header fields.
1219 If trailer fields exist, they are counted towards this num‐
1220 ber.
1221 Default: 100
1223 --response-header-field-buffer=<SIZE>
1225 Set maximum buffer size for incoming HTTP response header
1226 field list. This is the sum of header name and value in
1227 bytes. If trailer fields exist, they are counted towards
1228 this number.
1229 Default: 64K
1231 --max-response-header-fields=<N>
1233 Set maximum number of incoming HTTP response header fields.
1234 If trailer fields exist, they are counted towards this num‐
1235 ber.
1236 Default: 500
1238 --error-page=(<CODE>|*)=<PATH>
1240 Set file path to custom error page served when nghttpx origi‐
1241 nally generates HTTP error status code <CODE>. <CODE> must
1242 be greater than or equal to 400, and at most 599. If "*" is
1243 used instead of <CODE>, it matches all HTTP status code. If
1244 error status code comes from backend server, the custom error
1245 pages are not used.
1246 --server-name=<NAME>
1248 Change server response header field value to <NAME>.
1249 Default: nghttpx
1251 --no-server-rewrite
1253 Don't rewrite server header field in default mode. When
1254 --http2-proxy is used, these headers will not be altered regard‐
1255 less of this option.
1256 --redirect-https-port=<PORT>
1258 Specify the port number which appears in Location header field
1259 when redirect to HTTPS URI is made due to "redi‐
1260 rect-if-not-tls" parameter in --backend option.
1261 Default: 443
1263 API
1265 --api-max-request-body=<SIZE>
1266 Set the maximum size of request body for API request.
1267 Default: 32M
1269 DNS
1271 --dns-cache-timeout=<DURATION>
1272 Set duration that cached DNS results remain valid. Note that
1273 nghttpx caches the unsuccessful results as well.
1274 Default: 10s
1276 --dns-lookup-timeout=<DURATION>
1278 Set timeout that DNS server is given to respond to the initial
1279 DNS query. For the 2nd and later queries, server is given
1280 time based on this timeout, and it is scaled linearly.
1281 Default: 5s
1283 --dns-max-try=<N>
1285 Set the number of DNS query before nghttpx gives up name lookup.
1286 Default: 2
1288 --frontend-max-requests=<N>
1290 The number of requests that single frontend connection can
1291 process. For HTTP/2, this is the number of streams in one
1292 HTTP/2 connection. For HTTP/1, this is the number of keep
1293 alive requests. This is hint to nghttpx, and it may allow ad‐
1294 ditional few requests. The default value is unlimited.
1295 Debug
1297 --frontend-http2-dump-request-header=<PATH>
1298 Dumps request headers received by HTTP/2 frontend to the file
1299 denoted in <PATH>. The output is done in HTTP/1 header field
1300 format and each header block is followed by an empty line. This
1301 option is not thread safe and MUST NOT be used with option
1302 -n<N>, where <N> >= 2.
1303 --frontend-http2-dump-response-header=<PATH>
1305 Dumps response headers sent from HTTP/2 frontend to the file
1306 denoted in <PATH>. The output is done in HTTP/1 header field
1307 format and each header block is followed by an empty line. This
1308 option is not thread safe and MUST NOT be used with option
1309 -n<N>, where <N> >= 2.
1310 -o, --frontend-frame-debug
1312 Print HTTP/2 frames in frontend to stderr. This option is not
1313 thread safe and MUST NOT be used with option -n=N, where N
1314 >= 2.
1315 Process
1317 -D, --daemon
1318 Run in a background. If -D is used, the current working direc‐
1319 tory is changed to '/'.
1320 --pid-file=<PATH>
1322 Set path to save PID of this program.
1323 --user=<USER>
1325 Run this program as <USER>. This option is intended to be used
1326 to drop root privileges.
1327 --single-process
1329 Run this program in a single process mode for debugging pur‐
1330 pose. Without this option, nghttpx creates at least 2 pro‐
1331 cesses: main and worker processes. If this option is used,
1332 main and worker are unified into a single process.
1333 nghttpx still spawns additional process if neverbleed is
1334 used. In the single process mode, the signal handling fea‐
1335 ture is disabled.
1336 Scripting
1338 --mruby-file=<PATH>
1339 Set mruby script file
1340 --ignore-per-pattern-mruby-error
1342 Ignore mruby compile error for per-pattern mruby script file.
1343 If error occurred, it is treated as if no mruby file were
1344 specified for the pattern.
1345 HTTP/3 and QUIC
1347 --frontend-quic-idle-timeout=<DURATION>
1348 Specify an idle timeout for QUIC connection.
1349 Default: 30s
1351 --frontend-quic-debug-log
1353 Output QUIC debug log to /dev/stderr.
1354 --quic-bpf-program-file=<PATH>
1356 Specify a path to eBPF program file reuseport_kern.o to direct
1357 an incoming QUIC UDP datagram to a correct socket.
1358 Default: /usr/local/lib/nghttp2/reuseport_kern.o
1360 --frontend-quic-early-data
1362 Enable early data on frontend QUIC connections. nghttpx sends
1363 "Early-Data" header field to a backend server if a request is
1364 received in early data and handshake has not finished. All
1365 backend servers should deal with possibly replayed requests.
1366 --frontend-quic-qlog-dir=<DIR>
1368 Specify a directory where a qlog file is written for front‐
1369 end QUIC connections. A qlog file is created per each QUIC
1370 connection. The file name is ISO8601 basic format, followed
1371 by "-", server Source Connection ID and ".qlog".
1372 --frontend-quic-require-token
1374 Require an address validation token for a frontend QUIC connec‐
1375 tion. Server sends a token in Retry packet or NEW_TOKEN
1376 frame in the previous connection.
1377 --frontend-quic-congestion-controller=<CC>
1379 Specify a congestion controller algorithm for a frontend QUIC
1380 connection. <CC> should be either "cubic" or "bbr".
1381 Default: cubic
1383 --frontend-quic-connection-id-encryption-key=<HEXSTRING>
1385 Specify Connection ID encryption key. The encryption key
1386 must be 16 bytes, and it must be encoded in hex string
1387 (which is 32 bytes long). If this option is omitted, new
1388 key is generated. In order to survive QUIC connection in a con‐
1389 figuration reload event, old and new configuration must have
1390 this option and share the same key.
1391 --no-quic-bpf
1393 Disable eBPF.
1394 --frontend-http3-window-size=<SIZE>
1396 Sets the per-stream initial window size of HTTP/3 front‐
1397 end connection.
1398 Default: 256K
1400 --frontend-http3-connection-window-size=<SIZE>
1402 Sets the per-connection window size of HTTP/3 frontend connec‐
1403 tion.
1404 Default: 1M
1406 --frontend-http3-max-window-size=<SIZE>
1408 Sets the maximum per-stream window size of HTTP/3 front‐
1409 end connection. The window size is adjusted based on the re‐
1410 ceiving rate of stream data. The initial value is the value
1411 specified by --frontend-http3-window-size and the window size
1412 grows up to <SIZE> bytes.
1413 Default: 6M
1415 --frontend-http3-max-connection-window-size=<SIZE>
1417 Sets the maximum per-connection window size of HTTP/3 front‐
1418 end connection. The window size is adjusted based on the re‐
1419 ceiving rate of stream data. The initial value is the
1420 value specified by
1421 --frontend-http3-connection-window-size and the window size
1422 grows up to <SIZE> bytes.
1423 Default: 8M
1425 --frontend-http3-max-concurrent-streams=<N>
1427 Set the maximum number of the concurrent streams in one front‐
1428 end HTTP/3 connection.
1429 Default: 100
1431 Misc
1433 --conf=<PATH>
1434 Load configuration from <PATH>. Please note that nghttpx
1435 always tries to read the default configuration file if --conf
1436 is not given.
1437 Default: /etc/nghttpx/nghttpx.conf
1439 --include=<PATH>
1441 Load additional configurations from <PATH>. File <PATH> is
1442 read when configuration parser encountered this option.
1443 This option can be used multiple times, or even recursively.
1444 -v, --version
1446 Print version and exit.
1447 -h, --help
1449 Print this help and exit.
1450 The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
1452 * 1024). Units are K, M and G (powers of 1024).
1453 The <DURATION> argument is an integer and an optional unit (e.g., 1s is
1455 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
1456 (hours, minutes, seconds and milliseconds, respectively). If a unit is
1457 omitted, a second is used as unit.
1458
1460 /etc/nghttpx/nghttpx.conf
1461 The default configuration file path nghttpx searches at startup.
1462 The configuration file path can be changed using --conf option.
1463 Those lines which are staring # are treated as comment.
1465 The option name in the configuration file is the long com‐
1467 mand-line option name with leading -- stripped (e.g., frontend).
1468 Put = between option name and value. Don't put extra leading or
1469 trailing spaces.
1470 When specifying arguments including characters which have spe‐
1472 cial meaning to a shell, we usually use quotes so that shell
1473 does not interpret them. When writing this configuration file,
1474 quotes for this purpose must not be used. For example, specify
1475 additional request header field, do this:
1476 add-request-header=foo: bar
1478 instead of:
1480 add-request-header="foo: bar"
1482 The options which do not take argument in the command-line take
1484 argument in the configuration file. Specify yes as an argument
1485 (e.g., http2-proxy=yes). If other string is given, it is ig‐
1486 nored.
1487 To specify private key and certificate file which are given as
1489 positional arguments in command-line, use private-key-file and
1490 certificate-file.
1491 --conf option cannot be used in the configuration file and will
1493 be ignored if specified.
1494 Error log
1496 Error log is written to stderr by default. It can be configured
1497 using --errorlog-file. The format of log message is as follows:
1498 <datetime> <main-pid> <current-pid> <thread-id> <level> (<file‐
1500 name>:<line>) <msg>
1501 <datetime>
1503 It is a combination of date and time when the log is
1504 written. It is in ISO 8601 format.
1505 <main-pid>
1507 It is a main process ID.
1508 <current-pid>
1510 It is a process ID which writes this log.
1511 <thread-id>
1513 It is a thread ID which writes this log. It would be
1514 unique within <current-pid>.
1515 <filename> and <line>
1517 They are source file name, and line number which produce
1518 this log.
1519 <msg> It is a log message body.
1521
1523 SIGQUIT
1524 Shutdown gracefully. First accept pending connections and stop
1525 accepting connection. After all connections are handled,
1526 nghttpx exits.
1527 SIGHUP Reload configuration file given in --conf.
1529 SIGUSR1
1531 Reopen log files.
1532 SIGUSR2
1534 Fork and execute nghttpx. It will execute the binary in the same
1535 path with same command-line arguments and environment variables. As
1536 of nghttpx version 1.20.0, the new main process sends SIGQUIT to the
1537 original main process when it is ready to serve requests. For the
1538 earlier versions of nghttpx, user has to send SIGQUIT to the origi‐
1539 nal main process.
1540 The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
1542 is usually used to execute new binary, and the main process is newly
1543 spawned. On the other hand, the latter just reloads configuration
1544 file, and the same main process continues to exist.
1545 NOTE:
1547 nghttpx consists of multiple processes: one process for processing
1548 these signals, and another one for processing requests. The former
1549 spawns the latter. The former is called main process, and the lat‐
1550 ter is called worker process. If neverbleed is enabled, the worker
1551 process spawns neverbleed daemon process which does RSA key process‐
1552 ing. The above signal must be sent to the main process. If the
1553 other processes received one of them, it is ignored. This behaviour
1554 of these processes may change in the future release. In other
1555 words, in the future release, the processes other than main process
1556 may terminate upon the reception of these signals. Therefore these
1557 signals should not be sent to the processes other than main process.
1558
1560 nghttpx supports HTTP/2 server push in default mode with Link header
1561 field. nghttpx looks for Link header field (RFC 5988) in response
1562 headers from backend server and extracts URI-reference with parameter
1563 rel=preload (see preload) and pushes those URIs to the frontend client.
1564 Here is a sample Link header field to initiate server push:
1565 Link: </fonts/font.woff>; rel=preload
1567 Link: </css/theme.css>; rel=preload
1568 Currently, the following restriction is applied for server push:
1570 1. The associated stream must have method "GET" or "POST". The associ‐
1572 ated stream's status code must be 200.
1573 This limitation may be loosened in the future release.
1575 nghttpx also supports server push if both frontend and backend are
1577 HTTP/2 in default mode. In this case, in addition to server push via
1578 Link header field, server push from backend is forwarded to frontend
1579 HTTP/2 session.
1580 HTTP/2 server push will be disabled if --http2-proxy is used.
1582
1584 nghttpx supports UNIX domain socket with a filename for both frontend
1585 and backend connections.
1586 Please note that current nghttpx implementation does not delete a
1588 socket with a filename. And on start up, if nghttpx detects that the
1589 specified socket already exists in the file system, nghttpx first
1590 deletes it. However, if SIGUSR2 is used to execute new binary and both
1591 old and new configurations use same filename, new binary does not
1592 delete the socket and continues to use it.
1593
1595 OCSP query is done using external Python script fetch-ocsp-response,
1596 which has been originally developed in Perl as part of h2o project (‐
1597 https://github.com/h2o/h2o), and was translated into Python.
1598 The script file is usually installed under $(prefix)/share/nghttp2/ di‐
1600 rectory. The actual path to script can be customized using
1601 --fetch-ocsp-response-file option.
1602 If OCSP query is failed, previous OCSP response, if any, is continued
1604 to be used.
1605 --fetch-ocsp-response-file option provides wide range of possibility to
1607 manage OCSP response. It can take an arbitrary script or executable.
1608 The requirement is that it supports the command-line interface of
1609 fetch-ocsp-response script, and it must return a valid DER encoded OCSP
1610 response on success. It must return exit code 0 on success, and 75 for
1611 temporary error, and the other error code for generic failure. For
1612 large cluster of servers, it is not efficient for each server to per‐
1613 form OCSP query using fetch-ocsp-response. Instead, you can retrieve
1614 OCSP response in some way, and store it in a disk or a shared database.
1615 Then specify a program in --fetch-ocsp-response-file to fetch it from
1616 those stores. This could provide a way to share the OCSP response be‐
1617 tween fleet of servers, and also any OCSP query strategy can be applied
1618 which may be beyond the ability of nghttpx itself or fetch-ocsp-re‐
1619 sponse script.
1620
1622 nghttpx supports TLS session resumption through both session ID and
1623 session ticket.
1624 SESSION ID RESUMPTION
1626 By default, session ID is shared by all worker threads.
1627 If --tls-session-cache-memcached is given, nghttpx will insert serial‐
1629 ized session data to memcached with nghttpx:tls-session-cache: + lower‐
1630 case hex string of session ID as a memcached entry key, with expiry
1631 time 12 hours. Session timeout is set to 12 hours.
1632 By default, connections to memcached server are not encrypted. To en‐
1634 able encryption, use tls keyword in --tls-session-cache-memcached op‐
1635 tion.
1636 TLS SESSION TICKET RESUMPTION
1638 By default, session ticket is shared by all worker threads. The auto‐
1639 matic key rotation is also enabled by default. Every an hour, new en‐
1640 cryption key is generated, and previous encryption key becomes decryp‐
1641 tion only key. We set session timeout to 12 hours, and thus we keep at
1642 most 12 keys.
1643 If --tls-ticket-key-memcached is given, encryption keys are retrieved
1645 from memcached. nghttpx just reads keys from memcached; one has to de‐
1646 ploy key generator program to update keys frequently (e.g., every 1
1647 hour). The example key generator tlsticketupdate.go is available under
1648 contrib directory in nghttp2 archive. The memcached entry key is
1649 nghttpx:tls-ticket-key. The data format stored in memcached is the bi‐
1650 nary format described below:
1651 +--------------+-------+----------------+
1653 | VERSION (4) |LEN (2)|KEY(48 or 80) ...
1654 +--------------+-------+----------------+
1655 ^ |
1656 | |
1657 +------------------------+
1658 (LEN, KEY) pair can be repeated
1659 All numbers in the above figure is bytes. All integer fields are net‐
1661 work byte order.
1662 First 4 bytes integer VERSION field, which must be 1. The 2 bytes in‐
1664 teger LEN field gives the length of following KEY field, which contains
1665 key. If --tls-ticket-key-cipher=aes-128-cbc is used, LEN must be 48.
1666 If --tls-ticket-key-cipher=aes-256-cbc is used, LEN must be 80. LEN
1667 and KEY pair can be repeated multiple times to store multiple keys.
1668 The key appeared first is used as encryption key. All the remaining
1669 keys are used as decryption only.
1670 By default, connections to memcached server are not encrypted. To en‐
1672 able encryption, use tls keyword in --tls-ticket-key-memcached option.
1673 If --tls-ticket-key-file is given, encryption key is read from the
1675 given file. In this case, nghttpx does not rotate key automatically.
1676 To rotate key, one has to restart nghttpx (see SIGNALS).
1677
1679 nghttpx supports TLS signed_certificate_timestamp extension (RFC 6962).
1680 The relevant options are --tls-sct-dir and sct-dir parameter in
1681 --subcert. They takes a directory, and nghttpx reads all files whose
1682 extension is .sct under the directory. The *.sct files are encoded as
1683 SignedCertificateTimestamp struct described in section 3.2 of RFC
1684 69662. This format is the same one used by nginx-ct and mod_ssl_ct.
1685 ct-submit can be used to submit certificates to log servers, and obtain
1686 the SignedCertificateTimestamp struct which can be used with nghttpx.
1687
1689 WARNING:
1690 The current mruby extension API is experimental and not frozen. The
1691 API is subject to change in the future release.
1692 WARNING:
1694 Almost all string value returned from method, or attribute is a
1695 fresh new mruby string, which involves memory allocation, and
1696 copies. Therefore, it is strongly recommended to store a return
1697 value in a local variable, and use it, instead of calling method or
1698 accessing attribute repeatedly.
1699 nghttpx allows users to extend its capability using mruby scripts.
1701 nghttpx has 2 hook points to execute mruby script: request phase and
1702 response phase. The request phase hook is invoked after all request
1703 header fields are received from client. The response phase hook is in‐
1704 voked after all response header fields are received from backend
1705 server. These hooks allows users to modify header fields, or common
1706 HTTP variables, like authority or request path, and even return custom
1707 response without forwarding request to backend servers.
1708 There are 2 levels of mruby script invocations: global and per-pattern.
1710 The global mruby script is set by --mruby-file option and is called for
1711 all requests. The per-pattern mruby script is set by "mruby" parameter
1712 in -b option. It is invoked for a request which matches the particular
1713 pattern. The order of hook invocation is: global request phase hook,
1714 per-pattern request phase hook, per-pattern response phase hook, and
1715 finally global response phase hook. If a hook returns a response, any
1716 later hooks are not invoked. The global request hook is invoked before
1717 the pattern matching is made and changing request path may affect the
1718 pattern matching.
1719 Please note that request and response hooks of per-pattern mruby script
1721 for a single request might not come from the same script. This might
1722 happen after a request hook is executed, backend failed for some rea‐
1723 son, and at the same time, backend configuration is replaced by API re‐
1724 quest, and then the request uses new configuration on retry. The re‐
1725 sponse hook from new configuration, if it is specified, will be in‐
1726 voked.
1727 The all mruby script will be evaluated once per thread on startup, and
1729 it must instantiate object and evaluate it as the return value (e.g.,
1730 App.new). This object is called app object. If app object defines
1731 on_req method, it is called with Nghttpx::Env object on request hook.
1732 Similarly, if app object defines on_resp method, it is called with
1733 Nghttpx::Env object on response hook. For each method invocation, user
1734 can can access Nghttpx::Request and Nghttpx::Response objects via
1735 Nghttpx::Env#req and Nghttpx::Env#resp respectively.
1736 Nghttpx::REQUEST_PHASE
1738 Constant to represent request phase.
1739 Nghttpx::RESPONSE_PHASE
1741 Constant to represent response phase.
1742 class Nghttpx::Env
1744 Object to represent current request specific context.
1745 attribute [R] req
1747 Return Request object.
1748 attribute [R] resp
1750 Return Response object.
1751 attribute [R] ctx
1753 Return Ruby hash object. It persists until request fin‐
1754 ishes. So values set in request phase hook can be re‐
1755 trieved in response phase hook.
1756 attribute [R] phase
1758 Return the current phase.
1759 attribute [R] remote_addr
1761 Return IP address of a remote client. If connection is
1762 made via UNIX domain socket, this returns the string "lo‐
1763 calhost".
1764 attribute [R] server_addr
1766 Return address of server that accepted the connection.
1767 This is a string which specified in --frontend option,
1768 excluding port number, and not a resolved IP address.
1769 For UNIX domain socket, this is a path to UNIX domain
1770 socket.
1771 attribute [R] server_port
1773 Return port number of the server frontend which accepted
1774 the connection from client.
1775 attribute [R] tls_used
1777 Return true if TLS is used on the connection.
1778 attribute [R] tls_sni
1780 Return the TLS SNI value which client sent in this con‐
1781 nection.
1782 attribute [R] tls_client_fingerprint_sha256
1784 Return the SHA-256 fingerprint of a client certificate.
1785 attribute [R] tls_client_fingerprint_sha1
1787 Return the SHA-1 fingerprint of a client certificate.
1788 attribute [R] tls_client_issuer_name
1790 Return the issuer name of a client certificate.
1791 attribute [R] tls_client_subject_name
1793 Return the subject name of a client certificate.
1794 attribute [R] tls_client_serial
1796 Return the serial number of a client certificate.
1797 attribute [R] tls_client_not_before
1799 Return the start date of a client certificate in seconds
1800 since the epoch.
1801 attribute [R] tls_client_not_after
1803 Return the end date of a client certificate in seconds
1804 since the epoch.
1805 attribute [R] tls_cipher
1807 Return a TLS cipher negotiated in this connection.
1808 attribute [R] tls_protocol
1810 Return a TLS protocol version negotiated in this connec‐
1811 tion.
1812 attribute [R] tls_session_id
1814 Return a session ID for this connection in hex string.
1815 attribute [R] tls_session_reused
1817 Return true if, and only if a SSL/TLS session is reused.
1818 attribute [R] alpn
1820 Return ALPN identifier negotiated in this connection.
1821 attribute [R] tls_handshake_finished
1823 Return true if SSL/TLS handshake has finished. If it re‐
1824 turns false in the request phase hook, the request is re‐
1825 ceived in TLSv1.3 early data (0-RTT) and might be vulner‐
1826 able to the replay attack. nghttpx will send Early-Data
1827 header field to backend servers to indicate this.
1828 class Nghttpx::Request
1830 Object to represent request from client. The modification to
1831 Request object is allowed only in request phase hook.
1832 attribute [R] http_version_major
1834 Return HTTP major version.
1835 attribute [R] http_version_minor
1837 Return HTTP minor version.
1838 attribute [R/W] method
1840 HTTP method. On assignment, copy of given value is as‐
1841 signed. We don't accept arbitrary method name. We will
1842 document them later, but well known methods, like GET,
1843 PUT and POST, are all supported.
1844 attribute [R/W] authority
1846 Authority (i.e., example.org), including optional port
1847 component . On assignment, copy of given value is as‐
1848 signed.
1849 attribute [R/W] scheme
1851 Scheme (i.e., http, https). On assignment, copy of given
1852 value is assigned.
1853 attribute [R/W] path
1855 Request path, including query component (i.e., /in‐
1856 dex.html). On assignment, copy of given value is as‐
1857 signed. The path does not include authority component of
1858 URI. This may include query component. nghttpx makes
1859 certain normalization for path. It decodes percent-en‐
1860 coding for unreserved characters (see
1861 https://tools.ietf.org/html/rfc3986#section-2.3), and re‐
1862 solves ".." and ".". But it may leave characters which
1863 should be percent-encoded as is. So be careful when com‐
1864 paring path against desired string.
1865 attribute [R] headers
1867 Return Ruby hash containing copy of request header
1868 fields. Changing values in returned hash does not change
1869 request header fields actually used in request process‐
1870 ing. Use Nghttpx::Request#add_header or
1871 Nghttpx::Request#set_header to change request header
1872 fields.
1873 add_header(key, value)
1875 Add header entry associated with key. The value can be
1876 single string or array of string. It does not replace
1877 any existing values associated with key.
1878 set_header(key, value)
1880 Set header entry associated with key. The value can be
1881 single string or array of string. It replaces any exist‐
1882 ing values associated with key.
1883 clear_headers()
1885 Clear all existing request header fields.
1886 push(uri)
1888 Initiate to push resource identified by uri. Only HTTP/2
1889 protocol supports this feature. For the other protocols,
1890 this method is noop. uri can be absolute URI, absolute
1891 path or relative path to the current request. For abso‐
1892 lute or relative path, scheme and authority are inherited
1893 from the current request. Currently, method is always
1894 GET. nghttpx will issue request to backend servers to
1895 fulfill this request. The request and response phase
1896 hooks will be called for pushed resource as well.
1897 class Nghttpx::Response
1899 Object to represent response from backend server.
1900 attribute [R] http_version_major
1902 Return HTTP major version.
1903 attribute [R] http_version_minor
1905 Return HTTP minor version.
1906 attribute [R/W] status
1908 HTTP status code. It must be in the range [200, 999],
1909 inclusive. The non-final status code is not supported in
1910 mruby scripting at the moment.
1911 attribute [R] headers
1913 Return Ruby hash containing copy of response header
1914 fields. Changing values in returned hash does not change
1915 response header fields actually used in response process‐
1916 ing. Use Nghttpx::Response#add_header or
1917 Nghttpx::Response#set_header to change response header
1918 fields.
1919 add_header(key, value)
1921 Add header entry associated with key. The value can be
1922 single string or array of string. It does not replace
1923 any existing values associated with key.
1924 set_header(key, value)
1926 Set header entry associated with key. The value can be
1927 single string or array of string. It replaces any exist‐
1928 ing values associated with key.
1929 clear_headers()
1931 Clear all existing response header fields.
1932 return(body)
1934 Return custom response body to a client. When this
1935 method is called in request phase hook, the request is
1936 not forwarded to the backend, and response phase hook for
1937 this request will not be invoked. When this method is
1938 called in response phase hook, response from backend
1939 server is canceled and discarded. The status code and
1940 response header fields should be set before using this
1941 method. To set status code, use
1942 Nghttpx::Response#status. If status code is not set, 200
1943 is used. To set response header fields,
1944 Nghttpx::Response#add_header and
1945 Nghttpx::Response#set_header. When this method is in‐
1946 voked in response phase hook, the response headers are
1947 filled with the ones received from backend server. To
1948 send completely custom header fields, first call
1949 Nghttpx::Response#clear_headers to erase all existing
1950 header fields, and then add required header fields. It
1951 is an error to call this method twice for a given re‐
1952 quest.
1953 send_info(status, headers)
1955 Send non-final (informational) response to a client.
1956 status must be in the range [100, 199], inclusive. head‐
1957 ers is a hash containing response header fields. Its key
1958 must be a string, and the associated value must be either
1959 string or array of strings. Since this is not a final
1960 response, even if this method is invoked, request is
1961 still forwarded to a backend unless
1962 Nghttpx::Response#return is called. This method can be
1963 called multiple times. It cannot be called after
1964 Nghttpx::Response#return is called.
1965 MRUBY EXAMPLES
1967 Modify request path:
1968 class App
1970 def on_req(env)
1971 env.req.path = "/apps#{env.req.path}"
1972 end
1973 end
1974 App.new
1976 Don't forget to instantiate and evaluate object at the last line.
1978 Restrict permission of viewing a content to a specific client ad‐
1980 dresses:
1981 class App
1983 def on_req(env)
1984 allowed_clients = ["127.0.0.1", "::1"]
1985 if env.req.path.start_with?("/log/") &&
1987 !allowed_clients.include?(env.remote_addr) then
1988 env.resp.status = 404
1989 env.resp.return "permission denied"
1990 end
1991 end
1992 end
1993 App.new
1995
1997 nghttpx exposes API endpoints to manipulate it via HTTP based API. By
1998 default, API endpoint is disabled. To enable it, add a dedicated
1999 frontend for API using --frontend option with "api" parameter. All re‐
2000 quests which come from this frontend address, will be treated as API
2001 request.
2002 The response is normally JSON dictionary, and at least includes the
2004 following keys:
2005 status The status of the request processing. The following values are
2007 defined:
2008 Success
2010 The request was successful.
2011 Failure
2013 The request was failed. No change has been made.
2014 code HTTP status code
2016 Additionally, depending on the API endpoint, data key may be present,
2018 and its value contains the API endpoint specific data.
2019 We wrote "normally", since nghttpx may return ordinal HTML response in
2021 some cases where the error has occurred before reaching API endpoint
2022 (e.g., header field is too large).
2023 The following section describes available API endpoints.
2025 POST /api/v1beta1/backendconfig
2027 This API replaces the current backend server settings with the re‐
2028 quested ones. The request method should be POST, but PUT is also ac‐
2029 ceptable. The request body must be nghttpx configuration file format.
2030 For configuration file format, see FILES section. The line separator
2031 inside the request body must be single LF (0x0A). Currently, only
2032 backend option is parsed, the others are simply ignored. The semantics
2033 of this API is replace the current backend with the backend options in
2034 request body. Describe the desired set of backend severs, and nghttpx
2035 makes it happen. If there is no backend option is found in request
2036 body, the current set of backend is replaced with the backend option's
2037 default value, which is 127.0.0.1,80.
2038 The replacement is done instantly without breaking existing connections
2040 or requests. It also avoids any process creation as is the case with
2041 hot swapping with signals.
2042 The one limitation is that only numeric IP address is allowed in
2044 backend in request body unless "dns" parameter is used while non nu‐
2045 meric hostname is allowed in command-line or configuration file is read
2046 using --conf.
2047 GET /api/v1beta1/configrevision
2049 This API returns configuration revision of the current nghttpx. The
2050 configuration revision is opaque string, and it changes after each
2051 reloading by SIGHUP. With this API, an external application knows that
2052 whether nghttpx has finished reloading its configuration by comparing
2053 the configuration revisions between before and after reloading. It is
2054 recommended to disable persistent (keep-alive) connection for this pur‐
2055 pose in order to avoid to send a request using the reused connection
2056 which may bound to an old process.
2057 This API returns response including data key. Its value is JSON ob‐
2059 ject, and it contains at least the following key:
2060 configRevision
2062 The configuration revision of the current nghttpx
2063
2065 nghttp(1), nghttpd(1), h2load(1)
2066
2068 Tatsuhiro Tsujikawa
2069
2071 2012, 2015, 2016, Tatsuhiro Tsujikawa
20721.45.1 Sep 21, 2021 NGHTTPX(1)