Can be used to handle IP addresses differently for a certain time.
- .. method:: TimedIPSetRule:add(address, seconds)
+ .. method:: add(address, seconds)
Add an IP address to the set for the next ``second`` seconds.
:param ComboAddress address: The address to add
:param int seconds: Time to keep the address in the Rule
- .. method:: TimedIPSetRule:cleanup()
+ .. method:: cleanup()
Purge the set from expired IP addresses
- .. method:: TimedIPSetRule:clear()
+ .. method:: clear()
Clear the entire set
- .. method:: TimedIPSetRule:slice()
+ .. method:: slice()
Convert the TimedIPSetRule into a DNSRule that can be passed to :func:`addAction`
This represents the pool where zero or more servers are part of.
- .. method:: ServerPool:getCache() -> PacketCache
+ .. method:: getCache() -> PacketCache
Returns the :class:`PacketCache` for this pool or nil.
- .. method:: ServerPool:getZeroScope()
+ .. method:: getZeroScope()
.. versionadded:: 2.1.0
Whether dnsdist will enable the EDNS Client Subnet :doc:`../advanced/zero-scope` feature when looking up into the cache,
when all servers from this pool are down.
- .. method:: ServerPool:getECS()
+ .. method:: getECS()
Whether dnsdist will add EDNS Client Subnet information to the query before looking up into the cache,
when all servers from this pool are down. For more information see :meth:`ServerPool:setECS`.
- .. method:: ServerPool:setCache(cache)
+ .. method:: setCache(cache)
Adds ``cache`` as the pool's cache.
:param PacketCache cache: The new cache to add to the pool
- .. method:: ServerPool:setZeroScope(enabled)
+ .. method:: setZeroScope(enabled)
.. versionadded:: 2.1.0
:param bool enabled: Whether to enable the zero scope feature for this pool
- .. method:: ServerPool:setECS()
+ .. method:: setECS()
Set to true if dnsdist should add EDNS Client Subnet information to the query before looking up into the cache,
when all servers from this pool are down. If at least one server is up, the preference of the
and have EDNS Client Subnet enabled, since the queries in the cache will have been inserted with
ECS information. Default is false.
- .. method:: ServerPool:unsetCache()
+ .. method:: unsetCache()
Removes the cache from this pool.
Represents a cache that can be part of :class:`ServerPool`.
- .. method:: PacketCache:dump(fname [, rawResponse=false])
+ .. method:: dump(fname [, rawResponse=false])
.. versionchanged:: 2.0.0
``rawResponse`` added
:param str fname: The path to a file where the cache summary should be dumped. Note that if the target file already exists, it will not be overwritten.
:param bool rawResponse: Dump the raw packet response encoded with base64.
- .. method:: PacketCache:expunge(n)
+ .. method:: expunge(n)
Remove entries from the cache, leaving at most ``n`` entries
:param int n: Number of entries to keep
- .. method:: PacketCache:expungeByName(name [, qtype=DNSQType.ANY[, suffixMatch=false]])
+ .. method:: expungeByName(name [, qtype=DNSQType.ANY[, suffixMatch=false]])
.. versionchanged:: 1.6.0
``name`` can now also be a string
:param int qtype: The type to expunge, can be a pre-defined :ref:`DNSQType`
:param bool suffixMatch: When set to true, remove all entries under ``name``
- .. method:: PacketCache:getAddressListByDomain(domain)
+ .. method:: getAddressListByDomain(domain)
.. versionadded:: 1.8.0
:param DNSName domain: The domain to look for
- .. method:: PacketCache:getDomainListByAddress(addr)
+ .. method:: getDomainListByAddress(addr)
.. versionadded:: 1.8.0
:param ComboAddress addr: The address to look for
- .. method:: PacketCache:getStats()
+ .. method:: getStats()
.. versionadded:: 1.4.0
Return the cache stats (number of entries, hits, misses, deferred lookups, deferred inserts, lookup collisions, insert collisions and TTL too shorts) as a Lua table.
- .. method:: PacketCache:isFull() -> bool
+ .. method:: isFull() -> bool
Return true if the cache has reached the maximum number of entries.
- .. method:: PacketCache:printStats()
+ .. method:: printStats()
Print the cache stats (number of entries, hits, misses, deferred lookups, deferred inserts, lookup collisions, insert collisions and TTL too shorts).
- .. method:: PacketCache:purgeExpired(n)
+ .. method:: purgeExpired(n)
Remove expired entries from the cache until there is at most ``n`` entries remaining in the cache.
:param int n: Number of entries to keep
- .. method:: PacketCache:toString() -> string
+ .. method:: toString() -> string
Return the number of entries in the Packet Cache, and the maximum number of entries
This object represents an address and port dnsdist is listening on. When ``reuseport`` is in use, several ClientState objects can be present for the same address and port.
- .. method:: ClientState:attachFilter(filter)
+ .. method:: attachFilter(filter)
Attach a BPF filter to this frontend.
:param BPFFilter filter: The filter to attach to this frontend
- .. method:: ClientState:detachFilter()
+ .. method:: detachFilter()
Remove the BPF filter associated to this frontend, if any.
- .. method:: ClientState:getEffectiveTLSProvider() -> string
+ .. method:: getEffectiveTLSProvider() -> string
.. versionadded:: 1.7.0
Return the name of the TLS provider actually used.
- .. method:: ClientState:getRequestedTLSProvider() -> string
+ .. method:: getRequestedTLSProvider() -> string
.. versionadded:: 1.7.0
Return the name of the TLS provider requested in the configuration.
- .. method:: ClientState:getType() -> string
+ .. method:: getType() -> string
.. versionadded:: 1.7.0
Return the type of the frontend: UDP, UDP (DNSCrypt), TCP, TCP (DNSCrypt), TCP (DNS over TLS) or TCP (DNS over HTTPS).
- .. method:: ClientState:toString() -> string
+ .. method:: toString() -> string
Return the address and port this frontend is listening on.
:returns: The address and port this frontend is listening on
- .. attribute:: ClientState.muted
+ .. attribute:: muted
If set to true, queries received on this frontend will be normally processed and sent to a backend if needed, but no response will be ever be sent to the client over UDP. TCP queries are processed normally and responses sent to the client.
Represent the current state of a dynamic block.
- .. attribute:: DynBlock.action
+ .. attribute:: action
The action of this block, as an integer representing a :ref:`DNSAction <DNSAction>`.
- .. attribute:: DynBlock.blocks
+ .. attribute:: blocks
The number of queries blocked.
- .. attribute:: DynBlock.bpf
+ .. attribute:: bpf
Whether this block is using eBPF, as a boolean.
- .. attribute:: DynBlock.domain
+ .. attribute:: domain
The domain that is blocked, as a string, for Suffix Match Tree blocks.
- .. attribute:: DynBlock.reason
+ .. attribute:: reason
The reason why this block was inserted, as a string.
- .. attribute:: DynBlock.until
+ .. attribute:: until
The time (in seconds since Epoch) at which the block will expire.
- .. attribute:: DynBlock.warning
+ .. attribute:: warning
Whether this block is only a warning one (true) or is really enforced (false).
* ``tagName``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set
* ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set. Default is an empty string
- .. method:: DynBlockRulesGroup:setCacheMissRatio(ratio, seconds, reason, blockingTime, minimumNumberOfResponses, minimumGlobalCacheHitRatio, [, action [, warningRate, [options]]])
+ .. method:: setCacheMissRatio(ratio, seconds, reason, blockingTime, minimumNumberOfResponses, minimumGlobalCacheHitRatio, [, action [, warningRate, [options]]])
.. versionadded:: 1.9.0
* ``tagName``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set
* ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set. Default is an empty string.
- .. method:: DynBlockRulesGroup:setMasks(v4, v6, port)
+ .. method:: setMasks(v4, v6, port)
.. versionadded:: 1.7.0
:param int v6: Number of bits to keep for IPv6 addresses. Default is 128
:param int port: Number of bits of port to consider over IPv4. Default is 0 meaning that the port is not taken into account
- .. method:: DynBlockRulesGroup:setQueryRate(rate, seconds, reason, blockingTime [, action [, warningRate, [options]]])
+ .. method:: setQueryRate(rate, seconds, reason, blockingTime [, action [, warningRate, [options]]])
.. versionchanged:: 2.0.0
``options`` optional parameter added
* ``tagName``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set
* ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set. Default is an empty string
- .. method:: DynBlockRulesGroup:setNewBlockInsertedHook(hook)
+ .. method:: setNewBlockInsertedHook(hook)
.. versionadded:: 1.9.0
* the duration of the block in seconds
* whether this is a warning block (true) or not (false)
- .. method:: DynBlockRulesGroup:setRCodeRate(rcode, rate, seconds, reason, blockingTime [, action [, warningRate, [options]]])
+ .. method:: setRCodeRate(rcode, rate, seconds, reason, blockingTime [, action [, warningRate, [options]]])
.. versionadded:: 2.0.0
``options`` optional parameter added
* ``tagName``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set
* ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set. Default is an empty string
- .. method:: DynBlockRulesGroup:setRCodeRatio(rcode, ratio, seconds, reason, blockingTime, minimumNumberOfResponses [, action [, warningRate, [options]]])
+ .. method:: setRCodeRatio(rcode, ratio, seconds, reason, blockingTime, minimumNumberOfResponses [, action [, warningRate, [options]]])
.. versionadded:: 1.5.0
* ``tagName``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set
* ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set. Default is an empty string
- .. method:: DynBlockRulesGroup:setQTypeRate(qtype, rate, seconds, reason, blockingTime [, action [, warningRate, [options]]])
+ .. method:: setQTypeRate(qtype, rate, seconds, reason, blockingTime [, action [, warningRate, [options]]])
.. versionadded:: 2.0.0
``options`` optional parameter added
* ``tagName``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set
* ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set. Default is an empty string
- .. method:: DynBlockRulesGroup:setResponseByteRate(rate, seconds, reason, blockingTime [, action [, warningRate, [options]]])
+ .. method:: setResponseByteRate(rate, seconds, reason, blockingTime [, action [, warningRate, [options]]])
.. versionadded:: 2.0.0
``options`` optional parameter added
* ``tagName``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set
* ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set. Default is an empty string
- .. method:: DynBlockRulesGroup:setSuffixMatchRule(seconds, reason, blockingTime, action, visitor, [options])
+ .. method:: setSuffixMatchRule(seconds, reason, blockingTime, action, visitor, [options])
.. versionadded:: 1.4.0
* ``tagName``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set
* ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set. Default is an empty string
- .. method:: DynBlockRulesGroup:setSuffixMatchRuleFFI(seconds, reason, blockingTime, action , visitor, [options])
+ .. method:: setSuffixMatchRuleFFI(seconds, reason, blockingTime, action , visitor, [options])
.. versionadded:: 1.4.0
* ``tagName``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set
* ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set. Default is an empty string
- .. method:: DynBlockRulesGroup:apply()
+ .. method:: apply()
Walk the in-memory query and response ring buffers and apply the configured rate-limiting rules, adding dynamic blocks when the limits have been exceeded.
- .. method:: DynBlockRulesGroup:setQuiet(quiet)
+ .. method:: setQuiet(quiet)
.. versionadded:: 1.4.0
:param bool quiet: True means that insertions will not be logged, false that they will. Default is false.
- .. method:: DynBlockRulesGroup:excludeDomains(domains)
+ .. method:: excludeDomains(domains)
.. versionadded:: 1.4.0
:param str domain: A domain, or list of domains, as strings, like for example "powerdns.com"
- .. method:: DynBlockRulesGroup:excludeRange(netmasks)
+ .. method:: excludeRange(netmasks)
.. versionchanged:: 1.6.0
This method now accepts a :class:`NetmaskGroup` object.
:param list netmasks: A :class:`NetmaskGroup` object, or a netmask or list of netmasks as strings, like for example "192.0.2.1/24"
- .. method:: DynBlockRulesGroup:includeRange(netmasks)
+ .. method:: includeRange(netmasks)
.. versionchanged:: 1.6.0
This method now accepts a :class:`NetmaskGroup` object.
:param list netmasks: A :class:`NetmaskGroup` object, or a netmask or list of netmasks as strings, like for example "192.0.2.1/24"
- .. method:: DynBlockRulesGroup:removeRange(netmasks)
+ .. method:: removeRange(netmasks)
.. versionadded:: 1.8.3
:param list netmasks: A :class:`NetmaskGroup` object, or a netmask or list of netmasks as strings, like for example "192.0.2.1/24"
- .. method:: DynBlockRulesGroup:toString()
+ .. method:: toString()
Return a string describing the rules and range exclusions of this DynBlockRulesGroup.
Represent a given node, for the visitor functions used with :meth:`DynBlockRulesGroup:setSuffixMatchRule` and :meth:`DynBlockRulesGroup:setSuffixMatchRuleFFI`.
- .. attribute:: StatNode.fullname
+ .. attribute:: fullname
The complete name of that node, ie 'www.powerdns.com.'.
- .. attribute:: StatNode.labelsCount
+ .. attribute:: labelsCount
The number of labels in that node, for example 3 for 'www.powerdns.com.'.
- .. method:: StatNode:numChildren
+ .. method:: numChildren
The number of children of that node.
Represent the metrics for a given node, for the visitor functions used with :meth:`DynBlockRulesGroup:setSuffixMatchRule` and :meth:`DynBlockRulesGroup:setSuffixMatchRuleFFI`.
- .. attribute:: StatNodeStats.bytes
+ .. attribute:: bytes
The number of bytes for all responses returned for that node.
- .. attribute:: StatNodeStats.drops
+ .. attribute:: drops
The number of drops for that node.
- .. attribute:: StatNodeStats.noerrors
+ .. attribute:: noerrors
The number of No Error answers returned for that node.
- .. attribute:: StatNodeStats.hits
+ .. attribute:: hits
.. versionadded:: 1.8.0
The number of cache hits for that node.
- .. attribute:: StatNodeStats.nxdomains
+ .. attribute:: nxdomains
The number of NXDomain answers returned for that node.
- .. attribute:: StatNodeStats.queries
+ .. attribute:: queries
The number of queries for that node.
- .. attribute:: StatNodeStats.servfails
+ .. attribute:: servfails
The number of Server Failure answers returned for that node.
Represent a set of DNS suffixes for quick matching.
- .. method:: SuffixMatchNode:add(name)
+ .. method:: add(name)
.. versionchanged:: 1.4.0
This method now accepts strings, lists of DNSNames and lists of strings.
:param string name: The suffix to add to the set.
:param table name: The suffixes to add to the set. Elements of the table should be of the same type, either DNSName or string.
- .. method:: SuffixMatchNode:check(name) -> bool
+ .. method:: check(name) -> bool
Return true if the given name is a sub-domain of one of those in the set, and false otherwise.
:param DNSName name: The name to test against the set.
- .. method:: SuffixMatchNode:getBestMatch(name) -> DNSName
+ .. method:: getBestMatch(name) -> DNSName
.. versionadded:: 1.8.0
:param DNSName name: The name to look up.
- .. method:: SuffixMatchNode:remove(name)
+ .. method:: remove(name)
.. versionadded:: 1.5.0
This object represents an address and port dnsdist is listening on for DNS over HTTPS queries.
- .. method:: DOHFrontend:getAddressAndPort() -> string
+ .. method:: getAddressAndPort() -> string
.. versionadded:: 1.7.1
Return the address and port this frontend is listening on.
- .. method:: DOHFrontend:loadNewCertificatesAndKeys(certFile(s), keyFile(s))
+ .. method:: loadNewCertificatesAndKeys(certFile(s), keyFile(s))
.. versionadded:: 1.6.1
:param str certFile(s): The path to a X.509 certificate file in PEM format, a list of paths to such files, or a TLSCertificate object.
:param str keyFile(s): The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if ``certFile`` contains TLSCertificate objects.
- .. method:: DOHFrontend:loadTicketsKeys(ticketsKeysFile)
+ .. method:: loadTicketsKeys(ticketsKeysFile)
Load new tickets keys from the selected file, replacing the existing ones. These keys should be rotated often and never written to persistent storage to preserve forward secrecy. The default is to generate a random key. dnsdist supports several tickets keys to be able to decrypt existing sessions after the rotation.
See :doc:`../advanced/tls-sessions-management` for more information.
:param str ticketsKeysFile: The path to a file from where TLS tickets keys should be loaded.
- .. method:: DOHFrontend:loadTicketsKey(key)
+ .. method:: loadTicketsKey(key)
Load a new TLS tickets key.
:param str key: the new raw TLS tickets key to load.
- .. method:: DOHFrontend:reloadCertificates()
+ .. method:: reloadCertificates()
Reload the current TLS certificate and key pairs.
- .. method:: DOHFrontend:rotateTicketsKey()
+ .. method:: rotateTicketsKey()
Replace the current TLS tickets key by a new random one.
- .. method:: DOHFrontend:setResponsesMap(rules)
+ .. method:: setResponsesMap(rules)
Set a list of HTTP response rules allowing to intercept HTTP queries very early, before the DNS payload has been processed, and send custom responses including error pages, redirects and static content.
This object represents an address and port dnsdist is listening on for DNS over HTTP3 queries.
- .. method:: DOH3Frontend:reloadCertificates()
+ .. method:: reloadCertificates()
Reload the current TLS certificate and key pairs.
This object represents an address and port dnsdist is listening on for DNS over QUIC queries.
- .. method:: DOQFrontend:reloadCertificates()
+ .. method:: reloadCertificates()
Reload the current TLS certificate and key pairs.
This object represents an entry from the in-memory ring buffers, query or response.
- .. attribute:: LuaRingEntry.backend
+ .. attribute:: backend
If this entry is a response, the backend from which it has been received as a :ref:`ComboAddress`.
-.. attribute:: LuaRingEntry.dnsheader
+.. attribute:: dnsheader
The :ref:`DNSHeader` of this entry.
- .. attribute:: LuaRingEntry.isResponse
+ .. attribute:: isResponse
Whether this entry is a response (true) or a request (false).
- .. attribute:: LuaRingEntry.macAddress
+ .. attribute:: macAddress
The MAC address of the client as a string, if available.
- .. attribute:: LuaRingEntry.protocol
+ .. attribute:: protocol
The protocol (Do53 UDP, Do53 TCP, DoT, DoH, ...) over which this entry was received, as a string.
- .. attribute:: LuaRingEntry.qname
+ .. attribute:: qname
The qname of this entry as a :ref:`DNSName`.
- .. attribute:: LuaRingEntry.qtype
+ .. attribute:: qtype
The qtype of this entry as an integer.
- .. attribute:: LuaRingEntry.requestor
+ .. attribute:: requestor
The requestor (client IP) of this entry as a :ref:`ComboAddress`.
- .. attribute:: LuaRingEntry.size
+ .. attribute:: size
The size of the DNS payload of that entry, in bytes.
-.. attribute:: LuaRingEntry.usec
+.. attribute:: usec
The response time (elapsed time between the request was received and the response sent) in milliseconds.
-.. attribute:: LuaRingEntry.when
+.. attribute:: when
The timestamp of this entry, as a :ref:`timespec`.
This object represents an address and port dnsdist is listening on for DNS over TLS queries.
- .. method:: TLSContext:loadTicketsKeys(ticketsKeysFile)
+ .. method:: loadTicketsKeys(ticketsKeysFile)
Load new tickets keys from the selected file, replacing the existing ones. These keys should be rotated often and never written to persistent storage to preserve forward secrecy. The default is to generate a random key. The OpenSSL provider supports several tickets keys to be able to decrypt existing sessions after the rotation, while the GnuTLS provider only supports one key.
See :doc:`../advanced/tls-sessions-management` for more information.
:param str ticketsKeysFile: The path to a file from where TLS tickets keys should be loaded.
- .. method:: TLSContext:rotateTicketsKey()
+ .. method:: rotateTicketsKey()
Replace the current TLS tickets key by a new random one.
This object represents the configuration of a listening frontend for DNS over TLS queries. To each frontend is associated a TLSContext.
- .. method:: TLSFrontend:getAddressAndPort() -> string
+ .. method:: getAddressAndPort() -> string
.. versionadded:: 1.7.1
Return the address and port this frontend is listening on.
- .. method:: TLSFrontend:loadNewCertificatesAndKeys(certFile(s), keyFile(s))
+ .. method:: loadNewCertificatesAndKeys(certFile(s), keyFile(s))
Create and switch to a new TLS context using the same options than were passed to the corresponding `addTLSLocal()` directive, but loading new certificates and keys from the selected files, replacing the existing ones.
:param str certFile(s): The path to a X.509 certificate file in PEM format, or a list of paths to such files.
:param str keyFile(s): The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones.
- .. method:: TLSFrontend:loadTicketsKeys(ticketsKeysFile)
+ .. method:: loadTicketsKeys(ticketsKeysFile)
.. versionadded:: 1.6.0
:param str ticketsKeysFile: The path to a file from where TLS tickets keys should be loaded.
- .. method:: TLSFrontend:loadTicketsKey(key)
+ .. method:: loadTicketsKey(key)
Load a new TLS tickets key.
:param str key: the new raw TLS tickets key to load.
- .. method:: TLSFrontend:reloadCertificates()
+ .. method:: reloadCertificates()
.. versionadded:: 1.6.0
Reload the current TLS certificate and key pairs.
- .. method:: TLSFrontend:rotateTicketsKey()
+ .. method:: rotateTicketsKey()
.. versionadded:: 1.6.0
Represents a DNSCrypt certificate.
- .. method:: DNSCryptCert:getClientMagic() -> string
+ .. method:: getClientMagic() -> string
Return this certificate's client magic value.
- .. method:: DNSCryptCert:getEsVersion() -> string
+ .. method:: getEsVersion() -> string
Return the cryptographic construction to use with this certificate,.
- .. method:: DNSCryptCert:getMagic() -> string
+ .. method:: getMagic() -> string
Return the certificate magic number.
- .. method:: DNSCryptCert:getProtocolMinorVersion() -> string
+ .. method:: getProtocolMinorVersion() -> string
Return this certificate's minor version.
- .. method:: DNSCryptCert:getResolverPublicKey() -> string
+ .. method:: getResolverPublicKey() -> string
Return the public key corresponding to this certificate.
- .. method:: DNSCryptCert:getSerial() -> int
+ .. method:: getSerial() -> int
Return the certificate serial number.
- .. method:: DNSCryptCert:getSignature() -> string
+ .. method:: getSignature() -> string
Return this certificate's signature.
- .. method:: DNSCryptCert:getTSEnd() -> int
+ .. method:: getTSEnd() -> int
Return the date that the certificate is valid from, as a Unix timestamp.
- .. method:: DNSCryptCert:getTSStart() -> int
+ .. method:: getTSStart() -> int
Return the date that the certificate is valid until (inclusive), as a Unix timestamp
Represents a pair of DNSCrypt certificate and associated key
- .. method:: DNSCryptCertificatePair:getCertificate() -> DNSCryptCert
+ .. method:: getCertificate() -> DNSCryptCert
Return the certificate.
- .. method:: DNSCryptCertificatePair:isActive() -> bool
+ .. method:: isActive() -> bool
Return whether this pair is active and will be advertised to clients.
Represents a DNSCrypt content. Can be used to rotate certs.
- .. method:: DNSCryptContext:addNewCertificate(cert, key[, active])
+ .. method:: addNewCertificate(cert, key[, active])
Add a new certificate to the given context. Active certificates are advertised to
clients, inactive ones are not.
:param DNSCryptPrivateKey key: The private key corresponding to the certificate
:param bool active: Whether the certificate should be advertised to clients. Default is true
- .. method:: DNSCryptContext:generateAndLoadInMemoryCertificate(keyfile, serial, begin, end [, version]) -> bool
+ .. method:: generateAndLoadInMemoryCertificate(keyfile, serial, begin, end [, version]) -> bool
.. versionchanged:: 2.0.0
A return value indicating whether the certificate was correctly loaded has been added. Before 2.0.0 the method did not return any value.
:param int end: Unix timestamp from until the certificate is valid
:param DNSCryptExchangeVersion version: The exchange version to use. Possible values are ``DNSCryptExchangeVersion::VERSION1`` (default, X25519-XSalsa20Poly1305) and ``DNSCryptExchangeVersion::VERSION2`` (X25519-XChacha20Poly1305)
- .. method:: DNSCryptContext:getCertificate(index) -> DNSCryptCert
+ .. method:: getCertificate(index) -> DNSCryptCert
Return the certificate with index `index`.
:param int index: The index of the certificate, starting at 0
- .. method:: DNSCryptContext:getCertificatePair(index) -> DNSCryptCertificatePair
+ .. method:: getCertificatePair(index) -> DNSCryptCertificatePair
Return the certificate pair with index `index`.
:param int index: The index of the certificate, starting at 0
- .. method:: DNSCryptContext:getCertificatePair(index) -> table of DNSCryptCertificatePair
+ .. method:: getCertificatePair(index) -> table of DNSCryptCertificatePair
Return a table of certificate pairs.
- .. method:: DNSCryptContext:getProviderName() -> string
+ .. method:: getProviderName() -> string
Return the provider name
- .. method:: DNSCryptContext:loadNewCertificate(certificate, keyfile[, active])
+ .. method:: loadNewCertificate(certificate, keyfile[, active])
Load a new certificate and the corresponding private key. If `active` is false, the
certificate will not be advertised to clients but can still be used to answer queries
:param string keyfile: Path to the corresponding key file
:param bool active: Whether the certificate should be marked as active. Default is true
- .. method:: DNSCryptContext:markActive(serial)
+ .. method:: markActive(serial)
Mark the certificate with serial `serial` as active, meaning it will be advertised to clients.
:param int serial: The serial of the number to mark as active
- .. method:: DNSCryptContext:markInactive(serial)
+ .. method:: markInactive(serial)
Mark the certificate with serial `serial` as inactive, meaning it will not be advertised
to clients but can still be used to answer queries tied to this certificate.
:param int serial: The serial of the number to mark as inactive
- .. method:: DNSCryptContext:printCertificates()
+ .. method:: printCertificates()
Print all the certificates.
- .. method:: DNSCryptContext:reloadCertificates()
+ .. method:: reloadCertificates()
.. versionadded:: 1.6.0
Reload the current TLS certificate and key pairs.
- .. method:: DNSCryptContext:removeInactiveCertificate(serial)
+ .. method:: removeInactiveCertificate(serial)
Remove the certificate with serial `serial`. It will not be possible to answer queries tied
to this certificate, so it should have been marked as inactive for a certain time before that.
A ``DNSName`` object represents a name in the DNS.
It is returned by several functions and has several functions to programmatically interact with it.
- .. method:: DNSName:chopOff() -> bool
+ .. method:: chopOff() -> bool
Removes the left-most label and returns ``true``.
``false`` is returned if no label was removed
- .. method:: DNSName:countLabels() -> int
+ .. method:: countLabels() -> int
Returns the number of DNSLabels in the name
- .. method:: DNSName:isPartOf(name) -> bool
+ .. method:: isPartOf(name) -> bool
Returns true if the DNSName is part of the DNS tree of ``name``.
:param DNSName name: The name to check against
- .. method:: DNSName:makeRelative(name) -> DNSName
+ .. method:: makeRelative(name) -> DNSName
.. versionadded:: 1.8.0
:param DNSName name: The name to make us relative against
- .. method:: DNSName:toDNSString() -> string
+ .. method:: toDNSString() -> string
Returns a wire format form of the DNSName, suitable for usage in :func:`SpoofRawAction`.
- .. method:: DNSName:toString() -> string
+ .. method:: toString() -> string
DNSName:tostring() -> string
Returns a human-readable form of the DNSName.
- .. method:: DNSName:toStringNoDot() -> string
+ .. method:: toStringNoDot() -> string
.. versionadded:: 1.8.0
Returns a human-readable form of the DNSName, without the trailing dot.
- .. method:: DNSName:wirelength() -> int
+ .. method:: wirelength() -> int
Returns the length in bytes of the DNSName as it would be on the wire.
- .. method:: DNSName:append(labels: [DNSName,string])
+ .. method:: append(labels: [DNSName,string])
.. versionadded:: 2.2.0
local other_name = newDNSName("foobar.invalid")
n:append(other_name) -- n is now "example.com.example.foobar.invalid")
- .. method:: DNSName:prepend(labels: [DNSName,string])
+ .. method:: prepend(labels: [DNSName,string])
.. versionadded:: 2.2.0
A ``DNSNameSet`` object is a set of :class:`DNSName` objects.
- .. method:: DNSNameSet:add(name)
+ .. method:: add(name)
Adds the name to the set.
:param DNSName name: The name to add.
- .. method:: DNSNameSet:empty() -> bool
+ .. method:: empty() -> bool
Returns true is the DNSNameSet is empty.
- .. method:: DNSNameSet:clear()
+ .. method:: clear()
Clean up the set.
- .. method:: DNSNameSet:toString() -> string
+ .. method:: toString() -> string
Returns a human-readable form of the DNSNameSet.
- .. method:: DNSNameSet:size() -> int
+ .. method:: size() -> int
Returns the number of names in the set.
- .. method:: DNSNameSet:delete(name) -> int
+ .. method:: delete(name) -> int
Removes the name from the set. Returns the number of deleted elements.
:param DNSName name: The name to remove.
- .. method:: DNSNameSet:check(name) -> bool
+ .. method:: check(name) -> bool
Returns true if the set contains the name.
The DNSPacketOverlay object has several attributes, all of them read-only:
- .. attribute:: DNSPacketOverlay.qname
+ .. attribute:: qname
The qname of this packet, as a :ref:`DNSName`.
- .. attribute:: DNSPacketOverlay.qtype
+ .. attribute:: qtype
The type of the query in this packet.
- .. attribute:: DNSPacketOverlay.qclass
+ .. attribute:: qclass
The class of the query in this packet.
- .. attribute:: DNSPacketOverlay.dh
+ .. attribute:: dh
It also supports the following methods:
- .. method:: DNSPacketOverlay:getRecordsCountInSection(section) -> int
+ .. method:: getRecordsCountInSection(section) -> int
Returns the number of records in the ANSWER (1), AUTHORITY (2) and
ADDITIONAL (3) :ref:`DNSSection` of this packet. The number of records in the
:param int section: The section, see above
- .. method:: DNSPacketOverlay:getRecord(idx) -> DNSRecord
+ .. method:: getRecord(idx) -> DNSRecord
Get the record at the requested position. The records in the
QUESTION sections are not taken into account, so the first record
This object represents an unparsed DNS record, as returned by the :ref:`DNSPacketOverlay` class. It has several attributes, all of them read-only:
- .. attribute:: DNSRecord.name
+ .. attribute:: name
The name of this record, as a :ref:`DNSName`.
- .. attribute:: DNSRecord.type
+ .. attribute:: type
The type of this record.
- .. attribute:: DNSRecord.class
+ .. attribute:: class
The class of this record.
- .. attribute:: DNSRecord.ttl
+ .. attribute:: ttl
The TTL of this record.
- .. attribute:: DNSRecord.place
+ .. attribute:: place
The place (section) of this record.
- .. attribute:: DNSRecord.contentLength
+ .. attribute:: contentLength
The length, in bytes, of the rdata content of this record.
- .. attribute:: DNSRecord.contentOffset
+ .. attribute:: contentOffset
The offset since the beginning of the DNS payload, in bytes, at which the
rdata content of this record starts.
The DNSQuestion object has several attributes, many of them read-only:
- .. attribute:: DNSQuestion.deviceID
+ .. attribute:: deviceID
.. versionadded:: 1.8.0
The identifier of the remote device, which will be exported via ProtoBuf if set.
- .. attribute:: DNSQuestion.deviceName
+ .. attribute:: deviceName
.. versionadded:: 1.8.0
The name of the remote device, which will be exported via ProtoBuf if set.
- .. attribute:: DNSQuestion.dh
+ .. attribute:: dh
The :ref:`DNSHeader` of this query.
- .. attribute:: DNSQuestion.ecsOverride
+ .. attribute:: ecsOverride
Whether an existing ECS value should be overridden, settable.
- .. attribute:: DNSQuestion.ecsPrefixLength
+ .. attribute:: ecsPrefixLength
The ECS prefix length to use, settable.
- .. attribute:: DNSQuestion.len
+ .. attribute:: len
The length of the data starting at :attr:`DNSQuestion.dh`, including any trailing bytes following the DNS message.
- .. attribute:: DNSQuestion.localaddr
+ .. attribute:: localaddr
:ref:`ComboAddress` of the local bind this question was received on.
- .. attribute:: DNSQuestion.opcode
+ .. attribute:: opcode
Integer describing the OPCODE of the packet. Can be matched against :ref:`DNSOpcode`.
- .. attribute:: DNSQuestion.pool
+ .. attribute:: pool
.. versionadded:: 1.8.0
The pool of servers to which this query will be routed.
- .. attribute:: DNSQuestion.qclass
+ .. attribute:: qclass
QClass (as an unsigned integer) of this question.
Can be compared against :ref:`DNSClass`.
- .. attribute:: DNSQuestion.qname
+ .. attribute:: qname
:class:`DNSName` of this question.
- .. attribute:: DNSQuestion.qtype
+ .. attribute:: qtype
QType (as an unsigned integer) of this question.
Can be compared against the pre-defined :ref:`constants <DNSQType>` like ``DNSQType.A``, ``DNSQType.AAAA``.
- .. attribute:: DNSQuestion.remoteaddr
+ .. attribute:: remoteaddr
:ref:`ComboAddress` of the remote client.
- .. attribute:: DNSQuestion.requestorID
+ .. attribute:: requestorID
.. versionadded:: 1.8.0
The identifier of the requestor, which will be exported via ProtoBuf if set.
- .. attribute:: DNSQuestion.rcode
+ .. attribute:: rcode
RCode (as an unsigned integer) of this question.
Can be compared against :ref:`DNSRCode`
- .. attribute:: DNSQuestion.size
+ .. attribute:: size
The total size of the buffer starting at :attr:`DNSQuestion.dh`.
- .. attribute:: DNSQuestion.skipCache
+ .. attribute:: skipCache
Whether to skip cache lookup / storing the answer for this question, settable.
- .. attribute:: DNSQuestion.tempFailureTTL
+ .. attribute:: tempFailureTTL
On a SERVFAIL or REFUSED from the backend, cache for this amount of seconds, settable.
- .. attribute:: DNSQuestion.tcp
+ .. attribute:: tcp
Whether the query was received over TCP.
- .. attribute:: DNSQuestion.useECS
+ .. attribute:: useECS
Whether to send ECS to the backend, settable.
It also supports the following methods:
- .. method:: DNSQuestion:addProxyProtocolValue(type, value)
+ .. method:: addProxyProtocolValue(type, value)
.. versionadded:: 1.6.0
:param int type: The type of the new value, ranging from 0 to 255 (both included)
:param str value: The binary-safe value
- .. method:: DNSQuestion:getContent() -> str
+ .. method:: getContent() -> str
.. versionadded:: 1.8.0
Get the content of the DNS packet as a string
- .. method:: DNSQuestion:getDO() -> bool
+ .. method:: getDO() -> bool
Get the value of the DNSSEC OK bit.
:returns: true if the DO bit was set, false otherwise
- .. method:: DNSQuestion:getEDNSOptions() -> table
+ .. method:: getEDNSOptions() -> table
Return the list of EDNS Options, if any.
:returns: A table of EDNSOptionView objects, indexed on the ECS Option code
- .. method:: DNSQuestion::getElapsedUs -> double
+ .. method:: getElapsedUs() -> double
.. versionadded:: 1.9.8
:returns: A double indicating elapsed time in microseconds
- .. method:: DNSQuestion:getHTTPHeaders() -> table
+ .. method:: getHTTPHeaders() -> table
.. versionadded:: 1.4.0
.. versionchanged:: 1.8.0
:returns: A table of HTTP headers
- .. method:: DNSQuestion:getHTTPHost() -> string
+ .. method:: getHTTPHost() -> string
.. versionadded:: 1.4.0
:returns: The host of the DoH query
- .. method:: DNSQuestion:getHTTPPath() -> string
+ .. method:: getHTTPPath() -> string
.. versionadded:: 1.4.0
:returns: The path part of the DoH query URI
- .. method:: DNSQuestion:getHTTPQueryString() -> string
+ .. method:: getHTTPQueryString() -> string
.. versionadded:: 1.4.0
:returns: The query string part of the DoH query URI
- .. method:: DNSQuestion:getHTTPScheme() -> string
+ .. method:: getHTTPScheme() -> string
.. versionadded:: 1.4.0
:returns: The scheme of the DoH query, for example ``http`` or ``https``
- .. method:: DNSQuestion:getIncomingInterface() -> string
+ .. method:: getIncomingInterface() -> string
.. versionadded:: 1.9.10
:returns: The name of the network interface this query was received on, or an empty string.
- .. method:: DNSQuestion:getProtocol() -> string
+ .. method:: getProtocol() -> string
.. versionadded:: 1.7.0
:returns: A string
- .. method:: DNSQuestion:getProxyProtocolValues() -> table
+ .. method:: getProxyProtocolValues() -> table
.. versionadded:: 1.6.0
:returns: A table whose keys are types and values are binary-safe strings
- .. method:: DNSQuestion:getQueryTime -> timespec
+ .. method:: getQueryTime() -> timespec
.. versionadded:: 1.8.0
:returns: A :ref:`timespec` object
- .. method:: DNSQuestion:getServerNameIndication() -> string
+ .. method:: getServerNameIndication() -> string
.. versionadded:: 1.4.0
:returns: A string containing the TLS SNI value, if any
- .. method:: DNSQuestion:getTag(key) -> string
+ .. method:: getTag(key) -> string
Get the value of a tag stored into the DNSQuestion object.
:param string key: The tag's key
:returns: The tag's value if it was set, an empty string otherwise
- .. method:: DNSQuestion:getTagArray() -> table
+ .. method:: getTagArray() -> table
Get all the tags stored into the DNSQuestion object.
:returns: A table of tags, using strings as keys and values
- .. method:: DNSQuestion:getTraceID() -> string
+ .. method:: getTraceID() -> string
.. versionadded:: 2.1.0
:returns: A binary string containing the OpenTelemetry trace identifier
- .. method:: DNSQuestion:getSpanID() -> string
+ .. method:: getSpanID() -> string
.. versionadded:: 2.1.0
:returns: A binary string containing the OpenTelemetry Span identifier
- .. method:: DNSQuestion:getTrailingData() -> string
+ .. method:: getTrailingData() -> string
.. versionadded:: 1.4.0
:returns: The trailing data as a null-safe string
- .. method:: DNSQuestion:changeName(newName) -> bool
+ .. method:: changeName(newName) -> bool
.. versionadded:: 1.8.0
:param DNSName newName: The new qname to use
- .. method:: DNSQuestion:sendTrap(reason)
+ .. method:: sendTrap(reason)
Send an SNMP trap.
:param string reason: An optional string describing the reason why this trap was sent
- .. method:: DNSQuestion:setContent(data)
+ .. method:: setContent(data)
.. versionadded:: 1.8.0
:param string data: The raw DNS payload
- .. method:: DNSQuestion:setEDNSOption(code, data)
+ .. method:: setEDNSOption(code, data)
.. versionadded:: 1.8.0
:param int code: The EDNS option code
:param string data: The EDNS option raw data
- .. method:: DNSQuestion:setExtendedDNSError(infoCode [, extraText [, clearExistingEntries]])
+ .. method:: setExtendedDNSError(infoCode [, extraText [, clearExistingEntries]])
.. versionadded:: 1.9.0
:param string extraText: The optional EDNS Extended DNS Error extra text
:param bool clearExistingEntries: Whether to clear existing EDNS Extended DNS Error codes, default true
- .. method:: DNSQuestion:setHTTPResponse(status, body, contentType="")
+ .. method:: setHTTPResponse(status, body, contentType="")
.. versionadded:: 1.4.0
:param string body: The body of the HTTP response, or a URL if the status code is a redirect (3xx)
:param string contentType: The HTTP Content-Type header to return for a 200 response, ignored otherwise. Default is ``application/dns-message``.
- .. method:: DNSQuestion:setMetaKey(key, values)
+ .. method:: setMetaKey(key, values)
.. versionadded:: 2.0.0
:param string key: The key
:param list values: A list containing strings, integers, or a mix of integers and strings
- .. method:: DNSQuestion:setNegativeAndAdditionalSOA(nxd, zone, ttl, mname, rname, serial, refresh, retry, expire, minimum)
+ .. method:: setNegativeAndAdditionalSOA(nxd, zone, ttl, mname, rname, serial, refresh, retry, expire, minimum)
.. versionadded:: 1.5.0
:param int expire: The value of the expire field in the SOA record
:param int minimum: The value of the minimum field in the SOA record
- .. method:: DNSQuestion:setProxyProtocolValues(values)
+ .. method:: setProxyProtocolValues(values)
.. versionadded:: 1.5.0
:param table values: A table of types and values to send, for example: ``{ [0x00] = "foo", [0x42] = "bar" }``. Note that the type must be an integer. Try to avoid these values: 0x01 - 0x05, 0x20 - 0x25, 0x30 as those are predefined in https://www.haproxy.org/download/2.3/doc/proxy-protocol.txt (search for `PP2_TYPE_ALPN`)
- .. method:: DNSQuestion:setRestartable()
+ .. method:: setRestartable()
.. versionadded:: 1.8.0
Under the hood, this tells dnsdist to keep a copy of the initial query around so that we can send it a second time if needed. Copying the initial DNS payload has a small memory and CPU cost and thus is not done by default.
See also :func:`DNSResponse:restart`.
- .. method:: DNSQuestion:setTag(key, value)
+ .. method:: setTag(key, value)
.. versionchanged:: 1.7.0
Prior to 1.7.0 calling :func:`DNSQuestion:setTag` would not overwrite an existing tag value if already set.
:param string key: The tag's key
:param string value: The tag's value
- .. method:: DNSQuestion:setTagArray(tags)
+ .. method:: setTagArray(tags)
.. versionchanged:: 1.7.0
Prior to 1.7.0 calling :func:`DNSQuestion:setTagArray` would not overwrite existing tag values if already set.
:param table tags: A table of tags, using strings as keys and values
- .. method:: DNSQuestion:setTrailingData(tail) -> bool
+ .. method:: setTrailingData(tail) -> bool
.. versionadded:: 1.4.0
:param string tail: The new data
:returns: true if the operation succeeded, false otherwise
- .. method:: DNSQuestion:spoof(ip|ips|raw|raws [, typeForAny])
+ .. method:: spoof(ip|ips|raw|raws [, typeForAny])
.. versionadded:: 1.6.0
:param table raws: The raw strings to be spoofed, e.g. `{ "\\192\\000\\002\\001", "\\192\\000\\002\\002" }`.
:param int typeForAny: The type to use for raw responses when the requested type is ``ANY``, as using ``ANY`` for the type of the response record would not make sense.
- .. method:: DNSQuestion:suspend(asyncID, queryID, timeoutMS) -> bool
+ .. method:: suspend(asyncID, queryID, timeoutMS) -> bool
.. versionadded:: 1.8.0
If the value is really needed while the response is being processed, it is possible to set a tag while the query is processed, as tags will be passed to the response object.
It also has additional methods:
- .. method:: DNSResponse:getSelectedBackend() -> Server
+ .. method:: getSelectedBackend() -> Server
.. versionadded:: 1.9.0
Get the selected backend :class:`Server` or nil
- .. method:: DNSResponse:getStaleCacheHit() -> bool
+ .. method:: getStaleCacheHit() -> bool
.. versionadded:: 2.0.0
Get the indicator of whether the cache lookup hit a stale entry.
- .. method:: DNSResponse:getRestartCount() -> int
+ .. method:: getRestartCount() -> int
.. versionadded:: 2.0.0
Get the current restart count, useful when the number of restart attempts is to be checked.
- .. method:: DNSResponse:editTTLs(func)
+ .. method:: editTTLs(func)
The function ``func`` is invoked for every entry in the answer, authority and additional section.
:param string func: The function to call to edit TTLs.
- .. method:: DNSResponse:changeName(initialName) -> bool
+ .. method:: changeName(initialName) -> bool
.. versionadded:: 1.8.0
:param DNSName initialName: The initial qname
- .. method:: DNSResponse:restart()
+ .. method:: restart()
.. versionadded:: 1.8.0
This object holds a representation of a DNS packet's header.
- .. method:: DNSHeader:getAA() -> bool
+ .. method:: getAA() -> bool
Get authoritative answer flag.
- .. method:: DNSHeader:getAD() -> bool
+ .. method:: getAD() -> bool
Get authentic data flag.
- .. method:: DNSHeader:getCD() -> bool
+ .. method:: getCD() -> bool
Get checking disabled flag.
- .. method:: DNSHeader:getID() -> int
+ .. method:: getID() -> int
.. versionadded:: 1.8.0
Get the ID.
- .. method:: DNSHeader:getRA() -> bool
+ .. method:: getRA() -> bool
Get recursion available flag.
- .. method:: DNSHeader:getRD() -> bool
+ .. method:: getRD() -> bool
Get recursion desired flag.
- .. method:: DNSHeader:getTC() -> bool
+ .. method:: getTC() -> bool
.. versionadded:: 1.8.1
Get the TC flag.
- .. method:: DNSHeader:setAA(aa)
+ .. method:: setAA(aa)
Set authoritative answer flag.
:param bool aa: State of the AA flag
- .. method:: DNSHeader:setAD(ad)
+ .. method:: setAD(ad)
Set authentic data flag.
:param bool ad: State of the AD flag
- .. method:: DNSHeader:setCD(cd)
+ .. method:: setCD(cd)
Set checking disabled flag.
:param bool cd: State of the CD flag
- .. method:: DNSHeader:setQR(qr)
+ .. method:: setQR(qr)
Set Query/Response flag.
Setting QR to true means "This is an answer packet".
:param bool qr: State of the QR flag
- .. method:: DNSHeader:setRA(ra)
+ .. method:: setRA(ra)
Set recursion available flag.
:param bool ra: State of the RA flag
- .. method:: DNSHeader:setRD(rd)
+ .. method:: setRD(rd)
Set recursion desired flag.
:param bool rd: State of the RD flag
- .. method:: DNSHeader:setTC(tc)
+ .. method:: setTC(tc)
Set truncation flag (TC).
An object that represents the values of a single EDNS option received in a query.
- .. method:: EDNSOptionView:count()
+ .. method:: count()
The number of values for this EDNS option.
- .. method:: EDNSOptionView:getValues()
+ .. method:: getValues()
Return a table of NULL-safe strings values for this EDNS option.
This object holds a representation of a DNS query or response that has been suspended.
- .. method:: AsynchronousObject:drop() -> bool
+ .. method:: drop() -> bool
Drop that object immediately, without resuming it.
Returns true on success, false on failure.
- .. method:: AsynchronousObject:getDQ() -> DNSQuestion
+ .. method:: getDQ() -> DNSQuestion
Return a DNSQuestion object for the suspended object.
- .. method:: AsynchronousObject:getDR() -> DNSResponse
+ .. method:: getDR() -> DNSResponse
Return a DNSResponse object for the suspended object.
- .. method:: AsynchronousObject:resume() -> bool
+ .. method:: resume() -> bool
Resume the processing of the suspended object.
For a question, it means first checking whether it was turned into a response,
Note that the AsynchronousObject object should NOT be accessed after successfully calling this method.
Returns true on success, false on failure.
- .. method:: AsynchronousObject:setRCode(rcode, clearRecords) -> bool
+ .. method:: setRCode(rcode, clearRecords) -> bool
Set the response code in the DNS header of the current object to the supplied value,
optionally removing all records from the existing payload, if any.
Represents an eBPF filter
- .. method:: BPFFilter:attachToAllBinds()
+ .. method:: attachToAllBinds()
Attach this filter to every bind already defined.
This is the run-time equivalent of :func:`setDefaultBPFFilter`.
This method can be used at run-time only.
- .. method:: BPFFilter:block(address)
+ .. method:: block(address)
Block this address
:param ComboAddress address: The address to block
- .. method:: BPFFilter:addRangeRule(Netmask , action [, force=false])
+ .. method:: addRangeRule(Netmask , action [, force=false])
.. versionadded:: 1.8.0
:param int action: set ``action`` to ``0`` to allow a range, set ``action`` to ``1`` to block a range, set ``action`` to ``2`` to truncate a range.
:param bool force: When ``force`` is set to true, DNSDist always accepts adding a new item to BPF maps, even if the item to be added may already be included in the larger network range.
- .. method:: BPFFilter:blockQName(name [, qtype=65535])
+ .. method:: blockQName(name [, qtype=65535])
.. versionchanged:: 2.0.0
Before 2.0.0 the value used to block queries for all types was 255. It also used to be the default value. This was changed because it prevented blocking only queries for the ``ANY`` (255) qtype.
:param DNSName name: The name to block
:param int qtype: QType to block
- .. method:: BPFFilter:getStats()
+ .. method:: getStats()
Print the block tables.
- .. method:: BPFFilter:unblock(address)
+ .. method:: unblock(address)
Unblock this address.
:param ComboAddress address: The address to unblock
- .. method:: BPFFilter:rmRangeRule(Netmask)
+ .. method:: rmRangeRule(Netmask)
.. versionadded:: 1.8.0
:param Netmask string: The rule you want to remove
- .. method:: BPFFilter:lsRangeRule()
+ .. method:: lsRangeRule()
.. versionadded:: 1.8.0
List all range rule.
- .. method:: BPFFilter:unblockQName(name [, qtype=65535])
+ .. method:: unblockQName(name [, qtype=65535])
.. versionchanged:: 2.0.0
Before 2.0.0 the value used to block queries for all types was 255. It also used to be the default value. This was changed because it prevented blocking only queries for the ``ANY`` (255) qtype.
Represents a dynamic eBPF filter, allowing the use of ephemeral rules to an existing eBPF filter. Note that since 1.6.0 the default BPF filter set via :func:`setDefaultBPFFilter` will automatically be used by a :ref:`DynBlockRulesGroup`, becoming the preferred way of dealing with ephemeral rules.
- .. method:: DynBPFFilter:purgeExpired()
+ .. method:: purgeExpired()
Remove the expired ephemeral rules associated with this filter.
- .. method:: DynBPFFilter:excludeRange(netmasks)
+ .. method:: excludeRange(netmasks)
Exclude this range, or list of ranges, meaning that no dynamic block will ever be inserted for clients in that range. Default to empty, meaning rules are applied to all ranges. When used in combination with :meth:`DynBPFFilter:includeRange`, the more specific entry wins.
:param str or list of str netmasks: A netmask, or list of netmasks, as strings, like for example "192.0.2.1/24"
- .. method:: DynBPFFilter:includeRange(netmasks)
+ .. method:: includeRange(netmasks)
Include this range, or list of ranges, meaning that rules will be applied to this range. When used in combination with :meth:`DynBPFFilter:excludeRange`, the more specific entry wins.
Represents a Key Value Store
- .. method:: KeyValueStore:lookup(key [, wireFormat])
+ .. method:: lookup(key [, wireFormat])
Does a lookup into the corresponding key value store, and return the result as a string.
The key can be a :class:`ComboAddress` obtained via the :func:`newCA`, a :class:`DNSName` obtained via the :func:`newDNSName` function, or a raw string.
:param ComboAddress, DNSName or string key: The key to look up
:param bool wireFormat: If the key is DNSName, whether to use to do the lookup in wire format (default) or in plain text
- .. method:: KeyValueStore:lookupSuffix(key [, minLabels [, wireFormat]])
+ .. method:: lookupSuffix(key [, minLabels [, wireFormat]])
Does a suffix-based lookup into the corresponding key value store, and return the result as a string.
The key should be a :class:`DNSName` object obtained via the :func:`newDNSName` function, and several lookups will be done, removing one label from the name at a time until a match has been found or there is no label left.
:param int minLabels: The minimum number of labels to do a lookup for. Default is 0 which means unlimited
:param bool wireFormat: Whether to do the lookup in wire format (default) or in plain text
- .. method:: KeyValueStore:reload()
+ .. method:: reload()
Reload the database if this is supported by the underlying store. As of 1.4.0, only CDB stores can be reloaded, and this method is a no-op for LMDB stores.
Represents a netmask.
- .. method:: Netmask:getBits() -> int
+ .. method:: getBits() -> int
Return the number of bits of this netmask, for example ``24`` for ``192.0.2.0/24``.
- .. method:: Netmask:getMaskedNetwork() -> ComboAddress
+ .. method:: getMaskedNetwork() -> ComboAddress
Return a :class:`ComboAddress` object representing the base network of this netmask object after masking any additional bits if necessary (for example ``192.0.2.0`` if the netmask was constructed with ``newNetmask('192.0.2.1/24')``).
- .. method:: Netmask:empty() -> bool
+ .. method:: empty() -> bool
Return true if the netmask is empty, meaning that the netmask has not been set to a proper value.
- .. method:: Netmask:isIPv4() -> bool
+ .. method:: isIPv4() -> bool
Return true if the netmask is an IPv4 one.
- .. method:: Netmask:isIPv6() -> bool
+ .. method:: isIPv6() -> bool
Return true if the netmask is an IPv6 one.
- .. method:: Netmask:getNetwork() -> ComboAddress
+ .. method:: getNetwork() -> ComboAddress
Return a :class:`ComboAddress` object representing the base network of this netmask object.
- .. method:: Netmask:match(str) -> bool
+ .. method:: match(str) -> bool
Return true if the address passed in the ``str`` parameter belongs to this netmask.
:param string str: A network address, like ``192.0.2.0``.
- .. method:: Netmask:toString() -> string
+ .. method:: toString() -> string
Return a string representation of the netmask, for example ``192.0.2.0/24``.
This object represents a single protobuf message as emitted by :program:`dnsdist`.
- .. method:: DNSDistProtoBufMessage:addResponseRR(name, type, class, ttl, blob)
+ .. method:: addResponseRR(name, type, class, ttl, blob)
Add a response RR to the protobuf message.
:param int ttl: The RR TTL.
:param string blob: The RR binary content.
- .. method:: DNSDistProtoBufMessage:setBytes(bytes)
+ .. method:: setBytes(bytes)
Set the size of the query
:param int bytes: Number of bytes in the query.
- .. method:: DNSDistProtoBufMessage:setEDNSSubnet(netmask)
+ .. method:: setEDNSSubnet(netmask)
Set the EDNS Subnet to ``netmask``.
:param string netmask: The netmask to set to.
- .. method:: DNSDistProtoBufMessage:setQueryTime(sec, usec)
+ .. method:: setQueryTime(sec, usec)
In a response message, set the time at which the query has been received.
:param int sec: Unix timestamp when the query was received.
:param int usec: The microsecond the query was received.
- .. method:: DNSDistProtoBufMessage:setQuestion(name, qtype, qclass)
+ .. method:: setQuestion(name, qtype, qclass)
Set the question in the protobuf message.
:param int qtype: The qtype of the question
:param int qclass: The qclass of the question
- .. method:: DNSDistProtoBufMessage:setProtobufResponseType(sec, usec)
+ .. method:: setProtobufResponseType(sec, usec)
Change the protobuf response type from a query to a response, and optionally set the query time.
:param int sec: Optional query time in seconds.
:param int usec: Optional query time in additional micro-seconds.
- .. method:: DNSDistProtoBufMessage:setRequestor(address [, port])
+ .. method:: setRequestor(address [, port])
.. versionchanged:: 1.5.0
``port`` optional parameter added.
:param ComboAddress address: The address to set to
:param int port: The requestor source port
- .. method:: DNSDistProtoBufMessage:setRequestorFromString(address [, port])
+ .. method:: setRequestorFromString(address [, port])
.. versionchanged:: 1.5.0
``port`` optional parameter added.
:param string address: The address to set to
:param int port: The requestor source port
- .. method:: DNSDistProtoBufMessage:setResponder(address [, port])
+ .. method:: setResponder(address [, port])
.. versionchanged:: 1.5.0
``port`` optional parameter added.
:param ComboAddress address: The address to set to
:param int port: The responder port
- .. method:: DNSDistProtoBufMessage:setResponderFromString(address [, port])
+ .. method:: setResponderFromString(address [, port])
.. versionchanged:: 1.5.0
``port`` optional parameter added.
:param string address: The address to set to
:param int port: The responder port
- .. method:: DNSDistProtoBufMessage:setResponseCode(rcode)
+ .. method:: setResponseCode(rcode)
Set the response code of the query.
:param int rcode: The response code of the answer
- .. method:: DNSDistProtoBufMessage:setServerIdentity(id)
+ .. method:: setServerIdentity(id)
Set the server identify field.
:param string id: The server ID
- .. method:: DNSDistProtoBufMessage:setTag(value)
+ .. method:: setTag(value)
Add a tag to the list of tags.
:param string value: The tag value
- .. method:: DNSDistProtoBufMessage:setTagArray(valueList)
+ .. method:: setTagArray(valueList)
Add a list of tags.
:param table tags: A list of tags as strings
- .. method:: DNSDistProtoBufMessage:setTime(sec, usec)
+ .. method:: setTime(sec, usec)
Set the time at which the query or response has been received.
:param int sec: Unix timestamp when the query was received.
:param int usec: The microsecond the query was received.
- .. method:: DNSDistProtoBufMessage:toDebugString() -> string
+ .. method:: toDebugString() -> string
Return a string containing the content of the message
Represents a rule composed of a :class:`DNSRule` selector, to select the queries this applies to,
and a :class:`DNSAction` action to apply when the selector matches.
- .. method:: DNSDistRuleAction:getAction()
+ .. method:: getAction()
Return the :class:`DNSAction` action of this rule.
- .. method:: DNSDistRuleAction:getSelector()
+ .. method:: getSelector()
Return the :class:`DNSRule` selector of this rule.
Represents a rule composed of a :class:`DNSRule` selector, to select the responses this applies to,
and a :class:`DNSResponseAction` action to apply when the selector matches.
- .. method:: DNSDistResponseRuleAction:getAction()
+ .. method:: getAction()
Return the :class:`DNSResponseAction` action of this rule.
- .. method:: DNSDistResponseRuleAction:getSelector()
+ .. method:: getSelector()
Return the :class:`DNSRule` selector of this rule.
.. versionadded:: 1.9.0
- .. method:: DNSRule:getMatches() -> int
+ .. method:: getMatches() -> int
Return the number of times this selector matched a query or a response. Note that if the same selector is reused for different ``DNSDistRuleAction``
objects, the counter will be common to all these objects.
Represent a HTTP query, whose attributes are read-only.
- .. attribute:: WebRequest.body
+ .. attribute:: body
The body of this query, as a string.
- .. attribute:: WebRequest.getvars
+ .. attribute:: getvars
The GET parameters of this query, as a table whose keys and values are strings.
- .. attribute:: WebRequest.headers
+ .. attribute:: headers
The HTTP headers of this query, as a table whose keys and values are strings.
- .. attribute:: WebRequest.method
+ .. attribute:: method
The method of this query, as a string.
- .. attribute:: WebRequest.path
+ .. attribute:: path
The path of this query, as a string.
- .. attribute:: WebRequest.postvars
+ .. attribute:: postvars
The POST parameters of this query, as a table whose keys and values are strings.
- .. attribute:: WebRequest.version
+ .. attribute:: version
The HTTP version of this query, as an integer.
Represent a HTTP response.
- .. attribute:: WebResponse.body
+ .. attribute:: body
The body of this response, as a string.
- .. attribute:: WebResponse.headers
+ .. attribute:: headers
The HTTP headers of this response, as a table whose keys and values are strings.
- .. attribute:: WebResponse.status
+ .. attribute:: status
The HTTP status code of this response, as an integer.
Represents a ``XSK`` / ``AF_XDP`` socket tied to a specific network interface and queue. This object can be created via :func:`newXSK` and passed to :func:`addLocal` to use XSK for ``UDP`` packets between clients and dnsdist. It can also be passed to :func:`newServer` to use XSK for ``UDP`` packets between dnsdist a backend.
- .. method:: XskSocket:getMetrics() -> str
+ .. method:: getMetrics() -> str
Returns a string containing ``XSK`` / ``AF_XDP`` metrics for this object, as reported by the Linux kernel.
projects / thirdparty / pdns.git / commitdiff
