diff options
Diffstat (limited to 'libunbound/python/doc/examples')
| -rw-r--r-- | libunbound/python/doc/examples/example1a.rst | 26 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example1b.rst | 33 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example2.rst | 41 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example3.rst | 36 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example4.rst | 34 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example5.rst | 29 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example6-1.py | 27 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example6.rst | 11 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example7-1.py | 17 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example7-2.py | 16 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example7.rst | 18 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example8-1.py | 31 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/example8.rst | 28 | ||||
| -rw-r--r-- | libunbound/python/doc/examples/index.rst | 14 |
14 files changed, 361 insertions, 0 deletions
diff --git a/libunbound/python/doc/examples/example1a.rst b/libunbound/python/doc/examples/example1a.rst new file mode 100644 index 000000000000..3c81547f2948 --- /dev/null +++ b/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/libunbound/python/doc/examples/example1b.rst b/libunbound/python/doc/examples/example1b.rst new file mode 100644 index 000000000000..ea1e6f57de65 --- /dev/null +++ b/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/libunbound/python/doc/examples/example2.rst b/libunbound/python/doc/examples/example2.rst new file mode 100644 index 000000000000..c009ec1f5ae7 --- /dev/null +++ b/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/libunbound/python/doc/examples/example3.rst b/libunbound/python/doc/examples/example3.rst new file mode 100644 index 000000000000..91360335c63a --- /dev/null +++ b/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/libunbound/python/doc/examples/example4.rst b/libunbound/python/doc/examples/example4.rst new file mode 100644 index 000000000000..996ef4ede924 --- /dev/null +++ b/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/libunbound/python/doc/examples/example5.rst b/libunbound/python/doc/examples/example5.rst new file mode 100644 index 000000000000..0a31d9a57e76 --- /dev/null +++ b/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/libunbound/python/doc/examples/example6-1.py b/libunbound/python/doc/examples/example6-1.py new file mode 100644 index 000000000000..0f405448c513 --- /dev/null +++ b/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/libunbound/python/doc/examples/example6.rst b/libunbound/python/doc/examples/example6.rst new file mode 100644 index 000000000000..478e13909277 --- /dev/null +++ b/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/libunbound/python/doc/examples/example7-1.py b/libunbound/python/doc/examples/example7-1.py new file mode 100644 index 000000000000..802bd1c35baf --- /dev/null +++ b/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/libunbound/python/doc/examples/example7-2.py b/libunbound/python/doc/examples/example7-2.py new file mode 100644 index 000000000000..5a41f8dc9333 --- /dev/null +++ b/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/libunbound/python/doc/examples/example7.rst b/libunbound/python/doc/examples/example7.rst new file mode 100644 index 000000000000..d4050215e435 --- /dev/null +++ b/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/libunbound/python/doc/examples/example8-1.py b/libunbound/python/doc/examples/example8-1.py new file mode 100644 index 000000000000..79060167d83c --- /dev/null +++ b/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/libunbound/python/doc/examples/example8.rst b/libunbound/python/doc/examples/example8.rst new file mode 100644 index 000000000000..8cdfcdc0a904 --- /dev/null +++ b/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/libunbound/python/doc/examples/index.rst b/libunbound/python/doc/examples/index.rst new file mode 100644 index 000000000000..c2c9cf457117 --- /dev/null +++ b/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* |