pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-10-02 10:49:11 +02:00
Code Issues Packages Projects Releases Wiki Activity

port mintlify to fumadocs

Browse Source
This commit is contained in:
miloschwartz
2026-09-25 15:31:51 -04:00
parent dc54fb1017
commit 63199a588c
373 changed files with 13533 additions and 4577 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/docs/manage/resources/private/ai-gateway.mdx
+43
View File
@@ -0,0 +1,43 @@
---
title: "AI Gateway"
description: "Reach an AI API over the Pangolin tunnel using the connected client's identity"
---
A private AI Gateway resource exposes an AI API only to devices connected with the [Pangolin client](/manage/clients/install-client). Nothing is reachable from the public internet. Unlike [public AI Gateway](/manage/resources/public/ai-gateway), the gateway does not check a virtual API key. Identity comes from the active client connection.
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).
## 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).
2. You grant [users, roles, or machines](/manage/resources/private/authentication) access, the same as any other private resource.
3. The user connects with the Pangolin client. The machine running the AI client must be on that tunnel.
4. The agent calls the resource URL. Pangolin attributes the call to the connected user and proxies to the selected provider.
Clients still need a value in the API key field. Use the literal string `none`. Deleting the field usually breaks the client.
## Providers, Not Destinations
Private AI Gateway resources attach providers on the resource's **AI Gateway** tab. They do not use a host or CIDR [destination](/manage/resources/private/destinations) as the model backend. Cloud APIs are called from Pangolin. [Custom](/manage/ai/providers/custom) providers can use **Site Targets** when the model server is on a site network.
Private resources, including this type, can only be created on [Pangolin Sites](/manage/sites/understanding-sites#pangolin-site-recommended).
## Authentication and Access Rules
Access is the private resource model: grant users, roles, or machines explicitly. See [Private Authentication](/manage/resources/private/authentication).
When the connected client maps to a user, Pangolin forwards that identity upstream as [`Remote-*` headers](/manage/ai/providers/configuration#identity-headers).
## More Than One Resource
Give different users and roles their own providers with more than one AI Gateway resource. Distinct hostnames are the usual approach. Unlike other private resource types, they can also share a FQDN because they all route to the gateway inside Pangolin. See [Multiple Gateway Resources](/manage/ai/multiple-gateway-resources).
## Compared to Public AI Gateway
| | Private AI Gateway | [Public AI Gateway](/manage/resources/public/ai-gateway) |
|---|---|---|
| **Reachability** | Pangolin client tunnel | Public FQDN |
| **Auth** | Client identity; use `none` as the key placeholder | [Virtual API key](/manage/ai/virtual-api-keys) on every call |
| **Who can call it** | Users, roles, and machines granted on the resource | Identity keys follow users and roles; manual keys grant access when created |
For providers, model routing, and connecting Claude Code, Codex, and other clients, see [AI Gateway](/manage/ai/overview).
content/docs/manage/resources/private/alias.mdx
+39
View File
@@ -0,0 +1,39 @@
---
title: "Aliases"
description: "Friendly names for resources, overlaps, loopback on the site host, and DNS behavior"
---
Aliases provide a secondary, user-friendly address for any of your resources, allowing users to access the resource using this alternate name in addition to the original address.
For instance, a router with the address `10.0.0.1` could be assigned the alias `router.internal`, and users could connect using either. Aliases are accessible to anyone who has access to the resource, and they are exclusively accessible when connected with a Pangolin client, meaning they function without requiring any external DNS record setup. Furthermore, aliases are protocol agnostic, which means they will work with any network protocol, essentially acting as a pseudo-A record for an address that is only functional within the Pangolin environment.
## Overlapping Networks and Loopback on the Site Host
Several situations described on the [Destinations](/manage/resources/private/destinations) page are where an alias is especially important—either optional but strongly recommended, or effectively required.
Overlapping IP spaces across sites are common (for example the same RFC1918 subnet behind different Pangolin sites). Pangolin helps route connections without users picking a site by hand, but raw IPs or ambiguous names can still collide across environments. Assigning a distinct alias per resource gives clients a single hostname whose DNS resolution goes through Pangolin, so traffic consistently reaches the intended resource and site instead of whichever overlapping address would otherwise win. See [Overlapping destinations across sites](/manage/resources/private/destinations#overlapping-destinations-across-sites).
Loopback on the site host is another case: if the resource destination is `127.0.0.1` or `localhost` on the machine running the site, those strings still mean “this machine” on the user’s laptop or desktop—not the remote site. There is no safe way for users to type loopback literals and reach the service behind another host; an alias hostname is required so the client resolves the name via Pangolin and sends traffic over the tunnel to the site, which then forwards to its own loopback. See [Loopback on the site host](/manage/resources/private/destinations#loopback-on-the-site-host).
## CIDRs vs. IPs
An alias can only be created for a resource that is a single host (IP or FQDN). Aliases cannot be created for resources that are CIDR ranges because it would be ambiguous which host within the range the alias should point to.
## Domain Structure
Since aliases cannot be single-label domains, you must avoid using domain names that do not contain a dot (e.g., `pangolin`). A domain like `pangolin.net`, which includes a dot, is acceptable. Instead of a single-label domain, you should consider using a subdomain of a domain you control, such as `router.mywebsite.com`, or an existing private/internal domain name, like `router.internal` or `router.corp`.
### Wildcards
Wildcards allow you to define aliases that match multiple hostnames using special characters in the FQDN. For example, in an alias like `*.host-0?.autoco.internal`, the asterisk `*` matches any sequence of characters (including none), and the question mark `?` matches exactly one character.
If you use a wildcard such as `*.proxy.internal`, it will match any hostname that ends with `.proxy.internal` and has something before the dot—such as `host.proxy.internal`, `longerhost.proxy.internal`, or even `sub.host.proxy.internal`. However, the wildcard will not match the base domain itself (`autoco.internal` without anything before the dot).
### .local TLD
The `.local` TLD is reserved for local networking and multicast DNS (mDNS). mDNS is commonly used by Apple Bonjour, Linux zeroconf, and limited Windows features. Because of this, aliases that use `.local` may not resolve reliably across many devices. We recommend using a subdomain you control (for example, `alias.mywebsite.com`) or a private/internal domain such as `alias.internal` or `alias.corp`.
## Custom Upstream DNS
Aliases work by overriding the DNS of your computer running the client so that all DNS requests are sent to the Pangolin client for resolution. That behavior is controlled by the Enable Aliases (Override DNS) preference; see [Configure Clients](/manage/clients/configure-client#enable-aliases-override-dns). The DNS server on your computer is typically `100.96.128.1` (the first address inside of your utility subnet on the org) when connected to the tunnel, which forwards requests to an upstream server. By default, we use `1.1.1.1`, but this upstream address can be configured in the CLI or in the client settings.
**If you are attempting to set an upstream DNS server that is only accessible via the tunnel, ensure that you create a resource and check the tunnel DNS option in the client configuration settings.** Otherwise, connectivity to the server may fail when connected to the tunnel. Enable Aliases (Override DNS) must also be on—see [Configure Clients](/manage/clients/configure-client#enable-aliases-override-dns)—so the client can intercept DNS and forward queries to the upstream server.
content/docs/manage/resources/private/authentication.mdx
+13
View File
@@ -0,0 +1,13 @@
---
title: "Authentication"
description: "Only allow access to resources to specific users, roles, and machines"
---
When a client connects into an organization they will NOT have access to any resources by default. Access must be explicitly granted to users, roles, or machines for a tunnel to be established to the site(s) hosting the resource. The client will show no sites or resources unless access is granted.
Access can be granted in several ways:
* **Roles:** Assign access to resources to specific roles. Any user with that role will gain access to the resource when they connect.
* **Users:** Assign access to resources to specific users. Only those users will gain access to the resource when they connect.
* **Machines:** Assign access to resources to specific machines. Only those machine clients will gain access to the resource when they connect. Note that machines can not be put into roles.
When removing access to a resource, the client will automatically tear down the tunnel to that resource if there are no other resources accessible on that site.
content/docs/manage/resources/private/cidr.mdx
+30
View File
@@ -0,0 +1,30 @@
---
title: "CIDR"
description: "Route client traffic to an entire IP range on the remote network"
---
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.
<Warning>
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.
</Warning>
## 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.
content/docs/manage/resources/private/destinations.mdx
+63
View File
@@ -0,0 +1,63 @@
---
title: "Destinations"
description: "What a private resource destination is and how to define it (FQDN, IP, or CIDR)"
---
## What is a destination?
A destination is the network location your site can route to for a private resource: a single host IP address, an IP CIDR range, or a fully qualified domain name (FQDN). Every private resource must have a destination—it tells Pangolin where the resource lives on the remote network and how the site should reach it.
When a user connects with the Pangolin client and has access to that resource, their traffic is steered toward the address or range defined by the destination.
That role is similar to a [target](/manage/resources/public/targets) on a public resource: both tell Pangolin where to send traffic after it enters the platform. For public resources, traffic typically arrives from the internet; for private resources, it comes from other clients already connected to your organization.
You can optionally add an [alias](/manage/resources/private/alias) so people use a memorable hostname instead of the raw destination, or so overlapping IPs across sites resolve predictably (see [Overlapping destinations across sites](#overlapping-destinations-across-sites) below). In some setups an alias is required—for example when the destination is loopback on the site host ([Loopback on the site host](#loopback-on-the-site-host)).
## Defining a Destination
A private resource destination is always exactly one of the following: a single host IP, a CIDR range, or a FQDN.
### IP Address
Use a single IP address for one host on the remote network—for example, `10.1.0.35`. The Pangolin client installs a route for that host when the user connects with access to the resource, and traffic to that IP is carried over the tunnel to the site, which delivers it on the remote network.
### Loopback on the Site Host
If the service lives on the same machine as the Pangolin site, you can set the destination to `127.0.0.1` or `localhost`. The site then routes to its own loopback interface, which is where that process is listening.
On the user’s machine, `localhost` and `127.0.0.1` always mean that machine, not the remote site. Telling someone to open `http://127.0.0.1:8080` in a browser would hit their laptop, not the site.
So you must add an [alias](/manage/resources/private/alias)—for example a hostname only resolvable through Pangolin, such as `metrics.site-internal.example`—and have people use that name to connect. The client resolves the alias via Pangolin, sends traffic over the tunnel, and the site forwards it to `127.0.0.1` / `localhost` on its side. This is an example where an alias is required and where it resolves overlapping or conflicting meanings of the same address between the client and the site.
### CIDR Range
Use an IP CIDR range when many addresses should be reachable as one resource—for example, `10.1.0.0/16`. Any address inside the range is covered for users who have been granted access. The client installs routing for that prefix when they connect. This is the usual choice for whole subnets or segments instead of listing hosts one by one.
### FQDN
Use a fully qualified domain name when the resource is identified by DNS on the remote network—for example, `host.autoco.internal`. The Pangolin site resolves that hostname to an IP address on the network behind the site. That is a good fit when the host’s address can change but the name stays the same.
Another pattern is routing traffic destined for a public SaaS hostname through a Pangolin site using the client. For example, you can configure a private resource whose destination is `google.com`. When a user with access opens `google.com` in the browser, the client sends that traffic over the tunnel to the site. Because the site treats `google.com` as the resource’s destination, it proxies that traffic out to the internet from the site’s egress. The flow is: client → tunnel → site → upstream host, instead of the client reaching the host directly on its local path.
### Additional Notes on Resource Destinations
* Reserved IP Addresses: The Pangolin client reserves the CGNAT subnet 100.96.128.0/24. Accessing resources via an IP address within this reserved range will be blocked by the client, though its use is uncommon. This range can be configured for newly created orgs in the self-hosted Pangolin configuration file.
* Resource Destination Resolution: The configured address of the Resource is resolved by the site the resource points to. Make sure the site can resolve the address correctly.
### Overlapping destinations across sites
Pangolin smooths away overlapping networks and arbitrarily chooses a single site to resolve the IP address or range to. This is because we want connection requests to any Resource to be as simple as possible for the end users: when they connect to a particular IP address or FQDN, Pangolin figures out which site to send it to and the end user never needs to figure this out.
It is recommended that you create overlapping resources only if absolutely required. If you do, use [Aliases](/manage/resources/private/alias) to explicitly define which host should be used for a given FQDN or IP address and use the alias to connect.
### Overlapping destinations with local routes
The Pangolin client uses split tunneling: it only routes traffic for the private resources you've defined, and leaves everything else—public websites, local printers, other network devices—on the device's normal network path.
If a resource's destination overlaps with the user's local subnet, the client can end up capturing traffic that should have stayed local. For example, if a resource is defined as `192.168.1.0/24` (or a specific IP inside that range) and the user's home network is also on `192.168.1.0/24`, the client will route their local traffic—like printer or NAS access—over the tunnel instead, where it fails.
**Symptoms** include a user losing access to a local printer, file server, or another VPN client once connected to Pangolin.
**To fix it**, have the user check their local IP and subnet (`ipconfig` on Windows, `ifconfig`/`ip addr` on macOS/Linux), then compare it against your resource destinations. The recommended solution is to use more specific routes for your resources to prevent routing conflicts. For example instead of using a whole CIDR, use only host resources, or use more specific CIDRs like a /30 instead of a /24. Clients will always route to more specific routes over less specific ones. This way resource access is still controlled by Pangolin while the user's local and internet traffic is undisturbed.
If the above does not work, on Windows and Linux you can update the Pangolin client configuration to add a `prefer local routes` entry for the user's local subnet. This will tell the client to leave that traffic on the local network instead of routing it over the tunnel. See the [Configure Clients](/manage/clients/configure-client) page.
content/docs/manage/resources/private/host.mdx
+34
View File
@@ -0,0 +1,34 @@
---
title: "Host"
description: "Route client traffic to a single IP address or FQDN on the remote network"
---
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.
content/docs/manage/resources/private/multi-site-routing.mdx
+27
View File
@@ -0,0 +1,27 @@
---
title: "Multi-site Routing and High Availability"
description: "Use multiple sites on a private resource for resilient routing and failover"
---
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.
### 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.
<Note>
Failover may take a few seconds. The site must be registered as offline, routing changes propagated to clients, and only then can failover take effect, so a short gap while that happens is expected.
</Note>
You are not limited to two sites. You can select as many sites as you need on a single private resource, as long as every selected site can actually reach the resource’s destination on the network.
### Example: Redundant Office Connectors
Suppose your office LAN is reachable from two servers, and you install a Pangolin site connector on each. Both sites act as connectors into the same office network, so either site can route to the same internal hosts.
You create one private resource for an internal service and select both sites. While both connectors are healthy, Pangolin sends traffic through the better path. If one server or connector goes down, clients keep access to the private resource because traffic fails over to the other online site.
### Requirements and Pitfalls
Every site you attach must have routable access to the resource destination (same logical network, correct routes, DNS or IP resolution from that site’s perspective, and so on). The product assumes that any site in the list is a valid path to the same destination.
If you mix sites that live on entirely different networks and one or more of them cannot reach the destination, behavior becomes unpredictable and the resource may not work reliably. Before adding a site, confirm from that site’s network that it can reach the configured destination the same way you expect the primary site to.
content/docs/manage/resources/private/port-restrictions.mdx
+41
View File
@@ -0,0 +1,41 @@
---
title: "Ports and ICMP"
description: "Configure TCP and UDP port modes and ICMP (ping) for private resources"
---
For each private resource, TCP and UDP are configured separately. Each protocol uses one of three modes: All, Blocked, or Custom. ICMP (ping) is controlled on its own and does not follow those TCP/UDP modes.
## Port restrictions
Port settings apply to users, roles, and machines that have access to the resource. They limit which application traffic can reach the resource’s destination through Pangolin.
### All
All means no port filtering for that protocol: every port on the destination is reachable through the tunnel. This is the default-style behavior when you are not narrowing traffic to a subset of ports.
Use All when the service needs arbitrary ports (for example ephemeral ports on the client side are handled by the stack, but the server listens on many ports) or when you have not yet tightened access.
### Blocked
Blocked means that protocol is not allowed to the destination through Pangolin: no TCP or no UDP traffic passes, depending on which row you set. The other protocol can still be All or Custom independently-for example TCP Custom (only `443`) with UDP Blocked for a HTTPS-only workload that should not receive UDP to that destination.
Use Blocked when you want to turn off a protocol entirely for that resource.
### Custom
Custom means only the ports you list are allowed; every other port for that protocol is denied. Enter either:
* a single port (e.g. `80`),
* a comma-separated list (e.g. `80,443,8080`), or
* a range with a hyphen (e.g. `8000-8100`).
* lists and ranges (e.g. `80,443,8080-8090,9000-9010`)
Use Custom for least-privilege access: allow only the ports your application actually needs (see also [SSH](/manage/ssh) for allowing TCP `22` when using Pangolin SSH).
## ICMP
By default, ICMP (ping) to the resource’s destination is enabled. To turn it off, disable the ICMP option when configuring access to the resource. That stops ICMP echo requests (ping) to the destination for principals that have access.
<Note>
ICMP ping does not work when using a resource [alias](/manage/resources/private/alias) as the target-ping applies to the resource’s configured destination (FQDN, IP, or CIDR), not to alias hostnames.
</Note>
content/docs/manage/resources/private/private-http.mdx
+30
View File
@@ -0,0 +1,30 @@
---
title: "HTTP / HTTPS"
description: "Private reverse proxy with optional TLS termination at the site edge over the Pangolin 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 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.
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
The destination block for a private HTTP resource is closer to a [target](/manage/resources/public/targets) on a public resource than to a plain private resource: in addition to the upstream hostname or IP, you set a destination port and a scheme (`http` or `https`). Those values are required so the site knows how to open the connection to the backend after TLS is terminated at the proxy.
## Compared to an IP Resource and an Alias
You can approximate private browsing with a standard private resource by pairing an IP or internal hostname with an [alias](/manage/resources/private/alias) and a port. In practice you would still visit something like `https://your-alias.example:8443/` (or HTTP without a trusted name), and the browser will not show a normal publicly trusted certificate for that pattern the way it does for a first-class HTTPS hostname. Private HTTP is meant for the case where you want a real FQDN on your Pangolin domain with valid TLS and default ports, similar to a public resource, while keeping the surface client-only.
## Compared to a Public Resource
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. 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.
content/docs/manage/resources/private/ssh.mdx
+62
View File
@@ -0,0 +1,62 @@
---
title: "SSH"
description: "Connect to remote hosts over the Pangolin tunnel using the Pangolin CLI"
---
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 <alias>` 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 <resource-alias>
```
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).
<Warning>
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.
</Warning>
## 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.
<Warning>
**Pangolin SSH mode requires root.** The Pangolin Site must run as root on the site connector host. Use `sudo pangolin up site ...` or run the site service as root. See [Install Sites](/manage/sites/install-site).
</Warning>
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 <alias>` | 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 |
content/docs/manage/resources/public/ai-gateway.mdx
+49
View File
@@ -0,0 +1,49 @@
---
title: "AI Gateway"
description: "Publish an AI API on a public FQDN and authenticate coding agents with virtual API keys"
---
An AI Gateway public resource is a protocol-aware reverse proxy on a fully qualified domain name, like [HTTP / HTTPS](/manage/resources/public/http-https). Clients call that URL instead of OpenAI, Anthropic, Gemini, or another model API. Pangolin authenticates the caller, then forwards the request to an attached [provider](/manage/ai/providers/overview).
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).
## How It Works
1. You assign a FQDN on a domain managed in Pangolin and set the resource type to **AI Gateway**.
2. You attach one or more org-level providers. The resource speaks the API formats those providers advertise.
3. A user retrieves a [virtual API key](/manage/ai/virtual-api-keys) by visiting the URL in a browser and logging in, or from the Resource Launcher or `https://app.pangolin.net/<org-id>/keys`.
4. Coding agents send that key to the same FQDN. Pangolin checks the key and proxies to the selected provider.
Visiting the URL in a browser is how you retrieve a key. Model calls still need the key in the request. A dashboard session cookie cannot proxy through the gateway.
## Providers, Not Targets
AI Gateway public resources do **not** use HTTP [targets](/manage/resources/public/targets). Traffic goes to providers configured under **AI Gateway → Providers**, then attached on the resource.
Cloud APIs (OpenAI, Anthropic, and similar) need no site. [Custom](/manage/ai/providers/custom) providers can use **Site Targets** when the model server sits on a site network. That routing is on the provider, not on the resource.
## Authentication and Access Rules
Authentication is always on. You cannot turn Platform SSO off the way you can on an HTTPS resource.
Assign [users and roles](/manage/access-control/create-user) the same way as a public HTTPS resource. Those grants control who can use an **identity key**. [Manual keys](/manage/ai/virtual-api-keys#manual-keys) grant access as soon as you create them, regardless of users and roles on the resource.
When the call uses an identity key, or a manual key attributed to a user, Pangolin forwards that identity upstream as [`Remote-*` headers](/manage/ai/providers/configuration#identity-headers). An unattributed manual key authenticates without sending them.
HTTPS resources can add PIN, passcode, header auth, shareable links, or email OTP. AI clients authenticate programmatically, so this type uses virtual API keys instead of those methods. See [Virtual API Keys](/manage/ai/virtual-api-keys) and [public authentication](/manage/resources/public/authentication).
You can still attach a [resource policy](/manage/resources/public/resource-policies) for users, roles, and access rules.
## More Than One Resource
Give different users and roles their own providers with more than one AI Gateway resource. Distinct hostnames are the usual approach. Unlike HTTP / HTTPS, they can also share a FQDN because they all route to the gateway inside Pangolin. See [Multiple Gateway Resources](/manage/ai/multiple-gateway-resources).
## Compared to Private AI Gateway
| | Public AI Gateway | [Private AI Gateway](/manage/resources/private/ai-gateway) |
|---|---|---|
| **Reachability** | Public FQDN | Pangolin client tunnel |
| **Auth** | Virtual API key on every call | Client identity; the gateway does not check a key |
| **Browser visit** | Shows the user's key after login | Not used to retrieve a key |
For providers, keys, model routing, and connecting Claude Code, Codex, and other clients, see [AI Gateway](/manage/ai/overview).
content/docs/manage/resources/public/authentication.mdx
+50
View File
@@ -0,0 +1,50 @@
---
title: "Authentication"
description: "Create identity and context aware rules to allow access"
---
Though public resources are public and accessible to via a web browser, admins can create rules to enable a layer of authenticated protection in front of public resources. By default, all public resources have Pangolin auth (Platform SSO) enabled, but a number of other authentication methods are available.
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.
[AI Gateway](/manage/resources/public/ai-gateway) public resources always require authentication. Coding agents use [virtual API keys](/manage/ai/virtual-api-keys) rather than PIN, passcode, or email OTP. Users and roles still apply to identity keys the same way they do for HTTPS.
When an unauthenticated user visits a resource in their web browser, they will be redirected to a Pangolin-controlled authentication page where they must complete authentication.
## User Login
- **Pangolin (Platform) SSO** - Users must log in with a valid Pangolin account before they can log in.
- **External Identity Provider** - Enable log in to resources via your organization's identity provider of choice (Google, Azure, Okta, etc).
- **Users and Roles** - Assign specific users accesss to resources. Group users by roles and assign entire roles access to resources.
## PIN and Passcode
Add simple PIN or passcode authentication to resources. Similarly to user login, users will need to first enter a PIN or passcode before they can gain access to the resource.
## Header Auth
Add header auth to authenticate with a `Authorization` header or with a username and password challenge in the browser. When making a machine to machine request to this resource include the username and password in one of the following ways:
1. `Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=` where the payload is username:password -> dXNlcm5hbWU6cGFzc3dvcmQ=
2. In the url as `username:password@example.domain.com`
[Read more about the standard here.](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Authorization)
To challenge the browser to prompt for a username and password to log in, ensure the "Extended Compatibility" checkbox is toggled on. This will ensure a 401 response occurs which will trigger the prompt.
## Shareable Links and Access Tokens
Generate temporary self-destructing links that provide authenticated access to resources. Set specific expiration times for when all users who used the link will lose access and when the link becomes invalid. Links can optionally grant more permanent access with no expiration. Delete links when you want to revoke access.
You can also pass access tokens via query params or headers to resources to enable programmatic access.
## Email-based One Time Passcode (OTP)
First whitelist specific emails or wildcards, like `*@.example.com`. When users visit the resource, they will be prompted to enter an email. If the email they enter is on the whitelist, a temporary one time passcode will be sent to their email. Users can then enter this OTP to gain access to the resource.
## Rules to Access or Deny
Define ranked rules to either block or allow access from specific IPs, geolocation, URL paths, and more.
## More
Read about more authentication options and specific settings in [Access Control](/manage/access-control/) and [Identity Providers](/manage/identity-providers/). To reuse the same authentication and access rule settings across many public resources, see [Resource Policies](/manage/resources/public/resource-policies).
content/docs/manage/resources/public/healthchecks-failover.mdx
+103
View File
@@ -0,0 +1,103 @@
---
title: "Health Checks and Failover"
description: "Monitor public resource targets and automatically remove unhealthy targets from routing"
---
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.
## 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.
- Passing checks keep the target in rotation.
- Failing checks remove the target from rotation.
- Recovery checks add the target back after threshold conditions are met.
This gives automatic failover across targets without manual intervention.
## Target states
Targets move through three operational states:
- `Unknown`: initial state before the first check finishes; target may still receive traffic.
- `Healthy`: checks are passing; target is eligible for routing and load balancing.
- `Unhealthy`: checks are failing; target is excluded from routing and load balancing.
## Check types
Public resource target health checks support the same two probe types used by arbitrary health checks:
- HTTP checks: request a URL and evaluate response behavior (for example status code).
- TCP checks: attempt a TCP connection to a host and port without HTTP semantics. This is useful for non-HTTP services where you only need to verify the port is reachable.
## Configure health checks on a target
1. Open a public resource in the dashboard.
2. In the targets table, open the health check settings for the target.
3. Configure probe parameters and thresholds.
4. Save.
Each target can have its own health check settings.
<Frame caption="Create health check in the Pangolin dashboard">
<img src="/images/create-healthcheck.png" alt="Create health check form in the Pangolin dashboard" />
</Frame>
## Common parameters
Some of the most important settings to tune are:
- `healthy interval`: how often Pangolin probes when a target is currently healthy.
- `unhealthy interval`: how often Pangolin probes when a target is currently unhealthy (usually shorter for faster recovery detection).
- `healthy threshold`: how many consecutive successful checks are required before marking a target healthy again.
- `unhealthy threshold`: how many consecutive failed checks are required before marking a target unhealthy.
- `timeout`: maximum time a probe can take before it is treated as failed.
- HTTP-specific fields: probe scheme (`http`/`https`), path, method, headers, and expected status codes.
Use intervals and thresholds together to avoid flapping: short transient blips should not immediately eject a target, and recovery should be confirmed before re-entry.
<Note>
The dashboard includes additional health-check options beyond the examples above. Use this section as a starting point and refer to the full UI field set when configuring production checks.
</Note>
## Public resource failover patterns
### Multi-target redundancy
Use multiple targets for the same service. If one goes unhealthy, traffic continues to healthy targets.
```text
Resource: web-application
├── Target 1: web-01.local:8080 (Site A) - Healthy
├── Target 2: web-02.local:8080 (Site A) - Unhealthy
└── Target 3: web-03.local:8080 (Site B) - Healthy
Traffic routes to: Target 1 & Target 3 only
```
### Cross-site failover
Distribute targets across multiple sites to protect against site-level failures.
```text
Resource: api-service
├── Primary Site Targets
│ ├── api-01.primary:8443 - Healthy
│ └── api-02.primary:8443 - Healthy
└── Backup Site Targets
├── api-01.backup:8443 - Healthy
└── api-02.backup:8443 - Healthy
All targets receive traffic via load balancing
```
If a whole site fails, only targets from reachable sites continue receiving traffic until health recovers.
## Related alerting and arbitrary checks
This page covers health checks attached to public resource targets (available in all editions).
If you need centralized visibility across checks, standalone non-resource checks, or notifications:
- See [Alerting health checks](/manage/alerting/health-checks) for org-level health-check visibility and arbitrary health checks.
- See [Alert rules](/manage/alerting/alert-rules) to notify email, webhooks, and integrations when health state changes.
content/docs/manage/resources/public/http-https.mdx
+37
View File
@@ -0,0 +1,37 @@
---
title: "HTTP / HTTPS"
description: "Publish websites, APIs, and dashboards as authenticated public reverse proxies"
---
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).
content/docs/manage/resources/public/maintenance.mdx
+41
View File
@@ -0,0 +1,41 @@
---
title: "Maintenance Page"
description: "Show a maintenance page to users when a resources is down for maintenance or targets are unhealthy"
---
<Note>
Maintenance pages are only available in [Enterprise Edition](/self-host/enterprise-edition).
</Note>
Pangolin can display a customizable maintenance page to users when a resource is undergoing maintenance or when all targets are unhealthy. This ensures users are informed about the downtime and provides a better user experience.
<Frame caption="Maintenance Page Preview">
<img src="/images/maintenance_page.png" alt="Maintenance Page Preview"/>
</Frame>
## Configuration
Title: The main title text displayed on the maintenance page.
Message: A descriptive message informing users about the maintenance status.
Estimated completion time: Optionally provide an estimated time for when the resource will be back online.
## Enabling Maintenance Page
To enable the maintenance page for a resource, navigate to the general resource settings in the Pangolin dashboard. Under the "Maintenance Page" section, you can customize the title, message, and estimated completion time. This can also be set using Blueprints.
## When is the Maintenance Page Shown?
There are two modes that control when the page is shown:
#### Forced
In forced mode, the maintenance page is displayed to all users regardless of the health status of the resource targets. This is useful for planned maintenance windows.
#### Automatic
In automatic mode, the maintenance page is shown only when all targets associated with the resource are unhealthy or all of the sites are offline. This is useful for unplanned outages and can be used to inform the user that the resource is temporarily unavailable by customizing the above settings.
## Remote Nodes
Maintenance pages do not work on remote nodes at this time.
content/docs/manage/resources/public/raw-resources.mdx
+124
View File
@@ -0,0 +1,124 @@
---
title: "TCP / UDP"
description: "Expose raw TCP and UDP services on a Pangolin server port without authentication"
---
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 `<pangolin-server>:<port>` 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
<Note>
This feature is only available in self-hosted Pangolin instances. If you're using Pangolin Cloud, you will need to deploy a remote node.
</Note>
Pangolin supports raw TCP and UDP traffic because a site can pass anything through the tunnel.
In Community Edition or Enterprise Edition, ensure you have the flag enabled in the config file:
```
flags:
allow_raw_resources: true
```
You map the resource to a port on the host Pangolin server, so you can access the resource from `<server-public-ip>:<mapped-port>`. This is useful if you want to access the resource over the public internet, such as exposing a game server like Minecraft.
## Proxied Resources
Proxied resources require extra configuration to expose on the Pangolin server. You'll need to configure firewall rules, Docker port mappings, and Traefik entry points. These steps require a server restart.
<Steps>
<Step title="Create the resource">
In the Pangolin dashboard, go to Resources and click Add Resource. Select "Raw TCP/UDP resource", and enter your desired publicly mapped port. This is the port you'll use to access the proxied resource.
</Step>
<Step title="Configure firewall">
Open your desired ports on your VPS firewall, just like you did for ports 51820, 443, and 80. This is highly OS and VPS dependent.
<Note>
In this example, we're exposing two resources: TCP 1602 and UDP 1704.
</Note>
</Step>
<Step title="Configure Docker">
Add port mappings to your `docker-compose.yml` file:
```yaml title="docker-compose.yml" {4,5}
gerbil:
ports:
# ... existing ports ...
- 1704:1704/udp # ADDED: Your UDP port
- 1602:1602 # ADDED: Your TCP port
```
</Step>
<Step title="Configure Traefik">
Add entry points to your `config/traefik/traefik_config.yml`:
```yaml title="traefik_config.yml" {12-15}
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
http:
tls:
certResolver: letsencrypt
transport:
respondingTimeouts:
readTimeout: 30m
tcp-1602:
address: ":1602/tcp"
udp-1704:
address: ":1704/udp"
```
<Info>
**Important**: Always name your entry points in the format `protocol-port` (e.g., `tcp-1602`, `udp-1704`). This naming is required for Pangolin's dynamic configuration.
</Info>
</Step>
<Step title="Restart the stack">
Restart your Docker stack to apply all changes:
```bash
sudo docker compose down
sudo docker compose up -d
```
</Step>
</Steps>
<Note>
In this example, we expose port 1602 for TCP and port 1704 for UDP. You can use any available ports on your VPS.
</Note>
## Proxy Protocol
On TCP resources you can enable Proxy Protocol support to forward the original client IP address to your backend service. This is useful for logging and access control.
In order to enable proxy protocol, simply check the "Enable Proxy Protocol" box when creating or editing a TCP resource.
<Note>Your backend application must be configured to accept Proxy Protocol connections. If your backend doesn't support Proxy Protocol, enabling this will break all connections so only enable this if you know what you're doing. Make sure to configure your backend to trust Proxy Protocol headers from Traefik.</Note>
To enable Proxy Protocol in Traefik, add the following to the bottom of your `config/traefik/dynamic_config.yml`:
```yaml
tcp:
serversTransports:
pp-transport-v1:
proxyProtocol:
version: 1
pp-transport-v2:
proxyProtocol:
version: 2
```
content/docs/manage/resources/public/rdp.mdx
+44
View File
@@ -0,0 +1,44 @@
---
title: "RDP"
description: "Control a Windows computer remotely through a full RDP client rendered in the browser"
---
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.
<Frame caption="RDP session in the browser">
<img src="/images/rdp-public.gif" alt="Remote desktop session rendered in the Pangolin web dashboard" />
</Frame>
## Video Walkthrough
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube-nocookie.com/embed/wd5K1qzCfLA"
title="How To Setup RDP In The Browser With Pangolin"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
referrerPolicy="strict-origin-when-cross-origin"
allowFullScreen
></iframe>
## 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.
content/docs/manage/resources/public/resource-policies.mdx
+90
View File
@@ -0,0 +1,90 @@
---
title: "Resource Policies"
description: "Share authentication and access rule settings across multiple public resources"
---
<Note>
Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition).
</Note>
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.
<Note>
Resource policies currently apply to **public resources** only. Support for private resources is coming soon.
</Note>
## 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).
<Tip>
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.
</Tip>
content/docs/manage/resources/public/ssh.mdx
+62
View File
@@ -0,0 +1,62 @@
---
title: "SSH"
description: "Access a remote shell in the browser with password, key, or Pangolin identity authentication"
---
SSH public resources render a full interactive terminal in the browser. Users visit a FQDN—no SSH client or Pangolin desktop client is required.
<Frame caption="SSH session in the browser">
<img src="/images/ssh-public.gif" alt="Interactive SSH terminal rendered in the Pangolin web dashboard" />
</Frame>
## Video Walkthrough
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube-nocookie.com/embed/8bvVdcPPWGQ"
title="How To Setup SSH In The Browser With Pangolin"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
referrerPolicy="strict-origin-when-cross-origin"
allowFullScreen
></iframe>
## 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.
<Warning>
**Pangolin SSH mode requires root.** The Pangolin Site must run as root on the site connector host. Use `sudo pangolin up site ...` or run the site service as root. See [Install Sites](/manage/sites/install-site).
</Warning>
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 <alias>` |
| **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.
content/docs/manage/resources/public/targets.mdx
+236
View File
@@ -0,0 +1,236 @@
---
title: "Targets"
description: "Configure destination endpoints for resource routing and load balancing"
---
When you create a resource in Pangolin, you define different targets that specify where traffic should be routed within your network. Each target represents a specific destination that the resource can proxy to when handling incoming requests.
## How Targets Work
### Target Routing
Targets function as destination endpoints for your resources:
1. **Resource Creation**: When you create a resource, you configure one or more targets
2. **Traffic Routing**: Incoming traffic is routed to the appropriate target based on your configuration
3. **Network Access**: The site routes traffic to the local network through the tunnel
4. **Direct Connection**: No additional routing is necessary on the remote network
## Additional Proxy Settings
In the public resource **Proxy** tab, Pangolin also provides additional proxy settings for how requests are sent to the upstream target.
### Custom Host Header
Use **Custom Host Header** when the upstream application expects a specific `Host` value instead of the public resource hostname.
This is commonly needed for virtual-hosted backends that route traffic based on `Host`.
### Custom Headers
Use **Custom Headers** to add static headers to every proxied request for the resource.
- Enter one header per line.
- Use the format `Header-Name: value`.
- Save the change with **Save Proxy Settings**.
Example:
```text
X-Example-Header: example-value
X-Environment: production
```
Typical uses include upstream shared-secret headers, feature flags, or tenant-routing headers that your application expects on every request.
<Note>
Custom headers are static resource-level headers. If you need Pangolin to pass user identity to the upstream app, use [Forwarded Headers](/manage/access-control/forwarded-headers) instead.
</Note>
## Multi-Site Targets
Targets have sites associated with them. This provides significant benefits for reliability and load distribution described below.
### Site-Distributed Resources
You can now configure targets across different sites for the same resource:
<Card title="High Availability">
Distribute your resources across multiple sites so that if one site goes down, traffic automatically continues to be served from other available sites.
</Card>
<Card title="Load Balancing">
Set up load balancing across sites to distribute traffic in a round-robin fashion between all available targets.
</Card>
### Distributing Sites Load Across Servers
<Note>
This is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
</Note>
On highly available clustered Enterprise Pangolin servers - lik the cloud platform - different sites can connect to different nodes. If one of the nodes goes down, the site moves to another node. This has implications for site-based load balancing, because DNS must can only route a FQDN to one Pangolin server node at a time.
Load balancing between different targets only works when sites are connected to the same Pangolin node. In Pangolin instances with multiple remote nodes, ensure load balancing occurs on the same node.
To ensure effective load balancing in multi-node environments:
```bash
pangolin up site --prefer-endpoint <specific-endpoint> <other-args>
```
For a list of endpoints used on the cloud platform, take a look at `/manage/endpoints-and-pops#points-of-presence`.
## Path-Based Routing
Path-based routing allows you to direct traffic to different targets based on the request path. This enables sophisticated routing scenarios where different services can handle different parts of your application.
### How Path-Based Routing Works
Each target can be configured with optional path routing parameters:
- **Path**: The path pattern to match against incoming requests
- **Match**: The matching strategy to use when comparing the request path
When a request comes in, Pangolin evaluates the path against all targets and routes traffic to the target with the matching path configuration.
### Match Types
Pangolin supports three different matching strategies:
#### Exact Match
**exact**: The request path must match the configured path exactly.
Example: Path `/api/users` with exact match only matches `/api/users`
#### Prefix Match
**prefix**: The request path must start with the configured path.
Example: Path `/api` with prefix match matches `/api/users`, `/api/orders`, `/api/users/123`, etc.
#### Regex Match
**regex**: The request path is matched against a regular expression pattern.
Example: Path `^/api/users/[0-9]+$` with regex match matches `/api/users/123` but not `/api/users/abc`
<Frame caption="Pangolin UI showing targets with path-based routing configuration">
<img src="/images/targets_config_path_match.png" alt="Targets example"/>
</Frame>
### Load Balancing with Path-Based Routing
When multiple targets have the same path and match configuration, Pangolin will load balance between them using round-robin distribution.
**Example Scenario:**
- Target 1: Path `/api`, Match `prefix`, Address `10.0.1.10:8080`
- Target 2: Path `/api`, Match `prefix`, Address `10.0.1.11:8080`
- Target 3: Path `/web`, Match `prefix`, Address `10.0.1.12:80`
In this configuration:
- Requests to `/api/users` will be load balanced between Target 1 and Target 2
- Requests to `/web/dashboard` will only go to Target 3
## Path Rewriting
Path rewriting allows you to modify the request path before it reaches your backend service. This enables you to expose different URL structures to your users while maintaining your existing backend API paths.
<Note>
Path rewriting requires path-based routing to be configured first. You must set up a Path Match before you can configure path rewriting.
</Note>
### How Path Rewriting Works
After Pangolin matches a request using path-based routing, it can rewrite the path before forwarding the request to your target service. Each target with path matching configured can optionally include path rewriting:
- **Rewrite Type**: The strategy to use for rewriting the path
- **Rewrite Value**: The new path or pattern to apply (optional for Strip Prefix)
The rewriting happens after the path match evaluation but before the request reaches your backend service.
### Rewrite Types
Pangolin supports four different rewriting strategies:
#### Prefix Rewrite
**prefix**: Replaces the matched portion with a new prefix, preserving the rest of the path.
- With Prefix Match: `/api` → `/v2/api` transforms `/api/users` into `/v2/api/users`
- With Exact Match: `/old` → `/new` transforms `/old` into `/new`
- With Regex Match: Uses the regex pattern with the rewrite value as replacement
#### Exact Rewrite
**exact**: Replaces the matched path with the exact rewrite path.
Example: Match path `/api/users` → Rewrite to `/users` transforms `/api/users` into `/users`
#### Regex Rewrite
**regex**: Uses regular expression substitution to transform the path. Works with any match type.
- With Regex Match: Uses the regex pattern directly
- With Prefix Match: Automatically captures everything after the prefix with `(.*)`
- With Exact Match: Matches the exact path
Example: Match path `^/api/v1/(.*)` (regex) → Rewrite to `/api/v2/$1` transforms `/api/v1/users` into `/api/v2/users`
#### Strip Prefix
**stripPrefix**: Removes the matched prefix from the path.
- With Prefix Match: Efficiently strips the prefix using Traefik's stripPrefix middleware
- With Exact/Regex Match: Uses regex replacement to remove the matched portion
- Optionally add a new prefix after stripping by providing a rewrite value
Example: Match path `/api` (prefix) → Strip Prefix transforms `/api/users` into `/users`
Example with new prefix: Match path `/old` (prefix) → Strip Prefix + Rewrite to `/new` transforms `/old/users` into `/new/users`
<Frame caption="Pangolin UI showing path rewriting configuration">
<img src="/images/targets_config_path_rewrite.png" alt="Targets with path rewriting"/>
</Frame>
### Configuration Requirements
<Warning>
Path rewriting validation ensures your configuration is valid:
- Path rewriting requires path matching to be configured first
- When using rewrite types other than Strip Prefix, both rewrite path and rewrite type must be specified together
- For regex path matching, the path pattern must be a valid regular expression
- Strip Prefix works with any match type, but is most effective with Prefix match type
</Warning>
### Automatic Path Normalization
Pangolin automatically normalizes paths to ensure correct routing:
- Non-regex paths that don't start with `/` will have `/` prepended automatically
- Non-regex rewrite paths that don't start with `/` will have `/` prepended automatically
- This ensures consistent behavior across different configurations
### Load Balancing with Path Rewriting
All targets with identical path match and path rewrite configurations will be load balanced together.
**Example:**
- Target 1: Match `/api` (prefix), Rewrite `/v2` (prefix), Address `10.0.1.10:8080`
- Target 2: Match `/api` (prefix), Rewrite `/v2` (prefix), Address `10.0.1.11:8080`
- Target 3: Match `/api` (prefix), Strip Prefix, Address `10.0.1.12:8080`
Requests to `/api/users` will:
- Load balance between Target 1 and Target 2 (both rewrite to `/v2/users`)
- NOT be sent to Target 3 (different rewrite configuration - strips to `/users`)
### Priority Calculation
When using path rewriting, request priority is automatically calculated to ensure proper routing order:
- Base priority: 100
- Path matching adds +10 to priority
- Exact match adds +5 more
- Prefix match adds +3 more
- Regex match adds +2 more
- Root path `/` gets priority 1 (lowest, acts as catch-all)
- Custom priorities override the automatic calculation
content/docs/manage/resources/public/vnc.mdx
+40
View File
@@ -0,0 +1,40 @@
---
title: "VNC"
description: "View and control a remote display through a VNC client rendered in the browser"
---
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.
## Video Walkthrough
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube-nocookie.com/embed/4Yb5SpHaMRs"
title="How To Setup VNC In The Browser With Pangolin"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
referrerPolicy="strict-origin-when-cross-origin"
allowFullScreen
></iframe>
## 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.
content/docs/manage/resources/public/wildcard-resources.mdx
+34
View File
@@ -0,0 +1,34 @@
---
title: "Wildcard Resources"
description: "Pangolin Cloud and Enterprise: route every hostname at a subdomain level through one public resource"
---
<Note>
Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition).
</Note>
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. 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
In the resource’s domain settings, set the subdomain field to `*` to match any label at that level. You can combine this with a parent subdomain, such as `*.apps`, so only hostnames under `apps` are covered, as long as TLS and DNS cover that same scope.
The downstream target still receives the original `Host` header, so virtual hosts and path rules on your side keep working.
## Requirements for Wildcard Resources
Wildcard hostnames need TLS certificates that cover `*.your-level`, not just a single FQDN, and DNS must send all of those names to Pangolin. How you satisfy that depends on how you host Pangolin.
### Self-hosted Pangolin
You must issue a wildcard certificate using DNS validation (DNS-01). HTTP-01 challenges prove one exact hostname at a time; they cannot obtain a certificate for `*.example.com`. DNS-01 proves control of the DNS zone, which is what certificate authorities require for wildcard coverage, otherwise Pangolin could not terminate HTTPS for arbitrary subdomains at that label.
Configure Traefik / Let’s Encrypt for DNS-01 and wildcard certs as described in [Wildcard domains](/self-host/advanced/wild-card-domains).
You also need DNS records so every name at that level resolves to your Pangolin server, for example an A record for `*.subdomain`. See [Domains](/manage/domains#for-wildcard-domains) for typical wildcard DNS patterns.
### Pangolin Cloud
Use a [domain delegation](/manage/domains#domain-delegation-ns-records) (NS record) domain so Pangolin controls DNS at the delegated zone. That delegation lets Pangolin issue and renew wildcard certificates for that level and ensures queries for `*.your-delegated-zone` route to Pangolin. Pangolin Cloud manages the certificates for you once delegation is in place.
content/docs/manage/resources/understanding-resources.mdx
+144
View File
@@ -0,0 +1,144 @@
---
title: "Understanding Resources"
description: "Resources are any network address you want to make available to users"
---
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. They find and open what they can access from the [Resource Launcher](/manage/resource-launcher).
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.
## Resource Types
There are two categories of resources: **public resources** and **private resources**. Each category supports different protocol types suited to how users connect.
<CardGroup cols={2}>
<Card title="Public Resources">
- 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
</Card>
<Card title="Private Resources">
- Zero-trust VPN access over the Pangolin client
- Every resource requires authentication
- Not browser-rendered; requires a connected client
</Card>
</CardGroup>
### 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).
[AI Gateway](/manage/resources/public/ai-gateway) also gets a public FQDN, but coding agents call it as an API. Visiting the URL in a browser is how users retrieve a virtual API key, not how they run the workload.
SSH, RDP, and VNC require a **Pangolin Site**. HTTP/HTTPS, AI Gateway, 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.
<CardGroup cols={3}>
<Card title="HTTP / HTTPS" icon="globe" href="/manage/resources/public/http-https" arrow="true">
Websites, APIs, and dashboards behind an authenticated reverse proxy.
</Card>
<Card title="AI Gateway" icon="robot" href="/manage/resources/public/ai-gateway" arrow="true">
Public FQDN for coding agents. Authenticate with virtual API keys.
</Card>
<Card title="SSH" icon="terminal" href="/manage/resources/public/ssh" arrow="true">
Full terminal in the browser with password, key, or Pangolin identity (PAM).
</Card>
<Card title="RDP" icon="desktop" href="/manage/resources/public/rdp" arrow="true">
Full remote desktop in the browser, including file transfer and clipboard.
</Card>
<Card title="VNC" icon="display" href="/manage/resources/public/vnc" arrow="true">
Remote display session rendered entirely in the browser.
</Card>
<Card title="TCP" icon="network-wired" href="/manage/resources/public/raw-resources" arrow="true">
Raw TCP proxy on a Pangolin server port. No authentication.
</Card>
<Card title="UDP" icon="network-wired" href="/manage/resources/public/raw-resources" arrow="true">
Raw UDP proxy on a Pangolin server port. No authentication.
</Card>
</CardGroup>
#### Site Compatibility
<CardGroup cols={3}>
<Card title="Pangolin Site" icon="plug" href="/manage/sites/understanding-sites#pangolin-site-recommended">
All public resource types supported.
Required for SSH, RDP, and VNC.
</Card>
<Card title="Local Site" icon="server" href="/manage/sites/understanding-sites#local-site">
HTTP/HTTPS, AI Gateway, and TCP/UDP only.
SSH, RDP, and VNC are not supported.
</Card>
<Card title="Basic WireGuard Site" icon="shield" href="/manage/sites/understanding-sites#basic-wireguard-site">
HTTP/HTTPS, AI Gateway, and TCP/UDP only.
SSH, RDP, and VNC are not supported.
</Card>
</CardGroup>
### Private Resource Types
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.
<CardGroup cols={2}>
<Card title="Host" icon="server" href="/manage/resources/private/host" arrow="true">
Route traffic to a single IP address or FQDN on the remote network.
</Card>
<Card title="CIDR" icon="sitemap" href="/manage/resources/private/cidr" arrow="true">
Route traffic to an entire IP range, such as a subnet.
</Card>
<Card title="HTTP / HTTPS" icon="globe" href="/manage/resources/private/private-http" arrow="true">
Private reverse proxy with optional TLS termination at the site edge.
</Card>
<Card title="AI Gateway" icon="robot" href="/manage/resources/private/ai-gateway" arrow="true">
AI API over the client tunnel. Identity from the connected client.
</Card>
<Card title="SSH" icon="terminal" href="/manage/resources/private/ssh" arrow="true">
Traditional terminal SSH over the tunnel via `pangolin ssh`.
</Card>
</CardGroup>
Private resources can only be created on Pangolin 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 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 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
<CardGroup cols={3}>
<Card title="Pangolin Site" icon="plug" href="/manage/sites/understanding-sites#pangolin-site-recommended">
Supported.
Private resources require a Pangolin Site.
</Card>
<Card title="Local Site" icon="server" href="/manage/sites/understanding-sites#local-site">
Not supported.
Local sites can only host public resources.
</Card>
<Card title="Basic WireGuard Site" icon="shield" href="/manage/sites/understanding-sites#basic-wireguard-site">
Not supported.
Basic WireGuard sites can only host public resources.
</Card>
</CardGroup>