Mailu command line
Managing users and aliases can be done from CLI using commands:
alias
alias-delete
domain
password
user
user-import
user-delete
config-update
config-export
config-import
alias
docker-compose exec admin flask mailu alias foo example.net "mail1@example.com,mail2@example.com"
alias-delete
docker-compose exec admin flask mailu alias-delete foo@example.net
domain
docker-compose exec admin flask mailu domain example.net
password
docker-compose exec admin flask mailu password myuser example.net 'password123'
user
docker-compose exec admin flask mailu user myuser example.net 'password123'
user-import
primary difference with simple user command is that password is being imported as a hash - very useful when migrating users from other systems where only hash is known.
docker-compose run --rm admin flask mailu user-import myuser example.net '$6$51ebe0cb9f1dab48effa2a0ad8660cb489b445936b9ffd812a0b8f46bca66dd549fea530ce' 'SHA512-CRYPT'
user-delete
docker-compose exec admin flask mailu user-delete foo@example.net
config-update
The sole purpose of this command is for importing users/aliases in bulk and synchronizing DB entries with external YAML template:
cat mail-config.yml | docker-compose exec -T admin flask mailu config-update --delete-objects
where mail-config.yml looks like:
users:
- localpart: foo
domain: example.com
password_hash: klkjhumnzxcjkajahsdqweqqwr
aliases:
- localpart: alias1
domain: example.com
destination: "user1@example.com,user2@example.com"
without --delete-object option config-update will only add/update new values but will not remove any entries missing in provided YAML input.
Users
following are additional parameters that could be defined for users:
comment
quota_bytes
global_admin
enable_imap
enable_pop
forward_enabled
forward_destination
reply_enabled
reply_subject
reply_body
displayed_name
spam_enabled
spam_threshold
config-export
The purpose of this command is to export the complete configuration in YAML or JSON format.
$ docker-compose exec admin flask mailu config-export --help
Usage: flask mailu config-export [OPTIONS] [FILTER]...
Export configuration as YAML or JSON to stdout or file
Options:
-f, --full Include attributes with default value.
-s, --secrets Include secret attributes (dkim-key, passwords).
-d, --dns Include dns records.
-c, --color Force colorized output.
-o, --output-file FILENAME Save configuration to file.
-j, --json Export configuration in json format.
-?, -h, --help Show this message and exit.
Only non-default attributes are exported. If you want to export all attributes use --full.
If you want to export plain-text secrets (dkim-keys, passwords) you have to add the --secrets option.
To include dns records (mx, spf, dkim and dmarc) add the --dns option.
By default all configuration objects are exported (domain, user, alias, relay). You can specify
filters to export only some objects or attributes (try: user or domain.name).
Attributes explicitly specified in filters are automatically exported: there is no need to add --secrets or --full.
$ docker-compose exec admin flask mailu config-export --output mail-config.yml
$ docker-compose exec admin flask mailu config-export domain.dns_mx domain.dns_spf
$ docker-compose exec admin flask mailu config-export user.spam_threshold
config-import
This command imports configuration data from an external YAML or JSON source.
$ docker-compose exec admin flask mailu config-import --help
Usage: flask mailu config-import [OPTIONS] [FILENAME|-]
Import configuration as YAML or JSON from stdin or file
Options:
-v, --verbose Increase verbosity.
-s, --secrets Show secret attributes in messages.
-q, --quiet Quiet mode - only show errors.
-c, --color Force colorized output.
-u, --update Update mode - merge input with existing config.
-n, --dry-run Perform a trial run with no changes made.
-?, -h, --help Show this message and exit.
The current version of docker-compose exec does not pass stdin correctly, so you have to user docker exec instead:
docker exec -i $(docker-compose ps -q admin) flask mailu config-import -nv < mail-config.yml
mail-config.yml contains the configuration and looks like this:
domain:
- name: example.com
alternatives:
- alternative.example.com
user:
- email: foo@example.com
password_hash: '$2b$12$...'
hash_scheme: MD5-CRYPT
alias:
- email: alias1@example.com
destination:
- user1@example.com
- user2@example.com
relay:
- name: relay.example.com
comment: test
smtp: mx.example.com
config-import shows the number of created/modified/deleted objects after import.
To suppress all messages except error messages use --quiet.
By adding the --verbose switch the import gets more detailed and shows exactly what attributes changed.
In all log messages plain-text secrets (dkim-keys, passwords) are hidden by default. Use --secrets to log secrets.
If you want to test what would be done when importing without committing any changes, use --dry-run.
By default config-import replaces the whole configuration. --update allows to modify the existing configuration instead.
New elements will be added and existing elements will be modified.
It is possible to delete a single element or prune all elements from lists and associative arrays using a special notation:
Delete what? |
notation |
example |
|---|---|---|
specific array object |
|
|
specific list item |
|
|
all remaining array objects |
|
|
all remaining list items |
|
|
The -key: null notation can also be used to reset an attribute to its default.
To reset spam_threshold to it’s default 80 use -spam_threshold: null.
A new dkim key can be generated when adding or modifying a domain, by using the special value
dkim_key: -generate-.
This is a complete YAML template with all additional parameters that can be defined:
domain:
- name: example.com
alternatives:
- alternative.tld
comment: ''
dkim_key: ''
max_aliases: -1
max_quota_bytes: 0
max_users: -1
signup_enabled: false
user:
- email: postmaster@example.com
comment: ''
displayed_name: 'Postmaster'
enable_imap: true
enable_pop: false
enabled: true
fetches:
- id: 1
comment: 'test fetch'
error: null
host: other.example.com
keep: true
last_check: '2020-12-29T17:09:48.200179'
password: 'secret'
hash_password: true
port: 993
protocol: imap
tls: true
username: fetch-user
forward_destination:
- address@remote.example.com
forward_enabled: true
forward_keep: true
global_admin: true
manager_of:
- example.com
password: '$2b$12$...'
hash_password: true
quota_bytes: 1000000000
reply_body: ''
reply_enabled: false
reply_enddate: '2999-12-31'
reply_startdate: '1900-01-01'
reply_subject: ''
spam_enabled: true
spam_threshold: 80
tokens:
- id: 1
comment: email-client
ip: 192.168.1.1
password: '$5$rounds=1$...'
aliases:
- email: email@example.com
comment: ''
destination:
- address@example.com
wildcard: false
relay:
- name: relay.example.com
comment: ''
smtp: mx.example.com