.. _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.