path: root/src/knot/modules/geoip/geoip.rst

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