2 * Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2003 Internet Software Consortium.
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.
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.
18 /* $Id: client.h,v 1.82.128.4 2009/01/19 23:47:01 tbox Exp $ */
20 #ifndef NAMED_CLIENT_H
21 #define NAMED_CLIENT_H 1
29 * This module defines two objects, ns_client_t and ns_clientmgr_t.
31 * An ns_client_t object handles incoming DNS requests from clients
32 * on a given network interface.
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
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:
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)
52 * This will release any resources used by the request and
53 * and allow the ns_client_t to listen for the next request.
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.
65 #include <isc/buffer.h>
66 #include <isc/magic.h>
67 #include <isc/stdtime.h>
68 #include <isc/quota.h>
70 #include <dns/fixedname.h>
72 #include <dns/rdataclass.h>
73 #include <dns/rdatatype.h>
74 #include <dns/tcpmsg.h>
75 #include <dns/types.h>
77 #include <named/types.h>
78 #include <named/query.h>
84 typedef ISC_LIST(ns_client_t
) client_list_t
;
86 /*% nameserver client structure */
90 ns_clientmgr_t
* manager
;
100 unsigned int attributes
;
103 dns_dispatch_t
* dispatch
;
104 isc_socket_t
* udpsocket
;
105 isc_socket_t
* tcplistener
;
106 isc_socket_t
* tcpsocket
;
107 unsigned char * tcpbuf
;
109 isc_boolean_t tcpmsg_valid
;
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
);
124 isc_stdtime_t requesttime
;
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
;
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.
147 ISC_LINK(ns_client_t
) link
;
149 * The list 'link' is part of, or NULL if not on any list.
154 #define NS_CLIENT_MAGIC ISC_MAGIC('N','S','C','c')
155 #define NS_CLIENT_VALID(c) ISC_MAGIC_VALID(c, NS_CLIENT_MAGIC)
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 */
164 extern unsigned int ns_client_requests
;
171 * Note! These ns_client_ routines MUST be called ONLY from the client's
172 * task in order to ensure synchronization.
176 ns_client_send(ns_client_t
*client
);
178 * Finish processing the current client request and
179 * send client->message as a response.
181 * Note! These ns_client_ routines MUST be called ONLY from the client's
182 * task in order to ensure synchronization.
186 ns_client_sendraw(ns_client_t
*client
, dns_message_t
*msg
);
188 * Finish processing the current client request and
189 * send msg as a response using client->message->id for the id.
193 ns_client_error(ns_client_t
*client
, isc_result_t result
);
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'.
201 ns_client_next(ns_client_t
*client
, isc_result_t result
);
203 * Finish processing the current client request,
204 * return no response to the client.
208 ns_client_shuttingdown(ns_client_t
*client
);
210 * Return ISC_TRUE iff the client is currently shutting down.
214 ns_client_attach(ns_client_t
*source
, ns_client_t
**target
);
216 * Attach '*targetp' to 'source'.
220 ns_client_detach(ns_client_t
**clientp
);
222 * Detach '*clientp' from its client.
226 ns_client_replace(ns_client_t
*client
);
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.
234 ns_client_settimeout(ns_client_t
*client
, unsigned int seconds
);
236 * Set a timer in the client to go off in the specified amount of time.
240 ns_clientmgr_create(isc_mem_t
*mctx
, isc_taskmgr_t
*taskmgr
,
241 isc_timermgr_t
*timermgr
, ns_clientmgr_t
**managerp
);
243 * Create a client manager.
247 ns_clientmgr_destroy(ns_clientmgr_t
**managerp
);
249 * Destroy a client manager and all ns_client_t objects
254 ns_clientmgr_createclients(ns_clientmgr_t
*manager
, unsigned int n
,
255 ns_interface_t
*ifp
, isc_boolean_t tcp
);
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.
263 ns_client_getsockaddr(ns_client_t
*client
);
265 * Get the socket address of the client whose request is
266 * currently being processed.
270 ns_client_checkaclsilent(ns_client_t
*client
,
271 isc_sockaddr_t
*sockaddr
,
273 isc_boolean_t default_allow
);
276 * Convenience function for client request ACL checking.
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.
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.
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.
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.
302 ns_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
,
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.
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.
320 ns_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);
325 ns_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);
329 ns_client_aclmsg(const char *msg
, dns_name_t
*name
, dns_rdatatype_t type
,
330 dns_rdataclass_t rdclass
, char *buf
, size_t len
);
332 #define NS_CLIENT_ACLMSGSIZE(x) \
333 (DNS_NAME_FORMATSIZE + DNS_RDATATYPE_FORMATSIZE + \
334 DNS_RDATACLASS_FORMATSIZE + sizeof(x) + sizeof("'/'"))
337 ns_client_recursing(ns_client_t
*client
);
339 * Add client to end of th recursing list.
343 ns_client_killoldestquery(ns_client_t
*client
);
345 * Kill the oldest recursive query (recursing list head).
349 ns_client_dumprecursing(FILE *f
, ns_clientmgr_t
*manager
);
351 * Dump the outstanding recursive queries to 'f'.
355 ns_client_qnamereplace(ns_client_t
*client
, dns_name_t
*name
);
361 ns_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
);
368 #endif /* NAMED_CLIENT_H */