diff options
Diffstat (limited to 'external/unbound/libunbound/python')
14 files changed, 273 insertions, 198 deletions
diff --git a/external/unbound/libunbound/python/doc/conf.py b/external/unbound/libunbound/python/doc/conf.py index 97fca2125..1766036b9 100644 --- a/external/unbound/libunbound/python/doc/conf.py +++ b/external/unbound/libunbound/python/doc/conf.py @@ -82,10 +82,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". diff --git a/external/unbound/libunbound/python/doc/examples/example1a.rst b/external/unbound/libunbound/python/doc/examples/example1a.rst index 3c81547f2..f46cb92f4 100644 --- a/external/unbound/libunbound/python/doc/examples/example1a.rst +++ b/external/unbound/libunbound/python/doc/examples/example1a.rst @@ -1,26 +1,33 @@ .. _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). +This basic example shows how to create a context and resolve a host address +(DNS record of A type). + +Source code +----------- :: - #!/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. + #!/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 the 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 does 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/external/unbound/libunbound/python/doc/examples/example1b.rst b/external/unbound/libunbound/python/doc/examples/example1b.rst index ea1e6f57d..1adae2cb1 100644 --- a/external/unbound/libunbound/python/doc/examples/example1b.rst +++ b/external/unbound/libunbound/python/doc/examples/example1b.rst @@ -1,33 +1,37 @@ .. _example_reverse_lookup: -============================== Reverse DNS lookup -============================== +================== -Reverse DNS lookup involves determining the hostname associated with a given IP address. +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. +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.`` + +Source code +----------- :: - #!/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:: + #!/usr/bin/python + import unbound - def reverse(domain): - return '.'.join([a for a in domain.split(".")][::-1]) + 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 the +:meth:`unbound.reverse` 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/external/unbound/libunbound/python/doc/examples/example2.rst b/external/unbound/libunbound/python/doc/examples/example2.rst index c009ec1f5..a2bf2cbf5 100644 --- a/external/unbound/libunbound/python/doc/examples/example2.rst +++ b/external/unbound/libunbound/python/doc/examples/example2.rst @@ -1,41 +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. +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. + +Source code +----------- :: - #!/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() + #!/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/external/unbound/libunbound/python/doc/examples/example3.rst b/external/unbound/libunbound/python/doc/examples/example3.rst index 91360335c..b0626b55f 100644 --- a/external/unbound/libunbound/python/doc/examples/example3.rst +++ b/external/unbound/libunbound/python/doc/examples/example3.rst @@ -1,12 +1,14 @@ .. _example_asynch: -============================== Asynchronous lookup -============================== +=================== This example performs the name lookup in the background. The main program keeps running while the name is resolved. +Source code +----------- + :: #!/usr/bin/python @@ -33,4 +35,5 @@ The main program keeps running while the name is resolved. 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`. +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/external/unbound/libunbound/python/doc/examples/example4.rst b/external/unbound/libunbound/python/doc/examples/example4.rst index 996ef4ede..3b43eb85f 100644 --- a/external/unbound/libunbound/python/doc/examples/example4.rst +++ b/external/unbound/libunbound/python/doc/examples/example4.rst @@ -1,33 +1,35 @@ .. _example_examine: -============================== DNSSEC validator -============================== +================ This example program performs DNSSEC validation of a DNS lookup. +Source code +----------- + :: - #!/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" + #!/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`_. diff --git a/external/unbound/libunbound/python/doc/examples/example5.rst b/external/unbound/libunbound/python/doc/examples/example5.rst index 0a31d9a57..9262014bb 100644 --- a/external/unbound/libunbound/python/doc/examples/example5.rst +++ b/external/unbound/libunbound/python/doc/examples/example5.rst @@ -1,13 +1,17 @@ .. _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. +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. + +Source code +----------- :: @@ -25,5 +29,6 @@ This option contains a list of module names separated by the space char. This li 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). - + 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/external/unbound/libunbound/python/doc/examples/example6.rst b/external/unbound/libunbound/python/doc/examples/example6.rst index 478e13909..6fde8b25f 100644 --- a/external/unbound/libunbound/python/doc/examples/example6.rst +++ b/external/unbound/libunbound/python/doc/examples/example6.rst @@ -1,11 +1,13 @@ .. _example_localzone: -============================== Local zone manipulation -============================== +======================= -This example program shows how to define local zone containing custom DNS records. +This example program shows how to define local zone containing custom DNS +records. -.. literalinclude:: example6-1.py - :language: python +Source code +----------- +.. literalinclude:: example6-1.py + :language: python diff --git a/external/unbound/libunbound/python/doc/examples/example7.rst b/external/unbound/libunbound/python/doc/examples/example7.rst index d4050215e..2f48c8f0f 100644 --- a/external/unbound/libunbound/python/doc/examples/example7.rst +++ b/external/unbound/libunbound/python/doc/examples/example7.rst @@ -1,18 +1,33 @@ .. _example_idna: -================================================= Internationalized domain name support -================================================= +===================================== Unlike the libUnbound, pyUnbound is able to handle IDN queries. -.. literalinclude:: example7-1.py - :language: python +Automatic IDN DNAME conversion +------------------------------- -If we use unicode string in :meth:`unbound.ub_ctx.resolve` method, the IDN DNAME conversion (if it is necessary) is performed on background. +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 +Source code +........... -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`). +.. literalinclude:: example7-1.py + :language: python + +IDN converted attributes +------------------------ + +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`). + +Source code +........... + +.. literalinclude:: example7-2.py + :language: python diff --git a/external/unbound/libunbound/python/doc/examples/example8.rst b/external/unbound/libunbound/python/doc/examples/example8.rst index 8cdfcdc0a..16c140475 100644 --- a/external/unbound/libunbound/python/doc/examples/example8.rst +++ b/external/unbound/libunbound/python/doc/examples/example8.rst @@ -1,28 +1,34 @@ .. _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`). +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 +Source code +----------- -Previous example produces following output:: +.. literalinclude:: example8-1.py + :language: python - 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. +Output +------ - Result: - raw data: D9 1F CD 32 - address: 217.31.205.50 +The previous example produces the following output:: - 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. + 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/external/unbound/libunbound/python/doc/examples/index.rst b/external/unbound/libunbound/python/doc/examples/index.rst index c2c9cf457..283261652 100644 --- a/external/unbound/libunbound/python/doc/examples/index.rst +++ b/external/unbound/libunbound/python/doc/examples/index.rst @@ -1,14 +1,16 @@ 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. +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` +Tutorials +--------- .. toctree:: - :maxdepth: 1 - :glob: + :maxdepth: 1 + :glob: - example* + example* diff --git a/external/unbound/libunbound/python/doc/install.rst b/external/unbound/libunbound/python/doc/install.rst index a073a5c66..bb3118984 100644 --- a/external/unbound/libunbound/python/doc/install.rst +++ b/external/unbound/libunbound/python/doc/install.rst @@ -1,31 +1,38 @@ Installation -=================================== +============ -**Prerequisites** +Prerequisites +------------- Python 2.4 or higher, SWIG 1.3 or higher, GNU make -**Compiling** +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 + > 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 may want to enable ``--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. +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 python LDNS extension module by:: +If the compilation is successful, you can test the python LDNS extension module +by:: - > cd contrib/python - > make testenv - > ./dns-lookup.py + > 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. +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/external/unbound/libunbound/python/doc/intro.rst b/external/unbound/libunbound/python/doc/intro.rst index f751f54c0..e490d2c6f 100644 --- a/external/unbound/libunbound/python/doc/intro.rst +++ b/external/unbound/libunbound/python/doc/intro.rst @@ -1,39 +1,58 @@ 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 +============ + +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/external/unbound/libunbound/python/libunbound.i b/external/unbound/libunbound/python/libunbound.i index 50a9b67ac..84a536929 100644 --- a/external/unbound/libunbound/python/libunbound.i +++ b/external/unbound/libunbound/python/libunbound.i @@ -945,7 +945,7 @@ int _ub_resolve_async(struct ub_ctx* ctx, char* name, int rrtype, int rrclass, v :param idnname: (unicode string) IDN name :returns: (string) domain name """ - return '.'.join([encodings.idna.ToASCII(a) for a in idnname.split('.')]) + return '.'.join([encodings.idna.ToASCII(a) if a else '' for a in idnname.split('.')]) def dname2idn(name): """Converts canonic domain name in IDN format to unicode string |