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. 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
The authentication server accepts or rejects the client. To accept it, the
authentication server returns the backend's IP address and port in the
Angie opens a TCP connection to the backend, without TLS, and logs in on the
client's behalf with the IMAP The 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 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 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 Tags appear, as the 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: IPv6 addresses are specified in square brackets: UNIX-domain sockets are specified with the 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 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. 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 For example, will set the idle timeout ( Provides the configuration file context in which the mail proxy directives are specified. Sets the maximum number of commands issued during authentication
to enhance protection against DoS attacks. Sets the number of protocol errors after which the connection is closed. 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 When building from source, unnecessary protocols can be disabled using the
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 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 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 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 At runtime, Angie re-reads the file when it changes, updating the set of DNS
servers. Note Prefer a local trusted resolver such as 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 optional parameter allows overriding cached entry validity 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 Sets a timeout for name resolution, for example: Sets the configuration for a server. 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. Sets the timeout that is used before proxying to the backend starts.How It Works#
RCPT TO command.Auth-Server and Auth-Port response headers, and it can also
return the user name and password for logging in to the backend.LOGIN command or the POP3
USER and PASS commands. To an SMTP backend, Angie passes the
client's details with the XCLIENT command if xclient is
enabled, as it is by default, and authenticates with AUTH PLAIN if
proxy_smtp_auth is enabled. From then on, Angie relays data between
the client and the backend.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#
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;
}
}
}
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#
error_log_user_tag
directives defined on the current level.tags list, only in error_log destinations
that use format=json; filter=tag: matches them in any format.listen#
listen address[:port] [ssl] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [bind] [ipv6only=on | off] [multipath] [so_keepalive=on | off | [keepidle]:[keepintvl]:[keepcnt]];listen 127.0.0.1:110;
listen *:110;
listen 110; # same as *:110
listen localhost:110;
listen [::1]:110;
listen [::]:110;
unix: prefix:listen unix:/var/run/angie.sock;
sslproxy_protocollisten directive can have several additional parameters specific to socket-related system calls.backlog=numberbacklog parameter in the listen() call that
limits the maximum length for the queue of pending connections. By
default, backlog is set to -1 on FreeBSD, DragonFly BSD, and
macOS, and to 511 on other platforms.rcvbuf=sizeSO_RCVBUF option) for the listening socket.sndbuf=sizeSO_SNDBUF option) for the listening socket.bindbind() call for the given address:port pair.
Without this parameter, if several listen directives share a
port with different addresses and one of them listens on all addresses
for that port, Angie calls bind() only for the wildcard socket
and determines the accepting address with getsockname(). The
backlog, rcvbuf, sndbuf, ipv6only,
multipath, and so_keepalive parameters always imply a
separate bind() call.ipv6only=on | offIPV6_V6ONLY socket option) whether an IPv6 socket listening on a wildcard address [::] 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.multipathso_keepalive=on | off | [keepidle]:[keepintvl]:[keepcnt]''onSO_KEEPALIVE option is turned on for the socketoffSO_KEEPALIVE option is turned off for the socketTCP_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.so_keepalive=30m::10
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#
max_commands#
max_errors#
protocol#
listen directive:imap: 143, 993
pop3: 110, 995
smtp: 25, 587, 465
--without-mail_imap_module, --without-mail_pop3_module, and
--without-mail_smtp_module build options.resolver#
resolver [address ...] [conf [=file]] [valid=time] [ipv4=on | off] [ipv6=on | off] [status_zone=zone] | off;resolver off;Client-Host request header and to the SMTP backend in
the XCLIENT command. For example:resolver 127.0.0.53 [::1]:5353;
conf parameter must be specified,
except in the resolver off; form.offconf [=file]/etc/resolv.conf if no file is specifiednameserver lines in the same format used by the
system resolver:nameserver 127.0.1.4
nameserver 127.0.1.5
127.0.0.1:53.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.valid parameter overrides this
period:validresolver 127.0.0.53 [::1]:5353 valid=30s;
ipv4=offipv6=offstatus_zone127.0.0.11.resolver_timeout#
resolver_timeout 5s;
server#
server_name#
timeout#
Content