Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 953:aded7086e84f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Commercial version documentation.
author Ruslan Ermilov <ru@nginx.com>
date Thu, 01 Aug 2013 16:31:02 +0400
parents ba3d6ade3513
children 28d580f1eb63
comparison
equal deleted inserted replaced
952:417dc982362e 953:aded7086e84f
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="4"> 13 rev="5">
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
39 } 39 }
40 40
41 server { 41 server {
42 location / { 42 location / {
43 proxy_pass http://<emphasis>backend</emphasis>; 43 proxy_pass http://<emphasis>backend</emphasis>;
44 }
45 }
46 </example>
47 </para>
48
49 <para>
50 Dynamically configurable group,
51 available as part of our <commercial_version/> only:
52 <example>
53 upstream <emphasis>appservers</emphasis> {
54 zone appservers 64k;
55
56 server appserv1.example.com weight=5;
57 server appserv2.example.com:8080 fail_timeout=5s;
58 server 192.0.2.1 max_fails=3;
59
60 server reserve1.example.com:8080 backup;
61 server reserve2.example.com:8080 backup;
62 }
63
64 server {
65 location / {
66 proxy_pass http://<emphasis>appservers</emphasis>;
67 health_check;
68 }
69
70 location /upstream_conf {
71 upstream_conf;
72 allow 127.0.0.1;
73 deny all;
44 } 74 }
45 } 75 }
46 </example> 76 </example>
47 </para> 77 </para>
48 78
178 </para> 208 </para>
179 209
180 </directive> 210 </directive>
181 211
182 212
213 <directive name="zone">
214 <syntax><value>name</value> <value>size</value></syntax>
215 <default/>
216 <context>upstream</context>
217
218 <para>
219 Makes the group dynamically configurable.
220 Defines the <value>name</value> and <value>size</value> of a shared
221 memory zone that keeps group’s configuration and run-time state that are
222 shared between worker processes.
223 Such groups allow to add, remove, and modify servers at run time.
224 The configuration is accessible via a special location handled by
225 <link id="upstream_conf"/>.
226 </para>
227
228 <para>
229 <note>
230 This directive is available as part of our <commercial_version/> only.
231 </note>
232 </para>
233
234 </directive>
235
236
183 <directive name="ip_hash"> 237 <directive name="ip_hash">
184 <syntax/> 238 <syntax/>
185 <default/> 239 <default/>
186 <context>upstream</context> 240 <context>upstream</context>
187 241
358 Specifies that a group should use a load balancing method where a request 412 Specifies that a group should use a load balancing method where a request
359 is passed to the server with the least number of active connections, 413 is passed to the server with the least number of active connections,
360 taking into account weights of servers. 414 taking into account weights of servers.
361 If there are several such servers, they are tried using a 415 If there are several such servers, they are tried using a
362 weighted round-robin balancing method. 416 weighted round-robin balancing method.
417 </para>
418
419 </directive>
420
421
422 <directive name="health_check">
423 <syntax>
424 [<literal>interval=</literal><value>time</value>]
425 <!--
426 [<literal>jitter=</literal><value>time</value>]
427 -->
428 [<literal>fails=</literal><value>number</value>]
429 [<literal>passes=</literal><value>number</value>]
430 [<literal>uri=</literal><value>uri</value>]
431 [<literal>match=</literal><value>name</value>]</syntax>
432
433 <default/>
434 <context>location</context>
435
436 <para>
437 Enables periodic health checks of servers in a
438 <link id="upstream">group</link> referenced in the surrounding location.
439 </para>
440
441 <para>
442 The following optional parameters are supported:
443 <list type="bullet">
444
445 <listitem>
446 <literal>interval</literal>
447 sets interval between two consecutive health checks,
448 defaults to five seconds;
449 </listitem>
450
451 <listitem>
452 <literal>fails</literal>
453 sets a number of consecutive failed health checks
454 after which the server will be considered unhealthy,
455 defaults to 1;
456 </listitem>
457
458 <listitem>
459 <literal>passes</literal>
460 sets a number of consecutive passed health checks
461 after which the server will be considered healthy,
462 defaults to 1;
463 </listitem>
464
465 <listitem>
466 <literal>uri</literal>
467 defines the URI used in health check requests,
468 defaults to “<literal>/</literal>”;
469 </listitem>
470
471 <listitem>
472 <literal>match</literal>
473 names tests that a response should
474 pass in order for a health check to pass,
475 defaults to responses with status codes 2xx and 3xx.
476 </listitem>
477
478 </list>
479 </para>
480
481 <para>
482 For example,
483 <example>
484 location / {
485 proxy_pass http://backend;
486 health_check;
487 }
488 </example>
489 will send “<literal>/</literal>” requests to each
490 server in the group <literal>backend</literal> every five seconds.
491 If any communication errors or timeouts occur, or if a
492 proxied server responds with the status code other than
493 2xx or 3xx, health check will fail, and the server will
494 become unhealthy.
495 Client requests will not be passed to unhealthy servers.
496 </para>
497
498 <para>
499 Health checks can be configured to test status code of a response,
500 presence of certain header fields and their values,
501 and/or the body contents.
502 Tests are configured separately with the <link id="match"/> directives
503 and referenced in the <literal>match</literal> parameter.
504 For example,
505 <example>
506 http {
507 server {
508 ...
509 location / {
510 proxy_pass http://backend;
511 health_check match=welcome;
512 }
513 }
514
515 match welcome {
516 status 200;
517 header Content-Type = text/html;
518 body ~ "Welcome to nginx!";
519 }
520 }
521 </example>
522 tells that for a health check to pass, a response should succeed,
523 have status 200, content type “<literal>text/html</literal>”,
524 and contain “<literal>Welcome to nginx!</literal>” in the body.
525 </para>
526
527 <para>
528 It is required that a group be in <link id="zone">shared memory</link>.
529 </para>
530
531 <para>
532 If several health checks are defined for the same group of servers,
533 a single failure of any check will make the corresponding server
534 to become unhealthy.
535 </para>
536
537 <para>
538 <note>
539 This directive is available as part of our <commercial_version/> only.
540 </note>
541 </para>
542
543 </directive>
544
545
546 <directive name="match">
547 <syntax block="yes"><value>name</value></syntax>
548 <default/>
549 <context>http</context>
550
551 <para>
552 Defines the named test set used to verify responses to health check requests.
553 </para>
554
555 <para>
556 The following can be tested in a response:
557 <list type="tag">
558
559 <tag-name><literal>status 200;</literal></tag-name>
560 <tag-desc>status is 200</tag-desc>
561
562 <tag-name><literal>status ! 500;</literal></tag-name>
563 <tag-desc>status is not 500</tag-desc>
564
565 <tag-name><literal>status 200 204;</literal></tag-name>
566 <tag-desc>status is 200 or 204</tag-desc>
567
568 <tag-name><literal>status ! 301 302;</literal></tag-name>
569 <tag-desc>status is neither 301 nor 302</tag-desc>
570
571 <tag-name><literal>status 200-399;</literal></tag-name>
572 <tag-desc>status is in the 200..399 range</tag-desc>
573
574 <tag-name><literal>status ! 400-599;</literal></tag-name>
575 <tag-desc>status is not in the 400..599 range</tag-desc>
576
577 <tag-name><literal>status 301-303 307;</literal></tag-name>
578 <tag-desc>status is one of 301, 302, 303, or 307</tag-desc>
579
580 </list>
581
582 <list type="tag">
583
584 <tag-name><literal>header Content-Type = text/html;</literal></tag-name>
585 <tag-desc>
586 header contains <header>Content-Type</header>
587 with value <literal>text/html</literal>
588 </tag-desc>
589
590 <tag-name><literal>header Content-Type != text/html;</literal></tag-name>
591 <tag-desc>
592 header contains <header>Content-Type</header>
593 with value other than <literal>text/html</literal>
594 </tag-desc>
595
596 <tag-name><literal>header Connection ~ close;</literal></tag-name>
597 <tag-desc>
598 header contains <header>Connection</header>
599 with value matching regular expression <literal>close</literal>
600 </tag-desc>
601
602 <tag-name><literal>header Connection !~ close;</literal></tag-name>
603 <tag-desc>
604 header contains <header>Connection</header>
605 with value not matching regular expression <literal>close</literal>
606 </tag-desc>
607
608 <tag-name><literal>header Host;</literal></tag-name>
609 <tag-desc>header contains <header>Host</header></tag-desc>
610
611 <tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name>
612 <tag-desc>header lacks <header>X-Accel-Redirect</header></tag-desc>
613
614 </list>
615
616 <list type="tag">
617
618 <tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name>
619 <tag-desc>
620 body matches regular expression “<literal>Welcome to nginx!</literal>”
621 </tag-desc>
622
623 <tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name>
624 <tag-desc>
625 body does not match regular expression “<literal>Welcome to nginx!</literal>”
626 </tag-desc>
627
628 </list>
629 </para>
630
631 <para>
632 If several tests are specified,
633 the response matches only if it passes all tests.
634 <note>
635 Only the first 256k of body are examined.
636 </note>
637 </para>
638
639 <para>
640 Examples:
641 <example>
642 # status is 200, content type is "text/html",
643 # and body contains "Welcome to nginx!"
644 match welcome {
645 status 200;
646 header Content-Type = text/html;
647 body ~ "Welcome to nginx!";
648 }
649 </example>
650
651 <example>
652 # status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"
653 match not_redirect {
654 status ! 301-303 307;
655 header ! Refresh;
656 }
657 </example>
658
659 <example>
660 # status ok and not in maintenance mode
661 match server_ok {
662 status 200-399;
663 body !~ "maintenance mode";
664 }
665 </example>
666
667 </para>
668
669 <para>
670 <note>
671 This directive is available as part of our <commercial_version/> only.
672 </note>
673 </para>
674
675 </directive>
676
677
678 <directive name="sticky">
679 <syntax/>
680 <default/>
681 <context>upstream</context>
682
683 <para>
684 Enables session affinity support.
685 The session is an object that is used to uniquely identify and maintain the
686 state of a client during a given period of time.
687 If session affinity is enabled, a client’s requests are always passed to the
688 same server (in a group of servers) once a session has been created.
689 Method used to create and track sessions must be specified by a separate
690 directive, for example, <link id="sticky_cookie_insert"/>.
691 <example>
692 upstream backend {
693 server backend1.example.com;
694 server backend2.example.com;
695
696 sticky;
697 sticky_cookie_insert "sticky";
698 }
699
700 server {
701 location / {
702 proxy_pass http://backend;
703 }
704 }
705 </example>
706 The directive must be specified after the <link id="ip_hash"/> or the
707 <link id="least_conn"/> directives.
708 </para>
709
710 <para>
711 Requests are processed as follows with the session affinity enabled:
712 <list type="enum">
713
714 <listitem>
715 The lookup of session corresponding to request is performed.
716 If the session is found, server identification data is extracted from it.
717 This data is used by the server selection algorithm.
718 </listitem>
719
720 <listitem>
721 The server to process the request is chosen according to the configured
722 balancing method, server information from session and the real state of
723 servers in a group (up or down, failed, etc.).
724 </listitem>
725
726 <listitem>
727 The request is passed to the chosen server for processing.
728 If the chosen server does not match specified in the session
729 (due to being down, for example), the session is cleared
730 and the request is processed as it had no session.
731 </listitem>
732
733 <listitem>
734 The server returns the response.
735 </listitem>
736
737 <listitem>
738 If there was no session for the request, new session
739 is created and server identification data is stored in it.
740 </listitem>
741
742 </list>
743 </para>
744
745 <para>
746 <note>
747 This directive is available as part of our <commercial_version/> only.
748 </note>
749 </para>
750
751 </directive>
752
753
754 <directive name="sticky_cookie_insert">
755 <syntax><value>name</value>
756 [<literal>expires=</literal><value>time</value>]
757 [<literal>domain=</literal><value>host</value>]
758 [<literal>path=</literal><value>path</value>]</syntax>
759 <default/>
760 <context>upstream</context>
761
762 <para>
763 Enables and configures the session tracking method, based on keeping
764 session information in HTTP cookies.
765 The directive must be specified after the <link id="ip_hash"/> or the
766 <link id="least_conn"/> directives.
767 Example:
768 <example>
769 sticky_cookie_insert "srv_id" "expires=1h 7m" domain=example.com path=/;
770 </example>
771 The first parameter sets the name of the cookie to be inserted or inspected.
772 Additional parameters may be as follows:
773 <list type="tag">
774
775 <tag-name><literal>expires</literal></tag-name>
776 <tag-desc>
777 Sets a time during which a browser should keep the cookie.
778 The parameter “<literal>max</literal>” sets the time to
779 “<literal>31 Dec 2037 23:55:55 GMT</literal>”.
780 This is the maximum time understood by old browsers.
781 </tag-desc>
782
783 <tag-name><literal>domain</literal></tag-name>
784 <tag-desc>
785 Defines a domain for which the cookie is set.
786 </tag-desc>
787
788 <tag-name><literal>path</literal></tag-name>
789 <tag-desc>
790 Defines a path for which the cookie is set.
791 </tag-desc>
792
793 </list>
794 If some parameter is omitted, then the corresponding cookie field is not set.
795 </para>
796
797 <para>
798 <note>
799 This directive is available as part of our <commercial_version/> only.
800 </note>
801 </para>
802
803 </directive>
804
805
806 <directive name="sticky_log_requests">
807 <syntax><literal>debug</literal> |
808 <literal>info</literal> |
809 <literal>notice</literal> |
810 <literal>warn</literal> |
811 <literal>error</literal></syntax>
812 <default/>
813 <context>upstream</context>
814
815 <para>
816 Enables logging of session-related operations and sets the desired
817 logging level.
818 </para>
819
820 <para>
821 <note>
822 This directive is available as part of our <commercial_version/> only.
823 </note>
824 </para>
825
826 </directive>
827
828
829 <directive name="upstream_conf">
830 <syntax/>
831 <default/>
832 <context>location</context>
833
834 <para>
835 Turns on upstream configuration HTTP interface in a surrounding location.
836 Access to this location should be
837 <link doc="ngx_http_core_module.xml" id="satisfy">limited</link>.
838 </para>
839
840 <para>
841 Configuration commands allow to:
842 <list type="bullet">
843
844 <listitem>view all primary or backup servers in a group;</listitem>
845
846 <listitem>view an individual server;</listitem>
847
848 <listitem>modify an individual server;</listitem>
849
850 <listitem>add a new server (see note below);</listitem>
851
852 <listitem>remove an individual server.</listitem>
853
854 </list>
855 <note>
856 As noted in the <link id="server"/> directive, adding a server specified
857 as a domain name may result in several servers being added.
858 Since addresses in a group are not required to be unique, individual
859 servers in a group can be uniquely referenced to only by their ID.
860 IDs are assigned automatically and shown when viewing group configuration.
861 </note>
862 </para>
863
864 <para>
865 A command consists of parameters passed as request arguments, for example:
866 <example>
867 http://127.0.0.1/upstream_conf?upstream=appservers
868 </example>
869 </para>
870
871 <para>
872 The following parameters are supported:
873
874 <list type="tag" compact="no">
875
876 <tag-name>
877 <literal>upstream=</literal><value>name</value></tag-name>
878 <tag-desc>
879 Selects a group.
880 This parameter is mandatory.
881 </tag-desc>
882
883 <tag-name>
884 <literal>backup=</literal>
885 </tag-name>
886 <tag-desc>
887 If unset, selects primary servers in the group.
888 If set, selects backup servers in the group.
889 </tag-desc>
890
891 <tag-name>
892 <literal>id=</literal><value>number</value></tag-name>
893 <tag-desc>
894 Selects an individual primary or backup server in the group.
895 </tag-desc>
896
897 <tag-name>
898 <literal>remove=</literal></tag-name>
899 <tag-desc>
900 Removes an individual primary or backup server from the group.
901 </tag-desc>
902
903 <tag-name>
904 <literal>add=</literal></tag-name>
905 <tag-desc>
906 Adds a new primary or backup server to the group.
907 </tag-desc>
908
909 <tag-name>
910 <literal>server=</literal><value>address</value></tag-name>
911 <tag-desc>
912 Same as the “<literal>address</literal>” parameter
913 of the <link id="server"/> directive.
914 </tag-desc>
915
916 <tag-name>
917 <literal>weight=</literal><value>number</value></tag-name>
918 <tag-desc>
919 Same as the “<literal>weight</literal>” parameter
920 of the <link id="server"/> directive.
921 </tag-desc>
922
923 <tag-name>
924 <literal>max_fails=</literal><value>number</value></tag-name>
925 <tag-desc>
926 Same as the “<literal>max_fails</literal>” parameter
927 of the <link id="server"/> directive.
928 </tag-desc>
929
930 <tag-name>
931 <literal>fail_timeout=</literal><value>time</value></tag-name>
932 <tag-desc>
933 Same as the “<literal>fail_timeout</literal>” parameter
934 of the <link id="server"/> directive.
935 </tag-desc>
936
937 <tag-name>
938 <literal>down=</literal></tag-name>
939 <tag-desc>
940 Same as the “<literal>down</literal>” parameter
941 of the <link id="server"/> directive.
942 </tag-desc>
943
944 <tag-name>
945 <literal>up=</literal></tag-name>
946 <tag-desc>
947 The opposite of the “<literal>down</literal>” parameter
948 of the <link id="server"/> directive.
949 </tag-desc>
950
951 </list>
952
953 The first three parameters select a target the command applies to.
954 Without other parameters, configuration of the selected target
955 is shown.
956 </para>
957
958 <para>
959 For example, to view the primary servers in the group:
960 <example>
961 http://127.0.0.1/upstream_conf?upstream=appservers
962 </example>
963
964 To view the backup servers in the group:
965 <example>
966 http://127.0.0.1/upstream_conf?upstream=appservers&amp;backup=
967 </example>
968
969 To view an individual primary server in the group:
970 <example>
971 http://127.0.0.1/upstream_conf?upstream=appservers&amp;id=42
972 </example>
973
974 To view an individual backup server in the group:
975 <example>
976 http://127.0.0.1/upstream_conf?upstream=appservers&amp;backup=&amp;id=42
977 </example>
978 </para>
979
980 <para>
981 To add a new primary or backup server to the group,
982 its address should be specified in the “<literal>server=</literal>” parameter.
983 Without other parameters specified, a server will be added with other
984 parameters set to their default values (see the <link id="server"/> directive).
985 </para>
986
987 <para>
988 For example, to add a new primary server to the group:
989 <example>
990 http://127.0.0.1/upstream_conf?add=&amp;upstream=appservers&amp;server=127.0.0.1:8080
991 </example>
992
993 To add a new backup server to the group:
994 <example>
995 http://127.0.0.1/upstream_conf?add=&amp;upstream=appservers&amp;backup=&amp;server=127.0.0.1:8080
996 </example>
997
998 To add a new primary server to the group,
999 set its parameters to non-default values
1000 and mark it “<literal>down</literal>”:
1001 <example>
1002 http://127.0.0.1/upstream_conf?add=&amp;upstream=appservers&amp;server=127.0.0.1:8080&amp;weight=2&amp;max_fails=3&amp;fail_timeout=3s&amp;down=
1003 </example>
1004 </para>
1005
1006 <para>
1007 To remove an individual primary or backup server from the group,
1008 it should be selected with the <literal>id=</literal> parameter.
1009 </para>
1010
1011 <para>
1012 For example, to remove an individual primary server from the group:
1013 <example>
1014 http://127.0.0.1/upstream_conf?remove=&amp;upstream=appservers&amp;id=42
1015 </example>
1016
1017 To remove an individual backup server from the group:
1018 <example>
1019 http://127.0.0.1/upstream_conf?remove=&amp;upstream=appservers&amp;backup=&amp;id=42
1020 </example>
1021 </para>
1022
1023 <para>
1024 To modify an individual primary or backup server in the group,
1025 it should be selected with the <literal>id=</literal> parameter.
1026 </para>
1027
1028 <para>
1029 For example, to modify an individual primary server in the group
1030 by marking it “<literal>down</literal>”:
1031 <example>
1032 http://127.0.0.1/upstream_conf?upstream=appservers&amp;id=42&amp;down=
1033 </example>
1034
1035 To modify address of an individual backup server in the group:
1036 <example>
1037 http://127.0.0.1/upstream_conf?upstream=appservers&amp;backup=&amp;id=42&amp;server=192.0.2.3:8123
1038 </example>
1039
1040 To modify other parameters of an individual primary server in the group:
1041 <example>
1042 http://127.0.0.1/upstream_conf?upstream=appservers&amp;id=42&amp;max_fails=3&amp;weight=4
1043 </example>
1044
1045 </para>
1046
1047 <para>
1048 <note>
1049 This directive is available as part of our <commercial_version/> only.
1050 </note>
363 </para> 1051 </para>
364 1052
365 </directive> 1053 </directive>
366 1054
367 </section> 1055 </section>