Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_core_module.xml @ 617:368a449e85b8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Expanded documentation of what various parameters of the "listen" directive related to socket options do. While here, documented the fact that accept filters also work on NetBSD.
author Ruslan Ermilov <ru@nginx.com>
date Thu, 02 Aug 2012 13:24:07 +0000
parents f3ef5b77d22a
children af3f38e349eb
comparison
equal deleted inserted replaced
616:2fdd929c830e 617:368a449e85b8
1150 </note> 1150 </note>
1151 </para> 1151 </para>
1152 1152
1153 <para> 1153 <para>
1154 A <literal>listen</literal> directive 1154 A <literal>listen</literal> directive
1155 can have several additional parameters specific to system calls 1155 can have several additional parameters specific to socket-related system calls.
1156 <c-func>listen</c-func> and <c-func>bind</c-func>.
1157 They can be specified in any 1156 They can be specified in any
1158 <literal>listen</literal> directive, but only once for the given 1157 <literal>listen</literal> directive, but only once for the given
1159 <value>address</value>:<value>port</value> pair. 1158 <value>address</value>:<value>port</value> pair.
1160 <note> 1159 <note>
1161 In versions prior to 0.8.21, they could only be 1160 In versions prior to 0.8.21, they could only be
1162 specified in the <literal>listen</literal> directive with the 1161 specified in the <literal>listen</literal> directive along with the
1163 <literal>default</literal> parameter. 1162 <literal>default</literal> parameter.
1164 </note> 1163 </note>
1165 <list type="tag"> 1164 <list type="tag">
1166 1165
1167 <tag-name> 1166 <tag-name>
1168 <literal>setfib</literal>=<value>number</value> 1167 <literal>setfib</literal>=<value>number</value>
1169 </tag-name> 1168 </tag-name>
1170 <tag-desc> 1169 <tag-desc>
1171 this parameter (0.8.44) sets the associated FIB (routing table) 1170 this parameter (0.8.44) sets an associated routing table, FIB
1172 for the listening socket. 1171 (the <c-def>SO_SETFIB</c-def> option) for the listening socket.
1173 This currently works only on FreeBSD. 1172 This currently works only on FreeBSD.
1174 </tag-desc> 1173 </tag-desc>
1175 1174
1176 <tag-name> 1175 <tag-name>
1177 <literal>backlog</literal>=<value>number</value> 1176 <literal>backlog</literal>=<value>number</value>
1178 </tag-name> 1177 </tag-name>
1179 <tag-desc> 1178 <tag-desc>
1180 sets the <literal>backlog</literal> parameter in the 1179 sets the <literal>backlog</literal> parameter in the
1181 <c-func>listen</c-func> call. 1180 <c-func>listen</c-func> call that limits
1182 By default, <literal>backlog</literal> equals -1 on FreeBSD 1181 the maximum length for the queue of pending connections.
1183 and 511 on other platforms. 1182 By default, <literal>backlog</literal> is set to -1 on FreeBSD,
1183 and to 511 on other platforms.
1184 </tag-desc> 1184 </tag-desc>
1185 1185
1186 <tag-name> 1186 <tag-name>
1187 <literal>rcvbuf</literal>=<value>size</value> 1187 <literal>rcvbuf</literal>=<value>size</value>
1188 </tag-name> 1188 </tag-name>
1189 <tag-desc> 1189 <tag-desc>
1190 sets the <c-def>SO_RCVBUF</c-def> parameter for the listening socket. 1190 sets receive buffer size
1191 (the <c-def>SO_RCVBUF</c-def> option) for the listening socket.
1191 </tag-desc> 1192 </tag-desc>
1192 1193
1193 <tag-name> 1194 <tag-name>
1194 <literal>sndbuf</literal>=<value>size</value> 1195 <literal>sndbuf</literal>=<value>size</value>
1195 </tag-name> 1196 </tag-name>
1196 <tag-desc> 1197 <tag-desc>
1197 sets the <c-def>SO_SNDBUF</c-def> parameter for the listening socket. 1198 sets send buffer size
1199 (the <c-def>SO_SNDBUF</c-def> option) for the listening socket.
1198 </tag-desc> 1200 </tag-desc>
1199 1201
1200 <tag-name> 1202 <tag-name>
1201 <literal>accept_filter</literal>=<value>filter</value> 1203 <literal>accept_filter</literal>=<value>filter</value>
1202 </tag-name> 1204 </tag-name>
1203 <tag-desc> 1205 <tag-desc>
1204 sets the name of the accept filter. 1206 sets the name of accept filter
1205 This works only on FreeBSD, acceptable values are <literal>dataready</literal> 1207 (the <c-def>SO_ACCEPTFILTER</c-def> option) for the listening socket
1206 and <literal>httpready</literal>. 1208 that filters incoming connections before presenting them to
1207 On receipt of the <c-def>SIGHUP</c-def> signal, an accept filter can only be 1209 <c-func>accept</c-func>.
1208 changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE 1210 This works only on FreeBSD and NetBSD 5.0+.
1209 and 4.11-STABLE. 1211 Acceptable values are
1212 <link url="http://man.freebsd.org/accf_data">dataready</link>
1213 and
1214 <link url="http://man.freebsd.org/accf_http">httpready</link>.
1210 </tag-desc> 1215 </tag-desc>
1211 1216
1212 <tag-name> 1217 <tag-name>
1213 <literal>deferred</literal> 1218 <literal>deferred</literal>
1214 </tag-name> 1219 </tag-name>
1215 <tag-desc> 1220 <tag-desc>
1216 instructs to use a deferred <c-func>accept</c-func> on Linux 1221 instructs to use a deferred <c-func>accept</c-func>
1217 using the <c-def>TCP_DEFER_ACCEPT</c-def> option. 1222 (the <c-def>TCP_DEFER_ACCEPT</c-def> socket option) on Linux.
1218 </tag-desc> 1223 </tag-desc>
1219 1224
1220 <tag-name> 1225 <tag-name>
1221 <literal>bind</literal> 1226 <literal>bind</literal>
1222 </tag-name> 1227 </tag-name>
1242 1247
1243 <tag-name> 1248 <tag-name>
1244 <literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal> 1249 <literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>
1245 </tag-name> 1250 </tag-name>
1246 <tag-desc> 1251 <tag-desc>
1247 this parameter (0.7.42) sets the value of the <c-def>IPV6_V6ONLY</c-def> 1252 this parameter (0.7.42) determines
1248 parameter for the listening socket. 1253 (via the <c-def>IPV6_V6ONLY</c-def> socket option)
1249 It is turned on by default. 1254 whether IPv6 socket listening on a wildcard address <literal>[::]</literal>
1250 This parameter can only be set once on start. 1255 will accept only IPv6 connections, or both IPv6 and IPv4 connections.
1256 This parameter is turned on by default.
1257 It can only be set once on start.
1251 <note> 1258 <note>
1252 Prior to version 1.3.4, if parameter was not set explicitly, 1259 Prior to version 1.3.4,
1253 operating system’s setting was used. 1260 if this parameter was omitted then the operating system’s settings were
1261 in effect for the socket.
1254 </note> 1262 </note>
1255
1256 </tag-desc> 1263 </tag-desc>
1257 1264
1258 <tag-name> 1265 <tag-name>
1259 <literal>ssl</literal> 1266 <literal>ssl</literal>
1260 </tag-name> 1267 </tag-name>
1261 <tag-desc> 1268 <tag-desc>
1262 this parameter (0.7.14) does not relate to system calls 1269 this parameter (0.7.14) does not relate to socket-related system calls,
1263 <c-func>listen</c-func> and <c-func>bind</c-func>, but allows to 1270 but allows to specify that all connections accepted on this port
1264 specify that all connections accepted on this port should work in 1271 should work in SSL mode.
1265 the SSL mode. 1272 This allows for a more compact <link doc="configuring_https_servers.xml"
1266 This allows for a more compact configuration for the server operating 1273 id="single_http_https_server">configuration</link> for the server that
1267 in both HTTP and HTTPS modes simultaneously. 1274 handles both HTTP and HTTPS requests.
1268 <example>
1269 listen 80;
1270 listen 443 ssl;
1271 </example>
1272 </tag-desc> 1275 </tag-desc>
1273 1276
1274 <tag-name> 1277 <tag-name>
1275 <literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>] 1278 <literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]
1276 </tag-name> 1279 </tag-name>
1277 <tag-desc> 1280 <tag-desc>
1278 this parameter (1.1.11) configures the “TCP keepalive” behavior 1281 this parameter (1.1.11) configures the “TCP keepalive” behavior
1279 for the listening socket. 1282 for the listening socket.
1280 If this parameter is omitted then the system default setting will be 1283 If this parameter is omitted then the operating system’s settings will be
1281 in effect for the socket. 1284 in effect for the socket.
1282 If set to the value “<literal>on</literal>”, the <c-def>SO_KEEPALIVE</c-def> 1285 If set to the value “<literal>on</literal>”, the <c-def>SO_KEEPALIVE</c-def>
1283 socket option is turned on for the socket. 1286 socket option is turned on for the socket.
1284 If set to the value “<literal>off</literal>”, the <c-def>SO_KEEPALIVE</c-def> 1287 If set to the value “<literal>off</literal>”, the <c-def>SO_KEEPALIVE</c-def>
1285 socket option is turned off for the socket. 1288 socket option is turned off for the socket.
1303 </para> 1306 </para>
1304 1307
1305 <para> 1308 <para>
1306 Example: 1309 Example:
1307 <example> 1310 <example>
1308 listen 127.0.0.1 default accept_filter=dataready backlog=1024; 1311 listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;
1309 </example> 1312 </example>
1310 </para> 1313 </para>
1311 1314
1312 </directive> 1315 </directive>
1313 1316