idnits 2.17.1 draft-bierman-netconf-system-monitoring-00.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 388 has weird spacing: '...startup confi...' == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (June 11, 2010) is 5067 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) == Unused Reference: 'RFC3688' is defined on line 663, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netmod-yang-types' is defined on line 677, but no explicit reference was found in the text == Unused Reference: 'RFC3418' is defined on line 684, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF A. Bierman 3 Internet-Draft InterWorking Labs 4 Intended status: Standards Track June 11, 2010 5 Expires: December 13, 2010 7 NETCONF System Monitoring 8 draft-bierman-netconf-system-monitoring-00 10 Abstract 12 The NETCONF protocol provides mechanisms to manipulate configuration 13 datastores. However, client applications often need to examine 14 system information to determine the appropriate configuration 15 requirements. In addition, common system events such as a change in 16 system capabilities may impact management applications. Standard 17 mechanisms are needed to support the monitoring of the managed system 18 supported by a NETCONF server. This document defines a YANG module 19 for the monitoring of system information, which allows a NETCONF 20 client to identify system properties and receive notifications for 21 system events. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on December 13, 2010. 40 Copyright Notice 42 Copyright (c) 2010 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. YANG Module for System Monitoring . . . . . . . . . . . . . . 3 60 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2.1.1. Container . . . . . . . . . . . . . . . . . . 4 62 2.1.2. Notifications . . . . . . . . . . . . . . . . . . . . 4 63 2.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 64 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 65 4. Security Considerations . . . . . . . . . . . . . . . . . . . 15 66 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 67 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 68 6.1. Normative References . . . . . . . . . . . . . . . . . . . 15 69 6.2. Informative References . . . . . . . . . . . . . . . . . . 16 70 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 16 71 A.1. 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 74 1. Introduction 76 The NETCONF protocol [RFC4741] provides mechanisms to manipulate 77 configuration datastores. However, client applications often need to 78 examine system information to determine the appropriate configuration 79 requirements. In addition, common system events such as a change in 80 system capabilities may impact management applications. Standard 81 mechanisms are needed to support the monitoring of the managed system 82 supported by a NETCONF server. This document defines a YANG module 83 [I-D.ietf-netmod-yang] for the monitoring of system information, 84 which allows a NETCONF client to identify system properties and 85 receive notifications [RFC5277] for system events. 87 1.1. Terminology 89 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 90 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 91 document are to be interpreted as described in [RFC2119]. 93 The following terms are defined in [RFC4741]: 94 o client 95 o datastore 96 o operation 97 o server 99 The following terms are defined in [RFC5277]: 100 o event 101 o stream 102 o subscription 104 The following term is defined in [I-D.ietf-netmod-yang]: 105 o data node 107 2. YANG Module for System Monitoring 109 2.1. Overview 111 The following YANG module defines data node definitions suitable for 112 use with NETCONF operations such as , , and . In addition, a small number of system events are defined 114 for use within the NETCONF stream, and accessible to clients via the 115 subscription mechanism in [RFC5277]. 117 The YANG language is defined in [I-D.ietf-netmod-yang]. The NETCONF 118 operations are defined in YANG in [RFC4741]. 120 2.1.1. Container 122 The element provides commonly used vendor-specific 123 information to identify and control a managed system: 124 o sys-name: The name of the managed system. 125 o sys-current-date-and-time: The current time as known to the 126 managed system. 127 o sys-boot-date-and-time: The time when the system last restarted. 128 o sys-server-id: A vendor-specific string identifying the NETCONF 129 server implementation. 130 o uname: A container of common system naming information, such as 131 the release, version, machine, and nodename of the system. 133 2.1.2. Notifications 135 This module defines some system events to notify a client application 136 that the system state has changed. 137 o sys-startup: Generated during a system restart. Lists any errors 138 that were encountered while loading the datastore during 139 system initialization. 140 o sys-config-change: Generated when the configuration 141 datastore is changed. Summarizes each edit being reported. 142 o sys-capability-change: Generated when the NETCONF server 143 capabilities are changed. Indicates which capabilities have been 144 added, deleted, and/or modified. 145 o sys-session-start: Generated when the NETCONF session is started. 146 Indicates the identity of the user that started the session. 147 o sys-session-end: Generated when the NETCONF session is terminated. 148 Indicates the identity of the user that owned the session, and why 149 the session was terminated. 150 o sys-conformed-commit: Generated when the NETCONF confirmed-commit 151 event occurs. Indicates the current state of the confirmed-commit 152 operation in progress. 154 2.2. Definitions 156 file="netconf-system@2010-06-10.yang" 158 module netconf-system { 160 namespace "urn:ietf:params:xml:ns:yang:netconf-system"; 162 prefix ncsys; 164 import ietf-yang-types { prefix yang; } 165 import ietf-inet-types { prefix inet; } 166 organization 167 "IETF NETCONF (Network Configuration Protocol) Working Group"; 169 contact 170 "WG Web: 171 WG List: 173 WG Chair: Bert Wijnen 174 176 WG Chair: Mehmet Ersue 177 179 Editor: Andy Bierman 180 "; 182 description 183 "This module defines an YANG data model for use with the 184 NETCONF protocol that allows the NETCONF client to monitor 185 common system information and receive common system events. 187 Copyright (c) 2010 IETF Trust and the persons identified as 188 the document authors. All rights reserved. 190 Redistribution and use in source and binary forms, with or 191 without modification, is permitted pursuant to, and subject 192 to the license terms contained in, the Simplified BSD License 193 set forth in Section 4.c of the IETF Trust's Legal Provisions 194 Relating to IETF Documents 195 (http://trustee.ietf.org/license-info). 197 This version of this YANG module is part of RFC XXXX; see 198 the RFC itself for full legal notices."; 199 // RFC Ed.: replace XXXX with actual RFC number and remove this note 201 // RFC Ed.: remove this note 202 // Note: extracted from draft-bierman-netconf-system-00.txt 204 revision 2010-06-10 { 205 description 206 "Initial version."; 207 reference 208 "RFC XXXX: NETCONF System Monitoring"; 209 } 210 // RFC Ed.: replace XXXX with actual 211 // RFC number and remove this note 213 typedef error-type-type { 214 description "NETCONF Error Type"; 215 type enumeration { 216 enum transport { 217 description "Transport layer error"; 218 } 219 enum rpc { 220 description "Operation layer error"; 221 } 222 enum protocol { 223 description "Protocol layer error"; 224 } 225 enum application { 226 description "Application layer error"; 227 } 228 } 229 } 231 typedef error-tag-type { 232 description "NETCONF Error Tag"; 233 type enumeration { 234 // descriptions TBD; normative text in RFC 4741 235 enum in-use; 236 enum invalid-value; 237 enum too-big; 238 enum missing-attribute; 239 enum bad-attribute; 240 enum unknown-attribute; 241 enum missing-element; 242 enum bad-element; 243 enum unknown-element; 244 enum unknown-namespace; 245 enum access-denied; 246 enum lock-denied; 247 enum resource-denied; 248 enum rollback-failed; 249 enum data-exists; 250 enum data-missing; 251 enum operation-not-supported; 252 enum operation-failed; 253 enum partial-operation; 254 } 255 } 257 typedef error-severity-type { 258 description "NETCONF Error Severity"; 259 type enumeration { 260 enum error { 261 description "Error severity"; 263 } 264 enum warning { 265 description "Warning severity"; 266 } 267 } 268 } 270 typedef edit-operation-type { 271 description 272 "NETCONF 'operation' Attribute values"; 273 type enumeration { 274 enum merge; 275 enum replace; 276 enum create; 277 enum delete; 278 } 279 default "merge"; 280 } 282 grouping sys-common-session-parms { 284 leaf user-name { 285 description 286 "Name of the user for the session."; 287 type string; 288 } 290 leaf session-id { 291 description "Identifier of the session."; 292 type uint32; // nc:session-id-or-zero-type; 293 mandatory true; 294 } 296 leaf remote-host { 297 description 298 "Address of the remote host for the session."; 299 type inet:ip-address; 300 } 301 } 303 container system { 304 description 305 "Basic objects for NETCONF system identification."; 307 config false; 309 leaf sys-name { 310 description "The system name."; 311 reference "RFC 3418, sysName object"; 312 type string; 313 mandatory true; 314 } 316 leaf sys-current-date-time { 317 description 318 "The current system date and time."; 319 type yang:date-and-time; 320 mandatory true; 321 } 323 leaf sys-boot-date-time { 324 description 325 "The system date and time when the system 326 last restarted."; 327 type yang:date-and-time; 328 mandatory true; 329 } 331 leaf sys-server-id { 332 description 333 "The vendor-specific name and version ID string 334 for the NETCONF server running on this system."; 335 type string; 336 mandatory true; 337 } 339 container uname { 340 description 341 "Contains the broken out fields from the 342 output of the 'uname' command on this machine."; 343 leaf sysname { 344 type string; 345 description 346 "The name of the operating system in use."; 347 } 349 leaf release { 350 type string; 351 description 352 "The current release level of the operating 353 system in use."; 354 } 356 leaf version { 357 type string; 358 description 359 "The current version level of the operating 360 system in use."; 361 } 363 leaf machine { 364 type string; 365 description "A description of the hardware in use."; 366 } 368 leaf nodename { 369 type string; 370 description 371 "The host name of this system, as reported by 372 the uname command."; 373 } 374 } // container uname 375 } // container system 377 notification sys-startup { 378 description 379 "Generated when the system restarts. 380 Used for logging purposes, since no 381 sessions are actually active when 382 the system restarts."; 384 leaf startup-source { 385 description 386 "The system-specific filespec used to load the 387 running configuration. This leaf will only be 388 present if there was a startup configuration file used."; 389 type string; 390 } 392 list boot-error { 393 description 394 "There will be one entry for each 395 encountered during the load config operation. 396 There is no particular order, so no key is defined. 397 This list will only be present if the server is configured 398 to continue on error during startup, and there were recoverable 399 errors encountered during the last restart of the server."; 401 leaf error-type { 402 description 403 "Defines the conceptual layer that the error occurred."; 404 type error-type-type; 405 mandatory true; 407 } 409 leaf error-tag { 410 description 411 "Contains a string identifying the error condition."; 412 type error-tag-type; 413 mandatory true; 414 } 416 leaf error-severity { 417 description 418 "Contains a string identifying the error severity, as 419 determined by the device."; 420 type error-severity-type; 421 mandatory true; 422 } 424 leaf error-app-tag { 425 description 426 "Contains a string identifying the data-model-specific 427 or implementation-specific error condition, if one exists."; 428 type string; 429 } 431 leaf error-path { 432 description 433 "Contains the absolute XPath expression identifying 434 the element path to the node that is associated with 435 the error being reported in a particular 436 element."; 437 type yang:xpath1.0; 438 } 440 leaf error-message { 441 description 442 "Contains a string suitable for human display that 443 describes the error condition."; 444 type string; // LangString; 445 } 447 anyxml error-info { 448 description 449 "Contains protocol- or data-model-specific error content."; 450 } 451 } // list boot-error 452 } // notification sys-startup 453 notification sys-config-change { 454 description 455 "Generated when the configuration is changed."; 456 uses sys-common-session-parms; 458 list edit { 459 description 460 "An edit record will be present for each distinct 461 edit operation on the running config."; 462 leaf target { 463 type instance-identifier; 464 description 465 "Topmost node associated with the configuration change."; 466 } 468 leaf operation { 469 type edit-operation-type; 470 description "Type of edit operation performed."; 471 } 472 } // list edit 473 } // notification sys-config-change 475 notification sys-capability-change { 476 description 477 "Generated when a is added, deleted, 478 or modified."; 479 container changed-by { 480 description 481 "Indicates who caused this capability change. 482 If caused by internal action, then the 483 empty leaf 'server' will be present. 484 If caused by a management session, then 485 the name, remote host address, and session ID 486 of the session that made the change will be reported."; 487 choice server-or-user { 488 leaf server { 489 type empty; 490 description 491 "If present, the capability change was caused 492 by the server."; 493 } 495 case by-user { 496 uses sys-common-session-parms; 497 } // case by-user 498 } // choice server-or-user 499 } // container changed-by 500 leaf-list added-capability { 501 type inet:uri; 502 description 503 "List of capabilities that have just been added."; 504 } 506 leaf-list deleted-capability { 507 type inet:uri; 508 description 509 "List of capabilities that have just been deleted."; 510 } 512 leaf-list modified-capability { 513 type inet:uri; 514 description 515 "List of capabilities that have just been modified."; 516 } 517 } // notification sys-capability-change 519 notification sys-session-start { 520 description 521 "Generated when a new NETCONF session is started."; 522 uses sys-common-session-parms; 523 } // notification sys-session-start 525 notification sys-session-end { 526 description 527 "Generated when a NETCONF session is terminated."; 528 uses sys-common-session-parms; 530 leaf killed-by { 531 when "../termination-reason = 'killed'"; 532 type uint32; // nc:session-id-type; 533 description 534 "Session ID that issued the 535 if the session was terminated by this operation."; 536 } 538 leaf termination-reason { 539 type enumeration { 540 enum "closed" { 541 value 0; 542 description 543 "The session was terminated with 544 the operation."; 545 } 546 enum "killed" { 547 value 1; 548 description 549 "The session was terminated with 550 the operation."; 551 } 552 enum "dropped" { 553 value 2; 554 description 555 "The session was terminated because 556 the SSH session or TCP connection was 557 unexpectedly closed."; 558 } 559 enum "timeout" { 560 value 3; 561 description 562 "The session was terminated because 563 of inactivity, either waiting for 564 the or messages."; 565 } 566 enum "bad-start" { 567 value 4; 568 description "The session startup sequence failed."; 569 } 570 enum "bad-hello" { 571 value 5; 572 description 573 "The client's message was 574 bad or never arrived."; 575 } 576 enum "other" { 577 value 6; 578 description 579 "The session was terminated for 580 some other reason."; 581 } 582 } 583 mandatory "true"; 584 description "Reason the session was terminated."; 585 } 586 } // notification sys-session-end 588 notification sys-confirmed-commit { 589 description 590 "Generated when a confirmed-commit event occurs."; 591 uses sys-common-session-parms; 592 leaf confirm-event { 593 description 594 "Indicates the event that caused the notification."; 595 type enumeration { 596 enum "start" { 597 value 0; 598 description 599 "The confirm-commit procedure has started."; 600 } 601 enum "cancel" { 602 value 1; 603 description 604 "The confirm-commit procedure has been canceled, 605 due to the session being terminated."; 606 } 607 enum "timeout" { 608 value 2; 609 description 610 "The confirm-commit procedure has been canceled, 611 due to the confirm-timeout interval expiring. 612 The common session parameters will not be present 613 in this sub-mode."; 614 } 615 enum "extend" { 616 value 3; 617 description 618 "The confirm-commit timeout has been extended."; 619 } 620 enum "complete" { 621 value 4; 622 description 623 "The confirm-commit procedure has been completed."; 624 } 625 } 626 mandatory "true"; 627 } 628 } // notification sys-confirmed-commit 630 } 632 634 3. IANA Considerations 636 TBD 638 4. Security Considerations 640 This document defines a YANG module for reporting of particular 641 system information and system events. Although unlikely, it is 642 possible that data obtained from this module could be used in an 643 attack of some kind, although no specific information in this module 644 is considered sensitive. 646 TBD: follow Security Consideration guidelines from new template text. 648 5. Acknowledgements 650 Some data node definitions in this document are based on information 651 provided by the unix 'uname' program (origin unknown). 653 This module is based on the yuma-system.yang module, which can be 654 found at: http://www.netconfcentral.org/modules/yuma-system. 656 6. References 658 6.1. Normative References 660 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 661 Requirement Levels", BCP 14, RFC 2119, March 1997. 663 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 664 January 2004. 666 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 667 December 2006. 669 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 670 Notifications", RFC 5277, July 2008. 672 [I-D.ietf-netmod-yang] 673 Bjorklund, M., "YANG - A data modeling language for the 674 Network Configuration Protocol (NETCONF)", 675 draft-ietf-netmod-yang-13 (work in progress), June 2010. 677 [I-D.ietf-netmod-yang-types] 678 Schoenwaelder, J., "Common YANG Data Types", 679 draft-ietf-netmod-yang-types-09 (work in progress), 680 April 2010. 682 6.2. Informative References 684 [RFC3418] Presuhn, R., "Management Information Base (MIB) for the 685 Simple Network Management Protocol (SNMP)", STD 62, 686 RFC 3418, December 2002. 688 Appendix A. Change Log 690 -- RFC Ed.: remove this section before publication. 692 A.1. 00 694 Initial version. 696 Author's Address 698 Andy Bierman 699 InterWorking Labs 700 Scotts Valley, CA 701 USA 703 Phone: +1 831 460 7010 704 Email: andyb@iwl.com