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 omit‐
171 ted. "affinity-cookie-stickiness=<STICKINESS>" controls
172 stickiness of this affinity. If <STICKINESS> is
173 "loose", removing or adding a backend server might break the
174 affinity and the request might be forwarded to a different
175 backend server. If <STICKINESS> is "strict", removing the des‐
176 ignated backend server breaks affinity, but adding new backend
177 server does not cause breakage. If the designated backend
178 server becomes unavailable, new backend server is chosen as if
179 the request does not have an affinity cookie. <STICKINESS>
180 defaults to "loose".
181 By default, name resolution of backend host name is done at
183 start up, or reloading configuration. If "dns" parameter
184 is given, name resolution takes place dynamically. This
185 is useful if backend address changes frequently. If "dns"
186 is given, name resolution of backend host name at
187 start up, or reloading configuration is skipped.
188 If "redirect-if-not-tls" parameter is used, the matched backend
190 requires that frontend connection is TLS encrypted. If
191 it isn't, nghttpx responds to the request with 308 status code,
192 and https URI the client should use instead is included in
193 Location header field. The port number in redirect URI is 443
194 by default, and can be changed using --redirect-https-port
195 option. If at least one backend has "redirect-if-not-tls"
196 parameter, this feature is enabled for all backend servers
197 sharing the same <PATTERN>. It is advised to set
198 "redirect-if-no-tls" parameter to all backends explic‐
199 itly if this feature is desired.
200 If "upgrade-scheme" parameter is used along with "tls" parame‐
202 ter, HTTP/2 :scheme pseudo header field is changed to "https"
203 from "http" when forwarding a request to this particular back‐
204 end. This is a workaround for a backend server which re‐
205 quires "https" :scheme pseudo header field on TLS encrypted
206 connection.
207 "mruby=<PATH>" parameter specifies a path to mruby script
209 file which is invoked when this pattern is matched. All
210 backends which share the same pattern must have the same mruby
211 path.
212 "read-timeout=<DURATION>" and "write-timeout=<DURATION>" parame‐
214 ters specify the read and write timeout of the backend con‐
215 nection when this pattern is matched. All backends which
216 share the same pattern must have the same timeouts. If these
217 timeouts are entirely omitted for a pattern,
218 --backend-read-timeout and --backend-write-timeout are
219 used.
220 "group=<GROUP>" parameter specifies the name of group this
222 backend address belongs to. By default, it belongs to the un‐
223 named default group. The name of group is unique per
224 pattern. "group-weight=<N>" parameter specifies the weight
225 of the group. The higher weight gets more frequently se‐
226 lected by the load balancing algorithm. <N> must be [1,
227 256] inclusive. The weight 8 has 4 times more weight than 2.
228 <N> must be the same for all addresses which share the same
229 <GROUP>. If "group-weight" is omitted in an address, but the
230 other address which belongs to the same group specifies
231 "group-weight", its weight is used. If no
232 "group-weight" is specified for all addresses, the weight
233 of a group becomes 1. "group" and "group-weight" are ignored if
234 session affinity is enabled.
235 "weight=<N>" parameter specifies the weight of the backend
237 address inside a group which this address belongs to.
238 The higher weight gets more frequently selected by the load
239 balancing algorithm. <N> must be [1, 256] inclusive. The
240 weight 8 has 4 times more weight than weight 2. If this
241 parameter is omitted, weight becomes 1. "weight" is ig‐
242 nored if session affinity is enabled.
243 If "dnf" parameter is specified, an incoming request is not
245 forwarded to a backend and just consumed along with the re‐
246 quest body (actually a backend server never be contacted).
247 It is expected that the HTTP response is generated by mruby
248 script (see "mruby=<PATH>" parameter above). "dnf" is an abbre‐
249 viation of "do not forward".
250 Since ";" and ":" are used as delimiter, <PATTERN> must not
252 contain these characters. In order to include ":" in <PAT‐
253 TERN>, one has to specify "%3A" (which is percent-encoded
254 from of ":") instead. Since ";" has special meaning in
255 shell, the option value must be quoted.
256 Default: 127.0.0.1,80
258 -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]
260 Set frontend host and port. If <HOST> is '*', it assumes
261 all addresses including both IPv4 and IPv6. UNIX domain
262 socket can be specified by prefixing path name with "unix:"
263 (e.g., unix:/var/run/nghttpx.sock). This option can be used
264 multiple times to listen to multiple addresses.
265 This option can take 0 or more parameters, which are de‐
267 scribed below. Note that "api" and "healthmon" parame‐
268 ters are mutually exclusive.
269 Optionally, TLS can be disabled by specifying "no-tls" parame‐
271 ter. TLS is enabled by default.
272 If "sni-fwd" parameter is used, when performing a match to se‐
274 lect a backend server, SNI host name received from the client
275 is used instead of the request host. See --backend option
276 about the pattern match.
277 To make this frontend as API endpoint, specify "api" parame‐
279 ter. This is disabled by default. It is important to
280 limit the access to the API frontend. Otherwise, someone
281 may change the backend server, and break your services, or
282 expose confidential information to the outside the world.
283 To make this frontend as health monitor endpoint, specify
285 "healthmon" parameter. This is disabled by default. Any
286 requests which come through this address are replied with 200
287 HTTP status, without no body.
288 To accept PROXY protocol version 1 and 2 on frontend connec‐
290 tion, specify "proxyproto" parameter. This is disabled by
291 default.
292 To receive HTTP/3 (QUIC) traffic, specify "quic" parame‐
294 ter. It makes nghttpx listen on UDP port rather than TCP
295 port. UNIX domain socket, "api", and "healthmon" param‐
296 eters cannot be used with "quic" parameter.
297 Default: *,3000
299 --backlog=<N>
301 Set listen backlog size.
302 Default: 65536
304 --backend-address-family=(auto|IPv4|IPv6)
306 Specify address family of backend connections. If "auto"
307 is given, both IPv4 and IPv6 are considered. If "IPv4" is
308 given, only IPv4 address is considered. If "IPv6" is given,
309 only IPv6 address is considered.
310 Default: auto
312 --backend-http-proxy-uri=<URI>
314 Specify proxy URI in the form
315 http://[<USER>:<PASS>@]<PROXY>:<PORT>. If a proxy re‐
316 quires authentication, specify <USER> and <PASS>. Note
317 that they must be properly percent-encoded. This proxy is
318 used when the backend connection is HTTP/2. First, make a
319 CONNECT request to the proxy and it connects to the back‐
320 end on behalf of nghttpx. This forms tunnel. After that,
321 nghttpx performs SSL/TLS handshake with the downstream
322 through the tunnel. The timeouts when connecting and making
323 CONNECT request can be specified by
324 --backend-read-timeout and --backend-write-timeout options.
325 Performance
327 -n, --workers=<N>
328 Set the number of worker threads.
329 Default: 1
331 --single-thread
333 Run everything in one thread inside the worker process. This
334 feature is provided for better debugging experience,
335 or for the platforms which lack thread support. If
336 threading is disabled, this option is always enabled.
337 --read-rate=<SIZE>
339 Set maximum average read rate on frontend connection. Set‐
340 ting 0 to this option means read rate is unlimited.
341 Default: 0
343 --read-burst=<SIZE>
345 Set maximum read burst size on frontend connection. Set‐
346 ting 0 to this option means read burst size is unlimited.
347 Default: 0
349 --write-rate=<SIZE>
351 Set maximum average write rate on frontend connection. Set‐
352 ting 0 to this option means write rate is unlimited.
353 Default: 0
355 --write-burst=<SIZE>
357 Set maximum write burst size on frontend connection. Set‐
358 ting 0 to this option means write burst size is unlimited.
359 Default: 0
361 --worker-read-rate=<SIZE>
363 Set maximum average read rate on frontend connection per worker.
364 Setting 0 to this option means read rate is unlimited. Not
365 implemented yet.
366 Default: 0
368 --worker-read-burst=<SIZE>
370 Set maximum read burst size on frontend connection per worker.
371 Setting 0 to this option means read burst size is unlimited.
372 Not implemented yet.
373 Default: 0
375 --worker-write-rate=<SIZE>
377 Set maximum average write rate on frontend connection per
378 worker. Setting 0 to this option means write rate is unlim‐
379 ited. Not implemented yet.
380 Default: 0
382 --worker-write-burst=<SIZE>
384 Set maximum write burst size on frontend connection per worker.
385 Setting 0 to this option means write burst size is unlimited.
386 Not implemented yet.
387 Default: 0
389 --worker-frontend-connections=<N>
391 Set maximum number of simultaneous connections frontend ac‐
392 cepts. Setting 0 means unlimited.
393 Default: 0
395 --backend-connections-per-host=<N>
397 Set maximum number of backend concurrent connections (and/or
398 streams in case of HTTP/2) per origin host. This option is
399 meaningful when --http2-proxy option is used. The origin
400 host is determined by authority portion of request URI (or
401 :authority header field for HTTP/2). To limit the number
402 of connections per frontend for default
403 mode, use --backend-connections-per-frontend.
404 Default: 8
406 --backend-connections-per-frontend=<N>
408 Set maximum number of backend concurrent connections (and/or
409 streams in case of HTTP/2) per frontend. This option is
410 only used for default mode. 0 means unlimited. To limit
411 the number of connections per host with --http2-proxy
412 option, use --backend-connections-per-host.
413 Default: 0
415 --rlimit-nofile=<N>
417 Set maximum number of open files (RLIMIT_NOFILE) to <N>. If 0
418 is given, nghttpx does not set the limit.
419 Default: 0
421 --rlimit-memlock=<N>
423 Set maximum number of bytes of memory that may be locked into
424 RAM. If 0 is given, nghttpx does not set the limit.
425 Default: 0
427 --backend-request-buffer=<SIZE>
429 Set buffer size used to store backend request.
430 Default: 16K
432 --backend-response-buffer=<SIZE>
434 Set buffer size used to store backend response.
435 Default: 128K
437 --fastopen=<N>
439 Enables "TCP Fast Open" for the listening socket and limits
440 the maximum length for the queue of connections that have not
441 yet completed the three-way handshake. If value is 0 then fast
442 open is disabled.
443 Default: 0
445 --no-kqueue
447 Don't use kqueue. This option is only applicable for the
448 platforms which have kqueue. For other platforms, this option
449 will be simply ignored.
450 Timeout
452 --frontend-http2-read-timeout=<DURATION>
453 Specify read timeout for HTTP/2 frontend connection.
454 Default: 3m
456 --frontend-http3-read-timeout=<DURATION>
458 Specify read timeout for HTTP/3 frontend connection.
459 Default: 3m
461 --frontend-read-timeout=<DURATION>
463 Specify read timeout for HTTP/1.1 frontend connection.
464 Default: 1m
466 --frontend-write-timeout=<DURATION>
468 Specify write timeout for all frontend connections.
469 Default: 30s
471 --frontend-keep-alive-timeout=<DURATION>
473 Specify keep-alive timeout for frontend HTTP/1 connec‐
474 tion.
475 Default: 1m
477 --stream-read-timeout=<DURATION>
479 Specify read timeout for HTTP/2 streams. 0 means no time‐
480 out.
481 Default: 0
483 --stream-write-timeout=<DURATION>
485 Specify write timeout for HTTP/2 streams. 0 means no time‐
486 out.
487 Default: 1m
489 --backend-read-timeout=<DURATION>
491 Specify read timeout for backend connection.
492 Default: 1m
494 --backend-write-timeout=<DURATION>
496 Specify write timeout for backend connection.
497 Default: 30s
499 --backend-connect-timeout=<DURATION>
501 Specify timeout before establishing TCP connection to back‐
502 end.
503 Default: 30s
505 --backend-keep-alive-timeout=<DURATION>
507 Specify keep-alive timeout for backend HTTP/1 connec‐
508 tion.
509 Default: 2s
511 --listener-disable-timeout=<DURATION>
513 After accepting connection failed, connection listener is dis‐
514 abled for a given amount of time. Specifying 0 disables this
515 feature.
516 Default: 30s
518 --frontend-http2-setting-timeout=<DURATION>
520 Specify timeout before SETTINGS ACK is received from client.
521 Default: 10s
523 --backend-http2-settings-timeout=<DURATION>
525 Specify timeout before SETTINGS ACK is received from backend
526 server.
527 Default: 10s
529 --backend-max-backoff=<DURATION>
531 Specify maximum backoff interval. This is used when doing
532 health check against offline backend (see "fail" parameter in
533 --backend option). It is also used to limit the maximum
534 interval to temporarily disable backend when nghttpx failed
535 to connect to it. These intervals are calculated using expo‐
536 nential backoff, and consecutive failed attempts increase the
537 interval. This option caps its maximum value.
538 Default: 2m
540 SSL/TLS
542 --ciphers=<SUITE>
543 Set allowed cipher list for frontend connection. The format
544 of the string is described in OpenSSL ciphers(1). This option
545 sets cipher suites for TLSv1.2 or earlier. Use --tls13-ciphers
546 for TLSv1.3.
547 Default:
549 ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
550 --tls13-ciphers=<SUITE>
552 Set allowed cipher list for frontend connection. The format
553 of the string is described in OpenSSL ciphers(1). This option
554 sets cipher suites for TLSv1.3. Use --ciphers for TLSv1.2
555 or earlier.
556 Default:
558 TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
559 --client-ciphers=<SUITE>
561 Set allowed cipher list for backend connection. The format
562 of the string is described in OpenSSL ciphers(1). This option
563 sets cipher suites for TLSv1.2 or earlier. Use
564 --tls13-client-ciphers for TLSv1.3.
565 Default:
567 ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
568 --tls13-client-ciphers=<SUITE>
570 Set allowed cipher list for backend connection. The format
571 of the string is described in OpenSSL ciphers(1). This option
572 sets cipher suites for TLSv1.3. Use
573 --tls13-client-ciphers for TLSv1.2 or earlier.
574 Default:
576 TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
577 --ecdh-curves=<LIST>
579 Set supported curve list for frontend connections. <LIST>
580 is a colon separated list of curve NID or names in the prefer‐
581 ence order. The supported curves depend on the linked OpenSSL
582 library. This function requires OpenSSL >= 1.0.2.
583 Default: X25519:P-256:P-384:P-521
585 -k, --insecure
587 Don't verify backend server's certificate if TLS is enabled
588 for backend connections.
589 --cacert=<PATH>
591 Set path to trusted CA certificate file. It is used in backend
592 TLS connections to verify peer's certificate. It is also used
593 to verify OCSP response from the script set by
594 --fetch-ocsp-response-file. The file must be in PEM format.
595 It can contain multiple certificates. If the linked OpenSSL
596 is configured to load system wide certificates, they are
597 loaded at startup regardless of this option.
598 --private-key-passwd-file=<PATH>
600 Path to file that contains password for the server's private
601 key. If none is given and the private key is password pro‐
602 tected it'll be requested interactively.
603 --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
605 Specify additional certificate and private key file.
606 nghttpx will choose certificates based on the hostname indi‐
607 cated by client using TLS SNI extension. If nghttpx is built
608 with OpenSSL >= 1.0.2, the shared elliptic curves (e.g.,
609 P-256) between client and server are also taken into consider‐
610 ation. This allows nghttpx to send ECDSA certificate to mod‐
611 ern clients, while sending RSA based certificate to older
612 clients. This option can be used multiple times. To make
613 OCSP stapling work, <CERTPATH> must be absolute path.
614 Additional parameter can be specified in <PARAM>. The avail‐
616 able <PARAM> is "sct-dir=<DIR>".
617 "sct-dir=<DIR>" specifies the path to directory which con‐
619 tains *.sct files for TLS
620 signed_certificate_timestamp extension (RFC 6962). This feature
621 requires OpenSSL >= 1.0.2. See also --tls-sct-dir op‐
622 tion.
623 --dh-param-file=<PATH>
625 Path to file that contains DH parameters in PEM format. With‐
626 out this option, DHE cipher suites are not available.
627 --npn-list=<LIST>
629 Comma delimited list of ALPN protocol identifier sorted in the
630 order of preference. That means most desirable protocol comes
631 first. This is used in both ALPN and NPN. The parameter
632 must be delimited by a single comma only and any white spaces
633 are treated as a part of protocol string.
634 Default: h2,h2-16,h2-14,http/1.1
636 --verify-client
638 Require and verify client certificate.
639 --verify-client-cacert=<PATH>
641 Path to file that contains CA certificates to verify client
642 certificate. The file must be in PEM format. It can contain
643 multiple certificates.
644 --verify-client-tolerate-expired
646 Accept expired client certificate. Operator should handle
647 the expired client certificate by some means (e.g., mruby
648 script). Otherwise, this option might cause a security risk.
649 --client-private-key-file=<PATH>
651 Path to file that contains client private key used in backend
652 client authentication.
653 --client-cert-file=<PATH>
655 Path to file that contains client certificate used in backend
656 client authentication.
657 --tls-min-proto-version=<VER>
659 Specify minimum SSL/TLS protocol. The name matching is done in
660 case-insensitive manner. The versions between
661 --tls-min-proto-version and --tls-max-proto-version are en‐
662 abled. If the protocol list advertised by client does not
663 overlap this range, you will receive the error message "un‐
664 known protocol". If a protocol version lower than TLSv1.2 is
665 specified, make sure that the compatible ciphers are included
666 in --ciphers option. The default cipher list only includes
667 ciphers compatible with TLSv1.2 or above. The available ver‐
668 sions are: TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
669 Default: TLSv1.2
671 --tls-max-proto-version=<VER>
673 Specify maximum SSL/TLS protocol. The name matching is done in
674 case-insensitive manner. The versions between
675 --tls-min-proto-version and --tls-max-proto-version are en‐
676 abled. If the protocol list advertised by client does not
677 overlap this range, you will receive the error message "un‐
678 known protocol". The available versions are: TLSv1.3, TLSv1.2,
679 TLSv1.1, and TLSv1.0
680 Default: TLSv1.3
682 --tls-ticket-key-file=<PATH>
684 Path to file that contains random data to construct TLS session
685 ticket parameters. If aes-128-cbc is given in
686 --tls-ticket-key-cipher, the file must contain exactly 48
687 bytes. If aes-256-cbc is given in
688 --tls-ticket-key-cipher, the file must contain exactly 80
689 bytes. This options can be used repeatedly to specify
690 multiple ticket parameters. If several files are given, only
691 the first key is used to encrypt TLS session tickets. Other
692 keys are accepted but server will issue new session ticket
693 with first key. This allows session key rotation. Please
694 note that key rotation does not occur automatically. User
695 should rearrange files or change options values and restart
696 nghttpx gracefully. If opening or reading given file fails,
697 all loaded keys are discarded and it is treated as if none of
698 this option is given. If this option is not given or an error
699 occurred while opening or reading a file, key is generated ev‐
700 ery 1 hour internally and they are valid for 12 hours.
701 This is recommended if ticket key sharing between nghttpx
702 instances is not required.
703 --tls-ticket-key-memcached=<HOST>,<PORT>[;tls]
705 Specify address of memcached server to get TLS ticket keys
706 for session resumption. This enables shared TLS ticket key
707 between multiple nghttpx instances. nghttpx does not set TLS
708 ticket key to memcached. The external ticket key generator is
709 required. nghttpx just gets TLS ticket keys from memcached,
710 and use them, possibly replacing current set of keys. It is
711 up to extern TLS ticket key generator to rotate keys fre‐
712 quently. See "TLS SESSION TICKET RESUMPTION" section in man‐
713 ual page to know the data format in memcached entry. Option‐
714 ally, memcached connection can be encrypted with TLS by
715 specifying "tls" parameter.
716 --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6)
718 Specify address family of memcached connections to get TLS
719 ticket keys. If "auto" is given, both IPv4 and IPv6 are consid‐
720 ered. If "IPv4" is given, only IPv4 address is considered.
721 If "IPv6" is given, only IPv6 address is considered.
722 Default: auto
724 --tls-ticket-key-memcached-interval=<DURATION>
726 Set interval to get TLS ticket keys from memcached.
727 Default: 10m
729 --tls-ticket-key-memcached-max-retry=<N>
731 Set maximum number of consecutive retries before aban‐
732 doning TLS ticket key retrieval. If this number is reached,
733 the attempt is considered as failure, and "failure" count
734 is incremented by 1, which contributed to the
735 value controlled --tls-ticket-key-memcached-max-fail
736 option.
737 Default: 3
739 --tls-ticket-key-memcached-max-fail=<N>
741 Set maximum number of consecutive failure before dis‐
742 abling TLS ticket until next scheduled key retrieval.
743 Default: 2
745 --tls-ticket-key-cipher=<CIPHER>
747 Specify cipher to encrypt TLS session ticket. Specify either
748 aes-128-cbc or aes-256-cbc. By default, aes-128-cbc is
749 used.
750 --tls-ticket-key-memcached-cert-file=<PATH>
752 Path to client certificate for memcached connections to get TLS
753 ticket keys.
754 --tls-ticket-key-memcached-private-key-file=<PATH>
756 Path to client private key for memcached connections to get TLS
757 ticket keys.
758 --fetch-ocsp-response-file=<PATH>
760 Path to fetch-ocsp-response script file. It should be abso‐
761 lute path.
762 Default: /usr/local/share/nghttp2/fetch-ocsp-response
764 --ocsp-update-interval=<DURATION>
766 Set interval to update OCSP response cache.
767 Default: 4h
769 --ocsp-startup
771 Start accepting connections after initial attempts to get
772 OCSP responses finish. It does not matter some of the at‐
773 tempts fail. This feature is useful if OCSP responses
774 must be available before accepting connections.
775 --no-verify-ocsp
777 nghttpx does not verify OCSP response.
778 --no-ocsp
780 Disable OCSP stapling.
781 --tls-session-cache-memcached=<HOST>,<PORT>[;tls]
783 Specify address of memcached server to store session cache.
784 This enables shared session cache between multiple
785 nghttpx instances. Optionally, memcached connection can be
786 encrypted with TLS by specifying "tls" parameter.
787 --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6)
789 Specify address family of memcached connections to store session
790 cache. If "auto" is given, both IPv4 and IPv6 are considered.
791 If "IPv4" is given, only IPv4 address is considered. If "IPv6"
792 is given, only IPv6 address is considered.
793 Default: auto
795 --tls-session-cache-memcached-cert-file=<PATH>
797 Path to client certificate for memcached connections to store
798 session cache.
799 --tls-session-cache-memcached-private-key-file=<PATH>
801 Path to client private key for memcached connections to store
802 session cache.
803 --tls-dyn-rec-warmup-threshold=<SIZE>
805 Specify the threshold size for TLS dynamic record size behav‐
806 iour. During a TLS session, after the threshold number of
807 bytes have been written, the TLS record size will be increased
808 to the maximum allowed (16K). The max record size will con‐
809 tinue to be used on the active TLS session. After
810 --tls-dyn-rec-idle-timeout has elapsed, the record size is re‐
811 duced to 1300 bytes. Specify 0 to always use the maximum
812 record size, regardless of idle period. This behaviour ap‐
813 plies to all TLS based frontends, and TLS HTTP/2 backends.
814 Default: 1M
816 --tls-dyn-rec-idle-timeout=<DURATION>
818 Specify TLS dynamic record size behaviour timeout. See
819 --tls-dyn-rec-warmup-threshold for more information. This
820 behaviour applies to all TLS based frontends, and TLS HTTP/2
821 backends.
822 Default: 1s
824 --no-http2-cipher-block-list
826 Allow block listed cipher suite on frontend HTTP/2 connec‐
827 tion. See
828 https://tools.ietf.org/html/rfc7540#appendix-A for the com‐
829 plete HTTP/2 cipher suites block list.
830 --client-no-http2-cipher-block-list
832 Allow block listed cipher suite on backend HTTP/2 connec‐
833 tion. See
834 https://tools.ietf.org/html/rfc7540#appendix-A for the com‐
835 plete HTTP/2 cipher suites block list.
836 --tls-sct-dir=<DIR>
838 Specifies the directory where *.sct files exist. All *.sct
839 files in <DIR> are read, and sent as extension_data
840 of TLS signed_certificate_timestamp (RFC 6962) to client.
841 These *.sct files are for the certificate specified in
842 positional command-line argument <CERT>, or certificate op‐
843 tion in configuration file. For additional certificates,
844 use --subcert option. This option requires OpenSSL >= 1.0.2.
845 --psk-secrets=<PATH>
847 Read list of PSK identity and secrets from <PATH>. This is used
848 for frontend connection. The each line of input file is for‐
849 matted as <identity>:<hex-secret>, where <identity> is PSK
850 identity, and <hex-secret> is secret in hex. An empty line,
851 and line which starts with '#' are skipped. The default en‐
852 abled cipher list might not contain any PSK cipher suite. In
853 that case, desired PSK cipher suites must be enabled using
854 --ciphers option. The desired PSK cipher suite may be block
855 listed by HTTP/2. To use those cipher suites with
856 HTTP/2, consider to use --no-http2-cipher-block-list option.
857 But be aware its implications.
858 --client-psk-secrets=<PATH>
860 Read PSK identity and secrets from <PATH>. This is used for
861 backend connection. The each line of input file is formatted
862 as <identity>:<hex-secret>, where <identity> is PSK identity,
863 and <hex-secret> is secret in hex. An empty line, and line
864 which starts with '#' are skipped. The first identity and se‐
865 cret pair encountered is used. The default enabled cipher
866 list might not contain any PSK cipher suite. In that case,
867 desired PSK cipher suites must be enabled using
868 --client-ciphers option. The desired PSK cipher suite may be
869 block listed by HTTP/2. To use those cipher suites with
870 HTTP/2, consider to use --client-no-http2-cipher-block-list
871 option. But be aware its implications.
872 --tls-no-postpone-early-data
874 By default, except for QUIC connections, nghttpx post‐
875 pones forwarding HTTP requests sent in early data, including
876 those sent in partially in it, until TLS handshake fin‐
877 ishes. If all backend server recognizes "Early-Data" header
878 field, using this option makes nghttpx not postpone for‐
879 warding request and get full potential of 0-RTT data.
880 --tls-max-early-data=<SIZE>
882 Sets the maximum amount of 0-RTT data that server ac‐
883 cepts.
884 Default: 16K
886 --tls-ktls
888 Enable ktls. For server, ktls is enable if
889 --tls-session-cache-memcached is not configured.
890 HTTP/2
892 -c, --frontend-http2-max-concurrent-streams=<N>
893 Set the maximum number of the concurrent streams in one front‐
894 end HTTP/2 session.
895 Default: 100
897 --backend-http2-max-concurrent-streams=<N>
899 Set the maximum number of the concurrent streams in one backend
900 HTTP/2 session. This sets maximum number of concurrent
901 opened pushed streams. The maximum number of concurrent re‐
902 quests are set by a remote server.
903 Default: 100
905 --frontend-http2-window-size=<SIZE>
907 Sets the per-stream initial window size of HTTP/2 front‐
908 end connection.
909 Default: 65535
911 --frontend-http2-connection-window-size=<SIZE>
913 Sets the per-connection window size of HTTP/2 frontend connec‐
914 tion.
915 Default: 65535
917 --backend-http2-window-size=<SIZE>
919 Sets the initial window size of HTTP/2 backend connec‐
920 tion.
921 Default: 65535
923 --backend-http2-connection-window-size=<SIZE>
925 Sets the per-connection window size of HTTP/2 backend connec‐
926 tion.
927 Default: 2147483647
929 --http2-no-cookie-crumbling
931 Don't crumble cookie header field.
932 --padding=<N>
934 Add at most <N> bytes to a HTTP/2 frame payload as pad‐
935 ding. Specify 0 to disable padding. This option is meant for
936 debugging purpose and not intended to enhance protocol secu‐
937 rity.
938 --no-server-push
940 Disable HTTP/2 server push. Server push is supported by default
941 mode and HTTP/2 frontend via Link header field. It is also
942 supported if both frontend and backend are HTTP/2 in default
943 mode. In this case, server push from backend session is re‐
944 layed to frontend, and server push via Link header field is
945 also supported.
946 --frontend-http2-optimize-write-buffer-size
948 (Experimental) Enable write buffer size optimization in front‐
949 end HTTP/2 TLS connection. This optimization aims to reduce
950 write buffer size so that it only contains bytes which can
951 send immediately. This makes server more responsive to prior‐
952 itized HTTP/2 stream because the buffering of lower priority
953 stream is reduced. This option is only effective on recent
954 Linux platform.
955 --frontend-http2-optimize-window-size
957 (Experimental) Automatically tune connection level window
958 size of frontend HTTP/2 TLS connection. If this feature is
959 enabled, connection window size starts with the default win‐
960 dow size, 65535 bytes. nghttpx automatically adjusts
961 connection window size based on TCP receiving window size.
962 The maximum window size is capped by the value
963 specified by --frontend-http2-connection-window-size.
964 Since the stream is subject to stream level window size, it
965 should be adjusted using --frontend-http2-window-size option as
966 well. This option is only effective on recent Linux plat‐
967 form.
968 --frontend-http2-encoder-dynamic-table-size=<SIZE>
970 Specify the maximum dynamic table size of HPACK encoder in the
971 frontend HTTP/2 connection. The decoder (client) specifies the
972 maximum dynamic table size it accepts. Then the negotiated
973 dynamic table size is the minimum of this option value and the
974 value which client specified.
975 Default: 4K
977 --frontend-http2-decoder-dynamic-table-size=<SIZE>
979 Specify the maximum dynamic table size of HPACK decoder in the
980 frontend HTTP/2 connection.
981 Default: 4K
983 --backend-http2-encoder-dynamic-table-size=<SIZE>
985 Specify the maximum dynamic table size of HPACK encoder in the
986 backend HTTP/2 connection. The decoder (backend) specifies the
987 maximum dynamic table size it accepts. Then the negotiated
988 dynamic table size is the minimum of this option value and the
989 value which backend specified.
990 Default: 4K
992 --backend-http2-decoder-dynamic-table-size=<SIZE>
994 Specify the maximum dynamic table size of HPACK decoder in the
995 backend HTTP/2 connection.
996 Default: 4K
998 Mode
1000 (default mode)
1001 Accept HTTP/2, and HTTP/1.1 over SSL/TLS. "no-tls" parame‐
1002 ter is used in --frontend option, accept HTTP/2 and HTTP/1.1
1003 over cleartext TCP. The incoming HTTP/1.1 connection can be
1004 upgraded to HTTP/2 through HTTP Upgrade.
1005 -s, --http2-proxy
1007 Like default mode, but enable forward proxy. This is so called
1008 HTTP/2 proxy mode.
1009 Logging
1011 -L, --log-level=<LEVEL>
1012 Set the severity level of log output. <LEVEL> must be one of
1013 INFO, NOTICE, WARN, ERROR and FATAL.
1014 Default: NOTICE
1016 --accesslog-file=<PATH>
1018 Set path to write access log. To reopen file, send USR1 signal
1019 to nghttpx.
1020 --accesslog-syslog
1022 Send access log to syslog. If this option is used,
1023 --accesslog-file option is ignored.
1024 --accesslog-format=<FORMAT>
1026 Specify format string for access log. The default format
1027 is combined format. The following variables are available:
1028 • $remote_addr: client IP address.
1030 • $time_local: local time in Common Log format.
1032 • $time_iso8601: local time in ISO 8601 format.
1034 • $request: HTTP request line.
1036 • $status: HTTP response status code.
1038 • $body_bytes_sent: the number of bytes sent to client as re‐
1040 sponse body.
1041 • $http_<VAR>: value of HTTP request header <VAR> where '_' in
1043 <VAR> is replaced with '-'.
1044 • $remote_port: client port.
1046 • $server_port: server port.
1048 • $request_time: request processing time in seconds with mil‐
1050 liseconds resolution.
1051 • $pid: PID of the running process.
1053 • $alpn: ALPN identifier of the protocol which generates the re‐
1055 sponse. For HTTP/1, ALPN is always http/1.1, regardless of
1056 minor version.
1057 • $tls_cipher: cipher used for SSL/TLS connection.
1059 • $tls_client_fingerprint_sha256: SHA-256 fingerprint of client
1061 certificate.
1062 • $tls_client_fingerprint_sha1: SHA-1 fingerprint of client
1064 certificate.
1065 • $tls_client_subject_name: subject name in client cer‐
1067 tificate.
1068 • $tls_client_issuer_name: issuer name in client cer‐
1070 tificate.
1071 • $tls_client_serial: serial number in client cer‐
1073 tificate.
1074 • $tls_protocol: protocol for SSL/TLS connection.
1076 • $tls_session_id: session ID for SSL/TLS connection.
1078 • $tls_session_reused: "r" if SSL/TLS session was reused.
1080 Otherwise, "."
1081 • $tls_sni: SNI server name for SSL/TLS connection.
1083 • $backend_host: backend host used to fulfill the re‐
1085 quest. "-" if backend host is not available.
1086 • $backend_port: backend port used to fulfill the re‐
1088 quest. "-" if backend host is not available.
1089 • $method: HTTP method
1091 • $path: Request path including query. For CONNECT re‐
1093 quest, authority is recorded.
1094 • $path_without_query: $path up to the first '?' charac‐
1096 ter. For CONNECT request, authority is recorded.
1097 • $protocol_version: HTTP version (e.g., HTTP/1.1, HTTP/2)
1099 The variable can be enclosed by "{" and "}" for disam‐
1101 biguation (e.g., ${remote_addr}).
1102 Default: $remote_addr - - [$time_local] "$request" $status
1104 $body_bytes_sent "$http_referer" "$http_user_agent"
1105 --accesslog-write-early
1107 Write access log when response header fields are re‐
1108 ceived from backend rather than when request transac‐
1109 tion finishes.
1110 --errorlog-file=<PATH>
1112 Set path to write error log. To reopen file, send USR1 signal
1113 to nghttpx. stderr will be redirected to the error log file
1114 unless --errorlog-syslog is used.
1115 Default: /dev/stderr
1117 --errorlog-syslog
1119 Send error log to syslog. If this option is used,
1120 --errorlog-file option is ignored.
1121 --syslog-facility=<FACILITY>
1123 Set syslog facility to <FACILITY>.
1124 Default: daemon
1126 HTTP
1128 --add-x-forwarded-for
1129 Append X-Forwarded-For header field to the downstream re‐
1130 quest.
1131 --strip-incoming-x-forwarded-for
1133 Strip X-Forwarded-For header field from inbound client re‐
1134 quests.
1135 --no-add-x-forwarded-proto
1137 Don't append additional X-Forwarded-Proto header field to the
1138 backend request. If inbound client sets X-For‐
1139 warded-Proto, and
1140 --no-strip-incoming-x-forwarded-proto option is used, they
1141 are passed to the backend.
1142 --no-strip-incoming-x-forwarded-proto
1144 Don't strip X-Forwarded-Proto header field from inbound client
1145 requests.
1146 --add-forwarded=<LIST>
1148 Append RFC 7239 Forwarded header field with parameters speci‐
1149 fied in comma delimited list <LIST>. The supported parameters
1150 are "by", "for", "host", and "proto". By default, the value
1151 of "by" and "for" parameters are obfuscated string.
1152 See --forwarded-by and --forwarded-for options respec‐
1153 tively. Note that nghttpx does not translate non-standard
1154 X-Forwarded-* header fields into Forwarded header field, and
1155 vice versa.
1156 --strip-incoming-forwarded
1158 Strip Forwarded header field from inbound client re‐
1159 quests.
1160 --forwarded-by=(obfuscated|ip|<VALUE>)
1162 Specify the parameter value sent out with "by" parameter of For‐
1163 warded header field. If "obfuscated" is given, the string is
1164 randomly generated at startup. If "ip" is given, the inter‐
1165 face address of the connection, including port number, is
1166 sent with "by" parameter. In case of UNIX domain socket, "lo‐
1167 calhost" is used instead of address and port. User can also
1168 specify the static obfuscated string. The limitation is that it
1169 must start with "_", and only consists of character
1170 set [A-Za-z0-9._-], as described in RFC 7239.
1171 Default: obfuscated
1173 --forwarded-for=(obfuscated|ip)
1175 Specify the parameter value sent out with "for" parame‐
1176 ter of Forwarded header field. If "obfuscated" is given, the
1177 string is randomly generated for each client connection. If
1178 "ip" is given, the remote client address of the connection,
1179 without port number, is sent with "for" parameter. In case
1180 of UNIX domain socket, "localhost" is used instead of ad‐
1181 dress.
1182 Default: obfuscated
1184 --no-via
1186 Don't append to Via header field. If Via header field is re‐
1187 ceived, it is left unaltered.
1188 --no-strip-incoming-early-data
1190 Don't strip Early-Data header field from inbound client re‐
1191 quests.
1192 --no-location-rewrite
1194 Don't rewrite location header field in default mode. When
1195 --http2-proxy is used, location header field will not be al‐
1196 tered regardless of this option.
1197 --host-rewrite
1199 Rewrite host and :authority header fields in default mode.
1200 When --http2-proxy is used, these headers will not be altered
1201 regardless of this option.
1202 --altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1204 Specify protocol ID, port, host and origin of alter‐
1205 native service. <HOST>, <ORIGIN> and <PARAMS> are optional.
1206 Empty <HOST> and <ORIGIN> are allowed and they are treated
1207 as nothing is specified. They are advertised in alt-svc
1208 header field only in HTTP/1.1 frontend. This option can be
1209 used multiple times to specify multiple alternative services.
1210 Example: --altsvc="h2,443,,,ma=3600; persist=1"
1211 --http2-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1213 Just like --altsvc option, but this altsvc is only sent in
1214 HTTP/2 frontend.
1215 --add-request-header=<HEADER>
1217 Specify additional header field to add to request header set.
1218 This option just appends header field and won't replace any‐
1219 thing already set. This option can be used several times
1220 to specify multiple header fields. Example:
1221 --add-request-header="foo: bar"
1222 --add-response-header=<HEADER>
1224 Specify additional header field to add to response header
1225 set. This option just appends header field and won't replace
1226 anything already set. This option can be used several times
1227 to specify multiple header fields. Example:
1228 --add-response-header="foo: bar"
1229 --request-header-field-buffer=<SIZE>
1231 Set maximum buffer size for incoming HTTP request header field
1232 list. This is the sum of header name and value in bytes. If
1233 trailer fields exist, they are counted towards this number.
1234 Default: 64K
1236 --max-request-header-fields=<N>
1238 Set maximum number of incoming HTTP request header fields.
1239 If trailer fields exist, they are counted towards this num‐
1240 ber.
1241 Default: 100
1243 --response-header-field-buffer=<SIZE>
1245 Set maximum buffer size for incoming HTTP response header
1246 field list. This is the sum of header name and value in
1247 bytes. If trailer fields exist, they are counted towards
1248 this number.
1249 Default: 64K
1251 --max-response-header-fields=<N>
1253 Set maximum number of incoming HTTP response header fields.
1254 If trailer fields exist, they are counted towards this num‐
1255 ber.
1256 Default: 500
1258 --error-page=(<CODE>|*)=<PATH>
1260 Set file path to custom error page served when nghttpx origi‐
1261 nally generates HTTP error status code <CODE>. <CODE> must
1262 be greater than or equal to 400, and at most 599. If "*" is
1263 used instead of <CODE>, it matches all HTTP status code. If
1264 error status code comes from backend server, the custom error
1265 pages are not used.
1266 --server-name=<NAME>
1268 Change server response header field value to <NAME>.
1269 Default: nghttpx
1271 --no-server-rewrite
1273 Don't rewrite server header field in default mode. When
1274 --http2-proxy is used, these headers will not be altered regard‐
1275 less of this option.
1276 --redirect-https-port=<PORT>
1278 Specify the port number which appears in Location header field
1279 when redirect to HTTPS URI is made due to "redi‐
1280 rect-if-not-tls" parameter in --backend option.
1281 Default: 443
1283 --require-http-scheme
1285 Always require http or https scheme in HTTP request. It also
1286 requires that https scheme must be used for an encrypted
1287 connection. Otherwise, http scheme must be used. This op‐
1288 tion is recommended for a server deployment which di‐
1289 rectly faces clients and the services it provides only require
1290 http or https scheme.
1291 API
1293 --api-max-request-body=<SIZE>
1294 Set the maximum size of request body for API request.
1295 Default: 32M
1297 DNS
1299 --dns-cache-timeout=<DURATION>
1300 Set duration that cached DNS results remain valid. Note that
1301 nghttpx caches the unsuccessful results as well.
1302 Default: 10s
1304 --dns-lookup-timeout=<DURATION>
1306 Set timeout that DNS server is given to respond to the initial
1307 DNS query. For the 2nd and later queries, server is given
1308 time based on this timeout, and it is scaled linearly.
1309 Default: 5s
1311 --dns-max-try=<N>
1313 Set the number of DNS query before nghttpx gives up name lookup.
1314 Default: 2
1316 --frontend-max-requests=<N>
1318 The number of requests that single frontend connection can
1319 process. For HTTP/2, this is the number of streams in one
1320 HTTP/2 connection. For HTTP/1, this is the number of keep
1321 alive requests. This is hint to nghttpx, and it may allow ad‐
1322 ditional few requests. The default value is unlimited.
1323 Debug
1325 --frontend-http2-dump-request-header=<PATH>
1326 Dumps request headers received by HTTP/2 frontend to the file
1327 denoted in <PATH>. The output is done in HTTP/1 header field
1328 format and each header block is followed by an empty line. This
1329 option is not thread safe and MUST NOT be used with option
1330 -n<N>, where <N> >= 2.
1331 --frontend-http2-dump-response-header=<PATH>
1333 Dumps response headers sent from HTTP/2 frontend to the file
1334 denoted in <PATH>. The output is done in HTTP/1 header field
1335 format and each header block is followed by an empty line. This
1336 option is not thread safe and MUST NOT be used with option
1337 -n<N>, where <N> >= 2.
1338 -o, --frontend-frame-debug
1340 Print HTTP/2 frames in frontend to stderr. This option is not
1341 thread safe and MUST NOT be used with option -n=N, where N
1342 >= 2.
1343 Process
1345 -D, --daemon
1346 Run in a background. If -D is used, the current working direc‐
1347 tory is changed to '/'.
1348 --pid-file=<PATH>
1350 Set path to save PID of this program.
1351 --user=<USER>
1353 Run this program as <USER>. This option is intended to be used
1354 to drop root privileges.
1355 --single-process
1357 Run this program in a single process mode for debugging pur‐
1358 pose. Without this option, nghttpx creates at least 2 pro‐
1359 cesses: main and worker processes. If this option is used,
1360 main and worker are unified into a single process.
1361 nghttpx still spawns additional process if neverbleed is
1362 used. In the single process mode, the signal handling fea‐
1363 ture is disabled.
1364 --max-worker-processes=<N>
1366 The maximum number of worker processes. nghttpx spawns new
1367 worker process when it reloads its configuration. The previ‐
1368 ous worker process enters graceful termination period and will
1369 terminate when it finishes handling the existing connec‐
1370 tions. However, if reloading configurations happen
1371 very frequently, the worker processes might be piled up if
1372 they take a bit long time to finish the existing connections.
1373 With this option, if the number of worker processes exceeds
1374 the given value, the oldest worker process is termi‐
1375 nated immediately. Specifying 0 means no limit and it is the
1376 default behaviour.
1377 --worker-process-grace-shutdown-period=<DURATION>
1379 Maximum period for a worker process to terminate grace‐
1380 fully. When a worker process enters in graceful shutdown
1381 period (e.g., when nghttpx reloads its configuration)
1382 and it does not finish handling the existing connections in
1383 the given period of time, it is immediately terminated. Speci‐
1384 fying 0 means no limit and it is the default behaviour.
1385 Scripting
1387 --mruby-file=<PATH>
1388 Set mruby script file
1389 --ignore-per-pattern-mruby-error
1391 Ignore mruby compile error for per-pattern mruby script file.
1392 If error occurred, it is treated as if no mruby file were
1393 specified for the pattern.
1394 HTTP/3 and QUIC
1396 --frontend-quic-idle-timeout=<DURATION>
1397 Specify an idle timeout for QUIC connection.
1398 Default: 30s
1400 --frontend-quic-debug-log
1402 Output QUIC debug log to /dev/stderr.
1403 --quic-bpf-program-file=<PATH>
1405 Specify a path to eBPF program file reuseport_kern.o to direct
1406 an incoming QUIC UDP datagram to a correct socket.
1407 Default: /usr/local/lib/nghttp2/reuseport_kern.o
1409 --frontend-quic-early-data
1411 Enable early data on frontend QUIC connections. nghttpx sends
1412 "Early-Data" header field to a backend server if a request is
1413 received in early data and handshake has not finished. All
1414 backend servers should deal with possibly replayed requests.
1415 --frontend-quic-qlog-dir=<DIR>
1417 Specify a directory where a qlog file is written for front‐
1418 end QUIC connections. A qlog file is created per each QUIC
1419 connection. The file name is ISO8601 basic format, followed
1420 by "-", server Source Connection ID and ".sqlog".
1421 --frontend-quic-require-token
1423 Require an address validation token for a frontend QUIC connec‐
1424 tion. Server sends a token in Retry packet or NEW_TOKEN
1425 frame in the previous connection.
1426 --frontend-quic-congestion-controller=<CC>
1428 Specify a congestion controller algorithm for a frontend QUIC
1429 connection. <CC> should be one of "cubic", "bbr", and "bbr2".
1430 Default: cubic
1432 --frontend-quic-secret-file=<PATH>
1434 Path to file that contains secure random data to be used as QUIC
1435 keying materials. It is used to derive keys for encrypting to‐
1436 kens and Connection IDs. It is not used to encrypt QUIC pack‐
1437 ets. Each line of this file must contain exactly 136
1438 bytes hex-encoded string (when decoded the byte string is 68
1439 bytes long). The first 2 bits of decoded byte string are
1440 used to identify the keying material. An empty line or a
1441 line which starts '#' is ignored. The file can contain more
1442 than one keying materials. Because the identifier is 2 bits,
1443 at most 4 keying materials are read and the remaining data is
1444 discarded. The first keying material in the file is primarily
1445 used for encryption and decryption for new connection. The
1446 other ones are used to decrypt data for the existing connec‐
1447 tions. Specifying multiple keying materials enables key ro‐
1448 tation. Please note that key rotation does not occur auto‐
1449 matically. User should update files or change options
1450 values and restart nghttpx gracefully. If opening or read‐
1451 ing given file fails, all loaded keying materials are dis‐
1452 carded and it is treated as if none of this option is given.
1453 If this option is not given or an error occurred while opening
1454 or reading a file, a keying material is generated inter‐
1455 nally on startup and reload.
1456 --quic-server-id=<HEXSTRING>
1458 Specify server ID encoded in Connection ID to identify this
1459 particular server instance. Connection ID is encrypted and
1460 this part is not visible in public. It must be 4 bytes long
1461 and must be encoded in hex string (which is 8 bytes long). If
1462 this option is omitted, a random server ID is generated
1463 on startup and configuration reload.
1464 --frontend-quic-initial-rtt=<DURATION>
1466 Specify the initial RTT of the frontend QUIC connection.
1467 Default: 333ms
1469 --no-quic-bpf
1471 Disable eBPF.
1472 --frontend-http3-window-size=<SIZE>
1474 Sets the per-stream initial window size of HTTP/3 front‐
1475 end connection.
1476 Default: 256K
1478 --frontend-http3-connection-window-size=<SIZE>
1480 Sets the per-connection window size of HTTP/3 frontend connec‐
1481 tion.
1482 Default: 1M
1484 --frontend-http3-max-window-size=<SIZE>
1486 Sets the maximum per-stream window size of HTTP/3 front‐
1487 end connection. The window size is adjusted based on the re‐
1488 ceiving rate of stream data. The initial value is the value
1489 specified by --frontend-http3-window-size and the window size
1490 grows up to <SIZE> bytes.
1491 Default: 6M
1493 --frontend-http3-max-connection-window-size=<SIZE>
1495 Sets the maximum per-connection window size of HTTP/3 front‐
1496 end connection. The window size is adjusted based on the re‐
1497 ceiving rate of stream data. The initial value is the
1498 value specified by
1499 --frontend-http3-connection-window-size and the window size
1500 grows up to <SIZE> bytes.
1501 Default: 8M
1503 --frontend-http3-max-concurrent-streams=<N>
1505 Set the maximum number of the concurrent streams in one front‐
1506 end HTTP/3 connection.
1507 Default: 100
1509 Misc
1511 --conf=<PATH>
1512 Load configuration from <PATH>. Please note that nghttpx
1513 always tries to read the default configuration file if --conf
1514 is not given.
1515 Default: /etc/nghttpx/nghttpx.conf
1517 --include=<PATH>
1519 Load additional configurations from <PATH>. File <PATH> is
1520 read when configuration parser encountered this option.
1521 This option can be used multiple times, or even recursively.
1522 -v, --version
1524 Print version and exit.
1525 -h, --help
1527 Print this help and exit.
1528 The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
1530 * 1024). Units are K, M and G (powers of 1024).
1531 The <DURATION> argument is an integer and an optional unit (e.g., 1s is
1533 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
1534 (hours, minutes, seconds and milliseconds, respectively). If a unit is
1535 omitted, a second is used as unit.
1536
1538 /etc/nghttpx/nghttpx.conf
1539 The default configuration file path nghttpx searches at startup.
1540 The configuration file path can be changed using --conf option.
1541 Those lines which are staring # are treated as comment.
1543 The option name in the configuration file is the long com‐
1545 mand-line option name with leading -- stripped (e.g., frontend).
1546 Put = between option name and value. Don't put extra leading or
1547 trailing spaces.
1548 When specifying arguments including characters which have spe‐
1550 cial meaning to a shell, we usually use quotes so that shell
1551 does not interpret them. When writing this configuration file,
1552 quotes for this purpose must not be used. For example, specify
1553 additional request header field, do this:
1554 add-request-header=foo: bar
1556 instead of:
1558 add-request-header="foo: bar"
1560 The options which do not take argument in the command-line take
1562 argument in the configuration file. Specify yes as an argument
1563 (e.g., http2-proxy=yes). If other string is given, it is ig‐
1564 nored.
1565 To specify private key and certificate file which are given as
1567 positional arguments in command-line, use private-key-file and
1568 certificate-file.
1569 --conf option cannot be used in the configuration file and will
1571 be ignored if specified.
1572 Error log
1574 Error log is written to stderr by default. It can be configured
1575 using --errorlog-file. The format of log message is as follows:
1576 <datetime> <main-pid> <current-pid> <thread-id> <level> (<file‐
1578 name>:<line>) <msg>
1579 <datetime>
1581 It is a combination of date and time when the log is
1582 written. It is in ISO 8601 format.
1583 <main-pid>
1585 It is a main process ID.
1586 <current-pid>
1588 It is a process ID which writes this log.
1589 <thread-id>
1591 It is a thread ID which writes this log. It would be
1592 unique within <current-pid>.
1593 <filename> and <line>
1595 They are source file name, and line number which produce
1596 this log.
1597 <msg> It is a log message body.
1599
1601 SIGQUIT
1602 Shutdown gracefully. First accept pending connections and stop
1603 accepting connection. After all connections are handled,
1604 nghttpx exits.
1605 SIGHUP Reload configuration file given in --conf.
1607 SIGUSR1
1609 Reopen log files.
1610 SIGUSR2
1612 Fork and execute nghttpx. It will execute the binary in the same
1613 path with same command-line arguments and environment variables. As
1614 of nghttpx version 1.20.0, the new main process sends SIGQUIT to the
1615 original main process when it is ready to serve requests. For the
1616 earlier versions of nghttpx, user has to send SIGQUIT to the origi‐
1617 nal main process.
1618 The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
1620 is usually used to execute new binary, and the main process is newly
1621 spawned. On the other hand, the latter just reloads configuration
1622 file, and the same main process continues to exist.
1623 NOTE:
1625 nghttpx consists of multiple processes: one process for processing
1626 these signals, and another one for processing requests. The former
1627 spawns the latter. The former is called main process, and the lat‐
1628 ter is called worker process. If neverbleed is enabled, the worker
1629 process spawns neverbleed daemon process which does RSA key process‐
1630 ing. The above signal must be sent to the main process. If the
1631 other processes received one of them, it is ignored. This behaviour
1632 of these processes may change in the future release. In other
1633 words, in the future release, the processes other than main process
1634 may terminate upon the reception of these signals. Therefore these
1635 signals should not be sent to the processes other than main process.
1636
1638 nghttpx supports HTTP/2 server push in default mode with Link header
1639 field. nghttpx looks for Link header field (RFC 5988) in response
1640 headers from backend server and extracts URI-reference with parameter
1641 rel=preload (see preload) and pushes those URIs to the frontend client.
1642 Here is a sample Link header field to initiate server push:
1643 Link: </fonts/font.woff>; rel=preload
1645 Link: </css/theme.css>; rel=preload
1646 Currently, the following restriction is applied for server push:
1648 1. The associated stream must have method "GET" or "POST". The associ‐
1650 ated stream's status code must be 200.
1651 This limitation may be loosened in the future release.
1653 nghttpx also supports server push if both frontend and backend are
1655 HTTP/2 in default mode. In this case, in addition to server push via
1656 Link header field, server push from backend is forwarded to frontend
1657 HTTP/2 session.
1658 HTTP/2 server push will be disabled if --http2-proxy is used.
1660
1662 nghttpx supports UNIX domain socket with a filename for both frontend
1663 and backend connections.
1664 Please note that current nghttpx implementation does not delete a
1666 socket with a filename. And on start up, if nghttpx detects that the
1667 specified socket already exists in the file system, nghttpx first
1668 deletes it. However, if SIGUSR2 is used to execute new binary and both
1669 old and new configurations use same filename, new binary does not
1670 delete the socket and continues to use it.
1671
1673 OCSP query is done using external Python script fetch-ocsp-response,
1674 which has been originally developed in Perl as part of h2o project (‐
1675 https://github.com/h2o/h2o), and was translated into Python.
1676 The script file is usually installed under $(prefix)/share/nghttp2/ di‐
1678 rectory. The actual path to script can be customized using
1679 --fetch-ocsp-response-file option.
1680 If OCSP query is failed, previous OCSP response, if any, is continued
1682 to be used.
1683 --fetch-ocsp-response-file option provides wide range of possibility to
1685 manage OCSP response. It can take an arbitrary script or executable.
1686 The requirement is that it supports the command-line interface of
1687 fetch-ocsp-response script, and it must return a valid DER encoded OCSP
1688 response on success. It must return exit code 0 on success, and 75 for
1689 temporary error, and the other error code for generic failure. For
1690 large cluster of servers, it is not efficient for each server to per‐
1691 form OCSP query using fetch-ocsp-response. Instead, you can retrieve
1692 OCSP response in some way, and store it in a disk or a shared database.
1693 Then specify a program in --fetch-ocsp-response-file to fetch it from
1694 those stores. This could provide a way to share the OCSP response be‐
1695 tween fleet of servers, and also any OCSP query strategy can be applied
1696 which may be beyond the ability of nghttpx itself or fetch-ocsp-re‐
1697 sponse script.
1698
1700 nghttpx supports TLS session resumption through both session ID and
1701 session ticket.
1702 SESSION ID RESUMPTION
1704 By default, session ID is shared by all worker threads.
1705 If --tls-session-cache-memcached is given, nghttpx will insert serial‐
1707 ized session data to memcached with nghttpx:tls-session-cache: + lower‐
1708 case hex string of session ID as a memcached entry key, with expiry
1709 time 12 hours. Session timeout is set to 12 hours.
1710 By default, connections to memcached server are not encrypted. To en‐
1712 able encryption, use tls keyword in --tls-session-cache-memcached op‐
1713 tion.
1714 TLS SESSION TICKET RESUMPTION
1716 By default, session ticket is shared by all worker threads. The auto‐
1717 matic key rotation is also enabled by default. Every an hour, new en‐
1718 cryption key is generated, and previous encryption key becomes decryp‐
1719 tion only key. We set session timeout to 12 hours, and thus we keep at
1720 most 12 keys.
1721 If --tls-ticket-key-memcached is given, encryption keys are retrieved
1723 from memcached. nghttpx just reads keys from memcached; one has to de‐
1724 ploy key generator program to update keys frequently (e.g., every 1
1725 hour). The example key generator tlsticketupdate.go is available under
1726 contrib directory in nghttp2 archive. The memcached entry key is
1727 nghttpx:tls-ticket-key. The data format stored in memcached is the bi‐
1728 nary format described below:
1729 +--------------+-------+----------------+
1731 | VERSION (4) |LEN (2)|KEY(48 or 80) ...
1732 +--------------+-------+----------------+
1733 ^ |
1734 | |
1735 +------------------------+
1736 (LEN, KEY) pair can be repeated
1737 All numbers in the above figure is bytes. All integer fields are net‐
1739 work byte order.
1740 First 4 bytes integer VERSION field, which must be 1. The 2 bytes in‐
1742 teger LEN field gives the length of following KEY field, which contains
1743 key. If --tls-ticket-key-cipher=aes-128-cbc is used, LEN must be 48.
1744 If --tls-ticket-key-cipher=aes-256-cbc is used, LEN must be 80. LEN
1745 and KEY pair can be repeated multiple times to store multiple keys.
1746 The key appeared first is used as encryption key. All the remaining
1747 keys are used as decryption only.
1748 By default, connections to memcached server are not encrypted. To en‐
1750 able encryption, use tls keyword in --tls-ticket-key-memcached option.
1751 If --tls-ticket-key-file is given, encryption key is read from the
1753 given file. In this case, nghttpx does not rotate key automatically.
1754 To rotate key, one has to restart nghttpx (see SIGNALS).
1755
1757 nghttpx supports TLS signed_certificate_timestamp extension (RFC 6962).
1758 The relevant options are --tls-sct-dir and sct-dir parameter in
1759 --subcert. They takes a directory, and nghttpx reads all files whose
1760 extension is .sct under the directory. The *.sct files are encoded as
1761 SignedCertificateTimestamp struct described in section 3.2 of RFC
1762 69662. This format is the same one used by nginx-ct and mod_ssl_ct.
1763 ct-submit can be used to submit certificates to log servers, and obtain
1764 the SignedCertificateTimestamp struct which can be used with nghttpx.
1765
1767 WARNING:
1768 The current mruby extension API is experimental and not frozen. The
1769 API is subject to change in the future release.
1770 WARNING:
1772 Almost all string value returned from method, or attribute is a
1773 fresh new mruby string, which involves memory allocation, and
1774 copies. Therefore, it is strongly recommended to store a return
1775 value in a local variable, and use it, instead of calling method or
1776 accessing attribute repeatedly.
1777 nghttpx allows users to extend its capability using mruby scripts.
1779 nghttpx has 2 hook points to execute mruby script: request phase and
1780 response phase. The request phase hook is invoked after all request
1781 header fields are received from client. The response phase hook is in‐
1782 voked after all response header fields are received from backend
1783 server. These hooks allows users to modify header fields, or common
1784 HTTP variables, like authority or request path, and even return custom
1785 response without forwarding request to backend servers.
1786 There are 2 levels of mruby script invocations: global and per-pattern.
1788 The global mruby script is set by --mruby-file option and is called for
1789 all requests. The per-pattern mruby script is set by "mruby" parameter
1790 in -b option. It is invoked for a request which matches the particular
1791 pattern. The order of hook invocation is: global request phase hook,
1792 per-pattern request phase hook, per-pattern response phase hook, and
1793 finally global response phase hook. If a hook returns a response, any
1794 later hooks are not invoked. The global request hook is invoked before
1795 the pattern matching is made and changing request path may affect the
1796 pattern matching.
1797 Please note that request and response hooks of per-pattern mruby script
1799 for a single request might not come from the same script. This might
1800 happen after a request hook is executed, backend failed for some rea‐
1801 son, and at the same time, backend configuration is replaced by API re‐
1802 quest, and then the request uses new configuration on retry. The re‐
1803 sponse hook from new configuration, if it is specified, will be in‐
1804 voked.
1805 The all mruby script will be evaluated once per thread on startup, and
1807 it must instantiate object and evaluate it as the return value (e.g.,
1808 App.new). This object is called app object. If app object defines
1809 on_req method, it is called with Nghttpx::Env object on request hook.
1810 Similarly, if app object defines on_resp method, it is called with
1811 Nghttpx::Env object on response hook. For each method invocation, user
1812 can can access Nghttpx::Request and Nghttpx::Response objects via
1813 Nghttpx::Env#req and Nghttpx::Env#resp respectively.
1814 Nghttpx::REQUEST_PHASE
1816 Constant to represent request phase.
1817 Nghttpx::RESPONSE_PHASE
1819 Constant to represent response phase.
1820 class Nghttpx::Env
1822 Object to represent current request specific context.
1823 attribute [R] req
1825 Return Request object.
1826 attribute [R] resp
1828 Return Response object.
1829 attribute [R] ctx
1831 Return Ruby hash object. It persists until request fin‐
1832 ishes. So values set in request phase hook can be re‐
1833 trieved in response phase hook.
1834 attribute [R] phase
1836 Return the current phase.
1837 attribute [R] remote_addr
1839 Return IP address of a remote client. If connection is
1840 made via UNIX domain socket, this returns the string "lo‐
1841 calhost".
1842 attribute [R] server_addr
1844 Return address of server that accepted the connection.
1845 This is a string which specified in --frontend option,
1846 excluding port number, and not a resolved IP address.
1847 For UNIX domain socket, this is a path to UNIX domain
1848 socket.
1849 attribute [R] server_port
1851 Return port number of the server frontend which accepted
1852 the connection from client.
1853 attribute [R] tls_used
1855 Return true if TLS is used on the connection.
1856 attribute [R] tls_sni
1858 Return the TLS SNI value which client sent in this con‐
1859 nection.
1860 attribute [R] tls_client_fingerprint_sha256
1862 Return the SHA-256 fingerprint of a client certificate.
1863 attribute [R] tls_client_fingerprint_sha1
1865 Return the SHA-1 fingerprint of a client certificate.
1866 attribute [R] tls_client_issuer_name
1868 Return the issuer name of a client certificate.
1869 attribute [R] tls_client_subject_name
1871 Return the subject name of a client certificate.
1872 attribute [R] tls_client_serial
1874 Return the serial number of a client certificate.
1875 attribute [R] tls_client_not_before
1877 Return the start date of a client certificate in seconds
1878 since the epoch.
1879 attribute [R] tls_client_not_after
1881 Return the end date of a client certificate in seconds
1882 since the epoch.
1883 attribute [R] tls_cipher
1885 Return a TLS cipher negotiated in this connection.
1886 attribute [R] tls_protocol
1888 Return a TLS protocol version negotiated in this connec‐
1889 tion.
1890 attribute [R] tls_session_id
1892 Return a session ID for this connection in hex string.
1893 attribute [R] tls_session_reused
1895 Return true if, and only if a SSL/TLS session is reused.
1896 attribute [R] alpn
1898 Return ALPN identifier negotiated in this connection.
1899 attribute [R] tls_handshake_finished
1901 Return true if SSL/TLS handshake has finished. If it re‐
1902 turns false in the request phase hook, the request is re‐
1903 ceived in TLSv1.3 early data (0-RTT) and might be vulner‐
1904 able to the replay attack. nghttpx will send Early-Data
1905 header field to backend servers to indicate this.
1906 class Nghttpx::Request
1908 Object to represent request from client. The modification to
1909 Request object is allowed only in request phase hook.
1910 attribute [R] http_version_major
1912 Return HTTP major version.
1913 attribute [R] http_version_minor
1915 Return HTTP minor version.
1916 attribute [R/W] method
1918 HTTP method. On assignment, copy of given value is as‐
1919 signed. We don't accept arbitrary method name. We will
1920 document them later, but well known methods, like GET,
1921 PUT and POST, are all supported.
1922 attribute [R/W] authority
1924 Authority (i.e., example.org), including optional port
1925 component . On assignment, copy of given value is as‐
1926 signed.
1927 attribute [R/W] scheme
1929 Scheme (i.e., http, https). On assignment, copy of given
1930 value is assigned.
1931 attribute [R/W] path
1933 Request path, including query component (i.e., /in‐
1934 dex.html). On assignment, copy of given value is as‐
1935 signed. The path does not include authority component of
1936 URI. This may include query component. nghttpx makes
1937 certain normalization for path. It decodes percent-en‐
1938 coding for unreserved characters (see
1939 https://tools.ietf.org/html/rfc3986#section-2.3), and re‐
1940 solves ".." and ".". But it may leave characters which
1941 should be percent-encoded as is. So be careful when com‐
1942 paring path against desired string.
1943 attribute [R] headers
1945 Return Ruby hash containing copy of request header
1946 fields. Changing values in returned hash does not change
1947 request header fields actually used in request process‐
1948 ing. Use Nghttpx::Request#add_header or
1949 Nghttpx::Request#set_header to change request header
1950 fields.
1951 add_header(key, value)
1953 Add header entry associated with key. The value can be
1954 single string or array of string. It does not replace
1955 any existing values associated with key.
1956 set_header(key, value)
1958 Set header entry associated with key. The value can be
1959 single string or array of string. It replaces any exist‐
1960 ing values associated with key.
1961 clear_headers()
1963 Clear all existing request header fields.
1964 push(uri)
1966 Initiate to push resource identified by uri. Only HTTP/2
1967 protocol supports this feature. For the other protocols,
1968 this method is noop. uri can be absolute URI, absolute
1969 path or relative path to the current request. For abso‐
1970 lute or relative path, scheme and authority are inherited
1971 from the current request. Currently, method is always
1972 GET. nghttpx will issue request to backend servers to
1973 fulfill this request. The request and response phase
1974 hooks will be called for pushed resource as well.
1975 class Nghttpx::Response
1977 Object to represent response from backend server.
1978 attribute [R] http_version_major
1980 Return HTTP major version.
1981 attribute [R] http_version_minor
1983 Return HTTP minor version.
1984 attribute [R/W] status
1986 HTTP status code. It must be in the range [200, 999],
1987 inclusive. The non-final status code is not supported in
1988 mruby scripting at the moment.
1989 attribute [R] headers
1991 Return Ruby hash containing copy of response header
1992 fields. Changing values in returned hash does not change
1993 response header fields actually used in response process‐
1994 ing. Use Nghttpx::Response#add_header or
1995 Nghttpx::Response#set_header to change response header
1996 fields.
1997 add_header(key, value)
1999 Add header entry associated with key. The value can be
2000 single string or array of string. It does not replace
2001 any existing values associated with key.
2002 set_header(key, value)
2004 Set header entry associated with key. The value can be
2005 single string or array of string. It replaces any exist‐
2006 ing values associated with key.
2007 clear_headers()
2009 Clear all existing response header fields.
2010 return(body)
2012 Return custom response body to a client. When this
2013 method is called in request phase hook, the request is
2014 not forwarded to the backend, and response phase hook for
2015 this request will not be invoked. When this method is
2016 called in response phase hook, response from backend
2017 server is canceled and discarded. The status code and
2018 response header fields should be set before using this
2019 method. To set status code, use
2020 Nghttpx::Response#status. If status code is not set, 200
2021 is used. To set response header fields,
2022 Nghttpx::Response#add_header and
2023 Nghttpx::Response#set_header. When this method is in‐
2024 voked in response phase hook, the response headers are
2025 filled with the ones received from backend server. To
2026 send completely custom header fields, first call
2027 Nghttpx::Response#clear_headers to erase all existing
2028 header fields, and then add required header fields. It
2029 is an error to call this method twice for a given re‐
2030 quest.
2031 send_info(status, headers)
2033 Send non-final (informational) response to a client.
2034 status must be in the range [100, 199], inclusive. head‐
2035 ers is a hash containing response header fields. Its key
2036 must be a string, and the associated value must be either
2037 string or array of strings. Since this is not a final
2038 response, even if this method is invoked, request is
2039 still forwarded to a backend unless
2040 Nghttpx::Response#return is called. This method can be
2041 called multiple times. It cannot be called after
2042 Nghttpx::Response#return is called.
2043 MRUBY EXAMPLES
2045 Modify request path:
2046 class App
2048 def on_req(env)
2049 env.req.path = "/apps#{env.req.path}"
2050 end
2051 end
2052 App.new
2054 Don't forget to instantiate and evaluate object at the last line.
2056 Restrict permission of viewing a content to a specific client ad‐
2058 dresses:
2059 class App
2061 def on_req(env)
2062 allowed_clients = ["127.0.0.1", "::1"]
2063 if env.req.path.start_with?("/log/") &&
2065 !allowed_clients.include?(env.remote_addr) then
2066 env.resp.status = 404
2067 env.resp.return "permission denied"
2068 end
2069 end
2070 end
2071 App.new
2073
2075 nghttpx exposes API endpoints to manipulate it via HTTP based API. By
2076 default, API endpoint is disabled. To enable it, add a dedicated
2077 frontend for API using --frontend option with "api" parameter. All re‐
2078 quests which come from this frontend address, will be treated as API
2079 request.
2080 The response is normally JSON dictionary, and at least includes the
2082 following keys:
2083 status The status of the request processing. The following values are
2085 defined:
2086 Success
2088 The request was successful.
2089 Failure
2091 The request was failed. No change has been made.
2092 code HTTP status code
2094 Additionally, depending on the API endpoint, data key may be present,
2096 and its value contains the API endpoint specific data.
2097 We wrote "normally", since nghttpx may return ordinal HTML response in
2099 some cases where the error has occurred before reaching API endpoint
2100 (e.g., header field is too large).
2101 The following section describes available API endpoints.
2103 POST /api/v1beta1/backendconfig
2105 This API replaces the current backend server settings with the re‐
2106 quested ones. The request method should be POST, but PUT is also ac‐
2107 ceptable. The request body must be nghttpx configuration file format.
2108 For configuration file format, see FILES section. The line separator
2109 inside the request body must be single LF (0x0A). Currently, only
2110 backend option is parsed, the others are simply ignored. The semantics
2111 of this API is replace the current backend with the backend options in
2112 request body. Describe the desired set of backend severs, and nghttpx
2113 makes it happen. If there is no backend option is found in request
2114 body, the current set of backend is replaced with the backend option's
2115 default value, which is 127.0.0.1,80.
2116 The replacement is done instantly without breaking existing connections
2118 or requests. It also avoids any process creation as is the case with
2119 hot swapping with signals.
2120 The one limitation is that only numeric IP address is allowed in
2122 backend in request body unless "dns" parameter is used while non nu‐
2123 meric hostname is allowed in command-line or configuration file is read
2124 using --conf.
2125 GET /api/v1beta1/configrevision
2127 This API returns configuration revision of the current nghttpx. The
2128 configuration revision is opaque string, and it changes after each
2129 reloading by SIGHUP. With this API, an external application knows that
2130 whether nghttpx has finished reloading its configuration by comparing
2131 the configuration revisions between before and after reloading. It is
2132 recommended to disable persistent (keep-alive) connection for this pur‐
2133 pose in order to avoid to send a request using the reused connection
2134 which may bound to an old process.
2135 This API returns response including data key. Its value is JSON ob‐
2137 ject, and it contains at least the following key:
2138 configRevision
2140 The configuration revision of the current nghttpx
2141
2143 nghttp(1), nghttpd(1), h2load(1)
2144
2146 Tatsuhiro Tsujikawa
2147
2149 2012, 2015, 2016, Tatsuhiro Tsujikawa
21501.55.1 Jul 14, 2023 NGHTTPX(1)