The DNSQuestion (dq) object

A DNSQuestion or dq object is available in several hooks and Lua actions. This object contains details about the current state of the question. This state can be modified from the various hooks.

class DNSQuestion

The DNSQuestion object has several attributes, many of them read-only:

dh

The DNSHeader (dh) object of this query.

ecsOverride

Whether an existing ECS value should be overridden, settable.

ecsPrefixLength

The ECS prefix length to use, settable.

len

The length of the data starting at DNSQuestion.dh, including any trailing bytes following the DNS message.

localaddr

ComboAddress of the local bind this question was received on.

opcode

Integer describing the OPCODE of the packet. Can be matched against OPCode.

qclass

QClass (as an unsigned integer) of this question. Can be compared against DNSClass.

qname

DNSName of this question.

qtype

QType (as an unsigned integer) of this question. Can be compared against the pre-defined constants like DNSQType.A, DNSQType.AAAA.

remoteaddr

ComboAddress of the remote client.

rcode

RCode (as an unsigned integer) of this question. Can be compared against RCode

size

The total size of the buffer starting at DNSQuestion.dh.

skipCache

Whether to skip cache lookup / storing the answer for this question, settable.

tcp

Whether the query was received over TCP.

useECS

Whether to send ECS to the backend, settable.

It also supports the following methods:

:addProxyProtocolValue(type, value)

New in version 1.6.0.

Add a proxy protocol TLV entry of type type and value to the current query.

Parameters:
  • type (int) – The type of the new value, ranging from 0 to 255 (both included)
  • value (str) – The binary-safe value
:getDO() → bool

Get the value of the DNSSEC OK bit.

Returns:true if the DO bit was set, false otherwise
:getEDNSOptions() → table

Return the list of EDNS Options, if any.

Returns:A table of EDNSOptionView objects, indexed on the ECS Option code
:getHTTPHeaders() → table

New in version 1.4.0.

Return the HTTP headers for a DoH query, as a table whose keys are the header names and values the header values.

Returns:A table of HTTP headers
:getHTTPHost() → string

New in version 1.4.0.

Return the HTTP Host for a DoH query, which may or may not contain the port.

Returns:The host of the DoH query
:getHTTPPath() → string

New in version 1.4.0.

Return the HTTP path for a DoH query.

Returns:The path part of the DoH query URI
:getHTTPQueryString() → string

New in version 1.4.0.

Return the HTTP query string for a DoH query.

Returns:The query string part of the DoH query URI
:getHTTPScheme() → string

New in version 1.4.0.

Return the HTTP scheme for a DoH query.

Returns:The scheme of the DoH query, for example http or https
:getProtocol() → string

New in version 1.7.0.

Return the transport protocol this query was received over, as a string. The possible values are:

  • “Do53 UDP”
  • “Do53 TCP”
  • “DNSCrypt UDP”
  • “DNSCrypt TCP”
  • “DNS over TLS”
  • “DNS over HTTPS”
Returns:A string
:getProxyProtocolValues() → table

New in version 1.6.0.

Return a table of the Proxy Protocol values currently set for this query.

Returns:A table whose keys are types and values are binary-safe strings
:getServerNameIndication() → string

New in version 1.4.0.

Return the TLS Server Name Indication (SNI) value sent by the client over DoT or DoH, if any. See SNIRule() for more information, especially about the availability of SNI over DoH.

Returns:A string containing the TLS SNI value, if any
:getTag(key) → string

Get the value of a tag stored into the DNSQuestion object.

Parameters:key (string) – The tag’s key
Returns:The tag’s value if it was set, an empty string otherwise
:getTagArray() → table

Get all the tags stored into the DNSQuestion object.

Returns:A table of tags, using strings as keys and values
:getTrailingData() → string

New in version 1.4.0.

Get all data following the DNS message.

Returns:The trailing data as a null-safe string
:sendTrap(reason)

Send an SNMP trap.

Parameters:reason (string) – An optional string describing the reason why this trap was sent
:setHTTPResponse(status, body, contentType="")

New in version 1.4.0.

Set the HTTP status code and content to immediately send back to the client. For HTTP redirects (3xx), the string supplied in body should be the URL to redirect to. For 200 responses, the value of the content type header can be specified via the contentType parameter. In order for the response to be sent, the QR bit should be set before returning and the function should return Action.HeaderModify.

Parameters:
  • status (int) – The HTTP status code to return
  • body (string) – The body of the HTTP response, or a URL if the status code is a redirect (3xx)
  • contentType (string) – The HTTP Content-Type header to return for a 200 response, ignored otherwise. Default is application/dns-message.
:setNegativeAndAdditionalSOA(nxd, zone, ttl, mname, rname, serial, refresh, retry, expire, minimum)

New in version 1.5.0.

Turn a question into a response, either a NXDOMAIN or a NODATA one based on nxd, setting the QR bit to 1 and adding a SOA record in the additional section.

Parameters:
  • nxd (bool) – Whether the answer is a NXDOMAIN (true) or a NODATA (false)
  • zone (string) – The owner name for the SOA record
  • ttl (int) – The TTL of the SOA record
  • mname (string) – The mname of the SOA record
  • rname (string) – The rname of the SOA record
  • serial (int) – The value of the serial field in the SOA record
  • refresh (int) – The value of the refresh field in the SOA record
  • retry (int) – The value of the retry field in the SOA record
  • expire (int) – The value of the expire field in the SOA record
  • minimum (int) – The value of the minimum field in the SOA record
:setProxyProtocolValues(values)

New in version 1.5.0.

Set the Proxy-Protocol Type-Length values to send to the backend along with this query.

Parameters:values (table) – A table of types and values to send, for example: { [0x00] = "foo", [0x42] = "bar" }. Note that the type must be an integer. Try to avoid these values: 0x01 - 0x05, 0x20 - 0x25, 0x30 as those are predefined in https://www.haproxy.org/download/2.3/doc/proxy-protocol.txt (search for PP2_TYPE_ALPN)
:setTag(key, value)

Changed in version 1.7.0: Prior to 1.7.0 calling DNSQuestion:setTag() would not overwrite an existing tag value if already set.

Set a tag into the DNSQuestion object. Overwrites the value if any already exists.

Parameters:
  • key (string) – The tag’s key
  • value (string) – The tag’s value
:setTagArray(tags)

Changed in version 1.7.0: Prior to 1.7.0 calling DNSQuestion:setTagArray() would not overwrite existing tag values if already set.

Set an array of tags into the DNSQuestion object. Overwrites the values if any already exist.

Parameters:tags (table) – A table of tags, using strings as keys and values
:setTrailingData(tail) → bool

New in version 1.4.0.

Set the data following the DNS message, overwriting anything already present.

Parameters:tail (string) – The new data
Returns:true if the operation succeeded, false otherwise
:spoof(ip|ips|raw|raws)

New in version 1.6.0.

Forge a response with the specified record data as raw bytes. If you specify list of raws (it is assumed they match the query type), all will get spoofed in.

Parameters:
  • ip (ComboAddress) – The ComboAddress to be spoofed, e.g. newCA(“192.0.2.1”).
  • ComboAddresses ips (table) – The ComboAddress`es to be spoofed, e.g. `{ newCA(“192.0.2.1”), newCA(“192.0.2.2”) }.
  • raw (string) – The raw string to be spoofed, e.g. “\192\000\002\001”.
  • raws (table) – The raw strings to be spoofed, e.g. { “\192\000\002\001”, “\192\000\002\002” }.

DNSResponse object

class DNSResponse

This object has almost all the functions and members of a DNSQuestion, except for the following ones which are not available on a response:

  • addProxyProtocolValue
  • ecsOverride
  • ecsPrefixLength
  • getProxyProtocolValues
  • getHTTPHeaders
  • getHTTPHost
  • getHTTPPath
  • getHTTPQueryString
  • setHTTPResponse
  • getHTTPScheme
  • getServerNameIndication
  • setNegativeAndAdditionalSOA
  • setProxyProtocolValues
  • spoof
  • tempFailureTTL
  • useECS

If the value is really needed while the response is being processed, it is possible to set a tag while the query is processed, as tags will be passed to the response object. It also has one additional method:

:editTTLs(func)

The function func is invoked for every entry in the answer, authority and additional section.

func points to a function with the following prototype: myFunc(section, qclass, qtype, ttl)

All parameters to func are integers:

  • section is the section in the packet and can be compared to DNS Packet Sections
  • qclass is the QClass of the record. Can be compared to DNSClass
  • qtype is the QType of the record. Can be e.g. compared to DNSQType.A, DNSQType.AAAA constants and the like.
  • ttl is the current TTL

This function must return an integer with the new TTL. Setting this TTL to 0 to leaves it unchanged

Parameters:func (string) – The function to call to edit TTLs.

DNSHeader (dh) object

class DNSHeader

This object holds a representation of a DNS packet’s header.

:getAA() → bool

Get authoritative answer flag.

:getAD() → bool

Get authentic data flag.

:getCD() → bool

Get checking disabled flag.

:getRA() → bool

Get recursion available flag.

:getRD() → bool

Get recursion desired flag.

:setAA(aa)

Set authoritative answer flag.

Parameters:aa (bool) – State of the AA flag
:setAD(ad)

Set authentic data flag.

Parameters:ad (bool) – State of the AD flag
:setCD(cd)

Set checking disabled flag.

Parameters:cd (bool) – State of the CD flag
:setQR(qr)

Set Query/Response flag. Setting QR to true means “This is an answer packet”.

Parameters:qr (bool) – State of the QR flag
:setRA(ra)

Set recursion available flag.

Parameters:ra (bool) – State of the RA flag
:setRD(rd)

Set recursion desired flag.

Parameters:rd (bool) – State of the RD flag
:setTC(tc)

Set truncation flag (TC).

Parameters:tc (bool) – State of the TC flag

EDNSOptionView object

class EDNSOptionView

An object that represents the values of a single EDNS option received in a query.

:count()

The number of values for this EDNS option.

:getValues()

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