177 lines
6.6 KiB
Groff
177 lines
6.6 KiB
Groff
.\" Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
|
|
.\"
|
|
.\" This Source Code Form is subject to the terms of the Mozilla Public
|
|
.\" License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
.\" file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
.\"
|
|
.hy 0
|
|
.ad l
|
|
'\" t
|
|
.\" Title: lwres
|
|
.\" Author:
|
|
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
|
|
.\" Date: 2007-06-18
|
|
.\" Manual: BIND9
|
|
.\" Source: ISC
|
|
.\" Language: English
|
|
.\"
|
|
.TH "LWRES" "3" "2007\-06\-18" "ISC" "BIND9"
|
|
.\" -----------------------------------------------------------------
|
|
.\" * Define some portability stuff
|
|
.\" -----------------------------------------------------------------
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.\" http://bugs.debian.org/507673
|
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\" -----------------------------------------------------------------
|
|
.\" * set default formatting
|
|
.\" -----------------------------------------------------------------
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" -----------------------------------------------------------------
|
|
.\" * MAIN CONTENT STARTS HERE *
|
|
.\" -----------------------------------------------------------------
|
|
.SH "NAME"
|
|
lwres \- introduction to the lightweight resolver library
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
.ft B
|
|
.nf
|
|
#include <lwres/lwres\&.h>
|
|
.fi
|
|
.ft
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
The BIND 9 lightweight resolver library is a simple, name service independent stub resolver library\&. It provides hostname\-to\-address and address\-to\-hostname lookup services to applications by transmitting lookup requests to a resolver daemon
|
|
\fBlwresd\fR
|
|
running on the local host\&. The resolver daemon performs the lookup using the DNS or possibly other name service protocols, and returns the results to the application through the library\&. The library and resolver daemon communicate using a simple UDP\-based protocol\&.
|
|
.SH "OVERVIEW"
|
|
.PP
|
|
The lwresd library implements multiple name service APIs\&. The standard
|
|
\fBgethostbyname()\fR,
|
|
\fBgethostbyaddr()\fR,
|
|
\fBgethostbyname_r()\fR,
|
|
\fBgethostbyaddr_r()\fR,
|
|
\fBgetaddrinfo()\fR,
|
|
\fBgetipnodebyname()\fR, and
|
|
\fBgetipnodebyaddr()\fR
|
|
functions are all supported\&. To allow the lwres library to coexist with system libraries that define functions of the same name, the library defines these functions with names prefixed by
|
|
lwres_\&. To define the standard names, applications must include the header file
|
|
<lwres/netdb\&.h>
|
|
which contains macro definitions mapping the standard function names into
|
|
lwres_
|
|
prefixed ones\&. Operating system vendors who integrate the lwres library into their base distributions should rename the functions in the library proper so that the renaming macros are not needed\&.
|
|
.PP
|
|
The library also provides a native API consisting of the functions
|
|
\fBlwres_getaddrsbyname()\fR
|
|
and
|
|
\fBlwres_getnamebyaddr()\fR\&. These may be called by applications that require more detailed control over the lookup process than the standard functions provide\&.
|
|
.PP
|
|
In addition to these name service independent address lookup functions, the library implements a new, experimental API for looking up arbitrary DNS resource records, using the
|
|
\fBlwres_getaddrsbyname()\fR
|
|
function\&.
|
|
.PP
|
|
Finally, there is a low\-level API for converting lookup requests and responses to and from raw lwres protocol packets\&. This API can be used by clients requiring nonblocking operation, and is also used when implementing the server side of the lwres protocol, for example in the
|
|
\fBlwresd\fR
|
|
resolver daemon\&. The use of this low\-level API in clients and servers is outlined in the following sections\&.
|
|
.SH "CLIENT-SIDE LOW-LEVEL API CALL FLOW"
|
|
.PP
|
|
When a client program wishes to make an lwres request using the native low\-level API, it typically performs the following sequence of actions\&.
|
|
.PP
|
|
(1) Allocate or use an existing
|
|
\fBlwres_packet_t\fR, called
|
|
\fIpkt\fR
|
|
below\&.
|
|
.PP
|
|
(2) Set
|
|
\fIpkt\&.recvlength\fR
|
|
to the maximum length we will accept\&. This is done so the receiver of our packets knows how large our receive buffer is\&. The "default" is a constant in
|
|
lwres\&.h:
|
|
\fBLWRES_RECVLENGTH = 4096\fR\&.
|
|
.PP
|
|
(3) Set
|
|
\fIpkt\&.serial\fR
|
|
to a unique serial number\&. This value is echoed back to the application by the remote server\&.
|
|
.PP
|
|
(4) Set
|
|
\fIpkt\&.pktflags\fR\&. Usually this is set to 0\&.
|
|
.PP
|
|
(5) Set
|
|
\fIpkt\&.result\fR
|
|
to 0\&.
|
|
.PP
|
|
(6) Call
|
|
\fBlwres_*request_render()\fR, or marshall in the data using the primitives such as
|
|
\fBlwres_packet_render()\fR
|
|
and storing the packet data\&.
|
|
.PP
|
|
(7) Transmit the resulting buffer\&.
|
|
.PP
|
|
(8) Call
|
|
\fBlwres_*response_parse()\fR
|
|
to parse any packets received\&.
|
|
.PP
|
|
(9) Verify that the opcode and serial match a request, and process the packet specific information contained in the body\&.
|
|
.SH "SERVER-SIDE LOW-LEVEL API CALL FLOW"
|
|
.PP
|
|
When implementing the server side of the lightweight resolver protocol using the lwres library, a sequence of actions like the following is typically involved in processing each request packet\&.
|
|
.PP
|
|
Note that the same
|
|
\fBlwres_packet_t\fR
|
|
is used in both the
|
|
\fB_parse()\fR
|
|
and
|
|
\fB_render()\fR
|
|
calls, with only a few modifications made to the packet header\*(Aqs contents between uses\&. This method is recommended as it keeps the serial, opcode, and other fields correct\&.
|
|
.PP
|
|
(1) When a packet is received, call
|
|
\fBlwres_*request_parse()\fR
|
|
to unmarshall it\&. This returns a
|
|
\fBlwres_packet_t\fR
|
|
(also called
|
|
\fIpkt\fR, below) as well as a data specific type, such as
|
|
\fBlwres_gabnrequest_t\fR\&.
|
|
.PP
|
|
(2) Process the request in the data specific type\&.
|
|
.PP
|
|
(3) Set the
|
|
\fIpkt\&.result\fR,
|
|
\fIpkt\&.recvlength\fR
|
|
as above\&. All other fields can be left untouched since they were filled in by the
|
|
\fB*_parse()\fR
|
|
call above\&. If using
|
|
\fBlwres_*response_render()\fR,
|
|
\fIpkt\&.pktflags\fR
|
|
will be set up properly\&. Otherwise, the
|
|
\fBLWRES_LWPACKETFLAG_RESPONSE\fR
|
|
bit should be set\&.
|
|
.PP
|
|
(4) Call the data specific rendering function, such as
|
|
\fBlwres_gabnresponse_render()\fR\&.
|
|
.PP
|
|
(5) Send the resulting packet to the client\&.
|
|
.PP
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
\fBlwres_gethostent\fR(3),
|
|
\fBlwres_getipnode\fR(3),
|
|
\fBlwres_getnameinfo\fR(3),
|
|
\fBlwres_noop\fR(3),
|
|
\fBlwres_gabn\fR(3),
|
|
\fBlwres_gnba\fR(3),
|
|
\fBlwres_context\fR(3),
|
|
\fBlwres_config\fR(3),
|
|
\fBresolver\fR(5),
|
|
\fBlwresd\fR(8)\&.
|
|
.SH "AUTHOR"
|
|
.PP
|
|
\fBInternet Systems Consortium, Inc\&.\fR
|
|
.SH "COPYRIGHT"
|
|
.br
|
|
Copyright \(co 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
|
|
.br
|