nghttp2/doc/nghttpx.1

.\" 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)