RFC 6244
An Architecture for Network Management Using NETCONF and YANG
Abstract ✨
okay so NETCONF 🎀 gives you access to the native powers of every device in a network. It's got methods for editing configuration databases, pulling operational data, and invoking specific operations. YANG is the part that defines what goes inside NETCONF, both the data and the operations 💅 Together they let standard modules give devices interoperability and commonality, while every device still gets to show off what makes it unique 🦋
This document is all about how NETCONF and YANG team up to build network management apps that actually meet what network operators need 🫶
Status of This Memo 🌸
this one is NOT an Internet Standards Track spec, it's published for informational purposes, so no pressure 🙈
It's a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community, it got public review, and the Internet Engineering Steering Group (IESG) approved it for publication. Not everything the IESG approves is a candidate for any level of Internet Standard, so see Section 2 of RFC 5741 for the deets 💜
For the current status, any errata, and how to give feedback, check http://www.rfc-editor.org/info/rfc6244 🍓
Copyright Notice 💖
Copyright (c) 2011 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 of publication. Please actually read those, because they spell out your rights and restrictions for this document 👀 Code Components pulled out of this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as the Simplified BSD License describes.
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of that material may not have given the IETF Trust permission to allow modifications outside the IETF Standards Process. So unless you get an adequate license from whoever controls that copyright, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be made outside it either. The only exceptions are formatting it for publication as an RFC or translating it into languages other than English 🧚
⚠️ bestie, this is the boring legal part but it matters. Don't modify this doc outside the IETF Standards Process unless the exceptions above apply!
Table of Contents 🎀
1. Origins of NETCONF and YANG . . . . . . . . . . . . . . . . . 4
2. Elements of the Architecture . . . . . . . . . . . . . . . . . 5
2.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.1. NETCONF Transport Mappings . . . . . . . . . . . . . . 7
2.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.1. Constraints . . . . . . . . . . . . . . . . . . . . . 10
2.2.2. Flexibility . . . . . . . . . . . . . . . . . . . . . 11
2.2.3. Extensibility Model . . . . . . . . . . . . . . . . . 12
2.3. YANG Translations . . . . . . . . . . . . . . . . . . . . 13
2.3.1. YIN . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.3.2. DSDL (RELAX NG) . . . . . . . . . . . . . . . . . . . 14
2.4. YANG Types . . . . . . . . . . . . . . . . . . . . . . . . 14
2.5. IETF Guidelines . . . . . . . . . . . . . . . . . . . . . 14
3. Working with YANG . . . . . . . . . . . . . . . . . . . . . . 14
3.1. Building NETCONF- and YANG-Based Solutions . . . . . . . . 14
3.2. Addressing Operator Requirements . . . . . . . . . . . . . 16
3.3. Roles in Building Solutions . . . . . . . . . . . . . . . 18
3.3.1. Modeler . . . . . . . . . . . . . . . . . . . . . . . 19
3.3.2. Reviewer . . . . . . . . . . . . . . . . . . . . . . . 19
3.3.3. Device Developer . . . . . . . . . . . . . . . . . . . 19
3.3.4. Application Developer . . . . . . . . . . . . . . . . 20
4. Modeling Considerations . . . . . . . . . . . . . . . . . . . 22
4.1. Default Values . . . . . . . . . . . . . . . . . . . . . . 22
4.2. Compliance . . . . . . . . . . . . . . . . . . . . . . . . 23
4.3. Data Distinctions . . . . . . . . . . . . . . . . . . . . 24
4.3.1. Background . . . . . . . . . . . . . . . . . . . . . . 24
4.3.2. Definitions . . . . . . . . . . . . . . . . . . . . . 25
4.3.3. Implications . . . . . . . . . . . . . . . . . . . . . 27
4.4. Direction . . . . . . . . . . . . . . . . . . . . . . . . 27
5. Security Considerations . . . . . . . . . . . . . . . . . . . 28
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.1. Normative References . . . . . . . . . . . . . . . . . . . 28
6.2. Informative References . . . . . . . . . . . . . . . . . . 29Title Block 📜
- RFC number and title: RFC 6244, An Architecture for Network Management Using NETCONF and YANG 🎀
- Authors: P. Shafer, Juniper Networks 👑
- Category: Informational 🌸
- Date: June 2011 🦋
- ISSN: 2070-1721 ✨
- Obsoletes / Updates: the header doesn't list anything this RFC obsoletes or updates 🙈
1. Origins of NETCONF and YANG ✨
okay so networks are getting more complex and higher capacity, plus more services are packed on top of them 📈 Uptime, reliability, and predictable latency needs are basically forcing us to automate things 🤖 Network management problems aren't simple, bestie. They're complex and intricate 😭 But they have to get solved so networks can keep existing services stable while bringing in new ones, especially since network growth is burning through the supply of qualified networking engineers 💀
In June of 2002, the Internet Architecture Board (IAB) ran a workshop on Network Management [RFC3535]. The people there shared a bunch of observations and recommendations for the IETF to consider, about the problems operators were dealing with in their network management work and also about the direction of IETF activity in this area 🧐
The workshop was super focused on current problems 🔥 The observations were reasonable and straightforward. They included the need for transactions, rollback, low implementation costs, and the ability to save and restore a device's configuration data 🫶 A lot of them explained why operators were struggling with existing network management solutions, like the lack of full coverage of device capabilities, and not being able to tell configuration data apart from other kinds of data 😤
So the NETCONF working group got formed, and the Network Configuration (NETCONF) protocol was created 🎉 It's a simple mechanism where network management applications act as clients and invoke operations on devices, which act as servers 🧚 The NETCONF specification [RFC4741] defines a small set of operations, but it goes out of its way to not put any requirements on the data carried in those operations. It prefers to let the protocol carry any data at all 💅 That "data model agnostic" approach means data models can be defined independently 🌈
BUT here's the tea: without a way to define data models, NETCONF just wasn't usable for standards-based work 😩 Existing data modeling languages like the XML Schema Definition (XSD) [W3CXSD] and the Document Schema Definition Languages (DSDL) [ISODSDL] got considered, and got rejected because the domains have little natural overlap. Defining a data model or protocol encoded in XML is a totally different problem from defining an XML document 🙅♀️ NETCONF operations put requirements on data content that aren't shared with the static document problem domain that schema languages like XSD or RELAX NG handle 💖
In 2007 and 2008, the issue of a data modeling language for NETCONF got discussed in the OPS and APP areas of IETF 70 and 71 🗣️ A design team was tasked with writing a requirements document [RCDML]. After the options were discussed at the CANMOD BoF at IETF 71, the community wrote a charter for the NETMOD working group 📝 If you want an excellent recap of this period, check <http://www.ietf.org/mail-archive/web/ietf/current/msg51644.html> 🍓
In 2008 and 2009, the NETMOD working group produced a spec for YANG [RFC6020]. YANG is a means for defining data models for NETCONF, and it lets both standard and proprietary data models get published in a form that human readers can easily digest 🧠✨ It also satisfies many of the issues raised at the IAB NM workshop, so NETCONF is finally at a point where it can be used to develop standard data models within the IETF 🎀👑
YANG lets a modeler create a data model, define how the data in that model is organized, and define constraints on that data 🦋 Once it's published, the YANG module acts as a contract between client and server, where both sides understand how their peer will expect them to behave 🫶 A client knows how to create valid data for the server and knows what data the server will send back. A server knows the rules governing the data and how it should behave 💅
YANG also has a level of extensibility and flexibility that other modeling languages don't have 🌟 New modules can augment the data hierarchies defined in other modules, seamlessly adding data in the right places within the existing organization 🧚 YANG also lets new statements be defined, so the language itself can expand in a consistent way 🌈
This document presents an architecture for YANG. It describes how YANG-related technologies work and how solutions built on them can tackle the network management problem domain 💖
2. Elements of the Architecture ✨
2.1. NETCONF 🎀
okay so NETCONF is giving remote procedure calls (RPCs) that are encoded in XML 💅 and it's built on XML because XML parsers are everywhere and honestly so good. XML is a rich, flexible, hierarchical way to represent data, which is exactly what networking devices need. NETCONF carries configuration data and operations as requests and replies, and it does all of that over a connection-oriented transport. no cap, it's a whole vibe 🦋
XML's hierarchy lets complex networking data look natural, and this example is so clean 😭 It places interfaces into OSPF areas. The <ospf> element holds a list of <area> elements, and each area holds a list of <interface> elements. The <name> element tells you which area or interface you're looking at, and any extra config for that area or interface just sits right inside its element 🌸
<ospf xmlns="http://example.org/netconf/ospf">
<area>
<name>0.0.0.0</name>
<interface>
<name>ge-0/0/0.0</name>
<!-- The priority for this interface -->
<priority>30</priority>
<metric>100</metric>
<dead-interval>120</dead-interval>
</interface>
<interface>
<name>ge-0/0/1.0</name>
<metric>140</metric>
</interface>
</area>
<area>
<name>10.1.2.0</name>
<interface>
<name>ge-0/0/2.0</name>
<metric>100</metric>
</interface>
<interface>
<name>ge-0/0/3.0</name>
<metric>140</metric>
<dead-interval>120</dead-interval>
</interface>
</area>
</ospf>NETCONF also has mechanisms for controlling configuration datastores 🍓 Each datastore is a specific collection of configuration data, and it can be the source or the target of configuration operations. A device can tell you whether it has a distinct "startup" datastore, whether the current or "running" datastore is directly writable, or whether there's a "candidate" datastore. The candidate one is where you can make changes that won't affect the device until a "commit-configuration" operation gets invoked. ✨
NETCONF defines operations that the client (the application) invokes as RPCs on the server (running on the device). Here are some of the big ones 👑
| Operation | Description |
Okay, the table is kept exactly as the original shows it, so here it is:
+---------------+---------------------------------------------------+
| Operation | Description |
+---------------+---------------------------------------------------+
| commit | Commit the "candidate" configuration to "running" |
| copy-config | Copy one configuration datastore to another |
| delete-config | Delete a configuration datastore |
| edit-config | Change the contents of a configuration datastore |
| get-config | Retrieve all or part of a configuration datastore |
| lock | Prevent changes to a datastore from another party |
| unlock | Release a lock on a datastore |
+---------------+---------------------------------------------------+NETCONF's "capability" mechanism lets the device announce what it supports, including protocol operations, datastores, data models, and other abilities. These get announced during session establishment as part of the <hello> message. A client can look at the hello message to figure out what the device can do and how to talk to it to get the job done. main character energy 💖
NETCONF also defines a way to send asynchronous notifications from the server to the client, described in [RFC5277]. And NETCONF can fetch state data, receive notifications, and invoke extra RPC methods that are defined as part of a capability. For the full tea on NETCONF, check out [RFC4741] 🧚
2.1.1. NETCONF Transport Mappings 🦋
NETCONF can run over any transport protocol that meets the requirements defined in RFC 4741. That includes:
- connection-oriented operation
- authentication
- integrity
- confidentiality
[RFC4742] defines a mapping for the Secure Shell (SSH) [RFC4251] protocol, and SSH is the mandatory transport protocol 🔥 Others include SOAP [RFC4743], the Blocks Extensible Exchange Protocol (BEEP) [RFC4744], and Transport Layer Security (TLS) [RFC5539] 🫶
2.2. YANG 💜
YANG is a data modeling language for NETCONF. It lets you describe hierarchies of data nodes ("nodes") and the constraints that exist among them. YANG defines data models and how to manipulate those models with NETCONF protocol operations. ✨
Each YANG module defines a data model, uniquely identified by a namespace URI. These models are extensible, so standard data models and proprietary ones can integrate tightly. Models are built out of organizational containers, lists of data nodes, and leafs that form data nodes in the data tree 🌈
module example-ospf {
namespace "http://example.org/netconf/ospf";
prefix ospf;
import network-types { // Access another module's def'ns
prefix nett;
}
container ospf { // Declare the top-level tag
list area { // Declare a list of "area" nodes
key name; // The key "name" identifies list members
leaf name {
type nett:area-id;
}
list interface {
key name;
leaf name {
type nett:interface-name;
}
leaf priority {
description "Designated router priority";
type uint8; // The type is a constraint on
// valid values for "priority".
}
leaf metric {
type uint16 {
range 1..65535;
}
}
leaf dead-interval {
units seconds;
type uint16 {
range 1..65535;
}
}
}
}
}
}A YANG module defines a data model in terms of the data, how it's organized hierarchically, and the constraints on that data. YANG also defines how the data is represented in XML and how it gets used in NETCONF operations 🙈 Here's a quick look at some common YANG statements:
+--------------+----------------------------------------------------+
| Statement | Description |
+--------------+----------------------------------------------------+
| augment | Extends existing data hierarchies |
| choice | Defines mutually exclusive alternatives |
| container | Defines a layer of the data hierarchy |
| extension | Allows new statements to be added to YANG |
| feature | Indicates parts of the model that are optional |
| grouping | Groups data definitions into reusable sets |
| key | Defines the key leafs for lists |
| leaf | Defines a leaf node in the data hierarchy |
| leaf-list | A leaf node that can appear multiple times |
| list | A hierarchy that can appear multiple times |
| notification | Defines notification |
| rpc | Defines input and output parameters for an RPC |
| | operation |
| typedef | Defines a new type |
| uses | Incorporates the contents of a "grouping" |
+--------------+----------------------------------------------------+2.2.1. Constraints 🛡️
YANG lets the modeler add constraints to the data model so that impossible or illogical data gets blocked 🚫 These constraints tell clients what data the device is sending, and they also let the client learn as much as possible about what the device will accept, so the client can send correct data. These constraints apply to configuration data, but they can also be used for rpc and notification data 💅
The principal constraint is the "type" statement, which limits the contents of a leaf node to the named type. Here are some other common YANG constraints:
+--------------+----------------------------------------------------+
| Statement | Description |
+--------------+----------------------------------------------------+
| length | Limits the length of a string |
| mandatory | Requires the node appear |
| max-elements | Limits the number of instances in a list |
| min-elements | Limits the number of instances in a list |
| must | XPath expression must be true |
| pattern | Regular expression must be satisfied |
| range | Value must appear in range |
| reference | Value must appear elsewhere in the data |
| unique | Value must be unique within the data |
| when | Node is only present when XPath expression is true |
+--------------+----------------------------------------------------+The "must" and "when" statements use XPath [W3CXPATH] expressions to specify conditions that get semantically evaluated against the data hierarchy. But neither the client nor the server is required to implement the XPath specification. Instead, they can use any means to make sure these conditions are met 🧠
2.2.2. Flexibility 🦋
YANG uses the "union" type plus the "choice" and "feature" statements to give modelers flexibility when they define data models. The "union" type lets a single leaf accept multiple types, like an integer or the word "unbounded" 🌸
type union {
type int32;
type enumeration {
enum "unbounded";
}
}The "choice" statement lists a set of mutually exclusive nodes, so a valid configuration can pick any one node (or case). The "feature" statement lets the modeler mark parts of the model that can be optional, and it lets the device say whether it implements those optional portions ✨
The "deviation" statement lets the device indicate parts of a YANG module that it does not faithfully implement. Devices are encouraged to fully abide by the contract in the YANG module, but real-world situations can force a device to break that contract. Deviations give a way to declare this limitation, rather than leaving it to be discovered through run-time errors 🥺
2.2.3. Extensibility Model ✨
okay so XML has namespaces 🎀, which means elements from different sources can live in the same hierarchy without colliding. YANG modules define content for specific namespaces, but one module can augment another module's definition, slipping elements from its own namespace into the first module's hierarchy 💅
Since one module can augment another, hierarchies get to grow 🌱 as definitions from multiple sources get added onto the base hierarchy. These augmentations are qualified with the namespace of the source module, which helps avoid name conflicts as modules change over time. no cap, that's so smart 🧠
For example, if the above OSPF configuration were the standard, a vendor module could augment it with vendor-specific extensions 🦋
module vendorx-ospf {
namespace "http://vendorx.example.com/ospf";
prefix vendorx;
import example-ospf {
prefix ospf;
}
augment /ospf:ospf/ospf:area/ospf:interfaces {
leaf no-neighbor-down-notification {
type empty;
description "Don't inform other protocols about"
+ " neighbor down events";
}
}
}The <no-neighbor-down-notification> element then lives in the vendorx namespace 🧚
<ospf xmlns="http://example.org/netconf/ospf"
xmlns:vendorx="http://vendorx.example.com/ospf">
<area>
<name>0.0.0.0</name>
<interface>
<name>ge-0/0/0.0</name>
<priority>30</priority>
<vendorx:no-neighbor-down-notification/>
</interface>
</area>
</ospf>Augmentations are seamlessly integrated with base modules, so they can be fetched, archived, loaded, and deleted within their natural hierarchy 🫶. If a client application asks for the configuration for a specific OSPF area, it gets the sub-hierarchy for that area, complete with any augmented data. periodt ✨
2.3. YANG Translations 🌸
The YANG data modeling language is the central piece of a group of related technologies. The YANG language itself, described in [RFC6020], defines the syntax of the language and its statements, the meaning of those statements, and how to combine them to build the hierarchy of nodes that describe a data model.
That document also defines the "on the wire" XML content for NETCONF operations on data models defined in YANG modules. This includes the basic mapping between YANG data tree nodes and XML elements, as well as the mechanisms used in <edit-config> content to manipulate that data, such as arranging the order of nodes within a list.
YANG uses a syntax that is regular and easily described, and it's primarily designed for human readability. YANG's syntax is friendly to email, diff, patch, and the constraints of RFC formatting 💜
2.3.1. YIN 🧩
In some environments, bringing in a YANG parser may not be an acceptable option. For those scenarios, an XML grammar for YANG is defined as YIN (YANG Independent Notation). YIN lets you use XML parsers that are readily available in both open source and commercial versions. Conversion between YANG and YIN is direct, loss-less, and reversible. YANG statements are converted to XML elements, preserving the structure and content of YANG, but enabling the use of off-the-shelf XML parsers instead of requiring the integration of a YANG parser. YIN maintains complete semantic equivalence with YANG 👑
2.3.2. DSDL (RELAX NG) 🎀
Since NETCONF content is encoded in XML, it's only natural to use XML schema languages for validation. To make that easy, YANG offers a standardized mapping of YANG modules into Document Schema Definition Languages [RFC6110], of which RELAX NG is a major component 🌈
DSDL is considered to be the best choice as a standard schema language because it addresses not only grammar and datatypes of XML documents but also semantic constraints and rules for modifying the information set of the document. literally the whole package 😭
In addition, DSDL offers formal means for coordinating multiple independent schemas and specifying how to apply the schemas to the various parts of the document. This is super useful since YANG content is typically composed of multiple vocabularies 🍓
2.4. YANG Types 🔥
YANG supports a number of builtin types, and it allows additional types to be derived from those types in an extensible manner. New types can add additional restrictions to allowable data values.
A standard type library for use by YANG is available [RFC6021]. These YANG modules define commonly used data types for IETF-related standards. the library is giving organized 🗂️✨
2.5. IETF Guidelines 📝
A set of additional guidelines is defined that indicate desirable usage for authors and reviewers of Standards-Track specifications containing YANG data model modules [RFC6087]. These guidelines should be used as a basis for reviews of other YANG data model documents. bestie, this is your reading list for reviewing YANG stuff 🫶
3. Working with YANG 💖
3.1. Building NETCONF- and YANG-Based Solutions 🛠️
In the typical YANG-based solution, the client and server are driven by the content of YANG modules. The server includes the definitions of the modules as meta-data that is available to the NETCONF engine. This engine processes incoming requests, uses the meta-data to parse and verify the request, performs the requested operation, and returns the results to the client. the engine is doing the most, ngl 💅
+----------------------------+
|Server (device) |
| +--------------------+ |
| | configuration | |
+----+ | | ---------------| |
|YANG|+ | | m d state data | |
|mods||+ | | e a ---------------| |
+----+|| -----> | t t notifications | |
+----+| | | a a ---------------| |
+----+ | | operations | |
| +--------------------+ |
| ^ |
| | |
| v |
+------+ | +-------------+ |
| | -------------> | | |
|Client| <rpc> | | NETCONF | |
| (app)| | | engine | |
| | <------------ | | |
+------+ <rpc-reply> +-------------+ |
| / \ |
| / \ |
| / \ |
| +--------+ +---------+ |
| | config | |system |+ |
| | data- | |software ||+ |
| | base | |component||| |
| +--------+ +---------+|| |
| +---------+| |
| +---------+ |
+----------------------------+To use YANG, YANG modules must be defined to model the specific problem domain. These modules are then loaded, compiled, or coded into the server 🍓
The sequence of events for the typical client/server interaction may be as follows 🧠:
- A client application (
[C]) opens a NETCONF session to the server (device) ([S]) [C]and[S]exchange<hello>messages containing the list of capabilities supported by each side, allowing[C]to learn the modules supported by[S][C]builds and sends an operation defined in the YANG module, encoded in XML, within NETCONF's<rpc>element[S]receives and parses the<rpc>element[S]verifies the contents of the request against the data model defined in the YANG module[S]performs the requested operation, possibly changing the configuration datastore[S]builds the response, containing the response, any requested data, and any errors[S]sends the response, encoded in XML, within NETCONF's<rpc-reply>element[C]receives and parses the<rpc-reply>element[C]inspects the response and processes it as needed
Note that there is no requirement for the client or server to process the YANG modules in this way. The server may hard code the contents of the data model, rather than handling the content via a generic engine. Or the client may be targeted at the specific YANG model, rather than being driven generically. Such a client might be a simple shell script that stuffs arguments into an XML payload template and sends it to the server 🙈✨
3.2. Addressing Operator Requirements ✨
okay so NETCONF and YANG basically tackle a bunch of the problems that came up at the IAB NM workshop 💅 let's go through the list, bestie:
- Ease of use: YANG is built to be human friendly, simple, and readable 🌸 Plenty of tricky stuff is still hard because the problem domain is complicated, but YANG really tries to make those issues more visible and easier to handle 🫶
- Configuration and state data: YANG clearly splits configuration data from the other kinds of data 🎀
- Transactions: NETCONF gives you a simple transaction mechanism ✨
- Generation of deltas: a YANG module has enough info to generate the delta you need to get from one configuration data set to another 🧚
- Dump and restore: NETCONF lets you save and restore configuration data, and you can also do that for one specific YANG module 💾
- Network-wide configuration: NETCONF supports robust network-wide configuration transactions through the commit and confirmed-commit capabilities 👑 When a change hits multiple devices, these make failure scenarios way easier to manage, so transactions can dependably succeed or fail atomically 🔥
- Text-friendly: YANG modules are very text friendly, and so is the data they define 📝
- Configuration handling: NETCONF can tell the difference between distributing configuration data and activating it 🎯
- Task-oriented: a YANG module can define specific tasks as RPC operations. A client can either invoke the RPC operation or go straight to any of the underlying data 🦋
- Full coverage: YANG modules can be written to give full coverage of all the native abilities of a device. That access means you don't have to resort to the command line interface (CLI) and tools like Expect [SWEXPECT] 💅
- Timeliness: YANG modules can be tied to CLI operations, so all native operations and data are immediately available 🍓
- Implementation difficulty: YANG's flexibility makes modules that are easier to implement. Adding "features" and replacing "third normal form" with a natural data hierarchy should reduce complexity 🧠
- Simple data modeling language: YANG is powerful enough to be used in other situations too. In particular, an on-box API and a native CLI can be integrated to simplify the infrastructure 🌈
- Internationalization: YANG uses UTF-8 [RFC3629] encoded Unicode characters 🌍
- Event correlation: YANG brings together RPC operations, notifications, configuration, and state data, so internal references are possible 🔍 For example, a field in a notification can be tagged as pointing to a BGP peer, and the client application can easily find that peer in the configuration data 🫶
- Implementation costs: a lot of effort went into keeping implementation costs as low as possible 💸
- Human-friendly syntax: YANG's syntax is optimized for the reader, specifically the reviewer, because that's the most common human interaction 👀
- Post-processing: using XML maximizes the opportunities for post-processing data, possibly with XML-based technologies like XPath [W3CXPATH], XQuery [W3CXQUERY], and XSLT [W3CXSLT] 🧩
- Semantic mismatch: richer, more descriptive data models reduce the chance of semantic mismatch. With the ability to define new primitives, YANG modules get more specific, which allows more enforcement of rules and constraints 🎀
- Security: NETCONF runs over transport protocols secured by SSH or TLS, so you get secure communications and authentication using well-trusted tech 🔐 The secure transport can reuse existing key and credential management infrastructure, which cuts deployment costs 💰
- Reliable: NETCONF and YANG are solid, dependable technologies 💪 NETCONF is connection based and includes automatic recovery mechanisms when the connection is lost 🌸
- Delta friendly: YANG-based models support delta friendly operations. Add, change, insert, and delete operations are all well defined ➕
- Method-oriented: YANG lets you define new RPC operations, including an operation name, which is basically a method 🪄 The input and output parameters of those RPC operations are also defined in the YANG module 📦
3.3. Roles in Building Solutions 🎭
okay so building NETCONF- and YANG-based solutions means working with a bunch of different groups 🫶 Modelers have to figure out how to build useful models that give structure and meaning to data, while keeping it flexible enough to "future proof" their work. Reviewers need to quickly tell whether that structure is accurate. Device developers need to code that data model into their devices, and application developers need to code their apps to take advantage of it. There are lots of strategies for each piece of this work, and this section talks through some of them 🌈
3.3.1. Modeler 🧠
The modeler builds a data model using their deep knowledge of the domain being modeled 💖 The model should be as simple as possible, but it needs to balance complexity with expressiveness. The organization of the model should not only target the current needs, but also allow extensibility from other modules and adaptability to future changes ✨
Additional modeling issues are discussed in Section 4.
3.3.2. Reviewer 👀
The reviewer role is honestly one of the most important, and reviewers' time is precious ⏳ To help them out, YANG puts a lot of emphasis on readability, with a human-friendly syntax, a natural data hierarchy, and simple, concise statements 💅
3.3.3. Device Developer 🔧
The YANG model tells the device developer what data is being modeled 💜 The developer reads the YANG models and writes code that supports them. The model describes the data hierarchy and its associated constraints, and the description and reference material helps the developer figure out how to turn the model's view into the device's native implementation 🦋
3.3.3.1. Generic Content Support 🪄
A YANG model can be compiled into a YANG-based engine for either the client or the server side 🧚 Incoming data can be validated, and so can outgoing data. The complete configuration datastore may be validated against the constraints in the data model ✅
Serializers and de-serializers for generating and receiving NETCONF content can be driven by the meta-data in the model. As data comes in, the meta-data gets checked to make sure each incoming XML element is valid 🔍
3.3.3.2. XML Definitions 📜
The YANG module dictates the XML encoding for data sent via NETCONF 🎀 The encoding rules are fixed, so you can use the YANG module to check whether a specific NETCONF payload is following those rules 💖
3.3.4. Application Developer 📱
The YANG module tells the application developer what data can be modeled 🌸 Developers can look at the modules and take one of three distinct views 👑 We'll walk through those and how YANG affects their design. In the real world, most applications are a mix of these approaches 🫶
3.3.4.1. Hard Coded 🔒
An application can be coded against the specific, well-known contents of YANG modules, building in their organization, rules, and logic directly with explicit knowledge 🎯 For example, a script could change the domain name on a set of devices using a standard YANG module that includes that leaf node. The script takes the new domain name as an argument and inserts it into a string containing the rest of the XML encoding, as the YANG module requires. That content is then sent via NETCONF to each device 💌
This type of app is great for small, fixed problems, where the cost and complexity of flexibility are outweighed by how easy it is to hard code direct knowledge into the application 💅
3.3.4.2. Bottom Up 🪜
An application can take a generic, bottom-up approach to configuration. It focuses on the device's data directly and treats that data without any specific understanding 🧩
YANG modules can drive the operation of the YANG equivalent of a "MIB browser" 🔍 Such an application manipulates the device's configuration data based on the data organization in the YANG module. For example, a GUI can show a straightforward visualization where elements of the YANG hierarchy appear as a hierarchy of folders or GUI panels. Clicking a line expands it to show the contents of the matching XML hierarchy 📂
This type of GUI is pretty easy to build by generating XSLT stylesheets from the YANG data models 🎨 An XSLT engine can then turn configuration data into a set of web pages 🌐
The YANG modules let the application enforce a set of constraints without needing to understand the semantics of the YANG module 🛡️
3.3.4.3. Top Down ⬇️
Compared with the bottom-up approach, the top-down approach lets the application take a view of the configuration data that's separate from the standard and/or proprietary YANG modules 🌟 The application is free to build its own model for data organization and present that model to the user 💜 When the application needs to send data to a device, it transforms that data from the problem-oriented view of the world into the data that particular device needs 🦋 That transformation is under the control and maintenance of the application, so it can be changed and updated without affecting the device 🫶
For example, an application could model VPNs in a network-oriented view 🌐 The application would then have to transform these high-level VPN definitions into the configuration data handed to each particular device within a VPN 🧚
Even in this approach, YANG is useful, since it can be used to model the VPN itself 💅 For example, the following VPN straw-man models a list of VPNs, where each one has a protocol, a topology, a list of member interfaces, and a list of classifiers 🎀
list example-bgpvpn {
key name;
leaf name { ... }
leaf protocol {
type enumeration {
enum bgpvpn;
enum l2vpn;
}
}
leaf topology {
type enumeration {
enum hub-n-spoke;
enum mesh;
}
}
list members {
key "device interface";
leaf device { ... }
leaf interface { ... }
}
list classifiers {
...
}
}The application can use a YANG module like this to drive its operation. It builds VPN instances in a database, then pushes the configuration for those VPNs to individual devices. It can do that either with a standard device model (e.g., example-bgpvpn.yang), or by transforming that standard device content into some proprietary format for devices that don't support the standard 🎉
4. Modeling Considerations ✨
okay this section is for the modeler 🧠 It talks through the things you should keep in mind while developing models in YANG 💖
4.1. Default Values
okay so default values sound simple, right? 💅 but the details, how they're represented, and how they interact with configuration data can get messy fr 😭 NETCONF leaves default values as a data model issue, and YANG gives the device implementation flexibility in how it handles them 🎀 The requirement is that the device "MUST operationally behave as if the leaf was present in the data tree with the default value as its value". So the device gets to pick its own default-handling vibe ✨
One choice is to treat the configuration as a set of instructions for how the device should be configured. If a data value is given as part of those instructions and it happens to be the default value, then it stays in the configuration. But if it's not explicitly given, it's not considered part of the configuration 🌸
Another choice is to trim values that match the default values, so they get implicitly removed from the configuration datastore. Setting a leaf to its default value basically deletes that leaf 🧚
The device could also report all default values, whether or not they were explicitly set. This makes life way easier for a client that needs default values, but it can really bloat the size of the configuration data 💜
These choices reflect the default handling schemes of widely deployed networking devices, and supporting them lets YANG cut implementation and deployment costs for YANG-based models. Iconic behavior honestly 🦋
When a client retrieves data from the device, it has to be ready to handle leaf nodes that are absent when they hold the default value, since the server isn't required to send those leaf elements. This lets the device use either of the first two default handling schemes from above 🫶
No matter which implementation choice the device makes, it can support the "with-defaults" capability [RFC6243] and give the client the ability to select the handling of default values it wants 🍓
When evaluating the XPath expressions for constraints like "must" and "when", the evaluation context includes any appropriate default values. That means the modeler can count on consistent behavior from all devices, which is so satisfying 🙈✨
4.2. Compliance
ngl there are a lot of conflicting interests a data modeler has to juggle when building good models 🧠 Modelers need to be aware of five issues with models and devices:
- usefulness
- compliance
- flexibility
- extensibility
- deviations
For a model to be interesting, it has to be useful, solving a problem in a more direct or more powerful way than you could without the model. The model should maximize its usefulness within the problem domain 💅
Modelers should build models that maximize the number of devices that can faithfully implement the model. If the model is drawn too narrowly or makes too many assumptions about the device, the difficulty and cost of implementing it accurately will lead to low-quality implementations and interoperability issues, and the model loses value. Not it 💀
Modelers can use the "feature" statement to give the device some flexibility by partitioning the model, so the device can indicate which parts of the model it implements. For example, if the model includes a "logging" feature, a device with no storage facilities for the log can tell the client that it doesn't support that feature 🎀
Models can be extended via the "augment" statement, so the modeler should think about how the model is likely to be extended. These augmentations can be defined by vendors, applications, or standards bodies 🌈
Deviations are how devices indicate where their implementation isn't in full compliance with the model. For example, once a model is published, an implementer might decide to make a particular node configurable, even though the standard model describes it as state data. The implementation reports the value normally and may declare a deviation saying this device behaves differently than the standard. Applications that can discover the deviation can make allowances, but applications that don't discover it can keep treating the implementation as if it were compliant 🤷♀️
Rarely, implementations may make decisions that prevent compliance with the standard. Those moments are regrettable, but they're part of reality, and modelers and application writers ignore them at their own risk. An implementation that emits an integer leaf as "cow" would be painful to manage, but applications should expect to run into misbehaving devices in the field 😭
Even so, both client and server should view the YANG module as a contract, with both sides agreeing to abide by its terms. The modeler should be explicit about the terms of that contract, and both client and server implementations should strive to faithfully and accurately implement the data model described in the YANG module. Contract energy, babe 📜💖
4.3. Data Distinctions
the difference between configuration data, operational state data, and statistics is super important for data model writers and anyone planning to extend the NETCONF protocol 🦋 This section gives some background first, then definitions and a few examples ✨
4.3.1. Background
During the IAB NM workshop, operators formulated the following two requirements, as listed in [RFC3535]:
2. It is necessary to make a clear distinction between configuration data, data that describes operational state, and statistics. Some devices make it very hard to determine which parameters were administratively configured and which were obtained via other mechanisms such as routing protocols. 3. It is required to be able to fetch separately configuration data, operational state data, and statistics from devices, and to be able to compare these between devices.
The NETCONF protocol defined in RFC 4741 distinguishes two types of data, configuration data and state data 🌸
Configuration data is the set of writable data that is required to transform a system from its initial default state into its current state. State data is the additional data on a system that is not configuration data such as read-only status information and collected statistics.
NETCONF doesn't follow the distinction the operators asked for, between configuration data, operational state data, and statistical data. That's because it treats state data as including both statistics and operational state data 🙃
4.3.2. Definitions
Here are the definitions for configuration data, operational state data, and statistical data. They borrow from previous work 💅
- Configuration data is the set of writable data that is required to transform a system from its initial default state into its current state [RFC4741].
- Operational state data is a set of data that has been obtained by the system at runtime and influences the system's behavior similar to configuration data. Unlike configuration data, operational state is transient and modified by interactions with internal components or other systems via specialized protocols.
- Statistical data is the set of read-only data created by a system itself. It describes the performance of the system and its components.
These examples help clarify the difference between configuration data, operational state data, and statistical data 🧚
4.3.2.1. Example 1: IP Routing Table
IP routing tables can contain entries that are statically configured (configuration data) as well as entries obtained from routing protocols such as OSPF (operational state data). On top of that, a routing engine might collect statistics like how often a particular routing table entry has been used 🛣️
4.3.2.2. Example 2: Interfaces
Network interfaces usually come with a bunch of attributes that are specific to the interface type and, in some cases, specific to the cable plugged into an interface. Examples are the maximum transmission unit of an interface or the speed detected by an Ethernet interface 🔌
In many deployments, systems use the interface attributes detected when an interface is initialized. Because of that, these attributes constitute operational state. There are usually provisions to overwrite the discovered attributes with static configuration data, like configuring the interface MTU to use a specific value or forcing an Ethernet interface to run at a given speed 🎀
The system records statistics (counters) measuring the number of packets, bytes, and errors received and transmitted on each interface 📊
4.3.2.3. Example 3: Account Information
Systems usually maintain static configuration information about the accounts on the system. Systems can also obtain account information from other sources (e.g., Lightweight Directory Access Protocol (LDAP), Network Information Service (NIS)) dynamically, which leads to operational state data. Information about account usage is an example of statistical data 👤
Note that configuration data supplied to a system to create a new account might be supplemented with additional configuration information the system determines when the account is created, such as a unique account id. Even though the system might create that information, it usually becomes part of the static configuration of the system, since this data isn't transient 🔒
4.3.3. Implications
The primary focus of YANG is configuration data. There's no single mechanism defined for separating operational state data and statistics, since NETCONF treats them both as state data. This section describes several options for addressing this issue 🤔
4.3.3.1. Data Models
The first option is to have data models that explicitly differentiate between configuration data and operational state data. This leads to duplication of data structures and might not scale well from a modeling perspective 😬
For example, the configured duplex value and the operational duplex value would be distinct leafs in the data model 🦋
4.3.3.2. Additional Operations to Retrieve Operational State
The NETCONF protocol can be extended with new protocol operations that specifically allow retrieval of all operational state, e.g., by introducing a <get-ops> operation (and perhaps also a <get-stats> operation) 🧚♀️
4.3.3.3. Introduction of an Operational State Datastore
Another option is to introduce a new "configuration" data store that represents the operational state. A <get-config> operation on the <operational> data store would then return the operational state determining the behavior of the box, instead of its static and explicit configuration state 👑
4.4. Direction 🧭
okay so right now the ONLY viable solution is to model configuration and operational values as totally separate things 💅 The configuration leaf says what the desired value is, as the user gave it, and the operational leaf says what the current value is, as the device actually observes it 🔥
so in the duplex example you'd end up with two distinct leafs, duplex and op-duplex, one with config true and the other with config false ✨
sometimes distinct leafs are the move, but other times distinct lists are the way to go 🎀 distinct lists let the list be organized in different ways, with different constraints. keys, sorting, and constraint statements like must, unique, or when can all differ between configuration data and operational data 🦋
for example, configured static routes might be a distinct list from the operational routing table, since the use of keys and sorting might differ 🌸
5. Security Considerations 🔒
this document discusses an architecture for network management using NETCONF and YANG. it has no security impact on the Internet.
zero security impact on the Internet, periodt 🔒✨
6. References 📚
6.1. Normative References 💜
- [ISODSDL] International Organization for Standardization, "Document Schema Definition Languages (DSDL) - Part 1: Overview", ISO/IEC 19757-1, November 2004.
- [RFC3535] Schoenwaelder, J., "Overview of the 2002 IAB Network Management Workshop", RFC 3535, May 2003.
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.
- [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) Protocol Architecture", RFC 4251, January 2006.
- [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.
- [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event Notifications", RFC 5277, July 2008.
- [RFC5539] Badra, M., "NETCONF over Transport Layer Security (TLS)", RFC 5539, May 2009.
- [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, October 2010.
- [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, October 2010.
- [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG Data Model Documents", RFC 6087, January 2011.
- [RFC6110] Lhotka, L., "Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content", RFC 6110, February 2011.
- [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for NETCONF", RFC 6243, June 2011.
- [SWEXPECT] "The Expect Home Page",
<http://expect.sourceforge.net/>. - [W3CXPATH] DeRose, S. and J. Clark, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. - [W3CXQUERY] Boag, S., "XQuery 1.0: An XML Query Language", W3C WD WD-xquery-20050915, September 2005.
- [W3CXSD] Walmsley, P. and D. Fallside, "XML Schema Part 0: Primer Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-0-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-0-20041028>. - [W3CXSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide Web Consortium Recommendation REC-xslt-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xslt-19991116>.
6.2. Informative References 🌈
- [RCDML] Presuhn, R., Ed., "Requirements for a Configuration Data Modeling Language", Work in Progress, February 2008.
Author's Address 💌
Phil Shafer
Juniper Networks
EMail: phil@juniper.net📦 where this page comes from
- ietf: rfc6244 2011-06
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms