maddy

  1# IMAP4rev1 endpoint
  2
  3Module 'imap' is a listener that implements IMAP4rev1 protocol and provides
  4access to local messages storage specified by 'storage' directive.
  5
  6In most cases, local storage modules will auto-create accounts when they are
  7accessed via IMAP. This relies on authentication provider used by IMAP endpoint
  8to provide what essentially is access control. There is a caveat, however: this
  9auto-creation will not happen when delivering incoming messages via SMTP as
 10there is no authentication to confirm that this account should indeed be
 11created.
 12
 13## Configuration directives
 14
 15```
 16imap tcp://0.0.0.0:143 tls://0.0.0.0:993 {
 17    tls /etc/ssl/private/cert.pem /etc/ssl/private/pkey.key
 18    io_debug no
 19    debug no
 20    insecure_auth no
 21    sasl_login no
 22    auth pam
 23    storage &local_mailboxes
 24    auth_map identity
 25    auth_map_normalize auto
 26    storage_map identity
 27    storage_map_normalize auto
 28}
 29```
 30
 31### tls _certificate-path_ _key-path_ { ... }
 32Default: global directive value
 33
 34TLS certificate & key to use. Fine-tuning of other TLS properties is possible
 35by specifying a configuration block and options inside it:
 36
 37```
 38tls cert.crt key.key {
 39    protocols tls1.2 tls1.3
 40}
 41```
 42
 43See [TLS configuration / Server](/reference/tls/#server-side) for details.
 44
 45---
 46
 47### proxy_protocol _trusted ips..._ { ... }
 48Default: not enabled
 49
 50Enable use of HAProxy PROXY protocol. Supports both v1 and v2 protocols.
 51If a list of trusted IP addresses or subnets is provided, only connections
 52from those will be trusted.
 53
 54TLS for the channel between the proxies and maddy can be configured
 55using a 'tls' directive:
 56```
 57proxy_protocol {
 58    trust 127.0.0.1 ::1 192.168.0.1/24
 59    tls &proxy_tls
 60}
 61```
 62Note that the top-level 'tls' directive is not inherited here. If you
 63need TLS on top of the PROXY protocol, securing the protocol header,
 64you must declare TLS explicitly.
 65
 66---
 67
 68### io_debug _boolean_
 69Default: `no`
 70
 71Write all commands and responses to stderr.
 72
 73---
 74
 75### io_errors _boolean_
 76Default: `no`
 77
 78Log I/O errors.
 79
 80---
 81
 82### debug _boolean_
 83Default: global directive value
 84
 85Enable verbose logging.
 86
 87---
 88
 89### insecure_auth _boolean_
 90Default: `no` (`yes` if TLS is disabled)
 91
 92Allow plain-text authentication over unencrypted connections.
 93
 94---
 95
 96### sasl_login _boolean_
 97Default: `no`
 98
 99Enable support for SASL LOGIN authentication mechanism used by
100some outdated clients.
101
102---
103
104### auth _module-reference_
105**Required.**
106
107Use the specified module for authentication.
108
109---
110
111### storage _module-reference_
112**Required.**
113
114Use the specified module for message storage.
115
116---
117
118### storage_map _module-reference_
119Default: `identity`
120
121Use the specified table to map SASL usernames to storage account names.
122
123Before username is looked up, it is normalized using function defined by
124`storage_map_normalize`.
125
126This directive is useful if you want users user@example.org and user@example.com
127to share the same storage account named "user". In this case, use
128
129```
130    storage_map email_localpart
131```
132
133Note that `storage_map` does not affect the username passed to the
134authentication provider.
135
136It also does not affect how message delivery is handled, you should specify
137`delivery_map` in storage module to define how to map email addresses
138to storage accounts. E.g.
139
140```
141    storage.imapsql local_mailboxes {
142        ...
143        delivery_map email_localpart # deliver "user@*" to mailbox for "user"
144    }
145```
146
147---
148
149### storage_map_normalize _function_
150Default: `auto`
151
152Same as `auth_map_normalize` but for `storage_map`.
153
154---
155
156### auth_map_normalize _function_
157Default: `auto`
158
159Overrides global `auth_map_normalize` value for this endpoint.
160
161See [Global configuration](/reference/global-config) for details.
162
163
164