2 * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2003 Internet Software Consortium.
5 * Permission to use, copy, modify, and 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: view.h,v 1.73.2.4.2.12 2004/03/10 02:55:58 marka Exp $ */
30 * A "view" is a DNS namespace, together with an optional resolver and a
31 * forwarding policy. A "DNS namespace" is a (possibly empty) set of
32 * authoritative zones together with an optional cache and optional
33 * "hints" information.
35 * Views start out "unfrozen". In this state, core attributes like
36 * the cache, set of zones, and forwarding policy may be set. While
37 * "unfrozen", the caller (e.g. nameserver configuration loading
38 * code), must ensure exclusive access to the view. When the view is
39 * "frozen", the core attributes become immutable, and the view module
40 * will ensure synchronization. Freezing allows the view's core attributes
41 * to be accessed without locking.
44 * Before the view is frozen, the caller must ensure synchronization.
46 * After the view is frozen, the module guarantees appropriate
47 * synchronization of any data structures it creates and manipulates.
50 * No anticipated impact.
56 * No anticipated impact.
65 #include <isc/magic.h>
66 #include <isc/event.h>
67 #include <isc/mutex.h>
69 #include <isc/refcount.h>
70 #include <isc/rwlock.h>
71 #include <isc/stdtime.h>
74 #include <dns/fixedname.h>
75 #include <dns/types.h>
83 dns_rdataclass_t rdclass;
86 dns_resolver_t * resolver;
88 dns_requestmgr_t * requestmgr;
92 dns_keytable_t * secroots;
93 dns_keytable_t * trustedkeys;
100 /* Configurable data. */
101 dns_tsig_keyring_t * statickeys;
102 dns_tsig_keyring_t * dynamickeys;
103 dns_peerlist_t * peers;
105 dns_fwdtable_t * fwdtable;
106 isc_boolean_t recursion;
107 isc_boolean_t auth_nxdomain;
108 isc_boolean_t additionalfromcache;
109 isc_boolean_t additionalfromauth;
110 isc_boolean_t minimalresponses;
111 isc_boolean_t enablednssec;
112 dns_transfer_format_t transfer_format;
113 dns_acl_t * queryacl;
114 dns_acl_t * recursionacl;
115 dns_acl_t * sortlist;
116 isc_boolean_t requestixfr;
117 isc_boolean_t provideixfr;
118 dns_ttl_t maxcachettl;
119 dns_ttl_t maxncachettl;
122 dns_rdatatype_t preferred_glue;
124 dns_namelist_t * delonly;
125 isc_boolean_t rootdelonly;
126 dns_namelist_t * rootexclude;
127 isc_boolean_t checknames;
129 dns_fixedname_t dlv_fixed;
132 * Configurable data for server use only,
133 * locked by server configuration lock.
135 dns_acl_t * matchclients;
136 dns_acl_t * matchdestinations;
137 isc_boolean_t matchrecursiveonly;
139 /* Locked by themselves. */
140 isc_refcount_t references;
142 /* Locked by lock. */
143 unsigned int weakrefs;
144 unsigned int attributes;
145 /* Under owner's locking control. */
146 ISC_LINK(struct dns_view) link;
149 #define DNS_VIEW_MAGIC ISC_MAGIC('V','i','e','w')
150 #define DNS_VIEW_VALID(view) ISC_MAGIC_VALID(view, DNS_VIEW_MAGIC)
152 #define DNS_VIEWATTR_RESSHUTDOWN 0x01
153 #define DNS_VIEWATTR_ADBSHUTDOWN 0x02
154 #define DNS_VIEWATTR_REQSHUTDOWN 0x04
157 dns_view_create(isc_mem_t *mctx, dns_rdataclass_t rdclass,
158 const char *name, dns_view_t **viewp);
164 * The newly created view has no cache, no resolver, and an empty
165 * zone table. The view is not frozen.
169 * 'mctx' is a valid memory context.
171 * 'rdclass' is a valid class.
173 * 'name' is a valid C string.
175 * viewp != NULL && *viewp == NULL
182 * Other errors are possible.
186 dns_view_attach(dns_view_t *source, dns_view_t **targetp);
188 * Attach '*targetp' to 'source'.
192 * 'source' is a valid, frozen view.
194 * 'targetp' points to a NULL dns_view_t *.
198 * *targetp is attached to source.
200 * While *targetp is attached, the view will not shut down.
204 dns_view_detach(dns_view_t **viewp);
206 * Detach '*viewp' from its view.
210 * 'viewp' points to a valid dns_view_t *
218 dns_view_flushanddetach(dns_view_t **viewp);
220 * Detach '*viewp' from its view. If this was the last reference
221 * uncommited changed in zones will be flushed to disk.
225 * 'viewp' points to a valid dns_view_t *
233 dns_view_weakattach(dns_view_t *source, dns_view_t **targetp);
235 * Weakly attach '*targetp' to 'source'.
239 * 'source' is a valid, frozen view.
241 * 'targetp' points to a NULL dns_view_t *.
245 * *targetp is attached to source.
247 * While *targetp is attached, the view will not be freed.
251 dns_view_weakdetach(dns_view_t **targetp);
253 * Detach '*viewp' from its view.
257 * 'viewp' points to a valid dns_view_t *.
265 dns_view_createresolver(dns_view_t *view,
266 isc_taskmgr_t *taskmgr, unsigned int ntasks,
267 isc_socketmgr_t *socketmgr,
268 isc_timermgr_t *timermgr,
269 unsigned int options,
270 dns_dispatchmgr_t *dispatchmgr,
271 dns_dispatch_t *dispatchv4,
272 dns_dispatch_t *dispatchv6);
274 * Create a resolver and address database for the view.
278 * 'view' is a valid, unfrozen view.
280 * 'view' does not have a resolver already.
282 * The requirements of dns_resolver_create() apply to 'taskmgr',
283 * 'ntasks', 'socketmgr', 'timermgr', 'options', 'dispatchv4', and
290 * Any error that dns_resolver_create() can return.
294 dns_view_setcache(dns_view_t *view, dns_cache_t *cache);
296 * Set the view's cache database.
300 * 'view' is a valid, unfrozen view.
302 * 'cache' is a valid cache.
306 * The cache of 'view' is 'cached.
308 * If this is not the first call to dns_view_setcache() for this
309 * view, then previously set cache is detached.
313 dns_view_sethints(dns_view_t *view, dns_db_t *hints);
315 * Set the view's hints database.
319 * 'view' is a valid, unfrozen view, whose hints database has not been
322 * 'hints' is a valid zone database.
326 * The hints database of 'view' is 'hints'.
330 dns_view_setkeyring(dns_view_t *view, dns_tsig_keyring_t *ring);
332 * Set the view's static TSIG keys
336 * 'view' is a valid, unfrozen view, whose static TSIG keyring has not
339 * 'ring' is a valid TSIG keyring
343 * The static TSIG keyring of 'view' is 'ring'.
347 dns_view_setdstport(dns_view_t *view, in_port_t dstport);
349 * Set the view's destination port. This is the port to
350 * which outgoing queries are sent. The default is 53,
351 * the standard DNS port.
355 * 'view' is a valid view.
357 * 'dstport' is a valid TCP/UDP port number.
360 * External name servers will be assumed to be listning
361 * on 'dstport'. For servers whose address has already
362 * obtained obtained at the time of the call, the view may
363 * continue to use the previously set port until the address
364 * times out from the view's address database.
369 dns_view_addzone(dns_view_t *view, dns_zone_t *zone);
371 * Add zone 'zone' to 'view'.
375 * 'view' is a valid, unfrozen view.
377 * 'zone' is a valid zone.
381 dns_view_freeze(dns_view_t *view);
387 * 'view' is a valid, unfrozen view.
395 dns_view_find(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type,
396 isc_stdtime_t now, unsigned int options, isc_boolean_t use_hints,
397 dns_db_t **dbp, dns_dbnode_t **nodep, dns_name_t *foundname,
398 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
400 * Find an rdataset whose owner name is 'name', and whose type is
405 * See the description of dns_db_find() for information about 'options'.
406 * If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name'
407 * and 'type' are appropriate for glue retrieval.
409 * If 'now' is zero, then the current time will be used.
411 * If 'use_hints' is ISC_TRUE, and the view has a hints database, then
412 * it will be searched last. If the answer is found in the hints
413 * database, the result code will be DNS_R_HINT. If the name is found
414 * in the hints database but not the type, the result code will be
417 * 'foundname' must meet the requirements of dns_db_find().
419 * If 'sigrdataset' is not NULL, and there is a SIG rdataset which
420 * covers 'type', then 'sigrdataset' will be bound to it.
424 * 'view' is a valid, frozen view.
426 * 'name' is valid name.
428 * 'type' is a valid dns_rdatatype_t, and is not a meta query type
429 * except dns_rdatatype_any.
431 * dbp == NULL || *dbp == NULL
433 * nodep == NULL || *nodep == NULL. If nodep != NULL, dbp != NULL.
435 * 'foundname' is a valid name with a dedicated buffer or NULL.
437 * 'rdataset' is a valid, disassociated rdataset.
439 * 'sigrdataset' is NULL, or is a valid, disassociated rdataset.
443 * In successful cases, 'rdataset', and possibly 'sigrdataset', are
444 * bound to the found data.
446 * If dbp != NULL, it points to the database containing the data.
448 * If nodep != NULL, it points to the database node containing the data.
450 * If foundname != NULL, it contains the full name of the found data.
454 * Any result that dns_db_find() can return, with the exception of
459 dns_view_simplefind(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type,
460 isc_stdtime_t now, unsigned int options,
461 isc_boolean_t use_hints,
462 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
464 * Find an rdataset whose owner name is 'name', and whose type is
469 * This routine is appropriate for simple, exact-match queries of the
470 * view. 'name' must be a canonical name; there is no DNAME or CNAME
473 * See the description of dns_db_find() for information about 'options'.
474 * If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name'
475 * and 'type' are appropriate for glue retrieval.
477 * If 'now' is zero, then the current time will be used.
479 * If 'use_hints' is ISC_TRUE, and the view has a hints database, then
480 * it will be searched last. If the answer is found in the hints
481 * database, the result code will be DNS_R_HINT. If the name is found
482 * in the hints database but not the type, the result code will be
485 * If 'sigrdataset' is not NULL, and there is a SIG rdataset which
486 * covers 'type', then 'sigrdataset' will be bound to it.
490 * 'view' is a valid, frozen view.
492 * 'name' is valid name.
494 * 'type' is a valid dns_rdatatype_t, and is not a meta query type
495 * (e.g. dns_rdatatype_any), or dns_rdatatype_rrsig.
497 * 'rdataset' is a valid, disassociated rdataset.
499 * 'sigrdataset' is NULL, or is a valid, disassociated rdataset.
503 * In successful cases, 'rdataset', and possibly 'sigrdataset', are
504 * bound to the found data.
508 * ISC_R_SUCCESS Success; result is desired type.
509 * DNS_R_GLUE Success; result is glue.
510 * DNS_R_HINT Success; result is a hint.
511 * DNS_R_NCACHENXDOMAIN Success; result is a ncache entry.
512 * DNS_R_NCACHENXRRSET Success; result is a ncache entry.
513 * DNS_R_NXDOMAIN The name does not exist.
514 * DNS_R_NXRRSET The rrset does not exist.
515 * ISC_R_NOTFOUND No matching data found,
516 * or an error occurred.
520 dns_view_findzonecut(dns_view_t *view, dns_name_t *name, dns_name_t *fname,
521 isc_stdtime_t now, unsigned int options,
522 isc_boolean_t use_hints,
523 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
526 dns_view_findzonecut2(dns_view_t *view, dns_name_t *name, dns_name_t *fname,
527 isc_stdtime_t now, unsigned int options,
528 isc_boolean_t use_hints, isc_boolean_t use_cache,
529 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
531 * Find the best known zonecut containing 'name'.
533 * This uses local authority, cache, and optionally hints data.
534 * No external queries are performed.
538 * If 'now' is zero, then the current time will be used.
540 * If 'use_hints' is ISC_TRUE, and the view has a hints database, then
541 * it will be searched last.
543 * If 'use_cache' is ISC_TRUE, and the view has a cache, then it will be
546 * If 'sigrdataset' is not NULL, and there is a SIG rdataset which
547 * covers 'type', then 'sigrdataset' will be bound to it.
549 * If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned
550 * (if any) will be the deepest known ancestor of 'name'.
554 * 'view' is a valid, frozen view.
556 * 'name' is valid name.
558 * 'rdataset' is a valid, disassociated rdataset.
560 * 'sigrdataset' is NULL, or is a valid, disassociated rdataset.
564 * ISC_R_SUCCESS Success.
566 * Many other results are possible.
570 dns_viewlist_find(dns_viewlist_t *list, const char *name,
571 dns_rdataclass_t rdclass, dns_view_t **viewp);
573 * Search for a view with name 'name' and class 'rdclass' in 'list'.
574 * If found, '*viewp' is (strongly) attached to it.
578 * 'viewp' points to a NULL dns_view_t *.
582 * ISC_R_SUCCESS A matching view was found.
583 * ISC_R_NOTFOUND No matching view was found.
587 dns_view_findzone(dns_view_t *view, dns_name_t *name, dns_zone_t **zonep);
589 * Search for the zone 'name' in the zone table of 'view'.
590 * If found, 'zonep' is (strongly) attached to it. There
591 * are no partial matches.
595 * 'zonep' points to a NULL dns_zone_t *.
598 * ISC_R_SUCCESS A matching zone was found.
599 * ISC_R_NOTFOUND No matching zone was found.
600 * others An error occurred.
604 dns_view_load(dns_view_t *view, isc_boolean_t stop);
607 dns_view_loadnew(dns_view_t *view, isc_boolean_t stop);
609 * Load zones attached to this view. dns_view_load() loads
610 * all zones whose master file has changed since the last
611 * load; dns_view_loadnew() loads only zones that have never
614 * If 'stop' is ISC_TRUE, stop on the first error and return it.
615 * If 'stop' is ISC_FALSE, ignore errors.
623 dns_view_gettsig(dns_view_t *view, dns_name_t *keyname,
624 dns_tsigkey_t **keyp);
626 * Find the TSIG key configured in 'view' with name 'keyname',
630 * keyp points to a NULL dns_tsigkey_t *.
633 * ISC_R_SUCCESS A key was found and '*keyp' now points to it.
634 * ISC_R_NOTFOUND No key was found.
635 * others An error occurred.
639 dns_view_getpeertsig(dns_view_t *view, isc_netaddr_t *peeraddr,
640 dns_tsigkey_t **keyp);
642 * Find the TSIG key configured in 'view' for the server whose
643 * address is 'peeraddr', if any.
646 * keyp points to a NULL dns_tsigkey_t *.
649 * ISC_R_SUCCESS A key was found and '*keyp' now points to it.
650 * ISC_R_NOTFOUND No key was found.
651 * others An error occurred.
655 dns_view_checksig(dns_view_t *view, isc_buffer_t *source, dns_message_t *msg);
657 * Verifies the signature of a message.
661 * 'view' is a valid view.
662 * 'source' is a valid buffer containing the message
663 * 'msg' is a valid message
666 * see dns_tsig_verify()
670 dns_view_dialup(dns_view_t *view);
672 * Perform dialup-time maintenance on the zones of 'view'.
676 dns_view_dumpdbtostream(dns_view_t *view, FILE *fp);
678 * Dump the current state of the view 'view' to the stream 'fp'
679 * for purposes of analysis or debugging.
681 * Currently the dumped state includes the view's cache; in the future
682 * it may also include other state such as the address database.
683 * It will not not include authoritative data since it is voluminous and
684 * easily obtainable by other means.
690 * 'fp' refers to a file open for writing.
693 * ISC_R_SUCCESS The cache was successfully dumped.
694 * others An error occurred (see dns_master_dump)
698 dns_view_flushcache(dns_view_t *view);
700 * Flush the view's cache (and ADB).
705 * No other tasks are executing.
713 dns_view_flushname(dns_view_t *view, dns_name_t *);
715 * Flush the given name from the view's cache (and ADB).
723 * other returns are failures.
727 dns_view_adddelegationonly(dns_view_t *view, dns_name_t *name);
729 * Add the given name to the delegation only table.
742 dns_view_excludedelegationonly(dns_view_t *view, dns_name_t *name);
744 * Add the given name to be excluded from the root-delegation-only.
757 dns_view_isdelegationonly(dns_view_t *view, dns_name_t *name);
759 * Check if 'name' is in the delegation only table or if
760 * rootdelonly is set that name is not being excluded.
767 * ISC_TRUE if the name is is the table.
768 * ISC_FALSE othewise.
772 dns_view_setrootdelonly(dns_view_t *view, isc_boolean_t value);
774 * Set the root delegation only flag.
781 dns_view_getrootdelonly(dns_view_t *view);
783 * Get the root delegation only flag.
789 #endif /* DNS_VIEW_H */