mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-02-08 05:56:45 +00:00
Merge branch 'dev'
This commit is contained in:
Owen
@@ -46,8 +46,9 @@
|
||||
"pages": [
|
||||
"manage/resources/public/authentication",
|
||||
"manage/resources/public/targets",
|
||||
"manage/healthchecks-failover",
|
||||
"manage/resources/public/raw-resources"
|
||||
"manage/resources/public/raw-resources",
|
||||
"manage/resources/public/maintenance",
|
||||
"manage/resources/public/healthchecks-failover"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -282,6 +283,10 @@
|
||||
{
|
||||
"source": "/manage/resources/tcp-udp-resources",
|
||||
"destination": "/manage/resources/public/raw-resources"
|
||||
},
|
||||
{
|
||||
"source": "manage/healthchecks-failover",
|
||||
"destination": "manage/resources/public/healthchecks-failover"
|
||||
}
|
||||
],
|
||||
"seo": {
|
||||
|
||||
BIN
images/maintenance_page.png
Normal file
BIN
images/maintenance_page.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
@@ -21,6 +21,10 @@ Pangolin supports two blueprint formats:
|
||||
1. **YAML Configuration Files**: Standalone configuration files
|
||||
2. **Docker Labels**: Configuration embedded in Docker Compose files
|
||||
|
||||
<Note type="info">
|
||||
Some features in this documentation are marked with **(EE)**, indicating they are available only in the Enterprise Edition of Pangolin.
|
||||
</Note>
|
||||
|
||||
## YAML Configuration Format
|
||||
|
||||
YAML config can be applied using Docker labels, API, from a Newt site, or in the UI. _Application through a CLI tool is planned._
|
||||
@@ -159,6 +163,35 @@ public-resources:
|
||||
When using targets-only resources, the `name` and `protocol` fields are not required. All other resource-level validations are skipped for these simplified configurations.
|
||||
</Note>
|
||||
|
||||
### Maintenance Page Configuration **(EE)**
|
||||
|
||||
<Note type="warning">
|
||||
This is an Enterprise Edition (EE) feature only. It allows you to display a maintenance page for a public resource when it's under maintenance or when targets are unhealthy.
|
||||
</Note>
|
||||
|
||||
```yaml
|
||||
public-resources:
|
||||
production-app:
|
||||
name: Production Application
|
||||
protocol: http
|
||||
full-domain: app.example.com
|
||||
maintenance:
|
||||
enabled: true
|
||||
type: forced
|
||||
title: Scheduled Maintenance
|
||||
message: We are performing system upgrades to improve performance. The service will be back online shortly.
|
||||
estimated-time: 2 hours
|
||||
targets:
|
||||
- site: my-site
|
||||
hostname: app-server
|
||||
method: https
|
||||
port: 443
|
||||
```
|
||||
|
||||
**Maintenance Types:**
|
||||
- **`forced`**: Always displays the maintenance page regardless of target health status
|
||||
- **`automatic`**: Displays the maintenance page only when all targets are unhealthy or the sites are offline
|
||||
|
||||
### Private Resources
|
||||
|
||||
Private resources define proxied resources accessible when connected via an client:
|
||||
@@ -295,6 +328,7 @@ This will create a resource that looks like the following:
|
||||
| `headers` | array | No | Custom headers to add to requests | Each header requires `name` and `value` (min 1 char each) |
|
||||
| `rules` | array | No | Access control rules | See Rules section below |
|
||||
| `auth` | object | HTTP only | Authentication configuration | See Authentication section below |
|
||||
| `maintenance` | object | No | Maintenance page configuration **(EE)** | Enterprise Edition only. See Maintenance Configuration section below |
|
||||
| `targets` | array | Yes | Target endpoints for the resource | See Targets section below |
|
||||
|
||||
### Target Configuration
|
||||
@@ -374,6 +408,45 @@ Not allowed on TCP/UDP resources.
|
||||
| `whitelist-users` | array | No | Whitelisted user emails | Must be valid email addresses |
|
||||
| `auto-login-idp` | number | No | Automatic login identity provider ID | Must be a positive integer |
|
||||
|
||||
### Maintenance Configuration **(EE)**
|
||||
|
||||
<Note type="warning">
|
||||
This is an Enterprise Edition (EE) feature only. It allows you to display a maintenance page for a public resource.
|
||||
</Note>
|
||||
|
||||
The `maintenance` object can be added to any public resource to display a maintenance page to users:
|
||||
|
||||
```yaml
|
||||
public-resources:
|
||||
my-service:
|
||||
name: My Service
|
||||
protocol: http
|
||||
full-domain: service.example.com
|
||||
maintenance:
|
||||
enabled: true
|
||||
type: automatic
|
||||
title: Scheduled Maintenance
|
||||
message: We are performing scheduled maintenance. Service will resume shortly.
|
||||
estimated-time: 2 hours
|
||||
targets:
|
||||
- site: my-site
|
||||
hostname: backend-server
|
||||
method: https
|
||||
port: 8443
|
||||
```
|
||||
|
||||
| Property | Type | Required | Description | Constraints |
|
||||
|----------|------|----------|-------------|-------------|
|
||||
| `enabled` | boolean | No | Whether the maintenance page is enabled | Defaults to `false` |
|
||||
| `type` | string | No | Maintenance type (`forced` or `automatic`) | `forced` always shows maintenance page; `automatic` shows only when all targets are unhealthy or sites offline |
|
||||
| `title` | string | No | Title text for the maintenance page | Maximum 255 characters, can be null |
|
||||
| `message` | string | No | Message text explaining the maintenance | Maximum 2000 characters, can be null |
|
||||
| `estimated-time` | string | No | Estimated time for maintenance completion | Maximum 100 characters, can be null |
|
||||
|
||||
**Maintenance Types:**
|
||||
- **`forced`**: Always displays the maintenance page regardless of target health status
|
||||
- **`automatic`**: Displays the maintenance page only when all targets are unhealthy
|
||||
|
||||
### Rules Configuration
|
||||
|
||||
| Property | Type | Required | Description | Constraints |
|
||||
|
||||
@@ -123,6 +123,12 @@ Refer to the [documentation in the official repository](https://github.com/fosrl
|
||||
**Default**: `false`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="tunnel-dns" type="boolean">
|
||||
Force connectivity to the upstream DNS server to go via the tunnel to a resource.
|
||||
|
||||
**Default**: `false`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="disable-relay" type="boolean">
|
||||
Disable relay connections.
|
||||
|
||||
|
||||
@@ -15,9 +15,17 @@ A alias can only be created for a Resource that is a single host (IP or FQDN). A
|
||||
|
||||
Since aliases cannot be single-label domains, you must avoid using domain names that do not contain a dot (e.g., `pangolin`). A domain like `pangolin.net`, which includes a dot, is acceptable. Instead of a single-label domain, you should consider using a subdomain of a domain you control, such as `router.mywebsite.com`, or an existing private/internal domain name, like `router.internal` or `router.corp`.
|
||||
|
||||
### Wildcards
|
||||
|
||||
Wildcards allow you to define aliases that match multiple hostnames using special characters in the FQDN. For example, in an alias like `*.host-0?.autoco.internal`, the asterisk `*` matches any sequence of characters (including none), and the question mark `?` matches exactly one character.
|
||||
|
||||
If you use a wildcard such as `*.proxy.internal`, it will match any hostname that ends with `.proxy.internal` and has something before the dot—such as `host.proxy.internal`, `longerhost.proxy.internal`, or even `sub.host.proxy.internal`. However, the wildcard will not match the base domain itself (`autoco.internal` without anything before the dot).
|
||||
|
||||
## 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` which will forward request to an upstream server. By default, we use `9.9.9.9`, but this upstream address can be configured using [the flag](/manage/clients/configure-client) in the CLI / Olm 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. 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 using [the flag](/manage/clients/configure-client) in the CLI / Olm 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.
|
||||
|
||||
## Disable Aliases
|
||||
|
||||
|
||||
@@ -26,9 +26,9 @@ Pangolin smooths away overlapping networks and arbitrarily chooses a single site
|
||||
|
||||
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.
|
||||
|
||||
## Why is ICMP Pinging Not Working?
|
||||
## ICMP End to End?
|
||||
|
||||
Because Newt sites are proxying traffic out of the secure tunnel, ICMP needs to be handled specially just like UDP and TCP. Right now, ICMP **is not supported** through the Pangolin client. If you need to ping hosts on the remote network, consider using TCP or UDP-based tools like `hping3` or `nping` as alternatives. We plan to add ICMP support in a future release.
|
||||
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?
|
||||
|
||||
|
||||
38
manage/resources/public/maintenance.mdx
Normal file
38
manage/resources/public/maintenance.mdx
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: "Maintenance Page"
|
||||
description: "Show a maintenance page to users when a resources is down for maintenance or targets are unhealthy"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Maintenance pages are only available in Enterprise Edition.
|
||||
</Note>
|
||||
|
||||
Pangolin can display a customizable maintenance page to users when a resource is undergoing maintenance or when all targets are unhealthy. This ensures users are informed about the downtime and provides a better user experience.
|
||||
|
||||
<Frame caption="Maintenance Page Preview">
|
||||
<img src="/images/maintenance_page.png" alt="Maintenance Page Preview"/>
|
||||
</Frame>
|
||||
|
||||
## Configuration
|
||||
|
||||
Title: The main title text displayed on the maintenance page.
|
||||
|
||||
Message: A descriptive message informing users about the maintenance status.
|
||||
|
||||
Estimated completion time: Optionally provide an estimated time for when the resource will be back online.
|
||||
|
||||
## Enabling Maintenance Page
|
||||
|
||||
To enable the maintenance page for a resource, navigate to the general resource settings in the Pangolin dashboard. Under the "Maintenance Page" section, you can customize the title, message, and estimated completion time. This can also be set using Blueprints.
|
||||
|
||||
## When is the Maintenance Page Shown?
|
||||
|
||||
There are two modes that control when the page is shown:
|
||||
|
||||
#### Forced
|
||||
|
||||
In forced mode, the maintenance page is displayed to all users regardless of the health status of the resource targets. This is useful for planned maintenance windows.
|
||||
|
||||
#### Automatic
|
||||
|
||||
In automatic mode, the maintenance page is shown only when all targets associated with the resource are unhealthy or all of the sites are offline. This is useful for unplanned outages and can be used to inform the user that the resource is temporarily unavailable by customizing the above settings.
|
||||
@@ -461,6 +461,12 @@ This section contains the complete reference for all configuration options in `c
|
||||
**Example**: `51820`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="clients_start_port" type="integer">
|
||||
Starting port for client WireGuard relay and hole punch port.
|
||||
|
||||
**Example**: `21820`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="use_subdomain" type="boolean">
|
||||
Whether to assign unique subdomains to Gerbil exit nodes.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user