Adding upstream version 1.39.0.upstream/1.39.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 53 insertions, 41 deletions

diff --git a/health/notifications/matrix/README.md b/health/notifications/matrix/README.md
index 80e22da37..714d8c22e 100644
--- a/health/notifications/matrix/README.md
+++ b/health/notifications/matrix/README.md
@@ -1,62 +1,74 @@
-<!--
-title: "Send Netdata notifications to Matrix network rooms"
-description: "Stay aware of warning or critical anomalies by sending health alarms to Matrix network rooms with Netdata's health monitoring watchdog."
-sidebar_label: "Matrix"
-custom_edit_url: "https://github.com/netdata/netdata/edit/master/health/notifications/matrix/README.md"
-learn_status: "Published"
-learn_topic_type: "Tasks"
-learn_rel_path: "Setup/Notification/Agent"
-learn_autogeneration_metadata: "{'part_of_cloud': False, 'part_of_agent': True}"
--->
+# Matrix Agent alert notifications
 
-# Matrix
+Learn how to send notifications to Matrix network rooms using Netdata's Agent alert notification feature, which supports dozens of endpoints, user roles, and more.
 
-Send notifications to [Matrix](https://matrix.org/) network rooms.
+> ### Note
+>
+> This file assumes you have read the [Introduction to Agent alert notifications](https://github.com/netdata/netdata/blob/master/health/notifications/README.md), detailing how the Netdata Agent's alert notification method works.
 
-The requirements for this notification method are:
+## Prerequisites
 
-1.  The url of the homeserver (`https://homeserver:port`).
-2.  Credentials for connecting to the homeserver, in the form of a valid access token for your account (or for a
-    dedicated notification account). These tokens usually don't expire.
-3.  The room ids that you want to sent the notification to.
+You will need:
 
-To obtain the access token, you can use the following `curl` command:
+- The url of the homeserver (`https://homeserver:port`).
+- Credentials for connecting to the homeserver, in the form of a valid access token for your account (or for a dedicated notification account). These tokens usually don't expire.
+- The room ids that you want to sent the notification to.
 
-```bash
-curl -XPOST -d '{"type":"m.login.password", "user":"example", "password":"wordpass"}' "https://homeserver:8448/_matrix/client/r0/login"
-```
+## Configure Netdata to send alert notifications to Matrix
+
+> ### Info
+>
+> This file mentions editing configuration files.  
+>
+> - To edit configuration files in a safe way, we provide the [`edit config` script](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#use-edit-config-to-edit-configuration-files) located in your [Netdata config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory) (typically is `/etc/netdata`) that creates the proper file and opens it in an editor automatically.  
+> Note that to run the script you need to be inside your Netdata config directory.
+>
+> It is recommended to use this way for configuring Netdata.
+
+Edit `health_alarm_notify.conf`, changes to this file do not require restarting Netdata:
+
+1. Set `SEND_MATRIX` to `YES`.
+2. Set `MATRIX_HOMESERVER` to the URL of the Matrix homeserver.
+3. Set `MATRIX_ACCESSTOKEN` to the access token from your Matrix account.  
+    To obtain the access token, you can use the following `curl` command:
 
-The room ids are unique identifiers and can be obtained from the room settings in a Matrix client (e.g. Riot). Their
-format is `!uniqueid:homeserver`.
+    ```bash
+    curl -XPOST -d '{"type":"m.login.password", "user":"example", "password":"wordpass"}' "https://homeserver:8448/_matrix/client/r0/login"
+    ```
 
-Multiple room ids can be defined by separating with a space character.
+4. Set `DEFAULT_RECIPIENT_MATRIX` to the rooms you want the alert notifications to be sent to.  
+    The format is `!roomid:homeservername`.  
 
-Detailed information about the Matrix client API is available at the [official
-site](https://matrix.org/docs/guides/client-server.html).
+    The room ids are unique identifiers and can be obtained from the room settings in a Matrix client (e.g. Riot).
 
-Your `health_alarm_notify.conf` should look like this:
+    You can define multiple rooms like this: `!roomid1:homeservername !roomid2:homeservername`.  
+    All roles will default to this variable if left unconfigured.
+
+Detailed information about the Matrix client API is available at the [official site](https://matrix.org/docs/guides/client-server.html).
+
+You can then have different rooms per **role**, by editing `DEFAULT_RECIPIENT_MATRIX` with the `!roomid:homeservername` you want, in the following entries at the bottom of the same file:
 
 ```conf
-###############################################################################
+role_recipients_matrix[sysadmin]="!roomid1:homeservername"
+role_recipients_matrix[domainadmin]="!roomid2:homeservername"
+role_recipients_matrix[dba]="!roomid3:homeservername"
+role_recipients_matrix[webmaster]="!roomid4:homeservername"
+role_recipients_matrix[proxyadmin]="!roomid5:homeservername"
+role_recipients_matrix[sitemgr]="!roomid6:homeservername"
+```
+
+An example of a working configuration would be:
+
+```conf
+#------------------------------------------------------------------------------
 # Matrix notifications
-#
 
-# enable/disable Matrix notifications
 SEND_MATRIX="YES"
-
-# The url of the Matrix homeserver
-# e.g https://matrix.org:8448
 MATRIX_HOMESERVER="https://matrix.org:8448"
-
-# A access token from a valid Matrix account. Tokens usually don't expire,
-# can be controlled from a Matrix client.
-# See https://matrix.org/docs/guides/client-server.html
 MATRIX_ACCESSTOKEN="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
-
-# Specify the default rooms to receive the notification if no rooms are provided
-# in a role's recipients.
-# The format is !roomid:homeservername
 DEFAULT_RECIPIENT_MATRIX="!XXXXXXXXXXXX:matrix.org"
 ```
 
+## Test the notification method
 
+To test this alert notification method refer to the ["Testing Alert Notifications"](https://github.com/netdata/netdata/blob/master/health/notifications/README.md#testing-alert-notifications) section of the Agent alert notifications page.