nghttp2/doc/nghttpx.1

.\" Man page generated from reStructuredText.
.
.TH "NGHTTPX" "1" "September 16, 2015" "1.3.2" "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.  To  make OCSP
stapling work, this must be absolute path.
.UNINDENT
.SH OPTIONS
.sp
The options are categorized into several groups.
.SS Connections
.INDENT 0.0
.TP
.B \-b, \-\-backend=(<HOST>,<PORT>|unix:<PATH>)[;<PATTERN>[:...]]
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
Optionally, if <PATTERN>s are given, the backend address
is only used  if request matches the pattern.   If \fI\%\-s\fP or
\fI\%\-p\fP  is  used,  <PATTERN>s   are  ignored.   The  pattern
matching  is closely  designed to  ServeMux in  net/http
package of Go  programming language.  <PATTERN> consists
of path, host + path or  just host.  The path must start
with "\fI/\fP".  If  it ends with "\fI/\fP", it  matches all request
path in  its subtree.  To  deal with the request  to the
directory without  trailing slash,  the path  which ends
with "\fI/\fP" also matches the  request path which only lacks
trailing \(aq\fI/\fP\(aq  (e.g., path  "\fI/foo/\fP" matches  request path
"\fI/foo\fP").  If it does not end with "\fI/\fP", 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,  "\fI/\fP"  is  appended to  it,  so that  it
matches  all   request  paths  under  the   host  (e.g.,
specifying "nghttp2.org" equals to "nghttp2.org/").
.sp
Patterns with  host take  precedence over  patterns with
just path.   Then, longer patterns take  precedence over
shorter  ones,  breaking  a  tie by  the  order  of  the
appearance in the configuration.
.sp
If <PATTERN> is  omitted, "\fI/\fP" is used  as pattern, which
matches  all  request  paths (catch\-all  pattern).   The
catch\-all backend must be given.
.sp
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.
.sp
For   example,   \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org/httpbin/\(aq
matches the  request host "nghttp2.org" and  the request
path "\fI/httpbin/get\fP", but does not match the request host
"nghttp2.org" and the request path "\fI/index.html\fP".
.sp
The  multiple <PATTERN>s  can  be specified,  delimiting
them            by           ":".             Specifying
\fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org:www.nghttp2.org\(aq  has  the
same  effect  to specify  \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org\(aq
and \fI\%\-b\fP\(aq127.0.0.1,8080;www.nghttp2.org\(aq.
.sp
The backend addresses sharing same <PATTERN> are grouped
together forming  load balancing  group.
.sp
Since ";" and ":" are  used as delimiter, <PATTERN> must
not  contain these  characters.  Since  ";" has  special
meaning in shell, the option value must be quoted.
.sp
Default: \fB127.0.0.1,80\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-f, \-\-frontend=(<HOST>,<PORT>|unix:<PATH>)
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
.INDENT 0.0
.TP
.B \-\-accept\-proxy\-protocol
Accept PROXY protocol version 1 on frontend connection.
.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  backend   HTTP/2   physical
connections  per  worker.   If  pattern is  used  in  \fI\%\-b\fP
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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend\-http1\-connections\-per\-host=<N>
Set   maximum  number   of  backend   concurrent  HTTP/1
connections per origin host.   This option is meaningful
when \fI\%\-s\fP option  is used.  The origin  host is determined
by  authority  portion  of requset  URI  (or  :authority
header  field  for  HTTP/2).   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: \fB3m\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-frontend\-read\-timeout=<DURATION>
Specify read timeout for HTTP/1.1 frontend connection.
.sp
Default: \fB3m\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: \fB3m\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.   To  make  OCSP
stapling work, <CERTPATH> must be absolute path.
.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  random data to construct TLS
session ticket  parameters.  If aes\-128\-cbc is  given in
\fI\%\-\-tls\-ticket\-key\-cipher\fP, the  file must  contain exactly
48    bytes.     If     aes\-256\-cbc    is    given    in
\fI\%\-\-tls\-ticket\-key\-cipher\fP, 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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached\-interval=<DURATION>
Set interval to get TLS ticket keys from memcached.
.sp
Default: \fB10m\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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
\fI\%\-\-tls\-ticket\-key\-memcached\-max\-fail\fP option.
.sp
Default: \fB3\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-ticket\-key\-memcached\-max\-fail=<N>
Set  maximum   number  of  consecutive   failure  before
disabling TLS ticket until next scheduled key retrieval.
.sp
Default: \fB2\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-fetch\-ocsp\-response\-file=<PATH>
Path to  fetch\-ocsp\-response script file.  It  should be
absolute path.
.sp
Default: \fB/usr/local/share/nghttp2/fetch\-ocsp\-response\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ocsp\-update\-interval=<DURATION>
Set interval to update OCSP response cache.
.sp
Default: \fB4h\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-ocsp
Disable OCSP stapling.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tls\-session\-cache\-memcached=<HOST>,<PORT>
Specify  address of  memcached server  to store  session
cache.   This  enables   shared  session  cache  between
multiple nghttpx instances.
.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.
.IP \(bu 2
$ssl_cipher: cipher used for SSL/TLS connection.
.IP \(bu 2
$ssl_protocol: protocol for SSL/TLS connection.
.IP \(bu 2
$ssl_session_id: session ID for SSL/TLS connection.
.IP \(bu 2
$ssl_session_reused:  "r"   if  SSL/TLS   session  was
reused.  Otherwise, "."
.UNINDENT
.sp
The  variable  can  be  enclosed  by  "{"  and  "}"  for
disambiguation (e.g., ${remote_addr}).
.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.   stderr will  be redirected  to the
error log file unless \fI\%\-\-errorlog\-syslog\fP is used.
.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 \-\-host\-rewrite
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 only  in
HTTP/1.1  frontend.  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\-request\-header=<HEADER>
Specify additional header field to add to request 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\-request\-header\fP="foo: bar"
.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
.INDENT 0.0
.TP
.B \-\-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.
.sp
Default: \fB64K\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-header\-fields=<N>
Set maximum number of incoming HTTP header fields, which
appear in one request or response header field list.
.sp
Default: \fB100\fP
.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 Scripting
.INDENT 0.0
.TP
.B \-\-request\-phase\-file=<PATH>
Set  mruby  script  file  which will  be  executed  when
request  header  fields  are  completely  received  from
frontend.  This hook is called request phase hook.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-response\-phase\-file=<PATH>
Set  mruby  script  file  which will  be  executed  when
response  header  fields  are completely  received  from
backend.  This hook is called response phase hook.
.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 \-\-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.
.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 h, m, s or ms
(hours, minutes, seconds and milliseconds, respectively).  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 command\-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 restriction is applied for server push:
.INDENT 0.0
.IP 1. 3
The associated stream must have method "GET" or "POST".  The
associated stream\(aqs status code must be 200.
.UNINDENT
.sp
This limitation 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 OCSP STAPLING
.sp
OCSP query is done using external Python script
\fBfetch\-ocsp\-response\fP, which has been originally developed in Perl
as part of h2o project (\fI\%https://github.com/h2o/h2o\fP), and was
translated into Python.
.sp
The script file is usually installed under
\fB$(prefix)/share/nghttp2/\fP directory.  The actual path to script can
be customized using \fI\%\-\-fetch\-ocsp\-response\-file\fP option.
.sp
If OCSP query is failed, previous OCSP response, if any, is continued
to be used.
.SH TLS SESSION RESUMPTION
.sp
nghttpx supports TLS session resumption through both session ID and
session ticket.
.SS SESSION ID RESUMPTION
.sp
By default, session ID is shared by all worker threads.
.sp
If \fI\%\-\-tls\-session\-cache\-memcached\fP is given, nghttpx will
insert serialized session data to memcached with
\fBnghttpx:tls\-session\-cache:\fP + lowercased hex string of session ID
as a memcached entry key, with expiry time 12 hours.  Session timeout
is set to 12 hours.
.SS TLS SESSION TICKET RESUMPTION
.sp
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.
.sp
If \fI\%\-\-tls\-ticket\-key\-memcached\fP 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.,
every 1 hour).  The example key generator tlsticketupdate.go is
available under contrib directory in nghttp2 archive.  The memcached
entry key is \fBnghttpx:tls\-ticket\-key\fP\&.  The data format stored in
memcached is the binary format described below:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
| VERSION (4)  |LEN (2)|KEY(48 or 80) ...
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
               ^                        |
               |                        |
               +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
               (LEN, KEY) pair can be repeated
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All numbers in the above figure is bytes.  All integer fields are
network byte order.
.sp
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 \fI\%\-\-tls\-ticket\-key\-cipher\fP=aes\-128\-cbc is
used, LEN must be 48.  If
\fI\%\-\-tls\-ticket\-key\-cipher\fP=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.
.sp
If \fI\%\-\-tls\-ticket\-key\-file\fP 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).
.SH MRUBY SCRIPTING
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
The current mruby extension API is experimental and not frozen.  The
API is subject to change in the future release.
.UNINDENT
.UNINDENT
.sp
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.
.sp
To set request phase hook, use \fI\%\-\-request\-phase\-file\fP option.
To set response phase hook, use \fI\%\-\-response\-phase\-file\fP
option.
.sp
For request and response phase hook, user calls \fI\%Nghttpx.run\fP
with block.  The \fI\%Nghttpx::Env\fP is passed to the block.
User can can access \fI\%Nghttpx::Request\fP and
\fI\%Nghttpx::Response\fP objects via \fI\%Nghttpx::Env#req\fP
and \fI\%Nghttpx::Env#resp\fP respectively.
.INDENT 0.0
.TP
.B classmethod .Nghttpx.run(&block)
Run request or response phase hook with given \fIblock\fP\&.
\fI\%Nghttpx::Env\fP object is passed to the given block.
.UNINDENT
.INDENT 0.0
.TP
.B Nghttpx::REQUEST_PHASE
Constant to represent request phase.
.UNINDENT
.INDENT 0.0
.TP
.B Nghttpx::RESPONSE_PHASE
Constant to represent response phase.
.UNINDENT
.INDENT 0.0
.TP
.B class Nghttpx::Env
Object to represent current request specific context.
.INDENT 7.0
.TP
.B attribute [R] req
Return \fI\%Request\fP object.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] resp
Return \fI\%Response\fP object.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] ctx
Return Ruby hash object.  It persists until request finishes.
So values set in request phase hoo can be retrieved in
response phase hook.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] phase
Return the current phase.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] remote_addr
Return IP address of a remote client.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class Nghttpx::Request
Object to represent request from client.  The modification to
Request object is allowed only in request phase hook.
.INDENT 7.0
.TP
.B attribute [R] http_version_major
Return HTTP major version.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] http_version_minor
Return HTTP minor version.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R/W] method
HTTP method.  On assignment, copy of given value is assigned.
We don\(aqt accept arbitrary method name.  We will document them
later, but well known methods, like GET, PUT and POST, are all
supported.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R/W] authority
Authority (i.e., example.org), including optional port
component .  On assignment, copy of given value is assigned.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R/W] scheme
Scheme (i.e., http, https).  On assignment, copy of given
value is assigned.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R/W] 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.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] 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
\fI\%Nghttpx::Request#add_header\fP or
\fI\%Nghttpx::Request#set_header\fP to change request
header fields.
.UNINDENT
.INDENT 7.0
.TP
.B 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.
.UNINDENT
.INDENT 7.0
.TP
.B 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.
.UNINDENT
.INDENT 7.0
.TP
.B clear_headers()
Clear all existing request header fields.
.UNINDENT
.INDENT 7.0
.TP
.B push uri
Initiate to push resource identified by \fIuri\fP\&.  Only HTTP/2
protocol supports this feature.  For the other protocols, this
method is noop.  \fIuri\fP 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.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class Nghttpx::Response
Object to represent response from backend server.
.INDENT 7.0
.TP
.B attribute [R] http_version_major
Return HTTP major version.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] http_version_minor
Return HTTP minor version.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R/W] 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.
.UNINDENT
.INDENT 7.0
.TP
.B attribute [R] 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
\fI\%Nghttpx::Response#add_header\fP or
\fI\%Nghttpx::Response#set_header\fP to change response
header fields.
.UNINDENT
.INDENT 7.0
.TP
.B 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.
.UNINDENT
.INDENT 7.0
.TP
.B 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.
.UNINDENT
.INDENT 7.0
.TP
.B clear_headers()
Clear all existing response header fields.
.UNINDENT
.INDENT 7.0
.TP
.B return(body)
Return custom response \fIbody\fP 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
not be invoked.  When this method is called in resonse phase
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
\fI\%Nghttpx::Response#status\fP\&.  If status code is not
set, 200 is used.  \fI\%Nghttpx::Response#add_header\fP and
\fI\%Nghttpx::Response#set_header\fP\&.  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
\fI\%Nghttpx::Response#clear_headers\fP 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.
.UNINDENT
.UNINDENT
.SS MRUBY EXAMPLES
.sp
Modify requet path:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Nghttpx.run do |env|
  env.req.path = "/apps#{env.req.path}"
end
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the file containing the above script must be set with
\fI\%\-\-request\-phase\-file\fP option since we modify request path.
.sp
Restrict permission of viewing a content to a specific client
addresses:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Nghttpx.run do |env|
  allowed_clients = ["127.0.0.1", "::1"]

  if env.req.path.start_with?("/log/") &&
     !allowed_clients.include?(env.remote_addr) then
    env.resp.status = 404
    env.resp.return "permission denied"
  end
end
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.