lwres.html revision 8a66318e41ed14c5a88130e8c362610e8faa2121
25cc5fbba63f84b47e389af749f55abbbde71c8cChristian Maeder - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
25cc5fbba63f84b47e389af749f55abbbde71c8cChristian Maeder - Copyright (C) 2001 Internet Software Consortium.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - Permission to use, copy, modify, and distribute this software for any
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian 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
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian 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,
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian 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
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian Maeder - PERFORMANCE OF THIS SOFTWARE.
ce8b15da31cd181b7e90593cbbca98f47eda29d6Till Mossakowski<!-- $Id: lwres.html,v 1.5 2004/03/05 08:32:19 marka Exp $ -->
c0c2380bced8159ff0297ece14eba948bd236471Christian MaederNAME="GENERATOR"
c0c2380bced8159ff0297ece14eba948bd236471Christian MaederCONTENT="Modular DocBook HTML Stylesheet Version 1.73
c0c2380bced8159ff0297ece14eba948bd236471Christian MaederCLASS="REFENTRY"
8410667510a76409aca9bb24ff0eda0420088274Christian MaederBGCOLOR="#FFFFFF"
8410667510a76409aca9bb24ff0eda0420088274Christian MaederTEXT="#000000"
8410667510a76409aca9bb24ff0eda0420088274Christian MaederLINK="#0000FF"
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus LuettichVLINK="#840084"
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus LuettichALINK="#0000FF"
e593b89bfd4952698dc37feced21cefe869d87a2Christian MaederCLASS="REFNAMEDIV"
c6fcd42c6d6d9dae8c7835c24fcb7ce8531a9050Christian Maeder>lwres -- introduction to the lightweight resolver library</DIV
c55a0f77be7e88d3620b419ec8961f4379a586e3Klaus LuettichCLASS="REFSYNOPSISDIV"
c0c2380bced8159ff0297ece14eba948bd236471Christian MaederCLASS="FUNCSYNOPSIS"
c0c2380bced8159ff0297ece14eba948bd236471Christian MaederCLASS="FUNCSYNOPSISINFO"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFSECT1"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>DESCRIPTION</H2
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>The BIND 9 lightweight resolver library is a simple, name service
77a65251ee036c6aaf09c2775315a4ee24259fbdJorina Freya Gerkenindependent stub resolver library. It provides hostname-to-address
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederand address-to-hostname lookup services to applications by
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maedertransmitting lookup requests to a resolver daemon
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="COMMAND"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederrunning on the local host. The resover daemon performs the
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederlookup using the DNS or possibly other name service protocols,
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maederand returns the results to the application through the library.
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederThe library and resolver daemon communicate using a simple
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederUDP-based protocol.</P
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="REFSECT1"
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>The lwresd library implements multiple name service APIs.
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix ReckersCLASS="FUNCTION"
5d4038657f6a63e131f5804af2f7957b69e15a43Klaus Luettich>gethostbyname()</TT
c432483b64662e8db604a58758cd18ea7fa65659Christian MaederCLASS="FUNCTION"
857992065be4ed40a72c6296b6c0aec62ab4c5b9Christian Maeder>gethostbyaddr()</TT
8c692d0cc44e7df93f58a3eed0d9774ba5908339Jorina Freya GerkenCLASS="FUNCTION"
eeb419aa20c97b4af973e97ee6ae77a8eed29e15Till Mossakowski>gethostbyname_r()</TT
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="FUNCTION"
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder>gethostbyaddr_r()</TT
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="FUNCTION"
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder>getaddrinfo()</TT
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="FUNCTION"
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder>getipnodebyname()</TT
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="FUNCTION"
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder>getipnodebyaddr()</TT
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maederfunctions are all supported. To allow the lwres library to coexist
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckerswith system libraries that define functions of the same name,
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maederthe library defines these functions with names prefixed by
51e836611726885f6d2719d959ed1b51f8fd06f4Klaus LuettichCLASS="LITERAL"
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederTo define the standard names, applications must include the
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="FILENAME"
c0c2380bced8159ff0297ece14eba948bd236471Christian Maederwhich contains macro definitions mapping the standard function names
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="LITERAL"
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maederprefixed ones. Operating system vendors who integrate the lwres
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maederlibrary into their base distributions should rename the functions
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maederin the library proper so that the renaming macros are not needed.</P
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maeder>The library also provides a native API consisting of the functions
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian MaederCLASS="FUNCTION"
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maeder>lwres_getaddrsbyname()</TT
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian MaederCLASS="FUNCTION"
53818ced114da21321063fff307aa41c1ab31dd3Achim Mahnke>lwres_getnamebyaddr()</TT
53818ced114da21321063fff307aa41c1ab31dd3Achim MahnkeThese may be called by applications that require more detailed
53818ced114da21321063fff307aa41c1ab31dd3Achim Mahnkecontrol over the lookup process than the standard functions
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>In addition to these name service independent address lookup
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederfunctions, the library implements a new, experimental API
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maederfor looking up arbitrary DNS resource records, using the
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="FUNCTION"
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder>lwres_getaddrsbyname()</TT
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>Finally, there is a low-level API for converting lookup
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckersrequests and responses to and from raw lwres protocol packets.
b49276c9f50038e0bd499ad49f7bd6444566a834Christian MaederThis API can be used by clients requiring nonblocking operation,
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maederand is also used when implementing the server side of the lwres
ed9207cf24e96b0d6f59985822054ae28cb69b2eChristian Maederprotocol, for example in the
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="COMMAND"
b10267ae0a6523b73113fc2dee9ea628266fce60Christian Maederresolver daemon. The use of this low-level API in clients
fa21fba9ceb1ddf7b3efd54731a12ed8750191d8Christian Maederand servers is outlined in the following sections.</P
05a8b581f98b928baca6dab60cd20277659ac760Christian MaederCLASS="REFSECT1"
b49276c9f50038e0bd499ad49f7bd6444566a834Christian Maeder>CLIENT-SIDE LOW-LEVEL API CALL FLOW</H2
b905126bab9454b89041f92b3c50bb9efc85e427Klaus Luettich>When a client program wishes to make an lwres request using the
6e049108aa87dc46bcff96fae50a4625df1d9648Klaus Luettichnative low-level API, it typically performs the following
b905126bab9454b89041f92b3c50bb9efc85e427Klaus Luettichsequence of actions.</P
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian Maeder>(1) Allocate or use an existing <SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>lwres_packet_t</SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="VARNAME"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="STRUCTFIELD"
b905126bab9454b89041f92b3c50bb9efc85e427Klaus Luettich> to the maximum length we will accept.
b905126bab9454b89041f92b3c50bb9efc85e427Klaus LuettichThis is done so the receiver of our packets knows how large our receive
b905126bab9454b89041f92b3c50bb9efc85e427Klaus Luettichbuffer is. The "default" is a constant in
33d042fe6a9eb27a4c48f840b80838f3e7d98e34Christian MaederCLASS="FILENAME"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CONSTANT"
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maeder>LWRES_RECVLENGTH = 4096</TT
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian MaederCLASS="STRUCTFIELD"
ef67402074be14deb95e4ff564737d5593144130Klaus Luettichto a unique serial number. This value is echoed
1323eba62fc519b068f5aaec4f9d2be05ffabea9Klaus Luettichback to the application by the remote server.</P
725a68ec81cba9b8aa8647bebfb5baa449803e7eKlaus LuettichCLASS="STRUCTFIELD"
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder>. Usually this is set to 0.</P
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="STRUCTFIELD"
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian MaederCLASS="FUNCTION"
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettich>lwres_*request_render()</TT
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maederor marshall in the data using the primitives
e593b89bfd4952698dc37feced21cefe869d87a2Christian MaederCLASS="FUNCTION"
340706b6c0c6e3dbacdd7003e20e9cab7f9aa765Christian Maeder>lwres_packet_render()</TT
fdb2d618144159395f7bf8ce3327b3c112a17dd3Till Mossakowskiand storing the packet data.</P
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder>(7) Transmit the resulting buffer.</P
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian MaederCLASS="FUNCTION"
33d042fe6a9eb27a4c48f840b80838f3e7d98e34Christian Maeder>lwres_*response_parse()</TT
dc929508a3bd3c666e9b0182d56898fcafb5d66fChristian Maederto parse any packets received.</P
94d3aa05411444596b44ede4531f05dd7ac20fdfChristian Maeder>(9) Verify that the opcode and serial match a request, and process the
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maederpacket specific information contained in the body.</P
ddc9315cc0b1f5dd3d8f99a77f1c75064db33b48Christian MaederCLASS="REFSECT1"
8410667510a76409aca9bb24ff0eda0420088274Christian Maeder>SERVER-SIDE LOW-LEVEL API CALL FLOW</H2
ac43fa22d2d3f91a17674ac164cba3cf39a17795Klaus Luettich>When implementing the server side of the lightweight resolver
ac43fa22d2d3f91a17674ac164cba3cf39a17795Klaus Luettichprotocol using the lwres library, a sequence of actions like the
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckersfollowing is typically involved in processing each request packet.</P
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>Note that the same <SPAN
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>lwres_packet_t</SPAN
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maederin both the <TT
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="FUNCTION"
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="FUNCTION"
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder>_render()</TT
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maederwith only a few modifications made
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maederto the packet header's contents between uses. This method is recommended
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maederas it keeps the serial, opcode, and other fields correct.</P
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder>(1) When a packet is received, call <TT
61fa0ac06ede811c7aad54ec4c4202346727368eChristian MaederCLASS="FUNCTION"
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder>lwres_*request_parse()</TT
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maederunmarshall it. This returns a <SPAN
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>lwres_packet_t</SPAN
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder> (also called <TT
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix ReckersCLASS="VARNAME"
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckersas well as a data specific type, such as <SPAN
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>lwres_gabnrequest_t</SPAN
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder>(2) Process the request in the data specific type.</P
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>(3) Set the <TT
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="STRUCTFIELD"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="STRUCTFIELD"
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers> as above. All other fields can
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederbe left untouched since they were filled in by the <TT
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="FUNCTION"
d67a33b40578beef2e255a274f89bb9c34aaf056Christian Maeder>*_parse()</TT
d67a33b40578beef2e255a274f89bb9c34aaf056Christian Maederabove. If using <TT
26f228bf3a3fea810223396e5794c217a79a8d5bChristian MaederCLASS="FUNCTION"
26f228bf3a3fea810223396e5794c217a79a8d5bChristian Maeder>lwres_*response_render()</TT
ba904a15082557e939db689fcfba0c68c9a4f740Christian MaederCLASS="STRUCTFIELD"
6ae5607d2def114f998fd49bac4eef12a2620fafChristian Maeder> will be set up
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian Maederproperly. Otherwise, the <TT
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian MaederCLASS="CONSTANT"
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian Maeder>LWRES_LWPACKETFLAG_RESPONSE</TT
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder> bit should be
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>(4) Call the data specific rendering function, such as
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="FUNCTION"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>lwres_gabnresponse_render()</TT
75cda7e5b890d050d560d970af244a183f28328fKlaus Luettich>(5) Send the resulting packet to the client.</P
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFSECT1"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>lwres_gethostent</SPAN
470ca7a2797069ae4b27c34c1b71419f67be1f84Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>lwres_getipnode</SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>lwres_getnameinfo</SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"
481d4fe351800ab00fd323db8974559431227305Christian Maeder>lwres_noop</SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CITEREFENTRY"
327a9b9bf44b6e33f71fee7526dc1c0035251591Christian MaederCLASS="REFENTRYTITLE"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>lwres_gabn</SPAN
8b4c68db8b465107cabef8b9cd5b6bc216e1b156Till MossakowskiCLASS="CITEREFENTRY"
8b4c68db8b465107cabef8b9cd5b6bc216e1b156Till MossakowskiCLASS="REFENTRYTITLE"
8b4c68db8b465107cabef8b9cd5b6bc216e1b156Till Mossakowski>lwres_gnba</SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"
b49276c9f50038e0bd499ad49f7bd6444566a834Christian Maeder>lwres_context</SPAN
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix ReckersCLASS="CITEREFENTRY"
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix ReckersCLASS="REFENTRYTITLE"
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>lwres_config</SPAN
5d4038657f6a63e131f5804af2f7957b69e15a43Klaus LuettichCLASS="CITEREFENTRY"
5d4038657f6a63e131f5804af2f7957b69e15a43Klaus LuettichCLASS="REFENTRYTITLE"
5d4038657f6a63e131f5804af2f7957b69e15a43Klaus Luettich>resolver</SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"