Anything that can be configured in the web administration interface,
can also be configured via the Mailu RESTful API.
See the section Advanced configuration in the configuration reference
for the relevant settings in mailu.env for enabling the API.
(API, WEB_API, API_TOKEN).
main
Dimitri Huisman2 years agocommitted byAlexander Graf
'email':fields.String(description='The email address of the user',example='John.Doe@example.com',attribute='_email'),
'password':fields.String(description='PBKDF2-HMAC-SHA256 based password of the user. For more info see passlib.hash.pbkdf2_sha256',example='$pbkdf2-sha256$1$.6UI/S.nXIk8jcbdHx3Fhg$98jZicV16ODfEsEZeYPGHU3kbrUrvUEXOPimVSQDD44'),
'comment':fields.String(description='A description for the user. This description is shown on the Users page',example='my comment'),
'quota_bytes':fields.Integer(description='The maximum quota for the user’s email box in bytes',example='1000000000'),
'global_admin':fields.Boolean(description='Make the user a global administrator'),
'enabled':fields.Boolean(description='Enable the user. When an user is disabled, the user is unable to login to the Admin GUI or webmail or access his email via IMAP/POP3 or send mail'),
'enable_imap':fields.Boolean(description='Allow email retrieval via IMAP'),
'enable_pop':fields.Boolean(description='Allow email retrieval via POP3'),
'forward_enabled':fields.Boolean(description='Enable auto forwarding'),
'forward_destination':fields.List(fields.String(description='Email address to forward emails to'),example='Other@example.com'),
'forward_keep':fields.Boolean(description='Keep a copy of the forwarded email in the inbox'),
'reply_enabled':fields.Boolean(description='Enable automatic replies. This is also known as out of office (ooo) or out of facility (oof) replies'),
'reply_subject':fields.String(description='Optional subject for the automatic reply',example='Out of office'),
'reply_body':fields.String(description='The body of the automatic reply email',example='Hello, I am out of office. I will respond when I am back.'),
'reply_startdate':fields.Date(description='Start date for automatic replies in YYYY-MM-DD format.',example='2022-02-10'),
'reply_enddate':fields.Date(description='End date for automatic replies in YYYY-MM-DD format.',example='2022-02-22'),
'displayed_name':fields.String(description='The display name of the user within the Admin GUI',example='John Doe'),
'spam_enabled':fields.Boolean(description='Enable the spam filter'),
'spam_mark_as_read':fields.Boolean(description='Enable marking spam mails as read'),
'spam_threshold':fields.Integer(description='The user defined spam filter tolerance',example='80'),
})
user_fields_post=api.model('UserCreate',{
'email':fields.String(description='The email address of the user',example='John.Doe@example.com',attribute='_email',required=True),
'raw_password':fields.String(description='The raw (plain text) password of the user. Mailu will hash the password using PBKDF2-HMAC-SHA256',example='secret',required=True),
'comment':fields.String(description='A description for the user. This description is shown on the Users page',example='my comment'),
'quota_bytes':fields.Integer(description='The maximum quota for the user’s email box in bytes',example='1000000000'),
'global_admin':fields.Boolean(description='Make the user a global administrator'),
'enabled':fields.Boolean(description='Enable the user. When an user is disabled, the user is unable to login to the Admin GUI or webmail or access his email via IMAP/POP3 or send mail'),
'enable_imap':fields.Boolean(description='Allow email retrieval via IMAP'),
'enable_pop':fields.Boolean(description='Allow email retrieval via POP3'),
'forward_enabled':fields.Boolean(description='Enable auto forwarding'),
'forward_destination':fields.List(fields.String(description='Email address to forward emails to'),example='Other@example.com'),
'forward_keep':fields.Boolean(description='Keep a copy of the forwarded email in the inbox'),
'reply_enabled':fields.Boolean(description='Enable automatic replies. This is also known as out of office (ooo) or out of facility (oof) replies'),
'reply_subject':fields.String(description='Optional subject for the automatic reply',example='Out of office'),
'reply_body':fields.String(description='The body of the automatic reply email',example='Hello, I am out of office. I will respond when I am back.'),
'reply_startdate':fields.Date(description='Start date for automatic replies in YYYY-MM-DD format.',example='2022-02-10'),
'reply_enddate':fields.Date(description='End date for automatic replies in YYYY-MM-DD format.',example='2022-02-22'),
'displayed_name':fields.String(description='The display name of the user within the Admin GUI',example='John Doe'),
'spam_enabled':fields.Boolean(description='Enable the spam filter'),
'spam_mark_as_read':fields.Boolean(description='Enable marking spam mails as read'),
'spam_threshold':fields.Integer(description='The user defined spam filter tolerance',example='80'),
})
user_fields_put=api.model('UserUpdate',{
'raw_password':fields.String(description='The raw (plain text) password of the user. Mailu will hash the password using PBKDF2-HMAC-SHA256',example='secret'),
'comment':fields.String(description='A description for the user. This description is shown on the Users page',example='my comment'),
'quota_bytes':fields.Integer(description='The maximum quota for the user’s email box in bytes',example='1000000000'),
'global_admin':fields.Boolean(description='Make the user a global administrator'),
'enabled':fields.Boolean(description='Enable the user. When an user is disabled, the user is unable to login to the Admin GUI or webmail or access his email via IMAP/POP3 or send mail'),
'enable_imap':fields.Boolean(description='Allow email retrieval via IMAP'),
'enable_pop':fields.Boolean(description='Allow email retrieval via POP3'),
'forward_enabled':fields.Boolean(description='Enable auto forwarding'),
'forward_destination':fields.List(fields.String(description='Email address to forward emails to'),example='Other@example.com'),
'forward_keep':fields.Boolean(description='Keep a copy of the forwarded email in the inbox'),
'reply_enabled':fields.Boolean(description='Enable automatic replies. This is also known as out of office (ooo) or out of facility (oof) replies'),
'reply_subject':fields.String(description='Optional subject for the automatic reply',example='Out of office'),
'reply_body':fields.String(description='The body of the automatic reply email',example='Hello, I am out of office. I will respond when I am back.'),
'reply_startdate':fields.Date(description='Start date for automatic replies in YYYY-MM-DD format.',example='2022-02-10'),
'reply_enddate':fields.Date(description='End date for automatic replies in YYYY-MM-DD format.',example='2022-02-22'),
'displayed_name':fields.String(description='The display name of the user within the Admin GUI',example='John Doe'),
'spam_enabled':fields.Boolean(description='Enable the spam filter'),
'spam_mark_as_read':fields.Boolean(description='Enable marking spam mails as read'),
'spam_threshold':fields.Integer(description='The user defined spam filter tolerance',example='80'),
The ``LETSENCRYPT_SHORTCHAIN`` (default: False) setting controls whether we send the
ISRG Root X1 certificate in TLS handshakes. This is required for `android handsets older than 7.1.1`
The ``LETSENCRYPT_SHORTCHAIN`` (default: False) setting controls whether we send the
ISRG Root X1 certificate in TLS handshakes. This is required for `android handsets older than 7.1.1`
but slows down the performance of modern devices.
.._`android handsets older than 7.1.1`: https://community.letsencrypt.org/t/production-chain-changes/150739
@ -234,11 +243,11 @@ The ``TLS_PERMISSIVE`` (default: true) setting controls whether ciphers and prot
.._reverse_proxy_headers:
The ``REAL_IP_HEADER`` (default: unset) and ``REAL_IP_FROM`` (default: unset) settings
controls whether HTTP headers such as ``X-Forwarded-For`` or ``X-Real-IP`` should be trusted.
The former should be the name of the HTTP header to extract the client IP address from and the
later a comma separated list of IP addresses designating which proxies to trust.
If you are using Mailu behind a reverse proxy, you should set both. Setting the former without
The ``REAL_IP_HEADER`` (default: unset) and ``REAL_IP_FROM`` (default: unset) settings
controls whether HTTP headers such as ``X-Forwarded-For`` or ``X-Real-IP`` should be trusted.
The former should be the name of the HTTP header to extract the client IP address from and the
later a comma separated list of IP addresses designating which proxies to trust.
If you are using Mailu behind a reverse proxy, you should set both. Setting the former without
the later introduces a security vulnerability allowing a potential attacker to spoof his source address.
The ``TZ`` sets the timezone Mailu will use. The timezone naming convention usually uses a ``Region/City`` format. See `TZ database name`_ for a list of valid timezones This defaults to ``Etc/UTC``. Warning: if you are observing different timestamps in your log files you should change your hosts timezone to UTC instead of changing TZ to your local timezone. Using UTC allows easy log correlation with remote MTAs.
@ -348,15 +357,15 @@ Mail log settings
By default, all services log directly to stdout/stderr. Logs can be collected by any docker log processing solution.
Postfix writes the logs to a syslog server which logs to stdout. This is used to filter
out messages from the healthcheck. In some situations, a separate mail log is required
(e.g. for legal reasons). The syslog server can be configured to write log files to a volume.
Postfix writes the logs to a syslog server which logs to stdout. This is used to filter
out messages from the healthcheck. In some situations, a separate mail log is required
(e.g. for legal reasons). The syslog server can be configured to write log files to a volume.
It can be configured with the following option:
- ``POSTFIX_LOG_FILE``: The file to log the mail log to. When enabled, the syslog server will also log to stdout.
When ``POSTFIX_LOG_FILE`` is enabled, the logrotate program will automatically rotate the
logs every week and keep 52 logs. To override the logrotate configuration, create the file logrotate.conf
When ``POSTFIX_LOG_FILE`` is enabled, the logrotate program will automatically rotate the
logs every week and keep 52 logs. To override the logrotate configuration, create the file logrotate.conf
with the desired configuration in the :ref:`Postfix overrides folder<override-label>`.
@ -292,7 +292,7 @@ I want to integrate Nextcloud 15 (and newer) with Mailu
),
),
),
If a domain name (e.g. example.com) is specified, then this makes sure that only users from this domain will be allowed to login.
After successfull login the domain part will be stripped and the rest used as username in Nextcloud. e.g. 'username@example.com' will be 'username' in Nextcloud. Disable this behaviour by changing true (the fifth parameter) to false.
@ -346,7 +346,7 @@ How do I use webdav (radicale)?
|
| Subsequently to use webdav (radicale), you can configure your carddav/caldav client to use the following url:
| As username you must provide the complete email address (user@example.com).
| As username you must provide the complete email address (user@example.com).
| As password you must provide the password of the email address.
| The user must be an existing Mailu user.
@ -545,14 +545,14 @@ inside a container. The ``front`` container does use authentication rate limitin
down brute force attacks. The same applies to login attempts via the single sign on page.
We *do* provide a possibility to export the logs from the ``front`` service and ``Admin`` service to the host.
The ``front`` container logs failed logon attempts on SMTP, IMAP and POP3.
The ``front`` container logs failed logon attempts on SMTP, IMAP and POP3.
The ``Admin``container logs failed logon attempt on the single sign on page.
For this you need to set ``LOG_DRIVER=journald`` or ``syslog``, depending on the log
manager of the host. You will need to setup the proper Regex in the Fail2Ban configuration.
Below an example how to do so.
Below an example how to do so.
If you use a reverse proxy in front of Mailu, it is vital to set the environment variables REAL_IP_HEADER and REAL_IP_FROM.
Without these environment variables, Mailu will not trust the remote client IP passed on by the reverse proxy and as a result your reverse proxy will be banned.
Without these environment variables, Mailu will not trust the remote client IP passed on by the reverse proxy and as a result your reverse proxy will be banned.
See the :ref:`[configuration reference <reverse_proxy_headers>` for more information.
@ -591,12 +591,12 @@ follow these steps:
maxretry = 10
action = docker-action
The above will block flagged IPs for a week, you can of course change it to you needs.
The above will block flagged IPs for a week, you can of course change it to your needs.
4. In the mailu docker-compose set the logging driver of the Admin container to journald; and set the tag to mailu-admin
..code-block:: bash
logging:
driver: journald
options:
@ -625,28 +625,53 @@ The above will block flagged IPs for a week, you can of course change it to you
maxretry = 10
action = docker-action
The above will block flagged IPs for a week, you can of course change it to you needs.
The above will block flagged IPs for a week, you can of course change it to your needs.
7. Add the /etc/fail2ban/filter.d/bad-auth-api.conf
..code-block:: bash
# Fail2Ban configuration file
[Definition]
failregex = .* Invalid API token provided by <HOST>.
ignoreregex =
journalmatch = CONTAINER_TAG=mailu-admin
8. Add the /etc/fail2ban/jail.d/bad-auth-api.conf
..code-block:: bash
[bad-auth-api]
enabled = true
backend = systemd
filter = bad-auth-api
bantime = 604800
findtime = 300
maxretry = 10
action = docker-action
The above will block flagged IPs for a week, you can of course change it to your needs.
9. Add the /etc/fail2ban/action.d/docker-action.conf
7. Add the /etc/fail2ban/action.d/docker-action.conf
actionban = iptables -I f2b-bad-auth 1 -s <ip> -j DROP
actionunban = iptables -D f2b-bad-auth -s <ip> -j DROP
Using DOCKER-USER chain ensures that the blocked IPs are processed in the correct order with Docker. See more in: https://docs.docker.com/network/iptables/
@ -657,7 +682,7 @@ IMPORTANT: You have to install ipset on the host system, eg. `apt-get install ip
See ipset homepage for details on ipset, https://ipset.netfilter.org/.
ipset and iptables provide one big advantage over just using iptables: This setup reduces the overall iptable rules.
There is just one rule for the bad authentications and the IPs are within the ipset.
There is just one rule for the bad authentications and the IPs are within the ipset.
Specially in larger setups with a high amount of brute force attacks this comes in handy.
Using iptables with ipset might reduce the system load in such attacks significantly.
@ -678,7 +703,7 @@ Using iptables with ipset might reduce the system load in such attacks significa
Using DOCKER-USER chain ensures that the blocked IPs are processed in the correct order with Docker. See more in: https://docs.docker.com/network/iptables/
1. Configure and restart the Fail2Ban service
10. Configure and restart the Fail2Ban service
Make sure Fail2Ban is started after the Docker service by adding a partial override which appends this to the existing configuration.
@ -727,7 +752,7 @@ In any case, using a dedicated DNS server will improve the performance of your m
Can I learn ham/spam messages from an already existing mailbox?