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¶

The PowerDNS Recursor’s Lua engine has the notion of a DNSName, an object that represents a name in the DNS. It is returned by several functions and has several functions to programmatically interact with it. DNSNames can be compared against each other using the :equal function or the == operator. As names in the DNS are case-insensitive, www.powerdns.com is equal to Www.PowerDNS.cOM.

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

A small example of the functionality of a DNSName is shown below:

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

Functions and methods of a DNSName¶

newDN(name): DNSName¶

Returns the DNSName object of name.

Parameters:¶

name (string) – The name to create a DNSName for

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.

DNSName(): canonCompare(name): bool¶

Performs a comparison of DNS names in canonical order. Returns true if the DNSName comes before name. See https://tools.ietf.org/html/rfc4034#section-6

Parameters:¶

name (DNSName()) – The name to compare to

DNSName(): makeRelative(name): DNSName()¶

Returns a new DNSName that is relative to name

name = newDN("bb.a.example.com.")
parent = newDN("example.com.")
rel = name:makeRelative(parent) -- contains DNSName("bb.a.")

Parameters:¶

name (DNSName()) – The name to compare to

DNSName(): isPartOf(name): bool¶

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

Parameters:¶

name (DNSName()) – The name to check against

DNSName(): toString(): string¶

Returns a human-readable form of the DNSName

DNSName(): toStringNoDot(): string¶

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

DNSName(): chopOff(): bool¶

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

DNSName(): countLabels(): int¶

Returns the number of DNSLabels in the name

DNSName(): wireLength(): int¶

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

DNSName(): getRawLabels(): [string]¶

Returns a table that contains the raw labels of the DNSName

DNSName(): countLabels(): int¶

Returns the number of labels of the DNSName

DNSName(): equal(name): bool¶

Perform a comparison of the DNSName to the given name. You can also compare directly two DNSName objects using the == operator

Parameters:¶

name (string) – The name to compare to

DNS Suffix Match Group¶

The newDS() function creates a DNS 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(dnsname)

DNSSuffixMatchGroup(): add(domains)

Add one or more domains to the DNS Suffix Match Group.

Parameters:¶

• domain (str) – A domain name to add

• dnsname (DNSName) – A dnsname to add

• domains ({str}) – A list of domain names to add

DNSSuffixMatchGroup(): check(dnsname): bool¶

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

Parameters:¶

dnsname (DNSName) – The dnsname to check

DNSSuffixMatchGroup(): toString(): str¶

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