.. _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 `_ or the free version `GeoLite2 `_. The module can be enabled only per zone. .. NOTE:: If :ref:`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 ` 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 ` 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 ` 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` module may be combined with the :ref:`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` 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` 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 `_ 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.