Files

Funky (OpenClaw) 0682c79580 Initial infrastructure documentation - comprehensive homelab reference

2026-02-23 03:42:22 +00:00

18 KiB

Raw Blame History

MQTT Broker Setup Guide (Mosquitto)

This guide covers deploying a Mosquitto MQTT broker for Home Assistant and other IoT integrations on your Proxmox infrastructure.

What is MQTT?

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol designed for IoT devices. It enables efficient publish/subscribe communication between devices and services like Home Assistant.

Common Uses:

Smart home device communication (sensors, switches, lights)
ESP8266/ESP32 devices via ESPHome
Zigbee2MQTT and Z-Wave integration
Custom automation scripts
Inter-service messaging

Deployment Overview

Service: Mosquitto MQTT Broker Location: pve-router (i5 Proxmox node at 10.0.10.2) IP Address: 10.0.10.26 Deployment Method: LXC Container (lightweight, efficient)

Prerequisites

Access to Proxmox web interface (https://10.0.10.2:8006)
Ubuntu/Debian LXC template downloaded on Proxmox
DHCP reservation configured on UCG Ultra for 10.0.10.26

Part 1: Create LXC Container

1.1 Download Container Template

In Proxmox web interface on pve-router:

Select pve-router node
Click local (pve-router) storage
Click CT Templates
Click Templates button
Search for and download: ubuntu-22.04-standard or debian-12-standard

1.2 Create Container

Click Create CT (top right)
Configure as follows:

General Tab:

Node: pve-router
CT ID: (next available, e.g., 105)
Hostname: mosquitto
Password: (set a strong root password)
SSH public key: (optional, recommended)

Template Tab:

Storage: local
Template: ubuntu-22.04-standard (or debian-12)

Disks Tab:

Storage: local-lvm (or your preferred storage)
Disk size: 2 GiB (plenty for MQTT logs and config)

CPU Tab:

Cores: 1

Memory Tab:

Memory (MiB): 512
Swap (MiB): 512

Network Tab:

Bridge: vmbr0
IPv4: Static
IPv4/CIDR: 10.0.10.26/24
Gateway: 10.0.10.1
IPv6: SLAAC (or disable if not using IPv6)

DNS Tab:

DNS domain: home (or leave blank)
DNS servers: 10.0.10.1 (UCG Ultra)

Click Finish (uncheck "Start after created" - we'll configure first)

1.3 Configure UCG Ultra DHCP Reservation (Optional Backup)

Even though we're using static IP, create a DHCP reservation as backup:

Access UCG Ultra at https://10.0.10.1
Settings → Networks → LAN → DHCP
Add reservation:
- IP Address: 10.0.10.26
- MAC Address: (get from Proxmox container network tab after first start)
- Hostname: mosquitto
- Description: MQTT Broker (Mosquitto)

Part 2: Install and Configure Mosquitto

In Proxmox:

Select the mosquitto container
Click Start
Click Console (or SSH via ssh root@10.0.10.26)

2.2 Update System

# Update package lists
apt update

# Upgrade existing packages
apt upgrade -y

# Install basic utilities
apt install -y curl wget nano htop

2.3 Install Mosquitto

# Install Mosquitto broker and clients
apt install -y mosquitto mosquitto-clients

# Enable and start service
systemctl enable mosquitto
systemctl start mosquitto

# Verify it's running
systemctl status mosquitto

2.4 Configure Mosquitto

Create configuration file:

# Backup original config
cp /etc/mosquitto/mosquitto.conf /etc/mosquitto/mosquitto.conf.bak

# Create new configuration
nano /etc/mosquitto/mosquitto.conf

Basic Configuration:

# /etc/mosquitto/mosquitto.conf
# Basic MQTT broker configuration

# Listener settings
listener 1883
protocol mqtt

# Allow anonymous connections (for initial testing only)
allow_anonymous true

# Persistence settings
persistence true
persistence_location /var/lib/mosquitto/

# Logging
log_dest file /var/log/mosquitto/mosquitto.log
log_dest stdout
log_type error
log_type warning
log_type notice
log_type information

# Connection, protocol, and logging settings
connection_messages true
log_timestamp true

Save and exit (Ctrl+X, Y, Enter)

2.5 Restart Mosquitto

systemctl restart mosquitto
systemctl status mosquitto

Part 3: Secure MQTT with Authentication

3.1 Create MQTT User

# Create password file for user 'homeassistant'
mosquitto_passwd -c /etc/mosquitto/passwd homeassistant

# You'll be prompted to enter a password twice
# Save this password - you'll need it for Home Assistant

Add additional users:

# Add more users (without -c flag to avoid overwriting)
mosquitto_passwd /etc/mosquitto/passwd esphome
mosquitto_passwd /etc/mosquitto/passwd automation

3.2 Update Configuration for Authentication

Edit config:

nano /etc/mosquitto/mosquitto.conf

Change this line:

allow_anonymous true

To:

allow_anonymous false
password_file /etc/mosquitto/passwd

Save and restart:

systemctl restart mosquitto
systemctl status mosquitto

Part 4: Testing MQTT

4.1 Test Locally on Container

Terminal 1 - Subscribe to test topic:

mosquitto_sub -h localhost -t test/topic -u homeassistant -P YOUR_PASSWORD

Terminal 2 - Publish message:

mosquitto_pub -h localhost -t test/topic -m "Hello MQTT!" -u homeassistant -P YOUR_PASSWORD

You should see "Hello MQTT!" appear in Terminal 1.

4.2 Test from Another Machine

From any computer on your network:

# Subscribe
mosquitto_sub -h 10.0.10.26 -t test/topic -u homeassistant -P YOUR_PASSWORD

# Publish (from another terminal)
mosquitto_pub -h 10.0.10.26 -t test/topic -m "Remote test" -u homeassistant -P YOUR_PASSWORD

Part 5: Integrate with Home Assistant

5.1 Add MQTT Integration

Open Home Assistant at http://10.0.10.24:8123
Go to Settings → Devices & Services
Click Add Integration
Search for MQTT
Configure:
- Broker: 10.0.10.26
- Port: 1883
- Username: homeassistant
- Password: (password you set earlier)
- Leave other settings as default
Click Submit

5.2 Verify Connection

In Home Assistant:

Go to Settings → Devices & Services
Click on MQTT
You should see "Connected"

5.3 Test MQTT in Home Assistant

Developer Tools → MQTT
Listen to topic: homeassistant/#
Click Start Listening
In Publish section:
- Topic: homeassistant/test
- Payload: {"message": "Hello from HA"}
- Click Publish
You should see the message appear in the listen section

Part 6: ESPHome Integration

If you're using ESPHome (10.0.10.28):

Add to your ESPHome device YAML:

mqtt:
  broker: 10.0.10.26
  port: 1883
  username: esphome
  password: YOUR_ESPHOME_PASSWORD
  discovery: true
  discovery_prefix: homeassistant

This enables ESPHome devices to publish data to Home Assistant via MQTT.

Part 7: Advanced Configuration (Optional)

7.1 Enable TLS/SSL Encryption

Generate self-signed certificate (for internal use):

# Install certbot or use openssl
apt install -y openssl

# Create directory for certificates
mkdir -p /etc/mosquitto/certs
cd /etc/mosquitto/certs

# Generate CA key and certificate
openssl req -new -x509 -days 3650 -extensions v3_ca -keyout ca.key -out ca.crt

# Generate server key and certificate
openssl genrsa -out server.key 2048
openssl req -new -out server.csr -key server.key
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 3650

# Set permissions
chmod 600 /etc/mosquitto/certs/*.key
chown mosquitto:mosquitto /etc/mosquitto/certs/*

Update mosquitto.conf:

# Add TLS listener
listener 8883
protocol mqtt
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key

Restart: systemctl restart mosquitto

7.2 WebSocket Support (for Browser Clients)

Add to mosquitto.conf:

# WebSocket listener
listener 9001
protocol websockets

Useful for web-based MQTT clients or browser automation.

7.3 Access Control Lists (ACLs)

Create ACL file:

nano /etc/mosquitto/acl

Example ACL:

# homeassistant can access everything
user homeassistant
topic readwrite #

# esphome can only publish sensor data
user esphome
topic write sensors/#
topic read homeassistant/status

# automation user for scripts
user automation
topic readwrite automation/#

Update mosquitto.conf:

acl_file /etc/mosquitto/acl

Restart: systemctl restart mosquitto

Part 8: Monitoring and Maintenance

8.1 Check Logs

# Real-time log monitoring
tail -f /var/log/mosquitto/mosquitto.log

# Check systemd logs
journalctl -u mosquitto -f

# Last 100 lines
journalctl -u mosquitto -n 100

8.2 Monitor MQTT Traffic

# Subscribe to all topics (careful in production!)
mosquitto_sub -h localhost -t '#' -u homeassistant -P YOUR_PASSWORD -v

# Monitor specific namespace
mosquitto_sub -h localhost -t 'homeassistant/#' -u homeassistant -P YOUR_PASSWORD -v

8.3 Container Resource Monitoring

# Check CPU/memory usage
htop

# Check disk usage
df -h

# Check mosquitto process
ps aux | grep mosquitto

8.4 Backup Configuration

# Create backup script
nano /root/backup-mqtt.sh

Backup script:

#!/bin/bash
# MQTT configuration backup

BACKUP_DIR="/root/mqtt-backups"
DATE=$(date +%Y%m%d-%H%M%S)

mkdir -p "$BACKUP_DIR"

# Backup config, passwords, ACLs
tar -czf "$BACKUP_DIR/mqtt-config-$DATE.tar.gz" \
    /etc/mosquitto/mosquitto.conf \
    /etc/mosquitto/passwd \
    /etc/mosquitto/acl \
    /etc/mosquitto/certs/ 2>/dev/null

# Keep only last 10 backups
ls -t "$BACKUP_DIR"/*.tar.gz | tail -n +11 | xargs -r rm

echo "Backup completed: mqtt-config-$DATE.tar.gz"

Make executable: chmod +x /root/backup-mqtt.sh

Add to crontab:

crontab -e

Add: 0 2 * * 0 /root/backup-mqtt.sh (weekly at 2 AM Sunday)

Part 9: Firewall Configuration

9.1 UFW Firewall (Optional but Recommended)

# Install UFW
apt install -y ufw

# Allow SSH (IMPORTANT - don't lock yourself out!)
ufw allow 22/tcp

# Allow MQTT
ufw allow 1883/tcp comment 'MQTT'

# If using TLS
ufw allow 8883/tcp comment 'MQTT TLS'

# If using WebSockets
ufw allow 9001/tcp comment 'MQTT WebSocket'

# Enable firewall
ufw enable

# Check status
ufw status

9.2 UCG Ultra Firewall

The UCG Ultra should allow internal LAN traffic by default. No additional rules needed for 10.0.10.0/24 communication.

Part 10: Troubleshooting

MQTT Service Won't Start

# Check for syntax errors in config
mosquitto -c /etc/mosquitto/mosquitto.conf -v

# Check permissions
ls -la /etc/mosquitto/
ls -la /var/lib/mosquitto/

Cannot Connect from Home Assistant

Check network connectivity:

# From Home Assistant container/VM
ping 10.0.10.26

# Check if port is open
nc -zv 10.0.10.26 1883

Verify Mosquitto is listening:

# On MQTT container
ss -tlnp | grep 1883

Authentication Failures

# Check password file exists and has correct permissions
ls -la /etc/mosquitto/passwd

# Test credentials locally
mosquitto_sub -h localhost -t test -u homeassistant -P YOUR_PASSWORD -d

Check logs for specific error:

tail -f /var/log/mosquitto/mosquitto.log

High Resource Usage

MQTT is very lightweight. If seeing high CPU/RAM:

# Check for message loops or excessive traffic
mosquitto_sub -h localhost -t '#' -u homeassistant -P YOUR_PASSWORD -v | head -100

# Check connection count
ss -tn | grep :1883 | wc -l

Part 11: Integration Examples

11.1 Basic Sensor in Home Assistant

# configuration.yaml
mqtt:
  sensor:
    - name: "Temperature Sensor"
      state_topic: "home/sensor/temperature"
      unit_of_measurement: "°F"
      value_template: "{{ value_json.temperature }}"

Publish test data:

mosquitto_pub -h 10.0.10.26 -t home/sensor/temperature -m '{"temperature":72.5}' -u homeassistant -P YOUR_PASSWORD

11.2 MQTT Switch in Home Assistant

# configuration.yaml
mqtt:
  switch:
    - name: "Test Switch"
      state_topic: "home/switch/test"
      command_topic: "home/switch/test/set"
      payload_on: "ON"
      payload_off: "OFF"

11.3 ESP8266/ESP32 Example (Arduino)

#include <ESP8266WiFi.h>
#include <PubSubClient.h>

const char* ssid = "YourWiFi";
const char* password = "YourPassword";
const char* mqtt_server = "10.0.10.26";
const char* mqtt_user = "esphome";
const char* mqtt_password = "YOUR_PASSWORD";

WiFiClient espClient;
PubSubClient client(espClient);

void setup() {
  client.setServer(mqtt_server, 1883);
}

void loop() {
  if (!client.connected()) {
    client.connect("ESP8266Client", mqtt_user, mqtt_password);
  }
  client.publish("home/sensor/esp", "Hello from ESP8266");
  delay(5000);
}

Part 12: Performance Tuning

12.1 Connection Limits

Edit /etc/mosquitto/mosquitto.conf:

# Maximum simultaneous client connections
max_connections 100

# Maximum QoS 1 and 2 messages in flight
max_inflight_messages 20

# Maximum queued messages
max_queued_messages 1000

12.2 Memory Optimization

# Limit memory usage
memory_limit 256M

# Message size limit (bytes)
message_size_limit 1024000

Network Diagram

┌─────────────────────────────────────────────┐
│         UCG Ultra (10.0.10.1)               │
│         Gateway / DNS / DHCP                │
└─────────────────┬───────────────────────────┘
                  │
      ┌───────────┼───────────────┬─────────────┐
      │           │               │             │
┌─────▼─────┐ ┌──▼──────────┐ ┌──▼──────┐ ┌───▼─────────┐
│ Home      │ │ MQTT Broker │ │ ESPHome │ │ Proxmox     │
│ Assistant │ │ 10.0.10.26  │ │.28      │ │ Nodes       │
│ .24       │ │ Mosquitto   │ │         │ │ .2, .3, .4  │
└───────────┘ └─────────────┘ └─────────┘ └─────────────┘
      │              │              │
      └──────────────┴──────────────┘
         MQTT Protocol (Port 1883)
     Topics: homeassistant/*, sensors/*

Quick Reference

Common Commands

# Service management
systemctl status mosquitto
systemctl restart mosquitto
systemctl stop mosquitto
systemctl start mosquitto

# View logs
journalctl -u mosquitto -f
tail -f /var/log/mosquitto/mosquitto.log

# User management
mosquitto_passwd /etc/mosquitto/passwd USERNAME

# Testing
mosquitto_sub -h 10.0.10.26 -t '#' -u USER -P PASS -v
mosquitto_pub -h 10.0.10.26 -t test -m "message" -u USER -P PASS

Configuration Files

Main config: /etc/mosquitto/mosquitto.conf
Passwords: /etc/mosquitto/passwd
ACLs: /etc/mosquitto/acl
Logs: /var/log/mosquitto/mosquitto.log
Data: /var/lib/mosquitto/

Network Details

IP: 10.0.10.26
Hostname: mosquitto
MQTT Port: 1883 (standard)
MQTT TLS Port: 8883 (if configured)
WebSocket Port: 9001 (if configured)

IP-ALLOCATION.md - Network IP plan (MQTT at .26)
SERVICES.md - Service inventory
infrastructure-audit.md - Current infrastructure state
Home Assistant Documentation
Mosquitto Documentation

Security Best Practices

Never use allow_anonymous true in production
Use strong passwords for MQTT users (16+ characters)
Enable TLS/SSL if accessing over internet or untrusted networks
Use ACLs to limit user permissions
Regular backups of configuration and password files
Monitor logs for suspicious connection attempts
Keep Mosquitto updated: apt update && apt upgrade mosquitto

Future Enhancements

Configure TLS encryption for external access
Set up Mosquitto bridge to cloud MQTT broker (if needed)
Integrate with Authentik SSO (when deployed at 10.0.10.21)
Add to Prometheus/Grafana monitoring (when deployed at 10.0.10.25)
Configure message retention policies
Set up MQTT-based automation scripts

Last Updated: 2025-11-18 Status: Ready for deployment Priority: Medium (required for Home Assistant IoT integrations) Deployment Location: pve-router (10.0.10.2) Resource Requirements: 1 CPU core, 512MB RAM, 2GB storage

18 KiB Raw Blame History