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

Return the response obtained after sending a query via UDP.

q, a dns.message.Message, the query to send

where, a str containing an IPv4 or IPv6 address, where to send the message.

timeout, a float or None, the number of seconds to wait before the query times out. If None, the default, wait forever.

port, an int, the port send the message to. The default is 53.

source, a str containing an IPv4 or IPv6 address, specifying the source address. The default is the wildcard address.

source_port, an int, the port from which to send the message. The default is 0.

ignore_unexpected, a bool. If True, ignore responses from unexpected sources.

one_rr_per_rrset, a bool. If True, put each RR into its own RRset.

ignore_trailing, a bool. If True, ignore trailing junk at end of the received message.

raise_on_truncation, a bool. If True, raise an exception if the TC bit is set.

sock, a socket.socket, or None, the socket to use for the query. If None, the default, a socket is created. Note that if a socket is provided, it must be a nonblocking datagram socket, and the source and source_port are ignored.

ignore_errors, a bool. If various format errors or response mismatches occur, ignore them and keep listening for a valid response. The default is False.

Returns a 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]

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

q, a dns.message.Message, the query to send

where, a str containing an IPv4 or IPv6 address, where to send the message.

timeout, a float or None, the number of seconds to wait before the query times out. If None, the default, wait forever.

port, an int, the port send the message to. The default is 53.

source, a str containing an IPv4 or IPv6 address, specifying the source address. The default is the wildcard address.

source_port, an int, the port from which to send the message. The default is 0.

ignore_unexpected, a bool. If True, ignore responses from unexpected sources.

one_rr_per_rrset, a bool. If True, put each RR into its own RRset.

ignore_trailing, a bool. If True, ignore trailing junk at end of the received message.

udp_sock, a socket.socket, or None, the socket to use for the UDP query. If None, the default, a socket is created. Note that if a socket is provided, it must be a nonblocking datagram socket, and the source and source_port are ignored for the UDP query.

tcp_sock, a socket.socket, or None, the connected socket to use for the TCP query. If None, the default, a socket is created. Note that if a socket is provided, it must be a nonblocking connected stream socket, and where, source and source_port are ignored for the TCP query.

ignore_errors, a bool. If various format errors or response mismatches occur while listening for UDP, ignore them and keep listening for a valid response. The default is False.

Returns a (dns.message.Message, tcp) tuple where tcp is True if and only if TCP was used.

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

Send a DNS message to the specified UDP socket.

sock, a socket.

what, a bytes or dns.message.Message, the message to send.

destination, a destination tuple appropriate for the address family of the socket, specifying where to send the query.

expiration, a float or None, the absolute time at which a timeout exception should be raised. If None, no timeout will occur.

Returns an (int, float) tuple of bytes sent and the sent time.

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

Read a DNS message from a UDP socket.

sock, a socket.

destination, a destination tuple appropriate for the address family of the socket, specifying where the message is expected to arrive from. When receiving a response, this would be where the associated query was sent.

expiration, a float or None, the absolute time at which a timeout exception should be raised. If None, no timeout will occur.

ignore_unexpected, a bool. If True, ignore responses from unexpected sources.

one_rr_per_rrset, a bool. If True, put each RR into its own RRset.

keyring, a dict, the keyring to use for TSIG.

request_mac, a bytes or None, the MAC of the request (for TSIG).

ignore_trailing, a bool. If True, ignore trailing junk at end of the received message.

raise_on_truncation, a bool. If True, raise an exception if the TC bit is set.

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

If destination is not None, returns a (dns.message.Message, float) tuple of the received message and the received time.

If destination is None, returns a (dns.message.Message, float, tuple) tuple of the received message, the received time, and the address where the message arrived from.

ignore_errors, a bool. If various format errors or response mismatches occur, ignore them and keep listening for a valid response. The default is False.

query, a dns.message.Message or None. If not None and ignore_errors is True, check that the received message is a response to this query, and if not keep listening for a valid response.

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

Return the response obtained after sending a query via TCP.

q, a dns.message.Message, the query to send

where, a str containing an IPv4 or IPv6 address, where to send the message.

timeout, a float or None, the number of seconds to wait before the query times out. If None, the default, wait forever.

port, an int, the port send the message to. The default is 53.

source, a str containing an IPv4 or IPv6 address, specifying the source address. The default is the wildcard address.

source_port, an int, the port from which to send the message. The default is 0.

one_rr_per_rrset, a bool. If True, put each RR into its own RRset.

ignore_trailing, a bool. If True, ignore trailing junk at end of the received message.

sock, a socket.socket, or None, the connected socket to use for the query. If None, the default, a socket is created. Note that if a socket is provided, it must be a nonblocking connected stream socket, and where, port, source and source_port are ignored.

Returns a dns.message.Message.

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

Send a DNS message to the specified TCP socket.

sock, a socket.

what, a bytes or dns.message.Message, the message to send.

expiration, a float or None, the absolute time at which a timeout exception should be raised. If None, no timeout will occur.

Returns an (int, float) tuple of bytes sent and the sent time.

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]

Read a DNS message from a TCP socket.

sock, a socket.

expiration, a float or None, the absolute time at which a timeout exception should be raised. If None, no timeout will occur.

one_rr_per_rrset, a bool. If True, put each RR into its own RRset.

keyring, a dict, the keyring to use for TSIG.

request_mac, a bytes or None, the MAC of the request (for TSIG).

ignore_trailing, a bool. If True, ignore trailing junk at end of the received message.

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

Returns a (dns.message.Message, float) tuple of the received message and the received time.

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

Return the response obtained after sending a query via TLS.

q, a dns.message.Message, the query to send

where, a str containing an IPv4 or IPv6 address, where to send the message.

timeout, a float or None, the number of seconds to wait before the query times out. If None, the default, wait forever.

port, an int, the port send the message to. The default is 853.

source, a str containing an IPv4 or IPv6 address, specifying the source address. The default is the wildcard address.

source_port, an int, the port from which to send the message. The default is 0.

one_rr_per_rrset, a bool. If True, put each RR into its own RRset.

ignore_trailing, a bool. If True, ignore trailing junk at end of the received message.

sock, an ssl.SSLSocket, or None, the socket to use for the query. If None, the default, a socket is created. Note that if a socket is provided, it must be a nonblocking connected SSL stream socket, and where, port, source, source_port, and ssl_context are ignored.

ssl_context, an ssl.SSLContext, the context to use when establishing a TLS connection. If None, the default, creates one with the default configuration.

server_hostname, a str containing the server’s hostname. The default is None, which means that no hostname is known, and if an SSL context is created, hostname checking will be disabled.

verify, a bool or str. If a True, then TLS certificate verification of the server is done using the default CA bundle; if False, then no verification is done; if a str then it specifies the path to a certificate file or directory which will be used for verification.

Returns a 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 = True, resolver: Resolver | None = None, family: int | None = AddressFamily.AF_UNSPEC) → Message

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

q, a dns.message.Message, the query to send.

where, a str, the nameserver IP address or the full URL. If an IP address is given, the URL will be constructed using the following schema: https://<IP-address>:<port>/<path>.

timeout, a float or None, the number of seconds to wait before the query times out. If None, the default, wait forever.

port, a int, the port to send the query to. The default is 443.

source, a str containing an IPv4 or IPv6 address, specifying the source address. The default is the wildcard address.

source_port, an int, the port from which to send the message. The default is 0.

one_rr_per_rrset, a bool. If True, put each RR into its own RRset.

ignore_trailing, a bool. If True, ignore trailing junk at end of the received message.

session, an httpx.Client. If provided, the client session to use to send the queries.

path, a str. If where is an IP address, then path will be used to construct the URL to send the DNS query to.

post, a bool. If True, the default, POST method will be used.

bootstrap_address, a str, the IP address to use to bypass resolution.

verify, a bool or str. If a True, then TLS certificate verification of the server is done using the default CA bundle; if False, then no verification is done; if a str then it specifies the path to a certificate file or directory which will be used for verification.

resolver, a dns.resolver.Resolver or None, the resolver to use for resolution of hostnames in URLs. If not specified, a new resolver with a default configuration will be used; note this is not the default resolver as that resolver might have been configured to use DoH causing a chicken-and-egg problem. This parameter only has an effect if the HTTP library is httpx.

family, an int, the address family. If socket.AF_UNSPEC (the default), both A and AAAA records will be retrieved.

Returns a 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.UDPMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

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

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

where, a str containing an IPv4 or IPv6 address, where to send the message.

txn_manager, a dns.transaction.TransactionManager, the txn_manager for this transfer (typically a dns.zone.Zone).

query, the query to send. If not supplied, a default query is constructed using information from the txn_manager.

port, an int, the port send the message to. The default is 53.

timeout, a float, the number of seconds to wait for each response message. If None, the default, wait forever.

lifetime, a float, the total number of seconds to spend doing the transfer. If None, the default, then there is no limit on the time the transfer may take.

source, a str containing an IPv4 or IPv6 address, specifying the source address. The default is the wildcard address.

source_port, an int, the port from which to send the message. The default is 0.

udp_mode, a dns.query.UDPMode, determines how UDP is used for IXFRs. The default is dns.UDPMode.NEVER, i.e. only use TCP. Other possibilities are dns.UDPMode.TRY_FIRST, which means “try UDP but fallback to TCP if needed”, and dns.UDPMode.ONLY, which means “try UDP and raise dns.xfr.UseTCP if it does not succeed.

Raises on errors.

dns.query.xfr(where: str, zone: ~dns.name.Name | str, rdtype: ~dns.rdatatype.RdataType | str = RdataType.AXFR, rdclass: ~dns.rdataclass.RdataClass | str = RdataClass.IN, timeout: float | None = None, port: int = 53, keyring: ~typing.Dict[~dns.name.Name, ~dns.tsig.Key] | None = None, keyname: ~dns.name.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: ~dns.name.Name | str = <DNS name hmac-sha256.>) → Any

Return a generator for the responses to a zone transfer.

where, a str containing an IPv4 or IPv6 address, where to send the message.

zone, a dns.name.Name or str, the name of the zone to transfer.

rdtype, an int or str, the type of zone transfer. The default is dns.rdatatype.AXFR. dns.rdatatype.IXFR can be used to do an incremental transfer instead.

rdclass, an int or str, the class of the zone transfer. The default is dns.rdataclass.IN.

timeout, a float, the number of seconds to wait for each response message. If None, the default, wait forever.

port, an int, the port send the message to. The default is 53.

keyring, a dict, the keyring to use for TSIG.

keyname, a dns.name.Name or str, the name of the TSIG key to use.

relativize, a bool. If True, all names in the zone will be relativized to the zone origin. It is essential that the relativize setting matches the one specified to dns.zone.from_xfr() if using this generator to make a zone.

lifetime, a float, the total number of seconds to spend doing the transfer. If None, the default, then there is no limit on the time the transfer may take.

source, a str containing an IPv4 or IPv6 address, specifying the source address. The default is the wildcard address.

source_port, an int, the port from which to send the message. The default is 0.

serial, an int, the SOA serial number to use as the base for an IXFR diff sequence (only meaningful if rdtype is dns.rdatatype.IXFR).

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

keyalgorithm, a dns.name.Name or str, the TSIG algorithm to use.

Raises on errors, and so does the generator.

Returns a generator of dns.message.Message objects.