> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Increasing Site and Client Capacity

> Understand the Gerbil subnet hierarchy and how to raise the number of sites and clients an exit node can serve

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`](/self-host/advanced/config-file#gerbil-tunnel-controller) 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:

```yaml title="config.yml" theme={"theme":"gruvbox-light-hard"}
gerbil:
    subnet_group: "100.89.137.0/20" # 4,096 addresses total
    block_size: 24 # 256 addresses per exit node
    site_block_size: 32 # 1 address per site/client 
```

* 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**.

<Note>
  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`.
</Note>

## 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:

```yaml title="config.yml" theme={"theme":"gruvbox-light-hard"}
gerbil:
    subnet_group: "100.64.0.0/16" # widened to fit more /22 blocks
    block_size: 22 # 1,024 addresses per exit node (256 sites/clients * 4)
    site_block_size: 32 # unchanged - 1 address per site/client
```

<Tip>
  Pick CGNAT range addresses (`100.64.0.0/10`) for `subnet_group` to avoid conflicting with typical private networks, the same as the default.
</Tip>

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.

<Steps>
  <Step title="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).
  </Step>

  <Step title="Clear exit nodes from the database">
    Use `pangctl` to remove existing exit node records so they get re-created using the new ranges:

    ```bash theme={"theme":"gruvbox-light-hard"}
    docker exec -it pangolin pangctl clear-exit-nodes
    ```

    See [Clear Exit Nodes](/self-host/advanced/container-cli-tool#clear-exit-nodes) for details.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>