From 2b7cab28f73f7cea32104a6ac93415f295894804 Mon Sep 17 00:00:00 2001 From: Georg Lauterbach <44545919+georglauterbach@users.noreply.github.com> Date: Sun, 9 Apr 2023 11:27:00 +0200 Subject: [PATCH] compress & improve user management docs (#3232) 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. --- .../config/advanced/optional-config.md | 4 +- docs/content/config/environment.md | 4 +- .../security/understanding-the-ports.md | 16 ++-- docs/content/config/user-management.md | 86 +++++++++++++++++++ .../config/user-management/accounts.md | 47 ---------- .../content/config/user-management/aliases.md | 42 --------- docs/content/usage.md | 2 +- docs/mkdocs.yml | 4 +- 8 files changed, 100 insertions(+), 105 deletions(-) create mode 100644 docs/content/config/user-management.md delete mode 100644 docs/content/config/user-management/accounts.md delete mode 100644 docs/content/config/user-management/aliases.md diff --git a/docs/content/config/advanced/optional-config.md b/docs/content/config/advanced/optional-config.md index 2e5c29e0..259e05a2 100644 --- a/docs/content/config/advanced/optional-config.md +++ b/docs/content/config/advanced/optional-config.md @@ -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 diff --git a/docs/content/config/environment.md b/docs/content/config/environment.md index ad5c86e9..68a2fffe 100644 --- a/docs/content/config/environment.md +++ b/docs/content/config/environment.md @@ -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 diff --git a/docs/content/config/security/understanding-the-ports.md b/docs/content/config/security/understanding-the-ports.md index 6a3e91b9..4cd6ded5 100644 --- a/docs/content/config/security/understanding-the-ports.md +++ b/docs/content/config/security/understanding-the-ports.md @@ -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 diff --git a/docs/content/config/user-management.md b/docs/content/config/user-management.md new file mode 100644 index 00000000..a909157e --- /dev/null +++ b/docs/content/config/user-management.md @@ -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 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 setup email add `. 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 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 diff --git a/docs/content/config/user-management/accounts.md b/docs/content/config/user-management/accounts.md deleted file mode 100644 index cc447627..00000000 --- a/docs/content/config/user-management/accounts.md +++ /dev/null @@ -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 diff --git a/docs/content/config/user-management/aliases.md b/docs/content/config/user-management/aliases.md deleted file mode 100644 index ed68f945..00000000 --- a/docs/content/config/user-management/aliases.md +++ /dev/null @@ -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 diff --git a/docs/content/usage.md b/docs/content/usage.md index fbda6e09..bc34f665 100644 --- a/docs/content/usage.md +++ b/docs/content/usage.md @@ -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 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 13029f65..84fb7b7f 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -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