Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 3043:9eadb98ec770

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
comparison
equal deleted inserted replaced
3042:19e4897acb84 3043:9eadb98ec770
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9 9
10 <module name="Module ngx_http_upstream_module" 10 <module name="Module ngx_http_upstream_module"
11 link="/en/docs/http/ngx_http_upstream_module.html" 11 link="/en/docs/http/ngx_http_upstream_module.html"
12 lang="en" 12 lang="en"
13 rev="88"> 13 rev="89">
14 14
15 <section id="summary"> 15 <section id="summary">
16 16
17 <para> 17 <para>
18 The <literal>ngx_http_upstream_module</literal> module 18 The <literal>ngx_http_upstream_module</literal> module
42 } 42 }
43 43
44 server { 44 server {
45 location / { 45 location / {
46 proxy_pass http://<emphasis>backend</emphasis>; 46 proxy_pass http://<emphasis>backend</emphasis>;
47 }
48 }
49 </example>
50 </para>
51
52 <para>
53 Dynamically configurable group with
54 periodic <link doc="ngx_http_upstream_hc_module.xml">health checks</link> is
55 available as part of our
56 <commercial_version>commercial subscription</commercial_version>:
57 <example>
58 resolver 10.0.0.1;
59
60 upstream <emphasis>dynamic</emphasis> {
61 zone upstream_dynamic 64k;
62
63 server backend1.example.com weight=5;
64 server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
65 server 192.0.2.1 max_fails=3;
66 server backend3.example.com resolve;
67 server backend4.example.com service=http resolve;
68
69 server backup1.example.com:8080 backup;
70 server backup2.example.com:8080 backup;
71 }
72
73 server {
74 location / {
75 proxy_pass http://<emphasis>dynamic</emphasis>;
76 health_check;
77 } 47 }
78 } 48 }
79 </example> 49 </example>
80 </para> 50 </para>
81 51
165 If <link id="keepalive">idle keepalive</link> connections, 135 If <link id="keepalive">idle keepalive</link> connections,
166 multiple <link doc="../ngx_core_module.xml" id="worker_processes">workers</link>, 136 multiple <link doc="../ngx_core_module.xml" id="worker_processes">workers</link>,
167 and the <link id="zone">shared memory</link> are enabled, 137 and the <link id="zone">shared memory</link> are enabled,
168 the total number of active and idle connections to the proxied server 138 the total number of active and idle connections to the proxied server
169 may exceed the <literal>max_conns</literal> value. 139 may exceed the <literal>max_conns</literal> value.
170 </note>
171 <note>
172 Since version 1.5.9 and prior to version 1.11.5,
173 this parameter was available as part of our
174 <commercial_version>commercial subscription</commercial_version>.
175 </note> 140 </note>
176 </tag-desc> 141 </tag-desc>
177 142
178 <tag-name id="max_fails"> 143 <tag-name id="max_fails">
179 <literal>max_fails</literal>=<value>number</value> 144 <literal>max_fails</literal>=<value>number</value>
237 202
238 </list> 203 </list>
239 </para> 204 </para>
240 205
241 <para> 206 <para>
242 Additionally, 207 <note>
243 the following parameters are available as part of our 208 If there is only a single server in a group,
244 <commercial_version>commercial subscription</commercial_version>: 209 <literal>max_fails</literal> and <literal>fail_timeout</literal> parameters
245 <list type="tag">
246
247 <tag-name id="resolve">
248 <literal>resolve</literal>
249 </tag-name>
250 <tag-desc>
251 monitors changes of the IP addresses
252 that correspond to a domain name of the server,
253 and automatically modifies the upstream configuration
254 without the need of restarting nginx (1.5.12).
255 The server group must reside in the <link id="zone">shared memory</link>.
256 <para>
257 In order for this parameter to work,
258 the <literal>resolver</literal> directive
259 must be specified in the
260 <link doc="ngx_http_core_module.xml" id="resolver">http</link> block
261 or in the corresponding <link id="resolver">upstream</link> block.
262 </para>
263 </tag-desc>
264
265 <tag-name id="route">
266 <literal>route</literal>=<value>string</value>
267 </tag-name>
268 <tag-desc>
269 sets the server route name.
270 </tag-desc>
271
272 <tag-name id="service">
273 <literal>service</literal>=<value>name</value>
274 </tag-name>
275 <tag-desc>
276 enables resolving of DNS
277 <link url="https://datatracker.ietf.org/doc/html/rfc2782">SRV</link>
278 records and sets the service <value>name</value> (1.9.13).
279 In order for this parameter to work, it is necessary to specify
280 the <link id="resolve"/> parameter for the server
281 and specify a hostname without a port number.
282 <para>
283 If the service name does not contain a dot (“<literal>.</literal>”), then
284 the <link url="https://datatracker.ietf.org/doc/html/rfc2782">RFC</link>-compliant name
285 is constructed
286 and the TCP protocol is added to the service prefix.
287 For example, to look up the
288 <literal>_http._tcp.backend.example.com</literal> SRV record,
289 it is necessary to specify the directive:
290 <example>
291 server backend.example.com service=http resolve;
292 </example>
293 If the service name contains one or more dots, then the name is constructed
294 by joining the service prefix and the server name.
295 For example, to look up the <literal>_http._tcp.backend.example.com</literal>
296 and <literal>server1.backend.example.com</literal> SRV records,
297 it is necessary to specify the directives:
298 <example>
299 server backend.example.com service=_http._tcp resolve;
300 server example.com service=server1.backend resolve;
301 </example>
302 </para>
303
304 <para>
305 Highest-priority SRV records
306 (records with the same lowest-number priority value)
307 are resolved as primary servers,
308 the rest of SRV records are resolved as backup servers.
309 If the <link id="backup"/> parameter is specified for the server,
310 high-priority SRV records are resolved as backup servers,
311 the rest of SRV records are ignored.
312 </para>
313 </tag-desc>
314
315 <tag-name id="slow_start">
316 <literal>slow_start</literal>=<value>time</value>
317 </tag-name>
318 <tag-desc>
319 sets the <value>time</value> during which the server will recover its weight
320 from zero to a nominal value, when unhealthy server becomes
321 <link doc="ngx_http_upstream_hc_module.xml" id="health_check">healthy</link>,
322 or when the server becomes available after a period of time
323 it was considered <link id="fail_timeout">unavailable</link>.
324 Default value is zero, i.e. slow start is disabled.
325 <note>
326 The parameter cannot be used along with the
327 <link id="hash"/>, <link id="ip_hash"/>, and <link id="random"/>
328 load balancing methods.
329 </note>
330 </tag-desc>
331
332 <tag-name id="drain">
333 <literal>drain</literal>
334 </tag-name>
335 <tag-desc>
336 puts the server into the “draining” mode (1.13.6).
337 In this mode, only requests <link id="sticky">bound</link> to the server
338 will be proxied to it.
339 <note>
340 Prior to version 1.13.6,
341 the parameter could be changed only with the
342 <link doc="ngx_http_api_module.xml">API</link> module.
343 </note>
344 </tag-desc>
345
346 </list>
347 </para>
348
349 <para>
350 <note>
351 If there is only a single server in a group, <literal>max_fails</literal>,
352 <literal>fail_timeout</literal> and <literal>slow_start</literal> parameters
353 are ignored, and such a server will never be considered unavailable. 210 are ignored, and such a server will never be considered unavailable.
354 </note> 211 </note>
355 </para> 212 </para>
356 213
357 </directive> 214 </directive>
367 Defines the <value>name</value> and <value>size</value> of the shared 224 Defines the <value>name</value> and <value>size</value> of the shared
368 memory zone that keeps the group’s configuration and run-time state that are 225 memory zone that keeps the group’s configuration and run-time state that are
369 shared between worker processes. 226 shared between worker processes.
370 Several groups may share the same zone. 227 Several groups may share the same zone.
371 In this case, it is enough to specify the <value>size</value> only once. 228 In this case, it is enough to specify the <value>size</value> only once.
372 </para>
373
374 <para>
375 Additionally,
376 as part of our <commercial_version>commercial subscription</commercial_version>,
377 such groups allow changing the group membership
378 or modifying the settings of a particular server
379 without the need of restarting nginx.
380 The configuration is accessible via the
381 <link doc="ngx_http_api_module.xml">API</link> module (1.13.3).
382 <note>
383 Prior to version 1.13.3,
384 the configuration was accessible only via a special location
385 handled by
386 <link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf"/>.
387 </note>
388 </para>
389
390 </directive>
391
392
393 <directive name="state">
394 <syntax><value>file</value></syntax>
395 <default/>
396 <context>upstream</context>
397 <appeared-in>1.9.7</appeared-in>
398
399 <para>
400 Specifies a <value>file</value> that keeps the state
401 of the dynamically configurable group.
402 </para>
403
404 <para>
405 Examples:
406 <example>
407 state /var/lib/nginx/state/servers.conf; # path for Linux
408 state /var/db/nginx/state/servers.conf; # path for FreeBSD
409 </example>
410 </para>
411
412 <para>
413 The state is currently limited to the list of servers with their parameters.
414 The file is read when parsing the configuration and is updated each time
415 the upstream configuration is
416 <link doc="ngx_http_api_module.xml" id="http_upstreams_http_upstream_name_servers_">changed</link>.
417 Changing the file content directly should be avoided.
418 The directive cannot be used
419 along with the <link id="server"/> directive.
420 </para>
421
422 <para>
423 <note>
424 Changes made during
425 <link doc="../control.xml" id="reconfiguration">configuration reload</link>
426 or <link doc="../control.xml" id="upgrade">binary upgrade</link>
427 can be lost.
428 </note>
429 </para>
430
431 <para>
432 <note>
433 This directive is available as part of our
434 <commercial_version>commercial subscription</commercial_version>.
435 </note>
436 </para> 229 </para>
437 230
438 </directive> 231 </directive>
439 232
440 233
693 </para> 486 </para>
694 487
695 </directive> 488 </directive>
696 489
697 490
698 <directive name="ntlm">
699 <syntax/>
700 <default/>
701 <context>upstream</context>
702 <appeared-in>1.9.2</appeared-in>
703
704 <para>
705 Allows proxying requests with
706 <link url="https://en.wikipedia.org/wiki/Integrated_Windows_Authentication">NTLM
707 Authentication</link>.
708 The upstream connection is bound to the client connection
709 once the client sends a request with the <header>Authorization</header>
710 header field value
711 starting with “<literal>Negotiate</literal>” or “<literal>NTLM</literal>”.
712 Further client requests will be proxied through the same upstream connection,
713 keeping the authentication context.
714 </para>
715
716 <para>
717 In order for NTLM authentication to work,
718 it is necessary to enable keepalive connections to upstream servers.
719 The <link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/>
720 directive should be set to “<literal>1.1</literal>”
721 and the <header>Connection</header> header field should be cleared:
722 <example>
723 upstream http_backend {
724 server 127.0.0.1:8080;
725
726 ntlm;
727 }
728
729 server {
730 ...
731
732 location /http/ {
733 proxy_pass http://http_backend;
734 proxy_http_version 1.1;
735 proxy_set_header Connection "";
736 ...
737 }
738 }
739 </example>
740 </para>
741
742 <para>
743 <note>
744 When using load balancer methods other than the default
745 round-robin method, it is necessary to activate them before
746 the <literal>ntlm</literal> directive.
747 </note>
748 </para>
749
750 <para>
751 <note>
752 This directive is available as part of our
753 <commercial_version>commercial subscription</commercial_version>.
754 </note>
755 </para>
756
757 </directive>
758
759
760 <directive name="least_conn"> 491 <directive name="least_conn">
761 <syntax/> 492 <syntax/>
762 <default/> 493 <default/>
763 <context>upstream</context> 494 <context>upstream</context>
764 <appeared-in>1.3.1</appeared-in> 495 <appeared-in>1.3.1</appeared-in>
768 Specifies that a group should use a load balancing method where a request 499 Specifies that a group should use a load balancing method where a request
769 is passed to the server with the least number of active connections, 500 is passed to the server with the least number of active connections,
770 taking into account weights of servers. 501 taking into account weights of servers.
771 If there are several such servers, they are tried in turn using a 502 If there are several such servers, they are tried in turn using a
772 weighted round-robin balancing method. 503 weighted round-robin balancing method.
773 </para>
774
775 </directive>
776
777
778 <directive name="least_time">
779 <syntax>
780 <literal>header</literal> |
781 <literal>last_byte</literal>
782 [<literal>inflight</literal>]</syntax>
783 <default/>
784 <context>upstream</context>
785 <appeared-in>1.7.10</appeared-in>
786
787 <para>
788 Specifies that a group should use a load balancing method where a request
789 is passed to the server with the least average response time and
790 least number of active connections, taking into account weights of servers.
791 If there are several such servers, they are tried in turn using a
792 weighted round-robin balancing method.
793 </para>
794
795 <para>
796 If the <literal>header</literal> parameter is specified,
797 time to receive the
798 <link id="var_upstream_header_time">response header</link> is used.
799 If the <literal>last_byte</literal> parameter is specified,
800 time to receive the <link id="var_upstream_response_time">full response</link>
801 is used.
802 If the <literal>inflight</literal> parameter is specified (1.11.6),
803 incomplete requests are also taken into account.
804 <note>
805 Prior to version 1.11.6, incomplete requests were taken into account by default.
806 </note>
807 </para>
808
809 <para>
810 <note>
811 This directive is available as part of our
812 <commercial_version>commercial subscription</commercial_version>.
813 </note>
814 </para>
815
816 </directive>
817
818
819 <directive name="queue">
820 <syntax>
821 <value>number</value>
822 [<literal>timeout</literal>=<value>time</value>]</syntax>
823 <default/>
824 <context>upstream</context>
825 <appeared-in>1.5.12</appeared-in>
826
827 <para>
828 If an upstream server cannot be selected immediately
829 while processing a request,
830 the request will be placed into the queue.
831 The directive specifies the maximum <value>number</value> of requests
832 that can be in the queue at the same time.
833 If the queue is filled up,
834 or the server to pass the request to cannot be selected within
835 the time period specified in the <literal>timeout</literal> parameter,
836 the <http-status code="502" text="Bad Gateway"/>
837 error will be returned to the client.
838 </para>
839
840 <para>
841 The default value of the <literal>timeout</literal> parameter is 60 seconds.
842 </para>
843
844 <para>
845 <note>
846 When using load balancer methods other than the default
847 round-robin method, it is necessary to activate them before
848 the <literal>queue</literal> directive.
849 </note>
850
851 <note>
852 This directive is available as part of our
853 <commercial_version>commercial subscription</commercial_version>.
854 </note>
855 </para> 504 </para>
856 505
857 </directive> 506 </directive>
858 507
859 508
876 servers and then choose a server 525 servers and then choose a server
877 using the specified <literal>method</literal>. 526 using the specified <literal>method</literal>.
878 The default method is <literal>least_conn</literal> 527 The default method is <literal>least_conn</literal>
879 which passes a request to a server 528 which passes a request to a server
880 with the least number of active connections. 529 with the least number of active connections.
881 </para>
882
883 <para id="random_least_time">
884 The <literal>least_time</literal> method passes a request to a server
885 with the least average response time and least number of active connections.
886 If <literal>least_time=header</literal> is specified, the time to receive the
887 <link id="var_upstream_header_time">response header</link> is used.
888 If <literal>least_time=last_byte</literal> is specified, the time to receive the
889 <link id="var_upstream_response_time">full response</link> is used.
890 <note>
891 The <literal>least_time</literal> method is available as a part of our
892 <commercial_version>commercial subscription</commercial_version>.
893 </note>
894 </para>
895
896 </directive>
897
898
899 <directive name="resolver">
900 <syntax>
901 <value>address</value> ...
902 [<literal>valid</literal>=<value>time</value>]
903 [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>]
904 [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]
905 [<literal>status_zone</literal>=<value>zone</value>]</syntax>
906 <default/>
907 <context>upstream</context>
908 <appeared-in>1.17.5</appeared-in>
909
910 <para>
911 Configures name servers used to resolve names of upstream servers
912 into addresses, for example:
913 <example>
914 resolver 127.0.0.1 [::1]:5353;
915 </example>
916 The address can be specified as a domain name or IP address,
917 with an optional port.
918 If port is not specified, the port 53 is used.
919 Name servers are queried in a round-robin fashion.
920 </para>
921
922 <para id="resolver_ipv6">
923 By default, nginx will look up both IPv4 and IPv6 addresses while resolving.
924 If looking up of IPv4 or IPv6 addresses is not desired,
925 the <literal>ipv4=off</literal> (1.23.1) or
926 the <literal>ipv6=off</literal> parameter can be specified.
927 </para>
928
929 <para id="resolver_valid">
930 By default, nginx caches answers using the TTL value of a response.
931 An optional <literal>valid</literal> parameter allows overriding it:
932 <example>
933 resolver 127.0.0.1 [::1]:5353 valid=30s;
934 </example>
935 <note>
936 To prevent DNS spoofing, it is recommended
937 configuring DNS servers in a properly secured trusted local network.
938 </note>
939 </para>
940
941 <para id="resolver_status_zone">
942 The optional <literal>status_zone</literal> parameter
943 enables
944 <link doc="ngx_http_api_module.xml" id="resolvers_">collection</link>
945 of DNS server statistics of requests and responses
946 in the specified <value>zone</value>.
947 </para>
948
949 <para>
950 <note>
951 This directive is available as part of our
952 <commercial_version>commercial subscription</commercial_version>.
953 </note>
954 </para>
955
956 </directive>
957
958
959 <directive name="resolver_timeout">
960 <syntax><value>time</value></syntax>
961 <default>30s</default>
962 <context>upstream</context>
963 <appeared-in>1.17.5</appeared-in>
964
965 <para>
966 Sets a timeout for name resolution, for example:
967 <example>
968 resolver_timeout 5s;
969 </example>
970 </para>
971
972 <para>
973 <note>
974 This directive is available as part of our
975 <commercial_version>commercial subscription</commercial_version>.
976 </note>
977 </para>
978
979 </directive>
980
981
982 <directive name="sticky">
983 <syntax>
984 <literal>cookie</literal> <value>name</value>
985 [<literal>expires=</literal><value>time</value>]
986 [<literal>domain=</literal><value>domain</value>]
987 [<literal>httponly</literal>]
988 [<literal>samesite=</literal><literal>strict</literal>|<literal>lax</literal>|<literal>none</literal>|<value>$variable</value>]
989 [<literal>secure</literal>]
990 [<literal>path=</literal><value>path</value>]</syntax>
991 <syntax>
992 <literal>route</literal> <value>$variable</value> ...</syntax>
993 <syntax>
994 <literal>learn</literal>
995 <literal>create=</literal><value>$variable</value>
996 <literal>lookup=</literal><value>$variable</value>
997 <literal>zone=</literal><value>name</value>:<value>size</value>
998 [<literal>timeout=</literal><value>time</value>]
999 [<literal>header</literal>]
1000 [<literal>sync</literal>]</syntax>
1001 <default/>
1002 <context>upstream</context>
1003 <appeared-in>1.5.7</appeared-in>
1004
1005 <para>
1006 Enables session affinity, which causes requests from the same client to be
1007 passed to the same server in a group of servers.
1008 Three methods are available:
1009 <list type="tag">
1010 <tag-name id="sticky_cookie"><literal>cookie</literal></tag-name>
1011 <tag-desc>
1012
1013 <para>
1014 When the <literal>cookie</literal> method is used, information about the
1015 designated server is passed in an HTTP cookie generated by nginx:
1016 <example>
1017 upstream backend {
1018 server backend1.example.com;
1019 server backend2.example.com;
1020
1021 sticky cookie srv_id expires=1h domain=.example.com path=/;
1022 }
1023 </example>
1024 </para>
1025
1026 <para>
1027 A request that comes from a client not yet bound to a particular server
1028 is passed to the server selected by the configured balancing method.
1029 Further requests with this cookie will be passed to the designated server.
1030 If the designated server cannot process a request, the new server is
1031 selected as if the client has not been bound yet.
1032
1033 <note>
1034 As a load balancing method always tries to evenly distribute the load
1035 considering already bound requests,
1036 the server with a higher number of active bound requests
1037 has less possibility of getting new unbound requests.
1038 </note>
1039 </para>
1040
1041 <para>
1042 The first parameter sets the name of the cookie to be set or inspected.
1043 The cookie value is
1044 a hexadecimal representation of the MD5 hash of the IP address and port,
1045 or of the UNIX-domain socket path.
1046 However, if the “<literal>route</literal>” parameter of the
1047 <link id="server"/> directive is specified, the cookie value will be
1048 the value of the “<literal>route</literal>” parameter:
1049 <example>
1050 upstream backend {
1051 server backend1.example.com route=<emphasis>a</emphasis>;
1052 server backend2.example.com route=<emphasis>b</emphasis>;
1053
1054 sticky cookie srv_id expires=1h domain=.example.com path=/;
1055 }
1056 </example>
1057 In this case, the value of the “<literal>srv_id</literal>” cookie will be
1058 either <value>a</value> or <value>b</value>.
1059 </para>
1060
1061 <para>
1062 Additional parameters may be as follows:
1063 <list type="tag">
1064
1065 <tag-name><literal>expires=</literal><value>time</value></tag-name>
1066 <tag-desc>
1067 Sets the <value>time</value> for which a browser should keep the cookie.
1068 The special value <literal>max</literal> will cause the cookie to expire on
1069 “<literal>31 Dec 2037 23:55:55 GMT</literal>”.
1070 If the parameter is not specified, it will cause the cookie to expire at
1071 the end of a browser session.
1072 </tag-desc>
1073
1074 <tag-name><literal>domain=</literal><value>domain</value></tag-name>
1075 <tag-desc>
1076 Defines the <value>domain</value> for which the cookie is set.
1077 Parameter value can contain variables (1.11.5).
1078 </tag-desc>
1079
1080 <tag-name><literal>httponly</literal></tag-name>
1081 <tag-desc>
1082 Adds the <literal>HttpOnly</literal> attribute to the cookie (1.7.11).
1083 </tag-desc>
1084
1085 <tag-name id="sticky_samesite"><literal>samesite=</literal><literal>strict</literal> |
1086 <literal>lax</literal> | <literal>none</literal> | <value>$variable</value></tag-name>
1087 <tag-desc>
1088 Adds the <literal>SameSite</literal> (1.19.4) attribute to the cookie
1089 with one of the following values:
1090 <literal>Strict</literal>,
1091 <literal>Lax</literal>,
1092 <literal>None</literal>, or
1093 using variables (1.23.3).
1094 In the latter case, if the variable value is empty,
1095 the <literal>SameSite</literal> attribute will not be added to the cookie,
1096 if the value is resolved to
1097 <literal>Strict</literal>,
1098 <literal>Lax</literal>, or
1099 <literal>None</literal>,
1100 the corresponding value will be assigned,
1101 otherwise the <literal>Strict</literal> value will be assigned.
1102 </tag-desc>
1103
1104 <tag-name><literal>secure</literal></tag-name>
1105 <tag-desc>
1106 Adds the <literal>Secure</literal> attribute to the cookie (1.7.11).
1107 </tag-desc>
1108
1109 <tag-name><literal>path=</literal><value>path</value></tag-name>
1110 <tag-desc>
1111 Defines the <value>path</value> for which the cookie is set.
1112 </tag-desc>
1113
1114 </list>
1115 If any parameters are omitted, the corresponding cookie fields are not set.
1116 </para>
1117 </tag-desc>
1118
1119 <tag-name id="sticky_route"><literal>route</literal></tag-name>
1120 <tag-desc>
1121
1122 <para>
1123 When the <literal>route</literal> method is used, proxied server assigns
1124 client a route on receipt of the first request.
1125 All subsequent requests from this client will carry routing information
1126 in a cookie or URI.
1127 This information is compared with the “<literal>route</literal>” parameter
1128 of the <link id="server"/> directive to identify the server to which the
1129 request should be proxied.
1130 If the “<literal>route</literal>” parameter is not specified, the route name
1131 will be a hexadecimal representation of the MD5 hash of the IP address and port,
1132 or of the UNIX-domain socket path.
1133 If the designated server cannot process a request, the new server is
1134 selected by the configured balancing method as if there is no routing
1135 information in the request.
1136 </para>
1137
1138 <para>
1139 The parameters of the <literal>route</literal> method specify variables that
1140 may contain routing information.
1141 The first non-empty variable is used to find the matching server.
1142 </para>
1143
1144 <para>
1145 Example:
1146 <example>
1147 map $cookie_jsessionid $route_cookie {
1148 ~.+\.(?P&lt;route>\w+)$ $route;
1149 }
1150
1151 map $request_uri $route_uri {
1152 ~jsessionid=.+\.(?P&lt;route>\w+)$ $route;
1153 }
1154
1155 upstream backend {
1156 server backend1.example.com route=a;
1157 server backend2.example.com route=b;
1158
1159 sticky route $route_cookie $route_uri;
1160 }
1161 </example>
1162 Here, the route is taken from the “<literal>JSESSIONID</literal>” cookie
1163 if present in a request.
1164 Otherwise, the route from the URI is used.
1165 </para>
1166
1167 </tag-desc>
1168
1169 <tag-name id="sticky_learn"><literal>learn</literal></tag-name>
1170 <tag-desc>
1171 <para>
1172 When the <literal>learn</literal> method (1.7.1) is used, nginx
1173 analyzes upstream server responses and learns server-initiated sessions
1174 usually passed in an HTTP cookie.
1175 <example>
1176 upstream backend {
1177 server backend1.example.com:8080;
1178 server backend2.example.com:8081;
1179
1180 sticky learn
1181 create=$upstream_cookie_examplecookie
1182 lookup=$cookie_examplecookie
1183 zone=client_sessions:1m;
1184 }
1185 </example>
1186
1187 In the example, the upstream server creates a session by setting the
1188 cookie “<literal>EXAMPLECOOKIE</literal>” in the response.
1189 Further requests with this cookie will be passed to the same server.
1190 If the server cannot process the request, the new server is
1191 selected as if the client has not been bound yet.
1192 </para>
1193
1194 <para>
1195 The parameters <literal>create</literal> and <literal>lookup</literal>
1196 specify variables that indicate how new sessions are created and existing
1197 sessions are searched, respectively.
1198 Both parameters may be specified more than once, in which case the first
1199 non-empty variable is used.
1200 </para>
1201
1202 <para>
1203 Sessions are stored in a shared memory zone, whose <value>name</value> and
1204 <value>size</value> are configured by the <literal>zone</literal> parameter.
1205 One megabyte zone can store about 4000 sessions on the 64-bit platform.
1206 The sessions that are not accessed during the time specified by the
1207 <literal>timeout</literal> parameter get removed from the zone.
1208 By default, <literal>timeout</literal> is set to 10 minutes.
1209 </para>
1210
1211 <para id="sticky_learn_header">
1212 The <literal>header</literal> parameter (1.13.1) allows creating a session
1213 right after receiving response headers from the upstream server.
1214 </para>
1215
1216 <para id="sticky_learn_sync">
1217 The <literal>sync</literal> parameter (1.13.8) enables
1218 <link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">synchronization</link>
1219 of the shared memory zone.
1220 </para>
1221
1222 </tag-desc>
1223 </list>
1224 </para>
1225
1226 <para>
1227 <note>
1228 This directive is available as part of our
1229 <commercial_version>commercial subscription</commercial_version>.
1230 </note>
1231 </para>
1232
1233 </directive>
1234
1235
1236 <directive name="sticky_cookie_insert">
1237 <syntax><value>name</value>
1238 [<literal>expires=</literal><value>time</value>]
1239 [<literal>domain=</literal><value>domain</value>]
1240 [<literal>path=</literal><value>path</value>]</syntax>
1241 <default/>
1242 <context>upstream</context>
1243
1244 <para>
1245 This directive is obsolete since version 1.5.7.
1246 An equivalent
1247 <link id="sticky"/> directive with a new syntax should be used instead:
1248 <note>
1249 <literal>sticky cookie</literal> <value>name</value>
1250 [<literal>expires=</literal><value>time</value>]
1251 [<literal>domain=</literal><value>domain</value>]
1252 [<literal>path=</literal><value>path</value>];
1253 </note>
1254 </para> 530 </para>
1255 531
1256 </directive> 532 </directive>
1257 533
1258 </section> 534 </section>
1347 as for the variables that start with the 623 as for the variables that start with the
1348 “<link doc="ngx_http_core_module.xml" id="var_http_">$http_</link>” prefix. 624 “<link doc="ngx_http_core_module.xml" id="var_http_">$http_</link>” prefix.
1349 Only the header fields from the response of the last server are saved. 625 Only the header fields from the response of the last server are saved.
1350 </tag-desc> 626 </tag-desc>
1351 627
1352 <tag-name id="var_upstream_last_server_name"><var>$upstream_last_server_name</var></tag-name>
1353 <tag-desc>
1354 keeps the name of last selected upstream server (1.25.3);
1355 allows passing it
1356 <link doc="ngx_http_proxy_module.xml" id="proxy_ssl_server_name">through SNI</link>:
1357 <example>
1358 proxy_ssl_server_name on;
1359 proxy_ssl_name $upstream_last_server_name;
1360 </example>
1361
1362 <para>
1363 <note>
1364 This variable is available as part of our
1365 <commercial_version>commercial subscription</commercial_version>.
1366 </note>
1367 </para>
1368
1369 </tag-desc>
1370
1371 <tag-name id="var_upstream_queue_time"><var>$upstream_queue_time</var></tag-name> 628 <tag-name id="var_upstream_queue_time"><var>$upstream_queue_time</var></tag-name>
1372 <tag-desc> 629 <tag-desc>
1373 keeps time the request spent in the upstream <link id="queue">queue</link> 630 keeps time the request spent in the upstream <link id="queue">queue</link>
1374 (1.13.9); 631 (1.13.9);
1375 the time is kept in seconds with millisecond resolution. 632 the time is kept in seconds with millisecond resolution.