idnits 2.17.1 draft-ietf-netmod-system-mgmt-12.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 13, 2014) is 3724 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 17, 2014 Tail-f Systems 6 February 13, 2014 8 A YANG Data Model for System Management 9 draft-ietf-netmod-system-mgmt-12 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 17, 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-13.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 import iana-timezones { 441 prefix ianatz; 442 } 444 organization 445 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 447 contact 448 "WG Web: 449 WG List: 451 WG Chair: Thomas Nadeau 452 454 WG Chair: Juergen Schoenwaelder 455 457 Editor: Andy Bierman 458 460 Editor: Martin Bjorklund 461 "; 463 description 464 "This module contains a collection of YANG definitions for the 465 configuration and identification of some common system 466 properties within a device containing a NETCONF server. This 467 includes data node definitions for system identification, 468 time-of-day management, user management, DNS resolver 469 configuration, and some protocol operations for system 470 management. 472 Copyright (c) 2014 IETF Trust and the persons identified as 473 authors of the code. All rights reserved. 475 Redistribution and use in source and binary forms, with or 476 without modification, is permitted pursuant to, and subject 477 to the license terms contained in, the Simplified BSD License 478 set forth in Section 4.c of the IETF Trust's Legal Provisions 479 Relating to IETF Documents 480 (http://trustee.ietf.org/license-info). 482 This version of this YANG module is part of RFC XXXX; see 483 the RFC itself for full legal notices."; 485 // RFC Ed.: replace XXXX with actual RFC number and remove this 486 // note. 488 // RFC Ed.: remove this note 489 // Note: extracted from draft-ietf-netmod-system-mgmt-07.txt 491 // RFC Ed.: update the date below with the date of RFC publication 492 // and remove this note. 493 revision "2014-02-13" { 494 description 495 "Initial revision."; 496 reference 497 "RFC XXXX: A YANG Data Model for System Management"; 498 } 500 /* 501 * Typedefs 502 */ 504 typedef timezone-name { 505 type string; 506 description 507 "A timezone name as used by the Time Zone Database, sometimes 508 referred to as the 'Olson Database'. 510 The exact set of valid values is an implementation-specific 511 matter. Client discovery of the exact set of time zone names 512 for a particular server is out of scope."; 513 reference 514 "RFC 6557: Procedures for Maintaining the Time Zone Database"; 515 } 517 typedef crypt-hash { 518 type string { 519 pattern 520 '$0$.*' 521 + '|$1$[a-zA-Z0-9./]{1,8}$[a-zA-Z0-9./]{22}' 522 + '|$5$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{43}' 523 + '|$6$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{86}'; 524 } 525 description 526 "The crypt-hash type is used to store passwords using 527 a hash function. The algorithms for applying the hash 528 function and encoding the result are implemented in 529 various UNIX systems as the function crypt(3). 531 A value of this type matches one of the forms: 533 $0$ 534 $$$ 535 $$$$ 537 The '$0$' prefix signals that the value is clear text. When 538 such a value is received by the server, a hash value is 539 calculated, and the string '$$$' or 540 $$$$ is prepended to the result. This 541 value is stored in the configuration data store. 543 If a value starting with '$$', where is not '0', is 544 received, the server knows that the value already represents a 545 hashed value, and stores it as is in the data store. 547 When a server needs to verify a password given by a user, it 548 finds the stored password hash string for that user, extracts 549 the salt, and calculates the hash with the salt and given 550 password as input. If the calculated hash value is the same 551 as the stored value, the password given by the client is 552 accepted. 554 This type defines the following hash functions: 556 id | hash function | feature 557 ---+---------------+------------------- 558 1 | MD5 | crypt-hash-md5 559 5 | SHA-256 | crypt-hash-sha-256 560 6 | SHA-512 | crypt-hash-sha-512 562 The server indicates support for the different hash functions 563 by advertising the corresponding feature."; 564 reference 565 "IEEE Std 1003.1-2008 - crypt() function 566 Wikipedia: http://en.wikipedia.org/wiki/Crypt_(C) 567 RFC 1321: The MD5 Message-Digest Algorithm 568 FIPS.180-3.2008: Secure Hash Standard"; 569 } 571 /* 572 * Features 573 */ 575 feature radius { 576 description 577 "Indicates that the device can be configured as a RADIUS 578 client."; 579 reference 580 "RFC 2865: Remote Authentication Dial In User Service " 581 + "(RADIUS)"; 582 } 584 feature authentication { 585 description 586 "Indicates that the device supports configuration 587 for user authentication."; 588 } 590 feature local-users { 591 if-feature authentication; 592 description 593 "Indicates that the device supports configuration of 594 local user authentication."; 595 } 597 feature radius-authentication { 598 if-feature radius; 599 if-feature authentication; 600 description 601 "Indicates that the device supports configuration of user 602 authentication over RADIUS."; 603 reference 604 "RFC 2865: Remote Authentication Dial In User Service (RADIUS) 605 RFC 5607: Remote Authentication Dial-In User Service (RADIUS) 606 Authorization for Network Access Server (NAS) 607 Management"; 608 } 610 feature crypt-hash-md5 { 611 description 612 "Indicates that the device supports the MD5 613 hash function in 'crypt-hash' values"; 614 reference "RFC 1321: The MD5 Message-Digest Algorithm"; 615 } 617 feature crypt-hash-sha-256 { 618 description 619 "Indicates that the device supports the SHA-256 620 hash function in 'crypt-hash' values"; 621 reference "FIPS.180-3.2008: Secure Hash Standard"; 622 } 624 feature crypt-hash-sha-512 { 625 description 626 "Indicates that the device supports the SHA-512 627 hash function in 'crypt-hash' values"; 628 reference "FIPS.180-3.2008: Secure Hash Standard"; 629 } 631 feature ntp { 632 description 633 "Indicates that the device can be configured 634 to use one or more NTP servers to set the 635 system date and time."; 636 } 638 feature ntp-udp-port { 639 description 640 "Indicates that the device supports the configuration of 641 the UDP port for NTP servers. 643 This is a 'feature' since many implementations do not support 644 any other port than the default port."; 645 } 647 feature timezone-name { 648 description 649 "Indicates that the local timezone on the device 650 can be configured to use the TZ database 651 to set the timezone and manage daylight savings time."; 653 reference 654 "RFC 6557: Procedures for Maintaining the Time Zone Database"; 655 } 657 feature dns-udp-tcp-port { 658 description 659 "Indicates that the device supports the configuration of 660 the UDP and TCP port for DNS servers. 662 This is a 'feature' since many implementations do not support 663 any other port than the default port."; 664 } 666 /* 667 * Identities 668 */ 670 identity authentication-method { 671 description 672 "Base identity for user authentication methods."; 673 } 675 identity radius { 676 base authentication-method; 677 description 678 "Indicates user authentication using RADIUS."; 679 reference 680 "RFC 2865: Remote Authentication Dial In User Service (RADIUS) 681 RFC 5607: Remote Authentication Dial-In User Service (RADIUS) 682 Authorization for Network Access Server (NAS) 683 Management"; 684 } 686 identity local-users { 687 base authentication-method; 688 description 689 "Indicates password-based authentication of locally 690 configured users."; 691 } 693 identity radius-authentication-type { 694 description 695 "Base identity for RADIUS authentication types."; 696 } 698 identity radius-pap { 699 base radius-authentication-type; 700 description 701 "The device requests PAP authentication from the RADIUS 702 server."; 703 reference 704 "RFC 2865: Remote Authentication Dial In User Service"; 705 } 707 identity radius-chap { 708 base radius-authentication-type; 709 description 710 "The device requests CHAP authentication from the RADIUS 711 server."; 712 reference 713 "RFC 2865: Remote Authentication Dial In User Service"; 714 } 716 /* 717 * Configuration data nodes 718 */ 720 container system { 721 description 722 "System group configuration."; 724 leaf contact { 725 type string; 726 description 727 "The administrator contact information for the system. 729 A server implementation MAY map this leaf to the sysContact 730 MIB object. Such an implementation needs to use some 731 mechanism to handle the differences in size and characters 732 allowed between this leaf and sysContact. The definition of 733 such a mechanism is outside the scope of this document."; 734 reference 735 "RFC 3418: Management Information Base (MIB) for the 736 Simple Network Management Protocol (SNMP) 737 SNMPv2-MIB.sysContact"; 738 } 739 leaf hostname { 740 type inet:domain-name; 741 description 742 "The name of the host. This name can be a single domain 743 label, or the fully qualified domain name of the host."; 744 } 745 leaf location { 746 type string; 747 description 748 "The system location. 750 A server implementation MAY map this leaf to the sysLocation 751 MIB object. Such an implementation needs to use some 752 mechanism to handle the differences in size and characters 753 allowed between this leaf and sysLocation. The definition 754 of such a mechanism is outside the scope of this document."; 755 reference 756 "RFC 3418: Management Information Base (MIB) for the 757 Simple Network Management Protocol (SNMP) 758 SNMPv2-MIB.sysLocation"; 759 } 761 container clock { 762 description 763 "Configuration of the system date and time properties."; 765 choice timezone { 766 description 767 "The system timezone information."; 769 case timezone-name { 770 if-feature timezone-name; 771 leaf timezone-name { 772 type timezone-name; 773 description 774 "The TZ database name to use for the system, such 775 as 'Europe/Stockholm'."; 776 } 777 } 778 case timezone-utc-offset { 779 leaf timezone-utc-offset { 780 type int16 { 781 range "-1500 .. 1500"; 782 } 783 units "minutes"; 784 description 785 "The number of minutes to add to UTC time to 786 identify the timezone for this system. For example, 787 'UTC - 8:00 hours' would be represented as '-480'. 788 Note that automatic daylight savings time adjustment 789 is not provided, if this object is used."; 790 } 791 } 792 } 793 } 795 container ntp { 796 if-feature ntp; 797 presence 798 "Enables the NTP client unless the 'enabled' leaf 799 (which defaults to 'true') is set to 'false'"; 800 description 801 "Configuration of the NTP client."; 803 leaf enabled { 804 type boolean; 805 default true; 806 description 807 "Indicates that the system should attempt 808 to synchronize the system clock with an 809 NTP server from the 'ntp/server' list."; 810 } 811 list server { 812 key name; 813 description 814 "List of NTP servers to use for 815 system clock synchronization. If '/system/ntp/enabled' 816 is 'true', then the system will attempt to 817 contact and utilize the specified NTP servers."; 819 leaf name { 820 type string; 821 description 822 "An arbitrary name for the NTP server."; 823 } 824 choice transport { 825 mandatory true; 826 description 827 "The transport protocol specific parameters for this 828 server."; 830 case udp { 831 container udp { 832 description 833 "Contains UDP specific configuration parameters 834 for NTP."; 835 leaf address { 836 type inet:host; 837 mandatory true; 838 description 839 "The address of the NTP server."; 840 } 841 leaf port { 842 if-feature ntp-udp-port; 843 type inet:port-number; 844 default 123; 845 description 846 "The port number of the NTP server."; 847 } 848 } 849 } 850 } 851 leaf association-type { 852 type enumeration { 853 enum server { 854 description 855 "Use client association mode. This device 856 will not provide synchronization to the 857 configured NTP server."; 858 } 859 enum peer { 860 description 861 "Use symmetric active association mode. 862 This device may provide synchronization 863 to the configured NTP server."; 864 } 865 enum pool { 866 description 867 "Use client association mode with one or 868 more of the NTP servers found by DNS 869 resolution of the domain name given by 870 the 'address' leaf. This device will not 871 provide synchronization to the servers."; 872 } 873 } 874 default server; 875 description 876 "The desired association type for this NTP server."; 877 } 878 leaf iburst { 879 type boolean; 880 default false; 881 description 882 "Indicates whether this server should enable burst 883 synchronization or not."; 884 } 885 leaf prefer { 886 type boolean; 887 default false; 888 description 889 "Indicates whether this server should be preferred 890 or not."; 891 } 892 } 893 } 894 container dns-resolver { 895 description 896 "Configuration of the DNS resolver."; 898 leaf-list search { 899 type inet:domain-name; 900 ordered-by user; 901 description 902 "An ordered list of domains to search when resolving 903 a host name."; 904 } 905 list server { 906 key name; 907 ordered-by user; 908 description 909 "List of the DNS servers that the resolver should query. 911 When the resolver is invoked by a calling application, it 912 sends the query to the first name server in this list. If 913 no response has been received within 'timeout' seconds, 914 the resolver continues with the next server in the list. 915 If no response is received from any server, the resolver 916 continues with the first server again. When the resolver 917 has traversed the list 'attempts' times without receiving 918 any response, it gives up and returns an error to the 919 calling application. 921 Implementations MAY limit the number of entries in this 922 list."; 924 leaf name { 925 type string; 926 description 927 "An arbitrary name for the DNS server."; 928 } 929 choice transport { 930 mandatory true; 931 description 932 "The transport protocol specific parameters for this 933 server."; 935 case udp-and-tcp { 936 container udp-and-tcp { 937 description 938 "Contains UDP and TCP specific configuration 939 parameters for DNS."; 940 reference 941 "RFC 1035: Domain Implementation and Specification 942 RFC 5966: DNS over TCP"; 944 leaf address { 945 type inet:ip-address; 946 mandatory true; 947 description 948 "The address of the DNS server."; 949 } 950 leaf port { 951 if-feature dns-udp-tcp-port; 952 type inet:port-number; 953 default 53; 954 description 955 "The UDP and TCP port number of the DNS server."; 956 } 957 } 958 } 959 } 960 } 961 container options { 962 description 963 "Resolver options. The set of available options has been 964 limited to those that are generally available across 965 different resolver implementations, and generally 966 useful."; 967 leaf timeout { 968 type uint8 { 969 range "1..max"; 970 } 971 units "seconds"; 972 default "5"; 973 description 974 "The amount of time the resolver will wait for a 975 response from each remote name server before 976 retrying the query via a different name server."; 977 } 978 leaf attempts { 979 type uint8 { 980 range "1..max"; 981 } 982 default "2"; 983 description 984 "The number of times the resolver will send a query to 985 all its name servers before giving up and returning an 986 error to the calling application."; 987 } 988 } 989 } 990 container radius { 991 if-feature radius; 993 description 994 "Configuration of the RADIUS client."; 996 list server { 997 key name; 998 ordered-by user; 999 description 1000 "List of RADIUS servers used by the device. 1002 When the RADIUS client is invoked by a calling 1003 application, it sends the query to the first server in 1004 this list. If no response has been received within 1005 'timeout' seconds, the client continues with the next 1006 server in the list. If no response is received from any 1007 server, the client continues with the first server again. 1008 When the client has traversed the list 'attempts' times 1009 without receiving any response, it gives up and returns an 1010 error to the calling application."; 1012 leaf name { 1013 type string; 1014 description 1015 "An arbitrary name for the RADIUS server."; 1016 } 1017 choice transport { 1018 mandatory true; 1019 description 1020 "The transport protocol specific parameters for this 1021 server."; 1023 case udp { 1024 container udp { 1025 description 1026 "Contains UDP specific configuration parameters 1027 for RADIUS."; 1028 leaf address { 1029 type inet:host; 1030 mandatory true; 1031 description 1032 "The address of the RADIUS server."; 1033 } 1034 leaf authentication-port { 1035 type inet:port-number; 1036 default "1812"; 1037 description 1038 "The port number of the RADIUS server."; 1039 } 1040 leaf shared-secret { 1041 type string; 1042 mandatory true; 1043 nacm:default-deny-all; 1044 description 1045 "The shared secret which is known to both the 1046 RADIUS client and server."; 1047 reference 1048 "RFC 2865: Remote Authentication Dial In User 1049 Service"; 1050 } 1051 } 1052 } 1053 } 1054 leaf authentication-type { 1055 type identityref { 1056 base radius-authentication-type; 1057 } 1058 default radius-pap; 1059 description 1060 "The authentication type requested from the RADIUS 1061 server."; 1062 } 1063 } 1064 container options { 1065 description 1066 "RADIUS client options."; 1068 leaf timeout { 1069 type uint8 { 1070 range "1..max"; 1071 } 1072 units "seconds"; 1073 default "5"; 1074 description 1075 "The number of seconds the device will wait for a 1076 response from each RADIUS server before trying with a 1077 different server."; 1078 } 1079 leaf attempts { 1080 type uint8 { 1081 range "1..max"; 1082 } 1083 default "2"; 1084 description 1085 "The number of times the device will send a query to 1086 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 } 1183 } 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