doc/design/lwres

   1 Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 Copyright (C) 2000, 2001  Internet Software Consortium.
   3 See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
   4
   5 $Id: lwres,v 1.6 2004/03/05 05:04:46 marka Exp $
   6
   7 This document describes the bind v9 lightweight resolver.
   8
   9 WHY LWRES?
  10
  11 Currently, applications make queries directly to a DNS server.  With
  12 v4 records (A records) the client can typically do the proper DNS work
  13 to get a hostname into an address or vice versa.
  14
  15 With ipv6 and A6 recods, however, this becomes harder.  Add to that
  16 DNAME and CNAME and DNSSEC, and a client is quickly overwhelmed.
  17
  18 To keep clients from having to make direct DNS queries for address
  19 information, an API was developed to allow clients to ask high-level
  20 information, such as "what addresses does foo.nominum.com have?" and
  21 "what name does 1.2.3.4 have?"
  22
  23
  24
  25 GENERAL DESIGN
  26
  27 The lwres library converts structures into wire-format packets for
  28 transmission, and unmarshalls them on receive.
  29
  30
  31
  32 Marshalling and unmarshalling:
  33
  34 Each structure will have two functions defined, one to take a
  35 wire-format packet and convert it into a structure, and another to
  36 take a structure and convert it into a wire-format packet.  There
  37 is a structure cleanup function that will take the unmarshalled
  38 structure and free any dynamically allocated elements.
  39
  40
  41 Wire formats:
  42
  43 All integer values are in network byte order.
  44
  45 All addresses are in network byte order.  That is, they are directly
  46 usable and do not need to be byte swapped, at least for ipv4 and ipv6.
  47
  48 All character strings are prefixed with a length, and are NUL
  49 terminated C strings.  This is a concession for structure handling on
  50 the receive side, and allows a mapping structure to point to data
  51 contained in the actual receive buffer, eliminating copying.
  52
  53
  54 NOOP (aka ping) packet format (request, response):
  55
  56         lwres_lwpacket_t header;
  57         isc_uint16_t datalength;
  58         < datalength bytes >
  59
  60 The server simply returns the entire data region in the reply.  This
  61 allows the client to determine if the server is operational.
  62
  63
  64 GETADDRSBYNAME (response):
  65
  66         lwres_lwpacket_t header;
  67
  68         isc_uint16_t naliases;
  69
  70         isc_uint16_t naddrs;
  71
  72         isc_uint16_t real_name_len;
  73         < real_name_len bytes of name >
  74         isc_uint8_t \0
  75
  76         < naliases of
  77                 isc_uint16_t len;
  78                 < len bytes of name >
  79                 isc_uint8_t \0
  80         >
  81
  82         < naddrs of
  83                 isc_uint32_t family;
  84                 isc_uint16_t len;
  85                 < len bytes of address >
  86         >
  87
  88
  89 GETNAMEBYADDR (response):
  90
  91         lwres_lwpacket_t header;
  92
  93         isc_uint16_t naliases;
  94
  95         isc_uint16_t real_name_len;
  96         < real_name_len bytes of name >
  97         isc_uint8_t \0
  98
  99         < naliases of
 100                 isc_uint16_t len;
 101                 < len bytes of name >
 102                 isc_uint8_t \0
 103         >
 104
 105
 106
 107 FUNCTIONS PROVIDED
 108
 109 The lwres library provides three functions per data item.  One takes a
 110 structure and marshalls it into a buffer.  Another unmarshalls that
 111 data into a structure.  A third frees memory used to unmarshall the
 112 data.
 113
 114 There are two structures used in a typical request/response.  The
 115 basic sequence is for the client to marshall the request into a
 116 buffer and to transmit the request to the server.  The server will
 117 unmarshall the request, process it, and fill in a structure with the
 118 response.  The response is marshalled by the server, transmitted to
 119 the client, where it is unmarshalled and used by the client.
 120
 121
 122
 123 CLIENT CONTEXT
 124
 125 Each client instance has its own state that is created and maintained
 126 through library calls.  Each thread needs its own client context, or
 127 locking must be provided by the client to ensure private access to the
 128 structure while lwres_*() calls are in progress.
 129
 130 When a client context is created, /etc/resolv.conf is read to find
 131 various options, including search lists, sort lists, etc.
 132
 133
 134
 135 API
 136
 137 The simpliest interface is to call lwres_getaddrsbyname() or
 138 lwres_getnamebyaddr(), both of which are blocking calls.  That is, a
 139 packet is transmitted to the local lightweight resolver, and the call
 140 will not return until a response is received or the timeout period
 141 expires.
 142
 143 If a caller requires non-blocking operation, the caller must call the
 144 lower-level marshalling and unmarshalling functions directly.  See the
 145 source code implementing the blocking calls for more information, in
 146 lib/lwres/lwresutil.c.
 147
 148
 149
 150 LIBC INTEGRATION
 151
 152 Several sample implementations for gethostbyname() etc. are provided
 153 in the lib/lwres/ directory.  These are considered to be examples
 154 only.  They have been merged into a local copy of NetBSD's libc, but
 155 they are not drop-in replacements for most operating systems.  They do
 156 not provide NIS support or /etc/hosts support.
 157
 158
 159
 160 LWRES DAEMON
 161
 162 The daemon (in bin/lwresd/) implements name->address and address->name
 163 resolution using the bind9 dns library functions.  Currently, it will
 164 read /etc/resolv.conf and use any "nameserver" lines as forwarders.
 165 If none are listed it will become a full resolver itself, and not use
 166 any forwarders.