Webhook-triggered dynamic blocks
guide merged into dnsdist docs

Back to Blog

What We Contributed

dnsdist is the high-performance DNS load balancer from the PowerDNS project. It includes a dynamic blocking system that can drop or rate-limit traffic from abusive sources in real time. The existing documentation covered the built-in rate-based detection (queries per second thresholds, response ratios, etc.) but did not show how to trigger dynamic blocks from an external system.

We submitted a pull request adding a new section to the dynamic blocks guide that fills this gap. It was reviewed and merged on July 2, 2026. The addition provides working Lua handlers that accept blocks and unblocks via HTTP POST, with curl examples and production security notes.

How It Works

dnsdist exposes a built-in web server and supports custom HTTP handlers via registerWebHandler in its Lua configuration. The contributed guide shows how to register two endpoints:

• POST /api/v1/dynblock - Block a CIDR for a specified duration
• POST /api/v1/dynunblock - Remove an active block

Each endpoint accepts a JSON body with the CIDR to block, the duration in seconds, and an optional reason string. The handler calls addDynBlocks internally, which is the same mechanism that dnsdist's built-in rate detection uses. This means externally triggered blocks appear in the same dynamic block table and expire the same way.

A blocking example:

curl -X POST https://dnsdist.example.com/api/v1/dynblock \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "cidr": "192.0.2.0/24",
    "duration": 3600,
    "reason": "DNS amplification source"
  }'

And unblocking:

curl -X POST https://dnsdist.example.com/api/v1/dynunblock \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "cidr": "192.0.2.0/24"
  }'

The Lua handler includes a minimal API key check, with a note pointing operators toward dnsdist's webserver ACL and TLS configuration for production hardening. All example IP addresses use RFC 5737 documentation ranges.

Why This Matters for DNS DDoS Mitigation

DNS amplification is one of the most common DDoS attack vectors. Open resolvers and authoritative servers are abused to reflect and amplify traffic toward victims. dnsdist sits in front of DNS infrastructure and can drop abusive queries before they reach the backend resolver or authoritative server.

The built-in dynamic block system works well for rate-based detection (e.g., block any source that exceeds 1000 queries per second). But many operators also run external traffic analyzers, SIEMs, or DDoS detection systems that identify malicious sources through different means: NetFlow analysis, threat intelligence feeds, or packet-level classification.

Before this documentation existed, operators who wanted to push blocks into dnsdist from an external system had to figure out the Lua API themselves, reverse-engineering the handler pattern from dnsdist's source code. The contributed guide provides a tested, copy-paste starting point that handles both blocking and unblocking, with proper error handling and security considerations.

Flowtriq and dnsdist Together

When Flowtriq detects a DNS amplification attack targeting your network, it identifies the source IPs or subnets generating the amplified responses. With the webhook endpoints documented in this guide, Flowtriq can push dynamic blocks directly to your dnsdist instances, dropping the abusive traffic at the DNS layer before it reaches your resolvers.

The flow is straightforward:

1. Flowtriq detects DNS amplification traffic via packet-level analysis (sub-second detection)
2. The escalation policy triggers a webhook action targeting your dnsdist endpoint
3. dnsdist installs the dynamic block and begins dropping queries from the source CIDR
4. When the attack subsides and the block TTL expires, dnsdist removes the block automatically

This is particularly useful for operators running their own authoritative DNS infrastructure or open resolver networks. The block is applied at the dnsdist layer, which is purpose-built for high query rates and adds minimal latency even under heavy load.

The guide uses only built-in dnsdist APIs. No external dependencies, plugins, or patches are required. Any dnsdist 1.9+ deployment can use this pattern immediately.

Security Considerations

The guide includes explicit security guidance because a webhook that can block arbitrary CIDRs is a powerful capability that needs to be locked down:

• Webserver ACL: Restrict dnsdist's web server to trusted source IPs only. The guide references dnsdist's setWebserverConfig ACL parameter.
• TLS: Always use HTTPS in production. The guide notes that the webserver should be configured with a certificate.
• API key validation: The Lua handler includes a key check, but the guide emphasizes that the ACL is the primary defense and the API key is a secondary control.

Back to Blog

Related Articles