Working on exit nodes and subnet router

2026-10-01 10:19:23 +02:00 · 2026-09-29 17:35:40 -04:00
parent 5552bbeb80
commit e6621642d9
2 changed files with 76 additions and 17 deletions
@@ -43,19 +43,23 @@ Subnet routers and exit nodes both route traffic, but they do different jobs. An

 ## Set up a subnet router

-How to set it up
+### Deploy the site

-### Prereq: Install the site
-
-Make sure you have a site created in the dashboard and deployed on the remote network. See [2]
+You need a site in the dashboard, running on the remote network. See [Install Sites](/manage/sites/install-site).

 ### 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. 
+Create [CIDR](/manage/resources/private/cidr) resources, or [host](/manage/resources/private/host) resources with an IP destination. The destination must be an IP or CIDR so that other devices on the subnet router's network can set up routes that point at the router. Give the machine client from the next steps access to these resources.

 ### 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.
+The host must run Linux. Install the CLI with:
+
+```bash
+curl -fsSL https://static.pangolin.net/get-cli.sh | bash
+```
+
+When you run the CLI with `--subnet-router`, it enables forwarding and manages the nftables backend for you. See [Install Clients](/manage/clients/install-client#pangolin-cli-linux-macos-windows) for other install options.

 <Warning>

@@ -71,15 +75,54 @@ Restart Docker after changing this file. For background on running Docker on a r

 </Warning>

-### Login or create a machine client
+### Log in or create a machine client
+
+A machine client is the usual choice for a router, since it isn't tied to a user account. In the dashboard, go to Clients > Machines and create one. Copy its ID, secret, and endpoint. See [Credentials](/manage/clients/credentials).
+
+You can also log in as a user with `pangolin login` and run `pangolin up`, but a machine client is better suited to a long-running service.

 ### Connect the client as a subnet router

-### Setup routing on the network
+Start the client with the `--subnet-router` flag. It needs the CAP_NET_ADMIN capability, so run it as root:

-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
+```bash
+sudo pangolin up client \
+--id {client_id} \
+--secret {client_secret} \
+--endpoint {endpoint_url} \
+--subnet-router \
+--attach
+```

-<write an example table showing a route pointing to a host for a 192.168.18.1/24 network>
+`--attach` keeps the client in the foreground. To keep it running across reboots, install it as a service instead. See [Run as a Service](/manage/clients/install-client#run-as-a-service).
+
+### Check the firewall and NAT rules
+
+Make sure no firewall rules on the host or the network block traffic from the resource ranges going up the tunnel. Connections from the LAN to those ranges must be able to reach the Pangolin client and leave through its tunnel interface.
+
+When the client starts with `--subnet-router`, it enables IPv4 forwarding on the host and adds NAT rules for traffic leaving through the tunnel. It also accepts forwarded traffic to and from the tunnel interface, so a default-deny forward policy elsewhere on the host doesn't drop it. To see the rules, run:
+
+```bash
+sudo nft list table ip olm_subnet_router
+```
+
+The client removes the rules when it disconnects, and turns forwarding back off only if it was the one that enabled it.
+
+### Set up routing on the network
+
+On the default gateway of the network, add a route that sends the resource CIDRs to the device running the Pangolin client. For example, with a LAN of 192.168.18.0/24, the client running on 192.168.18.10, and a resource CIDR of 10.1.0.0/16:
+
+| Where | Destination | Next hop |
+|-------|-------------|----------|
+| Default gateway of 192.168.18.0/24 | 10.1.0.0/16 | 192.168.18.10 |
+
+On a Linux gateway, that route looks like this:
+
+```bash
+sudo ip route add 10.1.0.0/16 via 192.168.18.10
+```
+
+Devices on the LAN can now reach the resource through the subnet router without running the Pangolin client.

 ## Logging

@@ -48,23 +48,39 @@ Exit nodes are opt-in for security reasons. Every client must explicitly opt in

 ### Deploy the site

+Create a site in the dashboard and run it on the network you want your traffic to leave from. Traffic exits from that site's internet connection. See [Install Sites](/manage/sites/install-site). For redundancy or lower latency, deploy more than one site.
+
 ### Create the exit node resource

+1. Create a new private resource and set the mode to Exit Node.
+2. Select the sites to use as exit nodes. With several sites, clients pick the best one by latency.
+3. Choose the roles, users, and machine clients that can use the exit node.
+
+An exit node has no destination, since it always routes 0.0.0.0/0. All TCP and UDP ports and ICMP are allowed.
+
 ### 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.
+Each device enables the exit node on its own, and the steps depend on the client.

-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.
+#### MacOS, Windows, iOS, Android
+
+1. Open the Pangolin app and go to the exit node section.
+2. Select the exit node you want. 
+3. Check that the status shows active in the exit node section and when clicking on the sites they are marked for exit node 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.
+#### CLI
+
+Run this command and pick an exit node from the list:
+
+```bash
+pangolin select exit-node
+```
+
+If the client is running, the change applies immediately. If not, the choice is saved and applied on the next `pangolin up`. To turn it off, run the command again and choose None. To select an exit node without the prompt, pass its nice ID with `--exit-node`.

 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.