lwres.html revision 5347c0fcb04eaea19d9f39795646239f487c6207
c63ebf815c8a874525cf18670ad74847f7fc7b26Christian Maeder - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - This Source Code Form is subject to the terms of the Mozilla Public
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder - License, v. 2.0. If a copy of the MPL was not distributed with this
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - file, You can obtain one at http://mozilla.org/MPL/2.0/.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
c9a7e6af169a2adfb92f42331cd578065ed83a2bChristian Maeder<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
e7757995211bd395dc79d26fe017d99375f7d2a6Christian Maeder<a name="id-1"></a><div class="titlepage"></div>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<p>lwres — introduction to the lightweight resolver library</p>
b1f59a4ea7c96f4c03a4d7cfcb9c5e66871cfbbbChristian Maeder<div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre></div>
3e8b136f23ed57d40ee617f49bcac37830b58cabChristian Maeder The BIND 9 lightweight resolver library is a simple, name service
ef9e8535c168d3f774d9e74368a2317a9eda5826Christian Maeder independent stub resolver library. It provides hostname-to-address
bab2d88d650448628730ed3b65c9f99c52500e8cChristian Maeder and address-to-hostname lookup services to applications by
3e8b136f23ed57d40ee617f49bcac37830b58cabChristian Maeder transmitting lookup requests to a resolver daemon
ef9e8535c168d3f774d9e74368a2317a9eda5826Christian Maeder <span class="command"><strong>lwresd</strong></span>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder running on the local host. The resolver daemon performs the
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder lookup using the DNS or possibly other name service protocols,
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder and returns the results to the application through the library.
8b767d09a78927b111f5596fdff9ca7d2c1a439fChristian Maeder The library and resolver daemon communicate using a simple
8b767d09a78927b111f5596fdff9ca7d2c1a439fChristian Maeder UDP-based protocol.
d54cd08a4cfa26256c38d8ed12c343adbfe1a0e3Christian Maeder The lwresd library implements multiple name service APIs.
bab2d88d650448628730ed3b65c9f99c52500e8cChristian Maeder <code class="function">gethostbyname()</code>,
ed1b8e97e72b2e3e92edaf2eb22a4b5373d705f1Felix Gabriel Mance <code class="function">gethostbyaddr()</code>,
8cacad2a09782249243b80985f28e9387019fe40Christian Maeder <code class="function">gethostbyname_r()</code>,
6a2dad705deefd1b7a7e09b84fd2d75f2213be47Christian Maeder <code class="function">gethostbyaddr_r()</code>,
a7c27282e71cf4505026645f96d4f5cb8a284e32Christian Maeder <code class="function">getaddrinfo()</code>,
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder <code class="function">getipnodebyname()</code>,
f04e8f3ff56405901be968fd4c6e9769239f1a9bKlaus Luettich <code class="function">getipnodebyaddr()</code>
6aea82c63ba1d2efc0329bc784a14e521469ec20Christian Maeder functions are all supported. To allow the lwres library to coexist
4ba08bfca0cc8d9da65397b8dfd2654fdb4c0e62Christian Maeder with system libraries that define functions of the same name,
feca1d35123d8c31aee238c9ce79947b0bf65494Christian Maeder the library defines these functions with names prefixed by
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder To define the standard names, applications must include the
db675e8302ddb0d6528088ce68f5e98a00e890e3Christian Maeder <code class="filename"><lwres/netdb.h></code>
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder which contains macro definitions mapping the standard function names
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder prefixed ones. Operating system vendors who integrate the lwres
23ffcc44ca8612feccbd8fda63fa5be7ab5f9dc3Christian Maeder library into their base distributions should rename the functions
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder in the library proper so that the renaming macros are not needed.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder The library also provides a native API consisting of the functions
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="function">lwres_getaddrsbyname()</code>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="function">lwres_getnamebyaddr()</code>.
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder These may be called by applications that require more detailed
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder control over the lookup process than the standard functions
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder In addition to these name service independent address lookup
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder functions, the library implements a new, experimental API
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder for looking up arbitrary DNS resource records, using the
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder <code class="function">lwres_getaddrsbyname()</code>
b568982efd0997d877286faa592d81b03c8c67b8Christian Maeder Finally, there is a low-level API for converting lookup
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder requests and responses to and from raw lwres protocol packets.
0be0db405c49906bd7057255069bf6df53395ac9Klaus Luettich This API can be used by clients requiring nonblocking operation,
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder and is also used when implementing the server side of the lwres
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder protocol, for example in the
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <span class="command"><strong>lwresd</strong></span>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder resolver daemon. The use of this low-level API in clients
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder and servers is outlined in the following sections.
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder<a name="id-1.9"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder When a client program wishes to make an lwres request using the
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder native low-level API, it typically performs the following
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder sequence of actions.
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder (1) Allocate or use an existing <span class="type">lwres_packet_t</span>,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder called <code class="varname">pkt</code> below.
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder (2) Set <code class="varname">pkt.recvlength</code> to the maximum length
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder we will accept.
3e8b136f23ed57d40ee617f49bcac37830b58cabChristian Maeder This is done so the receiver of our packets knows how large our receive
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder buffer is. The "default" is a constant in
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder <code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>.
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder (3) Set <code class="varname">pkt.serial</code>
e4f4d096e5e6d60dd91c746d0e833d0ac7a29c50Christian Maeder to a unique serial number. This value is echoed
eb74267cf39e4e95f9eeb5c765f4c8dac33971b4Christian Maeder back to the application by the remote server.
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder (4) Set <code class="varname">pkt.pktflags</code>. Usually this is set to
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder (5) Set <code class="varname">pkt.result</code> to 0.
6cd33d6101fb1b93baa6d86fac158af18a115108Christian Maeder (6) Call <code class="function">lwres_*request_render()</code>,
6cd33d6101fb1b93baa6d86fac158af18a115108Christian Maeder or marshall in the data using the primitives
6cd33d6101fb1b93baa6d86fac158af18a115108Christian Maeder such as <code class="function">lwres_packet_render()</code>
b2ac5a92cf36382e8deea5661c1964566caf72b3Christian Maeder and storing the packet data.
b2ac5a92cf36382e8deea5661c1964566caf72b3Christian Maeder (7) Transmit the resulting buffer.
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder (8) Call <code class="function">lwres_*response_parse()</code>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder to parse any packets received.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder (9) Verify that the opcode and serial match a request, and process the
f1a913f880e409e7327b5deae95738b5448379a1Christian Maeder packet specific information contained in the body.
14c56dc499da4bbeaeebeb558ceb755150ae341cChristian Maeder<a name="id-1.10"></a><h2>SERVER-SIDE LOW-LEVEL API CALL FLOW</h2>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder When implementing the server side of the lightweight resolver
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder protocol using the lwres library, a sequence of actions like the
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder following is typically involved in processing each request packet.
93f5b72fdb9ee734caa750b43dd79bbb590dcd73Christian Maeder Note that the same <span class="type">lwres_packet_t</span> is used
93f5b72fdb9ee734caa750b43dd79bbb590dcd73Christian Maeder in both the <code class="function">_parse()</code> and <code class="function">_render()</code> calls,
328a85c807f2a95c3f147d10b05927eaf862ebebChristian Maeder with only a few modifications made
308834907a120fd8771e18292ed2ca9cd767c12dChristian Maeder to the packet header's contents between uses. This method is
254df6f22d01eacf7c57b85729e0445747b630d9Christian Maeder as it keeps the serial, opcode, and other fields correct.
5b818f10e11fc79def1fdd5c8a080d64a6438d87Christian Maeder (1) When a packet is received, call <code class="function">lwres_*request_parse()</code> to
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers unmarshall it. This returns a <span class="type">lwres_packet_t</span> (also called <code class="varname">pkt</code>, below)
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder as well as a data specific type, such as <span class="type">lwres_gabnrequest_t</span>.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder (2) Process the request in the data specific type.
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maeder (3) Set the <code class="varname">pkt.result</code>,
aded505f9b42cc38975559c2a5d175ae95de436bChristian Maeder <code class="varname">pkt.recvlength</code> as above. All other fields
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers be left untouched since they were filled in by the <code class="function">*_parse()</code> call
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder above. If using <code class="function">lwres_*response_render()</code>,
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder <code class="varname">pkt.pktflags</code> will be set up
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder (4) Call the data specific rendering function, such as
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder <code class="function">lwres_gabnresponse_render()</code>.
aded505f9b42cc38975559c2a5d175ae95de436bChristian Maeder (5) Send the resulting packet to the client.
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder<p><span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>,
a14767aeac3e78ed100f5b75e210ba563ee10dbaChristian Maeder <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>,
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>,
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <span class="citerefentry"><span class="refentrytitle">lwres_noop</span>(3)</span>,
54ea981a0503c396c2923a1c06421c6235baf27fChristian Maeder <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>,
697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder <span class="citerefentry"><span class="refentrytitle">lwres_gnba</span>(3)</span>,
697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder <span class="citerefentry"><span class="refentrytitle">lwres_context</span>(3)</span>,
aded505f9b42cc38975559c2a5d175ae95de436bChristian Maeder <span class="citerefentry"><span class="refentrytitle">lwres_config</span>(3)</span>,
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>,
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder <span class="citerefentry"><span class="refentrytitle">lwresd</span>(8)</span>.