contrib/bind-9.3/lib/dns/include/dns/zone.h

   1 /*
   2  * Copyright (C) 2004, 2006  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2003  Internet Software Consortium.
   4  *
   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.
   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: zone.h,v 1.106.2.7.4.18 2006/08/01 03:44:00 marka Exp $ */
  19
  20 #ifndef DNS_ZONE_H
  21 #define DNS_ZONE_H 1
  22
  23 /***
  24  ***    Imports
  25  ***/
  26
  27 #include <stdio.h>
  28
  29 #include <isc/formatcheck.h>
  30 #include <isc/lang.h>
  31 #include <isc/rwlock.h>
  32
  33 #include <dns/types.h>
  34
  35 typedef enum {
  36         dns_zone_none,
  37         dns_zone_master,
  38         dns_zone_slave,
  39         dns_zone_stub
  40 } dns_zonetype_t;
  41
  42 #define DNS_ZONEOPT_SERVERS       0x00000001U   /* perform server checks */
  43 #define DNS_ZONEOPT_PARENTS       0x00000002U   /* perform parent checks */
  44 #define DNS_ZONEOPT_CHILDREN      0x00000004U   /* perform child checks */
  45 #define DNS_ZONEOPT_NOTIFY        0x00000008U   /* perform NOTIFY */
  46 #define DNS_ZONEOPT_MANYERRORS    0x00000010U   /* return many errors on load */
  47 #define DNS_ZONEOPT_IXFRFROMDIFFS 0x00000020U   /* calculate differences */
  48 #define DNS_ZONEOPT_NOMERGE       0x00000040U   /* don't merge journal */
  49 #define DNS_ZONEOPT_CHECKNS       0x00000080U   /* check if NS's are addresses */
  50 #define DNS_ZONEOPT_FATALNS       0x00000100U   /* DNS_ZONEOPT_CHECKNS is fatal */
  51 #define DNS_ZONEOPT_MULTIMASTER   0x00000200U   /* this zone has multiple masters */
  52 #define DNS_ZONEOPT_USEALTXFRSRC  0x00000400U   /* use alternate transfer sources */
  53 #define DNS_ZONEOPT_CHECKNAMES    0x00000800U   /* check-names */
  54 #define DNS_ZONEOPT_CHECKNAMESFAIL 0x00001000U  /* fatal check-name failures */
  55
  56 #ifndef NOMINUM_PUBLIC
  57 /*
  58  * Nominum specific options build down.
  59  */
  60 #define DNS_ZONEOPT_NOTIFYFORWARD 0x80000000U   /* forward notify to master */
  61 #endif /* NOMINUM_PUBLIC */
  62
  63 #ifndef DNS_ZONE_MINREFRESH
  64 #define DNS_ZONE_MINREFRESH                 300 /* 5 minutes */
  65 #endif
  66 #ifndef DNS_ZONE_MAXREFRESH
  67 #define DNS_ZONE_MAXREFRESH             2419200 /* 4 weeks */
  68 #endif
  69 #ifndef DNS_ZONE_DEFAULTREFRESH
  70 #define DNS_ZONE_DEFAULTREFRESH            3600 /* 1 hour */
  71 #endif
  72 #ifndef DNS_ZONE_MINRETRY
  73 #define DNS_ZONE_MINRETRY                   300 /* 5 minutes */
  74 #endif
  75 #ifndef DNS_ZONE_MAXRETRY
  76 #define DNS_ZONE_MAXRETRY               1209600 /* 2 weeks */
  77 #endif
  78 #ifndef DNS_ZONE_DEFAULTRETRY
  79 #define DNS_ZONE_DEFAULTRETRY                60 /* 1 minute, subject to
  80                                                    exponential backoff */
  81 #endif
  82
  83 #define DNS_ZONESTATE_XFERRUNNING       1
  84 #define DNS_ZONESTATE_XFERDEFERRED      2
  85 #define DNS_ZONESTATE_SOAQUERY          3
  86 #define DNS_ZONESTATE_ANY               4
  87
  88 ISC_LANG_BEGINDECLS
  89
  90 /***
  91  ***    Functions
  92  ***/
  93
  94 isc_result_t
  95 dns_zone_create(dns_zone_t **zonep, isc_mem_t *mctx);
  96 /*
  97  *      Creates a new empty zone and attach '*zonep' to it.
  98  *
  99  * Requires:
 100  *      'zonep' to point to a NULL pointer.
 101  *      'mctx' to be a valid memory context.
 102  *
 103  * Ensures:
 104  *      '*zonep' refers to a valid zone.
 105  *
 106  * Returns:
 107  *      ISC_R_SUCCESS
 108  *      ISC_R_NOMEMORY
 109  *      ISC_R_UNEXPECTED
 110  */
 111
 112 void
 113 dns_zone_setclass(dns_zone_t *zone, dns_rdataclass_t rdclass);
 114 /*
 115  *      Sets the class of a zone.  This operation can only be performed
 116  *      once on a zone.
 117  *
 118  * Require:
 119  *      'zone' to be a valid zone.
 120  *      dns_zone_setclass() not to have been called since the zone was
 121  *      created.
 122  *      'rdclass' != dns_rdataclass_none.
 123  */
 124
 125 dns_rdataclass_t
 126 dns_zone_getclass(dns_zone_t *zone);
 127 /*
 128  *      Returns the current zone class.
 129  *
 130  * Requires:
 131  *      'zone' to be a valid zone.
 132  */
 133
 134 void
 135 dns_zone_settype(dns_zone_t *zone, dns_zonetype_t type);
 136 /*
 137  *      Sets the zone type. This operation can only be performed once on
 138  *      a zone.
 139  *
 140  * Requires:
 141  *      'zone' to be a valid zone.
 142  *      dns_zone_settype() not to have been called since the zone was
 143  *      created.
 144  *      'type' != dns_zone_none
 145  */
 146
 147 void
 148 dns_zone_setview(dns_zone_t *zone, dns_view_t *view);
 149 /*
 150  *      Associate the zone with a view.
 151  *
 152  * Require:
 153  *      'zone' to be a valid zone.
 154  */
 155
 156 dns_view_t *
 157 dns_zone_getview(dns_zone_t *zone);
 158 /*
 159  *      Returns the zone's associated view.
 160  *
 161  * Requires:
 162  *      'zone' to be a valid zone.
 163  */
 164
 165 isc_result_t
 166 dns_zone_setorigin(dns_zone_t *zone, const dns_name_t *origin);
 167 /*
 168  *      Sets the zones origin to 'origin'.
 169  *
 170  * Require:
 171  *      'zone' to be a valid zone.
 172  *      'origin' to be non NULL.
 173  *
 174  * Returns:
 175  *      ISC_R_SUCCESS
 176  *      ISC_R_NOMEMORY
 177  */
 178
 179 dns_name_t *
 180 dns_zone_getorigin(dns_zone_t *zone);
 181 /*
 182  *      Returns the value of the origin.
 183  *
 184  * Require:
 185  *      'zone' to be a valid zone.
 186  */
 187
 188 isc_result_t
 189 dns_zone_setfile(dns_zone_t *zone, const char *file);
 190 /*
 191  *      Sets the name of the master file from which the zone
 192  *      loads its database to 'file'.  For zones that have
 193  *      no associated master file, 'file' will be NULL.
 194  *
 195  *      For zones with persistent databases, the file name
 196  *      setting is ignored.
 197  *
 198  * Require:
 199  *      'zone' to be a valid zone.
 200  *
 201  * Returns:
 202  *      ISC_R_NOMEMORY
 203  *      ISC_R_SUCCESS
 204  */
 205
 206 const char *
 207 dns_zone_getfile(dns_zone_t *zone);
 208 /*
 209  *      Gets the name of the zone's master file, if any.
 210  *
 211  * Requires:
 212  *      'zone' to be valid initialised zone.
 213  *
 214  * Returns:
 215  *      Pointer to null-terminated file name, or NULL.
 216  */
 217
 218 isc_result_t
 219 dns_zone_load(dns_zone_t *zone);
 220
 221 isc_result_t
 222 dns_zone_loadnew(dns_zone_t *zone);
 223 /*
 224  *      Cause the database to be loaded from its backing store.
 225  *      Confirm that the minimum requirements for the zone type are
 226  *      met, otherwise DNS_R_BADZONE is returned.
 227  *
 228  *      dns_zone_loadnew() only loads zones that are not yet loaded.
 229  *      dns_zone_load() also loads zones that are already loaded and
 230  *      and whose master file has changed since the last load.
 231  *
 232  * Require:
 233  *      'zone' to be a valid zone.
 234  *
 235  * Returns:
 236  *      ISC_R_UNEXPECTED
 237  *      ISC_R_SUCCESS
 238  *      DNS_R_CONTINUE    Incremental load has been queued.
 239  *      DNS_R_UPTODATE    The zone has already been loaded based on
 240  *                        file system timestamps.
 241  *      DNS_R_BADZONE
 242  *      Any result value from dns_db_load().
 243  */
 244
 245 void
 246 dns_zone_attach(dns_zone_t *source, dns_zone_t **target);
 247 /*
 248  *      Attach '*target' to 'source' incrementing its external
 249  *      reference count.
 250  *
 251  * Require:
 252  *      'zone' to be a valid zone.
 253  *      'target' to be non NULL and '*target' to be NULL.
 254  */
 255
 256 void
 257 dns_zone_detach(dns_zone_t **zonep);
 258 /*
 259  *      Detach from a zone decrementing its external reference count.
 260  *      If this was the last external reference to the zone it will be
 261  *      shut down and eventually freed.
 262  *
 263  * Require:
 264  *      'zonep' to point to a valid zone.
 265  */
 266
 267 void
 268 dns_zone_iattach(dns_zone_t *source, dns_zone_t **target);
 269 /*
 270  *      Attach '*target' to 'source' incrementing its internal
 271  *      reference count.  This is intended for use by operations
 272  *      such as zone transfers that need to prevent the zone
 273  *      object from being freed but not from shutting down.
 274  *
 275  * Require:
 276  *      The caller is running in the context of the zone's task.
 277  *      'zone' to be a valid zone.
 278  *      'target' to be non NULL and '*target' to be NULL.
 279  */
 280
 281 void
 282 dns_zone_idetach(dns_zone_t **zonep);
 283 /*
 284  *      Detach from a zone decrementing its internal reference count.
 285  *      If there are no more internal or external references to the
 286  *      zone, it will be freed.
 287  *
 288  * Require:
 289  *      The caller is running in the context of the zone's task.
 290  *      'zonep' to point to a valid zone.
 291  */
 292
 293 void
 294 dns_zone_setflag(dns_zone_t *zone, unsigned int flags, isc_boolean_t value);
 295 /*
 296  *      Sets ('value' == 'ISC_TRUE') / clears ('value' == 'IS_FALSE')
 297  *      zone flags.  Valid flag bits are DNS_ZONE_F_*.
 298  *
 299  * Requires
 300  *      'zone' to be a valid zone.
 301  */
 302
 303 isc_result_t
 304 dns_zone_getdb(dns_zone_t *zone, dns_db_t **dbp);
 305 /*
 306  *      Attach '*dbp' to the database to if it exists otherwise
 307  *      return DNS_R_NOTLOADED.
 308  *
 309  * Require:
 310  *      'zone' to be a valid zone.
 311  *      'dbp' to be != NULL && '*dbp' == NULL.
 312  *
 313  * Returns:
 314  *      ISC_R_SUCCESS
 315  *      DNS_R_NOTLOADED
 316  */
 317
 318 isc_result_t
 319 dns_zone_setdbtype(dns_zone_t *zone,
 320                    unsigned int dbargc, const char * const *dbargv);
 321 /*
 322  *      Sets the database type to dbargv[0] and database arguments
 323  *      to subsequent dbargv elements.
 324  *      'db_type' is not checked to see if it is a valid database type.
 325  *
 326  * Require:
 327  *      'zone' to be a valid zone.
 328  *      'database' to be non NULL.
 329  *      'dbargc' to be >= 1
 330  *      'dbargv' to point to dbargc NULL-terminated strings
 331  *
 332  * Returns:
 333  *      ISC_R_NOMEMORY
 334  *      ISC_R_SUCCESS
 335  */
 336
 337 void
 338 dns_zone_markdirty(dns_zone_t *zone);
 339 /*
 340  *      Mark a zone as 'dirty'.
 341  *
 342  * Require:
 343  *      'zone' to be a valid zone.
 344  */
 345
 346 void
 347 dns_zone_expire(dns_zone_t *zone);
 348 /*
 349  *      Mark the zone as expired.  If the zone requires dumping cause it to
 350  *      be initiated.  Set the refresh and retry intervals to there default
 351  *      values and unload the zone.
 352  *
 353  * Require
 354  *      'zone' to be a valid zone.
 355  */
 356
 357 void
 358 dns_zone_refresh(dns_zone_t *zone);
 359 /*
 360  *      Initiate zone up to date checks.  The zone must already be being
 361  *      managed.
 362  *
 363  * Require
 364  *      'zone' to be a valid zone.
 365  */
 366
 367 isc_result_t
 368 dns_zone_flush(dns_zone_t *zone);
 369 /*
 370  *      Write the zone to database if there are uncommited changes.
 371  *
 372  * Require:
 373  *      'zone' to be a valid zone.
 374  */
 375
 376 isc_result_t
 377 dns_zone_dump(dns_zone_t *zone);
 378 /*
 379  *      Write the zone to database.
 380  *
 381  * Require:
 382  *      'zone' to be a valid zone.
 383  */
 384
 385 isc_result_t
 386 dns_zone_dumptostream(dns_zone_t *zone, FILE *fd);
 387 /*
 388  *      Write the zone to stream 'fd'.
 389  *
 390  * Require:
 391  *      'zone' to be a valid zone.
 392  *      'fd' to be a stream open for writing.
 393  */
 394
 395 isc_result_t
 396 dns_zone_fulldumptostream(dns_zone_t *zone, FILE *fd);
 397 /*
 398  *      The same as dns_zone_dumptostream, but dumps the zone with
 399  *      different dump settings (dns_master_style_full).
 400  *
 401  * Require:
 402  *      'zone' to be a valid zone.
 403  *      'fd' to be a stream open for writing.
 404  */
 405
 406 void
 407 dns_zone_maintenance(dns_zone_t *zone);
 408 /*
 409  *      Perform regular maintenace on the zone.  This is called as a
 410  *      result of a zone being managed.
 411  *
 412  * Require
 413  *      'zone' to be a valid zone.
 414  */
 415
 416 isc_result_t
 417 dns_zone_setmasters(dns_zone_t *zone, const isc_sockaddr_t *masters,
 418                     isc_uint32_t count);
 419 isc_result_t
 420 dns_zone_setmasterswithkeys(dns_zone_t *zone,
 421                             const isc_sockaddr_t *masters,
 422                             dns_name_t **keynames,
 423                             isc_uint32_t count);
 424 /*
 425  *      Set the list of master servers for the zone.
 426  *
 427  * Require:
 428  *      'zone' to be a valid zone.
 429  *      'masters' array of isc_sockaddr_t with port set or NULL.
 430  *      'count' the number of masters.
 431  *      'keynames' array of dns_name_t's for tsig keys or NULL.
 432  *
 433  *      dns_zone_setmasters() is just a wrapper to setmasterswithkeys(),
 434  *      passing NULL in the keynames field.
 435  *
 436  *      If 'masters' is NULL then 'count' must be zero.
 437  *
 438  * Returns:
 439  *      ISC_R_SUCCESS
 440  *      ISC_R_NOMEMORY
 441  *      Any result dns_name_dup() can return, if keynames!=NULL
 442  */
 443
 444 isc_result_t
 445 dns_zone_setalsonotify(dns_zone_t *zone, const isc_sockaddr_t *notify,
 446                        isc_uint32_t count);
 447 /*
 448  *      Set the list of additional servers to be notified when
 449  *      a zone changes.  To clear the list use 'count = 0'.
 450  *
 451  * Require:
 452  *      'zone' to be a valid zone.
 453  *      'notify' to be non-NULL if count != 0.
 454  *      'count' to be the number of notifyees.
 455  *
 456  * Returns:
 457  *      ISC_R_SUCCESS
 458  *      ISC_R_NOMEMORY
 459  */
 460
 461 void
 462 dns_zone_unload(dns_zone_t *zone);
 463 /*
 464  *      detach the database from the zone structure.
 465  *
 466  * Require:
 467  *      'zone' to be a valid zone.
 468  */
 469
 470 void
 471 dns_zone_setoption(dns_zone_t *zone, unsigned int option, isc_boolean_t value);
 472 /*
 473  *      Set given options on ('value' == ISC_TRUE) or off ('value' ==
 474  *      ISC_FALSE).
 475  *
 476  * Require:
 477  *      'zone' to be a valid zone.
 478  */
 479
 480 unsigned int
 481 dns_zone_getoptions(dns_zone_t *zone);
 482 /*
 483  *      Returns the current zone options.
 484  *
 485  * Require:
 486  *      'zone' to be a valid zone.
 487  */
 488
 489 void
 490 dns_zone_setminrefreshtime(dns_zone_t *zone, isc_uint32_t val);
 491 /*
 492  *      Set the minimum refresh time.
 493  *
 494  * Requires:
 495  *      'zone' is valid.
 496  *      val > 0.
 497  */
 498
 499 void
 500 dns_zone_setmaxrefreshtime(dns_zone_t *zone, isc_uint32_t val);
 501 /*
 502  *      Set the maximum refresh time.
 503  *
 504  * Requires:
 505  *      'zone' is valid.
 506  *      val > 0.
 507  */
 508
 509 void
 510 dns_zone_setminretrytime(dns_zone_t *zone, isc_uint32_t val);
 511 /*
 512  *      Set the minimum retry time.
 513  *
 514  * Requires:
 515  *      'zone' is valid.
 516  *      val > 0.
 517  */
 518
 519 void
 520 dns_zone_setmaxretrytime(dns_zone_t *zone, isc_uint32_t val);
 521 /*
 522  *      Set the maximum retry time.
 523  *
 524  * Requires:
 525  *      'zone' is valid.
 526  *      val > 0.
 527  */
 528
 529 isc_result_t
 530 dns_zone_setxfrsource4(dns_zone_t *zone, const isc_sockaddr_t *xfrsource);
 531 isc_result_t
 532 dns_zone_setaltxfrsource4(dns_zone_t *zone,
 533                           const isc_sockaddr_t *xfrsource);
 534 /*
 535  *      Set the source address to be used in IPv4 zone transfers.
 536  *
 537  * Require:
 538  *      'zone' to be a valid zone.
 539  *      'xfrsource' to contain the address.
 540  *
 541  * Returns:
 542  *      ISC_R_SUCCESS
 543  */
 544
 545 isc_sockaddr_t *
 546 dns_zone_getxfrsource4(dns_zone_t *zone);
 547 isc_sockaddr_t *
 548 dns_zone_getaltxfrsource4(dns_zone_t *zone);
 549 /*
 550  *      Returns the source address set by a previous dns_zone_setxfrsource4
 551  *      call, or the default of inaddr_any, port 0.
 552  *
 553  * Require:
 554  *      'zone' to be a valid zone.
 555  */
 556
 557 isc_result_t
 558 dns_zone_setxfrsource6(dns_zone_t *zone, const isc_sockaddr_t *xfrsource);
 559 isc_result_t
 560 dns_zone_setaltxfrsource6(dns_zone_t *zone,
 561                          const isc_sockaddr_t *xfrsource);
 562 /*
 563  *      Set the source address to be used in IPv6 zone transfers.
 564  *
 565  * Require:
 566  *      'zone' to be a valid zone.
 567  *      'xfrsource' to contain the address.
 568  *
 569  * Returns:
 570  *      ISC_R_SUCCESS
 571  */
 572
 573 isc_sockaddr_t *
 574 dns_zone_getxfrsource6(dns_zone_t *zone);
 575 isc_sockaddr_t *
 576 dns_zone_getaltxfrsource6(dns_zone_t *zone);
 577 /*
 578  *      Returns the source address set by a previous dns_zone_setxfrsource6
 579  *      call, or the default of in6addr_any, port 0.
 580  *
 581  * Require:
 582  *      'zone' to be a valid zone.
 583  */
 584
 585 isc_result_t
 586 dns_zone_setnotifysrc4(dns_zone_t *zone, const isc_sockaddr_t *notifysrc);
 587 /*
 588  *      Set the source address to be used with IPv4 NOTIFY messages.
 589  *
 590  * Require:
 591  *      'zone' to be a valid zone.
 592  *      'notifysrc' to contain the address.
 593  *
 594  * Returns:
 595  *      ISC_R_SUCCESS
 596  */
 597
 598 isc_sockaddr_t *
 599 dns_zone_getnotifysrc4(dns_zone_t *zone);
 600 /*
 601  *      Returns the source address set by a previous dns_zone_setnotifysrc4
 602  *      call, or the default of inaddr_any, port 0.
 603  *
 604  * Require:
 605  *      'zone' to be a valid zone.
 606  */
 607
 608 isc_result_t
 609 dns_zone_setnotifysrc6(dns_zone_t *zone, const isc_sockaddr_t *notifysrc);
 610 /*
 611  *      Set the source address to be used with IPv6 NOTIFY messages.
 612  *
 613  * Require:
 614  *      'zone' to be a valid zone.
 615  *      'notifysrc' to contain the address.
 616  *
 617  * Returns:
 618  *      ISC_R_SUCCESS
 619  */
 620
 621 isc_sockaddr_t *
 622 dns_zone_getnotifysrc6(dns_zone_t *zone);
 623 /*
 624  *      Returns the source address set by a previous dns_zone_setnotifysrc6
 625  *      call, or the default of in6addr_any, port 0.
 626  *
 627  * Require:
 628  *      'zone' to be a valid zone.
 629  */
 630
 631 void
 632 dns_zone_setnotifyacl(dns_zone_t *zone, dns_acl_t *acl);
 633 /*
 634  *      Sets the notify acl list for the zone.
 635  *
 636  * Require:
 637  *      'zone' to be a valid zone.
 638  *      'acl' to be a valid acl.
 639  */
 640
 641 void
 642 dns_zone_setqueryacl(dns_zone_t *zone, dns_acl_t *acl);
 643 /*
 644  *      Sets the query acl list for the zone.
 645  *
 646  * Require:
 647  *      'zone' to be a valid zone.
 648  *      'acl' to be a valid acl.
 649  */
 650
 651 void
 652 dns_zone_setupdateacl(dns_zone_t *zone, dns_acl_t *acl);
 653 /*
 654  *      Sets the update acl list for the zone.
 655  *
 656  * Require:
 657  *      'zone' to be a valid zone.
 658  *      'acl' to be valid acl.
 659  */
 660
 661 void
 662 dns_zone_setforwardacl(dns_zone_t *zone, dns_acl_t *acl);
 663 /*
 664  *      Sets the forward unsigned updates acl list for the zone.
 665  *
 666  * Require:
 667  *      'zone' to be a valid zone.
 668  *      'acl' to be valid acl.
 669  */
 670
 671 void
 672 dns_zone_setxfracl(dns_zone_t *zone, dns_acl_t *acl);
 673 /*
 674  *      Sets the transfer acl list for the zone.
 675  *
 676  * Require:
 677  *      'zone' to be a valid zone.
 678  *      'acl' to be valid acl.
 679  */
 680
 681 dns_acl_t *
 682 dns_zone_getnotifyacl(dns_zone_t *zone);
 683 /*
 684  *      Returns the current notify acl or NULL.
 685  *
 686  * Require:
 687  *      'zone' to be a valid zone.
 688  *
 689  * Returns:
 690  *      acl a pointer to the acl.
 691  *      NULL
 692  */
 693
 694 dns_acl_t *
 695 dns_zone_getqueryacl(dns_zone_t *zone);
 696 /*
 697  *      Returns the current query acl or NULL.
 698  *
 699  * Require:
 700  *      'zone' to be a valid zone.
 701  *
 702  * Returns:
 703  *      acl a pointer to the acl.
 704  *      NULL
 705  */
 706
 707 dns_acl_t *
 708 dns_zone_getupdateacl(dns_zone_t *zone);
 709 /*
 710  *      Returns the current update acl or NULL.
 711  *
 712  * Require:
 713  *      'zone' to be a valid zone.
 714  *
 715  * Returns:
 716  *      acl a pointer to the acl.
 717  *      NULL
 718  */
 719
 720 dns_acl_t *
 721 dns_zone_getforwardacl(dns_zone_t *zone);
 722 /*
 723  *      Returns the current forward unsigned updates acl or NULL.
 724  *
 725  * Require:
 726  *      'zone' to be a valid zone.
 727  *
 728  * Returns:
 729  *      acl a pointer to the acl.
 730  *      NULL
 731  */
 732
 733 dns_acl_t *
 734 dns_zone_getxfracl(dns_zone_t *zone);
 735 /*
 736  *      Returns the current transfer acl or NULL.
 737  *
 738  * Require:
 739  *      'zone' to be a valid zone.
 740  *
 741  * Returns:
 742  *      acl a pointer to the acl.
 743  *      NULL
 744  */
 745
 746 void
 747 dns_zone_clearupdateacl(dns_zone_t *zone);
 748 /*
 749  *      Clear the current update acl.
 750  *
 751  * Require:
 752  *      'zone' to be a valid zone.
 753  */
 754
 755 void
 756 dns_zone_clearforwardacl(dns_zone_t *zone);
 757 /*
 758  *      Clear the current forward unsigned updates acl.
 759  *
 760  * Require:
 761  *      'zone' to be a valid zone.
 762  */
 763
 764 void
 765 dns_zone_clearnotifyacl(dns_zone_t *zone);
 766 /*
 767  *      Clear the current notify acl.
 768  *
 769  * Require:
 770  *      'zone' to be a valid zone.
 771  */
 772
 773 void
 774 dns_zone_clearqueryacl(dns_zone_t *zone);
 775 /*
 776  *      Clear the current query acl.
 777  *
 778  * Require:
 779  *      'zone' to be a valid zone.
 780  */
 781
 782 void
 783 dns_zone_clearxfracl(dns_zone_t *zone);
 784 /*
 785  *      Clear the current transfer acl.
 786  *
 787  * Require:
 788  *      'zone' to be a valid zone.
 789  */
 790
 791 isc_boolean_t
 792 dns_zone_getupdatedisabled(dns_zone_t *zone);
 793
 794 void
 795 dns_zone_setupdatedisabled(dns_zone_t *zone, isc_boolean_t state);
 796
 797 void
 798 dns_zone_setchecknames(dns_zone_t *zone, dns_severity_t severity);
 799 /*
 800  *      Set the severity of name checking when loading a zone.
 801  *
 802  * Require:
 803  *      'zone' to be a valid zone.
 804  */
 805
 806 dns_severity_t
 807 dns_zone_getchecknames(dns_zone_t *zone);
 808 /*
 809  *      Return the current severity of name checking.
 810  *
 811  * Require:
 812  *      'zone' to be a valid zone.
 813  */
 814
 815 void
 816 dns_zone_setjournalsize(dns_zone_t *zone, isc_int32_t size);
 817 /*
 818  *      Sets the journal size for the zone.
 819  *
 820  * Requires:
 821  *      'zone' to be a valid zone.
 822  */
 823
 824 isc_int32_t
 825 dns_zone_getjournalsize(dns_zone_t *zone);
 826 /*
 827  *      Return the journal size as set with a previous call to
 828  *      dns_zone_setjournalsize().
 829  *
 830  * Requires:
 831  *      'zone' to be a valid zone.
 832  */
 833
 834 isc_result_t
 835 dns_zone_notifyreceive(dns_zone_t *zone, isc_sockaddr_t *from,
 836                        dns_message_t *msg);
 837 /*
 838  *      Tell the zone that it has recieved a NOTIFY message from another
 839  *      server.  This may cause some zone maintainence activity to occur.
 840  *
 841  * Requires:
 842  *      'zone' to be a valid zone.
 843  *      '*from' to contain the address of the server from which 'msg'
 844  *              was recieved.
 845  *      'msg' a message with opcode NOTIFY and qr clear.
 846  *
 847  * Returns:
 848  *      DNS_R_REFUSED
 849  *      DNS_R_NOTIMP
 850  *      DNS_R_FORMERR
 851  *      DNS_R_SUCCESS
 852  */
 853
 854 void
 855 dns_zone_setmaxxfrin(dns_zone_t *zone, isc_uint32_t maxxfrin);
 856 /*
 857  * Set the maximum time (in seconds) that a zone transfer in (AXFR/IXFR)
 858  * of this zone will use before being aborted.
 859  *
 860  * Requires:
 861  *      'zone' to be valid initialised zone.
 862  */
 863
 864 isc_uint32_t
 865 dns_zone_getmaxxfrin(dns_zone_t *zone);
 866 /*
 867  * Returns the maximum transfer time for this zone.  This will be
 868  * either the value set by the last call to dns_zone_setmaxxfrin() or
 869  * the default value of 1 hour.
 870  *
 871  * Requires:
 872  *      'zone' to be valid initialised zone.
 873  */
 874
 875 void
 876 dns_zone_setmaxxfrout(dns_zone_t *zone, isc_uint32_t maxxfrout);
 877 /*
 878  * Set the maximum time (in seconds) that a zone transfer out (AXFR/IXFR)
 879  * of this zone will use before being aborted.
 880  *
 881  * Requires:
 882  *      'zone' to be valid initialised zone.
 883  */
 884
 885 isc_uint32_t
 886 dns_zone_getmaxxfrout(dns_zone_t *zone);
 887 /*
 888  * Returns the maximum transfer time for this zone.  This will be
 889  * either the value set by the last call to dns_zone_setmaxxfrout() or
 890  * the default value of 1 hour.
 891  *
 892  * Requires:
 893  *      'zone' to be valid initialised zone.
 894  */
 895
 896 isc_result_t
 897 dns_zone_setjournal(dns_zone_t *zone, const char *journal);
 898 /*
 899  * Sets the filename used for journaling updates / IXFR transfers.
 900  * The default journal name is set by dns_zone_setfile() to be
 901  * "file.jnl".  If 'journal' is NULL, the zone will have no
 902  * journal name.
 903  *
 904  * Requires:
 905  *      'zone' to be a valid zone.
 906  *
 907  * Returns:
 908  *      ISC_R_SUCCESS
 909  *      ISC_R_NOMEMORY
 910  */
 911
 912 char *
 913 dns_zone_getjournal(dns_zone_t *zone);
 914 /*
 915  * Returns the journal name associated with this zone.
 916  * If no journal has been set this will be NULL.
 917  *
 918  * Requires:
 919  *      'zone' to be valid initialised zone.
 920  */
 921
 922 dns_zonetype_t
 923 dns_zone_gettype(dns_zone_t *zone);
 924 /*
 925  * Returns the type of the zone (master/slave/etc.)
 926  *
 927  * Requires:
 928  *      'zone' to be valid initialised zone.
 929  */
 930
 931 void
 932 dns_zone_settask(dns_zone_t *zone, isc_task_t *task);
 933 /*
 934  * Give a zone a task to work with.  Any current task will be detached.
 935  *
 936  * Requires:
 937  *      'zone' to be valid.
 938  *      'task' to be valid.
 939  */
 940
 941 void
 942 dns_zone_gettask(dns_zone_t *zone, isc_task_t **target);
 943 /*
 944  * Attach '*target' to the zone's task.
 945  *
 946  * Requires:
 947  *      'zone' to be valid initialised zone.
 948  *      'zone' to have a task.
 949  *      'target' to be != NULL && '*target' == NULL.
 950  */
 951
 952 void
 953 dns_zone_notify(dns_zone_t *zone);
 954 /*
 955  * Generate notify events for this zone.
 956  *
 957  * Requires:
 958  *      'zone' to be a valid zone.
 959  */
 960
 961 isc_result_t
 962 dns_zone_replacedb(dns_zone_t *zone, dns_db_t *db, isc_boolean_t dump);
 963 /*
 964  * Replace the database of "zone" with a new database "db".
 965  *
 966  * If "dump" is ISC_TRUE, then the new zone contents are dumped
 967  * into to the zone's master file for persistence.  When replacing
 968  * a zone database by one just loaded from a master file, set
 969  * "dump" to ISC_FALSE to avoid a redunant redump of the data just
 970  * loaded.  Otherwise, it should be set to ISC_TRUE.
 971  *
 972  * If the "diff-on-reload" option is enabled in the configuration file,
 973  * the differences between the old and the new database are added to the
 974  * journal file, and the master file dump is postponed.
 975  *
 976  * Requires:
 977  *      'zone' to be a valid zone.
 978  *
 979  * Returns:
 980  *      DNS_R_SUCCESS
 981  *      DNS_R_BADZONE   zone failed basic consistancy checks:
 982  *                      * a single SOA must exist
 983  *                      * some NS records must exist.
 984  *      Others
 985  */
 986
 987 isc_uint32_t
 988 dns_zone_getidlein(dns_zone_t *zone);
 989 /*
 990  * Requires:
 991  *      'zone' to be a valid zone.
 992  *
 993  * Returns:
 994  *      number of seconds of idle time before we abort the transfer in.
 995  */
 996
 997 void
 998 dns_zone_setidlein(dns_zone_t *zone, isc_uint32_t idlein);
 999 /*
1000  *      Set the idle timeout for transfer the.
1001  *      Zero set the default value, 1 hour.
1002  *
1003  * Requires:
1004  *      'zone' to be a valid zone.
1005  */
1006
1007 isc_uint32_t
1008 dns_zone_getidleout(dns_zone_t *zone);
1009 /*
1010  *
1011  * Requires:
1012  *      'zone' to be a valid zone.
1013  *
1014  * Returns:
1015  *      number of seconds of idle time before we abort a transfer out.
1016  */
1017
1018 void
1019 dns_zone_setidleout(dns_zone_t *zone, isc_uint32_t idleout);
1020 /*
1021  *      Set the idle timeout for transfers out.
1022  *      Zero set the default value, 1 hour.
1023  *
1024  * Requires:
1025  *      'zone' to be a valid zone.
1026  */
1027
1028 void
1029 dns_zone_getssutable(dns_zone_t *zone, dns_ssutable_t **table);
1030 /*
1031  * Get the simple-secure-update policy table.
1032  *
1033  * Requires:
1034  *      'zone' to be a valid zone.
1035  */
1036
1037 void
1038 dns_zone_setssutable(dns_zone_t *zone, dns_ssutable_t *table);
1039 /*
1040  * Set / clear the simple-secure-update policy table.
1041  *
1042  * Requires:
1043  *      'zone' to be a valid zone.
1044  */
1045
1046 isc_mem_t *
1047 dns_zone_getmctx(dns_zone_t *zone);
1048 /*
1049  * Get the memory context of a zone.
1050  *
1051  * Requires:
1052  *      'zone' to be a valid zone.
1053  */
1054
1055 dns_zonemgr_t *
1056 dns_zone_getmgr(dns_zone_t *zone);
1057 /*
1058  *      If 'zone' is managed return the zone manager otherwise NULL.
1059  *
1060  * Requires:
1061  *      'zone' to be a valid zone.
1062  */
1063
1064 void
1065 dns_zone_setsigvalidityinterval(dns_zone_t *zone, isc_uint32_t interval);
1066 /*
1067  * Set the zone's SIG validity interval.  This is the length of time
1068  * for which DNSSEC signatures created as a result of dynamic updates
1069  * to secure zones will remain valid, in seconds.
1070  *
1071  * Requires:
1072  *      'zone' to be a valid zone.
1073  */
1074
1075 isc_uint32_t
1076 dns_zone_getsigvalidityinterval(dns_zone_t *zone);
1077 /*
1078  * Get the zone's SIG validity interval.
1079  *
1080  * Requires:
1081  *      'zone' to be a valid zone.
1082  */
1083
1084 void
1085 dns_zone_setnotifytype(dns_zone_t *zone, dns_notifytype_t notifytype);
1086 /*
1087  * Sets zone notify method to "notifytype"
1088  */
1089
1090 isc_result_t
1091 dns_zone_forwardupdate(dns_zone_t *zone, dns_message_t *msg,
1092                        dns_updatecallback_t callback, void *callback_arg);
1093 /*
1094  * Forward 'msg' to each master in turn until we get an answer or we
1095  * have exausted the list of masters. 'callback' will be called with
1096  * ISC_R_SUCCESS if we get an answer and the returned message will be
1097  * passed as 'answer_message', otherwise a non ISC_R_SUCCESS result code
1098  * will be passed and answer_message will be NULL.  The callback function
1099  * is responsible for destroying 'answer_message'.
1100  *              (callback)(callback_arg, result, answer_message);
1101  *
1102  * Require:
1103  *      'zone' to be valid
1104  *      'msg' to be valid.
1105  *      'callback' to be non NULL.
1106  * Returns:
1107  *      ISC_R_SUCCESS if the message has been forwarded,
1108  *      ISC_R_NOMEMORY
1109  *      Others
1110  */
1111
1112 isc_result_t
1113 dns_zone_next(dns_zone_t *zone, dns_zone_t **next);
1114 /*
1115  * Find the next zone in the list of managed zones.
1116  *
1117  * Requires:
1118  *      'zone' to be valid
1119  *      The zone manager for the indicated zone MUST be locked
1120  *      by the caller.  This is not checked.
1121  *      'next' be non-NULL, and '*next' be NULL.
1122  *
1123  * Ensures:
1124  *      'next' points to a valid zone (result ISC_R_SUCCESS) or to NULL
1125  *      (result ISC_R_NOMORE).
1126  */
1127
1128 isc_result_t
1129 dns_zone_first(dns_zonemgr_t *zmgr, dns_zone_t **first);
1130 /*
1131  * Find the first zone in the list of managed zones.
1132  *
1133  * Requires:
1134  *      'zonemgr' to be valid
1135  *      The zone manager for the indicated zone MUST be locked
1136  *      by the caller.  This is not checked.
1137  *      'first' be non-NULL, and '*first' be NULL
1138  *
1139  * Ensures:
1140  *      'first' points to a valid zone (result ISC_R_SUCCESS) or to NULL
1141  *      (result ISC_R_NOMORE).
1142  */
1143
1144 isc_result_t
1145 dns_zone_setkeydirectory(dns_zone_t *zone, const char *directory);
1146 /*
1147  *      Sets the name of the directory where private keys used for
1148  *      online signing of dynamic zones are found.
1149  *
1150  * Require:
1151  *      'zone' to be a valid zone.
1152  *
1153  * Returns:
1154  *      ISC_R_NOMEMORY
1155  *      ISC_R_SUCCESS
1156  */
1157
1158 const char *
1159 dns_zone_getkeydirectory(dns_zone_t *zone);
1160 /*
1161  *      Gets the name of the directory where private keys used for
1162  *      online signing of dynamic zones are found.
1163  *
1164  * Requires:
1165  *      'zone' to be valid initialised zone.
1166  *
1167  * Returns:
1168  *      Pointer to null-terminated file name, or NULL.
1169  */
1170
1171
1172 isc_result_t
1173 dns_zonemgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr,
1174                    isc_timermgr_t *timermgr, isc_socketmgr_t *socketmgr,
1175                    dns_zonemgr_t **zmgrp);
1176 /*
1177  * Create a zone manager.
1178  *
1179  * Requires:
1180  *      'mctx' to be a valid memory context.
1181  *      'taskmgr' to be a valid task manager.
1182  *      'timermgr' to be a valid timer manager.
1183  *      'zmgrp' to point to a NULL pointer.
1184  */
1185
1186 isc_result_t
1187 dns_zonemgr_managezone(dns_zonemgr_t *zmgr, dns_zone_t *zone);
1188 /*
1189  *      Bring the zone under control of a zone manager.
1190  *
1191  * Require:
1192  *      'zmgr' to be a valid zone manager.
1193  *      'zone' to be a valid zone.
1194  */
1195
1196 isc_result_t
1197 dns_zonemgr_forcemaint(dns_zonemgr_t *zmgr);
1198 /*
1199  * Force zone maintenance of all zones managed by 'zmgr' at its
1200  * earliest conveniene.
1201  */
1202
1203 void
1204 dns_zonemgr_resumexfrs(dns_zonemgr_t *zmgr);
1205 /*
1206  * Attempt to start any stalled zone transfers.
1207  */
1208
1209 void
1210 dns_zonemgr_shutdown(dns_zonemgr_t *zmgr);
1211 /*
1212  *      Shut down the zone manager.
1213  *
1214  * Requires:
1215  *      'zmgr' to be a valid zone manager.
1216  */
1217
1218 void
1219 dns_zonemgr_attach(dns_zonemgr_t *source, dns_zonemgr_t **target);
1220 /*
1221  *      Attach '*target' to 'source' incrementing its external
1222  *      reference count.
1223  *
1224  * Require:
1225  *      'zone' to be a valid zone.
1226  *      'target' to be non NULL and '*target' to be NULL.
1227  */
1228
1229 void
1230 dns_zonemgr_detach(dns_zonemgr_t **zmgrp);
1231 /*
1232  *       Detach from a zone manager.
1233  *
1234  * Requires:
1235  *      '*zmgrp' is a valid, non-NULL zone manager pointer.
1236  *
1237  * Ensures:
1238  *      '*zmgrp' is NULL.
1239  */
1240
1241 void
1242 dns_zonemgr_releasezone(dns_zonemgr_t *zmgr, dns_zone_t *zone);
1243 /*
1244  *      Release 'zone' from the managed by 'zmgr'.  'zmgr' is implicitly
1245  *      detached from 'zone'.
1246  *
1247  * Requires:
1248  *      'zmgr' to be a valid zone manager.
1249  *      'zone' to be a valid zone.
1250  *      'zmgr' == 'zone->zmgr'
1251  *
1252  * Ensures:
1253  *      'zone->zmgr' == NULL;
1254  */
1255
1256 void
1257 dns_zonemgr_settransfersin(dns_zonemgr_t *zmgr, isc_uint32_t value);
1258 /*
1259  *      Set the maximum number of simultaneous transfers in allowed by
1260  *      the zone manager.
1261  *
1262  * Requires:
1263  *      'zmgr' to be a valid zone manager.
1264  */
1265
1266 isc_uint32_t
1267 dns_zonemgr_getttransfersin(dns_zonemgr_t *zmgr);
1268 /*
1269  *      Return the the maximum number of simultaneous transfers in allowed.
1270  *
1271  * Requires:
1272  *      'zmgr' to be a valid zone manager.
1273  */
1274
1275 void
1276 dns_zonemgr_settransfersperns(dns_zonemgr_t *zmgr, isc_uint32_t value);
1277 /*
1278  *      Set the number of zone transfers allowed per nameserver.
1279  *
1280  * Requires:
1281  *      'zmgr' to be a valid zone manager
1282  */
1283
1284 isc_uint32_t
1285 dns_zonemgr_getttransfersperns(dns_zonemgr_t *zmgr);
1286 /*
1287  *      Return the number of transfers allowed per nameserver.
1288  *
1289  * Requires:
1290  *      'zmgr' to be a valid zone manager.
1291  */
1292
1293 void
1294 dns_zonemgr_setiolimit(dns_zonemgr_t *zmgr, isc_uint32_t iolimit);
1295 /*
1296  *      Set the number of simultaneous file descriptors available for
1297  *      reading and writing masterfiles.
1298  *
1299  * Requires:
1300  *      'zmgr' to be a valid zone manager.
1301  *      'iolimit' to be positive.
1302  */
1303
1304 isc_uint32_t
1305 dns_zonemgr_getiolimit(dns_zonemgr_t *zmgr);
1306 /*
1307  *      Get the number of simultaneous file descriptors available for
1308  *      reading and writing masterfiles.
1309  *
1310  * Requires:
1311  *      'zmgr' to be a valid zone manager.
1312  */
1313
1314 void
1315 dns_zonemgr_setserialqueryrate(dns_zonemgr_t *zmgr, unsigned int value);
1316 /*
1317  *      Set the number of SOA queries sent per second.
1318  *
1319  * Requires:
1320  *      'zmgr' to be a valid zone manager
1321  */
1322
1323 unsigned int
1324 dns_zonemgr_getserialqueryrate(dns_zonemgr_t *zmgr);
1325 /*
1326  *      Return the number of SOA queries sent per second.
1327  *
1328  * Requires:
1329  *      'zmgr' to be a valid zone manager.
1330  */
1331
1332 unsigned int
1333 dns_zonemgr_getcount(dns_zonemgr_t *zmgr, int state);
1334 /*
1335  *      Returns the number of zones in the specified state.
1336  *
1337  * Requires:
1338  *      'zmgr' to be a valid zone manager.
1339  *      'state' to be a valid DNS_ZONESTATE_ constant.
1340  */
1341
1342 void
1343 dns_zone_forcereload(dns_zone_t *zone);
1344 /*
1345  *      Force a reload of specified zone.
1346  *
1347  * Requires:
1348  *      'zone' to be a valid zone.
1349  */
1350
1351 isc_boolean_t
1352 dns_zone_isforced(dns_zone_t *zone);
1353 /*
1354  *      Check if the zone is waiting a forced reload.
1355  *
1356  * Requires:
1357  *      'zone' to be a valid zone.
1358  */
1359
1360 isc_result_t
1361 dns_zone_setstatistics(dns_zone_t *zone, isc_boolean_t on);
1362 /*
1363  *      Make the zone keep or not keep an array of statistics
1364  *      counter.
1365  *
1366  * Requires:
1367  *      zone be a valid zone.
1368  */
1369
1370 isc_uint64_t *
1371 dns_zone_getstatscounters(dns_zone_t *zone);
1372 /*
1373  * Requires:
1374  *      zone be a valid zone.
1375  *
1376  * Returns:
1377  *      A pointer to the zone's array of statistics counters,
1378  *      or NULL if it has none.
1379  */
1380
1381 void
1382 dns_zone_dialup(dns_zone_t *zone);
1383 /*
1384  * Perform dialup-time maintenance on 'zone'.
1385  */
1386
1387 void
1388 dns_zone_setdialup(dns_zone_t *zone, dns_dialuptype_t dialup);
1389 /*
1390  * Set the dialup type of 'zone' to 'dialup'.
1391  *
1392  * Requires:
1393  *      'zone' to be valid initialised zone.
1394  *      'dialup' to be a valid dialup type.
1395  */
1396
1397 void
1398 dns_zone_log(dns_zone_t *zone, int level, const char *msg, ...)
1399         ISC_FORMAT_PRINTF(3, 4);
1400 /*
1401  * Log the message 'msg...' at 'level', including text that identifies
1402  * the message as applying to 'zone'.
1403  */
1404
1405 void
1406 dns_zone_logc(dns_zone_t *zone, isc_logcategory_t *category, int level,
1407               const char *msg, ...) ISC_FORMAT_PRINTF(4, 5);
1408 /*
1409  * Log the message 'msg...' at 'level', including text that identifies
1410  * the message as applying to 'zone'.
1411  */
1412
1413 void
1414 dns_zone_name(dns_zone_t *zone, char *buf, size_t len);
1415 /*
1416  * Return the name of the zone with class and view.
1417  *
1418  * Requires:
1419  *      'zone' to be valid.
1420  *      'buf' to be non NULL.
1421  */
1422
1423 isc_result_t
1424 dns_zone_checknames(dns_zone_t *zone, dns_name_t *name, dns_rdata_t *rdata);
1425 /*
1426  * Check if this record meets the check-names policy.
1427  *
1428  * Requires:
1429  *      'zone' to be valid.
1430  *      'name' to be valid.
1431  *      'rdata' to be valid.
1432  *
1433  * Returns:
1434  *      DNS_R_SUCCESS           passed checks.
1435  *      DNS_R_BADOWNERNAME      failed ownername checks.
1436  *      DNS_R_BADNAME           failed rdata checks.
1437  */
1438
1439 ISC_LANG_ENDDECLS
1440
1441 #endif /* DNS_ZONE_H */