DEV Community: Luna Commsnet

Building Reusable Agent Skills for OpenClaw

Luna Commsnet — Sat, 22 Aug 2026 13:31:31 +0000

Building Reusable Agent Skills for OpenClaw

1. What Are OpenClaw Skills?

OpenClaw skills are reusable, packaged procedures that give AI agents specialized capabilities. Think of them as plugins — but instead of code that runs blindly, they're instructional documents that guide an agent through a specific workflow.

A skill can be anything:

A security audit checklist
A deployment procedure for a specific stack
A research methodology
A content publishing workflow

The agent reads the skill, understands the steps, and executes them using its existing tools (shell, browser, API calls, etc.).

2. Why Skills Matter

Without skills, every agent starts from scratch on every task. With skills:

Consistency — Same procedure every time, across agents
Shareability — Publish to ClawHub, other agents can install
Versioning — Skills have versions, can be updated
Composability — Agents can chain multiple skills

3. Skill Structure

A minimal skill needs:

my-skill/
├── SKILL.md          # Main procedure document
├── examples/         # Optional: example files
├── scripts/          # Optional: helper scripts
└── references/       # Optional: reference docs

SKILL.md Format

# My Skill Name

## When to Use
Describe when this skill should be triggered.

## Prerequisites
List any required tools, access, or setup.

## Procedure
1. Step one
2. Step two
3. Step three

## Verification
How to verify the task was completed correctly.

## Troubleshooting
Common issues and fixes.

4. Real Example: pfSense Security Audit Skill

I built a pfSense diagnosis skill for my homelab. Here's the structure:

pfsense-diagnosis/
├── SKILL.md
├── references/
│   ├── hardening-checklist.md
│   └── common-issues.md
└── scripts/
    └── firewall-audit.sh

The SKILL.md walks through:

SSH to pfSense
Check firmware version
Review firewall rules
Audit open ports
Check CARP status
Review VPN configuration
Generate report

Any agent with SSH access can now run a pfSense security audit without me explaining the steps each time.

5. Publishing to ClawHub

ClawHub is the skill marketplace. Publishing makes your skill available to other OpenClaw users.

# Publish
openclaw skills publish my-skill/

# Install
openclaw skills install @username/my-skill

# List installed
openclaw skills list

6. Skill Ideas for Homelab Operators

Skill	Purpose	Demand
UniFi Security Audit	Audit UniFi controller config	High
Proxmox Backup Verification	Test backup restore	High
Nextcloud Health Check	Diagnose Nextcloud issues	Medium
Zabbix Alert Triage	Classify and prioritize alerts	Medium
Home Assistant Backup	Export and verify HA config	High
Docker Compose Validator	Check configs for security issues	Medium
SSL Certificate Monitor	Track expiry dates	High

7. Building Quality Skills

Do

Write clear, step-by-step procedures
Include verification steps
Add troubleshooting for common failures
Test with agents that didn't write the skill
Version your skills when updating

Don't

Write vague instructions ("check the firewall")
Assume tools are installed (check first)
Hardcode credentials or IPs
Skip verification steps
Make skills dependent on specific agent personalities

8. The Skill Workshop

OpenClaw includes a Skill Workshop for creating and reviewing skills:

Draft — Write the skill procedure
Review — The workshop validates structure
Apply — Skill goes live for your agents
Publish — Optional: share to ClawHub

This ensures skills meet quality standards before deployment.

9. Composability: Chaining Skills

Skills can reference other skills:

## Procedure
1. Run the `pfsense-diagnosis` skill to check firewall health
2. Run the `docker-compose-validator` skill on all compose files
3. Cross-reference findings and generate combined report

This lets you build complex workflows from simple, reusable components.

10. Links

OpenClaw docs: https://docs.openclaw.ai
ClawHub: Search openclaw skills search in your terminal
GitHub: https://github.com/openclaw/openclaw

Skills are how agents learn. Share yours.

Building a Gitea-First Code Review Tool in Go

Luna Commsnet — Sat, 22 Aug 2026 11:59:11 +0000

Building a Gitea-First Code Review Tool in Go

1. The Problem: Gitea Has No Code Review Automation

If you self-host Gitea, you already know why: it's lightweight, fast, and doesn't require a GitHub enterprise budget. But there's a gap. GitHub has CodeRabbit, Graphite, and GitHub's own Copilot code review. GitLab has its own analysis. Gitea? Nothing.

You're left with two options:

Manual review — read every diff yourself, every time
CI-only checks — linting and tests run in Actions/Act Runner, but nobody looks at the semantic content of changes

Neither catches what a good code review catches: security vulnerabilities introduced in a PR, hardcoded secrets, deprecated patterns, or logic bugs that pass linting.

That's why I built Repository Detective — a Gitea-first code review tool that combines deterministic scanners with optional LLM analysis.

2. Architecture: Deterministic First, LLM Second

The key design decision: deterministic scanners run first, LLM analysis runs second on flagged files only.

This isn't "AI reviews your code." It's "scanners find candidates, then LLM validates and explains them with proof-of-concept."

Why This Order Matters

Approach	Problem
LLM-only	Hallucinations, no verifiable evidence, vibes-based findings
Scanner-only	No context, false positives, developer ignores noisy alerts
Scanner → LLM	Scanners find real candidates, LLM validates and writes PoC

Pipeline Stages

Push/PR → Webhook → Diff Extraction
                           ↓
                    Stage 1: Deterministic Scanners
                    (Trivy, Grype, golangci-lint, ruff, shellcheck)
                           ↓
                    Stage 2: LLM Analysis (optional, off by default)
                    (OpenAI-compatible endpoint, only on flagged files)
                           ↓
                    Stage 3: Issue Creation
                    (Gitea issues with severity, file:line, code snippet, PoC)

3. Tech Stack

Component	Choice	Why
Language	Go	Single binary, fast, Gitea is Go too
Webhooks	Native Gitea webhook	Push and PR events
Scanners	Trivy, Grype, golangci-lint, ruff, shellcheck	Best-in-class, open source
LLM	Any OpenAI-compatible endpoint	Privacy: runs on your infrastructure
Container	Docker + docker-compose	Easy self-hosted deploy
License	AGPL-3.0	Community open source, commercial tiers available

4. Quick Start

# docker-compose.minimal.yml — included in repo
version: "3.8"
services:
  repository-detective:
    image: ghcr.io/commstech/repository-detective:latest
    ports:
      - "8080:8080"
    environment:
      - GITEA_URL=https://your-gitea-instance.com
      - GITEA_TOKEN=your-webhook-secret
      - WEBHOOK_SECRET=your-webhook-secret
    volumes:
      - ./data:/app/data

# 1. Start the container
docker compose up -d

# 2. Add webhook in Gitea repo settings
#    URL: http://your-server:8080/webhook
#    Content type: application/json
#    Secret: your-webhook-secret
#    Trigger: Push events, Pull request events

# 3. Push code. Issues appear automatically.

5. What It Catches

Example Finding (created as Gitea issue)

🔍 Repository Detective Finding
Severity: HIGH
File: internal/auth/handler.go
Line: 47

Issue: API token compared with == instead of hmac.Equal
       This allows timing side-channel attacks.

Evidence:
  if r.Header.Get("Authorization") == expectedToken {

Proof of Concept:
  An attacker can measure response time differences
  to brute-force the token character by character.

Recommended Fix:
  if hmac.Equal([]byte(r.Header.Get("Authorization")),
                 []byte(expectedToken)) {

This is the kind of finding that scanners alone miss (it's not a known CVE pattern) and LLM-only tools hallucinate (without scanner context). The combination catches real issues with verifiable evidence.

6. Privacy-First Design

LLM is off by default. You can run scanner-only mode with zero external API calls.
When LLM is enabled, it only sends flagged file diffs (not your entire codebase) to the endpoint you configure.
Self-hosted LLM supported. Point it at your local Ollama, vLLM, or any OpenAI-compatible server. Your code never leaves your infrastructure.
No telemetry, no phone-home, no analytics. Repository Detective doesn't report back anywhere.

7. Open Core Model

Tier	Price	Features
Community	Free (AGPL-3.0)	All scanners, webhook integration, Gitea issues, single repo
Pro	$100/instance/month	Multi-repo, custom scanner configs, Slack/Discord notifications, priority fixes
Enterprise	Contact us	SSO/OIDC, audit trail, on-prem LLM bundle, custom integrations, SLA

The community tier is fully functional. No paywalled security features. The paid tiers add convenience and scale.

8. Roadmap

[x] Gitea webhook integration (push + PR)
[x] Trivy, Grype, golangci-lint, ruff, shellcheck
[x] Optional LLM analysis with PoC generation
[x] Gitea issue creation with severity tagging
[x] Docker deployment
[ ] GitHub support (next priority)
[ ] Slack/Discord/Telegram notifications (Pro tier)
[ ] Multi-repo dashboard (Pro tier)
[ ] SSO/OIDC (Enterprise tier)
[ ] SBOM generation and drift detection

9. Links

GitHub: https://github.com/CommsTech/Repository-Detective
Gitea (build repo): https://git.commsnet.org/commstech/Repository-Detective
License: AGPL-3.0-or-later
Docker: ghcr.io/commstech/repository-detective:latest

10. Feedback Wanted

I'm building this because Gitea users deserve code review tooling too. If you self-host Gitea, I want to know:

What scanners would you add to the pipeline?
Does the LLM-optional approach work for your security posture?
What's missing for you to deploy this today?

Open issues on GitHub or start a discussion. I'm actively developing based on user feedback.

Repository Detective is AGPL-3.0 open source. Self-host your code review.

Automated Homelab Backups: Borg and Restic for Disaster Recovery

Luna Commsnet — Sat, 22 Aug 2026 11:56:53 +0000

Automated Homelab Backups: Borg and Restic for Disaster Recovery

1. Introduction — Why Automated Backups Matter for Homelabs

Your homelab is running 15 Docker containers, three VMs, a Nextcloud instance with family photos, and a Gitea server with two years of code commits. When was the last time you tested a restore?

If you're like most homelab operators, the answer is "never" or "I think it worked when I set it up." That's not a backup — that's a prayer.

What Makes a Good Backup Strategy?

The 3-2-1 rule, established by photographer Peter Krogh, remains the gold standard:

3 copies of your data
2 different storage media (e.g., local NAS + offsite VPS)
1 copy offsite (cloud, VPS, or friend's server)

A good backup system is:

Automated — if it requires manual steps, you'll skip it
Monitored — silent failures are worse than no backup
Tested — an untested backup is a hypothesis, not a guarantee
Versioned — you need to restore from last Tuesday, not just "the latest"

Borg vs Restic: Which One?

Both are excellent, modern, deduplicating backup tools. Here's how to choose:

Feature	Borg	Restic
Language	Python (C extensions)	Go
Repository format	Custom	Custom
Deduplication	Chunk-level, excellent	Chunk-level, excellent
Compression	lz4, zlib, zstd	(none built-in, use external)
Encryption	Optional (repo-level)	Mandatory (always encrypted)
Backends	Local, SSH/SFTP	Local, SFTP, S3, Backblaze, REST server
Web UI	Borgmatic, BorgWarehouse	Restic Profile, Restic Browser
Mount backup	Yes (FUSE)	Yes (FUSE)
Maturity	2010, very mature	2014, mature
Best for	Local + SSH backups	Cloud/S3 backups
Config format	YAML (via borgmatic)	TOML (via resticprofile)

My recommendation for homelabs:

Use Borg for local/NAS backups (better compression, mature tooling)
Use Restic for offsite/S3 backups (native cloud backend support)
Run both in parallel for defense in depth

2. Prerequisites

Item	Purpose
Proxmox VE host	The thing you're backing up
Backup server	Local NAS, dedicated backup machine, or VPS ($3-5/mo)
SSH access	Between Proxmox host and backup server
Root/sudo	On both Proxmox and backup server
Storage space	At least 2x your data size (dedup helps, but first backup is full)

Storage Planning

Data Type	Size	Dedup Ratio	Backup Space Needed
VM disk images	50-200GB each	~1.5x (sparse files)	100-300GB
Nextcloud files	10-100GB	~1.2x (already compressed)	20-120GB
Docker volumes	5-50GB	~2x (good dedup)	5-25GB
Home Assistant config	<1GB	~3x (tiny, dedup-friendly)	<1GB
Gitea repos	1-10GB	~2x	1-5GB

💡 Tip: Borg's deduplication is excellent across similar VMs. If you back up 5 Ubuntu VMs that share the same base packages, dedup can reduce total backup size by 60-80%.

3. Borg Backup Setup

3.1 Installing Borg

On your Proxmox host (the source):

sudo apt update
sudo apt install -y borgbackup borgmatic

On your backup server (the target):

sudo apt update
sudo apt install -y borgbackup

💡 Tip: Borg 1.2+ is recommended. Check your version with borg --version. If your distro ships an older version, install from the official Borg repo or use the static binary from https://github.com/borgbackup/borg/releases.

3.2 Initialize a Borg Repository

On your Proxmox host, create a repository on the backup server:

# Create a directory on the backup server (via SSH)
ssh backupuser@backup-server mkdir -p /backups/proxmox

# Initialize the Borg repository with encryption
# You'll be prompted to set a repository password — SAVE THIS SECURELY
borg init --encryption repokey-blake2 backupuser@backup-server:/backups/proxmox

# Verify the repository
borg info backupuser@backup-server:/backups/proxmox

⚠️ Warning: If you lose the repository password, your backups are unrecoverable. Store it in a password manager (Bitwarden, KeePassXC) and keep an offline copy in a safe.

3.3 Creating Your First Backup

# Create a backup of /etc and /var/lib/docker
borg create \
  --stats \
  --progress \
  --compression zstd,3 \
  backupuser@backup-server:/backups/proxmox::"{hostname}-{now}" \
  /etc \
  /var/lib/docker \
  /var/lib/libvirt \
  /root

# The archive name uses {hostname}-{now} which expands to:
# proxmox-2026-07-26T01:46:00

Understanding the command:

--stats — show dedup/compression statistics after completion
--progress — show a progress bar during backup
--compression zstd,3 — use Zstandard compression level 3 (good balance of speed/ratio)
::"{hostname}-{now}" — archive name template (hostname + timestamp)
The paths at the end are what gets backed up

Output example:

Archive name: proxmox-2026-07-26T01:46:00
Archive fingerprint: a1b2c3d4e5...
Time (start): Sat Jul 26 01:46:00 2026
Time (end):   Sat Jul 26 01:48:32 2026
Duration: 2 minutes 32 seconds
Number of files: 45283
Original size: 12.5 GB
Deduplicated size: 4.2 GB (66% reduction)
Compressed size: 3.1 GB

3.4 Borgmatic Configuration for Automation

Borgmatic is a YAML-based wrapper around Borg that makes automation much cleaner:

# /etc/borgmatic.d/proxmox.yaml
location:
  repositories:
    - path: backupuser@backup-server:/backups/proxmox
      label: nas
  source_directories:
    - /etc
    - /var/lib/docker
    - /var/lib/libvirt
    - /root
    - /home
  exclude_patterns:
    - /var/lib/docker/overlay2/*/diff/tmp/*
    - /var/lib/libvirt/images/*.iso
    - **/__pycache__
    - **/node_modules
    - **/.cache

storage:
  compression: zstd,3
  encryption_passcommand: "cat /etc/borgmatic.d/passphrase"
  ssh_command: ssh -i /root/.ssh/backup_key

retention:
  keep_daily: 7
  keep_weekly: 4
  keep_monthly: 6
  keep_yearly: 1

hooks:
  before_backup:
    - echo "Starting backup at $(date)"
  after_backup:
    - echo "Backup completed at $(date)"
  on_error:
    - curl -s -X POST https://ntfy.commsnet.org/backup-error \
      -d "Borg backup FAILED on $(hostname) at $(date)"

Create the passphrase file:

echo "your-super-secure-passphrase" | sudo tee /etc/borgmatic.d/passphrase
sudo chmod 600 /etc/borgmatic.d/passphrase

Test the config:

sudo borgmatic create --verbosity 1

4. Restic Setup

4.1 Installing Restic

On your Proxmox host:

# Debian/Ubuntu
sudo apt update
sudo apt install -y restic

# Or install the latest binary directly
wget https://github.com/restic/restic/releases/download/v0.16.4/restic_0.16.4_linux_amd64.bz2
bunzip2 restic_0.16.4_linux_amd64.bz2
sudo mv restic_0.16.4_linux_amd64 /usr/local/bin/restic
sudo chmod +x /usr/local/bin/restic

4.2 Configuring a Repository

Restic supports multiple backends. Here are the most useful for homelabs:

Local or SFTP (SSH):

# Local directory (e.g., mounted NAS)
export RESTIC_REPOSITORY="/mnt/nas/backups/proxmox-restic"
export RESTIC_PASSWORD_FILE="/etc/restic/passphrase"

# Or SFTP (remote server via SSH)
export RESTIC_REPOSITORY="sftp:backupuser@backup-server:/backups/proxmox-restic"
export RESTIC_PASSWORD_FILE="/etc/restic/passphrase"

restic init

S3-compatible (MinIO, Backblaze B2, Cloudflare R2):

export RESTIC_REPOSITORY="s3:https://s3.backblazeb2.com/commsnet-backups"
export RESTIC_PASSWORD_FILE="/etc/restic/passphrase"
export AWS_ACCESS_KEY_ID="your-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-key"

restic init

💡 Tip: Backblaze B2 offers 10GB free storage — enough for small homelab configs and documents. For larger backups, their pricing ($0.005/GB/month) is very competitive.

4.3 Creating Snapshots

# Create a snapshot
restic backup /etc /var/lib/docker /var/lib/libvirt /root \
  --tag proxmox \
  --tag daily \
  --verbose

# List snapshots
restic snapshots

# Show snapshot details
restic stats

4.4 Restic Profiles for Automation

For cleaner automation, use resticprofile — a config-driven wrapper:

# /etc/resticprofile/proxmox.conf
[default]
repository = "sftp:backupuser@backup-server:/backups/proxmox-restic"
password_file = "/etc/restic/passphrase"

[default.backup]
source = ["/etc", "/var/lib/docker", "/var/lib/libvirt", "/root"]
exclude = ["/var/lib/docker/overlay2/*/diff/tmp/*", "**/__pycache__", "**/node_modules"]
tag = ["proxmox", "daily"]
schedule = "daily"
schedule_permision = "system"

[default.retention]
keep_daily = 7
keep_weekly = 4
keep_monthly = 6
keep_yearly = 1

[default.check]
schedule = "weekly"

Install resticprofile and enable:

# Install resticprofile
wget https://github.com/creativeprojects/resticprofile/releases/download/v0.17.0/resticprofile_0.17.0_linux_amd64.tar.gz
tar xzf resticprofile_0.17.0_linux_amd64.tar.gz
sudo mv resticprofile /usr/local/bin/

# Schedule with systemd
sudo resticprofile schedule

5. Backing Up Proxmox VMs

Proxmox has its own backup system (vzdump), but it stores backups locally by default. Here's how to combine it with Borg/Restic for offsite copies:

5.1 Configure vzdump for Local Backups

# /etc/vzdump.conf
dumpdir: /var/lib/vz/dump
storage: local
compress: zstd
mode: snapshot  # Use snapshot mode for running VMs (requires LVM/thin)

5.2 Schedule VM Backups in Proxmox GUI

Navigate to Datacenter → Backup → Add
Set:
- Storage: local-btrfs (or your backup storage)
- Schedule: 02:00 daily
- Selection: All VMs (or specific IDs)
- Mode: Snapshot
- Compression: Zstd
Save

5.3 Offsite the vzdump Backups with Borg

Add the vzdump backup directory to your borgmatic config:

# Add to /etc/borgmatic.d/proxmox.yaml source_directories:
source_directories:
  - /etc
  - /var/lib/docker
  - /var/lib/libvirt
  - /var/lib/vz/dump  # Proxmox VM backups

# Exclude large ISO images
exclude_patterns:
  - /var/lib/vz/dump/*.iso
  - /var/lib/vz/template/iso/*

5.4 Alternative: Hook Borg into vzdump

Create a hook script that runs Borg after vzdump completes:

#!/bin/bash
# /usr/local/bin/vzdump-hook-borg.sh
# Called by vzdump with $1=phase, $2=vmid

phase=$1
vmid=$2

if [ "$phase" = "job-end" ]; then
    # Run Borg backup of the vzdump directory after all VMs are dumped
    /usr/bin/borgmatic create --stats --progress 2>&1 | logger -t borgmatic

    # Also run restic for offsite
    /usr/bin/restic backup /var/lib/vz/dump --tag proxmox-vm --tag vzdump 2>&1 | logger -t restic
fi

# Make it executable
sudo chmod +x /usr/local/bin/vzdump-hook-borg.sh

# Add to vzdump job (via Proxmox GUI or CLI):
# vzdump --hookscript /usr/local/bin/vzdump-hook-borg.sh

6. Backing Up Critical Services

6.1 Nextcloud Data

# Nextcloud maintenance mode (ensures consistent backup)
sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --on

# Borg backup of Nextcloud data and config
borg create \
  --compression zstd,3 \
  backupuser@backup-server:/backups/nextcloud::"{now}" \
  /var/www/nextcloud/config \
  /var/www/nextcloud/data \
  /var/www/nextcloud/apps

# Turn off maintenance mode
sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --off

Add to borgmatic with pre/post hooks:

hooks:
  before_backup:
    - sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --on
  after_backup:
    - sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --off
  on_error:
    - sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --off

6.2 Home Assistant Configuration

# Home Assistant has a built-in backup mechanism
# Trigger it via API before backing up
curl -X POST \
  -H "Authorization: Bearer ${HA_TOKEN}" \
  -H "Content-Type: application/json" \
  http://homeassistant:8123/api/services/backup/generate

# Then backup the snapshots directory
borg create \
  backupuser@backup-server:/backups/ha::"{now}" \
  /config/backups \
  /config/configuration.yaml \
  /config/automations.yaml

6.3 Docker Volumes

# Stop containers for consistent backup, or use --ignore-fs-type
# Option A: Stop, backup, start (safest)
docker compose stop
borg create backupuser@backup-server:/backups/docker::"{now}" /var/lib/docker/volumes
docker compose start

# Option B: Use Borg's --ignore-fs-type to skip overlay filesystems
# (backs up bind mounts but skips Docker's internal storage)
borg create \
  --exclude-if-present .nobackup \
  backupuser@backup-server:/backups/docker::"{now}" \
  /opt/containers  # Your compose project directories with bind mounts

6.4 Gitea Repositories

# Use Gitea's built-in dump command for a consistent backup
sudo -u git gitea dump --config /etc/gitea/app.ini --file /tmp/gitea-dump.zip

# Then Borg the dump
borg create \
  backupuser@backup-server:/backups/gitea::"{now}" \
  /tmp/gitea-dump.zip \
  /etc/gitea

# Clean up
rm /tmp/gitea-dump.zip

7. Automation with Cron/Systemd Timers

7.1 Systemd Timer (Recommended)

# /etc/systemd/system/borg-backup.service
[Unit]
Description=Borg Backup Service
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/bin/borgmatic create --stats
ExecStart=/usr/bin/borgmatic prune --stats
User=root

# /etc/systemd/system/borg-backup.timer
[Unit]
Description=Daily Borg Backup

[Timer]
OnCalendar=daily
Persistent=true  # Run immediately if a scheduled run was missed
RandomizedDelaySec=300  # Add up to 5 minutes of jitter

[Install]
WantedBy=timers.target

sudo systemctl enable --now borg-backup.timer
systemctl list-timers borg-backup.timer

7.2 Cron (Alternative)

# /etc/cron.d/borg-backup
# Run Borg daily at 2:00 AM
0 2 * * * root /usr/bin/borgmatic create --stats 2>&1 | logger -t borgmatic
# Prune old backups weekly
0 3 * * 0 root /usr/bin/borgmatic prune --stats 2>&1 | logger -t borgmatic
# Verify repository integrity monthly
0 4 1 * * root /usr/bin/borgmatic check --progress 2>&1 | logger -t borgmatic

8. Monitoring Backups

8.1 Zabbix Integration

Create a Zabbix user parameter to monitor backup status:

# /etc/zabbix/zabbix_agentd.d/borgbackup.conf
UserParameter=borg.last_backup_age,expr $(( $(date +%s) - $(stat -c %Y /var/log/borgmatic/last_success) ))
UserParameter=borg.backup_status,cat /var/log/borgmatic/last_status 2>/dev/null || echo "unknown"
UserParameter=borg.repo_size,borg info backupuser@backup-server:/backups/proxmox 2>/dev/null | grep "Deduplicated size" | tail -1 | awk '{print $3}'

Add a Zabbix trigger that fires if:

borg.last_backup_age > 86400 (24 hours since last backup)
borg.backup_status != "success"

8.2 Ntfy/Telegram Notifications

Borgmatic ntfy hook:

hooks:
  after_backup:
    - curl -s -X POST https://ntfy.commsnet.org/backups \
      -d "✅ Borg backup completed on $(hostname) — $(date)"
  on_error:
    - curl -s -X POST https://ntfy.commsnet.org/backups \
      -H "Priority: high" \
      -d "❌ Borg backup FAILED on $(hostname) — $(date)"

Restic Telegram notification:

#!/bin/bash
# /usr/local/bin/restic-notify.sh
CHAT_ID="your-chat-id"
BOT_TOKEN="your-bot-token"

if [ $? -eq 0 ]; then
    MESSAGE="✅ Restic backup completed on $(hostname) at $(date)"
else
    MESSAGE="❌ Restic backup FAILED on $(hostname) at $(date)"
fi

curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
  -d "chat_id=${CHAT_ID}" -d "text=${MESSAGE}"

9. Testing Restores

⚠️ The most important section of this entire article. An untested backup is NOT a backup.

9.1 Borg Restore Test

# List available archives
borg list backupuser@backup-server:/backups/proxmox

# Mount an archive as a filesystem (read-only)
mkdir -p /mnt/restore-test
borg mount backupuser@backup-server:/backups/proxmox /mnt/restore-test

# Browse and verify files
ls /mnt/restore-test/proxmox-2026-07-26T01:46:00/etc/
diff /mnt/restore-test/proxmox-2026-07-26T01:46:00/etc/hosts /etc/hosts

# Unmount when done
borg umount /mnt/restore-test

9.2 Restic Restore Test

# List snapshots
restic snapshots

# Restore a specific snapshot to a temp directory
restic restore latest --target /tmp/restore-test --include /etc

# Verify a specific file
diff /tmp/restore-test/etc/hosts /etc/hosts

# Or mount and browse
mkdir -p /mnt/restic-mount
restic mount /mnt/restic-mount
# Browse to /mnt/restic-mount/snapshots/latest/

9.3 Automated Restore Testing

Create a script that tests restores monthly:

#!/bin/bash
# /usr/local/bin/test-restore.sh
TEST_DIR="/tmp/restore-test-$(date +%s)"
mkdir -p "$TEST_DIR"

# Restore /etc as a canary
borg extract \
  backupuser@backup-server:/backups/proxmox::proxmox-$(date +%Y-%m-%d) \
  etc/hosts etc/hostname etc/passwd

# Verify critical files exist
for file in etc/hosts etc/hostname etc/passwd; do
    if [ ! -f "$file" ]; then
        echo "FAIL: $file not found in restore"
        exit 1
    fi
done

echo "Restore test passed"
rm -rf "$TEST_DIR"

Schedule it: 0 5 1 * * root /usr/local/bin/test-restore.sh 2>&1 | logger -t restore-test

10. Retention Policies

10.1 Grandfather-Father-Son (GFS)

The classic GFS rotation keeps backups at multiple granularities:

Period	Keep	What it means
Daily	7	One backup per day, keep last 7
Weekly	4	One backup per week, keep last 4
Monthly	6	One backup per month, keep last 6
Yearly	1	One backup per year, keep 1

This gives you: 7 daily + 4 weekly + 6 monthly + 1 yearly = 18 archives total, covering an entire year of recovery points.

10.2 Borg Prune

# Prune old archives according to retention policy
borg prune \
  --keep-daily 7 \
  --keep-weekly 4 \
  --keep-monthly 6 \
  --keep-yearly 1 \
  backupuser@backup-server:/backups/proxmox

Or in borgmatic:

retention:
  keep_daily: 7
  keep_weekly: 4
  keep_monthly: 6
  keep_yearly: 1
  prefix: "{hostname}-"  # Only prune archives from this host

10.3 Restic Forget + Prune

# Mark old snapshots for deletion
restic forget \
  --keep-daily 7 \
  --keep-weekly 4 \
  --keep-monthly 6 \
  --keep-yearly 1

# Actually delete the data (frees space)
restic prune

# Or combine with backup command
restic backup /etc --tag daily
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --keep-yearly 1 --prune

💡 Tip: Run restic prune weekly, not daily. Pruning reorganizes the repository and can be slow on large repos. Forgetting just marks snapshots; pruning actually removes the data.

10.4 Repository Check

Periodically verify your repository integrity:

# Borg check (monthly)
borg check --verify-data backupuser@backup-server:/backups/proxmox

# Restic check (weekly for metadata, monthly for full data)
restic check  # Quick metadata check
restic check --read-data  # Full data integrity check (slower)

11. Conclusion — Summary and Key Takeaways

You now have a robust, automated, monitored, tested backup system. Here's the complete picture:

Your Backup Stack

Layer	Tool	Frequency	Target	Retention
VM-level	Proxmox vzdump	Daily 2AM	Local storage	7 daily
File-level	Borg	Daily 2:30AM	NAS via SSH	7d/4w/6m/1y
Offsite	Restic	Daily 3AM	S3/B2	7d/4w/6m/1y
Integrity	Borg check	Monthly	—	—
Restore test	Automated script	Monthly	/tmp	—

Key Takeaways

Automate everything — borgmatic + systemd timers + resticprofile = hands-off backups
Monitor aggressively — Zabbix + ntfy/Telegram notifications mean you know about failures immediately
Test restores regularly — mount a backup, verify files, document the process
Use retention policies — GFS keeps a year of recovery points without consuming infinite storage
Defense in depth — Borg for local (fast restores), Restic for offsite (survives site loss)
Document your restore process — when disaster strikes at 3 AM, you don't want to be reading man pages

Restore Runbook Template

1. SSH to backup server: ssh backupuser@backup-server
2. List archives: borg list /backups/proxmox
3. Mount archive: borg mount /backups/proxmox::proxmox-2026-07-26 /mnt/restore
4. Copy files: rsync -av /mnt/restore/etc/ /etc/
5. Verify services: systemctl status docker && docker compose ps
6. Document what was restored and why

Useful Resources

Sleep well knowing your homelab is protected! 🛡️

WireGuard VPN: Secure Remote Access for Your Homelab

Luna Commsnet — Sat, 22 Aug 2026 11:56:44 +0000

WireGuard VPN: Secure Remote Access for Your Homelab

1. Introduction — Why WireGuard over OpenVPN/IPsec

If you've ever set up a VPN for your homelab, you know the pain of fiddling with OpenVPN configs, dealing with bulky certificate authorities, or wrestling with IPsec's cryptic phase 1/phase 2 negotiations. WireGuard cuts through all that noise.

WireGuard is a lean, modern VPN protocol that:

Runs in the kernel — the Linux implementation is roughly 4,000 lines of code (compared to OpenVPN's 100,000+ and IPsec's 400,000+). This translates to blistering performance and a tiny attack surface.
Uses state-of-the-art cryptography by default — Curve25519 for key exchange, ChaCha20 for symmetric encryption, Poly1305 for authentication, BLAKE2s for hashing. No cipher suites to configure, no deprecated algorithms to accidentally enable.
Offers simple, deterministic configs — a typical peer config is 10-15 lines. Compare that to OpenVPN's 50+ line configs with certificate chains.
Is cross-platform — Linux, macOS, Windows, iOS, and Android all have native, officially-supported clients.
Roams seamlessly — switch from WiFi to cellular and your tunnel stays up. WireGuard's connectionless design means there's no "reconnect" delay.

For a homelab, this means you get enterprise-grade remote access without the enterprise-grade complexity. Whether you're checking on your Home Assistant automations from a coffee shop or pushing config updates to your Proxmox cluster from a hotel, WireGuard gets you there securely with minimal overhead.

WireGuard vs OpenVPN: Quick Comparison

Feature	WireGuard	OpenVPN	IPsec
Code size	~4,000 lines	~100,000 lines	~400,000 lines
Crypto agility	Fixed (secure defaults)	Configurable (easy to misconfigure)	Configurable (easy to misconfigure)
Performance	Kernel-space, fastest	User-space, slower	Kernel-space, fast but complex
Config complexity	10-15 lines per peer	50+ lines + certificates	30+ lines + phase 1/2
Key management	Static keys (simple)	X.509 PKI (complex)	IKE/ISAKMP (complex)
UDP support	Native	Yes (default)	Yes
TCP fallback	No (by design)	Yes	Yes
Connectionless	Yes (roams seamlessly)	No (must reconnect)	No
Auditability	High (small codebase)	Medium	Low (huge codebase)

⚠️ Note: WireGuard's lack of TCP fallback is intentional — if your network blocks outbound UDP, you'll need to address that at the network level (e.g., a VPS relay) rather than trying to tunnel over TCP. TCP-over-TCP is a performance disaster.

2. Prerequisites

Item	What you need
Server	Debian/Ubuntu (any recent release) with a public IPv4 address OR a Cloudflare Tunnel for port-forwarding
Client devices	Linux, macOS, Windows, iOS, Android — any combination
Root access	`sudo` on the server and on each Linux/macOS client (or admin rights on Windows)
Optional	A pfSense firewall in front of your server (highly recommended for homelabs)
UDP port	51820 (default) must be reachable on your server's public IP

💡 Tip: If your ISP blocks inbound UDP or you're behind CGNAT, spin up a cheap VPS ($3-5/month from Hetzner, Vultr, or Oracle's free tier) and run WireGuard there, then tunnel to your homelab over a WireGuard-to-WireGuard connection. Alternatively, use Cloudflare Tunnel to expose UDP 51820.

Network Planning

Before you start, decide on your VPN subnet. This should NOT overlap with any existing LAN subnet:

Common VPN subnets	Avoid if your LAN uses
10.0.0.0/24	10.0.0.0/24 (obviously)
10.100.0.0/24	Any 10.x.x.x range
172.16.0.0/24	172.16.0.0/12 ranges
192.168.100.0/24	192.168.x.0/24 ranges

For this guide, I'll use 10.100.0.0/24 for the VPN subnet and assume your homelab LAN is 192.168.1.0/24. Adjust accordingly.

3. Installing WireGuard

Server (Debian/Ubuntu)

# Update packages
sudo apt update

# Install WireGuard (included in kernel since 5.6, tools package provides wg/wg-quick)
sudo apt install -y wireguard

# Verify the kernel module is loaded
sudo modprobe wireguard
lsmod | grep wireguard

If you're running a very old kernel (< 5.6), you may need to install wireguard-dkms instead, which builds the module from source:

sudo apt install -y wireguard-dkms wireguard-tools

Client — Linux

sudo apt update && sudo apt install -y wireguard

Client — macOS (Homebrew or MacPorts)

brew install wireguard-tools

Or download the official macOS app from https://www.wireguard.com/install/ — it provides a system tray UI for managing tunnels.

Client — Windows

Download the official installer from https://www.wireguard.com/install/
Run the installer — it adds both a GUI (system tray tunnel manager) and the wireguard.exe CLI utility.
You can also install via winget: winget install WireGuard.WireGuard

Client — iOS / Android

iOS: App Store → search for "WireGuard" (published by WireGuard Development Team)
Android: Play Store → search for "WireGuard" or F-Droid → "WireGuard"

💡 Tip: On mobile, use the QR code feature to import configs. Run qrencode -t ansiutf8 < client.conf on your server to generate a scannable QR code in the terminal.

4. Server Configuration

4.1 Generate Server Keys

# Create directory for WireGuard config and keys
sudo mkdir -p /etc/wireguard
sudo chmod 700 /etc/wireguard

# Generate server private key and derive public key
umask 077
wg genkey | tee /etc/wireguard/server_private.key | wg pubkey > /etc/wireguard/server_public.key

# View the keys (you'll need the public key for client configs)
cat /etc/wireguard/server_public.key

⚠️ Warning: The private key file must never be committed to version control, shared, or world-readable. The umask 077 ensures only root can read it.

4.2 Create `wg0.conf`

# /etc/wireguard/wg0.conf
[Interface]
# Server private key — keep secret!
PrivateKey = <contents of server_private.key>

# VPN interface address
Address = 10.100.0.1/24

# UDP port to listen on
ListenPort = 51820

# MTU — lower if you experience connectivity issues over PPPoE/CGNAT
MTU = 1420

# Firewall rules: allow forwarding between wg0 and eth0, NAT outbound traffic
# Replace eth0 with your server's actual external interface (check with `ip a`)
PostUp = iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A FORWARD -o wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT; iptables -D FORWARD -o wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

# --- Peers will be added below ---
# [Peer]
# PublicKey = <client_public_key>
# AllowedIPs = 10.100.0.2/32

💡 Tip: To find your server's external interface name, run ip route get 8.8.8.8 | awk '{print $5; exit}'. Common names: eth0, ens3, enp3s0, wlan0.

4.3 Enable IP Forwarding

Without IP forwarding, your VPN clients can reach the server but not the LAN or internet beyond it:

# Enable immediately
sudo sysctl -w net.ipv4.ip_forward=1

# Persist across reboots
echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.d/99-wireguard.conf

# Verify
cat /proc/sys/net/ipv4/ip_forward
# Should output: 1

4.4 Start the Service

# Enable to start on boot
sudo systemctl enable wg-quick@wg0

# Start now
sudo systemctl start wg-quick@wg0

# Check status
sudo systemctl status wg-quick@wg0

# Verify the interface is up
ip a show wg0
# Should show: inet 10.100.0.1/24

# Check WireGuard status
sudo wg show

5. Client Configuration

5.1 Generate Client Keys (Repeat Per Device)

On your server (or any machine with wg installed):

# Create a directory for client configs
mkdir -p ~/wireguard-clients/laptop
cd ~/wireguard-clients/laptop

# Generate client keys
umask 077
wg genkey | tee laptop_private.key | wg pubkey > laptop_public.key

# View the public key (needed for server config)
cat laptop_public.key

5.2 Add the Client as a Peer on the Server

Edit /etc/wireguard/wg0.conf on the server and append:

[Peer]
# Laptop
PublicKey = <contents of laptop_public.key>
# Assign this client a static VPN IP
AllowedIPs = 10.100.0.2/32
# Optional: keepalive for NAT traversal (useful if client is behind NAT)
PersistentKeepalive = 25

Apply the change without restarting the tunnel:

sudo wg syncconf wg0 <(wg-quick strip wg0)

💡 Tip: wg syncconf applies config changes without dropping existing connections. Use this for adding/removing peers in production.

5.3 Client Config File

Create laptop.conf (or use the GUI import on Windows/macOS/iOS):

# /etc/wireguard/wg0.conf (on the client)
[Interface]
PrivateKey = <contents of laptop_private.key>
Address = 10.100.0.2/24
# DNS — use Cloudflare, or your homelab's Unbound/Pi-hole for ad-blocking
DNS = 1.1.1.1, 1.0.0.1

[Peer]
# The server
PublicKey = <contents of server_public.key>
Endpoint = your-homelab.example.com:51820
# Route ALL traffic through the VPN (full tunnel)
AllowedIPs = 0.0.0.0/0, ::/0
# Keepalive — critical if you're behind NAT (maintains the NAT mapping)
PersistentKeepalive = 25

5.4 Split Tunnel vs Full Tunnel

The AllowedIPs on the client config determines what traffic goes through the VPN:

Full Tunnel (all traffic):

AllowedIPs = 0.0.0.0/0, ::/0

Split Tunnel (only homelab traffic):

# Only route VPN subnet and homelab LAN through the tunnel
AllowedIPs = 10.100.0.0/24, 192.168.1.0/24

💡 Tip: Use split tunnel if you only need to access homelab services and want your regular internet traffic to go directly. Use full tunnel if you're on an untrusted network (coffee shop, hotel WiFi) and want all traffic encrypted.

5.5 Connect the Client

Linux:

sudo wg-quick up wg0
# Verify
sudo wg show
# Disconnect
sudo wg-quick down wg0

macOS/Windows/iOS/Android: Import the config file via the GUI app and toggle the switch.

5.6 Generate QR Code for Mobile Clients

# Install qrencode
sudo apt install -y qrencode

# Generate QR code in terminal
qrencode -t ansiutf8 < laptop.conf

Scan with the WireGuard app on iOS or Android — instant config import, no manual typing.

6. Connecting Your Homelab Services

Once the VPN tunnel is up, your client has a 10.100.0.x address that can reach your homelab. Here's how to access common services:

Service	Internal Address	VPN-Accessible Address	Notes
Nextcloud	`https://nextcloud.commsnet.org`	Same URL (split DNS) or `https://10.100.0.1:443`	Works with split DNS or direct IP
Home Assistant	`http://192.168.1.50:8123`	`http://192.168.1.50:8123`	Accessible if AllowedIPs includes 192.168.1.0/24
Proxmox VE	`https://192.168.1.10:8006`	`https://192.168.1.10:8006`	Direct access to web UI
Gitea	`https://git.commsnet.org`	Same URL via split DNS	Or `https://10.100.0.1:3000`
Pi-hole/Unbound	`192.168.1.53`	Same	Use as VPN DNS for ad-blocking on the go

Split DNS Setup

If you use domain names like nextcloud.commsnet.org that resolve to your public IP externally but your private LAN IP internally, you need split DNS. With a VPN, the easiest approach:

Set your VPN DNS to your homelab's DNS server (Pi-hole, Unbound, or CoreDNS):

   # In client config [Interface] section
   DNS = 192.168.1.53

Configure your DNS server to resolve your domains to internal IPs:
- Pi-hole: Add local DNS records under Settings → Local DNS
- Unbound: Add local-data entries in unbound.conf

This way, when you're on VPN and type nextcloud.commsnet.org, it resolves to 192.168.1.100 (internal) instead of your public IP, keeping traffic inside the tunnel.

7. Optional: WireGuard Behind Cloudflare Tunnel

If you don't have a static public IP (CGNAT, dynamic IP, or behind a restrictive ISP), Cloudflare Tunnel can expose WireGuard's UDP port securely without opening any inbound ports on your router.

7.1 How It Works

Client → Cloudflare Edge (UDP) → Cloudflare Tunnel → Your Server (UDP 51820)

7.2 Setup Steps

Create a Cloudflare Tunnel in the Zero Trust dashboard:

   https://one.dash.cloudflare.com → Networks → Tunnels → Create Tunnel

Install cloudflared on your server:

   sudo apt install cloudflared

Authenticate and run the tunnel:

   cloudflared tunnel login
   cloudflared tunnel create wireguard-relay

Configure the tunnel to forward UDP 51820:

   # ~/.cloudflared/config.yml
   tunnel: wireguard-relay
   credentials-file: /root/.cloudflare/wireguard-relay.json
   ingress:
     - hostname: wg.yourdomain.com
       service: udp://localhost:51820
     - service: http_status:404

Start the tunnel:

   cloudflared tunnel run wireguard-relay

Update client config to point to the tunnel hostname:

   [Peer]
   Endpoint = wg.yourdomain.com:51820

⚠️ Note: Cloudflare Tunnel for UDP is a relatively new feature. Check Cloudflare's documentation for current limitations and supported regions.

8. Security Hardening

8.1 pfSense Firewall Rules

If you run pfSense (or OPNsense) in front of your homelab, create explicit allow rules for WireGuard:

WAN Rules (inbound):

Navigate to Firewall → Rules → WAN
Add a new rule:
- Action: Pass
- Interface: WAN
- Address Family: IPv4
- Protocol: UDP
- Source: Any (or restrict to known IPs for extra security)
- Destination: WAN address
- Destination Port: 51820
- Description: "Allow WireGuard VPN inbound"
Place this rule above any default deny rule
Save and Apply

LAN Rules (optional — restrict VPN access to specific services):

Navigate to Firewall → Rules → LAN
Add rules to allow traffic from the VPN subnet (10.100.0.0/24) to specific destinations:
- Allow 10.100.0.0/24 → 192.168.1.50:8123 (Home Assistant)
- Allow 10.100.0.0/24 → 192.168.1.10:8006 (Proxmox)
- Deny 10.100.0.0/24 → 192.168.1.0/24:* (block everything else)

💡 Tip: Following the principle of least privilege, only allow VPN clients to access the specific services they need. Don't blanket-allow the entire LAN unless you trust all VPN users equally.

8.2 Kill Switch (Client Side)

A kill switch prevents traffic from leaking outside the VPN tunnel if the VPN connection drops.

Linux (iptables):

# Create a kill switch script: /etc/wireguard/killswitch.sh
#!/bin/bash
IFACE="wg0"

# Flush existing OUTPUT rules (careful if you have other rules!)
iptables -F OUTPUT

# Allow traffic through the VPN
iptables -A OUTPUT -o $IFACE -j ACCEPT

# Allow established/related connections
iptables -A OUTPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# Allow loopback
iptables -A OUTPUT -o lo -j ACCEPT

# Allow DHCP
iptables -A OUTPUT -p udp --dport 67:68 -j ACCEPT

# Drop everything else
iptables -A OUTPUT -j DROP

macOS (pf):

# /etc/pf.anchors/wireguard-killswitch
# Block all outbound except through utun (WireGuard interface)
block out on en0 all
pass out on utun8 all
pass out proto tcp to any port { 51820 }  # Allow WireGuard itself

Windows: The official WireGuard app includes a "Block untunneled traffic (kill switch)" option in the tunnel settings. Enable it.

8.3 DNS Leak Prevention

DNS leaks occur when your system queries DNS servers outside the VPN tunnel, potentially revealing your browsing habits to your ISP or network operator.

Prevention strategies:

Set VPN DNS in client config:

   [Interface]
   DNS = 192.168.1.53  # Your homelab Pi-hole/Unbound

Use systemd-resolved (Linux):

   # WireGuard integrates with systemd-resolved automatically
   # if wg-quick detects it. Verify with:
   resolvectl status

Test for leaks at https://dnsleaktest.com/ — all DNS servers shown should be your homelab's DNS, not your ISP's.

8.4 Key Rotation

WireGuard's static key model means you should rotate keys periodically:

# Generate a new key pair
wg genkey | tee new_client_private.key | wg pubkey > new_client_public.key

# Update the server config with the new public key
# Update the client config with the new private key

# Apply
sudo wg syncconf wg0 <(wg-quick strip wg0)

💡 Tip: For a homelab with 2-3 clients, manual rotation every 6-12 months is fine. For larger deployments, consider a key management tool like wg-quick with Ansible or a web UI like WireGuard Portal.

9. Troubleshooting Common Issues

Handshake Never Completes

Symptom: wg show on the client shows latest handshake: (never) and no data transfer.

Likely Cause	How to Check	Fix
UDP port blocked	`sudo tcpdump -i eth0 udp port 51820` on server	Open port 51820 on pfSense/router
Wrong endpoint address	Check `Endpoint` in client config	Verify public IP with `curl ifconfig.me`
NAT not forwarding	Check router port forwarding rules	Forward UDP 51820 to server's LAN IP
Key mismatch	Compare server's `PublicKey` with client config	Regenerate and re-import keys
Firewall on server	`sudo ufw status` or `iptables -L`	Allow UDP 51820: `sudo ufw allow 51820/udp`

No Internet After Connecting (Full Tunnel)

Symptom: VPN connects (handshake succeeds) but no internet access.

Cause: Missing NAT/masquerade rule or AllowedIPs issue.

# Check if NAT is working
sudo iptables -t nat -L POSTROUTING
# Should show MASQUERADE rule for your interface

# If missing, verify wg0.conf PostUp line:
# PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE

# Check IP forwarding
cat /proc/sys/net/ipv4/ip_forward
# Must be 1

Can't Access LAN Services (Split Tunnel)

Symptom: VPN is up, can reach 10.100.0.1 (server) but not 192.168.1.x (LAN devices).

Cause: AllowedIPs on client doesn't include the LAN subnet, or server isn't forwarding between interfaces.

# Client config — add LAN subnet to AllowedIPs
[Peer]
AllowedIPs = 10.100.0.0/24, 192.168.1.0/24

Also ensure the server's PostUp rules include forwarding:

PostUp = iptables -A FORWARD -i wg0 -j ACCEPT

MTU Problems

Symptom: VPN connects but large transfers stall or time out (SSH works, but scp hangs).

Cause: Path MTU discovery is broken (common with PPPoE, CGNAT, or nested tunnels).

# Add to both server and client [Interface] section:
MTU = 1420

# If still problematic, try lower:
MTU = 1280  # IPv6 minimum, very conservative

DNS Queries Leak (Go Through ISP Instead of VPN)

Cause: Client DNS not set, or system DNS resolver bypassing WireGuard.

# Check which DNS is being used
resolvectl status  # systemd-resolved
cat /etc/resolv.conf  # traditional

# Fix: set DNS in client config
# [Interface]
# DNS = 1.1.1.1, 192.168.1.53

`wg-quick` Fails with "Address already in use"

# Check if the interface is already up
sudo wg show

# Remove stale interface
sudo ip link del wg0

# Try again
sudo wg-quick up wg0

10. Conclusion — Summary and Next Steps

You now have a lightweight, high-performance WireGuard tunnel protecting remote access to your entire homelab. Here's what we covered:

Why WireGuard — faster, simpler, more secure than OpenVPN/IPsec
Installation — on all major platforms (Linux, macOS, Windows, iOS, Android)
Server setup — key generation, wg0.conf, IP forwarding, systemd service
Client setup — key generation, peer config, QR code import for mobile
Service access — connecting to Nextcloud, Home Assistant, Proxmox via VPN
Cloudflare Tunnel — for setups without a public IP
Security hardening — pfSense rules, kill switch, DNS leak prevention, key rotation
Troubleshooting — handshake failures, routing, MTU, DNS leaks

Next Steps

Automate key distribution: Use Ansible or a script to manage client configs across multiple devices
Set up monitoring: Monitor VPN connections with Zabbix or Prometheus (track wg show output)
Add 2FA: For sensitive homelab services, combine WireGuard with TOTP-based authentication
Multi-hop: If you travel frequently, set up a VPS relay as a WireGuard-to-WireGuard hop for extra anonymity
WireGuard Portal: For more than 5 clients, consider running WireGuard Portal for a web-based user management interface

Useful Resources

WireGuard official documentation
WireGuard on Arch Wiki (excellent even for non-Arch users)
Pi-hole + WireGuard — ad-blocking VPN combo
Pro Custodibus — WireGuard monitoring and management

Happy tunneling! 🚀

Self-Hosted Monitoring Stack: Zabbix + Grafana for Home Infrastructure

Luna Commsnet — Mon, 22 Jun 2026 15:51:36 +0000

Self-Hosted Monitoring Stack: Zabbix + Grafana for Home Infrastructure

Published: June 15, 2026 | CommsNet

You know that feeling when something breaks and you only find out because the website is down? That's not monitoring, that's embarrassment detection. Real monitoring tells you before things break. It shows you the memory leak that started three hours ago, the disk that's filling at 2% per day, the SSL certificate expiring in 12 days.

Enterprise monitoring platforms (Datadog, New Relic, Splunk) cost hundreds to thousands per month. For a homelab, that's absurd. But running blind is worse. The answer: self-hosted Zabbix for data collection and alerting, paired with Grafana for visualization. Together, they give you enterprise-grade observability at the cost of the electricity to run them.

In this article, I'll walk through deploying a complete Zabbix + Grafana monitoring stack on Proxmox, configuring agents across VLANs, building dashboards that actually tell you something, and setting up alerts that wake you up when they matter, not at 3 AM for a transient spike.

Why Zabbix + Grafana?

Monitoring Landscape and Why Zabbix Over Prometheus

Solution	Cost	Data Ownership	Complexity	Alerting	Dashboards
Datadog	$15-23/host/mo	Cloud (theirs)	Low	Excellent	Excellent
Prometheus + Grafana	Free	Self-hosted	Medium	Good	Excellent
Zabbix + Grafana	Free	Self-hosted	Medium-High	Excellent	Excellent (with Grafana)
Netdata	Free	Self-hosted	Low	Basic	Good (built-in)
Uptime Kuma	Free	Self-hosted	Low	Basic	Basic

Prometheus is the darling of the cloud-native world, and for good reason. But for homelab monitoring, Zabbix has advantages.

Agent-based collection works across VLANs. Prometheus pull-based scraping struggles with firewall rules between VLANs. Zabbix agents push data to the server (or use active checks), making firewall rules simpler.
Auto-discovery. Zabbix can discover hosts, interfaces, and services automatically. With Prometheus, you're writing prometheus.yml targets by hand.
Built-in templates. Zabbix has 400+ out-of-the-box templates for everything from Linux to pfSense to Proxmox to SNMP devices. Prometheus requires exporters for everything.
Trigger logic. Zabbix triggers support expressions like "average of last 5 minutes > threshold AND last value > threshold". Prometheus alerting rules are powerful but harder to compose.
Grafana integration. Zabbix data in Grafana gives you the best of both worlds, with Zabbix collection and Grafana visualization.

Zabbix has its own dashboards, but they look like 2005. Grafana is the visualization layer that adds beautiful, customizable dashboards, a unified view across multiple data sources, annotation layers (deploy events, maintenance windows), alerting with deduplication and routing, and mobile-responsive layouts so you can check your homelab from your phone.

Architecture

┌────────────────────────────────────────────────────────────────┐
│                    Monitoring Architecture                       │
│                                                                  │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────────┐  │
│  │ Proxmox  │   │ pfSense  │   │ Docker   │   │ IoT Devices  │  │
│  │ Agent    │   │ Agent    │   │ Agent    │   │ SNMP         │  │
│  │ (VLAN20) │   │ (VLAN10) │   │ (VLAN20) │   │ (VLAN30)    │  │
│  └────┬─────┘   └────┬─────┘   └────┬─────┘   └──────┬───────┘  │
│       │              │              │                 │          │
│       └──────────────┴──────┬───────┴─────────────────┘          │
│                             │                                     │
│                    ┌────────▼────────┐                            │
│                    │  Zabbix Server  │                            │
│                    │  (VLAN 20)      │                            │
│                    │  - Collection  │                            │
│                    │  - Alerting    │                            │
│                    │  - Triggers    │                            │
│                    └────────┬──────┘                            │
│                             │                                     │
│                    ┌────────▼────────┐                            │
│                    │    Grafana      │                            │
│                    │  (VLAN 20)      │                            │
│                    │  - Dashboards   │                            │
│                    │  - Visualization│                            │
│                    │  - Alert UI     │                            │
│                    └─────────────────┘                            │
│                                                                  │
│  Alert Channels: Telegram, Email, Webhook                       │
└────────────────────────────────────────────────────────────────┘

Network Considerations (VLAN-Aware)

Following our zero-trust VLAN architecture from the previous article, here is the layout.

Zabbix Server lives on VLAN 20 (Servers)
Zabbix Agents on VLAN 10 (Management) push data to server via active checks
SNMP polling from Zabbix to VLAN 30 (IoT) requires explicit firewall allow rules
Grafana on VLAN 20, with an optional reverse proxy on VLAN 50 (Services) if you want external access

Firewall rules needed

# Allow Zabbix agents → Zabbix server (active checks)
ALLOW  VLAN10 → VLAN20  TCP 10051  — "Management agents → Zabbix"
ALLOW  VLAN20 → VLAN20  TCP 10051  — "Server agents → Zabbix"

# Allow Zabbix server → IoT (SNMP polling, if desired)
ALLOW  VLAN20 → VLAN30  UDP 161    — "Zabbix SNMP poll IoT"

# Allow Grafana access from Management VLAN
ALLOW  VLAN10 → VLAN20  TCP 3000   — "MGMT → Grafana dashboard"

Deployment on Proxmox

Step 1: Create the Zabbix Server LXC

Proxmox LXC containers are perfect for monitoring, with low overhead, fast startup, and a full Linux userspace.

# Download Debian 12 LXC template
pveam download local debian-12-standard_12.2-1_amd64.tar.zst

# Create container
pct create 200 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
  --hostname zabbix \
  --memory 4096 \
  --swap 2048 \
  --cores 2 \
  --storage local-lvm \
  --rootfs local-lvm:32 \
  --net0 name=eth0,bridge=vmbr0.20,ip=10.0.20.10/24,gw=10.0.20.1 \
  --unprivileged 1 \
  --onboot 1 \
  --start 1

Why LXC instead of VM. Zabbix doesn't need its own kernel. LXC gives you 95% of a VM's isolation with 5% of the overhead. Your monitoring shouldn't be the heaviest thing on the host. Honestly, I learned this the hard way after initially running Zabbix in a full VM and watching it eat 4GB of RAM for no good reason.

Step 2: Install Zabbix Server + PostgreSQL

# Enter the container
pct enter 200

# Install PostgreSQL
apt update && apt install -y postgresql postgresql-contrib

# Create Zabbix database
sudo -u postgres createuser --pwprompt zabbix
sudo -u postgres createdb -O zabbix -E Unicode -T template0 zabbix

# Add Zabbix repository
wget https://repo.zabbix.com/zabbix/7.2/debian/pool/main/z/zabbix-release/zabbix-release_7.2-1+debian12_all.deb
dpkg -i zabbix-release_7.2-1+debian12_all.deb
apt update

# Install Zabbix server, frontend, and agent
apt install -y zabbix-server-pgsql zabbix-frontend-php zabbix-apache-conf zabbix-sql-scripts zabbix-agent2

# Import initial schema
zcat /usr/share/zabbix-sql-scripts/postgresql/server.sql.gz | \
  sudo -u zabbix psql zabbix

# Configure Zabbix server
cat > /etc/zabbix/zabbix_server.conf << 'EOF'
DBHost=localhost
DBName=zabbix
DBUser=zabbix
DBPassword=YOUR_POSTGRES_PASSWORD_HERE
LogFile=/var/log/zabbix/zabbix_server.log
LogFileSize=50
DebugLevel=3
StartPollers=5
StartPollersUnreachable=2
StartTrappers=5
StartDiscoverers=2
StartHTTPPollers=2
CacheSize=64M
HistoryCacheSize=32M
TrendCacheSize=8M
ValueCacheSize=32M
Timeout=10
EOF

# Start services
systemctl restart zabbix-server zabbix-agent2 apache2
systemctl enable zabbix-server zabbix-agent2 apache2

Step 3: Install Grafana and Connect to Zabbix

# Add Grafana repository
apt install -y apt-transport-https software-properties-common
wget -q -O /usr/share/keyrings/grafana.key https://apt.grafana.com/gpg.key

echo "deb [signed-by=/usr/share/keyrings/grafana.key] https://apt.grafana.com stable main" | \
  tee /etc/apt/sources.list.d/grafana.list

apt update && apt install -y grafana

# Configure Grafana
cat > /etc/grafana/grafana.ini << 'EOF'
[server]
http_addr = 10.0.20.11
http_port = 3000
domain = grafana.commsnet.local

[security]
admin_user = admin
admin_password = CHANGE_ME_IMMEDIATELY

[database]
type = sqlite3

[analytics]
reporting_enabled = false
check_for_updates = false

[auth.anonymous]
enabled = false
EOF

systemctl restart grafana-server
systemctl enable grafana-server

Connect Grafana to Zabbix

Install the Zabbix data source plugin in Grafana.

grafana-cli plugins install alexanderzobnin-zabbix-app
systemctl restart grafana-server

In Grafana UI, go to Configuration → Plugins → Zabbix.

Enable the Zabbix app plugin
Add data source with these settings
- Name: Zabbix
- Type: Zabbix API
- URL: http://10.0.20.10/zabbix/api_jsonrpc.php
- Username: Admin
- Password: Your Zabbix admin password
- Trends: Enable (use trends for long-term graphs)

Configuring Zabbix Agents

Agent on Proxmox Host, pfSense, and Docker Hosts

Proxmox Host

# On the Proxmox host itself
apt install -y zabbix-agent2

cat > /etc/zabbix/zabbix_agent2.conf << 'EOF'
Server=10.0.20.10
ServerActive=10.0.20.10
Hostname=proxmox-host
LogFile=/var/log/zabbix/zabbix_agent2.log
DebugLevel=3

# Custom metrics for Proxmox
UserParameter=pve.cluster.status,/usr/bin/pvesh get /cluster/status --output json 2>/dev/null | grep -c '"online"'
UserParameter=pve.vm.count,/usr/bin/qm list 2>/dev/null | wc -l
UserParameter=pve.ct.count,/usr/bin/pct list 2>/dev/null | wc -l
UserParameter=pve.storage.used[*],/usr/bin/pvesm status --storage $1 --output json 2>/dev/null | grep -o '"used":[0-9]*' | cut -d: -f2
UserParameter=pve.storage.total[*],/usr/bin/pvesm status --storage $1 --output json 2>/dev/null | grep -o '"total":[0-9]*' | cut -d: -f2
EOF

systemctl restart zabbix-agent2
systemctl enable zabbix-agent2

pfSense

pfSense has a Zabbix agent package available in Package Manager under Available Packages, called pfSense-zabbix-agent.

Configuration is straightforward:

Zabbix Server IP: 10.0.20.10
Zabbix Server Port: 10051
Hostname: pfsense
Enable active checks: Yes

pfSense-specific items to monitor

CARP status (if using HA)
Gateway quality (packet loss, latency, jitter)
State table utilization
DHCP lease counts per VLAN
Firewall rule denials per VLAN (from our zero-trust setup)
OpenVPN/WireGuard client counts
Interface traffic per VLAN

Docker Hosts

# docker-compose.yml for Zabbix agent
version: '3.8'
services:
  zabbix-agent:
    image: zabbix/zabbix-agent2:latest
    container_name: zabbix-agent
    restart: unless-stopped
    environment:
      - ZBX_SERVER_HOST=10.0.20.10
      - ZBX_HOSTNAME=docker-host-01
      - ZBX_ACTIVE_ALLOW=true
    volumes:
      - /:/hostfs:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    network_mode: host
    privileged: true

Docker-specific metrics

# Additional UserParameters for Docker
UserParameter=docker.container.count,/usr/bin/docker ps -q | wc -l
UserParameter=docker.container.running,/usr/bin/docker ps --filter status=running -q | wc -l
UserParameter=docker.image.count,/usr/bin/docker images -q | wc -l
UserParameter=docker.volume.count,/usr/bin/docker volume ls -q | wc -l

Zabbix Host Configuration

Adding Hosts and Customizing Templates

Go to Configuration → Hosts → Create Host.

Host	Templates	Groups	Interface	Proxy
proxmox-host	Linux by Zabbix agent, Proxmox VE by Zabbix	Servers	Agent: 10.0.20.5:10051	None
pfsense	pfSense by Zabbix	Network	Agent: 10.0.10.1:10051	None
docker-host-01	Linux by Zabbix agent, Docker by Zabbix	Servers	Agent: 10.0.20.20:10051	None
unifi-switch	SNMP Generic, Ubiquiti Switch	Network	SNMP: 10.0.10.2:161	None
cisco-2960	SNMP Generic, Cisco Switch	Network	SNMP: 10.0.10.3:161	None

Template Customization

Zabbix templates are good out of the box but need tuning for homelab scale. This surprised me when I first deployed Zabbix, as the defaults were constantly triggering false alarms in my homelab.

Linux by Zabbix agent, adjust trigger thresholds:

Trigger	Default	Homelab Adjusted	Reason
CPU load > 5min per core	5 per core	80% sustained 10min	Homelab CPUs burst, don't alert on spikes
Available memory < 20%	20%	10%	Homelab hosts use more memory; 20% is too sensitive
Disk space < 20%	20%	10%	Small disks fill faster; 20% on 100GB = 20GB free
Swap usage > 50%	50%	80%	Some swap usage is normal in homelabs

pfSense template, add custom items:

# Custom pfSense items via UserParameter
UserParameter=pfsense.gateway.loss[*],/usr/local/bin/php -r "require '/etc/inc/util.inc'; echo get_gateway_loss('$1');"
UserParameter=pfsense.dhcp.leases[*],/usr/local/bin/php -r "require '/etc/inc/util.inc'; echo count_dhcp_leases('$1');"
UserParameter=pfsense.firmware.version,/usr/local/bin/php -r "require '/etc/inc/util.inc'; echo get_firmware_version();"

Building Grafana Dashboards

Dashboards: Infrastructure, pfSense Security, and Proxmox

Infrastructure Overview

The single pane of glass for your entire homelab.

Panels:

Row: "Host Status" ────────────────────────────────
  [Stat]  Hosts Up          zabbix: hosts.count{status=0}
  [Stat]  Hosts Down        zabbix: hosts.count{status=1}
  [Stat]  Active Triggers   zabbix: triggers.count{value=1}

Row: "System Health" ──────────────────────────────
  [Time Series]  CPU Usage per Host    zabbix: system.cpu.util{host=*}
  [Gauge]        Memory % per Host     zabbix: vm.memory.util{host=*}
  [Time Series]  Disk I/O per Host     zabbix: vfs.dev.read{host=*}, vfs.dev.write{host=*}

Row: "Network" ─────────────────────────────────────
  [Time Series]  Traffic per VLAN      zabbix: net.if.in{host=pfsense,if=VLAN*}
  [Stat]         Firewall Denials/h    zabbix: pf.deny.count
  [Table]        Top Talkers          zabbix: net.if.total{host=*}

Row: "Storage" ─────────────────────────────────────
  [Gauge]   Proxmox Storage Used  zabbix: pve.storage.used[*]
  [Bar]     Docker Disk Usage     zabbix: vfs.fs.size{host=docker*,fs=/var/lib/docker}

pfSense Network Security

Dedicated to monitoring the zero-trust firewall.

Panels:

Row: "Firewall Activity" ──────────────────────────
  [Time Series]  Denials per VLAN/hour    zabbix: pf.deny{vlan=*}
  [Table]        Top Denied Sources       zabbix: pf.deny.src{groupby=src_ip}
  [Time Series]  Allow vs Deny Ratio      zabbix: pf.allow / pf.deny

Row: "Gateway Quality" ────────────────────────────
  [Time Series]  Packet Loss %             zabbix: pfsense.gateway.loss[*]
  [Time Series]  Latency ms               zabbix: pfsense.gateway.latency[*]
  [Stat]         Gateway Status            zabbix: pfsense.gateway.status

Row: "DHCP Leases" ────────────────────────────────
  [Stat]     MGMT Leases       zabbix: pfsense.dhcp.leases[MGMT]
  [Stat]     Server Leases     zabbix: pfsense.dhcp.leases[SERVERS]
  [Stat]     IoT Leases        zabbix: pfsense.dhcp.leases[IOT]
  [Stat]     Guest Leases      zabbix: pfsense.dhcp.leases[GUEST]
  [Table]    New Leases (24h)   zabbix: pfsense.dhcp.new_leases

Proxmox Virtualization

Panels:

Row: "Cluster Health" ─────────────────────────────
  [Stat]    Cluster Status          zabbix: pve.cluster.status
  [Stat]    VMs Running             zabbix: pve.vm.count
  [Stat]    CTs Running             zabbix: pve.ct.count

Row: "Resource Usage" ─────────────────────────────
  [Gauge]    CPU Total              zabbix: system.cpu.util{host=proxmox*}
  [Gauge]    Memory Total           zabbix: vm.memory.util{host=proxmox*}
  [Bar]      Storage per Pool      zabbix: pve.storage.used[*] / pve.storage.total[*]

Row: "VM/CT Details" ─────────────────────────────
  [Table]    All VMs + CPU/Mem/Disk  zabbix: pve.vm.{cpu,mem,disk}[*]
  [Table]    All CTs + CPU/Mem/Disk  zabbix: pve.ct.{cpu,mem,disk}[*]

Grafana Variables for Reusable Dashboards

Set up template variables so dashboards work across all hosts. I recommend creating variables for host, VLAN, and time interval so you can reuse dashboards flexibly.

Variable: $host
  Type: Query
  Query: zabbix: hosts*
  Multi-value: Yes
  Include All: Yes

Variable: $vlan
  Type: Custom
  Values: MGMT, SERVERS, IOT, GUEST, SERVICES

Variable: $interval
  Type: Interval
  Values: 1m,5m,10m,30m,1h,6h,1d
  Auto: Yes

Alerting: Wake Me When It Matters

Zabbix Triggers and Grafana Alerts

The alerting pipeline flows like this:

Zabbix Agent → Zabbix Server (trigger fires) → Grafana Alert Rule → Notification Policy → Channel

Critical, Warning, and Information Alerts

Critical alerts (wake me up)

Alert	Trigger Expression	Severity	Channel
Host down	`nodata(5m)`	Disaster	Telegram + Email
Disk > 90%	`last(/{HOST}/vfs.fs.size[pct])>90`	High	Telegram
pfSense down	`nodata(3m)` on pfSense	Disaster	Telegram + Email
Gateway packet loss > 10%	`last(/{HOST}/pfsense.gateway.loss)>10`	High	Telegram
Zabbix server down	Internal zabbix trigger	Disaster	Email (fallback)

Warning and information alerts

Alert	Trigger Expression	Severity	Channel
CPU > 80% sustained	`avg(10m)>80`	Warning	Dashboard only
Memory > 85%	`last(/{HOST}/vm.memory.util)>85`	Warning	Dashboard only
Certificate expiring < 14 days	`last(/{HOST}/cert.days_left)<14`	Warning	Email digest
Docker container stopped	`last(/{HOST}/docker.container.running)<expected`	Warning	Dashboard only
New DHCP lease on MGMT VLAN	Event log match	Info	Weekly digest
Firmware update available	`diff(/{HOST}/pfsense.firmware.version)`	Info	Weekly digest
Storage growth rate > 5%/week	`trend(7d)>5`	Info	Weekly digest

Telegram Alert Integration

Grafana supports Telegram natively. Create a bot via @BotFather and configure it in Grafana under Alerting, then Contact points, and Add Contact Point.

  Type: Telegram
  BOT API Token: YOUR_BOT_TOKEN
  Chat ID: YOUR_CHAT_ID

Notification Policy:
  Group by: alertname, severity
  Group wait: 30s
  Group interval: 5m
  Repeat interval: 4h

  Route: severity=disaster → Telegram immediately
  Route: severity=high → Telegram, 5m repeat
  Route: severity=warning → Email digest, 1d repeat
  Route: severity=info → Weekly email

Performance Tuning

Zabbix Housekeeper, Database, and Retention

Zabbix's built-in housekeeper is notoriously slow with PostgreSQL. Replace it with partitioned tables using TimescaleDB.

-- Connect to Zabbix database
sudo -u postgres psql zabbix

-- Enable partitioning extension
CREATE EXTENSION IF NOT EXISTS timescaledb;

-- Convert history tables to hypertables (TimescaleDB)
SELECT create_hypertable('history', 'clock', chunk_time_interval => 86400);
SELECT create_hypertable('history_uint', 'clock', chunk_time_interval => 86400);
SELECT create_hypertable('history_str', 'clock', chunk_time_interval => 86400);
SELECT create_hypertable('trends', 'clock', chunk_time_interval => 2592000);
SELECT create_hypertable('trends_uint', 'clock', chunk_time_interval => 2592000);

Disable Zabbix internal housekeeper since TimescaleDB handles it now.

# /etc/zabbix/zabbix_server.conf
DisableHousekeeping=1

Set retention policies

-- Keep raw history for 14 days
SELECT add_retention_policy('history', INTERVAL '14 days');
SELECT add_retention_policy('history_uint', INTERVAL '14 days');
SELECT add_retention_policy('history_str', INTERVAL '14 days');

-- Keep trends for 2 years
SELECT add_retention_policy('trends', INTERVAL '2 years');
SELECT add_retention_policy('trends_uint', INTERVAL '2 years');

Database Size Estimates

Monitoring	Items	History/Day	14-Day History	2-Year Trends	Total DB Size
5 hosts	~500	~15 MB	~210 MB	~200 MB	~500 MB
10 hosts	~1000	~30 MB	~420 MB	~400 MB	~1 GB
20 hosts	~2000	~60 MB	~840 MB	~800 MB	~2 GB

A homelab with 10-20 hosts will use 1-2 GB of storage over 2 years. That's nothing.

Backup Strategy

Your monitoring data is valuable. It contains your baseline, your history, your incident timeline. Back it up.

Zabbix Database Backup

#!/bin/bash
# zabbix-backup.sh — Daily Zabbix database backup
BACKUP_DIR="/mnt/nas/backups/zabbix"
DATE=$(date +%Y-%m-%d)
RETENTION_DAYS=30

# PostgreSQL dump
sudo -u postgres pg_dump zabbix | gzip > "${BACKUP_DIR}/zabbix_${DATE}.sql.gz"

# Zabbix config
tar czf "${BACKUP_DIR}/zabbix_config_${DATE}.tar.gz" \
  /etc/zabbix/ /etc/grafana/

# Cleanup old backups
find "${BACKUP_DIR}" -name "zabbix_*.sql.gz" -mtime +${RETENTION_DAYS} -delete
find "${BACKUP_DIR}" -name "zabbix_config_*.tar.gz" -mtime +${RETENTION_DAYS} -delete

echo "Backup complete: ${DATE}"

Grafana Dashboard Export

Grafana dashboards should be version-controlled. I recommend committing them to git because your dashboards are infrastructure code, not click-and-hope.

#!/bin/bash
# grafana-export.sh — Export all dashboards as JSON
GRAFANA_URL="http://10.0.20.11:3000"
API_KEY="YOUR_GRAFANA_API_KEY"
OUTPUT_DIR="/home/commstech/grafana-dashboards"

# Get all dashboard UIDs
DASHBOARDS=$(curl -s -H "Authorization: Bearer ${API_KEY}" \
  "${GRAFANA_URL}/api/search?type=dash-db" | \
  jq -r '.[] | .uid')

# Export each dashboard
for UID in ${DASHBOARDS}; do
  curl -s -H "Authorization: Bearer ${API_KEY}" \
    "${GRAFANA_URL}/api/dashboards/uid/${UID}" | \
    jq '.dashboard' > "${OUTPUT_DIR}/${UID}.json"
done

echo "Exported $(echo ${DASHBOARDS} | wc -w) dashboards"

Cost Summary

Item	Cost	Notes
Zabbix Server (LXC on Proxmox)	$0	Already have hardware
Grafana (LXC on Proxmox)	$0	Already have hardware
PostgreSQL + TimescaleDB	$0	Open source
Zabbix Agents	$0	Open source
Storage (2 GB over 2 years)	$0	Negligible
Telegram bot for alerts	$0	Free tier
Total Monthly Cost	$0	Self-hosted, zero subscriptions

Compare to Datadog at $15/host/month for 10 hosts = $150/month = $1,800/year. You're saving $1,800/year by self-hosting.

Dashboard Screenshots Description

Since this is a text article, here is what your dashboards should look like.

Dashboard Visual Descriptions

Infrastructure Overview Dashboard

Top row has three large stat panels: green "5 Hosts Up", red "0 Hosts Down", orange "2 Active Warnings"
Middle left shows a time series graph with CPU usage for all hosts over the last 1 hour, with an 80% threshold line
Middle right displays gauge panels showing memory usage per host (color-coded: green < 60%, yellow 60-80%, red > 80%)
Bottom left has a network traffic stacked area chart per VLAN
Bottom right shows storage usage as a horizontal bar chart per Proxmox pool

pfSense Security Dashboard

Top row shows firewall deny rate time series, which should display a consistent low rate. Any spike is suspicious.
Middle has a table of top 10 denied source IPs with last attempt time
Bottom displays DHCP lease count per VLAN as small bar charts, with "new in 24h" annotation

Next Steps

With monitoring in place, you can now do the following.

Set up automated remediation. Zabbix can run scripts on alert (restart a service, clear a cache)
Add log monitoring. Forward syslog from pfSense, Proxmox, and Docker to Zabbix
Implement capacity planning. Use trend data to predict when you'll run out of disk/CPU/memory
Add synthetic monitoring. Zabbix web scenarios to check your services are actually responding
Integrate with Home Assistant. Send Zabbix alerts to your home automation for visual/audio alerts

Key Takeaways

Self-hosted monitoring costs nothing but electricity. Zabbix + Grafana is enterprise-grade, free, and yours
Zabbix for collection, Grafana for visualization. Each tool does what it does best
Active checks work across VLANs. Agents push data, no need to open inbound ports
Tune your triggers for homelab scale. Enterprise defaults are too sensitive for home infrastructure
TimescaleDB partitioning is essential. The built-in housekeeper will kill your database performance
Alert on what matters, ignore what doesn't. Disaster means wake me, warning means check in morning, info means weekly digest
Version-control your dashboards. They're infrastructure code, not click-and-hope
Back up your monitoring data. It's your operational history, and losing it means losing your baselines

CommsNet, building infrastructure that respects your privacy and your intelligence.

Follow on Medium and Dev.to for more homelab, networking, and self-hosting content.

This article is also published on:

Medium: Coming soon
Dev.to: Self-Hosted Monitoring Stack: Zabbix + Grafana for Home Infrastructure

Originally published at wiki.commsnet.org. Follow CommsNet for more homelab, networking, and self-hosting content.

Sponsor our work: GitHub Sponsors

Zero-Trust Homelab: Network Segmentation with VLANs and pfSense

Luna Commsnet — Mon, 22 Jun 2026 15:51:19 +0000

Zero-Trust Homelab: Network Segmentation with VLANs and pfSense

Published: June 15, 2026 | CommsNet

If everything on your network can reach everything else, you don't have a network. You have a single point of failure the size of your entire infrastructure. One compromised IoT lightbulb becomes a pivot to your NAS. One breached container becomes a foothold on your management VLAN. In a flat network, trust is binary, you're either in or you're out.

Zero-trust networking changes the assumption. Nothing is trusted by default. Every segment, every device, every flow must prove it belongs. And the mechanism that enforces this at the homelab scale isn't some expensive SDN controller. It's VLANs on a managed switch, enforced by pfSense firewall rules.

In this article, I'll walk through designing and implementing a zero-trust network segmentation strategy using IEEE 802.1Q VLANs, a managed switch, and pfSense as the inter-VLAN router and policy enforcement point. By the end, your IoT devices won't be able to touch your servers, your guest WiFi will be isolated at L2, and your management interfaces will require explicit allow rules.

Why Zero-Trust for a Homelab?

The Flat Network Problem

Most homelabs start as flat networks, one /24, everything plugged into one switch, maybe a consumer router doing NAT. It works until it doesn't.

Attack Vector	Flat Network Impact	Segmented Network Impact
Compromised IoT device	Lateral movement to NAS, servers	Contained to IoT VLAN, blocked at firewall
Malware on guest laptop	Access to all L2 hosts	Isolated to guest VLAN, no cross-VLAN routing
Exposed service exploit	Direct path to management interfaces	Must traverse firewall rules between VLANs
DNS poisoning on one host	Affects entire broadcast domain	Limited to single VLAN scope

Zero-Trust Principles (Adapted for Homelab)

Enterprise zero-trust frameworks (NIST SP 800-207, Forrester ZTX) assume things homelabbers don't have, like identity providers, microsegmentation platforms, and continuous verification. But the core principles translate.

Never trust, always verify. Every inter-VLAN flow is denied by default, explicitly allowed.
Least privilege access. VLANs get only the routing rules they need.
Assume breach. Design so that compromising one VLAN doesn't compromise others.
Verify explicitly. pfSense rules are the policy; logging proves enforcement.

Network Design

VLAN Architecture

Here's the segmentation model I use in my homelab, designed around the principle of isolation by trust level.

┌─────────────────────────────────────────────────────────┐
│                    VLAN Architecture                      │
│                                                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │  VLAN 10  │  │  VLAN 20  │  │  VLAN 30  │  │ VLAN 40 │ │
│  │Management│  │  Servers  │  │   IoT     │  │  Guest  │ │
│  │10.0.10/24│  │10.0.20/24│  │10.0.30/24│  │10.0.40 │ │
│  │ TRUST: H │  │ TRUST: H │  │ TRUST: L │  │TRUST: N│ │
│  └─────┬────┘  └─────┬────┘  └─────┬────┘  └────┬────┘ │
│        │              │              │            │       │
│        └──────────────┴──────┬───────┴────────────┘       │
│                              │                            │
│                     ┌────────┴────────┐                   │
│                     │    pfSense      │                   │
│                     │  Inter-VLAN     │                   │
│                     │  Router + FW    │                   │
│                     └────────────────┘                   │
└─────────────────────────────────────────────────────────┘

VLAN Definitions and Trust Model

VLAN ID	Name	Subnet	Trust Level	Purpose
10	Management	10.0.10.0/24	High	pfSense, Proxmox, switches, IPMI/iDRAC
20	Servers	10.0.20.0/24	High	NAS, Docker hosts, application servers
30	IoT	10.0.30.0/24	Low	Smart devices, sensors, cameras
40	Guest	10.0.40.0/24	None	Guest WiFi, untrusted devices
50	Services	10.0.50.0/24	Medium	Exposed services, reverse proxy, tunnel endpoints

The firewall policy is the heart of zero-trust. Every rule is explicit.

Source VLAN → Destination VLAN → Allowed? → Reason
─────────────────────────────────────────────────────
Management → Any              → ALLOW     → Admin access
Servers    → Management       → DENY      → No reverse access to mgmt
Servers    → Servers          → ALLOW     → Internal service communication
Servers    → IoT              → DENY      → No need to reach IoT
Servers    → Services         → ALLOW     → Publish services
IoT       → Servers           → LIMITED   → Only specific ports (DNS, NTP, specific API)
IoT       → Management       → DENY      → No access to mgmt interfaces
IoT       → Internet         → ALLOW     → Firmware updates, cloud APIs
IoT       → Guest            → DENY      → Mutual isolation
Guest     → Any (internal)   → DENY      → Complete isolation
Guest     → Internet          → ALLOW     → Internet-only access
Services  → Servers           → ALLOW     → Reverse proxy to backends
Services  → Management       → DENY      → No access to mgmt

Hardware Requirements

You don't need enterprise gear. Here's what works at the homelab scale.

Managed Switch and pfSense Hardware

You need a switch that supports 802.1Q VLAN tagging. Options by budget.

Switch	Ports	VLAN Support	Price (Used)	Notes
Cisco Catalyst 2960	24/48	Full 802.1Q	$30-80	Bulletproof, CLI only
HPE ProCurve 2530	24	Full 802.1Q	$40-100	Web UI + CLI
TP-Link SG108E	8	Basic 802.1Q	$25	Budget starter, limited CLI
Ubiquiti USW-24	24	Full + UI	$100-200	UniFi ecosystem
MikroTik CRS326	24	Full + RouterOS	$80	Powerful but steep learning curve

My pick: Cisco Catalyst 2960G, cheap on eBay, never dies, full VLAN feature set. The CLI is an investment that pays off. I learned this the hard way after burning through two consumer "smart" switches that quietly dropped tagged frames under load.

pfSense runs the inter-VLAN routing and firewall. Options.

Option	Cost	Performance	Notes
Netgate SG-1100	$179	~1 Gbps routing	Purpose-built, low power
Protectli Vault	$300+	~2 Gbps routing	Intel NICs, fanless
Repurposed PC + 4 NICs	$50-100	3+ Gbps routing	Best performance/$, more power draw
Proxmox VM + virtio NICs	$0	~10 Gbps routing	Already have Proxmox? Use it

My pick: pfSense as a Proxmox VM with 4 virtio NICs. You already have the hardware. Honestly, if you're running Proxmox already, there's no reason to buy separate firewall hardware unless you need that physical separation for compliance.

Implementation: Step by Step

Step 1: Configure VLANs on pfSense

Navigate to Interfaces → Assignments → VLANs and create each VLAN.

Parent Interface: vmx0 (LAN)
VLAN Tag: 10  Priority: 0  Description: Management
VLAN Tag: 20  Priority: 0  Description: Servers  
VLAN Tag: 30  Priority: 0  Description: IoT
VLAN Tag: 40  Priority: 0  Description: Guest
VLAN Tag: 50  Priority: 0  Description: Services

Then assign each VLAN as a new interface.

Interfaces → Assignments:

vmx0.10 → OPT1 → rename to MGMT
vmx0.20 → OPT2 → rename to SERVERS
vmx0.30 → OPT3 → rename to IOT
vmx0.40 → OPT4 → rename to GUEST
vmx0.50 → OPT5 → rename to SERVICES

Enable each interface and set its IPv4 Static address.

MGMT:     10.0.10.1/24
SERVERS:  10.0.20.1/24
IOT:      10.0.30.1/24
GUEST:    10.0.40.1/24
SERVICES: 10.0.50.1/24

Step 2: Configure DHCP for Each VLAN

Services → DHCP Server, enable on each VLAN interface.

Interface	Range	DNS	Gateway	Lease Time
MGMT	10.0.10.100-10.0.10.200	10.0.10.1	10.0.10.1	86400
SERVERS	10.0.20.100-10.0.20.200	10.0.20.1	10.0.20.1	86400
IOT	10.0.30.50-10.0.30.200	1.1.1.1, 9.9.9.9	10.0.30.1	3600
GUEST	10.0.40.50-10.0.40.200	1.1.1.1	10.0.40.1	3600
SERVICES	Static only	10.0.50.1	10.0.50.1	N/A

Key decisions:

IoT/Guest DNS: Point to public resolvers (1.1.1.1), NOT your internal DNS. These VLANs don't need to resolve internal names.
Services: No DHCP, all services get static IPs. If someone plugs into this VLAN, they get nothing.
Short lease times on IoT/Guest: Limits how long a rogue device keeps an address.

Step 3: Configure the Managed Switch

This is where VLAN theory meets physical reality. Each switch port must be configured as access (untagged, single VLAN) or trunk (tagged, multiple VLANs).

Port assignments:

Port 1-8:   Access, VLAN 20 (Servers)       NAS, Proxmox hosts, Docker servers
Port 9-12:  Access, VLAN 30 (IoT)           Smart devices, cameras
Port 13-16: Access, VLAN 40 (Guest)         Guest WiFi AP
Port 17-20: Access, VLAN 10 (Management)    Management workstations
Port 21-24: Trunk, VLAN ALL (tagged)         pfSense, Proxmox, WiFi AP

Cisco 2960 example config:

! Trunk port to pfSense
interface GigabitEthernet0/21
  switchport mode trunk
  switchport trunk allowed vlan 10,20,30,40,50
  switchport trunk native vlan 99  ! Never use VLAN 1 as native
  spanning-tree portfast trunk

! Access port for server
interface range GigabitEthernet0/1 - 8
  switchport mode access
  switchport access vlan 20
  spanning-tree portfast

! Access port for IoT
interface range GigabitEthernet0/9 - 12
  switchport mode access
  switchport access vlan 30
  spanning-tree portfast

! Access port for management workstation
interface range GigabitEthernet0/17 - 20
  switchport mode access
  switchport access vlan 10
  spanning-tree portfast

Critical: Set native vlan 99 (or any unused VLAN) on trunk ports. Never use VLAN 1 as the native VLAN, it's the default attack surface on every Cisco switch.

Step 4: Firewall Rules, The Zero-Trust Core

This is where zero-trust is actually enforced. Navigate to Firewall → Rules for each interface.

Management VLAN (Highest Trust)

# MGMT Interface Rules (evaluated top-to-bottom)
#
# 1. Allow MGMT to anything (admin access)
IPv4 *  MGMT net  *  *  *  →  ALLOW  // "MGMT: Allow all outbound"
#
# 2. Allow pfSense DNS from MGMT
IPv4 TCP/UDP  MGMT net  *  MGMT address  53  →  ALLOW  // "MGMT: DNS to pfSense"
#
# 3. Block everything else (implicit, but be explicit)
IPv4 *  *  *  MGMT net  *  →  DENY  // "MGMT: Block all inbound"

Management is simple, full outbound access, no inbound from other VLANs. Admins initiate connections to infrastructure; infrastructure never reaches back.

Servers VLAN

# SERVERS Interface Rules
#
# 1. Allow Servers → Servers (internal communication)
IPv4 *  SERVERS net  *  SERVERS net  *  →  ALLOW  // "SERVERS: Inter-server communication"
#
# 2. Allow Servers → Internet (updates, API calls)
IPv4 *  SERVERS net  *  !RFC1918  *  →  ALLOW  // "SERVERS: Internet access"
#
# 3. Allow Services → Servers (reverse proxy backends)
IPv4 TCP  SERVICES net  *  SERVERS net  80,443,8080  →  ALLOW  // "SERVICES: Reverse proxy to backends"
#
# 4. Block everything else
IPv4 *  *  *  SERVERS net  *  →  DENY  // "SERVERS: Block all other inbound"

Key rule: SERVERS → !RFC1918 allows internet access but blocks access to any other internal VLAN. Servers can reach the internet for updates but cannot reach IoT, Guest, or Management.

IoT VLAN (Low Trust)

# IOT Interface Rules (MOST RESTRICTIVE)
#
# 1. Allow IoT → pfSense DNS
IPv4 TCP/UDP  IOT net  *  IOT address  53  →  ALLOW  // "IOT: DNS to pfSense"
#
# 2. Allow IoT → pfSense NTP
IPv4 UDP  IOT net  *  IOT address  123  →  ALLOW  // "IOT: NTP to pfSense"
#
# 3. Allow specific IoT → Server API (e.g., Home Assistant)
IPv4 TCP  IOT net  *  10.0.20.50  8123  →  ALLOW  // "IOT: Home Assistant API"
#
# 4. Allow IoT → Internet (firmware, cloud APIs)
IPv4 *  IOT net  *  !RFC1918  *  →  ALLOW  // "IOT: Internet access"
#
# 5. Block everything else
IPv4 *  *  *  IOT net  *  →  DENY  // "IOT: Block all other inbound"

The IoT rules are surgical, only DNS, NTP, one specific API endpoint, and internet. This is the most important VLAN to lock down because IoT devices are the most likely to be compromised. This surprised me when I first started auditing my own IoT traffic, some smart plugs were making hundreds of outbound connections an hour to servers in countries I didn't expect.

Pro tip: Use aliases in pfSense for the IoT API rules. Create an alias IoT_Allowed_Services with the specific server IPs and ports IoT devices need. This makes it easy to add new devices without creating new rules.

Guest VLAN (No Trust)

# GUEST Interface Rules (TOTAL ISOLATION)
#
# 1. Allow Guest → Internet only
IPv4 *  GUEST net  *  !RFC1918  *  →  ALLOW  // "GUEST: Internet only"
#
# 2. Allow Guest → pfSense DNS (DHCP-assigned)
IPv4 TCP/UDP  GUEST net  *  GUEST address  53  →  ALLOW  // "GUEST: DNS"
#
# 3. Block everything else
IPv4 *  *  *  GUEST net  *  →  DENY  // "GUEST: Complete isolation"

Guests get internet. Nothing else. This is the simplest and most important rule set.

Services VLAN (Exposed Services)

# SERVICES Interface Rules
#
# 1. Allow Services → Servers (reverse proxy backends)
IPv4 TCP  SERVICES net  *  SERVERS net  80,443,8080,8123  →  ALLOW  // "SERVICES: Proxy to backends"
#
# 2. Allow Services → Internet (cert renewal, API calls)
IPv4 *  SERVICES net  *  !RFC1918  *  →  ALLOW  // "SERVICES: Internet access"
#
# 3. Block everything else
IPv4 *  *  *  SERVICES net  *  →  DENY  // "SERVICES: Block all other inbound"

Services VLAN is the DMZ equivalent. It can reach backends on specific ports and the internet for Let's Encrypt/certbot renewals. It cannot reach management, IoT, or guest.

Advanced: pfSense Aliases for Zero-Trust Maintenance

One of the most underused features in pfSense is aliases, named groups of networks, hosts, or ports that make firewall rules readable and maintainable.

Firewall → Aliases:

Name: MGMT_Net        Type: Host(s)    Value: 10.0.10.0/24
Name: SERVERS_Net     Type: Host(s)    Value: 10.0.20.0/24
Name: IOT_Net         Type: Host(s)    Value: 10.0.30.0/24
Name: GUEST_Net       Type: Host(s)    Value: 10.0.40.0/24
Name: SERVICES_Net    Type: Host(s)    Value: 10.0.50.0/24
Name: RFC1918         Type: Network   Value: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
Name: IoT_API_Targets Type: Host(s)    Value: 10.0.20.50  (Home Assistant)
Name: Web_Ports       Type: Port(s)    Value: 80, 443, 8080
Name: IoT_Allowed     Type: Port(s)    Value: 8123, 1883, 5353

Now your rules use human-readable names.

DENY  IOT_Net    →  RFC1918       //  *        //  "IOT: Block internal access"
ALLOW IOT_Net    →  IoT_API_Targets → IoT_Allowed  //  "IOT: Allowed services only"

When you add a new IoT device that needs to reach a different service, you update the alias, not the rule. This prevents rule sprawl, which is the #1 way zero-trust degrades over time.

Verification: Proving Your Segmentation Works

Setting up rules isn't enough. You need to verify they work. Here's how.

Verification: Proving Your Segmentation Works

Setting up rules isn't enough. You need to verify they work. Here's how.

Test 1: IoT Cannot Reach Management

From an IoT device (or a laptop plugged into an IoT port).

# Should FAIL (blocked by firewall)
nmap -p 22 10.0.10.1    # pfSense SSH
nmap -p 443 10.0.10.1   # pfSense WebUI
nmap -p 8006 10.0.10.5  # Proxmox WebUI

# Should SUCCEED (allowed)
ping 1.1.1.1            # Internet
dig @10.0.30.1 example.com  # DNS

Test 2: Guest Cannot Reach Any Internal Host

From a guest device.

# All should FAIL
ping 10.0.10.1    # Management
ping 10.0.20.1    # Servers
ping 10.0.30.1    # IoT
nmap 10.0.20.0/24 # Scan entire server VLAN

# Should SUCCEED
ping 1.1.1.1      # Internet

Test 3: Servers Cannot Reach Management

From a server.

# Should FAIL
ssh admin@10.0.10.1     # pfSense
curl https://10.0.10.5:8006  # Proxmox

# Should SUCCEED
ping 10.0.20.1          # Servers gateway
curl https://example.com # Internet

Test 4: pfSense Firewall Logs

Status → System Logs → Firewall.

Watch for denied packets between VLANs. If you see unexpected allowed traffic, your rules are wrong. If you see denied traffic that should be allowed, check your alias definitions.

Pro tip: Enable Log packets that are handled by this rule on every DENY rule. This gives you a complete audit trail of every attempted cross-VLAN connection.

WiFi Considerations

If you're running WiFi (and you should for IoT/mobile), the AP must support multiple SSIDs mapped to VLANs.

UniFi AP VLAN Configuration and WiFi Firewall Rules

SSID: "CommsNet-Home"     → VLAN 20 (Servers/Trusted devices)
SSID: "CommsNet-IoT"      → VLAN 30 (IoT only)
SSID: "CommsNet-Guest"    → VLAN 40 (Guest, rate-limited)

Each SSID gets its own DHCP scope from pfSense, its own firewall rules, and complete L2 isolation. The AP tags frames with the appropriate VLAN ID; pfSense routes and enforces policy.

WiFi-specific firewall additions.

# Rate limit Guest WiFi
IPv4 *  GUEST net  *  *  *  →  ALLOW  //  "GUEST: Rate limited"
  ↑ Limit: 10 Mbps down, 5 Mbps up per client
  ↑ Connection limit: 100 concurrent per /32

pfSense traffic shaping (limiter queues) can enforce per-client bandwidth caps on guest and IoT VLANs. This prevents one guest device from consuming your entire upstream.

Monitoring and Alerting

Zero-trust without monitoring is just wishful thinking. You need to know when segmentation fails.

pfSense Integration with Zabbix/Grafana and Suricata IDS

Install the pfSense Zabbix Agent package.

Package Manager → Available Packages → pfSense-zabbix-agent

Monitor these key metrics.

Metric	What It Tells You	Alert Threshold
Firewall deny rate	How many cross-VLAN attempts blocked	Sudden spike = scanning/recon
Interface traffic per VLAN	Normal traffic baseline	IoT VLAN talking to server VLAN = breach
DHCP lease count per VLAN	Device count per segment	New device on Management VLAN = investigate
State table utilization	Active connections	>80% = possible flood or compromised host
pfSense CPU/memory	Router health	>80% sustained = capacity issue

Enable Suricata on each VLAN interface for deep packet inspection.

Services → Suricata → Interfaces → Add
  Interface: VLAN_30 (IoT)
  Mode: IPS (Inline Prevention)
  Block offenders: Yes
  Alert only on new threats: Yes

Suricata on the IoT VLAN catches things like IoT devices phoning home to unexpected IPs, malware C2 beacon patterns, and known exploit signatures targeting IoT firmware. In my setup, Suricata caught a cheap WiFi outlet trying to call a Chinese IP every 30 seconds. That device is now quarantined in a separate VLAN with zero internet access.

Common Mistakes and Fixes

Mistake 1: Forgetting to Disable VLAN 1

VLAN 1 is the default on every switch. Every port is in it. If you don't explicitly disable it, you have a shadow flat network running alongside your segmented one.

Fix: Create a VLAN 99 as the native VLAN on all trunk ports and move all unused ports to a dead VLAN.

! Move all unused ports to dead VLAN
interface range GigabitEthernet0/22 - 24
  switchport mode access
  switchport access vlan 99
  shutdown

Mistake 2: Over-Allowing on Trunk Ports

switchport trunk allowed vlan all is lazy and dangerous. Only allow the VLANs that need to traverse each trunk.

Fix:

interface GigabitEthernet0/21
  switchport trunk allowed vlan 10,20,30,40,50
  ! NOT: switchport trunk allowed vlan all

Mistakes 3 and 4: Floating Rules and Missing Logs

Floating rules in pfSense apply globally and can bypass per-interface rules. If you use floating rules, make sure they don't accidentally allow cross-VLAN traffic. Avoid floating rules for inter-VLAN policies; use interface-specific rules. Use floating rules only for traffic shaping or QoS.

If you don't log denied packets, you have no way to detect reconnaissance, failed intrusion attempts, or misconfigured devices. Enable logging on every DENY rule. Set up a syslog server to aggregate and analyze firewall logs.

Cost Summary

Item	Cost	Notes
Cisco 2960G (used)	$50	eBay, 24-port managed
pfSense (VM on Proxmox)	$0	Already have hardware
Cat6 patch cables	$15	Monoprice 10-pack
UniFi AP AC Lite (used)	$40	Multi-SSID VLAN support
Total	$105	One-time cost

No subscriptions. No per-device licensing. No cloud dependencies. This is infrastructure you own, understand, and control.

What's Next?

This article covers L2/L3 segmentation. In the next article in this series, we'll add the following.

WireGuard VPN for remote management VLAN access (never expose pfSense to the internet)
Cilium eBPF policies for micro-segmentation within the server VLAN (container-to-container)
pfSense CARP for high-availability firewall failover
Automated compliance checks, scripts that verify your firewall rules match your zero-trust policy

Key Takeaways

Flat networks are the enemy. One compromised device becomes a pivot to everything.
VLANs + pfSense rules = zero-trust at homelab scale. No enterprise license required.
Deny by default, allow by exception. Every inter-VLAN flow must be justified.
IoT is your biggest risk. Isolate it to DNS + NTP + one API endpoint.
Guest gets internet only. No exceptions, no "just this once."
Log every deny. Visibility is how you prove zero-trust works.
Aliases keep rules maintainable. Rule sprawl is how zero-trust dies.
Test your segmentation. If you haven't verified it, it's probably broken.

CommsNet, Building infrastructure that respects your privacy and your intelligence.

Follow on Medium and Dev.to for more homelab, networking, and self-hosting content.

This article is also published on:

Medium: Coming soon
Dev.to: Zero-Trust Homelab: Network Segmentation with VLANs and pfSense

Originally published at wiki.commsnet.org. Follow CommsNet for more homelab, networking, and self-hosting content.

Sponsor our work: GitHub Sponsors

From ISP Lock-in to Control: Self-Hosting Nextcloud/Home Assistant Behind Cloudflare Tunnels

Luna Commsnet — Mon, 22 Jun 2026 15:51:00 +0000

From ISP Lock-in to Control: Self-Hosting Nextcloud/Supervised Behind Cloudflare Tunnels

Published: May 27, 2026 | CommsNet

Your ISP gave you a CGNAT address, blocked port 25, and thinks "advanced router settings" means changing the WiFi password. You're paying for a connection you don't control, and every cloud subscription is another monthly tax on data you should own.

This article is the exit strategy. We're going to self-host Nextcloud for file sync, calendar, and contacts, plus Home Assistant Supervised for home automation, all behind Cloudflare Tunnels so nothing is exposed directly to the internet. No port forwarding, no DDNS, no static IP required. Your ISP doesn't even need to know you're running services.

The Problem with ISP Defaults

What ISPs Do	Why It Matters
CGNAT (Carrier-Grade NAT)	You can't receive inbound connections, so no port forwarding is possible
Blocked ports (25, 80, 443)	Even with a public IP, common service ports are blocked
Dynamic IP addresses	DDNS works around this, but it's fragile
Residential TOS restrictions	"No servers" clauses in fine print
No IPv6 or broken IPv6	Dual-stack is no longer optional
Asymmetric bandwidth	Upload is 10% of download, so your "cloud" uploads crawl

The answer isn't a VPS that adds another monthly bill and another provider who can suspend you. The answer is Cloudflare Tunnels, outbound-only connections that punch through CGNAT, avoid blocked ports, and give you your own domain with TLS termination.

Architecture

                    ┌─────────────────┐
                    │  Cloudflare Edge  │
                    │  (Anycast CDN)    │
                    └────────┬─────────┘
                             │ HTTPS
                    ┌────────┴─────────┐
                    │ Cloudflare Tunnel  │
                    │ (cloudflared)      │
                    │ ← outbound only → │
                    └────────┬─────────┘
                             │ localhost
              ┌──────────────┼──────────────┐
              │              │              │
        ┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
        │ Nextcloud  │ │  Home      │ │  Other     │
        │ :8080      │ │ Assistant  │ │ Services   │
        │            │ │  :8123     │ │  :XXXX     │
        └────────────┘ └───────────┘ └────────────┘
              │              │              │
        ┌─────┴─────────────┴──────────────┴────┐
        │            Docker Network              │
        │         (internal only)                │
        └───────────────────────────────────────┘

Key insight. All connections are outbound from your server to Cloudflare. Your firewall never opens an inbound port. Your ISP never sees a server.

Step 1: Domain and Cloudflare Setup

Prerequisites and DNS Setup

You'll need a domain name (transfer to Cloudflare Registrar or use any registrar with Cloudflare DNS), a Cloudflare account (free tier works for tunnels), and Docker with Docker Compose on your server.

I learned this the hard way when I first tried self-hosting behind a CGNAT connection. Spent three days fighting port forwarding before realizing it was never going to work. Cloudflare Tunnels solved it in under an hour.

Point your domain's nameservers to Cloudflare, then add A/AAAA records for your services.

nextcloud.commsnet.org    → Proxied (orange cloud) → Tunnel
hass.commsnet.org         → Proxied (orange cloud) → Tunnel
files.commsnet.org        → Proxied (orange cloud) → Tunnel

The "Proxied" toggle is critical because it enables Cloudflare's TLS termination and DDoS protection. Your origin server IP never appears in DNS.

Step 2: Cloudflare Tunnel

Install and Authenticate cloudflared

# Debian/Ubuntu
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

# Or via package manager
sudo cloudflared --version

Authenticate and create your tunnel.

# Authenticate with your Cloudflare account
cloudflared tunnel login

# Create the tunnel
cloudflared tunnel create homelab

# Note the tunnel ID from the output, you'll need it
# Example: TUNNEL_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Now create ~/.cloudflared/config.yml with your tunnel configuration.

tunnel: TUNNEL_ID
credentials-file: /home/youruser/.cloudflared/TUNNEL_ID.json

ingress:
  # Nextcloud
  - hostname: nextcloud.commsnet.org
    service: http://localhost:8080
    originRequest:
      noTLSVerify: true

  # Home Assistant
  - hostname: hass.commsnet.org
    service: http://localhost:8123
    originRequest:
      noTLSVerify: true

  # Catch-all rule (required)
  - service: http_status:404

DNS Records, Testing, and Service Setup

# Create CNAME records pointing to the tunnel
cloudflared tunnel route dns homelab nextcloud.commsnet.org
cloudflared tunnel route dns homelab hass.commsnet.org

This automatically creates the CNAME records in Cloudflare DNS pointing <subdomain>.commsnet.org to <TUNNEL_ID>.cfargotunnel.com.

Test the tunnel by running it manually first.

cloudflared tunnel run homelab

If everything works, you'll see the tunnel connect and your services will be accessible at their respective hostnames, all over HTTPS, all without opening a single inbound port. Honestly, the first time I saw this work behind a CGNAT connection, it felt like magic.

Once confirmed, install it as a systemd service.

# Install as systemd service
sudo cloudflared service install

# Enable and start
sudo systemctl enable cloudflared
sudo systemctl start cloudflared

# Check status
sudo systemctl status cloudflared

Step 3: Nextcloud with Docker Compose

Directory Structure and docker-compose.yml

nextcloud/
├── docker-compose.yml
├── .env
├── data/
│   ├── nextcloud/
│   ├── db/
│   └── redis/
└── config/
    ├── nginx/
    │   └── nginx.conf
    └── php/
        └── uploads.ini

version: "3.8"

services:
  nextcloud-db:
    image: postgres:16-alpine
    container_name: nextcloud-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./data/db:/var/lib/postgresql/data
    networks:
      - nextcloud-internal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 30s
      timeout: 10s
      retries: 3

  nextcloud-redis:
    image: redis:7-alpine
    container_name: nextcloud-redis
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - ./data/redis:/data
    networks:
      - nextcloud-internal
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 30s
      timeout: 10s
      retries: 3

  nextcloud-app:
    image: nextcloud:30-apache
    container_name: nextcloud-app
    restart: unless-stopped
    depends_on:
      nextcloud-db:
        condition: service_healthy
      nextcloud-redis:
        condition: service_healthy
    environment:
      POSTGRES_HOST: nextcloud-db
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      REDIS_HOST: nextcloud-redis
      REDIS_HOST_PASSWORD: ${REDIS_PASSWORD}
      NEXTCLOUD_ADMIN_USER: ${NEXTCLOUD_ADMIN_USER}
      NEXTCLOUD_ADMIN_PASSWORD: ${NEXTCLOUD_ADMIN_PASSWORD}
      NEXTCLOUD_TRUSTED_DOMAINS: nextcloud.commsnet.org
      OVERWRITEPROTOCOL: https
      OVERWRITECLIURL: https://nextcloud.commsnet.org
      SMTP_HOST: ${SMTP_HOST}
      SMTP_PORT: 587
      SMTP_SECURE: tls
      SMTP_NAME: ${SMTP_USER}
      SMTP_PASSWORD: ${SMTP_PASSWORD}
      MAIL_FROM_ADDRESS: nextcloud
      MAIL_DOMAIN: commsnet.org
    volumes:
      - ./data/nextcloud:/var/www/html
      - ./config/php/uploads.ini:/usr/local/etc/php/conf.d/uploads.ini:ro
    networks:
      - nextcloud-internal
      - nextcloud-exposed
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:80/status.php || exit 1"]
      interval: 60s
      timeout: 15s
      retries: 3

  nextcloud-cron:
    image: nextcloud:30-apache
    container_name: nextcloud-cron
    restart: unless-stopped
    depends_on:
      nextcloud-app:
        condition: service_healthy
    volumes:
      - ./data/nextcloud:/var/www/html
    entrypoint: /cron.sh
    networks:
      - nextcloud-internal

networks:
  nextcloud-internal:
    driver: bridge
    internal: true   # No external access, only app is exposed
  nextcloud-exposed:
    driver: bridge

Environment File and PHP Tuning

# .env, NEVER commit this to git
POSTGRES_DB=nextcloud
POSTGRES_USER=nextcloud_db
POSTGRES_PASSWORD=<generate-with: openssl rand -hex 32>

REDIS_PASSWORD=<generate-with: openssl rand -hex 32>

NEXTCLOUD_ADMIN_USER=admin
NEXTCLOUD_ADMIN_PASSWORD=<generate-with: openssl rand -hex 32>

SMTP_HOST=smtp.example.com
SMTP_USER=nextcloud@commsnet.org
SMTP_PASSWORD=<your-smtp-password>

; config/php/uploads.ini
upload_max_filesize = 16G
post_max_size = 16G
max_execution_time = 3600
max_input_time = 3600
memory_limit = 512M

Notice the two Docker networks in the compose file. nextcloud-internal has no external routing, so the database and Redis can only be reached by Nextcloud containers. nextcloud-exposed is where the app container also sits, so Cloudflare Tunnel can reach it on localhost:8080.

The database and Redis are never accessible from outside the Docker network. Even if an attacker compromises the tunnel, they can't directly reach PostgreSQL or Redis.

Step 4: Home Assistant Supervised

Why Supervised Instead of Home Assistant OS

Home Assistant OS is the easy path, but it's a black box. You can't install custom add-ons, manage it with Docker Compose, or integrate it with your existing infrastructure. Supervised gives you the same UI and add-on store, but on your terms.

Install the required packages first.

# Install required packages for Supervised
sudo apt install -y \
  apparmor \
  jq \
  network-manager \
  dbus \
  curl \
  socat \
  avahi-daemon \
  udisks2 \
  libglib2.0-bin

Docker Compose for Home Assistant

version: "3.8"

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    environment:
      - TZ=America/Chicago
    volumes:
      - ./config/hass:/config
      - /etc/localtime:/etc/localtime:ro
    network_mode: host  # HA needs host networking for device discovery
    # Health check
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8123"]
      interval: 60s
      timeout: 10s
      retries: 5

  # Home Assistant Supervised Installer
  # Run this ONCE to install the supervisor, then remove this service
  hass-supervisor-installer:
    image: homeassistant/amd64-hassio-supervisor:latest
    container_name: hassio_supervisor
    restart: unless-stopped
    privileged: true
    environment:
      - SUPERVISOR_SHARE=/etc/hassio
      - SUPERVISOR_NAME=hassio_supervisor
    volumes:
      - /etc/hassio:/etc/hassio
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/run/dbus:/var/run/dbus
      - /etc/machine-id:/etc/machine-id:ro
    network_mode: host

Simpler Alternative (Non-Supervised)

If you don't need the add-on store, a plain HA container is simpler and more maintainable. This surprised me when I set it up for a family member who just wanted basic automations without the overhead.

version: "3.8"

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    environment:
      - TZ=America/Chicago
    volumes:
      - ./config/hass:/config
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "8123:8123"
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8123"]
      interval: 60s
      timeout: 10s
      retries: 5
    networks:
      - homeassistant

networks:
  homeassistant:
    driver: bridge

Cloudflare Tunnel Configuration for HA

Add this to your ~/.cloudflared/config.yml.

  # Home Assistant
  - hostname: hass.commsnet.org
    service: http://homeassistant:8123
    originRequest:
      noTLSVerify: true

Important. Home Assistant requires WebSocket support for real-time updates. Cloudflare Tunnels handle WebSocket proxying automatically, so no extra configuration is needed.

Step 5: Security Hardening

Nextcloud Security and Fail2Ban

After first login, configure these in config.php (or via OCC).

<?php
// data/nextcloud/config/config.php additions

'force_ssl' => true,
'default_phone_region' => 'US',
'memcache.local' => '\\OC\\Memcache\\APCu',
'memcache.distributed' => '\\OC\\Memcache\\Redis',
'memcache.locking' => '\\OC\\Memcache\\Redis',
'redis' => [
    'host' => 'nextcloud-redis',
    'port' => 6379,
    'password' => 'your-redis-password',
],
'maintenance' => false,
'theme' => '',
'loglevel' => 2,
'auth.bruteforce.protection.enabled' => true,
'share_folder' => '/Shared',
'trashbin_retention_obligation' => '30,180',
'activity_expire_days' => 90,
'simpleSignUpLink.shown' => false,
];

For brute-force protection, fail2ban can ban offending IPs at the firewall level. Here is the configuration.

# /etc/fail2ban/filter.d/nextcloud.conf
[Definition]
groups = nextcloud
failregex = ^.*Login failed.*Remote IP.*<HOST>.*$
            ^.*Bruteforce attempt.*Remote IP.*<HOST>.*$
ignoreregex =

# /etc/fail2ban/jail.d/nextcloud.conf
[nextcloud]
enabled = true
port = 80,443
filter = nextcloud
logpath = /path/to/nextcloud/data/nextcloud.log
maxretry = 5
bantime = 3600
findtime = 600

Note. Cloudflare Tunnels mean all traffic appears from Cloudflare IPs. Fail2ban won't be effective unless you configure the TRUSTED_PROXIES setting and use the X-Forwarded-For header. For most homelab users, Nextcloud's built-in brute-force protection is sufficient.

Home Assistant Security and Cloudflare Access

# config/hass/configuration.yaml additions

# Require login
homeassistant:
  auth_providers:
    - type: homeassistant
    - type: legacy_api_password  # Remove after migration

# IP ban after failed attempts
http:
  ip_ban_enabled: true
  login_attempts_threshold: 5
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.16.0.0/12    # Docker networks
    - 127.0.0.1        # Localhost (cloudflared)

For an extra layer, add Cloudflare Zero Trust authentication before your service. This is worth the extra setup time.

# Create an Access application in Cloudflare Zero Trust dashboard
# Settings → Zero Trust → Access → Applications → Add Application

# Configuration:
# Application name: Home Assistant
# Domain: hass.commsnet.org
# Policy: Email OTP (one-time password to your email)
# Or: Identity provider (Google, GitHub, etc.)

Now visitors hit Cloudflare's login wall before they even see Home Assistant. Two layers of authentication, zero ports open. I run this on my own homelab and it has been rock solid for months.

Step 6: Monitoring and Backups

Health Checks and Monitoring

# Add to your docker-compose.yml
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    restart: unless-stopped
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_SCHEDULE=0 0 4 * * *    # 4 AM daily
      - WATCHTOWER_NOTIFICATIONS=email
      - WATCHTOWER_NOTIFICATION_EMAIL_FROM=watchtower@commsnet.org
      - WATCHTOWER_NOTIFICATION_EMAIL_TO=admin@commsnet.org
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.example.com
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=${SMTP_USER}
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=${SMTP_PASSWORD}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - nextcloud-internal

Backups

#!/bin/bash
# backup-nextcloud.sh - Run daily via cron

# 1. Put Nextcloud in maintenance mode
docker exec -u www-data nextcloud-app php occ maintenance:mode --on

# 2. Dump PostgreSQL
docker exec nextcloud-db pg_dump -U nextcloud_db nextcloud > /backups/nextcloud-db-$(date +%Y%m%d).sql

# 3. Sync data directory
rsync -az --delete /path/to/nextcloud/data/ /backups/nextcloud-data/

# 4. Take Nextcloud out of maintenance mode
docker exec -u www-data nextcloud-app php occ maintenance:mode --off

# 5. Upload to offsite (optional: Backblaze B2, S3, etc.)
# rclone sync /backups/ remote:nextcloud-backups/

For Home Assistant, add automatic backups to configuration.yaml.

# Home Assistant automatic backups (in configuration.yaml)
automation:
  - alias: "Daily Backup"
    trigger:
      - platform: time
        at: "03:00:00"
    action:
      - service: backup.create
        data:
          name: "Daily Backup {{ now().strftime('%Y-%m-%d') }}"
          keep_days: 7

Troubleshooting

Common Issues and Fixes

Tunnel won't connect.

# Check cloudflared logs
sudo journalctl -u cloudflared -f

# Common issues:
# 1. DNS records not created, run `cloudflared tunnel route dns` again
# 2. Credentials file missing, check ~/.cloudflared/ for the JSON file
# 3. Firewall blocking outbound 7844, Cloudflare uses this port for tunnel protocol

Nextcloud shows wrong URL.

# Force the correct URL in config.php
docker exec -u www-data nextcloud-app php occ config:system:set overwrite.cli.url --value="https://nextcloud.commsnet.org"
docker exec -u www-data nextcloud-app php occ config:system:set overwriteprotocol --value="https"

Home Assistant not accessible.

# Check container health
docker inspect homeassistant | jq '.[0].State'

# Check logs
docker logs homeassistant --tail 50

# Common issue: WebSocket not upgrading
# Ensure your Cloudflare tunnel config has noTLSVerify: true
# and that you're using http:// not https:// in the service URL

Nextcloud performance is slow.

# Enable Redis caching (verify in config.php)
docker exec -u www-data nextcloud-app php occ status

# Check Redis connection
docker exec nextcloud-redis redis-cli -a "$REDIS_PASSWORD" ping

# Run maintenance tasks
docker exec -u www-data nextcloud-app php occ maintenance:repair
docker exec -u www-data nextcloud-app php occ files:scan --all

What You've Gained

Before (ISP Defaults)	After (This Setup)
CGNAT (no inbound connections)	Cloudflare Tunnel (outbound only)
Cloud storage subscriptions	Self-hosted Nextcloud (your data, your rules)
Exposed ports for services	Zero open inbound ports
No home automation centralization	Home Assistant with full control
Dynamic IP DDNS hacks	Cloudflare-managed DNS with automatic TLS
No backup strategy	Automated daily backups to offsite
Single point of failure	Health checks and automated recovery

Monthly Cost Comparison

Service	Cloud Subscription	Self-Hosted
File storage (1TB)	Google One: $9.99/mo	Nextcloud: $0
Calendar/Contacts	Google: Free (data tax)	Nextcloud: $0
Home Automation	Nabu Casa: $6.50/mo	HA Supervised: $0
Domain	$0	Cloudflare: ~$10/yr
Cloudflare Tunnels	$0	Free
Electricity (est.)	$0	~$5-10/mo
Total	$16.49/mo	~$1/mo + electricity

You break even in under a year, and you own your data forever.

Next Steps

Get a domain by transferring to Cloudflare or pointing nameservers there
Set up Cloudflare Tunnel in 15 minutes, zero ports opened
Deploy Nextcloud with Docker Compose, then configure and migrate your data
Deploy Home Assistant starting small, adding integrations over time
Set up backups that are automated, offsite, and tested
Monitor with Watchtower for updates and health checks for uptime

Self-hosting isn't just about saving money. It's about owning your infrastructure, your data, and your time. When Google sunsets a product or Dropbox changes their terms, you won't care, because your files are on your hardware, behind your domain, on your terms.

CommsNet builds secure, sovereign infrastructure. More at wiki.commsnet.org

Tags: #selfhosted #nextcloud #homeassistant #cloudflare #tunnels #docker #privacy #homelab #degoogling

This article is also published on:

Medium: Coming soon
Dev.to: From ISP Lock-in to Control: Self-Hosting Nextcloud Behind Cloudflare Tunnels

Originally published at wiki.commsnet.org. Follow CommsNet for more homelab, networking, and self-hosting content.

Sponsor our work: GitHub Sponsors

Building a Secure Homelab with Proxmox VE, pfSense, and Cilium

Luna Commsnet — Mon, 22 Jun 2026 15:50:33 +0000

Building a Secure Homelab with Proxmox VE, pfSense, and Cilium

Published: May 25, 2026 | CommsNet

Your homelab shouldn't be a flat network where every container can talk to every service. That's the ISP's model, one big subnet, trust everything. But you're running your own infrastructure now. You get to do better.

In this article, I'll walk through building a layered, observable homelab using three technologies that complement each other beautifully: Proxmox VE for virtualization, pfSense for network segmentation, and Cilium for eBPF-based observability and micro-segmentation. By the end, you'll have a setup where a compromised container can't pivot to your storage array, your traffic flows are visible at the kernel level, and your firewall rules actually mean something because your VLANs enforce them.

Why This Stack?

Proxmox VE, The Foundation

Proxmox gives you KVM virtual machines and LXC containers on the same hypervisor, with a decent web UI, ZFS-backed storage, and cluster support. It's the closest thing to an enterprise data center you can run on repurposed desktop hardware. Honestly, I was surprised how quickly it becomes second nature once you get past the initial learning curve.

What matters for security is straightforward

Separate physical NICs for WAN, LAN, and management. Don't trunk everything over one interface.
Linux Bridge isolation. Each VLAN gets its own bridge, and bridges don't route between each other without explicit firewall rules.
AppArmor profiles for LXC containers. Even your unprivileged containers get kernel-level confinement.

pfSense, The Gatekeeper

pfSense sits at your network boundary and between your VLANs. It's not sexy, but it's reliable. FreeBSD's packet filter is battle-tested, and pfSense gives you a usable GUI on top of it.

What you get with pfSense

Inter-VLAN firewalling. Your IoT VLAN cannot reach your server VLAN unless you write a rule.
Alias-based rules. Group IPs and ports by function, not by individual addresses.
VPN concentrator. WireGuard or OpenVPN for remote access without exposing services.
Traffic shaping. Because your backup job shouldn't saturate your upload.

Cilium, The Observer

This is where it gets interesting. Cilium uses eBPF to inject observability and security policies directly into the Linux kernel, with no sidecar proxies and no iptables chaos. It sees every packet, every connection, every DNS lookup, and it can enforce policy at Layer 3/4 and Layer 7.

Why Cilium in a homelab

Hubble. Real-time service map showing every connection between your workloads.
Network policies. Kubernetes-native micro-segmentation that pfSense can't see inside your cluster.
eBPF observability. Kernel-level tracing without modifying applications.
Transparent encryption. WireGuard-based encryption between nodes, managed declaratively.

Architecture Overview

                    ┌─────────────┐
                    │   Internet   │
                    └──────┬──────┘
                           │ WAN
                    ┌──────┴──────┐
                    │   pfSense    │
                    │  (VM on      │
                    │  Proxmox)    │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────┴─────┐ ┌───┴───┐ ┌─────┴─────┐
        │  VLAN 10   │ │VLAN 20│ │  VLAN 30   │
        │  Trusted   │ │  IoT  │ │  Servers   │
        │  LAN       │ │       │ │  (K8s)     │
        └─────┬─────┘ └───────┘ └─────┬─────┘
              │                        │
        ┌─────┴─────┐          ┌───────┴────────┐
        │ Workstations│        │  Proxmox Node   │
        │ Printers    │        │  ┌─────────────┐│
        │ Media        │        │  │  K8s Cluster  ││
        └─────────────┘        │  │  + Cilium    ││
                               │  │  + Hubble     ││
                               │  └─────────────┘│
                               └─────────────────┘

Step 1: Proxmox Network Foundation

Proxmox Network Configuration

Don't skip this. Using a single NIC with VLAN tagging works in a pinch, but separate physical interfaces eliminate a whole class of failure modes. I learned this the hard way when a single trunked NIC failed and took down every VLAN at once during a firmware update.

# Check your NICs
ip link show

# Assign roles in /etc/network/interfaces
# eno1 → WAN (passed through to pfSense VM)
# eno2 → vmbr0 (LAN - VLAN 10)
# eno3 → vmbr1 (Server - VLAN 30)
# eno4 → vmbr2 (IoT - VLAN 20)

Now configure your bridges in /etc/network/interfaces.

# /etc/network/interfaces on Proxmox host

# Management bridge (access your Proxmox web UI)
auto vmbr0
iface vmbr0 inet static
    address 10.10.10.1/24
    bridge-ports eno2
    bridge-stp off
    bridge-fd 0

# Server VLAN bridge
auto vmbr1
iface vmbr1 inet static
    address 10.30.10.1/24
    bridge-ports eno3
    bridge-stp off
    bridge-fd 0

# IoT VLAN bridge (isolated)
auto vmbr2
iface vmbr2 inet static
    address 10.20.10.1/24
    bridge-ports eno4
    bridge-stp off
    bridge-fd 0

Proxmox Firewall Basics

Enable the datacenter firewall, but keep it simple initially. Block all by default, allow only what's needed.

# /etc/pve/firewall/cluster.fw
[OPTIONS]
enable: 1
policy_in: DROP
policy_out: ACCEPT

[RULES]
# Allow SSH from management subnet only
IN ACCEPT -source 10.10.10.0/24 -p tcp -dport 22 -log nolog
# Allow Proxmox web UI from management subnet
IN ACCEPT -source 10.10.10.0/24 -p tcp -dport 8006 -log nolog
# Allow pfSense management
IN ACCEPT -source 10.10.10.0/24 -p tcp -dport 443 -dest 10.10.10.2 -log nolog

Step 2: pfSense as VLAN Firewall

pfSense VLAN Rules and Aliases

Create pfSense as a VM with at least 2 vCPUs and 2GB RAM. Attach NICs as follows

Interface	Bridge	Role
vtnet0	WAN passthrough	Internet
vtnet1	vmbr0	LAN (VLAN 10)
vtnet2	vmbr1	Server (VLAN 30)
vtnet3	vmbr2	IoT (VLAN 20)

This is where most homelabs fall apart. If your IoT devices can reach your NAS, you've already lost. The principle is simple.

Default deny. Allow only what's explicitly needed.

LAN to Any (Trusted)

# LAN interface, your workstations and admin machines
# Allow all outbound (your trusted users)
pass in on vtnet1 from 10.10.10.0/24 to any

Server to LAN (Selective)

# Server interface, K8s nodes, storage, services
# Allow established connections back
pass in on vtnet2 proto tcp from 10.30.10.0/24 to 10.10.10.0/24 port { 22, 443, 6443 } keep state
# Block everything else
block in on vtnet2 from 10.30.10.0/24 to 10.10.10.0/24

IoT to Only Internet (Locked Down)

# IoT interface, your smart devices, cameras, TVs
# Allow DNS and NTP outbound
pass in on vtnet3 proto { tcp, udp } from 10.20.10.0/24 to any port { 53, 123 }
# Allow HTTP/HTTPS outbound for firmware updates
pass in on vtnet3 proto tcp from 10.20.10.0/24 to any port { 80, 443 }
# Block ALL access to internal networks
block in on vtnet3 from 10.20.10.0/24 to { 10.10.10.0/24, 10.30.10.0/24, 10.10.10.1, 10.30.10.1 }

Don't hardcode IPs. Use aliases instead.

# pfSense aliases (Diagnostics → Aliases)
TRUSTED_NET    = 10.10.10.0/24
SERVER_NET     = 10.30.10.0/24
IOT_NET        = 10.20.10.0/24
DNS_PORTS      = 53
NTP_PORTS      = 123
ADMIN_PORTS    = 22, 443, 8006

Then your rules reference aliases, not IPs. When you add a new server subnet, update the alias, not every rule.

Step 3: Cilium for Kubernetes Observability and Micro-Segmentation

Cilium Installation and kube-proxy Replacement

Deploy Cilium as your CNI on your K8s cluster running inside Proxmox VMs or LXC.

# Install Cilium via Helm
helm repo add cilium https://helm.cilium.io/
helm repo update

helm install cilium cilium/cilium \
  --namespace kube-system \
  --set kubeProxyReplacement=strict \
  --set hubble.enabled=true \
  --set hubble.relay.enabled=true \
  --set hubble.ui.enabled=true \
  --set operator.replicas=1

Running kubeProxyReplacement=strict means Cilium replaces iptables-based kube-proxy entirely with eBPF. The benefits are significant

Faster service routing. eBPF programs run in-kernel, no context switches to userspace.
Lower latency. Direct packet processing at the socket layer.
Consistent observability. Every connection goes through the same eBPF programs.
No iptables drift. One mechanism, not two.

Hubble for Seeing Every Connection

Hubble is Cilium's observability layer. It streams every network connection in real time.

# Port-forward Hubble Relay
kubectl port-forward -n kube-system svc/hubble-relay 4245:4245

# Watch all connections in real time
hubble observe --since 1m

# Filter by namespace
hubble observe --namespace production --since 5m

# Track DNS resolution failures (classic IoT misbehavior indicator)
hubble observe --type trace:to-endpoint:dns --verdict DROPPED

The Hubble UI gives you a visual service map. You'll see immediately if your Home Assistant container is phoning home to sketchy endpoints, or if your Nextcloud pod is trying to reach the Kubernetes API when it shouldn't. This surprised me the first time I spun it up, I caught a smart plug making DNS requests to a Chinese IP within ten minutes of enabling Hubble.

Network Policies for Defense in Depth

pfSense controls traffic between VLANs. Cilium NetworkPolicies control traffic inside your cluster. Both layers matter.

Default Deny All Ingress

# default-deny.yaml, apply to every namespace
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-ingress
  namespace: default
spec:
  podSelector: {}
  policyTypes:
    - Ingress

Allow Specific Service Communication

# nextcloud-policy.yaml, Nextcloud can reach its DB and Redis, nothing else
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: nextcloud-ingress
  namespace: home-services
spec:
  podSelector:
    matchLabels:
      app: nextcloud
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: nginx-ingress
      ports:
        - port: 8080
  egress:
    - to:
        - podSelector:
            matchLabels:
              app: postgres-nextcloud
      ports:
        - port: 5432
    - to:
        - podSelector:
            matchLabels:
              app: redis-nextcloud
      ports:
        - port: 6379
    - to: []  # Allow DNS
      ports:
        - port: 53
          protocol: UDP

CiliumNetworkPolicy for L7 Visibility

Standard Kubernetes NetworkPolicies are L3/L4. Cilium extends this to L7.

# cilium-l7-policy.yaml, restrict Nextcloud egress at HTTP level
apiVersion: cilium.io/v2
kind: CiliumNetworkPolicy
metadata:
  name: nextcloud-l7-egress
  namespace: home-services
spec:
  endpointSelector:
    matchLabels:
      app: nextcloud
  egress:
    - toFQDNs:
        - matchName: "updates.nextcloud.com"
        - matchName: "download.nextcloud.com"
      toPorts:
        - ports:
            - port: "443"
          rules:
            http:
              - method: GET
                path: "/.*"

Now your Nextcloud instance can only make outbound GET requests to specific domains. If an attacker compromises it, they can't exfiltrate data to arbitrary endpoints. The eBPF program in the kernel drops the connection before it reaches the wire.

Step 4: Observability Pipeline

Metrics, Dashboards, and Alerting

Cilium eBPF → Hubble → Prometheus → Grafana
     ↓
pfSense (netflow) → Prometheus → Grafana
     ↓
Proxmox (node metrics) → Prometheus → Grafana

These are the key dashboards to build

Inter-VLAN traffic. Who's talking to whom? Any IoT device hitting server subnets?
DNS queries per namespace. Spot DNS tunneling or C2 callbacks.
Connection drops per policy. Are your policies actually working?
pfSense rule hits. Which rules fire most? Tune your alias groups.
eBPF program latency. Should be sub-microsecond. If it spikes, you've got a problem.

Now set up your alerting rules.

# Prometheus alerts for your homelab security
groups:
  - name: homelab-security
    rules:
      - alert: IoTDeviceReachingServerNet
        expr: |
          hubble_flows_total{
            source_namespace="iot",
            destination_namespace="servers"
          } > 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "IoT device reaching server network"

      - alert: UnexpectedDNSQueries
        expr: |
          count(hubble_dns_queries_total) by (namespace, qname) 
          > 100
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Unusual DNS query volume from {{ $labels.namespace }}"

      - alert: CiliumPolicyDrop
        expr: |
          cilium_policy_verdict_total{verdict="dropped"} > 0
        for: 2m
        labels:
          severity: info
        annotations:
          summary: "Cilium policy dropping traffic, expected behavior"

Security Best Practices Checklist

Proxmox

[ ] Enable Proxmox firewall at datacenter level
[ ] Use separate physical NICs for WAN, LAN, management
[ ] Run LXC containers as unprivileged with AppArmor profiles
[ ] Enable 2FA on Proxmox web UI
[ ] Regular ZFS snapshots with automated send to offsite
[ ] Keep Proxmox updated, subscribe to enterprise repo or use no-subscription

pfSense

[ ] Default deny on all interfaces except LAN
[ ] Use aliases, not hardcoded IPs, in rules
[ ] Enable pfBlockerNG for ad/malware blocking at the gateway
[ ] Set up WireGuard VPN for remote access, don't expose services
[ ] Regular config backups (Automated via cron to offsite storage)
[ ] Disable WAN responses, no ping, no admin interface on WAN

Cilium/Kubernetes

[ ] Default deny all ingress NetworkPolicy in every namespace
[ ] Use CiliumNetworkPolicy for L7 egress restrictions
[ ] Enable Hubble for real-time observability
[ ] Run kubeProxyReplacement=strict, don't mix iptables and eBPF
[ ] Enable Cilium encryption (WireGuard) for inter-node traffic
[ ] Audit NetworkPolicies regularly, use kubectl get networkpolicies -A to review

General

[ ] All management interfaces behind VPN or local access only
[ ] SSH key-only authentication, disable password auth
[ ] Automated security updates (unattended-upgrades on Debian/Ubuntu hosts)
[ ] Centralized logging to a write-once destination
[ ] Document your network topology, future you will thank present you

What This Gets You

Threat	Mitigation
Compromised IoT device	Can't reach server VLAN (pfSense drops it)
Lateral movement in K8s	NetworkPolicy default deny + Cilium L7 rules
Data exfiltration from container	Cilium FQDN egress policy + DNS monitoring
Unauthorized remote access	WireGuard VPN, no exposed ports
Blind spots	Hubble service map + Prometheus alerts
Insider threat (rogue admin)	Separate management VLAN + audit logging

Cost Breakdown

Component	Hardware	Cost
Proxmox host	Refurbished Dell OptiPlex (i5, 32GB RAM, 2TB NVMe)	~$200
NICs	Intel X710-T2L (2.5GbE, SR-IOV capable)	~$80 each × 2
pfSense	VM on Proxmox (free CE edition)	$0
Cilium	Open source	$0
Switch	Used managed switch (VLAN-capable)	~$40
Total		~$400

That's enterprise-grade network segmentation for less than a single rack-mount firewall license.

Next Steps

Start with Proxmox, get your VMs running, assign NICs properly
Add pfSense, configure VLANs before you deploy services
Deploy K8s with Cilium, enable Hubble from day one
Layer in policies, default deny first, then add specific allows
Observe, watch Hubble for a week before you think you know your traffic patterns

The homelab that's invisible to its own admin is the homelab that gets owned. Build with observability from day one, and you'll catch problems when they're misconfigurations, not breaches.

CommsNet builds secure, observable infrastructure. More at wiki.commsnet.org

Tags: #homelab #proxmox #pfsense #cilium #ebpf #kubernetes #networking #security #selfhosted

This article is also published on:

Medium: Coming soon
Dev.to: Building a Secure Homelab with Proxmox VE, pfSense, and Cilium

Originally published at wiki.commsnet.org. Follow CommsNet for more homelab, networking, and self-hosting content.

Sponsor our work: GitHub Sponsors