DNS Query Support

The dns.query module is for sending messages to DNS servers, and processing their responses. If you want “stub resolver” behavior, then you should use the higher level dns.resolver module; see Stub Resolver.

For UDP and TCP, the module provides a single “do everything” query function, and also provides the send and receive halves of this function individually for situations where more sophisticated I/O handling is being used by the application.

UDP

dns.query.udp(q: Message, where: str, timeout: float | None = None, port: int = 53, source: str | None = None, source_port: int = 0, ignore_unexpected: bool = False, one_rr_per_rrset: bool = False, ignore_trailing: bool = False, raise_on_truncation: bool = False, sock: Any | None = None, ignore_errors: bool = False) → Message[source]

Return the response obtained after sending a query via UDP.

Parameters:

  • q (dns.message.Message) – The query to send.

  • where (str) – IPv4 or IPv6 address of the nameserver.

  • timeout (float or None) – Seconds to wait before timing out. None means wait forever.

  • port (int) – The port to send the message to. Default is 53.

  • source (str or None) – Source IPv4 or IPv6 address. Default is the wildcard address.

  • source_port (int) – The port from which to send the message. Default is 0.

  • ignore_unexpected (bool) – If True, ignore responses from unexpected sources.

  • one_rr_per_rrset (bool) – If True, put each RR into its own RRset.

  • ignore_trailing (bool) – If True, ignore trailing junk at end of the received message.

  • raise_on_truncation (bool) – If True, raise an exception if the TC bit is set.

  • sock (socket.socket or None) – The socket to use. If None (the default), a socket is created. If provided, must be a nonblocking datagram socket; source and source_port are ignored.

  • ignore_errors (bool) – If True, ignore format errors or response mismatches and keep listening for a valid response.

Return type:

dns.message.Message

dns.query.udp_with_fallback(q: Message, where: str, timeout: float | None = None, port: int = 53, source: str | None = None, source_port: int = 0, ignore_unexpected: bool = False, one_rr_per_rrset: bool = False, ignore_trailing: bool = False, udp_sock: Any | None = None, tcp_sock: Any | None = None, ignore_errors: bool = False) → tuple[Message, bool][source]

Return the response to the query, trying UDP first and falling back to TCP if UDP results in a truncated response.

Parameters:

  • q (dns.message.Message) – The query to send.

  • where (str) – IPv4 or IPv6 address of the nameserver.

  • timeout (float or None) – Seconds to wait before timing out. None means wait forever.

  • port (int) – The port to send the message to. Default is 53.

  • source (str or None) – Source IPv4 or IPv6 address. Default is the wildcard address.

  • source_port (int) – The port from which to send the message. Default is 0.

  • ignore_unexpected (bool) – If True, ignore responses from unexpected sources.

  • one_rr_per_rrset (bool) – If True, put each RR into its own RRset.

  • ignore_trailing (bool) – If True, ignore trailing junk at end of the received message.

  • udp_sock (socket.socket or None) – The socket to use for the UDP query. If None (the default), a socket is created. If provided, must be a nonblocking datagram socket; source and source_port are ignored.

  • tcp_sock (socket.socket or None) – The connected socket to use for the TCP query. If None (the default), a socket is created. If provided, must be a nonblocking connected stream socket; where, source and source_port are ignored.

  • ignore_errors (bool) – If True, ignore UDP format errors or response mismatches and keep listening for a valid response.

Returns:

A (message, used_tcp) tuple; used_tcp is True if and only if TCP was used.

Return type:

tuple[dns.message.Message, bool]

dns.query.send_udp(sock: Any, what: Message | bytes, destination: Any, expiration: float | None = None) → tuple[int, float][source]

Send a DNS message to the specified UDP socket.

Parameters:

  • sock (socket) – The socket to use.

  • what (bytes or dns.message.Message) – The message to send.

  • destination – A destination tuple appropriate for the address family of the socket.

  • expiration (float or None) – The absolute time at which to raise a timeout exception. None means no timeout.

Returns:

A (bytes_sent, sent_time) tuple.

Return type:

tuple[int, float]

dns.query.receive_udp(sock: Any, destination: Any | None = None, expiration: float | None = None, ignore_unexpected: bool = False, one_rr_per_rrset: bool = False, keyring: dict[Name, Key] | None = None, request_mac: bytes | None = b'', ignore_trailing: bool = False, raise_on_truncation: bool = False, ignore_errors: bool = False, query: Message | None = None) → Any[source]

Read a DNS message from a UDP socket.

Raises if the message is malformed, if network errors occur, of if there is a timeout.

Parameters:

  • sock (socket) – The socket to read from.

  • destination – Destination tuple indicating where the message is expected to arrive from (where the associated query was sent). None means accept from any source.

  • expiration (float or None) – The absolute time at which to raise a timeout exception. None means no timeout.

  • ignore_unexpected (bool) – If True, ignore responses from unexpected sources.

  • one_rr_per_rrset (bool) – If True, put each RR into its own RRset.

  • keyring (dict or None) – The keyring to use for TSIG.

  • request_mac (bytes or None) – The MAC of the request (for TSIG).

  • ignore_trailing (bool) – If True, ignore trailing junk at end of the received message.

  • raise_on_truncation (bool) – If True, raise an exception if the TC bit is set.

  • ignore_errors (bool) – If True, ignore format errors or response mismatches and keep listening for a valid response.

  • query (dns.message.Message or None) – If not None and ignore_errors is True, verify the received message is a response to this query.

Returns:

If destination is not None, a (message, received_time) tuple; otherwise a (message, received_time, from_address) tuple.

Return type:

tuple

TCP

dns.query.tcp(q: Message, where: str, timeout: float | None = None, port: int = 53, source: str | None = None, source_port: int = 0, one_rr_per_rrset: bool = False, ignore_trailing: bool = False, sock: Any | None = None) → Message[source]

Return the response obtained after sending a query via TCP.

Parameters:

  • q (dns.message.Message) – The query to send.

  • where (str) – IPv4 or IPv6 address of the nameserver.

  • timeout (float or None) – Seconds to wait before timing out. None means wait forever.

  • port (int) – The port to send the message to. Default is 53.

  • source (str or None) – Source IPv4 or IPv6 address. Default is the wildcard address.

  • source_port (int) – The port from which to send the message. Default is 0.

  • one_rr_per_rrset (bool) – If True, put each RR into its own RRset.

  • ignore_trailing (bool) – If True, ignore trailing junk at end of the received message.

  • sock (socket.socket or None) – The connected socket to use. If None (the default), a socket is created. If provided, must be a nonblocking connected stream socket; where, port, source and source_port are ignored.

Return type:

dns.message.Message

dns.query.send_tcp(sock: Any, what: Message | bytes, expiration: float | None = None) → tuple[int, float][source]

Send a DNS message to the specified TCP socket.

Parameters:

  • sock (socket) – The socket to use.

  • what (bytes or dns.message.Message) – The message to send.

  • expiration (float or None) – The absolute time at which to raise a timeout exception. None means no timeout.

Returns:

A (bytes_sent, sent_time) tuple.

Return type:

tuple[int, float]

dns.query.receive_tcp(sock: Any, expiration: float | None = None, one_rr_per_rrset: bool = False, keyring: dict[Name, Key] | None = None, request_mac: bytes | None = b'', ignore_trailing: bool = False) → tuple[Message, float][source]

Read a DNS message from a TCP socket.

Parameters:

  • sock (socket) – The socket to read from.

  • expiration (float or None) – The absolute time at which to raise a timeout exception. None means no timeout.

  • one_rr_per_rrset (bool) – If True, put each RR into its own RRset.

  • keyring (dict or None) – The keyring to use for TSIG.

  • request_mac (bytes or None) – The MAC of the request (for TSIG).

  • ignore_trailing (bool) – If True, ignore trailing junk at end of the received message.

Returns:

A (message, received_time) tuple.

Return type:

tuple[dns.message.Message, float]

TLS

dns.query.tls(q: Message, where: str, timeout: float | None = None, port: int = 853, source: str | None = None, source_port: int = 0, one_rr_per_rrset: bool = False, ignore_trailing: bool = False, sock: SSLSocket | None = None, ssl_context: SSLContext | None = None, server_hostname: str | None = None, verify: bool | str = True) → Message[source]

Return the response obtained after sending a query via TLS.

Parameters:

  • q (dns.message.Message) – The query to send.

  • where (str) – IPv4 or IPv6 address of the nameserver.

  • timeout (float or None) – Seconds to wait before timing out. None means wait forever.

  • port (int) – The port to send the message to. Default is 853.

  • source (str or None) – Source IPv4 or IPv6 address. Default is the wildcard address.

  • source_port (int) – The port from which to send the message. Default is 0.

  • one_rr_per_rrset (bool) – If True, put each RR into its own RRset.

  • ignore_trailing (bool) – If True, ignore trailing junk at end of the received message.

  • sock (ssl.SSLSocket or None) – The SSL socket to use. If None (the default), a socket is created. If provided, must be a nonblocking connected SSL stream socket; where, port, source, source_port, and ssl_context are ignored.

  • ssl_context (ssl.SSLContext or None) – The SSL context to use when establishing the TLS connection. If None (the default), one is created with the default configuration.

  • server_hostname (str or None) – The server’s hostname, or None. If None and an SSL context is created, hostname checking is disabled.

  • verify (bool or str) – If True, verify the TLS certificate using default CA roots; if False, disable verification; if a str, path to a certificate file or directory.

Return type:

dns.message.Message

HTTPS

dns.query.https(q: Message, where: str, timeout: float | None = None, port: int = 443, source: str | None = None, source_port: int = 0, one_rr_per_rrset: bool = False, ignore_trailing: bool = False, session: Any | None = None, path: str = '/dns-query', post: bool = True, bootstrap_address: str | None = None, verify: bool | str | SSLContext = True, resolver: Resolver | None = None, family: int = AddressFamily.AF_UNSPEC, http_version: HTTPVersion = HTTPVersion.DEFAULT) → Message[source]

Return the response obtained after sending a query via DNS-over-HTTPS.

Parameters:

  • q (dns.message.Message) – The query to send.

  • where (str) – The nameserver IP address or full URL. If an IP address is given, the URL is constructed as https://<IP-address>:<port>/<path>.

  • timeout (float or None) – Seconds to wait before timing out. None means wait forever.

  • port (int) – The port to send the query to. Default is 443.

  • source (str or None) – Source IPv4 or IPv6 address. Default is the wildcard address.

  • source_port (int) – The port from which to send the message. Default is 0.

  • one_rr_per_rrset (bool) – If True, put each RR into its own RRset.

  • ignore_trailing (bool) – If True, ignore trailing junk at end of the received message.

  • session (httpx2.Client or None) – If provided, the client session to use to send the queries.

  • path (str) – If where is an IP address, path is used to construct the query URL.

  • post (bool) – If True (the default), use the POST method.

  • bootstrap_address (str or None) – The IP address to use to bypass resolution.

  • verify (bool or str) – If True, verify the TLS certificate using default CA roots; if False, disable verification; if a str, path to a certificate file or directory.

  • resolver (dns.resolver.Resolver or None) – Resolver to use for hostname resolution in URLs. If None, a new resolver with default configuration is used (not the default resolver, to avoid a DoH chicken-and-egg problem). Only effective when using httpx2.

  • family (int) – Address family. socket.AF_UNSPEC (the default) retrieves both A and AAAA records.

  • http_version (dns.query.HTTPVersion) – Which HTTP version to use.

Return type:

dns.message.Message

Zone Transfers

As of dnspython 2.1, dns.query.xfr() is deprecated. Please use dns.query.inbound_xfr() instead.

class dns.query.HTTPVersion(value)[source]

Which version of HTTP should be used?

DEFAULT will select the first version from the list [2, 1.1, 3] that is available.

class dns.query.UDPMode(value)[source]

How should UDP be used in an IXFR from inbound_xfr()?

NEVER means “never use UDP; always use TCP” TRY_FIRST means “try to use UDP but fall back to TCP if needed” ONLY means “raise dns.xfr.UseTCP if trying UDP does not succeed”

dns.query.inbound_xfr(where: str, txn_manager: TransactionManager, query: Message | None = None, port: int = 53, timeout: float | None = None, lifetime: float | None = None, source: str | None = None, source_port: int = 0, udp_mode: UDPMode = UDPMode.NEVER) → None[source]

Conduct an inbound transfer and apply it via a transaction from the txn_manager.

Parameters:

  • where (str) – IPv4 or IPv6 address of the nameserver.

  • txn_manager (dns.transaction.TransactionManager) – The transaction manager for this transfer (typically a dns.zone.Zone).

  • query – The query to send. If not supplied, a default query is constructed from txn_manager.

  • port (int) – The port to send the message to. Default is 53.

  • timeout (float or None) – Seconds to wait for each response message. None means wait forever.

  • lifetime (float or None) – Total seconds to spend on the transfer. None means no limit.

  • source (str or None) – Source IPv4 or IPv6 address. Default is the wildcard address.

  • source_port (int) – The port from which to send the message. Default is 0.

  • udp_mode (dns.query.UDPMode) – How to use UDP for IXFRs. Default is dns.query.UDPMode.NEVER (TCP only). TRY_FIRST tries UDP with TCP fallback; ONLY raises dns.xfr.UseTCP if UDP does not succeed.

dns.query.xfr(where: str, zone: Name | str, rdtype: RdataType | str = RdataType.AXFR, rdclass: RdataClass | str = RdataClass.IN, timeout: float | None = None, port: int = 53, keyring: dict[~dns.name.Name, ~dns.tsig.Key] | None=None, keyname: Name | str | None = None, relativize: bool = True, lifetime: float | None = None, source: str | None = None, source_port: int = 0, serial: int = 0, use_udp: bool = False, keyalgorithm: Name | str = <DNS name hmac-sha256.>) → Any[source]

Return a generator for the responses to a zone transfer.

Parameters:

  • where (str) – IPv4 or IPv6 address of the nameserver.

  • zone (dns.name.Name or str) – The name of the zone to transfer.

  • rdtype (dns.rdatatype.RdataType or str or int) – The type of zone transfer. Default is dns.rdatatype.AXFR; use dns.rdatatype.IXFR for incremental.

  • rdclass (dns.rdataclass.RdataClass or str or int) – The class of the zone transfer. Default is dns.rdataclass.IN.

  • timeout (float or None) – Seconds to wait for each response message. None means wait forever.

  • port (int) – The port to send the message to. Default is 53.

  • keyring (dict or None) – The keyring to use for TSIG.

  • keyname (dns.name.Name or str or None) – The name of the TSIG key to use.

  • relativize (bool) – If True, relativize all names to the zone origin. Must match the setting passed to dns.zone.from_xfr().

  • lifetime (float or None) – Total seconds to spend on the transfer. None means no limit.

  • source (str or None) – Source IPv4 or IPv6 address. Default is the wildcard address.

  • source_port (int) – The port from which to send the message. Default is 0.

  • serial (int) – SOA serial number to use as the IXFR base (only meaningful when rdtype is dns.rdatatype.IXFR).

  • use_udp (bool) – If True, use UDP (only meaningful for IXFR).

  • keyalgorithm (dns.name.Name or str) – The TSIG algorithm to use.

Returns:

A generator of dns.message.Message objects.