lib/dns/include/dns/zone.h

   1 /*
   2  * Copyright (C) 2004-2009  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: zone.h,v 1.174.4.1 2009/12/29 22:23:00 marka Exp $ */
  19
  20 #ifndef DNS_ZONE_H
  21 #define DNS_ZONE_H 1
  22
  23 /*! \file dns/zone.h */
  24
  25 /***
  26  ***    Imports
  27  ***/
  28
  29 #include <stdio.h>
  30
  31 #include <isc/formatcheck.h>
  32 #include <isc/lang.h>
  33 #include <isc/rwlock.h>
  34
  35 #include <dns/masterdump.h>
  36 #include <dns/rdatastruct.h>
  37 #include <dns/types.h>
  38
  39 typedef enum {
  40         dns_zone_none,
  41         dns_zone_master,
  42         dns_zone_slave,
  43         dns_zone_stub,
  44         dns_zone_key
  45 } dns_zonetype_t;
  46
  47 #define DNS_ZONEOPT_SERVERS       0x00000001U   /*%< perform server checks */
  48 #define DNS_ZONEOPT_PARENTS       0x00000002U   /*%< perform parent checks */
  49 #define DNS_ZONEOPT_CHILDREN      0x00000004U   /*%< perform child checks */
  50 #define DNS_ZONEOPT_NOTIFY        0x00000008U   /*%< perform NOTIFY */
  51 #define DNS_ZONEOPT_MANYERRORS    0x00000010U   /*%< return many errors on load */
  52 #define DNS_ZONEOPT_IXFRFROMDIFFS 0x00000020U   /*%< calculate differences */
  53 #define DNS_ZONEOPT_NOMERGE       0x00000040U   /*%< don't merge journal */
  54 #define DNS_ZONEOPT_CHECKNS       0x00000080U   /*%< check if NS's are addresses */
  55 #define DNS_ZONEOPT_FATALNS       0x00000100U   /*%< DNS_ZONEOPT_CHECKNS is fatal */
  56 #define DNS_ZONEOPT_MULTIMASTER   0x00000200U   /*%< this zone has multiple masters */
  57 #define DNS_ZONEOPT_USEALTXFRSRC  0x00000400U   /*%< use alternate transfer sources */
  58 #define DNS_ZONEOPT_CHECKNAMES    0x00000800U   /*%< check-names */
  59 #define DNS_ZONEOPT_CHECKNAMESFAIL 0x00001000U  /*%< fatal check-name failures */
  60 #define DNS_ZONEOPT_CHECKWILDCARD 0x00002000U   /*%< check for internal wildcards */
  61 #define DNS_ZONEOPT_CHECKMX       0x00004000U   /*%< check-mx */
  62 #define DNS_ZONEOPT_CHECKMXFAIL   0x00008000U   /*%< fatal check-mx failures */
  63 #define DNS_ZONEOPT_CHECKINTEGRITY 0x00010000U  /*%< perform integrity checks */
  64 #define DNS_ZONEOPT_CHECKSIBLING  0x00020000U   /*%< perform sibling glue checks */
  65 #define DNS_ZONEOPT_NOCHECKNS     0x00040000U   /*%< disable IN NS address checks */
  66 #define DNS_ZONEOPT_WARNMXCNAME   0x00080000U   /*%< warn on MX CNAME check */
  67 #define DNS_ZONEOPT_IGNOREMXCNAME 0x00100000U   /*%< ignore MX CNAME check */
  68 #define DNS_ZONEOPT_WARNSRVCNAME  0x00200000U   /*%< warn on SRV CNAME check */
  69 #define DNS_ZONEOPT_IGNORESRVCNAME 0x00400000U  /*%< ignore SRV CNAME check */
  70 #define DNS_ZONEOPT_UPDATECHECKKSK 0x00800000U  /*%< check dnskey KSK flag */
  71 #define DNS_ZONEOPT_TRYTCPREFRESH 0x01000000U   /*%< try tcp refresh on udp failure */
  72 #define DNS_ZONEOPT_NOTIFYTOSOA   0x02000000U   /*%< Notify the SOA MNAME */
  73 #define DNS_ZONEOPT_NSEC3TESTZONE 0x04000000U   /*%< nsec3-test-zone */
  74 #define DNS_ZONEOPT_SECURETOINSECURE 0x08000000U /*%< dnssec-secure-to-insecure */
  75 #define DNS_ZONEOPT_DNSKEYKSKONLY 0x10000000U   /*%< dnssec-dnskey-kskonly */
  76 #define DNS_ZONEOPT_CHECKDUPRR    0x20000000U   /*%< check-dup-records */
  77 #define DNS_ZONEOPT_CHECKDUPRRFAIL 0x40000000U  /*%< fatal check-dup-records failures */
  78
  79 #ifndef NOMINUM_PUBLIC
  80 /*
  81  * Nominum specific options build down.
  82  */
  83 #define DNS_ZONEOPT_NOTIFYFORWARD 0x80000000U   /* forward notify to master */
  84 #endif /* NOMINUM_PUBLIC */
  85
  86 /*
  87  * Zone key maintenance options
  88  */
  89 #define DNS_ZONEKEY_ALLOW       0x00000001U     /*%< fetch keys on command */
  90 #define DNS_ZONEKEY_MAINTAIN    0x00000002U     /*%< publish/sign on schedule */
  91 #define DNS_ZONEKEY_CREATE      0x00000004U     /*%< make keys when needed */
  92
  93 #ifndef DNS_ZONE_MINREFRESH
  94 #define DNS_ZONE_MINREFRESH                 300 /*%< 5 minutes */
  95 #endif
  96 #ifndef DNS_ZONE_MAXREFRESH
  97 #define DNS_ZONE_MAXREFRESH             2419200 /*%< 4 weeks */
  98 #endif
  99 #ifndef DNS_ZONE_DEFAULTREFRESH
 100 #define DNS_ZONE_DEFAULTREFRESH            3600 /*%< 1 hour */
 101 #endif
 102 #ifndef DNS_ZONE_MINRETRY
 103 #define DNS_ZONE_MINRETRY                   300 /*%< 5 minutes */
 104 #endif
 105 #ifndef DNS_ZONE_MAXRETRY
 106 #define DNS_ZONE_MAXRETRY               1209600 /*%< 2 weeks */
 107 #endif
 108 #ifndef DNS_ZONE_DEFAULTRETRY
 109 #define DNS_ZONE_DEFAULTRETRY                60 /*%< 1 minute, subject to
 110                                                    exponential backoff */
 111 #endif
 112
 113 #define DNS_ZONESTATE_XFERRUNNING       1
 114 #define DNS_ZONESTATE_XFERDEFERRED      2
 115 #define DNS_ZONESTATE_SOAQUERY          3
 116 #define DNS_ZONESTATE_ANY               4
 117
 118 ISC_LANG_BEGINDECLS
 119
 120 /***
 121  ***    Functions
 122  ***/
 123
 124 isc_result_t
 125 dns_zone_create(dns_zone_t **zonep, isc_mem_t *mctx);
 126 /*%<
 127  *      Creates a new empty zone and attach '*zonep' to it.
 128  *
 129  * Requires:
 130  *\li   'zonep' to point to a NULL pointer.
 131  *\li   'mctx' to be a valid memory context.
 132  *
 133  * Ensures:
 134  *\li   '*zonep' refers to a valid zone.
 135  *
 136  * Returns:
 137  *\li   #ISC_R_SUCCESS
 138  *\li   #ISC_R_NOMEMORY
 139  *\li   #ISC_R_UNEXPECTED
 140  */
 141
 142 void
 143 dns_zone_setclass(dns_zone_t *zone, dns_rdataclass_t rdclass);
 144 /*%<
 145  *      Sets the class of a zone.  This operation can only be performed
 146  *      once on a zone.
 147  *
 148  * Require:
 149  *\li   'zone' to be a valid zone.
 150  *\li   dns_zone_setclass() not to have been called since the zone was
 151  *      created.
 152  *\li   'rdclass' != dns_rdataclass_none.
 153  */
 154
 155 dns_rdataclass_t
 156 dns_zone_getclass(dns_zone_t *zone);
 157 /*%<
 158  *      Returns the current zone class.
 159  *
 160  * Requires:
 161  *\li   'zone' to be a valid zone.
 162  */
 163
 164 isc_result_t
 165 dns_zone_getserial2(dns_zone_t *zone, isc_uint32_t *serialp);
 166
 167 isc_uint32_t
 168 dns_zone_getserial(dns_zone_t *zone);
 169 /*%<
 170  *      Returns the current serial number of the zone.  On success, the SOA
 171  *      serial of the zone will be copied into '*serialp'.
 172  *      dns_zone_getserial() cannot catch failure cases and is deprecated by
 173  *      dns_zone_getserial2().
 174  *
 175  * Requires:
 176  *\li   'zone' to be a valid zone.
 177  *\li   'serialp' to be non NULL
 178  *
 179  * Returns:
 180  *\li   #ISC_R_SUCCESS
 181  *\li   #DNS_R_NOTLOADED        zone DB is not loaded
 182  */
 183
 184 void
 185 dns_zone_settype(dns_zone_t *zone, dns_zonetype_t type);
 186 /*%<
 187  *      Sets the zone type. This operation can only be performed once on
 188  *      a zone.
 189  *
 190  * Requires:
 191  *\li   'zone' to be a valid zone.
 192  *\li   dns_zone_settype() not to have been called since the zone was
 193  *      created.
 194  *\li   'type' != dns_zone_none
 195  */
 196
 197 void
 198 dns_zone_setview(dns_zone_t *zone, dns_view_t *view);
 199 /*%<
 200  *      Associate the zone with a view.
 201  *
 202  * Require:
 203  *\li   'zone' to be a valid zone.
 204  */
 205
 206 dns_view_t *
 207 dns_zone_getview(dns_zone_t *zone);
 208 /*%<
 209  *      Returns the zone's associated view.
 210  *
 211  * Requires:
 212  *\li   'zone' to be a valid zone.
 213  */
 214
 215 isc_result_t
 216 dns_zone_setorigin(dns_zone_t *zone, const dns_name_t *origin);
 217 /*%<
 218  *      Sets the zones origin to 'origin'.
 219  *
 220  * Require:
 221  *\li   'zone' to be a valid zone.
 222  *\li   'origin' to be non NULL.
 223  *
 224  * Returns:
 225  *\li   #ISC_R_SUCCESS
 226  *\li   #ISC_R_NOMEMORY
 227  */
 228
 229 dns_name_t *
 230 dns_zone_getorigin(dns_zone_t *zone);
 231 /*%<
 232  *      Returns the value of the origin.
 233  *
 234  * Require:
 235  *\li   'zone' to be a valid zone.
 236  */
 237
 238 isc_result_t
 239 dns_zone_setfile(dns_zone_t *zone, const char *file);
 240
 241 isc_result_t
 242 dns_zone_setfile2(dns_zone_t *zone, const char *file,
 243                   dns_masterformat_t format);
 244 /*%<
 245  *    Sets the name of the master file in the format of 'format' from which
 246  *    the zone loads its database to 'file'.
 247  *
 248  *    For zones that have no associated master file, 'file' will be NULL.
 249  *
 250  *      For zones with persistent databases, the file name
 251  *      setting is ignored.
 252  *
 253  *    dns_zone_setfile() is a backward-compatible form of
 254  *    dns_zone_setfile2(), which always specifies the
 255  *    dns_masterformat_text (RFC1035) format.
 256  *
 257  * Require:
 258  *\li   'zone' to be a valid zone.
 259  *
 260  * Returns:
 261  *\li   #ISC_R_NOMEMORY
 262  *\li   #ISC_R_SUCCESS
 263  */
 264
 265 const char *
 266 dns_zone_getfile(dns_zone_t *zone);
 267 /*%<
 268  *      Gets the name of the zone's master file, if any.
 269  *
 270  * Requires:
 271  *\li   'zone' to be valid initialised zone.
 272  *
 273  * Returns:
 274  *\li   Pointer to null-terminated file name, or NULL.
 275  */
 276
 277 isc_result_t
 278 dns_zone_load(dns_zone_t *zone);
 279
 280 isc_result_t
 281 dns_zone_loadnew(dns_zone_t *zone);
 282
 283 isc_result_t
 284 dns_zone_loadandthaw(dns_zone_t *zone);
 285 /*%<
 286  *      Cause the database to be loaded from its backing store.
 287  *      Confirm that the minimum requirements for the zone type are
 288  *      met, otherwise DNS_R_BADZONE is returned.
 289  *
 290  *      dns_zone_loadnew() only loads zones that are not yet loaded.
 291  *      dns_zone_load() also loads zones that are already loaded and
 292  *      and whose master file has changed since the last load.
 293  *      dns_zone_loadandthaw() is similar to dns_zone_load() but will
 294  *      also re-enable DNS UPDATEs when the load completes.
 295  *
 296  * Require:
 297  *\li   'zone' to be a valid zone.
 298  *
 299  * Returns:
 300  *\li   #ISC_R_UNEXPECTED
 301  *\li   #ISC_R_SUCCESS
 302  *\li   DNS_R_CONTINUE    Incremental load has been queued.
 303  *\li   DNS_R_UPTODATE    The zone has already been loaded based on
 304  *                        file system timestamps.
 305  *\li   DNS_R_BADZONE
 306  *\li   Any result value from dns_db_load().
 307  */
 308
 309 void
 310 dns_zone_attach(dns_zone_t *source, dns_zone_t **target);
 311 /*%<
 312  *      Attach '*target' to 'source' incrementing its external
 313  *      reference count.
 314  *
 315  * Require:
 316  *\li   'zone' to be a valid zone.
 317  *\li   'target' to be non NULL and '*target' to be NULL.
 318  */
 319
 320 void
 321 dns_zone_detach(dns_zone_t **zonep);
 322 /*%<
 323  *      Detach from a zone decrementing its external reference count.
 324  *      If this was the last external reference to the zone it will be
 325  *      shut down and eventually freed.
 326  *
 327  * Require:
 328  *\li   'zonep' to point to a valid zone.
 329  */
 330
 331 void
 332 dns_zone_iattach(dns_zone_t *source, dns_zone_t **target);
 333 /*%<
 334  *      Attach '*target' to 'source' incrementing its internal
 335  *      reference count.  This is intended for use by operations
 336  *      such as zone transfers that need to prevent the zone
 337  *      object from being freed but not from shutting down.
 338  *
 339  * Require:
 340  *\li   The caller is running in the context of the zone's task.
 341  *\li   'zone' to be a valid zone.
 342  *\li   'target' to be non NULL and '*target' to be NULL.
 343  */
 344
 345 void
 346 dns_zone_idetach(dns_zone_t **zonep);
 347 /*%<
 348  *      Detach from a zone decrementing its internal reference count.
 349  *      If there are no more internal or external references to the
 350  *      zone, it will be freed.
 351  *
 352  * Require:
 353  *\li   The caller is running in the context of the zone's task.
 354  *\li   'zonep' to point to a valid zone.
 355  */
 356
 357 void
 358 dns_zone_setflag(dns_zone_t *zone, unsigned int flags, isc_boolean_t value);
 359 /*%<
 360  *      Sets ('value' == 'ISC_TRUE') / clears ('value' == 'IS_FALSE')
 361  *      zone flags.  Valid flag bits are DNS_ZONE_F_*.
 362  *
 363  * Requires
 364  *\li   'zone' to be a valid zone.
 365  */
 366
 367 isc_result_t
 368 dns_zone_getdb(dns_zone_t *zone, dns_db_t **dbp);
 369 /*%<
 370  *      Attach '*dbp' to the database to if it exists otherwise
 371  *      return DNS_R_NOTLOADED.
 372  *
 373  * Require:
 374  *\li   'zone' to be a valid zone.
 375  *\li   'dbp' to be != NULL && '*dbp' == NULL.
 376  *
 377  * Returns:
 378  *\li   #ISC_R_SUCCESS
 379  *\li   DNS_R_NOTLOADED
 380  */
 381
 382 isc_result_t
 383 dns_zone_setdbtype(dns_zone_t *zone,
 384                    unsigned int dbargc, const char * const *dbargv);
 385 /*%<
 386  *      Sets the database type to dbargv[0] and database arguments
 387  *      to subsequent dbargv elements.
 388  *      'db_type' is not checked to see if it is a valid database type.
 389  *
 390  * Require:
 391  *\li   'zone' to be a valid zone.
 392  *\li   'database' to be non NULL.
 393  *\li   'dbargc' to be >= 1
 394  *\li   'dbargv' to point to dbargc NULL-terminated strings
 395  *
 396  * Returns:
 397  *\li   #ISC_R_NOMEMORY
 398  *\li   #ISC_R_SUCCESS
 399  */
 400
 401 isc_result_t
 402 dns_zone_getdbtype(dns_zone_t *zone, char ***argv, isc_mem_t *mctx);
 403 /*%<
 404  *      Returns the current dbtype.  isc_mem_free() should be used
 405  *      to free 'argv' after use.
 406  *
 407  * Require:
 408  *\li   'zone' to be a valid zone.
 409  *\li   'argv' to be non NULL and *argv to be NULL.
 410  *\li   'mctx' to be valid.
 411  *
 412  * Returns:
 413  *\li   #ISC_R_NOMEMORY
 414  *\li   #ISC_R_SUCCESS
 415  */
 416
 417 void
 418 dns_zone_markdirty(dns_zone_t *zone);
 419 /*%<
 420  *      Mark a zone as 'dirty'.
 421  *
 422  * Require:
 423  *\li   'zone' to be a valid zone.
 424  */
 425
 426 void
 427 dns_zone_expire(dns_zone_t *zone);
 428 /*%<
 429  *      Mark the zone as expired.  If the zone requires dumping cause it to
 430  *      be initiated.  Set the refresh and retry intervals to there default
 431  *      values and unload the zone.
 432  *
 433  * Require
 434  *\li   'zone' to be a valid zone.
 435  */
 436
 437 void
 438 dns_zone_refresh(dns_zone_t *zone);
 439 /*%<
 440  *      Initiate zone up to date checks.  The zone must already be being
 441  *      managed.
 442  *
 443  * Require
 444  *\li   'zone' to be a valid zone.
 445  */
 446
 447 isc_result_t
 448 dns_zone_flush(dns_zone_t *zone);
 449 /*%<
 450  *      Write the zone to database if there are uncommitted changes.
 451  *
 452  * Require:
 453  *\li   'zone' to be a valid zone.
 454  */
 455
 456 isc_result_t
 457 dns_zone_dump(dns_zone_t *zone);
 458 /*%<
 459  *      Write the zone to database.
 460  *
 461  * Require:
 462  *\li   'zone' to be a valid zone.
 463  */
 464
 465 isc_result_t
 466 dns_zone_dumptostream(dns_zone_t *zone, FILE *fd);
 467
 468 isc_result_t
 469 dns_zone_dumptostream2(dns_zone_t *zone, FILE *fd, dns_masterformat_t format,
 470                        const dns_master_style_t *style);
 471 /*%<
 472  *    Write the zone to stream 'fd' in the specified 'format'.
 473  *    If the 'format' is dns_masterformat_text (RFC1035), 'style' also
 474  *    specifies the file style (e.g., &dns_master_style_default).
 475  *
 476  *    dns_zone_dumptostream() is a backward-compatible form of
 477  *    dns_zone_dumptostream2(), which always uses the dns_masterformat_text
 478  *    format and the dns_master_style_default style.
 479  *
 480  *    Note that dns_zone_dumptostream2() is the most flexible form.  It
 481  *    can also provide the functionality of dns_zone_fulldumptostream().
 482  *
 483  * Require:
 484  *\li   'zone' to be a valid zone.
 485  *\li   'fd' to be a stream open for writing.
 486  */
 487
 488 isc_result_t
 489 dns_zone_fulldumptostream(dns_zone_t *zone, FILE *fd);
 490 /*%<
 491  *      The same as dns_zone_dumptostream, but dumps the zone with
 492  *      different dump settings (dns_master_style_full).
 493  *
 494  * Require:
 495  *\li   'zone' to be a valid zone.
 496  *\li   'fd' to be a stream open for writing.
 497  */
 498
 499 void
 500 dns_zone_maintenance(dns_zone_t *zone);
 501 /*%<
 502  *      Perform regular maintenance on the zone.  This is called as a
 503  *      result of a zone being managed.
 504  *
 505  * Require
 506  *\li   'zone' to be a valid zone.
 507  */
 508
 509 isc_result_t
 510 dns_zone_setmasters(dns_zone_t *zone, const isc_sockaddr_t *masters,
 511                     isc_uint32_t count);
 512 isc_result_t
 513 dns_zone_setmasterswithkeys(dns_zone_t *zone,
 514                             const isc_sockaddr_t *masters,
 515                             dns_name_t **keynames,
 516                             isc_uint32_t count);
 517 /*%<
 518  *      Set the list of master servers for the zone.
 519  *
 520  * Require:
 521  *\li   'zone' to be a valid zone.
 522  *\li   'masters' array of isc_sockaddr_t with port set or NULL.
 523  *\li   'count' the number of masters.
 524  *\li      'keynames' array of dns_name_t's for tsig keys or NULL.
 525  *
 526  *  \li    dns_zone_setmasters() is just a wrapper to setmasterswithkeys(),
 527  *      passing NULL in the keynames field.
 528  *
 529  * \li  If 'masters' is NULL then 'count' must be zero.
 530  *
 531  * Returns:
 532  *\li   #ISC_R_SUCCESS
 533  *\li   #ISC_R_NOMEMORY
 534  *\li      Any result dns_name_dup() can return, if keynames!=NULL
 535  */
 536
 537 isc_result_t
 538 dns_zone_setalsonotify(dns_zone_t *zone, const isc_sockaddr_t *notify,
 539                        isc_uint32_t count);
 540 /*%<
 541  *      Set the list of additional servers to be notified when
 542  *      a zone changes.  To clear the list use 'count = 0'.
 543  *
 544  * Require:
 545  *\li   'zone' to be a valid zone.
 546  *\li   'notify' to be non-NULL if count != 0.
 547  *\li   'count' to be the number of notifiees.
 548  *
 549  * Returns:
 550  *\li   #ISC_R_SUCCESS
 551  *\li   #ISC_R_NOMEMORY
 552  */
 553
 554 void
 555 dns_zone_unload(dns_zone_t *zone);
 556 /*%<
 557  *      detach the database from the zone structure.
 558  *
 559  * Require:
 560  *\li   'zone' to be a valid zone.
 561  */
 562
 563 void
 564 dns_zone_setoption(dns_zone_t *zone, unsigned int option, isc_boolean_t value);
 565 /*%<
 566  *      Set given options on ('value' == ISC_TRUE) or off ('value' ==
 567  *      #ISC_FALSE).
 568  *
 569  * Require:
 570  *\li   'zone' to be a valid zone.
 571  */
 572
 573 unsigned int
 574 dns_zone_getoptions(dns_zone_t *zone);
 575 /*%<
 576  *      Returns the current zone options.
 577  *
 578  * Require:
 579  *\li   'zone' to be a valid zone.
 580  */
 581
 582 void
 583 dns_zone_setkeyopt(dns_zone_t *zone, unsigned int option, isc_boolean_t value);
 584 /*%<
 585  *      Set key options on ('value' == ISC_TRUE) or off ('value' ==
 586  *      #ISC_FALSE).
 587  *
 588  * Require:
 589  *\li   'zone' to be a valid zone.
 590  */
 591
 592 unsigned int
 593 dns_zone_getkeyopts(dns_zone_t *zone);
 594 /*%<
 595  *      Returns the current zone key options.
 596  *
 597  * Require:
 598  *\li   'zone' to be a valid zone.
 599  */
 600
 601 void
 602 dns_zone_setminrefreshtime(dns_zone_t *zone, isc_uint32_t val);
 603 /*%<
 604  *      Set the minimum refresh time.
 605  *
 606  * Requires:
 607  *\li   'zone' is valid.
 608  *\li   val > 0.
 609  */
 610
 611 void
 612 dns_zone_setmaxrefreshtime(dns_zone_t *zone, isc_uint32_t val);
 613 /*%<
 614  *      Set the maximum refresh time.
 615  *
 616  * Requires:
 617  *\li   'zone' is valid.
 618  *\li   val > 0.
 619  */
 620
 621 void
 622 dns_zone_setminretrytime(dns_zone_t *zone, isc_uint32_t val);
 623 /*%<
 624  *      Set the minimum retry time.
 625  *
 626  * Requires:
 627  *\li   'zone' is valid.
 628  *\li   val > 0.
 629  */
 630
 631 void
 632 dns_zone_setmaxretrytime(dns_zone_t *zone, isc_uint32_t val);
 633 /*%<
 634  *      Set the maximum retry time.
 635  *
 636  * Requires:
 637  *\li   'zone' is valid.
 638  *      val > 0.
 639  */
 640
 641 isc_result_t
 642 dns_zone_setxfrsource4(dns_zone_t *zone, const isc_sockaddr_t *xfrsource);
 643 isc_result_t
 644 dns_zone_setaltxfrsource4(dns_zone_t *zone,
 645                           const isc_sockaddr_t *xfrsource);
 646 /*%<
 647  *      Set the source address to be used in IPv4 zone transfers.
 648  *
 649  * Require:
 650  *\li   'zone' to be a valid zone.
 651  *\li   'xfrsource' to contain the address.
 652  *
 653  * Returns:
 654  *\li   #ISC_R_SUCCESS
 655  */
 656
 657 isc_sockaddr_t *
 658 dns_zone_getxfrsource4(dns_zone_t *zone);
 659 isc_sockaddr_t *
 660 dns_zone_getaltxfrsource4(dns_zone_t *zone);
 661 /*%<
 662  *      Returns the source address set by a previous dns_zone_setxfrsource4
 663  *      call, or the default of inaddr_any, port 0.
 664  *
 665  * Require:
 666  *\li   'zone' to be a valid zone.
 667  */
 668
 669 isc_result_t
 670 dns_zone_setxfrsource6(dns_zone_t *zone, const isc_sockaddr_t *xfrsource);
 671 isc_result_t
 672 dns_zone_setaltxfrsource6(dns_zone_t *zone,
 673                           const isc_sockaddr_t *xfrsource);
 674 /*%<
 675  *      Set the source address to be used in IPv6 zone transfers.
 676  *
 677  * Require:
 678  *\li   'zone' to be a valid zone.
 679  *\li   'xfrsource' to contain the address.
 680  *
 681  * Returns:
 682  *\li   #ISC_R_SUCCESS
 683  */
 684
 685 isc_sockaddr_t *
 686 dns_zone_getxfrsource6(dns_zone_t *zone);
 687 isc_sockaddr_t *
 688 dns_zone_getaltxfrsource6(dns_zone_t *zone);
 689 /*%<
 690  *      Returns the source address set by a previous dns_zone_setxfrsource6
 691  *      call, or the default of in6addr_any, port 0.
 692  *
 693  * Require:
 694  *\li   'zone' to be a valid zone.
 695  */
 696
 697 isc_result_t
 698 dns_zone_setnotifysrc4(dns_zone_t *zone, const isc_sockaddr_t *notifysrc);
 699 /*%<
 700  *      Set the source address to be used with IPv4 NOTIFY messages.
 701  *
 702  * Require:
 703  *\li   'zone' to be a valid zone.
 704  *\li   'notifysrc' to contain the address.
 705  *
 706  * Returns:
 707  *\li   #ISC_R_SUCCESS
 708  */
 709
 710 isc_sockaddr_t *
 711 dns_zone_getnotifysrc4(dns_zone_t *zone);
 712 /*%<
 713  *      Returns the source address set by a previous dns_zone_setnotifysrc4
 714  *      call, or the default of inaddr_any, port 0.
 715  *
 716  * Require:
 717  *\li   'zone' to be a valid zone.
 718  */
 719
 720 isc_result_t
 721 dns_zone_setnotifysrc6(dns_zone_t *zone, const isc_sockaddr_t *notifysrc);
 722 /*%<
 723  *      Set the source address to be used with IPv6 NOTIFY messages.
 724  *
 725  * Require:
 726  *\li   'zone' to be a valid zone.
 727  *\li   'notifysrc' to contain the address.
 728  *
 729  * Returns:
 730  *\li   #ISC_R_SUCCESS
 731  */
 732
 733 isc_sockaddr_t *
 734 dns_zone_getnotifysrc6(dns_zone_t *zone);
 735 /*%<
 736  *      Returns the source address set by a previous dns_zone_setnotifysrc6
 737  *      call, or the default of in6addr_any, port 0.
 738  *
 739  * Require:
 740  *\li   'zone' to be a valid zone.
 741  */
 742
 743 void
 744 dns_zone_setnotifyacl(dns_zone_t *zone, dns_acl_t *acl);
 745 /*%<
 746  *      Sets the notify acl list for the zone.
 747  *
 748  * Require:
 749  *\li   'zone' to be a valid zone.
 750  *\li   'acl' to be a valid acl.
 751  */
 752
 753 void
 754 dns_zone_setqueryacl(dns_zone_t *zone, dns_acl_t *acl);
 755 /*%<
 756  *      Sets the query acl list for the zone.
 757  *
 758  * Require:
 759  *\li   'zone' to be a valid zone.
 760  *\li   'acl' to be a valid acl.
 761  */
 762
 763 void
 764 dns_zone_setqueryonacl(dns_zone_t *zone, dns_acl_t *acl);
 765 /*%<
 766  *      Sets the query-on acl list for the zone.
 767  *
 768  * Require:
 769  *\li   'zone' to be a valid zone.
 770  *\li   'acl' to be a valid acl.
 771  */
 772
 773 void
 774 dns_zone_setupdateacl(dns_zone_t *zone, dns_acl_t *acl);
 775 /*%<
 776  *      Sets the update acl list for the zone.
 777  *
 778  * Require:
 779  *\li   'zone' to be a valid zone.
 780  *\li   'acl' to be valid acl.
 781  */
 782
 783 void
 784 dns_zone_setforwardacl(dns_zone_t *zone, dns_acl_t *acl);
 785 /*%<
 786  *      Sets the forward unsigned updates acl list for the zone.
 787  *
 788  * Require:
 789  *\li   'zone' to be a valid zone.
 790  *\li   'acl' to be valid acl.
 791  */
 792
 793 void
 794 dns_zone_setxfracl(dns_zone_t *zone, dns_acl_t *acl);
 795 /*%<
 796  *      Sets the transfer acl list for the zone.
 797  *
 798  * Require:
 799  *\li   'zone' to be a valid zone.
 800  *\li   'acl' to be valid acl.
 801  */
 802
 803 dns_acl_t *
 804 dns_zone_getnotifyacl(dns_zone_t *zone);
 805 /*%<
 806  *      Returns the current notify acl or NULL.
 807  *
 808  * Require:
 809  *\li   'zone' to be a valid zone.
 810  *
 811  * Returns:
 812  *\li   acl a pointer to the acl.
 813  *\li   NULL
 814  */
 815
 816 dns_acl_t *
 817 dns_zone_getqueryacl(dns_zone_t *zone);
 818 /*%<
 819  *      Returns the current query acl or NULL.
 820  *
 821  * Require:
 822  *\li   'zone' to be a valid zone.
 823  *
 824  * Returns:
 825  *\li   acl a pointer to the acl.
 826  *\li   NULL
 827  */
 828
 829 dns_acl_t *
 830 dns_zone_getqueryonacl(dns_zone_t *zone);
 831 /*%<
 832  *      Returns the current query-on acl or NULL.
 833  *
 834  * Require:
 835  *\li   'zone' to be a valid zone.
 836  *
 837  * Returns:
 838  *\li   acl a pointer to the acl.
 839  *\li   NULL
 840  */
 841
 842 dns_acl_t *
 843 dns_zone_getupdateacl(dns_zone_t *zone);
 844 /*%<
 845  *      Returns the current update acl or NULL.
 846  *
 847  * Require:
 848  *\li   'zone' to be a valid zone.
 849  *
 850  * Returns:
 851  *\li   acl a pointer to the acl.
 852  *\li   NULL
 853  */
 854
 855 dns_acl_t *
 856 dns_zone_getforwardacl(dns_zone_t *zone);
 857 /*%<
 858  *      Returns the current forward unsigned updates acl or NULL.
 859  *
 860  * Require:
 861  *\li   'zone' to be a valid zone.
 862  *
 863  * Returns:
 864  *\li   acl a pointer to the acl.
 865  *\li   NULL
 866  */
 867
 868 dns_acl_t *
 869 dns_zone_getxfracl(dns_zone_t *zone);
 870 /*%<
 871  *      Returns the current transfer acl or NULL.
 872  *
 873  * Require:
 874  *\li   'zone' to be a valid zone.
 875  *
 876  * Returns:
 877  *\li   acl a pointer to the acl.
 878  *\li   NULL
 879  */
 880
 881 void
 882 dns_zone_clearupdateacl(dns_zone_t *zone);
 883 /*%<
 884  *      Clear the current update acl.
 885  *
 886  * Require:
 887  *\li   'zone' to be a valid zone.
 888  */
 889
 890 void
 891 dns_zone_clearforwardacl(dns_zone_t *zone);
 892 /*%<
 893  *      Clear the current forward unsigned updates acl.
 894  *
 895  * Require:
 896  *\li   'zone' to be a valid zone.
 897  */
 898
 899 void
 900 dns_zone_clearnotifyacl(dns_zone_t *zone);
 901 /*%<
 902  *      Clear the current notify acl.
 903  *
 904  * Require:
 905  *\li   'zone' to be a valid zone.
 906  */
 907
 908 void
 909 dns_zone_clearqueryacl(dns_zone_t *zone);
 910 /*%<
 911  *      Clear the current query acl.
 912  *
 913  * Require:
 914  *\li   'zone' to be a valid zone.
 915  */
 916
 917 void
 918 dns_zone_clearqueryonacl(dns_zone_t *zone);
 919 /*%<
 920  *      Clear the current query-on acl.
 921  *
 922  * Require:
 923  *\li   'zone' to be a valid zone.
 924  */
 925
 926 void
 927 dns_zone_clearxfracl(dns_zone_t *zone);
 928 /*%<
 929  *      Clear the current transfer acl.
 930  *
 931  * Require:
 932  *\li   'zone' to be a valid zone.
 933  */
 934
 935 isc_boolean_t
 936 dns_zone_getupdatedisabled(dns_zone_t *zone);
 937 /*%<
 938  * Return update disabled.
 939  * Transient unless called when running in isc_task_exclusive() mode.
 940  */
 941
 942 void
 943 dns_zone_setupdatedisabled(dns_zone_t *zone, isc_boolean_t state);
 944 /*%<
 945  * Set update disabled.
 946  * Should only be called only when running in isc_task_exclusive() mode.
 947  * Failure to do so may result in updates being committed after the
 948  * call has been made.
 949  */
 950
 951 isc_boolean_t
 952 dns_zone_getzeronosoattl(dns_zone_t *zone);
 953 /*%<
 954  * Return zero-no-soa-ttl status.
 955  */
 956
 957 void
 958 dns_zone_setzeronosoattl(dns_zone_t *zone, isc_boolean_t state);
 959 /*%<
 960  * Set zero-no-soa-ttl status.
 961  */
 962
 963 void
 964 dns_zone_setchecknames(dns_zone_t *zone, dns_severity_t severity);
 965 /*%<
 966  *      Set the severity of name checking when loading a zone.
 967  *
 968  * Require:
 969  * \li     'zone' to be a valid zone.
 970  */
 971
 972 dns_severity_t
 973 dns_zone_getchecknames(dns_zone_t *zone);
 974 /*%<
 975  *      Return the current severity of name checking.
 976  *
 977  * Require:
 978  *\li   'zone' to be a valid zone.
 979  */
 980
 981 void
 982 dns_zone_setjournalsize(dns_zone_t *zone, isc_int32_t size);
 983 /*%<
 984  *      Sets the journal size for the zone.
 985  *
 986  * Requires:
 987  *\li   'zone' to be a valid zone.
 988  */
 989
 990 isc_int32_t
 991 dns_zone_getjournalsize(dns_zone_t *zone);
 992 /*%<
 993  *      Return the journal size as set with a previous call to
 994  *      dns_zone_setjournalsize().
 995  *
 996  * Requires:
 997  *\li   'zone' to be a valid zone.
 998  */
 999
1000 isc_result_t
1001 dns_zone_notifyreceive(dns_zone_t *zone, isc_sockaddr_t *from,
1002                        dns_message_t *msg);
1003 /*%<
1004  *      Tell the zone that it has received a NOTIFY message from another
1005  *      server.  This may cause some zone maintenance activity to occur.
1006  *
1007  * Requires:
1008  *\li   'zone' to be a valid zone.
1009  *\li   '*from' to contain the address of the server from which 'msg'
1010  *              was received.
1011  *\li   'msg' a message with opcode NOTIFY and qr clear.
1012  *
1013  * Returns:
1014  *\li   DNS_R_REFUSED
1015  *\li   DNS_R_NOTIMP
1016  *\li   DNS_R_FORMERR
1017  *\li   DNS_R_SUCCESS
1018  */
1019
1020 void
1021 dns_zone_setmaxxfrin(dns_zone_t *zone, isc_uint32_t maxxfrin);
1022 /*%<
1023  * Set the maximum time (in seconds) that a zone transfer in (AXFR/IXFR)
1024  * of this zone will use before being aborted.
1025  *
1026  * Requires:
1027  * \li  'zone' to be valid initialised zone.
1028  */
1029
1030 isc_uint32_t
1031 dns_zone_getmaxxfrin(dns_zone_t *zone);
1032 /*%<
1033  * Returns the maximum transfer time for this zone.  This will be
1034  * either the value set by the last call to dns_zone_setmaxxfrin() or
1035  * the default value of 1 hour.
1036  *
1037  * Requires:
1038  *\li   'zone' to be valid initialised zone.
1039  */
1040
1041 void
1042 dns_zone_setmaxxfrout(dns_zone_t *zone, isc_uint32_t maxxfrout);
1043 /*%<
1044  * Set the maximum time (in seconds) that a zone transfer out (AXFR/IXFR)
1045  * of this zone will use before being aborted.
1046  *
1047  * Requires:
1048  * \li  'zone' to be valid initialised zone.
1049  */
1050
1051 isc_uint32_t
1052 dns_zone_getmaxxfrout(dns_zone_t *zone);
1053 /*%<
1054  * Returns the maximum transfer time for this zone.  This will be
1055  * either the value set by the last call to dns_zone_setmaxxfrout() or
1056  * the default value of 1 hour.
1057  *
1058  * Requires:
1059  *\li   'zone' to be valid initialised zone.
1060  */
1061
1062 isc_result_t
1063 dns_zone_setjournal(dns_zone_t *zone, const char *journal);
1064 /*%<
1065  * Sets the filename used for journaling updates / IXFR transfers.
1066  * The default journal name is set by dns_zone_setfile() to be
1067  * "file.jnl".  If 'journal' is NULL, the zone will have no
1068  * journal name.
1069  *
1070  * Requires:
1071  *\li   'zone' to be a valid zone.
1072  *
1073  * Returns:
1074  *\li   #ISC_R_SUCCESS
1075  *\li   #ISC_R_NOMEMORY
1076  */
1077
1078 char *
1079 dns_zone_getjournal(dns_zone_t *zone);
1080 /*%<
1081  * Returns the journal name associated with this zone.
1082  * If no journal has been set this will be NULL.
1083  *
1084  * Requires:
1085  *\li   'zone' to be valid initialised zone.
1086  */
1087
1088 dns_zonetype_t
1089 dns_zone_gettype(dns_zone_t *zone);
1090 /*%<
1091  * Returns the type of the zone (master/slave/etc.)
1092  *
1093  * Requires:
1094  *\li   'zone' to be valid initialised zone.
1095  */
1096
1097 void
1098 dns_zone_settask(dns_zone_t *zone, isc_task_t *task);
1099 /*%<
1100  * Give a zone a task to work with.  Any current task will be detached.
1101  *
1102  * Requires:
1103  *\li   'zone' to be valid.
1104  *\li   'task' to be valid.
1105  */
1106
1107 void
1108 dns_zone_gettask(dns_zone_t *zone, isc_task_t **target);
1109 /*%<
1110  * Attach '*target' to the zone's task.
1111  *
1112  * Requires:
1113  *\li   'zone' to be valid initialised zone.
1114  *\li   'zone' to have a task.
1115  *\li   'target' to be != NULL && '*target' == NULL.
1116  */
1117
1118 void
1119 dns_zone_notify(dns_zone_t *zone);
1120 /*%<
1121  * Generate notify events for this zone.
1122  *
1123  * Requires:
1124  *\li   'zone' to be a valid zone.
1125  */
1126
1127 isc_result_t
1128 dns_zone_replacedb(dns_zone_t *zone, dns_db_t *db, isc_boolean_t dump);
1129 /*%<
1130  * Replace the database of "zone" with a new database "db".
1131  *
1132  * If "dump" is ISC_TRUE, then the new zone contents are dumped
1133  * into to the zone's master file for persistence.  When replacing
1134  * a zone database by one just loaded from a master file, set
1135  * "dump" to ISC_FALSE to avoid a redundant redump of the data just
1136  * loaded.  Otherwise, it should be set to ISC_TRUE.
1137  *
1138  * If the "diff-on-reload" option is enabled in the configuration file,
1139  * the differences between the old and the new database are added to the
1140  * journal file, and the master file dump is postponed.
1141  *
1142  * Requires:
1143  * \li  'zone' to be a valid zone.
1144  *
1145  * Returns:
1146  * \li  DNS_R_SUCCESS
1147  * \li  DNS_R_BADZONE   zone failed basic consistency checks:
1148  *                      * a single SOA must exist
1149  *                      * some NS records must exist.
1150  *      Others
1151  */
1152
1153 isc_uint32_t
1154 dns_zone_getidlein(dns_zone_t *zone);
1155 /*%<
1156  * Requires:
1157  * \li  'zone' to be a valid zone.
1158  *
1159  * Returns:
1160  * \li  number of seconds of idle time before we abort the transfer in.
1161  */
1162
1163 void
1164 dns_zone_setidlein(dns_zone_t *zone, isc_uint32_t idlein);
1165 /*%<
1166  * \li  Set the idle timeout for transfer the.
1167  * \li  Zero set the default value, 1 hour.
1168  *
1169  * Requires:
1170  * \li  'zone' to be a valid zone.
1171  */
1172
1173 isc_uint32_t
1174 dns_zone_getidleout(dns_zone_t *zone);
1175 /*%<
1176  *
1177  * Requires:
1178  * \li  'zone' to be a valid zone.
1179  *
1180  * Returns:
1181  * \li  number of seconds of idle time before we abort a transfer out.
1182  */
1183
1184 void
1185 dns_zone_setidleout(dns_zone_t *zone, isc_uint32_t idleout);
1186 /*%<
1187  * \li  Set the idle timeout for transfers out.
1188  * \li  Zero set the default value, 1 hour.
1189  *
1190  * Requires:
1191  * \li  'zone' to be a valid zone.
1192  */
1193
1194 void
1195 dns_zone_getssutable(dns_zone_t *zone, dns_ssutable_t **table);
1196 /*%<
1197  * Get the simple-secure-update policy table.
1198  *
1199  * Requires:
1200  * \li  'zone' to be a valid zone.
1201  */
1202
1203 void
1204 dns_zone_setssutable(dns_zone_t *zone, dns_ssutable_t *table);
1205 /*%<
1206  * Set / clear the simple-secure-update policy table.
1207  *
1208  * Requires:
1209  * \li  'zone' to be a valid zone.
1210  */
1211
1212 isc_mem_t *
1213 dns_zone_getmctx(dns_zone_t *zone);
1214 /*%<
1215  * Get the memory context of a zone.
1216  *
1217  * Requires:
1218  * \li  'zone' to be a valid zone.
1219  */
1220
1221 dns_zonemgr_t *
1222 dns_zone_getmgr(dns_zone_t *zone);
1223 /*%<
1224  *      If 'zone' is managed return the zone manager otherwise NULL.
1225  *
1226  * Requires:
1227  * \li  'zone' to be a valid zone.
1228  */
1229
1230 void
1231 dns_zone_setsigvalidityinterval(dns_zone_t *zone, isc_uint32_t interval);
1232 /*%<
1233  * Set the zone's RRSIG validity interval.  This is the length of time
1234  * for which DNSSEC signatures created as a result of dynamic updates
1235  * to secure zones will remain valid, in seconds.
1236  *
1237  * Requires:
1238  * \li  'zone' to be a valid zone.
1239  */
1240
1241 isc_uint32_t
1242 dns_zone_getsigvalidityinterval(dns_zone_t *zone);
1243 /*%<
1244  * Get the zone's RRSIG validity interval.
1245  *
1246  * Requires:
1247  * \li  'zone' to be a valid zone.
1248  */
1249
1250 void
1251 dns_zone_setsigresigninginterval(dns_zone_t *zone, isc_uint32_t interval);
1252 /*%<
1253  * Set the zone's RRSIG re-signing interval.  A dynamic zone's RRSIG's
1254  * will be re-signed 'interval' amount of time before they expire.
1255  *
1256  * Requires:
1257  * \li  'zone' to be a valid zone.
1258  */
1259
1260 isc_uint32_t
1261 dns_zone_getsigresigninginterval(dns_zone_t *zone);
1262 /*%<
1263  * Get the zone's RRSIG re-signing interval.
1264  *
1265  * Requires:
1266  * \li  'zone' to be a valid zone.
1267  */
1268
1269 void
1270 dns_zone_setnotifytype(dns_zone_t *zone, dns_notifytype_t notifytype);
1271 /*%<
1272  * Sets zone notify method to "notifytype"
1273  */
1274
1275 isc_result_t
1276 dns_zone_forwardupdate(dns_zone_t *zone, dns_message_t *msg,
1277                        dns_updatecallback_t callback, void *callback_arg);
1278 /*%<
1279  * Forward 'msg' to each master in turn until we get an answer or we
1280  * have exhausted the list of masters. 'callback' will be called with
1281  * ISC_R_SUCCESS if we get an answer and the returned message will be
1282  * passed as 'answer_message', otherwise a non ISC_R_SUCCESS result code
1283  * will be passed and answer_message will be NULL.  The callback function
1284  * is responsible for destroying 'answer_message'.
1285  *              (callback)(callback_arg, result, answer_message);
1286  *
1287  * Require:
1288  *\li   'zone' to be valid
1289  *\li   'msg' to be valid.
1290  *\li   'callback' to be non NULL.
1291  * Returns:
1292  *\li   #ISC_R_SUCCESS if the message has been forwarded,
1293  *\li   #ISC_R_NOMEMORY
1294  *\li   Others
1295  */
1296
1297 isc_result_t
1298 dns_zone_next(dns_zone_t *zone, dns_zone_t **next);
1299 /*%<
1300  * Find the next zone in the list of managed zones.
1301  *
1302  * Requires:
1303  *\li   'zone' to be valid
1304  *\li   The zone manager for the indicated zone MUST be locked
1305  *      by the caller.  This is not checked.
1306  *\li   'next' be non-NULL, and '*next' be NULL.
1307  *
1308  * Ensures:
1309  *\li   'next' points to a valid zone (result ISC_R_SUCCESS) or to NULL
1310  *      (result ISC_R_NOMORE).
1311  */
1312
1313
1314
1315 isc_result_t
1316 dns_zone_first(dns_zonemgr_t *zmgr, dns_zone_t **first);
1317 /*%<
1318  * Find the first zone in the list of managed zones.
1319  *
1320  * Requires:
1321  *\li   'zonemgr' to be valid
1322  *\li   The zone manager for the indicated zone MUST be locked
1323  *      by the caller.  This is not checked.
1324  *\li   'first' be non-NULL, and '*first' be NULL
1325  *
1326  * Ensures:
1327  *\li   'first' points to a valid zone (result ISC_R_SUCCESS) or to NULL
1328  *      (result ISC_R_NOMORE).
1329  */
1330
1331 isc_result_t
1332 dns_zone_setkeydirectory(dns_zone_t *zone, const char *directory);
1333 /*%<
1334  *      Sets the name of the directory where private keys used for
1335  *      online signing of dynamic zones are found.
1336  *
1337  * Require:
1338  *\li   'zone' to be a valid zone.
1339  *
1340  * Returns:
1341  *\li   #ISC_R_NOMEMORY
1342  *\li   #ISC_R_SUCCESS
1343  */
1344
1345 const char *
1346 dns_zone_getkeydirectory(dns_zone_t *zone);
1347 /*%<
1348  *      Gets the name of the directory where private keys used for
1349  *      online signing of dynamic zones are found.
1350  *
1351  * Requires:
1352  *\li   'zone' to be valid initialised zone.
1353  *
1354  * Returns:
1355  *      Pointer to null-terminated file name, or NULL.
1356  */
1357
1358
1359 isc_result_t
1360 dns_zonemgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr,
1361                    isc_timermgr_t *timermgr, isc_socketmgr_t *socketmgr,
1362                    dns_zonemgr_t **zmgrp);
1363 /*%<
1364  * Create a zone manager.
1365  *
1366  * Requires:
1367  *\li   'mctx' to be a valid memory context.
1368  *\li   'taskmgr' to be a valid task manager.
1369  *\li   'timermgr' to be a valid timer manager.
1370  *\li   'zmgrp' to point to a NULL pointer.
1371  */
1372
1373 isc_result_t
1374 dns_zonemgr_managezone(dns_zonemgr_t *zmgr, dns_zone_t *zone);
1375 /*%<
1376  *      Bring the zone under control of a zone manager.
1377  *
1378  * Require:
1379  *\li   'zmgr' to be a valid zone manager.
1380  *\li   'zone' to be a valid zone.
1381  */
1382
1383 isc_result_t
1384 dns_zonemgr_forcemaint(dns_zonemgr_t *zmgr);
1385 /*%<
1386  * Force zone maintenance of all zones managed by 'zmgr' at its
1387  * earliest convenience.
1388  */
1389
1390 void
1391 dns_zonemgr_resumexfrs(dns_zonemgr_t *zmgr);
1392 /*%<
1393  * Attempt to start any stalled zone transfers.
1394  */
1395
1396 void
1397 dns_zonemgr_shutdown(dns_zonemgr_t *zmgr);
1398 /*%<
1399  *      Shut down the zone manager.
1400  *
1401  * Requires:
1402  *\li   'zmgr' to be a valid zone manager.
1403  */
1404
1405 void
1406 dns_zonemgr_attach(dns_zonemgr_t *source, dns_zonemgr_t **target);
1407 /*%<
1408  *      Attach '*target' to 'source' incrementing its external
1409  *      reference count.
1410  *
1411  * Require:
1412  *\li   'zone' to be a valid zone.
1413  *\li   'target' to be non NULL and '*target' to be NULL.
1414  */
1415
1416 void
1417 dns_zonemgr_detach(dns_zonemgr_t **zmgrp);
1418 /*%<
1419  *       Detach from a zone manager.
1420  *
1421  * Requires:
1422  *\li   '*zmgrp' is a valid, non-NULL zone manager pointer.
1423  *
1424  * Ensures:
1425  *\li   '*zmgrp' is NULL.
1426  */
1427
1428 void
1429 dns_zonemgr_releasezone(dns_zonemgr_t *zmgr, dns_zone_t *zone);
1430 /*%<
1431  *      Release 'zone' from the managed by 'zmgr'.  'zmgr' is implicitly
1432  *      detached from 'zone'.
1433  *
1434  * Requires:
1435  *\li   'zmgr' to be a valid zone manager.
1436  *\li   'zone' to be a valid zone.
1437  *\li   'zmgr' == 'zone->zmgr'
1438  *
1439  * Ensures:
1440  *\li   'zone->zmgr' == NULL;
1441  */
1442
1443 void
1444 dns_zonemgr_settransfersin(dns_zonemgr_t *zmgr, isc_uint32_t value);
1445 /*%<
1446  *      Set the maximum number of simultaneous transfers in allowed by
1447  *      the zone manager.
1448  *
1449  * Requires:
1450  *\li   'zmgr' to be a valid zone manager.
1451  */
1452
1453 isc_uint32_t
1454 dns_zonemgr_getttransfersin(dns_zonemgr_t *zmgr);
1455 /*%<
1456  *      Return the maximum number of simultaneous transfers in allowed.
1457  *
1458  * Requires:
1459  *\li   'zmgr' to be a valid zone manager.
1460  */
1461
1462 void
1463 dns_zonemgr_settransfersperns(dns_zonemgr_t *zmgr, isc_uint32_t value);
1464 /*%<
1465  *      Set the number of zone transfers allowed per nameserver.
1466  *
1467  * Requires:
1468  *\li   'zmgr' to be a valid zone manager
1469  */
1470
1471 isc_uint32_t
1472 dns_zonemgr_getttransfersperns(dns_zonemgr_t *zmgr);
1473 /*%<
1474  *      Return the number of transfers allowed per nameserver.
1475  *
1476  * Requires:
1477  *\li   'zmgr' to be a valid zone manager.
1478  */
1479
1480 void
1481 dns_zonemgr_setiolimit(dns_zonemgr_t *zmgr, isc_uint32_t iolimit);
1482 /*%<
1483  *      Set the number of simultaneous file descriptors available for
1484  *      reading and writing masterfiles.
1485  *
1486  * Requires:
1487  *\li   'zmgr' to be a valid zone manager.
1488  *\li   'iolimit' to be positive.
1489  */
1490
1491 isc_uint32_t
1492 dns_zonemgr_getiolimit(dns_zonemgr_t *zmgr);
1493 /*%<
1494  *      Get the number of simultaneous file descriptors available for
1495  *      reading and writing masterfiles.
1496  *
1497  * Requires:
1498  *\li   'zmgr' to be a valid zone manager.
1499  */
1500
1501 void
1502 dns_zonemgr_setserialqueryrate(dns_zonemgr_t *zmgr, unsigned int value);
1503 /*%<
1504  *      Set the number of SOA queries sent per second.
1505  *
1506  * Requires:
1507  *\li   'zmgr' to be a valid zone manager
1508  */
1509
1510 unsigned int
1511 dns_zonemgr_getserialqueryrate(dns_zonemgr_t *zmgr);
1512 /*%<
1513  *      Return the number of SOA queries sent per second.
1514  *
1515  * Requires:
1516  *\li   'zmgr' to be a valid zone manager.
1517  */
1518
1519 unsigned int
1520 dns_zonemgr_getcount(dns_zonemgr_t *zmgr, int state);
1521 /*%<
1522  *      Returns the number of zones in the specified state.
1523  *
1524  * Requires:
1525  *\li   'zmgr' to be a valid zone manager.
1526  *\li   'state' to be a valid DNS_ZONESTATE_ constant.
1527  */
1528
1529 void
1530 dns_zonemgr_unreachableadd(dns_zonemgr_t *zmgr, isc_sockaddr_t *remote,
1531                            isc_sockaddr_t *local, isc_time_t *now);
1532 /*%<
1533  *      Add the pair of addresses to the unreachable cache.
1534  *
1535  * Requires:
1536  *\li   'zmgr' to be a valid zone manager.
1537  *\li   'remote' to be a valid sockaddr.
1538  *\li   'local' to be a valid sockaddr.
1539  */
1540
1541 void
1542 dns_zone_forcereload(dns_zone_t *zone);
1543 /*%<
1544  *      Force a reload of specified zone.
1545  *
1546  * Requires:
1547  *\li      'zone' to be a valid zone.
1548  */
1549
1550 isc_boolean_t
1551 dns_zone_isforced(dns_zone_t *zone);
1552 /*%<
1553  *      Check if the zone is waiting a forced reload.
1554  *
1555  * Requires:
1556  * \li     'zone' to be a valid zone.
1557  */
1558
1559 isc_result_t
1560 dns_zone_setstatistics(dns_zone_t *zone, isc_boolean_t on);
1561 /*%<
1562  * This function is obsoleted by dns_zone_setrequeststats().
1563  */
1564
1565 isc_uint64_t *
1566 dns_zone_getstatscounters(dns_zone_t *zone);
1567 /*%<
1568  * This function is obsoleted by dns_zone_getrequeststats().
1569  */
1570
1571 void
1572 dns_zone_setstats(dns_zone_t *zone, isc_stats_t *stats);
1573 /*%<
1574  * Set a general zone-maintenance statistics set 'stats' for 'zone'.  This
1575  * function is expected to be called only on zone creation (when necessary).
1576  * Once installed, it cannot be removed or replaced.  Also, there is no
1577  * interface to get the installed stats from the zone; the caller must keep the
1578  * stats to reference (e.g. dump) it later.
1579  *
1580  * Requires:
1581  * \li  'zone' to be a valid zone and does not have a statistics set already
1582  *      installed.
1583  *
1584  *\li   stats is a valid statistics supporting zone statistics counters
1585  *      (see dns/stats.h).
1586  */
1587
1588 void
1589 dns_zone_setrequeststats(dns_zone_t *zone, isc_stats_t *stats);
1590 /*%<
1591  * Set an additional statistics set to zone.  It is attached in the zone
1592  * but is not counted in the zone module; only the caller updates the counters.
1593  *
1594  * Requires:
1595  * \li  'zone' to be a valid zone.
1596  *
1597  *\li   stats is a valid statistics.
1598  */
1599
1600 isc_stats_t *
1601 dns_zone_getrequeststats(dns_zone_t *zone);
1602 /*%<
1603  * Get the additional statistics for zone, if one is installed.
1604  *
1605  * Requires:
1606  * \li  'zone' to be a valid zone.
1607  *
1608  * Returns:
1609  * \li  when available, a pointer to the statistics set installed in zone;
1610  *      otherwise NULL.
1611  */
1612
1613 void
1614 dns_zone_dialup(dns_zone_t *zone);
1615 /*%<
1616  * Perform dialup-time maintenance on 'zone'.
1617  */
1618
1619 void
1620 dns_zone_setdialup(dns_zone_t *zone, dns_dialuptype_t dialup);
1621 /*%<
1622  * Set the dialup type of 'zone' to 'dialup'.
1623  *
1624  * Requires:
1625  * \li  'zone' to be valid initialised zone.
1626  *\li   'dialup' to be a valid dialup type.
1627  */
1628
1629 void
1630 dns_zone_log(dns_zone_t *zone, int level, const char *msg, ...)
1631         ISC_FORMAT_PRINTF(3, 4);
1632 /*%<
1633  * Log the message 'msg...' at 'level', including text that identifies
1634  * the message as applying to 'zone'.
1635  */
1636
1637 void
1638 dns_zone_logc(dns_zone_t *zone, isc_logcategory_t *category, int level,
1639               const char *msg, ...) ISC_FORMAT_PRINTF(4, 5);
1640 /*%<
1641  * Log the message 'msg...' at 'level', including text that identifies
1642  * the message as applying to 'zone'.
1643  */
1644
1645 void
1646 dns_zone_name(dns_zone_t *zone, char *buf, size_t len);
1647 /*%<
1648  * Return the name of the zone with class and view.
1649  *
1650  * Requires:
1651  *\li   'zone' to be valid.
1652  *\li   'buf' to be non NULL.
1653  */
1654
1655 isc_result_t
1656 dns_zone_checknames(dns_zone_t *zone, dns_name_t *name, dns_rdata_t *rdata);
1657 /*%<
1658  * Check if this record meets the check-names policy.
1659  *
1660  * Requires:
1661  *      'zone' to be valid.
1662  *      'name' to be valid.
1663  *      'rdata' to be valid.
1664  *
1665  * Returns:
1666  *      DNS_R_SUCCESS           passed checks.
1667  *      DNS_R_BADOWNERNAME      failed ownername checks.
1668  *      DNS_R_BADNAME           failed rdata checks.
1669  */
1670
1671 void
1672 dns_zone_setacache(dns_zone_t *zone, dns_acache_t *acache);
1673 /*%<
1674  *      Associate the zone with an additional cache.
1675  *
1676  * Require:
1677  *      'zone' to be a valid zone.
1678  *      'acache' to be a non NULL pointer.
1679  *
1680  * Ensures:
1681  *      'zone' will have a reference to 'acache'
1682  */
1683
1684 void
1685 dns_zone_setcheckmx(dns_zone_t *zone, dns_checkmxfunc_t checkmx);
1686 /*%<
1687  *      Set the post load integrity callback function 'checkmx'.
1688  *      'checkmx' will be called if the MX is not within the zone.
1689  *
1690  * Require:
1691  *      'zone' to be a valid zone.
1692  */
1693
1694 void
1695 dns_zone_setchecksrv(dns_zone_t *zone, dns_checkmxfunc_t checksrv);
1696 /*%<
1697  *      Set the post load integrity callback function 'checksrv'.
1698  *      'checksrv' will be called if the SRV TARGET is not within the zone.
1699  *
1700  * Require:
1701  *      'zone' to be a valid zone.
1702  */
1703
1704 void
1705 dns_zone_setcheckns(dns_zone_t *zone, dns_checknsfunc_t checkns);
1706 /*%<
1707  *      Set the post load integrity callback function 'checkmx'.
1708  *      'checkmx' will be called if the MX is not within the zone.
1709  *
1710  * Require:
1711  *      'zone' to be a valid zone.
1712  */
1713
1714 void
1715 dns_zone_setnotifydelay(dns_zone_t *zone, isc_uint32_t delay);
1716 /*%<
1717  * Set the minimum delay between sets of notify messages.
1718  *
1719  * Requires:
1720  *      'zone' to be valid.
1721  */
1722
1723 isc_uint32_t
1724 dns_zone_getnotifydelay(dns_zone_t *zone);
1725 /*%<
1726  * Get the minimum delay between sets of notify messages.
1727  *
1728  * Requires:
1729  *      'zone' to be valid.
1730  */
1731
1732 void
1733 dns_zone_setisself(dns_zone_t *zone, dns_isselffunc_t isself, void *arg);
1734 /*%<
1735  * Set the isself callback function and argument.
1736  *
1737  * isc_boolean_t
1738  * isself(dns_view_t *myview, dns_tsigkey_t *mykey, isc_netaddr_t *srcaddr,
1739  *        isc_netaddr_t *destaddr, dns_rdataclass_t rdclass, void *arg);
1740  *
1741  * 'isself' returns ISC_TRUE if a non-recursive query from 'srcaddr' to
1742  * 'destaddr' with optional key 'mykey' for class 'rdclass' would be
1743  * delivered to 'myview'.
1744  */
1745
1746 void
1747 dns_zone_setnodes(dns_zone_t *zone, isc_uint32_t nodes);
1748 /*%<
1749  * Set the number of nodes that will be checked per quantum.
1750  */
1751
1752 void
1753 dns_zone_setsignatures(dns_zone_t *zone, isc_uint32_t signatures);
1754 /*%<
1755  * Set the number of signatures that will be generated per quantum.
1756  */
1757
1758 isc_result_t
1759 dns_zone_signwithkey(dns_zone_t *zone, dns_secalg_t algorithm,
1760                      isc_uint16_t keyid, isc_boolean_t delete);
1761 /*%<
1762  * Initiate/resume signing of the entire zone with the zone DNSKEY(s)
1763  * that match the given algorithm and keyid.
1764  */
1765
1766 isc_result_t
1767 dns_zone_addnsec3chain(dns_zone_t *zone, dns_rdata_nsec3param_t *nsec3param);
1768 /*%<
1769  * Incrementally add a NSEC3 chain that corresponds to 'nsec3param'.
1770  */
1771
1772 void
1773 dns_zone_setprivatetype(dns_zone_t *zone, dns_rdatatype_t type);
1774 dns_rdatatype_t
1775 dns_zone_getprivatetype(dns_zone_t *zone);
1776 /*
1777  * Get/Set the private record type.  It is expected that these interfaces
1778  * will not be permanent.
1779  */
1780
1781 void
1782 dns_zone_rekey(dns_zone_t *zone);
1783 /*%<
1784  * Update the zone's DNSKEY set from the key repository.
1785  */
1786
1787 isc_result_t
1788 dns_zone_nscheck(dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version,
1789                  unsigned int *errors);
1790 /*%
1791  * Check if the name servers for the zone are sane (have address, don't
1792  * refer to CNAMEs/DNAMEs.  The number of constiancy errors detected in
1793  * returned in '*errors'
1794  *
1795  * Requires:
1796  * \li  'zone' to be valid.
1797  * \li  'db' to be valid.
1798  * \li  'version' to be valid or NULL.
1799  * \li  'errors' to be non NULL.
1800  *
1801  * Returns:
1802  *      ISC_R_SUCCESS if there were no errors examining the zone contents.
1803  */
1804
1805
1806 ISC_LANG_ENDDECLS
1807
1808 #endif /* DNS_ZONE_H */