mirror of
https://github.com/NLnetLabs/unbound.git
synced 2026-09-08 02:47:43 +02:00
- Added generic EDNS code for registering known EDNS option codes,
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
@@ -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.
|
||||
|
||||
@@ -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
|
||||
--------------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user