idnits 2.17.1 draft-ietf-netconf-monitoring-15.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 -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (Jun 22, 2010) is 5050 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) ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) ** Obsolete normative reference: RFC 4742 (Obsoleted by RFC 6242) ** Downref: Normative reference to an Historic RFC: RFC 4743 ** Downref: Normative reference to an Historic RFC: RFC 4744 ** Obsolete normative reference: RFC 5539 (Obsoleted by RFC 7589) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML-NAMES' -- Possible downref: Non-RFC (?) normative reference: ref. 'YANG' -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Scott 3 Internet-Draft Ericsson 4 Intended status: Standards Track M. Bjorklund 5 Expires: December 24, 2010 Tail-f Systems 6 Jun 22, 2010 8 YANG Module for NETCONF Monitoring 9 draft-ietf-netconf-monitoring-15 11 Abstract 13 This document defines a NETCONF data model to be used to monitor the 14 NETCONF protocol. The monitoring data model includes information 15 about NETCONF datastores, sessions, locks and statistics. This data 16 facilitates the management of a NETCONF server. This document also 17 defines methods for NETCONF clients to discover data models supported 18 by a NETCONF server and defines a new NETCONF operation 19 to retrieve them. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on December 24, 2010. 38 Copyright Notice 40 Copyright (c) 2010 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 This document may contain material from IETF Documents or IETF 54 Contributions published or made publicly available before November 55 10, 2008. The person(s) controlling the copyright in some of this 56 material may not have granted the IETF Trust the right to allow 57 modifications of such material outside the IETF Standards Process. 58 Without obtaining an adequate license from the person(s) controlling 59 the copyright in such materials, this document may not be modified 60 outside the IETF Standards Process, and derivative works of it may 61 not be created outside the IETF Standards Process, except to format 62 it for publication as an RFC or to translate it into languages other 63 than English. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 4 69 2. Data Model to Monitor NETCONF . . . . . . . . . . . . . . . . 5 70 2.1. The /netconf-state Subtree . . . . . . . . . . . . . . . . 5 71 2.1.1. The /netconf-state/capabilities Subtree . . . . . . . 6 72 2.1.2. The /netconf-state/datastores Subtree . . . . . . . . 6 73 2.1.3. The /netconf-state/schemas Subtree . . . . . . . . . . 6 74 2.1.4. The /netconf-state/sessions Subtree . . . . . . . . . 7 75 2.1.5. The /netconf-state/statistics Subtree . . . . . . . . 8 76 3. Schema Specific Operations . . . . . . . . . . . . . . . . . . 10 77 3.1. The Operation . . . . . . . . . . . . . . . . 10 78 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 79 4.1. Retrieving Schema List via Operation . . . . . . . . 11 80 4.2. Retrieving Schema Instances . . . . . . . . . . . . . . . 12 81 5. NETCONF Monitoring Data Model . . . . . . . . . . . . . . . . 15 82 6. Security Considerations . . . . . . . . . . . . . . . . . . . 27 83 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 28 84 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 85 9. Appendix A - Change Log . . . . . . . . . . . . . . . . . . . 30 86 9.1. draft-ietf-netconf-monitoring-14 . . . . . . . . . . . . . 30 87 9.2. draft-ietf-netconf-monitoring-13 . . . . . . . . . . . . . 30 88 9.3. draft-ietf-netconf-monitoring-12 . . . . . . . . . . . . . 30 89 9.4. draft-ietf-netconf-monitoring-11 . . . . . . . . . . . . . 31 90 9.5. draft-ietf-netconf-monitoring-10 . . . . . . . . . . . . . 33 91 9.6. draft-ietf-netconf-monitoring-09 . . . . . . . . . . . . . 33 92 9.7. draft-ietf-netconf-monitoring-08 . . . . . . . . . . . . . 34 93 9.8. draft-ietf-netconf-monitoring-07 . . . . . . . . . . . . . 34 94 9.9. draft-ietf-netconf-monitoring-06 . . . . . . . . . . . . . 34 95 9.10. draft-ietf-netconf-monitoring-05 . . . . . . . . . . . . . 34 96 9.11. draft-ietf-netconf-monitoring-04 . . . . . . . . . . . . . 35 97 9.12. draft-ietf-netconf-monitoring-03 . . . . . . . . . . . . . 35 98 9.13. draft-ietf-netconf-monitoring-02 . . . . . . . . . . . . . 35 99 9.14. draft-ietf-netconf-monitoring-01 . . . . . . . . . . . . . 35 100 9.15. draft-scott-netconf-monitoring-00 . . . . . . . . . . . . 36 101 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 37 102 10.1. Normative References . . . . . . . . . . . . . . . . . . . 37 103 10.2. Informative References . . . . . . . . . . . . . . . . . . 38 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 39 106 1. Introduction 108 This document defines a [YANG] model to be used to monitor the 109 NETCONF protocol. It provides information about NETCONF sessions and 110 supported schema as defined in [RFC4741]. 112 Considerations such as different schema formats, feature optionality 113 and access controls can all impact the applicability and level of 114 detail the NETCONF server sends to a client during session setup. 115 The methods defined in this document address the need for further 116 means to query and retrieve schema and NETCONF state information from 117 a NETCONF server. These are provided to complement existing base 118 NETCONF capabilities and operations and in no way affect existing 119 behaviour. 121 A new operation is also defined to support explicit 122 schema retrieval via NETCONF. 124 1.1. Definition of Terms 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 128 "OPTIONAL" in this document are to be interpreted as described in BCP 129 14, [RFC2119]. 131 2. Data Model to Monitor NETCONF 133 The NETCONF monitoring data model defined in this document provides 134 operational information on the NETCONF server. This includes details 135 specific to the NETCONF protocol (e.g., protocol specific counters 136 such as 'in-sessions') as well as data related to schema retrieval 137 (e.g., schema list). 139 A server that implements the data model defined in this document MUST 140 advertise the capability URI 141 "urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring", as described 142 in [YANG]. 144 This section presents an overview of the monitoring data model. For 145 detailed descriptions refer to the normative YANG module provided in 146 this document (see Section 5). 148 2.1. The /netconf-state Subtree 150 The netconf-state container is the root of the monitoring data model. 152 netconf-state 153 /capabilities 154 /datastores 155 /schemas 156 /sessions 157 /statistics 159 capabilities 160 List of NETCONF capabilities supported by the server. 162 datastores 163 List of NETCONF configuration datastores (e.g., running, startup, 164 candidate) supported on this device and related information. 166 schemas 167 List of schemas supported on the server. Includes all the 168 information required to identify the schemas and to support their 169 retrieval. 171 sessions 172 List of all active NETCONF sessions on the device. Includes per 173 session counters for all NETCONF sessions. 175 statistics 176 Includes global counters for the NETCONF server. 178 2.1.1. The /netconf-state/capabilities Subtree 180 The /netconf-state/capabilities subtree contains the capabilities 181 supported by the NETCONF server. The list MUST include all 182 capabilities exchanged during session setup still applicable at the 183 time of the request. 185 2.1.2. The /netconf-state/datastores Subtree 187 The /netconf-state/datastores subtree contains the list of available 188 datastores for the NETCONF server and includes information on their 189 lock state. 191 configuration 192 /name 193 /locks 195 name (leaf, netconf-datastore-type) 196 Enumeration of supported datastores; candidate, running, startup. 198 locks (grouping, lock-info) 199 List of locks for the datastore. Information is provided for both 200 global and partial locks [RFC5717]. For partial locks the list of 201 locked nodes and the select expressions originally used to request 202 the lock are returned. 204 2.1.3. The /netconf-state/schemas Subtree 206 The list of supported schema for the NETCONF server. 208 schema 209 /identifier (key) 210 /version (key) 211 /format (key) 212 /namespace 213 /location 215 The elements identifier, version, and format are used as a key in the 216 schema list. These are used in the operation. 218 identifier (string) 219 Identifier for the schema list entry. The identifier is used in 220 the operation and may be used for other means such as 221 file retrieval. 223 version (string) 224 Version of the schema supported. Multiple versions MAY be 225 supported simultaneously by a NETCONF server. Each version MUST 226 be reported individually in the schema list, i.e., with same 227 identifier, possibly different location, but different version. 229 For YANG data models, version is the value of the most recent YANG 230 'revision' statement in the module or submodule, or the empty 231 string if no revision statement is present. 233 format (identifyref, schema-format) 234 The data modeling language the schema is written in. The data 235 modeling language is represented as a YANG identity. This 236 document defines the identities "xsd", "yang", "yin", "rng" and 237 "rnc" (see Section 5). 239 namespace (inet:uri) 240 The Extensible Markup Language (XML) namespace [XML-NAMES] defined 241 by the schema. 243 location (union: enum, inet:uri) 244 One or more locations from which this specific schema can be 245 retrieved. The list SHOULD contain at least one entry per schema. 247 2.1.4. The /netconf-state/sessions Subtree 249 Includes session specific data for NETCONF management sessions. The 250 session list MUST include all currently active NETCONF sessions. 252 session 253 /session-id (key) 254 /transport 255 /username 256 /source-host 257 /login-time 258 /in-rpcs 259 /in-bad-rpcs 260 /out-rpc-errors 261 /out-notifications 263 session-id (uint32, 1..max) 264 Unique identifier for the session. This value is the NETCONF 265 session identifier, as defined in [RFC4741]. 267 transport (identityref, transport) 268 Identifies transport for each session. The transport is 269 represented as a YANG identity. This document defines the 270 identities "netconf-ssh", "netconf-soap-over-beep", "netconf-soap- 271 over-https", "netconf-beep", and "netconf-tls" (see Section 5). 273 username (string) 274 The username is the client identity that was authenticated by the 275 NETCONF transport protocol. The algorithm used to derive the 276 username is NETCONF transport protocol specific and in addition 277 specific to the authentication mechanism used by the NETCONF 278 transport protocol. 280 source-host (inet:host) 281 Host identifier (IP address or name) of the NETCONF client. 283 login-time (yang:date-and-time) 284 Time at the server at which the session was established. 286 in-rpcs (yang:zero-based-counter32) 287 Number of correct requests received. 289 in-bad-rpcs (yang:zero-based-counter32) 290 Number of messages received when a message was expected, 291 that were not correct messages. This includes XML parse 292 errors and errors on the rpc layer. 294 out-rpc-errors (yang:zero-based-counter32) 295 Number of messages sent which contained an 296 element. 298 out-notifications (yang:zero-based-counter32) 299 Number of messages sent. 301 2.1.5. The /netconf-state/statistics Subtree 303 Statistical data pertaining to the NETCONF server. 305 statistics 306 /netconf-start-time 307 /in-bad-hellos 308 /in-sessions 309 /dropped-sessions 310 /in-rpcs 311 /in-bad-rpcs 312 /out-rpc-errors 313 /out-notifications 315 statistics: 316 Contains management session related performance data for the 317 NETCONF server. 319 netconf-start-time (yang:date-and-time) 320 Date and time at which the management subsystem was started. 322 in-bad-hellos (yang:zero-based-counter32) 323 Number of sessions silently dropped because an invalid 324 message was received. 326 in-sessions (yang:zero-based-counter32) 327 Number of sessions started. 329 dropped-sessions (yang:zero-based-counter32) 330 Number of sessions that were abnormally terminated, e.g., due to 331 idle timeout or transport close. 333 in-rpcs (yang:zero-based-counter32) 334 Number of correct requests received. 336 in-bad-rpcs (yang:zero-based-counter32) 337 Number of messages received when a message was expected, 338 that were not correct messages. 340 out-rpc-errors (yang:zero-based-counter32) 341 Number of messages sent which contained an 342 element. 344 out-notifications (yang:zero-based-counter32) 345 Number of messages sent. 347 3. Schema Specific Operations 349 3.1. The Operation 351 Description: 353 This operation is used to retrieve a schema from the NETCONF 354 server. 356 Parameters: 358 identifier (string): 359 Identifier for the schema list entry. 360 Mandatory parameter. 362 version (string): 363 Version of the schema requested. 364 Optional parameter. 366 format (identityref, schema-format): 367 The data modeling language of the schema. 368 Default value is 'yang' when not specified. 369 Optional parameter. 371 Positive Response: 373 The NETCONF server returns the requested schema. 375 Negative Response: 377 If the requested schema does not exist, the is 378 'invalid-value'. 380 If more than one schema matches the requested parameters, the 381 is 'operation-failed', and is 382 'data-not-unique'. 384 4. Examples 386 4.1. Retrieving Schema List via Operation 388 A NETCONF client retrieves the list of supported schema from a 389 NETCONF server by retrieving the /netconf-state/schemas subtree via a 390 operation. 392 Available schema for the requesting session are returned in the reply 393 containing the ,, , and 394 elements. 396 The response data can be used to determine the available schema and 397 their versions. The schema itself (i.e., schema content) is not 398 returned in the response. The optional element contains a 399 URI, which can be used to retrieve the schema by another protocol 400 such as ftp [RFC0959] or http(s) [RFC2616] [RFC2818], or the special 401 value 'NETCONF', which means that the schema can be retrieved from 402 the device via the operation. 404 Example: 406 408 409 410 412 413 414 415 416 418 The NETCONF server returns a list of schema available for 419 retrieval. 421 423 424 426 427 428 foo 429 1.0 430 xsd 431 http://example.com/foo 432 ftp://ftp.example.com/schemas/foo_1.0.xsd 433 http://www.example.com/schema/foo_1.0.xsd 434 NETCONF 435 436 437 foo 438 1.1 439 xsd 440 http://example.com/foo 441 ftp://ftp.example.com/schemas/foo_1.1.xsd 442 http://www.example.com/schema/foo_1.1.xsd 443 NETCONF 444 445 446 bar 447 2008-06-01 448 yang 449 http://example.com/bar 450 451 http://example.com/schema/bar@2008-06-01.yang 452 453 NETCONF 454 455 456 bar-types 457 2008-06-01 458 yang 459 http://example.com/bar 460 461 http://example.com/schema/bar-types@2008-06-01.yang 462 463 NETCONF 464 465 466 467 468 470 4.2. Retrieving Schema Instances 472 Given the reply in the previous section, the following examples 473 illustrate the retrieval of 'foo', 'bar', and 'bar-types' schema at 474 multiple locations, with multiple formats, and in multiple locations. 476 1. foo, version 1.0 in xsd format: 478 a. Via FTP using location 479 ftp://ftp.example.com/schemas/foo_1.0.xsd 481 b. Via HTTP using location 482 http://www.example.com/schema/foo_1.0.xsd 484 c. Via using identifier, version, and 485 format parameters. 487 489 491 foo 492 1.0 493 xsd 494 495 497 499 501 502 503 504 505 507 2. bar, version 2008-06-01 in YANG format: 509 a. Via HTTP using location 510 http://example.com/schema/bar@2008-06-01.yang 512 b. Via using identifer and version 513 parameters: 515 517 519 bar 520 2008-06-01 521 522 524 526 528 module bar { 529 //default format (yang) returned 530 //bar version 2008-06-01 yang module 531 //contents here ... 532 } 533 534 536 3. bar-types, version 2008-06-01 in default YANG format: 538 a. Via using identifer parameter: 540 542 544 bar-types 545 546 548 550 552 module bar-types { 553 //default format (yang) returned 554 //latest revision returned 555 //is version 2008-06-01 yang module 556 //contents here ... 557 } 558 559 561 5. NETCONF Monitoring Data Model 563 The data model described in this memo is defined in the following 564 YANG module. 566 This YANG module imports typedefs from [YANG-TYPES] and references 567 [RFC4741], [RFC4742], [RFC4743], [RFC4744], [RFC5539], [xmlschema-1], 568 [YANG], [ISO/IEC 19757-2:2008], and [RFC5717]. 570 572 module ietf-netconf-monitoring { 574 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring"; 575 prefix "ncm"; 577 import ietf-yang-types { prefix yang; } 578 import ietf-inet-types { prefix inet; } 580 organization 581 "IETF NETCONF (Network Configuration) Working Group"; 583 contact 584 "WG Web: 585 WG List: 587 WG Chair: Mehmet Ersue 588 590 WG Chair: Bert Wijnen 591 593 Editor: Mark Scott 594 596 Editor: Martin Bjorklund 597 "; 599 description 600 "NETCONF Monitoring Module. 601 All elements in this module are read-only. 603 Copyright (c) 2010 IETF Trust and the persons identified as 604 the document authors. All rights reserved. 606 Redistribution and use in source and binary forms, with or 607 without modification, is permitted pursuant to, and subject 608 to the license terms contained in, the Simplified BSD License 609 set forth in Section 4.c of the IETF Trust's Legal Provisions 610 Relating to IETF Documents 611 (http://trustee.ietf.org/license-info). 613 This version of this YANG module is part of RFC XXXX; see 614 the RFC itself for full legal notices."; 615 // RFC Ed.: replace XXXX with actual RFC number and remove this note 617 revision 2010-06-22 { 618 description 619 "Initial revision."; 620 reference 621 "RFC XXXX: YANG Module for NETCONF Monitoring"; 622 // RFC Ed.: replace XXXX with actual RFC number and remove this note 623 } 625 typedef netconf-datastore-type { 626 type enumeration { 627 enum running; 628 enum candidate; 629 enum startup; 630 } 631 description 632 "Enumeration of possible NETCONF datastore types."; 633 reference 634 "RFC 4741: NETCONF Configuration Protocol"; 635 } 637 identity transport { 638 description 639 "Base identity for NETCONF transport types."; 640 } 642 identity netconf-ssh { 643 base transport; 644 description 645 "NETCONF over Secure Shell (SSH)."; 646 reference 647 "RFC 4742: Using the NETCONF Configuration Protocol 648 over Secure SHell (SSH)"; 649 } 651 identity netconf-soap-over-beep { 652 base transport; 653 description 654 "NETCONF over Simple Object Access Protocol (SOAP) over 655 Blocks Extensible Exchange Protocol (BEEP)."; 657 reference 658 "RFC 4743: Using NETCONF over the Simple Object 659 Access Protocol (SOAP)"; 660 } 662 identity netconf-soap-over-https { 663 base transport; 664 description 665 "NETCONF over Simple Object Access Protocol (SOAP) 666 over Hypertext Transfer Protocol Secure (HTTPS)."; 667 reference 668 "RFC 4743: Using NETCONF over the Simple Object 669 Access Protocol (SOAP)"; 670 } 672 identity netconf-beep { 673 base transport; 674 description 675 "NETCONF over Blocks Extensible Exchange Protocol (BEEP)."; 676 reference 677 "RFC 4744: Using the NETCONF Protocol over the 678 Blocks Extensible Exchange Protocol (BEEP)"; 679 } 681 identity netconf-tls { 682 base transport; 683 description 684 "NETCONF over Transport Layer Security (TLS)."; 685 reference 686 "RFC 5539: NETCONF over Transport Layer Security (TLS)"; 687 } 689 identity schema-format { 690 description 691 "Base identity for data model schema languages."; 692 } 694 identity xsd { 695 base schema-format; 696 description 697 "W3C XML Schema Definition."; 698 reference 699 "W3C REC REC-xmlschema-1-20041028: 700 XML Schema Part 1: Structures"; 701 } 703 identity yang { 704 base schema-format; 705 description 706 "The YANG data modeling language for NETCONF."; 707 reference 708 "RFC YYYY: YANG - A data modeling language for NETCONF"; 709 // RFC Ed.: replace YYYY with actual RFC number and remove this note 710 } 712 identity yin { 713 base schema-format; 714 description 715 "The YIN syntax for YANG."; 716 reference 717 "RFC YYYY: YANG - A data modeling language for NETCONF"; 718 // RFC Ed.: replace YYYY with actual RFC number and remove this note 719 } 721 identity rng { 722 base schema-format; 723 description 724 "Regular Language for XML Next Generation (RELAX NG)."; 725 reference 726 "ISO/IEC 19757-2:2008: RELAX NG"; 727 } 729 identity rnc { 730 base schema-format; 731 description 732 "Relax NG Compact Syntax"; 733 reference 734 "ISO/IEC 19757-2:2008: RELAX NG"; 735 } 737 grouping common-counters { 738 description 739 "Counters that exist both per session, and also globally, 740 accumulated from all sessions."; 742 leaf in-rpcs { 743 type yang:zero-based-counter32; 744 description 745 "Number of correct messages received."; 746 } 747 leaf in-bad-rpcs { 748 type yang:zero-based-counter32; 749 description 750 "Number of messages received when a message was expected, 751 that were not correct messages. This includes XML parse 752 errors and errors on the rpc layer."; 754 } 755 leaf out-rpc-errors { 756 type yang:zero-based-counter32; 757 description 758 "Number of messages sent which contained an 759 element."; 760 } 761 leaf out-notifications { 762 type yang:zero-based-counter32; 763 description 764 "Number of messages sent."; 765 } 766 } 768 container netconf-state { 769 config false; 770 description 771 "The netconf-state container is the root of the monitoring 772 data model."; 774 container capabilities { 775 description 776 "Contains the list of NETCONF capabilities supported by the 777 server."; 779 leaf-list capability { 780 type inet:uri; 781 description 782 "List of NETCONF capabilities supported by the server."; 783 } 784 } 786 container datastores { 787 description 788 "Contains the list of NETCONF configuration datastores."; 790 list datastore { 791 key name; 792 description 793 "List of NETCONF configuration datastores supported by 794 the NETCONF server and related information."; 796 leaf name { 797 type netconf-datastore-type; 798 description 799 "Name of the datastore associated with this list entry."; 800 } 801 container locks { 802 presence 803 "This container is present only if the datastore 804 is locked."; 805 description 806 "The NETCONF and operations allow 807 a client to lock specific resources in a datastore. The 808 NETCONF server will prevent changes to the locked 809 resources by all sessions except the one which acquired 810 the lock(s). 812 Monitoring information is provided for each datastore 813 entry including details such as the session which acquired 814 the lock, the type of lock (global or partial) and the 815 list of locked resources. Multiple locks per datastore 816 are supported."; 818 grouping lock-info { 819 description 820 "Lock related parameters, common to both global and 821 partial locks."; 823 leaf locked-by-session { 824 type uint32; 825 mandatory true; 826 description 827 "The session ID of the session that has locked 828 this resource. Both a global lock and a partial 829 lock MUST contain the NETCONF session-id. 831 If the lock is held by a session which is not managed 832 by the NETCONF server (e.g., a CLI session), a session 833 id of 0 (zero) is reported."; 834 reference 835 "RFC 4741: NETCONF Configuration Protocol"; 836 } 837 leaf locked-time { 838 type yang:date-and-time; 839 mandatory true; 840 description 841 "The date and time of when the resource was 842 locked."; 843 } 844 } 846 choice lock-type { 847 description 848 "Indicates if a global lock or a set of partial locks 849 are set."; 851 container global-lock { 852 description 853 "Present if the global lock is set."; 854 uses lock-info; 855 } 857 list partial-locks { 858 key lock-id; 859 description 860 "List of partial locks."; 861 reference 862 "RFC 5717: Partial Lock Remote Procedure Call (RPC) for 863 NETCONF"; 865 leaf lock-id { 866 type uint32; 867 description 868 "This is the lock id returned in the 869 response."; 870 } 871 uses lock-info; 872 leaf-list select { 873 type string; 874 min-elements 1; 875 description 876 "The xpath expression which was used to request 877 the lock. The select expression indicates the 878 original intended scope of the lock."; 879 } 880 leaf-list locked-nodes { 881 type instance-identifier; 882 description 883 "The list of instance-identifiers (i.e., the 884 locked nodes). 886 The scope of the partial lock is defined by the list 887 of locked nodes."; 888 } 889 } 890 } 891 } 892 } 893 } 895 container schemas { 896 description 897 "Contains the list of data model schemas supported by the 898 server."; 900 list schema { 901 key "identifier version format"; 903 description 904 "List of data model schemas supported by the server."; 906 leaf identifier { 907 type string; 908 description 909 "Identifier to uniquely reference the schema. The 910 identifier is used in the operation and may 911 be used for other purposes such as file retrieval. 913 For modeling languages which support or require a data 914 model name (e.g., YANG module name) the identifier MUST 915 match that name. For YANG data models, the identifier is 916 the name of the module or submodule. In other cases an 917 identifier such as a filename MAY be used instead."; 918 } 919 leaf version { 920 type string; 921 description 922 "Version of the schema supported. Multiple versions MAY be 923 supported simultaneously by a NETCONF server. Each 924 version MUST be reported individually in the schema list, 925 i.e., with same identifier, possibly different location, 926 but different version. 928 For YANG data models, version is the value of the most 929 recent YANG 'revision' statement in the module or 930 submodule, or the empty string if no revision statement 931 is present."; 932 } 933 leaf format { 934 type identityref { 935 base schema-format; 936 } 937 description 938 "The data modeling language the schema is written 939 in (currently xsd, yang, yin, rng or rnc). 941 For YANG data models, 'yang' format MUST be supported and 942 'yin' format MAY also be provided."; 943 } 944 leaf namespace { 945 type inet:uri; 946 mandatory true; 947 description 948 "The XML namespace defined by the data model. 950 For YANG data models, this is the module's namespace. 951 If the list entry describes a submodule, this field 952 contains the namespace of the module to which the 953 submodule belongs."; 954 } 955 leaf-list location { 956 type union { 957 type enumeration { 958 enum "NETCONF"; 959 } 960 type inet:uri; 961 } 962 description 963 "One or more locations from which the schema can be 964 retrieved. This list SHOULD contain at least one 965 entry per schema. 967 A schema entry may be located on a remote file system 968 (e.g., reference to file system for ftp retrieval) or 969 retrieved directly from a server supporting the 970 operation (denoted by the value 'NETCONF')."; 971 } 972 } 973 } 975 container sessions { 976 description 977 "The sessions container includes session specific data for 978 NETCONF management sessions. The session list MUST include 979 all currently active NETCONF sessions."; 981 list session { 982 key session-id; 983 description 984 "All NETCONF sessions managed by the NETCONF server 985 MUST be reported in this list."; 987 leaf session-id { 988 type uint32 { 989 range "1..max"; 990 } 991 description 992 "Unique identifier for the session. This value is the 993 NETCONF session identifier, as defined in RFC4741."; 994 reference 995 "RFC 4741: NETCONF Configuration Protocol"; 997 } 998 leaf transport { 999 type identityref { 1000 base transport; 1001 } 1002 mandatory true; 1003 description 1004 "Identifies the transport for each session, e.g., 1005 'netconf-ssh', 'netconf-soap', etc."; 1006 } 1007 leaf username { 1008 type string; 1009 mandatory true; 1010 description 1011 "The username is the client identity that was authenticated 1012 by the NETCONF transport protocol. The algorithm used to 1013 derive the username is NETCONF transport protocol specific 1014 and in addition specific to the authentication mechanism 1015 used by the NETCONF transport protocol."; 1016 } 1017 leaf source-host { 1018 type inet:host; 1019 description 1020 "Host identifier of the NETCONF client. The value 1021 returned is implementation specific (e.g., hostname, 1022 IPv4 address, IPv6 address)"; 1023 } 1024 leaf login-time { 1025 type yang:date-and-time; 1026 mandatory true; 1027 description 1028 "Time at the server at which the session was established."; 1029 } 1030 uses common-counters { 1031 description 1032 "Per-session counters. Zero based with following reset 1033 behaviour: 1034 - at start of a session 1035 - when max value is reached"; 1036 } 1037 } 1038 } 1040 container statistics { 1041 description 1042 "Statistical data pertaining to the NETCONF server."; 1044 leaf netconf-start-time { 1045 type yang:date-and-time; 1046 description 1047 "Date and time at which the management subsystem was 1048 started."; 1049 } 1050 leaf in-bad-hellos { 1051 type yang:zero-based-counter32; 1052 description 1053 "Number of sessions silently dropped because an 1054 invalid message was received. This includes hello 1055 messages with a 'session-id' attribute, bad namespace, and 1056 bad capability declarations."; 1057 } 1058 leaf in-sessions { 1059 type yang:zero-based-counter32; 1060 description 1061 "Number of sessions started. This counter is incremented 1062 when a message with a is sent. 1064 'in-sessions' - 'in-bad-hellos' = 1065 'number of correctly started netconf sessions'"; 1066 } 1067 leaf dropped-sessions { 1068 type yang:zero-based-counter32; 1069 description 1070 "Number of sessions that were abnormally terminated, e.g., 1071 due to idle timeout or transport close. This counter is not 1072 incremented when a session is properly closed by a 1073 operation, or killed by a 1074 operation."; 1075 } 1076 uses common-counters { 1077 description 1078 "Global counters, accumulated from all sessions. 1079 Zero based with following reset behaviour: 1080 - re-initialization of NETCONF server 1081 - when max value is reached"; 1082 } 1083 } 1084 } 1086 rpc get-schema { 1087 description 1088 "This operation is used to retrieve a schema from the 1089 NETCONF server. 1091 Positive Response: 1092 The NETCONF server returns the requested schema. 1094 Negative Response: 1095 If requested schema does not exist, the is 1096 'invalid-value'. 1098 If more than one schema matches the requested parameters, the 1099 is 'operation-failed', and is 1100 'data-not-unique'."; 1102 input { 1103 leaf identifier { 1104 type string; 1105 mandatory true; 1106 description 1107 "Identifier for the schema list entry."; 1108 } 1109 leaf version { 1110 type string; 1111 description 1112 "Version of the schema requested. If this parameter is not 1113 present, and more than one version of the schema exists on 1114 the server, a 'data-not-unique' error is returned, as 1115 described above."; 1116 } 1117 leaf format { 1118 type identityref { 1119 base schema-format; 1120 } 1121 description 1122 "The data modeling language of the schema. If this 1123 parameter is not present, and more than one formats of 1124 the schema exists on the server, a 'data-not-unique' error 1125 is returned, as described above."; 1126 } 1127 } 1128 output { 1129 anyxml data { 1130 description 1131 "Contains the schema content."; 1132 } 1133 } 1134 } 1135 } 1137 1139 6. Security Considerations 1141 The YANG module defined in this memo is designed to be accessed via 1142 the NETCONF protocol [RFC4741]. The lowest NETCONF layer is the 1143 secure transport layer and the mandatory to implement secure 1144 transport is SSH [RFC4742]. 1146 Some of the readable data nodes in this YANG module may be considered 1147 sensitive or vulnerable in some network environments. It is thus 1148 important to control read access (e.g., via get, get-config or 1149 notification) to these data nodes. 1151 These are the containers, list nodes and data nodes with their 1152 specific sensitivity/vulnerability: 1154 /netconf-state/sessions/session/username: Contains identity 1155 information which could be used in an attempt to authenticate with 1156 the server. 1158 This username is only meant for monitoring, and SHOULD NOT be used 1159 for other purposes, such as access control, without a detailed 1160 discussion of the limitations of this reported username. For 1161 example, it is possible that server A and server B might report 1162 the same username, but these might be for different persons. 1164 7. Acknowledgements 1166 The authors would like to thank Andy Bierman, Mehmet Ersue, Washam 1167 Fan, David Harrington, Balazs Lengyel, Hideki Okita, Juergen 1168 Schoenwaelder, Bert Wijnen and many other members of the NETCONF WG 1169 for providing important input to this document. The authors would 1170 also like to specifically acknowledge Sharon Chisholm's work on 1171 'draft-netconf-chisholm-monitoring-02' and contribution to this 1172 document. 1174 8. IANA Considerations 1176 -- Editor note to IANA/RFC-Editor: we request that you make these 1177 assignments, in which case it is to be documented as below replacing 1178 'RFCXXXX' as appropriate 1180 This document registers one URI in "The IETF XML Registry". 1181 Following the format in [RFC3688] the following is requested. 1183 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring 1184 Registrant Contact: The IESG. 1185 XML: N/A, the requested URI is an XML namespace. 1187 This document registers one module in the "YANG Module Names" 1188 registry. Following the format in [YANG] the following is requested. 1190 name: ietf-netconf-monitoring 1191 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring 1192 prefix: ncm 1193 reference: RFCXXXX 1195 9. Appendix A - Change Log 1197 [-- Editor note to IANA/RFC-Editor: Please remove this section upon 1198 publication.] 1200 9.1. draft-ietf-netconf-monitoring-14 1202 - removed the session-id and session-id-or-zero typedefs from the 1203 YANG module 1205 9.2. draft-ietf-netconf-monitoring-13 1207 - updated after AD and Gen-Art reviews 1208 - Sec 6: new security text template (rev4) used 1209 - updated IANA considerations to reference Yang Module Names registry 1210 - updated references to latest versions 1211 - removed unused informative reference to rfc5277 1212 - updated username description to specify SSH algorithm 1213 - updated negative response 1214 - Yang Module changes: 1215 - added Martin to list of contacts 1216 - prefix changed to 'ncm' (netconf monitoring) 1217 - grouping netconf-datastore-type is now an enumeration 1218 - netconf-over-soap-over-beep description update 1219 - netconf-over-soap-over-https description update 1220 - yang identity description update 1221 - yin identity description update 1222 - fixed reference statement in yin identity 1223 - capabilities leaf-list description update 1224 - added presence statement to locks container 1225 - name changed from container to leaf node 1226 - name key added for datastores list 1227 - added typedef sessionid-or-zero 1228 - locked-time now mandatory 1229 - lock-type description added 1230 - schemas description added 1231 - schema description added 1232 - namespace now mandatory 1234 9.3. draft-ietf-netconf-monitoring-12 1236 - updated for AD review 1238 9.4. draft-ietf-netconf-monitoring-11 1239 - updated URI and YANG module revision 1240 - updated sec 5 title to align with other text 1241 - updated Acknowledgements 1242 - added Description statements to identityrefs in the YANG module 1243 - updated document expiry 1244 - updated document title to v11 1245 - sec 1.1: removed 'schema' definition; it will be placed in one of 1246 the base NETCONF documents instead (i.e. 4741bis) 1247 - sec 2: reworded 'The NETCONF monitoring data defined' to 'The NETCONF 1248 monitoring data model defined' 1249 - sec 2.1: reworded 'The /netcong-state subtree...' to 1250 'The netconf-state container...' 1251 - sec 2.1: reworded 'List of NETCONF datastores...' to 1252 'Includes all supported datastore types...' 1253 - sec 2.1: removed '(Container)' for consistency 1254 - sec 2.1.3: reworded format to remove file/module with schema 1255 - sec 2.1.3 reworded 'The data modeling language of the file/module...' 1256 to 'The data modeling language the schema is written in...' removing 1257 references to files/modules. 1258 - sec 2.1.3: reworded 'defined by the data model' to 'defined by the 1259 schema' 1260 - sec 2.1.3: reworded namespace from 'by the data model' to 'by the 1261 schema' 1262 - sec 2.1.4 changed '[NETCONF Configuration Protocol]' to '[RFC4741]' 1263 - sec 4.1 simplified wording in this section. Specifically removed the 1264 SHOULD and MUST statements which are already qualified in sec 2.1.3 and 1265 in YANG the module 1266 - sec 4.1 to address comment about lack of standardized sftp definition 1267 changed 'sftp' to 'ftp' and updated examples to use standardized ftp URI 1268 - sec 4.1 reworded 'data models' to 'schema' 1269 - sec 4.1 updated YANG example URI to use '@' instead of '-' 1270 - sec 4.2 updated YANG example URI to use '@' instead of '-' 1271 - YANG module, revision statement: changed RFC title to match draft name 1272 - YANG module, container netconf-state: updated description to match 1273 sec 2.1 1274 - YANG module, container datastores: updated description 1275 - YANG module, list partial-locks: added reference to RFC5717 1276 - YANG module,leaf-list locked-nodes: removed text which was 1277 inconsistent with partial lock RFC 1278 - YANG module, leaf format: updated description to match sec 2.1.3 1279 - YANG module, container sessions: updated description to match 1280 sec 4.1 1281 - YANG module, leaf source-host: updated description to clarify 1282 that identifier is likely to be implementation specific per sec 2 1283 - References: moved YANG, Common Yang Data Types and XML from 1284 informative to normative 1285 - References: updated partial lock details to RFC5717 1286 9.5. draft-ietf-netconf-monitoring-10 1288 - sec 1.1, updated schema definition, removed YANG definition (it is 1289 in references instead) 1290 - reworded text in Intro about NETCONF clients adjusting 'capabilities', 1291 per agreement that capacbilities can not change in a session (per 1292 4741bis) 1293 - introduction, removed description of NETCONF behaviour for schema 1294 changes on active sesssions. Has been moved to 4741bis 1295 - updated namespace from '*:ns:netconf::state' to 1296 '*:yang:ns:ietf-netconf-monitoring:DRAFT-10' 1297 For details see ML archive: 1298 'http://www.ietf.org/mail-archive/web/netconf/current/msg05296.html' 1299 - moved majority of sec 2 into the yang module (making module self 1300 describing), leaving only overview text in the RFC body. 1301 For details see ML archive: 1302 'http://www.ietf.org/mail-archive/web/netconf/current/msg05209.html' 1303 - reworded definition of 'schema' 1304 - removed residual references to XSD types (i.e. xs:string) 1305 - reworded text that schema may not always be retrievable 1306 - will add additional text that yang format is both the default 1307 and mandatory; yin is optional 1308 - updated text per Juergen's WGLC comments on v09. 1309 For details see ML arhive: 1310 'http://www.ietf.org/mail-archive/web/netconf/current/msg05306.html' 1311 - updated reference in sec 1.1 for RFC2119 1312 - title change to 'YANG Module for NETCONF Monitoring' 1314 9.6. draft-ietf-netconf-monitoring-09 1316 - reversion of 'session-type' to 'transport' 1317 - element naming consistency. All lowerCamelCase names have been 1318 converted to 'hyphen-delimited' or 'netconf-style-naming' as it is 1319 sometimes referred to on the ML. E.g. 'sessionType' -> 1320 'session-type'. This change impacts both the draft text and yang 1321 module. 1322 - <get-schema> operation updated: 1323 - now has only one mandatory parameter, 'identifier' 1324 - updated negative responses, including the rpc operation 1325 description in yang module 1326 - comments added to the yang module indicating that the definition of 1327 'session-id' is consistent with 4741bis 'session-id-type' and could 1328 be imported from that pending RFC. Similar for 1329 'netconf-datastore-type'. This was in favour of adding further 1330 dependencies and delays by waiting for 4741bis to complete. 1332 9.7. draft-ietf-netconf-monitoring-08 1334 - Addresses action items from IETF75 and mailing list comments 1335 - Most significant is the decision to adopt YANG as normative 1336 As a result the publication of this draft depends on: 1337 o WGLC updates (if required) 1338 o updates to the normative model as result of netmod YANG 1339 changes (if required) 1340 o data organization changes if WG adopts a new data 1341 hierarchy for netmod (this draft uses "/netconf-state/") 1342 - XML Schema of model and IP host definition have been removed 1344 9.8. draft-ietf-netconf-monitoring-07 1346 - updates the examples in sec 4.2 per ML discussion 1348 9.9. draft-ietf-netconf-monitoring-06 1350 - replaced references to 'schema-retrieval capability' with 1351 '<get-schema> operation' 1352 - upper/lowercase alignment on references to 'format' 1353 - changed negative response for <get-schema> to 'data-missing' 1354 - ML comments on v05 which required changes in the draft: 1355 o 2.1.2: reworded to avoid suggestion that configurable data was 1356 contained in the sub-tree (per Balazs' request) 1357 o 2.1.2: reworded paragraph partial lock and select statements 1358 (per Balazs' suggested text) 1359 o Fixed examples in 3.1 and added negative response (per Balazs' 1360 comment) 1361 o YANG: location changed to leaf-list (per Balazs' comment) 1362 o added non-normative references to yang and yang-types (per Balazs' 1363 comment) 1364 o 2.1.3: added YIN and RNC to format 'enums' text and models 1366 9.10. draft-ietf-netconf-monitoring-05 1367 This version addresses action items from IETF74 and comments on v4. 1368 - updated statistics (and counter definitions) per offline discussion: 1369 - updated counter definitions 1370 - updated data types (addition of ZeroBasedCounter32) 1371 - per session counters; see section 2.1.4 1372 - global counters; see section 2.1.5 1373 - unique sessionId handling and WG consensus: 1374 o expected handling of NETCONF and non-NETCONF sessions defined 1375 o explicit exclusion of sessionId=0 added 1376 o see section 2.1.4 1377 - removal of subscriptions subtree; was sec 2.1.5 in v4 1378 - revised XSD and YANG models 1380 9.11. draft-ietf-netconf-monitoring-04 1382 - New RPC operation defined <get-schema<, replacing 1383 <list-schema>. 1384 - Updated Abstract and Introduction: new text, removed NETCONF 1385 protocol diagram. 1386 - Changed /netconfstate/ to /netconf-state 1387 - Added netconf-state/datastores 1388 - Changed /netconf-state/schema to /netconf-state/schemas 1389 - Added /netconf-state/statistics 1390 - Added /schema/format (and added to key) 1391 - Added /schema/namespace (and added to key) 1392 - Updated examples. 1393 - More detailed monitored data descriptions per ML comments. 1395 9.12. draft-ietf-netconf-monitoring-03 1397 - incorporates ML list comments on v-02. 1399 9.13. draft-ietf-netconf-monitoring-02 1401 - Merged content from 'draft-scott-netconf-schema-query' into this draft 1402 - this draft now covers both schema retrievel and monitoring 1404 9.14. draft-ietf-netconf-monitoring-01 1405 - WG first draft, 'draft-ietf-netconf-monitoring-01'. 1406 - Related draft 'draft-scott-netconf-schema-query-00' also presented 1407 covering schema retrieval. Query draft proposes new NETCONF 1408 operations to retrieve schema defined in this draft. 1410 9.15. draft-scott-netconf-monitoring-00 1412 - Initial draft, 'draft-scott-monitoring-00' 1413 - based on 'draft-netconf-chisholm-monitoring-02' 1414 - adopted as working group document at IETF69. 1416 10. References 1418 10.1. Normative References 1420 [ISO/IEC 19757-2:2008] 1421 ISO/IEC, "Document Schema Definition Language (DSDL) -- 1422 Part 2: Regular-grammar-based validation -- RELAX NG", 1423 December 2008, . 1426 [RFC2119] Bradner, s., ""Key words for use in RFCs to Indicate 1427 Requirement Levels", BCP 14", RFC 2119, March 1997, 1428 . 1430 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 1431 February 2006, . 1433 [RFC4742] Wasserman, M. and T. Goddard, "Using the NETCONF 1434 Configuration Protocol over Secure SHell (SSH)", 1435 December 2006, . 1437 [RFC4743] Goddard, T., "Using NETCONF over the Simple Object Access 1438 Protocol (SOAP)", December 2006, 1439 . 1441 [RFC4744] Lear, E. and K. Crozier, "Using the NETCONF Protocol over 1442 the Blocks Extensible Exchange Protocol (BEEP)", 1443 December 2008, . 1445 [RFC5539] Badra, M., "NETCONF over Transport Layer Security (TLS)", 1446 May 2009, . 1448 [RFC5717] Lengyel, B. and M. Bjorklund, "Partial Lock Remote 1449 Procedure Call (RPC) for NETCONF", December 2009, 1450 . 1452 [XML-NAMES] 1453 Hollander, D., Tobin, R., Thompson, H., Bray, T., and A. 1454 Layman, "Namespaces in XML 1.0 (Third Edition)", World 1455 Wide Web Consortium Recommendation REC-xml-names-20091208, 1456 December 2009, 1457 . 1459 [YANG] Bjorklund, M., "YANG - A data modeling language for 1460 NETCONF", June 2010, 1461 . 1463 [YANG-TYPES] 1464 Schoenwaelder, J., "Common YANG Data Types", April 2010, < 1465 http://tools.ietf.org/html/ 1466 draft-ietf-netmod-yang-types-09>. 1468 [xmlschema-1] 1469 Biron, Paul V. and Ashok. Malhotra, "XML Schema Part 1: 1470 Structures Second Edition W3C Recommendation 28 October 1471 2004", October 2004, . 1473 10.2. Informative References 1475 [RFC0959] Postel, J. and J. Reynolds, "File Transfer Protocol", 1476 STD 9, RFC 959, October 1985. 1478 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1479 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1480 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1482 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1484 [RFC3688] Mealling, M., "The IETF XML Registry", January 2004, 1485 . 1487 Authors' Addresses 1489 Mark Scott 1490 Ericsson 1491 3500 Carling Ave 1492 Nepean, Ontario K2H 8E9 1493 Canada 1495 Email: mark.scott@ericsson.com 1497 Martin Bjorklund 1498 Tail-f Systems 1499 Klara Norra Kyrkogata 31 1500 SE-111 22 Stockholm, 1501 Sweden 1503 Email: mbj@tail-f.com