Subnet Router

A subnet router lets devices that can't run the Pangolin client access Pangolin resources. It sits between the Pangolin network and a physical subnet, so legacy devices, whole networks, or services still have access without installing Pangolin on each one.

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 limit. Even so, a direct install remains the better option for performance, security, and simpler configuration.

BenefitsCopy Anchor Link

• 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 casesCopy Anchor Link

• 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 workCopy Anchor Link

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.

Set up a subnet routerCopy Anchor Link

Deploy the siteCopy Anchor Link

You need a site in the dashboard, running on the remote network. See Install Sites.

Create resourcesCopy Anchor Link

Create CIDR resources, or 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 CLICopy Anchor Link

The host must run Linux. Install the CLI with:

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 Pangolin CLI for other install options.

{
    "ip-forward-no-drop": true
}

Log in or create a machine clientCopy Anchor Link

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 Machine Client 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 routerCopy Anchor Link

Start the client with the --subnet-router flag. It needs the CAP_NET_ADMIN capability, so run it as root:

sudo pangolin up client \
--id {client_id} \
--secret {client_secret} \
--endpoint {endpoint_url} \
--subnet-router \
--attach

--attach keeps the client in the foreground. To keep it running across reboots, install it as a service instead. See Run as a Service.

Check the firewall and NAT rulesCopy Anchor Link

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:

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 networkCopy Anchor Link

If the Pangolin client is not running on the network's gateway/router then you will need to teach the network where to find these specific resource routes.

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:

On a Linux gateway, that route looks like this:

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.

LoggingCopy Anchor Link

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.