From a8d74e9ebb27e06862855e4961ee1d84b9c31cce Mon Sep 17 00:00:00 2001 From: =Corey Hulen Date: Wed, 21 Oct 2015 11:31:22 -0700 Subject: WIP --- doc/install/Troubleshooting-Email.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 doc/install/Troubleshooting-Email.md diff --git a/doc/install/Troubleshooting-Email.md b/doc/install/Troubleshooting-Email.md new file mode 100644 index 000000000..0ddc807bb --- /dev/null +++ b/doc/install/Troubleshooting-Email.md @@ -0,0 +1,21 @@ + +change settings via system console + +known good settings for providers: +amazon ses +postfix +gmail +hotmail +sendgrid + +if you fill in a username/password you must use a secure connection like TLS or STARTTLS + +test connection +check error logs +search for specific smtp errors like '555' with your provider. + +Adv Email trouble shooting +from the machine (if docker then exec) +run telnet to make sure host/port is correct +issue ELHO cmd to see if you can see stuff like STARTTSL + -- cgit v1.2.3-1-g7c22 From 9172ab33e4776a10f81dc523c75a87f737bcfd01 Mon Sep 17 00:00:00 2001 From: =Corey Hulen Date: Wed, 21 Oct 2015 15:48:18 -0700 Subject: Updating email guide --- doc/install/SMTP-Email-Setup.md | 55 ++++++++++++++++++++++++++++++++---- doc/install/Troubleshooting-Email.md | 44 +++++++++++++++++++++++------ 2 files changed, 85 insertions(+), 14 deletions(-) diff --git a/doc/install/SMTP-Email-Setup.md b/doc/install/SMTP-Email-Setup.md index 4e06d2f99..2100130ee 100644 --- a/doc/install/SMTP-Email-Setup.md +++ b/doc/install/SMTP-Email-Setup.md @@ -14,6 +14,7 @@ To enable email, configure an SMTP email service as follows: 3. Copy the `Server Name`, `Port`, `SMTP Username`, and `SMTP Password` for Step 2 below. 4. From the `Domains` menu set up and verify a new domain, then enable `Generate DKIM Settings` for the domain. 5. Choose an sender address like `mattermost@example.com` and click `Send a Test Email` to verify setup is working correctly. + 2. **Configure SMTP settings** 1. Open the **System Console** by logging into an existing team and accessing "System Console" from the main menu. 1. Alternatively, if a team doesn't yet exist, go to `http://dockerhost:8065/` in your browser, create a team, then from the main menu click **System Console** @@ -29,15 +30,42 @@ To enable email, configure an SMTP email service as follows: 9. **SMTP Port**: `SMTP Port` from Step 1 10. **Connection Security**: `TLS (Recommended)` 11. Then click **Save** + 12. Then click **Test Connection** + 13. If the test failed please look in **OTHER** > **Logs** for any errors that look like `[EROR] /api/v1/admin/test_email ...` + +### Known Good Sample Settings + +##### Amazon SES +* Set **SMTP Username** to **AKIASKLDSKDIWEOWE** +* Set **SMTP Password** to **AdskfjAKLSDJShflsdfjkakldADkjkjdfKAJDSlkjweiqQIWEOU** +* Set **SMTP Server** to **email-smtp.us-east-1.amazonaws.com** +* Set **SMTP Port** to **465** +* Set **Connection Security** to **TLS** + +##### Postfix +* Make sure Postfix is installed on the machine where Mattermost is installed +* Set **SMTP Username** to **** +* Set **SMTP Password** to **** +* Set **SMTP Server** to **localhost** +* Set **SMTP Port** to **25** +* Set **Connection Security** to **** + +##### Gmail +* Information needed + +##### Office 365 +* Information needed + +##### Hotmail +* Information needed -3. **Restart Mattermost** - 1. Use `ps -A` to find the process ID ("pid") for service named `platform` and stop it using `kill [pid]` - 2. The service should restart automatically. Run `ps -A` to verify the `platform` is running again - 3. Use the reset password page (E.g. _example.com/teamname/reset_password_) to test that email is now working by entering your email and clicking **Reset my password**. - 4. Note: The next time users log out, or when their session tokens expire, each will be required to verify their email address. ### Troubleshooting SMTP +#### Tip 1 +If you fill in **SMTP Username** and **SMTP Password** then you must set **Connection Security** to **TLS** or to **STARTTLS** + +#### Tip 2 If you have issues with your SMTP install, from your Mattermost team site go to the main menu and open **System Console -> Logs** to look for error messages related to your setup. You can do a search for the error code to narrow down the issue. Sometimes ISPs require nuanced setups for SMTP and error codes can hint at how to make the proper adjustments. For example, if **System Console -> Logs** has an error code reading: @@ -48,4 +76,19 @@ Connection unsuccessful: Failed to add to email address - 554 5.7.1 `. If the command works you should see something like +``` +250-mail.example.com NO UCE +250-STARTTLS +250-PIPELINING +250 8BITMIME +``` \ No newline at end of file diff --git a/doc/install/Troubleshooting-Email.md b/doc/install/Troubleshooting-Email.md index 0ddc807bb..b8e34de25 100644 --- a/doc/install/Troubleshooting-Email.md +++ b/doc/install/Troubleshooting-Email.md @@ -1,14 +1,42 @@ +### Mattermost Email Troubleshooting -change settings via system console +#### Update Email Settings in System Console +* Login to Mattermost with an account that has the `system admin` role +* Open the System Console by clicking on **...** > **System Console** > **Email Settings* + * Change **Send Email Notifications** to **true** + * Change **Require Email Verification** to **true** +* Set **Notification Email Address** must be set and must be a valid email allowed as the **FROM** field on the email server. Some email servers will only allow certian accounts to send emails. +* Set the **SMTP** fields based on your email service. Some known good samples are listed below. +* If you fill in **SMTP Username** and **SMTP Password** then you must set **Connection Security** to **TLS** or to **STARTTLS** +* Once you've filled in all the information please make sure to **Test Connection** +* If the test failed please look in **OTHER** > **Logs** for any errors that look like `[EROR] /api/v1/admin/test_email ...` -known good settings for providers: -amazon ses -postfix -gmail -hotmail -sendgrid +#### Known Good Sample Settings + +##### Amazon SES +* Set **SMTP Username** to **AKIASKLDSKDIWEOWE** +* Set **SMTP Password** to **AdskfjAKLSDJShflsdfjkakldADkjkjdfKAJDSlkjweiqQIWEOU** +* Set **SMTP Server** to **email-smtp.us-east-1.amazonaws.com** +* Set **SMTP Port** to **465** +* Set **Connection Security** to **TLS** + +##### Postfix +* Make sure Postfix is installed on the machine where Mattermost is installed +* Set **SMTP Username** to **** +* Set **SMTP Password** to **** +* Set **SMTP Server** to **localhost** +* Set **SMTP Port** to **25** +* Set **Connection Security** to **** + +##### Gmail +* Information needed + +##### Office 365 +* Information needed + +##### Hotmail +* Information needed -if you fill in a username/password you must use a secure connection like TLS or STARTTLS test connection check error logs -- cgit v1.2.3-1-g7c22 From 446e17a21ed3b5d2a2cd07d5f82a70edf085ef0c Mon Sep 17 00:00:00 2001 From: =Corey Hulen Date: Wed, 21 Oct 2015 15:48:52 -0700 Subject: Removing old dock --- doc/install/Troubleshooting-Email.md | 49 ------------------------------------ 1 file changed, 49 deletions(-) delete mode 100644 doc/install/Troubleshooting-Email.md diff --git a/doc/install/Troubleshooting-Email.md b/doc/install/Troubleshooting-Email.md deleted file mode 100644 index b8e34de25..000000000 --- a/doc/install/Troubleshooting-Email.md +++ /dev/null @@ -1,49 +0,0 @@ -### Mattermost Email Troubleshooting - -#### Update Email Settings in System Console -* Login to Mattermost with an account that has the `system admin` role -* Open the System Console by clicking on **...** > **System Console** > **Email Settings* - * Change **Send Email Notifications** to **true** - * Change **Require Email Verification** to **true** -* Set **Notification Email Address** must be set and must be a valid email allowed as the **FROM** field on the email server. Some email servers will only allow certian accounts to send emails. -* Set the **SMTP** fields based on your email service. Some known good samples are listed below. -* If you fill in **SMTP Username** and **SMTP Password** then you must set **Connection Security** to **TLS** or to **STARTTLS** -* Once you've filled in all the information please make sure to **Test Connection** -* If the test failed please look in **OTHER** > **Logs** for any errors that look like `[EROR] /api/v1/admin/test_email ...` - -#### Known Good Sample Settings - -##### Amazon SES -* Set **SMTP Username** to **AKIASKLDSKDIWEOWE** -* Set **SMTP Password** to **AdskfjAKLSDJShflsdfjkakldADkjkjdfKAJDSlkjweiqQIWEOU** -* Set **SMTP Server** to **email-smtp.us-east-1.amazonaws.com** -* Set **SMTP Port** to **465** -* Set **Connection Security** to **TLS** - -##### Postfix -* Make sure Postfix is installed on the machine where Mattermost is installed -* Set **SMTP Username** to **** -* Set **SMTP Password** to **** -* Set **SMTP Server** to **localhost** -* Set **SMTP Port** to **25** -* Set **Connection Security** to **** - -##### Gmail -* Information needed - -##### Office 365 -* Information needed - -##### Hotmail -* Information needed - - -test connection -check error logs -search for specific smtp errors like '555' with your provider. - -Adv Email trouble shooting -from the machine (if docker then exec) -run telnet to make sure host/port is correct -issue ELHO cmd to see if you can see stuff like STARTTSL - -- cgit v1.2.3-1-g7c22 From 903324c09b1058405224f27f925d0ce47884e6d5 Mon Sep 17 00:00:00 2001 From: =Corey Hulen Date: Wed, 21 Oct 2015 15:51:32 -0700 Subject: tweaking formatting --- doc/install/SMTP-Email-Setup.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/install/SMTP-Email-Setup.md b/doc/install/SMTP-Email-Setup.md index 2100130ee..135ca03e1 100644 --- a/doc/install/SMTP-Email-Setup.md +++ b/doc/install/SMTP-Email-Setup.md @@ -44,11 +44,11 @@ To enable email, configure an SMTP email service as follows: ##### Postfix * Make sure Postfix is installed on the machine where Mattermost is installed -* Set **SMTP Username** to **** -* Set **SMTP Password** to **** +* Set **SMTP Username** to **(empty)** +* Set **SMTP Password** to **(empty)** * Set **SMTP Server** to **localhost** * Set **SMTP Port** to **25** -* Set **Connection Security** to **** +* Set **Connection Security** to **(empty)** ##### Gmail * Information needed -- cgit v1.2.3-1-g7c22 From 391023339a79bd96ec803255713f8f009481e48a Mon Sep 17 00:00:00 2001 From: =Corey Hulen Date: Wed, 21 Oct 2015 15:53:01 -0700 Subject: tweaking formatting --- doc/install/SMTP-Email-Setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/install/SMTP-Email-Setup.md b/doc/install/SMTP-Email-Setup.md index 135ca03e1..b958a6a96 100644 --- a/doc/install/SMTP-Email-Setup.md +++ b/doc/install/SMTP-Email-Setup.md @@ -79,7 +79,7 @@ Search for `554 5.7.1 error` and `Client host rejected: Access denied`. #### Tip 3 * Attempt to telnet to the email service to make sure the server is reachable. * You must run the following commands from the same machine or virtual instance where `mattermost/bin/platform` is located. So if you're running Mattermost from docker you need to `docker exec -ti mattermost-dev /bin/bash` -* Telnet into email server with `telnet mail.example.com 25`. If the command works you should see something like +* Telnet to the email server with `telnet mail.example.com 25`. If the command works you should see something like ``` Trying 24.121.12.143... Connected to mail.example.com. -- cgit v1.2.3-1-g7c22