From 0e35e64892ff162810fe55ed8e3bc292b84c9eee Mon Sep 17 00:00:00 2001 From: Owen Date: Mon, 12 Oct 2026 16:14:47 -0400 Subject: [PATCH] Add use benefits, use cases, and how to on each section --- .../docs/manage/access-control/approvals.mdx | 19 ++++++++++++++ content/docs/manage/alerting/alert-rules.mdx | 25 +++++++++++++++++++ content/docs/manage/blueprints.mdx | 20 ++++++++++++--- .../manage/resources/private/ai-gateway.mdx | 15 +++++++++++ .../docs/manage/resources/private/cidr.mdx | 22 ++++++++++++++++ .../docs/manage/resources/private/host.mdx | 22 ++++++++++++++++ .../resources/private/multi-site-routing.mdx | 13 ++++++++++ .../manage/resources/private/private-http.mdx | 22 ++++++++++++++++ content/docs/manage/resources/private/ssh.mdx | 15 +++++++++++ .../manage/resources/public/ai-gateway.mdx | 14 +++++++++++ .../public/healthchecks-failover.mdx | 13 ++++++++++ .../manage/resources/public/http-https.mdx | 17 +++++++++++++ .../manage/resources/public/maintenance.mdx | 12 +++++++++ .../manage/resources/public/raw-resources.mdx | 22 ++++++++++++++++ content/docs/manage/resources/public/rdp.mdx | 14 +++++++++++ .../resources/public/resource-policies.mdx | 17 +++++++++++++ content/docs/manage/resources/public/ssh.mdx | 14 +++++++++++ content/docs/manage/resources/public/vnc.mdx | 13 ++++++++++ .../resources/public/wildcard-resources.mdx | 20 +++++++++++++++ content/docs/manage/ssh.mdx | 24 ++++++++++++++++++ 20 files changed, 349 insertions(+), 4 deletions(-) diff --git a/content/docs/manage/access-control/approvals.mdx b/content/docs/manage/access-control/approvals.mdx index 7072b8d..e694379 100644 --- a/content/docs/manage/access-control/approvals.mdx +++ b/content/docs/manage/access-control/approvals.mdx @@ -20,6 +20,25 @@ All approvals can also be managed from a central page as they stream in to allow Approvals page listing pending devices in the Pangolin dashboard +## Benefits + +- Stolen or phished credentials aren't enough to connect from an unknown device. +- Admins see every new device before it can reach resources. +- Approvals are set per role, so you can require them for some groups and not others. + +## Use Cases + +- Only allow company-issued laptops to connect, not personal devices. +- Require approval for contractor roles while employees connect freely. +- Catch an unexpected new device on a user's account before it reaches sensitive resources. + +## How Device Approvals Work + +1. A user in a role that requires approval connects a device for the first time. +2. The device shows as Pending Approval and can't reach any organization resources. +3. An admin approves or denies it from the device or the approvals page. +4. Once approved, the device connects normally. Devices that were already approved aren't asked again. + ## Enabling Device Approvals Device approvals are enabled on a per-role basis. To enable device approvals for a role, follow these steps: diff --git a/content/docs/manage/alerting/alert-rules.mdx b/content/docs/manage/alerting/alert-rules.mdx index be28884..3a9b1b0 100644 --- a/content/docs/manage/alerting/alert-rules.mdx +++ b/content/docs/manage/alerting/alert-rules.mdx @@ -9,6 +9,31 @@ Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [En Alert rules let you react to changes in Pangolin: you pick a source (what to watch), a trigger (which change matters), and one or more actions (what to do). For example, when a site moves from online to offline, email your admins and support; when a [health check](/manage/alerting/health-checks) or resource becomes unhealthy, call a webhook so a tool like Zapier can fan out the event. +## Benefits + +- Find out about outages as they happen instead of from users. +- Send alerts where your team already works: email, webhooks, or PagerDuty, Opsgenie, ServiceNow, and incident.io. +- One rule can watch every site or resource, or only the ones you pick. +- Health checks run from your sites, so alerts reflect what is reachable on the remote network. + +## Use cases + +- Page on-call when a production site goes offline. +- Email a branch office's IT contact when their site connector drops. +- Open an incident when a public resource's targets all become unhealthy. +- Watch printers, cameras, or legacy servers with arbitrary health checks and alert when they stop responding. +- Send events to a webhook to post in chat or trigger automation. + +## How alert rules work + +Each rule has three parts: + +1. A source: the sites, resources, or health checks to watch. +2. A trigger: the state change that matters, such as going offline or becoming unhealthy. +3. One or more actions: what Pangolin does when the trigger fires. + +When a watched entity changes state and matches the trigger, Pangolin runs every action on the rule. + ## Where to create rules Create and manage rules from the Alert rules page under Alerting for your organization. diff --git a/content/docs/manage/blueprints.mdx b/content/docs/manage/blueprints.mdx index 499769e..70f433b 100644 --- a/content/docs/manage/blueprints.mdx +++ b/content/docs/manage/blueprints.mdx @@ -5,11 +5,23 @@ description: "Define Pangolin resources and site settings declaratively with YAM Blueprints let you define Pangolin resources as code. Instead of configuring every site, target, and access rule manually in the dashboard, you describe the desired state in YAML or container labels and let Pangolin apply it consistently. -Use blueprints when you want: +## Benefits -- Repeatable rollouts across many sites -- Version control for infrastructure and access settings -- A source of truth that can be reviewed, templated, and automated +- Roll out the same resources and access settings across many sites without repeating dashboard work. +- Keep infrastructure and access settings in version control, where changes can be reviewed and rolled back. +- Template and automate configuration from CI, scripts, or provisioning tools. +- Keep a resource's definition next to the container it exposes with container labels. + +## Use Cases + +- Stamp out an identical set of resources for every store, branch office, or customer site. +- Manage Pangolin resources through pull requests in a GitOps workflow. +- Define resources next to the Docker Compose services they expose, using container labels. +- Bootstrap new sites with their resources during provisioning. + +## How Blueprints Work + +You describe the desired state in YAML or container labels and apply it through the dashboard, a site, the API, or the CLI. Pangolin matches each entry to an existing site, resource, or policy by its key and creates or updates it to match. A blueprint applied from a site file or container labels acts as an ongoing source of truth, while dashboard, API, and CLI applies are one-off. See [How YAML Blueprints Are Applied](#how-yaml-blueprints-are-applied). Some features in this documentation are marked with **(EE)**, which means they require [Enterprise Edition](/self-host/enterprise-edition). diff --git a/content/docs/manage/resources/private/ai-gateway.mdx b/content/docs/manage/resources/private/ai-gateway.mdx index 8410e92..e956195 100644 --- a/content/docs/manage/resources/private/ai-gateway.mdx +++ b/content/docs/manage/resources/private/ai-gateway.mdx @@ -7,6 +7,21 @@ A private AI Gateway resource exposes an AI API only to devices connected with t This page covers how the **resource** works: reachability, access, and what you attach. Providers, model routing, the catalog, and client setup live in [AI Gateway](/manage/ai/overview). +## Benefits + +- The gateway is never reachable from the public internet, only from connected clients with access. +- There are no API keys to issue or leak. The client connection identifies the caller. +- Provider API keys stay in Pangolin and never reach users' machines. +- Calls are attributed to the connected user, so [usage analytics](/manage/ai/usage-analytics) and [session logs](/manage/ai/session-logs) show who made each one. +- Self-hosted model servers on a site network can sit behind the same gateway as cloud providers. + +## Use Cases + +- Give employees Claude Code, Codex, or other coding agents through company provider accounts without handing out provider keys. +- Keep AI access limited to managed devices that run the Pangolin client. +- Serve a self-hosted model, such as one running on Ollama or vLLM, to your team without exposing it to the internet. +- Give machine clients, such as CI jobs or internal agents, model access tied to their own identity. + ## How It Works 1. You create a private resource with type **AI Gateway** on a Pangolin Site and attach one or more org-level [providers](/manage/ai/providers/overview). diff --git a/content/docs/manage/resources/private/cidr.mdx b/content/docs/manage/resources/private/cidr.mdx index d9bf36e..604f792 100644 --- a/content/docs/manage/resources/private/cidr.mdx +++ b/content/docs/manage/resources/private/cidr.mdx @@ -7,6 +7,28 @@ A CIDR private resource exposes an entire IP range on your remote network to con CIDR resources are the usual choice for whole subnets or network segments instead of creating a separate host resource for every machine. +## Benefits + +- One resource covers a whole subnet, so you don't have to create a resource for every machine. +- Hosts added to the range later are reachable right away, with no change in Pangolin. +- Access is still granted per user, role, or machine client, and port restrictions apply to the whole range. +- Attaching several sites that reach the same range gives redundant paths with automatic failover. +- CIDR resources are the building block for [subnet routers](/manage/clients/subnet-router), which give devices that can't run the client access to Pangolin resources. + +## Use Cases + +- Give IT or operations staff access to a full office or data center LAN. +- Reach a cloud VPC, such as an AWS VPC or Azure VNet, through a site running inside it. +- Manage a range of network equipment, IP cameras, or industrial devices on a dedicated subnet. +- Let a team reach a lab or staging network where machines change often. +- Restrict a range to a single protocol, such as HTTPS on port `443`, across every host in it. + +## How CIDR Resources Work + +When a user with access connects, the Pangolin client installs a route for the whole prefix. Any traffic to an address in that range goes over the encrypted tunnel to a site attached to the resource, and the site forwards it to the matching host on its network. + +The client only routes the prefixes a user has access to, so traffic to other addresses, including the public internet, stays on the device's normal network path. When a host resource and a CIDR resource overlap, the client prefers the more specific route. + ## 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. diff --git a/content/docs/manage/resources/private/host.mdx b/content/docs/manage/resources/private/host.mdx index dc3db48..c96ea9d 100644 --- a/content/docs/manage/resources/private/host.mdx +++ b/content/docs/manage/resources/private/host.mdx @@ -7,6 +7,28 @@ A host private resource exposes a single machine on your remote network to conne 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. +## Benefits + +- Nothing is exposed to the public internet. The host is only reachable by clients that are connected and granted access. +- Access is scoped to a single machine, not the whole network behind the site, so users only reach what they need. +- Any TCP or UDP protocol works, and you can narrow it to specific ports with port restrictions. +- An alias gives users a stable, memorable name for the host without any external DNS records. +- Attaching several sites gives the host redundant paths with automatic failover. + +## Use Cases + +- Connect to a database such as PostgreSQL or MySQL with your usual client, without opening its port to the internet. +- Reach an internal API, admin panel, or dashboard from a laptop on any network. +- Use a native RDP, SSH, or VNC client against a single server. +- Reach a service that only listens on the site host's loopback interface, through an alias. +- Give a machine client, such as a CI runner, access to one build server or artifact store. + +## How Host Resources Work + +When a user with access connects, the Pangolin client starts routing traffic for the host over the encrypted tunnel. That covers the destination address and, if the resource has one, its alias, which the client resolves through Pangolin. A site attached to the resource receives the traffic and sends it to the destination on its local network. Responses come back the same way. + +The site resolves the destination, so an FQDN only needs to resolve from the site's network, not from the user's device. Traffic to any other address stays on the user's normal network path, since the client only routes resources the user has access to. + ## Destination Every host resource has a [destination](/manage/resources/private/destinations): a single IP address or fully qualified domain name (FQDN). diff --git a/content/docs/manage/resources/private/multi-site-routing.mdx b/content/docs/manage/resources/private/multi-site-routing.mdx index 9987932..db0c8b3 100644 --- a/content/docs/manage/resources/private/multi-site-routing.mdx +++ b/content/docs/manage/resources/private/multi-site-routing.mdx @@ -4,6 +4,19 @@ description: "Use multiple sites on a private resource for resilient routing and --- When you configure a private resource, you can attach more than one site. Pangolin then chooses how to reach the resource’s destination through those sites, similar in spirit to running multiple connectors into the same network: traffic is steered toward whichever path is most suitable at the time. +### Benefits + +- A single site or connector host going down doesn't cut users off from the resource. +- Clients route through the best online site, weighing factors such as latency, so users never choose a site by hand. +- Failover is automatic. You don't need to edit the resource or reconnect clients. +- You can attach as many sites as you need to one resource. + +### Use Cases + +- Run two connectors into the same office LAN so access survives a server reboot or hardware failure. +- Reach a cloud VPC through connectors in different availability zones. +- Do maintenance or upgrades on one connector while users keep working through another. + ### How Routing Works Pangolin evaluates the sites you selected and routes client traffic through the site that is most ideal from the client’s perspective. That decision weighs factors such as latency and whether the site is reachable. If a site becomes unavailable, clients begin using the next best online site without you having to reconfigure the resource. diff --git a/content/docs/manage/resources/private/private-http.mdx b/content/docs/manage/resources/private/private-http.mdx index af49609..a48de3c 100644 --- a/content/docs/manage/resources/private/private-http.mdx +++ b/content/docs/manage/resources/private/private-http.mdx @@ -7,6 +7,28 @@ Private HTTP/HTTPS resources expose web applications over the Pangolin tunnel wi 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. +## Benefits + +- Web apps get a real hostname on your domain and a valid TLS certificate, so browsers show no certificate warnings. +- Users browse on the default port with a clean URL, with no port numbers or IP addresses to remember. +- Nothing is reachable from the public internet. The hostname only resolves for connected clients with access. +- Identity comes from the client connection, so users don't see an extra login page in front of the app. +- Traffic travels peer-to-peer from the client to the site, and TLS terminates at the site, close to the app. + +## Use Cases + +- Publish internal tools such as wikis, Grafana, or admin panels only to employees on the Pangolin client. +- Serve a self-hosted app over HTTPS when it only speaks plain HTTP on the local network. +- Replace a public resource for sensitive apps that should never have a public login page. +- Give contractors browser access to a staging site without exposing it to the internet. + +## How Private HTTP Resources Work + +1. You assign a hostname on a domain configured in Pangolin and set the destination host, port, and scheme. +2. The Pangolin control plane provisions routing and pushes a certificate for that hostname to the site. +3. A connected user with access opens the URL. The Pangolin client resolves the hostname privately and sends the request over the tunnel to the site. +4. A reverse proxy on the site terminates TLS and proxies the request to the destination. + 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 diff --git a/content/docs/manage/resources/private/ssh.mdx b/content/docs/manage/resources/private/ssh.mdx index 440d27b..045831c 100644 --- a/content/docs/manage/resources/private/ssh.mdx +++ b/content/docs/manage/resources/private/ssh.mdx @@ -5,6 +5,21 @@ description: "Connect to remote hosts over the Pangolin tunnel using the Pangoli 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. +## Benefits + +- SSH servers are never exposed to the public internet. Only connected clients with access can reach them. +- With automated provisioning, users sign in with their Pangolin identity and get short-lived certificates, so there are no long-lived keys to distribute or rotate. +- Accounts are created on the host just in time, with sudo and group permissions set by role. +- Users keep a native terminal workflow, including their own shell, tools, and SSH options. +- Removing a user's access in Pangolin cuts off their path to the host, whatever credentials they still hold. + +## Use Cases + +- Give engineers SSH access to production or staging servers based on their role. +- Reach many servers behind one bastion, with an auth daemon provisioning users on each host. +- Replace a shared jump host and hand-managed `authorized_keys` files. +- Let on-call staff get into servers from anywhere without a separate VPN. + ## How It Works 1. The user connects with the Pangolin client (GUI or CLI). diff --git a/content/docs/manage/resources/public/ai-gateway.mdx b/content/docs/manage/resources/public/ai-gateway.mdx index 847d4bd..c242183 100644 --- a/content/docs/manage/resources/public/ai-gateway.mdx +++ b/content/docs/manage/resources/public/ai-gateway.mdx @@ -7,6 +7,20 @@ An AI Gateway public resource is a protocol-aware reverse proxy on a fully quali This page covers how the **resource** works: reachability, authentication, and what you attach. Providers, keys, model routing, the catalog, and client setup live in [AI Gateway](/manage/ai/overview). +## Benefits + +- Coding agents work from anywhere, with no Pangolin client on the device. +- Provider API keys stay in Pangolin. Users get virtual API keys that you can revoke without rotating the provider key. +- Identity keys follow user and role grants, so removing someone's access disables their key. +- One URL can front several providers, with model routing, budgets, and usage analytics in one place. + +## Use Cases + +- Give a team Claude Code, Codex, or Gemini CLI on company provider accounts. +- Issue manual keys to CI pipelines, scripts, or internal services that call a model API. +- Track AI usage per user and key, and cap spend by role, key, or model with [budgets](/manage/ai/budgets). +- Limit which models each team can use with [model routing](/manage/ai/providers/model-routing). + ## How It Works 1. You assign a FQDN on a domain managed in Pangolin and set the resource type to **AI Gateway**. diff --git a/content/docs/manage/resources/public/healthchecks-failover.mdx b/content/docs/manage/resources/public/healthchecks-failover.mdx index 9a1069c..435d65a 100644 --- a/content/docs/manage/resources/public/healthchecks-failover.mdx +++ b/content/docs/manage/resources/public/healthchecks-failover.mdx @@ -5,6 +5,19 @@ description: "Monitor public resource targets and automatically remove unhealthy Health checks for public resources monitor each target and keep bad targets out of traffic automatically. When a target fails its check, Pangolin marks it unhealthy and removes it from load balancing. When it recovers and passes again, Pangolin adds it back. +## Benefits + +- Traffic is only sent to targets that are responding, so users don't hit a broken backend. +- Failover and recovery are automatic, with no manual changes to the resource. +- Thresholds keep a brief blip from pulling a target out of rotation. +- Health status feeds [alert rules](/manage/alerting/alert-rules) and the [maintenance page](/manage/resources/public/maintenance), so you can notify admins and users when something fails. + +## Use cases + +- Keep a web app online when one of several servers goes down or restarts. +- Fail over between sites in different locations for disaster recovery. +- Roll out an update one target at a time while the others keep serving traffic. + ## How it works For every target on a public resource, Pangolin runs checks at your configured intervals and evaluates the result against your health criteria. diff --git a/content/docs/manage/resources/public/http-https.mdx b/content/docs/manage/resources/public/http-https.mdx index d498ada..2832804 100644 --- a/content/docs/manage/resources/public/http-https.mdx +++ b/content/docs/manage/resources/public/http-https.mdx @@ -7,6 +7,23 @@ HTTP and HTTPS public resources are the most common public resource type. They e Users open the resource URL in any web browser. No Pangolin client is required. +## Benefits + +- Publish apps from behind NAT or a firewall without opening inbound ports or needing a public IP on the backend. +- Every resource gets a valid TLS certificate that Pangolin issues and renews. +- Unauthenticated visitors are stopped at Pangolin before any traffic reaches your app. +- SSO, identity providers, and context rules like geo-blocking protect apps that have no login of their own. +- Multiple targets across sites give load balancing, health checks, and automatic failover. +- Users only need a browser, so contractors, customers, and personal devices can get access without installing anything. + +## Use Cases + +- Put self-hosted apps such as Grafana, Home Assistant, or an internal wiki behind SSO. +- Publish a public website or API running on a home server or private network. +- Share a staging site with a client using a PIN, passcode, or expiring link. +- Restrict an admin panel to certain countries, IP ranges, or URL paths with access rules. +- Load balance a web app across servers in different locations. + ## How It Works 1. You assign a FQDN on a domain managed in Pangolin. diff --git a/content/docs/manage/resources/public/maintenance.mdx b/content/docs/manage/resources/public/maintenance.mdx index 2554dfe..585fec3 100644 --- a/content/docs/manage/resources/public/maintenance.mdx +++ b/content/docs/manage/resources/public/maintenance.mdx @@ -12,6 +12,18 @@ Pangolin can display a customizable maintenance page to users when a resource is Maintenance Page Preview +## Benefits + +- Users see a clear message you write instead of a gateway error when a resource is down. +- An estimated completion time sets expectations and cuts down on support requests. +- Automatic mode covers unplanned outages without anyone having to switch it on. + +## Use Cases + +- Announce a planned maintenance window for an app or API. +- Tell users a service is temporarily unavailable when every target fails its health check. +- Hold a page in place while you migrate a resource to new servers. + ## Configuration Title: The main title text displayed on the maintenance page. diff --git a/content/docs/manage/resources/public/raw-resources.mdx b/content/docs/manage/resources/public/raw-resources.mdx index b206d56..c51632e 100644 --- a/content/docs/manage/resources/public/raw-resources.mdx +++ b/content/docs/manage/resources/public/raw-resources.mdx @@ -9,6 +9,28 @@ Because TCP and UDP resources are not protocol-aware, they do **not** enforce Pa 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. +## Benefits + +- Expose any TCP or UDP service, whatever the protocol, without opening ports on the backend network. +- The backend stays behind NAT or a firewall. Only the Pangolin server needs a public port. +- Players or users connect with their normal client software, with no Pangolin client to install. +- Multiple targets across sites give round-robin routing and failover. +- Proxy Protocol can pass the original client IP through to backends that support it. + +## Use Cases + +- Host a game server, such as Minecraft, from a home network. +- Publish a VoIP, MQTT, or other non-HTTP service that clients reach by host and port. +- Give public access to a service that has its own authentication and needs no extra layer from Pangolin. + +## How TCP and UDP Resources Work + +1. You map a port on the Pangolin server to the resource. +2. A client connects to `:`. +3. Pangolin forwards the traffic as-is through the tunnel to a site, which delivers it to the target. + +Pangolin does not inspect or authenticate the traffic, so any security has to come from the service itself. + ## Target Configuration TCP and UDP resources use **[targets](/manage/resources/public/targets)** like HTTP/HTTPS resources: diff --git a/content/docs/manage/resources/public/rdp.mdx b/content/docs/manage/resources/public/rdp.mdx index a73e498..d3e107c 100644 --- a/content/docs/manage/resources/public/rdp.mdx +++ b/content/docs/manage/resources/public/rdp.mdx @@ -9,6 +9,20 @@ RDP public resources render a full Remote Desktop Protocol client in the browser Remote desktop session rendered in the Pangolin web dashboard +## Benefits + +- Users get a Windows desktop from any browser, with no remote desktop software or Pangolin client to install. +- Port 3389 is never exposed to the internet, which removes a common target for brute-force attacks. +- SSO, identity providers, and access rules sit in front of Windows authentication. +- File transfer and clipboard copy and paste work in the browser session. + +## Use Cases + +- Let staff reach their office workstation from home or a personal device. +- Give vendors or support staff time-limited access to a Windows server. +- Reach Windows machines on a factory floor, lab, or branch office behind NAT. +- Use Windows-only line-of-business apps from Mac, Linux, or Chromebook devices. + ## Video Walkthrough