1<!--
 2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
 3
 4SPDX-License-Identifier: Unlicense
 5-->
 6
 7# The Mumbling Herald
 8
 9A grumpy old herald who watches your Mumble server and announces comings and goings via XMPP.
10
11## Full setup
12
13- Create a herald user with minimal permissions
14  ```bash
15  sudo useradd -r -s /bin/false -d /var/lib/mumblingherald -m mumblingherald
16  sudo usermod -a -G mumble-server mumblingherald  # if mumble-server group exists for log access
17  ```
18- Copy script to user's directory, make it executable, and set ownership
19  ```bash
20  sudo cp mumblingherald /var/lib/mumblingherald
21  sudo chown mumblingherald:mumblingherald /var/lib/mumblingherald/mumblingherald
22  sudo chmod 700 /var/lib/mumblingherald/mumblingherald
23  ```
24- Edit the script to configure details
25  - `MUMBLE_LOG_FILE`: path to your Mumble server log
26  - `XMPP_RECIPIENTS`: recipient JID for notifications
27  - `MONITORED_CHANNELS`: display name of channels to watch
28- Install go-sendxmpp
29  - Download the latest binary from the [go-sendxmpp releases page](https://salsa.debian.org/mdosch/go-sendxmpp/-/releases)
30  - Extract and copy to system location
31    ```bash
32    sudo cp go-sendxmpp /usr/local/bin/
33    sudo chmod 755 /usr/local/bin/go-sendxmpp
34    ```
35- Create config directory
36  ```bash
37  sudo -u mumblingherald mkdir -p /var/lib/mumblingherald/.config/go-sendxmpp
38  ```
39- Create XMPP config in `/var/lib/mumblingherald/.config/go-sendxmpp/config` (edit values!)
40  ```bash
41  username: herald@your-xmpp-server.com
42  password: your-password
43  ```
44  - Correct permissions
45    ```bash
46    chmod 600 /var/lib/mumblingherald/.config/go-sendxmpp/config
47    ```
48- Create systemd service in `/etc/systemd/system/mumblingherald.service`
49  ```ini
50  [Unit]
51  Description=The Mumbling Herald - Mumble event notifier over XMPP
52  After=network.target
53  [Service]
54  Type=simple
55  User=mumblingherald
56  Group=mumble-server
57  WorkingDirectory=/var/lib/mumblingherald
58  Environment=HOME=/var/lib/mumblingherald
59  ExecStart=/var/lib/mumblingherald/mumblingherald
60  Restart=always
61  RestartSec=5
62  [Install]
63  WantedBy=multi-user.target
64  ```
65- Start the herald
66  ```bash
67  sudo systemctl daemon-reload
68  sudo systemctl enable --now mumblingherald
69  ```
70- Check status
71  ```bash
72  sudo systemctl status mumblingherald
73  ```
74
75## Logs
76
77```bash
78sudo journalctl -u mumblingherald -f
79```
80
81## Contributions are welcome
82
83This repo is on SourceHut ([repo][srhtrepo]) and Radicle ([web][radrepo],
84`rad:z37gVhKaFLFso2zkBHNdB6pK3HipW`, [what is Radicle?][rad]).
85
86[srhtrepo]: https://git.sr.ht/~amolith/mumblingherald
87[radrepo]: https://radicle.secluded.site/nodes/seed.secluded.site/rad:z37gVhKaFLFso2zkBHNdB6pK3HipW
88[rad]: https://radicle.xyz