ec9659d0cb
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
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>
138 lines
3.1 KiB
Markdown
138 lines
3.1 KiB
Markdown
# 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
|
|
```bash
|
|
docker network create --driver bridge fossorial
|
|
```
|
|
|
|
### 2. Deploy Pangolin
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```routeros
|
|
/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
|
|
|
|
1. **Is this needed?** Tailscale + Traefik already provides external access
|
|
2. **When to implement?** After XTRM-N1 survival node for fallback option
|
|
3. **Use case?** If Cloudflare/Tailscale goes down
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- Original planning: `archive/02-PHASE2-FOSSORIAL-STACK.md`
|
|
- GitHub: https://github.com/fossoriumtech
|