diff options
Diffstat (limited to 'contrib/unbound/libunbound/python/doc')
20 files changed, 807 insertions, 0 deletions
diff --git a/contrib/unbound/libunbound/python/doc/_static/readme b/contrib/unbound/libunbound/python/doc/_static/readme new file mode 100644 index 0000000..db676ae --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/_static/readme @@ -0,0 +1 @@ +this directory exists to pacify sphinx-build. diff --git a/contrib/unbound/libunbound/python/doc/conf.py b/contrib/unbound/libunbound/python/doc/conf.py new file mode 100644 index 0000000..97fca21 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/conf.py @@ -0,0 +1,181 @@ +# -*- coding: utf-8 -*- +# +# Unbound documentation build configuration file +# +# This file is execfile()d with the current directory set to its containing dir. +# +# The contents of this file are pickled, so don't put values in the namespace +# that aren't pickleable (module imports are okay, they're removed automatically). +# +# All configuration values have a default value; values that are commented out +# serve to show the default value. + +import sys, os + +# If your extensions are in another directory, add it here. If the directory +# is relative to the documentation root, use os.path.abspath to make it +# absolute, like shown here. +sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__),'../'))) +sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__),'../../../'))) +sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__),'../../../.libs/'))) +#print sys.path + +# General configuration +# --------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General substitutions. +project = 'pyUnbound' +copyright = '2009, Zdenek Vasicek, Marek Vavrusa' + +# The default replacements for |version| and |release|, also used in various +# other places throughout the built documents. +# +# The short X.Y version. +version = '1.0' +# The full version, including alpha/beta/rc tags. +release = '1.0.0' + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directories, that shouldn't be searched +# for source files. +#exclude_dirs = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# Options for HTML output +# ----------------------- + +# 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' + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (within the static path) to place at the top of +# the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +html_use_modindex = False + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, the reST sources are included in the HTML build as _sources/<name>. +html_copy_source = False + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Unbounddoc' + + +# Options for LaTeX output +# ------------------------ + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, document class [howto/manual]). +latex_documents = [ + ('index', 'Unbound.tex', 'Unbound Documentation', + 'Zdenek Vasicek, Marek Vavrusa', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True diff --git a/contrib/unbound/libunbound/python/doc/examples/example1a.rst b/contrib/unbound/libunbound/python/doc/examples/example1a.rst new file mode 100644 index 0000000..3c81547 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example1a.rst @@ -0,0 +1,26 @@ +.. _example_resolve_name: + +============================== +Resolve a name +============================== + +This basic example shows how to create a context and resolve a host address (DNS record of A type). + +:: + + #!/usr/bin/python + import unbound + + ctx = unbound.ub_ctx() + ctx.resolvconf("/etc/resolv.conf") + + status, result = ctx.resolve("www.google.com") + if status == 0 and result.havedata: + print "Result.data:", result.data.address_list + elif status != 0: + print "Resolve error:", unbound.ub_strerror(status) + +In contrast with C API, the source code is more compact while the performance of C implementation is preserved. +The main advantage is that you need not take care about the deallocation and allocation of context and result structures; pyUnbound module do it automatically for you. + +If only domain name is given, the :meth:`unbound.ub_ctx.resolve` looks for A records in IN class. diff --git a/contrib/unbound/libunbound/python/doc/examples/example1b.rst b/contrib/unbound/libunbound/python/doc/examples/example1b.rst new file mode 100644 index 0000000..ea1e6f5 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example1b.rst @@ -0,0 +1,33 @@ +.. _example_reverse_lookup: + +============================== +Reverse DNS lookup +============================== + +Reverse DNS lookup involves determining the hostname associated with a given IP address. +This example shows how reverse lookup can be done using unbound module. + +For the reverse DNS records, the special domain in-addr.arpa is reserved. +For example, a host name for the IP address 74.125.43.147 can be obtained by issuing a DNS query for the PTR record for address 147.43.125.74.in-addr.arpa. + +:: + + #!/usr/bin/python + import unbound + + ctx = unbound.ub_ctx() + ctx.resolvconf("/etc/resolv.conf") + + status, result = ctx.resolve(unbound.reverse("74.125.43.147") + ".in-addr.arpa.", unbound.RR_TYPE_PTR, unbound.RR_CLASS_IN) + if status == 0 and result.havedata: + print "Result.data:", result.data.domain_list + elif status != 0: + print "Resolve error:", unbound.ub_strerror(status) + +In order to simplify the python code, unbound module contains function which reverses the hostname components. +This function is defined as follows:: + + def reverse(domain): + return '.'.join([a for a in domain.split(".")][::-1]) + + diff --git a/contrib/unbound/libunbound/python/doc/examples/example2.rst b/contrib/unbound/libunbound/python/doc/examples/example2.rst new file mode 100644 index 0000000..c009ec1 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example2.rst @@ -0,0 +1,41 @@ +.. _example_setup_ctx: + +============================== +Lookup from threads +============================== + +This example shows how to use unbound module from a threaded program. +In this example, three lookup threads are created which work in background. +Each thread resolves different DNS record. + +:: + + #!/usr/bin/python + from unbound import ub_ctx, RR_TYPE_A, RR_CLASS_IN + from threading import Thread + + ctx = ub_ctx() + ctx.resolvconf("/etc/resolv.conf") + + class LookupThread(Thread): + def __init__(self,ctx, name): + Thread.__init__(self) + self.ctx = ctx + self.name = name + + def run(self): + print "Thread lookup started:",self.name + status, result = self.ctx.resolve(self.name, RR_TYPE_A, RR_CLASS_IN) + if status == 0 and result.havedata: + print " Result:",self.name,":", result.data.address_list + + threads = [] + for name in ["www.fit.vutbr.cz","www.vutbr.cz","www.google.com"]: + thread = LookupThread(ctx, name) + thread.start() + threads.append(thread) + + for thread in threads: + thread.join() + + diff --git a/contrib/unbound/libunbound/python/doc/examples/example3.rst b/contrib/unbound/libunbound/python/doc/examples/example3.rst new file mode 100644 index 0000000..9136033 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example3.rst @@ -0,0 +1,36 @@ +.. _example_asynch: + +============================== +Asynchronous lookup +============================== + +This example performs the name lookup in the background. +The main program keeps running while the name is resolved. + +:: + + #!/usr/bin/python + import time + import unbound + + ctx = unbound.ub_ctx() + ctx.resolvconf("/etc/resolv.conf") + + def call_back(my_data,status,result): + print "Call_back:", my_data + if status == 0 and result.havedata: + print "Result:", result.data.address_list + my_data['done_flag'] = True + + + my_data = {'done_flag':False,'arbitrary':"object"} + status, async_id = ctx.resolve_async("www.seznam.cz", my_data, call_back, unbound.RR_TYPE_A, unbound.RR_CLASS_IN) + + while (status == 0) and (not my_data['done_flag']): + status = ctx.process() + time.sleep(0.1) + + if (status != 0): + print "Resolve error:", unbound.ub_strerror(status) + +The :meth:`unbound.ub_ctx.resolve_async` method is able to pass on any Python object. In this example, we used a dictionary object `my_data`. diff --git a/contrib/unbound/libunbound/python/doc/examples/example4.rst b/contrib/unbound/libunbound/python/doc/examples/example4.rst new file mode 100644 index 0000000..996ef4e --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example4.rst @@ -0,0 +1,34 @@ +.. _example_examine: + +============================== +DNSSEC validator +============================== + +This example program performs DNSSEC validation of a DNS lookup. + +:: + + #!/usr/bin/python + import os + from unbound import ub_ctx,RR_TYPE_A,RR_CLASS_IN + + ctx = ub_ctx() + ctx.resolvconf("/etc/resolv.conf") + if (os.path.isfile("keys")): + ctx.add_ta_file("keys") #read public keys for DNSSEC verification + + status, result = ctx.resolve("www.nic.cz", RR_TYPE_A, RR_CLASS_IN) + if status == 0 and result.havedata: + + print "Result:", result.data.address_list + + if result.secure: + print "Result is secure" + elif result.bogus: + print "Result is bogus" + else: + print "Result is insecure" + +More detailed informations can be seen in libUnbound DNSSEC tutorial `here`_. + +.. _here: http://www.unbound.net/documentation/libunbound-tutorial-6.html diff --git a/contrib/unbound/libunbound/python/doc/examples/example5.rst b/contrib/unbound/libunbound/python/doc/examples/example5.rst new file mode 100644 index 0000000..0a31d9a --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example5.rst @@ -0,0 +1,29 @@ +.. _example_resolver_only: + +============================== +Resolver only +============================== + +This example program shows how to perform DNS resolution only. +Unbound contains two basic modules: resolver and validator. +In case, the validator is not necessary, the validator module can be turned off using "module-config" option. +This option contains a list of module names separated by the space char. This list determined which modules should be employed and in what order. + +:: + + #!/usr/bin/python + import os + from unbound import ub_ctx,RR_TYPE_A,RR_CLASS_IN + + ctx = ub_ctx() + ctx.set_option("module-config:","iterator") + ctx.resolvconf("/etc/resolv.conf") + + status, result = ctx.resolve("www.google.com", RR_TYPE_A, RR_CLASS_IN) + if status == 0 and result.havedata: + + print "Result:", result.data.address_list + +.. note:: + The :meth:`unbound.ub_ctx.set_option` method must be used before the first resolution (i.e. before :meth:`unbound.ub_ctx.resolve` or :meth:`unbound.ub_ctx.resolve_async` call). + diff --git a/contrib/unbound/libunbound/python/doc/examples/example6-1.py b/contrib/unbound/libunbound/python/doc/examples/example6-1.py new file mode 100644 index 0000000..0f40544 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example6-1.py @@ -0,0 +1,27 @@ +#!/usr/bin/python +from unbound import ub_ctx,ub_strerror,RR_TYPE_A,RR_CLASS_IN + +ctx = ub_ctx() +ctx.resolvconf("/etc/resolv.conf") + +status, result = ctx.resolve("test.record.xxx", RR_TYPE_A, RR_CLASS_IN) +if status == 0 and result.havedata: + print "Result:", result.data.address_list +else: + print "No record found" + +#define new local zone +status = ctx.zone_add("xxx.","static") +if (status != 0): print "Error zone_add:",status, ub_strerror(status) + +#add RR to the zone +status = ctx.data_add("test.record.xxx. IN A 1.2.3.4") +if (status != 0): print "Error data_add:",status, ub_strerror(status) + +#lookup for an A record +status, result = ctx.resolve("test.record.xxx", RR_TYPE_A, RR_CLASS_IN) +if status == 0 and result.havedata: + print "Result:", result.data.as_address_list() +else: + print "No record found" + diff --git a/contrib/unbound/libunbound/python/doc/examples/example6.rst b/contrib/unbound/libunbound/python/doc/examples/example6.rst new file mode 100644 index 0000000..478e139 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example6.rst @@ -0,0 +1,11 @@ +.. _example_localzone: + +============================== +Local zone manipulation +============================== + +This example program shows how to define local zone containing custom DNS records. + +.. literalinclude:: example6-1.py + :language: python + diff --git a/contrib/unbound/libunbound/python/doc/examples/example7-1.py b/contrib/unbound/libunbound/python/doc/examples/example7-1.py new file mode 100644 index 0000000..802bd1c --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example7-1.py @@ -0,0 +1,17 @@ +#!/usr/bin/python +# vim:fileencoding=utf-8 +# +# IDN (Internationalized Domain Name) lookup support +# +import unbound + +ctx = unbound.ub_ctx() +ctx.resolvconf("/etc/resolv.conf") + +status, result = ctx.resolve(u"www.háčkyčárky.cz", unbound.RR_TYPE_A, unbound.RR_CLASS_IN) +if status == 0 and result.havedata: + print "Result:" + print " raw data:", result.data + for k in result.data.address_list: + print " address:%s" % k + diff --git a/contrib/unbound/libunbound/python/doc/examples/example7-2.py b/contrib/unbound/libunbound/python/doc/examples/example7-2.py new file mode 100644 index 0000000..5a41f8d --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example7-2.py @@ -0,0 +1,16 @@ +#!/usr/bin/python +# vim:fileencoding=utf-8 +# +# IDN (Internationalized Domain Name) lookup support (lookup for MX) +# +import unbound + +ctx = unbound.ub_ctx() +ctx.resolvconf("/etc/resolv.conf") + +status, result = ctx.resolve(u"háčkyčárky.cz", unbound.RR_TYPE_MX, unbound.RR_CLASS_IN) +if status == 0 and result.havedata: + print "Result:" + print " raw data:", result.data + for k in result.data.mx_list_idn: + print " priority:%d address:%s" % k diff --git a/contrib/unbound/libunbound/python/doc/examples/example7.rst b/contrib/unbound/libunbound/python/doc/examples/example7.rst new file mode 100644 index 0000000..d405021 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example7.rst @@ -0,0 +1,18 @@ +.. _example_idna: + +================================================= +Internationalized domain name support +================================================= + +Unlike the libUnbound, pyUnbound is able to handle IDN queries. + +.. literalinclude:: example7-1.py + :language: python + +If we use unicode string in :meth:`unbound.ub_ctx.resolve` method, the IDN DNAME conversion (if it is necessary) is performed on background. + +.. literalinclude:: example7-2.py + :language: python + +The :class:`unbound.ub_data` class contains attributes suffix which converts the dname to UTF string. These attributes have the '_idn' suffix. +Apart from this aproach, two conversion functions exist (:func:`unbound.idn2dname` and :func:`unbound.dname2idn`). diff --git a/contrib/unbound/libunbound/python/doc/examples/example8-1.py b/contrib/unbound/libunbound/python/doc/examples/example8-1.py new file mode 100644 index 0000000..7906016 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example8-1.py @@ -0,0 +1,31 @@ +#!/usr/bin/python +# vim:fileencoding=utf-8 +# +# Lookup for MX and NS records +# +import unbound + +ctx = unbound.ub_ctx() +ctx.resolvconf("/etc/resolv.conf") + +status, result = ctx.resolve("nic.cz", unbound.RR_TYPE_MX, unbound.RR_CLASS_IN) +if status == 0 and result.havedata: + print "Result:" + print " raw data:", result.data + for k in result.data.mx_list: + print " priority:%d address:%s" % k + +status, result = ctx.resolve("nic.cz", unbound.RR_TYPE_A, unbound.RR_CLASS_IN) +if status == 0 and result.havedata: + print "Result:" + print " raw data:", result.data + for k in result.data.address_list: + print " address:%s" % k + +status, result = ctx.resolve("nic.cz", unbound.RR_TYPE_NS, unbound.RR_CLASS_IN) +if status == 0 and result.havedata: + print "Result:" + print " raw data:", result.data + for k in result.data.domain_list: + print " host: %s" % k + diff --git a/contrib/unbound/libunbound/python/doc/examples/example8.rst b/contrib/unbound/libunbound/python/doc/examples/example8.rst new file mode 100644 index 0000000..8cdfcdc --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/example8.rst @@ -0,0 +1,28 @@ +.. _example_mxlookup: + +================================================= +Lookup for MX and NS records +================================================= + +The pyUnbound extension provides functions which are able to encode RAW RDATA produces by unbound resolver (see :class:`unbound.ub_data`). + +.. literalinclude:: example8-1.py + :language: python + +Previous example produces following output:: + + Result: + raw data: 00 0F 05 6D 61 69 6C 34 03 6E 69 63 02 63 7A 00;00 14 02 6D 78 05 63 7A 6E 69 63 03 6F 72 67 00;00 0A 04 6D 61 69 6C 03 6E 69 63 02 63 7A 00 + priority:15 address: mail4.nic.cz. + priority:20 address: mx.cznic.org. + priority:10 address: mail.nic.cz. + + Result: + raw data: D9 1F CD 32 + address: 217.31.205.50 + + Result: + raw data: 01 61 02 6E 73 03 6E 69 63 02 63 7A 00;01 65 02 6E 73 03 6E 69 63 02 63 7A 00;01 63 02 6E 73 03 6E 69 63 02 63 7A 00 + host: a.ns.nic.cz. + host: e.ns.nic.cz. + host: c.ns.nic.cz. diff --git a/contrib/unbound/libunbound/python/doc/examples/index.rst b/contrib/unbound/libunbound/python/doc/examples/index.rst new file mode 100644 index 0000000..c2c9cf4 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/examples/index.rst @@ -0,0 +1,14 @@ +Examples +============================== + +Here you can find several examples which utilizes the unbound library in Python environment. +Unbound is a caching validator and resolver and can be linked into an application, as a library where can answer DNS queries for the application. +This set of examples shows how to use the functions from Python environment. + +`Tutorials` + +.. toctree:: + :maxdepth: 1 + :glob: + + example* diff --git a/contrib/unbound/libunbound/python/doc/index.rst b/contrib/unbound/libunbound/python/doc/index.rst new file mode 100644 index 0000000..b42e052 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/index.rst @@ -0,0 +1,27 @@ +PyUnbound documentation +======================================= + +This project contains an Unbound wrapper providing the thinnest layer over the library possible. +Everything you can do from the libUnbound C API, you can do from Python, even more. + +Contents +---------- +.. toctree:: + :maxdepth: 2 + + intro.rst + install.rst + examples/index.rst + modules/unbound + +Module Documentation +----------------------- + +* Module :mod:`unbound` + +Indices and tables +------------------- + +* :ref:`genindex` +* :ref:`search` + diff --git a/contrib/unbound/libunbound/python/doc/install.rst b/contrib/unbound/libunbound/python/doc/install.rst new file mode 100644 index 0000000..f638ed1 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/install.rst @@ -0,0 +1,31 @@ +Installation +=================================== + +**Prerequisites** + +Python 2.4 or higher, SWIG 1.3 or higher, GNU make + +**Compiling** + +After downloading, you can compile the pyUnbound library by doing:: + + > tar -xzf unbound-x.x.x-py.tar.gz + > cd unbound-x.x.x + > ./configure --with-pyunbound + > make + +You may want to --with-pythonmodule as well if you want to use python as +a module in the resolver. + +You need GNU make to compile sources; SWIG and Python devel libraries to compile extension module. + + +**Testing** + +If the compilation is successfull, you can test the python LDNS extension module by:: + + > cd contrib/python + > make testenv + > ./dns-lookup.py + +You may want to make install in the main directory since make testenv is for debugging. In contrib/examples you can find simple applications written in Python using the Unbound extension. diff --git a/contrib/unbound/libunbound/python/doc/intro.rst b/contrib/unbound/libunbound/python/doc/intro.rst new file mode 100644 index 0000000..f751f54 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/intro.rst @@ -0,0 +1,39 @@ +Introduction +=================================== + +**Unbound** + + `Unbound`_ is an implementation of a DNS resolver, that performs caching and DNSSEC validation. + Together with unbound, the libunbound library is provided. + This library can be used to convert hostnames to ip addresses, and back, as well as obtain other information. + Since the resolver allows to specify the class and type of a query (A record, NS, MX, ...), this library offers powerful resolving tool. + The library also performs public-key validation of results with DNSSEC. + + .. _Unbound: http://www.unbound.net/documentation + +**pyUnbound** + + The pyUnbound is an extension module for Python which provides an object-oriented interface to libunbound. + It is the first Python module which offers thread-safe caching resolver. + + The interface was designed with the emphasis on the simplicity of use. + There are two main classes :class:`unbound.ub_ctx` (a validation and resolution context) and :class:`unbound.ub_result` which contains the validation and resolution results. + The objects are thread-safe, and a context can be used in non-threaded as well as threaded environment. + Resolution can be performed blocking and non-blocking (i.e. asynchronous). + The asynchronous method returns from the call immediately, so that processing can go on, while the results become available later. + +**Features** + * customizable caching validation resolver for synchronous and asynchronous lookups + * easy to use object interface + * easy to integrate extension module + * designed for thread environment (i.e. thread-safe) + * allows define and customize of local zone and its RR's during the operation (i.e. without restart) + * includes encoding functions to simplify the results retrieval + * Internationalized domain name (`IDN`_) support + + .. _IDN: http://en.wikipedia.org/wiki/Internationalized_domain_name + +**Application area** + * DNS-based applications performing DNS lookups; the caching resolver can reduce overhead + * Applications where the validation of DNS records is required + * Great solution for customizable and dynamic DNS-based white/blacklists (spam rejection, connection rejection, ...) using the dynamic local zone manipulation diff --git a/contrib/unbound/libunbound/python/doc/modules/unbound.rst b/contrib/unbound/libunbound/python/doc/modules/unbound.rst new file mode 100644 index 0000000..21f4a12 --- /dev/null +++ b/contrib/unbound/libunbound/python/doc/modules/unbound.rst @@ -0,0 +1,167 @@ +Unbound module documentation +================================ + +.. automodule:: unbound + +Class ub_ctx +-------------- +.. autoclass:: ub_ctx + :members: + :undoc-members: + + .. automethod:: __init__ + +Class ub_result +---------------------- +.. autoclass:: ub_result + :members: + + .. attribute:: qname + + The original question, name text string. + + .. attribute:: qtype + + The class asked for. + + .. attribute:: canonname + + Canonical name for the result (the final cname). May be empty if no canonical name exists. + + .. attribute:: answer_packet + + The DNS answer packet. Network formatted. Can contain DNSSEC types. + + .. attribute:: havedata + + If there is any data, this property is true. If false, there was no data (nxdomain may be true, rcode can be set). + + .. attribute:: secure + + True, if the result is validated securely. + False, if validation failed or domain queried has no security info. + + It is possible to get a result with no data (havedata is false), + and secure is true. This means that the non-existance of the data + was cryptographically proven (with signatures). + + .. attribute:: bogus + + If the result was not secure (secure==0), and this result is due to a security failure, bogus is true. + This means the data has been actively tampered with, signatures + failed, expected signatures were not present, timestamps on + signatures were out of date and so on. + + If secure==0 and bogus==0, this can happen if the data is not secure + because security is disabled for that domain name. + This means the data is from a domain where data is not signed. + + .. attribute:: nxdomain + + If there was no data, and the domain did not exist, this is true. + If it is false, and there was no data, then the domain name is purported to exist, but the requested data type is not available. + + .. attribute:: rcode + + DNS RCODE for the result. May contain additional error code if there was no data due to an error. + 0 (RCODE_NOERROR) if okay. See predefined `RCODE_` constants. + + RCODE can be represented in display representation form (string) using :attr:`rcode_str` attribute. + +Class ub_data +---------------------- +.. autoclass:: ub_data + :members: + +Functions +---------------------- +.. autofunction:: reverse +.. autofunction:: idn2dname +.. autofunction:: dname2idn + +Predefined constants +----------------------- + +**RCODE** + * RCODE_FORMERR = 1 + * RCODE_NOERROR = 0 + * RCODE_NOTAUTH = 9 + * RCODE_NOTIMPL = 4 + * RCODE_NOTZONE = 10 + * RCODE_NXDOMAIN = 3 + * RCODE_NXRRSET = 8 + * RCODE_REFUSED = 5 + * RCODE_SERVFAIL = 2 + * RCODE_YXDOMAIN = 6 + * RCODE_YXRRSET = 7 + +**RR_CLASS** + * RR_CLASS_ANY = 255 + * RR_CLASS_CH = 3 + * RR_CLASS_HS = 4 + * RR_CLASS_IN = 1 + * RR_CLASS_NONE = 254 + +**RR_TYPE** + * RR_TYPE_A = 1 + * RR_TYPE_A6 = 38 + * RR_TYPE_AAAA = 28 + * RR_TYPE_AFSDB = 18 + * RR_TYPE_ANY = 255 + * RR_TYPE_APL = 42 + * RR_TYPE_ATMA = 34 + * RR_TYPE_AXFR = 252 + * RR_TYPE_CERT = 37 + * RR_TYPE_CNAME = 5 + * RR_TYPE_DHCID = 49 + * RR_TYPE_DLV = 32769 + * RR_TYPE_DNAME = 39 + * RR_TYPE_DNSKEY = 48 + * RR_TYPE_DS = 43 + * RR_TYPE_EID = 31 + * RR_TYPE_GID = 102 + * RR_TYPE_GPOS = 27 + * RR_TYPE_HINFO = 13 + * RR_TYPE_IPSECKEY = 45 + * RR_TYPE_ISDN = 20 + * RR_TYPE_IXFR = 251 + * RR_TYPE_KEY = 25 + * RR_TYPE_KX = 36 + * RR_TYPE_LOC = 29 + * RR_TYPE_MAILA = 254 + * RR_TYPE_MAILB = 253 + * RR_TYPE_MB = 7 + * RR_TYPE_MD = 3 + * RR_TYPE_MF = 4 + * RR_TYPE_MG = 8 + * RR_TYPE_MINFO = 14 + * RR_TYPE_MR = 9 + * RR_TYPE_MX = 15 + * RR_TYPE_NAPTR = 35 + * RR_TYPE_NIMLOC = 32 + * RR_TYPE_NS = 2 + * RR_TYPE_NSAP = 22 + * RR_TYPE_NSAP_PTR = 23 + * RR_TYPE_NSEC = 47 + * RR_TYPE_NSEC3 = 50 + * RR_TYPE_NSEC3PARAMS = 51 + * RR_TYPE_NULL = 10 + * RR_TYPE_NXT = 30 + * RR_TYPE_OPT = 41 + * RR_TYPE_PTR = 12 + * RR_TYPE_PX = 26 + * RR_TYPE_RP = 17 + * RR_TYPE_RRSIG = 46 + * RR_TYPE_RT = 21 + * RR_TYPE_SIG = 24 + * RR_TYPE_SINK = 40 + * RR_TYPE_SOA = 6 + * RR_TYPE_SRV = 33 + * RR_TYPE_SSHFP = 44 + * RR_TYPE_TSIG = 250 + * RR_TYPE_TXT = 16 + * RR_TYPE_UID = 101 + * RR_TYPE_UINFO = 100 + * RR_TYPE_UNSPEC = 103 + * RR_TYPE_WKS = 11 + * RR_TYPE_X25 = 19 |
