Документация

Установка

Брокер — один исполняемый файл. На Linux пакет Debian дополнительно заводит юнит systemd, создаёт рабочий каталог и запускает службу; на Windows файл работает оттуда, куда вы его положили.

wget https://elxsoftware.com/download/elxmqttbroker-linux-amd64
sudo install -m 755 elxmqttbroker-linux-amd64 /usr/local/bin/elxmqttbroker
sudo elxmqttbroker --install-service
sudo systemctl enable --now elxmqttbroker

Для 32- и 64-разрядных ARM-плат всё то же самое — возьмите arm64 или armhf. Что именно у платы, скажет uname -m: aarch64 — это arm64, armv7l — armhf.

Запустите установщик или распакуйте портативную сборку и откройте elxmqttbroker.exe.
Панель откроется по адресу http://127.0.0.1:8567
Вход по умолчанию: admin / admin

Первый запуск

1. Откройте http://<адрес>:8567 и войдите.
2. Смените пароль администратора в меню профиля.
3. Заведите в разделе Пользователи учётную запись для своих устройств и дайте ей нужные топики — список прав сначала пуст, а пустой список означает отсутствие доступа.
4. Подключите один клиент и посмотрите, как он появится в Клиентах: это разом подтверждает адрес, порт и пароль.
5. Опубликуйте пробное сообщение из раздела Публикация и убедитесь, что подписчик его получил.

Пользователи и права

У каждой учётной записи есть список правил. Правило — это фильтр топиков, вид доступа (подписка, публикация или оба) и вердикт: разрешить или запретить. Не разрешено ничего, что не написано: запись без правил подключится и не сможет сделать ничего.

Подстановка $u раскрывается в имя учётной записи при подключении. Одно правило поэтому обслуживает тысячу устройств вместо тысячи правил: каждое видит только своё поддерево.

Откуда берутся учётные записи

Брокер может держать свой список или спрашивать у чего-то другого. Источник переключается на ходу, без перезапуска, поэтому новый способ можно проверить, пока старый ещё обслуживает.

• Встроенный. Учётные записи в собственной базе брокера. Подходит для нескольких десятков устройств.
• MariaDB / MySQL. Ваша таблица, запрос к ней пишется в настройках. Подходит, когда реестр устройств уже где-то есть.
• SQLite. Файл той же структуры — для системы, которая держит свои данные локально.
• CSV. Обычный файл, перечитываемый при изменении. Удобно для фиксированного списка, который формирует другой инструмент.
• JWT. Устройство предъявляет подписанный токен вместо пароля; брокер проверяет подпись и берёт права из его полей.
• HTTP. Брокер спрашивает вашу службу, можно ли этому клиенту подключиться, и служба отвечает. Всё, что вы уже сделали — блокировка устройств, тарифы, квоты, — начинает действовать без дублирования.

TLS

Укажите брокеру сертификат и ключ — на порту 8883 поднимется шифрованный слушатель; та же пара может использоваться и панелью. Для закрытой сети брокер умеет выпустить самоподписанную пару сам, и этого достаточно, чтобы пароли не ходили по проводу открытым текстом.

openssl s_client -connect broker.example.com:8883 -servername broker.example.com </dev/null | head -20

Мосты

Мост — это постоянное соединение с другим брокером и список топиков, которые через него переносятся. Направление задаётся для каждого топика: наружу отдаёт местные сообщения, внутрь забирает удалённые, оба делает и то и другое.

• С любой стороны можно добавить префикс, чтобы сообщения с удалённого объекта приходили под site-b/… и никогда не сталкивались с местными.
• Защита от петель не даёт отправить обратно сообщение, которое пришло через мост.
• Разорванное соединение восстанавливается с растущей паузой; очередь тем временем продолжает копиться.
• TLS и пароли настраиваются для каждого моста отдельно, поэтому у двух объектов могут быть разные сертификаты.

Отложенная публикация

Публикация в $delayed/<секунды>/<топик> отдаёт брокеру сообщение, которое надо доставить позже. Оно сохраняется, переживает перезапуск и видно в панели, где его можно отменить до срабатывания.

mosquitto_pub -h broker -t '$delayed/300/home/light/kitchen' -m 'off'

Синтаксис совпадает с EMQX, поэтому скрипты, написанные под тот брокер, работают без правок.

Ограничение трафика

Два механизма для разных бед. Ведро токенов на соединение не даёт одному клиенту залить брокер. Правила по топикам решают другую задачу — устройство просто слишком старательное: вместо того чтобы его отключить, поток прореживается до нужной частоты с сохранением самого свежего значения.

REST API

Панель — клиент того же API, которым можете пользоваться и вы. Создайте токен в настройках, решите, можно ли ему писать, и вызывайте из своей системы.

curl -X POST https://broker.example.com/api/users \
  -H 'Authorization: Bearer <токен>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"sensor-42","password":"...","acl":[{"filter":"devices/sensor-42/#","access":"both","allow":true}]}'

Что переживает перезапуск

• Сохранённые сообщения — последнее значение каждого топика, который просил его сохранить.
• Постоянные сессии — подписки клиентов, подключившихся с выключенным clean_session.
• Очереди сообщений QoS 1 и 2 для таких сессий, пока клиента нет.
• Отложенные сообщения, срок которых ещё не наступил.
• Пользователи, права, мосты, правила и настройки.

Всё это лежит в одном файле SQLite. Резервная копия брокера — копия этого файла; переезд на другую машину — перенос его туда.

Когда что-то не так

Частые вопросы