diff --git a/about/how-pangolin-works.mdx b/about/how-pangolin-works.mdx index c25f0bf..2387c2f 100644 --- a/about/how-pangolin-works.mdx +++ b/about/how-pangolin-works.mdx @@ -21,7 +21,7 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; - Authenticated users can access resources anywhere using a web browser or when connected with a Pangolin client on their device. + Authenticated users access resources through a web browser (public resources) or when connected with a Pangolin client (private resources). The same users, roles, and policies apply across both—users never pick a site; Pangolin routes to the right connector automatically. @@ -33,10 +33,14 @@ Pangolin relies on several components that work together to provide secure remot 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. +You can use [Pangolin Cloud](https://app.pangolin.net/auth/signup), which is fully managed, or you can self-host your own Pangolin server for complete control over your infrastructure and data. + + + Fastest way to get started with the fully managed control plane. No credit card required. + - Learn how to deploy your own self-hosted Pangolin server or use Pangolin Cloud. + Learn how to deploy your own self-hosted Pangolin server. ### Sites @@ -45,7 +49,7 @@ Sites connect remote networks to your Pangolin server. They use Newt connectors 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. +The Newt connector handles tunnel creation, NAT traversal, and routing. It makes remote networks available without requiring complex firewall rules or public IP addresses. Newt sites also unlock browser-based SSH, RDP, and VNC resources, private HTTP with edge TLS termination, and intelligent multi-site routing when the same resource is reachable from more than one location. Learn about sites, how they work, and how to install and configure them. @@ -55,7 +59,16 @@ The Newt connector handles tunnel creation, NAT traversal, and routing. It makes 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. -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. +There are two types of resources. [Public resources](/manage/resources/understanding-resources#public-resource-types) work through web browsers and act as reverse proxies—or protocol-specific proxies—for backend services. [Private resources](/manage/resources/understanding-resources#private-resource-types) require a client connection and function like a zero-trust VPN. + +What sets Pangolin apart is the breadth of resource types on one platform: + +- **Public HTTP/HTTPS** — authenticated reverse proxies with SSO, access rules, and automatic TLS. No client required. +- **Public SSH, RDP, and VNC** — full terminal, desktop, or display sessions rendered in the browser. No SSH client or remote desktop software needed. +- **Public TCP/UDP** — raw port proxies for protocols that do not need a domain name or authentication layer. +- **Private host and CIDR** — route traffic to specific machines or entire subnets over the tunnel, with per-resource port restrictions. +- **Private HTTP/HTTPS** — reverse proxy with TLS terminated at your network edge over the tunnel. The app is never exposed on the public internet; only connected clients can reach it. +- **Private SSH** — traditional terminal access via `pangolin ssh`, with optional automatic user provisioning from Pangolin identity. 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. @@ -77,7 +90,7 @@ Clients are available for Mac, Windows, and Linux. They work transparently with ### Remote Nodes -Remote nodes are self-hosted Pangolin servers that you control while using Pangolin Cloud or [Enterprise Edition](/self-host/enterprise-edition) 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. +Remote nodes are self-hosted Pangolin servers that you control while using Pangolin Cloud 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. diff --git a/about/pangolin-vs-reverse-proxy-vs-vpn.mdx b/about/pangolin-vs-reverse-proxy-vs-vpn.mdx index 3645103..7b66010 100644 --- a/about/pangolin-vs-reverse-proxy-vs-vpn.mdx +++ b/about/pangolin-vs-reverse-proxy-vs-vpn.mdx @@ -7,8 +7,6 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; - - 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 @@ -17,29 +15,49 @@ Pangolin combines the capabilities of both a reverse proxy and a VPN into a sing **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. +**Pangolin** provides both capabilities—and several things neither traditional tool does on its own. 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. + +## What Pangolin Does Differently + +| Capability | Traditional reverse proxy | Traditional VPN | Pangolin | +|------------|--------------------------|-----------------|----------| +| Browser access to web apps | Yes | No | Yes — public HTTP/HTTPS | +| Browser SSH, RDP, VNC | No | No | Yes — public SSH, RDP, VNC | +| Client-only private access | No | Yes | Yes — host, CIDR, SSH, private HTTP | +| Per-resource access control | Limited | Network-wide | Yes — users and roles per resource | +| No open inbound ports | No | Sometimes | Yes — outbound site tunnels | +| TLS at the network edge (private) | No | No | Yes — [private HTTP/HTTPS](/manage/resources/private/private-http) | +| Multi-site routing and failover | Uncommon | Uncommon | Yes — automatic site selection | ## 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. +Pangolin's public resources function as reverse proxies—and go further than HTTP alone. -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. +**HTTP/HTTPS** resources expose web applications through domain names with automatic SSL certificates. Users access them in a browser with no client installed. Identity-aware access control supports SSO, MFA, and rules based on user identity, roles, geographic location, IP addresses, and URL paths. + +**SSH, RDP, and VNC** resources render full sessions in the browser. Users get a terminal, Windows desktop, or VNC display without installing SSH clients or remote desktop software—while still passing through Pangolin authentication first. + +**TCP and UDP** resources bind to a port on the Pangolin server for raw protocol proxying when you need a public pipe without a domain name or auth layer. 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. +Pangolin's private resources function like a zero-trust VPN—but with tighter scope than a traditional VPN. -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. +**Host and CIDR** resources route traffic to specific machines or subnets over the tunnel. Users only reach what you explicitly grant them, with optional per-resource port restrictions—not an entire flat network. + +**Private HTTP/HTTPS** resources behave like a reverse proxy that only exists on the tunnel. TLS terminates at your [site edge over peer-to-peer transport](/manage/resources/private/private-http)—the application is never reachable from the public internet, only from connected clients with valid access. + +**Private SSH** resources provide terminal access via `pangolin ssh`, with optional automatic user provisioning from Pangolin identity—no manual key distribution required. 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. +Many organizations need both reverse proxy and VPN capabilities. You might want to expose a customer portal through a browser while also giving developers SSH access to internal servers and a private HTTPS dashboard that never touches the public internet. -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. +With Pangolin, you use one platform for all of these. Public resources handle browser-based access—including SSH, RDP, and VNC when you want sessions without a client. Private resources handle tunnel-only access to hosts, subnets, internal HTTPS apps, and CLI SSH. 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. @@ -49,12 +67,12 @@ Traditional reverse proxies and VPNs typically run on a single server. If that s 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 a resource is reachable from multiple site connectors, Pangolin selects the healthiest path based on latency and availability—users connect to the resource, not to a specific site. 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. ## 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 reverse proxy if you only need to expose web applications over HTTP/HTTPS, 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 a traditional VPN if you need broad network access, you can accept the security risks of flat network visibility, 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. +Use Pangolin if you need both reverse proxy and VPN capabilities, browser-based SSH/RDP/VNC, private HTTPS with edge TLS termination, granular per-resource access control, multi-site routing, high availability, or outbound-only connectivity without open ports on your networks. diff --git a/docs.json b/docs.json index c283f26..45ac1a8 100644 --- a/docs.json +++ b/docs.json @@ -40,6 +40,7 @@ "manage/sites/install-site", "manage/sites/configure-site", "manage/sites/update-site", + "manage/sites/auto-update", "manage/sites/credentials", "manage/sites/site-provisioning" ] @@ -52,22 +53,30 @@ { "group": "Public Resources", "pages": [ + "manage/resources/public/http-https", + "manage/resources/public/ssh", + "manage/resources/public/rdp", + "manage/resources/public/vnc", + "manage/resources/public/raw-resources", "manage/resources/public/authentication", + "manage/resources/public/resource-policies", "manage/resources/public/targets", "manage/resources/public/wildcard-resources", "manage/resources/public/healthchecks-failover", - "manage/resources/public/raw-resources", "manage/resources/public/maintenance" ] }, { "group": "Private Resources", "pages": [ + "manage/resources/private/host", + "manage/resources/private/cidr", + "manage/resources/private/private-http", + "manage/resources/private/ssh", "manage/resources/private/authentication", "manage/resources/private/destinations", "manage/resources/private/port-restrictions", "manage/resources/private/alias", - "manage/resources/private/private-http", "manage/resources/private/multi-site-routing" ] } @@ -91,7 +100,8 @@ "group": "Organizations", "icon": "building", "pages": [ - "manage/organizations/org-id" + "manage/organizations/org-id", + "manage/labels" ] }, { diff --git a/images/ssh-resource-config.png b/images/ssh-resource-config.png new file mode 100644 index 0000000..cda432f Binary files /dev/null and b/images/ssh-resource-config.png differ diff --git a/manage/access-control/rules.mdx b/manage/access-control/rules.mdx index c744607..d046c8d 100644 --- a/manage/access-control/rules.mdx +++ b/manage/access-control/rules.mdx @@ -9,7 +9,7 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; -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. +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. On public resources, you can also define rules in a [resource policy](/manage/resources/public/resource-policies) and share them across multiple resources. diff --git a/manage/asnblocking.mdx b/manage/asnblocking.mdx index 93bff1d..9a08164 100644 --- a/manage/asnblocking.mdx +++ b/manage/asnblocking.mdx @@ -26,7 +26,7 @@ ASN blocking provides several important security and operational advantages: ## Implementing ASN Blocking with Bypass Rules -ASN blocking in Pangolin is implemented using [bypass rules](/manage/access-control/rules) with ASN-based matching. You can create rules that either allow or deny access based on the visitor's Autonomous System Number. +ASN blocking in Pangolin is implemented using [bypass rules](/manage/access-control/rules) with ASN-based matching. You can create rules that either allow or deny access based on the visitor's Autonomous System Number. To apply the same ASN rules to multiple public resources, define them in a [resource policy](/manage/resources/public/resource-policies) and attach that policy to each resource. Pangolin Dashboard diff --git a/manage/geoblocking.mdx b/manage/geoblocking.mdx index 5a40af6..ad272f6 100644 --- a/manage/geoblocking.mdx +++ b/manage/geoblocking.mdx @@ -25,7 +25,7 @@ Geo-blocking provides several important security and compliance advantages: ## Implementing Geo-blocking with Bypass Rules -Geo-blocking in Pangolin is implemented using [bypass rules](/manage/access-control/rules) with country-based matching. You can create rules that either allow or deny access based on the visitor's country. +Geo-blocking in Pangolin is implemented using [bypass rules](/manage/access-control/rules) with country-based matching. You can create rules that either allow or deny access based on the visitor's country. To apply the same geo-blocking rules to multiple public resources, define them in a [resource policy](/manage/resources/public/resource-policies) and attach that policy to each resource. Pangolin Dashboard diff --git a/manage/labels.mdx b/manage/labels.mdx new file mode 100644 index 0000000..9b467c1 --- /dev/null +++ b/manage/labels.mdx @@ -0,0 +1,65 @@ +--- +title: "Labels" +description: "Attach reusable string labels to sites, clients, and resources for metadata, search, and filtering" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + + +Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). + + +Labels are string-based values you can assign to sites, machine clients, and resources. Use them to attach metadata, group related entities, and quickly find what you need across your organization. + +## Supported Entities + +You can attach labels to: + +- **Sites** +- **Machine clients** +- **Resources** + +Labels are shared across all three entity types. The same label can be applied to a site, a client, and a resource in the same organization. There is no limit to how many labels you can attach to a single entity. + +## Organization Label Store + +Each organization maintains a central store of all labels. The organization-wide labels page shows every label available in that organization in one place, so you can see what is in use before assigning labels to new entities. + +## Search and Filtering + +Once a label is attached to an entity, that entity becomes searchable by the label string. You can also filter by label in the table view for sites, clients, and resources. + +For example, filtering resources by `warehouse-1` shows only resources tagged with that label. The same label on a site or client makes those entities searchable and filterable the same way. + +## Use Labels for Metadata + +Labels are flexible metadata. Because they are plain strings, you can use any naming convention that fits your workflow. Common examples include: + +| Category | Example labels | +| --- | --- | +| Environment | `prod`, `staging`, `dev` | +| Operating system | `linux`, `mac`, `windows` | +| Customer | `customer-1`, `customer-2` | +| Location | `us-east`, `warehouse-1`, `eu-west` | + +These are only examples. You can define labels for teams, cost centers, compliance tiers, or anything else that helps you organize your infrastructure. + +## Group Entities Across Types + +Labels work across entity types, which makes them useful for grouping things that belong together but are not the same kind of object. + +Want to see everything related to `warehouse-1`? Tag the site, the machine clients, and the resources for that location with the same label. You can then search and filter each table by that label to find the related entities quickly. + +## Managing Labels + +You can manage labels in two ways: + +### Inline on Entity Tables + +When viewing sites, clients, or resources, add labels directly from the entity table. If a label does not exist yet, you can create it on the spot and attach it immediately. + +### Organization-wide Labels Page + +Go to the organization labels page to see all labels in one place. From there you can create, edit, and delete labels across the organization. Changes to a label are reflected everywhere that label is used. \ No newline at end of file diff --git a/manage/resources/private/cidr.mdx b/manage/resources/private/cidr.mdx new file mode 100644 index 0000000..b29c271 --- /dev/null +++ b/manage/resources/private/cidr.mdx @@ -0,0 +1,34 @@ +--- +title: "CIDR" +description: "Route client traffic to an entire IP range on the remote network" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + +A CIDR private resource exposes an entire IP range on your remote network to connected Pangolin clients. When a user connects with the Pangolin client and has access to the resource, the client installs a route for that prefix and all traffic to addresses within the range is carried over the tunnel. + +CIDR resources are the usual choice for whole subnets or network segments instead of creating a separate host resource for every machine. + +## Destination + +A CIDR resource destination is an IP range in CIDR notation—for example `10.1.0.0/16`. Any address inside the range is covered for users who have been granted access. + +The site connector must have routable access to the entire prefix. Confirm from the site's network that it can reach hosts across the range before creating the resource. + +## Port Restrictions + +[Port restrictions](/manage/resources/private/port-restrictions) apply to the entire CIDR range. Use Custom mode to allow only specific ports (for example `443` for HTTPS workloads across the subnet) or Blocked to disable a protocol entirely. + +## Multi-Site Routing + +When the same CIDR is reachable from multiple site connectors, attach all applicable sites. Pangolin [routes through the best available path](/manage/resources/private/multi-site-routing) and fails over when a site goes offline. + + +Only attach sites that can actually reach the configured CIDR. Mixing sites on unrelated networks where some cannot reach the range leads to unpredictable routing. + + +## Overlapping Networks + +If the same IP range exists on multiple sites, Pangolin resolves the conflict automatically. CIDR resources cannot use [aliases](/manage/resources/private/alias)—aliases apply to individual hosts only. If you need predictable routing to a specific site, create separate [host resources](/manage/resources/private/host) for the machines you care about instead of relying on a shared CIDR range. \ No newline at end of file diff --git a/manage/resources/private/host.mdx b/manage/resources/private/host.mdx new file mode 100644 index 0000000..16b4728 --- /dev/null +++ b/manage/resources/private/host.mdx @@ -0,0 +1,38 @@ +--- +title: "Host" +description: "Route client traffic to a single IP address or FQDN on the remote network" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + +A host private resource exposes a single machine on your remote network to connected Pangolin clients. When a user connects with the Pangolin client and has access to the resource, traffic destined for that host is carried over the tunnel to the site, which delivers it on the remote network. + +Host resources are the most common private resource type. They do not render in a browser—you use native applications (a database client, `curl`, an RDP client, etc.) against the destination address while the Pangolin client is connected. + +## Destination + +Every host resource has a [destination](/manage/resources/private/destinations): a single IP address or fully qualified domain name (FQDN). + +| Destination type | Example | When to use | +|------------------|---------|-------------| +| IP address | `10.1.0.35` | A host with a stable IP on the remote network | +| FQDN | `db.autoco.internal` | A host identified by DNS that may change IP | +| Loopback | `127.0.0.1` | A service running on the site connector host itself | + +### Loopback on the Site Host + +If the service runs on the same machine as the site connector, set the destination to `127.0.0.1` or `localhost`. On the user's machine, `localhost` always refers to their own computer—not the remote site. You must add an [alias](/manage/resources/private/alias) (for example `metrics.site-internal.example`) so users connect to a name that Pangolin resolves over the tunnel. + +## Port Restrictions + +By default, all TCP and UDP ports on the destination are reachable. Tighten access with [port restrictions](/manage/resources/private/port-restrictions) to allow only the ports your application needs. + +## Multi-Site Routing + +Attach multiple sites to a host resource when the same destination is reachable from more than one connector. Pangolin [routes traffic through the best available site](/manage/resources/private/multi-site-routing) and fails over automatically when a site goes offline. + +## Aliases + +Optionally assign an [alias](/manage/resources/private/alias) so users connect with a memorable hostname instead of a raw IP. Aliases are required for loopback destinations and recommended when the same IP exists on overlapping networks across sites. \ No newline at end of file diff --git a/manage/resources/private/private-http.mdx b/manage/resources/private/private-http.mdx index 968e30a..a59e19a 100644 --- a/manage/resources/private/private-http.mdx +++ b/manage/resources/private/private-http.mdx @@ -1,6 +1,6 @@ --- -title: "Private HTTP" -description: "HTTPS private resources on your domain with a connected client—Pangolin Cloud and Enterprise; reverse proxy and TLS on the site" +title: "HTTP / HTTPS" +description: "Private reverse proxy with optional TLS termination at the site edge over the Pangolin tunnel" --- import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; @@ -11,13 +11,17 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). -Private HTTP is a special kind of private resource for web workloads. It behaves similarly to a [public resource](/manage/resources/understanding-resources#public-resources) in that traffic is HTTP-based and flows through a reverse proxy with a proper hostname, but it only works when the user has an active Pangolin client connection. Nothing is exposed on the public internet; access is entirely off the internet until someone is on the tunnel. +Private HTTP/HTTPS resources expose web applications over the Pangolin tunnel with a fully qualified domain name. Unlike [public HTTP/HTTPS resources](/manage/resources/public/http-https), nothing is reachable from the public internet—a user must connect with the Pangolin client first. + +Once connected, users open the resource in a normal web browser at a URL like `https://my-app.internal.example.com`. The Pangolin client resolves the hostname privately, traffic travels over the peer-to-peer tunnel, and the site connector terminates TLS and runs a reverse proxy to the backend. + +For a deep dive into how private HTTPS reverse proxying works—including DNS hijacking, overlay addressing, certificate push, and the embedded edge proxy—see [Building a Peer-to-Peer Alternative to Cloudflare Tunnels](https://pangolin.net/news/building-a-peer-to-edge-peer-reverse-proxy). ## Hostname, DNS, and TLS -When you enable private HTTP, you assign a domain name to the resource. That hostname must be a domain you have already added and configured in Pangolin (see [Domains](/manage/domains)). This is analogous to an [alias](/manage/resources/private/alias) in that the client resolves the name through Pangolin and traffic is steered to the correct site, but it is not the same system: the name must be a real domain managed in your organization, not an arbitrary internal alias. +When you create a private HTTP/HTTPS resource, you assign a domain name. That hostname must be a domain you have already added and configured in Pangolin (see [Domains](/manage/domains)). This is analogous to an [alias](/manage/resources/private/alias) in that the client resolves the name through Pangolin and traffic is steered to the correct site, but it is not the same system: the name must be a real domain managed in your organization, not an arbitrary internal alias. -You can enable SSL on the resource so Pangolin obtains and serves a valid certificate for that hostname. When a connected user opens the site in a browser, the request is resolved to the site the same way as with alias-style flows, but a reverse proxy running on the site terminates TLS and proxies the request downstream to your [destination](/manage/resources/private/destinations). The Pangolin control plane provisions the routing and pushes certificates to the edge where your site runs, so users get normal HTTPS without certificate warnings. +Enable SSL on the resource so Pangolin obtains and serves a valid certificate for that hostname. When a connected user opens the site in a browser, a reverse proxy running on the site terminates TLS and proxies the request downstream to your [destination](/manage/resources/private/destinations). The Pangolin control plane provisions routing and pushes certificates to the site connector, so users get normal HTTPS without certificate warnings. ## Destination Fields @@ -31,4 +35,4 @@ You can approximate private browsing with a standard private resource by pairing A [public resource](/manage/resources/public/authentication) is reachable from the internet; Pangolin sits in front with authentication (for example platform SSO or other methods) so unauthenticated requests are blocked at the edge—the “bouncer” in front of a public site. -Private HTTP does not use that public forward-auth model for reachability. The hostname does not grant access from the open internet at all. The user must connect with the Pangolin client first, like a VPN, before the domain resolves and the reverse proxy will serve the app. Authentication on who may use the resource still follows your private resource access rules (users, roles, machines), but the network path is client-attached only. +Private HTTP does not use that public forward-auth model for reachability. The hostname does not grant access from the open internet at all. The user must connect with the Pangolin client first, like a VPN, before the domain resolves and the reverse proxy will serve the app. Instead of a login page at the edge, Pangolin uses the user's active client connection to determine their identity and enforces [private resource access rules](/manage/resources/private/authentication) (users, roles, machines) from that session. The network path is client-attached only. diff --git a/manage/resources/private/ssh.mdx b/manage/resources/private/ssh.mdx new file mode 100644 index 0000000..92da4cc --- /dev/null +++ b/manage/resources/private/ssh.mdx @@ -0,0 +1,70 @@ +--- +title: "SSH" +description: "Connect to remote hosts over the Pangolin tunnel using the Pangolin CLI" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + + +Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). + + +Private SSH resources let users connect to remote hosts from their terminal over the Pangolin tunnel. Unlike [public SSH resources](/manage/resources/public/ssh), private SSH is **not** browser-rendered. + +## How It Works + +1. The user connects with the Pangolin client (GUI or CLI). +2. They run `pangolin ssh ` where the alias matches the private resource. +3. Pangolin checks the user's identity from the active client connection and enforces [private resource access rules](/manage/resources/private/authentication) (users, roles, machines). +4. Depending on the SSH [configuration](/manage/ssh#configuration-options), Pangolin generates a short-lived certificate and provisions the user on the host, or the user authenticates with existing host credentials. +5. An SSH session opens through the tunnel. + +The Pangolin client provides the tunnel; the CLI handles certificate generation, user provisioning, and the SSH session itself. No manual SSH key distribution is required when using automated provisioning. + +```bash +pangolin ssh +``` + +The tunnel can be provided by the CLI or by another Pangolin client (for example the macOS app). You can run the GUI for the tunnel and use the CLI only for SSH. + +## Destination and Access + +Create a private resource with a [destination](/manage/resources/private/destinations) (IP or FQDN) for the host you want to SSH into. Assign an [alias](/manage/resources/private/alias) so users have a friendly name to pass to `pangolin ssh`. + +Grant access to users or roles and ensure **TCP 22** is allowed in [port restrictions](/manage/resources/private/port-restrictions). + + +If TCP 22 is not allowed in the resource's port restrictions, users will not be able to establish SSH sessions to that resource even when the rest of the setup is correct. + + +## Site and Host Configuration + +SSH private resources do **not** use discrete targets. Instead, you: + +1. Select which sites can route to the resource. +2. Enter the backend host and port—unless you selected **Pangolin SSH** mode, which executes sessions on the site connector host and does not require a host or port. + + +**Pangolin SSH mode requires root.** Newt must run as root on the site connector host. Use `sudo newt ...` or run the Newt systemd service as root. See [Install a site](/manage/sites/install-site). + + +Pangolin routes through the site that is online and healthiest. See [Multi-site Routing](/manage/resources/private/multi-site-routing). + +## SSH Configuration + +The SSH settings on a private resource use the same options as [public SSH resources](/manage/resources/public/ssh). Mode, authentication method, and auth daemon location are configured identically in the dashboard. + +See [SSH Access](/manage/ssh) for a full explanation of each option, setup instructions, and an example for every configuration combination. + +## How Private SSH Differs from Public SSH + +| | Private SSH | [Public SSH](/manage/resources/public/ssh) | +|---|-------------|--------------------------------------------| +| **Access** | Pangolin CLI: `pangolin ssh ` | Web browser at a public FQDN | +| **Client required** | Yes — user must be connected with the Pangolin client | No | +| **Auth layer** | Identity from the active client connection; [private resource access rules](/manage/resources/private/authentication) | [Public resource authentication](/manage/resources/public/authentication) — login page, SSO, access rules | +| **Manual auth step** | Credentials handled by the SSH client or certificate flow | Username/password or private key entered in a browser form after the public auth layer | +| **Hostname** | [Alias](/manage/resources/private/alias) on the private resource | Public FQDN on your Pangolin domain | +| **Port restrictions** | TCP 22 must be allowed in [port restrictions](/manage/resources/private/port-restrictions) | Not applicable | \ No newline at end of file diff --git a/manage/resources/public/authentication.mdx b/manage/resources/public/authentication.mdx index 7c1bc5d..bfda677 100644 --- a/manage/resources/public/authentication.mdx +++ b/manage/resources/public/authentication.mdx @@ -11,6 +11,8 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; 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. +You can configure these settings directly on each resource or share them across multiple resources with a [resource policy](/manage/resources/public/resource-policies). A resource either uses an inline policy (no shared policy attached) or inherits a shared policy and can add resource-specific overrides on top. + 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 @@ -39,4 +41,4 @@ Define ranked rules to either block or allow access from specific IPs, geolocati ## More -Read about more authentication options and specific settings in [Access Control](/manage/access-control/) and [Identity Providers](/manage/identity-providers/). +Read about more authentication options and specific settings in [Access Control](/manage/access-control/) and [Identity Providers](/manage/identity-providers/). To reuse the same authentication and access rule settings across many public resources, see [Resource Policies](/manage/resources/public/resource-policies). diff --git a/manage/resources/public/http-https.mdx b/manage/resources/public/http-https.mdx new file mode 100644 index 0000000..606a8b5 --- /dev/null +++ b/manage/resources/public/http-https.mdx @@ -0,0 +1,41 @@ +--- +title: "HTTP / HTTPS" +description: "Publish websites, APIs, and dashboards as authenticated public reverse proxies" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + +HTTP and HTTPS public resources are the most common public resource type. They expose a web application or API on a fully qualified domain name with a valid TLS certificate, fronted by Pangolin's authenticated reverse proxy. + +Users open the resource URL in any web browser. No Pangolin client is required. + +## How It Works + +1. You assign a FQDN on a domain managed in Pangolin. +2. Pangolin terminates TLS and applies [authentication and access rules](/manage/resources/public/authentication). +3. Authenticated requests are proxied through a site connector to your backend target. + +Pangolin acts as a front-door barrier: unauthenticated visitors are redirected to a Pangolin login page before traffic reaches your application. + +## Target Configuration + +HTTP/HTTPS resources use **[targets](/manage/resources/public/targets)** to define where traffic is sent on your remote network. + +- Add one or more targets, each with an upstream address and port. +- Assign each target to a site. Targets on different sites enable [round-robin load balancing](/manage/resources/public/targets#multi-site-targets) and [automatic failover](/manage/resources/public/healthchecks-failover). +- Optionally configure path-based routing, path rewriting, custom host headers, and other proxy settings. + +This multi-target model differs from SSH, RDP, and VNC public resources, which use site selection and a single host/port instead of discrete targets. + +## Authentication and Access Rules + +HTTP/HTTPS resources are protocol-aware and fully support Pangolin's identity and context policies: + +- Platform SSO and external identity providers +- User, role, and machine access assignments +- PIN, passcode, shareable links, and email OTP +- Ranked allow/deny rules for IP, geolocation, URL paths, and more + +See [Authentication](/manage/resources/public/authentication) for the full list of options. To share the same settings across multiple resources, use a [resource policy](/manage/resources/public/resource-policies). diff --git a/manage/resources/public/raw-resources.mdx b/manage/resources/public/raw-resources.mdx index 52f9337..a810b6d 100644 --- a/manage/resources/public/raw-resources.mdx +++ b/manage/resources/public/raw-resources.mdx @@ -1,13 +1,26 @@ --- -title: "TCP & UDP" -description: "Configure raw TCP and UDP traffic through Pangolin tunnels" +title: "TCP / UDP" +description: "Expose raw TCP and UDP services on a Pangolin server port without authentication" --- import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; +TCP and UDP public resources are protocol-agnostic proxies. Unlike HTTP/HTTPS, SSH, RDP, and VNC, they do **not** receive a fully qualified domain name or TLS certificate. Instead, each resource binds to a port on the Pangolin server host. Clients connect to `:` and traffic is forwarded to the downstream service through a site connector. +Because TCP and UDP resources are not protocol-aware, they do **not** enforce Pangolin authentication or access rules. They are simple pipes—use them only when you need a raw public proxy and accept that traffic is unauthenticated at the Pangolin layer. + +For workloads that do not need a public proxy, prefer a [private host or CIDR resource](/manage/resources/understanding-resources#private-resource-types) so traffic stays on the zero-trust tunnel with full access control. + +## Target Configuration + +TCP and UDP resources use **[targets](/manage/resources/public/targets)** like HTTP/HTTPS resources: + +- Add one or more targets with an upstream address and port. +- Assign targets to different sites for round-robin routing and failover. + +## Self-Hosted Setup This feature is only available in self-hosted Pangolin instances. If you're using Pangolin Cloud, you will need to deploy a remote node. @@ -15,7 +28,7 @@ This feature is only available in self-hosted Pangolin instances. If you're usin Pangolin supports raw TCP and UDP traffic because Newt can pass anything through the tunnel. -In Pangolin Community Edition, ensure you have the flag enabled in the config file: +In Community Edition or Enterprise Edition, ensure you have the flag enabled in the config file: ``` flags: diff --git a/manage/resources/public/rdp.mdx b/manage/resources/public/rdp.mdx new file mode 100644 index 0000000..e524102 --- /dev/null +++ b/manage/resources/public/rdp.mdx @@ -0,0 +1,37 @@ +--- +title: "RDP" +description: "Control a Windows computer remotely through a full RDP client rendered in the browser" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + + +Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). + + +RDP public resources render a full Remote Desktop Protocol client in the browser. Users visit a FQDN, complete Pangolin authentication, and get an interactive Windows desktop session—including file transfers, clipboard copy/paste, and standard RDP features—without installing remote desktop software. + +## How It Works + +1. You assign a FQDN on a domain managed in Pangolin. +2. The user completes [authentication and access rules](/manage/resources/public/authentication) in the browser. +3. Pangolin renders the RDP session and proxies traffic to the Windows host through a site connector. + +No Pangolin client is required. Any modern web browser is sufficient. + +## Site and Host Configuration + +RDP public resources do **not** use [targets](/manage/resources/public/targets). Instead, you: + +1. Select which sites can route to the resource. +2. Enter the backend Windows host and RDP port (default `3389`). + +Pangolin routes through the site that is online and healthiest, using the same intelligent multi-site routing model as [private resources](/manage/resources/private/multi-site-routing). + +## Authentication and Access Rules + +RDP public resources are protocol-aware and support the full set of Pangolin [authentication and access rules](/manage/resources/public/authentication), including platform SSO, identity providers, user/role assignments, and context-based allow/deny rules. You can share these settings across resources with a [resource policy](/manage/resources/public/resource-policies). + +RDP session credentials (Windows username and password) are entered in the browser-rendered client after Pangolin authentication succeeds. \ No newline at end of file diff --git a/manage/resources/public/resource-policies.mdx b/manage/resources/public/resource-policies.mdx new file mode 100644 index 0000000..eb6d434 --- /dev/null +++ b/manage/resources/public/resource-policies.mdx @@ -0,0 +1,94 @@ +--- +title: "Resource Policies" +description: "Share authentication and access rule settings across multiple public resources" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + + +Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). + + +Resource policies let you define authentication and access rule settings once and apply them to multiple public resources. Instead of configuring the same PIN code, user assignments, or geo-blocking rules on every resource individually, you attach a shared policy and every linked resource inherits those settings. + + +Resource policies currently apply to **public resources** only. Support for private resources is coming soon. + + +## What a Resource Policy Contains + +A resource policy holds the same settings you configure on a public resource's authentication and access tabs: + +**Authentication** + +- Platform SSO and external identity providers +- PIN and passcode +- User and role assignments +- Shareable links, access tokens, and email OTP + +**Access rules** + +- Ranked allow, deny, and pass-to-auth rules +- IP and CIDR matching +- [Geo-blocking](/manage/geoblocking) and [ASN blocking](/manage/asnblocking) +- URL path and other context-based conditions + +See [Authentication](/manage/resources/public/authentication) for a full overview of these options. + +## Shared Policies vs. Inline Policies + +Each public resource uses one of two modes: + +| Mode | Description | +| --- | --- | +| **Shared policy** | The resource inherits settings from a resource policy. Multiple resources can reference the same policy. | +| **None (inline policy)** | The resource keeps its own settings with no shared policy attached. The policy applies only to that resource. | + +Choose **None** when a resource needs a one-off configuration. Choose a shared policy when several resources should enforce the same baseline—for example, a standard login requirement and geo-blocking rules across every app in a team. + +## Additive Policies + +Shared policies are **additive**. A resource policy provides the base layer, and the resource itself can add settings on top. + +For example: + +1. A shared policy **denies** all countries. +2. You attach that policy to a public HTTP resource. +3. On the resource, you add an additional **allow** rule for a specific country. + +The resource-specific rule sits on top of the shared policy, so visitors from that country can pass through while everyone else remains blocked. The same pattern works for users, roles, IP allow lists, and other rule types. + +Use additive policies when most resources share a common baseline but individual resources need small exceptions. + +## Create a Resource Policy + +1. In the Pangolin dashboard, open the **Shared Policies** section for your organization. +2. Start the policy wizard to define authentication and access rule settings. +3. Save the policy with a descriptive name. + +You can edit a shared policy at any time from this section. Changes apply to every public resource that references the policy. + +## Apply a Policy to a Resource + +1. Open the public resource in the dashboard. +2. Go to the **General** tab. +3. Under **Shared Policy**, select the policy you want to attach—or choose **None** for an inline-only policy. + +Once a shared policy is attached, the resource inherits its settings immediately. + +## Editing Settings on a Resource with a Shared Policy + +When a shared policy is applied, settings defined on the shared policy are **read-only** on the resource. They appear grayed out or disabled, sometimes with a lock icon. You cannot change those values from the resource—you must edit the shared policy directly. + +You can still add settings on the resource that layer on top of the shared policy: + +- **Authentication** — add additional users and roles beyond what the shared policy grants +- **Access rules** — add additional allow, deny, or pass-to-auth rules + +These resource-specific additions are additive. They combine with the shared policy rather than replacing it, as described in [Additive Policies](#additive-policies). + + +If a setting on a resource looks locked, open the linked shared policy to change it. To make the resource fully self-contained again, set **Shared Policy** to **None** on the General tab. + \ No newline at end of file diff --git a/manage/resources/public/ssh.mdx b/manage/resources/public/ssh.mdx new file mode 100644 index 0000000..54a626d --- /dev/null +++ b/manage/resources/public/ssh.mdx @@ -0,0 +1,55 @@ +--- +title: "SSH" +description: "Access a remote shell in the browser with password, key, or Pangolin identity authentication" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + + +Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). + + +SSH public resources render a full interactive terminal in the browser. Users visit a FQDN—no SSH client or Pangolin desktop client is required. + +## How It Works + +1. You assign a FQDN on a domain managed in Pangolin. +2. The user completes [public resource authentication](/manage/resources/public/authentication) in the browser (platform SSO, identity providers, access rules, and so on). +3. Depending on the SSH [configuration](/manage/ssh#configuration-options) you chose, the user may be prompted for a second credential step or proceed directly into the terminal. +4. Pangolin renders the session and proxies traffic to the backend through a site connector. + +## Site and Host Configuration + +SSH public resources do **not** use [targets](/manage/resources/public/targets). Instead, you: + +1. Select which sites can route to the resource. +2. Enter the backend host and port—unless you selected **Pangolin SSH** mode, which executes sessions on the site connector host and does not require a host or port. + + +**Pangolin SSH mode requires root.** Newt must run as root on the site connector host. Use `sudo newt ...` or run the Newt systemd service as root. See [Install a site](/manage/sites/install-site). + + +Pangolin routes through the site that is online and healthiest, using the same intelligent multi-site routing model as [private resources](/manage/resources/private/multi-site-routing). + +## SSH Configuration + +The SSH settings on a public resource use the same options as [private SSH resources](/manage/resources/private/ssh). Mode, authentication method, and auth daemon location are configured identically in the dashboard. + +See [SSH Access](/manage/ssh) for a full explanation of each option, setup instructions, and an example for every configuration combination. + +## How Public SSH Differs from Private SSH + +| | Public SSH | [Private SSH](/manage/resources/private/ssh) | +|---|------------|----------------------------------------------| +| **Access** | Web browser at a public FQDN | Pangolin CLI: `pangolin ssh ` | +| **Client required** | No | Yes — user must be connected with the Pangolin client | +| **First auth layer** | [Public resource authentication](/manage/resources/public/authentication) — login page, SSO, access rules | Identity from the active client connection; [private resource access rules](/manage/resources/private/authentication) | +| **Hostname** | Public FQDN on your Pangolin domain | [Alias](/manage/resources/private/alias) on the private resource | + +## Authentication and Access Rules + +SSH public resources are protocol-aware and support the full set of Pangolin [authentication and access rules](/manage/resources/public/authentication). These rules gate who can reach the resource URL in the first place—before any SSH session or host credential prompt begins. + +You can configure these settings inline on the resource or attach a shared [resource policy](/manage/resources/public/resource-policies) and add resource-specific overrides on top. \ No newline at end of file diff --git a/manage/resources/public/vnc.mdx b/manage/resources/public/vnc.mdx new file mode 100644 index 0000000..df02486 --- /dev/null +++ b/manage/resources/public/vnc.mdx @@ -0,0 +1,37 @@ +--- +title: "VNC" +description: "View and control a remote display through a VNC client rendered in the browser" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + + +Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). + + +VNC public resources render a full VNC client in the browser. Users visit a FQDN, complete Pangolin authentication, and get an interactive remote display session without installing a VNC viewer. + +## How It Works + +1. You assign a FQDN on a domain managed in Pangolin. +2. The user completes [authentication and access rules](/manage/resources/public/authentication) in the browser. +3. Pangolin renders the VNC session and proxies traffic to the VNC server through a site connector. + +No Pangolin client is required. + +## Site and Host Configuration + +VNC public resources do **not** use [targets](/manage/resources/public/targets). Instead, you: + +1. Select which sites can route to the resource. +2. Enter the backend VNC server host and port (commonly `5900` or `5900 + display number`). + +Pangolin routes through the site that is online and healthiest, using the same intelligent multi-site routing model as [private resources](/manage/resources/private/multi-site-routing). + +## Authentication and Access Rules + +VNC public resources are protocol-aware and support the full set of Pangolin [authentication and access rules](/manage/resources/public/authentication), including platform SSO, identity providers, user/role assignments, and context-based allow/deny rules. You can share these settings across resources with a [resource policy](/manage/resources/public/resource-policies). + +VNC session credentials (if configured on the VNC server) are entered in the browser-rendered client after Pangolin authentication succeeds. \ No newline at end of file diff --git a/manage/resources/public/wildcard-resources.mdx b/manage/resources/public/wildcard-resources.mdx index c46c7f1..b103a1b 100644 --- a/manage/resources/public/wildcard-resources.mdx +++ b/manage/resources/public/wildcard-resources.mdx @@ -13,7 +13,7 @@ Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [En With a wildcard public resource, one resource owns an entire subdomain level: every hostname under that level is proxied through the same Pangolin resource and tunnel so downstream systems can route further (for example another reverse proxy or Kubernetes ingress). -Access rules and authentication you set on that resource apply to all hostnames matched by the wildcard. If you enable a PIN code, every hostname under the wildcard requires that PIN. +Access rules and authentication you set on that resource apply to all hostnames matched by the wildcard. If you enable a PIN code, every hostname under the wildcard requires that PIN. You can also attach a [resource policy](/manage/resources/public/resource-policies) so the same shared settings apply to the wildcard and any other linked public resources. ## Creating a Wildcard Resource diff --git a/manage/resources/understanding-resources.mdx b/manage/resources/understanding-resources.mdx index ebddc11..a96e4eb 100644 --- a/manage/resources/understanding-resources.mdx +++ b/manage/resources/understanding-resources.mdx @@ -7,69 +7,115 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; - - Resources represent 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 +## Resource Types -There are two types of resources: public resources and private resources. +There are two categories of resources: **public resources** and **private resources**. Each category supports different protocol types suited to how users connect. - - Reverse proxies to backend services - - Optionally have authentication - - Anyone with web browser can access + - Protocol-aware reverse proxies on the public internet + - Browser-based access for most types (no client required) + - Authentication and access rules on protocol-aware types - - Zero-trust VPN - - Access to every resource requires authentication - - Users and machines access when connected with a client + - Zero-trust VPN access over the Pangolin client + - Every resource requires authentication + - Not browser-rendered; requires a connected client -### Public Resources +### Public Resource Types + +Public resources create a public proxy on the Pangolin server. The protocol changes per type, but the overall model is the same: traffic enters through Pangolin and is forwarded to your backend on a remote site. + +HTTP/HTTPS, SSH, RDP, and VNC are all **browser-based**. You assign a fully qualified domain name (FQDN) to each resource and users open it in a web browser—no client-side software is required. Pangolin authentication and access rules protect all of these types the same way. You can configure those rules inline on each resource or share them through a [resource policy](/manage/resources/public/resource-policies). + +SSH, RDP, and VNC require a **Newt site**. HTTP/HTTPS and TCP/UDP resources can also run on local and basic WireGuard sites. + +TCP and UDP are the exception. They do not receive a FQDN. Instead, they bind to a port on the Pangolin server host and act as simple protocol-agnostic pipes to the downstream resource. Because they are not protocol-aware, they do not enforce Pangolin authentication or access rules. + + + + Websites, APIs, and dashboards behind an authenticated reverse proxy. + + + + Full terminal in the browser with password, key, or Pangolin identity (PAM). + + + + Full remote desktop in the browser, including file transfer and clipboard. + + + + Remote display session rendered entirely in the browser. + + + + Raw TCP proxy on a Pangolin server port. No authentication. + + + + Raw UDP proxy on a Pangolin server port. No authentication. + + + +#### Site Compatibility - Supported. + All public resource types supported. - Best option for most deployments. + Required for SSH, RDP, and VNC. - Supported. + HTTP/HTTPS and TCP/UDP only. - Use when the resource runs on the same host as your Pangolin server. + SSH, RDP, and VNC are not supported. - Limited support. + HTTP/HTTPS and TCP/UDP only. - Intended for more manual and advanced setups with feature limitations. + SSH, RDP, and VNC are not supported. -Public resources are protocol-aware and TCP/UDP proxies to services that are made available to the public internet. +### Private Resource Types -#### HTTPS Resources +Private resources require users to connect with the Pangolin client before any traffic can flow. Nothing is exposed on the public internet. Users gain access to all resources their account is permitted to use once connected. -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. + + + Route traffic to a single IP address or FQDN on the remote network. + -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.** + + Route traffic to an entire IP range, such as a subnet. + -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. + + Private reverse proxy with optional TLS termination at the site edge. + -#### Raw TCP/UDP Resources + + Traditional terminal SSH over the tunnel via `pangolin ssh`. + + -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. +Private resources can only be created on Newt sites. -Since these resources are not protocol aware and are publicly proxied, they do not support identity and context policies and rules. +**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 raw TCP/UDP traffic that does not need a public proxy, prefer a private host or CIDR resource over public TCP/UDP resources. -### Private Resources +Private resources support [aliases](/manage/resources/private/alias) for human-readable internal hostnames. When multiple sites can reach the same destination, Pangolin [intelligently routes](/manage/resources/private/multi-site-routing) traffic through the healthiest path. + +#### Site Compatibility @@ -90,11 +136,3 @@ Since these resources are not protocol aware and are publicly proxied, they do n Basic WireGuard sites can only host public 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 can only be created on Newt sites. - -**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/auto-update.mdx b/manage/sites/auto-update.mdx new file mode 100644 index 0000000..cd52662 --- /dev/null +++ b/manage/sites/auto-update.mdx @@ -0,0 +1,52 @@ +--- +title: "Automatic Site Updates" +description: "Let Newt sites check for and install updates on their own" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + + +Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). + + +Newt sites can automatically check for new versions, download the latest release, and restart to begin using it. This is useful when you manage many remote connectors and do not want to update each one by hand. + +## Supported Installation Methods + +Automatic updates are only supported for sites installed with the [binary installation method](/manage/sites/install-site). + +If you run Newt in Docker, Kubernetes, or another container orchestration platform, updates are handled by that platform. Pangolin cannot coordinate automatic updates for containerized deployments. + +## How It Works + +When automatic updates are enabled, Newt periodically checks for a newer version. If one is available, it downloads the latest release and restarts itself. After the restart, the site reconnects to Pangolin on the new version. + +For safety, Pangolin waits **24 hours** after a release is published before sites pull that version. This gives time for early issues to surface before a fleet of connectors updates. + +## Enable Automatic Updates + + +Automatic updates are disabled by default. You must opt in at the organization or site level. + + +You can control automatic updates at two levels: + +- **Organization**: Enable automatic updates for all sites under **Organization Settings**. +- **Per site**: Enable or disable automatic updates on an individual site. + +These settings work together: + +- Turn updates **off** for the organization and enable them on specific sites only. +- Turn updates **on** for the organization and disable them on specific sites that should stay on a fixed version. + +## Fleet Deployments + +Automatic updates are especially useful when you run many sites across edge networks. For example, if you have dozens or hundreds of Raspberry Pis or other edge devices running Newt, you would otherwise need to update each connector every time a new release ships. + +With automatic updates enabled, each site in the fleet checks for new versions on its own, downloads the latest release after the 24-hour safety window, restarts, and reconnects to Pangolin without manual intervention. + +## Use With Caution + +Automatic updates trade convenience for control. If you need predictable change windows or want to validate a release before rolling it out, keep automatic updates disabled and [update sites manually](/manage/sites/update-site) on your own schedule. diff --git a/manage/sites/understanding-sites.mdx b/manage/sites/understanding-sites.mdx index d2e9407..a0fda5e 100644 --- a/manage/sites/understanding-sites.mdx +++ b/manage/sites/understanding-sites.mdx @@ -29,9 +29,10 @@ This site type exposes resources on a remote network through a managed tunnel an Use Newt sites in most deployments. Newt is the primary connector type and supports the broadest feature set. Newt sites support: -- Public HTTPS proxied resources -- Private resources -- Load balancing +- Public proxied resources +- Protocol awareness (HTTP/HTTPS, SSH, RDP, VNC) +- Private resources (ZTNA) +- Load balancing and multi-site routing - Health checking - Docker socket scanning - And more diff --git a/manage/ssh.mdx b/manage/ssh.mdx index d8be60a..1d9e665 100644 --- a/manage/ssh.mdx +++ b/manage/ssh.mdx @@ -1,18 +1,18 @@ --- title: "SSH Access" -description: "Connect to remote servers via SSH using Pangolin identity and certificate-based authentication" +description: "SSH configuration, setup, and examples for public and private resources" --- import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; - +> */} @@ -20,81 +20,167 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). -## Overview +Pangolin SSH works on both [public](/manage/resources/public/ssh) and [private](/manage/resources/private/ssh) resources. The SSH configuration in the dashboard is identical for both—the difference is how users connect (browser vs. `pangolin ssh`) and which authentication layer gates access first. -Pangolin includes a built-in SSH client so you can connect to remote servers and manage them directly from the terminal. You use your existing Pangolin identity—no separate SSH keys to create or copy. Pangolin generates and signs temporary access keys, pushes them to the remote server, and creates or updates your user account there. All of this happens automatically when you start a connection. +This page explains the configuration options shared by both resource types, gives a concrete example for every valid combination, and walks through host setup for **Standard SSH Server** automated provisioning. -You can SSH into any Pangolin site or private resource. Two components handle SSH on the server side: +## Default Configuration (Easiest) - - - Runs as a daemon and handles SSH for the host it runs on. Use this when the machine you want to SSH into is the same server running Newt. - - - Handles SSH for other servers on the same network. Run the auth daemon on each target host; Newt on a bastion proxies connections to them. - - +When you create an SSH resource, the dashboard defaults to **Pangolin SSH** mode with **Manual Authentication**. This is the easiest path—it works out of the box with no auth daemon, no OpenSSH reconfiguration, and no extra host setup beyond running Newt as root. -You connect using the Pangolin CLI as the SSH client. The tunnel can be provided by the CLI or by another Pangolin client (e.g. the macOS app); you can run the GUI for the tunnel and use the CLI only for SSH if you prefer. +With these defaults: -## How certificates work +1. Create the SSH resource and select a site where Newt runs as root on the machine you want to access. +2. Leave mode as **Pangolin SSH** and authentication as **Manual Authentication**. +3. Users connect and authenticate with credentials that already exist on that host. -Each organization has a **certificate authority (CA)** used to sign temporary SSH keys. +On a [public resource](/manage/resources/public/ssh), users visit the resource FQDN, complete Pangolin authentication, then enter their host username and password (or private key) in the browser form. On a [private resource](/manage/resources/private/ssh), users connect with the Pangolin client and run `pangolin ssh username@`—Pangolin prompts for the host password. To use a private key instead, pass it with `-i`: `pangolin ssh username@ -i `. -1. When you run `pangolin ssh `, the Pangolin client generates a temporary key pair. -2. It sends the public key to the Pangolin server with your identity and the target resource. -3. The server checks that you are allowed to access that resource, then signs the public key with the organization CA and returns it. The CA public key is also sent to the remote server and trusted there. -4. The client connects to the remote host using the temporary private key. The host verifies the certificate with the CA and uses principals in the certificate for access control. +That is the entire setup for the default preset. If you need Pangolin identities provisioned automatically on the host—without password prompts—switch to **Automated Provisioning**. With **Pangolin SSH** mode, that also works without OpenSSH or auth daemon configuration—Newt still must run as root. With **Standard SSH Server** mode, follow the host setup sections below. + +## Configuration Options + +SSH resources are configured through three decisions in the dashboard. + +### Mode + +| Option | Description | +|--------|-------------| +| **Pangolin SSH (Recommended)** | Executes commands directly on the host via the site connector. No network SSH server is required, and you do not enter a host or port. Newt must run as root (`sudo newt ...`). | +| **Standard SSH Server** | Routes commands over the network to an SSH server such as OpenSSH. Enter the backend host and port. To use automated provisioning (PAM) with this mode, you must configure OpenSSH to accept Pangolin certificates and connections. This mode also supports a remote auth daemon for pushing users to machines on the same network as the site connector that are not running the connector itself. | + + +**Pangolin SSH mode requires root.** Newt must run as root on the site connector host. Use `sudo newt ...` or run the Newt systemd service as root. See [Install a site](/manage/sites/install-site). + + +### Authentication Method + +| Option | Description | +|--------|-------------| +| **Manual Authentication** | Requires existing host credentials and bypasses automatic user provisioning. On [public resources](/manage/resources/public/ssh), users enter a username and password or upload a private key in a browser form after completing the public authentication layer. On [private resources](/manage/resources/private/ssh), credentials are handled by the SSH client. | +| **Automated Provisioning** | Automatically creates users, groups, and sudo permissions on the host based on Pangolin identity (PAM). Requires auth daemon and OpenSSH configuration on the target host. | + +### Auth Daemon Location + +Only shown when **Automated Provisioning** is selected. + +| Option | Description | +|--------|-------------| +| **On Site** | The auth daemon runs on the machine hosting the site connector. Use when the connector and target SSH host are the same machine, or when the connector handles provisioning locally. | +| **On Remote Host** | The auth daemon runs on a separate target machine on the same network. Use when the site connector is a bastion and each target host runs its own auth daemon. Only applies with **Standard SSH Server** mode. | + +### Daemon Port + +When the auth daemon runs on a remote host, set the port it listens on (default `22123`). This must match the `--port` flag used when starting the auth daemon. Newt and the auth daemon communicate over HTTPS on this port within your internal network. + + +Ensure your target host is properly configured to run the auth daemon before completing setup, or provisioning will fail. + + +## Configuration Examples + +There are five valid configuration combinations. Auth daemon location is not applicable when using manual authentication. + +### 1. Pangolin SSH + Manual Authentication + +**Settings:** Mode = Pangolin SSH · Authentication = Manual + +**When to use:** You want the simplest setup. The site connector runs on the machine you need to access, and users already have local accounts with passwords or keys on that host. + +**Example:** A small team exposes a staging server that runs Newt. You create a public SSH resource with Pangolin SSH and manual authentication. Developers visit `https://staging-ssh.example.com`, pass Pangolin login, then enter their existing Linux username and password in the browser form. No OpenSSH reconfiguration or auth daemon is needed on the host—run Newt as root. + +**Host setup required:** Run Newt as root on the site connector host (`sudo newt ...`). + +--- + +### 2. Pangolin SSH + Automated Provisioning + On Site + +**Settings:** Mode = Pangolin SSH · Authentication = Automated Provisioning · Auth Daemon = On Site + +**When to use:** The site connector runs on the machine you want to access, and you want Pangolin identities mapped to local users automatically—no password prompts and no separate SSH server routing. + +**Example:** Your production app server runs Newt. You create a private SSH resource with an alias `prod-app.internal` and configure Pangolin SSH with automated provisioning on site. Developers connect with the Pangolin client and run `pangolin ssh prod-app.internal`. Pangolin provisions their account on the fly from their organization identity. + +**Host setup required:** Run Newt as root on the site connector host. Pangolin SSH handles provisioning through the site connector directly. + +--- + +### 3. Standard SSH Server + Manual Authentication + +**Settings:** Mode = Standard SSH Server · Authentication = Manual + +**When to use:** You need to reach an existing OpenSSH server on the network and users will authenticate with credentials already configured on that server. + +**Example:** A legacy database server at `10.0.5.20` runs standard OpenSSH with per-user keys. You create a public SSH resource pointing at `10.0.5.20:22` with manual authentication. DBAs visit the resource FQDN, complete Pangolin authentication, then upload their private key in the browser form to open a terminal session. If the same host is reachable from multiple site connectors, select all applicable sites—Pangolin routes through the healthiest one automatically. + +**Host setup required:** None—use your existing OpenSSH configuration. + +--- + +### 4. Standard SSH Server + Automated Provisioning + On Site + +**Settings:** Mode = Standard SSH Server · Authentication = Automated Provisioning · Auth Daemon = On Site + +**When to use:** OpenSSH runs on the same machine as the site connector, but you want network SSH routing (Standard SSH Server mode) with Pangolin identity provisioning instead of Pangolin SSH mode. + +**Example:** Newt runs on your production app server. OpenSSH also listens on that host. You create a private SSH resource with destination `localhost`, allow TCP 22 in [port restrictions](/manage/resources/private/port-restrictions), and assign an alias such as `prod-app.internal`. Configure Standard SSH Server mode pointing at `127.0.0.1:22`, automated provisioning, and auth daemon on site. Engineers run `pangolin ssh prod-app.internal` and land on the same machine running Newt with a provisioned account. + +**Host setup required:** Run Newt and configure OpenSSH on the same host. Newt runs as an auth daemon by default. No extra flag is needed. See [Option 1](#option-1-newt-as-the-auth-daemon-same-host). + +--- + +### 5. Standard SSH Server + Automated Provisioning + On Remote Host + +**Settings:** Mode = Standard SSH Server · Authentication = Automated Provisioning · Auth Daemon = On Remote Host + +**When to use:** The site connector runs on a bastion, and you need to SSH into multiple other servers on the same network that do not run Newt. This is the most common automated provisioning setup for multi-server environments. + +**Example:** Newt runs on `bastion.corp.internal`. You have application servers `app-01` and `app-02` on the same VLAN. For `app-01`, you create a private SSH resource with destination `10.0.5.21` (the IP of the OpenSSH server on the remote host), allow TCP 22 in [port restrictions](/manage/resources/private/port-restrictions), and assign alias `app-01.corp.internal` as the domain name users connect with. Configure Standard SSH Server mode with host `10.0.5.21:22`, automated provisioning, and auth daemon on remote host (daemon port `22123`). Each app server runs `pangolin auth-daemon`. Developers run `pangolin ssh app-01.corp.internal`—the client tunnels through Newt, which proxies SSH to the OpenSSH server and coordinates with the auth daemon on that host to provision the user. + +**Host setup required:** Newt on the bastion with a pre-shared key, auth daemon on each target host, OpenSSH configured on each target. See [Option 2: External auth daemon](#option-2-external-auth-daemon-ssh-on-another-server-that-doesnt-run-newt). + +--- + + +**Pangolin SSH + Automated Provisioning + On Remote Host** is not a valid combination. Pangolin SSH executes sessions on the site connector host itself, so the auth daemon must run on site. Use **Standard SSH Server** mode when the auth daemon runs on a remote host. + + +## How Certificates Work + +When using automated provisioning, each organization has a **certificate authority (CA)** used to sign temporary SSH keys. This is only used for automated provisioning on Standard SSH Server mode. Pangolin SSH doesn't use standard SSH certificates and instead uses its own authentication layer. + +1. The user initiates a connection (browser for public resources, `pangolin ssh ` for private). +2. Pangolin generates a temporary key pair and sends the public key to the Pangolin server with the user's identity and target resource. +3. The server checks access, signs the public key with the organization CA, and returns it. The CA public key is sent to the remote server and trusted there. +4. The client connects using the temporary private key. The host verifies the certificate with the CA and uses principals in the certificate for access control. This gives short-lived, auditable access without long-lived keys on the server. -## How users and access are managed +## How Users and Access Are Managed -Users are provisioned **just in time** on the remote system. When you connect, Pangolin ensures an account exists for you with the right permissions before the SSH session starts. Your Pangolin identity is mapped to a local username (derived from the part before `@` in your identity; if needed, a suffix is added for uniqueness). The account is created with a home directory and can be granted sudo access as configured. +When using **Standard SSH Server** with automated provisioning, users are provisioned **just in time** on the remote system. When you connect, Pangolin ensures an account exists for you with the right permissions before the SSH session starts. Your Pangolin identity is mapped to a local username (derived from the part before `@` in your identity; if needed, a suffix is added for uniqueness). The account is created with a home directory and can be granted sudo access as configured. -## Setup: choose your architecture +With **Pangolin SSH** and automated provisioning, Pangolin handles user provisioning through the site connector directly—no OpenSSH or auth daemon setup required on the host. Newt must still run as root. -You can enable SSH in two ways: +## Host Setup -| Scenario | Approach | -|----------|----------| -| SSH into the **same server** that runs Newt | **Option 1**: Run Newt with auth-daemon support (built-in). | -| SSH into **other servers** on the same network as Newt | **Option 2**: Run Newt on one host (e.g. bastion) and run the auth daemon on each server you want to SSH into. | +Host setup is only required for **Standard SSH Server** mode with **Automated Provisioning**. **Pangolin SSH** mode (manual or automated) requires Newt to run as root on the site connector host but does not require OpenSSH or auth daemon configuration. -A single Newt instance can run as **both** the auth daemon for its own host **and** use external auth daemons. +| Configuration | Setup path | +|---------------|------------| +| Standard SSH Server + Automated + On Site | [Option 1](#option-1-newt-as-the-auth-daemon-same-host) | +| Standard SSH Server + Automated + On Remote Host | [Option 2](#option-2-external-auth-daemon-ssh-on-another-server-that-doesnt-run-newt) | -Both options require the SSH server on each target host to be configured to trust the Pangolin CA and to use the auth daemon for principals (see [Configure the SSH server](#configure-the-ssh-server-on-the-host) below). You also need a **private resource** on the site for each host you want to SSH into (see below). - -## Create a private resource (required) - -SSH access in both Option 1 and Option 2 is scoped to a private resource. You must create a private resource on the site for the host (or each host) you want to SSH into, then grant access and allow TCP 22. - -1. **Create a private resource** on the site in the Pangolin dashboard. The resource should target the host that will run Newt (Option 1) or the host that will run the auth daemon (Option 2). Give it a destination (IP or FQDN of the server). You can use an [alias](/manage/resources/private/alias) (e.g. `vm-01.prod.example.com`) so users connect with a friendly name: `pangolin ssh vm-01.prod.example.com`. - -2. **Grant access** to the resource by assigning **users** or **roles** in the resource’s access settings. Only users or roles with access can obtain SSH certificates and connect. - -3. **Allow TCP 22 in port restrictions.** In the private resource’s port restrictions, ensure **TCP 22** is allowed so SSH traffic is permitted through the tunnel. Without this, SSH connections to the resource will be blocked. - - -If TCP 22 is not allowed in the resource’s port restrictions, users will not be able to establish SSH sessions to that resource even when the rest of the setup is correct. - - -4. **Configure the auth daemon location.** On the SSH Access tab, select where the auth daemon is running. Is it on the Newt site itself (option 1) or a remote host (option 2)? - - - Pangolin Dashboard - - -After the resource exists and access is granted, proceed with [Option 1](#option-1-newt-as-the-auth-daemon-same-host) or [Option 2](#option-2-external-auth-daemon-ssh-on-another-server-that-doesnt-run-newt) below. +Before setting up the host, create the SSH resource (public or private) in the dashboard, grant access, and for private resources allow TCP 22 in [port restrictions](/manage/resources/private/port-restrictions). ## Option 1: Newt as the auth daemon (same host) -Use this when the machine you want to SSH into **is** the machine running Newt (e.g. the site connector and SSH are on the same server). +Use this for combination **4**—when the auth daemon runs on the site connector host and you are routing to OpenSSH in Standard SSH Server mode. ```mermaid flowchart LR subgraph client["User machine"] - CLI[Pangolin CLI] + CLI[Pangolin CLI / Browser] end subgraph cloud["Pangolin Cloud"] @@ -112,12 +198,12 @@ flowchart LR CLI -->|SSH port 22| SSHD ``` -### Run Newt with auth-daemon enabled +### Run Newt -With Newt [installed](/manage/sites/install-site), run it in auth-daemon mode so it can handle SSH on this host: +With Newt [installed](/manage/sites/install-site), run it normally. Newt runs as an auth daemon by default: ```bash -sudo newt --id --secret --endpoint --auth-daemon +sudo newt --id --secret --endpoint ``` @@ -128,12 +214,12 @@ Then configure the SSH server on this host as described in [Configure the SSH se ## Option 2: External auth daemon (SSH on another server that doesn't run Newt) -Use this when you want to SSH into servers that **do not** run Newt. One host runs Newt (e.g. as a bastion); each target server runs the Pangolin auth daemon as an extension of Newt. The client connects to the target by going **through** Newt—Newt proxies the SSH connection to the auth daemon and SSH server on each target. +Use this for combination **5**—when the site connector is a bastion and each target host runs its own auth daemon. ```mermaid flowchart LR subgraph client["User machine"] - CLI[Pangolin CLI] + CLI[Pangolin CLI / Browser] end subgraph cloud["Pangolin Cloud"] @@ -159,7 +245,7 @@ flowchart LR ### Prerequisites -- **Newt** running on one host (the “site” / bastion) with auth-daemon support and a pre-shared key for external auth daemons. +- **Newt** running on one host (the site / bastion) with a pre-shared key for external auth daemons. - **Pangolin CLI** installed on each server where you will run the auth daemon. See [Install Clients — Quick Install (Recommended)](/manage/clients/install-client#quick-install-recommended). ### Step 1: On the server running Newt @@ -182,7 +268,7 @@ On every host that should accept Pangolin SSH (and is not running Newt), run the sudo pangolin auth-daemon --pre-shared-key ``` -To use a non-default port, add `--port ` and set the same port in the resource’s SSH settings in the dashboard. +To use a non-default port, add `--port ` and set the same port in the resource's SSH settings in the dashboard. #### Run as a systemd service @@ -202,7 +288,7 @@ User=root WantedBy=multi-user.target ``` -Replace `` with the same value used on Newt. If you use a custom port (set in the resource’s SSH settings), add `--port ` to `ExecStart`. Then: +Replace `` with the same value used on Newt. If you use a custom port (set in the resource's SSH settings), add `--port ` to `ExecStart`. Then: ```bash sudo systemctl daemon-reload @@ -217,16 +303,12 @@ Ensure the Pangolin CLI binary is at `/usr/local/bin/pangolin` (or update `ExecS ### Step 3: Configure the SSH server on each target host -On each of these hosts, configure the SSH server as in [Configure the SSH server on the host](#configure-the-ssh-server-on-the-host). Use the `pangolin auth-daemon principals` command in `AuthorizedPrincipalsCommand` (see that section for the exact line). +On each of these hosts, configure the SSH server as in [Configure the SSH server on the host](#configure-the-ssh-server-on-the-host). Use the `pangolin auth-daemon principals` command in `AuthorizedPrincipalsCommand`. ### Step 4: Ensure network connectivity -- **Newt → auth daemon:** Newt must be able to reach the auth daemon port on each target server (default **TCP 22123**; configurable in the resource’s SSH settings and via the auth daemon’s `--port` flag). -- **Clients → SSH:** Port **22** must be open for SSH to each target server (from wherever your users connect—often only within your private network). - - -To change the auth daemon port from the default 22123, configure the port in the resource’s SSH settings in Pangolin and pass the same port with `--port` when starting the auth daemon. - +- **Newt → auth daemon:** Newt must be able to reach the auth daemon port on each target server (default **TCP 22123**). +- **Clients → SSH:** Port **22** must be open for SSH to each target server. These ports do not need to be exposed to the public internet. They only need to be reachable within the network where Newt and the target servers live. @@ -234,16 +316,16 @@ These ports do not need to be exposed to the public internet. They only need to ## Configure the SSH server on the host -For both Option 1 and Option 2, the host’s SSH server must trust the Pangolin CA and use the auth daemon to resolve principals. Do the following on **every** host that will accept Pangolin SSH (the host running Newt in Option 1, or each host running the external auth daemon in Option 2). +For automated provisioning, the host's SSH server must trust the Pangolin CA and use the auth daemon to resolve principals. Do the following on **every** host that will accept Pangolin SSH. ### 1. Update `sshd_config` Add or adjust these lines in `/etc/ssh/sshd_config`: -- **Option 1 (Newt on this host):** use `newt auth-daemon principals` in the command. -- **Option 2 (external auth daemon on this host):** use `pangolin auth-daemon principals` in the command. +- **Auth daemon on this host (Newt):** use `newt auth-daemon principals` in the command. +- **External auth daemon on this host:** use `pangolin auth-daemon principals` in the command. -Example for **Option 1** (Newt on same host): +Example for **auth daemon on site** (Newt on same host): ```ini title="/etc/ssh/sshd_config" TrustedUserCAKeys /etc/ssh/ca.pem @@ -251,7 +333,7 @@ AuthorizedPrincipalsCommand /usr/local/bin/newt auth-daemon principals --usernam AuthorizedPrincipalsCommandUser root ``` -Example for **Option 2** (external auth daemon on this host): +Example for **external auth daemon on this host**: ```ini title="/etc/ssh/sshd_config" TrustedUserCAKeys /etc/ssh/ca.pem @@ -265,40 +347,38 @@ AuthorizedPrincipalsCommandUser root sudo systemctl restart ssh ``` -After this, users with access to the resource in Pangolin can run `pangolin ssh ` to connect. +After this, users with access to the resource can connect via the browser (public) or `pangolin ssh ` (private). -## Signing keys for other applications +## Signing Keys for Other Applications -You can ask Pangolin to sign a key for a resource without starting an interactive SSH session. Useful for scripts or tools that use SSH with a specific key: +You can ask Pangolin to sign a key for a resource without starting an interactive SSH session: ```bash pangolin ssh sign vm-01.prod.example.com --key-file /path/to/public/key.pub ``` -## Generating passwords for users +## Generating Passwords for Users -If you need a password to be generated for your user on the remote system (e.g. for sudo access or if you have passwords required in your sshd config), you can use: - -`--ad-generate-random-password` to have Pangolin generate a random password when users are created on the device +If you need a password generated for your user on the remote system (for example for sudo access), use `--ad-generate-random-password` to have Pangolin generate a random password when users are created on the device. ## FAQ ### How long are the temporary keys valid? -When the client requests a signed key from the Pangolin server, the certificate is valid for **5 minutes**. You must start the SSH connection within that window. Once the session is established, it can stay open; the certificate is only needed for the initial authentication. +When the client requests a signed key from the Pangolin server, the certificate is valid for **5 minutes**. You must start the SSH connection within that window. Once the session is established, it can stay open. ### Is the SSH connection proxied through Newt? -**Option 1 (same host):** No. Your client connects directly to the server that runs Newt; SSH traffic does not go through another hop. +**Pangolin SSH mode or auth daemon on site:** Your client connects directly to the server that runs Newt; SSH traffic does not go through another hop. -**Option 2 (external auth daemon):** Yes. Your client connects to Newt, and Newt proxies the SSH session to the target server. The auth daemon on each target is an extension of Newt and works with it to complete the connection. +**Standard SSH Server + remote auth daemon:** Your client connects to Newt, and Newt proxies the SSH session to the target server. The auth daemon on each target is an extension of Newt. ### How are usernames created on the remote server? -Pangolin derives the remote username from your Pangolin identity (the part before `@`). If that name is already taken in the organization, a numeric suffix is added until it is unique. The user is created with a home directory and can be added to sudoers as configured by your organization. +Pangolin derives the remote username from your Pangolin identity (the part before `@`). If that name is already taken in the organization, a numeric suffix is added until it is unique. ### How does Newt communicate with the external auth daemon? -Newt talks to the auth daemon over **HTTPS**. **TCP 22123** is used by default. When you SSH into a server that uses the external auth daemon, Newt calls the auth daemon on that host to create or update your user and resolve principals. Port 22123 only needs to be open between Newt and the auth daemon hosts on your internal network; it should not be exposed to the internet. +Newt talks to the auth daemon over **HTTPS** on **TCP 22123** by default. Port 22123 only needs to be open between Newt and the auth daemon hosts on your internal network. -To use a different port, set the port in the resource’s SSH settings in the Pangolin dashboard and pass the same port to the auth daemon with the `--port` flag (e.g. `pangolin auth-daemon --pre-shared-key --port 22124`). Newt and the auth daemon must use the same port. +To use a different port, set the port in the resource's SSH settings and pass the same port to the auth daemon with `--port`. diff --git a/self-host/advanced/container-cli-tool.mdx b/self-host/advanced/container-cli-tool.mdx index f7cf56c..2653841 100644 --- a/self-host/advanced/container-cli-tool.mdx +++ b/self-host/advanced/container-cli-tool.mdx @@ -39,6 +39,29 @@ docker exec -it pangolin pangctl set-admin-credentials --email "admin@example.co Use a strong password and keep your admin credentials secure. +## Set Server Admin + +Add or remove server admin status for a user by email address: + +```bash +docker exec -it pangolin pangctl set-server-admin --email "admin@example.com" +``` + +To remove server admin status: + +```bash +docker exec -it pangolin pangctl set-server-admin --email "admin@example.com" --remove +``` + +### Options + +- `--email` (required): User email address +- `--remove` (optional, default: `false`): Remove server admin status from the user + + +At least one server admin must always exist. The command fails if you try to remove server admin status from the last remaining server admin. + + ## Clear Exit Nodes Clear all exit nodes from the database: @@ -63,6 +86,22 @@ docker exec -it pangolin pangctl reset-user-security-keys --email "user@example. This command permanently deletes all security keys for the specified user. The user will need to re-register their security keys to use passkey authentication again. +## Disable User 2FA + +Disable two-factor authentication for a user by email address. Sets `twoFactorEnabled` to false and clears the user's 2FA secret: + +```bash +docker exec -it pangolin pangctl disable-user-2fa --email "user@example.com" +``` + +### Options + +- `--email` (required): User email address + + +This command disables 2FA for the specified user and clears their stored 2FA secret. The user can re-enable 2FA from their account settings after signing in. + + ## Rotate Server Secret Rotate the server secret by decrypting all encrypted values with the old secret and re-encrypting with a new secret. This command updates OIDC IdP configurations and license keys in the database, as well as the config file. @@ -133,7 +172,7 @@ Generate an SSH CA public/private key pair for an organization and store them in docker exec -it pangolin pangctl generate-org-ca-keys --orgId "org-123" ``` -## Clear certificates +## Clear Certificates Clear all certificates from the database to be reinserted by the server when syncing from acme.json files or using Pangolin DNS.