883N/ACopyright (C) 2000, 2001 Internet Software Consortium.
883N/A$Id: lwres,v 1.5 2001/01/09 21:46:46 bwelling Exp $
883N/AThis document describes the bind v9 lightweight resolver.
883N/ACurrently, applications make queries directly to a DNS server. With
883N/Av4 records (A records) the client can typically do the proper DNS work
883N/Ato get a hostname into an address or vice versa.
883N/AWith ipv6 and A6 recods, however, this becomes harder. Add to that
883N/ADNAME and CNAME and DNSSEC, and a client is quickly overwhelmed.
883N/ATo keep clients from having to make direct DNS queries for address
883N/Ainformation, an API was developed to allow clients to ask high-level
883N/A"what name does 1.2.3.4 have?"
883N/AThe lwres library converts structures into wire-format packets for
883N/Atransmission, and unmarshalls them on receive.
883N/AMarshalling and unmarshalling:
883N/AEach structure will have two functions defined, one to take a
883N/Awire-format packet and convert it into a structure, and another to
883N/Atake a structure and convert it into a wire-format packet. There
883N/Ais a structure cleanup function that will take the unmarshalled
883N/Astructure and free any dynamically allocated elements.
883N/AAll integer values are in network byte order.
883N/AAll addresses are in network byte order. That is, they are directly
883N/Ausable and do not need to be byte swapped, at least for ipv4 and ipv6.
883N/AAll character strings are prefixed with a length, and are NUL
883N/Aterminated C strings. This is a concession for structure handling on
883N/Athe receive side, and allows a mapping structure to point to data
883N/Acontained in the actual receive buffer, eliminating copying.
883N/ANOOP (aka ping) packet format (request, response):
883N/A lwres_lwpacket_t header;
883N/A isc_uint16_t datalength;
883N/AThe server simply returns the entire data region in the reply. This
883N/Aallows the client to determine if the server is operational.
883N/AGETADDRSBYNAME (response):
883N/A lwres_lwpacket_t header;
883N/A isc_uint16_t real_name_len;
883N/A < real_name_len bytes of name >
883N/A < len bytes of address >
883N/AGETNAMEBYADDR (response):
883N/A lwres_lwpacket_t header;
883N/A isc_uint16_t real_name_len;
883N/A < real_name_len bytes of name >
883N/AThe lwres library provides three functions per data item. One takes a
883N/Astructure and marshalls it into a buffer. Another unmarshalls that
883N/Adata into a structure. A third frees memory used to unmarshall the
883N/Abasic sequence is for the client to marshall the request into a
883N/Abuffer and to transmit the request to the server. The server will
883N/Aunmarshall the request, process it, and fill in a structure with the
883N/Aresponse. The response is marshalled by the server, transmitted to
883N/Athe client, where it is unmarshalled and used by the client.
883N/AEach client instance has its own state that is created and maintained
883N/Athrough library calls. Each thread needs its own client context, or
883N/Alocking must be provided by the client to ensure private access to the
883N/Astructure while lwres_*() calls are in progress.
883N/Avarious options, including search lists, sort lists, etc.
883N/AThe simpliest interface is to call lwres_getaddrsbyname() or
883N/Alwres_getnamebyaddr(), both of which are blocking calls. That is, a
883N/Apacket is transmitted to the local lightweight resolver, and the call
883N/Awill not return until a response is received or the timeout period
883N/AIf a caller requires non-blocking operation, the caller must call the
883N/Alower-level marshalling and unmarshalling functions directly. See the
883N/Asource code implementing the blocking calls for more information, in
883N/ASeveral sample implementations for gethostbyname() etc. are provided
883N/Aonly. They have been merged into a local copy of NetBSD's libc, but
883N/Athey are not drop-in replacements for most operating systems. They do
883N/Aresolution using the bind9 dns library functions. Currently, it will
883N/AIf none are listed it will become a full resolver itself, and not use