WEBDIENSTE/unbound
1
0
Fork 0
mirror of https://github.com/NLnetLabs/unbound.git synced 2026-09-13 13:27:43 +02:00
Code Issues Packages Projects Releases Wiki Activity

- Added generic EDNS code for registering known EDNS option codes,

Browse Source 
bypassing the cache response stage and uniquifying mesh states. Four EDNS
  option lists were added to module_qstate (module_qstate.edns_opts_*) to
  store EDNS options from/to front/back side.
- Added two flags to module_qstate (no_cache_lookup, no_cache_store) that
  control the modules' cache interactions.
- Added code for registering inplace callback functions. The registered
  functions can be called just before replying with local data or Chaos,
  replying from cache, replying with SERVFAIL, replying with a resolved
  query, sending a query to a nameserver. The functions can inspect the
  available data and maybe change response/query related data (i.e. append
  EDNS options).
- Updated Python module for the above.
- Updated Python documentation.



git-svn-id: file:///svn/unbound/trunk@3947 be551aaa-1e26-0410-a405-d3ace91eadb9
This commit is contained in:
George Thessalonikefs
2016-12-06 13:42:51 +00:00
parent 3e1ff464f1
commit 7b948b0647
59 changed files with 3393 additions and 732 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pythonmod/doc/conf.py
+4 -1
View File
@@ -80,10 +80,13 @@ pygments_style = 'sphinx'
# Options for HTML output
# -----------------------
# The theme that the html output should use.
html_theme = "classic"
# The style sheet to use for HTML and HTML Help pages. A file of that name
# must exist either in Sphinx' static/ path, or in one of the custom paths
# given in html_static_path.
html_style = 'default.css'
#html_style = 'default.css'
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
pythonmod/doc/examples/example2.rst
+23 -20
View File
@@ -1,12 +1,14 @@
Response generation
=====================
===================
This example shows how to handle queries and generate response packet.
.. note::
If the python module is the first module and validator module is enabled (``module-config: "python validator iterator"``),
a return_msg security flag has to be set at least to 2. Leaving security flag untouched causes that the
response will be refused by unbound worker as unbound will consider it as non-valid response.
If the python module is the first module and validator module is enabled
(``module-config: "python validator iterator"``), a return_msg security flag
has to be set at least to 2. Leaving security flag untouched causes that the
response will be refused by unbound worker as unbound will consider it as
non-valid response.
Complete source code
--------------------
@@ -27,20 +29,21 @@ Query for a A record ending with .localdomain
Dig produces the following output::
;; global options: printcmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 48426
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;test.xxx.localdomain. IN A
;; ANSWER SECTION:
test.xxx.localdomain. 10 IN A 127.0.0.1
;; Query time: 2 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Jan 01 12:46:02 2009
;; MSG SIZE rcvd: 54
;; global options: printcmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 48426
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
As we handle (override) in python module only queries ending with "localdomain.", the unboud can still resolve host names.
;; QUESTION SECTION:
;test.xxx.localdomain. IN A
;; ANSWER SECTION:
test.xxx.localdomain. 10 IN A 127.0.0.1
;; Query time: 2 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Jan 01 12:46:02 2009
;; MSG SIZE rcvd: 54
As we handle (override) in the python module only queries ending with
``localdomain.``, unboud can still resolve host names.
pythonmod/doc/examples/example4.rst
+96 -82
View File
@@ -1,15 +1,19 @@
DNS-based language dictionary
===============================
=============================
This example shows how to create a simple language dictionary based on **DNS**
service within 15 minutes. The translation will be performed using TXT resource records.
service within 15 minutes. The translation will be performed using TXT resource
records.
Key parts
-----------
---------
Initialization
~~~~~~~~~~~~~~~~~~~~~~~
On **init()** module loads dictionary from a text file containing records in ``word [tab] translation`` format.
~~~~~~~~~~~~~~
On **init()** module loads dictionary from a text file containing records in
``word [tab] translation`` format.
::
def init(id, cfg):
@@ -20,11 +24,14 @@ On **init()** module loads dictionary from a text file containing records in ``w
The suitable file can be found at http://slovnik.zcu.cz
DNS query and word lookup
~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~
Let's define the following format od DNS queries: ``word1[.]word2[.] ... wordN[.]{en,cs}[._dict_.cz.]``.
Let's define the following format od DNS queries:
``word1[.]word2[.] ... wordN[.]{en,cs}[._dict_.cz.]``.
Word lookup is done by simple ``dict`` lookup from broken DNS request.
Query name is divided into a list of labels. This list is accessible as qname_list attribute.
Query name is divided into a list of labels. This list is accessible as
``qname_list`` attribute.
::
aword = ' '.join(qstate.qinfo.qname_list[0:-4]) #skip last four labels
@@ -37,35 +44,40 @@ Query name is divided into a list of labels. This list is accessible as qname_li
if (adict == "cs") and (aword in cz_dict):
words = cz_dict[aword] # CS -> EN
In the first step, we get a string in the form: ``word1[space]word2[space]...word[space]``.
In the second assignment, fourth label from the end is obtained. This label should contains *"cs"* or *"en"*.
This label determines the direction of translation.
In the first step, we get a string in the form:
``word1[space]word2[space]...word[space]``.
In the second assignment, fourth label from the end is obtained. This label
should contains *"cs"* or *"en"*. This label determines the direction of
translation.
Forming of a DNS reply
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~
DNS reply is formed only on valid match and added as TXT answer.
::
msg = DNSMessage(qstate.qinfo.qname_str, RR_TYPE_TXT, RR_CLASS_IN, PKT_AA)
msg = DNSMessage(qstate.qinfo.qname_str, RR_TYPE_TXT, RR_CLASS_IN, PKT_AA)
for w in words:
msg.answer.append("%s 300 IN TXT \"%s\"" % (qstate.qinfo.qname_str, w.replace("\"", "\\\"")))
for w in words:
msg.answer.append("%s 300 IN TXT \"%s\"" % (qstate.qinfo.qname_str, w.replace("\"", "\\\"")))
if not msg.set_return_msg(qstate):
qstate.ext_state[id] = MODULE_ERROR
return True
if not msg.set_return_msg(qstate):
qstate.ext_state[id] = MODULE_ERROR
return True
qstate.return_rcode = RCODE_NOERROR
qstate.ext_state[id] = MODULE_FINISHED
return True
qstate.return_rcode = RCODE_NOERROR
qstate.ext_state[id] = MODULE_FINISHED
return True
In the first step, a :class:`DNSMessage` instance is created for a given query *(type TXT)*.
In the first step, a :class:`DNSMessage` instance is created for a given query
*(type TXT)*.
The fourth argument specifies the flags *(authoritative answer)*.
In the second step, we append TXT records containing the translation *(on the right side of RR)*.
In the second step, we append TXT records containing the translation *(on the
right side of RR)*.
Then, the response is finished and ``qstate.return_msg`` contains new response.
If no error, the module sets :attr:`module_qstate.return_rcode` and :attr:`module_qstate.ext_state`.
If no error, the module sets :attr:`module_qstate.return_rcode` and
:attr:`module_qstate.ext_state`.
**Steps:**
@@ -82,80 +94,82 @@ Run the Unbound server:
In case you use own configuration file, don't forget to enable Python module::
module-config: "validator python iterator"
module-config: "validator python iterator"
and use valid script path::
python-script: "./examples/dict.py"
python-script: "./examples/dict.py"
The translation from english word *"a bar fly"* to Czech can be done by doing:
``>>>dig TXT @127.0.0.1 a.bar.fly.en._dict_.cz``
::
::
; (1 server found)
;; global options: printcmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 48691
;; flags: aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;a.bar.fly.en._dict_.cz. IN TXT
;; ANSWER SECTION:
a.bar.fly.en._dict_.cz. 300 IN TXT "barov\253 povale\232"
;; Query time: 5 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Jan 01 17:44:18 2009
;; MSG SIZE rcvd: 67
; (1 server found)
;; global options: printcmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 48691
;; flags: aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;a.bar.fly.en._dict_.cz. IN TXT
;; ANSWER SECTION:
a.bar.fly.en._dict_.cz. 300 IN TXT "barov\253 povale\232"
;; Query time: 5 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Jan 01 17:44:18 2009
;; MSG SIZE rcvd: 67
``>>>dig TXT @127.0.0.1 nic.cs._dict_.cz``
::
; <<>> DiG 9.5.0-P2 <<>> TXT @127.0.0.1 nic.cs._dict_.cz
; (1 server found)
;; global options: printcmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 58710
;; flags: aa rd ra; QUERY: 1, ANSWER: 6, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;nic.cs._dict_.cz. IN TXT
;; ANSWER SECTION:
nic.cs._dict_.cz. 300 IN TXT "aught"
nic.cs._dict_.cz. 300 IN TXT "naught"
nic.cs._dict_.cz. 300 IN TXT "nihil"
nic.cs._dict_.cz. 300 IN TXT "nix"
nic.cs._dict_.cz. 300 IN TXT "nothing"
nic.cs._dict_.cz. 300 IN TXT "zilch"
;; Query time: 0 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Jan 01 17:45:39 2009
;; MSG SIZE rcvd: 143
; <<>> DiG 9.5.0-P2 <<>> TXT @127.0.0.1 nic.cs._dict_.cz
; (1 server found)
;; global options: printcmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 58710
;; flags: aa rd ra; QUERY: 1, ANSWER: 6, AUTHORITY: 0, ADDITIONAL: 0
Proof that the unbound still works as resolver.
;; QUESTION SECTION:
;nic.cs._dict_.cz. IN TXT
;; ANSWER SECTION:
nic.cs._dict_.cz. 300 IN TXT "aught"
nic.cs._dict_.cz. 300 IN TXT "naught"
nic.cs._dict_.cz. 300 IN TXT "nihil"
nic.cs._dict_.cz. 300 IN TXT "nix"
nic.cs._dict_.cz. 300 IN TXT "nothing"
nic.cs._dict_.cz. 300 IN TXT "zilch"
;; Query time: 0 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Jan 01 17:45:39 2009
;; MSG SIZE rcvd: 143
Proof that the unbound still works as resolver.
``>>>dig A @127.0.0.1 www.nic.cz``
::
; (1 server found)
;; global options: printcmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 19996
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 3, ADDITIONAL: 5
;; QUESTION SECTION:
;www.nic.cz. IN A
;; ANSWER SECTION:
www.nic.cz. 1662 IN A 217.31.205.50
;; AUTHORITY SECTION:
...
; (1 server found)
;; global options: printcmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 19996
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 3, ADDITIONAL: 5
;; QUESTION SECTION:
;www.nic.cz. IN A
;; ANSWER SECTION:
www.nic.cz. 1662 IN A 217.31.205.50
;; AUTHORITY SECTION:
...
Complete source code
--------------------
pythonmod/doc/examples/example5.rst
+191
View File
@@ -0,0 +1,191 @@
EDNS options
============
This example shows how to interact with EDNS options.
When quering unbound with the EDNS option ``65001`` and data ``0xc001`` we
expect an answer with the same EDNS option code and data ``0xdeadbeef``.
Key parts
~~~~~~~~~
This example relies on the following functionalities:
Registering EDNS options
------------------------
By registering EDNS options we can tune unbound's behavior when encountering a
query with a known EDNS option. The two available options are:
- ``bypass_cache_stage``: If set to ``True`` unbound will not try to answer
from cache. Instead execution is passed to the modules
- ``no_aggregation``: If set to ``True`` unbound will consider this query
unique and will not aggregate it with similar queries
Both values default to ``False``.
.. code-block:: python
if not register_edns_option(env, 65001, bypass_cache_stage=True,
no_aggregation=True):
log_info("python: Could not register EDNS option {}".format(65001))
EDNS option lists
-----------------
EDNS option lists can be found in the :class:`module_qstate` class. There are
four available lists in total:
- :class:`module_qstate.edns_opts_front_in`: options that came from the client
side. **Should not** be changed
- :class:`module_qstate.edns_opts_back_out`: options that will be sent to the
server side. Can be populated by edns literate modules
- :class:`module_qstate.edns_opts_back_in`: options that came from the server
side. **Should not** be changed
- :class:`module_qstate.edns_opts_front_out`: options that will be sent to the
client side. Can be populated by edns literate modules
Each list element has the following members:
- ``code``: the EDNS option code;
- ``data``: the EDNS option data.
Reading an EDNS option list
...........................
The lists' contents can be accessed in python by their ``_iter`` counterpart as
an iterator:
.. code-block:: python
if not edns_opt_list_is_empty(qstate.edns_opts_front_in):
for o in qstate.edns_opts_front_in_iter:
log_info("python: Code: {}, Data: '{}'".format(o.code,
"".join('{:02x}'.format(x) for x in o.data)))
Writing to an EDNS option list
..............................
By appending to an EDNS option list we can add new EDNS options. The new
element is going to be allocated in :class:`module_qstate.region`. The data
**must** be represented with a python ``bytearray``:
.. code-block:: python
b = bytearray.fromhex("deadbeef")
if not edns_opt_list_append(qstate.edns_opts_front_out,
o.code, b, qstate.region):
log_info("python: Could not append EDNS option {}".format(o.code))
We can also remove an EDNS option code from an EDNS option list.
.. code-block:: python
if not edns_opt_list_remove(edns_opt_list, code):
log_info("python: Option code {} was not found in the "
"list.".format(code))
.. note:: All occurences of the EDNS option code will be removed from the list:
Controlling other modules' cache behavior
-----------------------------------------
During the modules' operation, some modules may interact with the cache
(e.g., iterator). This behavior can be controlled by using the following
:class:`module_qstate` flags:
- :class:`module_qstate.no_cache_lookup`: Modules *operating after* this module
will not lookup the cache for an answer
- :class:`module_qstate.no_cache_store`: Modules *operating after* this module
will not store the response in the cache
Both values default to ``0``.
.. code-block:: python
def operate(id, event, qstate, qdata):
if (event == MODULE_EVENT_NEW) or (event == MODULE_EVENT_PASS):
# Detect if edns option code 56001 is present from the client side. If
# so turn on the flags for cache management.
if not edns_opt_list_is_empty(qstate.edns_opts_front_in):
log_info("python: searching for edns option code 65001 during NEW "
"or PASS event ")
for o in qstate.edns_opts_front_in_iter:
if o.code == 65001:
log_info("python: found edns option code 65001")
# Instruct other modules to not lookup for an
# answer in the cache.
qstate.no_cache_lookup = 1
log_info("python: enabled no_cache_lookup")
# Instruct other modules to not store the answer in
# the cache.
qstate.no_cache_store = 1
log_info("python: enabled no_cache_store")
Testing
~~~~~~~
Run the Unbound server: ::
root@localhost$ unbound -dv -c ./test-edns.conf
In case you use your own configuration file, don't forget to enable the Python
module::
module-config: "validator python iterator"
and use a valid script path::
python-script: "./examples/edns.py"
Quering with EDNS option ``65001:0xc001``:
::
root@localhost$ dig @localhost nlnetlabs.nl +ednsopt=65001:c001
; <<>> DiG 9.10.3-P4-Ubuntu <<>> @localhost nlnetlabs.nl +ednsopt=65001:c001
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 33450
;; flags: qr rd ra ad; QUERY: 1, ANSWER: 1, AUTHORITY: 4, ADDITIONAL: 3
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
; OPT=65001: de ad be ef ("....")
;; QUESTION SECTION:
;nlnetlabs.nl. IN A
;; ANSWER SECTION:
nlnetlabs.nl. 10200 IN A 185.49.140.10
;; AUTHORITY SECTION:
nlnetlabs.nl. 10200 IN NS anyns.pch.net.
nlnetlabs.nl. 10200 IN NS ns.nlnetlabs.nl.
nlnetlabs.nl. 10200 IN NS ns-ext1.sidn.nl.
nlnetlabs.nl. 10200 IN NS sec2.authdns.ripe.net.
;; ADDITIONAL SECTION:
ns.nlnetlabs.nl. 10200 IN AAAA 2a04:b900::8:0:0:60
ns.nlnetlabs.nl. 10200 IN A 185.49.140.60
;; Query time: 10 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Dec 05 14:50:56 CET 2016
;; MSG SIZE rcvd: 212
Complete source code
~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/edns.py
:language: python
pythonmod/doc/examples/example6.rst
+299
View File
@@ -0,0 +1,299 @@
Inplace callbacks
=================
This example shows how to register and use inplace callback functions. These
functions are going to be called just before unbound replies back to a client.
They can perform certain actions without interrupting unbound's execution flow
(e.g. add/remove EDNS options, manipulate the reply).
Two different scenarios will be shown:
- If answering from cache and the client used EDNS option code ``65002`` we
will answer with the same code but with data ``0xdeadbeef``;
- When answering with a SERVFAIL we also add an empty EDNS option code
``65003``.
Key parts
~~~~~~~~~
This example relies on the following functionalities:
Registering inplace callback functions
--------------------------------------
There are four types of inplace callback functions:
- `inplace callback reply functions`_
- `inplace callback reply_cache functions`_
- `inplace callback reply_local functions`_
- `inplace callback reply_servfail functions`_
Inplace callback reply functions
................................
Called when answering with a *resolved* query.
The callback function's prototype is the following:
.. code-block:: python
def inplace_reply_callback(qinfo, qstate, rep, rcode, edns, opt_list_out, region):
"""Function that will be registered as an inplace callback function.
It will be called when answering with a resolved query.
:param qinfo: query_info struct;
:param qstate: module qstate. It contains the available opt_lists; It
SHOULD NOT be altered;
:param rep: reply_info struct;
:param rcode: return code for the query;
:param edns: edns_data to be sent to the client side. It SHOULD NOT be
altered;
:param opt_list_out: the list with the EDNS options that will be sent as a
reply. It can be populated with EDNS options;
:param region: region to allocate temporary data. Needs to be used when we
want to append a new option to opt_list_out.
:return: True on success, False on failure.
"""
.. note:: The function's name is irrelevant.
We can register such function as:
.. code-block:: python
if not register_inplace_cb_reply(inplace_reply_callback, env):
log_info("python: Could not register inplace callback function.")
Inplace callback reply_cache functions
......................................
Called when answering *from cache*.
The callback function's prototype is the following:
.. code-block:: python
def inplace_cache_callback(qinfo, qstate, rep, rcode, edns, opt_list_out, region):
"""Function that will be registered as an inplace callback function.
It will be called when answering from the cache.
:param qinfo: query_info struct;
:param qstate: module qstate. None;
:param rep: reply_info struct;
:param rcode: return code for the query;
:param edns: edns_data sent from the client side. The list with the EDNS
options is accesible through edns.opt_list. It SHOULD NOT be
altered;
:param opt_list_out: the list with the EDNS options that will be sent as a
reply. It can be populated with EDNS options;
:param region: region to allocate temporary data. Needs to be used when we
want to append a new option to opt_list_out.
:return: True on success, False on failure.
"""
.. note:: The function's name is irrelevant.
We can register such function as:
.. code-block:: python
if not register_inplace_cb_reply_cache(inplace_cache_callback, env):
log_info("python: Could not register inplace callback function.")
Inplace callback reply_local functions
......................................
Called when answering with *local data* or a *Chaos(CH) reply*.
The callback function's prototype is the following:
.. code-block:: python
def inplace_local_callback(qinfo, qstate, rep, rcode, edns, opt_list_out, region):
"""Function that will be registered as an inplace callback function.
It will be called when answering from local data.
:param qinfo: query_info struct;
:param qstate: module qstate. None;
:param rep: reply_info struct;
:param rcode: return code for the query;
:param edns: edns_data sent from the client side. The list with the
EDNS options is accesible through edns.opt_list. It
SHOULD NOT be altered;
:param opt_list_out: the list with the EDNS options that will be sent as a
reply. It can be populated with EDNS options;
:param region: region to allocate temporary data. Needs to be used when we
want to append a new option to opt_list_out.
:return: True on success, False on failure.
"""
.. note:: The function's name is irrelevant.
We can register such function as:
.. code-block:: python
if not register_inplace_cb_reply_local(inplace_local_callback, env):
log_info("python: Could not register inplace callback function.")
Inplace callback reply_servfail functions
.........................................
Called when answering with *SERVFAIL*.
The callback function's prototype is the following:
.. code-block:: python
def inplace_servfail_callback(qinfo, qstate, rep, rcode, edns, opt_list_out, region):
"""Function that will be registered as an inplace callback function.
It will be called when answering with SERVFAIL.
:param qinfo: query_info struct;
:param qstate: module qstate. If not None the relevant opt_lists are
available here;
:param rep: reply_info struct. None;
:param rcode: return code for the query. LDNS_RCODE_SERVFAIL;
:param edns: edns_data to be sent to the client side. If qstate is None
edns.opt_list contains the EDNS options sent from the client
side. It SHOULD NOT be altered;
:param opt_list_out: the list with the EDNS options that will be sent as a
reply. It can be populated with EDNS options;
:param region: region to allocate temporary data. Needs to be used when we
want to append a new option to opt_list_out.
:return: True on success, False on failure.
"""
.. note:: The function's name is irrelevant.
We can register such function as:
.. code-block:: python
if not register_inplace_cb_reply_servfail(inplace_servfail_callback, env):
log_info("python: Could not register inplace callback function.")
Testing
~~~~~~~
Run the Unbound server: ::
root@localhost$ unbound -dv -c ./test-inplace_callbacks.conf
In case you use your own configuration file, don't forget to enable the Python
module::
module-config: "validator python iterator"
and use a valid script path ::
python-script: "./examples/inplace_callbacks.py"
On the first query for the nlnetlabs.nl A record we get no EDNS option back:
::
root@localhost$ dig @localhost nlnetlabs.nl +ednsopt=65002
; <<>> DiG 9.10.3-P4-Ubuntu <<>> @localhost nlnetlabs.nl +ednsopt=65002
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 48057
;; flags: qr rd ra ad; QUERY: 1, ANSWER: 1, AUTHORITY: 4, ADDITIONAL: 3
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;nlnetlabs.nl. IN A
;; ANSWER SECTION:
nlnetlabs.nl. 10200 IN A 185.49.140.10
;; AUTHORITY SECTION:
nlnetlabs.nl. 10200 IN NS ns.nlnetlabs.nl.
nlnetlabs.nl. 10200 IN NS sec2.authdns.ripe.net.
nlnetlabs.nl. 10200 IN NS anyns.pch.net.
nlnetlabs.nl. 10200 IN NS ns-ext1.sidn.nl.
;; ADDITIONAL SECTION:
ns.nlnetlabs.nl. 10200 IN A 185.49.140.60
ns.nlnetlabs.nl. 10200 IN AAAA 2a04:b900::8:0:0:60
;; Query time: 813 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Dec 05 16:15:32 CET 2016
;; MSG SIZE rcvd: 204
When we issue the same query again we get a cached response and the expected
``65002: 0xdeadbeef`` EDNS option:
::
root@localhost$ dig @localhost nlnetlabs.nl +ednsopt=65002
; <<>> DiG 9.10.3-P4-Ubuntu <<>> @localhost nlnetlabs.nl +ednsopt=65002
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 26489
;; flags: qr rd ra ad; QUERY: 1, ANSWER: 1, AUTHORITY: 4, ADDITIONAL: 3
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
; OPT=65002: de ad be ef ("....")
;; QUESTION SECTION:
;nlnetlabs.nl. IN A
;; ANSWER SECTION:
nlnetlabs.nl. 10197 IN A 185.49.140.10
;; AUTHORITY SECTION:
nlnetlabs.nl. 10197 IN NS ns.nlnetlabs.nl.
nlnetlabs.nl. 10197 IN NS sec2.authdns.ripe.net.
nlnetlabs.nl. 10197 IN NS anyns.pch.net.
nlnetlabs.nl. 10197 IN NS ns-ext1.sidn.nl.
;; ADDITIONAL SECTION:
ns.nlnetlabs.nl. 10197 IN AAAA 2a04:b900::8:0:0:60
ns.nlnetlabs.nl. 10197 IN A 185.49.140.60
;; Query time: 0 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Dec 05 16:50:04 CET 2016
;; MSG SIZE rcvd: 212
By issuing a query for a bogus domain unbound replies with SERVFAIL and an
empty EDNS option code ``65003``. *For this example to work unbound needs to be
validating*:
::
root@localhost$ dig @localhost bogus.nlnetlabs.nl txt
; <<>> DiG 9.10.3-P4-Ubuntu <<>> @localhost bogus.nlnetlabs.nl txt
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: SERVFAIL, id: 19865
;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 1
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
; OPT=65003
;; QUESTION SECTION:
;bogus.nlnetlabs.nl. IN TXT
;; Query time: 11 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Dec 05 17:06:01 CET 2016
;; MSG SIZE rcvd: 51
Complete source code
~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/inplace_callbacks.py
:language: python
pythonmod/doc/examples/index.rst
+10 -9
View File
@@ -1,15 +1,16 @@
.. _Tutorials:
==============================
Examples
========
Here you can find several tutorials which clarify the usage and capabilities of
the Unbound scriptable interface.
Tutorials
==============================
Here you can find several tutorials which clarify the usage and capabilities of Unbound scriptable interface.
`Tutorials`
---------
.. toctree::
:maxdepth: 2
:glob:
:maxdepth: 2
:glob:
example*
example*
pythonmod/doc/install.rst
+25 -19
View File
@@ -1,39 +1,44 @@
Installation
===================================
============
**Prerequisites**
Prerequisites
-------------
Python 2.4 or higher, SWIG 1.3 or higher, GNU make
**Download**
Download
--------
You can download the source codes `here`_.
The latest release is 1.1.1, Jan 15, 2009.
.. _here: unbound-1.1.1-py.tar.gz
**Compiling**
Compiling
---------
After downloading, you can compile the Unbound library by doing::
> tar -xzf unbound-1.1.1-py.tar.gz
> cd unbound-1.1.1
> ./configure --with-pythonmodule
> make
> tar -xzf unbound-1.1.1-py.tar.gz
> cd unbound-1.1.1
> ./configure --with-pythonmodule
> make
You need GNU make to compile sources.
SWIG and Python devel libraries to compile extension module.
**Testing**
Testing
-------
If the compilation is successful, you can test the extension module by::
> cd pythonmod
> make sudo # or "make test" or "make suexec"
> cd pythonmod
> make sudo # or "make test" or "make suexec"
This will start unbound server with language dictionary service (see :ref:`Tutorials`).
This will start unbound server with language dictionary service
(see :ref:`Tutorials`).
In order to test this service, type::
> dig TXT @127.0.0.1 aught.en._dict_.cz
Dig should print this message (czech equivalent of aught)::
@@ -44,16 +49,17 @@ Dig should print this message (czech equivalent of aught)::
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 30085
;; flags: aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;aught.en._dict_.cz. IN TXT
;aught.en._dict_.cz. IN TXT
;; ANSWER SECTION:
aught.en._dict_.cz. 300 IN TXT "nic"
aught.en._dict_.cz. 300 IN TXT "nic"
;; Query time: 11 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Thu Jan 10 16:45:58 2009
;; MSG SIZE rcvd: 52
The ``pythonmod/examples`` directory contains simple applications written in Python.
The ``pythonmod/examples`` directory contains simple applications written in
Python.
pythonmod/doc/modules/functions.rst
+123 -16
View File
@@ -7,25 +7,26 @@ Network
.. function:: ntohs(netshort)
This subroutine converts values between the host and network byte order.
Specifically, **ntohs()** converts 16-bit quantities from network byte order to host byte order.
Specifically, **ntohs()** converts 16-bit quantities from network byte order
to host byte order.
:param netshort: 16-bit short addr
:rtype: converted addr
Cache
-----
.. function:: storeQueryInCache(qstate, qinfo, msgrep, is_referral)
Store pending query in local cache.
:param qstate: :class:`module_qstate`
:param qinfo: :class:`query_info`
:param msgrep: :class:`reply_info`
:param is_referal: integer
:rtype: boolean
.. function:: invalidateQueryInCache(qstate, qinfo)
Invalidate record in local cache.
@@ -34,6 +35,111 @@ Cache
:param qinfo: :class:`query_info`
EDNS options
------------
.. function:: register_edns_option(env, code, bypass_cache_stage=False, no_aggregation=False)
Register EDNS option code.
:param env: :class:`module_env`
:param code: option code(integer)
:param bypass_cache_stage: whether to bypass the cache response stage
:param no_aggregation: whether this query should be unique
:return: ``1`` if successful, ``0`` otherwise
:rtype: integer
.. function:: edns_opt_list_find(list, code)
Find the EDNS option code in the EDNS option list.
:param list: linked list of :class:`edns_option`
:param code: option code (integer)
:return: the edns option if found or None
:rtype: :class:`edns_option` or None
.. function:: edns_opt_list_remove(list, code);
Remove an ENDS option code from the list.
.. note:: All :class:`edns_option` with the code will be removed
:param list: linked list of :class:`edns_option`
:param code: option code (integer)
:return: ``1`` if at least one :class:`edns_option` was removed, ``0`` otherwise
:rtype: integer
.. function:: edns_opt_list_append(list, code, data, region)
Append given EDNS option code with data to the list.
:param list: linked list of :class:`edns_option`
:param code: option code (integer)
:param data: EDNS data. **Must** be a :class:`bytearray`
:param region: :class:`regional`
.. function:: edns_opt_list_is_empty(list)
Check if an EDNS option list is empty.
:param list: linked list of :class:`edns_option`
:return: ``1`` if list is empty, ``0`` otherwise
:rtype: integer
Inplace callbacks
-----------------
.. function:: inplace_cb_reply(qinfo, qstate, rep, rcode, edns, opt_list_out, region)
Function prototype for callback functions used in
`register_inplace_cb_reply`_, `register_inplace_cb_reply_cache`_,
`register_inplace_cb_reply_local` and `register_inplace_cb_reply_servfail`.
:param qinfo: :class:`query_info`
:param qstate: :class:`module_qstate`
:param rep: :class:`reply_info`
:param rcode: return code (integer), check ``RCODE_`` constants.
:param edns: :class:`edns_data`
:param opt_list_out: :class:`edns_option`. EDNS option list to append options to.
:param region: :class:`regional`
.. function:: register_inplace_cb_reply(py_cb, env)
Register py_cb as an inplace reply callback function.
:param py_cb: Python function that follows `inplace_cb_reply`_'s prototype. **Must** be callable.
:param env: :class:`module_env`
:return: True on success, False otherwise
:rtype: boolean
.. function:: register_inplace_cb_reply_cache(py_cb, env)
Register py_cb as an inplace reply_cache callback function.
:param py_cb: Python function that follows `inplace_cb_reply`_'s prototype. **Must** be callable.
:param env: :class:`module_env`
:return: True on success, False otherwise
:rtype: boolean
.. function:: register_inplace_cb_reply_local(py_cb, env)
Register py_cb as an inplace reply_local callback function.
:param py_cb: Python function that follows `inplace_cb_reply`_'s prototype. **Must** be callable.
:param env: :class:`module_env`
:return: True on success, False otherwise
:rtype: boolean
.. function:: register_inplace_cb_reply_servfail(py_cb, env)
Register py_cb as an inplace reply_servfail callback function.
:param py_cb: Python function that follows `inplace_cb_reply`_'s prototype. **Must** be callable.
:param env: :class:`module_env`
:return: True on success, False otherwise
:rtype: boolean
Logging
-------
@@ -71,50 +177,51 @@ Logging
:param msg: string desc to accompany the hexdump.
:param data: data to dump in hex format.
:param length: length of data.
.. function:: log_dns_msg(str, qinfo, reply)
Log DNS message.
:param str: string message
:param qinfo: :class:`query_info`
:param reply: :class:`reply_info`
.. function:: log_query_info(verbosity_value, str, qinf)
Log query information.
:param verbosity_value: see constants
:param str: string message
:param qinf: :class:`query_info`
.. function:: regional_log_stats(r)
Log regional statistics.
:param r: :class:`regional`
Debugging
---------
.. function:: strextstate(module_ext_state)
Debug utility, module external qstate to string.
:param module_ext_state: the state value.
:rtype: descriptive string.
.. function:: strmodulevent(module_event)
Debug utility, module event to string.
:param module_event: the module event value.
:rtype: descriptive string.
.. function:: ldns_rr_type2str(atype)
Convert RR type to string.
.. function:: ldns_rr_class2str(aclass)
Convert RR class to string.
pythonmod/doc/modules/struct.rst
+138 -49
View File
@@ -6,55 +6,94 @@ module_qstate
.. class:: module_qstate
Module state, per query.
This class provides these data attributes:
.. attribute:: qinfo
(:class:`query_info`) Informations about query being answered. Name, RR type, RR class.
.. attribute:: query_flags
(uint16) Flags for query. See QF_BIT\_ predefined constants.
.. attribute:: is_priming
If this is a (stub or root) priming query (with hints).
.. attribute:: reply
comm_reply contains server replies.
.. attribute:: return_msg
(:class:`dns_msg`) The reply message, with message for client and calling module (read-only attribute).
Note that if you want to create of modify return_msg you should use :class:`DNSMessage`.
.. attribute:: return_rcode
The rcode, in case of error, instead of a reply message. Determines whether the return_msg contains reply.
.. attribute:: region
Region for this query. Cleared when query process finishes.
.. attribute:: curmod
Which module is executing.
.. attribute:: ext_state[]
Module states.
.. attribute:: env
Environment for this query.
.. attribute:: mesh_info
Mesh related information for this query.
Module state, per query.
This class provides these data attributes:
.. attribute:: qinfo
(:class:`query_info`) Informations about query being answered. Name, RR type, RR class.
.. attribute:: query_flags
(uint16) Flags for query. See QF_BIT\_ predefined constants.
.. attribute:: is_priming
If this is a (stub or root) priming query (with hints).
.. attribute:: reply
comm_reply contains server replies.
.. attribute:: return_msg
(:class:`dns_msg`) The reply message, with message for client and calling module (read-only attribute).
Note that if you want to create of modify return_msg you should use :class:`DNSMessage`.
.. attribute:: return_rcode
The rcode, in case of error, instead of a reply message. Determines whether the return_msg contains reply.
.. attribute:: region
Region for this query. Cleared when query process finishes.
.. attribute:: curmod
Which module is executing.
.. attribute:: ext_state[]
Module states.
.. attribute:: env
Environment for this query.
.. attribute:: mesh_info
Mesh related information for this query.
.. attribute:: edns_opts_front_in
Incoming EDNS options from the front end.
.. attribute:: edns_opts_front_in_iter
Iterator for `edns_opts_front_in`.
.. attribute:: edns_opts_back_out
Outgoing EDNS options to the back end.
.. attribute:: edns_opts_back_out_iter
Iterator for `edns_opts_back_out`.
.. attribute:: edns_opts_back_in
Incoming EDNS options from the back end.
.. attribute:: edns_opts_back_in_iter
Iterator for `ends_opts_back_in`.
.. attribute:: edns_opts_front_out
Outgoing EDNS options to the front end.
.. attribute:: edns_opts_front_out_iter
Iterator for `edns_opts_front_out`.
.. attribute:: no_cache_lookup
Flag to indicate whether modules should answer from the cache.
.. attribute:: no_cache_store
Flag to indicate whether modules should store answer in the cache.
query_info
----------------
@@ -94,7 +133,57 @@ query_info
.. attribute:: qclass_str
The ``qclass`` in display presentation format (string).
edns_data
---------
.. class:: edns_data
This class represents the EDNS information parsed/encoded from/to a packet. It provides these data attributes:
.. attribute:: edns_present
If EDNS OPT record is present.
.. attribute:: ext_rcode
Extended RCODE.
.. attribute:: edns_version
The EDNS version number.
.. attribute:: bits
The EDNS bits field from ttl (host order): Z.
.. attribute:: udp_size
UDP reassembly size.
.. attribute:: opt_list
The EDNS option list.
.. attribute:: opt_list_iter
Iterator for `opt_list`.
edns_option
-----------
.. class:: edns_option
This class represents an EDNS option (code, data) found in EDNS option lists. It provides these data attributes:
.. attribute:: code
The EDNS option code.
.. attribute:: data
The EDNS option data.
reply_info
--------------------