docs: Alias section refactor
Extensively covers known issues and technical details that have been discussed often enough. The improvements should benefit both users and maintainers.
This commit is contained in:
polarathene
parent
9edf90f86d
commit
91c4b1794b
|
|
@ -29,16 +29,33 @@ The email address assigned to an account is relevant for:
|
|||
|
||||
### Aliases
|
||||
|
||||
You may read [Postfix's documentation on virtual aliases][postfix-docs::virtual-alias] first.
|
||||
An alias is typically a full email address that will either be:
|
||||
|
||||
An alias is a full email address that will either be:
|
||||
- Delivered to an existing local DMS account address.
|
||||
- Redirected to one or more other email addresses (_these may also be forwarded to external addresses not managed by DMS_).
|
||||
|
||||
- Delivered to an existing account
|
||||
- Redirected to one or more other email addresses
|
||||
??? abstract "Technical Details (_Local vs Virtual aliases_)"
|
||||
|
||||
Known issues
|
||||
Alias and Account names cannot overlap
|
||||
Wildcard and need to alias each real account.. (no longer supported?)
|
||||
Aliases are managed through Postfix which supports _local_ and _virtual_ aliases:
|
||||
|
||||
- **Local aliases** are for mail routed to the [`local` delivery agent][postfix::delivery-agent::local] (see [associated alias config format][postfix::config-table::local-alias])
|
||||
- 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**][postfix-docs::virtual-alias] are for mail routed to the [`virtual` delivery agent][postfix::delivery-agent::virtual] (see [associated alias config format][postfix::config-table::virtual-alias])
|
||||
- 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`_).
|
||||
|
||||
!!! tip "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 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.
|
||||
|
||||
!!! info "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.
|
||||
|
||||
### Sub-addressing
|
||||
|
||||
|
|
@ -178,3 +195,8 @@ Wildcard and need to alias each real account.. (no longer supported?)
|
|||
[postfix-docs::virtual-alias]: http://www.postfix.org/VIRTUAL_README.html#virtual_alias
|
||||
[postfix-docs::recipient-delimiter]: http://www.postfix.org/postconf.5.html#recipient_delimiter
|
||||
[dovecot-docs::config::recipient-delimiter]: https://doc.dovecot.org/settings/core/#core_setting-recipient_delimiter
|
||||
|
||||
[postfix::delivery-agent::local]: https://www.postfix.org/local.8.html
|
||||
[postfix::delivery-agent::virtual]: https://www.postfix.org/virtual.8.html
|
||||
[postfix::config-table::local-alias]: https://www.postfix.org/aliases.5.html
|
||||
[postfix::config-table::virtual-alias]: https://www.postfix.org/virtual.5.html
|
||||
|
|
|
|||
|
|
@ -45,26 +45,73 @@ When the mailbox is deleted, the quota directive is deleted as well.
|
|||
|
||||
**Config file:** `docker-data/dms/config/postfix-virtual.cf`
|
||||
|
||||
Alias and target are space separated. An example on a server with `example.com` as its domain:
|
||||
Each line in the config file is a value pair (**alias** --> **target address**), with white-space as a delimiter between the two values.
|
||||
|
||||
```cf
|
||||
# Alias delivered to an existing account
|
||||
alias1@example.com user1@example.com
|
||||
!!! example "`postfix-virtual.cf` config file"
|
||||
|
||||
# Alias forwarded to an external email address
|
||||
alias2@example.com external-account@gmail.com
|
||||
```
|
||||
With DMS configured to manage mail for `example.com`:
|
||||
|
||||
Multiple recipients can be added to one alias, but is not officially supported.
|
||||
https://github.com/orgs/docker-mailserver/discussions/3805#discussioncomment-8215417
|
||||
```cf-extra title="postfix-virtual.cf"
|
||||
# Alias delivers to an existing account:
|
||||
alias1@example.com user1@example.com
|
||||
|
||||
### Configuring RegExp Aliases
|
||||
# Alias forwards to an external email address:
|
||||
alias2@example.com external-account@gmail.com
|
||||
```
|
||||
|
||||
- Additional regexp aliases can be configured by placing them into `docker-data/dms/config/postfix-regexp.cf`.
|
||||
- The regexp aliases get evaluated after the virtual aliases (container path: `/tmp/docker-mailserver/postfix-virtual.cf`).
|
||||
??? warning "Known Issues"
|
||||
|
||||
For example, the following `docker-data/dms/config/postfix-regexp.cf` causes all email sent to "test" users to be delivered to `qa@example.com` instead:
|
||||
**`setup` CLI prevents an alias and account sharing an address:**
|
||||
|
||||
```cf
|
||||
/^test[0-9][0-9]*@example.com/ qa@example.com
|
||||
```
|
||||
You cannot presently add a new account (`setup email add`) or alias `setup alias add` with an address when that already exists as an alias or account.
|
||||
|
||||
This [restriction was enforced][gh-issue::bugs::account-alias-overlap] due to problems it could cause, although there are [use-cases where you may legitimately require this functionality][gh-issue::feature-request::allow-account-alias-overlap].
|
||||
|
||||
For now you must manually edit the `postfix-virtual.cf` file as a workaround. There are no run-time checks outside of the `setup` CLI related to this restriction.
|
||||
|
||||
---
|
||||
|
||||
**Wildcard catch-all support (`@example.com`):**
|
||||
|
||||
While this type of alias without a local-part is supported, you must keep in mind that aliases in Postfix have a higher precedence than a real address associated to a DMS account.
|
||||
|
||||
As a result, the wildcard is matched first and will direct mail for that entire domain to the alias target address. To work around this, [you will need an alias for each non-alias address of that domain][gh-issue::bugs::wildcard-catchall].
|
||||
|
||||
Additionally, Postfix will read the alias config and choose the alias value that matches the recipient address first. Ensure your more specific aliases for the domain are declared above the wildcard alias in the config file.
|
||||
|
||||
---
|
||||
|
||||
**Aliasing to another alias or multiple recipients:**
|
||||
|
||||
[While aliasing to multiple recipients is possible][gh-discussions::no-support::alias-multiple-targets], DMS does not officially support that.
|
||||
|
||||
- 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
|
||||
|
||||
**Config file:** `docker-data/dms/config/postfix-regexp.cf`
|
||||
|
||||
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.
|
||||
|
||||
!!! example "`postfix-regexp.cf` config file"
|
||||
|
||||
Deliver all mail for `test` users to `qa@example.com` instead:
|
||||
|
||||
```cf-extra title="postfix-regexp.cf"
|
||||
# Remember to escape regex tokens like `.` => `\.`, otherwise
|
||||
# your alias pattern may be more permissive than you intended:
|
||||
/^test[0-9][0-9]*@example\.com/ qa@example.com
|
||||
```
|
||||
|
||||
??? abstract "Technical Details"
|
||||
|
||||
`postfix-virtual.cf` has precedence, `postfix-regexp.cf` will only be checked if no alias match was found in `postfix-virtual.cf`.
|
||||
|
||||
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.
|
||||
|
||||
[gh-issue::feature-request::allow-account-alias-overlap]: https://github.com/docker-mailserver/docker-mailserver/issues/3528
|
||||
[gh-issue::bugs::account-alias-overlap]: https://github.com/docker-mailserver/docker-mailserver/issues/3022#issuecomment-1807816689
|
||||
[gh-issue::bugs::wildcard-catchall]: https://github.com/docker-mailserver/docker-mailserver/issues/3022#issuecomment-1610452561
|
||||
[gh-issue::bugs::alias-nested]: https://github.com/docker-mailserver/docker-mailserver/issues/3622#issuecomment-1794504849
|
||||
[gh-discussions::no-support::alias-multiple-targets]: https://github.com/orgs/docker-mailserver/discussions/3805#discussioncomment-8215417
|
||||
|
|
|
|||
Loading…
Reference in New Issue