Unbound module documentation

Class ub_ctx

class unbound.ub_ctx

Unbound resolving and validation context.

The validation context is created to hold the resolver status, validation keys and a small cache (containing messages, rrsets, roundtrip times, trusted keys, lameness information).

Usage

>>> import unbound
>>> ctx = unbound.ub_ctx()
>>> ctx.resolvconf("/etc/resolv.conf")
>>> status, result = ctx.resolve("www.google.com", unbound.RR_TYPE_A, unbound.RR_CLASS_IN)
>>> if status==0 and result.havedata:
>>>    print "Result:",result.data.address_list
Result: ['74.125.43.147', '74.125.43.99', '74.125.43.103', '74.125.43.104']

__init__()

Creates a resolving and validation context.

An exception is invoked if the process of creation an ub_ctx instance fails.

add_ta(ta)

Add a trust anchor to the given context.

The trust anchor is a string, on one line, that holds a valid DNSKEY or DS RR.

Parameters:

• ta – string, with zone-format RR on one line. [domainname] [TTL optional] [type] [class optional] [rdata contents]

Returns:

(int) 0 if OK, else error.

add_ta_file(fname)

Add trust anchors to the given context.

Pass name of a file with DS and DNSKEY records (like from dig or drill).

Parameters:

• fname – filename of file with keyfile with trust anchors.

Returns:

(int) 0 if OK, else error.

cancel(async_id)

Cancel an async query in progress.

Its callback will not be called.

Parameters:

• async_id – which query to cancel.

Returns:

(int) 0 if OK, else error.

config(fname)

setup configuration for the given context.

Parameters:

• fname – unbound config file (not all settings applicable). This is a power-users interface that lets you specify all sorts of options. For some specific options, such as adding trust anchors, special routines exist.

Returns:

(int) 0 if OK, else error.

data_add(rrdata)

Add new local RR data

Parameters:

• rrdata – string, in zone-format on one line. [domainname] [TTL optional] [type] [class optional] [rdata contents]

Returns:

(int) 0 if OK, else error.

Usage

The local data ...

>>> ctx = unbound.ub_ctx()
>>> ctx.zone_add("mydomain.net.","static")
0
>>> status = ctx.data_add("test.mydomain.net. IN A 192.168.1.1")
0
>>> status, result = ctx.resolve("test.mydomain.net")
>>> if status==0 and result.havedata:
>>>    print "Result:",result.data.address_list
Result: ['192.168.1.1']

data_remove(rrdata)

Remove local RR data

If exists, remove resource record from local zone

Parameters:

• rrdata – string, in zone-format on one line. [domainname] [TTL optional] [type] [class optional] [rdata contents]

Returns:

(int) 0 if OK, else error.

debuglevel(d)

Set debug verbosity for the context Output is directed to stderr.

Parameters:

• d – debug level, 0 is off, 1 is very minimal, 2 is detailed, and 3 is lots.

Returns:

(int) 0 if OK, else error.

debugout(out)

Set debug output (and error output) to the specified stream.

Pass None to disable. Default is stderr.

Parameters:

• out – File stream to log to.

Returns:

(int) 0 if OK, else error.

Usage:

In order to log into file, use

ctx = unbound.ub_ctx()
fw = fopen("debug.log")
ctx.debuglevel(3)
ctx.debugout(fw)

Another option is to print the debug informations to stderr output

ctx = unbound.ub_ctx()
ctx.debuglevel(10)
ctx.debugout(sys.stderr) 

get_fd()

Get file descriptor.

Wait for it to become readable, at this point answers are returned from the asynchronous validating resolver. Then call the ub_process to continue processing. This routine works immediately after context creation, the fd does not change.

Returns:(int) -1 on error, or file descriptor to use select(2) with.

hosts(fname='/etc/hosts')

Read list of hosts from the filename given.

Usually “/etc/hosts”. These addresses are not flagged as DNSSEC secure when queried for.

Parameters:

• fname – file name string. If None “/etc/hosts” is used.

Returns:

(int) 0 if OK, else error.

poll()

Poll a context to see if it has any new results Do not poll in a loop, instead extract the fd below to poll for readiness, and then check, or wait using the wait routine.

Returns:(int) 0 if nothing to read, or nonzero if a result is available. If nonzero, call ctx_process() to do callbacks.

print_local_zones()

Print the local zones and their content (RR data) to the debug output.

Returns:(int) 0 if OK, else error.

process()

Call this routine to continue processing results from the validating resolver (when the fd becomes readable).

Will perform necessary callbacks.

Returns:(int) 0 if OK, else error.

resolvconf(fname='/etc/resolv.conf')

Read list of nameservers to use from the filename given.

Usually “/etc/resolv.conf”. Uses those nameservers as caching proxies. If they do not support DNSSEC, validation may fail.

Only nameservers are picked up, the searchdomain, ndots and other settings from resolv.conf(5) are ignored.

Parameters:

• fname – file name string. If None “/etc/resolv.conf” is used.

Returns:

(int) 0 if OK, else error.

resolve(name, rrtype=1, rrclass=1)

Perform resolution and validation of the target name.

Parameters:

• name – domain name in text format (a string or unicode string). IDN domain name have to be passed as a unicode string.
• rrtype – type of RR in host order (optional argument). Default value is RR_TYPE_A (A class).
• rrclass – class of RR in host order (optional argument). Default value is RR_CLASS_IN (for internet).

Returns:

• (int) 0 if OK, else error.
• (ub_result) the result data is returned in a newly allocated result structure. May be None on return, return value is set to an error in that case (out of memory).

resolve_async(name, mydata, callback, rrtype=1, rrclass=1)

Perform resolution and validation of the target name.

Asynchronous, after a while, the callback will be called with your data and the result. If an error happens during processing, your callback will be called with error set to a nonzero value (and result==None).

Parameters:

• name – domain name in text format (a string or unicode string). IDN domain name have to be passed as a unicode string.
• mydata – this data is your own data (you can pass arbitrary python object or None) which are passed on to the callback function.
• callback – call-back function which is called on completion of the resolution.
• rrtype – type of RR in host order (optional argument). Default value is RR_TYPE_A (A class).
• rrclass – class of RR in host order (optional argument). Default value is RR_CLASS_IN (for internet).

Returns:

• (int) 0 if OK, else error.
• (int) async_id, an identifier number is returned for the query as it is in progress. It can be used to cancel the query.

Call-back function:

The call-back function looks as the follows:

def call_back(mydata, status, result):
    pass

Parameters:

• mydata - mydata object
• status - 0 when a result has been found
• result - the result structure. The result may be None, in that case err is set.

set_async(dothread)

Set a context behaviour for asynchronous action.

Parameters:

• dothread –

  if True, enables threading and a call to resolve_async() creates a thread to handle work in the background. If False, a process is forked to handle work in the background. Changes to this setting after async() calls have been made have no effect (delete and re-create the context to change).

Returns:

(int) 0 if OK, else error.

set_fwd(addr)

Set machine to forward DNS queries to, the caching resolver to use.

IP4 or IP6 address. Forwards all DNS requests to that machine, which is expected to run a recursive resolver. If the is not DNSSEC-capable, validation may fail. Can be called several times, in that case the addresses are used as backup servers.

To read the list of nameservers from /etc/resolv.conf (from DHCP or so), use the call resolvconf().

Parameters:

• addr – address, IP4 or IP6 in string format. If the addr is None, forwarding is disabled.

Returns:

(int) 0 if OK, else error.

set_option(opt, val)

Set an option for the context.

Changes to the options after resolve(), resolve_async(), zone_add(), zone_remove(), data_add() or data_remove() have no effect (you have to delete and re-create the context).

Parameters:

• opt – option name from the unbound.conf config file format. (not all settings applicable). The name includes the trailing ‘:’ for example set_option(“logfile:”, “mylog.txt”); This is a power-users interface that lets you specify all sorts of options. For some specific options, such as adding trust anchors, special routines exist.
• val – value of the option.

Returns:

(int) 0 if OK, else error.

trustedkeys(fname)

Add trust anchors to the given context.

Pass the name of a bind-style config file with trusted-keys{}.

Parameters:

• fname – filename of file with bind-style config entries with trust anchors.

Returns:

(int) 0 if OK, else error.

wait()

Wait for a context to finish with results.

Calls after the wait for you. After the wait, there are no more outstanding asynchronous queries.

Returns:(int) 0 if OK, else error.

zone_add(zonename, zonetype)

Add new local zone

Parameters:

• zonename – zone domain name (e.g. myzone.)
• zonetype – type of the zone (“static”,...)

Returns:

(int) 0 if OK, else error.

zone_print()

Print local zones using debougout

zone_remove(zonename)

Remove local zone

If exists, removes local zone with all the RRs.

Parameters:

• zonename – zone domain name

Returns:

(int) 0 if OK, else error.

Class ub_result

class unbound.ub_result

The validation and resolution results.

qname

The original question, name text string.

qtype

The class asked for.

canonname

Canonical name for the result (the final cname). May be empty if no canonical name exists.

answer_packet

The DNS answer packet. Network formatted. Can contain DNSSEC types.

havedata

If there is any data, this property is true. If false, there was no data (nxdomain may be true, rcode can be set).

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).

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.

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.

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 rcode_str attribute.

data

Returns ub_data instance containing various decoding functions or None

rawdata

Returns raw data, a list of rdata items. To decode RAW data use the data attribute which returns an instance of ub_data containing the conversion functions.

rcode_str

Returns rcode in display representation form

Returns:string

Class ub_data

class unbound.ub_data(data)

Class which makes the resolution results accessible

address_list

Returns a list of IP addresses. See as_address_list()

as_address_list()

Represents data as a list of IP addresses (query for RR_TYPE_PTR)

Returns:list of strings

as_domain_list()

Represents data as a list of domain names (query for RR_TYPE_A)

Returns:list of strings

as_idn_domain_list()

Represents data as a list of unicode domain names (query for RR_TYPE_A)

Returns:list of strings

as_idn_mx_list()

Represents data as a list of MX records (query for RR_TYPE_MX)

Returns:list of tuples (priority, unicode dname)

as_mx_list()

Represents data as a list of MX records (query for RR_TYPE_MX)

Returns:list of tuples (priority, dname)

as_raw_data()

Returns a list of RAW strings

dname2str

Parses DNAME and produces a list of labels

Parameters:

• ofs – where the conversion should start to parse data
• maxlen – maximum length (0 means parse to the end)

Returns:

list of labels (string)

domain_list

Returns a list of domain names. See as_domain_list()

domain_list_idn

Returns a list of IDN domain names. See as_idn_domain_list()

mx_list

Returns a list of tuples containing priority and domain names. See as_mx_list()

mx_list_idn

Returns a list of tuples containing priority and IDN domain names. See as_idn_mx_list()

raw

Returns RAW data (a list of binary encoded strings). See as_raw_data()

Functions

unbound.reverse(domain)

Reverse domain name

Usable for reverse lookups when the IP address should be reversed

unbound.idn2dname(idnname)

Converts domain name in IDN format to canonic domain name

Parameters:

• idnname – (unicode string) IDN name

Returns:

(string) domain name

unbound.dname2idn(name)

Converts canonic domain name in IDN format to unicode string

Parameters:

• name – (string) domain name

Returns:

(unicode string) domain name

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