diff options
Diffstat (limited to 'src/knot/modules/geoip/geoip.rst')
| -rw-r--r-- | src/knot/modules/geoip/geoip.rst | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/src/knot/modules/geoip/geoip.rst b/src/knot/modules/geoip/geoip.rst new file mode 100644 index 0000000..d65c1cb --- /dev/null +++ b/src/knot/modules/geoip/geoip.rst @@ -0,0 +1,324 @@ +.. _mod-geoip: + +``geoip`` — Geography-based responses +===================================== + +This module offers response tailoring based on client's +subnet, geographic location, or a statistical weight. It supports GeoIP databases +in the MaxMind DB format, such as `GeoIP2 <https://dev.maxmind.com/geoip/geoip2/downloadable/>`_ +or the free version `GeoLite2 <https://dev.maxmind.com/geoip/geoip2/geolite2/>`_. + +The module can be enabled only per zone. + +.. NOTE:: + If :ref:`EDNS Client Subnet<server_edns-client-subnet>` support is enabled + and if a query contains this option, the module takes advantage of this + information to provide a more accurate response. + +DNSSEC support +-------------- + +There are several ways to enable DNSSEC signing of tailored responses. + +Full zone signing +................. + +If :ref:`automatic DNSSEC signing <zone_dnssec-signing>` is enabled, +the whole zone is signed by the server and all alternative RRsets, which are responded +by the module, are pre-signed when the module is loaded. + +This has a speed benefit, however note that every RRset configured in the module should +have a **default** RRset of the same type contained in the zone, so that the NSEC(3) +chain can be built correctly. Also, it is STRONGLY RECOMMENDED to use +:ref:`manual key management <dnssec-manual-key-management>` in this setting, +as the corresponding zone has to be reloaded when the signing key changes and to +have better control over key synchronization to all instances of the server. + +.. NOTE:: + DNSSEC keys for computing record signatures MUST exist in the KASP database + or be generated before the module is launched, otherwise the module fails to + compute the signatures and does not load. + +Module signing +.............. + +If :ref:`automatic DNSSEC signing <zone_dnssec-signing>` is disabled, +it's possible to combine externally pre-signed zone with module pre-signing +of the alternative RRsets when the module is loaded. In this mode, only ZSK +has to be present in the KASP database. Also in this mode every RRset configured +in the module should have a **default** RRset of the same type contained in the zone. + +Example: + +:: + + policy: + - id: presigned_zone + manual: on + unsafe-operation: no-check-keyset + + mod-geoip: + - id: geo_dnssec + ... + dnssec: on + policy: presigned_zone + + zone: + - domain: example.com. + module: mod-geoip/geo_dnssec + +Online signing +.............. + +Alternatively, the :ref:`geoip<mod-geoip>` module may be combined with the +:ref:`onlinesign<mod-onlinesign>` module and the tailored responses can be signed +on the fly. This approach is much more computationally demanding for the server. + +.. NOTE:: + If the GeoIP module is used with online signing, it is recommended to set the :ref:`nsec-bitmap<mod-onlinesign_nsec-bitmap>` + option of the onlinesign module to contain all Resource Record types potentially generated by the module. + +Example +------- + +An example configuration: + +:: + + mod-geoip: + - id: default + config-file: /path/to/geo.conf + ttl: 20 + mode: geodb + geodb-file: /path/to/GeoLite2-City.mmdb + geodb-key: [ country/iso_code, city/names/en ] + + zone: + - domain: example.com. + module: mod-geoip/default + + +Configuration file +------------------ + +Every instance of the module requires an additional :ref:`mod-geoip_config-file` +in which the desired responses to queries from various locations are configured. +This file has the following simple format: + +:: + + domain-name1: + - geo|net|weight: value1 + RR-Type1: RDATA + RR-Type2: RDATA + ... + - geo|net|weight: value2 + RR-Type1: RDATA + ... + domain-name2: + ... + + +Module configuration examples +----------------------------- + +This section contains some examples for the module's :ref:`mod-geoip_config-file`. + +Using subnets +............. + +:: + + foo.example.com: + - net: 10.0.0.0/24 + A: [ 192.168.1.1, 192.168.1.2 ] + AAAA: [ 2001:DB8::1, 2001:DB8::2 ] + TXT: "subnet\ 10.0.0.0/24" + ... + bar.example.com: + - net: 2001:DB8::/32 + A: 192.168.1.3 + AAAA: 2001:DB8::3 + TXT: "subnet\ 2001:DB8::/32" + ... + +Clients from the specified subnets will receive the responses defined in the +module config. Others will receive the default records defined in the zone (if any). + +.. NOTE:: + If a space or a quotation mark is a part of record data, such a character + must be prefixed with a backslash. The following notations are equivalent:: + + Multi-word\ string + "Multi-word\ string" + "\"Multi-word string\"" + +Using geographic locations +.......................... + +:: + + foo.example.com: + - geo: "CZ;Prague" + CNAME: cz.foo.example.com. + - geo: "US;Las Vegas" + CNAME: vegas.foo.example.net. + - geo: "US;*" + CNAME: us.foo.example.net. + ... + +Clients from the specified geographic locations will receive the responses defined in the +module config. Others will receive the default records defined in the zone (if any). See +:ref:`mod-geoip_geodb-key` for the syntax and semantics of the location definitions. + +Using weighted records +...................... + +:: + + foo.example.com: + - weight: 1 + CNAME: canary.foo.example.com. + - weight: 10 + CNAME: prod1.foo.example.com. + - weight: 10 + CNAME: prod2.foo.example.com. + ... + +Each response is generated through a random pick where each defined record has a likelihood +of its weight over the sum of all weights for the requested name to. Records defined in the +zone itself (if any) will never be served. + +Result: + +.. code-block:: console + + $ for i in $(seq 1 100); do kdig @192.168.1.242 CNAME foo.example.com +short; done | sort | uniq -c + 3 canary.foo.example.com.foo.example.com. + 52 prod1.foo.example.net.foo.example.com. + 45 prod2.foo.example.net.foo.example.com. + +Module reference +---------------- + +:: + + mod-geoip: + - id: STR + config-file: STR + ttl: TIME + mode: geodb | subnet | weighted + dnssec: BOOL + policy: policy_id + geodb-file: STR + geodb-key: STR ... + +.. _mod-geoip_id: + +id +.. + +A module identifier. + +.. _mod-geoip_config-file: + +config-file +........... + +Full path to the response configuration file as described above. + +*Required* + +.. _mod-geoip_ttl: + +ttl +... + +The time to live of Resource Records returned by the module, in seconds. + +*Default:* ``60`` + +.. _mod-geoip_mode: + +mode +.... + +The mode of operation of the module. + +Possible values: + +- ``subnet`` – Responses are tailored according to subnets. +- ``geodb`` – Responses are tailored according to geographic data retrieved + from the configured database. +- ``weighted`` – Responses are tailored according to a statistical weight. + +*Default:* ``subnet`` + +.. _mod-geoip_dnssec: + +dnssec +...... + +If explicitly enabled, the module signs positive responses based on the module policy +(:ref:`mod-geoip_policy`). If explicitly disabled, positive responses from the +module are not signed even if the zone is pre-signed or signed by the server +(:ref:`zone_dnssec-signing`). + +.. WARNING:: + This configuration must be used carefully. Otherwise the zone responses + can be bogus. + DNSKEY rotation isn't supported. So :ref:`policy_manual` mode is highly + recommended. + +*Default:* current value of :ref:`zone_dnssec-signing` with :ref:`zone_dnssec-policy` + +.. _mod-geoip_policy: + +policy +...... + +A :ref:`reference<policy_id>` to DNSSEC signing policy which is used if +:ref:`mod-geoip_dnssec` is enabled. + +*Default:* an imaginary policy with all default values + +.. _mod-geoip_geodb-file: + +geodb-file +.......... + +Full path to a .mmdb file containing the GeoIP database. + +*Required if* :ref:`mod-geoip_mode` *is set to* **geodb** + +.. _mod-geoip_geodb-key: + +geodb-key +......... + +Multi-valued item, can be specified up to **8** times. Each **geodb-key** specifies +a path to a key in a node in the supplied GeoIP database. The module currently supports +two types of values: **string** or **32-bit unsigned int**. In the latter +case, the key has to be prefixed with **(id)**. Common choices of keys include: + +* **continent/code** + +* **country/iso_code** + +* **(id)country/geoname_id** + +* **city/names/en** + +* **(id)city/geoname_id** + +* **isp** + +* ... + +The exact keys available depend on the database being used. To get the full list +of keys available, you can e.g. do a sample lookup on your database with the +`mmdblookup <https://maxmind.github.io/libmaxminddb/mmdblookup.html>`_ tool. + +In the zone's config file for the module the values of the keys are entered in the same order +as the keys in the module's configuration, separated by a semicolon. Enter the value **"*"** +if the key is allowed to have any value. |