Mercurial > hg > nginx-site
changeset 664:8283b1048b27
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: <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 +</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>