Deploy Gateways

Gateways are what Clients connect to in order to access Resources in a Site. They're the data plane workhorse of the Firezone architecture and are responsible for securely routing traffic between Clients and Resources.

Prerequisites

• Any Linux distribution with kernel 3.10 or later
• x86_64, aarch64, or armv7l CPU architecture
• iptables and ip6tables commands available on your system
• Docker Engine or systemd installed for your distribution

Firewall ports

Gateways implement the industry-standard STUN and TURN protocols to perform secure NAT holepunching. This allows Firezone to establish direct connections between your Users and Resources while keeping your Resources invisible to the public internet.

Inbound ports

In most cases, no inbound firewall ports should be opened for Gateways to function properly. If your network has a stateless firewall in place, however, you'll need to ensure UDP return traffic can reach the Gateway(s). If you're not sure, you should err on the side of caution and leave all inbound ports closed unless you experience connectivity issues.

See the table below for firewall recommendations for popular cloud providers.

Outbound ports

If the network in which your Gateway is deployed applies egress filtering, you'll need to make sure the following outbound traffic is allowed:

Permissions

In order to function correctly, Gateways need access to several parts of the Linux system:

1. The TUN device as /dev/net/tun
2. Permissions to open new UDP sockets
3. Permissions to add and remove routes via netlink

Typically, it is enough to run Gateways with the CAP_NET_ADMIN capability. Alternatively, you can run them as root.

Gateways will check on startup for these two conditions and fail if neither are met. You can skip these permission checks by passing --no-check. This is only advisable in case you have configured access in ways not covered by these checks.

Where to deploy Gateways

Ideally, Gateways should be deployed as close to the Resources they're serving -- in some cases, even on the same host. This ensures the lowest possible latency and highest possible throughput for Client connections, and allows you to more easily deploy additional Gateways for other Resources that need to handle more Client connections.

When multiple Gateways are deployed within a Site, Firezone automatically selects the closest Gateway to route Client traffic based on the Client's geolocated IP address. This regional selection helps minimize latency and optimize performance by connecting users to the nearest available Gateway.

The downside of deploying Gateways close to Resources is that it increases the overall number of Gateways and Sites you need to manage. Firezone's control plane is designed to make this as easy as possible, but it's still something to keep in mind when planning your deployment.

Sizing recommendations

The Gateway, like the rest of Firezone's data plane stack, is written in Rust. As a result, it's extremely lightweight and computationally efficient by nature.

Gateways are mostly performance-bound by the I/O rate at which they can process packets, so bare metal deployments or VMs with high I/O rates will make a big difference in both throughput and latency.

The number of clients a Gateway can support depends heavily on your throughput requirements — available bandwidth is shared across all connected clients. A single Gateway on a 2-core dedicated vCPU VM can reliably handle up to 1,000 clients, assuming your link speed is sufficient. Throughput is also affected by latency to/from clients and whether connections are peer-to-peer or relayed (relayed connections carry additional overhead).

Gateways scale with CPU cores up to 4 cores, beyond which additional cores provide no benefit. Up to 4 GB of RAM can be used for packet buffers; more than that is not utilized. For ideal performance, we recommend at least 4 dedicated CPU cores.

A typical Gateway on a 4-core Linux machine with a recent kernel and sub-10ms round-trip latency should be able to push 2 Gbps+ of peer-to-peer WireGuard traffic. While the Gateway runs as a userspace binary, this is often on par with or faster than the kernel WireGuard module due to multithreading and offloading optimizations.

Gateways deployed to the Internet site should always have at least 4 CPU cores.

For production workloads, we recommend deploying at least 3 Gateways to ensure high availability during rolling upgrades and to distribute load across multiple machines. To scale beyond a single Gateway's capacity, deploy additional Gateways and use Firezone's automatic load balancing to shard Client connections across them.

Performance tuning

The default receive and send buffer sizes on Linux are quite small which can limit the maximum throughput that users can achieve.

The Gateway attempts to increase the system-wide UDP send and receive buffer max sizes to 16 and 128 MB respectively. It does that by setting net.core.wmem_max and net.core.rmem_max. This will however only work for Gateways deployed on bare-metal and not via Docker as Docker mounts /proc/sys as a read-only file system.

To disable this behaviour, you can set FIREZONE_NO_INC_BUF=true.

To ensure good throughput, it is advisable to ensure these parameters are set correctly.

sudo sysctl -w net.core.wmem_max=16777216 # 16 MB
sudo sysctl -w net.core.rmem_max=134217728 # 128 MB

Deploy a single Gateway

Deploying a single Gateway can be accomplished in the admin portal.

Go to Sites -> <name of Site> -> Deploy a Gateway and follow the prompts to deploy for your preferred environment. This will deploy a single Gateway.

Deploy multiple Gateways

To achieve high availability, deploy two or more Gateways within the same Site. High availability is achieved through a combination of automatic failover and load balancing, both of which are available on all plans.

You can deploy multiple Gateways within a Site manually from the admin portal, or automate the process by reusing the FIREZONE_TOKEN environment variable shown on the Manual tab of the Deploy a new Gateway page. This is a multi-owner token that can be reused to deploy multiple Gateways within the same Site.

Deploy as many Gateways as you need to handle the load of Client connections to Resources in a Site. This effectively shards Client connections across all Gateways in a Site, achieving higher overall throughput than otherwise possible with a single Gateway.

Automated Gateway deployment

See our automation recipes for deploying Gateways on various cloud providers using Terraform.

Keeping Gateways up to date

It's a good idea to keep your Gateways up to date with the latest version available. See upgrading Gateways for ways to automate this.

Telemetry

By default, Gateways will run a https://sentry.io crash-reporting agent. If you'd like to opt-out of this, set the environment variable FIREZONE_NO_TELEMETRY=true.

Environment variable reference