<a id="adc-mail-core"></a>

# Почтовый модуль

Базовый почтовый модуль реализует основную функциональность почтового
прокси-сервера: это поддержка протоколов SMTP, IMAP и POP3, настройка серверных
блоков, маршрутизация почтовых запросов, аутентификация пользователей и
поддержка SSL/TLS для защиты почтовых соединений.

Остальные модули этого раздела расширяют эту функциональность, позволяя гибко
настраивать и оптимизировать работу почтового сервера под различные сценарии и
требования.

В образах из наших репозиториев модуль уже включен в сборку.

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

```nginx
worker_processes auto;

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

events {
    worker_connections  1024;
}

mail {
    server_name       mail.example.com;
    auth_http         localhost:9000/cgi-bin/auth.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;
    }
}
```

## Директивы

<a id="index-0"></a>

<a id="adc-m-listen"></a>

### listen

| [Синтаксис](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)   | `listen` адрес[:порт] [`ssl`] [`proxy_protocol`] [`backlog=`число] [`rcvbuf=`размер] [`sndbuf=`размер] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]];   |
|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию                                                                                            | —                                                                                                                                                                                                                         |
| [Контекст](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)    | server                                                                                                                                                                                                                    |

Задает адрес и порт для сокета, на котором сервер будет принимать соединения. Можно указать только порт, и тогда Angie будет слушать на всех доступных IPv4-интерфейсах (и IPv6, если он включен). Кроме того, адрес может быть именем хоста, например:

```nginx
listen 127.0.0.1:110;
listen *:110;
listen 110;     # то же, что и *:110
listen localhost:110;
```

IPv6-адреса задаются в квадратных скобках:

```nginx
listen [::1]:110;
listen [::]:110;
```

UNIX-сокеты задаются префиксом `unix:`

```nginx
listen unix:/var/run/angie.sock;
```

#### NOTE
Разные серверы должны слушать на разных парах адрес:порт.

| `ssl`            | указывает на то, что все соединения, принимаемые на данном слушающем сокете, должны работать в режиме SSL.                                                                                                                                                                                                                                                                                                                         |
|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `proxy_protocol` | указывает на то, что все соединения, принимаемые на данном порту, должны использовать протокол PROXY.  Полученная информация передается [серверу аутентификации](https://angie.software//adc/docs/configuration_lb/reference/mail/mail_auth_http.md#adc-mail-auth-http) и может быть использована для [изменения адреса клиента](https://angie.software//adc/docs/configuration_lb/reference/mail/mail_realip.md#adc-mail-realip). |

В директиве `listen` можно также указать несколько дополнительных параметров, специфичных для связанных с сокетами системных вызовов.

| `backlog=`число       | задает параметр backlog в вызове listen(), который ограничивает максимальный размер очереди ожидающих приема соединений. По умолчанию backlog устанавливается равным -1 для FreeBSD, DragonFly BSD и macOS, и 511 для других платформ.                                                                                                                                                                                                                                                                                                                                                                                   |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `rcvbuf=`размер       | задает размер буфера приема (параметр SO_RCVBUF) для слушающего сокета.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `sndbuf=`размер       | задает размер буфера передачи (параметр SO_SNDBUF) для слушающего сокета.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `bind`                | указывает, что для данного слушающего сокета нужно делать bind() отдельно. Это нужно потому, что если описаны несколько директив `listen` с одинаковым портом, но разными адресами, и одна из директив `listen` слушает на всех адресах для данного порта (\*:порт), то Angie сделает bind() только на \*:порт. Необходимо заметить, что в этом случае для определения адреса, на который пришло соединение, делается системный вызов getsockname(). Если же используются параметры backlog, rcvbuf, sndbuf, ipv6only, reuseport или so_keepalive, то для данной пары адрес:порт всегда делается отдельный вызов bind(). |
| `ipv6only=on` | `off` | определяет (через параметр сокета `IPV6_V6ONLY`), будет ли слушающий на wildcard-адресе [::] IPv6-сокет принимать только IPv6-соединения, или же одновременно IPv6- и IPv4-соединения. По умолчанию параметр включен. Установить его можно только один раз на старте.                                                                                                                                                                                                                                                                                                                                                    |
| `multipath`           | включает прием соединений по протоколу [Multipath TCP](https://en.wikipedia.org/wiki/Multipath_TCP) (MPTCP),<br/>поддерживаемому в ядре Linux с версии 5.6.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

`so_keepalive=on` | `off` | [`keepidle`]:[`keepintvl`]:[`keepcnt`]

Конфигурирует для слушающего сокета поведение "TCP keepalive".

| `''`   | если параметр опущен, для сокета будут действовать настройки операционной системы   |
|--------|-------------------------------------------------------------------------------------|
| `on`   | для сокета включается параметр SO_KEEPALIVE                                         |
| `off`  | для сокета параметр SO_KEEPALIVE выключается                                        |

Некоторые операционные системы поддерживают настройку параметров "TCP keepalive"
на уровне сокета посредством параметров `TCP_KEEPIDLE`, `TCP_KEEPINTVL` и
`TCP_KEEPCNT`. На таких системах их можно сконфигурировать с помощью параметров
`keepidle`, `keepintvl` и `keepcnt`. Один или два параметра могут быть опущены,
в таком случае для соответствующего параметра сокета будут действовать
стандартные системные настройки.

Например,

```nginx
so_keepalive=30m::10
```

установит таймаут бездействия (`TCP_KEEPIDLE`) в 30 минут, для интервала проб (`TCP_KEEPINTVL`) будет действовать стандартная системная настройка, а счетчик проб (`TCP_KEEPCNT`) будет равен 10.

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

<a id="index-1"></a>

<a id="adc-m-mail"></a>

### mail

| [Синтаксис](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)   | `mail` { ... }   |
|---------------------------------------------------------------------------------------------------------|------------------|
| По умолчанию                                                                                            | —                |
| [Контекст](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)    | main             |

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

<a id="index-2"></a>

<a id="adc-max-commands"></a>

### max_commands

| [Синтаксис](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)   | `max_commands` число;   |
|---------------------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию                                                                                            | `max_commands 1000;`    |
| [Контекст](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)    | mail, server            |

Задает максимальное количество команд, отправляемых во время аутентификации,
для усиления защиты от DoS-атак.

<a id="index-3"></a>

<a id="adc-m-max-errors"></a>

### max_errors

| [Синтаксис](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)   | `max_errors` число;   |
|---------------------------------------------------------------------------------------------------------|-----------------------|
| По умолчанию                                                                                            | `max_errors 5;`       |
| [Контекст](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)    | mail, server          |

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

<a id="index-4"></a>

<a id="adc-m-protocol"></a>

### protocol

| [Синтаксис](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)   | `protocol` imap | pop3 | smtp;   |
|---------------------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию                                                                                            | —                                |
| [Контекст](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)    | server                           |

Задает протокол проксируемого сервера. Поддерживаются протоколы [IMAP](https://angie.software//adc/docs/configuration_lb/reference/mail/mail_imap.md#adc-mail-imap), [POP3](https://angie.software//adc/docs/configuration_lb/reference/mail/mail_pop3.md#adc-mail-pop3) и [SMTP](https://angie.software//adc/docs/configuration_lb/reference/mail/mail_smtp.md#adc-mail-smtp).

Если директива не указана, то протокол может быть определен автоматически по общеизвестному порту, указанному в директиве `listen`:

```console
imap: 143, 993
pop3: 110, 995
smtp: 25, 587, 465
```

<a id="index-5"></a>

<a id="adc-m-resolver"></a>

### resolver

| [Синтаксис](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)   | `resolver` адрес ... [`valid=`время] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`зона] | `off`;   |
|---------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| По умолчанию                                                                                            | `resolver off;`                                                                                                  |
| [Контекст](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)    | mail, server                                                                                                     |

Задает серверы DNS, используемые для преобразования имени хоста клиента для передачи его на [сервер аутентификации](https://angie.software//adc/docs/configuration_lb/reference/mail/mail_auth_http.md#adc-mail-auth-http) и в команде [XCLIENT](https://angie.software//adc/docs/configuration_lb/reference/mail/mail_proxy.md#adc-m-xclient) при проксировании SMTP, например:

```nginx
resolver 127.0.0.53 [::1]:5353;
```

Специальное значение `off` отключает преобразование имени хоста клиента и отменяет унаследованное значение директивы.

Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта.
Если порт не указан, используется порт 53. Серверы DNS опрашиваются циклически.

#### NOTE
Рекомендуется использовать локальный доверенный резолвер, например
`127.0.0.53` (systemd-resolved), а не публичный (например, `8.8.8.8`).
Публичные резолверы раскрывают DNS-запросы третьим сторонам и повышают
риск атак с подменой кэша.

#### NOTE
Значение директивы наследуется вложенными блоками
и может быть переопределено в них при необходимости.
В пределах одного блока допустимо указывать директиву только один раз.
Если она повторяется, действует последнее определение.

По умолчанию Angie кэширует ответы, используя значение TTL из ответа DNS. Если
директива `resolver` не указана и не выполняются динамические DNS-запросы
(например, при использовании фиксированных имен в [Proxy](https://angie.software//adc/docs/configuration_lb/reference/mail/mail_proxy.md#adc-mail-proxy) без
переменных), указание резолвера не требуется: имена будут разрешены при запуске
с помощью системного резолвера. Необязательный параметр `valid` позволяет
это переопределить:

| `valid`   |  *необязательный* параметр, позволяет переопределить срок кэширования ответа   |
|-----------|--------------------------------------------------------------------------------|
```nginx
resolver 127.0.0.53 [::1]:5353 valid=30s;
```

По умолчанию Angie будет искать как IPv4-, так и IPv6-адреса при преобразовании имен в адреса.

| `ipv4=off`    | запрещает поиск IPv4-адресов                                                                          |
|---------------|-------------------------------------------------------------------------------------------------------|
| `ipv6=off`    | запрещает поиск IPv6-адресов                                                                          |
| `status_zone` | *необязательный* параметр, включает сбор информации о запросах и ответах сервера DNS в указанной зоне |

<a id="index-6"></a>

<a id="adc-m-resolver-timeout"></a>

### resolver_timeout

| [Синтаксис](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)   | `resolver_timeout` время;   |
|---------------------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию                                                                                            | `resolver_timeout 30s;`     |
| [Контекст](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)    | mail, server                |

Задает таймаут для преобразования имени в адрес, например:

```nginx
resolver_timeout 5s;
```

<a id="index-7"></a>

<a id="adc-m-server"></a>

### server

| [Синтаксис](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)   | `server` { ... }   |
|---------------------------------------------------------------------------------------------------------|--------------------|
| По умолчанию                                                                                            | —                  |
| [Контекст](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)    | mail               |

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

<a id="index-8"></a>

<a id="adc-m-server-name"></a>

### server_name

| [Синтаксис](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)   | `server_name` имя;      |
|---------------------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию                                                                                            | `server_name hostname`; |
| [Контекст](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)    | mail, server            |

Задает имя сервера, используемое:

* в начальном приветствии POP3/SMTP-сервера;
* в salt при аутентификации SASL-методом CRAM-MD5;
* в команде EHLO при подключении к SMTP-бэкенду, если разрешена передача команды [XCLIENT](https://angie.software//adc/docs/configuration_lb/reference/mail/mail_proxy.md#adc-m-xclient).

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

<a id="index-9"></a>

<a id="adc-m-timeout"></a>

### timeout

| [Синтаксис](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)   | `timeout` время;   |
|---------------------------------------------------------------------------------------------------------|--------------------|
| По умолчанию                                                                                            | `timeout 60s;`     |
| [Контекст](https://angie.software//adc/docs/configuration_lb/reference/configfile.md#adc-configfile)    | mail, server       |

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