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