Mercurial > hg > nginx-site

comparison xml/ru/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="Модуль ngx_http_upstream_module" 10 <module name="Модуль ngx_http_upstream_module"
11 link="/ru/docs/http/ngx_http_upstream_module.html" 11 link="/ru/docs/http/ngx_http_upstream_module.html"
12 lang="ru" 12 lang="ru"
13 rev="88"> 13 rev="89">
14 14
15 <section id="summary"> 15 <section id="summary">
16 16
17 <para> 17 <para>
18 Модуль <literal>ngx_http_upstream_module</literal> 18 Модуль <literal>ngx_http_upstream_module</literal>
43 } 43 }
44 44
45 server { 45 server {
46 location / { 46 location / {
47 proxy_pass http://<emphasis>backend</emphasis>; 47 proxy_pass http://<emphasis>backend</emphasis>;
48 }
49 }
50 </example>
51 </para>
52
53 <para>
54 Динамически настраиваемая группа
55 с периодическими
56 <link doc="ngx_http_upstream_hc_module.xml">проверками работоспособности</link>
57 доступна как часть
58 <commercial_version>коммерческой подписки</commercial_version>:
59 <example>
60 resolver 10.0.0.1;
61
62 upstream <emphasis>dynamic</emphasis> {
63 zone upstream_dynamic 64k;
64
65 server backend1.example.com weight=5;
66 server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
67 server 192.0.2.1 max_fails=3;
68 server backend3.example.com resolve;
69 server backend4.example.com service=http resolve;
70
71 server backup1.example.com:8080 backup;
72 server backup2.example.com:8080 backup;
73 }
74
75 server {
76 location / {
77 proxy_pass http://<emphasis>dynamic</emphasis>;
78 health_check;
79 } 48 }
80 } 49 }
81 </example> 50 </example>
82 </para> 51 </para>
83 52
169 нескольких 138 нескольких
170 <link doc="../ngx_core_module.xml" id="worker_processes">рабочих процессах</link> 139 <link doc="../ngx_core_module.xml" id="worker_processes">рабочих процессах</link>
171 и <link id="zone">зоне разделяемой памяти</link>, 140 и <link id="zone">зоне разделяемой памяти</link>,
172 суммарное число активных и неактивных соединений с проксируемым сервером 141 суммарное число активных и неактивных соединений с проксируемым сервером
173 может превышать значение <literal>max_conns</literal>. 142 может превышать значение <literal>max_conns</literal>.
174 </note>
175 <note>
176 Начиная с версии 1.5.9 и до версии 1.11.5
177 этот параметр был доступен как часть
178 <commercial_version>коммерческой подписки</commercial_version>.
179 </note> 143 </note>
180 </tag-desc> 144 </tag-desc>
181 145
182 <tag-name id="max_fails"> 146 <tag-name id="max_fails">
183 <literal>max_fails</literal>=<value>число</value> 147 <literal>max_fails</literal>=<value>число</value>
240 204
241 </list> 205 </list>
242 </para> 206 </para>
243 207
244 <para> 208 <para>
245 Кроме того, 209 <note>
246 следующие параметры доступны как часть 210 Если в группе только один сервер,
247 <commercial_version>коммерческой подписки</commercial_version>: 211 параметры <literal>max_fails</literal> и <literal>fail_timeout</literal>
248 <list type="tag">
249
250 <tag-name id="resolve">
251 <literal>resolve</literal>
252 </tag-name>
253 <tag-desc>
254 отслеживает изменения IP-адресов, соответствующих доменному имени сервера,
255 и автоматически изменяет конфигурацию группы
256 без необходимости перезапуска nginx (1.5.12).
257 Группа должна находиться в <link id="zone">зоне разделяемой памяти</link>.
258 <para>
259 Для работы этого параметра
260 директива <literal>resolver</literal>
261 должна быть задана в блоке
262 <link doc="ngx_http_core_module.xml" id="resolver">http</link>
263 или в соответствующем блоке <link id="resolver">upstream</link>.
264 </para>
265 </tag-desc>
266
267 <tag-name id="route">
268 <literal>route</literal>=<value>строка</value>
269 </tag-name>
270 <tag-desc>
271 задаёт имя маршрута к серверу.
272 </tag-desc>
273
274 <tag-name id="service">
275 <literal>service</literal>=<value>имя</value>
276 </tag-name>
277 <tag-desc>
278 включает преобразование
279 <link url="https://datatracker.ietf.org/doc/html/rfc2782">SRV</link>-записей
280 DNS и задаёт <value>имя</value> сервиса (1.9.13).
281 Для работы параметра необходимо указать
282 параметр <link id="resolve"/> для сервера
283 и не указывать порт сервера.
284 <para>
285 Если имя сервиса не содержит точку (“<literal>.</literal>”), то
286 имя составляется в соответствии с
287 <link url="https://datatracker.ietf.org/doc/html/rfc2782">RFC</link>
288 и в префикс службы добавляется протокол TCP.
289 Например, для получения
290 SRV-записи <literal>_http._tcp.backend.example.com</literal>
291 необходимо указать директиву:
292 <example>
293 server backend.example.com service=http resolve;
294 </example>
295 Если имя сервиса содержит одну и более точек, то имя составляется
296 при помощи соединения префикса службы и имени сервера.
297 Например, для получения SRV-записей
298 <literal>_http._tcp.backend.example.com</literal>
299 и <literal>server1.backend.example.com</literal>
300 необходимо указать директивы:
301 <example>
302 server backend.example.com service=_http._tcp resolve;
303 server example.com service=server1.backend resolve;
304 </example>
305 </para>
306
307 <para>
308 SRV-записи с наивысшим приоритетом
309 (записи с одинаковым наименьшим значением приоритета)
310 преобразуются в основные серверы,
311 остальные SRV-записи преобразуются в запасные серверы.
312 Если в конфигурации сервера указан параметр <link id="backup"/>,
313 высокоприоритетные SRV-записи преобразуются в запасные серверы,
314 остальные SRV-записи игнорируются.
315 </para>
316 </tag-desc>
317
318 <tag-name id="slow_start">
319 <literal>slow_start</literal>=<value>время</value>
320 </tag-name>
321 <tag-desc>
322 задаёт <value>время</value>, в течение которого вес сервера
323 восстановится от нуля до своего номинального значения в ситуации, когда
324 неработоспособный (unhealthy) сервер вновь становится работоспособным
325 (<link doc="ngx_http_upstream_hc_module.xml" id="health_check">healthy</link>)
326 или когда сервер становится доступным по прошествии времени,
327 в течение которого он считался <link id="fail_timeout">недоступным</link>.
328 Значение по умолчанию равно нулю и означает, что медленный старт выключен.
329 <note>
330 Параметр нельзя использовать совместно с
331 методами балансировки нагрузки
332 <link id="hash"/>, <link id="ip_hash"/> и <link id="random"/>.
333 </note>
334 </tag-desc>
335
336 <tag-name id="drain">
337 <literal>drain</literal>
338 </tag-name>
339 <tag-desc>
340 переводит сервер в режим “draining” (1.13.6).
341 В этом режиме на сервер будут проксироваться только
342 <link id="sticky">привязанные</link> к нему запросы.
343 <note>
344 До версии 1.13.6
345 параметр мог быть изменён только при помощи
346 модуля <link doc="ngx_http_api_module.xml">API</link>.
347 </note>
348 </tag-desc>
349
350 </list>
351 </para>
352
353 <para>
354 <note>
355 Если в группе только один сервер, параметры <literal>max_fails</literal>,
356 <literal>fail_timeout</literal> и <literal>slow_start</literal>
357 игнорируются и такой сервер никогда не будет считаться недоступным. 212 игнорируются и такой сервер никогда не будет считаться недоступным.
358 </note> 213 </note>
359 </para> 214 </para>
360 215
361 </directive> 216 </directive>
371 Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти, 226 Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти,
372 в которой хранятся конфигурация группы и её рабочее состояние, 227 в которой хранятся конфигурация группы и её рабочее состояние,
373 разделяемые между рабочими процессами. 228 разделяемые между рабочими процессами.
374 В одной и той же зоне могут быть сразу несколько групп. 229 В одной и той же зоне могут быть сразу несколько групп.
375 В этом случае достаточно указать <value>размер</value> только один раз. 230 В этом случае достаточно указать <value>размер</value> только один раз.
376 </para>
377
378 <para>
379 Дополнительно, как часть
380 <commercial_version>коммерческой подписки</commercial_version>,
381 в таких группах для изменения состава группы
382 или настроек отдельных серверов
383 нет необходимости перезапускать nginx.
384 Конфигурация доступна через
385 модуль <link doc="ngx_http_api_module.xml">API</link> (1.13.3).
386 <note>
387 До версии 1.13.3
388 конфигурация была доступна только через специальный location,
389 в котором указана директива
390 <link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf"/>.
391 </note>
392 </para>
393
394 </directive>
395
396
397 <directive name="state">
398 <syntax><value>файл</value></syntax>
399 <default/>
400 <context>upstream</context>
401 <appeared-in>1.9.7</appeared-in>
402
403 <para>
404 Задаёт <value>файл</value>, в котором хранится состояние
405 динамически настраиваемой группы.
406 </para>
407
408 <para>
409 Примеры:
410 <example>
411 state /var/lib/nginx/state/servers.conf; # путь для Linux
412 state /var/db/nginx/state/servers.conf; # путь для FreeBSD
413 </example>
414 </para>
415
416 <para>
417 В данный момент состояние ограничено списком серверов с их параметрами.
418 Файл читается при парсинге конфигурации и обновляется каждый раз при
419 <link doc="ngx_http_api_module.xml" id="http_upstreams_http_upstream_name_servers_">изменении</link>
420 конфигурации группы.
421 Изменение содержимого файла напрямую не рекомендуется.
422 Директиву нельзя использовать
423 совместно с директивой <link id="server"/>.
424 </para>
425
426 <para>
427 <note>
428 Изменения, совершённые в момент
429 <link doc="../control.xml" id="reconfiguration">перезагрузки конфигурации</link>
430 или <link doc="../control.xml" id="upgrade">обновления бинарного файла</link>,
431 могут быть потеряны.
432 </note>
433 </para>
434
435 <para>
436 <note>
437 Эта директива доступна как часть
438 <commercial_version>коммерческой подписки</commercial_version>.
439 </note>
440 </para> 231 </para>
441 232
442 </directive> 233 </directive>
443 234
444 235
702 </para> 493 </para>
703 494
704 </directive> 495 </directive>
705 496
706 497
707 <directive name="ntlm">
708 <syntax/>
709 <default/>
710 <context>upstream</context>
711 <appeared-in>1.9.2</appeared-in>
712
713 <para>
714 Позволяет проксировать запросы с
715 <link url="https://en.wikipedia.org/wiki/Integrated_Windows_Authentication">проверкой
716 подлинности NTLM</link>.
717 Соединение с сервером группы привязывается к клиентскому соединению
718 как только клиент отправляет запрос, в заголовке которого есть поле
719 <header>Authorization</header> со значением,
720 начинающимся с “<literal>Negotiate</literal>” или “<literal>NTLM</literal>”.
721 Последующие запросы клиента будут проксироваться через это же соединение
722 с сервером группы,
723 сохраняя контекст аутентификации.
724 </para>
725
726 <para>
727 Для работы проверки подлинности NTLM
728 необходимо разрешить постоянные соединения с серверами группы.
729 Директиву <link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/>
730 следует установить в “<literal>1.1</literal>”,
731 а поле заголовка <header>Connection</header> — очистить:
732 <example>
733 upstream http_backend {
734 server 127.0.0.1:8080;
735
736 ntlm;
737 }
738
739 server {
740 ...
741
742 location /http/ {
743 proxy_pass http://http_backend;
744 proxy_http_version 1.1;
745 proxy_set_header Connection "";
746 ...
747 }
748 }
749 </example>
750 </para>
751
752 <para>
753 <note>
754 При использовании методов балансировки нагрузки, отличных
755 от стандартного round-robin, следует активировать их до
756 директивы <literal>ntlm</literal>.
757 </note>
758 </para>
759
760 <para>
761 <note>
762 Эта директива доступна как часть
763 <commercial_version>коммерческой подписки</commercial_version>.
764 </note>
765 </para>
766
767 </directive>
768
769
770 <directive name="least_conn"> 498 <directive name="least_conn">
771 <syntax/> 499 <syntax/>
772 <default/> 500 <default/>
773 <context>upstream</context> 501 <context>upstream</context>
774 <appeared-in>1.3.1</appeared-in> 502 <appeared-in>1.3.1</appeared-in>
778 Задаёт для группы метод балансировки нагрузки, при котором запрос 506 Задаёт для группы метод балансировки нагрузки, при котором запрос
779 передаётся серверу с наименьшим числом активных соединений, 507 передаётся серверу с наименьшим числом активных соединений,
780 с учётом весов серверов. 508 с учётом весов серверов.
781 Если подходит сразу несколько серверов, они выбираются циклически 509 Если подходит сразу несколько серверов, они выбираются циклически
782 (в режиме round-robin) с учётом их весов. 510 (в режиме round-robin) с учётом их весов.
783 </para>
784
785 </directive>
786
787
788 <directive name="least_time">
789 <syntax>
790 <literal>header</literal> |
791 <literal>last_byte</literal>
792 [<literal>inflight</literal>]</syntax>
793 <default/>
794 <context>upstream</context>
795 <appeared-in>1.7.10</appeared-in>
796
797 <para>
798 Задаёт для группы метод балансировки нагрузки, при котором запрос
799 передаётся серверу с наименьшими средним временем ответа и
800 числом активных соединений с учётом весов серверов.
801 Если подходит сразу несколько серверов, то они выбираются циклически
802 (в режиме round-robin) с учётом их весов.
803 </para>
804
805 <para>
806 Если указан параметр <literal>header</literal>,
807 то учитывается время получения
808 <link id="var_upstream_header_time">заголовка ответа</link>.
809 Если указан параметр <literal>last_byte</literal>, то учитывается
810 время получения <link id="var_upstream_response_time">всего ответа</link>.
811 Если указан параметр <literal>inflight</literal> (1.11.6),
812 то также учитываются незавершённые запросы.
813 <note>
814 До версии 1.11.6 незавершённые запросы учитывались по умолчанию.
815 </note>
816 </para>
817
818 <para>
819 <note>
820 Эта директива доступна как часть
821 <commercial_version>коммерческой подписки</commercial_version>.
822 </note>
823 </para>
824
825 </directive>
826
827
828 <directive name="queue">
829 <syntax>
830 <value>число</value>
831 [<literal>timeout</literal>=<value>время</value>]</syntax>
832 <default/>
833 <context>upstream</context>
834 <appeared-in>1.5.12</appeared-in>
835
836 <para>
837 Если при обработке запроса невозможно сразу выбрать сервер группы, то
838 запрос будет помещён в очередь.
839 Директива задаёт максимальное <value>число</value> запросов,
840 которые могут одновременно находиться в очереди.
841 Если очередь переполнена
842 или за время, задаваемое параметром <literal>timeout</literal>,
843 так и не удастся выбрать сервер для передачи ему запроса,
844 клиенту будет возвращена ошибка
845 <http-status code="502" text="Bad Gateway"/>.
846 </para>
847
848 <para>
849 По умолчанию параметр <literal>timeout</literal> равен 60 секундам.
850 </para>
851
852 <para>
853 <note>
854 При использовании методов балансировки нагрузки, отличных
855 от стандартного round-robin, следует активировать их до
856 директивы <literal>queue</literal>.
857 </note>
858
859 <note>
860 Эта директива доступна как часть
861 <commercial_version>коммерческой подписки</commercial_version>.
862 </note>
863 </para> 511 </para>
864 512
865 </directive> 513 </directive>
866 514
867 515
884 сервера, из которых выбирает сервер, 532 сервера, из которых выбирает сервер,
885 используя указанный <literal>метод</literal>. 533 используя указанный <literal>метод</literal>.
886 Методом по умолчанию является <literal>least_conn</literal>, 534 Методом по умолчанию является <literal>least_conn</literal>,
887 при котором запрос передаётся на сервер 535 при котором запрос передаётся на сервер
888 с наименьшим количеством активных соединений. 536 с наименьшим количеством активных соединений.
889 </para>
890
891 <para id="random_least_time">
892 Если указан метод <literal>least_time</literal>, то запрос передаётся серверу
893 с наименьшими средним временем ответа и числом активных соединений.
894 Если указан <literal>least_time=header</literal>, то учитывается
895 время получения <link id="var_upstream_header_time">заголовка ответа</link>.
896 Если указан <literal>least_time=last_byte</literal>, то учитывается
897 время получения <link id="var_upstream_response_time">всего ответа</link>.
898 <note>
899 Метод <literal>least_time</literal> доступен как часть
900 <commercial_version>коммерческой подписки</commercial_version>.
901 </note>
902 </para>
903
904 </directive>
905
906
907 <directive name="resolver">
908 <syntax>
909 <value>адрес</value> ...
910 [<literal>valid</literal>=<value>время</value>]
911 [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>]
912 [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]
913 [<literal>status_zone</literal>=<value>зона</value>]</syntax>
914 <default/>
915 <context>upstream</context>
916 <appeared-in>1.17.5</appeared-in>
917
918 <para>
919 Задаёт серверы DNS, используемые для преобразования имён вышестоящих серверов
920 в адреса, например:
921 <example>
922 resolver 127.0.0.1 [::1]:5353;
923 </example>
924 Адрес может быть указан в виде доменного имени или IP-адреса,
925 и необязательного порта.
926 Если порт не указан, используется порт 53.
927 Серверы DNS опрашиваются циклически.
928 </para>
929
930 <para id="resolver_ipv6">
931 По умолчанию nginx будет искать как IPv4-, так и IPv6-адреса
932 при преобразовании имён в адреса.
933 Если поиск IPv4- или IPv6-адресов нежелателен,
934 можно указать параметр <literal>ipv4=off</literal> (1.23.1) или
935 <literal>ipv6=off</literal>.
936 </para>
937
938 <para id="resolver_valid">
939 По умолчанию nginx кэширует ответы, используя значение TTL из ответа.
940 Необязательный параметр <literal>valid</literal> позволяет это
941 переопределить:
942 <example>
943 resolver 127.0.0.1 [::1]:5353 valid=30s;
944 </example>
945 <note>
946 Для предотвращения DNS-спуфинга рекомендуется
947 использовать DNS-серверы в защищённой доверенной локальной сети.
948 </note>
949 </para>
950
951 <para id="resolver_status_zone">
952 Необязательный параметр <literal>status_zone</literal>
953 включает
954 <link doc="ngx_http_api_module.xml" id="resolvers_">сбор информации</link>
955 о запросах и ответах сервера DNS
956 в указанной <value>зоне</value>.
957 </para>
958
959 <para>
960 <note>
961 Эта директива доступна как часть
962 <commercial_version>коммерческой подписки</commercial_version>.
963 </note>
964 </para>
965
966 </directive>
967
968
969 <directive name="resolver_timeout">
970 <syntax><value>время</value></syntax>
971 <default>30s</default>
972 <context>upstream</context>
973 <appeared-in>1.17.5</appeared-in>
974
975 <para>
976 Задаёт таймаут для преобразования имени в адрес, например:
977 <example>
978 resolver_timeout 5s;
979 </example>
980 </para>
981
982 <para>
983 <note>
984 Эта директива доступна как часть
985 <commercial_version>коммерческой подписки</commercial_version>.
986 </note>
987 </para>
988
989 </directive>
990
991
992 <directive name="sticky">
993 <syntax>
994 <literal>cookie</literal> <value>имя</value>
995 [<literal>expires=</literal><value>время</value>]
996 [<literal>domain=</literal><value>домен</value>]
997 [<literal>httponly</literal>]
998 [<literal>samesite=</literal><literal>strict</literal>|<literal>lax</literal>|<literal>none</literal>|<value>$переменная</value>]
999 [<literal>secure</literal>]
1000 [<literal>path=</literal><value>путь</value>]</syntax>
1001 <syntax>
1002 <literal>route</literal> <value>$переменная</value> ...</syntax>
1003 <syntax>
1004 <literal>learn</literal>
1005 <literal>create=</literal><value>$переменная</value>
1006 <literal>lookup=</literal><value>$переменная</value>
1007 <literal>zone=</literal><value>имя</value>:<value>размер</value>
1008 [<literal>timeout=</literal><value>время</value>]
1009 [<literal>header</literal>]
1010 [<literal>sync</literal>]</syntax>
1011 <default/>
1012 <context>upstream</context>
1013 <appeared-in>1.5.7</appeared-in>
1014
1015 <para>
1016 Включает режим привязки сеансов, в котором запросы клиента
1017 будут передаваться на один и тот же сервер группы.
1018 Доступны три метода:
1019 <list type="tag">
1020 <tag-name id="sticky_cookie"><literal>cookie</literal></tag-name>
1021 <tag-desc>
1022
1023 <para>
1024 При использовании метода <literal>cookie</literal> информация о
1025 назначенном сервере передаётся в HTTP-куке:
1026 <example>
1027 upstream backend {
1028 server backend1.example.com;
1029 server backend2.example.com;
1030
1031 sticky cookie srv_id expires=1h domain=.example.com path=/;
1032 }
1033 </example>
1034 </para>
1035
1036 <para>
1037 Запрос от клиента, ещё не привязанного к определённому серверу,
1038 передаётся на сервер, выбранный согласно настроенному методу балансировки.
1039 Дальнейшие запросы от этого клиента передаются на тот же сервер.
1040 Если назначенный сервер не может обработать запрос, выбирается новый
1041 сервер как если бы клиент не имел привязки к серверу.
1042
1043 <note>
1044 Так как любой метод балансировки пытается равномерно распределить нагрузку,
1045 учитывая уже привязанные запросы,
1046 сервер с наибольшим количеством привязанных запросов
1047 имеет меньшую вероятность получить новые, не привязанные запросы.
1048 </note>
1049 </para>
1050
1051 <para>
1052 Первый параметр задаёт имя куки, которую необходимо установить или проверить.
1053 Значением куки является MD5-хэш IP-адреса и порта
1054 (или пути UNIX-сокета) в шестнадцатеричном виде.
1055 Однако если указан параметр “<literal>route</literal>”
1056 директивы <link id="server"/>, то значением куки будет
1057 значение параметра “<literal>route</literal>”:
1058 <example>
1059 upstream backend {
1060 server backend1.example.com route=<emphasis>a</emphasis>;
1061 server backend2.example.com route=<emphasis>b</emphasis>;
1062
1063 sticky cookie srv_id expires=1h domain=.example.com path=/;
1064 }
1065 </example>
1066 В этом случае значение куки “<literal>srv_id</literal>” будет
1067 или <value>a</value>, или <value>b</value>.
1068 </para>
1069
1070 <para>
1071 Дополнительные параметры могут быть следующими:
1072 <list type="tag">
1073
1074 <tag-name><literal>expires=</literal><value>время</value></tag-name>
1075 <tag-desc>
1076 Задаёт <value>время</value>, в течение которого браузеру необходимо хранить куку.
1077 Специальное значение <literal>max</literal> устанавливает срок хранения куки до
1078 31 декабря 2037 года 23:55:55 GMT.
1079 Если параметр не указан, то время действия куки ограничивается сессией браузера.
1080 </tag-desc>
1081
1082 <tag-name><literal>domain=</literal><value>домен</value></tag-name>
1083 <tag-desc>
1084 Задаёт <value>домен</value>, для которого устанавливается кука.
1085 В значении параметра можно использовать переменные (1.11.5).
1086 </tag-desc>
1087
1088 <tag-name><literal>httponly</literal></tag-name>
1089 <tag-desc>
1090 Добавляет атрибут <literal>HttpOnly</literal> к куке (1.7.11).
1091 </tag-desc>
1092
1093 <tag-name id="sticky_samesite"><literal>samesite=</literal><literal>strict</literal> |
1094 <literal>lax</literal> | <literal>none</literal> | <literal>$переменная</literal></tag-name>
1095 <tag-desc>
1096 Добавляет атрибут <literal>SameSite</literal> (1.19.4) к куке
1097 с одним из следующих значений:
1098 <literal>Strict</literal>,
1099 <literal>Lax</literal>,
1100 <literal>None</literal> или
1101 при помощи переменных (1.23.3).
1102 В последнем случае если переменная имеет пустое значение,
1103 то атрибут <literal>SameSite</literal> не будет добавлен к куке,
1104 если значение переменной равно
1105 <literal>Strict</literal>,
1106 <literal>Lax</literal> или
1107 <literal>None</literal>,
1108 то атрибуту будет назначено соответствующее значение,
1109 иначе атрибуту будет назначено значение <literal>Strict</literal>.
1110 </tag-desc>
1111
1112 <tag-name><literal>secure</literal></tag-name>
1113 <tag-desc>
1114 Добавляет атрибут <literal>Secure</literal> к куке (1.7.11).
1115 </tag-desc>
1116
1117 <tag-name><literal>path=</literal><value>путь</value></tag-name>
1118 <tag-desc>
1119 Задаёт <value>путь</value>, для которого устанавливается кука.
1120 </tag-desc>
1121
1122 </list>
1123 Если пропущен тот или иной параметр, то соответствующего поля в куке не будет.
1124 </para>
1125 </tag-desc>
1126
1127 <tag-name id="sticky_route"><literal>route</literal></tag-name>
1128 <tag-desc>
1129
1130 <para>
1131 При использовании метода <literal>route</literal> проксируемый сервер назначает
1132 клиенту маршрут по получении первого запроса.
1133 Все последующие запросы от этого клиента будут содержать информацию о
1134 маршруте в куке или URI.
1135 Эта информация сравнивается с параметром “<literal>route</literal>” директивы
1136 <link id="server"/> для идентификации сервера, на который
1137 следует проксировать запрос.
1138 Если параметр “<literal>route</literal>” не задан, то именем маршрута
1139 будет являться MD5-хэш IP-адреса и порта
1140 (или пути UNIX-сокета) в шестнадцатеричном виде.
1141 Если назначенный сервер не может обработать запрос, выбирается новый сервер
1142 согласно настроенному методу балансировки как если бы в запросе не было
1143 информации о маршруте.
1144 </para>
1145
1146 <para>
1147 Параметры метода <literal>route</literal> задают переменные, которые
1148 могут содержать информацию о маршруте.
1149 Первая непустая переменная используется для поиска соответствующего сервера.
1150 </para>
1151
1152 <para>
1153 Пример:
1154 <example>
1155 map $cookie_jsessionid $route_cookie {
1156 ~.+\.(?P&lt;route>\w+)$ $route;
1157 }
1158
1159 map $request_uri $route_uri {
1160 ~jsessionid=.+\.(?P&lt;route>\w+)$ $route;
1161 }
1162
1163 upstream backend {
1164 server backend1.example.com route=a;
1165 server backend2.example.com route=b;
1166
1167 sticky route $route_cookie $route_uri;
1168 }
1169 </example>
1170 В этом примере маршрут берётся из куки “<literal>JSESSIONID</literal>”,
1171 если она присутствует в запросе.
1172 В противном случае используется маршрут из URI.
1173 </para>
1174
1175 </tag-desc>
1176
1177 <tag-name id="sticky_learn"><literal>learn</literal></tag-name>
1178 <tag-desc>
1179 <para>
1180 При использовании метода <literal>learn</literal> (1.7.1) nginx
1181 анализирует ответы от вышестоящего сервера и запоминает
1182 начатые им сессии, которые обычно передаются в HTTP-куке.
1183 <example>
1184 upstream backend {
1185 server backend1.example.com:8080;
1186 server backend2.example.com:8081;
1187
1188 sticky learn
1189 create=$upstream_cookie_examplecookie
1190 lookup=$cookie_examplecookie
1191 zone=client_sessions:1m;
1192 }
1193 </example>
1194
1195 В примере выше сервер группы создаёт сессию путём установки
1196 куки “<literal>EXAMPLECOOKIE</literal>” в своём ответе.
1197 Последующие запросы с этой кукой будут передаваться на этот же сервер.
1198 Если сервер не может обработать запрос, выбирается новый
1199 сервер как если бы клиент не имел привязки к серверу.
1200 </para>
1201
1202 <para>
1203 Параметры <literal>create</literal> и <literal>lookup</literal>
1204 задают переменные, в которых соответственно указывается способ
1205 создания новых и поиска существующих сессий.
1206 Оба параметра могут быть указаны больше одного раза
1207 (в этом случае используется первая непустая переменная).
1208 </para>
1209
1210 <para>
1211 Сессии хранятся в зоне разделяемой памяти, <value>имя</value> и
1212 <value>размер</value> которой задаются параметром <literal>zone</literal>.
1213 Зоны размером в 1 мегабайт достаточно для хранения около 4 тысяч сессий
1214 на 64-битной платформе.
1215 Сессии, к которым не было обращений в течение времени, заданного параметром
1216 <literal>timeout</literal>, удаляются из зоны.
1217 По умолчанию <literal>timeout</literal> равен 10 минутам.
1218 </para>
1219
1220 <para id="sticky_learn_header">
1221 Параметр <literal>header</literal> (1.13.1) позволяет создавать сессию
1222 сразу после получения заголовков ответа от сервера группы.
1223 </para>
1224
1225 <para id="sticky_learn_sync">
1226 Параметр <literal>sync</literal> (1.13.8) разрешает
1227 <link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">синхронизацию</link>
1228 данной зоны разделяемой памяти.
1229 </para>
1230
1231 </tag-desc>
1232 </list>
1233 </para>
1234
1235 <para>
1236 <note>
1237 Эта директива доступна как часть
1238 <commercial_version>коммерческой подписки</commercial_version>.
1239 </note>
1240 </para>
1241
1242 </directive>
1243
1244
1245 <directive name="sticky_cookie_insert">
1246 <syntax><value>имя</value>
1247 [<literal>expires=</literal><value>время</value>]
1248 [<literal>domain=</literal><value>домен</value>]
1249 [<literal>path=</literal><value>путь</value>]</syntax>
1250 <default/>
1251 <context>upstream</context>
1252
1253 <para>
1254 Эта директива устарела начиная с версии 1.5.7.
1255 Вместо неё следует использовать аналогичную директиву
1256 <link id="sticky"/> с изменённым синтаксисом:
1257 <note>
1258 <literal>sticky cookie</literal> <value>имя</value>
1259 [<literal>expires=</literal><value>время</value>]
1260 [<literal>domain=</literal><value>домен</value>]
1261 [<literal>path=</literal><value>путь</value>];
1262 </note>
1263 </para> 537 </para>
1264 538
1265 </directive> 539 </directive>
1266 540
1267 </section> 541 </section>
1358 “<link doc="ngx_http_core_module.xml" id="var_http_">$http_</link>”. 632 “<link doc="ngx_http_core_module.xml" id="var_http_">$http_</link>”.
1359 Необходимо иметь в виду, что поля заголовка запоминаются только из ответа 633 Необходимо иметь в виду, что поля заголовка запоминаются только из ответа
1360 последнего сервера. 634 последнего сервера.
1361 </tag-desc> 635 </tag-desc>
1362 636
1363 <tag-name id="var_upstream_last_server_name"><var>$upstream_last_server_name</var></tag-name>
1364 <tag-desc>
1365 хранит имя последнего выбранного сервера группы (1.25.3);
1366 позволяет передать его
1367 <link doc="ngx_http_proxy_module.xml" id="proxy_ssl_server_name">через SNI</link>:
1368 <example>
1369 proxy_ssl_server_name on;
1370 proxy_ssl_name $upstream_last_server_name;
1371 </example>
1372
1373 <para>
1374 <note>
1375 Эта переменная доступна как часть
1376 <commercial_version>коммерческой подписки</commercial_version>.
1377 </note>
1378 </para>
1379
1380 </tag-desc>
1381
1382 <tag-name id="var_upstream_queue_time"><var>$upstream_queue_time</var></tag-name> 637 <tag-name id="var_upstream_queue_time"><var>$upstream_queue_time</var></tag-name>
1383 <tag-desc> 638 <tag-desc>
1384 хранит время, проведённое запросом в <link id="queue">очереди</link> 639 хранит время, проведённое запросом в <link id="queue">очереди</link>
1385 (1.13.9); 640 (1.13.9);
1386 время хранится в секундах с точностью до миллисекунд. 641 время хранится в секундах с точностью до миллисекунд.