diff --git a/doc/Makefile.am b/doc/Makefile.am index 492931dd..d7f0a021 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -27,6 +27,10 @@ EXTRA_DIST = \ mkapiref.py \ README.rst \ apiref-header.rst \ + nghttp.1.rst \ + nghttpd.1.rst \ + nghttpx.1.rst \ + h2load.1.rst \ sources/index.rst \ sources/tutorial-client.rst \ sources/tutorial-server.rst \ diff --git a/doc/h2load.1 b/doc/h2load.1 index 2523901b..7fc773f9 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.45.1. -.TH H2LOAD "1" "June 2014" "h2load nghttp2/0.4.1" "User Commands" +.TH H2LOAD "1" "July 2014" "h2load nghttp2/0.4.2-DEV" "User Commands" .SH NAME h2load \- HTTP/2 benchmarking tool .SH SYNOPSIS @@ -45,8 +45,8 @@ than 16, this option is ignored. Otherwise 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\-12 -Default: h2c\-12 +h2c\-13 +Default: h2c\-13 .TP \fB\-v\fR, \fB\-\-verbose\fR Output debug information. diff --git a/doc/h2load.1.rst b/doc/h2load.1.rst new file mode 100644 index 00000000..44107a5a --- /dev/null +++ b/doc/h2load.1.rst @@ -0,0 +1,93 @@ +.. program:: h2load + +h2load(1) +========= + +NAME +---- +h2load - HTTP/2 benchmarking tool + +SYNOPSIS +-------- +**h2load** [OPTIONS]... ... + +DESCRIPTION +----------- +benchmarking tool for HTTP/2 and SPDY server + +.. option:: URI + + Specify URI to access. Multiple URIs can be + specified. URIs are used in this order for each + client. All URIs are used, then first URI is + used and then 2nd URI, and so on. The scheme, + host and port in the subsequent URIs, if present, + are ignored. Those in the first URI are used + solely. + +OPTIONS +------- + +.. option:: -n, --requests= + + Number of requests. Default: 1 + +.. option:: -c, --clients= + + + Number of concurrent clients. Default: 1 + +.. option:: -t, --threads= + + + Number of native threads. Default: 1 + +.. 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 + +.. option:: -w, --window-bits= + + + Sets the stream level initial window size to + (2\*\*)-1. For SPDY, 2\*\* is used instead. + +.. option:: -W, --connection-window-bits= + + + Sets the connection level initial window size to + (2\*\*)-1. For SPDY, if is strictly less + than 16, this option is ignored. Otherwise + 2\*\* is used for SPDY. + +.. 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-13 + Default: h2c-13 + +.. 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) diff --git a/doc/nghttp.1 b/doc/nghttp.1 index 99ffb4cc..fa003da6 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.45.1. -.TH NGHTTP "1" "June 2014" "nghttp nghttp2/0.4.1" "User Commands" +.TH NGHTTP "1" "July 2014" "nghttp nghttp2/0.4.2-DEV" "User Commands" .SH NAME nghttp \- HTTP/2 experimental client .SH SYNOPSIS @@ -60,10 +60,6 @@ be in PEM format. Post FILE to server. If '\-' is given, data will be read from stdin. .TP -\fB\-g\fR, \fB\-\-compress\-data\fR -When used with \fB\-d\fR option, compress request body -on the fly using per\-frame compression. -.TP \fB\-m\fR, \fB\-\-multiply=\fR Request each URI times. By default, same URI is not requested twice. This option disables it @@ -99,6 +95,9 @@ Force colored log output. \fB\-\-continuation\fR Send large header to test CONTINUATION. .TP +\fB\-\-no\-content\-length\fR +Don't send content\-length header field. +.TP \fB\-\-version\fR Display version information and exit. .TP diff --git a/doc/nghttp.1.rst b/doc/nghttp.1.rst new file mode 100644 index 00000000..a0bfd2d3 --- /dev/null +++ b/doc/nghttp.1.rst @@ -0,0 +1,166 @@ +.. program:: nghttp + +nghttp(1) +========= + +NAME +---- +nghttp - HTTP/2 experimental client + +SYNOPSIS +-------- +**nghttp** [OPTIONS]... ... + +DESCRIPTION +----------- +HTTP/2 experimental client + +.. option:: URI + + Specify URI to access. + +OPTIONS +------- + +.. option:: -v, --verbose + + + Print debug information such as reception and + transmission of frames and name/value pairs. + +.. 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 + 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 + linking resource will be downloaded. + +.. option:: -s, --stat + + + Print statistics. + +.. option:: -H, --header + + + Add a header to the requests. + +.. 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 + is not requested twice. This option disables it + too. + +.. option:: -u, --upgrade + + + Perform HTTP Upgrade for HTTP/2. This option is + ignored if the request URI has https scheme. If + :option:`-d` is used, the HTTP upgrade request is performed + with OPTIONS method. + +.. option:: -p, --weight= + + + Sets priority group weight. The valid value + range is [1, 256], inclusive. + Default: 16 + +.. option:: -M, --peer-max-concurrent-streams= + + + Use as SETTINGS_MAX_CONCURRENT_STREAMS value + of remote endpoint as if it is received in + SETTINGS frame. The default is large enough as + it is seen as unlimited. + +.. 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:: --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:: --version + + + Display version information and exit. + +.. option:: -h, --help + + + Display this help and exit. + +SEE ALSO +-------- + +nghttpd(1), nghttpx(1), h2load(1) diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index 60ab49cf..5699d5b5 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.45.1. -.TH NGHTTPD "1" "June 2014" "nghttpd nghttp2/0.4.1" "User Commands" +.TH NGHTTPD "1" "July 2014" "nghttpd nghttp2/0.4.2-DEV" "User Commands" .SH NAME nghttpd \- HTTP/2 experimental server .SH SYNOPSIS @@ -73,6 +73,16 @@ Default: 1 \fB\-e\fR, \fB\-\-error\-gzip\fR Make error response gzipped. .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\-\-early\-response\fR +Start sending response when request HEADERS is +received, rather than complete request is +received. +.TP \fB\-\-version\fR Display version information and exit. .TP diff --git a/doc/nghttpd.1.rst b/doc/nghttpd.1.rst new file mode 100644 index 00000000..fa510281 --- /dev/null +++ b/doc/nghttpd.1.rst @@ -0,0 +1,136 @@ +.. program:: nghttpd + +nghttpd(1) +========== + +NAME +---- +nghttpd - HTTP/2 experimental server + +SYNOPSIS +-------- +**nghttpd** [OPTION]... + +**nghttpd** --no-tls [OPTION]... + +DESCRIPTION +----------- +HTTP/2 experimental server + +.. option:: PORT + + Specify listening port number. + +.. option:: PRIVATE_KEY + + Set path to server's private key. Required + unless :option:`--no-tls` is specified. + +.. option:: CERT + + Set path to server's certificate. Required + unless :option:`--no-tls` is specified. + +OPTIONS +------- + +.. option:: -D, --daemon + + + Run in a background. If :option:`-D` is used, the current + working directory is changed to '/'. Therefore + if this option is used, :option:`-d` option must be + specified. + +.. option:: -V, --verify-client + + + The server sends a client certificate request. + If the client did not return a certificate, the + handshake is terminated. Currently, this option + just requests a client certificate and does not + verify it. + +.. 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:: -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 + +.. 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) diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index 6dbe3fa5..8017a4ea 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.45.1. -.TH NGHTTPX "1" "June 2014" "nghttpx nghttp2/0.4.1" "User Commands" +.TH NGHTTPX "1" "July 2014" "nghttpx nghttp2/0.4.2-DEV" "User Commands" .SH NAME nghttpx \- HTTP/2 experimental proxy .SH SYNOPSIS @@ -48,30 +48,6 @@ Resolve backend hostname to IPv6 address only. 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\-\-worker\-read\-rate=\fR Set maximum average read rate on frontend connection per worker. Setting 0 to this option @@ -95,6 +71,11 @@ Set maximum write burst size on frontend connection per worker. Setting 0 to this option means write burst size is unlimited. Default: 0 +.TP +\fB\-\-worker\-frontend\-connections=\fR +Set maximum number of simultaneous connections +frontend accepts. Setting 0 means unlimited. +Default: 0 .SS "Timeout:" .TP \fB\-\-frontend\-http2\-read\-timeout=\fR @@ -144,13 +125,7 @@ request can be specified by .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. +string is described in OpenSSL ciphers(1). .TP \fB\-k\fR, \fB\-\-insecure\fR Don't verify backend server's certificate if \fB\-p\fR, @@ -196,7 +171,7 @@ 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\-12,spdy/3.1,spdy/3,spdy/2,http/1.1 +Default: h2\-13,spdy/3.1,spdy/3,spdy/2,http/1.1 .TP \fB\-\-verify\-client\fR Require and verify client certificate. @@ -223,7 +198,7 @@ matching is done in case\-insensitive manner. The parameter must be delimited by a single comma only and any white spaces are treated as a part of protocol string. -Default: TLSv1.2,TLSv1.1,TLSv1.0 +Default: TLSv1.2,TLSv1.1 .SS "HTTP/2 and SPDY:" .TP \fB\-c\fR, \fB\-\-http2\-max\-concurrent\-streams=\fR @@ -307,11 +282,22 @@ Set the severity level of log output. must be one of INFO, WARNING, ERROR and FATAL. Default: WARNING .TP -\fB\-\-accesslog\fR -Print simple accesslog to stderr. +\fB\-\-accesslog\-file=\fR +Set path to write access log. To reopen file, +send USR1 signal to nghttpx. .TP -\fB\-\-syslog\fR -Send log messages to syslog. +\fB\-\-accesslog\-syslog\fR +Send access log to syslog. If this option is +used, \fB\-\-access\-file\fR option is ignored. +.TP +\fB\-\-errorlog\-file=\fR +Set path to write error log. To reopen file, +send USR1 signal to nghttpx. +Default: \fI\,/dev/stderr\/\fP +.TP +\fB\-\-errorlog\-syslog\fR +Send error log to syslog. If this option is +used, \fB\-\-errorlog\-file\fR option is ignored. .TP \fB\-\-syslog\-facility=\fR Set syslog facility to . diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst new file mode 100644 index 00000000..ce81909c --- /dev/null +++ b/doc/nghttpx.1.rst @@ -0,0 +1,530 @@ +.. 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 + + Set path to server's private key. Required + unless :option:`-p`, :option:`--client` or :option:`--frontend-no-tls` are + given. + +.. option:: CERT + + Set path to server's certificate. Required + unless :option:`-p`, :option:`--client` or :option:`--frontend-no-tls` are + given. + +OPTIONS +------- + +The options are categorized into several groups. + +Connections +^^^^^^^^^^^ + +.. option:: -b, --backend= + + + Set backend host and port. + 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' + +.. option:: --backlog= + + + Set listen backlog size. If -1 is given, + libevent will choose suitable value. + Default: -1 + +.. option:: --backend-ipv4 + + + Resolve backend hostname to IPv4 address only. + +.. option:: --backend-ipv6 + + + Resolve backend hostname to IPv6 address only. + +Performance +^^^^^^^^^^^ + +.. option:: -n, --workers= + + + Set the number of worker threads. + Default: 1 + +.. option:: --worker-read-rate= + + + Set maximum average read rate on frontend + connection per worker. Setting 0 to this option + means read rate is unlimited. + 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. + 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. + 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. + Default: 0 + +.. option:: --worker-frontend-connections= + + + Set maximum number of simultaneous connections + frontend accepts. Setting 0 means unlimited. + Default: 0 + +Timeout +^^^^^^^ + +.. option:: --frontend-http2-read-timeout= + + + Specify read timeout for HTTP/2 and SPDY frontend + connection. + Default: 180 + +.. option:: --frontend-read-timeout= + + + Specify read timeout for HTTP/1.1 frontend + connection. + Default: 180 + +.. option:: --frontend-write-timeout= + + + Specify write timeout for all frontend + connections. + Default: 60 + +.. option:: --backend-read-timeout= + + + Specify read timeout for backend connection. + Default: 900 + +.. option:: --backend-write-timeout= + + + Specify write timeout for backend connection. + Default: 60 + +.. option:: --backend-keep-alive-timeout= + + + Specify keep-alive timeout for backend + connection. + Default: 60 + +.. option:: --backend-http-proxy-uri= + + + Specify proxy URI in the form + http://[:@]:. If a + proxy requires authentication, specify and + . Note that they must be properly + percent-encoded. This proxy is used when the + backend connection is HTTP/2. First, make a + CONNECT request to the proxy and it connects to + the backend on behalf of nghttpx. This forms + tunnel. After that, nghttpx performs SSL/TLS + handshake with the downstream through the tunnel. + The timeouts when connecting and making CONNECT + request can be specified by + :option:`--backend-read-timeout` and + :option:`--backend-write-timeout` options. + +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 + :option:`--backend-no-tls` is not given. + +.. option:: --cacert= + + + Set path to trusted CA certificate file if :option:`-p`, + :option:`--client` or :option:`--http2-bridge` are given and + :option:`--backend-no-tls` is not given. The file must be + in PEM format. It can contain multiple + certificates. If the linked OpenSSL is + configured to load system wide certificates, they + are loaded at startup regardless of this option. + +.. option:: --private-key-passwd-file= + + + Path to file that contains password for the + server's private key. If none is given and the + private key is password protected it'll be + requested interactively. + +.. option:: --subcert=: + + + Specify additional certificate and private key + file. nghttpx will choose certificates based on + the hostname indicated by client using TLS SNI + extension. This option can be used multiple + times. + +.. 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-13,spdy/3.1,spdy/3,spdy/2,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 + certificates. + +.. 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, TLSv1.0 and SSLv3. The name + matching is done in case-insensitive manner. The + parameter must be delimited by a single comma + only and any white spaces are treated as a part + of protocol string. + Default: TLSv1.2,TLSv1.1 + +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 + +.. 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 + +.. 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 + +.. 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 + +.. option:: --backend-http2-connection-window-bits= + + + Sets the per-connection window size of HTTP/2 + backend connection to 2\*\*-1. + 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 +^^^^ + +.. describe:: (default mode) + + Accept HTTP/2, SPDY and HTTP/1.1 over SSL/TLS. + If :option:`--frontend-no-tls` is used, accept HTTP/2 and + HTTP/1.1. The incoming HTTP/1.1 connection can + be upgraded to HTTP/2 through HTTP Upgrade. The + protocol to the backend is HTTP/1.1. + +.. 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 + connection and relayed to the backend. See + :option:`--backend-http-proxy-uri` option if you are behind + the proxy and want to connect to the outside + HTTP/2 proxy. + +.. option:: --client + + + Accept HTTP/2 and HTTP/1.1 without SSL/TLS. The + incoming HTTP/1.1 connection can be upgraded to + HTTP/2 connection through HTTP Upgrade. The + protocol to the backend is HTTP/2. To use + nghttpx as a forward proxy, use :option:`-p` option + instead. + +.. 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 +^^^^^^^ + +.. option:: -L, --log-level= + + + Set the severity level of log output. + must be one of INFO, WARNING, ERROR and FATAL. + Default: WARNING + +.. 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. + +.. option:: --errorlog-file= + + + Set path to write error log. To reopen file, + send USR1 signal to nghttpx. + Default: /dev/stderr + +.. option:: --errorlog-syslog + + + Send error log to syslog. If this option is + used, :option:`--errorlog-file` option is ignored. + +.. option:: --syslog-facility= + + + Set syslog facility to . + Default: daemon + +Misc +^^^^ + +.. option:: --add-x-forwarded-for + + + Append X-Forwarded-For header field to the + downstream request. + +.. option:: --no-via + + + Don't append to Via header field. If Via header + field is received, it is left unaltered. + +.. 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 + +.. 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" + +.. 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. + +.. 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. + +.. 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. + +.. option:: -D, --daemon + + + Run in a background. If :option:`-D` is used, the current + 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 + +.. option:: -v, --version + + + Print version and exit. + +.. option:: -h, --help + + + Print this help and exit. + +SEE ALSO +-------- + +nghttp(1), nghttpd(1), h2load(1) diff --git a/doc/sources/index.rst b/doc/sources/index.rst index df92db7f..47acaffd 100644 --- a/doc/sources/index.rst +++ b/doc/sources/index.rst @@ -20,6 +20,10 @@ Contents: tutorial-client tutorial-server tutorial-hpack + nghttp.1 + nghttpd.1 + nghttpx.1 + h2load.1 nghttpx-howto h2load-howto apiref diff --git a/makemanpages b/makemanpages index c7d565dd..ad5a0225 100755 --- a/makemanpages +++ b/makemanpages @@ -11,3 +11,7 @@ help2man --output=doc/nghttpx.1 --name="HTTP/2 experimental proxy" \ 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 +done diff --git a/man2rst.py b/man2rst.py new file mode 100755 index 00000000..fd91667e --- /dev/null +++ b/man2rst.py @@ -0,0 +1,113 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +from __future__ import unicode_literals +import sys +import re + +def man2rst(f): + expect_arg = False + in_arg = False + + 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) + + return text + +if __name__ == '__main__': + man2rst(sys.stdin)