FAQ

Page Discussion Edit History

MailCoreModule

Contents

[edit] Mail Proxy Configuration

Nginx is able to handle and proxy the following mail protocols:

  • IMAP
  • POP3
  • SMTP

[edit] Authentication

nginx uses external HTTP-like server to learn which IMAP/POP backend it should connect to.

nginx passes authorization information in HTTP headers:

GET /auth HTTP/1.0
Host: auth.server.hostname
Auth-Method: plain
Auth-User: user
Auth-Pass: password
Auth-Protocol: imap
Auth-Login-Attempt: 1
Client-IP: 192.168.1.1

The good response is:

HTTP/1.0 200 OK      # this line is actually ignored and may not exist at all
Auth-Status: OK
Auth-Server: 192.168.1.10
Auth-Port: 110
Auth-User: newname   # you may override the user name to login to a backend

When authenticating with APOP for POP3, you must return Auth-Pass as well:

HTTP/1.0 200 OK      # this line is actually ignored and may not exist at all
Auth-Status: OK
Auth-Server: 192.168.1.10
Auth-Port: 110
Auth-User: newname   # you may override the user name to login to a backend
Auth-Pass: password  # this must be the user's password in cleartext

The failed response is:

HTTP/1.0 200 OK      # this line is actually ignored and may not exist at all
Auth-Status: Invalid login or password
Auth-Wait: 3         # nginx will wait 3 seconds before reading
# client's login/passwd again

[edit] Directives

[edit] auth

Renamed to pop3_auth in 0.5.15

[edit] imap_capabilities

syntax: imap_capabilities "capability1" ["capability2" .. "capabilityN"]

default: "IMAP4" "IMAP4rev1" "UIDPLUS"

context: main, server


With this directive you can set the list of IMAP protocol extensions presented to the client upon issuing the IMAP command CAPABILITY. STARTTLS is automatically added if you enable the starttls directive.

The current list of standardized IMAP expansions is published on www.iana.org.

mail {
  imap_capabilities NAMESPACE SORT QUOTA;
}

Will the defaults be also set, I haven't see this in the source?! (al 2007-05-11)

[edit] imap_client_buffer

syntax: imap_client_buffer size

default: 4K/8K

context: main, server

With this directive you can set the read buffer for IMAP commands. The default value is equal to the size of a page (this can be either 4K or 8K depending on the platform).

[edit] listen

syntax: listen address:port [ bind ]

default: no

context: server

The directive specifies the address and port, on which the server accepts requests. It is possible to specify address or port only, besides, an address can be the server name, for example:

listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;

IPv6 address(>=0.7.58) are set in square brackets:

listen  [::]:8000; 
listen  [fe80::1];

In directive listen it is possible to indicate the system call bind(2).

bind -- indicates that it is necessary to make bind(2) separately for this pair of address:port. If several directives listen with identical port but with different addresses and one of the directives listen to all addresses for this port (*:port) then Nginx will make bind(2) only to *:port. In this case the address is determined by the system call getsockname().

[edit] pop3_auth

syntax: pop3_auth [plain] [apop] [cram-md5]

default: plain

context: main, server

With this directive you can set the permitted methods of authentication for POP3 clients:

[edit] pop3_capabilities

syntax: pop3_capabilities "capability1" ["capability2" .. "capabilityN"]

default: "TOP" "USER" "UIDL"

context: main, server

With this directive you can set the list of POP3 protocol extensions presented to the client upon issuing the POP3 command CAPA. STLS is automatically added if you enable the starttls directive and SASL is added by the directive auth.

[edit] protocol

syntax: protocol [ pop3 | imap | smtp ] ;

default: IMAP

context: server

This directive set the protocol for this server block.

[edit] server

syntax: server {...}

default: no

context: mail

Directive assigns configuration for the virtual server.

There is no clear separation of the virtual servers ip-based and name-based (the value of the line "Host" header in the request).

Instead of this by directives listen are described all addresses and ports, on which it is necessary to assume connections for this server, and in directive server_name are indicated all names of servers. Example configurations are described in tuning of virtual servers.

[edit] server_name

syntax: server_name name fqdn_server_host

default: The name of the host, obtained through gethostname()

context: mail, server

Directive assigns the names of virtual server, for example:

server {
  server_name   example.com  www.example.com;
}

The first name becomes the basic name of server. By default the name of the machine (hostname) is used. It is possible to use "*" for replacing the first part of the name:

server {
  server_name   example.com  *.example.com;
}

Two of the given name of the above example can be combined into one:

server {
  server_name  .example.com;
}

The basic name of server is used in an HTTP redirects, if no a "Host" header was in client request or that header does not match any assigned server_name. You can also use just "*" to force Nginx to use the "Host" header in the HTTP redirect (note that "*" cannot be used as the first name, but you can use a dummy name such as "_" instead):

server {
  server_name example.com *;
}
server {
  server_name _ *;
}

[edit] smtp_auth

syntax: smtp_auth [login] [plain] [cram-md5] ;

default: login plain

context: main, server

With this directive you can set the permitted methods of authentication for SMTP clients:

[edit] smtp_capabilities

syntax: smtp_capabilities 鈥渃apability1鈥 [鈥渃apability2鈥 .. 鈥渃apabilityN鈥漖

default: no

context: main, server

With this directive you can set the list of SMTP protocol extensions presented to the client upon issuing the EHLO command. This list is automatically extended by the methods enabled with the directive smtp_auth.

The current list of standardized SMTP expansions is published on www.iana.org .

[edit] so_keepalive

syntax: so_keepalive on|off;

default: off

context: main, server

With this directive you can set the socket SO_KEEPALIVE option for the client connection to Nginx. In FreeBSD the keepalive option is used for all connections and can be turned off through setsockopt no (see sysctl net.inet.tcp.always_keepalive).

[edit] timeout

syntax: timeout milliseconds;

default: 60000

context: main, server

With this directive you can set the time out for proxied connections to the back end.

[edit] References