DNS names and comparing them

The PowerDNS Recursor uses a native format for the names it handles. This native format is exposed to Lua as well.

The DNSName object

class DNSName

A DNSName object represents a name in the DNS. It is returned by several functions and has several functions to programmatically interact with it.

Creating a DNSName is done with newDN(). The PowerDNS Recursor will complain loudly if the name is invalid (e.g. too long, dot in the wrong place).

myname = newDN("www.example.com")
print(myname:countLabels()) -- prints "3"
print(myname:wirelength()) -- prints "17"
name2 = newDN(myname)
name2:chopoff() -- returns true, as 'www' was stripped
if myname:isPartOf(name2) then -- prints "it is"
  print('it is')
end

DNSNames can be compared agains each other using the :equal function or the == operator.

newDN(name) → DNSName

Returns the DNSName object of name.

Parameters:name (string) – The name to create a DNSName for
DNSName::chopOff() -> bool

Removes the left-most label and returns true. false is returned if no label was removed

classmethod DNSName:countLabels() → int

Returns the number of DNSLabels in the name

classmethod DNSName:isPartOf(name) → bool

Returns true if the DNSName is part of the DNS tree of name.

newDN("www.powerdns.com"):isPartOf(newDN("CoM.")) -- true
Parameters:name (DNSName) – The name to check against
classmethod DNSName:toString() → str
classmethod DNSName:toStringNoDot() → str

Returns a human-readable form of the DNSName. With or without trailing dot.

DNSName:wirelength -> int

Returns the length in bytes of the DNSName as it would be on the wire.

DNS Suffix Match Groups

The func:newDS function creates a “Suffix Match group” that allows fast checking if a DNSName is part of a group. This could e.g. be used to answer questions for known malware domains. To check e.g. the dq.qname against a list:

m = newDS()
m:add({'example.com', 'example.net})
m:check(dq.qname) -- Would be true is dq.qname is a name in example.com or example.net
newDS() → DNSSuffixMatchGroup

Creates a new DNS Suffix Match Group.

class DNSSuffixMatchGroup

This class represents a group of DNS names that can be used to quickly compare a single DNSName against.

DNSSuffixMatchGroup::add(domain)
DNSSuffixMatchGroup::add(domains)

Add one or more domains to the Suffix Match Group.

Parameters:
  • domain ({str}) – A domain name to add
  • domain – A list of Domains to add
classmethod DNSSuffixMatchGroup:check(domain) → bool

Check domain against the Suffix Match Group. Returns true if it is matched, false otherwise.

Parameters:domain (DNSName) – The domain name to check
classmethod DNSSuffixMatchGroup:toString() → str

Returns a string of the set of suffixes matched by the Suffix Match Group