> For the complete documentation index, see [llms.txt](https://docs.i3d.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.i3d.net/anti-ddos/warden-capabilities-and-benefits/warden-how-it-works.md). # Warden: How it works This page explains what Warden does once traffic reaches the Warden Service. Before that point, GLAD's network filters have already run on i3D.net's network equipment: the GLAD Advanced ACL filter and, for GLAD Premium clients, the bytematching filter. Warden's job is to manage which IPs are trusted, rate-limit unknown sources, and drop known bad actors. Warden classifies every source IP into one of three states: whitelisted (trusted), blacklisted (blocked), or greylisted (everything else — rate-limited and subject to port checks). Greylisting is not a static list you configure; it is the default state for any IP that is not explicitly white or blacklisted. ## Traffic filtering techniques {% tabs %} {% tab title="Blacklisting" %} Blocks traffic from harmful or suspicious IP addresses or domains. Once blacklisted, their traffic is automatically denied to prevent attacks from known threats. {% endtab %} {% tab title="Greylisting" %} Greylisting is only used as a buffer during the authentication period. Warden allows you to connect, even though you are not whitelisted, requiring extra checks before allowing access. Warden will start limiting traffic in a greylist (and dropped) if you are in the middle of a DDoS attack, where traffic from unauthenticated IP addresses can be dropped as a safety measure. {% hint style="warning" %} **Per-IP enforcement:** The `tcp-gl-pps` and `udp-gl-pps` values you configure on an armor are applied **independently to each individual IP address** within the protected prefix — not shared across the prefix as a whole. For example, a /24 armor (256 IPs) with `udp-gl-pps: 50000` allows up to 50,000 PPS per IP from greylisted sources, not 50,000 PPS total. If your armor covers a subnet, review your greylist PPS values to ensure they reflect the per-IP exposure you intend. {% endhint %} {% endtab %} {% tab title="Whitelisting" %} Creates a list of approved IP addresses or domains allowed to access the network or service. Whitelisted traffic is not rate limited. {% endtab %} {% endtabs %} ## Where Warden fits The diagram below shows how traffic moves through your protection layers before reaching your servers. ![GLAD and Warden protection layers](/files/dyZWCl1qGGX6bfD5nI9U) GLAD's network filters run first. ACL rules run for all GLAD clients (GLAD Advanced), then bytematching runs for GLAD Premium clients. Only traffic that passes both checks reaches the Warden Service. ## How Warden works Warden handles TCP and UDP separately. The list checks (blacklist, whitelist) work the same way for both, but the default behaviour for greylisted traffic when no armor of the matching protocol exists differs between TCP and UDP; see the note at the end of this section. Non-TCP/UDP protocols (ICMP, GRE, SCTP, and others) bypass all Warden checks and pass through directly. See the FAQ below. ![Warden packet decision flow](/files/P4JXhNhgvurSuqm4ZhC6) **TCP** 1. **Blacklist check** — if the IP is on your blacklist, the packet is dropped. 2. **Whitelist check** — if the IP is on your whitelist, the packet is let through. Port and rate checks do not apply. 3. **Port check** — if the IP is on neither list (greylisted) and a TCP armor exists for the destination, Warden checks the destination port. If the port is not allowed, the packet is dropped. 4. **Rate check** — if the port is valid, Warden checks the packet rate. If it is below the configured PPS limit, the packet is let through. If it exceeds the limit, it is dropped. 5. **No TCP armor** — if no TCP armor exists for the destination, greylisted TCP packets are dropped (default-deny). **UDP** 1. **Blacklist check** — if the IP is on your blacklist, the packet is dropped. 2. **Whitelist check** — if the IP is on your whitelist, the packet is let through. Port and rate checks do not apply. 3. **Port check** — if the IP is on neither list (greylisted) and a UDP armor exists for the destination, Warden checks the destination port. If the port is not allowed, the packet is dropped. 4. **Rate check** — if the port is valid, Warden checks the packet rate. If it is below the configured PPS limit, the packet is let through. If it exceeds the limit, it is dropped. 5. **No UDP armor** — if no UDP armor exists for the destination, greylisted UDP packets are **let through unrestricted** (default-allow). This is intentional so that DNS replies and other return UDP traffic keep working when only TCP is being actively protected. {% hint style="warning" %} **TCP and UDP have asymmetric defaults when no matching armor exists.** Greylisted TCP packets without a TCP armor are dropped; greylisted UDP packets without a UDP armor pass through. If you protect TCP only, always also create a companion UDP armor for the same prefix to prevent unrestricted UDP from reaching your server. See the FAQ below for sizing guidance on the companion UDP armor. {% endhint %} ## Expiration precision The `expires` value passed via `POST /lists/{id}` is applied down to the minute. Any seconds component is rounded down — `"2025-08-20T19:04:55Z"` is treated as `"2025-08-20T19:04:00Z"` in the Warden dataplane. ## Warden FAQs #### What are the advantages of NOT using Warden's greylisting features at all, only allowing access from trusted IPs? * **Full service continuity while attacks are ongoing:** New players can continue to connect to the game instance even while the server is under attack. When relying on greylisting, untrusted IPs will experience degraded service or may even have no service at all when the `tcp-gl-pps` or `udp-gl-pps` value is exceeded. * **Reduced operational overhead:** You can skip thinking about how to interact with the blocklisting feature entirely, anything that is not trusted will be automatically dropped. * **Reduced exposure to low-and-slow attacks:** You cannot receive packets from untrustworthy sources, significantly reducing the attack surface of your game and helping to defend against application layer attacks, such as those involving malformed packets. To avoid triggering greylisting, manage your PPS (Packets Per Second) and ensure it remains below the specified threshold. * **Easier troubleshooting:** Debugging is much easier because a connection will either always work completely, or never work at all, there is no intermittency factor. #### How should I size my greylist PPS values? Because greylist PPS is enforced per individual IP (not per prefix), the right value depends on the legitimate volume of new or unauthenticated connections your server handles. A reasonable starting point is **10,000 PPS per IP**, but your ideal value is specific to your workload: * **Baseline from your traffic data**: Review normal inbound PPS from non-whitelisted sources during non-attack periods. Set the greylist limit at or slightly above that baseline to absorb normal load while still capping attack amplification. * **Ask i3D.net support for help**: We can plot your weekly traffic patterns to help you identify a safe threshold. Open a support ticket to request a traffic benchmarking review. * **Consider disabling greylisting entirely** if your integration always whitelists authenticated users before they connect — see the FAQ below for when this is the right choice. #### If that is the case, why would someone ever want to use Warden's greylisting feature? * In some cases it's not possible to integrate with the authentication layer, then the game operator could instead choose to add IPs to the trusted list based on that IP's interactions with the server while in the greylist. * Once your request reaches the GLAD API, updates propagate rapidly through Warden locations worldwide. However, in some cases the user still tries to connect to the game instance before the IP address collected during authentication makes it onto Warden's trusted IPs list - a greylist would allow for the user to still complete their initial connection successfully. #### Does a TCP armor also apply greylist controls to UDP traffic? No. A TCP armor applies `ports` and `tcp-gl-pps` to TCP traffic only — `udp-gl-pps` has no effect in a TCP armor. UDP traffic from non-whitelisted sources passes through unrestricted unless a separate UDP armor exists for the same prefix. This is intentional: without it, a TCP-protected server could not receive DNS responses (which use UDP). To restrict UDP greylist traffic, create a UDP armor for the same prefix. Set `udp-gl-pps: 0` to drop all greylisted UDP (full block), or set a low value (e.g., 1000) to allow a limited amount through — useful when some UDP responses need to reach the server. The same applies in reverse: a UDP armor does not apply greylist controls to TCP traffic. #### Does Warden process non-TCP/UDP protocol traffic (for example ICMP or GRE)? No. Non-TCP/UDP protocols bypass all Warden checks and pass through uninspected. This includes ICMP, GRE, SCTP, and any other protocol. If you need to block or allow that traffic, use your ACL rules — Warden does not act on it. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.i3d.net/anti-ddos/warden-capabilities-and-benefits/warden-how-it-works.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.