<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>7. Scripting</title><link rel="stylesheet" href="docbook.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="PowerDNS manual" /><link rel="up" href="built-in-recursor.html" title="Chapter 17. PowerDNS Recursor: a high performance resolving nameserver" /><link rel="prev" href="recursor-stats.html" title="6. Statistics" /><link rel="next" href="recursor-design-and-engineering.html" title="8. Design and Engineering of the PowerDNS Recursor" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">7. Scripting</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="recursor-stats.html">Prev</a> </td><th width="60%" align="center">Chapter 17. PowerDNS Recursor: a high performance resolving nameserver</th><td width="20%" align="right"> <a accesskey="n" href="recursor-design-and-engineering.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="7. Scripting"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="recursor-scripting"></a>7. Scripting</h2></div></div></div><div class="toc"><dl><dt><span class="sect2"><a href="recursor-scripting.html#idp8531600">7.1. Configuring Lua scripts</a></span></dt><dt><span class="sect2"><a href="recursor-scripting.html#idp8540416">7.2. Writing Lua PowerDNS Recursor scripts</a></span></dt></dl></div><p>
As of version 3.1.7 of the PowerDNS Recursor, it is possible to modify resolving behaviour using simple scripts written in the <a class="ulink" href="http://www.lua.org" target="_top">Lua</a>
programming language.
</p><p>
</p><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="warning.png" /></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>
This functionality is expected to change from version to version as additional scripting needs become apparent!
</p></td></tr></table></div><p>
</p><p>
These scripts can be used to quickly override dangerous domains, for load balancing or for legal or commercial purposes.
</p><p>
As of 3.1.7, queries can be intercepted in two places: before the resolving logic starts to work, plus after the resolving process failed to find
a correct answer for a domain.
</p><div class="sect2" title="7.1. Configuring Lua scripts"><div class="titlepage"><div><div><h3 class="title"><a id="idp8531600"></a>7.1. Configuring Lua scripts</h3></div></div></div><p>
In order to load scripts, the PowerDNS Recursor must have Lua support built in. The packages distributed from the PowerDNS website have this language
enabled, other distributions may differ. To compile with Lua support, use: <code class="literal">LUA=1 make</code> or <code class="literal">LUA=1 gmake</code>
as the case may be. Paths to the Lua include files and binaries may be found near the top of the <code class="filename">Makefile</code>.
</p><p>
If Lua support is available, a script can be configured either via the configuration file, or at runtime via the <span class="command"><strong>rec_control</strong></span> tool.
Scripts can be reloaded or unloaded at runtime with no interruption in operations. If a new script contains syntax errors, the old script remains in force.
</p><p>
On the command line, or in the configuration file, the setting <span class="command"><strong>lua-dns-script</strong></span> can be used to supply a full path to a 'lua' script.
</p><p>
At runtime, <span class="command"><strong>rec_control reload-lua-script</strong></span> can be used to either reload the script from its current location, or, when passed
a new file name, load one from a new location. A failure to parse the new script will leave the old script in working order.
</p><p>
Finally, <span class="command"><strong>rec_control unload-lua-script</strong></span> can be used to remove the currently installed script, and revert to unmodified behaviour.
</p></div><div class="sect2" title="7.2. Writing Lua PowerDNS Recursor scripts"><div class="titlepage"><div><div><h3 class="title"><a id="idp8540416"></a>7.2. Writing Lua PowerDNS Recursor scripts</h3></div></div></div><p>
Once a script is loaded, PowerDNS looks for several functions, as detailed below. All of these functions are optional.
</p><p>
<code class="function">preresolve ( remoteip, domain, qtype )</code> is called before any DNS resolution is attempted, and if this function indicates it, it can supply a direct answer to the
DNS query, overriding the internet. This is useful to combat botnets, or to disable domains unacceptable to an organization for whatever reason.
</p><p>
<code class="function">postresolve ( remoteip, domain, qtype, records, origrcode )</code> is called right before returning a response to a client (and, unless <code class="function">setvariable()</code> is called, to the packet cache too). It allows inspection and modification of almost any detail in the return packet. Available since version 3.4.
</p><p>
<code class="function">function nxdomain ( remoteip, domain, qtype )</code> is called after the DNS resolution process has run its course, but ended in an 'NXDOMAIN' situation, indicating that the domain
or the specific record does not exist. This can be used for various purposes.
</p><p>
<code class="function">function nodata ( remoteip, domain, qtype, records )</code> is just like <code class="function">nxdomain</code>, except it gets called when a domain exists, but the requested type does not. This is where one would implement DNS64. Available since version 3.4.
</p><p>
All these functions are passed the IP address of the requester, plus the name and type being requested. In return, these functions indicate if they
have taken over the request, or want to let normal proceedings take their course.
</p><p>
</p><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="warning.png" /></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>
In development versions of the PowerDNS Recursor, versions which were never released except as for testing purposes, these functions had a fourth parameter: localip
This parameter has been replaced by <code class="function">getlocaladdress()</code>, for which see below.
</p></td></tr></table></div><p>
</p><p>
If a function has taken over a request, it should return an rcode (usually 0), and specify a table with records to be put in the answer section
of a packet. An interesting rcode is NXDOMAIN (3, or <code class="function">pdns.NXDOMAIN</code>), which specifies the non-existence of a domain.
Returning -1 and an empty table signifies that the function chose not to intervene.
</p><p>
A minimal sample script:
</p><p>
</p><pre class="screen">
function nxdomain ( ip, domain, qtype )
print ("nxhandler called for: ", ip, domain, qtype)
ret={}
if qtype ~= pdns.A then return -1, ret end -- only A records
if not string.find(domain, "^www%.") then return -1, ret end -- only things that start with www.
if not matchnetmask(ip, "10.0.0.0/8", "192.168.0.0/16") then return -1, ret end -- only interfere with local queries
ret[1]={qtype=pdns.A, content="127.1.2.3"} -- add IN A 127.1.2.3
ret[2]={qtype=pdns.A, content="127.3.2.1"} -- add IN A 127.3.2.1
setvariable()
return 0, ret -- return no error, plus records
end
</pre><p>
</p><p>
</p><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="warning.png" /></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>
Please do NOT use the above sample script in production! Responsible NXDomain redirection requires more attention to detail.
</p></td></tr></table></div><p>
</p><p>
Note that the domain is passed to the Lua function terminated by a '.'.
A more complete sample script is provided as <code class="filename">powerdns-example-script.lua</code> in the PowerDNS Recursor distribution.
</p><p>
The answer content format is (nearly) identical to the storage in the PowerDNS Authoritative Server database, or as in zone files.
The exception is that, unlike in the database, there is no 'prio' field, which means that an MX record with priority 25 pointing to 'smtp.mailserver.com' would be encoded as
'25 smtp.mailserver.com.'.
</p><p>
Useful return 'rcodes' include 0 for "no error" and <code class="function">pdns.NXDOMAIN</code> for "NXDOMAIN".
</p><p>
Fields that can be set in the return table include:
</p><div class="variablelist"><dl><dt><span class="term">content</span></dt><dd><p>
Content of the record, as specified above in 'zone file format'. No default, mandatory field.
</p></dd><dt><span class="term">place</span></dt><dd><p>
Place of this record. Defaults to 1, indicating 'Answer' section. Can also be 2, for Authority of 3 for Additional.
When using this rare feature, always emit records with 'Place' in ascending order. This field is usually not needed.
</p></dd><dt><span class="term">qname</span></dt><dd><p>
qname of the answer, the 'name' of the record. Defaults to the name of the query, which is almost always correct except when
specifying additional records or rolling out a CNAME chain.
</p></dd><dt><span class="term">qtype</span></dt><dd><p>
Currently the numerical qtype of the answer, defaulting to '1' which is an A record. Can be also be specified as
<code class="function">pdns.A</code>, or <code class="function">pdns.CNAME</code> etc.
</p></dd><dt><span class="term">ttl</span></dt><dd><p>
Time to live of a record. Defaults to 3600. Be sure not to specify differing TTLs within answers with an identical qname. While this
will be encoded in DNS, actual results may be undesired.
</p></dd></dl></div><p>
</p><p>
</p><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="warning.png" /></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>
The result table must have indexes that start at 1! Otherwise the first or confusingly the last entry of the table will
be ignored. A useful technique is to return data using:
<code class="literal">return 0, {{qtype=1, content="1.2.3.4"}, {qtype=1, content="4.3.2.1"}}</code> as this will get the numbering
right automatically.
</p></td></tr></table></div><p>
</p><p>
The function <code class="function">matchnetmask(ip, netmask1, netmask2..)</code> (or <code class="function">matchnetmask(ip, {netmask1, netmask2})</code>) is available to match incoming queries against
a number of netmasks. If any of these match, the function returns true.
</p><p>
To log messages with the main PowerDNS Recursor process, use <code class="function">pdnslog(message)</code>. Available since version 3.2.
</p><p>
To retrieve the IP address on which a query was received, use <code class="function">getlocaladdress()</code>. Available since version 3.2.
</p><p>
To indicate that an answer should not be cached in the packet cache, use <code class="function">setvariable()</code>. Available since version 3.3.
</p><p>
To get fake AAAA records for DNS64 usage, use <code class="function">return "getFakeAAAARecords", domain, "fe80::21b:77ff:0:0"</code>. Available since version 3.4.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="recursor-stats.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="built-in-recursor.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="recursor-design-and-engineering.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6. Statistics </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 8. Design and Engineering of the PowerDNS Recursor</td></tr></table></div></body></html>
