diff options
Diffstat (limited to 'external/unbound/pythonmod/doc/examples')
| -rw-r--r-- | external/unbound/pythonmod/doc/examples/example0-1.py | 34 | ||||
| -rw-r--r-- | external/unbound/pythonmod/doc/examples/example0.rst | 129 | ||||
| -rw-r--r-- | external/unbound/pythonmod/doc/examples/example1.rst | 46 | ||||
| -rw-r--r-- | external/unbound/pythonmod/doc/examples/example2.rst | 49 | ||||
| -rw-r--r-- | external/unbound/pythonmod/doc/examples/example3.rst | 63 | ||||
| -rw-r--r-- | external/unbound/pythonmod/doc/examples/example4.rst | 178 | ||||
| -rw-r--r-- | external/unbound/pythonmod/doc/examples/example5.rst | 191 | ||||
| -rw-r--r-- | external/unbound/pythonmod/doc/examples/example6.rst | 299 | ||||
| -rw-r--r-- | external/unbound/pythonmod/doc/examples/index.rst | 16 |
9 files changed, 0 insertions, 1005 deletions
diff --git a/external/unbound/pythonmod/doc/examples/example0-1.py b/external/unbound/pythonmod/doc/examples/example0-1.py deleted file mode 100644 index 3b234f1e0..000000000 --- a/external/unbound/pythonmod/doc/examples/example0-1.py +++ /dev/null @@ -1,34 +0,0 @@ - -def init(id, cfg): - log_info("pythonmod: init called, module id is %d port: %d script: %s" % (id, cfg.port, cfg.python_script)) - return True - -def deinit(id): - log_info("pythonmod: deinit called, module id is %d" % id) - return True - -def inform_super(id, qstate, superqstate, qdata): - return True - -def operate(id, event, qstate, qdata): - log_info("pythonmod: operate called, id: %d, event:%s" % (id, strmodulevent(event))) - - if event == MODULE_EVENT_NEW: - qstate.ext_state[id] = MODULE_WAIT_MODULE - return True - - if event == MODULE_EVENT_MODDONE: - log_info("pythonmod: module we are waiting for is done") - qstate.ext_state[id] = MODULE_FINISHED - return True - - if event == MODULE_EVENT_PASS: - log_info("pythonmod: event_pass") - qstate.ext_state[id] = MODULE_ERROR - return True - - log_err("pythonmod: BAD event") - qstate.ext_state[id] = MODULE_ERROR - return True - -log_info("pythonmod: script loaded.") diff --git a/external/unbound/pythonmod/doc/examples/example0.rst b/external/unbound/pythonmod/doc/examples/example0.rst deleted file mode 100644 index 80eca5ea6..000000000 --- a/external/unbound/pythonmod/doc/examples/example0.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. _example_handler: - -Fundamentals -================ - -This basic example shows how to create simple python module which will pass on the requests to the iterator. - -How to enable python module ----------------------------- -If you look into unbound configuration file, you can find the option `module-config` which specifies the names and the order of modules to be used. -Example configuration:: - - module-config: "validator python iterator" - -As soon as the DNS query arrives, Unbound calls modules starting from leftmost - the validator *(it is the first module on the list)*. -The validator does not know the answer *(it can only validate)*, thus it will pass on the event to the next module. -Next module is python which can - - a) generate answer *(response)* - When python module generates the response unbound calls validator. Validator grabs the answer and determines the security flag. - - b) pass on the event to the iterator. - When iterator resolves the query, Unbound informs python module (event :data:`module_event_moddone`). In the end, when the python module is done, validator is called. - -Note that the python module is called with :data:`module_event_pass` event, because new DNS event was already handled by validator. - -Another situation occurs when we use the following configuration:: - - module-config: "python validator iterator" - -Python module is the first module here, so it's invoked with :data:`module_event_new` event *(new query)*. - -On Python module initialization, module loads script from `python-script` option:: - - python-script: "/unbound/test/ubmodule.py" - -Simple python module step by step ---------------------------------- - -Script file must contain four compulsory functions: - -.. function:: init(id, cfg) - - Initialize module internals, like database etc. - Called just once on module load. - - :param id: module identifier (integer) - :param cfg: :class:`config_file` configuration structure - -:: - - def init(id, cfg): - log_info("pythonmod: init called, module id is %d port: %d script: %s" % (id, cfg.port, cfg.python_script)) - return True - - -.. function:: deinit(id) - - Deinitialize module internals. - Called just once on module unload. - - :param id: module identifier (integer) - -:: - - def deinit(id): - log_info("pythonmod: deinit called, module id is %d" % id) - return True - - -.. function:: inform_super(id, qstate, superqstate, qdata) - - Inform super querystate about the results from this subquerystate. - Is called when the querystate is finished. - - :param id: module identifier (integer) - :param qstate: :class:`module_qstate` Query state - :param superqstate: :class:`pythonmod_qstate` Mesh state - :param qdata: :class:`query_info` Query data - -:: - - def inform_super(id, qstate, superqstate, qdata): - return True - - - -.. function:: operate(id, event, qstate, qdata) - - Perform action on pending query. Accepts a new query, or work on pending query. - - You have to set qstate.ext_state on exit. - The state informs unbound about result and controls the following states. - - :param id: module identifier (integer) - :param qstate: :class:`module_qstate` query state structure - :param qdata: :class:`query_info` per query data, here you can store your own data - -:: - - def operate(id, event, qstate, qdata): - log_info("pythonmod: operate called, id: %d, event:%s" % (id, strmodulevent(event))) - if event == MODULE_EVENT_NEW: - qstate.ext_state[id] = MODULE_WAIT_MODULE - return True - - if event == MODULE_EVENT_MODDONE: - qstate.ext_state[id] = MODULE_FINISHED - return True - - if event == MODULE_EVENT_PASS: - qstate.ext_state[id] = MODULE_ERROR - return True - - log_err("pythonmod: BAD event") - qstate.ext_state[id] = MODULE_ERROR - return True - - -Complete source code --------------------- - -.. literalinclude:: example0-1.py - :language: python - -As you can see, the source code is much more flexible in contrast to C modules. -Moreover, compulsory functions called on appropriate module events allows to handle almost -anything from web control to query analysis. - diff --git a/external/unbound/pythonmod/doc/examples/example1.rst b/external/unbound/pythonmod/doc/examples/example1.rst deleted file mode 100644 index ccd76da5a..000000000 --- a/external/unbound/pythonmod/doc/examples/example1.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _log_handler: - -Packet logger -============= - -This example shows how to log and print details about query and response. -As soon as the ``iterator`` has finished (event is -:data:`module_event_moddone`), ``qstate.return_msg`` contains response packet -or ``None``. -This packet will be send to a client that asked for it. - -Complete source code --------------------- - -.. literalinclude:: ../../examples/log.py - :language: python - -Testing -------- -Run the unbound server: - -``root@localhost>unbound -dv -c ./test-log.conf`` - -In case you use own configuration file, don't forget to enable python module: -``module-config: "validator python iterator"`` and use valid script path: -``python-script: "./examples/log.py"``. - -Example of output:: - - [1231790168] unbound[7941:0] info: response for <f.gtld-servers.NET. AAAA IN> - [1231790168] unbound[7941:0] info: reply from <gtld-servers.NET.> 192.5.6.31#53 - [1231790168] unbound[7941:0] info: query response was ANSWER - [1231790168] unbound[7941:0] info: pythonmod: operate called, id: 1, event:module_event_moddone - ---------------------------------------------------------------------------------------------------- - Query: f.gtld-servers.NET., type: AAAA (28), class: IN (1) - ---------------------------------------------------------------------------------------------------- - Return reply :: flags: 8080, QDcount: 1, Security:0, TTL=86400 - qinfo :: qname: ['f', 'gtld-servers', 'NET', ''] f.gtld-servers.NET., qtype: AAAA, qclass: IN - Reply: - 0 : ['gtld-servers', 'NET', ''] gtld-servers.NET. flags: 0000 type: SOA (6) class: IN (1) - 0 : TTL= 86400 - 0x00 | 00 3A 02 41 32 05 4E 53 54 4C 44 03 43 4F 4D 00 05 | . : . A 2 . N S T L D . C O M . . - 0x10 | 05 6E 73 74 6C 64 0C 76 65 72 69 73 69 67 6E 2D 67 | . n s t l d . v e r i s i g n - g - 0x20 | 67 72 73 03 43 4F 4D 00 77 74 2D 64 00 00 0E 10 00 | g r s . C O M . w t - d . . . . . - 0x30 | 00 00 03 84 00 12 75 00 00 01 51 80 | . . . . . . u . . . Q . - diff --git a/external/unbound/pythonmod/doc/examples/example2.rst b/external/unbound/pythonmod/doc/examples/example2.rst deleted file mode 100644 index 4ba9239a0..000000000 --- a/external/unbound/pythonmod/doc/examples/example2.rst +++ /dev/null @@ -1,49 +0,0 @@ -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. - -Complete source code --------------------- - -.. literalinclude:: ../../examples/resgen.py - :language: python - -Testing -------- - -Run the unbound server: - -``root@localhost>unbound -dv -c ./test-resgen.conf`` - -Query for a A record ending with .localdomain - -``dig A test.xxx.localdomain @127.0.0.1`` - -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 - -As we handle (override) in the python module only queries ending with -``localdomain.``, unboud can still resolve host names. diff --git a/external/unbound/pythonmod/doc/examples/example3.rst b/external/unbound/pythonmod/doc/examples/example3.rst deleted file mode 100644 index 6213dc188..000000000 --- a/external/unbound/pythonmod/doc/examples/example3.rst +++ /dev/null @@ -1,63 +0,0 @@ -Response modification -===================== - -This example shows how to modify the response produced by the ``iterator`` module. - -As soon as the iterator module returns the response, we : - -1. invalidate the data in cache -2. modify the response *TTL* -3. rewrite the data in cache -4. return modified packet - -Note that the steps 1 and 3 are neccessary only in case, the python module is the first module in the processing chain. -In other cases, the validator module guarantees updating data which are produced by iterator module. - -Complete source code --------------------- - -.. literalinclude:: ../../examples/resmod.py - :language: python - -Testing -------- - -Run Unbound server: - -``root@localhost>unbound -dv -c ./test-resmod.conf`` - -Issue a query for name ending with "nic.cz." - -``>>>dig A @127.0.0.1 www.nic.cz`` - -:: - - ;; global options: printcmd - ;; Got answer: - ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 48831 - ;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 3, ADDITIONAL: 5 - - ;; QUESTION SECTION: - ;www.nic.cz. IN A - - ;; ANSWER SECTION: - www.nic.cz. 10 IN A 217.31.205.50 - - ;; AUTHORITY SECTION: - nic.cz. 10 IN NS e.ns.nic.cz. - nic.cz. 10 IN NS a.ns.nic.cz. - nic.cz. 10 IN NS c.ns.nic.cz. - - ;; ADDITIONAL SECTION: - a.ns.nic.cz. 10 IN A 217.31.205.180 - a.ns.nic.cz. 10 IN AAAA 2001:1488:dada:176::180 - c.ns.nic.cz. 10 IN A 195.66.241.202 - c.ns.nic.cz. 10 IN AAAA 2a01:40:1000::2 - e.ns.nic.cz. 10 IN A 194.146.105.38 - - ;; Query time: 166 msec - ;; SERVER: 127.0.0.1#53(127.0.0.1) - ;; WHEN: Mon Jan 02 13:39:43 2009 - ;; MSG SIZE rcvd: 199 - -As you can see, TTL of all the records is set to 10. diff --git a/external/unbound/pythonmod/doc/examples/example4.rst b/external/unbound/pythonmod/doc/examples/example4.rst deleted file mode 100644 index 338210990..000000000 --- a/external/unbound/pythonmod/doc/examples/example4.rst +++ /dev/null @@ -1,178 +0,0 @@ -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. - -Key parts ---------- - -Initialization -~~~~~~~~~~~~~~ - -On **init()** module loads dictionary from a text file containing records in -``word [tab] translation`` format. - -:: - - def init(id, cfg): - log_info("pythonmod: dict init") - f = open("examples/dict_data.txt", "r") - ... - -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.]``. -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. - -:: - - aword = ' '.join(qstate.qinfo.qname_list[0:-4]) #skip last four labels - adict = qstate.qinfo.qname_list[-4] #get 4th label from the end - - words = [] #list of words - if (adict == "en") and (aword in en_dict): - words = en_dict[aword] - - 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. - -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) - - 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 - - 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)*. -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)*. -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`. - -**Steps:** - -1. create :class:`DNSMessage` instance -2. append TXT records containing the translation -3. set response to ``qstate.return_msg`` - -Testing -------- - -Run the Unbound server: - -``root@localhost>unbound -dv -c ./test-dict.conf`` - -In case you use own configuration file, don't forget to enable Python module:: - - module-config: "validator python iterator" - -and use valid script path:: - - 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 - -``>>>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 - - 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: - ... - -Complete source code --------------------- - -.. literalinclude:: ../../examples/dict.py - :language: python diff --git a/external/unbound/pythonmod/doc/examples/example5.rst b/external/unbound/pythonmod/doc/examples/example5.rst deleted file mode 100644 index 058fc331e..000000000 --- a/external/unbound/pythonmod/doc/examples/example5.rst +++ /dev/null @@ -1,191 +0,0 @@ -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 diff --git a/external/unbound/pythonmod/doc/examples/example6.rst b/external/unbound/pythonmod/doc/examples/example6.rst deleted file mode 100644 index 07117cd55..000000000 --- a/external/unbound/pythonmod/doc/examples/example6.rst +++ /dev/null @@ -1,299 +0,0 @@ -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, id): - 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, id): - 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, id): - 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, id): - 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 diff --git a/external/unbound/pythonmod/doc/examples/index.rst b/external/unbound/pythonmod/doc/examples/index.rst deleted file mode 100644 index 93d9b8e1e..000000000 --- a/external/unbound/pythonmod/doc/examples/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _Tutorials: - -Examples -======== - -Here you can find several tutorials which clarify the usage and capabilities of -the Unbound scriptable interface. - -Tutorials ---------- - -.. toctree:: - :maxdepth: 2 - :glob: - - example* |