Mail Module#
Implements a mail proxy: Angie handles connections from IMAP, POP3, and SMTP clients and, once an external authentication server accepts a client and chooses its backend, relays the client's session to that backend. The other modules in this section add protocol support, the exchange with the authentication server, SSL/TLS, and proxying settings.
When building from the source code, the module isn't built
by default; it must be enabled with the build option
--with-mail.
In packages and images from our repositories, the module is included in the build.
Related guides
Console Light Web Panel:
status_zone=in resolver fills the Resolvers tab.
How It Works#
Angie stands between mail clients and backends and handles each session in four steps:
The client connects to Angie, not to the backend. Angie itself sends the greeting, answers capability queries, runs STARTTLS, and receives the client's credentials by one of the methods set with imap_auth, pop3_auth, or smtp_auth.
Angie passes the credentials to the authentication server set by auth_http, in the headers of an HTTP request. An SMTP client that sends mail without authenticating triggers this request after its
RCPT TOcommand.The authentication server accepts or rejects the client. To accept it, the authentication server returns the backend's IP address and port in the
Auth-ServerandAuth-Portresponse headers, and it can also return the user name and password for logging in to the backend.Angie opens a TCP connection to the backend, without TLS, and logs in on the client's behalf with the IMAP
LOGINcommand or the POP3USERandPASScommands. To an SMTP backend, Angie passes the client's details with theXCLIENTcommand if xclient is enabled, as it is by default, and authenticates withAUTH PLAINif proxy_smtp_auth is enabled. From then on, Angie relays data between the client and the backend.
The mail block has no proxy_pass or upstream groups: the
authentication server's response is the only way Angie learns where to proxy a
session. That is why every server in the mail block needs
auth_http, even one that accepts SMTP mail without authentication. The
request and response headers are described in the
Auth HTTP module.
Configuration Example#
A minimal configuration proxies IMAP and POP3 sessions to a single backend at
192.0.2.10. The authentication server is a location in the same Angie: it
accepts every client and leaves the password check to the backend, which suits
the plain-text login methods enabled by default. Place the mail block
at the top level of angie.conf, and the map and server
blocks inside the existing http block:
mail {
auth_http 127.0.0.1:9000/mail-auth;
proxy_pass_error_message on;
server {
listen 143;
protocol imap;
}
server {
listen 110;
protocol pop3;
}
}
http {
map $http_auth_protocol $mail_backend_port {
imap 143;
pop3 110;
}
server {
listen 127.0.0.1:9000;
location = /mail-auth {
add_header Auth-Status OK;
add_header Auth-Server 192.0.2.10;
add_header Auth-Port $mail_backend_port;
return 204;
}
}
}
Because the backend checks the password, proxy_pass_error_message is enabled: a client with a wrong password gets the backend's error reply instead of an internal error, and Angie then closes the connection. The authentication server receives client passwords unencrypted, so it should listen on a local or otherwise trusted address.
A fuller configuration also proxies SMTP and enables more authentication
methods. Its authentication server, a CGI script here, has to check APOP and
CRAM-MD5 digests itself and return the user's password in Auth-Pass,
as described in the Auth HTTP module:
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;
}
}
Directives#
error_log_user_tag#
Added in version 1.12.0.
Attaches a tag to the error_log records of every session handled
by the server. Unlike its http and
stream counterparts, the value is a static
string and cannot contain variables. The directive can be specified multiple
times to add multiple tags. These directives are inherited from the previous
configuration level if and only if there are no error_log_user_tag
directives defined on the current level.
Tags appear, as the tags list, only in error_log destinations
that use format=json; filter=tag: matches them in any format.
listen#
| |
Default | — |
server |
Sets the address and port for the socket on which the server will accept connections. It is possible to specify just the port, and Angie will listen on all available IPv4 interfaces (and IPv6, if enabled). The address can also be a hostname, for example:
listen 127.0.0.1:110;
listen *:110;
listen 110; # same as *:110
listen localhost:110;
IPv6 addresses are specified in square brackets:
listen [::1]:110;
listen [::]:110;
UNIX-domain sockets are specified with the unix: prefix:
listen unix:/var/run/angie.sock;
Note
Different servers must listen on different address:port pairs.
| specifies that all connections accepted on this port should work in SSL mode. |
| specifies that all connections accepted on this port should use the PROXY protocol. Obtained information is passed to the authentication server and can be used to change the client address. |
The listen directive can have several additional parameters specific to socket-related system calls.
| sets the |
| sets the receive buffer size (the |
| sets the send buffer size (the |
| makes a separate |
| determines (via the |
| enables accepting connections via Multipath TCP (MPTCP), supported in Linux kernel version 5.6 and later. |
so_keepalive=on | off | [keepidle]:[keepintvl]:[keepcnt]
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 |
| the |
| the |
Some operating systems support setting of TCP keepalive parameters on a
per-socket basis using the TCP_KEEPIDLE, TCP_KEEPINTVL, and
TCP_KEEPCNT socket options. On such systems (currently, Linux, NetBSD,
DragonFly, FreeBSD, and macOS), they can be configured using the
keepidle, keepintvl, and keepcnt parameters. One or two
parameters may be omitted, in which case the system default setting for the
corresponding socket option will be in effect. On macOS, the keepidle
parameter sets the TCP_KEEPALIVE socket option instead of
TCP_KEEPIDLE.
For example,
so_keepalive=30m::10
will set the idle timeout (TCP_KEEPIDLE) to 30 minutes, leave the probe interval (TCP_KEEPINTVL) at its system default, and set the probes count (TCP_KEEPCNT) to 10 probes.
mail#
Provides the configuration file context in which the mail proxy directives are specified.
max_commands#
Sets the maximum number of commands issued during authentication to enhance protection against DoS attacks.
max_errors#
Sets the number of protocol errors after which the connection is closed.
protocol#
Sets the protocol for a proxied server. Supported protocols are IMAP, POP3, and SMTP.
If the directive is not set, the protocol can be detected automatically based on the well-known port specified in the listen directive:
imap: 143, 993
pop3: 110, 995
smtp: 25, 587, 465
When building from source, unnecessary protocols can be disabled using the
--without-mail_imap_module, --without-mail_pop3_module, and
--without-mail_smtp_module build options.
resolver#
| |
Default |
|
mail, server |
Configures name servers used to find the host name of an SMTP client, which
Angie passes to the authentication server in
the Client-Host request header and to the SMTP backend in
the XCLIENT command. For example:
resolver 127.0.0.53 [::1]:5353;
The address can be specified as a domain name or IP address, with an optional port. If port is not specified, the port 53 is used. Name servers are queried in a round-robin fashion.
At least one DNS server address or the conf parameter must be specified,
except in the resolver off; form.
Besides explicit server addresses, the directive recognizes:
| disables resolving of the client hostname and cancels an inherited directive value |
| reads DNS server addresses from the specified file, or from
|
The file may contain nameserver lines in the same format used by the
system resolver:
nameserver 127.0.1.4
nameserver 127.0.1.5
Addresses read from the file are added to any addresses specified explicitly
in the directive, and all of them are then queried together in a
round-robin fashion. If the file is absent, cannot be read, or lists no
addresses, and none are configured explicitly, Angie falls back to the
default server 127.0.0.1:53.
At runtime, Angie re-reads the file when it changes, updating the set of DNS servers.
Note
Prefer a local trusted resolver such as 127.0.0.53 (systemd-resolved)
over a public one (e.g. 8.8.8.8). Public resolvers expose DNS queries
to third parties and increase susceptibility to cache-poisoning attacks.
Note
The directive value is inherited by nested blocks and can be overridden in them if necessary. Within a single block the directive may be specified only once; repeating it is a configuration error.
When looking up the client's hostname, Angie caches each DNS answer for the
duration of its TTL. The optional valid parameter overrides this
period:
| optional parameter allows overriding cached entry validity |
resolver 127.0.0.53 [::1]:5353 valid=30s;
By default, Angie will look up both IPv4 and IPv6 addresses while resolving.
| disables looking up of IPv4 addresses |
| disables looking up of IPv6 addresses |
| optional parameter, enables collection of information about DNS server requests and responses in the specified zone |
Tip
To prevent DNS spoofing, it is recommended to configure DNS servers in a properly secured trusted local network.
Tip
When running in Docker, use its internal DNS server address such as 127.0.0.11.
resolver_timeout#
Sets a timeout for name resolution, for example:
resolver_timeout 5s;
server#
Sets the configuration for a server.
server_name#
Sets the server name that is used:
in the initial POP3/SMTP server greeting;
in the salt during the SASL CRAM-MD5 authentication;
in the EHLO command when connecting to the SMTP backend, if the passing of the XCLIENT command is enabled.
If the directive is not specified, the machine's hostname is used.
timeout#
Sets the timeout that is used before proxying to the backend starts.