docs: add new Access Control and Logs documentation pages
- Documented Access Control features (e.g., Device Approvals, Password Rotation, 2FA, Custom Login Pages). - Added detailed descriptions for Logs & Analytics (Access Logs, Request Logs, Action Logs). - Included configuration instructions and feature-specific notes for Pangolin Cloud and Enterprise Edition. Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
This commit is contained in:
+57
@@ -0,0 +1,57 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Authentication
|
||||
|
||||
> Create identity and context aware rules to allow access
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
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 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.
|
||||
|
||||
## 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/).
|
||||
|
||||
+153
@@ -0,0 +1,153 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Health Checks
|
||||
|
||||
> Configure automated health monitoring and failover for resources
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
Pangolin provides automated health checking for targets to ensure traffic is only routed to healthy services. Health
|
||||
checks are essential for building highly available services, as they automatically remove unhealthy targets from traffic
|
||||
routing and load balancing.
|
||||
|
||||
## How Health Checks Work
|
||||
|
||||
### Monitoring Process
|
||||
|
||||
Health checks operate continuously in the background:
|
||||
|
||||
1. **Periodic Checks**: Pangolin sends requests to your target endpoints at configured intervals.
|
||||
2. **Status Evaluation**: Responses are evaluated against your configured criteria.
|
||||
3. **Traffic Management**: Healthy targets receive traffic, unhealthy targets are excluded.
|
||||
4. **Automatic Recovery**: Targets are automatically re-enabled when they become healthy again.
|
||||
|
||||
## Target Health States
|
||||
|
||||
Targets can exist in three distinct states that determine how traffic is routed:
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Unknown" icon="question" color="#gray">
|
||||
**Initial State**: Targets start in this state before first health check
|
||||
|
||||
**Traffic Behavior**: Unknown targets still route traffic normally
|
||||
|
||||
**Duration**: Until first health check completes
|
||||
|
||||
</Card>
|
||||
|
||||
<Card title="Unhealthy" icon="x" color="#red">
|
||||
**Failed Checks**: Target has failed health check criteria
|
||||
|
||||
**Traffic Behavior**: No traffic is routed to unhealthy targets
|
||||
|
||||
**Load Balancing**: Excluded from load balancing rotation
|
||||
|
||||
</Card>
|
||||
|
||||
<Card title="Healthy" icon="check" color="#green">
|
||||
**Passing Checks**: Target is responding correctly to health checks
|
||||
|
||||
**Traffic Behavior**: Receives traffic according to load balancing rules
|
||||
|
||||
**Load Balancing**: Included in load balancing rotation
|
||||
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Configuring Health Checks
|
||||
|
||||
<Steps>
|
||||
<Step title="Access Target Settings">
|
||||
In the Pangolin dashboard, navigate to your resource and locate the target in the table.
|
||||
</Step>
|
||||
|
||||
<Step title="Open Health Check Configuration">
|
||||
Click the settings wheel (⚙️) next to the health check endpoint column.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure Health Check Parameters">
|
||||
Fill out the health check configuration with your desired parameters.
|
||||
</Step>
|
||||
|
||||
<Step title="Save Configuration">
|
||||
Save your settings to enable health checking for the target.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Health Check Parameters
|
||||
|
||||
### Endpoint Configuration
|
||||
|
||||
* **Target Endpoint**: The URL or address to monitor for health status
|
||||
* **Default Behavior**: Usually the same as your target endpoint
|
||||
* **Custom Endpoints**: Can monitor different endpoints (e.g., `/health`, `/status`)
|
||||
|
||||
### Timing Configuration
|
||||
|
||||
#### Healthy Interval
|
||||
|
||||
* **Purpose**: How often to check targets that are currently healthy
|
||||
* **Typical Range**: 30-60 seconds
|
||||
* **Consideration**: Less frequent checks reduce overhead
|
||||
|
||||
#### Unhealthy Interval
|
||||
|
||||
* **Purpose**: How often to check targets that are currently unhealthy
|
||||
* **Typical Range**: 10-30 seconds
|
||||
* **Consideration**: More frequent checks enable faster recovery
|
||||
|
||||
### Response Configuration
|
||||
|
||||
#### Timeout Settings
|
||||
|
||||
* **Request Timeout**: Maximum time to wait for a health check response
|
||||
* **Default Behavior**: Requests exceeding timeout are considered failed
|
||||
* **Recommended**: Set based on your service's typical response time
|
||||
|
||||
#### HTTP Response Codes
|
||||
|
||||
* **Healthy Codes**: Which HTTP status codes indicate a healthy target
|
||||
* **Common Settings**: 200, 201, 202, 204
|
||||
* **Custom Codes**: Configure based on your service's health endpoint behavior
|
||||
|
||||
## High Availability Strategies
|
||||
|
||||
### Multi-Target Redundancy
|
||||
|
||||
#### Service Redundancy
|
||||
|
||||
Deploy multiple instances of your service across different targets to ensure availability even when some targets fail.
|
||||
|
||||
```
|
||||
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
|
||||
|
||||
#### Geographic Distribution
|
||||
|
||||
Distribute targets across multiple sites to protect against site-level failures.
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Maintenance Page
|
||||
|
||||
> Show a maintenance page to users when a resources is down for maintenance or targets are unhealthy
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
<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="https://mintcdn.com/fossorial/WimeXubsTkPlCmpZ/images/maintenance_page.png?fit=max&auto=format&n=WimeXubsTkPlCmpZ&q=85&s=1947d7c701d51562591410339eafccc6" alt="Maintenance Page Preview" data-og-width="1386" width="1386" data-og-height="875" height="875" data-path="images/maintenance_page.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/WimeXubsTkPlCmpZ/images/maintenance_page.png?w=280&fit=max&auto=format&n=WimeXubsTkPlCmpZ&q=85&s=14994de5667ac481b9ef088cc343e679 280w, https://mintcdn.com/fossorial/WimeXubsTkPlCmpZ/images/maintenance_page.png?w=560&fit=max&auto=format&n=WimeXubsTkPlCmpZ&q=85&s=2f48365ffd4311ba820aa1fd9773e21e 560w, https://mintcdn.com/fossorial/WimeXubsTkPlCmpZ/images/maintenance_page.png?w=840&fit=max&auto=format&n=WimeXubsTkPlCmpZ&q=85&s=2d004cb29f6955ef370e4d1542338654 840w, https://mintcdn.com/fossorial/WimeXubsTkPlCmpZ/images/maintenance_page.png?w=1100&fit=max&auto=format&n=WimeXubsTkPlCmpZ&q=85&s=e2d43d08c1aedd97242ab7718da5ff6a 1100w, https://mintcdn.com/fossorial/WimeXubsTkPlCmpZ/images/maintenance_page.png?w=1650&fit=max&auto=format&n=WimeXubsTkPlCmpZ&q=85&s=5ef8e6c200e82b3722aa8fb2dead703f 1650w, https://mintcdn.com/fossorial/WimeXubsTkPlCmpZ/images/maintenance_page.png?w=2500&fit=max&auto=format&n=WimeXubsTkPlCmpZ&q=85&s=c62491470fc74c099c42b6b057fcc602 2500w" />
|
||||
</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.
|
||||
|
||||
@@ -0,0 +1,129 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# TCP & UDP
|
||||
|
||||
> Configure raw TCP and UDP traffic through Pangolin tunnels
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
<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} theme={null}
|
||||
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} theme={null}
|
||||
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 theme={null}
|
||||
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 theme={null}
|
||||
tcp:
|
||||
serversTransports:
|
||||
pp-transport-v1:
|
||||
proxyProtocol:
|
||||
version: 1
|
||||
pp-transport-v2:
|
||||
proxyProtocol:
|
||||
version: 2
|
||||
```
|
||||
|
||||
@@ -0,0 +1,232 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Targets
|
||||
|
||||
> Configure destination endpoints for resource routing and load balancing
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
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](/self-host/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 theme={null}
|
||||
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="https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_match.png?fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=4e04171f4730cd9280a7216ea38a34fc" alt="Targets example" data-og-width="1537" width="1537" data-og-height="382" height="382" data-path="images/targets_config_path_match.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_match.png?w=280&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=a8d9e09b9bbb6f60b0a8a3f2b9235d61 280w, https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_match.png?w=560&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=ddc07cc9c200156e06ddecf8525def24 560w, https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_match.png?w=840&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=682773b8ed77c3bff65ecd5a2ea7109a 840w, https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_match.png?w=1100&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=5b31701d00175ecaed9b929adceb195d 1100w, https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_match.png?w=1650&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=27f9476f448dbb52bde8757de934655f 1650w, https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_match.png?w=2500&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=a8b02f6a2348e7ff212495cf58d7da71 2500w" />
|
||||
</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="https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_rewrite.png?fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=2b4ac27da9b338ddbe5c084ca4f50738" alt="Targets with path rewriting" data-og-width="1545" width="1545" data-og-height="376" height="376" data-path="images/targets_config_path_rewrite.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_rewrite.png?w=280&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=8f3d6d4ee7ce629057f7f46e0eb77169 280w, https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_rewrite.png?w=560&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=5f56c3383bb510fbc1636104ec281190 560w, https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_rewrite.png?w=840&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=3c1ddb6683bce581a0a8c8a2f2cd2d65 840w, https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_rewrite.png?w=1100&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=bd9114e59b59bd24ae7b4438d59b14ab 1100w, https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_rewrite.png?w=1650&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=d305aba5d9dfe6b5ffd46f215929f470 1650w, https://mintcdn.com/fossorial/Ml6kFBgdb1oUkXPj/images/targets_config_path_rewrite.png?w=2500&fit=max&auto=format&n=Ml6kFBgdb1oUkXPj&q=85&s=e80dbb086ef9cff115f69798bc986098 2500w" />
|
||||
</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
|
||||
|
||||
Reference in New Issue
Block a user