mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-07-18 03:49:55 +00:00
Merge branch 'dev'
This commit is contained in:
miloschwartz
23
docs.json
23
docs.json
@@ -55,9 +55,10 @@
|
||||
"pages": [
|
||||
"manage/resources/public/authentication",
|
||||
"manage/resources/public/targets",
|
||||
"manage/resources/public/wildcard-resources",
|
||||
"manage/resources/public/healthchecks-failover",
|
||||
"manage/resources/public/raw-resources",
|
||||
"manage/resources/public/maintenance",
|
||||
"manage/resources/public/healthchecks-failover"
|
||||
"manage/resources/public/maintenance"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -65,7 +66,10 @@
|
||||
"pages": [
|
||||
"manage/resources/private/authentication",
|
||||
"manage/resources/private/destinations",
|
||||
"manage/resources/private/alias"
|
||||
"manage/resources/private/port-restrictions",
|
||||
"manage/resources/private/alias",
|
||||
"manage/resources/private/private-http",
|
||||
"manage/resources/private/multi-site-routing"
|
||||
]
|
||||
}
|
||||
]
|
||||
@@ -133,6 +137,14 @@
|
||||
"manage/analytics/streaming"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Alerting",
|
||||
"icon": "bell",
|
||||
"pages": [
|
||||
"manage/alerting/alert-rules",
|
||||
"manage/alerting/health-checks"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Blueprints",
|
||||
"icon": "file-code",
|
||||
@@ -182,6 +194,7 @@
|
||||
"self-host/advanced/enable-asnblocking",
|
||||
"self-host/advanced/metrics",
|
||||
"self-host/advanced/clustering",
|
||||
"self-host/advanced/traefik-log-rotation",
|
||||
"self-host/telemetry"
|
||||
]
|
||||
},
|
||||
@@ -390,6 +403,10 @@
|
||||
{
|
||||
"source": "manage/healthchecks-failover",
|
||||
"destination": "manage/resources/public/healthchecks-failover"
|
||||
},
|
||||
{
|
||||
"source": "/manage/resources/private/icmp-access",
|
||||
"destination": "/manage/resources/private/port-restrictions"
|
||||
}
|
||||
],
|
||||
"seo": {
|
||||
|
||||
BIN
images/create-alert-rule.png
Normal file
BIN
images/create-alert-rule.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 316 KiB |
BIN
images/create-healthcheck.png
Normal file
BIN
images/create-healthcheck.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 249 KiB |
216
manage/alerting/alert-rules.mdx
Normal file
216
manage/alerting/alert-rules.mdx
Normal file
@@ -0,0 +1,216 @@
|
||||
---
|
||||
title: "Alert Rules"
|
||||
description: "Subscribe to Pangolin events on sites, resources, and health checks and deliver email, webhooks, or integrations"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
<Note>
|
||||
Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition).
|
||||
</Note>
|
||||
|
||||
Alert rules let you react to changes in Pangolin: you pick a source (what to watch), a trigger (which change matters), and one or more actions (what to do). For example, when a site moves from online to offline, email your admins and support; when a [health check](/manage/alerting/health-checks) or resource becomes unhealthy, call a webhook so a tool like Zapier can fan out the event.
|
||||
|
||||
## Where to create rules
|
||||
|
||||
Create and manage rules from the Alert rules page under Alerting for your organization.
|
||||
|
||||
You can also start a rule from a site or resource detail page: use Create alert rule near the uptime graph to prefill context and keep the flow short.
|
||||
|
||||
## Actions
|
||||
|
||||
When a trigger fires, Pangolin can:
|
||||
|
||||
- Send email (recipients described below).
|
||||
- Call a webhook with a JSON payload (see [Webhook payloads](#webhook-payloads)).
|
||||
- Open an incident or ticket in PagerDuty, Opsgenie, ServiceNow, or incident.io.
|
||||
|
||||
You can attach several actions to the same rule (for example email plus a webhook).
|
||||
|
||||
### Email
|
||||
|
||||
Choose users in your Pangolin organization, entire roles, and/or arbitrary email addresses that should receive the message when the condition is met.
|
||||
|
||||
### Webhooks
|
||||
|
||||
Webhook actions issue an HTTP request to your endpoint when the trigger runs. Payloads are JSON and follow the shapes in [Webhook payloads](#webhook-payloads).
|
||||
|
||||
## Creating an alert rule
|
||||
|
||||
<Frame caption="Create alert rule: source (e.g. all sites), trigger (e.g. site status changes), and actions (email)">
|
||||
<img src="/images/create-alert-rule.png" alt="Create alert rule wizard in the Pangolin dashboard" />
|
||||
</Frame>
|
||||
|
||||
### 1. Source
|
||||
|
||||
Choose what entity the rule watches:
|
||||
|
||||
| Source type | Meaning |
|
||||
| --- | --- |
|
||||
| Site | One or more [sites](/manage/sites/understanding-sites) |
|
||||
| Resource | One or more resources in the org |
|
||||
| Health check | One or more [health checks](/manage/alerting/health-checks) |
|
||||
|
||||
For each type, decide whether the rule applies to all of that kind (for example all sites) or only specific sites, resources, or health checks you select.
|
||||
|
||||
### 2. Trigger
|
||||
|
||||
Available triggers depend on the source type. For sites, options include coming online, going offline, or any status change. For resources and health checks, you get healthy, unhealthy, and combined toggle-style triggers that match how those entities change state—the dashboard only lists combinations that apply to what you selected.
|
||||
|
||||
Pick the condition that should fire the rule (for example site status changes when you care about both online and offline transitions).
|
||||
|
||||
### 3. Actions
|
||||
|
||||
Configure what happens when the trigger runs: add one or more actions (email, webhook, or a vendor integration). Use Add action to stack multiple destinations for the same rule.
|
||||
|
||||
## Webhook payloads
|
||||
|
||||
Webhook bodies are JSON. Every event includes `event`, ISO-8601 `timestamp`, and a `data` object. The event name tells you what changed; `data` always includes `orgId` and entity-specific fields.
|
||||
|
||||
### Site events
|
||||
|
||||
#### `site_online`
|
||||
|
||||
A site came back online.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "site_online",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"siteId": 42,
|
||||
"siteName": "us-east-prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `site_offline`
|
||||
|
||||
A site went offline.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "site_offline",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"siteId": 42,
|
||||
"siteName": "us-east-prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `site_toggle`
|
||||
|
||||
Fires when site connectivity changes, alongside both `site_online` and `site_offline`. Use this when you only care that status flipped, not which direction. `siteId` is always present in `data`.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "site_toggle",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"siteId": 42,
|
||||
"siteName": "us-east-prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Health check events
|
||||
|
||||
#### `health_check_healthy`
|
||||
|
||||
A health check recovered.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "health_check_healthy",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"healthCheckName": "API /healthz"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `health_check_unhealthy`
|
||||
|
||||
A health check is failing.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "health_check_unhealthy",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"healthCheckName": "API /healthz"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `health_check_toggle`
|
||||
|
||||
Fires alongside healthy and unhealthy transitions. `healthCheckId` is included in `data` for this combined event.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "health_check_toggle",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"healthCheckId": 7,
|
||||
"healthCheckName": "API /healthz"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Resource events
|
||||
|
||||
#### `resource_healthy`
|
||||
|
||||
A resource recovered.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "resource_healthy",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"resourceName": "internal-dashboard"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `resource_unhealthy`
|
||||
|
||||
A resource is unhealthy.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "resource_unhealthy",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"resourceName": "internal-dashboard"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `resource_toggle`
|
||||
|
||||
Fires alongside healthy and unhealthy transitions, or when a resource is enabled or disabled. `resourceId` is included in `data`.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "resource_toggle",
|
||||
"timestamp": "2025-06-15T12:34:56.789Z",
|
||||
"data": {
|
||||
"orgId": "org_abc123",
|
||||
"resourceId": 15,
|
||||
"resourceName": "internal-dashboard"
|
||||
}
|
||||
}
|
||||
```
|
||||
55
manage/alerting/health-checks.mdx
Normal file
55
manage/alerting/health-checks.mdx
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: "Health Checks"
|
||||
description: "Monitor reachability and response for public resource targets and arbitrary endpoints from your sites"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
A health check is a periodic probe that decides whether something on your network is up and responding the way you expect. Pangolin runs these checks from your sites so they reflect reachability from the connector’s perspective, not only from wherever an administrator happens to be.
|
||||
|
||||
## Health Checks on Public Resource Targets
|
||||
|
||||
You can attach health checks to individual targets on public resources. When a target fails its health check, Pangolin treats it as unhealthy: it is removed from rotation and load balancing until it passes again, so traffic is not sent to a broken upstream. That behavior is configured per target alongside your proxy settings.
|
||||
|
||||
For step-by-step setup, states (healthy / unhealthy / unknown), and routing implications, see [Health checks & failover](/manage/resources/public/healthchecks-failover).
|
||||
|
||||
## Health Checks in Alerting
|
||||
|
||||
Under Alerting → Health checks for your organization, you get a single view of health checks tied to public resource targets, so you can see status across resources without opening each resource separately.
|
||||
|
||||
<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>
|
||||
|
||||
### Arbitrary Health Checks
|
||||
|
||||
<Note>
|
||||
Arbitrary health checks are only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). Health checks attached to public resource targets are available in all editions.
|
||||
</Note>
|
||||
|
||||
In addition to target-linked checks, you can create standalone health checks that are not attached to any routable resource target. They work the same way at the probe layer, with the same protocols and timing concepts, but only represent reachability for an address your sites can reach (for example an IP or hostname on a remote LAN). You choose which site runs the check so it stays within an addressable range for that connector.
|
||||
|
||||
These are useful when you care about whether a system is up, even if it is not modeled as a Pangolin resource like a network printer, an IP camera, a legacy server, or anything else that should be watched from the site’s network. Pair them with [Alert rules](/manage/alerting/alert-rules) to send notifications when something goes unhealthy or recovers.
|
||||
|
||||
## Check Types
|
||||
|
||||
There are two kinds of checks: HTTP and TCP.
|
||||
|
||||
### HTTP
|
||||
|
||||
An HTTP health check issues an HTTP or HTTPS request to a URL you specify. You can tune the scheme (`http` or `https`), HTTP method (for example `GET` or `POST`), path, headers, expected status codes, and anything else needed to match how the service exposes a liveness endpoint. Success means the response satisfies your criteria (including status code and optional body rules, depending on configuration).
|
||||
|
||||
### TCP
|
||||
|
||||
A TCP health check does not speak application data: it tries to open a TCP connection to a host and port. If the TCP handshake completes, the check is treated as passing; if nothing answers or the connection is refused or times out, it fails. That is ideal for services that only expose a plain port (databases, cameras, PLCs) or when you only care that the host is reachable on a given port.
|
||||
|
||||
## Timing and Thresholds
|
||||
|
||||
Both HTTP and TCP checks support configuration for how often probes run when things are healthy versus when they are failing, how many successes or failures are required before flipping state, and related tuning (for example healthy interval, unhealthy interval, healthy threshold, unhealthy threshold). Exact field names appear in the dashboard; the intent is to avoid flapping—brief blips should not instantly mark a host down, and recovery should be confirmed before treating it as fully healthy again.
|
||||
|
||||
## How the pieces fit together
|
||||
|
||||
- Target-linked health checks on public resources drive routing: unhealthy targets drop out of the pool until they recover.
|
||||
- Arbitrary checks track reachability for addresses your sites can reach—dashboard visibility and [Alert rules](/manage/alerting/alert-rules)—even when there is no Pangolin resource for that system.
|
||||
@@ -3,6 +3,10 @@ title: "DNS Cache"
|
||||
description: "What is a DNS cache and how to manage it with private resources"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
## What is a DNS Cache?
|
||||
A DNS cache is a temporary storage of DNS records that allows for faster resolution of domain names to IP addresses. When a user visits a website, their device queries the DNS server to resolve the domain name to an IP address. The DNS cache stores this information so that subsequent requests for the same domain can be resolved more quickly without needing to query the DNS server again.
|
||||
|
||||
|
||||
@@ -37,6 +37,10 @@ Organization only identity providers appear only on the organization login page.
|
||||
Available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). For [Enterprise Edition](/self-host/enterprise-edition), you must set `app.identity_provider_mode: "org"` in the [private config file](/self-host/advanced/private-config-file#param-identity-provider-mode) `privateConfig.yml`.
|
||||
</Note>
|
||||
|
||||
#### Sharing an identity provider across organizations
|
||||
|
||||
To share an organization-only identity provider across more than one organization, use the import feature. On the Identity Providers table in your organization, click Add Identity Provider and choose Import. You will see identity providers from other organizations where you are an administrator; you can associate another organization’s IdP with the current organization. Configure [auto provisioning](/manage/identity-providers/auto-provisioning) settings separately for each organization, since each organization has its own roles.
|
||||
|
||||
### Global Identity Providers
|
||||
|
||||
Global identity providers are managed at the server level and not the individual organization. They can apply to all or some organizations on the server. This means you must define policies per organization to map users to specific organizations and roles within those organizations.
|
||||
|
||||
@@ -27,7 +27,7 @@ If auto provision is disabled, organization admins will need to manually create
|
||||
<img src="/images/create-idp-user.png" />
|
||||
</Frame>
|
||||
|
||||
## Role mappings
|
||||
## Role Mappings
|
||||
|
||||
When you configure role mappings in auto provisioning settings, you use one of three approaches: fixed roles, mapping builder, or raw expression. These options are available for global identity providers and for organization-only identity providers.
|
||||
|
||||
@@ -35,7 +35,7 @@ When you configure role mappings in auto provisioning settings, you use one of t
|
||||
Auto provisioning does not create roles in Pangolin. Every role you assign whether you pick fixed roles, map IdP values in the builder, or return names from a raw expression must already exist in the target organization, and the name you use must match that role’s name exactly (character-for-character). This one-to-one name match applies to all three mapping types. If a name does not match an existing role, the user will not receive that role (and may not be added to the organization, depending on your setup).
|
||||
</Note>
|
||||
|
||||
### Fixed roles
|
||||
### Role Mapping: Fixed Roles
|
||||
|
||||
Fixed roles is the simplest option. Every user who signs in through the identity provider receives the same set of roles. The roles you select must already exist in Pangolin, and you must choose them by their exact names in that organization. Use this when you do not need dynamic mapping and a single role assignment for everyone is enough. You can still change roles on individual users after they have been auto-provisioned. This is the easiest way to get started.
|
||||
|
||||
@@ -43,7 +43,7 @@ Fixed roles is the simplest option. Every user who signs in through the identity
|
||||
<img src="/images/fixed-roles.png" />
|
||||
</Frame>
|
||||
|
||||
### Mapping builder
|
||||
### Role Mapping: Mapping Builder
|
||||
|
||||
The mapping builder lets you map roles from your identity provider to Pangolin roles without writing expressions. For example, a user might sign in from Azure and belong to several groups there. Azure identifies those groups with its own internal ID strings. With the mapping builder, you translate those IDs to Pangolin role names in the UI.
|
||||
|
||||
@@ -53,7 +53,7 @@ First, choose the claim in the OIDC token where roles or groups are provided suc
|
||||
<img src="/images/mapping-builder.png" />
|
||||
</Frame>
|
||||
|
||||
### Raw expression
|
||||
### Role Mapping: Raw Expression
|
||||
|
||||
Raw expression is the most flexible option and the most complex. It matches how many users previously defined mappings in Pangolin. You provide a [JMESPath](https://jmespath.org/) expression that must evaluate to a string or array of strings. Each value must be the exact name of a role that already exists in the organization. If you can express the logic in JMESPath, it will work (for example, combining conditions on name, email, and other claims).
|
||||
|
||||
@@ -68,6 +68,8 @@ The expression is evaluated against the token from the identity provider on each
|
||||
|
||||
#### Raw Expression Example: JMESPath role selection
|
||||
|
||||
This expression returns `"Admin"` when the user is in the `admin` group, and `"Member"` otherwise.
|
||||
|
||||
**Expression:**
|
||||
|
||||
<Note>
|
||||
@@ -97,7 +99,50 @@ contains(groups, 'admin') && 'Admin' || 'Member'
|
||||
}
|
||||
```
|
||||
|
||||
This expression returns `"Admin"` when the user is in the `admin` group, and `"Member"` otherwise.
|
||||
### Organization Mapping
|
||||
|
||||
Use this when you want to conditionally evaluate if the user should be added to an organization based on the identity provider data. For example, you can add users to an organization based on their email domain or if they are a member of a specific group.
|
||||
|
||||
This is different from the role mapping options because it is not based on the roles assigned to the user, but rather on the organization they should be added to.
|
||||
|
||||
The expression will be matched against each organization. Meaning:
|
||||
|
||||
- The result of the expression must return true or the organization ID as it is defined in the system.
|
||||
- If no matching organization is found, the user will not be added to the organization.
|
||||
|
||||
You can insert the template variable `{{orgId}}` in the expression. This will be replaced with the organization ID when the expression is evaluated.
|
||||
|
||||
#### Example: Email-based Selection
|
||||
|
||||
<Note>
|
||||
When entering a string literal in JMESPath, surround it with `'` (single quotes).
|
||||
</Note>
|
||||
|
||||
This example will return true since the user's email ends with @acme.com. Use this if you want to add users to an organization based on their email domain.
|
||||
|
||||
**Expression:**
|
||||
```
|
||||
ends_with(email, '@acme.com')
|
||||
```
|
||||
|
||||
**Identity Provider Data:**
|
||||
```json
|
||||
{
|
||||
...
|
||||
"sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
|
||||
"aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
|
||||
"exp": 1745790819,
|
||||
"iat": 1745789019,
|
||||
"auth_time": 1745789019,
|
||||
"email": "user@acme.com",
|
||||
"email_verified": true,
|
||||
"name": "Example User",
|
||||
"groups": [
|
||||
"home-lab",
|
||||
"admin"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Global Identity Providers
|
||||
|
||||
@@ -129,82 +174,15 @@ It is helpful to think of the auto provisioning process as follows:
|
||||
|
||||
Use a default policy, per-organization policies, or both. Role mapping options (fixed roles, mapping builder, raw expression) work the same way as described in [Role mappings](#role-mappings).
|
||||
|
||||
### Selecting Organizations
|
||||
|
||||
Use JMESPath to map attributes from the identity provider to organizations in Pangolin. See [JMESPath](https://jmespath.org/) for more information on how to use JMESPath.
|
||||
|
||||
The expression will be matched against each organization. Meaning:
|
||||
|
||||
- The result of the expression must return true or the organization ID as it is defined in the system.
|
||||
- If no matching organization is found, the user will not be added to the organization.
|
||||
|
||||
You can insert the template variable `{{orgId}}` in the expression. This will be replaced with the organization ID when the expression is evaluated.
|
||||
|
||||
### Example 1: Group-based Selection
|
||||
|
||||
**Expression:**
|
||||
```
|
||||
contains(groups, 'home-lab')
|
||||
```
|
||||
|
||||
**Identity Provider Data:**
|
||||
```json
|
||||
{
|
||||
...
|
||||
"sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
|
||||
"aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
|
||||
"exp": 1745790819,
|
||||
"iat": 1745789019,
|
||||
"auth_time": 1745789019,
|
||||
"email": "user@example.com",
|
||||
"email_verified": true,
|
||||
"name": "Example User",
|
||||
"groups": [
|
||||
"home-lab",
|
||||
"admin"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
This example will return true since the user is a member of the "home-lab" group.
|
||||
|
||||
### Example 2: Fixed Organization
|
||||
|
||||
<Note>
|
||||
When entering a string literal in JMESPath, surround it with `'` (single quotes). See below:
|
||||
</Note>
|
||||
|
||||
**Expression:**
|
||||
```
|
||||
'home-lab'
|
||||
```
|
||||
|
||||
**Identity Provider Data:**
|
||||
```json
|
||||
{
|
||||
...
|
||||
"sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
|
||||
"aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
|
||||
"exp": 1745790819,
|
||||
"iat": 1745789019,
|
||||
"auth_time": 1745789019,
|
||||
"email": "user@example.com",
|
||||
"email_verified": true,
|
||||
"name": "Example User",
|
||||
"groups": [
|
||||
"home-lab",
|
||||
"admin"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Default (Fallback) Policy
|
||||
|
||||
You can optionally configure a default policy for all organizations. This will be used if the organization does not have its own policy configured.
|
||||
|
||||
This example will always return 'home-lab' meaning the user will always be added to the "home-lab" organization.
|
||||
|
||||
### Example 1: Dynamic Organization Selection
|
||||
### Example: Dynamic Organization Selection with Interpolation
|
||||
|
||||
When Pangolin evaluates this expression against the "home-lab" organization, it will replace `{{orgId}}` with "home-lab". The result of the expression will return true since the user is a member of the "home-lab" group.
|
||||
|
||||
**Expression:**
|
||||
```
|
||||
@@ -228,6 +206,4 @@ contains(groups, '{{orgId}}')
|
||||
"admin"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
When Pangolin evaluates this expression against the "home-lab" organization, it will replace `{{orgId}}` with "home-lab". The result of the expression will return true since the user is a member of the "home-lab" group.
|
||||
```
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: "Aliases"
|
||||
description: "Set a friendly alias hostname that resolves to a host"
|
||||
description: "Friendly names for resources, overlaps, loopback on the site host, and DNS behavior"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
@@ -9,13 +9,21 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
|
||||
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
||||
## CIDRs Vs. IPs
|
||||
## Overlapping Networks and Loopback on the Site Host
|
||||
|
||||
A 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.
|
||||
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
|
||||
|
||||
@@ -29,14 +37,10 @@ If you use a wildcard such as `*.proxy.internal`, it will match any hostname tha
|
||||
|
||||
## 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. 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 will forward request to an upstream server. By default, we use `9.9.9.9`, but this upstream address can be configured in the CLI or in the client settings.
|
||||
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 or use the --tunnel-dns flag.** Otherwise, connectivity to the server may fail when connected to the tunnel. You must also be overriding the dns of the computer (as discussed above) for this to work because the client needs to intercept the DNS request to forward it to the upstream server.
|
||||
|
||||
## Disable Aliases
|
||||
|
||||
If you wish to disable this behavior and prevent aliases from being resolved and leave your DNS alone, you can do so by adding `--override-dns=false` to the CLI or disable override dns 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.
|
||||
|
||||
## ICMP Ping
|
||||
|
||||
Aliases do not currently support ICMP ping requests. If you attempt to ping an alias, it will not respond, even if the underlying Resource is reachable. This is because the Pangolin client does not intercept ICMP packets for alias resolution.
|
||||
Aliases do not currently support ICMP ping requests. If you attempt to ping an alias, it will not respond, even if the underlying resource is reachable. This is because the Pangolin client does not intercept ICMP packets for alias resolution.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: "Authentication"
|
||||
description: "Only allow access to Resources to specific users, roles, and machines"
|
||||
description: "Only allow access to resources to specific users, roles, and machines"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
@@ -9,24 +9,12 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
|
||||
|
||||
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 WireGuard tunnel to be established to the site hosting the Resource. The Client will show no peers unless access is granted.
|
||||
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 or machine 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 machines will gain access to the Resource when they connect. Note that machines can not be put into roles.
|
||||
* **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 WireGuard tunnel to that Resource if there are no other Resources accessible on that site.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/private_access_controls.png" centered/>
|
||||
</Frame>
|
||||
|
||||
### Port Restrictions
|
||||
|
||||
By default, when access to a Resource is granted, all ports on that Resource are accessible. However, you can restrict access to specific ports on a Resource by defining port restrictions. When port restrictions are defined, only the specified ports will be accessible to users, roles, or machines that have access to the Resource. To specify specific ports, enter either a single port (e.g., `80`), a comma-separated list of ports (e.g., `80,443,8080`), or a port range using a hyphen (e.g., `8000-8100`).
|
||||
|
||||
### ICMP Access
|
||||
|
||||
By default, ICMP (ping) access to Resources is enabled. To disable ICMP access, you can uncheck the "ICMP" option when configuring access to a Resource. This will prevent users, roles, or machines with access to the Resource to send ICMP echo requests (ping) to the Resource's destination. Currently you can not ping an alias.
|
||||
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.
|
||||
|
||||
@@ -1,41 +1,55 @@
|
||||
---
|
||||
title: "Destinations"
|
||||
description: "Understand connection options to the remote network"
|
||||
description: "What a private resource destination is and how to define it (FQDN, IP, or CIDR)"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
## 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.
|
||||
|
||||
A Resource's **destination** can be defined in several ways:
|
||||
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.
|
||||
|
||||
* **Fully Qualified Domain Name (FQDN):** For example, `host.autoco.internal`.
|
||||
* **IP Address:** For example, `10.1.0.35`.
|
||||
* **IP CIDR Range:** For example, `10.1.0.0/16`.
|
||||
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.
|
||||
|
||||
When defining a Resource with an FQDN, the Pangolin site will resolve the FQDN to an IP address on the remote network. This allows you to create Resources that point to hosts whose IP addresses may change over time, as long as the FQDN remains consistent.
|
||||
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)).
|
||||
|
||||
When defining a Resource with an IP address, the Pangolin client will connect directly to that specific IP address on the remote network. It will insert routes for that single IP address into the network route table of the host when users connect with the client.
|
||||
## Defining a Destination
|
||||
|
||||
When defining a Resource with a CIDR range, all IP addresses within that range will be accessible to users who have been granted access to the Resource. This is useful for providing access to entire subnets or network segments. It will insert routes for that single IP address into the network route table of the host when users connect with the client.
|
||||
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.
|
||||
* 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.
|
||||
|
||||
### What about overlaps?
|
||||
### 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 defined which host should be used for a given FQDN or IP address and use the alias to connect.
|
||||
|
||||
### ICMP End to End?
|
||||
|
||||
Pangolin supports testing connectivity to Resources using ICMP ping requests. However, it's important to note that while the Pangolin client can send ICMP echo requests to the destination, **the actual ping request is captured and replayed from the Newt binary to the actually destination**. This means that requests are not end to end but are still an effective way to test connectivity to a resource.
|
||||
|
||||
### Unicast Only?
|
||||
|
||||
Right now unicast TCP and UDP traffic is supported through the Pangolin client. Multicast and broadcast traffic is not supported at this time.
|
||||
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.
|
||||
|
||||
34
manage/resources/private/multi-site-routing.mdx
Normal file
34
manage/resources/private/multi-site-routing.mdx
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: "Multi-site Routing and High Availability"
|
||||
description: "Use multiple sites on a private resource for resilient routing and failover"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
|
||||
|
||||
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.
|
||||
45
manage/resources/private/port-restrictions.mdx
Normal file
45
manage/resources/private/port-restrictions.mdx
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: "Ports and ICMP"
|
||||
description: "Configure TCP and UDP port modes and ICMP (ping) for private resources"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
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>
|
||||
34
manage/resources/private/private-http.mdx
Normal file
34
manage/resources/private/private-http.mdx
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: "Private HTTP"
|
||||
description: "HTTPS private resources on your domain with a connected client—Pangolin Cloud and Enterprise; reverse proxy and TLS on the site"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
<Note>
|
||||
Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition).
|
||||
</Note>
|
||||
|
||||
Private HTTP is a special kind of private resource for web workloads. It behaves similarly to a [public resource](/manage/resources/understanding-resources#public-resources) in that traffic is HTTP-based and flows through a reverse proxy with a proper hostname, but it only works when the user has an active Pangolin client connection. Nothing is exposed on the public internet; access is entirely off the internet until someone is on the tunnel.
|
||||
|
||||
## Hostname, DNS, and TLS
|
||||
|
||||
When you enable private HTTP, you assign a domain name to the resource. 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.
|
||||
|
||||
You can 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, the request is resolved to the site the same way as with alias-style flows, but 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 the routing and pushes certificates to the edge where your site runs, 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. Authentication on who may use the resource still follows your private resource access rules (users, roles, machines), but the network path is client-attached only.
|
||||
@@ -1,144 +1,107 @@
|
||||
---
|
||||
title: "Health Checks"
|
||||
description: "Configure automated health monitoring and failover for resources"
|
||||
title: "Health Checks and Failover"
|
||||
description: "Monitor public resource targets and automatically remove unhealthy targets from routing"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
For every target on a public resource, Pangolin runs checks at your configured intervals and evaluates the result against your health criteria.
|
||||
|
||||
## How Health Checks Work
|
||||
- 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.
|
||||
|
||||
### Monitoring Process
|
||||
This gives automatic failover across targets without manual intervention.
|
||||
|
||||
Health checks operate continuously in the background:
|
||||
## Target states
|
||||
|
||||
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.
|
||||
Targets move through three operational states:
|
||||
|
||||
## Target Health 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.
|
||||
|
||||
Targets can exist in three distinct states that determine how traffic is routed:
|
||||
## Check types
|
||||
|
||||
<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>
|
||||
Public resource target health checks support the same two probe types used by arbitrary health checks:
|
||||
|
||||
<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>
|
||||
- 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.
|
||||
|
||||
<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>
|
||||
## Configure health checks on a target
|
||||
|
||||
## Configuring Health Checks
|
||||
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.
|
||||
|
||||
<Steps>
|
||||
<Step title="Access Target Settings">
|
||||
In the Pangolin dashboard, navigate to your resource and locate the target in the table.
|
||||
</Step>
|
||||
Each target can have its own health check settings.
|
||||
|
||||
<Step title="Open Health Check Configuration">
|
||||
Click the settings wheel (⚙️) next to the health check endpoint column.
|
||||
</Step>
|
||||
<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>
|
||||
|
||||
<Step title="Configure Health Check Parameters">
|
||||
Fill out the health check configuration with your desired parameters.
|
||||
</Step>
|
||||
## Common parameters
|
||||
|
||||
<Step title="Save Configuration">
|
||||
Save your settings to enable health checking for the target.
|
||||
</Step>
|
||||
</Steps>
|
||||
Some of the most important settings to tune are:
|
||||
|
||||
## Health Check Parameters
|
||||
- `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.
|
||||
|
||||
### Endpoint Configuration
|
||||
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.
|
||||
|
||||
- **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`)
|
||||
<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>
|
||||
|
||||
### Timing Configuration
|
||||
## Public resource failover patterns
|
||||
|
||||
#### Healthy Interval
|
||||
### Multi-target redundancy
|
||||
|
||||
- **Purpose**: How often to check targets that are currently healthy
|
||||
- **Typical Range**: 30-60 seconds
|
||||
- **Consideration**: Less frequent checks reduce overhead
|
||||
Use multiple targets for the same service. If one goes unhealthy, traffic continues to healthy targets.
|
||||
|
||||
#### 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.
|
||||
|
||||
```
|
||||
```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 ✅
|
||||
├── 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
|
||||
### 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 ✅
|
||||
│ ├── api-01.primary:8443 - Healthy
|
||||
│ └── api-02.primary:8443 - Healthy
|
||||
└── Backup Site Targets
|
||||
├── api-01.backup:8443 - Healthy ✅
|
||||
└── api-02.backup:8443 - Healthy ✅
|
||||
├── 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.
|
||||
|
||||
38
manage/resources/public/wildcard-resources.mdx
Normal file
38
manage/resources/public/wildcard-resources.mdx
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: "Wildcard Resources"
|
||||
description: "Pangolin Cloud and Enterprise: route every hostname at a subdomain level through one public resource"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
<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.
|
||||
|
||||
## 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.
|
||||
123
self-host/advanced/traefik-log-rotation.mdx
Normal file
123
self-host/advanced/traefik-log-rotation.mdx
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: "Traefik Access Log Rotation"
|
||||
description: "How to manage and rotate Traefik access logs when CrowdSec is installed"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
When CrowdSec is installed, Traefik access logging is enabled automatically so CrowdSec can analyze traffic. This means `config/traefik/logs/access.log` will grow indefinitely without log rotation in place.
|
||||
|
||||
<Note>
|
||||
The default Pangolin install (without CrowdSec) does not enable access
|
||||
logging, so this only applies if you have CrowdSec installed.
|
||||
</Note>
|
||||
|
||||
## How it works
|
||||
|
||||
The CrowdSec installer enables Traefik's `accessLog` block and mounts `./config/traefik/logs/` into the container at `/var/log/traefik/`. CrowdSec reads that log via its `acquis.d/traefik.yaml` acquisition config.
|
||||
|
||||
Without rotation, that file grows forever. The fix is `logrotate` with `copytruncate` — it copies the log file and truncates the original in place, so Traefik never needs to be restarted or sent a signal.
|
||||
|
||||
## Automatic setup (installer v1.x+)
|
||||
|
||||
If you installed CrowdSec using a recent version of the Pangolin installer, logrotate is configured automatically at `/etc/logrotate.d/pangolin-traefik`. You can verify it's there:
|
||||
|
||||
```bash
|
||||
cat /etc/logrotate.d/pangolin-traefik
|
||||
```
|
||||
|
||||
You should see something like:
|
||||
|
||||
```
|
||||
/opt/pangolin/config/traefik/logs/access.log {
|
||||
daily
|
||||
rotate 7
|
||||
compress
|
||||
delaycompress
|
||||
missingok
|
||||
notifempty
|
||||
copytruncate
|
||||
}
|
||||
```
|
||||
|
||||
## Manual setup
|
||||
|
||||
If you installed CrowdSec before automatic log rotation was added, set it up manually:
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the logrotate config">
|
||||
Replace `/opt/pangolin` with your actual Pangolin install directory if it differs.
|
||||
|
||||
```bash
|
||||
sudo tee /etc/logrotate.d/pangolin-traefik > /dev/null <<'EOF'
|
||||
/opt/pangolin/config/traefik/logs/access.log {
|
||||
daily
|
||||
rotate 7
|
||||
compress
|
||||
delaycompress
|
||||
missingok
|
||||
notifempty
|
||||
copytruncate
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Test the configuration">
|
||||
Do a dry run to confirm logrotate picks it up without errors:
|
||||
|
||||
```bash
|
||||
sudo logrotate --debug /etc/logrotate.d/pangolin-traefik
|
||||
```
|
||||
|
||||
No errors means you're good. You can also force a rotation immediately to verify end-to-end:
|
||||
|
||||
```bash
|
||||
sudo logrotate --force /etc/logrotate.d/pangolin-traefik
|
||||
```
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Customizing retention
|
||||
|
||||
The defaults (daily rotation, 7 compressed copies) work for most setups. To adjust:
|
||||
|
||||
| Option | What it does |
|
||||
| --------------- | -------------------------------------------------------------------------------------- |
|
||||
| `daily` | Rotate once per day. Use `weekly` or `monthly` if preferred. |
|
||||
| `rotate 7` | Keep 7 rotated files before deleting the oldest. |
|
||||
| `compress` | Gzip rotated files to save disk space. |
|
||||
| `delaycompress` | Skip compressing the most recent rotated file (useful if something still has it open). |
|
||||
|
||||
For example, to keep 30 days of compressed weekly logs:
|
||||
|
||||
```
|
||||
/opt/pangolin/config/traefik/logs/access.log {
|
||||
weekly
|
||||
rotate 30
|
||||
compress
|
||||
delaycompress
|
||||
missingok
|
||||
notifempty
|
||||
copytruncate
|
||||
}
|
||||
```
|
||||
|
||||
## Verifying rotation is working
|
||||
|
||||
Check that rotated files are appearing in the logs directory:
|
||||
|
||||
```bash
|
||||
ls -lh /opt/pangolin/config/traefik/logs/
|
||||
```
|
||||
|
||||
After the first rotation you should see files like `access.log.1` and `access.log.2.gz` alongside the active `access.log`.
|
||||
|
||||
To see when logrotate last ran and whether it succeeded:
|
||||
|
||||
```bash
|
||||
cat /var/lib/logrotate/status | grep pangolin
|
||||
```
|
||||
@@ -140,25 +140,7 @@ This is the default config generated by the installer. This is shown here for re
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="2. Add Wildcard Domains">
|
||||
Add the domain and wildcard domain to the domains section of the next (front end) router in the dynamic config. This tells Traefik to generate a wildcard certificate for the base domain and all subdomains.
|
||||
|
||||
```yaml title="dynamic_config.yml" highlight={8-12}
|
||||
next-router:
|
||||
rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
|
||||
service: next-service
|
||||
entryPoints:
|
||||
- websecure
|
||||
tls:
|
||||
certResolver: letsencrypt
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="3. Add Environment Variables">
|
||||
<Step title="2. Add Environment Variables">
|
||||
Add the environment variables for your DNS provider to the Traefik service in the docker compose file. This allows Traefik to authenticate with your DNS provider to create the DNS records needed for the challenge.
|
||||
|
||||
```yaml title="docker-compose.yml" highlight={11-13}
|
||||
@@ -180,6 +162,27 @@ This is the default config generated by the installer. This is shown here for re
|
||||
- ./config/letsencrypt:/letsencrypt
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="3. Add Wildcard Domains">
|
||||
|
||||
This step is optional and only effects the certs generated for the Pangolin dashboard. If you only plan to create wildcard resources and not use the dashboard, you can skip this step.
|
||||
|
||||
Add the domain and wildcard domain to the domains section of the next (front end) router in the dynamic config. This tells Traefik to generate a wildcard certificate for the base domain and all subdomains.
|
||||
|
||||
```yaml title="dynamic_config.yml" highlight={8-12}
|
||||
next-router:
|
||||
rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)"
|
||||
service: next-service
|
||||
entryPoints:
|
||||
- websecure
|
||||
tls:
|
||||
certResolver: letsencrypt
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
|
||||
@@ -18,6 +18,10 @@ CrowdSec is a modern, open-source, collaborative behavior detection engine, inte
|
||||
|
||||
Crowdsec can be installed using the Pangolin Installer.
|
||||
|
||||
<Tip>
|
||||
Enabling CrowdSec turns on Traefik access logging so CrowdSec can analyze traffic. This means `config/traefik/logs/access.log` will grow over time. If you want to set up log rotation, see the [Traefik Access Log Rotation](/self-host/advanced/traefik-log-rotation) guide.
|
||||
</Tip>
|
||||
|
||||
## Configuration
|
||||
|
||||
By default, Crowdsec is installed with a basic configuration, which includes the [Crowdsec Bouncer Traefik plugin](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin).
|
||||
|
||||
Reference in New Issue
Block a user