YAML response-action reference

ClearRecordTypesResponseAction

Removes given type(s) records from the response. Beware you can accidentally turn the answer into a NODATA response without a SOA record in the additional section in which case you may want to use NegativeAndSOAAction() to generate an answer, see example below. Subsequent rules are processed after this action.

Lua equivalent: ClearRecordTypesResponseAction()

Parameters:

  • types: Sequence of Unsigned integer - List of types to remove

DnstapLogResponseAction

Send the current response to a remote logger as a dnstap message. alter-function is a callback, receiving a DNSResponse and a DnstapMessage, that can be used to modify the message. Subsequent rules are processed after this action

Lua equivalent: DnstapLogResponseAction()

Parameters:

  • identity: String - Server identity to store in the dnstap message

  • logger_name: String - The name of dnstap logger

  • alter_function_name: String ("") - The name of the Lua function that will alter the message

  • alter_function_code: String ("") - The code of the Lua function that will alter the message

  • alter_function_file: String ("") - The path to a file containing the code of the Lua function that will alter the message

LimitTTLResponseAction

Cap the TTLs of the response to the given boundaries

Lua equivalent: LimitTTLResponseAction()

Parameters:

  • min: Unsigned integer - The minimum allowed value

  • max: Unsigned integer - The maximum allowed value

  • types: Sequence of Unsigned integer - The record types to cap the TTL for, as integers. Default is empty which means all records will be capped

LuaFFIResponseAction

Invoke a Lua function that accepts a pointer to a dnsdist_ffi_dnsresponse_t object, whose bindings are defined in dnsdist-lua-ffi-interface.h. The function should return a DNSResponseAction. If the Lua code fails, ServFail is returned

Lua equivalent: LuaFFIResponseAction()

Parameters:

  • function_name: String ("") - The name of the Lua function

  • function_code: String ("") - The code of the Lua function

  • function_file: String ("") - The path to a file containing the code of the Lua function

LuaFFIPerThreadResponseAction

Invoke a Lua function that accepts a pointer to a dnsdist_ffi_dnsresponse_t object, whose bindings are defined in dnsdist-lua-ffi-interface.h. The function should return a DNSResponseAction. If the Lua code fails, ServFail is returned. The function will be invoked in a per-thread Lua state, without access to the global Lua state. All constants (DNSQType, RCode, …) are available in that per-thread context, as well as all FFI functions. Objects and their bindings that are not usable in a FFI context (DNSQuestion, DNSDistProtoBufMessage, PacketCache, …) are not available.

Lua equivalent: LuaFFIPerThreadResponseAction()

Parameters:

  • code: String - The code of the Lua function

RemoteLogResponseAction

Changed in version 2.2.0: Added the export_tags_key_only, export_tags_prefixes and export_tags_strip_prefixes options

Send the current response to a remote logger as a Protocol Buffer message. alter-function is a callback, receiving a DNSResponse and a DNSDistProtoBufMessage, that can be used to modify the message, for example for anonymization purposes. Subsequent rules are processed after this action

Lua equivalent: RemoteLogResponseAction()

Parameters:

  • logger_name: String - The name of the protocol buffer logger

  • alter_function_name: String ("") - The name of the Lua function

  • alter_function_code: String ("") - The code of the Lua function

  • alter_function_file: String ("") - The path to a file containing the code of the Lua function

  • server_id: String ("") - Set the value of the Server Identity field

  • use_server_id: Boolean (false) - Use the general.server_id value to set the Server Identity field

  • ip_encrypt_key: String ("") - A key to encrypt the IP address of the requestor for anonymization purposes. For the “legacy” method, it can be generated via the makeIPCipherKey() function, The encryption method can be set using ip_encrypt_method

  • ip_encrypt_method: String (legacy) - The method to encrypt the IP addresses with. * legacy: The encryption is done using ipcrypt for IPv4 and a 128-bit AES ECB operation for IPv6. This is the default. * ipcrypt-pfx: IPCrypt2, using prefix-preserving encryption. See the ipcrypt website <https://ipcrypt-std.github.io/>__. ip_encrypt_key must be 32 bytes.

  • include_cname: Boolean (false) - Whether or not to parse and export CNAMEs

  • export_extended_errors_to_meta: String ("") - Export Extended DNS Errors present in the DNS response, if any, into the meta Protocol Buffer field using the specified key. The EDE info code will be exported as an integer value, and the EDE extra text, if present, as a string value

  • export_tags: Sequence of String ("") - The comma-separated list of keys of internal tags to export into the tags Protocol Buffer field, as key:value strings. Note that a tag with an empty value will be exported as <key>, not <key>:. An empty string means that no internal tag will be exported. The special value * means that all tags will be exported. See Protobuf Logging Reference for some examples.

  • export_tags_key_only: Boolean (false) - Whether to export tags matched by export_tags or export_tags_prefixes as key (true) or key:value strings (false, the default).

  • export_tags_prefixes: Sequence of String ("") - Internal tags whose keys match at least one of these prefixes will be exported into the tags Protocol Buffer field, as key:value strings (or as key if export_tags_key_only is set). Tags whose keys match at least of the entries in export_tags will be exported as well.

  • export_tags_strip_prefixes: Boolean (false) - Whether to strip the prefix part of the key when exporting a tag matched by one of the prefixes defined in export_tags_prefixes.

  • metas: Sequence of ProtoBufMetaConfiguration - A list of name``=``key pairs, for meta-data to be added to Protocol Buffer message

  • delay: Boolean (false) - Delay sending the protobuf message until after the response has been sent to the client. Useful when using OpenTelemetry Tracing

SNMPTrapResponseAction

Send an SNMP trap, adding the message string as the query description. Subsequent rules are processed after this action

Lua equivalent: SNMPTrapResponseAction()

Parameters:

  • reason: String ("") - The SNMP trap reason

SetEDNSOptionResponseAction

Add arbitrary EDNS option and data to the response. Any existing EDNS content with the same option code will be replaced. Subsequent rules are processed after this action

Lua equivalent: SetEDNSOptionResponseAction()

Parameters:

  • code: Unsigned integer - The EDNS option number

  • data: String - The EDNS0 option raw content

SetExtendedDNSErrorResponseAction

Set an Extended DNS Error status that will be added to the response. Subsequent rules are processed after this action

Lua equivalent: SetExtendedDNSErrorResponseAction()

Parameters:

  • info_code: Unsigned integer - The EDNS Extended DNS Error code

  • extra_text: String ("") - The optional EDNS Extended DNS Error extra text

  • clear_existing_entries: Boolean (true) - Whether to clear existing EDNS Extended DNS Error codes

SetMaxReturnedTTLResponseAction

Cap the TTLs of the response to the given maximum, but only after inserting the response into the packet cache with the initial TTL values

Lua equivalent: SetMaxReturnedTTLResponseAction()

Parameters:

  • max: Unsigned integer - The TTL cap

SetMaxTTLResponseAction

Cap the TTLs of the response to the given maximum

Lua equivalent: SetMaxTTLResponseAction()

Parameters:

  • max: Unsigned integer - The TTL cap

SetMinTTLResponseAction

Cap the TTLs of the response to the given minimum

Lua equivalent: SetMinTTLResponseAction()

Parameters:

  • min: Unsigned integer - The TTL cap

SetReducedTTLResponseAction

Reduce the TTL of records in a response to a percentage of the original TTL. For example, passing 50 means that the original TTL will be cut in half. Subsequent rules are processed after this action

Lua equivalent: SetReducedTTLResponseAction()

Parameters:

  • percentage: Unsigned integer - The percentage to use

SetSkipCacheResponseAction

Don’t store this answer in the cache. Subsequent rules are processed after this action.

Lua equivalent: SetSkipCacheResponseAction()

SetTagResponseAction

Associate a tag named tag with a value of value to this response. This function will overwrite any existing tag value. Subsequent rules are processed after this action

Lua equivalent: SetTagResponseAction()

Parameters:

  • tag: String - The tag name

  • value: String - The tag value

TCResponseAction

Truncate an existing answer, to force the client to TCP. Only applied to answers that will be sent to the client over TCP. In addition to the TC bit being set, all records are removed from the answer, authority and additional sections

Lua equivalent: TCResponseAction()

UnsetTagResponseAction

Remove a tag named tag from this response. Subsequent rules are processed after this action

Lua equivalent: UnsetTagResponseAction()

Parameters:

  • tag: String - The tag name

AllowResponseAction

Let these packets go through.

Lua equivalent: AllowResponseAction()

DelayResponseAction

Delay the response by the specified amount of milliseconds (UDP-only). Note that the sending of the query to the backend, if needed, is not delayed. Only the sending of the response to the client will be delayed. Subsequent rules are processed after this action

Lua equivalent: DelayResponseAction()

Parameters:

  • msec: Unsigned integer - The amount of milliseconds to delay the response

DropResponseAction

Drop the packet

Lua equivalent: DropResponseAction()

LogResponseAction

Log a line for each response, to the specified file if any, to the console (require verbose) if the empty string is given as filename. If an empty string is supplied in the file name, the logging is done to stdout, and only in verbose mode by default. This can be changed by setting verbose-only to false. The append parameter specifies whether we open the file for appending or truncate each time (default). The buffered parameter specifies whether writes to the file are buffered (default) or not. Subsequent rules are processed after this action

Lua equivalent: LogResponseAction()

Parameters:

  • file_name: String ("") - File to log to. Set to an empty string to log to the normal stdout log, this only works when -v is set on the command line

  • append: Boolean (false) - Whether to append to an existing file

  • buffered: Boolean (false) - Whether to use buffered I/O

  • verbose_only: Boolean (true) - Whether to log only in verbose mode when logging to stdout

  • include_timestamp: Boolean (false) - Whether to include a timestamp for every entry

LuaResponseAction

Invoke a Lua function that accepts a DNSResponse. The function should return a DNSResponseAction. If the Lua code fails, ServFail is returned

Lua equivalent: LuaResponseAction()

Parameters:

  • function_name: String ("") - The name of the Lua function

  • function_code: String ("") - The code of the Lua function

  • function_file: String ("") - The path to a file containing the code of the Lua function