Go to the latest version of this document.
search in docstrings

Search bar offers the following options:

- Term presence. The below example searches for documents that must contain “foo”, might contain “bar” and must not contain “baz”: `+foo bar -baz`
- Wildcards. The below example searches for documents with words beginning with “foo”: `foo*`
- Search in specific fields. The following search matches all objects in "twisted.mail" that matches “search”: `+qname:twisted.mail.* +search`

  Possible fields: 'name', 'qname' (fully qualified name), 'docstring', and 'kind'. Last two fields are only applicable if "search in docstrings" is enabled.

- Fuzzy matches. The following search matches all documents that have a word within 1 edit distance of “foo”: `foo~1`

Results provided by Lunr.js

# ``twisted`.`names`.`server`.`DNSServerFactory``

class documentation

`class DNSServerFactory(protocol.ServerFactory): (source)`

View In Hierarchy

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

Method | `__init__` | No summary
Method | `allowQuery` | Called by `DNSServerFactory.messageReceived` to decide whether to process a received message or to reply with `dns.EREFUSED`.
Method | `buildProtocol` | Create an instance of a subclass of Protocol.
Method | `connectionLost` | Stop tracking a no-longer connected `DNSProtocol`.
Method | `connectionMade` | Track a newly connected `DNSProtocol`.
Method | `gotResolverError` | A callback used by `DNSServerFactory.handleQuery` for handling deferred errors from `self.resolver.query`.
Method | `gotResolverResponse` | A callback used by `DNSServerFactory.handleQuery` for handling the deferred response from `self.resolver.query`.
Method | `handleInverseQuery` | Called by `DNSServerFactory.messageReceived` when an inverse query 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 | `handleQuery` | Called by `DNSServerFactory.messageReceived` when a query message is received.
Method | `handleStatus` | Called by `DNSServerFactory.messageReceived` when a status message is received.
Method | `messageReceived` | `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.
Method | `sendReply` | Send a response `message` to a given `address` via the supplied `protocol`.
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 | `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`...
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__`
Method | `_responseFromMessage` | Generate a `Message` instance suitable for use as the response to `message`.
Method | `_verboseLog` | Log a message only if verbose logging is enabled.
Instance Variable | `_messageFactory` | A response message constructor with an initializer signature matching `dns.Message.__init__`.

Inherited from `Factory` (via `ServerFactory`):

Class Method | `forProtocol` | Create a factory for the given protocol.
Method | `doStart` | Make sure startFactory is called.
Method | `doStop` | Make sure stopFactory is called.
Method | `logPrefix` | Describe this factory for log messages.
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.
Class Variable | `noisy` | Undocumented
Instance Variable | `numPorts` | Undocumented

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

Parameters
authorities:`list` of `IResolver` providers | Resolvers which provide authoritative answers.
caches:`list` of `Cache` instances | 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`.
clients:`list` of `IResolver` providers | Resolvers which are capable of performing recursive DNS lookups.
verbose:`int` | 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.

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:`dns.Message` | The DNS message that was received.
protocol:`dns.DNSDatagramProtocol` or `dns.DNSProtocol` | The DNS protocol instance which received the message
address:`tuple` or `None` | 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.
Returns
`bool` | `True` if the received message contained one or more queries, else `False`.

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 `IAddress`

def connectionLost(self, protocol): (source)

Stop tracking a no-longer connected `DNSProtocol`.

Parameters
protocol:`dns.DNSProtocol` | The tracked protocol instance to be which has been lost.

def connectionMade(self, protocol): (source)

Track a newly connected `DNSProtocol`.

Parameters
protocol:`dns.DNSProtocol` | The protocol instance to be tracked.

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:`Failure` | The reason for the failed resolution (as reported by `self.resolver.query`).
protocol:`dns.DNSDatagramProtocol` or `dns.DNSProtocol` | The DNS protocol instance to which to send a response message.
message:`dns.Message` | The original DNS query message for which a response message will be constructed.
address:`tuple` or `None` | The address to which the response message will be sent or `None` if `protocol` is a stream protocol.

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:`tuple` of `list` of `dns.RRHeader` instances | Answer records, authority records and additional records
protocol:`dns.DNSDatagramProtocol` or `dns.DNSProtocol` | The DNS protocol instance to which to send a response message.
message:`dns.Message` | The original DNS query message for which a response message will be constructed.
address:`tuple` or `None` | The address to which the response message will be sent or `None` if `protocol` is a stream protocol.

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

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

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

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:`dns.Message` | The original DNS query message for which a response message will be constructed.
protocol:`dns.DNSDatagramProtocol` or `dns.DNSProtocol` | The DNS protocol instance to which to send a response message.
address:`tuple` or `None` | The address to which the response message will be sent or `None` if `protocol` is a stream protocol.
Returns
`Deferred` | A `deferred` which fires with the resolved result or error of the first query in `message`.

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

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:`dns.Message` | The DNS message that was received.
proto:`dns.DNSDatagramProtocol` or `dns.DNSProtocol` | The DNS protocol instance which received the message
address:`tuple` or `None` | 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.

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:`dns.DNSDatagramProtocol` or `dns.DNSProtocol` | The DNS protocol instance to which to send the message.
message:`dns.Message` | The DNS message to be sent.
address:`tuple` or `None` | The address to which the message will be sent or `None` if `protocol` is a stream protocol.

cache: `Cache` or `None` = (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.

canRecurse: `bool` = (source)

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

connections: `list` of `DNSProtocol` instances = (source)

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

protocol: `IProtocolFactory` constructor = (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`.

resolver: `resolve.ResolverChain` = (source)

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

verbose = (source)

See `__init__`

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:`int` | The request message
rCode | The response code which will be assigned to the response.
answers:`list` of `dns.RRHeader` | An optional list of answer records which will be assigned to the response.
authority:`list` of `dns.RRHeader` | An optional list of authority records which will be assigned to the response.
additional:`list` of `dns.RRHeader` | An optional list of additional records which will be assigned to the response.
Returns
`Message` | A response `Message` instance.
See Also
`dns._responseFromMessage`

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`

_messageFactory: `callable` = (source)

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