Eclipse Mosquitto: настройка и использование MQTT-брокера
Eclipse Mosquitto – открытый MQTT-брокер, инструкция по установке, настройке и использованию в домашней лаборатории и продакшене.
Mosquitto: возможности и типичные сценарии для IoT
Основные возможности MQTT‑брокера
MQTT — это легковесный протокол обмена сообщениями, предназначенный для работы в условиях ограниченной пропускной способности и нестабильных сетей. Eclipse Mosquitto реализует большинство функций, которые требуются в IoT‑системах:
- Publish/Subscribe — клиенты публикуют данные на заданные топики, а брокер рассылает их всем подписчикам.
- QoS 1‑3 — три уровня подтверждения доставки: «не менее одного», «не менее двух», «точные» (exactly‑once).
- Retained messages — брокер сохраняет последнее сообщение на топике, чтобы новые подписчики сразу получали актуальное состояние (например, текущий уровень влажности).
- Access Control Lists (ACL) — можно задавать права чтения/записи per‑user или per‑IP, а также использовать TLS‑аутентификацию.
- TLS/SSL — шифрование канала и клиентская аутентификация, что критично для продакшена.
- Clustering и Bridges — возможность соединять несколько экземпляров брокера и перенаправлять трафик между отдельными сетями.
Пример базовой конфигурации (/etc/mosquitto/mosquitto.conf):
conf# Слушать все интерфейсы, но без анонимного доступа listener 1883 allow_anonymous false password_file /etc/mosquitto/passwd # TLS‑слушатель для зашифрованных соединений listener 8883 cafile /etc/mosquitto/certs/ca.crt certfile /etc/mosquitto/certs/server.crt keyfile /etc/mosquitto/certs/server.key require_certificate false
После изменения конфигурации перезапускаем сервис:
bashsudo systemctl restart mosquitto
Сценарии применения в домашней лаборатории и продакшене
Домашняя лаборатория
В типичной домашней среде Mosquitto используется для связывания различных умных устройств: датчиков температуры, розеток, камер видеонаблюдения и системы управления освещением. Пример сценария:
- Датчик температуры публикует измерения на топике
home/kitchen/temperature. - Система Home Assistant подписывается на этот топик и при достижении порога > 25 °C отправляет уведомление.
Команда публикации (на Raspberry Pi с установленным Mosquitto):
bashmosquitto_pub -h localhost -t home/kitchen/temperature -m "23.5" -u alice -P secret
Подписка в Home Assistant (yaml‑фрагмент):
yamlmqtt:
broker: localhost
port: 1883
username: alice
password: secret
discovery: true
topic_prefix: home
Продакшен
В продакшене Mosquitto часто выступает в роли центрального брокера для микросервисов, собирающих данные от сотен датчиков. Примеры типичных сценариев:
- Агрегация метрик — каждый микросервис публикует события в отдельный топик (
metrics/cpu,metrics/memory). С помощью bridge можно перенаправить их в InfluxDB или Prometheus. - Обратная связь — контроллеры (например, умные розетки) публикуют состояние (
device/room1/state) и получают команды (device/room1/set) от централизованного управляющего. - QoS 2 — гарантирует точную доставку критически важных команд (например, «выключить насоса»).
Конфигурация моста между двумя брокерами (внутренний и внешний):
conf# Внутренний брокер bridge_address internal.example.com:1883 bridge_cafile /etc/mosquitto/certs/ca.crt bridge_certfile /etc/mosquitto/certs/server.crt bridge_keyfile /etc/mosquitto/certs/server.key bridge_username bridge_user bridge_password bridge_pass bridge_topic_prefix internal/
conf# Внешний брокер (облачный) bridge_address cloud.example.com:8883 bridge_cafile /etc/mosquitto/certs/ca.crt bridge_certfile /etc/mosquitto/certs/server.crt bridge_keyfile /etc/mosquitto/certs/server.key bridge_username cloud_user bridge_password cloud_pass bridge_topic_prefix external/
Таким образом, Mosquitto обеспечивает предсказуемость работы сети: сообщения доставляются в установленном порядке, а при падении одного из узлов другие автоматически переключаются на резервный брокер.
Установка и базовая настройка для лаборатории
Установка через apt и Docker
Установка Mosquitto в домашней лаборатории обычно начинается с пакета из репозитория ОС. На Debian‑based системах (Ubuntu, Debian) достаточно выполнить:
bashsudo apt update
sudo apt install mosquitto mosquitto-clients
После установки сервис автоматически запускается и включается в автозапуск:
bashsudo systemctl enable --now mosquitto
sudo systemctl status mosquitto
Проверка показывает, что брокер слушает порт 1883 и готов принимать подключения.
Если вы предпочитаете изолировать брокер в контейнере, удобно использовать официальный образ Mosquitto. Пример запуска с Docker:
bashdocker run -d \ --name mosquitto \ -p 1883:1883 \ -p 8883:8883 \ -v /path/to/mosquitto/config:/mosquitto/config \ -v /path/to/mosquitto/data:/mosquitto/data \ eclipse-mosquitto:2
В этом примере конфигурационный файл и данные сохраняются на хосте, что упрощает их редактирование и сохранение между перезапусками.
Для удобства можно описать всё в Docker‑Compose. Пример docker-compose.yml:
yamlversion: "3.8"
services:
mosquitto:
image: eclipse-mosquitto:2
container_name: mosquitto
ports:
- "1883:1883"
- "8883:8883"
volumes:
- ./mosquitto/config:/mosquitto/config
- ./mosquitto/data:/mosquitto/data
restart: unless-stopped
Запуск выглядит так:
bashdocker compose up -d
Оба способа (apt и Docker) позволяют быстро получить работающий брокер в домашней лаборатории. Выбор зависит от предпочтений в управлении конфигурацией и уровне изоляции.
Eclipse Mosquitto: настройка open source MQTT‑брокера
Конфигурация mosquitto.conf и базовые параметры
Файл конфигурации обычно находится в /etc/mosquitto/mosquitto.conf или в поддиректории /etc/mosquitto/conf.d/. Ниже пример минимального набора параметров, который подходит для большинства сценариев:
conf# Прослушиваем стандартный порт MQTT listener 1883 # Позволяем анонимским подключениям (для тестов). В продакшене рекомендуется отключить. allow_anonymous true # Путь к файлу паролей password_file /etc/mosquitto/passwd # Ограничение на количество одновременных соединений max_connections 10000 # Включаем хранение сообщений на диске (persistence) persistence true persistence_location /var/lib/mosquitto/ # Уровень логирования (warning, info, debug) log_type warning
Создание пользователя и пароля:
bashsudo mosquitto_passwd -c /etc/mosquitto/passwd alice
# При появлении запроса введите пароль, затем подтвердите его.
После изменения конфигурации перезапустите сервис:
bashsudo systemctl restart mosquitto
Ключевые параметры
listener— порт, на котором брокер принимает соединения. Можно добавить TLS‑listener, указавssl_options.allow_anonymous— управляет тем, можно ли подключаться без авторизации. Для продакшена лучше установитьfalseи использоватьpassword_file.max_connections— защита от перегрузки сервера; значение подбирается в зависимости от нагрузки.persistence— сохраняет очередь сообщений на диск, что гарантирует доставку даже при перезапуске.log_type— уровень детализации логов; в лаборатории достаточноwarning, в продакшене можно повысить доinfoилиdebug.
Если вы используете Docker, те же параметры задаются в файле конфигурации, который вы монтируете в контейнер (см. пример выше). При необходимости можно добавить параметр listener 8883 для TLS‑соединений и указать require_certificate true.
При правильной настройке Mosquitto обеспечивает предсказуемую работу: сообщения доставляются в том порядке, в котором они были отправлены, а конфигурация остаётся стабильной при изменении количества клиентов. Это и есть основная «рабочая» часть брокера, с которой дальше можно приступать к тестированию и интеграции с другими сервисами.
Продвинутые сценарии и интеграция в продакшене
В продакшене Mosquitto обычно используют в сочетании TLS, авторизацию и высокий уровень доступности. Подробности по базовой настройке можно посмотреть в Eclipse Mosquitto: настройка open source MQTT‑брокера.
TLS/SSL
Для защиты канала используют TLS. Можно генерировать самоподписанные сертификаты или брать их от CA, например Let's Encrypt.
bashopenssl req -new -newkey rsa:2048 -days 365 -nodes -x509 \
-out /etc/mosquitto/certs/server.crt \
-keyout /etc/mosquitto/certs/server.key \
-subj "/C=RU/ST=Moscow/L=City/O=MyCompany/OU=IT/CN=broker.example.com"
inilistener 8883 certfile /etc/mosquitto/certs/server.crt keyfile /etc/mosquitto/certs/server.key require_certificate false use_identity_as_username false
В Docker‑compose файл можно смонтировать конфиг и сертификаты:
yamlservices:
mosquitto:
image: eclipse-mosquitto:2
ports:
- "1883:1883"
- "8883:8883"
volumes:
- ./mosquitto/config:/mosquitto/config
inilistener 8883 certfile /mosquitto/config/certs/server.crt keyfile /mosquitto/config/certs/server.key
Аутентификация и авторизация
После включения TLS обычно отключают анонимный доступ и вводят авторизацию через парольный файл или ACL.
bashmosquitto_passwd -c /etc/mosquitto/passwd alice
iniallow_anonymous false password_file /etc/mosquitto/passwd
Пример файла ACL (/etc/mosquitto/acl.conf):
user alice
topic readwrite #
user bob
topic read #
user *
$SYS/# #
Плагины
Mosquitto поддерживает плагины, расширяющие функциональность. Один из популярных — mosquitto_auth_plugin, позволяющий использовать JWT‑токены.
iniplugin_dir /usr/lib/mosquitto/plugins
iniplugin { name "auth" config_path /etc/mosquitto/passwd }
Для bridge‑ов используется встроенный плагин mosquitto_bridge:
inibridge {
address broker1:1883
address broker2:1884
topic readwrite #
}
Clustering и high‑availability
Mosquitto не является кластером по‑умолчанию, но его можно масштабировать с помощью bridge‑ов или внешних бекендов, например Redis, для совместного хранения подписок.
yamlversion: "3.8"
services:
broker1:
image: eclipse-mosquitto:2
ports:
- "1883:1883"
- "8883:8883"
volumes:
- ./broker1/config:/mosquitto/config
- ./broker1/data:/mosquitto/data
broker2:
image: eclipse-mosquitto:2
ports:
- "1884:1884"
- "8884:8884"
volumes:
- ./broker2/config:/mosquitto/config
- ./broker2/data:/mosquitto/data
bridge:
image: eclipse-mosquitto:2
command: ["-c", "/mosquitto/config/bridge.conf"]
volumes:
- ./bridge/bridge.conf:/mosquitto/config/bridge.conf
inibridge_address broker1:1883
bridge_address broker2:1884
topic readwrite #
Для повышения доступности broker‑ов можно использовать systemd‑юнит с автоматическим перезапуском:
ini[Unit]
Description=Mosquitto MQTT broker
After=network.target
[Service]
ExecStart=/usr/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
Эти приёмы позволяют построить надёжную MQTT‑инфраструктуру, удовлетворяющую требованиям продакшена.
Мониторинг, логирование и поддержка серверов
### Сбор метрик Prometheus
Eclipse Mosquitto начиная с версии 2.0 предоставляет встроенный exporter Prometheus – набор метрик, которые можно собирать scrap‑ом Prometheus.
- Установка плагина
bash# Debian/Ubuntu
sudo apt-get install mosquitto-plugins
# Alpine
apk add mosquitto-plugins
- Конфигурация Mosquitto
conf# /etc/mosquitto/mosquitto.conf listener 1883 allow_anonymous false password_file /etc/mosquitto/passwd # Включаем экспорт метрик metrics_port 9182 metrics_file /var/log/mosquitto/mosquitto.prom
metrics_port– порт, на котором exporter будет слушать запросы Prometheus (по‑умолчанию 9182).metrics_file– файл, в который exporter будет писать текущие метрики в формате Prometheus text‑based.
- Настройка Prometheus
yamlscrape_configs:
- job_name: 'mosquitto'
static_configs:
- targets: ['192.168.1.10:9182']
Метрики, которые появятся в Prometheus, включают:
mosquitto_connections– кол‑во активных TCP‑соединений.mosquitto_messages_sent_total– общее количество отправленных сообщений.mosquitto_messages_received_total– общее количество полученных сообщений.mosquitto_memory_usage_bytes– текущее потребление памяти.
Эти данные позволяют отслеживать нагрузку и предсказуемость работы брокера.
### Визуализация в Grafana
После того как Prometheus начинает собирать метрики, их удобно визуализировать в Grafana.
-
Добавление дата‑уса
- В Grafana → Configuration → Data Sources → Add data source → Prometheus.
- Укажите URL
http://192.168.1.10:9090(или IP вашего Prometheus‑сервера).
-
Создание дашборда
-
New → Dashboard → Add a new panel.
-
В поле Query введите, например:
promqlsum(rate(mosquitto_messages_sent_total[1m])) -
Для отображения активных соединений:
promqlmosquitto_connections -
Добавьте панель Stat для
mosquitto_memory_usage_bytesчтобы видеть потребление ОЗУ.
-
-
Пример дашборда

Скриншот дашборда, показывающий активные соединения, пропускную способность и память.
### Анализ логов
Mosquitto пишет логи в syslog или в файл /var/log/mosquitto/mosquitto.log. При включённом JSON‑логировании удобно использовать jq.
- Включение JSON‑логирования
conflog_dest jsonfile log_dest stdout
- Просмотр логов в реальном времени
bashjournalctl -u mosquitto -f
# или, если логи в файле:
tail -f /var/log/mosquitto/mosquitto.log
- Пример записи JSON‑лога
json{
"timestamp": "2025-10-31T12:00:01Z",
"level": "error",
"msg": "Authentication failed: Invalid username or password",
"client_id": "client_42",
"username": "alice"
}
- Поиск типовых ошибок
bash# Ошибки аутентификации
jq '.' /var/log/mosquitto/mosquitto.json | grep -i "authentication failed"
# Подключение закрыто по ACL
jq '.' /var/log/mosquitto/mosquitto.json | grep -i "ACL denied"
### Типичные проблемы и их решение
| Проблема | Причина | Решение |
|---|---|---|
| Порт 1883 не открыт | Фаервол ufw/iptables блокирует соединения. | sudo ufw allow 1883/tcp или iptables -A INPUT -p tcp --dport 1883 -j ACCEPT. |
| Клиенты не могут подключиться | allow_anonymous true или неправильный password_file. | Убедитесь, что allow_anonymous false и файл /etc/mosquitto/passwd содержит корректные записи (mosquitto_passwd -c /etc/mosquitto/passwd user). |
| Высокий CPU | Много сообщений, очередь растёт. | Увеличьте max_inflight_messages и max_queue_size в mosquitto.conf, либо ограничьте количество клиентов через max_connections. |
| Нехватка памяти | Большие сообщения, many retained messages. | Настройте memory_limit в systemd‑unit (Systemd: MemoryLimit=2G) и включите max_retained_messages = 0, если хранение retained‑сообщений не требуется. |
| ACL‑правила не применяются | Файл acl_file не указан или не читается. | Добавьте в mosquitto.conf строку acl_file /etc/mosquitto/acl.conf и проверьте права доступа к файлу. |
| Таймауты соединения | Недостаточное значение keepalive на клиенте. | Установите keepalive 60 на клиенте и timeout 30 на сервере (в mosquitto.conf). |
Практический пример – проблема с Authentication failed.
- Проверьте файл
passwd:
bashcat /etc/mosquitto/passwd
- Если запись отсутствует, создайте её:
bashsudo mosquitto_passwd -c /etc/mosquitto/passwd alice
# введите пароль, подтвердите
- Перезапустите Mosquitto:
bashsudo systemctl restart mosquitto
После этого клиент alice должен успешно аутентифицироваться.
Если настроить метрики Prometheus и Grafana правильно, а также регулярно анализировать логи, управление Mosquitto в домашней лаборатории станет предсказуемым. Настройка, мониторинг и документирование – это не «разбор», а часть системного подхода, который гарантирует стабильную работу MQTT‑брокера.
Часто задаваемые вопросы
Как установить Eclipse Mosquitto на Ubuntu и задать пароль для пользователей?
Для установки достаточно выполнить sudo apt-get install mosquitto mosquitto-clients, после чего файл конфигурации находится в /etc/mosquitto/mosquitto.conf. Чтобы задать пароль, используйте команду sudo mosquitto_passwd -c /etc/mosquitto/passwd username, где -c создаёт новый файл, а без него добавляет запись в существующий. После изменения пароля перезапустите сервис командой sudo systemctl restart mosquitto. Это обеспечит аутентификацию без анонимного доступа.
Как включить TLS‑шифрование и клиентскую аутентификацию?
В конфигурационном файле добавьте отдельный listener 8883 и укажите cafile, certfile и keyfile для сертификатов, а также require_certificate true для обязательной проверки клиентского сертификата. После этого клиенты должны использовать указанный CA‑сертификат при подключении, иначе соединение будет отклонено. Перезапуск сервиса (sudo systemctl restart mosquitto) активирует TLS‑соединение. Такой режим необходим для продакшн‑средов, где конфиденциальность данных критична.
Что такое retained‑сообщения и как их использовать в домашней автоматизации?
Retained‑сообщение — это последняя публикация на конкретном топике, которую брокер сохраняет и сразу отправляет всем новым подписчикам при их подключении. Чтобы установить retained‑сообщение, публикуйте данные с флагом retain (например, через mosquitto_pub -h <host> -t home/room/temperature -m "25" -r). Это удобно для состояний, которые часто запрашиваются, например, текущего уровня влажности или включения света. При подключении новых клиентов они получат актуальное значение без дополнительных запросов.
Как ограничить права доступа конкретного пользователя на определённый топик?
Для этого в файле /etc/mosquitto/passwd создайте пользователя, а затем в конфигурации укажите acl_file /etc/mosquitto/acl.conf. В acl.conf добавьте строку user <username> topic readwrite home/sensor/temperature, где readwrite задаёт права. После сохранения перезапустите Mosquitto, и пользователь будет иметь доступ только к указанному топику. Такой подход позволяет точно настроить доступ без изменения прав у остальных клиентов.