dns_exporter.config

dns_exporter.config contains all the configuration related code for dns_exporter.

The primary class is the Config object and the two RRValidator and RFValidator objects.

class dns_exporter.config.Config(name: str, collect_ttl: bool, collect_ttl_rr_value_length: int, edns: bool, edns_do: bool, edns_nsid: bool, edns_bufsize: int, edns_pad: int, family: str, protocol: str, query_class: str, query_type: str, proxy: urllib.parse.SplitResult | None, recursion_desired: bool, timeout: float, validate_answer_rrs: RRValidator, validate_authority_rrs: RRValidator, validate_additional_rrs: RRValidator, validate_response_flags: RFValidator, valid_rcodes: list[str], verify_certificate: bool, verify_certificate_path: str, ip: IPv4Address | IPv6Address | None = <factory>, server: urllib.parse.SplitResult | None = <factory>, query_name: str | None = <factory>)

dns_exporter.config.Config defines the primary config structure used in dns_exporter.

The defaults for each config key are defined in the dns_exporter.config.Config.create() method.

The dns_exporter.exporter.DNSExporter.modules dict consists of string keys and instances of this class as values.

collect_ttl: bool

Set this bool to True to enable collection of per-RR TTL metrics for the DNS query, False to not collect per-RR TTL metrics. Default is True

Type:

bool

collect_ttl_rr_value_length: int

Limits the length of the rr_value label when collecing per-RR TTL metrics. Default is 50

Type:

int

classmethod create(*, name: str, collect_ttl: bool = True, collect_ttl_rr_value_length: int = 50, edns: bool = True, edns_do: bool = False, edns_nsid: bool = True, edns_bufsize: int = 1232, edns_pad: int = 0, family: str = 'ipv6', protocol: str = 'udp', query_class: str = 'IN', query_type: str = 'A', recursion_desired: bool = True, proxy: urllib.parse.SplitResult | None = None, timeout: float = 5.0, validate_answer_rrs: RRValidator | None = None, validate_authority_rrs: RRValidator | None = None, validate_additional_rrs: RRValidator | None = None, validate_response_flags: RFValidator | None = None, valid_rcodes: list[str] | None = None, verify_certificate: bool = True, verify_certificate_path: str = '', ip: IPv4Address | IPv6Address | None = None, server: urllib.parse.SplitResult | None = None, query_name: str | None = None) → Config

Return an instance of the Config class with values from the provided parameters overriding the defaults.

edns: bool

Set this bool to True to enable EDNS0 for the DNS query, False to not use EDNS0. Default is True

Type:

bool

edns_bufsize: int

This int sets the EDNS0 bufsize for the DNS query. Default is 1232

Type:

int

edns_do: bool

Set this bool to True to set the EDNS0 DO flag for the DNS query. Default is False

Type:

bool

edns_nsid: bool

Set this bool to True to set the EDNS0 nsid option for the DNS query. Default is True

Type:

bool

edns_pad: int

This int sets the EDNS0 padding size for the DNS query. Default is 0

Type:

int

family: str

This string key must be set to either ipv6 or ipv4. It determines the address family used for the DNS query. Default is ipv6

Type:

str

ip: IPv4Address | IPv6Address | None

The IP to use instead of using IP or hostname from server. Default is None

Type:

IPv4Address | IPv6Address | None

json() → str

Return a json version of the config. Mostly used in unit tests.

name: str

The name of this config. It is mostly included in the class for convenience.

Type:

str

protocol: str

This key must be set to one of udp, tcp, udptcp, dot, doh, or doq. It determines the protocol used for the DNS query. Default is udp

Type:

str

proxy: urllib.parse.SplitResult | None

The proxy to use for this DNS query, for example socks5://127.0.0.1:5000. Supported proxy types are SOCKS4, SOCKS5, and HTTP. Leave empty to use no proxy. Default is no proxy.

Type:

str

query_class: str

The query class used for this DNS query, typically IN but can also be CHAOS. Default is IN

Type:

str

query_name: str | None

The name to ask for in the DNS query. Default is None

Type:

str | None

query_type: str

The query type used for this DNS query, like A or MX. Default is A

Type:

str

recursion_desired: bool

Set this bool to True to set the RD flag in the DNS query. Default is True

Type:

bool

server: urllib.parse.SplitResult | None

The DNS server to use in parsed form. Default is None

Type:

urllib.parse.SplitResult | None

timeout: float

This float determines how long the exporter will wait for a response before declaring the DNS query failed. Unit is seconds. Default is 5.0.

Type:

float

valid_rcodes: list[str]

A list of acceptable rcodes when validating the DNS response. Default is ["NOERROR"].

Type:

list[str]

validate_additional_rrs: RRValidator

This object contains the validation config for the additional section of the response. Default is an empty RRValidator()

Type:

RRValidator

validate_answer_rrs: RRValidator

This object contains the validation config for the answer section of the response. Default is an empty RRValidator()

Type:

RRValidator

validate_authority_rrs: RRValidator

This object contains the validation config for the authority section of the response. Default is an empty RRValidator()

Type:

RRValidator

validate_bools() → None

Validate bools.

validate_integers() → None

Validate integers.

validate_protocol() → None

Validate protocol.

validate_proxy() → None

Validate proxy.

validate_response_flags: RFValidator

This object contains the validation config for the response flags. Default is an empty RFValidator()

Type:

RFValidator

validate_valid_qtypes() → None

Validate query_type (make sure it is supported in dnspython).

validate_valid_rcodes() → None

Validate valid_rcodes.

verify_certificate: bool

Set this bool to True to verify the certificate of the DNS server, set it to False to disable certificate verification. When enabled the default system CA can be overridden with the verify_certificate_path setting. Certificate validation is ignored for unencrypted protocols. Default is True

Type:

bool

verify_certificate_path: str

Set this to the path of a CA dir or CA file to override the default system CA when verifying certificates of encrypted DNS servers. Leave empty to use the default system CA path. Default is an empty string.

Type:

bool

class dns_exporter.config.ConfigDict

A TypedDict to help hold config dicts before they become Config objects.

dns_exporter.config.ConfigDict behaves like a regular dict but works better with mypy because the individual keys has been annotated.

dns_exporter.config.ConfigDict has all the same keys and types as the real final dns_exporter.config.Config object does.

class dns_exporter.config.RFValidator(fail_if_any_present: list[str], fail_if_all_present: list[str], fail_if_any_absent: list[str], fail_if_all_absent: list[str])

dns_exporter.config.RFValidator defines the structure used in Config objects to validate response flags.

It is used in the validate_response_flags setting in the config.

Like the parent dns_exporter.config.Config class it consists of a bunch of attributes and the dns_exporter.config.RFValidator.create() method which returns an instance of this class.

classmethod create(fail_if_any_present: list[str] | None = None, fail_if_all_present: list[str] | None = None, fail_if_any_absent: list[str] | None = None, fail_if_all_absent: list[str] | None = None) → RFValidator

Return an instance of the RFValidator class with values from the provided parameters.

The values are used as-is.

fail_if_all_absent: list[str]

fail_if_all_present is a list of flags as strings, fail if all of them are absent from the response.

fail_if_all_present: list[str]

fail_if_all_present is a list of flags as strings, fail if all of them are present in the response.

fail_if_any_absent: list[str]

fail_if_any_absent is a list of flags as strings, fail if any of them are absent from the response.

fail_if_any_present: list[str]

fail_if_any_present is a list of flags as strings, fail if any of them are present in the response.

class dns_exporter.config.RRValidator(fail_if_matches_regexp: list[str], fail_if_all_match_regexp: list[str], fail_if_not_matches_regexp: list[str], fail_if_none_matches_regexp: list[str], fail_if_count_eq: int | None, fail_if_count_ne: int | None, fail_if_count_lt: int | None, fail_if_count_gt: int | None)

dns_exporter.config.RRValidator defines the structure used in Config objects to validate response RRs.

It is used in the validate_(answer|authority|additional)_rrs settings in the config.

Like the parent dns_exporter.config.Config class it consists of a bunch of attributes and the dns_exporter.config.RRValidator.create() method which returns an instance of this class.

Each Config object can have up to three (3) instances of this class, one for validating RRs in each section of the response:

• answer

• authority

• additional

classmethod create(fail_if_matches_regexp: list[str] | None = None, fail_if_all_match_regexp: list[str] | None = None, fail_if_not_matches_regexp: list[str] | None = None, fail_if_none_matches_regexp: list[str] | None = None, fail_if_count_eq: int | None = None, fail_if_count_ne: int | None = None, fail_if_count_lt: int | None = None, fail_if_count_gt: int | None = None) → RRValidator

Return an instance of the RRValidator class with values from the provided parameters.

The values are used as-is.

fail_if_all_match_regexp: list[str]

fail_if_all_match_regexp is a list of regular expressions, fail the query if all of them matches an RR.

fail_if_count_eq: int | None

fail_if_count_eq is an integer, fail the query if the number of RRs matches this number.

fail_if_count_gt: int | None

fail_if_count_gt is an integer, fail the query if the number of RRs is larger than this number.

fail_if_count_lt: int | None

fail_if_count_lt is an integer, fail the query if the number of RRs is smaller than this number.

fail_if_count_ne: int | None

fail_if_count_ne is an integer, fail the query if the number of RRs is not equal to this number.

fail_if_matches_regexp: list[str]

fail_if_matches_regexp is a list of regular expressions, fail the query if one of them matches an RR.

fail_if_none_matches_regexp: list[str]

fail_if_none_matches_regexp is a list of regular expressions, fail the query if all of them does not match an RR.

fail_if_not_matches_regexp: list[str]

fail_if_not_matches_regexp is a list of regular expressions, fail the query if one of them does not match an RR.