-
-
- Logging in
+ Technical Overview
@@ -2173,7 +2392,7 @@
-
+
@@ -2182,24 +2401,235 @@
-
+
- Dovecot Master Accounts
-
-
-A dovecot master account is able to login as any configured user. This is useful for administrative tasks like hot backups.
-
-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.
-
-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>
+
+This page provides a technical reference for account management in DMS.
+
+
Account provisioners and alternative authentication support
+
Each ACCOUNT_PROVISIONER has a separate page for configuration guidance and caveats:
+
+
Authentication from the provisioner can be supplemented with additional methods:
+
+
+
For custom authentication requirements, you could implement this with Lua.
+
+
Info
+
To receive or send mail, you'll need to provision user accounts into DMS (as each provisioner page documents).
+
+
A DMS account represents a user with their login username + password, and optional config like aliases and quota.
+
+- Sending mail from different addresses does not require aliases or separate accounts.
+- Each account is configured with a primary email address that a mailbox is associated to.
+
+
+Primary email address
+The email address associated to an account creates a mailbox. This address is relevant:
+
+- When DMS receives mail for that address as the recipient (or an alias that resolves to it), to identify which mailbox to deliver into.
+- With mail submission:
+SPOOF_PROTECTION=1 restricts the sender address to the DMS account email address (unless additional sender addresses have been permitted via supported config).SPOOF_PROTECTION=0 allows DMS accounts to use any sender address (only a single DMS account is necessary to send mail with different sender addresses).
+
+
+
+For more details, see the Technical Overview section.
+
+
+Support for multiple mail domains
+No extra configuration in DMS is required after provisioning an account with an email address.
+
+- The DNS records for a domain should direct mail to DMS and allow DMS to send mail on behalf of that domain.
+- DMS does not need TLS certificates for your mail domains, only for the DMS FQDN (the
hostname setting).
+
+
+
+Choosing a compatible email address
+An email address should conform to the standard permitted charset and format (local-part@domain-part).
+
+DMS has features that need to reserve special characters to work correctly. Ensure those characters are not present in email addresses you configure for DMS, otherwise disable / opt-out of the feature.
+
+- Sub-addressing is enabled by default with
+ as the tag delimiter. The tag can be changed, feature opt-out when the tag is explicitly unset.
+
+
+
+
+
Info
+
Aliases allow receiving mail:
+
+- As an alternative delivery address for a DMS account mailbox.
+- To redirect / forward to an external address outside of DMS like
@gmail.com.
+
+
+Technical Details (Local vs Virtual aliases)
+Aliases are managed through Postfix which supports local and virtual aliases:
+
+- Local aliases are for mail routed to the
local delivery agent (see associated alias config format)
+- You rarely need to configure this. It is used internally for system unix accounts belonging to the services running in DMS (including
root).
+postmaster may be a local alias to root, and root to a virtual alias or real email address.- Any mail sent through the
local delivery agent will not be delivered to an inbox managed by Dovecot (unless you have configured a local alias to redirect mail to a valid address or alias).
+- The domain-part of an these aliases belongs to your DMS FQDN (
hostname: mail.example.com, thus user@mail.example.com). Technically there is no domain-part at this point, that context is used when routing delivery, the local delivery agent only knows of the local-part (an alias or unix account).
+
+
+- Virtual aliases are for mail routed to the
virtual delivery agent (see associated alias config format)
+- When alias support in DMS is discussed without the context of being a local or virtual alias, it's likely the virtual kind (but could also be agnostic).
+- The domain-part of an these aliases belongs to a mail domain managed by DMS (like
user@example.com).
+
+
+
+
+
Verify alias resolves correctly
+
You can run postmap -q <alias> <table> in the container to verify an alias resolves to the expected target. If the target is also an alias, the command will not expand that alias to resolve the actual recipient(s).
+
For the FILE provisioner, an example would be: postmap -q alias1@example.com /etc/postfix/virtual. For the LDAP provisioner you'd need to adjust the table path.
+
+
Side effect - Dovecot Quotas (ENABLE_QUOTAS=1)
+
As a side effect of the alias workaround for the FILE provisioner with this feature, aliases can be used for account login. This is not intentional.
+
+
+
+
Info
+
Enables mail clients with the capability to query a mailbox for disk-space used and capacity limit.
+
+
+How are quotas useful?
+Without quota limits for disk storage, a mailbox could fill up the available storage which would cause delivery failures to all mailboxes.
+Quotas help by preventing that abuse, so that only a mailbox exceeding the assigned quota experiences a delivery failure instead of negatively impacting others (provided disk space is available).
+
+
+Technical Details
+The Dovecot Quotas feature is configured by enabling the Dovecot imap-quota plugin and using the count quota backend.
+
+Dovecot workaround for Postfix aliases
+When mail is delivered to DMS, Postfix will query Dovecot with the recipient(s) to verify quota has not been exceeded.
+This allows early rejection of mail arriving to DMS, preventing a spammer from taking advantage of a backscatter source if the mail was accepted by Postfix, only to later be rejected by Dovecot for storage when the quota limit was already reached.
+However, Postfix does not resolve aliases until after the incoming mail is accepted.
+
+- Postfix queries Dovecot (a
check_policy_service restriction tied to the Dovecot quota-status service) with the recipient (the alias).
+dovecot: auth: passwd-file(alias@example.com): unknown user is logged, Postfix is then informed that the recipient mailbox is not full even if it actually was (since no such user exists in the Dovecot UserDB).- However, when the real mailbox address that the alias would later resolve into does have a quota that exceeded the configured limit, Dovecot will refuse the mail delivery from Postfix which introduces a backscatter source for spammers.
+
+As a workaround to this problem with the ENABLE_QUOTAS=1 feature, DMS will add aliases as fake users into Dovecot UserDB (that are configured with the same data as the real address the alias would resolve to, thus sharing the same mailbox location and quota limit). This allows Postfix to properly be aware of an aliased mailbox having exceeded the allowed quota.
+NOTE: This workaround only supports aliases to a single target recipient of a real account address / mailbox.
+
+- Additionally, aliases that resolve to another alias or to an external address would both fail the UserDB lookup, unable to determine if enough storage is available.
+- A proper fix would implement a Postfix policy service that could correctly resolve aliases to valid entries in the Dovecot UserDB, querying the
quota-status service and returning that response to Postfix.
+
+
+
+
+
Info
+
Subaddressing (aka Plus Addressing or Address Tags) is a feature that allows you to receive mail to an address which includes a tag appended to the local-part of a valid account address.
+
+- A subaddress has a tag delimiter (default:
+), followed by the tag: <local-part>+<tag>@<domain-part>
+- The subaddress
user+github@example.com would deliver mail to the same mailbox as user@example.com.
+- Tags are dynamic. Anything between the
+ and @ is understood as the tag, no additional configuration required.
+- Only the first occurence of the tag delimiter is recognized. Any additional occurences become part of the tag value itself.
+
+
+When is subaddressing useful?
+A common use-case is to use a unique tag for each service you register your email address with.
+
+- Routing delivery to different folders in your mailbox based on the tag (via a Sieve filter).
+- Data leaks or bulk sales of email addresses.
+- If spam / phishing mail you receive has not removed the tag, you will have better insight into where your address was compromised from.
+- When the expected tag is missing, this additionally helps identify bad actors. Especially when mail delivery is routed to subfolders by tag.
+
+
+- For more use-cases, view the end of this article.
+
+
+
+Changing the tag delimiter
+Add recipient_delimiter = + to these config override files (replacing + with your preferred delimiter):
+
+- Postfix:
docker-data/dms/config/postfix-main.cf
+- Dovecot:
docker-data/dms/config/dovecot.cf
+
+
+
+Opt-out of subaddressing
+Follow the advice to change the tag delimiter, but instead set an empty value (recipient_delimiter =).
+
+
+Only for receiving, not sending
+Do not attempt to send mail from these tagged addresses, they are not equivalent to aliases.
+This feature is only intended to be used when a mail client sends to a DMS managed recipient address. While DMS does not restrict the sender address you choose to send mail from (provided SPOOF_PROTECTION has not been enabled), it is often forbidden by mail services.
+
+
+Technical Details
+The configured tag delimiter (+) allows both Postfix and Dovecot to recognize subaddresses. Without this feature configured, the subaddresses would be considered as separate mail accounts rather than routed to a common account address.
+
+Internally DMS has the tag delimiter configured by:
+
+
+
+
+
Info
+
This section provides insight for understanding how Postfix and Dovecot services are involved. It is intended as a reference for maintainers and contributors.
+
+- Postfix - Handles when mail is delivered (inbound) to DMS, or sent (outbound) from DMS.
+- Dovecot - Manages access and storage for mail delivered to the DMS account mailboxes of your users.
+
+
+Technical Details - Postfix (Inbound vs Outbound)
+Postfix needs to know how to handle inbound and outbound mail by asking these queries:
+
+
+
+
+- What mail domains is DMS responsible for handling? (for accepting mail delivered)
+- What are valid mail addresses for those mail domains? (reject delivery for users that don't exist)
+- Are there any aliases to redirect mail to 1 or more users, or forward to externally?
+
+
+
+
+- When
SPOOF_PROTECTION=1, how should DMS restrict the sender address? (eg: Users may only send mail from their associated mailbox address)
+
+
+
+
+
+Technical Details - Dovecot (Authentication)
+Dovecot additionally handles authenticating user accounts for sending and retrieving mail:
+
+- Over the ports for IMAP and POP3 connections (110, 143, 993, 995).
+- As the default configured SASL provider, which Postfix delegates user authentication through (for the submission(s) ports 465 & 587). Saslauthd can be configured as an alternative SASL provider.
+
+Dovecot splits all authentication lookups into two categories:
+
+- A PassDB lookup most importantly authenticates the user. It may also provide any other necessary pre-login information.
+- A UserDB lookup retrieves post-login information specific to a user.
+
+
@@ -2207,9 +2637,6 @@
-
-
-
diff --git a/edge/config/user-management/index.html b/edge/config/account-management/provisioner/file/index.html
similarity index 65%
rename from edge/config/user-management/index.html
rename to edge/config/account-management/provisioner/file/index.html
index a317898a..52ed7b0d 100644
--- a/edge/config/user-management/index.html
+++ b/edge/config/account-management/provisioner/file/index.html
@@ -12,28 +12,28 @@
-
+
-
+
-
+
-
+
- User Management - Docker Mailserver
+ Account Management | Provisioner (File) - Docker Mailserver
-
+
-
+
@@ -52,9 +52,9 @@
-
+
-
+
@@ -80,7 +80,7 @@