Продвинутый

Eclipse Mosquitto: настройка и использование MQTT-брокера

Алексей Кузнецов
Алексей Кузнецов
Системный администратор17 ноября 2026 г.11 мин чтения

Eclipse Mosquitto – открытый MQTT-брокер, инструкция по установке, настройке и использованию в домашней лаборатории и продакшене.

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

После изменения конфигурации перезапускаем сервис:

bash
sudo systemctl restart mosquitto

Сценарии применения в домашней лаборатории и продакшене

Домашняя лаборатория

В типичной домашней среде Mosquitto используется для связывания различных умных устройств: датчиков температуры, розеток, камер видеонаблюдения и системы управления освещением. Пример сценария:

  1. Датчик температуры публикует измерения на топике home/kitchen/temperature.
  2. Система Home Assistant подписывается на этот топик и при достижении порога > 25 °C отправляет уведомление.

Команда публикации (на Raspberry Pi с установленным Mosquitto):

bash
mosquitto_pub -h localhost -t home/kitchen/temperature -m "23.5" -u alice -P secret

Подписка в Home Assistant (yaml‑фрагмент):

yaml
mqtt:
  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 обеспечивает предсказуемость работы сети: сообщения доставляются в установленном порядке, а при падении одного из узлов другие автоматически переключаются на резервный брокер.

Eclipse Mosquitto: настройка open source MQTT‑брокера

Установка и базовая настройка для лаборатории

Установка через apt и Docker

Установка Mosquitto в домашней лаборатории обычно начинается с пакета из репозитория ОС. На Debian‑based системах (Ubuntu, Debian) достаточно выполнить:

bash
sudo apt update
sudo apt install mosquitto mosquitto-clients

После установки сервис автоматически запускается и включается в автозапуск:

bash
sudo systemctl enable --now mosquitto
sudo systemctl status mosquitto

Проверка показывает, что брокер слушает порт 1883 и готов принимать подключения.

Если вы предпочитаете изолировать брокер в контейнере, удобно использовать официальный образ Mosquitto. Пример запуска с Docker:

bash
docker 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:

yaml
version: "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

Запуск выглядит так:

bash
docker 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

Создание пользователя и пароля:

bash
sudo mosquitto_passwd -c /etc/mosquitto/passwd alice
# При появлении запроса введите пароль, затем подтвердите его.

После изменения конфигурации перезапустите сервис:

bash
sudo 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.

bash
openssl 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"
ini
listener 8883
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
require_certificate false
use_identity_as_username false

В Docker‑compose файл можно смонтировать конфиг и сертификаты:

yaml
services:
  mosquitto:
    image: eclipse-mosquitto:2
    ports:
      - "1883:1883"
      - "8883:8883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
ini
listener 8883
certfile /mosquitto/config/certs/server.crt
keyfile /mosquitto/config/certs/server.key

Аутентификация и авторизация

После включения TLS обычно отключают анонимный доступ и вводят авторизацию через парольный файл или ACL.

bash
mosquitto_passwd -c /etc/mosquitto/passwd alice
ini
allow_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‑токены.

ini
plugin_dir /usr/lib/mosquitto/plugins
ini
plugin {
  name "auth"
  config_path /etc/mosquitto/passwd
}

Для bridge‑ов используется встроенный плагин mosquitto_bridge:

ini
bridge {
  address broker1:1883
  address broker2:1884
  topic readwrite #
}

Clustering и high‑availability

Mosquitto не является кластером по‑умолчанию, но его можно масштабировать с помощью bridge‑ов или внешних бекендов, например Redis, для совместного хранения подписок.

yaml
version: "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
ini
bridge_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.

  1. Установка плагина
bash
# Debian/Ubuntu
sudo apt-get install mosquitto-plugins
# Alpine
apk add mosquitto-plugins
  1. Конфигурация 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.
  1. Настройка Prometheus
yaml
scrape_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 – текущее потребление памяти.

Эти данные позволяют отслеживать нагрузку и предсказуемость работы брокера.

Ссылка: Официальная документация Mosquitto – метрики.

### Визуализация в Grafana

После того как Prometheus начинает собирать метрики, их удобно визуализировать в Grafana.

  1. Добавление дата‑уса

    • В Grafana → Configuration → Data Sources → Add data source → Prometheus.
    • Укажите URL http://192.168.1.10:9090 (или IP  вашего Prometheus‑сервера).
  2. Создание дашборда

    • New → Dashboard → Add a new panel.

    • В поле Query введите, например:

      promql
      sum(rate(mosquitto_messages_sent_total[1m]))
      
    • Для отображения активных соединений:

      promql
      mosquitto_connections
      
    • Добавьте панель Stat для mosquitto_memory_usage_bytes чтобы видеть потребление ОЗУ.

  3. Пример дашборда

    Grafana dashboard example
    Скриншот дашборда, показывающий активные соединения, пропускную способность и память.

Ссылка: Grafana documentation – creating dashboards.

### Анализ логов

Mosquitto пишет логи в syslog или в файл /var/log/mosquitto/mosquitto.log. При включённом JSON‑логировании удобно использовать jq.

  1. Включение JSON‑логирования
conf
log_dest jsonfile
log_dest stdout
  1. Просмотр логов в реальном времени
bash
journalctl -u mosquitto -f
# или, если логи в файле:
tail -f /var/log/mosquitto/mosquitto.log
  1. Пример записи JSON‑лога
json
{
  "timestamp": "2025-10-31T12:00:01Z",
  "level": "error",
  "msg": "Authentication failed: Invalid username or password",
  "client_id": "client_42",
  "username": "alice"
}
  1. Поиск типовых ошибок
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.

  1. Проверьте файл passwd:
bash
cat /etc/mosquitto/passwd
  1. Если запись отсутствует, создайте её:
bash
sudo mosquitto_passwd -c /etc/mosquitto/passwd alice
# введите пароль, подтвердите
  1. Перезапустите Mosquitto:
bash
sudo 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, и пользователь будет иметь доступ только к указанному топику. Такой подход позволяет точно настроить доступ без изменения прав у остальных клиентов.

Поделиться:TelegramX / TwitterVK

Читайте также