1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
<!--
SPDX-FileCopyrightText: 2025 Tomasz Kramkowski <tomasz@kramkow.ski>
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# MQTTR
MQTTR (named for "MQTT Router") is a MQTT router (duh) which lets you subscribe
to MQTT topics and execute arbitrary programs when a message matching that topic
arrives.
It is the successor of [MQTTT](https://the-tk.com/cgit/mqttt/about/) which was
the result of realising that using a filesystem hierarchy to represent the
configuration did not appear to have any particular benefits over just storing
the information in the already existing config file.
## Building and Installation
Use `cargo build` as normal.
The `SYSCONFDIR` environment variable controls the location of where `mqttr.toml` is searched. The default is `/usr/local/etc`.
Once built, the `mqttr` program (found in `target/{debug,release}/mqttr`) should
be located in some sensible place (e.g. `/usr/local/bin/mqttr`) and configured
as a system service.
`mqttr` does not have a way to double-fork, if you need this behaviour, use
`daemon` or some equivalent utility.
## Configuration
Create a `mqttr.toml` in the appropriate location. The file should contain at
minimum a set of routes. The following is the default configuration:
```toml
host = "localhost" # MQTT server host
port = 1883 # MQTT server port
# [credentials] # Uncomment to specify MQTT connection credentials
# username = "username"
# password = "password"
id = "mqttr" # MQTT client identifier
```
The routes follow the following format:
```toml
[routes]
"zigbee2mqtt/+/light" = [
["/path/to/program"],
["/path/to/another/program", "with", "args"],
]
"foo/bar/baz" = [ ... ]
```
On startup, `mqttr` will read the config file and subscribe to all the topics.
When a message is received, `mqttr` will match the message topic against the
routes and execute every program which is part of a matching route. Each program
will have the message topic appended as an additional argument and will receive
the message on stdin.
An example program is this script:
```bash
#!/usr/bin/env bash
topic=$1
action=$(jq --raw-output .action)
[[ $action == "toggle" ]] || exit 0
mosquitto_pub --topic "zigbee2mqtt/light/set" --message '{"state":"TOGGLE"}'
```
This can be bound to a topic such as `zigbee2mqtt/light` which would result in
it being ran every time a new MQTT message is published to this topic.
## Missing Features
* Asynchronous program execution
* Timeouts (existent, configurable, per process configurable)
* Permission checks on `mqttr.toml` if it contains a password (to ensure the
password isn't being exposed)
* Configurable QoS for each subscription (default is 0 (at most once))
* Pass message metadata via the environment (QoS, retain, dup)
* Configurable logging
* Ability to configure programs with non-UTF-8 in paths
|
