Archive-Team
/
docker-mailserver
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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.
This commit is contained in:
polarathene 2024-07-18 15:15:02 +12:00
parent d88d637475
commit 5286f09683
2 changed files with 112 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/content/config/account-management/overview.md
View File

@ -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:

108
docs/content/config/account-management/provisioner/file.md
View File

@ -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