diff options
Diffstat (limited to 'doc/mod/notification-matrix.md')
| -rw-r--r-- | doc/mod/notification-matrix.md | 124 |
1 files changed, 82 insertions, 42 deletions
diff --git a/doc/mod/notification-matrix.md b/doc/mod/notification-matrix.md index 3da5659..da6d6de 100644 --- a/doc/mod/notification-matrix.md +++ b/doc/mod/notification-matrix.md @@ -1,7 +1,14 @@ Send notifications via Matrix ============================= -[◀ Go back to main README](../../README.md) +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) + +[⬅️ Go back to main README](../../README.md) > ℹ️️ **Info**: This module can not be used on its own but requires the base > installation. See [main README](../../README.md) for details. @@ -10,7 +17,7 @@ Description ----------- This module adds support for sending notifications via -[Matrix](https://matrix.org/) via client server api. A queue is used to +[Matrix ↗️](https://matrix.org/) via client server api. A queue is used to make sure notifications are not lost on failure but sent later. Requirements and installation @@ -21,8 +28,8 @@ Just install the module: $ScriptInstallUpdate mod/notification-matrix; Also install a Matrix client on at least one of your mobile and/or desktop -devices. As there is no privilege separation you should create a dedicated -notification account, in addition to your general user account. +devices. Create and setup an account there, we will reference that as +"*general account*" later. Configuration ------------- @@ -31,58 +38,66 @@ Edit `global-config-overlay`, add `MatrixHomeServer`, `MatrixAccessToken` and `MatrixRoom` - see below on hints how to retrieve this information. Then reload the configuration. -### Home server +> ℹ️ **Info**: Copy relevant configuration from +> [`global-config`](../../global-config.rsc) (the one without `-overlay`) to +> your local `global-config-overlay` and modify it to your specific needs. -Matrix user accounts are identified by a unique user id in the form of -`@localpart:domain`. The `domain` part is not necessarily your home server -address, you have to resolve it with the procedure described in the -[Matrix specification](https://spec.matrix.org/latest/client-server-api/#server-discovery). +The Matrix server is connected via encrypted https, and certificate +verification is applied. So make sure you have the certificate chain for +your server in device's certificate store. -Your best bet is to query the server at `domain` with the -[well-known uri](https://spec.matrix.org/latest/client-server-api/#well-known-uri). -For "*matrix.org*" this query is: +The example below is for `matrix.org`, which uses a trust chain from *Google +Trust Services*. Run this to import the required certificate: - /tool/fetch "https://matrix.org/.well-known/matrix/client" output=user; + $CertificateAvailable "GTS Root R4"; - +Replace the CA certificate name with what ever is needed for your server. +You may want to find the +[certificate name from browser](../../CERTIFICATES.md). -So the home server for "*matrix.org*" is "*matrix-client.matrix.org*". -Please strip the protocol ("*https://*") for `MatrixHomeServer` if given. +### From other device -### Access token +If you have setup your Matrix *notification account* before just reuse that. +Copy the relevant configuration to the device to be configured. -After discovering the correct home server an access token has to be created. -For this the login credentials (username and password) of the notification -account must be sent to the home server via -[client server api](https://matrix.org/docs/guides/client-server-api#login). +### Setup new account -We use the home server discovered above, "*matrix-client.matrix.org*". -The user is "*example*" and password is "*v3ry-s3cr3t*". +As there is no privilege separation you should create a dedicated account +for use with these scripts, in addition to your *general account*. +We will reference that as "*notification account*" in the following steps. - /tool/fetch "https://matrix-client.matrix.org/_matrix/client/r0/login" http-method=post http-data="{\"type\":\"m.login.password\", \"user\":\"example\", \"password\":\"v3ry-s3cr3t\"}" output=user; +#### Authenticate + +Matrix user accounts are identified by a unique user id in the form of +`@localpart:domain`. Use that and your password to generate an access token +and write first part of the configuration: - + $SetupMatrixAuthenticate "@example:matrix.org" "v3ry-s3cr3t"; -The server replied with a JSON object containing the `access_token`, use that -for `MatrixAccessToken`. + -### Room +The configuration is written to a new configuration snippet +`global-config-overlay.d/mod/notification-matrix`. -Every Matix chat is a room, so we have to create one. Do so with your general -user, this makes sure your general user is the room owner. Then join the room -and invite the notification user by its user id "*@example:matrix.org*". Look -up the room id within the Matrix client, it should read like -"*!WUcxpSjKyxSGelouhA:matrix.org*". Use that for `MatrixRoom`. +#### Join Room -Finally join the notification user to the room by accepting the invite. Again, -this can be done with -[client server api](https://matrix.org/docs/guides/client-server-api#joining-a-room-via-an-invite). -Make sure to replace room id ("*!*" is escaped with "*%21*") and access token -with your data. +Every Matix chat is a room, so we have to create one. Do that with your +*general account*, this makes sure your *general account* is the room owner. +Then join the room and invite the *notification account* by its user id +"*@example:matrix.org*". +Look up the *room id* within the Matrix client, it should read like +"*!WUcxpSjKyxSGelouhA:matrix.org*" (starting with an exclamation mark and +ending with the domain). - /tool/fetch "https://matrix-client.matrix.org/_matrix/client/r0/rooms/%21WUcxpSjKyxSGelouhA:matrix.org/join?access_token=yt_ZXdvcm0tdGVzdA_NNqUyvKHRhBLZmnzVVSK_0xu6yN" http-method=post http-data="" output=user; +Finally make the *notification account* join into the room by accepting +the invite. - + $SetupMatrixJoinRoom "!WUcxpSjKyxSGelouhA:matrix.org"; + + + +The configuration is appended to the configuration snippet +`global-config-overlay.d/mod/notification-matrix`. Usage and invocation -------------------- @@ -90,11 +105,36 @@ Usage and invocation There's nothing special to do. Every script or function sending a notification will now send it to your Matrix account. +But of course you can use the function to send notifications directly. Give +it a try: + + $SendMatrix "Subject..." "Body..."; + +Alternatively this sends a notification with all available and configured +methods: + + $SendNotification "Subject..." "Body..."; + +To use the functions in your own scripts you have to declare them first. +Place this before you call them: + + :global SendMatrix; + :global SendNotification; + +In case there is a situation when the queue needs to be purged there is a +function available: + + $PurgeMatrixQueue; + See also -------- +* [Certificate name from browser](../../CERTIFICATES.md) +* [Send notifications via e-mail](notification-email.md) +* [Send notifications via Gotify](notification-gotify.md) +* [Send notifications via Ntfy](notification-ntfy.md) * [Send notifications via Telegram](notification-telegram.md) --- -[◀ Go back to main README](../../README.md) -[▲ Go back to top](#top) +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) |