From: Pieter Lexis Date: Tue, 22 May 2018 18:13:40 +0000 (+0200) Subject: GeoIP docs: re-do part of the backend page X-Git-Tag: dnsdist-1.3.3~186^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c280ccd03f53030f6a3ac7984d4df84167e3d3ee;p=thirdparty%2Fpdns.git GeoIP docs: re-do part of the backend page --- diff --git a/docs/backends/geoip.rst b/docs/backends/geoip.rst index d8472bf516..fddfec14fb 100644 --- a/docs/backends/geoip.rst +++ b/docs/backends/geoip.rst @@ -51,30 +51,34 @@ defaults suite you. ~~~~~~~~~~~~~~~~~~~~~~~~ .. versionchanged:: 4.2.0 - This option has been changed since v4.2.0 + The syntax of the argument has been changed. Comma, tab or space separated list of files to open. You can use -`geoip-cvs-to-dat `__ +`geoip-cvs-to-dat `__. to generate your own. -For MMDB files, see `https://github.com/maxmind/getting-started-with-mmdb ` +For MMDB files, see `MaxMind's getting started guide `__. Since v4.2.0, database type is determined by file suffix, or you can use new syntax. New syntax is ``[driver:]path[;options]``. -Currently supported options for dat driver (legacy libGeoIP): - - mode=standard, memory, index or mmap +Drivers and options +^^^^^^^^^^^^^^^^^^^ -Currently supported options for mmdb driver (libmaxminddb): - - mode=mmap - - language=en (which language to use) +:dat: legacy libGeoIP database. Options: -.. _setting-geoip-database-cache: + :mode: The caching mode for data, one of ``standard``, ``memory``, ``index``, or ``mmap``. -``geoip-database-cache`` (before v4.2.0) +:mmdb: driver for libmaxminddb databases. Options: + + :mode: The caching mode for data, only ``mmap`` is supported + :language: The language to use, ``en`` by default + +``geoip-database-cache`` ~~~~~~~~~~~~~~~~~~~~~~~~ .. deprecated:: 4.2.0 + This setting is removed Specifies the kind of caching that is done on the database. This is one @@ -103,7 +107,7 @@ Zonefile format --------------- Zone configuration file uses YAML syntax. Here is simple example. Note -that the ‐ before certain keys is part of the syntax. +that the ``‐`` before certain keys is part of the syntax. .. code-block:: yaml @@ -142,95 +146,129 @@ that the ‐ before certain keys is part of the syntax. Keys explained ~~~~~~~~~~~~~~ -- **domains**: Mandatory root key. All configuration is below this -- **domain**: Defines a domain. You need ttl, records, services under - this. -- **ttl**: TTL value for all records -- **records**: Put fully qualified name as subkey, under which you must - define at least soa: key. Note that this is an array of records, so ‐ - is needed for the values. -- **services**: Defines one or more services for querying. -- From 4.2.0, you can also use %lat, %lon, %loc to expand for geographic - location, if available in backend. %loc in particular can be safely - used with LOC record type. -- From 4.2.0, you can also use %ip4 and %ip6 that will expand to the - IP address when AFI matches, and empty otherwise. Can be particularly - used with A and AAAA record types. -- From 4.1.0, you can also use %cc = 2 letter country code -- From 4.0.0, you can also use %as = ASn, %ip = Remote IP -- From 4.0.0, you can also use additional specifiers. These are %hh = - hour, %dd = day, %mo = month, %mos = month as short string, %wd = - weekday (as number), %wds weekday as short string. -- From 4.0.0, scopeMask is set to most specific value, in case of - date/time modifiers it will be 32 or 128, but with the others it is - set to what geoip says it used for matching. -- From 4.0.0, You can add per-network overrides for format, they will - be formatted with the same placeholders as default. Default is - short-hand for adding 0.0.0.0/0 and ::/0. Default is default when - only string is given for service name. -- From 4.0.0, You can use array to specify return values, works only if - you have those records specified. It matches the format results to - your records, and if it finds match that is used. Otherwise the last - is returned. -- From 4.0.0, You can apply all the attributes for the content of - static records too. -- From 4.0.0, You can use record attributes to set TTL. -- From 4.0.0, You can use record attributes to define weight. If this - is given, only one record is chosen randomly based on the weight. - **DO NOT** mix record types for these. It will not work. PROBABILITY - is calculated by summing up the weights and dividing each weight with - the sum. **WARNING**: If you use ip or time/date specifiers, caching - will be disabled for that RR completely. That means, if you have a - -something.example.com: - a: 1.2.3.4 - txt: "your ip is %ip" +:domains: Mandatory root key. All configuration is below this -then caching will not happen for any records of something.example.com. -If you need to use TXT for debugging, make sure you use dedicated name -for it. + :domain: Defines a domain. You need ttl, records, services under this. + :ttl: TTL value for all records, if no TTL is specified in specific record. + :records: Records for this domain. + Each subkey must be a fully qualified name, under which an array of records follows. + Every record is then keyed by its type (e.g. ``a``, ``txt``) and a type may exist more than once. + The content for this record may then be confgured as the value. + However, a record can alternatively have one or more subkeys: + + :content: The content of the record. + :ttl: The TTL for this record. + :weight: The weight for this specific content -Since v4.1.0 you can mix service and static records to produce the sum -of these records, including apex record. + :services: Defines one or more services for querying. + Each service name may have one or more placeholders. -Format explained -~~~~~~~~~~~~~~~~ +.. note:: -Following placeholders are supported, and support subnet caching with EDNS. -- %%: % -- %co: With legacy GeoIP database only expands to three letter country name, + For each **domain**, one record of the domain name **MUST** exist with a ``soa`` record. + +Placeholders +~~~~~~~~~~~~ + +Services, domains and record content can contain any number of placeholders that are replaced based on the information in the database and the query. + +Following placeholders are supported, and support subnet caching with EDNS: + +:%%: literal ``%`` +:%co: With legacy GeoIP database only expands to three letter country name, with MMDB and others this will expand into ISO3166 country code. -- %cc: ISO3166 country code. -- %cn: ISO3166 continent code. -- %af: v4 or v6. -- %re: Region code -- %na: AS organization name (spaces are converted to _) -- %as: AS number -- %ci: City name -- %loc: LOC record style expansion of location -- %lat: Decimal degree latitude -- %lon: Decimal degree longitude - -Following placeholders disable caching completely. -- %yy: Year -- %mos: Month name -- %mo: Month -- %wds: Weekday name -- %wd: Weekday -- %dd: Year day -- %hh: Hour -- %ip: IP address -- %ip4: IPv4 address -- %ip6: IPv6 address - -.. warning:: - Before 4.2.0 if record expanded to empty value it could cause SERVFAIL. Since 4.2.0 such expansions for non-TXT record types are not included in response. - -.. warning:: - If the record which a service points to exists under "records" then it is returned as a direct answer. If it does not exist under "records" then it is returned as a CNAME. - -.. warning:: - If your services match wildcard records in your zone file - then these will be returned as CNAMEs. This will only be an issue if you - are trying to use a service record at the apex of your domain where you - need other record types to be present (such as NS and SOA records.) Per - :rfc:`2181`, CNAME records cannot appear in the same label as NS or SOA - records. +:%cc: ISO3166 country code. +:%cn: ISO3166 continent code. +:%af: v4 or v6. +:%re: Region code +:%na: AS organization name (spaces are converted to _) +:%as: AS number +:%ci: City name +:%loc: LOC record style expansion of location +:%lat: Decimal degree latitude +:%lon: Decimal degree longitude + +These placeholders disable caching for the record completely: + +:%yy: Year +:%mos: Month name +:%mo: Month +:%wds: Weekday name +:%wd: Weekday +:%dd: Year day +:%hh: Hour +:%ip: Client IP address +:%ip4: Client IPv4 address +:%ip6: Client IPv6 address + +.. versionadded:: 4.2.0 + + These placeholder have been added in version 4.2.0: + + - %lat, %lon, %loc to expand for geographic location, if available in backend. %loc in particular can be safely used with LOC record type. + - %ip4 and %ip6 that will expand to the IP address when AFI matches, and empty otherwise. Can be particularly used with A and AAAA record types. + +.. versionadded:: 4.1.0 + + These placeholder have been added in version 4.1.0: + + - %cc = 2 letter country code + +Using the ``weight`` attribute +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use record attributes to define weight. +If this is given, only one record is chosen randomly based on the weight. + +Probability is calculated by summing up the weights and dividing each weight with the sum. + +Responses to queries +~~~~~~~~~~~~~~~~~~~~ + +If the record which a service points to exists under "records" then it is returned as a direct answer. +If it does not exist under "records" then it is returned as a CNAME. + +You can mix service and static records to produce the sum of these records, including apex record. +For instance, this configuration will send the correct response both A and SOA queries: + +.. code-block:: yaml + + domains: + - domain: example.com + - ttl: 300 + - records: + geo.example.com: + - soa: ns1.example.com hostmaster.example.com 2014090125 7200 3600 1209600 3600 + - ns: ns1.example.com + - a: 192.0.2.1 + swe.eu.example.com: + - a: 192.0.2.2 + - services: + geo.example.com: ['%co.%cn.example.com'] + +If your services match wildcard records in your zone file then these will be returned as CNAMEs. +This will only be an issue if you are trying to use a service record at the apex of your domain where you need other record types to be present (such as NS and SOA records). +Per :rfc:`2181`, CNAME records cannot appear in the same label as NS or SOA records. + +.. versionchanged:: 4.2.0 + + Before, a record expanded to an empty value it could cause SERVFAIL. + Since 4.2.0 such expansions for non-TXT record types are not included in response. + +Caching and the GeoIP Backend +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :ref:`packet-cache` and :ref:`query-cache` will cache the records with EDNS Client Subnet information, when provided in the response. +Use of certain placeholders (described above) can disable record caching for certail resource records. + +That means, if you have a record like this: + +.. code-block:: yaml + + something.example.com: + - a: 1.2.3.4 + - txt: "your ip is %ip" + +then caching will not happen for any records of something.example.com. + +If you need to use TXT for debugging, make sure you use dedicated name for it.