diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/mod/notification-matrix.d/01-authenticate.avif | bin | 0 -> 4209 bytes | |||
| -rw-r--r-- | doc/mod/notification-matrix.d/01-home-server.avif | bin | 2317 -> 0 bytes | |||
| -rw-r--r-- | doc/mod/notification-matrix.d/02-access-token.avif | bin | 4105 -> 0 bytes | |||
| -rw-r--r-- | doc/mod/notification-matrix.d/02-join-room.avif | bin | 0 -> 3955 bytes | |||
| -rw-r--r-- | doc/mod/notification-matrix.d/03-join-room.avif | bin | 3166 -> 0 bytes | |||
| -rw-r--r-- | doc/mod/notification-matrix.md | 73 |
6 files changed, 34 insertions, 39 deletions
diff --git a/doc/mod/notification-matrix.d/01-authenticate.avif b/doc/mod/notification-matrix.d/01-authenticate.avif Binary files differnew file mode 100644 index 0000000..1db516b --- /dev/null +++ b/doc/mod/notification-matrix.d/01-authenticate.avif diff --git a/doc/mod/notification-matrix.d/01-home-server.avif b/doc/mod/notification-matrix.d/01-home-server.avif Binary files differdeleted file mode 100644 index 683c7b5..0000000 --- a/doc/mod/notification-matrix.d/01-home-server.avif +++ /dev/null diff --git a/doc/mod/notification-matrix.d/02-access-token.avif b/doc/mod/notification-matrix.d/02-access-token.avif Binary files differdeleted file mode 100644 index 54109a6..0000000 --- a/doc/mod/notification-matrix.d/02-access-token.avif +++ /dev/null diff --git a/doc/mod/notification-matrix.d/02-join-room.avif b/doc/mod/notification-matrix.d/02-join-room.avif Binary files differnew file mode 100644 index 0000000..edd6c81 --- /dev/null +++ b/doc/mod/notification-matrix.d/02-join-room.avif diff --git a/doc/mod/notification-matrix.d/03-join-room.avif b/doc/mod/notification-matrix.d/03-join-room.avif Binary files differdeleted file mode 100644 index 45974b8..0000000 --- a/doc/mod/notification-matrix.d/03-join-room.avif +++ /dev/null diff --git a/doc/mod/notification-matrix.md b/doc/mod/notification-matrix.md index 4ae6e18..b309d3d 100644 --- a/doc/mod/notification-matrix.md +++ b/doc/mod/notification-matrix.md @@ -21,8 +21,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 ------------- @@ -35,58 +35,53 @@ reload the configuration. > [`global-config`](../../global-config.rsc) (the one without `-overlay`) to > your local `global-config-overlay` and modify it to your specific needs. -### Home server +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. -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). - -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: +> ℹ️ **Info**: The *matrix.org* server uses a Cloudflare certificate. You can +> install that with: `$CertificateAvailable "Cloudflare Inc ECC CA-3"` - /tool/fetch "https://matrix.org/.well-known/matrix/client" output=user; +### From other device - +If you have setup your Matrix *notification account* before just reuse that. +Copy the relevant configuration to the device to be configured. -So the home server for "*matrix.org*" is "*matrix-client.matrix.org*". -Please strip the protocol ("*https://*") for `MatrixHomeServer` if given. +### Setup new account -### Access token +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. -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). +#### Authenticate -We use the home server discovered above, "*matrix-client.matrix.org*". -The user is "*example*" and password is "*v3ry-s3cr3t*". +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: - /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; + $SetupMatrixAuthenticate "@example:matrix.org" "v3ry-s3cr3t"; - + -The server replied with a JSON object containing the `access_token`, use that -for `MatrixAccessToken`. +#### Join Room -### Room +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). -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`. +Finally make the *notification account* join into the room by accepting +the invite. -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. + $SetupMatrixJoinRoom "!WUcxpSjKyxSGelouhA:matrix.org"; - /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; + - +The settings have been appended to `global-config-overlay`. You may want to +edit to move it to an appropriate place. Usage and invocation -------------------- |
