mirror/docker-mailserver.docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2025-07-24 04:34:50 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Merge branch 'master' into add-send-only-aliases

Browse source
This commit is contained in:
Noah Overcash 2025-03-31 21:08:12 -04:00
commit bed51886f4
No known key found for this signature in database
107 changed files with 2727 additions and 3301 deletions
Download patch file Download diff file Expand all files Collapse all files

308
docs/content/config/advanced/auth-ldap.md
View file

@ -1,308 +0,0 @@
---
title: 'Advanced | LDAP Authentication'
---
## Introduction
Getting started with ldap and DMS we need to take 3 parts in account:
- `postfix` for incoming & outgoing email
- `dovecot` for accessing mailboxes
- `saslauthd` for SMTP authentication (this can also be delegated to dovecot)
## Variables to Control Provisioning by the Container
Have a look at [the ENV page][docs-environment] for information on the default values.
### `LDAP_QUERY_FILTER_*`
Those variables contain the LDAP lookup filters for postfix, using `%s` as the placeholder for the domain or email address in question. This means that...
- ...for incoming email, the domain must return an entry for the `DOMAIN` filter (see [`virtual_alias_domains`](http://www.postfix.org/postconf.5.html#virtual_alias_domains)).
- ...for incoming email, the inboxes which receive the email are chosen by the `USER`, `ALIAS` and `GROUP` filters.
- The `USER` filter specifies personal mailboxes, for which only one should exist per address, for example `(mail=%s)` (also see [`virtual_mailbox_maps`](http://www.postfix.org/postconf.5.html#virtual_mailbox_maps))
- The `ALIAS` filter specifies aliases for mailboxes, using [`virtual_alias_maps`](http://www.postfix.org/postconf.5.html#virtual_alias_maps), for example `(mailAlias=%s)`
- The `GROUP` filter specifies the personal mailboxes in a group (for emails that multiple people shall receive), using [`virtual_alias_maps`](http://www.postfix.org/postconf.5.html#virtual_alias_maps), for example `(mailGroupMember=%s)`.
- Technically, there is no difference between `ALIAS` and `GROUP`, but ideally you should use `ALIAS` for personal aliases for a singular person (like `ceo@example.org`) and `GROUP` for multiple people (like `hr@example.org`).
- ...for outgoing email, the sender address is put through the `SENDERS` filter, and only if the authenticated user is one of the returned entries, the email can be sent.
- This only applies if `SPOOF_PROTECTION=1`.
- If the `SENDERS` filter is missing, the `USER`, `ALIAS` and `GROUP` filters will be used in a disjunction (OR).
- To for example allow users from the `admin` group to spoof any sender email address, and to force everyone else to only use their personal mailbox address for outgoing email, you can use something like this: `(|(memberOf=cn=admin,*)(mail=%s))`
???+ example
A really simple `LDAP_QUERY_FILTER` configuration, using only the _user filter_ and allowing only `admin@*` to spoof any sender addresses.
```yaml
- LDAP_START_TLS=yes
- ACCOUNT_PROVISIONER=LDAP
- LDAP_SERVER_HOST=ldap.example.org
- LDAP_SEARCH_BASE=dc=example,dc=org"
- LDAP_BIND_DN=cn=admin,dc=example,dc=org
- LDAP_BIND_PW=mypassword
- SPOOF_PROTECTION=1
- LDAP_QUERY_FILTER_DOMAIN=(mail=*@%s)
- LDAP_QUERY_FILTER_USER=(mail=%s)
- LDAP_QUERY_FILTER_ALIAS=(|) # doesn't match anything
- LDAP_QUERY_FILTER_GROUP=(|) # doesn't match anything
- LDAP_QUERY_FILTER_SENDERS=(|(mail=%s)(mail=admin@*))
```
### `DOVECOT_*_FILTER` & `DOVECOT_*_ATTRS`
These variables specify the LDAP filters that dovecot uses to determine if a user can log in to their IMAP account, and which mailbox is responsible to receive email for a specific postfix user.
This is split into the following two lookups, both using `%u` as the placeholder for the full login name ([see dovecot documentation for a full list of placeholders](https://doc.dovecot.org/configuration_manual/config_file/config_variables/)). Usually you only need to set `DOVECOT_USER_FILTER`, in which case it will be used for both filters.
- `DOVECOT_USER_FILTER` is used to get the account details (uid, gid, home directory, quota, ...) of a user.
- `DOVECOT_PASS_FILTER` is used to get the password information of the user, and is in pretty much all cases identical to `DOVECOT_USER_FILTER` (which is the default behavior if left away).
If your directory doesn't have the [postfix-book schema](https://github.com/variablenix/ldap-mail-schema/blob/master/postfix-book.schema) installed, then you must change the internal attribute handling for dovecot. For this you have to change the `pass_attr` and the `user_attr` mapping, as shown in the example below:
```yaml
- DOVECOT_PASS_ATTRS=<YOUR_USER_IDENTIFIER_ATTRIBUTE>=user,<YOUR_USER_PASSWORD_ATTRIBUTE>=password
- DOVECOT_USER_ATTRS=<YOUR_USER_HOME_DIRECTORY_ATTRIBUTE>=home,<YOUR_USER_MAILSTORE_ATTRIBUTE>=mail,<YOUR_USER_MAIL_UID_ATTRIBUTE>=uid,<YOUR_USER_MAIL_GID_ATTRIBUTE>=gid
```
!!! note
For `DOVECOT_*_ATTRS`, you can replace `ldapAttr=dovecotAttr` with `=dovecotAttr=%{ldap:ldapAttr}` for more flexibility, like for example `=home=/var/mail/%{ldap:uid}` or just `=uid=5000`.
A list of dovecot attributes can be found [in the dovecot documentation](https://doc.dovecot.org/configuration_manual/authentication/user_databases_userdb/#authentication-user-database).
???+ example "Defaults"
```yaml
- DOVECOT_USER_ATTRS=mailHomeDirectory=home,mailUidNumber=uid,mailGidNumber=gid,mailStorageDirectory=mail
- DOVECOT_PASS_ATTRS=uniqueIdentifier=user,userPassword=password
- DOVECOT_USER_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
```
???+ example
Setup for a directory that has the [qmail-schema](https://github.com/amery/qmail/blob/master/qmail.schema) installed and uses `uid`:
```yaml
- DOVECOT_PASS_ATTRS=uid=user,userPassword=password
- DOVECOT_USER_ATTRS=homeDirectory=home,qmailUID=uid,qmailGID=gid,mailMessageStore=mail
- DOVECOT_USER_FILTER=(&(objectClass=qmailUser)(uid=%u)(accountStatus=active))
```
The LDAP server configuration for dovecot will be taken mostly from postfix, other options can be found in [the environment section in the docs][docs-environment].
### `DOVECOT_AUTH_BIND`
Set this to `yes` to enable authentication binds ([more details in the dovecot documentation](https://wiki.dovecot.org/AuthDatabase/LDAP/AuthBinds)). Currently, only DN lookup is supported without further changes to the configuration files, so this is only useful when you want to bind as a readonly user without the permission to read passwords.
### `SASLAUTHD_LDAP_FILTER`
This filter is used for `saslauthd`, which is called by postfix when someone is authenticating through SMTP (assuming that `SASLAUTHD_MECHANISMS=ldap` is being used). Note that you'll need to set up the LDAP server for saslauthd separately from postfix.
The filter variables are explained in detail [in the `LDAP_SASLAUTHD` file](https://github.com/winlibs/cyrus-sasl/blob/master/saslauthd/LDAP_SASLAUTHD#L121), but unfortunately, this method doesn't really support domains right now - that means that `%U` is the only token that makes sense in this variable.
!!! note "When to use this and how to avoid it"
Using a separate filter for SMTP authentication allows you to for example allow `noreply@example.org` to send email, but not log in to IMAP or receive email: `(&(mail=%U@example.org)(|(memberOf=cn=email,*)(mail=noreply@example.org)))`
If you don't want to use a separate filter for SMTP authentication, you can set `SASLAUTHD_MECHANISMS=rimap` and `SASLAUTHD_MECH_OPTIONS=127.0.0.1` to authenticate against dovecot instead - this means that the `DOVECOT_USER_FILTER` and `DOVECOT_PASS_FILTER` will be used for SMTP authentication as well.
???+ example "Configure LDAP with `saslauthd`"
```yaml
- ENABLE_SASLAUTHD=1
- SASLAUTHD_MECHANISMS=ldap
- SASLAUTHD_LDAP_FILTER=(mail=%U@example.org)
```
## Secure Connection with LDAPS or StartTLS
To enable LDAPS, all you need to do is to add the protocol to `LDAP_SERVER_HOST`, for example `ldaps://example.org:636`.
To enable LDAP over StartTLS (on port 389), you need to set the following environment variables instead (the **protocol must not be `ldaps://`** in this case!):
```yaml
- LDAP_START_TLS=yes
- DOVECOT_TLS=yes
- SASLAUTHD_LDAP_START_TLS=yes
```
## Active Directory Configurations (Tested with Samba4 AD Implementation)
In addition to LDAP explanation above, when Docker Mailserver is intended to be used with Active Directory (or the equivalent implementations like Samba4 AD DC) the following points should be taken into consideration:
- Samba4 Active Directory requires a **secure connection** to the domain controller (DC), either via SSL/TLS (LDAPS) or via StartTLS.
- The username equivalent in Active Directory is: `sAMAccountName`.
- `proxyAddresses` can be used to store email aliases of single users. The convention is to prefix the email aliases with `smtp:` (e.g: `smtp:some.name@example.com`).
- Active Directory is used typically not only as LDAP Directory storage, but also as a _domain controller_, i.e., it will do many things including authenticating users. Mixing Linux and Windows clients requires the usage of [RFC2307 attributes](https://wiki.samba.org/index.php/Administer_Unix_Attributes_in_AD_using_samba-tool_and_ldb-tools), namely `uidNumber`, `gidNumber` instead of the typical `uid`. Assigning different owner to email folders can also be done in this approach, nevertheless [there is a bug at the moment in Docker Mailserver that overwrites all permissions](https://github.com/docker-mailserver/docker-mailserver/pull/2256) when starting the container. Either a manual fix is necessary now, or a temporary workaround to use a hard-coded `ldap:uidNumber` that equals to `5000` until this issue is fixed.
- To deliver the emails to different members of Active Directory **Security Group** or **Distribution Group** (similar to mailing lists), use a [`user-patches.sh` script][docs-userpatches] to modify `ldap-groups.cf` so that it includes `leaf_result_attribute = mail` and `special_result_attribute = member`. This can be achieved simply by:
The configuration shown to get the Group to work is from [here](https://doc.zarafa.com/trunk/Administrator_Manual/en-US/html/_MTAIntegration.html) and [here](https://kb.kopano.io/display/WIKI/Postfix).
```bash
# user-patches.sh
...
grep -q '^leaf_result_attribute = mail$' /etc/postfix/ldap-groups.cf || echo "leaf_result_attribute = mail" >> /etc/postfix/ldap-groups.cf
grep -q '^special_result_attribute = member$' /etc/postfix/ldap-groups.cf || echo "special_result_attribute = member" >> /etc/postfix/ldap-groups.cf
...
```
- In `/etc/ldap/ldap.conf`, if the `TLS_REQCERT` is `demand` / `hard` (default), the CA certificate used to verify the LDAP server certificate must be recognized as a trusted CA. This can be done by volume mounting the `ca.crt` file and updating the trust store via a `user-patches.sh` script:
```bash
# user-patches.sh
...
cp /MOUNTED_FOLDER/ca.crt /usr/local/share/ca-certificates/
update-ca-certificates
...
```
The changes on the configurations necessary to work with Active Directory (**only changes are listed, the rest of the LDAP configuration can be taken from the other examples** shown in this documentation):
```yaml
# If StartTLS is the chosen method to establish a secure connection with Active Directory.
- LDAP_START_TLS=yes
- SASLAUTHD_LDAP_START_TLS=yes
- DOVECOT_TLS=yes
- LDAP_QUERY_FILTER_USER=(&(objectclass=person)(mail=%s))
- LDAP_QUERY_FILTER_ALIAS=(&(objectclass=person)(proxyAddresses=smtp:%s))
# Filters Active Directory groups (mail lists). Additional changes on ldap-groups.cf are also required as shown above.
- LDAP_QUERY_FILTER_GROUP=(&(objectClass=group)(mail=%s))
- LDAP_QUERY_FILTER_DOMAIN=(mail=*@%s)
# Allows only Domain admins to send any sender email address, otherwise the sender address must match the LDAP attribute `mail`.
- SPOOF_PROTECTION=1
- LDAP_QUERY_FILTER_SENDERS=(|(mail=%s)(proxyAddresses=smtp:%s)(memberOf=cn=Domain Admins,cn=Users,dc=*))
- DOVECOT_USER_FILTER=(&(objectclass=person)(sAMAccountName=%n))
# At the moment to be able to use %{ldap:uidNumber}, a manual bug fix as described above must be used. Otherwise %{ldap:uidNumber} %{ldap:uidNumber} must be replaced by the hard-coded value 5000.
- DOVECOT_USER_ATTRS==uid=%{ldap:uidNumber},=gid=5000,=home=/var/mail/%Ln,=mail=maildir:~/Maildir
- DOVECOT_PASS_ATTRS=sAMAccountName=user,userPassword=password
- SASLAUTHD_LDAP_FILTER=(&(sAMAccountName=%U)(objectClass=person))
```
## LDAP Setup Examples
???+ example "Basic Setup"
```yaml
services:
mailserver:
image: ghcr.io/docker-mailserver/docker-mailserver:latest
container_name: mailserver
hostname: mail.example.com
ports:
- "25:25"
- "143:143"
- "587:587"
- "993:993"
volumes:
- ./docker-data/dms/mail-data/:/var/mail/
- ./docker-data/dms/mail-state/:/var/mail-state/
- ./docker-data/dms/mail-logs/:/var/log/mail/
- ./docker-data/dms/config/:/tmp/docker-mailserver/
- /etc/localtime:/etc/localtime:ro
environment:
- ENABLE_SPAMASSASSIN=1
- ENABLE_CLAMAV=1
- ENABLE_FAIL2BAN=1
- ENABLE_POSTGREY=1
# >>> Postfix LDAP Integration
- ACCOUNT_PROVISIONER=LDAP
- LDAP_SERVER_HOST=ldap.example.org
- LDAP_BIND_DN=cn=admin,ou=users,dc=example,dc=org
- LDAP_BIND_PW=mypassword
- LDAP_SEARCH_BASE=dc=example,dc=org
- LDAP_QUERY_FILTER_DOMAIN=(|(mail=*@%s)(mailAlias=*@%s)(mailGroupMember=*@%s))
- LDAP_QUERY_FILTER_USER=(&(objectClass=inetOrgPerson)(mail=%s))
- LDAP_QUERY_FILTER_ALIAS=(&(objectClass=inetOrgPerson)(mailAlias=%s))
- LDAP_QUERY_FILTER_GROUP=(&(objectClass=inetOrgPerson)(mailGroupMember=%s))
- LDAP_QUERY_FILTER_SENDERS=(&(objectClass=inetOrgPerson)(|(mail=%s)(mailAlias=%s)(mailGroupMember=%s)))
- SPOOF_PROTECTION=1
# <<< Postfix LDAP Integration
# >>> Dovecot LDAP Integration
- DOVECOT_USER_FILTER=(&(objectClass=inetOrgPerson)(mail=%u))
- DOVECOT_PASS_ATTRS=uid=user,userPassword=password
- DOVECOT_USER_ATTRS==home=/var/mail/%{ldap:uid},=mail=maildir:~/Maildir,uidNumber=uid,gidNumber=gid
# <<< Dovecot LDAP Integration
# >>> SASL LDAP Authentication
- ENABLE_SASLAUTHD=1
- SASLAUTHD_MECHANISMS=ldap
- SASLAUTHD_LDAP_FILTER=(&(mail=%U@example.org)(objectClass=inetOrgPerson))
# <<< SASL LDAP Authentication
- SSL_TYPE=letsencrypt
- PERMIT_DOCKER=host
cap_add:
- NET_ADMIN
```
??? example "Kopano / Zarafa"
```yaml
services:
mailserver:
image: ghcr.io/docker-mailserver/docker-mailserver:latest
container_name: mailserver
hostname: mail.example.com
ports:
- "25:25"
- "143:143"
- "587:587"
- "993:993"
volumes:
- ./docker-data/dms/mail-data/:/var/mail/
- ./docker-data/dms/mail-state/:/var/mail-state/
- ./docker-data/dms/config/:/tmp/docker-mailserver/
environment:
# We are not using dovecot here
- SMTP_ONLY=1
- ENABLE_SPAMASSASSIN=1
- ENABLE_CLAMAV=1
- ENABLE_FAIL2BAN=1
- ENABLE_POSTGREY=1
- SASLAUTHD_PASSWD=
# >>> SASL Authentication
- ENABLE_SASLAUTHD=1
- SASLAUTHD_LDAP_FILTER=(&(sAMAccountName=%U)(objectClass=person))
- SASLAUTHD_MECHANISMS=ldap
# <<< SASL Authentication
# >>> Postfix Ldap Integration
- ACCOUNT_PROVISIONER=LDAP
- LDAP_SERVER_HOST=<yourLdapContainer/yourLdapServer>
- LDAP_SEARCH_BASE=dc=mydomain,dc=loc
- LDAP_BIND_DN=cn=Administrator,cn=Users,dc=mydomain,dc=loc
- LDAP_BIND_PW=mypassword
- LDAP_QUERY_FILTER_USER=(&(objectClass=user)(mail=%s))
- LDAP_QUERY_FILTER_GROUP=(&(objectclass=group)(mail=%s))
- LDAP_QUERY_FILTER_ALIAS=(&(objectClass=user)(otherMailbox=%s))
- LDAP_QUERY_FILTER_DOMAIN=(&(|(mail=*@%s)(mailalias=*@%s)(mailGroupMember=*@%s))(mailEnabled=TRUE))
# <<< Postfix Ldap Integration
# >>> Kopano Integration
- POSTFIX_DAGENT=lmtp:kopano:2003
# <<< Kopano Integration
- SSL_TYPE=letsencrypt
- PERMIT_DOCKER=host
cap_add:
- NET_ADMIN
```
[docs-environment]: ../environment.md
[docs-userpatches]: ./override-defaults/user-patches.md

69
docs/content/config/advanced/auth-oauth2.md
View file

@ -1,69 +0,0 @@
---
title: 'Advanced | Basic OAuth2 Authentication'
---
## Introduction
!!! warning "This is only a supplement to the existing account provisioners"
Accounts must still be managed via the configured [`ACCOUNT_PROVISIONER`][env::account-provisioner] (FILE or LDAP).
Reasoning for this can be found in [#3480][gh-pr::oauth2]. Future iterations on this feature may allow it to become a full account provisioner.
[gh-pr::oauth2]: https://github.com/docker-mailserver/docker-mailserver/pull/3480
[env::account-provisioner]: ../environment.md#account_provisioner
The present OAuth2 support provides the capability for 3rd-party applications such as Roundcube to authenticate with DMS (dovecot) by using a token obtained from an OAuth2 provider, instead of passing passwords around.
## Example (Authentik & Roundcube)
This example assumes you have:
- A working DMS server set up
- An Authentik server set up ([documentation](https://goauthentik.io/docs/installation/))
- A Roundcube server set up (either [docker](https://hub.docker.com/r/roundcube/roundcubemail/) or [bare metal](https://github.com/roundcube/roundcubemail/wiki/Installation))
!!! example "Setup Instructions"
=== "1. Docker Mailserver"
Edit the following values in `mailserver.env`:
```env
# -----------------------------------------------
# --- OAUTH2 Section ----------------------------
# -----------------------------------------------
# empty => OAUTH2 authentication is disabled
# 1 => OAUTH2 authentication is enabled
ENABLE_OAUTH2=1
# Specify the user info endpoint URL of the oauth2 provider
OAUTH2_INTROSPECTION_URL=https://authentik.example.com/application/o/userinfo/
```
=== "2. Authentik"
1. Create a new OAuth2 provider
2. Note the client id and client secret
3. Set the allowed redirect url to the equivalent of `https://roundcube.example.com/index.php/login/oauth` for your RoundCube instance.
=== "3. Roundcube"
Add the following to `oauth2.inc.php` ([documentation](https://github.com/roundcube/roundcubemail/wiki/Configuration)):
```php
$config['oauth_provider'] = 'generic';
$config['oauth_provider_name'] = 'Authentik';
$config['oauth_client_id'] = '<insert client id here>';
$config['oauth_client_secret'] = '<insert client secret here>';
$config['oauth_auth_uri'] = 'https://authentik.example.com/application/o/authorize/';
$config['oauth_token_uri'] = 'https://authentik.example.com/application/o/token/';
$config['oauth_identity_uri'] = 'https://authentik.example.com/application/o/userinfo/';
// Optional: disable SSL certificate check on HTTP requests to OAuth server. For possible values, see:
// http://docs.guzzlephp.org/en/stable/request-options.html#verify
$config['oauth_verify_peer'] = false;
$config['oauth_scope'] = 'email openid profile';
$config['oauth_identity_fields'] = ['email'];
// Boolean: automatically redirect to OAuth login when opening Roundcube without a valid session
$config['oauth_login_redirect'] = false;
```

21
docs/content/config/advanced/dovecot-master-accounts.md
View file

@ -1,21 +0,0 @@
---
title: 'Advanced | Dovecot master accounts'
---
## Introduction
A dovecot master account is able to login as any configured user. This is useful for administrative tasks like hot backups.
## Configuration
It is possible to create, update, delete and list dovecot master accounts using `setup.sh`. See `setup.sh help` for usage.
This feature is presently [not supported with LDAP](https://github.com/docker-mailserver/docker-mailserver/pull/2535).
## Logging in
Once a master account is configured, it is possible to connect to any users mailbox using this account. Log in over POP3/IMAP using the following credential scheme:
Username: `<EMAIL ADDRESS>*<MASTER ACCOUNT NAME>`
Password: `<MASTER ACCOUNT PASSWORD>`

2
docs/content/config/advanced/mail-forwarding/relay-hosts.md
View file

@ -151,6 +151,6 @@ We provide this support via two config files:
[wikipedia::smarthost]: https://en.wikipedia.org/wiki/Smart_host
[docs::env-relay]: ../../environment.md#relay-host
[dms-repo::helpers-relay]: https://github.com/docker-mailserver/docker-mailserver/blob/v14.0.0/target/scripts/helpers/relay.sh
[dms-repo::helpers-relay]: https://github.com/docker-mailserver/docker-mailserver/blob/v15.0.0/target/scripts/helpers/relay.sh
[dms-gh::pr-3607]: https://github.com/docker-mailserver/docker-mailserver/issues/3607
[dms-gh::relay-example]: https://github.com/docker-mailserver/docker-mailserver/issues/3842#issuecomment-1913380639

33
docs/content/config/advanced/mail-getmail.md
View file

@ -10,14 +10,19 @@ environment:
- GETMAIL_POLL=5
```
In your DMS config volume (eg: `docker-data/dms/config/`), create a `getmail-<ID>.cf` file for each remote account that you want to retrieve mail and store into a local DMS account. `<ID>` should be replaced by you, and is just the rest of the filename (eg: `getmail-example.cf`). The contents of each file should be configuration like documented below.
In your DMS config volume (eg: `docker-data/dms/config/`), add a subdirectory `getmail/` for including your getmail config files (eg: `imap-example.cf`) for each remote account that you want to retrieve mail from and deliver to the mailbox of a DMS account.
The directory structure should similar to this:
The content of these config files is documented in the next section with an IMAP and POP3 example to reference.
The directory structure should look similar to this:
```txt
├── docker-data/dms/config
│   ├── dovecot.cf
│   ├── getmail-example.cf
│ ├── getmail
│   │ ├── getmailrc_general.cf
│   │ ├── remote-account1.cf
│   │ ├── remote-account2.cf
│   ├── postfix-accounts.cf
│   └── postfix-virtual.cf
├── docker-compose.yml
@ -42,9 +47,13 @@ received = false
delivered_to = false
```
If you want to use a different base config, mount a file to `/etc/getmailrc_general`. This file will replace the default "Common Options" base config above, that all `getmail-<ID>.cf` files will extend with their configs when used.
The DMS integration for Getmail generates a `getmailrc` config that prepends the common options of the base config to each remote account config file (`*.cf`) found in the DMS Config Volume `getmail/` directory.
??? example "IMAP Configuration"
!!! tip "Change the base options"
Add your own base config as `getmail/getmailrc_general.cf` into the DMS Config Volume. It will replace the DMS defaults shown above.
??? example "IMAP Configuration"
This example will:
@ -54,7 +63,7 @@ If you want to use a different base config, mount a file to `/etc/getmailrc_gene
```getmailrc
[retriever]
type = SimpleIMAPRetriever
type = SimpleIMAPSSLRetriever
server = imap.gmail.com
username = alice
password = notsecure
@ -71,7 +80,7 @@ If you want to use a different base config, mount a file to `/etc/getmailrc_gene
```getmailrc
[retriever]
type = SimplePOP3Retriever
type = SimplePOP3SSLRetriever
server = pop3.gmail.com
username = alice
password = notsecure
@ -84,7 +93,7 @@ If you want to use a different base config, mount a file to `/etc/getmailrc_gene
### Polling Interval
By default the `getmail` service checks external mail accounts for new mail every 5 minutes. That polling interval is configurable via the `GETMAIL_POLL` ENV variable, with a value in minutes (_default: 5, min: 1, max: 30_):
By default the `getmail` service checks external mail accounts for new mail every 5 minutes. That polling interval is configurable via the `GETMAIL_POLL` ENV variable, with a value in minutes (_default: 5, min: 1_):
```yaml
environment:
@ -99,3 +108,11 @@ It is possible to utilize the `getmail-gmail-xoauth-tokens` helper to provide au
[getmail-docs]: https://getmail6.org/configuration.html
[getmail-docs-xoauth-12]: https://github.com/getmail6/getmail6/blob/1f95606156231f1e074ba62a9baa64f892a92ef8/docs/getmailrc-examples#L286
[getmail-docs-xoauth-13]: https://github.com/getmail6/getmail6/blob/1f95606156231f1e074ba62a9baa64f892a92ef8/docs/getmailrc-examples#L351
## Debugging
To debug your `getmail` configurations, run this `setup debug` command:
```sh
docker exec -it dms-container-name setup debug getmail
```

94
docs/content/config/advanced/mail-sieve.md
View file

@ -81,22 +81,76 @@ For more examples or a detailed description of the Sieve language have a look at
[sieve-info::examples]: http://sieve.info/examplescripts
[third-party::sieve-examples]: https://support.tigertech.net/sieve#sieve-example-rules-jmp
## Automatic Sorting Based on Subaddresses
## Automatic Sorting Based on Sub-addresses { #subaddress-mailbox-routing }
It is possible to sort subaddresses such as `user+mailing-lists@example.com` into a corresponding folder (here: `INBOX/Mailing-lists`) automatically.
When mail is delivered to your account, it is possible to organize storing mail into folders by the [subaddress (tag)][docs::accounts-subaddressing] used.
```sieve
require ["envelope", "fileinto", "mailbox", "subaddress", "variables"];
!!! example "Example: `user+<tag>@example.com` to `INBOX/<Tag>`"
if envelope :detail :matches "to" "*" {
set :lower :upperfirst "tag" "${1}";
if mailboxexists "INBOX.${1}" {
fileinto "INBOX.${1}";
} else {
fileinto :create "INBOX.${tag}";
}
}
```
This example sorts mail into inbox folders by their tag:
```sieve title="docker-data/dms/config/user@example.com.dovecot.sieve"
require ["envelope", "fileinto", "mailbox", "subaddress", "variables"];
# Check if the mail recipient address has a tag (:detail)
if envelope :detail :matches "to" "*" {
# Create a variable `tag`, with the the captured `to` value normalized (SoCIAL => Social)
set :lower :upperfirst "tag" "${1}";
# Store the mail into a folder with the tag name, nested under your inbox folder:
if mailboxexists "INBOX.${tag}" {
fileinto "INBOX.${tag}";
} else {
fileinto :create "INBOX.${tag}";
}
}
```
When receiving mail for `user+social@example.com` it would be delivered into the `INBOX/Social` folder.
??? tip "Only redirect mail for specific tags"
If you want to only handle specific tags, you could replace the envelope condition and tag assignment from the prior example with:
```sieve title="docker-data/dms/config/user@example.com.dovecot.sieve"
# Instead of `:matches`, use the default comparator `:is` (exact match)
if envelope :detail "to" "social" {
set "tag" "Social";
```
```sieve title="docker-data/dms/config/user@example.com.dovecot.sieve"
# Alternatively you can also provide a list of values to match:
if envelope :detail "to" ["azure", "aws"] {
set "tag" "Cloud";
```
```sieve title="docker-data/dms/config/user@example.com.dovecot.sieve"
# Similar to `:matches`, except `:regex` provides enhanced pattern matching.
# NOTE: This example needs you to `require` the "regex" extension
if envelope :detail :regex "to" "^cloud-(azure|aws)$" {
# Normalize the captured azure/aws tag as the resolved value is no longer fixed:
set :lower :upperfirst "vendor" "${1}";
# If a `.` exists in the tag, it will create nested folders:
set "tag" "Cloud.${vendor}";
```
**NOTE:** There is no need to lowercase the tag in the conditional as the [`to` value is a case-insensitive check][sieve-docs::envelope].
??? abstract "Technical Details"
- Dovecot supports this feature via the _Sieve subaddress extension_ ([RFC 5233][rfc::5233::sieve-subaddress]).
- Only a single tag per subaddress is supported. Any additional tag delimiters are part of the tag value itself.
- The Dovecot setting [`recipient_delimiter`][dovecot-docs::config::recipient_delimiter] (default: `+`) configures the tag delimiter. This is where the `local-part` of the recipient address will split at, providing the `:detail` (tag) value for Sieve.
---
`INBOX` is the [default namespace configured by Dovecot][dovecot-docs::namespace].
- If you omit the `INBOX.` prefix from the sieve script above, the mailbox (folder) for that tag is created at the top-level alongside your Trash and Junk folders.
- The `.` between `INBOX` and `${tag}` is important as a [separator to distinguish mailbox names][dovecot-docs::mailbox-names]. This can vary by mailbox format or configuration. DMS uses [`Maildir`][dovecot-docs::mailbox-formats::maildir] by default, which uses `.` as the separator.
- [`lmtp_save_to_detail_mailbox = yes`][dovecot-docs::config::lmtp_save_to_detail_mailbox] can be set in `/etc/dovecot/conf.d/20-lmtp.conf`:
- This implements the feature globally, except for the tag normalization and `INBOX.` prefix parts of the example script.
- However, if the sieve script is also present, the script has precedence and will handle this task instead when the condition is successful, otherwise falling back to the global feature.
## Manage Sieve
@ -104,8 +158,7 @@ The [Manage Sieve](https://doc.dovecot.org/admin_manual/pigeonhole_managesieve_s
!!! example
```yaml
# compose.yaml
```yaml title="compose.yaml"
ports:
- "4190:4190"
environment:
@ -122,3 +175,14 @@ The extension is known to work with the following ManageSieve clients:
- **[Sieve Editor](https://github.com/thsmi/sieve)** a portable standalone application based on the former Thunderbird plugin.
- **[Kmail](https://kontact.kde.org/components/kmail/)** the mail client of [KDE](https://kde.org/)'s Kontact Suite.
[docs::accounts-subaddressing]: ../account-management/overview.md#sub-addressing
[dovecot-docs::namespace]: https://doc.dovecot.org/configuration_manual/namespace/
[dovecot-docs::mailbox-names]: https://doc.dovecot.org/configuration_manual/sieve/usage/#mailbox-names
[dovecot-docs::mailbox-formats::maildir]: https://doc.dovecot.org/admin_manual/mailbox_formats/maildir/#maildir-mbox-format
[dovecot-docs::config::lmtp_save_to_detail_mailbox]: https://doc.dovecot.org/settings/core/#core_setting-lmtp_save_to_detail_mailbox
[dovecot-docs::config::recipient_delimiter]: https://doc.dovecot.org/settings/core/#core_setting-recipient_delimiter
[rfc::5233::sieve-subaddress]: https://datatracker.ietf.org/doc/html/rfc5233
[sieve-docs::envelope]: https://thsmi.github.io/sieve-reference/en/test/core/envelope.html

15
docs/content/config/advanced/optional-config.md
View file

@ -18,10 +18,7 @@ DMS has several locations in the container which may be worth persisting externa
- [Config](#volumes-config): `docker-data/dms/config/` => `/tmp/docker-mailserver/`
- [Mail Storage](#volumes-mail): `docker-data/dms/mail-data/` => `/var/mail/`
- [State](#volumes-state): `docker-data/dms/mail-state/` => `/var/mail-state/`
- [Logs](#volumes-logs): `docker-data/dms/mail-logs/` => `/var/log/mail/`
[docker-docs::volumes]: https://docs.docker.com/storage/volumes/
[docker-docs::volumes::bind-mount]: https://docs.docker.com/storage/bind-mounts/
- [Logs](#volumes-log): `docker-data/dms/mail-logs/` => `/var/log/mail/`
### Mail Storage Volume { #volumes-mail }
@ -80,8 +77,8 @@ This is a list of all configuration files and directories which are optional, au
- **postfix-send-access.cf:** List of users denied sending. Modify via [`setup.sh email restrict`][docs-setupsh].
- **postfix-receive-access.cf:** List of users denied receiving. Modify via [`setup.sh email restrict`][docs-setupsh].
- **postfix-virtual.cf:** Alias configuration file. Modify via [`setup.sh alias`][docs-setupsh].
- **postfix-sasl-password.cf:** listing of relayed domains with their respective `<username>:<password>`. Modify via `setup.sh relay add-auth <domain> <username> [<password>]`. (Docs: [Relay-Hosts Auth][docs-relayhosts-senderauth])
- **postfix-relaymap.cf:** domain-specific relays and exclusions. Modify via `setup.sh relay add-domain` and `setup.sh relay exclude-domain`. (Docs: [Relay-Hosts Senders][docs-relayhosts-senderhost])
- **postfix-sasl-password.cf:** listing of relayed domains with their respective `<username>:<password>`. Modify via `setup.sh relay add-auth <domain> <username> [<password>]`. (Docs: [Relay-Hosts Auth][docs::relay-hosts::advanced])
- **postfix-relaymap.cf:** domain-specific relays and exclusions. Modify via `setup.sh relay add-domain` and `setup.sh relay exclude-domain`. (Docs: [Relay-Hosts Senders][docs::relay-hosts::advanced])
- **postfix-regexp.cf:** Regular expression alias file. (Docs: [Aliases][docs-aliases-regex])
- **postfix-regexp-send-only.cf:** Regular expression alias file for sending only. (Docs: [Send-Only Aliases][docs-aliases-send-only])
- **ldap-users.cf:** Configuration for the virtual user mapping `virtual_mailbox_maps`. See the [`setup-stack.sh`][github-commit-setup-stack.sh-L411] script.
@ -98,6 +95,9 @@ This is a list of all configuration files and directories which are optional, au
- **user-patches.sh:** this file will be run after all configuration files are set up, but before the postfix, amavis and other daemons are started. (Docs: [FAQ - How to adjust settings with the `user-patches.sh` script][docs-faq-userpatches])
- **rspamd/custom-commands.conf:** list of simple commands to adjust Rspamd modules in an easy way (Docs: [Rspamd][docs-rspamd-commands])
[docker-docs::volumes]: https://docs.docker.com/storage/volumes/
[docker-docs::volumes::bind-mount]: https://docs.docker.com/storage/bind-mounts/
[docs-accounts-quota]: ../../config/user-management.md#quotas
[docs-aliases-regex]: ../../config/user-management.md#configuring-regexp-aliases
[docs-aliases-send-only]: ../../config/user-management.md#send-only-aliases
@ -107,8 +107,7 @@ This is a list of all configuration files and directories which are optional, au
[docs-faq-userpatches]: ../../faq.md#how-to-adjust-settings-with-the-user-patchessh-script
[docs-override-postfix]: ./override-defaults/postfix.md
[docs-override-dovecot]: ./override-defaults/dovecot.md
[docs-relayhosts-senderauth]: ./mail-forwarding/relay-hosts.md#sender-dependent-authentication
[docs-relayhosts-senderhost]: ./mail-forwarding/relay-hosts.md#sender-dependent-relay-host
[docs::relay-hosts::advanced]: ./mail-forwarding/relay-hosts.md#advanced-configuration
[docs-sieve]: ./mail-sieve.md
[docs-setupsh]: ../../config/setup.sh.md
[docs-ssl]: ../../config/security/ssl.md

6
docs/content/config/advanced/podman.md
View file

@ -107,7 +107,7 @@ The `PERMIT_DOCKER` variable in the `mailserver.env` file allows to specify trus
#### Use the slip4netns network driver
The second workaround is slightly more complicated because the `compose.yaml` has to be modified.
As shown in the [fail2ban section](../security/fail2ban.md#podman-with-slirp4netns-port-driver) the `slirp4netns` network driver has to be enabled.
As shown in the [fail2ban section][docs::fail2ban::rootless] the `slirp4netns` network driver has to be enabled.
This network driver enables podman to correctly resolve IP addresses but it is not compatible with
user defined networks which might be a problem depending on your setup.
@ -150,7 +150,7 @@ Remember to run this command as root user.
### Port Forwarding
When it comes to forwarding ports using `firewalld`, see <https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/securing_networks/using-and-configuring-firewalld_securing-networks#port-forwarding_using-and-configuring-firewalld> for more information.
When it comes to forwarding ports using `firewalld`, see [these port forwarding docs][firewalld-port-forwarding] for more information.
```bash
firewall-cmd --permanent --add-forward-port=port=<25|143|465|587|993>:proto=<tcp>:toport=<10025|10143|10465|10587|10993>
@ -171,5 +171,7 @@ firewall-cmd --reload
Just map all the privilege port with non-privilege port you set in compose.yaml before as root user.
[docs::fail2ban::rootless]: ../security/fail2ban.md#rootless-container
[rootless::podman]: https://github.com/containers/podman/blob/v3.4.1/docs/source/markdown/podman-run.1.md#--networkmode---net
[rootless::podman::interface]: https://github.com/containers/podman/blob/v3.4.1/libpod/networking_slirp4netns.go#L264
[firewalld-port-forwarding]: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/securing_networks/using-and-configuring-firewalld_securing-networks#port-forwarding_using-and-configuring-firewalld