YANG Module for NETCONF Monitoring Ericsson
3500 Carling Ave Nepean Ontario K2H 8E9 Canada mark.scott@ericsson.com
Tail-f Systems
Klara Norra Kyrkogata 31 SE-111 22 Stockholm Sweden mbj@tail-f.com
Operations and Management XML NETCONF YANG monitoring This document defines a NETCONF data model to be used to monitor the NETCONF protocol. The monitoring data model includes information about NETCONF datastores, sessions, locks and statistics. This data facilitates the management of a NETCONF server. This document also defines methods for NETCONF clients to discover data models supported by a NETCONF server and defines a new NETCONF <get-schema> operation to retrieve them.
This document defines a model to be used to monitor the NETCONF protocol. It provides information about NETCONF sessions and supported schema as defined in . Considerations such as different schema formats, feature optionality and access controls can all impact the applicability and level of detail the NETCONF server sends to a client during session setup. The methods defined in this document address the need for further means to query and retrieve schema and NETCONF state information from a NETCONF server. These are provided to complement existing base NETCONF capabilities and operations and in no way affect existing behaviour. A new <get-schema> operation is also defined to support explicit schema retrieval via NETCONF.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, .
The NETCONF monitoring data model defined in this document provides operational information on the NETCONF server. This includes details specific to the NETCONF protocol (e.g., protocol specific counters such as 'in-sessions') as well as data related to schema retrieval (e.g., schema list). A server that implements the data model defined in this document MUST advertise the capability URI "urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring", as described in . This section presents an overview of the monitoring data model. For detailed descriptions refer to the normative YANG module provided in this document (see ).
The netconf-state container is the root of the monitoring data model.
netconf-state /capabilities /datastores /schemas /sessions /statistics
List of NETCONF capabilities supported by the server. List of NETCONF configuration datastores (e.g., running, startup, candidate) supported on this device and related information. List of schemas supported on the server. Includes all the information required to identify the schemas and to support their retrieval. List of all active NETCONF sessions on the device. Includes per session counters for all NETCONF sessions. Includes global counters for the NETCONF server.
The /netconf-state/capabilities subtree contains the capabilities supported by the NETCONF server. The list MUST include all capabilities exchanged during session setup still applicable at the time of the request.
The /netconf-state/datastores subtree contains the list of available datastores for the NETCONF server and includes information on their lock state.
configuration /name /locks
Enumeration of supported datastores; candidate, running, startup. List of locks for the datastore. Information is provided for both global and partial locks . For partial locks the list of locked nodes and the select expressions originally used to request the lock are returned.
The list of supported schema for the NETCONF server.
schema /identifier (key) /version (key) /format (key) /namespace /location
The elements identifier, version, and format are used as a key in the schema list. These are used in the <get-schema> operation. Identifier for the schema list entry. The identifier is used in the <get-schema> operation and may be used for other means such as file retrieval. Version of the schema supported. Multiple versions MAY be supported simultaneously by a NETCONF server. Each version MUST be reported individually in the schema list, i.e., with same identifier, possibly different location, but different version. For YANG data models, version is the value of the most recent YANG 'revision' statement in the module or submodule, or the empty string if no revision statement is present. The data modeling language the schema is written in. The data modeling language is represented as a YANG identity. This document defines the identities "xsd", "yang", "yin", "rng" and "rnc" (see ). The Extensible Markup Language (XML) namespace defined by the schema. One or more locations from which this specific schema can be retrieved. The list SHOULD contain at least one entry per schema.
Includes session specific data for NETCONF management sessions. The session list MUST include all currently active NETCONF sessions.
session /session-id (key) /transport /username /source-host /login-time /in-rpcs /in-bad-rpcs /out-rpc-errors /out-notifications
Unique identifier for the session. This value is the NETCONF session identifier, as defined in . Identifies transport for each session. The transport is represented as a YANG identity. This document defines the identities "netconf-ssh", "netconf-soap-over-beep", "netconf-soap-over-https", "netconf-beep", and "netconf-tls" (see ). The username is the client identity that was authenticated by the NETCONF transport protocol. The algorithm used to derive the username is NETCONF transport protocol specific and in addition specific to the authentication mechanism used by the NETCONF transport protocol. Host identifier (IP address or name) of the NETCONF client. Time at the server at which the session was established. Number of correct <rpc> requests received. Number of messages received when a <rpc> message was expected, that were not correct <rpc> messages. This includes XML parse errors and errors on the rpc layer. Number of <rpc-reply> messages sent which contained an <rpc-error> element. Number of <notification> messages sent.
Statistical data pertaining to the NETCONF server.
statistics /netconf-start-time /in-bad-hellos /in-sessions /dropped-sessions /in-rpcs /in-bad-rpcs /out-rpc-errors /out-notifications
Contains management session related performance data for the NETCONF server. Date and time at which the management subsystem was started. Number of sessions silently dropped because an invalid <hello> message was received. Number of sessions started. Number of sessions that were abnormally terminated, e.g., due to idle timeout or transport close. Number of correct <rpc> requests received. Number of messages received when a <rpc> message was expected, that were not correct <rpc> messages. Number of <rpc-reply> messages sent which contained an <rpc-error> element. Number of <notification> messages sent.
This operation is used to retrieve a schema from the NETCONF server. Identifier for the schema list entry. Mandatory parameter. Version of the schema requested. Optional parameter. The data modeling language of the schema. Default value is 'yang' when not specified. Optional parameter. The NETCONF server returns the requested schema. If the requested schema does not exist, the <error‑tag> is 'invalid‑value'. If more than one schema matches the requested parameters, the <error‑tag> is 'operation‑failed', and <error‑app‑tag> is 'data‑not‑unique'.
A NETCONF client retrieves the list of supported schema from a NETCONF server by retrieving the /netconf-state/schemas subtree via a <get> operation. Available schema for the requesting session are returned in the reply containing the <identifier>,<version>, <format>, and <location> elements. The response data can be used to determine the available schema and their versions. The schema itself (i.e., schema content) is not returned in the response. The optional <location> element contains a URI, which can be used to retrieve the schema by another protocol such as ftp or http(s) , or the special value 'NETCONF', which means that the schema can be retrieved from the device via the <get-schema> operation. Example:
]]> The NETCONF server returns a list of schema available for retrieval. foo 1.0 xsd http://example.com/foo ftp://ftp.example.com/schemas/foo_1.0.xsd http://www.example.com/schema/foo_1.0.xsd NETCONF foo 1.1 xsd http://example.com/foo ftp://ftp.example.com/schemas/foo_1.1.xsd http://www.example.com/schema/foo_1.1.xsd NETCONF bar 2008-06-01 yang http://example.com/bar http://example.com/schema/bar@2008-06-01.yang NETCONF bar-types 2008-06-01 yang http://example.com/bar http://example.com/schema/bar-types@2008-06-01.yang NETCONF ]]>
Given the reply in the previous section, the following examples illustrate the retrieval of 'foo', 'bar', and 'bar-types' schema at multiple locations, with multiple formats, and in multiple locations.
1. foo, version 1.0 in xsd format: a. Via FTP using location ftp://ftp.example.com/schemas/foo_1.0.xsd b. Via HTTP using location http://www.example.com/schema/foo_1.0.xsd c. Via <get-schema> using identifier, version, and format parameters. foo 1.0 xsd ]]> 2. bar, version 2008-06-01 in YANG format: a. Via HTTP using location http://example.com/schema/bar@2008-06-01.yang b. Via <get-schema> using identifer and version parameters: bar 2008-06-01 module bar { //default format (yang) returned //bar version 2008-06-01 yang module //contents here ... } ]]> 3. bar-types, version 2008-06-01 in default YANG format: a. Via <get-schema> using identifer parameter: bar-types module bar-types { //default format (yang) returned //latest revision returned //is version 2008-06-01 yang module //contents here ... } ]]>
The data model described in this memo is defined in the following YANG module. This YANG module imports typedefs from and references , , , , , , , , and .
module ietf-netconf-monitoring { namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring"; prefix "ncm"; import ietf-yang-types { prefix yang; } import ietf-inet-types { prefix inet; } organization "IETF NETCONF (Network Configuration) Working Group"; contact "WG Web: WG List: WG Chair: Mehmet Ersue WG Chair: Bert Wijnen Editor: Mark Scott Editor: Martin Bjorklund "; description "NETCONF Monitoring Module. All elements in this module are read-only. Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX; see the RFC itself for full legal notices."; // RFC Ed.: replace XXXX with actual RFC number and remove this note revision 2010-06-22 { description "Initial revision."; reference "RFC XXXX: YANG Module for NETCONF Monitoring"; // RFC Ed.: replace XXXX with actual RFC number and remove this note } typedef netconf-datastore-type { type enumeration { enum running; enum candidate; enum startup; } description "Enumeration of possible NETCONF datastore types."; reference "RFC 4741: NETCONF Configuration Protocol"; } identity transport { description "Base identity for NETCONF transport types."; } identity netconf-ssh { base transport; description "NETCONF over Secure Shell (SSH)."; reference "RFC 4742: Using the NETCONF Configuration Protocol over Secure SHell (SSH)"; } identity netconf-soap-over-beep { base transport; description "NETCONF over Simple Object Access Protocol (SOAP) over Blocks Extensible Exchange Protocol (BEEP)."; reference "RFC 4743: Using NETCONF over the Simple Object Access Protocol (SOAP)"; } identity netconf-soap-over-https { base transport; description "NETCONF over Simple Object Access Protocol (SOAP) over Hypertext Transfer Protocol Secure (HTTPS)."; reference "RFC 4743: Using NETCONF over the Simple Object Access Protocol (SOAP)"; } identity netconf-beep { base transport; description "NETCONF over Blocks Extensible Exchange Protocol (BEEP)."; reference "RFC 4744: Using the NETCONF Protocol over the Blocks Extensible Exchange Protocol (BEEP)"; } identity netconf-tls { base transport; description "NETCONF over Transport Layer Security (TLS)."; reference "RFC 5539: NETCONF over Transport Layer Security (TLS)"; } identity schema-format { description "Base identity for data model schema languages."; } identity xsd { base schema-format; description "W3C XML Schema Definition."; reference "W3C REC REC-xmlschema-1-20041028: XML Schema Part 1: Structures"; } identity yang { base schema-format; description "The YANG data modeling language for NETCONF."; reference "RFC YYYY: YANG - A data modeling language for NETCONF"; // RFC Ed.: replace YYYY with actual RFC number and remove this note } identity yin { base schema-format; description "The YIN syntax for YANG."; reference "RFC YYYY: YANG - A data modeling language for NETCONF"; // RFC Ed.: replace YYYY with actual RFC number and remove this note } identity rng { base schema-format; description "Regular Language for XML Next Generation (RELAX NG)."; reference "ISO/IEC 19757-2:2008: RELAX NG"; } identity rnc { base schema-format; description "Relax NG Compact Syntax"; reference "ISO/IEC 19757-2:2008: RELAX NG"; } grouping common-counters { description "Counters that exist both per session, and also globally, accumulated from all sessions."; leaf in-rpcs { type yang:zero-based-counter32; description "Number of correct messages received."; } leaf in-bad-rpcs { type yang:zero-based-counter32; description "Number of messages received when a message was expected, that were not correct messages. This includes XML parse errors and errors on the rpc layer."; } leaf out-rpc-errors { type yang:zero-based-counter32; description "Number of messages sent which contained an element."; } leaf out-notifications { type yang:zero-based-counter32; description "Number of messages sent."; } } container netconf-state { config false; description "The netconf-state container is the root of the monitoring data model."; container capabilities { description "Contains the list of NETCONF capabilities supported by the server."; leaf-list capability { type inet:uri; description "List of NETCONF capabilities supported by the server."; } } container datastores { description "Contains the list of NETCONF configuration datastores."; list datastore { key name; description "List of NETCONF configuration datastores supported by the NETCONF server and related information."; leaf name { type netconf-datastore-type; description "Name of the datastore associated with this list entry."; } container locks { presence "This container is present only if the datastore is locked."; description "The NETCONF and operations allow a client to lock specific resources in a datastore. The NETCONF server will prevent changes to the locked resources by all sessions except the one which acquired the lock(s). Monitoring information is provided for each datastore entry including details such as the session which acquired the lock, the type of lock (global or partial) and the list of locked resources. Multiple locks per datastore are supported."; grouping lock-info { description "Lock related parameters, common to both global and partial locks."; leaf locked-by-session { type uint32; mandatory true; description "The session ID of the session that has locked this resource. Both a global lock and a partial lock MUST contain the NETCONF session-id. If the lock is held by a session which is not managed by the NETCONF server (e.g., a CLI session), a session id of 0 (zero) is reported."; reference "RFC 4741: NETCONF Configuration Protocol"; } leaf locked-time { type yang:date-and-time; mandatory true; description "The date and time of when the resource was locked."; } } choice lock-type { description "Indicates if a global lock or a set of partial locks are set."; container global-lock { description "Present if the global lock is set."; uses lock-info; } list partial-locks { key lock-id; description "List of partial locks."; reference "RFC 5717: Partial Lock Remote Procedure Call (RPC) for NETCONF"; leaf lock-id { type uint32; description "This is the lock id returned in the response."; } uses lock-info; leaf-list select { type string; min-elements 1; description "The xpath expression which was used to request the lock. The select expression indicates the original intended scope of the lock."; } leaf-list locked-nodes { type instance-identifier; description "The list of instance-identifiers (i.e., the locked nodes). The scope of the partial lock is defined by the list of locked nodes."; } } } } } } container schemas { description "Contains the list of data model schemas supported by the server."; list schema { key "identifier version format"; description "List of data model schemas supported by the server."; leaf identifier { type string; description "Identifier to uniquely reference the schema. The identifier is used in the operation and may be used for other purposes such as file retrieval. For modeling languages which support or require a data model name (e.g., YANG module name) the identifier MUST match that name. For YANG data models, the identifier is the name of the module or submodule. In other cases an identifier such as a filename MAY be used instead."; } leaf version { type string; description "Version of the schema supported. Multiple versions MAY be supported simultaneously by a NETCONF server. Each version MUST be reported individually in the schema list, i.e., with same identifier, possibly different location, but different version. For YANG data models, version is the value of the most recent YANG 'revision' statement in the module or submodule, or the empty string if no revision statement is present."; } leaf format { type identityref { base schema-format; } description "The data modeling language the schema is written in (currently xsd, yang, yin, rng or rnc). For YANG data models, 'yang' format MUST be supported and 'yin' format MAY also be provided."; } leaf namespace { type inet:uri; mandatory true; description "The XML namespace defined by the data model. For YANG data models, this is the module's namespace. If the list entry describes a submodule, this field contains the namespace of the module to which the submodule belongs."; } leaf-list location { type union { type enumeration { enum "NETCONF"; } type inet:uri; } description "One or more locations from which the schema can be retrieved. This list SHOULD contain at least one entry per schema. A schema entry may be located on a remote file system (e.g., reference to file system for ftp retrieval) or retrieved directly from a server supporting the operation (denoted by the value 'NETCONF')."; } } } container sessions { description "The sessions container includes session specific data for NETCONF management sessions. The session list MUST include all currently active NETCONF sessions."; list session { key session-id; description "All NETCONF sessions managed by the NETCONF server MUST be reported in this list."; leaf session-id { type uint32 { range "1..max"; } description "Unique identifier for the session. This value is the NETCONF session identifier, as defined in RFC4741."; reference "RFC 4741: NETCONF Configuration Protocol"; } leaf transport { type identityref { base transport; } mandatory true; description "Identifies the transport for each session, e.g., 'netconf-ssh', 'netconf-soap', etc."; } leaf username { type string; mandatory true; description "The username is the client identity that was authenticated by the NETCONF transport protocol. The algorithm used to derive the username is NETCONF transport protocol specific and in addition specific to the authentication mechanism used by the NETCONF transport protocol."; } leaf source-host { type inet:host; description "Host identifier of the NETCONF client. The value returned is implementation specific (e.g., hostname, IPv4 address, IPv6 address)"; } leaf login-time { type yang:date-and-time; mandatory true; description "Time at the server at which the session was established."; } uses common-counters { description "Per-session counters. Zero based with following reset behaviour: - at start of a session - when max value is reached"; } } } container statistics { description "Statistical data pertaining to the NETCONF server."; leaf netconf-start-time { type yang:date-and-time; description "Date and time at which the management subsystem was started."; } leaf in-bad-hellos { type yang:zero-based-counter32; description "Number of sessions silently dropped because an invalid message was received. This includes hello messages with a 'session-id' attribute, bad namespace, and bad capability declarations."; } leaf in-sessions { type yang:zero-based-counter32; description "Number of sessions started. This counter is incremented when a message with a is sent. 'in-sessions' - 'in-bad-hellos' = 'number of correctly started netconf sessions'"; } leaf dropped-sessions { type yang:zero-based-counter32; description "Number of sessions that were abnormally terminated, e.g., due to idle timeout or transport close. This counter is not incremented when a session is properly closed by a operation, or killed by a operation."; } uses common-counters { description "Global counters, accumulated from all sessions. Zero based with following reset behaviour: - re-initialization of NETCONF server - when max value is reached"; } } } rpc get-schema { description "This operation is used to retrieve a schema from the NETCONF server. Positive Response: The NETCONF server returns the requested schema. Negative Response: If requested schema does not exist, the is 'invalid-value'. If more than one schema matches the requested parameters, the is 'operation-failed', and is 'data-not-unique'."; input { leaf identifier { type string; mandatory true; description "Identifier for the schema list entry."; } leaf version { type string; description "Version of the schema requested. If this parameter is not present, and more than one version of the schema exists on the server, a 'data-not-unique' error is returned, as described above."; } leaf format { type identityref { base schema-format; } description "The data modeling language of the schema. If this parameter is not present, and more than one formats of the schema exists on the server, a 'data-not-unique' error is returned, as described above."; } } output { anyxml data { description "Contains the schema content."; } } } } ]]>
The YANG module defined in this memo is designed to be accessed via the NETCONF protocol . The lowest NETCONF layer is the secure transport layer and the mandatory to implement secure transport is SSH . Some of the readable data nodes in this YANG module may be considered sensitive or vulnerable in some network environments. It is thus important to control read access (e.g., via get, get-config or notification) to these data nodes. These are the containers, list nodes and data nodes with their specific sensitivity/vulnerability: Contains identity information which could be used in an attempt to authenticate with the server. This username is only meant for monitoring, and SHOULD NOT be used for other purposes, such as access control, without a detailed discussion of the limitations of this reported username. For example, it is possible that server A and server B might report the same username, but these might be for different persons.
The authors would like to thank Andy Bierman, Mehmet Ersue, Washam Fan, David Harrington, Balazs Lengyel, Hideki Okita, Juergen Schoenwaelder, Bert Wijnen and many other members of the NETCONF WG for providing important input to this document. The authors would also like to specifically acknowledge Sharon Chisholm's work on 'draft-netconf-chisholm-monitoring-02' and contribution to this document.
-- Editor note to IANA/RFC-Editor: we request that you make these assignments, in which case it is to be documented as below replacing 'RFCXXXX' as appropriate This document registers one URI in "The IETF XML Registry". Following the format in the following is requested.
This document registers one module in the "YANG Module Names" registry. Following the format in the following is requested.
[-- Editor note to IANA/RFC-Editor: Please remove this section upon publication.]
negative response - Yang Module changes: - added Martin to list of contacts - prefix changed to 'ncm' (netconf monitoring) - grouping netconf-datastore-type is now an enumeration - netconf-over-soap-over-beep description update - netconf-over-soap-over-https description update - yang identity description update - yin identity description update - fixed reference statement in yin identity - capabilities leaf-list description update - added presence statement to locks container - name changed from container to leaf node - name key added for datastores list - added typedef sessionid-or-zero - locked-time now mandatory - lock-type description added - schemas description added - schema description added - namespace now mandatory ]]>
'session-type'. This change impacts both the draft text and yang module. - <get-schema> operation updated: - now has only one mandatory parameter, 'identifier' - updated negative responses, including the rpc operation description in yang module - comments added to the yang module indicating that the definition of 'session-id' is consistent with 4741bis 'session-id-type' and could be imported from that pending RFC. Similar for 'netconf-datastore-type'. This was in favour of adding further dependencies and delays by waiting for 4741bis to complete. ]]>
 Partial Lock Remote Procedure Call (RPC) for NETCONF Ericsson Hungary Ltd. Tail-f Systems Namespaces in XML 1.0 (Third Edition) NETCONF Configuration Protocol Juniper "Key words for use in RFCs to Indicate Requirement Levels", BCP 14 MIT Using the NETCONF Configuration Protocol over Secure SHell (SSH) ThingMagic ICEsoft Technologies, Inc. Using NETCONF over the Simple Object Access Protocol (SOAP) ICEsoft Technologies, Inc. Using the NETCONF Protocol over the Blocks Extensible Exchange Protocol (BEEP) Cisco Systems NETCONF over Transport Layer Security (TLS) CNRS/LIMOS Laboratory YANG - A data modeling language for NETCONF Tail-f Systems Common YANG Data Types Jacobs University XML Schema Part 1: Structures Second Edition W3C Recommendation 28 October 2004 Kaiser Permanente, for Health Level Seven Microsoft (formerly of IBM) Document Schema Definition Language (DSDL) -- Part 2: Regular-grammar-based validation -- RELAX NG ISO/IEC File Transfer Protocol Information Sciences Institute (ISI) Hypertext Transfer Protocol -- HTTP/1.1 Department of Information and Computer Science
University of California, Irvine Irvine CA 92697-3425 +1(949)824-1715 fielding@ics.uci.edu
 World Wide Web Consortium
MIT Laboratory for Computer Science, NE43-356 545 Technology Square Cambridge MA 02139 +1(617)258-8682 jg@w3.org
 Compaq Computer Corporation
Western Research Laboratory 250 University Avenue Palo Alto CA 94305 mogul@wrl.dec.com
 World Wide Web Consortium
MIT Laboratory for Computer Science, NE43-356 545 Technology Square Cambridge MA 02139 +1(617)258-8682 frystyk@w3.org
 Xerox Corporation
MIT Laboratory for Computer Science, NE43-356 3333 Coyote Hill Road Palo Alto CA 94034 masinter@parc.xerox.com
 Microsoft Corporation
1 Microsoft Way Redmond WA 98052 paulle@microsoft.com
 World Wide Web Consortium
MIT Laboratory for Computer Science, NE43-356 545 Technology Square Cambridge MA 02139 +1(617)258-8682 timbl@w3.org
 The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. It is a generic, stateless, protocol which can be used for many tasks beyond its use for hypertext, such as name servers and distributed object management systems, through extension of its request methods, error codes and headers . A feature of HTTP is the typing and negotiation of data representation, allowing systems to be built independently of the data being transferred. HTTP has been in use by the World-Wide Web global information initiative since 1990. This specification defines the protocol referred to as "HTTP/1.1", and is an update to RFC 2068 . HTTP Over TLS This memo describes how to use Transport Layer Security (TLS) to secure Hypertext Transfer Protocol (HTTP) connections over the Internet. This memo provides information for the Internet community. The IETF XML Registry VeriSign, Inc.