mirror of
https://github.com/docker-mailserver/docker-mailserver.git
synced 2024-01-19 02:48:50 +00:00
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.
This commit is contained in:
Georg Lauterbach
GitHub
parent
adb38207ad
commit
2b7cab28f7
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
86
docs/content/config/user-management.md
Normal 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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue