Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_core_module.xml @ 617:368a449e85b8
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 |