@heytherevibin/skillforge 0.2.1

package/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-vpn

package/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-vpn