Mercurial > hg > nginx-site

changeset 664:8283b1048b27

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Translated mail modules into English.
author Vladimir Homutov <vl@nginx.com>
date Wed, 05 Sep 2012 14:07:43 +0000
parents 639bbb0c9d05
children 99e1b47b14a7
files xml/en/GNUmakefile xml/en/docs/index.xml xml/en/docs/mail/ngx_mail_auth_http_module.xml xml/en/docs/mail/ngx_mail_core_module.xml xml/en/docs/mail/ngx_mail_imap_module.xml xml/en/docs/mail/ngx_mail_pop3_module.xml xml/en/docs/mail/ngx_mail_proxy_module.xml xml/en/docs/mail/ngx_mail_smtp_module.xml xml/en/docs/mail/ngx_mail_ssl_module.xml
diffstat 9 files changed, 1086 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- 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)
--- a/xml/en/docs/index.xml
+++ b/xml/en/docs/index.xml
@@ -300,6 +300,32 @@ ngx_http_xslt_module</link>
 </list>
 </para>
 
+<para>
+<list type="bullet">
+
+<listitem>
+<link doc="mail/ngx_mail_core_module.xml">
+ngx_mail_core_module</link>
+</listitem>
+
+<listitem>
+<link doc="mail/ngx_mail_auth_http_module.xml">
+ngx_mail_auth_http_module</link>
+</listitem>
+
+<listitem>
+<link doc="mail/ngx_mail_proxy_module.xml">
+ngx_mail_proxy_module</link>
+</listitem>
+
+<listitem>
+<link doc="mail/ngx_mail_ssl_module.xml">
+ngx_mail_ssl_module</link>
+</listitem>
+
+</list>
+</para>
+
 </section>
 
 </article>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/mail/ngx_mail_auth_http_module.xml
@@ -0,0 +1,161 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) 2006, 2007 Anton Yuzhaninov
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_mail_auth_http_module"
+        link="/ru/docs/mail/ngx_mail_auth_http_module.html"
+        lang="ru"
+        rev="1">
+
+<section id="directives" name="Directives">
+
+<directive name="auth_http">
+<syntax><value>URL</value></syntax>
+<default/>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Sets the URL of the HTTP authentication server.
+The protocol is described below.
+</para>
+
+</directive>
+
+
+<directive name="auth_http_header">
+<syntax><value>header</value> <value>value</value></syntax>
+<default/>
+<context>mail</context>
+<context>server</context>
+
+<para>
+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:
+<example>
+auth_http_header X-Auth-Key "secret_string";
+</example>
+</para>
+
+</directive>
+
+
+<directive name="auth_http_timeout">
+<syntax><value>time</value></syntax>
+<default>60s</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+</para>
+
+</directive>
+
+</section>
+
+
+<section id="protocol" name="Protocol">
+
+<para>
+The HTTP is used to communicate with the authentication server.
+The data in the response body is ignored, information is passed only in headers.
+</para>
+
+<para>
+Requests and responses examples:
+</para>
+
+<para>
+Request:
+<example>
+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
+</example>
+Good response:
+<example>
+HTTP/1.0 200 OK # this line is ignored
+Auth-Status: OK
+Auth-Server: 10.1.1.1
+Auth-Port: 143
+</example>
+Bad response:
+<example>
+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
+</example>
+</para>
+
+<para>
+If there is no the <header>Auth-Wait</header> 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 <header>Auth-Wait</header> header after 10-20 attempts
+(see the <header>Auth-Login-Attempt</header> header).
+</para>
+
+<para>
+When using the APOP or CRAM-MD5 request-reponses will look like:
+<example>
+GET /auth HTTP/1.0
+Host: localhost
+Auth-Method: apop
+Auth-User: user
+Auth-Salt: &lt;238188073.1163692009@mail.example.com&gt;
+Auth-Pass: auth_response
+Auth-Protocol: imap
+Auth-Login-Attempt: 1 # attempt count in a single session
+Client-IP: 192.168.1.1
+</example>
+Good response:
+<example>
+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
+</example>
+</para>
+
+<para>
+For the SMTP, the response additionally takes into account
+the <header>Auth-Error-Code</header> header — it is used
+as a response code if exists.
+Otherwise the code 535 5.7.0 will be added to
+the <header>Auth-Status</header> by default.
+</para>
+
+<para>
+For example, if the following response is received
+from the authentication server:
+<example>
+HTTP/1.0 200 OK
+Auth-Status: Temporary server problem, try again later
+Auth-Error-Code: 451 4.3.0
+Auth-Wait: 3
+</example>
+then the SMTP client will be given an error
+<example>
+451 4.3.0 Temporary server problem, try again later
+</example>
+</para>
+
+</section>
+
+</module>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/mail/ngx_mail_core_module.xml
@@ -0,0 +1,247 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) 2006, 2007 Anton Yuzhaninov
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_mail_core_module"
+        link="/en/docs/mail/ngx_mail_core_module.html"
+        lang="en"
+        rev="1">
+
+<section id="summary">
+
+<para>
+This module is not built by default, it should be
+enabled with
+the <literal>--with-mail</literal> configuration parameter.
+</para>
+
+</section>
+
+
+<section id="example" name="Example configuration">
+
+<para>
+<example>
+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;
+    }
+}
+</example>
+</para>
+
+</section>
+
+
+<section id="directives" name="Directives">
+
+<directive name="listen">
+<syntax>
+    <value>address</value>:<value>port</value>
+    [<literal>bind</literal>]</syntax>
+<default/>
+<context>server</context>
+
+<para>
+Sets an <value>address</value> and a <value>port</value> 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:
+<example>
+listen 127.0.0.1:110;
+listen *:110;
+listen 110;     # то же, что и *:110
+listen localhost:110;
+</example>
+IPv6 addresses (0.7.58) are specified in square brackets:
+<example>
+listen [::1]:110;
+listen [::]:110;
+</example>
+UNIX-domain sockets (1.3.5) are specified with the “<literal>unix:</literal>”
+prefix:
+<example>
+listen unix:/var/run/nginx.sock;
+</example>
+
+</para>
+
+<para>
+The optional <literal>bind</literal> parameter
+instructs to make a separate <c-func>bind</c-func>
+call for a given address:port pair.
+The fact is that nginx will <c-func>bind</c-func> only to
+<literal>*:</literal><value>port</value>
+if there are several <literal>listen</literal> directives with
+the same port but different addresses, and one of the
+<literal>listen</literal> directives listens on all addresses
+for the given port (<literal>*:</literal><value>port</value>).
+It should be noted that the <c-func>getsockname</c-func> system call will be
+made in this case to determine an address that accepted a connection.
+</para>
+
+<para>
+Different virtual servers must listen on different
+<value>address</value>:<value>port</value> pairs.
+</para>
+
+</directive>
+
+
+<directive name="protocol">
+<syntax>
+  <literal>imap</literal> |
+  <literal>pop3</literal> |
+  <literal>smtp</literal></syntax>
+<default/>
+<context>server</context>
+
+<para>
+Sets the protocol of a proxied server.
+Supported protocols are
+<link doc="ngx_mail_imap_module.xml">IMAP</link>,
+<link doc="ngx_mail_pop3_module.xml">POP3</link> and
+<link doc="ngx_mail_smtp_module.xml">SMTP</link>.
+</para>
+
+<para>
+If the directive is not set, the protocol can be detected automatically
+basing on the well-known port specified in the <link id="listen"/>
+directive:
+<list type="bullet">
+
+<listitem>
+<literal>imap</literal>: 143, 993
+</listitem>
+
+<listitem>
+<literal>pop3</literal>: 110, 995
+</listitem>
+
+<listitem>
+<literal>smtp</literal>: 25, 587, 465
+</listitem>
+
+</list>
+</para>
+
+<para>
+Unnecessary protocols can be disabled using the
+<link doc="../install.xml">configuration</link>
+parameters <literal>--without-mail_imap_module</literal>,
+<literal>--without-mail_pop3_module</literal> and
+<literal>--without-mail_smtp_module</literal>.
+</para>
+
+</directive>
+
+
+<directive name="server">
+<syntax block="yes"/>
+<default/>
+<context>mail</context>
+
+<para>
+Sets a configuration for the virtual server.
+</para>
+
+</directive>
+
+
+<directive name="server_name">
+<syntax><value>name</value></syntax>
+<default>hostname</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Sets a name of the virtual server, used:
+
+<list type="bullet">
+
+<listitem>
+in the initial POP3/SMTP server greeting;
+</listitem>
+
+<listitem>
+in the salt during the SASL CRAM-MD5 authentication;
+</listitem>
+
+<listitem>
+in the <literal>EHLO</literal> command on the SMTP backend connection,
+if the <link doc="ngx_mail_proxy_module.xml" id="xclient"/> command
+is turned on.
+</listitem>
+
+</list>
+
+</para>
+
+</directive>
+
+
+<directive name="so_keepalive">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>off</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Controls if the “TCP keepalive” mode should be enabled on the client’s
+connection (<c-def>SO_KEEPALIVE</c-def> socket parameter) on the
+proxied server connection.
+</para>
+
+</directive>
+
+
+<directive name="timeout">
+<syntax><value>time</value></syntax>
+<default>60s</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Sets the timeout which is used before proxying to the backend started.
+</para>
+
+</directive>
+
+</section>
+
+</module>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/mail/ngx_mail_imap_module.xml
@@ -0,0 +1,99 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) 2006, 2007 Anton Yuzhaninov
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_mail_imap_module"
+        link="/en/docs/mail/ngx_mail_imap_module.html"
+        lang="en"
+        rev="1">
+
+<section id="directives" name="Directives">
+
+<directive name="imap_auth">
+<syntax><value>method</value> ...</syntax>
+<default>plain</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Sets permitted methods of authentication for IMAP clients.
+Supported methods are:
+<list type="tag">
+
+<tag-name><literal>login</literal></tag-name>
+<tag-desc>
+<link url="http://tools.ietf.org/html/draft-murchison-sasl-login-00">AUTH=LOGIN</link>
+</tag-desc>
+
+<tag-name><literal>plain</literal></tag-name>
+<tag-desc>
+<link url="http://tools.ietf.org/html/rfc4616">AUTH=PLAIN</link>
+</tag-desc>
+
+<tag-name><literal>cram-md5</literal></tag-name>
+<tag-desc>
+<link url="http://tools.ietf.org/html/rfc2195">AUTH=CRAM-MD5</link>.
+In order for this method to work, the password must be stored unencrypted.
+</tag-desc>
+
+</list>
+</para>
+
+</directive>
+
+
+<directive name="imap_capabilities">
+<syntax><value>extension</value> ...</syntax>
+<default>IMAP4 IMAP4rev1 UIDPLUS</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Allows to specify the
+<link url="http://tools.ietf.org/html/rfc3501">IMAP protocol</link>
+extensions list to be passed to the client upon
+issuing the <literal>CAPABILITY</literal> command.
+Authentication methods specified in the <link id="imap_auth"/> and
+<link url="http://tools.ietf.org/html/rfc2595">STARTTLS</link> directives
+are automatically added to this list if the
+<link doc="ngx_mail_ssl_module.xml" id="starttls"/> directive is enabled.
+</para>
+
+<para>
+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).
+</para>
+
+<para>
+The current list of standardized extensions is published at the
+<link url="http://www.iana.org/assignments/imap4-capabilities">www.iana.org</link>.
+</para>
+
+</directive>
+
+
+<directive name="imap_client_buffer">
+<syntax><value>size</value></syntax>
+<default>4k|8k</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+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.
+</para>
+
+</directive>
+
+</section>
+
+</module>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/mail/ngx_mail_pop3_module.xml
@@ -0,0 +1,90 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) 2006, 2007 Anton Yuzhaninov
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_mail_pop3_module"
+        link="/en/docs/mail/ngx_mail_pop3_module.html"
+        lang="en"
+        rev="1">
+
+<section id="directives" name="Directives">
+
+<directive name="pop3_auth">
+<syntax><value>method</value> ...</syntax>
+<default>plain</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Sets permitted methods of authentication for POP3 clients.
+Supported methods are:
+<list type="tag">
+
+<tag-name><literal>plain</literal></tag-name>
+<tag-desc>
+<link url="http://tools.ietf.org/html/rfc1939">USER/PASS</link>,
+<link url="http://tools.ietf.org/html/rfc4616">AUTH PLAIN</link>,
+<link url="http://tools.ietf.org/html/draft-murchison-sasl-login-00">AUTH LOGIN</link>.
+It is not possible to disable this methods.
+</tag-desc>
+
+<tag-name><literal>apop</literal></tag-name>
+<tag-desc>
+<link url="http://tools.ietf.org/html/rfc1939">APOP</link>.
+In order for this method to work, the password must be stored unencrypted.
+</tag-desc>
+
+<tag-name><literal>cram-md5</literal></tag-name>
+<tag-desc>
+<link url="http://tools.ietf.org/html/rfc2195">AUTH CRAM-MD5</link>.
+In order for this method to work, the password must be stored unencrypted.
+</tag-desc>
+
+</list>
+</para>
+
+</directive>
+
+
+<directive name="pop3_capabilities">
+<syntax><value>extension</value> ...</syntax>
+<default>TOP USER UIDL</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Allows to specify the
+<link url="http://tools.ietf.org/html/rfc2449">POP3 protocol</link>
+extensions list to be passed to the client upon
+issuing the <literal>CAPA</literal> command.
+
+Authentication methods specified in the <link id="pop3_auth"/> and
+(<link url="http://tools.ietf.org/html/rfc2449">SASL</link> extension) and
+<link url="http://tools.ietf.org/html/rfc2595">STLS</link> directives,
+are automatically added to this list if the
+<link doc="ngx_mail_ssl_module.xml" id="starttls"/> directive is enabled.
+</para>
+
+<para>
+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).
+</para>
+
+<para>
+The current list of standardized extensions is published at the
+<link url="http://www.iana.org/assignments/pop3-extension-mechanism">www.iana.org</link>.
+</para>
+
+</directive>
+
+</section>
+
+</module>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/mail/ngx_mail_proxy_module.xml
@@ -0,0 +1,139 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) 2006, 2007 Anton Yuzhaninov
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_mail_proxy_module"
+        link="/en/docs/mail/ngx_mail_proxy_module.html"
+        lang="en"
+        rev="1">
+
+<section id="directives" name="Directives">
+
+<!--
+<directive name="proxy">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>off</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Does not tested anywhere in the current version.
+</para>
+
+</directive>
+-->
+
+
+<directive name="proxy_buffer">
+<syntax><value>size</value></syntax>
+<default>4k|8k</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+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.
+</para>
+
+</directive>
+
+
+<directive name="proxy_pass_error_message">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>off</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Defines whether to pass the error message obtained during
+an authentication on the backend to the client.
+</para>
+
+<para>
+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
+<link url="http://www.stalker.com/CommuniGatePro/Alerts.html#Quota">mailbox
+overflow</link> or other events by periodically outputting the
+<link url="http://www.stalker.com/CommuniGatePro/POP.html#Alerts">authentcation
+error</link>.
+The directive should be enabled in this case.
+</para>
+
+</directive>
+
+
+<directive name="proxy_timeout">
+<syntax><value>timeout</value></syntax>
+<default>24h</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Defines a timeout used after the proxying to the backend had started.
+</para>
+
+</directive>
+
+
+<directive name="xclient">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>on</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Enables or disables issuing of the <literal>XCLIENT</literal> command
+upon the connection to the SMTP backend.
+For the <literal>XCLIENT</literal> command to work it is required to have
+Postfix with the
+<link url="http://citrin.ru/nginx:xclient-login-patch">patch</link>,
+which adds the <literal>LOGIN</literal> parameter.
+If the <literal>XCLIENT</literal> command is not used, the MTA will be unable
+to write the client's
+<literal>IP</literal>/<literal>HELO</literal>/<literal>LOGIN</literal>
+to the log and apply various limitations based on this data.
+</para>
+
+<para>
+If the <literal>xclient</literal> is enabled,
+then upon a backend connection nginx first issues
+<example>
+EHLO server_name
+</example>
+and then
+<example>
+XCLIENT PROTO=ESMTP HELO=client_hello ADDR=192.168.1.1 LOGIN=good_user NAME=[UNAVAILABLE]
+</example>
+If the client upon a connection to nginx issued the <literal>EHLO</literal>,
+then the <literal>XCLIENT</literal> command will pass
+the <literal>PROTO=ESMTP</literal>.
+Otherwise, <literal>PROTO=SMTP</literal> will be passed.
+The IP address of a client is specified in the <literal>ADDR</literal>
+parameter, and since nginx does not use DNS to resolve the hostname,
+the <literal>NAME=[UNAVAILABLE]</literal> is specified.
+</para>
+
+<para>
+If the <literal>xclient</literal> is disabled,
+then the <literal>EHLO</literal> is issued upon the connection to the backend
+if the client had passed it and the <literal>HELO</literal>
+otherwise.
+</para>
+
+</directive>
+
+</section>
+
+</module>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/mail/ngx_mail_smtp_module.xml
@@ -0,0 +1,83 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) 2006, 2007 Anton Yuzhaninov
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_mail_smtp_module"
+        link="/en/docs/mail/ngx_mail_smtp_module.html"
+        lang="en"
+        rev="1">
+
+<section id="directives" name="Directives">
+
+<directive name="smtp_auth">
+<syntax><value>method</value> ...</syntax>
+<default>login plain</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Sets permitted methods of
+<link url="http://tools.ietf.org/html/rfc2554">SASL authentication</link>
+for SMTP clients.
+Supported methods are:
+<list type="tag">
+
+<tag-name><literal>login</literal></tag-name>
+<tag-desc>
+<link url="http://tools.ietf.org/html/draft-murchison-sasl-login-00">AUTH LOGIN</link>
+</tag-desc>
+
+<tag-name><literal>plain</literal></tag-name>
+<tag-desc>
+<link url="http://tools.ietf.org/html/rfc4616">AUTH PLAIN</link>
+</tag-desc>
+
+<tag-name><literal>cram-md5</literal></tag-name>
+<tag-desc>
+<link url="http://tools.ietf.org/html/rfc2195">AUTH CRAM-MD5</link>.
+In order for this method to work, the password must be stored unencrypted.
+</tag-desc>
+
+</list>
+</para>
+
+</directive>
+
+
+<directive name="smtp_capabilities">
+<syntax><value>extension</value> ...</syntax>
+<default/>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Allows to specify the SMTP protocol extensions list
+to be passed to the client in the response to the
+<literal>EHLO</literal> command.
+Authentication methods specified in the <link id="smtp_auth"/> directive
+are automatically added to this list.
+</para>
+
+<para>
+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).
+</para>
+
+<para>
+The current list of standardized extensions is published at the
+<link url="http://www.iana.org/assignments/mail-parameters">www.iana.org</link>.
+</para>
+
+</directive>
+
+</section>
+
+</module>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/mail/ngx_mail_ssl_module.xml
@@ -0,0 +1,234 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) 2006, 2007 Anton Yuzhaninov
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_mail_ssl_module"
+        link="/en/docs/mail/ngx_mail_ssl_module.html"
+        lang="en"
+        rev="1">
+
+<section id="summary">
+
+<para>
+The <literal>ngx_mail_ssl_module</literal> provides the necessary
+support for mail proxy server for the SSL/TLS protocol.
+</para>
+
+<para>
+This module is not built by default, it should be enabled with
+the <literal>--with-mail_ssl_module</literal>
+configuration parameter.
+<note>
+This module requires the <link url="http://www.openssl.org">OpenSSL</link>
+library.
+</note>
+</para>
+
+</section>
+
+
+<section id="directives" name="Directives">
+
+<directive name="ssl">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>off</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Enables the HTTPS protocol for the given virtual server.
+</para>
+
+</directive>
+
+
+<directive name="ssl_certificate">
+<syntax><value>file</value></syntax>
+<default/>
+<context>mail</context>
+<context>server</context>
+
+<para>
+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.
+</para>
+
+</directive>
+
+
+<directive name="ssl_certificate_key">
+<syntax><value>file</value></syntax>
+<default/>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Specifies a file with a secret key in the PEM format for the given virtual
+server.
+</para>
+
+</directive>
+
+
+<directive name="ssl_prefer_server_ciphers">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>off</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Specifies that server ciphers should be preferred over client ciphers
+when using the SSLv3 and TLS protocols.
+</para>
+
+</directive>
+
+
+<directive name="ssl_protocols">
+<syntax>
+    [<literal>SSLv2</literal>]
+    [<literal>SSLv3</literal>]
+    [<literal>TLSv1</literal>]
+    [<literal>TLSv1.1</literal>]
+    [<literal>TLSv1.2</literal>]</syntax>
+<default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Enables the specified protocols.
+The parameters <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> work
+only when using the OpenSSL library version 1.0.1 and higher.
+<note>
+The parameters <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> 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.
+</note>
+</para>
+
+</directive>
+
+
+<directive name="ssl_session_cache">
+<syntax>
+    <literal>off</literal> |
+    <literal>none</literal> |
+    [<literal>builtin</literal>[:<value>size</value>]]
+    [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax>
+<default>none</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Sets types and sizes of caches that store session parameters.
+A cache can be any of the following types:
+<list type="tag">
+
+<tag-name><literal>off</literal></tag-name>
+<tag-desc>
+the use of session cache is strictly prohibited:
+nginx explicitly tells a client that sessions may not be reused.
+</tag-desc>
+
+<tag-name><literal>none</literal></tag-name>
+<tag-desc>
+the use of session cache is gently disallowed:
+nginx tells a client that sessions may be reused, but does not
+actually do that.
+</tag-desc>
+
+<tag-name><literal>builtin</literal></tag-name>
+<tag-desc>
+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.
+</tag-desc>
+
+<tag-name><literal>shared</literal></tag-name>
+<tag-desc>
+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.
+</tag-desc>
+
+</list>
+</para>
+
+<para>
+Both cache types can be used simultaneously, for example:
+<example>
+ssl_session_cache builtin:1000 shared:SSL:10m;
+</example>
+but using only shared cache without the built-in cache should
+be more efficient.
+</para>
+
+</directive>
+
+
+<directive name="ssl_session_timeout">
+<syntax><value>time</value></syntax>
+<default>5m</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+Specifies a time during which a client may reuse the
+session parameters stored in a cache.
+</para>
+
+</directive>
+
+
+<directive name="starttls">
+<syntax>
+  <literal>on</literal> |
+  <literal>off</literal> |
+  <literal>only</literal></syntax>
+<default>off</default>
+<context>mail</context>
+<context>server</context>
+
+<para>
+<list type="tag">
+
+<tag-name><literal>on</literal></tag-name>
+<tag-desc>
+Allow usage of <literal>STLS</literal> command for the POP3
+and <literal>STARTTLS</literal> command for the IMAP;
+</tag-desc>
+
+<tag-name><literal>off</literal></tag-name>
+<tag-desc>
+Deny usage of <literal>STLS</literal>
+and <literal>STARTTLS</literal> commands;
+</tag-desc>
+
+<tag-name><literal>only</literal></tag-name>
+<tag-desc>
+require preliminary TLS transition.
+</tag-desc>
+
+</list>
+</para>
+
+</directive>
+
+</section>
+
+</module>