From: Pieter Lexis Date: Tue, 9 Dec 2014 18:08:10 +0000 (+0100) Subject: Port port X-Git-Tag: rec-3.7.0-rc1~109^2~4^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d78cded90520344ea3cf058a4552599e59748997;p=thirdparty%2Fpdns.git Port port --- diff --git a/pdns/docs/markdown/authoritative/backend-lua.md b/pdns/docs/markdown/authoritative/backend-lua.md new file mode 100644 index 0000000000..671877008a --- /dev/null +++ b/pdns/docs/markdown/authoritative/backend-lua.md @@ -0,0 +1,158 @@ +# Lua Backend +The most up to date version of this backend can be found at [Fredrik's github](https://github.com/fredan/luabackend). + +The main author for this module is Fredrik Danerklint. + +|   |   | +|:--|:--| +|Native|Yes| +|Master|Yes| +|Slave|No| +|Superslave|No| +|Autoserial|No| +|DNSSEC|Yes| + +**Warning**: The Lua Backend is available since PowerDNS Authoritative Server 3.0. In 3.0 and 3.1, this backend is marked as Experimental! + +This backend is just a "glue" between PowerDNS and your own Lua application. + +What this means is that you can not have a working setup that can serve you +dns-questions directly from start. What you need to do is to program your own +backend completely in Lua! Which database server to use etc is now up to you! + +What you have here is the possibility to make your own "dns-server" without the +knowledge of programming in c/c++. + +There is one thing that needs to be said. Remember that each thread +PowerDNS launches of this backend is completely different so they cannot +share information between each other! + +You will need some kind of a database that can be shared for this. + +All the functionnames that PowerDNS accept for a backend should be the same +in your Lua script, in lowercase. Also, the parameters should be in the same +order. Where there is a structure in c/c++ there is a table in the Lua backend. +This is also true for return values. A few functions expect that you return a +table in a table. + + +## New functions +There is a couple of new functions for you to use in Lua: + +### `logger(log_facility, "your", "messages")` + +All these `log_facilities` is available: +* `log_all` +* `log_ntlog` +* `log_alert` +* `log_critical` +* `log_error` +* `log_warning` +* `log_notice,` +* `log_info` +* `log_debug` +* `log_none` + + +### `dnspacket()` +This will give you back three parameters with +`remote_ip`, `remote_port` and `local_ip` in that order. + +Can only be used in the functions [`list()`](#list) and [`getsoa()`](#getsoa). + +### `getarg("PARAMETER")` +This one tries to get the value of the name `"lua-PARAMETER"` from the +pdns.conf file. + +### `mustdo("PARAMETER")` +This is the same as [`getarg()`](#getarg) but return a boolean instead of a string. + +You also have all the different QTypes in a table called 'QTypes'. + +# What has been tested +The only functionality of the minimal functions except zone-transfer has +been tested. + +In the included powerdns-luabackend.lua file there is a example of how +this can be done. Note that this is more or less a static example since +there is no possibility for each thread to know when something has changed. + +However, you can run `pdns_control reload` and it should reload the whole thing +from scratch (does not work for the moment, PowerDNS only calls two thread with +the reload command - not all of them). + +# What you will find under the test directory +The following script can be used to test the server: +```{include='../../modules/luabackend/test/powerdns-luabackend.lua'} +``` + +This will yield the following result: + +``` +$dig any www.test.com @127.0.0.1 -p5300 +multiline +; <<>> DiG 9.7.3 <<>> any www.test.com @127.0.0.1 -p5300 +multiline +;; global options: +cmd +;; Got answer: +;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 1001 +;; flags: qr aa rd; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0 +;; WARNING: recursion requested but not available + +;; QUESTION SECTION: +;www.test.com. IN ANY + +;; ANSWER SECTION: +www.test.com. 120 IN CNAME host.test.com. +host.test.com. 120 IN A 10.11.12.13 +host.test.com. 120 IN AAAA 1:2:3:4:5:6:7:8 + +;; Query time: 1 msec +;; SERVER: 127.0.0.1#5300(127.0.0.1) +;; WHEN: Thu Jun 2 22:19:56 2011 +;; MSG SIZE rcvd: 93 +``` + +# Parameters +## `lua-filename` +Path to your lua script, 'powerdns-luabackend.lua' by default. + +## `lua-logging-query` +Log queries. default is 'no'. + +## `lua-f_FUNCTION=NEWFUNCTION` +You can also override all the default functionsnames for the luafunctions if you +want. For example: + +`lua-f_lookup = mynewfunction` + +will call the function `mynewfunction` for the lookup-routine. + +If you want your own configuration parameters you can have that too. +Just call the function `getarg("PARAMETER")` and it will return the value +of `lua-PARAMETER`. For boolean you use the function `mustdo("PARAMETER")`. + +## Your own error function in lua +You can have an error function in Lua when Lua gives back a error. + +First make your error function then you put this in `pdns.conf`: + +`lua-f_exec_error = YOUR_METHOD` + +# DNSSEC +You can have full dnssec support in our Lua application. You should note the +following regarding this: + +You don't have to implement the function 'updateDNSSECOrderAndAuth' since the +default code will work correctly for you via the backend itself. + +The functions activateDomainKey and deactivateDomainKey can be implemented via a +new function called updateDomainKey, which has three parameters (the other two +has only two parameters) where the third is a boolean which is true or false +depending on which function that was called from the beginning. + +# Information for logging +If you have the parameter `query-logging` or `lua-logging-query` set to +true/yes/on, then you will see what is happening in each function when PowerDNS +calls them. + +This can, hopefully, help you with some debugging if you run into some kind of +trouble with your Lua application. diff --git a/pdns/docs/mkdocs.yml b/pdns/docs/mkdocs.yml index 0f0beab0cb..5d3b10263d 100644 --- a/pdns/docs/mkdocs.yml +++ b/pdns/docs/mkdocs.yml @@ -34,6 +34,7 @@ pages: - [authoritative/backend-geoip.md, 'Authoritative Backends', 'GeoIP'] - [authoritative/backend-gsqlite.md, 'Authoritative Backends', 'Generic SQLite'] - [authoritative/backend-ldap.md, 'Authoritative Backends', 'LDAP'] + - [authoritative/backend-lua.md, 'Authoritative Backends', 'LUA'] - [authoritative/backend-lmdb.md, 'Authoritative Backends', 'LMDB'] - [authoritative/backend-oracle.md, 'Authoritative Backends', 'Oracle'] - [authoritative/backend-pipe.md, 'Authoritative Backends', 'Pipe']