<?xml version="1.0"?>

<!--
  Copyright (C) 2006, 2007 Anton Yuzhaninov
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_mail_core_module"
        link="/ru/docs/mail/ngx_mail_core_module.html"
        lang="ru"
        rev="23">

<section id="summary">

<para>
По умолчанию этот модуль не собирается, его сборку необходимо
разрешить с помощью конфигурационного параметра
<literal>--with-mail</literal>.
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
<example>
worker_processes auto;

error_log /var/log/nginx/error.log info;

events {
    worker_connections  1024;
}

mail {
    server_name       mail.example.com;
    auth_http         localhost:9000/cgi-bin/nginxauth.cgi;

    imap_capabilities IMAP4rev1 UIDPLUS IDLE LITERAL+ QUOTA;

    pop3_auth         plain apop cram-md5;
    pop3_capabilities LAST TOP USER PIPELINING UIDL;

    smtp_auth         login plain cram-md5;
    smtp_capabilities "SIZE 10485760" ENHANCEDSTATUSCODES 8BITMIME DSN;
    xclient           off;

    server {
        listen   25;
        protocol smtp;
    }
    server {
        listen   110;
        protocol pop3;
        proxy_pass_error_message on;
    }
    server {
        listen   143;
        protocol imap;
    }
    server {
        listen   587;
        protocol smtp;
    }
}
</example>
</para>

</section>


<section id="directives" name="Директивы">

<directive name="listen">
<syntax>
    <value>адрес</value>:<value>порт</value>
    [<literal>ssl</literal>]
    [<literal>proxy_protocol</literal>]
    [<literal>backlog</literal>=<value>число</value>]
    [<literal>rcvbuf</literal>=<value>размер</value>]
    [<literal>sndbuf</literal>=<value>размер</value>]
    [<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>

<para>
Задаёт <value>адрес</value> и <value>порт</value> сокета, на котором сервер
будет принимать запросы.
Можно указать только порт.
Кроме того, адрес может быть именем сервера, например:
<example>
listen 127.0.0.1:110;
listen *:110;
listen 110;     # то же, что и *:110
listen localhost:110;
</example>
IPv6-адреса (0.7.58) задаются в квадратных скобках:
<example>
listen [::1]:110;
listen [::]:110;
</example>
UNIX-сокеты (1.3.5) задаются при помощи префикса “<literal>unix:</literal>”:
<example>
listen unix:/var/run/nginx.sock;
</example>

</para>

<para>
Разные серверы должны слушать на разных парах
<value>адрес</value>:<value>порт</value>.
</para>

<para>
Параметр <literal>ssl</literal> указывает на то, что все соединения,
принимаемые на данном порту, должны работать в режиме SSL.
</para>

<para id="proxy_protocol">
Параметр <literal>proxy_protocol</literal> (1.19.8)
указывает на то, что все соединения, принимаемые на данном порту,
должны использовать
<link url="http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt">протокол
PROXY</link>.
Полученная информация передаётся
<link doc="ngx_mail_auth_http_module.xml" id="proxy_protocol">серверу аутентификации</link>
и может быть использована для
<link doc="ngx_mail_realip_module.xml">изменения адреса клиента</link>.
</para>

<para>
В директиве <literal>listen</literal> можно также указать несколько
дополнительных параметров, специфичных для связанных с сокетами
системных вызовов.
<list type="tag">

<tag-name>
<literal>backlog</literal>=<value>число</value>
</tag-name>
<tag-desc>
задаёт параметр <literal>backlog</literal> в вызове
<c-func>listen</c-func>, который ограничивает
максимальный размер очереди ожидающих приёма соединений (1.9.2).
По умолчанию <literal>backlog</literal> устанавливается равным -1 для
FreeBSD, DragonFly BSD и macOS, и 511 для других платформ.
</tag-desc>

<tag-name>
<literal>rcvbuf</literal>=<value>размер</value>
</tag-name>
<tag-desc>
задаёт размер буфера приёма
(параметр <c-def>SO_RCVBUF</c-def>) для слушающего сокета (1.11.13).
</tag-desc>

<tag-name>
<literal>sndbuf</literal>=<value>размер</value>
</tag-name>
<tag-desc>
задаёт размер буфера передачи
(параметр <c-def>SO_SNDBUF</c-def>) для слушающего сокета (1.11.13).
</tag-desc>

<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>*:</literal><value>порт</value>), то nginx сделает
<c-func>bind</c-func> только на <literal>*:</literal><value>порт</value>.
Необходимо заметить, что в этом случае для определения адреса, на который
пришло соединение, делается системный вызов <c-func>getsockname</c-func>.
Если же используются параметры <literal>backlog</literal>,
<literal>rcvbuf</literal>, <literal>sndbuf</literal>,
<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>

</directive>


<directive name="mail">
<syntax block="yes"/>
<default/>
<context>main</context>

<para>
Предоставляет контекст конфигурационного файла, в котором указываются
директивы почтового сервера.
</para>

</directive>


<directive name="max_commands">
<syntax><value>число</value></syntax>
<default>1000</default>
<context>mail</context>
<context>server</context>
<appeared-in>1.25.5</appeared-in>

<para>
Задаёт максимальное количество команд, допускаемое в процессе аутентификации.
Если ограничение достигнуто, а проксирование на бэкенд не началось,
соединение закрывается.
</para>

</directive>


<directive name="max_errors">
<syntax><value>число</value></syntax>
<default>5</default>
<context>mail</context>
<context>server</context>
<appeared-in>1.21.0</appeared-in>

<para>
Задаёт число ошибок протокола, по достижении которого соединение закрывается.
</para>

</directive>


<directive name="protocol">
<syntax>
  <literal>imap</literal> |
  <literal>pop3</literal> |
  <literal>smtp</literal></syntax>
<default/>
<context>server</context>

<para>
Задаёт протокол проксируемого сервера.
Поддерживаются протоколы
<link doc="ngx_mail_imap_module.xml">IMAP</link>,
<link doc="ngx_mail_pop3_module.xml">POP3</link> и
<link doc="ngx_mail_smtp_module.xml">SMTP</link>.
</para>

<para>
Если директива не указана, то протокол может быть определён автоматически
по общеизвестному порту, указанному в директиве <link id="listen"/>:
<list type="bullet">

<listitem>
<literal>imap</literal>: 143, 993
</listitem>

<listitem>
<literal>pop3</literal>: 110, 995
</listitem>

<listitem>
<literal>smtp</literal>: 25, 587, 465
</listitem>

</list>
</para>

<para>
Поддержку ненужных протоколов можно отключить с помощью
<link doc="../configure.xml">конфигурационных</link>
параметров <literal>--without-mail_imap_module</literal>,
<literal>--without-mail_pop3_module</literal> и
<literal>--without-mail_smtp_module</literal>.
</para>

</directive>


<directive name="resolver">
<syntax>
    <value>адрес</value> ...
    [<literal>valid</literal>=<value>time</value>]
    [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>]
    [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax>
<syntax><literal>off</literal></syntax>
<default>off</default>
<context>mail</context>
<context>server</context>

<para>
Задаёт серверы DNS, используемые для определения имени хоста клиента
для передачи его на
<link doc="ngx_mail_auth_http_module.xml">сервер аутентификации</link>
и в команде
<link doc="ngx_mail_proxy_module.xml" id="xclient">XCLIENT</link>
при проксировании SMTP.
Например:
<example>
resolver 127.0.0.1 [::1]:5353;
</example>
Адрес может быть указан в виде доменного имени или IP-адреса,
и необязательного порта (1.3.1, 1.2.2).
Если порт не указан, используется порт 53.
Серверы DNS опрашиваются циклически.
<note>
До версии 1.1.7 можно было задать лишь один DNS-сервер.
Задание DNS-серверов с помощью IPv6-адресов поддерживается
начиная с версий 1.3.1 и 1.2.2.
</note>
</para>

<para id="resolver_ipv6">
По умолчанию nginx будет искать как IPv4-, так и IPv6-адреса
при преобразовании имён в адреса.
Если поиск IPv4- или IPv6-адресов нежелателен,
можно указать параметр <literal>ipv4=off</literal> (1.23.1) или
<literal>ipv6=off</literal>.
<note>
Преобразование имён в IPv6-адреса поддерживается
начиная с версии 1.5.8.
</note>
</para>

<para id="resolver_valid">
По умолчанию nginx кэширует ответы, используя значение TTL из ответа.
Необязательный параметр <literal>valid</literal> позволяет это
переопределить:
<example>
resolver 127.0.0.1 [::1]:5353 valid=30s;
</example>
<note>
До версии 1.1.9 настройка времени кэширования была невозможна
и nginx всегда кэшировал ответы на срок в 5 минут.
</note>
<note>
Для предотвращения DNS-спуфинга рекомендуется
использовать DNS-серверы в защищённой доверенной локальной сети.
</note>
</para>

<para id="resolver_off">
Специальное значение <literal>off</literal> запрещает использование DNS.
</para>

</directive>


<directive name="resolver_timeout">
<syntax><value>время</value></syntax>
<default>30s</default>
<context>mail</context>
<context>server</context>

<para>
Задаёт таймаут для операций DNS, например:
<example>
resolver_timeout 5s;
</example>
</para>

</directive>


<directive name="server">
<syntax block="yes"/>
<default/>
<context>mail</context>

<para>
Задаёт конфигурацию для сервера.
</para>

</directive>


<directive name="server_name">
<syntax><value>имя</value></syntax>
<default>hostname</default>
<context>mail</context>
<context>server</context>

<para>
Задаёт имя сервера, используемое:
<list type="bullet">

<listitem>
в начальном приветствии POP3/SMTP-сервера;
</listitem>

<listitem>
в salt при аутентификации SASL-методом CRAM-MD5;
</listitem>

<listitem>
в команде <literal>EHLO</literal> при подключении к SMTP-бэкенду,
если разрешена передача команды
<link doc="ngx_mail_proxy_module.xml" id="xclient">XCLIENT</link>.
</listitem>

</list>
</para>

<para>
Если директива не указана, используется имя хоста (hostname) машины.
</para>

</directive>


<directive name="timeout">
<syntax><value>время</value></syntax>
<default>60s</default>
<context>mail</context>
<context>server</context>

<para>
Задаёт таймаут, который используется до начала проксирования на бэкенд.
</para>

</directive>

</section>

</module>