Merge pull request #245540 from yegu-ms/main

prmerger-automator[bot] · web-flow · commit 8882417c34b3 · 2023-07-19T20:01:05.000Z
Added SMTP config testing
diff --git a/articles/managed-grafana/how-to-smtp-settings.md b/articles/managed-grafana/how-to-smtp-settings.md
@@ -25,7 +25,7 @@ To follow the steps in this guide, you must have:
 
 ## Enable and configure SMTP settings
 
-To activate SMTP settings, enable email notifications and configure an email contact point in Azure Managed Grafana, follow the steps below.
+Follow these steps to activate SMTP settings, enable email notifications and configure an email contact point in Azure Managed Grafana.
 
 ### [Portal](#tab/azure-portal)
 
@@ -43,7 +43,7 @@ To activate SMTP settings, enable email notifications and configure an email con
         | From Address   | user@domain.com       | Enter the email address used when sending out emails.                                                                                      |
         | From Name      | Azure Managed Grafana Notification | Enter the name used when sending out emails. Default is "Azure Managed Grafana Notification" if parameter isn't given or empty. |
         | Skip Verify    | Disable                 |This setting controls whether a client verifies the server's certificate chain and host name. If **Skip Verify** is **Enable**, client accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. Default is **Disable** (toggled off). [More information](https://pkg.go.dev/crypto/tls#Config).                              |
-        | StartTLS Policy | OpportunisticStartTLS | There are 3 options. [More information](https://pkg.go.dev/github.com/go-mail/mail#StartTLSPolicy).<br><ul><li>**OpportunisticStartTLS** means that SMTP transactions are encrypted if STARTTLS is supported by the SMTP server. Otherwise, messages are sent in the clear. This is the default setting.</li><li>**MandatoryStartTLS** means that SMTP transactions must be encrypted. SMTP transactions are aborted unless STARTTLS is supported by the SMTP server.</li><li>**NoStartTLS** means encryption is disabled and messages are sent in the clear.</li></ul>          |
+        | StartTLS Policy | OpportunisticStartTLS | There are three options. [More information](https://pkg.go.dev/github.com/go-mail/mail#StartTLSPolicy).<br><ul><li>**OpportunisticStartTLS** means that SMTP transactions are encrypted if STARTTLS is supported by the SMTP server. Otherwise, messages are sent in the clear. It's the default setting.</li><li>**MandatoryStartTLS** means that SMTP transactions must be encrypted. SMTP transactions are aborted unless STARTTLS is supported by the SMTP server.</li><li>**NoStartTLS** means encryption is disabled and messages are sent in the clear.</li></ul>          |
 
   1. Select **Save** to save the SMTP settings. Updating may take a couple of minutes.
 
@@ -54,7 +54,7 @@ To activate SMTP settings, enable email notifications and configure an email con
 ### [Azure CLI](#tab/azure-cli)
 
 1. Azure Managed Grafana CLI extension 1.1 or above is required to enable or update SMTP settings. To update your extension, run `az extension update --name amg`.
-1. Run the [az grafana update](/cli/azure/grafana#az-grafana-update) command to configure SMTP settings for a given Azure Managed Grafana instance. When doing this, replace the placeholders below with information from your own instance.
+1. Run the [az grafana update](/cli/azure/grafana#az-grafana-update) command to configure SMTP settings for a given Azure Managed Grafana instance. Replace the placeholders with information from your own instance.
 
     ```azurecli
     az grafana update --resource-group <resource-group> \
@@ -79,7 +79,7 @@ To activate SMTP settings, enable email notifications and configure an email con
     | `--host`             | test.sendgrid.net:587              | Enter the SMTP server hostname with port.                                                                                        |
     | `--user`             | admin                              | Enter the name of the user of the SMTP authentication.                                                                           |
     | `--password`         | password                           | Enter password of the SMTP authentication. If the password contains "#" or ";" wrap it within triple quotes.                     |
-    | `--start-tls-policy` | OpportunisticStartTLS              | The StartTLSPolicy setting of the SMTP configuration. There are 3 options. [More information](https://pkg.go.dev/github.com/go-mail/mail#StartTLSPolicy).<br><ul><li>**OpportunisticStartTLS** means that SMTP transactions are encrypted if STARTTLS is supported by the SMTP server. Otherwise, messages are sent in the clear. This is the default setting.</li><li>**MandatoryStartTLS** means that SMTP transactions must be encrypted. SMTP transactions are aborted unless STARTTLS is supported by the SMTP server.</li><li>**NoStartTLS** means encryption is disabled and messages are sent in the clear.</li></ul>  |
+    | `--start-tls-policy` | OpportunisticStartTLS              | The StartTLSPolicy setting of the SMTP configuration. There are three options. [More information](https://pkg.go.dev/github.com/go-mail/mail#StartTLSPolicy).<br><ul><li>**OpportunisticStartTLS** means that SMTP transactions are encrypted if STARTTLS is supported by the SMTP server. Otherwise, messages are sent in the clear. This is the default setting.</li><li>**MandatoryStartTLS** means that SMTP transactions must be encrypted. SMTP transactions are aborted unless STARTTLS is supported by the SMTP server.</li><li>**NoStartTLS** means encryption is disabled and messages are sent in the clear.</li></ul>  |
     | `--skip-verify`      | false                              |This setting controls whether a client verifies the server's certificate chain and host name. If **--skip-verify** is **true**, client accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. Default is **false**. [More information](https://pkg.go.dev/crypto/tls#Config).                      |
 
 ---
@@ -88,6 +88,30 @@ To activate SMTP settings, enable email notifications and configure an email con
 > Here are some tips for properly configuring SMTP:
 >- When using a business email account such as Office 365, you may need to contact your email administrator to enable SMTP AUTH (for example, [enable-smtp-auth-for-specific-mailboxes](/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission#enable-smtp-auth-for-specific-mailboxes)). You should be able to create an app password afterwards and use it as the SMTP *password* setting.
 >- When using a personal email account such as Outlook or Gmail, you should create an app password and use it as the SMTP *password* setting. Note that your account won't work for email notification if it's configured with multi-factor authentication.
+>- It's recommended that you verify the SMTP configurations to be working as expected before applying them to your Managed Grafana workspace. For example, you can use an open source tool such as [swaks (Swiss Army Knife for SMTP)](https://github.com/jetmore/swaks) to send a test email using the SMTP configurations by running the following command in a terminal window:
+>     ```bash
+>     # fill in all the empty values for the following parameters
+>     host="" # SMTP host name with port separated by a ":", e.g. smtp.office365.com:587
+>     user="" # email address, e.g. team1@microsoft.com
+>     password="" # password
+>     fromAddress="" # source email address (usually the same as user above), e.g. team1@contoso.com
+>     toAddress="" # destination email address, e.g. team2@contoso.com
+>     ehlo="" # grafana endpoint, e.g. team1-ftbghja6ekeybng8.wcus.grafana.azure.com
+>
+>     header="Subject:Test"
+>     body="Testing!"
+>     
+>     # test SMTP connection by sending an email
+>     swaks --auth -tls \
+>         --server $host \
+>         --auth-user $user \
+>         --auth-password $password \
+>         --from $fromAddress \
+>         --to $toAddress \
+>         --ehlo $ehlo \
+>         --header $header \
+>         --body $body
+>     ```
 
 ## Configure Grafana contact points and send a test email
 
@@ -102,11 +126,11 @@ Configuring Grafana contact points is done in the Grafana portal:
   1. Add or update the **Name**, and **Contact point type**.
   1. Enter a destination email under **Addresses**, and select **Test**.
   1. Select **Send test notification** to send the notification with the predefined test message or select **Custom** to first edit the message.
-  1. A notification "Test alert sent" is displayed, meaning that the email setup has been successfully configured. The test email has been sent to the provided email address. In case of misconfiguration, an error message will be displayed instead.
+  1. A notification "Test alert sent" is displayed, meaning that the email setup has been successfully configured. The test email has been sent to the provided email address. If there is a misconfiguration, an error message is shown instead.
 
 ## Disable SMTP settings
 
-To disable SMTP settings, follow the steps below.
+To disable SMTP settings, follow these steps.
 
 ### [Portal](#tab/azure-portal)
 
@@ -116,7 +140,7 @@ To disable SMTP settings, follow the steps below.
 ### [Azure CLI](#tab/azure-cli)
 
 1. Azure Managed Grafana CLI extension 1.1 or above is required to disable SMTP settings. To update your extension, run `az extension update --name amg`.
-1. Run the [az grafana update](/cli/azure/grafana#az-grafana-update) command to configure SMTP settings for a given Azure Managed Grafana instance. Replace the placeholders below with information from your own instance.
+1. Run the [az grafana update](/cli/azure/grafana#az-grafana-update) command to configure SMTP settings for a given Azure Managed Grafana instance. Replace the placeholders with information from your own instance.
 
     ```azurecli
     az grafana update --resource-group <resource-group> \
@@ -139,14 +163,10 @@ To disable SMTP settings, follow the steps below.
 
 Within the Grafana portal, you can find a list of all Grafana alerting error messages that occurred in **Alerting > Notifications**.
 
-Below are some common error messages you may encounter:
+The following are some common error messages you may encounter:
 
 - "Authentication failed: The provided authorization grant is invalid, expired, or revoked". Grafana couldn't connect to the SMTP server. Check if the password entered in the SMTP settings in the Azure portal is correct.
-- "Failed to sent test alert.: SMTP not configured". SMTP is disabled. Open the Azure Managed Grafana instance in the Azure portal and enable SMTP settings.
-
-## Known limitation
-
-Due to limitation on alerting high availability configuration in Azure Managed Grafana, there could be duplicate email notifications delivered for a single firing alert.
+- "Failed to sent test alert: SMTP not configured". SMTP is disabled. Open the Azure Managed Grafana instance in the Azure portal and enable SMTP settings.
 
 ## Next steps
 
