lwres.html revision 4abdfc917e6635a7c81d1f931a0c79227e72d025
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
8001ba81cb851b38d86650a2fef5817facffb763johanengelen - Copyright (C) 2000, 2001 Internet Software Consortium.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen - Permission to use, copy, modify, and distribute this software for any
8001ba81cb851b38d86650a2fef5817facffb763johanengelen - purpose with or without fee is hereby granted, provided that the above
98a704c566ce5a750d76d5fc9675ccc804ac65f5johanengelen - copyright notice and this permission notice appear in all copies.
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
98a704c566ce5a750d76d5fc9675ccc804ac65f5johanengelen - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
01d27eab5fca2dcb8e883011f8be77ae6b78a11cTed Gould - PERFORMANCE OF THIS SOFTWARE.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen<!-- $Id: lwres.html,v 1.22 2007/01/26 23:29:04 marka Exp $ -->
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen<a name="id2476275"></a><div class="titlepage"></div>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen<p>lwres — introduction to the lightweight resolver library</p>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen<div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre></div>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen The BIND 9 lightweight resolver library is a simple, name service
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen independent stub resolver library. It provides hostname-to-address
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen and address-to-hostname lookup services to applications by
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen transmitting lookup requests to a resolver daemon
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <span><strong class="command">lwresd</strong></span>
d37634d73670180f99a3e0ea583621373d90ec4fJohan Engelen running on the local host. The resover daemon performs the
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen lookup using the DNS or possibly other name service protocols,
d37634d73670180f99a3e0ea583621373d90ec4fJohan Engelen and returns the results to the application through the library.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen The library and resolver daemon communicate using a simple
d37634d73670180f99a3e0ea583621373d90ec4fJohan Engelen UDP-based protocol.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen The lwresd library implements multiple name service APIs.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <code class="function">gethostbyname_r()</code>,
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <code class="function">gethostbyaddr_r()</code>,
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <code class="function">getipnodebyname()</code>,
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <code class="function">getipnodebyaddr()</code>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen functions are all supported. To allow the lwres library to coexist
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen with system libraries that define functions of the same name,
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen the library defines these functions with names prefixed by
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen To define the standard names, applications must include the
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <code class="filename"><lwres/netdb.h></code>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen which contains macro definitions mapping the standard function names
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen prefixed ones. Operating system vendors who integrate the lwres
ea8dd7683dd12883474f6cf9b5f424f8ed831166Kris library into their base distributions should rename the functions
ea8dd7683dd12883474f6cf9b5f424f8ed831166Kris in the library proper so that the renaming macros are not needed.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen The library also provides a native API consisting of the functions
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <code class="function">lwres_getaddrsbyname()</code>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <code class="function">lwres_getnamebyaddr()</code>.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen These may be called by applications that require more detailed
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen control over the lookup process than the standard functions
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen In addition to these name service independent address lookup
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen functions, the library implements a new, experimental API
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen for looking up arbitrary DNS resource records, using the
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <code class="function">lwres_getaddrsbyname()</code>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen Finally, there is a low-level API for converting lookup
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen requests and responses to and from raw lwres protocol packets.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen This API can be used by clients requiring nonblocking operation,
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen and is also used when implementing the server side of the lwres
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen protocol, for example in the
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <span><strong class="command">lwresd</strong></span>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen resolver daemon. The use of this low-level API in clients
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen and servers is outlined in the following sections.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen<a name="id2543421"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen When a client program wishes to make an lwres request using the
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen native low-level API, it typically performs the following
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen sequence of actions.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen (1) Allocate or use an existing <span class="type">lwres_packet_t</span>,
ed0798e33e14e86b60f8cd254d7131f9d83ba8c0johanengelen (2) Set <em class="structfield"><code>pkt.recvlength</code></em> to the maximum length
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen we will accept.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen This is done so the receiver of our packets knows how large our receive
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen buffer is. The "default" is a constant in
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen (3) Set <em class="structfield"><code>pkt.serial</code></em>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen to a unique serial number. This value is echoed
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen back to the application by the remote server.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen (4) Set <em class="structfield"><code>pkt.pktflags</code></em>. Usually this is set to
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen (5) Set <em class="structfield"><code>pkt.result</code></em> to 0.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen (6) Call <code class="function">lwres_*request_render()</code>,
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen or marshall in the data using the primitives
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen such as <code class="function">lwres_packet_render()</code>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen and storing the packet data.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen (7) Transmit the resulting buffer.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen (8) Call <code class="function">lwres_*response_parse()</code>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen to parse any packets received.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen (9) Verify that the opcode and serial match a request, and process the
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen packet specific information contained in the body.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen<a name="id2543570"></a><h2>SERVER-SIDE LOW-LEVEL API CALL FLOW</h2>
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen When implementing the server side of the lightweight resolver
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen protocol using the lwres library, a sequence of actions like the
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen following is typically involved in processing each request packet.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen Note that the same <span class="type">lwres_packet_t</span> is used
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen in both the <code class="function">_parse()</code> and <code class="function">_render()</code> calls,
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen with only a few modifications made
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen to the packet header's contents between uses. This method is
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen as it keeps the serial, opcode, and other fields correct.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen (1) When a packet is received, call <code class="function">lwres_*request_parse()</code> to
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen unmarshall it. This returns a <span class="type">lwres_packet_t</span> (also called <code class="varname">pkt</code>, below)
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen as well as a data specific type, such as <span class="type">lwres_gabnrequest_t</span>.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen (2) Process the request in the data specific type.
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen (3) Set the <em class="structfield"><code>pkt.result</code></em>,
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <em class="structfield"><code>pkt.recvlength</code></em> as above. All other fields
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen be left untouched since they were filled in by the <code class="function">*_parse()</code> call
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen above. If using <code class="function">lwres_*response_render()</code>,
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen <em class="structfield"><code>pkt.pktflags</code></em> will be set up
29684a16b6c92bee28a94fdc2607bcc143950fa8johanengelen properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen (4) Call the data specific rendering function, such as
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen <code class="function">lwres_gabnresponse_render()</code>.
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen (5) Send the resulting packet to the client.
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen<p><span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>,
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>,
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>,
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen <span class="citerefentry"><span class="refentrytitle">lwres_noop</span>(3)</span>,
c3a8ad9235ff81909bd472707550aef5b91daf7bjohanengelen <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>,
98a704c566ce5a750d76d5fc9675ccc804ac65f5johanengelen <span class="citerefentry"><span class="refentrytitle">lwres_gnba</span>(3)</span>,
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen <span class="citerefentry"><span class="refentrytitle">lwres_context</span>(3)</span>,
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen <span class="citerefentry"><span class="refentrytitle">lwres_config</span>(3)</span>,
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>,
1f37e9d97c3bb8cf02b2cc80af8dcfc9aba7c7b4johanengelen <span class="citerefentry"><span class="refentrytitle">lwresd</span>(8)</span>.