diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/nghttpx.1 | 2770 | ||||
| -rw-r--r-- | doc/nghttpx.1.rst | 2526 |
2 files changed, 5296 insertions, 0 deletions
diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 new file mode 100644 index 0000000..e9742a5 --- /dev/null +++ b/doc/nghttpx.1 @@ -0,0 +1,2770 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "NGHTTPX" "1" "Jan 21, 2024" "1.59.0" "nghttp2" +.SH NAME +nghttpx \- HTTP/2 proxy +.SH SYNOPSIS +.sp +\fBnghttpx\fP [OPTIONS]... [<PRIVATE_KEY> <CERT>] +.SH DESCRIPTION +.sp +A reverse proxy for HTTP/3, HTTP/2, and HTTP/1. +.INDENT 0.0 +.TP +.B <PRIVATE_KEY> +Set path to server\(aqs private key. Required unless +\(dqno\-tls\(dq parameter is used in \fI\%\-\-frontend\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B <CERT> +Set path to server\(aqs certificate. Required unless +\(dqno\-tls\(dq parameter is used in \fI\%\-\-frontend\fP option. To +make OCSP stapling work, this must be an absolute path. +.UNINDENT +.SH OPTIONS +.sp +The options are categorized into several groups. +.SS Connections +.INDENT 0.0 +.TP +.B \-b, \-\-backend=(<HOST>,<PORT>|unix:<PATH>)[;[<PATTERN>[:...]][[;<PARAM>]...] +Set backend host and port. The multiple backend +addresses are accepted by repeating this option. UNIX +domain socket can be specified by prefixing path name +with \(dqunix:\(dq (e.g., unix:/var/run/backend.sock). +.sp +Optionally, if <PATTERN>s are given, the backend address +is only used if request matches the pattern. The +pattern matching is closely designed to ServeMux in +net/http package of Go programming language. <PATTERN> +consists of path, host + path or just host. The path +must start with \(dq\fI/\fP\(dq. If it ends with \(dq\fI/\fP\(dq, it matches +all request path in its subtree. To deal with the +request to the directory without trailing slash, the +path which ends with \(dq\fI/\fP\(dq also matches the request path +which only lacks trailing \(aq\fI/\fP\(aq (e.g., path \(dq\fI/foo/\fP\(dq +matches request path \(dq\fI/foo\fP\(dq). If it does not end with +\(dq\fI/\fP\(dq, it performs exact match against the request path. +If host is given, it performs a match against the +request host. For a request received on the frontend +listener with \(dqsni\-fwd\(dq parameter enabled, SNI host is +used instead of a request host. If host alone is given, +\(dq\fI/\fP\(dq is appended to it, so that it matches all request +paths under the host (e.g., specifying \(dqnghttp2.org\(dq +equals to \(dqnghttp2.org/\(dq). CONNECT method is treated +specially. It does not have path, and we don\(aqt allow +empty path. To workaround this, we assume that CONNECT +method has \(dq\fI/\fP\(dq as path. +.sp +Patterns with host take precedence over patterns with +just path. Then, longer patterns take precedence over +shorter ones. +.sp +Host can include \(dq*\(dq in the left most position to +indicate wildcard match (only suffix match is done). +The \(dq*\(dq must match at least one character. For example, +host pattern \(dq*.nghttp2.org\(dq matches against +\(dqwww.nghttp2.org\(dq and \(dqgit.ngttp2.org\(dq, but does not +match against \(dqnghttp2.org\(dq. The exact hosts match +takes precedence over the wildcard hosts match. +.sp +If path part ends with \(dq*\(dq, it is treated as wildcard +path. The wildcard path behaves differently from the +normal path. For normal path, match is made around the +boundary of path component separator,\(dq\fI/\fP\(dq. On the other +hand, the wildcard path does not take into account the +path component separator. All paths which include the +wildcard path without last \(dq*\(dq as prefix, and are +strictly longer than wildcard path without last \(dq*\(dq are +matched. \(dq*\(dq must match at least one character. For +example, the pattern \(dq\fI/foo*\fP\(dq matches \(dq\fI/foo/\fP\(dq and +\(dq\fI/foobar\fP\(dq. But it does not match \(dq\fI/foo\fP\(dq, or \(dq\fI/fo\fP\(dq. +.sp +If <PATTERN> is omitted or empty string, \(dq\fI/\fP\(dq is used as +pattern, which matches all request paths (catch\-all +pattern). The catch\-all backend must be given. +.sp +When doing a match, nghttpx made some normalization to +pattern, request host and path. For host part, they are +converted to lower case. For path part, percent\-encoded +unreserved characters defined in RFC 3986 are decoded, +and any dot\-segments (\(dq..\(dq and \(dq.\(dq) are resolved and +removed. +.sp +For example, \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org/httpbin/\(aq +matches the request host \(dqnghttp2.org\(dq and the request +path \(dq\fI/httpbin/get\fP\(dq, but does not match the request host +\(dqnghttp2.org\(dq and the request path \(dq\fI/index.html\fP\(dq. +.sp +The multiple <PATTERN>s can be specified, delimiting +them by \(dq:\(dq. Specifying +\fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org:www.nghttp2.org\(aq has the +same effect to specify \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org\(aq +and \fI\%\-b\fP\(aq127.0.0.1,8080;www.nghttp2.org\(aq. +.sp +The backend addresses sharing same <PATTERN> are grouped +together forming load balancing group. +.sp +Several parameters <PARAM> are accepted after <PATTERN>. +The parameters are delimited by \(dq;\(dq. The available +parameters are: \(dqproto=<PROTO>\(dq, \(dqtls\(dq, +\(dqsni=<SNI_HOST>\(dq, \(dqfall=<N>\(dq, \(dqrise=<N>\(dq, +\(dqaffinity=<METHOD>\(dq, \(dqdns\(dq, \(dqredirect\-if\-not\-tls\(dq, +\(dqupgrade\-scheme\(dq, \(dqmruby=<PATH>\(dq, +\(dqread\-timeout=<DURATION>\(dq, \(dqwrite\-timeout=<DURATION>\(dq, +\(dqgroup=<GROUP>\(dq, \(dqgroup\-weight=<N>\(dq, \(dqweight=<N>\(dq, and +\(dqdnf\(dq. The parameter consists of keyword, and +optionally followed by \(dq=\(dq and value. For example, the +parameter \(dqproto=h2\(dq consists of the keyword \(dqproto\(dq and +value \(dqh2\(dq. The parameter \(dqtls\(dq consists of the keyword +\(dqtls\(dq without value. Each parameter is described as +follows. +.sp +The backend application protocol can be specified using +optional \(dqproto\(dq parameter, and in the form of +\(dqproto=<PROTO>\(dq. <PROTO> should be one of the following +list without quotes: \(dqh2\(dq, \(dqhttp/1.1\(dq. The default +value of <PROTO> is \(dqhttp/1.1\(dq. Note that usually \(dqh2\(dq +refers to HTTP/2 over TLS. But in this option, it may +mean HTTP/2 over cleartext TCP unless \(dqtls\(dq keyword is +used (see below). +.sp +TLS can be enabled by specifying optional \(dqtls\(dq +parameter. TLS is not enabled by default. +.sp +With \(dqsni=<SNI_HOST>\(dq parameter, it can override the TLS +SNI field value with given <SNI_HOST>. This will +default to the backend <HOST> name +.sp +The feature to detect whether backend is online or +offline can be enabled using optional \(dqfall\(dq and \(dqrise\(dq +parameters. Using \(dqfall=<N>\(dq parameter, if nghttpx +cannot connect to a this backend <N> times in a row, +this backend is assumed to be offline, and it is +excluded from load balancing. If <N> is 0, this backend +never be excluded from load balancing whatever times +nghttpx cannot connect to it, and this is the default. +There is also \(dqrise=<N>\(dq parameter. After backend was +excluded from load balancing group, nghttpx periodically +attempts to make a connection to the failed backend, and +if the connection is made successfully <N> times in a +row, the backend is assumed to be online, and it is now +eligible for load balancing target. If <N> is 0, a +backend is permanently offline, once it goes in that +state, and this is the default behaviour. +.sp +The session affinity is enabled using +\(dqaffinity=<METHOD>\(dq parameter. If \(dqip\(dq is given in +<METHOD>, client IP based session affinity is enabled. +If \(dqcookie\(dq is given in <METHOD>, cookie based session +affinity is enabled. If \(dqnone\(dq is given in <METHOD>, +session affinity is disabled, and this is the default. +The session affinity is enabled per <PATTERN>. If at +least one backend has \(dqaffinity\(dq parameter, and its +<METHOD> is not \(dqnone\(dq, session affinity is enabled for +all backend servers sharing the same <PATTERN>. It is +advised to set \(dqaffinity\(dq parameter to all backend +explicitly if session affinity is desired. The session +affinity may break if one of the backend gets +unreachable, or backend settings are reloaded or +replaced by API. +.sp +If \(dqaffinity=cookie\(dq is used, the additional +configuration is required. +\(dqaffinity\-cookie\-name=<NAME>\(dq must be used to specify a +name of cookie to use. Optionally, +\(dqaffinity\-cookie\-path=<PATH>\(dq can be used to specify a +path which cookie is applied. The optional +\(dqaffinity\-cookie\-secure=<SECURE>\(dq controls the Secure +attribute of a cookie. The default value is \(dqauto\(dq, and +the Secure attribute is determined by a request scheme. +If a request scheme is \(dqhttps\(dq, then Secure attribute is +set. Otherwise, it is not set. If <SECURE> is \(dqyes\(dq, +the Secure attribute is always set. If <SECURE> is +\(dqno\(dq, the Secure attribute is always omitted. +\(dqaffinity\-cookie\-stickiness=<STICKINESS>\(dq controls +stickiness of this affinity. If <STICKINESS> is +\(dqloose\(dq, removing or adding a backend server might break +the affinity and the request might be forwarded to a +different backend server. If <STICKINESS> is \(dqstrict\(dq, +removing the designated backend server breaks affinity, +but adding new backend server does not cause breakage. +If the designated backend server becomes unavailable, +new backend server is chosen as if the request does not +have an affinity cookie. <STICKINESS> defaults to +\(dqloose\(dq. +.sp +By default, name resolution of backend host name is done +at start up, or reloading configuration. If \(dqdns\(dq +parameter is given, name resolution takes place +dynamically. This is useful if backend address changes +frequently. If \(dqdns\(dq is given, name resolution of +backend host name at start up, or reloading +configuration is skipped. +.sp +If \(dqredirect\-if\-not\-tls\(dq parameter is used, the matched +backend requires that frontend connection is TLS +encrypted. If it isn\(aqt, nghttpx responds to the request +with 308 status code, and https URI the client should +use instead is included in Location header field. The +port number in redirect URI is 443 by default, and can +be changed using \fI\%\-\-redirect\-https\-port\fP option. If at +least one backend has \(dqredirect\-if\-not\-tls\(dq parameter, +this feature is enabled for all backend servers sharing +the same <PATTERN>. It is advised to set +\(dqredirect\-if\-no\-tls\(dq parameter to all backends +explicitly if this feature is desired. +.sp +If \(dqupgrade\-scheme\(dq parameter is used along with \(dqtls\(dq +parameter, HTTP/2 :scheme pseudo header field is changed +to \(dqhttps\(dq from \(dqhttp\(dq when forwarding a request to this +particular backend. This is a workaround for a backend +server which requires \(dqhttps\(dq :scheme pseudo header +field on TLS encrypted connection. +.sp +\(dqmruby=<PATH>\(dq parameter specifies a path to mruby +script file which is invoked when this pattern is +matched. All backends which share the same pattern must +have the same mruby path. +.sp +\(dqread\-timeout=<DURATION>\(dq and \(dqwrite\-timeout=<DURATION>\(dq +parameters specify the read and write timeout of the +backend connection when this pattern is matched. All +backends which share the same pattern must have the same +timeouts. If these timeouts are entirely omitted for a +pattern, \fI\%\-\-backend\-read\-timeout\fP and +\fI\%\-\-backend\-write\-timeout\fP are used. +.sp +\(dqgroup=<GROUP>\(dq parameter specifies the name of group +this backend address belongs to. By default, it belongs +to the unnamed default group. The name of group is +unique per pattern. \(dqgroup\-weight=<N>\(dq parameter +specifies the weight of the group. The higher weight +gets more frequently selected by the load balancing +algorithm. <N> must be [1, 256] inclusive. The weight +8 has 4 times more weight than 2. <N> must be the same +for all addresses which share the same <GROUP>. If +\(dqgroup\-weight\(dq is omitted in an address, but the other +address which belongs to the same group specifies +\(dqgroup\-weight\(dq, its weight is used. If no +\(dqgroup\-weight\(dq is specified for all addresses, the +weight of a group becomes 1. \(dqgroup\(dq and \(dqgroup\-weight\(dq +are ignored if session affinity is enabled. +.sp +\(dqweight=<N>\(dq parameter specifies the weight of the +backend address inside a group which this address +belongs to. The higher weight gets more frequently +selected by the load balancing algorithm. <N> must be +[1, 256] inclusive. The weight 8 has 4 times more +weight than weight 2. If this parameter is omitted, +weight becomes 1. \(dqweight\(dq is ignored if session +affinity is enabled. +.sp +If \(dqdnf\(dq parameter is specified, an incoming request is +not forwarded to a backend and just consumed along with +the request body (actually a backend server never be +contacted). It is expected that the HTTP response is +generated by mruby script (see \(dqmruby=<PATH>\(dq parameter +above). \(dqdnf\(dq is an abbreviation of \(dqdo not forward\(dq. +.sp +Since \(dq;\(dq and \(dq:\(dq are used as delimiter, <PATTERN> must +not contain these characters. In order to include \(dq:\(dq +in <PATTERN>, one has to specify \(dq%3A\(dq (which is +percent\-encoded from of \(dq:\(dq) instead. Since \(dq;\(dq has +special meaning in shell, the option value must be +quoted. +.sp +Default: \fB127.0.0.1,80\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-f, \-\-frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...] +Set frontend host and port. If <HOST> is \(aq*\(aq, it +assumes all addresses including both IPv4 and IPv6. +UNIX domain socket can be specified by prefixing path +name with \(dqunix:\(dq (e.g., unix:/var/run/nghttpx.sock). +This option can be used multiple times to listen to +multiple addresses. +.sp +This option can take 0 or more parameters, which are +described below. Note that \(dqapi\(dq and \(dqhealthmon\(dq +parameters are mutually exclusive. +.sp +Optionally, TLS can be disabled by specifying \(dqno\-tls\(dq +parameter. TLS is enabled by default. +.sp +If \(dqsni\-fwd\(dq parameter is used, when performing a match +to select a backend server, SNI host name received from +the client is used instead of the request host. See +\fI\%\-\-backend\fP option about the pattern match. +.sp +To make this frontend as API endpoint, specify \(dqapi\(dq +parameter. This is disabled by default. It is +important to limit the access to the API frontend. +Otherwise, someone may change the backend server, and +break your services, or expose confidential information +to the outside the world. +.sp +To make this frontend as health monitor endpoint, +specify \(dqhealthmon\(dq parameter. This is disabled by +default. Any requests which come through this address +are replied with 200 HTTP status, without no body. +.sp +To accept PROXY protocol version 1 and 2 on frontend +connection, specify \(dqproxyproto\(dq parameter. This is +disabled by default. +.sp +To receive HTTP/3 (QUIC) traffic, specify \(dqquic\(dq +parameter. It makes nghttpx listen on UDP port rather +than TCP port. UNIX domain socket, \(dqapi\(dq, and +\(dqhealthmon\(dq parameters cannot be used with \(dqquic\(dq +parameter. +.sp +Default: \fB*,3000\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backlog=<N> +Set listen backlog size. +.sp +Default: \fB65536\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-address\-family=(auto|IPv4|IPv6) +Specify address family of backend connections. If +\(dqauto\(dq is given, both IPv4 and IPv6 are considered. If +\(dqIPv4\(dq is given, only IPv4 address is considered. If +\(dqIPv6\(dq is given, only IPv6 address is considered. +.sp +Default: \fBauto\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-http\-proxy\-uri=<URI> +Specify proxy URI in the form +\fI\%http:/\fP/[<USER>:<PASS>@]<PROXY>:<PORT>. If a proxy +requires authentication, specify <USER> and <PASS>. +Note that they must be properly percent\-encoded. This +proxy is used when the backend connection is HTTP/2. +First, make a CONNECT request to the proxy and it +connects to the backend on behalf of nghttpx. This +forms tunnel. After that, nghttpx performs SSL/TLS +handshake with the downstream through the tunnel. The +timeouts when connecting and making CONNECT request can +be specified by \fI\%\-\-backend\-read\-timeout\fP and +\fI\%\-\-backend\-write\-timeout\fP options. +.UNINDENT +.SS Performance +.INDENT 0.0 +.TP +.B \-n, \-\-workers=<N> +Set the number of worker threads. +.sp +Default: \fB1\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-single\-thread +Run everything in one thread inside the worker process. +This feature is provided for better debugging +experience, or for the platforms which lack thread +support. If threading is disabled, this option is +always enabled. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-read\-rate=<SIZE> +Set maximum average read rate on frontend connection. +Setting 0 to this option means read rate is unlimited. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-read\-burst=<SIZE> +Set maximum read burst size on frontend connection. +Setting 0 to this option means read burst size is +unlimited. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-write\-rate=<SIZE> +Set maximum average write rate on frontend connection. +Setting 0 to this option means write rate is unlimited. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-write\-burst=<SIZE> +Set maximum write burst size on frontend connection. +Setting 0 to this option means write burst size is +unlimited. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-worker\-read\-rate=<SIZE> +Set maximum average read rate on frontend connection per +worker. Setting 0 to this option means read rate is +unlimited. Not implemented yet. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-worker\-read\-burst=<SIZE> +Set maximum read burst size on frontend connection per +worker. Setting 0 to this option means read burst size +is unlimited. Not implemented yet. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-worker\-write\-rate=<SIZE> +Set maximum average write rate on frontend connection +per worker. Setting 0 to this option means write rate +is unlimited. Not implemented yet. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-worker\-write\-burst=<SIZE> +Set maximum write burst size on frontend connection per +worker. Setting 0 to this option means write burst size +is unlimited. Not implemented yet. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-worker\-frontend\-connections=<N> +Set maximum number of simultaneous connections frontend +accepts. Setting 0 means unlimited. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-connections\-per\-host=<N> +Set maximum number of backend concurrent connections +(and/or streams in case of HTTP/2) per origin host. +This option is meaningful when \fI\%\-\-http2\-proxy\fP option is +used. The origin host is determined by authority +portion of request URI (or :authority header field for +HTTP/2). To limit the number of connections per +frontend for default mode, use +\fI\%\-\-backend\-connections\-per\-frontend\fP\&. +.sp +Default: \fB8\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-connections\-per\-frontend=<N> +Set maximum number of backend concurrent connections +(and/or streams in case of HTTP/2) per frontend. This +option is only used for default mode. 0 means +unlimited. To limit the number of connections per host +with \fI\%\-\-http2\-proxy\fP option, use +\fI\%\-\-backend\-connections\-per\-host\fP\&. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-rlimit\-nofile=<N> +Set maximum number of open files (RLIMIT_NOFILE) to <N>. +If 0 is given, nghttpx does not set the limit. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-rlimit\-memlock=<N> +Set maximum number of bytes of memory that may be locked +into RAM. If 0 is given, nghttpx does not set the +limit. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-request\-buffer=<SIZE> +Set buffer size used to store backend request. +.sp +Default: \fB16K\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-response\-buffer=<SIZE> +Set buffer size used to store backend response. +.sp +Default: \fB128K\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-fastopen=<N> +Enables \(dqTCP Fast Open\(dq for the listening socket and +limits the maximum length for the queue of connections +that have not yet completed the three\-way handshake. If +value is 0 then fast open is disabled. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-kqueue +Don\(aqt use kqueue. This option is only applicable for +the platforms which have kqueue. For other platforms, +this option will be simply ignored. +.UNINDENT +.SS Timeout +.INDENT 0.0 +.TP +.B \-\-frontend\-http2\-read\-timeout=<DURATION> +Specify read timeout for HTTP/2 frontend connection. +.sp +Default: \fB3m\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http3\-read\-timeout=<DURATION> +Specify read timeout for HTTP/3 frontend connection. +.sp +Default: \fB3m\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-read\-timeout=<DURATION> +Specify read timeout for HTTP/1.1 frontend connection. +.sp +Default: \fB1m\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-write\-timeout=<DURATION> +Specify write timeout for all frontend connections. +.sp +Default: \fB30s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-keep\-alive\-timeout=<DURATION> +Specify keep\-alive timeout for frontend HTTP/1 +connection. +.sp +Default: \fB1m\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-stream\-read\-timeout=<DURATION> +Specify read timeout for HTTP/2 streams. 0 means no +timeout. +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-stream\-write\-timeout=<DURATION> +Specify write timeout for HTTP/2 streams. 0 means no +timeout. +.sp +Default: \fB1m\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-read\-timeout=<DURATION> +Specify read timeout for backend connection. +.sp +Default: \fB1m\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-write\-timeout=<DURATION> +Specify write timeout for backend connection. +.sp +Default: \fB30s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-connect\-timeout=<DURATION> +Specify timeout before establishing TCP connection to +backend. +.sp +Default: \fB30s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-keep\-alive\-timeout=<DURATION> +Specify keep\-alive timeout for backend HTTP/1 +connection. +.sp +Default: \fB2s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-listener\-disable\-timeout=<DURATION> +After accepting connection failed, connection listener +is disabled for a given amount of time. Specifying 0 +disables this feature. +.sp +Default: \fB30s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http2\-setting\-timeout=<DURATION> +Specify timeout before SETTINGS ACK is received from +client. +.sp +Default: \fB10s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-http2\-settings\-timeout=<DURATION> +Specify timeout before SETTINGS ACK is received from +backend server. +.sp +Default: \fB10s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-max\-backoff=<DURATION> +Specify maximum backoff interval. This is used when +doing health check against offline backend (see \(dqfail\(dq +parameter in \fI\%\-\-backend\fP option). It is also used to +limit the maximum interval to temporarily disable +backend when nghttpx failed to connect to it. These +intervals are calculated using exponential backoff, and +consecutive failed attempts increase the interval. This +option caps its maximum value. +.sp +Default: \fB2m\fP +.UNINDENT +.SS SSL/TLS +.INDENT 0.0 +.TP +.B \-\-ciphers=<SUITE> +Set allowed cipher list for frontend connection. The +format of the string is described in OpenSSL ciphers(1). +This option sets cipher suites for TLSv1.2 or earlier. +Use \fI\%\-\-tls13\-ciphers\fP for TLSv1.3. +.sp +Default: \fBECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES256\-GCM\-SHA384:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-CHACHA20\-POLY1305:ECDHE\-RSA\-CHACHA20\-POLY1305:DHE\-RSA\-AES128\-GCM\-SHA256:DHE\-RSA\-AES256\-GCM\-SHA384\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls13\-ciphers=<SUITE> +Set allowed cipher list for frontend connection. The +format of the string is described in OpenSSL ciphers(1). +This option sets cipher suites for TLSv1.3. Use +\fI\%\-\-ciphers\fP for TLSv1.2 or earlier. +.sp +Default: \fBTLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-client\-ciphers=<SUITE> +Set allowed cipher list for backend connection. The +format of the string is described in OpenSSL ciphers(1). +This option sets cipher suites for TLSv1.2 or earlier. +Use \fI\%\-\-tls13\-client\-ciphers\fP for TLSv1.3. +.sp +Default: \fBECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES256\-GCM\-SHA384:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-CHACHA20\-POLY1305:ECDHE\-RSA\-CHACHA20\-POLY1305:DHE\-RSA\-AES128\-GCM\-SHA256:DHE\-RSA\-AES256\-GCM\-SHA384\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls13\-client\-ciphers=<SUITE> +Set allowed cipher list for backend connection. The +format of the string is described in OpenSSL ciphers(1). +This option sets cipher suites for TLSv1.3. Use +\fI\%\-\-tls13\-client\-ciphers\fP for TLSv1.2 or earlier. +.sp +Default: \fBTLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ecdh\-curves=<LIST> +Set supported curve list for frontend connections. +<LIST> is a colon separated list of curve NID or names +in the preference order. The supported curves depend on +the linked OpenSSL library. This function requires +OpenSSL >= 1.0.2. +.sp +Default: \fBX25519:P\-256:P\-384:P\-521\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-k, \-\-insecure +Don\(aqt verify backend server\(aqs certificate if TLS is +enabled for backend connections. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-cacert=<PATH> +Set path to trusted CA certificate file. It is used in +backend TLS connections to verify peer\(aqs certificate. +It is also used to verify OCSP response from the script +set by \fI\%\-\-fetch\-ocsp\-response\-file\fP\&. The file must be in +PEM format. It can contain multiple certificates. If +the linked OpenSSL is configured to load system wide +certificates, they are loaded at startup regardless of +this option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-private\-key\-passwd\-file=<PATH> +Path to file that contains password for the server\(aqs +private key. If none is given and the private key is +password protected it\(aqll be requested interactively. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...] +Specify additional certificate and private key file. +nghttpx will choose certificates based on the hostname +indicated by client using TLS SNI extension. If nghttpx +is built with OpenSSL >= 1.0.2, the shared elliptic +curves (e.g., P\-256) between client and server are also +taken into consideration. This allows nghttpx to send +ECDSA certificate to modern clients, while sending RSA +based certificate to older clients. This option can be +used multiple times. To make OCSP stapling work, +<CERTPATH> must be absolute path. +.sp +Additional parameter can be specified in <PARAM>. The +available <PARAM> is \(dqsct\-dir=<DIR>\(dq. +.sp +\(dqsct\-dir=<DIR>\(dq specifies the path to directory which +contains *.sct files for TLS +signed_certificate_timestamp extension (RFC 6962). This +feature requires OpenSSL >= 1.0.2. See also +\fI\%\-\-tls\-sct\-dir\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-dh\-param\-file=<PATH> +Path to file that contains DH parameters in PEM format. +Without this option, DHE cipher suites are not +available. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-alpn\-list=<LIST> +Comma delimited list of ALPN protocol identifier sorted +in the order of preference. That means most desirable +protocol comes first. The parameter must be delimited +by a single comma only and any white spaces are treated +as a part of protocol string. +.sp +Default: \fBh2,h2\-16,h2\-14,http/1.1\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-verify\-client +Require and verify client certificate. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-verify\-client\-cacert=<PATH> +Path to file that contains CA certificates to verify +client certificate. The file must be in PEM format. It +can contain multiple certificates. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-verify\-client\-tolerate\-expired +Accept expired client certificate. Operator should +handle the expired client certificate by some means +(e.g., mruby script). Otherwise, this option might +cause a security risk. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-client\-private\-key\-file=<PATH> +Path to file that contains client private key used in +backend client authentication. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-client\-cert\-file=<PATH> +Path to file that contains client certificate used in +backend client authentication. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-min\-proto\-version=<VER> +Specify minimum SSL/TLS protocol. The name matching is +done in case\-insensitive manner. The versions between +\fI\%\-\-tls\-min\-proto\-version\fP and \fI\%\-\-tls\-max\-proto\-version\fP are +enabled. If the protocol list advertised by client does +not overlap this range, you will receive the error +message \(dqunknown protocol\(dq. If a protocol version lower +than TLSv1.2 is specified, make sure that the compatible +ciphers are included in \fI\%\-\-ciphers\fP option. The default +cipher list only includes ciphers compatible with +TLSv1.2 or above. The available versions are: +TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0 +.sp +Default: \fBTLSv1.2\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-max\-proto\-version=<VER> +Specify maximum SSL/TLS protocol. The name matching is +done in case\-insensitive manner. The versions between +\fI\%\-\-tls\-min\-proto\-version\fP and \fI\%\-\-tls\-max\-proto\-version\fP are +enabled. If the protocol list advertised by client does +not overlap this range, you will receive the error +message \(dqunknown protocol\(dq. The available versions are: +TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0 +.sp +Default: \fBTLSv1.3\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-ticket\-key\-file=<PATH> +Path to file that contains random data to construct TLS +session ticket parameters. If aes\-128\-cbc is given in +\fI\%\-\-tls\-ticket\-key\-cipher\fP, the file must contain exactly +48 bytes. If aes\-256\-cbc is given in +\fI\%\-\-tls\-ticket\-key\-cipher\fP, the file must contain exactly +80 bytes. This options can be used repeatedly to +specify multiple ticket parameters. If several files +are given, only the first key is used to encrypt TLS +session tickets. Other keys are accepted but server +will issue new session ticket with first key. This +allows session key rotation. Please note that key +rotation does not occur automatically. User should +rearrange files or change options values and restart +nghttpx gracefully. If opening or reading given file +fails, all loaded keys are discarded and it is treated +as if none of this option is given. If this option is +not given or an error occurred while opening or reading +a file, key is generated every 1 hour internally and +they are valid for 12 hours. This is recommended if +ticket key sharing between nghttpx instances is not +required. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-ticket\-key\-memcached=<HOST>,<PORT>[;tls] +Specify address of memcached server to get TLS ticket +keys for session resumption. This enables shared TLS +ticket key between multiple nghttpx instances. nghttpx +does not set TLS ticket key to memcached. The external +ticket key generator is required. nghttpx just gets TLS +ticket keys from memcached, and use them, possibly +replacing current set of keys. It is up to extern TLS +ticket key generator to rotate keys frequently. See +\(dqTLS SESSION TICKET RESUMPTION\(dq section in manual page +to know the data format in memcached entry. Optionally, +memcached connection can be encrypted with TLS by +specifying \(dqtls\(dq parameter. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-ticket\-key\-memcached\-address\-family=(auto|IPv4|IPv6) +Specify address family of memcached connections to get +TLS ticket keys. If \(dqauto\(dq is given, both IPv4 and IPv6 +are considered. If \(dqIPv4\(dq is given, only IPv4 address +is considered. If \(dqIPv6\(dq is given, only IPv6 address is +considered. +.sp +Default: \fBauto\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-ticket\-key\-memcached\-interval=<DURATION> +Set interval to get TLS ticket keys from memcached. +.sp +Default: \fB10m\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-ticket\-key\-memcached\-max\-retry=<N> +Set maximum number of consecutive retries before +abandoning TLS ticket key retrieval. If this number is +reached, the attempt is considered as failure, and +\(dqfailure\(dq count is incremented by 1, which contributed +to the value controlled +\fI\%\-\-tls\-ticket\-key\-memcached\-max\-fail\fP option. +.sp +Default: \fB3\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-ticket\-key\-memcached\-max\-fail=<N> +Set maximum number of consecutive failure before +disabling TLS ticket until next scheduled key retrieval. +.sp +Default: \fB2\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-ticket\-key\-cipher=<CIPHER> +Specify cipher to encrypt TLS session ticket. Specify +either aes\-128\-cbc or aes\-256\-cbc. By default, +aes\-128\-cbc is used. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-ticket\-key\-memcached\-cert\-file=<PATH> +Path to client certificate for memcached connections to +get TLS ticket keys. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-ticket\-key\-memcached\-private\-key\-file=<PATH> +Path to client private key for memcached connections to +get TLS ticket keys. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-fetch\-ocsp\-response\-file=<PATH> +Path to fetch\-ocsp\-response script file. It should be +absolute path. +.sp +Default: \fB/usr/local/share/nghttp2/fetch\-ocsp\-response\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ocsp\-update\-interval=<DURATION> +Set interval to update OCSP response cache. +.sp +Default: \fB4h\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ocsp\-startup +Start accepting connections after initial attempts to +get OCSP responses finish. It does not matter some of +the attempts fail. This feature is useful if OCSP +responses must be available before accepting +connections. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-verify\-ocsp +nghttpx does not verify OCSP response. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-ocsp +Disable OCSP stapling. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-session\-cache\-memcached=<HOST>,<PORT>[;tls] +Specify address of memcached server to store session +cache. This enables shared session cache between +multiple nghttpx instances. Optionally, memcached +connection can be encrypted with TLS by specifying \(dqtls\(dq +parameter. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-session\-cache\-memcached\-address\-family=(auto|IPv4|IPv6) +Specify address family of memcached connections to store +session cache. If \(dqauto\(dq is given, both IPv4 and IPv6 +are considered. If \(dqIPv4\(dq is given, only IPv4 address +is considered. If \(dqIPv6\(dq is given, only IPv6 address is +considered. +.sp +Default: \fBauto\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-session\-cache\-memcached\-cert\-file=<PATH> +Path to client certificate for memcached connections to +store session cache. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-session\-cache\-memcached\-private\-key\-file=<PATH> +Path to client private key for memcached connections to +store session cache. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-dyn\-rec\-warmup\-threshold=<SIZE> +Specify the threshold size for TLS dynamic record size +behaviour. During a TLS session, after the threshold +number of bytes have been written, the TLS record size +will be increased to the maximum allowed (16K). The max +record size will continue to be used on the active TLS +session. After \fI\%\-\-tls\-dyn\-rec\-idle\-timeout\fP has elapsed, +the record size is reduced to 1300 bytes. Specify 0 to +always use the maximum record size, regardless of idle +period. This behaviour applies to all TLS based +frontends, and TLS HTTP/2 backends. +.sp +Default: \fB1M\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-dyn\-rec\-idle\-timeout=<DURATION> +Specify TLS dynamic record size behaviour timeout. See +\fI\%\-\-tls\-dyn\-rec\-warmup\-threshold\fP for more information. +This behaviour applies to all TLS based frontends, and +TLS HTTP/2 backends. +.sp +Default: \fB1s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-http2\-cipher\-block\-list +Allow block listed cipher suite on frontend HTTP/2 +connection. See +\fI\%https://tools.ietf.org/html/rfc7540#appendix\-A\fP for the +complete HTTP/2 cipher suites block list. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-client\-no\-http2\-cipher\-block\-list +Allow block listed cipher suite on backend HTTP/2 +connection. See +\fI\%https://tools.ietf.org/html/rfc7540#appendix\-A\fP for the +complete HTTP/2 cipher suites block list. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-sct\-dir=<DIR> +Specifies the directory where *.sct files exist. All +*.sct files in <DIR> are read, and sent as +extension_data of TLS signed_certificate_timestamp (RFC +6962) to client. These *.sct files are for the +certificate specified in positional command\-line +argument <CERT>, or certificate option in configuration +file. For additional certificates, use \fI\%\-\-subcert\fP +option. This option requires OpenSSL >= 1.0.2. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-psk\-secrets=<PATH> +Read list of PSK identity and secrets from <PATH>. This +is used for frontend connection. The each line of input +file is formatted as <identity>:<hex\-secret>, where +<identity> is PSK identity, and <hex\-secret> is secret +in hex. An empty line, and line which starts with \(aq#\(aq +are skipped. The default enabled cipher list might not +contain any PSK cipher suite. In that case, desired PSK +cipher suites must be enabled using \fI\%\-\-ciphers\fP option. +The desired PSK cipher suite may be block listed by +HTTP/2. To use those cipher suites with HTTP/2, +consider to use \fI\%\-\-no\-http2\-cipher\-block\-list\fP option. +But be aware its implications. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-client\-psk\-secrets=<PATH> +Read PSK identity and secrets from <PATH>. This is used +for backend connection. The each line of input file is +formatted as <identity>:<hex\-secret>, where <identity> +is PSK identity, and <hex\-secret> is secret in hex. An +empty line, and line which starts with \(aq#\(aq are skipped. +The first identity and secret pair encountered is used. +The default enabled cipher list might not contain any +PSK cipher suite. In that case, desired PSK cipher +suites must be enabled using \fI\%\-\-client\-ciphers\fP option. +The desired PSK cipher suite may be block listed by +HTTP/2. To use those cipher suites with HTTP/2, +consider to use \fI\%\-\-client\-no\-http2\-cipher\-block\-list\fP +option. But be aware its implications. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-no\-postpone\-early\-data +By default, except for QUIC connections, nghttpx +postpones forwarding HTTP requests sent in early data, +including those sent in partially in it, until TLS +handshake finishes. If all backend server recognizes +\(dqEarly\-Data\(dq header field, using this option makes +nghttpx not postpone forwarding request and get full +potential of 0\-RTT data. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-max\-early\-data=<SIZE> +Sets the maximum amount of 0\-RTT data that server +accepts. +.sp +Default: \fB16K\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-ktls +Enable ktls. For server, ktls is enable if +\fI\%\-\-tls\-session\-cache\-memcached\fP is not configured. +.UNINDENT +.SS HTTP/2 +.INDENT 0.0 +.TP +.B \-c, \-\-frontend\-http2\-max\-concurrent\-streams=<N> +Set the maximum number of the concurrent streams in one +frontend HTTP/2 session. +.sp +Default: \fB100\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-http2\-max\-concurrent\-streams=<N> +Set the maximum number of the concurrent streams in one +backend HTTP/2 session. This sets maximum number of +concurrent opened pushed streams. The maximum number of +concurrent requests are set by a remote server. +.sp +Default: \fB100\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http2\-window\-size=<SIZE> +Sets the per\-stream initial window size of HTTP/2 +frontend connection. +.sp +Default: \fB65535\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http2\-connection\-window\-size=<SIZE> +Sets the per\-connection window size of HTTP/2 frontend +connection. +.sp +Default: \fB65535\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-http2\-window\-size=<SIZE> +Sets the initial window size of HTTP/2 backend +connection. +.sp +Default: \fB65535\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-http2\-connection\-window\-size=<SIZE> +Sets the per\-connection window size of HTTP/2 backend +connection. +.sp +Default: \fB2147483647\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-http2\-no\-cookie\-crumbling +Don\(aqt crumble cookie header field. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-padding=<N> +Add at most <N> bytes to a HTTP/2 frame payload as +padding. Specify 0 to disable padding. This option is +meant for debugging purpose and not intended to enhance +protocol security. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-server\-push +Disable HTTP/2 server push. Server push is supported by +default mode and HTTP/2 frontend via Link header field. +It is also supported if both frontend and backend are +HTTP/2 in default mode. In this case, server push from +backend session is relayed to frontend, and server push +via Link header field is also supported. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http2\-optimize\-write\-buffer\-size +(Experimental) Enable write buffer size optimization in +frontend HTTP/2 TLS connection. This optimization aims +to reduce write buffer size so that it only contains +bytes which can send immediately. This makes server +more responsive to prioritized HTTP/2 stream because the +buffering of lower priority stream is reduced. This +option is only effective on recent Linux platform. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http2\-optimize\-window\-size +(Experimental) Automatically tune connection level +window size of frontend HTTP/2 TLS connection. If this +feature is enabled, connection window size starts with +the default window size, 65535 bytes. nghttpx +automatically adjusts connection window size based on +TCP receiving window size. The maximum window size is +capped by the value specified by +\fI\%\-\-frontend\-http2\-connection\-window\-size\fP\&. Since the +stream is subject to stream level window size, it should +be adjusted using \fI\%\-\-frontend\-http2\-window\-size\fP option as +well. This option is only effective on recent Linux +platform. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http2\-encoder\-dynamic\-table\-size=<SIZE> +Specify the maximum dynamic table size of HPACK encoder +in the frontend HTTP/2 connection. The decoder (client) +specifies the maximum dynamic table size it accepts. +Then the negotiated dynamic table size is the minimum of +this option value and the value which client specified. +.sp +Default: \fB4K\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http2\-decoder\-dynamic\-table\-size=<SIZE> +Specify the maximum dynamic table size of HPACK decoder +in the frontend HTTP/2 connection. +.sp +Default: \fB4K\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-http2\-encoder\-dynamic\-table\-size=<SIZE> +Specify the maximum dynamic table size of HPACK encoder +in the backend HTTP/2 connection. The decoder (backend) +specifies the maximum dynamic table size it accepts. +Then the negotiated dynamic table size is the minimum of +this option value and the value which backend specified. +.sp +Default: \fB4K\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-http2\-decoder\-dynamic\-table\-size=<SIZE> +Specify the maximum dynamic table size of HPACK decoder +in the backend HTTP/2 connection. +.sp +Default: \fB4K\fP +.UNINDENT +.SS Mode +.INDENT 0.0 +.TP +.B (default mode) +Accept HTTP/2, and HTTP/1.1 over SSL/TLS. \(dqno\-tls\(dq +parameter is used in \fI\%\-\-frontend\fP option, accept HTTP/2 +and HTTP/1.1 over cleartext TCP. The incoming HTTP/1.1 +connection can be upgraded to HTTP/2 through HTTP +Upgrade. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s, \-\-http2\-proxy +Like default mode, but enable forward proxy. This is so +called HTTP/2 proxy mode. +.UNINDENT +.SS Logging +.INDENT 0.0 +.TP +.B \-L, \-\-log\-level=<LEVEL> +Set the severity level of log output. <LEVEL> must be +one of INFO, NOTICE, WARN, ERROR and FATAL. +.sp +Default: \fBNOTICE\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-accesslog\-file=<PATH> +Set path to write access log. To reopen file, send USR1 +signal to nghttpx. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-accesslog\-syslog +Send access log to syslog. If this option is used, +\fI\%\-\-accesslog\-file\fP option is ignored. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-accesslog\-format=<FORMAT> +Specify format string for access log. The default +format is combined format. The following variables are +available: +.INDENT 7.0 +.IP \(bu 2 +$remote_addr: client IP address. +.IP \(bu 2 +$time_local: local time in Common Log format. +.IP \(bu 2 +$time_iso8601: local time in ISO 8601 format. +.IP \(bu 2 +$request: HTTP request line. +.IP \(bu 2 +$status: HTTP response status code. +.IP \(bu 2 +$body_bytes_sent: the number of bytes sent to client +as response body. +.IP \(bu 2 +$http_<VAR>: value of HTTP request header <VAR> where +\(aq_\(aq in <VAR> is replaced with \(aq\-\(aq. +.IP \(bu 2 +$remote_port: client port. +.IP \(bu 2 +$server_port: server port. +.IP \(bu 2 +$request_time: request processing time in seconds with +milliseconds resolution. +.IP \(bu 2 +$pid: PID of the running process. +.IP \(bu 2 +$alpn: ALPN identifier of the protocol which generates +the response. For HTTP/1, ALPN is always http/1.1, +regardless of minor version. +.IP \(bu 2 +$tls_cipher: cipher used for SSL/TLS connection. +.IP \(bu 2 +$tls_client_fingerprint_sha256: SHA\-256 fingerprint of +client certificate. +.IP \(bu 2 +$tls_client_fingerprint_sha1: SHA\-1 fingerprint of +client certificate. +.IP \(bu 2 +$tls_client_subject_name: subject name in client +certificate. +.IP \(bu 2 +$tls_client_issuer_name: issuer name in client +certificate. +.IP \(bu 2 +$tls_client_serial: serial number in client +certificate. +.IP \(bu 2 +$tls_protocol: protocol for SSL/TLS connection. +.IP \(bu 2 +$tls_session_id: session ID for SSL/TLS connection. +.IP \(bu 2 +$tls_session_reused: \(dqr\(dq if SSL/TLS session was +reused. Otherwise, \(dq.\(dq +.IP \(bu 2 +$tls_sni: SNI server name for SSL/TLS connection. +.IP \(bu 2 +$backend_host: backend host used to fulfill the +request. \(dq\-\(dq if backend host is not available. +.IP \(bu 2 +$backend_port: backend port used to fulfill the +request. \(dq\-\(dq if backend host is not available. +.IP \(bu 2 +$method: HTTP method +.IP \(bu 2 +$path: Request path including query. For CONNECT +request, authority is recorded. +.IP \(bu 2 +$path_without_query: $path up to the first \(aq?\(aq +character. For CONNECT request, authority is +recorded. +.IP \(bu 2 +$protocol_version: HTTP version (e.g., HTTP/1.1, +HTTP/2) +.UNINDENT +.sp +The variable can be enclosed by \(dq{\(dq and \(dq}\(dq for +disambiguation (e.g., ${remote_addr}). +.sp +Default: \fB$remote_addr \- \- [$time_local] \(dq$request\(dq $status $body_bytes_sent \(dq$http_referer\(dq \(dq$http_user_agent\(dq\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-accesslog\-write\-early +Write access log when response header fields are +received from backend rather than when request +transaction finishes. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-errorlog\-file=<PATH> +Set path to write error log. To reopen file, send USR1 +signal to nghttpx. stderr will be redirected to the +error log file unless \fI\%\-\-errorlog\-syslog\fP is used. +.sp +Default: \fB/dev/stderr\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-errorlog\-syslog +Send error log to syslog. If this option is used, +\fI\%\-\-errorlog\-file\fP option is ignored. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-syslog\-facility=<FACILITY> +Set syslog facility to <FACILITY>. +.sp +Default: \fBdaemon\fP +.UNINDENT +.SS HTTP +.INDENT 0.0 +.TP +.B \-\-add\-x\-forwarded\-for +Append X\-Forwarded\-For header field to the downstream +request. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-strip\-incoming\-x\-forwarded\-for +Strip X\-Forwarded\-For header field from inbound client +requests. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-add\-x\-forwarded\-proto +Don\(aqt append additional X\-Forwarded\-Proto header field +to the backend request. If inbound client sets +X\-Forwarded\-Proto, and +\fI\%\-\-no\-strip\-incoming\-x\-forwarded\-proto\fP option is used, +they are passed to the backend. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-strip\-incoming\-x\-forwarded\-proto +Don\(aqt strip X\-Forwarded\-Proto header field from inbound +client requests. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-add\-forwarded=<LIST> +Append RFC 7239 Forwarded header field with parameters +specified in comma delimited list <LIST>. The supported +parameters are \(dqby\(dq, \(dqfor\(dq, \(dqhost\(dq, and \(dqproto\(dq. By +default, the value of \(dqby\(dq and \(dqfor\(dq parameters are +obfuscated string. See \fI\%\-\-forwarded\-by\fP and +\fI\%\-\-forwarded\-for\fP options respectively. Note that nghttpx +does not translate non\-standard X\-Forwarded\-* header +fields into Forwarded header field, and vice versa. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-strip\-incoming\-forwarded +Strip Forwarded header field from inbound client +requests. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-forwarded\-by=(obfuscated|ip|<VALUE>) +Specify the parameter value sent out with \(dqby\(dq parameter +of Forwarded header field. If \(dqobfuscated\(dq is given, +the string is randomly generated at startup. If \(dqip\(dq is +given, the interface address of the connection, +including port number, is sent with \(dqby\(dq parameter. In +case of UNIX domain socket, \(dqlocalhost\(dq is used instead +of address and port. User can also specify the static +obfuscated string. The limitation is that it must start +with \(dq_\(dq, and only consists of character set +[A\-Za\-z0\-9._\-], as described in RFC 7239. +.sp +Default: \fBobfuscated\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-forwarded\-for=(obfuscated|ip) +Specify the parameter value sent out with \(dqfor\(dq +parameter of Forwarded header field. If \(dqobfuscated\(dq is +given, the string is randomly generated for each client +connection. If \(dqip\(dq is given, the remote client address +of the connection, without port number, is sent with +\(dqfor\(dq parameter. In case of UNIX domain socket, +\(dqlocalhost\(dq is used instead of address. +.sp +Default: \fBobfuscated\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-via +Don\(aqt append to Via header field. If Via header field +is received, it is left unaltered. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-strip\-incoming\-early\-data +Don\(aqt strip Early\-Data header field from inbound client +requests. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-location\-rewrite +Don\(aqt rewrite location header field in default mode. +When \fI\%\-\-http2\-proxy\fP is used, location header field will +not be altered regardless of this option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-host\-rewrite +Rewrite host and :authority header fields in default +mode. When \fI\%\-\-http2\-proxy\fP is used, these headers will +not be altered regardless of this option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]> +Specify protocol ID, port, host and origin of +alternative service. <HOST>, <ORIGIN> and <PARAMS> are +optional. Empty <HOST> and <ORIGIN> are allowed and +they are treated as nothing is specified. They are +advertised in alt\-svc header field only in HTTP/1.1 +frontend. This option can be used multiple times to +specify multiple alternative services. +Example: \fI\%\-\-altsvc\fP=\(dqh2,443,,,ma=3600; persist=1\(dq +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-http2\-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]> +Just like \fI\%\-\-altsvc\fP option, but this altsvc is only sent +in HTTP/2 frontend. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-add\-request\-header=<HEADER> +Specify additional header field to add to request header +set. The field name must be lowercase. This option +just appends header field and won\(aqt replace anything +already set. This option can be used several times to +specify multiple header fields. +Example: \fI\%\-\-add\-request\-header\fP=\(dqfoo: bar\(dq +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-add\-response\-header=<HEADER> +Specify additional header field to add to response +header set. The field name must be lowercase. This +option just appends header field and won\(aqt replace +anything already set. This option can be used several +times to specify multiple header fields. +Example: \fI\%\-\-add\-response\-header\fP=\(dqfoo: bar\(dq +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-request\-header\-field\-buffer=<SIZE> +Set maximum buffer size for incoming HTTP request header +field list. This is the sum of header name and value in +bytes. If trailer fields exist, they are counted +towards this number. +.sp +Default: \fB64K\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-max\-request\-header\-fields=<N> +Set maximum number of incoming HTTP request header +fields. If trailer fields exist, they are counted +towards this number. +.sp +Default: \fB100\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-response\-header\-field\-buffer=<SIZE> +Set maximum buffer size for incoming HTTP response +header field list. This is the sum of header name and +value in bytes. If trailer fields exist, they are +counted towards this number. +.sp +Default: \fB64K\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-max\-response\-header\-fields=<N> +Set maximum number of incoming HTTP response header +fields. If trailer fields exist, they are counted +towards this number. +.sp +Default: \fB500\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-error\-page=(<CODE>|*)=<PATH> +Set file path to custom error page served when nghttpx +originally generates HTTP error status code <CODE>. +<CODE> must be greater than or equal to 400, and at most +599. If \(dq*\(dq is used instead of <CODE>, it matches all +HTTP status code. If error status code comes from +backend server, the custom error pages are not used. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-server\-name=<NAME> +Change server response header field value to <NAME>. +.sp +Default: \fBnghttpx\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-server\-rewrite +Don\(aqt rewrite server header field in default mode. When +\fI\%\-\-http2\-proxy\fP is used, these headers will not be altered +regardless of this option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-redirect\-https\-port=<PORT> +Specify the port number which appears in Location header +field when redirect to HTTPS URI is made due to +\(dqredirect\-if\-not\-tls\(dq parameter in \fI\%\-\-backend\fP option. +.sp +Default: \fB443\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-require\-http\-scheme +Always require http or https scheme in HTTP request. It +also requires that https scheme must be used for an +encrypted connection. Otherwise, http scheme must be +used. This option is recommended for a server +deployment which directly faces clients and the services +it provides only require http or https scheme. +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B \-\-api\-max\-request\-body=<SIZE> +Set the maximum size of request body for API request. +.sp +Default: \fB32M\fP +.UNINDENT +.SS DNS +.INDENT 0.0 +.TP +.B \-\-dns\-cache\-timeout=<DURATION> +Set duration that cached DNS results remain valid. Note +that nghttpx caches the unsuccessful results as well. +.sp +Default: \fB10s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-dns\-lookup\-timeout=<DURATION> +Set timeout that DNS server is given to respond to the +initial DNS query. For the 2nd and later queries, +server is given time based on this timeout, and it is +scaled linearly. +.sp +Default: \fB5s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-dns\-max\-try=<N> +Set the number of DNS query before nghttpx gives up name +lookup. +.sp +Default: \fB2\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-max\-requests=<N> +The number of requests that single frontend connection +can process. For HTTP/2, this is the number of streams +in one HTTP/2 connection. For HTTP/1, this is the +number of keep alive requests. This is hint to nghttpx, +and it may allow additional few requests. The default +value is unlimited. +.UNINDENT +.SS Debug +.INDENT 0.0 +.TP +.B \-\-frontend\-http2\-dump\-request\-header=<PATH> +Dumps request headers received by HTTP/2 frontend to the +file denoted in <PATH>. The output is done in HTTP/1 +header field format and each header block is followed by +an empty line. This option is not thread safe and MUST +NOT be used with option \fI\%\-n\fP<N>, where <N> >= 2. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http2\-dump\-response\-header=<PATH> +Dumps response headers sent from HTTP/2 frontend to the +file denoted in <PATH>. The output is done in HTTP/1 +header field format and each header block is followed by +an empty line. This option is not thread safe and MUST +NOT be used with option \fI\%\-n\fP<N>, where <N> >= 2. +.UNINDENT +.INDENT 0.0 +.TP +.B \-o, \-\-frontend\-frame\-debug +Print HTTP/2 frames in frontend to stderr. This option +is not thread safe and MUST NOT be used with option +\fI\%\-n\fP=N, where N >= 2. +.UNINDENT +.SS Process +.INDENT 0.0 +.TP +.B \-D, \-\-daemon +Run in a background. If \fI\%\-D\fP is used, the current working +directory is changed to \(aq\fI/\fP\(aq. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-pid\-file=<PATH> +Set path to save PID of this program. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-user=<USER> +Run this program as <USER>. This option is intended to +be used to drop root privileges. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-single\-process +Run this program in a single process mode for debugging +purpose. Without this option, nghttpx creates at least +2 processes: main and worker processes. If this option +is used, main and worker are unified into a single +process. nghttpx still spawns additional process if +neverbleed is used. In the single process mode, the +signal handling feature is disabled. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-max\-worker\-processes=<N> +The maximum number of worker processes. nghttpx spawns +new worker process when it reloads its configuration. +The previous worker process enters graceful termination +period and will terminate when it finishes handling the +existing connections. However, if reloading +configurations happen very frequently, the worker +processes might be piled up if they take a bit long time +to finish the existing connections. With this option, +if the number of worker processes exceeds the given +value, the oldest worker process is terminated +immediately. Specifying 0 means no limit and it is the +default behaviour. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-worker\-process\-grace\-shutdown\-period=<DURATION> +Maximum period for a worker process to terminate +gracefully. When a worker process enters in graceful +shutdown period (e.g., when nghttpx reloads its +configuration) and it does not finish handling the +existing connections in the given period of time, it is +immediately terminated. Specifying 0 means no limit and +it is the default behaviour. +.UNINDENT +.SS Scripting +.INDENT 0.0 +.TP +.B \-\-mruby\-file=<PATH> +Set mruby script file +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ignore\-per\-pattern\-mruby\-error +Ignore mruby compile error for per\-pattern mruby script +file. If error occurred, it is treated as if no mruby +file were specified for the pattern. +.UNINDENT +.SS HTTP/3 and QUIC +.INDENT 0.0 +.TP +.B \-\-frontend\-quic\-idle\-timeout=<DURATION> +Specify an idle timeout for QUIC connection. +.sp +Default: \fB30s\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-quic\-debug\-log +Output QUIC debug log to \fI/dev/stderr.\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-quic\-bpf\-program\-file=<PATH> +Specify a path to eBPF program file reuseport_kern.o to +direct an incoming QUIC UDP datagram to a correct +socket. +.sp +Default: \fB/usr/local/lib/nghttp2/reuseport_kern.o\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-quic\-early\-data +Enable early data on frontend QUIC connections. nghttpx +sends \(dqEarly\-Data\(dq header field to a backend server if a +request is received in early data and handshake has not +finished. All backend servers should deal with possibly +replayed requests. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-quic\-qlog\-dir=<DIR> +Specify a directory where a qlog file is written for +frontend QUIC connections. A qlog file is created per +each QUIC connection. The file name is ISO8601 basic +format, followed by \(dq\-\(dq, server Source Connection ID and +\(dq.sqlog\(dq. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-quic\-require\-token +Require an address validation token for a frontend QUIC +connection. Server sends a token in Retry packet or +NEW_TOKEN frame in the previous connection. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-quic\-congestion\-controller=<CC> +Specify a congestion controller algorithm for a frontend +QUIC connection. <CC> should be either \(dqcubic\(dq or +\(dqbbr\(dq. +.sp +Default: \fBcubic\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-quic\-secret\-file=<PATH> +Path to file that contains secure random data to be used +as QUIC keying materials. It is used to derive keys for +encrypting tokens and Connection IDs. It is not used to +encrypt QUIC packets. Each line of this file must +contain exactly 136 bytes hex\-encoded string (when +decoded the byte string is 68 bytes long). The first 2 +bits of decoded byte string are used to identify the +keying material. An empty line or a line which starts +\(aq#\(aq is ignored. The file can contain more than one +keying materials. Because the identifier is 2 bits, at +most 4 keying materials are read and the remaining data +is discarded. The first keying material in the file is +primarily used for encryption and decryption for new +connection. The other ones are used to decrypt data for +the existing connections. Specifying multiple keying +materials enables key rotation. Please note that key +rotation does not occur automatically. User should +update files or change options values and restart +nghttpx gracefully. If opening or reading given file +fails, all loaded keying materials are discarded and it +is treated as if none of this option is given. If this +option is not given or an error occurred while opening +or reading a file, a keying material is generated +internally on startup and reload. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-quic\-server\-id=<HEXSTRING> +Specify server ID encoded in Connection ID to identify +this particular server instance. Connection ID is +encrypted and this part is not visible in public. It +must be 4 bytes long and must be encoded in hex string +(which is 8 bytes long). If this option is omitted, a +random server ID is generated on startup and +configuration reload. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-quic\-initial\-rtt=<DURATION> +Specify the initial RTT of the frontend QUIC connection. +.sp +Default: \fB333ms\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-quic\-bpf +Disable eBPF. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http3\-window\-size=<SIZE> +Sets the per\-stream initial window size of HTTP/3 +frontend connection. +.sp +Default: \fB256K\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http3\-connection\-window\-size=<SIZE> +Sets the per\-connection window size of HTTP/3 frontend +connection. +.sp +Default: \fB1M\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http3\-max\-window\-size=<SIZE> +Sets the maximum per\-stream window size of HTTP/3 +frontend connection. The window size is adjusted based +on the receiving rate of stream data. The initial value +is the value specified by \fI\%\-\-frontend\-http3\-window\-size\fP +and the window size grows up to <SIZE> bytes. +.sp +Default: \fB6M\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http3\-max\-connection\-window\-size=<SIZE> +Sets the maximum per\-connection window size of HTTP/3 +frontend connection. The window size is adjusted based +on the receiving rate of stream data. The initial value +is the value specified by +\fI\%\-\-frontend\-http3\-connection\-window\-size\fP and the window +size grows up to <SIZE> bytes. +.sp +Default: \fB8M\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-frontend\-http3\-max\-concurrent\-streams=<N> +Set the maximum number of the concurrent streams in one +frontend HTTP/3 connection. +.sp +Default: \fB100\fP +.UNINDENT +.SS Misc +.INDENT 0.0 +.TP +.B \-\-conf=<PATH> +Load configuration from <PATH>. Please note that +nghttpx always tries to read the default configuration +file if \fI\%\-\-conf\fP is not given. +.sp +Default: \fB/etc/nghttpx/nghttpx.conf\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-include=<PATH> +Load additional configurations from <PATH>. File <PATH> +is read when configuration parser encountered this +option. This option can be used multiple times, or even +recursively. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v, \-\-version +Print version and exit. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +Print this help and exit. +.UNINDENT +.sp +The <SIZE> argument is an integer and an optional unit (e.g., 10K is +10 * 1024). Units are K, M and G (powers of 1024). +.sp +The <DURATION> argument is an integer and an optional unit (e.g., 1s +is 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms +(hours, minutes, seconds and milliseconds, respectively). If a unit +is omitted, a second is used as unit. +.SH FILES +.INDENT 0.0 +.TP +.B \fI/etc/nghttpx/nghttpx.conf\fP +The default configuration file path nghttpx searches at startup. +The configuration file path can be changed using \fI\%\-\-conf\fP +option. +.sp +Those lines which are staring \fB#\fP are treated as comment. +.sp +The option name in the configuration file is the long command\-line +option name with leading \fB\-\-\fP stripped (e.g., \fBfrontend\fP). Put +\fB=\fP between option name and value. Don\(aqt put extra leading or +trailing spaces. +.sp +When specifying arguments including characters which have special +meaning to a shell, we usually use quotes so that shell does not +interpret them. When writing this configuration file, quotes for +this purpose must not be used. For example, specify additional +request header field, do this: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +add\-request\-header=foo: bar +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +instead of: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +add\-request\-header=\(dqfoo: bar\(dq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The options which do not take argument in the command\-line \fItake\fP +argument in the configuration file. Specify \fByes\fP as an argument +(e.g., \fBhttp2\-proxy=yes\fP). If other string is given, it is +ignored. +.sp +To specify private key and certificate file which are given as +positional arguments in command\-line, use \fBprivate\-key\-file\fP and +\fBcertificate\-file\fP\&. +.sp +\fI\%\-\-conf\fP option cannot be used in the configuration file and +will be ignored if specified. +.TP +.B Error log +Error log is written to stderr by default. It can be configured +using \fI\%\-\-errorlog\-file\fP\&. The format of log message is as +follows: +.sp +<datetime> <main\-pid> <current\-pid> <thread\-id> <level> (<filename>:<line>) <msg> +.INDENT 7.0 +.TP +.B <datetime> +It is a combination of date and time when the log is written. It +is in ISO 8601 format. +.TP +.B <main\-pid> +It is a main process ID. +.TP +.B <current\-pid> +It is a process ID which writes this log. +.TP +.B <thread\-id> +It is a thread ID which writes this log. It would be unique +within <current\-pid>. +.TP +.B <filename> and <line> +They are source file name, and line number which produce this log. +.TP +.B <msg> +It is a log message body. +.UNINDENT +.UNINDENT +.SH SIGNALS +.INDENT 0.0 +.TP +.B SIGQUIT +Shutdown gracefully. First accept pending connections and stop +accepting connection. After all connections are handled, nghttpx +exits. +.TP +.B SIGHUP +Reload configuration file given in \fI\%\-\-conf\fP\&. +.TP +.B SIGUSR1 +Reopen log files. +.UNINDENT +.sp +SIGUSR2 +.INDENT 0.0 +.INDENT 3.5 +Fork and execute nghttpx. It will execute the binary in the same +path with same command\-line arguments and environment variables. As +of nghttpx version 1.20.0, the new main process sends SIGQUIT to the +original main process when it is ready to serve requests. For the +earlier versions of nghttpx, user has to send SIGQUIT to the +original main process. +.sp +The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former +is usually used to execute new binary, and the main process is newly +spawned. On the other hand, the latter just reloads configuration +file, and the same main process continues to exist. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +nghttpx consists of multiple processes: one process for processing +these signals, and another one for processing requests. The former +spawns the latter. The former is called main process, and the +latter is called worker process. If neverbleed is enabled, the +worker process spawns neverbleed daemon process which does RSA key +processing. The above signal must be sent to the main process. If +the other processes received one of them, it is ignored. This +behaviour of these processes may change in the future release. In +other words, in the future release, the processes other than main +process may terminate upon the reception of these signals. +Therefore these signals should not be sent to the processes other +than main process. +.UNINDENT +.UNINDENT +.SH SERVER PUSH +.sp +nghttpx supports HTTP/2 server push in default mode with Link header +field. nghttpx looks for Link header field (\fI\%RFC 5988\fP) in response headers from +backend server and extracts URI\-reference with parameter +\fBrel=preload\fP (see \fI\%preload\fP) +and pushes those URIs to the frontend client. Here is a sample Link +header field to initiate server push: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +Link: </fonts/font.woff>; rel=preload +Link: </css/theme.css>; rel=preload +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Currently, the following restriction is applied for server push: +.INDENT 0.0 +.IP 1. 3 +The associated stream must have method \(dqGET\(dq or \(dqPOST\(dq. The +associated stream\(aqs status code must be 200. +.UNINDENT +.sp +This limitation may be loosened in the future release. +.sp +nghttpx also supports server push if both frontend and backend are +HTTP/2 in default mode. In this case, in addition to server push via +Link header field, server push from backend is forwarded to frontend +HTTP/2 session. +.sp +HTTP/2 server push will be disabled if \fI\%\-\-http2\-proxy\fP is +used. +.SH UNIX DOMAIN SOCKET +.sp +nghttpx supports UNIX domain socket with a filename for both frontend +and backend connections. +.sp +Please note that current nghttpx implementation does not delete a +socket with a filename. And on start up, if nghttpx detects that the +specified socket already exists in the file system, nghttpx first +deletes it. However, if SIGUSR2 is used to execute new binary and +both old and new configurations use same filename, new binary does not +delete the socket and continues to use it. +.SH OCSP STAPLING +.sp +OCSP query is done using external Python script +\fBfetch\-ocsp\-response\fP, which has been originally developed in Perl +as part of h2o project (\fI\%https://github.com/h2o/h2o\fP), and was +translated into Python. +.sp +The script file is usually installed under +\fB$(prefix)/share/nghttp2/\fP directory. The actual path to script can +be customized using \fI\%\-\-fetch\-ocsp\-response\-file\fP option. +.sp +If OCSP query is failed, previous OCSP response, if any, is continued +to be used. +.sp +\fI\%\-\-fetch\-ocsp\-response\-file\fP option provides wide range of +possibility to manage OCSP response. It can take an arbitrary script +or executable. The requirement is that it supports the command\-line +interface of \fBfetch\-ocsp\-response\fP script, and it must return a +valid DER encoded OCSP response on success. It must return exit code +0 on success, and 75 for temporary error, and the other error code for +generic failure. For large cluster of servers, it is not efficient +for each server to perform OCSP query using \fBfetch\-ocsp\-response\fP\&. +Instead, you can retrieve OCSP response in some way, and store it in a +disk or a shared database. Then specify a program in +\fI\%\-\-fetch\-ocsp\-response\-file\fP to fetch it from those stores. +This could provide a way to share the OCSP response between fleet of +servers, and also any OCSP query strategy can be applied which may be +beyond the ability of nghttpx itself or \fBfetch\-ocsp\-response\fP +script. +.SH TLS SESSION RESUMPTION +.sp +nghttpx supports TLS session resumption through both session ID and +session ticket. +.SS SESSION ID RESUMPTION +.sp +By default, session ID is shared by all worker threads. +.sp +If \fI\%\-\-tls\-session\-cache\-memcached\fP is given, nghttpx will +insert serialized session data to memcached with +\fBnghttpx:tls\-session\-cache:\fP + lowercase hex string of session ID +as a memcached entry key, with expiry time 12 hours. Session timeout +is set to 12 hours. +.sp +By default, connections to memcached server are not encrypted. To +enable encryption, use \fBtls\fP keyword in +\fI\%\-\-tls\-session\-cache\-memcached\fP option. +.SS TLS SESSION TICKET RESUMPTION +.sp +By default, session ticket is shared by all worker threads. The +automatic key rotation is also enabled by default. Every an hour, new +encryption key is generated, and previous encryption key becomes +decryption only key. We set session timeout to 12 hours, and thus we +keep at most 12 keys. +.sp +If \fI\%\-\-tls\-ticket\-key\-memcached\fP is given, encryption keys are +retrieved from memcached. nghttpx just reads keys from memcached; one +has to deploy key generator program to update keys frequently (e.g., +every 1 hour). The example key generator tlsticketupdate.go is +available under contrib directory in nghttp2 archive. The memcached +entry key is \fBnghttpx:tls\-ticket\-key\fP\&. The data format stored in +memcached is the binary format described below: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +| VERSION (4) |LEN (2)|KEY(48 or 80) ... ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ + ^ | + | | + +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ + (LEN, KEY) pair can be repeated +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +All numbers in the above figure is bytes. All integer fields are +network byte order. +.sp +First 4 bytes integer VERSION field, which must be 1. The 2 bytes +integer LEN field gives the length of following KEY field, which +contains key. If \fI\%\-\-tls\-ticket\-key\-cipher\fP=aes\-128\-cbc is +used, LEN must be 48. If +\fI\%\-\-tls\-ticket\-key\-cipher\fP=aes\-256\-cbc is used, LEN must be +80. LEN and KEY pair can be repeated multiple times to store multiple +keys. The key appeared first is used as encryption key. All the +remaining keys are used as decryption only. +.sp +By default, connections to memcached server are not encrypted. To +enable encryption, use \fBtls\fP keyword in +\fI\%\-\-tls\-ticket\-key\-memcached\fP option. +.sp +If \fI\%\-\-tls\-ticket\-key\-file\fP is given, encryption key is read +from the given file. In this case, nghttpx does not rotate key +automatically. To rotate key, one has to restart nghttpx (see +SIGNALS). +.SH CERTIFICATE TRANSPARENCY +.sp +nghttpx supports TLS \fBsigned_certificate_timestamp\fP extension (\fI\%RFC +6962\fP). The relevant options +are \fI\%\-\-tls\-sct\-dir\fP and \fBsct\-dir\fP parameter in +\fI\%\-\-subcert\fP\&. They takes a directory, and nghttpx reads all +files whose extension is \fB\&.sct\fP under the directory. The \fB*.sct\fP +files are encoded as \fBSignedCertificateTimestamp\fP struct described +in \fI\%section 3.2 of RFC 69662\fP\&. This format is +the same one used by \fI\%nginx\-ct\fP and \fI\%mod_ssl_ct\fP\&. +\fI\%ct\-submit\fP can be +used to submit certificates to log servers, and obtain the +\fBSignedCertificateTimestamp\fP struct which can be used with nghttpx. +.SH MRUBY SCRIPTING +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +The current mruby extension API is experimental and not frozen. The +API is subject to change in the future release. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Almost all string value returned from method, or attribute is a +fresh new mruby string, which involves memory allocation, and +copies. Therefore, it is strongly recommended to store a return +value in a local variable, and use it, instead of calling method or +accessing attribute repeatedly. +.UNINDENT +.UNINDENT +.sp +nghttpx allows users to extend its capability using mruby scripts. +nghttpx has 2 hook points to execute mruby script: request phase and +response phase. The request phase hook is invoked after all request +header fields are received from client. The response phase hook is +invoked after all response header fields are received from backend +server. These hooks allows users to modify header fields, or common +HTTP variables, like authority or request path, and even return custom +response without forwarding request to backend servers. +.sp +There are 2 levels of mruby script invocations: global and +per\-pattern. The global mruby script is set by \fI\%\-\-mruby\-file\fP +option and is called for all requests. The per\-pattern mruby script +is set by \(dqmruby\(dq parameter in \fI\%\-b\fP option. It is invoked for +a request which matches the particular pattern. The order of hook +invocation is: global request phase hook, per\-pattern request phase +hook, per\-pattern response phase hook, and finally global response +phase hook. If a hook returns a response, any later hooks are not +invoked. The global request hook is invoked before the pattern +matching is made and changing request path may affect the pattern +matching. +.sp +Please note that request and response hooks of per\-pattern mruby +script for a single request might not come from the same script. This +might happen after a request hook is executed, backend failed for some +reason, and at the same time, backend configuration is replaced by API +request, and then the request uses new configuration on retry. The +response hook from new configuration, if it is specified, will be +invoked. +.sp +The all mruby script will be evaluated once per thread on startup, and +it must instantiate object and evaluate it as the return value (e.g., +\fBApp.new\fP). This object is called app object. If app object +defines \fBon_req\fP method, it is called with \fI\%Nghttpx::Env\fP +object on request hook. Similarly, if app object defines \fBon_resp\fP +method, it is called with \fI\%Nghttpx::Env\fP object on response +hook. For each method invocation, user can can access +\fI\%Nghttpx::Request\fP and \fI\%Nghttpx::Response\fP objects +via \fI\%Nghttpx::Env#req\fP and \fI\%Nghttpx::Env#resp\fP +respectively. +.INDENT 0.0 +.TP +.B Nghttpx::REQUEST_PHASE +Constant to represent request phase. +.UNINDENT +.INDENT 0.0 +.TP +.B Nghttpx::RESPONSE_PHASE +Constant to represent response phase. +.UNINDENT +.INDENT 0.0 +.TP +.B class Nghttpx::Env +Object to represent current request specific context. +.INDENT 7.0 +.TP +.B attribute [R] req +Return \fI\%Request\fP object. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] resp +Return \fI\%Response\fP object. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] ctx +Return Ruby hash object. It persists until request finishes. +So values set in request phase hook can be retrieved in +response phase hook. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] phase +Return the current phase. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] remote_addr +Return IP address of a remote client. If connection is made +via UNIX domain socket, this returns the string \(dqlocalhost\(dq. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] server_addr +Return address of server that accepted the connection. This +is a string which specified in \fI\%\-\-frontend\fP option, +excluding port number, and not a resolved IP address. For +UNIX domain socket, this is a path to UNIX domain socket. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] server_port +Return port number of the server frontend which accepted the +connection from client. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_used +Return true if TLS is used on the connection. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_sni +Return the TLS SNI value which client sent in this connection. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_client_fingerprint_sha256 +Return the SHA\-256 fingerprint of a client certificate. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_client_fingerprint_sha1 +Return the SHA\-1 fingerprint of a client certificate. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_client_issuer_name +Return the issuer name of a client certificate. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_client_subject_name +Return the subject name of a client certificate. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_client_serial +Return the serial number of a client certificate. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_client_not_before +Return the start date of a client certificate in seconds since +the epoch. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_client_not_after +Return the end date of a client certificate in seconds since +the epoch. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_cipher +Return a TLS cipher negotiated in this connection. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_protocol +Return a TLS protocol version negotiated in this connection. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_session_id +Return a session ID for this connection in hex string. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_session_reused +Return true if, and only if a SSL/TLS session is reused. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] alpn +Return ALPN identifier negotiated in this connection. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_handshake_finished +Return true if SSL/TLS handshake has finished. If it returns +false in the request phase hook, the request is received in +TLSv1.3 early data (0\-RTT) and might be vulnerable to the +replay attack. nghttpx will send Early\-Data header field to +backend servers to indicate this. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B class Nghttpx::Request +Object to represent request from client. The modification to +Request object is allowed only in request phase hook. +.INDENT 7.0 +.TP +.B attribute [R] http_version_major +Return HTTP major version. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] http_version_minor +Return HTTP minor version. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R/W] method +HTTP method. On assignment, copy of given value is assigned. +We don\(aqt accept arbitrary method name. We will document them +later, but well known methods, like GET, PUT and POST, are all +supported. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R/W] authority +Authority (i.e., example.org), including optional port +component . On assignment, copy of given value is assigned. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R/W] scheme +Scheme (i.e., http, https). On assignment, copy of given +value is assigned. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R/W] path +Request path, including query component (i.e., /index.html). +On assignment, copy of given value is assigned. The path does +not include authority component of URI. This may include +query component. nghttpx makes certain normalization for +path. It decodes percent\-encoding for unreserved characters +(see \fI\%https://tools.ietf.org/html/rfc3986#section\-2.3\fP), and +resolves \(dq..\(dq and \(dq.\(dq. But it may leave characters which +should be percent\-encoded as is. So be careful when comparing +path against desired string. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] headers +Return Ruby hash containing copy of request header fields. +Changing values in returned hash does not change request +header fields actually used in request processing. Use +\fI\%Nghttpx::Request#add_header\fP or +\fI\%Nghttpx::Request#set_header\fP to change request +header fields. +.UNINDENT +.INDENT 7.0 +.TP +.B add_header(key, value) +Add header entry associated with key. The value can be single +string or array of string. It does not replace any existing +values associated with key. +.UNINDENT +.INDENT 7.0 +.TP +.B set_header(key, value) +Set header entry associated with key. The value can be single +string or array of string. It replaces any existing values +associated with key. +.UNINDENT +.INDENT 7.0 +.TP +.B clear_headers() +Clear all existing request header fields. +.UNINDENT +.INDENT 7.0 +.TP +.B push(uri) +Initiate to push resource identified by \fIuri\fP\&. Only HTTP/2 +protocol supports this feature. For the other protocols, this +method is noop. \fIuri\fP can be absolute URI, absolute path or +relative path to the current request. For absolute or +relative path, scheme and authority are inherited from the +current request. Currently, method is always GET. nghttpx +will issue request to backend servers to fulfill this request. +The request and response phase hooks will be called for pushed +resource as well. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B class Nghttpx::Response +Object to represent response from backend server. +.INDENT 7.0 +.TP +.B attribute [R] http_version_major +Return HTTP major version. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] http_version_minor +Return HTTP minor version. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R/W] status +HTTP status code. It must be in the range [200, 999], +inclusive. The non\-final status code is not supported in +mruby scripting at the moment. +.UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] headers +Return Ruby hash containing copy of response header fields. +Changing values in returned hash does not change response +header fields actually used in response processing. Use +\fI\%Nghttpx::Response#add_header\fP or +\fI\%Nghttpx::Response#set_header\fP to change response +header fields. +.UNINDENT +.INDENT 7.0 +.TP +.B add_header(key, value) +Add header entry associated with key. The value can be single +string or array of string. It does not replace any existing +values associated with key. +.UNINDENT +.INDENT 7.0 +.TP +.B set_header(key, value) +Set header entry associated with key. The value can be single +string or array of string. It replaces any existing values +associated with key. +.UNINDENT +.INDENT 7.0 +.TP +.B clear_headers() +Clear all existing response header fields. +.UNINDENT +.INDENT 7.0 +.TP +.B return(body) +Return custom response \fIbody\fP to a client. When this method +is called in request phase hook, the request is not forwarded +to the backend, and response phase hook for this request will +not be invoked. When this method is called in response phase +hook, response from backend server is canceled and discarded. +The status code and response header fields should be set +before using this method. To set status code, use +\fI\%Nghttpx::Response#status\fP\&. If status code is not +set, 200 is used. To set response header fields, +\fI\%Nghttpx::Response#add_header\fP and +\fI\%Nghttpx::Response#set_header\fP\&. When this method is +invoked in response phase hook, the response headers are +filled with the ones received from backend server. To send +completely custom header fields, first call +\fI\%Nghttpx::Response#clear_headers\fP to erase all +existing header fields, and then add required header fields. +It is an error to call this method twice for a given request. +.UNINDENT +.INDENT 7.0 +.TP +.B send_info(status, headers) +Send non\-final (informational) response to a client. \fIstatus\fP +must be in the range [100, 199], inclusive. \fIheaders\fP is a +hash containing response header fields. Its key must be a +string, and the associated value must be either string or +array of strings. Since this is not a final response, even if +this method is invoked, request is still forwarded to a +backend unless \fI\%Nghttpx::Response#return\fP is called. +This method can be called multiple times. It cannot be called +after \fI\%Nghttpx::Response#return\fP is called. +.UNINDENT +.UNINDENT +.SS MRUBY EXAMPLES +.sp +Modify request path: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +class App + def on_req(env) + env.req.path = \(dq/apps#{env.req.path}\(dq + end +end + +App.new +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Don\(aqt forget to instantiate and evaluate object at the last line. +.sp +Restrict permission of viewing a content to a specific client +addresses: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +class App + def on_req(env) + allowed_clients = [\(dq127.0.0.1\(dq, \(dq::1\(dq] + + if env.req.path.start_with?(\(dq/log/\(dq) && + !allowed_clients.include?(env.remote_addr) then + env.resp.status = 404 + env.resp.return \(dqpermission denied\(dq + end + end +end + +App.new +.ft P +.fi +.UNINDENT +.UNINDENT +.SH API ENDPOINTS +.sp +nghttpx exposes API endpoints to manipulate it via HTTP based API. By +default, API endpoint is disabled. To enable it, add a dedicated +frontend for API using \fI\%\-\-frontend\fP option with \(dqapi\(dq +parameter. All requests which come from this frontend address, will +be treated as API request. +.sp +The response is normally JSON dictionary, and at least includes the +following keys: +.INDENT 0.0 +.TP +.B status +The status of the request processing. The following values are +defined: +.INDENT 7.0 +.TP +.B Success +The request was successful. +.TP +.B Failure +The request was failed. No change has been made. +.UNINDENT +.TP +.B code +HTTP status code +.UNINDENT +.sp +Additionally, depending on the API endpoint, \fBdata\fP key may be +present, and its value contains the API endpoint specific data. +.sp +We wrote \(dqnormally\(dq, since nghttpx may return ordinal HTML response in +some cases where the error has occurred before reaching API endpoint +(e.g., header field is too large). +.sp +The following section describes available API endpoints. +.SS POST /api/v1beta1/backendconfig +.sp +This API replaces the current backend server settings with the +requested ones. The request method should be POST, but PUT is also +acceptable. The request body must be nghttpx configuration file +format. For configuration file format, see \fI\%FILES\fP section. The +line separator inside the request body must be single LF (0x0A). +Currently, only \fI\%backend\fP option is parsed, the +others are simply ignored. The semantics of this API is replace the +current backend with the backend options in request body. Describe +the desired set of backend severs, and nghttpx makes it happen. If +there is no \fI\%backend\fP option is found in request +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\&. +.sp +The replacement is done instantly without breaking existing +connections or requests. It also avoids any process creation as is +the case with hot swapping with signals. +.sp +The one limitation is that only numeric IP address is allowed in +\fI\%backend\fP in request body unless \(dqdns\(dq parameter +is used while non numeric hostname is allowed in command\-line or +configuration file is read using \fI\%\-\-conf\fP\&. +.SS GET /api/v1beta1/configrevision +.sp +This API returns configuration revision of the current nghttpx. The +configuration revision is opaque string, and it changes after each +reloading by SIGHUP. With this API, an external application knows +that whether nghttpx has finished reloading its configuration by +comparing the configuration revisions between before and after +reloading. It is recommended to disable persistent (keep\-alive) +connection for this purpose in order to avoid to send a request using +the reused connection which may bound to an old process. +.sp +This API returns response including \fBdata\fP key. Its value is JSON +object, and it contains at least the following key: +.INDENT 0.0 +.TP +.B configRevision +The configuration revision of the current nghttpx +.UNINDENT +.SH SEE ALSO +.sp +\fBnghttp(1)\fP, \fBnghttpd(1)\fP, \fBh2load(1)\fP +.SH AUTHOR +Tatsuhiro Tsujikawa +.SH COPYRIGHT +2012, 2015, 2016, Tatsuhiro Tsujikawa +.\" Generated by docutils manpage writer. +. diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst new file mode 100644 index 0000000..03109e4 --- /dev/null +++ b/doc/nghttpx.1.rst @@ -0,0 +1,2526 @@ + +.. GENERATED by help2rst.py. DO NOT EDIT DIRECTLY. + +.. program:: nghttpx + +nghttpx(1) +========== + +SYNOPSIS +-------- + +**nghttpx** [OPTIONS]... [<PRIVATE_KEY> <CERT>] + +DESCRIPTION +----------- + +A reverse proxy for HTTP/3, HTTP/2, and HTTP/1. + +.. describe:: <PRIVATE_KEY> + + + Set path to server's private key. Required unless + "no-tls" parameter is used in :option:`--frontend` option. + +.. describe:: <CERT> + + Set path to server's certificate. Required unless + "no-tls" parameter is used in :option:`--frontend` option. To + make OCSP stapling work, this must be an absolute path. + + +OPTIONS +------- + +The options are categorized into several groups. + +Connections +~~~~~~~~~~~ + +.. option:: -b, --backend=(<HOST>,<PORT>|unix:<PATH>)[;[<PATTERN>[:...]][[;<PARAM>]...] + + + Set backend host and port. The multiple backend + addresses are accepted by repeating this option. UNIX + domain socket can be specified by prefixing path name + with "unix:" (e.g., unix:/var/run/backend.sock). + + Optionally, if <PATTERN>s are given, the backend address + is only used if request matches the pattern. The + pattern matching is closely designed to ServeMux in + net/http package of Go programming language. <PATTERN> + consists of path, host + path or just host. The path + must start with "*/*". If it ends with "*/*", it matches + all request path in its subtree. To deal with the + request to the directory without trailing slash, the + path which ends with "*/*" also matches the request path + which only lacks trailing '*/*' (e.g., path "*/foo/*" + matches request path "*/foo*"). If it does not end with + "*/*", it performs exact match against the request path. + If host is given, it performs a match against the + request host. For a request received on the frontend + listener with "sni-fwd" parameter enabled, SNI host is + used instead of a request host. If host alone is given, + "*/*" is appended to it, so that it matches all request + paths under the host (e.g., specifying "nghttp2.org" + equals to "nghttp2.org/"). CONNECT method is treated + specially. It does not have path, and we don't allow + empty path. To workaround this, we assume that CONNECT + method has "*/*" as path. + + Patterns with host take precedence over patterns with + just path. Then, longer patterns take precedence over + shorter ones. + + Host can include "\*" in the left most position to + indicate wildcard match (only suffix match is done). + The "\*" must match at least one character. For example, + host pattern "\*.nghttp2.org" matches against + "www.nghttp2.org" and "git.ngttp2.org", but does not + match against "nghttp2.org". The exact hosts match + takes precedence over the wildcard hosts match. + + If path part ends with "\*", it is treated as wildcard + path. The wildcard path behaves differently from the + normal path. For normal path, match is made around the + boundary of path component separator,"*/*". On the other + hand, the wildcard path does not take into account the + path component separator. All paths which include the + wildcard path without last "\*" as prefix, and are + strictly longer than wildcard path without last "\*" are + matched. "\*" must match at least one character. For + example, the pattern "*/foo\**" matches "*/foo/*" and + "*/foobar*". But it does not match "*/foo*", or "*/fo*". + + If <PATTERN> is omitted or empty string, "*/*" is used as + pattern, which matches all request paths (catch-all + pattern). The catch-all backend must be given. + + When doing a match, nghttpx made some normalization to + pattern, request host and path. For host part, they are + converted to lower case. For path part, percent-encoded + unreserved characters defined in RFC 3986 are decoded, + and any dot-segments (".." and ".") are resolved and + removed. + + For example, :option:`-b`\'127.0.0.1,8080;nghttp2.org/httpbin/' + matches the request host "nghttp2.org" and the request + path "*/httpbin/get*", but does not match the request host + "nghttp2.org" and the request path "*/index.html*". + + The multiple <PATTERN>s can be specified, delimiting + them by ":". Specifying + :option:`-b`\'127.0.0.1,8080;nghttp2.org:www.nghttp2.org' has the + same effect to specify :option:`-b`\'127.0.0.1,8080;nghttp2.org' + and :option:`-b`\'127.0.0.1,8080;www.nghttp2.org'. + + The backend addresses sharing same <PATTERN> are grouped + together forming load balancing group. + + Several parameters <PARAM> are accepted after <PATTERN>. + The parameters are delimited by ";". The available + parameters are: "proto=<PROTO>", "tls", + "sni=<SNI_HOST>", "fall=<N>", "rise=<N>", + "affinity=<METHOD>", "dns", "redirect-if-not-tls", + "upgrade-scheme", "mruby=<PATH>", + "read-timeout=<DURATION>", "write-timeout=<DURATION>", + "group=<GROUP>", "group-weight=<N>", "weight=<N>", and + "dnf". The parameter consists of keyword, and + optionally followed by "=" and value. For example, the + parameter "proto=h2" consists of the keyword "proto" and + value "h2". The parameter "tls" consists of the keyword + "tls" without value. Each parameter is described as + follows. + + The backend application protocol can be specified using + optional "proto" parameter, and in the form of + "proto=<PROTO>". <PROTO> should be one of the following + list without quotes: "h2", "http/1.1". The default + value of <PROTO> is "http/1.1". Note that usually "h2" + refers to HTTP/2 over TLS. But in this option, it may + mean HTTP/2 over cleartext TCP unless "tls" keyword is + used (see below). + + TLS can be enabled by specifying optional "tls" + parameter. TLS is not enabled by default. + + With "sni=<SNI_HOST>" parameter, it can override the TLS + SNI field value with given <SNI_HOST>. This will + default to the backend <HOST> name + + The feature to detect whether backend is online or + offline can be enabled using optional "fall" and "rise" + parameters. Using "fall=<N>" parameter, if nghttpx + cannot connect to a this backend <N> times in a row, + this backend is assumed to be offline, and it is + excluded from load balancing. If <N> is 0, this backend + never be excluded from load balancing whatever times + nghttpx cannot connect to it, and this is the default. + There is also "rise=<N>" parameter. After backend was + excluded from load balancing group, nghttpx periodically + attempts to make a connection to the failed backend, and + if the connection is made successfully <N> times in a + row, the backend is assumed to be online, and it is now + eligible for load balancing target. If <N> is 0, a + backend is permanently offline, once it goes in that + state, and this is the default behaviour. + + The session affinity is enabled using + "affinity=<METHOD>" parameter. If "ip" is given in + <METHOD>, client IP based session affinity is enabled. + If "cookie" is given in <METHOD>, cookie based session + affinity is enabled. If "none" is given in <METHOD>, + session affinity is disabled, and this is the default. + The session affinity is enabled per <PATTERN>. If at + least one backend has "affinity" parameter, and its + <METHOD> is not "none", session affinity is enabled for + all backend servers sharing the same <PATTERN>. It is + advised to set "affinity" parameter to all backend + explicitly if session affinity is desired. The session + affinity may break if one of the backend gets + unreachable, or backend settings are reloaded or + replaced by API. + + If "affinity=cookie" is used, the additional + configuration is required. + "affinity-cookie-name=<NAME>" must be used to specify a + name of cookie to use. Optionally, + "affinity-cookie-path=<PATH>" can be used to specify a + path which cookie is applied. The optional + "affinity-cookie-secure=<SECURE>" controls the Secure + attribute of a cookie. The default value is "auto", and + the Secure attribute is determined by a request scheme. + If a request scheme is "https", then Secure attribute is + set. Otherwise, it is not set. If <SECURE> is "yes", + the Secure attribute is always set. If <SECURE> is + "no", the Secure attribute is always omitted. + "affinity-cookie-stickiness=<STICKINESS>" controls + stickiness of this affinity. If <STICKINESS> is + "loose", removing or adding a backend server might break + the affinity and the request might be forwarded to a + different backend server. If <STICKINESS> is "strict", + removing the designated backend server breaks affinity, + but adding new backend server does not cause breakage. + If the designated backend server becomes unavailable, + new backend server is chosen as if the request does not + have an affinity cookie. <STICKINESS> defaults to + "loose". + + By default, name resolution of backend host name is done + at start up, or reloading configuration. If "dns" + parameter is given, name resolution takes place + dynamically. This is useful if backend address changes + frequently. If "dns" is given, name resolution of + backend host name at start up, or reloading + configuration is skipped. + + If "redirect-if-not-tls" parameter is used, the matched + backend requires that frontend connection is TLS + encrypted. If it isn't, nghttpx responds to the request + with 308 status code, and https URI the client should + use instead is included in Location header field. The + port number in redirect URI is 443 by default, and can + be changed using :option:`--redirect-https-port` option. If at + least one backend has "redirect-if-not-tls" parameter, + this feature is enabled for all backend servers sharing + the same <PATTERN>. It is advised to set + "redirect-if-no-tls" parameter to all backends + explicitly if this feature is desired. + + If "upgrade-scheme" parameter is used along with "tls" + parameter, HTTP/2 :scheme pseudo header field is changed + to "https" from "http" when forwarding a request to this + particular backend. This is a workaround for a backend + server which requires "https" :scheme pseudo header + field on TLS encrypted connection. + + "mruby=<PATH>" parameter specifies a path to mruby + script file which is invoked when this pattern is + matched. All backends which share the same pattern must + have the same mruby path. + + "read-timeout=<DURATION>" and "write-timeout=<DURATION>" + parameters specify the read and write timeout of the + backend connection when this pattern is matched. All + backends which share the same pattern must have the same + timeouts. If these timeouts are entirely omitted for a + pattern, :option:`--backend-read-timeout` and + :option:`--backend-write-timeout` are used. + + "group=<GROUP>" parameter specifies the name of group + this backend address belongs to. By default, it belongs + to the unnamed default group. The name of group is + unique per pattern. "group-weight=<N>" parameter + specifies the weight of the group. The higher weight + gets more frequently selected by the load balancing + algorithm. <N> must be [1, 256] inclusive. The weight + 8 has 4 times more weight than 2. <N> must be the same + for all addresses which share the same <GROUP>. If + "group-weight" is omitted in an address, but the other + address which belongs to the same group specifies + "group-weight", its weight is used. If no + "group-weight" is specified for all addresses, the + weight of a group becomes 1. "group" and "group-weight" + are ignored if session affinity is enabled. + + "weight=<N>" parameter specifies the weight of the + backend address inside a group which this address + belongs to. The higher weight gets more frequently + selected by the load balancing algorithm. <N> must be + [1, 256] inclusive. The weight 8 has 4 times more + weight than weight 2. If this parameter is omitted, + weight becomes 1. "weight" is ignored if session + affinity is enabled. + + If "dnf" parameter is specified, an incoming request is + not forwarded to a backend and just consumed along with + the request body (actually a backend server never be + contacted). It is expected that the HTTP response is + generated by mruby script (see "mruby=<PATH>" parameter + above). "dnf" is an abbreviation of "do not forward". + + Since ";" and ":" are used as delimiter, <PATTERN> must + not contain these characters. In order to include ":" + in <PATTERN>, one has to specify "%3A" (which is + percent-encoded from of ":") instead. Since ";" has + special meaning in shell, the option value must be + quoted. + + + Default: ``127.0.0.1,80`` + +.. option:: -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...] + + Set frontend host and port. If <HOST> is '\*', it + assumes all addresses including both IPv4 and IPv6. + UNIX domain socket can be specified by prefixing path + name with "unix:" (e.g., unix:/var/run/nghttpx.sock). + This option can be used multiple times to listen to + multiple addresses. + + This option can take 0 or more parameters, which are + described below. Note that "api" and "healthmon" + parameters are mutually exclusive. + + Optionally, TLS can be disabled by specifying "no-tls" + parameter. TLS is enabled by default. + + If "sni-fwd" parameter is used, when performing a match + to select a backend server, SNI host name received from + the client is used instead of the request host. See + :option:`--backend` option about the pattern match. + + To make this frontend as API endpoint, specify "api" + parameter. This is disabled by default. It is + important to limit the access to the API frontend. + Otherwise, someone may change the backend server, and + break your services, or expose confidential information + to the outside the world. + + To make this frontend as health monitor endpoint, + specify "healthmon" parameter. This is disabled by + default. Any requests which come through this address + are replied with 200 HTTP status, without no body. + + To accept PROXY protocol version 1 and 2 on frontend + connection, specify "proxyproto" parameter. This is + disabled by default. + + To receive HTTP/3 (QUIC) traffic, specify "quic" + parameter. It makes nghttpx listen on UDP port rather + than TCP port. UNIX domain socket, "api", and + "healthmon" parameters cannot be used with "quic" + parameter. + + + Default: ``*,3000`` + +.. option:: --backlog=<N> + + Set listen backlog size. + + Default: ``65536`` + +.. option:: --backend-address-family=(auto|IPv4|IPv6) + + Specify address family of backend connections. If + "auto" is given, both IPv4 and IPv6 are considered. If + "IPv4" is given, only IPv4 address is considered. If + "IPv6" is given, only IPv6 address is considered. + + Default: ``auto`` + +.. option:: --backend-http-proxy-uri=<URI> + + Specify proxy URI in the form + http://[<USER>:<PASS>@]<PROXY>:<PORT>. If a proxy + requires authentication, specify <USER> and <PASS>. + Note that they must be properly percent-encoded. This + proxy is used when the backend connection is HTTP/2. + First, make a CONNECT request to the proxy and it + connects to the backend on behalf of nghttpx. This + forms tunnel. After that, nghttpx performs SSL/TLS + handshake with the downstream through the tunnel. The + timeouts when connecting and making CONNECT request can + be specified by :option:`--backend-read-timeout` and + :option:`--backend-write-timeout` options. + + +Performance +~~~~~~~~~~~ + +.. option:: -n, --workers=<N> + + Set the number of worker threads. + + Default: ``1`` + +.. option:: --single-thread + + Run everything in one thread inside the worker process. + This feature is provided for better debugging + experience, or for the platforms which lack thread + support. If threading is disabled, this option is + always enabled. + +.. option:: --read-rate=<SIZE> + + Set maximum average read rate on frontend connection. + Setting 0 to this option means read rate is unlimited. + + Default: ``0`` + +.. option:: --read-burst=<SIZE> + + Set maximum read burst size on frontend connection. + Setting 0 to this option means read burst size is + unlimited. + + Default: ``0`` + +.. option:: --write-rate=<SIZE> + + Set maximum average write rate on frontend connection. + Setting 0 to this option means write rate is unlimited. + + Default: ``0`` + +.. option:: --write-burst=<SIZE> + + Set maximum write burst size on frontend connection. + Setting 0 to this option means write burst size is + unlimited. + + Default: ``0`` + +.. option:: --worker-read-rate=<SIZE> + + Set maximum average read rate on frontend connection per + worker. Setting 0 to this option means read rate is + unlimited. Not implemented yet. + + Default: ``0`` + +.. option:: --worker-read-burst=<SIZE> + + Set maximum read burst size on frontend connection per + worker. Setting 0 to this option means read burst size + is unlimited. Not implemented yet. + + Default: ``0`` + +.. option:: --worker-write-rate=<SIZE> + + Set maximum average write rate on frontend connection + per worker. Setting 0 to this option means write rate + is unlimited. Not implemented yet. + + Default: ``0`` + +.. option:: --worker-write-burst=<SIZE> + + Set maximum write burst size on frontend connection per + worker. Setting 0 to this option means write burst size + is unlimited. Not implemented yet. + + Default: ``0`` + +.. option:: --worker-frontend-connections=<N> + + Set maximum number of simultaneous connections frontend + accepts. Setting 0 means unlimited. + + Default: ``0`` + +.. option:: --backend-connections-per-host=<N> + + Set maximum number of backend concurrent connections + (and/or streams in case of HTTP/2) per origin host. + This option is meaningful when :option:`--http2-proxy` option is + used. The origin host is determined by authority + portion of request URI (or :authority header field for + HTTP/2). To limit the number of connections per + frontend for default mode, use + :option:`--backend-connections-per-frontend`\. + + Default: ``8`` + +.. option:: --backend-connections-per-frontend=<N> + + Set maximum number of backend concurrent connections + (and/or streams in case of HTTP/2) per frontend. This + option is only used for default mode. 0 means + unlimited. To limit the number of connections per host + with :option:`--http2-proxy` option, use + :option:`--backend-connections-per-host`\. + + Default: ``0`` + +.. option:: --rlimit-nofile=<N> + + Set maximum number of open files (RLIMIT_NOFILE) to <N>. + If 0 is given, nghttpx does not set the limit. + + Default: ``0`` + +.. option:: --rlimit-memlock=<N> + + Set maximum number of bytes of memory that may be locked + into RAM. If 0 is given, nghttpx does not set the + limit. + + Default: ``0`` + +.. option:: --backend-request-buffer=<SIZE> + + Set buffer size used to store backend request. + + Default: ``16K`` + +.. option:: --backend-response-buffer=<SIZE> + + Set buffer size used to store backend response. + + Default: ``128K`` + +.. option:: --fastopen=<N> + + Enables "TCP Fast Open" for the listening socket and + limits the maximum length for the queue of connections + that have not yet completed the three-way handshake. If + value is 0 then fast open is disabled. + + Default: ``0`` + +.. option:: --no-kqueue + + Don't use kqueue. This option is only applicable for + the platforms which have kqueue. For other platforms, + this option will be simply ignored. + + +Timeout +~~~~~~~ + +.. option:: --frontend-http2-read-timeout=<DURATION> + + Specify read timeout for HTTP/2 frontend connection. + + Default: ``3m`` + +.. option:: --frontend-http3-read-timeout=<DURATION> + + Specify read timeout for HTTP/3 frontend connection. + + Default: ``3m`` + +.. option:: --frontend-read-timeout=<DURATION> + + Specify read timeout for HTTP/1.1 frontend connection. + + Default: ``1m`` + +.. option:: --frontend-write-timeout=<DURATION> + + Specify write timeout for all frontend connections. + + Default: ``30s`` + +.. option:: --frontend-keep-alive-timeout=<DURATION> + + Specify keep-alive timeout for frontend HTTP/1 + connection. + + Default: ``1m`` + +.. option:: --stream-read-timeout=<DURATION> + + Specify read timeout for HTTP/2 streams. 0 means no + timeout. + + Default: ``0`` + +.. option:: --stream-write-timeout=<DURATION> + + Specify write timeout for HTTP/2 streams. 0 means no + timeout. + + Default: ``1m`` + +.. option:: --backend-read-timeout=<DURATION> + + Specify read timeout for backend connection. + + Default: ``1m`` + +.. option:: --backend-write-timeout=<DURATION> + + Specify write timeout for backend connection. + + Default: ``30s`` + +.. option:: --backend-connect-timeout=<DURATION> + + Specify timeout before establishing TCP connection to + backend. + + Default: ``30s`` + +.. option:: --backend-keep-alive-timeout=<DURATION> + + Specify keep-alive timeout for backend HTTP/1 + connection. + + Default: ``2s`` + +.. option:: --listener-disable-timeout=<DURATION> + + After accepting connection failed, connection listener + is disabled for a given amount of time. Specifying 0 + disables this feature. + + Default: ``30s`` + +.. option:: --frontend-http2-setting-timeout=<DURATION> + + Specify timeout before SETTINGS ACK is received from + client. + + Default: ``10s`` + +.. option:: --backend-http2-settings-timeout=<DURATION> + + Specify timeout before SETTINGS ACK is received from + backend server. + + Default: ``10s`` + +.. option:: --backend-max-backoff=<DURATION> + + Specify maximum backoff interval. This is used when + doing health check against offline backend (see "fail" + parameter in :option:`--backend` option). It is also used to + limit the maximum interval to temporarily disable + backend when nghttpx failed to connect to it. These + intervals are calculated using exponential backoff, and + consecutive failed attempts increase the interval. This + option caps its maximum value. + + Default: ``2m`` + + +SSL/TLS +~~~~~~~ + +.. option:: --ciphers=<SUITE> + + Set allowed cipher list for frontend connection. The + format of the string is described in OpenSSL ciphers(1). + This option sets cipher suites for TLSv1.2 or earlier. + Use :option:`--tls13-ciphers` for TLSv1.3. + + Default: ``ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384`` + +.. option:: --tls13-ciphers=<SUITE> + + Set allowed cipher list for frontend connection. The + format of the string is described in OpenSSL ciphers(1). + This option sets cipher suites for TLSv1.3. Use + :option:`--ciphers` for TLSv1.2 or earlier. + + Default: ``TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256`` + +.. option:: --client-ciphers=<SUITE> + + Set allowed cipher list for backend connection. The + format of the string is described in OpenSSL ciphers(1). + This option sets cipher suites for TLSv1.2 or earlier. + Use :option:`--tls13-client-ciphers` for TLSv1.3. + + Default: ``ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384`` + +.. option:: --tls13-client-ciphers=<SUITE> + + Set allowed cipher list for backend connection. The + format of the string is described in OpenSSL ciphers(1). + This option sets cipher suites for TLSv1.3. Use + :option:`--tls13-client-ciphers` for TLSv1.2 or earlier. + + Default: ``TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256`` + +.. option:: --ecdh-curves=<LIST> + + Set supported curve list for frontend connections. + <LIST> is a colon separated list of curve NID or names + in the preference order. The supported curves depend on + the linked OpenSSL library. This function requires + OpenSSL >= 1.0.2. + + Default: ``X25519:P-256:P-384:P-521`` + +.. option:: -k, --insecure + + Don't verify backend server's certificate if TLS is + enabled for backend connections. + +.. option:: --cacert=<PATH> + + Set path to trusted CA certificate file. It is used in + backend TLS connections to verify peer's certificate. + It is also used to verify OCSP response from the script + set by :option:`--fetch-ocsp-response-file`\. The file must be in + PEM format. It can contain multiple certificates. If + the linked OpenSSL is configured to load system wide + certificates, they are loaded at startup regardless of + this option. + +.. option:: --private-key-passwd-file=<PATH> + + Path to file that contains password for the server's + private key. If none is given and the private key is + password protected it'll be requested interactively. + +.. option:: --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...] + + Specify additional certificate and private key file. + nghttpx will choose certificates based on the hostname + indicated by client using TLS SNI extension. If nghttpx + is built with OpenSSL >= 1.0.2, the shared elliptic + curves (e.g., P-256) between client and server are also + taken into consideration. This allows nghttpx to send + ECDSA certificate to modern clients, while sending RSA + based certificate to older clients. This option can be + used multiple times. To make OCSP stapling work, + <CERTPATH> must be absolute path. + + Additional parameter can be specified in <PARAM>. The + available <PARAM> is "sct-dir=<DIR>". + + "sct-dir=<DIR>" specifies the path to directory which + contains \*.sct files for TLS + signed_certificate_timestamp extension (RFC 6962). This + feature requires OpenSSL >= 1.0.2. See also + :option:`--tls-sct-dir` option. + +.. option:: --dh-param-file=<PATH> + + Path to file that contains DH parameters in PEM format. + Without this option, DHE cipher suites are not + available. + +.. option:: --alpn-list=<LIST> + + Comma delimited list of ALPN protocol identifier sorted + in the order of preference. That means most desirable + protocol comes first. The parameter must be delimited + by a single comma only and any white spaces are treated + as a part of protocol string. + + Default: ``h2,h2-16,h2-14,http/1.1`` + +.. option:: --verify-client + + Require and verify client certificate. + +.. option:: --verify-client-cacert=<PATH> + + Path to file that contains CA certificates to verify + client certificate. The file must be in PEM format. It + can contain multiple certificates. + +.. option:: --verify-client-tolerate-expired + + Accept expired client certificate. Operator should + handle the expired client certificate by some means + (e.g., mruby script). Otherwise, this option might + cause a security risk. + +.. option:: --client-private-key-file=<PATH> + + Path to file that contains client private key used in + backend client authentication. + +.. option:: --client-cert-file=<PATH> + + Path to file that contains client certificate used in + backend client authentication. + +.. option:: --tls-min-proto-version=<VER> + + Specify minimum SSL/TLS protocol. The name matching is + done in case-insensitive manner. The versions between + :option:`--tls-min-proto-version` and :option:`\--tls-max-proto-version` are + enabled. If the protocol list advertised by client does + not overlap this range, you will receive the error + message "unknown protocol". If a protocol version lower + than TLSv1.2 is specified, make sure that the compatible + ciphers are included in :option:`--ciphers` option. The default + cipher list only includes ciphers compatible with + TLSv1.2 or above. The available versions are: + TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0 + + Default: ``TLSv1.2`` + +.. option:: --tls-max-proto-version=<VER> + + Specify maximum SSL/TLS protocol. The name matching is + done in case-insensitive manner. The versions between + :option:`--tls-min-proto-version` and :option:`\--tls-max-proto-version` are + enabled. If the protocol list advertised by client does + not overlap this range, you will receive the error + message "unknown protocol". The available versions are: + TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0 + + Default: ``TLSv1.3`` + +.. option:: --tls-ticket-key-file=<PATH> + + Path to file that contains random data to construct TLS + session ticket parameters. If aes-128-cbc is given in + :option:`--tls-ticket-key-cipher`\, the file must contain exactly + 48 bytes. If aes-256-cbc is given in + :option:`--tls-ticket-key-cipher`\, the file must contain exactly + 80 bytes. This options can be used repeatedly to + specify multiple ticket parameters. If several files + are given, only the first key is used to encrypt TLS + session tickets. Other keys are accepted but server + will issue new session ticket with first key. This + allows session key rotation. Please note that key + rotation does not occur automatically. User should + rearrange files or change options values and restart + nghttpx gracefully. If opening or reading given file + fails, all loaded keys are discarded and it is treated + as if none of this option is given. If this option is + not given or an error occurred while opening or reading + a file, key is generated every 1 hour internally and + they are valid for 12 hours. This is recommended if + ticket key sharing between nghttpx instances is not + required. + +.. option:: --tls-ticket-key-memcached=<HOST>,<PORT>[;tls] + + Specify address of memcached server to get TLS ticket + keys for session resumption. This enables shared TLS + ticket key between multiple nghttpx instances. nghttpx + does not set TLS ticket key to memcached. The external + ticket key generator is required. nghttpx just gets TLS + ticket keys from memcached, and use them, possibly + replacing current set of keys. It is up to extern TLS + ticket key generator to rotate keys frequently. See + "TLS SESSION TICKET RESUMPTION" section in manual page + to know the data format in memcached entry. Optionally, + memcached connection can be encrypted with TLS by + specifying "tls" parameter. + +.. option:: --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6) + + Specify address family of memcached connections to get + TLS ticket keys. If "auto" is given, both IPv4 and IPv6 + are considered. If "IPv4" is given, only IPv4 address + is considered. If "IPv6" is given, only IPv6 address is + considered. + + Default: ``auto`` + +.. option:: --tls-ticket-key-memcached-interval=<DURATION> + + Set interval to get TLS ticket keys from memcached. + + Default: ``10m`` + +.. option:: --tls-ticket-key-memcached-max-retry=<N> + + Set maximum number of consecutive retries before + abandoning TLS ticket key retrieval. If this number is + reached, the attempt is considered as failure, and + "failure" count is incremented by 1, which contributed + to the value controlled + :option:`--tls-ticket-key-memcached-max-fail` option. + + Default: ``3`` + +.. option:: --tls-ticket-key-memcached-max-fail=<N> + + Set maximum number of consecutive failure before + disabling TLS ticket until next scheduled key retrieval. + + Default: ``2`` + +.. option:: --tls-ticket-key-cipher=<CIPHER> + + Specify cipher to encrypt TLS session ticket. Specify + either aes-128-cbc or aes-256-cbc. By default, + aes-128-cbc is used. + +.. option:: --tls-ticket-key-memcached-cert-file=<PATH> + + Path to client certificate for memcached connections to + get TLS ticket keys. + +.. option:: --tls-ticket-key-memcached-private-key-file=<PATH> + + Path to client private key for memcached connections to + get TLS ticket keys. + +.. option:: --fetch-ocsp-response-file=<PATH> + + Path to fetch-ocsp-response script file. It should be + absolute path. + + Default: ``/usr/local/share/nghttp2/fetch-ocsp-response`` + +.. option:: --ocsp-update-interval=<DURATION> + + Set interval to update OCSP response cache. + + Default: ``4h`` + +.. option:: --ocsp-startup + + Start accepting connections after initial attempts to + get OCSP responses finish. It does not matter some of + the attempts fail. This feature is useful if OCSP + responses must be available before accepting + connections. + +.. option:: --no-verify-ocsp + + nghttpx does not verify OCSP response. + +.. option:: --no-ocsp + + Disable OCSP stapling. + +.. option:: --tls-session-cache-memcached=<HOST>,<PORT>[;tls] + + Specify address of memcached server to store session + cache. This enables shared session cache between + multiple nghttpx instances. Optionally, memcached + connection can be encrypted with TLS by specifying "tls" + parameter. + +.. option:: --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6) + + Specify address family of memcached connections to store + session cache. If "auto" is given, both IPv4 and IPv6 + are considered. If "IPv4" is given, only IPv4 address + is considered. If "IPv6" is given, only IPv6 address is + considered. + + Default: ``auto`` + +.. option:: --tls-session-cache-memcached-cert-file=<PATH> + + Path to client certificate for memcached connections to + store session cache. + +.. option:: --tls-session-cache-memcached-private-key-file=<PATH> + + Path to client private key for memcached connections to + store session cache. + +.. option:: --tls-dyn-rec-warmup-threshold=<SIZE> + + Specify the threshold size for TLS dynamic record size + behaviour. During a TLS session, after the threshold + number of bytes have been written, the TLS record size + will be increased to the maximum allowed (16K). The max + record size will continue to be used on the active TLS + session. After :option:`--tls-dyn-rec-idle-timeout` has elapsed, + the record size is reduced to 1300 bytes. Specify 0 to + always use the maximum record size, regardless of idle + period. This behaviour applies to all TLS based + frontends, and TLS HTTP/2 backends. + + Default: ``1M`` + +.. option:: --tls-dyn-rec-idle-timeout=<DURATION> + + Specify TLS dynamic record size behaviour timeout. See + :option:`--tls-dyn-rec-warmup-threshold` for more information. + This behaviour applies to all TLS based frontends, and + TLS HTTP/2 backends. + + Default: ``1s`` + +.. option:: --no-http2-cipher-block-list + + Allow block listed cipher suite on frontend HTTP/2 + connection. See + https://tools.ietf.org/html/rfc7540#appendix-A for the + complete HTTP/2 cipher suites block list. + +.. option:: --client-no-http2-cipher-block-list + + Allow block listed cipher suite on backend HTTP/2 + connection. See + https://tools.ietf.org/html/rfc7540#appendix-A for the + complete HTTP/2 cipher suites block list. + +.. option:: --tls-sct-dir=<DIR> + + Specifies the directory where \*.sct files exist. All + \*.sct files in <DIR> are read, and sent as + extension_data of TLS signed_certificate_timestamp (RFC + 6962) to client. These \*.sct files are for the + certificate specified in positional command-line + argument <CERT>, or certificate option in configuration + file. For additional certificates, use :option:`--subcert` + option. This option requires OpenSSL >= 1.0.2. + +.. option:: --psk-secrets=<PATH> + + Read list of PSK identity and secrets from <PATH>. This + is used for frontend connection. The each line of input + file is formatted as <identity>:<hex-secret>, where + <identity> is PSK identity, and <hex-secret> is secret + in hex. An empty line, and line which starts with '#' + are skipped. The default enabled cipher list might not + contain any PSK cipher suite. In that case, desired PSK + cipher suites must be enabled using :option:`--ciphers` option. + The desired PSK cipher suite may be block listed by + HTTP/2. To use those cipher suites with HTTP/2, + consider to use :option:`--no-http2-cipher-block-list` option. + But be aware its implications. + +.. option:: --client-psk-secrets=<PATH> + + Read PSK identity and secrets from <PATH>. This is used + for backend connection. The each line of input file is + formatted as <identity>:<hex-secret>, where <identity> + is PSK identity, and <hex-secret> is secret in hex. An + empty line, and line which starts with '#' are skipped. + The first identity and secret pair encountered is used. + The default enabled cipher list might not contain any + PSK cipher suite. In that case, desired PSK cipher + suites must be enabled using :option:`--client-ciphers` option. + The desired PSK cipher suite may be block listed by + HTTP/2. To use those cipher suites with HTTP/2, + consider to use :option:`--client-no-http2-cipher-block-list` + option. But be aware its implications. + +.. option:: --tls-no-postpone-early-data + + By default, except for QUIC connections, nghttpx + postpones forwarding HTTP requests sent in early data, + including those sent in partially in it, until TLS + handshake finishes. If all backend server recognizes + "Early-Data" header field, using this option makes + nghttpx not postpone forwarding request and get full + potential of 0-RTT data. + +.. option:: --tls-max-early-data=<SIZE> + + Sets the maximum amount of 0-RTT data that server + accepts. + + Default: ``16K`` + +.. option:: --tls-ktls + + Enable ktls. For server, ktls is enable if + :option:`--tls-session-cache-memcached` is not configured. + + +HTTP/2 +~~~~~~ + +.. option:: -c, --frontend-http2-max-concurrent-streams=<N> + + Set the maximum number of the concurrent streams in one + frontend HTTP/2 session. + + Default: ``100`` + +.. option:: --backend-http2-max-concurrent-streams=<N> + + Set the maximum number of the concurrent streams in one + backend HTTP/2 session. This sets maximum number of + concurrent opened pushed streams. The maximum number of + concurrent requests are set by a remote server. + + Default: ``100`` + +.. option:: --frontend-http2-window-size=<SIZE> + + Sets the per-stream initial window size of HTTP/2 + frontend connection. + + Default: ``65535`` + +.. option:: --frontend-http2-connection-window-size=<SIZE> + + Sets the per-connection window size of HTTP/2 frontend + connection. + + Default: ``65535`` + +.. option:: --backend-http2-window-size=<SIZE> + + Sets the initial window size of HTTP/2 backend + connection. + + Default: ``65535`` + +.. option:: --backend-http2-connection-window-size=<SIZE> + + Sets the per-connection window size of HTTP/2 backend + connection. + + Default: ``2147483647`` + +.. option:: --http2-no-cookie-crumbling + + Don't crumble cookie header field. + +.. option:: --padding=<N> + + Add at most <N> bytes to a HTTP/2 frame payload as + padding. Specify 0 to disable padding. This option is + meant for debugging purpose and not intended to enhance + protocol security. + +.. option:: --no-server-push + + Disable HTTP/2 server push. Server push is supported by + default mode and HTTP/2 frontend via Link header field. + It is also supported if both frontend and backend are + HTTP/2 in default mode. In this case, server push from + backend session is relayed to frontend, and server push + via Link header field is also supported. + +.. option:: --frontend-http2-optimize-write-buffer-size + + (Experimental) Enable write buffer size optimization in + frontend HTTP/2 TLS connection. This optimization aims + to reduce write buffer size so that it only contains + bytes which can send immediately. This makes server + more responsive to prioritized HTTP/2 stream because the + buffering of lower priority stream is reduced. This + option is only effective on recent Linux platform. + +.. option:: --frontend-http2-optimize-window-size + + (Experimental) Automatically tune connection level + window size of frontend HTTP/2 TLS connection. If this + feature is enabled, connection window size starts with + the default window size, 65535 bytes. nghttpx + automatically adjusts connection window size based on + TCP receiving window size. The maximum window size is + capped by the value specified by + :option:`--frontend-http2-connection-window-size`\. Since the + stream is subject to stream level window size, it should + be adjusted using :option:`--frontend-http2-window-size` option as + well. This option is only effective on recent Linux + platform. + +.. option:: --frontend-http2-encoder-dynamic-table-size=<SIZE> + + Specify the maximum dynamic table size of HPACK encoder + in the frontend HTTP/2 connection. The decoder (client) + specifies the maximum dynamic table size it accepts. + Then the negotiated dynamic table size is the minimum of + this option value and the value which client specified. + + Default: ``4K`` + +.. option:: --frontend-http2-decoder-dynamic-table-size=<SIZE> + + Specify the maximum dynamic table size of HPACK decoder + in the frontend HTTP/2 connection. + + Default: ``4K`` + +.. option:: --backend-http2-encoder-dynamic-table-size=<SIZE> + + Specify the maximum dynamic table size of HPACK encoder + in the backend HTTP/2 connection. The decoder (backend) + specifies the maximum dynamic table size it accepts. + Then the negotiated dynamic table size is the minimum of + this option value and the value which backend specified. + + Default: ``4K`` + +.. option:: --backend-http2-decoder-dynamic-table-size=<SIZE> + + Specify the maximum dynamic table size of HPACK decoder + in the backend HTTP/2 connection. + + Default: ``4K`` + + +Mode +~~~~ + +.. describe:: (default mode) + + + Accept HTTP/2, and HTTP/1.1 over SSL/TLS. "no-tls" + parameter is used in :option:`--frontend` option, accept HTTP/2 + and HTTP/1.1 over cleartext TCP. The incoming HTTP/1.1 + connection can be upgraded to HTTP/2 through HTTP + Upgrade. + +.. option:: -s, --http2-proxy + + Like default mode, but enable forward proxy. This is so + called HTTP/2 proxy mode. + + +Logging +~~~~~~~ + +.. option:: -L, --log-level=<LEVEL> + + Set the severity level of log output. <LEVEL> must be + one of INFO, NOTICE, WARN, ERROR and FATAL. + + Default: ``NOTICE`` + +.. option:: --accesslog-file=<PATH> + + Set path to write access log. To reopen file, send USR1 + signal to nghttpx. + +.. option:: --accesslog-syslog + + Send access log to syslog. If this option is used, + :option:`--accesslog-file` option is ignored. + +.. option:: --accesslog-format=<FORMAT> + + Specify format string for access log. The default + format is combined format. The following variables are + available: + + * $remote_addr: client IP address. + * $time_local: local time in Common Log format. + * $time_iso8601: local time in ISO 8601 format. + * $request: HTTP request line. + * $status: HTTP response status code. + * $body_bytes_sent: the number of bytes sent to client + as response body. + * $http_<VAR>: value of HTTP request header <VAR> where + '_' in <VAR> is replaced with '-'. + * $remote_port: client port. + * $server_port: server port. + * $request_time: request processing time in seconds with + milliseconds resolution. + * $pid: PID of the running process. + * $alpn: ALPN identifier of the protocol which generates + the response. For HTTP/1, ALPN is always http/1.1, + regardless of minor version. + * $tls_cipher: cipher used for SSL/TLS connection. + * $tls_client_fingerprint_sha256: SHA-256 fingerprint of + client certificate. + * $tls_client_fingerprint_sha1: SHA-1 fingerprint of + client certificate. + * $tls_client_subject_name: subject name in client + certificate. + * $tls_client_issuer_name: issuer name in client + certificate. + * $tls_client_serial: serial number in client + certificate. + * $tls_protocol: protocol for SSL/TLS connection. + * $tls_session_id: session ID for SSL/TLS connection. + * $tls_session_reused: "r" if SSL/TLS session was + reused. Otherwise, "." + * $tls_sni: SNI server name for SSL/TLS connection. + * $backend_host: backend host used to fulfill the + request. "-" if backend host is not available. + * $backend_port: backend port used to fulfill the + request. "-" if backend host is not available. + * $method: HTTP method + * $path: Request path including query. For CONNECT + request, authority is recorded. + * $path_without_query: $path up to the first '?' + character. For CONNECT request, authority is + recorded. + * $protocol_version: HTTP version (e.g., HTTP/1.1, + HTTP/2) + + The variable can be enclosed by "{" and "}" for + disambiguation (e.g., ${remote_addr}). + + + Default: ``$remote_addr - - [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"`` + +.. option:: --accesslog-write-early + + Write access log when response header fields are + received from backend rather than when request + transaction finishes. + +.. option:: --errorlog-file=<PATH> + + Set path to write error log. To reopen file, send USR1 + signal to nghttpx. stderr will be redirected to the + error log file unless :option:`--errorlog-syslog` is used. + + Default: ``/dev/stderr`` + +.. option:: --errorlog-syslog + + Send error log to syslog. If this option is used, + :option:`--errorlog-file` option is ignored. + +.. option:: --syslog-facility=<FACILITY> + + Set syslog facility to <FACILITY>. + + Default: ``daemon`` + + +HTTP +~~~~ + +.. option:: --add-x-forwarded-for + + Append X-Forwarded-For header field to the downstream + request. + +.. option:: --strip-incoming-x-forwarded-for + + Strip X-Forwarded-For header field from inbound client + requests. + +.. option:: --no-add-x-forwarded-proto + + Don't append additional X-Forwarded-Proto header field + to the backend request. If inbound client sets + X-Forwarded-Proto, and + :option:`--no-strip-incoming-x-forwarded-proto` option is used, + they are passed to the backend. + +.. option:: --no-strip-incoming-x-forwarded-proto + + Don't strip X-Forwarded-Proto header field from inbound + client requests. + +.. option:: --add-forwarded=<LIST> + + Append RFC 7239 Forwarded header field with parameters + specified in comma delimited list <LIST>. The supported + parameters are "by", "for", "host", and "proto". By + default, the value of "by" and "for" parameters are + obfuscated string. See :option:`--forwarded-by` and + :option:`--forwarded-for` options respectively. Note that nghttpx + does not translate non-standard X-Forwarded-\* header + fields into Forwarded header field, and vice versa. + +.. option:: --strip-incoming-forwarded + + Strip Forwarded header field from inbound client + requests. + +.. option:: --forwarded-by=(obfuscated|ip|<VALUE>) + + Specify the parameter value sent out with "by" parameter + of Forwarded header field. If "obfuscated" is given, + the string is randomly generated at startup. If "ip" is + given, the interface address of the connection, + including port number, is sent with "by" parameter. In + case of UNIX domain socket, "localhost" is used instead + of address and port. User can also specify the static + obfuscated string. The limitation is that it must start + with "_", and only consists of character set + [A-Za-z0-9._-], as described in RFC 7239. + + Default: ``obfuscated`` + +.. option:: --forwarded-for=(obfuscated|ip) + + Specify the parameter value sent out with "for" + parameter of Forwarded header field. If "obfuscated" is + given, the string is randomly generated for each client + connection. If "ip" is given, the remote client address + of the connection, without port number, is sent with + "for" parameter. In case of UNIX domain socket, + "localhost" is used instead of address. + + Default: ``obfuscated`` + +.. option:: --no-via + + Don't append to Via header field. If Via header field + is received, it is left unaltered. + +.. option:: --no-strip-incoming-early-data + + Don't strip Early-Data header field from inbound client + requests. + +.. option:: --no-location-rewrite + + Don't rewrite location header field in default mode. + When :option:`--http2-proxy` is used, location header field will + not be altered regardless of this option. + +.. option:: --host-rewrite + + Rewrite host and :authority header fields in default + mode. When :option:`--http2-proxy` is used, these headers will + not be altered regardless of this option. + +.. option:: --altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]> + + Specify protocol ID, port, host and origin of + alternative service. <HOST>, <ORIGIN> and <PARAMS> are + optional. Empty <HOST> and <ORIGIN> are allowed and + they are treated as nothing is specified. They are + advertised in alt-svc header field only in HTTP/1.1 + frontend. This option can be used multiple times to + specify multiple alternative services. + Example: :option:`--altsvc`\="h2,443,,,ma=3600; persist=1" + +.. option:: --http2-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]> + + Just like :option:`--altsvc` option, but this altsvc is only sent + in HTTP/2 frontend. + +.. option:: --add-request-header=<HEADER> + + Specify additional header field to add to request header + set. The field name must be lowercase. This option + just appends header field and won't replace anything + already set. This option can be used several times to + specify multiple header fields. + Example: :option:`--add-request-header`\="foo: bar" + +.. option:: --add-response-header=<HEADER> + + Specify additional header field to add to response + header set. The field name must be lowercase. This + option just appends header field and won't replace + anything already set. This option can be used several + times to specify multiple header fields. + Example: :option:`--add-response-header`\="foo: bar" + +.. option:: --request-header-field-buffer=<SIZE> + + Set maximum buffer size for incoming HTTP request header + field list. This is the sum of header name and value in + bytes. If trailer fields exist, they are counted + towards this number. + + Default: ``64K`` + +.. option:: --max-request-header-fields=<N> + + Set maximum number of incoming HTTP request header + fields. If trailer fields exist, they are counted + towards this number. + + Default: ``100`` + +.. option:: --response-header-field-buffer=<SIZE> + + Set maximum buffer size for incoming HTTP response + header field list. This is the sum of header name and + value in bytes. If trailer fields exist, they are + counted towards this number. + + Default: ``64K`` + +.. option:: --max-response-header-fields=<N> + + Set maximum number of incoming HTTP response header + fields. If trailer fields exist, they are counted + towards this number. + + Default: ``500`` + +.. option:: --error-page=(<CODE>|*)=<PATH> + + Set file path to custom error page served when nghttpx + originally generates HTTP error status code <CODE>. + <CODE> must be greater than or equal to 400, and at most + 599. If "\*" is used instead of <CODE>, it matches all + HTTP status code. If error status code comes from + backend server, the custom error pages are not used. + +.. option:: --server-name=<NAME> + + Change server response header field value to <NAME>. + + Default: ``nghttpx`` + +.. option:: --no-server-rewrite + + Don't rewrite server header field in default mode. When + :option:`--http2-proxy` is used, these headers will not be altered + regardless of this option. + +.. option:: --redirect-https-port=<PORT> + + Specify the port number which appears in Location header + field when redirect to HTTPS URI is made due to + "redirect-if-not-tls" parameter in :option:`--backend` option. + + Default: ``443`` + +.. option:: --require-http-scheme + + Always require http or https scheme in HTTP request. It + also requires that https scheme must be used for an + encrypted connection. Otherwise, http scheme must be + used. This option is recommended for a server + deployment which directly faces clients and the services + it provides only require http or https scheme. + + +API +~~~ + +.. option:: --api-max-request-body=<SIZE> + + Set the maximum size of request body for API request. + + Default: ``32M`` + + +DNS +~~~ + +.. option:: --dns-cache-timeout=<DURATION> + + Set duration that cached DNS results remain valid. Note + that nghttpx caches the unsuccessful results as well. + + Default: ``10s`` + +.. option:: --dns-lookup-timeout=<DURATION> + + Set timeout that DNS server is given to respond to the + initial DNS query. For the 2nd and later queries, + server is given time based on this timeout, and it is + scaled linearly. + + Default: ``5s`` + +.. option:: --dns-max-try=<N> + + Set the number of DNS query before nghttpx gives up name + lookup. + + Default: ``2`` + +.. option:: --frontend-max-requests=<N> + + The number of requests that single frontend connection + can process. For HTTP/2, this is the number of streams + in one HTTP/2 connection. For HTTP/1, this is the + number of keep alive requests. This is hint to nghttpx, + and it may allow additional few requests. The default + value is unlimited. + + +Debug +~~~~~ + +.. option:: --frontend-http2-dump-request-header=<PATH> + + Dumps request headers received by HTTP/2 frontend to the + file denoted in <PATH>. The output is done in HTTP/1 + header field format and each header block is followed by + an empty line. This option is not thread safe and MUST + NOT be used with option :option:`-n`\<N>, where <N> >= 2. + +.. option:: --frontend-http2-dump-response-header=<PATH> + + Dumps response headers sent from HTTP/2 frontend to the + file denoted in <PATH>. The output is done in HTTP/1 + header field format and each header block is followed by + an empty line. This option is not thread safe and MUST + NOT be used with option :option:`-n`\<N>, where <N> >= 2. + +.. option:: -o, --frontend-frame-debug + + Print HTTP/2 frames in frontend to stderr. This option + is not thread safe and MUST NOT be used with option + :option:`-n`\=N, where N >= 2. + + +Process +~~~~~~~ + +.. option:: -D, --daemon + + Run in a background. If :option:`-D` is used, the current working + directory is changed to '*/*'. + +.. option:: --pid-file=<PATH> + + Set path to save PID of this program. + +.. option:: --user=<USER> + + Run this program as <USER>. This option is intended to + be used to drop root privileges. + +.. option:: --single-process + + Run this program in a single process mode for debugging + purpose. Without this option, nghttpx creates at least + 2 processes: main and worker processes. If this option + is used, main and worker are unified into a single + process. nghttpx still spawns additional process if + neverbleed is used. In the single process mode, the + signal handling feature is disabled. + +.. option:: --max-worker-processes=<N> + + The maximum number of worker processes. nghttpx spawns + new worker process when it reloads its configuration. + The previous worker process enters graceful termination + period and will terminate when it finishes handling the + existing connections. However, if reloading + configurations happen very frequently, the worker + processes might be piled up if they take a bit long time + to finish the existing connections. With this option, + if the number of worker processes exceeds the given + value, the oldest worker process is terminated + immediately. Specifying 0 means no limit and it is the + default behaviour. + +.. option:: --worker-process-grace-shutdown-period=<DURATION> + + Maximum period for a worker process to terminate + gracefully. When a worker process enters in graceful + shutdown period (e.g., when nghttpx reloads its + configuration) and it does not finish handling the + existing connections in the given period of time, it is + immediately terminated. Specifying 0 means no limit and + it is the default behaviour. + + +Scripting +~~~~~~~~~ + +.. option:: --mruby-file=<PATH> + + Set mruby script file + +.. option:: --ignore-per-pattern-mruby-error + + Ignore mruby compile error for per-pattern mruby script + file. If error occurred, it is treated as if no mruby + file were specified for the pattern. + + +HTTP/3 and QUIC +~~~~~~~~~~~~~~~ + +.. option:: --frontend-quic-idle-timeout=<DURATION> + + Specify an idle timeout for QUIC connection. + + Default: ``30s`` + +.. option:: --frontend-quic-debug-log + + Output QUIC debug log to */dev/stderr.* + +.. option:: --quic-bpf-program-file=<PATH> + + Specify a path to eBPF program file reuseport_kern.o to + direct an incoming QUIC UDP datagram to a correct + socket. + + Default: ``/usr/local/lib/nghttp2/reuseport_kern.o`` + +.. option:: --frontend-quic-early-data + + Enable early data on frontend QUIC connections. nghttpx + sends "Early-Data" header field to a backend server if a + request is received in early data and handshake has not + finished. All backend servers should deal with possibly + replayed requests. + +.. option:: --frontend-quic-qlog-dir=<DIR> + + Specify a directory where a qlog file is written for + frontend QUIC connections. A qlog file is created per + each QUIC connection. The file name is ISO8601 basic + format, followed by "-", server Source Connection ID and + ".sqlog". + +.. option:: --frontend-quic-require-token + + Require an address validation token for a frontend QUIC + connection. Server sends a token in Retry packet or + NEW_TOKEN frame in the previous connection. + +.. option:: --frontend-quic-congestion-controller=<CC> + + Specify a congestion controller algorithm for a frontend + QUIC connection. <CC> should be either "cubic" or + "bbr". + + Default: ``cubic`` + +.. option:: --frontend-quic-secret-file=<PATH> + + Path to file that contains secure random data to be used + as QUIC keying materials. It is used to derive keys for + encrypting tokens and Connection IDs. It is not used to + encrypt QUIC packets. Each line of this file must + contain exactly 136 bytes hex-encoded string (when + decoded the byte string is 68 bytes long). The first 2 + bits of decoded byte string are used to identify the + keying material. An empty line or a line which starts + '#' is ignored. The file can contain more than one + keying materials. Because the identifier is 2 bits, at + most 4 keying materials are read and the remaining data + is discarded. The first keying material in the file is + primarily used for encryption and decryption for new + connection. The other ones are used to decrypt data for + the existing connections. Specifying multiple keying + materials enables key rotation. Please note that key + rotation does not occur automatically. User should + update files or change options values and restart + nghttpx gracefully. If opening or reading given file + fails, all loaded keying materials are discarded and it + is treated as if none of this option is given. If this + option is not given or an error occurred while opening + or reading a file, a keying material is generated + internally on startup and reload. + +.. option:: --quic-server-id=<HEXSTRING> + + Specify server ID encoded in Connection ID to identify + this particular server instance. Connection ID is + encrypted and this part is not visible in public. It + must be 4 bytes long and must be encoded in hex string + (which is 8 bytes long). If this option is omitted, a + random server ID is generated on startup and + configuration reload. + +.. option:: --frontend-quic-initial-rtt=<DURATION> + + Specify the initial RTT of the frontend QUIC connection. + + Default: ``333ms`` + +.. option:: --no-quic-bpf + + Disable eBPF. + +.. option:: --frontend-http3-window-size=<SIZE> + + Sets the per-stream initial window size of HTTP/3 + frontend connection. + + Default: ``256K`` + +.. option:: --frontend-http3-connection-window-size=<SIZE> + + Sets the per-connection window size of HTTP/3 frontend + connection. + + Default: ``1M`` + +.. option:: --frontend-http3-max-window-size=<SIZE> + + Sets the maximum per-stream window size of HTTP/3 + frontend connection. The window size is adjusted based + on the receiving rate of stream data. The initial value + is the value specified by :option:`--frontend-http3-window-size` + and the window size grows up to <SIZE> bytes. + + Default: ``6M`` + +.. option:: --frontend-http3-max-connection-window-size=<SIZE> + + Sets the maximum per-connection window size of HTTP/3 + frontend connection. The window size is adjusted based + on the receiving rate of stream data. The initial value + is the value specified by + :option:`--frontend-http3-connection-window-size` and the window + size grows up to <SIZE> bytes. + + Default: ``8M`` + +.. option:: --frontend-http3-max-concurrent-streams=<N> + + Set the maximum number of the concurrent streams in one + frontend HTTP/3 connection. + + Default: ``100`` + + +Misc +~~~~ + +.. option:: --conf=<PATH> + + Load configuration from <PATH>. Please note that + nghttpx always tries to read the default configuration + file if :option:`--conf` is not given. + + Default: ``/etc/nghttpx/nghttpx.conf`` + +.. option:: --include=<PATH> + + Load additional configurations from <PATH>. File <PATH> + is read when configuration parser encountered this + option. This option can be used multiple times, or even + recursively. + +.. option:: -v, --version + + Print version and exit. + +.. option:: -h, --help + + Print this help and exit. + + + +The <SIZE> argument is an integer and an optional unit (e.g., 10K is +10 * 1024). Units are K, M and G (powers of 1024). + +The <DURATION> argument is an integer and an optional unit (e.g., 1s +is 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms +(hours, minutes, seconds and milliseconds, respectively). If a unit +is omitted, a second is used as unit. + +FILES +----- + +*/etc/nghttpx/nghttpx.conf* + The default configuration file path nghttpx searches at startup. + The configuration file path can be changed using :option:`--conf` + option. + + Those lines which are staring ``#`` are treated as comment. + + The option name in the configuration file is the long command-line + option name with leading ``--`` stripped (e.g., ``frontend``). Put + ``=`` between option name and value. Don't put extra leading or + trailing spaces. + + When specifying arguments including characters which have special + meaning to a shell, we usually use quotes so that shell does not + interpret them. When writing this configuration file, quotes for + this purpose must not be used. For example, specify additional + request header field, do this: + + .. code-block:: text + + add-request-header=foo: bar + + instead of: + + .. code-block:: text + + add-request-header="foo: bar" + + The options which do not take argument in the command-line *take* + argument in the configuration file. Specify ``yes`` as an argument + (e.g., ``http2-proxy=yes``). If other string is given, it is + ignored. + + To specify private key and certificate file which are given as + positional arguments in command-line, use ``private-key-file`` and + ``certificate-file``. + + :option:`--conf` option cannot be used in the configuration file and + will be ignored if specified. + +Error log + Error log is written to stderr by default. It can be configured + using :option:`--errorlog-file`. The format of log message is as + follows: + + <datetime> <main-pid> <current-pid> <thread-id> <level> (<filename>:<line>) <msg> + + <datetime> + It is a combination of date and time when the log is written. It + is in ISO 8601 format. + + <main-pid> + It is a main process ID. + + <current-pid> + It is a process ID which writes this log. + + <thread-id> + It is a thread ID which writes this log. It would be unique + within <current-pid>. + + <filename> and <line> + They are source file name, and line number which produce this log. + + <msg> + It is a log message body. + +SIGNALS +------- + +SIGQUIT + Shutdown gracefully. First accept pending connections and stop + accepting connection. After all connections are handled, nghttpx + exits. + +SIGHUP + Reload configuration file given in :option:`--conf`. + +SIGUSR1 + Reopen log files. + +SIGUSR2 + + Fork and execute nghttpx. It will execute the binary in the same + path with same command-line arguments and environment variables. As + of nghttpx version 1.20.0, the new main process sends SIGQUIT to the + original main process when it is ready to serve requests. For the + earlier versions of nghttpx, user has to send SIGQUIT to the + original main process. + + The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former + is usually used to execute new binary, and the main process is newly + spawned. On the other hand, the latter just reloads configuration + file, and the same main process continues to exist. + +.. note:: + + nghttpx consists of multiple processes: one process for processing + these signals, and another one for processing requests. The former + spawns the latter. The former is called main process, and the + latter is called worker process. If neverbleed is enabled, the + worker process spawns neverbleed daemon process which does RSA key + processing. The above signal must be sent to the main process. If + the other processes received one of them, it is ignored. This + behaviour of these processes may change in the future release. In + other words, in the future release, the processes other than main + process may terminate upon the reception of these signals. + Therefore these signals should not be sent to the processes other + than main process. + +SERVER PUSH +----------- + +nghttpx supports HTTP/2 server push in default mode with Link header +field. nghttpx looks for Link header field (`RFC 5988 +<http://tools.ietf.org/html/rfc5988>`_) in response headers from +backend server and extracts URI-reference with parameter +``rel=preload`` (see `preload +<http://w3c.github.io/preload/#interoperability-with-http-link-header>`_) +and pushes those URIs to the frontend client. Here is a sample Link +header field to initiate server push: + +.. code-block:: text + + Link: </fonts/font.woff>; rel=preload + Link: </css/theme.css>; rel=preload + +Currently, the following restriction is applied for server push: + +1. The associated stream must have method "GET" or "POST". The + associated stream's status code must be 200. + +This limitation may be loosened in the future release. + +nghttpx also supports server push if both frontend and backend are +HTTP/2 in default mode. In this case, in addition to server push via +Link header field, server push from backend is forwarded to frontend +HTTP/2 session. + +HTTP/2 server push will be disabled if :option:`--http2-proxy` is +used. + +UNIX DOMAIN SOCKET +------------------ + +nghttpx supports UNIX domain socket with a filename for both frontend +and backend connections. + +Please note that current nghttpx implementation does not delete a +socket with a filename. And on start up, if nghttpx detects that the +specified socket already exists in the file system, nghttpx first +deletes it. However, if SIGUSR2 is used to execute new binary and +both old and new configurations use same filename, new binary does not +delete the socket and continues to use it. + +OCSP STAPLING +------------- + +OCSP query is done using external Python script +``fetch-ocsp-response``, which has been originally developed in Perl +as part of h2o project (https://github.com/h2o/h2o), and was +translated into Python. + +The script file is usually installed under +``$(prefix)/share/nghttp2/`` directory. The actual path to script can +be customized using :option:`--fetch-ocsp-response-file` option. + +If OCSP query is failed, previous OCSP response, if any, is continued +to be used. + +:option:`--fetch-ocsp-response-file` option provides wide range of +possibility to manage OCSP response. It can take an arbitrary script +or executable. The requirement is that it supports the command-line +interface of ``fetch-ocsp-response`` script, and it must return a +valid DER encoded OCSP response on success. It must return exit code +0 on success, and 75 for temporary error, and the other error code for +generic failure. For large cluster of servers, it is not efficient +for each server to perform OCSP query using ``fetch-ocsp-response``. +Instead, you can retrieve OCSP response in some way, and store it in a +disk or a shared database. Then specify a program in +:option:`--fetch-ocsp-response-file` to fetch it from those stores. +This could provide a way to share the OCSP response between fleet of +servers, and also any OCSP query strategy can be applied which may be +beyond the ability of nghttpx itself or ``fetch-ocsp-response`` +script. + +TLS SESSION RESUMPTION +---------------------- + +nghttpx supports TLS session resumption through both session ID and +session ticket. + +SESSION ID RESUMPTION +~~~~~~~~~~~~~~~~~~~~~ + +By default, session ID is shared by all worker threads. + +If :option:`--tls-session-cache-memcached` is given, nghttpx will +insert serialized session data to memcached with +``nghttpx:tls-session-cache:`` + lowercase hex string of session ID +as a memcached entry key, with expiry time 12 hours. Session timeout +is set to 12 hours. + +By default, connections to memcached server are not encrypted. To +enable encryption, use ``tls`` keyword in +:option:`--tls-session-cache-memcached` option. + +TLS SESSION TICKET RESUMPTION +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, session ticket is shared by all worker threads. The +automatic key rotation is also enabled by default. Every an hour, new +encryption key is generated, and previous encryption key becomes +decryption only key. We set session timeout to 12 hours, and thus we +keep at most 12 keys. + +If :option:`--tls-ticket-key-memcached` is given, encryption keys are +retrieved from memcached. nghttpx just reads keys from memcached; one +has to deploy key generator program to update keys frequently (e.g., +every 1 hour). The example key generator tlsticketupdate.go is +available under contrib directory in nghttp2 archive. The memcached +entry key is ``nghttpx:tls-ticket-key``. The data format stored in +memcached is the binary format described below: + +.. code-block:: text + + +--------------+-------+----------------+ + | VERSION (4) |LEN (2)|KEY(48 or 80) ... + +--------------+-------+----------------+ + ^ | + | | + +------------------------+ + (LEN, KEY) pair can be repeated + +All numbers in the above figure is bytes. All integer fields are +network byte order. + +First 4 bytes integer VERSION field, which must be 1. The 2 bytes +integer LEN field gives the length of following KEY field, which +contains key. If :option:`--tls-ticket-key-cipher`\=aes-128-cbc is +used, LEN must be 48. If +:option:`--tls-ticket-key-cipher`\=aes-256-cbc is used, LEN must be +80. LEN and KEY pair can be repeated multiple times to store multiple +keys. The key appeared first is used as encryption key. All the +remaining keys are used as decryption only. + +By default, connections to memcached server are not encrypted. To +enable encryption, use ``tls`` keyword in +:option:`--tls-ticket-key-memcached` option. + +If :option:`--tls-ticket-key-file` is given, encryption key is read +from the given file. In this case, nghttpx does not rotate key +automatically. To rotate key, one has to restart nghttpx (see +SIGNALS). + +CERTIFICATE TRANSPARENCY +------------------------ + +nghttpx supports TLS ``signed_certificate_timestamp`` extension (`RFC +6962 <https://tools.ietf.org/html/rfc6962>`_). The relevant options +are :option:`--tls-sct-dir` and ``sct-dir`` parameter in +:option:`--subcert`. They takes a directory, and nghttpx reads all +files whose extension is ``.sct`` under the directory. The ``*.sct`` +files are encoded as ``SignedCertificateTimestamp`` struct described +in `section 3.2 of RFC 69662 +<https://tools.ietf.org/html/rfc6962#section-3.2>`_. This format is +the same one used by `nginx-ct +<https://github.com/grahamedgecombe/nginx-ct>`_ and `mod_ssl_ct +<https://httpd.apache.org/docs/trunk/mod/mod_ssl_ct.html>`_. +`ct-submit <https://github.com/grahamedgecombe/ct-submit>`_ can be +used to submit certificates to log servers, and obtain the +``SignedCertificateTimestamp`` struct which can be used with nghttpx. + +MRUBY SCRIPTING +--------------- + +.. warning:: + + The current mruby extension API is experimental and not frozen. The + API is subject to change in the future release. + +.. warning:: + + Almost all string value returned from method, or attribute is a + fresh new mruby string, which involves memory allocation, and + copies. Therefore, it is strongly recommended to store a return + value in a local variable, and use it, instead of calling method or + accessing attribute repeatedly. + +nghttpx allows users to extend its capability using mruby scripts. +nghttpx has 2 hook points to execute mruby script: request phase and +response phase. The request phase hook is invoked after all request +header fields are received from client. The response phase hook is +invoked after all response header fields are received from backend +server. These hooks allows users to modify header fields, or common +HTTP variables, like authority or request path, and even return custom +response without forwarding request to backend servers. + +There are 2 levels of mruby script invocations: global and +per-pattern. The global mruby script is set by :option:`--mruby-file` +option and is called for all requests. The per-pattern mruby script +is set by "mruby" parameter in :option:`-b` option. It is invoked for +a request which matches the particular pattern. The order of hook +invocation is: global request phase hook, per-pattern request phase +hook, per-pattern response phase hook, and finally global response +phase hook. If a hook returns a response, any later hooks are not +invoked. The global request hook is invoked before the pattern +matching is made and changing request path may affect the pattern +matching. + +Please note that request and response hooks of per-pattern mruby +script for a single request might not come from the same script. This +might happen after a request hook is executed, backend failed for some +reason, and at the same time, backend configuration is replaced by API +request, and then the request uses new configuration on retry. The +response hook from new configuration, if it is specified, will be +invoked. + +The all mruby script will be evaluated once per thread on startup, and +it must instantiate object and evaluate it as the return value (e.g., +``App.new``). This object is called app object. If app object +defines ``on_req`` method, it is called with :rb:class:`Nghttpx::Env` +object on request hook. Similarly, if app object defines ``on_resp`` +method, it is called with :rb:class:`Nghttpx::Env` object on response +hook. For each method invocation, user can can access +:rb:class:`Nghttpx::Request` and :rb:class:`Nghttpx::Response` objects +via :rb:attr:`Nghttpx::Env#req` and :rb:attr:`Nghttpx::Env#resp` +respectively. + +.. rb:module:: Nghttpx + +.. rb:const:: REQUEST_PHASE + + Constant to represent request phase. + +.. rb:const:: RESPONSE_PHASE + + Constant to represent response phase. + +.. rb:class:: Env + + Object to represent current request specific context. + + .. rb:attr_reader:: req + + Return :rb:class:`Request` object. + + .. rb:attr_reader:: resp + + Return :rb:class:`Response` object. + + .. rb:attr_reader:: ctx + + Return Ruby hash object. It persists until request finishes. + So values set in request phase hook can be retrieved in + response phase hook. + + .. rb:attr_reader:: phase + + Return the current phase. + + .. rb:attr_reader:: remote_addr + + Return IP address of a remote client. If connection is made + via UNIX domain socket, this returns the string "localhost". + + .. rb:attr_reader:: server_addr + + Return address of server that accepted the connection. This + is a string which specified in :option:`--frontend` option, + excluding port number, and not a resolved IP address. For + UNIX domain socket, this is a path to UNIX domain socket. + + .. rb:attr_reader:: server_port + + Return port number of the server frontend which accepted the + connection from client. + + .. rb:attr_reader:: tls_used + + Return true if TLS is used on the connection. + + .. rb:attr_reader:: tls_sni + + Return the TLS SNI value which client sent in this connection. + + .. rb:attr_reader:: tls_client_fingerprint_sha256 + + Return the SHA-256 fingerprint of a client certificate. + + .. rb:attr_reader:: tls_client_fingerprint_sha1 + + Return the SHA-1 fingerprint of a client certificate. + + .. rb:attr_reader:: tls_client_issuer_name + + Return the issuer name of a client certificate. + + .. rb:attr_reader:: tls_client_subject_name + + Return the subject name of a client certificate. + + .. rb:attr_reader:: tls_client_serial + + Return the serial number of a client certificate. + + .. rb:attr_reader:: tls_client_not_before + + Return the start date of a client certificate in seconds since + the epoch. + + .. rb:attr_reader:: tls_client_not_after + + Return the end date of a client certificate in seconds since + the epoch. + + .. rb:attr_reader:: tls_cipher + + Return a TLS cipher negotiated in this connection. + + .. rb:attr_reader:: tls_protocol + + Return a TLS protocol version negotiated in this connection. + + .. rb:attr_reader:: tls_session_id + + Return a session ID for this connection in hex string. + + .. rb:attr_reader:: tls_session_reused + + Return true if, and only if a SSL/TLS session is reused. + + .. rb:attr_reader:: alpn + + Return ALPN identifier negotiated in this connection. + + .. rb:attr_reader:: tls_handshake_finished + + Return true if SSL/TLS handshake has finished. If it returns + false in the request phase hook, the request is received in + TLSv1.3 early data (0-RTT) and might be vulnerable to the + replay attack. nghttpx will send Early-Data header field to + backend servers to indicate this. + +.. rb:class:: Request + + Object to represent request from client. The modification to + Request object is allowed only in request phase hook. + + .. rb:attr_reader:: http_version_major + + Return HTTP major version. + + .. rb:attr_reader:: http_version_minor + + Return HTTP minor version. + + .. rb:attr_accessor:: method + + HTTP method. On assignment, copy of given value is assigned. + We don't accept arbitrary method name. We will document them + later, but well known methods, like GET, PUT and POST, are all + supported. + + .. rb:attr_accessor:: authority + + Authority (i.e., example.org), including optional port + component . On assignment, copy of given value is assigned. + + .. rb:attr_accessor:: scheme + + Scheme (i.e., http, https). On assignment, copy of given + value is assigned. + + .. rb:attr_accessor:: path + + Request path, including query component (i.e., /index.html). + On assignment, copy of given value is assigned. The path does + not include authority component of URI. This may include + query component. nghttpx makes certain normalization for + path. It decodes percent-encoding for unreserved characters + (see https://tools.ietf.org/html/rfc3986#section-2.3), and + resolves ".." and ".". But it may leave characters which + should be percent-encoded as is. So be careful when comparing + path against desired string. + + .. rb:attr_reader:: headers + + Return Ruby hash containing copy of request header fields. + Changing values in returned hash does not change request + header fields actually used in request processing. Use + :rb:meth:`Nghttpx::Request#add_header` or + :rb:meth:`Nghttpx::Request#set_header` to change request + header fields. + + .. rb:method:: add_header(key, value) + + Add header entry associated with key. The value can be single + string or array of string. It does not replace any existing + values associated with key. + + .. rb:method:: set_header(key, value) + + Set header entry associated with key. The value can be single + string or array of string. It replaces any existing values + associated with key. + + .. rb:method:: clear_headers + + Clear all existing request header fields. + + .. rb:method:: push(uri) + + Initiate to push resource identified by *uri*. Only HTTP/2 + protocol supports this feature. For the other protocols, this + method is noop. *uri* can be absolute URI, absolute path or + relative path to the current request. For absolute or + relative path, scheme and authority are inherited from the + current request. Currently, method is always GET. nghttpx + will issue request to backend servers to fulfill this request. + The request and response phase hooks will be called for pushed + resource as well. + +.. rb:class:: Response + + Object to represent response from backend server. + + .. rb:attr_reader:: http_version_major + + Return HTTP major version. + + .. rb:attr_reader:: http_version_minor + + Return HTTP minor version. + + .. rb:attr_accessor:: status + + HTTP status code. It must be in the range [200, 999], + inclusive. The non-final status code is not supported in + mruby scripting at the moment. + + .. rb:attr_reader:: headers + + Return Ruby hash containing copy of response header fields. + Changing values in returned hash does not change response + header fields actually used in response processing. Use + :rb:meth:`Nghttpx::Response#add_header` or + :rb:meth:`Nghttpx::Response#set_header` to change response + header fields. + + .. rb:method:: add_header(key, value) + + Add header entry associated with key. The value can be single + string or array of string. It does not replace any existing + values associated with key. + + .. rb:method:: set_header(key, value) + + Set header entry associated with key. The value can be single + string or array of string. It replaces any existing values + associated with key. + + .. rb:method:: clear_headers + + Clear all existing response header fields. + + .. rb:method:: return(body) + + Return custom response *body* to a client. When this method + is called in request phase hook, the request is not forwarded + to the backend, and response phase hook for this request will + not be invoked. When this method is called in response phase + hook, response from backend server is canceled and discarded. + The status code and response header fields should be set + before using this method. To set status code, use + :rb:attr:`Nghttpx::Response#status`. If status code is not + set, 200 is used. To set response header fields, + :rb:meth:`Nghttpx::Response#add_header` and + :rb:meth:`Nghttpx::Response#set_header`. When this method is + invoked in response phase hook, the response headers are + filled with the ones received from backend server. To send + completely custom header fields, first call + :rb:meth:`Nghttpx::Response#clear_headers` to erase all + existing header fields, and then add required header fields. + It is an error to call this method twice for a given request. + + .. rb:method:: send_info(status, headers) + + Send non-final (informational) response to a client. *status* + must be in the range [100, 199], inclusive. *headers* is a + hash containing response header fields. Its key must be a + string, and the associated value must be either string or + array of strings. Since this is not a final response, even if + this method is invoked, request is still forwarded to a + backend unless :rb:meth:`Nghttpx::Response#return` is called. + This method can be called multiple times. It cannot be called + after :rb:meth:`Nghttpx::Response#return` is called. + +MRUBY EXAMPLES +~~~~~~~~~~~~~~ + +Modify request path: + +.. code-block:: ruby + + class App + def on_req(env) + env.req.path = "/apps#{env.req.path}" + end + end + + App.new + +Don't forget to instantiate and evaluate object at the last line. + +Restrict permission of viewing a content to a specific client +addresses: + +.. code-block:: ruby + + class App + def on_req(env) + allowed_clients = ["127.0.0.1", "::1"] + + if env.req.path.start_with?("/log/") && + !allowed_clients.include?(env.remote_addr) then + env.resp.status = 404 + env.resp.return "permission denied" + end + end + end + + App.new + +API ENDPOINTS +------------- + +nghttpx exposes API endpoints to manipulate it via HTTP based API. By +default, API endpoint is disabled. To enable it, add a dedicated +frontend for API using :option:`--frontend` option with "api" +parameter. All requests which come from this frontend address, will +be treated as API request. + +The response is normally JSON dictionary, and at least includes the +following keys: + +status + The status of the request processing. The following values are + defined: + + Success + The request was successful. + + Failure + The request was failed. No change has been made. + +code + HTTP status code + +Additionally, depending on the API endpoint, ``data`` key may be +present, and its value contains the API endpoint specific data. + +We wrote "normally", since nghttpx may return ordinal HTML response in +some cases where the error has occurred before reaching API endpoint +(e.g., header field is too large). + +The following section describes available API endpoints. + +POST /api/v1beta1/backendconfig +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This API replaces the current backend server settings with the +requested ones. The request method should be POST, but PUT is also +acceptable. The request body must be nghttpx configuration file +format. For configuration file format, see `FILES`_ section. The +line separator inside the request body must be single LF (0x0A). +Currently, only :option:`backend <--backend>` option is parsed, the +others are simply ignored. The semantics of this API is replace the +current backend with the backend options in request body. Describe +the desired set of backend severs, and nghttpx makes it happen. If +there is no :option:`backend <--backend>` option is found in request +body, the current set of backend is replaced with the :option:`backend +<--backend>` option's default value, which is ``127.0.0.1,80``. + +The replacement is done instantly without breaking existing +connections or requests. It also avoids any process creation as is +the case with hot swapping with signals. + +The one limitation is that only numeric IP address is allowed in +:option:`backend <--backend>` in request body unless "dns" parameter +is used while non numeric hostname is allowed in command-line or +configuration file is read using :option:`--conf`. + +GET /api/v1beta1/configrevision +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This API returns configuration revision of the current nghttpx. The +configuration revision is opaque string, and it changes after each +reloading by SIGHUP. With this API, an external application knows +that whether nghttpx has finished reloading its configuration by +comparing the configuration revisions between before and after +reloading. It is recommended to disable persistent (keep-alive) +connection for this purpose in order to avoid to send a request using +the reused connection which may bound to an old process. + +This API returns response including ``data`` key. Its value is JSON +object, and it contains at least the following key: + +configRevision + The configuration revision of the current nghttpx + + +SEE ALSO +-------- + +:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`h2load(1)` |