From 5286f09683bfabc19feba6a981baf6600bad6559 Mon Sep 17 00:00:00 2001 From: polarathene <5098581+polarathene@users.noreply.github.com> Date: Thu, 18 Jul 2024 15:15:02 +1200 Subject: [PATCH] docs: Another revision pass File based provisioner docs: - Sections indent with info admonitions. - Accounts section expanded with config format and example. - Quotas section expanded and shifted to bottom (alphabetical sort). - Split into `setup` CLI and config reference groups. Overview page: - Sections indent with info admonitions. - Revised content. --- .../config/account-management/overview.md | 32 ++++-- .../account-management/provisioner/file.md | 108 +++++++++++++++--- 2 files changed, 112 insertions(+), 28 deletions(-) diff --git a/docs/content/config/account-management/overview.md b/docs/content/config/account-management/overview.md index 1291cfe1..6b9963b1 100644 --- a/docs/content/config/account-management/overview.md +++ b/docs/content/config/account-management/overview.md @@ -20,12 +20,16 @@ This page provides a technical reference for account management in DMS. ## Accounts -To receive or send mail, you'll need to provision user accounts into DMS (_as each provisioner page demonstrates_). +!!! info -A DMS account represents a user with their login username + password, along with related features like aliases and quotas. + To receive or send mail, you'll need to provision user accounts into DMS (_as each provisioner page documents_). -- 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. Aliases allow for sharing delivery to a common mailbox. + --- + + 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. ??? info "Primary email address" @@ -59,10 +63,12 @@ A DMS account represents a user with their login username + password, along with ### Aliases -An alias is typically a full email address that will either be: +!!! info -- Delivered to the mailbox of a DMS account. -- Redirected to one or more other email addresses (_these may also be forwarded to external addresses not managed by DMS_). + 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`. ??? abstract "Technical Details (_Local vs Virtual aliases_)" @@ -178,12 +184,14 @@ An alias is typically a full email address that will either be: ## Technical Overview -This section provides insight for understanding how Postfix and Dovecot services are involved. It is intended as a reference for maintainers and contributors. +!!! info -- Postfix handles when mail is delivered (inbound) to DMS, or sent (outbound) from DMS. -- Dovecot manages mailbox storage for mail delivered to the DMS accounts of your users. + This section provides insight for understanding how Postfix and Dovecot services are involved. It is intended as a reference for maintainers and contributors. -??? abstract "Technical Details - Postfix" + - **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. + +??? abstract "Technical Details - Postfix (Inbound vs Outbound)" Postfix needs to know how to handle inbound and outbound mail by asking these queries: @@ -197,7 +205,7 @@ This section provides insight for understanding how Postfix and Dovecot services - When `SPOOF_PROTECTION=1`, how should DMS restrict the sender address? (_eg: Users may only send mail from their associated mailbox address_) -??? abstract "Technical Details - Dovecot" +??? abstract "Technical Details - Dovecot (Authentication)" Dovecot additionally handles authenticating user accounts for sending and retrieving mail: diff --git a/docs/content/config/account-management/provisioner/file.md b/docs/content/config/account-management/provisioner/file.md index 39faa192..48d0c8f6 100644 --- a/docs/content/config/account-management/provisioner/file.md +++ b/docs/content/config/account-management/provisioner/file.md @@ -2,9 +2,9 @@ title: 'Account Management | Provisioner (File)' --- -## Accounts +# Provisioner - File -**Config file:** `docker-data/dms/config/postfix-accounts.cf` +## Management via the `setup` CLI The best way to manage DMS accounts and related config files is through our `setup` CLI provided within the container. @@ -21,31 +21,80 @@ The best way to manage DMS accounts and related config files is through our `set docker run --rm -itd --name dms --hostname mail.example.com mailserver/docker-mailserver docker exec -it dms bash - # Create some accounts: - setup email add john.doe@example.com bad-password - setup email add jane.doe@example.com bad-password + # Create an account: + setup email add hello@example.com your-password-here # Create an alias: - setup alias add your-alias-here@example.com john.doe@example.com + setup alias add your-alias-here@example.com hello@example.com + + # Limit the mailbox capacity to 10 MiB: + setup quota set hello@example.com 10M ``` + ??? tip "Secure password input" + + When you don't provide a password to the command, you will be prompted for one. This avoids the password being captured in your shell history. + + ```bash + # As you input your password it will not update. + # Press the ENTER key to apply the hidden password input. + $ setup email add hello@example.com + Enter Password: + Confirm Password: + ``` + +!!! note "Account removal via `setup email del`" + + When you remove a DMS account with this command, it will also remove any associated aliases and quota. + + The command will also prompt for deleting the account mailbox from disk, or can be forced with the `-y` flag. + +## Config Reference + +### Accounts + !!! info + **Config file:** `docker-data/dms/config/postfix-accounts.cf` + + --- + + The config format is line-based with two fields separated by the delimiter `|`: + + - **User:** The primary email address for the account mailbox to use. + - **Password:** A SHA512-CRYPT hash of the account password (_in this example it is `secret`_). + + ??? tip "Password hash without the `setup email add` command" + + A compatible password hash can be generated with: + + ```bash + doveadm pw -s SHA512-CRYPT -u hello@example.com -p secret + ``` + +!!! example "`postfix-accounts.cf` config file" + + In this example DMS manages mail for the domain `example.com`: + + ```cf title="postfix-accounts.cf" + hello@example.com|{SHA512-CRYPT}$6$W4rxRQwI6HNMt9n3$riCi5/OqUxnU8eZsOlZwoCnrNgu1gBGPkJc.ER.LhJCu7sOg9i1kBrRIistlBIp938GdBgMlYuoXYUU5A4Qiv0 + ``` + +!!! note + Account creation will normalize the provided email address to lowercase, as DMS does not support multiple case-sensitive address variants. The email address chosen will also represent the _login username_ credential for mail clients to authenticate with. -## Quotas +### Aliases -**Config file:** `docker-data/dms/config/dovecot-quotas.cf` +!!! info -When the mailbox is deleted, the quota directive is deleted as well. + **Config file:** `docker-data/dms/config/postfix-virtual.cf` -## Aliases + --- -**Config file:** `docker-data/dms/config/postfix-virtual.cf` - -Each line in the config file is a value pair (**alias** --> **target address**), with white-space as a delimiter between the two values. + The config format is line-based with key value pairs (**alias** --> **target address**), with white-space as a delimiter. !!! example "`postfix-virtual.cf` config file" @@ -88,11 +137,17 @@ Each line in the config file is a value pair (**alias** --> **target address**), - You may experience issues when our feature integrations don't expect more than one target per alias. - These concerns also apply to the usage of nested aliases (_where the recipient target provided is to an alias instead of a real address_). An example is the [incompatibility with `setup alias add`][gh-issue::bugs::alias-nested]. -### Configuring RegEx aliases +#### Configuring RegEx aliases -**Config file:** `docker-data/dms/config/postfix-regexp.cf` +!!! info -This config file is similar to the above `postfix-virtual.cf`, but the alias value instead is configured with a regex pattern. There is no `setup` CLI support for this feature, it is config only. + **Config file:** `docker-data/dms/config/postfix-regexp.cf` + + --- + + This config file is similar to the above `postfix-virtual.cf`, but the alias value is instead configured with a regex pattern. + + There is **no `setup` CLI support** for this feature, it is config only. !!! example "`postfix-regexp.cf` config file" @@ -110,6 +165,27 @@ This config file is similar to the above `postfix-virtual.cf`, but the alias val These files are both copied internally to `/etc/postfix/` and configured in `main.cf` for the `virtual_alias_maps` setting. As `postfix-virtual.cf` is declared first for that setting, it will be processed before using `postfix-regexp.cf` as a fallback. +### Quotas + +!!! info + + **Config file:** `docker-data/dms/config/dovecot-quotas.cf` + + ---- + + The config format is line-based with two fields separated by the delimiter `:`: + + - **Dovecot UserDB account:** The user DMS account. It should have a matching field in `postfix-accounts.cf`. + - **Quota limit:** Expressed in bytes (_binary unit suffix is supported: `M` => `MiB`, `G` => `GiB`_). + +!!! example "`dovecot-quotas.cf` config file" + + For the account with the mailbox address of `hello@example.com`, it may not exceed 5 GiB in storage: + + ```cf-extra title="dovecot-quotas.cf" + hello@example.com:5G + ``` + [gh-issue::feature-request::allow-account-alias-overlap]: https://github.com/docker-mailserver/docker-mailserver/issues/3528 [gh-issue::bugs::account-alias-overlap-problem]: https://github.com/docker-mailserver/docker-mailserver/issues/3350#issuecomment-1550528898 [gh-issue::bugs::account-alias-overlap]: https://github.com/docker-mailserver/docker-mailserver/issues/3022#issuecomment-1807816689