# HG changeset patch # User Vladimir Homutov # Date 1346854063 0 # Node ID 8283b1048b27dadcda8ad2ab208642d9f0124515 # Parent 639bbb0c9d058d35b78d2a34a75e4e8fd76e7129 Translated mail modules into English. diff --git a/xml/en/GNUmakefile b/xml/en/GNUmakefile --- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -72,6 +72,13 @@ REFS = \ http/ngx_http_upstream_module \ http/ngx_http_userid_module \ http/ngx_http_xslt_module \ + mail/ngx_mail_core_module \ + mail/ngx_mail_auth_http_module \ + mail/ngx_mail_proxy_module \ + mail/ngx_mail_ssl_module \ + mail/ngx_mail_imap_module \ + mail/ngx_mail_pop3_module \ + mail/ngx_mail_smtp_module \ REFS_XML = $(foreach name, $(REFS), xml/$(DOC_LANG)/docs/$(name).xml) REFS_HTML = $(foreach name, $(REFS), $(OUT)/$(DOC_LANG)/docs/$(name).html) diff --git a/xml/en/docs/index.xml b/xml/en/docs/index.xml --- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -300,6 +300,32 @@ ngx_http_xslt_module + + + + + +ngx_mail_core_module + + + + +ngx_mail_auth_http_module + + + + +ngx_mail_proxy_module + + + + +ngx_mail_ssl_module + + + + + diff --git a/xml/en/docs/mail/ngx_mail_auth_http_module.xml b/xml/en/docs/mail/ngx_mail_auth_http_module.xml new file mode 100644 --- /dev/null +++ b/xml/en/docs/mail/ngx_mail_auth_http_module.xml @@ -0,0 +1,161 @@ + + + + + + + + +
+ + +URL + +mail +server + + +Sets the URL of the HTTP authentication server. +The protocol is described below. + + + + + + +header value + +mail +server + + +Allows to append the specified header to requests to the authentication server. +Can be used as a shared secret to verify +that the request came in from nginx. +For example: + +auth_http_header X-Auth-Key "secret_string"; + + + + + + + +time +60s +mail +server + + + + + + +
+ + +
+ + +The HTTP is used to communicate with the authentication server. +The data in the response body is ignored, information is passed only in headers. + + + +Requests and responses examples: + + + +Request: + +GET /auth HTTP/1.0 +Host: localhost +Auth-Method: plain # plain or apop or cram-md5 +Auth-User: user +Auth-Pass: password +Auth-Protocol: imap # imap, pop3 or smtp +Auth-Login-Attempt: 1 # attempt count in a single session +Client-IP: 192.168.1.1 + +Good response: + +HTTP/1.0 200 OK # this line is ignored +Auth-Status: OK +Auth-Server: 10.1.1.1 +Auth-Port: 143 + +Bad response: + +HTTP/1.0 200 OK # this line is ignored +Auth-Status: Invalid login or password +Auth-Wait: 3 # wait for 3 seconds before returning an error to the client + + + + +If there is no the
Auth-Wait
header, +the connection will be closed after returning an error. +The current implementation allocates memory per each authentication attempt, +which is freed only at the end of a session. +Therefore a number of invalid authentication attempts in a single session +must be limited — the server must response without +the
Auth-Wait
header after 10-20 attempts +(see the
Auth-Login-Attempt
header). + + + +When using the APOP or CRAM-MD5 request-reponses will look like: + +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 # attempt count in a single session +Client-IP: 192.168.1.1 + +Good response: + +HTTP/1.0 200 OK # this line is ignored +Auth-Status: OK +Auth-Server: 10.1.1.1 +Auth-Port: 143 +Auth-Pass: plain-text-pass + + + + +For the SMTP, the response additionally takes into account +the
Auth-Error-Code
header — it is used +as a response code if exists. +Otherwise the code 535 5.7.0 will be added to +the
Auth-Status
by default. + + + +For example, if the following response is received +from the authentication server: + +HTTP/1.0 200 OK +Auth-Status: Temporary server problem, try again later +Auth-Error-Code: 451 4.3.0 +Auth-Wait: 3 + +then the SMTP client will be given an error + +451 4.3.0 Temporary server problem, try again later + + + +
+ + diff --git a/xml/en/docs/mail/ngx_mail_core_module.xml b/xml/en/docs/mail/ngx_mail_core_module.xml new file mode 100644 --- /dev/null +++ b/xml/en/docs/mail/ngx_mail_core_module.xml @@ -0,0 +1,247 @@ + + + + + + + + +
+ + +This module is not built by default, it should be +enabled with +the --with-mail configuration parameter. + + +
+ + +
+ + + +worker_processes 1; + +error_log /var/log/nginx/error.log info; + +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; + } +} + + + +
+ + +
+ + + + address:port + [bind] + +server + + +Sets an address and a port for for a socket, +on which the server will accept requests. +Only port may be specified. +An address may also be a hostname, for example: + +listen 127.0.0.1:110; +listen *:110; +listen 110; # то же, что и *:110 +listen localhost:110; + +IPv6 addresses (0.7.58) are specified in square brackets: + +listen [::1]:110; +listen [::]:110; + +UNIX-domain sockets (1.3.5) are specified with the “unix:” +prefix: + +listen unix:/var/run/nginx.sock; + + + + + +The optional bind parameter +instructs to make a separate bind +call for a given address:port pair. +The fact is that nginx will bind only to +*:port +if there are several listen directives with +the same port but different addresses, and one of the +listen directives listens on all addresses +for the given port (*:port). +It should be noted that the getsockname system call will be +made in this case to determine an address that accepted a connection. + + + +Different virtual servers must listen on different +address:port pairs. + + + + + + + + imap | + pop3 | + smtp + +server + + +Sets the protocol of a proxied server. +Supported protocols are +IMAP, +POP3 and +SMTP. + + + +If the directive is not set, the protocol can be detected automatically +basing on the well-known port specified in the +directive: + + + +imap: 143, 993 + + + +pop3: 110, 995 + + + +smtp: 25, 587, 465 + + + + + + +Unnecessary protocols can be disabled using the +configuration +parameters --without-mail_imap_module, +--without-mail_pop3_module and +--without-mail_smtp_module. + + + + + + + + +mail + + +Sets a configuration for the virtual server. + + + + + + +name +hostname +mail +server + + +Sets a name of the virtual server, used: + + + + +in the initial POP3/SMTP server greeting; + + + +in the salt during the SASL CRAM-MD5 authentication; + + + +in the EHLO command on the SMTP backend connection, +if the command +is turned on. + + + + + + + + + + +on | off +off +mail +server + + +Controls if the “TCP keepalive” mode should be enabled on the client’s +connection (SO_KEEPALIVE socket parameter) on the +proxied server connection. + + + + + + +time +60s +mail +server + + +Sets the timeout which is used before proxying to the backend started. + + + + +
+ + diff --git a/xml/en/docs/mail/ngx_mail_imap_module.xml b/xml/en/docs/mail/ngx_mail_imap_module.xml new file mode 100644 --- /dev/null +++ b/xml/en/docs/mail/ngx_mail_imap_module.xml @@ -0,0 +1,99 @@ + + + + + + + + +
+ + +method ... +plain +mail +server + + +Sets permitted methods of authentication for IMAP clients. +Supported methods are: + + +login + +AUTH=LOGIN + + +plain + +AUTH=PLAIN + + +cram-md5 + +AUTH=CRAM-MD5. +In order for this method to work, the password must be stored unencrypted. + + + + + + + + + +extension ... +IMAP4 IMAP4rev1 UIDPLUS +mail +server + + +Allows to specify the +IMAP protocol +extensions list to be passed to the client upon +issuing the CAPABILITY command. +Authentication methods specified in the and +STARTTLS directives +are automatically added to this list if the + directive is enabled. + + + +It makes sense to specify extensions +supported by IMAP backends +to which clients are proxied (if this extensions are related to commands +used after the authentication, when nginx transparently proxies the client +connection to the backend). + + + +The current list of standardized extensions is published at the +www.iana.org. + + + + + + +size +4k|8k +mail +server + + +Sets the IMAP commands read buffer size. +By default, the buffer size is equal to one memory page. +This is either 4K or 8K, depending on a platform. + + + + +
+ + diff --git a/xml/en/docs/mail/ngx_mail_pop3_module.xml b/xml/en/docs/mail/ngx_mail_pop3_module.xml new file mode 100644 --- /dev/null +++ b/xml/en/docs/mail/ngx_mail_pop3_module.xml @@ -0,0 +1,90 @@ + + + + + + + + +
+ + +method ... +plain +mail +server + + +Sets permitted methods of authentication for POP3 clients. +Supported methods are: + + +plain + +USER/PASS, +AUTH PLAIN, +AUTH LOGIN. +It is not possible to disable this methods. + + +apop + +APOP. +In order for this method to work, the password must be stored unencrypted. + + +cram-md5 + +AUTH CRAM-MD5. +In order for this method to work, the password must be stored unencrypted. + + + + + + + + + +extension ... +TOP USER UIDL +mail +server + + +Allows to specify the +POP3 protocol +extensions list to be passed to the client upon +issuing the CAPA command. + +Authentication methods specified in the and +(SASL extension) and +STLS directives, +are automatically added to this list if the + directive is enabled. + + + +It makes sense to specify extensions +supported by POP3 backends +to which clients are proxied (if this extensions are related to commands +used after the authentication, when nginx transparently proxies the client +connection to the backend). + + + +The current list of standardized extensions is published at the +www.iana.org. + + + + +
+ + diff --git a/xml/en/docs/mail/ngx_mail_proxy_module.xml b/xml/en/docs/mail/ngx_mail_proxy_module.xml new file mode 100644 --- /dev/null +++ b/xml/en/docs/mail/ngx_mail_proxy_module.xml @@ -0,0 +1,139 @@ + + + + + + + + +
+ + + + + +size +4k|8k +mail +server + + +Sets size of the buffer used for proxying. +The buffer size is equal to one memory page by default. +Depending on a platform, this is either 4K or 8K. + + + + + + +on | off +off +mail +server + + +Defines whether to pass the error message obtained during +an authentication on the backend to the client. + + + +Usually, if the authentication in nginx was sucessfull, +backend can't return an error, but if it nonetheless exists, +this means there is some problem inside. +In such cases the backend message can contain the information +that should not be shown to the client. +However responding with an error for the correct password +is a normal behavior of some POP3 servers. +For example, CommuniGatePro informs user about +mailbox +overflow or other events by periodically outputting the +authentcation +error. +The directive should be enabled in this case. + + + + + + +timeout +24h +mail +server + + +Defines a timeout used after the proxying to the backend had started. + + + + + + +on | off +on +mail +server + + +Enables or disables issuing of the XCLIENT command +upon the connection to the SMTP backend. +For the XCLIENT command to work it is required to have +Postfix with the +patch, +which adds the LOGIN parameter. +If the XCLIENT command is not used, the MTA will be unable +to write the client's +IP/HELO/LOGIN +to the log and apply various limitations based on this data. + + + +If the xclient is enabled, +then upon a backend connection nginx first issues + +EHLO server_name + +and then + +XCLIENT PROTO=ESMTP HELO=client_hello ADDR=192.168.1.1 LOGIN=good_user NAME=[UNAVAILABLE] + +If the client upon a connection to nginx issued the EHLO, +then the XCLIENT command will pass +the PROTO=ESMTP. +Otherwise, PROTO=SMTP will be passed. +The IP address of a client is specified in the ADDR +parameter, and since nginx does not use DNS to resolve the hostname, +the NAME=[UNAVAILABLE] is specified. + + + +If the xclient is disabled, +then the EHLO is issued upon the connection to the backend +if the client had passed it and the HELO +otherwise. + + + + +
+ + diff --git a/xml/en/docs/mail/ngx_mail_smtp_module.xml b/xml/en/docs/mail/ngx_mail_smtp_module.xml new file mode 100644 --- /dev/null +++ b/xml/en/docs/mail/ngx_mail_smtp_module.xml @@ -0,0 +1,83 @@ + + + + + + + + +
+ + +method ... +login plain +mail +server + + +Sets permitted methods of +SASL authentication +for SMTP clients. +Supported methods are: + + +login + +AUTH LOGIN + + +plain + +AUTH PLAIN + + +cram-md5 + +AUTH CRAM-MD5. +In order for this method to work, the password must be stored unencrypted. + + + + + + + + + +extension ... + +mail +server + + +Allows to specify the SMTP protocol extensions list +to be passed to the client in the response to the +EHLO command. +Authentication methods specified in the directive +are automatically added to this list. + + + +It makes sense to specify extensions +supported by MTA +to which clients are proxied (if this extensions are related to commands +used after the authentication, when nginx transparently proxies the client +connection to the backend). + + + +The current list of standardized extensions is published at the +www.iana.org. + + + + +
+ + diff --git a/xml/en/docs/mail/ngx_mail_ssl_module.xml b/xml/en/docs/mail/ngx_mail_ssl_module.xml new file mode 100644 --- /dev/null +++ b/xml/en/docs/mail/ngx_mail_ssl_module.xml @@ -0,0 +1,234 @@ + + + + + + + + +
+ + +The ngx_mail_ssl_module provides the necessary +support for mail proxy server for the SSL/TLS protocol. + + + +This module is not built by default, it should be enabled with +the --with-mail_ssl_module +configuration parameter. + +This module requires the OpenSSL +library. + + + +
+ + +
+ + +on | off +off +mail +server + + +Enables the HTTPS protocol for the given virtual server. + + + + + + +file + +mail +server + + +Specifies a file with a certificate in the PEM format for the given +virtual server. +If intermediate certificates should be specified in addition to a primary +certificate, they should be specified in the same file in the following +order: the primary certificate comes first, then the intermediate certificates. +A secret key in the PEM format may be placed in the same file. + + + + + + +file + +mail +server + + +Specifies a file with a secret key in the PEM format for the given virtual +server. + + + + + + +on | off +off +mail +server + + +Specifies that server ciphers should be preferred over client ciphers +when using the SSLv3 and TLS protocols. + + + + + + + + [SSLv2] + [SSLv3] + [TLSv1] + [TLSv1.1] + [TLSv1.2] +SSLv3 TLSv1 TLSv1.1 TLSv1.2 +mail +server + + +Enables the specified protocols. +The parameters TLSv1.1 and TLSv1.2 work +only when using the OpenSSL library version 1.0.1 and higher. + +The parameters TLSv1.1 and TLSv1.2 are +supported starting from versions 1.1.13 and 1.0.12 +so when using OpenSSL version 1.0.1 +and higher on older nginx versions these protocols will work but could not +be disabled. + + + + + + + + + off | + none | + [builtin[:size]] + [shared:name:size] +none +mail +server + + +Sets types and sizes of caches that store session parameters. +A cache can be any of the following types: + + +off + +the use of session cache is strictly prohibited: +nginx explicitly tells a client that sessions may not be reused. + + +none + +the use of session cache is gently disallowed: +nginx tells a client that sessions may be reused, but does not +actually do that. + + +builtin + +a cache built in OpenSSL; used by one worker process only. +The cache size is specified in sessions. +If size is not given, it is equal to 20480 sessions. +Use of the built-in cache can cause memory fragmentation. + + +shared + +shared between all worker processes. +The cache size is specified in bytes; one megabyte can store +about 4000 sessions. +Each shared cache should have an arbitrary name. +A cache with the same name can be used in several +virtual servers. + + + + + + +Both cache types can be used simultaneously, for example: + +ssl_session_cache builtin:1000 shared:SSL:10m; + +but using only shared cache without the built-in cache should +be more efficient. + + + + + + +time +5m +mail +server + + +Specifies a time during which a client may reuse the +session parameters stored in a cache. + + + + + + + + on | + off | + only +off +mail +server + + + + +on + +Allow usage of STLS command for the POP3 +and STARTTLS command for the IMAP; + + +off + +Deny usage of STLS +and STARTTLS commands; + + +only + +require preliminary TLS transition. + + + + + + + +
+ +