COREDNS-GEOIP(7)

📦
version 1.15.0 · 3 versions
, in opensuse-leap 16.0

🌸 COREDNS-GEOIP(7) 🌸

okay so before we even get into it — welcome to the geoip page of the CoreDNS Plugins manual, bestie. grab a snack, this one's a chonky read but it's honestly so good. 💖

✨ NAME ✨

geoip — it looks up .mmdb databases (that's the MaxMind db file format, over at https://maxmind.github.io/MaxMind-DB/) using the client IP, and then it adds all that associated geoip data into the context request. slay. 🗺️

💅 DESCRIPTION 💅

So the geoip plugin is literally here to enrich the data tied to Client IP addresses — think geoip info like City, Country, and Network ASN. 🌍 GeoIP data usually comes in .mmdb format, which is a database format that maps IPv4 and IPv6 addresses to data records using a binary search tree. ikyk. 🌳

All that data gets added by leveraging the metadata plugin, and then you can retrieve the values by using it too. it's giving teamwork. 🫶

Longitude example — here's the vibe:

import (
    "strconv"
    "github.com/coredns/coredns/plugin/metadata"
)
// ...
if getLongitude := metadata.ValueFunc(ctx, "geoip/longitude"); getLongitude != nil {
    if longitude, err := strconv.ParseFloat(getLongitude(), 64); err == nil {
        // Do something useful with longitude.
    }
} else {
    // The metadata label geoip/longitude for some reason, was not set.
}
// ...

City example — yes we're doing this one too 🏙️:

import (
    "github.com/coredns/coredns/plugin/metadata"
)
// ...
if getCity := metadata.ValueFunc(ctx, "geoip/city/name"); getCity != nil {
    city := getCity()
    // Do something useful with city.
} else {
    // The metadata label geoip/city/name for some reason, was not set.
}
// ...

ASN example — ok last one, and it's a two-parter 🔥:

import (
    "strconv"
    "github.com/coredns/coredns/plugin/metadata"
)
// ...
if getASN := metadata.ValueFunc(ctx, "geoip/asn/number"); getASN != nil {
    if asn, err := strconv.ParseUint(getASN(), 10, 32); err == nil {
        // Do something useful with asn.
    }
}
if getASNOrg := metadata.ValueFunc(ctx, "geoip/asn/org"); getASNOrg != nil {
    asnOrg := getASNOrg()
    // Do something useful with asnOrg.
}
// ...

🎀 DATABASES 🎀

The supported databases use city schema — like ASN, City, and Enterprise. basically .mmdb files are generally supported, as long as their field names correctly map to the Metadata Labels down below. 👑 Other database types with different schemas? not supported yet, sorry bestie. 🙈

Free and commercial GeoIP .mmdb files are commonly available from vendors like:

⭐ SYNTAX ⭐

geoip [DBFILE]

orrrr

geoip [DBFILE] {
    [edns-subnet]
}
  • DBFILE — the mmdb database file path. highly recommend you update your mmdb database periodically for more accurate results. like, keep it fresh. 🧚
  • edns-subnet — Optional. Use EDNS0 subnet (https://en.wikipedia.org/wiki/EDNS_Client_Subnet) (if present) for Geo IP instead of the source IP of the DNS request. This helps identifying the closest source IP address through intermediary DNS resolvers, and it also makes GeoIP testing easy — look: dig +subnet=1.2.3.4 @dns-server.example.com www.geo-aware.com. 💀✨
NOTE: due to security reasons, recursive DNS resolvers may mask a few bits off of the clients' IP address, which can cause inaccuracies in GeoIP resolution. ⚠️

There's no defined mask size in the standards, but there are examples, so let's look at those: RFC 7871's example (https://www.rfc-editor.org/info/rfc7871/#section-13) conceals the last 72 bits of an IPv6 source address, and the NS1 Help Center mentions (https://help.ns1.com/hc/en-us/articles/360020256573-About-the-EDNS-Client-Subnet-ECS-DNS-extension) that ECS-enabled DNS resolvers send only the first three octets (eg. /24) of the source IPv4 address. the way they just chop off bits 😭

🦋 EXAMPLES 🦋

This config configures the City database, and looks up geolocation based on EDNS0 subnet if present. iconic behaviour honestly:

. {
    geoip /opt/geoip2/db/GeoLite2-City.mmdb {
      edns-subnet
    }
    metadata # Note that metadata plugin must be enabled as well.
}

The view plugin can use geoip metadata as selection criteria to give you GSLB functionality. ✨ In this example, clients from the city "Exampleshire" will receive answers for example.com from the zone defined in example.com.exampleshire-db. All other clients will receive answers from the zone defined in example.com.db. Note that the order of the two example.com server blocks below is important; the default viewless server block must be last. don't mess with the order, i'm serious. 👀

example.com {
    view exampleshire {
      expr metadata('geoip/city/name') == 'Exampleshire'
    }
    geoip /opt/geoip2/db/GeoLite2-City.mmdb
    metadata
    file example.com.exampleshire-db
}

example.com {
    file example.com.db
}

💜 METADATA LABELS 💜

A limited set of fields will be exported as labels, and all values are stored using strings regardless of their underlying value type — so you may have to convert it back to its original type. 📝 note that numeric values are always represented in base 10. no hex shenanigans here, bestie.

ok and that's literally only the beginning — the labels themselves are coming up next, so don't go anywhere 🫶✨

  • geoip/city/name — string — e.g. Cambridge — the city name in English 🔥
  • geoip/country/code — string — e.g. GB — the country's ISO 3166-1 code, iykyk (https://en.wikipedia.org/wiki/ISO_3166-1)
  • geoip/country/name — string — e.g. United Kingdom — the country name, in English, no cap
  • geoip/country/is_in_european_union — bool — e.g. false — literally just either true or false 💅
  • geoip/continent/code — string — e.g. EU — check the Continent codes #continent-codes section for the full lore
  • geoip/continent/name — string — e.g. Europe — the continent name in English 🌍
  • geoip/latitude — float64 — e.g. 52.2242 — base 10, max available precision, she's precise ✨
  • geoip/longitude — float64 — e.g. 0.1315 — base 10, max available precision, same energy 🎀
  • geoip/timezone — string — e.g. Europe/London — the timezone, bestie 🕰️
  • geoip/postalcode — string — e.g. CB4 — the postal code 🍓
  • geoip/subdivisions/code — string — e.g. ENG,TWH — comma separated ISO 3166-2
  • (this one's the tail end of the subdivision label above — no type, no default listed) — <https://en.wikipedia.org/wiki/ISO_3166-2> subdivision(region) codes, e.g. first level (province), second level (state). 🗺️
  • geoip/asn/number — type uint, default 396982 ✨ — literally the autonomous system number.
  • geoip/asn/org — type string, default GOOGLE-CLOUD-PLATFORM 💖 — the autonomous system organization. ok that default is such a flex ngl.

🌍 CONTINENT CODES 🌍

bestie these are the continent values, memorise them or keep this open, either works 🫶

  • AF — Africa
  • AN — Antarctica
  • AS — Asia
  • EU — Europe
  • NA — North America
  • OC — Oceania
  • SA — South America

💀 NOTABLE CHANGES 💀

🚨 real talk: if your code was checking for 0 to mean "no coords", that check is lowkey cooked now. it's "" in v2, and 0 was never actually "missing" anyway because Null Island is a whole real place. so yeah — possibly-breaking, read the migration guide, do not come for me. 🫠

and that's the whole page, bestie!! 🎀 you officially know more about geoip than like 99% of people. the vibe check passed, the docs ate, periodt. 💅✨

this little icon was brought to you by CoreDNS, October 2026 edition, filed under COREDNS-GEOIP(7) in the manual shelf — go read it again, iykyk 🦋💜

📦 where this page comes from