74 lines
2.2 KiB
Markdown
74 lines
2.2 KiB
Markdown
# TellMe
|
|
|
|
A server and client notifications system written in Python that alerts you of events via SimpleX chat or Matrix.
|
|
|
|
## Overview
|
|
|
|
TellMe monitors for events (completed processes, server uptime, etc.) and sends notifications through a built-in server to SimpleX chat or Matrix over websockets. Starting from version 2.2, TellMe supports [GoAlert](https://goalert.io) messages natively.
|
|
|
|
## Client Features
|
|
|
|
- **Send messages**: `-m "Your message"` - Send custom notifications
|
|
- **Monitor processes**: `-p <pid>` - Wait for a process to exit, then notify
|
|
- **Watch commands**: `-w "command"` - Run a command periodically and notify on output
|
|
- **Ping hosts**: `-P <host>` - Monitor host availability until it's reachable
|
|
|
|
## Server Setup
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
cd server/src
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Configuration
|
|
|
|
1. Configure hooks in `/etc/tellme/hooks.yml`:
|
|
```yaml
|
|
2345555XE:
|
|
transport: "simplex"
|
|
target: "#Bottest"
|
|
```
|
|
|
|
Supported transports: `simplex`, `matrix`
|
|
|
|
2. (Optional) Configure Matrix credentials in `/etc/tellme/config.yml`:
|
|
```yaml
|
|
matrix_homeserver: "https://matrix.org"
|
|
matrix_access_token: "syt_your_token_here"
|
|
matrix_user_id: "@yourbot:matrix.org"
|
|
```
|
|
|
|
#### Obtaining a Matrix Access Token
|
|
|
|
**Via Element Web (easiest):**
|
|
1. Log into Element (https://app.element.io or your homeserver's Element instance)
|
|
2. Go to **Settings** (gear icon) → **Help & About**
|
|
3. Scroll to **Access Token** → click "Reveal Access Token" → copy it
|
|
|
|
**Via Matrix API (curl):**
|
|
```bash
|
|
curl -X POST "https://your-homeserver.url/_matrix/client/v3/login" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"type":"m.login.password","user":"@youruser:homeserver","password":"yourpassword"}'
|
|
```
|
|
The response includes `access_token`.
|
|
|
|
**Important:**
|
|
- Use a dedicated bot account, not your personal one
|
|
- Keep the token secure (don't commit to git)
|
|
- Revoke it in Element settings if compromised
|
|
|
|
3. Run the SimpleX CLI chat as a daemon (for SimpleX transport).
|
|
|
|
4. Start the server:
|
|
```bash
|
|
python tellmesrv.py
|
|
```
|
|
|
|
## Ansible
|
|
|
|
An example Ansible role is included in `Ansible/tellme_notification` for integrating TellMe notifications into Ansible playbooks.
|
|
|
|
Created by Taurix IT (https://www.taurix.net) | Licensed under AGPLv3+ |