Set up a site-to-site tunnel

In this guide, we'll connect two Sites so that any host in one can reach any host in the other. The hosts themselves don't run Firezone. Instead, two machines in each Site carry the traffic for everyone else.

Connections in Firezone are directional. A Client connects to a Gateway, never the other way around. So each Site needs two machines:

• A headless Client that the other hosts use as their route to the remote Site. It sends their traffic into the tunnel.
• A Gateway that receives traffic from the remote Site and delivers it to hosts in its own Site.

This guide uses these example Sites. Replace the addresses with your own.

Prerequisites

• Two Linux machines or VMs in each Site, one for the headless Client and one for the Gateway.
• The two subnets must not overlap.
• Access to change routes for the other hosts in each Site, either on each host or on the Site's router.

Step 1: Create the Sites and deploy their Gateways

1. In your admin portal, open Sites and click New Site. Name it Site A.
2. In the new Site, click Deploy a gateway and follow the instructions to install it on the Gateway machine in Site A, 10.10.10.3.
3. Repeat for Site B, with its Gateway on 192.168.10.3.

See Deploy Gateways for each install method.

Step 2: Add a Resource for each subnet

1. Open Resources and click New Resource.
2. Select CIDR as the type and enter 10.10.10.0/24 as the address.
3. Name it Site A subnet and choose Site A as its Site.
4. Click Create Resource.
5. Repeat for Site B subnet, 192.168.10.0/24, in Site B.

Step 3: Create a Group and service account for each direction

Each headless Client should only reach the other Site. If a Client is also given its own subnet, it routes that subnet into the tunnel and loses its connection to its own LAN. So each direction gets its own Group and service account.

1. Open Groups and click New Group. Name it Site A to Site B.
2. Create a second Group named Site B to Site A.
3. Open Service Accounts and click New Service Account.
4. Name it Site A Client, set a token expiration, and add it to the Site A to Site B Group.
5. Click Create Service Account, then copy the token. It's only shown once.
6. Repeat for a service account named Site B Client in the Site B to Site A Group.

You now have one token for each headless Client. To rotate a token later, open the service account and click Add Token.

Step 4: Create the Policies

1. Open Policies and click New Policy.
2. Select the Site A to Site B Group and the Site B subnet Resource, then save.
3. Create a second Policy for the Site B to Site A Group and the Site A subnet Resource.

Optionally, limit what can cross between the Sites. Add traffic restrictions to a Resource to allow only certain ports and protocols, or add conditions to a Policy.

Step 5: Start a headless Client in each Site

On the headless Client machine in Site A, 10.10.10.2, download the headless Linux Client:

curl -fsSL -o firezone-client \
  https://www.firezone.dev/dl/firezone-client-headless-linux/latest/x86_64
chmod +x firezone-client

Save the Site A Client token to the Client's token file. The Client only reads the file if it's owned by root and readable by no one else, and keeping the token in a file keeps it out of your shell history and environment:

sudo install -d -m 755 /etc/dev.firezone.client
sudo install -m 600 /dev/null /etc/dev.firezone.client/token
sudoedit /etc/dev.firezone.client/token

Paste the token, save, and start the Client:

sudo FIREZONE_NAME="Site A Client" ./firezone-client

Do the same on 192.168.10.2 with the Site B Client token. To keep the Client running across reboots, run it as a service. See the headless Linux Client reference.

There's no need to install Firezone on any other host in either Site.

Step 6: Turn on forwarding on the headless Clients

The headless Client machine forwards traffic for the other hosts, so turn on IP forwarding. Run this on both 10.10.10.2 and 192.168.10.2:

sudo tee /etc/sysctl.d/99-firezone-site-to-site.conf <<EOF
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1
EOF
sudo sysctl --system

Then let traffic flow in and out of the tunnel, and masquerade it behind the Client's tunnel address. The Client only sends traffic from that address, so without this rule it drops traffic from every other host:

sudo iptables -A FORWARD -i tun-firezone -j ACCEPT
sudo iptables -A FORWARD -o tun-firezone -j ACCEPT
sudo iptables -t nat -A POSTROUTING -o tun-firezone -j MASQUERADE

The Gateway install already turns on forwarding. If you installed the Gateway manually, check that the forwarding settings in the standalone guide are applied.

Step 7: Clamp the TCP MSS on every Client and Gateway

The tun-firezone interface has an MTU of 1280 bytes, smaller than most LANs. Clamp the TCP maximum segment size to it so large transfers don't stall. Run this on both headless Clients and both Gateways:

sudo iptables -t mangle -A FORWARD -o tun-firezone -p tcp \
  --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu

Step 8: Route each Site to its headless Client

Point the other hosts in each Site at their headless Client for the remote subnet. The easiest place is the Site's router, as a static route. You can also add the route on each host.

On hosts in Site A, route Site B through 10.10.10.2:

sudo ip route add 192.168.10.0/24 via 10.10.10.2

On hosts in Site B, route Site A through 192.168.10.2:

sudo ip route add 10.10.10.0/24 via 192.168.10.2

Step 9: Test the connection

From a host in Site A, ping a host in Site B:

ping 192.168.10.20

Then try the other direction from a host in Site B:

ping 10.10.10.20

Hosts in Site B see traffic from Site A as coming from the Site B Gateway, and the same is true in reverse. Allow the Gateway's address in any host firewalls.

Step 10: Done!

The two Sites can now reach each other through Firezone, with no software on the hosts and no inbound ports open in either Site.

Troubleshooting

The headless Client machine can reach the other Site, but other hosts can't. Check that IP forwarding is on and that the FORWARD and MASQUERADE rules from Step 6 are in place. Then check that the host's route for the remote subnet points at the headless Client.

The headless Client machine loses access to its own Site. Its Group has access to its own subnet. Check that each Group's Policy grants only the other Site's Resource.

Ping works but large transfers or web pages hang. The MSS clamp from Step 7 is missing on one of the four machines.

The Client exits with a token permission error. The token file must be owned by root with mode 600 or 400. Rerun the install commands in Step 5.

Nothing gets through. Check that both Gateways show as online under Sites, and that both headless Clients appear under their service accounts.

Need help? See all support options.