Files

Kaloyan Danchev ec9659d0cb

ci/woodpecker/push/woodpecker Pipeline was successful

Details

Restructure docs: archive VLAN migration, update IPs to VLAN 10

Major documentation cleanup after VLAN migration completion:
- Archive 12 VLAN project docs to archive/vlan-migration/
- Archive 5 done WIP docs (VLAN proposals, AI stack, Fossorial, DNS backup)
- Create standing reference docs 08-DNS-ARCHITECTURE and 09-TAILSCALE-VPN
- Renumber docs to clean 01-09 sequence with merged CHANGELOG
- Update all active docs from stale 192.168.31.x to current VLAN 10 IPs
- Fix CSS1 (.10.9→.10.3) and ZX1 (.10.7→.10.4) IPs in hardware inventory
- Clean 06-VLAN-DEVICE-ASSIGNMENT: remove migration columns/sections, fix VLAN 25 subnet

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-06 12:45:16 +02:00

3.1 KiB

Raw Blame History

Fossorial Tunnel Stack (Pangolin + Gerbil)

Status: 💡 IDEA Priority: Low Depends On: Hardware upgrade (XTRM-N1 for resilience)

Overview

Self-hosted tunnel solution for exposing services without Cloudflare/VPS dependency.

Component	Purpose
Pangolin	Central controller/dashboard
Gerbil	WireGuard peer manager
Newt	Tunnel connector agent

Why Fossorial?

Current state uses Traefik + Cloudflare DNS for external access.

Fossorial would provide:

Independent tunneling (no Cloudflare dependency)
Self-healing WireGuard connections
Web-based tunnel management
Potential for MikroTik container fallback

Architecture

Internet (62.73.120.142)
         │
         ▼ UDP 51820
┌─────────────────────┐
│ Gerbil (WG Manager) │
│ :51820 WireGuard    │
│ :8080 API           │
└─────────┬───────────┘
          │
┌─────────▼───────────┐
│ Pangolin (Dashboard)│
│ :3000 Web UI        │
└─────────┬───────────┘
          │
┌─────────▼───────────┐
│ Newt (Connector)    │
│ Dials out to peers  │
└─────────────────────┘

Prerequisites

Port 51820/UDP forwarded on MikroTik
fossorial Docker network created
Secret key generated

Deployment Steps

1. Create Network

docker network create --driver bridge fossorial

2. Deploy Pangolin

docker run -d \
  --name pangolin \
  --network fossorial \
  -p 3000:3000 \
  -v /mnt/user/appdata/pangolin/data:/app/data \
  -e PANGOLIN_BASE_URL=https://pangolin.xtrm-lab.org \
  -e PANGOLIN_SECRET_KEY=$(openssl rand -hex 32) \
  fossoriumtech/pangolin:latest

3. Deploy Gerbil

docker run -d \
  --name gerbil \
  --network fossorial \
  --cap-add=NET_ADMIN \
  -p 51820:51820/udp \
  -p 8080:8080 \
  -v /mnt/user/appdata/gerbil:/app/data \
  -e GERBIL_PUBLIC_IP=62.73.120.142 \
  -e GERBIL_PUBLIC_PORT=51820 \
  fossoriumtech/gerbil:latest

4. Deploy Newt

docker run -d \
  --name newt \
  --network fossorial \
  -v /mnt/user/appdata/newt:/app/data \
  -e NEWT_PANGOLIN_URL=https://pangolin.xtrm-lab.org \
  -e NEWT_ENDPOINT=62.73.120.142:51820 \
  fossoriumtech/newt:latest

5. MikroTik NAT

/ip/firewall/nat add chain=dstnat \
    action=dst-nat to-addresses=192.168.31.2 to-ports=51820 \
    protocol=udp dst-port=51820 \
    comment="Fossorial WireGuard"

Current WireGuard (Not Affected)

Existing back-to-home-vpn uses port 59188, completely separate.

Decision Points

Is this needed? Tailscale + Traefik already provides external access
When to implement? After XTRM-N1 survival node for fallback option
Use case? If Cloudflare/Tailscale goes down

References

Original planning: archive/02-PHASE2-FOSSORIAL-STACK.md
GitHub: https://github.com/fossoriumtech

3.1 KiB Raw Blame History