The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: add homelab config skills (VLAN segmentation, Pi-hole DNS, WireGuard VPN) (#1838)
Arsal Sajjad71ed7c58d459
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 89c87c7c3..71047464f 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -11,7 +11,7 @@{"name": "ecc","source": "./",- "description": "The most comprehensive Claude Code plugin — 60 agents, 225 skills, 75 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",+ "description": "The most comprehensive Claude Code plugin — 60 agents, 228 skills, 75 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning","version": "2.0.0-rc.1","author": {"name": "Affaan Mustafa",diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex aabcb2fa6..e98e81abd 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ecc","version": "2.0.0-rc.1",- "description": "Battle-tested Claude Code plugin for engineering teams — 60 agents, 225 skills, 75 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",+ "description": "Battle-tested Claude Code plugin for engineering teams — 60 agents, 228 skills, 75 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use","author": {"name": "Affaan Mustafa","url": "https://x.com/affaanmustafa"diff --git a/AGENTS.md b/AGENTS.mdindex 5d5229ca7..e34717bb6 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -1,6 +1,6 @@# Everything Claude Code (ECC) — Agent Instructions-This is a **production-ready AI coding plugin** providing 60 specialized agents, 225 skills, 75 commands, and automated hook workflows for software development.+This is a **production-ready AI coding plugin** providing 60 specialized agents, 228 skills, 75 commands, and automated hook workflows for software development.**Version:** 2.0.0-rc.1@@ -150,7 +150,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat```agents/ — 60 specialized subagents-skills/ — 225 workflow skills and domain knowledge+skills/ — 228 workflow skills and domain knowledgecommands/ — 75 slash commandshooks/ — Trigger-based automationsrules/ — Always-follow guidelines (common + per-language)diff --git a/README.md b/README.mdindex 6bfa448dc..ec2461fc7 100644--- a/README.md+++ b/README.md@@ -358,7 +358,7 @@ If you stacked methods, clean up in this order:/plugin list ecc@ecc```-**That's it!** You now have access to 60 agents, 225 skills, and 75 legacy command shims.+**That's it!** You now have access to 60 agents, 228 skills, and 75 legacy command shims.### Dashboard GUI@@ -1362,7 +1362,7 @@ The configuration is automatically detected from `.opencode/opencode.json`.|---------|-------------|----------|--------|| Agents | PASS: 60 agents | PASS: 12 agents | **Claude Code leads** || Commands | PASS: 75 commands | PASS: 35 commands | **Claude Code leads** |-| Skills | PASS: 225 skills | PASS: 37 skills | **Claude Code leads** |+| Skills | PASS: 228 skills | PASS: 37 skills | **Claude Code leads** || Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** || Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** || MCP Servers | PASS: 14 servers | PASS: Full | **Full parity** |@@ -1467,7 +1467,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e|---------|------------|------------|-----------|----------|| **Agents** | 60 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 || **Commands** | 75 | Shared | Instruction-based | 35 |-| **Skills** | 225 | Shared | 10 (native format) | 37 |+| **Skills** | 228 | Shared | 10 (native format) | 37 || **Hook Events** | 8 types | 15 types | None yet | 11 types || **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks || **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions |diff --git a/README.zh-CN.md b/README.zh-CN.mdindex c1775b4e5..19dfb2cf0 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -160,7 +160,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"/plugin list ecc@ecc```-**完成!** 你现在可以使用 60 个代理、225 个技能和 75 个命令。+**完成!** 你现在可以使用 60 个代理、228 个技能和 75 个命令。### multi-* 命令需要额外配置diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.mdindex 738abc7af..7ab620bab 100644--- a/docs/zh-CN/AGENTS.md+++ b/docs/zh-CN/AGENTS.md@@ -1,6 +1,6 @@# Everything Claude Code (ECC) — 智能体指令-这是一个**生产就绪的 AI 编码插件**,提供 60 个专业代理、225 项技能、75 条命令以及自动化钩子工作流,用于软件开发。+这是一个**生产就绪的 AI 编码插件**,提供 60 个专业代理、228 项技能、75 条命令以及自动化钩子工作流,用于软件开发。**版本:** 2.0.0-rc.1@@ -147,7 +147,7 @@```agents/ — 60 个专业子代理-skills/ — 225 个工作流技能和领域知识+skills/ — 228 个工作流技能和领域知识commands/ — 75 个斜杠命令hooks/ — 基于触发的自动化rules/ — 始终遵循的指导方针(通用 + 每种语言)diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.mdindex 15dfbf209..4794bef1f 100644--- a/docs/zh-CN/README.md+++ b/docs/zh-CN/README.md@@ -224,7 +224,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"/plugin list ecc@ecc```-**搞定!** 你现在可以使用 60 个智能体、225 项技能和 75 个命令了。+**搞定!** 你现在可以使用 60 个智能体、228 项技能和 75 个命令了。***@@ -1138,7 +1138,7 @@ opencode|---------|-------------|----------|--------|| 智能体 | PASS: 60 个 | PASS: 12 个 | **Claude Code 领先** || 命令 | PASS: 75 个 | PASS: 35 个 | **Claude Code 领先** |-| 技能 | PASS: 225 项 | PASS: 37 项 | **Claude Code 领先** |+| 技能 | PASS: 228 项 | PASS: 37 项 | **Claude Code 领先** || 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多!** || 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** || MCP 服务器 | PASS: 14 个 | PASS: 完整 | **完全对等** |@@ -1246,7 +1246,7 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以|---------|------------|------------|-----------|----------|| **智能体** | 60 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 || **命令** | 75 | 共享 | 基于指令 | 35 |-| **技能** | 225 | 共享 | 10 (原生格式) | 37 |+| **技能** | 228 | 共享 | 10 (原生格式) | 37 || **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 || **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 || **规则** | 34 (通用 + 语言) | 34 (YAML 前页) | 基于指令 | 13 条指令 |diff --git a/skills/homelab-pihole-dns/SKILL.md b/skills/homelab-pihole-dns/SKILL.mdnew file mode 100644index 000000000..0048749c3--- /dev/null+++ b/skills/homelab-pihole-dns/SKILL.md@@ -0,0 +1,274 @@+---+name: homelab-pihole-dns+description: Pi-hole installation, blocklist management, DNS-over-HTTPS setup, DHCP integration, local DNS records, and troubleshooting broken DNS resolution on a home network.+origin: community+---++# Homelab Pi-hole DNS++Pi-hole is a network-wide DNS ad blocker that runs on a Raspberry Pi or any Linux host.+Every device on your network gets ad and malware domain blocking automatically — no browser+extension needed.++## When to Use++- Installing Pi-hole on a Raspberry Pi or Linux host+- Configuring Pi-hole as the DNS server for a home network+- Adding or managing blocklists+- Setting up DNS-over-HTTPS (DoH) upstream resolvers+- Creating local DNS records (e.g. `nas.home.lan`, `pi.home.lan`)+- Troubleshooting devices that lose internet access after Pi-hole is installed+- Running Pi-hole alongside or instead of DHCP++## How Pi-hole Works++```+Normal flow (without Pi-hole):+ Device → requests ads.tracker.com → ISP DNS → real IP → ads load++With Pi-hole:+ Device → requests ads.tracker.com → Pi-hole DNS → blocked (returns 0.0.0.0) → no ad++All DNS queries go through Pi-hole first.+Pi-hole checks against blocklists.+Blocked domains return a null response — the ad/tracker never loads.+Allowed domains get forwarded to your upstream resolver (Cloudflare, Google, etc.).+```++## Installation++### Docker (Recommended)++Docker is the easiest way to install Pi-hole and makes updates and backups+straightforward.++```yaml+# docker-compose.yml+services:+ pihole:+ image: pihole/pihole:<pinned-release-tag>+ container_name: pihole+ ports:+ - "53:53/tcp"+ - "53:53/udp"+ - "80:80/tcp" # Web admin+ environment:+ TZ: "America/New_York"+ WEBPASSWORD: "${PIHOLE_WEBPASSWORD}" # set via .env file or secret+ PIHOLE_DNS_: "1.1.1.1;1.0.0.1"+ DNSMASQ_LISTENING: "all"+ volumes:+ - "./etc-pihole:/etc/pihole"+ - "./etc-dnsmasq.d:/etc/dnsmasq.d"+ restart: unless-stopped+ cap_add:+ - NET_ADMIN # only needed if Pi-hole will serve DHCP+```++Replace `<pinned-release-tag>` with a current Pi-hole release tag before deploying.+Avoid `latest` for long-lived DNS infrastructure so upgrades are deliberate and+reviewable.++Set `PIHOLE_WEBPASSWORD` in a `.env` file next to `docker-compose.yml`, chmod it to+`600`, and keep it out of git — do not put the password directly in the compose file.++Access web admin at: `http://<pi-ip>/admin`++### Bare-Metal Install (Raspberry Pi OS / Debian / Ubuntu)++Pi-hole requires a static IP before installing.++```bash+# Step 1: Assign a static IP (edit /etc/dhcpcd.conf on Pi OS)+sudo nano /etc/dhcpcd.conf+# Add at the bottom:+interface eth0+static ip_address=192.168.3.2/24+static routers=192.168.3.1+static domain_name_servers=192.168.3.1++# Step 2: Download and inspect the installer before running it.+# Prefer the package or installer path documented by Pi-hole for your OS/version.+curl -sSL https://install.pi-hole.net -o pi-hole-install.sh+less pi-hole-install.sh # review before proceeding++# Step 3: Run+bash pi-hole-install.sh++# Follow the interactive installer:+# 1. Select network interface (eth0 for wired — recommended)+# 2. Select upstream DNS (Cloudflare or leave default — can change later)+# 3. Confirm static IP+# 4. Install the web admin interface (recommended)+# 5. Note the admin password shown at the end+```++## Pointing Your Network at Pi-hole++```+# Method 1: Change DNS in your router DHCP settings (recommended)+ Router admin UI → DHCP Settings → DNS Server+ Primary DNS: 192.168.3.2 (Pi-hole IP)+ Secondary DNS: leave blank for strict blocking, or use a second Pi-hole.+ A public fallback such as 1.1.1.1 improves availability during+ rollout but can bypass blocking because clients may query it.++ All devices get Pi-hole as DNS automatically on next DHCP renewal.+ Force renewal: reconnect Wi-Fi or run 'sudo dhclient -r && sudo dhclient' on Linux++# Method 2: Per-device DNS (useful for testing before network-wide rollout)+ Windows: Control Panel → Network Adapter → IPv4 Properties → set DNS manually+ macOS: System Settings → Network → Details → DNS → set manually+ Linux: /etc/resolv.conf or NetworkManager++# Method 3: Pi-hole as DHCP server (replaces router DHCP)+ Pi-hole admin → Settings → DHCP → Enable+ Disable DHCP on your router first — two DHCP servers on the same network cause conflicts+ Advantage: hostname resolution works automatically (devices register their names)+```++## Blocklist Management++```+# Pi-hole admin → Adlists → Add new adlist++# Recommended blocklists:+ https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts+ # default — 200k+ domains++ https://blocklistproject.github.io/Lists/malware.txt+ # malware domains++ https://blocklistproject.github.io/Lists/tracking.txt+ # tracking/telemetry++# After adding a list:+ Tools → Update Gravity (downloads and compiles all blocklists)++# If a site is blocked that should not be (false positive):+ Pi-hole admin → Whitelist → Add domain+ Example: api.my-legitimate-service.com++# Check what is being blocked in real time:+ Dashboard → Query Log (live DNS query stream with block/allow status)+```++## DNS-over-HTTPS Upstream++DNS-over-HTTPS encrypts your DNS queries so your ISP cannot see what sites you resolve.++```bash+# Install cloudflared (Cloudflare's DoH proxy).+# Prefer Cloudflare's package repository for automatic signed package verification.+# If you download a binary directly, pin a release version and verify its checksum.+CLOUDFLARED_VERSION="<pinned-version>"+curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"+# Verify the checksum/signature from Cloudflare's release notes before installing.+sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared+sudo chmod +x /usr/local/bin/cloudflared++# Create cloudflared config+sudo mkdir -p /etc/cloudflared+sudo tee /etc/cloudflared/config.yml << EOF+proxy-dns: true+proxy-dns-port: 5053+proxy-dns-upstream:+ - https://1.1.1.1/dns-query+ - https://1.0.0.1/dns-query+EOF++# Create systemd service+sudo cloudflared service install+sudo systemctl start cloudflared+sudo systemctl enable cloudflared++# Now point Pi-hole at the local DoH proxy:+# Pi-hole admin → Settings → DNS → Custom upstream DNS+# Set to: 127.0.0.1#5053+# Uncheck all other upstream resolvers+```++## Local DNS Records++Make your services reachable by name (e.g. `nas.home.lan`, `grafana.home.lan`).++> **Domain name note:** `.home.lan` is widely used in homelabs and works in practice.+> The IETF-reserved suffix for local use is `.home.arpa` (RFC 8375) — use that to+> follow the standard. Avoid `.local` for Pi-hole DNS records as it conflicts with+> mDNS/Bonjour.++```+# Pi-hole admin → Local DNS → DNS Records++ Domain IP+ nas.home.lan 192.168.30.10+ pi.home.lan 192.168.30.2+ grafana.home.lan 192.168.30.3+ proxmox.home.lan 192.168.30.4++# From any device on your network:+ ping nas.home.lan → 192.168.30.10+ http://grafana.home.lan → your Grafana dashboard++# For subdomains, add a CNAME:+ Pi-hole admin → Local DNS → CNAME Records+ Domain: portainer.home.lan → Target: pi.home.lan+```++## Troubleshooting++```bash+# Pi-hole blocking something it should not+pihole -q example.com # Check if domain is blocked and which list+pihole -w example.com # Whitelist immediately++# DNS not resolving at all+pihole status # Check if pihole-FTL is running+dig @192.168.3.2 google.com # Test DNS directly against Pi-hole++# Restart Pi-hole DNS+pihole restartdns++# Check query logs for a specific device+pihole -t # Live tail of all queries+# Or filter by client in the web admin Query Log++# Pi-hole gravity update (refresh blocklists)+pihole -g+```++## Anti-Patterns++```+# BAD: Depending on one Pi-hole without a recovery path+# If Pi-hole crashes or the Pi loses power, DNS can stop working+# GOOD: Keep a documented router fallback for rollback during setup+# BETTER: Run two Pi-hole instances for redundancy; avoid public fallback DNS for strict blocking++# BAD: Installing Pi-hole without a static IP+# If the Pi gets a new DHCP IP, all devices lose DNS+# GOOD: Set static IP first, then install Pi-hole++# BAD: Enabling Pi-hole DHCP without disabling the router's DHCP first+# Two DHCP servers on the same network hand out conflicting IPs+# GOOD: Disable router DHCP, then enable Pi-hole DHCP++# BAD: Never updating gravity (blocklists)+# New ad and malware domains accumulate — stale lists miss them+# GOOD: Schedule weekly gravity update: pihole -g (or enable in Settings → API)+```++## Best Practices++- Give the Pi a static IP or DHCP reservation before installing Pi-hole+- Use Pi-hole as primary DNS; for redundancy, add a second Pi-hole instead of a+ public resolver if you need strict blocking+- Enable DoH (DNS-over-HTTPS) with cloudflared for encrypted upstream queries+- Set `home.lan` as your local domain and create DNS records for all your services+- Review the Query Log occasionally — blocked queries show you what devices are doing++## Related Skills++- homelab-network-setup+- homelab-vlan-segmentation+- homelab-wireguard-vpndiff --git a/skills/homelab-vlan-segmentation/SKILL.md b/skills/homelab-vlan-segmentation/SKILL.mdnew file mode 100644index 000000000..8741801dd--- /dev/null+++ b/skills/homelab-vlan-segmentation/SKILL.md@@ -0,0 +1,311 @@+---+name: homelab-vlan-segmentation+description: Segmenting home networks into VLANs for IoT, guest, trusted, and server traffic using UniFi, pfSense/OPNsense, and MikroTik — including switch trunk config, firewall rules, and wireless SSID mapping.+origin: community+---++# Homelab VLAN Segmentation++How to split a home network into isolated VLANs so IoT devices, guests, and your main+PCs cannot talk to each other. The most impactful security upgrade for a home network.++All firewall rules shown here add isolation between segments — they do not remove+existing protections. Apply changes in a maintenance window and verify connectivity+between segments after each step before moving on.++## When to Use++- Setting up VLANs on a home network for the first time+- Isolating IoT devices (smart bulbs, cameras, TVs) from trusted devices+- Creating a guest Wi-Fi network that cannot reach home devices+- Explaining how VLANs work to someone unfamiliar with the concept+- Configuring trunk ports, access ports, and SSID-to-VLAN mapping+- Troubleshooting inter-VLAN routing or firewall rule issues on pfSense/OPNsense/UniFi++## How It Works++```+Without VLANs — flat network:+ All devices on 192.168.1.0/24+ Smart TV (potential malware) → can reach your NAS, PCs, everything++With VLANs:+ VLAN 10 — Trusted 192.168.10.0/24 (PCs, phones, laptops)+ VLAN 20 — IoT 192.168.20.0/24 (smart TV, bulbs, cameras)+ VLAN 30 — Servers 192.168.30.0/24 (NAS, Pi, VMs)+ VLAN 40 — Guest 192.168.40.0/24 (visitor Wi-Fi)+ VLAN 99 — Management 192.168.99.0/24 (switch/AP web UIs)++ Smart TV → blocked from reaching 192.168.10.0/24 and 192.168.30.0/24+ Guests → internet only, cannot see any home devices+```++## VLAN Design Template++```+VLAN Name Subnet Gateway Purpose+10 trusted 192.168.10.0/24 192.168.10.1 PCs, phones, laptops+20 iot 192.168.20.0/24 192.168.20.1 Smart home devices+30 servers 192.168.30.0/24 192.168.30.1 NAS, Pi, self-hosted+40 guest 192.168.40.0/24 192.168.40.1 Visitor Wi-Fi+99 management 192.168.99.0/24 192.168.99.1 Network gear web UIs+```++## Examples++**Typical homelab with UniFi AP and managed switch:**++```+Scenario: 3-bedroom house, UniFi Dream Machine + UniFi 8-port switch + 2 APs++VLAN 10 — Trusted 192.168.10.0/24 MacBook, iPhones, iPad+VLAN 20 — IoT 192.168.20.0/24 Nest thermostat, Philips Hue, Ring doorbell, smart TVs+VLAN 30 — Servers 192.168.30.0/24 Synology NAS (192.168.30.10), Pi-hole (192.168.30.2)+VLAN 40 — Guest 192.168.40.0/24 Visitor Wi-Fi — internet only++SSID → VLAN mapping:+ "Home" → VLAN 10 (WPA2, strong password, trusted devices only)+ "IoT" → VLAN 20 (WPA2, separate password, printed on router for setup)+ "Guest" → VLAN 40 (WPA2, simple password you can share freely)++Switch port behavior:+ Port 1 → trunk to router (tagged VLANs 10,20,30,40,99)+ Port 2 → trunk to APs (tagged VLANs 10,20,40; AP handles per-SSID tagging)+ Port 3 → access VLAN 30 (NAS — untagged, no VLAN awareness needed)+ Port 4 → access VLAN 30 (Pi-hole — untagged)+ Port 5–8 → access VLAN 10 (wired workstations)++Firewall rules applied (all rules add isolation, none remove existing protections):+ IoT → Trusted: BLOCK+ IoT → Servers: BLOCK except 192.168.30.2:53 (Pi-hole DNS allowed)+ IoT → Internet: ALLOW+ Guest → Local networks: BLOCK+ Guest → Internet: ALLOW+ Trusted → everywhere: ALLOW+```++## UniFi Configuration++### Create Networks in UniFi Controller++```+Settings → Networks → Create New Network++For each VLAN:+ Name: IoT+ Purpose: Corporate (gives DHCP + routing)+ VLAN ID: 20+ Network: 192.168.20.0/24+ Gateway IP: 192.168.20.1+ DHCP: Enable+ DHCP Range: 192.168.20.100 – 192.168.20.254+```++### Map SSIDs to VLANs (UniFi)++```+Settings → WiFi → Create New WiFi++ Name: IoT-Network+ Password: <separate password>+ Network: IoT ← select your VLAN here+ # All devices connecting to this SSID land in VLAN 20++ Name: Guest+ Password: <guest password>+ Network: Guest+ Guest Policy: Enable ← isolates guests from each other too+```++### UniFi Firewall Rules (Traffic Rules)++```+Settings → Traffic & Security → Traffic Rules++# Block IoT from reaching Trusted VLAN+ Action: Block+ Category: Local Network+ Source: IoT (192.168.20.0/24)+ Destination: Trusted (192.168.10.0/24)++# Allow IoT to reach internet only+ Action: Allow+ Source: IoT+ Destination: Internet++# Block Guest from all local networks+ Action: Block+ Source: Guest+ Destination: Local Networks+```++## pfSense / OPNsense Configuration++### Create VLANs++```+Interfaces → Assignments → VLANs → Add++ Parent Interface: em1 (your LAN NIC)+ VLAN Tag: 20+ Description: IoT++# Repeat for each VLAN, then assign each VLAN to an interface:+Interfaces → Assignments → Add+ Select the VLAN you created → click Add+ Enable the interface, set IP to gateway address (192.168.20.1/24)+```++### DHCP for Each VLAN++```+Services → DHCP Server → Select your VLAN interface++ Enable DHCP+ Range: 192.168.20.100 to 192.168.20.254+ DNS Servers: 192.168.30.2 ← Pi-hole IP if you have one+```++### Firewall Rules (pfSense/OPNsense)++```+# Rules are processed top-to-bottom, first match wins.++# On the IoT interface (VLAN 20):+ Rule 1: Allow IoT → Pi-hole DNS ← MUST come before the RFC1918 block rule+ Protocol: UDP/TCP+ Source: IoT net+ Destination: 192.168.30.2 port 53+ Action: Allow++ Rule 2: Block IoT → RFC1918 (all private IP ranges)+ Protocol: any+ Source: IoT net+ Destination: RFC1918 (192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12)+ Action: Block++ Rule 3: Allow IoT → internet+ Protocol: any+ Source: IoT net+ Destination: any+ Action: Allow++# On the Trusted interface (VLAN 10):+ Allow all (trusted devices can reach everything)+ Source: Trusted net+ Destination: any+ Action: Allow++# Additional exceptions for IoT devices that need specific local services:+ Insert before Rule 2 (the RFC1918 block):+ Protocol: TCP+ Source: IoT net+ Destination: 192.168.30.x port 8123 ← Home Assistant+ Action: Allow+```++## MikroTik Configuration++```+# Step 1: Create a bridge with VLAN filtering enabled+/interface bridge+add name=bridge vlan-filtering=yes++# Step 2: Add physical ports to the bridge+# Trunk port to router/uplink (tagged for all VLANs)+/interface bridge port+add bridge=bridge interface=ether1 frame-types=admit-only-vlan-tagged++# Access port for trusted devices (untagged VLAN 10)+/interface bridge port+add bridge=bridge interface=ether2 pvid=10 frame-types=admit-only-untagged-and-priority-tagged++# Access port for IoT devices (untagged VLAN 20)+/interface bridge port+add bridge=bridge interface=ether3 pvid=20 frame-types=admit-only-untagged-and-priority-tagged++# Step 3: Define which VLANs are allowed on which ports+/interface bridge vlan+add bridge=bridge tagged=ether1 untagged=ether2 vlan-ids=10+add bridge=bridge tagged=ether1 untagged=ether3 vlan-ids=20++# Step 4: Create VLAN interfaces on the bridge (gateway IPs)+/interface vlan+add interface=bridge name=vlan10 vlan-id=10+add interface=bridge name=vlan20 vlan-id=20++# Step 5: Assign gateway IPs+/ip address+add interface=vlan10 address=192.168.10.1/24+add interface=vlan20 address=192.168.20.1/24++# Step 6: DHCP pools and servers+/ip pool+add name=pool-trusted ranges=192.168.10.100-192.168.10.254+add name=pool-iot ranges=192.168.20.100-192.168.20.254++/ip dhcp-server+add interface=vlan10 address-pool=pool-trusted name=dhcp-trusted+add interface=vlan20 address-pool=pool-iot name=dhcp-iot++/ip dhcp-server network+add address=192.168.10.0/24 gateway=192.168.10.1+add address=192.168.20.0/24 gateway=192.168.20.1++# Step 7: Firewall — block IoT from reaching trusted VLAN+/ip firewall filter+add chain=forward src-address=192.168.20.0/24 dst-address=192.168.10.0/24 \+ action=drop comment="Block IoT to Trusted"+```++## Switch Trunk vs Access Ports++```+# Trunk port: carries multiple VLANs (tagged) — connects switch-to-switch, switch-to-router, switch-to-AP+# Access port: carries one VLAN (untagged) — connects to end devices (PC, camera, NAS)++# A managed switch port connected to your router should be a trunk:+ Allowed VLANs: 10, 20, 30, 40, 99++# A port connecting to a PC should be an access port:+ VLAN: 10 (trusted)+ No tagging — the PC does not know or care about VLANs++# A port connecting to an AP must be a trunk:+ The AP tags traffic from each SSID with the right VLAN ID+ Allowed VLANs: 10, 20, 40 (whichever SSIDs the AP serves)+```++## Anti-Patterns++```+# BAD: Creating VLANs without adding firewall rules+# VLANs without firewall rules do not provide security — inter-VLAN routing is open by default+# GOOD: Add explicit block rules immediately after creating VLANs++# BAD: Putting the Pi-hole in the IoT VLAN+# IoT devices can reach it but trusted devices cannot (without extra rules)+# GOOD: Pi-hole in the Servers VLAN with a rule allowing all VLANs to reach port 53++# BAD: Native VLAN equals management VLAN+# Untagged traffic landing in your management VLAN enables VLAN hopping attacks+# GOOD: Use a dedicated unused VLAN as native (e.g. VLAN 999), keep management traffic tagged++# BAD: Same Wi-Fi password for IoT SSID and trusted SSID+# Anyone who learns the password can connect IoT devices to the wrong segment+```++## Best Practices++- Start with 4 VLANs: Trusted, IoT, Servers, Guest — add more as needed+- Put Pi-hole in the Servers VLAN (192.168.30.x)+- Add a firewall rule allowing DNS (port 53) from all VLANs to the Pi-hole IP — before any RFC1918 block rule+- Test isolation after every rule change: from the IoT VLAN, try to ping a trusted device — it should fail+- Use a management VLAN for switch and AP web UIs and restrict access to the Trusted VLAN only+- Document your VLAN design in a table (VLAN ID, name, subnet, purpose)++## Related Skills++- homelab-network-setup+- homelab-pihole-dns+- homelab-wireguard-vpndiff --git a/skills/homelab-wireguard-vpn/SKILL.md b/skills/homelab-wireguard-vpn/SKILL.mdnew file mode 100644index 000000000..65b58fb7e--- /dev/null+++ b/skills/homelab-wireguard-vpn/SKILL.md@@ -0,0 +1,305 @@+---+name: homelab-wireguard-vpn+description: WireGuard VPN server setup, peer configuration, key generation, split tunneling vs full tunnel routing, and remote access to a home network from mobile and laptop clients.+origin: community+---++# Homelab WireGuard VPN++WireGuard is a fast, modern VPN protocol. It is the right choice for remote access to a+home network — simpler to configure than OpenVPN and faster than most alternatives.++All configuration examples show common setups. Review each command — especially the+iptables forwarding rules and key file permissions — before applying them to your+system, and make changes in a maintenance window.++## When to Use++- Setting up WireGuard server on a Raspberry Pi, Linux host, pfSense, or router+- Generating WireGuard keypairs and writing peer config files+- Configuring remote access from a phone or laptop to a home network+- Explaining split tunneling (route only home traffic) vs full tunnel (route all traffic)+- Troubleshooting WireGuard connections that will not come up+- Automating peer configuration generation for multiple clients++## How WireGuard Works++```+Your phone (WireGuard client)+ │+ │ Encrypted UDP tunnel (port 51820)+ │+Your home router (WireGuard server — needs a public IP or DDNS)+ │+ Your home network (192.168.1.0/24, NAS, Pi, etc.)++Every device has a keypair (public + private key).+The server knows each client's public key.+The client knows the server's public key + endpoint (IP:port).+Traffic is encrypted end-to-end with no central server or certificate authority.+```++## Server Setup (Linux)++```bash+# Install WireGuard+sudo apt update && sudo apt install wireguard -y++# Generate server keypair — create files with private permissions from the start+sudo mkdir -p /etc/wireguard+sudo sh -c 'umask 077; wg genkey > /etc/wireguard/server_private.key'+sudo sh -c 'wg pubkey < /etc/wireguard/server_private.key > /etc/wireguard/server_public.key'++# Write server config — substitute the actual private key value+# Do not store private keys in version control or share them+sudo tee /etc/wireguard/wg0.conf << 'EOF'+[Interface]+Address = 10.8.0.1/24 # VPN subnet — server gets .1+ListenPort = 51820+PrivateKey = <paste_server_private_key_here>++# Scoped forwarding rules: allow VPN traffic in/out, not a blanket FORWARD ACCEPT+PostUp = iptables -A FORWARD -i wg0 -o eth0 -j ACCEPT+PostUp = iptables -A FORWARD -i eth0 -o wg0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT+PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE+PostDown = iptables -D FORWARD -i wg0 -o eth0 -j ACCEPT+PostDown = iptables -D FORWARD -i eth0 -o wg0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT+PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE++[Peer]+# Phone — replace with the actual phone public key+PublicKey = <phone_public_key>+AllowedIPs = 10.8.0.2/32++[Peer]+# Laptop — replace with the actual laptop public key+PublicKey = <laptop_public_key>+AllowedIPs = 10.8.0.3/32+EOF+sudo chmod 600 /etc/wireguard/wg0.conf++# Replace eth0 with your actual outbound interface name+# Check with: ip route show default++# Enable IP forwarding (required for routing traffic through the server)+echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-wireguard.conf+sudo sysctl --system++# Start WireGuard and enable on boot+sudo wg-quick up wg0+sudo systemctl enable wg-quick@wg0+```++## Client Configuration++```bash+# Generate a unique keypair for each client device+# Run on the client, or on the server and transfer the private key securely — never in plaintext+umask 077+wg genkey | tee phone_private.key | wg pubkey > phone_public.key++# Client config file (phone_wg0.conf):+[Interface]+PrivateKey = <phone_private_key>+Address = 10.8.0.2/32+DNS = 192.168.1.2 # Optional: use Pi-hole for DNS over the tunnel++[Peer]+PublicKey = <server_public_key>+Endpoint = your-home-ip.ddns.net:51820 # Your public IP or DDNS hostname+AllowedIPs = 192.168.1.0/24 # Split tunnel: only home network traffic+# AllowedIPs = 0.0.0.0/0, ::/0 # Full tunnel: all traffic through VPN++PersistentKeepalive = 25 # Keep NAT hole open (required for mobile clients)+```++## Split Tunnel vs Full Tunnel++```+# Split tunnel: AllowedIPs = 192.168.1.0/24+ Only traffic destined for your home network goes through the VPN.+ Internet traffic (YouTube, Spotify) goes directly — better performance on mobile.+ Best for: "I just want to reach my NAS and Pi from anywhere."++# Full tunnel: AllowedIPs = 0.0.0.0/0, ::/0+ ALL traffic goes through your home internet connection.+ Useful for: piggybacking home DNS/Pi-hole ad blocking.+ Downside: home upload speed becomes your bottleneck everywhere.++# Multi-subnet split tunnel (most common homelab use case):+ AllowedIPs = 192.168.10.0/24, 192.168.20.0/24, 192.168.30.0/24, 10.8.0.0/24+ Routes all your VLANs through the tunnel; internet stays direct.+```++## Key Generation and Peer Management++```python+import subprocess++def generate_keypair() -> tuple[str, str]:+ """Generate a WireGuard keypair. Returns (private_key, public_key)."""+ private = subprocess.check_output(["wg", "genkey"]).decode().strip()+ public = subprocess.run(+ ["wg", "pubkey"], input=private.encode(), capture_output=True+ ).stdout.decode().strip()+ return private, public++def generate_preshared_key() -> str:+ return subprocess.check_output(["wg", "genpsk"]).decode().strip()++def build_client_config(+ client_private_key: str,+ client_vpn_ip: str, # e.g. "10.8.0.3"+ server_public_key: str,+ server_endpoint: str, # e.g. "home.example.com:51820"+ allowed_ips: str = "192.168.1.0/24",+ dns: str = "",+) -> str:+ dns_line = f"DNS = {dns}\n" if dns else ""+ return f"""[Interface]+PrivateKey = {client_private_key}+Address = {client_vpn_ip}/32+{dns_line}+[Peer]+PublicKey = {server_public_key}+Endpoint = {server_endpoint}+AllowedIPs = {allowed_ips}+PersistentKeepalive = 25+"""++def build_server_peer_block(+ client_public_key: str,+ client_vpn_ip: str,+ comment: str = "",+) -> str:+ comment_line = f"# {comment}\n" if comment else ""+ return f"""+{comment_line}[Peer]+PublicKey = {client_public_key}+AllowedIPs = {client_vpn_ip}/32+"""+```++Keep private keys out of source control. If you use this script, write key material+to files with mode 600 and never log or print it.++## pfSense / OPNsense WireGuard++```+# pfSense: VPN → WireGuard → Add Tunnel+ Interface Keys: Generate (creates keypair automatically)+ Listen Port: 51820+ Interface Address: 10.8.0.1/24++# Add Peer (one per client):+ Public Key: <client public key>+ Allowed IPs: 10.8.0.2/32++# Assign the WireGuard interface:+ Interfaces → Assignments → Add (select wg0)+ Enable interface, no IP needed (it is set in the tunnel config)++# Firewall rules:+ WAN → Allow UDP port 51820 inbound (so clients can reach the server)+ WireGuard interface → Allow traffic to LAN networks you want reachable+```++## DDNS (Dynamic DNS) for Home Servers++Most home internet connections have a dynamic IP. Use DDNS so your VPN endpoint+stays reachable after an IP change.++```bash+# Option 1: Cloudflare DDNS — store credentials in a secrets file, not inline+# docker-compose entry using an env file:+ ddns-updater:+ image: qmcgaw/ddns-updater+ env_file: ./ddns.env # store zone_id and token here, not in compose+ restart: unless-stopped++# ddns.env (chmod 600, not committed to git):+# SETTINGS_CLOUDFLARE_ZONE_ID=your_zone_id+# SETTINGS_CLOUDFLARE_TOKEN=your_api_token++# Option 2: DuckDNS (free, simple)+ Sign up at duckdns.org → get a token and subdomain (myhome.duckdns.org)+ Store token in /etc/ddns.env (mode 600), then use a small root-owned script:++ # /usr/local/bin/update-duckdns+ #!/bin/sh+ set -eu+ . /etc/ddns.env+ curl --fail --silent --show-error --max-time 10 \+ --get "https://www.duckdns.org/update" \+ --data-urlencode "domains=myhome" \+ --data-urlencode "token=${DUCKDNS_TOKEN}" \+ --data-urlencode "ip="++ # Cron job:+ */5 * * * * /usr/local/bin/update-duckdns >/dev/null 2>&1+```++## Troubleshooting++```bash+# Check WireGuard status and last handshake+sudo wg show++# If "latest handshake" is never or very old, the tunnel is not connected.+# Check:+# 1. Is UDP port 51820 open on the router/firewall?+sudo ufw status # or check pfSense/UniFi firewall rules++# 2. Is the server public key in the client config correct?+sudo wg show wg0 public-key # Compare to what is in the client config++# 3. Is IP forwarding enabled on the server?+cat /proc/sys/net/ipv4/ip_forward # Should be 1++# 4. Does the client AllowedIPs cover the IP you are trying to reach?+# If AllowedIPs = 192.168.1.0/24 and you are trying to reach 192.168.3.5, it will not route.++# Check kernel logs for WireGuard errors+dmesg | grep wireguard++# Restart WireGuard+sudo wg-quick down wg0 && sudo wg-quick up wg0+```++## Anti-Patterns++```+# BAD: Storing private keys in version control or sharing them+# Private keys are equivalent to passwords — never commit them to git++# BAD: Using AllowedIPs = 0.0.0.0/0 on mobile without considering the impact+# Full tunnel routes all mobile traffic through your home upload — usually slow++# BAD: Not setting PersistentKeepalive on mobile clients+# Mobile clients behind NAT drop idle tunnels without it++# BAD: Opening port 51820 in the firewall but forgetting IP forwarding on the server+# Tunnel connects but no traffic routes — confusing to debug++# BAD: Sharing a keypair across multiple client devices+# Each device must have its own unique keypair — shared keys break the security model++# BAD: Using a broad "FORWARD ACCEPT" iptables rule+# Scope forwarding rules to the wg0 interface and direction only+```++## Best Practices++- Generate a unique keypair per client device — never reuse keys+- Use split tunneling (`AllowedIPs = <home subnets>`) for mobile+- Set `PersistentKeepalive = 25` on all mobile clients+- Use DDNS if your ISP assigns a dynamic IP; store credentials in env files, not inline+- Use scoped iptables forwarding rules (inbound on wg0 only) rather than a blanket FORWARD ACCEPT+- Add Pi-hole's IP as `DNS =` in client configs to get ad blocking over the VPN+- Rotate the server keypair periodically and update all client configs++## Related Skills++- homelab-network-setup+- homelab-vlan-segmentation+- homelab-pihole-dns