]>
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 | ||
9 | ``who`` | |
10 | ~~~~~~~ | |
11 | IP address of requesting resolver | |
12 | ||
13 | ||
25bcfaec | 14 | ``ecswho`` |
4754223f | 15 | ~~~~~~~~~~~ |
16 | The EDNS Client Subnet, should one have been set on the query. Unset | |
17 | otherwise. | |
18 | ||
25bcfaec | 19 | ``bestwho`` |
4754223f | 20 | ~~~~~~~~~~~~ |
6a1f0529 | 21 | In absence of ECS, this is set to the IP address of requesting resolver. |
4754223f | 22 | Otherwise set to the network part of the EDNS Client Subnet supplied by the |
23 | resolver. | |
24 | ||
25 | Functions available | |
26 | ------------------- | |
27 | ||
6a1f0529 PL |
28 | Record creation functions |
29 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
4754223f | 30 | |
6a1f0529 | 31 | .. function:: ifportup(portnum, addresses[, options]) |
4754223f | 32 | |
8a28fb38 CHB |
33 | Simplistic test to see if an IP address listens on a certain port. This will |
34 | attempt a TCP connection on port ``portnum`` and consider it UP if the | |
35 | connection establishes, no data will be sent or read on that connection. Note | |
36 | that both IPv4 and IPv6 addresses can be tested, but that it is an error to | |
37 | list IPv4 addresses on an AAAA record, or IPv6 addresses on an A record. | |
25bcfaec | 38 | |
6a1f0529 PL |
39 | Will return a single IP address from the set of available IP addresses. If |
40 | no IP address is available, will return a random element of the set of | |
8a28fb38 | 41 | addresses supplied for testing. |
25bcfaec | 42 | |
6a1f0529 PL |
43 | :param int portnum: The port number to test connections to. |
44 | :param {str} addresses: The list of IP addresses to check connectivity for. | |
45 | :param options: Table of options for this specific check, see below. | |
25bcfaec | 46 | |
6a1f0529 | 47 | Various options can be set in the ``options`` parameter: |
4754223f | 48 | |
707cedf3 CHB |
49 | - ``selector``: used to pick the IP address from list of viable candidates. Choices include 'pickclosest', 'random', 'hashed', 'all' (default to 'random'). |
50 | - ``backupSelector``: used to pick the IP address from list of all candidates if all addresses are down. Choices include 'pickclosest', 'random', 'hashed', 'all' (default to 'random'). | |
6a1f0529 | 51 | - ``source``: Source IP address to check from |
a6897a16 | 52 | - ``timeout``: Maximum time in seconds that you allow the check to take (default 2) |
4754223f | 53 | |
4754223f | 54 | |
6a1f0529 | 55 | .. function:: ifurlup(url, addresses[, options]) |
4754223f | 56 | |
6a1f0529 PL |
57 | More sophisticated test that attempts an actual http(s) connection to |
58 | ``url``. In addition, multiple groups of IP addresses can be supplied. The | |
5daed657 CHB |
59 | first set with a working (available) IP address is used. URL is considered up if |
60 | HTTP response code is 200 and optionally if the content matches ``stringmatch`` | |
61 | option. | |
4754223f | 62 | |
6a1f0529 PL |
63 | :param string url: The url to retrieve. |
64 | :param addresses: List of lists of IP addresses to check the URL on. | |
65 | :param options: Table of options for this specific check, see below. | |
89ff3721 | 66 | |
6a1f0529 | 67 | Various options can be set in the ``options`` parameter: |
89ff3721 | 68 | |
707cedf3 CHB |
69 | - ``selector``: used to pick the IP address from list of viable candidates. Choices include 'pickclosest', 'random', 'hashed', 'all' (default to 'random'). |
70 | - ``backupSelector``: used to pick the IP address from list of all candidates if all addresses are down. Choices include 'pickclosest', 'random', 'hashed', 'all' (default to 'random'). | |
6a1f0529 | 71 | - ``source``: Source IP address to check from |
a6897a16 | 72 | - ``timeout``: Maximum time in seconds that you allow the check to take (default 2) |
6a1f0529 | 73 | - ``stringmatch``: check ``url`` for this string, only declare 'up' if found |
adf5f025 | 74 | - ``useragent``: Set the HTTP "User-Agent" header in the requests. By default it is set to "PowerDNS Authoritative Server" |
89ff3721 | 75 | |
6a1f0529 | 76 | An example of IP address sets: |
89ff3721 | 77 | |
6a1f0529 | 78 | .. code-block:: lua |
89ff3721 | 79 | |
6a1f0529 PL |
80 | ifurlup("example.com", { {"192.0.2.20", "203.0.113.4"}, {"203.0.113.2"} }) |
81 | ||
82 | .. function:: pickrandom(addresses) | |
83 | ||
84 | Returns a random IP address from the list supplied. | |
85 | ||
86 | :param addresses: A list of strings with the possible IP addresses. | |
87 | ||
1bc56192 | 88 | .. function:: pickclosest(addresses) |
6a1f0529 PL |
89 | |
90 | Returns IP address deemed closest to the ``bestwho`` IP address. | |
91 | ||
92 | :param addresses: A list of strings with the possible IP addresses. | |
93 | ||
94 | .. function:: latlon() | |
95 | ||
96 | Returns text listing fractional latitude/longitude associated with the ``bestwho`` IP address. | |
97 | ||
98 | .. function:: latlonloc() | |
99 | ||
100 | Returns text in LOC record format listing latitude/longitude associated with the ``bestwho`` IP address. | |
101 | ||
102 | .. function:: closestMagic() | |
103 | ||
104 | Suitable for use as a wildcard LUA A record. Will parse the query name which should be in format:: | |
105 | ||
106 | 192-0-2-1.192-0-2-2.198-51-100-1.magic.v4.powerdns.org | |
107 | ||
108 | It will then resolve to an A record with the IP address closest to ``bestwho`` from the list | |
109 | of supplied addresses. | |
110 | ||
111 | In the ``magic.v4.powerdns.org`` this looks like:: | |
112 | ||
113 | *.magic.v4.powerdns.org IN LUA A "closestMagic()" | |
114 | ||
115 | ||
116 | In another zone, a record is then present like this:: | |
117 | ||
118 | www-balanced.powerdns.org IN CNAME 192-0-2-1.192-0-2-2.198-51-100-1.magic.v4.powerdns.org | |
119 | ||
120 | This effectively opens up your server to being a 'geographical load balancer as a service'. | |
121 | ||
122 | Performs no uptime checking. | |
123 | ||
124 | .. function:: view(pairs) | |
125 | ||
126 | Shorthand function to implement 'views' for all record types. | |
127 | ||
128 | :param pairs: A list of netmask/result pairs. | |
129 | ||
130 | An example:: | |
131 | ||
132 | view.v4.powerdns.org IN LUA A ("view({ " | |
133 | "{ {'192.168.0.0/16'}, {'192.168.1.54'}}," | |
134 | "{ {'0.0.0.0/0'}, {'192.0.2.1'}} " | |
135 | " }) " ) | |
136 | ||
137 | This will return IP address 192.168.1.54 for queries coming from | |
138 | 192.168.0.0/16, and 192.0.2.1 for all other queries. | |
139 | ||
140 | This function also works for CNAME or TXT records. | |
141 | ||
1bc56192 | 142 | .. function:: pickwhashed(weightparams) |
6a1f0529 PL |
143 | |
144 | Based on the hash of ``bestwho``, returns an IP address from the list | |
145 | supplied, as weighted by the various ``weight`` parameters. | |
146 | Performs no uptime checking. | |
147 | ||
148 | :param weightparams: table of weight, IP addresses. | |
149 | ||
150 | Because of the hash, the same client keeps getting the same answer, but | |
151 | given sufficient clients, the load is still spread according to the weight | |
152 | factors. | |
153 | ||
154 | An example:: | |
155 | ||
1bc56192 CHB |
156 | mydomain.example.com IN LUA A ("pickwhashed({ " |
157 | " {15, "192.0.2.1"}, " | |
158 | " {100, "198.51.100.5"} " | |
159 | "}) ") | |
89ff3721 | 160 | |
161 | ||
1bc56192 | 162 | .. function:: pickwrandom(weightparams) |
89ff3721 | 163 | |
6a1f0529 PL |
164 | Returns a random IP address from the list supplied, as weighted by the |
165 | various ``weight`` parameters. Performs no uptime checking. | |
89ff3721 | 166 | |
6a1f0529 | 167 | :param weightparams: table of weight, IP addresses. |
89ff3721 | 168 | |
1bc56192 | 169 | See :func:`pickwhashed` for an example. |
4754223f | 170 | |
c9fb9a3e | 171 | Reverse DNS functions |
c052aac7 | 172 | ~~~~~~~~~~~~~~~~~~~~~ |
c9fb9a3e | 173 | |
54b7ef3e CS |
174 | .. warning:: |
175 | The reverse DNS functions are under active development. **They may** | |
c9fb9a3e S |
176 | **not be safe for production use.** The syntax of these functions may change at any |
177 | time. | |
178 | ||
179 | .. function:: createReverse(format) | |
180 | ||
54b7ef3e | 181 | Used for generating default hostnames from IPv4 wildcard reverse DNS records, e.g. ``*.0.0.127.in-addr.arpa`` |
c9fb9a3e S |
182 | |
183 | See :func:`createReverse6` for IPv6 records (ip6.arpa) | |
54b7ef3e CS |
184 | |
185 | See :func:`createForward` for creating the A records on a wildcard record such as ``*.static.example.com`` | |
c9fb9a3e S |
186 | |
187 | Returns a formatted hostname based on the format string passed. | |
188 | ||
189 | :param format: A hostname string to format, for example ``%1%.%2%.%3%.%4%.static.example.com``. | |
190 | ||
54b7ef3e CS |
191 | **Formatting options:** |
192 | ||
f404c4c6 GD |
193 | - ``%1%`` to ``%4%`` are individual octets |
194 | - Example record query: ``1.0.0.127.in-addr.arpa`` | |
195 | - ``%1%`` = 127 | |
196 | - ``%2%`` = 0 | |
197 | - ``%3%`` = 0 | |
198 | - ``%4%`` = 1 | |
199 | - ``%5%`` joins the four decimal octets together with dashes | |
200 | - Example: ``%5%.static.example.com`` is equivalent to ``%1%-%2%-%3%-%4%.static.example.com`` | |
201 | - ``%6%`` converts each octet from decimal to hexadecimal and joins them together | |
202 | - Example: A query for ``15.0.0.127.in-addr.arpa`` | |
203 | - ``%6`` would be ``7f00000f`` (127 is 7f, and 15 is 0f in hexadecimal) | |
54b7ef3e CS |
204 | |
205 | **NOTE:** At the current time, only forward dotted format works with :func:`createForward` (i.e. ``127.0.0.1.static.example.com``) | |
c9fb9a3e S |
206 | |
207 | Example records:: | |
208 | ||
209 | *.0.0.127.in-addr.arpa IN LUA PTR "createReverse('%1%.%2%.%3%.%4%.static.example.com')" | |
210 | *.1.0.127.in-addr.arpa IN LUA PTR "createReverse('%5%.static.example.com')" | |
211 | *.2.0.127.in-addr.arpa IN LUA PTR "createReverse('%6%.static.example.com')" | |
212 | ||
213 | When queried:: | |
214 | ||
215 | # -x is syntactic sugar to request the PTR record for an IPv4/v6 address such as 127.0.0.5 | |
216 | # Equivalent to dig PTR 5.0.0.127.in-addr.arpa | |
217 | $ dig +short -x 127.0.0.5 @ns1.example.com | |
218 | 127.0.0.5.static.example.com. | |
219 | $ dig +short -x 127.0.1.5 @ns1.example.com | |
220 | 127-0-0-5.static.example.com. | |
221 | $ dig +short -x 127.0.2.5 @ns1.example.com | |
222 | 7f000205.static.example.com. | |
223 | ||
224 | .. function:: createForward() | |
225 | ||
226 | Used to generate the reverse DNS domains made from :func:`createReverse` | |
227 | ||
228 | Generates an A record for a dotted or hexadecimal IPv4 domain (e.g. 127.0.0.1.static.example.com) | |
229 | ||
230 | It does not take any parameters, it simply interprets the zone record to find the IP address. | |
231 | ||
232 | An example record for zone ``static.example.com``:: | |
233 | ||
234 | *.static.example.com IN LUA A "createForward()" | |
235 | ||
54b7ef3e | 236 | **NOTE:** At the current time, only forward dotted format works for this function (i.e. ``127.0.0.1.static.example.com``) |
c9fb9a3e S |
237 | |
238 | When queried:: | |
239 | ||
240 | $ dig +short A 127.0.0.5.static.example.com @ns1.example.com | |
241 | 127.0.0.5 | |
242 | ||
243 | .. function:: createReverse6(format) | |
244 | ||
54b7ef3e | 245 | Used for generating default hostnames from IPv6 wildcard reverse DNS records, e.g. ``*.1.0.0.2.ip6.arpa`` |
c9fb9a3e S |
246 | |
247 | **For simplicity purposes, only small sections of IPv6 rDNS domains are used in most parts of this guide,** | |
54b7ef3e | 248 | **as a full ip6.arpa record is around 80 characters long** |
c9fb9a3e S |
249 | |
250 | See :func:`createReverse` for IPv4 records (in-addr.arpa) | |
54b7ef3e CS |
251 | |
252 | See :func:`createForward6` for creating the AAAA records on a wildcard record such as ``*.static.example.com`` | |
c9fb9a3e S |
253 | |
254 | Returns a formatted hostname based on the format string passed. | |
255 | ||
256 | :param format: A hostname string to format, for example ``%33%.static6.example.com``. | |
257 | ||
54b7ef3e | 258 | Formatting options: |
c9fb9a3e | 259 | |
f404c4c6 GD |
260 | - ``%1%`` to ``%32%`` are individual characters (nibbles) |
261 | - **Example PTR record query:** ``a.0.0.0.1.0.0.2.ip6.arpa`` | |
262 | - ``%1%`` = 2 | |
263 | - ``%2%`` = 0 | |
264 | - ``%3%`` = 0 | |
265 | - ``%4%`` = 1 | |
266 | - ``%33%`` converts the compressed address format into a dashed format, e.g. ``2001:a::1`` to ``2001-a--1`` | |
267 | - ``%34%`` to ``%41%`` represent the 8 uncompressed 2-byte chunks | |
268 | - **Example:** PTR query for ``2001:a:b::123`` | |
269 | - ``%34%`` - returns ``2001`` (chunk 1) | |
270 | - ``%35%`` - returns ``000a`` (chunk 2) | |
271 | - ``%41%`` - returns ``0123`` (chunk 8) | |
c9fb9a3e | 272 | |
54b7ef3e | 273 | **NOTE:** At the current time, only dashed compressed format works for this function (i.e. ``2001-a-b--1.static6.example.com``) |
c9fb9a3e S |
274 | |
275 | Example records:: | |
276 | ||
277 | *.1.0.0.2.ip6.arpa IN LUA PTR "createReverse('%33%.static6.example.com')" | |
278 | *.2.0.0.2.ip6.arpa IN LUA PTR "createReverse('%34%.%35%.static6.example.com')" | |
279 | ||
280 | When queried:: | |
281 | ||
282 | # -x is syntactic sugar to request the PTR record for an IPv4/v6 address such as 2001::1 | |
283 | # 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 | |
284 | # 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 | |
285 | ||
286 | $ dig +short -x 2001:a:b::1 @ns1.example.com | |
287 | 2001-a-b--1.static6.example.com. | |
288 | ||
289 | $ dig +short -x 2002:a:b::1 @ns1.example.com | |
290 | 2002.000a.static6.example.com | |
291 | ||
292 | .. function:: createForward6() | |
293 | ||
294 | Used to generate the reverse DNS domains made from :func:`createReverse6` | |
295 | ||
54b7ef3e | 296 | Generates an AAAA record for a dashed compressed IPv6 domain (e.g. ``2001-a-b--1.static6.example.com``) |
c9fb9a3e S |
297 | |
298 | It does not take any parameters, it simply interprets the zone record to find the IP address. | |
299 | ||
300 | An example record for zone ``static.example.com``:: | |
301 | ||
302 | *.static6.example.com IN LUA AAAA "createForward6()" | |
303 | ||
54b7ef3e | 304 | **NOTE:** At the current time, only dashed compressed format works for this function (i.e. ``2001-a-b--1.static6.example.com``) |
c9fb9a3e S |
305 | |
306 | When queried:: | |
307 | ||
308 | $ dig +short AAAA 2001-a-b--1.static6.example.com @ns1.example.com | |
309 | 2001:a:b::1 | |
310 | ||
6a1f0529 PL |
311 | Helper functions |
312 | ~~~~~~~~~~~~~~~~ | |
4754223f | 313 | |
6a1f0529 PL |
314 | .. function:: asnum(number) |
315 | asnum(numbers) | |
4754223f | 316 | |
6a1f0529 PL |
317 | Returns true if the ``bestwho`` IP address is determined to be from |
318 | any of the listed AS numbers. | |
4754223f | 319 | |
6a1f0529 PL |
320 | :param int number: An AS number |
321 | :param [int] numbers: A list of AS numbers | |
4754223f | 322 | |
6a1f0529 PL |
323 | .. function:: country(country) |
324 | country(countries) | |
4754223f | 325 | |
6a1f0529 | 326 | Returns true if the ``bestwho`` IP address of the client is within the |
2d578977 | 327 | two letter ISO country code passed, as described in :doc:`../backends/geoip`. |
975f0839 | 328 | |
6a1f0529 PL |
329 | :param string country: A country code like "NL" |
330 | :param [string] countries: A list of country codes | |
975f0839 | 331 | |
6a1f0529 PL |
332 | .. function:: continent(continent) |
333 | continent(continents) | |
975f0839 | 334 | |
6a1f0529 | 335 | Returns true if the ``bestwho`` IP address of the client is within the |
2d578977 | 336 | continent passed, as described in :doc:`../backends/geoip`. |
4754223f | 337 | |
6a1f0529 PL |
338 | :param string continent: A continent code like "EU" |
339 | :param [string] continents: A list of continent codes | |
25bcfaec | 340 | |
6a1f0529 | 341 | .. function:: netmask(netmasks) |
4754223f | 342 | |
6a1f0529 | 343 | Returns true if ``bestwho`` is within any of the listed subnets. |
4754223f | 344 | |
6a1f0529 | 345 | :param [string] netmasks: The list of IP addresses to check against |