COREDNS-HOSTS(7)

💅 COREDNS-HOSTS(7) — the hosts plugin, explained by your fave sysadmin bestie ✨

okay so real talk, this is a page from the CoreDNS Plugins manual, and it's all about the hosts plugin. buckle up, it's actually so good 🫶

---

🌸 NAME 🌸

hosts — enables serving zone data from a /etc/hosts style file. literally that's it, that's the vibe 💖

---

✨ DESCRIPTION ✨

okay so the hosts plugin is lowkey iconic for serving zones straight out of a /etc/hosts file. it serves from a preloaded file that exists on disk — and the way it's always checking that file for changes and updating the zones accordingly?? main character energy fr fr 👑

important: this plugin only supports A, AAAA, and PTR records. that's the whole roster, no notes 💅

and bestie, you can absolutely use it with the readily available hosts files that block access to advertising servers — you know the ones 🦋

it reloads the content of the hosts file every 5 seconds. upon reload, CoreDNS will use the new definitions. and if the file gets deleted?? any inlined content will continue to be served (she's resilient like that 💀). when the file is restored, it will then again be used. slay.

if you want to pass the request to the rest of the plugin chain whenever there's no match in the hosts plugin, you must specify the fallthrough option. no fallthrough, no passing, periodt.

🎀 one tiny caveat bestie: this plugin can only be used once per Server Block. that's the rule, i don't make them.

---

🦋 THE HOSTS FILE 🦋

commonly the entries are of the form IP_address canonical_hostname [aliases...] — as explained by the hosts(5) man page. iykyk.

examples:

127.0.0.1       localhost
192.168.1.10    example.com            example

::1                     localhost ip6-localhost ip6-loopback
fdfc:a744:27b5:3b0e::1  example.com example

⭐ WILDCARD RECORDS ⭐

owner names may use a * as the leftmost label to match one additional label below that name. this follows the same wildcard semantics as the file plugin. no cap.

examples:

192.168.1.10    *.example.com
192.168.1.11    a.example.com
192.168.1.12    b.example.com

with the entries above:

• a.example.com and b.example.com resolve to their explicit addresses.
• apps.example.com resolves to 192.168.1.10.
• example.com does not match the wildcard (the zone apex is excluded 🚫).
• deep.apps.example.com does not match *.example.com (only one label is matched — she's not greedy like that).

🙈 also: wildcard entries do not generate PTR records. noted.

💜 PTR RECORDS 💜

PTR records for reverse lookups are generated automatically by CoreDNS (based on the hosts file entries) and cannot be created manually. so don't even try, bestie 😭

---

🌈 SYNTAX 🌈

hosts [FILE [ZONES...]] {
    [INLINE]
    ttl SECONDS
    no_reverse
    reload DURATION
    fallthrough [ZONES...]
    fallthrough_unsupported
}

• FILE — the hosts file to read and parse. if the path is relative, the path from the root plugin will be prepended to it. defaults to /etc/hosts if omitted. we scan the file for changes every 5 seconds. 👀
• ZONES — zones it should be authoritative for. if empty, the zones from the configuration block are used.
• INLINE — the hosts file contents inlined in Corefile. if there are any lines before fallthrough then all of them will be treated as the additional content for hosts file. the specified hosts file path will still be read but entries will be overridden. wild but true.
• ttl — change the DNS TTL of the records generated (forward and reverse). the default is 3600 seconds (1 hour). ⏰
• reload — change the period between each hostsfile reload. a time of zero seconds disables the feature. examples of valid durations: "300ms", "1.5h" or "2h45m". see Go's time package at https://godoc.org/time. 🧚
• no_reverse — disable the automatic generation of the in-addr.arpa or ip6.arpa entries for the hosts.
• fallthrough — if zone matches and no record can be generated, pass request to the next plugin. if [ZONES...] is omitted, then fallthrough happens for all zones for which the plugin is authoritative. if specific zones are listed (for example in-addr.arpa and ip6.arpa), then only queries for those zones will be subject to fallthrough. by default, queries for unsupported record types return an authoritative NODATA response when the queried name has an A or AAAA entry in the hosts data.
• fallthrough_unsupported — extends fallthrough to unsupported query types when the queried name exists in the hosts data. for example, TXT, HTTPS, and SVCB queries for a name with an A or AAAA entry are passed to the next plugin. if that plugin is forward, these queries are sent upstream. 🌊 this option requires fallthrough and uses the same zone scope.

---

🔥 METRICS 🔥

if monitoring is enabled (via the prometheus plugin) then the following metrics are exported:

• coredns_hosts_entries{} — the combined number of entries in hosts and Corefile.
• coredns_hosts_reload_timestamp_seconds{} — the timestamp of the last reload of hosts file. ⏱️

---

👑 EXAMPLES 👑

load /etc/hosts file.

. {
    hosts
}

load example.hosts file in the current directory.

. {
    hosts example.hosts
}

load example.hosts file and only serve example.org and example.net from it, and fall through to the next plugin if the query doesn't match.

. {
    hosts example.hosts example.org example.net {
        fallthrough
    }
}

load hosts file inlined in Corefile.

example.hosts example.org {
    hosts {
        10.0.0.1 example.org
        fallthrough
    }
    whoami
}

resolve all single-label subdomains of example.com to one address, with explicit exceptions, and fall through for everything else under example.com. this one ate, honestly 🍓

. {
    hosts example.hosts example.com {
        192.168.1.10 *.example.com
        192.168.1.11 www.example.com
        fallthrough example.com
    }
    forward . 8.8.8.8
}

---

🎀 SEE ALSO 🎀

the form of the entries in the /etc/hosts file are based on IETF RFC 952 at https://www.rfc-editor.org/info/rfc952/ which was updated by IETF RFC 1123 at https://www.rfc-editor.org/info/rfc1123/. go read them, they're giving original lore 📚

---

and that's the whole page bestie!! this little writeup is from the CoreDNS manual, dated October 2026 — mwah, go configure something cute 💅✨🫶