From e8260d7523e1ba5770abedd3c2eac4951528ee6d Mon Sep 17 00:00:00 2001 From: polarathene <5098581+polarathene@users.noreply.github.com> Date: Fri, 26 Jan 2024 16:24:50 +1300 Subject: [PATCH] docs: Accounts (File) - Refactor - Manual method not necessary to document. - Condense `setup` example guidance. - Quotas / Aliases content migrated to Overview when not specific about file provisioner. Some of the content is this commit is not a complete revision. --- .../config/account-management/overview.md | 27 +++++++ .../account-management/provisioner/file.md | 70 ++++--------------- 2 files changed, 42 insertions(+), 55 deletions(-) diff --git a/docs/content/config/account-management/overview.md b/docs/content/config/account-management/overview.md index a0b2d50f..34691f27 100644 --- a/docs/content/config/account-management/overview.md +++ b/docs/content/config/account-management/overview.md @@ -10,8 +10,35 @@ Anchor heading links stubbed out below. ### Aliases +You may read [Postfix's documentation on virtual aliases][postfix-docs-alias] first. + +An alias is a full email address that will either be: + +- Delivered to an existing account +- Redirected to one or more other email addresses + +### 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 + ### Quotas +- `imap-quota` is enabled and allow clients to query their mailbox usage. +- Dovecot quotas are compatible with LDAP, **but it's not implemented** (_PRs are welcome!_). + ## Technical Overview - Postfix handles when mail is delivered (inbound) to DMS, or sent (outbound) from DMS. diff --git a/docs/content/config/account-management/provisioner/file.md b/docs/content/config/account-management/provisioner/file.md index 58a05959..801ffcf1 100644 --- a/docs/content/config/account-management/provisioner/file.md +++ b/docs/content/config/account-management/provisioner/file.md @@ -4,55 +4,27 @@ title: 'Account Management | File Provisioner' ## 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. +Users (email accounts) are managed in `/tmp/docker-mailserver/postfix-accounts.cf`. -### Adding a new Account +The best way to manage accounts is to use our `setup` CLI provided inside the container. -#### Via `setup` inside the container +!!! example "Using `setup` within the container" -You can add an account by running `docker exec -ti setup email add `. This method is strongly preferred. + Try the following within the DMS container (`docker exec -it bash`): -#### 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 -``` + - Add an account: `setup email add ` + - Add an alias: `setup alias add ` + - Learn more about subcommands available: `setup help` ### Quotas -- `imap-quota` is enabled and allow clients to query their mailbox usage. +`/tmp/docker-mailserver/dovecot-quotas.cf` + - 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 +### 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 +`/tmp/docker-mailserver/postfix-virtual.cf` Alias and target are space separated. An example on a server with `example.com` as its domain: @@ -66,23 +38,11 @@ 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: +- 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