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
orstr
. 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. IfNone
, the default IDNA 2003 encoder/decoder is used.one_rr_per_rrset, a
bool
. IfTrue
, then each RR is put into its own rrset. The default isFalse
.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. IfNone
, the default IDNA 2003 encoder/decoder is used.one_rr_per_rrset, a
bool
. IfTrue
, then each RR is put into its own rrset. The default isFalse
.origin, a
dns.name.Name
(orNone
), the origin to use for relative names.relativize, a
bool
. If true, name will be relativized.relativize_to, a
dns.name.Name
(orNone
), 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
, orNone
, the key or keyring to use if the message is signed. IfNone
orTrue
, then trying to decode a message with a TSIG will fail as it cannot be validated. IfFalse
, then TSIG validation is disabled.request_mac, a
bytes
orNone
. 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 toTrue
if this message is part of a zone transfer.origin, a
dns.name.Name
orNone
. If the message is part of a zone transfer, origin should be the origin name of the zone. If notNone
, names will be relativized to the origin.tsig_ctx, a
dns.tsig.HMACTSig
ordns.tsig.GSSTSig
object, the ongoing TSIG context, used when validating zone transfers.multi, a
bool
, should be set toTrue
if this message is part of a multiple message sequence.question_only, a
bool
. IfTrue
, read only up to the end of the question section.one_rr_per_rrset, a
bool
. IfTrue
, put each RR into its own RRset.ignore_trailing, a
bool
. IfTrue
, ignore trailing junk at end of the message.raise_on_truncation, a
bool
. IfTrue
, raise an exception if the TC bit is set.continue_on_error, a
bool
. IfTrue
, 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’serrors
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 isFalse
.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 isFalse
.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 isTrue
.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
orstr
, the query name.rdtype, an
int
orstr
, the desired rdata type.rdclass, an
int
orstr
, the desired rdata class; the default is class IN.use_edns, an
int
,bool
orNone
. The EDNS level to use; the default isNone
. IfNone
, 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
. IfTrue
, 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 orNone
, the EDNS options.idna_codec, a
dns.name.IDNACodec
, specifies the IDNA encoder/decoder. IfNone
, the default IDNA 2003 encoder/decoder is used.id, an
int
orNone
, the desired query id. The default isNone
, which generates a random query id.flags, an
int
, the desired query flags. The default isdns.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
orNone
. If 0, the default, do not pad; otherwise if notNone
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. IfNone
, 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
orNone
, determines how sections are copied. The default,None
copies sections according to the default for the message’s opcode, which is currentlydns.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 beFalse
if you create a response this way and the rcode is notFORMERR
,SERVFAIL
,NOTIMP
, orREFUSED
.Returns a
dns.message.Message
object whose specific class is appropriate for the query. For example, if query is adns.update.UpdateMessage
, the response will be one too.