From 2ec903f443846dceae7c05f8568c5f7a49e79d4f Mon Sep 17 00:00:00 2001 From: Owen Date: Tue, 29 Sep 2026 17:22:30 -0400 Subject: [PATCH] First pass on subnet router and exit node docs --- app/global.css | 14 +++ content/docs/development/contributing.mdx | 2 +- content/docs/manage/clients/subnet-router.mdx | 90 +++++++++++++++++++ .../manage/resources/private/exit-node.mdx | 75 ++++++++++++++++ lib/navigation.json | 2 + 5 files changed, 182 insertions(+), 1 deletion(-) create mode 100644 content/docs/manage/clients/subnet-router.mdx create mode 100644 content/docs/manage/resources/private/exit-node.mdx diff --git a/app/global.css b/app/global.css index c937929..36e6504 100644 --- a/app/global.css +++ b/app/global.css @@ -559,6 +559,20 @@ figure.shiki .line.highlighted { margin-bottom: 0; } +/* The callout sits inside .not-prose, which disables typography's link/bold styles. */ +.pg-callout-body a { + color: var(--color-fd-primary); + font-weight: 500; + text-decoration: underline; + text-underline-offset: 2px; +} +.pg-callout-body a:hover { + opacity: 0.8; +} +.pg-callout-body strong { + font-weight: 600; +} + /* ---------- cards ---------- */ .pg-card-group { display: grid; diff --git a/content/docs/development/contributing.mdx b/content/docs/development/contributing.mdx index af7e582..5a710bf 100644 --- a/content/docs/development/contributing.mdx +++ b/content/docs/development/contributing.mdx @@ -195,7 +195,7 @@ Then choose your database: -## Exit Nodes +## Gerbil Registration When running Pangolin for the first time there will be no exit nodes. This means that there have been no Gerbil "exit nodes" registered in the database, and therefore, you cannot create Newt sites. When Gerbil first starts up and requests its config from Pangolin for the first time it gets registered as an exit node. diff --git a/content/docs/manage/clients/subnet-router.mdx b/content/docs/manage/clients/subnet-router.mdx new file mode 100644 index 0000000..f841312 --- /dev/null +++ b/content/docs/manage/clients/subnet-router.mdx @@ -0,0 +1,90 @@ +--- +title: "Subnet Router" +description: "" +--- + +A subnet router lets devices that can't run the Pangolin client join your Pangolin network. It sits between the Pangolin network and a physical subnet, so you can reach legacy devices, whole networks, or services without installing Pangolin on each one. + + + Subnet routing currently only works on Linux with the [Pangolin + CLI](/manage/clients/install-client#pangolin-cli-linux-macos-windows). + + +Installing the Pangolin client on a device gives you end-to-end encryption and the best performance, so do that whenever you can. Often you can't. Printers usually can't run the client, and in a large AWS VPC or a legacy network that is being modernized step by step, touching every endpoint isn't realistic. + +In those cases a subnet router relays traffic between your Pangolin network and the regular subnet. It enforces your access control policies on that traffic, so non-Pangolin devices get connectivity without a gap in security. + +Devices behind a subnet router don't count toward your plan's client limit. Even so, a direct install remains the better option for performance, security, and simpler configuration. + +## Benefits + +- Connect legacy devices that can't run the Pangolin client. +- Bring in entire networks, such as AWS VPCs, without installing Pangolin on each device. +- Adopt Pangolin gradually by connecting existing network segments through subnet routers. +- Keep access control in place, since subnet routers follow Pangolin's access control policies. + +## Use cases + +- Reach managed services such as Amazon RDS or Google Cloud SQL without exposing them to the public internet. +- Connect cloud VPCs or other cloud network segments to your Pangolin network. +- Let remote Pangolin users reach devices like printers or cameras that can't run the client. + +## How subnet routers work + +A subnet router links separate network environments under one access model. It works at the network layer to pass traffic between your Pangolin network and traditional subnet-based networks. + +In Pangolin, a subnet router is a client in your Pangolin network that acts as a gateway and advertises routes to a subnet. Other devices in that subnet can then connect to your Pangolin network without running the Pangolin client. + +A device that uses the subnet router as its gateway is said to be behind it. By default, subnet routers apply Source Network Address Translation (SNAT), so traffic from a device behind the router appears to come from the router rather than from the device. + + +Subnet routers and exit nodes both route traffic, but they do different jobs. An exit node sends outbound internet traffic from your Pangolin clients through itself, like a VPN server. Your traffic appears to originate from the exit node's location, which helps with geo-restricted content or privacy. A subnet router gives access to specific private subnets. Pangolin clients can reach Pangolin resources in those subnets, and internet routing is unchanged. For private networks such as office LANs or cloud VPCs, use a subnet router. + + +## Set up a subnet router + +How to set it up + +### Prereq: Install the site + +Make sure you have a site created in the dashboard and deployed on the remote network. See [2] + +### Create resources + +Create CIDR resources or host resources with a IP destination. It is important to use a IP or CIDR here so that other devices on the subnet router network are able to setup routes to address the subnet router. + +### Install the Pangolin CLI + +The host must run Linux. When you run the CLI with `--subnet-router`, it enables forwarding and manages the nftables backend for you. + + + +By default Docker adds its own forwarding rules to iptables, which can interfere with subnet routing if Docker is on the host. Let forwarded traffic through Docker's chain by setting this in `/etc/docker/daemon.json`: + +```json title="/etc/docker/daemon.json" +{ + "ip-forward-no-drop": true +} +``` + +Restart Docker after changing this file. For background on running Docker on a router, see Docker's [packet filtering and firewalls guide](https://docs.docker.com/engine/network/packet-filtering-firewalls/#docker-on-a-router). + + + +### Login or create a machine client + +### Connect the client as a subnet router + +### Setup routing on the network + +You will need to configure the routes on the default gateway of your network to send the desired resource CIDRs to the device running the Pangolin client. For example + + + +## Logging + +All subnet traffic will show up in the network connection logs but will originate from the source of the Pangolin client because of the SNAT. + + +Network connection logs are availble on Enterprise Edition and Pangolin Cloud. + \ No newline at end of file diff --git a/content/docs/manage/resources/private/exit-node.mdx b/content/docs/manage/resources/private/exit-node.mdx new file mode 100644 index 0000000..22aa853 --- /dev/null +++ b/content/docs/manage/resources/private/exit-node.mdx @@ -0,0 +1,75 @@ +--- +title: "Exit Node (route all traffic)" +description: "Create private exit node resources to act as full" +--- + +Pangolin works as a split tunnel VPN by default. It carries traffic between sites and clients and leaves your public internet traffic alone, for example when you visit Google or Wikipedia. This suits most people, who want secure communication between sensitive devices such as company servers or home computers, without the extra encryption and latency on their regular internet connection. + +Sometimes you do want Pangolin to carry your public internet traffic, for instance when: + +- You're on untrusted coffee shop Wi-Fi. +- You're abroad and need an online service, such as banking, that only works from your home country. + +To do this, make a site an exit node and point other devices at it using an exit node resource. Routing everything through an exit node uses the default routes (0.0.0.0/0, ::/0), the same way a typical VPN does. + + + Exit nodes and subnet routers both route traffic, but they do different + jobs. An exit node sends outbound internet traffic from your Pangolin + clients through sites, like a VPN server. Your traffic appears to originate + from the exit node's location, which helps with geo-restricted content or + privacy. A subnet router gives access to specific private subnets. Pangolin + clients can reach Pangolin resources in those subnets, and internet routing + is unchanged. For private networks such as office LANs or cloud VPCs, use a + subnet router. + + +## Benefits + +- All traffic is secured, including traffic to internet sites and applications. +- You can deploy exit nodes around the world to fit your scale and location needs. +- Network connection logging shows traffic across the Pangolin network and supports analysis after a security incident. + +## Use cases + +- Traveling staff have all their internet traffic secured, whatever network they're on. +- You can test applications from different locations by deploying exit nodes in several regions and choosing between them. +- If regulations or compliance rules require your workforce to use a VPN, exit nodes can meet that requirement. + +## How it works + +With the exit node feature, you send all traffic through one or more sites on your Pangolin network. That device is the exit node. You can use exit nodes in several ways: + +- Route all non-Pangolin traffic through an exit node. +- Use multiple exit nodes on the resource and clients will pick the best one automatically based on latency. + +Exit nodes are opt-in for security reasons. Every client must explicitly opt in to using an exit node by choosing the resource they want. + +## Set up a exit node + +### Deploy the site + +### Create the exit node resource + +### Select the node in your client + +Each device enables the exit node on its own, and the steps depend on the device's operating system. + +1. Open the Pangolin app on the Android device and go to the Exit Node section. +2. Select the exit node you want. To keep direct access to your local network while routing through an exit node, turn on Allow LAN access. +3. Check that the home screen shows the selected device in the Exit Node section. The section turns blue while an exit node is in use. +4. To stop using an exit node, go to the Exit Node section and select None. + +The exit node option only appears when your Pangolin network has an exit node available. + +To confirm routing works, look up your public IP address with an online tool. It should show the exit node's public address instead of your local device's. + +To turn routing off, select None in the Exit Node drop-down. + +## Logging + +All exit node traffic appears in the network connection logs. + + + Network connection logs are available on Enterprise Edition and Pangolin + Cloud. + diff --git a/lib/navigation.json b/lib/navigation.json index ac53b5f..74b645c 100644 --- a/lib/navigation.json +++ b/lib/navigation.json @@ -63,6 +63,7 @@ "pages": [ "manage/resources/private/host", "manage/resources/private/cidr", + "manage/resources/private/exit-node", "manage/resources/private/private-http", "manage/resources/private/ai-gateway", "manage/resources/private/ssh", @@ -85,6 +86,7 @@ "manage/clients/configure-client", "manage/clients/client-logs", "manage/clients/update-client", + "manage/clients/subnet-router", "manage/clients/credentials", "manage/clients/fingerprinting", "manage/clients/archiving-blocking",