Class ldns_resolver

Class ldns_resolver

class ldns.ldns_resolver

LDNS resolver object.

The ldns_resolver object keeps a list of name servers and can perform queries.

Usage

>>> import ldns
>>> resolver = ldns.ldns_resolver.new_frm_file("/etc/resolv.conf")
>>> pkt = resolver.query("www.nic.cz", ldns.LDNS_RR_TYPE_A,ldns.LDNS_RR_CLASS_IN)
>>> if (pkt) and (pkt.answer()): 
>>>    print pkt.answer()
www.nic.cz. 1757    IN      A       217.31.205.50

This simple example instances a resolver in order to resolve www.nic.cz A type record.

axfr_complete()

Returns True if the axfr transfer has completed (i.e., 2 SOA RRs and no errors were encountered).

Returns:(bool)
axfr_last_pkt()

Returns a last packet that was sent by the server in the AXFR transfer (usable for instance to get the error code on failure).

Returns:(ldns_pkt) Last packet of the AXFR transfer.
axfr_next()

Get the next stream of RRs in a AXFR.

Returns:(ldns_rr) The next RR from the AXFR stream.
axfr_start(domain, aclass)

Prepares the resolver for an axfr query. The query is sent and the answers can be read with axfr_next().

Parameters:
  • domain (dlsn_dname) – Domain to axfr.
  • aclass (ldns_rr_class) – The class to use.
Throws TypeError:
 

When arguments of inappropriate types.

Returns:

(ldns_status) The status of the transfer.

Note

The type checking of parameter domain is benevolent. It allows also to pass a dname ldns_rdf object. This will probably change in future.

Usage

status = resolver.axfr_start("nic.cz", ldns.LDNS_RR_CLASS_IN)
if (status != ldns.LDNS_STATUS_OK):
    raise Exception("Can't start AXFR, error: %s" % ldns.ldns_get_errorstr_by_id(status))
#Print the results
while True:
     rr = resolver.axfr_next()
     if not rr: 
        break

     print rr
debug()

Get the debug status of the resolver.

Returns:(bool) True if so, otherwise False.
dec_nameserver_count()

Decrement the resolver’s name server count.

defnames()

Does the resolver apply default domain name.

Returns:(bool)
dnsrch()

Does the resolver apply search list.

Returns:(bool)
dnssec()

Does the resolver do DNSSEC.

Returns:(bool) True: yes, False: no.
dnssec_anchors()

Get the resolver’s DNSSEC anchors.

Returns:(ldns_rr_list) An rr list containing trusted DNSSEC anchors.
dnssec_cd()

Does the resolver set the CD bit.

Returns:(bool) True: yes, False: no.
domain()

What is the default dname to add to relative queries.

Returns:(ldns_dname) The dname which is added.
edns_udp_size()

Get the resolver’s udp size.

Returns:(uint16_t) The udp mesg size.
fail()

Does the resolver only try the first name server.

Returns:(bool) True: yes, fail, False: no, try the others.
fallback()

Get the truncation fall-back status.

Returns:(bool) Whether the truncation fall*back mechanism is used.
get_addr_by_name(name, aclass=1, flags=8)

Ask the resolver about name and return all address records.

Parameters:
  • name (ldns_dname or str) – The name to look for. String is automatically converrted to dname.
  • aclass (ldns_rr_class) – The class to use.
  • flags (uint16_t) – Give some optional flags to the query.
Throws TypeError:
 

When arguments of inappropriate types.

Returns:

(ldns_rr_list) RR List object or None.

Usage
>>> addr = resolver.get_addr_by_name("www.google.com", ldns.LDNS_RR_CLASS_IN, ldns.LDNS_RD)
>>> if (not addr): raise Exception("Can't retrieve server address")
>>> for rr in addr.rrs():
>>>     print rr
www.l.google.com.  300     IN      A       74.125.43.99
www.l.google.com.  300     IN      A       74.125.43.103
www.l.google.com.  300     IN      A       74.125.43.104
www.l.google.com.  300     IN      A       74.125.43.147
get_name_by_addr(addr, aclass=1, flags=8)

Ask the resolver about the address and return the name.

Parameters:
  • name (ldns_rdf of A or AAAA type) – (ldns_rdf of A or AAAA type) the addr to look for. If a string is given, A or AAAA type is identified automatically.
  • aclass (ldns_rr_class) – The class to use.
  • flags (uint16_t) – Give some optional flags to the query.
Throws TypeError:
 

When arguments of inappropriate types.

Returns:

(ldns_rr_list) RR List object or None.

Usage
>>> addr = resolver.get_name_by_addr("74.125.43.99", ldns.LDNS_RR_CLASS_IN, ldns.LDNS_RD)
>>> if (not addr): raise Exception("Can't retrieve server address")
>>> for rr in addr.rrs():
>>>     print rr
99.43.125.74.in-addr.arpa. 85641   IN      PTR     bw-in-f99.google.com.
igntc()

Does the resolver ignore the TC bit (truncated).

Returns:(bool) True: yes, False: no.
incr_nameserver_count()

Increment the resolver’s name server count.

ip6()

Does the resolver use ip6 or ip4.

Returns:(uint8_t) 0: both, 1: ip4, 2:ip6
nameserver_count()

How many name server are configured in the resolver.

Returns:(size_t) Number of name servers.
nameserver_rtt(pos)

Return the used round trip time for a specific name server.

Parameters:pos (size_t) – The index to the name server.
Throws TypeError:
 When arguments of inappropriate types.
Returns:(size_t) The rrt, 0: infinite, >0: undefined (as of * yet).
nameservers()

Return the configured name server ip address.

Returns:(ldns_rdf **) A ldns_rdf pointer to a list of the addresses.
nameservers_randomize()

Randomize the name server list in the resolver.

static new()

Creates a new resolver object.

Returns:(ldns_resolver) New resolver object or None.

Note

The returned resolver object is unusable unless some name servers are added.

Usage
>>> resolver = ldns.ldns_resolver.new()
>>> ns_addr = ldns.ldns_rdf.new_frm_str("8.8.8.8", ldns.LDNS_RDF_TYPE_A)
>>> if not ns_addr: raise Exception("Can't create resolver address.")
>>> status = resolver.push_nameserver(ns_addr)
>>> if status != ldns.LDNS_STATUS_OK: raise Exception("Can't push resolver address.")
>>> pkt = resolver.query("www.nic.cz.", ldns.LDNS_RR_TYPE_A, ldns.LDNS_RR_CLASS_IN, ldns.LDNS_RD)
>>> if (pkt) and (pkt.answer()):
>>>     print pkt.answer()
www.nic.cz.     1265    IN      A       217.31.205.50
static new_frm_file(filename='/etc/resolv.conf', raiseException=True)

Creates a resolver object from given file name

Parameters:
  • filename (str) – Name of file which contains resolver informations (usually /etc/resolv.conf).
  • raiseException (bool) – If True, an exception occurs in case a resolver object can’t be created.
Throws TypeError:
 

When arguments of inappropriate types.

Throws Exception:
 

When raiseException set and resolver couldn’t be created.

Returns:

(ldns_resolver) Resolver object or None. An exception occurs if the object can’t be created and ‘raiseException’ is True.

static new_frm_fp(file, raiseException=True)

Creates a resolver object from file

Parameters:
  • file (file) – A file object.
  • raiseException (bool) – If True, an exception occurs in case a resolver object can’t be created.
Throws TypeError:
 

When arguments of inappropriate types.

Throws Exception:
 

When raiseException set and resolver couldn’t be created.

Returns:

(ldns_resolver) Resolver object or None. An exception occurs if the object can’t be created and raiseException is True.

static new_frm_fp_l(file, raiseException=True)

Creates a resolver object from file

Parameters:
  • file (file) – A file object.
  • raiseException (bool) – If True, an exception occurs in case a resolver instance can’t be created.
Throws TypeError:
 

When arguments of inappropriate types.

Throws Exception:
 

When raiseException set and resolver couldn’t be created.

Returns:

  • (ldns_resolver) Resolver instance or None.

    An exception occurs if an instance can’t be created and raiseException is True.

  • (int) - The line number. (e.g., for debugging)

pop_nameserver()

Pop the last name server from the resolver.

Returns:(ldns_rdf) The popped address or None if empty.
port()

Get the port the resolver should use.

Returns:(uint16_t) The port number.
prepare_query_pkt(name, t, c, f, raiseException=True)

Form a query packet from a resolver and name/type/class combo.

Parameters:
  • name (ldns_dname or str) – Query for this name.
  • t (ldns_rr_type) – Query for this type (may be 0, defaults to A).
  • c (ldns_rr_class) – Query for this class (may be 0, default to IN).
  • f (uint16_t) – The query flags.
Throws TypeError:
 

When arguments of inappropriate types.

Throws Exception:
 

When raiseException set and answer couldn’t be resolved.

Returns:

(ldns_pkt) Query packet or None. An exception occurs if the object can’t be created and ‘raiseException’ is True.

print_to_file(output)

Print a resolver (in so far that is possible) state to output.

push_dnssec_anchor(rr)

Push a new trust anchor to the resolver. It must be a DS or DNSKEY rr.

Parameters:rr (DS of DNSKEY ldns_rr) – The RR to add as a trust anchor.
Throws TypeError:
 When arguments of inappropriate types.
Returns:(ldns_status) A status.
push_nameserver(n)

Push a new name server to the resolver. It must be an IP address v4 or v6.

Parameters:n (ldns_rdf of A or AAAA type.) – The ip address.
Throws TypeError:
 When arguments of inappropriate types.
Returns:(ldns_status) A status.
push_nameserver_rr(rr)

Push a new name server to the resolver. It must be an A or AAAA RR record type.

Parameters:rr (ldns_rr of A or AAAA type.) – The resource record.
Throws TypeError:
 When arguments of inappropriate types.
Returns:(ldns_status) A status.
push_nameserver_rr_list(rrlist)

Push a new name server rr_list to the resolver.

Parameters:rrlist (ldns_rr_list) – The rr list to push.
Throws TypeError:
 When arguments of inappropriate types.
Returns:(ldns_status) A status.
push_searchlist(rd)

Push a new rd to the resolver’s search-list.

Parameters:
Throws TypeError:
 

When arguments of inappropriate types.

query(name, atype=1, aclass=1, flags=8)

Send a query to a name server.

Parameters:
  • name (ldns_dname or str) – The name to look for.
  • atype (ldns_rr_type) – The RR type to use.
  • aclass (ldns_rr_class) – The RR class to use.
  • flags (uint16_t) – Give some optional flags to the query.
Throws TypeError:
 

When arguments of inappropriate types.

Returns:

(ldns_pkt) A packet with the reply from the name server if _defnames is true the default domain will be added.

random()

Does the resolver randomize the name server before usage?

Returns:(bool) True: yes, False: no.
recursive()

Is the resolver set to recurse?

Returns:(bool) True if so, otherwise False.
retrans()

Get the retransmit interval.

Returns:(uint8_t) The retransmit interval.
retry()

Get the number of retries.

Returns:(uint8_t) The number of retries.
rtt()

Return the used round trip times for the name servers.

Returns:(size_t *) a size_t* pointer to the list. yet)
search(name, atype=1, aclass=1, flags=8)

Send the query for using the resolver and take the search list into account The search algorithm is as follows: If the name is absolute, try it as-is, otherwise apply the search list.

Parameters:
  • name (ldns_dname or str) – The name to look for.
  • atype (ldns_rr_type) – The RR type to use.
  • aclass (ldns_rr_class) – The RR class to use.
  • flags (uint16_t) – Give some optional flags to the query.
Throws TypeError:
 

When arguments of inappropriate types.

Returns:

(ldns_pkt) A packet with the reply from the name server.

searchlist()

What is the search-list as used by the resolver.

Returns:(ldns_rdf **) A ldns_rdf pointer to a list of the addresses.
searchlist_count()

Return the resolver’s search-list count.

Returns:(size_t) The search-list count.
send(name, atype, aclass, flags, raiseException=True)

Send the query for name as-is.

Parameters:
  • name (ldns_dname or str) – The name to look for.
  • atype (ldns_rr_type) – The RR type to use.
  • aclass (ldns_rr_class) – The RR class to use.
  • flags (uint16_t) – Give some optional flags to the query.
Throws TypeError:
 

When arguments of inappropriate types.

Throws Exception:
 

When raiseException set and answer couldn’t be resolved.

Returns:

(ldns_pkt) A packet with the reply from the name server.

send_pkt(query_pkt)

Send the given packet to a name server.

Parameters:query_pkt (ldns_pkt) – Query packet.
Throws TypeError:
 When arguments of inappropriate types.
Returns:
  • (ldns_status) Return status.
  • (ldns_pkt) Response packet if returns status ok.
set_debug(b)

Set the resolver debugging.

Parameters:b (bool) – True: debug on, False: debug off.
set_defnames(b)

Whether the resolver uses the name set with _set_domain.

Parameters:b (bool) – True: use the defaults, False: don’t use them.
set_dnsrch(b)

Whether the resolver uses the search list.

Parameters:b (bool) – True: use the list, False: don’t use the list.
set_dnssec(b)

Whether the resolver uses DNSSEC.

Parameters:b (bool) – True: use DNSSEC, False: don’t use DNSSEC.
set_dnssec_anchors(l)

Set the resolver’s DNSSEC anchor list directly. RRs should be of type DS or DNSKEY.

Parameters:l (ldns_rr_list) – The list of RRs to use as trust anchors.
Throws TypeError:
 When arguments of inappropriate types.
set_dnssec_cd(b)

Whether the resolver uses the checking disable bit.

Parameters:b (bool) – True: enable, False: disable.
set_domain(rd)

Set the resolver’s default domain. This gets appended when no absolute name is given.

Parameters:rd (ldns_dname or str) – The name to append.
Throws TypeError:
 When arguments of inappropriate types.
Throws Exception:
 When rd a non dname rdf.

Note

The type checking of parameter rd is benevolent. It allows also to pass a dname ldns_rdf object. This will probably change in future.

set_edns_udp_size(s)

Set maximum udp size.

Parameters:s (uint16_t) – The udp max size.
Throws TypeError:
 When arguments of inappropriate types.
set_fail(b)

Whether or not to fail after one failed query.

Parameters:b (bool) – True: yes fail, False: continue with next name server.
set_fallback(fallback)

Set whether the resolvers truncation fall-back mechanism is used when query() is called.

Parameters:fallback (bool) – Whether to use the fall-back mechanism.
set_igntc(b)

Whether or not to ignore the TC bit.

Parameters:b (bool) – True: yes ignore, False: don’t ignore.
set_ip6(i)

Whether the resolver uses ip6.

Parameters:i (uint8_t) – 0: no pref, 1: ip4, 2: ip6
Throws TypeError:
 When arguments of inappropriate types.
set_nameserver_count(c)

Set the resolver’s name server count directly.

Parameters:c (size_t) – The name server count.
Throws TypeError:
 When arguments of inappropriate types.
set_nameserver_rtt(pos, value)

Set round trip time for a specific name server. Note this currently differentiates between: unreachable and reachable.

Parameters:
  • pos (size_t) – The name server position.
  • value (size_t) – The rtt.
Throws TypeError:
 

When arguments of inappropriate types.

set_nameservers(rd)

Set the resolver’s name server count directly by using an rdf list.

Parameters:rd (ldns_rdf **) – The resolver addresses.
Throws TypeError:
 When arguments of inappropriate types.
set_port(p)

Set the port the resolver should use.

Parameters:p (uint16_t) – The port number.
Throws TypeError:
 When arguments of inappropriate types.
set_random(b)

Should the name server list be randomized before each use.

Parameters:b (bool) – True: randomize, False: don’t.
set_recursive(b)

Set the resolver recursion.

Parameters:b (bool) – True: set to recurse, False: unset.
set_retrans(re)

Set the resolver retrans time-out (in seconds).

Parameters:re (uint8_t) – The retransmission interval in seconds.
Throws TypeError:
 When arguments of inappropriate types.
set_retry(re)

Set the resolver retry interval (in seconds).

Parameters:re (uint8_t) – The retry interval.
Throws TypeError:
 When arguments of inappropriate types.
set_rtt(rtt)

Set round trip time for all name servers. Note this currently differentiates between: unreachable and reachable.

Parameters:rtt (size *) – A list with the times.
Throws TypeError:
 When arguments of inappropriate types.
set_timeout(timeout)

Set the resolver’s socket time out when talking to remote hosts.

Parameters:
  • timeout – The time-out to use.
  • timeout – struct timeval
Throws TypeError:
 

When arguments of inappropriate types.

set_tsig_algorithm(tsig_algorithm)

Set the tsig algorithm.

Parameters:
  • tsig_algorithm – The tsig algorithm.
  • tsig_algorithm – str
Throws TypeError:
 

When arguments of inappropriate types.

set_tsig_keydata(tsig_keydata)

Set the tsig key data.

Parameters:tsig_keydata (str) – The key data.
Throws TypeError:
 When arguments of inappropriate types.
set_tsig_keyname(tsig_keyname)

Set the tsig key name.

Parameters:tsig_keyname (str) – The tsig key name.
Throws TypeError:
 When arguments of inappropriate types.
set_usevc(b)

Whether the resolver uses a virtual circuit (TCP).

Parameters:b (bool) – True: use TCP, False: don’t use TCP.
timeout()

What is the time-out on socket connections.

Returns:(struct timeval) The time-out.
trusted_key(keys)

Returns true if at least one of the provided keys is a trust anchor.

Parameters:keys (ldns_rr_list) – The key set to check.
Throws TypeError:
 When arguments of inappropriate types.
Returns:(ldns_rr_list) List of trusted keys if at least one of the provided keys is a configured trust anchor, None else.
tsig_algorithm()

Return the tsig algorithm as used by the name server.

Returns:(str) The algorithm used.
tsig_keydata()

Return the tsig key data as used by the name server.

Returns:(str) The key data used.
tsig_keyname()

Return the tsig key name as used by the name server.

Returns:(str) The name used.
usevc()

Does the resolver use tcp or udp.

Returns:(bool) True: tcp, False: udp.

Table Of Contents

Previous topic

LDNS module documentation

Next topic

Class ldns_pkt