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

小鱼儿 2021-07-04 16:00 343阅读 0赞

# 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 ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>listen</strong> <code>address:port [ssl] [backlog=number] [rcvbuf=size] [sndbuf=size] [bind] [ipv6only=on\|off] [so_keepalive=on\|off\|[keepidle]:[keepintvl]:[keepcnt]]</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">server</td> 
  </tr> 
 </tbody> 
</table>

为将接受请求的服务器的套接字设置地址（`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 ###

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

### protocol ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>protocol</strong> <code>imap</code> | <code>pop3</code> | <code>smtp</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">server</td> 
  </tr> 
 </tbody> 
</table>

设置代理服务器的协议。支持的协议有 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 ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>resolver</strong> <code>address ... [valid=time] [ipv6=on\|off] [status_zone=zone]</code>;<br><strong>resolver</strong> <code>off</code></td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">resolver off;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">mail、server</td> 
  </tr> 
 </tbody> 
</table>

配置用于查找客户端主机名以将其传递给身份验证服务器的名称服务器，以及代理 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\_)。该参数为我们的[商业订阅][Link 1]部分。

特殊值 `off` 禁用解析。

### resolver\_timeout ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>resolver_timeout</strong> <code>time</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">resolver_timeout 30s;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">mail、server</td> 
  </tr> 
 </tbody> 
</table>

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

resolver_timeout 5s;

### server ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>server</strong> <code>{ ... }</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">mail</td> 
  </tr> 
 </tbody> 
</table>

设置服务器的配置。

### server\_name ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>server_name</strong> <code>name</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">server_name hostname;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">mail、server</td> 
  </tr> 
 </tbody> 
</table>

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

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

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

### timeout ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>timeout</strong> <code>time</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">timeout 60s;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">mail、server</td> 
  </tr> 
 </tbody> 
</table>

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

## 原文档 ##

*  [http://nginx.org/en/docs/mail/ngx\_mail\_core\_module.html][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 ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>auth_http</strong> <code>URL</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">mail、server</td> 
  </tr> 
 </tbody> 
</table>

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

### auth\_http\_header ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>auth_http_header</strong> <code>header value</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">mail、server</td> 
  </tr> 
 </tbody> 
</table>

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

auth_http_header X-Auth-Key "secret_string";

### auth\_http\_pass\_client\_cert ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>auth_http_pass_client_cert</strong> <code>on</code> | <code>off</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">auth_http_pass_client_cert off;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">mail、server</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>提示</strong></td> 
   <td align="left">该指令在 1.7.11 版本中出现</td> 
  </tr> 
 </tbody> 
</table>

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

### auth\_http\_timeout ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>auth_http_timeout</strong> <code>time</code></td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">auth_http_timeout 60s;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">mail、server</td> 
  </tr> 
 </tbody> 
</table>

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

## 协议 ##

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][http_nginx.org_en_docs_mail_ngx_mail_auth_http_module.html]

[Link 1]: http://nginx.com/products/?_ga=2.151996858.282650095.1578660485-1105498734.1571247330
[http_nginx.org_en_docs_mail_ngx_mail_core_module.html]: http://nginx.org/en/docs/mail/ngx_mail_core_module.html
[http_nginx.org_en_docs_mail_ngx_mail_auth_http_module.html]: http://nginx.org/en/docs/mail/ngx_mail_auth_http_module.html