The DNSQuestion (`dq`) object¶

Apart from the ipfilter()-function, all functions work on a dq (DNSQuestion) object. This object contains details about the current state of the question. This state can be modified from the various hooks.

The DNSQuestion object contains at least the following fields:

class DNSQuestion¶

An object that contains everything about the current query. This object has the following attributes:

addPaddingToResponse¶: Added in version 4.5.0.

Whether the response will get EDNS Padding. See incoming.edns_padding_from and incoming.edns_padding_mode.

extendedErrorCode¶: Added in version 4.5.0.

The extended error code, if any. See recursor.extended_resolution_errors.

extendedErrorExtra¶: Added in version 4.5.0.

The extended error extra text, as a string, if any. See recursor.extended_resolution_errors.

qname¶: DNSName of the name this query is for.

qtype¶: Type this query is for as an integer, can be compared against pdns.A, pdns.AAAA.

rcode¶: current DNS Result Code, which can be overridden, including to several magical values. Before 4.4.0, the rcode can be set to pdns.DROP to drop the query, for later versions refer to Callback Semantics. Other statuses are normal DNS return codes, like pdns.NOERROR, pdns.NXDOMAIN etc.

isTcp¶: Whether the query was received over TCP.

remoteaddr¶: ComboAddress of the requestor. If the proxy protocol is used, this will contain the source address from the proxy protocol header.

localaddr¶: ComboAddress where this query was received on. If the proxy protocol is used, this will contain the destination address from the proxy protocol header.

interface_remoteaddr¶: Source ComboAddress of the packet received by the recursor. If the proxy protocol is not used, the value will match remoteaddr.

interface_localaddr¶: Destination ComboAddress of the packet received by the recursor. If the proxy protocol is not used, the value will match localaddr.

variable¶: Boolean which, if set, indicates the recursor should not packet cache this answer. Honored even when returning false from a hook! Important when providing answers that vary over time or based on sender details.

followupFunction¶

String that signals the nameserver to take one an additional action:

followCNAMERecords: When adding a CNAME to the answer, this tells the recursor to follow that CNAME. See CNAME Chain Resolution
getFakeAAAARecords: Get a fake AAAA record, see DNS64
getFakePTRRecords: Get a fake PTR record, see DNS64
udpQueryResponse: Do a UDP query and call a handler, see UDP Query Response

followupName¶: see DNS64

followupPrefix¶: see DNS64

appliedPolicy¶

The decision that was made by the policy engine, see Modifying Policy Decisions.

appliedPolicy.policyName¶: A string with the name of the policy. Set by policyName in the rpzFile() and rpzPrimary() configuration items. It is advised to overwrite this when modifying the DNSQuestion.appliedPolicy.policyKind

appliedPolicy.policyType¶

The type of match for the policy.

pdns.policytypes.None the empty policy type
pdns.policytypes.QName a match on qname
pdns.policytypes.ClientIP a match on client IP
pdns.policytypes.ResponseIP a match on response IP
pdns.policytypes.NSDName a match on the name of a nameserver
pdns.policytypes.NSIP a match on the IP of a nameserver

appliedPolicy.policyCustom¶: The CNAME content for the pdns.policyactions.Custom response, a string

appliedPolicy.policyKind¶

The kind of policy response, there are several policy kinds:

pdns.policykinds.Custom will return a NoError, CNAME answer with the value specified in DNSQuestion.appliedPolicy.policyCustom
pdns.policykinds.Drop will simply cause the query to be dropped
pdns.policykinds.NoAction will continue normal processing of the query
pdns.policykinds.NODATA will return a NoError response with no value in the answer section
pdns.policykinds.NXDOMAIN will return a response with a NXDomain rcode
pdns.policykinds.Truncate will return a NoError, no answer, truncated response over UDP. Normal processing will continue over TCP

appliedPolicy.policyTTL¶: The TTL in seconds for the pdns.policyactions.Custom response

appliedPolicy.policyTrigger¶: The trigger (left-hand) part of the RPZ rule that was matched

appliedPolicy.policyHit¶: The value that was matched. This is a string representing a name or an address.

wantsRPZ¶: A boolean that indicates the use of the Policy Engine. Can be set to false in prerpz to disable RPZ for this query.

data¶: A Lua object reference that is persistent throughout the lifetime of the DNSQuestion object for a single query. It can be used to store custom data. Most scripts initialise this to an empty table early on so they can store multiple items.

requestorId¶: Added in version 4.1.0.

A string that will be used to set the requestorId field in protobuf messages.

deviceId¶: Added in version 4.1.0.

A string that will be used to set the deviceId field in protobuf messages.

deviceName¶: Added in version 4.3.0.

A string that will be used to set the deviceName field in protobuf messages.

udpAnswer¶: Answer to the udpQuery when using the udpQueryResponse followupFunction. Only filled when the call-back function is invoked.

udpQueryDest¶: Destination IP address to send the UDP packet to when using the udpQueryResponse followupFunction

udpQuery¶: The content of the UDP payload when using the udpQueryResponse followupFunction

udpCallback¶: The name of the callback function that is called when using the udpQueryResponse followupFunction when an answer is received.

validationState¶: Added in version 4.1.0.

The result of the DNSSEC validation, accessible from the postresolve, nxdomain and nodata hooks. Possible states are pdns.validationstates.Indeterminate, pdns.validationstates.Bogus, pdns.validationstates.Insecure and pdns.validationstates.Secure. The result will always be pdns.validationstates.Indeterminate if validation is disabled or was not requested.

detailedValidationState¶

Added in version 4.4.2.

The result of the DNSSEC validation, accessible from the postresolve, nxdomain and nodata hooks. By contrast with validationState, there are several Bogus states to be able to better understand the reason for a DNSSEC validation failure.

Possible states are:

pdns.validationstates.Indeterminate
pdns.validationstates.BogusNoValidDNSKEY
pdns.validationstates.BogusInvalidDenial
pdns.validationstates.BogusUnableToGetDSs
pdns.validationstates.BogusUnableToGetDNSKEYs
pdns.validationstates.BogusSelfSignedDS
pdns.validationstates.BogusNoRRSIG
pdns.validationstates.BogusNoValidRRSIG
pdns.validationstates.BogusMissingNegativeIndication
pdns.validationstates.BogusSignatureNotYetValid
pdns.validationstates.BogusSignatureExpired
pdns.validationstates.BogusUnsupportedDNSKEYAlgo
pdns.validationstates.BogusUnsupportedDSDigestType
pdns.validationstates.BogusNoZoneKeyBitSet
pdns.validationstates.BogusRevokedDNSKEY
pdns.validationstates.BogusInvalidDNSKEYProtocol
pdns.validationstates.Insecure
pdns.validationstates.Secure

The result will always be pdns.validationstates.Indeterminate is validation is disabled or was not requested. There is a convenience function named isValidationStateBogus that accepts such a state and return a boolean indicating whether this state is a Bogus one.

logResponse¶: Added in version 4.2.0.

Whether the response to this query will be exported to a remote protobuf logger, if one has been configured.

tag¶: The packetcache tag set via gettag() or gettag_ffi(). Default tag is zero. Internally to the recursor, the tag is interpreted as an unsigned 32-bit integer.

queryTime¶

Added in version 4.8.0.

The time the query was received

queryTime.tv_sec¶: The number of seconds since the Unix epoch.

queryTime.tv_usec¶: The number of microseconds, to be added to the number of seconds in DNSQuestion.queryTime.tv_sec to get a high accuracy timestamp.

It also supports the following methods:

addAnswer(type, content, [ttl, name])¶

Add an answer to the record of type with content.

Parameters:¶

type (int) – The type of record to add, can be pdns.AAAA etc.
content (str) – The content of the record, will be parsed into wireformat based on the type
ttl (int) – The TTL in seconds for this record, defaults to 3600
name (DNSName) – The name of this record, defaults to DNSQuestion.qname

addRecord(type, content, place, [ttl, name])¶

Add a record of type with content in section place.

Parameters:¶

type (int) – The type of record to add, can be pdns.AAAA etc.
content (str) – The content of the record, will be parsed into wireformat based on the type
place (int) – The section to place the record, see DNSRecord.place
ttl (int) – The TTL in seconds for this record, defaults to 3600
name (DNSName) – The name of this record, defaults to DNSQuestion.qname

addPolicyTag(tag)¶

Add policyTag tag to the list of policyTags.

Parameters:¶: tag (str) – The tag to add

getPolicyTags(): {str}¶: Get the current policy tags as a table of strings.

setPolicyTags(tags)¶

Set the policy tags to tags, overwriting any existing policy tags.

Parameters:¶: tags ({str}) – The policy tags

discardPolicy(policyname)¶

Skip the filtering policy (for example RPZ) named policyname for this query. This is mostly useful in the prerpz hook.

Parameters:¶: policyname (str) – The name of the policy to ignore.

getDH(): DNSHeader¶: Returns the DNSHeader of the query or nil.

getProxyProtocolValues(): {ProxyProtocolValue}¶: Added in version 4.4.0.

Get the Proxy Protocol Type-Length Values if any, as a table of ProxyProtocolValue objects.

getRecords(): {DNSRecord}¶: Get a table of DNS Records in this DNS Question (or answer by now).

setRecords(records)¶

After your edits, update the answers of this question

Parameters:¶: records ({DNSRecord}) – The records to put in the packet

getEDNSFlag(name): bool¶

Returns true if the EDNS flag with name is set in the query.

Parameters:¶: name (string) – Name of the flag.

getEDNSFlags(): {str}¶: Returns a list of strings with all the EDNS flag mnemonics in the query.

getEDNSOption(num): str¶: Get the EDNS Option with number num as a bytestring.

getEDNSOptions(): {str: str}¶: Get a map of all EDNS Options

getEDNSSubnet(): Netmask¶: Returns the Netmask specified in the EDNSSubnet option, or empty if there was none.

DNSHeader Object¶

The DNS header as returned by DNSQuestion:getDH() represents a header of a DNS message.

class DNSHeader¶

represents a header of a DNS message.

getRD(): bool¶: The value of the Recursion Desired bit.

getAA(): bool¶: The value of the Authoritative Answer bit.

getAD(): bool¶: The value of the Authenticated Data bit.

getCD(): bool¶: The value of the Checking Disabled bit.

getTC(): bool¶: The value of the Truncation bit.

getRCODE(): int¶: The Response Code of the query

getOPCODE(): int¶: The Operation Code of the query

getID(): int¶: The ID of the query

DNSRecord Object¶

See DNSRecord.

The EDNSOptionView Class¶

class EDNSOptionView¶

An object that represents the values of a single EDNS option

count()¶: Added in version 4.2.0.

The number of values for this EDNS option.

getValues()¶: Added in version 4.2.0.

Return a table of NULL-safe strings values for this EDNS option.

size¶: The size in bytes of the first value of this EDNS option.

getContent()¶: Returns a NULL-safe string object of the first value of this EDNS option.

The ProxyProtocolValue Class¶

class ProxyProtocolValue¶

Added in version 4.4.0.

An object that represents the value of a Proxy Protocol Type-Length Value

getContent(): str¶: Returns a NULL-safe string object.

getType(): int¶: Returns the type of this value.

The DNSQuestion (dq) object¶

DNSHeader Object¶

DNSRecord Object¶

The EDNSOptionView Class¶

The ProxyProtocolValue Class¶

The DNSQuestion (`dq`) object¶