lib/dns/include/dns/view.h

   1 /*
   2  * Copyright (C) 2004-2010  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: view.h,v 1.120.8.6 2010/08/11 18:19:58 each Exp $ */
  19
  20 #ifndef DNS_VIEW_H
  21 #define DNS_VIEW_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file dns/view.h
  28  * \brief
  29  * DNS View
  30  *
  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.
  35  *
  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.
  43  *
  44  * MP:
  45  *\li   Before the view is frozen, the caller must ensure synchronization.
  46  *
  47  *\li   After the view is frozen, the module guarantees appropriate
  48  *      synchronization of any data structures it creates and manipulates.
  49  *
  50  * Reliability:
  51  *\li   No anticipated impact.
  52  *
  53  * Resources:
  54  *\li   TBS
  55  *
  56  * Security:
  57  *\li   No anticipated impact.
  58  *
  59  * Standards:
  60  *\li   None.
  61  */
  62
  63 #include <stdio.h>
  64
  65 #include <isc/lang.h>
  66 #include <isc/magic.h>
  67 #include <isc/event.h>
  68 #include <isc/mutex.h>
  69 #include <isc/net.h>
  70 #include <isc/refcount.h>
  71 #include <isc/rwlock.h>
  72 #include <isc/stdtime.h>
  73
  74 #include <dns/acl.h>
  75 #include <dns/fixedname.h>
  76 #include <dns/rdatastruct.h>
  77 #include <dns/types.h>
  78
  79 ISC_LANG_BEGINDECLS
  80
  81 struct dns_view {
  82         /* Unlocked. */
  83         unsigned int                    magic;
  84         isc_mem_t *                     mctx;
  85         dns_rdataclass_t                rdclass;
  86         char *                          name;
  87         dns_zt_t *                      zonetable;
  88         dns_dlzdb_t *                   dlzdatabase;
  89         dns_resolver_t *                resolver;
  90         dns_adb_t *                     adb;
  91         dns_requestmgr_t *              requestmgr;
  92         dns_acache_t *                  acache;
  93         dns_cache_t *                   cache;
  94         dns_db_t *                      cachedb;
  95         dns_db_t *                      hints;
  96
  97         /*
  98          * security roots.
  99          * internal use only; access via * dns_view_getsecroots()
 100          */
 101         dns_keytable_t *                secroots_priv;
 102
 103         isc_mutex_t                     lock;
 104         isc_boolean_t                   frozen;
 105         isc_task_t *                    task;
 106         isc_event_t                     resevent;
 107         isc_event_t                     adbevent;
 108         isc_event_t                     reqevent;
 109         isc_stats_t *                   resstats;
 110         dns_stats_t *                   resquerystats;
 111         isc_boolean_t                   cacheshared;
 112
 113         /* Configurable data. */
 114         dns_tsig_keyring_t *            statickeys;
 115         dns_tsig_keyring_t *            dynamickeys;
 116         dns_peerlist_t *                peers;
 117         dns_order_t *                   order;
 118         dns_fwdtable_t *                fwdtable;
 119         isc_boolean_t                   recursion;
 120         isc_boolean_t                   auth_nxdomain;
 121         isc_boolean_t                   additionalfromcache;
 122         isc_boolean_t                   additionalfromauth;
 123         isc_boolean_t                   minimalresponses;
 124         isc_boolean_t                   enablednssec;
 125         isc_boolean_t                   enablevalidation;
 126         isc_boolean_t                   acceptexpired;
 127         dns_transfer_format_t           transfer_format;
 128         dns_acl_t *                     queryacl;
 129         dns_acl_t *                     queryonacl;
 130         dns_acl_t *                     recursionacl;
 131         dns_acl_t *                     recursiononacl;
 132         dns_acl_t *                     sortlist;
 133         dns_acl_t *                     notifyacl;
 134         dns_acl_t *                     transferacl;
 135         dns_acl_t *                     updateacl;
 136         dns_acl_t *                     upfwdacl;
 137         dns_acl_t *                     denyansweracl;
 138         dns_rbt_t *                     answeracl_exclude;
 139         dns_rbt_t *                     denyanswernames;
 140         dns_rbt_t *                     answernames_exclude;
 141         isc_boolean_t                   requestixfr;
 142         isc_boolean_t                   provideixfr;
 143         isc_boolean_t                   requestnsid;
 144         dns_ttl_t                       maxcachettl;
 145         dns_ttl_t                       maxncachettl;
 146         in_port_t                       dstport;
 147         dns_aclenv_t                    aclenv;
 148         dns_rdatatype_t                 preferred_glue;
 149         isc_boolean_t                   flush;
 150         dns_namelist_t *                delonly;
 151         isc_boolean_t                   rootdelonly;
 152         dns_namelist_t *                rootexclude;
 153         isc_boolean_t                   checknames;
 154         dns_name_t *                    dlv;
 155         dns_fixedname_t                 dlv_fixed;
 156         isc_uint16_t                    maxudp;
 157         dns_v4_aaaa_t                   v4_aaaa;
 158         dns_acl_t *                     v4_aaaa_acl;
 159
 160         /*
 161          * Configurable data for server use only,
 162          * locked by server configuration lock.
 163          */
 164         dns_acl_t *                     matchclients;
 165         dns_acl_t *                     matchdestinations;
 166         isc_boolean_t                   matchrecursiveonly;
 167
 168         /* Locked by themselves. */
 169         isc_refcount_t                  references;
 170
 171         /* Locked by lock. */
 172         unsigned int                    weakrefs;
 173         unsigned int                    attributes;
 174         /* Under owner's locking control. */
 175         ISC_LINK(struct dns_view)       link;
 176         dns_viewlist_t *                viewlist;
 177
 178         dns_zone_t *                    managed_keys;
 179
 180 #ifdef BIND9
 181         /* File in which to store configuration for newly added zones */
 182         char *                          new_zone_file;
 183
 184         void *                          new_zone_config;
 185         void                            (*cfg_destroy)(void **);
 186 #endif
 187 };
 188
 189 #define DNS_VIEW_MAGIC                  ISC_MAGIC('V','i','e','w')
 190 #define DNS_VIEW_VALID(view)            ISC_MAGIC_VALID(view, DNS_VIEW_MAGIC)
 191
 192 #define DNS_VIEWATTR_RESSHUTDOWN        0x01
 193 #define DNS_VIEWATTR_ADBSHUTDOWN        0x02
 194 #define DNS_VIEWATTR_REQSHUTDOWN        0x04
 195
 196 isc_result_t
 197 dns_view_create(isc_mem_t *mctx, dns_rdataclass_t rdclass,
 198                 const char *name, dns_view_t **viewp);
 199 /*%<
 200  * Create a view.
 201  *
 202  * Notes:
 203  *
 204  *\li   The newly created view has no cache, no resolver, and an empty
 205  *      zone table.  The view is not frozen.
 206  *
 207  * Requires:
 208  *
 209  *\li   'mctx' is a valid memory context.
 210  *
 211  *\li   'rdclass' is a valid class.
 212  *
 213  *\li   'name' is a valid C string.
 214  *
 215  *\li   viewp != NULL && *viewp == NULL
 216  *
 217  * Returns:
 218  *
 219  *\li   #ISC_R_SUCCESS
 220  *\li   #ISC_R_NOMEMORY
 221  *
 222  *\li   Other errors are possible.
 223  */
 224
 225 void
 226 dns_view_attach(dns_view_t *source, dns_view_t **targetp);
 227 /*%<
 228  * Attach '*targetp' to 'source'.
 229  *
 230  * Requires:
 231  *
 232  *\li   'source' is a valid, frozen view.
 233  *
 234  *\li   'targetp' points to a NULL dns_view_t *.
 235  *
 236  * Ensures:
 237  *
 238  *\li   *targetp is attached to source.
 239  *
 240  *\li   While *targetp is attached, the view will not shut down.
 241  */
 242
 243 void
 244 dns_view_detach(dns_view_t **viewp);
 245 /*%<
 246  * Detach '*viewp' from its view.
 247  *
 248  * Requires:
 249  *
 250  *\li   'viewp' points to a valid dns_view_t *
 251  *
 252  * Ensures:
 253  *
 254  *\li   *viewp is NULL.
 255  */
 256
 257 void
 258 dns_view_flushanddetach(dns_view_t **viewp);
 259 /*%<
 260  * Detach '*viewp' from its view.  If this was the last reference
 261  * uncommitted changed in zones will be flushed to disk.
 262  *
 263  * Requires:
 264  *
 265  *\li   'viewp' points to a valid dns_view_t *
 266  *
 267  * Ensures:
 268  *
 269  *\li   *viewp is NULL.
 270  */
 271
 272 void
 273 dns_view_weakattach(dns_view_t *source, dns_view_t **targetp);
 274 /*%<
 275  * Weakly attach '*targetp' to 'source'.
 276  *
 277  * Requires:
 278  *
 279  *\li   'source' is a valid, frozen view.
 280  *
 281  *\li   'targetp' points to a NULL dns_view_t *.
 282  *
 283  * Ensures:
 284  *
 285  *\li   *targetp is attached to source.
 286  *
 287  * \li  While *targetp is attached, the view will not be freed.
 288  */
 289
 290 void
 291 dns_view_weakdetach(dns_view_t **targetp);
 292 /*%<
 293  * Detach '*viewp' from its view.
 294  *
 295  * Requires:
 296  *
 297  *\li   'viewp' points to a valid dns_view_t *.
 298  *
 299  * Ensures:
 300  *
 301  *\li   *viewp is NULL.
 302  */
 303
 304 isc_result_t
 305 dns_view_createresolver(dns_view_t *view,
 306                         isc_taskmgr_t *taskmgr, unsigned int ntasks,
 307                         isc_socketmgr_t *socketmgr,
 308                         isc_timermgr_t *timermgr,
 309                         unsigned int options,
 310                         dns_dispatchmgr_t *dispatchmgr,
 311                         dns_dispatch_t *dispatchv4,
 312                         dns_dispatch_t *dispatchv6);
 313 /*%<
 314  * Create a resolver and address database for the view.
 315  *
 316  * Requires:
 317  *
 318  *\li   'view' is a valid, unfrozen view.
 319  *
 320  *\li   'view' does not have a resolver already.
 321  *
 322  *\li   The requirements of dns_resolver_create() apply to 'taskmgr',
 323  *      'ntasks', 'socketmgr', 'timermgr', 'options', 'dispatchv4', and
 324  *      'dispatchv6'.
 325  *
 326  * Returns:
 327  *
 328  *\li           #ISC_R_SUCCESS
 329  *
 330  *\li   Any error that dns_resolver_create() can return.
 331  */
 332
 333 void
 334 dns_view_setcache(dns_view_t *view, dns_cache_t *cache);
 335 void
 336 dns_view_setcache2(dns_view_t *view, dns_cache_t *cache, isc_boolean_t shared);
 337 /*%<
 338  * Set the view's cache database.  If 'shared' is true, this means the cache
 339  * is created by another view and is shared with that view.  dns_view_setcache()
 340  * is a backward compatible version equivalent to setcache2(..., ISC_FALSE).
 341  *
 342  * Requires:
 343  *
 344  *\li   'view' is a valid, unfrozen view.
 345  *
 346  *\li   'cache' is a valid cache.
 347  *
 348  * Ensures:
 349  *
 350  * \li          The cache of 'view' is 'cached.
 351  *
 352  *\li   If this is not the first call to dns_view_setcache() for this
 353  *      view, then previously set cache is detached.
 354  */
 355
 356 void
 357 dns_view_sethints(dns_view_t *view, dns_db_t *hints);
 358 /*%<
 359  * Set the view's hints database.
 360  *
 361  * Requires:
 362  *
 363  *\li   'view' is a valid, unfrozen view, whose hints database has not been
 364  *      set.
 365  *
 366  *\li   'hints' is a valid zone database.
 367  *
 368  * Ensures:
 369  *
 370  * \li          The hints database of 'view' is 'hints'.
 371  */
 372
 373 void
 374 dns_view_setkeyring(dns_view_t *view, dns_tsig_keyring_t *ring);
 375 /*%<
 376  * Set the view's static TSIG keys
 377  *
 378  * Requires:
 379  *
 380  *   \li   'view' is a valid, unfrozen view, whose static TSIG keyring has not
 381  *      been set.
 382  *
 383  *\li      'ring' is a valid TSIG keyring
 384  *
 385  * Ensures:
 386  *
 387  *\li      The static TSIG keyring of 'view' is 'ring'.
 388  */
 389
 390 void
 391 dns_view_setdstport(dns_view_t *view, in_port_t dstport);
 392 /*%<
 393  * Set the view's destination port.  This is the port to
 394  * which outgoing queries are sent.  The default is 53,
 395  * the standard DNS port.
 396  *
 397  * Requires:
 398  *
 399  *\li      'view' is a valid view.
 400  *
 401  *\li      'dstport' is a valid TCP/UDP port number.
 402  *
 403  * Ensures:
 404  *\li   External name servers will be assumed to be listening
 405  *      on 'dstport'.  For servers whose address has already
 406  *      obtained obtained at the time of the call, the view may
 407  *      continue to use the previously set port until the address
 408  *      times out from the view's address database.
 409  */
 410
 411
 412 isc_result_t
 413 dns_view_addzone(dns_view_t *view, dns_zone_t *zone);
 414 /*%<
 415  * Add zone 'zone' to 'view'.
 416  *
 417  * Requires:
 418  *
 419  *\li   'view' is a valid, unfrozen view.
 420  *
 421  *\li   'zone' is a valid zone.
 422  */
 423
 424 void
 425 dns_view_freeze(dns_view_t *view);
 426 /*%<
 427  * Freeze view.  No changes can be made to view configuration while frozen.
 428  *
 429  * Requires:
 430  *
 431  *\li   'view' is a valid, unfrozen view.
 432  *
 433  * Ensures:
 434  *
 435  *\li   'view' is frozen.
 436  */
 437
 438 void
 439 dns_view_thaw(dns_view_t *view);
 440 /*%<
 441  * Thaw view.  This allows zones to be added or removed at runtime.  This is
 442  * NOT thread-safe; the caller MUST have run isc_task_exclusive() prior to
 443  * thawing the view.
 444  *
 445  * Requires:
 446  *
 447  *\li   'view' is a valid, frozen view.
 448  *
 449  * Ensures:
 450  *
 451  *\li   'view' is no longer frozen.
 452  */
 453 isc_result_t
 454 dns_view_find(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type,
 455               isc_stdtime_t now, unsigned int options, isc_boolean_t use_hints,
 456               dns_db_t **dbp, dns_dbnode_t **nodep, dns_name_t *foundname,
 457               dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
 458 /*%<
 459  * Find an rdataset whose owner name is 'name', and whose type is
 460  * 'type'.
 461  *
 462  * Notes:
 463  *
 464  *\li   See the description of dns_db_find() for information about 'options'.
 465  *      If the caller sets #DNS_DBFIND_GLUEOK, it must ensure that 'name'
 466  *      and 'type' are appropriate for glue retrieval.
 467  *
 468  *\li   If 'now' is zero, then the current time will be used.
 469  *
 470  *\li   If 'use_hints' is ISC_TRUE, and the view has a hints database, then
 471  *      it will be searched last.  If the answer is found in the hints
 472  *      database, the result code will be DNS_R_HINT.  If the name is found
 473  *      in the hints database but not the type, the result code will be
 474  *      #DNS_R_HINTNXRRSET.
 475  *
 476  *\li   'foundname' must meet the requirements of dns_db_find().
 477  *
 478  *\li   If 'sigrdataset' is not NULL, and there is a SIG rdataset which
 479  *      covers 'type', then 'sigrdataset' will be bound to it.
 480  *
 481  * Requires:
 482  *
 483  *\li   'view' is a valid, frozen view.
 484  *
 485  *\li   'name' is valid name.
 486  *
 487  *\li   'type' is a valid dns_rdatatype_t, and is not a meta query type
 488  *      except dns_rdatatype_any.
 489  *
 490  *\li   dbp == NULL || *dbp == NULL
 491  *
 492  *\li   nodep == NULL || *nodep == NULL.  If nodep != NULL, dbp != NULL.
 493  *
 494  *\li   'foundname' is a valid name with a dedicated buffer or NULL.
 495  *
 496  *\li   'rdataset' is a valid, disassociated rdataset.
 497  *
 498  *\li   'sigrdataset' is NULL, or is a valid, disassociated rdataset.
 499  *
 500  * Ensures:
 501  *
 502  *\li   In successful cases, 'rdataset', and possibly 'sigrdataset', are
 503  *      bound to the found data.
 504  *
 505  *\li   If dbp != NULL, it points to the database containing the data.
 506  *
 507  *\li   If nodep != NULL, it points to the database node containing the data.
 508  *
 509  *\li   If foundname != NULL, it contains the full name of the found data.
 510  *
 511  * Returns:
 512  *
 513  *\li   Any result that dns_db_find() can return, with the exception of
 514  *      #DNS_R_DELEGATION.
 515  */
 516
 517 isc_result_t
 518 dns_view_simplefind(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type,
 519                     isc_stdtime_t now, unsigned int options,
 520                     isc_boolean_t use_hints,
 521                     dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
 522 /*%<
 523  * Find an rdataset whose owner name is 'name', and whose type is
 524  * 'type'.
 525  *
 526  * Notes:
 527  *
 528  *\li   This routine is appropriate for simple, exact-match queries of the
 529  *      view.  'name' must be a canonical name; there is no DNAME or CNAME
 530  *      processing.
 531  *
 532  *\li   See the description of dns_db_find() for information about 'options'.
 533  *      If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name'
 534  *      and 'type' are appropriate for glue retrieval.
 535  *
 536  *\li   If 'now' is zero, then the current time will be used.
 537  *
 538  *\li   If 'use_hints' is ISC_TRUE, and the view has a hints database, then
 539  *      it will be searched last.  If the answer is found in the hints
 540  *      database, the result code will be DNS_R_HINT.  If the name is found
 541  *      in the hints database but not the type, the result code will be
 542  *      DNS_R_HINTNXRRSET.
 543  *
 544  *\li   If 'sigrdataset' is not NULL, and there is a SIG rdataset which
 545  *      covers 'type', then 'sigrdataset' will be bound to it.
 546  *
 547  * Requires:
 548  *
 549  *\li   'view' is a valid, frozen view.
 550  *
 551  *\li   'name' is valid name.
 552  *
 553  *\li   'type' is a valid dns_rdatatype_t, and is not a meta query type
 554  *      (e.g. dns_rdatatype_any), or dns_rdatatype_rrsig.
 555  *
 556  *\li   'rdataset' is a valid, disassociated rdataset.
 557  *
 558  *\li   'sigrdataset' is NULL, or is a valid, disassociated rdataset.
 559  *
 560  * Ensures:
 561  *
 562  *\li   In successful cases, 'rdataset', and possibly 'sigrdataset', are
 563  *      bound to the found data.
 564  *
 565  * Returns:
 566  *
 567  *\li   #ISC_R_SUCCESS                  Success; result is desired type.
 568  *\li   DNS_R_GLUE                      Success; result is glue.
 569  *\li   DNS_R_HINT                      Success; result is a hint.
 570  *\li   DNS_R_NCACHENXDOMAIN            Success; result is a ncache entry.
 571  *\li   DNS_R_NCACHENXRRSET             Success; result is a ncache entry.
 572  *\li   DNS_R_NXDOMAIN                  The name does not exist.
 573  *\li   DNS_R_NXRRSET                   The rrset does not exist.
 574  *\li   #ISC_R_NOTFOUND                 No matching data found,
 575  *                                      or an error occurred.
 576  */
 577
 578 /*% See dns_view_findzonecut2() */
 579 isc_result_t
 580 dns_view_findzonecut(dns_view_t *view, dns_name_t *name, dns_name_t *fname,
 581                      isc_stdtime_t now, unsigned int options,
 582                      isc_boolean_t use_hints,
 583                      dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
 584
 585 isc_result_t
 586 dns_view_findzonecut2(dns_view_t *view, dns_name_t *name, dns_name_t *fname,
 587                       isc_stdtime_t now, unsigned int options,
 588                       isc_boolean_t use_hints, isc_boolean_t use_cache,
 589                       dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
 590 /*%<
 591  * Find the best known zonecut containing 'name'.
 592  *
 593  * This uses local authority, cache, and optionally hints data.
 594  * No external queries are performed.
 595  *
 596  * Notes:
 597  *
 598  *\li   If 'now' is zero, then the current time will be used.
 599  *
 600  *\li   If 'use_hints' is ISC_TRUE, and the view has a hints database, then
 601  *      it will be searched last.
 602  *
 603  *\li   If 'use_cache' is ISC_TRUE, and the view has a cache, then it will be
 604  *      searched.
 605  *
 606  *\li   If 'sigrdataset' is not NULL, and there is a SIG rdataset which
 607  *      covers 'type', then 'sigrdataset' will be bound to it.
 608  *
 609  *\li   If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned
 610  *      (if any) will be the deepest known ancestor of 'name'.
 611  *
 612  * Requires:
 613  *
 614  *\li   'view' is a valid, frozen view.
 615  *
 616  *\li   'name' is valid name.
 617  *
 618  *\li   'rdataset' is a valid, disassociated rdataset.
 619  *
 620  *\li   'sigrdataset' is NULL, or is a valid, disassociated rdataset.
 621  *
 622  * Returns:
 623  *
 624  *\li   #ISC_R_SUCCESS                          Success.
 625  *
 626  *\li   Many other results are possible.
 627  */
 628
 629 isc_result_t
 630 dns_viewlist_find(dns_viewlist_t *list, const char *name,
 631                   dns_rdataclass_t rdclass, dns_view_t **viewp);
 632 /*%<
 633  * Search for a view with name 'name' and class 'rdclass' in 'list'.
 634  * If found, '*viewp' is (strongly) attached to it.
 635  *
 636  * Requires:
 637  *
 638  *\li   'viewp' points to a NULL dns_view_t *.
 639  *
 640  * Returns:
 641  *
 642  *\li   #ISC_R_SUCCESS          A matching view was found.
 643  *\li   #ISC_R_NOTFOUND         No matching view was found.
 644  */
 645
 646 isc_result_t
 647 dns_viewlist_findzone(dns_viewlist_t *list, dns_name_t *name, isc_boolean_t allclasses,
 648                       dns_rdataclass_t rdclass, dns_zone_t **zonep);
 649
 650 /*%<
 651  * Search zone with 'name' in view with 'rdclass' in viewlist 'list'
 652  * If found, zone is returned in *zonep. If allclasses is set rdclass is ignored
 653  *
 654  * Returns:
 655  *\li   #ISC_R_SUCCESS          A matching zone was found.
 656  *\li   #ISC_R_NOTFOUND         No matching zone was found.
 657  */
 658
 659 isc_result_t
 660 dns_view_findzone(dns_view_t *view, dns_name_t *name, dns_zone_t **zonep);
 661 /*%<
 662  * Search for the zone 'name' in the zone table of 'view'.
 663  * If found, 'zonep' is (strongly) attached to it.  There
 664  * are no partial matches.
 665  *
 666  * Requires:
 667  *
 668  *\li   'zonep' points to a NULL dns_zone_t *.
 669  *
 670  * Returns:
 671  *\li   #ISC_R_SUCCESS          A matching zone was found.
 672  *\li   #ISC_R_NOTFOUND         No matching zone was found.
 673  *\li   others                  An error occurred.
 674  */
 675
 676 isc_result_t
 677 dns_view_load(dns_view_t *view, isc_boolean_t stop);
 678
 679 isc_result_t
 680 dns_view_loadnew(dns_view_t *view, isc_boolean_t stop);
 681 /*%<
 682  * Load zones attached to this view.  dns_view_load() loads
 683  * all zones whose master file has changed since the last
 684  * load; dns_view_loadnew() loads only zones that have never
 685  * been loaded.
 686  *
 687  * If 'stop' is ISC_TRUE, stop on the first error and return it.
 688  * If 'stop' is ISC_FALSE, ignore errors.
 689  *
 690  * Requires:
 691  *
 692  *\li   'view' is valid.
 693  */
 694
 695 isc_result_t
 696 dns_view_gettsig(dns_view_t *view, dns_name_t *keyname,
 697                  dns_tsigkey_t **keyp);
 698 /*%<
 699  * Find the TSIG key configured in 'view' with name 'keyname',
 700  * if any.
 701  *
 702  * Requires:
 703  *\li   keyp points to a NULL dns_tsigkey_t *.
 704  *
 705  * Returns:
 706  *\li   #ISC_R_SUCCESS  A key was found and '*keyp' now points to it.
 707  *\li   #ISC_R_NOTFOUND No key was found.
 708  *\li   others          An error occurred.
 709  */
 710
 711 isc_result_t
 712 dns_view_getpeertsig(dns_view_t *view, isc_netaddr_t *peeraddr,
 713                      dns_tsigkey_t **keyp);
 714 /*%<
 715  * Find the TSIG key configured in 'view' for the server whose
 716  * address is 'peeraddr', if any.
 717  *
 718  * Requires:
 719  *      keyp points to a NULL dns_tsigkey_t *.
 720  *
 721  * Returns:
 722  *\li   #ISC_R_SUCCESS  A key was found and '*keyp' now points to it.
 723  *\li   #ISC_R_NOTFOUND No key was found.
 724  *\li   others          An error occurred.
 725  */
 726
 727 isc_result_t
 728 dns_view_checksig(dns_view_t *view, isc_buffer_t *source, dns_message_t *msg);
 729 /*%<
 730  * Verifies the signature of a message.
 731  *
 732  * Requires:
 733  *
 734  *\li   'view' is a valid view.
 735  *\li   'source' is a valid buffer containing the message
 736  *\li   'msg' is a valid message
 737  *
 738  * Returns:
 739  *\li   see dns_tsig_verify()
 740  */
 741
 742 void
 743 dns_view_dialup(dns_view_t *view);
 744 /*%<
 745  * Perform dialup-time maintenance on the zones of 'view'.
 746  */
 747
 748 isc_result_t
 749 dns_view_dumpdbtostream(dns_view_t *view, FILE *fp);
 750 /*%<
 751  * Dump the current state of the view 'view' to the stream 'fp'
 752  * for purposes of analysis or debugging.
 753  *
 754  * Currently the dumped state includes the view's cache; in the future
 755  * it may also include other state such as the address database.
 756  * It will not not include authoritative data since it is voluminous and
 757  * easily obtainable by other means.
 758  *
 759  * Requires:
 760  *
 761  *\li   'view' is valid.
 762  *
 763  *\li   'fp' refers to a file open for writing.
 764  *
 765  * Returns:
 766  * \li  ISC_R_SUCCESS   The cache was successfully dumped.
 767  * \li  others          An error occurred (see dns_master_dump)
 768  */
 769
 770 isc_result_t
 771 dns_view_flushcache(dns_view_t *view);
 772 isc_result_t
 773 dns_view_flushcache2(dns_view_t *view, isc_boolean_t fixuponly);
 774 /*%<
 775  * Flush the view's cache (and ADB).  If 'fixuponly' is true, it only updates
 776  * the internal reference to the cache DB with omitting actual flush operation.
 777  * 'fixuponly' is intended to be used for a view that shares a cache with
 778  * a different view.  dns_view_flushcache() is a backward compatible version
 779  * that always sets fixuponly to false.
 780  *
 781  * Requires:
 782  *      'view' is valid.
 783  *
 784  *      No other tasks are executing.
 785  *
 786  * Returns:
 787  *\li   #ISC_R_SUCCESS
 788  *\li   #ISC_R_NOMEMORY
 789  */
 790
 791 isc_result_t
 792 dns_view_flushname(dns_view_t *view, dns_name_t *);
 793 /*%<
 794  * Flush the given name from the view's cache (and ADB).
 795  *
 796  * Requires:
 797  *\li   'view' is valid.
 798  *\li   'name' is valid.
 799  *
 800  * Returns:
 801  *\li   #ISC_R_SUCCESS
 802  *      other returns are failures.
 803  */
 804
 805 isc_result_t
 806 dns_view_adddelegationonly(dns_view_t *view, dns_name_t *name);
 807 /*%<
 808  * Add the given name to the delegation only table.
 809  *
 810  *
 811  * Requires:
 812  *\li   'view' is valid.
 813  *\li   'name' is valid.
 814  *
 815  * Returns:
 816  *\li   #ISC_R_SUCCESS
 817  *\li   #ISC_R_NOMEMORY
 818  */
 819
 820 isc_result_t
 821 dns_view_excludedelegationonly(dns_view_t *view, dns_name_t *name);
 822 /*%<
 823  * Add the given name to be excluded from the root-delegation-only.
 824  *
 825  *
 826  * Requires:
 827  *\li   'view' is valid.
 828  *\li   'name' is valid.
 829  *
 830  * Returns:
 831  *\li   #ISC_R_SUCCESS
 832  *\li   #ISC_R_NOMEMORY
 833  */
 834
 835 isc_boolean_t
 836 dns_view_isdelegationonly(dns_view_t *view, dns_name_t *name);
 837 /*%<
 838  * Check if 'name' is in the delegation only table or if
 839  * rootdelonly is set that name is not being excluded.
 840  *
 841  * Requires:
 842  *\li   'view' is valid.
 843  *\li   'name' is valid.
 844  *
 845  * Returns:
 846  *\li   #ISC_TRUE if the name is the table.
 847  *\li   #ISC_FALSE otherwise.
 848  */
 849
 850 void
 851 dns_view_setrootdelonly(dns_view_t *view, isc_boolean_t value);
 852 /*%<
 853  * Set the root delegation only flag.
 854  *
 855  * Requires:
 856  *\li   'view' is valid.
 857  */
 858
 859 isc_boolean_t
 860 dns_view_getrootdelonly(dns_view_t *view);
 861 /*%<
 862  * Get the root delegation only flag.
 863  *
 864  * Requires:
 865  *\li   'view' is valid.
 866  */
 867
 868 isc_result_t
 869 dns_view_freezezones(dns_view_t *view, isc_boolean_t freeze);
 870 /*%<
 871  * Freeze/thaw updates to master zones.
 872  *
 873  * Requires:
 874  * \li  'view' is valid.
 875  */
 876
 877 void
 878 dns_view_setresstats(dns_view_t *view, isc_stats_t *stats);
 879 /*%<
 880  * Set a general resolver statistics counter set 'stats' for 'view'.
 881  *
 882  * Requires:
 883  * \li  'view' is valid and is not frozen.
 884  *
 885  *\li   stats is a valid statistics supporting resolver statistics counters
 886  *      (see dns/stats.h).
 887  */
 888
 889 void
 890 dns_view_getresstats(dns_view_t *view, isc_stats_t **statsp);
 891 /*%<
 892  * Get the general statistics counter set for 'view'.  If a statistics set is
 893  * set '*statsp' will be attached to the set; otherwise, '*statsp' will be
 894  * untouched.
 895  *
 896  * Requires:
 897  * \li  'view' is valid and is not frozen.
 898  *
 899  *\li   'statsp' != NULL && '*statsp' != NULL
 900  */
 901
 902 void
 903 dns_view_setresquerystats(dns_view_t *view, dns_stats_t *stats);
 904 /*%<
 905  * Set a statistics counter set of rdata type, 'stats', for 'view'.  Once the
 906  * statistic set is installed, view's resolver will count outgoing queries
 907  * per rdata type.
 908  *
 909  * Requires:
 910  * \li  'view' is valid and is not frozen.
 911  *
 912  *\li   stats is a valid statistics created by dns_rdatatypestats_create().
 913  */
 914
 915 void
 916 dns_view_getresquerystats(dns_view_t *view, dns_stats_t **statsp);
 917 /*%<
 918  * Get the rdatatype statistics counter set for 'view'.  If a statistics set is
 919  * set '*statsp' will be attached to the set; otherwise, '*statsp' will be
 920  * untouched.
 921  *
 922  * Requires:
 923  * \li  'view' is valid and is not frozen.
 924  *
 925  *\li   'statsp' != NULL && '*statsp' != NULL
 926  */
 927
 928 isc_boolean_t
 929 dns_view_iscacheshared(dns_view_t *view);
 930 /*%<
 931  * Check if the view shares the cache created by another view.
 932  *
 933  * Requires:
 934  * \li  'view' is valid.
 935  *
 936  * Returns:
 937  *\li   #ISC_TRUE if the cache is shared.
 938  *\li   #ISC_FALSE otherwise.
 939  */
 940
 941 isc_result_t
 942 dns_view_initsecroots(dns_view_t *view, isc_mem_t *mctx);
 943 /*%<
 944  * Initialize security roots for the view.  (Note that secroots is
 945  * NULL until this function is called, so any function using
 946  * secroots must check its validity first.  One way to do this is
 947  * use dns_view_getsecroots() and check its return value.)
 948  *
 949  * Requires:
 950  * \li  'view' is valid.
 951  * \li  'view->secroots' is NULL.
 952  *
 953  * Returns:
 954  *\li   ISC_R_SUCCESS
 955  *\li   Any other result indicates failure
 956  */
 957
 958 isc_result_t
 959 dns_view_getsecroots(dns_view_t *view, dns_keytable_t **ktp);
 960 /*%<
 961  * Get the security roots for this view.  Returns ISC_R_NOTFOUND if
 962  * the security roots keytable has not been initialized for the view.
 963  *
 964  * '*ktp' is attached on success; the caller is responsible for
 965  * detaching it with dns_keytable_detach().
 966  *
 967  * Requires:
 968  * \li  'view' is valid.
 969  * \li  'ktp' is not NULL and '*ktp' is NULL.
 970  *
 971  * Returns:
 972  *\li   ISC_R_SUCCESS
 973  *\li   ISC_R_NOTFOUND
 974  */
 975
 976 isc_result_t
 977 dns_view_issecuredomain(dns_view_t *view, dns_name_t *name,
 978                          isc_boolean_t *secure_domain);
 979 /*%<
 980  * Is 'name' at or beneath a trusted key?  Put answer in
 981  * '*secure_domain'.
 982  *
 983  * Requires:
 984  * \li  'view' is valid.
 985  *
 986  * Returns:
 987  *\li   ISC_R_SUCCESS
 988  *\li   Any other value indicates failure
 989  */
 990
 991 void
 992 dns_view_untrust(dns_view_t *view, dns_name_t *keyname,
 993                  dns_rdata_dnskey_t *dnskey, isc_mem_t *mctx);
 994 /*%<
 995  * Remove keys that match 'keyname' and 'dnskey' from the views trust
 996  * anchors.
 997  *
 998  * Requires:
 999  * \li  'view' is valid.
1000  * \li  'keyname' is valid.
1001  * \li  'mctx' is valid.
1002  * \li  'dnskey' is valid.
1003  */
1004
1005 void
1006 dns_view_setnewzones(dns_view_t *view, isc_boolean_t allow, void *cfgctx,
1007                      void (*cfg_destroy)(void **));
1008 /*%<
1009  * Set whether or not to allow zones to be created or deleted at runtime.
1010  *
1011  * If 'allow' is ISC_TRUE, determines the filename into which new zone
1012  * configuration will be written.  Preserves the configuration context
1013  * (a pointer to which is passed in 'cfgctx') for use when parsing new
1014  * zone configuration.  'cfg_destroy' points to a callback routine to
1015  * destroy the configuration context when the view is destroyed.  (This
1016  * roundabout method is used in order to avoid libdns having a dependency
1017  * on libisccfg and libbind9.)
1018  *
1019  * If 'allow' is ISC_FALSE, removes any existing references to
1020  * configuration context and frees any memory.
1021  *
1022  * Requires:
1023  * \li 'view' is valid.
1024  */
1025
1026 #endif /* DNS_VIEW_H */