Mercurial > hg > nginx-site
changeset 1488:0a1c5a087556
Documented bind/ipv6only/ssl/so_keepalive in mail listen directive.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Mon, 25 May 2015 13:22:48 +0300 |
parents | 269e8de8765a |
children | 9f9b8543b946 |
files | xml/en/docs/mail/ngx_mail_core_module.xml xml/ru/docs/mail/ngx_mail_core_module.xml |
diffstat | 2 files changed, 138 insertions(+), 8 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/mail/ngx_mail_core_module.xml +++ b/xml/en/docs/mail/ngx_mail_core_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_mail_core_module" link="/en/docs/mail/ngx_mail_core_module.html" lang="en" - rev="4"> + rev="5"> <section id="summary"> @@ -73,7 +73,10 @@ mail { <directive name="listen"> <syntax> <value>address</value>:<value>port</value> - [<literal>bind</literal>]</syntax> + [<literal>ssl</literal>] + [<literal>bind</literal>] + [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax> <default/> <context>server</context> @@ -102,8 +105,20 @@ listen unix:/var/run/nginx.sock; </para> <para> -The optional <literal>bind</literal> parameter -instructs to make a separate <c-func>bind</c-func> +The <literal>ssl</literal> parameter allows specifying that all +connections accepted on this port should work in SSL mode. +</para> + +<para> +The <literal>listen</literal> directive +can have several additional parameters specific to socket-related system calls. +<list type="tag"> + +<tag-name> +<literal>bind</literal> +</tag-name> +<tag-desc> +this parameter instructs to make a separate <c-func>bind</c-func> call for a given address:port pair. The fact is that if there are several <literal>listen</literal> directives with the same port but different addresses, and one of the @@ -112,6 +127,54 @@ for the given port (<literal>*:</literal <c-func>bind</c-func> only to <literal>*:</literal><value>port</value>. It should be noted that the <c-func>getsockname</c-func> system call will be made in this case to determine the address that accepted the connection. +If the <literal>ipv6only</literal> +or <literal>so_keepalive</literal> parameters +are used then for a given +<value>address</value>:<value>port</value> pair +a separate <c-func>bind</c-func> call will always be made. +</tag-desc> + +<tag-name> +<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal> +</tag-name> +<tag-desc> +this parameter determines +(via the <c-def>IPV6_V6ONLY</c-def> socket option) +whether an IPv6 socket listening on a wildcard address <literal>[::]</literal> +will accept only IPv6 connections or both IPv6 and IPv4 connections. +This parameter is turned on by default. +It can only be set once on start. +</tag-desc> + +<tag-name> +<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>] +</tag-name> +<tag-desc> +this parameter configures the “TCP keepalive” behavior +for the listening socket. +If this parameter is omitted then the operating system’s settings will be +in effect for the socket. +If it is set to the value “<literal>on</literal>”, the +<c-def>SO_KEEPALIVE</c-def> option is turned on for the socket. +If it is set to the value “<literal>off</literal>”, the +<c-def>SO_KEEPALIVE</c-def> option is turned off for the socket. +Some operating systems support setting of TCP keepalive parameters on +a per-socket basis using the <c-def>TCP_KEEPIDLE</c-def>, +<c-def>TCP_KEEPINTVL</c-def>, and <c-def>TCP_KEEPCNT</c-def> socket options. +On such systems (currently, Linux 2.4+, NetBSD 5+, and +FreeBSD 9.0-STABLE), they can be configured +using the <value>keepidle</value>, <value>keepintvl</value>, and +<value>keepcnt</value> parameters. +One or two parameters may be omitted, in which case the system default setting +for the corresponding socket option will be in effect. +For example, +<example>so_keepalive=30m::10</example> +will set the idle timeout (<c-def>TCP_KEEPIDLE</c-def>) to 30 minutes, +leave the probe interval (<c-def>TCP_KEEPINTVL</c-def>) at its system default, +and set the probes count (<c-def>TCP_KEEPCNT</c-def>) to 10 probes. +</tag-desc> + +</list> </para> <para>
--- a/xml/ru/docs/mail/ngx_mail_core_module.xml +++ b/xml/ru/docs/mail/ngx_mail_core_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_mail_core_module" link="/ru/docs/mail/ngx_mail_core_module.html" lang="ru" - rev="4"> + rev="5"> <section id="summary"> @@ -73,7 +73,10 @@ mail { <directive name="listen"> <syntax> <value>адрес</value>:<value>порт</value> - [<literal>bind</literal>]</syntax> + [<literal>ssl</literal>] + [<literal>bind</literal>] + [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax> <default/> <context>server</context> @@ -101,17 +104,81 @@ listen unix:/var/run/nginx.sock; </para> <para> -Необязательный параметр <literal>bind</literal> +Параметр <literal>ssl</literal> указывает на то, что все соединения, +принимаемые на данном порту, должны работать в режиме SSL. +</para> + +<para> +В директиве <literal>listen</literal> можно также указать несколько +дополнительных параметров, специфичных для связанных с сокетами +системных вызовов. +<list type="tag"> + +<tag-name> +<literal>bind</literal> +</tag-name> +<tag-desc> указывает, что для данной пары <value>адрес</value>:<value>порт</value> нужно делать <c-func>bind</c-func> отдельно. -Дело в том, что если описаны несколько директив <literal>listen</literal> +Это нужно потому, что если описаны несколько директив <literal>listen</literal> с одинаковым портом, но разными адресами, и одна из директив <literal>listen</literal> слушает на всех адресах для данного порта (<literal>*:</literal><value>порт</value>), то nginx сделает <c-func>bind</c-func> только на <literal>*:</literal><value>порт</value>. Необходимо заметить, что в этом случае для определения адреса, на который пришло соединение, делается системный вызов <c-func>getsockname</c-func>. +Если же используются параметры <literal>ipv6only</literal> +или <literal>so_keepalive</literal>, +то для данной пары +<value>адрес</value>:<value>порт</value> всегда делается +отдельный вызов <c-func>bind</c-func>. +</tag-desc> + +<tag-name> +<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal> +</tag-name> +<tag-desc> +этот параметр определяет +(через параметр сокета <c-def>IPV6_V6ONLY</c-def>), +будет ли слушающий на wildcard-адресе <literal>[::]</literal> IPv6-сокет +принимать только IPv6-соединения, или же одновременно IPv6- и IPv4-соединения. +По умолчанию параметр включён. +Установить его можно только один раз на старте. +</tag-desc> + +<tag-name> +<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>] +</tag-name> +<tag-desc> +этот параметр конфигурирует для слушающего сокета +поведение “TCP keepalive”. +Если этот параметр опущен, то для сокета будут действовать +настройки операционной системы. +Если он установлен в значение “<literal>on</literal>”, то для сокета +включается параметр <c-def>SO_KEEPALIVE</c-def>. +Если он установлен в значение “<literal>off</literal>”, то для сокета +параметр <c-def>SO_KEEPALIVE</c-def> выключается. +Некоторые операционные системы поддерживают настройку параметров +“TCP keepalive” на уровне сокета посредством параметров +<c-def>TCP_KEEPIDLE</c-def>, <c-def>TCP_KEEPINTVL</c-def> и +<c-def>TCP_KEEPCNT</c-def>. +На таких системах (в настоящий момент это Linux 2.4+, NetBSD 5+ и +FreeBSD 9.0-STABLE) +их можно сконфигурировать с помощью параметров <value>keepidle</value>, +<value>keepintvl</value> и <value>keepcnt</value>. +Один или два параметра могут быть опущены, в таком случае для +соответствующего параметра сокета будут действовать стандартные +системные настройки. +Например, +<example>so_keepalive=30m::10</example> +установит таймаут бездействия (<c-def>TCP_KEEPIDLE</c-def>) в 30 минут, +для интервала проб (<c-def>TCP_KEEPINTVL</c-def>) будет действовать +стандартная системная настройка, а счётчик проб (<c-def>TCP_KEEPCNT</c-def>) +будет равен 10. +</tag-desc> + +</list> </para> <para>