Mosquitto broker – jak zainstalować, zabezpieczyć i połączyć z Home Assistant?

Autor: [Twoje Imię lub Nick] | Data: maj 2026

W świecie smart home protokół MQTT stał się nieodzownym elementem komunikacji między urządzeniami IoT. Na jego czele stoi broker, a jednym z najpopularniejszych jest Mosquitto – lekki, szybki i niezawodny serwer MQTT. W tym rozbudowanym poradniku krok po kroku pokażę, jak zainstalować Mosquitto na Raspberry Pi lub innym systemie Linux (np. Ubuntu/Debian), jak go zabezpieczyć przed nieautoryzowanym dostępem, a na koniec jak zintegrować go z Home Assistant.

Bez względu na to, czy budujesz inteligentny dom od zera, czy optymalizujesz istniejącą instalację, ten przewodnik da Ci solidne podstawy. Zakładam podstawową wiedzę z terminala Linux – jeśli jesteś początkujący, nie martw się, wszystko wyjaśnię!

Czym jest Mosquitto i dlaczego warto go używać?

Mosquitto to otwartoźródłowy broker MQTT (Message Queuing Telemetry Transport) napisany w C, wspierający protokół MQTT w wersjach 3.1, 3.1.1 i 5.0. Działa jako pośrednik między wydawcami (publishers) a subskrybentami (subscribers) tematów (topics).

Zalety Mosquitto w smart home

Poniżej znajdziesz najważniejsze atuty, które szczególnie docenisz w domowej automatyce:

• niskie zużycie zasobów – idealny na Raspberry Pi;
• obsługa TLS/SSL – szyfrowanie komunikacji;
• uwierzytelnianie użytkowników i ACL (Access Control Lists) – precyzyjna kontrola uprawnień;
• integracja z Home Assistant, Zigbee2MQTT, ESPHome – szeroka kompatybilność;
• darmowy i stabilny – używany w milionach instalacji.

W porównaniu do chmurowych brokerów (np. HiveMQ), Mosquitto daje pełną kontrolę i prywatność danych.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz poniższe elementy:

• sprzęt – Raspberry Pi 3/4/5 (lub inny serwer Linux), min. 1 GB RAM;
• system – Raspberry Pi OS (dawny Raspbian), Ubuntu/Debian 20.04+;
• dostęp – SSH (np. PuTTY) lub bezpośrednia konsola;
• uprawnienia – użytkownik z sudo.

Uwaga: przed większymi zmianami wykonaj kopię zapasową systemu.

Krok 1 – instalacja Mosquitto i klientów

Instalacja jest prosta dzięki menedżerowi pakietów apt. Uruchom terminal i wykonaj polecenia:

sudo apt update && sudo apt upgrade -y
sudo apt install mosquitto mosquitto-clients -y


Pakiet mosquitto instaluje broker (serwer), a mosquitto-clients dodaje narzędzia testowe: mosquitto_pub (publikacja) i mosquitto_sub (subskrypcja).

Aby sprawdzić wersję zainstalowanego serwera, użyj:

mosquitto -v


Oczekiwany wynik to m.in. mosquitto version 2.0.x.

Aby uruchamiać usługę automatycznie przy starcie systemu, wykonaj:

sudo systemctl enable mosquitto.service
sudo systemctl start mosquitto.service


Sprawdzenie statusu usługi wygląda tak:

sudo systemctl status mosquitto.service


Jeśli widzisz status active (running), broker działa poprawnie.

Domyślnie broker nasłuchuje na porcie 1883 bez uwierzytelniania – koniecznie go zabezpiecz.

Krok 2 – podstawowa konfiguracja

Główny plik konfiguracyjny to /etc/mosquitto/mosquitto.conf. Nie edytuj go bezpośrednio – utwórz własny plik w podkatalogu conf.d i dodaj tam ustawienia:

sudo mkdir -p /etc/mosquitto/conf.d
sudo nano /etc/mosquitto/conf.d/moje-mosquitto.conf


Wklej bazową konfigurację:

# Port nasłuchu (domyślny 1883)
listener 1883

# Logi
log_dest file /var/log/mosquitto/mosquitto.log
log_type all
log_timestamp true

# Maksymalny rozmiar wiadomości (w bajtach)
message_size_limit 0 # bez limitu

Zapisz plik i zrestartuj usługę:

sudo systemctl restart mosquitto.service


Krok 3 – zabezpieczenie brokera: uwierzytelnianie i hasła

Wyłącz anonimowy dostęp – domyślnie każdy może się połączyć! Otwórz plik /etc/mosquitto/conf.d/moje-mosquitto.conf i dodaj poniższe linie:

# Wymuś uwierzytelnianie
allow_anonymous false

# Plik z hasłami
password_file /etc/mosquitto/passwd

Aby utworzyć plik haseł i pierwszego użytkownika (zastąp mqttuser i ustaw własne silne hasło), wykonaj:

sudo mosquitto_passwd -c /etc/mosquitto/passwd mqttuser
# Wpisz hasło dwukrotnie


Dodawanie kolejnych użytkowników odbywa się tak:

sudo mosquitto_passwd /etc/mosquitto/passwd nowyuser


Dla bezpieczeństwa ustaw właściwe uprawnienia do pliku haseł:

sudo chown mosquitto:mosquitto /etc/mosquitto/passwd
sudo chmod 600 /etc/mosquitto/passwd


Na koniec zrestartuj usługę, aby wczytać nowe ustawienia:

sudo systemctl restart mosquitto.service


Test z klientami

W dwóch osobnych terminalach sprawdź publikację i subskrypcję z uwierzytelnianiem:

# Terminal 1 – subskrypcja
mosquitto_sub -h localhost -u mqttuser -P silnehaslo123 -t "test/temat" -v

# Terminal 2 – publikacja
mosquitto_pub -h localhost -u mqttuser -P silnehaslo123 -t "test/temat" -m "Witaj MQTT!"


W Terminalu 1 powinieneś zobaczyć:

test/temat Witaj MQTT!


Krok 4 – zaawansowane zabezpieczenia: ACL i TLS/SSL

Listy kontroli dostępu (ACL)

Aby precyzyjnie kontrolować, kto i do jakich tematów ma dostęp, utwórz plik reguł ACL:

sudo nano /etc/mosquitto/aclfile


Przykładowa konfiguracja ACL wygląda następująco:

# Użytkownik mqttuser może publikować i subskrybować swoje tematy
user mqttuser
topic readwrite sensor/+/temperatura
topic read dom/ogolne/#

# Wzorzec z nazwą użytkownika w ścieżce
pattern readwrite home/%u/#

# Inny użytkownik tylko czyta
user reader
topic readonly #

Następnie do pliku /etc/mosquitto/conf.d/moje-mosquitto.conf dodaj odwołanie do ACL i zrestartuj usługę:

acl_file /etc/mosquitto/aclfile
sudo systemctl restart mosquitto.service


Szyfrowanie TLS/SSL

Włącz TLS/SSL, zwłaszcza gdy broker jest dostępny poza siecią lokalną. Poniżej kroki konfiguracji:

1. Wygeneruj certyfikaty (na testy self-signed; w produkcji użyj Let’s Encrypt):

sudo mkdir -p /etc/mosquitto/certs
cd /etc/mosquitto/certs
sudo openssl req -new -x509 -days 365 -out server.crt -keyout server.key -nodes
# Common Name (CN) ustaw na hostname lub publiczny adres IP serwera


2. Dodaj listener TLS (port 8883) w pliku moje-mosquitto.conf:

listener 8883
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
require_certificate false


3. Przetestuj połączenie TLS przy użyciu wygenerowanego certyfikatu:

mosquitto_sub -h localhost -p 8883 --cafile /etc/mosquitto/certs/server.crt -u mqttuser -P silnehaslo123 -t "test/tls" -v


W środowisku produkcyjnym używaj certyfikatów od zaufanego CA (np. Let’s Encrypt) i rozważ reverse proxy, np. Nginx lub Traefik.

Krok 5 – integracja z Home Assistant

Home Assistant (HA) posiada wbudowany dodatek Mosquitto, ale własny broker daje większą kontrolę i elastyczność.

Opcja 1 – add-on w HA (najłatwiejsza)

Skorzystaj z dodatku MQTT Broker w HA, a następnie wskaż połączenie w konfiguracji:

1. W HA: Ustawienia > Dodatki > Sklep z dodatkami > MQTT Broker;
2. Zainstaluj dodatek i ustaw login/hasło;
3. W pliku configuration.yaml dodaj sekcję integracji:

mqtt:
broker: localhost # lub IP Raspberry Pi
port: 1883
username: mqttuser
password: silnehaslo123


Opcja 2 – zewnętrzny Mosquitto (na Raspberry Pi lub innym Linuxie)

Jeśli używasz zewnętrznego brokera, uzupełnij konfigurację HA tak:

mqtt:
broker: 192.168.1.100 # IP serwera z Mosquitto
port: 1883
username: mqttuser
password: silnehaslo123
discovery: true
birth_message:
topic: 'hass/status'
payload: 'online'
will_message:
topic: 'hass/status'
payload: 'offline'


Zrestartuj Home Assistant, a następnie sprawdź integrację MQTT w Ustawienia > Urządzenia i usługi.

Przykład konfiguracji Zigbee2MQTT współpracującej z brokerem wygląda tak:

{
"mqtt": {
"base_topic": "zigbee2mqtt",
"server": "mqtt://192.168.1.100:1883",
"user": "mqttuser",
"password": "silnehaslo123"
}
}


Rozwiązywanie problemów

Poniższa tabela zawiera najczęstsze problemy i szybkie działania naprawcze:

Problem	Rozwiązanie
Port 1883 nieotwarty	Dodaj regułę w firewallu: sudo ufw allow 1883
Błąd „Connection refused”	Sprawdź usługę: sudo systemctl status mosquitto
Hasła nie działają	Utwórz plik od nowa: sudo mosquitto_passwd -c /etc/mosquitto/passwd user
Logi	Podgląd w czasie rzeczywistym: sudo tail -f /var/log/mosquitto/mosquitto.log
HA nie widzi brokera	Wyczyść cache MQTT w HA i zweryfikuj składnię YAML

Dodatkowy tryb diagnostyczny – subskrypcja wszystkiego:

mosquitto_sub -v -t '#' -h IP_BROKERA -u USER -P PASS


Źródła – oficjalna dokumentacja Mosquitto, polskie fora (ArturHome, Supla), praktyczne testy na RPi5.

Tagi – MQTT, Mosquitto, Home Assistant, Raspberry Pi, smart home, IoT, zabezpieczenia.

Uwaga: stan na maj 2026. Wersje oprogramowania mogą się zmieniać – przed instalacją uruchom sudo apt update i sprawdź aktualną dokumentację.