2 .. GENERATED by help2rst.py. DO NOT EDIT DIRECTLY.
12 **nghttpx** [OPTIONS]... [<PRIVATE_KEY> <CERT>]
17 A reverse proxy for HTTP/2, and HTTP/1.
19 .. describe:: <PRIVATE_KEY>
22 Set path to server's private key. Required unless
23 "no-tls" parameter is used in :option:`--frontend` option.
27 Set path to server's certificate. Required unless
28 "no-tls" parameter is used in :option:`--frontend` option. To
29 make OCSP stapling work, this must be an absolute path.
35 The options are categorized into several groups.
40 .. option:: -b, --backend=(<HOST>,<PORT>|unix:<PATH>)[;[<PATTERN>[:...]][[;<PARAM>]...]
43 Set backend host and port. The multiple backend
44 addresses are accepted by repeating this option. UNIX
45 domain socket can be specified by prefixing path name
46 with "unix:" (e.g., unix:/var/run/backend.sock).
48 Optionally, if <PATTERN>s are given, the backend address
49 is only used if request matches the pattern. The
50 pattern matching is closely designed to ServeMux in
51 net/http package of Go programming language. <PATTERN>
52 consists of path, host + path or just host. The path
53 must start with "*/*". If it ends with "*/*", it matches
54 all request path in its subtree. To deal with the
55 request to the directory without trailing slash, the
56 path which ends with "*/*" also matches the request path
57 which only lacks trailing '*/*' (e.g., path "*/foo/*"
58 matches request path "*/foo*"). If it does not end with
59 "*/*", it performs exact match against the request path.
60 If host is given, it performs a match against the
61 request host. For a request received on the frontend
62 listener with "sni-fwd" parameter enabled, SNI host is
63 used instead of a request host. If host alone is given,
64 "*/*" is appended to it, so that it matches all request
65 paths under the host (e.g., specifying "nghttp2.org"
66 equals to "nghttp2.org/"). CONNECT method is treated
67 specially. It does not have path, and we don't allow
68 empty path. To workaround this, we assume that CONNECT
69 method has "*/*" as path.
71 Patterns with host take precedence over patterns with
72 just path. Then, longer patterns take precedence over
75 Host can include "\*" in the left most position to
76 indicate wildcard match (only suffix match is done).
77 The "\*" must match at least one character. For example,
78 host pattern "\*.nghttp2.org" matches against
79 "www.nghttp2.org" and "git.ngttp2.org", but does not
80 match against "nghttp2.org". The exact hosts match
81 takes precedence over the wildcard hosts match.
83 If path part ends with "\*", it is treated as wildcard
84 path. The wildcard path behaves differently from the
85 normal path. For normal path, match is made around the
86 boundary of path component separator,"*/*". On the other
87 hand, the wildcard path does not take into account the
88 path component separator. All paths which include the
89 wildcard path without last "\*" as prefix, and are
90 strictly longer than wildcard path without last "\*" are
91 matched. "\*" must match at least one character. For
92 example, the pattern "*/foo\**" matches "*/foo/*" and
93 "*/foobar*". But it does not match "*/foo*", or "*/fo*".
95 If <PATTERN> is omitted or empty string, "*/*" is used as
96 pattern, which matches all request paths (catch-all
97 pattern). The catch-all backend must be given.
99 When doing a match, nghttpx made some normalization to
100 pattern, request host and path. For host part, they are
101 converted to lower case. For path part, percent-encoded
102 unreserved characters defined in RFC 3986 are decoded,
103 and any dot-segments (".." and ".") are resolved and
106 For example, :option:`-b`\'127.0.0.1,8080;nghttp2.org/httpbin/'
107 matches the request host "nghttp2.org" and the request
108 path "*/httpbin/get*", but does not match the request host
109 "nghttp2.org" and the request path "*/index.html*".
111 The multiple <PATTERN>s can be specified, delimiting
112 them by ":". Specifying
113 :option:`-b`\'127.0.0.1,8080;nghttp2.org:www.nghttp2.org' has the
114 same effect to specify :option:`-b`\'127.0.0.1,8080;nghttp2.org'
115 and :option:`-b`\'127.0.0.1,8080;www.nghttp2.org'.
117 The backend addresses sharing same <PATTERN> are grouped
118 together forming load balancing group.
120 Several parameters <PARAM> are accepted after <PATTERN>.
121 The parameters are delimited by ";". The available
122 parameters are: "proto=<PROTO>", "tls",
123 "sni=<SNI_HOST>", "fall=<N>", "rise=<N>",
124 "affinity=<METHOD>", "dns", "redirect-if-not-tls",
125 "upgrade-scheme", "mruby=<PATH>",
126 "read-timeout=<DURATION>", "write-timeout=<DURATION>",
127 "group=<GROUP>", "group-weight=<N>", and "weight=<N>".
128 The parameter consists of keyword, and optionally
129 followed by "=" and value. For example, the parameter
130 "proto=h2" consists of the keyword "proto" and value
131 "h2". The parameter "tls" consists of the keyword "tls"
132 without value. Each parameter is described as follows.
134 The backend application protocol can be specified using
135 optional "proto" parameter, and in the form of
136 "proto=<PROTO>". <PROTO> should be one of the following
137 list without quotes: "h2", "http/1.1". The default
138 value of <PROTO> is "http/1.1". Note that usually "h2"
139 refers to HTTP/2 over TLS. But in this option, it may
140 mean HTTP/2 over cleartext TCP unless "tls" keyword is
143 TLS can be enabled by specifying optional "tls"
144 parameter. TLS is not enabled by default.
146 With "sni=<SNI_HOST>" parameter, it can override the TLS
147 SNI field value with given <SNI_HOST>. This will
148 default to the backend <HOST> name
150 The feature to detect whether backend is online or
151 offline can be enabled using optional "fall" and "rise"
152 parameters. Using "fall=<N>" parameter, if nghttpx
153 cannot connect to a this backend <N> times in a row,
154 this backend is assumed to be offline, and it is
155 excluded from load balancing. If <N> is 0, this backend
156 never be excluded from load balancing whatever times
157 nghttpx cannot connect to it, and this is the default.
158 There is also "rise=<N>" parameter. After backend was
159 excluded from load balancing group, nghttpx periodically
160 attempts to make a connection to the failed backend, and
161 if the connection is made successfully <N> times in a
162 row, the backend is assumed to be online, and it is now
163 eligible for load balancing target. If <N> is 0, a
164 backend is permanently offline, once it goes in that
165 state, and this is the default behaviour.
167 The session affinity is enabled using
168 "affinity=<METHOD>" parameter. If "ip" is given in
169 <METHOD>, client IP based session affinity is enabled.
170 If "cookie" is given in <METHOD>, cookie based session
171 affinity is enabled. If "none" is given in <METHOD>,
172 session affinity is disabled, and this is the default.
173 The session affinity is enabled per <PATTERN>. If at
174 least one backend has "affinity" parameter, and its
175 <METHOD> is not "none", session affinity is enabled for
176 all backend servers sharing the same <PATTERN>. It is
177 advised to set "affinity" parameter to all backend
178 explicitly if session affinity is desired. The session
179 affinity may break if one of the backend gets
180 unreachable, or backend settings are reloaded or
183 If "affinity=cookie" is used, the additional
184 configuration is required.
185 "affinity-cookie-name=<NAME>" must be used to specify a
186 name of cookie to use. Optionally,
187 "affinity-cookie-path=<PATH>" can be used to specify a
188 path which cookie is applied. The optional
189 "affinity-cookie-secure=<SECURE>" controls the Secure
190 attribute of a cookie. The default value is "auto", and
191 the Secure attribute is determined by a request scheme.
192 If a request scheme is "https", then Secure attribute is
193 set. Otherwise, it is not set. If <SECURE> is "yes",
194 the Secure attribute is always set. If <SECURE> is
195 "no", the Secure attribute is always omitted.
197 By default, name resolution of backend host name is done
198 at start up, or reloading configuration. If "dns"
199 parameter is given, name resolution takes place
200 dynamically. This is useful if backend address changes
201 frequently. If "dns" is given, name resolution of
202 backend host name at start up, or reloading
203 configuration is skipped.
205 If "redirect-if-not-tls" parameter is used, the matched
206 backend requires that frontend connection is TLS
207 encrypted. If it isn't, nghttpx responds to the request
208 with 308 status code, and https URI the client should
209 use instead is included in Location header field. The
210 port number in redirect URI is 443 by default, and can
211 be changed using :option:`--redirect-https-port` option. If at
212 least one backend has "redirect-if-not-tls" parameter,
213 this feature is enabled for all backend servers sharing
214 the same <PATTERN>. It is advised to set
215 "redirect-if-no-tls" parameter to all backends
216 explicitly if this feature is desired.
218 If "upgrade-scheme" parameter is used along with "tls"
219 parameter, HTTP/2 :scheme pseudo header field is changed
220 to "https" from "http" when forwarding a request to this
221 particular backend. This is a workaround for a backend
222 server which requires "https" :scheme pseudo header
223 field on TLS encrypted connection.
225 "mruby=<PATH>" parameter specifies a path to mruby
226 script file which is invoked when this pattern is
227 matched. All backends which share the same pattern must
228 have the same mruby path.
230 "read-timeout=<DURATION>" and "write-timeout=<DURATION>"
231 parameters specify the read and write timeout of the
232 backend connection when this pattern is matched. All
233 backends which share the same pattern must have the same
234 timeouts. If these timeouts are entirely omitted for a
235 pattern, :option:`--backend-read-timeout` and
236 :option:`--backend-write-timeout` are used.
238 "group=<GROUP>" parameter specifies the name of group
239 this backend address belongs to. By default, it belongs
240 to the unnamed default group. The name of group is
241 unique per pattern. "group-weight=<N>" parameter
242 specifies the weight of the group. The higher weight
243 gets more frequently selected by the load balancing
244 algorithm. <N> must be [1, 256] inclusive. The weight
245 8 has 4 times more weight than 2. <N> must be the same
246 for all addresses which share the same <GROUP>. If
247 "group-weight" is omitted in an address, but the other
248 address which belongs to the same group specifies
249 "group-weight", its weight is used. If no
250 "group-weight" is specified for all addresses, the
251 weight of a group becomes 1. "group" and "group-weight"
252 are ignored if session affinity is enabled.
254 "weight=<N>" parameter specifies the weight of the
255 backend address inside a group which this address
256 belongs to. The higher weight gets more frequently
257 selected by the load balancing algorithm. <N> must be
258 [1, 256] inclusive. The weight 8 has 4 times more
259 weight than weight 2. If this parameter is omitted,
260 weight becomes 1. "weight" is ignored if session
263 Since ";" and ":" are used as delimiter, <PATTERN> must
264 not contain these characters. Since ";" has special
265 meaning in shell, the option value must be quoted.
268 Default: ``127.0.0.1,80``
270 .. option:: -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]
272 Set frontend host and port. If <HOST> is '\*', it
273 assumes all addresses including both IPv4 and IPv6.
274 UNIX domain socket can be specified by prefixing path
275 name with "unix:" (e.g., unix:/var/run/nghttpx.sock).
276 This option can be used multiple times to listen to
279 This option can take 0 or more parameters, which are
280 described below. Note that "api" and "healthmon"
281 parameters are mutually exclusive.
283 Optionally, TLS can be disabled by specifying "no-tls"
284 parameter. TLS is enabled by default.
286 If "sni-fwd" parameter is used, when performing a match
287 to select a backend server, SNI host name received from
288 the client is used instead of the request host. See
289 :option:`--backend` option about the pattern match.
291 To make this frontend as API endpoint, specify "api"
292 parameter. This is disabled by default. It is
293 important to limit the access to the API frontend.
294 Otherwise, someone may change the backend server, and
295 break your services, or expose confidential information
296 to the outside the world.
298 To make this frontend as health monitor endpoint,
299 specify "healthmon" parameter. This is disabled by
300 default. Any requests which come through this address
301 are replied with 200 HTTP status, without no body.
303 To accept PROXY protocol version 1 and 2 on frontend
304 connection, specify "proxyproto" parameter. This is
310 .. option:: --backlog=<N>
312 Set listen backlog size.
316 .. option:: --backend-address-family=(auto|IPv4|IPv6)
318 Specify address family of backend connections. If
319 "auto" is given, both IPv4 and IPv6 are considered. If
320 "IPv4" is given, only IPv4 address is considered. If
321 "IPv6" is given, only IPv6 address is considered.
325 .. option:: --backend-http-proxy-uri=<URI>
327 Specify proxy URI in the form
328 http://[<USER>:<PASS>@]<PROXY>:<PORT>. If a proxy
329 requires authentication, specify <USER> and <PASS>.
330 Note that they must be properly percent-encoded. This
331 proxy is used when the backend connection is HTTP/2.
332 First, make a CONNECT request to the proxy and it
333 connects to the backend on behalf of nghttpx. This
334 forms tunnel. After that, nghttpx performs SSL/TLS
335 handshake with the downstream through the tunnel. The
336 timeouts when connecting and making CONNECT request can
337 be specified by :option:`--backend-read-timeout` and
338 :option:`--backend-write-timeout` options.
344 .. option:: -n, --workers=<N>
346 Set the number of worker threads.
350 .. option:: --single-thread
352 Run everything in one thread inside the worker process.
353 This feature is provided for better debugging
354 experience, or for the platforms which lack thread
355 support. If threading is disabled, this option is
358 .. option:: --read-rate=<SIZE>
360 Set maximum average read rate on frontend connection.
361 Setting 0 to this option means read rate is unlimited.
365 .. option:: --read-burst=<SIZE>
367 Set maximum read burst size on frontend connection.
368 Setting 0 to this option means read burst size is
373 .. option:: --write-rate=<SIZE>
375 Set maximum average write rate on frontend connection.
376 Setting 0 to this option means write rate is unlimited.
380 .. option:: --write-burst=<SIZE>
382 Set maximum write burst size on frontend connection.
383 Setting 0 to this option means write burst size is
388 .. option:: --worker-read-rate=<SIZE>
390 Set maximum average read rate on frontend connection per
391 worker. Setting 0 to this option means read rate is
392 unlimited. Not implemented yet.
396 .. option:: --worker-read-burst=<SIZE>
398 Set maximum read burst size on frontend connection per
399 worker. Setting 0 to this option means read burst size
400 is unlimited. Not implemented yet.
404 .. option:: --worker-write-rate=<SIZE>
406 Set maximum average write rate on frontend connection
407 per worker. Setting 0 to this option means write rate
408 is unlimited. Not implemented yet.
412 .. option:: --worker-write-burst=<SIZE>
414 Set maximum write burst size on frontend connection per
415 worker. Setting 0 to this option means write burst size
416 is unlimited. Not implemented yet.
420 .. option:: --worker-frontend-connections=<N>
422 Set maximum number of simultaneous connections frontend
423 accepts. Setting 0 means unlimited.
427 .. option:: --backend-connections-per-host=<N>
429 Set maximum number of backend concurrent connections
430 (and/or streams in case of HTTP/2) per origin host.
431 This option is meaningful when :option:`--http2-proxy` option is
432 used. The origin host is determined by authority
433 portion of request URI (or :authority header field for
434 HTTP/2). To limit the number of connections per
435 frontend for default mode, use
436 :option:`--backend-connections-per-frontend`\.
440 .. option:: --backend-connections-per-frontend=<N>
442 Set maximum number of backend concurrent connections
443 (and/or streams in case of HTTP/2) per frontend. This
444 option is only used for default mode. 0 means
445 unlimited. To limit the number of connections per host
446 with :option:`--http2-proxy` option, use
447 :option:`--backend-connections-per-host`\.
451 .. option:: --rlimit-nofile=<N>
453 Set maximum number of open files (RLIMIT_NOFILE) to <N>.
454 If 0 is given, nghttpx does not set the limit.
458 .. option:: --backend-request-buffer=<SIZE>
460 Set buffer size used to store backend request.
464 .. option:: --backend-response-buffer=<SIZE>
466 Set buffer size used to store backend response.
470 .. option:: --fastopen=<N>
472 Enables "TCP Fast Open" for the listening socket and
473 limits the maximum length for the queue of connections
474 that have not yet completed the three-way handshake. If
475 value is 0 then fast open is disabled.
479 .. option:: --no-kqueue
481 Don't use kqueue. This option is only applicable for
482 the platforms which have kqueue. For other platforms,
483 this option will be simply ignored.
489 .. option:: --frontend-http2-read-timeout=<DURATION>
491 Specify read timeout for HTTP/2 frontend connection.
495 .. option:: --frontend-read-timeout=<DURATION>
497 Specify read timeout for HTTP/1.1 frontend connection.
501 .. option:: --frontend-write-timeout=<DURATION>
503 Specify write timeout for all frontend connections.
507 .. option:: --frontend-keep-alive-timeout=<DURATION>
509 Specify keep-alive timeout for frontend HTTP/1
514 .. option:: --stream-read-timeout=<DURATION>
516 Specify read timeout for HTTP/2 streams. 0 means no
521 .. option:: --stream-write-timeout=<DURATION>
523 Specify write timeout for HTTP/2 streams. 0 means no
528 .. option:: --backend-read-timeout=<DURATION>
530 Specify read timeout for backend connection.
534 .. option:: --backend-write-timeout=<DURATION>
536 Specify write timeout for backend connection.
540 .. option:: --backend-connect-timeout=<DURATION>
542 Specify timeout before establishing TCP connection to
547 .. option:: --backend-keep-alive-timeout=<DURATION>
549 Specify keep-alive timeout for backend HTTP/1
554 .. option:: --listener-disable-timeout=<DURATION>
556 After accepting connection failed, connection listener
557 is disabled for a given amount of time. Specifying 0
558 disables this feature.
562 .. option:: --frontend-http2-setting-timeout=<DURATION>
564 Specify timeout before SETTINGS ACK is received from
569 .. option:: --backend-http2-settings-timeout=<DURATION>
571 Specify timeout before SETTINGS ACK is received from
576 .. option:: --backend-max-backoff=<DURATION>
578 Specify maximum backoff interval. This is used when
579 doing health check against offline backend (see "fail"
580 parameter in :option:`--backend` option). It is also used to
581 limit the maximum interval to temporarily disable
582 backend when nghttpx failed to connect to it. These
583 intervals are calculated using exponential backoff, and
584 consecutive failed attempts increase the interval. This
585 option caps its maximum value.
593 .. option:: --ciphers=<SUITE>
595 Set allowed cipher list for frontend connection. The
596 format of the string is described in OpenSSL ciphers(1).
597 This option sets cipher suites for TLSv1.2 or earlier.
598 Use :option:`--tls13-ciphers` for TLSv1.3.
600 Default: ``ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256``
602 .. option:: --tls13-ciphers=<SUITE>
604 Set allowed cipher list for frontend connection. The
605 format of the string is described in OpenSSL ciphers(1).
606 This option sets cipher suites for TLSv1.3. Use
607 :option:`--ciphers` for TLSv1.2 or earlier.
609 Default: ``TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256``
611 .. option:: --client-ciphers=<SUITE>
613 Set allowed cipher list for backend connection. The
614 format of the string is described in OpenSSL ciphers(1).
615 This option sets cipher suites for TLSv1.2 or earlier.
616 Use :option:`--tls13-client-ciphers` for TLSv1.3.
618 Default: ``ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256``
620 .. option:: --tls13-client-ciphers=<SUITE>
622 Set allowed cipher list for backend connection. The
623 format of the string is described in OpenSSL ciphers(1).
624 This option sets cipher suites for TLSv1.3. Use
625 :option:`--tls13-client-ciphers` for TLSv1.2 or earlier.
627 Default: ``TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256``
629 .. option:: --ecdh-curves=<LIST>
631 Set supported curve list for frontend connections.
632 <LIST> is a colon separated list of curve NID or names
633 in the preference order. The supported curves depend on
634 the linked OpenSSL library. This function requires
637 Default: ``X25519:P-256:P-384:P-521``
639 .. option:: -k, --insecure
641 Don't verify backend server's certificate if TLS is
642 enabled for backend connections.
644 .. option:: --cacert=<PATH>
646 Set path to trusted CA certificate file. It is used in
647 backend TLS connections to verify peer's certificate.
648 It is also used to verify OCSP response from the script
649 set by :option:`--fetch-ocsp-response-file`\. The file must be in
650 PEM format. It can contain multiple certificates. If
651 the linked OpenSSL is configured to load system wide
652 certificates, they are loaded at startup regardless of
655 .. option:: --private-key-passwd-file=<PATH>
657 Path to file that contains password for the server's
658 private key. If none is given and the private key is
659 password protected it'll be requested interactively.
661 .. option:: --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]
663 Specify additional certificate and private key file.
664 nghttpx will choose certificates based on the hostname
665 indicated by client using TLS SNI extension. If nghttpx
666 is built with OpenSSL >= 1.0.2, the shared elliptic
667 curves (e.g., P-256) between client and server are also
668 taken into consideration. This allows nghttpx to send
669 ECDSA certificate to modern clients, while sending RSA
670 based certificate to older clients. This option can be
671 used multiple times. To make OCSP stapling work,
672 <CERTPATH> must be absolute path.
674 Additional parameter can be specified in <PARAM>. The
675 available <PARAM> is "sct-dir=<DIR>".
677 "sct-dir=<DIR>" specifies the path to directory which
678 contains \*.sct files for TLS
679 signed_certificate_timestamp extension (RFC 6962). This
680 feature requires OpenSSL >= 1.0.2. See also
681 :option:`--tls-sct-dir` option.
683 .. option:: --dh-param-file=<PATH>
685 Path to file that contains DH parameters in PEM format.
686 Without this option, DHE cipher suites are not
689 .. option:: --npn-list=<LIST>
691 Comma delimited list of ALPN protocol identifier sorted
692 in the order of preference. That means most desirable
693 protocol comes first. This is used in both ALPN and
694 NPN. The parameter must be delimited by a single comma
695 only and any white spaces are treated as a part of
698 Default: ``h2,h2-16,h2-14,http/1.1``
700 .. option:: --verify-client
702 Require and verify client certificate.
704 .. option:: --verify-client-cacert=<PATH>
706 Path to file that contains CA certificates to verify
707 client certificate. The file must be in PEM format. It
708 can contain multiple certificates.
710 .. option:: --verify-client-tolerate-expired
712 Accept expired client certificate. Operator should
713 handle the expired client certificate by some means
714 (e.g., mruby script). Otherwise, this option might
715 cause a security risk.
717 .. option:: --client-private-key-file=<PATH>
719 Path to file that contains client private key used in
720 backend client authentication.
722 .. option:: --client-cert-file=<PATH>
724 Path to file that contains client certificate used in
725 backend client authentication.
727 .. option:: --tls-min-proto-version=<VER>
729 Specify minimum SSL/TLS protocol. The name matching is
730 done in case-insensitive manner. The versions between
731 :option:`--tls-min-proto-version` and :option:`\--tls-max-proto-version` are
732 enabled. If the protocol list advertised by client does
733 not overlap this range, you will receive the error
734 message "unknown protocol". If a protocol version lower
735 than TLSv1.2 is specified, make sure that the compatible
736 ciphers are included in :option:`--ciphers` option. The default
737 cipher list only includes ciphers compatible with
738 TLSv1.2 or above. The available versions are:
739 TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
743 .. option:: --tls-max-proto-version=<VER>
745 Specify maximum SSL/TLS protocol. The name matching is
746 done in case-insensitive manner. The versions between
747 :option:`--tls-min-proto-version` and :option:`\--tls-max-proto-version` are
748 enabled. If the protocol list advertised by client does
749 not overlap this range, you will receive the error
750 message "unknown protocol". The available versions are:
751 TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0
755 .. option:: --tls-ticket-key-file=<PATH>
757 Path to file that contains random data to construct TLS
758 session ticket parameters. If aes-128-cbc is given in
759 :option:`--tls-ticket-key-cipher`\, the file must contain exactly
760 48 bytes. If aes-256-cbc is given in
761 :option:`--tls-ticket-key-cipher`\, the file must contain exactly
762 80 bytes. This options can be used repeatedly to
763 specify multiple ticket parameters. If several files
764 are given, only the first key is used to encrypt TLS
765 session tickets. Other keys are accepted but server
766 will issue new session ticket with first key. This
767 allows session key rotation. Please note that key
768 rotation does not occur automatically. User should
769 rearrange files or change options values and restart
770 nghttpx gracefully. If opening or reading given file
771 fails, all loaded keys are discarded and it is treated
772 as if none of this option is given. If this option is
773 not given or an error occurred while opening or reading
774 a file, key is generated every 1 hour internally and
775 they are valid for 12 hours. This is recommended if
776 ticket key sharing between nghttpx instances is not
779 .. option:: --tls-ticket-key-memcached=<HOST>,<PORT>[;tls]
781 Specify address of memcached server to get TLS ticket
782 keys for session resumption. This enables shared TLS
783 ticket key between multiple nghttpx instances. nghttpx
784 does not set TLS ticket key to memcached. The external
785 ticket key generator is required. nghttpx just gets TLS
786 ticket keys from memcached, and use them, possibly
787 replacing current set of keys. It is up to extern TLS
788 ticket key generator to rotate keys frequently. See
789 "TLS SESSION TICKET RESUMPTION" section in manual page
790 to know the data format in memcached entry. Optionally,
791 memcached connection can be encrypted with TLS by
792 specifying "tls" parameter.
794 .. option:: --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6)
796 Specify address family of memcached connections to get
797 TLS ticket keys. If "auto" is given, both IPv4 and IPv6
798 are considered. If "IPv4" is given, only IPv4 address
799 is considered. If "IPv6" is given, only IPv6 address is
804 .. option:: --tls-ticket-key-memcached-interval=<DURATION>
806 Set interval to get TLS ticket keys from memcached.
810 .. option:: --tls-ticket-key-memcached-max-retry=<N>
812 Set maximum number of consecutive retries before
813 abandoning TLS ticket key retrieval. If this number is
814 reached, the attempt is considered as failure, and
815 "failure" count is incremented by 1, which contributed
816 to the value controlled
817 :option:`--tls-ticket-key-memcached-max-fail` option.
821 .. option:: --tls-ticket-key-memcached-max-fail=<N>
823 Set maximum number of consecutive failure before
824 disabling TLS ticket until next scheduled key retrieval.
828 .. option:: --tls-ticket-key-cipher=<CIPHER>
830 Specify cipher to encrypt TLS session ticket. Specify
831 either aes-128-cbc or aes-256-cbc. By default,
834 .. option:: --tls-ticket-key-memcached-cert-file=<PATH>
836 Path to client certificate for memcached connections to
839 .. option:: --tls-ticket-key-memcached-private-key-file=<PATH>
841 Path to client private key for memcached connections to
844 .. option:: --fetch-ocsp-response-file=<PATH>
846 Path to fetch-ocsp-response script file. It should be
849 Default: ``/usr/local/share/nghttp2/fetch-ocsp-response``
851 .. option:: --ocsp-update-interval=<DURATION>
853 Set interval to update OCSP response cache.
857 .. option:: --ocsp-startup
859 Start accepting connections after initial attempts to
860 get OCSP responses finish. It does not matter some of
861 the attempts fail. This feature is useful if OCSP
862 responses must be available before accepting
865 .. option:: --no-verify-ocsp
867 nghttpx does not verify OCSP response.
869 .. option:: --no-ocsp
871 Disable OCSP stapling.
873 .. option:: --tls-session-cache-memcached=<HOST>,<PORT>[;tls]
875 Specify address of memcached server to store session
876 cache. This enables shared session cache between
877 multiple nghttpx instances. Optionally, memcached
878 connection can be encrypted with TLS by specifying "tls"
881 .. option:: --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6)
883 Specify address family of memcached connections to store
884 session cache. If "auto" is given, both IPv4 and IPv6
885 are considered. If "IPv4" is given, only IPv4 address
886 is considered. If "IPv6" is given, only IPv6 address is
891 .. option:: --tls-session-cache-memcached-cert-file=<PATH>
893 Path to client certificate for memcached connections to
896 .. option:: --tls-session-cache-memcached-private-key-file=<PATH>
898 Path to client private key for memcached connections to
901 .. option:: --tls-dyn-rec-warmup-threshold=<SIZE>
903 Specify the threshold size for TLS dynamic record size
904 behaviour. During a TLS session, after the threshold
905 number of bytes have been written, the TLS record size
906 will be increased to the maximum allowed (16K). The max
907 record size will continue to be used on the active TLS
908 session. After :option:`--tls-dyn-rec-idle-timeout` has elapsed,
909 the record size is reduced to 1300 bytes. Specify 0 to
910 always use the maximum record size, regardless of idle
911 period. This behaviour applies to all TLS based
912 frontends, and TLS HTTP/2 backends.
916 .. option:: --tls-dyn-rec-idle-timeout=<DURATION>
918 Specify TLS dynamic record size behaviour timeout. See
919 :option:`--tls-dyn-rec-warmup-threshold` for more information.
920 This behaviour applies to all TLS based frontends, and
925 .. option:: --no-http2-cipher-black-list
927 Allow black listed cipher suite on frontend HTTP/2
929 https://tools.ietf.org/html/rfc7540#appendix-A for the
930 complete HTTP/2 cipher suites black list.
932 .. option:: --client-no-http2-cipher-black-list
934 Allow black listed cipher suite on backend HTTP/2
936 https://tools.ietf.org/html/rfc7540#appendix-A for the
937 complete HTTP/2 cipher suites black list.
939 .. option:: --tls-sct-dir=<DIR>
941 Specifies the directory where \*.sct files exist. All
942 \*.sct files in <DIR> are read, and sent as
943 extension_data of TLS signed_certificate_timestamp (RFC
944 6962) to client. These \*.sct files are for the
945 certificate specified in positional command-line
946 argument <CERT>, or certificate option in configuration
947 file. For additional certificates, use :option:`--subcert`
948 option. This option requires OpenSSL >= 1.0.2.
950 .. option:: --psk-secrets=<PATH>
952 Read list of PSK identity and secrets from <PATH>. This
953 is used for frontend connection. The each line of input
954 file is formatted as <identity>:<hex-secret>, where
955 <identity> is PSK identity, and <hex-secret> is secret
956 in hex. An empty line, and line which starts with '#'
957 are skipped. The default enabled cipher list might not
958 contain any PSK cipher suite. In that case, desired PSK
959 cipher suites must be enabled using :option:`--ciphers` option.
960 The desired PSK cipher suite may be black listed by
961 HTTP/2. To use those cipher suites with HTTP/2,
962 consider to use :option:`--no-http2-cipher-black-list` option.
963 But be aware its implications.
965 .. option:: --client-psk-secrets=<PATH>
967 Read PSK identity and secrets from <PATH>. This is used
968 for backend connection. The each line of input file is
969 formatted as <identity>:<hex-secret>, where <identity>
970 is PSK identity, and <hex-secret> is secret in hex. An
971 empty line, and line which starts with '#' are skipped.
972 The first identity and secret pair encountered is used.
973 The default enabled cipher list might not contain any
974 PSK cipher suite. In that case, desired PSK cipher
975 suites must be enabled using :option:`--client-ciphers` option.
976 The desired PSK cipher suite may be black listed by
977 HTTP/2. To use those cipher suites with HTTP/2,
978 consider to use :option:`--client-no-http2-cipher-black-list`
979 option. But be aware its implications.
981 .. option:: --tls-no-postpone-early-data
983 By default, nghttpx postpones forwarding HTTP requests
984 sent in early data, including those sent in partially in
985 it, until TLS handshake finishes. If all backend server
986 recognizes "Early-Data" header field, using this option
987 makes nghttpx not postpone forwarding request and get
988 full potential of 0-RTT data.
990 .. option:: --tls-max-early-data=<SIZE>
992 Sets the maximum amount of 0-RTT data that server
1001 .. option:: -c, --frontend-http2-max-concurrent-streams=<N>
1003 Set the maximum number of the concurrent streams in one
1004 frontend HTTP/2 session.
1008 .. option:: --backend-http2-max-concurrent-streams=<N>
1010 Set the maximum number of the concurrent streams in one
1011 backend HTTP/2 session. This sets maximum number of
1012 concurrent opened pushed streams. The maximum number of
1013 concurrent requests are set by a remote server.
1017 .. option:: --frontend-http2-window-size=<SIZE>
1019 Sets the per-stream initial window size of HTTP/2
1020 frontend connection.
1024 .. option:: --frontend-http2-connection-window-size=<SIZE>
1026 Sets the per-connection window size of HTTP/2 frontend
1031 .. option:: --backend-http2-window-size=<SIZE>
1033 Sets the initial window size of HTTP/2 backend
1038 .. option:: --backend-http2-connection-window-size=<SIZE>
1040 Sets the per-connection window size of HTTP/2 backend
1043 Default: ``2147483647``
1045 .. option:: --http2-no-cookie-crumbling
1047 Don't crumble cookie header field.
1049 .. option:: --padding=<N>
1051 Add at most <N> bytes to a HTTP/2 frame payload as
1052 padding. Specify 0 to disable padding. This option is
1053 meant for debugging purpose and not intended to enhance
1056 .. option:: --no-server-push
1058 Disable HTTP/2 server push. Server push is supported by
1059 default mode and HTTP/2 frontend via Link header field.
1060 It is also supported if both frontend and backend are
1061 HTTP/2 in default mode. In this case, server push from
1062 backend session is relayed to frontend, and server push
1063 via Link header field is also supported.
1065 .. option:: --frontend-http2-optimize-write-buffer-size
1067 (Experimental) Enable write buffer size optimization in
1068 frontend HTTP/2 TLS connection. This optimization aims
1069 to reduce write buffer size so that it only contains
1070 bytes which can send immediately. This makes server
1071 more responsive to prioritized HTTP/2 stream because the
1072 buffering of lower priority stream is reduced. This
1073 option is only effective on recent Linux platform.
1075 .. option:: --frontend-http2-optimize-window-size
1077 (Experimental) Automatically tune connection level
1078 window size of frontend HTTP/2 TLS connection. If this
1079 feature is enabled, connection window size starts with
1080 the default window size, 65535 bytes. nghttpx
1081 automatically adjusts connection window size based on
1082 TCP receiving window size. The maximum window size is
1083 capped by the value specified by
1084 :option:`--frontend-http2-connection-window-size`\. Since the
1085 stream is subject to stream level window size, it should
1086 be adjusted using :option:`--frontend-http2-window-size` option as
1087 well. This option is only effective on recent Linux
1090 .. option:: --frontend-http2-encoder-dynamic-table-size=<SIZE>
1092 Specify the maximum dynamic table size of HPACK encoder
1093 in the frontend HTTP/2 connection. The decoder (client)
1094 specifies the maximum dynamic table size it accepts.
1095 Then the negotiated dynamic table size is the minimum of
1096 this option value and the value which client specified.
1100 .. option:: --frontend-http2-decoder-dynamic-table-size=<SIZE>
1102 Specify the maximum dynamic table size of HPACK decoder
1103 in the frontend HTTP/2 connection.
1107 .. option:: --backend-http2-encoder-dynamic-table-size=<SIZE>
1109 Specify the maximum dynamic table size of HPACK encoder
1110 in the backend HTTP/2 connection. The decoder (backend)
1111 specifies the maximum dynamic table size it accepts.
1112 Then the negotiated dynamic table size is the minimum of
1113 this option value and the value which backend specified.
1117 .. option:: --backend-http2-decoder-dynamic-table-size=<SIZE>
1119 Specify the maximum dynamic table size of HPACK decoder
1120 in the backend HTTP/2 connection.
1128 .. describe:: (default mode)
1131 Accept HTTP/2, and HTTP/1.1 over SSL/TLS. "no-tls"
1132 parameter is used in :option:`--frontend` option, accept HTTP/2
1133 and HTTP/1.1 over cleartext TCP. The incoming HTTP/1.1
1134 connection can be upgraded to HTTP/2 through HTTP
1137 .. option:: -s, --http2-proxy
1139 Like default mode, but enable forward proxy. This is so
1140 called HTTP/2 proxy mode.
1146 .. option:: -L, --log-level=<LEVEL>
1148 Set the severity level of log output. <LEVEL> must be
1149 one of INFO, NOTICE, WARN, ERROR and FATAL.
1153 .. option:: --accesslog-file=<PATH>
1155 Set path to write access log. To reopen file, send USR1
1158 .. option:: --accesslog-syslog
1160 Send access log to syslog. If this option is used,
1161 :option:`--accesslog-file` option is ignored.
1163 .. option:: --accesslog-format=<FORMAT>
1165 Specify format string for access log. The default
1166 format is combined format. The following variables are
1169 * $remote_addr: client IP address.
1170 * $time_local: local time in Common Log format.
1171 * $time_iso8601: local time in ISO 8601 format.
1172 * $request: HTTP request line.
1173 * $status: HTTP response status code.
1174 * $body_bytes_sent: the number of bytes sent to client
1176 * $http_<VAR>: value of HTTP request header <VAR> where
1177 '_' in <VAR> is replaced with '-'.
1178 * $remote_port: client port.
1179 * $server_port: server port.
1180 * $request_time: request processing time in seconds with
1181 milliseconds resolution.
1182 * $pid: PID of the running process.
1183 * $alpn: ALPN identifier of the protocol which generates
1184 the response. For HTTP/1, ALPN is always http/1.1,
1185 regardless of minor version.
1186 * $tls_cipher: cipher used for SSL/TLS connection.
1187 * $tls_client_fingerprint_sha256: SHA-256 fingerprint of
1189 * $tls_client_fingerprint_sha1: SHA-1 fingerprint of
1191 * $tls_client_subject_name: subject name in client
1193 * $tls_client_issuer_name: issuer name in client
1195 * $tls_client_serial: serial number in client
1197 * $tls_protocol: protocol for SSL/TLS connection.
1198 * $tls_session_id: session ID for SSL/TLS connection.
1199 * $tls_session_reused: "r" if SSL/TLS session was
1200 reused. Otherwise, "."
1201 * $tls_sni: SNI server name for SSL/TLS connection.
1202 * $backend_host: backend host used to fulfill the
1203 request. "-" if backend host is not available.
1204 * $backend_port: backend port used to fulfill the
1205 request. "-" if backend host is not available.
1207 The variable can be enclosed by "{" and "}" for
1208 disambiguation (e.g., ${remote_addr}).
1211 Default: ``$remote_addr - - [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"``
1213 .. option:: --accesslog-write-early
1215 Write access log when response header fields are
1216 received from backend rather than when request
1217 transaction finishes.
1219 .. option:: --errorlog-file=<PATH>
1221 Set path to write error log. To reopen file, send USR1
1222 signal to nghttpx. stderr will be redirected to the
1223 error log file unless :option:`--errorlog-syslog` is used.
1225 Default: ``/dev/stderr``
1227 .. option:: --errorlog-syslog
1229 Send error log to syslog. If this option is used,
1230 :option:`--errorlog-file` option is ignored.
1232 .. option:: --syslog-facility=<FACILITY>
1234 Set syslog facility to <FACILITY>.
1242 .. option:: --add-x-forwarded-for
1244 Append X-Forwarded-For header field to the downstream
1247 .. option:: --strip-incoming-x-forwarded-for
1249 Strip X-Forwarded-For header field from inbound client
1252 .. option:: --no-add-x-forwarded-proto
1254 Don't append additional X-Forwarded-Proto header field
1255 to the backend request. If inbound client sets
1256 X-Forwarded-Proto, and
1257 :option:`--no-strip-incoming-x-forwarded-proto` option is used,
1258 they are passed to the backend.
1260 .. option:: --no-strip-incoming-x-forwarded-proto
1262 Don't strip X-Forwarded-Proto header field from inbound
1265 .. option:: --add-forwarded=<LIST>
1267 Append RFC 7239 Forwarded header field with parameters
1268 specified in comma delimited list <LIST>. The supported
1269 parameters are "by", "for", "host", and "proto". By
1270 default, the value of "by" and "for" parameters are
1271 obfuscated string. See :option:`--forwarded-by` and
1272 :option:`--forwarded-for` options respectively. Note that nghttpx
1273 does not translate non-standard X-Forwarded-\* header
1274 fields into Forwarded header field, and vice versa.
1276 .. option:: --strip-incoming-forwarded
1278 Strip Forwarded header field from inbound client
1281 .. option:: --forwarded-by=(obfuscated|ip|<VALUE>)
1283 Specify the parameter value sent out with "by" parameter
1284 of Forwarded header field. If "obfuscated" is given,
1285 the string is randomly generated at startup. If "ip" is
1286 given, the interface address of the connection,
1287 including port number, is sent with "by" parameter. In
1288 case of UNIX domain socket, "localhost" is used instead
1289 of address and port. User can also specify the static
1290 obfuscated string. The limitation is that it must start
1291 with "_", and only consists of character set
1292 [A-Za-z0-9._-], as described in RFC 7239.
1294 Default: ``obfuscated``
1296 .. option:: --forwarded-for=(obfuscated|ip)
1298 Specify the parameter value sent out with "for"
1299 parameter of Forwarded header field. If "obfuscated" is
1300 given, the string is randomly generated for each client
1301 connection. If "ip" is given, the remote client address
1302 of the connection, without port number, is sent with
1303 "for" parameter. In case of UNIX domain socket,
1304 "localhost" is used instead of address.
1306 Default: ``obfuscated``
1308 .. option:: --no-via
1310 Don't append to Via header field. If Via header field
1311 is received, it is left unaltered.
1313 .. option:: --no-strip-incoming-early-data
1315 Don't strip Early-Data header field from inbound client
1318 .. option:: --no-location-rewrite
1320 Don't rewrite location header field in default mode.
1321 When :option:`--http2-proxy` is used, location header field will
1322 not be altered regardless of this option.
1324 .. option:: --host-rewrite
1326 Rewrite host and :authority header fields in default
1327 mode. When :option:`--http2-proxy` is used, these headers will
1328 not be altered regardless of this option.
1330 .. option:: --altsvc=<PROTOID,PORT[,HOST,[ORIGIN]]>
1332 Specify protocol ID, port, host and origin of
1333 alternative service. <HOST> and <ORIGIN> are optional.
1334 They are advertised in alt-svc header field only in
1335 HTTP/1.1 frontend. This option can be used multiple
1336 times to specify multiple alternative services.
1337 Example: :option:`--altsvc`\=h2,443
1339 .. option:: --add-request-header=<HEADER>
1341 Specify additional header field to add to request header
1342 set. This option just appends header field and won't
1343 replace anything already set. This option can be used
1344 several times to specify multiple header fields.
1345 Example: :option:`--add-request-header`\="foo: bar"
1347 .. option:: --add-response-header=<HEADER>
1349 Specify additional header field to add to response
1350 header set. This option just appends header field and
1351 won't replace anything already set. This option can be
1352 used several times to specify multiple header fields.
1353 Example: :option:`--add-response-header`\="foo: bar"
1355 .. option:: --request-header-field-buffer=<SIZE>
1357 Set maximum buffer size for incoming HTTP request header
1358 field list. This is the sum of header name and value in
1359 bytes. If trailer fields exist, they are counted
1360 towards this number.
1364 .. option:: --max-request-header-fields=<N>
1366 Set maximum number of incoming HTTP request header
1367 fields. If trailer fields exist, they are counted
1368 towards this number.
1372 .. option:: --response-header-field-buffer=<SIZE>
1374 Set maximum buffer size for incoming HTTP response
1375 header field list. This is the sum of header name and
1376 value in bytes. If trailer fields exist, they are
1377 counted towards this number.
1381 .. option:: --max-response-header-fields=<N>
1383 Set maximum number of incoming HTTP response header
1384 fields. If trailer fields exist, they are counted
1385 towards this number.
1389 .. option:: --error-page=(<CODE>|*)=<PATH>
1391 Set file path to custom error page served when nghttpx
1392 originally generates HTTP error status code <CODE>.
1393 <CODE> must be greater than or equal to 400, and at most
1394 599. If "\*" is used instead of <CODE>, it matches all
1395 HTTP status code. If error status code comes from
1396 backend server, the custom error pages are not used.
1398 .. option:: --server-name=<NAME>
1400 Change server response header field value to <NAME>.
1402 Default: ``nghttpx``
1404 .. option:: --no-server-rewrite
1406 Don't rewrite server header field in default mode. When
1407 :option:`--http2-proxy` is used, these headers will not be altered
1408 regardless of this option.
1410 .. option:: --redirect-https-port=<PORT>
1412 Specify the port number which appears in Location header
1413 field when redirect to HTTPS URI is made due to
1414 "redirect-if-not-tls" parameter in :option:`--backend` option.
1422 .. option:: --api-max-request-body=<SIZE>
1424 Set the maximum size of request body for API request.
1432 .. option:: --dns-cache-timeout=<DURATION>
1434 Set duration that cached DNS results remain valid. Note
1435 that nghttpx caches the unsuccessful results as well.
1439 .. option:: --dns-lookup-timeout=<DURATION>
1441 Set timeout that DNS server is given to respond to the
1442 initial DNS query. For the 2nd and later queries,
1443 server is given time based on this timeout, and it is
1448 .. option:: --dns-max-try=<N>
1450 Set the number of DNS query before nghttpx gives up name
1455 .. option:: --frontend-max-requests=<N>
1457 The number of requests that single frontend connection
1458 can process. For HTTP/2, this is the number of streams
1459 in one HTTP/2 connection. For HTTP/1, this is the
1460 number of keep alive requests. This is hint to nghttpx,
1461 and it may allow additional few requests. The default
1468 .. option:: --frontend-http2-dump-request-header=<PATH>
1470 Dumps request headers received by HTTP/2 frontend to the
1471 file denoted in <PATH>. The output is done in HTTP/1
1472 header field format and each header block is followed by
1473 an empty line. This option is not thread safe and MUST
1474 NOT be used with option :option:`-n`\<N>, where <N> >= 2.
1476 .. option:: --frontend-http2-dump-response-header=<PATH>
1478 Dumps response headers sent from HTTP/2 frontend to the
1479 file denoted in <PATH>. The output is done in HTTP/1
1480 header field format and each header block is followed by
1481 an empty line. This option is not thread safe and MUST
1482 NOT be used with option :option:`-n`\<N>, where <N> >= 2.
1484 .. option:: -o, --frontend-frame-debug
1486 Print HTTP/2 frames in frontend to stderr. This option
1487 is not thread safe and MUST NOT be used with option
1488 :option:`-n`\=N, where N >= 2.
1494 .. option:: -D, --daemon
1496 Run in a background. If :option:`-D` is used, the current working
1497 directory is changed to '*/*'.
1499 .. option:: --pid-file=<PATH>
1501 Set path to save PID of this program.
1503 .. option:: --user=<USER>
1505 Run this program as <USER>. This option is intended to
1506 be used to drop root privileges.
1508 .. option:: --single-process
1510 Run this program in a single process mode for debugging
1511 purpose. Without this option, nghttpx creates at least
1512 2 processes: master and worker processes. If this
1513 option is used, master and worker are unified into a
1514 single process. nghttpx still spawns additional process
1515 if neverbleed is used. In the single process mode, the
1516 signal handling feature is disabled.
1522 .. option:: --mruby-file=<PATH>
1524 Set mruby script file
1526 .. option:: --ignore-per-pattern-mruby-error
1528 Ignore mruby compile error for per-pattern mruby script
1529 file. If error occurred, it is treated as if no mruby
1530 file were specified for the pattern.
1536 .. option:: --conf=<PATH>
1538 Load configuration from <PATH>. Please note that
1539 nghttpx always tries to read the default configuration
1540 file if :option:`--conf` is not given.
1542 Default: ``/etc/nghttpx/nghttpx.conf``
1544 .. option:: --include=<PATH>
1546 Load additional configurations from <PATH>. File <PATH>
1547 is read when configuration parser encountered this
1548 option. This option can be used multiple times, or even
1551 .. option:: -v, --version
1553 Print version and exit.
1555 .. option:: -h, --help
1557 Print this help and exit.
1561 The <SIZE> argument is an integer and an optional unit (e.g., 10K is
1562 10 * 1024). Units are K, M and G (powers of 1024).
1564 The <DURATION> argument is an integer and an optional unit (e.g., 1s
1565 is 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
1566 (hours, minutes, seconds and milliseconds, respectively). If a unit
1567 is omitted, a second is used as unit.
1572 */etc/nghttpx/nghttpx.conf*
1573 The default configuration file path nghttpx searches at startup.
1574 The configuration file path can be changed using :option:`--conf`
1577 Those lines which are staring ``#`` are treated as comment.
1579 The option name in the configuration file is the long command-line
1580 option name with leading ``--`` stripped (e.g., ``frontend``). Put
1581 ``=`` between option name and value. Don't put extra leading or
1584 When specifying arguments including characters which have special
1585 meaning to a shell, we usually use quotes so that shell does not
1586 interpret them. When writing this configuration file, quotes for
1587 this purpose must not be used. For example, specify additional
1588 request header field, do this:
1590 .. code-block:: text
1592 add-request-header=foo: bar
1596 .. code-block:: text
1598 add-request-header="foo: bar"
1600 The options which do not take argument in the command-line *take*
1601 argument in the configuration file. Specify ``yes`` as an argument
1602 (e.g., ``http2-proxy=yes``). If other string is given, it is
1605 To specify private key and certificate file which are given as
1606 positional arguments in command-line, use ``private-key-file`` and
1607 ``certificate-file``.
1609 :option:`--conf` option cannot be used in the configuration file and
1610 will be ignored if specified.
1613 Error log is written to stderr by default. It can be configured
1614 using :option:`--errorlog-file`. The format of log message is as
1617 <datetime> <master-pid> <current-pid> <thread-id> <level> (<filename>:<line>) <msg>
1620 It is a combination of date and time when the log is written. It
1621 is in ISO 8601 format.
1624 It is a master process ID.
1627 It is a process ID which writes this log.
1630 It is a thread ID which writes this log. It would be unique
1631 within <current-pid>.
1633 <filename> and <line>
1634 They are source file name, and line number which produce this log.
1637 It is a log message body.
1643 Shutdown gracefully. First accept pending connections and stop
1644 accepting connection. After all connections are handled, nghttpx
1648 Reload configuration file given in :option:`--conf`.
1655 Fork and execute nghttpx. It will execute the binary in the same
1656 path with same command-line arguments and environment variables. As
1657 of nghttpx version 1.20.0, the new master process sends SIGQUIT to
1658 the original master process when it is ready to serve requests. For
1659 the earlier versions of nghttpx, user has to send SIGQUIT to the
1660 original master process.
1662 The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
1663 is usually used to execute new binary, and the master process is
1664 newly spawned. On the other hand, the latter just reloads
1665 configuration file, and the same master process continues to exist.
1669 nghttpx consists of multiple processes: one process for processing
1670 these signals, and another one for processing requests. The former
1671 spawns the latter. The former is called master process, and the
1672 latter is called worker process. If neverbleed is enabled, the
1673 worker process spawns neverbleed daemon process which does RSA key
1674 processing. The above signal must be sent to the master process.
1675 If the other processes received one of them, it is ignored. This
1676 behaviour of these processes may change in the future release. In
1677 other words, in the future release, the processes other than master
1678 process may terminate upon the reception of these signals.
1679 Therefore these signals should not be sent to the processes other
1680 than master process.
1685 nghttpx supports HTTP/2 server push in default mode with Link header
1686 field. nghttpx looks for Link header field (`RFC 5988
1687 <http://tools.ietf.org/html/rfc5988>`_) in response headers from
1688 backend server and extracts URI-reference with parameter
1689 ``rel=preload`` (see `preload
1690 <http://w3c.github.io/preload/#interoperability-with-http-link-header>`_)
1691 and pushes those URIs to the frontend client. Here is a sample Link
1692 header field to initiate server push:
1694 .. code-block:: text
1696 Link: </fonts/font.woff>; rel=preload
1697 Link: </css/theme.css>; rel=preload
1699 Currently, the following restriction is applied for server push:
1701 1. The associated stream must have method "GET" or "POST". The
1702 associated stream's status code must be 200.
1704 This limitation may be loosened in the future release.
1706 nghttpx also supports server push if both frontend and backend are
1707 HTTP/2 in default mode. In this case, in addition to server push via
1708 Link header field, server push from backend is forwarded to frontend
1711 HTTP/2 server push will be disabled if :option:`--http2-proxy` is
1717 nghttpx supports UNIX domain socket with a filename for both frontend
1718 and backend connections.
1720 Please note that current nghttpx implementation does not delete a
1721 socket with a filename. And on start up, if nghttpx detects that the
1722 specified socket already exists in the file system, nghttpx first
1723 deletes it. However, if SIGUSR2 is used to execute new binary and
1724 both old and new configurations use same filename, new binary does not
1725 delete the socket and continues to use it.
1730 OCSP query is done using external Python script
1731 ``fetch-ocsp-response``, which has been originally developed in Perl
1732 as part of h2o project (https://github.com/h2o/h2o), and was
1733 translated into Python.
1735 The script file is usually installed under
1736 ``$(prefix)/share/nghttp2/`` directory. The actual path to script can
1737 be customized using :option:`--fetch-ocsp-response-file` option.
1739 If OCSP query is failed, previous OCSP response, if any, is continued
1742 :option:`--fetch-ocsp-response-file` option provides wide range of
1743 possibility to manage OCSP response. It can take an arbitrary script
1744 or executable. The requirement is that it supports the command-line
1745 interface of ``fetch-ocsp-response`` script, and it must return a
1746 valid DER encoded OCSP response on success. It must return exit code
1747 0 on success, and 75 for temporary error, and the other error code for
1748 generic failure. For large cluster of servers, it is not efficient
1749 for each server to perform OCSP query using ``fetch-ocsp-response``.
1750 Instead, you can retrieve OCSP response in some way, and store it in a
1751 disk or a shared database. Then specify a program in
1752 :option:`--fetch-ocsp-response-file` to fetch it from those stores.
1753 This could provide a way to share the OCSP response between fleet of
1754 servers, and also any OCSP query strategy can be applied which may be
1755 beyond the ability of nghttpx itself or ``fetch-ocsp-response``
1758 TLS SESSION RESUMPTION
1759 ----------------------
1761 nghttpx supports TLS session resumption through both session ID and
1764 SESSION ID RESUMPTION
1765 ~~~~~~~~~~~~~~~~~~~~~
1767 By default, session ID is shared by all worker threads.
1769 If :option:`--tls-session-cache-memcached` is given, nghttpx will
1770 insert serialized session data to memcached with
1771 ``nghttpx:tls-session-cache:`` + lowercase hex string of session ID
1772 as a memcached entry key, with expiry time 12 hours. Session timeout
1775 By default, connections to memcached server are not encrypted. To
1776 enable encryption, use ``tls`` keyword in
1777 :option:`--tls-session-cache-memcached` option.
1779 TLS SESSION TICKET RESUMPTION
1780 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1782 By default, session ticket is shared by all worker threads. The
1783 automatic key rotation is also enabled by default. Every an hour, new
1784 encryption key is generated, and previous encryption key becomes
1785 decryption only key. We set session timeout to 12 hours, and thus we
1786 keep at most 12 keys.
1788 If :option:`--tls-ticket-key-memcached` is given, encryption keys are
1789 retrieved from memcached. nghttpx just reads keys from memcached; one
1790 has to deploy key generator program to update keys frequently (e.g.,
1791 every 1 hour). The example key generator tlsticketupdate.go is
1792 available under contrib directory in nghttp2 archive. The memcached
1793 entry key is ``nghttpx:tls-ticket-key``. The data format stored in
1794 memcached is the binary format described below:
1796 .. code-block:: text
1798 +--------------+-------+----------------+
1799 | VERSION (4) |LEN (2)|KEY(48 or 80) ...
1800 +--------------+-------+----------------+
1803 +------------------------+
1804 (LEN, KEY) pair can be repeated
1806 All numbers in the above figure is bytes. All integer fields are
1809 First 4 bytes integer VERSION field, which must be 1. The 2 bytes
1810 integer LEN field gives the length of following KEY field, which
1811 contains key. If :option:`--tls-ticket-key-cipher`\=aes-128-cbc is
1812 used, LEN must be 48. If
1813 :option:`--tls-ticket-key-cipher`\=aes-256-cbc is used, LEN must be
1814 80. LEN and KEY pair can be repeated multiple times to store multiple
1815 keys. The key appeared first is used as encryption key. All the
1816 remaining keys are used as decryption only.
1818 By default, connections to memcached server are not encrypted. To
1819 enable encryption, use ``tls`` keyword in
1820 :option:`--tls-ticket-key-memcached` option.
1822 If :option:`--tls-ticket-key-file` is given, encryption key is read
1823 from the given file. In this case, nghttpx does not rotate key
1824 automatically. To rotate key, one has to restart nghttpx (see
1827 CERTIFICATE TRANSPARENCY
1828 ------------------------
1830 nghttpx supports TLS ``signed_certificate_timestamp`` extension (`RFC
1831 6962 <https://tools.ietf.org/html/rfc6962>`_). The relevant options
1832 are :option:`--tls-sct-dir` and ``sct-dir`` parameter in
1833 :option:`--subcert`. They takes a directory, and nghttpx reads all
1834 files whose extension is ``.sct`` under the directory. The ``*.sct``
1835 files are encoded as ``SignedCertificateTimestamp`` struct described
1836 in `section 3.2 of RFC 69662
1837 <https://tools.ietf.org/html/rfc6962#section-3.2>`_. This format is
1838 the same one used by `nginx-ct
1839 <https://github.com/grahamedgecombe/nginx-ct>`_ and `mod_ssl_ct
1840 <https://httpd.apache.org/docs/trunk/mod/mod_ssl_ct.html>`_.
1841 `ct-submit <https://github.com/grahamedgecombe/ct-submit>`_ can be
1842 used to submit certificates to log servers, and obtain the
1843 ``SignedCertificateTimestamp`` struct which can be used with nghttpx.
1850 The current mruby extension API is experimental and not frozen. The
1851 API is subject to change in the future release.
1855 Almost all string value returned from method, or attribute is a
1856 fresh new mruby string, which involves memory allocation, and
1857 copies. Therefore, it is strongly recommended to store a return
1858 value in a local variable, and use it, instead of calling method or
1859 accessing attribute repeatedly.
1861 nghttpx allows users to extend its capability using mruby scripts.
1862 nghttpx has 2 hook points to execute mruby script: request phase and
1863 response phase. The request phase hook is invoked after all request
1864 header fields are received from client. The response phase hook is
1865 invoked after all response header fields are received from backend
1866 server. These hooks allows users to modify header fields, or common
1867 HTTP variables, like authority or request path, and even return custom
1868 response without forwarding request to backend servers.
1870 There are 2 levels of mruby script invocations: global and
1871 per-pattern. The global mruby script is set by :option:`--mruby-file`
1872 option and is called for all requests. The per-pattern mruby script
1873 is set by "mruby" parameter in :option:`-b` option. It is invoked for
1874 a request which matches the particular pattern. The order of hook
1875 invocation is: global request phase hook, per-pattern request phase
1876 hook, per-pattern response phase hook, and finally global response
1877 phase hook. If a hook returns a response, any later hooks are not
1878 invoked. The global request hook is invoked before the pattern
1879 matching is made and changing request path may affect the pattern
1882 Please note that request and response hooks of per-pattern mruby
1883 script for a single request might not come from the same script. This
1884 might happen after a request hook is executed, backend failed for some
1885 reason, and at the same time, backend configuration is replaced by API
1886 request, and then the request uses new configuration on retry. The
1887 response hook from new configuration, if it is specified, will be
1890 The all mruby script will be evaluated once per thread on startup, and
1891 it must instantiate object and evaluate it as the return value (e.g.,
1892 ``App.new``). This object is called app object. If app object
1893 defines ``on_req`` method, it is called with :rb:class:`Nghttpx::Env`
1894 object on request hook. Similarly, if app object defines ``on_resp``
1895 method, it is called with :rb:class:`Nghttpx::Env` object on response
1896 hook. For each method invocation, user can can access
1897 :rb:class:`Nghttpx::Request` and :rb:class:`Nghttpx::Response` objects
1898 via :rb:attr:`Nghttpx::Env#req` and :rb:attr:`Nghttpx::Env#resp`
1901 .. rb:module:: Nghttpx
1903 .. rb:const:: REQUEST_PHASE
1905 Constant to represent request phase.
1907 .. rb:const:: RESPONSE_PHASE
1909 Constant to represent response phase.
1913 Object to represent current request specific context.
1915 .. rb:attr_reader:: req
1917 Return :rb:class:`Request` object.
1919 .. rb:attr_reader:: resp
1921 Return :rb:class:`Response` object.
1923 .. rb:attr_reader:: ctx
1925 Return Ruby hash object. It persists until request finishes.
1926 So values set in request phase hook can be retrieved in
1927 response phase hook.
1929 .. rb:attr_reader:: phase
1931 Return the current phase.
1933 .. rb:attr_reader:: remote_addr
1935 Return IP address of a remote client. If connection is made
1936 via UNIX domain socket, this returns the string "localhost".
1938 .. rb:attr_reader:: server_addr
1940 Return address of server that accepted the connection. This
1941 is a string which specified in :option:`--frontend` option,
1942 excluding port number, and not a resolved IP address. For
1943 UNIX domain socket, this is a path to UNIX domain socket.
1945 .. rb:attr_reader:: server_port
1947 Return port number of the server frontend which accepted the
1948 connection from client.
1950 .. rb:attr_reader:: tls_used
1952 Return true if TLS is used on the connection.
1954 .. rb:attr_reader:: tls_sni
1956 Return the TLS SNI value which client sent in this connection.
1958 .. rb:attr_reader:: tls_client_fingerprint_sha256
1960 Return the SHA-256 fingerprint of a client certificate.
1962 .. rb:attr_reader:: tls_client_fingerprint_sha1
1964 Return the SHA-1 fingerprint of a client certificate.
1966 .. rb:attr_reader:: tls_client_issuer_name
1968 Return the issuer name of a client certificate.
1970 .. rb:attr_reader:: tls_client_subject_name
1972 Return the subject name of a client certificate.
1974 .. rb:attr_reader:: tls_client_serial
1976 Return the serial number of a client certificate.
1978 .. rb:attr_reader:: tls_client_not_before
1980 Return the start date of a client certificate in seconds since
1983 .. rb:attr_reader:: tls_client_not_after
1985 Return the end date of a client certificate in seconds since
1988 .. rb:attr_reader:: tls_cipher
1990 Return a TLS cipher negotiated in this connection.
1992 .. rb:attr_reader:: tls_protocol
1994 Return a TLS protocol version negotiated in this connection.
1996 .. rb:attr_reader:: tls_session_id
1998 Return a session ID for this connection in hex string.
2000 .. rb:attr_reader:: tls_session_reused
2002 Return true if, and only if a SSL/TLS session is reused.
2004 .. rb:attr_reader:: alpn
2006 Return ALPN identifier negotiated in this connection.
2008 .. rb:attr_reader:: tls_handshake_finished
2010 Return true if SSL/TLS handshake has finished. If it returns
2011 false in the request phase hook, the request is received in
2012 TLSv1.3 early data (0-RTT) and might be vulnerable to the
2013 replay attack. nghttpx will send Early-Data header field to
2014 backend servers to indicate this.
2016 .. rb:class:: Request
2018 Object to represent request from client. The modification to
2019 Request object is allowed only in request phase hook.
2021 .. rb:attr_reader:: http_version_major
2023 Return HTTP major version.
2025 .. rb:attr_reader:: http_version_minor
2027 Return HTTP minor version.
2029 .. rb:attr_accessor:: method
2031 HTTP method. On assignment, copy of given value is assigned.
2032 We don't accept arbitrary method name. We will document them
2033 later, but well known methods, like GET, PUT and POST, are all
2036 .. rb:attr_accessor:: authority
2038 Authority (i.e., example.org), including optional port
2039 component . On assignment, copy of given value is assigned.
2041 .. rb:attr_accessor:: scheme
2043 Scheme (i.e., http, https). On assignment, copy of given
2046 .. rb:attr_accessor:: path
2048 Request path, including query component (i.e., /index.html).
2049 On assignment, copy of given value is assigned. The path does
2050 not include authority component of URI. This may include
2051 query component. nghttpx makes certain normalization for
2052 path. It decodes percent-encoding for unreserved characters
2053 (see https://tools.ietf.org/html/rfc3986#section-2.3), and
2054 resolves ".." and ".". But it may leave characters which
2055 should be percent-encoded as is. So be careful when comparing
2056 path against desired string.
2058 .. rb:attr_reader:: headers
2060 Return Ruby hash containing copy of request header fields.
2061 Changing values in returned hash does not change request
2062 header fields actually used in request processing. Use
2063 :rb:meth:`Nghttpx::Request#add_header` or
2064 :rb:meth:`Nghttpx::Request#set_header` to change request
2067 .. rb:method:: add_header(key, value)
2069 Add header entry associated with key. The value can be single
2070 string or array of string. It does not replace any existing
2071 values associated with key.
2073 .. rb:method:: set_header(key, value)
2075 Set header entry associated with key. The value can be single
2076 string or array of string. It replaces any existing values
2077 associated with key.
2079 .. rb:method:: clear_headers
2081 Clear all existing request header fields.
2083 .. rb:method:: push(uri)
2085 Initiate to push resource identified by *uri*. Only HTTP/2
2086 protocol supports this feature. For the other protocols, this
2087 method is noop. *uri* can be absolute URI, absolute path or
2088 relative path to the current request. For absolute or
2089 relative path, scheme and authority are inherited from the
2090 current request. Currently, method is always GET. nghttpx
2091 will issue request to backend servers to fulfill this request.
2092 The request and response phase hooks will be called for pushed
2095 .. rb:class:: Response
2097 Object to represent response from backend server.
2099 .. rb:attr_reader:: http_version_major
2101 Return HTTP major version.
2103 .. rb:attr_reader:: http_version_minor
2105 Return HTTP minor version.
2107 .. rb:attr_accessor:: status
2109 HTTP status code. It must be in the range [200, 999],
2110 inclusive. The non-final status code is not supported in
2111 mruby scripting at the moment.
2113 .. rb:attr_reader:: headers
2115 Return Ruby hash containing copy of response header fields.
2116 Changing values in returned hash does not change response
2117 header fields actually used in response processing. Use
2118 :rb:meth:`Nghttpx::Response#add_header` or
2119 :rb:meth:`Nghttpx::Response#set_header` to change response
2122 .. rb:method:: add_header(key, value)
2124 Add header entry associated with key. The value can be single
2125 string or array of string. It does not replace any existing
2126 values associated with key.
2128 .. rb:method:: set_header(key, value)
2130 Set header entry associated with key. The value can be single
2131 string or array of string. It replaces any existing values
2132 associated with key.
2134 .. rb:method:: clear_headers
2136 Clear all existing response header fields.
2138 .. rb:method:: return(body)
2140 Return custom response *body* to a client. When this method
2141 is called in request phase hook, the request is not forwarded
2142 to the backend, and response phase hook for this request will
2143 not be invoked. When this method is called in response phase
2144 hook, response from backend server is canceled and discarded.
2145 The status code and response header fields should be set
2146 before using this method. To set status code, use
2147 :rb:attr:`Nghttpx::Response#status`. If status code is not
2148 set, 200 is used. To set response header fields,
2149 :rb:meth:`Nghttpx::Response#add_header` and
2150 :rb:meth:`Nghttpx::Response#set_header`. When this method is
2151 invoked in response phase hook, the response headers are
2152 filled with the ones received from backend server. To send
2153 completely custom header fields, first call
2154 :rb:meth:`Nghttpx::Response#clear_headers` to erase all
2155 existing header fields, and then add required header fields.
2156 It is an error to call this method twice for a given request.
2158 .. rb:method:: send_info(status, headers)
2160 Send non-final (informational) response to a client. *status*
2161 must be in the range [100, 199], inclusive. *headers* is a
2162 hash containing response header fields. Its key must be a
2163 string, and the associated value must be either string or
2164 array of strings. Since this is not a final response, even if
2165 this method is invoked, request is still forwarded to a
2166 backend unless :rb:meth:`Nghttpx::Response#return` is called.
2167 This method can be called multiple times. It cannot be called
2168 after :rb:meth:`Nghttpx::Response#return` is called.
2173 Modify request path:
2175 .. code-block:: ruby
2179 env.req.path = "/apps#{env.req.path}"
2185 Don't forget to instantiate and evaluate object at the last line.
2187 Restrict permission of viewing a content to a specific client
2190 .. code-block:: ruby
2194 allowed_clients = ["127.0.0.1", "::1"]
2196 if env.req.path.start_with?("/log/") &&
2197 !allowed_clients.include?(env.remote_addr) then
2198 env.resp.status = 404
2199 env.resp.return "permission denied"
2209 nghttpx exposes API endpoints to manipulate it via HTTP based API. By
2210 default, API endpoint is disabled. To enable it, add a dedicated
2211 frontend for API using :option:`--frontend` option with "api"
2212 parameter. All requests which come from this frontend address, will
2213 be treated as API request.
2215 The response is normally JSON dictionary, and at least includes the
2219 The status of the request processing. The following values are
2223 The request was successful.
2226 The request was failed. No change has been made.
2231 Additionally, depending on the API endpoint, ``data`` key may be
2232 present, and its value contains the API endpoint specific data.
2234 We wrote "normally", since nghttpx may return ordinal HTML response in
2235 some cases where the error has occurred before reaching API endpoint
2236 (e.g., header field is too large).
2238 The following section describes available API endpoints.
2240 POST /api/v1beta1/backendconfig
2241 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2243 This API replaces the current backend server settings with the
2244 requested ones. The request method should be POST, but PUT is also
2245 acceptable. The request body must be nghttpx configuration file
2246 format. For configuration file format, see `FILES`_ section. The
2247 line separator inside the request body must be single LF (0x0A).
2248 Currently, only :option:`backend <--backend>` option is parsed, the
2249 others are simply ignored. The semantics of this API is replace the
2250 current backend with the backend options in request body. Describe
2251 the desired set of backend severs, and nghttpx makes it happen. If
2252 there is no :option:`backend <--backend>` option is found in request
2253 body, the current set of backend is replaced with the :option:`backend
2254 <--backend>` option's default value, which is ``127.0.0.1,80``.
2256 The replacement is done instantly without breaking existing
2257 connections or requests. It also avoids any process creation as is
2258 the case with hot swapping with signals.
2260 The one limitation is that only numeric IP address is allowed in
2261 :option:`backend <--backend>` in request body unless "dns" parameter
2262 is used while non numeric hostname is allowed in command-line or
2263 configuration file is read using :option:`--conf`.
2265 GET /api/v1beta1/configrevision
2266 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2268 This API returns configuration revision of the current nghttpx. The
2269 configuration revision is opaque string, and it changes after each
2270 reloading by SIGHUP. With this API, an external application knows
2271 that whether nghttpx has finished reloading its configuration by
2272 comparing the configuration revisions between before and after
2273 reloading. It is recommended to disable persistent (keep-alive)
2274 connection for this purpose in order to avoid to send a request using
2275 the reused connection which may bound to an old process.
2277 This API returns response including ``data`` key. Its value is JSON
2278 object, and it contains at least the following key:
2281 The configuration revision of the current nghttpx
2287 :manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`h2load(1)`