DESCRIPTION
-----------
-A reverse proxy for HTTP/2, and HTTP/1.
+A reverse proxy for HTTP/3, HTTP/2, and HTTP/1.
.. describe:: <PRIVATE_KEY>
"affinity=<METHOD>", "dns", "redirect-if-not-tls",
"upgrade-scheme", "mruby=<PATH>",
"read-timeout=<DURATION>", "write-timeout=<DURATION>",
- "group=<GROUP>", "group-weight=<N>", and "weight=<N>".
- 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.
+ "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
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. Since ";" has special
- meaning in shell, the option value must be quoted.
+ 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``
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``
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: ``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: ``1s``
-.. option:: --no-http2-cipher-black-list
+.. option:: --no-http2-cipher-block-list
- Allow black listed cipher suite on frontend HTTP/2
+ 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 black list.
+ complete HTTP/2 cipher suites block list.
-.. option:: --client-no-http2-cipher-black-list
+.. option:: --client-no-http2-cipher-block-list
- Allow black listed cipher suite on backend HTTP/2
+ 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 black list.
+ complete HTTP/2 cipher suites block list.
.. option:: --tls-sct-dir=<DIR>
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 black listed by
+ 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-black-list` option.
+ consider to use :option:`--no-http2-cipher-block-list` option.
But be aware its implications.
.. option:: --client-psk-secrets=<PATH>
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 black listed by
+ 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-black-list`
+ consider to use :option:`--client-no-http2-cipher-block-list`
option. But be aware its implications.
.. option:: --tls-no-postpone-early-data
- By default, 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.
+ 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>
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}).
mode. When :option:`--http2-proxy` is used, these headers will
not be altered regardless of this option.
-.. option:: --altsvc=<PROTOID,PORT[,HOST,[ORIGIN]]>
+.. option:: --altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>
Specify protocol ID, port, host and origin of
- alternative service. <HOST> and <ORIGIN> are optional.
- 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
+ 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>
Run this program in a single process mode for debugging
purpose. Without this option, nghttpx creates at least
- 2 processes: master and worker processes. If this
- option is used, master and worker are unified into a
- single process. nghttpx still spawns additional process
- if neverbleed is used. In the single process mode, the
+ 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
~~~~~~~~~
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
+ ".qlog".
+
+.. 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
~~~~
using :option:`--errorlog-file`. The format of log message is as
follows:
- <datetime> <master-pid> <current-pid> <thread-id> <level> (<filename>:<line>) <msg>
+ <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.
- <master-pid>
- It is a master process ID.
+ <main-pid>
+ It is a main process ID.
<current-pid>
It is a process ID which writes this log.
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 master process sends SIGQUIT to
- the original master process when it is ready to serve requests. For
- the earlier versions of nghttpx, user has to send SIGQUIT to the
- original master process.
+ 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 master process is
- newly spawned. On the other hand, the latter just reloads
- configuration file, and the same master process continues to exist.
+ 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 master process, and the
+ 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 master process.
- If the other processes received one of them, it is ignored. This
+ 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 master
+ 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 master process.
+ than main process.
SERVER PUSH
-----------
projects / platform / upstream / nghttp2.git / blobdiff