t.n.s.DNSServerFactory(protocol.ServerFactory) : class documentation

Part of twisted.names.server View Source View In Hierarchy 

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

@ivar cache: A L{Cache<twisted.names.cache.Cache>} instance whose
    C{cacheResult} method is called when a response is received from one of
    C{clients}. Defaults to L{None} if no caches are specified. See
    C{caches} of L{__init__} for more details.
@type cache: L{Cache<twisted.names.cache.Cache} or L{None}

@ivar canRecurse: A flag indicating whether this server is capable of
    performing recursive DNS resolution.
@type canRecurse: L{bool}

@ivar resolver: A L{resolve.ResolverChain} containing an ordered list of
    C{authorities}, C{caches} and C{clients} to which queries will be
    dispatched.
@type resolver: L{resolve.ResolverChain}

@ivar verbose: See L{__init__}

@ivar connections: A list of all the connected L{DNSProtocol} instances
    using this object as their controller.
@type connections: C{list} of L{DNSProtocol} instances

@ivar protocol: A callable used for building a DNS stream protocol. Called
    by L{DNSServerFactory.buildProtocol} and passed the L{DNSServerFactory}
    instance as the one and only positional argument.  Defaults to
    L{dns.DNSProtocol}.
@type protocol: L{IProtocolFactory} constructor

@ivar _messageFactory: A response message constructor with an initializer
     signature matching L{dns.Message.__init__}.
@type _messageFactory: C{callable}
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.
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):

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.
def __init__(self, authorities=None, caches=None, clients=None, verbose=0): (source) 
@param authorities: Resolvers which provide authoritative answers.
@type authorities: L{list} of L{IResolver} providers

@param caches: Resolvers which provide cached non-authoritative
    answers. The first cache instance is assigned to
    C{DNSServerFactory.cache} and its C{cacheResult} method will be
    called when a response is received from one of C{clients}.
@type caches: L{list} of L{Cache<twisted.names.cache.Cache} instances

@param clients: Resolvers which are capable of performing recursive DNS
    lookups.
@type clients: L{list} of L{IResolver} providers

@param verbose: An integer controlling the verbosity of logging of
    queries and responses. Default is C{0} which means no logging. Set
    to C{2} to enable logging of full query and response messages.
@param verbose: L{int}
def _verboseLog(self, *args, **kwargs): (source)
Log a message only if verbose logging is enabled.
ParametersargsPositional arguments which will be passed to log.msg
kwargsKeyword arguments which will be passed to log.msg
def buildProtocol(self, addr): (source)
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.

Override this method to alter how Protocol instances get created.

Parametersaddran object implementing twisted.internet.interfaces.IAddress
def connectionMade(self, protocol): (source)
Track a newly connected DNSProtocol.
ParametersprotocolThe protocol instance to be tracked. (type: dns.DNSProtocol)
def connectionLost(self, protocol): (source)
Stop tracking a no-longer connected DNSProtocol.
ParametersprotocolThe 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.

ParametersprotocolThe DNS protocol instance to which to send the message. (type: dns.DNSDatagramProtocol or dns.DNSProtocol)
messageThe DNS message to be sent. (type: dns.Message)
addressThe 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

ParametersmessageThe request message (type: int)
rCodeThe response code which will be assigned to the response.
answersAn optional list of answer records which will be assigned to the response. (type: list of dns.RRHeader)
authorityAn optional list of authority records which will be assigned to the response. (type: list of dns.RRHeader)
additionalAn optional list of additional records which will be assigned to the response. (type: list of dns.RRHeader)
ReturnsA response Message instance. (type: Message)
See Alsodns._responseFromMessage
def gotResolverResponse(self, (ans, auth, add), 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.

ParametersansA list of answer records (type: list of dns.RRHeader instances)
authA list of authority records (type: list of dns.RRHeader instances)
addA list of additional records (type: list of dns.RRHeader instances)
protocolThe DNS protocol instance to which to send a response message. (type: dns.DNSDatagramProtocol or dns.DNSProtocol)
messageThe original DNS query message for which a response message will be constructed. (type: dns.Message)
addressThe 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.

ParametersfailureThe reason for the failed resolution (as reported by self.resolver.query). (type: Failure)
protocolThe DNS protocol instance to which to send a response message. (type: dns.DNSDatagramProtocol or dns.DNSProtocol)
messageThe original DNS query message for which a response message will be constructed. (type: dns.Message)
addressThe 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.

ParametersprotocolThe DNS protocol instance to which to send a response message. (type: dns.DNSDatagramProtocol or dns.DNSProtocol)
messageThe original DNS query message for which a response message will be constructed. (type: dns.Message)
addressThe address to which the response message will be sent or None if protocol is a stream protocol. (type: tuple or None)
ReturnsA 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.

ParametersprotocolThe DNS protocol instance to which to send a response message. (type: dns.DNSDatagramProtocol or dns.DNSProtocol)
messageThe original DNS query message for which a response message will be constructed. (type: dns.Message)
addressThe 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.

ParametersprotocolThe DNS protocol instance to which to send a response message. (type: dns.DNSDatagramProtocol or dns.DNSProtocol)
messageThe original DNS query message for which a response message will be constructed. (type: dns.Message)
addressThe 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.

ParametersprotocolThe DNS protocol instance to which to send a response message. (type: dns.DNSDatagramProtocol or dns.DNSProtocol)
messageThe original DNS query message for which a response message will be constructed. (type: dns.Message)
addressThe 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.

ParametersprotocolThe DNS protocol instance to which to send a response message. (type: dns.DNSDatagramProtocol or dns.DNSProtocol)
messageThe original DNS query message for which a response message will be constructed. (type: dns.Message)
addressThe 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.

ParametersmessageThe DNS message that was received. (type: dns.Message)
protoThe DNS protocol instance which received the message (type: dns.DNSDatagramProtocol or dns.DNSProtocol)
addressThe 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.

ParametersmessageThe DNS message that was received. (type: dns.Message)
protocolThe DNS protocol instance which received the message (type: dns.DNSDatagramProtocol or dns.DNSProtocol)
addressThe 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)
ReturnsTrue if the received message contained one or more queries, else False. (type: bool)
API Documentation for Twisted, generated by pydoctor at 2014-05-12 18:27:00.