diff --git a/docs.json b/docs.json
index 4105798..340e8eb 100644
--- a/docs.json
+++ b/docs.json
@@ -317,6 +317,7 @@
"group": "Advanced Configuration",
"pages": [
"self-host/advanced/config-file",
+ "self-host/advanced/increasing-subnet-capacity",
"self-host/advanced/private-config-file",
"self-host/advanced/wild-card-domains",
"self-host/advanced/cloudflare-proxy",
diff --git a/manage/sites/install-newt.mdx b/manage/sites/install-newt.mdx
index 85874cf..f17c0f2 100644
--- a/manage/sites/install-newt.mdx
+++ b/manage/sites/install-newt.mdx
@@ -158,8 +158,7 @@ A safer but slightly more complex way is to use [Compose Secrets](https://docs.d
{
"id": "2ix2t8xk22ubpfy",
"secret": "nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2",
- "endpoint": "https://app.pangolin.net",
- "tlsClientCert": ""
+ "endpoint": "https://app.pangolin.net"
}
```
diff --git a/manage/sites/install-site.mdx b/manage/sites/install-site.mdx
index b1f8e6f..c8a4ecf 100644
--- a/manage/sites/install-site.mdx
+++ b/manage/sites/install-site.mdx
@@ -159,7 +159,7 @@ A safer but slightly more complex way is to use [Compose Secrets](https://docs.d
{
"id": "2ix2t8xk22ubpfy",
"secret": "nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2",
- "endpoint": "https://app.pangolin.net",
+ "endpoint": "https://app.pangolin.net"
}
```
@@ -171,6 +171,9 @@ services:
image: fosrl/pangolin-cli
container_name: pangolin-site
restart: unless-stopped
+ command:
+ - up
+ - site
environment:
- CONFIG_FILE=/run/secrets/pangolin-site-config
secrets:
diff --git a/self-host/advanced/increasing-subnet-capacity.mdx b/self-host/advanced/increasing-subnet-capacity.mdx
new file mode 100644
index 0000000..ef67103
--- /dev/null
+++ b/self-host/advanced/increasing-subnet-capacity.mdx
@@ -0,0 +1,85 @@
+---
+title: "Increasing Site and Client Capacity"
+description: "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"
+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**.
+
+
+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:
+
+```yaml title="config.yml"
+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
+```
+
+
+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.
+
+
+
+
+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).
+
+
+
+Use `pangctl` to remove existing exit node records so they get re-created using the new ranges:
+
+```bash
+docker exec -it pangolin pangctl clear-exit-nodes
+```
+
+See [Clear Exit Nodes](/self-host/advanced/container-cli-tool#clear-exit-nodes) for details.
+
+
+
+Restart every container in your Pangolin stack (Pangolin, Gerbil, Traefik, etc.) so the exit node re-registers with the new subnet settings.
+
+
+
+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.
+