0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCopyright (C) 2000, 2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsThis Source Code Form is subject to the terms of the Mozilla Public
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsLicense, v. 2.0. If a copy of the MPL was not distributed with this
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsfile, You can obtain one at http://mozilla.org/MPL/2.0/.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews$Id: lwres,v 1.6 2004/03/05 05:04:46 marka Exp $
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffThis document describes the bind v9 lightweight resolver.
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffCurrently, applications make queries directly to a DNS server. With
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffv4 records (A records) the client can typically do the proper DNS work
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffto get a hostname into an address or vice versa.
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffWith ipv6 and A6 recods, however, this becomes harder. Add to that
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffDNAME and CNAME and DNSSEC, and a client is quickly overwhelmed.
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffTo keep clients from having to make direct DNS queries for address
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffinformation, an API was developed to allow clients to ask high-level
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffinformation, such as "what addresses does foo.nominum.com have?" and
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graff"what name does 1.2.3.4 have?"
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffGENERAL DESIGN
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael GraffThe lwres library converts structures into wire-format packets for
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Grafftransmission, and unmarshalls them on receive.
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael GraffMarshalling and unmarshalling:
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael GraffEach structure will have two functions defined, one to take a
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graffwire-format packet and convert it into a structure, and another to
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Grafftake a structure and convert it into a wire-format packet. There
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graffis a structure cleanup function that will take the unmarshalled
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graffstructure and free any dynamically allocated elements.
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael GraffAll integer values are in network byte order.
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael GraffAll addresses are in network byte order. That is, they are directly
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graffusable and do not need to be byte swapped, at least for ipv4 and ipv6.
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael GraffAll character strings are prefixed with a length, and are NUL
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graffterminated C strings. This is a concession for structure handling on
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graffthe receive side, and allows a mapping structure to point to data
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graffcontained in the actual receive buffer, eliminating copying.
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffNOOP (aka ping) packet format (request, response):
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff lwres_lwpacket_t header;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint16_t datalength;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff < datalength bytes >
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael GraffThe server simply returns the entire data region in the reply. This
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graffallows the client to determine if the server is operational.
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffGETADDRSBYNAME (response):
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff lwres_lwpacket_t header;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint16_t naliases;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint16_t naddrs;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint16_t real_name_len;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff < real_name_len bytes of name >
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint8_t \0
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff < naliases of
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint16_t len;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff < len bytes of name >
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint8_t \0
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint32_t family;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint16_t len;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff < len bytes of address >
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffGETNAMEBYADDR (response):
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff lwres_lwpacket_t header;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint16_t naliases;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint16_t real_name_len;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff < real_name_len bytes of name >
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint8_t \0
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff < naliases of
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint16_t len;
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff < len bytes of name >
2358fd9353e91bc2291c165a679af9b3a1b7fb3aMichael Graff isc_uint8_t \0
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffFUNCTIONS PROVIDED
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffThe lwres library provides three functions per data item. One takes a
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffstructure and marshalls it into a buffer. Another unmarshalls that
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffdata into a structure. A third frees memory used to unmarshall the
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffThere are two structures used in a typical request/response. The
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffbasic sequence is for the client to marshall the request into a
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffbuffer and to transmit the request to the server. The server will
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffunmarshall the request, process it, and fill in a structure with the
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffresponse. The response is marshalled by the server, transmitted to
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffthe client, where it is unmarshalled and used by the client.
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffCLIENT CONTEXT
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffEach client instance has its own state that is created and maintained
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffthrough library calls. Each thread needs its own client context, or
0982a13bcfef0d9a443248bcf929042b460613a9Michael Grafflocking must be provided by the client to ensure private access to the
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffstructure while lwres_*() calls are in progress.
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffWhen a client context is created, /etc/resolv.conf is read to find
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffvarious options, including search lists, sort lists, etc.
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffThe simpliest interface is to call lwres_getaddrsbyname() or
0982a13bcfef0d9a443248bcf929042b460613a9Michael Grafflwres_getnamebyaddr(), both of which are blocking calls. That is, a
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffpacket is transmitted to the local lightweight resolver, and the call
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffwill not return until a response is received or the timeout period
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffIf a caller requires non-blocking operation, the caller must call the
0982a13bcfef0d9a443248bcf929042b460613a9Michael Grafflower-level marshalling and unmarshalling functions directly. See the
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffsource code implementing the blocking calls for more information, in
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffLIBC INTEGRATION
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffSeveral sample implementations for gethostbyname() etc. are provided
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffin the lib/lwres/ directory. These are considered to be examples
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffonly. They have been merged into a local copy of NetBSD's libc, but
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffthey are not drop-in replacements for most operating systems. They do
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffnot provide NIS support or /etc/hosts support.
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffThe daemon (in bin/lwresd/) implements name->address and address->name
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffresolution using the bind9 dns library functions. Currently, it will
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffread /etc/resolv.conf and use any "nameserver" lines as forwarders.
0982a13bcfef0d9a443248bcf929042b460613a9Michael GraffIf none are listed it will become a full resolver itself, and not use
0982a13bcfef0d9a443248bcf929042b460613a9Michael Graffany forwarders.