From a8ed200a20bc7a71fab026377880adcd00716779 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sat, 15 Feb 2014 16:46:11 +0900 Subject: [PATCH 1/2] doc: Add man pages for nghttp, nghttpd and nghttpx Patch from Dave Beckett --- doc/Makefile.am | 5 +- doc/nghttp.1 | 90 ++++++++++++++++ doc/nghttpd.1 | 55 ++++++++++ doc/nghttpx.1 | 278 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 427 insertions(+), 1 deletion(-) create mode 100644 doc/nghttp.1 create mode 100644 doc/nghttpd.1 create mode 100644 doc/nghttpx.1 diff --git a/doc/Makefile.am b/doc/Makefile.am index 35b22c51..a46c15b3 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -21,6 +21,8 @@ # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +man_MANS = nghttp.1 nghttpd.1 nghttpx.1 + EXTRA_DIST = README.rst apiref-header.rst index.rst mkapiref.py \ package_README.rst tutorial-client.rst tutorial-server.rst \ nghttp2.h.rst nghttp2ver.h.rst \ @@ -40,7 +42,8 @@ EXTRA_DIST = README.rst apiref-header.rst index.rst mkapiref.py \ _themes/sphinx_rtd_theme/static/fonts/fontawesome-webfont.ttf \ _themes/sphinx_rtd_theme/static/js/theme.js \ _themes/sphinx_rtd_theme/static/css/theme.css \ - _themes/sphinx_rtd_theme/static/css/badge_only.css + _themes/sphinx_rtd_theme/static/css/badge_only.css \ + $(man_MANS) # Makefile for Sphinx documentation # diff --git a/doc/nghttp.1 b/doc/nghttp.1 new file mode 100644 index 00000000..99999040 --- /dev/null +++ b/doc/nghttp.1 @@ -0,0 +1,90 @@ +.\" nghttp2 manual page +.TH nghttp2 "1" "January 2014" "nghttp2" "User Commands" +.SH NAME +nghttp2 \- HTTP2 experimental client +.SH SYNOPSIS +\fBnghttp\fP [\fIOPTIONS\fP] \fIURI\fP... +.SH DESCRIPTION +Experimental client for HTTP 2.0. +.SH OPTIONS +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Print debug information such as reception/ +transmission of frames and name/value pairs. +.TP +\fB\-n\fR, \fB\-\-null\-out\fR +Discard downloaded data. +.TP +\fB\-O\fR, \fB\-\-remote\-name\fR +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. +.TP +\fB\-t\fR, \fB\-\-timeout=\fR +Timeout each request after seconds. +.TP +\fB\-w\fR, \fB\-\-window\-bits=\fR +Sets the stream level initial window size +to 2**\-1. +.TP +\fB\-W\fR, \fB\-\-connection\-window\-bits=\fR +Sets the connection level initial window +size to 2**\-1. +.TP +\fB\-a\fR, \fB\-\-get\-assets\fR +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. +.TP +\fB\-s\fR, \fB\-\-stat\fR +Print statistics. +.TP +\fB\-H\fR, \fB\-\-header\fR +Add a header to the requests. +.TP +\fB\-\-cert=\fR +Use the specified client certificate file. +The file must be in PEM format. +.TP +\fB\-\-key=\fR +Use the client private key file. The file +must be in PEM format. +.TP +\fB\-d\fR, \fB\-\-data=\fR +Post FILE to server. If \- is given, data +will be read from stdin. +.TP +\fB\-m\fR, \fB\-\-multiply=\fR Request each URI times. By default, same +URI is not requested twice. This option +disables it too. +.TP +\fB\-f\fR, \fB\-\-no\-flow\-control\fR +Disables connection and stream level flow +controls. +.TP +\fB\-u\fR, \fB\-\-upgrade\fR +Perform HTTP Upgrade for HTTP/2.0. This +option is ignored if the request URI has +https scheme. +If \fB\-d\fR is used, the HTTP upgrade request is +performed with OPTIONS method. +.TP +\fB\-p\fR, \fB\-\-pri=\fR +Sets stream priority. Default: 1073741824 +.TP +\fB\-M\fR, \fB\-\-peer\-max\-concurrent\-streams=\fR +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. +.TP +\fB\-c\fR, \fB\-\-header\-table\-size=\fR +Specify decoder header table size. +.TP +\fB\-\-color\fR +Force colored log output. +.SH "SEE ALSO" +nghttpd(1), nghttpx(1) diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 new file mode 100644 index 00000000..b622f5b7 --- /dev/null +++ b/doc/nghttpd.1 @@ -0,0 +1,55 @@ +.\" nghttpd manual page +.TH nghttpd "1" "January 2014" "nghttpd" "User Commands" +.SH NAME +nghttpd \- HTTP 2.0 experimental server +.SH SYNOPSIS +\fBnghttpd\fP [\fIOPTIONS\fP...] [\fIPRIVATE_KEY\fP \fICERT\fP] +.SH DESCRIPTION +Experimental HTTP 2.0 server. +.SH "Positional arguments" +.TP +\fIPRIVATE_KEY\fP +Set path to server's private key. Required +unless either \fB\-p\fR or \fB\-\-client\fR is specified. +.TP +\fICERT\fP +Set path to server's certificate. Required +unless either \fB\-p\fR or \fB\-\-client\fR is specified. +.SH OPTIONS +.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 specified. +.TP +\fB\-V\fR, \fB\-\-verify\-client\fR +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. +.TP +\fB\-d\fR, \fB\-\-htdocs=\fR +Specify document root. If this option is +not specified, the document root is the +current working directory. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Print debug information such as reception/ +transmission of frames and name/value pairs. +.TP +\fB\-\-no\-tls\fR +Disable SSL/TLS. +.TP +\fB\-f\fR, \fB\-\-no\-flow\-control\fR +Disables connection and stream level flow +controls. +.TP +\fB\-\-color\fR +Force colored log output. +.TP +\fB\-h\fR, \fB\-\-help\fR +Print this help. +.SH "SEE ALSO" +nghttp(1), nghttpx(1) diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 new file mode 100644 index 00000000..831d6880 --- /dev/null +++ b/doc/nghttpx.1 @@ -0,0 +1,278 @@ +.\" nghttpx manual page +.TH nghttpx "1" "January 2014" "nghttpx" "User Commands" +.SH NAME +nghttpx \- HTTP 2.0 experimental proxy +.SH SYNOPSIS +\fBnghttpx\fP [\fIOPTIONS\fP...] [\fIPRIVATE_KEY\fP \fICERT\fP] +.SH DESCRIPTION +Experimental HTTP 2.0 reverse proxy. +.LP +The default mode is to accept HTTP/2.0, SPDY (if compiled in) and +HTTP/1.1 over SSL/TLS. If \fB\-\-frontend\-no\-tls\fR is used, accept +HTTP/2.0 and HTTP/1.1. The incoming HTTP/1.1 connection can be +upgraded to HTTP/2.0 through HTTP Upgrade. The protocol to the +backend is HTTP/1.1. +.SH "Positional arguments" +.TP +\fIPRIVATE_KEY\fP +Set path to server's private key. Required +unless either \fB\-p\fR or \fB\-\-client\fR is specified. +.TP +\fICERT\fP +Set path to server's certificate. Required +unless either \fB\-p\fR or \fB\-\-client\fR is specified. +.SH OPTIONS +.TP +\fB\-b\fR, \fB\-\-backend=\fR +Set backend host and port. +Default: '127.0.0.1,80' +.TP +\fB\-f\fR, \fB\-\-frontend=\fR +Set frontend host and port. +Default: '0.0.0.0,3000' +.TP +\fB\-\-backlog=\fR +Set listen backlog size. +Default: 256 +.TP +\fB\-\-backend\-ipv4\fR +Resolve backend hostname to IPv4 address +only. +.TP +\fB\-\-backend\-ipv6\fR +Resolve backend hostname to IPv6 address +only. +.TP +\fB\-n\fR, \fB\-\-workers=\fR +Set the number of worker threads. +Default: 1 +.TP +\fB\-\-read\-rate=\fR Set maximum average read rate on frontend +connection. Setting 0 to this option means +read rate is unlimited. +Default: 1048576 +.TP +\fB\-\-read\-burst=\fR +Set maximum read burst size on frontend +connection. Setting 0 to this option means +read burst size is unlimited. +Default: 4194304 +.TP +\fB\-\-write\-rate=\fR +Set maximum average write rate on frontend +connection. Setting 0 to this option means +write rate is unlimited. +Default: 0 +.TP +\fB\-\-write\-burst=\fR +Set maximum write burst size on frontend +connection. Setting 0 to this option means +write burst size is unlimited. +Default: 0 +.TP +\fB\-\-frontend\-http2\-read\-timeout=\fR +Specify read timeout for HTTP/2.0 and SPDY frontend +connection. Default: 180 +.TP +\fB\-\-frontend\-read\-timeout=\fR +Specify read timeout for HTTP/1.1 frontend +connection. Default: 180 +.TP +\fB\-\-frontend\-write\-timeout=\fR +Specify write timeout for all frontends. +connection. Default: 60 +.TP +\fB\-\-backend\-read\-timeout=\fR +Specify read timeout for backend connection. +Default: 900 +.TP +\fB\-\-backend\-write\-timeout=\fR +Specify write timeout for backend +connection. Default: 60 +.TP +\fB\-\-backend\-keep\-alive\-timeout=\fR +Specify keep\-alive timeout for backend +connection. Default: 60 +.TP +\fB\-\-backend\-http\-proxy\-uri=\fR +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.0. First, +make a CONNECT request to the proxy and +it connects to the backend on behalf of +nghttpx. This forms tunnel. After that, nghttpx +performs SSL/TLS handshake with the +downstream through the tunnel. The timeouts +when connecting and making CONNECT request +can be specified by \fB\-\-backend\-read\-timeout\fR +and \fB\-\-backend\-write\-timeout\fR options. +.TP +\fB\-\-ciphers=\fR +Set allowed cipher list. The format of the +string is described in OpenSSL ciphers(1). +If this option is used, \fB\-\-honor\-cipher\-order\fR +is implicitly enabled. +.TP +\fB\-\-honor\-cipher\-order\fR +Honor server cipher order, giving the +ability to mitigate BEAST attacks. +.TP +\fB\-k\fR, \fB\-\-insecure\fR +When used with \fB\-p\fR or \fB\-\-client\fR, don't verify +backend server's certificate. +.TP +\fB\-\-cacert=\fR +When used with \fB\-p\fR or \fB\-\-client\fR, set path to +trusted CA certificate file. +The file must be in PEM format. It can +contain multiple certificates. If the +linked OpenSSL is configured to load system +wide certificates, they are loaded +at startup regardless of this option. +.TP +\fB\-\-private\-key\-passwd\-file=\fR +Path to file that contains password for the +server's private key. If none is given and +the private key is password protected it'll +be requested interactively. +.TP +\fB\-\-subcert=\fR: +Specify additional certificate and private +key file. nghttpx will choose certificates +based on the hostname indicated by client +using TLS SNI extension. This option can be +used multiple times. +.TP +\fB\-\-backend\-tls\-sni\-field=\fR +Explicitly set the content of the TLS SNI +extension. This will default to the backend +HOST name. +.TP +\fB\-\-dh\-param\-file=\fR +Path to file that contains DH parameters in +PEM format. Without this option, DHE cipher +suites are not available. +.TP +\fB\-\-npn\-list=\fR +Comma delimited list of NPN protocol sorted +in the order of preference. That means +most desirable protocol comes first. +The parameter must be delimited by a single +comma only and any white spaces are treated +as a part of protocol string. +Default: HTTP\-draft\-07/2.0,http/1.1 +.TP +\fB\-\-verify\-client\fR +Require and verify client certificate. +.TP +\fB\-\-verify\-client\-cacert=\fR +Path to file that contains CA certificates +to verify client certificate. +The file must be in PEM format. It can +contain multiple certificates. +.TP +\fB\-\-client\-private\-key\-file=\fR +Path to file that contains client private +key used in backend client authentication. +.TP +\fB\-\-client\-cert\-file=\fR +Path to file that contains client +certificate used in backend client +authentication. +.TP +\fB\-c\fR, \fB\-\-http2\-max\-concurrent\-streams=\fR +Set the maximum number of the concurrent +streams in one HTTP/2.0 and SPDY session. +Default: 100 +.TP +\fB\-\-frontend\-http2\-window\-bits=\fR +Sets the initial window size of HTTP/2.0 and SPDY +frontend connection to 2**\-1. +Default: 16 +.TP +\fB\-\-frontend\-no\-tls\fR +Disable SSL/TLS on frontend connections. +.TP +\fB\-\-backend\-http2\-window\-bits=\fR +Sets the initial window size of HTTP/2.0 and SPDY +backend connection to 2**\-1. +Default: 16 +.TP +\fB\-\-backend\-no\-tls\fR +Disable SSL/TLS on backend connections. +.TP +\fB\-s\fR, \fB\-\-http2\-proxy\fR +Like default mode, but enable secure proxy mode. +.TP +\fB\-\-http2\-bridge\fR +Like default mode, but communicate with the +backend in HTTP/2.0 over SSL/TLS. Thus the +incoming all connections are converted +to HTTP/2.0 connection and relayed to +the backend. See \fB\-\-backend\-http\-proxy\-uri\fR +option if you are behind the proxy and want +to connect to the outside HTTP/2.0 proxy. +.TP +\fB\-\-client\fR +Accept HTTP/2.0 and HTTP/1.1 without SSL/TLS. +The incoming HTTP/1.1 connection can be +upgraded to HTTP/2.0 connection through +HTTP Upgrade. +The protocol to the backend is HTTP/2.0. +To use nghttpx as a forward proxy, use \fB\-p\fR +option instead. +.TP +\fB\-p\fR, \fB\-\-client\-proxy\fR Like \fB\-\-client\fR option, but it also requires +the request path from frontend must be +an absolute URI, suitable for use as a +forward proxy. +.TP +\fB\-L\fR, \fB\-\-log\-level=\fR +Set the severity level of log output. +INFO, WARNING, ERROR and FATAL. +Default: WARNING +.TP +\fB\-\-accesslog\fR +Print simple accesslog to stderr. +.TP +\fB\-\-syslog\fR +Send log messages to syslog. +.TP +\fB\-\-syslog\-facility=\fR +Set syslog facility. +Default: daemon +.TP +\fB\-\-add\-x\-forwarded\-for\fR +Append X\-Forwarded\-For header field to the +downstream request. +.TP +\fB\-\-no\-via\fR +Don't append to Via header field. If Via +header field is received, it is left +unaltered. +.TP +\fB\-D\fR, \fB\-\-daemon\fR +Run in a background. If \fB\-D\fR is used, the +current working directory is changed to '/'. +.TP +\fB\-\-pid\-file=\fR +Set path to save PID of this program. +.TP +\fB\-\-user=\fR +Run this program as USER. This option is +intended to be used to drop root privileges. +.TP +\fB\-\-conf=\fR +Load configuration from PATH. +Default: \fI/etc/nghttpx/nghttpx.conf\fP +.TP +\fB\-v\fR, \fB\-\-version\fR +Print version and exit. +.TP +\fB\-h\fR, \fB\-\-help\fR +Print this help and exit. +.SH "SEE ALSO" +nghttp(1), nghttpd(1) From f25545b2dbb13dc703a65523516c2597013c8fcb Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sat, 15 Feb 2014 17:49:32 +0900 Subject: [PATCH 2/2] Fix doc EXTRA_DIST to include source .rst files Also erase generated .rst files on `make clean`. --- doc/Makefile.am | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index a46c15b3..7a3f878e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -23,9 +23,13 @@ man_MANS = nghttp.1 nghttpd.1 nghttpx.1 -EXTRA_DIST = README.rst apiref-header.rst index.rst mkapiref.py \ - package_README.rst tutorial-client.rst tutorial-server.rst \ - nghttp2.h.rst nghttp2ver.h.rst \ +EXTRA_DIST = \ + mkapiref.py \ + README.rst \ + apiref-header.rst \ + sources/index.rst \ + sources/tutorial-client.rst \ + sources/tutorial-server.rst \ _themes/sphinx_rtd_theme/footer.html \ _themes/sphinx_rtd_theme/theme.conf \ _themes/sphinx_rtd_theme/layout_old.html \ @@ -85,7 +89,7 @@ apiref.rst: $(top_builddir)/lib/includes/nghttp2/nghttp2ver.h \ $(PYTHON) $(top_srcdir)/doc/mkapiref.py \ --header $(top_srcdir)/doc/apiref-header.rst $^ > $@ -clean: +clean-local: -rm apiref.rst -rm -rf $(BUILDDIR)/*