2014-07-08 17:38:43 +02:00
|
|
|
|
2015-05-12 17:44:37 +02:00
|
|
|
.. GENERATED by help2rst.py. DO NOT EDIT DIRECTLY.
|
|
|
|
|
2015-04-17 16:14:23 +02:00
|
|
|
.. program:: nghttpx
|
|
|
|
|
2014-07-08 17:38:43 +02:00
|
|
|
nghttpx(1)
|
|
|
|
==========
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
--------
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2014-07-08 17:38:43 +02:00
|
|
|
**nghttpx** [OPTIONS]... [<PRIVATE_KEY> <CERT>]
|
|
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
-----------
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2014-07-08 17:38:43 +02:00
|
|
|
A reverse proxy for HTTP/2, HTTP/1 and SPDY.
|
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
.. describe:: <PRIVATE_KEY>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
|
|
|
|
Set path to server's private key. Required unless :option:`-p`\,
|
|
|
|
:option:`--client` or :option:`\--frontend-no-tls` are given.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
.. describe:: <CERT>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set path to server's certificate. Required unless :option:`-p`\,
|
2015-03-30 17:23:12 +02:00
|
|
|
:option:`--client` or :option:`\--frontend-no-tls` are given. To make OCSP
|
|
|
|
stapling work, this must be absolute path.
|
2015-01-15 16:10:16 +01:00
|
|
|
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
OPTIONS
|
|
|
|
-------
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
The options are categorized into several groups.
|
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
Connections
|
|
|
|
~~~~~~~~~~~
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-07-14 17:01:04 +02:00
|
|
|
.. option:: -b, --backend=(<HOST>,<PORT>|unix:<PATH>)[;<PATTERN>[:...]]
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-03-14 10:52:50 +01:00
|
|
|
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
|
2015-07-11 05:45:23 +02:00
|
|
|
with "unix:" (e.g., unix:/var/run/backend.sock).
|
|
|
|
|
|
|
|
Optionally, if <PATTERN>s are given, the backend address
|
2015-07-12 16:26:45 +02:00
|
|
|
is only used if request matches the pattern. If :option:`-s` or
|
|
|
|
:option:`-p` is used, <PATTERN>s are ignored. The pattern
|
|
|
|
matching is closely designed to ServeMux in net/http
|
|
|
|
package of Go programming language. <PATTERN> consists
|
2015-07-14 17:01:04 +02:00
|
|
|
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 exact match against the 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/").
|
|
|
|
|
|
|
|
Patterns with host take precedence over patterns with
|
|
|
|
just path. Then, longer patterns take precedence over
|
2015-07-12 16:26:45 +02:00
|
|
|
shorter ones, breaking a tie by the order of the
|
|
|
|
appearance in the configuration.
|
2015-07-11 05:45:23 +02:00
|
|
|
|
|
|
|
If <PATTERN> is omitted, "*/*" is used as pattern, which
|
2015-07-14 17:01:04 +02:00
|
|
|
matches all request paths (catch-all pattern). The
|
|
|
|
catch-all backend must be given.
|
2015-07-11 05:45:23 +02:00
|
|
|
|
|
|
|
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'
|
2015-07-14 17:01:04 +02:00
|
|
|
and :option:`-b`\'127.0.0.1,8080;www.nghttp2.org'.
|
2015-07-11 05:45:23 +02:00
|
|
|
|
|
|
|
The backend addresses sharing same <PATTERN> are grouped
|
2015-07-14 17:01:04 +02:00
|
|
|
together forming load balancing group.
|
|
|
|
|
|
|
|
Since ";" and ":" are used as delimiter, <PATTERN> must
|
|
|
|
not contain these characters. Since ";" has special
|
|
|
|
meaning in shell, the option value must be quoted.
|
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``127.0.0.1,80``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-07-14 17:01:04 +02:00
|
|
|
.. option:: -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set frontend host and port. If <HOST> is '\*', it
|
2015-02-22 10:02:57 +01:00
|
|
|
assumes all addresses including both IPv4 and IPv6.
|
|
|
|
UNIX domain socket can be specified by prefixing path
|
2015-02-22 10:10:55 +01:00
|
|
|
name with "unix:" (e.g., unix:/var/run/nghttpx.sock)
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``*,3000``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: --backlog=<N>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set listen backlog size.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Default: ``512``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --backend-ipv4
|
|
|
|
|
|
|
|
Resolve backend hostname to IPv4 address only.
|
|
|
|
|
|
|
|
.. option:: --backend-ipv6
|
|
|
|
|
|
|
|
Resolve backend hostname to IPv6 address only.
|
|
|
|
|
2014-08-29 17:15:31 +02:00
|
|
|
.. option:: --backend-http-proxy-uri=<URI>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
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
|
2014-08-29 17:15:31 +02:00
|
|
|
:option:`--backend-write-timeout` options.
|
|
|
|
|
2015-09-12 15:51:40 +02:00
|
|
|
.. option:: --accept-proxy-protocol
|
|
|
|
|
|
|
|
Accept PROXY protocol version 1 on frontend connection.
|
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
Performance
|
|
|
|
~~~~~~~~~~~
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: -n, --workers=<N>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
Set the number of worker threads.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``1``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: --read-rate=<SIZE>
|
2014-08-29 17:15:31 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum average read rate on frontend connection.
|
|
|
|
Setting 0 to this option means read rate is unlimited.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
2014-08-29 17:15:31 +02:00
|
|
|
|
|
|
|
.. option:: --read-burst=<SIZE>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum read burst size on frontend connection.
|
|
|
|
Setting 0 to this option means read burst size is
|
|
|
|
unlimited.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
2014-08-29 17:15:31 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: --write-rate=<SIZE>
|
2014-08-29 17:15:31 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum average write rate on frontend connection.
|
|
|
|
Setting 0 to this option means write rate is unlimited.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
2014-08-29 17:15:31 +02:00
|
|
|
|
|
|
|
.. option:: --write-burst=<SIZE>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum write burst size on frontend connection.
|
|
|
|
Setting 0 to this option means write burst size is
|
|
|
|
unlimited.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
2014-08-29 17:15:31 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: --worker-read-rate=<SIZE>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum average read rate on frontend connection per
|
|
|
|
worker. Setting 0 to this option means read rate is
|
|
|
|
unlimited. Not implemented yet.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --worker-read-burst=<SIZE>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum read burst size on frontend connection per
|
|
|
|
worker. Setting 0 to this option means read burst size
|
|
|
|
is unlimited. Not implemented yet.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: --worker-write-rate=<SIZE>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum average write rate on frontend connection
|
|
|
|
per worker. Setting 0 to this option means write rate
|
|
|
|
is unlimited. Not implemented yet.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --worker-write-burst=<SIZE>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum write burst size on frontend connection per
|
|
|
|
worker. Setting 0 to this option means write burst size
|
|
|
|
is unlimited. Not implemented yet.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: --worker-frontend-connections=<N>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum number of simultaneous connections frontend
|
|
|
|
accepts. Setting 0 means unlimited.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-03-14 10:52:50 +01:00
|
|
|
.. option:: --backend-http2-connections-per-worker=<N>
|
|
|
|
|
2015-07-12 16:26:45 +02:00
|
|
|
Set maximum number of backend HTTP/2 physical
|
|
|
|
connections per worker. If pattern is used in :option:`-b`
|
|
|
|
option, this limit is applied to each pattern group (in
|
|
|
|
other words, each pattern group can have maximum <N>
|
|
|
|
HTTP/2 connections). The default value is 0, which
|
|
|
|
means that the value is adjusted to the number of
|
|
|
|
backend addresses. If pattern is used, this adjustment
|
|
|
|
is done for each pattern group.
|
2015-03-14 10:52:50 +01:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: --backend-http1-connections-per-host=<N>
|
2014-08-16 15:54:15 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum number of backend concurrent HTTP/1
|
2015-06-22 17:50:35 +02:00
|
|
|
connections per origin host. This option is meaningful
|
|
|
|
when :option:`-s` option is used. The origin host is determined
|
2015-11-09 03:40:35 +01:00
|
|
|
by authority portion of request URI (or :authority
|
2015-06-22 17:50:35 +02:00
|
|
|
header field for HTTP/2). To limit the number of
|
|
|
|
connections per frontend for default mode, use
|
2015-01-09 16:37:42 +01:00
|
|
|
:option:`--backend-http1-connections-per-frontend`\.
|
|
|
|
|
|
|
|
Default: ``8``
|
2014-08-16 15:54:15 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: --backend-http1-connections-per-frontend=<N>
|
2015-01-06 17:40:55 +01:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum number of backend concurrent HTTP/1
|
|
|
|
connections per frontend. This option is only used for
|
|
|
|
default mode. 0 means unlimited. To limit the number
|
|
|
|
of connections per host for HTTP/2 or SPDY proxy mode
|
|
|
|
(-s option), use :option:`--backend-http1-connections-per-host`\.
|
2015-01-06 17:40:55 +01:00
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
Default: ``0``
|
|
|
|
|
2015-01-11 09:34:43 +01:00
|
|
|
.. option:: --rlimit-nofile=<N>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set maximum number of open files (RLIMIT_NOFILE) to <N>.
|
|
|
|
If 0 is given, nghttpx does not set the limit.
|
2015-01-11 09:34:43 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. 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.
|
|
|
|
|
2015-01-25 13:49:12 +01:00
|
|
|
Default: ``16K``
|
2015-01-15 16:10:16 +01:00
|
|
|
|
2015-10-19 17:22:03 +02:00
|
|
|
.. 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``
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
Timeout
|
|
|
|
~~~~~~~
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
.. option:: --frontend-http2-read-timeout=<DURATION>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Specify read timeout for HTTP/2 and SPDY frontend
|
2014-07-08 17:38:43 +02:00
|
|
|
connection.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-03-30 17:23:12 +02:00
|
|
|
Default: ``3m``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
.. option:: --frontend-read-timeout=<DURATION>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Specify read timeout for HTTP/1.1 frontend connection.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-10-19 17:22:03 +02:00
|
|
|
Default: ``1m``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
.. option:: --frontend-write-timeout=<DURATION>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Specify write timeout for all frontend connections.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
Default: ``30s``
|
2014-08-16 15:54:15 +02:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
.. option:: --stream-read-timeout=<DURATION>
|
2014-08-16 15:54:15 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Specify read timeout for HTTP/2 and SPDY streams. 0
|
|
|
|
means no timeout.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
2014-08-16 15:54:15 +02:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
.. option:: --stream-write-timeout=<DURATION>
|
2014-08-16 15:54:15 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Specify write timeout for HTTP/2 and SPDY streams. 0
|
|
|
|
means no timeout.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``0``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
.. option:: --backend-read-timeout=<DURATION>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
Specify read timeout for backend connection.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-10-19 17:22:03 +02:00
|
|
|
Default: ``1m``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
.. option:: --backend-write-timeout=<DURATION>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
Specify write timeout for backend connection.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
Default: ``30s``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
.. option:: --backend-keep-alive-timeout=<DURATION>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Specify keep-alive timeout for backend connection.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
Default: ``2s``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
.. option:: --listener-disable-timeout=<DURATION>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
After accepting connection failed, connection listener
|
2015-01-29 15:29:52 +01:00
|
|
|
is disabled for a given amount of time. Specifying 0
|
2015-01-15 16:10:16 +01:00
|
|
|
disables this feature.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
Default: ``0``
|
|
|
|
|
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
SSL/TLS
|
|
|
|
~~~~~~~
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --ciphers=<SUITE>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set allowed cipher list. The format of the string is
|
|
|
|
described in OpenSSL ciphers(1).
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: -k, --insecure
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Don't verify backend server's certificate if :option:`-p`\,
|
|
|
|
:option:`--client` or :option:`\--http2-bridge` are given and
|
2014-07-08 17:38:43 +02:00
|
|
|
:option:`--backend-no-tls` is not given.
|
|
|
|
|
|
|
|
.. option:: --cacert=<PATH>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set path to trusted CA certificate file if :option:`-p`\, :option:`--client`
|
|
|
|
or :option:`--http2-bridge` are given and :option:`\--backend-no-tls` is not
|
|
|
|
given. 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.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: --private-key-passwd-file=<PATH>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
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.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --subcert=<KEYPATH>:<CERTPATH>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Specify additional certificate and private key file.
|
|
|
|
nghttpx will choose certificates based on the hostname
|
|
|
|
indicated by client using TLS SNI extension. This
|
2015-03-30 17:23:12 +02:00
|
|
|
option can be used multiple times. To make OCSP
|
|
|
|
stapling work, <CERTPATH> must be absolute path.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --backend-tls-sni-field=<HOST>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Explicitly set the content of the TLS SNI extension.
|
|
|
|
This will default to the backend HOST name.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --dh-param-file=<PATH>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Path to file that contains DH parameters in PEM format.
|
|
|
|
Without this option, DHE cipher suites are not
|
|
|
|
available.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --npn-list=<LIST>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Comma delimited list of ALPN protocol identifier sorted
|
|
|
|
in the order of preference. That means most desirable
|
|
|
|
protocol comes first. This is used in both ALPN and
|
|
|
|
NPN. The parameter must be delimited by a single comma
|
|
|
|
only and any white spaces are treated as a part of
|
|
|
|
protocol string.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-02-22 10:02:57 +01:00
|
|
|
Default: ``h2,h2-16,h2-14,spdy/3.1,http/1.1``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --verify-client
|
|
|
|
|
|
|
|
Require and verify client certificate.
|
|
|
|
|
|
|
|
.. option:: --verify-client-cacert=<PATH>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Path to file that contains CA certificates to verify
|
|
|
|
client certificate. The file must be in PEM format. It
|
|
|
|
can contain multiple certificates.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --client-private-key-file=<PATH>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Path to file that contains client private key used in
|
|
|
|
backend client authentication.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --client-cert-file=<PATH>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Path to file that contains client certificate used in
|
|
|
|
backend client authentication.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --tls-proto-list=<LIST>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Comma delimited list of SSL/TLS protocol to be enabled.
|
|
|
|
The following protocols are available: TLSv1.2, TLSv1.1
|
|
|
|
and TLSv1.0. The name matching is done in
|
|
|
|
case-insensitive manner. The parameter must be
|
|
|
|
delimited by a single comma only and any white spaces
|
2015-10-19 17:22:03 +02:00
|
|
|
are treated as a part of protocol string. If the
|
|
|
|
protocol list advertised by client does not overlap this
|
|
|
|
list, you will receive the error message "unknown
|
|
|
|
protocol".
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
Default: ``TLSv1.2,TLSv1.1``
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: --tls-ticket-key-file=<PATH>
|
|
|
|
|
2015-07-28 17:01:12 +02:00
|
|
|
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>
|
|
|
|
|
|
|
|
Specify address of memcached server to store session
|
|
|
|
cache. 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.
|
|
|
|
|
|
|
|
.. 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.
|
2015-01-15 16:10:16 +01:00
|
|
|
|
2015-03-30 17:23:12 +02:00
|
|
|
.. 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:: --no-ocsp
|
|
|
|
|
|
|
|
Disable OCSP stapling.
|
|
|
|
|
2015-07-28 17:01:12 +02:00
|
|
|
.. option:: --tls-session-cache-memcached=<HOST>,<PORT>
|
|
|
|
|
|
|
|
Specify address of memcached server to store session
|
|
|
|
cache. This enables shared session cache between
|
|
|
|
multiple nghttpx instances.
|
|
|
|
|
2015-10-25 09:05:48 +01:00
|
|
|
.. 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``
|
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
HTTP/2 and SPDY
|
|
|
|
~~~~~~~~~~~~~~~
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
.. option:: -c, --http2-max-concurrent-streams=<N>
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set the maximum number of the concurrent streams in one
|
|
|
|
HTTP/2 and SPDY session.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``100``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --frontend-http2-window-bits=<N>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Sets the per-stream initial window size of HTTP/2 SPDY
|
|
|
|
frontend connection. For HTTP/2, the size is 2\*\*<N>-1.
|
|
|
|
For SPDY, the size is 2\*\*<N>.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``16``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --frontend-http2-connection-window-bits=<N>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Sets the per-connection window size of HTTP/2 and SPDY
|
|
|
|
frontend connection. For HTTP/2, the size is
|
|
|
|
2**<N>-1. For SPDY, the size is 2\*\*<N>.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``16``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --frontend-no-tls
|
|
|
|
|
|
|
|
Disable SSL/TLS on frontend connections.
|
|
|
|
|
|
|
|
.. option:: --backend-http2-window-bits=<N>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Sets the initial window size of HTTP/2 backend
|
|
|
|
connection to 2\*\*<N>-1.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``16``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --backend-http2-connection-window-bits=<N>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Sets the per-connection window size of HTTP/2 backend
|
|
|
|
connection to 2\*\*<N>-1.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``16``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --backend-no-tls
|
|
|
|
|
|
|
|
Disable SSL/TLS on backend connections.
|
|
|
|
|
|
|
|
.. option:: --http2-no-cookie-crumbling
|
|
|
|
|
|
|
|
Don't crumble cookie header field.
|
|
|
|
|
|
|
|
.. option:: --padding=<N>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
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.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-02-08 09:48:18 +01:00
|
|
|
.. option:: --no-server-push
|
|
|
|
|
|
|
|
Disable HTTP/2 server push. Server push is only
|
|
|
|
supported by default mode and HTTP/2 frontend. SPDY
|
|
|
|
frontend does not support server push.
|
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
Mode
|
|
|
|
~~~~
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. describe:: (default mode)
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
|
|
|
|
Accept HTTP/2, SPDY and HTTP/1.1 over SSL/TLS. If
|
|
|
|
:option:`--frontend-no-tls` is used, accept HTTP/2 and HTTP/1.1.
|
|
|
|
The incoming HTTP/1.1 connection can be upgraded to
|
|
|
|
HTTP/2 through HTTP Upgrade. The protocol to the
|
|
|
|
backend is HTTP/1.1.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: -s, --http2-proxy
|
|
|
|
|
|
|
|
Like default mode, but enable secure proxy mode.
|
|
|
|
|
|
|
|
.. option:: --http2-bridge
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Like default mode, but communicate with the backend in
|
|
|
|
HTTP/2 over SSL/TLS. Thus the incoming all connections
|
|
|
|
are converted to HTTP/2 connection and relayed to the
|
|
|
|
backend. See :option:`--backend-http-proxy-uri` option if you are
|
|
|
|
behind the proxy and want to connect to the outside
|
2014-07-08 17:38:43 +02:00
|
|
|
HTTP/2 proxy.
|
|
|
|
|
|
|
|
.. option:: --client
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Accept HTTP/2 and HTTP/1.1 without SSL/TLS. The
|
|
|
|
incoming HTTP/1.1 connection can be upgraded to HTTP/2
|
|
|
|
connection through HTTP Upgrade. The protocol to the
|
|
|
|
backend is HTTP/2. To use nghttpx as a forward proxy,
|
|
|
|
use :option:`-p` option instead.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: -p, --client-proxy
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Like :option:`--client` option, but it also requires the request
|
|
|
|
path from frontend must be an absolute URI, suitable for
|
|
|
|
use as a forward proxy.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
Logging
|
|
|
|
~~~~~~~
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: -L, --log-level=<LEVEL>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set the severity level of log output. <LEVEL> must be
|
|
|
|
one of INFO, NOTICE, WARN, ERROR and FATAL.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``NOTICE``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --accesslog-file=<PATH>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set path to write access log. To reopen file, send USR1
|
|
|
|
signal to nghttpx.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --accesslog-syslog
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Send access log to syslog. If this option is used,
|
|
|
|
:option:`--accesslog-file` option is ignored.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2014-11-24 07:27:41 +01:00
|
|
|
.. option:: --accesslog-format=<FORMAT>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Specify format string for access log. The default
|
|
|
|
format is combined format. The following variables are
|
|
|
|
available:
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
* $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.
|
2015-01-15 16:10:16 +01:00
|
|
|
* $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 '-'.
|
2015-01-09 16:37:42 +01:00
|
|
|
* $remote_port: client port.
|
|
|
|
* $server_port: server port.
|
2015-01-15 16:10:16 +01:00
|
|
|
* $request_time: request processing time in seconds with
|
|
|
|
milliseconds resolution.
|
2015-01-09 16:37:42 +01:00
|
|
|
* $pid: PID of the running process.
|
2015-01-15 16:10:16 +01:00
|
|
|
* $alpn: ALPN identifier of the protocol which generates
|
|
|
|
the response. For HTTP/1, ALPN is always http/1.1,
|
|
|
|
regardless of minor version.
|
2015-07-11 05:45:23 +02:00
|
|
|
* $ssl_cipher: cipher used for SSL/TLS connection.
|
|
|
|
* $ssl_protocol: protocol for SSL/TLS connection.
|
|
|
|
* $ssl_session_id: session ID for SSL/TLS connection.
|
|
|
|
* $ssl_session_reused: "r" if SSL/TLS session was
|
|
|
|
reused. Otherwise, "."
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-07-14 17:01:04 +02:00
|
|
|
The variable can be enclosed by "{" and "}" for
|
|
|
|
disambiguation (e.g., ${remote_addr}).
|
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``$remote_addr - - [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"``
|
2014-11-24 07:27:41 +01:00
|
|
|
|
2014-07-08 17:38:43 +02:00
|
|
|
.. option:: --errorlog-file=<PATH>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Set path to write error log. To reopen file, send USR1
|
2015-04-08 10:36:12 +02:00
|
|
|
signal to nghttpx. stderr will be redirected to the
|
|
|
|
error log file unless :option:`--errorlog-syslog` is used.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``/dev/stderr``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --errorlog-syslog
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Send error log to syslog. If this option is used,
|
|
|
|
:option:`--errorlog-file` option is ignored.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --syslog-facility=<FACILITY>
|
|
|
|
|
|
|
|
Set syslog facility to <FACILITY>.
|
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
Default: ``daemon``
|
|
|
|
|
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
HTTP
|
|
|
|
~~~~
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --add-x-forwarded-for
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Append X-Forwarded-For header field to the downstream
|
|
|
|
request.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2014-10-27 16:35:44 +01:00
|
|
|
.. option:: --strip-incoming-x-forwarded-for
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Strip X-Forwarded-For header field from inbound client
|
|
|
|
requests.
|
2014-10-27 16:35:44 +01:00
|
|
|
|
2014-07-08 17:38:43 +02:00
|
|
|
.. option:: --no-via
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Don't append to Via header field. If Via header field
|
|
|
|
is received, it is left unaltered.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2014-08-16 15:54:15 +02:00
|
|
|
.. option:: --no-location-rewrite
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Don't rewrite location header field on :option:`--http2-bridge`\,
|
|
|
|
:option:`--client` and default mode. For :option:`\--http2-proxy` and
|
|
|
|
:option:`--client-proxy` mode, location header field will not be
|
|
|
|
altered regardless of this option.
|
2014-08-16 15:54:15 +02:00
|
|
|
|
2015-07-28 17:01:12 +02:00
|
|
|
.. option:: --host-rewrite
|
2015-02-08 09:48:18 +01:00
|
|
|
|
2015-07-28 17:01:12 +02:00
|
|
|
Rewrite host and :authority header fields on
|
2015-02-08 09:48:18 +01:00
|
|
|
:option:`--http2-bridge`\, :option:`--client` and default mode. For
|
|
|
|
:option:`--http2-proxy` and :option:`\--client-proxy` mode, these headers
|
|
|
|
will not be altered regardless of this option.
|
|
|
|
|
2014-07-08 17:38:43 +02:00
|
|
|
.. option:: --altsvc=<PROTOID,PORT[,HOST,[ORIGIN]]>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Specify protocol ID, port, host and origin of
|
|
|
|
alternative service. <HOST> and <ORIGIN> are optional.
|
2015-05-15 17:10:41 +02:00
|
|
|
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
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-06-12 15:38:19 +02:00
|
|
|
.. option:: --add-request-header=<HEADER>
|
|
|
|
|
|
|
|
Specify additional header field to add to request header
|
|
|
|
set. 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"
|
|
|
|
|
2014-07-08 17:38:43 +02:00
|
|
|
.. option:: --add-response-header=<HEADER>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Specify additional header field to add to response
|
|
|
|
header set. 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.
|
2015-01-09 16:37:42 +01:00
|
|
|
Example: :option:`--add-response-header`\="foo: bar"
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-05-07 13:55:10 +02:00
|
|
|
.. option:: --header-field-buffer=<SIZE>
|
|
|
|
|
|
|
|
Set maximum buffer size for incoming HTTP header field
|
|
|
|
list. This is the sum of header name and value in
|
|
|
|
bytes.
|
|
|
|
|
|
|
|
Default: ``64K``
|
|
|
|
|
|
|
|
.. option:: --max-header-fields=<N>
|
|
|
|
|
|
|
|
Set maximum number of incoming HTTP header fields, which
|
|
|
|
appear in one request or response header field list.
|
|
|
|
|
|
|
|
Default: ``100``
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
Debug
|
|
|
|
~~~~~
|
2015-01-15 16:10:16 +01:00
|
|
|
|
2014-07-08 17:38:43 +02:00
|
|
|
.. option:: --frontend-http2-dump-request-header=<PATH>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
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.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --frontend-http2-dump-response-header=<PATH>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
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.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: -o, --frontend-frame-debug
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
Process
|
|
|
|
~~~~~~~
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: -D, --daemon
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Run in a background. If :option:`-D` is used, the current working
|
|
|
|
directory is changed to '*/*'.
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --pid-file=<PATH>
|
|
|
|
|
|
|
|
Set path to save PID of this program.
|
|
|
|
|
|
|
|
.. option:: --user=<USER>
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
Run this program as <USER>. This option is intended to
|
|
|
|
be used to drop root privileges.
|
|
|
|
|
|
|
|
|
2015-09-06 10:41:37 +02:00
|
|
|
Scripting
|
|
|
|
~~~~~~~~~
|
|
|
|
|
2015-10-25 09:05:48 +01:00
|
|
|
.. option:: --mruby-file=<PATH>
|
2015-09-06 10:41:37 +02:00
|
|
|
|
2015-10-25 09:05:48 +01:00
|
|
|
Set mruby script file
|
2015-09-06 10:41:37 +02:00
|
|
|
|
|
|
|
|
2015-02-01 10:33:24 +01:00
|
|
|
Misc
|
|
|
|
~~~~
|
2014-07-08 17:38:43 +02:00
|
|
|
|
|
|
|
.. option:: --conf=<PATH>
|
|
|
|
|
|
|
|
Load configuration from <PATH>.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
|
|
|
Default: ``/etc/nghttpx/nghttpx.conf``
|
2014-07-08 17:38:43 +02:00
|
|
|
|
2015-07-12 16:26:45 +02:00
|
|
|
.. 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.
|
|
|
|
|
2014-07-08 17:38:43 +02:00
|
|
|
.. option:: -v, --version
|
|
|
|
|
|
|
|
Print version and exit.
|
|
|
|
|
|
|
|
.. option:: -h, --help
|
|
|
|
|
|
|
|
Print this help and exit.
|
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
|
2015-03-30 17:23:12 +02:00
|
|
|
|
2015-01-15 16:10:16 +01:00
|
|
|
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).
|
|
|
|
|
2015-01-29 15:29:52 +01:00
|
|
|
The <DURATION> argument is an integer and an optional unit (e.g., 1s
|
2015-03-30 17:23:12 +02:00
|
|
|
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.
|
2015-01-29 15:29:52 +01:00
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
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.
|
|
|
|
|
2015-01-11 09:34:43 +01:00
|
|
|
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.
|
|
|
|
|
|
|
|
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
|
2015-05-12 03:49:42 +02:00
|
|
|
positional arguments in command-line, use ``private-key-file`` and
|
2015-01-11 09:34:43 +01:00
|
|
|
``certificate-file``.
|
|
|
|
|
|
|
|
:option:`--conf` option cannot be used in the configuration file and
|
|
|
|
will be ignored if specified.
|
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
SIGNALS
|
|
|
|
-------
|
|
|
|
|
|
|
|
SIGQUIT
|
|
|
|
Shutdown gracefully. First accept pending connections and stop
|
|
|
|
accepting connection. After all connections are handled, nghttpx
|
|
|
|
exits.
|
|
|
|
|
|
|
|
SIGUSR1
|
|
|
|
Reopen log files.
|
|
|
|
|
|
|
|
SIGUSR2
|
|
|
|
Fork and execute nghttpx. It will execute the binary in the same
|
2015-01-10 09:12:24 +01:00
|
|
|
path with same command-line arguments and environment variables.
|
|
|
|
After new process comes up, sending SIGQUIT to the original process
|
|
|
|
to perform hot swapping.
|
2015-01-09 16:37:42 +01:00
|
|
|
|
2015-09-23 17:17:14 +02:00
|
|
|
.. note::
|
|
|
|
|
2015-10-19 17:22:03 +02:00
|
|
|
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
|
|
|
|
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
|
|
|
|
behaviour of these processes may change in the future release. In
|
|
|
|
other words, in the future release, the processes other than master
|
|
|
|
process may terminate upon the reception of these signals.
|
|
|
|
Therefore these signals should not be sent to the processes other
|
|
|
|
than master process.
|
2015-09-23 17:17:14 +02:00
|
|
|
|
2015-02-08 09:48:18 +01:00
|
|
|
SERVER PUSH
|
|
|
|
-----------
|
|
|
|
|
|
|
|
nghttpx supports HTTP/2 server push in default mode. nghttpx looks
|
|
|
|
for Link header field (`RFC 5988
|
2015-02-15 05:07:23 +01:00
|
|
|
<http://tools.ietf.org/html/rfc5988>`_) in response headers from
|
2015-02-08 09:48:18 +01:00
|
|
|
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:: http
|
|
|
|
|
|
|
|
Link: </fonts/font.woff>; rel=preload
|
|
|
|
Link: </css/theme.css>; rel=preload
|
|
|
|
|
2015-09-06 10:41:37 +02:00
|
|
|
Currently, the following restriction is applied for server push:
|
2015-02-08 09:48:18 +01:00
|
|
|
|
2015-09-06 10:41:37 +02:00
|
|
|
1. The associated stream must have method "GET" or "POST". The
|
2015-02-08 09:48:18 +01:00
|
|
|
associated stream's status code must be 200.
|
|
|
|
|
2015-09-06 10:41:37 +02:00
|
|
|
This limitation may be loosened in the future release.
|
2015-02-08 09:48:18 +01:00
|
|
|
|
2015-02-26 16:57:13 +01:00
|
|
|
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.
|
|
|
|
|
2015-04-08 10:36:12 +02:00
|
|
|
OCSP STAPLING
|
|
|
|
-------------
|
|
|
|
|
2015-06-22 17:50:35 +02:00
|
|
|
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.
|
2015-04-08 10:36:12 +02:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2015-08-14 16:59:47 +02:00
|
|
|
If OCSP query is failed, previous OCSP response, if any, is continued
|
|
|
|
to be used.
|
|
|
|
|
2015-07-28 17:01:12 +02:00
|
|
|
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:`` + lowercased hex string of session ID
|
|
|
|
as a memcached entry key, with expiry time 12 hours. Session timeout
|
|
|
|
is set to 12 hours.
|
|
|
|
|
|
|
|
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.,
|
2015-08-08 18:13:35 +02:00
|
|
|
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::
|
2015-07-28 17:01:12 +02:00
|
|
|
|
|
|
|
+--------------+-------+----------------+
|
|
|
|
| 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.
|
|
|
|
|
|
|
|
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).
|
|
|
|
|
2015-09-06 10:41:37 +02:00
|
|
|
MRUBY SCRIPTING
|
|
|
|
---------------
|
|
|
|
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
The current mruby extension API is experimental and not frozen. The
|
|
|
|
API is subject to change in the future release.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2015-10-19 17:22:03 +02:00
|
|
|
To specify mruby script file, use :option:`--mruby-file` option. The
|
|
|
|
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.
|
2015-09-06 10:41:37 +02:00
|
|
|
|
|
|
|
.. 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 hoo 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.
|
|
|
|
|
|
|
|
.. 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.
|
|
|
|
|
|
|
|
.. 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
|
2015-11-09 03:40:35 +01:00
|
|
|
not be invoked. When this method is called in response phase
|
2015-09-06 10:41:37 +02:00
|
|
|
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:meth To
|
|
|
|
set response header fields, use
|
|
|
|
:rb:attr:`Nghttpx::Response#status`. If status code is not
|
|
|
|
set, 200 is used. :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.
|
|
|
|
|
|
|
|
MRUBY EXAMPLES
|
|
|
|
~~~~~~~~~~~~~~
|
|
|
|
|
2015-11-09 03:40:35 +01:00
|
|
|
Modify request path:
|
2015-09-06 10:41:37 +02:00
|
|
|
|
|
|
|
.. code-block:: ruby
|
|
|
|
|
2015-10-19 17:22:03 +02:00
|
|
|
class App
|
|
|
|
def on_req(env)
|
|
|
|
env.req.path = "/apps#{env.req.path}"
|
|
|
|
end
|
2015-09-06 10:41:37 +02:00
|
|
|
end
|
|
|
|
|
2015-10-19 17:22:03 +02:00
|
|
|
App.new
|
|
|
|
|
|
|
|
Don't forget to instantiate and evaluate object at the last line.
|
2015-09-06 10:41:37 +02:00
|
|
|
|
|
|
|
Restrict permission of viewing a content to a specific client
|
|
|
|
addresses:
|
|
|
|
|
|
|
|
.. code-block:: ruby
|
|
|
|
|
2015-10-19 17:22:03 +02:00
|
|
|
class App
|
|
|
|
def on_req(env)
|
|
|
|
allowed_clients = ["127.0.0.1", "::1"]
|
2015-09-06 10:41:37 +02:00
|
|
|
|
2015-10-19 17:22:03 +02:00
|
|
|
if env.req.path.start_with?("/log/") &&
|
|
|
|
!allowed_clients.include?(env.remote_addr) then
|
|
|
|
env.resp.status = 404
|
|
|
|
env.resp.return "permission denied"
|
|
|
|
end
|
2015-09-06 10:41:37 +02:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2015-10-19 17:22:03 +02:00
|
|
|
App.new
|
|
|
|
|
2014-07-08 17:38:43 +02:00
|
|
|
SEE ALSO
|
|
|
|
--------
|
|
|
|
|
2015-01-09 16:37:42 +01:00
|
|
|
:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`h2load(1)`
|