diff --git a/docs/content/config/account-management/overview.md b/docs/content/config/account-management/overview.md index fd4ab469..190a0e73 100644 --- a/docs/content/config/account-management/overview.md +++ b/docs/content/config/account-management/overview.md @@ -4,8 +4,6 @@ **TODO:** `ACCOUNT_PROVISIONER` and supplementary pages referenced here. -An email address should conform to the [expected syntax](https://en.wikipedia.org/wiki/Email_address#Syntax). - !!! info In the DMS docs, there may be references to the sub-components of an address (`local-part@domain-part`). @@ -21,9 +19,13 @@ The email address assigned to an account is relevant for: - `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. -!!! warning +??? warning "Email address considerations" - Ensure that you avoid configuring email addresses with the [sub-address tag delimiter](#sub-addressing), otherwise opt-out of the sub-addressing feature. + An email address should conform to the standard [permitted charset and format](https://stackoverflow.com/questions/2049502/what-characters-are-allowed-in-an-email-address/2049510#2049510). + + 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, or disable / opt-out of the feature. + + - [Sub-addressing](#sub-addressing) is enabled by default with the _tag delimiter_ `+`. This can be configured, or be unset to opt-out. ### Aliases @@ -42,9 +44,9 @@ Wildcard and need to alias each real account.. (no longer supported?) !!! info - [Subaddressing][wikipedia::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. + [Subaddressing][wikipedia::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: `+@` + - A subaddress has a tag delimiter (_default: `+`_), followed by the tag: `+@` - 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. @@ -87,7 +89,6 @@ Wildcard and need to alias each real account.. (no longer supported?) - Applying the Postfix `main.cf` setting: [`recipient_delimiter = +`][postfix-docs::recipient-delimiter] - Dovecot has the equivalent setting set as `+` by default: [`recipient_delimiter = +`][dovecot-docs::config::recipient-delimiter] - ### Quotas - `imap-quota` is enabled and allow clients to query their mailbox usage. diff --git a/docs/content/config/account-management/provisioner/file.md b/docs/content/config/account-management/provisioner/file.md index 68f6d84d..da562bfe 100644 --- a/docs/content/config/account-management/provisioner/file.md +++ b/docs/content/config/account-management/provisioner/file.md @@ -1,10 +1,10 @@ --- -title: 'Account Management | File Provisioner' +title: 'Account Management | Provisioner (File)' --- ## Accounts -**Config file:** `docker-data/dms/config/postfix-accounts.cf`. +**Config file:** `docker-data/dms/config/postfix-accounts.cf` The best way to manage DMS accounts and related config files is through our `setup` CLI provided within the container. @@ -16,32 +16,32 @@ The best way to manage DMS accounts and related config files is through our `set - Add an alias: `setup alias add ` - Learn more about the available subcommands via: `setup help` - ```console - # Spin up a basic DMS instance and then shells into the container to provision accounts: - $ docker run --rm -itd --name dms --hostname mail.example.com ghcr.io/docker-mailserver/docker-mailserver:latest - $ docker exec -it dms bash + ```bash + # Starts a basic DMS instance and then shells into the container to use the `setup` CLI: + docker run --rm -itd --name dms --hostname mail.example.com ghcr.io/docker-mailserver/docker-mailserver:latest + 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 + setup email add john.doe@example.com bad-password + setup email add jane.doe@example.com bad-password # Create an alias: - $ setup alias add your-alias-here@example.com john.doe@example.com + setup alias add your-alias-here@example.com john.doe@example.com ``` !!! info - The email address chosen will also represent the login username credential for mail clients. + Account creation will normalize the provided email address to lowercase, as DMS does not support multiple case-sensitive address variants. - Account creation will also normalize the provided address to lowercase, as DMS does not support multiple address variants relying on case-sensitivity. + The email address chosen will also represent the _login username_ credential for mail clients to authenticate with. -### Quotas +## Quotas **Config file:** `docker-data/dms/config/dovecot-quotas.cf` When the mailbox is deleted, the quota directive is deleted as well. -### Aliases +## Aliases **Config file:** `docker-data/dms/config/postfix-virtual.cf` diff --git a/docs/content/config/account-management/provisioner/ldap.md b/docs/content/config/account-management/provisioner/ldap.md index 23e8a551..607ee3d5 100644 --- a/docs/content/config/account-management/provisioner/ldap.md +++ b/docs/content/config/account-management/provisioner/ldap.md @@ -1,5 +1,5 @@ --- -title: 'Account Management | LDAP Provisioner' +title: 'Account Management | Provisioner (LDAP)' --- ## Introduction diff --git a/docs/content/config/account-management/supplementary/oauth2.md b/docs/content/config/account-management/supplementary/oauth2.md index a9ce9e62..c4f693db 100644 --- a/docs/content/config/account-management/supplementary/oauth2.md +++ b/docs/content/config/account-management/supplementary/oauth2.md @@ -6,7 +6,7 @@ title: 'Account Management | OAuth2 Support' !!! 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). + 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. @@ -15,13 +15,13 @@ title: 'Account Management | OAuth2 Support' 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) +## Example (Authentik with Roundcube) -This example assumes you have: +This example assumes you have already set up: -- 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)) +- A working DMS server +- An Authentik server ([documentation](https://goauthentik.io/docs/installation/)) +- A Roundcube server (either [docker](https://hub.docker.com/r/roundcube/roundcubemail/) or [bare metal](https://github.com/roundcube/roundcubemail/wiki/Installation)) !!! example "Setup Instructions" diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b99f5593..0c0c8e59 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -144,8 +144,8 @@ nav: - 'File Based': config/account-management/provisioner/file.md - 'LDAP Service': config/account-management/provisioner/ldap.md - 'Supplementary': - - 'OAuth2 Authentication': config/account-management/supplementary/oauth2.md - 'Dovecot Master Accounts': config/account-management/supplementary/master-accounts.md + - 'OAuth2 Authentication': config/account-management/supplementary/oauth2.md - 'Best Practices': - 'Auto-discovery': config/best-practices/autodiscover.md - 'DKIM, DMARC & SPF': config/best-practices/dkim_dmarc_spf.md