# How OpenWAF works

> The path of a request through OpenWAF, from the nameservers to the edge nodes in Germany and Spain and on to your origin.

OpenWAF sits between your visitors and your origin server. DNS sends visitors to the **edge**, the edge inspects each
request, and only allowed requests reach the origin. A separate **control plane** stores your configuration and
publishes it to the edge.

```text
Visitor ──1. DNS query──▶ OpenWAF nameservers (or your DNS + CNAME)
   │                         └─ answer: an edge address
   └──2. HTTPS──▶ Edge node (Germany or Spain) ──3. allowed requests──▶ Your origin
                     ▲
                     └── signed configuration ── Control plane
```

## 1. DNS sends visitors to the edge

When a visitor opens `https://www.example.com`, their resolver asks who answers for the name:

- In a **delegated** zone, OpenWAF's nameservers answer. For a [proxied](https://developers.openwaf.dev/fundamentals/proxied-and-dns-only/) name
  they return the address of an edge node, chosen among the healthy nodes closest to the visitor. DNS-only records are
  answered exactly as you wrote them.
- In an **external** zone, your DNS provider answers with a `CNAME` to `edge.openwaf.dev` (or the edge addresses at the
  root of the domain), which leads to the same edge.

Edge nodes are health-checked continuously: a node that stops answering leaves the DNS answers and visitors move to
the next closest one.

## 2. The edge inspects the request

The edge nodes run in **Germany and Spain**. For each request to a proxied name, the node:

1. Terminates TLS with the site's certificate (Let's Encrypt, issued and renewed automatically), preferring a hybrid
   post-quantum key exchange.
2. Applies the site's protection: [WAF](https://developers.openwaf.dev/waf/) rules, [bot and AI-agent policy](https://developers.openwaf.dev/ai-crawl-control/), the access gate,
   IP and country rules and rate limits ([Rules](https://developers.openwaf.dev/rules/)).
3. Answers from the [cache](https://developers.openwaf.dev/cache/) when the site uses it and the response is cached.
4. Forwards the request to your **origin**: the content of the proxied record. New sites connect over HTTPS and verify
   the origin certificate ([SSL/TLS](https://developers.openwaf.dev/ssl/)).

Blocked requests get a block page and are recorded as security events in [Analytics](https://developers.openwaf.dev/analytics/).

## 3. Configuration reaches the edge signed

Every change you make (DNS records, settings, rules) creates a new [version](https://developers.openwaf.dev/dns/zone-versions/) of the zone. The
control plane turns each version into a configuration document signed with Ed25519; nodes verify the signature before
applying it and reject anything that does not verify. New versions reach all edge nodes in under a minute. The
**Propagation** view of a domain shows which version each node has applied.

If the nodes cannot reach the control plane, they keep serving with the last valid configuration they received.

## Where data lives

| Component | Location |
|---|---|
| Edge nodes (TLS termination, WAF, cache) | Germany and Spain |
| DNS servers | Germany |
| Control plane and customer data | Germany (EU) |

Security events are kept for 30 days. See [Trust and security](https://developers.openwaf.dev/fundamentals/trust-and-security/) and the
[sub-processors](https://openwaf.dev/legal/subprocessors/) list.

## Interfaces

The same configuration can be managed from four places, all with the same validation, versioning and audit:

- [Dashboard](https://dash.openwaf.dev): The web app at dash.openwaf.dev.
- [API](https://developers.openwaf.dev/api/): REST API at https://dash.openwaf.dev/v1 with bearer tokens.
- [CLI](https://developers.openwaf.dev/cli/): `openwaf-cloud ctl`, for scripts and terminals.
- [MCP server](https://developers.openwaf.dev/mcp/): Connect an AI assistant at https://mcp.openwaf.dev/mcp.