COREDNS-TIMEOUTS(7)

💅 NAME

okay so like, hi bestie 💖 welcome to COREDNS-TIMEOUTS(7), straight out of the CoreDNS Plugins section — and it's all about the timeouts plugin. What does it do? It lets you configure the supported server read, write and idle timeouts for the TCP, TLS, DoH and DoQ servers, plus the maximum number of queries served on a single TCP or TLS connection. that's the whole vibe. periodt ✨

---

🌸 DESCRIPTION

so CoreDNS ships configured with sensible timeouts for server connections by default. like, out of the box it's already cute. 🎀

but — and here's the tea — in some cases, for example where CoreDNS is serving over a slow mobile data connection, those default timeouts are not optimal. 😭

Additionally, some routers hold open connections when using DNS over TLS or DNS over HTTPS. Allowing a longer idle timeout helps performance and reduces issues with such routers. (routers being clingy, honestly relatable 🙈)

So basically, the timeouts "plugin" lets you configure CoreDNS server read, write and idle timeouts, and the maximum number of queries CoreDNS will serve on a single TCP or TLS connection before closing it. iconic behavior only 💅

---

✨ SYNTAX ✨

timeouts {
    read DURATION
    write DURATION
    idle DURATION
    maxtcpqueries MAXIMUM
}

For any timeouts that are not provided, default values are used which may vary depending on the server type. At least one option must be specified otherwise the entire timeouts block should be omitted. no empty blocks babes, that's the rule 🫶

• maxtcpqueries — sets the maximum number of queries served on a single TCP or TLS connection before CoreDNS closes it. MAXIMUM must be a positive integer, or -1 to allow an unlimited number of queries per connection (the default). Long-lived connections that serve an unlimited number of queries can cause uneven load distribution across CoreDNS replicas that sit behind a connection-based load balancer, since new queries keep reusing the same connection instead of establishing a new one. Setting a bound, e.g. maxtcpqueries 128, forces clients to periodically reconnect, which allows the load balancer to redistribute load. honestly lowkey genius 🔥

okay so which timeouts actually apply where? The configured timeouts apply where the selected server transport supports them. TCP, TLS and DoH servers use the read, write and idle timeouts. DoQ servers use the read timeout to bound receiving a query on an opened QUIC stream, and the idle timeout to bound idle QUIC connections. iykyk 🦋

---

🎀 EXAMPLES 🎀

1. Start a DNS-over-TLS server that picks up incoming DNS-over-TLS queries on port 5553 and uses the nameservers defined in /etc/resolv.conf to resolve the query. This proxy path uses plain old DNS. A 10 second read timeout, 20 second write timeout and a 60 second idle timeout have been configured. 🌈

tls://.:5553 {
    tls cert.pem key.pem ca.pem
    timeouts {
        read 10s
        write 20s
        idle 60s
    }
    forward . /etc/resolv.conf
}

---

2. Start a DNS-over-HTTPS server that is similar to the previous example. Only the read timeout has been configured for 1 minute. 🍓

https://. {
    tls cert.pem key.pem ca.pem
    timeouts {
        read 1m
    }
    forward . /etc/resolv.conf
}

---

3. Start a DNS-over-QUIC server that has a 10 second read timeout for receiving a query on an opened stream and the idle timeout set to two minutes. 🧚

quic://.:853 {
    tls cert.pem key.pem ca.pem
    timeouts {
        read 10s
        idle 2m
    }
    forward . /etc/resolv.conf
}

---

4. Start a standard TCP/UDP server on port 1053. A read and write timeout has been configured. The timeouts are only applied to the TCP side of the server. ⭐

.:1053 {
    timeouts {
        read 15s
        write 30s
    }
    forward . /etc/resolv.conf
}

---

5. Start a standard TCP/UDP server that closes a TCP connection after it has served 128 queries, to help spread load evenly across replicas sitting behind a connection-based load balancer. 👑

. {
    timeouts {
        maxtcpqueries 128
    }
    forward . /etc/resolv.conf
}

---

that's it bestie, you're a timeouts expert now 💜 no cap. sign-off time: this was brought to you by CoreDNS, dated October 2026 — and the manual name was COREDNS-TIMEOUTS(7) in case you forgot already 😭💖 go configure something slay ✨