<?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="9">

<section id="directives" name="Directives">

<directive name="smtp_auth">
<syntax><value>method</value> ...</syntax>
<default>plain login</default>
<context>mail</context>
<context>server</context>

<para>
Sets permitted methods of
<link url="https://datatracker.ietf.org/doc/html/rfc2554">SASL authentication</link>
for SMTP clients.
Supported methods are:
<list type="tag">

<tag-name><literal>plain</literal></tag-name>
<tag-desc>
<link url="https://datatracker.ietf.org/doc/html/rfc4616">AUTH PLAIN</link>
</tag-desc>

<tag-name><literal>login</literal></tag-name>
<tag-desc>
<link url="https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00">AUTH LOGIN</link>
</tag-desc>

<tag-name><literal>cram-md5</literal></tag-name>
<tag-desc>
<link url="https://datatracker.ietf.org/doc/html/rfc2195">AUTH CRAM-MD5</link>.
In order for this method to work, the password must be stored unencrypted.
</tag-desc>

<tag-name><literal>external</literal></tag-name>
<tag-desc>
<link url="https://datatracker.ietf.org/doc/html/rfc4422">AUTH EXTERNAL</link> (1.11.6).
</tag-desc>

<tag-name><literal>xoauth2</literal></tag-name>
<tag-desc>
<link url="https://developers.google.com/gmail/imap/xoauth2-protocol"
>AUTH XOAUTH2</link> (1.27.1).
</tag-desc>

<tag-name><literal>oauthbearer</literal></tag-name>
<tag-desc>
<link url="https://datatracker.ietf.org/doc/html/rfc7628"
>AUTH OAUTHBEARER</link> (1.27.1).
</tag-desc>

<tag-name><literal>none</literal></tag-name>
<tag-desc>
Authentication is not required.
</tag-desc>

</list>
</para>

<para>
Plain text authentication methods
(<literal>AUTH PLAIN</literal> and <literal>AUTH LOGIN</literal>)
are always enabled,
though if the <literal>plain</literal> and <literal>login</literal> methods
are not specified,
<literal>AUTH PLAIN</literal> and <literal>AUTH LOGIN</literal>
will not be automatically included in <link id="smtp_capabilities"/>.
</para>

</directive>


<directive name="smtp_capabilities">
<syntax><value>extension</value> ...</syntax>
<default/>
<context>mail</context>
<context>server</context>

<para>
Sets the SMTP protocol extensions list
that is passed to the client in response to the
<literal>EHLO</literal> command.
The authentication methods specified in the <link id="smtp_auth"/> directive and
<link url="https://datatracker.ietf.org/doc/html/rfc3207">STARTTLS</link>
are automatically added to this list depending on the
<link doc="ngx_mail_ssl_module.xml" id="starttls"/> directive value.
</para>

<para>
It makes sense to specify the extensions
supported by the MTA
to which the clients are proxied (if these 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
<link url="http://www.iana.org/assignments/mail-parameters">www.iana.org</link>.
</para>

</directive>


<directive name="smtp_client_buffer">
<syntax><value>size</value></syntax>
<default>4k|8k</default>
<context>mail</context>
<context>server</context>

<para>
Sets the <value>size</value> of the buffer used for reading SMTP commands.
By default, the buffer size is equal to one memory page.
This is either 4K or 8K, depending on a platform.
</para>

</directive>


<directive name="smtp_greeting_delay">
<syntax><value>time</value></syntax>
<default>0</default>
<context>mail</context>
<context>server</context>

<para>
Allows setting a delay before sending an SMTP greeting
in order to reject clients who fail to wait for the greeting before
sending SMTP commands.
</para>

</directive>

</section>

</module>