dns-server@2016-08-03.yang 23.4 KB
Newer Older
Pavel Spirek's avatar
Pavel Spirek committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
module dns-server {

  yang-version "1.1";

  namespace "http://www.nic.cz/ns/yang/dns-server";

  prefix "dnss";

  import ietf-inet-types {
    prefix "inet";
  }

  import ietf-yang-types {
    prefix "yang";
  }

  import dns-parameters {
    prefix "dnspars";
  }

  import tsig-algorithms {
    prefix "tsig";
  }

  organization
    "CZ.NIC, z. s. p. o.";

  contact
    "Editor:   Ladislav Lhotka
               <mailto:lhotka@nic.cz>";

  description
    "This YANG module defines the data model for an authoritative DNS
     server.";

36
  revision 2016-08-03 {
Pavel Spirek's avatar
Pavel Spirek committed
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193
    description
      "Initial revision.";
    reference
      "TODO: put git tag here";
  }

  /* Features */

  feature acl-entry-port {
    description
      "This feature indicates support for specifying a port number in
       access control entries.";
  }

  feature any-to-tcp {
    description
      "This feature indicates support for answering ANY queries over
       UDP with an empty response and TC bit set.";
  }

  feature journal-from-differences {
    description
      "This feature indicates support for generating a set of
       differences from two versions of full zone file.";
  }

  /* Identities */

  identity query-module-type {
    description
      "Base identity from which query module types are derived.";
  }

  /* Typedefs */

  typedef rr-ttl {
    type int32 {
      range "0..max";
    }
    units "seconds";
    description
      "This type is used for TTL values of DNS resource records.";
  }

  typedef packet-type {
    type enumeration {
      enum invalid {
        description
          "Invalid packet";
      }
      enum normal {
        description
          "Normal DNS query";
      }
      enum axfr {
        description
          "Authoritative zone transfer";
      }
      enum ixfr {
        description
          "Incremental zone transfer";
      }
      enum notify {
        description
          "NOTIFY message";
      }
      enum update {
        description
          "UPDATE message";
      }
    }
    description
      "This type defines an enumeration for types of packets received
       by a DNS server.";
  }

  typedef fs-path {
    type string;
    description
      "This type is used for specifying a filesystem path (absolute
       or relative).

       An implementation must check that the string satisfies all
       rules of the underlying operating system.";
  }

  typedef acl-ref {
    type leafref {
      path "/dnss:dns-server/dnss:access-control-list/dnss:name";
    }
    description
      "This type is used for referring to a configured access control
       list.";
  }

  typedef key-ref {
    type leafref {
      path "/dnss:dns-server/dnss:key/dnss:name";
    }
    description
      "This type is used for referring to a configured TSIG key.";
  }

  typedef remote-ref {
    type leafref {
      path "/dnss:dns-server/dnss:remote-server/dnss:name";
    }
    description
      "This type is used for referring to a configured remote
       server.";
  }

  typedef zone-ref {
    type leafref {
      path "/dnss:dns-server/dnss:zones/dnss:zone/dnss:domain";
    }
    description
      "This type is used for referring to a configured zone.";
  }

  /* Groupings */

  grouping counter64 {
    description
      "This grouping defines a 64-bit zero-based counter.";
    leaf count {
      type yang:zero-based-counter64;
      default "0";
      description
        "64-bit zero based counter.";
    }
  }

  grouping endpoint-address {
    description
      "This grouping defines a TCP/IP endpoint address, i.e., the
       combination of an IP address and port number.";
    leaf ip-address {
      type inet:ip-address;
      mandatory "true";
      description
        "IPv4/IPv6 address.";
    }
    leaf port {
      type inet:port-number;
      description
        "Port number.";
    }
  }

  grouping entry-name {
    description
      "This grouping defines a leaf that is intended for use as a
       list key.";
    leaf name {
      type string;
      description
194
        "Name of a list entry.";
Pavel Spirek's avatar
Pavel Spirek committed
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918
    }
  }

  grouping acls {
    description
      "This grouping defines a list of ACL references.";
    leaf-list access-control-list {
      type acl-ref;
      description
        "List of references to access control lists.";
    }
  }

  grouping description {
    description
      "This grouping defines 'description' leaf that can be added to
       various objects.";
    leaf description {
      type string;
      description
        "Textual description of an object.";
    }
  }

  grouping pid {
    description
      "This grouping defines PID leaf for use in RPC replies.";
    leaf pid {
      type uint32;
      mandatory "true";
      description
        "Return PID of the DNS server process.";
    }
  }

  /* State data */

  container dns-server-state {
    config "false";
    description
      "Operational state of the name server.";
    container server {
      description
        "State data of the server process.";
      leaf boot-time {
        type yang:date-and-time;
        mandatory "true";
        description
          "Time when the DNS server was started.";
      }
      leaf config-time {
        type yang:date-and-time;
        mandatory "true";
        description
          "Time when the DNS server was last (re)configured.";
      }
    }
    list zone {
      key "domain";
      description
        "State data of a zone.";
      leaf domain {
        type inet:domain-name;
        description
          "Zone name.";
      }
      leaf class {
        type dnspars:dns-class;
        default "IN";
        description
          "DNS class of the zone.";
      }
      leaf server-role {
        type enumeration {
          enum master {
            description
              "Master for the zone.";
          }
          enum slave {
            description
              "Slave for the zone.";
          }
        }
        mandatory "true";
        description
          "The role of the server for the parent zone.";
      }
      leaf serial {
        type uint32;
        mandatory "true";
        description
          "Zone's SOA serial number.";
      }
      container statistics {
        description
          "Zone statistics.";
        container opcodes {
          description
            "Opcode statistics.";
          list opcode-count {
            key "opcode";
            description
              "Each entry gives the count of queries with the given
               opcode.";
            leaf opcode {
              type dnspars:dns-opcode;
              description
                "DNS opcode.";
            }
            uses counter64;
          }
        }
        container rcodes {
          description
            "Rcode statistics.";
          list rcode-count {
            key "rcode";
            description
              "Each entry gives the count of responses with the given
               rcode.";
            leaf rcode {
              type dnspars:dns-rcode;
              description
                "DNS rcode.";
            }
            uses counter64;
          }
        }
        container packets {
          description
            "Packet statistics.";
          list packet-count {
            key "packet-type";
            description
              "Each entry gives the count of packets of the given
               type.";
            leaf packet-type {
              type packet-type;
              description
                "DNS packet type.";
            }
            uses counter64;
          }
        }
      }
    }
  }

  /* Configuration data */

  container dns-server {
    description
      "Configuration of a DNS server.";
    uses description;
    container server-options {
      description
        "Configuration of global server options.";
      uses description;
      container chaos-identity {
        presence "report server identity to CHAOS queries";
        description
          "Presence of this container enables reporting server
           identity in response to queries in the CHAOS class.";
        reference
          "RFC 4892: Requirements for a Mechanism Identifying a Name
           Server Instance.";
        leaf id-server {
          type string;
          description
            "Server identitity string sent in response to queries for
             ID.SERVER or BIND.HOSTNAME resource in the CHAOS class.

             Default: FQDN of the server.";
        }
        leaf version {
          type string;
          description
            "Server software version sent in response to queries for
             VERSION.SERVER or VERSION.BIND resource in the CHAOS
             class.

             Default: implementation-specific string.";
        }
      }
      container nsid-identity {
        presence "report server identity to NSID query";
        description
          "Presence of this container enables reporting server
           identity string in response to EDNS NSID query.";
        reference
          "RFC 5001: DNS Name Server Identifier (NSID) Option.";
        leaf nsid {
          type string;
          description
            "Server identitity string.

             Default: FQDN of the server.";
        }
      }
      list listen-endpoint {
        key "name";
        unique "ip-address port";
        description
          "List of IP addresses and optional ports on which the
           server listens.

           If the 'ip-address' value is '0.0.0.0' (for IPv4) and/or
           '::', the server listens on all configured IPv4/IPv6
           addresses that are not explicitly configured in this
           list.";
        uses entry-name;
        uses endpoint-address {
          refine "port" {
            default "53";
          }
        }
      }
      container resources {
        description
          "Configuration of server resources.";
        leaf max-tcp-clients {
          type uint16;
          default "100";
          description
            "Maximum number of simultaneous TCP client
             connections.";
        }
        leaf max-udp-size {
          type uint16;
          default "4096";
          description
            "Maximum size of a UDP datagram with EDNS0 extensions.";
        }
      }
      container filesystem-paths {
        description
          "Configuration of directories and file paths.";
        leaf run-time-dir {
          type fs-path;
          description
            "Default location of various run-time files such as PID
             file.

             Default: implementation specific.";
        }
        leaf pid-file {
          type fs-path;
          description
            "Path of the PID file.

             If the path is relative, the value of 'run-time-dir' is
             prepended to it.

             Default: implementation specific.";
        }
      }
      container privileges {
        presence "process owner (and group)";
        description
          "Parameters in this container can be used to run the server
           with less privileges. The server MUST switch to the
           corresponding UID/GID immediately after binding to
           privileged ports.";
        leaf user {
          type string;
          mandatory "true";
          description
            "User name.";
        }
        leaf group {
          type string;
          description
            "Group name.";
        }
      }
      container response-rate-limiting {
        presence "enable RRL";
        description
          "Configuration of Response Rate Limiting that is used to
           prevent/mitigate DNS reflection and amplification
           attacks.";
        reference
          "http://ss.vix.su/~vixie/isc-tn-2012-1.txt";
        leaf responses-per-second {
          type uint16;
          default "5";
          description
            "Maximum number of times that the a set of related
             requestors is sent the same answer within a one-second
             interval.

             The sets of related requestors are determined based on
             an implementation-specific classification scheme, which
             typically involves several query parameters such as
             source address prefix, query type, domain name or rcode.

             Queries that exceed the limit are either discarded or
             replied with a SLIP response that has the TC bit set and
             thus instructs the requestor to switch to TCP.

             The value of zero means no rate limit.";
        }
        leaf slip {
          type uint8;
          default "1";
          description
            "If this parameter is set to N, then every Nth response
             that doesn't pass the rate limit check is sent as the
             SLIP message instead of being discarded.

             The value of zero turns the SLIP feature off.";
        }
        leaf table-size {
          type uint32;
          description
            "The size of the (hash) table, i.e., the number of
             classification buckets that the server keeps in
             memory.";
        }
      }
    }
    list access-control-list {
      key "name";
      description
        "Access control lists.";
      uses entry-name;
      uses description;
      list network {
        key "name";
        unique "ip-prefix port";
        description
          "Identification of a network.";
        uses entry-name;
        leaf ip-prefix {
          type inet:ip-prefix;
          mandatory "true";
          description
            "IPv4 or IPv6 prefix in the usual ADDRESS/LENGTH
             notation.";
        }
        leaf port {
          when "../ip-prefix" {
            description
              "Port is valid only if the ACL entry specifies an IP
               prefix.";
          }
          if-feature acl-entry-port;
          type inet:port-number;
          description
            "Port associated with the access control entry.";
        }
      }
      leaf-list key {
        type key-ref;
        description
          "List of TSIG keys associated with the access control
           entry.";
      }
      leaf-list operation {
        type enumeration {
          enum transfer {
            description
              "Transfer operation";
          }
          enum notify {
            description
              "Notify operation";
          }
          enum update {
            description
              "Update operation";
          }
          enum control {
            description
              "Control operation";
          }
        }
        min-elements "1";
        description
          "Operations to which the ACL is applied.";
      }
      leaf action {
        type enumeration {
          enum allow {
            description
              "Allow action";
          }
          enum deny {
            description
              "Deny action";
          }
        }
        default "allow";
        description
          "ACL action.";
      }
    }
    list remote-server {
      key "name";
      description
        "Definitions of remote servers.";
      uses entry-name;
      uses description;
      container remote {
        description
          "Parameters of the remote server.";
        uses endpoint-address {
          refine "port" {
            default "53";
          }
        }
      }
      container local {
        presence "local endpoint address";
        description
          "Source address and port of the local server.

           If not configured, the normal operating system's source
           address and port selection is applied.";
        uses endpoint-address;
      }
      leaf key {
        type key-ref;
        description
          "TSIG key associated with the remote server.";
      }
    }
    list key {
      key "name";
      description
        "Definitions of TSIG keys.";
      uses entry-name;
      uses description;
      leaf algorithm {
        type identityref {
          base tsig:tsig-algorithm;
        }
        default "tsig:HMAC-MD5.SIG-ALG.REG.INT";
        description
          "Authentication algorithm for this key.";
      }
      leaf secret {
        type binary;
        mandatory "true";
        description
          "The shared secret.";
      }
    }
    list query-module {
      key "type name";
      ordered-by "user";
      description
        "Configurations of query modules that implement special
         server behavior in response to certain queries.

         Configuration parameters for a particular module are
         expected to be added via augmentation, and inside a
         container with presence.";
      leaf type {
        type identityref {
          base dnss:query-module-type;
        }
        description
          "Query module type.";
      }
      uses entry-name;
      uses description;
    }
    container zones {
      must "count(template[default='true']) <= 1" {
        error-message "Multiple default zone templates.";
        description
          "No more than one template may be designated as default.";
      }
      description
        "Configuration of zones.";
      grouping zone-options {
        description
          "This grouping defines zone options that are used both in
           the configuration of zones and templates.";
        uses description;
        leaf zones-dir {
          type fs-path;
          description
            "Filesystem directory where zone files are stored.

             Default: implementation specific.";
        }
        leaf file {
          type fs-path;
          description
            "Path to zone file.

             If the path is relative, the value of 'zones-dir' is
             prepended to it.

             Default: implementation specific.

             The following substitutions are supported:

             - '%s' is replaced with the current zone name.

             - '%%' is replaced with a single percent sign.";
        }
        leaf-list master {
          type remote-ref;
          description
            "List of references to master servers for the zone from
             which the local server receives zone data via
             AXFR/IXFR.";
        }
        container notify {
          description
            "Configuration of NOTIFY messages.";
          reference
            "RFC 1996: A Mechanism for Prompt Notification of Zone
             Changes (DNS NOTIFY).";
          leaf-list recipient {
            type remote-ref;
            description
              "List of references to NOTIFY recipients.";
          }
        }
        uses acls {
          description
            "Access control lists applied for the zone.";
        }
        leaf serial-update-method {
          type enumeration {
            enum increment {
              description
                "Increment the zone number by one.";
            }
            enum unix-time {
              description
                "Set the serial number to the number of seconds since
                 Unix epoch.

                 If the serial number is already greater than this
                 value, fall back to the 'increment' method.";
            }
          }
          default "increment";
          description
            "Specify the method for updating the zone serial method
             after a dynamic update or automatic zone signing.";
        }
        leaf any-to-tcp {
          if-feature any-to-tcp;
          type boolean;
          default "false";
          description
            "If this flag is on, ANY queries to this zone sent over
             UDP are served with an empty reply that has the TC bit
             on.";
        }
        container journal {
          description
            "Zone journal parameters.";
          leaf maximum-journal-size {
            type uint64;
            units "bytes";
            description
              "Maximum size of the zone journal file.

               Default: no limit, i.e., maximum size supported by an
               implementation.";
          }
          leaf zone-file-sync-delay {
            type uint32;
            units "seconds";
            default "0";
            description
              "Delay between first zone change via IXFR, DDNS or
               automatic DNSSEC signing, and recording the changes to
               the zone file.

               The value of 0 means no delay, i.e., changes are
               recorded immediately.";
          }
          leaf from-differences {
            if-feature journal-from-differences;
            type boolean;
            default "false";
            description
              "When 'true' and either a new version of a master zone
               is reloaded from the zone file, or a new version of a
               slave zone is received via zone transfer, the server
               will calculate the differences and record them in the
               journal.";
          }
        }
        list query-module {
          key "type name";
          ordered-by "user";
          description
            "A user-ordered list of references to configured query
             modules.

             The modules shall be applied to queries for the current
             zone in the specified order.";
          leaf type {
            type leafref {
              path "/dns-server/query-module/type";
            }
            description
              "Type of the query module";
          }
          leaf name {
            type leafref {
              path "/dns-server/query-module[type=current()/../"
                 + "type]/name";
            }
            description
              "Name of the query module.";
          }
        }
      }
      list template {
        key "name";
        description
          "List of zone configuration templates.";
        uses entry-name;
        leaf default {
          type boolean;
          default "false";
          description
            "This flag indicates the default template.";
        }
        uses zone-options;
      }
      list zone {
        key "domain";
        description
          "List of zones.";
        leaf domain {
          type inet:domain-name;
          description
            "Zone name.";
        }
        leaf template {
          type leafref {
            path "/dns-server/zones/template/name";
          }
          description
            "Reference to a configured zone template.";
        }
        uses zone-options;
      }
    }
  }

  /* Operations */

  rpc start-server {
    description
      "Start the DNS server, or do nothing if it is already
       running.";
    output {
      uses pid;
    }
  }

  rpc stop-server {
    description
      "Stop the DNS server, or do nothing if it is not running.";
  }

  rpc restart-server {
    description
      "Restart the DNS server, which is equivalent to executing
       'stop-server' and 'start-server' in sequence.";
    output {
      uses pid;
    }
  }

  rpc reload-server {
    description
      "Reload server configuration.";
  }

  rpc zone-reload {
    description
      "Reload specified zones.";
    input {
      leaf-list zones {
        type zone-ref;
        description
          "Domain names of the zones to be reloaded.";
      }
    }
  }

  rpc zone-refresh {
    description
      "Refresh slave zones.";
    input {
      leaf-list zones {
        type zone-ref;
        description
          "Domain names of the zones to be refreshed.";
      }
      leaf force-retransfer {
        type boolean;
        default "false";
        description
          "Setting this parameter to true forces retransfer.";
      }
    }
  }

  rpc zone-flush {
    description
      "Flush journal and update zone files.";
    input {
      leaf-list zones {
        type zone-ref;
        description
          "Domain names of the zones to be flushed.";
      }
    }
  }
}