Skip to main content
Every Gerbil exit node hands out its own persistent WireGuard subnet, and every site or client that connects to that exit node gets its own smaller subnet carved out of it. By default this hierarchy only leaves room for a limited number of sites and clients per exit node. If you’re running a large deployment and are hitting that ceiling, you can raise it by changing three related settings in config.yml.

​
How the subnet hierarchy works

There are three gerbil settings that work together, each nested inside the one before it:
  1. subnet_group - The overall CIDR range that exit node subnets are carved from. This is the outermost container.
  2. block_size - The size of the subnet an exit node reserves for itself out of subnet_group when it registers. This is the persistent subnet for that exit node.
  3. site_block_size - The size of the subnet each site or client reserves for itself out of its exit node’s block_size block when it connects.
In other words: subnet_group must be large enough to contain many block_size blocks (one per exit node), and each block_size block must be large enough to contain many site_block_size blocks (one per site or client). With the defaults, this looks like:
config.yml
  • A /20 subnet_group holds 16 non-overlapping /24 blocks, so it can support up to 16 exit nodes.
  • A /24 block_size holds 64 non-overlapping /30 blocks, so each exit node can support up to 64 sites and clients.
Smaller numbers after the slash mean more addresses (a /22 is bigger than a /24). Increasing a block size means moving to a smaller number, and it always shrinks how many of the next-larger container it can fit into - which is why growing block_size usually means you also need to grow subnet_group.

​
Increasing the number of sites and clients per exit node

If your exit nodes are running out of room for sites and clients, increase block_size so each exit node reserves a bigger subnet. Because a bigger block_size block takes up more of subnet_group, you should also grow subnet_group at the same time so it can still fit as many exit nodes as you need. For example, to go from 64 sites/clients per exit node to 1,024, and keep room for 16 exit nodes:
config.yml
Pick CGNAT range addresses (100.64.0.0/10) for subnet_group to avoid conflicting with typical private networks, the same as the default.
You can also raise site_block_size (e.g. from /30 to /29 or /28) if individual sites need more addresses for heavy WireGuard usage, but doing so reduces how many sites/clients fit in each exit node’s block, so weigh that trade-off against your capacity needs.

​
Applying the change

Changing any of subnet_group, block_size, or site_block_size changes the addressing scheme for every exit node, site, and client, so existing exit node records need to be cleared out and re-created against the new ranges.
1

Update config.yml

Edit the gerbil.subnet_group, gerbil.block_size, and/or gerbil.site_block_size values on every node in your deployment (they must match everywhere).
2

Clear exit nodes from the database

Use pangctl to remove existing exit node records so they get re-created using the new ranges:
See Clear Exit Nodes for details.
3

Restart the full stack

Restart every container in your Pangolin stack (Pangolin, Gerbil, Traefik, etc.) so the exit node re-registers with the new subnet settings.
4

Restart sites and clients

Existing Newt sites and Olm clients may need to be restarted to pick up new addresses from their exit node and reconnect.
Clearing exit nodes and changing the subnet hierarchy re-addresses every site and client connected through them. Plan for a maintenance window, since sites and clients will disconnect until they reconnect with their new address.