# Account Management | Provisioner (File) - Docker Mailserver
A fullstack but simple mail-server (SMTP, IMAP, LDAP, Anti-spam, Anti-virus, etc.) using Docker.
Author: docker-mailserver (Github Organization)

Skip to content

# Provisioner - File

## Management via the `setup` CLI

The best way to manage DMS accounts and related config files is through our `setup` CLI provided within the container.

Using the `setup` CLI

Try the following within the DMS container (`docker exec -it <CONTAINER NAME> bash`):

- Add an account: `setup email add <EMAIL ADDRESS>`
- Add an alias: `setup alias add <FROM ALIAS> <TO TARGET ADDRESS>`
- Learn more about the available subcommands via: `setup help`

    # Starts a basic DMS instance and then shells into the container to use the `setup` CLI:
    docker run --rm -itd --name dms --hostname mail.example.com mailserver/docker-mailserver
    docker exec -it dms bash

    # Create an account:
    setup email add hello@example.com your-password-here

    # Create an alias:
    setup alias add your-alias-here@example.com hello@example.com

    # Limit the mailbox capacity to 10 MiB:
    setup quota set hello@example.com 10M

Secure password input

When you don't provide a password to the command, you will be prompted for one. This avoids the password being captured in your shell history.

    # As you input your password it will not update.
    # Press the ENTER key to apply the hidden password input.
    $ setup email add hello@example.com
    Enter Password:
    Confirm Password:

Account removal via `setup email del`

When you remove a DMS account with this command, it will also remove any associated aliases and quota.

The command will also prompt for deleting the account mailbox from disk, or can be forced with the `-y` flag.

## Config Reference

These config files belong to the Config Volume.

### Accounts

Info

Config file: `docker-data/dms/config/postfix-accounts.cf`

The config format is line-based with two fields separated by the delimiter `|`:

- User: The primary email address for the account mailbox to use.
- Password: A SHA512-CRYPT hash of the account password (in this example it is `secret`).

Password hash without the `setup email add` command

A compatible password hash can be generated with:

    doveadm pw -s SHA512-CRYPT -u hello@example.com -p secret

`postfix-accounts.cf` config file

In this example DMS manages mail for the domain `example.com`:

postfix-accounts.cf

    hello@example.com|{SHA512-CRYPT}$6$W4rxRQwI6HNMt9n3$riCi5/OqUxnU8eZsOlZwoCnrNgu1gBGPkJc.ER.LhJCu7sOg9i1kBrRIistlBIp938GdBgMlYuoXYUU5A4Qiv0

Dovecot "extra fields"

Appending a third column will customize "extra fields" when converting account data into a Dovecot UserDB entry.

DMS is not aware of these customizations beyond carrying them over, expect potential for bugs when this feature breaks any assumed conventions used in the scripts (such as changing the mailbox path or type).

Note

Account creation will normalize the provided email address to lowercase, as DMS does not support multiple case-sensitive address variants.

The email address chosen will also represent the login username credential for mail clients to authenticate with.

### Aliases

Info

Config file: `docker-data/dms/config/postfix-virtual.cf`

The config format is line-based with key value pairs (alias --> target address), with white-space as a delimiter.

`postfix-virtual.cf` config file

In this example DMS manages mail for the domain `example.com`:

postfix-virtual.cf

    # Alias delivers to an existing account:
    alias1@example.com hello@example.com

    # Alias forwards to an external email address:
    alias2@example.com external-account@gmail.com

Known Issues

`setup` CLI prevents an alias and account sharing an address:

You cannot presently add a new account (`setup email add`) or alias (`setup alias add`) with an address which already exists as an alias or account in DMS.

This restriction was enforced due to problems it could cause, although there are use-cases where you may legitimately require this functionality.

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.

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, 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`.

#### Configuring RegEx aliases

Info

Config file: `docker-data/dms/config/postfix-regexp.cf`

This config file is similar to the above `postfix-virtual.cf`, but the alias value is instead configured with a regex pattern.

There is no `setup` CLI support for this feature, it is config only.

`postfix-regexp.cf` config file

Deliver all mail for `test` users to `qa@example.com` instead:

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

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.

### Quotas

Info

Config file: `docker-data/dms/config/dovecot-quotas.cf`

The config format is line-based with two fields separated by the delimiter `:`:

- Dovecot UserDB account: The user DMS account. It should have a matching field in `postfix-accounts.cf`.
- Quota limit: Expressed in bytes (binary unit suffix is supported: `M` => `MiB`, `G` => `GiB`).

`dovecot-quotas.cf` config file

For the account with the mailbox address of `hello@example.com`, it may not exceed 5 GiB in storage:

dovecot-quotas.cf

    hello@example.com:5G