parameters:
- name: "action"
type: "Action"
+ description: "The action to execute"
- name: "delay"
description: "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"
parameters:
- name: "msec"
type: "u32"
+ description: "The amount of milliseconds to delay the response"
- name: "DnstapLog"
skip-cpp: true
skip-rust: true
parameters:
- name: "identity"
type: "String"
+ description: "Server identity to store in the dnstap message"
- name: "logger_name"
type: "String"
+ description: "The name of dnstap logger"
- name: "alter_function_name"
type: "String"
default: ""
+ description: "The name of the Lua function that will alter the message"
- name: "alter_function_code"
type: "String"
default: ""
+ description: "The code of the Lua function that will alter the message"
- name: "alter_function_file"
type: "String"
default: ""
+ description: "The path to a file containing the code of the Lua function that will alter the message"
- name: "drop"
description: "Drop the packet"
- name: "SetEDNSOption"
parameters:
- name: "code"
type: "u32"
+ description: "The EDNS option number"
- name: "data"
type: "String"
+ description: "The EDNS0 option raw content"
- name: "ERCode"
description: "Reply immediately by turning the query into a response with the specified EDNS extended rcode"
skip-cpp: true
parameters:
- name: "rcode"
type: "u8"
+ description: "The RCODE to respond with"
- name: "vars"
type: "ResponseConfig"
default: true
+ description: "The response options"
- name: "HTTPStatus"
description: "Return an HTTP response with a status code of ``status``. For HTTP redirects, ``body`` should be the redirect URL"
skip-cpp: true
parameters:
- name: "status"
type: "u16"
+ description: "The HTTP status code to return"
- name: "body"
rust-type: "String"
type: "PacketBuffer"
+ description: "The body of the HTTP response, or a URL if the status code is a redirect (3xx)"
- name: "content_type"
type: "String"
default: ""
+ description: "The HTTP Content-Type header to return for a 200 response, ignored otherwise. Default is ``application/dns-message``"
- name: "vars"
type: "ResponseConfig"
default: true
+ description: "The response options"
- name: "KeyValueStoreLookup"
description: "Does a lookup into the key value store using the key returned by ``lookup_key_name``, and storing the result if any into the tag named ``destination_tag``. The store can be a ``CDB`` or a ``LMDB`` database. The key can be based on the qname, source IP or the value of an existing tag. Subsequent rules are processed after this action. Note that the tag is always created, even if there was no match, but in that case the content is empty"
skip-cpp: true
parameters:
- name: "kvs_name"
type: "String"
+ description: "The name of the KV store"
- name: "lookup_key_name"
type: "String"
+ description: "The name of the key to use for the lookup"
- name: "destination_tag"
type: "String"
+ description: "The name of the tag to store the result into"
- name: "KeyValueStoreRangeLookup"
description: "Does a range-based lookup into the key value store using the key returned by ``lookup_key_name``, and storing the result if any into the tag named ``destination_tag``. This assumes that there is a key in network byte order for the last element of the range (for example ``2001:0db8:ffff:ffff:ffff:ffff:ffff:ffff`` for ``2001:db8::/32``) which contains the first element of the range (``2001:0db8:0000:0000:0000:0000:0000:0000``) (optionally followed by any data) as value, also in network byte order, and that there is no overlapping ranges in the database. This requires that the underlying store supports ordered keys, which is true for LMDB but not for CDB"
skip-cpp: true
parameters:
- name: "kvs_name"
type: "String"
+ description: "The name of the KV store"
- name: "lookup_key_name"
type: "String"
+ description: "The name of the key to use for the lookup"
- name: "destination_tag"
type: "String"
+ description: "The name of the tag to store the result into"
- name: "log"
description: "Log a line for each query, 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``.
type: "String"
default: ""
cpp-optional: false
+ description: "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"
- name: "binary"
type: "bool"
default: "true"
cpp-optional: false
+ description: "Whether to do binary logging"
- name: "append"
type: "bool"
default: "false"
cpp-optional: false
+ description: "Whether to append to an existing file"
- name: "buffered"
type: "bool"
default: "false"
cpp-optional: false
+ description: "Whether to use buffered I/O"
- name: "verbose_only"
type: "bool"
default: "true"
cpp-optional: false
+ description: "Whether to log only in verbose mode when logging to stdout"
- name: "include_timestamp"
type: "bool"
default: "false"
cpp-optional: false
+ description: "Whether to include a timestamp for every entry"
- name: "lua"
description: "Invoke a Lua function that accepts a :class:`DNSQuestion`. The function should return a :ref:`DNSAction`. If the Lua code fails, ``ServFail`` is returned"
skip-cpp: true
- name: "function_name"
type: "String"
default: ""
+ description: "The name of the Lua function"
- name: "function_code"
type: "String"
default: ""
+ description: "The code of the Lua function"
- name: "function_file"
type: "String"
default: ""
+ description: "The path to a file containing the code of the Lua function"
- name: "LuaFFI"
description: "Invoke a Lua function that accepts a pointer to a ``dnsdist_ffi_dnsquestion_t`` object, whose bindings are defined in ``dnsdist-lua-ffi-interface.h``. The function should return a :ref:`DNSAction`. If the Lua code fails, ``ServFail`` is returned"
skip-cpp: true
- name: "function_name"
type: "String"
default: ""
+ description: "The name of the Lua function"
- name: "function_code"
type: "String"
default: ""
+ description: "The code of the Lua function"
- name: "function_file"
type: "String"
default: ""
+ description: "The path to a file containing the code of the Lua function"
- name: "LuaFFIPerThread"
description: "Invoke a Lua function that accepts a pointer to a ``dnsdist_ffi_dnsquestion_t`` object, whose bindings are defined in ``dnsdist-lua-ffi-interface.h``. The function should return a :ref:`DNSAction`. 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 (:ref:`DNSQType`, :ref:`DNSRCode`, ...) 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 (:class:`DNSQuestion`, :class:`DNSDistProtoBufMessage`, :class:`PacketCache`, ...) are not available."
parameters:
- name: "code"
type: "String"
+ description: "The code of the Lua function"
- name: "NegativeAndSOA"
description: "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"
skip-cpp: true
parameters:
- name: "nxd"
type: "bool"
+ description: "Whether the answer is a NXDOMAIN (true) or a NODATA (false)"
- name: "zone"
type: "DNSName"
rust-type: "String"
+ description: "The owner name for the SOA record"
- name: "ttl"
type: "u32"
+ description: "The TTL of the SOA record"
- name: "mname"
type: "DNSName"
rust-type: "String"
+ description: "The mname of the SOA record"
- name: "rname"
type: "DNSName"
rust-type: "String"
+ description: "The rname of the SOA record"
- name: "soa_parameters"
type: "SOAParams"
+ description: "The fields of the SOA record"
- name: "soa_in_authority"
type: "bool"
default: "false"
+ description: "Whether the SOA record should be the authority section for a complete NXDOMAIN/NODATA response that works as a cacheable negative response, rather than the RPZ-style response with a purely informational SOA in the additional section. Default is false (SOA in additional section)"
- name: "vars"
type: "ResponseConfig"
default: true
+ description: "Response options"
- name: "none"
description: "Does nothing. Subsequent rules are processed after this action"
- name: "pool"
parameters:
- name: "pool_name"
type: "String"
+ description: "The name of the pool"
- name: "stop_processing"
type: "bool"
default: "true"
cpp-optional: false
+ description: "Whether subsequent rules should be executed after this one"
- name: "QPS"
description: "Drop a packet if it does exceed the ``limit`` queries per second limit. Letting the subsequent rules apply otherwise"
parameters:
- name: "limit"
type: "u32"
+ description: "The QPS limit"
- name: "QPSPool"
description: "Send the packet into the specified pool only if it does not exceed the ``limit`` queries per second limit. If ``stop-processing`` is set to ``false``, subsequent rules will be processed after this action. Letting the subsequent rules apply otherwise"
parameters:
- name: "limit"
type: "u32"
+ description: "The QPS limit"
- name: "pool_name"
type: "String"
+ description: "The name of the pool"
- name: "stop_processing"
type: "bool"
default: "true"
cpp-optional: false
+ description: "Whether subsequent rules should be executed after this one"
- name: "RCode"
description: "Reply immediately by turning the query into a response with the specified rcode"
skip-cpp: true
parameters:
- name: "rcode"
type: "u8"
+ description: "The response code"
- name: "vars"
type: "ResponseConfig"
default: true
+ description: "Response options"
- name: "RemoteLog"
skip-cpp: true
skip-rust: true
parameters:
- name: "logger_name"
type: "String"
+ description: "The name of the protocol buffer logger"
- name: "alter_function_name"
type: "String"
default: ""
+ description: "The name of the Lua function"
- name: "alter_function_code"
type: "String"
default: ""
+ description: "The code of the Lua function"
- name: "alter_function_file"
type: "String"
default: ""
+ description: "The path to a file containing the code of the Lua function"
- name: "server_id"
type: "String"
default: ""
+ description: "Set the Server Identity field"
- name: "ip_encrypt_key"
type: "String"
default: ""
+ description: "A key, that can be generated via the :func:`makeIPCipherKey` function, to encrypt the IP address of the requestor for anonymization purposes. The encryption is done using ipcrypt for IPv4 and a 128-bit AES ECB operation for IPv6"
- name: "export_tags"
type: "Vec<String>"
default: ""
+ description: "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"
- name: "metas"
type: "Vec<ProtoBufMetaConfiguration>"
default: true
+ description: "A list of ``name``=``key`` pairs, for meta-data to be added to Protocol Buffer message"
- name: "SetAdditionalProxyProtocolValue"
description: "Add a Proxy-Protocol Type-Length value to be sent to the server along with this query. It does not replace any existing value with the same type but adds a new value. Be careful that Proxy Protocol values are sent once at the beginning of the TCP connection for TCP and DoT queries. That means that values received on an incoming TCP connection will be inherited by subsequent queries received over the same incoming TCP connection, if any, but values set to a query will not be inherited by subsequent queries. Subsequent rules
are processed after this action"
parameters:
- name: "proxy_type"
type: "u8"
+ description: "The proxy protocol type"
- name: "value"
type: "String"
+ description: "The value"
- name: "SetDisableECS"
description: "Disable the sending of ECS to the backend. Subsequent rules are processed after this action"
- name: "SetDisableValidation"
parameters:
- name: "ipv4"
type: "String"
+ description: "The IPv4 netmask, for example 192.0.2.1/32"
- name: "ipv6"
type: "String"
default: ""
+ description: "The IPv6 netmask, if any"
cpp-optional: false
- name: "SetECSOverride"
description: "Whether an existing EDNS Client Subnet value should be overridden (true) or not (false). Subsequent rules are processed after this action"
parameters:
- name: "override_existing"
type: "bool"
+ description: "Whether to override an existing EDNS Client Subnet value"
- name: "SetECSPrefixLength"
description: "Set the ECS prefix length. Subsequent rules are processed after this action"
parameters:
- name: "ipv4"
type: "u16"
+ description: "The IPv4 netmask length"
- name: "ipv6"
type: "u16"
+ description: "The IPv6 netmask length"
- name: "SetExtendedDNSError"
description: "Set an Extended DNS Error status that will be added to the response corresponding to the current query. Subsequent rules are processed after this action"
parameters:
- name: "info_code"
type: "u16"
+ description: "The EDNS Extended DNS Error code"
- name: "extra_text"
type: "String"
default: ""
cpp-optional: false
+ description: "The optional EDNS Extended DNS Error extra text"
- name: "SetMacAddr"
- description: "Add the source MAC address to the query as EDNS0 option option. This action is currently only supported on Linux. Subsequent rules are processed after this action"
+ description: "Add the source MAC address to the query as an EDNS0 option. This action is currently only supported on Linux. Subsequent rules are processed after this action"
parameters:
- name: "code"
type: "u32"
+ description: "The EDNS option code"
- name: "SetMaxReturnedTTL"
description: "Cap the TTLs of the response to the given maximum, but only after inserting the response into the packet cache with the initial TTL value"
skip-cpp: true
parameters:
- name: "max"
type: "u32"
+ description: "The TTL cap"
- name: "SetNoRecurse"
description: "Strip RD bit from the question, let it go through. Subsequent rules are processed after this action"
- name: "SetProxyProtocolValues"
- name: "values"
type: "Vec<ProxyProtocolValueConfiguration>"
default: true
+ description: "List of proxy protocol values"
- name: "SetSkipCache"
description: "Don’t lookup the cache for this query, don’t store the answer. Subsequent rules are processed after this action."
- name: "SetTag"
parameters:
- name: "tag"
type: "String"
+ description: "The tag name"
- name: "value"
type: "String"
+ description: "The tag value"
- name: "SetTempFailureCacheTTL"
description: "Set the cache TTL to use for ServFail and Refused replies. TTL is not applied for successful replies. Subsequent rules are processed after this action"
parameters:
- - name: "maxTTL"
+ - name: "ttl"
type: "u32"
+ description: "The TTL to use"
- name: "SNMPTrap"
description: "Send an SNMP trap, adding the message string as the query description. Subsequent rules are processed after this action"
parameters:
type: "String"
default: ""
cpp-optional: false
+ description: "The SNMP trap reason"
- name: "Spoof"
description: "Forge a response with the specified IPv4 (for an A query) or IPv6 (for an AAAA) addresses. If you specify multiple addresses, all that match the query type (A, AAAA or ANY) will get spoofed in"
skip-cpp: true
parameters:
- name: "ips"
type: "Vec<String>"
+ description: "List of IP addresses to spoof"
- name: "vars"
type: "ResponseConfig"
default: true
+ description: "Response options"
- name: "SpoofCNAME"
description: "Forge a response with the specified CNAME value. Please be aware that DNSdist will not chase the target of the CNAME, so it will not be present in the response which might be a problem for stub resolvers that do not know how to follow a CNAME"
skip-cpp: true
parameters:
- name: "cname"
type: "String"
+ description: "The CNAME to use in the response"
- name: "vars"
type: "ResponseConfig"
default: true
+ description: "Response options"
- name: "SpoofPacket"
description: "Spoof a raw self-generated answer"
skip-cpp: true
parameters:
- name: "response"
type: "String"
+ description: "The DNS packet"
- name: "len"
type: "u32"
+ description: "The length of the DNS packet"
- name: "SpoofRaw"
- description: "Forge a response with the specified raw bytes as record data"
+ description: |
+ Forge a response with the specified raw bytes as record data
+ .. code-block:: Lua
+
+ -- select queries for the 'raw.powerdns.com.' name and TXT type, and answer with both a "aaa" "bbbb" and "ccc" TXT record:
+ addAction(AndRule({QNameRule('raw.powerdns.com.'), QTypeRule(DNSQType.TXT)}), SpoofRawAction({"\003aaa\004bbbb", "\003ccc"}))
+ -- select queries for the 'raw-srv.powerdns.com.' name and SRV type, and answer with a '0 0 65535 srv.powerdns.com.' SRV record, setting the AA bit to 1 and the TTL to 3600s
+ addAction(AndRule({QNameRule('raw-srv.powerdns.com.'), QTypeRule(DNSQType.SRV)}), SpoofRawAction("\000\000\000\000\255\255\003srv\008powerdns\003com\000", { aa=true, ttl=3600 }))
+ -- select reverse queries for '127.0.0.1' and answer with 'localhost'
+ addAction(AndRule({QNameRule('1.0.0.127.in-addr.arpa.'), QTypeRule(DNSQType.PTR)}), SpoofRawAction("\009localhost\000"))
+ -- rfc8482: Providing Minimal-Sized Responses to DNS Queries That Have QTYPE=ANY via HINFO of value "rfc8482"
+ addAction(QTypeRule(DNSQType.ANY), SpoofRawAction("\007rfc\056\052\056\050\000", { typeForAny=DNSQType.HINFO }))
+
+ :func:`DNSName:toDNSString` is convenient for converting names to wire format for passing to ``SpoofRawAction``.
+
+ ``sdig dumpluaraw`` and ``pdnsutil raw-lua-from-content`` from PowerDNS can generate raw answers for you:
+
+ .. code-block:: Shell
+
+ $ pdnsutil raw-lua-from-content SRV '0 0 65535 srv.powerdns.com.'
+ "\000\000\000\000\255\255\003srv\008powerdns\003com\000"
+ $ sdig 127.0.0.1 53 open-xchange.com MX recurse dumpluaraw
+ Reply to question for qname='open-xchange.com.', qtype=MX
+ Rcode: 0 (No Error), RD: 1, QR: 1, TC: 0, AA: 0, opcode: 0
+ 0 open-xchange.com. IN MX "\000c\004mx\049\049\012open\045xchange\003com\000"
+ 0 open-xchange.com. IN MX "\000\010\003mx\049\012open\045xchange\003com\000"
+ 0 open-xchange.com. IN MX "\000\020\003mx\050\012open\045xchange\003com\000"
skip-cpp: true
skip-rust: true
parameters:
- name: "answers"
type: "Vec<String>"
+ description: "A list of DNS record content entries to use in the response"
- name: "qtype_for_any"
type: "String"
default: ""
+ description: "The type to use for ANY queries"
- name: "vars"
type: "ResponseConfig"
default: true
+ description: "Response options"
- name: "SpoofSVC"
description: "Forge a response with the specified ``SVC`` record data. If the list contains more than one ``SVC`` parameter, they are all returned, and should have different priorities. The hints provided in the SVC parameters, if any, will also be added as ``A``/``AAAA`` records in the additional section, using the target name present in the parameters as owner name if it’s not empty (root) and the qname instead"
skip-cpp: true
parameters:
- name: "parameters"
type: "Vec<SVCRecordParameters>"
+ description: "List of SVC record parameters"
- name: "vars"
type: "ResponseConfig"
default: true
+ description: "Response options"
- name: "TC"
description: "Create answer to query with the ``TC`` bit set, and the ``RA`` bit set to the value of ``RD`` in the query, to force the client to TCP"
- name: "tee"
- name: "rca"
type: "ComboAddress"
rust-type: "String"
+ description: "The address and port of the remote server"
- name: "lca"
type: "ComboAddress"
rust-type: "String"
default: ""
+ description: "The source address to use to send packets to the remote server"
- name: "add_ecs"
type: "bool"
default: "false"
+ description: "Whether to add EDNS Client Subnet to the query"
- name: "add_proxy_protocol"
type: "bool"
default: "false"
+ description: "Whether to add a proxy protocol payload to the query"
{
return std::shared_ptr<DNSAction>(new SetTagAction(tag, value));
}
-std::shared_ptr<DNSAction> getSetTempFailureCacheTTLAction(uint32_t maxTTL)
+std::shared_ptr<DNSAction> getSetTempFailureCacheTTLAction(uint32_t ttl)
{
- return std::shared_ptr<DNSAction>(new SetTempFailureCacheTTLAction(maxTTL));
+ return std::shared_ptr<DNSAction>(new SetTempFailureCacheTTLAction(ttl));
}
std::shared_ptr<DNSAction> getSNMPTrapAction(const std::string& reason)
{
std::shared_ptr<DNSAction> getSetNoRecurseAction();
std::shared_ptr<DNSAction> getSetSkipCacheAction();
std::shared_ptr<DNSAction> getSetTagAction(const std::string& tag, const std::string& value);
-std::shared_ptr<DNSAction> getSetTempFailureCacheTTLAction(uint32_t maxTTL);
+std::shared_ptr<DNSAction> getSetTempFailureCacheTTLAction(uint32_t ttl);
std::shared_ptr<DNSAction> getSNMPTrapAction(const std::string& reason);
std::shared_ptr<DNSAction> getTCAction();
luaCtx.writeFunction("SetTagAction", [](std::string tag, std::string value) {
return dnsdist::actions::getSetTagAction(tag, value);
});
-luaCtx.writeFunction("SetTempFailureCacheTTLAction", [](uint32_t maxTTL) {
- return dnsdist::actions::getSetTempFailureCacheTTLAction(maxTTL);
+luaCtx.writeFunction("SetTempFailureCacheTTLAction", [](uint32_t ttl) {
+ return dnsdist::actions::getSetTempFailureCacheTTLAction(ttl);
});
luaCtx.writeFunction("SNMPTrapAction", [](boost::optional<std::string> reason) {
return dnsdist::actions::getSNMPTrapAction(reason ? *reason : "");
luaCtx.writeFunction("DropResponseAction", []() {
return dnsdist::actions::getDropResponseAction();
});
-luaCtx.writeFunction("LogResponseAction", [](boost::optional<std::string> fileName, boost::optional<bool> append, boost::optional<bool> buffered, boost::optional<bool> verboseOnly, boost::optional<bool> includeTimestamp) {
- return dnsdist::actions::getLogResponseAction(fileName ? *fileName : "", append ? *append : false, buffered ? *buffered : false, verboseOnly ? *verboseOnly : true, includeTimestamp ? *includeTimestamp : false);
+luaCtx.writeFunction("LogResponseAction", [](boost::optional<std::string> file_name, boost::optional<bool> append, boost::optional<bool> buffered, boost::optional<bool> verbose_only, boost::optional<bool> include_timestamp) {
+ return dnsdist::actions::getLogResponseAction(file_name ? *file_name : "", append ? *append : false, buffered ? *buffered : false, verbose_only ? *verbose_only : true, include_timestamp ? *include_timestamp : false);
});
luaCtx.writeFunction("LuaFFIPerThreadResponseAction", [](std::string code) {
return dnsdist::actions::getLuaFFIPerThreadResponseAction(code);
});
-luaCtx.writeFunction("SetExtendedDNSErrorResponseAction", [](uint16_t infoCode, boost::optional<std::string> extraText) {
- return dnsdist::actions::getSetExtendedDNSErrorResponseAction(infoCode, extraText ? *extraText : "");
+luaCtx.writeFunction("SetExtendedDNSErrorResponseAction", [](uint16_t info_code, boost::optional<std::string> extra_text) {
+ return dnsdist::actions::getSetExtendedDNSErrorResponseAction(info_code, extra_text ? *extra_text : "");
});
luaCtx.writeFunction("SetReducedTTLResponseAction", [](uint8_t percentage) {
return dnsdist::actions::getSetReducedTTLResponseAction(percentage);
parameters:
- name: "msec"
type: "u32"
+ description: "The amount of milliseconds to delay the response"
- name: "DnstapLog"
description: "Send the current response to a remote logger as a dnstap message. ``alter-function`` is a callback, receiving a :class:`DNSResponse` and a :class:`DnstapMessage`, that can be used to modify the message. Subsequent rules are processed after this action"
skip-cpp: true
parameters:
- name: "identity"
type: "String"
- - name: "logger-name"
+ description: "Server identity to store in the dnstap message"
+ - name: "logger_name"
type: "String"
- - name: "alter-function_name"
+ description: "The name of dnstap logger"
+ - name: "alter_function_name"
type: "String"
default: ""
- - name: "alter-function-code"
+ description: "The name of the Lua function that will alter the message"
+ - name: "alter_function_code"
type: "String"
default: ""
- - name: "alter-function-file"
+ description: "The code of the Lua function that will alter the message"
+ - name: "alter_function_file"
type: "String"
default: ""
+ description: "The path to a file containing the code of the Lua function that will alter the message"
- name: "drop"
description: "Drop the packet"
- name: "LimitTTL"
parameters:
- name: "min"
type: "u32"
+ description: "The minimum allowed value"
- name: "max"
type: "u32"
+ description: "The maximum allowed value"
- name: "types"
type: "Vec<u16>"
default: true
+ description: "The record types to cap the TTL for, as integers. Default is empty which means all records will be capped"
- name: "log"
description: "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``.
-When logging to a file, the ``binary`` parameter specifies whether we log in binary form (default) or in textual form. 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.
+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"
parameters:
- - name: "file-name"
+ - name: "file_name"
type: "String"
default: ""
cpp-optional: false
+ description: "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"
- name: "append"
type: "bool"
default: "false"
cpp-optional: false
+ description: "Whether to append to an existing file"
- name: "buffered"
type: "bool"
default: "false"
cpp-optional: false
- - name: "verbose-only"
+ description: "Whether to use buffered I/O"
+ - name: "verbose_only"
type: "bool"
default: "true"
cpp-optional: false
- - name: "include-timestamp"
+ description: "Whether to log only in verbose mode when logging to stdout"
+ - name: "include_timestamp"
type: "bool"
default: "false"
cpp-optional: false
+ description: "Whether to include a timestamp for every entry"
- name: "lua"
description: "Invoke a Lua function that accepts a :class:`DNSResponse`. The function should return a :ref:`DNSResponseAction`. If the Lua code fails, ``ServFail`` is returned"
skip-cpp: true
skip-rust: true
parameters:
- - name: "function-name"
+ - name: "function_name"
type: "String"
default: ""
- - name: "function-code"
+ description: "The name of the Lua function"
+ - name: "function_code"
type: "String"
default: ""
- - name: "function-file"
+ description: "The code of the Lua function"
+ - name: "function_file"
type: "String"
default: ""
+ description: "The path to a file containing the code of the Lua function"
- name: "LuaFFI"
description: "Invoke a Lua function that accepts a pointer to a ``dnsdist_ffi_dnsquestion_t`` object, whose bindings are defined in ``dnsdist-lua-ffi-interface.h``. The function should return a :ref:`DNSResponseAction`. If the Lua code fails, ``ServFail`` is returned"
skip-cpp: true
skip-rust: true
parameters:
- - name: "function-name"
+ - name: "function_name"
type: "String"
default: ""
- - name: "function-code"
+ description: "The name of the Lua function"
+ - name: "function_code"
type: "String"
default: ""
- - name: "function-file"
+ description: "The code of the Lua function"
+ - name: "function_file"
type: "String"
default: ""
+ description: "The path to a file containing the code of the Lua function"
- name: "LuaFFIPerThread"
description: "Invoke a Lua function that accepts a pointer to a ``dnsdist_ffi_dnsquestion_t`` object, whose bindings are defined in ``dnsdist-lua-ffi-interface.h``. The function should return a :ref:`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 (:ref:`DNSQType`, :ref:`DNSRCode`, ...) 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 (:class:`DNSQuestion`, :class:`DNSDistProtoBufMessage`, :class:`PacketCache`, ...) are not available."
parameters:
- name: "code"
type: "String"
+ description: "The code of the Lua function"
- name: "RemoteLog"
description: "Send the current response to a remote logger as a Protocol Buffer message. ``alter-function`` is a callback, receiving a :class:`DNSResponse` and a :class:`DNSDistProtoBufMessage`, that can be used to modify the message, for example for anonymization purposes. Subsequent rules are processed after this action"
skip-cpp: true
skip-rust: true
parameters:
- - name: "logger-name"
+ - name: "logger_name"
type: "String"
- - name: "alter-function-name"
+ description: "The name of the protocol buffer logger"
+ - name: "alter_function_name"
type: "String"
default: ""
- - name: "alter-function-code"
+ description: "The name of the Lua function"
+ - name: "alter_function_code"
type: "String"
default: ""
- - name: "alter-function-file"
+ description: "The code of the Lua function"
+ - name: "alter_function_file"
type: "String"
default: ""
- - name: "server-id"
+ description: "The path to a file containing the code of the Lua function"
+ - name: "server_id"
type: "String"
default: ""
- - name: "ip-encrypt-key"
+ description: "Set the Server Identity field"
+ - name: "ip_encrypt_key"
type: "String"
default: ""
- - name: "include-cname"
+ description: "A key, that can be generated via the :func:`makeIPCipherKey` function, to encrypt the IP address of the requestor for anonymization purposes. The encryption is done using ipcrypt for IPv4 and a 128-bit AES ECB operation for IPv6"
+ - name: "include_cname"
type: "bool"
default: "false"
- - name: "export-tags"
+ description: "Whether or not to parse and export CNAMEs"
+ - name: "export_tags"
type: "Vec<String>"
- default: true
- - name: "export-extended-errors-to-meta"
+ default: ""
+ description: "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"
+ - name: "export_extended_errors_to_meta"
type: "String"
default: ""
+ description: "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"
- name: "metas"
type: "Vec<ProtoBufMetaConfiguration>"
default: true
+ description: "A list of ``name``=``key`` pairs, for meta-data to be added to Protocol Buffer message"
- name: "SetExtendedDNSError"
description: "Set an Extended DNS Error status that will be added to the response. Subsequent rules are processed after this action"
parameters:
- - name: "info-code"
+ - name: "info_code"
type: "u16"
- - name: "extra-text"
+ description: "The EDNS Extended DNS Error code"
+ - name: "extra_text"
type: "String"
default: ""
cpp-optional: false
+ description: "The optional EDNS Extended DNS Error extra text"
- name: "SetMaxReturnedTTL"
description: "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"
skip-cpp: true
parameters:
- name: "max"
type: "u32"
+ description: "The TTL cap"
- name: "SetMaxTTL"
description: "Cap the TTLs of the response to the given maximum"
skip-cpp: true
parameters:
- name: "max"
type: "u32"
+ description: "The TTL cap"
- name: "SetMinTTL"
description: "Cap the TTLs of the response to the given minimum"
skip-cpp: true
parameters:
- name: "min"
type: "u32"
+ description: "The TTL cap"
- name: "SetReducedTTL"
description: "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"
parameters:
- name: "percentage"
type: "u8"
+ description: "The percentage to use"
- name: "SetSkipCache"
description: "Don’t store this answer in the cache. Subsequent rules are processed after this action."
- name: "SetTag"
parameters:
- name: "tag"
type: "String"
+ description: "The tag name"
- name: "value"
type: "String"
+ description: "The tag value"
- name: "SNMPTrap"
description: "Send an SNMP trap, adding the message string as the query description. Subsequent rules are processed after this action"
parameters:
type: "String"
default: ""
cpp-optional: false
+ description: "The SNMP trap reason"
- name: "TC"
description: "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"
{
return std::shared_ptr<DNSResponseAction>(new DropResponseAction());
}
-std::shared_ptr<DNSResponseAction> getLogResponseAction(const std::string& fileName, bool append, bool buffered, bool verboseOnly, bool includeTimestamp)
+std::shared_ptr<DNSResponseAction> getLogResponseAction(const std::string& file_name, bool append, bool buffered, bool verbose_only, bool include_timestamp)
{
- return std::shared_ptr<DNSResponseAction>(new LogResponseAction(fileName, append, buffered, verboseOnly, includeTimestamp));
+ return std::shared_ptr<DNSResponseAction>(new LogResponseAction(file_name, append, buffered, verbose_only, include_timestamp));
}
std::shared_ptr<DNSResponseAction> getLuaFFIPerThreadResponseAction(const std::string& code)
{
return std::shared_ptr<DNSResponseAction>(new LuaFFIPerThreadResponseAction(code));
}
-std::shared_ptr<DNSResponseAction> getSetExtendedDNSErrorResponseAction(uint16_t infoCode, const std::string& extraText)
+std::shared_ptr<DNSResponseAction> getSetExtendedDNSErrorResponseAction(uint16_t info_code, const std::string& extra_text)
{
- return std::shared_ptr<DNSResponseAction>(new SetExtendedDNSErrorResponseAction(infoCode, extraText));
+ return std::shared_ptr<DNSResponseAction>(new SetExtendedDNSErrorResponseAction(info_code, extra_text));
}
std::shared_ptr<DNSResponseAction> getSetReducedTTLResponseAction(uint8_t percentage)
{
std::shared_ptr<DNSResponseAction> getAllowResponseAction();
std::shared_ptr<DNSResponseAction> getDelayResponseAction(uint32_t msec);
std::shared_ptr<DNSResponseAction> getDropResponseAction();
-std::shared_ptr<DNSResponseAction> getLogResponseAction(const std::string& fileName, bool append, bool buffered, bool verboseOnly, bool includeTimestamp);
+std::shared_ptr<DNSResponseAction> getLogResponseAction(const std::string& file_name, bool append, bool buffered, bool verbose_only, bool include_timestamp);
std::shared_ptr<DNSResponseAction> getLuaFFIPerThreadResponseAction(const std::string& code);
-std::shared_ptr<DNSResponseAction> getSetExtendedDNSErrorResponseAction(uint16_t infoCode, const std::string& extraText);
+std::shared_ptr<DNSResponseAction> getSetExtendedDNSErrorResponseAction(uint16_t info_code, const std::string& extra_text);
std::shared_ptr<DNSResponseAction> getSetReducedTTLResponseAction(uint8_t percentage);
std::shared_ptr<DNSResponseAction> getSetSkipCacheResponseAction();
std::shared_ptr<DNSResponseAction> getSetTagResponseAction(const std::string& tag, const std::string& value);
}
std::shared_ptr<DNSActionWrapper> getSetTempFailureCacheTTLAction(const SetTempFailureCacheTTLActionConfiguration& config)
{
- auto action = dnsdist::actions::getSetTempFailureCacheTTLAction(config.maxttl);
+ auto action = dnsdist::actions::getSetTempFailureCacheTTLAction(config.ttl);
return newDNSActionWrapper(std::move(action), config.name);
}
std::shared_ptr<DNSActionWrapper> getSNMPTrapAction(const SNMPTrapActionConfiguration& config)
struct SetTempFailureCacheTTLActionConfiguration {
#[serde(default, skip_serializing_if = "crate::is_default")]
name: String,
- #[serde(rename = "maxTTL", )]
- maxttl: u32,
+ ttl: u32,
}
#[derive(Deserialize, Serialize, Debug, PartialEq)]
#[serde(default, skip_serializing_if = "crate::is_default")]
name: String,
identity: String,
- #[serde(rename = "logger-name", )]
logger_name: String,
- #[serde(rename = "alter-function_name", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
alter_function_name: String,
- #[serde(rename = "alter-function-code", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
alter_function_code: String,
- #[serde(rename = "alter-function-file", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
alter_function_file: String,
}
struct LogResponseActionConfiguration {
#[serde(default, skip_serializing_if = "crate::is_default")]
name: String,
- #[serde(rename = "file-name", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
file_name: String,
#[serde(default, skip_serializing_if = "crate::is_default")]
append: bool,
#[serde(default, skip_serializing_if = "crate::is_default")]
buffered: bool,
- #[serde(rename = "verbose-only", default = "crate::Bool::<true>::value", skip_serializing_if = "crate::if_true")]
+ #[serde(default = "crate::Bool::<true>::value", skip_serializing_if = "crate::if_true")]
verbose_only: bool,
- #[serde(rename = "include-timestamp", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
include_timestamp: bool,
}
struct LuaResponseActionConfiguration {
#[serde(default, skip_serializing_if = "crate::is_default")]
name: String,
- #[serde(rename = "function-name", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
function_name: String,
- #[serde(rename = "function-code", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
function_code: String,
- #[serde(rename = "function-file", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
function_file: String,
}
struct LuaFFIResponseActionConfiguration {
#[serde(default, skip_serializing_if = "crate::is_default")]
name: String,
- #[serde(rename = "function-name", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
function_name: String,
- #[serde(rename = "function-code", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
function_code: String,
- #[serde(rename = "function-file", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
function_file: String,
}
struct RemoteLogResponseActionConfiguration {
#[serde(default, skip_serializing_if = "crate::is_default")]
name: String,
- #[serde(rename = "logger-name", )]
logger_name: String,
- #[serde(rename = "alter-function-name", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
alter_function_name: String,
- #[serde(rename = "alter-function-code", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
alter_function_code: String,
- #[serde(rename = "alter-function-file", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
alter_function_file: String,
- #[serde(rename = "server-id", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
server_id: String,
- #[serde(rename = "ip-encrypt-key", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
ip_encrypt_key: String,
- #[serde(rename = "include-cname", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
include_cname: bool,
- #[serde(rename = "export-tags", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
export_tags: Vec<String>,
- #[serde(rename = "export-extended-errors-to-meta", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
export_extended_errors_to_meta: String,
#[serde(default, skip_serializing_if = "crate::is_default")]
metas: Vec<ProtoBufMetaConfiguration>,
struct SetExtendedDNSErrorResponseActionConfiguration {
#[serde(default, skip_serializing_if = "crate::is_default")]
name: String,
- #[serde(rename = "info-code", )]
info_code: u16,
- #[serde(rename = "extra-text", default, skip_serializing_if = "crate::is_default")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
extra_text: String,
}
temporary_failure_ttl: u32,
#[serde(default, skip_serializing_if = "crate::is_default")]
cookie_hashing: bool,
- #[serde(default, skip_serializing_if = "crate::is_default")]
+ #[serde(default = "crate::U32::<4096>::value", skip_serializing_if = "crate::U32::<4096>::is_equal")]
maximum_entry_size: u32,
#[serde(default, skip_serializing_if = "crate::is_default")]
options_to_skip: Vec<String>,
name: String,
#[serde(default, skip_serializing_if = "crate::is_default")]
packet_cache: String,
- #[serde(default = "crate::default_value_pool_policy", skip_serializing_if = "crate::default_value_equal_pool_policy")]
+ #[serde(default, skip_serializing_if = "crate::is_default")]
policy: String,
}
}
-// DEFAULT HANDLING for pool_policy
-fn default_value_pool_policy() -> String {
- String::from("leastOutstanding")
-}
-fn default_value_equal_pool_policy(value: &str)-> bool {
- value == default_value_pool_policy()
-}
-
-
impl Default for dnsdistsettings::PoolConfiguration {
fn default() -> Self {
let deserialized: dnsdistsettings::PoolConfiguration = serde_yaml::from_str("").unwrap();
- name: "selectors"
type: "Vec<Selector>"
default: true
+ description: "List of selectors"
- name: "ByName"
skip-cpp: true
skip-rust: true
parameters:
- name: "selector_name"
type: "String"
+ descripton: "The selector name"
- name: "DNSSEC"
description: "Matches queries with the DO flag set"
- name: "DSTPort"
parameters:
- name: "port"
type: "u16"
+ description: "Match destination port"
- name: "EDNSOption"
description: "Matches queries or responses with the specified EDNS option present"
parameters:
- name: "option_code"
type: "u16"
+ description: "The option code as an integer"
- name: "EDNSVersion"
description: "Matches queries or responses with an OPT record whose EDNS version is greater than the specified EDNS version"
parameters:
- name: "version"
type: "u8"
+ description: "The EDNS version to match on"
- name: "ERCode"
description: "Matches queries or responses with the specified rcode. The full 16bit RCode will be matched. If no EDNS OPT RR is present, the upper 12 bits are treated as 0"
parameters:
- name: "rcode"
type: "u64"
+ description: "The full 16bit RCode will be matched. If no EDNS OPT RR is present, the upper 12 bits are treated as 0"
- name: "HTTPHeader"
description: "Matches DNS over HTTPS queries with a HTTP header name whose content matches the supplied regular expression. It is necessary to set the ``keepIncomingHeaders`` to :func:`addDOHLocal()` to use this rule"
parameters:
- name: "header"
type: "String"
+ description: "The case-insensitive name of the HTTP header to match on"
- name: "expression"
type: "String"
+ description: "A regular expression to match the content of the specified header"
+
- name: "HTTPPath"
- description: "Matches DNS over HTTPS queries with a specific HTTP path"
+ description: "Matches DNS over HTTPS queries with a specific HTTP path. For example, if the query has been sent to the https://192.0.2.1:443/PowerDNS?dns=... URL, the path would be '/PowerDNS'. Only valid DNS over HTTPS queries are matched. If you want to match all HTTP queries, see :meth:`DOHFrontend:setResponsesMap` instead"
parameters:
- name: "path"
type: "String"
+ description: "The exact HTTP path to match on"
- name: "HTTPPathRegex"
- description: "Matches DNS over HTTPS queries with a path matching the supplied regular expression"
+ description: |
+ Matches DNS over HTTPS queries with a path matching the supplied regular expression. For example, if the query has been sent to the https://192.0.2.1:443/PowerDNS?dns=... URL, the path would be '/PowerDNS'.
+ Only valid DNS over HTTPS queries are matched. If you want to match all HTTP queries, see :meth:`DOHFrontend:setResponsesMap` instead
parameters:
- name: "expression"
type: "String"
+ description: "The regex to match on"
- name: "KeyValueStoreLookup"
skip-cpp: true
skip-rust: true
parameters:
- name: "kvs_name"
type: "String"
+ description: "The key value store to query"
- name: "lookup_key_name"
type: "String"
+ description: "The key to use for the lookup"
- name: "KeyValueStoreRangeLookup"
skip-cpp: true
skip-rust: true
parameters:
- name: "kvs_name"
type: "String"
+ description: "The key value store to query"
- name: "lookup_key_name"
type: "String"
+ description: "The key to use for the lookup"
- name: "lua"
description: "Invoke a Lua function that accepts a :class:`DNSQuestion` object. The function should return true if the query matches, or false otherwise. If the Lua code fails, false is returned"
skip-cpp: true
- name: "function_name"
type: "String"
default: ""
+ description: "The name of the Lua function"
- name: "function_code"
type: "String"
default: ""
+ description: "The code of the Lua function"
- name: "function_file"
type: "String"
default: ""
+ description: "The path to a file containing the code of the Lua function"
- name: "LuaFFI"
description: "Invoke a Lua FFI function that accepts a pointer to a ``dnsdist_ffi_dnsquestion_t`` object, whose bindings are defined in ``dnsdist-lua-ffi-interface.h``. The function should return true if the query matches, or false otherwise. If the Lua code fails, false is returned"
skip-cpp: true
- name: "function_name"
type: "String"
default: ""
+ description: "The name of the Lua function"
- name: "function_code"
type: "String"
default: ""
+ description: "The code of the Lua function"
- name: "function_file"
type: "String"
default: ""
+ description: "The path to a file containing the code of the Lua function"
- name: "LuaFFIPerThread"
description: "Invoke a Lua FFI function that accepts a pointer to a ``dnsdist_ffi_dnsquestion_t`` object, whose bindings are defined in ``dnsdist-lua-ffi-interface.h``. The function should return true if the query matches, or false otherwise. If the Lua code fails, false is returned.
parameters:
- name: "code"
type: "String"
+ description: "The code of the Lua function"
- name: "MaxQPS"
description: "Matches traffic not exceeding this qps limit. If e.g. this is set to 50, starting at the 51st query of the current second traffic stops being matched. This can be used to enforce a global QPS limit"
parameters:
- name: "qps"
type: "u32"
+ description: "The number of queries per second allowed, above this number the traffic is **not** matched anymore"
- name: "burst"
type: "u32"
default: 0
+ description: "The number of burstable queries per second allowed. Default is same as qps"
- name: "MaxQPSIP"
description: "Matches traffic for a subnet specified by the v4 or v6 mask exceeding ``qps`` queries per second up to ``burst`` allowed. This rule keeps track of QPS by netmask or source IP. This state is cleaned up regularly if ``cleanup_delay`` is greater than zero, removing existing netmasks or IP addresses that have not been seen in the last ``expiration`` seconds."
parameters:
- name: "qps"
type: "u32"
+ description: "The number of queries per second allowed, above this number traffic is matched"
- name: "ipv4_mask"
type: "u8"
default: 32
+ description: "The IPv4 netmask to match on. Default is 32 (the whole address)"
- name: "ipv6_mask"
type: "u8"
default: 64
+ description: "he IPv6 netmask to match on"
- name: "burst"
type: "u32"
default: 0
+ description: "The number of burstable queries per second allowed. Default is same as qps"
- name: "expiration"
type: "u32"
default: 300
+ description: "How long to keep netmask or IP addresses after they have last been seen, in seconds"
- name: "cleanup_delay"
type: "u32"
default: 60
+ description: "The number of seconds between two cleanups"
- name: "scan_fraction"
type: "u32"
default: 10
+ description: "he maximum fraction of the store to scan for expired entries, for example 5 would scan at most 20% of it"
- name: "shards"
type: "u32"
default: 10
+ description: "How many shards to use, to decrease lock contention between threads. Default is 10 and is a safe default unless a very high number of threads are used to process incoming queries"
- name: "NetmaskGroup"
skip-cpp: true
skip-rust: true
- name: "netmask_group_name"
type: "String"
default: ""
+ description: "The name of the netmask group object to use"
- name: "netmasks"
type: "Vec<String>"
default: ""
+ description: "A list of netmasks to use instead of an existing netmask group object"
- name: "source"
type: "bool"
default: "true"
+ description: "Whether to match source or destination address of the packet. Defaults to true (matches source)"
- name: "quiet"
type: "bool"
default: "false"
+ description: "Do not display the list of matched netmasks in Rules. Default is false."
- name: "Not"
description: "Matches the traffic if the selector rule does not match"
skip-cpp: true
parameters:
- name: "selector"
type: "Selector"
+ description: "The list of selectors"
- name: "opcode"
description: "Matches queries with opcode equals to ``code``"
parameters:
- name: "code"
type: "u8"
+ description: "The opcode to match"
- name: "Or"
description: "Matches the traffic if one or more of the selectors Rules does match"
skip-cpp: true
- name: "selectors"
type: "Vec<Selector>"
default: true
+ description: "The list of selectors"
- name: "PayloadSize"
description: "Matches queries or responses whose DNS payload size fits the given comparison"
parameters:
- name: "comparison"
type: "String"
+ description: "The comparison operator to use"
+ supported-values: ["equal", "greater", "greaterOrEqual", "smaller", "smallerOrEqual"]
- name: "size"
type: "u16"
+ description: "The size to compare to"
- name: "PoolAvailable"
description: "Check whether a pool has any servers available to handle queries"
parameters:
- name: "pool"
type: "String"
+ description: "The name of the pool"
- name: "PoolOutstanding"
description: "Check whether a pool has total outstanding queries above limit"
parameters:
- name: "pool"
type: "String"
+ description: "The name of the pool"
- name: "max_outstanding"
type: "u64"
+ description: "The maximum number of outstanding queries in that pool"
- name: "proba"
- description: "Matches queries with a given probability. 1.0 means \"always\""
+ description: "Matches queries with a given probability. 1.0 means ``always``"
parameters:
- name: "probability"
type: "f64"
+ description: "Probability of a match"
- name: "ProxyProtocolValue"
description: "Matches queries that have a proxy protocol TLV value of the specified type. If ``option_value`` is set, the content of the value should also match the content of value"
parameters:
- name: "option_type"
type: "u8"
+ description: "The type of the value, ranging from 0 to 255 (both included)"
- name: "option_value"
type: "String"
default: ""
+ description: "The optional binary-safe value to match"
- name: "QClass"
description: "Matches queries with the specified qclass. The class can be specified as a numerical value or as a string"
skip-cpp: true
- name: "qclass"
type: "String"
default: ""
+ description: "The Query Class to match on, as a string"
- name: "numeric_value"
type: "u16"
default: 0
+ description: "The Query Class to match on, as an integer"
- name: "QName"
description: "Matches queries with the specified qname exactly"
skip-cpp: true
parameters:
- name: "qname"
type: "String"
+ description: "Qname to match"
- name: "QNameLabelsCount"
description: "Matches if the qname has less than ``min_labels_count`` or more than ``max_labels_count`` labels"
parameters:
- name: "min_labels_count"
type: "u16"
+ description: "Minimum number of labels"
- name: "max_labels_count"
type: "u16"
+ description: "Maximum number of labels"
- name: "QNameSet"
description: "Matches if the set contains exact qname. To match subdomain names, see :ref:`yaml-settings-QNameSuffixSelector`"
skip-cpp: true
parameters:
- name: "qnames"
type: "Vec<String>"
+ description: "List of qnames"
- name: "QNameSuffix"
description: "Matches based on a group of domain suffixes for rapid testing of membership. Pass true to ``quiet`` to prevent listing of all domains matched in the console or the web interface"
skip-cpp: true
parameters:
- name: "suffixes"
type: "Vec<String>"
+ description: "List of suffixes"
- name: "quiet"
type: "bool"
default: "false"
+ description: "Do not display the list of matched domains in Rules"
- name: "QNameWireLength"
description: "Matches if the qname’s length on the wire is less than ``min`` or more than ``max`` bytes."
parameters:
- name: "min"
type: "u16"
+ description: "Minimum number of bytes"
- name: "max"
type: "u16"
+ description: "Maximum number of bytes"
- name: "QType"
description: "Matches queries with the specified qtype, which can be supplied as a String or as a numerical value"
skip-cpp: true
parameters:
- name: "qtype"
type: "String"
+ description: "The qtype, as a string"
- name: "numeric_value"
type: "u16"
default: 0
+ description: "The qtype, as a numerical value"
- name: "RCode"
description: "Matches queries or responses with the specified rcode"
parameters:
- name: "rcode"
type: "u64"
+ description: "The response code, as a numerical value"
- name: "RD"
description: "Matches queries with the RD flag set"
- name: "RE2"
parameters:
- name: "expression"
type: "String"
+ description: "The regular expression to match the QNAME"
- name: "RecordsCount"
description: "Matches if there is at least ``minimum`` and at most ``maximum`` records in the ``section`` section. ``section`` is specified as an integer with ``0`` being the question section, ``1`` answer, ``2`` authority and ``3`` additional"
parameters:
- name: "section"
type: "u8"
+ description: "The section to match on"
- name: "minimum"
type: "u16"
+ description: "The minimum number of entries"
- name: "maximum"
type: "u16"
+ description: "The maximum number of entries"
- name: "RecordsTypeCount"
description: "Matches if there is at least ``minimum`` and at most ``maximum`` records of type ``record_type`` in the section ``section``. ``section`` is specified as an integer with ``0`` being the question section, ``1`` answer, ``2`` authority and ``3`` additional"
parameters:
- name: "section"
type: "u8"
+ description: "The section to match on"
- name: "record_type"
type: "u16"
+ description: "The record type to match on"
- name: "minimum"
type: "u16"
+ description: "The minimum number of entries"
- name: "maximum"
type: "u16"
+ description: "The maximum number of entries"
- name: "regex"
description: "Matches the query name against the supplied regular expression"
parameters:
- name: "expression"
type: "String"
+ description: "The regular expression to match the QNAME"
- name: "SNI"
description: "Matches against the TLS Server Name Indication value sent by the client, if any. Only makes sense for DoT or DoH, and for that last one matching on the HTTP Host header using :ref:`yaml-settings-HTTPHeaderSelector` might provide more consistent results"
parameters:
- name: "server_name"
type: "String"
+ description: "The exact Server Name Indication value"
- name: "Tag"
description: "Matches question or answer with a tag named ``tag`` set. If ``value`` is specified, the existing tag value should match too"
parameters:
- name: "tag"
type: "String"
+ description: "The name of the tag that has to be set"
- name: "value"
type: "String"
default: ""
+ description: "If set, the value the tag has to be set to"
- name: "TCP"
description: "Matches question received over TCP if ``tcp`` is true, over UDP otherwise"
parameters:
- name: "tcp"
type: "bool"
+ description: "Match TCP traffic if true, UDP traffic if false"
- name: "TrailingData"
description: "Matches if the query has trailing data"
default: true
general:
+ description: "General settings"
parameters:
- name: "edns_udp_payload_size_self_generated_answers"
type: "u16"
lua-name: "setPayloadSizeOnSelfGeneratedAnswers"
internal-field-name: "d_payloadSizeSelfGenAnswers"
runtime-configurable: true
+ description: "Set the UDP payload size advertised via EDNS on self-generated responses. In accordance with :rfc:`RFC 6891 <6891#section-6.2.5>`, values lower than 512 will be treated as equal to 512"
- name: "add_edns_to_self_generated_answers"
type: "bool"
default: "true"
lua-name: "setAddEDNSToSelfGeneratedResponses"
internal-field-name: "d_addEDNSToSelfGeneratedResponses"
runtime-configurable: true
+ description: "Whether to add EDNS to self-generated responses, provided that the initial query had EDNS"
- name: "truncate_tc_answers"
type: "bool"
default: "false"
lua-name: "truncateTC"
internal-field-name: "d_truncateTC"
runtime-configurable: true
+ description: "Remove any left-over records in responses with the TC bit set, in accordance with :rfc:`RFC 6891 <6891#section-7>`"
- name: "fixup_case"
type: "bool"
default: "false"
lua-name: "fixupCase"
internal-field-name: "d_fixupCase"
runtime-configurable: true
+ description: "If set, ensure that the case of the DNS qname in the response matches the one from the query"
- name: "allow_empty_responses"
type: "bool"
default: "false"
lua-name: "setAllowEmptyResponse"
internal-field-name: "d_allowEmptyResponse"
runtime-configurable: true
+ description: "Set to true (defaults to false) to allow empty responses (qdcount=0) with a NoError or NXDomain rcode (default) from backends. dnsdist drops these responses by default because it can't match them against the initial query since they don't contain the qname, qtype and qclass, and therefore the risk of collision is much higher than with regular responses"
- name: "drop_empty_queries"
type: "bool"
default: "false"
lua-name: "setDropEmptyQueries"
internal-field-name: "d_dropEmptyQueries"
runtime-configurable: true
+ description: "Set to true (defaults to false) to drop empty queries (qdcount=0) right away, instead of answering with a NotImp rcode. dnsdist used to drop these queries by default because most rules and existing Lua code expects a query to have a qname, qtype and qclass. However :rfc:`7873` uses these queries to request a server cookie, and :rfc:`8906` as a conformance test, so answering these queries with NotImp is much better than not answering at all"
- name: "capabilities_to_retain"
type: "Vec<String>"
default: ""
lua-name: "addCapabilitiesToRetain"
runtime-configurable: false
+ description: |
+ Accept a Linux capability as a string, or a list of these, to retain after startup so that privileged operations can still be performed at runtime.
+ Keeping ``CAP_SYS_ADMIN`` on kernel 5.8+ for example allows loading eBPF programs and altering eBPF maps at runtime even if the ``kernel.unprivileged_bpf_disabled`` sysctl is set.
+ Note that this does not grant the capabilities to the process, doing so might be done by running it as root which we don't advise, or by adding capabilities via the systemd unit file, for example.
+ Please also be aware that switching to a different user via ``--uid`` will still drop all capabilities."
packet_cache:
+ description: "Packet-cache settings"
parameters:
- name: "name"
type: "String"
+ description: "The name of the packet cache object"
- name: "size"
type: "u64"
+ description: "The maximum number of entries in this cache"
- name: "deferrable_insert_lock"
type: "bool"
default: "true"
+ description: "Whether the cache should give up insertion if the lock is held by another thread, or simply wait to get the lock"
- name: "dont_age"
type: "bool"
default: "false"
+ description: "Don’t reduce TTLs when serving from the cache. Use this when dnsdist fronts a cluster of authoritative servers"
- name: "keep_stale_data"
type: "bool"
default: "false"
+ description: "Whether to suspend the removal of expired entries from the cache when there is no backend available in at least one of the pools using this cache"
- name: "max_negative_ttl"
type: "u32"
default: "3600"
+ description: "Cache a NXDomain or NoData answer from the backend for at most this amount of seconds, even if the TTL of the SOA record is higher"
- name: "max_ttl"
type: "u32"
default: "86400"
+ description: "Cap the TTL for records to his number"
- name: "min_ttl"
type: "u32"
default: 0
+ description: "Don’t cache entries with a TTL lower than this"
- name: "shards"
type: "u32"
default: "20"
+ description: "Number of shards to divide the cache into, to reduce lock contention"
- name: "parse_ecs"
type: "bool"
default: "false"
+ description: "Whether any EDNS Client Subnet option present in the query should be extracted and stored to be able to detect hash collisions involving queries with the same qname, qtype and qclass but a different incoming ECS value. Enabling this option adds a parsing cost and only makes sense if at least one backend might send different responses based on the ECS value, so it's disabled by default. Enabling this option is required for the :doc:`../advanced/zero-scope` option to work"
- name: "stale_ttl"
type: "u32"
default: "60"
+ description: "When the backend servers are not reachable, and global configuration setStaleCacheEntriesTTL is set appropriately, TTL that will be used when a stale cache entry is returned"
- name: "temporary_failure_ttl"
type: "u32"
default: "60"
+ description: "On a SERVFAIL or REFUSED from the backend, cache for this amount of seconds"
- name: "cookie_hashing"
type: "bool"
default: "false"
+ description: "If true, EDNS Cookie values will be hashed, resulting in separate entries for different cookies in the packet cache. This is required if the backend is sending answers with EDNS Cookies, otherwise a client might receive an answer with the wrong cookie"
- name: "maximum_entry_size"
type: "u32"
- default: "0"
+ default: "4096"
+ description: "The maximum size, in bytes, of a DNS packet that can be inserted into the packet cache"
- name: "options_to_skip"
type: "Vec<String>"
default: ""
+ description: "Extra list of EDNS option codes to skip when hashing the packet (if ``cookie_hashing`` above is false, EDNS cookie option number will be added to this list internally)"
proxy_protocol:
+ description: "Proxy Protocol-related settings"
parameters:
- name: "acl"
type: "Vec<String>"
default: ""
+ description: "Set the list of netmasks from which a Proxy Protocol header will be required, over UDP, TCP and DNS over TLS. The default is empty. Note that a proxy protocol payload will be required from these clients, regular DNS queries will no longer be accepted if they are not preceded by a proxy protocol payload. Be also aware that, if ``apply_acl_to_proxied_clients`` is set (default is false), the general ACL will be applied to the source IP address as seen by dnsdist first, but also to the source IP address provided in the Proxy Protocol header."
- name: "maximum_payload_size"
type: "u32"
default: "512"
lua-name: "setProxyProtocolMaximumPayloadSize"
internal-field-name: "d_proxyProtocolMaximumSize"
runtime-configurable: true
+ description: "Set the maximum size of a Proxy Protocol payload that dnsdist is willing to accept, in bytes. The default is 512, which is more than enough except for very large TLV data. This setting can’t be set to a value lower than 16 since it would deny of Proxy Protocol headers"
- name: "apply_acl_to_proxied_clients"
type: "bool"
default: "false"
lua-name: "setProxyProtocolApplyACLToProxiedClients"
internal-field-name: "d_applyACLToProxiedClients"
runtime-configurable: true
+ description: "Whether the general ACL should be applied to the source IP address provided in the Proxy Protocol header, in addition to being applied to the source IP address as seen by dnsdist first"
snmp:
+ description: "SNMP-related settings"
parameters:
- name: "enabled"
type: "bool"
lua-name: "snmpAgent"
internal-field-name: "d_snmpEnabled"
runtime-configurable: false
+ description: "Enable SNMP support"
- name: "traps_enabled"
type: "bool"
default: "false"
lua-name: "snmpAgent"
internal-field-name: "d_snmpTrapsEnabled"
runtime-configurable: false
+ description: "Enable the sending of SNMP traps for specific events"
- name: "daemon_socket"
type: "String"
default: ""
lua-name: "snmpAgent"
internal-field-name: "d_snmpDaemonSocketPath"
runtime-configurable: false
+ description: "A string specifying how to connect to the daemon agent. This is usually the path to a UNIX socket, but e.g. ``tcp:localhost:705`` can be used as well. By default, SNMP agent’s default socket is used"
query_count:
+ description: "Per-record Carbon statistics of the amount of queries. See :doc:`../guides/carbon`"
parameters:
- name: "enabled"
type: "bool"
default: "false"
+ description: "Enable per-record Carbon statistics of the amount of queries"
- name: "filter_function_name"
type: "String"
default: ""
+ description: "The name of a Lua function to filter which query should be accounted for, and how"
- name: "filter_function_code"
type: "String"
default: ""
+ description: "The code of a Lua function to filter which query should be accounted for, and how"
- name: "filter_function_file"
type: "String"
default: ""
+ description: "The path to a file containing the code of a Lua function to filter which query should be accounted for, and how"
pool:
+ description: "Settings for a pool of servers"
parameters:
- name: "name"
type: "String"
+ description: "The name of this pool"
- name: "packet_cache"
type: "String"
- default: true
+ default: ""
+ description: "The name of a packet cache object, if any"
- name: "policy"
type: "String"
- default: "leastOutstanding"
+ default: ""
+ description: "The name of the load-balancing policy associated to this pool. If left empty, the global policy will be used"
custom_load_balancing_policy:
+ description: "Settings for a custom load-balancing policy"
parameters:
- name: "name"
type: "String"
+ description: "The name of this load-balancing policy"
- name: "function_name"
type: "String"
default: ""
+ description: "The name of a Lua function implementing the custom load-balancing policy. If ``ffi`` is false, this function takes a table of :class:`Server` objects and a :class:`DNSQuestion` representing the current query, and must return the index of the selected server in the supplied table. If ``ffi`` is true, this function takes a ``const dnsdist_ffi_servers_list_t*`` and a ``dnsdist_ffi_dnsquestion_t*``"
- name: "function_code"
type: "String"
default: ""
+ description: "Same than ``function_name` but contain actual Lua code returning a function instead of a name"
- name: "function_file"
type: "String"
default: ""
+ description: "Same than ``function_name` but contain the path to a file containing actual Lua code returning a function instead of a name"
- name: "ffi"
type: "bool"
default: "false"
+ description: "Whether the function uses the faster but more complicated Lua FFI API"
- name: "per_thread"
type: "bool"
default: "false"
+ description: "If set, the resulting policy will be executed in a lock-free per-thread context, instead of running in the global Lua context. Note that ``function_name`` cannot be used, since this needs the Lua code to create the function in a new Lua context instead of just a function"
load_balancing_policies:
+ description: "Setting for load-balancing policies"
parameters:
- name: "default_policy"
type: "String"
default: "leastOutstanding"
lua-name: "setServerPolicy"
runtime-configurable: true
+ description: "Set the default server selection policy"
- name: "servfail_on_no_server"
type: "bool"
default: "false"
lua-name: "setServFailWhenNoServer"
internal-field-name: "d_servFailOnNoPolicy"
runtime-configurable: true
+ description: "If set, return a ServFail when no servers are available, instead of the default behaviour of dropping the query"
- name: "round_robin_servfail_on_no_server"
type: "bool"
default: "false"
lua-name: "setRoundRobinFailOnNoServer"
internal-field-name: "d_roundrobinFailOnNoServer"
runtime-configurable: true
+ description: "By default the roundrobin load-balancing policy will still try to select a backend even if all backends are currently down. Setting this to true will make the policy fail and return that no server is available instead"
- name: "weighted_balancing_factor"
type: "f64"
default: 0.0
lua-name: "setWeightedBalancingFactor"
internal-field-name: "d_weightedBalancingFactor"
runtime-configurable: false
+ description: "Set the maximum imbalance between the number of outstanding queries intended for a given server, based on its weight, and the actual number, when using the ``whashed`` or ``wrandom`` load-balancing policy. Default is 0, which disables the bounded-load algorithm"
- name: "consistent_hashing_balancing_factor"
type: "f64"
default: 0.0
lua-name: "setConsistentHashingBalancingFactor"
internal-field-name: "d_consistentHashBalancingFactor"
runtime-configurable: false
+ description: "Set the maximum imbalance between the number of outstanding queries intended for a given server, based on its weight, and the actual number, when using the ``chashed`` consistent hashing load-balancing policy. Default is 0, which disables the bounded-load algorithm"
- name: "custom_policies"
type: "Vec<CustomLoadBalancingPolicyConfiguration>"
default: true
+ description: "Custom load-balancing policies implemented in Lua"
- name: "hash_perturbation"
type: "u32"
default: "0"
lua-name: "setWHashedPertubation"
internal-field-name: "d_hashPerturbation"
runtime-configurable: false
+ description: "Set the hash perturbation value to be used in the ``whashed`` policy instead of a random one, allowing to have consistent ``whashed`` results on different instances"
query_rule:
description: "A rule that can applied on queries"
Parameters:
-- **action**: :ref:`Action <yaml-settings-Action>`
+- **action**: :ref:`Action <yaml-settings-Action>` - The action to execute
.. _yaml-settings-DelayAction:
Parameters:
-- **msec**: Unsigned integer
+- **msec**: Unsigned integer - The amount of milliseconds to delay the response
.. _yaml-settings-DnstapLogAction:
Parameters:
-- **identity**: String
-- **logger_name**: String
-- **alter_function_name**: String ``("")``
-- **alter_function_code**: String ``("")``
-- **alter_function_file**: String ``("")``
+- **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
.. _yaml-settings-DropAction:
Parameters:
-- **code**: Unsigned integer
-- **data**: String
+- **code**: Unsigned integer - The EDNS option number
+- **data**: String - The EDNS0 option raw content
.. _yaml-settings-ERCodeAction:
Parameters:
-- **rcode**: Unsigned integer
-- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>`
+- **rcode**: Unsigned integer - The RCODE to respond with
+- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>` - The response options
.. _yaml-settings-HTTPStatusAction:
Parameters:
-- **status**: Unsigned integer
-- **body**: String
-- **content_type**: String ``("")``
-- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>`
+- **status**: Unsigned integer - 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)
+- **content_type**: String ``("")`` - The HTTP Content-Type header to return for a 200 response, ignored otherwise. Default is ``application/dns-message``
+- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>` - The response options
.. _yaml-settings-KeyValueStoreLookupAction:
Parameters:
-- **kvs_name**: String
-- **lookup_key_name**: String
-- **destination_tag**: String
+- **kvs_name**: String - The name of the KV store
+- **lookup_key_name**: String - The name of the key to use for the lookup
+- **destination_tag**: String - The name of the tag to store the result into
.. _yaml-settings-KeyValueStoreRangeLookupAction:
Parameters:
-- **kvs_name**: String
-- **lookup_key_name**: String
-- **destination_tag**: String
+- **kvs_name**: String - The name of the KV store
+- **lookup_key_name**: String - The name of the key to use for the lookup
+- **destination_tag**: String - The name of the tag to store the result into
.. _yaml-settings-LogAction:
Parameters:
-- **file_name**: String ``("")``
-- **binary**: Boolean ``(true)``
-- **append**: Boolean ``(false)``
-- **buffered**: Boolean ``(false)``
-- **verbose_only**: Boolean ``(true)``
-- **include_timestamp**: Boolean ``(false)``
+- **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
+- **binary**: Boolean ``(true)`` - Whether to do binary logging
+- **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
.. _yaml-settings-LuaAction:
Parameters:
-- **function_name**: String ``("")``
-- **function_code**: String ``("")``
-- **function_file**: String ``("")``
+- **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
.. _yaml-settings-LuaFFIAction:
Parameters:
-- **function_name**: String ``("")``
-- **function_code**: String ``("")``
-- **function_file**: String ``("")``
+- **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
.. _yaml-settings-LuaFFIPerThreadAction:
Parameters:
-- **code**: String
+- **code**: String - The code of the Lua function
.. _yaml-settings-NegativeAndSOAAction:
Parameters:
-- **nxd**: Boolean
-- **zone**: String
-- **ttl**: Unsigned integer
-- **mname**: String
-- **rname**: String
-- **soa_parameters**: :ref:`SOAParams <yaml-settings-SOAParams>`
-- **soa_in_authority**: Boolean ``(false)``
-- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>`
+- **nxd**: Boolean - Whether the answer is a NXDOMAIN (true) or a NODATA (false)
+- **zone**: String - The owner name for the SOA record
+- **ttl**: Unsigned integer - The TTL of the SOA record
+- **mname**: String - The mname of the SOA record
+- **rname**: String - The rname of the SOA record
+- **soa_parameters**: :ref:`SOAParams <yaml-settings-SOAParams>` - The fields of the SOA record
+- **soa_in_authority**: Boolean ``(false)`` - Whether the SOA record should be the authority section for a complete NXDOMAIN/NODATA response that works as a cacheable negative response, rather than the RPZ-style response with a purely informational SOA in the additional section. Default is false (SOA in additional section)
+- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>` - Response options
.. _yaml-settings-NoneAction:
Parameters:
-- **pool_name**: String
-- **stop_processing**: Boolean ``(true)``
+- **pool_name**: String - The name of the pool
+- **stop_processing**: Boolean ``(true)`` - Whether subsequent rules should be executed after this one
.. _yaml-settings-QPSAction:
Parameters:
-- **limit**: Unsigned integer
+- **limit**: Unsigned integer - The QPS limit
.. _yaml-settings-QPSPoolAction:
Parameters:
-- **limit**: Unsigned integer
-- **pool_name**: String
-- **stop_processing**: Boolean ``(true)``
+- **limit**: Unsigned integer - The QPS limit
+- **pool_name**: String - The name of the pool
+- **stop_processing**: Boolean ``(true)`` - Whether subsequent rules should be executed after this one
.. _yaml-settings-RCodeAction:
Parameters:
-- **rcode**: Unsigned integer
-- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>`
+- **rcode**: Unsigned integer - The response code
+- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>` - Response options
.. _yaml-settings-RemoteLogAction:
Parameters:
-- **logger_name**: String
-- **alter_function_name**: String ``("")``
-- **alter_function_code**: String ``("")``
-- **alter_function_file**: String ``("")``
-- **server_id**: String ``("")``
-- **ip_encrypt_key**: String ``("")``
-- **export_tags**: Sequence of String ``("")``
-- **metas**: Sequence of :ref:`ProtoBufMetaConfiguration <yaml-settings-ProtoBufMetaConfiguration>`
+- **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 Server Identity field
+- **ip_encrypt_key**: String ``("")`` - A key, that can be generated via the :func:`makeIPCipherKey` function, to encrypt the IP address of the requestor for anonymization purposes. The encryption is done using ipcrypt for IPv4 and a 128-bit AES ECB operation for IPv6
+- **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
+- **metas**: Sequence of :ref:`ProtoBufMetaConfiguration <yaml-settings-ProtoBufMetaConfiguration>` - A list of ``name``=``key`` pairs, for meta-data to be added to Protocol Buffer message
.. _yaml-settings-SetAdditionalProxyProtocolValueAction:
Parameters:
-- **proxy_type**: Unsigned integer
-- **value**: String
+- **proxy_type**: Unsigned integer - The proxy protocol type
+- **value**: String - The value
.. _yaml-settings-SetDisableECSAction:
Parameters:
-- **ipv4**: String
-- **ipv6**: String ``("")``
+- **ipv4**: String - The IPv4 netmask, for example 192.0.2.1/32
+- **ipv6**: String ``("")`` - The IPv6 netmask, if any
.. _yaml-settings-SetECSOverrideAction:
Parameters:
-- **override_existing**: Boolean
+- **override_existing**: Boolean - Whether to override an existing EDNS Client Subnet value
.. _yaml-settings-SetECSPrefixLengthAction:
Parameters:
-- **ipv4**: Unsigned integer
-- **ipv6**: Unsigned integer
+- **ipv4**: Unsigned integer - The IPv4 netmask length
+- **ipv6**: Unsigned integer - The IPv6 netmask length
.. _yaml-settings-SetExtendedDNSErrorAction:
Parameters:
-- **info_code**: Unsigned integer
-- **extra_text**: String ``("")``
+- **info_code**: Unsigned integer - The EDNS Extended DNS Error code
+- **extra_text**: String ``("")`` - The optional EDNS Extended DNS Error extra text
.. _yaml-settings-SetMacAddrAction:
SetMacAddrAction
----------------
-Add the source MAC address to the query as EDNS0 option option. This action is currently only supported on Linux. Subsequent rules are processed after this action
+Add the source MAC address to the query as an EDNS0 option. This action is currently only supported on Linux. Subsequent rules are processed after this action
Lua equivalent: :func:`SetMacAddrAction`
Parameters:
-- **code**: Unsigned integer
+- **code**: Unsigned integer - The EDNS option code
.. _yaml-settings-SetMaxReturnedTTLAction:
Parameters:
-- **max**: Unsigned integer
+- **max**: Unsigned integer - The TTL cap
.. _yaml-settings-SetNoRecurseAction:
Parameters:
-- **values**: Sequence of :ref:`ProxyProtocolValueConfiguration <yaml-settings-ProxyProtocolValueConfiguration>`
+- **values**: Sequence of :ref:`ProxyProtocolValueConfiguration <yaml-settings-ProxyProtocolValueConfiguration>` - List of proxy protocol values
.. _yaml-settings-SetSkipCacheAction:
Parameters:
-- **tag**: String
-- **value**: String
+- **tag**: String - The tag name
+- **value**: String - The tag value
.. _yaml-settings-SetTempFailureCacheTTLAction:
Parameters:
-- **maxTTL**: Unsigned integer
+- **ttl**: Unsigned integer - The TTL to use
.. _yaml-settings-SNMPTrapAction:
Parameters:
-- **reason**: String ``("")``
+- **reason**: String ``("")`` - The SNMP trap reason
.. _yaml-settings-SpoofAction:
Parameters:
-- **ips**: Sequence of String
-- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>`
+- **ips**: Sequence of String - List of IP addresses to spoof
+- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>` - Response options
.. _yaml-settings-SpoofCNAMEAction:
Parameters:
-- **cname**: String
-- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>`
+- **cname**: String - The CNAME to use in the response
+- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>` - Response options
.. _yaml-settings-SpoofPacketAction:
Parameters:
-- **response**: String
-- **len**: Unsigned integer
+- **response**: String - The DNS packet
+- **len**: Unsigned integer - The length of the DNS packet
.. _yaml-settings-SpoofRawAction:
--------------
Forge a response with the specified raw bytes as record data
+.. code-block:: Lua
+
+ -- select queries for the 'raw.powerdns.com.' name and TXT type, and answer with both a "aaa" "bbbb" and "ccc" TXT record:
+ addAction(AndRule({QNameRule('raw.powerdns.com.'), QTypeRule(DNSQType.TXT)}), SpoofRawAction({"\003aaa\004bbbb", "\003ccc"}))
+ -- select queries for the 'raw-srv.powerdns.com.' name and SRV type, and answer with a '0 0 65535 srv.powerdns.com.' SRV record, setting the AA bit to 1 and the TTL to 3600s
+ addAction(AndRule({QNameRule('raw-srv.powerdns.com.'), QTypeRule(DNSQType.SRV)}), SpoofRawAction("\000\000\000\000\255\255\003srv\008powerdns\003com\000", { aa=true, ttl=3600 }))
+ -- select reverse queries for '127.0.0.1' and answer with 'localhost'
+ addAction(AndRule({QNameRule('1.0.0.127.in-addr.arpa.'), QTypeRule(DNSQType.PTR)}), SpoofRawAction("\009localhost\000"))
+ -- rfc8482: Providing Minimal-Sized Responses to DNS Queries That Have QTYPE=ANY via HINFO of value "rfc8482"
+ addAction(QTypeRule(DNSQType.ANY), SpoofRawAction("\007rfc\056\052\056\050\000", { typeForAny=DNSQType.HINFO }))
+
+:func:`DNSName:toDNSString` is convenient for converting names to wire format for passing to ``SpoofRawAction``.
+
+``sdig dumpluaraw`` and ``pdnsutil raw-lua-from-content`` from PowerDNS can generate raw answers for you:
+
+.. code-block:: Shell
+
+ $ pdnsutil raw-lua-from-content SRV '0 0 65535 srv.powerdns.com.'
+ "\000\000\000\000\255\255\003srv\008powerdns\003com\000"
+ $ sdig 127.0.0.1 53 open-xchange.com MX recurse dumpluaraw
+ Reply to question for qname='open-xchange.com.', qtype=MX
+ Rcode: 0 (No Error), RD: 1, QR: 1, TC: 0, AA: 0, opcode: 0
+ 0 open-xchange.com. IN MX "\000c\004mx\049\049\012open\045xchange\003com\000"
+ 0 open-xchange.com. IN MX "\000\010\003mx\049\012open\045xchange\003com\000"
+ 0 open-xchange.com. IN MX "\000\020\003mx\050\012open\045xchange\003com\000"
+
Lua equivalent: :func:`SpoofRawAction`
Parameters:
-- **answers**: Sequence of String
-- **qtype_for_any**: String ``("")``
-- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>`
+- **answers**: Sequence of String - A list of DNS record content entries to use in the response
+- **qtype_for_any**: String ``("")`` - The type to use for ANY queries
+- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>` - Response options
.. _yaml-settings-SpoofSVCAction:
Parameters:
-- **parameters**: Sequence of :ref:`SVCRecordParameters <yaml-settings-SVCRecordParameters>`
-- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>`
+- **parameters**: Sequence of :ref:`SVCRecordParameters <yaml-settings-SVCRecordParameters>` - List of SVC record parameters
+- **vars**: :ref:`ResponseConfig <yaml-settings-ResponseConfig>` - Response options
.. _yaml-settings-TCAction:
Parameters:
-- **rca**: String
-- **lca**: String ``("")``
-- **add_ecs**: Boolean ``(false)``
-- **add_proxy_protocol**: Boolean ``(false)``
+- **rca**: String - The address and port of the remote server
+- **lca**: String ``("")`` - The source address to use to send packets to the remote server
+- **add_ecs**: Boolean ``(false)`` - Whether to add EDNS Client Subnet to the query
+- **add_proxy_protocol**: Boolean ``(false)`` - Whether to add a proxy protocol payload to the query
Parameters:
-- **msec**: Unsigned integer
+- **msec**: Unsigned integer - The amount of milliseconds to delay the response
.. _yaml-settings-DnstapLogResponseAction:
Parameters:
-- **identity**: String
-- **logger-name**: String
-- **alter-function_name**: String ``("")``
-- **alter-function-code**: String ``("")``
-- **alter-function-file**: String ``("")``
+- **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
.. _yaml-settings-DropResponseAction:
Parameters:
-- **min**: Unsigned integer
-- **max**: Unsigned integer
-- **types**: Sequence of Unsigned integer
+- **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
.. _yaml-settings-LogResponseAction:
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``. When logging to a file, the ``binary`` parameter specifies whether we log in binary form (default) or in textual form. 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
+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: :func:`LogResponseAction`
Parameters:
-- **file-name**: String ``("")``
-- **append**: Boolean ``(false)``
-- **buffered**: Boolean ``(false)``
-- **verbose-only**: Boolean ``(true)``
-- **include-timestamp**: Boolean ``(false)``
+- **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
.. _yaml-settings-LuaResponseAction:
Parameters:
-- **function-name**: String ``("")``
-- **function-code**: String ``("")``
-- **function-file**: String ``("")``
+- **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
.. _yaml-settings-LuaFFIResponseAction:
Parameters:
-- **function-name**: String ``("")``
-- **function-code**: String ``("")``
-- **function-file**: String ``("")``
+- **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
.. _yaml-settings-LuaFFIPerThreadResponseAction:
Parameters:
-- **code**: String
+- **code**: String - The code of the Lua function
.. _yaml-settings-RemoteLogResponseAction:
Parameters:
-- **logger-name**: String
-- **alter-function-name**: String ``("")``
-- **alter-function-code**: String ``("")``
-- **alter-function-file**: String ``("")``
-- **server-id**: String ``("")``
-- **ip-encrypt-key**: String ``("")``
-- **include-cname**: Boolean ``(false)``
-- **export-tags**: Sequence of String
-- **export-extended-errors-to-meta**: String ``("")``
-- **metas**: Sequence of :ref:`ProtoBufMetaConfiguration <yaml-settings-ProtoBufMetaConfiguration>`
+- **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 Server Identity field
+- **ip_encrypt_key**: String ``("")`` - A key, that can be generated via the :func:`makeIPCipherKey` function, to encrypt the IP address of the requestor for anonymization purposes. The encryption is done using ipcrypt for IPv4 and a 128-bit AES ECB operation for IPv6
+- **include_cname**: Boolean ``(false)`` - Whether or not to parse and export CNAMEs
+- **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
+- **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
+- **metas**: Sequence of :ref:`ProtoBufMetaConfiguration <yaml-settings-ProtoBufMetaConfiguration>` - A list of ``name``=``key`` pairs, for meta-data to be added to Protocol Buffer message
.. _yaml-settings-SetExtendedDNSErrorResponseAction:
Parameters:
-- **info-code**: Unsigned integer
-- **extra-text**: String ``("")``
+- **info_code**: Unsigned integer - The EDNS Extended DNS Error code
+- **extra_text**: String ``("")`` - The optional EDNS Extended DNS Error extra text
.. _yaml-settings-SetMaxReturnedTTLResponseAction:
Parameters:
-- **max**: Unsigned integer
+- **max**: Unsigned integer - The TTL cap
.. _yaml-settings-SetMaxTTLResponseAction:
Parameters:
-- **max**: Unsigned integer
+- **max**: Unsigned integer - The TTL cap
.. _yaml-settings-SetMinTTLResponseAction:
Parameters:
-- **min**: Unsigned integer
+- **min**: Unsigned integer - The TTL cap
.. _yaml-settings-SetReducedTTLResponseAction:
Parameters:
-- **percentage**: Unsigned integer
+- **percentage**: Unsigned integer - The percentage to use
.. _yaml-settings-SetSkipCacheResponseAction:
Parameters:
-- **tag**: String
-- **value**: String
+- **tag**: String - The tag name
+- **value**: String - The tag value
.. _yaml-settings-SNMPTrapResponseAction:
Parameters:
-- **reason**: String ``("")``
+- **reason**: String ``("")`` - The SNMP trap reason
.. _yaml-settings-TCResponseAction:
Parameters:
-- **selectors**: Sequence of :ref:`Selector <yaml-settings-Selector>`
+- **selectors**: Sequence of :ref:`Selector <yaml-settings-Selector>` - List of selectors
.. _yaml-settings-ByNameSelector:
Parameters:
-- **port**: Unsigned integer
+- **port**: Unsigned integer - Match destination port
.. _yaml-settings-EDNSOptionSelector:
Parameters:
-- **option_code**: Unsigned integer
+- **option_code**: Unsigned integer - The option code as an integer
.. _yaml-settings-EDNSVersionSelector:
Parameters:
-- **version**: Unsigned integer
+- **version**: Unsigned integer - The EDNS version to match on
.. _yaml-settings-ERCodeSelector:
Parameters:
-- **rcode**: Unsigned integer
+- **rcode**: Unsigned integer - The full 16bit RCode will be matched. If no EDNS OPT RR is present, the upper 12 bits are treated as 0
.. _yaml-settings-HTTPHeaderSelector:
Parameters:
-- **header**: String
-- **expression**: String
+- **header**: String - The case-insensitive name of the HTTP header to match on
+- **expression**: String - A regular expression to match the content of the specified header
.. _yaml-settings-HTTPPathSelector:
HTTPPathSelector
----------------
-Matches DNS over HTTPS queries with a specific HTTP path
+Matches DNS over HTTPS queries with a specific HTTP path. For example, if the query has been sent to the https://192.0.2.1:443/PowerDNS?dns=... URL, the path would be '/PowerDNS'. Only valid DNS over HTTPS queries are matched. If you want to match all HTTP queries, see :meth:`DOHFrontend:setResponsesMap` instead
Lua equivalent: :func:`HTTPPathRule`
Parameters:
-- **path**: String
+- **path**: String - The exact HTTP path to match on
.. _yaml-settings-HTTPPathRegexSelector:
HTTPPathRegexSelector
---------------------
-Matches DNS over HTTPS queries with a path matching the supplied regular expression
+Matches DNS over HTTPS queries with a path matching the supplied regular expression. For example, if the query has been sent to the https://192.0.2.1:443/PowerDNS?dns=... URL, the path would be '/PowerDNS'.
+Only valid DNS over HTTPS queries are matched. If you want to match all HTTP queries, see :meth:`DOHFrontend:setResponsesMap` instead
+
Lua equivalent: :func:`HTTPPathRegexRule`
Parameters:
-- **expression**: String
+- **expression**: String - The regex to match on
.. _yaml-settings-KeyValueStoreLookupSelector:
Parameters:
-- **kvs_name**: String
-- **lookup_key_name**: String
+- **kvs_name**: String - The key value store to query
+- **lookup_key_name**: String - The key to use for the lookup
.. _yaml-settings-KeyValueStoreRangeLookupSelector:
Parameters:
-- **kvs_name**: String
-- **lookup_key_name**: String
+- **kvs_name**: String - The key value store to query
+- **lookup_key_name**: String - The key to use for the lookup
.. _yaml-settings-LuaSelector:
Parameters:
-- **function_name**: String ``("")``
-- **function_code**: String ``("")``
-- **function_file**: String ``("")``
+- **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
.. _yaml-settings-LuaFFISelector:
Parameters:
-- **function_name**: String ``("")``
-- **function_code**: String ``("")``
-- **function_file**: String ``("")``
+- **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
.. _yaml-settings-LuaFFIPerThreadSelector:
Parameters:
-- **code**: String
+- **code**: String - The code of the Lua function
.. _yaml-settings-MaxQPSSelector:
Parameters:
-- **qps**: Unsigned integer
-- **burst**: Unsigned integer ``(0)``
+- **qps**: Unsigned integer - The number of queries per second allowed, above this number the traffic is **not** matched anymore
+- **burst**: Unsigned integer ``(0)`` - The number of burstable queries per second allowed. Default is same as qps
.. _yaml-settings-MaxQPSIPSelector:
Parameters:
-- **qps**: Unsigned integer
-- **ipv4_mask**: Unsigned integer ``(32)``
-- **ipv6_mask**: Unsigned integer ``(64)``
-- **burst**: Unsigned integer ``(0)``
-- **expiration**: Unsigned integer ``(300)``
-- **cleanup_delay**: Unsigned integer ``(60)``
-- **scan_fraction**: Unsigned integer ``(10)``
-- **shards**: Unsigned integer ``(10)``
+- **qps**: Unsigned integer - The number of queries per second allowed, above this number traffic is matched
+- **ipv4_mask**: Unsigned integer ``(32)`` - The IPv4 netmask to match on. Default is 32 (the whole address)
+- **ipv6_mask**: Unsigned integer ``(64)`` - he IPv6 netmask to match on
+- **burst**: Unsigned integer ``(0)`` - The number of burstable queries per second allowed. Default is same as qps
+- **expiration**: Unsigned integer ``(300)`` - How long to keep netmask or IP addresses after they have last been seen, in seconds
+- **cleanup_delay**: Unsigned integer ``(60)`` - The number of seconds between two cleanups
+- **scan_fraction**: Unsigned integer ``(10)`` - he maximum fraction of the store to scan for expired entries, for example 5 would scan at most 20% of it
+- **shards**: Unsigned integer ``(10)`` - How many shards to use, to decrease lock contention between threads. Default is 10 and is a safe default unless a very high number of threads are used to process incoming queries
.. _yaml-settings-NetmaskGroupSelector:
Parameters:
-- **netmask_group_name**: String ``("")``
-- **netmasks**: Sequence of String ``("")``
-- **source**: Boolean ``(true)``
-- **quiet**: Boolean ``(false)``
+- **netmask_group_name**: String ``("")`` - The name of the netmask group object to use
+- **netmasks**: Sequence of String ``("")`` - A list of netmasks to use instead of an existing netmask group object
+- **source**: Boolean ``(true)`` - Whether to match source or destination address of the packet. Defaults to true (matches source)
+- **quiet**: Boolean ``(false)`` - Do not display the list of matched netmasks in Rules. Default is false.
.. _yaml-settings-NotSelector:
Parameters:
-- **selector**: :ref:`Selector <yaml-settings-Selector>`
+- **selector**: :ref:`Selector <yaml-settings-Selector>` - The list of selectors
.. _yaml-settings-OpcodeSelector:
Parameters:
-- **code**: Unsigned integer
+- **code**: Unsigned integer - The opcode to match
.. _yaml-settings-OrSelector:
Parameters:
-- **selectors**: Sequence of :ref:`Selector <yaml-settings-Selector>`
+- **selectors**: Sequence of :ref:`Selector <yaml-settings-Selector>` - The list of selectors
.. _yaml-settings-PayloadSizeSelector:
Parameters:
-- **comparison**: String
-- **size**: Unsigned integer
+- **comparison**: String - The comparison operator to use. Supported values are: equal, greater, greaterOrEqual, smaller, smallerOrEqual
+- **size**: Unsigned integer - The size to compare to
.. _yaml-settings-PoolAvailableSelector:
Parameters:
-- **pool**: String
+- **pool**: String - The name of the pool
.. _yaml-settings-PoolOutstandingSelector:
Parameters:
-- **pool**: String
-- **max_outstanding**: Unsigned integer
+- **pool**: String - The name of the pool
+- **max_outstanding**: Unsigned integer - The maximum number of outstanding queries in that pool
.. _yaml-settings-ProbaSelector:
ProbaSelector
-------------
-Matches queries with a given probability. 1.0 means "always"
+Matches queries with a given probability. 1.0 means ``always``
Lua equivalent: :func:`ProbaRule`
Parameters:
-- **probability**: Double
+- **probability**: Double - Probability of a match
.. _yaml-settings-ProxyProtocolValueSelector:
Parameters:
-- **option_type**: Unsigned integer
-- **option_value**: String ``("")``
+- **option_type**: Unsigned integer - The type of the value, ranging from 0 to 255 (both included)
+- **option_value**: String ``("")`` - The optional binary-safe value to match
.. _yaml-settings-QClassSelector:
Parameters:
-- **qclass**: String ``("")``
-- **numeric_value**: Unsigned integer ``(0)``
+- **qclass**: String ``("")`` - The Query Class to match on, as a string
+- **numeric_value**: Unsigned integer ``(0)`` - The Query Class to match on, as an integer
.. _yaml-settings-QNameSelector:
Parameters:
-- **qname**: String
+- **qname**: String - Qname to match
.. _yaml-settings-QNameLabelsCountSelector:
Parameters:
-- **min_labels_count**: Unsigned integer
-- **max_labels_count**: Unsigned integer
+- **min_labels_count**: Unsigned integer - Minimum number of labels
+- **max_labels_count**: Unsigned integer - Maximum number of labels
.. _yaml-settings-QNameSetSelector:
Parameters:
-- **qnames**: Sequence of String
+- **qnames**: Sequence of String - List of qnames
.. _yaml-settings-QNameSuffixSelector:
Parameters:
-- **suffixes**: Sequence of String
-- **quiet**: Boolean ``(false)``
+- **suffixes**: Sequence of String - List of suffixes
+- **quiet**: Boolean ``(false)`` - Do not display the list of matched domains in Rules
.. _yaml-settings-QNameWireLengthSelector:
Parameters:
-- **min**: Unsigned integer
-- **max**: Unsigned integer
+- **min**: Unsigned integer - Minimum number of bytes
+- **max**: Unsigned integer - Maximum number of bytes
.. _yaml-settings-QTypeSelector:
Parameters:
-- **qtype**: String
-- **numeric_value**: Unsigned integer ``(0)``
+- **qtype**: String - The qtype, as a string
+- **numeric_value**: Unsigned integer ``(0)`` - The qtype, as a numerical value
.. _yaml-settings-RCodeSelector:
Parameters:
-- **rcode**: Unsigned integer
+- **rcode**: Unsigned integer - The response code, as a numerical value
.. _yaml-settings-RDSelector:
Parameters:
-- **expression**: String
+- **expression**: String - The regular expression to match the QNAME
.. _yaml-settings-RecordsCountSelector:
Parameters:
-- **section**: Unsigned integer
-- **minimum**: Unsigned integer
-- **maximum**: Unsigned integer
+- **section**: Unsigned integer - The section to match on
+- **minimum**: Unsigned integer - The minimum number of entries
+- **maximum**: Unsigned integer - The maximum number of entries
.. _yaml-settings-RecordsTypeCountSelector:
Parameters:
-- **section**: Unsigned integer
-- **record_type**: Unsigned integer
-- **minimum**: Unsigned integer
-- **maximum**: Unsigned integer
+- **section**: Unsigned integer - The section to match on
+- **record_type**: Unsigned integer - The record type to match on
+- **minimum**: Unsigned integer - The minimum number of entries
+- **maximum**: Unsigned integer - The maximum number of entries
.. _yaml-settings-RegexSelector:
Parameters:
-- **expression**: String
+- **expression**: String - The regular expression to match the QNAME
.. _yaml-settings-SNISelector:
Parameters:
-- **server_name**: String
+- **server_name**: String - The exact Server Name Indication value
.. _yaml-settings-TagSelector:
Parameters:
-- **tag**: String
-- **value**: String ``("")``
+- **tag**: String - The name of the tag that has to be set
+- **value**: String ``("")`` - If set, the value the tag has to be set to
.. _yaml-settings-TCPSelector:
Parameters:
-- **tcp**: Boolean
+- **tcp**: Boolean - Match TCP traffic if true, UDP traffic if false
.. _yaml-settings-TrailingDataSelector:
CustomLoadBalancingPolicyConfiguration
--------------------------------------
-- **name**: String
-- **function_name**: String ``("")``
-- **function_code**: String ``("")``
-- **function_file**: String ``("")``
-- **ffi**: Boolean ``(false)``
-- **per_thread**: Boolean ``(false)``
+Settings for a custom load-balancing policy
+
+- **name**: String - The name of this load-balancing policy
+- **function_name**: String ``("")`` - The name of a Lua function implementing the custom load-balancing policy. If ``ffi`` is false, this function takes a table of :class:`Server` objects and a :class:`DNSQuestion` representing the current query, and must return the index of the selected server in the supplied table. If ``ffi`` is true, this function takes a ``const dnsdist_ffi_servers_list_t*`` and a ``dnsdist_ffi_dnsquestion_t*``
+- **function_code**: String ``("")`` - Same than ``function_name` but contain actual Lua code returning a function instead of a name
+- **function_file**: String ``("")`` - Same than ``function_name` but contain the path to a file containing actual Lua code returning a function instead of a name
+- **ffi**: Boolean ``(false)`` - Whether the function uses the faster but more complicated Lua FFI API
+- **per_thread**: Boolean ``(false)`` - If set, the resulting policy will be executed in a lock-free per-thread context, instead of running in the global Lua context. Note that ``function_name`` cannot be used, since this needs the Lua code to create the function in a new Lua context instead of just a function
.. _yaml-settings-DnstapLoggerConfiguration:
GeneralConfiguration
--------------------
-- **edns_udp_payload_size_self_generated_answers**: Unsigned integer ``(1232)``
-- **add_edns_to_self_generated_answers**: Boolean ``(true)``
-- **truncate_tc_answers**: Boolean ``(false)``
-- **fixup_case**: Boolean ``(false)``
-- **allow_empty_responses**: Boolean ``(false)``
-- **drop_empty_queries**: Boolean ``(false)``
-- **capabilities_to_retain**: Sequence of String ``("")``
+General settings
+
+- **edns_udp_payload_size_self_generated_answers**: Unsigned integer ``(1232)`` - Set the UDP payload size advertised via EDNS on self-generated responses. In accordance with :rfc:`RFC 6891 <6891#section-6.2.5>`, values lower than 512 will be treated as equal to 512
+- **add_edns_to_self_generated_answers**: Boolean ``(true)`` - Whether to add EDNS to self-generated responses, provided that the initial query had EDNS
+- **truncate_tc_answers**: Boolean ``(false)`` - Remove any left-over records in responses with the TC bit set, in accordance with :rfc:`RFC 6891 <6891#section-7>`
+- **fixup_case**: Boolean ``(false)`` - If set, ensure that the case of the DNS qname in the response matches the one from the query
+- **allow_empty_responses**: Boolean ``(false)`` - Set to true (defaults to false) to allow empty responses (qdcount=0) with a NoError or NXDomain rcode (default) from backends. dnsdist drops these responses by default because it can't match them against the initial query since they don't contain the qname, qtype and qclass, and therefore the risk of collision is much higher than with regular responses
+- **drop_empty_queries**: Boolean ``(false)`` - Set to true (defaults to false) to drop empty queries (qdcount=0) right away, instead of answering with a NotImp rcode. dnsdist used to drop these queries by default because most rules and existing Lua code expects a query to have a qname, qtype and qclass. However :rfc:`7873` uses these queries to request a server cookie, and :rfc:`8906` as a conformance test, so answering these queries with NotImp is much better than not answering at all
+- **capabilities_to_retain**: Sequence of String ``("")`` - Accept a Linux capability as a string, or a list of these, to retain after startup so that privileged operations can still be performed at runtime.
+Keeping ``CAP_SYS_ADMIN`` on kernel 5.8+ for example allows loading eBPF programs and altering eBPF maps at runtime even if the ``kernel.unprivileged_bpf_disabled`` sysctl is set.
+Note that this does not grant the capabilities to the process, doing so might be done by running it as root which we don't advise, or by adding capabilities via the systemd unit file, for example.
+Please also be aware that switching to a different user via ``--uid`` will still drop all capabilities."
+
.. _yaml-settings-HealthCheckConfiguration:
LoadBalancingPoliciesConfiguration
----------------------------------
-- **default_policy**: String ``(leastOutstanding)``
-- **servfail_on_no_server**: Boolean ``(false)``
-- **round_robin_servfail_on_no_server**: Boolean ``(false)``
-- **weighted_balancing_factor**: Double ``(0.0)``
-- **consistent_hashing_balancing_factor**: Double ``(0.0)``
-- **custom_policies**: Sequence of :ref:`CustomLoadBalancingPolicyConfiguration <yaml-settings-CustomLoadBalancingPolicyConfiguration>`
-- **hash_perturbation**: Unsigned integer ``(0)``
+Setting for load-balancing policies
+
+- **default_policy**: String ``(leastOutstanding)`` - Set the default server selection policy
+- **servfail_on_no_server**: Boolean ``(false)`` - If set, return a ServFail when no servers are available, instead of the default behaviour of dropping the query
+- **round_robin_servfail_on_no_server**: Boolean ``(false)`` - By default the roundrobin load-balancing policy will still try to select a backend even if all backends are currently down. Setting this to true will make the policy fail and return that no server is available instead
+- **weighted_balancing_factor**: Double ``(0.0)`` - Set the maximum imbalance between the number of outstanding queries intended for a given server, based on its weight, and the actual number, when using the ``whashed`` or ``wrandom`` load-balancing policy. Default is 0, which disables the bounded-load algorithm
+- **consistent_hashing_balancing_factor**: Double ``(0.0)`` - Set the maximum imbalance between the number of outstanding queries intended for a given server, based on its weight, and the actual number, when using the ``chashed`` consistent hashing load-balancing policy. Default is 0, which disables the bounded-load algorithm
+- **custom_policies**: Sequence of :ref:`CustomLoadBalancingPolicyConfiguration <yaml-settings-CustomLoadBalancingPolicyConfiguration>` - Custom load-balancing policies implemented in Lua
+- **hash_perturbation**: Unsigned integer ``(0)`` - Set the hash perturbation value to be used in the ``whashed`` policy instead of a random one, allowing to have consistent ``whashed`` results on different instances
.. _yaml-settings-LoggingConfiguration:
PacketCacheConfiguration
------------------------
-- **name**: String
-- **size**: Unsigned integer
-- **deferrable_insert_lock**: Boolean ``(true)``
-- **dont_age**: Boolean ``(false)``
-- **keep_stale_data**: Boolean ``(false)``
-- **max_negative_ttl**: Unsigned integer ``(3600)``
-- **max_ttl**: Unsigned integer ``(86400)``
-- **min_ttl**: Unsigned integer ``(0)``
-- **shards**: Unsigned integer ``(20)``
-- **parse_ecs**: Boolean ``(false)``
-- **stale_ttl**: Unsigned integer ``(60)``
-- **temporary_failure_ttl**: Unsigned integer ``(60)``
-- **cookie_hashing**: Boolean ``(false)``
-- **maximum_entry_size**: Unsigned integer ``(0)``
-- **options_to_skip**: Sequence of String ``("")``
+Packet-cache settings
+
+- **name**: String - The name of the packet cache object
+- **size**: Unsigned integer - The maximum number of entries in this cache
+- **deferrable_insert_lock**: Boolean ``(true)`` - Whether the cache should give up insertion if the lock is held by another thread, or simply wait to get the lock
+- **dont_age**: Boolean ``(false)`` - Don’t reduce TTLs when serving from the cache. Use this when dnsdist fronts a cluster of authoritative servers
+- **keep_stale_data**: Boolean ``(false)`` - Whether to suspend the removal of expired entries from the cache when there is no backend available in at least one of the pools using this cache
+- **max_negative_ttl**: Unsigned integer ``(3600)`` - Cache a NXDomain or NoData answer from the backend for at most this amount of seconds, even if the TTL of the SOA record is higher
+- **max_ttl**: Unsigned integer ``(86400)`` - Cap the TTL for records to his number
+- **min_ttl**: Unsigned integer ``(0)`` - Don’t cache entries with a TTL lower than this
+- **shards**: Unsigned integer ``(20)`` - Number of shards to divide the cache into, to reduce lock contention
+- **parse_ecs**: Boolean ``(false)`` - Whether any EDNS Client Subnet option present in the query should be extracted and stored to be able to detect hash collisions involving queries with the same qname, qtype and qclass but a different incoming ECS value. Enabling this option adds a parsing cost and only makes sense if at least one backend might send different responses based on the ECS value, so it's disabled by default. Enabling this option is required for the :doc:`../advanced/zero-scope` option to work
+- **stale_ttl**: Unsigned integer ``(60)`` - When the backend servers are not reachable, and global configuration setStaleCacheEntriesTTL is set appropriately, TTL that will be used when a stale cache entry is returned
+- **temporary_failure_ttl**: Unsigned integer ``(60)`` - On a SERVFAIL or REFUSED from the backend, cache for this amount of seconds
+- **cookie_hashing**: Boolean ``(false)`` - If true, EDNS Cookie values will be hashed, resulting in separate entries for different cookies in the packet cache. This is required if the backend is sending answers with EDNS Cookies, otherwise a client might receive an answer with the wrong cookie
+- **maximum_entry_size**: Unsigned integer ``(4096)`` - The maximum size, in bytes, of a DNS packet that can be inserted into the packet cache
+- **options_to_skip**: Sequence of String ``("")`` - Extra list of EDNS option codes to skip when hashing the packet (if ``cookie_hashing`` above is false, EDNS cookie option number will be added to this list internally)
.. _yaml-settings-PoolConfiguration:
PoolConfiguration
-----------------
-- **name**: String
-- **packet_cache**: String
-- **policy**: String ``(leastOutstanding)``
+Settings for a pool of servers
+
+- **name**: String - The name of this pool
+- **packet_cache**: String ``("")`` - The name of a packet cache object, if any
+- **policy**: String ``("")`` - The name of the load-balancing policy associated to this pool. If left empty, the global policy will be used
.. _yaml-settings-ProtoBufMetaConfiguration:
ProxyProtocolConfiguration
--------------------------
-- **acl**: Sequence of String ``("")``
-- **maximum_payload_size**: Unsigned integer ``(512)``
-- **apply_acl_to_proxied_clients**: Boolean ``(false)``
+Proxy Protocol-related settings
+
+- **acl**: Sequence of String ``("")`` - Set the list of netmasks from which a Proxy Protocol header will be required, over UDP, TCP and DNS over TLS. The default is empty. Note that a proxy protocol payload will be required from these clients, regular DNS queries will no longer be accepted if they are not preceded by a proxy protocol payload. Be also aware that, if ``apply_acl_to_proxied_clients`` is set (default is false), the general ACL will be applied to the source IP address as seen by dnsdist first, but also to the source IP address provided in the Proxy Protocol header.
+- **maximum_payload_size**: Unsigned integer ``(512)`` - Set the maximum size of a Proxy Protocol payload that dnsdist is willing to accept, in bytes. The default is 512, which is more than enough except for very large TLV data. This setting can’t be set to a value lower than 16 since it would deny of Proxy Protocol headers
+- **apply_acl_to_proxied_clients**: Boolean ``(false)`` - Whether the general ACL should be applied to the source IP address provided in the Proxy Protocol header, in addition to being applied to the source IP address as seen by dnsdist first
.. _yaml-settings-ProxyProtocolValueConfiguration:
QueryCountConfiguration
-----------------------
-- **enabled**: Boolean ``(false)``
-- **filter_function_name**: String ``("")``
-- **filter_function_code**: String ``("")``
-- **filter_function_file**: String ``("")``
+Per-record Carbon statistics of the amount of queries. See :doc:`../guides/carbon`
+
+- **enabled**: Boolean ``(false)`` - Enable per-record Carbon statistics of the amount of queries
+- **filter_function_name**: String ``("")`` - The name of a Lua function to filter which query should be accounted for, and how
+- **filter_function_code**: String ``("")`` - The code of a Lua function to filter which query should be accounted for, and how
+- **filter_function_file**: String ``("")`` - The path to a file containing the code of a Lua function to filter which query should be accounted for, and how
.. _yaml-settings-QueryRuleConfiguration:
SnmpConfiguration
-----------------
-- **enabled**: Boolean ``(false)``
-- **traps_enabled**: Boolean ``(false)``
-- **daemon_socket**: String ``("")``
+SNMP-related settings
+
+- **enabled**: Boolean ``(false)`` - Enable SNMP support
+- **traps_enabled**: Boolean ``(false)`` - Enable the sending of SNMP traps for specific events
+- **daemon_socket**: String ``("")`` - A string specifying how to connect to the daemon agent. This is usually the path to a UNIX socket, but e.g. ``tcp:localhost:705`` can be used as well. By default, SNMP agent’s default socket is used
.. _yaml-settings-StructuredLoggingConfiguration:
projects / thirdparty / pdns.git / commitdiff
