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

<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>plain</literal></tag-name>
<tag-desc>
<link url="https://datatracker.ietf.org/doc/html/rfc3501">LOGIN</link>,
<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>

</list>
</para>

<para>
Plain text authentication methods
(the <literal>LOGIN</literal> command, <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="imap_capabilities"/>.
</para>

</directive>


<directive name="imap_capabilities">
<syntax><value>extension</value> ...</syntax>
<default>IMAP4 IMAP4rev1 UIDPLUS</default>
<context>mail</context>
<context>server</context>

<para>
Sets the
<link url="https://datatracker.ietf.org/doc/html/rfc3501">IMAP protocol</link>
extensions list that is passed to the client in response to
the <literal>CAPABILITY</literal> command.
The authentication methods specified in the <link id="imap_auth"/> directive and
<link url="https://datatracker.ietf.org/doc/html/rfc2595">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 IMAP backends
to which the clients are proxied (if these extensions are related to commands
used after the authentication, when nginx transparently proxies a client
connection to the backend).
</para>

<para>
The current list of standardized extensions is published at
<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 <value>size</value> of the buffer used for reading IMAP commands.
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>