From a2639c002f98b5004727ea10f1546ec9b6aef9fb Mon Sep 17 00:00:00 2001
From: Pip <pip@pi-zero-2w.local>
Date: Sat, 23 May 2026 13:31:58 +0000
Subject: [PATCH] CUB-231: Mosquitto MQTT broker setup on Pi Zero 2 W hub

- Install script for Mosquitto MQTT broker on Pi Zero 2 W (10.60.1.101)
- Persistence enabled with data stored in /var/lib/mosquitto/data/
- Topic ACL configuration for hub, sensor, mobile, and admin users
- systemd service with security hardening (NoNewPrivileges, ProtectSystem)
- Configuration files: mosquitto.conf, acl.conf
- Validation script to verify setup before deployment
---
 .gitignore            |  33 +++++++++
 README.md             | 164 ++++++++++++++++++++++++++++++++++++++++++
 acl.conf              |  20 ++++++
 deploy.sh             |  33 +++++++++
 install-mosquitto.sh  |  97 +++++++++++++++++++++++++
 mosquitto.conf        |  26 +++++++
 mosquitto.service     |  26 +++++++
 validate-mosquitto.sh |  67 +++++++++++++++++
 8 files changed, 466 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 acl.conf
 create mode 100644 deploy.sh
 create mode 100644 install-mosquitto.sh
 create mode 100644 mosquitto.conf
 create mode 100644 mosquitto.service
 create mode 100644 validate-mosquitto.sh

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..6ab2cab
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,33 @@
+# .gitignore for Mosquitto Hub Config
+
+# Don't commit sensitive files
+/etc/mosquitto/passwd
+*.pem
+*.key
+*.crt
+
+# Generated files
+*.log
+*.bak
+*~
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+/tmp/
+/var/tmp/
+*.tmp
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ed2018d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,164 @@
+# Mosquitto MQTT Broker Setup for Pi Zero 2 W Hub
+
+## Overview
+This repository contains the complete setup for a Mosquitto MQTT broker running on a Raspberry Pi Zero 2 W, serving as a central hub for IoT devices.
+
+## Hardware Target
+- **Device**: Raspberry Pi Zero 2 W
+- **IP Address**: 10.60.1.101
+- **OS**: Raspberry Pi OS Lite
+- **User**: overseer
+
+## Installation
+
+### Quick Install (on Pi Zero 2 W)
+```bash
+ssh overseer@10.60.1.101
+cd ~
+curl -O https://code.cubecraftcreations.com/cubecraft/pi-hub-config/raw/branch/dev/install-mosquitto.sh
+chmod +x install-mosquitto.sh
+sudo ./install-mosquitto.sh
+```
+
+### Manual Installation
+1. Install packages: `sudo apt-get install mosquitto mosquitto-clients python3-paho-mqtt`
+2. Create directories: `/etc/mosquitto/conf.d`, `/etc/mosquitto/acl`, `/var/lib/mosquitto/data`
+3. Copy configuration files to `/etc/mosquitto/`
+4. Set up users with `mosquitto_passwd`
+
+## Configuration
+
+### Main Configuration (`/etc/mosquitto/conf.d/mosquitto.conf`)
+- **Persistence**: Enabled at `/var/lib/mosquitto/data/`
+- **Port**: 1883 (standard MQTT)
+- **Authentication**: Enabled (anonymous access disabled)
+- **ACL**: Configured in `/etc/mosquitto/acl/acl.conf`
+- **Logging**: Full logging to `/var/log/mosquitto/mosquitto.log`
+
+### Access Control List
+See `/etc/mosquitto/acl/acl.conf` for full topic patterns.
+
+| User | Read Topics | Write Topics |
+|------|-------------|--------------|
+| hub | / (all) | hub/+/set |
+| sensor | sensors/+/data | devices/+/commands |
+| mobile | home/+/status | home/+/control |
+| admin | # (all) | # (all) |
+
+### Security
+- Password file: `/etc/mosquitto/passwd` (mode 600)
+- No anonymous access
+- ACL-enforced topic restrictions
+- Systemd service with security hardening (NoNewPrivileges, ProtectSystem=strict)
+
+## systemd Service
+
+### Auto-start Configuration
+```bash
+# Copy service file to systemd
+sudo cp mosquitto.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable mosquitto
+sudo systemctl start mosquitto
+```
+
+### Service Management
+```bash
+sudo systemctl status mosquitto
+sudo systemctl restart mosquitto
+sudo systemctl stop mosquitto
+```
+
+## Usage
+
+### Testing Installation
+```bash
+# Subscribe to test topic
+mosquitto_sub -h localhost -t test -u admin -P <password>
+
+# Publish test message
+mosquitto_pub -h localhost -t test -m "Hello Mosquitto" -u admin -P <password>
+```
+
+### MQTT Client Examples
+
+#### Python (paho-mqtt)
+```python
+import paho.mqtt.client as mqtt
+
+client = mqtt.Client("client-id")
+client.username_pw_set("admin", password="your-password")
+client.connect("10.60.1.101", 1883, 60)
+client.subscribe("test")
+client.loop_start()
+```
+
+#### Home Assistant
+```yaml
+mqtt:
+  broker: 10.60.1.101
+  port: 1883
+  username: admin
+  password: "your-password"
+```
+
+## Maintenance
+
+### Adding Users
+```bash
+sudo mosquitto_passwd -c /etc/mosquitto/passwd <username>
+```
+
+### Changing Password
+```bash
+sudo mosquitto_passwd /etc/mosquitto/passwd <username>
+```
+
+### Restarting Service
+```bash
+sudo systemctl restart mosquitto
+```
+
+### Viewing Logs
+```bash
+sudo journalctl -u mosquitto -f
+# or
+tail -f /var/log/mosquitto/mosquitto.log
+```
+
+## Troubleshooting
+
+### Service won't start
+- Check configuration syntax: `mosquitto -c /etc/mosquitto/conf.d/mosquitto.conf -t`
+- Verify file permissions on `/etc/mosquitto/`
+- Check logs: `journalctl -u mosquitto`
+
+### Authentication failures
+- Verify password file exists: `ls -la /etc/mosquitto/passwd`
+- Check password file permissions: should be 600
+- Test with: `mosquitto_sub -h localhost -t test -u <user> -P <pass> -v`
+
+### Connection refused
+- Ensure service is running: `systemctl status mosquitto`
+- Verify no firewall blocking port 1883
+- Check if another MQTT broker is running
+
+## Deployment Checklist
+
+- [ ] Install dependencies: `apt-get install mosquitto mosquitto-clients python3-paho-mqtt`
+- [ ] Run install script: `./install-mosquitto.sh`
+- [ ] Create admin user password
+- [ ] Copy systemd service file
+- [ ] Enable and start service
+- [ ] Test with mosquitto_pub/sub
+- [ ] Configure firewall (allow port 1883)
+- [ ] Update DNS/DHCP with static IP for Pi Zero 2 W
+- [ ] Document in network inventory
+
+## Related Projects
+- CUB-231: Mosquitto MQTT broker setup on Pi Zero 2 W hub
+- Pi hub serves as central MQTT broker for IoT devices
+- Integrates with Home Assistant at 10.60.1.80
+
+## License
+MIT License - See LICENSE file for details.
diff --git a/acl.conf b/acl.conf
new file mode 100644
index 0000000..68f51db
--- /dev/null
+++ b/acl.conf
@@ -0,0 +1,20 @@
+# Access Control List for Mosquitto
+# Topic patterns with user permissions
+
+# Hub - Internal services (full access)
+user hub
+topic # rw
+
+# Sensors - Read sensor data, write commands
+user sensor
+pattern read sensors/+/data
+pattern write devices/+/commands
+
+# Mobile - Home status and control
+user mobile
+pattern read home/+/status
+pattern write home/+/control
+
+# Admin - Full access to all topics
+user admin
+topic # rw
diff --git a/deploy.sh b/deploy.sh
new file mode 100644
index 0000000..ba03691
--- /dev/null
+++ b/deploy.sh
@@ -0,0 +1,33 @@
+# Install Mosquitto MQTT Broker
+# Runs on Pi Zero 2 W (10.60.1.101)
+
+apt-get update
+apt-get install -y mosquitto mosquitto-clients python3-paho-mqtt
+
+# Create directories
+mkdir -p /etc/mosquitto/conf.d
+mkdir -p /etc/mosquitto/acl
+mkdir -p /var/lib/mosquitto/data
+chown -R mosquitto:mosquitto /var/lib/mosquitto/data
+
+# Copy configuration files
+cp /root/mosquitto.conf /etc/mosquitto/conf.d/mosquitto.conf
+cp /root/acl.conf /etc/mosquitto/acl/acl.conf
+
+# Set permissions
+chown -R mosquitto:mosquitto /etc/mosquitto
+chmod 644 /etc/mosquitto/conf.d/mosquitto.conf
+chmod 644 /etc/mosquitto/acl/acl.conf
+
+# Create initial users
+mosquitto_passwd -cb /etc/mosquitto/passwd hub hubpassword123
+mosquitto_passwd -c /etc/mosquitto/passwd admin
+
+# Create systemd service
+cp /root/mosquitto.service /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable mosquitto
+systemctl start mosquitto
+
+echo "Mosquitto installation complete!"
+echo "Test with: mosquitto_sub -h localhost -t test -u admin -P <password> -v"
diff --git a/install-mosquitto.sh b/install-mosquitto.sh
new file mode 100644
index 0000000..875973d
--- /dev/null
+++ b/install-mosquitto.sh
@@ -0,0 +1,97 @@
+#!/bin/bash
+# install-mosquitto.sh - Install and configure Mosquitto MQTT broker on Pi Zero 2 W
+# Target: Raspberry Pi Zero 2 W (10.60.1.101)
+# Author: Pip (CUB-231)
+
+set -e
+
+echo "=== Installing Mosquitto MQTT Broker ==="
+
+# Update package list
+echo "[1/6] Updating package list..."
+apt-get update
+
+# Install Mosquitto and clients
+echo "[2/6] Installing Mosquitto packages..."
+apt-get install -y mosquitto mosquitto-clients python3-paho-mqtt
+
+# Create necessary directories
+echo "[3/6] Creating configuration directories..."
+mkdir -p /etc/mosquitto/conf.d
+mkdir -p /var/lib/mosquitto/data
+mkdir -p /etc/mosquitto/acl
+
+# Set proper permissions for data directory
+chown mosquitto:mosquitto /var/lib/mosquitto/data
+chmod 755 /var/lib/mosquitto/data
+
+# Create Mosquitto configuration
+echo "[4/6] Creating mosquitto.conf..."
+cat > /etc/mosquitto/conf.d/mosquitto.conf << 'EOF'
+# Mosquitto Configuration for Pi Zero 2 W Hub
+# Auto-generated by install-mosquitto.sh (CUB-231)
+
+# Persistence
+persistence true
+persistence_location /var/lib/mosquitto/data/
+persistence_file mosquitto.db
+
+# Listening
+listener 1883
+
+# Authentication
+allow_anonymous false
+
+# ACL (Access Control List) configuration
+acl_file /etc/mosquitto/acl/acl.conf
+
+# Logging
+log_dest file /var/log/mosquitto/mosquitto.log
+log_type all
+EOF
+
+# Create ACL configuration
+echo "[5/6] Creating ACL configuration..."
+cat > /etc/mosquitto/acl/acl.conf << 'EOF'
+# Mosquitto ACL Configuration
+# Topic access control for MQTT users
+# Format: topic [read|write] <username>
+
+# Pi Zero 2 W Hub - Read all topics, write to hub-specific topics
+pattern read /
+pattern write hub/+/set
+
+# Pi clients - Read sensor data, write commands
+pattern read sensors/+/data
+pattern write devices/+/commands
+
+# Mobile clients - Read home status, write control commands
+pattern read home/+/status
+pattern write home/+/control
+
+# Admin - Full access
+user admin
+topic # rw
+EOF
+
+# Create users (run interactively with -p for password)
+echo "[6/6] Creating initial users..."
+echo "Creating 'hub' user for internal services..."
+mosquitto_passwd -b /etc/mosquitto/passwd hub "$(openssl rand -base64 16 | tr -d 'O0Il' | cut -c1-16)" 2>/dev/null || echo "User 'hub' setup required"
+
+# Set proper permissions
+chown -R mosquitto:mosquitto /etc/mosquitto
+chown -R mosquitto:mosquitto /var/lib/mosquitto
+chmod 644 /etc/mosquitto/conf.d/mosquitto.conf
+chmod 644 /etc/mosquitto/acl/acl.conf
+chmod 600 /etc/mosquitto/passwd
+
+echo ""
+echo "=== Mosquitto Installation Complete ==="
+echo ""
+echo "Next steps:"
+echo "1. Set password for admin user: mosquitto_passwd -c /etc/mosquitto/passwd <username>"
+echo "2. Start the service: systemctl start mosquitto"
+echo "3. Enable auto-start: systemctl enable mosquitto"
+echo "4. Test connection: mosquitto_sub -h localhost -t test -u <user> -P <pass>"
+echo ""
diff --git a/mosquitto.conf b/mosquitto.conf
new file mode 100644
index 0000000..d28f50e
--- /dev/null
+++ b/mosquitto.conf
@@ -0,0 +1,26 @@
+# Main Mosquitto Configuration
+# Target: Pi Zero 2 W Hub (10.60.1.101)
+
+# Persistence
+persistence true
+persistence_location /var/lib/mosquitto/data/
+persistence_file mosquitto.db
+
+# Listener
+listener 1883
+
+# Authentication
+allow_anonymous false
+
+# ACL
+acl_file /etc/mosquitto/acl/acl.conf
+
+# Logging
+log_dest file /var/log/mosquitto/mosquitto.log
+log_type all
+
+# Max connections
+max_connections 100
+
+# Keep alive
+persistent_client_expiration 4w
diff --git a/mosquitto.service b/mosquitto.service
new file mode 100644
index 0000000..57f5e47
--- /dev/null
+++ b/mosquitto.service
@@ -0,0 +1,26 @@
+[Unit]
+Description=Mosquitto MQTT Broker
+Documentation=man:mosquitto(8)
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/usr/sbin/mosquitto -c /etc/mosquitto/conf.d/mosquitto.conf
+ExecReload=/bin/kill -HUP $MAINPID
+Restart=on-failure
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=mosquitto
+
+# Resource limits
+LimitNOFILE=65535
+
+# Security hardening
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/log/mosquitto /var/lib/mosquitto /etc/mosquitto
+
+[Install]
+WantedBy=multi-user.target
diff --git a/validate-mosquitto.sh b/validate-mosquitto.sh
new file mode 100644
index 0000000..f8bee25
--- /dev/null
+++ b/validate-mosquitto.sh
@@ -0,0 +1,67 @@
+#!/bin/bash
+# validate-mosquitto.sh - Validate Mosquitto setup configuration
+# Run on Pi Zero 2 W to verify configuration before deployment
+
+set -e
+
+echo "=== Validating Mosquitto Configuration ==="
+
+# Check if configuration files exist
+echo "[CHECK 1/5] Verifying configuration files exist..."
+if [ -f /etc/mosquitto/conf.d/mosquitto.conf ]; then
+    echo "  ✓ mosquitto.conf exists"
+else
+    echo "  ✗ mosquitto.conf missing"
+    exit 1
+fi
+
+if [ -f /etc/mosquitto/acl/acl.conf ]; then
+    echo "  ✓ acl.conf exists"
+else
+    echo "  ✗ acl.conf missing"
+    exit 1
+fi
+
+# Check if mosquitto is installed
+echo "[CHECK 2/5] Verifying Mosquitto installation..."
+if command -v mosquitto &> /dev/null; then
+    echo "  ✓ mosquitto binary found"
+else
+    echo "  ✗ mosquitto binary not found"
+    exit 1
+fi
+
+# Validate configuration syntax
+echo "[CHECK 3/5] Validating configuration syntax..."
+if mosquitto -c /etc/mosquitto/conf.d/mosquitto.conf -t; then
+    echo "  ✓ Configuration syntax is valid"
+else
+    echo "  ✗ Configuration has syntax errors"
+    exit 1
+fi
+
+# Check persistence directory
+echo "[CHECK 4/5] Verifying persistence directory..."
+if [ -d /var/lib/mosquitto/data ]; then
+    echo "  ✓ Persistence directory exists"
+else
+    echo "  ✗ Persistence directory missing"
+    exit 1
+fi
+
+# Check ACL file permissions
+echo "[CHECK 5/5] Verifying file permissions..."
+if [ -f /etc/mosquitto/passwd ]; then
+    if [ "$(stat -c %a /etc/mosquitto/passwd)" = "600" ]; then
+        echo "  ✓ Password file has secure permissions (600)"
+    else
+        echo "  ⚠ Password file permissions should be 600"
+    fi
+else
+    echo "  ⚠ Password file not yet created (create with mosquitto_passwd)"
+fi
+
+echo ""
+echo "=== Validation Complete ==="
+echo "Configuration is ready for deployment to Pi Zero 2 W (10.60.1.101)"
+echo ""