Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 1259:954dcc02cb63

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Upstream: "session learn" sticky method and upstream_conf changes.
author Ruslan Ermilov <ru@nginx.com>
date Thu, 17 Jul 2014 18:39:52 +0400
parents 2246339a6a93
children 5e45198fa991
comparison
equal deleted inserted replaced
1258:700487454cf2 1259:954dcc02cb63
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="27"> 13 rev="28">
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
51 <para> 51 <para>
52 Dynamically configurable group, 52 Dynamically configurable group,
53 available as part of our 53 available as part of our
54 <commercial_version>commercial subscription</commercial_version>: 54 <commercial_version>commercial subscription</commercial_version>:
55 <example> 55 <example>
56 upstream <emphasis>appservers</emphasis> { 56 upstream <emphasis>dynamic</emphasis> {
57 zone appservers 64k; 57 zone upstream_dynamic 64k;
58 58
59 server appserv1.example.com weight=5; 59 server backend1.example.com weight=5;
60 server appserv2.example.com:8080 fail_timeout=5s slow_start=30s; 60 server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
61 server 192.0.2.1 max_fails=3; 61 server 192.0.2.1 max_fails=3;
62 62
63 server reserve1.example.com:8080 backup; 63 server backup1.example.com:8080 backup;
64 server reserve2.example.com:8080 backup; 64 server backup2.example.com:8080 backup;
65 } 65 }
66 66
67 server { 67 server {
68 location / { 68 location / {
69 proxy_pass http://<emphasis>appservers</emphasis>; 69 proxy_pass http://<emphasis>dynamic</emphasis>;
70 health_check; 70 health_check;
71 } 71 }
72 72
73 location /upstream_conf { 73 location /upstream_conf {
74 upstream_conf; 74 upstream_conf;
824 824
825 </directive> 825 </directive>
826 826
827 827
828 <directive name="sticky"> 828 <directive name="sticky">
829 <syntax><literal>cookie</literal> <value>name</value> 829 <syntax>
830 [<literal>expires=</literal><value>time</value>] 830 <literal>cookie</literal> <value>name</value>
831 [<literal>domain=</literal><value>domain</value>] 831 [<literal>expires=</literal><value>time</value>]
832 [<literal>path=</literal><value>path</value>]</syntax> 832 [<literal>domain=</literal><value>domain</value>]
833 <syntax><literal>route</literal> <value>variable</value> ...</syntax> 833 [<literal>path=</literal><value>path</value>]</syntax>
834 <syntax>
835 <literal>route</literal> <value>$variable</value> ...</syntax>
836 <syntax>
837 <literal>learn</literal>
838 <literal>create=</literal><value>$variable</value>
839 <literal>lookup=</literal><value>$variable</value>
840 <literal>zone=</literal><value>name</value>:<value>size</value>
841 [<literal>timeout=</literal><value>time</value>]</syntax>
834 <default/> 842 <default/>
835 <context>upstream</context> 843 <context>upstream</context>
836 <appeared-in>1.5.7</appeared-in> 844 <appeared-in>1.5.7</appeared-in>
837 845
838 <para> 846 <para>
839 Enables session affinity, which causes requests from the same client to be 847 Enables session affinity, which causes requests from the same client to be
840 passed to the same server in a group of servers. 848 passed to the same server in a group of servers.
841 Two methods are available, 849 Three methods are available:
842 <literal>cookie</literal> and <literal>route</literal>. 850 <list type="tag">
843 </para> 851 <tag-name id="sticky_cookie"><literal>cookie</literal></tag-name>
852 <tag-desc>
844 853
845 <para> 854 <para>
846 When the <literal>cookie</literal> method is used, information about the 855 When the <literal>cookie</literal> method is used, information about the
847 designated server is passed in an HTTP cookie: 856 designated server is passed in an HTTP cookie generated by nginx:
848 <example> 857 <example>
849 upstream backend { 858 upstream backend {
850 server backend1.example.com; 859 server backend1.example.com;
851 server backend2.example.com; 860 server backend2.example.com;
852 861
856 </para> 865 </para>
857 866
858 <para> 867 <para>
859 A request that comes from a client not yet bound to a particular server 868 A request that comes from a client not yet bound to a particular server
860 is passed to the server selected by the configured balancing method. 869 is passed to the server selected by the configured balancing method.
861 Further requests from the same client are passed to the same server. 870 Further requests with this cookie will be passed to the designated server.
862 If the designated server cannot process a request, the new server is 871 If the designated server cannot process a request, the new server is
863 selected as if the client has not been bound yet. 872 selected as if the client has not been bound yet.
864 </para> 873 </para>
865 874
866 <para> 875 <para>
888 </tag-desc> 897 </tag-desc>
889 898
890 </list> 899 </list>
891 If any parameters are omitted, the corresponding cookie fields are not set. 900 If any parameters are omitted, the corresponding cookie fields are not set.
892 </para> 901 </para>
902 </tag-desc>
903
904 <tag-name id="sticky_route"><literal>route</literal></tag-name>
905 <tag-desc>
893 906
894 <para> 907 <para>
895 When the <literal>route</literal> method is used, proxied server assigns 908 When the <literal>route</literal> method is used, proxied server assigns
896 client a route on receipt of the first request. 909 client a route on receipt of the first request.
897 All subsequent requests from this client will carry routing information 910 All subsequent requests from this client will carry routing information
931 Here, the route is taken from the “<literal>JSESSIONID</literal>” cookie 944 Here, the route is taken from the “<literal>JSESSIONID</literal>” cookie
932 if present in a request. 945 if present in a request.
933 Otherwise, the route from the URI is used. 946 Otherwise, the route from the URI is used.
934 </para> 947 </para>
935 948
949 </tag-desc>
950
951 <tag-name id="sticky_learn"><literal>learn</literal></tag-name>
952 <tag-desc>
953 <para>
954 When the <literal>learn</literal> method (1.7.1) is used, nginx
955 analyzes upstream server responses and learns server-initiated sessions
956 usually passed in an HTTP cookie.
957 <example>
958 upstream backend {
959 server backend1.example.com:8080;
960 server backend2.example.com:8081;
961
962 sticky learn
963 create=$upstream_cookie_sessionid
964 lookup=$cookie_sessionid
965 zone=client_sessions:1m;
966 }
967 </example>
968
969 In the example, the upstream server creates a session by setting the
970 cookie “<literal>SESSIONID</literal>” in the response.
971 Further requests with this cookie will be passed to the same server.
972 If the server cannot process the request, the new server is
973 selected as if the client has not been bound yet.
974 </para>
975
976 <para>
977 The parameters <literal>create</literal> and <literal>lookup</literal>
978 specify variables that indicate how new sessions are created and existing
979 sessions are searched, respectively.
980 Both parameters may be specified more than once, in which case the first
981 non-empty variable is used.
982 </para>
983
984 <para>
985 Sessions are stored in a shared memory zone, whose <value>name</value> and
986 <value>size</value> are configured by the <literal>zone</literal> parameter.
987 One megabyte zone can store about 8000 sessions on the 64-bit platform.
988 The sessions that are not accessed during the time specified by the
989 <literal>timeout</literal> parameter get removed from the zone.
990 By default, <literal>timeout</literal> is set to 10 minutes.
991 </para>
992
993 </tag-desc>
994 </list>
995 </para>
996
936 <para> 997 <para>
937 <note> 998 <note>
938 This directive is available as part of our 999 This directive is available as part of our
939 <commercial_version>commercial subscription</commercial_version>. 1000 <commercial_version>commercial subscription</commercial_version>.
940 </note> 1001 </note>
980 1041
981 <para> 1042 <para>
982 Configuration commands can be used to: 1043 Configuration commands can be used to:
983 <list type="bullet"> 1044 <list type="bullet">
984 1045
985 <listitem>view all primary or backup servers in a group;</listitem> 1046 <listitem>view the group configuration;</listitem>
986 1047
987 <listitem>view an individual server;</listitem> 1048 <listitem>view, modify, or remove an individual server;</listitem>
988 1049
989 <listitem>modify an individual server;</listitem> 1050 <listitem>add a new server.</listitem>
990
991 <listitem>add a new server (see the note below);</listitem>
992
993 <listitem>remove an individual server.</listitem>
994 1051
995 </list> 1052 </list>
996 <note> 1053 <note>
997 As noted in the <link id="server"/> directive, specifying a server
998 as a domain name may result in several servers being added to the group.
999 Since addresses in a group are not required to be unique, individual 1054 Since addresses in a group are not required to be unique, individual
1000 servers in a group can be uniquely referenced to only by their ID. 1055 servers in a group are referenced by their IDs.
1001 IDs are assigned automatically and shown on viewing of the group configuration. 1056 IDs are assigned automatically and shown when adding a new server
1057 or viewing the group configuration.
1002 </note> 1058 </note>
1003 </para> 1059 </para>
1004 1060
1005 <para> 1061 <para>
1006 A configuration command consists of parameters passed as request arguments, 1062 A configuration command consists of parameters passed as request arguments,
1007 for example: 1063 for example:
1008 <example> 1064 <example>
1009 http://127.0.0.1/upstream_conf?upstream=appservers 1065 http://127.0.0.1/upstream_conf?upstream=dynamic
1010 </example> 1066 </example>
1011 </para> 1067 </para>
1012 1068
1013 <para> 1069 <para>
1014 The following parameters are supported: 1070 The following parameters are supported:
1016 <list type="tag" compact="no"> 1072 <list type="tag" compact="no">
1017 1073
1018 <tag-name> 1074 <tag-name>
1019 <literal>upstream=</literal><value>name</value></tag-name> 1075 <literal>upstream=</literal><value>name</value></tag-name>
1020 <tag-desc> 1076 <tag-desc>
1021 Selects a group. 1077 Selects a group to work with.
1022 This parameter is mandatory. 1078 This parameter is mandatory.
1023 </tag-desc>
1024
1025 <tag-name>
1026 <literal>backup=</literal>
1027 </tag-name>
1028 <tag-desc>
1029 If not set, selects primary servers in the group.
1030 If set, selects backup servers in the group.
1031 </tag-desc> 1079 </tag-desc>
1032 1080
1033 <tag-name> 1081 <tag-name>
1034 <literal>id=</literal><value>number</value></tag-name> 1082 <literal>id=</literal><value>number</value></tag-name>
1035 <tag-desc> 1083 <tag-desc>
1036 Selects an individual primary or backup server in the group. 1084 Selects an individual server for viewing, modifying, or removing.
1037 </tag-desc> 1085 </tag-desc>
1038 1086
1039 <tag-name> 1087 <tag-name>
1040 <literal>remove=</literal></tag-name> 1088 <literal>remove=</literal></tag-name>
1041 <tag-desc> 1089 <tag-desc>
1042 Removes an individual primary or backup server from the group. 1090 Removes an individual server from the group.
1043 </tag-desc> 1091 </tag-desc>
1044 1092
1045 <tag-name> 1093 <tag-name>
1046 <literal>add=</literal></tag-name> 1094 <literal>add=</literal></tag-name>
1047 <tag-desc> 1095 <tag-desc>
1048 Adds a new primary or backup server to the group. 1096 Adds a new server to the group.
1097 </tag-desc>
1098
1099 <tag-name>
1100 <literal>backup=</literal></tag-name>
1101 <tag-desc>
1102 Required to add a backup server.
1103 <note>
1104 Before version 1.7.2, <literal>backup=</literal>
1105 was also required to view, modify, or remove existing backup servers.
1106 </note>
1049 </tag-desc> 1107 </tag-desc>
1050 1108
1051 <tag-name> 1109 <tag-name>
1052 <literal>server=</literal><value>address</value></tag-name> 1110 <literal>server=</literal><value>address</value></tag-name>
1053 <tag-desc> 1111 <tag-desc>
1054 Same as the “<literal>address</literal>” parameter 1112 Same as the “<literal>address</literal>” parameter
1055 of the <link id="server"/> directive. 1113 of the <link id="server"/> directive.
1114 <para>
1115 When adding a server, it is possible to specify it as a domain name.
1116 In this case, changes of the IP addresses that correspond to a domain name
1117 will be monitored and automatically applied to the upstream
1118 configuration without the need of restarting nginx (1.7.2).
1119 This requires the
1120 <link doc="ngx_http_core_module.xml" id="resolver"/> directive in the
1121 <link doc="ngx_http_core_module.xml" id="http"/> block.
1122 See also
1123 the <link id="resolve"/> parameter of the <link id="server"/> directive.
1124 </para>
1056 </tag-desc> 1125 </tag-desc>
1057 1126
1058 <tag-name> 1127 <tag-name>
1059 <literal>weight=</literal><value>number</value></tag-name> 1128 <literal>weight=</literal><value>number</value></tag-name>
1060 <tag-desc> 1129 <tag-desc>
1104 of the <link id="server"/> directive. 1173 of the <link id="server"/> directive.
1105 </tag-desc> 1174 </tag-desc>
1106 1175
1107 </list> 1176 </list>
1108 1177
1109 The first three parameters select a target the command applies to. 1178 The first two parameters select an object.
1110 Without other parameters, the command shows configuration of the selected 1179 This can be either the whole group or an individual server.
1111 target. 1180 Without other parameters, the configuration of the selected
1112 </para> 1181 group or server is shown.
1113 1182 </para>
1114 <para> 1183
1115 For example, to view the primary servers in the group, send: 1184 <para>
1116 <example> 1185 For example, to view the configuration of the whole group, send:
1117 http://127.0.0.1/upstream_conf?upstream=appservers 1186 <example>
1118 </example> 1187 http://127.0.0.1/upstream_conf?upstream=dynamic
1119 1188 </example>
1120 To view the backup servers in the group, send: 1189
1121 <example> 1190 To view the configuration of an individual server, also specify its ID:
1122 http://127.0.0.1/upstream_conf?upstream=appservers&amp;backup= 1191 <example>
1123 </example> 1192 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42
1124 1193 </example>
1125 To view an individual primary server in the group, send: 1194 </para>
1126 <example> 1195
1127 http://127.0.0.1/upstream_conf?upstream=appservers&amp;id=42 1196 <para>
1128 </example> 1197 To add a new server,
1129
1130 To view an individual backup server in the group, send:
1131 <example>
1132 http://127.0.0.1/upstream_conf?upstream=appservers&amp;backup=&amp;id=42
1133 </example>
1134 </para>
1135
1136 <para>
1137 To add a new primary or backup server to the group,
1138 specify its address in the “<literal>server=</literal>” parameter. 1198 specify its address in the “<literal>server=</literal>” parameter.
1139 Without other parameters specified, a server will be added with other 1199 Without other parameters specified, a server will be added with other
1140 parameters set to their default values (see the <link id="server"/> directive). 1200 parameters set to their default values (see the <link id="server"/> directive).
1141 </para> 1201 </para>
1142 1202
1143 <para> 1203 <para>
1144 For example, to add a new primary server to the group, send: 1204 For example, to add a new primary server, send:
1145 <example> 1205 <example>
1146 http://127.0.0.1/upstream_conf?add=&amp;upstream=appservers&amp;server=127.0.0.1:8080 1206 http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;server=127.0.0.1:8080
1147 </example> 1207 </example>
1148 1208
1149 To add a new backup server to the group, send: 1209 To add a new backup server, send:
1150 <example> 1210 <example>
1151 http://127.0.0.1/upstream_conf?add=&amp;upstream=appservers&amp;backup=&amp;server=127.0.0.1:8080 1211 http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;backup=&amp;server=127.0.0.1:8080
1152 </example> 1212 </example>
1153 1213
1154 To add a new primary server to the group, 1214 To add a new primary server,
1155 set its parameters to non-default values 1215 set its parameters to non-default values
1156 and mark it as “<literal>down</literal>”, send: 1216 and mark it as “<literal>down</literal>”, send:
1157 <example> 1217 <example>
1158 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= 1218 http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;server=127.0.0.1:8080&amp;weight=2&amp;down=
1159 </example> 1219 </example>
1160 </para> 1220 </para>
1161 1221
1162 <para> 1222 <para>
1163 To remove an individual primary or backup server from the group, 1223 To remove a server, specify its ID:
1164 select it with the <literal>id=</literal> parameter. 1224 <example>
1165 </para> 1225 http://127.0.0.1/upstream_conf?remove=&amp;upstream=dynamic&amp;id=42
1166 1226 </example>
1167 <para> 1227 </para>
1168 For example, to remove an individual primary server from the group, send: 1228
1169 <example> 1229 <para>
1170 http://127.0.0.1/upstream_conf?remove=&amp;upstream=appservers&amp;id=42 1230 To mark an existing server as “<literal>down</literal>”, send:
1171 </example> 1231 <example>
1172 1232 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;down=
1173 To remove an individual backup server from the group, send: 1233 </example>
1174 <example> 1234
1175 http://127.0.0.1/upstream_conf?remove=&amp;upstream=appservers&amp;backup=&amp;id=42 1235 To modify the address of an existing server, send:
1176 </example> 1236 <example>
1177 </para> 1237 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;server=192.0.2.3:8123
1178 1238 </example>
1179 <para> 1239
1180 To modify an individual primary or backup server in the group, 1240 To modify other parameters of an existing server, send:
1181 select it with the <literal>id=</literal> parameter. 1241 <example>
1182 </para> 1242 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;max_fails=3&amp;weight=4
1183
1184 <para>
1185 For example, to modify an individual primary server in the group
1186 by marking it as “<literal>down</literal>”, send:
1187 <example>
1188 http://127.0.0.1/upstream_conf?upstream=appservers&amp;id=42&amp;down=
1189 </example>
1190
1191 To modify the address of an individual backup server in the group, send:
1192 <example>
1193 http://127.0.0.1/upstream_conf?upstream=appservers&amp;backup=&amp;id=42&amp;server=192.0.2.3:8123
1194 </example>
1195
1196 To modify other parameters of an individual primary server in the group, send:
1197 <example>
1198 http://127.0.0.1/upstream_conf?upstream=appservers&amp;id=42&amp;max_fails=3&amp;weight=4
1199 </example> 1243 </example>
1200 1244
1201 </para> 1245 </para>
1202 1246
1203 <para> 1247 <para>