====== Директивы модуля ngx_mail_core_module ======

По умолчанию модули mail не собирается, нужно разрешить его сборку при конфигурировании параметром --with-mail.

===== Пример конфигурации =====

    # для проксирования pop3/imap/smtp рекомендуется установить равным числу CPU
    worker_processes  1;
    
    error_log  /var/log/nginx/error.log info;
    
    mail {
        server_name  mail.example.ru;
        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;
            # По RFC 2821 таймаут должен быть 300 секунд
            timeout            300s;
        }
        server {
            listen     110;
            protocol   pop3;
            proxy      on;
            proxy_pass_error_message  on;
        }
        server {
            listen     143;
            protocol   imap;
            proxy      on;
        }
        server {
            listen              587;
            protocol           smtp;
            timeout            300s;
        }
    }


===== Директивы =====

==== imap_capabilities ====
**syntax**: imap_capabilities //**"capability1" ["capability2" .. "capabilityN"]**//\\
**default**: "IMAP4" "IMAP4rev1" "UIDPLUS"\\
**context**: mail, server

Директива позволяет указать список расширений [[http://ietf.org/rfc/rfc3501.txt|протокола IMAP]], выдаваемый клиенту по команде CAPABILITY. К этому списку автоматически добавляется [[http://ietf.org/rfc/rfc2595.txt|STARTTLS]] если включена директива [[ngx_mail_ssl_module#starttls|starttls]]

В данной директиве имеет смысл указать расширения поддерживаемые pop3-бэкендами на которые проксируются клиенты (если эти расширения относятся к командам используемым после авторизации, когда nginx прозрачно проксирует подключение клиента на бэкенд).

Текущий список стандартизованных расширений опубликован на [[http://www.iana.org/assignments/imap4-capabilities|www.iana.org]].

==== imap_client_buffer ====
**syntax**: imap_client_buffer //**размер**//\\
**default**: 4k/8k\\
**context**: mail, server

Задаёт размер буфера, используемого для чтения imap комманд. По умолчанию размер буфера равен размеру страницы, в зависимости от платформы это или 4K, или 8K.

==== listen ====
**syntax**: listen //**адрес:порт [bind]**//\\
**default**: нет\\
**context**: server

Директива задаёт адрес и порт, на которых сервер принимает запросы. Можно указать только порт, кроме того, адрес может быть именем сервера, например:

    listen  127.0.0.1:110;
    listen  *:110;
    listen  110;   # то же самое что *:110
    listen  localhost:110;

  * bind — указывает, что для данной пары адрес:порт нужно делать bind(2) отдельно. Дело в том, что если описаны несколько директив listen с одинаковым портом, но разными адресами и одна из директив listen слушает на всех адресах для данного порта (*:порт), то nginx сделает bind(2) только на *:порт. Необходимо учитывать, что в этом случае для определения адреса, на которой пришло соединение, делается системный вызов getsockname().

Разные виртуальные сервера должны слушать разные пары ip и port.

==== pop3_auth ====
**syntax**: pop3_auth //**[plain] [apop] [cram-md5]**//\\
**default**: plain\\
**context**: mail, server

Директива задаёт разрешенные методы аутентификации **pop3** клиентов:
  * plan - [[http://ietf.org/rfc/rfc1939.txt|USER/PASS]], [[http://ietf.org/rfc/rfc2595.txt|AUTH PLAIN]], {{:draft-murchison-sasl-login-00.txt|AUTH LOGIN}}. Данные методы отключить нельзя.
  * apop - [[http://ietf.org/rfc/rfc1939.txt|APOP]] - для работы этого метода в базе пользователей должен храниться пароль в plain-text
  * cram-md5 - [[http://ietf.org/rfc/rfc2195.txt|AUTH CRAM-MD5]] - при этом методе то же необходим пароль в виде plain-text.

==== pop3_capabilities ====
**syntax**: pop3_capabilities //**"capability1" ["capability2" .. "capabilityN"]**//\\
**default**: "TOP" "USER" "UIDL"\\
**context**: mail, server

Директива позволяет указать список [[http://ietf.org/rfc/rfc2449.txt|расширений протокола POP3]], выдаваемый клиенту по команде CAPA. К этому списку автоматически добавляются методы авторизации, указанные в директиве auth [[ngx_mail_core_module#auth|auth]] ([[http://ietf.org/rfc/rfc2449.txt|SASL]] capability) и [[http://ietf.org/rfc/rfc2595.txt|STLS]] если включена директива [[ngx_mail_ssl_module#starttls|starttls]]

В данной директиве имеет смысл указать расширения поддерживаемые imap-бэкендами на которые проксируются клиенты (если эти расширения относятся к командам используемым после авторизации, когда nginx прозрачно проксирует подключение клиента на бэкенд).

Текущий список стандартизованных расширений опубликован на [[http://www.iana.org/assignments/pop3-extension-mechanism|www.iana.org]].

==== protocol ====

**syntax**: protocol //**imap|pop3|smtp**//\\
**default**: mail\\
**context**: server

==== server ====
**syntax**: server //**{ ... }**//\\
**default**: нет\\
**context**: imap

Директива задаёт конфигурацию для виртуального сервера.

==== server_name ====
**syntax**: server_name //**fqdn_server_host**//\\
**default**: имя хоста, полученное через gethostname()\\
**context**: mail, server

Задает имя сервера, используемое:
  * В начальном приветствии pop3/smtp-сервера
  * В salt при авторизации SASL-методом CRAM-MD5
  * В команде EHLO при подключении к SMTP-бэкенду если включена команда [[ngx_mail_proxy_module#xclient|xclient]]

==== smtp_auth ====
**syntax**: smtp_auth //**[login] [plain] [cram-md5]**//\\
**default**: login plain\\
**context**: mail, server

Директива задаёт разрешенные методы [[http://ietf.org/rfc/rfc2554.txt|SASL аутентификации]] **smtp** клиентов:
  * login - {{:draft-murchison-sasl-login-00.txt|AUTH LOGIN}}
  * plain - [[http://ietf.org/rfc/rfc2595.txt|AUTH PLAIN]]
  * cram-md5 - [[http://ietf.org/rfc/rfc2195.txt|AUTH CRAM-MD5]] - при этом методе необходим пароль в виде plain-text.

==== smtp_capabilities ====
**syntax**: smtp_capabilities //**"capability1" ["capability2" .. "capabilityN"]**//\\
**default**: нет\\
**context**: mail, server

Директива позволяет указать список расширений протокола SMTP, выдаваемый клиенту в ответе на команду EHLO. К этому списку автоматически добавляются методы авторизации, указанные в директиве smtp_auth [[ngx_mail_core_module#smtp_auth|smtp_auth]].

В данной директиве имеет смысл указать расширения поддерживаемые MTA на который проксируются клиенты (если эти расширения относятся к командам используемым после авторизации, когда nginx прозрачно проксирует подключение клиента на бэкенд).

Текущий список стандартизованных расширений опубликован на [[http://www.iana.org/assignments/mail-parameters|www.iana.org]].

==== so_keepalive ====
**syntax**: so_keepalive //**on|off**//\\
**default**: off\\
**context**: mail, server

Устанавливать опцию сокета SO_KEEPALIVE при подключении к imap/pop3 бэкенду.
Во FreeBSD keepalive используются по умолчанию для всех соединений и необходимости явно задавать это через setsockopt нет (см. sysctl net.inet.tcp.always_keepalive).

==== timeout ====
**syntax**: timeout //**время**//\\
**default**: timeout 60\\
**context**: mail, server\\

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