diff --git a/admin_manual/groupware/mail.rst b/admin_manual/groupware/mail.rst index fc093e977b6..73cbbaf8868 100644 --- a/admin_manual/groupware/mail.rst +++ b/admin_manual/groupware/mail.rst @@ -2,6 +2,119 @@ Mail ==== +Configuration +------------- + +Anti-abuse alerts +^^^^^^^^^^^^^^^^^ + +The app can write alerts to the logs when users send messages to a high number of recipients or sends a high number of messages for a short period of time. These events might indicate that the account is abused for sending spam messages. + +To enable anti-abuse alerts, you'll have to set a few configuration options :doc:`via occ <../occ_command>` . + +:: + + # Turn alerts on + occ config:app:set mail abuse_detection --value=on + # Turn alerts off + occ config:app:set mail abuse_detection --value=off + + # Alert when 50 or more recipients are used for one single message + occ config:app:set mail abuse_number_of_recipients_per_message_threshold --value=50 + + # Alerts can be configured for three intervals: 15m, 1h and 1d + # Alert when more than 10 messages are sent in 15 minutes + occ config:app:set mail abuse_number_of_messages_per_15m --value=10 + # Alert when more than 30 messages are sent in one hour + occ config:app:set mail abuse_number_of_messages_per_1h --value=30 + # Alert when more than 100 messages are sent in one day + occ config:app:set mail abuse_number_of_messages_per_1d --value=100 + +Attachment size limit +^^^^^^^^^^^^^^^^^^^^^ + +Admins can prevent users from attaching large attachments to their emails. Users will be asked to use link shares instead. + +:: + + 'app.mail.attachment-size-limit' => 3*1024*1024, + +The unit is bytes. The example about with limit to 3MB attachments. The default is 0 bytes which means no upload limit. + +Background sync interval +^^^^^^^^^^^^^^^^^^^^^^^^ + +Configure how often Mail keeps users' mailboxes updated in the background in seconds. Defaults to 3600, minimum 300. + +:: + + 'app.mail.background-sync-interval' => 7200, + +Disable TLS verification for IMAP/SMTP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Turn off TLS verification for IMAP/SMTP. This happens globally for all accounts and is only needed in edge cases like with email servers that have a self-signed certificate. + +:: + + 'app.mail.verify-tls-peer' => false + +Google OAuth +^^^^^^^^^^^^ + +This app can allow users to connect their Google accounts with OAuth. This makes it possible to use accounts without 2FA or app password. + +1. `Create authorization credentials `_. You will receive a client ID and a client secret. +2. Open the Nextcloud settings page. Navigate to *Groupware* and scroll down to *Gmail integration*. Enter and save the client ID and client secret. + +Local IMAP and SMTP servers +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, Nextcloud does not allow local hostnames and IP addresses as remote servers. This includes IMAP, SMTP and Sieve servers +like ``localhost``, ``mx.local`` and ``10.0.0.3``. This check can be disabled with via ``config/config.php``. + +:: + + 'allow_local_remote_servers' => true, + +Timeouts +^^^^^^^^ + +Depending on your mail host, it may be necessary to increase your IMAP and/or SMTP timeout threshold. +Currently IMAP defaults to 5 seconds and SMTP defaults to 20 seconds. They can be changed as follows: + +IMAP timeout +~~~~~~~~~~~~ + +:: + + 'app.mail.imap.timeout' => 5 + +SMTP timeout +~~~~~~~~~~~~ + +:: + + 'app.mail.smtp.timeout' => 20 + +Sieve timeout +~~~~~~~~~~~~~ + +:: + + 'app.mail.sieve.timeout' => 5 + +Use php-mail for sending mail +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. warning:: Support for using php-mail was removed in version 4.4 of the mail app! + +You can use the php-mail function to send mails. This is needed for some web hosters (1&1 (1und1)). + +:: + + 'app.mail.transport' => 'php-mail' + Account delegation ------------------ @@ -25,15 +138,13 @@ XOAUTH2 Authentication with Microsoft Azure AD The Mail app supports XOAUTH2 authentication with hosted Microsoft Outlook accounts. An app has to be registered in the Microsoft Azure web interface and its credentials have to be supplied to the Nextcloud instance. You can find relevant settings in the Groupware section of the admin settings. -Step 1: Open the Azure AD Dashboard -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Step 1: Open the Azure AD Dashboard** Visit the `Azure portal `_ and navigate to the Azure AD dashboard. .. figure:: images/azure_xoauth2/1.png -Step 2: Create a new app registration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Step 2: Create a new app registration** .. figure:: images/azure_xoauth2/2.png @@ -41,15 +152,13 @@ Chose a name, allow organizational and personal Microsoft accounts. Configure a .. figure:: images/azure_xoauth2/3.png -Step 3: Copy the client ID -~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Step 3: Copy the client ID** This ID will be needed later for the Nextcloud settings. .. figure:: images/azure_xoauth2/4.png -Step 4: Create a new client secret -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Step 4: Create a new client secret** .. figure:: images/azure_xoauth2/5.png @@ -57,15 +166,13 @@ Chose a descriptive name for the secret and set the an appropriate expiration da .. figure:: images/azure_xoauth2/6.png -Step 5: Copy the client secret -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Step 5: Copy the client secret** Copy the client secret manually or by clicking on the copy button. You can find it in the value column. The secret will also be needed later for the Nextcloud settings. .. figure:: images/azure_xoauth2/7.png -Step 6: Configure Nextcloud -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Step 6: Configure Nextcloud** Open the groupware settings in the Nextcloud admin settings and fill in the client ID and client secret. Leave the tenant ID as is (common). You can also find the redirect URI here. Click on save to proceed. @@ -73,8 +180,7 @@ Open the groupware settings in the Nextcloud admin settings and fill in the clie .. figure:: images/azure_xoauth2/8.png -Step 7: Connect Microsoft Outlook accounts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Step 7: Connect Microsoft Outlook accounts** Congratulations! You are now able to use hosted Microsoft Outlook accounts in the Mail app. Use your Microsoft account email and any password when adding your account. The password will be discarded and you will be prompted with a Microsoft consent popup to log in to your account. diff --git a/admin_manual/groupware/troubleshooting.rst b/admin_manual/groupware/troubleshooting.rst index c7b1331531b..0c430f74861 100644 --- a/admin_manual/groupware/troubleshooting.rst +++ b/admin_manual/groupware/troubleshooting.rst @@ -39,3 +39,243 @@ C. **Delete Specific Unshares:** **Why Isn't there an Automated Migration to Correct the Problem?** Unsharing a calendar is a feature, and with the given information, we cannot determine if a calendar was unshared on purpose or as a result of the bug. + +Mail +#### + +Autoconfig for your mail domain fails +************************************* + +If autoconfiguration for your domain fails, you can create an autoconfig file and place it as ``https://autoconfig.yourdomain.tld/mail/config-v1.1.xml``. For more information please refer to `Mozilla's documentation `_. + + +Database insert problems on MySQL +********************************* + +If the mail app fails to insert new rows for messages (`oc_mail_messages`), recipients (`oc_mail_recipients`) or similar tables, you are possibly not using the 4 byte support. + +See :doc:`../configuration_database/mysql_4byte_support` for how to update your database configuration. + + +Export threading data +********************* + +If you encounter an issue with threading, e.g. messages that belong to the same conversation thread don't show up as one, you can export the data the algorithm will use to build threads. We are dealing with sensitive data here, but the command will optionally redact the data with the ``--redact`` switch. The exported data will then only keep the original database IDs, the rest of the data is randomized. This format does not the export message details, it still contains metadata about how many messages you have and how they relate. Please consider this before posting the data online. + +:: + + sudo -E -u www-data php occ mail:account:export-threads 1393 + +.. note:: 1393 represents the :ref:`account ID `. + +The output will look similar to this:: + + [ + { + "subject": "83379f9bc36915d5024de878386060b5@redacted", + "id": "2def0f3597806ecb886da1d9cc323a7c@redacted", + "references": [], + "databaseId": 261535 + }, + { + "subject": "Re: 1d4725ae1ac4e4798b541ca3f3cdce6e@redacted", + "id": "ce9e248333c44a5a64ccad26f2550f95@redacted", + "references": [ + "bc95cbaff3abbed716e1d40bbdaa58a0@redacted", + "8651a9ac37674907606c936ced1333d7@redacted", + "4a87e94522a3cf26dba8977ae901094d@redacted", + "a3b30430b1ccb41089170eecbe315d3a@redacted", + "8e9f60369dce3d8b2b27430bd50ec46d@redacted", + "46cfa6e729ff329e6ede076853154113@redacted", + "079e7bc89d69792839a5e1831b1cbc80@redacted", + "079e7bc89d69792839a5e1831b1cbc80@redacted" + ], + "databaseId": 262086 + }, + { + "subject": "Re: 1d4725ae1ac4e4798b541ca3f3cdce6e@redacted", + "id": "8dd0e0ef2f7ab100b75922489ff26306@redacted", + "references": [ + "bc95cbaff3abbed716e1d40bbdaa58a0@redacted", + "8651a9ac37674907606c936ced1333d7@redacted", + "4a87e94522a3cf26dba8977ae901094d@redacted", + "a3b30430b1ccb41089170eecbe315d3a@redacted", + "8e9f60369dce3d8b2b27430bd50ec46d@redacted", + "46cfa6e729ff329e6ede076853154113@redacted", + "079e7bc89d69792839a5e1831b1cbc80@redacted", + "ce9e248333c44a5a64ccad26f2550f95@redacted", + "ce9e248333c44a5a64ccad26f2550f95@redacted" + ], + "databaseId": 262087 + } + ] + +It's recommended practice to pipe the export into a file, which you can later share with the Mail app community and developers:: + + sudo -E -u www-data php occ mail:account:export-threads 1393 | gzip -c > /tmp/nextcloud-mail-threads-1393.json.gz + + +.. _mail_get_account_ids_groupware: + +Get account IDs +*************** + +For many troubleshooting instructions you need to know the `id` of a mail account. You can acquire this through the database, but it's also possible to utilize the account export command of :doc:`occ <../occ_command>` if you know the UID of the user utilizing the mail account:: + + sudo -E -u www-data php occ mail:account:export user123 + +The output will look similar to this:: + + Account 1393: + - E-Mail: christoph@domain.com + - Name: Christoph Wurst + - IMAP user: christoph + - IMAP host: mx.domain.com:993, security: ssl + - SMTP user: christoph + - SMTP host: mx.domain.com:587, security: tls + +In this example, ``1393`` is the `account ID`. + + +Issues connecting to Outlook.com +******************************** + +If you can not access your Outlook.com account try to enable the `Two-Factor Verification `_ and set up an `app password `_, which you then use for the Nextcloud Mail app. + + +Logging the IMAP/SMTP/Sieve connections +*************************************** + +The Nextcloud Mail app offers an extensive logging system to make it easier identifying and tracking down bugs. As this may include sensitive data, be sure to remove or mask them before posting them publicly. + +Per mail account +~~~~~~~~~~~~~~~~ +.. versionadded:: 5.1.0 + +Starting with version 5.1.0 of the mail app, you can enable logging of outgoing IMAP/SMTP/Sieve connections limited to a specific mail account. As that saves a lot of resources on your system, this is the preferred method for debugging issues regarding IMAP/SMTP/Sieve connections. + +First, you need to get the accountId for the mail account you like to enable debug logging on. Please see :ref:`mail_get_account_ids_groupware` for more. + +Once you know the accountId of the mail account in question, you can use it to enable debug logging by running the following command on the server: + +:: + + sudo -E -u www-data php occ mail:account:debug --on + +All subsequent outgoing connections made by the mail app will then be written to the ``data`` directory. The file naming follows the following format: ``mail-{{userId}}-{{accountId}}-{{protocol}}.log`` (e.g., `mail-admin-49-imap.log`). + +The debug logging for that specific account can be disabled once you've collected the necessary data by running the following command on the server: + +:: + + occ mail:account:debug --off + +Globally +~~~~~~~~ +This enables logging of the IMAP/SMTP/Sieve connections for **all** mail accounts configured on the server. This should be used with caution as it can put a lot of strain on large environments. + +.. versionadded:: 5.1.0 + +To enable the global debug logging on versions 5.1.0 and above, just run the following command on the server: + +:: + + sudo -E -u www-data php occ config:system:set app.mail.debug --value true --type bool + +All subsequent outgoing connections made by the mail app will then be written to the ``data`` directory. The file naming follows the following format: ``mail-{{userId}}-{{accountId}}-{{protocol}}.log`` (e.g., `mail-admin-49-imap.log`). + +The global debug logging can be disabled once you've collected the necessary data by running the following command on the server: + +:: + + sudo -E -u www-data php occ config:system:set app.mail.debug --value false --type bool + +.. note:: The following steps only apply to version 1.6.2 up to 5.0.8. Restrict logging of outgoing connections to a specific mail account is not available there. +.. versionadded:: 1.6.2 + +To enable the global debug logging, it's necessary to enable both the debug mode as well as debug logging for the whole nextcloud instance by running the following commands on the server: + +:: + + sudo -E -u www-data php occ config:system:set debug --value true --type bool + sudo -E -u www-data php occ config:system:set loglevel --value 0 --type int + +All subsequent outgoing connections made by the mail app will then be written to the ``data`` directory. The file naming follows the following format: ``horde_{{protocol}}.log`` (e.g., `horde_imap.log`). + +Once you've collected the necessary data, it's highly recommended to disable the debug mode as well as resetting the loglevel to the default value by running the following commands: + +:: + + sudo -E -u www-data php occ config:system:set debug --value false --type bool + sudo -E -u www-data php occ config:system:set loglevel --value 2 --type int + + +Timeout and other connectivity issues +************************************* + +You can use OpenSSL to test and benchmark the connection from your nextcloud host to the IMAP/SMTP host.:: + + openssl s_time -connect imap.domain.tld:993 + +The output should look similar to this:: + + Collecting connection statistics for 30 seconds + *************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************** + + 483 connections in 0.94s; 513.83 connections/user sec, bytes read 0 + 483 connections in 31 real seconds, 0 bytes read per connection + + + Now timing with session id reuse. + starting + ***************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************** + + 497 connections in 0.97s; 512.37 connections/user sec, bytes read 0 + 497 connections in 31 real seconds, 0 bytes read per connection + + +Manual account synchronization and threading +******************************************** + +To troubleshoot synchronization or threading problems it's helpful to run the sync from the command line while the user does not use the web interface (reduces chances of a conflict):: + + sudo -E -u www-data php occ mail:account:sync -vvv 1393 + +.. note:: 1393 represents the :ref:`account ID `. + +The command offers a ``--force`` option. Use it wisely as it doesn't perform the same path a typical web triggered sync request would do. + +The output will look similar to this:: + + [debug] Skipping mailbox sync for Archive + [debug] Skipping mailbox sync for Archive.2020 + [debug] partial sync 1393:Drafts - get all known UIDs took 0s + [debug] partial sync 1393:Drafts - get new messages via Horde took 0s + [debug] partial sync 1393:Drafts - persist new messages took 0s + [debug] partial sync 1393:Drafts - get changed messages via Horde took 0s + [debug] partial sync 1393:Drafts - persist changed messages took 0s + [debug] partial sync 1393:Drafts - get vanished messages via Horde took 0s + [debug] partial sync 1393:Drafts - persist new messages took 0s + [debug] partial sync 1393:Drafts took 0s + [debug] partial sync 1393:INBOX - get all known UIDs took 0s + [debug] partial sync 1393:INBOX - get new messages via Horde took 0s + [debug] partial sync 1393:INBOX - classified a chunk of new messages took 1s + [debug] partial sync 1393:INBOX - persist new messages took 0s + [debug] partial sync 1393:INBOX - get changed messages via Horde took 1s + [debug] partial sync 1393:INBOX - persist changed messages took 0s + [debug] partial sync 1393:INBOX - get vanished messages via Horde took 0s + [debug] partial sync 1393:INBOX - persist new messages took 0s + [debug] partial sync 1393:INBOX took 2s + [debug] Skipping mailbox sync for Sent + [debug] Skipping mailbox sync for Sentry + [debug] Skipping mailbox sync for Trash + [debug] Account 1393 has 19417 messages for threading + [debug] Threading 19417 messages - build ID table took 1s + [debug] Threading 19417 messages - build root container took 0s + [debug] Threading 19417 messages - free ID table took 0s + [debug] Threading 19417 messages - prune containers took 0s + [debug] Threading 19417 messages - group by subject took 0s + [debug] Threading 19417 messages took 1s + [debug] Account 1393 has 9839 threads + [debug] Account 1393 has 0 messages with a new thread IDs + 62MB of memory used \ No newline at end of file diff --git a/user_manual/groupware/mail.rst b/user_manual/groupware/mail.rst index 1101902f5d9..1d7c1f925e6 100644 --- a/user_manual/groupware/mail.rst +++ b/user_manual/groupware/mail.rst @@ -519,3 +519,10 @@ The mail app offers two widgets designed for integration with Nextcloud's dashbo * Important mails: This widget shows emails that have been flagged as important. These widgets utilize the emails from the email accounts that are set up for your account. + +Keyboard shortcuts +------------------ + +The Mail app implements several keyboard shortcuts to speed up your experience. + +For a full list of the supported shortcuts, check out the Mail settings in your instance. \ No newline at end of file