Nginx官方文档(四十二)【ngx_mail_core_module|ngx_mail_auth_http_module】

ngx_mail_core_module

• 示例配置
• 指令
  • listen
  • mail
  • protocol
  • resolver
  • resolver_timeout
  • server
  • server_name
  • timeout

默认不构建此模块，可使用 --with-mail 配置参数启用。

示例配置

worker_processes 1;

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

events {
    worker_connections  1024;
}

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;
    }
}

指令

listen

-	说明
语法	listen address:port [ssl] [backlog=number] [rcvbuf=size] [sndbuf=size] [bind] [ipv6only=on\|off] [so_keepalive=on\|off\|[keepidle]:[keepintvl]:[keepcnt]];
默认	——
上下文	server

为将接受请求的服务器的套接字设置地址（address）和端口（port）。可以仅指定端口。地址也可以是主机名，例如：

listen 127.0.0.1:110;
listen *:110;
listen 110;     # same as *:110
listen localhost:110;

IPv6 地址在方括号中指定（0.7.58）：

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

UNIX 域套接字使用 unix: 前缀指定（1.3.5）：

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

不同的服务器必须侦听不同的 address:port 对，不能重复。

ssl 参数指定该端口上接受的所有连接均应以 SSL 模式工作。

listen 指令可以指定几个额外的参数给套接字相关的系统调用。

• backlog=number

  在 listen() 调用中设置 backlog 参数，该参数限制挂起的连接队列的最大长度（1.9.2）。默认情况下，在 FreeBSD、DragonFly BSD 和 mac OS上，backlog 设置为 -1，而在其他平台上则设置为 511。

• rcvbuf=size

  设置侦听套接字的接收缓冲区大小（SO_RCVBUF 选项）（1.11.13）。

• sndbuf=size

  设置侦听套接字的发送缓冲区大小（SO_SNDBUF 选项）（1.11.13）。

• bind

  此参数指示对给定的 address:port 对进行单独的 bind() 调用。事实上，如果有多个有相同端口但地址不同的 listen 指令，并且其中一个 listen 指令在给定端口（*:port）的所有地址上监听，nginx 只会将绑定（bind()）到 *:port。要注意的是，这种情况下将进行 getsockname() 系统调用，以确定接受连接的地址。如果使用 ipv6only 或 so_keepalive 参数，则对于给定的 address:port 对，将始终进行单独的 bind() 调用。

• ipv6only=on|off

  此参数确定（通过 IPV6_V6ONLY 套接字选项）监听通配符地址 [::] 的 IPv6 套接字是否仅接受 IPv6 连接，还是接受 IPv6 和 IPv4 连接。默认情况下，此参数是打开的。启动时只能设置一次。

• so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]

  此参数为监听套接字配置「TCP keepalive」行为。如果省略此参数，则套接字的操作系统设置将生效。如果将其设置为值 on，则会为套接字打开 SO_KEEPALIVE 选项。如果将其设置为值 off，则将关闭套接字 SO_KEEPALIVE 选项。某些操作系统支持使用 TCP_KEEPIDLE、TCP_KEEPINTVL 和 TCP_KEEPCNT 套接字选项在每个套接字的基础上设置 TCP Keepalive 参数。在此类系统（当前为 Linux 2.4+、NetBSD 5+ 和 FreeBSD 9.0-STABLE）上，可以使用 keepidle、keepintvl 和 keepcnt 参数进行配置。可以省略一个或两个参数，在这种情况下，相应套接字选项的系统默认设置将生效。例如，

  so_keepalive=30m::10
  

  会将闲置超时时间（TCP_KEEPIDLE）设置为 30 分钟，将探测间隔（TCP_KEEPINTVL）保留为系统默认值，并将探测计数（TCP_KEEPCNT）设置为 10 个探测。

mail

-	说明
语法	mail { ... };
默认	——
上下文	main

在指定的邮件服务器指令中提供配置文件上下文。

protocol

-	说明
语法	protocol imap | pop3 | smtp;
默认	——
上下文	server

设置代理服务器的协议。支持的协议有 IMAP、POP3 和 SMTP。

如果未设置该指令，则可以基于 listen 指令中指定的为人熟知的默认端口来自动检测协议：

• imap：143、993
• pop3：110、995
• smtp：25、587、465

可以使用配置参数 --without-mail_imap_module、--without-mail_pop3_module 和 --without-mail_smtp_module 禁用不必要的协议。

resolver

-	说明
语法	resolver address ... [valid=time] [ipv6=on\|off] [status_zone=zone]; resolver off
默认	resolver off;
上下文	mail、server

配置用于查找客户端主机名以将其传递给身份验证服务器的名称服务器，以及代理 SMTP 时的 XCLIENT 命令。 例如：

resolver 127.0.0.1 [::1]:5353;

可以使用可选端口（1.3.1、1.2.2）将地址指定为域名或 IP 地址。如果未指定端口，则使用端口 53。以轮询方式查询名称服务器。

在 1.1.7 版本之前，只能配置一个名称服务器。从 1.3.1 和 1.2.2 版本开始，支持使用 IPv6 地址指定名称服务器。

默认情况下，nginx 将在解析时同时查找 IPv4 和 IPv6 地址。如果不需要查找 IPv6 地址，则可以指定 ipv6=off 参数。

从 1.5.8 版本开始，支持将名称解析为 IPv6 地址。

默认情况下，nginx 使用响应的 TTL 值缓存应答。可选的 valid 参数可覆盖它：

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

在1.1.9 版本之前，无法调整缓存时间，nginx 始终将应答缓存 5 分钟。

为防止 DNS 欺骗，建议在适当安全的受信任本地网络中配置 DNS 服务器。

可选的 status_zone 参数（1.17.1）启用对指定区域中的请求和响应的 DNS 服务器统计信息的[收集]功能(…/http/ngx_http_api_module.md#resolvers_)。该参数为我们的商业订阅部分。

特殊值 off 禁用解析。

resolver_timeout

-	说明
语法	resolver_timeout time;
默认	resolver_timeout 30s;
上下文	mail、server

设置 DNS 操作的超时时间，例如：

resolver_timeout 5s;

server

-	说明
语法	server { ... };
默认	——
上下文	mail

设置服务器的配置。

server_name

-	说明
语法	server_name name;
默认	server_name hostname;
上下文	mail、server

设置服务器名称，在以下场景中使用的：

• 最开始的 POP3/SMTP 服务器问候语中
• SASL CRAM-MD5 身份验证中的盐值中
• 如果启用了 XCLIENT 命令的传递，则在连接到 SMTP 后端时，在 EHLO 命令中

如果未指定指令，则使用计算机的主机名。

timeout

-	说明
语法	timeout time;
默认	timeout 60s;
上下文	mail、server

设置超时时间，在代理到后端开始之前使用。

原文档

• http://nginx.org/en/docs/mail/ngx_mail_core_module.html

---

ngx_mail_auth_http_module

• 指令
  • auth_http
  • auth_http_header
  • auth_http_pass_client_cert
  • auth_http_timeout
• 协议

指令

auth_http

-	说明
语法	auth_http URL;
默认	——
上下文	mail、server

设置 HTTP 认证服务器的 URL。协议描述如下。

auth_http_header

-	说明
语法	auth_http_header header value;
默认	——
上下文	mail、server

将指定的头附加到发送到身份验证服务器的请求。该头可以用作共享密钥，以验证请求来自 nginx。例如：

auth_http_header X-Auth-Key "secret_string";

auth_http_pass_client_cert

-	说明
语法	auth_http_pass_client_cert on | off;
默认	auth_http_pass_client_cert off;
上下文	mail、server
提示	该指令在 1.7.11 版本中出现

将 Auth-SSL-Cert 头和 PEM 格式（已编码）的客户端证书附加到发送到身份验证服务器的请求。

auth_http_timeout

-	说明
语法	auth_http_timeout time
默认	auth_http_timeout 60s;
上下文	mail、server

设置与认证服务器通信的超时时间。

协议

HTTP 协议用于与身份验证服务器进行通信。响应正文中的数据将被忽略，信息仅在头中传递。

请求和响应的示例：

请求：

GET /auth HTTP/1.0
Host: localhost
Auth-Method: plain # plain/apop/cram-md5/external
Auth-User: user
Auth-Pass: password
Auth-Protocol: imap # imap/pop3/smtp
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Client-Host: client.example.org

好的响应：

HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143

坏的响应：

HTTP/1.0 200 OK
Auth-Status: Invalid login or password
Auth-Wait: 3

如果没有 Auth-Wait 头，则将返回错误并关闭连接。当前实现为每次身份验证尝试分配内存。仅在会话结束时才释放内存。因此，必须限制单个会话中无效身份验证尝试的次数 — 服务器必须在 10-20 次尝试后响应不带 Auth-Wait 头（尝试次数在 Auth-Login-Attempt 头中传递）。

使用 APOP 或 CRAM-MD5 时，请求-响应如下所示：

GET /auth HTTP/1.0
Host: localhost
Auth-Method: apop
Auth-User: user
Auth-Salt: <238188073.1163692009@mail.example.com>
Auth-Pass: auth_response
Auth-Protocol: imap
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Client-Host: client.example.org

好的响应：

HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143
Auth-Pass: plain-text-pass

如果响应中存在 Auth-User 头，它将覆盖用于与后端进行身份验证的用户名。

对于 SMTP，响应还考虑了 Auth-Error-Code 头 — 如果存在，则在发生错误时用作响应代码。否则，将 535 5.7.0 代码添加到 Auth-Status 头中。

例如，如果从身份验证服务器收到以下响应：

HTTP/1.0 200 OK
Auth-Status: Temporary server problem, try again later
Auth-Error-Code: 451 4.3.0
Auth-Wait: 3

则 SMTP 客户端将收到错误

451 4.3.0 Temporary server problem, try again later

如果代理 SMTP 不需要身份验证，则请求将如下所示：

GET /auth HTTP/1.0
Host: localhost
Auth-Method: none
Auth-User:
Auth-Pass:
Auth-Protocol: smtp
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Client-Host: client.example.org
Auth-SMTP-Helo: client.example.org
Auth-SMTP-From: MAIL FROM: <>
Auth-SMTP-To: RCPT TO: <postmaster@mail.example.com>

对于 SSL/TLS 客户端连接（1.7.11），添加了 Auth-SSL 头，并且 Auth-SSL-Verify 将包含客户端证书验证的结果（如果启用）：SUCCESS、FAILED:reason 和 NONE（如果不存在证书）。

在 1.11.7 版本之前，FAILED 结果不包含原因字符串。

存在客户端证书时，其详细信息将在以下请求头中传递：Auth-SSL-Subject、Auth-SSL-Issuer、Auth-SSL-Serial 和 Auth-SSL-Fingerprint。如果启用了 auth_http_pass_client_cert，则证书本身将在 Auth-SSL-Cert 头中传递。该请求将如下所示：

GET /auth HTTP/1.0
Host: localhost
Auth-Method: plain
Auth-User: user
Auth-Pass: password
Auth-Protocol: imap
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Auth-SSL: on
Auth-SSL-Verify: SUCCESS
Auth-SSL-Subject: /CN=example.com
Auth-SSL-Issuer: /CN=example.com
Auth-SSL-Serial: C07AD56B846B5BFF
Auth-SSL-Fingerprint: 29d6a80a123d13355ed16b4b04605e29cb55a5ad

原文档

• http://nginx.org/en/docs/mail/ngx_mail_auth_http_module.html