Making DNS Messages

dns.message.from_file(f: Any, idna_codec: IDNACodec | None = None, one_rr_per_rrset: bool = False) Message[source]

Read the next text format message from the specified file.

Message blocks are separated by a single blank line.

f, a file or str. If f is text, it is treated as the pathname of a file to open.

idna_codec, a dns.name.IDNACodec, specifies the IDNA encoder/decoder. If None, the default IDNA 2003 encoder/decoder is used.

one_rr_per_rrset, a bool. If True, then each RR is put into its own rrset. The default is False.

Raises dns.message.UnknownHeaderField if a header is unknown.

Raises dns.exception.SyntaxError if the text is badly formed.

Returns a dns.message.Message object

dns.message.from_text(text: str, idna_codec: IDNACodec | None = None, one_rr_per_rrset: bool = False, origin: Name | None = None, relativize: bool = True, relativize_to: Name | None = None) Message[source]

Convert the text format message into a message object.

The reader stops after reading the first blank line in the input to facilitate reading multiple messages from a single file with dns.message.from_file().

text, a str, the text format message.

idna_codec, a dns.name.IDNACodec, specifies the IDNA encoder/decoder. If None, the default IDNA 2003 encoder/decoder is used.

one_rr_per_rrset, a bool. If True, then each RR is put into its own rrset. The default is False.

origin, a dns.name.Name (or None), the origin to use for relative names.

relativize, a bool. If true, name will be relativized.

relativize_to, a dns.name.Name (or None), the origin to use when relativizing names. If not set, the origin value will be used.

Raises dns.message.UnknownHeaderField if a header is unknown.

Raises dns.exception.SyntaxError if the text is badly formed.

Returns a dns.message.Message object

dns.message.from_wire(wire: bytes, keyring: Any | None = None, request_mac: bytes | None = b'', xfr: bool = False, origin: Name | None = None, tsig_ctx: HMACTSig | GSSTSig | None = None, multi: bool = False, question_only: bool = False, one_rr_per_rrset: bool = False, ignore_trailing: bool = False, raise_on_truncation: bool = False, continue_on_error: bool = False) Message[source]

Convert a DNS wire format message into a message object.

keyring, a dns.tsig.Key, dict, bool, or None, the key or keyring to use if the message is signed. If None or True, then trying to decode a message with a TSIG will fail as it cannot be validated. If False, then TSIG validation is disabled.

request_mac, a bytes or None. If the message is a response to a TSIG-signed request, request_mac should be set to the MAC of that request.

xfr, a bool, should be set to True if this message is part of a zone transfer.

origin, a dns.name.Name or None. If the message is part of a zone transfer, origin should be the origin name of the zone. If not None, names will be relativized to the origin.

tsig_ctx, a dns.tsig.HMACTSig or dns.tsig.GSSTSig object, the ongoing TSIG context, used when validating zone transfers.

multi, a bool, should be set to True if this message is part of a multiple message sequence.

question_only, a bool. If True, read only up to the end of the question section.

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 message.

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

continue_on_error, a bool. If True, try to continue parsing even if errors occur. Erroneous rdata will be ignored. Errors will be accumulated as a list of MessageError objects in the message’s errors attribute. This option is recommended only for DNS analysis tools, or for use in a server as part of an error handling path. The default is False.

Raises dns.message.ShortHeader if the message is less than 12 octets long.

Raises dns.message.TrailingJunk if there were octets in the message past the end of the proper DNS message, and ignore_trailing is False.

Raises dns.message.BadEDNS if an OPT record was in the wrong section, or occurred more than once.

Raises dns.message.BadTSIG if a TSIG record was not the last record of the additional data section.

Raises dns.message.Truncated if the TC flag is set and raise_on_truncation is True.

Returns a dns.message.Message.

dns.message.make_query(qname: ~dns.name.Name | str, rdtype: ~dns.rdatatype.RdataType | str, rdclass: ~dns.rdataclass.RdataClass | str = RdataClass.IN, use_edns: int | bool | None = None, want_dnssec: bool = False, ednsflags: int | None = None, payload: int | None = None, request_payload: int | None = None, options: ~typing.List[~dns.edns.Option] | None = None, idna_codec: ~dns.name.IDNACodec | None = None, id: int | None = None, flags: int = <Flag.RD: 256>, pad: int = 0) QueryMessage[source]

Make a query message.

The query name, type, and class may all be specified either as objects of the appropriate type, or as strings.

The query will have a randomly chosen query id, and its DNS flags will be set to dns.flags.RD.

qname, a dns.name.Name or str, the query name.

rdtype, an int or str, the desired rdata type.

rdclass, an int or str, the desired rdata class; the default is class IN.

use_edns, an int, bool or None. The EDNS level to use; the default is None. If None, EDNS will be enabled only if other parameters (ednsflags, payload, request_payload, or options) are set. See the description of dns.message.Message.use_edns() for the possible values for use_edns and their meanings.

want_dnssec, a bool. If True, DNSSEC data is desired.

ednsflags, an int, the EDNS flag values.

payload, an int, is the EDNS sender’s payload field, which is the maximum size of UDP datagram the sender can handle. I.e. how big a response to this message can be.

request_payload, an int, is the EDNS payload size to use when sending this message. If not specified, defaults to the value of payload.

options, a list of dns.edns.Option objects or None, the EDNS options.

idna_codec, a dns.name.IDNACodec, specifies the IDNA encoder/decoder. If None, the default IDNA 2003 encoder/decoder is used.

id, an int or None, the desired query id. The default is None, which generates a random query id.

flags, an int, the desired query flags. The default is dns.flags.RD.

pad, a non-negative int. If 0, the default, do not pad; otherwise add padding bytes to make the message size a multiple of pad. Note that if padding is non-zero, an EDNS PADDING option will always be added to the message.

Returns a dns.message.QueryMessage

dns.message.make_response(query: Message, recursion_available: bool = False, our_payload: int = 8192, fudge: int = 300, tsig_error: int = 0, pad: int | None = None, copy_mode: CopyMode | None = None) Message[source]

Make a message which is a response for the specified query. The message returned is really a response skeleton; it has all of the infrastructure required of a response, but none of the content.

Response section(s) which are copied are shallow copies of the matching section(s) in the query, so the query’s RRsets should not be changed.

query, a dns.message.Message, the query to respond to.

recursion_available, a bool, should RA be set in the response?

our_payload, an int, the payload size to advertise in EDNS responses.

fudge, an int, the TSIG time fudge.

tsig_error, an int, the TSIG error.

pad, a non-negative int or None. If 0, the default, do not pad; otherwise if not None add padding bytes to make the message size a multiple of pad. Note that if padding is non-zero, an EDNS PADDING option will always be added to the message. If None, add padding following RFC 8467, namely if the request is padded, pad the response to 468 otherwise do not pad.

copy_mode, a dns.message.CopyMode or None, determines how sections are copied. The default, None copies sections according to the default for the message’s opcode, which is currently dns.message.CopyMode.QUESTION for all opcodes. dns.message.CopyMode.QUESTION copies only the question section. dns.message.CopyMode.EVERYTHING copies all sections other than OPT or TSIG records, which are created appropriately if needed. dns.message.CopyMode.NOTHING copies no sections; note that this mode is for server testing purposes and is otherwise not recommended for use. In particular, dns.message.is_response() will be False if you create a response this way and the rcode is not FORMERR, SERVFAIL, NOTIMP, or REFUSED.

Returns a dns.message.Message object whose specific class is appropriate for the query. For example, if query is a dns.update.UpdateMessage, the response will be one too.