月度归档： 2016 年 6 月

nginx中文文档-ngx_mail_auth_http_module

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
版本：1.7.11+

追加含有PEM格式（url编码过的）客户端证书的“Auth-SSL-Cert”头到发送给认证服务器的请求中。

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
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”头，它会覆盖用于与后端认证的用户名。
对于SMPT，响应会考虑“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:

对于SSL/TLS客户端连接（1.7.11+），“Auth-SSL”头会被添加，“Auth-SSL-Verify”会包含客户端证书验证结果，如果启用则可能是“SUCCESS”或“FAILED”，如果证书没有出现则为“NONE”。当客户端证书出现，它的详情会在以下请求头中传递“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

nginx中文文档-ngx_mail_core_module

nginx邮件服务器模块。

该模块默认不会构建，需要通过–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] [bind] [ipv6only=on|off] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]]
默认：—
上下文：server

设置服务器将接受请求的socket的地址和端口。可以只指定端口。地址可以是主机名，例如：

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-domain sockets（1.3.5+）指定以“unix:”前缀：
listen unix:/var/run/nginx.sock;
不同的服务器必须监听不同的地址:端口对。
ssl参数指定所有这个端口接受的连接需要工作在SSL模式。
listen指令可以有多个附加参数指定socket相关的系统调用。

backlog=number
设置listen()调用的backlog参数，用于限制等待连接队列的最大长度（1.9.2+）。默认情况下，FreeBSD、DragonFly BSD和Mac OS X系统上是-1，其他平台上是511。

bind
这个参数为给定的地址端口对执行单独的bind()调用。实际上，如果有多个listen指令是相同的端口号但不同的地址，并且其中一个listen指令在所有地址上监听给定的端口（*:port）,nginx将只绑定*:port。需要注意的是getsockname()系统调用会在这种情况下发生以决定接受连接的地址。如果使用了ipv6only或so_keepalive参数，那么对于一个给定的地址端口对，总会发生一个单独的bind()调用。

ipv6only=on|off
该参数决定（通过IPV6_V6ONLY socket选项）一个通过通配符地址[::]的IPv6 socket监听将只接受ipv6连接还是ipv6和ipv4都接受。该参数默认是开启的。可以在启动时设置一次。

so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
这个参数配置了监听socket的“TCP keepalive”行为。如果该参数省略，则操作系统的设置会影响socket。如果它设置为“on”，SO_KEEPALIVE选项会被打开。如果值为“off”SO_KEEPALIVE选项将被关闭。一些操作系统支持设置TCP keepalive参数使用TCP_KEEPIDLE、TCP_KEEPINTVL和TCP_KEEPCNT socket选项。在这些操作系统上（目前，Linux 2.4+、NetBSD 5+以及FreeBSD 9.0-STABLE）,可以使用keepidle、keepintvl和keepcnt参数。一个或两个参数可以忽略，这种情况下操作系统相应的socket选项的默认设置会生效。例如，
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]
resolver off
默认：resolver off
上下文：mail, server

设置名称服务器用于查找客户端的主机名以传递给验证服务器，代理SMTP时是XCLIENT命令，例如：
resolver 127.0.0.1 [::1]:5353;
地址可以指定为域名或IP地址和一个可选的端口号（1.3.1+，1.2.2+）。如果端口号没有指定，将使用53号端口。名称服务器会通过轮询方式查询。
在1.1.7版本之前，只能配置一个名称服务器。指定IPv6地址的名称服务器从1.3.1和1.2.2版本开始支持。
默认情况下，nginx缓存响应结果使用TTL值。一个可选的valid参数可以覆盖它：
resolver 127.0.0.1 [::1]:5353 valid=30s;
在1.1.9版本之前，不能调整缓存时间，nginx总会缓存结果5分钟。
特殊值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验证中的盐
  • 连接到SMTP上游服务器的EHLO命令，如果XCLIENT命令开启

如果指令没有定义，则使用机器的主机名称。

timeout

语法：timeout time
默认：timeout 60s
上下文：mail, server

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