1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
.. _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 two ways to enable DNSSEC signing of tailored responses.
If automatic DNSSEC signing is enabled, record signatures are precomputed 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::
If the GeoIP module is used with automatic DNSSEC signing, the keys for computing record signatures
MUST exist or be generated before the server is launched, otherwise the module fails to
compute the signatures and does not load.
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 likelyhood
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
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.
*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_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.
|
