From 943b9d366b3c04dff22337644608dc1d24e69b0c Mon Sep 17 00:00:00 2001 From: Antoine Nguyen Date: Wed, 26 Apr 2023 11:52:46 +0200 Subject: [PATCH] Updated doc --- doc/configuration.rst | 69 ++++++++++++++++++++++++++++++++- doc/features/dmarc.rst | 64 ------------------------------ doc/features/imap-migration.rst | 55 -------------------------- doc/features/pdfcredentials.rst | 14 ------- doc/index.rst | 24 ------------ doc/moving.rst | 51 +++++++++++++++++++++++- 6 files changed, 117 insertions(+), 160 deletions(-) delete mode 100644 doc/features/dmarc.rst delete mode 100644 doc/features/imap-migration.rst delete mode 100644 doc/features/pdfcredentials.rst diff --git a/doc/configuration.rst b/doc/configuration.rst index c21709d0e..ee4368555 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -209,7 +209,7 @@ Custom new admin sub-url You can edit the new admin sub-url (by default it is `/new-admin`). -To do so, open the :file:`settings.py` file and add (or uncomment) +To do so, open the :file:`settings.py` file and add (or uncomment) ``NEW_ADMIN_URL`` variable. This variable must contain a relative url without initial and last `'/'`. For example:: @@ -577,3 +577,70 @@ night:: The default behaviour is to disable accounts. You can delete them using the ``--delete`` option. + +************* +DMARC reports +************* + +.. _dmarcdoc: + +A set of tools to use DMARC through Modoboa. + +This feature is still in BETA stage, for now it only parses XML aggregated +reports and generate visual reports on a per-domain basis. + +Installation +============ + +.. note:: + + modoboa-installer can automatically set it up for you. + +Make sure to install the following additional system package according to your distribution: + ++-----------------+ +| Debian / Ubuntu | ++=================+ +| libmagic1 | ++-----------------+ + ++------------+ +| CentOS | ++============+ +| file-devel | ++------------+ + + +Integration with Postfix +======================== + +A management command is provided to automatically parse DMARC +aggregated reports (rua) and feed the database. The execution of this +command can be automated with the definition of a postfix service and +a custom transport table. + +First, declare a new service in ``/etc/postfix/master.cf``:: + + dmarc-rua-parser unix - n n - - pipe + flags= user=vmail:vmail argv= /manage.py import_aggregated_report --pipe + +Define a new transport table inside ``/etc/postfix/main.cf``:: + + transport_maps = + hash:/etc/postfix/dmarc_transport + # other transport maps... + +Create a file called ``/etc/postfix/dmarc_transport`` with the following content:: + + dmarc-rua-parser: + +.. note:: + You must not declare this email address as an identity (user account or alias), else DMARC reports will be directed to your mailbox and won't be parsed. + +Hash the file using the following command:: + + $ postmap /etc/postfix/dmarc_transport + +Finally, reload postfix:: + + $ service postfix reload diff --git a/doc/features/dmarc.rst b/doc/features/dmarc.rst deleted file mode 100644 index 9c2b268ad..000000000 --- a/doc/features/dmarc.rst +++ /dev/null @@ -1,64 +0,0 @@ -modoboa-dmarc -============= - -.. _dmarcdoc: - -A set of tools to use DMARC through Modoboa. - -This feature is still in BETA stage, for now it only parses XML aggregated -reports and generate visual reports (using c3.js) on a per-domain basis. - -Installation ------------- - -.. note:: - modoboa-installer can automatically set it up for you. - -Make sure to install the following additional system package according to your distribution: - -+-----------------+ -| Debian / Ubuntu | -+=================+ -| libmagic1 | -+-----------------+ - -+------------+ -| CentOS | -+============+ -| file-devel | -+------------+ - - -Integration with Postfix ------------------------- - -A management command is provided to automatically parse DMARC -aggregated reports (rua) and feed the database. The execution of this -command can be automated with the definition of a postfix service and -a custom transport table. - -First, declare a new service in ``/etc/postfix/master.cf``:: - - dmarc-rua-parser unix - n n - - pipe - flags= user=vmail:vmail argv= /manage.py import_aggregated_report --pipe - -Define a new transport table inside ``/etc/postfix/main.cf``:: - - transport_maps = - hash:/etc/postfix/dmarc_transport - # other transport maps... - -Create a file called ``/etc/postfix/dmarc_transport`` with the following content:: - - dmarc-rua-parser: - -.. note:: - You must not declare this email address as an identity (user account or alias), else DMARC reports will be directed to your mailbox and won't be parsed. - -Hash the file using the following command:: - - $ postmap /etc/postfix/dmarc_transport - -Finally, reload postfix:: - - $ service postfix reload diff --git a/doc/features/imap-migration.rst b/doc/features/imap-migration.rst deleted file mode 100644 index ad062c266..000000000 --- a/doc/features/imap-migration.rst +++ /dev/null @@ -1,55 +0,0 @@ -IMAP Migration for Modoboa -=========================== - -.. _imap: - -A simple `Modoboa `_ extension which provides a -way to transfer your account from another provider/server -provided that you have IMAP access to it. - - -Configuration -------------- - -The plugin configuration is done from the admin panel (*Modoboa > -Parameters > IMAP Migration*). And you have a specific tab to configure -your migration that is visible for SuperAdmins. -These settings are only available on the new admin interface. - -.. warning:: - - You must have enabled "Auto create domain" in modoboa parameters for this extension to work. - -This extension can create `OfflineIMAP `_ -configuration file with the command: - -.. sourcecode:: bash - - > python manage.py generate_offlineimap_config - -You then need to setup `OfflineIMAP `_. - .. -This will sync back-and-forth user mailbox. - - -Providers ---------- - -Mail server can host multiple domains so the provider address -may be different from the domain part of your email address. - -Associated domain is the domain part of the email address. -You can leave "Local Domain" blank if you keep the same domain. -This domain will be auto-created if needed. -you must create the domain beforhand if you want to migrate an account -from `user@domain1.tld` to `user@domain2.tld`. - - -Migrations ----------- - -Migrations are automatically handled when providers have been configured. -Users use their old credential to log and the account is automatically created. -They shall use the new domain on next logins if a local domain was set in the provider configuration. -If you have installed OfflineIMAP, you may delete the migration to stop mailbox sync. -SuperAdmins may check migrations in the `IMAP Migration` tab. diff --git a/doc/features/pdfcredentials.rst b/doc/features/pdfcredentials.rst deleted file mode 100644 index 2b897d4a3..000000000 --- a/doc/features/pdfcredentials.rst +++ /dev/null @@ -1,14 +0,0 @@ -PDF credentials for Modoboa -=========================== - -.. _pdfc: - -A simple `Modoboa `_ extension which provides a -way to download PDF documents containing users credentials. - - -Configuration -------------- - -All the configuration is done from the admin panel (*Modoboa > -Parameters > PDF Credentials*). diff --git a/doc/index.rst b/doc/index.rst index cb9a85f89..6d00c2965 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -16,30 +16,6 @@ Modoboa is a mail hosting and management platform including a modern and simplified Web User Interface designed to work with `Postfix `_ and `Dovecot `_. - -It provides built-in features by default : - - -+---------------------------------------------------------+-------------------------+------------------------------------------------------+ -|Name |Description |Documentation | -| | | | -| | | | -| | | | -+=========================================================+=========================+======================================================+ -|modoboa-dmarc |A set of tools to use |:ref:`modoboa_dmarc Documentation ` | -| |`DMARC | | -| |`_ | | -+---------------------------------------------------------+-------------------------+------------------------------------------------------+ -|modoboa-pdfcredentials |Generate PDF documents |:ref:`modoboa_pdfcredentials Documentation ` | -| |containing account | | -| |credentials | | -+---------------------------------------------------------+-------------------------+------------------------------------------------------+ -|modoboa-imap-migration |Transfer accounts from |:ref:`modoboa_imap-migration Documentation ` | -| |other mail server | | -| |automatically | | -+---------------------------------------------------------+-------------------------+------------------------------------------------------+ - - And it is extensible by nature and comes with a lot of additional extensions: +---------------------------------------------------------+-------------------------+------------------------------------------------------+ diff --git a/doc/moving.rst b/doc/moving.rst index 40c921720..e50a32257 100644 --- a/doc/moving.rst +++ b/doc/moving.rst @@ -8,9 +8,56 @@ following tools could help you. Using IMAP protocol =================== -A built-in tool to migrate accounts from an old server using the IMAP protocol. +.. _imap: + +`Modoboa `_ provides a way to transfer your +account from another provider/server using an IMAP access. + +Configuration +------------- + +The configuration is done from the admin panel (*Modoboa > +Parameters > IMAP Migration*). And you have a specific tab to configure +your migration that is visible for SuperAdmins. +These settings are only available on the new admin interface. + +.. warning:: + + You must have enabled **Auto create domain** in modoboa parameters for this extension to work. + +This extension can create `OfflineIMAP `_ +configuration file with the command: + +.. sourcecode:: bash + + > python manage.py generate_offlineimap_config + +You then need to setup `OfflineIMAP `_. + +This will sync back-and-forth user mailbox. + +Providers +--------- + +Mail server can host multiple domains so the provider address +may be different from the domain part of your email address. + +Associated domain is the domain part of the email address. +You can leave "Local Domain" blank if you keep the same domain. +This domain will be auto-created if needed. +you must create the domain beforhand if you want to migrate an account +from `user@domain1.tld` to `user@domain2.tld`. + + +Migrations +---------- + +Migrations are automatically handled when providers have been configured. +Users use their old credential to log and the account is automatically created. +They shall use the new domain on next logins if a local domain was set in the provider configuration. +If you have installed OfflineIMAP, you may delete the migration to stop mailbox sync. +SuperAdmins may check migrations in the `IMAP Migration` tab. -:ref:`Know more `. From postfixadmin =================