From d196639aed7fabe176b7d8069932c067e29cbab9 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sat, 4 Jun 2016 18:53:13 +0900 Subject: [PATCH] Update man pages --- doc/h2load.1 | 2 +- doc/nghttp.1 | 2 +- doc/nghttpd.1 | 2 +- doc/nghttpx.1 | 48 +++++++++++++++++++++++++++++++++++++++++- doc/nghttpx.1.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 103 insertions(+), 4 deletions(-) diff --git a/doc/h2load.1 b/doc/h2load.1 index a56d4577..a683bcbe 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "H2LOAD" "1" "May 26, 2016" "1.11.0" "nghttp2" +.TH "H2LOAD" "1" "June 04, 2016" "1.12.0-DEV" "nghttp2" .SH NAME h2load \- HTTP/2 benchmarking tool . diff --git a/doc/nghttp.1 b/doc/nghttp.1 index e6537d53..d44dc4f5 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTP" "1" "May 26, 2016" "1.11.0" "nghttp2" +.TH "NGHTTP" "1" "June 04, 2016" "1.12.0-DEV" "nghttp2" .SH NAME nghttp \- HTTP/2 client . diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index fb6120ee..8b656113 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPD" "1" "May 26, 2016" "1.11.0" "nghttp2" +.TH "NGHTTPD" "1" "June 04, 2016" "1.12.0-DEV" "nghttp2" .SH NAME nghttpd \- HTTP/2 server . diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index 9bc3a09b..a6650af9 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPX" "1" "May 26, 2016" "1.11.0" "nghttp2" +.TH "NGHTTPX" "1" "June 04, 2016" "1.12.0-DEV" "nghttp2" .SH NAME nghttpx \- HTTP/2 proxy . @@ -179,6 +179,13 @@ multiple addresses. Optionally, TLS can be disabled by specifying "no\-tls" parameter. TLS is enabled by default. .sp +To make this frontend as API endpoint, specify "api" +parameter. This is disabled by default. It is +important to limit the access to the API frontend. +Otherwise, someone may change the backend server, and +break your services, or expose confidential information +to the outside the world. +.sp Default: \fB*,3000\fP .UNINDENT .INDENT 0.0 @@ -1078,6 +1085,14 @@ originally generates HTTP error status code . HTTP status code. If error status code comes from backend server, the custom error pages are not used. .UNINDENT +.SS API +.INDENT 0.0 +.TP +.B \-\-api\-max\-request\-body= +Set the maximum size of request body for API request. +.sp +Default: \fB16K\fP +.UNINDENT .SS Debug .INDENT 0.0 .TP @@ -1682,6 +1697,37 @@ App.new .fi .UNINDENT .UNINDENT +.SH API ENDPOINTS +.sp +nghttpx exposes API endpoints to manipulate it via HTTP based API. By +default, API endpoint is disabled. To enable it, add a dedicated +frontend for API using \fI\%\-\-frontend\fP option with "api" +parameter. All requests which come from this frontend address, will +be treated as API request. +.sp +The following section describes available API endpoints. +.SS PUT /api/v1beta/backend/replace +.sp +This API replaces the current set of backend servers with the +requested ones. The request must carry request body with method PUT +or POST. The request body must be nghttpx configuration file format. +For configuration file format, see \fI\%FILES\fP section. The line +separator inside the request body must be single LF (0x0A). +Currently, only \fI\%backend\fP option is parsed, the +others are simply ignored. The semantics of this API is replace the +current backend with the backend options in request body. Describe +the desired set of backend severs, and nghttpx makes it happen. If +there is no \fI\%backend\fP option is found in request +body, the current set of backend is replaced with the \fI\%backend\fP option\(aqs default value, which is \fB127.0.0.1,80\fP\&. +.sp +The replacement is done instantly without breaking existing +connections or requests. It also avoids any process creation as is +the case with hot swapping with signals. +.sp +The one limitation is that only numeric IP address is allowd in +\fI\%backend\fP in request body while non numeric +hostname is allowed in command\-line or configuration file is read +using \fI\%\-\-conf\fP\&. .SH SEE ALSO .sp \fInghttp(1)\fP, \fInghttpd(1)\fP, \fIh2load(1)\fP diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst index 718694ba..d8306e9d 100644 --- a/doc/nghttpx.1.rst +++ b/doc/nghttpx.1.rst @@ -163,6 +163,13 @@ Connections Optionally, TLS can be disabled by specifying "no-tls" parameter. TLS is enabled by default. + To make this frontend as API endpoint, specify "api" + parameter. This is disabled by default. It is + important to limit the access to the API frontend. + Otherwise, someone may change the backend server, and + break your services, or expose confidential information + to the outside the world. + Default: ``*,3000`` @@ -972,6 +979,16 @@ HTTP backend server, the custom error pages are not used. +API +~~~ + +.. option:: --api-max-request-body= + + Set the maximum size of request body for API request. + + Default: ``16K`` + + Debug ~~~~~ @@ -1522,6 +1539,42 @@ addresses: App.new +API ENDPOINTS +------------- + +nghttpx exposes API endpoints to manipulate it via HTTP based API. By +default, API endpoint is disabled. To enable it, add a dedicated +frontend for API using :option:`--frontend` option with "api" +parameter. All requests which come from this frontend address, will +be treated as API request. + +The following section describes available API endpoints. + +PUT /api/v1beta/backend/replace +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This API replaces the current set of backend servers with the +requested ones. The request must carry request body with method PUT +or POST. The request body must be nghttpx configuration file format. +For configuration file format, see `FILES`_ section. The line +separator inside the request body must be single LF (0x0A). +Currently, only :option:`backend <--backend>` option is parsed, the +others are simply ignored. The semantics of this API is replace the +current backend with the backend options in request body. Describe +the desired set of backend severs, and nghttpx makes it happen. If +there is no :option:`backend <--backend>` option is found in request +body, the current set of backend is replaced with the :option:`backend +<--backend>` option's default value, which is ``127.0.0.1,80``. + +The replacement is done instantly without breaking existing +connections or requests. It also avoids any process creation as is +the case with hot swapping with signals. + +The one limitation is that only numeric IP address is allowd in +:option:`backend <--backend>` in request body while non numeric +hostname is allowed in command-line or configuration file is read +using :option:`--conf`. + SEE ALSO --------