root/trunk/pdns/modules/luabackend/README

====================================
This is the luabackend for PowerDNS!
====================================

Note: shortly before the 3.2 release of PowerDNS, Fredrik Danerklinkt
(author of this Luabackend) opened https://github.com/fredan/luabackend
and is doing development there.


http://www.lua.org for more information about what Lua really is.


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() and getsoa().


------------------------
getarg("your_parameter")
------------------------

This one tries to get the value of the name "lua-your_parameter" from the 
pdns.conf file.


------------------------
mustdo("your_parameter")
------------------------

This is the same as 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 hole 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 script 'pdns' is used to test the server on the ip address '127.0.0.1' with
the port 5300. You should be able to run the following test with the included 
'powerdns-luabackend.lua' file:

$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


=============================
OPTIONS IN THE CONFIGURE FILE
=============================

The default values is:

lua-filename = powerdns-luabackend.lua
lua-logging-query = no

You can also override all the default functionsnames for the luafunctions if you
want. The prefix is lua-f_<functionname>=mynewfunction. 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("my_parameter") and it will return the value
of 'lua-my_parameter'. For boolean you use the function mustdo("my_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_name_of_the_error_function_in_lua>


======
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.


===============
ASKING QUESTION
===============

You can send question about this backend to >dev/null first and if you don't get any 
answer from that you can try to send them to me at fredan-pdns@fredan.org

Fredrik Danerklint.