Mercurial > hg > nginx-site
diff xml/en/docs/http/ngx_http_upstream_module.xml @ 3043:9eadb98ec770
Free nginx: removed commercial version documentation.
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Wed, 14 Feb 2024 20:05:49 +0300 |
parents | 27008cb3fb27 |
children | 0bbf14c9fd66 |
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_upstream_module.xml Wed Feb 14 20:05:46 2024 +0300 +++ b/xml/en/docs/http/ngx_http_upstream_module.xml Wed Feb 14 20:05:49 2024 +0300 @@ -10,7 +10,7 @@ <module name="Module ngx_http_upstream_module" link="/en/docs/http/ngx_http_upstream_module.html" lang="en" - rev="88"> + rev="89"> <section id="summary"> @@ -49,36 +49,6 @@ </example> </para> -<para> -Dynamically configurable group with -periodic <link doc="ngx_http_upstream_hc_module.xml">health checks</link> is -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 backend4.example.com service=http resolve; - - server backup1.example.com:8080 backup; - server backup2.example.com:8080 backup; -} - -server { - location / { - proxy_pass http://<emphasis>dynamic</emphasis>; - health_check; - } -} -</example> -</para> - </section> @@ -168,11 +138,6 @@ the total number of active and idle connections to the proxied server may exceed the <literal>max_conns</literal> value. </note> -<note> -Since version 1.5.9 and prior to version 1.11.5, -this parameter was available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> </tag-desc> <tag-name id="max_fails"> @@ -239,117 +204,9 @@ </para> <para> -Additionally, -the following parameters are available as part of our -<commercial_version>commercial subscription</commercial_version>: -<list type="tag"> - -<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). -The server group must reside in the <link id="zone">shared memory</link>. -<para> -In order for this parameter to work, -the <literal>resolver</literal> directive -must be specified in the -<link doc="ngx_http_core_module.xml" id="resolver">http</link> block -or in the corresponding <link id="resolver">upstream</link> block. -</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="service"> -<literal>service</literal>=<value>name</value> -</tag-name> -<tag-desc> -enables resolving of DNS -<link url="https://datatracker.ietf.org/doc/html/rfc2782">SRV</link> -records and sets the service <value>name</value> (1.9.13). -In order for this parameter to work, it is necessary to specify -the <link id="resolve"/> parameter for the server -and specify a hostname without a port number. -<para> -If the service name does not contain a dot (“<literal>.</literal>”), then -the <link url="https://datatracker.ietf.org/doc/html/rfc2782">RFC</link>-compliant name -is constructed -and the TCP protocol is added to the service prefix. -For example, to look up the -<literal>_http._tcp.backend.example.com</literal> SRV record, -it is necessary to specify the directive: -<example> -server backend.example.com service=http resolve; -</example> -If the service name contains one or more dots, then the name is constructed -by joining the service prefix and the server name. -For example, to look up the <literal>_http._tcp.backend.example.com</literal> -and <literal>server1.backend.example.com</literal> SRV records, -it is necessary to specify the directives: -<example> -server backend.example.com service=_http._tcp resolve; -server example.com service=server1.backend resolve; -</example> -</para> - -<para> -Highest-priority SRV records -(records with the same lowest-number priority value) -are resolved as primary servers, -the rest of SRV records are resolved as backup servers. -If the <link id="backup"/> parameter is specified for the server, -high-priority SRV records are resolved as backup servers, -the rest of SRV records are ignored. -</para> -</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 doc="ngx_http_upstream_hc_module.xml" 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. <note> -The parameter cannot be used along with the -<link id="hash"/>, <link id="ip_hash"/>, and <link id="random"/> -load balancing methods. -</note> -</tag-desc> - -<tag-name id="drain"> -<literal>drain</literal> -</tag-name> -<tag-desc> -puts the server into the “draining” mode (1.13.6). -In this mode, only requests <link id="sticky">bound</link> to the server -will be proxied to it. -<note> -Prior to version 1.13.6, -the parameter could be changed only with the -<link doc="ngx_http_api_module.xml">API</link> module. -</note> -</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 +If there is only a single server in a group, +<literal>max_fails</literal> and <literal>fail_timeout</literal> parameters are ignored, and such a server will never be considered unavailable. </note> </para> @@ -371,70 +228,6 @@ In this case, it is enough to specify the <value>size</value> only once. </para> -<para> -Additionally, -as part of our <commercial_version>commercial subscription</commercial_version>, -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 the -<link doc="ngx_http_api_module.xml">API</link> module (1.13.3). -<note> -Prior to version 1.13.3, -the configuration was accessible only via a special location -handled by -<link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. -</note> -</para> - -</directive> - - -<directive name="state"> -<syntax><value>file</value></syntax> -<default/> -<context>upstream</context> -<appeared-in>1.9.7</appeared-in> - -<para> -Specifies a <value>file</value> that keeps the state -of the dynamically configurable group. -</para> - -<para> -Examples: -<example> -state /var/lib/nginx/state/servers.conf; # path for Linux -state /var/db/nginx/state/servers.conf; # path for FreeBSD -</example> -</para> - -<para> -The state is currently limited to the list of servers with their parameters. -The file is read when parsing the configuration and is updated each time -the upstream configuration is -<link doc="ngx_http_api_module.xml" id="http_upstreams_http_upstream_name_servers_">changed</link>. -Changing the file content directly should be avoided. -The directive cannot be used -along with the <link id="server"/> directive. -</para> - -<para> -<note> -Changes made during -<link doc="../control.xml" id="reconfiguration">configuration reload</link> -or <link doc="../control.xml" id="upgrade">binary upgrade</link> -can be lost. -</note> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - </directive> @@ -695,68 +488,6 @@ </directive> -<directive name="ntlm"> -<syntax/> -<default/> -<context>upstream</context> -<appeared-in>1.9.2</appeared-in> - -<para> -Allows proxying requests with -<link url="https://en.wikipedia.org/wiki/Integrated_Windows_Authentication">NTLM -Authentication</link>. -The upstream connection is bound to the client connection -once the client sends a request with the <header>Authorization</header> -header field value -starting with “<literal>Negotiate</literal>” or “<literal>NTLM</literal>”. -Further client requests will be proxied through the same upstream connection, -keeping the authentication context. -</para> - -<para> -In order for NTLM authentication to work, -it is necessary to enable keepalive connections to upstream servers. -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; - - ntlm; -} - -server { - ... - - location /http/ { - proxy_pass http://http_backend; - proxy_http_version 1.1; - proxy_set_header Connection ""; - ... - } -} -</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>ntlm</literal> directive. -</note> -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="least_conn"> <syntax/> <default/> @@ -775,88 +506,6 @@ </directive> -<directive name="least_time"> -<syntax> - <literal>header</literal> | - <literal>last_byte</literal> - [<literal>inflight</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. -If the <literal>inflight</literal> parameter is specified (1.11.6), -incomplete requests are also taken into account. -<note> -Prior to version 1.11.6, incomplete requests were taken into account by default. -</note> -</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, -the request will be placed into the queue. -The directive specifies the maximum <value>number</value> 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 be selected within -the time period specified in the <literal>timeout</literal> parameter, -the <http-status code="502" text="Bad Gateway"/> -error will be returned to the client. -</para> - -<para> -The default value of the <literal>timeout</literal> parameter is 60 seconds. -</para> - -<para> -<note> -When using load balancer methods other than the default -round-robin method, it is necessary to activate them before -the <literal>queue</literal> directive. -</note> - -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="random"> <syntax>[<literal>two</literal> [<value>method</value>]]</syntax> <default/> @@ -880,379 +529,6 @@ with the least number of active connections. </para> -<para id="random_least_time"> -The <literal>least_time</literal> method passes a request to a server -with the least average response time and least number of active connections. -If <literal>least_time=header</literal> is specified, the time to receive the -<link id="var_upstream_header_time">response header</link> is used. -If <literal>least_time=last_byte</literal> is specified, the time to receive the -<link id="var_upstream_response_time">full response</link> is used. -<note> -The <literal>least_time</literal> method is available as a part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="resolver"> -<syntax> - <value>address</value> ... - [<literal>valid</literal>=<value>time</value>] - [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] - [<literal>status_zone</literal>=<value>zone</value>]</syntax> -<default/> -<context>upstream</context> -<appeared-in>1.17.5</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> -The address can be specified as a domain name or IP address, -with an optional port. -If port is not specified, the port 53 is used. -Name servers are queried in a round-robin fashion. -</para> - -<para id="resolver_ipv6"> -By default, nginx will look up both IPv4 and IPv6 addresses while resolving. -If looking up of IPv4 or IPv6 addresses is not desired, -the <literal>ipv4=off</literal> (1.23.1) or -the <literal>ipv6=off</literal> parameter can be specified. -</para> - -<para id="resolver_valid"> -By default, nginx caches answers using the TTL value of a response. -An optional <literal>valid</literal> parameter allows overriding it: -<example> -resolver 127.0.0.1 [::1]:5353 valid=30s; -</example> -<note> -To prevent DNS spoofing, it is recommended -configuring DNS servers in a properly secured trusted local network. -</note> -</para> - -<para id="resolver_status_zone"> -The optional <literal>status_zone</literal> parameter -enables -<link doc="ngx_http_api_module.xml" id="resolvers_">collection</link> -of DNS server statistics of requests and responses -in the specified <value>zone</value>. -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - -<directive name="resolver_timeout"> -<syntax><value>time</value></syntax> -<default>30s</default> -<context>upstream</context> -<appeared-in>1.17.5</appeared-in> - -<para> -Sets a timeout for name resolution, for example: -<example> -resolver_timeout 5s; -</example> -</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>httponly</literal>] - [<literal>samesite=</literal><literal>strict</literal>|<literal>lax</literal>|<literal>none</literal>|<value>$variable</value>] - [<literal>secure</literal>] - [<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>] - [<literal>header</literal>] - [<literal>sync</literal>]</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. - -<note> -As a load balancing method always tries to evenly distribute the load -considering already bound requests, -the server with a higher number of active bound requests -has less possibility of getting new unbound requests. -</note> -</para> - -<para> -The first parameter sets the name of the cookie to be set or inspected. -The cookie value is -a hexadecimal representation of the MD5 hash of the IP address and port, -or of the UNIX-domain socket path. -However, if the “<literal>route</literal>” parameter of the -<link id="server"/> directive is specified, the cookie value will be -the value of the “<literal>route</literal>” parameter: -<example> -upstream backend { - server backend1.example.com route=<emphasis>a</emphasis>; - server backend2.example.com route=<emphasis>b</emphasis>; - - sticky cookie srv_id expires=1h domain=.example.com path=/; -} -</example> -In this case, the value of the “<literal>srv_id</literal>” cookie will be -either <value>a</value> or <value>b</value>. -</para> - -<para> -Additional parameters may be as follows: -<list type="tag"> - -<tag-name><literal>expires=</literal><value>time</value></tag-name> -<tag-desc> -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><value>domain</value></tag-name> -<tag-desc> -Defines the <value>domain</value> for which the cookie is set. -Parameter value can contain variables (1.11.5). -</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 id="sticky_samesite"><literal>samesite=</literal><literal>strict</literal> | -<literal>lax</literal> | <literal>none</literal> | <value>$variable</value></tag-name> -<tag-desc> -Adds the <literal>SameSite</literal> (1.19.4) attribute to the cookie -with one of the following values: -<literal>Strict</literal>, -<literal>Lax</literal>, -<literal>None</literal>, or -using variables (1.23.3). -In the latter case, if the variable value is empty, -the <literal>SameSite</literal> attribute will not be added to the cookie, -if the value is resolved to -<literal>Strict</literal>, -<literal>Lax</literal>, or -<literal>None</literal>, -the corresponding value will be assigned, -otherwise the <literal>Strict</literal> value will be assigned. -</tag-desc> - -<tag-name><literal>secure</literal></tag-name> -<tag-desc> -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> -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 “<literal>route</literal>” parameter is not specified, the route name -will be a hexadecimal representation of the MD5 hash of the IP address and port, -or of the UNIX-domain socket path. -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_examplecookie - lookup=$cookie_examplecookie - zone=client_sessions:1m; -} -</example> - -In the example, the upstream server creates a session by setting the -cookie “<literal>EXAMPLECOOKIE</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 4000 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> - -<para id="sticky_learn_header"> -The <literal>header</literal> parameter (1.13.1) allows creating a session -right after receiving response headers from the upstream server. -</para> - -<para id="sticky_learn_sync"> -The <literal>sync</literal> parameter (1.13.8) enables -<link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">synchronization</link> -of the shared memory zone. -</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> </section> @@ -1349,25 +625,6 @@ Only the header fields from the response of the last server are saved. </tag-desc> -<tag-name id="var_upstream_last_server_name"><var>$upstream_last_server_name</var></tag-name> -<tag-desc> -keeps the name of last selected upstream server (1.25.3); -allows passing it -<link doc="ngx_http_proxy_module.xml" id="proxy_ssl_server_name">through SNI</link>: -<example> -proxy_ssl_server_name on; -proxy_ssl_name $upstream_last_server_name; -</example> - -<para> -<note> -This variable is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</tag-desc> - <tag-name id="var_upstream_queue_time"><var>$upstream_queue_time</var></tag-name> <tag-desc> keeps time the request spent in the upstream <link id="queue">queue</link>