``DOMAIN`` is the main mail domain. Aka, server identification for outgoing mail. DMARC reports point to ``POSTMASTER`` @ ``DOMAIN``.
These are really the only things it is used for. You don't need a cert for ``DOMAIN``, as it is a mail domain only and not used as host in any sense.
However, it is usual that ``DOMAIN`` gets setup as one of the many mail domains. None of the mail domains ever need a certificate.
TLS certificates work on host connection level only.
``HOSTNAMES`` however, can be used to connect to the server. All host names supplied in this variable will need a certificate. When ``TLS_FLAVOR=letsencrypt`` is set,
a certificate is requested automatically for all those domains.
So when you have something like this:
..code-block:: bash
DOMAIN=example.com
POSTMASTER=me
HOSTNAMES=mail.example.com,mail.foo.com,bar.com
TLS_FLAVOR=letsencrypt
- You'll end up with a DMARC address to ``me@example.com``.
- Server identifies itself as the SMTP server of ``@example.com`` when sending mail. Make sure your reverse DNS hostname is part of that domain!
- Your server will have certificates for the 3 hostnames. You will need to create ``A`` and ``AAAA`` records for those names,
pointing to the IP addresses of your server.
- The admin interface generates ``MX`` and ``SPF`` examples which point to the first entry of ``HOSTNAMES`` but these are only examples.
You can modify them to use any other ``HOSTNAMES`` entry.
In this case ``example.com`` is not reachable as a host and will not have a certificate.
It can be used as a mail domain if MX is setup to point to one of the ``HOSTNAMES``. However, it is possible to include ``example.com`` in ``HOSTNAMES``.
To override the root location (``/``) in Nginx ``WEBROOT_REDIRECT`` needs to be set to ``none`` in the env file (see :ref:`web settings <web_settings>`).
After successful 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.
After successfull login the domain part will be striped and the rest used as username in Nextcloud. e.g. 'username@example.com' will be 'username' in Nextcloud.
1. add ``mta-sts.example.com`` to the ``HOSTNAMES`` configuration variable (and ensure that a valid SSL certificate is available for it; this may mean restarting your smtp container)
3. setup the appropriate DNS/CNAME record (``mta-sts.example.com`` -> ``mailu.example.com``) and DNS/TXT record (``_mta-sts.example.com`` -> ``v=STSv1; id=1``) paying attention to the ``TTL`` as this is used by MTA-STS.
It is not possible to delete users via the Mailu web administration interface. The main reason is to prevent email address reuse. If a user was deleted, it can be recreated and used by someone else. It is not clear that the email address has been used by someone else previously. This new user might receive emails which were meant for the previous user. Disabling the user, prevents the email address to be reused by mistake.
Another reason is that extra post-deletion steps are required after a user has been deleted from the Mailu database. Those additional steps are:
* Delete the dovecot mailbox. If this does not happen, a new user with the same email address reuses the previous user's mailbox.
* Delete the user from the roundcube database (not required when SnappyMail is used). If this does not happen, a new user with the same email address reuses the previous roundcube data (such as address lists, gpg keys etc).
For safely deleting the user data (and possible the user as well) a script has been introduced. The scripts provides the following information
* commands for deleting mailboxes of unknown users. These users were deleted from Mailu, but still have their mailbox data on the file system.
* commands for deleting mailboxes and roundcube data for disabled users.
* commands for deleting users from the Mailu database.
Proceed as following for deleting an user:
1. Disable the to-be-deleted user. This can be done via the Web Administration interface (/admin), the Mailu CLI command user-delete, or the RESTful API. Do **not** delete the user.
2. Download .\\scripts\\purge_user.sh from the `github project`_. Or clone the Mailu github project.
3. Copy the script purge_user.sh to the Mailu folder that contains the `docker-compose.yml` file.
4. Run as root: purge_user.sh
5. The script will output the commands that can be used for fully purging each disabled user. It will show the instruction for deleting the user from the
* Dovecot maildir from filesystem (all email data)
* Roundcube database (all data saved in roundcube)
* Mailu database.
6. Run the commands for deleting all user data for each disabled user.
Any mail related connection is proxied by the front container. Therefore the SMTP Banner is also set by front container. Overwriting in overrides/postfix.cf does not apply.
Some email operators insist that emails are delivered slowly. Mailu maintains two separate queues for such destinations: ``polite`` and ``turtle``. To enable them for some destination you can creating an override at ``overrides/postfix/transport.map`` as follow:
Emails are asynchronous and it's not abnormal for them to be defered sometimes. That being said, Mailu enforces secure connections where possible using DANE and MTA-STS, both of which have the potential to delay indefinitely delivery if something is misconfigured.
If delivery to a specific domain fails because their DANE records are invalid or their TLS configuration inadequate (expired certificate, ...), you can assist delivery by downgrading the security level for that domain by creating an override at ``overrides/postfix/tls_policy.map`` as follow:
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.
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/.
Please note that the provided example will block the subnet from sending any email to the Mailu instance.
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/
After applying the change, you will need to rebuild the image and use it in your deployment.
We **strongly** advice against downgrading the TLS version and ciphers, please upgrade your client instead! We will not support a more standard way of setting this up.
In many cases, Docker Compose will complain about the yaml syntax because it is too old. It is especially true if you installed Docker Compose as part of your GNU/Linux distribution package system.
Disabling antispam in the user settings actually disables automatic classification of messages as spam and stops moving them to the `junk` folder. It does not stop spam scanning and filtering.
Therefore, messages still get discarded if their spam score is so high that the antispam finds them unfit for distribution. Also, the antispam headers are still present in the message, so that mail clients can display it and classify based on it.
*Issue reference:*`897`_.
Why is SPF failing while properly setup?
````````````````````````````````````````
Very often, SPF failure is related to Mailu sending emails with a different IP address than the one configured in the env file.
This is mostly due to using a separate IP address for Mailu and still having masquerading NAT setup for Docker, which results in a different outbound IP address. You can simply check the email headers on the receiving side to confirm this.
First, check if you are really sure the user is a legitimate sender, i.e. the registered user is authenticated successfully and own either the account or alias he/she is trying to send from. If you are really sure this is correct, then the user might try to erroneously send via port 25 instead of the designated SMTP client-ports. Port 25 is meant for server-to-server delivery, while users should use port 587 or 465.
Since v1.9, Mailu requires a **validating** DNSSEC enabled DNS resolver. To check whether your DNS resolver (and its upstream) fits the requirements you can use the following command and see whether the **AD** flag is present in the reply:
..code-block:: bash
dig @<ip> +adflag example.org A
We recommend that you run your own DNS resolver (enable unbound and update your docker-compose.yml when you update from older versions) instead of relying on publicly available ones. It's better security-wise (you don't have to trust them) and RBLs used by rspamd are known to rate-limit per source-ip address.
We have seen a fair amount of support requests related to the following:
- dnsmasq won't forward DNSSEC results unless instructed to do so. If you are running openwrt or pi-hole, you do need to enable DNSSEC.
- systemd-resolve won't validate DNSSEC results unless instructed to do so. If you are using it you can check its configuration using ``systemd-resolve --status | grep DNSSEC``
Running Mailu without docker is not supported. If you want to do so, you need to export an environment variable called ``I_KNOW_MY_SETUP_DOESNT_FIT_REQUIREMENTS_AND_WONT_FILE_ISSUES_WITHOUT_PATCHES`` to the ``admin`` container.
We welcome patches but do not have the bandwidth to test and fix issues related to your unsupported setup. If you do want to help, we welcome new maintainers: please get in touch.
If not, you can download the `aspell dictionary`_ you require and place it in ``/usr/share/aspell/`` and then enable it by tweaking the following in the configuration file:
There may be multiple causes for it but if you are running docker 24.0.0, odds are you are `experiencing this docker bug`_ and the workaround is to switch to a different version of docker.
.._`experiencing this docker bug`: https://github.com/Mailu/Mailu/issues/2827
In some situations, a separate log is required. For example a separate mail log (from postfix) could be required due to legal reasons.
All Mailu containers log the output to journald. The logs are written to journald with the tag:
| mailu-<service name>
| where <service-name> is the name of the service in the docker-compose.yml file.
| For example, the service running postfix is called smtp. To view the postfix logs use:
..code-block:: bash
journalctl -t mailu-smtp
Note: ``SHIFT+G`` can be used to jump to the end of the log file. ``G`` can be used to jump back to the top of the log file.
To export the log files from journald to the file system, the logs could be imported into a syslog program like ``rsyslog``.
Via ``rsyslog`` the container specific logs could be written to a separate file using a filter.
Below are the steps for writing the postfix (mail) logs to a log file on the file system.
1. Install the ``rsyslog`` package. Note: on most distributions this program is already installed.
2. Edit ``/etc/systemd/journald.conf``.
3. Enable ``ForwardToSyslog=yes``. Note: on most distributions this is already enabled by default. This forwards journald to syslog.
4.``sudo touch /var/log/postfix.log``. This step creates the mail log file.
5.``sudo chown syslog:syslog /var/log/postfix.log``. This provides rsyslog the permissions for accessing this file.
6. Create a new config file in ``/etc/rsyslog.d/export-postfix.conf``
7. Add ``:programname, contains, "mailu-smtp" /var/log/postfix.log``. This instructs rsyslog to write the logs for mailu-smtp to a log file on file system.
10. All messages from the smtp/postfix container are now logged to ``/var/log/postfix.log``.
11. Rsyslog does not perform log rotation. The program (package) ``log rotate`` can be used for this task. Install the ``logrotate`` package.
12. Modify the existing configuration file for rsyslog: ``sudo nano /etc/logrotate.d/rsyslog``
13. Add at the top add: ``/var/log/postfix.log``. Of course you can also use your own configuration. This is just an example. A complete example for configuring log rotate is:
If the admin container is `unable to connect to an external MariaDB database due to incompatible collation`_, you may need to change the ``SQLALCHEMY_DATABASE_URI`` setting to ensure the right connector is used.
MariaDB has no support for utf8mb4_0900_ai_ci which is the new default since MySQL version 8.0.
.._`unable to connect to an external MariaDB database due to incompatible collation`: https://github.com/Mailu/Mailu/issues/3449
On Linux amd64 (x84_64), if the antispam container is crashing and gives you an `Illegal instruction` error, you may have a CPU that lacks support of the ``SSE4.2`` instruction set.
The more modern and FOSS ``vectorscan`` library used by rspamd superseeded the now closed source Intel ``hyperscan`` library in Alpine Linux, and since August 2024 it requires the ``SSE4.2`` instruction set to work properly.
Pre-2013 Intel Atom CPUs (Like N2800 or D425), Intel pre-Nehalem architectures and AMD pre-Bulldozer architectures does not support ``SSE4.2``.
A workaround to this issue is to use a x86_32 (or i686) version of rspamd, because the ``vectorscan`` library is only used on 64-bit capable systems.
Note that this may stop working in the future, as 32-bit software support is being progressively dropped.
