Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_module.xml @ 1367:f1e14d87d833

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 Mon, 01 Dec 2014 13:40:25 +0300
parents
children 66f227952864
comparison
equal deleted inserted replaced
1366:f3b7ec81b738 1367:f1e14d87d833
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) 2014 Yaroslav Zhuravlev
5 Copyright (C) Nginx, Inc.
6 -->
7
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9
10 <module name="Module ngx_stream_module"
11 link="/en/docs/stream/ngx_stream_module.html"
12 lang="en"
13 rev="1">
14
15 <section id="summary">
16
17 <para>
18 The <literal>stream</literal> module (1.7.7) provides
19 proxying TCP and UNIX-domain socket connections.
20 </para>
21
22 <para>
23 <note>
24 This module is available as part of our
25 <commercial_version>commercial subscription</commercial_version>.
26 </note>
27 </para>
28
29 </section>
30
31 <section id="example" name="Example Configuration">
32
33 <para>
34 <example>
35 stream {
36 upstream backend {
37 least_conn;
38 server srv1.example.com:8000;
39 server srv2.example.com:8000;
40 server srv3.example.com:8001;
41 }
42
43 server {
44 listen 9000;
45 proxy_connect_timeout 1s;
46 proxy_timeout 3s;
47 proxy_pass backend;
48 }
49 }
50 </example>
51 In this example, a server that listens on port 9000
52 <link doc="ngx_stream_module.xml" id="proxy_pass">proxies</link>
53 TCP connections to a group of servers named <literal>backend</literal>.
54 Note that the <link doc="ngx_stream_module.xml" id="proxy_pass"/>
55 directive defined the context of the <literal>stream</literal> module
56 must not contain a protocol.
57 Two optional timeout parameters are specified:
58 the <link doc="ngx_stream_module.xml" id="proxy_connect_timeout"/> sets
59 a timeout required for establishing a connection with a server
60 that belongs to the <literal>backend</literal> group, while the
61 <link doc="ngx_stream_module.xml" id="proxy_timeout"/> sets
62 a timeout used after proxying to one of the servers in the
63 <literal>backend</literal> group had started.
64 All TCP proxy-related functionality is configured inside the
65 <link doc="ngx_stream_module.xml" id="stream"/> block
66 just like the <link doc="../http/ngx_http_core_module.xml" id="http"/> block
67 for HTTP requests.
68 </para>
69
70 <para>
71 The <literal>backend</literal> group consists of three physical servers
72 (<literal>srv1-srv3</literal>).
73 Each server name follows the obligatory <literal>port</literal> number.
74 TCP connections are distributed among the servers according to the
75 <link doc="ngx_stream_upstream_module.xml" id="least_conn">least
76 connected</link> load balancing method: a connection will go to the server
77 that has the fewest active connections.
78 Directives required to configure a group of proxied servers
79 and load-balancing can be found in the
80 <link doc="ngx_stream_upstream_module.xml">ngx_stream_upstream_module</link>.
81 </para>
82
83 </section>
84
85
86 <section id="directives" name="Directives">
87
88 <directive name="listen">
89 <syntax>
90 <value>address</value>:<value>port</value>
91 [<literal>bind</literal>]
92 [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>]
93 [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax>
94 <default/>
95 <context>server</context>
96
97 <para>
98 Sets the <value>address</value> and <value>port</value> for the socket
99 on which the server will accept connections.
100 It is possible to specify just the port.
101 The address can also be a hostname, for example:
102 <example>
103 listen 127.0.0.1:110;
104 listen *:110;
105 listen 110; # same as *:110
106 listen localhost:110;
107 </example>
108 IPv6 addresses are specified in square brackets:
109 <example>
110 listen [::1]:110;
111 listen [::]:110;
112 </example>
113 UNIX-domain sockets are specified with the “<literal>unix:</literal>”
114 prefix:
115 <example>
116 listen unix:/var/run/nginx.sock;
117 </example>
118
119 </para>
120
121 <para>
122 The directive supports the following parameters:
123
124 <list type="tag">
125
126 <tag-name id="bind">
127 <literal>bind</literal>
128 </tag-name>
129 <tag-desc>
130 this parameter instructs to make a separate <c-func>bind</c-func>
131 call for a given address:port pair.
132 The fact is that if there are several <literal>listen</literal> directives with
133 the same port but different addresses, and one of the
134 <literal>listen</literal> directives listens on all addresses
135 for the given port (<literal>*:</literal><value>port</value>), nginx will
136 <c-func>bind</c-func> only to <literal>*:</literal><value>port</value>.
137 It should be noted that the <c-func>getsockname</c-func> system call will be
138 made in this case to determine the address that accepted the connection.
139 If the <literal>ipv6only</literal>
140 or <literal>so_keepalive</literal> parameters
141 are used then for a given
142 <value>address</value>:<value>port</value> pair
143 a separate <c-func>bind</c-func> call will always be made.
144 </tag-desc>
145
146 <tag-name id="ipv6only">
147 <literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>
148 </tag-name>
149 <tag-desc>
150 this parameter determines
151 (via the <c-def>IPV6_V6ONLY</c-def> socket option)
152 whether an IPv6 socket listening on a wildcard address <literal>[::]</literal>
153 will accept only IPv6 connections or both IPv6 and IPv4 connections.
154 This parameter is turned on by default.
155 It can only be set once on start.
156 </tag-desc>
157
158 <tag-name id="so_keepalive">
159 <literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]
160 </tag-name>
161 <tag-desc>
162 this parameter configures the “TCP keepalive” behavior
163 for the listening socket.
164 If this parameter is omitted then the operating system’s settings will be
165 in effect for the socket.
166 If it is set to the value “<literal>on</literal>”, the
167 <c-def>SO_KEEPALIVE</c-def> option is turned on for the socket.
168 If it is set to the value “<literal>off</literal>”, the
169 <c-def>SO_KEEPALIVE</c-def> option is turned off for the socket.
170 Some operating systems support setting of TCP keepalive parameters on
171 a per-socket basis using the <c-def>TCP_KEEPIDLE</c-def>,
172 <c-def>TCP_KEEPINTVL</c-def>, and <c-def>TCP_KEEPCNT</c-def> socket options.
173 On such systems (currently, Linux 2.4+, NetBSD 5+, and
174 FreeBSD 9.0-STABLE), they can be configured
175 using the <value>keepidle</value>, <value>keepintvl</value>, and
176 <value>keepcnt</value> parameters.
177 One or two parameters may be omitted, in which case the system default setting
178 for the corresponding socket option will be in effect.
179 For example,
180 <example>so_keepalive=30m::10</example>
181 will set the idle timeout (<c-def>TCP_KEEPIDLE</c-def>) to 30 minutes,
182 leave the probe interval (<c-def>TCP_KEEPINTVL</c-def>) at its system default,
183 and set the probes count (<c-def>TCP_KEEPCNT</c-def>) to 10 probes.
184 </tag-desc>
185 </list>
186 </para>
187
188 <para>
189 Different servers must listen on different
190 <value>address</value>:<value>port</value> pairs.
191 </para>
192
193 </directive>
194
195
196 <directive name="proxy_connect_timeout">
197 <syntax><value>time</value></syntax>
198 <default>60s</default>
199 <context>stream</context>
200 <context>server</context>
201
202 <para>
203 Defines a timeout for establishing a connection with a proxied server.
204 </para>
205
206 </directive>
207
208
209 <directive name="proxy_downstream_buffer">
210 <syntax><value>size</value></syntax>
211 <default>16k</default>
212 <context>stream</context>
213 <context>server</context>
214
215 <para>
216 Sets the <value>size</value> of the
217 buffers used for reading data from the client.
218 </para>
219
220 </directive>
221
222
223 <directive name="proxy_pass">
224 <syntax><value>URL</value></syntax>
225 <default/>
226 <context>server</context>
227
228 <para>
229 Sets the address of a proxied server or a
230 <link doc="ngx_stream_upstream_module.xml">server group</link>.
231 The address can be specified as a domain name or IP address,
232 and an obligatory port.
233 If a domain name resolves to several addresses, all of them will be
234 used in a round-robin fashion.
235 </para>
236
237 </directive>
238
239
240 <directive name="proxy_timeout">
241 <syntax><value>timeout</value></syntax>
242 <default>10m</default>
243 <context>stream</context>
244 <context>server</context>
245
246 <para>
247 Defines a timeout used after the proxying to the backend had started.
248 </para>
249
250 </directive>
251
252
253 <directive name="proxy_upstream_buffer">
254 <syntax><value>size</value></syntax>
255 <default>16k</default>
256 <context>stream</context>
257 <context>server</context>
258
259 <para>
260 Sets the <value>size</value> of the
261 buffers used for reading data from the upstream server.
262 </para>
263
264 </directive>
265
266
267 <directive name="server">
268 <syntax block="yes"/>
269 <default/>
270 <context>stream</context>
271
272 <para>
273 Sets the configuration for a server.
274 </para>
275
276 </directive>
277
278
279 <directive name="stream">
280 <syntax block="yes"/>
281 <default/>
282 <context>main</context>
283
284 <para>
285 Provides the configuration file context in which the stream server directives
286 are specified.
287 </para>
288
289 </directive>
290
291 </section>
292
293 </module>