1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * SPDX-License-Identifier: MPL-2.0 5 * 6 * This Source Code Form is subject to the terms of the Mozilla Public 7 * License, v. 2.0. If a copy of the MPL was not distributed with this 8 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 9 * 10 * See the COPYRIGHT file distributed with this work for additional 11 * information regarding copyright ownership. 12 */ 13 14 #ifndef DNS_ZONE_H 15 #define DNS_ZONE_H 1 16 17 /*! \file dns/zone.h */ 18 19 /*** 20 *** Imports 21 ***/ 22 23 #include <inttypes.h> 24 #include <stdbool.h> 25 #include <stdio.h> 26 27 #include <isc/formatcheck.h> 28 #include <isc/lang.h> 29 #include <isc/rwlock.h> 30 31 #include <dns/catz.h> 32 #include <dns/master.h> 33 #include <dns/masterdump.h> 34 #include <dns/rdatastruct.h> 35 #include <dns/rpz.h> 36 #include <dns/types.h> 37 #include <dns/zt.h> 38 39 typedef enum { 40 dns_zone_none, 41 dns_zone_primary, 42 dns_zone_secondary, 43 dns_zone_mirror, 44 dns_zone_stub, 45 dns_zone_staticstub, 46 dns_zone_key, 47 dns_zone_dlz, 48 dns_zone_redirect 49 } dns_zonetype_t; 50 51 #ifndef dns_zone_master 52 #define dns_zone_master dns_zone_primary 53 #endif /* dns_zone_master */ 54 55 #ifndef dns_zone_slave 56 #define dns_zone_slave dns_zone_secondary 57 #endif /* dns_zone_slave */ 58 59 typedef enum { 60 dns_zonestat_none = 0, 61 dns_zonestat_terse, 62 dns_zonestat_full 63 } dns_zonestat_level_t; 64 65 typedef enum { 66 DNS_ZONEOPT_MANYERRORS = 1 << 0, /*%< return many errors on load */ 67 DNS_ZONEOPT_IXFRFROMDIFFS = 1 << 1, /*%< calculate differences */ 68 DNS_ZONEOPT_NOMERGE = 1 << 2, /*%< don't merge journal */ 69 DNS_ZONEOPT_CHECKNS = 1 << 3, /*%< check if NS's are addresses */ 70 DNS_ZONEOPT_FATALNS = 1 << 4, /*%< DNS_ZONEOPT_CHECKNS is fatal */ 71 DNS_ZONEOPT_MULTIMASTER = 1 << 5, /*%< this zone has multiple 72 primaries */ 73 DNS_ZONEOPT_USEALTXFRSRC = 1 << 6, /*%< use alternate transfer sources 74 */ 75 DNS_ZONEOPT_CHECKNAMES = 1 << 7, /*%< check-names */ 76 DNS_ZONEOPT_CHECKNAMESFAIL = 1 << 8, /*%< fatal check-name failures */ 77 DNS_ZONEOPT_CHECKWILDCARD = 1 << 9, /*%< check for internal wildcards */ 78 DNS_ZONEOPT_CHECKMX = 1 << 10, /*%< check-mx */ 79 DNS_ZONEOPT_CHECKMXFAIL = 1 << 11, /*%< fatal check-mx failures */ 80 DNS_ZONEOPT_CHECKINTEGRITY = 1 << 12, /*%< perform integrity checks */ 81 DNS_ZONEOPT_CHECKSIBLING = 1 << 13, /*%< perform sibling glue checks */ 82 DNS_ZONEOPT_NOCHECKNS = 1 << 14, /*%< disable IN NS address checks */ 83 DNS_ZONEOPT_WARNMXCNAME = 1 << 15, /*%< warn on MX CNAME check */ 84 DNS_ZONEOPT_IGNOREMXCNAME = 1 << 16, /*%< ignore MX CNAME check */ 85 DNS_ZONEOPT_WARNSRVCNAME = 1 << 17, /*%< warn on SRV CNAME check */ 86 DNS_ZONEOPT_IGNORESRVCNAME = 1 << 18, /*%< ignore SRV CNAME check */ 87 DNS_ZONEOPT_UPDATECHECKKSK = 1 << 19, /*%< check dnskey KSK flag */ 88 DNS_ZONEOPT_TRYTCPREFRESH = 1 << 20, /*%< try tcp refresh on udp failure 89 */ 90 DNS_ZONEOPT_NOTIFYTOSOA = 1 << 21, /*%< Notify the SOA MNAME */ 91 DNS_ZONEOPT_NSEC3TESTZONE = 1 << 22, /*%< nsec3-test-zone */ 92 DNS_ZONEOPT_SECURETOINSECURE = 1 << 23, /*%< dnssec-secure-to-insecure 93 */ 94 DNS_ZONEOPT_DNSKEYKSKONLY = 1 << 24, /*%< dnssec-dnskey-kskonly */ 95 DNS_ZONEOPT_CHECKDUPRR = 1 << 25, /*%< check-dup-records */ 96 DNS_ZONEOPT_CHECKDUPRRFAIL = 1 << 26, /*%< fatal check-dup-records 97 * failures */ 98 DNS_ZONEOPT_CHECKSPF = 1 << 27, /*%< check SPF records */ 99 DNS_ZONEOPT_CHECKTTL = 1 << 28, /*%< check max-zone-ttl */ 100 DNS_ZONEOPT_AUTOEMPTY = 1 << 29, /*%< automatic empty zone */ 101 DNS_ZONEOPT___MAX = UINT64_MAX, /* trick to make the ENUM 64-bit wide */ 102 } dns_zoneopt_t; 103 104 /* 105 * Zone key maintenance options 106 */ 107 typedef enum { 108 DNS_ZONEKEY_ALLOW = 0x00000001U, /*%< fetch keys on command */ 109 DNS_ZONEKEY_MAINTAIN = 0x00000002U, /*%< publish/sign on schedule */ 110 DNS_ZONEKEY_CREATE = 0x00000004U, /*%< make keys when needed */ 111 DNS_ZONEKEY_FULLSIGN = 0x00000008U, /*%< roll to new keys immediately */ 112 DNS_ZONEKEY_NORESIGN = 0x00000010U, /*%< no automatic resigning */ 113 DNS_ZONEKEY___MAX = UINT64_MAX, /* trick to make the ENUM 64-bit wide */ 114 } dns_zonekey_t; 115 116 #ifndef DNS_ZONE_MINREFRESH 117 #define DNS_ZONE_MINREFRESH 300 /*%< 5 minutes */ 118 #endif /* ifndef DNS_ZONE_MINREFRESH */ 119 #ifndef DNS_ZONE_MAXREFRESH 120 #define DNS_ZONE_MAXREFRESH 2419200 /*%< 4 weeks */ 121 #endif /* ifndef DNS_ZONE_MAXREFRESH */ 122 #ifndef DNS_ZONE_DEFAULTREFRESH 123 #define DNS_ZONE_DEFAULTREFRESH 3600 /*%< 1 hour */ 124 #endif /* ifndef DNS_ZONE_DEFAULTREFRESH */ 125 #ifndef DNS_ZONE_MINRETRY 126 #define DNS_ZONE_MINRETRY 300 /*%< 5 minutes */ 127 #endif /* ifndef DNS_ZONE_MINRETRY */ 128 #ifndef DNS_ZONE_MAXRETRY 129 #define DNS_ZONE_MAXRETRY 1209600 /*%< 2 weeks */ 130 #endif /* ifndef DNS_ZONE_MAXRETRY */ 131 #ifndef DNS_ZONE_DEFAULTRETRY 132 #define DNS_ZONE_DEFAULTRETRY \ 133 60 /*%< 1 minute, subject to \ 134 * exponential backoff */ 135 #endif /* ifndef DNS_ZONE_DEFAULTRETRY */ 136 137 #define DNS_ZONESTATE_XFERRUNNING 1 138 #define DNS_ZONESTATE_XFERDEFERRED 2 139 #define DNS_ZONESTATE_SOAQUERY 3 140 #define DNS_ZONESTATE_ANY 4 141 #define DNS_ZONESTATE_AUTOMATIC 5 142 143 ISC_LANG_BEGINDECLS 144 145 /*** 146 *** Functions 147 ***/ 148 149 isc_result_t 150 dns_zone_create(dns_zone_t **zonep, isc_mem_t *mctx); 151 /*%< 152 * Creates a new empty zone and attach '*zonep' to it. 153 * 154 * Requires: 155 *\li 'zonep' to point to a NULL pointer. 156 *\li 'mctx' to be a valid memory context. 157 * 158 * Ensures: 159 *\li '*zonep' refers to a valid zone. 160 * 161 * Returns: 162 *\li #ISC_R_SUCCESS 163 *\li #ISC_R_NOMEMORY 164 *\li #ISC_R_UNEXPECTED 165 */ 166 167 void 168 dns_zone_setclass(dns_zone_t *zone, dns_rdataclass_t rdclass); 169 /*%< 170 * Sets the class of a zone. This operation can only be performed 171 * once on a zone. 172 * 173 * Require: 174 *\li 'zone' to be a valid zone. 175 *\li dns_zone_setclass() not to have been called since the zone was 176 * created. 177 *\li 'rdclass' != dns_rdataclass_none. 178 */ 179 180 dns_rdataclass_t 181 dns_zone_getclass(dns_zone_t *zone); 182 /*%< 183 * Returns the current zone class. 184 * 185 * Requires: 186 *\li 'zone' to be a valid zone. 187 */ 188 189 isc_result_t 190 dns_zone_getserial(dns_zone_t *zone, uint32_t *serialp); 191 /*%< 192 * Returns the current serial number of the zone. On success, the SOA 193 * serial of the zone will be copied into '*serialp'. 194 * 195 * Requires: 196 *\li 'zone' to be a valid zone. 197 *\li 'serialp' to be non NULL 198 * 199 * Returns: 200 *\li #ISC_R_SUCCESS 201 *\li #DNS_R_NOTLOADED zone DB is not loaded 202 */ 203 204 void 205 dns_zone_settype(dns_zone_t *zone, dns_zonetype_t type); 206 /*%< 207 * Sets the zone type. This operation can only be performed once on 208 * a zone. 209 * 210 * Requires: 211 *\li 'zone' to be a valid zone. 212 *\li dns_zone_settype() not to have been called since the zone was 213 * created. 214 *\li 'type' != dns_zone_none 215 */ 216 217 void 218 dns_zone_setview(dns_zone_t *zone, dns_view_t *view); 219 /*%< 220 * Associate the zone with a view. 221 * 222 * Require: 223 *\li 'zone' to be a valid zone. 224 */ 225 226 dns_view_t * 227 dns_zone_getview(dns_zone_t *zone); 228 /*%< 229 * Returns the zone's associated view. 230 * 231 * Requires: 232 *\li 'zone' to be a valid zone. 233 */ 234 235 void 236 dns_zone_setviewcommit(dns_zone_t *zone); 237 /*%< 238 * Commit the previous view saved internally via dns_zone_setview(). 239 * 240 * Require: 241 *\li 'zone' to be a valid zone. 242 */ 243 244 void 245 dns_zone_setviewrevert(dns_zone_t *zone); 246 /*%< 247 * Revert the most recent dns_zone_setview() on this zone, 248 * restoring the previous view. 249 * 250 * Require: 251 *\li 'zone' to be a valid zone. 252 */ 253 254 isc_result_t 255 dns_zone_setorigin(dns_zone_t *zone, const dns_name_t *origin); 256 /*%< 257 * Sets the zones origin to 'origin'. 258 * 259 * Require: 260 *\li 'zone' to be a valid zone. 261 *\li 'origin' to be non NULL. 262 * 263 * Returns: 264 *\li #ISC_R_SUCCESS 265 *\li #ISC_R_NOMEMORY 266 */ 267 268 dns_name_t * 269 dns_zone_getorigin(dns_zone_t *zone); 270 /*%< 271 * Returns the value of the origin. 272 * 273 * Require: 274 *\li 'zone' to be a valid zone. 275 */ 276 277 isc_result_t 278 dns_zone_setfile(dns_zone_t *zone, const char *file, dns_masterformat_t format, 279 const dns_master_style_t *style); 280 /*%< 281 * Sets the name of the master file in the format of 'format' from which 282 * the zone loads its database to 'file'. 283 * 284 * For zones that have no associated master file, 'file' will be NULL. 285 * 286 * For zones with persistent databases, the file name 287 * setting is ignored. 288 * 289 * Require: 290 *\li 'zone' to be a valid zone. 291 * 292 * Returns: 293 *\li #ISC_R_NOMEMORY 294 *\li #ISC_R_SUCCESS 295 */ 296 297 const char * 298 dns_zone_getfile(dns_zone_t *zone); 299 /*%< 300 * Gets the name of the zone's master file, if any. 301 * 302 * Requires: 303 *\li 'zone' to be valid initialised zone. 304 * 305 * Returns: 306 *\li Pointer to null-terminated file name, or NULL. 307 */ 308 309 void 310 dns_zone_setmaxrecords(dns_zone_t *zone, uint32_t records); 311 /*%< 312 * Sets the maximum number of records permitted in a zone. 313 * 0 implies unlimited. 314 * 315 * Requires: 316 *\li 'zone' to be valid initialised zone. 317 * 318 * Returns: 319 *\li void 320 */ 321 322 uint32_t 323 dns_zone_getmaxrecords(dns_zone_t *zone); 324 /*%< 325 * Gets the maximum number of records permitted in a zone. 326 * 0 implies unlimited. 327 * 328 * Requires: 329 *\li 'zone' to be valid initialised zone. 330 * 331 * Returns: 332 *\li uint32_t maxrecords. 333 */ 334 335 void 336 dns_zone_setmaxttl(dns_zone_t *zone, uint32_t maxttl); 337 /*%< 338 * Sets the max ttl of the zone. 339 * 340 * Requires: 341 *\li 'zone' to be valid initialised zone. 342 * 343 * Returns: 344 *\li void 345 */ 346 347 dns_ttl_t 348 dns_zone_getmaxttl(dns_zone_t *zone); 349 /*%< 350 * Gets the max ttl of the zone. 351 * 352 * Requires: 353 *\li 'zone' to be valid initialised zone. 354 * 355 * Returns: 356 *\li dns_ttl_t maxttl. 357 */ 358 359 void 360 dns_zone_lock_keyfiles(dns_zone_t *zone); 361 /*%< 362 * Lock associated keyfiles for this zone. 363 * 364 * Require: 365 *\li 'zone' to be a valid zone. 366 */ 367 368 void 369 dns_zone_unlock_keyfiles(dns_zone_t *zone); 370 /*%< 371 * Unlock associated keyfiles for this zone. 372 * 373 * Require: 374 *\li 'zone' to be a valid zone. 375 */ 376 377 isc_result_t 378 dns_zone_load(dns_zone_t *zone, bool newonly); 379 380 isc_result_t 381 dns_zone_loadandthaw(dns_zone_t *zone); 382 383 /*%< 384 * Cause the database to be loaded from its backing store. 385 * Confirm that the minimum requirements for the zone type are 386 * met, otherwise DNS_R_BADZONE is returned. 387 * 388 * If newonly is set dns_zone_load() only loads new zones. 389 * dns_zone_loadandthaw() is similar to dns_zone_load() but will 390 * also re-enable DNS UPDATEs when the load completes. 391 * 392 * Require: 393 *\li 'zone' to be a valid zone. 394 * 395 * Returns: 396 *\li #ISC_R_UNEXPECTED 397 *\li #ISC_R_SUCCESS 398 *\li DNS_R_CONTINUE Incremental load has been queued. 399 *\li DNS_R_UPTODATE The zone has already been loaded based on 400 * file system timestamps. 401 *\li DNS_R_BADZONE 402 *\li Any result value from dns_db_load(). 403 */ 404 405 isc_result_t 406 dns_zone_asyncload(dns_zone_t *zone, bool newonly, dns_zt_zoneloaded_t done, 407 void *arg); 408 /*%< 409 * Cause the database to be loaded from its backing store asynchronously. 410 * Other zone maintenance functions are suspended until this is complete. 411 * When finished, 'done' is called to inform the caller, with 'arg' as 412 * its first argument and 'zone' as its second. (Normally, 'arg' is 413 * expected to point to the zone table but is left undefined for testing 414 * purposes.) 415 * 416 * Require: 417 *\li 'zone' to be a valid zone. 418 * 419 * Returns: 420 *\li #ISC_R_ALREADYRUNNING 421 *\li #ISC_R_SUCCESS 422 *\li #ISC_R_FAILURE 423 *\li #ISC_R_NOMEMORY 424 */ 425 426 bool 427 dns__zone_loadpending(dns_zone_t *zone); 428 /*%< 429 * Indicates whether the zone is waiting to be loaded asynchronously. 430 * (Not currently intended for use outside of this module and associated 431 * tests.) 432 */ 433 434 void 435 dns_zone_attach(dns_zone_t *source, dns_zone_t **target); 436 /*%< 437 * Attach '*target' to 'source' incrementing its external 438 * reference count. 439 * 440 * Require: 441 *\li 'zone' to be a valid zone. 442 *\li 'target' to be non NULL and '*target' to be NULL. 443 */ 444 445 void 446 dns_zone_detach(dns_zone_t **zonep); 447 /*%< 448 * Detach from a zone decrementing its external reference count. 449 * If this was the last external reference to the zone it will be 450 * shut down and eventually freed. 451 * 452 * Require: 453 *\li 'zonep' to point to a valid zone. 454 */ 455 456 void 457 dns_zone_iattach(dns_zone_t *source, dns_zone_t **target); 458 /*%< 459 * Attach '*target' to 'source' incrementing its internal 460 * reference count. This is intended for use by operations 461 * such as zone transfers that need to prevent the zone 462 * object from being freed but not from shutting down. 463 * 464 * Require: 465 *\li The caller is running in the context of the zone's task. 466 *\li 'zone' to be a valid zone. 467 *\li 'target' to be non NULL and '*target' to be NULL. 468 */ 469 470 void 471 dns_zone_idetach(dns_zone_t **zonep); 472 /*%< 473 * Detach from a zone decrementing its internal reference count. 474 * If there are no more internal or external references to the 475 * zone, it will be freed. 476 * 477 * Require: 478 *\li The caller is running in the context of the zone's task. 479 *\li 'zonep' to point to a valid zone. 480 */ 481 482 isc_result_t 483 dns_zone_getdb(dns_zone_t *zone, dns_db_t **dbp); 484 /*%< 485 * Attach '*dbp' to the database to if it exists otherwise 486 * return DNS_R_NOTLOADED. 487 * 488 * Require: 489 *\li 'zone' to be a valid zone. 490 *\li 'dbp' to be != NULL && '*dbp' == NULL. 491 * 492 * Returns: 493 *\li #ISC_R_SUCCESS 494 *\li DNS_R_NOTLOADED 495 */ 496 497 void 498 dns_zone_setdb(dns_zone_t *zone, dns_db_t *db); 499 /*%< 500 * Sets the zone database to 'db'. 501 * 502 * This function is expected to be used to configure a zone with a 503 * database which is not loaded from a file or zone transfer. 504 * It can be used for a general purpose zone, but right now its use 505 * is limited to static-stub zones to avoid possible undiscovered 506 * problems in the general cases. 507 * 508 * Require: 509 *\li 'zone' to be a valid zone of static-stub. 510 *\li zone doesn't have a database. 511 */ 512 513 void 514 dns_zone_setdbtype(dns_zone_t *zone, unsigned int dbargc, 515 const char *const *dbargv); 516 /*%< 517 * Sets the database type to dbargv[0] and database arguments 518 * to subsequent dbargv elements. 519 * 'db_type' is not checked to see if it is a valid database type. 520 * 521 * Require: 522 *\li 'zone' to be a valid zone. 523 *\li 'database' to be non NULL. 524 *\li 'dbargc' to be >= 1 525 *\li 'dbargv' to point to dbargc NULL-terminated strings 526 */ 527 528 isc_result_t 529 dns_zone_getdbtype(dns_zone_t *zone, char ***argv, isc_mem_t *mctx); 530 /*%< 531 * Returns the current dbtype. isc_mem_free() should be used 532 * to free 'argv' after use. 533 * 534 * Require: 535 *\li 'zone' to be a valid zone. 536 *\li 'argv' to be non NULL and *argv to be NULL. 537 *\li 'mctx' to be valid. 538 * 539 * Returns: 540 *\li #ISC_R_NOMEMORY 541 *\li #ISC_R_SUCCESS 542 */ 543 544 void 545 dns_zone_markdirty(dns_zone_t *zone); 546 /*%< 547 * Mark a zone as 'dirty'. 548 * 549 * Require: 550 *\li 'zone' to be a valid zone. 551 */ 552 553 void 554 dns_zone_expire(dns_zone_t *zone); 555 /*%< 556 * Mark the zone as expired. If the zone requires dumping cause it to 557 * be initiated. Set the refresh and retry intervals to there default 558 * values and unload the zone. 559 * 560 * Require 561 *\li 'zone' to be a valid zone. 562 */ 563 564 void 565 dns_zone_refresh(dns_zone_t *zone); 566 /*%< 567 * Initiate zone up to date checks. The zone must already be being 568 * managed. 569 * 570 * Require 571 *\li 'zone' to be a valid zone. 572 */ 573 574 isc_result_t 575 dns_zone_flush(dns_zone_t *zone); 576 /*%< 577 * Write the zone to database if there are uncommitted changes. 578 * 579 * Require: 580 *\li 'zone' to be a valid zone. 581 */ 582 583 isc_result_t 584 dns_zone_dump(dns_zone_t *zone); 585 /*%< 586 * Write the zone to database. 587 * 588 * Require: 589 *\li 'zone' to be a valid zone. 590 */ 591 592 isc_result_t 593 dns_zone_dumptostream(dns_zone_t *zone, FILE *fd, dns_masterformat_t format, 594 const dns_master_style_t *style, 595 const uint32_t rawversion); 596 /*%< 597 * Write the zone to stream 'fd' in the specified 'format'. 598 * If the 'format' is dns_masterformat_text (RFC1035), 'style' also 599 * specifies the file style (e.g., &dns_master_style_default). 600 * 601 * dns_zone_dumptostream() is a backward-compatible form of 602 * dns_zone_dumptostream2(), which always uses the dns_masterformat_text 603 * format and the dns_master_style_default style. 604 * 605 * dns_zone_dumptostream2() is a backward-compatible form of 606 * dns_zone_dumptostream3(), which always uses the current 607 * default raw file format version. 608 * 609 * Note that dns_zone_dumptostream3() is the most flexible form. It 610 * can also provide the functionality of dns_zone_fulldumptostream(). 611 * 612 * Require: 613 *\li 'zone' to be a valid zone. 614 *\li 'fd' to be a stream open for writing. 615 */ 616 617 void 618 dns_zone_maintenance(dns_zone_t *zone); 619 /*%< 620 * Perform regular maintenance on the zone. This is called as a 621 * result of a zone being managed. 622 * 623 * Require 624 *\li 'zone' to be a valid zone. 625 */ 626 627 isc_result_t 628 dns_zone_setprimaries(dns_zone_t *zone, const isc_sockaddr_t *primaries, 629 uint32_t count); 630 isc_result_t 631 dns_zone_setprimarieswithkeys(dns_zone_t *zone, const isc_sockaddr_t *primaries, 632 dns_name_t **keynames, uint32_t count); 633 /*%< 634 * Set the list of master servers for the zone. 635 * 636 * Require: 637 *\li 'zone' to be a valid zone. 638 *\li 'primaries' array of isc_sockaddr_t with port set or NULL. 639 *\li 'count' the number of primaries. 640 *\li 'keynames' array of dns_name_t's for tsig keys or NULL. 641 * 642 *\li If 'primaries' is NULL then 'count' must be zero. 643 * 644 * Returns: 645 *\li #ISC_R_SUCCESS 646 *\li #ISC_R_NOMEMORY 647 *\li Any result dns_name_dup() can return, if keynames!=NULL 648 */ 649 650 isc_result_t 651 dns_zone_setparentals(dns_zone_t *zone, const isc_sockaddr_t *parentals, 652 dns_name_t **keynames, uint32_t count); 653 /*%< 654 * Set the list of parental agents for the zone. 655 * 656 * Require: 657 *\li 'zone' to be a valid zone. 658 *\li 'parentals' array of isc_sockaddr_t with port set or NULL. 659 *\li 'count' the number of primaries. 660 *\li 'keynames' array of dns_name_t's for tsig keys or NULL. 661 * 662 *\li If 'parentals' is NULL then 'count' must be zero. 663 * 664 * Returns: 665 *\li #ISC_R_SUCCESS 666 *\li #ISC_R_NOMEMORY 667 *\li Any result dns_name_dup() can return, if keynames!=NULL 668 */ 669 670 isc_result_t 671 dns_zone_setalsonotify(dns_zone_t *zone, const isc_sockaddr_t *notify, 672 uint32_t count); 673 isc_result_t 674 dns_zone_setalsonotifywithkeys(dns_zone_t *zone, const isc_sockaddr_t *notify, 675 dns_name_t **keynames, uint32_t count); 676 isc_result_t 677 dns_zone_setalsonotifydscpkeys(dns_zone_t *zone, const isc_sockaddr_t *notify, 678 const isc_dscp_t *dscps, dns_name_t **keynames, 679 uint32_t count); 680 /*%< 681 * Set the list of additional servers to be notified when 682 * a zone changes. To clear the list use 'count = 0'. 683 * 684 * dns_zone_alsonotifywithkeys() allows each notify address to 685 * be associated with a TSIG key. 686 * 687 * Require: 688 *\li 'zone' to be a valid zone. 689 *\li 'notify' to be non-NULL if count != 0. 690 *\li 'count' to be the number of notifiees. 691 * 692 * Returns: 693 *\li #ISC_R_SUCCESS 694 *\li #ISC_R_NOMEMORY 695 */ 696 697 void 698 dns_zone_unload(dns_zone_t *zone); 699 /*%< 700 * detach the database from the zone structure. 701 * 702 * Require: 703 *\li 'zone' to be a valid zone. 704 */ 705 706 dns_kasp_t * 707 dns_zone_getkasp(dns_zone_t *zone); 708 /*%< 709 * Returns the current kasp. 710 * 711 * Require: 712 *\li 'zone' to be a valid zone. 713 */ 714 715 void 716 dns_zone_setkasp(dns_zone_t *zone, dns_kasp_t *kasp); 717 /*%< 718 * Set kasp for zone. If a kasp is already set, it will be detached. 719 * 720 * Requires: 721 *\li 'zone' to be a valid zone. 722 */ 723 724 void 725 dns_zone_setoption(dns_zone_t *zone, dns_zoneopt_t option, bool value); 726 /*%< 727 * Set the given options on ('value' == true) or off 728 * ('value' == #false). 729 * 730 * Require: 731 *\li 'zone' to be a valid zone. 732 */ 733 734 dns_zoneopt_t 735 dns_zone_getoptions(dns_zone_t *zone); 736 /*%< 737 * Returns the current zone options. 738 * 739 * Require: 740 *\li 'zone' to be a valid zone. 741 */ 742 743 void 744 dns_zone_setkeyopt(dns_zone_t *zone, unsigned int option, bool value); 745 /*%< 746 * Set key options on ('value' == true) or off ('value' == 747 * #false). 748 * 749 * Require: 750 *\li 'zone' to be a valid zone. 751 */ 752 753 unsigned int 754 dns_zone_getkeyopts(dns_zone_t *zone); 755 /*%< 756 * Returns the current zone key options. 757 * 758 * Require: 759 *\li 'zone' to be a valid zone. 760 */ 761 762 void 763 dns_zone_setminrefreshtime(dns_zone_t *zone, uint32_t val); 764 /*%< 765 * Set the minimum refresh time. 766 * 767 * Requires: 768 *\li 'zone' is valid. 769 *\li val > 0. 770 */ 771 772 void 773 dns_zone_setmaxrefreshtime(dns_zone_t *zone, uint32_t val); 774 /*%< 775 * Set the maximum refresh time. 776 * 777 * Requires: 778 *\li 'zone' is valid. 779 *\li val > 0. 780 */ 781 782 void 783 dns_zone_setminretrytime(dns_zone_t *zone, uint32_t val); 784 /*%< 785 * Set the minimum retry time. 786 * 787 * Requires: 788 *\li 'zone' is valid. 789 *\li val > 0. 790 */ 791 792 void 793 dns_zone_setmaxretrytime(dns_zone_t *zone, uint32_t val); 794 /*%< 795 * Set the maximum retry time. 796 * 797 * Requires: 798 *\li 'zone' is valid. 799 * val > 0. 800 */ 801 802 isc_result_t 803 dns_zone_setxfrsource4(dns_zone_t *zone, const isc_sockaddr_t *xfrsource); 804 isc_result_t 805 dns_zone_setaltxfrsource4(dns_zone_t *zone, const isc_sockaddr_t *xfrsource); 806 /*%< 807 * Set the source address to be used in IPv4 zone transfers. 808 * 809 * Require: 810 *\li 'zone' to be a valid zone. 811 *\li 'xfrsource' to contain the address. 812 * 813 * Returns: 814 *\li #ISC_R_SUCCESS 815 */ 816 817 isc_sockaddr_t * 818 dns_zone_getxfrsource4(dns_zone_t *zone); 819 isc_sockaddr_t * 820 dns_zone_getaltxfrsource4(dns_zone_t *zone); 821 /*%< 822 * Returns the source address set by a previous dns_zone_setxfrsource4 823 * call, or the default of inaddr_any, port 0. 824 * 825 * Require: 826 *\li 'zone' to be a valid zone. 827 */ 828 829 isc_result_t 830 dns_zone_setxfrsource4dscp(dns_zone_t *zone, isc_dscp_t dscp); 831 isc_result_t 832 dns_zone_setaltxfrsource4dscp(dns_zone_t *zone, isc_dscp_t dscp); 833 /*%< 834 * Set the DSCP value associated with the transfer/alt-transfer source. 835 * 836 * Require: 837 *\li 'zone' to be a valid zone. 838 * 839 * Returns: 840 *\li #ISC_R_SUCCESS 841 */ 842 843 isc_dscp_t 844 dns_zone_getxfrsource4dscp(dns_zone_t *zone); 845 isc_dscp_t 846 dns_zone_getaltxfrsource4dscp(dns_zone_t *zone); 847 /*%/ 848 * Get the DSCP value associated with the transfer/alt-transfer source. 849 * 850 * Require: 851 *\li 'zone' to be a valid zone. 852 */ 853 854 isc_result_t 855 dns_zone_setxfrsource6(dns_zone_t *zone, const isc_sockaddr_t *xfrsource); 856 isc_result_t 857 dns_zone_setaltxfrsource6(dns_zone_t *zone, const isc_sockaddr_t *xfrsource); 858 /*%< 859 * Set the source address to be used in IPv6 zone transfers. 860 * 861 * Require: 862 *\li 'zone' to be a valid zone. 863 *\li 'xfrsource' to contain the address. 864 * 865 * Returns: 866 *\li #ISC_R_SUCCESS 867 */ 868 869 isc_sockaddr_t * 870 dns_zone_getxfrsource6(dns_zone_t *zone); 871 isc_sockaddr_t * 872 dns_zone_getaltxfrsource6(dns_zone_t *zone); 873 /*%< 874 * Returns the source address set by a previous dns_zone_setxfrsource6 875 * call, or the default of in6addr_any, port 0. 876 * 877 * Require: 878 *\li 'zone' to be a valid zone. 879 */ 880 881 isc_dscp_t 882 dns_zone_getxfrsource6dscp(dns_zone_t *zone); 883 isc_dscp_t 884 dns_zone_getaltxfrsource6dscp(dns_zone_t *zone); 885 /*%/ 886 * Get the DSCP value associated with the transfer/alt-transfer source. 887 * 888 * Require: 889 *\li 'zone' to be a valid zone. 890 */ 891 892 isc_result_t 893 dns_zone_setxfrsource6dscp(dns_zone_t *zone, isc_dscp_t dscp); 894 isc_result_t 895 dns_zone_setaltxfrsource6dscp(dns_zone_t *zone, isc_dscp_t dscp); 896 /*%< 897 * Set the DSCP value associated with the transfer/alt-transfer source. 898 * 899 * Require: 900 *\li 'zone' to be a valid zone. 901 * 902 * Returns: 903 *\li #ISC_R_SUCCESS 904 */ 905 906 isc_result_t 907 dns_zone_setparentalsrc4(dns_zone_t *zone, const isc_sockaddr_t *parentalsrc); 908 /*%< 909 * Set the source address to be used with IPv4 parental DS queries. 910 * 911 * Require: 912 *\li 'zone' to be a valid zone. 913 *\li 'parentalsrc' to contain the address. 914 * 915 * Returns: 916 *\li #ISC_R_SUCCESS 917 */ 918 919 isc_sockaddr_t * 920 dns_zone_getparentalsrc4(dns_zone_t *zone); 921 /*%< 922 * Returns the source address set by a previous dns_zone_setparentalsrc4 923 * call, or the default of inaddr_any, port 0. 924 * 925 * Require: 926 *\li 'zone' to be a valid zone. 927 */ 928 929 isc_dscp_t 930 dns_zone_getparentalsrc4dscp(dns_zone_t *zone); 931 /*%/ 932 * Get the DSCP value associated with the IPv4 parental source. 933 * 934 * Require: 935 *\li 'zone' to be a valid zone. 936 */ 937 938 isc_result_t 939 dns_zone_setparentalsrc4dscp(dns_zone_t *zone, isc_dscp_t dscp); 940 /*%< 941 * Set the DSCP value associated with the IPv4 parental source. 942 * 943 * Require: 944 *\li 'zone' to be a valid zone. 945 * 946 * Returns: 947 *\li #ISC_R_SUCCESS 948 */ 949 950 isc_result_t 951 dns_zone_setparentalsrc6(dns_zone_t *zone, const isc_sockaddr_t *parentalsrc); 952 /*%< 953 * Set the source address to be used with IPv6 parental DS queries. 954 * 955 * Require: 956 *\li 'zone' to be a valid zone. 957 *\li 'parentalsrc' to contain the address. 958 * 959 * Returns: 960 *\li #ISC_R_SUCCESS 961 */ 962 963 isc_sockaddr_t * 964 dns_zone_getparentalsrc6(dns_zone_t *zone); 965 /*%< 966 * Returns the source address set by a previous dns_zone_setparentalsrc6 967 * call, or the default of in6addr_any, port 0. 968 * 969 * Require: 970 *\li 'zone' to be a valid zone. 971 */ 972 973 isc_dscp_t 974 dns_zone_getparentalsrc6dscp(dns_zone_t *zone); 975 /*%/ 976 * Get the DSCP value associated with the IPv6 parental source. 977 * 978 * Require: 979 *\li 'zone' to be a valid zone. 980 */ 981 982 isc_result_t 983 dns_zone_setparentalsrc6dscp(dns_zone_t *zone, isc_dscp_t dscp); 984 /*%< 985 * Set the DSCP value associated with the IPv6 parental source. 986 * 987 * Require: 988 *\li 'zone' to be a valid zone. 989 * 990 * Returns: 991 *\li #ISC_R_SUCCESS 992 */ 993 994 isc_result_t 995 dns_zone_setnotifysrc4(dns_zone_t *zone, const isc_sockaddr_t *notifysrc); 996 /*%< 997 * Set the source address to be used with IPv4 NOTIFY messages. 998 * 999 * Require: 1000 *\li 'zone' to be a valid zone. 1001 *\li 'notifysrc' to contain the address. 1002 * 1003 * Returns: 1004 *\li #ISC_R_SUCCESS 1005 */ 1006 1007 isc_sockaddr_t * 1008 dns_zone_getnotifysrc4(dns_zone_t *zone); 1009 /*%< 1010 * Returns the source address set by a previous dns_zone_setnotifysrc4 1011 * call, or the default of inaddr_any, port 0. 1012 * 1013 * Require: 1014 *\li 'zone' to be a valid zone. 1015 */ 1016 1017 isc_dscp_t 1018 dns_zone_getnotifysrc4dscp(dns_zone_t *zone); 1019 /*%/ 1020 * Get the DSCP value associated with the IPv4 notify source. 1021 * 1022 * Require: 1023 *\li 'zone' to be a valid zone. 1024 */ 1025 1026 isc_result_t 1027 dns_zone_setnotifysrc4dscp(dns_zone_t *zone, isc_dscp_t dscp); 1028 /*%< 1029 * Set the DSCP value associated with the IPv4 notify source. 1030 * 1031 * Require: 1032 *\li 'zone' to be a valid zone. 1033 * 1034 * Returns: 1035 *\li #ISC_R_SUCCESS 1036 */ 1037 1038 isc_result_t 1039 dns_zone_setnotifysrc6(dns_zone_t *zone, const isc_sockaddr_t *notifysrc); 1040 /*%< 1041 * Set the source address to be used with IPv6 NOTIFY messages. 1042 * 1043 * Require: 1044 *\li 'zone' to be a valid zone. 1045 *\li 'notifysrc' to contain the address. 1046 * 1047 * Returns: 1048 *\li #ISC_R_SUCCESS 1049 */ 1050 1051 isc_sockaddr_t * 1052 dns_zone_getnotifysrc6(dns_zone_t *zone); 1053 /*%< 1054 * Returns the source address set by a previous dns_zone_setnotifysrc6 1055 * call, or the default of in6addr_any, port 0. 1056 * 1057 * Require: 1058 *\li 'zone' to be a valid zone. 1059 */ 1060 1061 isc_dscp_t 1062 dns_zone_getnotifysrc6dscp(dns_zone_t *zone); 1063 /*%/ 1064 * Get the DSCP value associated with the IPv6 notify source. 1065 * 1066 * Require: 1067 *\li 'zone' to be a valid zone. 1068 */ 1069 1070 isc_result_t 1071 dns_zone_setnotifysrc6dscp(dns_zone_t *zone, isc_dscp_t dscp); 1072 /*%< 1073 * Set the DSCP value associated with the IPv6 notify source. 1074 * 1075 * Require: 1076 *\li 'zone' to be a valid zone. 1077 * 1078 * Returns: 1079 *\li #ISC_R_SUCCESS 1080 */ 1081 1082 void 1083 dns_zone_setnotifyacl(dns_zone_t *zone, dns_acl_t *acl); 1084 /*%< 1085 * Sets the notify acl list for the zone. 1086 * 1087 * Require: 1088 *\li 'zone' to be a valid zone. 1089 *\li 'acl' to be a valid acl. 1090 */ 1091 1092 void 1093 dns_zone_setqueryacl(dns_zone_t *zone, dns_acl_t *acl); 1094 /*%< 1095 * Sets the query acl list for the zone. 1096 * 1097 * Require: 1098 *\li 'zone' to be a valid zone. 1099 *\li 'acl' to be a valid acl. 1100 */ 1101 1102 void 1103 dns_zone_setqueryonacl(dns_zone_t *zone, dns_acl_t *acl); 1104 /*%< 1105 * Sets the query-on acl list for the zone. 1106 * 1107 * Require: 1108 *\li 'zone' to be a valid zone. 1109 *\li 'acl' to be a valid acl. 1110 */ 1111 1112 void 1113 dns_zone_setupdateacl(dns_zone_t *zone, dns_acl_t *acl); 1114 /*%< 1115 * Sets the update acl list for the zone. 1116 * 1117 * Require: 1118 *\li 'zone' to be a valid zone. 1119 *\li 'acl' to be valid acl. 1120 */ 1121 1122 void 1123 dns_zone_setforwardacl(dns_zone_t *zone, dns_acl_t *acl); 1124 /*%< 1125 * Sets the forward unsigned updates acl list for the zone. 1126 * 1127 * Require: 1128 *\li 'zone' to be a valid zone. 1129 *\li 'acl' to be valid acl. 1130 */ 1131 1132 void 1133 dns_zone_setxfracl(dns_zone_t *zone, dns_acl_t *acl); 1134 /*%< 1135 * Sets the transfer acl list for the zone. 1136 * 1137 * Require: 1138 *\li 'zone' to be a valid zone. 1139 *\li 'acl' to be valid acl. 1140 */ 1141 1142 dns_acl_t * 1143 dns_zone_getnotifyacl(dns_zone_t *zone); 1144 /*%< 1145 * Returns the current notify acl or NULL. 1146 * 1147 * Require: 1148 *\li 'zone' to be a valid zone. 1149 * 1150 * Returns: 1151 *\li acl a pointer to the acl. 1152 *\li NULL 1153 */ 1154 1155 dns_acl_t * 1156 dns_zone_getqueryacl(dns_zone_t *zone); 1157 /*%< 1158 * Returns the current query acl or NULL. 1159 * 1160 * Require: 1161 *\li 'zone' to be a valid zone. 1162 * 1163 * Returns: 1164 *\li acl a pointer to the acl. 1165 *\li NULL 1166 */ 1167 1168 dns_acl_t * 1169 dns_zone_getqueryonacl(dns_zone_t *zone); 1170 /*%< 1171 * Returns the current query-on acl or NULL. 1172 * 1173 * Require: 1174 *\li 'zone' to be a valid zone. 1175 * 1176 * Returns: 1177 *\li acl a pointer to the acl. 1178 *\li NULL 1179 */ 1180 1181 dns_acl_t * 1182 dns_zone_getupdateacl(dns_zone_t *zone); 1183 /*%< 1184 * Returns the current update acl or NULL. 1185 * 1186 * Require: 1187 *\li 'zone' to be a valid zone. 1188 * 1189 * Returns: 1190 *\li acl a pointer to the acl. 1191 *\li NULL 1192 */ 1193 1194 dns_acl_t * 1195 dns_zone_getforwardacl(dns_zone_t *zone); 1196 /*%< 1197 * Returns the current forward unsigned updates acl or NULL. 1198 * 1199 * Require: 1200 *\li 'zone' to be a valid zone. 1201 * 1202 * Returns: 1203 *\li acl a pointer to the acl. 1204 *\li NULL 1205 */ 1206 1207 dns_acl_t * 1208 dns_zone_getxfracl(dns_zone_t *zone); 1209 /*%< 1210 * Returns the current transfer acl or NULL. 1211 * 1212 * Require: 1213 *\li 'zone' to be a valid zone. 1214 * 1215 * Returns: 1216 *\li acl a pointer to the acl. 1217 *\li NULL 1218 */ 1219 1220 void 1221 dns_zone_clearupdateacl(dns_zone_t *zone); 1222 /*%< 1223 * Clear the current update acl. 1224 * 1225 * Require: 1226 *\li 'zone' to be a valid zone. 1227 */ 1228 1229 void 1230 dns_zone_clearforwardacl(dns_zone_t *zone); 1231 /*%< 1232 * Clear the current forward unsigned updates acl. 1233 * 1234 * Require: 1235 *\li 'zone' to be a valid zone. 1236 */ 1237 1238 void 1239 dns_zone_clearnotifyacl(dns_zone_t *zone); 1240 /*%< 1241 * Clear the current notify acl. 1242 * 1243 * Require: 1244 *\li 'zone' to be a valid zone. 1245 */ 1246 1247 void 1248 dns_zone_clearqueryacl(dns_zone_t *zone); 1249 /*%< 1250 * Clear the current query acl. 1251 * 1252 * Require: 1253 *\li 'zone' to be a valid zone. 1254 */ 1255 1256 void 1257 dns_zone_clearqueryonacl(dns_zone_t *zone); 1258 /*%< 1259 * Clear the current query-on acl. 1260 * 1261 * Require: 1262 *\li 'zone' to be a valid zone. 1263 */ 1264 1265 void 1266 dns_zone_clearxfracl(dns_zone_t *zone); 1267 /*%< 1268 * Clear the current transfer acl. 1269 * 1270 * Require: 1271 *\li 'zone' to be a valid zone. 1272 */ 1273 1274 bool 1275 dns_zone_getupdatedisabled(dns_zone_t *zone); 1276 /*%< 1277 * Return update disabled. 1278 * Transient unless called when running in isc_task_exclusive() mode. 1279 */ 1280 1281 void 1282 dns_zone_setupdatedisabled(dns_zone_t *zone, bool state); 1283 /*%< 1284 * Set update disabled. 1285 * Should only be called only when running in isc_task_exclusive() mode. 1286 * Failure to do so may result in updates being committed after the 1287 * call has been made. 1288 */ 1289 1290 bool 1291 dns_zone_getzeronosoattl(dns_zone_t *zone); 1292 /*%< 1293 * Return zero-no-soa-ttl status. 1294 */ 1295 1296 void 1297 dns_zone_setzeronosoattl(dns_zone_t *zone, bool state); 1298 /*%< 1299 * Set zero-no-soa-ttl status. 1300 */ 1301 1302 void 1303 dns_zone_setchecknames(dns_zone_t *zone, dns_severity_t severity); 1304 /*%< 1305 * Set the severity of name checking when loading a zone. 1306 * 1307 * Require: 1308 * \li 'zone' to be a valid zone. 1309 */ 1310 1311 dns_severity_t 1312 dns_zone_getchecknames(dns_zone_t *zone); 1313 /*%< 1314 * Return the current severity of name checking. 1315 * 1316 * Require: 1317 *\li 'zone' to be a valid zone. 1318 */ 1319 1320 void 1321 dns_zone_setjournalsize(dns_zone_t *zone, int32_t size); 1322 /*%< 1323 * Sets the journal size for the zone. 1324 * 1325 * Requires: 1326 *\li 'zone' to be a valid zone. 1327 */ 1328 1329 int32_t 1330 dns_zone_getjournalsize(dns_zone_t *zone); 1331 /*%< 1332 * Return the journal size as set with a previous call to 1333 * dns_zone_setjournalsize(). 1334 * 1335 * Requires: 1336 *\li 'zone' to be a valid zone. 1337 */ 1338 1339 isc_result_t 1340 dns_zone_notifyreceive(dns_zone_t *zone, isc_sockaddr_t *from, 1341 isc_sockaddr_t *to, dns_message_t *msg); 1342 /*%< 1343 * Tell the zone that it has received a NOTIFY message from another 1344 * server. This may cause some zone maintenance activity to occur. 1345 * 1346 * Requires: 1347 *\li 'zone' to be a valid zone. 1348 *\li '*from' to contain the address of the server from which 'msg' 1349 * was received. 1350 *\li 'msg' a message with opcode NOTIFY and qr clear. 1351 * 1352 * Returns: 1353 *\li DNS_R_REFUSED 1354 *\li DNS_R_NOTIMP 1355 *\li DNS_R_FORMERR 1356 *\li DNS_R_SUCCESS 1357 */ 1358 1359 void 1360 dns_zone_setmaxxfrin(dns_zone_t *zone, uint32_t maxxfrin); 1361 /*%< 1362 * Set the maximum time (in seconds) that a zone transfer in (AXFR/IXFR) 1363 * of this zone will use before being aborted. 1364 * 1365 * Requires: 1366 * \li 'zone' to be valid initialised zone. 1367 */ 1368 1369 uint32_t 1370 dns_zone_getmaxxfrin(dns_zone_t *zone); 1371 /*%< 1372 * Returns the maximum transfer time for this zone. This will be 1373 * either the value set by the last call to dns_zone_setmaxxfrin() or 1374 * the default value of 1 hour. 1375 * 1376 * Requires: 1377 *\li 'zone' to be valid initialised zone. 1378 */ 1379 1380 void 1381 dns_zone_setmaxxfrout(dns_zone_t *zone, uint32_t maxxfrout); 1382 /*%< 1383 * Set the maximum time (in seconds) that a zone transfer out (AXFR/IXFR) 1384 * of this zone will use before being aborted. 1385 * 1386 * Requires: 1387 * \li 'zone' to be valid initialised zone. 1388 */ 1389 1390 uint32_t 1391 dns_zone_getmaxxfrout(dns_zone_t *zone); 1392 /*%< 1393 * Returns the maximum transfer time for this zone. This will be 1394 * either the value set by the last call to dns_zone_setmaxxfrout() or 1395 * the default value of 1 hour. 1396 * 1397 * Requires: 1398 *\li 'zone' to be valid initialised zone. 1399 */ 1400 1401 isc_result_t 1402 dns_zone_setjournal(dns_zone_t *zone, const char *myjournal); 1403 /*%< 1404 * Sets the filename used for journaling updates / IXFR transfers. 1405 * The default journal name is set by dns_zone_setfile() to be 1406 * "file.jnl". If 'myjournal' is NULL, the zone will have no 1407 * journal name. 1408 * 1409 * Requires: 1410 *\li 'zone' to be a valid zone. 1411 * 1412 * Returns: 1413 *\li #ISC_R_SUCCESS 1414 *\li #ISC_R_NOMEMORY 1415 */ 1416 1417 char * 1418 dns_zone_getjournal(dns_zone_t *zone); 1419 /*%< 1420 * Returns the journal name associated with this zone. 1421 * If no journal has been set this will be NULL. 1422 * 1423 * Requires: 1424 *\li 'zone' to be valid initialised zone. 1425 */ 1426 1427 dns_zonetype_t 1428 dns_zone_gettype(dns_zone_t *zone); 1429 /*%< 1430 * Returns the type of the zone (master/slave/etc.) 1431 * 1432 * Requires: 1433 *\li 'zone' to be valid initialised zone. 1434 */ 1435 1436 dns_zonetype_t 1437 dns_zone_getredirecttype(dns_zone_t *zone); 1438 /*%< 1439 * Returns whether the redirect zone is configured as a master or a 1440 * slave zone. 1441 * 1442 * Requires: 1443 *\li 'zone' to be valid initialised zone. 1444 *\li 'zone' to be a redirect zone. 1445 * 1446 * Returns: 1447 *\li 'dns_zone_primary' 1448 *\li 'dns_zone_secondary' 1449 */ 1450 1451 void 1452 dns_zone_settask(dns_zone_t *zone, isc_task_t *task); 1453 /*%< 1454 * Give a zone a task to work with. Any current task will be detached. 1455 * 1456 * Requires: 1457 *\li 'zone' to be valid. 1458 *\li 'task' to be valid. 1459 */ 1460 1461 void 1462 dns_zone_gettask(dns_zone_t *zone, isc_task_t **target); 1463 /*%< 1464 * Attach '*target' to the zone's task. 1465 * 1466 * Requires: 1467 *\li 'zone' to be valid initialised zone. 1468 *\li 'zone' to have a task. 1469 *\li 'target' to be != NULL && '*target' == NULL. 1470 */ 1471 1472 void 1473 dns_zone_notify(dns_zone_t *zone); 1474 /*%< 1475 * Generate notify events for this zone. 1476 * 1477 * Requires: 1478 *\li 'zone' to be a valid zone. 1479 */ 1480 1481 isc_result_t 1482 dns_zone_replacedb(dns_zone_t *zone, dns_db_t *db, bool dump); 1483 /*%< 1484 * Replace the database of "zone" with a new database "db". 1485 * 1486 * If "dump" is true, then the new zone contents are dumped 1487 * into to the zone's master file for persistence. When replacing 1488 * a zone database by one just loaded from a master file, set 1489 * "dump" to false to avoid a redundant redump of the data just 1490 * loaded. Otherwise, it should be set to true. 1491 * 1492 * If the "diff-on-reload" option is enabled in the configuration file, 1493 * the differences between the old and the new database are added to the 1494 * journal file, and the master file dump is postponed. 1495 * 1496 * Requires: 1497 * \li 'zone' to be a valid zone. 1498 * 1499 * Returns: 1500 * \li DNS_R_SUCCESS 1501 * \li DNS_R_BADZONE zone failed basic consistency checks: 1502 * * a single SOA must exist 1503 * * some NS records must exist. 1504 * Others 1505 */ 1506 1507 uint32_t 1508 dns_zone_getidlein(dns_zone_t *zone); 1509 /*%< 1510 * Requires: 1511 * \li 'zone' to be a valid zone. 1512 * 1513 * Returns: 1514 * \li number of seconds of idle time before we abort the transfer in. 1515 */ 1516 1517 void 1518 dns_zone_setidlein(dns_zone_t *zone, uint32_t idlein); 1519 /*%< 1520 * \li Set the idle timeout for transfer the. 1521 * \li Zero set the default value, 1 hour. 1522 * 1523 * Requires: 1524 * \li 'zone' to be a valid zone. 1525 */ 1526 1527 uint32_t 1528 dns_zone_getidleout(dns_zone_t *zone); 1529 /*%< 1530 * 1531 * Requires: 1532 * \li 'zone' to be a valid zone. 1533 * 1534 * Returns: 1535 * \li number of seconds of idle time before we abort a transfer out. 1536 */ 1537 1538 void 1539 dns_zone_setidleout(dns_zone_t *zone, uint32_t idleout); 1540 /*%< 1541 * \li Set the idle timeout for transfers out. 1542 * \li Zero set the default value, 1 hour. 1543 * 1544 * Requires: 1545 * \li 'zone' to be a valid zone. 1546 */ 1547 1548 void 1549 dns_zone_getssutable(dns_zone_t *zone, dns_ssutable_t **table); 1550 /*%< 1551 * Get the simple-secure-update policy table. 1552 * 1553 * Requires: 1554 * \li 'zone' to be a valid zone. 1555 */ 1556 1557 void 1558 dns_zone_setssutable(dns_zone_t *zone, dns_ssutable_t *table); 1559 /*%< 1560 * Set / clear the simple-secure-update policy table. 1561 * 1562 * Requires: 1563 * \li 'zone' to be a valid zone. 1564 */ 1565 1566 isc_mem_t * 1567 dns_zone_getmctx(dns_zone_t *zone); 1568 /*%< 1569 * Get the memory context of a zone. 1570 * 1571 * Requires: 1572 * \li 'zone' to be a valid zone. 1573 */ 1574 1575 dns_zonemgr_t * 1576 dns_zone_getmgr(dns_zone_t *zone); 1577 /*%< 1578 * If 'zone' is managed return the zone manager otherwise NULL. 1579 * 1580 * Requires: 1581 * \li 'zone' to be a valid zone. 1582 */ 1583 1584 void 1585 dns_zone_setsigvalidityinterval(dns_zone_t *zone, uint32_t interval); 1586 /*%< 1587 * Set the zone's general signature validity interval. This is the length 1588 * of time for which DNSSEC signatures created as a result of dynamic 1589 * updates to secure zones will remain valid, in seconds. 1590 * 1591 * Requires: 1592 * \li 'zone' to be a valid zone. 1593 */ 1594 1595 uint32_t 1596 dns_zone_getsigvalidityinterval(dns_zone_t *zone); 1597 /*%< 1598 * Get the zone's general signature validity interval. 1599 * 1600 * Requires: 1601 * \li 'zone' to be a valid zone. 1602 */ 1603 1604 void 1605 dns_zone_setkeyvalidityinterval(dns_zone_t *zone, uint32_t interval); 1606 /*%< 1607 * Set the zone's DNSKEY signature validity interval. This is the length 1608 * of time for which DNSSEC signatures created for DNSKEY records 1609 * will remain valid, in seconds. 1610 * 1611 * If this value is set to zero, then the regular signature validity 1612 * interval (see dns_zone_setsigvalidityinterval(), above) is used 1613 * for all RRSIGs. However, if this value is nonzero, then it is used 1614 * as the validity interval for RRSIGs covering DNSKEY and CDNSKEY 1615 * RRsets. 1616 * 1617 * Requires: 1618 * \li 'zone' to be a valid zone. 1619 */ 1620 1621 uint32_t 1622 dns_zone_getkeyvalidityinterval(dns_zone_t *zone); 1623 /*%< 1624 * Get the zone's DNSKEY signature validity interval. 1625 * 1626 * Requires: 1627 * \li 'zone' to be a valid zone. 1628 */ 1629 1630 void 1631 dns_zone_setsigresigninginterval(dns_zone_t *zone, uint32_t interval); 1632 /*%< 1633 * Set the zone's RRSIG re-signing interval. A dynamic zone's RRSIG's 1634 * will be re-signed 'interval' amount of time before they expire. 1635 * 1636 * Requires: 1637 * \li 'zone' to be a valid zone. 1638 */ 1639 1640 uint32_t 1641 dns_zone_getsigresigninginterval(dns_zone_t *zone); 1642 /*%< 1643 * Get the zone's RRSIG re-signing interval. 1644 * 1645 * Requires: 1646 * \li 'zone' to be a valid zone. 1647 */ 1648 1649 void 1650 dns_zone_setnotifytype(dns_zone_t *zone, dns_notifytype_t notifytype); 1651 /*%< 1652 * Sets zone notify method to "notifytype" 1653 */ 1654 1655 isc_result_t 1656 dns_zone_forwardupdate(dns_zone_t *zone, dns_message_t *msg, 1657 dns_updatecallback_t callback, void *callback_arg); 1658 /*%< 1659 * Forward 'msg' to each master in turn until we get an answer or we 1660 * have exhausted the list of primaries. 'callback' will be called with 1661 * ISC_R_SUCCESS if we get an answer and the returned message will be 1662 * passed as 'answer_message', otherwise a non ISC_R_SUCCESS result code 1663 * will be passed and answer_message will be NULL. The callback function 1664 * is responsible for destroying 'answer_message'. 1665 * (callback)(callback_arg, result, answer_message); 1666 * 1667 * Require: 1668 *\li 'zone' to be valid 1669 *\li 'msg' to be valid. 1670 *\li 'callback' to be non NULL. 1671 * Returns: 1672 *\li #ISC_R_SUCCESS if the message has been forwarded, 1673 *\li #ISC_R_NOMEMORY 1674 *\li Others 1675 */ 1676 1677 isc_result_t 1678 dns_zone_next(dns_zone_t *zone, dns_zone_t **next); 1679 /*%< 1680 * Find the next zone in the list of managed zones. 1681 * 1682 * Requires: 1683 *\li 'zone' to be valid 1684 *\li The zone manager for the indicated zone MUST be locked 1685 * by the caller. This is not checked. 1686 *\li 'next' be non-NULL, and '*next' be NULL. 1687 * 1688 * Ensures: 1689 *\li 'next' points to a valid zone (result ISC_R_SUCCESS) or to NULL 1690 * (result ISC_R_NOMORE). 1691 */ 1692 1693 isc_result_t 1694 dns_zone_first(dns_zonemgr_t *zmgr, dns_zone_t **first); 1695 /*%< 1696 * Find the first zone in the list of managed zones. 1697 * 1698 * Requires: 1699 *\li 'zonemgr' to be valid 1700 *\li The zone manager for the indicated zone MUST be locked 1701 * by the caller. This is not checked. 1702 *\li 'first' be non-NULL, and '*first' be NULL 1703 * 1704 * Ensures: 1705 *\li 'first' points to a valid zone (result ISC_R_SUCCESS) or to NULL 1706 * (result ISC_R_NOMORE). 1707 */ 1708 1709 isc_result_t 1710 dns_zone_setkeydirectory(dns_zone_t *zone, const char *directory); 1711 /*%< 1712 * Sets the name of the directory where private keys used for 1713 * online signing of dynamic zones are found. 1714 * 1715 * Require: 1716 *\li 'zone' to be a valid zone. 1717 * 1718 * Returns: 1719 *\li #ISC_R_NOMEMORY 1720 *\li #ISC_R_SUCCESS 1721 */ 1722 1723 const char * 1724 dns_zone_getkeydirectory(dns_zone_t *zone); 1725 /*%< 1726 * Gets the name of the directory where private keys used for 1727 * online signing of dynamic zones are found. 1728 * 1729 * Requires: 1730 *\li 'zone' to be valid initialised zone. 1731 * 1732 * Returns: 1733 * Pointer to null-terminated file name, or NULL. 1734 */ 1735 1736 isc_result_t 1737 dns_zone_getdnsseckeys(dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *ver, 1738 isc_stdtime_t now, dns_dnsseckeylist_t *keys); 1739 /*% 1740 * Find DNSSEC keys used for signing with dnssec-policy. Load these keys 1741 * into 'keys'. 1742 * 1743 * Requires: 1744 *\li 'zone' to be valid initialised zone. 1745 *\li 'keys' to be an initialised DNSSEC keylist. 1746 * 1747 * Returns: 1748 *\li #ISC_R_SUCCESS 1749 *\li Error 1750 */ 1751 1752 isc_result_t 1753 dns_zonemgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr, 1754 isc_timermgr_t *timermgr, isc_socketmgr_t *socketmgr, 1755 dns_zonemgr_t **zmgrp); 1756 /*%< 1757 * Create a zone manager. Note: the zone manager will not be able to 1758 * manage any zones until dns_zonemgr_setsize() has been run. 1759 * 1760 * Requires: 1761 *\li 'mctx' to be a valid memory context. 1762 *\li 'taskmgr' to be a valid task manager. 1763 *\li 'timermgr' to be a valid timer manager. 1764 *\li 'zmgrp' to point to a NULL pointer. 1765 */ 1766 1767 isc_result_t 1768 dns_zonemgr_setsize(dns_zonemgr_t *zmgr, int num_zones); 1769 /*%< 1770 * Set the size of the zone manager task pool. This must be run 1771 * before zmgr can be used for managing zones. Currently, it can only 1772 * be run once; the task pool cannot be resized. 1773 * 1774 * Requires: 1775 *\li zmgr is a valid zone manager. 1776 *\li zmgr->zonetasks has been initialized. 1777 */ 1778 1779 isc_result_t 1780 dns_zonemgr_createzone(dns_zonemgr_t *zmgr, dns_zone_t **zonep); 1781 /*%< 1782 * Allocate a new zone using a memory context from the 1783 * zone manager's memory context pool. 1784 * 1785 * Require: 1786 *\li 'zmgr' to be a valid zone manager. 1787 *\li 'zonep' != NULL and '*zonep' == NULL. 1788 */ 1789 1790 isc_result_t 1791 dns_zonemgr_managezone(dns_zonemgr_t *zmgr, dns_zone_t *zone); 1792 /*%< 1793 * Bring the zone under control of a zone manager. 1794 * 1795 * Require: 1796 *\li 'zmgr' to be a valid zone manager. 1797 *\li 'zone' to be a valid zone. 1798 */ 1799 1800 isc_result_t 1801 dns_zonemgr_forcemaint(dns_zonemgr_t *zmgr); 1802 /*%< 1803 * Force zone maintenance of all loaded zones managed by 'zmgr' 1804 * to take place at the system's earliest convenience. 1805 */ 1806 1807 void 1808 dns__zonemgr_run(isc_task_t *task, isc_event_t *event); 1809 /*%< 1810 * Event handler to call dns_zonemgr_forcemaint(); used to start 1811 * zone operations from a unit test. Not intended for use outside 1812 * libdns or related tests. 1813 */ 1814 1815 void 1816 dns_zonemgr_resumexfrs(dns_zonemgr_t *zmgr); 1817 /*%< 1818 * Attempt to start any stalled zone transfers. 1819 */ 1820 1821 void 1822 dns_zonemgr_shutdown(dns_zonemgr_t *zmgr); 1823 /*%< 1824 * Shut down the zone manager. 1825 * 1826 * Requires: 1827 *\li 'zmgr' to be a valid zone manager. 1828 */ 1829 1830 void 1831 dns_zonemgr_attach(dns_zonemgr_t *source, dns_zonemgr_t **target); 1832 /*%< 1833 * Attach '*target' to 'source' incrementing its external 1834 * reference count. 1835 * 1836 * Require: 1837 *\li 'zone' to be a valid zone. 1838 *\li 'target' to be non NULL and '*target' to be NULL. 1839 */ 1840 1841 void 1842 dns_zonemgr_detach(dns_zonemgr_t **zmgrp); 1843 /*%< 1844 * Detach from a zone manager. 1845 * 1846 * Requires: 1847 *\li '*zmgrp' is a valid, non-NULL zone manager pointer. 1848 * 1849 * Ensures: 1850 *\li '*zmgrp' is NULL. 1851 */ 1852 1853 void 1854 dns_zonemgr_releasezone(dns_zonemgr_t *zmgr, dns_zone_t *zone); 1855 /*%< 1856 * Release 'zone' from the managed by 'zmgr'. 'zmgr' is implicitly 1857 * detached from 'zone'. 1858 * 1859 * Requires: 1860 *\li 'zmgr' to be a valid zone manager. 1861 *\li 'zone' to be a valid zone. 1862 *\li 'zmgr' == 'zone->zmgr' 1863 * 1864 * Ensures: 1865 *\li 'zone->zmgr' == NULL; 1866 */ 1867 1868 isc_taskmgr_t * 1869 dns_zonemgr_gettaskmgr(dns_zonemgr_t *zmgr); 1870 /*% 1871 * Get the tasmkgr object attached to 'zmgr'. 1872 */ 1873 1874 void 1875 dns_zonemgr_settransfersin(dns_zonemgr_t *zmgr, uint32_t value); 1876 /*%< 1877 * Set the maximum number of simultaneous transfers in allowed by 1878 * the zone manager. 1879 * 1880 * Requires: 1881 *\li 'zmgr' to be a valid zone manager. 1882 */ 1883 1884 uint32_t 1885 dns_zonemgr_getttransfersin(dns_zonemgr_t *zmgr); 1886 /*%< 1887 * Return the maximum number of simultaneous transfers in allowed. 1888 * 1889 * Requires: 1890 *\li 'zmgr' to be a valid zone manager. 1891 */ 1892 1893 void 1894 dns_zonemgr_settransfersperns(dns_zonemgr_t *zmgr, uint32_t value); 1895 /*%< 1896 * Set the number of zone transfers allowed per nameserver. 1897 * 1898 * Requires: 1899 *\li 'zmgr' to be a valid zone manager 1900 */ 1901 1902 uint32_t 1903 dns_zonemgr_getttransfersperns(dns_zonemgr_t *zmgr); 1904 /*%< 1905 * Return the number of transfers allowed per nameserver. 1906 * 1907 * Requires: 1908 *\li 'zmgr' to be a valid zone manager. 1909 */ 1910 1911 void 1912 dns_zonemgr_setiolimit(dns_zonemgr_t *zmgr, uint32_t iolimit); 1913 /*%< 1914 * Set the number of simultaneous file descriptors available for 1915 * reading and writing masterfiles. 1916 * 1917 * Requires: 1918 *\li 'zmgr' to be a valid zone manager. 1919 *\li 'iolimit' to be positive. 1920 */ 1921 1922 uint32_t 1923 dns_zonemgr_getiolimit(dns_zonemgr_t *zmgr); 1924 /*%< 1925 * Get the number of simultaneous file descriptors available for 1926 * reading and writing masterfiles. 1927 * 1928 * Requires: 1929 *\li 'zmgr' to be a valid zone manager. 1930 */ 1931 1932 void 1933 dns_zonemgr_setcheckdsrate(dns_zonemgr_t *zmgr, unsigned int value); 1934 /*%< 1935 * Set the number of parental DS queries sent per second. 1936 * 1937 * Requires: 1938 *\li 'zmgr' to be a valid zone manager 1939 */ 1940 1941 void 1942 dns_zonemgr_setnotifyrate(dns_zonemgr_t *zmgr, unsigned int value); 1943 /*%< 1944 * Set the number of NOTIFY requests sent per second. 1945 * 1946 * Requires: 1947 *\li 'zmgr' to be a valid zone manager 1948 */ 1949 1950 void 1951 dns_zonemgr_setstartupnotifyrate(dns_zonemgr_t *zmgr, unsigned int value); 1952 /*%< 1953 * Set the number of startup NOTIFY requests sent per second. 1954 * 1955 * Requires: 1956 *\li 'zmgr' to be a valid zone manager 1957 */ 1958 1959 void 1960 dns_zonemgr_setserialqueryrate(dns_zonemgr_t *zmgr, unsigned int value); 1961 /*%< 1962 * Set the number of SOA queries sent per second. 1963 * 1964 * Requires: 1965 *\li 'zmgr' to be a valid zone manager 1966 */ 1967 1968 unsigned int 1969 dns_zonemgr_getnotifyrate(dns_zonemgr_t *zmgr); 1970 /*%< 1971 * Return the number of NOTIFY requests sent per second. 1972 * 1973 * Requires: 1974 *\li 'zmgr' to be a valid zone manager. 1975 */ 1976 1977 unsigned int 1978 dns_zonemgr_getstartupnotifyrate(dns_zonemgr_t *zmgr); 1979 /*%< 1980 * Return the number of startup NOTIFY requests sent per second. 1981 * 1982 * Requires: 1983 *\li 'zmgr' to be a valid zone manager. 1984 */ 1985 1986 unsigned int 1987 dns_zonemgr_getserialqueryrate(dns_zonemgr_t *zmgr); 1988 /*%< 1989 * Return the number of SOA queries sent per second. 1990 * 1991 * Requires: 1992 *\li 'zmgr' to be a valid zone manager. 1993 */ 1994 1995 unsigned int 1996 dns_zonemgr_getcount(dns_zonemgr_t *zmgr, int state); 1997 /*%< 1998 * Returns the number of zones in the specified state. 1999 * 2000 * Requires: 2001 *\li 'zmgr' to be a valid zone manager. 2002 *\li 'state' to be a valid DNS_ZONESTATE_ constant. 2003 */ 2004 2005 void 2006 dns_zonemgr_unreachableadd(dns_zonemgr_t *zmgr, isc_sockaddr_t *remote, 2007 isc_sockaddr_t *local, isc_time_t *now); 2008 /*%< 2009 * Add the pair of addresses to the unreachable cache. 2010 * 2011 * Requires: 2012 *\li 'zmgr' to be a valid zone manager. 2013 *\li 'remote' to be a valid sockaddr. 2014 *\li 'local' to be a valid sockaddr. 2015 */ 2016 2017 bool 2018 dns_zonemgr_unreachable(dns_zonemgr_t *zmgr, isc_sockaddr_t *remote, 2019 isc_sockaddr_t *local, isc_time_t *now); 2020 /*%< 2021 * Returns true if the given local/remote address pair 2022 * is found in the zone maanger's unreachable cache. 2023 * 2024 * Requires: 2025 *\li 'zmgr' to be a valid zone manager. 2026 *\li 'remote' to be a valid sockaddr. 2027 *\li 'local' to be a valid sockaddr. 2028 *\li 'now' != NULL 2029 */ 2030 2031 void 2032 dns_zonemgr_unreachabledel(dns_zonemgr_t *zmgr, isc_sockaddr_t *remote, 2033 isc_sockaddr_t *local); 2034 /*%< 2035 * Remove the pair of addresses from the unreachable cache. 2036 * 2037 * Requires: 2038 *\li 'zmgr' to be a valid zone manager. 2039 *\li 'remote' to be a valid sockaddr. 2040 *\li 'local' to be a valid sockaddr. 2041 */ 2042 2043 void 2044 dns_zone_forcereload(dns_zone_t *zone); 2045 /*%< 2046 * Force a reload of specified zone. 2047 * 2048 * Requires: 2049 *\li 'zone' to be a valid zone. 2050 */ 2051 2052 bool 2053 dns_zone_isforced(dns_zone_t *zone); 2054 /*%< 2055 * Check if the zone is waiting a forced reload. 2056 * 2057 * Requires: 2058 * \li 'zone' to be a valid zone. 2059 */ 2060 2061 isc_result_t 2062 dns_zone_setstatistics(dns_zone_t *zone, bool on); 2063 /*%< 2064 * This function is obsoleted by dns_zone_setrequeststats(). 2065 */ 2066 2067 uint64_t * 2068 dns_zone_getstatscounters(dns_zone_t *zone); 2069 /*%< 2070 * This function is obsoleted by dns_zone_getrequeststats(). 2071 */ 2072 2073 void 2074 dns_zone_setstats(dns_zone_t *zone, isc_stats_t *stats); 2075 /*%< 2076 * Set a general zone-maintenance statistics set 'stats' for 'zone'. This 2077 * function is expected to be called only on zone creation (when necessary). 2078 * Once installed, it cannot be removed or replaced. Also, there is no 2079 * interface to get the installed stats from the zone; the caller must keep the 2080 * stats to reference (e.g. dump) it later. 2081 * 2082 * Requires: 2083 * \li 'zone' to be a valid zone and does not have a statistics set already 2084 * installed. 2085 * 2086 *\li stats is a valid statistics supporting zone statistics counters 2087 * (see dns/stats.h). 2088 */ 2089 2090 void 2091 dns_zone_setrequeststats(dns_zone_t *zone, isc_stats_t *stats); 2092 2093 void 2094 dns_zone_setrcvquerystats(dns_zone_t *zone, dns_stats_t *stats); 2095 2096 void 2097 dns_zone_setdnssecsignstats(dns_zone_t *zone, dns_stats_t *stats); 2098 /*%< 2099 * Set additional statistics sets to zone. These are attached to the zone 2100 * but are not counted in the zone module; only the caller updates the 2101 * counters. 2102 * 2103 * Requires: 2104 * \li 'zone' to be a valid zone. 2105 * 2106 *\li stats is a valid statistics. 2107 */ 2108 2109 isc_stats_t * 2110 dns_zone_getrequeststats(dns_zone_t *zone); 2111 2112 dns_stats_t * 2113 dns_zone_getrcvquerystats(dns_zone_t *zone); 2114 2115 dns_stats_t * 2116 dns_zone_getdnssecsignstats(dns_zone_t *zone); 2117 /*%< 2118 * Get the additional statistics for zone, if one is installed. 2119 * 2120 * Requires: 2121 * \li 'zone' to be a valid zone. 2122 * 2123 * Returns: 2124 * \li when available, a pointer to the statistics set installed in zone; 2125 * otherwise NULL. 2126 */ 2127 2128 void 2129 dns_zone_dialup(dns_zone_t *zone); 2130 /*%< 2131 * Perform dialup-time maintenance on 'zone'. 2132 */ 2133 2134 void 2135 dns_zone_setdialup(dns_zone_t *zone, dns_dialuptype_t dialup); 2136 /*%< 2137 * Set the dialup type of 'zone' to 'dialup'. 2138 * 2139 * Requires: 2140 * \li 'zone' to be valid initialised zone. 2141 *\li 'dialup' to be a valid dialup type. 2142 */ 2143 2144 void 2145 dns_zone_logv(dns_zone_t *zone, isc_logcategory_t *category, int level, 2146 const char *prefix, const char *msg, va_list ap); 2147 /*%< 2148 * Log the message 'msg...' at 'level' using log category 'category', including 2149 * text that identifies the message as applying to 'zone'. If the (optional) 2150 * 'prefix' is not NULL, it will be placed at the start of the entire log line. 2151 */ 2152 2153 void 2154 dns_zone_log(dns_zone_t *zone, int level, const char *msg, ...) 2155 ISC_FORMAT_PRINTF(3, 4); 2156 /*%< 2157 * Log the message 'msg...' at 'level', including text that identifies 2158 * the message as applying to 'zone'. 2159 */ 2160 2161 void 2162 dns_zone_logc(dns_zone_t *zone, isc_logcategory_t *category, int level, 2163 const char *msg, ...) ISC_FORMAT_PRINTF(4, 5); 2164 /*%< 2165 * Log the message 'msg...' at 'level', including text that identifies 2166 * the message as applying to 'zone'. 2167 */ 2168 2169 void 2170 dns_zone_name(dns_zone_t *zone, char *buf, size_t len); 2171 /*%< 2172 * Return the name of the zone with class and view. 2173 * 2174 * Requires: 2175 *\li 'zone' to be valid. 2176 *\li 'buf' to be non NULL. 2177 */ 2178 2179 void 2180 dns_zone_nameonly(dns_zone_t *zone, char *buf, size_t len); 2181 /*%< 2182 * Return the name of the zone only. 2183 * 2184 * Requires: 2185 *\li 'zone' to be valid. 2186 *\li 'buf' to be non NULL. 2187 */ 2188 2189 isc_result_t 2190 dns_zone_checknames(dns_zone_t *zone, const dns_name_t *name, 2191 dns_rdata_t *rdata); 2192 /*%< 2193 * Check if this record meets the check-names policy. 2194 * 2195 * Requires: 2196 * 'zone' to be valid. 2197 * 'name' to be valid. 2198 * 'rdata' to be valid. 2199 * 2200 * Returns: 2201 * DNS_R_SUCCESS passed checks. 2202 * DNS_R_BADOWNERNAME failed ownername checks. 2203 * DNS_R_BADNAME failed rdata checks. 2204 */ 2205 2206 void 2207 dns_zone_setcheckmx(dns_zone_t *zone, dns_checkmxfunc_t checkmx); 2208 /*%< 2209 * Set the post load integrity callback function 'checkmx'. 2210 * 'checkmx' will be called if the MX TARGET is not within the zone. 2211 * 2212 * Require: 2213 * 'zone' to be a valid zone. 2214 */ 2215 2216 void 2217 dns_zone_setchecksrv(dns_zone_t *zone, dns_checkmxfunc_t checksrv); 2218 /*%< 2219 * Set the post load integrity callback function 'checksrv'. 2220 * 'checksrv' will be called if the SRV TARGET is not within the zone. 2221 * 2222 * Require: 2223 * 'zone' to be a valid zone. 2224 */ 2225 2226 void 2227 dns_zone_setcheckns(dns_zone_t *zone, dns_checknsfunc_t checkns); 2228 /*%< 2229 * Set the post load integrity callback function 'checkns'. 2230 * 'checkns' will be called if the NS TARGET is not within the zone. 2231 * 2232 * Require: 2233 * 'zone' to be a valid zone. 2234 */ 2235 2236 void 2237 dns_zone_setnotifydelay(dns_zone_t *zone, uint32_t delay); 2238 /*%< 2239 * Set the minimum delay between sets of notify messages. 2240 * 2241 * Requires: 2242 * 'zone' to be valid. 2243 */ 2244 2245 uint32_t 2246 dns_zone_getnotifydelay(dns_zone_t *zone); 2247 /*%< 2248 * Get the minimum delay between sets of notify messages. 2249 * 2250 * Requires: 2251 * 'zone' to be valid. 2252 */ 2253 2254 void 2255 dns_zone_setisself(dns_zone_t *zone, dns_isselffunc_t isself, void *arg); 2256 /*%< 2257 * Set the isself callback function and argument. 2258 * 2259 * bool 2260 * isself(dns_view_t *myview, dns_tsigkey_t *mykey, 2261 * const isc_netaddr_t *srcaddr, const isc_netaddr_t *destaddr, 2262 * dns_rdataclass_t rdclass, void *arg); 2263 * 2264 * 'isself' returns true if a non-recursive query from 'srcaddr' to 2265 * 'destaddr' with optional key 'mykey' for class 'rdclass' would be 2266 * delivered to 'myview'. 2267 */ 2268 2269 void 2270 dns_zone_setnodes(dns_zone_t *zone, uint32_t nodes); 2271 /*%< 2272 * Set the number of nodes that will be checked per quantum. 2273 */ 2274 2275 void 2276 dns_zone_setsignatures(dns_zone_t *zone, uint32_t signatures); 2277 /*%< 2278 * Set the number of signatures that will be generated per quantum. 2279 */ 2280 2281 uint32_t 2282 dns_zone_getsignatures(dns_zone_t *zone); 2283 /*%< 2284 * Get the number of signatures that will be generated per quantum. 2285 */ 2286 2287 isc_result_t 2288 dns_zone_signwithkey(dns_zone_t *zone, dns_secalg_t algorithm, uint16_t keyid, 2289 bool deleteit); 2290 /*%< 2291 * Initiate/resume signing of the entire zone with the zone DNSKEY(s) 2292 * that match the given algorithm and keyid. 2293 */ 2294 2295 isc_result_t 2296 dns_zone_addnsec3chain(dns_zone_t *zone, dns_rdata_nsec3param_t *nsec3param); 2297 /*%< 2298 * Incrementally add a NSEC3 chain that corresponds to 'nsec3param'. 2299 */ 2300 2301 void 2302 dns_zone_setprivatetype(dns_zone_t *zone, dns_rdatatype_t type); 2303 dns_rdatatype_t 2304 dns_zone_getprivatetype(dns_zone_t *zone); 2305 /* 2306 * Get/Set the private record type. It is expected that these interfaces 2307 * will not be permanent. 2308 */ 2309 2310 void 2311 dns_zone_rekey(dns_zone_t *zone, bool fullsign); 2312 /*%< 2313 * Update the zone's DNSKEY set from the key repository. 2314 * 2315 * If 'fullsign' is true, trigger an immediate full signing of 2316 * the zone with the new key. Otherwise, if there are no keys or 2317 * if the new keys are for algorithms that have already signed the 2318 * zone, then the zone can be re-signed incrementally. 2319 */ 2320 2321 isc_result_t 2322 dns_zone_nscheck(dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version, 2323 unsigned int *errors); 2324 /*% 2325 * Check if the name servers for the zone are sane (have address, don't 2326 * refer to CNAMEs/DNAMEs. The number of constiancy errors detected in 2327 * returned in '*errors' 2328 * 2329 * Requires: 2330 * \li 'zone' to be valid. 2331 * \li 'db' to be valid. 2332 * \li 'version' to be valid or NULL. 2333 * \li 'errors' to be non NULL. 2334 * 2335 * Returns: 2336 * ISC_R_SUCCESS if there were no errors examining the zone contents. 2337 */ 2338 2339 isc_result_t 2340 dns_zone_cdscheck(dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version); 2341 /*% 2342 * Check if CSD, CDNSKEY and DNSKEY are consistent. 2343 * 2344 * Requires: 2345 * \li 'zone' to be valid. 2346 * \li 'db' to be valid. 2347 * \li 'version' to be valid or NULL. 2348 * 2349 * Returns: 2350 *\li #ISC_R_SUCCESS 2351 *\li #DNS_R_BADCDS 2352 *\li #DNS_R_BADCDNSKEY 2353 * Others 2354 */ 2355 2356 void 2357 dns_zone_setadded(dns_zone_t *zone, bool added); 2358 /*% 2359 * Sets the value of zone->added, which should be true for 2360 * zones that were originally added by "rndc addzone". 2361 * 2362 * Requires: 2363 * \li 'zone' to be valid. 2364 */ 2365 2366 bool 2367 dns_zone_getadded(dns_zone_t *zone); 2368 /*% 2369 * Returns true if the zone was originally added at runtime 2370 * using "rndc addzone". 2371 * 2372 * Requires: 2373 * \li 'zone' to be valid. 2374 */ 2375 2376 void 2377 dns_zone_setautomatic(dns_zone_t *zone, bool automatic); 2378 /*% 2379 * Sets the value of zone->automatic, which should be true for 2380 * zones that were automatically added by named. 2381 * 2382 * Requires: 2383 * \li 'zone' to be valid. 2384 */ 2385 2386 bool 2387 dns_zone_getautomatic(dns_zone_t *zone); 2388 /*% 2389 * Returns true if the zone was added automatically by named. 2390 * 2391 * Requires: 2392 * \li 'zone' to be valid. 2393 */ 2394 2395 isc_result_t 2396 dns_zone_dlzpostload(dns_zone_t *zone, dns_db_t *db); 2397 /*% 2398 * Load the origin names for a writeable DLZ database. 2399 */ 2400 2401 bool 2402 dns_zone_isdynamic(dns_zone_t *zone, bool ignore_freeze); 2403 /*% 2404 * Return true iff the zone is "dynamic", in the sense that the zone's 2405 * master file (if any) is written by the server, rather than being 2406 * updated manually and read by the server. 2407 * 2408 * This is true for slave zones, stub zones, key zones, and zones that 2409 * allow dynamic updates either by having an update policy ("ssutable") 2410 * or an "allow-update" ACL with a value other than exactly "{ none; }". 2411 * 2412 * If 'ignore_freeze' is true, then the zone which has had updates disabled 2413 * will still report itself to be dynamic. 2414 * 2415 * Requires: 2416 * \li 'zone' to be valid. 2417 */ 2418 2419 isc_result_t 2420 dns_zone_setrefreshkeyinterval(dns_zone_t *zone, uint32_t interval); 2421 /*% 2422 * Sets the frequency, in minutes, with which the key repository will be 2423 * checked to see if the keys for this zone have been updated. Any value 2424 * higher than 1440 minutes (24 hours) will be silently reduced. A 2425 * value of zero will return an out-of-range error. 2426 * 2427 * Requires: 2428 * \li 'zone' to be valid. 2429 */ 2430 2431 bool 2432 dns_zone_getrequestexpire(dns_zone_t *zone); 2433 /*% 2434 * Returns the true/false value of the request-expire option in the zone. 2435 * 2436 * Requires: 2437 * \li 'zone' to be valid. 2438 */ 2439 2440 void 2441 dns_zone_setrequestexpire(dns_zone_t *zone, bool flag); 2442 /*% 2443 * Sets the request-expire option for the zone. Either true or false. The 2444 * default value is determined by the setting of this option in the view. 2445 * 2446 * Requires: 2447 * \li 'zone' to be valid. 2448 */ 2449 2450 bool 2451 dns_zone_getrequestixfr(dns_zone_t *zone); 2452 /*% 2453 * Returns the true/false value of the request-ixfr option in the zone. 2454 * 2455 * Requires: 2456 * \li 'zone' to be valid. 2457 */ 2458 2459 void 2460 dns_zone_setrequestixfr(dns_zone_t *zone, bool flag); 2461 /*% 2462 * Sets the request-ixfr option for the zone. Either true or false. The 2463 * default value is determined by the setting of this option in the view. 2464 * 2465 * Requires: 2466 * \li 'zone' to be valid. 2467 */ 2468 2469 uint32_t 2470 dns_zone_getixfrratio(dns_zone_t *zone); 2471 /*% 2472 * Returns the zone's current IXFR ratio. 2473 * 2474 * Requires: 2475 * \li 'zone' to be valid. 2476 */ 2477 2478 void 2479 dns_zone_setixfrratio(dns_zone_t *zone, uint32_t ratio); 2480 /*% 2481 * Sets the ratio of IXFR size to zone size above which we use an AXFR 2482 * response, expressed as a percentage. Cannot exceed 100. 2483 * 2484 * Requires: 2485 * \li 'zone' to be valid. 2486 */ 2487 2488 void 2489 dns_zone_setserialupdatemethod(dns_zone_t *zone, dns_updatemethod_t method); 2490 /*% 2491 * Sets the update method to use when incrementing the zone serial number 2492 * due to a DDNS update. Valid options are dns_updatemethod_increment 2493 * and dns_updatemethod_unixtime. 2494 * 2495 * Requires: 2496 * \li 'zone' to be valid. 2497 */ 2498 2499 dns_updatemethod_t 2500 dns_zone_getserialupdatemethod(dns_zone_t *zone); 2501 /*% 2502 * Returns the update method to be used when incrementing the zone serial 2503 * number due to a DDNS update. 2504 * 2505 * Requires: 2506 * \li 'zone' to be valid. 2507 */ 2508 2509 isc_result_t 2510 dns_zone_link(dns_zone_t *zone, dns_zone_t *raw); 2511 2512 void 2513 dns_zone_getraw(dns_zone_t *zone, dns_zone_t **raw); 2514 2515 isc_result_t 2516 dns_zone_keydone(dns_zone_t *zone, const char *data); 2517 2518 isc_result_t 2519 dns_zone_setnsec3param(dns_zone_t *zone, uint8_t hash, uint8_t flags, 2520 uint16_t iter, uint8_t saltlen, unsigned char *salt, 2521 bool replace, bool resalt); 2522 /*% 2523 * Set the NSEC3 parameters for the zone. 2524 * 2525 * If 'replace' is true, then the existing NSEC3 chain, if any, will 2526 * be replaced with the new one. If 'hash' is zero, then the replacement 2527 * chain will be NSEC rather than NSEC3. If 'resalt' is true, or if 'salt' 2528 * is NULL, generate a new salt with the given salt length. 2529 * 2530 * Requires: 2531 * \li 'zone' to be valid. 2532 */ 2533 2534 void 2535 dns_zone_setrawdata(dns_zone_t *zone, dns_masterrawheader_t *header); 2536 /*% 2537 * Set the data to be included in the header when the zone is dumped in 2538 * binary format. 2539 */ 2540 2541 isc_result_t 2542 dns_zone_synckeyzone(dns_zone_t *zone); 2543 /*% 2544 * Force the managed key zone to synchronize, and start the key 2545 * maintenance timer. 2546 */ 2547 2548 isc_result_t 2549 dns_zone_getloadtime(dns_zone_t *zone, isc_time_t *loadtime); 2550 /*% 2551 * Return the time when the zone was last loaded. 2552 */ 2553 2554 isc_result_t 2555 dns_zone_getrefreshtime(dns_zone_t *zone, isc_time_t *refreshtime); 2556 /*% 2557 * Return the time when the (slave) zone will need to be refreshed. 2558 */ 2559 2560 isc_result_t 2561 dns_zone_getexpiretime(dns_zone_t *zone, isc_time_t *expiretime); 2562 /*% 2563 * Return the time when the (slave) zone will expire. 2564 */ 2565 2566 isc_result_t 2567 dns_zone_getrefreshkeytime(dns_zone_t *zone, isc_time_t *refreshkeytime); 2568 /*% 2569 * Return the time of the next scheduled DNSSEC key event. 2570 */ 2571 2572 unsigned int 2573 dns_zone_getincludes(dns_zone_t *zone, char ***includesp); 2574 /*% 2575 * Return the number include files that were encountered 2576 * during load. If the number is greater than zero, 'includesp' 2577 * will point to an array containing the filenames. 2578 * 2579 * The array and its contents need to be freed using isc_mem_free. 2580 */ 2581 2582 isc_result_t 2583 dns_zone_rpz_enable(dns_zone_t *zone, dns_rpz_zones_t *rpzs, 2584 dns_rpz_num_t rpz_num); 2585 /*% 2586 * Set the response policy associated with a zone. 2587 */ 2588 2589 void 2590 dns_zone_rpz_enable_db(dns_zone_t *zone, dns_db_t *db); 2591 /*% 2592 * If a zone is a response policy zone, mark its new database. 2593 */ 2594 2595 dns_rpz_num_t 2596 dns_zone_get_rpz_num(dns_zone_t *zone); 2597 2598 void 2599 dns_zone_catz_enable(dns_zone_t *zone, dns_catz_zones_t *catzs); 2600 /*%< 2601 * Enable zone as catalog zone. 2602 * 2603 * Requires: 2604 * 2605 * \li 'zone' is a valid zone object 2606 * \li 'catzs' is not NULL 2607 * \li prior to calling, zone->catzs is NULL or is equal to 'catzs' 2608 */ 2609 2610 void 2611 dns_zone_catz_disable(dns_zone_t *zone); 2612 /*%< 2613 * Disable zone as catalog zone, if it is one. 2614 * 2615 * Requires: 2616 * 2617 * \li 'zone' is a valid zone object 2618 */ 2619 2620 bool 2621 dns_zone_catz_is_enabled(dns_zone_t *zone); 2622 /*%< 2623 * Return a boolean indicating whether the zone is enabled as catalog zone. 2624 * 2625 * Requires: 2626 * 2627 * \li 'zone' is a valid zone object 2628 */ 2629 2630 void 2631 dns_zone_catz_enable_db(dns_zone_t *zone, dns_db_t *db); 2632 /*%< 2633 * If 'zone' is a catalog zone, then set up a notify-on-update trigger 2634 * in its database. (If not a catalog zone, this function has no effect.) 2635 * 2636 * Requires: 2637 * 2638 * \li 'zone' is a valid zone object 2639 * \li 'db' is not NULL 2640 */ 2641 void 2642 dns_zone_set_parentcatz(dns_zone_t *zone, dns_catz_zone_t *catz); 2643 /*%< 2644 * Set parent catalog zone for this zone 2645 * 2646 * Requires: 2647 * 2648 * \li 'zone' is a valid zone object 2649 * \li 'catz' is not NULL 2650 */ 2651 2652 dns_catz_zone_t * 2653 dns_zone_get_parentcatz(const dns_zone_t *zone); 2654 /*%< 2655 * Get parent catalog zone for this zone 2656 * 2657 * Requires: 2658 * 2659 * \li 'zone' is a valid zone object 2660 */ 2661 2662 void 2663 dns_zone_setstatlevel(dns_zone_t *zone, dns_zonestat_level_t level); 2664 2665 dns_zonestat_level_t 2666 dns_zone_getstatlevel(dns_zone_t *zone); 2667 /*% 2668 * Set and get the statistics reporting level for the zone; 2669 * full, terse, or none. 2670 */ 2671 2672 isc_result_t 2673 dns_zone_setserial(dns_zone_t *zone, uint32_t serial); 2674 /*% 2675 * Set the zone's serial to 'serial'. 2676 */ 2677 ISC_LANG_ENDDECLS 2678 2679 isc_stats_t * 2680 dns_zone_getgluecachestats(dns_zone_t *zone); 2681 /*%< 2682 * Get the glue cache statistics for zone. 2683 * 2684 * Requires: 2685 * \li 'zone' to be a valid zone. 2686 * 2687 * Returns: 2688 * \li if present, a pointer to the statistics set installed in zone; 2689 * otherwise NULL. 2690 */ 2691 2692 bool 2693 dns_zone_isloaded(dns_zone_t *zone); 2694 /*%< 2695 * Return true if 'zone' was loaded and has not expired yet, return 2696 * false otherwise. 2697 */ 2698 2699 isc_result_t 2700 dns_zone_verifydb(dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *ver); 2701 /*%< 2702 * If 'zone' is a mirror zone, perform DNSSEC validation of version 'ver' of 2703 * its database, 'db'. Ensure that the DNSKEY RRset at zone apex is signed by 2704 * at least one trust anchor specified for the view that 'zone' is assigned to. 2705 * If 'ver' is NULL, use the current version of 'db'. 2706 * 2707 * If 'zone' is not a mirror zone, return ISC_R_SUCCESS immediately. 2708 * 2709 * Returns: 2710 * 2711 * \li #ISC_R_SUCCESS either 'zone' is not a mirror zone or 'zone' is 2712 * a mirror zone and all DNSSEC checks succeeded 2713 * and the DNSKEY RRset at zone apex is signed by 2714 * a trusted key 2715 * 2716 * \li #DNS_R_VERIFYFAILURE any other case 2717 */ 2718 2719 const char * 2720 dns_zonetype_name(dns_zonetype_t type); 2721 /*%< 2722 * Return the name of the zone type 'type'. 2723 */ 2724 2725 #endif /* DNS_ZONE_H */ 2726