pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-03-07 11:16:41 +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

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/).

109
manage/resources/public/raw-resources.mdx Normal file
View File

@@ -0,0 +1,109 @@
---
title: "TCP & UDP"
description: "Configure raw TCP and UDP traffic through Pangolin tunnels"
---
<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 Newt can pass anything through the tunnel.
In Pangolin Community 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" highlight={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" highlight={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
```

204
manage/resources/public/targets.mdx Normal file
View File

@@ -0,0 +1,204 @@
---
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**: 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
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 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:
```bash
newt --prefer-endpoint <specific-endpoint> <other-args>
```
## 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