idnits 2.17.1 draft-ietf-netmod-system-mgmt-13.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 243 has weird spacing: '...address ine...' == Line 265 has weird spacing: '...rw name str...' == Line 269 has weird spacing: '...address ine...' == Line 335 has weird spacing: '...gorithm str...' == 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 (February 18, 2014) is 3713 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) -- 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) ** Downref: Normative reference to an Informational RFC: RFC 6151 ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 4 errors (**), 0 flaws (~~), 6 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: August 22, 2014 Tail-f Systems 6 February 18, 2014 8 A YANG Data Model for System Management 9 draft-ietf-netmod-system-mgmt-13 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 August 22, 2014. 37 Copyright Notice 39 Copyright (c) 2014 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. Relationship to the SNMPv2-MIB . . . . . . . . . . . . . . . . 11 74 5. System YANG module . . . . . . . . . . . . . . . . . . . . . . 12 75 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 76 7. Security Considerations . . . . . . . . . . . . . . . . . . . 32 77 8. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 34 78 8.1. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 34 79 8.2. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 34 80 8.3. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 34 81 8.4. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 34 82 8.5. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 34 83 8.6. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 35 84 8.7. 06-07 . . . . . . . . . . . . . . . . . . . . . . . . . . 35 85 8.8. 07-08 . . . . . . . . . . . . . . . . . . . . . . . . . . 36 86 8.9. 08-09 . . . . . . . . . . . . . . . . . . . . . . . . . . 36 87 8.10. 09-10 . . . . . . . . . . . . . . . . . . . . . . . . . . 36 88 8.11. 11-12 . . . . . . . . . . . . . . . . . . . . . . . . . . 36 89 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 37 90 9.1. Normative References . . . . . . . . . . . . . . . . . . . 37 91 9.2. Informative References . . . . . . . . . . . . . . . . . . 38 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 39 94 1. Introduction 96 This document defines a YANG [RFC6020] data model for the 97 configuration and identification of some common properties within a 98 device containing a NETCONF server. 100 Devices that are managed by NETCONF and perhaps other mechanisms have 101 common properties that need to be configured and monitored in a 102 standard way. 104 The "ietf-system" YANG module defined in this document provides the 105 following features: 107 o system identification configuration and monitoring 109 o system time-of-day configuration and monitoring 111 o user authentication configuration 113 o local users configuration 115 o DNS resolver configuration 117 o system control operations (shutdown, restart, setting time) 119 1.1. Terminology 121 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 123 "OPTIONAL" in this document are to be interpreted as described in BCP 124 14, [RFC2119]. 126 The following terms are defined in [RFC6241] and are not redefined 127 here: 129 o client 131 o configuration data 133 o server 135 o state data 137 1.2. Tree Diagrams 139 A simplified graphical representation of the data model is used in 140 this document. The meaning of the symbols in these diagrams is as 141 follows: 143 o Brackets "[" and "]" enclose list keys. 145 o Abbreviations before data node names: "rw" means configuration 146 (read-write) and "ro" state data (read-only). 148 o Symbols after data node names: "?" means an optional node, "!" 149 means a presence container, and "*" denotes a list and leaf-list. 151 o Parentheses enclose choice and case nodes, and case nodes are also 152 marked with a colon (":"). 154 o Ellipsis ("...") stands for contents of subtrees that are not 155 shown. 157 2. Objectives 159 2.1. System Identification 161 There are many common properties used to identify devices, operating 162 systems, software versions, etc. that need to be supported in the 163 system data module. These objects are defined as operational state 164 data and the information returned by the server is intended to be 165 specific to the device vendor. 167 Some user-configurable administrative strings are also provided, such 168 as the system location and description. 170 2.2. System Time Management 172 The management of the date and time used by the system need to be 173 supported. Use of one or more NTP servers to automatically set the 174 system date and time need to be possible. Utilization of the 175 Timezone database [RFC6557] also need to be supported. It should be 176 possible to configure the system to use NTP. 178 2.3. User Authentication 180 The authentication mechanism needs to support password authentication 181 over RADIUS, to support deployment scenarios with centralized 182 authentication servers. Additionally, local users need to be 183 supported, for scenarios when no centralized authentication server 184 exists, or for situations where the centralized authentication server 185 cannot be reached from the device. 187 Since the mandatory transport protocol for NETCONF is SSH [RFC6242] 188 the authentication model needs to support SSH's "publickey" and 189 "password" authentication methods [RFC4252]. 191 The model for authentication configuration should be flexible enough 192 to support authentication methods defined by other standard documents 193 or by vendors. It should be possible to configure the system 194 authentication properties. 196 2.4. DNS Resolver 198 The configuration of the DNS resolver within the system containing 199 the NETCONF server is required in order to control how domain names 200 are resolved. 202 2.5. System Control 204 A few operations are needed to support common tasks such as 205 restarting the device or setting the system date and time. 207 3. System Data Model 209 3.1. System Identification 211 The data model for system identification has the following structure: 213 +--rw system 214 | +--rw contact? string 215 | +--rw hostname? inet:domain-name 216 | +--rw location? string 217 +--ro system-state 218 +--ro platform 219 +--ro os-name? string 220 +--ro os-release? string 221 +--ro os-version? string 222 +--ro machine? string 224 3.2. System Time Management 226 The data model for system time management has the following 227 structure: 229 +--rw system 230 | +--rw clock 231 | | +--rw (timezone)? 232 | | +--:(timezone-name) 233 | | | +--rw timezone-name? timezone-name 234 | | +--:(timezone-utc-offset) 235 | | +--rw timezone-utc-offset? int16 236 | +--rw ntp! 237 | +--rw enabled? boolean 238 | +--rw server* [name] 239 | +--rw name string 240 | +--rw (transport) 241 | | +--:(udp) 242 | | +--rw udp 243 | | +--rw address inet:host 244 | | +--rw port? inet:port-number 245 | +--rw association-type? enumeration 246 | +--rw iburst? boolean 247 | +--rw prefer? boolean 248 +--ro system-state 249 +--ro clock 250 +--ro current-datetime? yang:date-and-time 251 +--ro boot-datetime? yang:date-and-time 253 New "case" statements can be added over time or augmented to the 254 "transport" choice to support other transport protocols. 256 3.3. DNS Resolver Model 258 The data model for configuration of the DNS resolver has the 259 following structure: 261 +--rw system 262 +--rw dns-resolver 263 +--rw search* inet:domain-name 264 +--rw server* [name] 265 | +--rw name string 266 | +--rw (transport) 267 | +--:(udp-and-tcp) 268 | +--udp-and-tcp 269 | +--rw address inet:ip-address 270 | +--rw port? inet:port-number 271 +--rw options 272 +--rw timeout? uint8 273 +--rw attempts? uint8 275 New "case" statements can be added over time or augmented to the 276 "transport" choice to support other transport protocols. 278 3.4. RADIUS Client Model 280 The data model for configuration of the RADIUS client has the 281 following structure: 283 +--rw system 284 +--rw radius 285 +--rw server* [name] 286 | +--rw name string 287 | +--rw (transport) 288 | | +--:(udp) 289 | | +--rw udp 290 | | +--rw address inet:host 291 | | +--rw authentication-port? inet:port-number 292 | | +--rw shared-secret string 293 | +--rw authentication-type? identityref 294 +--rw options 295 +--rw timeout? uint8 296 +--rw attempts? uint8 298 New "case" statements can be added over time or augmented to the 299 "transport" choice to support other transport protocols. 301 3.5. User Authentication Model 303 This document defines three authentication methods for use with 304 NETCONF: 306 o publickey for local users over SSH 308 o password for local users over any transport 310 o password for RADIUS users over any transport 312 Additional methods can be defined by other standard documents or by 313 vendors. 315 This document defines two optional YANG features, "local-users" and 316 "radius-authentication", which the server advertises to indicate 317 support for configuring local users on the device, and support for 318 using RADIUS for authentication, respectively. 320 The authentication parameters defined in this document are primarily 321 used to configure authentication of NETCONF users, but MAY also be 322 used by other interfaces, e.g., a Command Line Interface or a Web- 323 based User Interface. 325 The data model for user authentication has the following structure: 327 +--rw system 328 +--rw authentication 329 +--rw user-authentication-order* identityref 330 +--rw user* [name] 331 +--rw name string 332 +--rw password? crypt-hash 333 +--rw ssh-key* [name] 334 +--rw name string 335 +--rw algorithm string 336 +--rw key-data binary 338 3.5.1. SSH Public Key Authentication 340 If the NETCONF server advertises the "local-users" feature, 341 configuration of local users and their SSH public keys is supported 342 in the /system/authentication/user list. 344 Public key authentication is requested by the SSH client. If the 345 "local-users" feature is supported, then when a NETCONF client starts 346 an SSH session towards the server using the "publickey" 347 authentication "method name" [RFC4252], the SSH server looks up the 348 user name given in the SSH authentication request in the /system/ 349 authentication/user list, and verifies the key as described in 350 [RFC4253]. 352 3.5.2. Local User Password Authentication 354 If the NETCONF server advertises the "local-users" feature, 355 configuration of local users and their passwords is supported in the 356 /system/authentication/user list. 358 For NETCONF transport protocols that support password authentication, 359 the leaf-list "user-authentication-order" is used to control if local 360 user password authentication should be used. 362 In SSH, password authentication is requested by the client. Other 363 NETCONF transport protocols MAY also support password authentication. 365 When local user password authentication is requested, the NETCONF 366 transport looks up the user name provided by the client in the 367 /system/authentication/user list, and verifies the password. 369 3.5.3. RADIUS Password Authentication 371 If the NETCONF server advertises the "radius-authentication" feature, 372 the device supports user authentication using RADIUS. 374 For NETCONF transport protocols that support password authentication, 375 the leaf-list "user-authentication-order" is used to control if 376 RADIUS password authentication should be used. 378 In SSH, password authentication is requested by the client. Other 379 NETCONF transport protocols MAY also support password authentication. 381 3.6. System Control 383 The following operations are defined: 385 set-current-datetime 386 system-restart 387 system-shutdown 389 Two protocol operations are included to restart or shutdown the 390 system. The 'system-restart' operation can be used to restart the 391 entire system (not just the NETCONF server). The 'system-shutdown' 392 operation can be used to power off the entire system. 394 4. Relationship to the SNMPv2-MIB 396 If a device implements the SNMPv2-MIB [RFC3418], there are two 397 objects that MAY be mapped by the implementation. See the YANG 398 module definition in Section 5 for details. The following table 399 lists the YANG data nodes with corresponding objects in the SNMPv2- 400 MIB. 402 +----------------+-------------------+ 403 | YANG data node | SNMPv2-MIB object | 404 +----------------+-------------------+ 405 | contact | sysContact | 406 | location | sysLocation | 407 +----------------+-------------------+ 409 YANG interface configuration data nodes and related SNMPv2-MIB 410 objects 412 5. System YANG module 414 This YANG module imports YANG extensions from [RFC6536], and imports 415 YANG types from [RFC6991]. It also references [RFC1035], [RFC1321], 416 [RFC2865], [RFC3418], [RFC5607], [RFC5966], [RFC6557], 417 [IEEE-1003.1-2008], and [FIPS.180-3.2008]. 419 RFC Ed.: update the date below with the date of RFC publication and 420 remove this note. 422 file "ietf-system@2014-02-18.yang" 424 module ietf-system { 425 namespace "urn:ietf:params:xml:ns:yang:ietf-system"; 426 prefix "sys"; 428 import ietf-yang-types { 429 prefix yang; 430 } 432 import ietf-inet-types { 433 prefix inet; 434 } 436 import ietf-netconf-acm { 437 prefix nacm; 438 } 440 organization 441 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 443 contact 444 "WG Web: 445 WG List: 447 WG Chair: Thomas Nadeau 448 450 WG Chair: Juergen Schoenwaelder 451 453 Editor: Andy Bierman 454 456 Editor: Martin Bjorklund 457 "; 459 description 460 "This module contains a collection of YANG definitions for the 461 configuration and identification of some common system 462 properties within a device containing a NETCONF server. This 463 includes data node definitions for system identification, 464 time-of-day management, user management, DNS resolver 465 configuration, and some protocol operations for system 466 management. 468 Copyright (c) 2014 IETF Trust and the persons identified as 469 authors of the code. All rights reserved. 471 Redistribution and use in source and binary forms, with or 472 without modification, is permitted pursuant to, and subject 473 to the license terms contained in, the Simplified BSD License 474 set forth in Section 4.c of the IETF Trust's Legal Provisions 475 Relating to IETF Documents 476 (http://trustee.ietf.org/license-info). 478 This version of this YANG module is part of RFC XXXX; see 479 the RFC itself for full legal notices."; 481 // RFC Ed.: replace XXXX with actual RFC number and remove this 482 // note. 484 // RFC Ed.: remove this note 485 // Note: extracted from draft-ietf-netmod-system-mgmt-07.txt 487 // RFC Ed.: update the date below with the date of RFC publication 488 // and remove this note. 489 revision "2014-02-18" { 490 description 491 "Initial revision."; 492 reference 493 "RFC XXXX: A YANG Data Model for System Management"; 494 } 496 /* 497 * Typedefs 498 */ 500 typedef timezone-name { 501 type string; 502 description 503 "A timezone name as used by the Time Zone Database, sometimes 504 referred to as the 'Olson Database'. 506 The exact set of valid values is an implementation-specific 507 matter. Client discovery of the exact set of time zone names 508 for a particular server is out of scope."; 509 reference 510 "RFC 6557: Procedures for Maintaining the Time Zone Database"; 511 } 513 typedef crypt-hash { 514 type string { 515 pattern 516 '$0$.*' 517 + '|$1$[a-zA-Z0-9./]{1,8}$[a-zA-Z0-9./]{22}' 518 + '|$5$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{43}' 519 + '|$6$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{86}'; 520 } 521 description 522 "The crypt-hash type is used to store passwords using 523 a hash function. The algorithms for applying the hash 524 function and encoding the result are implemented in 525 various UNIX systems as the function crypt(3). 527 A value of this type matches one of the forms: 529 $0$ 530 $$$ 531 $$$$ 533 The '$0$' prefix signals that the value is clear text. When 534 such a value is received by the server, a hash value is 535 calculated, and the string '$$$' or 536 $$$$ is prepended to the result. This 537 value is stored in the configuration data store. 539 If a value starting with '$$', where is not '0', is 540 received, the server knows that the value already represents a 541 hashed value, and stores it as is in the data store. 543 When a server needs to verify a password given by a user, it 544 finds the stored password hash string for that user, extracts 545 the salt, and calculates the hash with the salt and given 546 password as input. If the calculated hash value is the same 547 as the stored value, the password given by the client is 548 accepted. 550 This type defines the following hash functions: 552 id | hash function | feature 553 ---+---------------+------------------- 554 1 | MD5 | crypt-hash-md5 555 5 | SHA-256 | crypt-hash-sha-256 556 6 | SHA-512 | crypt-hash-sha-512 558 The server indicates support for the different hash functions 559 by advertising the corresponding feature."; 560 reference 561 "IEEE Std 1003.1-2008 - crypt() function 562 Wikipedia: http://en.wikipedia.org/wiki/Crypt_(C) 563 RFC 1321: The MD5 Message-Digest Algorithm 564 FIPS.180-3.2008: Secure Hash Standard"; 565 } 567 /* 568 * Features 569 */ 571 feature radius { 572 description 573 "Indicates that the device can be configured as a RADIUS 574 client."; 575 reference 576 "RFC 2865: Remote Authentication Dial In User Service " 577 + "(RADIUS)"; 578 } 580 feature authentication { 581 description 582 "Indicates that the device supports configuration 583 for user authentication."; 584 } 586 feature local-users { 587 if-feature authentication; 588 description 589 "Indicates that the device supports configuration of 590 local user authentication."; 591 } 593 feature radius-authentication { 594 if-feature radius; 595 if-feature authentication; 596 description 597 "Indicates that the device supports configuration of user 598 authentication over RADIUS."; 599 reference 600 "RFC 2865: Remote Authentication Dial In User Service (RADIUS) 601 RFC 5607: Remote Authentication Dial-In User Service (RADIUS) 602 Authorization for Network Access Server (NAS) 603 Management"; 604 } 606 feature crypt-hash-md5 { 607 description 608 "Indicates that the device supports the MD5 609 hash function in 'crypt-hash' values"; 610 reference "RFC 1321: The MD5 Message-Digest Algorithm"; 611 } 613 feature crypt-hash-sha-256 { 614 description 615 "Indicates that the device supports the SHA-256 616 hash function in 'crypt-hash' values"; 617 reference "FIPS.180-3.2008: Secure Hash Standard"; 618 } 620 feature crypt-hash-sha-512 { 621 description 622 "Indicates that the device supports the SHA-512 623 hash function in 'crypt-hash' values"; 624 reference "FIPS.180-3.2008: Secure Hash Standard"; 625 } 627 feature ntp { 628 description 629 "Indicates that the device can be configured 630 to use one or more NTP servers to set the 631 system date and time."; 632 } 634 feature ntp-udp-port { 635 description 636 "Indicates that the device supports the configuration of 637 the UDP port for NTP servers. 639 This is a 'feature' since many implementations do not support 640 any other port than the default port."; 641 } 643 feature timezone-name { 644 description 645 "Indicates that the local timezone on the device 646 can be configured to use the TZ database 647 to set the timezone and manage daylight savings time."; 648 reference 649 "RFC 6557: Procedures for Maintaining the Time Zone Database"; 650 } 651 feature dns-udp-tcp-port { 652 description 653 "Indicates that the device supports the configuration of 654 the UDP and TCP port for DNS servers. 656 This is a 'feature' since many implementations do not support 657 any other port than the default port."; 658 } 660 /* 661 * Identities 662 */ 664 identity authentication-method { 665 description 666 "Base identity for user authentication methods."; 667 } 669 identity radius { 670 base authentication-method; 671 description 672 "Indicates user authentication using RADIUS."; 673 reference 674 "RFC 2865: Remote Authentication Dial In User Service (RADIUS) 675 RFC 5607: Remote Authentication Dial-In User Service (RADIUS) 676 Authorization for Network Access Server (NAS) 677 Management"; 678 } 680 identity local-users { 681 base authentication-method; 682 description 683 "Indicates password-based authentication of locally 684 configured users."; 685 } 687 identity radius-authentication-type { 688 description 689 "Base identity for RADIUS authentication types."; 690 } 692 identity radius-pap { 693 base radius-authentication-type; 694 description 695 "The device requests PAP authentication from the RADIUS 696 server."; 697 reference 698 "RFC 2865: Remote Authentication Dial In User Service"; 700 } 702 identity radius-chap { 703 base radius-authentication-type; 704 description 705 "The device requests CHAP authentication from the RADIUS 706 server."; 707 reference 708 "RFC 2865: Remote Authentication Dial In User Service"; 709 } 711 /* 712 * Configuration data nodes 713 */ 715 container system { 716 description 717 "System group configuration."; 719 leaf contact { 720 type string; 721 description 722 "The administrator contact information for the system. 724 A server implementation MAY map this leaf to the sysContact 725 MIB object. Such an implementation needs to use some 726 mechanism to handle the differences in size and characters 727 allowed between this leaf and sysContact. The definition of 728 such a mechanism is outside the scope of this document."; 729 reference 730 "RFC 3418: Management Information Base (MIB) for the 731 Simple Network Management Protocol (SNMP) 732 SNMPv2-MIB.sysContact"; 733 } 734 leaf hostname { 735 type inet:domain-name; 736 description 737 "The name of the host. This name can be a single domain 738 label, or the fully qualified domain name of the host."; 739 } 740 leaf location { 741 type string; 742 description 743 "The system location. 745 A server implementation MAY map this leaf to the sysLocation 746 MIB object. Such an implementation needs to use some 747 mechanism to handle the differences in size and characters 748 allowed between this leaf and sysLocation. The definition 749 of such a mechanism is outside the scope of this document."; 750 reference 751 "RFC 3418: Management Information Base (MIB) for the 752 Simple Network Management Protocol (SNMP) 753 SNMPv2-MIB.sysLocation"; 754 } 756 container clock { 757 description 758 "Configuration of the system date and time properties."; 760 choice timezone { 761 description 762 "The system timezone information."; 764 case timezone-name { 765 if-feature timezone-name; 766 leaf timezone-name { 767 type timezone-name; 768 description 769 "The TZ database name to use for the system, such 770 as 'Europe/Stockholm'."; 771 } 772 } 773 case timezone-utc-offset { 774 leaf timezone-utc-offset { 775 type int16 { 776 range "-1500 .. 1500"; 777 } 778 units "minutes"; 779 description 780 "The number of minutes to add to UTC time to 781 identify the timezone for this system. For example, 782 'UTC - 8:00 hours' would be represented as '-480'. 783 Note that automatic daylight savings time adjustment 784 is not provided, if this object is used."; 785 } 786 } 787 } 788 } 790 container ntp { 791 if-feature ntp; 792 presence 793 "Enables the NTP client unless the 'enabled' leaf 794 (which defaults to 'true') is set to 'false'"; 795 description 796 "Configuration of the NTP client."; 798 leaf enabled { 799 type boolean; 800 default true; 801 description 802 "Indicates that the system should attempt 803 to synchronize the system clock with an 804 NTP server from the 'ntp/server' list."; 805 } 806 list server { 807 key name; 808 description 809 "List of NTP servers to use for 810 system clock synchronization. If '/system/ntp/enabled' 811 is 'true', then the system will attempt to 812 contact and utilize the specified NTP servers."; 814 leaf name { 815 type string; 816 description 817 "An arbitrary name for the NTP server."; 818 } 819 choice transport { 820 mandatory true; 821 description 822 "The transport protocol specific parameters for this 823 server."; 825 case udp { 826 container udp { 827 description 828 "Contains UDP specific configuration parameters 829 for NTP."; 830 leaf address { 831 type inet:host; 832 mandatory true; 833 description 834 "The address of the NTP server."; 835 } 836 leaf port { 837 if-feature ntp-udp-port; 838 type inet:port-number; 839 default 123; 840 description 841 "The port number of the NTP server."; 842 } 843 } 845 } 846 } 847 leaf association-type { 848 type enumeration { 849 enum server { 850 description 851 "Use client association mode. This device 852 will not provide synchronization to the 853 configured NTP server."; 854 } 855 enum peer { 856 description 857 "Use symmetric active association mode. 858 This device may provide synchronization 859 to the configured NTP server."; 860 } 861 enum pool { 862 description 863 "Use client association mode with one or 864 more of the NTP servers found by DNS 865 resolution of the domain name given by 866 the 'address' leaf. This device will not 867 provide synchronization to the servers."; 868 } 869 } 870 default server; 871 description 872 "The desired association type for this NTP server."; 873 } 874 leaf iburst { 875 type boolean; 876 default false; 877 description 878 "Indicates whether this server should enable burst 879 synchronization or not."; 880 } 881 leaf prefer { 882 type boolean; 883 default false; 884 description 885 "Indicates whether this server should be preferred 886 or not."; 887 } 888 } 889 } 891 container dns-resolver { 892 description 893 "Configuration of the DNS resolver."; 895 leaf-list search { 896 type inet:domain-name; 897 ordered-by user; 898 description 899 "An ordered list of domains to search when resolving 900 a host name."; 901 } 902 list server { 903 key name; 904 ordered-by user; 905 description 906 "List of the DNS servers that the resolver should query. 908 When the resolver is invoked by a calling application, it 909 sends the query to the first name server in this list. If 910 no response has been received within 'timeout' seconds, 911 the resolver continues with the next server in the list. 912 If no response is received from any server, the resolver 913 continues with the first server again. When the resolver 914 has traversed the list 'attempts' times without receiving 915 any response, it gives up and returns an error to the 916 calling application. 918 Implementations MAY limit the number of entries in this 919 list."; 921 leaf name { 922 type string; 923 description 924 "An arbitrary name for the DNS server."; 925 } 926 choice transport { 927 mandatory true; 928 description 929 "The transport protocol specific parameters for this 930 server."; 932 case udp-and-tcp { 933 container udp-and-tcp { 934 description 935 "Contains UDP and TCP specific configuration 936 parameters for DNS."; 937 reference 938 "RFC 1035: Domain Implementation and Specification 939 RFC 5966: DNS over TCP"; 941 leaf address { 942 type inet:ip-address; 943 mandatory true; 944 description 945 "The address of the DNS server."; 946 } 947 leaf port { 948 if-feature dns-udp-tcp-port; 949 type inet:port-number; 950 default 53; 951 description 952 "The UDP and TCP port number of the DNS server."; 953 } 954 } 955 } 956 } 957 } 958 container options { 959 description 960 "Resolver options. The set of available options has been 961 limited to those that are generally available across 962 different resolver implementations, and generally 963 useful."; 964 leaf timeout { 965 type uint8 { 966 range "1..max"; 967 } 968 units "seconds"; 969 default "5"; 970 description 971 "The amount of time the resolver will wait for a 972 response from each remote name server before 973 retrying the query via a different name server."; 974 } 975 leaf attempts { 976 type uint8 { 977 range "1..max"; 978 } 979 default "2"; 980 description 981 "The number of times the resolver will send a query to 982 all its name servers before giving up and returning an 983 error to the calling application."; 984 } 985 } 986 } 988 container radius { 989 if-feature radius; 991 description 992 "Configuration of the RADIUS client."; 994 list server { 995 key name; 996 ordered-by user; 997 description 998 "List of RADIUS servers used by the device. 1000 When the RADIUS client is invoked by a calling 1001 application, it sends the query to the first server in 1002 this list. If no response has been received within 1003 'timeout' seconds, the client continues with the next 1004 server in the list. If no response is received from any 1005 server, the client continues with the first server again. 1006 When the client has traversed the list 'attempts' times 1007 without receiving any response, it gives up and returns an 1008 error to the calling application."; 1010 leaf name { 1011 type string; 1012 description 1013 "An arbitrary name for the RADIUS server."; 1014 } 1015 choice transport { 1016 mandatory true; 1017 description 1018 "The transport protocol specific parameters for this 1019 server."; 1021 case udp { 1022 container udp { 1023 description 1024 "Contains UDP specific configuration parameters 1025 for RADIUS."; 1026 leaf address { 1027 type inet:host; 1028 mandatory true; 1029 description 1030 "The address of the RADIUS server."; 1031 } 1032 leaf authentication-port { 1033 type inet:port-number; 1034 default "1812"; 1035 description 1036 "The port number of the RADIUS server."; 1038 } 1039 leaf shared-secret { 1040 type string; 1041 mandatory true; 1042 nacm:default-deny-all; 1043 description 1044 "The shared secret which is known to both the 1045 RADIUS client and server."; 1046 reference 1047 "RFC 2865: Remote Authentication Dial In User 1048 Service"; 1049 } 1050 } 1051 } 1052 } 1053 leaf authentication-type { 1054 type identityref { 1055 base radius-authentication-type; 1056 } 1057 default radius-pap; 1058 description 1059 "The authentication type requested from the RADIUS 1060 server."; 1061 } 1062 } 1063 container options { 1064 description 1065 "RADIUS client options."; 1067 leaf timeout { 1068 type uint8 { 1069 range "1..max"; 1070 } 1071 units "seconds"; 1072 default "5"; 1073 description 1074 "The number of seconds the device will wait for a 1075 response from each RADIUS server before trying with a 1076 different server."; 1077 } 1078 leaf attempts { 1079 type uint8 { 1080 range "1..max"; 1081 } 1082 default "2"; 1083 description 1084 "The number of times the device will send a query to 1085 all its RADIUS servers before giving up."; 1087 } 1088 } 1089 } 1091 container authentication { 1092 nacm:default-deny-write; 1093 if-feature authentication; 1095 description 1096 "The authentication configuration subtree."; 1098 leaf-list user-authentication-order { 1099 type identityref { 1100 base authentication-method; 1101 } 1102 must '(. != "sys:radius" or ../../radius/server)' { 1103 error-message 1104 "When 'radius' is used, a RADIUS server" 1105 + " must be configured."; 1106 description 1107 "When 'radius' is used as an authentication method, 1108 a RADIUS server must be configured."; 1109 } 1110 ordered-by user; 1112 description 1113 "When the device authenticates a user with a password, 1114 it tries the authentication methods in this leaf-list in 1115 order. If authentication with one method fails, the next 1116 method is used. If no method succeeds, the user is 1117 denied access. 1119 An empty user-authentication-order leaf-list still allows 1120 authentication of users using mechanisms that do not 1121 involve a password. 1123 If the 'radius-authentication' feature is advertised by 1124 the NETCONF server, the 'radius' identity can be added to 1125 this list. 1127 If the 'local-users' feature is advertised by the 1128 NETCONF server, the 'local-users' identity can be 1129 added to this list."; 1130 } 1132 list user { 1133 if-feature local-users; 1134 key name; 1135 description 1136 "The list of local users configured on this device."; 1138 leaf name { 1139 type string; 1140 description 1141 "The user name string identifying this entry."; 1142 } 1143 leaf password { 1144 type crypt-hash; 1145 description 1146 "The password for this entry."; 1147 } 1148 list ssh-key { 1149 key name; 1150 description 1151 "A list of public SSH keys for this user."; 1152 reference 1153 "RFC 4253: The Secure Shell (SSH) Transport Layer 1154 Protocol"; 1156 leaf name { 1157 type string; 1158 description 1159 "An arbitrary name for the ssh key."; 1160 } 1161 leaf algorithm { 1162 type string; 1163 mandatory true; 1164 description 1165 "The public key algorithm name for this ssh key. 1167 Valid values are the values in the IANA Secure Shell 1168 (SSH) Protocol Parameters registry, Public Key 1169 Algorithm Names"; 1170 reference 1171 "IANA Secure Shell (SSH) Protocol Parameters registry, 1172 Public Key Algorithm Names"; 1173 } 1174 leaf key-data { 1175 type binary; 1176 mandatory true; 1177 description 1178 "The binary key data for this ssh key."; 1179 } 1180 } 1181 } 1182 } 1184 } 1186 /* 1187 * Operational state data nodes 1188 */ 1190 container system-state { 1191 config false; 1192 description 1193 "System group operational state."; 1195 container platform { 1196 description 1197 "Contains vendor-specific information for 1198 identifying the system platform and operating system."; 1199 reference 1200 "IEEE Std 1003.1-2008 - sys/utsname.h"; 1202 leaf os-name { 1203 type string; 1204 description 1205 "The name of the operating system in use, 1206 for example 'Linux'"; 1207 reference 1208 "IEEE Std 1003.1-2008 - utsname.sysname"; 1209 } 1210 leaf os-release { 1211 type string; 1212 description 1213 "The current release level of the operating 1214 system in use. This string MAY indicate 1215 the OS source code revision."; 1216 reference 1217 "IEEE Std 1003.1-2008 - utsname.release"; 1218 } 1219 leaf os-version { 1220 type string; 1221 description 1222 "The current version level of the operating 1223 system in use. This string MAY indicate 1224 the specific OS build date and target variant 1225 information."; 1226 reference 1227 "IEEE Std 1003.1-2008 - utsname.version"; 1228 } 1229 leaf machine { 1230 type string; 1231 description 1232 "A vendor-specific identifier string representing 1233 the hardware in use."; 1234 reference 1235 "IEEE Std 1003.1-2008 - utsname.machine"; 1236 } 1237 } 1239 container clock { 1240 description 1241 "Monitoring of the system 1242 date and time properties."; 1244 leaf current-datetime { 1245 type yang:date-and-time; 1246 description 1247 "The current system date and time."; 1248 } 1249 leaf boot-datetime { 1250 type yang:date-and-time; 1251 description 1252 "The system date and time when the system last restarted."; 1253 } 1254 } 1255 } 1257 rpc set-current-datetime { 1258 nacm:default-deny-all; 1259 description 1260 "Set the /system-state/clock/current-datetime leaf 1261 to the specified value. 1263 If the system is using NTP (i.e., /system/ntp/enabled 1264 is set to 'true'), then this operation will 1265 fail with error-tag 'operation-failed', 1266 and error-app-tag value of 'ntp-active'"; 1267 input { 1268 leaf current-datetime { 1269 type yang:date-and-time; 1270 mandatory true; 1271 description 1272 "The current system date and time."; 1273 } 1274 } 1275 } 1277 rpc system-restart { 1278 nacm:default-deny-all; 1279 description 1280 "Request that the entire system be restarted immediately. 1281 A server SHOULD send an rpc reply to the client before 1282 restarting the system."; 1283 } 1285 rpc system-shutdown { 1286 nacm:default-deny-all; 1287 description 1288 "Request that the entire system be shut down immediately. 1289 A server SHOULD send an rpc reply to the client before 1290 shutting down the system."; 1291 } 1293 } 1295 1297 6. IANA Considerations 1299 This document registers one URI in the IETF XML registry [RFC3688]. 1300 Following the format in RFC 3688, the following registration is 1301 requested to be made. 1303 URI: urn:ietf:params:xml:ns:yang:ietf-system 1304 Registrant Contact: The NETMOD WG of the IETF. 1305 XML: N/A, the requested URI is an XML namespace. 1307 This document registers one YANG module in the YANG Module Names 1308 registry [RFC6020]. 1310 name: ietf-system 1311 namespace: urn:ietf:params:xml:ns:yang:ietf-system 1312 prefix: sys 1313 reference: RFC XXXX 1315 7. Security Considerations 1317 The YANG module defined in this memo is designed to be accessed via 1318 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1319 secure transport layer and the mandatory-to-implement secure 1320 transport is SSH [RFC6242]. Authorization for access to specific 1321 portions of conceptual data and operations within this module is 1322 provided by the NETCONF access control model (NACM) [RFC6536]. 1324 There are a number of data nodes defined in this YANG module which 1325 are writable/creatable/deletable (i.e., config true, which is the 1326 default). These data nodes may be considered sensitive or vulnerable 1327 in some network environments. Write operations to these data nodes 1328 can have a negative effect on network operations. It is thus 1329 important to control write access (e.g., via edit-config) to these 1330 data nodes. These are the subtrees and data nodes and their 1331 sensitivity/vulnerability: 1333 o /system/clock/timezone: This choice contains the objects used to 1334 control the timezone used by the device. 1336 o /system/ntp: This container contains the objects used to control 1337 the Network Time Protocol servers used by the device. 1339 o /system/dns-resolver: This container contains the objects used to 1340 control the Domain Name System servers used by the device. 1342 o /system/radius: This container contains the objects used to 1343 control the Remote Authentication Dial-In User Service servers 1344 used by the device. 1346 o /system/authentication/user-authentication-order: This leaf 1347 controls how user login attempts are authenticated by the device. 1349 o /system/authentication/user: This list contains the local users 1350 enabled on the system. 1352 Some of the readable data nodes in this YANG module may be considered 1353 sensitive or vulnerable in some network environments. It is thus 1354 important to control read access (e.g., via get, get-config, or 1355 notification) to these data nodes. These are the subtrees and data 1356 nodes and their sensitivity/vulnerability: 1358 o /system/platform: This container has objects which may help 1359 identify the specific NETCONF server and/or operating system 1360 implementation used on the device. 1362 o /system/authentication/user: This list has objects that may help 1363 identify the specific user names and password information in use 1364 on the device. 1366 Some of the remote procedure call (RPC) operations in this YANG 1367 module may be considered sensitive or vulnerable in some network 1368 environments. It is thus important to control access to these 1369 operations. These are the operations and their sensitivity/ 1370 vulnerability: 1372 o set-current-datetime: Changes the current date and time on the 1373 device. 1375 o system-restart: Reboots the device. 1377 o system-shutdown: Shuts down the device. 1379 This YANG model defines a type "crypt-hash" that can be used to store 1380 MD5 hashes. [RFC6151] discusses security considerations for MD5. 1381 The usage of MD5 is NOT RECOMMENDED. 1383 8. Change Log 1385 -- RFC Ed.: remove this section before publication. 1387 8.1. 00-01 1389 o added configuration-source identities 1391 o added configuration-source leaf to ntp and dns (via grouping) to 1392 choose configuration source 1394 o added association-type, iburst, prefer, and true leafs to the ntp- 1395 server list 1397 o extended the ssh keys for a user to a list of keys. support all 1398 defined key algorithms, not just dsa and rsa 1400 o clarified timezone-utc-offset description-stmt 1402 o removed '/system/ntp/server/true' leaf from data model 1404 8.2. 01-02 1406 o added default-stmts to ntp-server/iburst and ntp-server/prefer 1407 leafs 1409 o changed timezone-location leaf to use iana-timezone typedef 1410 instead of a string 1412 8.3. 02-03 1414 o removed configuration-source identities and leafs 1416 8.4. 03-04 1418 o removed ndots dns resolver option 1420 o added radius-authentication-type identity, and identities for pap 1421 and chap, and a leaf to control which authentication type to use 1422 when communicating with the radius server 1424 o made 0 an invalid value for timeouts and attempts 1426 8.5. 04-05 1428 o updated tree diagram explanation text 1430 8.6. 05-06 1432 o changed ntp/use-ntp to ntp/enabled 1434 o changed ntp/ntp-server to ntp/server 1436 o removed /system/platform/nodename leaf 1438 o changed /system/name to /system/hostname 1440 o simplified must expression in user-authentication-order 1442 o added optional rounds to sha hash definition 1444 o clarified the crypt-hash description 1446 o clarified ntp descriptions 1448 o clarified YANG module description to indicate that some system 1449 properties are supported, not the entire system 1451 o clarified that system identification values are vendor specific, 1452 not the data node objects 1454 o clarified sec. 2.2 and 2.3 to indicate that the server should also 1455 be capable of configuring these properties 1457 o changed /system/dns/search from inet:host to inet:domain-name 1459 o changed RFC6021 reference to 6021-bis 1461 o changed /system/platform/nodename to /system/platform/hostname 1463 o changed /system/radius/server/{leafs} to be within a choice and 1464 'udp' case statement so other transport specific parameters can 1465 augment this list or they can be added by the WG to a future 1466 version of this module. {leafs} are authentication-port and 1467 shared-secret. 1469 o updated YANG tree diagrams for objects added in -05 and -06 1471 8.7. 06-07 1473 o updated the Abstract and Introduction 1475 o updated Tree diagram notation 1476 o identify all external servers (dns, ntp, radius) by name instead 1477 of address, in order to make the data model extensible for 1478 additional transport protocol. 1480 o updated the Security Considerations section with a reference to 1481 NACM. 1483 8.8. 07-08 1485 o renamed the DNS transport to 'udp-and-tcp' and added references. 1487 o moved the operational state nodes into /system-state. 1489 8.9. 08-09 1491 o made "ntp" node a presence container 1493 o added reference to RFC 6151 1495 o updated reference from 6021-bis to RFC 6991 1497 o cleaned up usage of config false in the YANG module 1499 8.10. 09-10 1501 o clarified relationship with SNMPv2-MIB 1503 8.11. 11-12 1505 o added typedef "timezone-name", and removed reference to 1506 draft-ietf-netmod-iana-timezones 1508 9. References 1510 9.1. Normative References 1512 [FIPS.180-3.2008] 1513 National Institute of Standards and Technology, "Secure 1514 Hash Standard", FIPS PUB 180-3, October 2008, . 1518 [IEEE-1003.1-2008] 1519 Institute of Electrical and Electronics Engineers, 1520 "POSIX.1-2008", IEEE Standard 1003.1, March 2008. 1522 [RFC1035] Mockapetris, P., "Domain names - implementation and 1523 specification", STD 13, RFC 1035, November 1987. 1525 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 1526 April 1992. 1528 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1529 Requirement Levels", BCP 14, RFC 2119, March 1997. 1531 [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, 1532 "Remote Authentication Dial In User Service (RADIUS)", 1533 RFC 2865, June 2000. 1535 [RFC3418] Presuhn, R., "Management Information Base (MIB) for the 1536 Simple Network Management Protocol (SNMP)", STD 62, 1537 RFC 3418, December 2002. 1539 [RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 1540 Authentication Protocol", RFC 4252, January 2006. 1542 [RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 1543 Transport Layer Protocol", RFC 4253, January 2006. 1545 [RFC5607] Nelson, D. and G. Weber, "Remote Authentication Dial-In 1546 User Service (RADIUS) Authorization for Network Access 1547 Server (NAS) Management", RFC 5607, July 2009. 1549 [RFC5966] Bellis, R., "DNS Transport over TCP - Implementation 1550 Requirements", RFC 5966, August 2010. 1552 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1553 Network Configuration Protocol (NETCONF)", RFC 6020, 1554 October 2010. 1556 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 1557 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 1558 RFC 6151, March 2011. 1560 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1561 and A. Bierman, Ed., "Network Configuration Protocol 1562 (NETCONF)", RFC 6241, June 2011. 1564 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1565 Shell (SSH)", RFC 6242, June 2011. 1567 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1568 Protocol (NETCONF) Access Control Model", RFC 6536, 1569 March 2012. 1571 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1572 July 2013. 1574 9.2. Informative References 1576 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1577 January 2004. 1579 [RFC6557] Lear, E. and P. Eggert, "Procedures for Maintaining the 1580 Time Zone Database", BCP 175, RFC 6557, February 2012. 1582 Authors' Addresses 1584 Andy Bierman 1585 YumaWorks 1587 Email: andy@yumaworks.com 1589 Martin Bjorklund 1590 Tail-f Systems 1592 Email: mbj@tail-f.com