twisted.names.server.DNSServerFactory : API documentation

class documentation

class twisted.names.server.DNSServerFactory(protocol.ServerFactory): (source)

Server factory and tracker for DNSProtocol connections. This class also provides records for responses to DNS queries.

Instance Variable	cache	A `Cache` instance whose `cacheResult` method is called when a response is received from one of `clients`. Defaults to `None` if no caches are specified. See `caches` of `__init__` for more details.
Instance Variable	canRecurse	A flag indicating whether this server is capable of performing recursive DNS resolution.
Instance Variable	resolver	A `resolve.ResolverChain` containing an ordered list of `authorities`, `caches` and `clients` to which queries will be dispatched.
Instance Variable	verbose	See `__init__`
Instance Variable	connections	A list of all the connected `DNSProtocol` instances using this object as their controller.
Instance Variable	protocol	A callable used for building a DNS stream protocol. Called by `DNSServerFactory.buildProtocol` and passed the `DNSServerFactory` instance as the one and only positional argument. Defaults to `dns.DNSProtocol`.
Method	__init__
Method	buildProtocol	Create an instance of a subclass of Protocol.
Method	connectionMade	Track a newly connected `DNSProtocol`.
Method	connectionLost	Stop tracking a no-longer connected `DNSProtocol`.
Method	sendReply	Send a response `message` to a given `address` via the supplied `protocol`.
Method	gotResolverResponse	A callback used by `DNSServerFactory.handleQuery` for handling the deferred response from `self.resolver.query`.
Method	gotResolverError	A callback used by `DNSServerFactory.handleQuery` for handling deferred errors from `self.resolver.query`.
Method	handleQuery	Called by `DNSServerFactory.messageReceived` when a query message is received.
Method	handleInverseQuery	Called by `DNSServerFactory.messageReceived` when an inverse query message is received.
Method	handleStatus	Called by `DNSServerFactory.messageReceived` when a status message is received.
Method	handleNotify	Called by `DNSServerFactory.messageReceived` when a notify message is received.
Method	handleOther	Called by `DNSServerFactory.messageReceived` when a message with unrecognised OPCODE is received.
Method	messageReceived	No summary
Method	allowQuery	Called by `DNSServerFactory.messageReceived` to decide whether to process a received message or to reply with `dns.EREFUSED`.
Instance Variable	_messageFactory	A response message constructor with an initializer signature matching `dns.Message.__init__`.
Method	_verboseLog	Log a message only if verbose logging is enabled.
Method	_responseFromMessage	Generate a `Message` instance suitable for use as the response to `message`.

Inherited from Factory (via ServerFactory):

Instance Variable	numPorts	Undocumented
Class Variable	noisy	Undocumented
Class Method	forProtocol	Create a factory for the given protocol.
Method	logPrefix	Describe this factory for log messages.
Method	doStart	Make sure startFactory is called.
Method	doStop	Make sure stopFactory is called.
Method	startFactory	This will be called before I begin listening on a Port or Connector.
Method	stopFactory	This will be called before I stop listening on all Ports/Connectors.

cache = (source)

A Cache instance whose cacheResult method is called when a response is received from one of clients. Defaults to None if no caches are specified. See caches of __init__ for more details.

(type: Cache or None)

canRecurse = (source)

A flag indicating whether this server is capable of performing recursive DNS resolution.

(type: bool)

resolver = (source)

A resolve.ResolverChain containing an ordered list of authorities, caches and clients to which queries will be dispatched.

(type: resolve.ResolverChain)

verbose = (source)

See __init__

connections = (source)

A list of all the connected DNSProtocol instances using this object as their controller.

(type: list of DNSProtocol instances)

protocol = (source)

overrides twisted.internet.protocol.Factory.protocol

A callable used for building a DNS stream protocol. Called by DNSServerFactory.buildProtocol and passed the DNSServerFactory instance as the one and only positional argument. Defaults to dns.DNSProtocol.

(type: IProtocolFactory constructor)

_messageFactory = (source)

A response message constructor with an initializer signature matching dns.Message.__init__.

(type: callable)

def __init__(self, authorities=None, caches=None, clients=None, verbose=0): (source)

Parameters	authorities	Resolvers which provide authoritative answers. (type: `list` of `IResolver` providers)
	caches	Resolvers which provide cached non-authoritative answers. The first cache instance is assigned to `DNSServerFactory.cache` and its `cacheResult` method will be called when a response is received from one of `clients`. (type: `list` of `Cache` instances)
	clients	Resolvers which are capable of performing recursive DNS lookups. (type: `list` of `IResolver` providers)
	verbose	An integer controlling the verbosity of logging of queries and responses. Default is `0` which means no logging. Set to `2` to enable logging of full query and response messages. (type: `int`)

def _verboseLog(self, *args, **kwargs): (source)

Log a message only if verbose logging is enabled.

Parameters	args	Positional arguments which will be passed to `log.msg`
	kwargs	Keyword arguments which will be passed to `log.msg`

def buildProtocol(self, addr): (source)

from twisted.internet.interfaces.IProtocolFactory

overrides twisted.internet.protocol.Factory.buildProtocol

Create an instance of a subclass of Protocol.

The returned instance will handle input on an incoming server connection, and an attribute "factory" pointing to the creating factory.

Alternatively, None may be returned to immediately close the new connection.

Override this method to alter how Protocol instances get created.

Parameters addr an object implementing twisted.internet.interfaces.IAddress

def connectionMade(self, protocol): (source)

Track a newly connected DNSProtocol.

Parameters protocol The protocol instance to be tracked. (type: dns.DNSProtocol)

def connectionLost(self, protocol): (source)

Stop tracking a no-longer connected DNSProtocol.

Parameters protocol The tracked protocol instance to be which has been lost. (type: dns.DNSProtocol)

def sendReply(self, protocol, message, address): (source)

Send a response message to a given address via the supplied protocol.

Message payload will be logged if DNSServerFactory.verbose is >1.

Parameters	protocol	The DNS protocol instance to which to send the message. (type: `dns.DNSDatagramProtocol` or `dns.DNSProtocol`)
	message	The DNS message to be sent. (type: `dns.Message`)
	address	The address to which the message will be sent or `None` if `protocol` is a stream protocol. (type: `tuple` or `None`)

def _responseFromMessage(self, message, rCode=dns.OK, answers=None, authority=None, additional=None): (source)

Generate a Message instance suitable for use as the response to message.

queries will be copied from the request to the response.

rCode, answers, authority and additional will be assigned to the response, if supplied.

The recAv flag will be set on the response if the canRecurse flag on this DNSServerFactory is set to True.

The auth flag will be set on the response if *any* of the supplied answers have their auth flag set to True.

The response will have the same maxSize as the request.

Additionally, the response will have a timeReceived attribute whose value is that of the original request and the

Parameters	message	The request message (type: `int`)
	rCode	The response code which will be assigned to the response.
	answers	An optional list of answer records which will be assigned to the response. (type: `list` of `dns.RRHeader`)
	authority	An optional list of authority records which will be assigned to the response. (type: `list` of `dns.RRHeader`)
	additional	An optional list of additional records which will be assigned to the response. (type: `list` of `dns.RRHeader`)
Returns	A response `Message` instance. (type: `Message`)
See Also	`dns._responseFromMessage`

def gotResolverResponse(self, response, protocol, message, address): (source)

A callback used by DNSServerFactory.handleQuery for handling the deferred response from self.resolver.query.

Constructs a response message by combining the original query message with the resolved answer, authority and additional records.

Marks the response message as authoritative if any of the resolved answers are found to be authoritative.

The resolved answers count will be logged if DNSServerFactory.verbose is >1.

Parameters	response	Answer records, authority records and additional records (type: `tuple` of `list` of `dns.RRHeader` instances)
	protocol	The DNS protocol instance to which to send a response message. (type: `dns.DNSDatagramProtocol` or `dns.DNSProtocol`)
	message	The original DNS query message for which a response message will be constructed. (type: `dns.Message`)
	address	The address to which the response message will be sent or `None` if `protocol` is a stream protocol. (type: `tuple` or `None`)

def gotResolverError(self, failure, protocol, message, address): (source)

A callback used by DNSServerFactory.handleQuery for handling deferred errors from self.resolver.query.

Constructs a response message from the original query message by assigning a suitable error code to rCode.

An error message will be logged if DNSServerFactory.verbose is >1.

Parameters	failure	The reason for the failed resolution (as reported by `self.resolver.query`). (type: `Failure`)
	protocol	The DNS protocol instance to which to send a response message. (type: `dns.DNSDatagramProtocol` or `dns.DNSProtocol`)
	message	The original DNS query message for which a response message will be constructed. (type: `dns.Message`)
	address	The address to which the response message will be sent or `None` if `protocol` is a stream protocol. (type: `tuple` or `None`)

def handleQuery(self, message, protocol, address): (source)

Called by DNSServerFactory.messageReceived when a query message is received.

Takes the first query from the received message and dispatches it to self.resolver.query.

Adds callbacks DNSServerFactory.gotResolverResponse and DNSServerFactory.gotResolverError to the resulting deferred.

Note: Multiple queries in a single message are not supported because there is no standard way to respond with multiple rCodes, auth, etc. This is consistent with other DNS server implementations. See http://tools.ietf.org/html/draft-ietf-dnsext-edns1-03 for a proposed solution.

Parameters	message	The original DNS query message for which a response message will be constructed. (type: `dns.Message`)
	protocol	The DNS protocol instance to which to send a response message. (type: `dns.DNSDatagramProtocol` or `dns.DNSProtocol`)
	address	The address to which the response message will be sent or `None` if `protocol` is a stream protocol. (type: `tuple` or `None`)
Returns	A `deferred` which fires with the resolved result or error of the first query in `message`. (type: `Deferred`)

def handleInverseQuery(self, message, protocol, address): (source)

Called by DNSServerFactory.messageReceived when an inverse query message is received.

Replies with a Not Implemented error by default.

An error message will be logged if DNSServerFactory.verbose is >1.

Override in a subclass.

Parameters	message	The original DNS query message for which a response message will be constructed. (type: `dns.Message`)
	protocol	The DNS protocol instance to which to send a response message. (type: `dns.DNSDatagramProtocol` or `dns.DNSProtocol`)
	address	The address to which the response message will be sent or `None` if `protocol` is a stream protocol. (type: `tuple` or `None`)

def handleStatus(self, message, protocol, address): (source)

Called by DNSServerFactory.messageReceived when a status message is received.

Replies with a Not Implemented error by default.

An error message will be logged if DNSServerFactory.verbose is >1.

Override in a subclass.

Parameters	message	The original DNS query message for which a response message will be constructed. (type: `dns.Message`)
	protocol	The DNS protocol instance to which to send a response message. (type: `dns.DNSDatagramProtocol` or `dns.DNSProtocol`)
	address	The address to which the response message will be sent or `None` if `protocol` is a stream protocol. (type: `tuple` or `None`)

def handleNotify(self, message, protocol, address): (source)

Called by DNSServerFactory.messageReceived when a notify message is received.

Replies with a Not Implemented error by default.

An error message will be logged if DNSServerFactory.verbose is >1.

Override in a subclass.

Parameters	message	The original DNS query message for which a response message will be constructed. (type: `dns.Message`)
	protocol	The DNS protocol instance to which to send a response message. (type: `dns.DNSDatagramProtocol` or `dns.DNSProtocol`)
	address	The address to which the response message will be sent or `None` if `protocol` is a stream protocol. (type: `tuple` or `None`)

def handleOther(self, message, protocol, address): (source)

Called by DNSServerFactory.messageReceived when a message with unrecognised OPCODE is received.

Replies with a Not Implemented error by default.

An error message will be logged if DNSServerFactory.verbose is >1.

Override in a subclass.

Parameters	message	The original DNS query message for which a response message will be constructed. (type: `dns.Message`)
	protocol	The DNS protocol instance to which to send a response message. (type: `dns.DNSDatagramProtocol` or `dns.DNSProtocol`)
	address	The address to which the response message will be sent or `None` if `protocol` is a stream protocol. (type: `tuple` or `None`)

def messageReceived(self, message, proto, address=None): (source)

DNSServerFactory.messageReceived is called by protocols which are under the control of this DNSServerFactory whenever they receive a DNS query message or an unexpected / duplicate / late DNS response message.

DNSServerFactory.allowQuery is called with the received message, protocol and origin address. If it returns False, a dns.EREFUSED response is sent back to the client.

Otherwise the received message is dispatched to one of DNSServerFactory.handleQuery, DNSServerFactory.handleInverseQuery, DNSServerFactory.handleStatus, DNSServerFactory.handleNotify, or DNSServerFactory.handleOther depending on the OPCODE of the received message.

If DNSServerFactory.verbose is >0 all received messages will be logged in more or less detail depending on the value of verbose.

Parameters	message	The DNS message that was received. (type: `dns.Message`)
	proto	The DNS protocol instance which received the message (type: `dns.DNSDatagramProtocol` or `dns.DNSProtocol`)
	address	The address from which the message was received. Only provided for messages received by datagram protocols. The origin of Messages received from stream protocols can be gleaned from the protocol `transport` attribute. (type: `tuple` or `None`)

def allowQuery(self, message, protocol, address): (source)

Called by DNSServerFactory.messageReceived to decide whether to process a received message or to reply with dns.EREFUSED.

This default implementation permits anything but empty queries.

Override in a subclass to implement alternative policies.

Parameters	message	The DNS message that was received. (type: `dns.Message`)
	protocol	The DNS protocol instance which received the message (type: `dns.DNSDatagramProtocol` or `dns.DNSProtocol`)
	address	The address from which the message was received. Only provided for messages received by datagram protocols. The origin of Messages received from stream protocols can be gleaned from the protocol `transport` attribute. (type: `tuple` or `None`)
Returns	`True` if the received message contained one or more queries, else `False`. (type: `bool`)

API Documentation for Twisted, generated by pydoctor 20.12.1 at 2021-02-28 19:53:36.