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

many updates for 1.13

Browse Source
This commit is contained in:
miloschwartz
2025-12-10 15:20:41 -05:00
parent 5c2de2a7ab
commit c31b0cecde
36 changed files with 705 additions and 912 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
manage/resources/client-resources.mdx
View File

@@ -1,79 +0,0 @@
---
title: "Client Resources"
description: "Configure resources for Olm clients to access on a Newt site"
---
## Overview
Site resources in Pangolin allow you to define specific ports and a destination that can be accessed through the VPN tunnel when using [Olm clients](/manage/clients/add-client). This is useful for exposing internal services to your remote clients securely.
<Note>
Site resources are only for exposing services on a Newt site to Olm clients running remotely and do not get proxied.
</Note>
## Internal Exposure with Clients
Internal exposure resources are only accessible when connected via an Olm client. This approach is perfect for secure access to services without exposing them to the public internet.
When you run Newt with `--accept-clients`, it operates fully in user space without creating a virtual network interface on the host. This means:
- **No special permissions required** for the container or binary
- **No virtual network interface** created on the host
- **Client-only access** through Pangolin's tunnel
- **Secure internal routing** to your services
## Configuring Site Resources
To configure site resources:
<Steps>
<Step title="Navigate to Resources">
Navigate to the **Resources** section in the Pangolin dashboard.
</Step>
<Step title="Select Site Resources">
In the toggle at the top of the table, select "Site Resources".
</Step>
<Step title="Add Resource">
Click **Add Resource**.
</Step>
<Step title="Choose Resource Type">
Choose the resource type (TCP or UDP).
</Step>
<Step title="Configure Port and Target">
Specify the local port and the target address.
</Step>
</Steps>
## Accessing Site Resources
Once configured, you can access these resources from your remote clients using the Olm tunnel.
### Example: SSH Access
Here's how to set up SSH access to your server when connected with a client:
<Steps>
<Step title="Create the resource">
In the Pangolin dashboard, create a new client resource and set the port to `2022` (or any available port).
<Frame>
<img src="/images/client_resource.png" width="400" centered/>
</Frame>
</Step>
<Step title="Connect and access">
When connected with a Olm client, you can SSH to your server using `<site-address>:2022`.
```bash
ssh user@100.90.128.0 -p 22
```
<Note>
When accessing a site resource, you use the IP of the site found in the dashboard and the local port you configured for the resource.
</Note>
</Step>
</Steps>
<Note>
This approach is ideal for secure remote access without exposing SSH directly to the internet.
</Note>

4
manage/resources/private/alias.mdx Normal file
View File

@@ -0,0 +1,4 @@
---
title: "Aliases"
description: "Set a friendly alias hostname that resolves to a host"
---

4
manage/resources/private/cidr.mdx Normal file
View File

@@ -0,0 +1,4 @@
---
title: "CIDRs"
description: "Provide access to an entire network range"
---

4
manage/resources/private/host.mdx Normal file
View File

@@ -0,0 +1,4 @@
---
title: "Hosts"
description: "Provide access to a specific host on the network"
---

4
manage/resources/private/overview.mdx Normal file
View File

@@ -0,0 +1,4 @@
---
title: "Overview"
description: "Private resources are only accessible when connected with a Pangolin client"
---

36
manage/resources/public/authentication.mdx Normal file
View File

@@ -0,0 +1,36 @@
---
title: "Authentication"
description: "Create identity and context aware rules to allow access"
---
Though public resources are public and accessible to via a web browser, admins can create rules to enable a layer of authenticated protection in front of public resources. By default, all public resources have Pangolin auth (Platform SSO) enabled, but a number of other authentication methods are available.
When an unauthenticated user visits a resource in their web browser, they will be redirected to a Pangolin-controlled authentication page where they must complete authentication.
## User Login
- **Pangolin (Platform) SSO** - Users must log in with a valid Pangolin account before they can log in.
- **External Identity Provider** - Enable log in to resoruces via your organization's identity provider of choice (Google, Azure, Okta, etc).
- **Users and Roles** - Assign specific users accesss to resources. Group users by roles and assign entire roles access to resources.
## PIN and Passcode
Add simple PIN or passcode authentication to resources. Similarly to user login, users will need to first enter a PIN or passcode before they can gain access to the resource.
## Shareable Links and Access Tokens
Generate temporary self-destructing links that provide authenticated access to resources. Set specific expiration times for when all users who used the link will lose access and when the link becomes invalid. Links can optionally grant more permanent access with no expiration. Delete links when you want to revoke access.
You can also pass access tokens via query params or headers to resources to enable programmatic access.
## Email-based One Time Passcode (OTP)
First whitelist specific emails or wildcards, like `*@.example.com`. When users visit the resource, they will be prompted to enter an email. If the email they enter is on the whitelist, a temporary one time passcode will be sent to their email. Users can then enter this OTP to gain access to the resource.
## Rules to Access or Deny
Define ranked rules to either block or allow access from specific IPs, geolocation, URL paths, and more.
## More
Read about more authentication options and specific settings in [Access Control](/manage/access-control/) and [Identity Providers](/manage/identity-providers/).

5
manage/resources/tcp-udp-resources.mdx → manage/resources/public/raw-resources.mdx
View File

@@ -1,5 +1,5 @@
---
title: "Raw TCP & UDP"
title: "TCP & UDP"
description: "Configure raw TCP and UDP traffic through Pangolin tunnels"
---
@@ -15,6 +15,7 @@ In Pangolin Community Edition, ensure you have the flag enabled in the config fi
flags:
allow_raw_resources: true
```
You map the resource to a port on the host Pangolin server, so you can access the resource from `<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
@@ -105,4 +106,4 @@ tcp:
pp-transport-v2:
proxyProtocol:
version: 2
```
```

122
manage/resources/targets.mdx → manage/resources/public/targets.mdx
View File

@@ -3,14 +3,8 @@ title: "Targets"
description: "Configure destination endpoints for resource routing and load balancing"
---
## Overview
When you create a resource in Pangolin, you define different targets that specify where traffic should be routed within your network. Each target represents a specific destination that the resource can proxy to when handling incoming requests.
<Note>
Targets are created on the Newt tunnel, enabling traffic to reach destinations on the remote network without requiring additional routing configuration.
</Note>
## How Targets Work
### Target Routing
@@ -22,9 +16,9 @@ Targets function as destination endpoints for your resources:
3. **Network Access**: Newt proxy routes traffic to the local network through the tunnel
4. **Direct Connection**: No additional routing is necessary on the remote network
## Multi-Site Targets (v1.9.0+)
## Multi-Site Targets
With the introduction of update 1.9.0, targets now have sites associated with them. This enhancement provides significant benefits for reliability and load distribution.
Targets have sites associated with them. This provides significant benefits for reliability and load distribution described below.
### Site-Distributed Resources
@@ -38,11 +32,15 @@ You can now configure targets across different sites for the same resource:
Set up load balancing across sites to distribute traffic in a round-robin fashion between all available targets.
</Card>
### Load Balancing Requirements
### Distributing Sites Load Across Servers
<Warning>
Load balancing between different targets only works when sites are connected to the same node. In Pangolin instances with multiple remote nodes, ensure load balancing occurs on the same node.
</Warning>
<Note>
This is an Enterprise Edition only feature.
</Note>
This refers to having more than on Pangolin server node that a site can connect to. If one of the server nodes goes down, the site moves to another node. This has some implications for site-based load balancing, because DNS must can only route a FQDN to one Pangolin server node at a time.
Load balancing between different targets only works when sites are connected to the same Pangolin node. In Pangolin instances with multiple remote nodes, ensure load balancing occurs on the same node.
To ensure effective load balancing in multi-node environments:
@@ -50,10 +48,6 @@ To ensure effective load balancing in multi-node environments:
newt --prefer-endpoint <specific-endpoint> <other-args>
```
<Note>
Pangolin currently does not load balance between nodes, only between targets on the same node.
</Note>
## Path-Based Routing
Path-based routing allows you to direct traffic to different targets based on the request path. This enables sophisticated routing scenarios where different services can handle different parts of your application.
@@ -71,23 +65,23 @@ When a request comes in, Pangolin evaluates the path against all targets and rou
Pangolin supports three different matching strategies:
<Card title="Exact Match">
**exact**: The request path must match the configured path exactly.
Example: Path `/api/users` with exact match only matches `/api/users`
</Card>
#### Exact Match
<Card title="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.
</Card>
**exact**: The request path must match the configured path exactly.
<Card title="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`
</Card>
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"/>
@@ -127,41 +121,41 @@ The rewriting happens after the path match evaluation but before the request rea
Pangolin supports four different rewriting strategies:
<Card title="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
</Card>
#### Prefix Rewrite
<Card title="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`
</Card>
**prefix**: Replaces the matched portion with a new prefix, preserving the rest of the path.
<Card title="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`
</Card>
- 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
<Card title="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`
</Card>
#### 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"/>
@@ -207,4 +201,4 @@ When using path rewriting, request priority is automatically calculated to ensur
- Prefix match adds +3 more
- Regex match adds +2 more
- Root path `/` gets priority 1 (lowest, acts as catch-all)
- Custom priorities override the automatic calculation
- Custom priorities override the automatic calculation

52
manage/resources/understanding-resources.mdx Normal file
View File

@@ -0,0 +1,52 @@
---
title: "Understanding Resources"
description: "Resources are any network address you want to make available to users"
---
Resources respresent the applications, hosts, or ranges you make available for remote access to users. Resources exist on the remote networks of your sites. Users only ever think about connecting to resources and not specific sites.
By default, no resources are made available on sites. Admins must define resources with backend targets, and assign specific access policies before any users can gain access.
## Resources Types
There are two types of resources: public resources and private resources.
<CardGroup cols={2}>
<Card title="Public Resources">
- Reverse proxies to backend services
- Optionally have authentication
- Anyone with web browser can access
</Card>
<Card title="Private Resources">
- Zero-trust VPN
- Access to every resources requires authentication
- Users and machines access when connected with a client
</Card>
</CardGroup>
### Public Resources
Public resources are protocol-aware and TCP/UDP proxies to services that are made available to the public internet.
#### HTTPS Resources
Examples of HTTP resources include, APIs, websites, and dashboards. These are served with a fully qualified domain name and HTTPS with a valid SSL certificate.
All requests go through an authenticated reverse proxy. **Thus, public resources do not require client-side software to be installed on user devices for access. Anyone with a web browser can access public resources.**
HTTP resources are also identity and context aware, meaning you can create policies and rules to only let certain users, roles, countries, IPs, CIDRs, etc have access. When users visit an authenticated public resource, they are greeted with a Pangolin login page where they must complete authentication in order to get to the underlying resource. Therefore, Pangolin acts as a frontdoor barrier to these resources.
#### Raw TCP/UDP Resources
Raw resources are a way to proxy any TCP and UDP traffic through the Pangolin reverse proxy. Instead of a fully qualified domain name and certificate, these resources are bound to one or more ports on the Pangolin host.
Since these resources are not protocol aware and are publically proxied, they do not support identity and context policies and rules.
### Private Resources
Private resources require users to be connected with Pangolin client in order for them to be accessed. Any TCP and UDP traffic can be made available.
**Private resources function like a zero-trust virtual private network (VPN).** Explicit access to resources must be granted for users and roles to be able to access them. For this reason, we recommend using private resources for all raw TCP/UDP traffic that doesn't need a public proxy, instead of relying on raw TCP/UDP public resources (as discussed above).
Private resources support single hosts or entire network ranges (CIDR). Private resources can also have internal DNS alias hostnames assigned for easy, human-readable naming. Users don't choose to connect to specific resources; rather, when they connect via a client to your organization, they can access all resources their account has access to at once.