From 18d42b411bedda81244ddfa331cf781e6825aed1 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Fri, 16 Jan 2015 00:10:16 +0900 Subject: [PATCH] Update man pages --- doc/h2load.1 | 56 +++-- doc/h2load.1.rst | 54 +++-- doc/nghttp.1 | 98 ++++----- doc/nghttp.1.rst | 97 ++++----- doc/nghttpd.1 | 68 +++--- doc/nghttpd.1.rst | 68 +++--- doc/nghttpx.1 | 529 +++++++++++++++++++++++---------------------- doc/nghttpx.1.rst | 539 +++++++++++++++++++++++----------------------- 8 files changed, 748 insertions(+), 761 deletions(-) diff --git a/doc/h2load.1 b/doc/h2load.1 index b2156216..615ff0a6 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "H2LOAD" "1" "January 11, 2015" "0.7.1" "nghttp2" +.TH "H2LOAD" "1" "January 16, 2015" "0.7.2-DEV" "nghttp2" .SH NAME h2load \- HTTP/2 benchmarking tool . @@ -39,13 +39,12 @@ benchmarking tool for HTTP/2 and SPDY server .INDENT 0.0 .TP .B -Specify URI to access. Multiple URIs can be -specified. URIs are used in this order for each -client. All URIs are used, then first URI is -used and then 2nd URI, and so on. The scheme, -host and port in the subsequent URIs, if present, -are ignored. Those in the first URI are used -solely. +Specify URI to access. Multiple URIs can be specified. +URIs are used in this order for each client. All URIs +are used, then first URI is used and then 2nd URI, and +so on. The scheme, host and port in the subsequent +URIs, if present, are ignored. Those in the first URI +are used solely. .UNINDENT .SH OPTIONS: .INDENT 0.0 @@ -72,38 +71,36 @@ Default: \fB1\fP .INDENT 0.0 .TP .B \-i, \-\-input\-file= -Path of a file with multiple URIs are seperated -by EOLs. This option will disable URIs getting -from command\-line. If \(aq\-\(aq is given as , -URIs will be read from stdin. URIs are used in -this order for each client. All URIs are used, -then first URI is used and then 2nd URI, and so -on. The scheme, host and port in the subsequent -URIs, if present, are ignored. Those in the -first URI are used solely. +Path of a file with multiple URIs are seperated by EOLs. +This option will disable URIs getting from command\-line. +If \(aq\-\(aq is given as , URIs will be read from stdin. +URIs are used in this order for each client. All URIs +are used, then first URI is used and then 2nd URI, and +so on. The scheme, host and port in the subsequent +URIs, if present, are ignored. Those in the first URI +are used solely. .UNINDENT .INDENT 0.0 .TP .B \-m, \-\-max\-concurrent\-streams=(auto|) -Max concurrent streams to issue per session. If -"auto" is given, the number of given URIs is -used. +Max concurrent streams to issue per session. If "auto" +is given, the number of given URIs is used. .sp Default: \fBauto\fP .UNINDENT .INDENT 0.0 .TP .B \-w, \-\-window\-bits= -Sets the stream level initial window size to -(2**)\-1. For SPDY, 2** is used instead. +Sets the stream level initial window size to (2**)\-1. +For SPDY, 2** is used instead. .UNINDENT .INDENT 0.0 .TP .B \-W, \-\-connection\-window\-bits= -Sets the connection level initial window size to -(2**)\-1. For SPDY, if is strictly less -than 16, this option is ignored. Otherwise -2** is used for SPDY. +Sets the connection level initial window size to +(2**)\-1. For SPDY, if is strictly less than 16, +this option is ignored. Otherwise 2** is used for +SPDY. .UNINDENT .INDENT 0.0 .TP @@ -113,10 +110,9 @@ Add/Override a header to the requests. .INDENT 0.0 .TP .B \-p, \-\-no\-tls\-proto= -Specify ALPN identifier of the protocol to be -used when accessing http URI without SSL/TLS. -Available protocols: spdy/2, spdy/3, spdy/3.1 and -h2c\-14 +Specify ALPN identifier of the protocol to be used when +accessing http URI without SSL/TLS. +Available protocols: spdy/2, spdy/3, spdy/3.1 and h2c\-14 .sp Default: \fBh2c\-14\fP .UNINDENT diff --git a/doc/h2load.1.rst b/doc/h2load.1.rst index 120bda1b..ac447ebe 100644 --- a/doc/h2load.1.rst +++ b/doc/h2load.1.rst @@ -14,13 +14,12 @@ benchmarking tool for HTTP/2 and SPDY server .. describe:: - Specify URI to access. Multiple URIs can be - specified. URIs are used in this order for each - client. All URIs are used, then first URI is - used and then 2nd URI, and so on. The scheme, - host and port in the subsequent URIs, if present, - are ignored. Those in the first URI are used - solely. + Specify URI to access. Multiple URIs can be specified. + URIs are used in this order for each client. All URIs + are used, then first URI is used and then 2nd URI, and + so on. The scheme, host and port in the subsequent + URIs, if present, are ignored. Those in the first URI + are used solely. OPTIONS: -------- @@ -45,35 +44,33 @@ OPTIONS: .. option:: -i, --input-file= - Path of a file with multiple URIs are seperated - by EOLs. This option will disable URIs getting - from command-line. If '-' is given as , - URIs will be read from stdin. URIs are used in - this order for each client. All URIs are used, - then first URI is used and then 2nd URI, and so - on. The scheme, host and port in the subsequent - URIs, if present, are ignored. Those in the - first URI are used solely. + Path of a file with multiple URIs are seperated by EOLs. + This option will disable URIs getting from command-line. + If '-' is given as , URIs will be read from stdin. + URIs are used in this order for each client. All URIs + are used, then first URI is used and then 2nd URI, and + so on. The scheme, host and port in the subsequent + URIs, if present, are ignored. Those in the first URI + are used solely. .. option:: -m, --max-concurrent-streams=(auto|) - Max concurrent streams to issue per session. If - "auto" is given, the number of given URIs is - used. + Max concurrent streams to issue per session. If "auto" + is given, the number of given URIs is used. Default: ``auto`` .. option:: -w, --window-bits= - Sets the stream level initial window size to - (2**)-1. For SPDY, 2\*\* is used instead. + Sets the stream level initial window size to (2\*\*)-1. + For SPDY, 2** is used instead. .. option:: -W, --connection-window-bits= - Sets the connection level initial window size to - (2**)-1. For SPDY, if is strictly less - than 16, this option is ignored. Otherwise - 2** is used for SPDY. + Sets the connection level initial window size to + (2**)-1. For SPDY, if is strictly less than 16, + this option is ignored. Otherwise 2\*\* is used for + SPDY. .. option:: -H, --header=
@@ -81,10 +78,9 @@ OPTIONS: .. option:: -p, --no-tls-proto= - Specify ALPN identifier of the protocol to be - used when accessing http URI without SSL/TLS. - Available protocols: spdy/2, spdy/3, spdy/3.1 and - h2c-14 + Specify ALPN identifier of the protocol to be used when + accessing http URI without SSL/TLS. + Available protocols: spdy/2, spdy/3, spdy/3.1 and h2c-14 Default: ``h2c-14`` diff --git a/doc/nghttp.1 b/doc/nghttp.1 index 5485db12..31d0eed0 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTP" "1" "January 11, 2015" "0.7.1" "nghttp2" +.TH "NGHTTP" "1" "January 16, 2015" "0.7.2-DEV" "nghttp2" .SH NAME nghttp \- HTTP/2 experimental client . @@ -45,10 +45,9 @@ Specify URI to access. .INDENT 0.0 .TP .B \-v, \-\-verbose -Print debug information such as reception and -transmission of frames and name/value pairs. -Specifying this option multiple times increases -verbosity. +Print debug information such as reception and +transmission of frames and name/value pairs. Specifying +this option multiple times increases verbosity. .UNINDENT .INDENT 0.0 .TP @@ -58,39 +57,37 @@ Discard downloaded data. .INDENT 0.0 .TP .B \-O, \-\-remote\-name -Save download data in the current directory. The -filename is dereived from URI. If URI ends with -\(aq\fI/\fP\(aq, \(aqindex.html\(aq is used as a filename. Not -implemented yet. +Save download data in the current directory. The +filename is dereived from URI. If URI ends with \(aq\fI/\fP\(aq, +\(aqindex.html\(aq is used as a filename. Not implemented +yet. .UNINDENT .INDENT 0.0 .TP -.B \-t, \-\-timeout= -Timeout each request after seconds. +.B \-t, \-\-timeout= +Timeout each request after seconds. .UNINDENT .INDENT 0.0 .TP .B \-w, \-\-window\-bits= -Sets the stream level initial window size to -2**\-1. +Sets the stream level initial window size to 2**\-1. .UNINDENT .INDENT 0.0 .TP .B \-W, \-\-connection\-window\-bits= -Sets the connection level initial window size to +Sets the connection level initial window size to 2**\-1. .UNINDENT .INDENT 0.0 .TP .B \-a, \-\-get\-assets -Download assets such as stylesheets, images and -script files linked from the downloaded resource. -Only links whose origins are the same with the -linking resource will be downloaded. nghttp -prioritizes resources using HTTP/2 dependency -based priority. The priority order, from highest -to lowest, is html itself, css, javascript and -images. +Download assets such as stylesheets, images and script +files linked from the downloaded resource. Only links +whose origins are the same with the linking resource +will be downloaded. nghttp prioritizes resources using +HTTP/2 dependency based priority. The priority order, +from highest to lowest, is html itself, css, javascript +and images. .UNINDENT .INDENT 0.0 .TP @@ -100,74 +97,70 @@ Print statistics. .INDENT 0.0 .TP .B \-H, \-\-header=
-Add a header to the requests. Example: -\fI\%\-H\fP\(aq:method: PUT\(aq +Add a header to the requests. Example: \fI\%\-H\fP\(aq:method: PUT\(aq .UNINDENT .INDENT 0.0 .TP .B \-\-cert= -Use the specified client certificate file. The -file must be in PEM format. +Use the specified client certificate file. The file +must be in PEM format. .UNINDENT .INDENT 0.0 .TP .B \-\-key= -Use the client private key file. The file must -be in PEM format. +Use the client private key file. The file must be in +PEM format. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-data= -Post FILE to server. If \(aq\-\(aq is given, data will -be read from stdin. +Post FILE to server. If \(aq\-\(aq is given, data will be read +from stdin. .UNINDENT .INDENT 0.0 .TP .B \-m, \-\-multiply= -Request each URI times. By default, same URI -is not requested twice. This option disables it -too. +Request each URI times. By default, same URI is not +requested twice. This option disables it too. .UNINDENT .INDENT 0.0 .TP .B \-u, \-\-upgrade -Perform HTTP Upgrade for HTTP/2. This option is -ignored if the request URI has https scheme. If -\fI\-d\fP is used, the HTTP upgrade request is performed -with OPTIONS method. +Perform HTTP Upgrade for HTTP/2. This option is ignored +if the request URI has https scheme. If \fI\-d\fP is used, the +HTTP upgrade request is performed with OPTIONS method. .UNINDENT .INDENT 0.0 .TP .B \-p, \-\-weight= -Sets priority group weight. The valid value -range is [1, 256], inclusive. +Sets priority group weight. The valid value range is +[1, 256], inclusive. .sp Default: \fB16\fP .UNINDENT .INDENT 0.0 .TP .B \-M, \-\-peer\-max\-concurrent\-streams= -Use as SETTINGS_MAX_CONCURRENT_STREAMS value -of remote endpoint as if it is received in -SETTINGS frame. The default is large enough as -it is seen as unlimited. +Use as SETTINGS_MAX_CONCURRENT_STREAMS value of +remote endpoint as if it is received in SETTINGS frame. +The default is large enough as it is seen as unlimited. .UNINDENT .INDENT 0.0 .TP -.B \-c, \-\-header\-table\-size= +.B \-c, \-\-header\-table\-size= Specify decoder header table size. .UNINDENT .INDENT 0.0 .TP .B \-b, \-\-padding= -Add at most bytes to a frame payload as -padding. Specify 0 to disable padding. +Add at most bytes to a frame payload as padding. +Specify 0 to disable padding. .UNINDENT .INDENT 0.0 .TP .B \-r, \-\-har= -Output HTTP transactions in HAR format. -If \(aq\-\(aq is given, data is written to stdout. +Output HTTP transactions in HAR format. If \(aq\-\(aq +is given, data is written to stdout. .UNINDENT .INDENT 0.0 .TP @@ -187,14 +180,12 @@ Don\(aqt send content\-length header field. .INDENT 0.0 .TP .B \-\-no\-dep -Don\(aqt send dependency based priority hint to -server. +Don\(aqt send dependency based priority hint to server. .UNINDENT .INDENT 0.0 .TP .B \-\-dep\-idle -Use idle streams as anchor nodes to express -priority. +Use idle streams as anchor nodes to express priority. .UNINDENT .INDENT 0.0 .TP @@ -206,6 +197,9 @@ Display version information and exit. .B \-h, \-\-help Display this help and exit. .UNINDENT +.sp +The argument is an integer and an optional unit (e.g., 10K is +10 * 1024). Units are K, M and G (powers of 1024). .SH SEE ALSO .sp \fInghttpd(1)\fP, \fInghttpx(1)\fP, \fIh2load(1)\fP diff --git a/doc/nghttp.1.rst b/doc/nghttp.1.rst index 6103dbf0..27218b54 100644 --- a/doc/nghttp.1.rst +++ b/doc/nghttp.1.rst @@ -21,10 +21,9 @@ OPTIONS: .. option:: -v, --verbose - Print debug information such as reception and - transmission of frames and name/value pairs. - Specifying this option multiple times increases - verbosity. + Print debug information such as reception and + transmission of frames and name/value pairs. Specifying + this option multiple times increases verbosity. .. option:: -n, --null-out @@ -32,35 +31,33 @@ OPTIONS: .. option:: -O, --remote-name - Save download data in the current directory. The - filename is dereived from URI. If URI ends with - '*/*', 'index.html' is used as a filename. Not - implemented yet. + Save download data in the current directory. The + filename is dereived from URI. If URI ends with '*/*', + 'index.html' is used as a filename. Not implemented + yet. -.. option:: -t, --timeout= +.. option:: -t, --timeout= - Timeout each request after seconds. + Timeout each request after seconds. .. option:: -w, --window-bits= - Sets the stream level initial window size to - 2\*\*-1. + Sets the stream level initial window size to 2\*\*-1. .. option:: -W, --connection-window-bits= - Sets the connection level initial window size to + Sets the connection level initial window size to 2\*\*-1. .. option:: -a, --get-assets - Download assets such as stylesheets, images and - script files linked from the downloaded resource. - Only links whose origins are the same with the - linking resource will be downloaded. nghttp - prioritizes resources using HTTP/2 dependency - based priority. The priority order, from highest - to lowest, is html itself, css, javascript and - images. + Download assets such as stylesheets, images and script + files linked from the downloaded resource. Only links + whose origins are the same with the linking resource + will be downloaded. nghttp prioritizes resources using + HTTP/2 dependency based priority. The priority order, + from highest to lowest, is html itself, css, javascript + and images. .. option:: -s, --stat @@ -68,64 +65,60 @@ OPTIONS: .. option:: -H, --header=
- Add a header to the requests. Example: - :option:`-H`\':method: PUT' + Add a header to the requests. Example: :option:`-H`\':method: PUT' .. option:: --cert= - Use the specified client certificate file. The - file must be in PEM format. + Use the specified client certificate file. The file + must be in PEM format. .. option:: --key= - Use the client private key file. The file must - be in PEM format. + Use the client private key file. The file must be in + PEM format. .. option:: -d, --data= - Post FILE to server. If '-' is given, data will - be read from stdin. + Post FILE to server. If '-' is given, data will be read + from stdin. .. option:: -m, --multiply= - Request each URI times. By default, same URI - is not requested twice. This option disables it - too. + Request each URI times. By default, same URI is not + requested twice. This option disables it too. .. option:: -u, --upgrade - Perform HTTP Upgrade for HTTP/2. This option is - ignored if the request URI has https scheme. If - :option:`-d` is used, the HTTP upgrade request is performed - with OPTIONS method. + Perform HTTP Upgrade for HTTP/2. This option is ignored + if the request URI has https scheme. If :option:`-d` is used, the + HTTP upgrade request is performed with OPTIONS method. .. option:: -p, --weight= - Sets priority group weight. The valid value - range is [1, 256], inclusive. + Sets priority group weight. The valid value range is + [1, 256], inclusive. Default: ``16`` .. option:: -M, --peer-max-concurrent-streams= - Use as SETTINGS_MAX_CONCURRENT_STREAMS value - of remote endpoint as if it is received in - SETTINGS frame. The default is large enough as - it is seen as unlimited. + Use as SETTINGS_MAX_CONCURRENT_STREAMS value of + remote endpoint as if it is received in SETTINGS frame. + The default is large enough as it is seen as unlimited. -.. option:: -c, --header-table-size= +.. option:: -c, --header-table-size= Specify decoder header table size. .. option:: -b, --padding= - Add at most bytes to a frame payload as - padding. Specify 0 to disable padding. + Add at most bytes to a frame payload as padding. + Specify 0 to disable padding. .. option:: -r, --har= - Output HTTP transactions in HAR format. - If '-' is given, data is written to stdout. + Output HTTP transactions in HAR format. If '-' + is given, data is written to stdout. .. option:: --color @@ -141,13 +134,11 @@ OPTIONS: .. option:: --no-dep - Don't send dependency based priority hint to - server. + Don't send dependency based priority hint to server. .. option:: --dep-idle - Use idle streams as anchor nodes to express - priority. + Use idle streams as anchor nodes to express priority. .. option:: --version @@ -157,6 +148,10 @@ OPTIONS: Display this help and exit. + +The argument is an integer and an optional unit (e.g., 10K is +10 * 1024). Units are K, M and G (powers of 1024). + SEE ALSO -------- diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index b4092061..c564f306 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPD" "1" "January 11, 2015" "0.7.1" "nghttp2" +.TH "NGHTTPD" "1" "January 16, 2015" "0.7.2-DEV" "nghttp2" .SH NAME nghttpd \- HTTP/2 experimental server . @@ -44,45 +44,42 @@ Specify listening port number. .INDENT 0.0 .TP .B -Set path to server\(aqs private key. Required -unless \fI\%\-\-no\-tls\fP is specified. +Set path to server\(aqs private key. Required unless +\fI\%\-\-no\-tls\fP is specified. .UNINDENT .INDENT 0.0 .TP .B -Set path to server\(aqs certificate. Required -unless \fI\%\-\-no\-tls\fP is specified. +Set path to server\(aqs certificate. Required unless +\fI\%\-\-no\-tls\fP is specified. .UNINDENT .SH OPTIONS: .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. Therefore -if this option is used, \fI\%\-d\fP option must be -specified. +Run in a background. If \fI\-D\fP is used, the current working +directory is changed to \(aq\fI/\fP\(aq. Therefore if this option +is used, \fI\%\-d\fP option must be specified. .UNINDENT .INDENT 0.0 .TP .B \-V, \-\-verify\-client -The server sends a client certificate request. -If the client did not return a certificate, the -handshake is terminated. Currently, this option -just requests a client certificate and does not -verify it. +The server sends a client certificate request. If the +client did not return a certificate, the handshake is +terminated. Currently, this option just requests a +client certificate and does not verify it. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-htdocs= -Specify document root. If this option is not -specified, the document root is the current -working directory. +Specify document root. If this option is not specified, +the document root is the current working directory. .UNINDENT .INDENT 0.0 .TP .B \-v, \-\-verbose -Print debug information such as reception/ -transmission of frames and name/value pairs. +Print debug information such as reception/ transmission +of frames and name/value pairs. .UNINDENT .INDENT 0.0 .TP @@ -91,7 +88,7 @@ Disable SSL/TLS. .UNINDENT .INDENT 0.0 .TP -.B \-c, \-\-header\-table\-size= +.B \-c, \-\-header\-table\-size= Specify decoder header table size. .UNINDENT .INDENT 0.0 @@ -102,22 +99,21 @@ Force colored log output. .INDENT 0.0 .TP .B \-p, \-\-push== -Push resources s when is -requested. This option can be used repeatedly to -specify multiple push configurations. and -s are relative to document root. See -\fI\%\-\-htdocs\fP option. Example: \fI\-p\fP/=/foo.png -\fI\-p\fP/doc=/bar.css +Push resources s when is requested. +This option can be used repeatedly to specify multiple +push configurations. and s are +relative to document root. See \fI\%\-\-htdocs\fP option. +Example: \fI\-p\fP/=/foo.png \fI\-p\fP/doc=/bar.css .UNINDENT .INDENT 0.0 .TP .B \-b, \-\-padding= -Add at most bytes to a frame payload as -padding. Specify 0 to disable padding. +Add at most bytes to a frame payload as padding. +Specify 0 to disable padding. .UNINDENT .INDENT 0.0 .TP -.B \-n, \-\-workers= +.B \-n, \-\-workers= Set the number of worker threads. .sp Default: \fB1\fP @@ -130,16 +126,15 @@ Make error response gzipped. .INDENT 0.0 .TP .B \-\-dh\-param\-file= -Path to file that contains DH parameters in PEM -format. Without this option, DHE cipher suites -are not available. +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 \-\-early\-response -Start sending response when request HEADERS is -received, rather than complete request is -received. +Start sending response when request HEADERS is received, +rather than complete request is received. .UNINDENT .INDENT 0.0 .TP @@ -151,6 +146,9 @@ Display version information and exit. .B \-h, \-\-help Display this help and exit. .UNINDENT +.sp +The argument is an integer and an optional unit (e.g., 10K is +10 * 1024). Units are K, M and G (powers of 1024). .SH SEE ALSO .sp \fInghttp(1)\fP, \fInghttpx(1)\fP, \fIh2load(1)\fP diff --git a/doc/nghttpd.1.rst b/doc/nghttpd.1.rst index 005852e1..298d0318 100644 --- a/doc/nghttpd.1.rst +++ b/doc/nghttpd.1.rst @@ -18,48 +18,46 @@ HTTP/2 experimental server .. describe:: - Set path to server's private key. Required - unless :option:`--no-tls` is specified. + + Set path to server's private key. Required unless + :option:`--no-tls` is specified. .. describe:: - Set path to server's certificate. Required - unless :option:`--no-tls` is specified. + Set path to server's certificate. Required unless + :option:`--no-tls` is specified. OPTIONS: -------- .. option:: -D, --daemon - Run in a background. If :option:`-D` is used, the current - working directory is changed to '*/*'. Therefore - if this option is used, :option:`-d` option must be - specified. + Run in a background. If :option:`-D` is used, the current working + directory is changed to '*/*'. Therefore if this option + is used, :option:`-d` option must be specified. .. option:: -V, --verify-client - The server sends a client certificate request. - If the client did not return a certificate, the - handshake is terminated. Currently, this option - just requests a client certificate and does not - verify it. + The server sends a client certificate request. If the + client did not return a certificate, the handshake is + terminated. Currently, this option just requests a + client certificate and does not verify it. .. option:: -d, --htdocs= - Specify document root. If this option is not - specified, the document root is the current - working directory. + Specify document root. If this option is not specified, + the document root is the current working directory. .. option:: -v, --verbose - Print debug information such as reception/ - transmission of frames and name/value pairs. + Print debug information such as reception/ transmission + of frames and name/value pairs. .. option:: --no-tls Disable SSL/TLS. -.. option:: -c, --header-table-size= +.. option:: -c, --header-table-size= Specify decoder header table size. @@ -69,19 +67,18 @@ OPTIONS: .. option:: -p, --push== - Push resources s when is - requested. This option can be used repeatedly to - specify multiple push configurations. and - s are relative to document root. See - :option:`--htdocs` option. Example: :option:`\-p`/=/foo.png - :option:`-p`\/doc=/bar.css + Push resources s when is requested. + This option can be used repeatedly to specify multiple + push configurations. and s are + relative to document root. See :option:`--htdocs` option. + Example: :option:`-p`\/=/foo.png :option:`-p`\/doc=/bar.css .. option:: -b, --padding= - Add at most bytes to a frame payload as - padding. Specify 0 to disable padding. + Add at most bytes to a frame payload as padding. + Specify 0 to disable padding. -.. option:: -n, --workers= +.. option:: -n, --workers= Set the number of worker threads. @@ -93,15 +90,14 @@ OPTIONS: .. option:: --dh-param-file= - Path to file that contains DH parameters in PEM - format. Without this option, DHE cipher suites - are not available. + Path to file that contains DH parameters in PEM format. + Without this option, DHE cipher suites are not + available. .. option:: --early-response - Start sending response when request HEADERS is - received, rather than complete request is - received. + Start sending response when request HEADERS is received, + rather than complete request is received. .. option:: --version @@ -111,6 +107,10 @@ OPTIONS: Display this help and exit. + +The argument is an integer and an optional unit (e.g., 10K is +10 * 1024). Units are K, M and G (powers of 1024). + SEE ALSO -------- diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index 7eb274fa..58f4ff9a 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPX" "1" "January 11, 2015" "0.7.1" "nghttp2" +.TH "NGHTTPX" "1" "January 16, 2015" "0.7.2-DEV" "nghttp2" .SH NAME nghttpx \- HTTP/2 experimental proxy . @@ -39,16 +39,14 @@ A reverse proxy for HTTP/2, HTTP/1 and SPDY. .INDENT 0.0 .TP .B -Set path to server\(aqs private key. Required -unless \fI\%\-p\fP, \fI\%\-\-client\fP or \fI\%\-\-frontend\-no\-tls\fP are -given. +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 -Set path to server\(aqs certificate. Required -unless \fI\%\-p\fP, \fI\%\-\-client\fP or \fI\%\-\-frontend\-no\-tls\fP are -given. +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 @@ -57,30 +55,28 @@ The options are categorized into several groups. .INDENT 0.0 .TP .B \-b, \-\-backend= -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. +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. .sp Default: \fB127.0.0.1,80\fP .UNINDENT .INDENT 0.0 .TP .B \-f, \-\-frontend= -Set frontend host and port. If is \(aq*\(aq, it -assumes all addresses including both IPv4 and -IPv6. +Set frontend host and port. If is \(aq*\(aq, it +assumes all addresses including both IPv4 and IPv6. .sp Default: \fB*,3000\fP .UNINDENT .INDENT 0.0 .TP -.B \-\-backlog= -Set listen backlog size. If \fI\-1\fP is given, -libevent will choose suitable value. +.B \-\-backlog= +Set listen backlog size. .sp -Default: \fB128\fP +Default: \fB512\fP .UNINDENT .INDENT 0.0 .TP @@ -95,150 +91,154 @@ Resolve backend hostname to IPv6 address only. .INDENT 0.0 .TP .B \-\-backend\-http\-proxy\-uri= -Specify proxy URI in the form -\fI\%http:/\fP/[:@]:. If a -proxy requires authentication, specify and -. 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 +Specify proxy URI in the form +\fI\%http:/\fP/[:@]:. If a proxy +requires authentication, specify and . +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= +.B \-n, \-\-workers= Set the number of worker threads. .sp Default: \fB1\fP .UNINDENT .INDENT 0.0 .TP -.B \-\-read\-rate= -Set maximum average read rate on frontend -connection. Setting 0 to this option means read -rate is unlimited. +.B \-\-read\-rate= +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= -Set maximum read burst size on frontend -connection. Setting 0 to this option means read -burst size is unlimited. +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= -Set maximum average write rate on frontend -connection. Setting 0 to this option means write -rate is unlimited. +.B \-\-write\-rate= +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= -Set maximum write burst size on frontend -connection. Setting 0 to this option means write -burst size is unlimited. +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= -Set maximum average read rate on frontend -connection per worker. Setting 0 to this option -means read rate is unlimited. Not implemented -yet. +.B \-\-worker\-read\-rate= +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= -Set maximum read burst size on frontend -connection per worker. Setting 0 to this option -means read burst size is unlimited. Not -implemented yet. +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= -Set maximum average write rate on frontend -connection per worker. Setting 0 to this option -means write rate is unlimited. Not implemented -yet. +.B \-\-worker\-write\-rate= +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= -Set maximum write burst size on frontend -connection per worker. Setting 0 to this option -means write burst size is unlimited. Not -implemented yet. +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= -Set maximum number of simultaneous connections -frontend accepts. Setting 0 means unlimited. +.B \-\-worker\-frontend\-connections= +Set maximum number of simultaneous connections frontend +accepts. Setting 0 means unlimited. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP -.B \-\-backend\-http1\-connections\-per\-host= -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 +.B \-\-backend\-http1\-connections\-per\-host= +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= -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\&. +.B \-\-backend\-http1\-connections\-per\-frontend= +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= -Set maximum number of open files (RLIMIT_NOFILE) -to . If 0 is given, nghttpx does not set the -limit. +Set maximum number of open files (RLIMIT_NOFILE) to . +If 0 is given, nghttpx does not set the limit. .sp Default: \fB0\fP .UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-request\-buffer= +Set buffer size used to store backend request. +.sp +Default: \fB16K\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-backend\-response\-buffer= +Set buffer size used to store backend response. +.sp +Default: \fB64K\fP +.UNINDENT .SS Timeout: .INDENT 0.0 .TP .B \-\-frontend\-http2\-read\-timeout= -Specify read timeout for HTTP/2 and SPDY frontend +Specify read timeout for HTTP/2 and SPDY frontend connection. .sp Default: \fB180\fP @@ -246,32 +246,30 @@ Default: \fB180\fP .INDENT 0.0 .TP .B \-\-frontend\-read\-timeout= -Specify read timeout for HTTP/1.1 frontend -connection. +Specify read timeout for HTTP/1.1 frontend connection. .sp Default: \fB180\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-write\-timeout= -Specify write timeout for all frontend -connections. +Specify write timeout for all frontend connections. .sp Default: \fB30\fP .UNINDENT .INDENT 0.0 .TP .B \-\-stream\-read\-timeout= -Specify read timeout for HTTP/2 and SPDY streams. -0 means no timeout. +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= -Specify write timeout for HTTP/2 and SPDY -streams. 0 means no timeout. +Specify write timeout for HTTP/2 and SPDY streams. 0 +means no timeout. .sp Default: \fB0\fP .UNINDENT @@ -292,17 +290,16 @@ Default: \fB30\fP .INDENT 0.0 .TP .B \-\-backend\-keep\-alive\-timeout= -Specify keep\-alive timeout for backend -connection. +Specify keep\-alive timeout for backend connection. .sp Default: \fB600\fP .UNINDENT .INDENT 0.0 .TP .B \-\-listener\-disable\-timeout= -After accepting connection failed, connection -listener is disabled for a given time in seconds. -Specifying 0 disables this feature. +After accepting connection failed, connection listener +is disabled for a given time in seconds. Specifying 0 +disables this feature. .sp Default: \fB0\fP .UNINDENT @@ -310,67 +307,63 @@ Default: \fB0\fP .INDENT 0.0 .TP .B \-\-ciphers= -Set allowed cipher list. The format of the -string is described in OpenSSL ciphers(1). +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 +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= -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. +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 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. +.B \-\-private\-key\-passwd\-file= +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=: -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. +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= -Explicitly set the content of the TLS SNI -extension. This will default to the backend HOST -name. +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 to file that contains DH parameters in PEM -format. Without this option, DHE cipher suites -are not available. +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= -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. +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\-16,h2\-14,spdy/3.1,http/1.1\fP .UNINDENT @@ -382,82 +375,89 @@ Require and verify client certificate. .INDENT 0.0 .TP .B \-\-verify\-client\-cacert= -Path to file that contains CA certificates to -verify client certificate. The file must be in -PEM format. It can contain multiple -certificates. +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 to file that contains client private key -used in backend client authentication. +Path to file that contains client private key used in +backend client authentication. .UNINDENT .INDENT 0.0 .TP .B \-\-client\-cert\-file= -Path to file that contains client certificate -used in backend client authentication. +Path to file that contains client certificate used in +backend client authentication. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-proto\-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. +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 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. +.B \-\-tls\-ticket\-key\-file= +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= -Set the maximum number of the concurrent streams -in one HTTP/2 and SPDY session. +.B \-c, \-\-http2\-max\-concurrent\-streams= +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= -Sets the per\-stream initial window size of HTTP/2 -SPDY frontend connection. For HTTP/2, the size -is 2**\-1. For SPDY, the size is 2**. +Sets the per\-stream initial window size of HTTP/2 SPDY +frontend connection. For HTTP/2, the size is 2**\-1. +For SPDY, the size is 2**. .sp Default: \fB16\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http2\-connection\-window\-bits= -Sets the per\-connection window size of HTTP/2 and -SPDY frontend connection. For HTTP/2, the size -is 2**\-1. For SPDY, the size is 2**. +Sets the per\-connection window size of HTTP/2 and SPDY +frontend connection. For HTTP/2, the size is +2**\-1. For SPDY, the size is 2**. .sp Default: \fB16\fP .UNINDENT @@ -469,7 +469,7 @@ Disable SSL/TLS on frontend connections. .INDENT 0.0 .TP .B \-\-backend\-http2\-window\-bits= -Sets the initial window size of HTTP/2 backend +Sets the initial window size of HTTP/2 backend connection to 2**\-1. .sp Default: \fB16\fP @@ -477,8 +477,8 @@ Default: \fB16\fP .INDENT 0.0 .TP .B \-\-backend\-http2\-connection\-window\-bits= -Sets the per\-connection window size of HTTP/2 -backend connection to 2**\-1. +Sets the per\-connection window size of HTTP/2 backend +connection to 2**\-1. .sp Default: \fB16\fP .UNINDENT @@ -495,20 +495,20 @@ Don\(aqt crumble cookie header field. .INDENT 0.0 .TP .B \-\-padding= -Add at most 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. +Add at most 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 .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. +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 @@ -518,59 +518,56 @@ Like default mode, but enable secure proxy mode. .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 +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. +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. +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= -Set the severity level of log output. -must be one of INFO, NOTICE, WARN, ERROR and -FATAL. +Set the severity level of log output. must be +one of INFO, NOTICE, WARN, ERROR and FATAL. .sp Default: \fBNOTICE\fP .UNINDENT .INDENT 0.0 .TP .B \-\-accesslog\-file= -Set path to write access log. To reopen file, -send USR1 signal to nghttpx. +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. +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= -Specify format string for access log. The -default format is combined format. The following -variables are available: +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. @@ -583,24 +580,24 @@ $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. +$body_bytes_sent: the number of bytes sent to client +as response body. .IP \(bu 2 -$http_: value of HTTP request header -where \(aq_\(aq in is replaced with \(aq\-\(aq. +$http_: value of HTTP request header where +\(aq_\(aq in 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. +$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. +$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 @@ -608,16 +605,16 @@ Default: \fB$remote_addr \- \- [$time_local] "$request" $status $body_bytes_sent .INDENT 0.0 .TP .B \-\-errorlog\-file= -Set path to write error log. To reopen file, -send USR1 signal to nghttpx. +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. +Send error log to syslog. If this option is used, +\fI\%\-\-errorlog\-file\fP option is ignored. .UNINDENT .INDENT 0.0 .TP @@ -626,86 +623,84 @@ Set syslog facility to . .sp Default: \fBdaemon\fP .UNINDENT -.SS Misc: +.SS HTTP: .INDENT 0.0 .TP .B \-\-add\-x\-forwarded\-for -Append X\-Forwarded\-For header field to the -downstream request. +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. +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. +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. +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 \-\-altsvc= -Specify protocol ID, port, host and origin of -alternative service. and 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 +Specify protocol ID, port, host and origin of +alternative service. and 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=
-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. +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= -Dumps request headers received by HTTP/2 frontend -to the file denoted in . 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, where >= 2. +Dumps request headers received by HTTP/2 frontend to the +file denoted in . 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, where >= 2. .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http2\-dump\-response\-header= -Dumps response headers sent from HTTP/2 frontend -to the file denoted in . 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, where >= 2. +Dumps response headers sent from HTTP/2 frontend to the +file denoted in . 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, where >= 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. +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. +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 @@ -715,9 +710,10 @@ Set path to save PID of this program. .INDENT 0.0 .TP .B \-\-user= -Run this program as . This option is -intended to be used to drop root privileges. +Run this program as . This option is intended to +be used to drop root privileges. .UNINDENT +.SS Misc: .INDENT 0.0 .TP .B \-\-conf= @@ -735,6 +731,9 @@ Print version and exit. .B \-h, \-\-help Print this help and exit. .UNINDENT +.sp +The argument is an integer and an optional unit (e.g., 10K is +10 * 1024). Units are K, M and G (powers of 1024). .SH FILES .INDENT 0.0 .TP diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst index d2d44934..0ac99fbf 100644 --- a/doc/nghttpx.1.rst +++ b/doc/nghttpx.1.rst @@ -14,15 +14,15 @@ A reverse proxy for HTTP/2, HTTP/1 and SPDY. .. describe:: - Set path to server's private key. Required - unless :option:`-p`\, :option:`--client` or :option:`\--frontend-no-tls` are - given. + + Set path to server's private key. Required unless :option:`-p`\, + :option:`--client` or :option:`\--frontend-no-tls` are given. .. describe:: - Set path to server's certificate. Required - unless :option:`-p`\, :option:`--client` or :option:`\--frontend-no-tls` are - given. + Set path to server's certificate. Required unless :option:`-p`\, + :option:`--client` or :option:`\--frontend-no-tls` are given. + OPTIONS: -------- @@ -34,28 +34,26 @@ Connections: .. option:: -b, --backend= - 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. + 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`` .. option:: -f, --frontend= - Set frontend host and port. If is '\*', it - assumes all addresses including both IPv4 and - IPv6. + Set frontend host and port. If is '\*', it + assumes all addresses including both IPv4 and IPv6. Default: ``*,3000`` -.. option:: --backlog= +.. option:: --backlog= - Set listen backlog size. If :option:`-1` is given, - libevent will choose suitable value. + Set listen backlog size. - Default: ``128`` + Default: ``512`` .. option:: --backend-ipv4 @@ -67,171 +65,171 @@ Connections: .. option:: --backend-http-proxy-uri= - Specify proxy URI in the form - http://[:@]:. If a - proxy requires authentication, specify and - . 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 - :option:`--backend-read-timeout` and + Specify proxy URI in the form + http://[:@]:. If a proxy + requires authentication, specify and . + 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 :option:`--backend-read-timeout` and :option:`--backend-write-timeout` options. Performance: ~~~~~~~~~~~~ -.. option:: -n, --workers= +.. option:: -n, --workers= Set the number of worker threads. Default: ``1`` -.. option:: --read-rate= +.. option:: --read-rate= - Set maximum average read rate on frontend - connection. Setting 0 to this option means read - rate is unlimited. + Set maximum average read rate on frontend connection. + Setting 0 to this option means read rate is unlimited. Default: ``0`` .. option:: --read-burst= - Set maximum read burst size on frontend - connection. Setting 0 to this option means read - burst size is unlimited. + Set maximum read burst size on frontend connection. + Setting 0 to this option means read burst size is + unlimited. Default: ``0`` -.. option:: --write-rate= +.. option:: --write-rate= - Set maximum average write rate on frontend - connection. Setting 0 to this option means write - rate is unlimited. + Set maximum average write rate on frontend connection. + Setting 0 to this option means write rate is unlimited. Default: ``0`` .. option:: --write-burst= - Set maximum write burst size on frontend - connection. Setting 0 to this option means write - burst size is unlimited. + Set maximum write burst size on frontend connection. + Setting 0 to this option means write burst size is + unlimited. Default: ``0`` -.. option:: --worker-read-rate= +.. option:: --worker-read-rate= - Set maximum average read rate on frontend - connection per worker. Setting 0 to this option - means read rate is unlimited. Not implemented - yet. + 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`` .. option:: --worker-read-burst= - Set maximum read burst size on frontend - connection per worker. Setting 0 to this option - means read burst size is unlimited. Not - implemented yet. + 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`` -.. option:: --worker-write-rate= +.. option:: --worker-write-rate= - Set maximum average write rate on frontend - connection per worker. Setting 0 to this option - means write rate is unlimited. Not implemented - yet. + 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`` .. option:: --worker-write-burst= - Set maximum write burst size on frontend - connection per worker. Setting 0 to this option - means write burst size is unlimited. Not - implemented yet. + 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`` -.. option:: --worker-frontend-connections= +.. option:: --worker-frontend-connections= - Set maximum number of simultaneous connections - frontend accepts. Setting 0 means unlimited. + Set maximum number of simultaneous connections frontend + accepts. Setting 0 means unlimited. Default: ``0`` -.. option:: --backend-http1-connections-per-host= +.. option:: --backend-http1-connections-per-host= - Set maximum number of backend concurrent HTTP/1 - connections per host. This option is meaningful - when :option:`-s` option is used. To limit the number of - connections per frontend for default mode, use + Set maximum number of backend concurrent HTTP/1 + connections per host. This option is meaningful when :option:`-s` + option is used. To limit the number of connections per + frontend for default mode, use :option:`--backend-http1-connections-per-frontend`\. Default: ``8`` -.. option:: --backend-http1-connections-per-frontend= +.. option:: --backend-http1-connections-per-frontend= - 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 - :option:`--backend-http1-connections-per-host`\. + 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 :option:`--backend-http1-connections-per-host`\. Default: ``0`` .. option:: --rlimit-nofile= - Set maximum number of open files (RLIMIT_NOFILE) - to . If 0 is given, nghttpx does not set the - limit. + Set maximum number of open files (RLIMIT_NOFILE) to . + If 0 is given, nghttpx does not set the limit. Default: ``0`` +.. option:: --backend-request-buffer= + + Set buffer size used to store backend request. + + Default: ``16K`` + +.. option:: --backend-response-buffer= + + Set buffer size used to store backend response. + + Default: ``64K`` + Timeout: ~~~~~~~~ .. option:: --frontend-http2-read-timeout= - Specify read timeout for HTTP/2 and SPDY frontend + Specify read timeout for HTTP/2 and SPDY frontend connection. Default: ``180`` .. option:: --frontend-read-timeout= - Specify read timeout for HTTP/1.1 frontend - connection. + Specify read timeout for HTTP/1.1 frontend connection. Default: ``180`` .. option:: --frontend-write-timeout= - Specify write timeout for all frontend - connections. + Specify write timeout for all frontend connections. Default: ``30`` .. option:: --stream-read-timeout= - Specify read timeout for HTTP/2 and SPDY streams. - 0 means no timeout. + Specify read timeout for HTTP/2 and SPDY streams. 0 + means no timeout. Default: ``0`` .. option:: --stream-write-timeout= - Specify write timeout for HTTP/2 and SPDY - streams. 0 means no timeout. + Specify write timeout for HTTP/2 and SPDY streams. 0 + means no timeout. Default: ``0`` @@ -249,16 +247,15 @@ Timeout: .. option:: --backend-keep-alive-timeout= - Specify keep-alive timeout for backend - connection. + Specify keep-alive timeout for backend connection. Default: ``600`` .. option:: --listener-disable-timeout= - After accepting connection failed, connection - listener is disabled for a given time in seconds. - Specifying 0 disables this feature. + After accepting connection failed, connection listener + is disabled for a given time in seconds. Specifying 0 + disables this feature. Default: ``0`` @@ -268,60 +265,56 @@ SSL/TLS: .. option:: --ciphers= - Set allowed cipher list. The format of the - string is described in OpenSSL ciphers(1). + Set allowed cipher list. The format of the string is + described in OpenSSL ciphers(1). .. option:: -k, --insecure - Don't verify backend server's certificate if :option:`-p`\, - :option:`--client` or :option:`\--http2-bridge` are given and + Don't verify backend server's certificate if :option:`-p`\, + :option:`--client` or :option:`\--http2-bridge` are given and :option:`--backend-no-tls` is not given. .. option:: --cacert= - Set path to trusted CA certificate file if :option:`-p`\, - :option:`--client` or :option:`\--http2-bridge` are given and - :option:`--backend-no-tls` 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. + Set path to trusted CA certificate file if :option:`-p`\, :option:`--client` + or :option:`--http2-bridge` are given and :option:`\--backend-no-tls` 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. -.. option:: --private-key-passwd-file= +.. option:: --private-key-passwd-file= - 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. + 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. .. option:: --subcert=: - 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. + 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. .. option:: --backend-tls-sni-field= - Explicitly set the content of the TLS SNI - extension. This will default to the backend HOST - name. + Explicitly set the content of the TLS SNI extension. + This will default to the backend HOST name. .. option:: --dh-param-file= - Path to file that contains DH parameters in PEM - format. Without this option, DHE cipher suites - are not available. + Path to file that contains DH parameters in PEM format. + Without this option, DHE cipher suites are not + available. .. option:: --npn-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. + 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`` @@ -331,78 +324,84 @@ SSL/TLS: .. option:: --verify-client-cacert= - Path to file that contains CA certificates to - verify client certificate. The file must be in - PEM format. It can contain multiple - certificates. + Path to file that contains CA certificates to verify + client certificate. The file must be in PEM format. It + can contain multiple certificates. .. option:: --client-private-key-file= - Path to file that contains client private key - used in backend client authentication. + Path to file that contains client private key used in + backend client authentication. .. option:: --client-cert-file= - Path to file that contains client certificate - used in backend client authentication. + Path to file that contains client certificate used in + backend client authentication. .. option:: --tls-proto-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. + 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`` -.. option:: --tls-ticket-key-file= +.. option:: --tls-ticket-key-file= - 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. + 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. + +.. option:: --tls-ctx-per-worker + + Create OpenSSL's 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. HTTP/2 and SPDY: ~~~~~~~~~~~~~~~~ -.. option:: -c, --http2-max-concurrent-streams= +.. option:: -c, --http2-max-concurrent-streams= - Set the maximum number of the concurrent streams - in one HTTP/2 and SPDY session. + Set the maximum number of the concurrent streams in one + HTTP/2 and SPDY session. Default: ``100`` .. option:: --frontend-http2-window-bits= - Sets the per-stream initial window size of HTTP/2 - SPDY frontend connection. For HTTP/2, the size - is 2**-1. For SPDY, the size is 2\*\*. + Sets the per-stream initial window size of HTTP/2 SPDY + frontend connection. For HTTP/2, the size is 2\*\*-1. + For SPDY, the size is 2\*\*. Default: ``16`` .. option:: --frontend-http2-connection-window-bits= - Sets the per-connection window size of HTTP/2 and - SPDY frontend connection. For HTTP/2, the size - is 2**-1. For SPDY, the size is 2\*\*. + Sets the per-connection window size of HTTP/2 and SPDY + frontend connection. For HTTP/2, the size is + 2**-1. For SPDY, the size is 2\*\*. Default: ``16`` @@ -412,15 +411,15 @@ HTTP/2 and SPDY: .. option:: --backend-http2-window-bits= - Sets the initial window size of HTTP/2 backend - connection to 2**-1. + Sets the initial window size of HTTP/2 backend + connection to 2\*\*-1. Default: ``16`` .. option:: --backend-http2-connection-window-bits= - Sets the per-connection window size of HTTP/2 - backend connection to 2\*\*-1. + Sets the per-connection window size of HTTP/2 backend + connection to 2\*\*-1. Default: ``16`` @@ -434,10 +433,10 @@ HTTP/2 and SPDY: .. option:: --padding= - Add at most 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. + Add at most 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. Mode: @@ -445,11 +444,12 @@ Mode: .. describe:: (default mode) - Accept HTTP/2, SPDY and HTTP/1.1 over SSL/TLS. - If :option:`--frontend-no-tls` 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. + + Accept HTTP/2, SPDY and HTTP/1.1 over SSL/TLS. If + :option:`--frontend-no-tls` 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. .. option:: -s, --http2-proxy @@ -457,28 +457,26 @@ Mode: .. option:: --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 - :option:`--backend-http-proxy-uri` option if you are behind - the proxy and want to connect to the outside + 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 :option:`--backend-http-proxy-uri` option if you are + behind the proxy and want to connect to the outside HTTP/2 proxy. .. option:: --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 :option:`-p` option - instead. + 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 :option:`-p` option instead. .. option:: -p, --client-proxy - Like :option:`--client` option, but it also requires the - request path from frontend must be an absolute - URI, suitable for use as a forward proxy. + Like :option:`--client` option, but it also requires the request + path from frontend must be an absolute URI, suitable for + use as a forward proxy. Logging: @@ -486,60 +484,59 @@ Logging: .. option:: -L, --log-level= - Set the severity level of log output. - must be one of INFO, NOTICE, WARN, ERROR and - FATAL. + Set the severity level of log output. must be + one of INFO, NOTICE, WARN, ERROR and FATAL. Default: ``NOTICE`` .. option:: --accesslog-file= - Set path to write access log. To reopen file, - send USR1 signal to nghttpx. + Set path to write access log. To reopen file, send USR1 + signal to nghttpx. .. option:: --accesslog-syslog - Send access log to syslog. If this option is - used, :option:`--accesslog-file` option is ignored. + Send access log to syslog. If this option is used, + :option:`--accesslog-file` option is ignored. .. option:: --accesslog-format= - Specify format string for access log. The - default format is combined format. The following - variables are available: + 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_: value of HTTP request header - where '_' in is replaced with '-'. + * $body_bytes_sent: the number of bytes sent to client + as response body. + * $http_: value of HTTP request header where + '_' in is replaced with '-'. * $remote_port: client port. * $server_port: server port. - * $request_time: request processing time in - seconds with milliseconds resolution. + * $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. + * $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"`` .. option:: --errorlog-file= - Set path to write error log. To reopen file, - send USR1 signal to nghttpx. + Set path to write error log. To reopen file, send USR1 + signal to nghttpx. Default: ``/dev/stderr`` .. option:: --errorlog-syslog - Send error log to syslog. If this option is - used, :option:`--errorlog-file` option is ignored. + Send error log to syslog. If this option is used, + :option:`--errorlog-file` option is ignored. .. option:: --syslog-facility= @@ -548,78 +545,82 @@ Logging: Default: ``daemon`` -Misc: +HTTP: ~~~~~ .. option:: --add-x-forwarded-for - Append X-Forwarded-For header field to the - downstream request. + Append X-Forwarded-For header field to the downstream + request. .. option:: --strip-incoming-x-forwarded-for - Strip X-Forwarded-For header field from inbound - client requests. + Strip X-Forwarded-For header field from inbound client + requests. .. option:: --no-via - Don't append to Via header field. If Via header - field is received, it is left unaltered. + Don't append to Via header field. If Via header field + is received, it is left unaltered. .. option:: --no-location-rewrite - Don't rewrite location header field on - :option:`--http2-bridge`\, :option:`--client` and default mode. For - :option:`--http2-proxy` and :option:`\--client-proxy` mode, location - header field will not be altered regardless of - this option. + Don't rewrite location header field on :option:`--http2-bridge`\, + :option:`--client` and default mode. For :option:`\--http2-proxy` and + :option:`--client-proxy` mode, location header field will not be + altered regardless of this option. .. option:: --altsvc= - Specify protocol ID, port, host and origin of - alternative service. and 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: :option:`--altsvc`\=h2,443 + Specify protocol ID, port, host and origin of + alternative service. and 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: + :option:`--altsvc`\=h2,443 .. option:: --add-response-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. + 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: :option:`--add-response-header`\="foo: bar" + +Debug: +~~~~~~ + .. option:: --frontend-http2-dump-request-header= - Dumps request headers received by HTTP/2 frontend - to the file denoted in . 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 :option:`-n`\, where >= 2. + Dumps request headers received by HTTP/2 frontend to the + file denoted in . 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 :option:`-n`\, where >= 2. .. option:: --frontend-http2-dump-response-header= - Dumps response headers sent from HTTP/2 frontend - to the file denoted in . 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 :option:`-n`\, where >= 2. + Dumps response headers sent from HTTP/2 frontend to the + file denoted in . 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 :option:`-n`\, where >= 2. .. option:: -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 :option:`-n`\=N, where N >= 2. + Print HTTP/2 frames in frontend to stderr. This option + is not thread safe and MUST NOT be used with option + :option:`-n`\=N, where N >= 2. + + +Process: +~~~~~~~~ .. option:: -D, --daemon - Run in a background. If :option:`-D` is used, the current - working directory is changed to '*/*'. + Run in a background. If :option:`-D` is used, the current working + directory is changed to '*/*'. .. option:: --pid-file= @@ -627,8 +628,12 @@ Misc: .. option:: --user= - Run this program as . This option is - intended to be used to drop root privileges. + Run this program as . This option is intended to + be used to drop root privileges. + + +Misc: +~~~~~ .. option:: --conf= @@ -644,6 +649,10 @@ Misc: Print this help and exit. + +The argument is an integer and an optional unit (e.g., 10K is +10 * 1024). Units are K, M and G (powers of 1024). + FILES -----