2 * Copyright (C) 2004-2010 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: view.h,v 1.111.88.4.24.2 2010/09/29 23:46:31 tbox Exp $ */
31 * A "view" is a DNS namespace, together with an optional resolver and a
32 * forwarding policy. A "DNS namespace" is a (possibly empty) set of
33 * authoritative zones together with an optional cache and optional
34 * "hints" information.
36 * Views start out "unfrozen". In this state, core attributes like
37 * the cache, set of zones, and forwarding policy may be set. While
38 * "unfrozen", the caller (e.g. nameserver configuration loading
39 * code), must ensure exclusive access to the view. When the view is
40 * "frozen", the core attributes become immutable, and the view module
41 * will ensure synchronization. Freezing allows the view's core attributes
42 * to be accessed without locking.
45 *\li Before the view is frozen, the caller must ensure synchronization.
47 *\li After the view is frozen, the module guarantees appropriate
48 * synchronization of any data structures it creates and manipulates.
51 *\li No anticipated impact.
57 *\li No anticipated impact.
66 #include <isc/magic.h>
67 #include <isc/event.h>
68 #include <isc/mutex.h>
70 #include <isc/refcount.h>
71 #include <isc/rwlock.h>
72 #include <isc/stdtime.h>
75 #include <dns/fixedname.h>
76 #include <dns/types.h>
84 dns_rdataclass_t rdclass;
87 dns_dlzdb_t * dlzdatabase;
88 dns_resolver_t * resolver;
90 dns_requestmgr_t * requestmgr;
91 dns_acache_t * acache;
95 dns_keytable_t * secroots;
96 dns_keytable_t * trustedkeys;
100 isc_event_t resevent;
101 isc_event_t adbevent;
102 isc_event_t reqevent;
103 isc_stats_t * resstats;
104 dns_stats_t * resquerystats;
106 /* Configurable data. */
107 dns_tsig_keyring_t * statickeys;
108 dns_tsig_keyring_t * dynamickeys;
109 dns_peerlist_t * peers;
111 dns_fwdtable_t * fwdtable;
112 isc_boolean_t recursion;
113 isc_boolean_t auth_nxdomain;
114 isc_boolean_t additionalfromcache;
115 isc_boolean_t additionalfromauth;
116 isc_boolean_t minimalresponses;
117 isc_boolean_t enablednssec;
118 isc_boolean_t enablevalidation;
119 isc_boolean_t acceptexpired;
120 dns_transfer_format_t transfer_format;
121 dns_acl_t * cacheacl;
122 dns_acl_t * cacheonacl;
123 dns_acl_t * queryacl;
124 dns_acl_t * queryonacl;
125 dns_acl_t * recursionacl;
126 dns_acl_t * recursiononacl;
127 dns_acl_t * sortlist;
128 dns_acl_t * notifyacl;
129 dns_acl_t * transferacl;
130 dns_acl_t * updateacl;
131 dns_acl_t * upfwdacl;
132 isc_boolean_t requestixfr;
133 isc_boolean_t provideixfr;
134 isc_boolean_t requestnsid;
135 dns_ttl_t maxcachettl;
136 dns_ttl_t maxncachettl;
139 dns_rdatatype_t preferred_glue;
141 dns_namelist_t * delonly;
142 isc_boolean_t rootdelonly;
143 dns_namelist_t * rootexclude;
144 isc_boolean_t checknames;
146 dns_fixedname_t dlv_fixed;
150 * Configurable data for server use only,
151 * locked by server configuration lock.
153 dns_acl_t * matchclients;
154 dns_acl_t * matchdestinations;
155 isc_boolean_t matchrecursiveonly;
157 /* Locked by themselves. */
158 isc_refcount_t references;
160 /* Locked by lock. */
161 unsigned int weakrefs;
162 unsigned int attributes;
163 /* Under owner's locking control. */
164 ISC_LINK(struct dns_view) link;
167 #define DNS_VIEW_MAGIC ISC_MAGIC('V','i','e','w')
168 #define DNS_VIEW_VALID(view) ISC_MAGIC_VALID(view, DNS_VIEW_MAGIC)
170 #define DNS_VIEWATTR_RESSHUTDOWN 0x01
171 #define DNS_VIEWATTR_ADBSHUTDOWN 0x02
172 #define DNS_VIEWATTR_REQSHUTDOWN 0x04
175 dns_view_create(isc_mem_t *mctx, dns_rdataclass_t rdclass,
176 const char *name, dns_view_t **viewp);
182 *\li The newly created view has no cache, no resolver, and an empty
183 * zone table. The view is not frozen.
187 *\li 'mctx' is a valid memory context.
189 *\li 'rdclass' is a valid class.
191 *\li 'name' is a valid C string.
193 *\li viewp != NULL && *viewp == NULL
200 *\li Other errors are possible.
204 dns_view_attach(dns_view_t *source, dns_view_t **targetp);
206 * Attach '*targetp' to 'source'.
210 *\li 'source' is a valid, frozen view.
212 *\li 'targetp' points to a NULL dns_view_t *.
216 *\li *targetp is attached to source.
218 *\li While *targetp is attached, the view will not shut down.
222 dns_view_detach(dns_view_t **viewp);
224 * Detach '*viewp' from its view.
228 *\li 'viewp' points to a valid dns_view_t *
236 dns_view_flushanddetach(dns_view_t **viewp);
238 * Detach '*viewp' from its view. If this was the last reference
239 * uncommitted changed in zones will be flushed to disk.
243 *\li 'viewp' points to a valid dns_view_t *
251 dns_view_weakattach(dns_view_t *source, dns_view_t **targetp);
253 * Weakly attach '*targetp' to 'source'.
257 *\li 'source' is a valid, frozen view.
259 *\li 'targetp' points to a NULL dns_view_t *.
263 *\li *targetp is attached to source.
265 * \li While *targetp is attached, the view will not be freed.
269 dns_view_weakdetach(dns_view_t **targetp);
271 * Detach '*viewp' from its view.
275 *\li 'viewp' points to a valid dns_view_t *.
283 dns_view_createresolver(dns_view_t *view,
284 isc_taskmgr_t *taskmgr, unsigned int ntasks,
285 isc_socketmgr_t *socketmgr,
286 isc_timermgr_t *timermgr,
287 unsigned int options,
288 dns_dispatchmgr_t *dispatchmgr,
289 dns_dispatch_t *dispatchv4,
290 dns_dispatch_t *dispatchv6);
292 * Create a resolver and address database for the view.
296 *\li 'view' is a valid, unfrozen view.
298 *\li 'view' does not have a resolver already.
300 *\li The requirements of dns_resolver_create() apply to 'taskmgr',
301 * 'ntasks', 'socketmgr', 'timermgr', 'options', 'dispatchv4', and
308 *\li Any error that dns_resolver_create() can return.
312 dns_view_setcache(dns_view_t *view, dns_cache_t *cache);
314 * Set the view's cache database.
318 *\li 'view' is a valid, unfrozen view.
320 *\li 'cache' is a valid cache.
324 * \li The cache of 'view' is 'cached.
326 *\li If this is not the first call to dns_view_setcache() for this
327 * view, then previously set cache is detached.
331 dns_view_sethints(dns_view_t *view, dns_db_t *hints);
333 * Set the view's hints database.
337 *\li 'view' is a valid, unfrozen view, whose hints database has not been
340 *\li 'hints' is a valid zone database.
344 * \li The hints database of 'view' is 'hints'.
348 dns_view_setkeyring(dns_view_t *view, dns_tsig_keyring_t *ring);
350 * Set the view's static TSIG keys
354 * \li 'view' is a valid, unfrozen view, whose static TSIG keyring has not
357 *\li 'ring' is a valid TSIG keyring
361 *\li The static TSIG keyring of 'view' is 'ring'.
365 dns_view_setdstport(dns_view_t *view, in_port_t dstport);
367 * Set the view's destination port. This is the port to
368 * which outgoing queries are sent. The default is 53,
369 * the standard DNS port.
373 *\li 'view' is a valid view.
375 *\li 'dstport' is a valid TCP/UDP port number.
378 *\li External name servers will be assumed to be listening
379 * on 'dstport'. For servers whose address has already
380 * obtained obtained at the time of the call, the view may
381 * continue to use the previously set port until the address
382 * times out from the view's address database.
387 dns_view_addzone(dns_view_t *view, dns_zone_t *zone);
389 * Add zone 'zone' to 'view'.
393 *\li 'view' is a valid, unfrozen view.
395 *\li 'zone' is a valid zone.
399 dns_view_freeze(dns_view_t *view);
405 *\li 'view' is a valid, unfrozen view.
409 *\li 'view' is frozen.
413 dns_view_find(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type,
414 isc_stdtime_t now, unsigned int options, isc_boolean_t use_hints,
415 dns_db_t **dbp, dns_dbnode_t **nodep, dns_name_t *foundname,
416 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
418 * Find an rdataset whose owner name is 'name', and whose type is
423 *\li See the description of dns_db_find() for information about 'options'.
424 * If the caller sets #DNS_DBFIND_GLUEOK, it must ensure that 'name'
425 * and 'type' are appropriate for glue retrieval.
427 *\li If 'now' is zero, then the current time will be used.
429 *\li If 'use_hints' is ISC_TRUE, and the view has a hints database, then
430 * it will be searched last. If the answer is found in the hints
431 * database, the result code will be DNS_R_HINT. If the name is found
432 * in the hints database but not the type, the result code will be
433 * #DNS_R_HINTNXRRSET.
435 *\li 'foundname' must meet the requirements of dns_db_find().
437 *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which
438 * covers 'type', then 'sigrdataset' will be bound to it.
442 *\li 'view' is a valid, frozen view.
444 *\li 'name' is valid name.
446 *\li 'type' is a valid dns_rdatatype_t, and is not a meta query type
447 * except dns_rdatatype_any.
449 *\li dbp == NULL || *dbp == NULL
451 *\li nodep == NULL || *nodep == NULL. If nodep != NULL, dbp != NULL.
453 *\li 'foundname' is a valid name with a dedicated buffer or NULL.
455 *\li 'rdataset' is a valid, disassociated rdataset.
457 *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset.
461 *\li In successful cases, 'rdataset', and possibly 'sigrdataset', are
462 * bound to the found data.
464 *\li If dbp != NULL, it points to the database containing the data.
466 *\li If nodep != NULL, it points to the database node containing the data.
468 *\li If foundname != NULL, it contains the full name of the found data.
472 *\li Any result that dns_db_find() can return, with the exception of
477 dns_view_simplefind(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type,
478 isc_stdtime_t now, unsigned int options,
479 isc_boolean_t use_hints,
480 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
482 * Find an rdataset whose owner name is 'name', and whose type is
487 *\li This routine is appropriate for simple, exact-match queries of the
488 * view. 'name' must be a canonical name; there is no DNAME or CNAME
491 *\li See the description of dns_db_find() for information about 'options'.
492 * If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name'
493 * and 'type' are appropriate for glue retrieval.
495 *\li If 'now' is zero, then the current time will be used.
497 *\li If 'use_hints' is ISC_TRUE, and the view has a hints database, then
498 * it will be searched last. If the answer is found in the hints
499 * database, the result code will be DNS_R_HINT. If the name is found
500 * in the hints database but not the type, the result code will be
503 *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which
504 * covers 'type', then 'sigrdataset' will be bound to it.
508 *\li 'view' is a valid, frozen view.
510 *\li 'name' is valid name.
512 *\li 'type' is a valid dns_rdatatype_t, and is not a meta query type
513 * (e.g. dns_rdatatype_any), or dns_rdatatype_rrsig.
515 *\li 'rdataset' is a valid, disassociated rdataset.
517 *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset.
521 *\li In successful cases, 'rdataset', and possibly 'sigrdataset', are
522 * bound to the found data.
526 *\li #ISC_R_SUCCESS Success; result is desired type.
527 *\li DNS_R_GLUE Success; result is glue.
528 *\li DNS_R_HINT Success; result is a hint.
529 *\li DNS_R_NCACHENXDOMAIN Success; result is a ncache entry.
530 *\li DNS_R_NCACHENXRRSET Success; result is a ncache entry.
531 *\li DNS_R_NXDOMAIN The name does not exist.
532 *\li DNS_R_NXRRSET The rrset does not exist.
533 *\li #ISC_R_NOTFOUND No matching data found,
534 * or an error occurred.
537 /*% See dns_view_findzonecut2() */
539 dns_view_findzonecut(dns_view_t *view, dns_name_t *name, dns_name_t *fname,
540 isc_stdtime_t now, unsigned int options,
541 isc_boolean_t use_hints,
542 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
545 dns_view_findzonecut2(dns_view_t *view, dns_name_t *name, dns_name_t *fname,
546 isc_stdtime_t now, unsigned int options,
547 isc_boolean_t use_hints, isc_boolean_t use_cache,
548 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
550 * Find the best known zonecut containing 'name'.
552 * This uses local authority, cache, and optionally hints data.
553 * No external queries are performed.
557 *\li If 'now' is zero, then the current time will be used.
559 *\li If 'use_hints' is ISC_TRUE, and the view has a hints database, then
560 * it will be searched last.
562 *\li If 'use_cache' is ISC_TRUE, and the view has a cache, then it will be
565 *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which
566 * covers 'type', then 'sigrdataset' will be bound to it.
568 *\li If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned
569 * (if any) will be the deepest known ancestor of 'name'.
573 *\li 'view' is a valid, frozen view.
575 *\li 'name' is valid name.
577 *\li 'rdataset' is a valid, disassociated rdataset.
579 *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset.
583 *\li #ISC_R_SUCCESS Success.
585 *\li Many other results are possible.
589 dns_viewlist_find(dns_viewlist_t *list, const char *name,
590 dns_rdataclass_t rdclass, dns_view_t **viewp);
592 * Search for a view with name 'name' and class 'rdclass' in 'list'.
593 * If found, '*viewp' is (strongly) attached to it.
597 *\li 'viewp' points to a NULL dns_view_t *.
601 *\li #ISC_R_SUCCESS A matching view was found.
602 *\li #ISC_R_NOTFOUND No matching view was found.
606 dns_viewlist_findzone(dns_viewlist_t *list, dns_name_t *name, isc_boolean_t allclasses,
607 dns_rdataclass_t rdclass, dns_zone_t **zonep);
610 * Search zone with 'name' in view with 'rdclass' in viewlist 'list'
611 * If found, zone is returned in *zonep. If allclasses is set rdclass is ignored
614 *\li #ISC_R_SUCCESS A matching zone was found.
615 *\li #ISC_R_NOTFOUND No matching zone was found.
619 dns_view_findzone(dns_view_t *view, dns_name_t *name, dns_zone_t **zonep);
621 * Search for the zone 'name' in the zone table of 'view'.
622 * If found, 'zonep' is (strongly) attached to it. There
623 * are no partial matches.
627 *\li 'zonep' points to a NULL dns_zone_t *.
630 *\li #ISC_R_SUCCESS A matching zone was found.
631 *\li #ISC_R_NOTFOUND No matching zone was found.
632 *\li others An error occurred.
636 dns_view_load(dns_view_t *view, isc_boolean_t stop);
639 dns_view_loadnew(dns_view_t *view, isc_boolean_t stop);
641 * Load zones attached to this view. dns_view_load() loads
642 * all zones whose master file has changed since the last
643 * load; dns_view_loadnew() loads only zones that have never
646 * If 'stop' is ISC_TRUE, stop on the first error and return it.
647 * If 'stop' is ISC_FALSE, ignore errors.
651 *\li 'view' is valid.
655 dns_view_gettsig(dns_view_t *view, dns_name_t *keyname,
656 dns_tsigkey_t **keyp);
658 * Find the TSIG key configured in 'view' with name 'keyname',
662 *\li keyp points to a NULL dns_tsigkey_t *.
665 *\li #ISC_R_SUCCESS A key was found and '*keyp' now points to it.
666 *\li #ISC_R_NOTFOUND No key was found.
667 *\li others An error occurred.
671 dns_view_getpeertsig(dns_view_t *view, isc_netaddr_t *peeraddr,
672 dns_tsigkey_t **keyp);
674 * Find the TSIG key configured in 'view' for the server whose
675 * address is 'peeraddr', if any.
678 * keyp points to a NULL dns_tsigkey_t *.
681 *\li #ISC_R_SUCCESS A key was found and '*keyp' now points to it.
682 *\li #ISC_R_NOTFOUND No key was found.
683 *\li others An error occurred.
687 dns_view_checksig(dns_view_t *view, isc_buffer_t *source, dns_message_t *msg);
689 * Verifies the signature of a message.
693 *\li 'view' is a valid view.
694 *\li 'source' is a valid buffer containing the message
695 *\li 'msg' is a valid message
698 *\li see dns_tsig_verify()
702 dns_view_dialup(dns_view_t *view);
704 * Perform dialup-time maintenance on the zones of 'view'.
708 dns_view_dumpdbtostream(dns_view_t *view, FILE *fp);
710 * Dump the current state of the view 'view' to the stream 'fp'
711 * for purposes of analysis or debugging.
713 * Currently the dumped state includes the view's cache; in the future
714 * it may also include other state such as the address database.
715 * It will not not include authoritative data since it is voluminous and
716 * easily obtainable by other means.
720 *\li 'view' is valid.
722 *\li 'fp' refers to a file open for writing.
725 * \li ISC_R_SUCCESS The cache was successfully dumped.
726 * \li others An error occurred (see dns_master_dump)
730 dns_view_flushcache(dns_view_t *view);
732 * Flush the view's cache (and ADB).
737 * No other tasks are executing.
745 dns_view_flushname(dns_view_t *view, dns_name_t *);
747 * Flush the given name from the view's cache (and ADB).
750 *\li 'view' is valid.
751 *\li 'name' is valid.
755 * other returns are failures.
759 dns_view_adddelegationonly(dns_view_t *view, dns_name_t *name);
761 * Add the given name to the delegation only table.
765 *\li 'view' is valid.
766 *\li 'name' is valid.
774 dns_view_excludedelegationonly(dns_view_t *view, dns_name_t *name);
776 * Add the given name to be excluded from the root-delegation-only.
780 *\li 'view' is valid.
781 *\li 'name' is valid.
789 dns_view_isdelegationonly(dns_view_t *view, dns_name_t *name);
791 * Check if 'name' is in the delegation only table or if
792 * rootdelonly is set that name is not being excluded.
795 *\li 'view' is valid.
796 *\li 'name' is valid.
799 *\li #ISC_TRUE if the name is the table.
800 *\li #ISC_FALSE otherwise.
804 dns_view_setrootdelonly(dns_view_t *view, isc_boolean_t value);
806 * Set the root delegation only flag.
809 *\li 'view' is valid.
813 dns_view_getrootdelonly(dns_view_t *view);
815 * Get the root delegation only flag.
818 *\li 'view' is valid.
822 dns_view_freezezones(dns_view_t *view, isc_boolean_t freeze);
824 * Freeze/thaw updates to master zones.
827 * \li 'view' is valid.
831 dns_view_setresstats(dns_view_t *view, isc_stats_t *stats);
833 * Set a general resolver statistics counter set 'stats' for 'view'.
836 * \li 'view' is valid and is not frozen.
838 *\li stats is a valid statistics supporting resolver statistics counters
843 dns_view_getresstats(dns_view_t *view, isc_stats_t **statsp);
845 * Get the general statistics counter set for 'view'. If a statistics set is
846 * set '*statsp' will be attached to the set; otherwise, '*statsp' will be
850 * \li 'view' is valid and is not frozen.
852 *\li 'statsp' != NULL && '*statsp' != NULL
856 dns_view_setresquerystats(dns_view_t *view, dns_stats_t *stats);
858 * Set a statistics counter set of rdata type, 'stats', for 'view'. Once the
859 * statistic set is installed, view's resolver will count outgoing queries
863 * \li 'view' is valid and is not frozen.
865 *\li stats is a valid statistics created by dns_rdatatypestats_create().
869 dns_view_getresquerystats(dns_view_t *view, dns_stats_t **statsp);
871 * Get the rdatatype statistics counter set for 'view'. If a statistics set is
872 * set '*statsp' will be attached to the set; otherwise, '*statsp' will be
876 * \li 'view' is valid and is not frozen.
878 *\li 'statsp' != NULL && '*statsp' != NULL
881 #endif /* DNS_VIEW_H */