COREDNS-SHED(7)

🦋 shed — the manual page, but make it make sense

okay so this is coredns-shed, a CoreDNS plugin page (from the CoreDNS Plugins manual, section 7 if you're keeping score 💅). Sit down bestie, because this one is genuinely iconic and also mildly terrifying.

✨ NAME ✨

shed — it serializes UDP response writes per listener socket, and sheds load when the socket literally cannot keep up. no cap.

🌸 DESCRIPTION 🌸

So here's the vibe. UDP responses written back through one listener socket all serialize on the Go runtime's internal fdMutex, and that thing allows at most 2^20-1 concurrent operations (holders plus waiters) per file descriptor. Go over that, and your process just dies. Like, on the spot, with:

panic: too many concurrent operations on a single file or socket (max 1048575)

CoreDNS serves UDP with one goroutine per query, and every single one of them writes back through the shared packet connection. So when queries arrive faster than the socket's serialized writes can drain, every excess in-flight query just parks its goroutine in that wait queue and nothing bounds the pile. Observed in production, fr fr: ~2.8M goroutines and 60GiB RSS before the panic. 😭

The shed plugin makes that panic structurally unreachable, per UDP listener socket. two ways:

• Single writer 🔥 — responses are not written by the handler goroutine. The packed response gets pushed onto a bounded per-socket stack (fixed depth 1024), and one writer goroutine per socket does the actual wire writes, so the file descriptor never sees more than one writer. The stack evicts the oldest entry when it's full and the writer pops the newest first, so under overload the socket's residual capacity always goes to the freshest response. That depth is a fixed burst budget (roughly 12-16ms of a typical socket's drain rate), not a tunable. don't try to tune it, bestie, it's not that kind of number.
• Coupled shedding 🫶 — while a socket's stack is full, arriving queries on that socket are dropped before any plugin runs. Because work admitted then would only produce a response destined for eviction anyway. There is no configuration here: the stack's fullness is the signal. periodt.

Drops are silent — no response is written, so the client's resolver retries against another server. That's the standard load-shedding contract for UDP DNS, iykyk. Every drop is counted though. 👑

The plugin only acts on UDP; TCP queries pass through untouched. It can only be used in plain DNS server blocks (not tls, grpc, https or quic), and that's enforced at startup — so if you try it, it'll tell you no. It should be listed before (above) the prometheus plugin in the plugin chain, so that shed drops are never counted as handled requests by the prometheus plugin — which is where this plugin sits by default.

⭐ real talk: when several server blocks share a listener, any block with shed installs the write discipline for every write on that socket, but the pre-chain shedding only runs in blocks that carry the directive. So keep it uniform across blocks sharing a listener. And the discipline covers every response written through WriteMsg — which is how every plugin responds. A plugin writing raw bytes with ResponseWriter.Write would bypass it. 💀

🎀 SYNTAX 🎀

shed

The plugin takes no arguments. that's it. that's the whole syntax. slay.

💖 METRICS 💖

If monitoring is enabled (via the prometheus plugin) then the following metric is exported:

• coredns_shed_dropped_total{server, reason} — counter of dropped queries and responses. The reason label is query for queries dropped before the plugin chain because the socket's stack was full, and response for responses dropped at the write boundary (evicted by a newer response, failed to reach the wire, or arriving during shutdown).

🌈 EXAMPLES 🌈

Protect the UDP listener while forwarding:

. {
    shed
    forward . 8.8.8.8
}

🧚 SEE ALSO 🧚

The fdMutex limit is enforced in GOROOT/src/internal/poll/fd_mutex.go. go read it if you're feeling brave. 🙈

---

and that's the whole page, bestie! this one's from the CoreDNS peeps, October 2026 edition — CoreDNS, section 7 of the plugins manual. mwah 💋