Network.DNS.Resolver

DNS Resolver and generic (lower-level) lookup functions.

Documentation

Configuration for resolver

data FileOrNumericHost

Union type for FilePath and HostName. Specify FilePath to "resolv.conf" or numeric IP address in String form.

Warning: Only numeric IP addresses are valid RCHostNames.

Example (using Google's public DNS cache):

>>> let cache = RCHostName "8.8.8.8"

Constructors

RCFilePath FilePath

A path for "resolv.conf"

RCHostName HostName

A numeric IP address

RCHostPort HostName PortNumber

A numeric IP address and port number

data ResolvConf

Type for resolver configuration. The easiest way to construct a ResolvConf object is to modify the defaultResolvConf.

Constructors

ResolvConf

Fields

• resolvInfo :: FileOrNumericHost
• resolvTimeout :: Int

  Timeout in micro seconds.

• resolvRetry :: Int

  The number of retries including the first try.

• resolvBufsize :: Integer

  This field was obsoleted.

defaultResolvConf :: ResolvConf

Return a default ResolvConf:

• resolvInfo is RCFilePath "/etc/resolv.conf".
• resolvTimeout is 3,000,000 micro seconds.
• resolvRetry is 3.
• resolvBufsize is 512. (obsoleted)

Example (use Google's public DNS cache instead of resolv.conf):

>>> let cache = RCHostName "8.8.8.8"
>>> let rc = defaultResolvConf { resolvInfo = cache }

Intermediate data type for resolver

data ResolvSeed

Abstract data type of DNS Resolver seed. When implementing a DNS cache, this should be re-used.

makeResolvSeed :: ResolvConf -> IO ResolvSeed

Make a ResolvSeed from a ResolvConf.

Examples:

>>> rs <- makeResolvSeed defaultResolvConf

Type and function for resolver

data Resolver

Abstract data type of DNS Resolver When implementing a DNS cache, this MUST NOT be re-used.

Constructors

Resolver

Fields

• genId :: IO Int
• dnsSock :: Socket
• dnsTimeout :: Int
• dnsRetry :: Int
• dnsBufsize :: Integer

withResolver :: ResolvSeed -> (Resolver -> IO a) -> IO a

Giving a thread-safe Resolver to the function of the second argument. A socket for UDP is opened inside and is surely closed. Multiple withResolvers can be used concurrently. Multiple lookups must be done sequentially with a given Resolver. If multiple Resolvers are necessary for concurrent purpose, use withResolvers.

withResolvers :: [ResolvSeed] -> ([Resolver] -> IO a) -> IO a

Giving thread-safe Resolvers to the function of the second argument. Sockets for UDP are opened inside and are surely closed. For each Resolver, multiple lookups must be done sequentially. Resolvers can be used concurrently.

Looking up functions

lookup :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RData])

Look up resource records for a domain, collecting the results from the ANSWER section of the response.

We repeat an example from Network.DNS.Lookup:

>>> let hostname = Data.ByteString.Char8.pack "www.example.com"
>>> rs <- makeResolvSeed defaultResolvConf
>>> withResolver rs $ \resolver -> lookup resolver hostname A
Right [93.184.216.34]

lookupAuth :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RData])

Look up resource records for a domain, collecting the results from the AUTHORITY section of the response.

Raw looking up function

lookupRaw :: Resolver -> Domain -> TYPE -> IO (Either DNSError DNSMessage)

Look up a name and return the entire DNS Response. If the initial UDP query elicits a truncated answer, the query is retried over TCP. The TCP retry may extend the total time taken by one more timeout beyond timeout * tries.

Sample output is included below, however it is not tested the sequence number is unpredictable (it has to be!).

The example code:

  let hostname = Data.ByteString.Char8.pack "www.example.com"
  rs <- makeResolvSeed defaultResolvConf
  withResolver rs $ resolver -> lookupRaw resolver hostname A
  

And the (formatted) expected output:

  Right (DNSMessage
          { header = DNSHeader
                       { identifier = 1,
                         flags = DNSFlags
                                   { qOrR = QR_Response,
                                     opcode = OP_STD,
                                     authAnswer = False,
                                     trunCation = False,
                                     recDesired = True,
                                     recAvailable = True,
                                     rcode = NoErr,
                                     authenData = False
                                   },
                       },
            question = [Question { qname = "www.example.com.",
                                   qtype = A}],
            answer = [ResourceRecord {rrname = "www.example.com.",
                                      rrtype = A,
                                      rrttl = 800,
                                      rdlen = 4,
                                      rdata = 93.184.216.119}],
            authority = [],
            additional = []})
 

lookupRawAD :: Resolver -> Domain -> TYPE -> IO (Either DNSError DNSMessage)

Same as lookupRaw, but the query sets the AD bit, which solicits the the authentication status in the server reply. In most applications (other than diagnostic tools) that want authenticated data It is unwise to trust the AD bit in the responses of non-local servers, this interface should in most cases only be used with a loopback resolver.

fromDNSMessage :: DNSMessage -> (DNSMessage -> a) -> Either DNSError a

Extract necessary information from DNSMessage

fromDNSFormat :: DNSMessage -> (DNSMessage -> a) -> Either DNSError a

For backward compatibility.