github-com-docker-mailserver/docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2024-01-19 02:48:50 +00:00
Code Issues Projects Releases Wiki Activity

compress & improve user management docs (#3232)

Browse source 
The user management docs are now one page, because the division between
accounts and aliases is useless because there simply isn't enough
content to justify the split. I improved and updated the text a bit.
This commit is contained in:
Georg Lauterbach 2023-04-09 11:27:00 +02:00 committed by GitHub
parent adb38207ad
commit 2b7cab28f7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 100 additions and 105 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/content/config/advanced/optional-config.md
View file

@ -41,8 +41,8 @@ This is a list of all configuration files and directories which are optional or
- **user-patches.sh:** this file will be run after all configuration files are set up, but before the postfix, amavis and other daemons are started. (Docs: [FAQ - How to adjust settings with the `user-patches.sh` script][docs-faq-userpatches])
- **rspamd-commands:** list of simple commands to adjust Rspamd modules in an easy way (Docs: [Rspamd][docs-rspamd-commands])
[docs-accounts-quota]: ../../config/user-management/accounts.md#notes
[docs-aliases-regex]: ../../config/user-management/aliases.md#configuring-regexp-aliases
[docs-accounts-quota]: ../../config/user-management.md#quotas
[docs-aliases-regex]: ../../config/user-management.md#configuring-regexp-aliases
[docs-dkim]: ../../config/best-practices/dkim.md
[docs-fail2ban]: ../../config/security/fail2ban.md
[docs-faq-spamrules]: ../../faq.md#how-can-i-manage-my-custom-spamassassin-rules

4
docs/content/config/environment.md
View file

@ -213,7 +213,7 @@ Set the mailbox size limit for all users. If set to zero, the size will be unlim
- **1** => Dovecot quota is enabled
- 0 => Dovecot quota is disabled
See [mailbox quota][docs-accounts].
See [mailbox quota][docs-accounts-quota].
##### POSTFIX\_MESSAGE\_SIZE\_LIMIT
@ -831,4 +831,4 @@ you to replace both instead of just the envelope sender.
[docs-tls-letsencrypt]: ./security/ssl.md#lets-encrypt-recommended
[docs-tls-manual]: ./security/ssl.md#bring-your-own-certificates
[docs-tls-selfsigned]: ./security/ssl.md#self-signed-certificates
[docs-accounts]: ./user-management/accounts.md#notes
[docs-accounts-quota]: ./user-management.md#quotas

16
docs/content/config/security/understanding-the-ports.md
View file

@ -22,11 +22,11 @@ Prefer ports with Implicit [TLS][wikipedia-tls] ports, they're more secure than
??? warning "Beware of outdated advice on port 465"
There is a common misconception of this port due to it's history detailed by various communities and blogs articles on the topic (_including by popular mail relay services_).
Port 465 was [briefly assigned the role of SMTPS in 1997][wikipedia-smtps] as an secure alternative to Port 25 between MTA exchanges. Then RFC 2487 (`STARTTLS`) [while still in a draft status in late 1998 had IANA revoke the SMTPS assignment][history-465-revoked]. The [draft history was modified to exclude all mention of port 465 and SMTPS][history-465-politics].
In 2018 [RFC 8314][rfc-8314] was published which revives Port 465 as an Implicit TLS alternative to Port 587 for mail submission. It details very clearly that gaining adoption of 465 as the preferred port will take time. IANA reassigned [port 465 as the `submissions` service][iana-services-465]. Any unofficial usage as **SMTPS is legacy and has been for over two decades**.
Understand that port 587 is more broadly supported due to this history and that lots of software in that time has been built or configured with that port in mind. [`STARTTLS` is known to have various CVEs discovered even in recent years][starttls-vulnerabilities], do not be misled by any advice implying it should be preferred over implicit TLS. Trust in more official sources, such as the [config Postfix has][postfix-upstream-config-mastercf] which acknowledges the `submissions` port (465).
@ -82,7 +82,7 @@ Mail arriving at your server will be processed and stored in a mailbox, or sent
#### Outbound Traffic (On the Right)
Mail being sent from your server is either being relayed through another MTA (eg: SendGrid), or direct to an MTA responsible for an email address (eg: Gmail).
Mail being sent from your server is either being relayed through another MTA (eg: SendGrid), or direct to an MTA responsible for an email address (eg: Gmail).
- **Port 25:**
- As most MTA use port 25 to receive inbound mail, when no authenticated relay is involved this is the outbound port used.
@ -95,10 +95,10 @@ Mail being sent from your server is either being relayed through another MTA (eg
!!! tip
`docker-mailserver` can function as a relay too, but professional relay services have a trusted reputation (_which increases success of delivery_).
An MTA with low reputation can affect if mail is treated as junk, or even rejected.
!!! note
!!! note
At best, you can only ensure a secure connection between the MTA you directly connect to. The receiving MTA may relay that mail to another MTA (_and so forth_), each connection may not be enforcing TLS.
@ -119,7 +119,7 @@ Sometimes a reverse-proxy is involved, but is misconfigured or lacks support for
!!! warning
`STARTTLS` [continues to have vulnerabilities found][starttls-vulnerabilities] (Nov 2021 article), as per [RFC 8314 (Section 4.1)][rfc-8314-s41] you are encouraged to **prefer Implicit TLS where possible**.
Support for `STARTTLS` is not always implemented correctly, which can lead to leaking credentials (like a client sending too early) prior to a TLS connection being established. Third-parties such as some ISPs have also been known to intercept the `STARTTLS` exchange, modifying network traffic to prevent establishing a secure connection.
@ -146,7 +146,7 @@ Unlike with HTTP where a web browser client communicates directly with the serve
Other machines that facilitate a connection that generally aren't taken into account can exist between a client and server, such as those where your connection passes through your ISP provider are capable of compromising a `cleartext` connection through interception.
[docs-accounts]: ../user-management/accounts.md
[docs-accounts]: ../user-management.md#accounts
[docs-relays]: ../advanced/mail-forwarding/relay-hosts.md
[iana-services-465]: https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=465
[starttls-policy-list]: https://github.com/EFForg/starttls-everywhere#email-security-database-starttls-policy-list

86
docs/content/config/user-management.md Normal file
View file

@ -0,0 +1,86 @@
# User Management
## Accounts
Users (email accounts) are managed in `/tmp/docker-mailserver/postfix-accounts.cf`. The best way to manage accounts is to use the reliable `setup` command inside the container. Just run `docker exec <CONTAINER NAME> setup help` and have a look at the section about subcommands, specifically the `email` subcommand.
### Adding a new Account
#### Via `setup` inside the container
You can add an account by running `docker exec -ti <CONTAINER NAME> setup email add <NEW ADDRESS>`. This method is strongly preferred.
#### Manually
!!! warning
This method is discouraged!
Alternatively, you may directly add the full email address and its encrypted password, separated by a pipe. To generate a new mail account data, directly from your host, you could for example run the following:
```sh
docker run --rm -it \
--env MAIL_USER=user1@example.com \
--env MAIL_PASS=mypassword \
ghcr.io/docker-mailserver/docker-mailserver:latest \
/bin/bash -c \
'echo "${MAIL_USER}|$(doveadm pw -s SHA512-CRYPT -u ${MAIL_USER} -p ${MAIL_PASS})" >>docker-data/dms/config/postfix-accounts.cf'
```
You will then be asked for a password, and be given back the data for a new account entry, as text. To actually _add_ this new account, just copy all the output text in `docker-data/dms/config/postfix-accounts.cf` file of your running container.
The result could look like this:
```cf
user1@example.com|{SHA512-CRYPT}$6$2YpW1nYtPBs2yLYS$z.5PGH1OEzsHHNhl3gJrc3D.YMZkvKw/vp.r5WIiwya6z7P/CQ9GDEJDr2G2V0cAfjDFeAQPUoopsuWPXLk3u1
```
### Quotas
- `imap-quota` is enabled and allow clients to query their mailbox usage.
- When the mailbox is deleted, the quota directive is deleted as well.
- Dovecot quotas support LDAP, **but it's not implemented** (_PRs are welcome!_).
## Aliases
The best way to manage aliases is to use the reliable `setup` script inside the container. Just run `docker exec <CONTAINER NAME> setup help` and have a look at the section about subcommands, specifically the `alias`-subcommand.
### About
You may read [Postfix's documentation on virtual aliases][postfix-docs-alias] first. Aliases are managed in `/tmp/docker-mailserver/postfix-virtual.cf`. An alias is a full email address that will either be:
- delivered to an existing account registered in `/tmp/docker-mailserver/postfix-accounts.cf`
- redirected to one or more other email addresses
Alias and target are space separated. An example on a server with `example.com` as its domain:
```cf
# Alias delivered to an existing account
alias1@example.com user1@example.com
# Alias forwarded to an external email address
alias2@example.com external-account@gmail.com
```
### Configuring RegExp Aliases
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`). 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:
```cf
/^test[0-9][0-9]*@example.com/ qa@example.com
```
### Address Tags (Extension Delimiters) as an alternative to Aliases
Postfix supports so-called address tags, in the form of plus (+) tags - i.e. `address+tag@example.com` will end up at `address@example.com`. This is configured by default and the (configurable!) separator is set to `+`. For more info, see [Postfix's official documentation][postfix-docs-extension-delimiters].
!!! note
If you do decide to change the configurable separator, you must add the same line to *both* `docker-data/dms/config/postfix-main.cf` and `docker-data/dms/config/dovecot.cf`, because Dovecot is acting as the delivery agent. For example, to switch to `-`, add:
```cf
recipient_delimiter = -
```
[postfix-docs-alias]: http://www.postfix.org/VIRTUAL_README.html#virtual_alias
[postfix-docs-extension-delimiters]: http://www.postfix.org/postconf.5.html#recipient_delimiter

47
docs/content/config/user-management/accounts.md
View file

@ -1,47 +0,0 @@
---
title: 'User Management | Accounts'
hide:
- toc # Hide Table of Contents for this page
---
## Adding a New Account
Users (email accounts) are managed in `/tmp/docker-mailserver/postfix-accounts.cf`. **_The best way to manage accounts is to use the reliable [`setup.sh`][docs-setupsh] script_**. Or you may directly add the _full_ email address and its encrypted password, separated by a pipe:
```cf
user1@example.com|{SHA512-CRYPT}$6$2YpW1nYtPBs2yLYS$z.5PGH1OEzsHHNhl3gJrc3D.YMZkvKw/vp.r5WIiwya6z7P/CQ9GDEJDr2G2V0cAfjDFeAQPUoopsuWPXLk3u1
user2@not-example.com|{SHA512-CRYPT}$6$2YpW1nYtPBs2yLYS$z.5PGH1OEzsHHNhl3gJrc3D.YMZkvKw/vp.r5WIiwya6z7P/CQ9GDEJDr2G2V0cAfjDFeAQPUoopsuWPXLk3u1
```
In the example above, we've added 2 mail accounts for 2 different domains. Consequently, the mail-server will automatically be configured for multi-domains. Therefore, to generate a new mail account data, directly from your docker host, you could for example run the following:
```sh
docker run --rm \
-e MAIL_USER=user1@example.com \
-e MAIL_PASS=mypassword \
-it ghcr.io/docker-mailserver/docker-mailserver:latest \
/bin/sh -c 'echo "$MAIL_USER|$(doveadm pw -s SHA512-CRYPT -u $MAIL_USER -p $MAIL_PASS)"' >> docker-data/dms/config/postfix-accounts.cf
```
You will then be asked for a password, and be given back the data for a new account entry, as text. To actually _add_ this new account, just copy all the output text in `docker-data/dms/config/postfix-accounts.cf` file of your running container.
!!! note
`doveadm pw` command lets you choose between several encryption schemes for the password.
Use `doveadm pw -l` to get a list of the currently supported encryption schemes.
!!! note
Changes to the accounts list require a restart of the container, using `supervisord`. See [#552][github-issue-552].
---
### Notes
- `imap-quota` is enabled and allow clients to query their mailbox usage.
- When the mailbox is deleted, the quota directive is deleted as well.
- Dovecot quotas support LDAP, **but it's not implemented** (_PRs are welcome!_).
[docs-setupsh]: ../setup.sh.md
[github-issue-552]: https://github.com/docker-mailserver/docker-mailserver/issues/552

42
docs/content/config/user-management/aliases.md
View file

@ -1,42 +0,0 @@
---
title: 'User Management | Aliases'
---
Please read the [Postfix documentation on virtual aliases](http://www.postfix.org/VIRTUAL_README.html#virtual_alias) first.
You can use [`setup.sh`][docs-setupsh] instead of creating and editing files manually. Aliases are managed in `/tmp/docker-mailserver/postfix-virtual.cf`. An alias is a _full_ email address that will either be:
* delivered to an existing account registered in `/tmp/docker-mailserver/postfix-accounts.cf`
* redirected to one or more other email addresses
Alias and target are space separated. An example on a server with example.com as its domain:
```cf
# Alias delivered to an existing account
alias1@example.com user1@example.com
# Alias forwarded to an external email address
alias2@example.com external-account@gmail.com
```
## Configuring RegExp Aliases
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`). 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:
```cf
/^test[0-9][0-9]*@example.com/ qa@example.com
```
## Address Tags (Extension Delimiters) an Alternative to Aliases
Postfix supports so-called address tags, in the form of plus (+) tags - i.e. `address+tag@example.com` will end up at `address@example.com`. This is configured by default and the (configurable !) separator is set to `+`. For more info, see the [official documentation](http://www.postfix.org/postconf.5.html#recipient_delimiter).
!!! note
If you do decide to change the configurable separator, you must add the same line to *both* `docker-data/dms/config/postfix-main.cf` and `docker-data/dms/config/dovecot.cf`, because Dovecot is acting as the delivery agent. For example, to switch to `-`, add:
```cf
recipient_delimiter = -
```
[docs-setupsh]: ../setup.sh.md

2
docs/content/usage.md
View file

@ -152,7 +152,7 @@ You definitely want to setup TLS. Please refer to [our documentation about TLS][
You should add at least one [alias][docs-aliases], the [_postmaster alias_][docs-env-postmaster]. This is a common convention, but not strictly required.
[docs-aliases]: ./config/user-management/aliases.md
[docs-aliases]: ./config/user-management.md#aliases
[docs-env-postmaster]: ./config/environment.md#postmaster_address
```bash

4
docs/mkdocs.yml
View file

@ -114,9 +114,7 @@ nav:
- 'Usage': usage.md
- 'Configuration':
- 'Environment Variables': config/environment.md
- 'User Management':
- 'Accounts': config/user-management/accounts.md
- 'Aliases': config/user-management/aliases.md
- 'User Management': config/user-management.md
- 'Best Practices':
- 'DKIM': config/best-practices/dkim.md
- 'DMARC': config/best-practices/dmarc.md