1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: Unlicense
5-->
6
7# The Mumbling Herald
8
9[](https://scratchanitch.dev)
10
11A grumpy old herald who watches your Mumble server and announces comings and goings via XMPP.
12
13## Examples
14
15**Joining a channel:**
16
17- ➡️ {USERNAME} stumbles into {CHANNEL}
18- ➡️ _grumbles_ Oh, look who's decided to grace {CHANNEL} with their presence... {USERNAME}
19- ➡️ _adjusts spectacles_ Hmph! {USERNAME} wanders into {CHANNEL} with purpose unknown
20- ➡️ _sighs heavily_ Another soul wanders into {CHANNEL}... {USERNAME}, was it?
21
22**Leaving a channel:**
23
24- ⬅️ Oh, what? _ahem_ {USERNAME} fled... somewhere _waves hand_
25- ⬅️ {USERNAME} vanishes into the void...
26- ⬅️ _grumbles_ Well, that was brief... {USERNAME} has wandered off to other adventures
27- ⬅️ _mutters_ {USERNAME} has departed from us. Just when things were getting interesting...
28
29## Full setup
30
31- Create a herald user with minimal permissions
32 ```bash
33 sudo useradd -r -s /bin/false -d /var/lib/mumblingherald -m mumblingherald
34 sudo usermod -a -G mumble-server mumblingherald # if mumble-server group exists for log access
35 ```
36- Copy script to user's directory, make it executable, and set ownership
37 ```bash
38 sudo cp mumblingherald /var/lib/mumblingherald
39 sudo chown mumblingherald:mumblingherald /var/lib/mumblingherald/mumblingherald
40 sudo chmod 700 /var/lib/mumblingherald/mumblingherald
41 ```
42- Edit the script to configure details
43 - `MUMBLE_LOG_FILE`: path to your Mumble server log
44 - `XMPP_RECIPIENTS`: recipient JID for notifications
45 - `MONITORED_CHANNELS`: display name of channels to watch
46- Install go-sendxmpp
47 - Download the latest binary from the [go-sendxmpp releases page](https://salsa.debian.org/mdosch/go-sendxmpp/-/releases)
48 - Extract and copy to system location
49 ```bash
50 sudo cp go-sendxmpp /usr/local/bin/
51 sudo chmod 755 /usr/local/bin/go-sendxmpp
52 ```
53- Create config directory
54 ```bash
55 sudo -u mumblingherald mkdir -p /var/lib/mumblingherald/.config/go-sendxmpp
56 ```
57- Create XMPP config in `/var/lib/mumblingherald/.config/go-sendxmpp/config` (edit values!)
58 ```bash
59 username: herald@your-xmpp-server.com
60 password: your-password
61 ```
62 - Correct permissions
63 ```bash
64 chmod 600 /var/lib/mumblingherald/.config/go-sendxmpp/config
65 ```
66- Create systemd service in `/etc/systemd/system/mumblingherald.service`
67 ```ini
68 [Unit]
69 Description=The Mumbling Herald - Mumble event notifier over XMPP
70 After=network.target
71 [Service]
72 Type=simple
73 User=mumblingherald
74 Group=mumble-server
75 WorkingDirectory=/var/lib/mumblingherald
76 Environment=HOME=/var/lib/mumblingherald
77 ExecStart=/var/lib/mumblingherald/mumblingherald
78 Restart=always
79 RestartSec=5
80 [Install]
81 WantedBy=multi-user.target
82 ```
83- Start the herald
84 ```bash
85 sudo systemctl daemon-reload
86 sudo systemctl enable --now mumblingherald
87 ```
88- Check status
89 ```bash
90 sudo systemctl status mumblingherald
91 ```
92- Check logs
93 ```bash
94 sudo journalctl -feu mumblingherald
95 ```
96
97## Contributions are welcome
98
99This repo is on SourceHut ([repo][srhtrepo]) and Radicle ([web][radrepo],
100`rad:z37gVhKaFLFso2zkBHNdB6pK3HipW`, [what is Radicle?][rad]).
101
102[srhtrepo]: https://git.sr.ht/~amolith/mumblingherald
103[radrepo]: https://radicle.secluded.site/nodes/seed.secluded.site/rad:z37gVhKaFLFso2zkBHNdB6pK3HipW
104[rad]: https://radicle.xyz