387 lines
12 KiB
Groff
387 lines
12 KiB
Groff
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.45.1.
|
|
.TH NGHTTPX "1" "May 2014" "nghttpx nghttp2/0.4.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.
|
|
Default: '127.0.0.1,80'
|
|
.TP
|
|
\fB\-f\fR, \fB\-\-frontend=\fR<HOST,PORT>
|
|
Set frontend host and port.
|
|
Default: '0.0.0.0,3000'
|
|
.TP
|
|
\fB\-\-backlog=\fR<NUM>
|
|
Set listen backlog size. If \fB\-1\fR is given,
|
|
libevent will choose suitable value.
|
|
Default: \fB\-1\fR
|
|
.TP
|
|
\fB\-\-backend\-ipv4\fR
|
|
Resolve backend hostname to IPv4 address only.
|
|
.TP
|
|
\fB\-\-backend\-ipv6\fR
|
|
Resolve backend hostname to IPv6 address only.
|
|
.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: 1048576
|
|
.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: 4194304
|
|
.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.
|
|
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.
|
|
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.
|
|
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.
|
|
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: 60
|
|
.TP
|
|
\fB\-\-backend\-read\-timeout=\fR<SEC>
|
|
Specify read timeout for backend connection.
|
|
Default: 900
|
|
.TP
|
|
\fB\-\-backend\-write\-timeout=\fR<SEC>
|
|
Specify write timeout for backend connection.
|
|
Default: 60
|
|
.TP
|
|
\fB\-\-backend\-keep\-alive\-timeout=\fR<SEC>
|
|
Specify keep\-alive timeout for backend
|
|
connection.
|
|
Default: 60
|
|
.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 "SSL/TLS:"
|
|
.TP
|
|
\fB\-\-ciphers=\fR<SUITE>
|
|
Set allowed cipher list. The format of the
|
|
string is described in OpenSSL ciphers(1). If
|
|
this option is used, \fB\-\-honor\-cipher\-order\fR is
|
|
implicitly enabled.
|
|
.TP
|
|
\fB\-\-honor\-cipher\-order\fR
|
|
Honor server cipher order, giving the ability to
|
|
mitigate BEAST attacks.
|
|
.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 NPN/ALPN protocol sorted
|
|
in the order of preference. That means most
|
|
desirable protocol comes first. The parameter
|
|
must be delimited by a single comma only and any
|
|
white spaces are treated as a part of protocol
|
|
string.
|
|
Default: h2\-12,spdy/3.1,spdy/3,spdy/2,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, TLSv1.0 and SSLv3. 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,TLSv1.0
|
|
.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, WARNING, ERROR and FATAL.
|
|
Default: WARNING
|
|
.TP
|
|
\fB\-\-accesslog\fR
|
|
Print simple accesslog to stderr.
|
|
.TP
|
|
\fB\-\-syslog\fR
|
|
Send log messages to syslog.
|
|
.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\-\-no\-via\fR
|
|
Don't append to Via header field. If Via header
|
|
field is received, it is left unaltered.
|
|
.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)
|