Mail Module#

The core mail module implements basic functionality for a mail proxy server: this includes support for SMTP, IMAP, and POP3 protocols, configuring server blocks, mail request routing, user authentication, and SSL/TLS support for securing mail connections.

The other modules in this section extend this functionality, allowing you to flexibly configure and optimize the mail server for various scenarios and requirements.

When building from the source code, this module isn't built by default; it should be enabled with the --with-mail build option. In packages and images from our repos, the module is included in the build.

Configuration Example#

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#

listen#

Syntax

listen address[:port] [ssl] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];

Default

Context

server

Sets the address and port for the socket on which the server will accept requests. It is possible to specify just the port. 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;

Important

Different servers must listen on different address:port pairs.

ssl

allows specifying that all connections accepted on this port should work in SSL mode.

proxy_protocol

allows specifying 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.

backlog=number

sets the backlog 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=size

sets the receive buffer size (the SO_RCVBUF option) for the listening socket.

sndbuf=size

sets the send buffer size (the SO_SNDBUF option) for the listening socket.

bind

this parameter instructs to make a separate bind() call for a given address:port pair. The fact is that if there are several listen directives with the same port but different addresses, and one of the listen directives listens on all addresses for the given port (*:port), Angie will bind() only to *:port. It should be noted that the getsockname() system call will be made in this case to determine the address that accepted the connection. If the backlog, rcvbuf, sndbuf, ipv6only, reuseport, or so_keepalive parameters are used then for a given address:port pair a separate bind() call will always be made.

ipv6only=on | off

this parameter determines (via the IPV6_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.

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

on

the SO_KEEPALIVE option is turned on for the socket

off

the SO_KEEPALIVE option is turned off for the socket

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 2.4+, NetBSD 5+, and FreeBSD 9.0-STABLE), 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.

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#

Syntax

mail { ... }

Default

Context

main

Provides the configuration file context in which the mail server directives are specified.

max_commands#

Added in version 1.7.0.

Syntax

max_commands number;

Default

max_commands 1000;

Context

mail, server

Sets the maximum number of commands issued during authentication to enhance protection against DoS attacks.

max_errors#

Syntax

max_errors number;

Default

max_errors 5;

Context

mail, server

Sets the number of protocol errors after which the connection is closed.

protocol#

Syntax

protocol imap | pop3 | smtp;

Default

Context

server

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#

Syntax

resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];

Default

resolver off;

Context

mail, server

Configures name servers used to find the client's hostname to pass it to the authentication server, and in the XCLIENT command when proxying SMTP. 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.

By default, Angie caches answers using the TTL value of a response. The optional valid parameter allows overriding it:

valid

optional valid 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.

ipv4=off

disables looking up of IPv4 addresses

ipv6=off

disables looking up of IPv6 addresses

status_zone

optional parameter, enables statistics collection for specified zone

Tip

To prevent DNS spoofing, it is recommended configuring DNS servers in a properly secured trusted local network.

resolver_timeout#

Syntax

resolver_timeout time;

Default

resolver_timeout 30s;

Context

mail, server

Sets a timeout for DNS operations, for example:

resolver_timeout 5s;

server#

Syntax

server { ... }

Default

Context

mail

Sets the configuration for a server.

server_name#

Syntax

server_name name;

Default

server_name hostname;

Context

mail, 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.

timeout#

Syntax

timeout time;

Default

timeout 60s;

Context

mail, server

Sets the timeout that is used before proxying to the backend starts.