]> CyberLeo.Net >> Repos - FreeBSD/releng/9.0.git/blob - contrib/bind9/bin/named/include/named/client.h
Copy stable/9 to releng/9.0 as part of the FreeBSD 9.0-RELEASE release
[FreeBSD/releng/9.0.git] / contrib / bind9 / bin / named / include / named / client.h
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.91 2009-10-26 23:14:53 each 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
84 typedef ISC_LIST(ns_client_t) client_list_t;
85
86 /*% nameserver client structure */
87 struct 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         isc_boolean_t           needshutdown;   /*
101                                                  * Used by clienttest to get
102                                                  * the client to go from
103                                                  * inactive to free state
104                                                  * by shutting down the
105                                                  * client's task.
106                                                  */
107         unsigned int            attributes;
108         isc_task_t *            task;
109         dns_view_t *            view;
110         dns_dispatch_t *        dispatch;
111         isc_socket_t *          udpsocket;
112         isc_socket_t *          tcplistener;
113         isc_socket_t *          tcpsocket;
114         unsigned char *         tcpbuf;
115         dns_tcpmsg_t            tcpmsg;
116         isc_boolean_t           tcpmsg_valid;
117         isc_timer_t *           timer;
118         isc_boolean_t           timerset;
119         dns_message_t *         message;
120         isc_socketevent_t *     sendevent;
121         isc_socketevent_t *     recvevent;
122         unsigned char *         recvbuf;
123         dns_rdataset_t *        opt;
124         isc_uint16_t            udpsize;
125         isc_uint16_t            extflags;
126         isc_int16_t             ednsversion;    /* -1 noedns */
127         void                    (*next)(ns_client_t *);
128         void                    (*shutdown)(void *arg, isc_result_t result);
129         void                    *shutdown_arg;
130         ns_query_t              query;
131         isc_stdtime_t           requesttime;
132         isc_stdtime_t           now;
133         dns_name_t              signername;   /*%< [T]SIG key name */
134         dns_name_t *            signer;       /*%< NULL if not valid sig */
135         isc_boolean_t           mortal;       /*%< Die after handling request */
136         isc_quota_t             *tcpquota;
137         isc_quota_t             *recursionquota;
138         ns_interface_t          *interface;
139         isc_sockaddr_t          peeraddr;
140         isc_boolean_t           peeraddr_valid;
141         isc_netaddr_t           destaddr;
142         struct in6_pktinfo      pktinfo;
143         isc_event_t             ctlevent;
144         /*%
145          * Information about recent FORMERR response(s), for
146          * FORMERR loop avoidance.  This is separate for each
147          * client object rather than global only to avoid
148          * the need for locking.
149          */
150         struct {
151                 isc_sockaddr_t          addr;
152                 isc_stdtime_t           time;
153                 dns_messageid_t         id;
154         } formerrcache;
155         ISC_LINK(ns_client_t)   link;
156         /*%
157          * The list 'link' is part of, or NULL if not on any list.
158          */
159         client_list_t           *list;
160 };
161
162 #define NS_CLIENT_MAGIC                 ISC_MAGIC('N','S','C','c')
163 #define NS_CLIENT_VALID(c)              ISC_MAGIC_VALID(c, NS_CLIENT_MAGIC)
164
165 #define NS_CLIENTATTR_TCP               0x01
166 #define NS_CLIENTATTR_RA                0x02 /*%< Client gets recursive service */
167 #define NS_CLIENTATTR_PKTINFO           0x04 /*%< pktinfo is valid */
168 #define NS_CLIENTATTR_MULTICAST         0x08 /*%< recv'd from multicast */
169 #define NS_CLIENTATTR_WANTDNSSEC        0x10 /*%< include dnssec records */
170 #define NS_CLIENTATTR_WANTNSID          0x20 /*%< include nameserver ID */
171 #ifdef ALLOW_FILTER_AAAA_ON_V4
172 #define NS_CLIENTATTR_FILTER_AAAA       0x40 /*%< suppress AAAAs */
173 #define NS_CLIENTATTR_FILTER_AAAA_RC    0x80 /*%< recursing for A against AAAA */
174 #endif
175
176 extern unsigned int ns_client_requests;
177
178 /***
179  *** Functions
180  ***/
181
182 /*%
183  * Note!  These ns_client_ routines MUST be called ONLY from the client's
184  * task in order to ensure synchronization.
185  */
186
187 void
188 ns_client_send(ns_client_t *client);
189 /*%
190  * Finish processing the current client request and
191  * send client->message as a response.
192  * \brief
193  * Note!  These ns_client_ routines MUST be called ONLY from the client's
194  * task in order to ensure synchronization.
195  */
196
197 void
198 ns_client_sendraw(ns_client_t *client, dns_message_t *msg);
199 /*%
200  * Finish processing the current client request and
201  * send msg as a response using client->message->id for the id.
202  */
203
204 void
205 ns_client_error(ns_client_t *client, isc_result_t result);
206 /*%
207  * Finish processing the current client request and return
208  * an error response to the client.  The error response
209  * will have an RCODE determined by 'result'.
210  */
211
212 void
213 ns_client_next(ns_client_t *client, isc_result_t result);
214 /*%
215  * Finish processing the current client request,
216  * return no response to the client.
217  */
218
219 isc_boolean_t
220 ns_client_shuttingdown(ns_client_t *client);
221 /*%
222  * Return ISC_TRUE iff the client is currently shutting down.
223  */
224
225 void
226 ns_client_attach(ns_client_t *source, ns_client_t **target);
227 /*%
228  * Attach '*targetp' to 'source'.
229  */
230
231 void
232 ns_client_detach(ns_client_t **clientp);
233 /*%
234  * Detach '*clientp' from its client.
235  */
236
237 isc_result_t
238 ns_client_replace(ns_client_t *client);
239 /*%
240  * Try to replace the current client with a new one, so that the
241  * current one can go off and do some lengthy work without
242  * leaving the dispatch/socket without service.
243  */
244
245 void
246 ns_client_settimeout(ns_client_t *client, unsigned int seconds);
247 /*%
248  * Set a timer in the client to go off in the specified amount of time.
249  */
250
251 isc_result_t
252 ns_clientmgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr,
253                     isc_timermgr_t *timermgr, ns_clientmgr_t **managerp);
254 /*%
255  * Create a client manager.
256  */
257
258 void
259 ns_clientmgr_destroy(ns_clientmgr_t **managerp);
260 /*%
261  * Destroy a client manager and all ns_client_t objects
262  * managed by it.
263  */
264
265 isc_result_t
266 ns_clientmgr_createclients(ns_clientmgr_t *manager, unsigned int n,
267                            ns_interface_t *ifp, isc_boolean_t tcp);
268 /*%
269  * Create up to 'n' clients listening on interface 'ifp'.
270  * If 'tcp' is ISC_TRUE, the clients will listen for TCP connections,
271  * otherwise for UDP requests.
272  */
273
274 isc_sockaddr_t *
275 ns_client_getsockaddr(ns_client_t *client);
276 /*%
277  * Get the socket address of the client whose request is
278  * currently being processed.
279  */
280
281 isc_result_t
282 ns_client_checkaclsilent(ns_client_t *client, isc_netaddr_t *netaddr,
283                          dns_acl_t *acl, isc_boolean_t default_allow);
284
285 /*%
286  * Convenience function for client request ACL checking.
287  *
288  * Check the current client request against 'acl'.  If 'acl'
289  * is NULL, allow the request iff 'default_allow' is ISC_TRUE.
290  * If netaddr is NULL, check the ACL against client->peeraddr;
291  * otherwise check it against netaddr.
292  *
293  * Notes:
294  *\li   This is appropriate for checking allow-update,
295  *      allow-query, allow-transfer, etc.  It is not appropriate
296  *      for checking the blackhole list because we treat positive
297  *      matches as "allow" and negative matches as "deny"; in
298  *      the case of the blackhole list this would be backwards.
299  *
300  * Requires:
301  *\li   'client' points to a valid client.
302  *\li   'netaddr' points to a valid address, or is NULL.
303  *\li   'acl' points to a valid ACL, or is NULL.
304  *
305  * Returns:
306  *\li   ISC_R_SUCCESS   if the request should be allowed
307  * \li  DNS_R_REFUSED   if the request should be denied
308  *\li   No other return values are possible.
309  */
310
311 isc_result_t
312 ns_client_checkacl(ns_client_t  *client,
313                    isc_sockaddr_t *sockaddr,
314                    const char *opname, dns_acl_t *acl,
315                    isc_boolean_t default_allow,
316                    int log_level);
317 /*%
318  * Like ns_client_checkaclsilent, except the outcome of the check is
319  * logged at log level 'log_level' if denied, and at debug 3 if approved.
320  * Log messages will refer to the request as an 'opname' request.
321  *
322  * Requires:
323  *\li   'client' points to a valid client.
324  *\li   'sockaddr' points to a valid address, or is NULL.
325  *\li   'acl' points to a valid ACL, or is NULL.
326  *\li   'opname' points to a null-terminated string.
327  */
328
329 void
330 ns_client_log(ns_client_t *client, isc_logcategory_t *category,
331               isc_logmodule_t *module, int level,
332               const char *fmt, ...) ISC_FORMAT_PRINTF(5, 6);
333
334 void
335 ns_client_logv(ns_client_t *client, isc_logcategory_t *category,
336                isc_logmodule_t *module, int level, const char *fmt, va_list ap) ISC_FORMAT_PRINTF(5, 0);
337
338 void
339 ns_client_aclmsg(const char *msg, dns_name_t *name, dns_rdatatype_t type,
340                  dns_rdataclass_t rdclass, char *buf, size_t len);
341
342 #define NS_CLIENT_ACLMSGSIZE(x) \
343         (DNS_NAME_FORMATSIZE + DNS_RDATATYPE_FORMATSIZE + \
344          DNS_RDATACLASS_FORMATSIZE + sizeof(x) + sizeof("'/'"))
345
346 void
347 ns_client_recursing(ns_client_t *client);
348 /*%
349  * Add client to end of th recursing list.
350  */
351
352 void
353 ns_client_killoldestquery(ns_client_t *client);
354 /*%
355  * Kill the oldest recursive query (recursing list head).
356  */
357
358 void
359 ns_client_dumprecursing(FILE *f, ns_clientmgr_t *manager);
360 /*%
361  * Dump the outstanding recursive queries to 'f'.
362  */
363
364 void
365 ns_client_qnamereplace(ns_client_t *client, dns_name_t *name);
366 /*%
367  * Replace the qname.
368  */
369
370 isc_boolean_t
371 ns_client_isself(dns_view_t *myview, dns_tsigkey_t *mykey,
372                  isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
373                  dns_rdataclass_t rdclass, void *arg);
374 /*%
375  * Isself callback.
376  */
377
378 #endif /* NAMED_CLIENT_H */