Bans

Block clients by IP address or CIDR for a limited time. Bans travel over the node channel directly, take effect within seconds and create no configuration revision.

ConceptsCopy Anchor Link

Ban an addressCopy Anchor Link

1. Open Bans and click "New ban".

2. Pick the "Scope": "Site" or "Global".

3. For a site ban, pick the site under "Site"; with many sites, type a name or domain into "Search sites" first.

4. Fill in "IP or CIDR", e.g. 203.0.113.7 or 198.51.100.0/24.

5. Pick a "Reason" and a "Duration" (1 h, 6 h, 1 d, 3 d, 7 d) and click "Ban".

6. Verify: request the site from the banned address:

   Copy Text

   curl -sI -H 'Host: www.example.com' http://<node IP>/

   The response is 403 with X-Edgeweir-Error: ip-banned. With a site ban, other sites still answer the same address.

Unban: click "Unban" in the row and confirm. The nodes drop the ban within seconds. Manual and automatic bans can both be lifted.

Without typing it again: the access logs, the top IPs of the analytics, and the top addresses and automatic bans on a site's Security tab offer "Ban IP" under ⋯ at the end of the row, with the site and address filled in (the "Scope" can change to "Global"); ⌘K / Ctrl+K → "Ban an IP…" opens the same dialog (with the site filled in on a site's pages). The toast after a ban links to the list ("View bans"). The link /bans?site=<site ID>&ip=<address> opens the dialog filled in the same way, and the list shows only the bans that overlap that address (× beside the address clears it).

The list shows active bans only (neither expired nor lifted), newest first, and filters by scope, site and source:

RulesCopy Anchor Link

LimitsCopy Anchor Link

Automatic bans do not count toward the limit of manual bans. Once the limit is reached, a new ban gets BAN_PLATFORM_LIMIT ("At most N manual bans can be active"); banning an address that is still banned is not limited.

Automatic bansCopy Anchor Link

A node bans on its own on a trigger (the per-IP QPS of CC mitigation, see Challenges and CC mitigation): a single IPv4 address, or the IPv6 /64 (one client usually holds a whole /64); loopback addresses are never banned. The ban applies on that node at once and is reported to the console in batches every 5 seconds.

NodesCopy Anchor Link

Kernel bansCopy Anchor Link

The node agent also writes global bans into nftables, which drops the banned addresses' packets in the kernel: a banned client cannot even complete the TCP and TLS handshakes. Site bans apply at the HTTP layer only. L4 apps are subject to kernel bans only: site bans and HTTP-layer bans do not reach layer-4 traffic.

The default systemd unit and node image do not grant CAP_NET_ADMIN. Enable it as follows when needed.

systemd nodesCopy Anchor Link

1. Install nftables:

   Copy Text

   sudo apt-get install -y nftables    # Debian, Ubuntu
   sudo dnf install -y nftables        # RHEL family

2. Add a drop-in that grants CAP_NET_ADMIN next to the existing CAP_NET_BIND_SERVICE:

   Copy Text

   [Service]
   AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_NET_ADMIN
   CapabilityBoundingSet=CAP_NET_BIND_SERVICE CAP_NET_ADMIN

3. Reload and restart:

   Copy Text

   sudo systemctl daemon-reload
   sudo systemctl restart edgeweir-node

4. Verify: sudo nft list table inet edgeweir lists the sets ban4 and ban6; supportedFeatures of GET /api/v1/nodes/{id} contains kernel-ban-v1.

Container nodesCopy Anchor Link

1. Build the node image with the build argument NFT_CAPABILITY=true. The image gives nft a file capability; the agent still runs as a non-root user:

   Copy Text

   docker build --build-arg NFT_CAPABILITY=true -t edgeweir-node:nft .

2. Run the container with --cap-add NET_ADMIN (Compose: cap_add: [NET_ADMIN]).

3. Verify: docker exec <container> nft list table inet edgeweir lists the sets ban4 and ban6; supportedFeatures of GET /api/v1/nodes/{id} contains kernel-ban-v1.

Load balancers in front of the nodesCopy Anchor Link

The cluster's client IP setting decides the visitor address (ip.src) of the HTTP and HTTPS listeners:

With the last two, the Bans page shows "Clusters {clusters} take client addresses from proxies: kernel bans match the TCP peer only". In direct mode behind a load balancer, add the balancers' addresses to an allow list: they can then never be banned or dropped in the kernel.

L4 apps accept the PROXY protocol on their own listeners, independently of the client IP setting of the HTTP and HTTPS listeners.

APICopy Anchor Link

Paths are under /api/v1.

Read-only AccessKeys can call only bans.list; service accounts cannot call the ban procedures (403 SERVICE_ACCOUNT_FORBIDDEN). Fields and examples: API and endpoints.

TroubleshootingCopy Anchor Link