Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_upstream_module.xml @ 316:1fb1c077658b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the following directives: "keepalive", "proxy_http_version", and "fastcgi_keep_conn".
author Ruslan Ermilov <ru@nginx.com>
date Fri, 13 Jan 2012 18:10:34 +0000
parents 34246e706f48
children 4f907cde0382
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
293
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
2
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
4
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
5 <module name="Module ngx_http_upstream_module"
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
6 link="/en/docs/http/ngx_http_upstream_module.html"
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
7 lang="en">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
8
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
9 <section id="summary">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
10
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
11 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
12 The <literal>ngx_http_upstream_module</literal> module
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
13 allows to define groups of servers that can be referenced
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14 from the <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/> and
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/> directives.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
17
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
18 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
19
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
20
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
21 <section id="example" name="Example Configuration">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
22
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
23 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
24 <example>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
25 upstream <emphasis>backend</emphasis> {
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
26 server backend1.example.com weight=5;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
27 server backend2.example.com:8080;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
28 server unix:/tmp/backend3;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
29
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
30 server backup1.example.com:8080 backup;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
31 server backup2.example.com:8080 backup;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
32 }
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
33
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
34 server {
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
35 location / {
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
36 proxy_pass http://<emphasis>backend</emphasis>;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
37 }
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
38 }
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
39 </example>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
40 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
41
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
42 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
43
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
44
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
45 <section id="directives" name="Directives">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
46
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
47 <directive name="ip_hash">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
48 <syntax/>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
49 <default/>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
50 <context>upstream</context>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
51
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
52 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
53 Specifies that a group should use a balancing method where requests
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
54 are distributed between servers based on client IP addresses.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
55 A class C network containing the client IP address is used as a hashing key.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
56 The method ensures that requests of the same client will always be
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
57 passed to the same server except when this server is considered down
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
58 in which case client requests will be passed to another server and
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
59 most probably it will also be the same server.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
60 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
61
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
62 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
63 It is not possible to specify a weight for servers using the
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
64 <literal>ip_hash</literal> balancing method.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
65 If one of the servers needs to be temporarily removed, it should
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
66 be marked with the <literal>down</literal> parameter in
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
67 order to preserve the current hashing of client IP addresses.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
68 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
69
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
70 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
71 Example:
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
72 <example>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
73 upstream backend {
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
74 ip_hash;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
75
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
76 server backend1.example.com;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
77 server backend2.example.com;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
78 server backend3.example.com <emphasis>down</emphasis>;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
79 server backend4.example.com;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
80 }
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
81 </example>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
82 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
83
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
84 </directive>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
85
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
86
316
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
87 <directive name="keepalive">
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
88 <syntax><value>connections</value></syntax>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
89 <default/>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
90 <context>upstream</context>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
91 <appeared-in>1.1.4</appeared-in>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
92
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
93 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
94 Activates cache of connections to upstream servers.
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
95 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
96
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
97 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
98 The <value>connections</value> parameter sets the maximum number of
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
99 keepalive connections to upstream servers that are retained in
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
100 the cache per one worker process.
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
101 If there are more idle connections to retain to an upstream than
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
102 are specified by this number, the least recently used ones will
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
103 be closed.
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
104 <note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
105 It should be noted that <literal>keepalive</literal> directive
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
106 does not limit the total number of connections that nginx worker
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
107 process can open to upstream servers.
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
108 The new connections are always created on demand.
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
109 The <value>connections</value> parameter should be set low enough
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
110 to allow upstream servers to process additional new incoming
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
111 connections as well.
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
112 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
113 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
114
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
115 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
116 Example configuration of memcached upstream with keepalive connections:
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
117 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
118 upstream memcached_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
119 server 127.0.0.1:11211;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
120 server 10.0.0.2:11211;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
121
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
122 keepalive 32;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
123 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
124
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
125 server {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
126 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
127
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
128 location /memcached/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
129 set $memcached_key $uri;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
130 memcached_pass memcached_backend;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
131 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
132
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
133 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
134 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
135 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
136
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
137 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
138 For HTTP, the <link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
139 directive should be set to “<literal>1.1</literal>”
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
140 and the <header>Connection</header> header field should be cleared:
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
141 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
142 upstream http_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
143 server 127.0.0.1:8080;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
144
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
145 keepalive 16;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
146 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
147
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
148 server {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
149 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
150
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
151 location /http/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
152 proxy_pass http://http_backend;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
153 proxy_http_version 1.1;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
154 proxy_set_header Connection "";
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
155 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
156 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
157 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
158 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
159 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
160
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
161 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
162 <note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
163 Alternatively, HTTP/1.0 persistent connections can be used by passing the
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
164 <header>Connection: Keep-Alive</header> header field to an upstream server,
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
165 though this is not recommended.
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
166 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
167 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
168
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
169 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
170 For FastCGI servers, it is required to set
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
171 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_keep_conn"/>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
172 for keepalive connections to work:
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
173 <example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
174 upstream fastcgi_backend {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
175 server 127.0.0.1:9000;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
176
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
177 keepalive 8;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
178 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
179
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
180 server {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
181 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
182
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
183 location /fastcgi/ {
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
184 fastcgi_pass fastcgi_backend;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
185 fastcgi_keep_conn on;
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
186 ...
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
187 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
188 }
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
189 </example>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
190 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
191
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
192 <para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
193 <note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
194 When using load balancer modules other than the default
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
195 round-robin, it is necessary to activate them before
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
196 the <literal>keepalive</literal> directive.
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
197 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
198
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
199 <note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
200 SCGI and uwsgi protocols do not define keepalive connections.
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
201 </note>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
202 </para>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
203
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
204 </directive>
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
205
1fb1c077658b Documented the following directives: "keepalive", "proxy_http_version",
Ruslan Ermilov <ru@nginx.com>
parents: 293
diff changeset
206
293
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
207 <directive name="server">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
208 <syntax><value>name</value> [<value>parameters</value>]</syntax>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
209 <default/>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
210 <context>upstream</context>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
211
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
212 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
213 Sets a <value>name</value> and other <value>parameters</value> of the server.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
214 A <value>name</value> can be a domain name, an address, a port, or a
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
215 path of the UNIX-domain socket.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
216 If a domain name resolves to several addresses, all of them are used.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
217 <list type="tag">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
218
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
219 <tag-name><literal>weight</literal>=<value>number</value></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
220 <tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
221 sets a weight of the server, by default 1.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
222 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
223
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
224 <tag-name><literal>max_fails</literal>=<value>number</value></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
225 <tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
226 sets a number of unsuccessful attempts to communicate with the server
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
227 during a time set by the <literal>fail_timeout</literal> parameter
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
228 after which it will be considered down for a period of time also set
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
229 by the <literal>fail_timeout</literal> parameter.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
230 By default, the number of unsuccessful attempts is set to 1.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
231 A value of zero disables accounting of attempts.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
232 What is considered to be an unsuccessful attempt is configured by the
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
233 <link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
234 and <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
235 directives.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
236 The <literal>http_404</literal> state is not considered
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
237 an unsuccessful attempt.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
238 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
239
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
240 <tag-name><literal>fail_timeout</literal>=<value>time</value></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
241 <tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
242 sets
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
243 <list type="bullet">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
244
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
245 <listitem>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
246 a time during which the specified number of unsuccessful attempts to
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
247 communicate with the server should happen for the server to be
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
248 considered down;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
249 </listitem>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
250
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
251 <listitem>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
252 and a period of time the server will be considered down.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
253 </listitem>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
254
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
255 </list>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
256 By default, timeout is set to 10 seconds.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
257 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
258
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
259 <tag-name><literal>backup</literal></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
260 <tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
261 marks the server as a backup server.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
262 It will be passed requests when the primary servers are down.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
263 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
264
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
265 <tag-name><literal>down</literal></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
266 <tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
267 marks the server as permanently down; used along with
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
268 the <link id="ip_hash"/> directive.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
269 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
270
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
271 </list>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
272 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
273
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
274 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
275 Example:
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
276 <example>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
277 upstream backend {
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
278 server backend1.example.com weight=5;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
279 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
280 server unix:/tmp/backend3;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
281
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
282 server backup1.example.com:8080 backup;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
283 }
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
284 </example>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
285 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
286
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
287 </directive>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
288
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
289
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
290 <directive name="upstream">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
291 <syntax block="yes"><value>name</value></syntax>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
292 <default/>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
293 <context>http</context>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
294
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
295 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
296 Defines a group of servers.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
297 Servers can listen on different ports.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
298 In addition, servers listening on TCP and UNIX-domain sockets
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
299 can be used simultaneously.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
300 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
301
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
302 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
303 Example:
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
304 <example>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
305 upstream backend {
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
306 server backend1.example.com weight=5;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
307 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
308 server unix:/tmp/backend3;
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
309 }
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
310 </example>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
311 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
312
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
313 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
314 Requests are distributed between servers in a round-robin fashion,
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
315 taking into account the weights of servers.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
316 In the above example, each 7 requests will be distributed as follows:
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
317 5 requests to <literal>backend1.example.com</literal>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
318 and one request to each of second and third servers.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
319 If an error occurs when communicating with the server, a request will
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
320 be passed to the next server, and so on until all of the functioning
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
321 servers will be tried.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
322 If a successful response could not be obtained from any of the servers,
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
323 the client will be returned the result of contacting the last server.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
324 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
325
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
326 </directive>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
327
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
328 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
329
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
330
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
331 <section id="variables" name="Embedded Variables">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
332
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
333 <para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
334 The <literal>ngx_http_upstream_module</literal> module
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
335 supports the following embedded variables:
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
336 <list type="tag">
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
337
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
338 <tag-name><var>$upstream_addr</var></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
339 <tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
340 keeps an IP address and port of the server,
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
341 or a path to the UNIX-domain socket.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
342 If several servers were contacted during request processing,
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
343 their addresses are separated by commas, e.g.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
344 “<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
345 If an internal redirect from one server group to another happened
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
346 using
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
347 <header>X-Accel-Redirect</header> or
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
348 <link doc="ngx_http_core_module.xml" id="error_page"/>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
349 then these server groups are separated by colons, e.g.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
350 “<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80</literal>”.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
351 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
352
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
353 <tag-name><var>$upstream_response_time</var></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
354 <tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
355 keeps servers response times in seconds with a milliseconds resolution.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
356 Several responses are also separated by commas and colons.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
357 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
358
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
359 <tag-name><var>$upstream_status</var></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
360 <tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
361 keeps servers response codes.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
362 Several responses are also separated by commas and colons.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
363 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
364
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
365 <tag-name><var>$upstream_http_...</var></tag-name>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
366 <tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
367 keep server response header fields.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
368 For example, the <header>Server</header> response header field
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
369 is made available through the <var>$upstream_http_server</var> variable.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
370 Note that only the last server’s response header fields are saved.
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
371 </tag-desc>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
372
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
373 </list>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
374 </para>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
375
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
376 </section>
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
377
34246e706f48 English translation of the ngx_http_upstream_module documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
378 </module>