]>
Commit | Line | Data |
---|---|---|
4754223f | 1 | Preset variables |
2 | ---------------- | |
3 | ||
4 | LUA rules run within the same environment as described in | |
2d578977 | 5 | :doc:`../modes-of-operation`. |
4754223f | 6 | |
7 | The Lua snippets can query the following variables: | |
8 | ||
21168dc7 PL |
9 | Query variables |
10 | ~~~~~~~~~~~~~~~ | |
11 | ``dh`` | |
12 | The :class:`DNSHeader` of the received query. | |
13 | ``dnssecOK`` | |
14 | A boolean describing if the DNSSEC OK (DO) bit was set in the query. | |
15 | ``ednsPKTSize`` | |
16 | The advertised EDNS buffer size. | |
17 | ``qname`` | |
18 | The name of the requested record. This is a :class:`DNSName`. | |
19 | ``zone`` | |
20 | The zone this LUA record is in. This is a :class:`DNSName`. | |
21 | ``zoneid`` | |
22 | The id of the zone. This is an integer. | |
23 | ``tcp`` | |
24 | Whether or not the query was received over TCP. | |
25 | ||
26 | Client variables | |
27 | ~~~~~~~~~~~~~~~~ | |
25bcfaec | 28 | ``ecswho`` |
21168dc7 | 29 | The EDNS Client Subnet, should one have been set on the query. Unset |
d2b831c8 | 30 | otherwise. This is a :class:`Netmask`. |
25bcfaec | 31 | ``bestwho`` |
21168dc7 PL |
32 | In absence of ECS, this is set to the IP address of requesting resolver. |
33 | Otherwise set to the network part of the EDNS Client Subnet supplied by the | |
d2b831c8 | 34 | resolver. This is a :class:`ComboAddress`. |
21168dc7 PL |
35 | ``who`` |
36 | IP address of requesting resolver as a :class:`ComboAddress`. | |
514df45b | 37 | ``localwho`` |
38 | IP address (including port) of socket on which the question arrived. | |
4754223f | 39 | |
40 | Functions available | |
41 | ------------------- | |
42 | ||
6a1f0529 PL |
43 | Record creation functions |
44 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
4754223f | 45 | |
6a1f0529 | 46 | .. function:: ifportup(portnum, addresses[, options]) |
4754223f | 47 | |
8a28fb38 | 48 | Simplistic test to see if an IP address listens on a certain port. This will |
ff580c47 OM |
49 | attempt a TCP connection on port ``portnum`` and consider it available if the |
50 | connection establishes. No data will be sent or read on that connection. Note | |
8a28fb38 CHB |
51 | that both IPv4 and IPv6 addresses can be tested, but that it is an error to |
52 | list IPv4 addresses on an AAAA record, or IPv6 addresses on an A record. | |
25bcfaec | 53 | |
ff580c47 OM |
54 | Will return a single address from the set of available addresses. If |
55 | no address is available, will return a random element of the set of | |
8a28fb38 | 56 | addresses supplied for testing. |
25bcfaec | 57 | |
6a1f0529 | 58 | :param int portnum: The port number to test connections to. |
ff580c47 | 59 | :param {str} addresses: The list of addresses to check connectivity for. |
6a1f0529 | 60 | :param options: Table of options for this specific check, see below. |
25bcfaec | 61 | |
6a1f0529 | 62 | Various options can be set in the ``options`` parameter: |
4754223f | 63 | |
ff580c47 OM |
64 | - ``selector``: used to pick the address(es) from the list of available addresses. Choices include 'pickclosest', 'random', 'hashed', 'all' (default 'random'). |
65 | - ``backupSelector``: used to pick the address(es) from all addresses if all addresses are down. Choices include 'pickclosest', 'random', 'hashed', 'all' (default 'random'). | |
66 | - ``source``: Source address to check from | |
a6897a16 | 67 | - ``timeout``: Maximum time in seconds that you allow the check to take (default 2) |
4754223f | 68 | |
4754223f | 69 | |
6a1f0529 | 70 | .. function:: ifurlup(url, addresses[, options]) |
4754223f | 71 | |
6a1f0529 | 72 | More sophisticated test that attempts an actual http(s) connection to |
ff580c47 OM |
73 | ``url``. In addition, a list of sets of IP addresses can be supplied. The |
74 | first set with at least one available address is selected. The ``selector`` then | |
75 | selects from the subset of available addresses of the selected set. | |
76 | An URL is considered available if the HTTP response code is 200 and optionally if | |
77 | the content matches the ``stringmatch`` option. | |
4754223f | 78 | |
6a1f0529 | 79 | :param string url: The url to retrieve. |
ff580c47 | 80 | :param addresses: List of sets of addresses to check the URL on. |
6a1f0529 | 81 | :param options: Table of options for this specific check, see below. |
89ff3721 | 82 | |
6a1f0529 | 83 | Various options can be set in the ``options`` parameter: |
89ff3721 | 84 | |
ff580c47 OM |
85 | - ``selector``: used to pick the address(es) from the subset of available addresses of the selected set. Choices include 'pickclosest', 'random', 'hashed', 'all' (default 'random'). |
86 | - ``backupSelector``: used to pick the address from all addresses if all addresses are down. Choices include 'pickclosest', 'random', 'hashed', 'all' (default 'random'). | |
87 | - ``source``: Source address to check from | |
a6897a16 | 88 | - ``timeout``: Maximum time in seconds that you allow the check to take (default 2) |
6a1f0529 | 89 | - ``stringmatch``: check ``url`` for this string, only declare 'up' if found |
adf5f025 | 90 | - ``useragent``: Set the HTTP "User-Agent" header in the requests. By default it is set to "PowerDNS Authoritative Server" |
0e524ab0 | 91 | - ``byteslimit``: Limit the maximum download size to ``byteslimit`` bytes (default 0 meaning no limit). |
89ff3721 | 92 | |
ff580c47 | 93 | An example of a list of address sets: |
89ff3721 | 94 | |
6a1f0529 | 95 | .. code-block:: lua |
89ff3721 | 96 | |
ef1fd46b | 97 | ifurlup("https://example.com/", { {"192.0.2.20", "203.0.113.4"}, {"203.0.113.2"} }) |
6a1f0529 | 98 | |
95d0df69 PD |
99 | .. function:: ifurlextup(groups-of-address-url-pairs[, options]) |
100 | ||
101 | Very similar to ``ifurlup``, but the returned IPs are decoupled from their external health check URLs. | |
102 | This is useful when health checking already happens elsewhere, and that state is exposed over HTTP(S). | |
103 | Health checks are considered positive if the HTTP response code is 200 and optionally if the content matches the ``stringmatch`` option. | |
104 | ||
105 | Options are identical to those for ``ifurlup``. | |
106 | ||
107 | Example: | |
108 | ||
109 | .. code-block:: lua | |
110 | ||
111 | ifurlextup({{['192.168.0.1']='https://example.com/',['192.168.0.2']='https://example.com/404'}}) | |
112 | ||
113 | Example with two groups: | |
114 | ||
115 | .. code-block:: lua | |
116 | ||
117 | ifurlextup({{['192.168.0.1']='https://example.net/404',['192.168.0.2']='https://example.com/404'}, {['192.168.0.3']='https://example.net/'}})" | |
118 | ||
119 | The health checker will look up the first two URLs (using normal DNS resolution to find them - whenever possible, use URLs with IPs in them). | |
120 | The 404s will cause the first group of IPs to get marked as down, after which the URL in the second group is tested. | |
121 | The third IP will get marked up assuming ``https://example.net/`` responds with HTTP response code 200. | |
6a1f0529 | 122 | |
60f9d9a2 | 123 | .. function:: pickrandom(values) |
6a1f0529 | 124 | |
60f9d9a2 | 125 | Returns a random value from the list supplied. |
6a1f0529 | 126 | |
60f9d9a2 | 127 | :param values: A list of strings such as IPv4 or IPv6 address. |
128 | ||
129 | This function also works for CNAME or TXT records. | |
130 | ||
131 | .. function:: pickrandomsample(number, values) | |
132 | ||
133 | Returns N random values from the list supplied. | |
134 | ||
135 | :param number: Number of values to return | |
136 | :param values: A list of strings such as IPv4 or IPv6 address. | |
137 | ||
138 | This function also works for CNAME or TXT records. | |
139 | ||
140 | .. function:: pickhashed(values) | |
141 | ||
142 | Based on the hash of ``bestwho``, returns a random value from the list supplied. | |
143 | ||
144 | :param values: A list of strings such as IPv4 or IPv6 address. | |
145 | ||
146 | This function also works for CNAME or TXT records. | |
6a1f0529 | 147 | |
1bc56192 | 148 | .. function:: pickclosest(addresses) |
6a1f0529 PL |
149 | |
150 | Returns IP address deemed closest to the ``bestwho`` IP address. | |
151 | ||
152 | :param addresses: A list of strings with the possible IP addresses. | |
153 | ||
154 | .. function:: latlon() | |
155 | ||
156 | Returns text listing fractional latitude/longitude associated with the ``bestwho`` IP address. | |
157 | ||
158 | .. function:: latlonloc() | |
159 | ||
160 | Returns text in LOC record format listing latitude/longitude associated with the ``bestwho`` IP address. | |
161 | ||
162 | .. function:: closestMagic() | |
163 | ||
164 | Suitable for use as a wildcard LUA A record. Will parse the query name which should be in format:: | |
165 | ||
166 | 192-0-2-1.192-0-2-2.198-51-100-1.magic.v4.powerdns.org | |
167 | ||
168 | It will then resolve to an A record with the IP address closest to ``bestwho`` from the list | |
169 | of supplied addresses. | |
170 | ||
171 | In the ``magic.v4.powerdns.org`` this looks like:: | |
172 | ||
173 | *.magic.v4.powerdns.org IN LUA A "closestMagic()" | |
174 | ||
175 | ||
176 | In another zone, a record is then present like this:: | |
177 | ||
178 | www-balanced.powerdns.org IN CNAME 192-0-2-1.192-0-2-2.198-51-100-1.magic.v4.powerdns.org | |
179 | ||
180 | This effectively opens up your server to being a 'geographical load balancer as a service'. | |
181 | ||
182 | Performs no uptime checking. | |
183 | ||
60f9d9a2 | 184 | .. function:: all(values) |
185 | ||
186 | Returns all values. | |
187 | ||
188 | :param values: A list of strings such as IPv4 or IPv6 address. | |
189 | ||
190 | This function also works for CNAME or TXT records. | |
191 | ||
6a1f0529 PL |
192 | .. function:: view(pairs) |
193 | ||
194 | Shorthand function to implement 'views' for all record types. | |
195 | ||
196 | :param pairs: A list of netmask/result pairs. | |
197 | ||
198 | An example:: | |
199 | ||
200 | view.v4.powerdns.org IN LUA A ("view({ " | |
201 | "{ {'192.168.0.0/16'}, {'192.168.1.54'}}," | |
202 | "{ {'0.0.0.0/0'}, {'192.0.2.1'}} " | |
203 | " }) " ) | |
204 | ||
205 | This will return IP address 192.168.1.54 for queries coming from | |
206 | 192.168.0.0/16, and 192.0.2.1 for all other queries. | |
207 | ||
208 | This function also works for CNAME or TXT records. | |
209 | ||
4a0d414b CHB |
210 | .. function:: pickchashed(values) |
211 | ||
212 | Based on the hash of ``bestwho``, returns a string from the list | |
213 | supplied, as weighted by the various ``weight`` parameters and distributed consistently. | |
214 | Performs no uptime checking. | |
215 | ||
216 | :param values: table of weight, string (such as IPv4 or IPv6 address). | |
217 | ||
218 | This function works almost like :func:`pickwhashed` while bringing the following properties: | |
219 | - reordering the list of entries won't affect the distribution | |
220 | - updating the weight of an entry will only affect a part of the distribution | |
221 | - because of the previous properties, the CPU and memory cost is a bit higher than :func:`pickwhashed` | |
222 | ||
a6be268f CHB |
223 | Hashes will be pre computed the first time such a record is hit and refreshed if needed. If updating the list is done often, |
224 | the cash may grow. A cleanup routine is performed every :ref:`setting-lua-consistent-hashes-cleanup-interval` seconds (default 1h) | |
225 | and cleans cached entries for records that haven't been used for :ref:`setting-lua-consistent-hashes-expire-delay` seconds (default 24h) | |
226 | ||
4a0d414b CHB |
227 | An example:: |
228 | ||
229 | mydomain.example.com IN LUA A ("pickchashed({ " | |
230 | " {15, "192.0.2.1"}, " | |
231 | " {100, "198.51.100.5"} " | |
232 | "}) ") | |
233 | ||
234 | ||
60f9d9a2 | 235 | .. function:: pickwhashed(values) |
6a1f0529 | 236 | |
60f9d9a2 | 237 | Based on the hash of ``bestwho``, returns a string from the list |
6a1f0529 PL |
238 | supplied, as weighted by the various ``weight`` parameters. |
239 | Performs no uptime checking. | |
240 | ||
60f9d9a2 | 241 | :param values: table of weight, string (such as IPv4 or IPv6 address). |
6a1f0529 PL |
242 | |
243 | Because of the hash, the same client keeps getting the same answer, but | |
244 | given sufficient clients, the load is still spread according to the weight | |
245 | factors. | |
246 | ||
60f9d9a2 | 247 | This function also works for CNAME or TXT records. |
248 | ||
6a1f0529 PL |
249 | An example:: |
250 | ||
1bc56192 CHB |
251 | mydomain.example.com IN LUA A ("pickwhashed({ " |
252 | " {15, "192.0.2.1"}, " | |
253 | " {100, "198.51.100.5"} " | |
254 | "}) ") | |
89ff3721 | 255 | |
d33b8bf4 BR |
256 | .. function:: picknamehashed(values) |
257 | ||
2b457561 | 258 | Based on the hash of the DNS record name, returns a string from the list supplied, as weighted by the various ``weight`` parameters. |
d33b8bf4 BR |
259 | Performs no uptime checking. |
260 | ||
261 | :param values: table of weight, string (such as IPv4 or IPv6 address). | |
262 | ||
2b457561 PD |
263 | This allows basic persistent load balancing across a number of backends. |
264 | It means that ``test.mydomain.example.com`` will always resolve to the same IP, but ``test2.mydomain.example.com`` may go elsewhere. | |
265 | This function is only useful for wildcard records. | |
d33b8bf4 | 266 | |
2b457561 | 267 | This works similar to round-robin load balancing, but has the advantage of making traffic for the same domain always end up on the same server which can help cache hit rates. |
d33b8bf4 BR |
268 | |
269 | This function also works for CNAME or TXT records. | |
270 | ||
271 | An example:: | |
272 | ||
33e306dc | 273 | *.mydomain.example.com IN LUA A ("picknamehashed({ " |
2b457561 PD |
274 | " {15, "192.0.2.1"}, " |
275 | " {100, "198.51.100.5"} " | |
276 | "}) ") | |
d33b8bf4 | 277 | |
89ff3721 | 278 | |
60f9d9a2 | 279 | .. function:: pickwrandom(values) |
89ff3721 | 280 | |
60f9d9a2 | 281 | Returns a random string from the list supplied, as weighted by the |
6a1f0529 | 282 | various ``weight`` parameters. Performs no uptime checking. |
89ff3721 | 283 | |
60f9d9a2 | 284 | :param values: table of weight, string (such as IPv4 or IPv6 address). |
89ff3721 | 285 | |
1bc56192 | 286 | See :func:`pickwhashed` for an example. |
4754223f | 287 | |
60f9d9a2 | 288 | This function also works for CNAME or TXT records. |
289 | ||
c9fb9a3e | 290 | Reverse DNS functions |
c052aac7 | 291 | ~~~~~~~~~~~~~~~~~~~~~ |
c9fb9a3e | 292 | |
54b7ef3e | 293 | .. warning:: |
223bfcad PD |
294 | For :func:`createForward` and :func:`createForward6`, we recommend filtering with :func:`filterForward`, to prevent PowerDNS from generating A/AAAA responses to addresses outside of your network. |
295 | Not limiting responses like this may, in some situations, help attackers with impersonation and attacks like such as cookie stealing. | |
c9fb9a3e | 296 | |
223bfcad | 297 | .. function:: createReverse(format, [exceptions]) |
c9fb9a3e | 298 | |
4a0d414b CHB |
299 | Used for generating default hostnames from IPv4 wildcard reverse DNS records, e.g. ``*.0.0.127.in-addr.arpa`` |
300 | ||
c9fb9a3e | 301 | See :func:`createReverse6` for IPv6 records (ip6.arpa) |
54b7ef3e CS |
302 | |
303 | See :func:`createForward` for creating the A records on a wildcard record such as ``*.static.example.com`` | |
4a0d414b | 304 | |
c9fb9a3e S |
305 | Returns a formatted hostname based on the format string passed. |
306 | ||
307 | :param format: A hostname string to format, for example ``%1%.%2%.%3%.%4%.static.example.com``. | |
223bfcad PD |
308 | :param exceptions: An optional table of overrides. For example ``{['10.10.10.10'] = 'quad10.example.com.'}`` would, when generating a name for IP ``10.10.10.10``, return ``quad10.example.com`` instead of something like ``10.10.10.10.example.com``. |
309 | ||
54b7ef3e CS |
310 | **Formatting options:** |
311 | ||
f404c4c6 GD |
312 | - ``%1%`` to ``%4%`` are individual octets |
313 | - Example record query: ``1.0.0.127.in-addr.arpa`` | |
314 | - ``%1%`` = 127 | |
315 | - ``%2%`` = 0 | |
316 | - ``%3%`` = 0 | |
317 | - ``%4%`` = 1 | |
318 | - ``%5%`` joins the four decimal octets together with dashes | |
319 | - Example: ``%5%.static.example.com`` is equivalent to ``%1%-%2%-%3%-%4%.static.example.com`` | |
320 | - ``%6%`` converts each octet from decimal to hexadecimal and joins them together | |
321 | - Example: A query for ``15.0.0.127.in-addr.arpa`` | |
322 | - ``%6`` would be ``7f00000f`` (127 is 7f, and 15 is 0f in hexadecimal) | |
54b7ef3e | 323 | |
c9fb9a3e | 324 | Example records:: |
4a0d414b | 325 | |
c9fb9a3e S |
326 | *.0.0.127.in-addr.arpa IN LUA PTR "createReverse('%1%.%2%.%3%.%4%.static.example.com')" |
327 | *.1.0.127.in-addr.arpa IN LUA PTR "createReverse('%5%.static.example.com')" | |
328 | *.2.0.127.in-addr.arpa IN LUA PTR "createReverse('%6%.static.example.com')" | |
4a0d414b | 329 | |
c9fb9a3e | 330 | When queried:: |
4a0d414b | 331 | |
c9fb9a3e S |
332 | # -x is syntactic sugar to request the PTR record for an IPv4/v6 address such as 127.0.0.5 |
333 | # Equivalent to dig PTR 5.0.0.127.in-addr.arpa | |
334 | $ dig +short -x 127.0.0.5 @ns1.example.com | |
335 | 127.0.0.5.static.example.com. | |
336 | $ dig +short -x 127.0.1.5 @ns1.example.com | |
337 | 127-0-0-5.static.example.com. | |
338 | $ dig +short -x 127.0.2.5 @ns1.example.com | |
339 | 7f000205.static.example.com. | |
340 | ||
341 | .. function:: createForward() | |
4a0d414b | 342 | |
c9fb9a3e | 343 | Used to generate the reverse DNS domains made from :func:`createReverse` |
4a0d414b | 344 | |
c9fb9a3e | 345 | Generates an A record for a dotted or hexadecimal IPv4 domain (e.g. 127.0.0.1.static.example.com) |
4a0d414b | 346 | |
c9fb9a3e | 347 | It does not take any parameters, it simply interprets the zone record to find the IP address. |
4a0d414b | 348 | |
c9fb9a3e | 349 | An example record for zone ``static.example.com``:: |
4a0d414b | 350 | |
c9fb9a3e | 351 | *.static.example.com IN LUA A "createForward()" |
4a0d414b | 352 | |
cbdef4ab | 353 | This function supports the forward dotted format (``127.0.0.1.static.example.com``), and the hex format, when prefixed by two ignored characters (``ip40414243.static.example.com``) |
4a0d414b | 354 | |
c9fb9a3e | 355 | When queried:: |
4a0d414b | 356 | |
c9fb9a3e S |
357 | $ dig +short A 127.0.0.5.static.example.com @ns1.example.com |
358 | 127.0.0.5 | |
4a0d414b | 359 | |
ee5265d3 PD |
360 | Since 4.8.0: the hex format can be prefixed by any number of characters (within DNS label length limits), including zero characters (so no prefix). |
361 | ||
223bfcad | 362 | .. function:: createReverse6(format[, exceptions]) |
c9fb9a3e | 363 | |
54b7ef3e | 364 | Used for generating default hostnames from IPv6 wildcard reverse DNS records, e.g. ``*.1.0.0.2.ip6.arpa`` |
4a0d414b | 365 | |
c9fb9a3e | 366 | **For simplicity purposes, only small sections of IPv6 rDNS domains are used in most parts of this guide,** |
54b7ef3e | 367 | **as a full ip6.arpa record is around 80 characters long** |
4a0d414b | 368 | |
c9fb9a3e | 369 | See :func:`createReverse` for IPv4 records (in-addr.arpa) |
54b7ef3e CS |
370 | |
371 | See :func:`createForward6` for creating the AAAA records on a wildcard record such as ``*.static.example.com`` | |
4a0d414b | 372 | |
c9fb9a3e S |
373 | Returns a formatted hostname based on the format string passed. |
374 | ||
375 | :param format: A hostname string to format, for example ``%33%.static6.example.com``. | |
223bfcad PD |
376 | :param exceptions: An optional table of overrides. For example ``{['2001:db8::1'] = 'example.example.com.'}`` would, when generating a name for IP ``2001:db8::1``, return ``example.example.com`` instead of something like ``2001--db8.example.com``. |
377 | ||
54b7ef3e | 378 | Formatting options: |
4a0d414b | 379 | |
f404c4c6 GD |
380 | - ``%1%`` to ``%32%`` are individual characters (nibbles) |
381 | - **Example PTR record query:** ``a.0.0.0.1.0.0.2.ip6.arpa`` | |
382 | - ``%1%`` = 2 | |
383 | - ``%2%`` = 0 | |
384 | - ``%3%`` = 0 | |
385 | - ``%4%`` = 1 | |
386 | - ``%33%`` converts the compressed address format into a dashed format, e.g. ``2001:a::1`` to ``2001-a--1`` | |
387 | - ``%34%`` to ``%41%`` represent the 8 uncompressed 2-byte chunks | |
388 | - **Example:** PTR query for ``2001:a:b::123`` | |
389 | - ``%34%`` - returns ``2001`` (chunk 1) | |
390 | - ``%35%`` - returns ``000a`` (chunk 2) | |
391 | - ``%41%`` - returns ``0123`` (chunk 8) | |
4a0d414b | 392 | |
c9fb9a3e | 393 | Example records:: |
4a0d414b | 394 | |
1efb8aa6 MH |
395 | *.1.0.0.2.ip6.arpa IN LUA PTR "createReverse6('%33%.static6.example.com')" |
396 | *.2.0.0.2.ip6.arpa IN LUA PTR "createReverse6('%34%.%35%.static6.example.com')" | |
4a0d414b | 397 | |
c9fb9a3e | 398 | When queried:: |
4a0d414b | 399 | |
c9fb9a3e S |
400 | # -x is syntactic sugar to request the PTR record for an IPv4/v6 address such as 2001::1 |
401 | # Equivalent to dig PTR 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.b.0.0.0.a.0.0.0.1.0.0.2.ip6.arpa | |
402 | # readable version: 1.0.0.0 .0.0.0.0 .0.0.0.0 .0.0.0.0 .0.0.0.0 .b.0.0.0 .a.0.0.0 .1.0.0.2 .ip6.arpa | |
4a0d414b | 403 | |
c9fb9a3e S |
404 | $ dig +short -x 2001:a:b::1 @ns1.example.com |
405 | 2001-a-b--1.static6.example.com. | |
4a0d414b | 406 | |
c9fb9a3e S |
407 | $ dig +short -x 2002:a:b::1 @ns1.example.com |
408 | 2002.000a.static6.example.com | |
409 | ||
410 | .. function:: createForward6() | |
4a0d414b | 411 | |
c9fb9a3e | 412 | Used to generate the reverse DNS domains made from :func:`createReverse6` |
4a0d414b | 413 | |
54b7ef3e | 414 | Generates an AAAA record for a dashed compressed IPv6 domain (e.g. ``2001-a-b--1.static6.example.com``) |
4a0d414b | 415 | |
c9fb9a3e | 416 | It does not take any parameters, it simply interprets the zone record to find the IP address. |
4a0d414b | 417 | |
c9fb9a3e | 418 | An example record for zone ``static.example.com``:: |
4a0d414b | 419 | |
c9fb9a3e | 420 | *.static6.example.com IN LUA AAAA "createForward6()" |
4a0d414b | 421 | |
cbdef4ab | 422 | This function supports the dashed compressed format (i.e. ``2001-a-b--1.static6.example.com``), and the dot-split uncompressed format (``2001.db8.6.5.4.3.2.1.static6.example.com``) |
4a0d414b | 423 | |
c9fb9a3e | 424 | When queried:: |
4a0d414b | 425 | |
c9fb9a3e S |
426 | $ dig +short AAAA 2001-a-b--1.static6.example.com @ns1.example.com |
427 | 2001:a:b::1 | |
428 | ||
ee5265d3 PD |
429 | Since 4.8.0: a non-split full length format (``20010002000300040005000600070db8.example.com``) is also supported, optionally prefixed, in which case the last 32 characters will be considered. |
430 | ||
223bfcad PD |
431 | .. function:: filterForward(address, masks[, fallback]) |
432 | ||
af9598dc PD |
433 | .. versionadded:: 4.5.0 |
434 | ||
223bfcad PD |
435 | Used for limiting the output of :func:`createForward` and :func:`createForward6` to a set of netmasks. |
436 | ||
437 | :param address: A string containing an address, usually taken directly from :func:`createForward: or :func:`createForward6`. | |
438 | :param masks: A NetmaskGroup; any address not matching the NMG will be replaced by the fallback address. | |
439 | :param fallback: A string containing the fallback address. Defaults to ``0.0.0.0`` or ``::``. | |
440 | ||
441 | Example:: | |
442 | ||
af9598dc | 443 | *.static4.example.com IN LUA A "filterForward(createForward(), newNMG({'192.0.2.0/24', '10.0.0.0/8'}))" |
223bfcad | 444 | |
6a1f0529 PL |
445 | Helper functions |
446 | ~~~~~~~~~~~~~~~~ | |
4754223f | 447 | |
6a1f0529 PL |
448 | .. function:: asnum(number) |
449 | asnum(numbers) | |
4754223f | 450 | |
6a1f0529 PL |
451 | Returns true if the ``bestwho`` IP address is determined to be from |
452 | any of the listed AS numbers. | |
4754223f | 453 | |
6a1f0529 PL |
454 | :param int number: An AS number |
455 | :param [int] numbers: A list of AS numbers | |
4754223f | 456 | |
6a1f0529 PL |
457 | .. function:: country(country) |
458 | country(countries) | |
4754223f | 459 | |
6a1f0529 | 460 | Returns true if the ``bestwho`` IP address of the client is within the |
2d578977 | 461 | two letter ISO country code passed, as described in :doc:`../backends/geoip`. |
975f0839 | 462 | |
6a1f0529 PL |
463 | :param string country: A country code like "NL" |
464 | :param [string] countries: A list of country codes | |
975f0839 | 465 | |
60f9d9a2 | 466 | .. function:: countryCode() |
467 | ||
468 | Returns two letter ISO country code based ``bestwho`` IP address, as described in :doc:`../backends/geoip`. | |
469 | If the two letter ISO country code is unknown "--" will be returned. | |
470 | ||
cc521cc1 PG |
471 | .. function:: region(region) |
472 | region(regions) | |
60f9d9a2 | 473 | |
474 | Returns true if the ``bestwho`` IP address of the client is within the | |
475 | two letter ISO region code passed, as described in :doc:`../backends/geoip`. | |
476 | ||
477 | :param string region: A region code like "CA" | |
478 | :param [string] regions: A list of regions codes | |
479 | ||
480 | .. function:: regionCode() | |
481 | ||
482 | Returns two letter ISO region code based ``bestwho`` IP address, as described in :doc:`../backends/geoip`. | |
483 | If the two letter ISO region code is unknown "--" will be returned. | |
484 | ||
cc521cc1 PG |
485 | .. function:: continent(continent) |
486 | continent(continents) | |
975f0839 | 487 | |
6a1f0529 | 488 | Returns true if the ``bestwho`` IP address of the client is within the |
2d578977 | 489 | continent passed, as described in :doc:`../backends/geoip`. |
4754223f | 490 | |
6a1f0529 PL |
491 | :param string continent: A continent code like "EU" |
492 | :param [string] continents: A list of continent codes | |
25bcfaec | 493 | |
60f9d9a2 | 494 | .. function:: continentCode() |
495 | ||
496 | Returns two letter ISO continent code based ``bestwho`` IP address, as described in :doc:`../backends/geoip`. | |
497 | If the two letter ISO continent code is unknown "--" will be returned. | |
498 | ||
6a1f0529 | 499 | .. function:: netmask(netmasks) |
4754223f | 500 | |
6a1f0529 | 501 | Returns true if ``bestwho`` is within any of the listed subnets. |
4754223f | 502 | |
6a1f0529 | 503 | :param [string] netmasks: The list of IP addresses to check against |
3bf2f94d PD |
504 | |
505 | .. function:: dblookup(name, type) | |
506 | ||
507 | Does a database lookup for name and type, and returns a (possibly empty) array of string results. | |
508 | ||
509 | Please keep the following in mind: | |
510 | ||
511 | * it does not evaluate any LUA code found | |
512 | * if you needed just one string, perhaps you want ``dblookup('www.example.org', 'A')[1]`` to take the first item from the array | |
513 | * some things, like ifurlup, don't like empty tables, so be careful not to accidentally look up a name that does not have any records of that type, if you are going to use the result in ``ifurlup`` | |
514 | ||
515 | Example usage: :: | |
516 | ||
517 | www IN LUA A "ifurlup('https://www.example.com/', {dblookup('www1.example.com', 'A'), dblookup('www2.example.com', 'A'), dblookup('www3.example.com', 'A')})" | |
518 | ||
519 | :param string name: Name to look up in the database | |
520 | :param string type: DNS type to look for |