Initial commit: cleaned project structure
- Consolidated documentation from Ralph Loop iterations - Archived 20+ outdated/superseded files to .archive/ - Kept essential docs: OIDC integration, mobile setup, quick start - Added operational scripts for health monitoring and backup - Research artifacts preserved in .tasks/artifacts/ Current state: - 3 VPS sites (fry, proton, photon) ONLINE in Pangolin - brn-home site pending for local services (Jellyfin, etc.) - Mobile access configuration pending Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
935
.tasks/artifacts/pangolin-research.md
Normal file
935
.tasks/artifacts/pangolin-research.md
Normal file
@@ -0,0 +1,935 @@
|
||||
# Pangolin Self-Hosting Research
|
||||
|
||||
**Research Date:** 2026-01-20
|
||||
**Purpose:** RESEARCH-001 - Comprehensive documentation for self-hosting Pangolin control plane
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Pangolin is an open-source, identity-based remote access platform built on WireGuard. It functions as a self-hosted tunneled reverse proxy with identity-aware access control, providing a secure alternative to Cloudflare Tunnels and similar managed services. Pangolin combines two primary use cases: tunneled reverse proxy for web applications and VPN-style access for private network resources, all managed through a centralized control plane.
|
||||
|
||||
**Key Architecture Components:**
|
||||
- **Pangolin Server (Control Plane)**: Centralized dashboard and management plane hosted on a VPS
|
||||
- **Newt (Site/Client Connector)**: Tunnel client installed on private networks to connect backend services
|
||||
- **WireGuard Tunnels**: Encrypted tunneling protocol for secure communication
|
||||
- **Traefik**: Underlying reverse proxy technology
|
||||
- **Identity Providers**: OIDC/OAuth2 integration for authentication
|
||||
|
||||
---
|
||||
|
||||
## 1. Installation Methods for Self-Hosting Pangolin Control Plane
|
||||
|
||||
### 1.1 Quick Install (Recommended for Most Users)
|
||||
|
||||
**Official Installer Script:**
|
||||
The quickest method uses Pangolin's automated installer script that handles all dependencies and configuration.
|
||||
|
||||
**Prerequisites:**
|
||||
- Linux server (Ubuntu 22.04/24.04 or Debian 11/12 recommended)
|
||||
- Root or sudo access
|
||||
- Public IPv4 address
|
||||
- Domain name with DNS configured
|
||||
- Email address for Let's Encrypt SSL certificates
|
||||
- Open firewall ports:
|
||||
- TCP 80 (HTTP & Let's Encrypt validation)
|
||||
- TCP 443 (HTTPS)
|
||||
- UDP 51820 (WireGuard tunnels)
|
||||
|
||||
**Installation Command:**
|
||||
```bash
|
||||
curl -fsSL https://get.pangolin.net | sudo bash
|
||||
```
|
||||
|
||||
The installer will:
|
||||
1. Install required dependencies (Docker, Docker Compose, WireGuard kernel module)
|
||||
2. Generate configuration files
|
||||
3. Set up Traefik reverse proxy
|
||||
4. Configure SSL certificates via Let's Encrypt
|
||||
5. Create initial admin account
|
||||
6. Start all services
|
||||
|
||||
**Post-Installation:**
|
||||
- Access dashboard at `https://your-domain.com`
|
||||
- Log in with admin credentials sent to provided email
|
||||
- Complete organization setup
|
||||
|
||||
### 1.2 Manual Docker Compose Installation
|
||||
|
||||
For users requiring full control over configuration, manual Docker Compose deployment is available.
|
||||
|
||||
**File Structure:**
|
||||
```
|
||||
pangolin/
|
||||
├── docker-compose.yml
|
||||
├── config/
|
||||
│ ├── pangolin.yml # Pangolin configuration
|
||||
│ ├── traefik.yml # Traefik static configuration
|
||||
│ └── traefik-dynamic.yml # Traefik dynamic configuration
|
||||
├── data/
|
||||
│ ├── pangolin/ # Application data
|
||||
│ ├── traefik/ # Traefik certificates
|
||||
│ └── postgres/ # Database (if using PostgreSQL)
|
||||
└── logs/
|
||||
```
|
||||
|
||||
**Docker Compose Configuration:**
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
pangolin:
|
||||
image: fosrl/pangolin:latest
|
||||
container_name: pangolin
|
||||
restart: unless-stopped
|
||||
cap_add:
|
||||
- NET_ADMIN
|
||||
sysctls:
|
||||
- net.ipv4.conf.all.src_valid_mark=1
|
||||
- net.ipv4.ip_forward=1
|
||||
- net.ipv6.conf.all.forwarding=1
|
||||
volumes:
|
||||
- ./config/pangolin.yml:/app/config.yml:ro
|
||||
- ./data/pangolin:/app/data
|
||||
- /dev/net/tun:/dev/net/tun
|
||||
environment:
|
||||
- CONFIG_FILE=/app/config.yml
|
||||
ports:
|
||||
- "51820:51820/udp"
|
||||
networks:
|
||||
- pangolin
|
||||
|
||||
traefik:
|
||||
image: traefik:latest
|
||||
container_name: traefik
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- ./config/traefik.yml:/etc/traefik/traefik.yml:ro
|
||||
- ./config/traefik-dynamic.yml:/etc/traefik/dynamic.yml:ro
|
||||
- ./data/traefik:/letsencrypt
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
networks:
|
||||
- pangolin
|
||||
|
||||
postgres:
|
||||
image: postgres:15-alpine
|
||||
container_name: pangolin-db
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- POSTGRES_DB=pangolin
|
||||
- POSTGRES_USER=pangolin
|
||||
- POSTGRES_PASSWORD=<secure_password>
|
||||
volumes:
|
||||
- ./data/postgres:/var/lib/postgresql/data
|
||||
networks:
|
||||
- pangolin
|
||||
|
||||
networks:
|
||||
pangolin:
|
||||
driver: bridge
|
||||
```
|
||||
|
||||
**Starting the Stack:**
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 1.3 Alternative Installation Methods
|
||||
|
||||
**Unraid Deployment:**
|
||||
- Community applications available in Unraid App Store
|
||||
- Template-based deployment with GUI configuration
|
||||
- Integration with Unraid Docker management
|
||||
|
||||
**Kubernetes Deployment:**
|
||||
- Helm charts available for production deployments
|
||||
- Supports horizontal scaling of control plane
|
||||
- Advanced orchestration for enterprise use cases
|
||||
|
||||
---
|
||||
|
||||
## 2. OIDC Integration Configuration
|
||||
|
||||
Pangolin supports external identity providers via OAuth2/OIDC for Single Sign-On (SSO), enabling centralized authentication for both the Pangolin dashboard and applications behind the proxy.
|
||||
|
||||
### 2.1 Supported Identity Providers
|
||||
|
||||
- **Google Workspace** - Native integration
|
||||
- **Microsoft Entra ID (Azure AD)** - Native integration
|
||||
- **Generic OAuth2/OIDC** - Any compliant provider
|
||||
- **Authelia** - Tested with v4.39.15+
|
||||
- **Authentik** - Community-supported integration
|
||||
- **Zitadel** - Native support
|
||||
- **Pocket ID** - Native support
|
||||
|
||||
### 2.2 OIDC Provider Configuration
|
||||
|
||||
**Step 1: Create OAuth2/OIDC Application in Identity Provider**
|
||||
|
||||
In your IdP (e.g., Authentik, Authelia, Google), create a new OAuth2/OIDC application with the following settings:
|
||||
|
||||
**Redirect URIs (Critical):**
|
||||
```
|
||||
https://<pangolin-domain>/api/v1/auth/callback
|
||||
https://<pangolin-domain>/api/v1/auth/callback/google # If using Google
|
||||
https://<pangolin-domain>/api/v1/auth/callback/microsoft # If using Microsoft
|
||||
```
|
||||
|
||||
For custom authentication domains:
|
||||
```
|
||||
https://auth.<your-company>.com/api/v1/auth/callback
|
||||
```
|
||||
|
||||
**Required Scopes:**
|
||||
- `openid` (required)
|
||||
- `profile` (recommended)
|
||||
- `email` (recommended)
|
||||
- `groups` (optional, for role-based access)
|
||||
|
||||
**Client Configuration:**
|
||||
- **Client Type:** Confidential
|
||||
- **Grant Type:** Authorization Code
|
||||
- **PKCE:** Enabled (recommended)
|
||||
- **Token Endpoint Auth Method:** client_secret_post or client_secret_basic
|
||||
|
||||
**Step 2: Configure Pangolin Identity Provider**
|
||||
|
||||
In Pangolin Dashboard:
|
||||
|
||||
1. Navigate to **Settings** → **Identity Providers** → **Add Identity Provider**
|
||||
2. Select provider type:
|
||||
- **Google** for Google Workspace
|
||||
- **Azure Entra ID** for Microsoft
|
||||
- **Generic OAuth2/OIDC** for other providers
|
||||
|
||||
3. Enter configuration details:
|
||||
|
||||
**For Generic OAuth2/OIDC:**
|
||||
```yaml
|
||||
Provider Name: Your IdP Name
|
||||
Provider Type: OAuth2/OIDC
|
||||
|
||||
# Discovery URL (auto-populates endpoints)
|
||||
OIDC Discovery URL: https://your-idp.com/.well-known/openid-configuration
|
||||
|
||||
# Manual configuration (if discovery not available)
|
||||
Authorization Endpoint: https://your-idp.com/oauth/authorize
|
||||
Token Endpoint: https://your-idp.com/oauth/token
|
||||
Userinfo Endpoint: https://your-idp.com/oauth/userinfo
|
||||
JWKS URI: https://your-idp.com/oauth/jwks
|
||||
|
||||
# Client credentials
|
||||
Client ID: <from_your_idp>
|
||||
Client Secret: <from_your_idp>
|
||||
|
||||
# Scopes
|
||||
Scopes: openid profile email groups
|
||||
|
||||
# User Mapping
|
||||
Username Claim: preferred_username
|
||||
Email Claim: email
|
||||
Display Name Claim: name
|
||||
Groups Claim: groups (optional)
|
||||
```
|
||||
|
||||
**For Google Workspace:**
|
||||
```yaml
|
||||
Provider Type: Google
|
||||
Client ID: <google_client_id>
|
||||
Client Secret: <google_client_secret>
|
||||
Hosted Domain: your-domain.com (optional, restricts to specific domain)
|
||||
```
|
||||
|
||||
**For Microsoft Entra ID:**
|
||||
```yaml
|
||||
Provider Type: Azure Entra ID
|
||||
Client ID: <azure_client_id>
|
||||
Client Secret: <azure_client_secret>
|
||||
Tenant ID: <azure_tenant_id>
|
||||
```
|
||||
|
||||
### 2.3 Auto-Provisioning Users
|
||||
|
||||
Pangolin supports automatic user provisioning from IdP:
|
||||
|
||||
**Configuration Options:**
|
||||
- **Auto-provision on first login:** Create user accounts automatically when users authenticate
|
||||
- **Group mapping:** Map IdP groups to Pangolin roles/organizations
|
||||
- **Just-in-Time (JIT) provisioning:** Update user attributes on each login
|
||||
|
||||
**Example Configuration:**
|
||||
```yaml
|
||||
auto_provisioning:
|
||||
enabled: true
|
||||
default_role: user
|
||||
group_mapping:
|
||||
- idp_group: "admin"
|
||||
pangolin_role: "admin"
|
||||
- idp_group: "developers"
|
||||
pangolin_role: "developer"
|
||||
```
|
||||
|
||||
### 2.4 Custom Authentication Domains
|
||||
|
||||
For branded authentication experiences:
|
||||
|
||||
1. Configure custom domain in Pangolin settings
|
||||
2. Set authentication domain: `auth.yourcompany.com`
|
||||
3. Update DNS records to point to Pangolin server
|
||||
4. Update redirect URIs in IdP configuration
|
||||
|
||||
---
|
||||
|
||||
## 3. Site Configuration (Defining Backend Services)
|
||||
|
||||
Sites in Pangolin represent network locations where backend services run. The Newt client connects these sites to the Pangolin control plane via WireGuard tunnels.
|
||||
|
||||
### 3.1 Understanding Sites vs Resources
|
||||
|
||||
**Sites:**
|
||||
- Physical or virtual network locations (e.g., home lab, office network, VPS)
|
||||
- Run the Newt client to establish WireGuard tunnels
|
||||
- Can host multiple resources/services
|
||||
- Types:
|
||||
- **Newt Sites:** Traditional tunnel-based sites for private networks
|
||||
- **Remote Nodes:** Exit nodes for client VPN access
|
||||
|
||||
**Resources:**
|
||||
- Individual services/applications exposed through Pangolin
|
||||
- Defined within sites
|
||||
- Types:
|
||||
- **Public Resources (HTTPS):** Web applications accessible via public URLs
|
||||
- **Private Resources:** TCP/UDP services for VPN-style access
|
||||
|
||||
### 3.2 Creating a Site
|
||||
|
||||
**Via Dashboard:**
|
||||
|
||||
1. Navigate to **Sites** → **Add Site**
|
||||
2. Configure site settings:
|
||||
|
||||
```yaml
|
||||
Site Name: Home Lab
|
||||
Description: Private home network services
|
||||
Site Type: Newt Site
|
||||
|
||||
# Tunnel Configuration
|
||||
WireGuard IP Range: 10.0.1.0/24 (auto-assigned)
|
||||
Listen Port: 51820 (default)
|
||||
|
||||
# Site Location (optional)
|
||||
Location: Home Network
|
||||
Tags: homelab, production
|
||||
```
|
||||
|
||||
3. Copy the generated installation command with credentials
|
||||
|
||||
**Installation Command Format:**
|
||||
```bash
|
||||
newt --id <site_id> --key <site_key> --endpoint <pangolin_server>:51820
|
||||
```
|
||||
|
||||
### 3.3 Defining Resources (Backend Services)
|
||||
|
||||
**HTTPS Resources (Public Web Applications):**
|
||||
|
||||
1. Navigate to **Resources** → **Add Resource**
|
||||
2. Select resource type: **HTTPS Resource**
|
||||
|
||||
```yaml
|
||||
Resource Name: Internal Wiki
|
||||
Public URL: wiki.yourdomain.com
|
||||
|
||||
# Backend Configuration
|
||||
Site: Home Lab
|
||||
Backend Type: HTTP
|
||||
Backend Address: 192.168.1.100:8080
|
||||
Backend Protocol: http
|
||||
|
||||
# Health Checks
|
||||
Health Check: Enabled
|
||||
Health Check Path: /health
|
||||
Health Check Interval: 30s
|
||||
|
||||
# Access Control
|
||||
Access Level: Authenticated Users Only
|
||||
Allowed Groups: developers, admins
|
||||
|
||||
# Additional Settings
|
||||
Enable WebSocket: Yes (for real-time apps)
|
||||
Custom Headers: X-Forwarded-Proto: https
|
||||
```
|
||||
|
||||
**Private Resources (TCP/UDP Services):**
|
||||
|
||||
For services accessed via Pangolin client VPN:
|
||||
|
||||
```yaml
|
||||
Resource Name: SSH Server
|
||||
Resource Type: TCP
|
||||
|
||||
# Backend Configuration
|
||||
Site: Home Lab
|
||||
Backend Address: 192.168.1.50:22
|
||||
Protocol: TCP
|
||||
|
||||
# Access Control
|
||||
Access Level: Specific Users
|
||||
Allowed Users: admin@company.com, ops@company.com
|
||||
```
|
||||
|
||||
### 3.4 Advanced Site Configuration
|
||||
|
||||
**Environment Variables (for Newt):**
|
||||
```bash
|
||||
# Custom configuration
|
||||
NEWT_CONFIG_FILE=/etc/newt/config.yml
|
||||
NEWT_LOG_LEVEL=info
|
||||
NEWT_RECONNECT_INTERVAL=10s
|
||||
```
|
||||
|
||||
**Configuration File (`/etc/newt/config.yml`):**
|
||||
```yaml
|
||||
server:
|
||||
endpoint: pangolin.yourdomain.com:51820
|
||||
id: <site_id>
|
||||
key: <site_key>
|
||||
|
||||
tunnel:
|
||||
mtu: 1420
|
||||
keepalive: 25
|
||||
persistent_keepalive: true
|
||||
|
||||
logging:
|
||||
level: info
|
||||
format: json
|
||||
output: /var/log/newt/newt.log
|
||||
|
||||
health:
|
||||
enable: true
|
||||
interval: 30s
|
||||
```
|
||||
|
||||
### 3.5 DNS Configuration for Resources
|
||||
|
||||
**For HTTPS Resources:**
|
||||
|
||||
Create DNS A/CNAME records pointing to Pangolin server:
|
||||
|
||||
```
|
||||
wiki.yourdomain.com A <pangolin_server_ip>
|
||||
app1.yourdomain.com A <pangolin_server_ip>
|
||||
app2.yourdomain.com A <pangolin_server_ip>
|
||||
```
|
||||
|
||||
**Wildcard Domain (Advanced):**
|
||||
```
|
||||
*.yourdomain.com A <pangolin_server_ip>
|
||||
```
|
||||
|
||||
Configure wildcard domain in Pangolin settings to automatically route all subdomains.
|
||||
|
||||
---
|
||||
|
||||
## 4. Client Deployment (Newt Client for VPS/Mobile)
|
||||
|
||||
The Newt client serves dual purposes:
|
||||
1. **Site Connector:** Install on private networks to expose backend services
|
||||
2. **VPN Client:** Install on user devices for accessing private resources
|
||||
|
||||
### 4.1 Newt Site Connector Deployment
|
||||
|
||||
**For VPS/Server Sites:**
|
||||
|
||||
**Installation Methods:**
|
||||
|
||||
**A. Binary Installation (Linux):**
|
||||
```bash
|
||||
# Download latest release
|
||||
curl -fsSL https://get.pangolin.net/newt | sudo bash
|
||||
|
||||
# Or manual installation
|
||||
wget https://github.com/fosrl/newt/releases/latest/download/newt-linux-amd64
|
||||
chmod +x newt-linux-amd64
|
||||
sudo mv newt-linux-amd64 /usr/local/bin/newt
|
||||
|
||||
# Run with credentials from Pangolin dashboard
|
||||
newt --id <site_id> --key <site_key> --endpoint <pangolin_server>:51820
|
||||
```
|
||||
|
||||
**B. Docker Deployment (Recommended):**
|
||||
|
||||
Create `docker-compose.yml` for Newt site:
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
newt:
|
||||
image: fosrl/newt:latest
|
||||
container_name: newt-site
|
||||
restart: unless-stopped
|
||||
cap_add:
|
||||
- NET_ADMIN
|
||||
sysctls:
|
||||
- net.ipv4.conf.all.src_valid_mark=1
|
||||
devices:
|
||||
- /dev/net/tun
|
||||
environment:
|
||||
- NEWT_SERVER_ENDPOINT=pangolin.yourdomain.com:51820
|
||||
- NEWT_SITE_ID=<site_id>
|
||||
- NEWT_SITE_KEY=<site_key>
|
||||
volumes:
|
||||
- ./config:/etc/newt
|
||||
network_mode: host # Required for proper networking
|
||||
```
|
||||
|
||||
**C. Systemd Service (Production):**
|
||||
|
||||
Create `/etc/systemd/system/newt.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Pangolin Newt Site Connector
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=root
|
||||
ExecStart=/usr/local/bin/newt \
|
||||
--id <site_id> \
|
||||
--key <site_key> \
|
||||
--endpoint pangolin.yourdomain.com:51820 \
|
||||
--config /etc/newt/config.yml
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Enable and start:
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable newt
|
||||
sudo systemctl start newt
|
||||
sudo systemctl status newt
|
||||
```
|
||||
|
||||
**D. Kubernetes Deployment:**
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: DaemonSet
|
||||
metadata:
|
||||
name: newt-site
|
||||
namespace: pangolin
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: newt-site
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: newt-site
|
||||
spec:
|
||||
hostNetwork: true
|
||||
containers:
|
||||
- name: newt
|
||||
image: fosrl/newt:latest
|
||||
securityContext:
|
||||
capabilities:
|
||||
add:
|
||||
- NET_ADMIN
|
||||
env:
|
||||
- name: NEWT_SERVER_ENDPOINT
|
||||
value: "pangolin.yourdomain.com:51820"
|
||||
- name: NEWT_SITE_ID
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: newt-credentials
|
||||
key: site-id
|
||||
- name: NEWT_SITE_KEY
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: newt-credentials
|
||||
key: site-key
|
||||
```
|
||||
|
||||
### 4.2 Newt VPN Client Deployment
|
||||
|
||||
**For End-User Devices (Accessing Private Resources):**
|
||||
|
||||
**A. Desktop Clients (Windows/Mac/Linux):**
|
||||
|
||||
Download from Pangolin dashboard or releases page:
|
||||
- Windows: `newt-windows-amd64.exe`
|
||||
- macOS: `newt-darwin-amd64` (Intel) or `newt-darwin-arm64` (Apple Silicon)
|
||||
- Linux: `newt-linux-amd64`
|
||||
|
||||
**Installation Steps:**
|
||||
|
||||
1. Create client in Pangolin dashboard:
|
||||
- Navigate to **Clients** → **Add Client**
|
||||
- Configure client settings:
|
||||
```yaml
|
||||
Client Name: John's Laptop
|
||||
Client Type: VPN Client
|
||||
Allowed Resources: SSH Server, Database Server
|
||||
User: john@company.com
|
||||
```
|
||||
|
||||
2. Copy generated credentials
|
||||
|
||||
3. Run Newt client:
|
||||
```bash
|
||||
newt --mode client \
|
||||
--id <client_id> \
|
||||
--key <client_key> \
|
||||
--endpoint pangolin.yourdomain.com:51820
|
||||
```
|
||||
|
||||
**B. Mobile Clients (iOS/Android):**
|
||||
|
||||
Currently, mobile clients use standard WireGuard configuration:
|
||||
|
||||
1. Generate WireGuard config in Pangolin dashboard
|
||||
2. Export configuration as QR code or config file
|
||||
3. Import into WireGuard mobile app:
|
||||
- iOS: WireGuard from App Store
|
||||
- Android: WireGuard from Google Play
|
||||
|
||||
**Example WireGuard Config:**
|
||||
```ini
|
||||
[Interface]
|
||||
PrivateKey = <client_private_key>
|
||||
Address = 10.0.2.5/24
|
||||
DNS = 1.1.1.1
|
||||
|
||||
[Peer]
|
||||
PublicKey = <pangolin_server_public_key>
|
||||
Endpoint = pangolin.yourdomain.com:51820
|
||||
AllowedIPs = 10.0.0.0/16, 192.168.1.0/24
|
||||
PersistentKeepalive = 25
|
||||
```
|
||||
|
||||
**C. Configuration Management:**
|
||||
|
||||
**Client Configuration File (`config.yml`):**
|
||||
```yaml
|
||||
client:
|
||||
id: <client_id>
|
||||
key: <client_key>
|
||||
name: Johns-Laptop
|
||||
|
||||
server:
|
||||
endpoint: pangolin.yourdomain.com:51820
|
||||
public_key: <server_public_key>
|
||||
|
||||
tunnel:
|
||||
mtu: 1420
|
||||
dns_servers:
|
||||
- 1.1.1.1
|
||||
- 8.8.8.8
|
||||
routes:
|
||||
- 10.0.0.0/16 # Pangolin internal network
|
||||
- 192.168.1.0/24 # Home lab network
|
||||
|
||||
access:
|
||||
auto_connect: true
|
||||
reconnect_on_failure: true
|
||||
kill_switch: false # Block internet if VPN disconnects
|
||||
```
|
||||
|
||||
### 4.3 Updating Newt Clients
|
||||
|
||||
**Manual Update:**
|
||||
```bash
|
||||
# Stop service
|
||||
sudo systemctl stop newt
|
||||
|
||||
# Download latest version
|
||||
curl -fsSL https://get.pangolin.net/newt | sudo bash
|
||||
|
||||
# Restart service
|
||||
sudo systemctl start newt
|
||||
```
|
||||
|
||||
**Docker Update:**
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**Auto-Update Configuration:**
|
||||
```yaml
|
||||
updates:
|
||||
auto_update: true
|
||||
channel: stable # or beta, nightly
|
||||
check_interval: 24h
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Integration Points with Authentik
|
||||
|
||||
Based on research, here's how Pangolin integrates with Authentik for your use case:
|
||||
|
||||
### 5.1 Authentik Configuration
|
||||
|
||||
**Create OAuth2/OIDC Provider in Authentik:**
|
||||
|
||||
1. In Authentik Admin Interface:
|
||||
- Navigate to **Applications** → **Providers** → **Create Provider**
|
||||
- Select **OAuth2/OpenID Provider**
|
||||
|
||||
2. Configure Provider:
|
||||
```yaml
|
||||
Name: Pangolin
|
||||
Authorization Flow: default-provider-authorization-implicit-consent
|
||||
Client Type: Confidential
|
||||
Client ID: <generate_or_custom>
|
||||
Client Secret: <generate_secure_secret>
|
||||
|
||||
Redirect URIs:
|
||||
- https://pangolin.photon.obnh.io/api/v1/auth/callback
|
||||
|
||||
Scopes:
|
||||
- openid
|
||||
- profile
|
||||
- email
|
||||
- groups
|
||||
|
||||
Subject Mode: Based on User's hashed ID
|
||||
Include claims in id_token: Yes
|
||||
```
|
||||
|
||||
3. Create Application:
|
||||
- Navigate to **Applications** → **Applications** → **Create**
|
||||
```yaml
|
||||
Name: Pangolin
|
||||
Slug: pangolin
|
||||
Provider: Pangolin (from step 2)
|
||||
Launch URL: https://pangolin.photon.obnh.io
|
||||
```
|
||||
|
||||
### 5.2 Pangolin Configuration for Authentik
|
||||
|
||||
In Pangolin Dashboard:
|
||||
|
||||
1. Navigate to **Settings** → **Identity Providers** → **Add Identity Provider**
|
||||
2. Select **Generic OAuth2/OIDC**
|
||||
|
||||
```yaml
|
||||
Provider Name: Authentik
|
||||
Provider Type: OAuth2/OIDC
|
||||
|
||||
# Discovery
|
||||
OIDC Discovery URL: https://auth.photon.obnh.io/application/o/pangolin/.well-known/openid-configuration
|
||||
|
||||
# Or manual configuration
|
||||
Authorization Endpoint: https://auth.photon.obnh.io/application/o/authorize/
|
||||
Token Endpoint: https://auth.photon.obnh.io/application/o/token/
|
||||
Userinfo Endpoint: https://auth.photon.obnh.io/application/o/userinfo/
|
||||
JWKS URI: https://auth.photon.obnh.io/application/o/pangolin/jwks/
|
||||
|
||||
# Credentials
|
||||
Client ID: <from_authentik>
|
||||
Client Secret: <from_authentik>
|
||||
|
||||
# Scopes
|
||||
Scopes: openid profile email groups
|
||||
|
||||
# Claims Mapping
|
||||
Username Claim: preferred_username
|
||||
Email Claim: email
|
||||
Display Name Claim: name
|
||||
Groups Claim: groups
|
||||
|
||||
# Provisioning
|
||||
Auto-provision Users: Enabled
|
||||
Default Role: user
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Production Deployment Checklist
|
||||
|
||||
### 6.1 Security Hardening
|
||||
|
||||
- [ ] Enable firewall with only required ports open (80, 443, 51820)
|
||||
- [ ] Use strong passwords and rotate secrets regularly
|
||||
- [ ] Enable 2FA/MFA for admin accounts
|
||||
- [ ] Configure rate limiting in Traefik
|
||||
- [ ] Enable HTTPS-only (HSTS headers)
|
||||
- [ ] Implement fail2ban or CrowdSec for intrusion detection
|
||||
- [ ] Regular security updates and patching
|
||||
- [ ] Audit logs enabled and monitored
|
||||
|
||||
### 6.2 Backup Strategy
|
||||
|
||||
**Critical Data to Backup:**
|
||||
- `/data/pangolin/` - Application data and database
|
||||
- `/data/traefik/acme.json` - SSL certificates
|
||||
- `/config/` - Configuration files
|
||||
- Database dumps (if using PostgreSQL)
|
||||
|
||||
**Backup Script Example:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
BACKUP_DIR="/backups/pangolin-$(date +%Y%m%d)"
|
||||
mkdir -p "$BACKUP_DIR"
|
||||
|
||||
# Stop services
|
||||
docker compose stop
|
||||
|
||||
# Backup data
|
||||
tar -czf "$BACKUP_DIR/pangolin-data.tar.gz" /opt/pangolin/data/
|
||||
tar -czf "$BACKUP_DIR/pangolin-config.tar.gz" /opt/pangolin/config/
|
||||
|
||||
# Backup database
|
||||
docker exec pangolin-db pg_dump -U pangolin pangolin > "$BACKUP_DIR/database.sql"
|
||||
|
||||
# Start services
|
||||
docker compose start
|
||||
|
||||
# Retain last 7 days
|
||||
find /backups -name "pangolin-*" -mtime +7 -exec rm -rf {} \;
|
||||
```
|
||||
|
||||
### 6.3 Monitoring
|
||||
|
||||
**Metrics to Monitor:**
|
||||
- WireGuard tunnel status
|
||||
- Active client connections
|
||||
- Resource health checks
|
||||
- Certificate expiration (Let's Encrypt)
|
||||
- Disk space and memory usage
|
||||
- Authentication failures
|
||||
|
||||
**Integration Options:**
|
||||
- Prometheus + Grafana for metrics
|
||||
- ELK stack for log aggregation
|
||||
- Uptime monitoring (UptimeRobot, Healthchecks.io)
|
||||
|
||||
---
|
||||
|
||||
## 7. Common Use Cases
|
||||
|
||||
### 7.1 Home Lab Exposure
|
||||
- Expose home services (Jellyfin, Home Assistant, Plex) without port forwarding
|
||||
- Centralized authentication via Authentik
|
||||
- SSL certificates automatically managed
|
||||
|
||||
### 7.2 Multi-Site Corporate Network
|
||||
- Connect multiple office locations
|
||||
- Centralized access control for all resources
|
||||
- VPN access for remote employees
|
||||
|
||||
### 7.3 Hybrid Cloud Architecture
|
||||
- Bridge on-premises and cloud resources
|
||||
- Single pane of glass for access management
|
||||
- Secure communication between cloud regions
|
||||
|
||||
---
|
||||
|
||||
## 8. Troubleshooting
|
||||
|
||||
### 8.1 Common Issues
|
||||
|
||||
**Newt Cannot Connect to Server:**
|
||||
- Verify UDP port 51820 is open on firewall
|
||||
- Check WireGuard kernel module: `lsmod | grep wireguard`
|
||||
- Verify credentials are correct
|
||||
- Check logs: `docker logs newt-site`
|
||||
|
||||
**SSL Certificate Issues:**
|
||||
- Ensure DNS points to server IP
|
||||
- Verify ports 80/443 are accessible
|
||||
- Check Let's Encrypt rate limits
|
||||
- Review Traefik logs: `docker logs traefik`
|
||||
|
||||
**Authentication Failures:**
|
||||
- Verify IdP redirect URIs match exactly
|
||||
- Check client ID/secret are correct
|
||||
- Review Pangolin logs for OIDC errors
|
||||
- Test IdP discovery URL is accessible
|
||||
|
||||
### 8.2 Logging
|
||||
|
||||
**Enable Debug Logging:**
|
||||
```yaml
|
||||
# In pangolin.yml
|
||||
logging:
|
||||
level: debug
|
||||
format: json
|
||||
outputs:
|
||||
- type: file
|
||||
path: /app/logs/pangolin.log
|
||||
- type: stdout
|
||||
```
|
||||
|
||||
**View Logs:**
|
||||
```bash
|
||||
# Pangolin
|
||||
docker logs -f pangolin
|
||||
|
||||
# Newt
|
||||
docker logs -f newt-site
|
||||
|
||||
# Traefik
|
||||
docker logs -f traefik
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Additional Resources
|
||||
|
||||
### Official Documentation
|
||||
- Main Documentation: https://docs.pangolin.net/
|
||||
- GitHub Repository: https://github.com/fosrl/pangolin
|
||||
- Newt Client: https://github.com/fosrl/newt
|
||||
- Community Discord: https://discord.gg/pangolin
|
||||
|
||||
### Integration Guides
|
||||
- Authentik Integration: https://docs.goauthentik.io/integrations/services/pangolin/
|
||||
- Authelia Integration: https://www.authelia.com/integration/openid-connect/clients/pangolin/
|
||||
- CrowdSec Integration: https://www.crowdsec.net/blog/web-defense-with-pangolin-and-crowdsec
|
||||
|
||||
### Community Resources
|
||||
- Unraid Deployment Guide: https://forums.unraid.net/topic/193431-secure-external-access-to-plex-more-using-pangolin-tunneled-reverse-proxy/
|
||||
- Docker Compose Examples: https://github.com/fosrl/pangolin/blob/main/docker-compose.yml
|
||||
- YouTube Tutorials: Search "Pangolin self-hosting" for video guides
|
||||
|
||||
---
|
||||
|
||||
## 10. Conclusion
|
||||
|
||||
Pangolin provides a robust, self-hosted alternative to managed tunneling services with enterprise-grade features:
|
||||
|
||||
**Key Advantages:**
|
||||
- Complete data ownership and control
|
||||
- Identity-aware access control with OIDC/OAuth2
|
||||
- No port forwarding required on client networks
|
||||
- Automatic SSL certificate management
|
||||
- Centralized management for distributed resources
|
||||
- Open-source and community-driven
|
||||
|
||||
**Ideal for:**
|
||||
- Home lab enthusiasts requiring secure external access
|
||||
- Organizations needing multi-site connectivity
|
||||
- Teams requiring centralized identity management
|
||||
- Privacy-conscious users avoiding third-party services
|
||||
|
||||
**Next Steps for Implementation:**
|
||||
1. Provision VPS with required specifications
|
||||
2. Configure DNS records for Pangolin domain
|
||||
3. Run installation script or deploy via Docker Compose
|
||||
4. Configure Authentik OIDC integration
|
||||
5. Deploy Newt clients on target networks
|
||||
6. Define resources and access policies
|
||||
7. Test connectivity and authentication flows
|
||||
8. Implement monitoring and backup strategies
|
||||
|
||||
This research provides a comprehensive foundation for deploying Pangolin as a self-hosted control plane integrated with Authentik for identity management.
|
||||
Reference in New Issue
Block a user