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.
83394c6b6e6de128e71b67c9251ed7a84485d082Christian Maeder<!-- Converted by db4-upgrade version 1.0 -->
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
83394c6b6e6de128e71b67c9251ed7a84485d082Christian Maeder <refentryinfo>
c9acb8681bcc512245b4f0d1a9f2b189c60e10d4Christian Maeder <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
ce8b15da31cd181b7e90593cbbca98f47eda29d6Till Mossakowski </refentryinfo>
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder <refpurpose>introduction to the lightweight resolver library</refpurpose>
2e2094a642e3775b0d76b890556407941d3a53b6Christian Maeder </refnamediv>
4d56f2fa72e4aec20eb827c11ed49c8cbb7014bdChristian Maeder <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian Maeder <holder>Internet Software Consortium.</holder>
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian Maeder <refsynopsisdiv>
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian Maeder <funcsynopsis>
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian Maeder<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian Maeder</funcsynopsis>
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettich </refsynopsisdiv>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <refsection><info><title>DESCRIPTION</title></info>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder The BIND 9 lightweight resolver library is a simple, name service
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder independent stub resolver library. It provides hostname-to-address
e593b89bfd4952698dc37feced21cefe869d87a2Christian Maeder and address-to-hostname lookup services to applications by
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder transmitting lookup requests to a resolver daemon
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder running on the local host. The resolver daemon performs the
2e2094a642e3775b0d76b890556407941d3a53b6Christian Maeder lookup using the DNS or possibly other name service protocols,
f13d1e86e58da53680e78043e8df182eed867efbChristian Maeder and returns the results to the application through the library.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder The library and resolver daemon communicate using a simple
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder UDP-based protocol.
c6fcd42c6d6d9dae8c7835c24fcb7ce8531a9050Christian Maeder </refsection>
c55a0f77be7e88d3620b419ec8961f4379a586e3Klaus Luettich <refsection><info><title>OVERVIEW</title></info>
c9acb8681bcc512245b4f0d1a9f2b189c60e10d4Christian Maeder The lwresd library implements multiple name service APIs.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder functions are all supported. To allow the lwres library to coexist
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder with system libraries that define functions of the same name,
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder the library defines these functions with names prefixed by
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder To define the standard names, applications must include the
c9acb8681bcc512245b4f0d1a9f2b189c60e10d4Christian Maeder which contains macro definitions mapping the standard function names
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder prefixed ones. Operating system vendors who integrate the lwres
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder library into their base distributions should rename the functions
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian 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 <function>lwres_getaddrsbyname()</function>
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder <function>lwres_getnamebyaddr()</function>.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian 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
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder functions, the library implements a new, experimental API
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder for looking up arbitrary DNS resource records, using the
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder <function>lwres_getaddrsbyname()</function>
6ff7a91875597d6e4dfaa68c79187d01473e8341Christian Maeder Finally, there is a low-level API for converting lookup
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder requests and responses to and from raw lwres protocol packets.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder This API can be used by clients requiring nonblocking operation,
4017ebc0f692820736d796af3110c3b3018c108aChristian 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
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder and servers is outlined in the following sections.
88318aafc287e92931dceffbb943d58a9310001dChristian Maeder </refsection>
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder <refsection><info><title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title></info>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder When a client program wishes to make an lwres request using the
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder native low-level API, it typically performs the following
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder sequence of actions.
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder (1) Allocate or use an existing <type>lwres_packet_t</type>,
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder (2) Set <varname remap="structfield">pkt.recvlength</varname> to the maximum length
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder we will accept.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder This is done so the receiver of our packets knows how large our receive
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder buffer is. The "default" is a constant in
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian 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
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder back to the application by the remote server.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder (4) Set <varname remap="structfield">pkt.pktflags</varname>. Usually this is set to
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder (5) Set <varname remap="structfield">pkt.result</varname> to 0.
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder (6) Call <function>lwres_*request_render()</function>,
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder or marshall in the data using the primitives
f4505a64a089693012a3f5c3b1f12a82cd7a2a5aKlaus Luettich such as <function>lwres_packet_render()</function>
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder and storing the packet data.
f4505a64a089693012a3f5c3b1f12a82cd7a2a5aKlaus Luettich (7) Transmit the resulting buffer.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder (8) Call <function>lwres_*response_parse()</function>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder to parse any packets received.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder (9) Verify that the opcode and serial match a request, and process the
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder packet specific information contained in the body.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder </refsection>
d272062059eea4d7479e1c6e8517469f02f61287Christian Maeder <refsection><info><title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title></info>
83394c6b6e6de128e71b67c9251ed7a84485d082Christian Maeder When implementing the server side of the lightweight resolver
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder protocol using the lwres library, a sequence of actions like the
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder following is typically involved in processing each request packet.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder Note that the same <type>lwres_packet_t</type> is used
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder in both the <function>_parse()</function> and <function>_render()</function> calls,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder with only a few modifications made
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder to the packet header's contents between uses. This method is
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers as it keeps the serial, opcode, and other fields correct.
5b818f10e11fc79def1fdd5c8a080d64a6438d87Christian Maeder (1) When a packet is received, call <function>lwres_*request_parse()</function> to
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)
0799b5dc3f06d2640e66e9ab54b8b217348fd719Christian Maeder as well as a data specific type, such as <type>lwres_gabnrequest_t</type>.
38352346eb1a67ba0f4eab8ad6f718528cf0cde0Christian Maeder (2) Process the request in the data specific type.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder (3) Set the <varname remap="structfield">pkt.result</varname>,
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <varname remap="structfield">pkt.recvlength</varname> as above. All other fields
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder be left untouched since they were filled in by the <function>*_parse()</function> call
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder above. If using <function>lwres_*response_render()</function>,
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <varname remap="structfield">pkt.pktflags</varname> will be set up
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder (4) Call the data specific rendering function, such as
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <function>lwres_gabnresponse_render()</function>.
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder (5) Send the resulting packet to the client.
11280087fb7891a39bae5305886e76c0cc30886cChristian Maeder </refsection>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <refsection><info><title>SEE ALSO</title></info>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder </citerefentry>,
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <citerefentry>
11280087fb7891a39bae5305886e76c0cc30886cChristian Maeder <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder </citerefentry>,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <citerefentry>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder </citerefentry>,
6fe9628743562678acf97d6730ebcfee5e9e50c2Christian Maeder <citerefentry>
6fe9628743562678acf97d6730ebcfee5e9e50c2Christian Maeder <refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder </citerefentry>,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <citerefentry>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder </citerefentry>,
fb328c4f646dd3dd78a9391c5cb58450a3dd0aa9Klaus Luettich <citerefentry>
fb328c4f646dd3dd78a9391c5cb58450a3dd0aa9Klaus Luettich <refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>
e96a0bf4040fd789339958c01f145c5057d26db6René Wagner </citerefentry>,
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <citerefentry>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder </citerefentry>,
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <citerefentry>
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder </citerefentry>,
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder <citerefentry>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
fdb2d618144159395f7bf8ce3327b3c112a17dd3Till Mossakowski </citerefentry>,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <citerefentry>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder </citerefentry>.
e8896c7bb416c4ced255a4d500808c2ea5a6869aChristian Maeder </refsection>