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

port mintlify to fumadocs

Browse Source
This commit is contained in:
miloschwartz
2026-09-25 15:31:51 -04:00
parent dc54fb1017
commit 63199a588c
373 changed files with 13533 additions and 4577 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/docs/manage/remote-node/backhaul.mdx
+275
View File
@@ -0,0 +1,275 @@
---
title: "Site to Cloud Backhaul"
description: "Turn a remote node into a network concentrator that routes traffic between a cloud VPC and your Pangolin sites for edge to cloud backhaul"
---
<Note>
Site to cloud is an advanced [remote node](/manage/remote-node/understanding-nodes) configuration available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition).
</Note>
A standard remote node terminates WireGuard tunnels and proxies HTTP(S) traffic to your resources. A **backhaul** node goes a step further: it acts as an IP router between an entire network, such as a cloud VPC, and your Pangolin sites. Instead of just forwarding individual resource connections, the node forwards whole subnets, letting hosts on either side reach each other without needing to install site and client on every machine.
This is useful when you want to bridge a cloud network (for example, an AWS VPC) with your on-prem or office network through Pangolin, using a node running in that VPC as the concentrator.
Another common use case is connecting edge devices to a cloud network. Edge devices can send traffic to a service in the cloud, and the cloud can send traffic down to a specific edge device. In both cases, the persistent backhaul tunnel carries the traffic.
<Frame>
<img src="/images/basic-backhaul-diagram.png" alt="Diagram of a backhaul remote node in a cloud network with bidirectional tunnels to sites on remote private networks" />
</Frame>
<Tip>
Site to cloud builds on top of a normal remote node install. Read [Remote Nodes](/manage/remote-node/understanding-nodes) and [Quick Install Guide](/manage/remote-node/quick-install-remote) first if you haven't deployed a node yet.
</Tip>
## How It Works
- **The node routes, it doesn't just proxy.** Gerbil creates the WireGuard interface directly on the host and Docker forwards packets between it and the host's network, rather than isolating traffic inside a container network namespace.
- **The cloud network learns to route to the node.** You add a route in your VPC (or other network) so that traffic destined for the Pangolin overlay is sent to the node.
- **The node learns to route to the cloud network.** You register the VPC's CIDR on the node so it's pushed down to your sites as a route.
- **Sites route natively.** Sites connect with native routing mode so the tunnel subnet is a real route on the site's host, not just an application-layer proxy.
## Prerequisites
- A Linux server with Docker and root access, dedicated to running the backhaul node.
- Administrative access to the cloud network you want to bridge (for example, an AWS VPC) so you can edit security groups, route tables, and instance settings.
## Enable IP Forwarding on the Host
Because the node forwards packets between the WireGuard tunnel and the host network instead of only terminating them, the host must have IP forwarding enabled.
```bash
sudo sysctl -w net.ipv4.ip_forward=1
```
Make it permanent by adding `net.ipv4.ip_forward=1` to `/etc/sysctl.d/99-pangolin-backhaul.conf`.
Docker enables forwarding in its own iptables rules by default, but if you've disabled Docker's iptables management, or packets are still being dropped, allow forwarded traffic through Docker's chain in `/etc/docker/daemon.json`:
```json title="/etc/docker/daemon.json"
{
"ip-forward-no-drop": true
}
```
Restart Docker after changing this file. See Docker's [packet filtering and firewalls guide](https://docs.docker.com/engine/network/packet-filtering-firewalls/#docker-on-a-router) for background on running Docker on a router.
## Deploy the Node with Host Networking
The standard node install runs Gerbil and Traefik on a bridge network, with Traefik sharing Gerbil's network namespace. For backhaul, all three services run with `network_mode: host` instead. This gives Gerbil direct access to the host's network stack and routing table, which is required for it to create routes for the subnets you register instead of only handling its own tunnel traffic.
```yaml title="docker-compose.yml"
name: pangolin
services:
pangolin:
image: docker.io/fosrl/pangolin-node:latest # We recommend locking to a specific version for stability.
container_name: pangolin
restart: unless-stopped
network_mode: host
volumes:
- ./config:/app/config
- pangolin-data-certificates:/var/certificates
- pangolin-data-dynamic:/var/dynamic
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"]
interval: "10s"
timeout: "10s"
retries: 15
gerbil:
image: docker.io/fosrl/gerbil:latest
container_name: gerbil
restart: unless-stopped
network_mode: host
depends_on:
pangolin:
condition: service_healthy
command:
- --reachableAt=http://localhost:3003
- --generateAndSaveKeyTo=/var/config/key
- --remoteConfig=http://localhost:3001/api/v1/
volumes:
- ./config/:/var/config
cap_add:
- NET_ADMIN
- SYS_MODULE
traefik:
image: docker.io/traefik:v3.7
container_name: traefik
restart: unless-stopped
network_mode: host
depends_on:
pangolin:
condition: service_healthy
command:
- --configFile=/etc/traefik/traefik_config.yml
volumes:
- ./config/traefik:/etc/traefik:ro
- ./config/traefik/logs:/var/log/traefik
- pangolin-data-certificates:/var/certificates:ro
- pangolin-data-dynamic:/var/dynamic:ro
volumes:
pangolin-data-dynamic:
pangolin-data-certificates:
```
<Note>
With `network_mode: host`, containers bind to ports directly on the host, so there's no `ports` mapping and no `network_mode: service:gerbil` on Traefik like there is in the [standard install](/self-host/manual/docker-compose). Gerbil and Traefik reach each other and Pangolin over `localhost`.
</Note>
## Configure the Node
The `config.yml` for a backhaul node uses the same fields as any [remote node](/manage/remote-node/config-file), mounted at `config/config.yml`:
```yaml title="config/config.yml"
gerbil:
start_port: 51820
base_endpoint: "203.0.113.10" # REPLACE WITH YOUR NODE'S PUBLIC IP OR DOMAIN
reachable_at: http://localhost:3003
server:
internal_port: 3001
internal_hostname: localhost
managed:
id: "he4g78wevj25msf" # REPLACE WITH YOUR NODE'S ID
secret: "n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d" # REPLACE WITH YOUR NODE'S SECRET
```
See the [configuration file reference](/manage/remote-node/config-file) for every available option.
## Configure Traefik
Traefik's config is largely the same as a standard node, with `trustedIPs` opened up to accept the proxy protocol header from Gerbil on the host network:
```yaml title="config/traefik/traefik_config.yml"
api:
insecure: true
dashboard: true
providers:
file:
directory: "/var/dynamic"
watch: true
experimental:
plugins:
badger:
moduleName: "github.com/fosrl/badger"
version: "v1.7.0" # Check GitHub Releases for latest version tag
log:
level: "INFO"
format: "common"
maxSize: 100
maxBackups: 3
maxAge: 3
compress: true
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
proxyProtocol:
trustedIPs:
- 0.0.0.0/0 # This is coming from Gerbil
- ::1/128
transport:
respondingTimeouts:
readTimeout: "30m"
serversTransport:
insecureSkipVerify: true
ping:
entryPoint: "web"
```
## Configure the Cloud Network
This section uses AWS as an example, but the same steps apply to any VPC-style network: the node needs to be allowed to receive and forward traffic for the whole network, and the network needs a route pointing back at the node.
<Steps>
<Step title="Allow all traffic into the node">
The node is acting as a concentrator for the whole network, not just serving its own ports, so its security group must accept all traffic from the VPC's CIDR. Otherwise the security group blocks the inbound traffic it's meant to forward.
<Frame>
<img src="/images/security_group_inbound_to_node.png" alt="AWS security group inbound rule allowing all VPC traffic" />
</Frame>
</Step>
<Step title="Route the Pangolin overlay through the node">
Add a route in the VPC's route table for the WireGuard overlay subnet assigned to your node (shown as the node's **Address** on its page in the [Pangolin dashboard](https://app.pangolin.net)), targeting the node's instance or network interface. This tells the rest of the VPC to send anything destined for the Pangolin overlay - other sites and clients - to the node.
<Frame>
<img src="/images/subnet_in_route_table.png" alt="AWS route table entry routing the overlay subnet to the node" />
</Frame>
</Step>
<Step title="Disable source/destination check">
By default, AWS drops any packet where an instance isn't the source or destination, which would silently break a node that's forwarding traffic on behalf of others. Disable the source/destination check on the node's instance so it's allowed to route traffic that isn't addressed to itself.
<Frame>
<img src="/images/source_destination_check_menu.png" alt="AWS instance menu option to change source/destination check" />
</Frame>
<Frame>
<img src="/images/source_destination_check_box.png" alt="AWS dialog checkbox disabling the source/destination check" />
</Frame>
</Step>
<Step title="Advertise the VPC subnet on the node">
In the node's settings in the Pangolin dashboard, add the VPC's CIDR (for example, `172.31.0.0/16`) to **Remote Subnets** under the **Networking** tab. This is pushed down to your sites as a route, so they know to send traffic for that subnet through this node's tunnel.
You can also set **Preference Labels** on the node and apply matching labels to sites, which enforces that those sites connect through this remote node specifically. This is useful once you have more than one node or point of presence and want particular sites to always backhaul through this one.
<Frame>
<img src="/images/subnet_programmed_on_node.png" alt="Pangolin dashboard remote subnets setting with VPC CIDR added" />
</Frame>
</Step>
</Steps>
## Enable Native Routing on Your Sites
For the VPC and a site's network to route to each other, the tunnel needs to be a real route on the site's host, not just something the Pangolin Site proxies at the application layer. Start the site with `--native-main` so it creates the network interface and routes directly on the host:
```bash
sudo pangolin up site \
--id 34s48my8iba5wsl \
--secret ts1v7480qqw01j7ba4uiw5y7l58skw7anpji2ndludhgzloh \
--endpoint https://app.pangolin.net \
--native-main
```
On Windows, set `nativeMain` in `C:\Users\<Username>\.config\pangolin\site.json` instead:
```json title="C:\Users\<Username>\.config\pangolin\site.json"
{
"id": "34s48my8iba5wsl",
"secret": "ts1v7480qqw01j7ba4uiw5y7l58skw7anpji2ndludhgzloh",
"endpoint": "https://app.pangolin.net",
"nativeMain": true
}
```
<Warning>
If you are using a Pangolin Site on Windows, `wintun.dll` is required to run in native mode. If not already provided by the installer, you can download from https://www.wintun.net/
</Warning>
<Warning>
Windows doesn't respond to ICMP echo requests (ping) over the tunnel interface by default. If you need to ping a Windows site, enable the built-in firewall rule for it:
```powershell
Enable-NetFirewallRule -DisplayName "File and Printer Sharing (Echo Request - ICMPv4-In)"
```
</Warning>
## Resolving a Site's Address Directly
If something outside of Pangolin's normal resource routing needs to reach a site directly, for example a static route configured elsewhere in your network or a cloud service sending traffic to a specific edge device, you can resolve `<siteId>.site.pangolin.net` (the site ID is the one used in the `--id` argument when running the site) to get the site's current routable address.
## High Availability
Deploy multiple nodes in your network. Each node will have a different routable subnet. Repeating the above steps will ensure they are routed to uniquely. Sites will connect to one of the nodes in the network and if it does down fail over to another online node.
Make sure to use the site's DNS address to connect to it as when it moves between nodes its address may change.
content/docs/manage/remote-node/config-file.mdx
+85
View File
@@ -0,0 +1,85 @@
---
title: "Configuration File"
description: "Configure your remote node using the config.yml file"
---
The `config.yml` file includes basic config variable for your remote node. This file is mounted at `config/config.yml` in your Docker container.
Minimal configuration file:
```yaml title="config.yml"
gerbil:
start_port: 51820
base_endpoint: "154.123.45.67" # REPLACE WITH YOUR IP OR DOMAIN
managed:
id: "he4g78wevj25msf"
secret: "n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d"
```
### Gerbil Tunnel Controller
<ResponseField name="gerbil" type="object" required>
Gerbil tunnel controller settings for WireGuard tunneling.
<Expandable title="Gerbil">
<ResponseField name="base_endpoint" type="string" required>
Domain name included in WireGuard configuration for tunnel connections.
**Example**: `pangolin.example.com`
</ResponseField>
<ResponseField name="start_port" type="integer">
Starting port for WireGuard tunnels.
**Example**: `51820`
</ResponseField>
</Expandable>
</ResponseField>
### Remote Node Configuration
<ResponseField name="managed" type="object">
Settings for connecting the remote node to the Pangolin head server.
<Expandable title="Managed">
{/* <ResponseField name="name" type="string">
Display name for the managed deployment.
**Example**: `My Self-Hosted Instance`
</ResponseField> */}
<ResponseField name="id" type="string">
Unique identifier for the managed deployment. Generated from the installer or the [Pangolin dashboard](https://app.pangolin.net).
**Example**: `he4g78wevj25msf`
</ResponseField>
<ResponseField name="secret" type="string">
Secret key for authenticating with the managed service. Generated from the installer or the [Pangolin dashboard](https://app.pangolin.net).
**Example**: `n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d`
<Warning>
Keep this secret secure and do not share it publicly.
</Warning>
</ResponseField>
<ResponseField name="endpoint" type="string">
The managed service endpoint to connect to. This can only change with enterprise deployments.
**Example**: `https://app.pangolin.net`
**Default**: `https://app.pangolin.net`
</ResponseField>
<ResponseField name="redirect_endpoint" type="string">
Custom redirect endpoint for authentication flows. This can only change for enterprise deployments.
**Example**: `https://my-pangolin.example.com`
<Note>
If not specified, the default dashboard URL will be used.
</Note>
</ResponseField>
</Expandable>
</ResponseField>
content/docs/manage/remote-node/quick-install-remote.mdx
+108
View File
@@ -0,0 +1,108 @@
---
title: "Quick Install Guide"
description: "Deploy your own remote Pangolin node in under 10 minutes with our automated installer"
---
## Prerequisites
Before you begin, ensure you have:
- **Pangolin Cloud** account. You can [create a free account here](https://app.pangolin.net/auth/signup) OR a [clustered self-hosted Pangolin Enterprise deployment](/self-host/clustering/understanding-clustering).
- **Linux server** with root access and public IP address.
- **Open ports on firewall** for 80 (TCP), 443 (TCP), 51820 (UDP), and 21820 (UDP for clients).
<Tip>
**Recommended**: Ubuntu 20.04+ or Debian 11+ for best compatibility and performance.
</Tip>
## Choose Your Server
Need help choosing? See our [complete VPS guide](/self-host/choosing-a-vps) for suggestions.
## Networking
Before installing Pangolin, ensure you've opened the required port on your firewall. See our guide on [networking](/self-host/dns-and-networking#port-configuration) for more information.
## Installation Process
<Steps>
<Step title="Download the installer">
Connect to your server via SSH and download the installer:
```bash
curl -fsSL https://static.pangolin.net/get-node-installer.sh | bash
```
The installer supports both AMD64 (x86_64) and ARM64 architectures.
</Step>
<Step title="Run the installer">
Execute the installer with root privileges:
```bash
sudo ./installer
```
The installer places all files in the current directory. Move the installer to your desired installation directory before running it.
<Note>
If you're not using Pangolin Cloud (`app.pangolin.net`) and instead have a self-hosted Pangolin Enterprise deployment, pass its URL with the `--pangolin-endpoint` flag so the installer requests node credentials from your instance instead:
```bash
sudo ./installer --pangolin-endpoint https://pangolin.example.com
```
</Note>
</Step>
<Step title="Do you already have credentials from the dashboard?">
If you are on your game and have already generated credentials for this node in the dashboard enter them here.
<Tip>
If you don't have them yet you can just select no when asked and we will create it in a later step.
</Tip>
</Step>
<Step title="The public addressable IP address for this node">
Enter either the public IP address of your server or a domain name that resolves to it.
<Note>
The installer will attempt resolve and prefill your public IP address. Verify this is correct before preceding.
</Note>
<Warning>
If you choose to use a domain keep in mind this just resolves your node on the internet while the actual subdomains for resources will be managed in the server.
</Warning>
</Step>
<Step title="Generate credentials">
If you did not enter credentials earlier then you should see something like the following:
```
Your managed credentials have been obtained successfully.
ID: he4g78wevj25msf
Secret: n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d
```
Go to the [Pangolin dashboard](https://app.pangolin.net/) (or your own panel's URL if you passed `--pangolin-endpoint`) and log in. Navigate to the "Self-hosted" section and add a new node. Select the adopt method. Use this ID and secret to register your node.
<Tip>
More than one account can use the same node credentials. This is useful for teams.
</Tip>
</Step>
</Steps>
## Post-Installation Setup
Once installation completes successfully, you'll see:
```
Installation complete!
```
Navigate to the [Pangolin dashboard](https://app.pangolin.net/) (or your own dashboard if self-hosted) and create sites, resources, and targets for your remote node.
content/docs/manage/remote-node/understanding-nodes.mdx
+47
View File
@@ -0,0 +1,47 @@
---
title: "Remote Nodes"
description: "Control your own Pangolin node with cloud management"
---
<Note>
Remote nodes are only available in [Pangolin
Cloud](https://app.pangolin.net/auth/signup) and [Enterprise
Edition](/self-host/enterprise-edition).
</Note>
Remote nodes, you run your own Pangolin node - your tunnels, SSL termination, and traffic all stay on your server and use your bandwidth. The difference is that management and monitoring are handled through our cloud. The node just handles terminating Wireguard tunnels, serving HTTP(S) traffic, and routing relayed client connections - it is essentially a remote networking hub.
Think of different nodes as the "front doors" to your applications - users connect to the closest one, and it securely routes their requests to your backend services.
<Tip>
You can deploy a remote Pangolin node [using the installer](/manage/remote-node/quick-install-remote).
</Tip>
## How It Works
- **Host the Node**: Run Gerbil, Traefik, and a light weight agent on your server that communicates with the central Pangolin control plane with a websocket connection.
- **Delegate the DNS**: Your domain and DNS config is still controlled by the Pangolin control plane and the central DNS server routes to the right node when connecting.
- **Certificates and Config**: The control plane pushes down WireGuard configs, SSL certificates, and routing rules to your node as you create resources and sites.
- **Failover**: If you have multiple nodes, the control plane will failover between them. If one node becomes unavailable, traffic can optionally fail over to our cloud infrastructure or other nodes until you restore service.
<Frame>
<img src="/images/ha.png" alt="Diagram of high availability failover across remote nodes" width="400"/>
</Frame>
## Benefits
### Automatic Updates and Less Maintenance
The cloud dashboard evolves quickly, so you get new features and bug fixes without having to manually pull new containers every time. Because the remote node is just handling the networking you do not need to do database migrations, or backups.
### Cloud Failover
If your nodes goes down, your tunnels can temporarily fail over to our cloud points of presence or another node until you bring it back online. This ensures continuous availability.
### High Availability (PoPs)
You can attach multiple nodes to your account for redundancy and better performance. For example, deploy nodes across different regions or providers for decreased latency.
### Better Bandwidth
Since all tunnel traffic flows through your own server, you benefit from your own network's bandwidth capacity. This means you are not constrained by shared cloud infrastructure limits - if your server has high-throughput connectivity, your tunnels will too.
## Restrictions
### AI Gateway Providers
AI Gateway providers are only routed to the Pangolin server nodes. Sites that are connected to remote nodes will not be accessible to be routed to as targets on providers. DNS resolution of gateway resources will not point at remote nodes. Users using gateway resources with custom targets on sites may wish to create a separate org for these resources so sites are able to connect to regular nodes.