idnits 2.17.1 draft-ietf-netmod-system-mgmt-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 229 has weird spacing: '...address ine...' == Line 251 has weird spacing: '...rw name str...' == Line 255 has weird spacing: '...address ine...' == Line 321 has weird spacing: '...gorithm str...' == Line 604 has weird spacing: '...atabase http:...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 4, 2013) is 3948 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-03) exists of draft-ietf-netmod-iana-timezones-00 -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE-1003.1-2008' ** Downref: Normative reference to an Informational RFC: RFC 1321 ** Obsolete normative reference: RFC 5966 (Obsoleted by RFC 7766) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 3 errors (**), 0 flaws (~~), 8 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Intended status: Standards Track M. Bjorklund 5 Expires: January 5, 2014 Tail-f Systems 6 July 4, 2013 8 YANG Data Model for System Management 9 draft-ietf-netmod-system-mgmt-08 11 Abstract 13 This document defines a YANG data model for the configuration and 14 identification of some common system properties within a device 15 containing a NETCONF server. This includes data node definitions for 16 system identification, time-of-day management, user management, DNS 17 resolver configuration, and some protocol operations for system 18 management. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on January 5, 2014. 37 Copyright Notice 39 Copyright (c) 2013 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 2.1. System Identification . . . . . . . . . . . . . . . . . . 5 59 2.2. System Time Management . . . . . . . . . . . . . . . . . . 5 60 2.3. User Authentication . . . . . . . . . . . . . . . . . . . 5 61 2.4. DNS Resolver . . . . . . . . . . . . . . . . . . . . . . . 5 62 2.5. System Control . . . . . . . . . . . . . . . . . . . . . . 6 63 3. System Data Model . . . . . . . . . . . . . . . . . . . . . . 7 64 3.1. System Identification . . . . . . . . . . . . . . . . . . 7 65 3.2. System Time Management . . . . . . . . . . . . . . . . . . 7 66 3.3. DNS Resolver Model . . . . . . . . . . . . . . . . . . . . 8 67 3.4. RADIUS Client Model . . . . . . . . . . . . . . . . . . . 8 68 3.5. User Authentication Model . . . . . . . . . . . . . . . . 9 69 3.5.1. SSH Public Key Authentication . . . . . . . . . . . . 9 70 3.5.2. Local User Password Authentication . . . . . . . . . . 10 71 3.5.3. RADIUS Password Authentication . . . . . . . . . . . . 10 72 3.6. System Control . . . . . . . . . . . . . . . . . . . . . . 10 73 4. System YANG module . . . . . . . . . . . . . . . . . . . . . . 11 74 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 75 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 76 7. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 32 77 7.1. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 78 7.2. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 79 7.3. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 80 7.4. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 81 7.5. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 82 7.6. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 33 83 7.7. 06-07 . . . . . . . . . . . . . . . . . . . . . . . . . . 33 84 7.8. 07-08 . . . . . . . . . . . . . . . . . . . . . . . . . . 34 85 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 35 86 8.1. Normative References . . . . . . . . . . . . . . . . . . . 35 87 8.2. Informative References . . . . . . . . . . . . . . . . . . 36 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 37 90 1. Introduction 92 This document defines a YANG [RFC6020] data model for the 93 configuration and identification of some common properties within a 94 device containing a NETCONF server. 96 Devices that are managed by NETCONF and perhaps other mechanisms have 97 common properties that need to be configured and monitored in a 98 standard way. 100 The "ietf-system" YANG module defined in this document provides the 101 following features: 103 o system identification configuration and monitoring 105 o system time-of-day configuration and monitoring 107 o user authentication configuration 109 o local users configuration 111 o DNS resolver configuration 113 o system control operations (shutdown, restart, setting time) 115 1.1. Terminology 117 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 119 "OPTIONAL" in this document are to be interpreted as described in BCP 120 14, [RFC2119]. 122 1.2. Tree Diagrams 124 A simplified graphical representation of the data model is used in 125 this document. The meaning of the symbols in these diagrams is as 126 follows: 128 o Brackets "[" and "]" enclose list keys. 130 o Abbreviations before data node names: "rw" means configuration 131 (read-write) and "ro" state data (read-only). 133 o Symbols after data node names: "?" means an optional node and "*" 134 denotes a "list" and "leaf-list". 136 o Parentheses enclose choice and case nodes, and case nodes are also 137 marked with a colon (":"). 139 o Ellipsis ("...") stands for contents of subtrees that are not 140 shown. 142 2. Objectives 144 2.1. System Identification 146 There are many common properties used to identify devices, operating 147 systems, software versions, etc. that need to be supported in the 148 system data module. These objects are defined as operational state 149 data and the information returned by the server is intended to be 150 specific to the device vendor. 152 Some user-configurable administrative strings are also provided, such 153 as the system location and description. 155 2.2. System Time Management 157 The management of the date and time used by the system need to be 158 supported. Use of one or more NTP servers to automatically set the 159 system date and time need to be possible. Utilization of the 160 Timezone database [RFC6557] also need to be supported. It should be 161 possible for the server, as well as clients, to configure the system 162 to use NTP. 164 2.3. User Authentication 166 The authentication mechanism need to support password authentication 167 over RADIUS, to support deployment scenarios with centralized 168 authentication servers. Additionally, local users need to be 169 supported, for scenarios when no centralized authentication server 170 exists, or for situations where the centralized authentication server 171 cannot be reached from the device. 173 Since the mandatory transport protocol for NETCONF is SSH [RFC6242] 174 the authentication model need to support SSH's "publickey" and 175 "password" authentication methods [RFC4252]. 177 The model for authentication configuration should be flexible enough 178 to support authentication methods defined by other standard documents 179 or by vendors. It should be possible for the server, as well as 180 clients, to configure the system authentication properties. 182 2.4. DNS Resolver 184 The configuration of the DNS resolver within the system containing 185 the NETCONF server is required to control how domain names are 186 resolved. 188 2.5. System Control 190 A few operations are needed to support common tasks such as 191 restarting the device or setting the system date and time. 193 3. System Data Model 195 3.1. System Identification 197 The data model for system identification has the following structure: 199 +--rw system 200 | +--rw contact? string 201 | +--rw hostname? inet:domain-name 202 | +--rw location? string 203 +--ro system-state 204 +--ro platform 205 +--ro os-name? string 206 +--ro os-release? string 207 +--ro os-version? string 208 +--ro machine? string 210 3.2. System Time Management 212 The data model for system time management has the following 213 structure: 215 +--rw system 216 | +--rw clock 217 | | +--rw (timezone)? 218 | | +--:(timezone-location) 219 | | | +--rw timezone-location? ianatz:iana-timezone 220 | | +--:(timezone-utc-offset) 221 | | +--rw timezone-utc-offset? int16 222 | +--rw ntp 223 | +--rw enabled? boolean 224 | +--rw server* [name] 225 | +--rw name string 226 | +--rw (transport) 227 | | +--:(udp) 228 | | +--rw udp 229 | | +--rw address inet:host 230 | | +--rw port? inet:port-number 231 | +--rw association-type? enumeration 232 | +--rw iburst? boolean 233 | +--rw prefer? boolean 234 +--ro system-state 235 +--ro clock 236 +--ro current-datetime? yang:date-and-time 237 +--ro boot-datetime? yang:date-and-time 239 New "case" statements can be added over time or augmented to the 240 "transport" choice to support other transport protocols. 242 3.3. DNS Resolver Model 244 The data model for configuration of the DNS resolver has the 245 following structure: 247 +--rw system 248 +--rw dns-resolver 249 +--rw search* inet:domain-name 250 +--rw server* [name] 251 | +--rw name string 252 | +--rw (transport) 253 | +--:(udp-and-tcp) 254 | +--udp-and-tcp 255 | +--rw address inet:ip-address 256 | +--rw port? inet:port-number 257 +--rw options 258 +--rw timeout? uint8 259 +--rw attempts? uint8 261 New "case" statements can be added over time or augmented to the 262 "transport" choice to support other transport protocols. 264 3.4. RADIUS Client Model 266 The data model for configuration of the RADIUS client has the 267 following structure: 269 +--rw system 270 +--rw radius 271 +--rw server* [name] 272 | +--rw name string 273 | +--rw (transport) 274 | | +--:(udp) 275 | | +--rw udp 276 | | +--rw address inet:host 277 | | +--rw authentication-port? inet:port-number 278 | | +--rw shared-secret string 279 | +--rw authentication-type? identityref 280 +--rw options 281 +--rw timeout? uint8 282 +--rw attempts? uint8 284 New "case" statements can be added over time or augmented to the 285 "transport" choice to support other transport protocols. 287 3.5. User Authentication Model 289 This document defines three authentication methods for use with 290 NETCONF: 292 o publickey for local users over SSH 294 o password for local users over any transport 296 o password for RADIUS users over any transport 298 Additional methods can be defined by other standard documents or by 299 vendors. 301 This document defines two optional YANG features, "local-users" and 302 "radius-authentication", which the server advertises to indicate 303 support for configuring local users on the device, and support for 304 using RADIUS for authentication, respectively. 306 The authentication parameters defined in this document are primarily 307 used to configure authentication of NETCONF users, but MAY also be 308 used by other interfaces, e.g., a Command Line Interface or a Web- 309 based User Interface. 311 The data model for user authentication has the following structure: 313 +--rw system 314 +--rw authentication 315 +--rw user-authentication-order* identityref 316 +--rw user* [name] 317 +--rw name string 318 +--rw password? crypt-hash 319 +--rw ssh-key* [name] 320 +--rw name string 321 +--rw algorithm string 322 +--rw key-data binary 324 3.5.1. SSH Public Key Authentication 326 If the NETCONF server advertises the "local-users" feature, 327 configuration of local users and their SSH public keys is supported 328 in the /system/authentication/user list. 330 Public key authentication is requested by the SSH client. If the 331 "local-users" feature is supported, then when a NETCONF client starts 332 an SSH session towards the server using the "publickey" 333 authentication "method name" [RFC4252], the SSH server looks up the 334 user name given in the SSH authentication request in the /system/ 335 authentication/user list, and verifies the key as described in 336 [RFC4253]. 338 3.5.2. Local User Password Authentication 340 If the NETCONF server advertises the "local-users" feature, 341 configuration of local users and their passwords is supported in the 342 /system/authentication/user list. 344 For NETCONF transport protocols that support password authentication, 345 the leaf-list "user-authentication-order" is used to control if local 346 user password authentication should be used. 348 In SSH, password authentication is requested by the client. Other 349 NETCONF transport protocols MAY also support password authentication. 351 When local user password authentication is requested, the NETCONF 352 transport looks up the user name provided by the client in the 353 /system/authentication/user list, and verifies the password. 355 3.5.3. RADIUS Password Authentication 357 If the NETCONF server advertises the "radius-authentication" feature, 358 the device supports user authentication using RADIUS. 360 For NETCONF transport protocols that support password authentication, 361 the leaf-list "user-authentication-order" is used to control if 362 RADIUS password authentication should be used. 364 In SSH, password authentication is requested by the client. Other 365 NETCONF transport protocols MAY also support password authentication. 367 3.6. System Control 369 Two protocol operations are included to restart or shutdown the 370 system. The 'system-restart' operation can be used to restart the 371 entire system (not just the NETCONF server). The 'system-shutdown' 372 operation can be used to power off the entire system. 374 4. System YANG module 376 This YANG module imports YANG extensions from [RFC6536], and imports 377 YANG types from [I-D.ietf-netmod-rfc6021-bis] and 378 [I-D.ietf-netmod-iana-timezones]. It also references [RFC1035], 379 [RFC1321], [RFC2865], [RFC3418], [RFC5607], [RFC5966], 380 [IEEE-1003.1-2008], and [FIPS.180-3.2008]. 382 RFC Ed.: update the date below with the date of RFC publication and 383 remove this note. 385 file "ietf-system@2013-07-04.yang" 387 module ietf-system { 388 namespace "urn:ietf:params:xml:ns:yang:ietf-system"; 389 prefix "sys"; 391 import ietf-yang-types { 392 prefix yang; 393 } 395 import ietf-inet-types { 396 prefix inet; 397 } 399 import ietf-netconf-acm { 400 prefix nacm; 401 } 403 import iana-timezones { 404 prefix ianatz; 405 } 407 organization 408 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 410 contact 411 "WG Web: 412 WG List: 414 WG Chair: David Kessens 415 417 WG Chair: Juergen Schoenwaelder 418 420 Editor: Andy Bierman 421 423 Editor: Martin Bjorklund 424 "; 426 description 427 "This module contains a collection of YANG definitions for the 428 configuration and identification of some common system 429 properties within a device containing a NETCONF server. This 430 includes data node definitions for system identification, 431 time-of-day management, user management, DNS resolver 432 configuration, and some protocol operations for system 433 management. 435 Copyright (c) 2013 IETF Trust and the persons identified as 436 authors of the code. All rights reserved. 438 Redistribution and use in source and binary forms, with or 439 without modification, is permitted pursuant to, and subject 440 to the license terms contained in, the Simplified BSD License 441 set forth in Section 4.c of the IETF Trust's Legal Provisions 442 Relating to IETF Documents 443 (http://trustee.ietf.org/license-info). 445 This version of this YANG module is part of RFC XXXX; see 446 the RFC itself for full legal notices."; 448 // RFC Ed.: replace XXXX with actual RFC number and remove this 449 // note. 451 // RFC Ed.: remove this note 452 // Note: extracted from draft-ietf-netmod-system-mgmt-07.txt 454 // RFC Ed.: update the date below with the date of RFC publication 455 // and remove this note. 456 revision "2013-07-04" { 457 description 458 "Initial revision."; 459 reference 460 "RFC XXXX: A YANG Data Model for System Management"; 461 } 463 /* 464 * Typedefs 465 */ 467 typedef crypt-hash { 468 type string { 469 pattern 470 '$0$.*' 472 + '|$1$[a-zA-Z0-9./]{1,8}$[a-zA-Z0-9./]{22}' 473 + '|$5$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{43}' 474 + '|$6$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{86}'; 475 } 476 description 477 "The crypt-hash type is used to store passwords using 478 a hash function. The algorithms for applying the hash 479 function and encoding the result are implemented in 480 various UNIX systems as the function crypt(3). 482 A value of this type matches one of the forms: 484 $0$ 485 $$$ 486 $$$$ 488 The '$0$' prefix signals that the value is clear text. When 489 such a value is received by the server, a hash value is 490 calculated, and the string '$$$' or 491 $$$$ is prepended to the result. This 492 value is stored in the configuration data store. 494 If a value starting with '$$', where is not '0', is 495 received, the server knows that the value already represents a 496 hashed value, and stores it as is in the data store. 498 When a server needs to verify a password given by a user, it 499 finds the stored password hash string for that user, extracts 500 the salt, and calculates the hash with the salt and given 501 password as input. If the calculated hash value is the same 502 as the stored value, the password given by the client is 503 accepted. 505 This type defines the following hash functions: 507 id | hash function | feature 508 ---+---------------+------------------- 509 1 | MD5 | crypt-hash-md5 510 5 | SHA-256 | crypt-hash-sha-256 511 6 | SHA-512 | crypt-hash-sha-512 513 The server indicates support for the different hash functions 514 by advertising the corresponding feature."; 515 reference 516 "IEEE Std 1003.1-2008 - crypt() function 517 Wikipedia: http://en.wikipedia.org/wiki/Crypt_(C) 518 RFC 1321: The MD5 Message-Digest Algorithm 519 FIPS.180-3.2008: Secure Hash Standard"; 521 } 523 /* 524 * Features 525 */ 527 feature radius { 528 description 529 "Indicates that the device can be configured as a RADIUS 530 client."; 531 reference 532 "RFC 2865: Remote Authentication Dial In User Service " 533 + "(RADIUS)"; 534 } 536 feature authentication { 537 description 538 "Indicates that the device supports configuration 539 for user authentication."; 540 } 542 feature local-users { 543 if-feature authentication; 544 description 545 "Indicates that the device supports configuration of 546 local user authentication."; 547 } 549 feature radius-authentication { 550 if-feature radius; 551 if-feature authentication; 552 description 553 "Indicates that the device supports configuration of user 554 authentication over RADIUS."; 555 reference 556 "RFC 2865: Remote Authentication Dial In User Service (RADIUS) 557 RFC 5607: Remote Authentication Dial-In User Service (RADIUS) 558 Authorization for Network Access Server (NAS) 559 Management"; 560 } 562 feature crypt-hash-md5 { 563 description 564 "Indicates that the device supports the MD5 565 hash function in 'crypt-hash' values"; 566 reference "RFC 1321: The MD5 Message-Digest Algorithm"; 567 } 568 feature crypt-hash-sha-256 { 569 description 570 "Indicates that the device supports the SHA-256 571 hash function in 'crypt-hash' values"; 572 reference "FIPS.180-3.2008: Secure Hash Standard"; 573 } 575 feature crypt-hash-sha-512 { 576 description 577 "Indicates that the device supports the SHA-512 578 hash function in 'crypt-hash' values"; 579 reference "FIPS.180-3.2008: Secure Hash Standard"; 580 } 582 feature ntp { 583 description 584 "Indicates that the device can be configured 585 to use one or more NTP servers to set the 586 system date and time."; 587 } 589 feature ntp-udp-port { 590 description 591 "Indicates that the device supports the configuration of 592 the UDP port for NTP servers. 594 This is a 'feature' since many implementations do not support 595 any other port than the default port."; 596 } 598 feature timezone-location { 599 description 600 "Indicates that the local timezone on the device 601 can be configured to use the TZ database 602 to set the timezone and manage daylight savings time."; 603 reference 604 "TZ Database http://www.twinsun.com/tz/tz-link.htm 605 Maintaining the Timezone Database 606 RFC 6557 (BCP 175)"; 607 } 609 feature dns-udp-tcp-port { 610 description 611 "Indicates that the device supports the configuration of 612 the UDP and TCP port for DNS servers. 614 This is a 'feature' since many implementations do not support 615 any other port than the default port."; 617 } 619 /* 620 * Identities 621 */ 623 identity authentication-method { 624 description 625 "Base identity for user authentication methods."; 626 } 628 identity radius { 629 base authentication-method; 630 description 631 "Indicates user authentication using RADIUS."; 632 reference 633 "RFC 2865: Remote Authentication Dial In User Service (RADIUS) 634 RFC 5607: Remote Authentication Dial-In User Service (RADIUS) 635 Authorization for Network Access Server (NAS) 636 Management"; 637 } 639 identity local-users { 640 base authentication-method; 641 description 642 "Indicates password-based authentication of locally 643 configured users."; 644 } 646 identity radius-authentication-type { 647 description 648 "Base identity for RADIUS authentication types."; 649 } 651 identity radius-pap { 652 base radius-authentication-type; 653 description 654 "The device requests PAP authentication from the RADIUS 655 server."; 656 reference 657 "RFC 2865: Remote Authentication Dial In User Service"; 658 } 660 identity radius-chap { 661 base radius-authentication-type; 662 description 663 "The device requests CHAP authentication from the RADIUS 664 server."; 666 reference 667 "RFC 2865: Remote Authentication Dial In User Service"; 668 } 670 /* 671 * Top-level container 672 */ 674 container system { 675 description 676 "System group configuration."; 678 leaf contact { 679 type string; 680 description 681 "The administrator contact information for the system. 682 The server MAY restrict the size and characters in 683 order to maintain compatibility with the sysContact 684 MIB object."; 685 reference 686 "RFC 3418 - Management Information Base (MIB) for the 687 Simple Network Management Protocol (SNMP) 688 SNMPv2-MIB.sysContact"; 689 } 690 leaf hostname { 691 type inet:domain-name; 692 description 693 "The name of the host. This name can be a single domain 694 label, or the fully qualified domain name of the host."; 695 } 696 leaf location { 697 type string; 698 description 699 "The system location. The server MAY restrict the size 700 and characters in order to maintain compatibility with 701 the sysLocation MIB object."; 702 reference 703 "RFC 3418 - Management Information Base (MIB) for the 704 Simple Network Management Protocol (SNMP) 705 SNMPv2-MIB.sysLocation"; 706 } 707 container clock { 708 description 709 "Configuration of the system date and time properties."; 711 choice timezone { 712 description 713 "The system timezone information."; 715 case timezone-location { 716 if-feature timezone-location; 717 leaf timezone-location { 718 type ianatz:iana-timezone; 719 description 720 "The TZ database location identifier string 721 to use for the system, such as 'Europe/Stockholm'."; 722 } 723 } 724 case timezone-utc-offset { 725 leaf timezone-utc-offset { 726 type int16 { 727 range "-1500 .. 1500"; 728 } 729 units "minutes"; 730 description 731 "The number of minutes to add to UTC time to 732 identify the timezone for this system. For example, 733 'UTC - 8:00 hours' would be represented as '-480'. 734 Note that automatic daylight savings time adjustment 735 is not provided, if this object is used."; 736 } 737 } 738 } 739 } 741 container ntp { 742 if-feature ntp; 743 description 744 "Configuration of the NTP client."; 746 leaf enabled { 747 type boolean; 748 default true; 749 description 750 "Indicates that the system should attempt 751 to synchronize the system clock with an 752 NTP server from the 'ntp/server' list."; 753 } 754 list server { 755 key name; 756 description 757 "List of NTP servers to use for 758 system clock synchronization. If '/system/ntp/enabled' 759 is 'true', then the system will attempt to 760 contact and utilize the specified NTP servers."; 762 leaf name { 763 type string; 764 description 765 "An arbitrary name for the NTP server."; 766 } 767 choice transport { 768 mandatory true; 769 description 770 "The transport protocol specific parameters for this 771 server."; 773 case udp { 774 container udp { 775 description 776 "Contains UDP specific configuration parameters 777 for NTP."; 778 leaf address { 779 type inet:host; 780 mandatory true; 781 description 782 "The address of the NTP server."; 783 } 784 leaf port { 785 if-feature ntp-udp-port; 786 type inet:port-number; 787 default 123; 788 description 789 "The port number of the NTP server."; 790 } 791 } 792 } 793 } 794 leaf association-type { 795 type enumeration { 796 enum server { 797 description 798 "Use client association mode. This device 799 will not provide synchronization to the 800 configured NTP server."; 801 } 802 enum peer { 803 description 804 "Use symmetric active association mode. 805 This device may provide synchronization 806 to the configured NTP server."; 807 } 808 enum pool { 809 description 810 "Use client association mode with one or 811 more of the NTP servers found by DNS 812 resolution of the domain name given by 813 the 'address' leaf. This device will not 814 provide synchronization to the servers."; 815 } 816 } 817 default server; 818 description 819 "The desired association type for this NTP server."; 820 } 821 leaf iburst { 822 type boolean; 823 default false; 824 description 825 "Indicates whether this server should enable burst 826 synchronization or not."; 827 } 828 leaf prefer { 829 type boolean; 830 default false; 831 description 832 "Indicates whether this server should be preferred 833 or not."; 834 } 835 } 836 } 838 container dns-resolver { 839 description 840 "Configuration of the DNS resolver."; 842 leaf-list search { 843 type inet:domain-name; 844 ordered-by user; 845 description 846 "An ordered list of domains to search when resolving 847 a host name."; 848 } 849 list server { 850 key name; 851 ordered-by user; 852 description 853 "List of the DNS servers that the resolver should query. 855 When the resolver is invoked by a calling application, it 856 sends the query to the first name server in this list. If 857 no response has been received within 'timeout' seconds, 858 the resolver continues with the next server in the list. 860 If no response is received from any server, the resolver 861 continues with the first server again. When the resolver 862 has traversed the list 'attempts' times without receiving 863 any response, it gives up and returns an error to the 864 calling application. 866 Implementations MAY limit the number of entries in this 867 list."; 869 leaf name { 870 type string; 871 description 872 "An arbitrary name for the DNS server."; 873 } 874 choice transport { 875 mandatory true; 876 description 877 "The transport protocol specific parameters for this 878 server."; 880 case udp-and-tcp { 881 container udp-and-tcp { 882 description 883 "Contains UDP and TCP specific configuration 884 parameters for DNS."; 885 reference 886 "RFC 1035: Domain Implementation and Specification 887 RFC 5966: DNS over TCP"; 889 leaf address { 890 type inet:ip-address; 891 mandatory true; 892 description 893 "The address of the DNS server."; 894 } 895 leaf port { 896 if-feature dns-udp-tcp-port; 897 type inet:port-number; 898 default 53; 899 description 900 "The UDP and TCP port number of the DNS server."; 901 } 902 } 903 } 904 } 905 } 906 container options { 907 description 908 "Resolver options. The set of available options has been 909 limited to those that are generally available across 910 different resolver implementations, and generally 911 useful."; 912 leaf timeout { 913 type uint8 { 914 range "1..max"; 915 } 916 units "seconds"; 917 default "5"; 918 description 919 "The amount of time the resolver will wait for a 920 response from each remote name server before 921 retrying the query via a different name server."; 922 } 923 leaf attempts { 924 type uint8 { 925 range "1..max"; 926 } 927 default "2"; 928 description 929 "The number of times the resolver will send a query to 930 all its name servers before giving up and returning an 931 error to the calling application."; 932 } 933 } 934 } 936 container radius { 937 if-feature radius; 939 description 940 "Configuration of the RADIUS client."; 942 list server { 943 key name; 944 ordered-by user; 945 description 946 "List of RADIUS servers used by the device. 948 When the RADIUS client is invoked by a calling 949 application, it sends the query to the first server in 950 this list. If no response has been received within 951 'timeout' seconds, the client continues with the next 952 server in the list. If no response is received from any 953 server, the client continues with the first server again. 954 When the client has traversed the list 'attempts' times 955 without receiving any response, it gives up and returns an 956 error to the calling application."; 958 leaf name { 959 type string; 960 description 961 "An arbitrary name for the RADIUS server."; 962 } 963 choice transport { 964 mandatory true; 965 description 966 "The transport protocol specific parameters for this 967 server."; 969 case udp { 970 container udp { 971 description 972 "Contains UDP specific configuration parameters 973 for RADIUS."; 974 leaf address { 975 type inet:host; 976 mandatory true; 977 description 978 "The address of the RADIUS server."; 979 } 980 leaf authentication-port { 981 type inet:port-number; 982 default "1812"; 983 description 984 "The port number of the RADIUS server."; 985 } 986 leaf shared-secret { 987 type string; 988 mandatory true; 989 nacm:default-deny-all; 990 description 991 "The shared secret which is known to both the 992 RADIUS client and server."; 993 reference 994 "RFC 2865: Remote Authentication Dial In User 995 Service"; 996 } 997 } 998 } 999 } 1000 leaf authentication-type { 1001 type identityref { 1002 base radius-authentication-type; 1003 } 1004 default radius-pap; 1005 description 1006 "The authentication type requested from the RADIUS 1007 server."; 1008 } 1009 } 1010 container options { 1011 description 1012 "RADIUS client options."; 1014 leaf timeout { 1015 type uint8 { 1016 range "1..max"; 1017 } 1018 units "seconds"; 1019 default "5"; 1020 description 1021 "The number of seconds the device will wait for a 1022 response from each RADIUS server before trying with a 1023 different server."; 1024 } 1025 leaf attempts { 1026 type uint8 { 1027 range "1..max"; 1028 } 1029 default "2"; 1030 description 1031 "The number of times the device will send a query to 1032 all its RADIUS servers before giving up."; 1033 } 1034 } 1035 } 1037 container authentication { 1038 nacm:default-deny-write; 1039 if-feature authentication; 1041 description 1042 "The authentication configuration subtree."; 1044 leaf-list user-authentication-order { 1045 type identityref { 1046 base authentication-method; 1047 } 1048 must '(. != "sys:radius" or ../../radius/server)' { 1049 error-message 1050 "When 'radius' is used, a RADIUS server" 1051 + " must be configured."; 1052 description 1053 "When 'radius' is used as an authentication method, 1054 a RADIUS server must be configured."; 1055 } 1056 ordered-by user; 1058 description 1059 "When the device authenticates a user with 1060 a password, it tries the authentication methods in this 1061 leaf-list in order. If authentication with one method 1062 fails, the next method is used. If no method succeeds, 1063 the user is denied access. 1065 If the 'radius-authentication' feature is advertised by 1066 the NETCONF server, the 'radius' identity can be added to 1067 this list. 1069 If the 'local-users' feature is advertised by the 1070 NETCONF server, the 'local-users' identity can be 1071 added to this list."; 1072 } 1074 list user { 1075 if-feature local-users; 1076 key name; 1077 description 1078 "The list of local users configured on this device."; 1080 leaf name { 1081 type string; 1082 description 1083 "The user name string identifying this entry."; 1084 } 1085 leaf password { 1086 type crypt-hash; 1087 description 1088 "The password for this entry."; 1089 } 1090 list ssh-key { 1091 key name; 1092 description 1093 "A list of public SSH keys for this user."; 1094 reference 1095 "RFC 4253: The Secure Shell (SSH) Transport Layer 1096 Protocol"; 1098 leaf name { 1099 type string; 1100 description 1101 "An arbitrary name for the ssh key."; 1102 } 1103 leaf algorithm { 1104 type string; 1105 mandatory true; 1106 description 1107 "The public key algorithm name for this ssh key. 1109 Valid values are the values in the IANA Secure Shell 1110 (SSH) Protocol Parameters registry, Public Key 1111 Algorithm Names"; 1112 reference 1113 "IANA Secure Shell (SSH) Protocol Parameters registry, 1114 Public Key Algorithm Names"; 1115 } 1116 leaf key-data { 1117 type binary; 1118 mandatory true; 1119 description 1120 "The binary key data for this ssh key."; 1121 } 1122 } 1123 } 1124 } 1125 } 1127 container system-state { 1128 config false; 1129 description 1130 "System group operational state."; 1132 container platform { 1133 config false; 1134 description 1135 "Contains vendor-specific information for 1136 identifying the system platform and operating system."; 1137 reference 1138 "IEEE Std 1003.1-2008 - sys/utsname.h"; 1140 leaf os-name { 1141 type string; 1142 description 1143 "The name of the operating system in use, 1144 for example 'Linux'"; 1145 reference 1146 "IEEE Std 1003.1-2008 - utsname.sysname"; 1147 } 1148 leaf os-release { 1149 type string; 1150 description 1151 "The current release level of the operating 1152 system in use. This string MAY indicate 1153 the OS source code revision."; 1154 reference 1155 "IEEE Std 1003.1-2008 - utsname.release"; 1156 } 1157 leaf os-version { 1158 type string; 1159 description 1160 "The current version level of the operating 1161 system in use. This string MAY indicate 1162 the specific OS build date and target variant 1163 information."; 1164 reference 1165 "IEEE Std 1003.1-2008 - utsname.version"; 1166 } 1167 leaf machine { 1168 type string; 1169 description 1170 "A vendor-specific identifier string representing 1171 the hardware in use."; 1172 reference 1173 "IEEE Std 1003.1-2008 - utsname.machine"; 1174 } 1175 } 1176 container clock { 1177 description 1178 "Monitoring of the system 1179 date and time properties."; 1181 leaf current-datetime { 1182 type yang:date-and-time; 1183 config false; 1184 description 1185 "The current system date and time."; 1186 } 1187 leaf boot-datetime { 1188 type yang:date-and-time; 1189 config false; 1190 description 1191 "The system date and time when the system last restarted."; 1192 } 1193 } 1195 } 1196 rpc set-current-datetime { 1197 nacm:default-deny-all; 1198 description 1199 "Set the /system-state/clock/current-datetime leaf 1200 to the specified value. 1202 If the system is using NTP (i.e., /system/ntp/enabled 1203 is set to 'true'), then this operation will 1204 fail with error-tag 'operation-failed', 1205 and error-app-tag value of 'ntp-active'"; 1206 input { 1207 leaf current-datetime { 1208 type yang:date-and-time; 1209 mandatory true; 1210 description 1211 "The current system date and time."; 1212 } 1213 } 1214 } 1216 rpc system-restart { 1217 nacm:default-deny-all; 1218 description 1219 "Request that the entire system be restarted immediately. 1220 A server SHOULD send an rpc reply to the client before 1221 restarting the system."; 1222 } 1224 rpc system-shutdown { 1225 nacm:default-deny-all; 1226 description 1227 "Request that the entire system be shut down immediately. 1228 A server SHOULD send an rpc reply to the client before 1229 shutting down the system."; 1230 } 1232 } 1234 1236 5. IANA Considerations 1238 This document registers one URI in the IETF XML registry [RFC3688]. 1239 Following the format in RFC 3688, the following registration is 1240 requested to be made. 1242 URI: urn:ietf:params:xml:ns:yang:ietf-system 1243 Registrant Contact: The NETMOD WG of the IETF. 1244 XML: N/A, the requested URI is an XML namespace. 1246 This document registers one YANG module in the YANG Module Names 1247 registry [RFC6020]. 1249 name: ietf-system 1250 namespace: urn:ietf:params:xml:ns:yang:ietf-system 1251 prefix: sys 1252 reference: RFC XXXX 1254 6. Security Considerations 1256 The YANG module defined in this memo is designed to be accessed via 1257 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1258 secure transport layer and the mandatory-to-implement secure 1259 transport is SSH [RFC6242]. Authorization for access to specific 1260 portions of conceptual data and operations within this module is 1261 provided by the NETCONF access control model (NACM) [RFC6536]. 1263 There are a number of data nodes defined in this YANG module which 1264 are writable/creatable/deletable (i.e., config true, which is the 1265 default). These data nodes may be considered sensitive or vulnerable 1266 in some network environments. Write operations (e.g., edit-config) 1267 to these data nodes without proper protection can have a negative 1268 effect on network operations. These are the subtrees and data nodes 1269 and their sensitivity/vulnerability: 1271 o /system/clock/timezone: This choice contains the objects used to 1272 control the timezone used by the device. 1274 o /system/ntp: This container contains the objects used to control 1275 the Network Time Protocol servers used by the device. 1277 o /system/dns-resolver: This container contains the objects used to 1278 control the Domain Name System servers used by the device. 1280 o /system/radius: This container contains the objects used to 1281 control the Remote Authentication Dial-In User Service servers 1282 used by the device. 1284 o /system/authentication/user-authentication-order: This leaf 1285 controls how user login attempts are authenticated by the device. 1287 o /system/authentication/user: This list contains the local users 1288 enabled on the system. 1290 Some of the readable data nodes in this YANG module may be considered 1291 sensitive or vulnerable in some network environments. It is thus 1292 important to control read access (e.g., via get, get-config, or 1293 notification) to these data nodes. These are the subtrees and data 1294 nodes and their sensitivity/vulnerability: 1296 o /system/platform: This container has objects which may help 1297 identify the specific NETCONF server and/or operating system 1298 implementation used on the device. 1300 o /system/authentication/user: This list has objects that may help 1301 identify the specific user names and password information in use 1302 on the device. 1304 Some of the RPC operations in this YANG module may be considered 1305 sensitive or vulnerable in some network environments. It is thus 1306 important to control access to these operations. These are the 1307 operations and their sensitivity/vulnerability: 1309 o set-current-datetime: Changes the current date and time on the 1310 device. 1312 o system-restart: Reboots the device. 1314 o system-shutdown: Shuts down the device. 1316 7. Change Log 1318 -- RFC Ed.: remove this section before publication. 1320 7.1. 00-01 1322 o added configuration-source identities 1324 o added configuration-source leaf to ntp and dns (via grouping) to 1325 choose configuration source 1327 o added association-type, iburst, prefer, and true leafs to the ntp- 1328 server list 1330 o extended the ssh keys for a user to a list of keys. support all 1331 defined key algorithms, not just dsa and rsa 1333 o clarified timezone-utc-offset description-stmt 1335 o removed '/system/ntp/server/true' leaf from data model 1337 7.2. 01-02 1339 o added default-stmts to ntp-server/iburst and ntp-server/prefer 1340 leafs 1342 o changed timezone-location leaf to use iana-timezone typedef 1343 instead of a string 1345 7.3. 02-03 1347 o removed configuration-source identities and leafs 1349 7.4. 03-04 1351 o removed ndots dns resolver option 1353 o added radius-authentication-type identity, and identities for pap 1354 and chap, and a leaf to control which authentication type to use 1355 when communicating with the radius server 1357 o made 0 an invalid value for timeouts and attempts 1359 7.5. 04-05 1361 o updated tree diagram explanation text 1363 7.6. 05-06 1365 o changed ntp/use-ntp to ntp/enabled 1367 o changed ntp/ntp-server to ntp/server 1369 o removed /system/platform/nodename leaf 1371 o changed /system/name to /system/hostname 1373 o simplified must expression in user-authentication-order 1375 o added optional rounds to sha hash definition 1377 o clarified the crypt-hash description 1379 o clarified ntp descriptions 1381 o clarified YANG module description to indicate that some system 1382 properties are supported, not the entire system 1384 o clarified that system identification values are vendor specific, 1385 not the data node objects 1387 o clarified sec. 2.2 and 2.3 to indicate that the server should also 1388 be capable of configuring these properties 1390 o changed /system/dns/search from inet:host to inet:domain-name 1392 o changed RFC6021 reference to 6021-bis 1394 o changed /system/platform/nodename to /system/platform/hostname 1396 o changed /system/radius/server/{leafs} to be within a choice and 1397 'udp' case statement so other transport specific parameters can 1398 augment this list or they can be added by the WG to a future 1399 version of this module. {leafs} are authentication-port and 1400 shared-secret. 1402 o updated YANG tree diagrams for objects added in -05 and -06 1404 7.7. 06-07 1406 o updated the Abstract and Introduction 1408 o updated Tree diagram notation 1409 o identify all external servers (dns, ntp, radius) by name instead 1410 of address, in order to make the data model extensible for 1411 additional transport protocol. 1413 o updated the Security Considerations section with a reference to 1414 NACM. 1416 7.8. 07-08 1418 o renamed the DNS transport to 'udp-and-tcp' and added references. 1420 o moved the operational state nodes into /system-state. 1422 8. References 1424 8.1. Normative References 1426 [FIPS.180-3.2008] 1427 National Institute of Standards and Technology, "Secure 1428 Hash Standard", FIPS PUB 180-3, October 2008, . 1432 [I-D.ietf-netmod-iana-timezones] 1433 Lange, J., "IANA Timezone Database YANG Module", 1434 draft-ietf-netmod-iana-timezones-00 (work in progress), 1435 July 2012. 1437 [I-D.ietf-netmod-rfc6021-bis] 1438 Schoenwaelder, J., "Common YANG Data Types", 1439 draft-ietf-netmod-rfc6021-bis-03 (work in progress), 1440 June 2013. 1442 [IEEE-1003.1-2008] 1443 Institute of Electrical and Electronics Engineers, 1444 "POSIX.1-2008", IEEE Standard 1003.1, March 2008. 1446 [RFC1035] Mockapetris, P., "Domain names - implementation and 1447 specification", STD 13, RFC 1035, November 1987. 1449 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 1450 April 1992. 1452 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1453 Requirement Levels", BCP 14, RFC 2119, March 1997. 1455 [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, 1456 "Remote Authentication Dial In User Service (RADIUS)", 1457 RFC 2865, June 2000. 1459 [RFC3418] Presuhn, R., "Management Information Base (MIB) for the 1460 Simple Network Management Protocol (SNMP)", STD 62, 1461 RFC 3418, December 2002. 1463 [RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 1464 Authentication Protocol", RFC 4252, January 2006. 1466 [RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 1467 Transport Layer Protocol", RFC 4253, January 2006. 1469 [RFC5607] Nelson, D. and G. Weber, "Remote Authentication Dial-In 1470 User Service (RADIUS) Authorization for Network Access 1471 Server (NAS) Management", RFC 5607, July 2009. 1473 [RFC5966] Bellis, R., "DNS Transport over TCP - Implementation 1474 Requirements", RFC 5966, August 2010. 1476 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1477 Network Configuration Protocol (NETCONF)", RFC 6020, 1478 October 2010. 1480 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1481 and A. Bierman, Ed., "Network Configuration Protocol 1482 (NETCONF)", RFC 6241, June 2011. 1484 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1485 Shell (SSH)", RFC 6242, June 2011. 1487 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1488 Protocol (NETCONF) Access Control Model", RFC 6536, 1489 March 2012. 1491 8.2. Informative References 1493 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1494 January 2004. 1496 [RFC6557] Lear, E. and P. Eggert, "Procedures for Maintaining the 1497 Time Zone Database", BCP 175, RFC 6557, February 2012. 1499 Authors' Addresses 1501 Andy Bierman 1502 YumaWorks 1504 Email: andy@yumaworks.com 1506 Martin Bjorklund 1507 Tail-f Systems 1509 Email: mbj@tail-f.com