1 .\" Man page generated from reStructuredText.
3 .TH "NGHTTPX" "1" "Oct 19, 2021" "1.46.0" "nghttp2"
5 nghttpx \- HTTP/2 proxy
7 .nr rst2man-indent-level 0
11 level \\n[rst2man-indent-level]
12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
19 .\" .rstReportMargin pre:
21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
22 . nr rst2man-indent-level +1
23 .\" .rstReportMargin post:
27 .\" indent \\n[an-margin]
28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .nr rst2man-indent-level -1
30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
35 \fBnghttpx\fP [OPTIONS]... [<PRIVATE_KEY> <CERT>]
38 A reverse proxy for HTTP/3, HTTP/2, and HTTP/1.
42 Set path to server\(aqs private key. Required unless
43 "no\-tls" parameter is used in \fI\%\-\-frontend\fP option.
48 Set path to server\(aqs certificate. Required unless
49 "no\-tls" parameter is used in \fI\%\-\-frontend\fP option. To
50 make OCSP stapling work, this must be an absolute path.
54 The options are categorized into several groups.
58 .B \-b, \-\-backend=(<HOST>,<PORT>|unix:<PATH>)[;[<PATTERN>[:...]][[;<PARAM>]...]
59 Set backend host and port. The multiple backend
60 addresses are accepted by repeating this option. UNIX
61 domain socket can be specified by prefixing path name
62 with "unix:" (e.g., unix:/var/run/backend.sock).
64 Optionally, if <PATTERN>s are given, the backend address
65 is only used if request matches the pattern. The
66 pattern matching is closely designed to ServeMux in
67 net/http package of Go programming language. <PATTERN>
68 consists of path, host + path or just host. The path
69 must start with "\fI/\fP". If it ends with "\fI/\fP", it matches
70 all request path in its subtree. To deal with the
71 request to the directory without trailing slash, the
72 path which ends with "\fI/\fP" also matches the request path
73 which only lacks trailing \(aq\fI/\fP\(aq (e.g., path "\fI/foo/\fP"
74 matches request path "\fI/foo\fP"). If it does not end with
75 "\fI/\fP", it performs exact match against the request path.
76 If host is given, it performs a match against the
77 request host. For a request received on the frontend
78 listener with "sni\-fwd" parameter enabled, SNI host is
79 used instead of a request host. If host alone is given,
80 "\fI/\fP" is appended to it, so that it matches all request
81 paths under the host (e.g., specifying "nghttp2.org"
82 equals to "nghttp2.org/"). CONNECT method is treated
83 specially. It does not have path, and we don\(aqt allow
84 empty path. To workaround this, we assume that CONNECT
85 method has "\fI/\fP" as path.
87 Patterns with host take precedence over patterns with
88 just path. Then, longer patterns take precedence over
91 Host can include "*" in the left most position to
92 indicate wildcard match (only suffix match is done).
93 The "*" must match at least one character. For example,
94 host pattern "*.nghttp2.org" matches against
95 "www.nghttp2.org" and "git.ngttp2.org", but does not
96 match against "nghttp2.org". The exact hosts match
97 takes precedence over the wildcard hosts match.
99 If path part ends with "*", it is treated as wildcard
100 path. The wildcard path behaves differently from the
101 normal path. For normal path, match is made around the
102 boundary of path component separator,"\fI/\fP". On the other
103 hand, the wildcard path does not take into account the
104 path component separator. All paths which include the
105 wildcard path without last "*" as prefix, and are
106 strictly longer than wildcard path without last "*" are
107 matched. "*" must match at least one character. For
108 example, the pattern "\fI/foo*\fP" matches "\fI/foo/\fP" and
109 "\fI/foobar\fP". But it does not match "\fI/foo\fP", or "\fI/fo\fP".
111 If <PATTERN> is omitted or empty string, "\fI/\fP" is used as
112 pattern, which matches all request paths (catch\-all
113 pattern). The catch\-all backend must be given.
115 When doing a match, nghttpx made some normalization to
116 pattern, request host and path. For host part, they are
117 converted to lower case. For path part, percent\-encoded
118 unreserved characters defined in RFC 3986 are decoded,
119 and any dot\-segments (".." and ".") are resolved and
122 For example, \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org/httpbin/\(aq
123 matches the request host "nghttp2.org" and the request
124 path "\fI/httpbin/get\fP", but does not match the request host
125 "nghttp2.org" and the request path "\fI/index.html\fP".
127 The multiple <PATTERN>s can be specified, delimiting
128 them by ":". Specifying
129 \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org:www.nghttp2.org\(aq has the
130 same effect to specify \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org\(aq
131 and \fI\%\-b\fP\(aq127.0.0.1,8080;www.nghttp2.org\(aq.
133 The backend addresses sharing same <PATTERN> are grouped
134 together forming load balancing group.
136 Several parameters <PARAM> are accepted after <PATTERN>.
137 The parameters are delimited by ";". The available
138 parameters are: "proto=<PROTO>", "tls",
139 "sni=<SNI_HOST>", "fall=<N>", "rise=<N>",
140 "affinity=<METHOD>", "dns", "redirect\-if\-not\-tls",
141 "upgrade\-scheme", "mruby=<PATH>",
142 "read\-timeout=<DURATION>", "write\-timeout=<DURATION>",
143 "group=<GROUP>", "group\-weight=<N>", "weight=<N>", and
144 "dnf". The parameter consists of keyword, and
145 optionally followed by "=" and value. For example, the
146 parameter "proto=h2" consists of the keyword "proto" and
147 value "h2". The parameter "tls" consists of the keyword
148 "tls" without value. Each parameter is described as
151 The backend application protocol can be specified using
152 optional "proto" parameter, and in the form of
153 "proto=<PROTO>". <PROTO> should be one of the following
154 list without quotes: "h2", "http/1.1". The default
155 value of <PROTO> is "http/1.1". Note that usually "h2"
156 refers to HTTP/2 over TLS. But in this option, it may
157 mean HTTP/2 over cleartext TCP unless "tls" keyword is
160 TLS can be enabled by specifying optional "tls"
161 parameter. TLS is not enabled by default.
163 With "sni=<SNI_HOST>" parameter, it can override the TLS
164 SNI field value with given <SNI_HOST>. This will
165 default to the backend <HOST> name
167 The feature to detect whether backend is online or
168 offline can be enabled using optional "fall" and "rise"
169 parameters. Using "fall=<N>" parameter, if nghttpx
170 cannot connect to a this backend <N> times in a row,
171 this backend is assumed to be offline, and it is
172 excluded from load balancing. If <N> is 0, this backend
173 never be excluded from load balancing whatever times
174 nghttpx cannot connect to it, and this is the default.
175 There is also "rise=<N>" parameter. After backend was
176 excluded from load balancing group, nghttpx periodically
177 attempts to make a connection to the failed backend, and
178 if the connection is made successfully <N> times in a
179 row, the backend is assumed to be online, and it is now
180 eligible for load balancing target. If <N> is 0, a
181 backend is permanently offline, once it goes in that
182 state, and this is the default behaviour.
184 The session affinity is enabled using
185 "affinity=<METHOD>" parameter. If "ip" is given in
186 <METHOD>, client IP based session affinity is enabled.
187 If "cookie" is given in <METHOD>, cookie based session
188 affinity is enabled. If "none" is given in <METHOD>,
189 session affinity is disabled, and this is the default.
190 The session affinity is enabled per <PATTERN>. If at
191 least one backend has "affinity" parameter, and its
192 <METHOD> is not "none", session affinity is enabled for
193 all backend servers sharing the same <PATTERN>. It is
194 advised to set "affinity" parameter to all backend
195 explicitly if session affinity is desired. The session
196 affinity may break if one of the backend gets
197 unreachable, or backend settings are reloaded or
200 If "affinity=cookie" is used, the additional
201 configuration is required.
202 "affinity\-cookie\-name=<NAME>" must be used to specify a
203 name of cookie to use. Optionally,
204 "affinity\-cookie\-path=<PATH>" can be used to specify a
205 path which cookie is applied. The optional
206 "affinity\-cookie\-secure=<SECURE>" controls the Secure
207 attribute of a cookie. The default value is "auto", and
208 the Secure attribute is determined by a request scheme.
209 If a request scheme is "https", then Secure attribute is
210 set. Otherwise, it is not set. If <SECURE> is "yes",
211 the Secure attribute is always set. If <SECURE> is
212 "no", the Secure attribute is always omitted.
214 By default, name resolution of backend host name is done
215 at start up, or reloading configuration. If "dns"
216 parameter is given, name resolution takes place
217 dynamically. This is useful if backend address changes
218 frequently. If "dns" is given, name resolution of
219 backend host name at start up, or reloading
220 configuration is skipped.
222 If "redirect\-if\-not\-tls" parameter is used, the matched
223 backend requires that frontend connection is TLS
224 encrypted. If it isn\(aqt, nghttpx responds to the request
225 with 308 status code, and https URI the client should
226 use instead is included in Location header field. The
227 port number in redirect URI is 443 by default, and can
228 be changed using \fI\%\-\-redirect\-https\-port\fP option. If at
229 least one backend has "redirect\-if\-not\-tls" parameter,
230 this feature is enabled for all backend servers sharing
231 the same <PATTERN>. It is advised to set
232 "redirect\-if\-no\-tls" parameter to all backends
233 explicitly if this feature is desired.
235 If "upgrade\-scheme" parameter is used along with "tls"
236 parameter, HTTP/2 :scheme pseudo header field is changed
237 to "https" from "http" when forwarding a request to this
238 particular backend. This is a workaround for a backend
239 server which requires "https" :scheme pseudo header
240 field on TLS encrypted connection.
242 "mruby=<PATH>" parameter specifies a path to mruby
243 script file which is invoked when this pattern is
244 matched. All backends which share the same pattern must
245 have the same mruby path.
247 "read\-timeout=<DURATION>" and "write\-timeout=<DURATION>"
248 parameters specify the read and write timeout of the
249 backend connection when this pattern is matched. All
250 backends which share the same pattern must have the same
251 timeouts. If these timeouts are entirely omitted for a
252 pattern, \fI\%\-\-backend\-read\-timeout\fP and
253 \fI\%\-\-backend\-write\-timeout\fP are used.
255 "group=<GROUP>" parameter specifies the name of group
256 this backend address belongs to. By default, it belongs
257 to the unnamed default group. The name of group is
258 unique per pattern. "group\-weight=<N>" parameter
259 specifies the weight of the group. The higher weight
260 gets more frequently selected by the load balancing
261 algorithm. <N> must be [1, 256] inclusive. The weight
262 8 has 4 times more weight than 2. <N> must be the same
263 for all addresses which share the same <GROUP>. If
264 "group\-weight" is omitted in an address, but the other
265 address which belongs to the same group specifies
266 "group\-weight", its weight is used. If no
267 "group\-weight" is specified for all addresses, the
268 weight of a group becomes 1. "group" and "group\-weight"
269 are ignored if session affinity is enabled.
271 "weight=<N>" parameter specifies the weight of the
272 backend address inside a group which this address
273 belongs to. The higher weight gets more frequently
274 selected by the load balancing algorithm. <N> must be
275 [1, 256] inclusive. The weight 8 has 4 times more
276 weight than weight 2. If this parameter is omitted,
277 weight becomes 1. "weight" is ignored if session
280 If "dnf" parameter is specified, an incoming request is
281 not forwarded to a backend and just consumed along with
282 the request body (actually a backend server never be
283 contacted). It is expected that the HTTP response is
284 generated by mruby script (see "mruby=<PATH>" parameter
285 above). "dnf" is an abbreviation of "do not forward".
287 Since ";" and ":" are used as delimiter, <PATTERN> must
288 not contain these characters. In order to include ":"
289 in <PATTERN>, one has to specify "%3A" (which is
290 percent\-encoded from of ":") instead. Since ";" has
291 special meaning in shell, the option value must be
294 Default: \fB127.0.0.1,80\fP
298 .B \-f, \-\-frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]
299 Set frontend host and port. If <HOST> is \(aq*\(aq, it
300 assumes all addresses including both IPv4 and IPv6.
301 UNIX domain socket can be specified by prefixing path
302 name with "unix:" (e.g., unix:/var/run/nghttpx.sock).
303 This option can be used multiple times to listen to
306 This option can take 0 or more parameters, which are
307 described below. Note that "api" and "healthmon"
308 parameters are mutually exclusive.
310 Optionally, TLS can be disabled by specifying "no\-tls"
311 parameter. TLS is enabled by default.
313 If "sni\-fwd" parameter is used, when performing a match
314 to select a backend server, SNI host name received from
315 the client is used instead of the request host. See
316 \fI\%\-\-backend\fP option about the pattern match.
318 To make this frontend as API endpoint, specify "api"
319 parameter. This is disabled by default. It is
320 important to limit the access to the API frontend.
321 Otherwise, someone may change the backend server, and
322 break your services, or expose confidential information
323 to the outside the world.
325 To make this frontend as health monitor endpoint,
326 specify "healthmon" parameter. This is disabled by
327 default. Any requests which come through this address
328 are replied with 200 HTTP status, without no body.
330 To accept PROXY protocol version 1 and 2 on frontend
331 connection, specify "proxyproto" parameter. This is
334 To receive HTTP/3 (QUIC) traffic, specify "quic"
335 parameter. It makes nghttpx listen on UDP port rather
336 than TCP port. UNIX domain socket, "api", and
337 "healthmon" parameters cannot be used with "quic"
340 Default: \fB*,3000\fP
345 Set listen backlog size.
351 .B \-\-backend\-address\-family=(auto|IPv4|IPv6)
352 Specify address family of backend connections. If
353 "auto" is given, both IPv4 and IPv6 are considered. If
354 "IPv4" is given, only IPv4 address is considered. If
355 "IPv6" is given, only IPv6 address is considered.
361 .B \-\-backend\-http\-proxy\-uri=<URI>
362 Specify proxy URI in the form
363 \fI\%http:/\fP/[<USER>:<PASS>@]<PROXY>:<PORT>. If a proxy
364 requires authentication, specify <USER> and <PASS>.
365 Note that they must be properly percent\-encoded. This
366 proxy is used when the backend connection is HTTP/2.
367 First, make a CONNECT request to the proxy and it
368 connects to the backend on behalf of nghttpx. This
369 forms tunnel. After that, nghttpx performs SSL/TLS
370 handshake with the downstream through the tunnel. The
371 timeouts when connecting and making CONNECT request can
372 be specified by \fI\%\-\-backend\-read\-timeout\fP and
373 \fI\%\-\-backend\-write\-timeout\fP options.
378 .B \-n, \-\-workers=<N>
379 Set the number of worker threads.
385 .B \-\-single\-thread
386 Run everything in one thread inside the worker process.
387 This feature is provided for better debugging
388 experience, or for the platforms which lack thread
389 support. If threading is disabled, this option is
394 .B \-\-read\-rate=<SIZE>
395 Set maximum average read rate on frontend connection.
396 Setting 0 to this option means read rate is unlimited.
402 .B \-\-read\-burst=<SIZE>
403 Set maximum read burst size on frontend connection.
404 Setting 0 to this option means read burst size is
411 .B \-\-write\-rate=<SIZE>
412 Set maximum average write rate on frontend connection.
413 Setting 0 to this option means write rate is unlimited.
419 .B \-\-write\-burst=<SIZE>
420 Set maximum write burst size on frontend connection.
421 Setting 0 to this option means write burst size is
428 .B \-\-worker\-read\-rate=<SIZE>
429 Set maximum average read rate on frontend connection per
430 worker. Setting 0 to this option means read rate is
431 unlimited. Not implemented yet.
437 .B \-\-worker\-read\-burst=<SIZE>
438 Set maximum read burst size on frontend connection per
439 worker. Setting 0 to this option means read burst size
440 is unlimited. Not implemented yet.
446 .B \-\-worker\-write\-rate=<SIZE>
447 Set maximum average write rate on frontend connection
448 per worker. Setting 0 to this option means write rate
449 is unlimited. Not implemented yet.
455 .B \-\-worker\-write\-burst=<SIZE>
456 Set maximum write burst size on frontend connection per
457 worker. Setting 0 to this option means write burst size
458 is unlimited. Not implemented yet.
464 .B \-\-worker\-frontend\-connections=<N>
465 Set maximum number of simultaneous connections frontend
466 accepts. Setting 0 means unlimited.
472 .B \-\-backend\-connections\-per\-host=<N>
473 Set maximum number of backend concurrent connections
474 (and/or streams in case of HTTP/2) per origin host.
475 This option is meaningful when \fI\%\-\-http2\-proxy\fP option is
476 used. The origin host is determined by authority
477 portion of request URI (or :authority header field for
478 HTTP/2). To limit the number of connections per
479 frontend for default mode, use
480 \fI\%\-\-backend\-connections\-per\-frontend\fP\&.
486 .B \-\-backend\-connections\-per\-frontend=<N>
487 Set maximum number of backend concurrent connections
488 (and/or streams in case of HTTP/2) per frontend. This
489 option is only used for default mode. 0 means
490 unlimited. To limit the number of connections per host
491 with \fI\%\-\-http2\-proxy\fP option, use
492 \fI\%\-\-backend\-connections\-per\-host\fP\&.
498 .B \-\-rlimit\-nofile=<N>
499 Set maximum number of open files (RLIMIT_NOFILE) to <N>.
500 If 0 is given, nghttpx does not set the limit.
506 .B \-\-rlimit\-memlock=<N>
507 Set maximum number of bytes of memory that may be locked
508 into RAM. If 0 is given, nghttpx does not set the
515 .B \-\-backend\-request\-buffer=<SIZE>
516 Set buffer size used to store backend request.
522 .B \-\-backend\-response\-buffer=<SIZE>
523 Set buffer size used to store backend response.
530 Enables "TCP Fast Open" for the listening socket and
531 limits the maximum length for the queue of connections
532 that have not yet completed the three\-way handshake. If
533 value is 0 then fast open is disabled.
540 Don\(aqt use kqueue. This option is only applicable for
541 the platforms which have kqueue. For other platforms,
542 this option will be simply ignored.
547 .B \-\-frontend\-http2\-read\-timeout=<DURATION>
548 Specify read timeout for HTTP/2 frontend connection.
554 .B \-\-frontend\-http3\-read\-timeout=<DURATION>
555 Specify read timeout for HTTP/3 frontend connection.
561 .B \-\-frontend\-read\-timeout=<DURATION>
562 Specify read timeout for HTTP/1.1 frontend connection.
568 .B \-\-frontend\-write\-timeout=<DURATION>
569 Specify write timeout for all frontend connections.
575 .B \-\-frontend\-keep\-alive\-timeout=<DURATION>
576 Specify keep\-alive timeout for frontend HTTP/1
583 .B \-\-stream\-read\-timeout=<DURATION>
584 Specify read timeout for HTTP/2 streams. 0 means no
591 .B \-\-stream\-write\-timeout=<DURATION>
592 Specify write timeout for HTTP/2 streams. 0 means no
599 .B \-\-backend\-read\-timeout=<DURATION>
600 Specify read timeout for backend connection.
606 .B \-\-backend\-write\-timeout=<DURATION>
607 Specify write timeout for backend connection.
613 .B \-\-backend\-connect\-timeout=<DURATION>
614 Specify timeout before establishing TCP connection to
621 .B \-\-backend\-keep\-alive\-timeout=<DURATION>
622 Specify keep\-alive timeout for backend HTTP/1
629 .B \-\-listener\-disable\-timeout=<DURATION>
630 After accepting connection failed, connection listener
631 is disabled for a given amount of time. Specifying 0
632 disables this feature.
638 .B \-\-frontend\-http2\-setting\-timeout=<DURATION>
639 Specify timeout before SETTINGS ACK is received from
646 .B \-\-backend\-http2\-settings\-timeout=<DURATION>
647 Specify timeout before SETTINGS ACK is received from
654 .B \-\-backend\-max\-backoff=<DURATION>
655 Specify maximum backoff interval. This is used when
656 doing health check against offline backend (see "fail"
657 parameter in \fI\%\-\-backend\fP option). It is also used to
658 limit the maximum interval to temporarily disable
659 backend when nghttpx failed to connect to it. These
660 intervals are calculated using exponential backoff, and
661 consecutive failed attempts increase the interval. This
662 option caps its maximum value.
669 .B \-\-ciphers=<SUITE>
670 Set allowed cipher list for frontend connection. The
671 format of the string is described in OpenSSL ciphers(1).
672 This option sets cipher suites for TLSv1.2 or earlier.
673 Use \fI\%\-\-tls13\-ciphers\fP for TLSv1.3.
675 Default: \fBECDHE\-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\fP
679 .B \-\-tls13\-ciphers=<SUITE>
680 Set allowed cipher list for frontend connection. The
681 format of the string is described in OpenSSL ciphers(1).
682 This option sets cipher suites for TLSv1.3. Use
683 \fI\%\-\-ciphers\fP for TLSv1.2 or earlier.
685 Default: \fBTLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256\fP
689 .B \-\-client\-ciphers=<SUITE>
690 Set allowed cipher list for backend connection. The
691 format of the string is described in OpenSSL ciphers(1).
692 This option sets cipher suites for TLSv1.2 or earlier.
693 Use \fI\%\-\-tls13\-client\-ciphers\fP for TLSv1.3.
695 Default: \fBECDHE\-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\fP
699 .B \-\-tls13\-client\-ciphers=<SUITE>
700 Set allowed cipher list for backend connection. The
701 format of the string is described in OpenSSL ciphers(1).
702 This option sets cipher suites for TLSv1.3. Use
703 \fI\%\-\-tls13\-client\-ciphers\fP for TLSv1.2 or earlier.
705 Default: \fBTLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256\fP
709 .B \-\-ecdh\-curves=<LIST>
710 Set supported curve list for frontend connections.
711 <LIST> is a colon separated list of curve NID or names
712 in the preference order. The supported curves depend on
713 the linked OpenSSL library. This function requires
716 Default: \fBX25519:P\-256:P\-384:P\-521\fP
721 Don\(aqt verify backend server\(aqs certificate if TLS is
722 enabled for backend connections.
727 Set path to trusted CA certificate file. It is used in
728 backend TLS connections to verify peer\(aqs certificate.
729 It is also used to verify OCSP response from the script
730 set by \fI\%\-\-fetch\-ocsp\-response\-file\fP\&. The file must be in
731 PEM format. It can contain multiple certificates. If
732 the linked OpenSSL is configured to load system wide
733 certificates, they are loaded at startup regardless of
738 .B \-\-private\-key\-passwd\-file=<PATH>
739 Path to file that contains password for the server\(aqs
740 private key. If none is given and the private key is
741 password protected it\(aqll be requested interactively.
745 .B \-\-subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
746 Specify additional certificate and private key file.
747 nghttpx will choose certificates based on the hostname
748 indicated by client using TLS SNI extension. If nghttpx
749 is built with OpenSSL >= 1.0.2, the shared elliptic
750 curves (e.g., P\-256) between client and server are also
751 taken into consideration. This allows nghttpx to send
752 ECDSA certificate to modern clients, while sending RSA
753 based certificate to older clients. This option can be
754 used multiple times. To make OCSP stapling work,
755 <CERTPATH> must be absolute path.
757 Additional parameter can be specified in <PARAM>. The
758 available <PARAM> is "sct\-dir=<DIR>".
760 "sct\-dir=<DIR>" specifies the path to directory which
761 contains *.sct files for TLS
762 signed_certificate_timestamp extension (RFC 6962). This
763 feature requires OpenSSL >= 1.0.2. See also
764 \fI\%\-\-tls\-sct\-dir\fP option.
768 .B \-\-dh\-param\-file=<PATH>
769 Path to file that contains DH parameters in PEM format.
770 Without this option, DHE cipher suites are not
775 .B \-\-npn\-list=<LIST>
776 Comma delimited list of ALPN protocol identifier sorted
777 in the order of preference. That means most desirable
778 protocol comes first. This is used in both ALPN and
779 NPN. The parameter must be delimited by a single comma
780 only and any white spaces are treated as a part of
783 Default: \fBh2,h2\-16,h2\-14,http/1.1\fP
787 .B \-\-verify\-client
788 Require and verify client certificate.
792 .B \-\-verify\-client\-cacert=<PATH>
793 Path to file that contains CA certificates to verify
794 client certificate. The file must be in PEM format. It
795 can contain multiple certificates.
799 .B \-\-verify\-client\-tolerate\-expired
800 Accept expired client certificate. Operator should
801 handle the expired client certificate by some means
802 (e.g., mruby script). Otherwise, this option might
803 cause a security risk.
807 .B \-\-client\-private\-key\-file=<PATH>
808 Path to file that contains client private key used in
809 backend client authentication.
813 .B \-\-client\-cert\-file=<PATH>
814 Path to file that contains client certificate used in
815 backend client authentication.
819 .B \-\-tls\-min\-proto\-version=<VER>
820 Specify minimum SSL/TLS protocol. The name matching is
821 done in case\-insensitive manner. The versions between
822 \fI\%\-\-tls\-min\-proto\-version\fP and \fI\%\-\-tls\-max\-proto\-version\fP are
823 enabled. If the protocol list advertised by client does
824 not overlap this range, you will receive the error
825 message "unknown protocol". If a protocol version lower
826 than TLSv1.2 is specified, make sure that the compatible
827 ciphers are included in \fI\%\-\-ciphers\fP option. The default
828 cipher list only includes ciphers compatible with
829 TLSv1.2 or above. The available versions are:
830 TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
832 Default: \fBTLSv1.2\fP
836 .B \-\-tls\-max\-proto\-version=<VER>
837 Specify maximum SSL/TLS protocol. The name matching is
838 done in case\-insensitive manner. The versions between
839 \fI\%\-\-tls\-min\-proto\-version\fP and \fI\%\-\-tls\-max\-proto\-version\fP are
840 enabled. If the protocol list advertised by client does
841 not overlap this range, you will receive the error
842 message "unknown protocol". The available versions are:
843 TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
845 Default: \fBTLSv1.3\fP
849 .B \-\-tls\-ticket\-key\-file=<PATH>
850 Path to file that contains random data to construct TLS
851 session ticket parameters. If aes\-128\-cbc is given in
852 \fI\%\-\-tls\-ticket\-key\-cipher\fP, the file must contain exactly
853 48 bytes. If aes\-256\-cbc is given in
854 \fI\%\-\-tls\-ticket\-key\-cipher\fP, the file must contain exactly
855 80 bytes. This options can be used repeatedly to
856 specify multiple ticket parameters. If several files
857 are given, only the first key is used to encrypt TLS
858 session tickets. Other keys are accepted but server
859 will issue new session ticket with first key. This
860 allows session key rotation. Please note that key
861 rotation does not occur automatically. User should
862 rearrange files or change options values and restart
863 nghttpx gracefully. If opening or reading given file
864 fails, all loaded keys are discarded and it is treated
865 as if none of this option is given. If this option is
866 not given or an error occurred while opening or reading
867 a file, key is generated every 1 hour internally and
868 they are valid for 12 hours. This is recommended if
869 ticket key sharing between nghttpx instances is not
874 .B \-\-tls\-ticket\-key\-memcached=<HOST>,<PORT>[;tls]
875 Specify address of memcached server to get TLS ticket
876 keys for session resumption. This enables shared TLS
877 ticket key between multiple nghttpx instances. nghttpx
878 does not set TLS ticket key to memcached. The external
879 ticket key generator is required. nghttpx just gets TLS
880 ticket keys from memcached, and use them, possibly
881 replacing current set of keys. It is up to extern TLS
882 ticket key generator to rotate keys frequently. See
883 "TLS SESSION TICKET RESUMPTION" section in manual page
884 to know the data format in memcached entry. Optionally,
885 memcached connection can be encrypted with TLS by
886 specifying "tls" parameter.
890 .B \-\-tls\-ticket\-key\-memcached\-address\-family=(auto|IPv4|IPv6)
891 Specify address family of memcached connections to get
892 TLS ticket keys. If "auto" is given, both IPv4 and IPv6
893 are considered. If "IPv4" is given, only IPv4 address
894 is considered. If "IPv6" is given, only IPv6 address is
901 .B \-\-tls\-ticket\-key\-memcached\-interval=<DURATION>
902 Set interval to get TLS ticket keys from memcached.
908 .B \-\-tls\-ticket\-key\-memcached\-max\-retry=<N>
909 Set maximum number of consecutive retries before
910 abandoning TLS ticket key retrieval. If this number is
911 reached, the attempt is considered as failure, and
912 "failure" count is incremented by 1, which contributed
913 to the value controlled
914 \fI\%\-\-tls\-ticket\-key\-memcached\-max\-fail\fP option.
920 .B \-\-tls\-ticket\-key\-memcached\-max\-fail=<N>
921 Set maximum number of consecutive failure before
922 disabling TLS ticket until next scheduled key retrieval.
928 .B \-\-tls\-ticket\-key\-cipher=<CIPHER>
929 Specify cipher to encrypt TLS session ticket. Specify
930 either aes\-128\-cbc or aes\-256\-cbc. By default,
931 aes\-128\-cbc is used.
935 .B \-\-tls\-ticket\-key\-memcached\-cert\-file=<PATH>
936 Path to client certificate for memcached connections to
941 .B \-\-tls\-ticket\-key\-memcached\-private\-key\-file=<PATH>
942 Path to client private key for memcached connections to
947 .B \-\-fetch\-ocsp\-response\-file=<PATH>
948 Path to fetch\-ocsp\-response script file. It should be
951 Default: \fB/usr/local/share/nghttp2/fetch\-ocsp\-response\fP
955 .B \-\-ocsp\-update\-interval=<DURATION>
956 Set interval to update OCSP response cache.
963 Start accepting connections after initial attempts to
964 get OCSP responses finish. It does not matter some of
965 the attempts fail. This feature is useful if OCSP
966 responses must be available before accepting
971 .B \-\-no\-verify\-ocsp
972 nghttpx does not verify OCSP response.
977 Disable OCSP stapling.
981 .B \-\-tls\-session\-cache\-memcached=<HOST>,<PORT>[;tls]
982 Specify address of memcached server to store session
983 cache. This enables shared session cache between
984 multiple nghttpx instances. Optionally, memcached
985 connection can be encrypted with TLS by specifying "tls"
990 .B \-\-tls\-session\-cache\-memcached\-address\-family=(auto|IPv4|IPv6)
991 Specify address family of memcached connections to store
992 session cache. If "auto" is given, both IPv4 and IPv6
993 are considered. If "IPv4" is given, only IPv4 address
994 is considered. If "IPv6" is given, only IPv6 address is
1001 .B \-\-tls\-session\-cache\-memcached\-cert\-file=<PATH>
1002 Path to client certificate for memcached connections to
1003 store session cache.
1007 .B \-\-tls\-session\-cache\-memcached\-private\-key\-file=<PATH>
1008 Path to client private key for memcached connections to
1009 store session cache.
1013 .B \-\-tls\-dyn\-rec\-warmup\-threshold=<SIZE>
1014 Specify the threshold size for TLS dynamic record size
1015 behaviour. During a TLS session, after the threshold
1016 number of bytes have been written, the TLS record size
1017 will be increased to the maximum allowed (16K). The max
1018 record size will continue to be used on the active TLS
1019 session. After \fI\%\-\-tls\-dyn\-rec\-idle\-timeout\fP has elapsed,
1020 the record size is reduced to 1300 bytes. Specify 0 to
1021 always use the maximum record size, regardless of idle
1022 period. This behaviour applies to all TLS based
1023 frontends, and TLS HTTP/2 backends.
1029 .B \-\-tls\-dyn\-rec\-idle\-timeout=<DURATION>
1030 Specify TLS dynamic record size behaviour timeout. See
1031 \fI\%\-\-tls\-dyn\-rec\-warmup\-threshold\fP for more information.
1032 This behaviour applies to all TLS based frontends, and
1033 TLS HTTP/2 backends.
1039 .B \-\-no\-http2\-cipher\-block\-list
1040 Allow block listed cipher suite on frontend HTTP/2
1042 \fI\%https://tools.ietf.org/html/rfc7540#appendix\-A\fP for the
1043 complete HTTP/2 cipher suites block list.
1047 .B \-\-client\-no\-http2\-cipher\-block\-list
1048 Allow block listed cipher suite on backend HTTP/2
1050 \fI\%https://tools.ietf.org/html/rfc7540#appendix\-A\fP for the
1051 complete HTTP/2 cipher suites block list.
1055 .B \-\-tls\-sct\-dir=<DIR>
1056 Specifies the directory where *.sct files exist. All
1057 *.sct files in <DIR> are read, and sent as
1058 extension_data of TLS signed_certificate_timestamp (RFC
1059 6962) to client. These *.sct files are for the
1060 certificate specified in positional command\-line
1061 argument <CERT>, or certificate option in configuration
1062 file. For additional certificates, use \fI\%\-\-subcert\fP
1063 option. This option requires OpenSSL >= 1.0.2.
1067 .B \-\-psk\-secrets=<PATH>
1068 Read list of PSK identity and secrets from <PATH>. This
1069 is used for frontend connection. The each line of input
1070 file is formatted as <identity>:<hex\-secret>, where
1071 <identity> is PSK identity, and <hex\-secret> is secret
1072 in hex. An empty line, and line which starts with \(aq#\(aq
1073 are skipped. The default enabled cipher list might not
1074 contain any PSK cipher suite. In that case, desired PSK
1075 cipher suites must be enabled using \fI\%\-\-ciphers\fP option.
1076 The desired PSK cipher suite may be block listed by
1077 HTTP/2. To use those cipher suites with HTTP/2,
1078 consider to use \fI\%\-\-no\-http2\-cipher\-block\-list\fP option.
1079 But be aware its implications.
1083 .B \-\-client\-psk\-secrets=<PATH>
1084 Read PSK identity and secrets from <PATH>. This is used
1085 for backend connection. The each line of input file is
1086 formatted as <identity>:<hex\-secret>, where <identity>
1087 is PSK identity, and <hex\-secret> is secret in hex. An
1088 empty line, and line which starts with \(aq#\(aq are skipped.
1089 The first identity and secret pair encountered is used.
1090 The default enabled cipher list might not contain any
1091 PSK cipher suite. In that case, desired PSK cipher
1092 suites must be enabled using \fI\%\-\-client\-ciphers\fP option.
1093 The desired PSK cipher suite may be block listed by
1094 HTTP/2. To use those cipher suites with HTTP/2,
1095 consider to use \fI\%\-\-client\-no\-http2\-cipher\-block\-list\fP
1096 option. But be aware its implications.
1100 .B \-\-tls\-no\-postpone\-early\-data
1101 By default, except for QUIC connections, nghttpx
1102 postpones forwarding HTTP requests sent in early data,
1103 including those sent in partially in it, until TLS
1104 handshake finishes. If all backend server recognizes
1105 "Early\-Data" header field, using this option makes
1106 nghttpx not postpone forwarding request and get full
1107 potential of 0\-RTT data.
1111 .B \-\-tls\-max\-early\-data=<SIZE>
1112 Sets the maximum amount of 0\-RTT data that server
1120 .B \-c, \-\-frontend\-http2\-max\-concurrent\-streams=<N>
1121 Set the maximum number of the concurrent streams in one
1122 frontend HTTP/2 session.
1128 .B \-\-backend\-http2\-max\-concurrent\-streams=<N>
1129 Set the maximum number of the concurrent streams in one
1130 backend HTTP/2 session. This sets maximum number of
1131 concurrent opened pushed streams. The maximum number of
1132 concurrent requests are set by a remote server.
1138 .B \-\-frontend\-http2\-window\-size=<SIZE>
1139 Sets the per\-stream initial window size of HTTP/2
1140 frontend connection.
1142 Default: \fB65535\fP
1146 .B \-\-frontend\-http2\-connection\-window\-size=<SIZE>
1147 Sets the per\-connection window size of HTTP/2 frontend
1150 Default: \fB65535\fP
1154 .B \-\-backend\-http2\-window\-size=<SIZE>
1155 Sets the initial window size of HTTP/2 backend
1158 Default: \fB65535\fP
1162 .B \-\-backend\-http2\-connection\-window\-size=<SIZE>
1163 Sets the per\-connection window size of HTTP/2 backend
1166 Default: \fB2147483647\fP
1170 .B \-\-http2\-no\-cookie\-crumbling
1171 Don\(aqt crumble cookie header field.
1176 Add at most <N> bytes to a HTTP/2 frame payload as
1177 padding. Specify 0 to disable padding. This option is
1178 meant for debugging purpose and not intended to enhance
1183 .B \-\-no\-server\-push
1184 Disable HTTP/2 server push. Server push is supported by
1185 default mode and HTTP/2 frontend via Link header field.
1186 It is also supported if both frontend and backend are
1187 HTTP/2 in default mode. In this case, server push from
1188 backend session is relayed to frontend, and server push
1189 via Link header field is also supported.
1193 .B \-\-frontend\-http2\-optimize\-write\-buffer\-size
1194 (Experimental) Enable write buffer size optimization in
1195 frontend HTTP/2 TLS connection. This optimization aims
1196 to reduce write buffer size so that it only contains
1197 bytes which can send immediately. This makes server
1198 more responsive to prioritized HTTP/2 stream because the
1199 buffering of lower priority stream is reduced. This
1200 option is only effective on recent Linux platform.
1204 .B \-\-frontend\-http2\-optimize\-window\-size
1205 (Experimental) Automatically tune connection level
1206 window size of frontend HTTP/2 TLS connection. If this
1207 feature is enabled, connection window size starts with
1208 the default window size, 65535 bytes. nghttpx
1209 automatically adjusts connection window size based on
1210 TCP receiving window size. The maximum window size is
1211 capped by the value specified by
1212 \fI\%\-\-frontend\-http2\-connection\-window\-size\fP\&. Since the
1213 stream is subject to stream level window size, it should
1214 be adjusted using \fI\%\-\-frontend\-http2\-window\-size\fP option as
1215 well. This option is only effective on recent Linux
1220 .B \-\-frontend\-http2\-encoder\-dynamic\-table\-size=<SIZE>
1221 Specify the maximum dynamic table size of HPACK encoder
1222 in the frontend HTTP/2 connection. The decoder (client)
1223 specifies the maximum dynamic table size it accepts.
1224 Then the negotiated dynamic table size is the minimum of
1225 this option value and the value which client specified.
1231 .B \-\-frontend\-http2\-decoder\-dynamic\-table\-size=<SIZE>
1232 Specify the maximum dynamic table size of HPACK decoder
1233 in the frontend HTTP/2 connection.
1239 .B \-\-backend\-http2\-encoder\-dynamic\-table\-size=<SIZE>
1240 Specify the maximum dynamic table size of HPACK encoder
1241 in the backend HTTP/2 connection. The decoder (backend)
1242 specifies the maximum dynamic table size it accepts.
1243 Then the negotiated dynamic table size is the minimum of
1244 this option value and the value which backend specified.
1250 .B \-\-backend\-http2\-decoder\-dynamic\-table\-size=<SIZE>
1251 Specify the maximum dynamic table size of HPACK decoder
1252 in the backend HTTP/2 connection.
1260 Accept HTTP/2, and HTTP/1.1 over SSL/TLS. "no\-tls"
1261 parameter is used in \fI\%\-\-frontend\fP option, accept HTTP/2
1262 and HTTP/1.1 over cleartext TCP. The incoming HTTP/1.1
1263 connection can be upgraded to HTTP/2 through HTTP
1268 .B \-s, \-\-http2\-proxy
1269 Like default mode, but enable forward proxy. This is so
1270 called HTTP/2 proxy mode.
1275 .B \-L, \-\-log\-level=<LEVEL>
1276 Set the severity level of log output. <LEVEL> must be
1277 one of INFO, NOTICE, WARN, ERROR and FATAL.
1279 Default: \fBNOTICE\fP
1283 .B \-\-accesslog\-file=<PATH>
1284 Set path to write access log. To reopen file, send USR1
1289 .B \-\-accesslog\-syslog
1290 Send access log to syslog. If this option is used,
1291 \fI\%\-\-accesslog\-file\fP option is ignored.
1295 .B \-\-accesslog\-format=<FORMAT>
1296 Specify format string for access log. The default
1297 format is combined format. The following variables are
1301 $remote_addr: client IP address.
1303 $time_local: local time in Common Log format.
1305 $time_iso8601: local time in ISO 8601 format.
1307 $request: HTTP request line.
1309 $status: HTTP response status code.
1311 $body_bytes_sent: the number of bytes sent to client
1314 $http_<VAR>: value of HTTP request header <VAR> where
1315 \(aq_\(aq in <VAR> is replaced with \(aq\-\(aq.
1317 $remote_port: client port.
1319 $server_port: server port.
1321 $request_time: request processing time in seconds with
1322 milliseconds resolution.
1324 $pid: PID of the running process.
1326 $alpn: ALPN identifier of the protocol which generates
1327 the response. For HTTP/1, ALPN is always http/1.1,
1328 regardless of minor version.
1330 $tls_cipher: cipher used for SSL/TLS connection.
1332 $tls_client_fingerprint_sha256: SHA\-256 fingerprint of
1335 $tls_client_fingerprint_sha1: SHA\-1 fingerprint of
1338 $tls_client_subject_name: subject name in client
1341 $tls_client_issuer_name: issuer name in client
1344 $tls_client_serial: serial number in client
1347 $tls_protocol: protocol for SSL/TLS connection.
1349 $tls_session_id: session ID for SSL/TLS connection.
1351 $tls_session_reused: "r" if SSL/TLS session was
1352 reused. Otherwise, "."
1354 $tls_sni: SNI server name for SSL/TLS connection.
1356 $backend_host: backend host used to fulfill the
1357 request. "\-" if backend host is not available.
1359 $backend_port: backend port used to fulfill the
1360 request. "\-" if backend host is not available.
1362 $method: HTTP method
1364 $path: Request path including query. For CONNECT
1365 request, authority is recorded.
1367 $path_without_query: $path up to the first \(aq?\(aq
1368 character. For CONNECT request, authority is
1371 $protocol_version: HTTP version (e.g., HTTP/1.1,
1375 The variable can be enclosed by "{" and "}" for
1376 disambiguation (e.g., ${remote_addr}).
1378 Default: \fB$remote_addr \- \- [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"\fP
1382 .B \-\-accesslog\-write\-early
1383 Write access log when response header fields are
1384 received from backend rather than when request
1385 transaction finishes.
1389 .B \-\-errorlog\-file=<PATH>
1390 Set path to write error log. To reopen file, send USR1
1391 signal to nghttpx. stderr will be redirected to the
1392 error log file unless \fI\%\-\-errorlog\-syslog\fP is used.
1394 Default: \fB/dev/stderr\fP
1398 .B \-\-errorlog\-syslog
1399 Send error log to syslog. If this option is used,
1400 \fI\%\-\-errorlog\-file\fP option is ignored.
1404 .B \-\-syslog\-facility=<FACILITY>
1405 Set syslog facility to <FACILITY>.
1407 Default: \fBdaemon\fP
1412 .B \-\-add\-x\-forwarded\-for
1413 Append X\-Forwarded\-For header field to the downstream
1418 .B \-\-strip\-incoming\-x\-forwarded\-for
1419 Strip X\-Forwarded\-For header field from inbound client
1424 .B \-\-no\-add\-x\-forwarded\-proto
1425 Don\(aqt append additional X\-Forwarded\-Proto header field
1426 to the backend request. If inbound client sets
1427 X\-Forwarded\-Proto, and
1428 \fI\%\-\-no\-strip\-incoming\-x\-forwarded\-proto\fP option is used,
1429 they are passed to the backend.
1433 .B \-\-no\-strip\-incoming\-x\-forwarded\-proto
1434 Don\(aqt strip X\-Forwarded\-Proto header field from inbound
1439 .B \-\-add\-forwarded=<LIST>
1440 Append RFC 7239 Forwarded header field with parameters
1441 specified in comma delimited list <LIST>. The supported
1442 parameters are "by", "for", "host", and "proto". By
1443 default, the value of "by" and "for" parameters are
1444 obfuscated string. See \fI\%\-\-forwarded\-by\fP and
1445 \fI\%\-\-forwarded\-for\fP options respectively. Note that nghttpx
1446 does not translate non\-standard X\-Forwarded\-* header
1447 fields into Forwarded header field, and vice versa.
1451 .B \-\-strip\-incoming\-forwarded
1452 Strip Forwarded header field from inbound client
1457 .B \-\-forwarded\-by=(obfuscated|ip|<VALUE>)
1458 Specify the parameter value sent out with "by" parameter
1459 of Forwarded header field. If "obfuscated" is given,
1460 the string is randomly generated at startup. If "ip" is
1461 given, the interface address of the connection,
1462 including port number, is sent with "by" parameter. In
1463 case of UNIX domain socket, "localhost" is used instead
1464 of address and port. User can also specify the static
1465 obfuscated string. The limitation is that it must start
1466 with "_", and only consists of character set
1467 [A\-Za\-z0\-9._\-], as described in RFC 7239.
1469 Default: \fBobfuscated\fP
1473 .B \-\-forwarded\-for=(obfuscated|ip)
1474 Specify the parameter value sent out with "for"
1475 parameter of Forwarded header field. If "obfuscated" is
1476 given, the string is randomly generated for each client
1477 connection. If "ip" is given, the remote client address
1478 of the connection, without port number, is sent with
1479 "for" parameter. In case of UNIX domain socket,
1480 "localhost" is used instead of address.
1482 Default: \fBobfuscated\fP
1487 Don\(aqt append to Via header field. If Via header field
1488 is received, it is left unaltered.
1492 .B \-\-no\-strip\-incoming\-early\-data
1493 Don\(aqt strip Early\-Data header field from inbound client
1498 .B \-\-no\-location\-rewrite
1499 Don\(aqt rewrite location header field in default mode.
1500 When \fI\%\-\-http2\-proxy\fP is used, location header field will
1501 not be altered regardless of this option.
1505 .B \-\-host\-rewrite
1506 Rewrite host and :authority header fields in default
1507 mode. When \fI\%\-\-http2\-proxy\fP is used, these headers will
1508 not be altered regardless of this option.
1512 .B \-\-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1513 Specify protocol ID, port, host and origin of
1514 alternative service. <HOST>, <ORIGIN> and <PARAMS> are
1515 optional. Empty <HOST> and <ORIGIN> are allowed and
1516 they are treated as nothing is specified. They are
1517 advertised in alt\-svc header field only in HTTP/1.1
1518 frontend. This option can be used multiple times to
1519 specify multiple alternative services.
1520 Example: \fI\%\-\-altsvc\fP="h2,443,,,ma=3600; persist=1\(aq
1524 .B \-\-http2\-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
1525 Just like \fI\%\-\-altsvc\fP option, but this altsvc is only sent
1530 .B \-\-add\-request\-header=<HEADER>
1531 Specify additional header field to add to request header
1532 set. This option just appends header field and won\(aqt
1533 replace anything already set. This option can be used
1534 several times to specify multiple header fields.
1535 Example: \fI\%\-\-add\-request\-header\fP="foo: bar"
1539 .B \-\-add\-response\-header=<HEADER>
1540 Specify additional header field to add to response
1541 header set. This option just appends header field and
1542 won\(aqt replace anything already set. This option can be
1543 used several times to specify multiple header fields.
1544 Example: \fI\%\-\-add\-response\-header\fP="foo: bar"
1548 .B \-\-request\-header\-field\-buffer=<SIZE>
1549 Set maximum buffer size for incoming HTTP request header
1550 field list. This is the sum of header name and value in
1551 bytes. If trailer fields exist, they are counted
1552 towards this number.
1558 .B \-\-max\-request\-header\-fields=<N>
1559 Set maximum number of incoming HTTP request header
1560 fields. If trailer fields exist, they are counted
1561 towards this number.
1567 .B \-\-response\-header\-field\-buffer=<SIZE>
1568 Set maximum buffer size for incoming HTTP response
1569 header field list. This is the sum of header name and
1570 value in bytes. If trailer fields exist, they are
1571 counted towards this number.
1577 .B \-\-max\-response\-header\-fields=<N>
1578 Set maximum number of incoming HTTP response header
1579 fields. If trailer fields exist, they are counted
1580 towards this number.
1586 .B \-\-error\-page=(<CODE>|*)=<PATH>
1587 Set file path to custom error page served when nghttpx
1588 originally generates HTTP error status code <CODE>.
1589 <CODE> must be greater than or equal to 400, and at most
1590 599. If "*" is used instead of <CODE>, it matches all
1591 HTTP status code. If error status code comes from
1592 backend server, the custom error pages are not used.
1596 .B \-\-server\-name=<NAME>
1597 Change server response header field value to <NAME>.
1599 Default: \fBnghttpx\fP
1603 .B \-\-no\-server\-rewrite
1604 Don\(aqt rewrite server header field in default mode. When
1605 \fI\%\-\-http2\-proxy\fP is used, these headers will not be altered
1606 regardless of this option.
1610 .B \-\-redirect\-https\-port=<PORT>
1611 Specify the port number which appears in Location header
1612 field when redirect to HTTPS URI is made due to
1613 "redirect\-if\-not\-tls" parameter in \fI\%\-\-backend\fP option.
1620 .B \-\-api\-max\-request\-body=<SIZE>
1621 Set the maximum size of request body for API request.
1628 .B \-\-dns\-cache\-timeout=<DURATION>
1629 Set duration that cached DNS results remain valid. Note
1630 that nghttpx caches the unsuccessful results as well.
1636 .B \-\-dns\-lookup\-timeout=<DURATION>
1637 Set timeout that DNS server is given to respond to the
1638 initial DNS query. For the 2nd and later queries,
1639 server is given time based on this timeout, and it is
1646 .B \-\-dns\-max\-try=<N>
1647 Set the number of DNS query before nghttpx gives up name
1654 .B \-\-frontend\-max\-requests=<N>
1655 The number of requests that single frontend connection
1656 can process. For HTTP/2, this is the number of streams
1657 in one HTTP/2 connection. For HTTP/1, this is the
1658 number of keep alive requests. This is hint to nghttpx,
1659 and it may allow additional few requests. The default
1665 .B \-\-frontend\-http2\-dump\-request\-header=<PATH>
1666 Dumps request headers received by HTTP/2 frontend to the
1667 file denoted in <PATH>. The output is done in HTTP/1
1668 header field format and each header block is followed by
1669 an empty line. This option is not thread safe and MUST
1670 NOT be used with option \fI\%\-n\fP<N>, where <N> >= 2.
1674 .B \-\-frontend\-http2\-dump\-response\-header=<PATH>
1675 Dumps response headers sent from HTTP/2 frontend to the
1676 file denoted in <PATH>. The output is done in HTTP/1
1677 header field format and each header block is followed by
1678 an empty line. This option is not thread safe and MUST
1679 NOT be used with option \fI\%\-n\fP<N>, where <N> >= 2.
1683 .B \-o, \-\-frontend\-frame\-debug
1684 Print HTTP/2 frames in frontend to stderr. This option
1685 is not thread safe and MUST NOT be used with option
1686 \fI\%\-n\fP=N, where N >= 2.
1692 Run in a background. If \fI\%\-D\fP is used, the current working
1693 directory is changed to \(aq\fI/\fP\(aq.
1697 .B \-\-pid\-file=<PATH>
1698 Set path to save PID of this program.
1703 Run this program as <USER>. This option is intended to
1704 be used to drop root privileges.
1708 .B \-\-single\-process
1709 Run this program in a single process mode for debugging
1710 purpose. Without this option, nghttpx creates at least
1711 2 processes: main and worker processes. If this option
1712 is used, main and worker are unified into a single
1713 process. nghttpx still spawns additional process if
1714 neverbleed is used. In the single process mode, the
1715 signal handling feature is disabled.
1719 .B \-\-max\-worker\-processes=<N>
1720 The maximum number of worker processes. nghttpx spawns
1721 new worker process when it reloads its configuration.
1722 The previous worker process enters graceful termination
1723 period and will terminate when it finishes handling the
1724 existing connections. However, if reloading
1725 configurations happen very frequently, the worker
1726 processes might be piled up if they take a bit long time
1727 to finish the existing connections. With this option,
1728 if the number of worker processes exceeds the given
1729 value, the oldest worker process is terminated
1730 immediately. Specifying 0 means no limit and it is the
1735 .B \-\-worker\-process\-grace\-shutdown\-period=<DURATION>
1736 Maximum period for a worker process to terminate
1737 gracefully. When a worker process enters in graceful
1738 shutdown period (e.g., when nghttpx reloads its
1739 configuration) and it does not finish handling the
1740 existing connections in the given period of time, it is
1741 immediately terminated. Specifying 0 means no limit and
1742 it is the default behaviour.
1747 .B \-\-mruby\-file=<PATH>
1748 Set mruby script file
1752 .B \-\-ignore\-per\-pattern\-mruby\-error
1753 Ignore mruby compile error for per\-pattern mruby script
1754 file. If error occurred, it is treated as if no mruby
1755 file were specified for the pattern.
1760 .B \-\-frontend\-quic\-idle\-timeout=<DURATION>
1761 Specify an idle timeout for QUIC connection.
1767 .B \-\-frontend\-quic\-debug\-log
1768 Output QUIC debug log to \fI/dev/stderr.\fP
1772 .B \-\-quic\-bpf\-program\-file=<PATH>
1773 Specify a path to eBPF program file reuseport_kern.o to
1774 direct an incoming QUIC UDP datagram to a correct
1777 Default: \fB/usr/local/lib/nghttp2/reuseport_kern.o\fP
1781 .B \-\-frontend\-quic\-early\-data
1782 Enable early data on frontend QUIC connections. nghttpx
1783 sends "Early\-Data" header field to a backend server if a
1784 request is received in early data and handshake has not
1785 finished. All backend servers should deal with possibly
1790 .B \-\-frontend\-quic\-qlog\-dir=<DIR>
1791 Specify a directory where a qlog file is written for
1792 frontend QUIC connections. A qlog file is created per
1793 each QUIC connection. The file name is ISO8601 basic
1794 format, followed by "\-", server Source Connection ID and
1799 .B \-\-frontend\-quic\-require\-token
1800 Require an address validation token for a frontend QUIC
1801 connection. Server sends a token in Retry packet or
1802 NEW_TOKEN frame in the previous connection.
1806 .B \-\-frontend\-quic\-congestion\-controller=<CC>
1807 Specify a congestion controller algorithm for a frontend
1808 QUIC connection. <CC> should be either "cubic" or
1811 Default: \fBcubic\fP
1815 .B \-\-frontend\-quic\-secret\-file=<PATH>
1816 Path to file that contains secure random data to be used
1817 as QUIC keying materials. It is used to derive keys for
1818 encrypting tokens and Connection IDs. It is not used to
1819 encrypt QUIC packets. Each line of this file must
1820 contain exactly 136 bytes hex\-encoded string (when
1821 decoded the byte string is 68 bytes long). The first 2
1822 bits of decoded byte string are used to identify the
1823 keying material. An empty line or a line which starts
1824 \(aq#\(aq is ignored. The file can contain more than one
1825 keying materials. Because the identifier is 2 bits, at
1826 most 4 keying materials are read and the remaining data
1827 is discarded. The first keying material in the file is
1828 primarily used for encryption and decryption for new
1829 connection. The other ones are used to decrypt data for
1830 the existing connections. Specifying multiple keying
1831 materials enables key rotation. Please note that key
1832 rotation does not occur automatically. User should
1833 update files or change options values and restart
1834 nghttpx gracefully. If opening or reading given file
1835 fails, all loaded keying materials are discarded and it
1836 is treated as if none of this option is given. If this
1837 option is not given or an error occurred while opening
1838 or reading a file, a keying material is generated
1839 internally on startup and reload.
1843 .B \-\-quic\-server\-id=<HEXSTRING>
1844 Specify server ID encoded in Connection ID to identify
1845 this particular server instance. Connection ID is
1846 encrypted and this part is not visible in public. It
1847 must be 4 bytes long and must be encoded in hex string
1848 (which is 8 bytes long). If this option is omitted, a
1849 random server ID is generated on startup and
1850 configuration reload.
1854 .B \-\-frontend\-quic\-initial\-rtt=<DURATION>
1855 Specify the initial RTT of the frontend QUIC connection.
1857 Default: \fB333ms\fP
1861 .B \-\-no\-quic\-bpf
1866 .B \-\-frontend\-http3\-window\-size=<SIZE>
1867 Sets the per\-stream initial window size of HTTP/3
1868 frontend connection.
1874 .B \-\-frontend\-http3\-connection\-window\-size=<SIZE>
1875 Sets the per\-connection window size of HTTP/3 frontend
1882 .B \-\-frontend\-http3\-max\-window\-size=<SIZE>
1883 Sets the maximum per\-stream window size of HTTP/3
1884 frontend connection. The window size is adjusted based
1885 on the receiving rate of stream data. The initial value
1886 is the value specified by \fI\%\-\-frontend\-http3\-window\-size\fP
1887 and the window size grows up to <SIZE> bytes.
1893 .B \-\-frontend\-http3\-max\-connection\-window\-size=<SIZE>
1894 Sets the maximum per\-connection window size of HTTP/3
1895 frontend connection. The window size is adjusted based
1896 on the receiving rate of stream data. The initial value
1897 is the value specified by
1898 \fI\%\-\-frontend\-http3\-connection\-window\-size\fP and the window
1899 size grows up to <SIZE> bytes.
1905 .B \-\-frontend\-http3\-max\-concurrent\-streams=<N>
1906 Set the maximum number of the concurrent streams in one
1907 frontend HTTP/3 connection.
1915 Load configuration from <PATH>. Please note that
1916 nghttpx always tries to read the default configuration
1917 file if \fI\%\-\-conf\fP is not given.
1919 Default: \fB/etc/nghttpx/nghttpx.conf\fP
1923 .B \-\-include=<PATH>
1924 Load additional configurations from <PATH>. File <PATH>
1925 is read when configuration parser encountered this
1926 option. This option can be used multiple times, or even
1932 Print version and exit.
1937 Print this help and exit.
1940 The <SIZE> argument is an integer and an optional unit (e.g., 10K is
1941 10 * 1024). Units are K, M and G (powers of 1024).
1943 The <DURATION> argument is an integer and an optional unit (e.g., 1s
1944 is 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
1945 (hours, minutes, seconds and milliseconds, respectively). If a unit
1946 is omitted, a second is used as unit.
1950 .B \fI/etc/nghttpx/nghttpx.conf\fP
1951 The default configuration file path nghttpx searches at startup.
1952 The configuration file path can be changed using \fI\%\-\-conf\fP
1955 Those lines which are staring \fB#\fP are treated as comment.
1957 The option name in the configuration file is the long command\-line
1958 option name with leading \fB\-\-\fP stripped (e.g., \fBfrontend\fP). Put
1959 \fB=\fP between option name and value. Don\(aqt put extra leading or
1962 When specifying arguments including characters which have special
1963 meaning to a shell, we usually use quotes so that shell does not
1964 interpret them. When writing this configuration file, quotes for
1965 this purpose must not be used. For example, specify additional
1966 request header field, do this:
1972 add\-request\-header=foo: bar
1984 add\-request\-header="foo: bar"
1990 The options which do not take argument in the command\-line \fItake\fP
1991 argument in the configuration file. Specify \fByes\fP as an argument
1992 (e.g., \fBhttp2\-proxy=yes\fP). If other string is given, it is
1995 To specify private key and certificate file which are given as
1996 positional arguments in command\-line, use \fBprivate\-key\-file\fP and
1997 \fBcertificate\-file\fP\&.
1999 \fI\%\-\-conf\fP option cannot be used in the configuration file and
2000 will be ignored if specified.
2003 Error log is written to stderr by default. It can be configured
2004 using \fI\%\-\-errorlog\-file\fP\&. The format of log message is as
2007 <datetime> <main\-pid> <current\-pid> <thread\-id> <level> (<filename>:<line>) <msg>
2011 It is a combination of date and time when the log is written. It
2012 is in ISO 8601 format.
2015 It is a main process ID.
2018 It is a process ID which writes this log.
2021 It is a thread ID which writes this log. It would be unique
2022 within <current\-pid>.
2024 .B <filename> and <line>
2025 They are source file name, and line number which produce this log.
2028 It is a log message body.
2035 Shutdown gracefully. First accept pending connections and stop
2036 accepting connection. After all connections are handled, nghttpx
2040 Reload configuration file given in \fI\%\-\-conf\fP\&.
2049 Fork and execute nghttpx. It will execute the binary in the same
2050 path with same command\-line arguments and environment variables. As
2051 of nghttpx version 1.20.0, the new main process sends SIGQUIT to the
2052 original main process when it is ready to serve requests. For the
2053 earlier versions of nghttpx, user has to send SIGQUIT to the
2054 original main process.
2056 The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
2057 is usually used to execute new binary, and the main process is newly
2058 spawned. On the other hand, the latter just reloads configuration
2059 file, and the same main process continues to exist.
2066 nghttpx consists of multiple processes: one process for processing
2067 these signals, and another one for processing requests. The former
2068 spawns the latter. The former is called main process, and the
2069 latter is called worker process. If neverbleed is enabled, the
2070 worker process spawns neverbleed daemon process which does RSA key
2071 processing. The above signal must be sent to the main process. If
2072 the other processes received one of them, it is ignored. This
2073 behaviour of these processes may change in the future release. In
2074 other words, in the future release, the processes other than main
2075 process may terminate upon the reception of these signals.
2076 Therefore these signals should not be sent to the processes other
2082 nghttpx supports HTTP/2 server push in default mode with Link header
2083 field. nghttpx looks for Link header field (\fI\%RFC 5988\fP) in response headers from
2084 backend server and extracts URI\-reference with parameter
2085 \fBrel=preload\fP (see \fI\%preload\fP)
2086 and pushes those URIs to the frontend client. Here is a sample Link
2087 header field to initiate server push:
2093 Link: </fonts/font.woff>; rel=preload
2094 Link: </css/theme.css>; rel=preload
2100 Currently, the following restriction is applied for server push:
2103 The associated stream must have method "GET" or "POST". The
2104 associated stream\(aqs status code must be 200.
2107 This limitation may be loosened in the future release.
2109 nghttpx also supports server push if both frontend and backend are
2110 HTTP/2 in default mode. In this case, in addition to server push via
2111 Link header field, server push from backend is forwarded to frontend
2114 HTTP/2 server push will be disabled if \fI\%\-\-http2\-proxy\fP is
2116 .SH UNIX DOMAIN SOCKET
2118 nghttpx supports UNIX domain socket with a filename for both frontend
2119 and backend connections.
2121 Please note that current nghttpx implementation does not delete a
2122 socket with a filename. And on start up, if nghttpx detects that the
2123 specified socket already exists in the file system, nghttpx first
2124 deletes it. However, if SIGUSR2 is used to execute new binary and
2125 both old and new configurations use same filename, new binary does not
2126 delete the socket and continues to use it.
2129 OCSP query is done using external Python script
2130 \fBfetch\-ocsp\-response\fP, which has been originally developed in Perl
2131 as part of h2o project (\fI\%https://github.com/h2o/h2o\fP), and was
2132 translated into Python.
2134 The script file is usually installed under
2135 \fB$(prefix)/share/nghttp2/\fP directory. The actual path to script can
2136 be customized using \fI\%\-\-fetch\-ocsp\-response\-file\fP option.
2138 If OCSP query is failed, previous OCSP response, if any, is continued
2141 \fI\%\-\-fetch\-ocsp\-response\-file\fP option provides wide range of
2142 possibility to manage OCSP response. It can take an arbitrary script
2143 or executable. The requirement is that it supports the command\-line
2144 interface of \fBfetch\-ocsp\-response\fP script, and it must return a
2145 valid DER encoded OCSP response on success. It must return exit code
2146 0 on success, and 75 for temporary error, and the other error code for
2147 generic failure. For large cluster of servers, it is not efficient
2148 for each server to perform OCSP query using \fBfetch\-ocsp\-response\fP\&.
2149 Instead, you can retrieve OCSP response in some way, and store it in a
2150 disk or a shared database. Then specify a program in
2151 \fI\%\-\-fetch\-ocsp\-response\-file\fP to fetch it from those stores.
2152 This could provide a way to share the OCSP response between fleet of
2153 servers, and also any OCSP query strategy can be applied which may be
2154 beyond the ability of nghttpx itself or \fBfetch\-ocsp\-response\fP
2156 .SH TLS SESSION RESUMPTION
2158 nghttpx supports TLS session resumption through both session ID and
2160 .SS SESSION ID RESUMPTION
2162 By default, session ID is shared by all worker threads.
2164 If \fI\%\-\-tls\-session\-cache\-memcached\fP is given, nghttpx will
2165 insert serialized session data to memcached with
2166 \fBnghttpx:tls\-session\-cache:\fP + lowercase hex string of session ID
2167 as a memcached entry key, with expiry time 12 hours. Session timeout
2170 By default, connections to memcached server are not encrypted. To
2171 enable encryption, use \fBtls\fP keyword in
2172 \fI\%\-\-tls\-session\-cache\-memcached\fP option.
2173 .SS TLS SESSION TICKET RESUMPTION
2175 By default, session ticket is shared by all worker threads. The
2176 automatic key rotation is also enabled by default. Every an hour, new
2177 encryption key is generated, and previous encryption key becomes
2178 decryption only key. We set session timeout to 12 hours, and thus we
2179 keep at most 12 keys.
2181 If \fI\%\-\-tls\-ticket\-key\-memcached\fP is given, encryption keys are
2182 retrieved from memcached. nghttpx just reads keys from memcached; one
2183 has to deploy key generator program to update keys frequently (e.g.,
2184 every 1 hour). The example key generator tlsticketupdate.go is
2185 available under contrib directory in nghttp2 archive. The memcached
2186 entry key is \fBnghttpx:tls\-ticket\-key\fP\&. The data format stored in
2187 memcached is the binary format described below:
2193 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
2194 | VERSION (4) |LEN (2)|KEY(48 or 80) ...
2195 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
2198 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
2199 (LEN, KEY) pair can be repeated
2205 All numbers in the above figure is bytes. All integer fields are
2208 First 4 bytes integer VERSION field, which must be 1. The 2 bytes
2209 integer LEN field gives the length of following KEY field, which
2210 contains key. If \fI\%\-\-tls\-ticket\-key\-cipher\fP=aes\-128\-cbc is
2211 used, LEN must be 48. If
2212 \fI\%\-\-tls\-ticket\-key\-cipher\fP=aes\-256\-cbc is used, LEN must be
2213 80. LEN and KEY pair can be repeated multiple times to store multiple
2214 keys. The key appeared first is used as encryption key. All the
2215 remaining keys are used as decryption only.
2217 By default, connections to memcached server are not encrypted. To
2218 enable encryption, use \fBtls\fP keyword in
2219 \fI\%\-\-tls\-ticket\-key\-memcached\fP option.
2221 If \fI\%\-\-tls\-ticket\-key\-file\fP is given, encryption key is read
2222 from the given file. In this case, nghttpx does not rotate key
2223 automatically. To rotate key, one has to restart nghttpx (see
2225 .SH CERTIFICATE TRANSPARENCY
2227 nghttpx supports TLS \fBsigned_certificate_timestamp\fP extension (\fI\%RFC
2228 6962\fP). The relevant options
2229 are \fI\%\-\-tls\-sct\-dir\fP and \fBsct\-dir\fP parameter in
2230 \fI\%\-\-subcert\fP\&. They takes a directory, and nghttpx reads all
2231 files whose extension is \fB\&.sct\fP under the directory. The \fB*.sct\fP
2232 files are encoded as \fBSignedCertificateTimestamp\fP struct described
2233 in \fI\%section 3.2 of RFC 69662\fP\&. This format is
2234 the same one used by \fI\%nginx\-ct\fP and \fI\%mod_ssl_ct\fP\&.
2235 \fI\%ct\-submit\fP can be
2236 used to submit certificates to log servers, and obtain the
2237 \fBSignedCertificateTimestamp\fP struct which can be used with nghttpx.
2243 The current mruby extension API is experimental and not frozen. The
2244 API is subject to change in the future release.
2251 Almost all string value returned from method, or attribute is a
2252 fresh new mruby string, which involves memory allocation, and
2253 copies. Therefore, it is strongly recommended to store a return
2254 value in a local variable, and use it, instead of calling method or
2255 accessing attribute repeatedly.
2259 nghttpx allows users to extend its capability using mruby scripts.
2260 nghttpx has 2 hook points to execute mruby script: request phase and
2261 response phase. The request phase hook is invoked after all request
2262 header fields are received from client. The response phase hook is
2263 invoked after all response header fields are received from backend
2264 server. These hooks allows users to modify header fields, or common
2265 HTTP variables, like authority or request path, and even return custom
2266 response without forwarding request to backend servers.
2268 There are 2 levels of mruby script invocations: global and
2269 per\-pattern. The global mruby script is set by \fI\%\-\-mruby\-file\fP
2270 option and is called for all requests. The per\-pattern mruby script
2271 is set by "mruby" parameter in \fI\%\-b\fP option. It is invoked for
2272 a request which matches the particular pattern. The order of hook
2273 invocation is: global request phase hook, per\-pattern request phase
2274 hook, per\-pattern response phase hook, and finally global response
2275 phase hook. If a hook returns a response, any later hooks are not
2276 invoked. The global request hook is invoked before the pattern
2277 matching is made and changing request path may affect the pattern
2280 Please note that request and response hooks of per\-pattern mruby
2281 script for a single request might not come from the same script. This
2282 might happen after a request hook is executed, backend failed for some
2283 reason, and at the same time, backend configuration is replaced by API
2284 request, and then the request uses new configuration on retry. The
2285 response hook from new configuration, if it is specified, will be
2288 The all mruby script will be evaluated once per thread on startup, and
2289 it must instantiate object and evaluate it as the return value (e.g.,
2290 \fBApp.new\fP). This object is called app object. If app object
2291 defines \fBon_req\fP method, it is called with \fI\%Nghttpx::Env\fP
2292 object on request hook. Similarly, if app object defines \fBon_resp\fP
2293 method, it is called with \fI\%Nghttpx::Env\fP object on response
2294 hook. For each method invocation, user can can access
2295 \fI\%Nghttpx::Request\fP and \fI\%Nghttpx::Response\fP objects
2296 via \fI\%Nghttpx::Env#req\fP and \fI\%Nghttpx::Env#resp\fP
2300 .B Nghttpx::REQUEST_PHASE
2301 Constant to represent request phase.
2305 .B Nghttpx::RESPONSE_PHASE
2306 Constant to represent response phase.
2310 .B class Nghttpx::Env
2311 Object to represent current request specific context.
2314 .B attribute [R] req
2315 Return \fI\%Request\fP object.
2319 .B attribute [R] resp
2320 Return \fI\%Response\fP object.
2324 .B attribute [R] ctx
2325 Return Ruby hash object. It persists until request finishes.
2326 So values set in request phase hook can be retrieved in
2327 response phase hook.
2331 .B attribute [R] phase
2332 Return the current phase.
2336 .B attribute [R] remote_addr
2337 Return IP address of a remote client. If connection is made
2338 via UNIX domain socket, this returns the string "localhost".
2342 .B attribute [R] server_addr
2343 Return address of server that accepted the connection. This
2344 is a string which specified in \fI\%\-\-frontend\fP option,
2345 excluding port number, and not a resolved IP address. For
2346 UNIX domain socket, this is a path to UNIX domain socket.
2350 .B attribute [R] server_port
2351 Return port number of the server frontend which accepted the
2352 connection from client.
2356 .B attribute [R] tls_used
2357 Return true if TLS is used on the connection.
2361 .B attribute [R] tls_sni
2362 Return the TLS SNI value which client sent in this connection.
2366 .B attribute [R] tls_client_fingerprint_sha256
2367 Return the SHA\-256 fingerprint of a client certificate.
2371 .B attribute [R] tls_client_fingerprint_sha1
2372 Return the SHA\-1 fingerprint of a client certificate.
2376 .B attribute [R] tls_client_issuer_name
2377 Return the issuer name of a client certificate.
2381 .B attribute [R] tls_client_subject_name
2382 Return the subject name of a client certificate.
2386 .B attribute [R] tls_client_serial
2387 Return the serial number of a client certificate.
2391 .B attribute [R] tls_client_not_before
2392 Return the start date of a client certificate in seconds since
2397 .B attribute [R] tls_client_not_after
2398 Return the end date of a client certificate in seconds since
2403 .B attribute [R] tls_cipher
2404 Return a TLS cipher negotiated in this connection.
2408 .B attribute [R] tls_protocol
2409 Return a TLS protocol version negotiated in this connection.
2413 .B attribute [R] tls_session_id
2414 Return a session ID for this connection in hex string.
2418 .B attribute [R] tls_session_reused
2419 Return true if, and only if a SSL/TLS session is reused.
2423 .B attribute [R] alpn
2424 Return ALPN identifier negotiated in this connection.
2428 .B attribute [R] tls_handshake_finished
2429 Return true if SSL/TLS handshake has finished. If it returns
2430 false in the request phase hook, the request is received in
2431 TLSv1.3 early data (0\-RTT) and might be vulnerable to the
2432 replay attack. nghttpx will send Early\-Data header field to
2433 backend servers to indicate this.
2438 .B class Nghttpx::Request
2439 Object to represent request from client. The modification to
2440 Request object is allowed only in request phase hook.
2443 .B attribute [R] http_version_major
2444 Return HTTP major version.
2448 .B attribute [R] http_version_minor
2449 Return HTTP minor version.
2453 .B attribute [R/W] method
2454 HTTP method. On assignment, copy of given value is assigned.
2455 We don\(aqt accept arbitrary method name. We will document them
2456 later, but well known methods, like GET, PUT and POST, are all
2461 .B attribute [R/W] authority
2462 Authority (i.e., example.org), including optional port
2463 component . On assignment, copy of given value is assigned.
2467 .B attribute [R/W] scheme
2468 Scheme (i.e., http, https). On assignment, copy of given
2473 .B attribute [R/W] path
2474 Request path, including query component (i.e., /index.html).
2475 On assignment, copy of given value is assigned. The path does
2476 not include authority component of URI. This may include
2477 query component. nghttpx makes certain normalization for
2478 path. It decodes percent\-encoding for unreserved characters
2479 (see \fI\%https://tools.ietf.org/html/rfc3986#section\-2.3\fP), and
2480 resolves ".." and ".". But it may leave characters which
2481 should be percent\-encoded as is. So be careful when comparing
2482 path against desired string.
2486 .B attribute [R] headers
2487 Return Ruby hash containing copy of request header fields.
2488 Changing values in returned hash does not change request
2489 header fields actually used in request processing. Use
2490 \fI\%Nghttpx::Request#add_header\fP or
2491 \fI\%Nghttpx::Request#set_header\fP to change request
2496 .B add_header(key, value)
2497 Add header entry associated with key. The value can be single
2498 string or array of string. It does not replace any existing
2499 values associated with key.
2503 .B set_header(key, value)
2504 Set header entry associated with key. The value can be single
2505 string or array of string. It replaces any existing values
2506 associated with key.
2511 Clear all existing request header fields.
2516 Initiate to push resource identified by \fIuri\fP\&. Only HTTP/2
2517 protocol supports this feature. For the other protocols, this
2518 method is noop. \fIuri\fP can be absolute URI, absolute path or
2519 relative path to the current request. For absolute or
2520 relative path, scheme and authority are inherited from the
2521 current request. Currently, method is always GET. nghttpx
2522 will issue request to backend servers to fulfill this request.
2523 The request and response phase hooks will be called for pushed
2529 .B class Nghttpx::Response
2530 Object to represent response from backend server.
2533 .B attribute [R] http_version_major
2534 Return HTTP major version.
2538 .B attribute [R] http_version_minor
2539 Return HTTP minor version.
2543 .B attribute [R/W] status
2544 HTTP status code. It must be in the range [200, 999],
2545 inclusive. The non\-final status code is not supported in
2546 mruby scripting at the moment.
2550 .B attribute [R] headers
2551 Return Ruby hash containing copy of response header fields.
2552 Changing values in returned hash does not change response
2553 header fields actually used in response processing. Use
2554 \fI\%Nghttpx::Response#add_header\fP or
2555 \fI\%Nghttpx::Response#set_header\fP to change response
2560 .B add_header(key, value)
2561 Add header entry associated with key. The value can be single
2562 string or array of string. It does not replace any existing
2563 values associated with key.
2567 .B set_header(key, value)
2568 Set header entry associated with key. The value can be single
2569 string or array of string. It replaces any existing values
2570 associated with key.
2575 Clear all existing response header fields.
2580 Return custom response \fIbody\fP to a client. When this method
2581 is called in request phase hook, the request is not forwarded
2582 to the backend, and response phase hook for this request will
2583 not be invoked. When this method is called in response phase
2584 hook, response from backend server is canceled and discarded.
2585 The status code and response header fields should be set
2586 before using this method. To set status code, use
2587 \fI\%Nghttpx::Response#status\fP\&. If status code is not
2588 set, 200 is used. To set response header fields,
2589 \fI\%Nghttpx::Response#add_header\fP and
2590 \fI\%Nghttpx::Response#set_header\fP\&. When this method is
2591 invoked in response phase hook, the response headers are
2592 filled with the ones received from backend server. To send
2593 completely custom header fields, first call
2594 \fI\%Nghttpx::Response#clear_headers\fP to erase all
2595 existing header fields, and then add required header fields.
2596 It is an error to call this method twice for a given request.
2600 .B send_info(status, headers)
2601 Send non\-final (informational) response to a client. \fIstatus\fP
2602 must be in the range [100, 199], inclusive. \fIheaders\fP is a
2603 hash containing response header fields. Its key must be a
2604 string, and the associated value must be either string or
2605 array of strings. Since this is not a final response, even if
2606 this method is invoked, request is still forwarded to a
2607 backend unless \fI\%Nghttpx::Response#return\fP is called.
2608 This method can be called multiple times. It cannot be called
2609 after \fI\%Nghttpx::Response#return\fP is called.
2614 Modify request path:
2622 env.req.path = "/apps#{env.req.path}"
2632 Don\(aqt forget to instantiate and evaluate object at the last line.
2634 Restrict permission of viewing a content to a specific client
2643 allowed_clients = ["127.0.0.1", "::1"]
2645 if env.req.path.start_with?("/log/") &&
2646 !allowed_clients.include?(env.remote_addr) then
2647 env.resp.status = 404
2648 env.resp.return "permission denied"
2660 nghttpx exposes API endpoints to manipulate it via HTTP based API. By
2661 default, API endpoint is disabled. To enable it, add a dedicated
2662 frontend for API using \fI\%\-\-frontend\fP option with "api"
2663 parameter. All requests which come from this frontend address, will
2664 be treated as API request.
2666 The response is normally JSON dictionary, and at least includes the
2671 The status of the request processing. The following values are
2676 The request was successful.
2679 The request was failed. No change has been made.
2686 Additionally, depending on the API endpoint, \fBdata\fP key may be
2687 present, and its value contains the API endpoint specific data.
2689 We wrote "normally", since nghttpx may return ordinal HTML response in
2690 some cases where the error has occurred before reaching API endpoint
2691 (e.g., header field is too large).
2693 The following section describes available API endpoints.
2694 .SS POST /api/v1beta1/backendconfig
2696 This API replaces the current backend server settings with the
2697 requested ones. The request method should be POST, but PUT is also
2698 acceptable. The request body must be nghttpx configuration file
2699 format. For configuration file format, see \fI\%FILES\fP section. The
2700 line separator inside the request body must be single LF (0x0A).
2701 Currently, only \fI\%backend\fP option is parsed, the
2702 others are simply ignored. The semantics of this API is replace the
2703 current backend with the backend options in request body. Describe
2704 the desired set of backend severs, and nghttpx makes it happen. If
2705 there is no \fI\%backend\fP option is found in request
2706 body, the current set of backend is replaced with the \fI\%backend\fP option\(aqs default value, which is \fB127.0.0.1,80\fP\&.
2708 The replacement is done instantly without breaking existing
2709 connections or requests. It also avoids any process creation as is
2710 the case with hot swapping with signals.
2712 The one limitation is that only numeric IP address is allowed in
2713 \fI\%backend\fP in request body unless "dns" parameter
2714 is used while non numeric hostname is allowed in command\-line or
2715 configuration file is read using \fI\%\-\-conf\fP\&.
2716 .SS GET /api/v1beta1/configrevision
2718 This API returns configuration revision of the current nghttpx. The
2719 configuration revision is opaque string, and it changes after each
2720 reloading by SIGHUP. With this API, an external application knows
2721 that whether nghttpx has finished reloading its configuration by
2722 comparing the configuration revisions between before and after
2723 reloading. It is recommended to disable persistent (keep\-alive)
2724 connection for this purpose in order to avoid to send a request using
2725 the reused connection which may bound to an old process.
2727 This API returns response including \fBdata\fP key. Its value is JSON
2728 object, and it contains at least the following key:
2732 The configuration revision of the current nghttpx
2736 \fBnghttp(1)\fP, \fBnghttpd(1)\fP, \fBh2load(1)\fP
2740 2012, 2015, 2016, Tatsuhiro Tsujikawa
2741 .\" Generated by docutils manpage writer.