Mercurial > hg > nginx-site
changeset 1450:f5b5eefc43cb
Updated commercial docs for the upcoming release.
| author | Ruslan Ermilov <ru@nginx.com> |
|---|---|
| date | Thu, 09 Apr 2015 19:18:54 +0300 |
| parents | c79501e16e26 |
| children | 45869c3eb9c3 |
| files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_status_module.xml xml/en/docs/http/ngx_http_upstream_conf_module.xml xml/en/docs/http/ngx_http_upstream_module.xml xml/en/docs/index.xml xml/en/docs/ngx_core_module.xml xml/en/docs/stream/ngx_stream_core_module.xml xml/en/docs/stream/ngx_stream_proxy_module.xml xml/en/docs/stream/ngx_stream_ssl_module.xml xml/en/docs/stream/ngx_stream_upstream_module.xml xml/ru/GNUmakefile xml/ru/docs/http/ngx_http_status_module.xml xml/ru/docs/http/ngx_http_upstream_conf_module.xml xml/ru/docs/http/ngx_http_upstream_module.xml xml/ru/docs/index.xml xml/ru/docs/ngx_core_module.xml |
| diffstat | 16 files changed, 2173 insertions(+), 564 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/en/GNUmakefile Thu Apr 09 19:18:54 2015 +0300 @@ -80,6 +80,7 @@ http/ngx_http_stub_status_module \ http/ngx_http_sub_module \ http/ngx_http_upstream_module \ + http/ngx_http_upstream_conf_module \ http/ngx_http_userid_module \ http/ngx_http_uwsgi_module \ http/ngx_http_xslt_module \ @@ -92,6 +93,7 @@ mail/ngx_mail_ssl_module \ stream/ngx_stream_core_module \ stream/ngx_stream_proxy_module \ + stream/ngx_stream_ssl_module \ stream/ngx_stream_upstream_module \ TOP = \
--- a/xml/en/docs/http/ngx_http_status_module.xml Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/en/docs/http/ngx_http_status_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -9,7 +9,7 @@ <module name="Module ngx_http_status_module" link="/en/docs/http/ngx_http_status_module.html" lang="en" - rev="4"> + rev="6"> <section id="summary"> @@ -32,40 +32,58 @@ <para> <example> -upstream <emphasis>backend</emphasis> { - <emphasis>zone</emphasis> upstream_backend 64k; +http { + upstream <emphasis>backend</emphasis> { + <emphasis>zone</emphasis> http_backend 64k; + + server backend1.example.com weight=5; + server backend2.example.com; + } + + proxy_cache_path /data/nginx/cache_backend keys_zone=<emphasis>cache_backend</emphasis>:10m; + + server { + server_name backend.example.com; + + location / { + proxy_pass http://backend; + proxy_cache cache_backend; - server backend1.example.com weight=5; - server backend2.example.com; + health_check; + } + + <emphasis>status_zone server_backend;</emphasis> + } + + server { + listen 127.0.0.1; + + location /upstream_conf { + upstream_conf; + } + + location /status { + status; + } + + location = /status.html { + } + } } -proxy_cache_path /data/nginx/cache_backend keys_zone=<emphasis>cache_backend</emphasis>:10m; - -server { - server_name backend.example.com; +stream { + upstream <emphasis>backend</emphasis> { + <emphasis>zone</emphasis> stream_backend 64k; - location / { - proxy_pass http://backend; - proxy_cache cache_backend; - - health_check; + server backend1.example.com:12345 weight=5; + server backend2.example.com:12345; } - <emphasis>status_zone server_backend;</emphasis> -} - -server { - listen 127.0.0.1; - - location /upstream_conf { - upstream_conf; - } - - location /status { - status; - } - - location = /status.html { + server { + listen 127.0.0.1:12345; + proxy_pass backend; + <emphasis>status_zone server_backend;</emphasis> + health_check; } } </example> @@ -81,6 +99,11 @@ http://127.0.0.1/status/upstreams/backend http://127.0.0.1/status/upstreams/backend/1 http://127.0.0.1/status/upstreams/backend/1/weight +http://127.0.0.1/status/stream +http://127.0.0.1/status/stream/upstreams +http://127.0.0.1/status/stream/upstreams/backend +http://127.0.0.1/status/stream/upstreams/backend/1 +http://127.0.0.1/status/stream/upstreams/backend/1/weight </example> </para> @@ -138,9 +161,11 @@ <para> Enables collection of virtual -<link doc="ngx_http_core_module.xml" id="server"/> -status information in the specified <value>zone</value>. -Several virtual servers may share the same zone. +<link doc="ngx_http_core_module.xml" id="server">http</link> +or +<link doc="../stream/ngx_stream_core_module.xml" id="server">stream</link> +(1.7.11) server status information in the specified <value>zone</value>. +Several servers may share the same zone. </para> </directive> @@ -157,7 +182,7 @@ <tag-name id="version"><literal>version</literal></tag-name> <tag-desc> Version of the provided data set. -The current version is 4. +The current version is 5. </tag-desc> <tag-name><literal>nginx_version</literal></tag-name> @@ -170,6 +195,12 @@ The address of the server that accepted status request. </tag-desc> +<tag-name id="generation"><literal>generation</literal></tag-name> +<tag-desc> +The total number of configuration +<link doc="../control.xml" id="reconfiguration">reloads</link>. +</tag-desc> + <tag-name id="load_timestamp"><literal>load_timestamp</literal></tag-name> <tag-desc> Time of the last reload of configuration, in milliseconds since Epoch. @@ -180,6 +211,19 @@ Current time in milliseconds since Epoch. </tag-desc> +<tag-name id="processes"><literal>processes</literal></tag-name> +<tag-desc> +<list type="tag"> + +<tag-name id="respawned"><literal>respawned</literal></tag-name> +<tag-desc> +The total number of abnormally terminated and respawned +child processes. +</tag-desc> + +</list> +</tag-desc> + <tag-name><literal>connections</literal></tag-name> <tag-desc> <list type="tag"> @@ -330,11 +374,13 @@ The current number of active connections. </tag-desc> +<!-- <tag-name><literal>keepalive</literal></tag-name> <tag-desc> The current number of idle <link doc="ngx_http_upstream_module.xml" id="keepalive"/> connections. </tag-desc> +--> <tag-name id="max_conns"><literal>max_conns</literal></tag-name> <tag-desc> @@ -451,6 +497,26 @@ when the server was last selected to process a request (1.7.5). </tag-desc> +<tag-name id="header_time"><literal>header_time</literal></tag-name> +<tag-desc> +The average time to get the +<link doc="ngx_http_upstream_module.xml" id="var_upstream_header_time">response +header</link> from the server (1.7.10). +The field is available when using the +<link doc="ngx_http_upstream_module.xml" id="least_time"/> +load balancing method. +</tag-desc> + +<tag-name id="response_time"><literal>response_time</literal></tag-name> +<tag-desc> +The average time to get the +<link doc="ngx_http_upstream_module.xml" id="var_upstream_response_time">full +response</link> from the server (1.7.10). +The field is available when using the +<link doc="ngx_http_upstream_module.xml" id="least_time"/> +load balancing method. +</tag-desc> + </list> </tag-desc> @@ -537,6 +603,206 @@ </list> </tag-desc> +<tag-name id="stream"><literal>stream</literal></tag-name> +<tag-desc> + +<list type="tag"> +<tag-name><literal>server_zones</literal></tag-name> +<tag-desc> +For each <link id="status_zone"/>: +<list type="tag"> + +<tag-name><literal>processing</literal></tag-name> +<tag-desc> +The number of +client connections that are currently being processed. +</tag-desc> + +<tag-name><literal>connections</literal></tag-name> +<tag-desc> +The total number of +connections accepted from clients. +</tag-desc> + +<tag-name><literal>received</literal></tag-name> +<tag-desc> +The total number of bytes received from clients. +</tag-desc> + +<tag-name><literal>sent</literal></tag-name> +<tag-desc> +The total number of bytes sent to clients. +</tag-desc> + +</list> +</tag-desc> + +<tag-name><literal>upstreams</literal></tag-name> +<tag-desc> +For each +<link doc="../stream/ngx_stream_upstream_module.xml" id="server"/> +in the +<link doc="../stream/ngx_stream_upstream_module.xml" id="zone">dynamically +configurable</link> +<link doc="../stream/ngx_stream_upstream_module.xml" id="upstream">group</link>, +the following data are provided: +<list type="tag"> + +<tag-name><literal>id</literal></tag-name> +<tag-desc> +The ID of the server. +</tag-desc> + +<tag-name><literal>server</literal></tag-name> +<tag-desc> +An +<link doc="../stream/ngx_stream_upstream_module.xml" id="server">address</link> +of the server. +</tag-desc> + +<tag-name><literal>backup</literal></tag-name> +<tag-desc> +A boolean value indicating whether the server is a +<link doc="../stream/ngx_stream_upstream_module.xml" id="backup"/> +server. +</tag-desc> + +<tag-name><literal>weight</literal></tag-name> +<tag-desc> +<link doc="../stream/ngx_stream_upstream_module.xml" id="weight">Weight</link> +of the server. +</tag-desc> + +<tag-name><literal>state</literal></tag-name> +<tag-desc> +Current state, which may be one of +“<literal>up</literal>”, +“<literal>down</literal>”, +“<literal>unavail</literal>”, +or +“<literal>unhealthy</literal>”. +</tag-desc> + +<tag-name><literal>active</literal></tag-name> +<tag-desc> +The current number of connections. +</tag-desc> + +<tag-name><literal>connections</literal></tag-name> +<tag-desc> +The total number of +client connections forwarded to this server. +</tag-desc> + +<tag-name><literal>connect_time</literal></tag-name> +<tag-desc> +The average time to connect to the upstream server. +The field is available when using the +<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/> +load balancing method. +</tag-desc> + +<tag-name><literal>first_byte_time</literal></tag-name> +<tag-desc> +The average time to receive the first byte of data. +The field is available when using the +<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/> +load balancing method. +</tag-desc> + +<tag-name><literal>response_time</literal></tag-name> +<tag-desc> +The average time to receive the last byte of data. +The field is available when using the +<link doc="../stream/ngx_stream_upstream_module.xml" id="least_time"/> +load balancing method. +</tag-desc> + +<tag-name><literal>sent</literal></tag-name> +<tag-desc> +The total number of bytes sent to this server. +</tag-desc> + +<tag-name><literal>received</literal></tag-name> +<tag-desc> +The total number of bytes received from this server. +</tag-desc> + +<tag-name><literal>fails</literal></tag-name> +<tag-desc> +The total number of +unsuccessful attempts to communicate with the server. +</tag-desc> + +<tag-name><literal>unavail</literal></tag-name> +<tag-desc> +How many times +the server became unavailable for client connections +(state “<literal>unavail</literal>”) +due to the number of unsuccessful attempts reaching the +<link doc="../stream/ngx_stream_upstream_module.xml" id="max_fails"/> +threshold. +</tag-desc> + +<tag-name><literal>health_checks</literal></tag-name> +<tag-desc> +<list type="tag"> + +<tag-name><literal>checks</literal></tag-name> +<tag-desc> +The total number of +<link doc="../stream/ngx_stream_upstream_module.xml" id="health_check">health check</link> +requests made. +</tag-desc> + +<tag-name><literal>fails</literal></tag-name> +<tag-desc> +The number of failed health checks. +</tag-desc> + +<tag-name><literal>unhealthy</literal></tag-name> +<tag-desc> +How many times +the server became unhealthy (state “<literal>unhealthy</literal>”). +</tag-desc> + +<tag-name><literal>last_passed</literal></tag-name> +<tag-desc> +Boolean indicating +if the last health check request was successful and passed +<link doc="../stream/ngx_stream_upstream_module.xml" id="match">tests</link>. +</tag-desc> + +</list> +</tag-desc> + +<tag-name><literal>downtime</literal></tag-name> +<tag-desc> +Total time +the server was in the “<literal>unavail</literal>” +and “<literal>unhealthy</literal>” states. +</tag-desc> + +<tag-name><literal>downstart</literal></tag-name> +<tag-desc> +The time (in milliseconds since Epoch) +when the server became +“<literal>unavail</literal>” +or “<literal>unhealthy</literal>”. +</tag-desc> + +<tag-name><literal>selected</literal></tag-name> +<tag-desc> +The time (in milliseconds since Epoch) +when the server was last selected to process a connection. +</tag-desc> + +</list> +</tag-desc> + +</list> +</tag-desc> + </list> </para> @@ -548,6 +814,36 @@ <list type="bullet"> <listitem> +The <literal>keepalive</literal> field of an upstream server +was removed in <link id="version"/> 5. +</listitem> + +<listitem> +The <link id="stream">stream</link> status data +were added in <link id="version"/> 5. +</listitem> + +<listitem> +The +<link id="generation"/> field +was added in <link id="version"/> 5. +</listitem> + +<listitem> +The +<link id="respawned"/> field in +<link id="processes"/> +was added in <link id="version"/> 5. +</listitem> + +<listitem> +The +<link id="header_time"/> and <link id="response_time"/> fields in +<link id="upstreams"/> +were added in <link id="version"/> 5. +</listitem> + +<listitem> The <link id="selected"/> field in <link id="upstreams"/>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/http/ngx_http_upstream_conf_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -0,0 +1,350 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_upstream_conf_module" + link="/en/docs/http/ngx_http_upstream_conf_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_http_upstream_conf_module</literal> module +allows configuring upstream server groups on-the-fly +via a simple HTTP interface without the need of restarting nginx. +The +<link doc="ngx_http_upstream_module.xml" id="zone">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="zone">stream</link> +server group must reside in the shared memory. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +upstream backend { + zone upstream_backend 64k; + + ... +} + +server { + location /upstream_conf { + <emphasis>upstream_conf</emphasis>; + allow 127.0.0.1; + deny all; + } +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="upstream_conf"> +<syntax/> +<default/> +<context>location</context> + +<para> +Turns on the HTTP interface of upstream configuration in the surrounding +location. +Access to this location should be +<link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. +</para> + +<para> +Configuration commands can be used to: +<list type="bullet"> + +<listitem>view the group configuration;</listitem> + +<listitem>view, modify, or remove a server;</listitem> + +<listitem>add a new server.</listitem> + +</list> +<note> +Since addresses in a group are not required to be unique, specific +servers in a group are referenced by their IDs. +IDs are assigned automatically and shown when adding a new server +or viewing the group configuration. +</note> +</para> + +<para> +A configuration command consists of parameters passed as request arguments, +for example: +<example> +http://127.0.0.1/upstream_conf?upstream=backend +</example> +</para> + +<para> +The following parameters are supported: + +<list type="tag" compact="no"> + +<tag-name> +<literal>stream=</literal></tag-name> +<tag-desc> +Selects a +<link doc="../stream/ngx_stream_upstream_module.xml">stream</link> +upstream server group. +Without this parameter, selects an +<link doc="ngx_http_upstream_module.xml">http</link> +upstream server group. +</tag-desc> + +<tag-name> +<literal>upstream=</literal><value>name</value></tag-name> +<tag-desc> +Selects a group to work with. +This parameter is mandatory. +</tag-desc> + +<tag-name> +<literal>id=</literal><value>number</value></tag-name> +<tag-desc> +Selects a server for viewing, modifying, or removing. +</tag-desc> + +<tag-name> +<literal>remove=</literal></tag-name> +<tag-desc> +Removes a server from the group. +</tag-desc> + +<tag-name> +<literal>add=</literal></tag-name> +<tag-desc> +Adds a new server to the group. +</tag-desc> + +<tag-name> +<literal>backup=</literal></tag-name> +<tag-desc> +Required to add a backup server. +<note> +Before version 1.7.2, <literal>backup=</literal> +was also required to view, modify, or remove existing backup servers. +</note> +</tag-desc> + +<tag-name> +<literal>server=</literal><value>address</value></tag-name> +<tag-desc> +Same as the “<literal>address</literal>” parameter +of the +<link doc="ngx_http_upstream_module.xml" id="server">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link> +upstream server. +<para> +When adding a server, it is possible to specify it as a domain name. +In this case, changes of the IP addresses that correspond to a domain name +will be monitored and automatically applied to the upstream +configuration without the need of restarting nginx (1.7.2). +This requires the “<literal>resolver</literal>” directive in the +<link doc="ngx_http_core_module.xml" id="resolver">http</link> +or +<link doc="../stream/ngx_stream_core_module.xml" id="resolver">stream</link> +block. +See also the “<literal>resolve</literal>” parameter +of the +<link doc="ngx_http_upstream_module.xml" id="resolve">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="resolve">stream</link> +upstream server. +</para> +</tag-desc> + +<tag-name> +<literal>weight=</literal><value>number</value></tag-name> +<tag-desc> +Same as the “<literal>weight</literal>” parameter +of the +<link doc="ngx_http_upstream_module.xml" id="weight">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="weight">stream</link> +upstream server. +</tag-desc> + +<tag-name> +<literal>max_conns=</literal><value>number</value></tag-name> +<tag-desc> +Same as the “<literal>max_conns</literal>” parameter +of the +<link doc="ngx_http_upstream_module.xml" id="max_conns">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="max_conns">stream</link> +upstream server. +</tag-desc> + +<tag-name> +<literal>max_fails=</literal><value>number</value></tag-name> +<tag-desc> +Same as the “<literal>max_fails</literal>” parameter +of the +<link doc="ngx_http_upstream_module.xml" id="max_fails">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="max_fails">stream</link> +upstream server. +</tag-desc> + +<tag-name> +<literal>fail_timeout=</literal><value>time</value></tag-name> +<tag-desc> +Same as the “<literal>fail_timeout</literal>” parameter +of the +<link doc="ngx_http_upstream_module.xml" id="fail_timeout">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="fail_timeout">stream</link> +upstream server. +</tag-desc> + +<tag-name> +<literal>slow_start=</literal><value>time</value></tag-name> +<tag-desc> +Same as the “<literal>slow_start</literal>” parameter +of the +<link doc="ngx_http_upstream_module.xml" id="slow_start">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="slow_start">stream</link> +upstream server. +</tag-desc> + +<tag-name> +<literal>down=</literal></tag-name> +<tag-desc> +Same as the “<literal>down</literal>” parameter +of the +<link doc="ngx_http_upstream_module.xml" id="down">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link> +upstream server. +</tag-desc> + +<tag-name id="drain"><literal>drain=</literal></tag-name> +<tag-desc> +Puts the +<link doc="ngx_http_upstream_module.xml">http</link> +upstream server in the “draining” mode (1.7.5). +In this mode, only requests of the +<link doc="ngx_http_upstream_module.xml" id="sticky">bound</link> to the server +will be proxied to it. +</tag-desc> + +<tag-name> +<literal>up=</literal></tag-name> +<tag-desc> +The opposite of the “<literal>down</literal>” parameter +of the +<link doc="ngx_http_upstream_module.xml" id="down">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link> +upstream server. +</tag-desc> + +<tag-name> +<literal>route=</literal><value>string</value></tag-name> +<tag-desc> +Same as the “<literal>route</literal>” parameter of the +<link doc="ngx_http_upstream_module.xml" id="route">http</link> +upstream server. +</tag-desc> + +</list> + +The first three parameters select an object. +This can be either the whole http or stream upstream server group, +or a specific server. +Without other parameters, the configuration of the selected +group or server is shown. +</para> + +<para> +For example, to view the configuration of the whole group, send: +<example> +http://127.0.0.1/upstream_conf?upstream=backend +</example> + +To view the configuration of a specific server, also specify its ID: +<example> +http://127.0.0.1/upstream_conf?upstream=backend&id=42 +</example> +</para> + +<para> +To add a new server, +specify its address in the “<literal>server=</literal>” parameter. +Without other parameters specified, a server will be added with other +parameters set to their default values (see the +<link doc="ngx_http_upstream_module.xml" id="server">http</link> +or +<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link> +“<literal>server</literal>” directive). +</para> + +<para> +For example, to add a new primary server, send: +<example> +http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080 +</example> + +To add a new backup server, send: +<example> +http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080 +</example> + +To add a new primary server, +set its parameters to non-default values +and mark it as “<literal>down</literal>”, send: +<example> +http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down= +</example> + +To remove a server, specify its ID: +<example> +http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42 +</example> + +To mark an existing server as “<literal>down</literal>”, send: +<example> +http://127.0.0.1/upstream_conf?upstream=backend&id=42&down= +</example> + +To modify the address of an existing server, send: +<example> +http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123 +</example> + +To modify other parameters of an existing server, send: +<example> +http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4 +</example> + +The above examples are for an +<link doc="ngx_http_upstream_module.xml">http</link> +upstream server group. +Similar examples for a +<link doc="../stream/ngx_stream_upstream_module.xml">stream</link> +upstream server group require the “<literal>stream=</literal>” parameter. +</para> + +</directive> + +</section> + +</module>
--- a/xml/en/docs/http/ngx_http_upstream_module.xml Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/en/docs/http/ngx_http_upstream_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -10,7 +10,7 @@ <module name="Module ngx_http_upstream_module" link="/en/docs/http/ngx_http_upstream_module.html" lang="en" - rev="35"> + rev="36"> <section id="summary"> @@ -53,12 +53,15 @@ available as part of our <commercial_version>commercial subscription</commercial_version>: <example> +resolver 10.0.0.1; + upstream <emphasis>dynamic</emphasis> { zone upstream_dynamic 64k; server backend1.example.com weight=5; server backend2.example.com:8080 fail_timeout=5s slow_start=30s; server 192.0.2.1 max_fails=3; + server backend3.example.com resolve; server backup1.example.com:8080 backup; server backup2.example.com:8080 backup; @@ -69,12 +72,6 @@ proxy_pass http://<emphasis>dynamic</emphasis>; health_check; } - - location /upstream_conf { - upstream_conf; - allow 127.0.0.1; - deny all; - } } </example> </para> @@ -298,7 +295,8 @@ or modifying the settings of a particular server without the need of restarting nginx. The configuration is accessible via a special location -handled by <link id="upstream_conf"/>. +handled by +<link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. </para> <para> @@ -528,6 +526,39 @@ </directive> +<directive name="least_time"> +<syntax><literal>header</literal> | <literal>last_byte</literal></syntax> +<default/> +<context>upstream</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies that a group should use a load balancing method where a request +is passed to the server with the least average response time and +least number of active connections, taking into account weights of servers. +If there are several such servers, they are tried in turn using a +weighted round-robin balancing method. +</para> + +<para> +If the <literal>header</literal> parameter is specified, +time to receive the +<link id="var_upstream_header_time">response header</link> is used. +If the <literal>last_byte</literal> parameter is specified, +time to receive the <link id="var_upstream_response_time">full response</link> +is used. +</para> + +<para> +<note> +This directive is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</directive> + + <directive name="health_check"> <syntax>[<value>parameters</value>]</syntax> <default/> @@ -836,6 +867,8 @@ <literal>cookie</literal> <value>name</value> [<literal>expires=</literal><value>time</value>] [<literal>domain=</literal><value>domain</value>] + [<literal>httponly</literal>] + [<literal>secure</literal>] [<literal>path=</literal><value>path</value>]</syntax> <syntax> <literal>route</literal> <value>$variable</value> ...</syntax> @@ -883,23 +916,34 @@ Additional parameters may be as follows: <list type="tag"> -<tag-name><literal>expires</literal></tag-name> +<tag-name><literal>expires=</literal><value>time</value></tag-name> <tag-desc> -Sets the time for which a browser should keep the cookie. +Sets the <value>time</value> for which a browser should keep the cookie. The special value <literal>max</literal> will cause the cookie to expire on “<literal>31 Dec 2037 23:55:55 GMT</literal>”. If the parameter is not specified, it will cause the cookie to expire at the end of a browser session. </tag-desc> -<tag-name><literal>domain</literal></tag-name> +<tag-name><literal>domain=</literal><value>domain</value></tag-name> <tag-desc> -Defines the domain for which the cookie is set. +Defines the <value>domain</value> for which the cookie is set. +</tag-desc> + +<tag-name><literal>httponly</literal></tag-name> +<tag-desc> +Adds the <literal>HttpOnly</literal> attribute to the cookie (1.7.11). </tag-desc> -<tag-name><literal>path</literal></tag-name> +<tag-name><literal>secure</literal></tag-name> <tag-desc> -Defines the path for which the cookie is set. +Adds the <literal>Secure</literal> attribute to the cookie (1.7.11). + +</tag-desc> + +<tag-name><literal>path=</literal><value>path</value></tag-name> +<tag-desc> +Defines the <value>path</value> for which the cookie is set. </tag-desc> </list> @@ -1032,247 +1076,6 @@ </directive> - -<directive name="upstream_conf"> -<syntax/> -<default/> -<context>location</context> - -<para> -Turns on the HTTP interface of upstream configuration in the surrounding -location. -Access to this location should be -<link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. -</para> - -<para> -Configuration commands can be used to: -<list type="bullet"> - -<listitem>view the group configuration;</listitem> - -<listitem>view, modify, or remove a server;</listitem> - -<listitem>add a new server.</listitem> - -</list> -<note> -Since addresses in a group are not required to be unique, specific -servers in a group are referenced by their IDs. -IDs are assigned automatically and shown when adding a new server -or viewing the group configuration. -</note> -</para> - -<para> -A configuration command consists of parameters passed as request arguments, -for example: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic -</example> -</para> - -<para> -The following parameters are supported: - -<list type="tag" compact="no"> - -<tag-name> -<literal>upstream=</literal><value>name</value></tag-name> -<tag-desc> -Selects a group to work with. -This parameter is mandatory. -</tag-desc> - -<tag-name> -<literal>id=</literal><value>number</value></tag-name> -<tag-desc> -Selects a server for viewing, modifying, or removing. -</tag-desc> - -<tag-name> -<literal>remove=</literal></tag-name> -<tag-desc> -Removes a server from the group. -</tag-desc> - -<tag-name> -<literal>add=</literal></tag-name> -<tag-desc> -Adds a new server to the group. -</tag-desc> - -<tag-name> -<literal>backup=</literal></tag-name> -<tag-desc> -Required to add a backup server. -<note> -Before version 1.7.2, <literal>backup=</literal> -was also required to view, modify, or remove existing backup servers. -</note> -</tag-desc> - -<tag-name> -<literal>server=</literal><value>address</value></tag-name> -<tag-desc> -Same as the “<literal>address</literal>” parameter -of the <link id="server"/> directive. -<para> -When adding a server, it is possible to specify it as a domain name. -In this case, changes of the IP addresses that correspond to a domain name -will be monitored and automatically applied to the upstream -configuration without the need of restarting nginx (1.7.2). -This requires the -<link doc="ngx_http_core_module.xml" id="resolver"/> directive in the -<link doc="ngx_http_core_module.xml" id="http"/> block. -See also -the <link id="resolve"/> parameter of the <link id="server"/> directive. -</para> -</tag-desc> - -<tag-name> -<literal>weight=</literal><value>number</value></tag-name> -<tag-desc> -Same as the “<literal>weight</literal>” parameter -of the <link id="server"/> directive. -</tag-desc> - -<tag-name> -<literal>max_conns=</literal><value>number</value></tag-name> -<tag-desc> -Same as the “<literal>max_conns</literal>” parameter -of the <link id="server"/> directive. -</tag-desc> - -<tag-name> -<literal>max_fails=</literal><value>number</value></tag-name> -<tag-desc> -Same as the “<literal>max_fails</literal>” parameter -of the <link id="server"/> directive. -</tag-desc> - -<tag-name> -<literal>fail_timeout=</literal><value>time</value></tag-name> -<tag-desc> -Same as the “<literal>fail_timeout</literal>” parameter -of the <link id="server"/> directive. -</tag-desc> - -<tag-name> -<literal>slow_start=</literal><value>time</value></tag-name> -<tag-desc> -Same as the “<literal>slow_start</literal>” parameter -of the <link id="server"/> directive. -</tag-desc> - -<tag-name> -<literal>down=</literal></tag-name> -<tag-desc> -Same as the “<literal>down</literal>” parameter -of the <link id="server"/> directive. -</tag-desc> - -<tag-name id="drain"><literal>drain=</literal></tag-name> -<tag-desc> -Puts the upstream server in the “draining” mode (1.7.5). -In this mode, only requests <link id="sticky">bound</link> to the server -will be proxied to it. -</tag-desc> - -<tag-name> -<literal>up=</literal></tag-name> -<tag-desc> -The opposite of the “<literal>down</literal>” parameter -of the <link id="server"/> directive. -</tag-desc> - -<tag-name> -<literal>route=</literal><value>string</value></tag-name> -<tag-desc> -Same as the “<literal>route</literal>” parameter -of the <link id="server"/> directive. -</tag-desc> - -</list> - -The first two parameters select an object. -This can be either the whole group or a specific server. -Without other parameters, the configuration of the selected -group or server is shown. -</para> - -<para> -For example, to view the configuration of the whole group, send: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic -</example> - -To view the configuration of a specific server, also specify its ID: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42 -</example> -</para> - -<para> -To add a new server, -specify its address in the “<literal>server=</literal>” parameter. -Without other parameters specified, a server will be added with other -parameters set to their default values (see the <link id="server"/> directive). -</para> - -<para> -For example, to add a new primary server, send: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080 -</example> - -To add a new backup server, send: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&backup=&server=127.0.0.1:8080 -</example> - -To add a new primary server, -set its parameters to non-default values -and mark it as “<literal>down</literal>”, send: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080&weight=2&down= -</example> -</para> - -<para> -To remove a server, specify its ID: -<example> -http://127.0.0.1/upstream_conf?remove=&upstream=dynamic&id=42 -</example> -</para> - -<para> -To mark an existing server as “<literal>down</literal>”, send: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&down= -</example> - -To modify the address of an existing server, send: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&server=192.0.2.3:8123 -</example> - -To modify other parameters of an existing server, send: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&max_fails=3&weight=4 -</example> - -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - </section>
--- a/xml/en/docs/index.xml Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/en/docs/index.xml Thu Apr 09 19:18:54 2015 +0300 @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="17" + rev="19" toc="no"> @@ -405,6 +405,11 @@ </listitem> <listitem> +<link doc="http/ngx_http_upstream_conf_module.xml"> +ngx_http_upstream_conf_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_userid_module.xml"> ngx_http_userid_module</link> </listitem> @@ -477,6 +482,11 @@ </listitem> <listitem> +<link doc="stream/ngx_stream_ssl_module.xml"> +ngx_stream_ssl_module</link> +</listitem> + +<listitem> <link doc="stream/ngx_stream_upstream_module.xml"> ngx_stream_upstream_module</link> </listitem>
--- a/xml/en/docs/ngx_core_module.xml Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/en/docs/ngx_core_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -10,7 +10,7 @@ <module name="Core functionality" link="/en/docs/ngx_core_module.html" lang="en" - rev="12"> + rev="13"> <section id="example" name="Example Configuration"> @@ -158,6 +158,7 @@ <default>logs/error.log error</default> <context>main</context> <context>http</context> +<context>stream</context> <context>server</context> <context>location</context> @@ -195,6 +196,12 @@ be built with <literal>--with-debug</literal>, see “<link doc="debugging_log.xml"/>”. </note> + +<note> +The directive can be specified on the +<literal>stream</literal> level +starting from version 1.7.11. +</note> </para> </directive>
--- a/xml/en/docs/stream/ngx_stream_core_module.xml Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/en/docs/stream/ngx_stream_core_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -9,7 +9,7 @@ <module name="Module ngx_stream_core_module" link="/en/docs/stream/ngx_stream_core_module.html" lang="en" - rev="1"> + rev="2"> <section id="summary"> @@ -63,6 +63,7 @@ <directive name="listen"> <syntax> <value>address</value>:<value>port</value> + [<literal>ssl</literal>] [<literal>bind</literal>] [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>] [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax> @@ -94,11 +95,16 @@ </para> <para> -The directive supports the following parameters: +The <literal>ssl</literal> parameter (1.7.10) allows specifying that all +connections accepted on this port should work in SSL mode. +</para> +<para> +The <literal>listen</literal> directive +can have several additional parameters specific to socket-related system calls. <list type="tag"> -<tag-name id="bind"> +<tag-name> <literal>bind</literal> </tag-name> <tag-desc> @@ -118,7 +124,7 @@ a separate <c-func>bind</c-func> call will always be made. </tag-desc> -<tag-name id="ipv6only"> +<tag-name> <literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal> </tag-name> <tag-desc> @@ -130,7 +136,7 @@ It can only be set once on start. </tag-desc> -<tag-name id="so_keepalive"> +<tag-name> <literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>] </tag-name> <tag-desc> @@ -157,6 +163,7 @@ leave the probe interval (<c-def>TCP_KEEPINTVL</c-def>) at its system default, and set the probes count (<c-def>TCP_KEEPCNT</c-def>) to 10 probes. </tag-desc> + </list> </para> @@ -168,6 +175,62 @@ </directive> +<directive name="resolver"> +<syntax> + <value>address</value> ... + [<literal>valid</literal>=<value>time</value>] + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Configures name servers used to resolve names of upstream servers +into addresses, for example: +<example> +resolver 127.0.0.1 [::1]:5353; +</example> +An address can be specified as a domain name or IP address, +and an optional port. +If port is not specified, the port 53 is used. +Name servers are queried in a round-robin fashion. +</para> + +<para> +By default, nginx will look up both IPv4 and IPv6 addresses while resolving. +If looking up of IPv6 addresses is not desired, +the <literal>ipv6=off</literal> parameter can be specified. +</para> + +<para> +By default, nginx caches answers using the TTL value of a response. +The optional <literal>valid</literal> parameter allows overriding it: +<example> +resolver 127.0.0.1 [::1]:5353 valid=30s; +</example> +</para> + +</directive> + + +<directive name="resolver_timeout"> +<syntax><value>time</value></syntax> +<default>30s</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Sets a timeout for name resolution, for example: +<example> +resolver_timeout 5s; +</example> +</para> + +</directive> + + <directive name="server"> <syntax block="yes"/> <default/>
--- a/xml/en/docs/stream/ngx_stream_proxy_module.xml Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/en/docs/stream/ngx_stream_proxy_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -9,7 +9,7 @@ <module name="Module ngx_stream_proxy_module" link="/en/docs/stream/ngx_stream_proxy_module.html" lang="en" - rev="2"> + rev="3"> <section id="summary"> @@ -83,6 +83,59 @@ </directive> +<directive name="proxy_next_upstream"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +When a connection to the proxied server cannot be established, determines +whether a client connection will be passed to the next server. +</para> + +<para> +Passing a connection to the next server can be limited by +<link id="proxy_next_upstream_tries">the number of tries</link> +and by <link id="proxy_next_upstream_timeout">time</link>. +</para> + +</directive> + + +<directive name="proxy_next_upstream_timeout"> +<syntax><value>time</value></syntax> +<default>0</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Limits the time allowed to pass a connection to the +<link id="proxy_next_upstream">next server</link>. +The <literal>0</literal> value turns off this limitation. +</para> + +</directive> + + +<directive name="proxy_next_upstream_tries"> +<syntax><value>number</value></syntax> +<default>0</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Limits the number of possible tries for passing a connection to the +<link id="proxy_next_upstream">next server</link>. +The <literal>0</literal> value turns off this limitation. +</para> + +</directive> + + <directive name="proxy_pass"> <syntax><value>address</value></syntax> <default/> @@ -111,6 +164,223 @@ </directive> +<directive name="proxy_ssl"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Enables the SSL/TLS protocol for connections to a proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies a <value>file</value> with the certificate in the PEM format +used for authentication to a proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_certificate_key"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies a <value>file</value> with the secret key in the PEM format +used for authentication to a proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_ciphers"> +<syntax><value>ciphers</value></syntax> +<default>DEFAULT</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies the enabled ciphers for connections to a proxied server. +The ciphers are specified in the format understood by the OpenSSL library. +</para> + +<para> +The full list can be viewed using the +“<command>openssl ciphers</command>” command. +</para> + +</directive> + + +<directive name="proxy_ssl_crl"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies a <value>file</value> with revoked certificates (CRL) +in the PEM format used to <link id="proxy_ssl_verify">verify</link> +the certificate of the proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_name"> +<syntax><value>name</value></syntax> +<default>host from proxy_pass</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Allows to override the server name used to +<link id="proxy_ssl_verify">verify</link> +the certificate of the proxied server and to be +<link id="proxy_ssl_server_name">passed through SNI</link> +when establishing a connection with the proxied server. +</para> + +<para> +By default, the host part of the <link id="proxy_pass"/> address is used. +</para> + +</directive> + + +<directive name="proxy_ssl_password_file"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies a <value>file</value> with passphrases for +<link id="proxy_ssl_certificate_key">secret keys</link> +where each passphrase is specified on a separate line. +Passphrases are tried in turn when loading the key. +</para> + +</directive> + + +<directive name="proxy_ssl_server_name"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Enables or disables passing of the server name through +<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">TLS +Server Name Indication extension</link> (SNI, RFC 6066) +when establishing a connection with the proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_session_reuse"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Determines whether SSL sessions can be reused when working with +the proxied server. +If the errors +“<literal>SSL3_GET_FINISHED:digest check failed</literal>” +appear in the logs, try disabling session reuse. +</para> + +</directive> + + +<directive name="proxy_ssl_protocols"> +<syntax> + [<literal>SSLv2</literal>] + [<literal>SSLv3</literal>] + [<literal>TLSv1</literal>] + [<literal>TLSv1.1</literal>] + [<literal>TLSv1.2</literal>]</syntax> +<default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Enables the specified protocols for connections to a proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_trusted_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Specifies a <value>file</value> with trusted CA certificates in the PEM format +used to <link id="proxy_ssl_verify">verify</link> +the certificate of the proxied server. +</para> + +</directive> + + +<directive name="proxy_ssl_verify"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Enables or disables verification of the proxied server certificate. +</para> + +</directive> + + +<directive name="proxy_ssl_verify_depth"> +<syntax><value>number</value></syntax> +<default>1</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Sets the verification depth in the proxied server certificates chain. +</para> + +</directive> + + <directive name="proxy_timeout"> <syntax><value>timeout</value></syntax> <default>10m</default>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/stream/ngx_stream_ssl_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -0,0 +1,326 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_stream_ssl_module" + link="/en/docs/stream/ngx_stream_ssl_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_stream_ssl_module</literal> module (1.7.10) +provides the necessary support for a stream proxy server to work with +the SSL/TLS protocol. +</para> + +<para> +<note> +This module is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="ssl_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Specifies a file with the certificate in the PEM format for the given +server. +If intermediate certificates should be specified in addition to a primary +certificate, they should be specified in the same file in the following +order: the primary certificate comes first, then the intermediate certificates. +A secret key in the PEM format may be placed in the same file. +</para> + +</directive> + + +<directive name="ssl_certificate_key"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Specifies a file with the secret key in the PEM format for the given +server. +</para> + +</directive> + + +<directive name="ssl_ciphers"> +<syntax><value>ciphers</value></syntax> +<default>HIGH:!aNULL:!MD5</default> +<context>stream</context> +<context>server</context> + +<para> +Specifies the enabled ciphers. +The ciphers are specified in the format understood by the +OpenSSL library, for example: +<example> +ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; +</example> +</para> + +<para> +The full list can be viewed using the +“<command>openssl ciphers</command>” command. +</para> + +</directive> + + +<directive name="ssl_dhparam"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Specifies a <value>file</value> with DH parameters for EDH ciphers. +</para> + +</directive> + + +<directive name="ssl_ecdh_curve"> +<syntax><value>curve</value></syntax> +<default>prime256v1</default> +<context>stream</context> +<context>server</context> + +<para> +Specifies a <value>curve</value> for ECDHE ciphers. +</para> + +</directive> + + +<directive name="ssl_handshake_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>stream</context> +<context>server</context> + +<para> +Specifies a timeout for the SSL handshake to complete. +</para> + +</directive> + + +<directive name="ssl_password_file"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Specifies a <value>file</value> with passphrases for +<link id="ssl_certificate_key">secret keys</link> +where each passphrase is specified on a separate line. +Passphrases are tried in turn when loading the key. +</para> + +<para> +Example: +<example> +stream { + ssl_password_file /etc/keys/global.pass; + ... + + server { + listen 127.0.0.1:12345; + ssl_certificate_key /etc/keys/first.key; + } + + server { + listen 127.0.0.1:12346; + + # named pipe can also be used instead of a file + ssl_password_file /etc/keys/fifo; + ssl_certificate_key /etc/keys/second.key; + } +} +</example> +</para> + +</directive> + + +<directive name="ssl_prefer_server_ciphers"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> + +<para> +Specifies that server ciphers should be preferred over client ciphers +when the SSLv3 and TLS protocols are used. +</para> + +</directive> + + +<directive name="ssl_protocols"> +<syntax> + [<literal>SSLv2</literal>] + [<literal>SSLv3</literal>] + [<literal>TLSv1</literal>] + [<literal>TLSv1.1</literal>] + [<literal>TLSv1.2</literal>]</syntax> +<default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default> +<context>stream</context> +<context>server</context> + +<para> +Enables the specified protocols. +The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters work +only when the OpenSSL library of version 1.0.1 or higher is used. +</para> + +</directive> + + +<directive name="ssl_session_cache"> +<syntax> + <literal>off</literal> | + <literal>none</literal> | + [<literal>builtin</literal>[:<value>size</value>]] + [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax> +<default>none</default> +<context>stream</context> +<context>server</context> + +<para> +Sets the types and sizes of caches that store session parameters. +A cache can be of any of the following types: +<list type="tag"> + +<tag-name><literal>off</literal></tag-name> +<tag-desc> +the use of a session cache is strictly prohibited: +nginx explicitly tells a client that sessions may not be reused. +</tag-desc> + +<tag-name><literal>none</literal></tag-name> +<tag-desc> +the use of a session cache is gently disallowed: +nginx tells a client that sessions may be reused, but does not +actually store session parameters in the cache. +</tag-desc> + +<tag-name><literal>builtin</literal></tag-name> +<tag-desc> +a cache built in OpenSSL; used by one worker process only. +The cache size is specified in sessions. +If size is not given, it is equal to 20480 sessions. +Use of the built-in cache can cause memory fragmentation. +</tag-desc> + +<tag-name><literal>shared</literal></tag-name> +<tag-desc> +a cache shared between all worker processes. +The cache size is specified in bytes; one megabyte can store +about 4000 sessions. +Each shared cache should have an arbitrary name. +A cache with the same name can be used in several +servers. +</tag-desc> + +</list> +</para> + +<para> +Both cache types can be used simultaneously, for example: +<example> +ssl_session_cache builtin:1000 shared:SSL:10m; +</example> +but using only shared cache without the built-in cache should +be more efficient. +</para> + +</directive> + + +<directive name="ssl_session_ticket_key"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Sets a <value>file</value> with the secret key used to encrypt +and decrypt TLS session tickets. +The directive is necessary if the same key has to be shared between +multiple servers. +By default, a randomly generated key is used. +</para> + +<para> +If several keys are specified, only the first key is +used to encrypt TLS session tickets. +This allows configuring key rotation, for example: +<example> +ssl_session_ticket_key current.key; +ssl_session_ticket_key previous.key; +</example> +</para> + +<para> +The <value>file</value> must contain 48 bytes of random data and can +be created using the following command: +<example> +openssl rand 48 > ticket.key +</example> +</para> + +</directive> + + +<directive name="ssl_session_tickets"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>stream</context> +<context>server</context> + +<para> +Enables or disables session resumption through +<link url="http://tools.ietf.org/html/rfc5077">TLS session tickets</link>. +</para> + +</directive> + + +<directive name="ssl_session_timeout"> +<syntax><value>time</value></syntax> +<default>5m</default> +<context>stream</context> +<context>server</context> + +<para> +Specifies a time during which a client may reuse the +session parameters stored in a cache. +</para> + +</directive> + +</section> + +</module>
--- a/xml/en/docs/stream/ngx_stream_upstream_module.xml Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/en/docs/stream/ngx_stream_upstream_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -9,7 +9,7 @@ <module name="Module ngx_stream_upstream_module" link="/en/docs/stream/ngx_stream_upstream_module.html" lang="en" - rev="4"> + rev="5"> <section id="summary"> @@ -34,17 +34,23 @@ <para> <example> +resolver 10.0.0.1; + upstream <emphasis>backend</emphasis> { + zone upstream_backend 64k; + hash $remote_addr consistent; server backend1.example.com:12345 weight=5; server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; - server unix:/tmp/backend3; + server unix:/tmp/backend2; + server backend3.example.com:12345 resolve; } server { listen 12346; proxy_pass <emphasis>backend</emphasis>; + health_check; } </example> </para> @@ -72,7 +78,8 @@ upstream backend { server backend1.example.com:12345 weight=5; server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; - server unix:/tmp/backend3; + server unix:/tmp/backend2; + server backend3.example.com:12345 resolve; server backup1.example.com:12345 backup; } @@ -179,6 +186,34 @@ Default value is zero, meaning there is no limit. </tag-desc> +<tag-name id="resolve"> +<literal>resolve</literal> +</tag-name> +<tag-desc> +monitors changes of the IP addresses +that correspond to a domain name of the server, +and automatically modifies the upstream configuration +without the need of restarting nginx (1.7.10). +<para> +In order for this parameter to work, +the <link doc="ngx_stream_core_module.xml" id="resolver"/> directive +must be specified in the +<link doc="ngx_stream_core_module.xml" id="stream"/> block. +Example: +<example> +stream { + resolver 10.0.0.1; + + upstream u { + zone ...; + ... + server example.com:12345 resolve; + } +} +</example> +</para> +</tag-desc> + <tag-name id="slow_start"> <literal>slow_start</literal>=<value>time</value> </tag-name> @@ -204,6 +239,27 @@ </directive> +<directive name="zone"> +<syntax><value>name</value> <value>size</value></syntax> +<default/> +<context>upstream</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Defines the <value>name</value> and <value>size</value> of the shared +memory zone that keeps the group’s configuration and run-time state that are +shared between worker processes. +Such groups allow changing the group membership +or modifying the settings of a particular server +without the need of restarting nginx. +The configuration is accessible via a special location +handled by +<link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. +</para> + +</directive> + + <directive name="hash"> <syntax><value>key</value> [<literal>consistent</literal>]</syntax> <default/> @@ -253,6 +309,229 @@ </directive> + +<directive name="least_time"> +<syntax><literal>connect</literal> | + <literal>first_byte</literal> | + <literal>last_byte</literal></syntax> +<default/> +<context>upstream</context> +<appeared-in>1.7.11</appeared-in> + +<para> +Specifies that a group should use a load balancing method where a connection +is passed to the server with the least average time and +least number of active connections, taking into account weights of servers. +If there are several such servers, they are tried in turn using a +weighted round-robin balancing method. +</para> + +<para> +If the <literal>connect</literal> parameter is specified, +time to connect to the upstream server is used. +If the <literal>first_byte</literal> parameter is specified, +time to receive the first byte of data is used. +If the <literal>last_byte</literal> is specified, +time to receive the last byte of data is used. +</para> + +</directive> + + +<directive name="health_check"> +<syntax>[<value>parameters</value>]</syntax> +<default/> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Enables periodic health checks of the servers in a +<link id="upstream">group</link>. +</para> + +<para> +The following optional parameters are supported: +<list type="tag"> + +<tag-name id="interval"> +<literal>interval</literal>=<value>time</value> +</tag-name> +<tag-desc> +sets the interval between two consecutive health checks, +by default, 5 seconds; +</tag-desc> + +<tag-name id="fails"> +<literal>fails</literal>=<value>number</value> +</tag-name> +<tag-desc> +sets the number of consecutive failed health checks of a particular server +after which this server will be considered unhealthy, +by default, 1; +</tag-desc> + +<tag-name id="passes"> +<literal>passes</literal>=<value>number</value> +</tag-name> +<tag-desc> +sets the number of consecutive passed health checks of a particular server +after which the server will be considered healthy, +by default, 1; +</tag-desc> + +<tag-name id="hc_match"> +<literal>match</literal>=<value>name</value> +</tag-name> +<tag-desc> +specifies the <literal>match</literal> block configuring the tests that a +successful connection should pass in order for a health check to pass; +by default, only the ability to connect to the server is checked. +</tag-desc> + +</list> +</para> + +<para> +For example, +<example> +server { + proxy_pass backend; + health_check; +} +</example> +will check the ability to connect to each +server in the <literal>backend</literal> group every five seconds. +When a connection to the server cannot be established, +the health check will fail, and the server will +be considered unhealthy. +Client connections are not passed to unhealthy servers. +</para> + +<para> +Health checks can also be configured to test data obtained from the server. +Tests are configured separately using the <link id="match"/> directive +and referenced in the <literal>match</literal> parameter. +</para> + +<para> +The server group must reside in the <link id="zone">shared memory</link>. +</para> + +<para> +If several health checks are defined for the same group of servers, +a single failure of any check will make the corresponding server be +considered unhealthy. +</para> + +</directive> + + +<directive name="health_check_timeout"> +<syntax><value>timeout</value></syntax> +<default>5s</default> +<context>stream</context> +<context>server</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Overrides the +<link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/> +value for health checks. +</para> + +</directive> + + +<directive name="match"> +<syntax block="yes"><value>name</value> </syntax> +<default/> +<context>stream</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Defines the named test set used to verify server responses to health checks. +</para> + +<para> +The following parameters can be configured: +<list type="tag"> + +<tag-name> +<literal>send</literal> <value>string</value>; +</tag-name> +<tag-desc> +sends a <value>string</value> to the server; +</tag-desc> + +<tag-name> +<literal>expect</literal> <literal>~</literal> <value>regexp</value>; +</tag-name> +<tag-desc> +a regular expression that the data obtained from the server should match. +The regular expression is specified with the preceding +“<literal>~*</literal>” modifier (for case-insensitive matching), or the +“<literal>~</literal>” modifier (for case-sensitive matching). +</tag-desc> + +</list> +</para> + +<para> +Health check is passed if: +<list type="bullet"> +<listitem> +the connection was successfully established; +</listitem> + +<listitem> +the <value>string</value> from the <literal>send</literal> parameter, +if specified, was sent; +</listitem> + +<listitem> +the data obtained from the server matched the regular expression +from the <literal>expect</literal> parameter, if specified; +</listitem> + +<listitem> +the time elapsed does not exceed the value specified +in the <link id="health_check_timeout"/> directive. +</listitem> + +</list> +</para> + +<para> +Example: +<example> +upstream backend { + zone upstream_backend 10m; + server 127.0.0.1:12345; +} + +match http { + send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n"; + expect ~ "200 OK"; +} + +server { + listen 12346; + proxy_pass backend; + health_check match=http; +} +</example> +</para> + +<para> +<note> +Only the first +<link doc="ngx_stream_proxy_module.xml" id="proxy_upstream_buffer"/> +bytes of data obtained from the server are examined. +</note> +</para> + +</directive> + </section> </module>
--- a/xml/ru/GNUmakefile Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/ru/GNUmakefile Thu Apr 09 19:18:54 2015 +0300 @@ -70,6 +70,7 @@ http/ngx_http_stub_status_module \ http/ngx_http_sub_module \ http/ngx_http_upstream_module \ + http/ngx_http_upstream_conf_module \ http/ngx_http_userid_module \ http/ngx_http_uwsgi_module \ http/ngx_http_xslt_module \
--- a/xml/ru/docs/http/ngx_http_status_module.xml Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/ru/docs/http/ngx_http_status_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -9,7 +9,7 @@ <module name="Модуль ngx_http_status_module" link="/ru/docs/http/ngx_http_status_module.html" lang="ru" - rev="4"> + rev="5"> <section id="summary"> @@ -160,7 +160,7 @@ <tag-name id="version"><literal>version</literal></tag-name> <tag-desc> Версия предоставляемого набора данных. -Текущей является версия 4. +Текущей является версия 5. </tag-desc> <tag-name><literal>nginx_version</literal></tag-name> @@ -173,6 +173,13 @@ Адрес сервера, принявшего запрос получения информации о состоянии. </tag-desc> +<tag-name id="generation"><literal>generation</literal></tag-name> +<tag-desc> +Суммарное число +<link doc="../control.xml" id="reconfiguration">перезагрузок</link> +конфигурации. +</tag-desc> + <tag-name id="load_timestamp"><literal>load_timestamp</literal></tag-name> <tag-desc> Время последней перезагрузки конфигурации, в миллисекундах с начала эпохи. @@ -183,6 +190,19 @@ Текущее время в миллисекундах с начала эпохи. </tag-desc> +<tag-name id="processes"><literal>processes</literal></tag-name> +<tag-desc> +<list type="tag"> + +<tag-name id="respawned"><literal>respawned</literal></tag-name> +<tag-desc> +Суммарное число перезапусков аварийно завершённых +дочерних процессов. +</tag-desc> + +</list> +</tag-desc> + <tag-name><literal>connections</literal></tag-name> <tag-desc> <list type="tag"> @@ -331,11 +351,13 @@ Текущее число активных соединений. </tag-desc> +<!-- <tag-name><literal>keepalive</literal></tag-name> <tag-desc> Текущее число бездействующих <link doc="ngx_http_upstream_module.xml" id="keepalive"/>-соединений. </tag-desc> +--> <tag-name id="max_conns"><literal>max_conns</literal></tag-name> <tag-desc> @@ -451,6 +473,24 @@ когда сервер в последний раз был выбран для обработки запроса (1.7.5). </tag-desc> +<tag-name id="header_time"><literal>header_time</literal></tag-name> +<tag-desc> +Среднее время получения +<link doc="ngx_http_upstream_module.xml" id="var_upstream_header_time">заголовка +ответа</link> от сервера (1.7.10). +Поле доступно при использовании метода балансировки +<link doc="ngx_http_upstream_module.xml" id="least_time"/>. +</tag-desc> + +<tag-name id="response_time"><literal>response_time</literal></tag-name> +<tag-desc> +Среднее время получения +<link doc="ngx_http_upstream_module.xml" id="var_upstream_response_time">всего +ответа</link> от сервера (1.7.10). +Поле доступно при использовании метода балансировки +<link doc="ngx_http_upstream_module.xml" id="least_time"/>. +</tag-desc> + </list> </tag-desc> @@ -551,6 +591,28 @@ <list type="bullet"> <listitem> +Поле <literal>keepalive</literal> сервера группы +было удалено в <link id="version">версии</link> 5. +</listitem> + +<listitem> +Поле <link id="generation"/> +было добавлено в <link id="version">версии</link> 5. +</listitem> + +<listitem> +Поле <link id="respawned"/> в +<link id="processes"/> +было добавлено в <link id="version">версии</link> 5. +</listitem> + +<listitem> +Поля <link id="header_time"/> и <link id="response_time"/> в +<link id="upstreams"/> +были добавлены в <link id="version">версии</link> 5. +</listitem> + +<listitem> Поле <link id="selected"/> в <link id="upstreams"/> было добавлено в <link id="version">версии</link> 4.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_upstream_conf_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -0,0 +1,333 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Модуль ngx_http_upstream_conf_module" + link="/ru/docs/http/ngx_http_upstream_conf_module.html" + lang="ru" + rev="1"> + +<section id="summary"> + +<para> +Модуль <literal>ngx_http_upstream_conf_module</literal> +позволяет оперативно настраивать группы серверов +при помощи простого HTTP-интерфейса без необходимости перезапуска nginx. +Группа серверов +<link doc="ngx_http_upstream_module.xml" id="zone">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="zone">stream</link> +должна находиться в разделяемой памяти. +</para> + +</section> + + +<section id="example" name="Пример конфигурации"> + +<para> +<example> +upstream backend { + zone upstream_backend 64k; + + ... +} + +server { + location /upstream_conf { + <emphasis>upstream_conf</emphasis>; + allow 127.0.0.1; + deny all; + } +} +</example> +</para> + +</section> + + +<section id="directives" name="Директивы"> + +<directive name="upstream_conf"> +<syntax/> +<default/> +<context>location</context> + +<para> +Активирует HTTP-интерфейс для настройки групп серверов в содержащем location. +Доступ в location следует +<link doc="ngx_http_core_module.xml" id="satisfy">ограничить</link>. +</para> + +<para> +С помощью команд настройки можно: +<list type="bullet"> + +<listitem>просматривать конфигурацию группы;</listitem> + +<listitem> +просматривать или изменять конфигурацию, а также +удалять серверы; +</listitem> + +<listitem>добавлять новые серверы.</listitem> + +</list> +<note> +Поскольку адреса в группе не обязаны быть уникальными, +обращение к отдельным серверам в группе осуществляется по их идентификаторам. +Идентификаторы назначаются автоматически и показываются при добавлении сервера +или просмотре конфигурации группы. +</note> +</para> + +<para> +Команда настройки состоит из параметров, передаваемых в аргументах запроса, +например: +<example> +http://127.0.0.1/upstream_conf?upstream=backend +</example> +</para> + +<para> +Поддерживаются следующие параметры: + +<list type="tag" compact="no"> + +<tag-name> +<literal>stream=</literal></tag-name> +<tag-desc> +Выбирает группу серверов +<link doc="../stream/ngx_stream_upstream_module.xml">stream</link>. +Если параметр не задан, будет выбрана группа серверов +<link doc="ngx_http_upstream_module.xml">http</link>. +</tag-desc> + +<tag-name> +<literal>upstream=</literal><value>имя</value></tag-name> +<tag-desc> +Выбирает группу серверов для работы. +Параметр является обязательным. +</tag-desc> + +<tag-name> +<literal>id=</literal><value>число</value></tag-name> +<tag-desc> +Выбирает сервер для просмотра, изменения или удаления. +</tag-desc> + +<tag-name> +<literal>remove=</literal></tag-name> +<tag-desc> +Удаляет сервер из группы. +</tag-desc> + +<tag-name> +<literal>add=</literal></tag-name> +<tag-desc> +Добавляет новый сервер в группу. +</tag-desc> + +<tag-name> +<literal>backup=</literal></tag-name> +<tag-desc> +Необходим для добавления запасного сервера. +<note> +До версии 1.7.2 параметр <literal>backup=</literal> требовался +также для просмотра, изменения или удаления существующих запасных серверов. +</note> +</tag-desc> + +<tag-name> +<literal>server=</literal><value>адрес</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>адрес</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="server">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link>. +<para> +При добавлении сервер можно задать в виде доменного имени. +В этом случае любые изменения IP-адресов, соответствующих доменному имени +сервера, отслеживаются и автоматически применяются к конфигурации группы +без необходимости перезапуска nginx (1.7.2). +Для этого в блоке +<link doc="ngx_http_core_module.xml" id="resolver">http</link> +или +<link doc="../stream/ngx_stream_core_module.xml" id="resolver">stream</link> +должна быть задана директива “<literal>resolver</literal>”. +См. также параметр “<literal>resolve</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="resolve">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="resolve">stream</link>. +</para> +</tag-desc> + +<tag-name> +<literal>weight=</literal><value>число</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>weight</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="weight">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="weight">stream</link>. +</tag-desc> + +<tag-name> +<literal>max_conns=</literal><value>число</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>max_conns</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="max_conns">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="max_conns">stream</link>. +</tag-desc> + +<tag-name> +<literal>max_fails=</literal><value>число</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>max_fails</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="max_fails">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="max_fails">stream</link>. +</tag-desc> + +<tag-name> +<literal>fail_timeout=</literal><value>время</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>fail_timeout</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="fail_timeout">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="fail_timeout">stream</link>. +</tag-desc> + +<tag-name> +<literal>slow_start=</literal><value>время</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>slow_start</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="slow_start">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="slow_start">stream</link>. +</tag-desc> + +<tag-name> +<literal>down=</literal></tag-name> +<tag-desc> +То же, что и параметр “<literal>down</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="down">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link>. +</tag-desc> + +<tag-name id="drain"><literal>drain=</literal></tag-name> +<tag-desc> +Переводит сервер группы серверов +<link doc="ngx_http_upstream_module.xml">http</link> +в режим “draining” (1.7.5). +В этом режиме на сервер будут проксироваться только +<link doc="ngx_http_upstream_module.xml" id="sticky">привязанные</link> +к нему запросы. +</tag-desc> + +<tag-name> +<literal>up=</literal></tag-name> +<tag-desc> +Параметр, обратный по значению параметру “<literal>down</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="down">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="down">stream</link>. +</tag-desc> + +<tag-name> +<literal>route=</literal><value>строка</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>route</literal>” сервера группы +<link doc="ngx_http_upstream_module.xml" id="route">http</link>. +</tag-desc> + +</list> + +Первые три параметра выбирают объект. +Объектом может быть либо группа серверов http или stream, +либо отдельный сервер. +Если остальные параметры не указаны, то показывается конфигурация выбранной +группы или сервера. +</para> + +<para> +Например, команда для просмотра конфигурации всей группы +выглядит следующим образом: +<example> +http://127.0.0.1/upstream_conf?upstream=backend +</example> + +Для просмотра конфигурации отдельного сервера следует указать его идентификатор: +<example> +http://127.0.0.1/upstream_conf?upstream=backend&id=42 +</example> +</para> + +<para> +Для добавления нового сервера в группу +следует указать его адрес в параметре “<literal>server=</literal>”. +Если остальные параметры не указаны, то при добавлении сервера +их значения будут установлены по умолчанию (см. директиву +“<literal>server</literal>” для +<link doc="ngx_http_upstream_module.xml" id="server">http</link> +или +<link doc="../stream/ngx_stream_upstream_module.xml" id="server">stream</link>). +</para> + +<para> +Например, команда для добавления нового основного сервера в группу +выглядит следующим образом: +<example> +http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080 +</example> + +Добавление нового запасного сервера происходит следующим образом: +<example> +http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080 +</example> + +Добавление нового основного сервера с нестандартными +значениями параметров и с пометкой его как постоянно недоступного +(“<literal>down</literal>”) происходит следующим образом: +<example> +http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down= +</example> + +Для удаления сервера следует указать его идентификатор: +<example> +http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42 +</example> + +Пометка существующего сервера как постоянно недоступного +(“<literal>down</literal>”) происходит следующим образом: +<example> +http://127.0.0.1/upstream_conf?upstream=backend&id=42&down= +</example> + +Изменение адреса существующего сервера происходит следующим образом: +<example> +http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123 +</example> + +Изменение других параметров существующего сервера происходит следующим образом: +<example> +http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4 +</example> + +Вышеприведённые примеры актуальны для группы серверов +<link doc="ngx_http_upstream_module.xml">http</link>. +Аналогичные примеры для группы серверов +<link doc="../stream/ngx_stream_upstream_module.xml">stream</link> +требуют указания параметра “<literal>stream=</literal>”. +</para> + +</directive> + +</section> + +</module>
--- a/xml/ru/docs/http/ngx_http_upstream_module.xml Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/ru/docs/http/ngx_http_upstream_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_upstream_module" link="/ru/docs/http/ngx_http_upstream_module.html" lang="ru" - rev="35"> + rev="36"> <section id="summary"> @@ -54,12 +54,15 @@ доступна как часть <commercial_version>коммерческой подписки</commercial_version>: <example> +resolver 10.0.0.1; + upstream <emphasis>dynamic</emphasis> { zone upstream_dynamic 64k; server backend1.example.com weight=5; server backend2.example.com:8080 fail_timeout=5s slow_start=30s; server 192.0.2.1 max_fails=3; + server backend3.example.com resolve; server backup1.example.com:8080 backup; server backup2.example.com:8080 backup; @@ -70,12 +73,6 @@ proxy_pass http://<emphasis>dynamic</emphasis>; health_check; } - - location /upstream_conf { - upstream_conf; - allow 127.0.0.1; - deny all; - } } </example> </para> @@ -299,7 +296,8 @@ или настроек отдельных серверов нет необходимости перезапускать nginx. Конфигурация доступна через специальный location, -в котором указана директива <link id="upstream_conf"/>. +в котором указана директива +<link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. </para> <para> @@ -533,6 +531,38 @@ </directive> +<directive name="least_time"> +<syntax><literal>header</literal> | <literal>last_byte</literal></syntax> +<default/> +<context>upstream</context> +<appeared-in>1.7.10</appeared-in> + +<para> +Задаёт для группы метод балансировки нагрузки, при котором запрос +передаётся серверу с наименьшими средним временем ответа и +числом активных соединений с учётом весов серверов. +Если подходит сразу несколько серверов, то они выбираются циклически +(в режиме round-robin) с учётом их весов. +</para> + +<para> +Если указан параметр <literal>header</literal>, +то учитывается время получения +<link id="var_upstream_header_time">заголовка ответа</link>. +Если указан параметр <literal>last_byte</literal>, то учитывается +время получения <link id="var_upstream_response_time">всего ответа</link>. +</para> + +<para> +<note> +Эта директива доступна как часть +<commercial_version>коммерческой подписки</commercial_version>. +</note> +</para> + +</directive> + + <directive name="health_check"> <syntax>[<value>параметры</value>]</syntax> <default/> @@ -842,6 +872,8 @@ <literal>cookie</literal> <value>имя</value> [<literal>expires=</literal><value>время</value>] [<literal>domain=</literal><value>домен</value>] + [<literal>httponly</literal>] + [<literal>secure</literal>] [<literal>path=</literal><value>путь</value>]</syntax> <syntax> <literal>route</literal> <value>переменная</value> ...</syntax> @@ -889,22 +921,32 @@ Дополнительные параметры могут быть следующими: <list type="tag"> -<tag-name><literal>expires</literal></tag-name> +<tag-name><literal>expires=</literal><value>время</value></tag-name> <tag-desc> -Задаёт время, в течение которого браузеру необходимо хранить куку. +Задаёт <value>время</value>, в течение которого браузеру необходимо хранить куку. Специальное значение <literal>max</literal> устанавливает срок хранения куки до 31 декабря 2037 года 23:55:55 GMT. Если параметр не указан, то время действия куки ограничивается сессией браузера. </tag-desc> -<tag-name><literal>domain</literal></tag-name> +<tag-name><literal>domain=</literal><value>домен</value></tag-name> <tag-desc> -Задаёт домен, для которого устанавливается кука. +Задаёт <value>домен</value>, для которого устанавливается кука. </tag-desc> -<tag-name><literal>path</literal></tag-name> +<tag-name><literal>httponly</literal></tag-name> +<tag-desc> +Добавляет атрибут <literal>HttpOnly</literal> к куке (1.7.11). +</tag-desc> + +<tag-name><literal>secure</literal></tag-name> <tag-desc> -Задаёт путь, для которого устанавливается кука. +Добавляет атрибут <literal>Secure</literal> к куке (1.7.11). +</tag-desc> + +<tag-name><literal>path=</literal><value>путь</value></tag-name> +<tag-desc> +Задаёт <value>путь</value>, для которого устанавливается кука. </tag-desc> </list> @@ -1038,253 +1080,6 @@ </directive> - -<directive name="upstream_conf"> -<syntax/> -<default/> -<context>location</context> - -<para> -Активирует HTTP-интерфейс для настройки групп серверов в содержащем location. -Доступ в location следует -<link doc="ngx_http_core_module.xml" id="satisfy">ограничить</link>. -</para> - -<para> -С помощью команд настройки можно: -<list type="bullet"> - -<listitem>просматривать конфигурацию группы;</listitem> - -<listitem> -просматривать или изменять конфигурацию, а также -удалять серверы; -</listitem> - -<listitem>добавлять новые серверы.</listitem> - -</list> -<note> -Поскольку адреса в группе не обязаны быть уникальными, -обращение к отдельным серверам в группе осуществляется по их идентификаторам. -Идентификаторы назначаются автоматически и показываются при добавлении сервера -или просмотре конфигурации группы. -</note> -</para> - -<para> -Команда настройки состоит из параметров, передаваемых в аргументах запроса, -например: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic -</example> -</para> - -<para> -Поддерживаются следующие параметры: - -<list type="tag" compact="no"> - -<tag-name> -<literal>upstream=</literal><value>имя</value></tag-name> -<tag-desc> -Выбирает группу серверов для работы. -Параметр является обязательным. -</tag-desc> - -<tag-name> -<literal>id=</literal><value>число</value></tag-name> -<tag-desc> -Выбирает сервер для просмотра, изменения или удаления. -</tag-desc> - -<tag-name> -<literal>remove=</literal></tag-name> -<tag-desc> -Удаляет сервер из группы. -</tag-desc> - -<tag-name> -<literal>add=</literal></tag-name> -<tag-desc> -Добавляет новый сервер в группу. -</tag-desc> - -<tag-name> -<literal>backup=</literal></tag-name> -<tag-desc> -Необходим для добавления запасного сервера. -<note> -До версии 1.7.2 параметр <literal>backup=</literal> требовался -также для просмотра, изменения или удаления существующих запасных серверов. -</note> -</tag-desc> - -<tag-name> -<literal>server=</literal><value>адрес</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>адрес</literal>” -директивы <link id="server"/>. -<para> -При добавлении сервер можно задать в виде доменного имени. -В этом случае любые изменения IP-адресов, соответствующих доменному имени -сервера, отслеживаются и автоматически применяются к конфигурации группы -без необходимости перезапуска nginx (1.7.2). -Для этого в блоке <link doc="ngx_http_core_module.xml" id="http"/> должна -быть задана директива <link doc="ngx_http_core_module.xml" id="resolver"/>. -См. также параметр -<link id="resolve"/> директивы <link id="server"/>. -</para> -</tag-desc> - -<tag-name> -<literal>weight=</literal><value>число</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>weight</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>max_conns=</literal><value>число</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>max_conns</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>max_fails=</literal><value>число</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>max_fails</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>fail_timeout=</literal><value>время</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>fail_timeout</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>slow_start=</literal><value>время</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>slow_start</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>down=</literal></tag-name> -<tag-desc> -То же, что и параметр “<literal>down</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name id="drain"><literal>drain=</literal></tag-name> - -<tag-desc> -Переводит сервер группы в режим “draining” (1.7.5). -В этом режиме на сервер будут проксироваться только -<link id="sticky">привязанные</link> к нему запросы. -</tag-desc> - -<tag-name> -<literal>up=</literal></tag-name> -<tag-desc> -Параметр, обратный по значению параметру “<literal>down</literal>” -директивы <link id="server"/>. -</tag-desc> - -<tag-name> -<literal>route=</literal><value>строка</value></tag-name> -<tag-desc> -То же, что и параметр “<literal>route</literal>” -директивы <link id="server"/>. -</tag-desc> - -</list> - -Первые два параметра выбирают объект. -Объектом может быть либо группа серверов, либо отдельный сервер. -Если остальные параметры не указаны, то показывается конфигурация выбранной -группы или сервера. -</para> - -<para> -Например, команда для просмотра конфигурации всей группы -выглядит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic -</example> - -Для просмотра конфигурации отдельного сервера следует указать его идентификатор: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42 -</example> - -</para> - -<para> -Для добавления нового сервера в группу -следует указать его адрес в параметре “<literal>server=</literal>”. -Если остальные параметры не указаны, то при добавлении сервера -их значения будут установлены по умолчанию (см. директиву <link id="server"/>). -</para> - -<para> -Например, команда для добавления нового основного сервера в группу -выглядит следующим образом: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080 -</example> - -Добавление нового запасного сервера происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&backup=&server=127.0.0.1:8080 -</example> - -Добавление нового основного сервера с нестандартными -значениями параметров и с пометкой его как постоянно недоступного -(“<literal>down</literal>”) происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080&weight=2&down= -</example> -</para> - -<para> -Для удаления сервера следует указать его идентификатор: -<example> -http://127.0.0.1/upstream_conf?remove=&upstream=dynamic&id=42 -</example> -</para> - -<para> -Пометка существующего сервера как постоянно недоступного -(“<literal>down</literal>”) происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&down= -</example> - -Изменение адреса существующего сервера происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&server=192.0.2.3:8123 -</example> - -Изменение других параметров существующего сервера происходит следующим образом: -<example> -http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&max_fails=3&weight=4 -</example> - -</para> - -<para> -<note> -Эта директива доступна как часть -<commercial_version>коммерческой подписки</commercial_version>. -</note> -</para> - -</directive> - </section>
--- a/xml/ru/docs/index.xml Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/ru/docs/index.xml Thu Apr 09 19:18:54 2015 +0300 @@ -8,7 +8,7 @@ <article name="nginx: документация" link="/ru/docs/" lang="ru" - rev="17" + rev="18" toc="no"> @@ -409,6 +409,11 @@ </listitem> <listitem> +<link doc="http/ngx_http_upstream_conf_module.xml"> +ngx_http_upstream_conf_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_userid_module.xml"> ngx_http_userid_module</link> </listitem>
--- a/xml/ru/docs/ngx_core_module.xml Wed Apr 08 13:56:52 2015 +0300 +++ b/xml/ru/docs/ngx_core_module.xml Thu Apr 09 19:18:54 2015 +0300 @@ -10,7 +10,7 @@ <module name="Основная функциональность" link="/ru/docs/ngx_core_module.html" lang="ru" - rev="12"> + rev="13"> <section id="example" name="Пример конфигурации"> @@ -158,6 +158,7 @@ <default>logs/error.log error</default> <context>main</context> <context>http</context> +<context>stream</context> <context>server</context> <context>location</context> @@ -194,6 +195,12 @@ nginx с <literal>--with-debug</literal>, см. “<link doc="debugging_log.xml"/>”. </note> + +<note> +Директива может быть указана на +уровне <literal>stream</literal> +начиная с версии 1.7.11. +</note> </para> </directive>