mirror of
https://github.com/optim-enterprises-bv/Mailu-OIDC.git
synced 2025-10-30 01:32:22 +00:00
322 lines
9.1 KiB
ReStructuredText
322 lines
9.1 KiB
ReStructuredText
Mailu command line
|
|
==================
|
|
|
|
Managing domains, users and aliases can be done from CLI using the commands:
|
|
|
|
* alias
|
|
* alias-delete
|
|
* domain
|
|
* password
|
|
* user
|
|
* user-import
|
|
* user-delete
|
|
* config-update
|
|
* config-export
|
|
* config-import
|
|
|
|
alias
|
|
-----
|
|
|
|
.. code-block:: bash
|
|
|
|
docker compose exec admin flask mailu alias foo example.net "mail1@example.com,mail2@example.com"
|
|
|
|
|
|
alias-delete
|
|
------------
|
|
|
|
.. code-block:: bash
|
|
|
|
docker compose exec admin flask mailu alias-delete foo@example.net
|
|
|
|
|
|
domain
|
|
------
|
|
|
|
.. code-block:: bash
|
|
|
|
docker compose exec admin flask mailu domain example.net
|
|
|
|
|
|
password
|
|
--------
|
|
|
|
.. code-block:: bash
|
|
|
|
docker compose exec admin flask mailu password myuser example.net 'password123'
|
|
|
|
|
|
user
|
|
----
|
|
|
|
.. code-block:: bash
|
|
|
|
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.
|
|
|
|
.. code-block:: bash
|
|
|
|
docker compose run --rm admin flask mailu user-import myuser example.net '$6$51ebe0cb9f1dab48effa2a0ad8660cb489b445936b9ffd812a0b8f46bca66dd549fea530ce' 'SHA512-CRYPT'
|
|
|
|
|
|
user-delete
|
|
-----------
|
|
|
|
Although the action is called "user-delete" the user is only deactivated by default.
|
|
This is due to the fact mailu does not remove user-data (emails and webmail contacts) when a user is deleted.
|
|
Add the flag `-r` to really delete the user after you have deleted user-data manually.
|
|
|
|
.. code-block:: bash
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
cat mail-config.yml | docker compose exec -T admin flask mailu config-update --delete-objects
|
|
|
|
where mail-config.yml looks like:
|
|
|
|
.. code-block:: bash
|
|
|
|
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_mark_as_read
|
|
* spam_threshold
|
|
|
|
Alias
|
|
^^^^^
|
|
|
|
additional fields:
|
|
|
|
* wildcard
|
|
|
|
.. _config-export:
|
|
|
|
config-export
|
|
-------------
|
|
|
|
The purpose of this command is to export the complete configuration in YAML or JSON format.
|
|
|
|
.. code-block:: bash
|
|
|
|
$ docker compose exec -T 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``.
|
|
|
|
.. code-block:: bash
|
|
|
|
$ docker compose exec admin flask mailu config-export --output-file mail-config.yml
|
|
|
|
$ docker compose exec -T admin flask mailu config-export domain.dns_mx domain.dns_spf
|
|
|
|
$ docker compose exec -T admin flask mailu config-export user.email user.spam_threshold
|
|
|
|
config-import
|
|
-------------
|
|
|
|
This command imports configuration data from an external YAML or JSON source.
|
|
|
|
.. code-block:: bash
|
|
|
|
$ docker compose exec -T 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.
|
|
|
|
To pass stdin correctly you have to use the `-T` option:
|
|
|
|
.. code-block:: bash
|
|
|
|
docker compose exec -T admin flask mailu config-import -nv < mail-config.yml
|
|
|
|
mail-config.yml contains the configuration and looks like this:
|
|
|
|
.. code-block:: yaml
|
|
|
|
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 | ``- -key: id`` | ``- -name: example.com`` |
|
|
+-----------------------------+------------------+--------------------------+
|
|
| specific list item | ``- -id`` | ``- -user1@example.com`` |
|
|
+-----------------------------+------------------+--------------------------+
|
|
| all remaining array objects | ``- -key: null`` | ``- -email: null`` |
|
|
+-----------------------------+------------------+--------------------------+
|
|
| all remaining list items | ``- -prune-`` | ``- -prune-`` |
|
|
+-----------------------------+------------------+--------------------------+
|
|
|
|
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:
|
|
|
|
.. code-block:: yaml
|
|
|
|
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_mark_as_read: true
|
|
spam_threshold: 80
|
|
tokens:
|
|
- id: 1
|
|
comment: email-client
|
|
ip: 192.168.1.1
|
|
password: '$5$rounds=1$...'
|
|
|
|
alias:
|
|
- email: email@example.com
|
|
comment: ''
|
|
destination:
|
|
- address@example.com
|
|
wildcard: false
|
|
|
|
relay:
|
|
- name: relay.example.com
|
|
comment: ''
|
|
smtp: mx.example.com
|