blob: be9edcd11810c38997146902439a7eab8be37af7 (
plain)
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
|
<!--
SPDX-FileCopyrightText: 2025 Tomasz Kramkowski <tomasz@kramkow.ski>
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# MQTTT
MQTTT (named for "MQTT Tree") is a MQTT router which uses a the structure of a
filesystem hierarchy to subscribe to MQTT topics and dispatch them to
executables within this structure.
It is deprecated as there's no particular advantage to having a directory
hierarchy as opposed to having a config file with routes mapped to program
invocations.
## Building
Use `cargo build` as normal.
The `DEFAULT_ROOT` environment variable controls the default root path which is
normally `/var/run/mqttt`.
The `SYSCONFDIR` environment variable controls the location of where
`mqttt.toml` is searched. The default is `/usr/local/etc`.
## Installation and Configuration
Copy the `mqttt` binary to the path on the target system. The default
configuration is equivalent to the following contents of `mqttt.toml`:
```toml
root = "/var/run/mqttt" # Path to MQTTT root
host = "localhost" # MQTT server host
port = 1883 # MQTT server port
# [credentials] # Uncomment to specify MQTT connection credentials
# username = "username"
# password = "password"
id = "mqttt" # MQTT client identifier
}
```
## Usage
Create a directory structure under the root directory which matches the MQTT
topic you want to subscribe to. For example:
```shell
$ mkdir -p /var/run/mqttt/zigbee2mqtt/light_switch
```
Populate this directory with executables which you wish to run when a message
matching that topic filter is received.
```shell
$ cat <<EOF >/var/run/mqttt/zigbee2mqtt/light_switch/toggle_light
#!/usr/bin/env bash
topic=$1
action=$(jq --raw-output .action)
[[ $action == "toggle" ]] || exit 0
mosquitto_pub --topic "zigbee2mqtt/light/set" --message '{"state":"TOGGLE"}'
EOF
$ chmod +x /var/run/mqttt/zigbee2mqtt/light_switch/toggle_light
```
Start the `mqttt` program. It cannot be forked to background so it is expected
to be ran under a daemontools style supervisor, the `daemon` utility or with
something like systemd.
It's a good idea to run `mqttt` as its own dedicated user.
## Known bugs
* Executables are run sequentially
* No timeout
* Can't map to a topic with a single or double dot as a path component
* No permission checks on `mqttt.toml` if it contains a password (to ensure the
password isn't being exposed)
* No way to specify the subscription QOS for a route (default is 0 (at most
once))
|
