diff --git a/about/how-pangolin-works.mdx b/about/how-pangolin-works.mdx index 4a4dc59..6e7a254 100644 --- a/about/how-pangolin-works.mdx +++ b/about/how-pangolin-works.mdx @@ -1,66 +1,81 @@ --- title: "How Pangolin Works" -description: "Learn about Pangolin's architecture and how its components work together to provide secure application access" +icon: "brain" +description: "Learn about the fundamentals of Pangolin and how they work together to provide simple and secure remote access." --- -Pangolin provides secure, application-specific ingress to your applications through a network of nodes. Users connect to the closest node, which authenticates them and routes their requests through secure tunnels to your backend. - - - - - -## How It Works +## Basic Steps - - DNS automatically routes users to the closest available regional node. A node is always available because the control plane fails over between nodes. + + Join remote networks together using site connectors. Pangolin's lightweight connectors use intelligent routing and NAT traversal to make any network anywhere available. - - The node verifies the user's identity, checks access permissions, and applies context aware rules such as IP and path based filters, geoblocking, and rate limiting. + + Create resources that represent services or entire network ranges available for remote access. Resources can be public or fully private. - - Authenticated requests are routed and flow through encrypted WireGuard tunnels to your applications with optional load balancing and failover for your backend servers. - - - - Your applications receive the requests and respond through the same secure path. + + Authenticated users can access resources anywhere using a web browser or when connected with a Pangolin client on their device. -## Deployment Options +## Key Concepts - - - Large network of nodes with automatic failover and routing to your backend services. We host the Pangolin server for you. +Pangolin relies on several components that work together to provide secure remote access. Each component has a specific role in ensuring that only authenticated users can access the resources they are authorized to use. + +### Pangolin Server + +The Pangolin server is the central coordination component for your network. It stores configuration changes, manages access policies, and coordinates connections between clients and sites. The server handles user authentication and generates access control lists that determine what resources each user can reach. + +You can use Pangolin Cloud, which is fully managed, or you can self-host your own Pangolin server for complete control over your infrastructure and data. + + + Learn how to deploy your own self-hosted Pangolin server or use Pangolin Cloud. - - Fully self-hosted, self-contained Pangolin server acting as a single node. +### Sites + +Sites connect remote networks to your Pangolin server. They use Newt connectors to create secure tunnels from remote networks back to Pangolin. Sites let you expose resources on those networks to authorized users. + +Sites run behind firewalls on remote networks. They maintain outbound connections to the Pangolin server. By default, sites block all traffic until you define resources and grant access. This ensures that just deploying a site does not expose any network resources. + +The Newt connector handles tunnel creation, NAT traversal, and routing. It makes remote networks available without requiring complex firewall rules or public IP addresses. + + + Learn about sites, how they work, and how to install and configure them. - - Self-host your own Pangolin node with cloud coordination for high availability and automatic failover. Data always transits your servers. - - +### Resources -## Key Benefits +Resources are the applications, hosts, or network ranges you make available to users. They exist on sites and represent what users can access. Users connect to resources, not to sites directly. - - - Your applications can run on private networks without exposing ports. +There are two types of resources. Public resources work through web browsers and act as reverse proxies to backend services. Private resources require a client connection and function like a zero-trust VPN. + +You must define resources and assign access before users can reach them. By default, no resources are available on sites. This ensures that only explicitly defined resources can be accessed. + + + Learn about public and private resources and how to create them. - - Users always connect to the closest available node. +### Clients + +Clients are software components installed on user devices or machines. They let users and automated systems connect to your Pangolin network and access private resources through a secure tunnel. + +Users authenticate through the client using their accounts. Machines connect with credentials. Once connected, users can reach all resources their account has access to. The client handles routing decisions and establishes encrypted tunnels to the appropriate sites. + +Clients are available for Mac, Windows, and Linux. They work transparently with applications, so no application configuration is required. + + + Learn about clients and where to download them for Mac, Windows, and Linux. - - Every request is authenticated and authorized before reaching your applications. - +### Remote Nodes - - Multiple nodes, failover, and load balancing between tunnels ensures there is always a way for users to access your applications. +Remote nodes are self-hosted Pangolin servers that you control while using Pangolin Cloud or enterprise for management and coordination. You maintain complete control over your infrastructure and data flow, while the cloud handles the control plane, DNS, certificate management, and backups. + +You can deploy multiple remote nodes for high availability and automatic failover. If your nodes become unavailable, traffic can optionally fail over to cloud infrastructure until you restore service. + + + Learn about remote nodes and how they provide high availability and simplified operations. - diff --git a/about/pangolin-vs-reverse-proxy-vs-vpn.mdx b/about/pangolin-vs-reverse-proxy-vs-vpn.mdx new file mode 100644 index 0000000..c67dde6 --- /dev/null +++ b/about/pangolin-vs-reverse-proxy-vs-vpn.mdx @@ -0,0 +1,55 @@ +--- +title: "Pangolin vs. Reverse Proxy vs. VPN" +icon: "book" +description: "What are the similarities and differences between Pangolin and traditional reverse proxies and VPNs?" +--- + +Pangolin combines the capabilities of both a reverse proxy and a VPN into a single platform. It provides reverse proxy functionality through public resources and VPN functionality through private resources, all with zero-trust access control and distributed architecture. + +## What Each Solution Provides + +**Reverse Proxies** expose web applications to the internet. They handle SSL termination, load balancing, and basic authentication. Users access applications through web browsers using domain names. + +**VPNs** create encrypted tunnels that give users access to entire private networks. Users install client software and connect to a VPN server. Once connected, they can access any resource on the network they have network-level access to. + +**Pangolin** provides both capabilities. Public resources work like a reverse proxy, allowing browser-based access to specific applications. Private resources work like a zero-trust VPN, giving users access to specific hosts or network ranges when connected with a client. + +## Reverse Proxy Capabilities + +Pangolin's public resources function as reverse proxies. They expose web applications through domain names with automatic SSL certificates. Users access these resources through web browsers without installing any software. + +Public resources support identity-aware access control. You can require authentication, enforce multi-factor authentication, and create rules based on user identity, roles, geographic location, IP addresses, and URL paths. This goes beyond what traditional reverse proxies offer. + +Unlike traditional reverse proxies, Pangolin does not require public IP addresses or open ports on your network. Sites create outbound tunnels to Pangolin, so your applications remain behind firewalls. + +## VPN Capabilities + +Pangolin's private resources function like a zero-trust VPN. Users install a Pangolin client on their device and connect to your organization. Once connected, they can access the specific hosts or network ranges you have granted them access to. + +Private resources provide granular access control. Users only get access to the specific resources you define, not entire networks. This reduces the risk of over-permission that comes with traditional VPNs. + +Clients work transparently with applications. No application configuration is required. Users connect once and can access all their authorized resources. The client handles routing and establishes encrypted tunnels automatically. + +## Why Pangolin Combines Both + +Many organizations need both reverse proxy and VPN capabilities. You might want to expose web applications to users through browsers while also providing secure access to databases, SSH servers, or internal services that require a VPN-like connection. + +With Pangolin, you use one platform for both use cases. Public resources handle web application access. Private resources handle VPN-like access. Both use the same authentication system, access control policies, and infrastructure. + +This unified approach simplifies management. You configure users, roles, and access policies once. Those policies apply to both public and private resources. You do not need to maintain separate systems for reverse proxy and VPN access. + +## Infrastructure and Availability + +Traditional reverse proxies and VPNs typically run on a single server. If that server fails, all access is lost. They also require public IP addresses and open ports, which adds complexity and security concerns. + +Pangolin uses a distributed architecture with multiple nodes. If one node fails, traffic automatically routes to another node. Sites create outbound tunnels, so your networks do not need public IP addresses or open ports. + +You can deploy multiple remote nodes for high availability. If your nodes become unavailable, traffic can optionally fail over to cloud infrastructure until you restore service. This provides redundancy that single-server solutions cannot match. + +## When to Use Each Solution + +Use a traditional reverse proxy if you only need to expose web applications, you have a public IP address, and you do not need advanced access control or high availability. + +Use a traditional VPN if you need full network access, you can accept the security risks of broad access, and you do not need application-specific access control. + +Use Pangolin if you need both reverse proxy and VPN capabilities, you want granular access control, you need high availability, or you want to avoid public IP addresses and open ports. diff --git a/about/pangolin-vs-traditional-reverse-proxy.mdx b/about/pangolin-vs-traditional-reverse-proxy.mdx deleted file mode 100644 index 90266fb..0000000 --- a/about/pangolin-vs-traditional-reverse-proxy.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: "Pangolin vs. Reverse Proxy" -description: "Learn how Pangolin's distributed architecture eliminates single points of failure and provides authenticated access to your applications" ---- - -Pangolin builds upon traditional reverse proxy principles but adds distributed architecture, tunneling, and identity-aware access control. While traditional reverse proxies are typically single-server solutions, Pangolin operates as a distributed network of nodes that provide highly-available access to your applications. - -## Traditional Reverse Proxy Limitations - - - - If the reverse proxy server goes down, all applications become inaccessible. - - - - Users far from the server location experience higher latency. - - - - Requires public IP addresses and open ports on your network. - - - - Typically relies on network-based trust rather than user identity. - - - -## Pangolin's Dual-Layer High Availability - -Pangolin provides high availability at two critical layers: ingress points and backend routing. - -### How It Works - - - - Request is routed to the closest available node. If one goes down, there is always another point available. - - - - User identity is verified at the node before getting routed to your backend. - - - - Pangolin selects the optimal tunnel route to your backend service. - - - - If the primary tunnel fails, traffic automatically switches to an alternative route. - - - - Response follows the same resilient path back to the user. - - - - -This dual-layer approach ensures your applications remain accessible even if individual nodes or tunnel connections fail. - - -## Key Differences - -### Tunneling vs. Direct Network Access - -| Traditional Reverse Proxy | Pangolin | -|--------------------------|----------| -| **Public IP Required** | **No Public IP Needed** | -| **Open Ports (80, 443)** | **No Open Ports** | -| **Complex Network Setup** | **Automatic Discovery** | -| **Network-Based Security** | **Encrypted WireGuard Tunnels** | - - -This tunneling capability makes Pangolin ideal for environments behind restrictive firewalls, CGNAT, or corporate networks. - - -### Identity-Aware Proxy (IAP) - -Traditional reverse proxies rely on network-based trust, while Pangolin implements zero-trust access control: - - - - Support for 2FA, passkeys, and OTP. - - - - Integration with Google, Okta, and other identity providers. - - - - Role-based access control and path-based rules. - - - - IP-based, path-based, and geographic access policies. - - - - -Unlike traditional reverse proxies, Pangolin authenticates every single request, ensuring that only authorized users can access your applications. - - -## Benefits Summary - -| Feature | Traditional Reverse Proxy | Pangolin | -|---------|--------------------------|----------| -| **Availability** | Single point of failure | Distributed, fault-tolerant | -| **Performance** | Limited by server location | Regionally, optimized routing | -| **Security** | Network-based trust | Zero-trust, identity-aware | -| **Network Requirements** | Public IP, open ports | No public IP needed | -| **Authentication** | Basic or none | Advanced, multi-factor | -| **Scalability** | Manual scaling | Automatic regional distribution | - - - Get distributed, authenticated access to your applications with Pangolin's regional network of nodes. - diff --git a/about/pangolin-vs-vpn.mdx b/about/pangolin-vs-vpn.mdx deleted file mode 100644 index 7f10402..0000000 --- a/about/pangolin-vs-vpn.mdx +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "Pangolin vs. VPN" -description: "Learn how Pangolin provides application-specific access with zero-trust security compared to traditional VPNs" ---- - -Pangolin and VPNs serve different purposes: Pangolin focuses on secure ingress and application routing, while VPNs provide remote access to internal networks. They offer different approaches to secure connectivity. - -## Traditional VPN Limitations - - - - Users get access to entire networks, not just the applications they need. - - - - Users must install and configure VPN client software. - - - - Requires public IP addresses, open ports, and complex network configuration. - - - - Basic network-level security with few granular controls or complicated ACLs. - - - - If the VPN server goes down, all access is lost. - - - - Broad network access can be risky if user devices are compromised. - - - -## Pangolin's Ingress-First Approach - -Pangolin provides secure, application-specific ingress and routing without the limitations of traditional VPNs: - -### Zero-Trust Access Control - - - - Users access only the applications they're authorized to use. - - - - No client software installation required - works with any web browser. - - - - Role-based access control, path-based rules, and contextual policies. - - - - Support for SSO, OIDC, 2FA, and passkeys. - - - -### Simplified Ingress Infrastructure - - - - Edge networks don't need public IP addresses. - - - -Multiple nodes ensure high availability. - - - -## Key Differences - -| Feature | Traditional VPN | Pangolin | -|---------|----------------|----------| -| **Access Scope** | Full network access | Application-specific access | -| **Client Software** | Required | Not needed (browser-based) | -| **Network Requirements** | Public IP, open ports | No public IP needed | -| **Access Control** | Network-level | Zero-trust, granular | -| **Authentication** | Basic credentials | Multi-factor, SSO, OIDC | -| **Infrastructure** | Single server | Distributed nodes | -| **Security Model** | Network-based trust | Identity-based trust | - - - Get application-specific access with zero-trust security and no client software required. - - -# Pangolin vs. Mesh VPN (e.g., Tailscale, Netbird) - -Pangolin and mesh VPNs like Tailscale or Netbird both provide secure remote access, but they differ in their approach and functionality. Mesh VPNs focus on creating peer-to-peer connections between devices for full network access, while Pangolin is designed to expose specific applications or services securely through nodes, with no need for client-side software on user devices. - -Pangolin is a better choice for application-specific access with zero-trust security and no client-side software requirements. Mesh VPNs like Tailscale or Netbird are more suitable for full network access and peer-to-peer connectivity. For environments prioritizing granular access control and simplicity, Pangolin offers a more focused and secure solution. diff --git a/additional-resources/changelog.mdx b/additional-resources/changelog.mdx new file mode 100644 index 0000000..8526c95 --- /dev/null +++ b/additional-resources/changelog.mdx @@ -0,0 +1,7 @@ +--- +title: "Changelog" +icon: "clipboard-list" +--- + +To view the complete changelog, please visit our [GitHub Releases +page](https://github.com/fosrl/pangolin/releases). diff --git a/additional-resources/trust-center.mdx b/additional-resources/trust-center.mdx new file mode 100644 index 0000000..ce9df79 --- /dev/null +++ b/additional-resources/trust-center.mdx @@ -0,0 +1,9 @@ +--- +title: "Trust Center" +icon: "scale-balanced" +--- + +- [Terms of Service](https://pangolin.net/terms-of-service.html) +- [Privacy Policy](https://pangolin.net/privacy-policy.html) +- [AGLPv3](https://www.gnu.org/licenses/gpl-3.0.en.html) +- [Fossorial Commercial License (FCL)](https://pangolin.net/fcl.hmtl) diff --git a/development/contributing.mdx b/development/contributing.mdx index ad5e26d..318046f 100644 --- a/development/contributing.mdx +++ b/development/contributing.mdx @@ -7,9 +7,9 @@ This guide describes how to set up your local development environment for contri ## Prerequisites -- NodeJS v20.10.0 -- NPM v10.2.3 (or similar) -- Go v1.23.1 +- Node 24 +- NPM 11 or similar +- Go 1.25 - Git - Docker & Docker Compose @@ -280,7 +280,7 @@ Windows users with Docker Desktop + WSL2: File change detection may not work pro ### Gerbil -- Go v1.23.1 +- Go 1.25 ```bash make local @@ -288,7 +288,7 @@ make local ### Newt -- Go v1.23.1 +- Go 1.25 ```bash make local @@ -296,7 +296,7 @@ make local ### Olm -- Go v1.23.1 +- Go 1.25 ```bash make local diff --git a/docs.json b/docs.json index 1e20fbd..44c2839 100644 --- a/docs.json +++ b/docs.json @@ -1,257 +1,288 @@ { - "$schema": "https://mintlify.com/docs.json", - "theme": "aspen", - "name": "Pangolin Docs", - "description": "Pangolin is a self-hosted alternative to Cloudflare Tunnels, designed to provide secure and highly-available ingress access to applications.", - "colors": { - "primary": "#F36117", - "light": "#F36117", - "dark": "#F36117" - }, - "favicon": "/favicon.svg", - "navigation": { - "tabs": [ - { - "tab": "Docs", - "groups": [ - { - "group": "About", - "pages": [ - "about/pangolin-vs-traditional-reverse-proxy", - "about/pangolin-vs-vpn" - ] - }, - { - "group": "Manage Pangolin", - "pages": [ - { - "group": "Sites", - "pages": [ - "manage/sites/add-site", - "manage/sites/install-site", - "manage/sites/install-kubernetes", - "manage/sites/configure-site", - "manage/sites/update-site" - ] - }, - { - "group": "Resources", - "pages": [ - "manage/resources/targets", - "manage/resources/tcp-udp-resources", - "manage/resources/client-resources" - ] - }, - { - "group": "Access Control", - "pages": [ - "manage/access-control/create-user", - "manage/access-control/rules", - "manage/access-control/forwarded-headers", - "manage/access-control/login-page", - "manage/geoblocking", - "manage/access-control/mfa", - "manage/access-control/password-rotation", - "manage/access-control/session-length", - "manage/access-control/change-password", - "manage/access-control/security-keys" - ] - }, - { - "group": "Identity Providers", - "pages": [ - "manage/identity-providers/add-an-idp", - "manage/identity-providers/auto-provisioning", - "manage/identity-providers/openid-connect", - "manage/identity-providers/google", - "manage/identity-providers/azure", - "manage/identity-providers/pocket-id", - "manage/identity-providers/zitadel" - ] - }, - { - "group": "Clients", - "pages": [ - "manage/clients/add-client", - "manage/clients/install-client", - "manage/clients/configure-client" - ] - }, - "manage/healthchecks-failover", - "manage/blueprints", - { - "group": "Remote Nodes", - "pages": [ - "manage/remote-node/ha", - "manage/remote-node/nodes", - "manage/remote-node/quick-install-remote", - "manage/remote-node/convert-remote", - "manage/remote-node/config-file" - ] - }, - { - "group": "Analytics", - "pages": [ - "manage/analytics/request", - "manage/analytics/access", - "manage/analytics/action" - ] - }, - "manage/domains", - "manage/integration-api", - "manage/branding" - ] - }, - { - "group": "Self-host Pangolin", - "pages": [ - "self-host/quick-install", - { - "group": "Manual Installation", - "pages": [ - "self-host/manual/docker-compose", - "self-host/manual/unraid" - ] - }, - "self-host/dns-and-networking", - "self-host/choosing-a-vps", - "self-host/how-to-update", - "self-host/supporter-program", - { - "group": "Advanced Configuration", - "pages": [ - "self-host/advanced/config-file", - "self-host/advanced/wild-card-domains", - "self-host/advanced/cloudflare-proxy", - "self-host/advanced/without-tunneling", - "self-host/advanced/container-cli-tool", - "self-host/advanced/database-options", - "self-host/advanced/integration-api", - "self-host/advanced/enable-geoblocking", - "self-host/advanced/metrics" - ] - }, - { - "group": "Community Guides", - "pages": [ - "self-host/community-guides/overview", - "self-host/community-guides/crowdsec", - "self-host/community-guides/metrics", - "self-host/community-guides/homeassistant", - "self-host/community-guides/middlewaremanager", - "self-host/community-guides/traefiklogsdashboard", - "self-host/community-guides/geolite2automation" - ] - }, - "self-host/telemetry", - "self-host/enterprise-edition" - ] - }, - { - "group": "Development", - "pages": [ - "development/system-architecture", - "development/contributing", - "development/feature-requests-and-bug-reports" - ] - }, - { - "group": "Careers", - "pages": [ - "careers/join-us", - "careers/software-engineer-full-stack", - "careers/software-engineer-go" - ] - } - ] - }, - { - "tab": "Blog", - "href": "https://pangolin.net/blog" - }, - { - "tab": "Website", - "href": "https://pangolin.net/" - } - ], - "global": { - "anchors": [ - { - "anchor": "GitHub", - "href": "https://github.com/fosrl/pangolin", - "icon": "github" - }, - { - "anchor": "Slack", - "href": "https://pangolin.net/slack", - "icon": "slack" - }, - { - "anchor": "Discord", - "href": "https://pangolin.net/discord", - "icon": "discord" - } - ] - } - }, - "logo": { - "light": "/logo/light.png", - "dark": "/logo/dark.png", - "href": "https://docs.pangolin.net" - }, - "navbar": { - "links": [ - { - "label": "Contact Us", - "href": "mailto:numbat@pangolin.net" - } - ], - "primary": { - "type": "button", - "label": "Pangolin Dashboard", - "href": "https://app.pangolin.net" - } - }, - "footer": { - "socials": { - "github": "https://github.com/fosrl/pangolin", - "linkedin": "https://linkedin.com/company/digpangolin" - } - }, - "integrations": { - "posthog": { - "apiKey": "phc_RIHQ7o2Y2hf8qms2nP62vpoJHEvsrw6TieflQGQO7yI", - "apiHost": "https://pangolin.net/relay-O7yI" - } - }, - "contextual": { - "options": [ - "copy", - "view", - "chatgpt", - "claude", - "perplexity", - { - "title": "Request a feature", - "description": "Open a GitHub discussion to request a new feature", - "icon": "plus", - "href": "https://github.com/fosrl/pangolin/discussions" - } - ] - }, - "redirects": [ - { - "source": "/telemetry", - "destination": "/self-host/telemetry" + "$schema": "https://mintlify.com/docs.json", + "theme": "aspen", + "name": "Pangolin Docs", + "description": "Pangolin is the easiest to use identity-based remote access platform based on WireGuard.", + "colors": { + "primary": "#F36117", + "light": "#F36117", + "dark": "#F36117" }, - { - "source": "/community/:slug*", - "destination": "/self-host/:slug*" + "favicon": "/favicon.svg", + "navigation": { + "tabs": [ + { + "tab": "Docs", + "groups": [ + { + "group": "About", + "pages": [ + "about/how-pangolin-works", + "about/pangolin-vs-reverse-proxy-vs-vpn" + ] + }, + { + "group": "Manage Pangolin", + "pages": [ + { + "group": "Sites", + "icon": "plug", + "pages": [ + "manage/sites/understanding-sites", + "manage/sites/install-site", + "manage/sites/install-kubernetes", + "manage/sites/configure-site", + "manage/sites/update-site", + "manage/sites/credentials" + ] + }, + { + "group": "Resources", + "icon": "link", + "pages": [ + "manage/resources/understanding-resources", + { + "group": "Public Resources", + "pages": [ + "manage/resources/public/authentication", + "manage/resources/public/targets", + "manage/healthchecks-failover", + "manage/resources/public/raw-resources" + ] + }, + { + "group": "Private Resources", + "pages": [ + "manage/resources/private/authentication", + "manage/resources/private/destinations", + "manage/resources/private/alias" + ] + } + ] + }, + { + "group": "Clients", + "icon": "desktop", + "pages": [ + "manage/clients/understanding-clients", + "manage/clients/install-client", + "manage/clients/configure-client", + "manage/clients/update-client", + "manage/clients/credentials" + ] + }, + "manage/domains", + { + "group": "Access Control", + "icon": "user-group", + "pages": [ + "manage/access-control/create-user", + "manage/access-control/rules", + "manage/access-control/forwarded-headers", + "manage/access-control/login-page", + "manage/geoblocking", + "manage/access-control/mfa", + "manage/access-control/password-rotation", + "manage/access-control/session-length", + "manage/access-control/change-password", + "manage/access-control/security-keys" + ] + }, + { + "group": "Identity Providers", + "icon": "id-card", + "pages": [ + "manage/identity-providers/add-an-idp", + "manage/identity-providers/auto-provisioning", + "manage/identity-providers/openid-connect", + "manage/identity-providers/google", + "manage/identity-providers/azure", + "manage/identity-providers/pocket-id", + "manage/identity-providers/zitadel" + ] + }, + { + "group": "Logs & Analytics", + "icon": "chart-bar", + "pages": [ + "manage/analytics/request", + "manage/analytics/access", + "manage/analytics/action" + ] + }, + "manage/blueprints", + { + "group": "Remote Nodes", + "icon": "circle-nodes", + "pages": [ + "manage/remote-node/ha", + "manage/remote-node/nodes", + "manage/remote-node/quick-install-remote", + "manage/remote-node/convert-remote", + "manage/remote-node/config-file" + ] + }, + "manage/integration-api", + "manage/branding" + ] + }, + { + "group": "Self-host Pangolin", + "pages": [ + "self-host/quick-install", + "self-host/choosing-a-vps", + { + "group": "Manual Installation", + "pages": [ + "self-host/manual/docker-compose", + "self-host/manual/unraid" + ] + }, + "self-host/dns-and-networking", + { + "group": "Advanced Configuration", + "pages": [ + "self-host/advanced/config-file", + "self-host/advanced/wild-card-domains", + "self-host/advanced/cloudflare-proxy", + "self-host/advanced/without-tunneling", + "self-host/advanced/container-cli-tool", + "self-host/advanced/database-options", + "self-host/advanced/integration-api", + "self-host/advanced/enable-geoblocking", + "self-host/advanced/metrics", + "self-host/telemetry" + ] + }, + "self-host/how-to-update", + { + "group": "Community Guides", + "pages": [ + "self-host/community-guides/overview", + "self-host/community-guides/crowdsec", + "self-host/community-guides/metrics", + "self-host/community-guides/homeassistant", + "self-host/community-guides/middlewaremanager", + "self-host/community-guides/traefiklogsdashboard", + "self-host/community-guides/geolite2automation" + ] + }, + "self-host/supporter-program", + "self-host/enterprise-edition" + ] + }, + { + "group": "Development", + "pages": [ + "development/system-architecture", + "development/contributing", + "development/feature-requests-and-bug-reports" + ] + }, + { + "group": "Additional Resources", + "pages": [ + "additional-resources/changelog", + "additional-resources/trust-center" + ] + } + ] + }, + { + "tab": "Blog", + "href": "https://pangolin.net/blog" + }, + { + "tab": "Website", + "href": "https://pangolin.net/" + } + ], + "global": { + "anchors": [ + { + "anchor": "GitHub", + "href": "https://github.com/fosrl/pangolin", + "icon": "github" + }, + { + "anchor": "Slack", + "href": "https://pangolin.net/slack", + "icon": "slack" + }, + { + "anchor": "Discord", + "href": "https://pangolin.net/discord", + "icon": "discord" + } + ] + } + }, + "interaction": { + "drilldown": true + }, + "logo": { + "light": "/logo/light.png", + "dark": "/logo/dark.png", + "href": "https://docs.pangolin.net" + }, + "navbar": { + "links": [ + { + "label": "Log In", + "href": "https://app.pangolin.net/auth/login" + }, + { + "label": "Contact Us", + "icon": "envelope", + "href": "mailto:contact@pangolin.net" + } + ], + "primary": { + "type": "button", + "label": "Pangolin Dashboard", + "href": "https://app.pangolin.net/auth/signup" + } + }, + "footer": { + "socials": { + "github": "https://github.com/fosrl/pangolin", + "linkedin": "https://linkedin.com/company/digpangolin" + } + }, + "integrations": { + "posthog": { + "apiKey": "phc_RIHQ7o2Y2hf8qms2nP62vpoJHEvsrw6TieflQGQO7yI", + "apiHost": "https://pangolin.net/relay-O7yI" + } + }, + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude", + "perplexity", + { + "title": "Request a feature", + "description": "Open a GitHub discussion to request a new feature", + "icon": "plus", + "href": "https://github.com/fosrl/pangolin/discussions" + } + ] + }, + "redirects": [ + { + "source": "/telemetry", + "destination": "/self-host/telemetry" + }, + { + "source": "/community/:slug*", + "destination": "/self-host/:slug*" + } + ], + "seo": { + "metatags": { + "canonical": "https://docs.pangolin.net" + } } - ], - "seo": { - "metatags": { - "canonical": "https://docs.pangolin.net" - } - } -} +} \ No newline at end of file diff --git a/images/hero-dark.png b/images/hero-dark.png deleted file mode 100644 index a61cbb1..0000000 Binary files a/images/hero-dark.png and /dev/null differ diff --git a/images/hero.png b/images/hero.png new file mode 100644 index 0000000..f42a830 Binary files /dev/null and b/images/hero.png differ diff --git a/images/mac-client-preferences.png b/images/mac-client-preferences.png new file mode 100644 index 0000000..7645da2 Binary files /dev/null and b/images/mac-client-preferences.png differ diff --git a/images/private_access_controls.png b/images/private_access_controls.png new file mode 100644 index 0000000..853c143 Binary files /dev/null and b/images/private_access_controls.png differ diff --git a/index.mdx b/index.mdx index ce851e4..1ee76a1 100644 --- a/index.mdx +++ b/index.mdx @@ -2,24 +2,40 @@ title: "Introduction to Pangolin" --- -Pangolin is an open-source and identity-aware tunneled reverse proxy server. Pangolin's distributed architecture with nodes provide highly available ingress to ensure applications always remain accessible. +Pangolin is an open-source, identity-based remote access platform built on WireGuard that enables secure, seamless connectivity to private and public resources. - Pangolin Dashboard + Pangolin Dashboard -Pangolin establishes secure connections from edge networks to nodes, bypassing the need for public inbound ports and complex firewall configurations. Pangolin is incredibly useful for exposing local services, IoT devices, or internal applications to the internet without direct exposure, enhancing security by reducing attack surface and simplifying network management. Additionally, Pangolin acts as an identity-aware proxy by authenticating every request against admin-defined access controls and rules. +Pangolin combines reverse proxy and VPN capabilities into one platform. It provides browser-based access to web applications and client-based access to private resources like databases and SSH servers, all with zero-trust security and granular access control. + +Pangolin connects remote networks using lightweight software connectors called sites. Sites create secure tunnels without requiring public IP addresses or open ports. Admins define specific resources that users can access, not entire networks. This gives users only the access they need while keeping everything else secure. + +Users access public resources through any web browser with authentication. Users access private resources by connecting with a Pangolin client on their device. Both methods use the same identity-based access control, so you manage users and permissions in one place. + +## Keep Reading + + + Learn about the fundamentals of Pangolin and how they work together to provide simple and secure remote access. + + + + What are the similarities and differences between Pangolin and traditional reverse proxies and VPNs? + + +## Deployment Options - Use Cloud for a highly available and access-controlled ingress service with nodes all over the world. Optionally self-host a node to keep your traffic private. + Use Cloud for low-maintenance, highly available remote access. Optionally self-host a node to keep your traffic private. Self-host a fully isolated Pangolin server. Install the Community Edition or Enterprise Edition easily using the quick installer. -## What is a fossorial animal? +## What is a Fossorial Animal? The Pangolin system is made up of many components, all with unique animal names. These animals are called fossorial animals. diff --git a/manage/access-control/rules.mdx b/manage/access-control/rules.mdx index 630695a..8e2f471 100644 --- a/manage/access-control/rules.mdx +++ b/manage/access-control/rules.mdx @@ -5,12 +5,12 @@ description: "Configure rules to allow or deny access to resources without authe Rules allow you to either "allow" and bypass the Pangolin auth system (no pin, login, password), or "deny" and fully reject the request. After you create a resource you can select the "Rules" tab on the sidebar and enable rules. - - + + Bypass authentication completely for matching requests. Users can access resources without any login or PIN. - + Completely reject requests that match the rule. Useful for blocking admin paths or sensitive endpoints. diff --git a/manage/blueprints.mdx b/manage/blueprints.mdx index ae5dd31..abbdb08 100644 --- a/manage/blueprints.mdx +++ b/manage/blueprints.mdx @@ -1,5 +1,6 @@ --- title: "Blueprints" +icon: "file-code" description: "Pangolin Blueprints are declarative configurations that allow you to define your resources and their settings in a structured format" --- @@ -60,12 +61,12 @@ YAML config can be applied using Docker labels, API, from a Newt site, or in the -### Proxy Resources +### Public Resources -Proxy resources are used to expose HTTP, TCP, or UDP services through Pangolin. Below is an example configuration for proxy resources: +Public resources are used to expose HTTP, TCP, or UDP services through Pangolin. Below is an example configuration for public resources: ```yaml -proxy-resources: +public-resources: resource-nice-id-uno: name: this is a http resource protocol: http @@ -115,7 +116,7 @@ Authentication is off by default. You can enable it by adding the relevant field ```yaml -proxy-resources: +public-resources: secure-resource: name: Secured Resource protocol: http @@ -141,7 +142,7 @@ proxy-resources: You can define simplified resources that contain only target configurations. This is useful for adding targets to existing resources or for simple configurations: ```yaml -proxy-resources: +public-resources: additional-targets: targets: - site: another-site @@ -158,19 +159,32 @@ proxy-resources: When using targets-only resources, the `name` and `protocol` fields are not required. All other resource-level validations are skipped for these simplified configurations. -### Client Resources +### Private Resources -Client resources define proxied resources accessible when connected via an Olm client: +Private resources define proxied resources accessible when connected via an client: ```yaml -client-resources: - client-resource-nice-id-uno: - name: this is my resource - protocol: tcp - proxy-port: 3001 - hostname: localhost - internal-port: 3000 +private-resources: + private-resource-nice-id-uno: + name: SSH Server + mode: host + destination: 192.168.1.100 site: lively-yosemite-toad + roles: + - Developer + - DevOps + users: + - user@example.com + machines: + - machine-id-1 + - machine-id-2 + private-resource-nice-id-duo: + name: Internal Network + mode: cidr + destination: 10.0.0.0/24 + site: lively-yosemite-toad + users: + - admin@example.com ``` ## Docker Labels Format @@ -219,25 +233,25 @@ services: image: nginxdemos/hello container_name: nginx1 labels: - # Proxy Resource Configuration - - pangolin.proxy-resources.nginx.name=nginx - - pangolin.proxy-resources.nginx.full-domain=nginx.fosrl.io - - pangolin.proxy-resources.nginx.protocol=http - - pangolin.proxy-resources.nginx.headers[0].name=X-Example-Header - - pangolin.proxy-resources.nginx.headers[0].value=example-value + # Public Resource Configuration + - pangolin.public-resources.nginx.name=nginx + - pangolin.public-resources.nginx.full-domain=nginx.fosrl.io + - pangolin.public-resources.nginx.protocol=http + - pangolin.public-resources.nginx.headers[0].name=X-Example-Header + - pangolin.public-resources.nginx.headers[0].value=example-value # Target Configuration - the port and hostname will be auto-detected - - pangolin.proxy-resources.nginx.targets[0].method=http - - pangolin.proxy-resources.nginx.targets[0].path=/path - - pangolin.proxy-resources.nginx.targets[0].path-match=prefix + - pangolin.public-resources.nginx.targets[0].method=http + - pangolin.public-resources.nginx.targets[0].path=/path + - pangolin.public-resources.nginx.targets[0].path-match=prefix nginx2: image: nginxdemos/hello container_name: nginx2 labels: # Additional target for the same resource where the port and hostname are explicit - - pangolin.proxy-resources.nginx.targets[1].method=http - - pangolin.proxy-resources.nginx.targets[1].hostname=nginx2 - - pangolin.proxy-resources.nginx.targets[1].port=80 + - pangolin.public-resources.nginx.targets[1].method=http + - pangolin.public-resources.nginx.targets[1].hostname=nginx2 + - pangolin.public-resources.nginx.targets[1].port=80 networks: default: @@ -266,14 +280,14 @@ This will create a resource that looks like the following: ## Configuration Properties -### Proxy Resources +### Public Resources | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| | `name` | string | Conditional | Human-readable name for the resource | Required unless targets-only resource | | `protocol` | string | Conditional | Protocol type (`http`, `tcp`, or `udp`) | Required unless targets-only resource | | `full-domain` | string | HTTP only | Full domain name for HTTP resources | Required for HTTP protocol, must be unique | -| `proxy-port` | number | TCP/UDP only | Port for raw TCP/UDP resources | Required for TCP/UDP, 1-65535, must be unique within proxy-resources | +| `proxy-port` | number | TCP/UDP only | Port for raw TCP/UDP resources | Required for TCP/UDP, 1-65535, must be unique within public-resources | | `ssl` | boolean | No | Enable SSL/TLS for the resource | - | | `enabled` | boolean | No | Whether the resource is enabled | Defaults to `true` | | `host-header` | string | No | Custom Host header for requests | - | @@ -305,7 +319,7 @@ This will create a resource that looks like the following: Health checks can be configured for individual targets to monitor their availability. Add a `healthcheck` object to any target: ```yaml -proxy-resources: +public-resources: monitored-service: name: Monitored Service protocol: http @@ -358,6 +372,7 @@ Not allowed on TCP/UDP resources. | `sso-roles` | array | No | Allowed SSO roles | Cannot include "Admin" role | | `sso-users` | array | No | Allowed SSO usernames | Must be valid usernames | | `whitelist-users` | array | No | Whitelisted user emails | Must be valid email addresses | +| `auto-login-idp` | number | No | Automatic login identity provider ID | Must be a positive integer | ### Rules Configuration @@ -367,19 +382,20 @@ Not allowed on TCP/UDP resources. | `match` | string | Yes | Match type (`cidr`, `path`, `ip`, or `country`) | - | | `value` | string | Yes | Value to match against | Format depends on match type. For `country` match, use `ALL` to match all countries | -### Client Resources +### Private Resources -These are resources used with Pangolin Olm clients (e.g., SSH, RDP). +These are resources used with Pangolin clients (e.g., SSH, RDP). | Property | Type | Required | Description | Constraints | |----------|------|----------|-------------|-------------| -| `name` | string | Yes | Human-readable name for the resource | 2-100 characters | -| `protocol` | string | Yes | Protocol type (`tcp` or `udp`) | - | -| `proxy-port` | number | Yes | Port accessible to clients | 1-65535, must be unique within client-resources | -| `hostname` | string | Yes | Target hostname or IP address | 1-255 characters | -| `internal-port` | number | Yes | Port on the target system | 1-65535 | -| `site` | string | No | Site identifier where the resource is located | 2-100 characters | -| `enabled` | boolean | No | Whether the resource is enabled | Defaults to `true` | +| `name` | string | Yes | Human-readable name for the resource | 1-255 characters | +| `mode` | string | Yes | Resource mode (`host` or `cidr`) | - | +| `destination` | string | Yes | Target IP address, hostname, or CIDR block | For `host` mode: IP address or domain. For `cidr` mode: valid CIDR notation | +| `site` | string | Yes | Site identifier where the resource is located | - | +| `alias` | string | No | Fully qualified domain name alias | Must be a valid FQDN (e.g., example.com). Required when destination is a domain in `host` mode | +| `roles` | array | No | Allowed SSO roles | Cannot include "Admin" role | +| `users` | array | No | Allowed user emails | Must be valid email addresses | +| `machines` | array | No | Allowed machine identifiers | Array of strings | ## Validation Rules and Constraints @@ -392,14 +408,13 @@ These are resources used with Pangolin Olm clients (e.g., SSH, RDP). - **TCP/UDP Protocol**: Must have `proxy-port` and targets must NOT have `method` field - **TCP/UDP Protocol**: Cannot have `auth` configuration -3. **Port Uniqueness**: - - `proxy-port` values must be unique within `proxy-resources` - - `proxy-port` values must be unique within `client-resources` - - Cross-validation between proxy and client resources is not enforced +3. **Alias Uniqueness**: `alias` values must be unique across all private resources within the same blueprint and in the org -4. **Domain Uniqueness**: `full-domain` values must be unique across all proxy resources +4. **Domain Uniqueness**: `full-domain` values must be unique across all public resources -5. **Target Method Requirements**: When protocol is `http`, all non-null targets must specify a `method` +5. **Proxy Port Uniqueness**: `proxy-port` values must be unique per protocol within public resources (e.g., TCP port 3000 and UDP port 3000 can coexist) + +6. **Target Method Requirements**: When protocol is `http`, all non-null targets must specify a `method` ## Common Validation Errors @@ -409,10 +424,10 @@ When working with blueprints, you may encounter these validation errors: The `Admin` role is reserved and cannot be included in the `sso-roles` array for authentication configuration. ### "Duplicate 'full-domain' values found" -Each `full-domain` must be unique across all proxy resources. If you need multiple resources for the same domain, use different subdomains or paths. +Each `full-domain` must be unique across all public resources. If you need multiple resources for the same domain, use different subdomains or paths. -### "Duplicate 'proxy-port' values found" -Port numbers in `proxy-port` must be unique within their resource type (proxy-resources or client-resources separately). +### "Duplicate 'proxy-port' values found in public-resources" +Port numbers in `proxy-port` must be unique per protocol within public-resources (e.g., you can't have two TCP resources using port 3000, but TCP port 3000 and UDP port 3000 can coexist). ### "When protocol is 'http', all targets must have a 'method' field" All targets in HTTP proxy resources must specify whether they use `http`, `https`, or `h2c`. @@ -425,3 +440,14 @@ Authentication is only supported for HTTP resources, not TCP or UDP. ### "Resource must either be targets-only or have both 'name' and 'protocol' fields" Resources must either contain only the `targets` field (targets-only) or include both `name` and `protocol` for complete resource definitions. + +### "Duplicate 'alias' values found in private-resources" +Alias values in private resources must be unique within the blueprint. + +### "Destination must be a valid IP address or valid domain AND alias is required" +For private resources in `host` mode, the destination must be a valid IP address or domain. When using a domain, an `alias` field is required. +### "Destination must be a valid CIDR notation for cidr mode" +For private resources in `cidr` mode, the destination must be a valid CIDR notation (e.g., 10.0.0.0/24). + +### "Admin role cannot be included in roles" +The `Admin` role is reserved and cannot be included in the `roles` array for private resource configuration. \ No newline at end of file diff --git a/manage/branding.mdx b/manage/branding.mdx index bc5736c..5d25819 100644 --- a/manage/branding.mdx +++ b/manage/branding.mdx @@ -1,5 +1,6 @@ --- title: "Branding" +icon: "brush" description: "Learn how to customize the look your Pangolin dashboard and login pages with custom branding" --- @@ -25,8 +26,6 @@ branding: light_path: "/branding/logo-light.svg" dark_path: "/branding/logo-dark.svg" - favicon_path: "/branding/favicon.ico" - colors: light: primary: "hsl(212, 65%, 35%)" @@ -73,6 +72,16 @@ All branding configuration options are optional. Only specify the sections you w **Example**: `"MyApp"` +### Favicon + +To customize the favicon, mount your favicon to `/app/public/favicon.ico` in the container. + +```yaml title="docker-compose.yml" +volumes: + - ./config:/app/config + - ./branding/favicon.ico:/app/public/favicon.ico +``` + ### Background Image @@ -168,18 +177,6 @@ All branding configuration options are optional. Only specify the sections you w -### Favicon - - - Path to a custom favicon. - - **Example**: `"/branding/favicon.ico"` - - - Requires mounting a volume to `/app/public`. - - - ### Footer @@ -209,12 +206,6 @@ All branding configuration options are optional. Only specify the sections you w Custom text for the login page. - - The main title text displayed on the login page. - - **Example**: `"Welcome Back!"` - - The subtitle text displayed below the title. @@ -229,12 +220,6 @@ All branding configuration options are optional. Only specify the sections you w Custom text for the signup page. - - The main title text displayed on the signup page. - - **Example**: `"Create Your Account"` - - The subtitle text displayed below the title. diff --git a/manage/clients/add-client.mdx b/manage/clients/add-client.mdx deleted file mode 100644 index ae028c2..0000000 --- a/manage/clients/add-client.mdx +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: "Add Client" -description: "Create a client to connect to your Pangolin network from a remote computer" ---- - -A client in Pangolin is a way to create a traditional VPN tunnel from your remote computer to your Newt site on your private network. Clients allow you to tunnel your computer back into your whole network and remotely access non-HTTP resources like file shares or use it as a bastion host to manage servers. - - -Client support in Pangolin is still in beta - things may not perform as expected. If you encounter bugs please report them on [GitHub in an issue](https://github.com/fosrl/pangolin). - - -## How Clients Work - -### The Connection Process - -1. **Client Creation**: You create a client in Pangolin's dashboard -2. **Olm Registration**: Olm registers with Pangolin using the client credentials -3. **Tunnel Establishment**: Olm establishes a WireGuard tunnel to your network -4. **Resource Access**: You can access resources on your private network through the tunnel - -### What Clients Are - -- A way to tunnel your computer back into your whole network -- Remotely access non HTTP resources like file shares -- A bastion host or "jump box" to manage servers - -### What Pangolin Clients Are Not (Yet) - -- A mesh VPN like Tailscale, Netbird, or Netmaker -- A slick desktop UI (coming soon) - -You can install the [Olm](https://github.com/fosrl/olm) client on your computer and run it with the ID and secret values you generate in the dashboard. When it connects, it will create a virtual network adapter on your computer just like a traditional VPN. - -[Take a look at a quick video about clients](https://youtu.be/jg8Bb05hlnI) - -## Prerequisites - -Before adding a client, ensure you have: - -1. **Updated Components**: Make sure you have the required versions: - - Pangolin ^1.8.0 - - Gerbil ^1.1.0 - - Newt ^1.4.0 - -2. **Site Configuration**: Your Newt site must be configured to accept clients with the `--accept-clients` flag or `ACCEPT_CLIENTS=true` environment variable. - -3. **Port Configuration**: Ensure port 21820 is open on your VPS and added to your `docker-compose.yml`: - -```yml title="docker-compose.yml" highlight={4} -gerbil: - ports: - - 51820:51820/udp - - 21820:21820/udp - - 443:443 - - 80:80 -``` - -## Adding a Client - - - - In the Pangolin dashboard, go to the **Clients** section and click **Add Client**. - - - - Configure the basic information: - - **Client Name**: A descriptive name for your client - - - - Pangolin will generate: - - **Client ID**: Unique identifier for the Olm client - - **Secret**: Authentication secret for secure connection - - **Endpoint**: The Pangolin server endpoint - - - - Use the generated credentials to install and configure Olm on your remote computer. See [Install Olm](/manage/clients/install-client) for detailed instructions. - - - - Create [client resources](/manage/resources/client-resources) for what you would like to access through the client. For example, to SSH into a server, create a resource like `22:localhost:22`. - - - - Once Olm is running, the client status should show as "Online" in the dashboard. You can then connect to your network using the site's IP address. - - - -## Client Modalities - -Clients have two major operation modalities: - -### Relaying (Default) - -By default, Olm will relay traffic through your Pangolin VPS - through Gerbil specifically. Gerbil listens on UDP port 21820 for new WireGuard connections and forwards the packets down the Newt site tunnels to the right peers. This means your connections back to your site do not require firewall config and uses the existing NAT holepunching capabilities of Newt. - -### NAT Hole Punching (Experimental) - - -Right now NAT hole punching is EXPERIMENTAL. While functional, it does not always connect reliably and can fall back to relaying. We plan to work to improve the reliability over time by implementing more methods for those behind CGNAT or hard nats. - -Take a look at [Tailscale docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make to improve HP performance. - - -This mode can be activated by using `--holepunch` in Olm. Instead of immediately relaying through the VPS, this will attempt to connect directly to the Newt site across NAT routers. - -This should help to: -- Increase performance (speed/bandwidth) -- Reduce VPS transit costs - -## Site Modalities - -Sites have two operating modalities when accepting clients: - -### Proxy Mode - -When you run Newt with `--accept-clients` it will run fully in user space. This means you do not need to give the container or binary any special permissions. It will NOT create a virtual network interface on the host. Instead you should create [client resources](/manage/resources/client-resources) in Pangolin to configure what ports clients can hit and where they should go. - -### Native Mode - - -Right now native mode only works on Linux. - - -In native mode with both `--accept-clients` and `--native`, Newt will create a native Linux tunnel interface on the host. This means that all traffic destined for the site can access anything on the host. - -#### Remote Subnets - -In native mode, you can add remote subnets to the site settings in Pangolin to forward remote networks through Newt. This can let Newt act as a traditional VPN server to route to anything on your local network. - - - Remote Subnets - - -This will configure a route on the Olm side of the tunnel to route this subnet down the tunnel. When it reaches the other end, can be routed to the appropriate destination by the host. - -This requires proper Linux routing configuration. Here's what happens in native mode: - -1. **Olm forwards packets**: Your computer running Olm blindly forwards all packets destined for the remote subnet (e.g., 192.168.0.x) over the tunnel -2. **Newt receives packets**: Newt creates a WireGuard network interface on the Linux host and receives these packets -3. **Linux must route packets**: The Linux machine needs to know what to do with packets destined for 192.168.0.x - -#### Required Configuration - -**Enable IP forwarding:** -```bash -sudo nano /etc/sysctl.conf - -net.ipv4.ip_forward = 1 -``` - -**Setup NAT masquerading:** -```bash -sudo iptables -t nat -A POSTROUTING -j MASQUERADE -``` - -This rewrites the source address of packets from the tunnel to be the 192.168.0.x address of the Linux instance when packets leave the instance. This way, when devices on 192.168.0.x reply to the Olm client, they know to send the response back through the tunnel. - -#### Troubleshooting Routing Issues - -If you can connect to Newt (peer shows as connected in logs) but can't reach remote subnet resources: - -1. **Check if packets reach the destination**: The connection to Newt is working, so this is likely a routing issue -2. **Verify forwarding is enabled**: Use `sysctl net.ipv4.ip_forward` to confirm it's set to 1 -3. **Check iptables rules**: Ensure NAT masquerading is configured -4. **Consider using proxy mode**: [Client resources](/manage/resources/client-resources) can be easier as Newt handles the proxying, though you'll need to address everything as the Newt IP and assign specific ports - - -NAT masquerading can affect other services on the Linux instance, so be aware of potential conflicts with existing network configurations. - - -## Notes - -- Clients require Olm to be running on the remote computer -- Each client can access multiple resources on the site -- Connection status is monitored automatically -- Olm creates a native tun interface and usually requires sudo/admin permissions -- On Windows: Olm will run as a service -- LXC containers need to be configured to allow tun access diff --git a/manage/clients/configure-client.mdx b/manage/clients/configure-client.mdx index a7d5633..c908687 100644 --- a/manage/clients/configure-client.mdx +++ b/manage/clients/configure-client.mdx @@ -1,25 +1,23 @@ --- -title: "Configure Client" +title: "Configure Clients" description: "Configure Olm for connecting to Pangolin clients" --- -Olm is a WireGuard client designed to securely connect your remote computer to your Pangolin network. By using Olm, you can create a traditional VPN tunnel that allows you to access resources on your private network from anywhere. +## Mac and Windows -## How Olm Works +Each respective client has a preferences window with all currently available configuration parameters like DNS override and preferred DNS servers. In your desktop client, click the menu bar or system tray icon, select More in the menu, and click Preferences. -### Registers with Pangolin + + + -Using the Olm ID and a secret, the client will make HTTP requests to Pangolin to receive a session token. Using that token, it will connect to a websocket and maintain that connection. Control messages will be sent over the websocket. +## Pangolin CLI -### Establishes WireGuard Tunnel +Refer to the [documentation in the official repository](https://github.com/fosrl/cli/blob/main/docs/pangolin.md) for the available commands, default values, and more. -When Olm receives WireGuard control messages, it will use the information encoded (endpoint, public key) to bring up a WireGuard tunnel using native system interfaces. It will ping over the tunnel to ensure the peer on the Gerbil side is brought up. +## Olm CLI -### Creates Virtual Network Interface - -Olm creates a virtual network adapter on your computer just like a traditional VPN. This allows you to access resources on your private network as if you were physically connected to it. - -## Configuration Arguments +### Flags Olm ID generated by Pangolin to identify the client. @@ -43,18 +41,32 @@ Olm creates a virtual network adapter on your computer just like a traditional V **Example**: `https://pangolin.example.com` + + Organization ID to connect to. + + + + User authentication token. + + - MTU for the WireGuard interface. + MTU for the internal WireGuard interface. **Default**: `1280` - DNS server to use for resolving the endpoint. + DNS server to use to resolve the endpoint. **Default**: `8.8.8.8` + + Upstream DNS server(s), comma-separated. + + **Default**: `8.8.8.8:53` + + The log level to use for Olm output. @@ -75,68 +87,56 @@ Olm creates a virtual network adapter on your computer just like a traditional V **Default**: `5s` - - Enable NAT hole punching mode instead of relaying through the VPS. + + Name of the WireGuard interface. + + **Default**: `olm` + + + + Enable API server for receiving connection requests. **Default**: `false` - - - This is EXPERIMENTAL. While functional, it does not always connect reliably and can fall back to relaying. - - - Path to a configuration file containing the same arguments as command line. + + HTTP server address (e.g., ':9452'). - **Example**: `/etc/olm/config.yaml` + **Default**: `:9452` -## Configuration Examples + + Unix socket path (or named pipe on Windows). + + **Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows) + -### Basic Configuration + + Disable hole punching. + + **Default**: `false` + -```bash -olm \ ---id 31frd0uzbjvp721 \ ---secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ ---endpoint https://example.com -``` + + Override system DNS settings. + + **Default**: `false` + -### With Hole Punching + + Disable relay connections. + + **Default**: `false` + -```bash -olm \ ---id 31frd0uzbjvp721 \ ---secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ ---endpoint https://example.com \ ---holepunch -``` - -### With Custom MTU and DNS - -```bash -olm \ ---id 31frd0uzbjvp721 \ ---secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ ---endpoint https://example.com \ ---mtu 1400 \ ---dns 1.1.1.1 -``` - -### With Health Check - -```bash -olm \ ---id 31frd0uzbjvp721 \ ---secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ ---endpoint https://example.com \ ---health-file /tmp/olm-health -``` - -## Environment Variables +### Environment Variables All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables are particularly useful when running Olm in containerized environments. + +When both environment variables and CLI arguments are provided, CLI arguments take precedence. + + Endpoint of your Pangolin server (equivalent to `--endpoint`) @@ -149,79 +149,141 @@ All CLI arguments can be set using environment variables as an alternative to co Olm secret for authentication (equivalent to `--secret`) - - MTU for the WireGuard interface (equivalent to `--mtu`) + + Organization ID to connect to (equivalent to `--org`) + + + + User authentication token (equivalent to `--user-token`) + + + + MTU for the internal WireGuard interface (equivalent to `--mtu`) **Default**: `1280` - - DNS server to use for resolving the endpoint (equivalent to `--dns`) + + DNS server to use to resolve the endpoint (equivalent to `--dns`) **Default**: `8.8.8.8` - + + Upstream DNS server(s), comma-separated (equivalent to `--upstream-dns`) + + **Default**: `8.8.8.8:53` + + + Log level (equivalent to `--log-level`) **Default**: `INFO` - + Interval for pinging the server (equivalent to `--ping-interval`) **Default**: `3s` - + Timeout for each ping (equivalent to `--ping-timeout`) **Default**: `5s` - - Enable NAT hole punching mode (equivalent to `--holepunch`) + + Name of the WireGuard interface (equivalent to `--interface`) + + **Default**: `olm` + + + + Enable API server for receiving connection requests (equivalent to `--enable-api`) + + Set to "true" to enable **Default**: `false` - - Path to health file for connection monitoring (equivalent to `--health-file`) + + HTTP server address (equivalent to `--http-addr`) + + **Default**: `:9452` - - Load the config from this file instead of command line arguments (equivalent to `--config-file`) + + Unix socket path or Windows named pipe (equivalent to `--socket-path`) + + **Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows) - -When both environment variables and CLI arguments are provided, CLI arguments take precedence. - + + Disable hole punching (equivalent to `--disable-holepunch`) + + Set to "true" to disable + + **Default**: `false` + -## Troubleshooting + + Override system DNS settings (equivalent to `--override-dns`) + + Set to "true" to enable + + **Default**: `false` + -### Connection Issues + + Disable relay connections (equivalent to `--disable-relay`) + + Set to "true" to disable + + **Default**: `false` + -1. **Check credentials**: Ensure the ID and secret are correct -2. **Verify endpoint**: Make sure the endpoint URL is accessible -3. **Check firewall**: Ensure port 21820 is open on your VPS -4. **Verify site configuration**: Make sure your Newt site has `--accept-clients` enabled + + Set to the location of a JSON file to load secret values + -### Permission Issues +### Loading secrets from files -1. **Linux/macOS**: Run with sudo or ensure proper capabilities -2. **Windows**: Run as administrator or install as a service -3. **LXC containers**: Configure tun device access +You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs. -### Performance Issues +``` +$ cat ~/.config/olm-client/config.json +{ + "id": "spmzu8rbpzj1qq6", + "secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3", + "endpoint": "https://app.pangolin.net", + "org": "", + "userToken": "", + "mtu": 1280, + "dns": "8.8.8.8", + "upstreamDNS": ["8.8.8.8:53"], + "interface": "olm", + "logLevel": "INFO", + "enableApi": false, + "httpAddr": "", + "socketPath": "/var/run/olm.sock", + "pingInterval": "3s", + "pingTimeout": "5s", + "disableHolepunch": false, + "overrideDNS": false, + "disableRelay": false, + "tlsClientCert": "" +} +``` -1. **Try hole punching**: Use `--holepunch` for better performance -2. **Adjust MTU**: Try different MTU values if experiencing packet loss -3. **Check network**: Ensure stable internet connection +This file is also written to when olm first starts up. So you do not need to run every time with --id and secret if you have run it once! -## Security Considerations +Default locations: -- Keep your client secret secure and private -- Use HTTPS endpoints only -- Regularly rotate client credentials -- Monitor client connections in the dashboard -- Use firewall rules to restrict access to specific resources +- **macOS**: `~/Library/Application Support/olm-client/config.json` +- **Windows**: `%PROGRAMDATA%\olm\olm-client\config.json` +- **Linux/Others**: `~/.config/olm-client/config.json` + +### API + +Olm can be started with a HTTP or socket API to configure and manage it. See the [API documentation](https://github.com/fosrl/olm/blob/main/API.md) for more details. \ No newline at end of file diff --git a/manage/clients/credentials.mdx b/manage/clients/credentials.mdx new file mode 100644 index 0000000..101e76e --- /dev/null +++ b/manage/clients/credentials.mdx @@ -0,0 +1,52 @@ +--- +title: "Client Credentials" +description: "Understanding how client credentials work and how they can be rotated & regenerated" +--- + +## Understanding Credentials + +Every machine client is provisioned with a unique identifier (ID), secret, and endpoint. The client uses the combination of these three to establish a secure, encrypted connection to the server. + +User devices use a special combination of credentials and temporary session tokens tied to the user account. Therefore, these credentials are obscured and can not be regenerated for user devices. To invalidate a user device, the user should logout via the client of choice. + +### ID + +Example: `ln8yqs6w85la5zg` + +The ID represents the client connection in the system. Every machine client has an ID. + +This value is not a secret and it is okay if made publically available. + +### Secret + +Example: `tfpwoc580jf1l1glfagix0o97p8kirjogdflqg604n0tr3to` + +The secret represents the "password" of the client. This secret must match the secret hashed in the system for the relevant ID. + + +This is a _secret_! Only share it with trusted people and be sure to store it safely and securely. + + +When the client connects, it uses this secret as a first handshake with the server. The server then passes temporary session credentials back to the site before it can initiate a websocket connection. Once the websocket connection is established, ephemeral keys are used to establish tunnels using WireGuard. + +### Endpoint + +Example: `https://app.pangolin.net` or `https://pangolin.my-server.com` + +The endpoint is how the client knows which server to connect to. This is the fully qualified hostname of the Pangolin server (the URL you use to access the dashboard). For Pangolin cloud, the endpoint is `https://app.pangolin.net`. The client uses this endpoint ot establish a websocket connection and receive control messages from the server. + +## Rotating and Regenerating Credentials + + +This is an Enterprise Edition only feature. + + +Client credentials can be regenerated. Regenerating credentials will completely invalidate the previous ID and secret. Use this feature if you have lost the secret and need to reset the credentials, or if you wish to rotate credentials on a regular basis for extra security. + +To regenerate credentials, visit Clients > Machines > Your Client > Credentials in the Pangolin admin dashboard. + +### Regenerate vs. Regenerate and Disconnect + +Regenerate simply recreates the credentials and invalidates the old ones. The client will remain connected until you restart it with the new credentials. + +Regenerate and Disconnect recreates the credentials and invalides the old ones. The client will instantly disconnect and will require you to restart it with the new credentials. diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index fd5a2c5..ed21841 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -1,25 +1,138 @@ --- -title: "Install Client" -description: "Install Olm as a binary" +title: "Install Clients" +description: "Install native clients for Mac, Windows, and Linux" --- -Olm can be installed as either a static binary executable or a Docker container. Configuration is passed via CLI arguments in both cases. +## Windows - -You **must first create a client and copy the Olm config** in Pangolin before running Olm. - +- [Pangolin for Windows Installer](https://pangolin.net/downloads/windows) - This is the official page to download the latest installer file for Windows. +- [All Versions](https://github.com/fosrl/windows/releases) - The releases section of this repository contains release notes and download artifacts for the latest version and all older versions. -## Binary Installation +### Installation Steps + +1. **Download and install the Pangolin client** + + Download and install the Pangolin client using the official .msi installer from the download button above. + +2. **Launch Pangolin** + + Open Pangolin from the Start menu or the shortcut on your Desktop. + +3. **Log in with your Pangolin account** + + Log in on your Pangolin Cloud account or your self-hosted Pangolin instance. + + - Click the Pangolin icon in the task bar's system tray and select Log in. + +## Mac + +- [Pangolin for macOS Installer](https://pangolin.net/downloads/mac) - This is the official page to download the latest installer file for macOS. +- [All Versions](https://github.com/fosrl/apple/releases) - The releases section of this repository contains release notes and download artifacts for the latest version and all older versions. + +### Installation Steps + +1. **Download and install the Pangolin client** + + Download and install the Pangolin client using the official .dmg installer from the download button above. + + - Open the downloaded .dmg file + - Drag and drop Pangolin.app into your Applications folder + +2. **Launch Pangolin** + + Open Pangolin from your Applications folder. + +3. **Install the VPN configuration** + + Follow the Pangolin onboarding flow, which will guide you to install the Pangolin VPN configuration. + + - Select Open System Settings on startup when it asks to install a network extension. + - In System Settings, under General > Login Items & Extension > By Category > Network Extensions, ensure that Pangolin.app is toggled on. + - Select Allow when Pangolin asks to add a VPN configuration. + +4. **Log in with your Pangolin account** + + Log in on your Pangolin Cloud account or your self-hosted Pangolin instance. + + - Click the Pangolin icon in the menu bar and select Log in. + +## Pangolin CLI (Linux) + +Pangolin CLI is the recommended way to run a client using a command line interface on Mac or Linux. Support for Windows is coming soon. + +Pangolin CLI supports running as user device with authentication or a machine client. ### Quick Install (Recommended) +Use this command to automatically install Pangolin CLI. It detects your system architecture automatically and always pulls the latest version, adding `pangolin` to your PATH: + +```bash +curl -fsSL https://static.pangolin.net/get-cli.sh | bash +``` + +### Manual Download + +Binaries for Linux and macOS are available in the [GitHub releases](https://github.com/fosrl/cli/releases) for ARM and AMD64 (x86_64) architectures. + +Download and install manually: + +```bash +wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin +``` + + +Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information. + + +### Installation Steps + +1. **Download and install the Pangolin client** + + Install Pangolin using the installation script: + + ```bash + curl -fsSL https://static.pangolin.net/get-cli.sh | bash + ``` + +2. **Log in with your Pangolin account** + + Log in on your Pangolin Cloud account or your self-hosted Pangolin instance: + + ```bash + pangolin login + ``` + +3. **Start Pangolin** + + Connect Pangolin by running: + + ```bash + pangolin up + ``` + +## Olm CLI + +Olm CLI is the most basic form of a client. All other clients implement Olm under the hood in some form. + +If you're looking for a CLI interface for a client, we recommend using Pangolin CLI where possible. + +Olm CLI is mainly only used for machine clients. Though the Pangolin CLI can also be used for machine clients, use Pangolin CLI if you expect to log in as a user. + +### Binary Installation (Linux) + +#### Quick Install (Recommended) + Use this command to automatically install Olm. It detects your system architecture automatically and always pulls the latest version, adding Olm to your PATH: ```bash -curl -fsSL https://pangolin.net/get-olm.sh | bash +curl -fsSL https://static.pangolin.net/get-olm.sh | bash ``` -### Manual Download +#### Windows + +If you would like to use Olm on Windows, wintun.dll is required. Please use latest installer from [GitHub releases](https://github.com/fosrl/olm/releases/latest).V + +#### Manual Download Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/olm/releases) for ARM and AMD64 (x86_64) architectures. @@ -44,18 +157,6 @@ olm \ --endpoint https://example.com ``` -### Permanent Installation - -Install to your PATH (may need to run as root): - -```bash -mv ./olm /usr/local/bin -``` - - -The quick installer will do this step for you. - - ### Systemd Service Create a basic systemd service: @@ -78,11 +179,52 @@ WantedBy=multi-user.target Make sure to move the binary to `/usr/local/bin/olm` before creating the service! -## Windows Service +### Docker + +You can also run it with Docker compose. For example, a service in your `docker-compose.yml` might look like this using environment vars (recommended): + +```yaml +services: + olm: + image: fosrl/olm + container_name: olm + restart: unless-stopped + network_mode: host + devices: + - /dev/net/tun:/dev/net/tun + environment: + - PANGOLIN_ENDPOINT=https://example.com + - OLM_ID=31frd0uzbjvp721 + - OLM_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 +``` + +You can also pass the CLI args to the container: + +```yaml +services: + olm: + image: fosrl/olm + container_name: olm + restart: unless-stopped + network_mode: host + devices: + - /dev/net/tun:/dev/net/tun + command: + - --id 31frd0uzbjvp721 + - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 + - --endpoint https://example.com +``` + +**Docker Configuration Notes:** + +- `network_mode: host` brings the olm network interface to the host system, allowing the WireGuard tunnel to function properly +- `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating WireGuard interfaces + +### Windows Service On Windows, olm has to be installed and run as a Windows service. When running it with the cli args, it will attempt to install and run the service to function like a cli tool. You can also run the following: -### Service Management Commands +#### Service Management Commands ``` # Install the service @@ -109,15 +251,15 @@ olm.exe help Note running the service requires credentials in `%PROGRAMDATA%\olm\olm-client\config.json`. -### Service Configuration +#### Service Configuration When running as a service, Olm will read configuration from environment variables or you can modify the service to include command-line arguments: 1. Install the service: `olm.exe install` -2. Set the credentials in `%PROGRAMDATA%\olm\olm-client\config.json`. Hint: if you run olm once with --id and --secret this file will be populated! +2. Set the credentials in `%PROGRAMDATA%\olm\olm-client\config.json`. Hint: if you run olm once with --id and --secret this file will be populated! 3. Start the service: `olm.exe start` -### Service Logs +#### Service Logs When running as a service, logs are written to: @@ -130,11 +272,21 @@ You can view the Windows Event Log using Event Viewer or PowerShell: Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10 ``` -## Gotchas +### Gotchas Olm creates a native tun interface. This usually requires sudo / admin permissions. Some notes: - **Windows**: Olm will run as a service. You can use the commands described [Configure Client](/manage/clients/configure-client) to manage it. You can use this to run it in the background if needed! -- **LXC containers**: Need to be configured to allow tun access. See [Tailscale's guide](https://tailscale.com/kb/1130/lxc-unprivileged). +- **LXC containers**: Need to be configured to allow tun access. On Proxmox see below. - **Linux**: May require root privileges or specific capabilities to create tun interfaces. - **macOS**: May require additional permissions for network interface creation. + +#### LXC Proxmox + +1. Create your LXC container. +2. Go to the Resources tab of the container. +3. Select Add. Then select Device Passthrough. +4. On the Add Device prompt, enter dev/net/tun in the Device Path field and select Add. +5. If the container is running, shut it down and start it up again. + +Once /dev/net/tun is available, the olm can run within the LXC. diff --git a/manage/clients/understanding-clients.mdx b/manage/clients/understanding-clients.mdx new file mode 100644 index 0000000..5c7752d --- /dev/null +++ b/manage/clients/understanding-clients.mdx @@ -0,0 +1,70 @@ +--- +title: "Understanding Clients" +description: "Create a client to connect to your Pangolin network from a remote computer" +--- + +A client is a way to access resources on sites remotely and privately via a virtual private network. Clients are used with private resources to faciliate zero-trust network access. + +By default a client does not have access to any hosts on the local network of the site. Admins must explicitely define resources on the site and give specific users and roles access to the resources. + +Users must log in and connect from a Pangolin client for [Window, Mac, and Linux](/manage/clients/install-client). Machine (automated systems and servers) connect with an ID and secret. + +## Client Types + +There are two types of clients: user devices and machines. + + + + - Associated with a user in your Pangolin organization + - Requires login to connect (password, 2fa, etc) + - Available for download on Mac, Windows, and Linux + + + + - Represent a server or automated system instead of a user + - Connect with an ID and secret + - Available in CLI form with Pangolin CLI or Olm CLI + + + +### User Devices + +A user may download a client for their specific system. Before they can connect, they must select a Pangolin server to authenticate to using their provided Pangolin account. Users can log in as a Pangolin user or with your attached external identity provider. + +Examples include: + +- **SSH**: Admins and developers can connect with their client to specific hosts for SSH. +- **RDP**: Users can connect to a remote host using familiar remote desktop software. + +Then, just like in the Pangolin dashboard, a user selects the organization to connect to. Once connected, all resources made available to the user in that organization become available via the tunnel. + +### Machines + +Machine clients are for servers and automated systems that are not associated with a specific user. + +Examples include: + +- **CICD**: Access remote resources like a database in an automated deployment pipeline. +- **Servers**: Provide a VPS with access to a resource running in a different network. + +Though you may connect a server via a user account using a CLI client, we reccomend you specifically use a machine client. + +Machine clients authenticate with an ID and secret string. These credentials are passed via arguments into one of the supported Pangolin CLI clients. They can be revoked and rotated. + +## Client Modalities + +Clients have two major operation modalities. A client will first attempt to hole punch before falling back to relaying. + +### Relaying + +Clients can relay traffic through a Pangolin server - through Gerbil specifically. Gerbil listens on UDP port 21820 for new WireGuard connections and forwards the packets down the Newt site tunnels to the right peers. This means your connections back to your site do not require firewall config and uses the existing NAT holepunching capabilities of Newt. + +### NAT Hole Punching + +While functional, it does not always connect reliably and can fall back to relaying. We plan to work to improve the reliability over time by implementing more methods for those behind CGNAT or hard nats. + +Take a look at [some things you can do to improve reliability](/manage/sites/configure-site#nat-traversal-tweaks) if you are not getting reliable hole punching. + +This should help to: +- Increase performance (speed/bandwidth) +- Reduce VPS transit costs diff --git a/manage/clients/update-client.mdx b/manage/clients/update-client.mdx new file mode 100644 index 0000000..61fd03e --- /dev/null +++ b/manage/clients/update-client.mdx @@ -0,0 +1,73 @@ +--- +title: "Update Clients" +description: "Update your installed client to the latest version" +--- + +## Mac and Windows + +### Automatic Updates (Recommended) + +The desktop clients for Mac and Windows will periodically check for updates in the background. When an update is available, they will request permission to update. However, you can manually check for updates in the menu bar or system tray menu, or by restarting the application. + +Once you accept the update, these clients will automatically download the latest version and replace itself on your computer. + +### Manual Updates + +- **Mac**: Find the latest version in the [GitHub releases](https://github.com/fosrl/apple/releases). +- **Windows**: Find the latest version in the [GitHub releases](https://github.com/fosrl/windows/releases). + +You can download the latest installer files and restart the installation process to install the latest version. Visit [https://pangolin.net/downloads](https://pangolin.net/downloads) to find the latest official installers for your platform. + +## Pangolin CLI + +Find the latest version in the [GitHub releases](https://github.com/fosrl/cli/releases). + +### Automatic Updates (Recommended) + +If you already have Pangolin CLI installed, use the update command: + +```bash +pangolin update +``` + +Or you can re-run the installation script: + +```bash +curl -fsSL https://static.pangolin.net/get-cli.sh | bash +``` + +### Manual Updates + +Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/cli/releases) and replace your existing binary. + +```bash +wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin +``` + + +Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information. + + +## Olm CLI + +Find the latest version in the [GitHub releases](https://github.com/fosrl/olm/releases). + +### Automatic Updates (Recommended) + +If you used the auto installer, simply run it again: + +```bash +curl -fsSL https://static.pangolin.net/get-olm.sh | bash +``` + +### Manual Updates + +Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/olm/releases) and replace your existing binary. + +```bash +wget -O olm "https://github.com/fosrl/olm/releases/download/{version}/olm_{architecture}" && chmod +x ./olm +``` + + +Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/olm/releases) for the latest information. + diff --git a/manage/domains.mdx b/manage/domains.mdx index 0798641..41caee1 100644 --- a/manage/domains.mdx +++ b/manage/domains.mdx @@ -1,5 +1,6 @@ --- title: "Domains" +icon: "globe" description: "Learn how to configure domains for your Pangolin resources and understand the different domain types available" --- @@ -72,6 +73,10 @@ You then access your resources via subdomains like `app.example.com` or `db.exam ### For Domain Delegation + +Some domain providers, namely Cloudflare, do not allow adding NS records for the root of your domain. This would prevent you from delegating all `*.example` to Pangolin. However, you can usually delegate everything after the first level, like `*.subdomain.example.com`. If your provider restricts you in this way, you could either move your domain, or use CNAME records for individual subdomains of the root domain. + + When using domain delegation, you'll need to update your domain's nameservers: **Example NS Records:** @@ -99,7 +104,3 @@ Type: CNAME Name: _acme-challenge.test.example.com Value: _acme-challenge.0nbn5rpcq4wthq6.cname.pangolin.net ``` - - -Once DNS is properly configured and propagated, your domain will be verified and ready to use with your Pangolin resources. - diff --git a/manage/healthchecks-failover.mdx b/manage/healthchecks-failover.mdx index c6b2491..2da4191 100644 --- a/manage/healthchecks-failover.mdx +++ b/manage/healthchecks-failover.mdx @@ -1,20 +1,9 @@ --- title: "Health Checks" -description: "Configure automated health monitoring and failover for high availability" +description: "Configure automated health monitoring and failover for resources" --- - - -## Overview - -Pangolin provides automated health checking for [targets](/manage/resources/targets) to ensure traffic is only routed to healthy services. Health checks are essential for building highly available services, as they automatically remove unhealthy targets from traffic routing and load balancing. +Pangolin provides automated health checking for targets to ensure traffic is only routed to healthy services. Health checks are essential for building highly available services, as they automatically remove unhealthy targets from traffic routing and load balancing. ## How Health Checks Work @@ -22,16 +11,10 @@ Pangolin provides automated health checking for [targets](/manage/resources/targ Health checks operate continuously in the background: -1. **Periodic Checks**: Pangolin sends requests to your target endpoints at configured intervals -2. **Status Evaluation**: Responses are evaluated against your configured criteria -3. **Traffic Management**: Healthy targets receive traffic, unhealthy targets are excluded -4. **Automatic Recovery**: Targets are automatically re-enabled when they become healthy again - -### Health Check vs Target Endpoint - - - The health check endpoint can be the same as your target, but you can also monitor a different endpoint. This allows you to create dedicated health check endpoints that provide more detailed service status information. - +1. **Periodic Checks**: Pangolin sends requests to your target endpoints at configured intervals. +2. **Status Evaluation**: Responses are evaluated against your configured criteria. +3. **Traffic Management**: Healthy targets receive traffic, unhealthy targets are excluded. +4. **Automatic Recovery**: Targets are automatically re-enabled when they become healthy again. ## Target Health States @@ -87,109 +70,45 @@ Targets can exist in three distinct states that determine how traffic is routed: ### Endpoint Configuration - - **Target Endpoint**: The URL or address to monitor for health status - - **Default Behavior**: Usually the same as your target endpoint - - **Custom Endpoints**: Can monitor different endpoints (e.g., `/health`, `/status`) - +- **Target Endpoint**: The URL or address to monitor for health status +- **Default Behavior**: Usually the same as your target endpoint +- **Custom Endpoints**: Can monitor different endpoints (e.g., `/health`, `/status`) ### Timing Configuration - - - **Purpose**: How often to check targets that are currently healthy - - **Typical Range**: 30-60 seconds - - **Consideration**: Less frequent checks reduce overhead - +#### Healthy Interval - - **Purpose**: How often to check targets that are currently unhealthy +- **Purpose**: How often to check targets that are currently healthy +- **Typical Range**: 30-60 seconds +- **Consideration**: Less frequent checks reduce overhead + +#### Unhealthy Interval - **Typical Range**: 10-30 seconds - - **Consideration**: More frequent checks enable faster recovery - - +- **Purpose**: How often to check targets that are currently unhealthy +- **Typical Range**: 10-30 seconds +- **Consideration**: More frequent checks enable faster recovery ### Response Configuration - - **Request Timeout**: Maximum time to wait for a health check response - - **Default Behavior**: Requests exceeding timeout are considered failed - - **Recommended**: Set based on your service's typical response time - +#### Timeout Settings - - **Healthy Codes**: Which HTTP status codes indicate a healthy target - - **Common Settings**: 200, 201, 202, 204 - - **Custom Codes**: Configure based on your service's health endpoint behavior - +- **Request Timeout**: Maximum time to wait for a health check response +- **Default Behavior**: Requests exceeding timeout are considered failed +- **Recommended**: Set based on your service's typical response time -## Failover Behavior +#### HTTP Response Codes -### Automatic Traffic Exclusion - -When a target becomes unhealthy: - - - - Target fails to meet health check criteria (response code, timeout, etc.) - - - - Target status changes from "Healthy" to "Unhealthy" - - - - Target is immediately removed from traffic routing configuration - - - - Load balancing configuration is updated to exclude the unhealthy target - - - - Health checks continue at the unhealthy interval for recovery detection - - - -### Automatic Recovery - -When an unhealthy target recovers: - - - - Target begins responding correctly to health checks - - - - Target status changes from "Unhealthy" to "Healthy" - - - - Target is automatically added back to traffic routing - - - - Load balancing resumes including the recovered target - - +- **Healthy Codes**: Which HTTP status codes indicate a healthy target +- **Common Settings**: 200, 201, 202, 204 +- **Custom Codes**: Configure based on your service's health endpoint behavior ## High Availability Strategies ### Multi-Target Redundancy - - Deploy multiple instances of your service across different targets to ensure availability even when some targets fail. - +#### Service Redundancy + +Deploy multiple instances of your service across different targets to ensure availability even when some targets fail. ``` Resource: web-application @@ -202,9 +121,9 @@ Traffic routes to: Target 1 & Target 3 only ### Cross-Site Failover - - Distribute targets across multiple sites to protect against site-level failures. - +#### Geographic Distribution + +Distribute targets across multiple sites to protect against site-level failures. ``` Resource: api-service diff --git a/manage/integration-api.mdx b/manage/integration-api.mdx index f860bed..0d028aa 100644 --- a/manage/integration-api.mdx +++ b/manage/integration-api.mdx @@ -1,13 +1,16 @@ --- title: "Integration API" +icon: "cube" description: "Learn how to use Pangolin's REST API to automate and script operations with fine-grained permissions" --- + +Pangolin is in heavy development. The REST API routes and behavior may include braking changes between updates. We will do our best to document large changes. + + The API is REST-based and supports many operations available through the web interface. Authentication uses Bearer tokens, and you can create multiple API keys with specific permissions for different use cases. - For Pangolin Community Edition, the integration API must be enabled. Check out [the documentation](/self-host/advanced/integration-api) for how to enable the integration API. - ## Authentication diff --git a/manage/remote-node/quick-install-remote.mdx b/manage/remote-node/quick-install-remote.mdx index fee6bb3..d779e3a 100644 --- a/manage/remote-node/quick-install-remote.mdx +++ b/manage/remote-node/quick-install-remote.mdx @@ -39,7 +39,7 @@ Before installing Pangolin, ensure you've opened the required port on your firew Connect to your server via SSH and download the installer: ```bash - curl -fsSL https://pangolin.net/get-node-installer.sh | bash + curl -fsSL https://static.pangolin.net/get-node-installer.sh | bash ``` The installer supports both AMD64 (x86_64) and ARM64 architectures. diff --git a/manage/resources/client-resources.mdx b/manage/resources/client-resources.mdx deleted file mode 100644 index 881d3f7..0000000 --- a/manage/resources/client-resources.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "Client Resources" -description: "Configure resources for Olm clients to access on a Newt site" ---- - -## Overview - -Site resources in Pangolin allow you to define specific ports and a destination that can be accessed through the VPN tunnel when using [Olm clients](/manage/clients/add-client). This is useful for exposing internal services to your remote clients securely. - - -Site resources are only for exposing services on a Newt site to Olm clients running remotely and do not get proxied. - - -## Internal Exposure with Clients - -Internal exposure resources are only accessible when connected via an Olm client. This approach is perfect for secure access to services without exposing them to the public internet. - -When you run Newt with `--accept-clients`, it operates fully in user space without creating a virtual network interface on the host. This means: - -- **No special permissions required** for the container or binary -- **No virtual network interface** created on the host -- **Client-only access** through Pangolin's tunnel -- **Secure internal routing** to your services - -## Configuring Site Resources - -To configure site resources: - - - - Navigate to the **Resources** section in the Pangolin dashboard. - - - In the toggle at the top of the table, select "Site Resources". - - - Click **Add Resource**. - - - Choose the resource type (TCP or UDP). - - - Specify the local port and the target address. - - - -## Accessing Site Resources - -Once configured, you can access these resources from your remote clients using the Olm tunnel. - -### Example: SSH Access - -Here's how to set up SSH access to your server when connected with a client: - - - - In the Pangolin dashboard, create a new client resource and set the port to `2022` (or any available port). - - - - - - - - When connected with a Olm client, you can SSH to your server using `:2022`. - -```bash -ssh user@100.90.128.0 -p 2022 -``` - -When accessing a site resource, you use the IP of the site found in the dashboard and the local port you configured for the resource. - - - - - -This approach is ideal for secure remote access without exposing SSH directly to the internet. - - diff --git a/manage/resources/private/alias.mdx b/manage/resources/private/alias.mdx new file mode 100644 index 0000000..d34d91b --- /dev/null +++ b/manage/resources/private/alias.mdx @@ -0,0 +1,24 @@ +--- +title: "Aliases" +description: "Set a friendly alias hostname that resolves to a host" +--- + +Aliases provide a secondary, user-friendly address for any of your Resources, allowing users to access the Resource using this alternate name in addition to the original address. + +For instance, a router with the address `10.0.0.1` could be assigned the alias `router.internal`, and users could connect using either. Aliases are accessible to anyone who has access to the Resource, and they are exclusively accessible when connected with a Pangolin client, meaning they function without requiring any external DNS record setup. Furthermore, aliases are protocol agnostic, which means they will work with any network protocol, essentially acting as a pseudo-A record for an address that is only functional within the Pangolin environment. + +## CIDRs Vs. IPs + +A alias can only be created for a Resource that is a single host (IP or FQDN). Aliases cannot be created for Resources that are CIDR ranges because it would be ambiguous which host within the range the alias should point to. + +## Domain Structure + +Since aliases cannot be single-label domains, you must avoid using domain names that do not contain a dot (e.g., `pangolin`). A domain like `pangolin.net`, which includes a dot, is acceptable. Instead of a single-label domain, you should consider using a subdomain of a domain you control, such as `router.mywebsite.com`, or an existing private/internal domain name, like `router.internal` or `router.corp`. + +## Custom Upstream DNS + +Aliases work by overriding the DNS of your computer running the client so that all DNS requests are sent to the Pangolin client for resolution. The dns server on your computer is typically `100.96.128.1` which will forward request to an upstream server. By default, we use `9.9.9.9`, but this upstream address can be configured using [the flag](/manage/clients/configure-client) in the CLI / Olm or in the client settings. + +## Disable Aliases + +If you wish to disable this behavior and prevent aliases from being resolved and leave your DNS alone, you can do so by adding [the flag](/manage/clients/configure-client) to the CLI / Olm or disable override dns in the client settings. diff --git a/manage/resources/private/authentication.mdx b/manage/resources/private/authentication.mdx new file mode 100644 index 0000000..93eb399 --- /dev/null +++ b/manage/resources/private/authentication.mdx @@ -0,0 +1,18 @@ +--- +title: "Authentication" +description: "Only allow access to Resources to specific users, roles, and machines" +--- + +When a client connects into an organization they will **NOT** have access to any Resources by default. Access must be explicitly granted to users, roles, or machines for a WireGuard tunnel to be established to the site hosting the Resource. The Client will show no peers unless access is granted. + +Access can be granted in several ways: + +* **Roles:** Assign access to Resources to specific roles. Any user or machine with that role will gain access to the Resource when they connect. +* **Users:** Assign access to Resources to specific users. Only those users will gain access to the Resource when they connect. +* **Machines:** Assign access to Resources to specific machines. Only those machines will gain access to the Resource when they connect. Note that machines can not be put into roles. + +When removing access to a resource, the client will automatically tear down the WireGuard tunnel to that Resource if there are no other Resources accessible on that site. + + + + \ No newline at end of file diff --git a/manage/resources/private/destinations.mdx b/manage/resources/private/destinations.mdx new file mode 100644 index 0000000..81f582e --- /dev/null +++ b/manage/resources/private/destinations.mdx @@ -0,0 +1,27 @@ +--- +title: "Destinations" +description: "Understand connection options to the remote network" +--- + +A Resource's **destination** can be defined in several ways: + +* **Fully Qualified Domain Name (FQDN):** For example, `host.autoco.internal`. +* **IP Address:** For example, `10.1.0.35`. +* **IP CIDR Range:** For example, `10.1.0.0/16`. + +When defining a Resource with an FQDN, the Pangolin site will resolve the FQDN to an IP address on the remote network. This allows you to create Resources that point to hosts whose IP addresses may change over time, as long as the FQDN remains consistent. + +When defining a Resource with an IP address, the Pangolin client will connect directly to that specific IP address on the remote network. It will insert routes for that single IP address into the network route table of the host when users connect with the client. + +When defining a Resource with a CIDR range, all IP addresses within that range will be accessible to users who have been granted access to the Resource. This is useful for providing access to entire subnets or network segments. It will insert routes for that single IP address into the network route table of the host when users connect with the client. + +### Additional Notes on Resource Destinations + +* **Reserved IP Addresses:** The Pangolin client reserves the CGNAT subnet 100.96.128.0/24. Accessing resources via an IP address within this reserved range will be blocked by the client, though its use is uncommon. This range can be configured for newly created orgs in the self-hosted Pangolin configuration file. +* **Resource Destination Resolution:** The configured address of the Resource is resolved by the site the resource points to. Make sure the site can resolve the address correctly. + +### What about overlaps? + +Pangolin smooths away overlapping networks and arbitrarily chooses a single site to resolve the IP address or range to. This is because we want connection requests to any Resource to be as simple as possible for the end users: when they connect to a particular IP address or FQDN, Pangolin figures out which site to send it to and the end user never needs to figure this out. + +It is recommended that you create overlapping resources only if absolutely required. If you do, use [Aliases](/manage/resources/private/alias) to explicitly defined which host should be used for a given FQDN or IP address and use the alias to connect. \ No newline at end of file diff --git a/manage/resources/public/authentication.mdx b/manage/resources/public/authentication.mdx new file mode 100644 index 0000000..d38b4a5 --- /dev/null +++ b/manage/resources/public/authentication.mdx @@ -0,0 +1,36 @@ +--- +title: "Authentication" +description: "Create identity and context aware rules to allow access" +--- + +Though public resources are public and accessible to via a web browser, admins can create rules to enable a layer of authenticated protection in front of public resources. By default, all public resources have Pangolin auth (Platform SSO) enabled, but a number of other authentication methods are available. + +When an unauthenticated user visits a resource in their web browser, they will be redirected to a Pangolin-controlled authentication page where they must complete authentication. + +## User Login + +- **Pangolin (Platform) SSO** - Users must log in with a valid Pangolin account before they can log in. +- **External Identity Provider** - Enable log in to resoruces via your organization's identity provider of choice (Google, Azure, Okta, etc). +- **Users and Roles** - Assign specific users accesss to resources. Group users by roles and assign entire roles access to resources. + +## PIN and Passcode + +Add simple PIN or passcode authentication to resources. Similarly to user login, users will need to first enter a PIN or passcode before they can gain access to the resource. + +## Shareable Links and Access Tokens + +Generate temporary self-destructing links that provide authenticated access to resources. Set specific expiration times for when all users who used the link will lose access and when the link becomes invalid. Links can optionally grant more permanent access with no expiration. Delete links when you want to revoke access. + +You can also pass access tokens via query params or headers to resources to enable programmatic access. + +## Email-based One Time Passcode (OTP) + +First whitelist specific emails or wildcards, like `*@.example.com`. When users visit the resource, they will be prompted to enter an email. If the email they enter is on the whitelist, a temporary one time passcode will be sent to their email. Users can then enter this OTP to gain access to the resource. + +## Rules to Access or Deny + +Define ranked rules to either block or allow access from specific IPs, geolocation, URL paths, and more. + +## More + +Read about more authentication options and specific settings in [Access Control](/manage/access-control/) and [Identity Providers](/manage/identity-providers/). diff --git a/manage/resources/tcp-udp-resources.mdx b/manage/resources/public/raw-resources.mdx similarity index 99% rename from manage/resources/tcp-udp-resources.mdx rename to manage/resources/public/raw-resources.mdx index 8966346..fe24319 100644 --- a/manage/resources/tcp-udp-resources.mdx +++ b/manage/resources/public/raw-resources.mdx @@ -1,5 +1,5 @@ --- -title: "Raw TCP & UDP" +title: "TCP & UDP" description: "Configure raw TCP and UDP traffic through Pangolin tunnels" --- @@ -15,6 +15,7 @@ In Pangolin Community Edition, ensure you have the flag enabled in the config fi flags: allow_raw_resources: true ``` + You map the resource to a port on the host Pangolin server, so you can access the resource from `:`. This is useful if you want to access the resource over the public internet, such as exposing a game server like Minecraft. ## Proxied Resources @@ -105,4 +106,4 @@ tcp: pp-transport-v2: proxyProtocol: version: 2 -``` \ No newline at end of file +``` diff --git a/manage/resources/targets.mdx b/manage/resources/public/targets.mdx similarity index 66% rename from manage/resources/targets.mdx rename to manage/resources/public/targets.mdx index 8b8825d..253de9d 100644 --- a/manage/resources/targets.mdx +++ b/manage/resources/public/targets.mdx @@ -3,14 +3,8 @@ title: "Targets" description: "Configure destination endpoints for resource routing and load balancing" --- -## Overview - When you create a resource in Pangolin, you define different targets that specify where traffic should be routed within your network. Each target represents a specific destination that the resource can proxy to when handling incoming requests. - -Targets are created on the Newt tunnel, enabling traffic to reach destinations on the remote network without requiring additional routing configuration. - - ## How Targets Work ### Target Routing @@ -22,9 +16,9 @@ Targets function as destination endpoints for your resources: 3. **Network Access**: Newt proxy routes traffic to the local network through the tunnel 4. **Direct Connection**: No additional routing is necessary on the remote network -## Multi-Site Targets (v1.9.0+) +## Multi-Site Targets -With the introduction of update 1.9.0, targets now have sites associated with them. This enhancement provides significant benefits for reliability and load distribution. +Targets have sites associated with them. This provides significant benefits for reliability and load distribution described below. ### Site-Distributed Resources @@ -38,11 +32,15 @@ You can now configure targets across different sites for the same resource: Set up load balancing across sites to distribute traffic in a round-robin fashion between all available targets. -### Load Balancing Requirements +### Distributing Sites Load Across Servers - -Load balancing between different targets only works when sites are connected to the same node. In Pangolin instances with multiple remote nodes, ensure load balancing occurs on the same node. - + +This is an Enterprise Edition only feature. + + +This refers to having more than on Pangolin server node that a site can connect to. If one of the server nodes goes down, the site moves to another node. This has some implications for site-based load balancing, because DNS must can only route a FQDN to one Pangolin server node at a time. + +Load balancing between different targets only works when sites are connected to the same Pangolin node. In Pangolin instances with multiple remote nodes, ensure load balancing occurs on the same node. To ensure effective load balancing in multi-node environments: @@ -50,10 +48,6 @@ To ensure effective load balancing in multi-node environments: newt --prefer-endpoint ``` - -Pangolin currently does not load balance between nodes, only between targets on the same node. - - ## Path-Based Routing Path-based routing allows you to direct traffic to different targets based on the request path. This enables sophisticated routing scenarios where different services can handle different parts of your application. @@ -71,23 +65,23 @@ When a request comes in, Pangolin evaluates the path against all targets and rou Pangolin supports three different matching strategies: - - **exact**: The request path must match the configured path exactly. - - Example: Path `/api/users` with exact match only matches `/api/users` - +#### Exact Match - - **prefix**: The request path must start with the configured path. - - Example: Path `/api` with prefix match matches `/api/users`, `/api/orders`, `/api/users/123`, etc. - +**exact**: The request path must match the configured path exactly. - - **regex**: The request path is matched against a regular expression pattern. - - Example: Path `^/api/users/[0-9]+$` with regex match matches `/api/users/123` but not `/api/users/abc` - +Example: Path `/api/users` with exact match only matches `/api/users` + +#### Prefix Match + +**prefix**: The request path must start with the configured path. + +Example: Path `/api` with prefix match matches `/api/users`, `/api/orders`, `/api/users/123`, etc. + +#### Regex Match + +**regex**: The request path is matched against a regular expression pattern. + +Example: Path `^/api/users/[0-9]+$` with regex match matches `/api/users/123` but not `/api/users/abc` Targets example @@ -127,41 +121,41 @@ The rewriting happens after the path match evaluation but before the request rea Pangolin supports four different rewriting strategies: - - **prefix**: Replaces the matched portion with a new prefix, preserving the rest of the path. - - - With Prefix Match: `/api` → `/v2/api` transforms `/api/users` into `/v2/api/users` - - With Exact Match: `/old` → `/new` transforms `/old` into `/new` - - With Regex Match: Uses the regex pattern with the rewrite value as replacement - +#### Prefix Rewrite - - **exact**: Replaces the matched path with the exact rewrite path. - - Example: Match path `/api/users` → Rewrite to `/users` transforms `/api/users` into `/users` - +**prefix**: Replaces the matched portion with a new prefix, preserving the rest of the path. - - **regex**: Uses regular expression substitution to transform the path. Works with any match type. - - - With Regex Match: Uses the regex pattern directly - - With Prefix Match: Automatically captures everything after the prefix with `(.*)` - - With Exact Match: Matches the exact path - - Example: Match path `^/api/v1/(.*)` (regex) → Rewrite to `/api/v2/$1` transforms `/api/v1/users` into `/api/v2/users` - +- With Prefix Match: `/api` → `/v2/api` transforms `/api/users` into `/v2/api/users` +- With Exact Match: `/old` → `/new` transforms `/old` into `/new` +- With Regex Match: Uses the regex pattern with the rewrite value as replacement - - **stripPrefix**: Removes the matched prefix from the path. - - - With Prefix Match: Efficiently strips the prefix using Traefik's stripPrefix middleware - - With Exact/Regex Match: Uses regex replacement to remove the matched portion - - Optionally add a new prefix after stripping by providing a rewrite value - - Example: Match path `/api` (prefix) → Strip Prefix transforms `/api/users` into `/users` - - Example with new prefix: Match path `/old` (prefix) → Strip Prefix + Rewrite to `/new` transforms `/old/users` into `/new/users` - +#### Exact Rewrite + +**exact**: Replaces the matched path with the exact rewrite path. + +Example: Match path `/api/users` → Rewrite to `/users` transforms `/api/users` into `/users` + +#### Regex Rewrite + +**regex**: Uses regular expression substitution to transform the path. Works with any match type. + +- With Regex Match: Uses the regex pattern directly +- With Prefix Match: Automatically captures everything after the prefix with `(.*)` +- With Exact Match: Matches the exact path + +Example: Match path `^/api/v1/(.*)` (regex) → Rewrite to `/api/v2/$1` transforms `/api/v1/users` into `/api/v2/users` + +#### Strip Prefix + +**stripPrefix**: Removes the matched prefix from the path. + +- With Prefix Match: Efficiently strips the prefix using Traefik's stripPrefix middleware +- With Exact/Regex Match: Uses regex replacement to remove the matched portion +- Optionally add a new prefix after stripping by providing a rewrite value + +Example: Match path `/api` (prefix) → Strip Prefix transforms `/api/users` into `/users` + +Example with new prefix: Match path `/old` (prefix) → Strip Prefix + Rewrite to `/new` transforms `/old/users` into `/new/users` Targets with path rewriting @@ -207,4 +201,4 @@ When using path rewriting, request priority is automatically calculated to ensur - Prefix match adds +3 more - Regex match adds +2 more - Root path `/` gets priority 1 (lowest, acts as catch-all) -- Custom priorities override the automatic calculation \ No newline at end of file +- Custom priorities override the automatic calculation diff --git a/manage/resources/understanding-resources.mdx b/manage/resources/understanding-resources.mdx new file mode 100644 index 0000000..6f39f9d --- /dev/null +++ b/manage/resources/understanding-resources.mdx @@ -0,0 +1,52 @@ +--- +title: "Understanding Resources" +description: "Resources are any network address you want to make available to users" +--- + +Resources respresent the applications, hosts, or ranges you make available for remote access to users. Resources exist on the remote networks of your sites. Users only ever think about connecting to resources and not specific sites. + +By default, no resources are made available on sites. Admins must define resources with backend targets, and assign specific access policies before any users can gain access. + +## Resources Types + +There are two types of resources: public resources and private resources. + + + + - Reverse proxies to backend services + - Optionally have authentication + - Anyone with web browser can access + + + + - Zero-trust VPN + - Access to every resources requires authentication + - Users and machines access when connected with a client + + + +### Public Resources + +Public resources are protocol-aware and TCP/UDP proxies to services that are made available to the public internet. + +#### HTTPS Resources + +Examples of HTTP resources include, APIs, websites, and dashboards. These are served with a fully qualified domain name and HTTPS with a valid SSL certificate. + +All requests go through an authenticated reverse proxy. **Thus, public resources do not require client-side software to be installed on user devices for access. Anyone with a web browser can access public resources.** + +HTTP resources are also identity and context aware, meaning you can create policies and rules to only let certain users, roles, countries, IPs, CIDRs, etc have access. When users visit an authenticated public resource, they are greeted with a Pangolin login page where they must complete authentication in order to get to the underlying resource. Therefore, Pangolin acts as a frontdoor barrier to these resources. + +#### Raw TCP/UDP Resources + +Raw resources are a way to proxy any TCP and UDP traffic through the Pangolin reverse proxy. Instead of a fully qualified domain name and certificate, these resources are bound to one or more ports on the Pangolin host. + +Since these resources are not protocol aware and are publicly proxied, they do not support identity and context policies and rules. + +### Private Resources + +Private resources require users to be connected with Pangolin client in order for them to be accessed. Any TCP and UDP traffic can be made available. + +**Private resources function like a zero-trust virtual private network (VPN).** Explicit access to resources must be granted for users and roles to be able to access them. For this reason, we recommend using private resources for all raw TCP/UDP traffic that doesn't need a public proxy, instead of relying on raw TCP/UDP public resources (as discussed above). + +Private resources support single hosts or entire network ranges (CIDR). Private resources can also have internal DNS alias hostnames assigned for easy, human-readable naming. Users don't choose to connect to specific resources; rather, when they connect via a client to your organization, they can access all resources their account has access to at once. diff --git a/manage/sites/add-site.mdx b/manage/sites/add-site.mdx deleted file mode 100644 index 56987b9..0000000 --- a/manage/sites/add-site.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Add Site" -description: "Create a site to connect to a remote network and expose resources" ---- - -A site is a connection to a remote network that allows Pangolin to establish a tunnel to that network. Sites are the foundation for exposing resources because all resources exist on a site. Newt is the software connector that facilitates the connection and addresses the targets on the remote networks. - -## How Sites Work - -### The Connection Process - -1. **Site Creation**: You create a site in Pangolin's dashboard -2. **Newt Registration**: Newt registers with Pangolin using the site credentials -3. **Tunnel Establishment**: Newt establishes a WireGuard tunnel to the remote network -4. **Resource Exposure**: Resources on the remote network become accessible through the tunnel - -### Why Sites Matter - -Sites are the first step to exposing resources with Pangolin because: - -- **Resources exist on sites**: All resources must be associated with a site -- **Newt addresses targets**: Newt is what actually connects to the targets on remote networks -- **Tunnel enables access**: The tunnel allows Pangolin to expose resources without opening ports or needing a public IP -- **Secure communication**: All traffic flows through encrypted WireGuard tunnels - -## Site Types - -Pangolin supports three different types of sites, each designed for different use cases and deployment scenarios. - - - This site allows you to expose resources on a remote network via a fully managed tunnel. This requires the Newt connector to be running on the remote network. It's the easiest to use and requires the least amount of setup. No NAT configuration required. - - - - - Use this if you want to expose resources on the same host as the Pangolin server (this is for self-hosted Pangolin only). No tunnels are created. Ports must be opened on the host running Pangolin (this has to happen anyway for Pangolin to work). - - - - This is self-hosted only. This uses a raw WireGuard connection without Newt, thus there is no websocket connection, requiring more manual management. These sites require NAT to address targets running on other hosts on the remote network. Otherwise, you can only expose resources on the remote WireGuard peer itself. - - - -## Adding a Site - - - - In the Pangolin dashboard, go to the **Sites** section and click **Add Site**. - - - - Configure the basic information: - - **Site Name**: A descriptive name for your site - - - - Select the appropriate site type based on your needs: - - **Newt Tunnel**: For remote networks with Newt connector - - **Local Site**: For resources on the same host as Pangolin - - **Basic WireGuard**: For direct WireGuard connections - - - - Pangolin will generate: - - **Newt ID**: Unique identifier for the Newt client - - **Secret**: Authentication secret for secure connection - - **Endpoint**: The Pangolin server endpoint - - - - Use the generated credentials to configure the site on the remote network. See [Install Site](/manage/sites/install-site) for detailed instructions on how to install Newt. - - - - Once Newt is running, the site status should show as "Online" in the dashboard. Sometimes it takes a few moments for the status to update. - - - -## Notes - -- Sites require Newt to be running on the remote network -- Each site can host multiple resources -- Connection status is monitored automatically diff --git a/manage/sites/configure-site.mdx b/manage/sites/configure-site.mdx index 63dd7f7..361f8cb 100644 --- a/manage/sites/configure-site.mdx +++ b/manage/sites/configure-site.mdx @@ -1,42 +1,21 @@ --- -title: "Configure Site" +title: "Configure Sites" description: "Configure Newt for connecting to Pangolin sites" --- -Newt is a fully user space [WireGuard](https://www.wireguard.com/) tunnel client and TCP/UDP proxy, designed to securely expose private resources controlled by Pangolin. By using Newt, you don't need to manage complex WireGuard tunnels and NATing. -## Preview - - -Newt Preview - - -## How Newt Works - -### Registers with Pangolin - -Using the Newt ID and a secret, the client will make HTTP requests to Pangolin to receive a session token. Using that token, it will connect to a websocket and maintain that connection. Control messages will be sent over the websocket. - -### Receives WireGuard Control Messages - -When Newt receives WireGuard control messages, it will use the information encoded (endpoint, public key) to bring up a WireGuard tunnel using [netstack](https://github.com/WireGuard/wireguard-go/blob/master/tun/netstack/examples/http_server.go) fully in user space. It will ping over the tunnel to ensure the peer on the Gerbil side is brought up. - -### Receives Proxy Control Messages - -When Newt receives proxy control messages, it will use the information encoded to create a local low level TCP and UDP proxies attached to the virtual tunnel in order to relay traffic to programmed targets. - -## Configuration Arguments +## Flags Newt ID generated by Pangolin to identify the client. - + **Example**: `31frd0uzbjvp721` A unique secret used to authenticate the client ID with the websocket. - + **Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6` - + Keep this secret private and secure. It's used for authentication. @@ -44,106 +23,176 @@ When Newt receives proxy control messages, it will use the information encoded t The endpoint where both Gerbil and Pangolin reside for websocket connections. - + **Example**: `https://pangolin.example.com` + + Port for the peers to connect to Newt on. This can be used to keep a static port open in firewalls instead of default random ports. + + **Example**: `34534` + + MTU for the internal WireGuard interface. - + **Default**: `1280` DNS server to use for resolving the endpoint. - - **Default**: `8.8.8.8` + + **Default**: `9.9.9.9` The log level to use for Newt output. - + **Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` - + **Default**: `INFO` Interval for pinging the server. - + **Default**: `3s` Timeout for each ping. - + **Default**: `5s` Set the Docker socket path for container discovery integration. - + **Example**: `/var/run/docker.sock` Validate the container target is on the same network as the Newt process. - + **Default**: `false` Check if connection to WireGuard server (Pangolin) is ok. Creates a file if ok, removes it if not ok. Can be used with Docker healthcheck to restart Newt. - + **Example**: `/tmp/healthy` Script to be called when targets are added or removed. - + **Example**: `/path/to/updown.sh` - - Client certificate (p12 or pfx) for mutual TLS (mTLS) authentication. - - **Example**: `/path/to/client.p12` + + Path to blueprint file to define Pangolin resources and configurations. + + **Example**: `/path/to/blueprint.yaml` - - Enable WireGuard server mode to accept incoming Olm client connections. - + + Don't fail over to the cloud when using managed nodes in Pangolin Cloud. + **Default**: `false` - - Path to save generated private key (used with accept-clients). - - **Example**: `/var/key` + + Disable clients on the WireGuard interface. + + **Default**: `false` (clients enabled) - Use native WireGuard interface when accepting clients (requires WireGuard kernel module and Linux, must run as root). - + Use native WireGuard interface (requires WireGuard kernel module and Linux, must run as root). + **Default**: `false` (uses userspace netstack) - Name of the WireGuard interface (used with native mode). - + Name of the WireGuard interface. + **Default**: `newt` - - Keep the WireGuard interface after shutdown (used with native mode). - + + Enable Prometheus /metrics exporter. + + **Default**: `true` + + + + Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT. + **Default**: `false` + + Admin/metrics bind address. + + **Default**: `127.0.0.1:2112` + + + + Enable async bytes counting (background flush; lower hot path overhead). + + **Default**: `false` + + + + Optional region resource attribute for telemetry and metrics. + + **Example**: `us-west-2` + + + + Enforce certificate validation for health checks. + + **Default**: `false` (accepts any cert) + + + + Path to client certificate file (PEM/DER format) for mTLS. + + **Example**: `/path/to/client.crt` + + + + Path to client private key file (PEM/DER format) for mTLS. + + **Example**: `/path/to/client.key` + + + + Path to CA certificate file for validating remote certificates (can be specified multiple times). + + **Example**: `/path/to/ca.crt` + + + + Path to client certificate (PKCS12 format) - DEPRECATED: use `--tls-client-cert-file` and `--tls-client-key` instead. + + **Example**: `/path/to/client.p12` + + + + Prefer this endpoint for the connection (if set, will override the endpoint from the server). + + **Example**: `https://preferred.endpoint.com` + + ## Environment Variables All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables are particularly useful when running Newt in containerized environments. + +When both environment variables and CLI arguments are provided, CLI arguments take precedence. + + Endpoint of your Pangolin server (equivalent to `--endpoint`) @@ -156,21 +205,39 @@ All CLI arguments can be set using environment variables as an alternative to co Newt secret for authentication (equivalent to `--secret`) + + Port for the peers to connect to Newt on (equivalent to `--port`) + + MTU for the internal WireGuard interface (equivalent to `--mtu`) - + **Default**: `1280` DNS server to use for resolving the endpoint (equivalent to `--dns`) - - **Default**: `8.8.8.8` + + **Default**: `9.9.9.9` + + + + Load the config JSON from this file instead of in the home folder. + + + + Path to blueprint file to define Pangolin resources and configurations (equivalent to `--blueprint-file`). + + + + Don't fail over to the cloud when using managed nodes in Pangolin Cloud (equivalent to `--no-cloud`). + + **Default**: `false` Log level (equivalent to `--log-level`) - + **Default**: `INFO` @@ -180,13 +247,13 @@ All CLI arguments can be set using environment variables as an alternative to co Interval for pinging the server (equivalent to `--ping-interval`) - + **Default**: `3s` Timeout for each ping (equivalent to `--ping-timeout`) - + **Default**: `5s` @@ -194,13 +261,9 @@ All CLI arguments can be set using environment variables as an alternative to co Path to updown script for target add/remove events (equivalent to `--updown`) - - Path to client certificate for mTLS (equivalent to `--tls-client-cert`) - - Validate container targets are on same network (equivalent to `--docker-enforce-network-validation`) - + **Default**: `false` @@ -208,173 +271,144 @@ All CLI arguments can be set using environment variables as an alternative to co Path to health file for connection monitoring (equivalent to `--health-file`) - - Enable WireGuard server mode (equivalent to `--accept-clients`) - - **Default**: `false` - + + Disable clients on the WireGuard interface (equivalent to `--disable-clients`). - - Path to save generated private key (equivalent to `--generateAndSaveKeyTo`) + **Default**: `false` Use native WireGuard interface (Linux only, equivalent to `--native`) - + **Default**: `false` Name of the WireGuard interface (equivalent to `--interface`) - + **Default**: `newt` - - Keep the WireGuard interface after shutdown (equivalent to `--keep-interface`) - + + Enable Prometheus /metrics exporter (equivalent to `--metrics`). + + **Default**: `true` + + + + Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT (equivalent to `--otlp`). + **Default**: `false` - - Load the config JSON from this file instead of in the home folder. + + Admin/metrics bind address (equivalent to `--metrics-admin-addr`). + + **Default**: `127.0.0.1:2112` - -When both environment variables and CLI arguments are provided, CLI arguments take precedence. - + + Enable async bytes counting (background flush; lower hot path overhead, equivalent to `--metrics-async-bytes`). -## Basic Configuration Examples + **Default**: `false` + -### Binary Example + + Optional region resource attribute for telemetry and metrics (equivalent to `--region`). + -```bash -newt \ ---id 31frd0uzbjvp721 \ ---secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ ---endpoint https://example.com + + Enforce certificate validation for health checks (equivalent to `--enforce-hc-cert`). + + **Default**: `false` + + + + Path to client certificate file (PEM/DER format) for mTLS (equivalent to `--tls-client-cert-file`) + + + + Path to client private key file (PEM/DER format) for mTLS (equivalent to `--tls-client-key`) + + + + Comma-separated list of CA certificate file paths for validating remote certificates (equivalent to multiple `--tls-client-ca` flags) + + + + Path to client certificate (PKCS12 format) - DEPRECATED: use `TLS_CLIENT_CERT` and `TLS_CLIENT_KEY` instead + + +## Loading secrets from files + +You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs. + +``` +$ cat ~/.config/newt-client/config.json +{ + "id": "spmzu8rbpzj1qq6", + "secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3", + "endpoint": "https://app.pangolin.net", + "tlsClientCert": "" +} ``` -### Docker Compose with Environment Variables (Recommended) +This file is also written to when newt first starts up. So you do not need to run every time with --id and secret if you have run it once! -```yaml title="docker-compose.yml" -services: - newt: - image: fosrl/newt - container_name: newt - restart: unless-stopped - environment: - - PANGOLIN_ENDPOINT=https://app.pangolin.net - - NEWT_ID=2ix2t8xk22ubpfy - - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 - - HEALTH_FILE=/tmp/healthy -``` +Default locations: -### Docker Compose with CLI Arguments +- **macOS**: `~/Library/Application Support/newt-client/config.json` +- **Windows**: `%PROGRAMDATA%\newt\newt-client\config.json` +- **Linux/Others**: `~/.config/newt-client/config.json` -```yaml title="docker-compose.yml" -services: - newt: - image: fosrl/newt - container_name: newt - restart: unless-stopped - command: - - --id 31frd0uzbjvp721 - - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 - - --endpoint https://app.pangolin.net - - --health-file /tmp/healthy -``` - -## Advanced Features - -### Accept Client Connections - -When the `--accept-clients` flag is enabled (or `ACCEPT_CLIENTS=true` environment variable is set), Newt operates as a WireGuard server that can accept incoming client connections from other devices. This enables peer-to-peer connectivity through the Newt instance. - -#### Client Tunneling Modes - -Newt supports two WireGuard tunneling modes: - -##### Userspace Mode (Default) - -By default, Newt uses a fully userspace WireGuard implementation using [netstack](https://github.com/WireGuard/wireguard-go/blob/master/tun/netstack/examples/http_server.go). This mode: - -- **Does not require root privileges** -- **Works on all supported platforms** (Linux, Windows, macOS) -- **Does not require WireGuard kernel module** to be installed -- **Runs entirely in userspace** - no system network interface is created -- **Is containerization-friendly** - works seamlessly in Docker containers - - -This is the recommended mode for most deployments, especially containerized environments. - - -##### Native Mode (Linux only) - -When using the `--native` flag or setting `USE_NATIVE_INTERFACE=true`, Newt uses the native WireGuard kernel module. This mode: - -- **Requires root privileges** to create and manage network interfaces -- **Only works on Linux** with the WireGuard kernel module installed -- **Creates a real network interface** (e.g., `newt0`) on the system -- **May offer better performance** for high-throughput scenarios -- **Requires proper network permissions** and may conflict with existing network configurations - - -Native mode requires Linux with WireGuard kernel module and must run as root. - - -#### Native Mode Requirements - -To use native mode: - -1. Run on a Linux system -2. Install the WireGuard kernel module -3. Run Newt as root (`sudo`) -4. Ensure the system allows creation of network interfaces - -**Docker Compose example:** - -```yaml title="docker-compose.yml" -services: - newt: - image: fosrl/newt - container_name: newt - restart: unless-stopped - environment: - - PANGOLIN_ENDPOINT=https://app.pangolin.net - - NEWT_ID=2ix2t8xk22ubpfy - - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 - - ACCEPT_CLIENTS=true -``` - -### Docker Socket Integration +## Docker Socket Integration Newt can integrate with the Docker socket to provide remote inspection of Docker containers. This allows Pangolin to query and retrieve detailed information about containers running on the Newt client, including metadata, network configuration, port mappings, and more. **Configuration:** -You can specify the Docker socket path using the `--docker-socket` CLI argument or by setting the `DOCKER_SOCKET` environment variable. On most Linux systems the socket is `/var/run/docker.sock`. When deploying Newt as a container, you need to mount the host socket as a volume for the Newt container to access it. +You can specify the Docker socket path using the `--docker-socket` CLI argument or by setting the `DOCKER_SOCKET` environment variable. If the Docker socket is not available or accessible, Newt will gracefully disable Docker integration and continue normal operation. -```yaml title="docker-compose.yml" +Supported values include: + +- Local UNIX socket (default): + >You must mount the socket file into the container using a volume, so Newt can access it. + + `unix:///var/run/docker.sock` + +- TCP socket (e.g., via Docker Socket Proxy): + + `tcp://localhost:2375` + +- HTTP/HTTPS endpoints (e.g., remote Docker APIs): + + `http://your-host:2375` + +- SSH connections (experimental, requires SSH setup): + + `ssh://user@host` + + +```yaml services: - newt: - image: fosrl/newt - container_name: newt - restart: unless-stopped - volumes: - - /var/run/docker.sock:/var/run/docker.sock:ro - environment: - - PANGOLIN_ENDPOINT=https://app.pangolin.net - - NEWT_ID=2ix2t8xk22ubpfy - - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 - - DOCKER_SOCKET=/var/run/docker.sock + newt: + image: fosrl/newt + container_name: newt + restart: unless-stopped + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + environment: + - PANGOLIN_ENDPOINT=https://example.com + - NEWT_ID=2ix2t8xk22ubpfy + - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 + - DOCKER_SOCKET=unix:///var/run/docker.sock ``` If the Docker socket is not available or accessible, Newt will gracefully disable Docker integration and continue normal operation. -#### Hostnames vs IPs +**Hostnames vs IPs** When the Docker Socket Integration is used, depending on the network which Newt is run with, either the hostname (generally considered the container name) or the IP address of the container will be sent to Pangolin: @@ -383,19 +417,17 @@ When the Docker Socket Integration is used, depending on the network which Newt - **Running in docker-compose without a network specification**: Docker compose creates a network for the compose by default, hostnames will be used - **Running on docker-compose with defined network**: Hostnames will be used -#### Docker Enforce Network Validation +**Docker Enforce Network Validation** When run as a Docker container, Newt can validate that the target being provided is on the same network as the Newt container and only return containers directly accessible by Newt. Validation will be carried out against either the hostname/IP Address and the Port number to ensure the running container is exposing the ports to Newt. +Validation is `false` by default. It can be enabled via setting the `--docker-enforce-network-validation` CLI argument or by setting the `DOCKER_ENFORCE_NETWORK_VALIDATION` environment variable. + If the Newt container is run with a network mode of `host`, this feature will not work. Running in `host` mode causes the container to share its resources with the host machine, making it impossible to retrieve specific host container information for network validation. -**Configuration:** - -Validation is `false` by default. It can be enabled via setting the `--docker-enforce-network-validation` CLI argument or by setting the `DOCKER_ENFORCE_NETWORK_VALIDATION` environment variable. - -### Updown Scripts +## Updown Scripts You can pass in an updown script for Newt to call when it is adding or removing a target: @@ -418,19 +450,24 @@ Returning a string from the script in the format of a target (`ip:dst` so `10.0. You can look at `updown.py` as a reference script to get started! -### mTLS Authentication +## mTLS Authentication -Newt supports mutual TLS (mTLS) authentication if the server has been configured to request a client certificate. +Newt supports mutual TLS (mTLS) authentication if the server is configured to request a client certificate. You can use either a PKCS12 (.p12/.pfx) file or split PEM files for the client cert, private key, and CA. + +### Option 1: PKCS12 (Legacy) + + +This is the original method and still supported. + **Requirements:** -- Only PKCS12 (.p12 or .pfx) file format is accepted -- The PKCS12 file must contain: - - Private key +- File must contain: + - Client private key - Public certificate - CA certificate -- Encrypted PKCS12 files are currently not supported +- Encrypted `.p12` files are **not supported** -**Binary Example:** +**Example:** ```bash newt \ @@ -440,21 +477,30 @@ newt \ --tls-client-cert ./client.p12 ``` -**Docker Compose Example:** +### Option 2: Split PEM Files (Preferred) -```yaml title="docker-compose.yml" -services: - newt: - image: fosrl/newt - container_name: newt - restart: unless-stopped - environment: - - PANGOLIN_ENDPOINT=https://app.pangolin.net - - NEWT_ID=2ix2t8xk22ubpfy - - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 - - TLS_CLIENT_CERT=./client.p12 +You can now provide separate files for: + +- `--tls-client-cert-file`: client certificate (`.crt` or `.pem`) +- `--tls-client-key`: client private key (`.key` or `.pem`) +- `--tls-client-ca`: CA cert to verify the server (can be specified multiple times) + +**Example:** + +```bash +newt \ +--id 31frd0uzbjvp721 \ +--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ +--endpoint https://example.com \ +--tls-client-cert-file ./client.crt \ +--tls-client-key ./client.key \ +--tls-client-ca ./ca.crt ``` - -Get your `id` and `secret` from the Pangolin dashboard when creating a Newt client. - +## NAT Traversal Tweaks + +Newt supports NAT traversal to allow clients to connect directly to Newt sites without relaying through the Pangolin server, improving performance and reducing latency. + +In some environment depending on the NAT type and firewall, you may need to tweak some settings to get optimal connectivity in the firewall itself. Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make. + +Another option is to keep newt listening for client connections on a static port. This allows you to open a specific port in your firewall for Newt client connections instead of random high ports. You can do this by setting the `--port` flag or `PORT` environment variable and then opening this port in the your firewall to DNAT to Newt. diff --git a/manage/sites/credentials.mdx b/manage/sites/credentials.mdx new file mode 100644 index 0000000..320cb7b --- /dev/null +++ b/manage/sites/credentials.mdx @@ -0,0 +1,50 @@ +--- +title: "Site Credentials" +description: "Understanding how site credentials work and how they can be rotated & regenerated" +--- + +## Understanding Credentials + +Every site is provisioned with a unique identifier (ID), secret, and endpoint. The site uses the combination of these three to establish a secure, encrypted connection to the server. + +### ID + +Example: `ln8yqs6w85la5zg` + +The ID represents the site connection type in the system. Every Newt site has an ID. + +This value is not a secret and it is okay if made publically available. + +### Secret + +Example: `tfpwoc580jf1l1glfagix0o97p8kirjogdflqg604n0tr3to` + +The secret represents the "password" of the site. This secret must match the secret hashed in the system for the relevant ID. + + +This is a _secret_! Only share it with trusted people and be sure to store it safely and securely. + + +When the site connects, it uses this secret as a first handshake with the server. The server then passes temporary session credentials back to the site before it can initiate a websocket connection. Once the websocket connection is established, ephemeral keys are used to establish tunnels using WireGuard. + +### Endpoint + +Example: `https://app.pangolin.net` or `https://pangolin.my-server.com` + +The endpoint is how the site knows which server to connect to. This is the fully qualified hostname of the Pangolin server (the URL you use to access the dashboard). For Pangolin cloud, the endpoint is `https://app.pangolin.net`. The site uses this endpoint ot establish a websocket connection and receive control messages from the server. + +## Rotating and Regenerating Credentials + + +This is an Enterprise Edition only feature. + + +Site credentials can be regenerated. Regenerating credentials will completely invalidate the previous ID and secret. Use this feature if you have lost the secret and need to reset the credentials, or if you wish to rotate credentials on a regular basis for extra security. + +To regenerate credentials, visit Sites > Your Site > Credentials in the Pangolin admin dashboard. + +### Regenerate vs. Regenerate and Disconnect + +Regenerate simply recreates the credentials and invalidates the old ones. The site will remain connected until you restart it with the new credentials. + +Regenerate and Disconnect recreates the credentials and invalides the old ones. The site will instantly disconnect and will require you to restart it with the new credentials. diff --git a/manage/sites/install-kubernetes.mdx b/manage/sites/install-kubernetes.mdx index ef1b97d..12c5cc2 100644 --- a/manage/sites/install-kubernetes.mdx +++ b/manage/sites/install-kubernetes.mdx @@ -9,95 +9,76 @@ This guide assumes you already are familiar with Kubernetes concepts and you ful ## Global Prerequisites - - Kubernetes Cluster (v1.28.15+) - Access to the Kubernetes Cluster - Helm (v3.0+) installed, see Helm install docs - - -**Recommended**: Helm Chart Installation. - +## Helm Installation ---- +All Fossorial Helm charts are available on Artifact Hub. See Fossorial Charts. - - + + + ```bash + helm repo add fossorial https://charts.fossorial.io + helm repo update fossorial + helm search repo fossorial + ``` + + - # Helm Installation + Prepare your Newt credentials: + ```env title="newt-cred.env" + PANGOLIN_ENDPOINT= + NEWT_ID= + NEWT_SECRET= + ``` - - All Fossorial Helm charts are available on Artifact Hub. See Fossorial Charts. - + Prepare a values file with your desired configuration. - ## Install Newt + See Newt chart values configuration options. - - - ```bash - helm repo add fossorial https://charts.fossorial.io - helm repo update fossorial - helm search repo fossorial - ``` - - + ```yaml title="values-newt.yaml" + newtInstances: + - name: main + enabled: true + auth: + existingSecretName: newt-cred + keys: + endpointKey: PANGOLIN_ENDPOINT + idKey: NEWT_ID + secretKey: NEWT_SECRET + ``` + + - Prepare your Newt credentials: - ```env title="newt-cred.env" - PANGOLIN_ENDPOINT= - NEWT_ID= - NEWT_SECRET= - ``` + Create a Kubernetes Secret from the env file created earlier: + ```bash +kubectl create secret generic newt-cred -n newt --from-env-file=newt-cred.env + ``` - Prepare a values file with your desired configuration. + Install Newt with Helm: + ```bash + helm install my-newt fossorial/newt \ + -n newt --create-namespace \ + -f values-newt.yaml + ``` - See Newt chart values configuration options. - - ```yaml title="values-newt.yaml" - newtInstances: - - name: main - enabled: true - auth: - existingSecretName: newt-cred - keys: - endpointKey: PANGOLIN_ENDPOINT - idKey: NEWT_ID - secretKey: NEWT_SECRET - ``` - - - - Create a Kubernetes Secret from the env file created earlier: - ```bash - kubectl create secret generic newt-cred -n newt --from-env-file=newt-cred.env - ``` - - Install Newt with Helm: - ```bash - helm install my-newt fossorial/newt \ - -n newt --create-namespace \ - -f values-newt.yaml - ``` - - Change the release name (`my-newt`), namespace (`newt`), and values filename as needed. - - - ```bash - # Update repo to get latest charts - helm repo update fossorial - # Upgrade Newt (after editing values) - helm upgrade my-newt fossorial/newt -n newt -f values-newt.yaml - ``` - ```bash - # Roll back to a previous revision - helm rollback my-newt 1 -n newt - ``` - - - - - ---- + Change the release name (`my-newt`), namespace (`newt`), and values filename as needed. + + + ```bash + # Update repo to get latest charts + helm repo update fossorial + # Upgrade Newt (after editing values) + helm upgrade my-newt fossorial/newt -n newt -f values-newt.yaml + ``` + ```bash + # Roll back to a previous revision + helm rollback my-newt 1 -n newt + ``` + + ## Customizing Your Values @@ -105,8 +86,6 @@ All configuration options are documented in the respective repositories: - Newt Helm chart values ---- - ## References - All Fossorial Helm Charts repo diff --git a/manage/sites/install-site.mdx b/manage/sites/install-site.mdx index 3b7837e..af6be48 100644 --- a/manage/sites/install-site.mdx +++ b/manage/sites/install-site.mdx @@ -1,29 +1,9 @@ --- -title: "Install Site" +title: "Install Sites" description: "Install Newt as a binary or Docker container" --- -Newt can be installed as either a static binary executable or a Docker container. Configuration is passed via CLI arguments in both cases. - - -You **must first create a site and copy the Newt config** in Pangolin before running Newt. - - - - - - Static executable - - Cross-platform support - - Easy to install and run - - Systemd service support - - - - - Containerized deployment - - Environment variables - - Docker Compose support - - Easy management - - +Newt can be installed as either a static binary executable or a Docker container. You must first create a site and copy the Newt config in Pangolin before running Newt. ## Binary Installation @@ -32,12 +12,16 @@ You **must first create a site and copy the Newt config** in Pangolin before run Use this command to automatically install Newt. It detects your system architecture automatically and always pulls the latest version, adding Newt to your PATH: ```bash -curl -fsSL https://pangolin.net/get-newt.sh | bash +curl -fsSL https://static.pangolin.net/get-newt.sh | bash ``` +#### Windows + +If you would like to use Newt on Windows as a service or with clients, wintun.dll is sometimes required. Please use latest installer from [GitHub releases](https://github.com/fosrl/newt/releases/latest). + ### Manual Download -Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/newt/releases) for ARM and AMD64 (x86_64) architectures. +Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/newt/releases/latest) for ARM and AMD64 (x86_64) architectures. Download and install manually: @@ -57,21 +41,9 @@ Run Newt with the configuration from Pangolin: newt \ --id 31frd0uzbjvp721 \ --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ ---endpoint https://example.com +--endpoint https://app.pangolin.net ``` -### Permanent Installation - -Install to your PATH (may need to run as root): - -```bash -mv ./newt /usr/local/bin -``` - - -The quick installer will do this step for you. - - ### Systemd Service Create a basic systemd service: @@ -82,7 +54,7 @@ Description=Newt After=network.target [Service] -ExecStart=/usr/local/bin/newt --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://example.com +ExecStart=/usr/local/bin/newt --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://app.pangolin.net Restart=always User=root @@ -111,7 +83,7 @@ Run Newt with CLI arguments from Pangolin: ```bash docker run -it fosrl/newt --id 31frd0uzbjvp721 \ --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ ---endpoint https://example.com +--endpoint https://app.pangolin.net ``` ### Docker Compose @@ -130,7 +102,7 @@ services: - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 ``` -#### Config file injected as Compose Secret +#### Config File Injected as Compose Secret A safer but slightly more complex way is to use [Compose Secrets](https://docs.docker.com/compose/how-tos/use-secrets/). First, create a `JSON` file containing your configuration: @@ -138,7 +110,7 @@ A safer but slightly more complex way is to use [Compose Secrets](https://docs.d { "id": "2ix2t8xk22ubpfy", "secret": "nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2", - "endpoint": "https://example.com", + "endpoint": "https://app.pangolin.net", "tlsClientCert": "" } ``` @@ -174,7 +146,7 @@ services: command: - --id 31frd0uzbjvp721 - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 - - --endpoint https://example.com + - --endpoint https://app.pangolin.net ``` Start the service: @@ -196,3 +168,52 @@ Newt is available in the Unraid Community Applications store. Search for "Newt" ### Portainer and Other UIs Container management UIs like Portainer typically allow passing commands and environment variables to containers similar to Docker Compose. Look for a commands or arguments configuration section and follow the relevant guides. + +### Windows Service + +On Windows, newt can to be installed and run as a Windows service to remain persistent. + +#### Service Management Commands + +``` +# Install the service +newt.exe install + +# Start the service +newt.exe start + +# Stop the service +newt.exe stop + +# Check service status +newt.exe status + +# Remove the service +newt.exe remove + +# Show help +newt.exe service-help +``` + +Note running the service requires credentials in `%PROGRAMDATA%\newt\newt-client\config.json`. + +#### Service Configuration + +When running as a service, newt will read configuration from environment variables or you can modify the service to include command-line arguments: + +1. Install the service: `newt.exe install` +2. Set the credentials in `%PROGRAMDATA%\newt\newt-client\config.json`. Hint: if you run newt once with --id and --secret this file will be populated! +3. Start the service: `newt.exe start` + +#### Service Logs + +When running as a service, logs are written to: + +- Windows Event Log (Application log, source: "newtWireguardService") +- Log files in: `%PROGRAMDATA%\newt\logs\newt.log` + +You can view the Windows Event Log using Event Viewer or PowerShell: + +```powershell +Get-EventLog -LogName Application -Source "newtWireguardService" -Newest 10 +``` diff --git a/manage/sites/understanding-sites.mdx b/manage/sites/understanding-sites.mdx new file mode 100644 index 0000000..87d2942 --- /dev/null +++ b/manage/sites/understanding-sites.mdx @@ -0,0 +1,55 @@ +--- +title: "Understanding Sites" +description: "Create a site to connect to a remote network and expose resources" +--- + +A site is a connection to a remote network that allows Pangolin to provide access to resources, whether public or private, to users anywhere. Sites are the foundation for exposing resources because all resources exist on one or more sites. Newt is Pangolin's custom software connector that facilitates the connection and addresses the targets on the remote networks. + +## The Basics + +- **Tunneled sites should always run behind a firewall.** Never provide public access to a site. +- **Users do not connect to a site directly.** Instead, admins define public (browser-based) or private resources on the local network of the site and Pangolin provides acess to these resources. +- **You can run one or multiple sites per network.** You need at least on site to facilitate access to resources, but you can run more than one site in the same network for redundancy, for example. It's up to your preferred deployment method. +- **Sites are software-defined proxies and deny all traffic by default.** Just because a site is deployed to a network doesn't mean users have access to resources on the network. By default, sites don't allow any traffic to hosts on the network. Admins must define explicit resources and delegate access to users. + +## Site Types + +Pangolin supports three different types of sites, each designed for different use cases and deployment scenarios. + +### Newt Site (Recommended) + +This site allows you to expose resources on a remote network via a fully managed tunnel and websocket. This requires the Newt connector to be running on the remote network. It's the easiest to use and requires the least amount of setup. No NAT configuration required. + +We recommend using Newt sites in almost all cases. Newt is the primary connector type and supports the most features. + +Newt sites support: +- Public HTTPS proxied resources +- Private resources +- Load balancing +- Health checking +- Docker socket scanning +- And more... + + +### Local Site + +Use this if you want to expose resources on the same host as the Pangolin server (this is for self-hosted Pangolin only). No tunnels are created. Ports must be opened on the host running Pangolin (this has to happen anyway for Pangolin to work). + +Use local sites if you want to expose a public resource on the same host as your self-hosted Pangolin server. + +Local sites do not support: +- Private resources +- Health checking +- Docker socket scanning + +### Basic WireGuard Site + +This is self-hosted only. This uses a raw WireGuard connection without Newt, thus there is no websocket connection, requiring more manual management. These sites require NAT to address targets running on other hosts on the remote network. Otherwise, you can only expose resources on the remote WireGuard peer itself. + +Generally, we do not reccomend you use basic WireGuard sites unless you have a specific use case. + +Basic WireGuard sites do not support: +- Using LAN-style addresses as targets +- Private resources +- Health checking +- Docker socket scanning diff --git a/manage/sites/update-site.mdx b/manage/sites/update-site.mdx index 5263781..efbf04f 100644 --- a/manage/sites/update-site.mdx +++ b/manage/sites/update-site.mdx @@ -1,5 +1,5 @@ --- -title: "Update Site" +title: "Update Sites" description: "Update Newt to the latest version" --- @@ -32,7 +32,7 @@ docker compose up -d newt If you used the auto installer, simply run it again. ```bash -curl -fsSL https://pangolin.net/get-newt.sh | bash +curl -fsSL https://static.pangolin.net/get-newt.sh | bash ``` ### Manual Installation diff --git a/self-host/advanced/config-file.mdx b/self-host/advanced/config-file.mdx index f3fda67..7d802c1 100644 --- a/self-host/advanced/config-file.mdx +++ b/self-host/advanced/config-file.mdx @@ -714,16 +714,6 @@ This section contains the complete reference for all configuration options in `c When enabled, only domains created through the UI are allowed. - - - Whether to enable client functionality. - - **Default**: `true` - - - Controls access to client-related features and endpoints. - - diff --git a/self-host/advanced/enable-geoblocking.mdx b/self-host/advanced/enable-geoblocking.mdx index 35d02b6..f730483 100644 --- a/self-host/advanced/enable-geoblocking.mdx +++ b/self-host/advanced/enable-geoblocking.mdx @@ -17,7 +17,7 @@ Have a look at this [Community guide](/self-host/community-guides/geolite2automa You can use the installer to download and place the database for you, just grab the latest installer: ```bash - curl -fsSL https://pangolin.net/get-installer.sh | bash + curl -fsSL https://static.pangolin.net/get-installer.sh | bash ``` Then run the installer again: diff --git a/self-host/quick-install.mdx b/self-host/quick-install.mdx index 31affc9..ee9b5a0 100644 --- a/self-host/quick-install.mdx +++ b/self-host/quick-install.mdx @@ -41,7 +41,7 @@ Before installing Pangolin, ensure you've set up DNS for your domain(s) and open Connect to your server via SSH and download the installer: ```bash - curl -fsSL https://pangolin.net/get-installer.sh | bash + curl -fsSL https://static.pangolin.net/get-installer.sh | bash ``` The installer supports both AMD64 (x86_64) and ARM64 architectures. @@ -143,8 +143,8 @@ https://pangolin.example.com/auth/initial-setup After logging in: - 1. Click "Create Organization" - 2. Enter organization name and description + 1. Enter organization name and description + 2. Click "Create Organization" You're now ready to start adding applications and configuring your reverse proxy!