1*00b67f09SDavid van Moolenbroek<!-- 2*00b67f09SDavid van Moolenbroek - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC") 3*00b67f09SDavid van Moolenbroek - Copyright (C) 2000, 2001 Internet Software Consortium. 4*00b67f09SDavid van Moolenbroek - 5*00b67f09SDavid van Moolenbroek - Permission to use, copy, modify, and/or distribute this software for any 6*00b67f09SDavid van Moolenbroek - purpose with or without fee is hereby granted, provided that the above 7*00b67f09SDavid van Moolenbroek - copyright notice and this permission notice appear in all copies. 8*00b67f09SDavid van Moolenbroek - 9*00b67f09SDavid van Moolenbroek - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10*00b67f09SDavid van Moolenbroek - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11*00b67f09SDavid van Moolenbroek - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12*00b67f09SDavid van Moolenbroek - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13*00b67f09SDavid van Moolenbroek - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14*00b67f09SDavid van Moolenbroek - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15*00b67f09SDavid van Moolenbroek - PERFORMANCE OF THIS SOFTWARE. 16*00b67f09SDavid van Moolenbroek--> 17*00b67f09SDavid van Moolenbroek<!-- Id --> 18*00b67f09SDavid van Moolenbroek<html> 19*00b67f09SDavid van Moolenbroek<head> 20*00b67f09SDavid van Moolenbroek<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 21*00b67f09SDavid van Moolenbroek<title>lwres</title> 22*00b67f09SDavid van Moolenbroek<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> 23*00b67f09SDavid van Moolenbroek</head> 24*00b67f09SDavid van Moolenbroek<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> 25*00b67f09SDavid van Moolenbroek<a name="id2476275"></a><div class="titlepage"></div> 26*00b67f09SDavid van Moolenbroek<div class="refnamediv"> 27*00b67f09SDavid van Moolenbroek<h2>Name</h2> 28*00b67f09SDavid van Moolenbroek<p>lwres — introduction to the lightweight resolver library</p> 29*00b67f09SDavid van Moolenbroek</div> 30*00b67f09SDavid van Moolenbroek<div class="refsynopsisdiv"> 31*00b67f09SDavid van Moolenbroek<h2>Synopsis</h2> 32*00b67f09SDavid van Moolenbroek<div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre></div> 33*00b67f09SDavid van Moolenbroek</div> 34*00b67f09SDavid van Moolenbroek<div class="refsect1" lang="en"> 35*00b67f09SDavid van Moolenbroek<a name="id2543357"></a><h2>DESCRIPTION</h2> 36*00b67f09SDavid van Moolenbroek<p> 37*00b67f09SDavid van Moolenbroek The BIND 9 lightweight resolver library is a simple, name service 38*00b67f09SDavid van Moolenbroek independent stub resolver library. It provides hostname-to-address 39*00b67f09SDavid van Moolenbroek and address-to-hostname lookup services to applications by 40*00b67f09SDavid van Moolenbroek transmitting lookup requests to a resolver daemon 41*00b67f09SDavid van Moolenbroek <span><strong class="command">lwresd</strong></span> 42*00b67f09SDavid van Moolenbroek running on the local host. The resolver daemon performs the 43*00b67f09SDavid van Moolenbroek lookup using the DNS or possibly other name service protocols, 44*00b67f09SDavid van Moolenbroek and returns the results to the application through the library. 45*00b67f09SDavid van Moolenbroek The library and resolver daemon communicate using a simple 46*00b67f09SDavid van Moolenbroek UDP-based protocol. 47*00b67f09SDavid van Moolenbroek </p> 48*00b67f09SDavid van Moolenbroek</div> 49*00b67f09SDavid van Moolenbroek<div class="refsect1" lang="en"> 50*00b67f09SDavid van Moolenbroek<a name="id2543370"></a><h2>OVERVIEW</h2> 51*00b67f09SDavid van Moolenbroek<p> 52*00b67f09SDavid van Moolenbroek The lwresd library implements multiple name service APIs. 53*00b67f09SDavid van Moolenbroek The standard 54*00b67f09SDavid van Moolenbroek <code class="function">gethostbyname()</code>, 55*00b67f09SDavid van Moolenbroek <code class="function">gethostbyaddr()</code>, 56*00b67f09SDavid van Moolenbroek <code class="function">gethostbyname_r()</code>, 57*00b67f09SDavid van Moolenbroek <code class="function">gethostbyaddr_r()</code>, 58*00b67f09SDavid van Moolenbroek <code class="function">getaddrinfo()</code>, 59*00b67f09SDavid van Moolenbroek <code class="function">getipnodebyname()</code>, 60*00b67f09SDavid van Moolenbroek and 61*00b67f09SDavid van Moolenbroek <code class="function">getipnodebyaddr()</code> 62*00b67f09SDavid van Moolenbroek functions are all supported. To allow the lwres library to coexist 63*00b67f09SDavid van Moolenbroek with system libraries that define functions of the same name, 64*00b67f09SDavid van Moolenbroek the library defines these functions with names prefixed by 65*00b67f09SDavid van Moolenbroek <code class="literal">lwres_</code>. 66*00b67f09SDavid van Moolenbroek To define the standard names, applications must include the 67*00b67f09SDavid van Moolenbroek header file 68*00b67f09SDavid van Moolenbroek <code class="filename"><lwres/netdb.h></code> 69*00b67f09SDavid van Moolenbroek which contains macro definitions mapping the standard function names 70*00b67f09SDavid van Moolenbroek into 71*00b67f09SDavid van Moolenbroek <code class="literal">lwres_</code> 72*00b67f09SDavid van Moolenbroek prefixed ones. Operating system vendors who integrate the lwres 73*00b67f09SDavid van Moolenbroek library into their base distributions should rename the functions 74*00b67f09SDavid van Moolenbroek in the library proper so that the renaming macros are not needed. 75*00b67f09SDavid van Moolenbroek </p> 76*00b67f09SDavid van Moolenbroek<p> 77*00b67f09SDavid van Moolenbroek The library also provides a native API consisting of the functions 78*00b67f09SDavid van Moolenbroek <code class="function">lwres_getaddrsbyname()</code> 79*00b67f09SDavid van Moolenbroek and 80*00b67f09SDavid van Moolenbroek <code class="function">lwres_getnamebyaddr()</code>. 81*00b67f09SDavid van Moolenbroek These may be called by applications that require more detailed 82*00b67f09SDavid van Moolenbroek control over the lookup process than the standard functions 83*00b67f09SDavid van Moolenbroek provide. 84*00b67f09SDavid van Moolenbroek </p> 85*00b67f09SDavid van Moolenbroek<p> 86*00b67f09SDavid van Moolenbroek In addition to these name service independent address lookup 87*00b67f09SDavid van Moolenbroek functions, the library implements a new, experimental API 88*00b67f09SDavid van Moolenbroek for looking up arbitrary DNS resource records, using the 89*00b67f09SDavid van Moolenbroek <code class="function">lwres_getaddrsbyname()</code> 90*00b67f09SDavid van Moolenbroek function. 91*00b67f09SDavid van Moolenbroek </p> 92*00b67f09SDavid van Moolenbroek<p> 93*00b67f09SDavid van Moolenbroek Finally, there is a low-level API for converting lookup 94*00b67f09SDavid van Moolenbroek requests and responses to and from raw lwres protocol packets. 95*00b67f09SDavid van Moolenbroek This API can be used by clients requiring nonblocking operation, 96*00b67f09SDavid van Moolenbroek and is also used when implementing the server side of the lwres 97*00b67f09SDavid van Moolenbroek protocol, for example in the 98*00b67f09SDavid van Moolenbroek <span><strong class="command">lwresd</strong></span> 99*00b67f09SDavid van Moolenbroek resolver daemon. The use of this low-level API in clients 100*00b67f09SDavid van Moolenbroek and servers is outlined in the following sections. 101*00b67f09SDavid van Moolenbroek </p> 102*00b67f09SDavid van Moolenbroek</div> 103*00b67f09SDavid van Moolenbroek<div class="refsect1" lang="en"> 104*00b67f09SDavid van Moolenbroek<a name="id2543434"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2> 105*00b67f09SDavid van Moolenbroek<p> 106*00b67f09SDavid van Moolenbroek When a client program wishes to make an lwres request using the 107*00b67f09SDavid van Moolenbroek native low-level API, it typically performs the following 108*00b67f09SDavid van Moolenbroek sequence of actions. 109*00b67f09SDavid van Moolenbroek </p> 110*00b67f09SDavid van Moolenbroek<p> 111*00b67f09SDavid van Moolenbroek (1) Allocate or use an existing <span class="type">lwres_packet_t</span>, 112*00b67f09SDavid van Moolenbroek called <code class="varname">pkt</code> below. 113*00b67f09SDavid van Moolenbroek </p> 114*00b67f09SDavid van Moolenbroek<p> 115*00b67f09SDavid van Moolenbroek (2) Set <em class="structfield"><code>pkt.recvlength</code></em> to the maximum length 116*00b67f09SDavid van Moolenbroek we will accept. 117*00b67f09SDavid van Moolenbroek This is done so the receiver of our packets knows how large our receive 118*00b67f09SDavid van Moolenbroek buffer is. The "default" is a constant in 119*00b67f09SDavid van Moolenbroek <code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>. 120*00b67f09SDavid van Moolenbroek </p> 121*00b67f09SDavid van Moolenbroek<p> 122*00b67f09SDavid van Moolenbroek (3) Set <em class="structfield"><code>pkt.serial</code></em> 123*00b67f09SDavid van Moolenbroek to a unique serial number. This value is echoed 124*00b67f09SDavid van Moolenbroek back to the application by the remote server. 125*00b67f09SDavid van Moolenbroek </p> 126*00b67f09SDavid van Moolenbroek<p> 127*00b67f09SDavid van Moolenbroek (4) Set <em class="structfield"><code>pkt.pktflags</code></em>. Usually this is set to 128*00b67f09SDavid van Moolenbroek 0. 129*00b67f09SDavid van Moolenbroek </p> 130*00b67f09SDavid van Moolenbroek<p> 131*00b67f09SDavid van Moolenbroek (5) Set <em class="structfield"><code>pkt.result</code></em> to 0. 132*00b67f09SDavid van Moolenbroek </p> 133*00b67f09SDavid van Moolenbroek<p> 134*00b67f09SDavid van Moolenbroek (6) Call <code class="function">lwres_*request_render()</code>, 135*00b67f09SDavid van Moolenbroek or marshall in the data using the primitives 136*00b67f09SDavid van Moolenbroek such as <code class="function">lwres_packet_render()</code> 137*00b67f09SDavid van Moolenbroek and storing the packet data. 138*00b67f09SDavid van Moolenbroek </p> 139*00b67f09SDavid van Moolenbroek<p> 140*00b67f09SDavid van Moolenbroek (7) Transmit the resulting buffer. 141*00b67f09SDavid van Moolenbroek </p> 142*00b67f09SDavid van Moolenbroek<p> 143*00b67f09SDavid van Moolenbroek (8) Call <code class="function">lwres_*response_parse()</code> 144*00b67f09SDavid van Moolenbroek to parse any packets received. 145*00b67f09SDavid van Moolenbroek </p> 146*00b67f09SDavid van Moolenbroek<p> 147*00b67f09SDavid van Moolenbroek (9) Verify that the opcode and serial match a request, and process the 148*00b67f09SDavid van Moolenbroek packet specific information contained in the body. 149*00b67f09SDavid van Moolenbroek </p> 150*00b67f09SDavid van Moolenbroek</div> 151*00b67f09SDavid van Moolenbroek<div class="refsect1" lang="en"> 152*00b67f09SDavid van Moolenbroek<a name="id2543582"></a><h2>SERVER-SIDE LOW-LEVEL API CALL FLOW</h2> 153*00b67f09SDavid van Moolenbroek<p> 154*00b67f09SDavid van Moolenbroek When implementing the server side of the lightweight resolver 155*00b67f09SDavid van Moolenbroek protocol using the lwres library, a sequence of actions like the 156*00b67f09SDavid van Moolenbroek following is typically involved in processing each request packet. 157*00b67f09SDavid van Moolenbroek </p> 158*00b67f09SDavid van Moolenbroek<p> 159*00b67f09SDavid van Moolenbroek Note that the same <span class="type">lwres_packet_t</span> is used 160*00b67f09SDavid van Moolenbroek in both the <code class="function">_parse()</code> and <code class="function">_render()</code> calls, 161*00b67f09SDavid van Moolenbroek with only a few modifications made 162*00b67f09SDavid van Moolenbroek to the packet header's contents between uses. This method is 163*00b67f09SDavid van Moolenbroek recommended 164*00b67f09SDavid van Moolenbroek as it keeps the serial, opcode, and other fields correct. 165*00b67f09SDavid van Moolenbroek </p> 166*00b67f09SDavid van Moolenbroek<p> 167*00b67f09SDavid van Moolenbroek (1) When a packet is received, call <code class="function">lwres_*request_parse()</code> to 168*00b67f09SDavid van Moolenbroek unmarshall it. This returns a <span class="type">lwres_packet_t</span> (also called <code class="varname">pkt</code>, below) 169*00b67f09SDavid van Moolenbroek as well as a data specific type, such as <span class="type">lwres_gabnrequest_t</span>. 170*00b67f09SDavid van Moolenbroek </p> 171*00b67f09SDavid van Moolenbroek<p> 172*00b67f09SDavid van Moolenbroek (2) Process the request in the data specific type. 173*00b67f09SDavid van Moolenbroek </p> 174*00b67f09SDavid van Moolenbroek<p> 175*00b67f09SDavid van Moolenbroek (3) Set the <em class="structfield"><code>pkt.result</code></em>, 176*00b67f09SDavid van Moolenbroek <em class="structfield"><code>pkt.recvlength</code></em> as above. All other fields 177*00b67f09SDavid van Moolenbroek can 178*00b67f09SDavid van Moolenbroek be left untouched since they were filled in by the <code class="function">*_parse()</code> call 179*00b67f09SDavid van Moolenbroek above. If using <code class="function">lwres_*response_render()</code>, 180*00b67f09SDavid van Moolenbroek <em class="structfield"><code>pkt.pktflags</code></em> will be set up 181*00b67f09SDavid van Moolenbroek properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be 182*00b67f09SDavid van Moolenbroek set. 183*00b67f09SDavid van Moolenbroek </p> 184*00b67f09SDavid van Moolenbroek<p> 185*00b67f09SDavid van Moolenbroek (4) Call the data specific rendering function, such as 186*00b67f09SDavid van Moolenbroek <code class="function">lwres_gabnresponse_render()</code>. 187*00b67f09SDavid van Moolenbroek </p> 188*00b67f09SDavid van Moolenbroek<p> 189*00b67f09SDavid van Moolenbroek (5) Send the resulting packet to the client. 190*00b67f09SDavid van Moolenbroek </p> 191*00b67f09SDavid van Moolenbroek<p></p> 192*00b67f09SDavid van Moolenbroek</div> 193*00b67f09SDavid van Moolenbroek<div class="refsect1" lang="en"> 194*00b67f09SDavid van Moolenbroek<a name="id2543666"></a><h2>SEE ALSO</h2> 195*00b67f09SDavid van Moolenbroek<p><span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>, 196*00b67f09SDavid van Moolenbroek 197*00b67f09SDavid van Moolenbroek <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>, 198*00b67f09SDavid van Moolenbroek 199*00b67f09SDavid van Moolenbroek <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>, 200*00b67f09SDavid van Moolenbroek 201*00b67f09SDavid van Moolenbroek <span class="citerefentry"><span class="refentrytitle">lwres_noop</span>(3)</span>, 202*00b67f09SDavid van Moolenbroek 203*00b67f09SDavid van Moolenbroek <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>, 204*00b67f09SDavid van Moolenbroek 205*00b67f09SDavid van Moolenbroek <span class="citerefentry"><span class="refentrytitle">lwres_gnba</span>(3)</span>, 206*00b67f09SDavid van Moolenbroek 207*00b67f09SDavid van Moolenbroek <span class="citerefentry"><span class="refentrytitle">lwres_context</span>(3)</span>, 208*00b67f09SDavid van Moolenbroek 209*00b67f09SDavid van Moolenbroek <span class="citerefentry"><span class="refentrytitle">lwres_config</span>(3)</span>, 210*00b67f09SDavid van Moolenbroek 211*00b67f09SDavid van Moolenbroek <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>, 212*00b67f09SDavid van Moolenbroek 213*00b67f09SDavid van Moolenbroek <span class="citerefentry"><span class="refentrytitle">lwresd</span>(8)</span>. 214*00b67f09SDavid van Moolenbroek 215*00b67f09SDavid van Moolenbroek </p> 216*00b67f09SDavid van Moolenbroek</div> 217*00b67f09SDavid van Moolenbroek</div></body> 218*00b67f09SDavid van Moolenbroek</html> 219