diff --git a/doc/Makefile.am b/doc/Makefile.am index 544f42e3..a9d34049 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -176,7 +176,7 @@ text: @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." -man: +man: apiref.rst $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." diff --git a/doc/conf.py.in b/doc/conf.py.in index 3276221b..0e572cf3 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -64,7 +64,7 @@ master_doc = 'index' # General information about the project. project = u'nghttp2' -copyright = u'2012, 2014, Tatsuhiro Tsujikawa' +copyright = u'2012, 2015, Tatsuhiro Tsujikawa' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -242,6 +242,12 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'nghttp2', u'nghttp2 Documentation', + ('nghttp.1', 'nghttp', u'HTTP/2 experimental client', + [u'Tatsuhiro Tsujikawa'], 1), + ('nghttpd.1', 'nghttpd', u'HTTP/2 experimental server', + [u'Tatsuhiro Tsujikawa'], 1), + ('nghttpx.1', 'nghttpx', u'HTTP/2 experimental proxy', + [u'Tatsuhiro Tsujikawa'], 1), + ('h2load.1', 'h2load', u'HTTP/2 benchmarking tool', [u'Tatsuhiro Tsujikawa'], 1) ] diff --git a/doc/h2load.1 b/doc/h2load.1 index 98d69216..69537faf 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -1,14 +1,44 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.4. -.TH H2LOAD "1" "January 2015" "h2load nghttp2/0.7.0" "User Commands" +.\" Man page generated from reStructuredText. +. +.TH "H2LOAD" "1" "January 10, 2015" "0.7.1-DEV" "nghttp2" .SH NAME h2load \- HTTP/2 benchmarking tool +. +.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 -.B h2load -[\fI\,OPTIONS\/\fR]... [\fI\,URI\/\fR]... +.sp +\fBh2load\fP [OPTIONS]... [URI]... .SH DESCRIPTION +.sp 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 @@ -16,60 +46,101 @@ 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. -.SH OPTIONS -.HP -\fB\-n\fR, \fB\-\-requests=\fR Number of requests. Default: 1 +.UNINDENT +.SH OPTIONS: +.INDENT 0.0 .TP -\fB\-c\fR, \fB\-\-clients=\fR -Number of concurrent clients. Default: 1 +.B \-n, \-\-requests= +Number of requests. +.sp +Default: \fB1\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-t\fR, \fB\-\-threads=\fR -Number of native threads. Default: 1 +.B \-c, \-\-clients= +Number of concurrent clients. +.sp +Default: \fB1\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-i\fR, \fB\-\-input\-file=\fR +.B \-t, \-\-threads= +Number of native threads. +.sp +Default: \fB1\fP +.UNINDENT +.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 '\-' is given as , +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 -\fB\-m\fR, \fB\-\-max\-concurrent\-streams=\fR(auto|) +.B \-m, \-\-max\-concurrent\-streams=(auto|) Max concurrent streams to issue per session. If "auto" is given, the number of given URIs is -used. Default: auto +used. +.sp +Default: \fBauto\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-w\fR, \fB\-\-window\-bits=\fR +.B \-w, \-\-window\-bits= Sets the stream level initial window size to (2**)\-1. For SPDY, 2** is used instead. +.UNINDENT +.INDENT 0.0 .TP -\fB\-W\fR, \fB\-\-connection\-window\-bits=\fR +.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. +.UNINDENT +.INDENT 0.0 .TP -\fB\-H\fR, \fB\-\-header=\fR
+.B \-H, \-\-header=
Add/Override a header to the requests. +.UNINDENT +.INDENT 0.0 .TP -\fB\-p\fR, \fB\-\-no\-tls\-proto=\fR +.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 -Default: h2c\-14 +.sp +Default: \fBh2c\-14\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-v\fR, \fB\-\-verbose\fR +.B \-v, \-\-verbose Output debug information. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-version\fR +.B \-\-version Display version information and exit. +.UNINDENT +.INDENT 0.0 .TP -\fB\-h\fR, \fB\-\-help\fR +.B \-h, \-\-help Display this help and exit. -.SH "SEE ALSO" - -nghttp(1), nghttpd(1), nghttpx(1) +.UNINDENT +.SH SEE ALSO +.sp +\fInghttp(1)\fP, \fInghttpd(1)\fP, \fInghttpx(1)\fP +.SH AUTHOR +Tatsuhiro Tsujikawa +.SH COPYRIGHT +2012, 2014, Tatsuhiro Tsujikawa +.\" Generated by docutils manpage writer. +. diff --git a/doc/h2load.1.rst b/doc/h2load.1.rst index 9022005a..120bda1b 100644 --- a/doc/h2load.1.rst +++ b/doc/h2load.1.rst @@ -1,23 +1,18 @@ -.. DO NOT MODIFY THIS FILE! It was generated by man2rst.py - -.. program:: h2load h2load(1) ========= -NAME ----- -h2load - HTTP/2 benchmarking tool - SYNOPSIS -------- + **h2load** [OPTIONS]... [URI]... DESCRIPTION ----------- + benchmarking tool for HTTP/2 and SPDY server -.. option:: URI +.. describe:: Specify URI to access. Multiple URIs can be specified. URIs are used in this order for each @@ -27,26 +22,29 @@ benchmarking tool for HTTP/2 and SPDY server are ignored. Those in the first URI are used solely. -OPTIONS -------- +OPTIONS: +-------- .. option:: -n, --requests= - Number of requests. Default: 1 + Number of requests. + + Default: ``1`` .. option:: -c, --clients= - - Number of concurrent clients. Default: 1 + Number of concurrent clients. + + Default: ``1`` .. option:: -t, --threads= - - Number of native threads. Default: 1 + Number of native threads. + + Default: ``1`` .. 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 , @@ -59,55 +57,50 @@ OPTIONS .. option:: -m, --max-concurrent-streams=(auto|) - Max concurrent streams to issue per session. If "auto" is given, the number of given URIs is - used. Default: auto + used. + + Default: ``auto`` .. option:: -w, --window-bits= - Sets the stream level initial window size to - (2\*\*)-1. For SPDY, 2\*\* is used instead. + (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 + (2**)-1. For SPDY, if is strictly less than 16, this option is ignored. Otherwise - 2\*\* is used for SPDY. + 2** is used for SPDY. .. option:: -H, --header=
- Add/Override a header to the requests. .. 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 - Default: h2c-14 + + Default: ``h2c-14`` .. option:: -v, --verbose - Output debug information. .. option:: --version - Display version information and exit. .. option:: -h, --help - Display this help and exit. SEE ALSO -------- -nghttp(1), nghttpd(1), nghttpx(1) +:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`nghttpx(1)` diff --git a/doc/h2load.h2m b/doc/h2load.h2m deleted file mode 100644 index c74e1116..00000000 --- a/doc/h2load.h2m +++ /dev/null @@ -1,3 +0,0 @@ -[SEE ALSO] - -nghttp(1), nghttpd(1), nghttpx(1) diff --git a/doc/h2load.h2r b/doc/h2load.h2r new file mode 100644 index 00000000..ac90672c --- /dev/null +++ b/doc/h2load.h2r @@ -0,0 +1,4 @@ +SEE ALSO +-------- + +:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`nghttpx(1)` diff --git a/doc/nghttp.1 b/doc/nghttp.1 index 205d8a9c..eebdfcdf 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -1,44 +1,88 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.4. -.TH NGHTTP "1" "January 2015" "nghttp nghttp2/0.7.0" "User Commands" +.\" Man page generated from reStructuredText. +. +.TH "NGHTTP" "1" "January 10, 2015" "0.7.1-DEV" "nghttp2" .SH NAME nghttp \- HTTP/2 experimental client +. +.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 -.B nghttp -[\fI\,OPTIONS\/\fR]... \fI\,\/\fR... +.sp +\fBnghttp\fP [OPTIONS]... ... .SH DESCRIPTION +.sp HTTP/2 experimental client +.INDENT 0.0 .TP - +.B Specify URI to access. -.SH OPTIONS +.UNINDENT +.SH OPTIONS: +.INDENT 0.0 .TP -\fB\-v\fR, \fB\-\-verbose\fR +.B \-v, \-\-verbose 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 -\fB\-n\fR, \fB\-\-null\-out\fR +.B \-n, \-\-null\-out Discard downloaded data. +.UNINDENT +.INDENT 0.0 .TP -\fB\-O\fR, \fB\-\-remote\-name\fR +.B \-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 +\(aq\fI/\fP\(aq, \(aqindex.html\(aq is used as a filename. Not implemented yet. +.UNINDENT +.INDENT 0.0 .TP -\fB\-t\fR, \fB\-\-timeout=\fR +.B \-t, \-\-timeout= Timeout each request after seconds. +.UNINDENT +.INDENT 0.0 .TP -\fB\-w\fR, \fB\-\-window\-bits=\fR +.B \-w, \-\-window\-bits= Sets the stream level initial window size to 2**\-1. +.UNINDENT +.INDENT 0.0 .TP -\fB\-W\fR, \fB\-\-connection\-window\-bits=\fR +.B \-W, \-\-connection\-window\-bits= Sets the connection level initial window size to 2**\-1. +.UNINDENT +.INDENT 0.0 .TP -\fB\-a\fR, \fB\-\-get\-assets\fR +.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 @@ -47,81 +91,127 @@ 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 -\fB\-s\fR, \fB\-\-stat\fR +.B \-s, \-\-stat Print statistics. +.UNINDENT +.INDENT 0.0 .TP -\fB\-H\fR, \fB\-\-header=\fR
+.B \-H, \-\-header=
Add a header to the requests. Example: -\fB\-H\fR':method: PUT' +\fI\%\-H\fP\(aq:method: PUT\(aq +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-cert=\fR +.B \-\-cert= Use the specified client certificate file. The file must be in PEM format. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-key=\fR +.B \-\-key= Use the client private key file. The file must be in PEM format. +.UNINDENT +.INDENT 0.0 .TP -\fB\-d\fR, \fB\-\-data=\fR -Post FILE to server. If '\-' is given, data will +.B \-d, \-\-data= +Post FILE to server. If \(aq\-\(aq is given, data will be read from stdin. +.UNINDENT +.INDENT 0.0 .TP -\fB\-m\fR, \fB\-\-multiply=\fR Request each URI times. -By default, same URI +.B \-m, \-\-multiply= +Request each URI times. By default, same URI is not requested twice. This option disables it too. +.UNINDENT +.INDENT 0.0 .TP -\fB\-u\fR, \fB\-\-upgrade\fR +.B \-u, \-\-upgrade Perform HTTP Upgrade for HTTP/2. This option is ignored if the request URI has https scheme. If -\fB\-d\fR is used, the HTTP upgrade request is performed +\fI\-d\fP is used, the HTTP upgrade request is performed with OPTIONS method. +.UNINDENT +.INDENT 0.0 .TP -\fB\-p\fR, \fB\-\-weight=\fR +.B \-p, \-\-weight= Sets priority group weight. The valid value range is [1, 256], inclusive. -Default: 16 +.sp +Default: \fB16\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-M\fR, \fB\-\-peer\-max\-concurrent\-streams=\fR +.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. +.UNINDENT +.INDENT 0.0 .TP -\fB\-c\fR, \fB\-\-header\-table\-size=\fR +.B \-c, \-\-header\-table\-size= Specify decoder header table size. +.UNINDENT +.INDENT 0.0 .TP -\fB\-b\fR, \fB\-\-padding=\fR +.B \-b, \-\-padding= Add at most bytes to a frame payload as padding. Specify 0 to disable padding. +.UNINDENT +.INDENT 0.0 .TP -\fB\-r\fR, \fB\-\-har=\fR +.B \-r, \-\-har= Output HTTP transactions in HAR format. -If '\-' is given, data is written to stdout. +If \(aq\-\(aq is given, data is written to stdout. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-color\fR +.B \-\-color Force colored log output. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-continuation\fR +.B \-\-continuation Send large header to test CONTINUATION. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-no\-content\-length\fR -Don't send content\-length header field. +.B \-\-no\-content\-length +Don\(aqt send content\-length header field. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-no\-dep\fR -Don't send dependency based priority hint to +.B \-\-no\-dep +Don\(aqt send dependency based priority hint to server. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-dep\-idle\fR +.B \-\-dep\-idle Use idle streams as anchor nodes to express priority. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-version\fR +.B \-\-version Display version information and exit. +.UNINDENT +.INDENT 0.0 .TP -\fB\-h\fR, \fB\-\-help\fR +.B \-h, \-\-help Display this help and exit. -.SH "SEE ALSO" - -nghttpd(1), nghttpx(1), h2load(1) +.UNINDENT +.SH SEE ALSO +.sp +\fInghttpd(1)\fP, \fInghttpx(1)\fP, \fIh2load(1)\fP +.SH AUTHOR +Tatsuhiro Tsujikawa +.SH COPYRIGHT +2012, 2014, Tatsuhiro Tsujikawa +.\" Generated by docutils manpage writer. +. diff --git a/doc/nghttp.1.rst b/doc/nghttp.1.rst index de8c4208..6103dbf0 100644 --- a/doc/nghttp.1.rst +++ b/doc/nghttp.1.rst @@ -1,32 +1,26 @@ -.. DO NOT MODIFY THIS FILE! It was generated by man2rst.py - -.. program:: nghttp nghttp(1) ========= -NAME ----- -nghttp - HTTP/2 experimental client - SYNOPSIS -------- + **nghttp** [OPTIONS]... ... DESCRIPTION ----------- + HTTP/2 experimental client -.. option:: URI +.. describe:: Specify URI to access. -OPTIONS -------- +OPTIONS: +-------- .. option:: -v, --verbose - Print debug information such as reception and transmission of frames and name/value pairs. Specifying this option multiple times increases @@ -34,37 +28,31 @@ OPTIONS .. option:: -n, --null-out - Discard downloaded data. .. 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 + '*/*', 'index.html' is used as a filename. Not implemented yet. .. option:: -t, --timeout= - Timeout each request after seconds. .. option:: -w, --window-bits= - Sets the stream level initial window size to 2\*\*-1. .. option:: -W, --connection-window-bits= - 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 @@ -76,43 +64,36 @@ OPTIONS .. option:: -s, --stat - Print statistics. .. option:: -H, --header=
- Add a header to the requests. Example: - -H':method: PUT' + :option:`-H`\':method: PUT' .. option:: --cert= - 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. .. option:: -d, --data= - Post FILE to server. If '-' is given, data will be read from stdin. .. option:: -m, --multiply= - Request each URI times. - By default, same URI + 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 @@ -120,14 +101,13 @@ OPTIONS .. option:: -p, --weight= - Sets priority group weight. The valid value range is [1, 256], inclusive. - Default: 16 + + 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 @@ -135,59 +115,49 @@ OPTIONS .. 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. .. option:: -r, --har= - Output HTTP transactions in HAR format. If '-' is given, data is written to stdout. .. option:: --color - Force colored log output. .. option:: --continuation - Send large header to test CONTINUATION. .. option:: --no-content-length - Don't send content-length header field. .. option:: --no-dep - Don't send dependency based priority hint to server. .. option:: --dep-idle - Use idle streams as anchor nodes to express priority. .. option:: --version - Display version information and exit. .. option:: -h, --help - Display this help and exit. SEE ALSO -------- -nghttpd(1), nghttpx(1), h2load(1) +:manpage:`nghttpd(1)`, :manpage:`nghttpx(1)`, :manpage:`h2load(1)` diff --git a/doc/nghttp.h2m b/doc/nghttp.h2m deleted file mode 100644 index eac6ec0c..00000000 --- a/doc/nghttp.h2m +++ /dev/null @@ -1,3 +0,0 @@ -[SEE ALSO] - -nghttpd(1), nghttpx(1), h2load(1) diff --git a/doc/nghttp.h2r b/doc/nghttp.h2r new file mode 100644 index 00000000..a27f416f --- /dev/null +++ b/doc/nghttp.h2r @@ -0,0 +1,4 @@ +SEE ALSO +-------- + +:manpage:`nghttpd(1)`, :manpage:`nghttpx(1)`, :manpage:`h2load(1)` diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index 580486a9..359cc033 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -1,93 +1,162 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.4. -.TH NGHTTPD "1" "January 2015" "nghttpd nghttp2/0.7.0" "User Commands" +.\" Man page generated from reStructuredText. +. +.TH "NGHTTPD" "1" "January 10, 2015" "0.7.1-DEV" "nghttp2" .SH NAME nghttpd \- HTTP/2 experimental server +. +.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 -.B nghttpd -[\fI\,OPTION\/\fR]... \fI\, \/\fR -.br -.B nghttpd -\fI\,--no-tls \/\fR[\fI\,OPTION\/\fR]... \fI\,\/\fR +.sp +\fBnghttpd\fP [OPTION]... [ ] .SH DESCRIPTION +.sp HTTP/2 experimental server +.INDENT 0.0 .TP - +.B Specify listening port number. +.UNINDENT +.INDENT 0.0 .TP - -Set path to server's private key. Required -unless \fB\-\-no\-tls\fR is specified. +.B +Set path to server\(aqs private key. Required +unless \fI\%\-\-no\-tls\fP is specified. +.UNINDENT +.INDENT 0.0 .TP - -Set path to server's certificate. Required -unless \fB\-\-no\-tls\fR is specified. -.SH OPTIONS +.B +Set path to server\(aqs certificate. Required +unless \fI\%\-\-no\-tls\fP is specified. +.UNINDENT +.SH OPTIONS: +.INDENT 0.0 .TP -\fB\-D\fR, \fB\-\-daemon\fR -Run in a background. If \fB\-D\fR is used, the current -working directory is changed to '/'. Therefore -if this option is used, \fB\-d\fR option must be +.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. +.UNINDENT +.INDENT 0.0 .TP -\fB\-V\fR, \fB\-\-verify\-client\fR +.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. +.UNINDENT +.INDENT 0.0 .TP -\fB\-d\fR, \fB\-\-htdocs=\fR +.B \-d, \-\-htdocs= Specify document root. If this option is not specified, the document root is the current working directory. +.UNINDENT +.INDENT 0.0 .TP -\fB\-v\fR, \fB\-\-verbose\fR +.B \-v, \-\-verbose Print debug information such as reception/ transmission of frames and name/value pairs. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-no\-tls\fR +.B \-\-no\-tls Disable SSL/TLS. +.UNINDENT +.INDENT 0.0 .TP -\fB\-c\fR, \fB\-\-header\-table\-size=\fR +.B \-c, \-\-header\-table\-size= Specify decoder header table size. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-color\fR +.B \-\-color Force colored log output. +.UNINDENT +.INDENT 0.0 .TP -\fB\-p\fR, \fB\-\-push=\fR= +.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 -\fB\-\-htdocs\fR option. Example: \fB\-p\fR/=/foo.png -\fB\-p\fR/doc=/bar.css +\fI\%\-\-htdocs\fP option. Example: \fI\-p\fP/=/foo.png +\fI\-p\fP/doc=/bar.css +.UNINDENT +.INDENT 0.0 .TP -\fB\-b\fR, \fB\-\-padding=\fR +.B \-b, \-\-padding= Add at most bytes to a frame payload as padding. Specify 0 to disable padding. +.UNINDENT +.INDENT 0.0 .TP -\fB\-n\fR, \fB\-\-workers=\fR +.B \-n, \-\-workers= Set the number of worker threads. -Default: 1 +.sp +Default: \fB1\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-e\fR, \fB\-\-error\-gzip\fR +.B \-e, \-\-error\-gzip Make error response gzipped. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-dh\-param\-file=\fR +.B \-\-dh\-param\-file= Path to file that contains DH parameters in PEM format. Without this option, DHE cipher suites are not available. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-early\-response\fR +.B \-\-early\-response Start sending response when request HEADERS is received, rather than complete request is received. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-version\fR +.B \-\-version Display version information and exit. +.UNINDENT +.INDENT 0.0 .TP -\fB\-h\fR, \fB\-\-help\fR +.B \-h, \-\-help Display this help and exit. -.SH "SEE ALSO" - -nghttp(1), nghttpx(1), h2load(1) +.UNINDENT +.SH SEE ALSO +.sp +\fInghttp(1)\fP, \fInghttpx(1)\fP, \fIh2load(1)\fP +.SH AUTHOR +Tatsuhiro Tsujikawa +.SH COPYRIGHT +2012, 2014, Tatsuhiro Tsujikawa +.\" Generated by docutils manpage writer. +. diff --git a/doc/nghttpd.1.rst b/doc/nghttpd.1.rst index 0e8cb96c..005852e1 100644 --- a/doc/nghttpd.1.rst +++ b/doc/nghttpd.1.rst @@ -1,52 +1,43 @@ -.. DO NOT MODIFY THIS FILE! It was generated by man2rst.py - -.. program:: nghttpd nghttpd(1) ========== -NAME ----- -nghttpd - HTTP/2 experimental server - SYNOPSIS -------- -**nghttpd** [OPTION]... -**nghttpd** --no-tls [OPTION]... +**nghttpd** [OPTION]... [ ] DESCRIPTION ----------- + HTTP/2 experimental server -.. option:: PORT +.. describe:: Specify listening port number. -.. option:: PRIVATE_KEY +.. describe:: Set path to server's private key. Required unless :option:`--no-tls` is specified. -.. option:: CERT +.. describe:: Set path to server's certificate. Required unless :option:`--no-tls` is specified. -OPTIONS -------- +OPTIONS: +-------- .. option:: -D, --daemon - Run in a background. If :option:`-D` is used, the current - working directory is changed to '/'. Therefore + 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 @@ -55,84 +46,72 @@ OPTIONS .. option:: -d, --htdocs= - 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. .. option:: --no-tls - Disable SSL/TLS. .. option:: -c, --header-table-size= - Specify decoder header table size. .. option:: --color - Force colored log output. .. 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: -p/=/foo.png - -p/doc=/bar.css + :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. .. option:: -n, --workers= - Set the number of worker threads. - Default: 1 + + Default: ``1`` .. option:: -e, --error-gzip - Make error response gzipped. .. option:: --dh-param-file= - 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. .. option:: --version - Display version information and exit. .. option:: -h, --help - Display this help and exit. SEE ALSO -------- -nghttp(1), nghttpx(1), h2load(1) +:manpage:`nghttp(1)`, :manpage:`nghttpx(1)`, :manpage:`h2load(1)` diff --git a/doc/nghttpd.h2m b/doc/nghttpd.h2m deleted file mode 100644 index fa02c9a2..00000000 --- a/doc/nghttpd.h2m +++ /dev/null @@ -1,3 +0,0 @@ -[SEE ALSO] - -nghttp(1), nghttpx(1), h2load(1) diff --git a/doc/nghttpd.h2r b/doc/nghttpd.h2r new file mode 100644 index 00000000..e346cd16 --- /dev/null +++ b/doc/nghttpd.h2r @@ -0,0 +1,4 @@ +SEE ALSO +-------- + +:manpage:`nghttp(1)`, :manpage:`nghttpx(1)`, :manpage:`h2load(1)` diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index e0926084..1fe11e02 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -1,55 +1,102 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.4. -.TH NGHTTPX "1" "January 2015" "nghttpx nghttp2/0.7.0" "User Commands" +.\" Man page generated from reStructuredText. +. +.TH "NGHTTPX" "1" "January 10, 2015" "0.7.1-DEV" "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 -.B nghttpx -[\fI\,OPTIONS\/\fR]... [\fI\, \/\fR] +.sp +\fBnghttpx\fP [OPTIONS]... [ ] .SH DESCRIPTION +.sp A reverse proxy for HTTP/2, HTTP/1 and SPDY. +.INDENT 0.0 .TP - -Set path to server's private key. Required -unless \fB\-p\fR, \fB\-\-client\fR or \fB\-\-frontend\-no\-tls\fR are +.B +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 - -Set path to server's certificate. Required -unless \fB\-p\fR, \fB\-\-client\fR or \fB\-\-frontend\-no\-tls\fR are +.B +Set path to server\(aqs certificate. Required +unless \fI\%\-p\fP, \fI\%\-\-client\fP or \fI\%\-\-frontend\-no\-tls\fP are given. -.SH OPTIONS -.IP +.UNINDENT +.SH OPTIONS: +.sp The options are categorized into several groups. -.SS "Connections:" +.SS Connections: +.INDENT 0.0 .TP -\fB\-b\fR, \fB\-\-backend=\fR +.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. -Default: '127.0.0.1,80' +.sp +Default: \fB127.0.0.1,80\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-f\fR, \fB\-\-frontend=\fR -Set frontend host and port. If is '*', it +.B \-f, \-\-frontend= +Set frontend host and port. If is \(aq*\(aq, it assumes all addresses including both IPv4 and IPv6. -Default: '*,3000' +.sp +Default: \fB*,3000\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backlog=\fR -Set listen backlog size. If \fB\-1\fR is given, +.B \-\-backlog= +Set listen backlog size. If \fI\-1\fP is given, libevent will choose suitable value. -Default: 128 +.sp +Default: \fB128\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-ipv4\fR +.B \-\-backend\-ipv4 Resolve backend hostname to IPv4 address only. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-ipv6\fR +.B \-\-backend\-ipv6 Resolve backend hostname to IPv6 address only. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-http\-proxy\-uri=\fR +.B \-\-backend\-http\-proxy\-uri= Specify proxy URI in the form -http://[:@]:. If a +\fI\%http:/\fP/[:@]:. If a proxy requires authentication, specify and . Note that they must be properly percent\-encoded. This proxy is used when the @@ -60,202 +107,292 @@ tunnel. After that, nghttpx performs SSL/TLS handshake with the downstream through the tunnel. The timeouts when connecting and making CONNECT request can be specified by -\fB\-\-backend\-read\-timeout\fR and -\fB\-\-backend\-write\-timeout\fR options. -.SS "Performance:" +\fI\%\-\-backend\-read\-timeout\fP and +\fI\%\-\-backend\-write\-timeout\fP options. +.UNINDENT +.SS Performance: +.INDENT 0.0 .TP -\fB\-n\fR, \fB\-\-workers=\fR +.B \-n, \-\-workers= Set the number of worker threads. -Default: 1 +.sp +Default: \fB1\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-read\-rate=\fR +.B \-\-read\-rate= Set maximum average read rate on frontend connection. Setting 0 to this option means read rate is unlimited. -Default: 0 +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-read\-burst=\fR +.B \-\-read\-burst= Set maximum read burst size on frontend connection. Setting 0 to this option means read burst size is unlimited. -Default: 0 +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-write\-rate=\fR +.B \-\-write\-rate= Set maximum average write rate on frontend connection. Setting 0 to this option means write rate is unlimited. -Default: 0 +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-write\-burst=\fR +.B \-\-write\-burst= Set maximum write burst size on frontend connection. Setting 0 to this option means write burst size is unlimited. -Default: 0 +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-worker\-read\-rate=\fR +.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. -Default: 0 +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-worker\-read\-burst=\fR +.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. -Default: 0 +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-worker\-write\-rate=\fR +.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. -Default: 0 +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-worker\-write\-burst=\fR +.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. -Default: 0 +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-worker\-frontend\-connections=\fR +.B \-\-worker\-frontend\-connections= Set maximum number of simultaneous connections frontend accepts. Setting 0 means unlimited. -Default: 0 +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-http1\-connections\-per\-host=\fR +.B \-\-backend\-http1\-connections\-per\-host= Set maximum number of backend concurrent HTTP/1 connections per host. This option is meaningful -when \fB\-s\fR option is used. To limit the number of +when \fI\%\-s\fP option is used. To limit the number of connections per frontend for default mode, use -\fB\-\-backend\-http1\-connections\-per\-frontend\fR. -Default: 8 +\fI\%\-\-backend\-http1\-connections\-per\-frontend\fP\&. +.sp +Default: \fB8\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-http1\-connections\-per\-frontend=\fR +.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 (\fB\-s\fR option), use -\fB\-\-backend\-http1\-connections\-per\-host\fR. -Default: 0 -.SS "Timeout:" +HTTP/2 or SPDY proxy mode (\-s option), use +\fI\%\-\-backend\-http1\-connections\-per\-host\fP\&. +.sp +Default: \fB0\fP +.UNINDENT +.SS Timeout: +.INDENT 0.0 .TP -\fB\-\-frontend\-http2\-read\-timeout=\fR +.B \-\-frontend\-http2\-read\-timeout= Specify read timeout for HTTP/2 and SPDY frontend connection. -Default: 180 +.sp +Default: \fB180\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-frontend\-read\-timeout=\fR +.B \-\-frontend\-read\-timeout= Specify read timeout for HTTP/1.1 frontend connection. -Default: 180 +.sp +Default: \fB180\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-frontend\-write\-timeout=\fR +.B \-\-frontend\-write\-timeout= Specify write timeout for all frontend connections. -Default: 30 +.sp +Default: \fB30\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-stream\-read\-timeout=\fR +.B \-\-stream\-read\-timeout= Specify read timeout for HTTP/2 and SPDY streams. 0 means no timeout. -Default: 0 +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-stream\-write\-timeout=\fR +.B \-\-stream\-write\-timeout= Specify write timeout for HTTP/2 and SPDY streams. 0 means no timeout. -Default: 0 +.sp +Default: \fB0\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-read\-timeout=\fR +.B \-\-backend\-read\-timeout= Specify read timeout for backend connection. -Default: 180 +.sp +Default: \fB180\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-write\-timeout=\fR +.B \-\-backend\-write\-timeout= Specify write timeout for backend connection. -Default: 30 +.sp +Default: \fB30\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-keep\-alive\-timeout=\fR +.B \-\-backend\-keep\-alive\-timeout= Specify keep\-alive timeout for backend connection. -Default: 600 +.sp +Default: \fB600\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-listener\-disable\-timeout=\fR +.B \-\-listener\-disable\-timeout= After accepting connection failed, connection listener is disabled for a given time in seconds. Specifying 0 disables this feature. -Default: 0 -.SS "SSL/TLS:" +.sp +Default: \fB0\fP +.UNINDENT +.SS SSL/TLS: +.INDENT 0.0 .TP -\fB\-\-ciphers=\fR +.B \-\-ciphers= Set allowed cipher list. The format of the string is described in OpenSSL ciphers(1). +.UNINDENT +.INDENT 0.0 .TP -\fB\-k\fR, \fB\-\-insecure\fR -Don't verify backend server's certificate if \fB\-p\fR, -\fB\-\-client\fR or \fB\-\-http2\-bridge\fR are given and -\fB\-\-backend\-no\-tls\fR is not given. +.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 -\fB\-\-cacert=\fR -Set path to trusted CA certificate file if \fB\-p\fR, -\fB\-\-client\fR or \fB\-\-http2\-bridge\fR are given and -\fB\-\-backend\-no\-tls\fR is not given. The file must be +.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. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-private\-key\-passwd\-file=\fR +.B \-\-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 +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 -\fB\-\-subcert=\fR: +.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. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-tls\-sni\-field=\fR +.B \-\-backend\-tls\-sni\-field= Explicitly set the content of the TLS SNI extension. This will default to the backend HOST name. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-dh\-param\-file=\fR +.B \-\-dh\-param\-file= Path to file that contains DH parameters in PEM format. Without this option, DHE cipher suites are not available. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-npn\-list=\fR +.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. -Default: h2\-16,h2\-14,spdy/3.1,http/1.1 +.sp +Default: \fBh2\-16,h2\-14,spdy/3.1,http/1.1\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-verify\-client\fR +.B \-\-verify\-client Require and verify client certificate. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-verify\-client\-cacert=\fR +.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. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-client\-private\-key\-file=\fR +.B \-\-client\-private\-key\-file= Path to file that contains client private key used in backend client authentication. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-client\-cert\-file=\fR +.B \-\-client\-cert\-file= Path to file that contains client certificate used in backend client authentication. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-tls\-proto\-list=\fR +.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 @@ -263,212 +400,362 @@ is done in case\-insensitive manner. The parameter must be delimited by a single comma only and any white spaces are treated as a part of protocol string. -Default: TLSv1.2,TLSv1.1 -.SS "HTTP/2 and SPDY:" +.sp +Default: \fBTLSv1.2,TLSv1.1\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-c\fR, \fB\-\-http2\-max\-concurrent\-streams=\fR +.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 +.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. -Default: 100 +.sp +Default: \fB100\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-frontend\-http2\-window\-bits=\fR +.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**. -Default: 16 +.sp +Default: \fB16\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-frontend\-http2\-connection\-window\-bits=\fR +.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**. -Default: 16 +.sp +Default: \fB16\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-frontend\-no\-tls\fR +.B \-\-frontend\-no\-tls Disable SSL/TLS on frontend connections. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-http2\-window\-bits=\fR +.B \-\-backend\-http2\-window\-bits= Sets the initial window size of HTTP/2 backend connection to 2**\-1. -Default: 16 +.sp +Default: \fB16\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-http2\-connection\-window\-bits=\fR +.B \-\-backend\-http2\-connection\-window\-bits= Sets the per\-connection window size of HTTP/2 backend connection to 2**\-1. -Default: 16 +.sp +Default: \fB16\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-backend\-no\-tls\fR +.B \-\-backend\-no\-tls Disable SSL/TLS on backend connections. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-http2\-no\-cookie\-crumbling\fR -Don't crumble cookie header field. +.B \-\-http2\-no\-cookie\-crumbling +Don\(aqt crumble cookie header field. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-padding=\fR +.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. -.SS "Mode:" +.UNINDENT +.SS Mode: +.INDENT 0.0 .TP -(default mode) +.B (default mode) Accept HTTP/2, SPDY and HTTP/1.1 over SSL/TLS. -If \fB\-\-frontend\-no\-tls\fR is used, accept HTTP/2 and +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 -\fB\-s\fR, \fB\-\-http2\-proxy\fR +.B \-s, \-\-http2\-proxy Like default mode, but enable secure proxy mode. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-http2\-bridge\fR +.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 -\fB\-\-backend\-http\-proxy\-uri\fR option if you are behind +\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 -\fB\-\-client\fR +.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 \fB\-p\fR option +nghttpx as a forward proxy, use \fI\%\-p\fP option instead. +.UNINDENT +.INDENT 0.0 .TP -\fB\-p\fR, \fB\-\-client\-proxy\fR -Like \fB\-\-client\fR option, but it also requires the +.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. -.SS "Logging:" +.UNINDENT +.SS Logging: +.INDENT 0.0 .TP -\fB\-L\fR, \fB\-\-log\-level=\fR +.B \-L, \-\-log\-level= Set the severity level of log output. must be one of INFO, NOTICE, WARN, ERROR and FATAL. -Default: NOTICE +.sp +Default: \fBNOTICE\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-accesslog\-file=\fR +.B \-\-accesslog\-file= Set path to write access log. To reopen file, send USR1 signal to nghttpx. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-accesslog\-syslog\fR +.B \-\-accesslog\-syslog Send access log to syslog. If this option is -used, \fB\-\-access\-file\fR option is ignored. +used, \fI\%\-\-accesslog\-file\fP option is ignored. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-accesslog\-format=\fR +.B \-\-accesslog\-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_: value of HTTP request header -where '_' in is replaced with '\-'. +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. +.IP \(bu 2 $pid: PID of the running process. -$alpn: ALPN identifier of the protocol which -generates the response. For HTTP/1, ALPN is +.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. -Default: $remote_addr \- \- [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" +.UNINDENT +.sp +Default: \fB$remote_addr \- \- [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-errorlog\-file=\fR +.B \-\-errorlog\-file= Set path to write error log. To reopen file, send USR1 signal to nghttpx. -Default: \fI\,/dev/stderr\/\fP +.sp +Default: \fB/dev/stderr\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-errorlog\-syslog\fR +.B \-\-errorlog\-syslog Send error log to syslog. If this option is -used, \fB\-\-errorlog\-file\fR option is ignored. +used, \fI\%\-\-errorlog\-file\fP option is ignored. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-syslog\-facility=\fR +.B \-\-syslog\-facility= Set syslog facility to . -Default: daemon -.SS "Misc:" +.sp +Default: \fBdaemon\fP +.UNINDENT +.SS Misc: +.INDENT 0.0 .TP -\fB\-\-add\-x\-forwarded\-for\fR +.B \-\-add\-x\-forwarded\-for Append X\-Forwarded\-For header field to the downstream request. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-strip\-incoming\-x\-forwarded\-for\fR +.B \-\-strip\-incoming\-x\-forwarded\-for Strip X\-Forwarded\-For header field from inbound client requests. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-no\-via\fR -Don't append to Via header field. If Via header +.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 -\fB\-\-no\-location\-rewrite\fR -Don't rewrite location header field on -\fB\-\-http2\-bridge\fR, \fB\-\-client\fR and default mode. For -\fB\-\-http2\-proxy\fR and \fB\-\-client\-proxy\fR mode, location +.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 -\fB\-\-altsvc=\fR +.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: \fB\-\-altsvc\fR=\fI\,h2\/\fR,443 +alternative services. Example: \fI\%\-\-altsvc\fP=h2,443 +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-add\-response\-header=\fR
+.B \-\-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 +header field and won\(aqt replace anything already set. This option can be used several times to specify multiple header fields. -Example: \fB\-\-add\-response\-header=\fR"foo: bar" +Example: \fI\%\-\-add\-response\-header\fP="foo: bar" +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-frontend\-http2\-dump\-request\-header=\fR +.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 \fB\-n\fR, where >= 2. +with option \fI\%\-n\fP, where >= 2. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-frontend\-http2\-dump\-response\-header=\fR +.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 \fB\-n\fR, where >= 2. +with option \fI\%\-n\fP, where >= 2. +.UNINDENT +.INDENT 0.0 .TP -\fB\-o\fR, \fB\-\-frontend\-frame\-debug\fR +.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 \fB\-n\fR=\fI\,N\/\fR, where N >= 2. +with option \fI\%\-n\fP=N, where N >= 2. +.UNINDENT +.INDENT 0.0 .TP -\fB\-D\fR, \fB\-\-daemon\fR -Run in a background. If \fB\-D\fR is used, the current -working directory is changed to '/'. +.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 -\fB\-\-pid\-file=\fR +.B \-\-pid\-file= Set path to save PID of this program. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-user=\fR +.B \-\-user= Run this program as . This option is intended to be used to drop root privileges. +.UNINDENT +.INDENT 0.0 .TP -\fB\-\-conf=\fR +.B \-\-conf= Load configuration from . -Default: \fI\,/etc/nghttpx/nghttpx.conf\/\fP +.sp +Default: \fB/etc/nghttpx/nghttpx.conf\fP +.UNINDENT +.INDENT 0.0 .TP -\fB\-v\fR, \fB\-\-version\fR +.B \-v, \-\-version Print version and exit. +.UNINDENT +.INDENT 0.0 .TP -\fB\-h\fR, \fB\-\-help\fR +.B \-h, \-\-help Print this help and exit. -.SH "SEE ALSO" - -nghttp(1), nghttpd(1), h2load(1) +.UNINDENT +.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. +.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. After new process comes up, sending SIGQUIT to the original +process to perform hotswap. +.UNINDENT +.SH SEE ALSO +.sp +\fInghttp(1)\fP, \fInghttpd(1)\fP, \fIh2load(1)\fP +.SH AUTHOR +Tatsuhiro Tsujikawa +.SH COPYRIGHT +2012, 2014, Tatsuhiro Tsujikawa +.\" Generated by docutils manpage writer. +. diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst index 6c0551fc..bd5d4af9 100644 --- a/doc/nghttpx.1.rst +++ b/doc/nghttpx.1.rst @@ -1,80 +1,72 @@ -.. DO NOT MODIFY THIS FILE! It was generated by man2rst.py - -.. program:: nghttpx nghttpx(1) ========== -NAME ----- -nghttpx - HTTP/2 experimental proxy - SYNOPSIS -------- + **nghttpx** [OPTIONS]... [ ] DESCRIPTION ----------- + A reverse proxy for HTTP/2, HTTP/1 and SPDY. -.. option:: PRIVATE_KEY +.. describe:: Set path to server's private key. Required - unless :option:`-p`, :option:`--client` or :option:`--frontend-no-tls` are + unless :option:`-p`\, :option:`--client` or :option:`\--frontend-no-tls` are given. -.. option:: CERT +.. describe:: Set path to server's certificate. Required - unless :option:`-p`, :option:`--client` or :option:`--frontend-no-tls` are + unless :option:`-p`\, :option:`--client` or :option:`\--frontend-no-tls` are given. -OPTIONS -------- +OPTIONS: +-------- The options are categorized into several groups. -Connections -^^^^^^^^^^^ +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. - Default: '127.0.0.1,80' + + 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. - Default: '\*,3000' + + Default: ``*,3000`` .. option:: --backlog= - - Set listen backlog size. If -1 is given, + Set listen backlog size. If :option:`-1` is given, libevent will choose suitable value. - Default: 128 + + Default: ``128`` .. option:: --backend-ipv4 - Resolve backend hostname to IPv4 address only. .. option:: --backend-ipv6 - Resolve backend hostname to IPv6 address only. .. option:: --backend-http-proxy-uri= - Specify proxy URI in the form http://[:@]:. If a proxy requires authentication, specify and @@ -90,197 +82,197 @@ Connections :option:`--backend-read-timeout` and :option:`--backend-write-timeout` options. -Performance -^^^^^^^^^^^ + +Performance: +~~~~~~~~~~~~ .. option:: -n, --workers= - Set the number of worker threads. - Default: 1 + + Default: ``1`` .. option:: --read-rate= - Set maximum average read rate on frontend connection. Setting 0 to this option means read rate is unlimited. - Default: 0 + + Default: ``0`` .. option:: --read-burst= - Set maximum read burst size on frontend connection. Setting 0 to this option means read burst size is unlimited. - Default: 0 + + Default: ``0`` .. option:: --write-rate= - Set maximum average write rate on frontend connection. Setting 0 to this option means write rate is unlimited. - Default: 0 + + Default: ``0`` .. option:: --write-burst= - Set maximum write burst size on frontend connection. Setting 0 to this option means write burst size is unlimited. - Default: 0 + + Default: ``0`` .. 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. - Default: 0 + + 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. - Default: 0 + + Default: ``0`` .. 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. - Default: 0 + + 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. - Default: 0 + + Default: ``0`` .. option:: --worker-frontend-connections= - Set maximum number of simultaneous connections frontend accepts. Setting 0 means unlimited. - Default: 0 + + Default: ``0`` .. 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 - :option:`--backend-http1-connections-per-frontend`. - Default: 8 + :option:`--backend-http1-connections-per-frontend`\. + + Default: ``8`` .. 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 (:option:`-s` option), use - :option:`--backend-http1-connections-per-host`. - Default: 0 + HTTP/2 or SPDY proxy mode (-s option), use + :option:`--backend-http1-connections-per-host`\. -Timeout -^^^^^^^ + Default: ``0`` + + +Timeout: +~~~~~~~~ .. option:: --frontend-http2-read-timeout= - Specify read timeout for HTTP/2 and SPDY frontend connection. - Default: 180 + + Default: ``180`` .. option:: --frontend-read-timeout= - Specify read timeout for HTTP/1.1 frontend connection. - Default: 180 + + Default: ``180`` .. option:: --frontend-write-timeout= - Specify write timeout for all frontend connections. - Default: 30 + + Default: ``30`` .. option:: --stream-read-timeout= - Specify read timeout for HTTP/2 and SPDY streams. 0 means no timeout. - Default: 0 + + Default: ``0`` .. option:: --stream-write-timeout= - Specify write timeout for HTTP/2 and SPDY streams. 0 means no timeout. - Default: 0 + + Default: ``0`` .. option:: --backend-read-timeout= - Specify read timeout for backend connection. - Default: 180 + + Default: ``180`` .. option:: --backend-write-timeout= - Specify write timeout for backend connection. - Default: 30 + + Default: ``30`` .. option:: --backend-keep-alive-timeout= - Specify keep-alive timeout for backend connection. - Default: 600 + + 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. - Default: 0 -SSL/TLS -^^^^^^^ + Default: ``0`` + + +SSL/TLS: +~~~~~~~~ .. option:: --ciphers= - 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 + 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 @@ -289,7 +281,6 @@ SSL/TLS .. 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 @@ -297,7 +288,6 @@ SSL/TLS .. option:: --subcert=: - Specify additional certificate and private key file. nghttpx will choose certificates based on the hostname indicated by client using TLS SNI @@ -306,37 +296,33 @@ SSL/TLS .. option:: --backend-tls-sni-field= - 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. .. 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. - Default: h2-16,h2-14,spdy/3.1,http/1.1 + + Default: ``h2-16,h2-14,spdy/3.1,http/1.1`` .. option:: --verify-client - Require and verify client certificate. .. 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 @@ -344,19 +330,16 @@ SSL/TLS .. option:: --client-private-key-file= - 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. .. 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 @@ -364,73 +347,93 @@ SSL/TLS 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 -HTTP/2 and SPDY -^^^^^^^^^^^^^^^ + Default: ``TLSv1.2,TLSv1.1`` + +.. 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. + + +HTTP/2 and SPDY: +~~~~~~~~~~~~~~~~ .. option:: -c, --http2-max-concurrent-streams= - Set the maximum number of the concurrent streams in one HTTP/2 and SPDY session. - Default: 100 + + 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\*\*. - Default: 16 + 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\*\*. - Default: 16 + is 2**-1. For SPDY, the size is 2\*\*. + + Default: ``16`` .. option:: --frontend-no-tls - Disable SSL/TLS on frontend connections. .. option:: --backend-http2-window-bits= - Sets the initial window size of HTTP/2 backend - connection to 2\*\*-1. - Default: 16 + 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. - Default: 16 + + Default: ``16`` .. option:: --backend-no-tls - Disable SSL/TLS on backend connections. .. option:: --http2-no-cookie-crumbling - Don't crumble cookie header field. .. 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. -Mode -^^^^ + +Mode: +~~~~~ .. describe:: (default mode) @@ -442,12 +445,10 @@ Mode .. option:: -s, --http2-proxy - Like default mode, but enable secure proxy 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 @@ -458,7 +459,6 @@ Mode .. 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 @@ -468,189 +468,199 @@ Mode .. 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. -Logging -^^^^^^^ + +Logging: +~~~~~~~~ .. option:: -L, --log-level= - Set the severity level of log output. must be one of INFO, NOTICE, WARN, ERROR and FATAL. - Default: NOTICE + + Default: ``NOTICE`` .. option:: --accesslog-file= - 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:`--access-file` option is ignored. + 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: - $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 '-'. - $remote_port: client port. - $server_port: server port. - $request_time: request processing time in - seconds with milliseconds resolution. - $pid: PID of the running process. - $alpn: ALPN identifier of the protocol which - generates the response. For HTTP/1, ALPN is - always http/1.1, regardless of minor version. - Default: $remote_addr - - [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" + + * $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 '-'. + * $remote_port: client port. + * $server_port: server port. + * $request_time: request processing time in + seconds with milliseconds resolution. + * $pid: PID of the running process. + * $alpn: ALPN identifier of the protocol which + generates the response. For HTTP/1, ALPN is + always http/1.1, regardless of minor version. + + + Default: ``$remote_addr - - [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"`` .. option:: --errorlog-file= - Set path to write error log. To reopen file, send USR1 signal to nghttpx. - Default: /dev/stderr + + Default: ``/dev/stderr`` .. option:: --errorlog-syslog - Send error log to syslog. If this option is used, :option:`--errorlog-file` option is ignored. .. option:: --syslog-facility= - Set syslog facility to . - Default: daemon -Misc -^^^^ + Default: ``daemon`` + + +Misc: +~~~~~ .. option:: --add-x-forwarded-for - 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. .. option:: --no-via - 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 + :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: --altsvc=h2,443 + 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. - Example: --add-response-header="foo: bar" + Example: :option:`--add-response-header`\="foo: bar" .. 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 -n, where >= 2. + 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 -n, where >= 2. + 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 -n=N, where N >= 2. + with option :option:`-n`\=N, where N >= 2. .. option:: -D, --daemon - Run in a background. If :option:`-D` is used, the current - working directory is changed to '/'. + working directory is changed to '*/*'. .. option:: --pid-file= - Set path to save PID of this program. .. option:: --user= - Run this program as . This option is intended to be used to drop root privileges. .. option:: --conf= - Load configuration from . - Default: /etc/nghttpx/nghttpx.conf + + Default: ``/etc/nghttpx/nghttpx.conf`` .. option:: -v, --version - Print version and exit. .. option:: -h, --help - Print this help and exit. +FILES +----- + +*/etc/nghttpx/nghttpx.conf* + The default configuration file path nghttpx searches at startup. + The configuration file path can be changed using :option:`--conf` + option. + +SIGNALS +------- + +SIGQUIT + Shutdown gracefully. First accept pending connections and stop + accepting connection. After all connections are handled, nghttpx + exits. + +SIGUSR1 + Reopen log files. + +SIGUSR2 + Fork and execute nghttpx. It will execute the binary in the same + path. After new process comes up, sending SIGQUIT to the original + process to perform hotswap. + SEE ALSO -------- -nghttp(1), nghttpd(1), h2load(1) +:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`h2load(1)` diff --git a/doc/nghttpx.h2m b/doc/nghttpx.h2m deleted file mode 100644 index fba92116..00000000 --- a/doc/nghttpx.h2m +++ /dev/null @@ -1,3 +0,0 @@ -[SEE ALSO] - -nghttp(1), nghttpd(1), h2load(1) diff --git a/doc/nghttpx.h2r b/doc/nghttpx.h2r new file mode 100644 index 00000000..9c458e67 --- /dev/null +++ b/doc/nghttpx.h2r @@ -0,0 +1,28 @@ +FILES +----- + +*/etc/nghttpx/nghttpx.conf* + The default configuration file path nghttpx searches at startup. + The configuration file path can be changed using :option:`--conf` + option. + +SIGNALS +------- + +SIGQUIT + Shutdown gracefully. First accept pending connections and stop + accepting connection. After all connections are handled, nghttpx + exits. + +SIGUSR1 + Reopen log files. + +SIGUSR2 + Fork and execute nghttpx. It will execute the binary in the same + path. After new process comes up, sending SIGQUIT to the original + process to perform hotswap. + +SEE ALSO +-------- + +:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`h2load(1)` diff --git a/help2rst.py b/help2rst.py new file mode 100755 index 00000000..a6062a6a --- /dev/null +++ b/help2rst.py @@ -0,0 +1,178 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- + +# script to produce rst file from program's help output. + +from __future__ import unicode_literals +import sys +import re +import argparse + +arg_indent = ' ' * 21 + +def help2man(infile): + # We assume that first line is usage line like this: + # + # Usage: nghttp [OPTIONS]... URI... + # + # The second line is description of the command. Multiple lines + # are permitted. The blank line signals the end of this section. + # After that, we parses positional and optional arguments. + # + # The positional argument is enclosed with < and >: + # + # + # + # We may describe default behavior without any options by encoding + # ( and ): + # + # (default mode) + # + # "Options:" is treated specially and produces "OPTIONS" section. + # We allow subsection under OPTIONS. Lines not starting with (, < + # and Options: are treated as subsection name and produces section + # one level down: + # + # TLS/SSL: + # + # The above is an example of subsection. + # + # The description of arguments must be indented by len(arg_indent) + # characters. The default value should be placed in separate line + # and should be start with "Default: " after indentation. + + line = infile.readline().strip() + m = re.match(r'^Usage: (.*)', line) + if not m: + print 'usage line is invalid. Expected following lines:' + print 'Usage: cmdname ...' + sys.exit(1) + synopsis = m.group(1).split(' ', 1) + if len(synopsis) == 2: + cmdname, args = synopsis + else: + cmdname, args = synopsis[0], '' + + description = [] + for line in infile: + line = line.strip() + if not line: + break + description.append(line) + + print ''' +{cmdname}(1) +{cmdnameunderline} + +SYNOPSIS +-------- + +**{cmdname}** {args} + +DESCRIPTION +----------- + +{description} +'''.format(cmdname=cmdname, args=args, + cmdnameunderline='=' * (len(cmdname) + 3), + synopsis=synopsis, description=format_text('\n'.join(description))) + + in_arg = False + + for line in infile: + line = line.rstrip() + + if not line.strip() and in_arg: + print '' + continue + if line.startswith(' ') and in_arg: + if not line.startswith(arg_indent): + sys.stderr.write('warning: argument description is not indented correctly. We need {} spaces as indentation.'.format(len(arg_indent))) + print '{}'.format(format_arg_text(line[len(arg_indent):])) + continue + + if in_arg: + print '' + in_arg = False + + if line == 'Options:': + print 'OPTIONS:' + print '--------' + print '' + continue + + if line.startswith(' <'): + # positional argument + m = re.match(r'^(?:\s+)([a-zA-Z0-9-_<>]+)(.*)', line) + argname, rest = m.group(1), m.group(2) + print '.. describe:: {}'.format(argname) + print '' + print '{}'.format(format_arg_text(rest.strip())) + in_arg = True + continue + + if line.startswith(' ('): + # positional argument + m = re.match(r'^(?:\s+)(\([a-zA-Z0-9-_<> ]+\))(.*)', line) + argname, rest = m.group(1), m.group(2) + print '.. describe:: {}'.format(argname) + print '' + print '{}'.format(format_arg_text(rest.strip())) + in_arg = True + continue + + if line.startswith(' -'): + # optional argument + m = re.match( + r'^(?:\s+)(-\S+?(?:, -\S+?)*)($| .*)', + line) + argname, rest = m.group(1), m.group(2) + print '.. option:: {}'.format(argname) + print '' + rest = rest.strip() + if len(rest): + print '{}'.format(format_arg_text(rest)) + in_arg = True + continue + + if not line.startswith(' ') and line.endswith(':'): + # subsection + subsec = line.strip() + print '{}'.format(subsec) + print '{}'.format('~' * len(subsec)) + print '' + continue + + print line.strip() + +def format_text(text): + # escape * + if len(text) > len(arg_indent): + text = text[:len(arg_indent) + 1] + re.sub(r'\*', r'\*', text[len(arg_indent) + 1:]) + else: + text = re.sub(r'\*', r'\*', text) + # markup option reference + text = re.sub(r'(^|\s)(-[a-zA-Z0-9-]+)', r'\1:option:`\2`', text) + # sphinx does not like markup like ':option:`-f`='. We need + # backslash between ` and =. + text = re.sub(r'(:option:`.*?`)(\S)', r'\1\\\2', text) + # file path should be italic + text = re.sub(r'(^|\s|\'|")(/[^\s\'"]*)', r'\1*\2*', text) + return text + +def format_arg_text(text): + if text.strip().startswith('Default: '): + return '\n ' + re.sub(r'^(\s*Default: )(.*)$', r'\1``\2``', text) + return ' {}'.format(format_text(text)) + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='Produces rst document from help output.') + parser.add_argument('-i', '--include', metavar='FILE', + help='include content of as verbatim. It should be ReST formatted text.') + args = parser.parse_args() + help2man(sys.stdin) + if args.include: + print '' + with open(args.include) as f: + sys.stdout.write(f.read()) diff --git a/makemanpages b/makemanpages index ad5a0225..0b7c54ea 100755 --- a/makemanpages +++ b/makemanpages @@ -1,17 +1,12 @@ #!/bin/sh -e -help2man --output=doc/nghttp.1 --name="HTTP/2 experimental client" \ - -N --include doc/nghttp.h2m src/nghttp - -help2man --output=doc/nghttpd.1 --name="HTTP/2 experimental server" \ - -N --include doc/nghttpd.h2m src/nghttpd - -help2man --output=doc/nghttpx.1 --name="HTTP/2 experimental proxy" \ - -N --include doc/nghttpx.h2m src/nghttpx - -help2man --output=doc/h2load.1 --name="HTTP/2 benchmarking tool" \ - -N --include doc/h2load.h2m src/h2load - -for file in doc/nghttp.1 doc/nghttpd.1 doc/nghttpx.1 doc/h2load.1; do - ./man2rst.py < $file > $file.rst +for prog in nghttp nghttpd nghttpx h2load; do + src/$prog -h | ./help2rst.py -i doc/$prog.h2r > doc/$prog.1.rst +done + +cd doc +make man + +for prog in nghttp nghttpd nghttpx h2load; do + cp manual/man/$prog.1 $prog.1 done diff --git a/man2rst.py b/man2rst.py deleted file mode 100755 index 053712f9..00000000 --- a/man2rst.py +++ /dev/null @@ -1,121 +0,0 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- - -# This script reads man page from stdin and converts it to rst -# document and outputs to stdout. - -from __future__ import unicode_literals -import sys -import re - -def man2rst(f): - expect_arg = False - in_arg = False - - sys.stdout.write('.. DO NOT MODIFY THIS FILE! ' - 'It was generated by man2rst.py\n\n') - - for line in f: - line = line.rstrip() - - if re.match(r'\.\\"', line): - # comment - continue - - if re.match(r'\.TH ', line): - # title - title = line.split()[1].lower() - sys.stdout.write('.. program:: {}\n\n'.format(title)) - title += '(1)' - sys.stdout.write('{}\n'.format(title)) - sys.stdout.write('=' * len(title)) - sys.stdout.write('\n') - continue - - if re.match(r'\.SH ', line): - # section - expect_arg = False - in_arg = False - section = line.split(' ', 1)[1].strip('"') - sys.stdout.write('\n{}\n'.format(section)) - sys.stdout.write('-' * len(section)) - sys.stdout.write('\n') - continue - - if re.match(r'\.br', line): - sys.stdout.write('\n') - continue - - if re.match(r'\.B ', line): - prog = line.split(' ', 1)[1] - sys.stdout.write('**{}** '.format(prog)) - continue - - if re.match(r'\.SS ', line): - # subsection - expect_arg = False - in_arg = False - subsection = line.split(' ', 1)[1].strip('"').rstrip(':') - sys.stdout.write('\n{}\n'.format(subsection)) - sys.stdout.write('^' * len(subsection)) - sys.stdout.write('\n') - continue - - if re.match(r'\.(T|H|I)P', line): - expect_arg = True - in_arg = False - sys.stdout.write('\n') - continue - - if expect_arg and line.startswith('<'): - expect_arg = False - in_arg = True - positional_arg = line.lstrip('<').rstrip('>') - sys.stdout.write('.. option:: {}\n\n'.format(positional_arg)) - continue - - if expect_arg and line.startswith('('): - expect_arg = False - in_arg = True - sys.stdout.write('.. describe:: {}\n\n'.format(line)) - continue - - if expect_arg: - expect_arg = False - - m = re.match(r'(\\fB.*?\\fR(?:, \\fB.*?\\fR)?[\S]*)(.*)', line) - if not m: - sys.stdout.write('{}\n'.format(process_text(line))) - continue - - in_arg = True - optional_arg = process_arg(m.group(1)) - text = m.group(2).strip() - sys.stdout.write('.. option:: {}\n\n'.format(optional_arg)) - sys.stdout.write(' {}\n'.format(process_text(text))) - continue - - if in_arg: - sys.stdout.write(' {}\n'.format(process_text(line))) - continue - - sys.stdout.write('{}\n'.format(process_text(line))) - -def process_arg(text): - text = re.sub(r'\\fB(.*?)\\fR', '\\1', text) - text = re.sub(r'\\-', '-', text) - - return text - -def process_text(text): - text = re.sub(r'\\fI\\,(.*?)\\/\\f(?:R|P)', '\\1', text) - text = re.sub(r'\\fB\\(-[^1].*?)\\fR(\s|[,.]|\Z)', ':option:`\\1`\\2', text) - text = re.sub(r'\\fB(.*?)\\fR', '\\1', text) - text = re.sub(r'\\-', '-', text) - text = re.sub(r'\*', '\\*', text) - text = re.sub(r'\\&', '', text) - - return text - -if __name__ == '__main__': - man2rst(sys.stdin) diff --git a/src/h2load.cc b/src/h2load.cc index 53d9f87e..5b408745 100644 --- a/src/h2load.cc +++ b/src/h2load.cc @@ -852,8 +852,7 @@ void print_version(std::ostream &out) { namespace { void print_usage(std::ostream &out) { - out << R"( -Usage: h2load [OPTIONS]... [URI]... + out << R"(Usage: h2load [OPTIONS]... [URI]... benchmarking tool for HTTP/2 and SPDY server)" << std::endl; } } // namespace @@ -871,11 +870,12 @@ void print_help(std::ostream &out) { are ignored. Those in the first URI are used solely. Options: - -n, --requests= Number of requests. Default: )" << config.nreqs << R"( - -c, --clients= Number of concurrent clients. Default: )" - << config.nclients << R"( - -t, --threads= Number of native threads. Default: )" << config.nthreads - << R"( + -n, --requests= Number of requests. + Default: )" << config.nreqs << R"( + -c, --clients= Number of concurrent clients. + Default: )" << config.nclients << R"( + -t, --threads= Number of native threads. + Default: )" << config.nthreads << R"( -i, --input-file= Path of a file with multiple URIs are seperated by EOLs. This option will disable URIs getting @@ -889,7 +889,8 @@ Options: -m, --max-concurrent-streams=(auto|) Max concurrent streams to issue per session. If "auto" is given, the number of given URIs is - used. Default: auto + used. + Default: auto -w, --window-bits= Sets the stream level initial window size to (2**)-1. For SPDY, 2** is used instead. diff --git a/src/nghttpd.cc b/src/nghttpd.cc index ebc86d73..e08ff00a 100644 --- a/src/nghttpd.cc +++ b/src/nghttpd.cc @@ -81,8 +81,7 @@ void print_version(std::ostream &out) { namespace { void print_usage(std::ostream &out) { - out << "Usage: nghttpd [OPTION]... \n" - << " or: nghttpd --no-tls [OPTION]... \n" + out << "Usage: nghttpd [OPTION]... [ ]\n" << "HTTP/2 experimental server" << std::endl; } } // namespace diff --git a/src/shrpx.cc b/src/shrpx.cc index badc15a9..15140d69 100644 --- a/src/shrpx.cc +++ b/src/shrpx.cc @@ -788,14 +788,14 @@ Connections: repeating this option. HTTP/2 backend does not support multiple backend addresses and the first occurrence of this option is used. - Default: ')" << DEFAULT_DOWNSTREAM_HOST << "," - << DEFAULT_DOWNSTREAM_PORT << R"(' + Default: )" << DEFAULT_DOWNSTREAM_HOST << "," + << DEFAULT_DOWNSTREAM_PORT << R"( -f, --frontend= Set frontend host and port. If is '*', it assumes all addresses including both IPv4 and IPv6. - Default: ')" << get_config()->host.get() << "," - << get_config()->port << R"(' + Default: )" << get_config()->host.get() << "," + << get_config()->port << R"( --backlog= Set listen backlog size. If -1 is given, libevent will choose suitable value. Default: )" << get_config()->backlog << R"( @@ -1082,28 +1082,30 @@ Logging: send USR1 signal to nghttpx. --accesslog-syslog Send access log to syslog. If this option is - used, --access-file option is ignored. + used, --accesslog-file option is ignored. --accesslog-format= Specify format string for access log. The default format is combined format. The following variables are available: - $remote_addr: client IP address. - $time_local: local time in Common Log format. - $time_iso8601: local time in ISO 8601 format. - $request: HTTP request line. - $status: HTTP response status code. - $body_bytes_sent: the number of bytes sent to - client as response body. - $http_: 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. - $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. + + * $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 '-'. + * $remote_port: client port. + * $server_port: server port. + * $request_time: request processing time in + seconds with milliseconds resolution. + * $pid: PID of the running process. + * $alpn: ALPN identifier of the protocol which + generates the response. For HTTP/1, ALPN is + always http/1.1, regardless of minor version. + Default: )" << DEFAULT_ACCESSLOG_FORMAT << R"( --errorlog-file= Set path to write error log. To reopen file,