NAME

SYNOPSIS

  plugins => { geoip => {
    maps => {
      my_prod_map => {
        geoip2_db => GeoIP2-City.mmdb,
        datacenters => [dc-03, dc-02, dc-01, dc-fail],
        map => {
            EU => {
                DE => [dc-03, dc-01, dc-fail],
                CH => [dc-01, dc-03, dc-fail]
            },
            NA => { MX => [dc-02, dc-fail] }
        }
      },
      my_auto_map => {
        geoip2_db => GeoIP2-Country.mmdb,
        datacenters => [dc1, dc2],
        auto_dc_coords => {
           dc1 => [ 38.9, -77 ],
           dc2 => [ 50.1, 8.7 ],
        }
      }
    },
    resources => {
      prod_www => {
        map => my_prod_map
        service_types => up
        dcmap => {
          dc-01 => 192.0.2.1,
          dc-02 => { lb01 => 192.0.2.2, lb02 => 192.0.2.3 },
          dc-03 => [ 192.0.2.4, 192.0.2.5, 192.0.2.6 ],
          dc-fail => last.resort.cname.example.net.
        }
      }
      corp_www => {
        map => my_auto_map
        dcmap => {
          dc1 => 192.0.2.100,
          dc2 => 192.0.2.101
        }
      }
    }
  }}

Example zonefile RRs in zone example.com:

  www      600 DYNA geoip!prod_www
  www-dc01 600 DYNA geoip!prod_www/dc-01
  www.corp 600 DYNA geoip!corp_www

DESCRIPTION

It supports the GeoIP2 format databases, which typically end in .mmdb. It does not supports the legacy GeoIP1 format databases (which typically end in .dat).

It can also be used with no GeoIP database at all, in which case the only network-mapping input comes from the "nets" config data or an external "nets" file, which explicitly map subnets to datacenter lists.

This plugin can operate in an automatic distance-based mode (using a City-level database's coordinate information) It can also operate coordinate-free and rely on the user to configure a hierarchical map of cascading default user-location-to-datacenter mappings, starting at the continent level.

The two modes can also be effectively mixed at geographic boundaries.

For each "map" you define (which maps geographic location codes to preference-ordered lists of your datacenter locations), this plugin merges all of the raw GeoIP subnets into the largest possible supernets which contain identical responses in your configuration. These in turn are used to set larger edns-client-subnet scope masks than you'd see simply returning raw GeoIP results.

PLUGIN_METAFO

FILE LOCATIONS

CONFIGURATION - TOP-LEVEL

The other two are required and expanded upon in detail in the next two sections: "maps", and "resources". The "maps" section defines one or more named mappings of location information from GeoIP binary databases to ordered subsets of datacenter names. The "resources" section defines one or more named resources, each of which references one of the named maps and resolves datacenter names to specific sets of addresses or CNAMEs.

Any other keys present at this level will be inherited down inside of each per-resource hash inside the "resources" stanza, acting as per-resource defaults for anything not defined explicitly there.

CONFIGURATION - MAPS

    nets => {
        10.0.0.0/8 => [ dc1, dc2 ],
        192.0.2.128/25 => dc3
        2001:DB8::/32 => [ dc4, dc5, dc6 ],
    }

  { OC => { NZ => { OTA => [...] } } }

  { EU => { FR => { Paris => [...] } } }

CONFIGURATION - MAPS - CITY AUTO MODE

"auto_dc_coords = { ... }"

Key-value hash, optional. If this option is specified, the whole map's basic mode of operation changes to "city-auto-mode". The contents of the hash are a key for each datacenter named in "datacenters", with their values set to an array of "[lat, lon]" in decimal degree units. When city-auto-mode is enabled by this, the following configuration-validation changes occur from the default, static-mapping mode: the loaded GeoIP2 database(s) are required be City-level databases, and the special keyword "auto" becomes a legal "datacenter list" in the "map" stanza.

With city-auto-mode enabled, the top-level map "default" defaults to "auto", but can be overridden with a manual list. For any location that maps to "auto", the coordinates specified here in "auto_dc_coords" will be compared with the coordinates from the City-level database(s) to determine an automatic distance-sorted datacenter list.

If you omit one or more defined datacenters from the coordinate list in "auto_dc_coords", those datacenters will not be used in automatic results, but will still be available for manual use via "map" and/or "nets" entries.

"auto_dc_limit = N"

Unsigned integer, optional, default 3. When city-auto-mode is in effect, this is the upper length limit for auto-generated lists. 3 is a reasonable default even if you have a considerably longer set of datacenters, as this provides a primary as well as two fallbacks. Raising this to a large number in the presence of a long datacenter list will cause the set of unique result datacenter lists to increase rapidly, and thus reduce the optimization of the final result database for edns-client-subnet purposes. It's really not worth raising this value in almost any case, unless you really need to handle more than 3 random datacenters going offline at the same time and still have clients fail elsewhere. The value zero is treated as unlimited (highly un-recommended).

Under city-auto-mode, when the top-level default is (explicitly or implicitly) "auto", there is still a fallback static ordering which is the whole ordered "datacenters" list, which is the normal static default "default" when not in city-auto-mode. This fallback is used when no location information is available at all (e.g. IPv6 client vs IPv4 GeoIP DB, Anonymous Proxies, etc).

MAP TESTING

CONFIGURATION - RESOURCES

One difference is that metafo's per-resource "datacenters" array is replaced with "map => mapname", which references one of the maps defined in the "maps" stanza, described in detail earlier. The set of defined datacenters in the "dcmap" stanza must match the total set of datacenters defined by the referenced map, unless "undefined_datacenters_ok" is set to "true" (see warnings and documentation above).

The "skip_first" flag can also be set per resource, and is much more useful with the geoip plugin than it is with the basic metafo plugin. If this flag is set, the first datacenter in the failover list for a given lookup will be skipped, allowing the definition of a "second choice" resource using the same basic map definition as the first choice. In this case the original first choice is *never* a possible answer, and the rest of the logic (e.g. skipping datacenters marked as down) proceeds as normal with the remaining list. If the map entry and/or the resource definition have already reduced the effective datacenter count to one, the flag has no effect.

META-PLUGIN INTERACTION

Bear in mind that once you begin using inter-meta-plugin references, you could create a reference loop. gdnsd does not currently detect or prevent such loops, and they will cause complete runtime failure when queried, probably by running out of stack space during recursion.

Additionally, "geoip" can synthesize configuration for "metafo" resources, but the reverse does not hold; "metafo" cannot synthesize configuration for "geoip" resources.

IPv4 Compatible Addresses

         ::0000:NNNN:NNNN/96   # RFC 4291 - v4compat (deprecated)
         ::ffff:NNNN:NNNN/96   # RFC 4291 - v4mapped
    ::ffff:0000:NNNN:NNNN/96   # RFC 2765 - SIIT (obsoleted)
       64:ff9b::NNNN:NNNN/96   # RFC 6052 - Well-Known Prefix
    2001:0000:X:NNNN:NNNN/32   # RFC 4380 - Teredo (IPv4 bits are flipped)
           2002:NNNN:NNNN::/16 # RFC 3056 - 6to4

    (in the Teredo case above, "X" represents some variable non-zero bytes
     that occupy the center 64 bits of the address).

All of this plugin's internal lookup databases are IPv6 databases, and any IPv4-like information is always stored in the v4compat space within these databases. When doing runtime lookups all other v4-like addresses (raw IPv4 addresses, v4mapped, SIIT, WKP, Teredo, and 6to4) are converted to the canonical v4compat IPv6 representation before querying the internal databases. The other representations (v4mapped, SIIT, WKP, Teredo, 6to4) are Undefined internally, and will never be referenced at lookup-time due to the v4compat conversion mentioned earlier.

The "nets" stanza is not allowed to specify entries in the five undefined v4-like IPv6 spaces (those other than v4compat). Specify those networks as normal IPv4 networks or v4compat networks instead. Legitimate IPv6 "nets" entries which happen to be a supernet of any v4-like spaces will *not* unduly affect v4-like lookups. There is no functional difference between v4compat and native v4 forms in "nets", e.g. "192.0.2.0/24" and "::C000:0200/120" are completely identical.

GeoIP databases that are natively IPv4-only get all of their data loaded into the v4compat space only. For normal IPv6 GeoIP databases, by default we load the v4compat space directly (which is where MaxMind stores IPv4 data in their IPv6 databases), but ignore the v4mapped/SIIT/Teredo/6to4 spaces (some of which are empty in MaxMind's databases, and some of which simply alias the v4compat space).

ANOTHER CONFIG EXAMPLE

  service_types => {
    xmpp_svc => { plugin => "tcp_connect", ... }
    www_svc => { plugin => "http_status", ... }
  }
  plugins => {
    geoip => {
      maps => {
        my_prod_map => {
          geoip2_db => GeoIP2-City.mmdb,
          datacenters => [us-01, de-01, sg-01],
          map => {
              # Hierarchy is Continent -> Country -> Region -> City
              NA => {
                US => {
                  Dallas => [sg-01],
                }
              }
              SA => [us-01, sg-01, de-01],
              EU => {
                default => [de-01, us-01, sg-01],
                CH => {
                  Geneve => {
                    Geneva => [sg-01],
                  }
                }
              }
              AF => [de-01, us-01, sg-01],
              AS => [sg-01, de-01, us-01],
              OC => [sg-01, us-01, de-01],
          }
          nets => {
              10.0.0.0/8 => [ de-01 ],
              2001:DB8::/32 => [ us-01 ],
          }
        }
        my_auto_map => {
          geoip2_db => GeoIP2-City.mmdb,
          datacenters => [us-01, de-01, sg-01],
          auto_dc_coords => {
             us-01 => [ 38.9, -77 ],
             de-01 => [ 50.1, 8.7 ],
             sg-01 => [ 1.3, 103.9 ],
          }
        }
      }
      resources => {
        prod_app => {
          map => my_auto_map
          # these two are inherited multifo config keys
          #  for all of the dcmap below:
          service_types => [www_svc, xmpp_svc],
          up_thresh => 0.4,
          dcmap => {
            us-01 => {
              lb01 => 192.0.2.1,
              lb02 => 192.0.2.2,
              lb03 => 192.0.2.3,
              lb01.v6 => 2001:DB8::1,
              lb02.v6 => 2001:DB8::2,
              lb03.v6 => 2001:DB8::3,
            },
            sg-01 => {
              lb01 => 192.0.2.4,
              lb02 => 192.0.2.5,
              lb03 => 192.0.2.6,
              lb01.v6 => 2001:DB8::4,
              lb02.v6 => 2001:DB8::5,
              lb03.v6 => 2001:DB8::6,
            },
            de-01 => {
              lb01 => 192.0.2.7,
              lb02 => 192.0.2.8,
              lb03 => 192.0.2.9,
              lb01.v6 => 2001:DB8::7,
              lb02.v6 => 2001:DB8::8,
              lb03.v6 => 2001:DB8::9,
            },
          }
        },
        prod_cdn => {
          map => my_prod_map,
          dcmap => {
            us-01 => us-cdn-provider.example.net.
            sg-01 => asia-cdn-provider.example.net.
            de-01 => europe-cdn-provider.example.net.
          }
        }
      }
    }
  }

Example zonefile RRs in zone example.com:

  app     600 DYNA geoip!prod_app
  app.us  600 DYNA geoip!prod_app/us-01
  app.sg  600 DYNA geoip!prod_app/sg-01
  app.de  600 DYNA geoip!prod_app/de-01
  content 600 DYNC geoip!prod_cdn

EXAMPLE OF METAFO->GEOIP CITY-AUTO-MODE w/ LAST RESORT CNAME

  plugins => {
    geoip => {
      maps => {
        auto_map => {
          geoip2_db => GeoIP2-City.mmdb,
          datacenters => [dc1, dc2, dc3, dc4],
          auto_dc_coords => {
             dc1 => [ 38.9, -77 ],
             dc2 => [ 50.1, 8.7 ],
             dc3 => [ 20.2, 88.9 ],
             dc4 => [ 39.0, -20 ],
          },
          # only fail through the nearest 2 before giving up:
          auto_dc_limit => 2,
        }
      },
      resources => {
        www_real => {
          map => my_auto_map,
          service_types => [ http, xmpp ],
          dcmap => {
            dc1 => 192.0.2.100,
            dc2 => 192.0.2.101,
            dc3 => 192.0.2.102,
            dc4 => 192.0.2.103
          }
        }
      }
    },
    metafo => {
      resources => {
        www => {
          datacenters => [ real, backup ],
          dcmap => {
            real => %geoip!www_real,
            backup => backup-host.example.net.
          }
        }
      }
    }
  }

  And in the example.com zonefile:

  ; This tries through the closest 2/4 datacenters to
  ;   the client from the geoip map, and if both of
  ;   those are down it returns a CNAME to backup-host.example.net.
  ;   for a downtime message or something:
  www DYNC metafo!www

SEE ALSO

The gdnsd manual.

COPYRIGHT AND LICENSE

This file is part of gdnsd.

gdnsd is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

gdnsd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with gdnsd. If not, see <http://www.gnu.org/licenses/>.