The dns.message.Message Class¶
This is the base class for all messages, and the class used for any DNS opcodes that do not have a more specific class.
- class dns.message.Message(id: Optional[int] = None)[source]¶
A DNS message.
- id¶
An
int
, the query id; the default is a randomly chosen id.
- flags¶
An
int
, the DNS flags of the message.
- sections¶
A list of lists of
dns.rrset.RRset
objects.
- edns¶
An
int
, the EDNS level to use. The default is -1, no EDNS.
- ednsflags¶
An
int
, the EDNS flags.
- payload¶
An
int
, the EDNS payload size. The default is 0.
- options¶
The EDNS options, a list of
dns.edns.Option
objects. The default is the empty list.
- request_payload¶
The associated request’s EDNS payload size. This field is meaningful in response messages, and if set to a non-zero value, will limit the size of the response to the specified size. The default is 0, which means “use the default limit” which is currently 65535.
- keyring¶
A
dns.tsig.Key
, the TSIG key. The default is None.
- keyname¶
The TSIG keyname to use, a
dns.name.Name
. The default isNone
.
- keyalgorithm¶
A
dns.name.Name
, the TSIG algorithm to use. Defaults todns.tsig.default_algorithm
. Constants for TSIG algorithms are defined the indns.tsig
module.
- request_mac¶
A
bytes
, the TSIG MAC of the request message associated with this message; used when validating TSIG signatures.
- fudge¶
An
int
, the TSIG time fudge. The default is 300 seconds.
- original_id¶
An
int
, the TSIG original id; defaults to the message’s id.
- tsig_error¶
An
int
, the TSIG error code. The default is 0.
- other_data¶
A
bytes
, the TSIG “other data”. The default is the emptybytes
.
- mac¶
A
bytes
, the TSIG MAC for this message.
- xfr¶
A
bool
. This attribute is true when the message being used for the results of a DNS zone transfer. The default isFalse
.
- origin¶
A
dns.name.Name
. The origin of the zone in messages which are used for zone transfers or for DNS dynamic updates. The default isNone
.
- tsig_ctx¶
An
hmac.HMAC
, the TSIG signature context associated with this message. The default isNone
.
- had_tsig¶
A
bool
, which isTrue
if the message had a TSIG signature when it was decoded from wire format.
- multi¶
A
bool
, which isTrue
if this message is part of a multi-message sequence. The default isFalse
. This attribute is used when validating TSIG signatures on messages which are part of a zone transfer.
- first¶
A
bool
, which isTrue
if this message is stand-alone, or the first of a multi-message sequence. The default isTrue
. This variable is used when validating TSIG signatures on messages which are part of a zone transfer.
- index¶
A
dict
, an index of RRsets in the message. The index key is(section, name, rdclass, rdtype, covers, deleting)
. The default is{}
. Indexing improves the performance of finding RRsets. Indexing can be disabled by setting the index toNone
.
- property additional: List[dns.rrset.RRset]¶
The additional data section.
- property answer: List[dns.rrset.RRset]¶
The answer section.
- property authority: List[dns.rrset.RRset]¶
The authority section.
- find_rrset(section: Union[int, List[dns.rrset.RRset]], name: dns.name.Name, rdclass: dns.rdataclass.RdataClass, rdtype: dns.rdatatype.RdataType, covers: dns.rdatatype.RdataType = RdataType.TYPE0, deleting: Optional[dns.rdataclass.RdataClass] = None, create: bool = False, force_unique: bool = False) dns.rrset.RRset [source]¶
Find the RRset with the given attributes in the specified section.
section, an
int
section number, or one of the section attributes of this message. This specifies the the section of the message to search. For example:my_message.find_rrset(my_message.answer, name, rdclass, rdtype) my_message.find_rrset(dns.message.ANSWER, name, rdclass, rdtype)
name, a
dns.name.Name
, the name of the RRset.rdclass, an
int
, the class of the RRset.rdtype, an
int
, the type of the RRset.covers, an
int
orNone
, the covers value of the RRset. The default isNone
.deleting, an
int
orNone
, the deleting value of the RRset. The default isNone
.create, a
bool
. IfTrue
, create the RRset if it is not found. The created RRset is appended to section.force_unique, a
bool
. IfTrue
and create is alsoTrue
, create a new RRset regardless of whether a matching RRset exists already. The default isFalse
. This is useful when creating DDNS Update messages, as order matters for them.Raises
KeyError
if the RRset was not found and create wasFalse
.Returns a
dns.rrset.RRset object
.
- get_rrset(section: Union[int, List[dns.rrset.RRset]], name: dns.name.Name, rdclass: dns.rdataclass.RdataClass, rdtype: dns.rdatatype.RdataType, covers: dns.rdatatype.RdataType = RdataType.TYPE0, deleting: Optional[dns.rdataclass.RdataClass] = None, create: bool = False, force_unique: bool = False) Optional[dns.rrset.RRset] [source]¶
Get the RRset with the given attributes in the specified section.
If the RRset is not found, None is returned.
section, an
int
section number, or one of the section attributes of this message. This specifies the the section of the message to search. For example:my_message.get_rrset(my_message.answer, name, rdclass, rdtype) my_message.get_rrset(dns.message.ANSWER, name, rdclass, rdtype)
name, a
dns.name.Name
, the name of the RRset.rdclass, an
int
, the class of the RRset.rdtype, an
int
, the type of the RRset.covers, an
int
orNone
, the covers value of the RRset. The default isNone
.deleting, an
int
orNone
, the deleting value of the RRset. The default isNone
.create, a
bool
. IfTrue
, create the RRset if it is not found. The created RRset is appended to section.force_unique, a
bool
. IfTrue
and create is alsoTrue
, create a new RRset regardless of whether a matching RRset exists already. The default isFalse
. This is useful when creating DDNS Update messages, as order matters for them.Returns a
dns.rrset.RRset object
orNone
.
- is_response(other: dns.message.Message) bool [source]¶
Is other, also a
dns.message.Message
, a response to this message?Returns a
bool
.
- property question: List[dns.rrset.RRset]¶
The question section.
- section_from_number(number: int) List[dns.rrset.RRset] [source]¶
Return the section list associated with the specified section number.
number is a section number int or the text form of a section name.
Raises
ValueError
if the section isn’t known.Returns a
list
.
- section_number(section: List[dns.rrset.RRset]) int [source]¶
Return the “section number” of the specified section for use in indexing.
section is one of the section attributes of this message.
Raises
ValueError
if the section isn’t known.Returns an
int
.
- set_opcode(opcode: dns.opcode.Opcode) None [source]¶
Set the opcode.
opcode, a
dns.opcode.Opcode
, is the opcode to set.
- set_rcode(rcode: dns.rcode.Rcode) None [source]¶
Set the rcode.
rcode, a
dns.rcode.Rcode
, is the rcode to set.
- to_text(origin: Optional[dns.name.Name] = None, relativize: bool = True, **kw: Dict[str, Any]) str [source]¶
Convert the message to text.
The origin, relativize, and any other keyword arguments are passed to the RRset
to_wire()
method.Returns a
str
.
- to_wire(origin: Optional[dns.name.Name] = None, max_size: int = 0, multi: bool = False, tsig_ctx: Optional[Any] = None, **kw: Dict[str, Any]) bytes [source]¶
Return a string containing the message in DNS compressed wire format.
Additional keyword arguments are passed to the RRset
to_wire()
method.origin, a
dns.name.Name
orNone
, the origin to be appended to any relative names. IfNone
, and the message has an origin attribute that is notNone
, then it will be used.max_size, an
int
, the maximum size of the wire format output; default is 0, which means “the message’s request payload, if nonzero, or 65535”.multi, a
bool
, should be set toTrue
if this message is part of a multiple message sequence.tsig_ctx, a
dns.tsig.HMACTSig
ordns.tsig.GSSTSig
object, the ongoing TSIG context, used when signing zone transfers.Raises
dns.exception.TooBig
if max_size was exceeded.Returns a
bytes
.
- use_edns(edns: Optional[Union[int, bool]] = 0, ednsflags: int = 0, payload: int = 1232, request_payload: Optional[int] = None, options: Optional[List[dns.edns.Option]] = None, pad: int = 0) None [source]¶
Configure EDNS behavior.
edns, an
int
, is the EDNS level to use. SpecifyingNone
,False
, or-1
means “do not use EDNS”, and in this case the other parameters are ignored. SpecifyingTrue
is equivalent to specifying 0, i.e. “use EDNS0”.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.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.
- use_tsig(keyring: Any, keyname: Optional[Union[dns.name.Name, str]] = None, fudge: int = 300, original_id: Optional[int] = None, tsig_error: int = 0, other_data: bytes = b'', algorithm: Union[dns.name.Name, str] = <DNS name hmac-sha256.>) None [source]¶
When sending, a TSIG signature using the specified key should be added.
key, a
dns.tsig.Key
is the key to use. If a key is specified, the keyring and algorithm fields are not used.keyring, a
dict
,callable
ordns.tsig.Key
, is either the TSIG keyring or key to use.The format of a keyring dict is a mapping from TSIG key name, as
dns.name.Name
todns.tsig.Key
or a TSIG secret, abytes
. If adict
keyring is specified but a keyname is not, the key used will be the first key in the keyring. Note that the order of keys in a dictionary is not defined, so applications should supply a keyname when adict
keyring is used, unless they know the keyring contains only one key. If acallable
keyring is specified, the callable will be called with the message and the keyname, and is expected to return a key.keyname, a
dns.name.Name
,str
orNone
, the name of this TSIG key to use; defaults toNone
. If keyring is adict
, the key must be defined in it. If keyring is adns.tsig.Key
, this is ignored.fudge, an
int
, the TSIG time fudge.original_id, an
int
, the TSIG original id. IfNone
, the message’s id is used.tsig_error, an
int
, the TSIG error code.other_data, a
bytes
, the TSIG other data.algorithm, a
dns.name.Name
orstr
, the TSIG algorithm to use. This is only used if keyring is adict
, and the key entry is abytes
.
The following constants may be used to specify sections in the
find_rrset()
and get_rrset()
methods:
- dns.message.QUESTION = MessageSection.QUESTION¶
Message sections
- dns.message.ANSWER = MessageSection.ANSWER¶
Message sections
- dns.message.AUTHORITY = MessageSection.AUTHORITY¶
Message sections
- dns.message.ADDITIONAL = MessageSection.ADDITIONAL¶
Message sections