docs/lua-records/functions.rst

   1 Preset variables
   2 ----------------
   3
   4 LUA rules run within the same environment as described in
   5 :doc:`../modes-of-operation`.
   6
   7 The Lua snippets can query the following variables:
   8
   9 ``who``
  10 ~~~~~~~
  11 IP address of requesting resolver
  12
  13
  14 ``ecswho``
  15 ~~~~~~~~~~~
  16 The EDNS Client Subnet, should one have been set on the query. Unset
  17 otherwise.
  18
  19 ``bestwho``
  20 ~~~~~~~~~~~~
  21 In absence of ECS, this is set to the IP address of requesting resolver.
  22 Otherwise set to the network part of the EDNS Client Subnet supplied by the
  23 resolver.
  24
  25 Functions available
  26 -------------------
  27
  28 Record creation functions
  29 ~~~~~~~~~~~~~~~~~~~~~~~~~
  30
  31 .. function:: ifportup(portnum, addresses[, options])
  32
  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.
  38
  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
  41   addresses supplied for testing.
  42
  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.
  46
  47   Various options can be set in the ``options`` parameter:
  48
  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').
  51   - ``source``: Source IP address to check from
  52   - ``timeout``: Maximum time in seconds that you allow the check to take (default 2)
  53
  54
  55 .. function:: ifurlup(url, addresses[, options])
  56
  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
  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.
  62
  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.
  66
  67   Various options can be set in the ``options`` parameter:
  68
  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').
  71   - ``source``: Source IP address to check from
  72   - ``timeout``: Maximum time in seconds that you allow the check to take (default 2)
  73   - ``stringmatch``: check ``url`` for this string, only declare 'up' if found
  74   - ``useragent``: Set the HTTP "User-Agent" header in the requests. By default it is set to "PowerDNS Authoritative Server"
  75
  76   An example of IP address sets:
  77
  78   .. code-block:: lua
  79
  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
  88 .. function:: pickclosest(addresses)
  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
 142 .. function:: pickwhashed(weightparams)
 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
 156     mydomain.example.com    IN    LUA    A ("pickwhashed({                             "
 157                                             "        {15,  "192.0.2.1"},               "
 158                                             "        {100, "198.51.100.5"}             "
 159                                             "})                                        ")
 160
 161
 162 .. function:: pickwrandom(weightparams)
 163
 164   Returns a random IP address from the list supplied, as weighted by the
 165   various ``weight`` parameters. Performs no uptime checking.
 166
 167   :param weightparams: table of weight, IP addresses.
 168
 169   See :func:`pickwhashed` for an example.
 170
 171 Reverse DNS functions
 172 ~~~~~~~~~~~~~~~~~~~~~
 173
 174 .. warning::
 175   The reverse DNS functions are under active development. **They may**
 176   **not be safe for production use.** The syntax of these functions may change at any
 177   time.
 178
 179 .. function:: createReverse(format)
 180
 181   Used for generating default hostnames from IPv4 wildcard reverse DNS records, e.g. ``*.0.0.127.in-addr.arpa``
 182
 183   See :func:`createReverse6` for IPv6 records (ip6.arpa)
 184
 185   See :func:`createForward` for creating the A records on a wildcard record such as ``*.static.example.com``
 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
 191   **Formatting options:**
 192
 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)
 204
 205   **NOTE:** At the current time, only forward dotted format works with :func:`createForward` (i.e. ``127.0.0.1.static.example.com``)
 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
 236   **NOTE:** At the current time, only forward dotted format works for this function (i.e. ``127.0.0.1.static.example.com``)
 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
 245   Used for generating default hostnames from IPv6 wildcard reverse DNS records, e.g. ``*.1.0.0.2.ip6.arpa``
 246
 247   **For simplicity purposes, only small sections of IPv6 rDNS domains are used in most parts of this guide,**
 248   **as a full ip6.arpa record is around 80 characters long**
 249
 250   See :func:`createReverse` for IPv4 records (in-addr.arpa)
 251
 252   See :func:`createForward6` for creating the AAAA records on a wildcard record such as ``*.static.example.com``
 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
 258   Formatting options:
 259
 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)
 272
 273   **NOTE:** At the current time, only dashed compressed format works for this function (i.e. ``2001-a-b--1.static6.example.com``)
 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
 296   Generates an AAAA record for a dashed compressed IPv6 domain (e.g. ``2001-a-b--1.static6.example.com``)
 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
 304   **NOTE:** At the current time, only dashed compressed format works for this function (i.e. ``2001-a-b--1.static6.example.com``)
 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
 311 Helper functions
 312 ~~~~~~~~~~~~~~~~
 313
 314 .. function:: asnum(number)
 315               asnum(numbers)
 316
 317   Returns true if the ``bestwho`` IP address is determined to be from
 318   any of the listed AS numbers.
 319
 320   :param int number: An AS number
 321   :param [int] numbers: A list of AS numbers
 322
 323 .. function:: country(country)
 324               country(countries)
 325
 326   Returns true if the ``bestwho`` IP address of the client is within the
 327   two letter ISO country code passed, as described in :doc:`../backends/geoip`.
 328
 329   :param string country: A country code like "NL"
 330   :param [string] countries: A list of country codes
 331
 332 .. function:: continent(continent)
 333               continent(continents)
 334
 335   Returns true if the ``bestwho`` IP address of the client is within the
 336   continent passed, as described in :doc:`../backends/geoip`.
 337
 338   :param string continent: A continent code like "EU"
 339   :param [string] continents: A list of continent codes
 340
 341 .. function:: netmask(netmasks)
 342
 343   Returns true if ``bestwho`` is within any of the listed subnets.
 344
 345   :param [string] netmasks: The list of IP addresses to check against