Mercurial > hg > nginx-site
diff xml/en/docs/http/ngx_http_upstream_conf_module.xml @ 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 | xml/en/docs/http/ngx_http_upstream_module.xml@410e0683b6b4 |
| children | d3c1a4e8c1fe |
line wrap: on
line diff
copy from xml/en/docs/http/ngx_http_upstream_module.xml copy to xml/en/docs/http/ngx_http_upstream_conf_module.xml --- a/xml/en/docs/http/ngx_http_upstream_module.xml +++ b/xml/en/docs/http/ngx_http_upstream_conf_module.xml @@ -1,27 +1,27 @@ <?xml version="1.0"?> <!-- - Copyright (C) Igor Sysoev Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> -<module name="Module ngx_http_upstream_module" - link="/en/docs/http/ngx_http_upstream_module.html" +<module name="Module ngx_http_upstream_conf_module" + link="/en/docs/http/ngx_http_upstream_conf_module.html" lang="en" - rev="35"> + rev="1"> <section id="summary"> <para> -The <literal>ngx_http_upstream_module</literal> module -is used to define groups of servers that can be referenced -by the <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>, -<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>, -<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_pass"/>, -<link doc="ngx_http_scgi_module.xml" id="scgi_pass"/>, and -<link doc="ngx_http_memcached_module.xml" id="memcached_pass"/> directives. +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> @@ -31,47 +31,15 @@ by the <link doc="ngx_http_proxy_module. <para> <example> -upstream <emphasis>backend</emphasis> { - server backend1.example.com weight=5; - server backend2.example.com:8080; - server unix:/tmp/backend3; +upstream backend { + zone upstream_backend 64k; - server backup1.example.com:8080 backup; - server backup2.example.com:8080 backup; + ... } server { - location / { - proxy_pass http://<emphasis>backend</emphasis>; - } -} -</example> -</para> - -<para> -Dynamically configurable group, -available as part of our -<commercial_version>commercial subscription</commercial_version>: -<example> -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 backup1.example.com:8080 backup; - server backup2.example.com:8080 backup; -} - -server { - location / { - proxy_pass http://<emphasis>dynamic</emphasis>; - health_check; - } - location /upstream_conf { - upstream_conf; + <emphasis>upstream_conf</emphasis>; allow 127.0.0.1; deny all; } @@ -84,955 +52,6 @@ server { <section id="directives" name="Directives"> -<directive name="upstream"> -<syntax block="yes"><value>name</value></syntax> -<default/> -<context>http</context> - -<para> -Defines a group of servers. -Servers can listen on different ports. -In addition, servers listening on TCP and UNIX-domain sockets -can be mixed. -</para> - -<para> -Example: -<example> -upstream backend { - server backend1.example.com weight=5; - server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; - server unix:/tmp/backend3; - - server backup1.example.com backup; -} -</example> -</para> - -<para> -By default, requests are distributed between the servers using a -weighted round-robin balancing method. -In the above example, each 7 requests will be distributed as follows: -5 requests go to <literal>backend1.example.com</literal> -and one request to each of the second and third servers. -If an error occurs during communication with a server, the request will -be passed to the next server, and so on until all of the functioning -servers will be tried. -If a successful response could not be obtained from any of the servers, -the client will receive the result of the communication with the last server. -</para> - -</directive> - - -<directive name="server"> -<syntax><value>address</value> [<value>parameters</value>]</syntax> -<default/> -<context>upstream</context> - -<para> -Defines the <value>address</value> and other <value>parameters</value> -of a server. -The address can be specified as a domain name or IP address, -with an optional port, or as a UNIX-domain socket path -specified after the “<literal>unix:</literal>” prefix. -If a port is not specified, the port 80 is used. -A domain name that resolves to several IP addresses defines -multiple servers at once. -</para> - -<para> -The following parameters can be defined: -<list type="tag"> - -<tag-name id="weight"> -<literal>weight</literal>=<value>number</value> -</tag-name> -<tag-desc> -sets the weight of the server, by default, 1. -</tag-desc> - -<tag-name id="max_fails"> -<literal>max_fails</literal>=<value>number</value> -</tag-name> -<tag-desc> -sets the number of unsuccessful attempts to communicate with the server -that should happen in the duration set by the <literal>fail_timeout</literal> -parameter to consider the server unavailable for a duration also set by the -<literal>fail_timeout</literal> parameter. -By default, the number of unsuccessful attempts is set to 1. -The zero value disables the accounting of attempts. -What is considered an unsuccessful attempt is defined by the -<link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>, -<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>, -<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_next_upstream"/>, -<link doc="ngx_http_scgi_module.xml" id="scgi_next_upstream"/>, and -<link doc="ngx_http_memcached_module.xml" id="memcached_next_upstream"/> -directives. -</tag-desc> - -<tag-name id="fail_timeout"> -<literal>fail_timeout</literal>=<value>time</value> -</tag-name> -<tag-desc> -sets -<list type="bullet"> - -<listitem> -the time during which the specified number of unsuccessful attempts to -communicate with the server should happen to consider the server unavailable; -</listitem> - -<listitem> -and the period of time the server will be considered unavailable. -</listitem> - -</list> -By default, the parameter is set to 10 seconds. -</tag-desc> - -<tag-name id="backup"> -<literal>backup</literal> -</tag-name> -<tag-desc> -marks the server as a backup server. -It will be passed requests when the primary servers are unavailable. -</tag-desc> - -<tag-name id="down"> -<literal>down</literal> -</tag-name> -<tag-desc> -marks the server as permanently unavailable. -</tag-desc> - -</list> -</para> - -<para> -Additionally, -the following parameters are available as part of our -<commercial_version>commercial subscription</commercial_version>: -<list type="tag"> - -<tag-name id="max_conns"> -<literal>max_conns</literal>=<value>number</value> -</tag-name> -<tag-desc> -limits the maximum <value>number</value> of simultaneous connections to the -proxied server (1.5.9). -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.5.12). -<para> -In order for this parameter to work, -the <link doc="ngx_http_core_module.xml" id="resolver"/> directive -must be specified in the -<link doc="ngx_http_core_module.xml" id="http"/> block. -Example: -<example> -http { - resolver 10.0.0.1; - - upstream u { - zone ...; - ... - server example.com resolve; - } -} -</example> -</para> -</tag-desc> - -<tag-name id="route"> -<literal>route</literal>=<value>string</value> -</tag-name> -<tag-desc> -sets the server route name. -</tag-desc> - -<tag-name id="slow_start"> -<literal>slow_start</literal>=<value>time</value> -</tag-name> -<tag-desc> -sets the <value>time</value> during which the server will recover its weight -from zero to a nominal value, when unhealthy server becomes -<link id="health_check">healthy</link>, -or when the server becomes available after a period of time -it was considered <link id="fail_timeout">unavailable</link>. -Default value is zero, i.e. slow start is disabled. -</tag-desc> - -</list> -</para> - -<para> -<note> -If there is only a single server in a group, <literal>max_fails</literal>, -<literal>fail_timeout</literal> and <literal>slow_start</literal> parameters -are ignored, and such a server will never be considered unavailable. -</note> -</para> - -</directive> - - -<directive name="zone"> -<syntax><value>name</value> <value>size</value></syntax> -<default/> -<context>upstream</context> - -<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 id="upstream_conf"/>. -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="hash"> -<syntax><value>key</value> [<literal>consistent</literal>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.7.2</appeared-in> - -<para> -Specifies a load balancing method for a server group -where the client-server mapping is based on the hashed <value>key</value> value. -The <value>key</value> can contain text, variables, and their combinations. -Note that adding or removing a server from the group -may result in remapping most of the keys to different servers. -The method is compatible with the -<link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached">Cache::Memcached</link> -Perl library. -</para> - -<para> -If the <literal>consistent</literal> parameter is specified -the <link url="http://www.last.fm/user/RJ/journal/2007/04/10/392555/">ketama</link> -consistent hashing method will be used instead. -The method ensures that only a few keys -will be remapped to different servers -when a server is added to or removed from the group. -This helps to achieve a higher cache hit ratio for caching servers. -The method is compatible with the -<link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached%3A%3AFast">Cache::Memcached::Fast</link> -Perl library with the <value>ketama_points</value> parameter set to 160. -</para> - -</directive> - - -<directive name="ip_hash"> -<syntax/> -<default/> -<context>upstream</context> - -<para> -Specifies that a group should use a load balancing method where requests -are distributed between servers based on client IP addresses. -The first three octets of the client IPv4 address, or the entire IPv6 address, -are used as a hashing key. -The method ensures that requests from the same client will always be -passed to the same server except when this server is unavailable. -In the latter case client requests will be passed to another server. -Most probably, it will always be the same server as well. -<note> -IPv6 addresses are supported starting from versions 1.3.2 and 1.2.2. -</note> -</para> - -<para> -If one of the servers needs to be temporarily removed, it should -be marked with the <literal>down</literal> parameter in -order to preserve the current hashing of client IP addresses. -</para> - -<para> -Example: -<example> -upstream backend { - ip_hash; - - server backend1.example.com; - server backend2.example.com; - server backend3.example.com <emphasis>down</emphasis>; - server backend4.example.com; -} -</example> -</para> - -<para> -<note> -Until versions 1.3.1 and 1.2.2, it was not possible to specify a weight for -servers using the <literal>ip_hash</literal> load balancing method. -</note> -</para> - -</directive> - - -<directive name="keepalive"> -<syntax><value>connections</value></syntax> -<default/> -<context>upstream</context> -<appeared-in>1.1.4</appeared-in> - -<para> -Activates the cache for connections to upstream servers. -</para> - -<para> -The <value>connections</value> parameter sets the maximum number of -idle keepalive connections to upstream servers that are preserved in -the cache of each worker process. -When this number is exceeded, the least recently used connections -are closed. -<note> -It should be particularly noted that the <literal>keepalive</literal> directive -does not limit the total number of connections to upstream servers -that an nginx worker process can open. -The <value>connections</value> parameter should be set to a number small enough -to let upstream servers process new incoming connections as well. -</note> -</para> - -<para> -Example configuration of memcached upstream with keepalive connections: -<example> -upstream memcached_backend { - server 127.0.0.1:11211; - server 10.0.0.2:11211; - - keepalive 32; -} - -server { - ... - - location /memcached/ { - set $memcached_key $uri; - memcached_pass memcached_backend; - } - -} -</example> -</para> - -<para> -For HTTP, the <link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/> -directive should be set to “<literal>1.1</literal>” -and the <header>Connection</header> header field should be cleared: -<example> -upstream http_backend { - server 127.0.0.1:8080; - - keepalive 16; -} - -server { - ... - - location /http/ { - proxy_pass http://http_backend; - proxy_http_version 1.1; - proxy_set_header Connection ""; - ... - } -} -</example> -</para> - -<para> -<note> -Alternatively, HTTP/1.0 persistent connections can be used by passing the -<header>Connection: Keep-Alive</header> header field to an upstream server, -though this method is not recommended. -</note> -</para> - -<para> -For FastCGI servers, it is required to set -<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_keep_conn"/> -for keepalive connections to work: -<example> -upstream fastcgi_backend { - server 127.0.0.1:9000; - - keepalive 8; -} - -server { - ... - - location /fastcgi/ { - fastcgi_pass fastcgi_backend; - fastcgi_keep_conn on; - ... - } -} -</example> -</para> - -<para> -<note> -When using load balancer methods other than the default -round-robin method, it is necessary to activate them before -the <literal>keepalive</literal> directive. -</note> - -<note> -SCGI and uwsgi protocols do not have a notion of keepalive connections. -</note> -</para> - -</directive> - - -<directive name="least_conn"> -<syntax/> -<default/> -<context>upstream</context> -<appeared-in>1.3.1</appeared-in> -<appeared-in>1.2.2</appeared-in> - -<para> -Specifies that a group should use a load balancing method where a request -is passed to the server with the 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> - -</directive> - - -<directive name="health_check"> -<syntax>[<value>parameters</value>]</syntax> -<default/> -<context>location</context> - -<para> -Enables periodic health checks of the servers in a -<link id="upstream">group</link> referenced in the surrounding location. -</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="uri"> -<literal>uri</literal>=<value>uri</value> -</tag-name> -<tag-desc> -defines the URI used in health check requests, -by default, “<literal>/</literal>”; -</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 -response should pass in order for a health check to pass; -by default, the response should have status code 2xx or 3xx. -</tag-desc> - -</list> -</para> - -<para> -For example, -<example> -location / { - proxy_pass http://backend; - health_check; -} -</example> -will send “<literal>/</literal>” requests to each -server in the <literal>backend</literal> group every five seconds. -If any communication error or timeout occurs, or a -proxied server responds with the status code other than -2xx or 3xx, the health check will fail, and the server will -be considered unhealthy. -Client requests are not passed to unhealthy servers. -</para> - -<para> -Health checks can be configured to test the status code of a response, -presence of certain header fields and their values, -and the body contents. -Tests are configured separately using the <link id="match"/> directive -and referenced in the <literal>match</literal> parameter. -For example: -<example> -http { - server { - ... - location / { - proxy_pass http://backend; - health_check match=welcome; - } - } - - match welcome { - status 200; - header Content-Type = text/html; - body ~ "Welcome to nginx!"; - } -} -</example> -This configuration tells that for a health check to pass, the response to a -health check request should succeed, -have status 200, content type “<literal>text/html</literal>”, -and contain “<literal>Welcome to nginx!</literal>” in the body. -</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> - -<para> -<note> -Please note that most of the variables will have empty values -when used with health checks. -</note> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="match"> -<syntax block="yes"><value>name</value></syntax> -<default/> -<context>http</context> - -<para> -Defines the named test set used to verify responses to health check requests. -</para> - -<para> -The following items can be tested in a response: -<list type="tag"> - -<tag-name><literal>status 200;</literal></tag-name> -<tag-desc>status is 200</tag-desc> - -<tag-name><literal>status ! 500;</literal></tag-name> -<tag-desc>status is not 500</tag-desc> - -<tag-name><literal>status 200 204;</literal></tag-name> -<tag-desc>status is 200 or 204</tag-desc> - -<tag-name><literal>status ! 301 302;</literal></tag-name> -<tag-desc>status is neither 301 nor 302</tag-desc> - -<tag-name><literal>status 200-399;</literal></tag-name> -<tag-desc>status is in the range from 200 to 399</tag-desc> - -<tag-name><literal>status ! 400-599;</literal></tag-name> -<tag-desc>status is not in the range from 400 to 599</tag-desc> - -<tag-name><literal>status 301-303 307;</literal></tag-name> -<tag-desc>status is either 301, 302, 303, or 307</tag-desc> - -</list> - -<list type="tag"> - -<tag-name><literal>header Content-Type = text/html;</literal></tag-name> -<tag-desc> -header contains <header>Content-Type</header> -with value <literal>text/html</literal> -</tag-desc> - -<tag-name><literal>header Content-Type != text/html;</literal></tag-name> -<tag-desc> -header contains <header>Content-Type</header> -with value other than <literal>text/html</literal> -</tag-desc> - -<tag-name><literal>header Connection ~ close;</literal></tag-name> -<tag-desc> -header contains <header>Connection</header> -with value matching regular expression <literal>close</literal> -</tag-desc> - -<tag-name><literal>header Connection !~ close;</literal></tag-name> -<tag-desc> -header contains <header>Connection</header> -with value not matching regular expression <literal>close</literal> -</tag-desc> - -<tag-name><literal>header Host;</literal></tag-name> -<tag-desc>header contains <header>Host</header></tag-desc> - -<tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name> -<tag-desc>header lacks <header>X-Accel-Redirect</header></tag-desc> - -</list> - -<list type="tag"> - -<tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name> -<tag-desc> -body matches regular expression “<literal>Welcome to nginx!</literal>” -</tag-desc> - -<tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name> -<tag-desc> -body does not match regular expression “<literal>Welcome to nginx!</literal>” -</tag-desc> - -</list> -</para> - -<para> -If several tests are specified, -the response matches only if it matches all tests. -<note> -Only the first 256k of the response body are examined. -</note> -</para> - -<para> -Examples: -<example> -# status is 200, content type is "text/html", -# and body contains "Welcome to nginx!" -match welcome { - status 200; - header Content-Type = text/html; - body ~ "Welcome to nginx!"; -} -</example> - -<example> -# status is not one of 301, 302, 303, or 307, and header does not have "Refresh:" -match not_redirect { - status ! 301-303 307; - header ! Refresh; -} -</example> - -<example> -# status ok and not in maintenance mode -match server_ok { - status 200-399; - body !~ "maintenance mode"; -} -</example> - -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="queue"> -<syntax> -<value>number</value> -[<literal>timeout</literal>=<value>time</value>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.5.12</appeared-in> - -<para> -If an upstream server cannot be selected immediately -while processing a request, -and there are the servers in the group that have reached the -<link id="max_conns"/> limit, -the request will be placed into the queue. -The directive specifies the maximum number of requests that can be in the queue -at the same time. -If the queue is filled up, -or the server to pass the request to cannot been selected within -the time period specified in the <literal>timeout</literal> parameter, -an error will be returned to the client. -</para> - -<para> -The default value of the <literal>timeout</literal> parameter is 60 seconds. -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="sticky"> -<syntax> - <literal>cookie</literal> <value>name</value> - [<literal>expires=</literal><value>time</value>] - [<literal>domain=</literal><value>domain</value>] - [<literal>path=</literal><value>path</value>]</syntax> -<syntax> - <literal>route</literal> <value>$variable</value> ...</syntax> -<syntax> - <literal>learn</literal> - <literal>create=</literal><value>$variable</value> - <literal>lookup=</literal><value>$variable</value> - <literal>zone=</literal><value>name</value>:<value>size</value> - [<literal>timeout=</literal><value>time</value>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.5.7</appeared-in> - -<para> -Enables session affinity, which causes requests from the same client to be -passed to the same server in a group of servers. -Three methods are available: -<list type="tag"> -<tag-name id="sticky_cookie"><literal>cookie</literal></tag-name> -<tag-desc> - -<para> -When the <literal>cookie</literal> method is used, information about the -designated server is passed in an HTTP cookie generated by nginx: -<example> -upstream backend { - server backend1.example.com; - server backend2.example.com; - - sticky cookie srv_id expires=1h domain=.example.com path=/; -} -</example> -</para> - -<para> -A request that comes from a client not yet bound to a particular server -is passed to the server selected by the configured balancing method. -Further requests with this cookie will be passed to the designated server. -If the designated server cannot process a request, the new server is -selected as if the client has not been bound yet. -</para> - -<para> -The first parameter sets the name of the cookie to be set or inspected. -Additional parameters may be as follows: -<list type="tag"> - -<tag-name><literal>expires</literal></tag-name> -<tag-desc> -Sets the time 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-desc> -Defines the domain for which the cookie is set. -</tag-desc> - -<tag-name><literal>path</literal></tag-name> -<tag-desc> -Defines the path for which the cookie is set. -</tag-desc> - -</list> -If any parameters are omitted, the corresponding cookie fields are not set. -</para> -</tag-desc> - -<tag-name id="sticky_route"><literal>route</literal></tag-name> -<tag-desc> - -<para> -When the <literal>route</literal> method is used, proxied server assigns -client a route on receipt of the first request. -All subsequent requests from this client will carry routing information -in a cookie or URI. -This information is compared with the “<literal>route</literal>” parameter -of the <link id="server"/> directive to identify the server to which the -request should be proxied. -If the designated server cannot process a request, the new server is -selected by the configured balancing method as if there is no routing -information in the request. -</para> - -<para> -The parameters of the <literal>route</literal> method specify variables that -may contain routing information. -The first non-empty variable is used to find the matching server. -</para> - -<para> -Example: -<example> -map $cookie_jsessionid $route_cookie { - ~.+\.(?P<route>\w+)$ $route; -} - -map $request_uri $route_uri { - ~jsessionid=.+\.(?P<route>\w+)$ $route; -} - -upstream backend { - server backend1.example.com route=a; - server backend2.example.com route=b; - - sticky route $route_cookie $route_uri; -} -</example> -Here, the route is taken from the “<literal>JSESSIONID</literal>” cookie -if present in a request. -Otherwise, the route from the URI is used. -</para> - -</tag-desc> - -<tag-name id="sticky_learn"><literal>learn</literal></tag-name> -<tag-desc> -<para> -When the <literal>learn</literal> method (1.7.1) is used, nginx -analyzes upstream server responses and learns server-initiated sessions -usually passed in an HTTP cookie. -<example> -upstream backend { - server backend1.example.com:8080; - server backend2.example.com:8081; - - sticky learn - create=$upstream_cookie_sessionid - lookup=$cookie_sessionid - zone=client_sessions:1m; -} -</example> - -In the example, the upstream server creates a session by setting the -cookie “<literal>SESSIONID</literal>” in the response. -Further requests with this cookie will be passed to the same server. -If the server cannot process the request, the new server is -selected as if the client has not been bound yet. -</para> - -<para> -The parameters <literal>create</literal> and <literal>lookup</literal> -specify variables that indicate how new sessions are created and existing -sessions are searched, respectively. -Both parameters may be specified more than once, in which case the first -non-empty variable is used. -</para> - -<para> -Sessions are stored in a shared memory zone, whose <value>name</value> and -<value>size</value> are configured by the <literal>zone</literal> parameter. -One megabyte zone can store about 8000 sessions on the 64-bit platform. -The sessions that are not accessed during the time specified by the -<literal>timeout</literal> parameter get removed from the zone. -By default, <literal>timeout</literal> is set to 10 minutes. -</para> - -</tag-desc> -</list> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="sticky_cookie_insert"> -<syntax><value>name</value> -[<literal>expires=</literal><value>time</value>] -[<literal>domain=</literal><value>domain</value>] -[<literal>path=</literal><value>path</value>]</syntax> -<default/> -<context>upstream</context> - -<para> -This directive is obsolete since version 1.5.7. -An equivalent -<link id="sticky"/> directive with a new syntax should be used instead: -<note> -<literal>sticky cookie</literal> <value>name</value> -[<literal>expires=</literal><value>time</value>] -[<literal>domain=</literal><value>domain</value>] -[<literal>path=</literal><value>path</value>]; -</note> -</para> - -</directive> - - <directive name="upstream_conf"> <syntax/> <default/> @@ -1068,7 +87,7 @@ or viewing the group configuration. A configuration command consists of parameters passed as request arguments, for example: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic +http://127.0.0.1/upstream_conf?upstream=backend </example> </para> @@ -1078,6 +97,17 @@ 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. @@ -1116,17 +146,27 @@ was also required to view, modify, or re <literal>server=</literal><value>address</value></tag-name> <tag-desc> Same as the “<literal>address</literal>” parameter -of the <link id="server"/> directive. +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 -<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. +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> @@ -1134,48 +174,75 @@ the <link id="resolve"/> parameter of th <literal>weight=</literal><value>number</value></tag-name> <tag-desc> Same as the “<literal>weight</literal>” parameter -of the <link id="server"/> directive. +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 id="server"/> directive. +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 id="server"/> directive. +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 id="server"/> directive. +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 id="server"/> directive. +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 id="server"/> directive. +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 upstream server in the “draining” mode (1.7.5). -In this mode, only requests <link id="sticky">bound</link> to the server +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> @@ -1183,20 +250,26 @@ will be proxied to it. <literal>up=</literal></tag-name> <tag-desc> The opposite of the “<literal>down</literal>” parameter -of the <link id="server"/> directive. +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 id="server"/> directive. +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 two parameters select an object. -This can be either the whole group or a specific server. +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> @@ -1204,12 +277,12 @@ group or server is shown. <para> For example, to view the configuration of the whole group, send: <example> -http://127.0.0.1/upstream_conf?upstream=dynamic +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=dynamic&id=42 +http://127.0.0.1/upstream_conf?upstream=backend&id=42 </example> </para> @@ -1217,158 +290,61 @@ http://127.0.0.1/upstream_conf?upstream= 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). +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=dynamic&server=127.0.0.1:8080 +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=dynamic&backup=&server=127.0.0.1:8080 +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=dynamic&server=127.0.0.1:8080&weight=2&down= +http://127.0.0.1/upstream_conf?add=&upstream=backend&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 +http://127.0.0.1/upstream_conf?remove=&upstream=backend&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= +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=dynamic&id=42&server=192.0.2.3:8123 +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=dynamic&id=42&max_fails=3&weight=4 +http://127.0.0.1/upstream_conf?upstream=backend&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> +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> - -<section id="variables" name="Embedded Variables"> - -<para> -The <literal>ngx_http_upstream_module</literal> module -supports the following embedded variables: -<list type="tag"> - -<tag-name id="var_upstream_addr"><var>$upstream_addr</var></tag-name> -<tag-desc> -keeps the IP address and port, -or the path to the UNIX-domain socket of the upstream server. -If several servers were contacted during request processing, -their addresses are separated by commas, e.g. -“<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”. -If an internal redirect from one server group to another happens, -initiated by -<header>X-Accel-Redirect</header> or -<link doc="ngx_http_core_module.xml" id="error_page"/>, -then the server addresses from different groups are separated by colons, e.g. -“<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80</literal>”. -</tag-desc> - -<tag-name id="var_upstream_cache_status"><var>$upstream_cache_status</var> -</tag-name> -<tag-desc> -keeps the status of accessing a response cache (0.8.3). -The status can be either “<literal>MISS</literal>”, -“<literal>BYPASS</literal>”, “<literal>EXPIRED</literal>”, -“<literal>STALE</literal>”, “<literal>UPDATING</literal>”, -“<literal>REVALIDATED</literal>”, or “<literal>HIT</literal>”. -</tag-desc> - -<tag-name id="var_upstream_cookie_"><var>$upstream_cookie_</var><value>name</value> -</tag-name> -<tag-desc> -cookie with the specified <value>name</value> sent by the upstream server -in the <header>Set-Cookie</header> response header field (1.7.1). -Only the cookies from the response of the last server are saved. -</tag-desc> - -<tag-name id="var_upstream_header_time"><var>$upstream_header_time</var> -</tag-name> -<tag-desc> -keeps time -spent on receiving the response header from the upstream server (1.7.10); -the time is kept in seconds with millisecond resolution. -Times of several responses -are separated by commas and colons like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -<tag-name id="var_upstream_http_"><var>$upstream_http_</var><value>name</value></tag-name> -<tag-desc> -keep server response header fields. -For example, the <header>Server</header> response header field -is available through the <var>$upstream_http_server</var> variable. -The rules of converting header field names to variable names are the same -as for the variables that start with the -“<link doc="ngx_http_core_module.xml" id="var_http_">$http_</link>” prefix. -Only the header fields from the response of the last server are saved. -</tag-desc> - -<tag-name id="var_upstream_response_length"><var>$upstream_response_length</var> -</tag-name> -<tag-desc> -keeps the length of the response obtained from the upstream server (0.7.27); -the length is kept in bytes. -Lengths of several responses -are separated by commas and colons like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -<tag-name id="var_upstream_response_time"><var>$upstream_response_time</var> -</tag-name> -<tag-desc> -keeps time spent on receiving the response from the upstream server; -the time is kept in seconds with millisecond resolution. -Times of several responses -are separated by commas and colons like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -<tag-name id="var_upstream_status"><var>$upstream_status</var></tag-name> -<tag-desc> -keeps status code of the response obtained from the upstream server. -Status codes of several responses -are separated by commas and colons like addresses in the -<link id="var_upstream_addr">$upstream_addr</link> variable. -</tag-desc> - -</list> -</para> - -</section> - </module>