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:
IPv6 address(>=0.7.58) are set in square brackets:
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:
- plain - USER/PASS , AUTH PLAIN , AUTH LOGIN
- apop - APOP
- cram-md5 - AUTH CRAM-MD5
[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:
- login - AUTH LOGIN
- plain - AUTH PLAIN
- cram-md5 - AUTH CRAM-MD5
- none - Disable SMTP Auth
[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.
