mailu/docs/configuration.rst

Configuration reference
=======================

This page explains the variables found in ``mailu.env``.
In most cases ``mailu.env`` is setup correctly by the setup utility and can be left as-is.
However, some advanced settings or modifications can be done by modifying this file.

.. _common_cfg:

Common configuration
--------------------

The ``SECRET_KEY`` **must** be changed for every setup and set to a 16 bytes
randomly generated value. It is intended to secure authentication cookies
among other critical uses. This can be generated with a utility such as *pwgen*,
which can be installed on most Linux systems:

.. code-block:: bash

  apt-get install pwgen
  pwgen 16 1

The ``DOMAIN`` holds the main e-mail domain for the server. This email domain
is used for bounce emails, for generating the postmaster email and other
technical addresses.

The ``HOSTNAMES`` are all public hostnames for the mail server. Mailu supports
a mail server with multiple hostnames. The first declared hostname is the main
hostname and will be exposed over SMTP, IMAP, etc.

The ``SUBNET`` defines the address range of the docker network used by Mailu.
This should not conflict with any networks to which your system is connected.
(Internal and external!). Normally this does not need to be changed,
unless there is a conflict with existing networks.

The ``POSTMASTER`` is the local part of the postmaster email address. It is
recommended to setup a generic value and later configure a mail alias for that
address.

The ``AUTH_RATELIMIT`` holds a security setting for fighting attackers that
try to guess user passwords. The value is the limit of failed authentication attempts
that a single IP address can perform against IMAP, POP and SMTP authentication endpoints.

If ``AUTH_RATELIMIT_SUBNET`` is ``True`` (which is the default), the ``AUTH_RATELIMIT``
rules does also apply to auth requests coming from ``SUBNET``, especially for the webmail.
If you disable this, ensure that the rate limit on the webmail is enforced in a different
way (e.g. roundcube plug-in), otherwise an attacker can simply bypass the limit using webmail.


The ``TLS_FLAVOR`` sets how Mailu handles TLS connections. Setting this value to
``notls`` will cause Mailu not to server any web content! More on :ref:`tls_flavor`.

Mail settings
-------------

The ``MESSAGE_SIZE_LIMIT`` is the maximum size of a single email. It should not
be too low to avoid dropping legitimate emails and should not be too high to
avoid filling the disks with large junk emails.

The ``RELAYNETS`` are network addresses for which mail is relayed for free with
no authentication required. This should be used with great care. If you want other
Docker services' outbound mail to be relayed, you can set this to ``172.16.0.0/12``
to include **all** Docker networks. The default is to leave this empty.

The ``RELAYHOST`` is an optional address of a mail server relaying all outgoing
mail in following format: ``[HOST]:PORT``.
``RELAYUSER`` and ``RELAYPASSWORD`` can be used when authentication is needed.

The ``FETCHMAIL_DELAY`` is a delay (in seconds) for the fetchmail service to
go and fetch new email if available. Do not use too short delays if you do not
want to be blacklisted by external services, but not too long delays if you
want to receive your email in time.

The ``RECIPIENT_DELIMITER`` is a character used to delimit localpart from a
custom address part. For instance, if set to ``+``, users can use addresses
like ``localpart+custom@domain.tld`` to deliver mail to ``localpart@domain.tld``.
This is useful to provide external parties with different email addresses and
later classify incoming mail based on the custom part.

The ``DMARC_RUA`` and ``DMARC_RUF`` are DMARC protocol specific values. They hold
the localpart for DMARC rua and ruf email addresses.

Web settings
------------

The ``WEB_ADMIN`` contains the path to the main admin interface, while
``WEB_WEBMAIL`` contains the path to the Web email client.
The ``WEBROOT_REDIRECT`` redirects all non-found queries to the set path.
An empty ``WEBROOT_REDIRECT`` value disables redirecting and enables classic
behavior of a 404 result when not found.
All three options need a leading slash (``/``) to work.

  .. note:: ``WEBROOT_REDIRECT`` has to point to a valid path on the webserver.
    This means it cannot point to any services which are not enabled.
    For example, don't point it to ``/webmail`` when ``WEBMAIL=none``

Both ``SITENAME`` and ``WEBSITE`` are customization options for the panel menu
in the admin interface, while ``SITENAME`` is a customization option for
every Web interface.

.. _admin_account:

Admin account - automatic creation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For administrative tasks, an admin user account will be needed. You can create it manually,
after deploying the system, or automatically.
To create it manually, follow the specific deployment method documentation.

To have the account created automatically, you just need to define a few environment variables:

.. code-block:: bash

  INITIAL_ADMIN_ACCOUNT = ``root`` The first part of the e-mail address (ROOT@example.com)
  INITIAL_ADMIN_DOMAIN = ``example.com`` the domain appendix. Most probably identical to the DOMAIN variable
  INITIAL_ADMIN_PW = ``password`` the chosen password for the user

Also, environment variable ``INITIAL_ADMIN_MODE`` defines how the code should behave when it will
try to create the admin user:

- ``create`` (default) Will try to create user and will raise an exception if present
- ``ifmissing``: if user exists, nothing happens, else it will be created
- ``update``: user is created or, if it exists, its password gets updated

Depending on your particular deployment you most probably will want to change the default.

Advanced settings
-----------------

The ``PASSWORD_SCHEME`` is the password encryption scheme. You should use the
default value, unless you are importing password from a separate system and
want to keep using the old password encryption scheme.

The ``LOG_LEVEL`` setting is used by the python start-up scripts as a logging threshold.
Log messages equal or higher than this priority will be printed.
Can be one of: CRITICAL, ERROR, WARNING, INFO, DEBUG or NOTSET.
See the `python docs`_ for more information.

.. _`python docs`: https://docs.python.org/3.6/library/logging.html#logging-levels

Antivirus settings
------------------

The ``ANTIVIRUS_ACTION`` switches behaviour if a virus is detected. It defaults to 'discard',
so any detected virus is silently discarded. If set to 'reject', rspamd is configured to reject
virus mails during SMTP dialogue, so the sender will receive a reject message.

Infrastructure settings
-----------------------

Various environment variables ``HOST_*`` can be used to run Mailu containers
separately from a supported orchestrator. It is used by the various components
to find the location of the other containers it depends on. They can contain an
optional port number. Those variables are:

- ``HOST_IMAP``: the container that is running the IMAP server (default: ``imap``, port 143)
- ``HOST_LMTP``: the container that is running the LMTP server (default: ``imap:2525``)
- ``HOST_HOSTIMAP``: the container that is running the IMAP server for the webmail (default: ``imap``, port 10143)
- ``HOST_POP3``: the container that is running the POP3 server (default: ``imap``, port 110)
- ``HOST_SMTP``: the container that is running the SMTP server (default: ``smtp``, port 25)
- ``HOST_AUTHSMTP``: the container that is running the authenticated SMTP server for the webnmail (default: ``smtp``, port 10025)
- ``HOST_ADMIN``: the container that is running the admin interface (default: ``admin``)
- ``HOST_ANTISPAM_MILTER``: the container that is running the antispam milter service (default: ``antispam:11332``)
- ``HOST_ANTISPAM_WEBUI``: the container that is running the antispam webui service (default: ``antispam:11334``)
- ``HOST_ANTIVIRUS``: the container that is running the antivirus service (default: ``antivirus:3310``)
- ``HOST_WEBMAIL``: the container that is running the webmail (default: ``webmail``)
- ``HOST_WEBDAV``: the container that is running the webdav server (default: ``webdav:5232``)
- ``HOST_REDIS``: the container that is running the redis daemon (default: ``redis``)
- ``HOST_WEBMAIL``: the container that is running the webmail (default: ``webmail``)

The startup scripts will resolve ``HOST_*`` to their IP addresses and store the result in ``*_ADDRESS`` for further use.

Alternatively, ``*_ADDRESS`` can directly be set. In this case, the values of ``*_ADDRESS`` is kept and not
resolved. This can be used to rely on DNS based service discovery with changing services IP addresses.
When using ``*_ADDRESS``, the hostnames must be full-qualified hostnames. Otherwise nginx will not be able to
resolve the hostnames.
Make docs refer to the setup utility 6 years ago			`Configuration reference`
			`=======================`

			This page explains the variables found in ``mailu.env``.
			In most cases ``mailu.env`` is setup correctly by the setup utility and can be left as-is.
			`However, some advanced settings or modifications can be done by modifying this file.`
Import the documentation from the wiki 7 years ago
Some documentation flow refactoring and updates: - Improve advice on IP binding; Follow up on issue #641 - mailradar is dead. Found mxtoolbox instead - Fix some internal linking 6 years ago			`.. _common_cfg:`

Import the documentation from the wiki 7 years ago			`Common configuration`
			`--------------------`

Fix the rst syntax for most documentation 7 years ago			The ``SECRET_KEY`` must be changed for every setup and set to a 16 bytes
Import the documentation from the wiki 7 years ago			`randomly generated value. It is intended to secure authentication cookies`
Some documentation flow refactoring and updates: - Improve advice on IP binding; Follow up on issue #641 - mailradar is dead. Found mxtoolbox instead - Fix some internal linking 6 years ago			`among other critical uses. This can be generated with a utility such as pwgen,`
			`which can be installed on most Linux systems:`

			`.. code-block:: bash`

			`apt-get install pwgen`
			`pwgen 16 1`
Import the documentation from the wiki 7 years ago
Fix the rst syntax for most documentation 7 years ago			The ``DOMAIN`` holds the main e-mail domain for the server. This email domain
Import the documentation from the wiki 7 years ago			`is used for bounce emails, for generating the postmaster email and other`
			`technical addresses.`

Fix the rst syntax for most documentation 7 years ago			The ``HOSTNAMES`` are all public hostnames for the mail server. Mailu supports
Import the documentation from the wiki 7 years ago			`a mail server with multiple hostnames. The first declared hostname is the main`
			`hostname and will be exposed over SMTP, IMAP, etc.`

Move the Mailu Docker network to a fixed subnet. This will make network configuration and host based authentication more robust, across different deployment platforms. The options `RELAYNETS` and`POD_ADDRESS_RANGE` are kept for compatibility. However, their usage have become optional. 6 years ago			The ``SUBNET`` defines the address range of the docker network used by Mailu.
			`This should not conflict with any networks to which your system is connected.`
			`(Internal and external!). Normally this does not need to be changed,`
			`unless there is a conflict with existing networks.`

Fix the rst syntax for most documentation 7 years ago			The ``POSTMASTER`` is the local part of the postmaster email address. It is
Import the documentation from the wiki 7 years ago			`recommended to setup a generic value and later configure a mail alias for that`
			`address.`

Fix the rst syntax for most documentation 7 years ago			The ``AUTH_RATELIMIT`` holds a security setting for fighting attackers that
Don't raise rate limit exception on hit(), only on check() 5 years ago			`try to guess user passwords. The value is the limit of failed authentication attempts`
			`that a single IP address can perform against IMAP, POP and SMTP authentication endpoints.`

			If ``AUTH_RATELIMIT_SUBNET`` is ``True`` (which is the default), the ``AUTH_RATELIMIT``
			rules does also apply to auth requests coming from ``SUBNET``, especially for the webmail.
			`If you disable this, ensure that the rate limit on the webmail is enforced in a different`
			`way (e.g. roundcube plug-in), otherwise an attacker can simply bypass the limit using webmail.`

Import the documentation from the wiki 7 years ago
Make docs refer to the setup utility 6 years ago			The ``TLS_FLAVOR`` sets how Mailu handles TLS connections. Setting this value to
Fix notls typo 6 years ago			``notls`` will cause Mailu not to server any web content! More on :ref:`tls_flavor`.
Make docs refer to the setup utility 6 years ago
Import the documentation from the wiki 7 years ago			`Mail settings`
			`-------------`

Fix the rst syntax for most documentation 7 years ago			The ``MESSAGE_SIZE_LIMIT`` is the maximum size of a single email. It should not
Import the documentation from the wiki 7 years ago			`be too low to avoid dropping legitimate emails and should not be too high to`
			`avoid filling the disks with large junk emails.`

Fix the rst syntax for most documentation 7 years ago			The ``RELAYNETS`` are network addresses for which mail is relayed for free with
Move the Mailu Docker network to a fixed subnet. This will make network configuration and host based authentication more robust, across different deployment platforms. The options `RELAYNETS` and`POD_ADDRESS_RANGE` are kept for compatibility. However, their usage have become optional. 6 years ago			`no authentication required. This should be used with great care. If you want other`
			Docker services' outbound mail to be relayed, you can set this to ``172.16.0.0/12``
			`to include all Docker networks. The default is to leave this empty.`
Import the documentation from the wiki 7 years ago
Fix the rst syntax for most documentation 7 years ago			The ``RELAYHOST`` is an optional address of a mail server relaying all outgoing
Add authentication for email relays 6 years ago			mail in following format: ``[HOST]:PORT``.
			``RELAYUSER`` and ``RELAYPASSWORD`` can be used when authentication is needed.
Import the documentation from the wiki 7 years ago
Fix the rst syntax for most documentation 7 years ago			The ``FETCHMAIL_DELAY`` is a delay (in seconds) for the fetchmail service to
Import the documentation from the wiki 7 years ago			`go and fetch new email if available. Do not use too short delays if you do not`
			`want to be blacklisted by external services, but not too long delays if you`
			`want to receive your email in time.`

fix variable name for RECIPIENT_DELIMETER the variable name as referenced by postfix (https://github.com/Mailu/Mailu/blob/dcda412b99f19c9b9e62dda19b9bc398df9ece60/core/postfix/conf/main.cf#L40) and others is `RECIPIENT_DELIMETER`. 5 years ago			The ``RECIPIENT_DELIMITER`` is a character used to delimit localpart from a
Fix the rst syntax for most documentation 7 years ago			custom address part. For instance, if set to ``+``, users can use addresses
			like ``localpart+custom@domain.tld`` to deliver mail to ``localpart@domain.tld``.
Import the documentation from the wiki 7 years ago			`This is useful to provide external parties with different email addresses and`
			`later classify incoming mail based on the custom part.`

Update configuration.rst Fix env variable. 7 years ago			The ``DMARC_RUA`` and ``DMARC_RUF`` are DMARC protocol specific values. They hold
Import the documentation from the wiki 7 years ago			`the localpart for DMARC rua and ruf email addresses.`

			`Web settings`
			`------------`

Fix the rst syntax for most documentation 7 years ago			The ``WEB_ADMIN`` contains the path to the main admin interface, while
			``WEB_WEBMAIL`` contains the path to the Web email client.
Add WEBROOT_REDIRECT documentation Closes #802 6 years ago			The ``WEBROOT_REDIRECT`` redirects all non-found queries to the set path.
			An empty ``WEBROOT_REDIRECT`` value disables redirecting and enables classic
			`behavior of a 404 result when not found.`
			All three options need a leading slash (``/``) to work.

			.. note:: ``WEBROOT_REDIRECT`` has to point to a valid path on the webserver.
			`This means it cannot point to any services which are not enabled.`
			For example, don't point it to ``/webmail`` when ``WEBMAIL=none``
Import the documentation from the wiki 7 years ago
Fix the rst syntax for most documentation 7 years ago			Both ``SITENAME`` and ``WEBSITE`` are customization options for the panel menu
			in the admin interface, while ``SITENAME`` is a customization option for
Import the documentation from the wiki 7 years ago			`every Web interface.`

Hopefully improved documentation around initial admin account creation. 6 years ago			`.. _admin_account:`

			`Admin account - automatic creation`
			`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`
			`For administrative tasks, an admin user account will be needed. You can create it manually,`
			`after deploying the system, or automatically.`
			`To create it manually, follow the specific deployment method documentation.`

			`To have the account created automatically, you just need to define a few environment variables:`

			`.. code-block:: bash`

			INITIAL_ADMIN_ACCOUNT = ``root`` The first part of the e-mail address (ROOT@example.com)
			INITIAL_ADMIN_DOMAIN = ``example.com`` the domain appendix. Most probably identical to the DOMAIN variable
			INITIAL_ADMIN_PW = ``password`` the chosen password for the user

			Also, environment variable ``INITIAL_ADMIN_MODE`` defines how the code should behave when it will
			`try to create the admin user:`

			- ``create`` (default) Will try to create user and will raise an exception if present
			- ``ifmissing``: if user exists, nothing happens, else it will be created
			- ``update``: user is created or, if it exists, its password gets updated

			`Depending on your particular deployment you most probably will want to change the default.`

Import the documentation from the wiki 7 years ago			`Advanced settings`
			`-----------------`

Fix the rst syntax for most documentation 7 years ago			The ``PASSWORD_SCHEME`` is the password encryption scheme. You should use the
Import the documentation from the wiki 7 years ago			`default value, unless you are importing password from a separate system and`
			`want to keep using the old password encryption scheme.`
Parametrize hosts Allows to use mailu without docker-compose when hostnames are not set up by docker itself but provided via a separate resolver. Use case: use mailu using nomad scheduler and consul resolver instead of docker-compose. Other servers are provided by the DNS resolver that resolves names like admin.service.consul or webmail.service.consul. These names needs to be configurable. 7 years ago
LOG_LEVEL docs and changelog entry 6 years ago			The ``LOG_LEVEL`` setting is used by the python start-up scripts as a logging threshold.
			`Log messages equal or higher than this priority will be printed.`
			`Can be one of: CRITICAL, ERROR, WARNING, INFO, DEBUG or NOTSET.`
			See the `python docs`_ for more information.

			.. _`python docs`: https://docs.python.org/3.6/library/logging.html#logging-levels

Document default antivirus behaviour, add an option to reject viruses 5 years ago			`Antivirus settings`
			`------------------`

			The ``ANTIVIRUS_ACTION`` switches behaviour if a virus is detected. It defaults to 'discard',
			`so any detected virus is silently discarded. If set to 'reject', rspamd is configured to reject`
			`virus mails during SMTP dialogue, so the sender will receive a reject message.`

Parametrize hosts Allows to use mailu without docker-compose when hostnames are not set up by docker itself but provided via a separate resolver. Use case: use mailu using nomad scheduler and consul resolver instead of docker-compose. Other servers are provided by the DNS resolver that resolves names like admin.service.consul or webmail.service.consul. These names needs to be configurable. 7 years ago			`Infrastructure settings`
			`-----------------------`

			Various environment variables ``HOST_*`` can be used to run Mailu containers
			`separately from a supported orchestrator. It is used by the various components`
			`to find the location of the other containers it depends on. They can contain an`
			`optional port number. Those variables are:`

			- ``HOST_IMAP``: the container that is running the IMAP server (default: ``imap``, port 143)
Add various environment variables to allow running outside of docker-compose 7 years ago			- ``HOST_LMTP``: the container that is running the LMTP server (default: ``imap:2525``)
			- ``HOST_HOSTIMAP``: the container that is running the IMAP server for the webmail (default: ``imap``, port 10143)
Parametrize hosts Allows to use mailu without docker-compose when hostnames are not set up by docker itself but provided via a separate resolver. Use case: use mailu using nomad scheduler and consul resolver instead of docker-compose. Other servers are provided by the DNS resolver that resolves names like admin.service.consul or webmail.service.consul. These names needs to be configurable. 7 years ago			- ``HOST_POP3``: the container that is running the POP3 server (default: ``imap``, port 110)
			- ``HOST_SMTP``: the container that is running the SMTP server (default: ``smtp``, port 25)
			- ``HOST_AUTHSMTP``: the container that is running the authenticated SMTP server for the webnmail (default: ``smtp``, port 10025)
			- ``HOST_ADMIN``: the container that is running the admin interface (default: ``admin``)
Split HOST_ANTISPAM in HOST_ANTISPAM_MILTER and HOST_ANTISPAM_WEBUI 5 years ago			- ``HOST_ANTISPAM_MILTER``: the container that is running the antispam milter service (default: ``antispam:11332``)
			- ``HOST_ANTISPAM_WEBUI``: the container that is running the antispam webui service (default: ``antispam:11334``)
Fixed hardcoded antispam and antivirus host addresses Fixes #978 6 years ago			- ``HOST_ANTIVIRUS``: the container that is running the antivirus service (default: ``antivirus:3310``)
Parametrize hosts Allows to use mailu without docker-compose when hostnames are not set up by docker itself but provided via a separate resolver. Use case: use mailu using nomad scheduler and consul resolver instead of docker-compose. Other servers are provided by the DNS resolver that resolves names like admin.service.consul or webmail.service.consul. These names needs to be configurable. 7 years ago			- ``HOST_WEBMAIL``: the container that is running the webmail (default: ``webmail``)
			- ``HOST_WEBDAV``: the container that is running the webdav server (default: ``webdav:5232``)
Add various environment variables to allow running outside of docker-compose 7 years ago			- ``HOST_REDIS``: the container that is running the redis daemon (default: ``redis``)
Resolve HOST_* to _ADDRESS only if _ADDRESS is not already set 5 years ago			- ``HOST_WEBMAIL``: the container that is running the webmail (default: ``webmail``)

Docs: Fix various build warnings: - /docs/configuration.rst:157: WARNING: Inline emphasis start-string without end-string. - /docs/configuration.rst:159: WARNING: Inline emphasis start-string without end-string. - /docs/configuration.rst:159: WARNING: Inline emphasis start-string without end-string. - /docs/configuration.rst:159: WARNING: Inline emphasis start-string without end-string. - /docs/rpi_build.rst: WARNING: document isn't included in any toctree 5 years ago			The startup scripts will resolve ``HOST_`` to their IP addresses and store the result in ``_ADDRESS`` for further use.
Resolve HOST_* to _ADDRESS only if _ADDRESS is not already set 5 years ago
Docs: Fix various build warnings: - /docs/configuration.rst:157: WARNING: Inline emphasis start-string without end-string. - /docs/configuration.rst:159: WARNING: Inline emphasis start-string without end-string. - /docs/configuration.rst:159: WARNING: Inline emphasis start-string without end-string. - /docs/configuration.rst:159: WARNING: Inline emphasis start-string without end-string. - /docs/rpi_build.rst: WARNING: document isn't included in any toctree 5 years ago			Alternatively, ``_ADDRESS`` can directly be set. In this case, the values of ``_ADDRESS`` is kept and not
Resolve HOST_* to _ADDRESS only if _ADDRESS is not already set 5 years ago			`resolved. This can be used to rely on DNS based service discovery with changing services IP addresses.`
Docs: Fix various build warnings: - /docs/configuration.rst:157: WARNING: Inline emphasis start-string without end-string. - /docs/configuration.rst:159: WARNING: Inline emphasis start-string without end-string. - /docs/configuration.rst:159: WARNING: Inline emphasis start-string without end-string. - /docs/configuration.rst:159: WARNING: Inline emphasis start-string without end-string. - /docs/rpi_build.rst: WARNING: document isn't included in any toctree 5 years ago			When using ``*_ADDRESS``, the hostnames must be full-qualified hostnames. Otherwise nginx will not be able to
Resolve HOST_* to _ADDRESS only if _ADDRESS is not already set 5 years ago			`resolve the hostnames.`
Parametrize hosts Allows to use mailu without docker-compose when hostnames are not set up by docker itself but provided via a separate resolver. Use case: use mailu using nomad scheduler and consul resolver instead of docker-compose. Other servers are provided by the DNS resolver that resolves names like admin.service.consul or webmail.service.consul. These names needs to be configurable. 7 years ago
Add various environment variables to allow running outside of docker-compose 7 years ago