Продвинутый

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

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

Разбор Eclipse Mosquitto – open source MQTT‑broker, инструкция по установке, конфигурации и эксплуатации в домашней лаборатории.

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

Разбор Eclipse Mosquitto – open source MQTT‑broker, инструкция по установке, конфигурации и эксплуатации в домашней лаборатории.

Обзор Mosquitto: назначение и ключевые возможности

Основные возможности MQTT‑брокера

Eclipse Mosquitto – это лёгкий open source‑брокер, реализующий протокол MQTT 5.0 (с поддержкой 3.1.1). Он подходит как для небольших домашних сетей, так и для промышленных решений.

  • Publish/Subscribe – клиенты публикуют сообщения на темы, а брокер доставляет их подписчикам. Тема – строка, разделённая символом /, что позволяет легко группировать данные (например, home/kitchen/temperature).
  • QoS‑уровни – три уровня доставки:
    • QoS 0 – «не менее одного» (fire‑and‑forget);
    • QoS 1 – «не менее одного», гарантирует доставку, но без idempotent‑свойства;
    • QoS 2 – «ровно один», гарантирует отсутствие дублирования.
  • Retained‑messages – брокер сохраняет последнее сообщение на теме, чтобы новые подписчики сразу получали актуальное значение.
  • Last Will and Testament (LWT) – при неожиданном разрыве соединения брокер публикует заранее заданное сообщение, что удобно для мониторинга «жизнедеятельности» устройств.
  • Authentication & Authorization – поддержка username/password, ACL‑файлов и интеграция с внешними провайдерами (OAuth, JWT).
  • TLS/SSL – шифрование канала без необходимости отдельного reverse‑proxy.
  • Clustering и Bridge – возможность собрать несколько экземпляров в кластер или настроить bridge‑соединение с другими MQTT‑серверами (например, облачными).
  • Плагин‑система – расширяемость через Lua‑скрипты, Python‑плагины и C‑модули.

Пример базовой конфигурации (/etc/mosquitto/mosquitto.conf):

ini
# Enable listener on default port 1883
listener 1883

# Enable TLS listener on 8883
listener 8883
protocol mqtt
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
require_certificate false
use_identity_as_username true

# ACL‑файл (по умолчаниюmosquitto.hcl)
acl_file /etc/mosquitto/acl.conf

# Логи
log_type all
log_dest file
log_file /var/log/mosquitto/mosquitto.log

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

bash
sudo systemctl restart mosquitto

Сценарии применения в IoT и облачных сервисах

В домашней лаборатории Mosquitto часто выступает «локальным» брокером, который собирает данные с датчиков, камер, бытовых приборов и передаёт их в облачные сервисы или в локальные приложения.

  • Домótica – датчики температуры, влажности, состояния световых приборов публикуют сообщения в темы home/<room>/sensor/<type>. Подписчики (например, Home Assistant, Node‑RED) получают обновления в реальном времени без постоянного опроса.

    bash
    # Пример публикации температуры с retained‑message
    mosquitto_pub -t "home/kitchen/temperature" -m "22.3" -q 1 -r
    
  • Сбора метрик – Prometheus‑exporter может публиковать метрики в MQTT, а Grafana + Mosquitto‑bridge позволяют визуализировать их в дашбордах.

  • Облачные сервисы – Mosquitto может работать как bridge между локальной сетью и облачными MQTT‑сервисами (AWS IoT Core, Azure IoT Hub, Google Cloud IoT). Это упрощает миграцию и обеспечивает fallback‑режим при потере интернета.

    bash
    # Пример настройки bridge в конфиге
    bridge_address cloud.mqtt.server
    bridge_cafile /etc/mosquitto/certs/ca.crt
    bridge_certfile /etc/mosquitto/certs/client.crt
    bridge_keyfile /etc/mosquitto/certs/client.key
    bridge_username cloud_user
    bridge_password secret
    
  • Автоматическое резервное копирование – при использовании mosquitto_pub с параметром -s (создание резервной копии) можно сохранять историю сообщений в файл, а затем восстанавливать их после перезапуска брокера.

  • Кластеризация – в larger‑scale домах (более 10‑20 нод) удобно запускать несколько экземпляров Mosquitto в Proxmox‑контейнерах и объединять их через cluster‑модуль. Это повышает отказоустойчивость и позволяет распределять нагрузку.

Практический пример:
Установим Mosquitto в Docker‑контейнере, добавим TLS и включим LWT:

bash
docker run -d \
  --name mosquitto \
  -p 1883:1883 -p 8883:8883 \
  -v /etc/mosquitto/conf.d:/mosquitto/config \
  -v /etc/mosquitto/certs:/mosquitto/certs \
  eclipse-mosquitto:2

После старта проверяем работу:

bash
mosquitto_sub -t "test/hello" -v
# в другом терминале
mosquitto_pub -t "test/hello" -m "world" -q 1

Подписчик сразу получит сообщение «world», а если брокер упадёт, при следующем подключении будет опубликовано последнее retained‑сообщение (если оно задано).

Таким образом, Mosquitto обеспечивает гибкую, надёжную и простую в управлении инфраструктуру обмена данными как в небольших IoT‑проектах, так и в более сложных облачных решениях.

Установка и базовая настройка Mosquitto в Linux

Установка через пакетные менеджеры

Когда речь заходит о развёртывании инфраструктуры, я всегда сторонник предсказуемости. Для Mosquitto в среде Linux проще и надёжнее всего использовать системные репозитории. Это гарантирует, что сервис будет корректно интегрирован с systemd, а зависимости — подтянуты автоматически.

Если вы используете Debian или Ubuntu, установка выполняется одной командой. Сначала обновите индекс пакетов, чтобы получить актуальную версию из репозитория:

bash
sudo apt update
sudo apt install mosquitto mosquitto-clients

Пакет mosquitto-clients я рекомендую ставить сразу. Он включает в себя утилиты mosquitto_pub и mosquitto_sub, которые жизненно необходимы для быстрой проверки работоспособности брокера через терминал.

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

bash
systemctl status mosquitto

Если сервис не активен, запустите его и добавьте в автозагрузку:

bash
sudo systemctl enable --now mosquitto

Для тех, кто предпочитает более минималистичные системы вроде Alpine Linux, процесс аналогичен, но использует apk:

bash
apk add mosquitto mosquitto-clients

Настройка listener-портов и ACL

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

Все основные настройки хранятся в файле /etc/mosquitto/mosquitto.conf. Я предпочитаю не раздувать основной конфиг, а использовать директорию conf.d для модульных настроек. Создайте отдельный файл, например /etc/mosquitto/conf.d/default.conf, чтобы управлять слушателями (listeners).

Пример конфигурации, который открывает порт 1883 для всех интерфейсов, но требует авторизации:

conf
# Слушаем на всех сетевых интерфейсах на стандартном порту
listener 1883 0.0.0.0

# Запрещаем анонимные подключения. 
# Это критически важно для безопасности, даже в домашней сети.
allow_anonymous false

# Путь к файлу с паролями пользователей
password_file /etc/mosquitto/passwd

После внесения изменений обязательно проверьте синтаксис и перезапустите сервис:

bash
sudo systemctl restart mosquitto

Если вам нужно разграничить права доступа (например, чтобы датчик температуры мог только публиковать данные, а панель управления — только подписываться), необходимо настроить ACL (Access Control Lists).

Создайте файл /etc/mosquitto/aclfile и опишите правила. С точки зрения системного инженера, это лучший способ избежать ситуации, когда один скомпрометированный IoT-девайс начинает спамить во все топики системы.

Пример файла ACL:

conf
# Пользователь 'sensor_node' может только публиковать в топик датчиков
user sensor_node
topic write sensors/temperature

# Пользователь 'dashboard' может только читать данные
user dashboard
topic read sensors/#

# Администратор имеет полный доступ
user admin
topic #

Чтобы применить эти правила, добавьте строку acl_file /etc/mosquitto/aclfile в ваш основной конфигурационный файл.

Для создания пользователей и назначения им паролей используйте утилиту mosquitto_passwd. Например, чтобы создать пользователя sensor_node:

bash
sudo mosquitto_passwd -c /etc/mosquitto/passwd sensor_node

Флаг -c создаст новый файл. Если вы добавляете второго пользователя, используйте флаг -b (для автоматизации) или просто уберите -c, чтобы дописать данные в существующий файл:

bash
sudo mosquitto_passwd /etc/mosquitto/passwd dashboard

Теперь ваша конфигурация стала предсказуемой: каждый клиент имеет строго определённую зону ответственности, а анонимный доступ закрыт.

Оптимизация, масштабирование и безопасность

TLS/SSL и защита соединений

Для шифрования трафика MQTT‑брокер должен принимать подключения по TLS.
Самый простой способ — создать самоподписанный сертификат и указать его в конфигурации Mosquitto. В реальном домашнем сервере удобно использовать сертификат от Let’s Encrypt, полученный для доменного имени, под которым будет доступен брокер (например, mqtt.example.com).

Генерация сертификата

bash
# создаём приватный ключ и самоподписанный сертификат на 1 год
openssl req -new -x509 -days 365 -nodes \
    -out /etc/mosquitto/certs/broker.crt \
    -keyout /etc/mosquitto/certs/broker.key \
    -subj "/C=RU/ST=Moscow/L=Moscow/O=HomeLab/OU=IT/CN=mqtt.example.com"

Если используете Let’s Encrypt, сертификат уже лежит в /etc/letsencrypt/live/mqtt.example.com/fullchain.pem, а приватный ключ — в privkey.pem. В этом случае в конфиге указываете пути к этим файлам.

Пример конфигурации Mosquitto (файл /etc/mosquitto/conf.d/tls.conf)

conf
# listener для зашифрованных соединений
listener 8883
# путь к сертификату и ключу
certfile /etc/mosquitto/certs/broker.crt
keyfile  /etc/mosquitto/certs/broker.key
# требуем TLS, но не требуем клиентский сертификат
require_certificate false
# optional: проверка цепочки доверия (CA)
cafile /etc/mosquitto/certs/ca.crt
# если нужен mutual TLS, замените require_certificate на true и укажите cafile/capath

Подключение клиента

bash
mosquitto_sub -h mqtt.example.com -p 8883 --tls-version tlsv1.2 --cafile /etc/mosquitto/certs/ca.crt -t 'test/topic'

Аутентификация без анонимного доступа

bash
# создаём файл паролей (пример для пользователя alice)
mosquitto_passwd -c /etc/mosquitto/passwd alice
# в конфиге включаем авторизацию и отключаем анонимный доступ
allow_anonymous false
password_file /etc/mosquitto/passwd

После перезапуска сервиса (systemctl restart mosquitto) клиент будет вынужден авторизоваться паролем alice.


Cluster и high‑availability

Один экземпляр Mosquitto не обеспечивает отказоустойчивость: при падении процесса брокер становится недоступен. В домашней лаборатории обычно используют два (или более) брокера и распределяют нагрузку через балансировщик (HAProxy) или реализуют «броджинг» тем между узлами. Оба подхода позволяют сохранять доступность даже при отказе одного из узлов.

Броджинг тем между брокерами

На каждом брокере включаем Bridge‑модуль и указываем друг друга в конфигурации.

Broker 1 (/etc/mosquitto/conf.d/bridge.conf)

conf
# основной listener (можно оставить без TLS, если клиенты работают в LAN)
listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

# bridge‑направление всех тем к брокеру 2
bridge_branch topic/
bridge_host broker2.example.com:1883
bridge_username alice
bridge_password secret
bridge_cafile /etc/mosquitto/certs/ca.crt
bridge_capath /etc/mosquitto/certs

Broker 2 (/etc/mosquitto/conf.d/bridge.conf)

conf
listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

bridge_branch topic/
bridge_host broker1.example.com:1883
bridge_username alice
bridge_password secret
bridge_cafile /etc/mosquitto/certs/ca.crt
bridge_capath /etc/mosquitto/certs

После перезапуска обоих сервисов (systemctl restart mosquitto) любой клиент, подключившийся к брокеру 1, будет получать сообщения, опубликованные на брокере 2, и наоборот. Это обеспечивает распределение нагрузки и частичную отказоустойчивость: если один узел выходит из строя, другой продолжит принимать подключения.

HAProxy как единый точка входа

Если хотите скрыть количество брокеров за одним IP‑адресом, используйте HAProxy. Пример конфигурации (/etc/haproxy/haproxy.cfg):

cfg
global
    log /dev/log    local0
    maxconn 2000
    daemon

defaults
    log     global
    mode    tcp
    option  tcplog
    timeout connect 5s
    timeout client  30s
    timeout server  30s

frontend mqtt_in
    bind *:1883
    default_backend brokers

backend brokers
    balance roundrobin
    server broker1 192.168.1.10:1883 check
    server broker2 192.168.1.11:1883 check

Запуск и проверка:

bash
systemctl restart haproxy
systemctl status haproxy

Клиент будет подключаться к mqtt.example.com:1883, а HAProxy автоматически передаст запрос одному из доступных брокеров. При отказе одного сервера HAProxy переключит клиента на оставшийся, что делает схему полностью отказоустойчивой.

Проверка работоспособности

bash
# проверка доступности брокера через HAProxy
mosquitto_pub -h mqtt.example.com -p 1883 -t 'test/ha' -m 'alive' -u alice -P secret

Если сообщение приходит без ошибок, кластер работает корректно.


В итоге TLS / SSL защищает конфиденциальность данных, а кластер или балансировщик гарантируют, что ваш MQTT‑сервис будет доступен даже при отказе отдельного узла. Оба подхода легко реализовать в домашней лаборатории, используя уже знакомые инструменты: OpenSSL, Mosquitto и HAProxy.

Мониторинг, логирование и поддержка в инфраструктуре

Интеграция с Prometheus и Grafana

Eclipse Mosquitto не экспортирует метрики из коробки, но в экосистеме есть лёгкий exporter — mosquitto_exporter. Он подключается к брокеру по MQTT, собирает статистику (соединения, топики, сообщения) и отдаёт их в формате Prometheus.

Установка exporter

bash
# На Ubuntu/Debian
apt-get update
apt-get install -y mosquitto-exporter

Конфигурация Mosquitto

toml
# /etc/mosquitto/conf.d/metrics.conf
allow_anonymous false
password_file /etc/mosquitto/passwd/exporter
listener 1883
# Exporter будет использовать отдельный пользователь, поэтому
# разрешаем только ему подключаться
acl_file /etc/mosquitto/conf.d/metrics_acl.conf
toml
# /etc/mosquitto/conf.d/metrics_acl.conf
pattern read $SYS/#   # только чтение системных тем

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

bash
# создаём системного пользователя
adduser --system --group --no-create-home mosquitto_exporter

# задаём пароль (в примере – mosquitto123)
mosquitto_passwd -c /etc/mosquitto/passwd/exporter mosquitto_exporter
# (при необходимости добавляем ещё пользователей)

Запускаем exporter в качестве systemd‑службы:

ini
# /etc/systemd/system/mosquitto-exporter.service
[Unit]
Description=Prometheus exporter for Mosquitto
After=network.target

[Service]
User=mosquitto_exporter
Group=mosquitto_exporter
ExecStart=/usr/bin/mosquitto_exporter \
  --mosquitto.url=tcp://127.0.0.1:1883 \
  --mosquitto.username=exporter \
  --mosquitto.password=mosquitto123 \
  --listen-address=:9183
Restart=on-failure

[Install]
WantedBy=multi-user.target
bash
systemctl daemon-reload
systemctl enable --now mosquitto-exporter

Настройка Prometheus

yaml
# /etc/prometheus/prometheus.yml
scrape_configs:
  - job_name: 'mosquitto'
    static_configs:
      - targets: ['127.0.0.1:9183']

Перезапускаем Prometheus:

bash
systemctl restart prometheus

Grafana‑дашборд

Официальный дашборд — Mosquitto Exporter Dashboard.
Импортируйте JSON‑файл, укажите источник данных Prometheus, и вы получите визуализацию соединений, топиков, скорости сообщений и других метрик.


Ведение журналов и резервное копирование

Журналы Mosquitto

По умолчанию брокер пишет в системный журнал, но удобнее настроить отдельный файл:

toml
# /etc/mosquitto/conf.d/logging.conf
log_type all
log_dest file
log_file /var/log/mosquitto/mosquitto.log
log_level notice

Системд‑журнал по‑прежнему работает, но файл позволяет удобно управлять ротацией.

Logrotate

conf
# /etc/logrotate.d/mosquitto
/var/log/mosquitto/mosquitto.log {
    weekly
    rotate 4
    compress
    missingok
    notifempty
    create 640 mosquitto adm
    postrotate
        systemctl reload mosquitto > /dev/null 2>&1 || true
    endscript
}

Резервное копирование конфигурации и данных

Если вы используете постоянное хранилище (например, persistence true в mosquitto.conf), копировать нужно всё дерево конфигурации и данные:

bash
# Пример резервного копирования на внешний диск /mnt/backup
rsync -a --delete /etc/mosquitto/ /mnt/backup/mosquitto-config/
rsync -a --delete /var/lib/mosquitto/ /mnt/backup/mosquitto-data/

Для более надёжной защиты можно добавить шифрование и удалённый хранилище, например, с помощью restic:

bash
# Инициализация репозитория (один раз)
restic init -r s3:s3.amazonaws.com/backup-bucket/mosquitto

# Выполнение бэкапа
restic -r s3:s3.amazonaws.com/backup-bucket/mosquitto backup /etc/mosquitto /var/lib/mosquitto

Планируйте запуск скрипта ежедневно через cron:

cron
0 2 * * * /usr/local/bin/mosquitto-backup.sh >> /var/log/mosquitto/backup.log 2>&1

Проверка целостности

После копирования полезно проверить, что брокер сможет стартовать из резервной копии:

bash
# Останавливаем текущий экземпляр
systemctl stop mosquitto

# Заменяем каталог данных (пример)
systemctl start mosquitto

Если всё работает, значит резервная копия готова к восстановлению.


Alexey Kuznetsov
Системный инженер, 12 лет опыта в настройке и эксплуатации серверных решений.

Часто задаваемые вопросы

Какой порт использовать для обычного MQTT и для TLS?

Для нешифрованного соединения MQTT брокер слушает порт 1883, а для защищённого – порт 8883. Оба порта необходимо открыть в файрволе, если клиенты находятся в разных сетях. При настройке TLS в mosquitto.conf указываются listener 8883 и параметры cafile, certfile, keyfile.

Как задать пользовательскую аутентификацию и пароли для Mosquitto?

В конфигурационном файле задаётся директива password_file /etc/mosquitto/passwd, после чего создаётся файл с пользователями и их хешами (mosquitto_passwd -c /etc/mosquitto/passwd user). Для более гибкой авторизации можно использовать ACL‑файл (acl_file) и разместить его в той же директории. После изменения конфигурации перезапустите сервис (systemctl restart mosquitto).

Как настроить Retained‑message и Last Will and Testament (LWT)?

Retained‑message задаётся на стороне клиента при публикации, указывая флаг retain. Для LWT в конфигурации брокера задаются параметры will_topic, will_qos и will_message, которые будут опубликованы при неожиданном разрыве соединения. Оба механизма полезны для мониторинга состояния устройств и поддержания актуального значения параметров.

Какие сертификаты нужны для TLS и как их правильно указать в конфиге?

Для TLS используются три файла: корневой сертификат (cafile), серверный сертификат (certfile) и приватный ключ (keyfile). Если клиенты проверяют сертификат, достаточно self‑signed сертификата, иначе рекомендуется использовать сертификат, подписанный доверенным CA. В mosquitto.conf указываются пути к этим файлам, а параметр require_certificate false оставляется, если клиентская аутентификация не требуется.

Как проверить работу брокера и подключиться к нему из командной строки?

Для базовой проверки используйте утилиты mosquitto_sub и mosquitto_pub, которые поставляются в пакете Mosquitto. Подпишитесь на тему test/topic командой mosquitto_sub -h localhost -p 1883 -t test/topic и опубликуйте сообщение mosquitto_pub -h localhost -p 1883 -t test/topic -m "hello"; полученное сообщение должно появиться у подписчика. Для диагностики слушайте лог сервиса (journalctl -u mosquitto) и используйте mosquitto_ctrl -h localhost -p 1883 info.

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