nginx

Module ngx_mail_core_module


english
русский

简体中文
עברית
日本語
türkçe
italiano

news
about
download
security advisories
documentation
pgp keys
faq
links
books
support
donation

trac
wiki
twitter
nginx.com
blog
Example Configuration
Directives
     listen
     mail
     protocol
     resolver
     resolver_timeout
     server
     server_name
     so_keepalive
     timeout

This module is not built by default, it should be enabled with the --with-mail configuration parameter.

Example Configuration

worker_processes 1;

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

mail {
    server_name       mail.example.com;
    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;
    }
    server {
        listen   110;
        protocol pop3;
        proxy_pass_error_message on;
    }
    server {
        listen   143;
        protocol imap;
    }
    server {
        listen   587;
        protocol smtp;
    }
}

Directives

Syntax: listen address:port [bind];
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 (0.7.58) are specified in square brackets:

listen [::1]:110;
listen [::]:110;

UNIX-domain sockets (1.3.5) are specified with the “unix:” prefix:

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

The optional bind 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), nginx 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.

Different servers must listen on different address:port pairs.

Syntax: mail { ... }
Default:
Context: main

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

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

Unnecessary protocols can be disabled using the configuration parameters --without-mail_imap_module, --without-mail_pop3_module, and --without-mail_smtp_module.

Syntax: resolver address ... [valid=time];
resolver off;
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.1 [::1]:5353;

An address can be specified as a domain name or IP address, and an optional port (1.3.1, 1.2.2). If port is not specified, the port 53 is used. Name servers are queried in a round-robin fashion.

Before version 1.1.7, only a single name server could be configured. Specifying name servers using IPv6 addresses is supported starting from versions 1.3.1 and 1.2.2.

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

resolver 127.0.0.1 [::1]:5353 valid=30s;

Before version 1.1.9, tuning of caching time was not possible, and nginx always cached answers for the duration of 5 minutes.

The special value off disables resolving.

Syntax: resolver_timeout time;
Default:
resolver_timeout 30s;
Context: mail, server

Sets a timeout for DNS operations, for example:

resolver_timeout 5s;

Syntax: server { ... }
Default:
Context: mail

Sets the configuration for a server.

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.

Syntax: so_keepalive on | off;
Default:
so_keepalive off;
Context: mail, server

Indicates if the “TCP keepalive” mode should be enabled on the client’s connection (SO_KEEPALIVE socket parameter) when connecting to a proxied server.

Syntax: timeout time;
Default:
timeout 60s;
Context: mail, server

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