RFC 6022
YANG Module for NETCONF Monitoring
RFC 6022: YANG Module for NETCONF Monitoring 🎀
Internet Engineering Task Force (IETF) 🌸
- Request for Comments: 6022
- Authors: M. Scott (Ericsson) and M. Bjorklund (Tail-f Systems)
- Category: Standards Track ✨
- ISSN: 2070-1721
- Date: October 2010
- Obsoletes/Updates: the header doesn't list anything this one obsoletes or updates, so it stands on its own 💅
Abstract ✨
okay so this doc defines a YANG-style data model for the Network Configuration Protocol (NETCONF) that lets you monitor NETCONF itself 🧚. The monitoring data covers datastores, sessions, locks, and statistics, and it's literally what helps you manage a NETCONF server. It also gives NETCONF clients a way to discover which data models a server supports, plus a brand new <get-schema> operation to go grab them 🦋.
Status of This Memo 🌈
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check Section 2 of RFC 5741 📚.
For the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc6022 🔗.
Copyright Notice 💜
Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved 🎀.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info), as in effect on the date this document was published. Please actually read these, bestie, because they spell out your rights and restrictions for this document 🙈. Code Components pulled out of this document must include the Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF Contributions that were published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of that material may not have granted the IETF Trust the right to allow modifications outside the IETF Standards Process. So unless you get an adequate license from those copyright holders, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside that process. The exception is formatting it for publication as an RFC or translating it into languages other than English 🌍.
Table of Contents 🍓
1. Introduction ....................................................3
1.1. Definition of Terms ........................................3
2. Data Model to Monitor NETCONF ...................................3
2.1. The /netconf-state Subtree .................................3
2.1.1. The /netconf-state/capabilities Subtree .............4
2.1.2. The /netconf-state/datastores Subtree ...............4
2.1.3. The /netconf-state/schemas Subtree ..................5
2.1.4. The /netconf-state/sessions Subtree .................6
2.1.5. The /netconf-state/statistics Subtree ...............7
3. Schema Specific Operations ......................................8
3.1. The <get-schema> Operation .................................8
4. Examples ........................................................9
4.1. Retrieving Schema List via <get> Operation .................9
4.2. Retrieving Schema Instances ...............................11
5. NETCONF Monitoring Data Model ..................................13
6. Security Considerations ........................................25
7. Acknowledgements ...............................................26
8. IANA Considerations ............................................26
9. References .....................................................26
9.1. Normative References ......................................26
9.2. Informative References ....................................271. Introduction ✨
okay so this doc defines a YANG model [RFC6020] for monitoring the NETCONF protocol 💅. It gives you info about NETCONF sessions and the schemas it supports, as defined in [RFC4741] 🦋.
Things like different schema formats, feature optionality, and access controls can all change how applicable things are and how much detail the NETCONF server sends a client during session setup 👀. So the methods in here help you query and retrieve schema and NETCONF state info from a server. They're meant to complement the existing base NETCONF capabilities and operations, and they in no way affect existing behaviour 🫶.
A new <get-schema> operation is also defined, so you can explicitly retrieve schemas over NETCONF 🧚.
1.1. Definition of Terms 📖
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 [RFC2119] 💖.
2. Data Model to Monitor NETCONF 🌸
The NETCONF monitoring data model in this document gives you operational info about the NETCONF server 👑. That includes protocol-specific stuff like counters (for example, 'in-sessions'), and also schema-retrieval data like the schema list 📊.
A server that implements the data model defined here ("urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring") MUST advertise the capability URI as described in [RFC6020] ✨.
This section gives you an overview of the monitoring data model. For the detailed descriptions, check the normative YANG module included in this document (see Section 5) 🔍.
2.1. The /netconf-state Subtree 🌳
The netconf-state container is the root of the monitoring data model 🎀.
netconf-state
/capabilities
/datastores
/schemas
/sessions
/statistics- capabilities: the list of NETCONF capabilities the server supports 🧩.
- datastores: the list of NETCONF configuration datastores (for example, running, startup, candidate) supported on this device, plus related info 💾.
- schemas: the list of schemas the server supports. It includes everything needed to identify the schemas and to support their retrieval 📚.
- sessions: the list of all active NETCONF sessions on the device. It includes per-session counters for every NETCONF session 🦋.
- statistics: global counters for the NETCONF server 📈.
2.1.1. The /netconf-state/capabilities Subtree 🧩
The /netconf-state/capabilities subtree holds the capabilities the NETCONF server supports. The list MUST include all capabilities that were exchanged during session setup and are still applicable at the time of the request 💅.
2.1.2. The /netconf-state/datastores Subtree 💾
The /netconf-state/datastores subtree holds the list of available datastores for the NETCONF server, and it includes info on their lock state 🔐.
datastore
/name
/locks- name (leaf,
netconf-datastore-type): an enumeration of supported datastores: candidate, running, startup 🏷️. - locks (grouping,
lock-info): the list of locks for the datastore. Info is provided for both global and partial locks [RFC5717] ✨. For partial locks, you get back the list of locked nodes and the select expressions that were originally used to request the lock 🔒.
2.1.3. The /netconf-state/schemas Subtree 📚
This is the list of supported schemas for the NETCONF server 🌈.
schema
/identifier (key)
/version (key)
/format (key)
/namespace
/locationThe elements identifier, version, and format are used as a key in the schema list. They're also used in the <get-schema> operation 🔑.
- identifier (string): the identifier for the schema list entry. It's used in the
<get-schema>operation, and it may also be used for other things, like file retrieval 🪪. - version (string): the version of the schema that's supported. Multiple versions MAY be supported at the same time by a NETCONF server. Each version MUST be reported individually in the schema list, meaning same identifier, possibly different location, but a different version 🎀.
For YANG data models, the version is the value of the most recent YANG 'revision' statement in the module or submodule. If there's no 'revision' statement, it's the empty string 🧁.
- format (identifyref,
schema-format): the data modeling language the schema is written in. That language is represented as a YANG identity. This document defines the identities "xsd", "yang", "yin", "rng", and "rnc" (see Section 5) 🦋. - namespace (
inet:uri): the Extensible Markup Language (XML) namespace [XML-NAMES] defined by the schema 🌸. - location (union: enum,
inet:uri): one or more locations where this specific schema can be retrieved from. The list SHOULD contain at least one entry per schema 📍.
2.1.4. The /netconf-state/sessions Subtree 🦋
This 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- session-id (
uint32, 1..max): a unique identifier for the session. This value is the NETCONF session identifier, as defined in [RFC4741] 🪪. - transport (identityref,
transport): identifies the 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 Section 5) 🚇. - username (string): the client identity that was authenticated by the NETCONF transport protocol. The algorithm used to derive the username is specific to the NETCONF transport protocol, and it's also specific to the authentication mechanism that protocol uses 🙋.
- source-host (
inet:host): the host identifier (IP address or name) of the NETCONF client 💻. - login-time (
yang:date-and-time): the time at the server when the session was established ⏰. - in-rpcs (
yang:zero-based-counter32): the number of correct<rpc>messages received ✅. - in-bad-rpcs (
yang:zero-based-counter32): the number of messages received when an<rpc>message was expected, that were not correct<rpc>messages. This includes XML parse errors and errors on the rpc layer 🙈. - out-rpc-errors (
yang:zero-based-counter32): the number of<rpc-reply>messages sent that contained an<rpc-error>element 📤. - out-notifications (
yang:zero-based-counter32): the number of<notification>messages sent 🔔.
part 1 of 4 done, bestie, part 2 is coming next! 🫶✨
2.1.5. The /netconf-state/statistics Subtree
Okay bestie, this is the stats 📊 corner of the subtree, all about how the NETCONF server is doing with its management sessions. Here's the whole family tree:
statistics
/netconf-start-time
/in-bad-hellos
/in-sessions
/dropped-sessions
/in-rpcs
/in-bad-rpcs
/out-rpc-errors
/out-notifications- statistics: This is the container that holds the management-session performance data for the NETCONF server. 💖
netconf-start-time(yang:date-and-time): The date and time when the management subsystem got switched on. 🌸in-bad-hellos(yang:zero-based-counter32): The number of sessions quietly dropped because an invalid<hello>message showed up. Ghosted, literally. 👻in-sessions(yang:zero-based-counter32): The number of sessions that have started. ✨dropped-sessions(yang:zero-based-counter32): The number of sessions that ended abnormally, for example because of an idle timeout or a transport close. 💀in-rpcs(yang:zero-based-counter32): The number of correct<rpc>messages received. Good manners, iconic. 🎀in-bad-rpcs(yang:zero-based-counter32): The number of messages received when an<rpc>message was expected, but which weren't correct<rpc>messages. Oof. 🙈out-rpc-errors(yang:zero-based-counter32): The number of<rpc-reply>messages sent that contained an<rpc-error>element. 😭out-notifications(yang:zero-based-counter32): The number of<notification>messages sent. 🦋
3. Schema Specific Operations
3. Schema Specific Operations 🧚
3.1. The <get-schema> Operation
Description: This operation is how you retrieve a schema from the NETCONF server. It's giving "fetch the blueprint" energy. 📐
Parameters:
identifier(string): The identifier for the schema list entry. Mandatory parameter. 🔑version(string): The version of the schema you're asking for. Optional parameter. 🏷️format(identityref, schema-format): The data modeling language of the schema. The default value is 'yang' when it isn't specified. Optional parameter. 🌈
Positive Response: The NETCONF server hands back the schema you requested. Slay. 💅
Negative Response:
- If the requested schema doesn't exist, the
<error-tag>is 'invalid-value'. Not it. 🙅♀️ - If more than one schema matches the requested parameters, the
<error-tag>is 'operation-failed', and the<error-app-tag>is 'data-not-unique'. Too many lookalikes, bestie. 👯♀️
4. Examples ✨
4.1. Retrieving Schema List via <get> Operation
Okay so a NETCONF client can grab the list of schemas the server supports by fetching the /netconf-state/schemas subtree with a <get> operation. 🛍️
The reply hands back the schemas that are available for the requesting session, each one showing its <identifier>, <version>, <format>, and <location> elements. Main character energy. 👑
The response data is what you use to figure out which schemas are around and what versions they come in. The schema itself (aka the schema content) is not returned in the response, so don't go looking for it there. 🙃 The optional <location> element contains a URI, which you can use to retrieve the schema through another protocol, like ftp [RFC0959] or http(s) [RFC2616] [RFC2818]. Or you can use the special value 'NETCONF', which means the schema can be retrieved from the device via the <get-schema> operation. Two routes, same destination. 🗺️
Example:
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<netconf-state xmlns=
"urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<schemas/>
</netconf-state>
</filter>
</get>
</rpc>The NETCONF server returns a list of the schemas that are available for retrieval. 🎀
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<netconf-state
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<schemas>
<schema>
<identifier>foo</identifier>
<version>1.0</version>
<format>xsd</format>
<namespace>http://example.com/foo</namespace>
<location>ftp://ftp.example.com/schemas/foo_1.0.xsd</location>
<location>http://www.example.com/schema/foo_1.0.xsd</location>
<location>NETCONF</location>
</schema>
<schema>
<identifier>foo</identifier>
<version>1.1</version>
<format>xsd</format>
<namespace>http://example.com/foo</namespace>
<location>ftp://ftp.example.com/schemas/foo_1.1.xsd</location>
<location>http://www.example.com/schema/foo_1.1.xsd</location>
<location>NETCONF</location>
</schema>
<schema>
<identifier>bar</identifier>
<version>2008-06-01</version>
<format>yang</format>
<namespace>http://example.com/bar</namespace>
<location>
http://example.com/schema/bar@2008-06-01.yang
</location>
<location>NETCONF</location>
</schema>
<schema>
<identifier>bar-types</identifier>
<version>2008-06-01</version>
<format>yang</format>
<namespace>http://example.com/bar</namespace>
<location>
http://example.com/schema/bar-types@2008-06-01.yang
</location>
<location>NETCONF</location>
</schema>
</schemas>
</netconf-state>
</data>
</rpc-reply>4.2. Retrieving Schema Instances
Following on from the reply in the previous section, these examples show how to retrieve the 'foo', 'bar', and 'bar-types' schemas at multiple locations, in multiple formats, and from multiple locations. Lots of routes, so pick your favourite. 🧭
- 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. 💌
- a. Via FTP using location
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-schema
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<identifier>foo</identifier>
<version>1.0</version>
<format>xsd</format>
</get-schema>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<!-- foo 1.0 xsd schema contents here -->
</xs:schema>
</data>
</rpc-reply>- 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 identifier and version parameters:
- a. Via HTTP using location
<rpc message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-schema
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<identifer>bar</identifer>
<version>2008-06-01</version>
</get-schema>
</rpc>
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
module bar {
//default format (yang) returned
//bar version 2008-06-01 yang module
//contents here ...
}
</data>
</rpc-reply>- bar-types, version 2008-06-01 in default YANG format:
- a. Via
<get-schema>using identifer parameter:
- a. Via
<rpc message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-schema
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<identifer>bar-types</identifer>
</get-schema>
</rpc>
<rpc-reply message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
module bar-types {
//default format (yang) returned
//latest revision returned
//is version 2008-06-01 yang module
//contents here ...
}
</data>
</rpc-reply>5. NETCONF Monitoring Data Model 🎀
The data model described in this memo is defined in the following YANG module. Here comes the good stuff. 🤩
This YANG module imports typedefs from [RFC6021], and references [RFC4741], [RFC4742], [RFC4743], [RFC4744], [RFC5539], [xmlschema-1], [RFC6020], [ISO/IEC19757-2:2008], and [RFC5717]. Lots of friends in this module. 🫶
<CODE BEGINS> file "ietf-netconf-monitoring@2010-10-04.yang"
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: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
WG Chair: Mehmet Ersue
<mailto:mehmet.ersue@nsn.com>
WG Chair: Bert Wijnen
<mailto:bertietf@bwijnen.net>
Editor: Mark Scott
<mailto:mark.scott@ericsson.com>
Editor: Martin Bjorklund
<mailto:mbj@tail-f.com>";
description
"NETCONF Monitoring Module.
All elements in this module are read-only.
Copyright (c) 2010 IETF Trust and the persons identified as
authors of the code. 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 6022; see
the RFC itself for full legal notices.";
revision 2010-10-04 {
description
"Initial revision.";
reference
"RFC 6022: YANG Module for NETCONF Monitoring";
}
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.";
}Okay, the monitoring module is literally the best part of this whole RFC 🧚 Here's the rest of the netconf-state container, the stats and all 💖
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 6020: YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)";
}
identity yin {
base schema-format;
description
"The YIN syntax for YANG.";
reference
"RFC 6020: YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)";
}
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 <rpc> messages received.";
}
leaf in-bad-rpcs {
type yang:zero-based-counter32;
description
"Number of messages received when an <rpc> message was expected,
that were not correct <rpc> messages. This includes XML parse
errors and errors on the rpc layer.";
}
leaf out-rpc-errors {
type yang:zero-based-counter32;
description
"Number of <rpc-reply> messages sent that contained an
<rpc-error> element.";
}
leaf out-notifications {
type yang:zero-based-counter32;
description
"Number of <notification> 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 <lock> and <partial-lock> 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 that acquired
the lock(s).
Monitoring information is provided for each datastore
entry including details such as the session that 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 that 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-lock {
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 <partial-lock>
response.";
}
uses lock-info;
leaf-list select {
type yang:xpath1.0;
min-elements 1;
description
"The xpath expression that was used to request
the lock. The select expression indicates the
original intended scope of the lock.";
}
leaf-list locked-node {
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 <get-schema> operation and may
be used for other purposes such as file retrieval.
For modeling languages that 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
<get-schema> 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 RFC 4741.";
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 <hello> 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 <hello> message with a <session-id> 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
<close-session> operation, or killed by a <kill-session>
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 <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'.";
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.";
}
}
}
}
<CODE ENDS>6. Security Considerations 🛡️
okay bestie, this is the serious part, so no cap, read it carefully 🔒. The YANG module in this memo is meant to be accessed through the NETCONF protocol [RFC4741]. The lowest NETCONF layer is the secure transport layer, and the mandatory to implement secure transport is SSH [RFC4742] 💜.
Some of the readable data nodes in this YANG module can be sensitive or vulnerable in certain network environments 😭. So it's really important to control read access to these data nodes (for example, through get, get-config, or notification) 🫶.
Here are the containers, list nodes, and data nodes that have specific sensitivity or vulnerability:
/netconf-state/sessions/session/username: this one contains identity information that could be used in an attempt to authenticate with the server 💀.
This username is only meant for monitoring, and it SHOULD NOT be used for other purposes, such as access control, without a detailed discussion of the limitations of this reported username 🙈. For example, server A and server B might both report the same username, but those could belong to two different people 👯.
7. Acknowledgements 🫶
The authors want 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 giving important input to this document 🌈. They also want to specifically shout out Sharon Chisholm's work on "NETCONF Monitoring Schema" [NETCONF] and her contribution to this document ✨.
8. IANA Considerations 📋
This document registers one URI in "The IETF XML Registry" 🧚. Following the format in [RFC3688], the following has been registered:
URI: urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.This document also registers one module in the "YANG Module Names" registry 🍓. Following the format in [RFC6020], the following has been registered:
name: ietf-netconf-monitoring
namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring
prefix: ncm
reference: RFC 60229. References 📚
9.1. Normative References
- [ISO/IEC19757-2:2008] ISO/IEC, "Document Schema Definition Language (DSDL) -- Part 2: Regular-grammar-based validation -- RELAX NG", December 2008,
<http://www.iso.org/iso/catalogue_detail.htm?csnumber=37605>. - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006.
- [RFC4742] Wasserman, M. and T. Goddard, "Using the NETCONF Configuration Protocol over Secure SHell (SSH)", RFC 4742, December 2006.
- [RFC4743] Goddard, T., "Using NETCONF over the Simple Object Access Protocol (SOAP)", RFC 4743, December 2006.
- [RFC4744] Lear, E. and K. Crozier, "Using the NETCONF Protocol over the Blocks Extensible Exchange Protocol (BEEP)", RFC 4744, December 2006.
- [RFC5539] Badra, M., "NETCONF over Transport Layer Security (TLS)", RFC 5539, May 2009.
- [RFC5717] Lengyel, B. and M. Bjorklund, "Partial Lock Remote Procedure Call (RPC) for NETCONF", RFC 5717, December 2009.
- [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", October 2010.
- [RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types", October 2010.
- [XML-NAMES] Hollander, D., Tobin, R., Thompson, H., Bray, T., and A. Layman, "Namespaces in XML 1.0 (Third Edition)", World Wide Web Consortium Recommendation REC-xml-names-20091208, December 2009,
<http://www.w3.org/TR/2009/REC-xml-names-20091208>. - [xmlschema-1] Biron, Paul V. and Ashok. Malhotra, "XML Schema Part 1: Structures Second Edition W3C Recommendation 28 October 2004", October 2004,
<http://www.w3.org/TR/xmlschema-1>.
9.2. Informative References
- [NETCONF] Chisholm, S. and H. Trevino, "NETCONF Monitoring Schema", Work in Progress, February 2007.
- [RFC0959] Postel, J. and J. Reynolds, "File Transfer Protocol", STD 9, RFC 959, October 1985.
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
- [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
- [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.
Authors' Addresses 🌸
Mark Scott
Ericsson
3500 Carling Ave
Nepean, Ontario K2H 8E9
Canada
EMail: mark.scott@ericsson.com
Martin Bjorklund
Tail-f Systems
Klara Norra Kyrkogata 31
SE-111 22 Stockholm,
Sweden
EMail: mbj@tail-f.com📦 where this page comes from
- ietf: rfc6022 2010-10
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms