lwres.docbook revision 2eeb74d1cf5355dd98f6d507a10086e16bb08c4b
25cc5fbba63f84b47e389af749f55abbbde71c8cChristian Maeder - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder - Copyright (C) 2000, 2001 Internet Software Consortium.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - Permission to use, copy, modify, and/or distribute this software for any
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder - purpose with or without fee is hereby granted, provided that the above
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - copyright notice and this permission notice appear in all copies.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
d8c71aacc9f1c8cd40a8ad8dcdad9be8854b849fChristian Maeder - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - PERFORMANCE OF THIS SOFTWARE.
a737caf82de97c1907027c03e4b4509eb492b4b8Christian Maeder<!-- Converted by db4-upgrade version 1.0 -->
a737caf82de97c1907027c03e4b4509eb492b4b8Christian Maeder<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
473bc1f3f3443f18e0ee83e4642fab42183470f2Christian Maeder <refentryinfo>
a53841f6d6e86ac751c12a33dc8aadf53f59d977Klaus Luettich <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
a53841f6d6e86ac751c12a33dc8aadf53f59d977Klaus Luettich </refentryinfo>
bd54a9917cd87169b8e40bcc5616c537fed85815Christian Maeder <refpurpose>introduction to the lightweight resolver library</refpurpose>
a53841f6d6e86ac751c12a33dc8aadf53f59d977Klaus Luettich </refnamediv>
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
e8db9a65830cf71504e33c6f441a67b4d184a3caChristian Maeder <holder>Internet Software Consortium.</holder>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <refsynopsisdiv>
8410667510a76409aca9bb24ff0eda0420088274Christian Maeder <funcsynopsis>
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettich<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
b1f59a4ea7c96f4c03a4d7cfcb9c5e66871cfbbbChristian Maeder</funcsynopsis>
3e61f574717499939bd8e0ff538ea9e7b72d4e2dKlaus Luettich </refsynopsisdiv>
4d56f2fa72e4aec20eb827c11ed49c8cbb7014bdChristian Maeder <refsection><info><title>DESCRIPTION</title></info>
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettich The BIND 9 lightweight resolver library is a simple, name service
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder independent stub resolver library. It provides hostname-to-address
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder and address-to-hostname lookup services to applications by
55adfe57a4de1f36adc3e3bfc16f342e44a7d444Christian Maeder transmitting lookup requests to a resolver daemon
8d97ef4f234681b11bb5924bd4d03adef858d2d2Christian Maeder running on the local host. The resolver daemon performs the
8d97ef4f234681b11bb5924bd4d03adef858d2d2Christian Maeder lookup using the DNS or possibly other name service protocols,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder and returns the results to the application through the library.
e593b89bfd4952698dc37feced21cefe869d87a2Christian Maeder The library and resolver daemon communicate using a simple
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder UDP-based protocol.
0206ab93ef846e4e0885996d052b9b73b9dc66b0Christian Maeder </refsection>
cdd280437686b1e2e25e3761d4adf3d4a0a2d11cKlaus Luettich <refsection><info><title>OVERVIEW</title></info>
e7757995211bd395dc79d26fe017d99375f7d2a6Christian Maeder The lwresd library implements multiple name service APIs.
a7c27282e71cf4505026645f96d4f5cb8a284e32Christian Maeder functions are all supported. To allow the lwres library to coexist
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder with system libraries that define functions of the same name,
8a28707e9155465c6f2236a06eac6580a65c7025Christian Maeder the library defines these functions with names prefixed by
431d34c7007a787331c4e5ec997badb0f8190fc7Christian Maeder To define the standard names, applications must include the
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder which contains macro definitions mapping the standard function names
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder prefixed ones. Operating system vendors who integrate the lwres
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder library into their base distributions should rename the functions
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder in the library proper so that the renaming macros are not needed.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder The library also provides a native API consisting of the functions
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder <function>lwres_getaddrsbyname()</function>
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder <function>lwres_getnamebyaddr()</function>.
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder These may be called by applications that require more detailed
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder control over the lookup process than the standard functions
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder In addition to these name service independent address lookup
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder functions, the library implements a new, experimental API
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder for looking up arbitrary DNS resource records, using the
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <function>lwres_getaddrsbyname()</function>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder Finally, there is a low-level API for converting lookup
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder requests and responses to and from raw lwres protocol packets.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder This API can be used by clients requiring nonblocking operation,
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder and is also used when implementing the server side of the lwres
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder protocol, for example in the
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder resolver daemon. The use of this low-level API in clients
0769e2a25732dc2544b2a7425dfa284e24d23b71Christian Maeder and servers is outlined in the following sections.
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder </refsection>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <refsection><info><title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title></info>
ad4889ebb40efae8595b0969dd6ba1162d52bac3Christian Maeder When a client program wishes to make an lwres request using the
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder native low-level API, it typically performs the following
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder sequence of actions.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder (1) Allocate or use an existing <type>lwres_packet_t</type>,
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder (2) Set <varname remap="structfield">pkt.recvlength</varname> to the maximum length
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder we will accept.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder This is done so the receiver of our packets knows how large our receive
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder buffer is. The "default" is a constant in
88318aafc287e92931dceffbb943d58a9310001dChristian Maeder <filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder (3) Set <varname remap="structfield">pkt.serial</varname>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder to a unique serial number. This value is echoed
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder back to the application by the remote server.
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder (4) Set <varname remap="structfield">pkt.pktflags</varname>. Usually this is set to
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder (5) Set <varname remap="structfield">pkt.result</varname> to 0.
b568982efd0997d877286faa592d81b03c8c67b8Christian Maeder (6) Call <function>lwres_*request_render()</function>,
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder or marshall in the data using the primitives
0be0db405c49906bd7057255069bf6df53395ac9Klaus Luettich such as <function>lwres_packet_render()</function>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder and storing the packet data.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder (7) Transmit the resulting buffer.
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder (8) Call <function>lwres_*response_parse()</function>
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder to parse any packets received.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder (9) Verify that the opcode and serial match a request, and process the
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder packet specific information contained in the body.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder </refsection>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder <refsection><info><title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title></info>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder When implementing the server side of the lightweight resolver
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder protocol using the lwres library, a sequence of actions like the
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder following is typically involved in processing each request packet.
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder Note that the same <type>lwres_packet_t</type> is used
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder in both the <function>_parse()</function> and <function>_render()</function> calls,
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder with only a few modifications made
89f7631cbfbd1bb99fc152b434bd362a7799d295Christian Maeder to the packet header's contents between uses. This method is
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder as it keeps the serial, opcode, and other fields correct.
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder (1) When a packet is received, call <function>lwres_*request_parse()</function> to
f4505a64a089693012a3f5c3b1f12a82cd7a2a5aKlaus Luettich unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder as well as a data specific type, such as <type>lwres_gabnrequest_t</type>.
e7757995211bd395dc79d26fe017d99375f7d2a6Christian Maeder (2) Process the request in the data specific type.
2c619a4dfdc1df27573eba98e81ed1ace906941dChristian Maeder (3) Set the <varname remap="structfield">pkt.result</varname>,
36f63902db2b3463faa9f59912ad106e2d5aaa24Klaus Luettich <varname remap="structfield">pkt.recvlength</varname> as above. All other fields
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder be left untouched since they were filled in by the <function>*_parse()</function> call
e7757995211bd395dc79d26fe017d99375f7d2a6Christian Maeder above. If using <function>lwres_*response_render()</function>,
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <varname remap="structfield">pkt.pktflags</varname> will be set up
d272062059eea4d7479e1c6e8517469f02f61287Christian Maeder properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be
7c5c311d67e187280877c45bd89dcba9038bc0a3Christian Maeder (4) Call the data specific rendering function, such as
7c5c311d67e187280877c45bd89dcba9038bc0a3Christian Maeder <function>lwres_gabnresponse_render()</function>.
83394c6b6e6de128e71b67c9251ed7a84485d082Christian Maeder (5) Send the resulting packet to the client.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder </refsection>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <refsection><info><title>SEE ALSO</title></info>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder </citerefentry>,
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers <citerefentry>
010c56c4cf12dd7977ca36efe85219b91e265ee3Christian Maeder <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
fb328c4f646dd3dd78a9391c5cb58450a3dd0aa9Klaus Luettich </citerefentry>,
5b818f10e11fc79def1fdd5c8a080d64a6438d87Christian Maeder <citerefentry>
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder </citerefentry>,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <citerefentry>
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder <refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers </citerefentry>,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <citerefentry>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder </citerefentry>,
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder <citerefentry>
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder <refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder </citerefentry>,
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <citerefentry>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder </citerefentry>,
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder <citerefentry>
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder <refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder </citerefentry>,
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <citerefentry>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder </citerefentry>,
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <citerefentry>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder </citerefentry>.
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder </refsection>