475 lines
15 KiB
Groff
475 lines
15 KiB
Groff
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.4.
|
|
.TH NGHTTPX "1" "January 2015" "nghttpx nghttp2/0.7.0" "User Commands"
|
|
.SH NAME
|
|
nghttpx \- HTTP/2 experimental proxy
|
|
.SH SYNOPSIS
|
|
.B nghttpx
|
|
[\fI\,OPTIONS\/\fR]... [\fI\,<PRIVATE_KEY> <CERT>\/\fR]
|
|
.SH DESCRIPTION
|
|
A reverse proxy for HTTP/2, HTTP/1 and SPDY.
|
|
.TP
|
|
<PRIVATE_KEY>
|
|
Set path to server's private key. Required
|
|
unless \fB\-p\fR, \fB\-\-client\fR or \fB\-\-frontend\-no\-tls\fR are
|
|
given.
|
|
.TP
|
|
<CERT>
|
|
Set path to server's certificate. Required
|
|
unless \fB\-p\fR, \fB\-\-client\fR or \fB\-\-frontend\-no\-tls\fR are
|
|
given.
|
|
.SH OPTIONS
|
|
.IP
|
|
The options are categorized into several groups.
|
|
.SS "Connections:"
|
|
.TP
|
|
\fB\-b\fR, \fB\-\-backend=\fR<HOST,PORT>
|
|
Set backend host and port. For HTTP/1 backend,
|
|
multiple backend addresses are accepted by
|
|
repeating this option. HTTP/2 backend does not
|
|
support multiple backend addresses and the first
|
|
occurrence of this option is used.
|
|
Default: '127.0.0.1,80'
|
|
.TP
|
|
\fB\-f\fR, \fB\-\-frontend=\fR<HOST,PORT>
|
|
Set frontend host and port. If <HOST> is '*', it
|
|
assumes all addresses including both IPv4 and
|
|
IPv6.
|
|
Default: '*,3000'
|
|
.TP
|
|
\fB\-\-backlog=\fR<NUM>
|
|
Set listen backlog size. If \fB\-1\fR is given,
|
|
libevent will choose suitable value.
|
|
Default: 128
|
|
.TP
|
|
\fB\-\-backend\-ipv4\fR
|
|
Resolve backend hostname to IPv4 address only.
|
|
.TP
|
|
\fB\-\-backend\-ipv6\fR
|
|
Resolve backend hostname to IPv6 address only.
|
|
.TP
|
|
\fB\-\-backend\-http\-proxy\-uri=\fR<URI>
|
|
Specify proxy URI in the form
|
|
http://[<USER>:<PASS>@]<PROXY>:<PORT>. If a
|
|
proxy requires authentication, specify <USER> and
|
|
<PASS>. Note that they must be properly
|
|
percent\-encoded. This proxy is used when the
|
|
backend connection is HTTP/2. First, make a
|
|
CONNECT request to the proxy and it connects to
|
|
the backend on behalf of nghttpx. This forms
|
|
tunnel. After that, nghttpx performs SSL/TLS
|
|
handshake with the downstream through the tunnel.
|
|
The timeouts when connecting and making CONNECT
|
|
request can be specified by
|
|
\fB\-\-backend\-read\-timeout\fR and
|
|
\fB\-\-backend\-write\-timeout\fR options.
|
|
.SS "Performance:"
|
|
.TP
|
|
\fB\-n\fR, \fB\-\-workers=\fR<CORES>
|
|
Set the number of worker threads.
|
|
Default: 1
|
|
.TP
|
|
\fB\-\-read\-rate=\fR<RATE>
|
|
Set maximum average read rate on frontend
|
|
connection. Setting 0 to this option means read
|
|
rate is unlimited.
|
|
Default: 0
|
|
.TP
|
|
\fB\-\-read\-burst=\fR<SIZE>
|
|
Set maximum read burst size on frontend
|
|
connection. Setting 0 to this option means read
|
|
burst size is unlimited.
|
|
Default: 0
|
|
.TP
|
|
\fB\-\-write\-rate=\fR<RATE>
|
|
Set maximum average write rate on frontend
|
|
connection. Setting 0 to this option means write
|
|
rate is unlimited.
|
|
Default: 0
|
|
.TP
|
|
\fB\-\-write\-burst=\fR<SIZE>
|
|
Set maximum write burst size on frontend
|
|
connection. Setting 0 to this option means write
|
|
burst size is unlimited.
|
|
Default: 0
|
|
.TP
|
|
\fB\-\-worker\-read\-rate=\fR<RATE>
|
|
Set maximum average read rate on frontend
|
|
connection per worker. Setting 0 to this option
|
|
means read rate is unlimited. Not implemented
|
|
yet.
|
|
Default: 0
|
|
.TP
|
|
\fB\-\-worker\-read\-burst=\fR<SIZE>
|
|
Set maximum read burst size on frontend
|
|
connection per worker. Setting 0 to this option
|
|
means read burst size is unlimited. Not
|
|
implemented yet.
|
|
Default: 0
|
|
.TP
|
|
\fB\-\-worker\-write\-rate=\fR<RATE>
|
|
Set maximum average write rate on frontend
|
|
connection per worker. Setting 0 to this option
|
|
means write rate is unlimited. Not implemented
|
|
yet.
|
|
Default: 0
|
|
.TP
|
|
\fB\-\-worker\-write\-burst=\fR<SIZE>
|
|
Set maximum write burst size on frontend
|
|
connection per worker. Setting 0 to this option
|
|
means write burst size is unlimited. Not
|
|
implemented yet.
|
|
Default: 0
|
|
.TP
|
|
\fB\-\-worker\-frontend\-connections=\fR<NUM>
|
|
Set maximum number of simultaneous connections
|
|
frontend accepts. Setting 0 means unlimited.
|
|
Default: 0
|
|
.TP
|
|
\fB\-\-backend\-http1\-connections\-per\-host=\fR<NUM>
|
|
Set maximum number of backend concurrent HTTP/1
|
|
connections per host. This option is meaningful
|
|
when \fB\-s\fR option is used. To limit the number of
|
|
connections per frontend for default mode, use
|
|
\fB\-\-backend\-http1\-connections\-per\-frontend\fR.
|
|
Default: 8
|
|
.TP
|
|
\fB\-\-backend\-http1\-connections\-per\-frontend=\fR<NUM>
|
|
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 (\fB\-s\fR option), use
|
|
\fB\-\-backend\-http1\-connections\-per\-host\fR.
|
|
Default: 0
|
|
.SS "Timeout:"
|
|
.TP
|
|
\fB\-\-frontend\-http2\-read\-timeout=\fR<SEC>
|
|
Specify read timeout for HTTP/2 and SPDY frontend
|
|
connection.
|
|
Default: 180
|
|
.TP
|
|
\fB\-\-frontend\-read\-timeout=\fR<SEC>
|
|
Specify read timeout for HTTP/1.1 frontend
|
|
connection.
|
|
Default: 180
|
|
.TP
|
|
\fB\-\-frontend\-write\-timeout=\fR<SEC>
|
|
Specify write timeout for all frontend
|
|
connections.
|
|
Default: 30
|
|
.TP
|
|
\fB\-\-stream\-read\-timeout=\fR<SEC>
|
|
Specify read timeout for HTTP/2 and SPDY streams.
|
|
0 means no timeout.
|
|
Default: 0
|
|
.TP
|
|
\fB\-\-stream\-write\-timeout=\fR<SEC>
|
|
Specify write timeout for HTTP/2 and SPDY
|
|
streams. 0 means no timeout.
|
|
Default: 0
|
|
.TP
|
|
\fB\-\-backend\-read\-timeout=\fR<SEC>
|
|
Specify read timeout for backend connection.
|
|
Default: 180
|
|
.TP
|
|
\fB\-\-backend\-write\-timeout=\fR<SEC>
|
|
Specify write timeout for backend connection.
|
|
Default: 30
|
|
.TP
|
|
\fB\-\-backend\-keep\-alive\-timeout=\fR<SEC>
|
|
Specify keep\-alive timeout for backend
|
|
connection.
|
|
Default: 600
|
|
.TP
|
|
\fB\-\-listener\-disable\-timeout=\fR<SEC>
|
|
After accepting connection failed, connection
|
|
listener is disabled for a given time in seconds.
|
|
Specifying 0 disables this feature.
|
|
Default: 0
|
|
.SS "SSL/TLS:"
|
|
.TP
|
|
\fB\-\-ciphers=\fR<SUITE>
|
|
Set allowed cipher list. The format of the
|
|
string is described in OpenSSL ciphers(1).
|
|
.TP
|
|
\fB\-k\fR, \fB\-\-insecure\fR
|
|
Don't verify backend server's certificate if \fB\-p\fR,
|
|
\fB\-\-client\fR or \fB\-\-http2\-bridge\fR are given and
|
|
\fB\-\-backend\-no\-tls\fR is not given.
|
|
.TP
|
|
\fB\-\-cacert=\fR<PATH>
|
|
Set path to trusted CA certificate file if \fB\-p\fR,
|
|
\fB\-\-client\fR or \fB\-\-http2\-bridge\fR are given and
|
|
\fB\-\-backend\-no\-tls\fR 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.
|
|
.TP
|
|
\fB\-\-private\-key\-passwd\-file=\fR<FILEPATH>
|
|
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.
|
|
.TP
|
|
\fB\-\-subcert=\fR<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.
|
|
.TP
|
|
\fB\-\-backend\-tls\-sni\-field=\fR<HOST>
|
|
Explicitly set the content of the TLS SNI
|
|
extension. This will default to the backend HOST
|
|
name.
|
|
.TP
|
|
\fB\-\-dh\-param\-file=\fR<PATH>
|
|
Path to file that contains DH parameters in PEM
|
|
format. Without this option, DHE cipher suites
|
|
are not available.
|
|
.TP
|
|
\fB\-\-npn\-list=\fR<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.
|
|
Default: h2\-16,h2\-14,spdy/3.1,http/1.1
|
|
.TP
|
|
\fB\-\-verify\-client\fR
|
|
Require and verify client certificate.
|
|
.TP
|
|
\fB\-\-verify\-client\-cacert=\fR<PATH>
|
|
Path to file that contains CA certificates to
|
|
verify client certificate. The file must be in
|
|
PEM format. It can contain multiple
|
|
certificates.
|
|
.TP
|
|
\fB\-\-client\-private\-key\-file=\fR<PATH>
|
|
Path to file that contains client private key
|
|
used in backend client authentication.
|
|
.TP
|
|
\fB\-\-client\-cert\-file=\fR<PATH>
|
|
Path to file that contains client certificate
|
|
used in backend client authentication.
|
|
.TP
|
|
\fB\-\-tls\-proto\-list=\fR<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.
|
|
Default: TLSv1.2,TLSv1.1
|
|
.SS "HTTP/2 and SPDY:"
|
|
.TP
|
|
\fB\-c\fR, \fB\-\-http2\-max\-concurrent\-streams=\fR<NUM>
|
|
Set the maximum number of the concurrent streams
|
|
in one HTTP/2 and SPDY session.
|
|
Default: 100
|
|
.TP
|
|
\fB\-\-frontend\-http2\-window\-bits=\fR<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>.
|
|
Default: 16
|
|
.TP
|
|
\fB\-\-frontend\-http2\-connection\-window\-bits=\fR<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>.
|
|
Default: 16
|
|
.TP
|
|
\fB\-\-frontend\-no\-tls\fR
|
|
Disable SSL/TLS on frontend connections.
|
|
.TP
|
|
\fB\-\-backend\-http2\-window\-bits=\fR<N>
|
|
Sets the initial window size of HTTP/2 backend
|
|
connection to 2**<N>\-1.
|
|
Default: 16
|
|
.TP
|
|
\fB\-\-backend\-http2\-connection\-window\-bits=\fR<N>
|
|
Sets the per\-connection window size of HTTP/2
|
|
backend connection to 2**<N>\-1.
|
|
Default: 16
|
|
.TP
|
|
\fB\-\-backend\-no\-tls\fR
|
|
Disable SSL/TLS on backend connections.
|
|
.TP
|
|
\fB\-\-http2\-no\-cookie\-crumbling\fR
|
|
Don't crumble cookie header field.
|
|
.TP
|
|
\fB\-\-padding=\fR<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.
|
|
.SS "Mode:"
|
|
.TP
|
|
(default mode)
|
|
Accept HTTP/2, SPDY and HTTP/1.1 over SSL/TLS.
|
|
If \fB\-\-frontend\-no\-tls\fR 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.
|
|
.TP
|
|
\fB\-s\fR, \fB\-\-http2\-proxy\fR
|
|
Like default mode, but enable secure proxy mode.
|
|
.TP
|
|
\fB\-\-http2\-bridge\fR
|
|
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
|
|
\fB\-\-backend\-http\-proxy\-uri\fR option if you are behind
|
|
the proxy and want to connect to the outside
|
|
HTTP/2 proxy.
|
|
.TP
|
|
\fB\-\-client\fR
|
|
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 \fB\-p\fR option
|
|
instead.
|
|
.TP
|
|
\fB\-p\fR, \fB\-\-client\-proxy\fR
|
|
Like \fB\-\-client\fR option, but it also requires the
|
|
request path from frontend must be an absolute
|
|
URI, suitable for use as a forward proxy.
|
|
.SS "Logging:"
|
|
.TP
|
|
\fB\-L\fR, \fB\-\-log\-level=\fR<LEVEL>
|
|
Set the severity level of log output. <LEVEL>
|
|
must be one of INFO, NOTICE, WARN, ERROR and
|
|
FATAL.
|
|
Default: NOTICE
|
|
.TP
|
|
\fB\-\-accesslog\-file=\fR<PATH>
|
|
Set path to write access log. To reopen file,
|
|
send USR1 signal to nghttpx.
|
|
.TP
|
|
\fB\-\-accesslog\-syslog\fR
|
|
Send access log to syslog. If this option is
|
|
used, \fB\-\-access\-file\fR option is ignored.
|
|
.TP
|
|
\fB\-\-accesslog\-format=\fR<FORMAT>
|
|
Specify format string for access log. The
|
|
default format is combined format. The following
|
|
variables are available:
|
|
$remote_addr: client IP address.
|
|
$time_local: local time in Common Log format.
|
|
$time_iso8601: local time in ISO 8601 format.
|
|
$request: HTTP request line.
|
|
$status: HTTP response status code.
|
|
$body_bytes_sent: the number of bytes sent to
|
|
client as response body.
|
|
$http_<VAR>: value of HTTP request header <VAR>
|
|
where '_' in <VAR> is replaced with '\-'.
|
|
$remote_port: client port.
|
|
$server_port: server port.
|
|
$request_time: request processing time in
|
|
seconds with milliseconds resolution.
|
|
$pid: PID of the running process.
|
|
$alpn: ALPN identifier of the protocol which
|
|
generates the response. For HTTP/1, ALPN is
|
|
always http/1.1, regardless of minor version.
|
|
Default: $remote_addr \- \- [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"
|
|
.TP
|
|
\fB\-\-errorlog\-file=\fR<PATH>
|
|
Set path to write error log. To reopen file,
|
|
send USR1 signal to nghttpx.
|
|
Default: \fI\,/dev/stderr\/\fP
|
|
.TP
|
|
\fB\-\-errorlog\-syslog\fR
|
|
Send error log to syslog. If this option is
|
|
used, \fB\-\-errorlog\-file\fR option is ignored.
|
|
.TP
|
|
\fB\-\-syslog\-facility=\fR<FACILITY>
|
|
Set syslog facility to <FACILITY>.
|
|
Default: daemon
|
|
.SS "Misc:"
|
|
.TP
|
|
\fB\-\-add\-x\-forwarded\-for\fR
|
|
Append X\-Forwarded\-For header field to the
|
|
downstream request.
|
|
.TP
|
|
\fB\-\-strip\-incoming\-x\-forwarded\-for\fR
|
|
Strip X\-Forwarded\-For header field from inbound
|
|
client requests.
|
|
.TP
|
|
\fB\-\-no\-via\fR
|
|
Don't append to Via header field. If Via header
|
|
field is received, it is left unaltered.
|
|
.TP
|
|
\fB\-\-no\-location\-rewrite\fR
|
|
Don't rewrite location header field on
|
|
\fB\-\-http2\-bridge\fR, \fB\-\-client\fR and default mode. For
|
|
\fB\-\-http2\-proxy\fR and \fB\-\-client\-proxy\fR mode, location
|
|
header field will not be altered regardless of
|
|
this option.
|
|
.TP
|
|
\fB\-\-altsvc=\fR<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: \fB\-\-altsvc\fR=\fI\,h2\/\fR,443
|
|
.TP
|
|
\fB\-\-add\-response\-header=\fR<HEADER>
|
|
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.
|
|
Example: \fB\-\-add\-response\-header=\fR"foo: bar"
|
|
.TP
|
|
\fB\-\-frontend\-http2\-dump\-request\-header=\fR<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 \fB\-n\fR<N>, where <N> >= 2.
|
|
.TP
|
|
\fB\-\-frontend\-http2\-dump\-response\-header=\fR<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 \fB\-n\fR<N>, where <N> >= 2.
|
|
.TP
|
|
\fB\-o\fR, \fB\-\-frontend\-frame\-debug\fR
|
|
Print HTTP/2 frames in frontend to stderr. This
|
|
option is not thread safe and MUST NOT be used
|
|
with option \fB\-n\fR=\fI\,N\/\fR, where N >= 2.
|
|
.TP
|
|
\fB\-D\fR, \fB\-\-daemon\fR
|
|
Run in a background. If \fB\-D\fR is used, the current
|
|
working directory is changed to '/'.
|
|
.TP
|
|
\fB\-\-pid\-file=\fR<PATH>
|
|
Set path to save PID of this program.
|
|
.TP
|
|
\fB\-\-user=\fR<USER>
|
|
Run this program as <USER>. This option is
|
|
intended to be used to drop root privileges.
|
|
.TP
|
|
\fB\-\-conf=\fR<PATH>
|
|
Load configuration from <PATH>.
|
|
Default: \fI\,/etc/nghttpx/nghttpx.conf\/\fP
|
|
.TP
|
|
\fB\-v\fR, \fB\-\-version\fR
|
|
Print version and exit.
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
Print this help and exit.
|
|
.SH "SEE ALSO"
|
|
|
|
nghttp(1), nghttpd(1), h2load(1)
|