diff options
Diffstat (limited to 'health/notifications/matrix/README.md')
| -rw-r--r-- | health/notifications/matrix/README.md | 94 |
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. |