lwres revision 0c27b3fe77ac1d5094ba3521e8142d9e7973133f
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCopyright (C) 2000, 2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark AndrewsThis Source Code Form is subject to the terms of the Mozilla Public
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinLicense, v. 2.0. If a copy of the MPL was not distributed with this
4a14ce5ba00ab7bc55c99ffdcf59c7a4ab902721Automatic Updaterfile, You can obtain one at http://mozilla.org/MPL/2.0/.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein$Id: lwres,v 1.6 2004/03/05 05:04:46 marka Exp $
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThis document describes the bind v9 lightweight resolver.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCurrently, applications make queries directly to a DNS server. With
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinv4 records (A records) the client can typically do the proper DNS work
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinto get a hostname into an address or vice versa.
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic UpdaterWith ipv6 and A6 recods, however, this becomes harder. Add to that
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinDNAME and CNAME and DNSSEC, and a client is quickly overwhelmed.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinTo keep clients from having to make direct DNS queries for address
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeininformation, an API was developed to allow clients to ask high-level
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrewsinformation, such as "what addresses does foo.nominum.com have?" and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein"what name does 1.2.3.4 have?"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinGENERAL DESIGN
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe lwres library converts structures into wire-format packets for
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeintransmission, and unmarshalls them on receive.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinMarshalling and unmarshalling:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinEach structure will have two functions defined, one to take a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwire-format packet and convert it into a structure, and another to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeintake a structure and convert it into a wire-format packet. There
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinis a structure cleanup function that will take the unmarshalled
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinstructure and free any dynamically allocated elements.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinWire formats:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinAll integer values are in network byte order.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinAll addresses are in network byte order. That is, they are directly
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinusable and do not need to be byte swapped, at least for ipv4 and ipv6.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinAll character strings are prefixed with a length, and are NUL
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic Updaterterminated C strings. This is a concession for structure handling on
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthe receive side, and allows a mapping structure to point to data
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeincontained in the actual receive buffer, eliminating copying.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNOOP (aka ping) packet format (request, response):
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic Updater lwres_lwpacket_t header;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein isc_uint16_t datalength;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein < datalength bytes >
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic UpdaterThe server simply returns the entire data region in the reply. This
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinallows the client to determine if the server is operational.
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic UpdaterGETADDRSBYNAME (response):
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_lwpacket_t header;
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic Updater isc_uint16_t naliases;
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic Updater isc_uint16_t naddrs;
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic Updater isc_uint16_t real_name_len;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein < real_name_len bytes of name >
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein isc_uint8_t \0
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein < naliases of
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein isc_uint16_t len;
a1ad6695ed6f988406cf155aa26376f84f73bcb9Automatic Updater < len bytes of name >
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic Updater isc_uint8_t \0
2895f101b5585a19015ac2c2c1e1812ac467fa12Automatic Updater isc_uint32_t family;
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic Updater isc_uint16_t len;
44d0f0256fbdce130a18655023c3b06bacacbd61Automatic Updater < len bytes of address >
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinGETNAMEBYADDR (response):
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic Updater lwres_lwpacket_t header;
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic Updater isc_uint16_t naliases;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein isc_uint16_t real_name_len;
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic Updater < real_name_len bytes of name >
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein isc_uint8_t \0
dcfda24abf565c442d058cbf81b2180d847a1b3eAutomatic Updater isc_uint16_t len;
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews < len bytes of name >
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein isc_uint8_t \0
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinFUNCTIONS PROVIDED
71c66a876ecca77923638d3f94cc0783152b2f03Mark AndrewsThe lwres library provides three functions per data item. One takes a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinstructure and marshalls it into a buffer. Another unmarshalls that
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrewsdata into a structure. A third frees memory used to unmarshall the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThere are two structures used in a typical request/response. The
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrewsbasic sequence is for the client to marshall the request into a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinbuffer and to transmit the request to the server. The server will
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinunmarshall the request, process it, and fill in a structure with the
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrewsresponse. The response is marshalled by the server, transmitted to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthe client, where it is unmarshalled and used by the client.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCLIENT CONTEXT
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinEach client instance has its own state that is created and maintained
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthrough library calls. Each thread needs its own client context, or
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrewslocking must be provided by the client to ensure private access to the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinstructure while lwres_*() calls are in progress.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinWhen a client context is created, /etc/resolv.conf is read to find
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinvarious options, including search lists, sort lists, etc.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe simpliest interface is to call lwres_getaddrsbyname() or
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_getnamebyaddr(), both of which are blocking calls. That is, a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinpacket is transmitted to the local lightweight resolver, and the call
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwill not return until a response is received or the timeout period
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinIf a caller requires non-blocking operation, the caller must call the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlower-level marshalling and unmarshalling functions directly. See the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinsource code implementing the blocking calls for more information, in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinLIBC INTEGRATION
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinSeveral sample implementations for gethostbyname() etc. are provided
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinin the lib/lwres/ directory. These are considered to be examples
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinonly. They have been merged into a local copy of NetBSD's libc, but
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthey are not drop-in replacements for most operating systems. They do
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnot provide NIS support or /etc/hosts support.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe daemon (in bin/lwresd/) implements name->address and address->name
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinresolution using the bind9 dns library functions. Currently, it will
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinread /etc/resolv.conf and use any "nameserver" lines as forwarders.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinIf none are listed it will become a full resolver itself, and not use
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsany forwarders.