861 lines
24 KiB
Groff
861 lines
24 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "NGHTTPX" "1" "March 24, 2015" "0.7.8" "nghttp2"
|
|
.SH NAME
|
|
nghttpx \- HTTP/2 experimental proxy
|
|
.
|
|
.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
|
|
..
|
|
.SH SYNOPSIS
|
|
.sp
|
|
\fBnghttpx\fP [OPTIONS]... [<PRIVATE_KEY> <CERT>]
|
|
.SH DESCRIPTION
|
|
.sp
|
|
A reverse proxy for HTTP/2, HTTP/1 and SPDY.
|
|
.INDENT 0.0
|
|
.TP
|
|
.B <PRIVATE_KEY>
|
|
Set path to server\(aqs private key. Required unless \fI\%\-p\fP,
|
|
\fI\%\-\-client\fP or \fI\%\-\-frontend\-no\-tls\fP are given.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B <CERT>
|
|
Set path to server\(aqs certificate. Required unless \fI\%\-p\fP,
|
|
\fI\%\-\-client\fP or \fI\%\-\-frontend\-no\-tls\fP are given.
|
|
.UNINDENT
|
|
.SH OPTIONS
|
|
.sp
|
|
The options are categorized into several groups.
|
|
.SS Connections
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-b, \-\-backend=<HOST,PORT>
|
|
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)
|
|
.sp
|
|
Default: \fB127.0.0.1,80\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-f, \-\-frontend=<HOST,PORT>
|
|
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 "unix:" (e.g., unix:/var/run/nghttpx.sock)
|
|
.sp
|
|
Default: \fB*,3000\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-backlog=<N>
|
|
Set listen backlog size.
|
|
.sp
|
|
Default: \fB512\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-backend\-ipv4
|
|
Resolve backend hostname to IPv4 address only.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-backend\-ipv6
|
|
Resolve backend hostname to IPv6 address only.
|
|
.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 \-\-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\-http2\-connections\-per\-worker=<N>
|
|
Set maximum number of HTTP/2 connections per worker.
|
|
The default value is 0, which means the number of
|
|
backend addresses specified by \fI\%\-b\fP option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-backend\-http1\-connections\-per\-host=<N>
|
|
Set maximum number of backend concurrent HTTP/1
|
|
connections per host. This option is meaningful when \fI\%\-s\fP
|
|
option is used. To limit the number of connections per
|
|
frontend for default mode, use
|
|
\fI\%\-\-backend\-http1\-connections\-per\-frontend\fP\&.
|
|
.sp
|
|
Default: \fB8\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-backend\-http1\-connections\-per\-frontend=<N>
|
|
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 \fI\%\-\-backend\-http1\-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 \-\-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: \fB16K\fP
|
|
.UNINDENT
|
|
.SS Timeout
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-frontend\-http2\-read\-timeout=<DURATION>
|
|
Specify read timeout for HTTP/2 and SPDY frontend
|
|
connection.
|
|
.sp
|
|
Default: \fB180s\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-frontend\-read\-timeout=<DURATION>
|
|
Specify read timeout for HTTP/1.1 frontend connection.
|
|
.sp
|
|
Default: \fB180s\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 \-\-stream\-read\-timeout=<DURATION>
|
|
Specify read timeout for HTTP/2 and SPDY 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 and SPDY streams. 0
|
|
means no timeout.
|
|
.sp
|
|
Default: \fB0\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-backend\-read\-timeout=<DURATION>
|
|
Specify read timeout for backend connection.
|
|
.sp
|
|
Default: \fB180s\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\-keep\-alive\-timeout=<DURATION>
|
|
Specify keep\-alive timeout for backend 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: \fB0\fP
|
|
.UNINDENT
|
|
.SS SSL/TLS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-ciphers=<SUITE>
|
|
Set allowed cipher list. The format of the string is
|
|
described in OpenSSL ciphers(1).
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-k, \-\-insecure
|
|
Don\(aqt verify backend server\(aqs certificate if \fI\%\-p\fP,
|
|
\fI\%\-\-client\fP or \fI\%\-\-http2\-bridge\fP are given and
|
|
\fI\%\-\-backend\-no\-tls\fP is not given.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-cacert=<PATH>
|
|
Set path to trusted CA certificate file if \fI\%\-p\fP, \fI\%\-\-client\fP
|
|
or \fI\%\-\-http2\-bridge\fP are given and \fI\%\-\-backend\-no\-tls\fP 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.
|
|
.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>
|
|
Specify additional certificate and private key file.
|
|
nghttpx will choose certificates based on the hostname
|
|
indicated by client using TLS SNI extension. This
|
|
option can be used multiple times.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-backend\-tls\-sni\-field=<HOST>
|
|
Explicitly set the content of the TLS SNI extension.
|
|
This will default to the backend HOST name.
|
|
.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 \-\-npn\-list=<LIST>
|
|
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.
|
|
.sp
|
|
Default: \fBh2,h2\-16,h2\-14,spdy/3.1,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 \-\-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\-proto\-list=<LIST>
|
|
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
|
|
are treated as a part of protocol string.
|
|
.sp
|
|
Default: \fBTLSv1.2,TLSv1.1\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-tls\-ticket\-key\-file=<PATH>
|
|
Path to file that contains 48 bytes random data to
|
|
construct TLS session ticket parameters. 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
|
|
automatically and renewed every 12hrs. At most 2 keys
|
|
are stored in memory.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-tls\-ctx\-per\-worker
|
|
Create OpenSSL\(aqs SSL_CTX per worker, so that no internal
|
|
locking is required. This may improve scalability with
|
|
multi threaded configuration. If this option is
|
|
enabled, session ID is no longer shared accross SSL_CTX
|
|
objects, which means session ID generated by one worker
|
|
is not acceptable by another worker. On the other hand,
|
|
session ticket key is shared across all worker threads.
|
|
.UNINDENT
|
|
.SS HTTP/2 and SPDY
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-c, \-\-http2\-max\-concurrent\-streams=<N>
|
|
Set the maximum number of the concurrent streams in one
|
|
HTTP/2 and SPDY session.
|
|
.sp
|
|
Default: \fB100\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-frontend\-http2\-window\-bits=<N>
|
|
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>.
|
|
.sp
|
|
Default: \fB16\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-frontend\-http2\-connection\-window\-bits=<N>
|
|
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>.
|
|
.sp
|
|
Default: \fB16\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-frontend\-no\-tls
|
|
Disable SSL/TLS on frontend connections.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-backend\-http2\-window\-bits=<N>
|
|
Sets the initial window size of HTTP/2 backend
|
|
connection to 2**<N>\-1.
|
|
.sp
|
|
Default: \fB16\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-backend\-http2\-connection\-window\-bits=<N>
|
|
Sets the per\-connection window size of HTTP/2 backend
|
|
connection to 2**<N>\-1.
|
|
.sp
|
|
Default: \fB16\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-backend\-no\-tls
|
|
Disable SSL/TLS on backend connections.
|
|
.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 only
|
|
supported by default mode and HTTP/2 frontend. SPDY
|
|
frontend does not support server push.
|
|
.UNINDENT
|
|
.SS Mode
|
|
.INDENT 0.0
|
|
.TP
|
|
.B (default mode)
|
|
Accept HTTP/2, SPDY and HTTP/1.1 over SSL/TLS. If
|
|
\fI\%\-\-frontend\-no\-tls\fP 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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-s, \-\-http2\-proxy
|
|
Like default mode, but enable secure proxy mode.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-http2\-bridge
|
|
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 \fI\%\-\-backend\-http\-proxy\-uri\fP option if you are
|
|
behind the proxy and want to connect to the outside
|
|
HTTP/2 proxy.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-client
|
|
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 \fI\%\-p\fP option instead.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-p, \-\-client\-proxy
|
|
Like \fI\%\-\-client\fP option, but it also requires the request
|
|
path from frontend must be an absolute URI, suitable for
|
|
use as a forward proxy.
|
|
.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.
|
|
.UNINDENT
|
|
.sp
|
|
Default: \fB$remote_addr \- \- [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-errorlog\-file=<PATH>
|
|
Set path to write error log. To reopen file, send USR1
|
|
signal to nghttpx.
|
|
.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\-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\-location\-rewrite
|
|
Don\(aqt rewrite location header field on \fI\%\-\-http2\-bridge\fP,
|
|
\fI\%\-\-client\fP and default mode. For \fI\%\-\-http2\-proxy\fP and
|
|
\fI\%\-\-client\-proxy\fP mode, location header field will not be
|
|
altered regardless of this option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-no\-host\-rewrite
|
|
Don\(aqt rewrite host and :authority header fields on
|
|
\fI\%\-\-http2\-bridge\fP, \fI\%\-\-client\fP and default mode. For
|
|
\fI\%\-\-http2\-proxy\fP and \fI\%\-\-client\-proxy\fP mode, these headers
|
|
will not be altered regardless of this option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-altsvc=<PROTOID,PORT[,HOST,[ORIGIN]]>
|
|
Specify protocol ID, port, host and origin of
|
|
alternative service. <HOST> and <ORIGIN> are optional.
|
|
They are advertised in alt\-svc header field or HTTP/2
|
|
ALTSVC frame. This option can be used multiple times to
|
|
specify multiple alternative services. Example:
|
|
\fI\%\-\-altsvc\fP=h2,443
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-add\-response\-header=<HEADER>
|
|
Specify additional header field to add to response
|
|
header set. 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="foo: bar"
|
|
.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
|
|
.SS Misc
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-conf=<PATH>
|
|
Load configuration from <PATH>.
|
|
.sp
|
|
Default: \fB/etc/nghttpx/nghttpx.conf\fP
|
|
.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 s or ms. 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
|
|
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 commnad\-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.
|
|
.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 SIGUSR1
|
|
Reopen log files.
|
|
.TP
|
|
.B SIGUSR2
|
|
Fork and execute nghttpx. It will execute the binary in the same
|
|
path with same command\-line arguments and environment variables.
|
|
After new process comes up, sending SIGQUIT to the original process
|
|
to perform hot swapping.
|
|
.UNINDENT
|
|
.SH SERVER PUSH
|
|
.sp
|
|
nghttpx supports HTTP/2 server push in default mode. 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 restrictions are applied for server push:
|
|
.INDENT 0.0
|
|
.IP 1. 3
|
|
URI\-reference must not contain authority. If it exists, it is not
|
|
pushed. \fB/fonts/font.woff\fP and \fBcss/theme.css\fP are eligible to
|
|
be pushed. \fBhttps://example.org/fonts/font.woff\fP and
|
|
\fB//example.org/css/theme.css\fP are not.
|
|
.IP 2. 3
|
|
The associated stream must have method "GET" or "POST". The
|
|
associated stream\(aqs status code must be 200.
|
|
.UNINDENT
|
|
.sp
|
|
These limitations may be loosened in the future release.
|
|
.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 SEE ALSO
|
|
.sp
|
|
\fInghttp(1)\fP, \fInghttpd(1)\fP, \fIh2load(1)\fP
|
|
.SH AUTHOR
|
|
Tatsuhiro Tsujikawa
|
|
.SH COPYRIGHT
|
|
2012, 2015, Tatsuhiro Tsujikawa
|
|
.\" Generated by docutils manpage writer.
|
|
.
|