Merge pull request #95 from NethServer/fix-mail-migration

Add Mail app information for migration

email_notifications.rst

@@ -1,13 +1,50 @@
 .. _smarthost-section:
 
+.. _email-notifications:
+
 ===================
 Email notifications
 ===================
 
-Many applications require access to an SMTP server to send mail.
+Many applications, such as Nextcloud and Mattermost, require SMTP server
+configuration to send notification messages to users and service
+administrators.
 
 You can configure the same SMTP server for all installed applications by
 accessing the ``Email notifications`` card inside the ``Settings`` page.
 
-Then, enable the feature by clicking on ``Send notifications with an SMTP
+To enable the feature, click on ``Send notifications with an SMTP
 server`` and fill the required details.
+
+If a Mail application instance is already installed in the cluster, choose
+the ``Use Mail app instance`` option. Then refer to the section
+:ref:`relay-rules-section` for further information about the configuration
+of Mail.
+
+Instead, choose ``Manual configuration`` to specify SMTP server parameters
+in this form. Available fields are:
+
+- **SMTP server**: The host name or IP address of the SMTP server
+
+- **SMTP port number**: TCP port number of the server. Common values are
+  587, 25, 465, 2525.
+
+- **SMTP encryption**: Encryption used by the server. TLS is a widely used
+  encryption protocol that encrypts a connection from the moment it is
+  established. STARTTLS is the standard encryption method for SMTP. If
+  both the client and server support it, the connection is encrypted after
+  both sides agree to use it.
+
+- **Verify the TLS certificate**: If encryption is used, this switch
+  controls if the certificate used to encrypt the connection must be
+  signed by a trusted authority or not. If the server presents a
+  self-signed certificate, turn off this switch to accept it.
+
+- **Username** and **Password**: If the server requires SMTP
+  authentication, fill the credential fields; otherwise leave them blank.
+
+After saving the settings, a SMTP connection to validate the form
+parameters is immediately started. In some cases, validation is
+successful, but messages may still fail to be delivered. It is recommended
+to check that individual applications can successfully send messages with
+the new settings.

migration.rst

@@ -224,12 +224,49 @@ Password policy settings (strength and expiration) are not migrated. They
 must be enabled under the domain settings of the ``Domains and users``
 page. See also :ref:`password-policy-section`.
 
+.. _mail-migration-section:
+
+Mail
+====
+
+The Migration Procedure preserves both data and configurations of NS7
+Email application, unless stated differently in this section or in
+:ref:`config-excluded-migration`.
+
+Mail messages are copied to NS8 with Rsync. After :guilabel:`Finish
+migration` is clicked, some time-consuming operations are executed.
+
+- **IMAP ACL Format Conversion**: The user and group name format in IMAP
+  ACLs is modified by removing the domain suffix. For example, an ACL entry
+  referring to IMAP user `john.doe@server.example.org` becomes `john.doe`.
+  IMAP login still accepts both formats.
+
+- **Quota Recalculation**: If IMAP quota is enabled, mailbox sizes are
+  recalculated in the background. During this time, disk usage of mailboxes
+  might not be available.
+
+- **Messages and Attachments Reindexing**: The full-text search engine of
+  NS8 runs in the background to reindex all messages and attachments. During
+  this time, full-text searches might not work. To check if the reindexing
+  process is still running, use the command ``pgrep dovecot-index``.
+
+Remember to update the DNS records or transfer the IP address to the NS8
+node at the end of the migration.
+
+Smart host
+----------
+
+The NS7 system smart host configuration is converted to a :ref:`default
+relay rule <relay-rules-section>`. The NS8 Mail application is then
+configured as the SMTP server for every application in the cluster: see
+:ref:`email-notifications`.
+
 .. _getmail_migration-section:
 
 POP3 connector
-==============
+--------------
 
-The migration involves transferring POP3 Connector settings to NS8 Imapsync module, together with Email application.
+The migration involves transferring POP3 Connector settings to NS8 :ref:`Imapsync module <imapsync-section>`, together with Email application.
 Configurations of accounts using the IMAP protocol are translated to working Imapsync tasks.
 For accounts using POP3, it is necessary to review the settings and commence synchronization manually.
 
@@ -263,10 +300,20 @@ Example for adding WebTop routes:
    * ``/.well-known``
    * ``/webtop-dav``
 
+.. _config-excluded-migration:
+
 Configurations excluded from migration
 ======================================
 
 The following configurations will not be migrated:
 
-- custom templates
-- account provider password policy settings (see :ref:`migrate-account-provider`)
+- Custom templates.
+
+- Account provider password policy settings (see
+  :ref:`migrate-account-provider`).
+
+- System smart host, if the NS7 Email app is not installed or is not
+  migrated.
+
+- In NS7 Email app, the setting ``Forward a copy of all messages``, formerly known as
+  ``Always send a copy (Bcc)``, is not migrated.