86 lines
2.7 KiB
Markdown
86 lines
2.7 KiB
Markdown
# sendtomatrix
|
|
|
|
Linux shell script to send a (multiline) message to a [matrix room](https://matrix.org) hosted on a [synapse server](https://github.com/matrix-org/synapse).
|
|
|
|
Usable for e.g. cronjobs, nagios notifications or ci pipelines.
|
|
|
|
## Usage
|
|
|
|
This script expects data to be piped in on STDIN.
|
|
|
|
```bash
|
|
COMMAND | sendtomatrix [OPTION]
|
|
```
|
|
|
|
## Options
|
|
|
|
* -u Matrix User Name
|
|
* -p Matrix User Password
|
|
* -a Matrix Access Token
|
|
* -s Matrix Server FQDN
|
|
* -r Matrix RoomID
|
|
* -f Optional configuration file
|
|
* -h Show help message
|
|
|
|
You can either provide an access token or username / password.
|
|
If no access token is provided, this script will get one for you from the server.
|
|
|
|
But keep in mind, that every time this script runs without an access token, a new access token is created and fills up your device list.
|
|
With to many devices in your device list, there is a potential getting blacklisted.
|
|
|
|
The recommended way is to provide an access token.
|
|
|
|
### Getting an access token from the server
|
|
|
|
```bash
|
|
curl -s -X POST -d '{ "type":"m.login.password", "user":"$MATRIX_USER", "password":"$MATRIX_PASS" }' "https://$MATRIX_SERVER/_matrix/client/r0/login" | jq -r '.access_token'
|
|
```
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
echo "Testmessage 1" | sendtomatrix -f /etc/sendtomatrix.conf
|
|
echo "Testmessage 2" | sendtomatrix -f /etc/sendtomatrix.conf -r "\!QtykxKocfZaZOUrTwp:matrix.org"
|
|
```
|
|
|
|
Please keep an eye on the format of the RoomID!
|
|
|
|
## Requirements
|
|
|
|
* [Synapse server](https://github.com/matrix-org/synapse) as API endpoint
|
|
* jq on the system which runs the script
|
|
* Before you can send a message to a room, the user sending the message already needs to have joined it
|
|
|
|
## Configuration file
|
|
|
|
The configuration file can contain the following values:
|
|
|
|
```bash
|
|
MATRIX_USER=TestUser
|
|
MATRIX_PASS=TestPassword
|
|
MATRIX_ACCESS_TOKEN=MD..blah
|
|
MATRIX_SERVER=matrix.org
|
|
# RoomID from the #matrix:matrix.org Channel
|
|
MATRIX_ROOM_ID="!QtykxKocfZaZOUrTwp:matrix.org"
|
|
```
|
|
|
|
These values can be overriden by command line parameters.
|
|
|
|
## Cron Job
|
|
|
|
It's also possible to use this script to send the output of a cronjob to a matrix room.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
SHELL=/bin/bash
|
|
0 4 * * * root /usr/local/sbin/random_script | sendtomatrix -f /etc/sendtomatrix.conf
|
|
0 5 * * * OUTPUT="# $(hostname -f) - random_script" && OUTPUT="$OUTPUT\n" && echo -e "$OUTPUT" | sendtomatrix -f /etc/sendtomatrix.conf
|
|
```
|
|
|
|
The last example allows appending e.g. the fqdn of the server and custom text to a message.
|
|
|
|
With this approach it's possible to send the same message from different servers to the same room and still be able to keep track from which server the message originates.
|
|
|
|
# Original github-repo
|
|
https://github.com/Madic-/Scripts/tree/master/Linux/sendtomatrix |