Nginx 中文官方手册mail模块MailCore

上一篇：HttpImageFilter 下一篇：MailAuth

MailCore

Nginx is able to handle and proxy the following mail protocols:
Nginx 能够处理和代理以下邮件协议:

IMAP
POP3
SMTP

认证

nginx uses external HTTP-like server to learn which IMAP/POP backend it should connect to.
nginx的IMAP／POP后端处理类似HTTP服务器的连接方式。

nginx passes authorization information in HTTP headers:
nginx 在HTTP头里传递授权信息:

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:
当在POP3中使用APOP协议时，你必须返回验证密码如下:

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  Nginx在读之前等待3秒
# client's login/passwd again

指令

auth

Renamed to pop3_auth in 0.5.15

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.
使用这条指令你可以设置IMAP协议列表来扩展现有的客户端上的IMAP的命令CAPABILITY。如果你启用了STARTTLS那么STARTTLS命令将自动加入。

The current list of standardized IMAP expansions is published on www.iana.org.
现在所列出的标准的IMAP扩展发布在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)
这个设置了默认了？我在源码中没有看到！

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).

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).
listen指令可能显示显示系统命令 bind.

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().
bind -- bind指令必须是绑定一对地址：端口。如果多个指令监听不同地址的相同的端口，另一个指令监听所有地址的端口(:端口号)，这样的话Nginx将指执行 bind的 :端口号 .这样的话地址只能是系统命令getsockname()的值。

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:
使用这条指令你可以设置验证POP3客户端的验证方法:

plain - USER/PASS , AUTH PLAIN , AUTH LOGIN
apop - APOP
cram-md5 - AUTH CRAM-MD5

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.
使用这条指令你可以设置 POP3 协议列表来扩展现有客户端上的POP3命令CAPA。如果你启用了starttls指令STLS将会自动被添加，通过auth，SASL也将被添加。

protocol

syntax:*protocol*[ pop3 | imap | smtp ] ;

default:*IMAP*

context:*server*

This directive set the protocol for this server block.
这条指令设置了服务器块的协议

> 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).
这里不区分基于IP的虚拟服务器和基于命名的虚拟服务器（Host指从请求头中获得）

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.
可以替代这个的listen指令描述了连接服务器的所有的地址和端口，和纸条指令的server_name显示了所有的服务器命名。例如以下配置描述了虚拟服务器的调度

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:
2个给定的名词在以上的例子中被合并成一个

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 servername. 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):
HTTP重定向中使用了服务器基本名称，如果客户端请求中没有"host"头或者头中没知道servername.你可以使用“＊”来强制Nginx在HTTP重定向中使用"Host"头（注释： "*"不能作为第一命名可以使用""代替）

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

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:
使用这个命令你可以设置SMTP客户端的验证方法

login - AUTH LOGIN
plain - AUTH PLAIN
cram-md5 - AUTH CRAM-MD5

smtp_capabilities

syntax:*smtp_capabilities*“capability1” [“capability2” .. “capabilityN”]

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.
使用这条指令你可以设置SMTP协议扩展现有的客户端通过使用EHLO命令.使用smtp_auth指令这个列表将被自动扩展。

The current list of standardized SMTP expansions is published on www.iana.org . 现在标准的SMTP扩展列表发布在www.iana.org

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 connection to the IMAP/POP3 backend. 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).
通过使用这条指令你可以设置socket连接IMAP／POP3的SO——KEEPALIVE选项。在FREEBSD中这个 keepalive(保持存活) 选项在所有的连接中都有效并且可以使用setsockopt no来关闭。

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.
使用这条指令你可以设置代理连接的超时时间

上一篇：HttpImageFilter 下一篇：MailAuth