BIND: update vendor tree to 9.5.2-P2
[dragonfly.git] / contrib / bind / bin / named / include / named / client.h
CommitLineData
bbbf71a3
JL
1/*
2 * Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2003 Internet Software Consortium.
4 *
5 * Permission to use, copy, modify, and/or distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
8 *
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
16 */
17
18/* $Id: client.h,v 1.82.128.4 2009/01/19 23:47:01 tbox Exp $ */
19
20#ifndef NAMED_CLIENT_H
21#define NAMED_CLIENT_H 1
22
23/*****
24 ***** Module Info
25 *****/
26
27/*! \file
28 * \brief
29 * This module defines two objects, ns_client_t and ns_clientmgr_t.
30 *
31 * An ns_client_t object handles incoming DNS requests from clients
32 * on a given network interface.
33 *
34 * Each ns_client_t object can handle only one TCP connection or UDP
35 * request at a time. Therefore, several ns_client_t objects are
36 * typically created to serve each network interface, e.g., one
37 * for handling TCP requests and a few (one per CPU) for handling
38 * UDP requests.
39 *
40 * Incoming requests are classified as queries, zone transfer
41 * requests, update requests, notify requests, etc, and handed off
42 * to the appropriate request handler. When the request has been
43 * fully handled (which can be much later), the ns_client_t must be
44 * notified of this by calling one of the following functions
45 * exactly once in the context of its task:
46 * \code
47 * ns_client_send() (sending a non-error response)
48 * ns_client_sendraw() (sending a raw response)
49 * ns_client_error() (sending an error response)
50 * ns_client_next() (sending no response)
51 *\endcode
52 * This will release any resources used by the request and
53 * and allow the ns_client_t to listen for the next request.
54 *
55 * A ns_clientmgr_t manages a number of ns_client_t objects.
56 * New ns_client_t objects are created by calling
57 * ns_clientmgr_createclients(). They are destroyed by
58 * destroying their manager.
59 */
60
61/***
62 *** Imports
63 ***/
64
65#include <isc/buffer.h>
66#include <isc/magic.h>
67#include <isc/stdtime.h>
68#include <isc/quota.h>
69
70#include <dns/fixedname.h>
71#include <dns/name.h>
72#include <dns/rdataclass.h>
73#include <dns/rdatatype.h>
74#include <dns/tcpmsg.h>
75#include <dns/types.h>
76
77#include <named/types.h>
78#include <named/query.h>
79
80/***
81 *** Types
82 ***/
83
84typedef ISC_LIST(ns_client_t) client_list_t;
85
86/*% nameserver client structure */
87struct ns_client {
88 unsigned int magic;
89 isc_mem_t * mctx;
90 ns_clientmgr_t * manager;
91 int state;
92 int newstate;
93 int naccepts;
94 int nreads;
95 int nsends;
96 int nrecvs;
97 int nupdates;
98 int nctls;
99 int references;
100 unsigned int attributes;
101 isc_task_t * task;
102 dns_view_t * view;
103 dns_dispatch_t * dispatch;
104 isc_socket_t * udpsocket;
105 isc_socket_t * tcplistener;
106 isc_socket_t * tcpsocket;
107 unsigned char * tcpbuf;
108 dns_tcpmsg_t tcpmsg;
109 isc_boolean_t tcpmsg_valid;
110 isc_timer_t * timer;
111 isc_boolean_t timerset;
112 dns_message_t * message;
113 isc_socketevent_t * sendevent;
114 isc_socketevent_t * recvevent;
115 unsigned char * recvbuf;
116 dns_rdataset_t * opt;
117 isc_uint16_t udpsize;
118 isc_uint16_t extflags;
119 isc_int16_t ednsversion; /* -1 noedns */
120 void (*next)(ns_client_t *);
121 void (*shutdown)(void *arg, isc_result_t result);
122 void *shutdown_arg;
123 ns_query_t query;
124 isc_stdtime_t requesttime;
125 isc_stdtime_t now;
126 dns_name_t signername; /*%< [T]SIG key name */
127 dns_name_t * signer; /*%< NULL if not valid sig */
128 isc_boolean_t mortal; /*%< Die after handling request */
129 isc_quota_t *tcpquota;
130 isc_quota_t *recursionquota;
131 ns_interface_t *interface;
132 isc_sockaddr_t peeraddr;
133 isc_boolean_t peeraddr_valid;
134 struct in6_pktinfo pktinfo;
135 isc_event_t ctlevent;
136 /*%
137 * Information about recent FORMERR response(s), for
138 * FORMERR loop avoidance. This is separate for each
139 * client object rather than global only to avoid
140 * the need for locking.
141 */
142 struct {
143 isc_sockaddr_t addr;
144 isc_stdtime_t time;
145 dns_messageid_t id;
146 } formerrcache;
147 ISC_LINK(ns_client_t) link;
148 /*%
149 * The list 'link' is part of, or NULL if not on any list.
150 */
151 client_list_t *list;
152};
153
154#define NS_CLIENT_MAGIC ISC_MAGIC('N','S','C','c')
155#define NS_CLIENT_VALID(c) ISC_MAGIC_VALID(c, NS_CLIENT_MAGIC)
156
157#define NS_CLIENTATTR_TCP 0x01
158#define NS_CLIENTATTR_RA 0x02 /*%< Client gets recursive service */
159#define NS_CLIENTATTR_PKTINFO 0x04 /*%< pktinfo is valid */
160#define NS_CLIENTATTR_MULTICAST 0x08 /*%< recv'd from multicast */
161#define NS_CLIENTATTR_WANTDNSSEC 0x10 /*%< include dnssec records */
162#define NS_CLIENTATTR_WANTNSID 0x20 /*%< include nameserver ID */
163
164extern unsigned int ns_client_requests;
165
166/***
167 *** Functions
168 ***/
169
170/*%
171 * Note! These ns_client_ routines MUST be called ONLY from the client's
172 * task in order to ensure synchronization.
173 */
174
175void
176ns_client_send(ns_client_t *client);
177/*%
178 * Finish processing the current client request and
179 * send client->message as a response.
180 * \brief
181 * Note! These ns_client_ routines MUST be called ONLY from the client's
182 * task in order to ensure synchronization.
183 */
184
185void
186ns_client_sendraw(ns_client_t *client, dns_message_t *msg);
187/*%
188 * Finish processing the current client request and
189 * send msg as a response using client->message->id for the id.
190 */
191
192void
193ns_client_error(ns_client_t *client, isc_result_t result);
194/*%
195 * Finish processing the current client request and return
196 * an error response to the client. The error response
197 * will have an RCODE determined by 'result'.
198 */
199
200void
201ns_client_next(ns_client_t *client, isc_result_t result);
202/*%
203 * Finish processing the current client request,
204 * return no response to the client.
205 */
206
207isc_boolean_t
208ns_client_shuttingdown(ns_client_t *client);
209/*%
210 * Return ISC_TRUE iff the client is currently shutting down.
211 */
212
213void
214ns_client_attach(ns_client_t *source, ns_client_t **target);
215/*%
216 * Attach '*targetp' to 'source'.
217 */
218
219void
220ns_client_detach(ns_client_t **clientp);
221/*%
222 * Detach '*clientp' from its client.
223 */
224
225isc_result_t
226ns_client_replace(ns_client_t *client);
227/*%
228 * Try to replace the current client with a new one, so that the
229 * current one can go off and do some lengthy work without
230 * leaving the dispatch/socket without service.
231 */
232
233void
234ns_client_settimeout(ns_client_t *client, unsigned int seconds);
235/*%
236 * Set a timer in the client to go off in the specified amount of time.
237 */
238
239isc_result_t
240ns_clientmgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr,
241 isc_timermgr_t *timermgr, ns_clientmgr_t **managerp);
242/*%
243 * Create a client manager.
244 */
245
246void
247ns_clientmgr_destroy(ns_clientmgr_t **managerp);
248/*%
249 * Destroy a client manager and all ns_client_t objects
250 * managed by it.
251 */
252
253isc_result_t
254ns_clientmgr_createclients(ns_clientmgr_t *manager, unsigned int n,
255 ns_interface_t *ifp, isc_boolean_t tcp);
256/*%
257 * Create up to 'n' clients listening on interface 'ifp'.
258 * If 'tcp' is ISC_TRUE, the clients will listen for TCP connections,
259 * otherwise for UDP requests.
260 */
261
262isc_sockaddr_t *
263ns_client_getsockaddr(ns_client_t *client);
264/*%
265 * Get the socket address of the client whose request is
266 * currently being processed.
267 */
268
269isc_result_t
270ns_client_checkaclsilent(ns_client_t *client,
271 isc_sockaddr_t *sockaddr,
272 dns_acl_t *acl,
273 isc_boolean_t default_allow);
274
275/*%
276 * Convenience function for client request ACL checking.
277 *
278 * Check the current client request against 'acl'. If 'acl'
279 * is NULL, allow the request iff 'default_allow' is ISC_TRUE.
280 * If netaddr is NULL, check the ACL against client->peeraddr;
281 * otherwise check it against netaddr.
282 *
283 * Notes:
284 *\li This is appropriate for checking allow-update,
285 * allow-query, allow-transfer, etc. It is not appropriate
286 * for checking the blackhole list because we treat positive
287 * matches as "allow" and negative matches as "deny"; in
288 * the case of the blackhole list this would be backwards.
289 *
290 * Requires:
291 *\li 'client' points to a valid client.
292 *\li 'sockaddr' points to a valid address, or is NULL.
293 *\li 'acl' points to a valid ACL, or is NULL.
294 *
295 * Returns:
296 *\li ISC_R_SUCCESS if the request should be allowed
297 * \li ISC_R_REFUSED if the request should be denied
298 *\li No other return values are possible.
299 */
300
301isc_result_t
302ns_client_checkacl(ns_client_t *client,
303 isc_sockaddr_t *sockaddr,
304 const char *opname, dns_acl_t *acl,
305 isc_boolean_t default_allow,
306 int log_level);
307/*%
308 * Like ns_client_checkaclsilent, except the outcome of the check is
309 * logged at log level 'log_level' if denied, and at debug 3 if approved.
310 * Log messages will refer to the request as an 'opname' request.
311 *
312 * Requires:
313 *\li 'client' points to a valid client.
314 *\li 'sockaddr' points to a valid address, or is NULL.
315 *\li 'acl' points to a valid ACL, or is NULL.
316 *\li 'opname' points to a null-terminated string.
317 */
318
319void
320ns_client_log(ns_client_t *client, isc_logcategory_t *category,
321 isc_logmodule_t *module, int level,
322 const char *fmt, ...) ISC_FORMAT_PRINTF(5, 6);
323
324void
325ns_client_logv(ns_client_t *client, isc_logcategory_t *category,
326 isc_logmodule_t *module, int level, const char *fmt, va_list ap) ISC_FORMAT_PRINTF(5, 0);
327
328void
329ns_client_aclmsg(const char *msg, dns_name_t *name, dns_rdatatype_t type,
330 dns_rdataclass_t rdclass, char *buf, size_t len);
331
332#define NS_CLIENT_ACLMSGSIZE(x) \
333 (DNS_NAME_FORMATSIZE + DNS_RDATATYPE_FORMATSIZE + \
334 DNS_RDATACLASS_FORMATSIZE + sizeof(x) + sizeof("'/'"))
335
336void
337ns_client_recursing(ns_client_t *client);
338/*%
339 * Add client to end of th recursing list.
340 */
341
342void
343ns_client_killoldestquery(ns_client_t *client);
344/*%
345 * Kill the oldest recursive query (recursing list head).
346 */
347
348void
349ns_client_dumprecursing(FILE *f, ns_clientmgr_t *manager);
350/*%
351 * Dump the outstanding recursive queries to 'f'.
352 */
353
354void
355ns_client_qnamereplace(ns_client_t *client, dns_name_t *name);
356/*%
357 * Replace the qname.
358 */
359
360isc_boolean_t
361ns_client_isself(dns_view_t *myview, dns_tsigkey_t *mykey,
362 isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
363 dns_rdataclass_t rdclass, void *arg);
364/*%
365 * Isself callback.
366 */
367
368#endif /* NAMED_CLIENT_H */