Mercurial > hg > nginx-site
comparison 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 |
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<route>\w+)$ $route; | |
1149 } | |
1150 | |
1151 map $request_uri $route_uri { | |
1152 ~jsessionid=.+\.(?P<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. |