Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 1450:f5b5eefc43cb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated commercial docs for the upcoming release.
author Ruslan Ermilov <ru@nginx.com>
date Thu, 09 Apr 2015 19:18:54 +0300
parents 410e0683b6b4
children 4e5cab61e548
comparison
equal deleted inserted replaced
1449:c79501e16e26 1450:f5b5eefc43cb
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="35"> 13 rev="36">
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 resolver 10.0.0.1;
57
56 upstream <emphasis>dynamic</emphasis> { 58 upstream <emphasis>dynamic</emphasis> {
57 zone upstream_dynamic 64k; 59 zone upstream_dynamic 64k;
58 60
59 server backend1.example.com weight=5; 61 server backend1.example.com weight=5;
60 server backend2.example.com:8080 fail_timeout=5s slow_start=30s; 62 server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
61 server 192.0.2.1 max_fails=3; 63 server 192.0.2.1 max_fails=3;
64 server backend3.example.com resolve;
62 65
63 server backup1.example.com:8080 backup; 66 server backup1.example.com:8080 backup;
64 server backup2.example.com:8080 backup; 67 server backup2.example.com:8080 backup;
65 } 68 }
66 69
67 server { 70 server {
68 location / { 71 location / {
69 proxy_pass http://<emphasis>dynamic</emphasis>; 72 proxy_pass http://<emphasis>dynamic</emphasis>;
70 health_check; 73 health_check;
71 }
72
73 location /upstream_conf {
74 upstream_conf;
75 allow 127.0.0.1;
76 deny all;
77 } 74 }
78 } 75 }
79 </example> 76 </example>
80 </para> 77 </para>
81 78
296 shared between worker processes. 293 shared between worker processes.
297 Such groups allow changing the group membership 294 Such groups allow changing the group membership
298 or modifying the settings of a particular server 295 or modifying the settings of a particular server
299 without the need of restarting nginx. 296 without the need of restarting nginx.
300 The configuration is accessible via a special location 297 The configuration is accessible via a special location
301 handled by <link id="upstream_conf"/>. 298 handled by
299 <link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf"/>.
302 </para> 300 </para>
303 301
304 <para> 302 <para>
305 <note> 303 <note>
306 This directive is available as part of our 304 This directive is available as part of our
521 Specifies that a group should use a load balancing method where a request 519 Specifies that a group should use a load balancing method where a request
522 is passed to the server with the least number of active connections, 520 is passed to the server with the least number of active connections,
523 taking into account weights of servers. 521 taking into account weights of servers.
524 If there are several such servers, they are tried in turn using a 522 If there are several such servers, they are tried in turn using a
525 weighted round-robin balancing method. 523 weighted round-robin balancing method.
524 </para>
525
526 </directive>
527
528
529 <directive name="least_time">
530 <syntax><literal>header</literal> | <literal>last_byte</literal></syntax>
531 <default/>
532 <context>upstream</context>
533 <appeared-in>1.7.10</appeared-in>
534
535 <para>
536 Specifies that a group should use a load balancing method where a request
537 is passed to the server with the least average response time and
538 least number of active connections, taking into account weights of servers.
539 If there are several such servers, they are tried in turn using a
540 weighted round-robin balancing method.
541 </para>
542
543 <para>
544 If the <literal>header</literal> parameter is specified,
545 time to receive the
546 <link id="var_upstream_header_time">response header</link> is used.
547 If the <literal>last_byte</literal> parameter is specified,
548 time to receive the <link id="var_upstream_response_time">full response</link>
549 is used.
550 </para>
551
552 <para>
553 <note>
554 This directive is available as part of our
555 <commercial_version>commercial subscription</commercial_version>.
556 </note>
526 </para> 557 </para>
527 558
528 </directive> 559 </directive>
529 560
530 561
834 <directive name="sticky"> 865 <directive name="sticky">
835 <syntax> 866 <syntax>
836 <literal>cookie</literal> <value>name</value> 867 <literal>cookie</literal> <value>name</value>
837 [<literal>expires=</literal><value>time</value>] 868 [<literal>expires=</literal><value>time</value>]
838 [<literal>domain=</literal><value>domain</value>] 869 [<literal>domain=</literal><value>domain</value>]
870 [<literal>httponly</literal>]
871 [<literal>secure</literal>]
839 [<literal>path=</literal><value>path</value>]</syntax> 872 [<literal>path=</literal><value>path</value>]</syntax>
840 <syntax> 873 <syntax>
841 <literal>route</literal> <value>$variable</value> ...</syntax> 874 <literal>route</literal> <value>$variable</value> ...</syntax>
842 <syntax> 875 <syntax>
843 <literal>learn</literal> 876 <literal>learn</literal>
881 <para> 914 <para>
882 The first parameter sets the name of the cookie to be set or inspected. 915 The first parameter sets the name of the cookie to be set or inspected.
883 Additional parameters may be as follows: 916 Additional parameters may be as follows:
884 <list type="tag"> 917 <list type="tag">
885 918
886 <tag-name><literal>expires</literal></tag-name> 919 <tag-name><literal>expires=</literal><value>time</value></tag-name>
887 <tag-desc> 920 <tag-desc>
888 Sets the time for which a browser should keep the cookie. 921 Sets the <value>time</value> for which a browser should keep the cookie.
889 The special value <literal>max</literal> will cause the cookie to expire on 922 The special value <literal>max</literal> will cause the cookie to expire on
890 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. 923 “<literal>31 Dec 2037 23:55:55 GMT</literal>”.
891 If the parameter is not specified, it will cause the cookie to expire at 924 If the parameter is not specified, it will cause the cookie to expire at
892 the end of a browser session. 925 the end of a browser session.
893 </tag-desc> 926 </tag-desc>
894 927
895 <tag-name><literal>domain</literal></tag-name> 928 <tag-name><literal>domain=</literal><value>domain</value></tag-name>
896 <tag-desc> 929 <tag-desc>
897 Defines the domain for which the cookie is set. 930 Defines the <value>domain</value> for which the cookie is set.
898 </tag-desc> 931 </tag-desc>
899 932
900 <tag-name><literal>path</literal></tag-name> 933 <tag-name><literal>httponly</literal></tag-name>
901 <tag-desc> 934 <tag-desc>
902 Defines the path for which the cookie is set. 935 Adds the <literal>HttpOnly</literal> attribute to the cookie (1.7.11).
936 </tag-desc>
937
938 <tag-name><literal>secure</literal></tag-name>
939 <tag-desc>
940 Adds the <literal>Secure</literal> attribute to the cookie (1.7.11).
941
942 </tag-desc>
943
944 <tag-name><literal>path=</literal><value>path</value></tag-name>
945 <tag-desc>
946 Defines the <value>path</value> for which the cookie is set.
903 </tag-desc> 947 </tag-desc>
904 948
905 </list> 949 </list>
906 If any parameters are omitted, the corresponding cookie fields are not set. 950 If any parameters are omitted, the corresponding cookie fields are not set.
907 </para> 951 </para>
1025 <note> 1069 <note>
1026 <literal>sticky cookie</literal> <value>name</value> 1070 <literal>sticky cookie</literal> <value>name</value>
1027 [<literal>expires=</literal><value>time</value>] 1071 [<literal>expires=</literal><value>time</value>]
1028 [<literal>domain=</literal><value>domain</value>] 1072 [<literal>domain=</literal><value>domain</value>]
1029 [<literal>path=</literal><value>path</value>]; 1073 [<literal>path=</literal><value>path</value>];
1030 </note>
1031 </para>
1032
1033 </directive>
1034
1035
1036 <directive name="upstream_conf">
1037 <syntax/>
1038 <default/>
1039 <context>location</context>
1040
1041 <para>
1042 Turns on the HTTP interface of upstream configuration in the surrounding
1043 location.
1044 Access to this location should be
1045 <link doc="ngx_http_core_module.xml" id="satisfy">limited</link>.
1046 </para>
1047
1048 <para>
1049 Configuration commands can be used to:
1050 <list type="bullet">
1051
1052 <listitem>view the group configuration;</listitem>
1053
1054 <listitem>view, modify, or remove a server;</listitem>
1055
1056 <listitem>add a new server.</listitem>
1057
1058 </list>
1059 <note>
1060 Since addresses in a group are not required to be unique, specific
1061 servers in a group are referenced by their IDs.
1062 IDs are assigned automatically and shown when adding a new server
1063 or viewing the group configuration.
1064 </note>
1065 </para>
1066
1067 <para>
1068 A configuration command consists of parameters passed as request arguments,
1069 for example:
1070 <example>
1071 http://127.0.0.1/upstream_conf?upstream=dynamic
1072 </example>
1073 </para>
1074
1075 <para>
1076 The following parameters are supported:
1077
1078 <list type="tag" compact="no">
1079
1080 <tag-name>
1081 <literal>upstream=</literal><value>name</value></tag-name>
1082 <tag-desc>
1083 Selects a group to work with.
1084 This parameter is mandatory.
1085 </tag-desc>
1086
1087 <tag-name>
1088 <literal>id=</literal><value>number</value></tag-name>
1089 <tag-desc>
1090 Selects a server for viewing, modifying, or removing.
1091 </tag-desc>
1092
1093 <tag-name>
1094 <literal>remove=</literal></tag-name>
1095 <tag-desc>
1096 Removes a server from the group.
1097 </tag-desc>
1098
1099 <tag-name>
1100 <literal>add=</literal></tag-name>
1101 <tag-desc>
1102 Adds a new server to the group.
1103 </tag-desc>
1104
1105 <tag-name>
1106 <literal>backup=</literal></tag-name>
1107 <tag-desc>
1108 Required to add a backup server.
1109 <note>
1110 Before version 1.7.2, <literal>backup=</literal>
1111 was also required to view, modify, or remove existing backup servers.
1112 </note>
1113 </tag-desc>
1114
1115 <tag-name>
1116 <literal>server=</literal><value>address</value></tag-name>
1117 <tag-desc>
1118 Same as the “<literal>address</literal>” parameter
1119 of the <link id="server"/> directive.
1120 <para>
1121 When adding a server, it is possible to specify it as a domain name.
1122 In this case, changes of the IP addresses that correspond to a domain name
1123 will be monitored and automatically applied to the upstream
1124 configuration without the need of restarting nginx (1.7.2).
1125 This requires the
1126 <link doc="ngx_http_core_module.xml" id="resolver"/> directive in the
1127 <link doc="ngx_http_core_module.xml" id="http"/> block.
1128 See also
1129 the <link id="resolve"/> parameter of the <link id="server"/> directive.
1130 </para>
1131 </tag-desc>
1132
1133 <tag-name>
1134 <literal>weight=</literal><value>number</value></tag-name>
1135 <tag-desc>
1136 Same as the “<literal>weight</literal>” parameter
1137 of the <link id="server"/> directive.
1138 </tag-desc>
1139
1140 <tag-name>
1141 <literal>max_conns=</literal><value>number</value></tag-name>
1142 <tag-desc>
1143 Same as the “<literal>max_conns</literal>” parameter
1144 of the <link id="server"/> directive.
1145 </tag-desc>
1146
1147 <tag-name>
1148 <literal>max_fails=</literal><value>number</value></tag-name>
1149 <tag-desc>
1150 Same as the “<literal>max_fails</literal>” parameter
1151 of the <link id="server"/> directive.
1152 </tag-desc>
1153
1154 <tag-name>
1155 <literal>fail_timeout=</literal><value>time</value></tag-name>
1156 <tag-desc>
1157 Same as the “<literal>fail_timeout</literal>” parameter
1158 of the <link id="server"/> directive.
1159 </tag-desc>
1160
1161 <tag-name>
1162 <literal>slow_start=</literal><value>time</value></tag-name>
1163 <tag-desc>
1164 Same as the “<literal>slow_start</literal>” parameter
1165 of the <link id="server"/> directive.
1166 </tag-desc>
1167
1168 <tag-name>
1169 <literal>down=</literal></tag-name>
1170 <tag-desc>
1171 Same as the “<literal>down</literal>” parameter
1172 of the <link id="server"/> directive.
1173 </tag-desc>
1174
1175 <tag-name id="drain"><literal>drain=</literal></tag-name>
1176 <tag-desc>
1177 Puts the upstream server in the “draining” mode (1.7.5).
1178 In this mode, only requests <link id="sticky">bound</link> to the server
1179 will be proxied to it.
1180 </tag-desc>
1181
1182 <tag-name>
1183 <literal>up=</literal></tag-name>
1184 <tag-desc>
1185 The opposite of the “<literal>down</literal>” parameter
1186 of the <link id="server"/> directive.
1187 </tag-desc>
1188
1189 <tag-name>
1190 <literal>route=</literal><value>string</value></tag-name>
1191 <tag-desc>
1192 Same as the “<literal>route</literal>” parameter
1193 of the <link id="server"/> directive.
1194 </tag-desc>
1195
1196 </list>
1197
1198 The first two parameters select an object.
1199 This can be either the whole group or a specific server.
1200 Without other parameters, the configuration of the selected
1201 group or server is shown.
1202 </para>
1203
1204 <para>
1205 For example, to view the configuration of the whole group, send:
1206 <example>
1207 http://127.0.0.1/upstream_conf?upstream=dynamic
1208 </example>
1209
1210 To view the configuration of a specific server, also specify its ID:
1211 <example>
1212 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42
1213 </example>
1214 </para>
1215
1216 <para>
1217 To add a new server,
1218 specify its address in the “<literal>server=</literal>” parameter.
1219 Without other parameters specified, a server will be added with other
1220 parameters set to their default values (see the <link id="server"/> directive).
1221 </para>
1222
1223 <para>
1224 For example, to add a new primary server, send:
1225 <example>
1226 http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;server=127.0.0.1:8080
1227 </example>
1228
1229 To add a new backup server, send:
1230 <example>
1231 http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;backup=&amp;server=127.0.0.1:8080
1232 </example>
1233
1234 To add a new primary server,
1235 set its parameters to non-default values
1236 and mark it as “<literal>down</literal>”, send:
1237 <example>
1238 http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;server=127.0.0.1:8080&amp;weight=2&amp;down=
1239 </example>
1240 </para>
1241
1242 <para>
1243 To remove a server, specify its ID:
1244 <example>
1245 http://127.0.0.1/upstream_conf?remove=&amp;upstream=dynamic&amp;id=42
1246 </example>
1247 </para>
1248
1249 <para>
1250 To mark an existing server as “<literal>down</literal>”, send:
1251 <example>
1252 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;down=
1253 </example>
1254
1255 To modify the address of an existing server, send:
1256 <example>
1257 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;server=192.0.2.3:8123
1258 </example>
1259
1260 To modify other parameters of an existing server, send:
1261 <example>
1262 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;max_fails=3&amp;weight=4
1263 </example>
1264
1265 </para>
1266
1267 <para>
1268 <note>
1269 This directive is available as part of our
1270 <commercial_version>commercial subscription</commercial_version>.
1271 </note> 1074 </note>
1272 </para> 1075 </para>
1273 1076
1274 </directive> 1077 </directive>
1275 1078