idnits 2.17.1 draft-ietf-netconf-monitoring-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 683 has weird spacing: '...ontains manag...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (June 24, 2009) is 5420 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) == Missing Reference: '0-1' is mentioned on line 1125, but not defined == Missing Reference: '0-9' is mentioned on line 1125, but not defined == Missing Reference: '0-4' is mentioned on line 1125, but not defined == Missing Reference: '0-5' is mentioned on line 1125, but not defined == Missing Reference: 'RFC4741' is mentioned on line 1209, but not defined ** Obsolete undefined reference: RFC 4741 (Obsoleted by RFC 6241) == Unused Reference: 'NETCONF' is defined on line 1240, but no explicit reference was found in the text == Unused Reference: 'NETCONF-EVENT' is defined on line 1243, but no explicit reference was found in the text == Unused Reference: 'XML' is defined on line 1254, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4741 (ref. 'NETCONF') (Obsoleted by RFC 6241) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XMLSchema' Summary: 3 errors (**), 0 flaws (~~), 11 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Scott 3 Internet-Draft S. Chisholm 4 Intended status: Standards Track Nortel 5 Expires: December 26, 2009 M. Bjorklund 6 Tail-f Systems 7 June 24, 2009 9 NETCONF Monitoring Schema 10 draft-ietf-netconf-monitoring-05 12 Status of this Memo 14 This Internet-Draft is submitted to IETF in full conformance with the 15 provisions of BCP 78 and BCP 79. This document may contain material 16 from IETF Documents or IETF Contributions published or made publicly 17 available before November 10, 2008. The person(s) controlling the 18 copyright in some of this material may not have granted the IETF 19 Trust the right to allow modifications of such material outside the 20 IETF Standards Process. Without obtaining an adequate license from 21 the person(s) controlling the copyright in such materials, this 22 document may not be modified outside the IETF Standards Process, and 23 derivative works of it may not be created outside the IETF Standards 24 Process, except to format it for publication as an RFC or to 25 translate it into languages other than English. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF), its areas, and its working groups. Note that 29 other groups may also distribute working documents as Internet- 30 Drafts. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 The list of current Internet-Drafts can be accessed at 38 http://www.ietf.org/ietf/1id-abstracts.txt. 40 The list of Internet-Draft Shadow Directories can be accessed at 41 http://www.ietf.org/shadow.html. 43 This Internet-Draft will expire on December 26, 2009. 45 Copyright Notice 47 Copyright (c) 2009 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents in effect on the date of 52 publication of this document (http://trustee.ietf.org/license-info). 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. 56 Abstract 58 This document defines a NETCONF data model (in XML Schema) to be used 59 to monitor the NETCONF protocol. The monitoring data model includes 60 information about NETCONF datastores, sessions, locks and statistics. 61 This data facilitates the management of a NETCONF server. This 62 document also defines methods for NETCONF clients to discover data 63 models supported by a NETCONF server and defines a new NETCONF operation to retrieve them. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 4 70 2. XML Schema to Monitor NETCONF . . . . . . . . . . . . . . . . 5 71 2.1. The /netconf-state Subtree . . . . . . . . . . . . . . . . 5 72 2.1.1. The /netconf-state/capabilities Subtree . . . . . . . 5 73 2.1.2. The /netconf-state/datastores Subtree . . . . . . . . 6 74 2.1.3. The /netconf-state/schemas Subtree . . . . . . . . . . 6 75 2.1.4. The /netconf-state/sessions Subtree . . . . . . . . . 8 76 2.1.5. The /netconf-state/statistics Subtree . . . . . . . . 9 77 3. Schema Specific Operations . . . . . . . . . . . . . . . . . . 11 78 3.1. The Operation . . . . . . . . . . . . . . . . 11 79 3.2. NETCONF Schema List Retrieval ( monitoring data) . . 11 80 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 81 4.1. Retrieving schema list via . . . . . . . . . . . . . 13 82 4.2. Retrieving schema instances . . . . . . . . . . . . . . . 15 83 5. XSD Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 17 84 5.1. NETCONF Monitoring Schema . . . . . . . . . . . . . . . . 17 85 5.2. inet:host schema . . . . . . . . . . . . . . . . . . . . . 27 86 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 87 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 31 88 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 89 9. Normative References . . . . . . . . . . . . . . . . . . . . . 33 90 Appendix A. YANG module (non-normative) . . . . . . . . . . . . . 34 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 43 93 1. Introduction 95 This document defines NETCONF content via [XMLSchema] to be used to 96 monitor the NETCONF protocol. It provides information about NETCONF 97 sessions. Today, NETCONF capabilities exchange is the only 98 standardized method a client can use to discover the functionality 99 supported by a NETCONF server. This works well for static protocol 100 capabilities but is not well suited for capabilities which could 101 change during a session. 103 Considerations such as different schema formats, feature optionality 104 and access controls can all impact the applicability and level of 105 detail the NETCONF server sends to a client during session setup. 106 Through updated monitoring data NETCONF clients can adjust their 107 capabilities throughout a session. Specifically the details returned 108 can be used by a client to determine whether retrieval of new schema 109 information is required and includes the information required to 110 facilitate the retrieval. The methods defined in this document 111 address the need for further means to query and retrieve schema and 112 netconf state information from a NETCONF server. These are provided 113 to complement existing base NETCONF capabilities and operations and 114 in no way affect existing behaviour. 116 A new operation is also defined to support explicit 117 schema retrieval via NETCONF. 119 1.1. Definition of Terms 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 123 document are to be interpreted as d/lockedescribed in [RFC2119]. 125 Schema: A machine readable data model definition. The schema is 126 independent of which data modeling language is used for the data 127 model. 129 XML Schema: The W3C XML Schema [XMLSchema] data modeling language. 131 YANG: YANG is a data modeling language used to model configuration 132 and state data manipulated by the NETCONF protocol, NETCONF remote 133 procedure calls, and NETCONF notifications. 135 2. XML Schema to Monitor NETCONF 137 The following data allows a NETCONF client to monitor both the 138 NETCONF server itself and the associated network device operational 139 data. A server that implements the data model defined in this 140 document MUST advertise the capability URI 141 "urn:ietf:params:xml:ns:netconf:state". The specific monitoring data 142 defined in this draft which MUST be present follows. 144 2.1. The /netconf-state Subtree 146 The /netconf-state subtree is the root of the monitoring 147 data model. It acts as the container for the other monitored data. 149 netconf-state 150 |_capabilities 151 |_datastores 152 |_schemas 153 |_sessions 154 |_statistics 156 capabilities 157 List of NETCONF capabilities supported by the server. 159 datastores 160 List of NETCONF datastores on the server. 161 Includes all supported datastore types (running, candidate, startup) 163 schemas 164 List of schemas supported on the server. 165 Includes all the information required to identify the schemas and 166 to support their retrieval. 168 sessions 169 List of all active NETCONF sessions on the device. 170 Includes sessions for all NETCONF clients across all protocols. 172 statistics 173 Contains management stats for the NETCONF server 174 including performance and error related counters. 176 2.1.1. The /netconf-state/capabilities Subtree 178 The /netconf-state/capabilibiles subtree contains the capabilities 179 supported by the NETCONF server. The list MUST include all 180 capabilities exchanged during session setup still applicable at the 181 time of the request. This ensures consistency with the initial 182 capabilities exchanged while allowing for potential modifications 183 during a session. 185 2.1.2. The /netconf-state/datastores Subtree 187 The /netconf-state/datastores subtree contains configuration data 188 for the NETCONF server including information on the lock state of 189 the datastores. 191 configuration (type: ConfigurationDataStore) 192 |_name 193 |_locks 195 name (type: NETCONFDatastoreType) 196 Enumeration of supported datastores; candidate, running, startup. 198 locks (type: xs:choice) 199 The NETCONF and operations allow a client 200 to lock specific resources in a datastore. The NETCONF server will 201 prevent changes to the locked resources by all sessions except 202 the one which acquired the lock(s). 204 To provide clients the ability to manage locked resources lock 205 information is provided for each ConfigurationDataStore instance. 206 The lock data includes details such as the session which acquired 207 the lock, the type of lock (global or partial) and the list of locked 208 resources. Multiple locks per datastore are supported. 210 Both a global lock and a partial lock MUST contain the sessionId. 212 For partial locks the list of locked nodes is also returned. Since 213 this list may change over time the select expressions originally used 214 to request the lock are also returned. The select expression 215 indicates the original intended scope of the lock and time the lock 216 was acquired. The scope of the partial lock is defined by the list 217 of locked nodes. 219 2.1.3. The /netconf-state/schemas Subtree 220 The list of supported schema for the NETCONF server. 222 schema 223 |_identifier (key) 224 |_version (key) 225 |_format (key) 226 |_namespace 227 |_location 229 The elements identifier, version, and format are used as a key in the 230 schema list. These are used in the operation. 232 identifier (type: xs:string) 233 Identifier for the schema list entry. For modeling languages which 234 support or require a data model name (eg: YANG module name) the 235 identifier MUST match that name. For modeling lanuguages which 236 do not this must contain some other identifier such as filename. 238 Identifier is used in the operation and may 239 be used for other means such as file retrieval. 241 version (type: xs:string) 242 Version of the schema supported. Multiple versions MAY be supported 243 simultaneously by a NETCONF server. Each version MUST be reported 244 individually in the schema list, i.e. with same identifier, possibly 245 different location, but different version. 247 format (type: xs:QName) 248 The data modeling language of the file/module. Current selection of 249 XSD, YANG, and RNG. 251 namespace(type: xs:anyURI) 252 The XML namespace defined by the data model. 254 location (type: xs:union: xs:string, xs:anyURI) 255 One of more locations from which this specific schema, format, and 256 version can be retrieved. The list SHOULD contain at least one 257 entry per schema. 259 A schema entry may be located on a network device (eg: xs:anyURI), 260 (eg: xs:string reference to file system for ftp retrieval) or 261 available explicitly via NETCONF (xs:string value 'NETCONF') for 262 NETCONF servers which support the schema-retrieval capability via 263 . 265 2.1.4. The /netconf-state/sessions Subtree 267 Includes session specific data for NETCONF management sessions. 269 sessions (type: ManagementSession): 271 session 272 |_sessionId (key) 273 |_transport 274 |_username 275 |_sourceHost 276 |_loginTime 277 |_inRpcs 278 |_inBadRpcs 279 |_outRpcErrors 280 |_outNotifications 282 sessionId (type: SessionId) 283 Unique NETCONF identifier for the session, used for all 284 supported operations (e.g. monitoring, session kill, lock 285 release) regardless of protocol. 286 MUST be a unique non-0 value for all sessions reported. 287 SessionId=0 will not be reported in the session table. 288 For purposes of NETCONF management all sessions are one of: 289 Known session: any session which can be managed by the 290 NETCONF server SHOULD be reported in this table and 291 MUST map to a unique sessionId as described above 292 Unknown session: such sessions are not managed by the 293 NETCONF server and all map to sessionId=0. These MUST 294 be excluded from the session table as a result. 295 SessionId=0 will continue to be reported in error messages 296 with sessionId=0 per existing 4741 definition. 298 transport (type: xs: QName) 299 Idenfities NETCONF transport for each session, e.g. "netconf-ssh". 301 username (type: xs:string) 302 Subject to the authentication mechanisms and security 303 considerations this SHOULD contain an identifier which 304 can be used to uniquely identify an individual client 305 (human or machine). This is likely be implementation 306 specific subject to the security requirements of the 307 device vendor and/or operators. e.g. an SSH user, a host RSA 308 fingerprint or other identifier deemed acceptable 310 sourceHost (type: inet:host) 311 Host identifier (IP + name) for the client. 312 See section 5.2 for definition. 314 loginTime (type: xs:dateTime) 315 Time at which the session was established. 317 inRpcs (type: ZeroBasedCounter32) 318 Number of correct requests received. 320 inBadRpcs (type: ZeroBasedCounter32) 321 Number of messages received when a message was expected, 322 that were not correct messages. This includes XML parse 323 errors and errors on the rpc layer. 325 outRpcErrors (type: ZeroBasedCounter32) 326 Number of messages sent which contained an 327 element. 329 outNotifications (type: ZeroBasedCounter32) 330 Number of messages sent. 332 2.1.5. The /netconf-state/statistics Subtree 334 Statistical data pertaining to the NETCONF server. 336 statistics 337 |_netconfStartTime 338 |_inBadHellos 339 |_inSessions 340 |_droppedSessions 341 |_inRpcs 342 |_inBadRpcs 343 |_outRpcErrors 344 |_outNotifications 346 statistics (type: ManagementStatistics): 347 Contains management session related performance data for the NETCONF 348 server. 350 Data type ZeroBasedCounter32 is defined and used for counters. 351 Counters are zero based with following reset behaviour: 352 - at start of a session for all per session counters 353 (in /netconf-state/sessions) 354 - re-initilization of NETCONF server for global counters 355 (in /netconf-state/statistics) 356 - when max value is reached for all per session and global 357 counters 359 netconfStartTime (type: xs:dateTime) 360 Date and time at which the NETCONF server process was started. 361 Allows for calculation of simple time interval for reported metrics. 363 Ie: current time - startTime defines the collection interval for the 364 metrics allowing for calculations such as averages. 365 More complex calculations would require multiple collection 366 intervals with both start and stop times defined per interval. 368 inBadHellos (type: ZeroBasedCounter32) 369 Number of sessions silently dropped because an 370 invalid message was received. This includes hello 371 messages with a 'session-id' attribute, bad namespace, and 372 bad capability declarations. 374 inSessions (type: ZeroBasedCounter32) 375 Number of sessions started. This counter is incremented when 376 a message with a is sent. 377 I.e. inSessions - inBadHellos = number of correctly started 378 netconf sessions 380 droppedSessions (type: ZeroBasedCounter32) 381 Number of sessions that were abnormally terminated, e.g. due 382 to idle timeout or transport close. This counter is not 383 incremented when a session is properly closed by a 384 operation, or killed by a 385 operation. 387 inRpcs (type: ZeroBasedCounter32) 388 Number of correct requests received. 390 inBadRpcs (type: ZeroBasedCounter32) 391 Number of messages received when a message was expected, 392 that were not correct messages. This includes XML parse 393 errors and errors on the rpc layer. 395 outRpcErrors (type: ZeroBasedCounter32) 396 Number of messages sent which contained an 397 element. 399 outNotifications (type: ZeroBasedCounter32) 400 Number of messages sent. 402 3. Schema Specific Operations 404 3.1. The Operation 406 Description: When the schema is available on the device and the 407 client wishes to have it returned via NETCONF this new operation is 408 used. 410 Parameters: 412 identifier (type: xs:string): Identifier for the schema list entry. 414 version (type: xs:string): Version of the schema supported. 416 format (type: SchemaFormat): The data modeling language of the 417 schema. 419 Example: Retrieve a specific schema from the device using operation 422 424 425 foo 426 v1 427 XSD 428 429 430 > 431 Positive Response: The NETCONF server returns the XML schema (XSD). 433 435 < 436 437 438 > 439 440 442 3.2. NETCONF Schema List Retrieval ( monitoring data) 444 A NETCONF client retrieves the list of supported schema from a 445 NETCONF server by retrieving the /netconf-state/schema subtree via a 446 >get< operation. Available schema for the requesting session are 447 returned in the reply containing the ,, 448 and elements. Since the same schema may be 449 supported in multiple locations and/or have multiple versions and/or 450 multiple formats no particular attribute is unique. An empty reply 451 is returned if there are no available schema. 453 The response data can be used to determine the available schema and 454 their versions. The schema itself (i.e. schema content) is not 455 returned in the response. The URL details returned in the list 456 SHOULD facilitate retrieval from a network location via a means such 457 as ftp or http. 459 Negative Response: If the requested schema is not available the 460 response will be generated as follows: If no 461 schema matches the requested parameters the will be 462 'operation-failed', and the will be 'no-matches'. If 463 access control denies the partial lock, the will be 464 'access-denied'. Additionally the ability to retrieve a schema via 465 NETCONF SHOULD be supported. When a schema is available on the 466 device and the schema-retrieval capability is supported by the 467 NETCONF server a location value of 'NETCONF' MUST be used to indicate 468 that it can be retrieved via NETCONF using the operation 469 described in section 3.1. 471 4. Examples 473 4.1. Retrieving schema list via 475 477 478 479 480 481 482 483 484 486 The NETCONF server returns a list of data models available for 487 retrieval. 489 491 492 493 494 495 foo 496 1.0 497 XSD 498 http://example.com/foo 499 ftp://ftp.example.com/schemas/foo_1.0.xsd 500 http://www.example.com/schema/foo_1.0.xsd 501 NETCONF 502 503 504 foo 505 1.1 506 XSD 507 http://example.com/foo 508 ftp://ftp.example.com/schemas/foo_1.1.xsd 509 http://www.example.com/schema/foo_1.1.xsd 510 NETCONF 511 512 513 bar 514 2008-06-01 515 YANG 516 http://example.com/bar 517 518 http://example.com/schema/bar-2008-06-01.yang 519 520 NETCONF 521 522 523 bar-types 524 2008-06-01 525 YANG 526 http://example.com/bar 527 528 http://example.com/schema/bar-types-2008-06-01.yang 529 530 NETCONF 531 532 533 534 535 536 4.2. Retrieving schema instances 538 Given the reply in the previous section, the following examples 539 illustrate the availability of 'foo', 'bar', and 'bar-types' schema 540 at multiple locations, with multiple formats, and in multiple 541 locations. 543 1. foo, version 1.0 in XSD format: 545 a. Via FTP using location 546 ftp://ftp.example.com/schemas/foo_1.0.xsd 548 b. Via HTTP using location 549 http://www.example.com/schema/foo/1.0.xsd 551 c. Via using identifier, version, and 552 format parameters. 554 556 557 foo 558 1.0 559 XSD 560 561 563 2. bar, version 2008-06-01 in YANG format: 565 a. Via HTTP using location 566 http://example.com/schema/bar-2008-06-01.yang 568 b. Via using identifer, version, and 569 format parameters: 571 573 574 bar 575 2008-06-01 576 YANG 577 578 580 3. bar-types, version 2008-06-01 in YANG format: 582 a. Via using identifer, version, and 583 format parameters: 585 587 588 bar-types 589 2008-06-01 590 YANG 591 592 594 5. XSD Schema 596 5.1. NETCONF Monitoring Schema 598 The data model described in this memo is defined in the following 599 XSD. 601 602 609 610 612 614 616 617 618 619 620 621 622 623 The list of currently provided NETCONF capabilities. 624 This may be different than those exchanged during 625 session setup (i.e. hello). 626 627 628 629 630 632 633 634 635 636 637 638 Contains the NETCONF configurations datastores available 639 on the device. 640 642 643 644 645 648 649 650 651 652 653 654 Contains the list of supported schemas on the device. 655 I.e. NETCONF data models, interface descriptions, etc. 656 657 658 659 660 662 663 664 665 666 667 668 Contains the details on active sessions on the device. 669 Covers both NETCONF and non-NETCONF management sessions. 670 671 672 673 674 676 677 678 679 681 682 683 Contains management metrics for the NETCONF server. 684 685 686 687 688 689 690 691 692 693 694 Counters that exist both per session, and also globally, 695 accumulated from all sessions. 696 697 698 699 700 701 702 Number of correct <rpc> requests received. 703 704 705 706 707 708 709 Number of messages received when a <rpc> message was 710 expected, that were not correct <rpc> messages. This 711 includes XML parse errors and errors on the rpc layer. 712 713 714 715 716 717 718 Number of <rpc-reply> messages sent which contained an 719 <rpc-error> element. 720 721 722 723 724 725 726 Number of <notification> messages sent. 727 728 729 730 731 732 733 734 735 736 Contains information on the datastores available on 737 the NETCONF server including locks. 739 740 741 742 743 744 745 enumeration of supported datastores; candidate, 746 running, startup 747 748 749 750 751 752 753 An indication of whether a resource is locked or 754 unlocked. If locked, additional information about 755 the locking such as user an time stamp is provided. 756 757 758 759 760 761 762 763 Present if a global lock is set. 764 765 766 767 769 770 771 Present if at least one partial lock is set. 772 773 774 775 776 777 778 779 780 781 782 783 Contains the information used to describe the schema. 784 785 786 787 788 789 790 Identifier to uniquely reference the schema. 791 792 793 794 795 796 797 Version of the schema supported. Multiple versions can be 798 supported simultaneously. 799 800 801 802 803 804 805 Schema language for the file/module. Eg: ns:xsd, ns:yang 806 807 808 809 810 811 812 The XML namespace defined by the data model. 813 814 815 816 817 818 819 A location from which the schema can be retrieved. Can be 820 either on the network device retrievable explicitly via 821 the get-schema netconf operation (denoted by the value 822 'NETCONF') or some network location (i.e. URL). 823 824 825 826 827 828 829 830 831 832 833 834 836 837 838 839 840 841 842 843 844 Contains information related to managment sessions on 845 the device. 846 847 848 849 850 851 Unique NETCONF identifier for the session, 852 used for all supported operations (e.g. monitoring, session 853 kill, lock release) regardless of protocol. 854 MUST be a unique non-0 value for all sessions reported. 855 SessionId=0 will not be reported in the session table. 856 For purposes of NETCONF management all sessions are one of: 857 Known session: any session which can be managed by the 858 NETCONF server SHOULD be reported in this table and MUST 859 map to a unique sessionId as described above 860 Unknown session: such sessions are not managed by the 861 NETCONF server and all map to sessionId=0. These MUST 862 be excluded from the session table as a result. 863 SessionId=0 will continue to be reported in error messages 864 with sessionId=0 per existing 4741 definition. 865 866 867 868 869 870 871 Identifies the transport for each session, e.g. 872 ns:netconf-ssh, ns:netconf-beep. 873 874 875 876 877 878 879 Session owner. 880 881 882 883 884 885 886 Client for the session. 887 888 889 890 891 892 893 Time at which the session was established. 894 895 896 897 898 899 900 Per-session counters. 901 902 903 904 905 906 907 908 909 Contains management statistics for the NETCONF server. 910 911 912 913 914 915 916 Date and time at which the NETCONF server process was 917 started. Allows for calculation of time interval for 918 reported metrics. 919 920 921 922 923 924 925 Number of sessions silently dropped because an 926 invalid <hello> message was received. This includes 927 hello messages with a 'session-id' attribute, bad namespace, 928 and bad capability declarations. 929 930 931 932 933 934 935 Number of sessions started. This counter is incremented 936 when a <hello> message with a <session-id> 937 is sent. 938 inSessions - inBadHellos = 'number of correctly started 939 netconf sessions' 940 941 942 943 944 945 946 Number of sessions that were abnormally terminated, 947 e.g. due to idle timeout or transport close. This 948 counter is not incremented when a session is properly 949 closed by a <close-session> operation, or killed 950 by a <kill-session> operation. 951 952 953 954 955 956 957 Global counters, accumulated from all sessions. 958 959 960 961 962 963 964 965 966 A non-negative integer which monotonically increases 967 until it reaches a maximum value of 2^32-1, when it 968 wraps around and starts increasing again from zero. 969 970 971 972 973 974 975 976 Enumeration of possible NETCONF datastore types. 977 978 979 980 981 982 983 984 985 986 987 988 989 990 The session Id which holds the lock. 991 992 993 994 995 996 997 Date and Time the lock was acquired. 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 For a partial lock this is the lock id returned 1009 in the partial-lock response. 1010 1011 1012 1013 1014 1015 1016 The session Id which holds the lock. 1017 1018 1019 1020 1021 1022 1023 Date and Time the lock was acquired. 1024 1025 1026 1027 1028 1029 1030 The xpath expression which was used to request the lock. 1031 1032 1033 1034 1036 1037 1038 The list of instance-identifiers (i.e. the locked nodes). 1039 1040 1041 1042 1043 1044 1045 1047 1048 1049 RPC definition: <get-schema> 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1077 1078 1086 1092 1093 1094 1095 The ipAddress type represents an IP address and 1096 is IP version neutral. The format of the textual 1097 representations implies the IP version. 1098 1099 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1113 1114 1115 1116 The ipv4Address type represents an IPv4 address in 1117 dotted-quad notation. The IPv4 address may include 1118 a zone index, separated by a % sign. 1119 1120 1122 1123 1127 1128 1130 1131 1132 1133 The ipv6Address type represents an IPv6 address in 1134 full, mixed, shortened and shortened mixed notation. 1135 The IPv6 address may include a zone index, separated 1136 by a % sign. 1137 1138 1140 1141 1154 1155 1157 1158 1159 1160 The domainName type represents a DNS domain 1161 name. The name SHOULD be fully qualified 1162 whenever possible. 1164 The description clause of objects using the 1165 domainName type MUST describe how (and when) 1166 these names are resolved to IP addresses. 1168 Note that the resolution of a domainName value 1169 may require to query multiple DNS records (e.g., 1170 A for IPv4 and AAAA for IPv6). The order of the 1171 resolution process and which DNS record takes 1172 precedence depends on the configuration of the 1173 resolver. 1174 1175 1177 1178 1179 1180 1182 1183 1184 1185 The host type represents either an IP address 1186 or a DNS domain name. 1187 1188 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1202 1204 6. Security Considerations 1206 The NETCONF monitoring schema as defined in this document provides 1207 information about a NETCONF system that could be used to aid an 1208 attack on that system. The same considerations as for the base 1209 NETCONF Protocol [RFC4741] are valid. It is assumed that access to 1210 the data and operations defined in this document are subject to 1211 appropriate access control on the device. 1213 7. Acknowledgements 1215 The authors would like to thank Andy Bierman, Mehmet Ersue, Washam 1216 Fan, David Harrington, Balazs Lengyel, Hideki Okita, Juergen 1217 Schoenwaelder, Bert Wijnen and many other members of the NETCONF WG 1218 for providing important input to this document. 1220 8. IANA Considerations 1222 -- Editor note to IANA/RFC-Editor: we request that you make these 1223 assignments, in which case it is to be documented as below. 1225 This document registers two URIs in the IETF XML registry. 1227 Following the format in [RFC3688], the following registration is 1228 requested. 1230 URI: urn:ietf:params:xml:ns:netconf:state 1231 Registrant Contact: The IESG. 1232 XML: N/A, the requested URI is an XML namespace. 1234 URI: urn:ietf:params:xml:ns:inet-types 1235 Registrant Contact: The IESG. 1236 XML: N/A, the requested URI is an XML namespace. 1238 9. Normative References 1240 [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 1241 February 2006. 1243 [NETCONF-EVENT] 1244 Chisholm, S. and H. Trevino, "NETCONF Event 1245 Notifications", ID draft-ietf-netconf-notification-14, 1246 June 2008. 1248 [RFC2119] Bradner, s., ""Key words for use in RFCs to Indicate 1249 Requirement Levels", BCP 14", RFC 2119, March 1997. 1251 [RFC3688] Mealling, M., ""The IETF XML Registry", BCP 81", RFC 3688, 1252 January 2004. 1254 [XML] World Wide Web Consortium, "Extensible Markup Language 1255 (XML) 1.0", W3C XML, February 1998, 1256 . 1258 [XMLSchema] 1259 Fallside, D. and P. Walmsley, "XML Schema Part 0: Primer 1260 Second Edition", W3C XML Schema, October 2004. 1262 [draft-ietf-netconf-partial-lock-07] 1263 Lengyel, Balazs., "Partial Lock RPC for NETCONF", 1264 February 2009. 1266 Appendix A. YANG module (non-normative) 1268 The following YANG module is included as a reference only. It is 1269 based on YANG specification at the time of publishing and is subject 1270 to change as a result of NETMOD work underway to refine YANG. 1272 It is worth noting the included YANG module has a distinct advantage 1273 over the normative XSD: 1275 The normative XSD in this draft does not allow for vendor 1276 extensions of the data model without modification of the base 1277 schema. 1279 In the YANG model, identities are used to provide extensibile 1280 enumerations. In the XSD, this is partially addressed by the use 1281 of QName datatype in the model. 1283 Although this approach is more restrictive than other alternatives 1284 (such as redefinition) it was chosen for simplicity and improved 1285 interoperability. 1287 module ietf-netconf-state { 1289 namespace "urn:ietf:params:xml:ns:netconf:state"; 1290 prefix "ns"; 1292 import ietf-yang-types { prefix yang; } 1293 import ietf-inet-types { prefix inet; } 1295 organization 1296 "IETF NETCONF (Network Configuration) Working Group"; 1298 contact 1299 "WG Web: 1300 WG List: 1302 WG Chair: Mehmet Ersue 1303 1305 WG Chair: Bert Wijnen 1306 1308 Editor: Mark Scott 1309 "; 1311 description 1312 "NETCONF Monitoring Module. 1314 All elements in this module are read-only. 1316 Copyright (c) 2009 IETF Trust and the persons identified as the 1317 document authors. All rights reserved. 1319 This version of this YANG module is part of RFC XXXX; see the 1320 RFC itself for full legal notices."; 1321 // RFC Ed.: replace XXXX with actual RFC number 1322 // and remove this note 1324 revision 2009-06-16 { 1325 description 1326 "Initial revision, published as RFC XXXX."; 1327 // RFC Ed.: replace XXXX with actual RFC number 1328 // and remove this note 1329 } 1331 typedef SessionId { 1332 type uint32 { 1333 range "1..max"; 1334 } 1335 reference "RFC 4741: NETCONF Configuration Protocol"; 1336 } 1338 grouping NETCONFDatastoreType { 1339 description 1340 "Enumeration of possible NETCONF datastore types."; 1341 reference "RFC 4741: NETCONF Configuration Protocol"; 1342 choice datastore { 1343 mandatory true; 1344 leaf running { 1345 type empty; 1346 } 1347 leaf candidate { 1348 type empty; 1349 } 1350 leaf startup { 1351 type empty; 1352 } 1353 } 1354 } 1356 identity transport { 1357 description 1358 "Base identity for session transports."; 1359 } 1361 identity netconf-ssh { 1362 base transport; 1363 reference "RFC 4742"; 1364 } 1366 identity netconf-soap-over-beep { 1367 base transport; 1368 reference "RFC 4743"; 1369 } 1371 identity netconf-soap-over-https { 1372 base transport; 1373 reference "RFC 4743"; 1374 } 1376 identity netconf-beep { 1377 base transport; 1378 reference "RFC 4744"; 1379 } 1381 identity netconf-tls { 1382 base transport; 1383 reference "RFC 5539"; 1384 } 1386 identity schema-format { 1387 description 1388 "Base identity for data model schema languages."; 1389 } 1391 identity xsd { 1392 base schema-format; 1393 reference "W3C REC REC-xmlschema-1-20041028"; 1394 } 1396 identity rng { 1397 base schema-format; 1398 reference "ISO/IEC 19757-2"; 1399 } 1401 identity yang { 1402 base schema-format; 1403 reference "draft-ietf-netmod-yang"; 1404 } 1406 grouping CommonCounters { 1407 description 1408 "Counters that exist both per session, and also globally, 1409 accumulated from all sessions."; 1411 leaf inRpcs { 1412 type yang:zero-based-counter32; 1413 description 1414 "Number of correct requests received."; 1415 } 1416 leaf inBadRpcs { 1417 type yang:zero-based-counter32; 1418 description 1419 "Number of messages received when a message was expected, 1420 that were not correct messages. This includes XML parse 1421 errors and errors on the rpc layer."; 1422 } 1423 leaf outRpcErrors { 1424 type yang:zero-based-counter32; 1425 description 1426 "Number of messages sent which contained an 1427 element."; 1428 } 1429 leaf outNotifications { 1430 type yang:zero-based-counter32; 1431 description 1432 "Number of messages sent."; 1433 } 1434 } 1436 container netconf-state { 1437 config false; 1439 container capabilities { 1440 description 1441 "The list of currently provided NETCONF capabilities. This 1442 may be different than those exchanged during session setup 1443 (i.e. hello)."; 1444 leaf-list capability { 1445 type inet:uri; 1446 } 1447 } 1449 container datastores { 1450 description 1451 "List of NETCONF configuration datastores (e.g. running, 1452 startup, candidate) supported on this device and related 1453 information."; 1454 list datastore { 1455 container name { 1456 uses NETCONFDatastoreType; 1457 } 1458 container locks { 1459 description 1460 "An indication of whether a resource is locked or 1461 unlocked. If locked, additional information about 1462 the locking such as user an time stamp is provided."; 1464 grouping LockInfo { 1465 leaf lockedBySession { 1466 type SessionId; 1467 description 1468 "The session ID of the session that has locked 1469 this resource."; 1470 } 1471 leaf lockedTime { 1472 type yang:date-and-time; 1473 description 1474 "The date and time of when the resource was 1475 locked."; 1476 } 1477 } 1479 choice lockType { 1480 container globalLock { 1481 description 1482 "Present if the global lock is set."; 1483 uses LockInfo; 1484 } 1485 list partialLocks { 1486 key lockId; 1487 description 1488 "For a partial lock this is the lock id returned 1489 in the response."; 1490 leaf lockId { 1491 type uint32; 1492 } 1494 uses LockInfo; 1495 leaf-list select { 1496 type string; 1497 min-elements 1; 1498 description 1499 "The xpath expression which was used to request 1500 the lock."; 1501 } 1502 leaf-list lockedNodes { 1503 type instance-identifier; 1504 description 1505 "The list of instance-identifiers (i.e. the 1506 locked nodes)."; 1508 } 1509 } 1510 } 1511 } 1512 } 1513 } 1515 container schemas { 1516 list schema { 1517 key "identifier version format"; 1518 leaf identifier { 1519 type string; 1520 description 1521 "Identifier to uniquely reference the schema"; 1522 } 1523 leaf version { 1524 type string; 1525 description 1526 "Version of the schema supported. Multiple versions can be 1527 supported simultaneously."; 1528 } 1529 leaf format { 1530 type identityref { 1531 base schema-format; 1532 } 1533 description 1534 "Schema language for the file/module."; 1535 } 1536 leaf namespace { 1537 type inet:uri; 1538 description 1539 "The XML namespace defined by the data model."; 1540 } 1541 leaf location { 1542 type union { 1543 type enumeration { 1544 enum "NETCONF"; 1545 } 1546 type inet:uri; 1547 } 1548 description 1549 "One or more Locations from which the schema can be 1550 retrieved. Can be either on the network device 1551 retrievable explicitly via the NETCONF 1552 operation (denoted by the value 'NETCONF') or some 1553 network location (i.e. URL)."; 1554 } 1555 } 1557 } 1559 container sessions { 1560 description 1561 "List of management sessions currently active on this device."; 1563 list session { 1564 key sessionId; 1565 leaf sessionId { 1566 type SessionId; 1567 } 1568 leaf transport { 1569 type identityref { 1570 base transport; 1571 } 1572 } 1573 leaf username { 1574 type string; 1575 } 1576 leaf sourceHost { 1577 type inet:host; 1578 } 1579 leaf loginTime { 1580 type yang:date-and-time; 1581 description 1582 "Time at which the session was established."; 1583 } 1584 uses CommonCounters { 1585 description 1586 "Per-session counters."; 1587 } 1588 } 1589 } 1591 container statistics { 1592 leaf netconfStartTime { 1593 type yang:date-and-time; 1594 description 1595 "Date and time at which the NETCONF server process was 1596 started. Allows for calculation of time interval for 1597 reported metrics."; 1598 } 1599 leaf inBadHellos { 1600 type yang:zero-based-counter32; 1601 description 1602 "Number of sessions silently dropped because an 1603 invalid message was received. This includes hello 1604 messages with a 'session-id' attribute, bad namespace, and 1605 bad capability declarations."; 1606 } 1607 leaf inSessions { 1608 type yang:zero-based-counter32; 1609 description 1610 "Number of sessions started. This counter is incremented when 1611 a message with a is sent. 1613 inSessions - inBadHellos = 'number of correctly started 1614 netconf sessions'"; 1615 } 1616 leaf droppedSessions { 1617 type yang:zero-based-counter32; 1618 description 1619 "Number of sessions that were abnormally terminated, e.g. due 1620 to idle timeout or transport close. This counter is not 1621 incremented when a session is properly closed by a 1622 operation, or killed by a 1623 operation."; 1624 } 1625 uses CommonCounters { 1626 description 1627 "Global counters, accumulated from all sessions."; 1628 } 1630 } 1632 } 1634 rpc get-schema { 1635 input { 1636 leaf identifier { 1637 type string; 1638 mandatory true; 1639 } 1640 leaf version { 1641 type string; 1642 mandatory true; 1643 } 1644 leaf format { 1645 type identityref { 1646 base schema-format; 1647 } 1648 mandatory true; 1649 } 1650 } 1651 output { 1652 anyxml data { 1653 description "Contains the schema content."; 1654 } 1655 } 1656 } 1657 } 1658 Authors' Addresses 1660 Mark Scott 1661 Nortel 1662 3500 Carling Ave 1663 Nepean, Ontario K2H 8E9 1664 Canada 1666 Email: markscot@nortel.com 1668 Sharon Chisholm 1669 Nortel 1670 3500 Carling Ave 1671 Nepean, Ontario K2H 8E9 1672 Canada 1674 Email: schishol@nortel.com 1676 Martin Bjorklund 1677 Tail-f Systems 1678 Klara Norra Kyrkogata 31 1679 SE-111 22 Stockholm, 1680 Sweden 1682 Email: mbj@tail-f.com