From 77e3fc0ebcd7ac4970e8b05f5e8fa9cd5d97992c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20M=C3=B6hlmann?= Date: Thu, 11 Oct 2018 18:14:37 +0300 Subject: [PATCH] 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 --- docs/compose/setup.rst | 57 ++++++++++++++++++++++++++++++------------ docs/configuration.rst | 10 +++++++- docs/dns.rst | 2 ++ docs/setup.rst | 7 +++--- 4 files changed, 55 insertions(+), 21 deletions(-) diff --git a/docs/compose/setup.rst b/docs/compose/setup.rst index 8759e2f1..d4fb8014 100644 --- a/docs/compose/setup.rst +++ b/docs/compose/setup.rst @@ -26,35 +26,60 @@ for the ``VERSION_TAG`` branch, use: wget https://mailu.io/VERSION_TAG/_downloads/docker-compose.yml wget https://mailu.io/VERSION_TAG/_downloads/.env -Then open the ``.env`` file to setup the mail server. Modify the ``ROOT`` setting -to match your setup directory if different from ``/mailu``. +Important configuration variables +--------------------------------- -Modify the ``VERSION`` configuration in the ``.env`` file to reflect the version you picked. +Open the ``.env`` file and review the following variable settings: -Set the common configuration values ------------------------------------ +- Change ``ROOT`` if you have your setup directory in a different location then ``/mailu``. +- Check ``VERSION`` to reflect the version you picked. (``master`` or ``1.5``). -Open the ``.env`` file and set configuration settings after reading the configuration -documentation. Some settings are specific to the Docker Compose setup. +Make sure to read the comments in the file and instructions from the :ref:`common_cfg` section. -Modify ``BIND_ADDRESS4`` to match the public IP address assigned to your server. -This address should be configured on one of the network interfaces of the server. -If the address is not configured directly (NAT) on any of the network interfaces or if -you would simply like the server to listen on all interfaces, use ``0.0.0.0``. - -Modify ``BIND_ADDRESS6`` to match the public IPv6 address assigned to your server. -The behavior is identical to ``BIND_ADDRESS4``. +TLS certificates +```````````````` Set the ``TLS_FLAVOR`` to one of the following values: - ``cert`` is the default and requires certificates to be setup manually; -- ``letsencrypt`` will use the Letsencrypt! CA to generate automatic ceriticates; +- ``letsencrypt`` will use the *Letsencrypt!* CA to generate automatic ceriticates; - ``mail`` is similar to ``cert`` except that TLS will only be served for emails (IMAP and SMTP), not HTTP (use it behind reverse proxies); - ``mail-letsencrypt`` is similar to ``letsencrypt`` except that TLS will only be served for emails (IMAP and SMTP), not HTTP (use it behind reverse proxies); -- ``notls`` will disable TLS, this is not recommended except for testing. +- ``notls`` will disable TLS, this is not recommended except for testing + +.. note:: + + When using *Letsencrypt!* you have to make sure that the DNS ``A`` and ``AAAA`` records for the + all hostnames mentioned in the ``HOSTNAMES`` variable match with the ip adresses of you server. + Or else certificate generation will fail! See also: :ref:`dns_setup`. + +Bind address +```````````` + +Modify ``BIND_ADDRESS4`` and ``BIND_ADDRESS6`` to match the public IP addresses assigned to your server. For IPv6 you will need the ```` scope address. + +You can find those addresses by running the following: + +.. code-block:: bash + + [root@mailu ~]$ ifconfig eth0 + eth0: flags=4163 mtu 1500 + inet 125.189.138.127 netmask 255.255.255.0 broadcast 5.189.138.255 + inet6 fd21:aab2:717c:cc5a::1 prefixlen 64 scopeid 0x0 + inet6 fe2f:2a73:43a8:7a1b::1 prefixlen 64 scopeid 0x20 + ether 00:50:56:3c:b2:23 txqueuelen 1000 (Ethernet) + RX packets 174866612 bytes 127773819607 (118.9 GiB) + RX errors 0 dropped 0 overruns 0 frame 0 + TX packets 19905110 bytes 2191519656 (2.0 GiB) + TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 + +If the address is not configured directly (NAT) on any of the network interfaces or if +you would simply like the server to listen on all interfaces, use ``0.0.0.0`` and ``::``. Note that running is this mode is not supported and can lead to `issues`_. + +.. _issues: https://github.com/Mailu/Mailu/issues/641 Enable optional features ------------------------ diff --git a/docs/configuration.rst b/docs/configuration.rst index 62b6f34e..cab30072 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -1,12 +1,20 @@ Mailu configuration settings ============================ +.. _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. +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 diff --git a/docs/dns.rst b/docs/dns.rst index 3d94aecb..d2fd4131 100644 --- a/docs/dns.rst +++ b/docs/dns.rst @@ -1,3 +1,5 @@ +.. _dns_setup: + Setting up your DNS =================== diff --git a/docs/setup.rst b/docs/setup.rst index d7d0cc13..9771f886 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -32,7 +32,7 @@ user. Make sure you complete the requirements for the flavor you chose. You should also have at least a DNS hostname and a DNS name for receiving emails. Some instructions are provided on the matter in the article -[Setup your DNS](dns). +:ref:`dns_setup`. .. _`MFAshby's fork`: https://github.com/MFAshby/Mailu @@ -68,10 +68,9 @@ Make sure that you test properly before going live! - Try to receive an email from an external service - Check the logs (``docker-compose logs -f servicenamehere``) to look for warnings or errors -- Use an open relay checker like `mailradar`_ +- Use an open relay checker like `mxtoolbox`_ to ensure you're not contributing to the spam problem on the internet. - All tests there should result in "Relay denied". - If using DMARC, be sure to check the reports you get to verify that legitimate email is getting through and forgeries are being properly blocked. - .. _mailradar: http://www.mailradar.com/openrelay/ + .. _mxtoolbox: https://mxtoolbox.com/diagnostic.aspx