Introducing Pangolin Tunnels: A Game-Changer in Open Source Networking

hhf.technoloy · December 26, 2024, 9:09pm

In the world of networking and cybersecurity, the quest for secure, user-friendly, and open-source solutions is always on. Enter Pangolin Tunnels, a breakthrough in how we think about exposing private resources to the internet securely. Here’s an in-depth look at what Pangolin offers, why it’s revolutionary, and how you can leverage it for your projects or home lab.

What is Pangolin?

flowchart TD
    %% Client Zone
    subgraph "Client Zone"
        direction TB
        Browser["User Browser"]:::external
        Frontend["Next.js Frontend"]:::ui
    end

    %% Server Zone
    subgraph "Server Zone"
        direction TB

        subgraph "Edge Proxy & Infra"
            direction TB
            Traefik["Traefik Reverse Proxy"]:::infra
            CrowdSecExt["CrowdSec (External)"]:::external
            LetsEncrypt["Let's Encrypt"]:::external
        end

        subgraph "Hybrid Server"
            direction TB
            NextServer["NextServer (UI/API)"]:::ui
            APIProxy["Integration API Server"]:::api
        end

        subgraph "API Layer"
            direction TB
            ApiServer["apiServer.ts"]:::api
            InternalServer["internalServer.ts"]:::api
            HybridServer["hybridServer.ts"]:::api
            IntegrationApi["integrationApiServer.ts"]:::api
            Routers["Backend Routers"]:::api
            Middlewares["Middlewares"]:::security
            Lib["Business Logic / Libraries"]:::api
        end

        subgraph "Data Layer"
            direction TB
            PGConfig["drizzle.pg.config.ts"]:::db
            SQLiteConfig["drizzle.sqlite.config.ts"]:::db
            PGFolder["server/db/pg"]:::db
            SQLiteFolder["server/db/sqlite"]:::db
            Database["Database (Postgres/SQLite)"]:::db
        end

        subgraph "Security & Identity"
            direction TB
            Auth["Authentication & Access Management"]:::security
            OIDC["OIDC Integration"]:::security
            Email["Email Templates & SMTP"]:::security
        end

        subgraph "Tunnel Management"
            direction TB
            NewtRouter["Newt Router"]:::infra
            ExitNodesLib["Exit Nodes Logic"]:::infra
        end

        subgraph "Installer & Tooling"
            direction TB
            Installer["Go Install Orchestrator"]:::infra
            CLI["CLI Wrapper"]:::infra
            DSL["DSL Scripting (Bruno)"]:::infra
            Orchestration["Docker & Compose Orchestration"]:::infra
        end

        subgraph "Frontend Utilities"
            direction TB
            Contexts["Front-end Contexts"]:::ui
            Providers["Front-end Providers"]:::ui
            Hooks["Front-end Hooks"]:::ui
            ApiLib["Front-end API Lib"]:::ui
        end

        EnvConfig["Env & Logging Config"]:::infra
        Localization["Localization Assets"]:::ui
    end

    %% External Identity and SMTP
    IdP["External IdP/OIDC Providers"]:::external
    SMTP["Email SMTP Service"]:::external

    %% Connections
    Browser -->|"HTTPS"| Traefik
    Traefik -->|"routes UI/API"| NextServer
    NextServer -->|HTTP| ApiServer
    ApiServer -->|requests| Middlewares
    Middlewares -->|calls| Routers
    Routers -->|uses| Lib
    Lib -->|queries| Database
    APIProxy -->|websocket| NewtRouter
    NewtRouter -->|manages tunnel| ExitNodesLib
    Traefik -->|"ACME"| LetsEncrypt
    Traefik -->|"plugin"| CrowdSecExt
    Installer -->|orchestrates| Traefik
    Installer -->|orchestrates| ApiServer
    Installer -->|orchestrates| NewtRouter
    Installer -->|orchestrates| CrowdSecExt
    Installer -->|orchestrates| Database
    Auth -->|redirect| IdP
    Auth -->|email codes| SMTP
    Email -->|send| SMTP

    %% Click Events
    click Frontend "https://github.com/fosrl/pangolin/tree/main/src/"
    click ApiServer "https://github.com/fosrl/pangolin/blob/main/server/apiServer.ts"
    click InternalServer "https://github.com/fosrl/pangolin/blob/main/server/internalServer.ts"
    click HybridServer "https://github.com/fosrl/pangolin/blob/main/server/hybridServer.ts"
    click IntegrationApi "https://github.com/fosrl/pangolin/blob/main/server/integrationApiServer.ts"
    click Routers "https://github.com/fosrl/pangolin/tree/main/server/routers/"
    click Middlewares "https://github.com/fosrl/pangolin/tree/main/server/middlewares/"
    click Lib "https://github.com/fosrl/pangolin/tree/main/server/lib/"
    click PGConfig "https://github.com/fosrl/pangolin/blob/main/drizzle.pg.config.ts"
    click SQLiteConfig "https://github.com/fosrl/pangolin/blob/main/drizzle.sqlite.config.ts"
    click PGFolder "https://github.com/fosrl/pangolin/tree/main/server/db/pg/"
    click SQLiteFolder "https://github.com/fosrl/pangolin/tree/main/server/db/sqlite/"
    click Database "https://github.com/fosrl/pangolin/blob/main/server/db/pg/index.ts"
    click Auth "https://github.com/fosrl/pangolin/tree/main/server/auth/"
    click OIDC "https://github.com/fosrl/pangolin/blob/main/server/lib/idp/generateRedirectUrl.ts"
    click OIDC "https://github.com/fosrl/pangolin/tree/main/server/routers/idp/"
    click Email "https://github.com/fosrl/pangolin/tree/main/server/emails/"
    click NewtRouter "https://github.com/fosrl/pangolin/tree/main/server/routers/newt/"
    click ExitNodesLib "https://github.com/fosrl/pangolin/blob/main/server/lib/exitNodes/exitNodes.ts"
    click ExitNodesLib "https://github.com/fosrl/pangolin/blob/main/server/lib/exitNodeComms.ts"
    click Traefik "https://github.com/fosrl/pangolin/blob/main/config/traefik/traefik_config.yml"
    click Traefik "https://github.com/fosrl/pangolin/blob/main/config/traefik/dynamic_config.yml"
    click Traefik "https://github.com/fosrl/pangolin/blob/main/install/config/traefik/traefik_config.yml"
    click Traefik "https://github.com/fosrl/pangolin/blob/main/install/config/traefik/dynamic_config.yml"
    click Traefik "https://github.com/fosrl/pangolin/blob/main/server/lib/traefikConfig.ts"
    click Traefik "https://github.com/fosrl/pangolin/tree/main/server/routers/traefik/"
    click CrowdSecExt "https://github.com/fosrl/pangolin/tree/main/install/config/crowdsec/"
    click CrowdSecExt "https://github.com/fosrl/pangolin/blob/main/install/config/crowdsec/docker-compose.yml"
    click CrowdSecExt "https://github.com/fosrl/pangolin/blob/main/install/config/crowdsec/profiles.yaml"
    click Installer "https://github.com/fosrl/pangolin/blob/main/install/main.go"
    click CLI "https://github.com/fosrl/pangolin/blob/main/cli/index.ts"
    click CLI "https://github.com/fosrl/pangolin/blob/main/cli/wrapper.sh"
    click DSL "https://github.com/fosrl/pangolin/tree/main/bruno/"
    click Orchestration "https://github.com/fosrl/pangolin/blob/main/docker-compose.yml"
    click EnvConfig "https://github.com/fosrl/pangolin/blob/main/config/config.example.yml"
    click Localization "https://github.com/fosrl/pangolin/tree/main/messages/"
    click Contexts "https://github.com/fosrl/pangolin/tree/main/src/contexts/"
    click Providers "https://github.com/fosrl/pangolin/tree/main/src/providers/"
    click Hooks "https://github.com/fosrl/pangolin/tree/main/src/hooks/"
    click ApiLib "https://github.com/fosrl/pangolin/tree/main/src/lib/api/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef api fill:#b8daff,stroke:#004085,color:#004085
    classDef security fill:#d4edda,stroke:#155724,color:#155724
    classDef infra fill:#fff3cd,stroke:#856404,color:#856404
    classDef db fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24

Pangolin is an open-source, self-hosted server that manages tunneled reverse proxies. It’s designed to provide secure access to private services without needing to open ports on your router, which is particularly useful in environments where port forwarding isn’t possible or when you want to maintain a high level of security.

Key Features:

WireGuard Tunneling: Pangolin uses WireGuard, a modern, fast VPN that utilizes state-of-the-art cryptography. This ensures that your data remains secure while traveling through tunnels from your private network to the public internet.
Identity and Access Management: Beyond just tunneling, Pangolin includes comprehensive identity and access controls, allowing for user authentication, role-based access, and features like one-time passwords or email authentication for added security.
User Interface: With an intuitive web dashboard, managing your tunnels, users, and resources has never been simpler. The dashboard allows you to configure everything from site connections to user permissions without delving into complex command lines.
SSL Automation: Pangolin automates SSL certificate management with Let’s Encrypt, ensuring your services are available via secure HTTPS connections effortlessly.
Support for Multiple Protocols: Whether you’re dealing with HTTP/HTTPS or raw TCP/UDP services, Pangolin can handle it, making it versatile for various applications.

Why Pangolin is a Revolution in Open Source

Control and Privacy: By hosting your own tunneling solution, you retain full control over your data and network security, reducing reliance on third-party services which might track or monetize your data.
Cost-Effective: Unlike proprietary solutions, Pangolin is free to use, modify, and distribute. This opens up high-quality networking capabilities to hobbyists, small businesses, and large enterprises looking to cut costs or avoid vendor lock-in.
Community Driven: Being open source, Pangolin benefits from community contributions. This means bugs are fixed, features are added, and the software evolves rapidly to meet user needs.
Ease of Use: Pangolin’s interface and installation process are designed with the user in mind, making complex networking tasks accessible to a broader audience, from networking novices to seasoned professionals.

How to Get Started with Pangolin

Installation: Pangolin can be installed via Docker, which simplifies setup across different environments. There are detailed guides on the official documentation or community forums to help you get started.

Prerequisites: You’ll need a domain name and a server (like a VPS) where Pangolin can run.
Docker Compose: There’s an easy-to-follow Docker Compose file that sets up Pangolin alongside necessary components like Traefik and Gerbil (for WireGuard interface management).

Configuration:

Create Organizations and Sites: Define your structure for managing different environments or projects within Pangolin.
Set Up Tunnels: Connect your private services to the public internet by configuring tunnels through the Pangolin dashboard.

Security:

Implement user authentication. Decide who can access which services by defining roles and permissions.
Ensure all traffic is encrypted by leveraging Pangolin’s SSL automation.

Testing and Usage: Once configured, test your services from the internet to ensure they’re accessible, secure, and functioning as expected.

Use Cases

Home Labs: Securely expose services like Plex, Jellyfin, or your own web applications to the internet without the hassle of port forwarding.
Business Applications: For small businesses, manage access to internal tools or applications for remote employees or clients securely.
Education and Learning: A fantastic tool for students or enthusiasts learning about networking, security, and how applications are deployed and accessed over the internet.

Community and Support

Pangolin has an active community on platforms like Reddit, GitHub, and Discord. Here, you can find support, share configurations, and even contribute to the project’s development. The documentation is thorough, and community members are generally eager to help newcomers get started.

Conclusion

Pangolin Tunnels represent more than just another open-source project; they symbolize a shift towards democratizing advanced networking tools. Whether you’re a developer, a sysadmin, or just someone passionate about technology, Pangolin offers you the tools to secure your network, control your data, and explore new possibilities in application deployment and access. Give it a try, contribute if you can, and join the growing community of users who are excited about what Pangolin brings to the table in the open-source ecosystem.