contrib/bind-9.2.4rc7/lib/dns/include/dns/zone.h

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