RFC 7921
An Architecture for the Interface to the Routing System
RFC 7921: An Architecture for the Interface to the Routing System 🎀
okay bestie, this one is from the IETF (the group that writes the rules for how the internet talks to itself) 💅 It's RFC 7921, an Informational doc (so it's published for info, not as a Standards Track spec 🧚). It came out in June 2016 and its ISSN is 2070-1721. The authors are A. Atlas (Juniper Networks), J. Halpern (Ericsson), S. Hares (Huawei), D. Ward (Cisco Systems), and T. Nadeau (Brocade). The header doesn't list any RFCs it obsoletes or updates, so it's standing on its own 🌸
Abstract ✨
This doc is about the IETF's plan for a standard, programmatic way to move state in and out of the internet routing system 🦋 It covers the high-level architecture, the building blocks that make it up, and how those blocks talk to each other, with extra focus on the parts being standardized as part of the Interface to the Routing System (I2RS) 💖
Status of This Memo
Not a standards track spec, just published for info 🧚
This is an IETF product, so it reflects the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG) 👑 Not every IESG-approved doc is eligible for any level of Internet Standard though, so check Section 2 of RFC 7841 if you're curious 🙈
For the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7921 🍓
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. ✨
This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they were on the publication date. Read them carefully, because they spell out your rights and restrictions for this doc 📜 Any Code Components pulled out of this doc have to include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as described in the Simplified BSD License 💜
Table of Contents 🌈
1. Introduction ....................................................4
1.1. Drivers for the I2RS Architecture ..........................5
1.2. Architectural Overview .....................................6
2. Terminology ....................................................11
3. Key Architectural Properties ...................................13
3.1. Simplicity ................................................13
3.2. Extensibility .............................................14
3.3. Model-Driven Programmatic Interfaces ......................14
4. Security Considerations ........................................15
4.1. Identity and Authentication ...............................17
4.2. Authorization .............................................18
4.3. Client Redundancy .........................................19
4.4. I2RS in Personal Devices ..................................19
5. Network Applications and I2RS Client ...........................19
5.1. Example Network Application: Topology Manager .............20
6. I2RS Agent Role and Functionality ..............................20
6.1. Relationship to Its Routing Element .......................20
6.2. I2RS State Storage ........................................21
6.2.1. I2RS Agent Failure .................................21
6.2.2. Starting and Ending ................................22
6.2.3. Reversion ..........................................23
6.3. Interactions with Local Configuration .....................23
6.3.1. Examples of Local Configuration vs. I2RS
Ephemeral Configuration ............................24
6.4. Routing Components and Associated I2RS Services ...........26
6.4.1. Routing and Label Information Bases ................28
6.4.2. IGPs, BGP, and Multicast Protocols .................28
6.4.3. MPLS ...............................................29
6.4.4. Policy and QoS Mechanisms ..........................29
6.4.5. Information Modeling, Device Variation, and
Information Relationships ..........................29
6.4.5.1. Managing Variation: Object
Classes/Types and Inheritance .............29
6.4.5.2. Managing Variation: Optionality ...........30
6.4.5.3. Managing Variation: Templating ............31
6.4.5.4. Object Relationships ......................31
6.4.5.4.1. Initialization .................31
6.4.5.4.2. Correlation Identification .....32
6.4.5.4.3. Object References ..............32
6.4.5.4.4. Active References ..............32
7. I2RS Client Agent Interface ....................................32
7.1. One Control and Data Exchange Protocol ....................32
7.2. Communication Channels ....................................33
7.3. Capability Negotiation ....................................33
7.4. Scope Policy Specifications ...............................34
7.5. Connectivity ..............................................34
7.6. Notifications .............................................35
7.7. Information Collection ....................................35
7.8. Multi-headed Control ......................................36
7.9. Transactions ..............................................36
8. Operational and Manageability Considerations ...................37
9. References .....................................................38
9.1. Normative References ......................................38
9.2. Informative References ....................................38
Acknowledgements ..................................................39
Authors' Addresses ................................................401. Introduction ✨
Routers that make up the internet's routing infrastructure keep state at lots of different layers and for lots of different jobs 🧚 A typical router keeps a Routing Information Base (RIB) and runs routing protocols like OSPF, IS-IS, and BGP so it can swap reachability info, topology info, protocol state, and other details about the network with other routers 🌐
Routers turn all of that info into forwarding entries, which then get used to forward packets and flows between network elements 💅 The forwarding plane and the forwarding entries it's been given hold active state, meaning they describe how the router is expected to behave and how it's actually behaving day to day, and network applications need that info too 🦋 Network-oriented apps need easy access to it so they can learn the network topology, check that programmed state actually got installed in the forwarding plane, measure how flows, routes, or forwarding entries behave, and understand both the configured state and the active state of the router 📊 They also need easy access to an interface that lets them program and control forwarding-related state 🎀
This doc lays out the architecture for one common, standards-based interface to all of that info 💖 The Interface to the Routing System (I2RS) makes it possible to control and observe routing-related state (like a Routing Element RIB manager's state), and it lets network-oriented apps get built on top of today's routed networks 🫶 I2RS is a programmatic, asynchronous interface for moving state into and out of the internet routing system ⭐ The architecture also recognizes that the routing system and a router's Operating System (OS) already have useful mechanisms that apps could use to hit their app-level goals 🔥 Those apps can use the I2RS programmatic interface to combine things in new ways: pulling internet routing data, analyzing it, and setting state inside routers 👑
What makes I2RS work is clear data models that define the meaning of the info that can be written and read 📚 I2RS gives apps a way to customize network behavior while still using the existing routing system however they like 🌸 It also gives apps (including controller apps) a framework to register and request the right info for each particular app 🧚
The I2RS architecture is general enough to handle info and data models for all kinds of data, and parts of the I2RS solution might be useful outside of routing 💜 Still, I2RS and this doc are specifically about an interface for routing data 🍓
Security matters for any new I2RS 🔒 Section 4 gives an overview of the security considerations for the I2RS architecture 🙈 The detailed requirements for I2RS protocol security are in [I2RS-PROT-SEC], and the detailed security requirements for the environment the I2RS protocol lives in are in [I2RS-ENV-SEC] 🛡️
1.1. Drivers for the I2RS Architecture 💅
Four key drivers shape the I2RS architecture, and they're the main reason it looks the way it does 🔥 Driver one is needing an interface that's programmatic and asynchronous and gives fast, interactive access for atomic operations ⚡ Driver two is access to structured info and state that usually can't be directly configured or isn't modeled in existing implementations or configuration protocols 🤯 Driver three is being able to subscribe to structured, filterable event notifications from the router 🔔 Driver four is that I2RS is meant to be data-model-driven, so it's extensible and comes with standard data models that network apps can use 📐
I2RS gets described as an asynchronous programmatic interface, and you can read about its key properties in Section 5 of [RFC7920] 📖
The I2RS architecture makes it easier to get info out of the router 👀 It doesn't just let you read specific info, it also lets you subscribe to targeted info streams, filtered events, and thresholded events 🦋
The architecture also makes it possible to inject ephemeral state into the routing system 💫 Ephemeral state is state on a router that doesn't survive a reboot of the routing device, or a reboot of the software handling I2RS on that device 🥹 A non-routing protocol or application can push state into a routing element through I2RS's state-insertion functionality, and that state can then get distributed through a routing or signaling protocol, be used locally (for example, to program the co-located forwarding plane), or both 🧚 The one hard limit here: I2RS will only allow changes to state that could also be changed through Local Configuration 🙅♀️ No direct messing with protocol-internal, dynamically determined data is planned 🙈✨
1.2. Architectural Overview 🏗️
Okay so, Figure 1 is the big-picture moodboard for I2RS 🦋. It shows the applications that use I2RS, their I2RS clients, and the I2RS agents. Apps get I2RS services through clients, and one client can serve one or more apps. The figure also shows the kinds of data models hanging around the routing system (dynamic configuration, static configuration, Local Configuration, and routing and signaling configuration) that the I2RS agent data models may access or augment 💅.
Figure 1 is giving cousin energy to Figure 1 in [RFC7920] 👯, but this one shows way more detail on how apps use clients to talk to agents. It also shows a logical view of the data models instead of a functional view (RIB, Forwarding Information Base (FIB), topology, policy, routing/signaling protocols, etc.) 🧠.
In Figure 1, Clients A and B each serve a single application (Applications A and B, respectively), while Client P is the multitasker serving multiple apps 🫶.
Apps can reach I2RS services through local or remote clients. A local client runs on the same physical box as the routing system. A remote client, on the other hand, runs across the network 🌐. In the figure, Applications A and B use local clients, while Applications C, D, and E use a remote client. How apps actually communicate with a remote client is out of scope for I2RS, so that's a not-our-problem situation 🙈.
An I2RS client can access one or more I2RS agents. In Figure 1, Clients B and P access I2RS agents 1 and 2. And the other way around, an I2RS agent can serve one or more clients. Here, agent 1 serves Clients A, B, and P, while Agent 2 serves only Clients B and P ✨.
I2RS agents and clients talk to each other asynchronously 📬. So a single client can post multiple simultaneous requests, either to one agent or to several. An agent can also work on multiple requests at once, whether they come from one client or from many. Main character multitasking 👑.
The I2RS agent gives read and write access to selected data on the routing element, and that data is organized into I2RS services. Section 4 explains how authentication and access control mediate that access 🔐. Figure 1 shows agents writing ephemeral static state (e.g., RIB entries) and reading from dynamic static (e.g., MPLS Label Switched Path Identifier (LSP-ID) or number of active BGP peers) 📊.
On top of read and write, the I2RS agent lets clients subscribe to different types of notifications about events that affect different object instances 🔔. One example, which is unrelated to an object creation, modification or deletion, is when a next hop in the RIB gets resolved in a way that lets a RIB manager use it to install the forwarding plane as part of a particular route. Please see Sections 7.6 and 7.7 for the details 🧚.
Basically, the scope of I2RS is defining the interactions between the I2RS agent and the I2RS client, plus the proper behavior of each one 🎀.
****************** ***************** *****************
* Application C * * Application D * * Application E *
****************** ***************** *****************
^ ^ ^
|--------------| | |--------------|
| | |
v v v
***************
* Client P *
***************
^ ^
| |-------------------------|
*********************** | *********************** |
* Application A * | * Application B * |
* * | * * |
* +----------------+ * | * +----------------+ * |
* | Client A | * | * | Client B | * |
* +----------------+ * | * +----------------+ * |
******* ^ ************* | ***** ^ ****** ^ ****** |
| | | | |
| |-------------| | | |-----|
| | -----------------------| | |
| | | | |
************ v * v * v ********* ***************** v * v ********
* +---------------------+ * * +---------------------+ *
* | Agent 1 | * * | Agent 2 | *
* +---------------------+ * * +---------------------+ *
* ^ ^ ^ ^ * * ^ ^ ^ ^ *
* | | | | * * | | | | *
* v | | v * * v | | v *
* +---------+ | | +--------+ * * +---------+ | | +--------+ *
* | Routing | | | | Local | * * | Routing | | | | Local | *
* | and | | | | Config | * * | and | | | | Config | *
* |Signaling| | | +--------+ * * |Signaling| | | +--------+ *
* +---------+ | | ^ * * +---------+ | | ^ *
* ^ | | | * * ^ | | | *
* | |----| | | * * | |----| | | *
* v | v v * * v | v v *
* +----------+ +------------+ * * +----------+ +------------+ *
* | Dynamic | | Static | * * | Dynamic | | Static | *
* | System | | System | * * | System | | System | *
* | State | | State | * * | State | | State | *
* +----------+ +------------+ * * +----------+ +------------+ *
* * * *
* Routing Element 1 * * Routing Element 2 *
******************************** ********************************
Figure 1: Architecture of I2RS Clients and AgentsRouting Element: A Routing Element implements some subset of the routing system. It does not need to have a forwarding plane associated with it. Examples of Routing Elements can include:
- A router with a forwarding plane and RIB Manager that runs IS-IS, OSPF, BGP, PIM, etc.,
- A BGP speaker acting as a Route Reflector,
- A Label Switching Router (LSR) that implements RSVP-TE, OSPF-TE, and the Path Computation Element (PCE) Communication Protocol (PCEP) and has a forwarding plane and associated RIB Manager, and
- A server that runs IS-IS, OSPF, and BGP and uses Forwarding and Control Element Separation (ForCES) to control a remote forwarding plane.
A Routing Element may be locally managed, whether via command-line interface (CLI), SNMP, or the Network Configuration Protocol (NETCONF) 🛠️.
Routing and Signaling: This block represents the portion of the Routing Element that implements part of the Internet routing system. It includes not merely standardized protocols (i.e., IS-IS, OSPF, BGP, PIM, RSVP-TE, LDP, etc.), but also the RIB Manager layer 🧩.
Local Configuration: The black box behavior for interactions between the ephemeral state that I2RS installs into the routing element. Local Configuration is defined by this document and the behaviors specified by the I2RS protocol 📦.
Dynamic System State: An I2RS agent needs access to state on a routing element beyond what is contained in the routing subsystem. Such state may include various counters, statistics, flow data, and local events. This is the subset of operational state that is needed by network applications based on I2RS that is not contained in the routing and signaling information. How this information is provided to the I2RS agent is out of scope, but the standardized information and data models for what is exposed are part of I2RS 📈.
Static System State: An I2RS agent needs access to static state on a routing element beyond what is contained in the routing subsystem. An example of such state is specifying queueing behavior for an interface or traffic. How the I2RS agent modifies or obtains this information is out of scope, but the standardized information and data models for what is exposed are part of I2RS 🚦.
I2RS agent: See the definition in Section 2.
Application: A network application that needs to observe the network or manipulate the network to achieve its service requirements 📱.
I2RS client: See the definition in Section 2.
As you can see in Figure 1, an I2RS client can communicate with multiple I2RS agents. Similarly, an I2RS agent may communicate with multiple I2RS clients, whether to respond to their requests, to send notifications, etc. Timely notifications are critical so that several simultaneously operating applications have up-to-date information on the state of the network ⏰.
As you can also see in Figure 1, an I2RS agent may communicate with multiple clients. Each client may send the agent a variety of write operations. To keep the protocol simple, two clients should not attempt to write (modify) the same piece of information on an I2RS agent. This is considered an error. However, such collisions may happen, and Section 7.8 ("Multi-headed Control") describes how the I2RS agent resolves collisions by first utilizing priority, and second by servicing the requests on a first-in, first-served basis 🚨. The I2RS architecture includes this definition of behavior for this case simply for predictability, not because this is an intended result. This predictability will simplify error handling and suppress oscillations. If additional error cases beyond this simple treatment are required, these error cases should be resolved by the network applications and management systems 🤝.
Two clients fighting over the same write is an error, so the rules here are a safety net, not a green light to collide 🙅♀️.
In contrast, although multiple I2RS clients may need to supply data into the same list (e.g., a prefix or filter list), this is not considered an error and must be correctly handled 📝. The nuances so that writers do not normally collide should be handled in the information models 💭.
The architectural goal for I2RS is that such errors produce predictable behaviors and can be reported to interested clients 📣. The details of the associated policy are discussed in Section 7.8. The same policy mechanism (simple priority per I2RS client) applies to interactions between the I2RS agent and the CLI/SNMP/NETCONF, as described in Section 6.3 🎯.
Finally, it must be noted that there may be indirect interactions between write operations. A basic example is when two different but overlapping prefixes are written with different forwarding behavior. Detection and avoidance of such interactions is outside the scope of the I2RS work and is left to agent design and implementation 🫠.
2. Terminology 🎀
Okay so before we go any further, we need to get the vocab down, bestie 💅 The following terminology is used in this document.
agent or I2RS agent: An I2RS agent provides the supported I2RS services from the local system's routing subsystems by interacting with the routing element to provide specified behavior. The I2RS agent understands the I2RS protocol and can be contacted by I2RS clients. 🤖
client or I2RS client: A client implements the I2RS protocol, uses it to communicate with I2RS agents, and uses the I2RS services to accomplish a task. It interacts with other elements of the policy, provisioning, and configuration system by means outside of the scope of the I2RS effort. It interacts with the I2RS agents to collect information from the routing and forwarding system. Based on the information and the policy-oriented interactions, the I2RS client may also interact with I2RS agents to modify the state of their associated routing systems to achieve operational goals. An I2RS client can be seen as the part of an application that uses and supports I2RS and could be a software library. 🧚
service or I2RS service: For the purposes of I2RS, a service refers to a set of related state access functions together with the policies that control their usage. The expectation is that a service will be represented by a data model. For instance, 'RIB service' could be an example of a service that gives access to state held in a device's RIB. 🌸
read scope: The read scope of an I2RS client within an I2RS agent is the set of information that the I2RS client is authorized to read within the I2RS agent. The read scope specifies the access restrictions to both see the existence of data and read the value of that data. 👀
notification scope: The notification scope is the set of events and associated information that the I2RS client can request be pushed by the I2RS agent. I2RS clients have the ability to register for specific events and information streams, but must be constrained by the access restrictions associated with their notification scope. 🔔
write scope: The write scope is the set of field values that the I2RS client is authorized to write (i.e., add, modify or delete). This access can restrict what data can be modified or created, and what specific value sets and ranges can be installed. ✍️
scope: When unspecified as either read scope, write scope, or notification scope, the term "scope" applies to the read scope, write scope, and notification scope. 💖
resources: A resource is an I2RS-specific use of memory, storage, or execution that a client may consume due to its I2RS operations. The amount of each such resource that a client may consume in the context of a particular agent may be constrained based upon the client's security role. An example of such a resource could include the number of notifications registered for. These are not protocol-specific resources or network-specific resources. 📦
role or security role: A security role specifies the scope, resources, priorities, etc., that a client or agent has. If an identity has multiple roles in the security system, the identity is permitted to perform any operations any of those roles permit. Multiple identities may use the same security role. 👑
identity: A client is associated with exactly one specific identity. State can be attributed to a particular identity. It is possible for multiple communication channels to use the same identity; in that case, the assumption is that the associated client is coordinating such communication. 🪪
identity and scope: A single identity can be associated with multiple roles. Each role has its own scope, and an identity associated with multiple roles can use the combined scope of all its roles. More formally, each identity has:
- a read scope that is the logical OR of the read scopes associated with its roles,
- a write scope that is the logical OR of the write scopes associated with its roles, and
- a notification scope that is the logical OR of the notification scopes associated with its roles.
secondary identity: An I2RS client may supply a secondary opaque identifier for a secondary identity that is not interpreted by the I2RS agent. An example of the use of the secondary opaque identifier is when the I2RS client is a go-between for multiple applications and it is necessary to track which application has requested a particular operation. 🕵️♀️
ephemeral data: Ephemeral data is data that does not persist across a reboot (software or hardware) or a power on/off condition. Ephemeral data can be configured data or data recorded from operations of the router. Ephemeral configuration data also has the property that a system cannot roll back to a previous ephemeral configuration state. 🫧
group: The NETCONF Access Control Model [RFC6536] uses the term "group" in terms of an administrative group that supports the well-established distinction between a root account and other types of less-privileged conceptual user accounts. "Group" still refers to a single identity (e.g., root) that is shared by a group of users. 🫶
routing system/subsystem: A routing system or subsystem is a set of software and/or hardware that determines where packets are forwarded. The I2RS agent is a component of a routing system. The term "packets" may be qualified to be layer 1 frames, layer 2 frames, or layer 3 packets. The phrase "Internet routing system" implies the packets that have IP as layer 3. A routing "subsystem" indicates that the routing software/hardware is only the subsystem of another larger system. 🗺️
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 📖
3. Key Architectural Properties 🏗️
Okay, the big architectural vibes! ✨ Several key architectural properties for the I2RS protocol are elucidated below (simplicity, extensibility, and model-driven programmatic interfaces). However, some architectural properties such as performance and scaling are not described below because they are discussed in [RFC7920] and because they may vary based on the particular use cases. 🦋
3.1. Simplicity
Making routing information visible and usable is literally iconic, and there have been many efforts over the years to improve access to the information available to the routing and forwarding system. Making such information visible and usable to network management and applications has many well-understood benefits. There are two related challenges in doing so. First, the quantity and diversity of information potentially available is very large. Second, the variation both in the structure of the data and in the kinds of operations required tends to introduce protocol complexity. 🌀
While the types of operations contemplated here are complex in their nature, it is critical that I2RS be easily deployable and robust. Adding complexity beyond what is needed to satisfy well known and understood requirements would hinder the ease of implementation, the robustness of the protocol, and the deployability of the protocol. Overly complex data models tend to ossify information sets by attempting to describe and close off every possible option, complicating extensibility. 🙈
Thus, one of the key aims for I2RS is to keep the protocol and modeling architecture simple. So for each architectural component or aspect, we ask ourselves, "Do we need this complexity, or is the behavior merely nice to have?" If we need the complexity, we should ask ourselves, "Is this the simplest way to provide this complexity in the I2RS external interface?" 🧠
3.2. Extensibility
Extensibility of the protocol and data model is very important. In particular, given the necessary scope limitations of the initial work, it is critical that the initial design include strong support for extensibility. 🌈
The scope of I2RS work is being designed in phases to provide deliverable and deployable results at every phase. Each phase will have a specific set of requirements, and the I2RS protocol and data models will progress toward these requirements. Therefore, it is clearly desirable for the I2RS data models to be easily and highly extensible to represent additional aspects of the network elements or network systems. It should be easy to integrate data models from I2RS with other data. This reinforces the criticality of designing the data models to be highly extensible, preferably in a regular and simple fashion. 🍓
The I2RS Working Group is defining operations for the I2RS protocol. It would be optimistic to assume that more and different ones may not be needed when the scope of I2RS increases. Thus, it is important to consider extensibility not only of the underlying services' data models, but also of the primitives and protocol operations. 🔮
3.3. Model-Driven Programmatic Interfaces
A critical component of I2RS is the standard information and data models with their associated semantics. While many components of the routing system are standardized, associated data models for them are not yet available. Instead, each router uses different information, different mechanisms, and different CLI, which makes a standard interface for use by applications extremely cumbersome to develop and maintain. Well-known data modeling languages exist and may be used for defining the data models for I2RS. 😭
There are several key benefits for I2RS in using model-driven architecture and protocol(s). First, it allows for data-model-focused processing of management data that provides modular implementation in I2RS clients and I2RS agents. The I2RS client only needs to implement the models the I2RS client is able to access. The I2RS agent only needs to implement the data models the I2RS agent supports. 🧩
Second, tools can automate checking and manipulating data; this is particularly valuable for both extensibility and for the ability to easily manipulate and check proprietary data models. 🛠️
The different services provided by I2RS can correspond to separate data models. An I2RS agent may indicate which data models are supported. 📚
The purpose of the data model is to provide a definition of the information regarding the routing system that can be used in operational networks. If routing information is being modeled for the first time, a logical information model may be standardized prior to creating the data model. 💜
4. Security Considerations 🔐✨
okay bestie, this part is SERIOUS 😭 because I2RS gives you real control over the network, so security is literally not optional 💅. this architecture describes interfaces that clearly need serious security thinking. the big idea is "reuse, don't reinvent" 🦋. I2RS was designed to borrow existing protocols that already carry network management info. for I2RS protocol version 1, two of those are NETCONF [RFC6241] and RESTCONF [RESTCONF]. more protocols might get reused in future versions 🌈.
The I2RS protocol design process goes like this: add extra requirements (security included) to the existing protocols so they can support the I2RS architecture 🛠️. once something like NETCONF or RESTCONF has been tweaked to fit I2RS, it gets reviewed to see if it actually meets those requirements. during that review, an in-depth security review of the revised protocol should be done 🔍. no skipping!
Because of the reuse strategy, this section lays out the assumed security environment for I2RS, with extra detail on a) identity and authentication, b) authorization, and c) client redundancy 💖. every protocol proposed as an I2RS protocol will need to be evaluated against its own security constraints. the detailed I2RS protocol requirements and the I2RS security environment will be defined inside these global security environments ✨.
The I2RS protocol security requirements for I2RS protocol version 1 are contained in [I2RS-PROT-SEC], and the global I2RS security environment requirements are contained in [I2RS-ENV-SEC] 📚.
First, here's a quick tour of the assumed security environment 🗺️. the I2RS agent on a Routing Element is a trusted part of that Routing Element 🏰. it might be part of a vendor-distributed signed software image for the whole Routing Element, or it might be a trusted signed app that an operator installed. the agent is assumed to have a separate authentication and authorization channel where it can validate both the identity and the permissions of an I2RS client 🔐. to keep interactions numerous and speedy ⚡, the agent is also assumed to be able to cache which I2RS clients are trusted and their authorized scope. that means the permission info may be old: in a pull model, until the agent re-requests it, or in a push model, until the authentication and authorization channel tells the agent about changes ⏳.
Mutual authentication between the I2RS client and agent is required 🤝. the client has to trust that the agent is attached to the relevant Routing Element, so write/modify operations get applied correctly and the info coming back from the agent can be trusted 💜.
An I2RS client is not automatically trustworthy 🚧. each client is tied to an identity with a set of scope limitations. apps using a client should be aware that those limits are based on its identity (see Section 4.1) and the role that identity has. a role sets specific authorization limits on what an I2RS client can successfully request from an agent (see Section 4.2) 🎭. for example, one client may only be able to read a static route table, while another may be able to add an ephemeral route to that static route table 🛣️.
If the I2RS client is a broker for multiple applications, managing the security, authentication, and authorization for that communication is out of scope 🙅. nothing stops the broker from using the I2RS protocol with a separate authentication and authorization channel. either way, a client acting as a broker is responsible for determining that the applications using it are trusted and permitted to make the particular requests 🫶.
Different levels of integrity, confidentiality, and replay protection matter for different parts of I2RS 🍓. the primary channel, the one used for client authentication and then for writing data, requires integrity, confidentiality and replay protection 🔒. picking a default required transport protocol is the preferred way to meet those needs ✨.
Other communications via I2RS may not need integrity, confidentiality, and replay protection 🌸. for instance, if a client subscribes to a stream of OSPF prefix announcements, those may need integrity but probably not confidentiality or replay protection. similarly, an interface statistics stream may not even need guaranteed delivery 📊. Section 7.2 covers more on multiple communication channels and how they're used. from the security perspective, it's critical to realize that an agent may open a NEW communication channel based on info provided by a client (as described in Section 7.2) 😱. for example, a client may request notifications of certain events, and the agent will open a channel to report them.
Heads up, bestie 🚨: to avoid an indirect attack, a request like that must be made in the context of an authenticated and authorized client whose communications cannot have been altered.
4.1. Identity and Authentication 🪪
As we covered above, all control exchanges between the I2RS client and agent should be authenticated and integrity-protected, so the contents can't be changed without detection 🕵️. manipulation of the system must be accurately attributable 📝. in an ideal architecture, even information collection and notification should be protected, though this may be subject to engineering trade-offs during the design ⚖️.
I2RS clients may be operating on behalf of other applications 🤹. those applications' identities aren't needed for authentication or authorization, but each application should have a unique opaque identifier that the client can hand to the agent. that way, operations can be tracked to an application identifier (and from there to the application's identity) 🏷️. this tracking supports I2RS functionality for tracing actions (to aid troubleshooting in routers) and logging network changes 🔎.
4.2. Authorization 👑
All operations using I2RS, both observation and manipulation, should be subject to appropriate authorization controls 🚦. that authorization is based on the identity and assigned role of the client performing the operations, plus the agent on the network element. multiple identities may use the same role(s). as noted in the definitions of "identity" and "role" above, if multiple roles are tied to one identity, that identity is authorized to perform any operation authorized by any of its roles 🎟️.
I2RS agents, when collecting info and manipulating things, act on behalf of the I2RS clients 🤖. so each operation's authorization is based on the lower of the two permissions: the agent's own and the authenticated client's. how this gets applied inside the device is outside the scope of I2RS 🙅.
The right level of granularity for scope can depend on the particular I2RS service and the implementation's granularity. a similar access control problem is handled by the NETCONF Access Control Model (NACM) [RFC6536], which lets you specify arbitrary access for a data node instance identifier while still defining meaningful manipulable defaults 🧩. the identity within NACM [RFC6536] can be a user name or a group user name (e.g., Root), and that name is linked to a scope policy contained in a set of access control rules. similarly, the I2RS identity is expected to link to one role that has a scope policy specified by a set of access control rules. that scope policy can come from Local Configuration, be exposed as an I2RS service for manipulation by authorized clients, or come from some other method (e.g., an Authentication, Authorization, and Accounting (AAA) service) 📜.
While the I2RS agent allows access based on the I2RS client's scope policy, this does not mean the access has to arrive on a particular transport connection or from a particular I2RS client, according to the I2RS architecture 🔌. the operator-applied scope policy may or may not restrict the transport connection or the identities that can access a local I2RS agent.
When an I2RS client is authenticated, its identity is provided to the I2RS agent, and that identity links to a role, which links to the scope policy 🔗. multiple identities may belong to the same role. for example, such a role might be an Internal-Routes-Monitor that allows reading the portion of the I2RS RIB associated with IP prefixes used for internal device addresses in the AS 👀.
4.3. Client Redundancy 👯
I2RS must support client redundancy 💪. at the simplest, this can be handled by having a primary and a backup network application that both use the same client identity and can successfully authenticate as it 🔁. since I2RS does not require a continuous transport connection and supports multiple transport sessions, this can provide some basic redundancy 🌟. however, it doesn't address the need for troubleshooting and logging of network changes, so you can tell which network application is actually active 🤷. at a minimum, basic transport information about each connection, and the time, can be logged with the identity 📋.
4.4. I2RS in Personal Devices 📱
If an I2RS agent or I2RS client is tightly correlated with a person (such as an I2RS agent running on someone's phone to control tethering), this usage can raise privacy issues, over and above the security issues that normally need handling in I2RS 😳. one example of an I2RS interaction that could raise privacy issues is one that makes it easier to track a person's phone location 📍. the I2RS protocol and data models should consider whether privacy issues can arise when clients or agents are used for such use cases 🫣.
5. Network Applications and I2RS Client 🎀
okay bestie, I2RS is expected to be used by network-oriented applications in different architectures 💅. The interface between a network-oriented application and the I2RS client is outside the scope of I2RS, but ngl, thinking through the different architectures is important if you want I2RS to be specified properly ✨.
In the simplest architecture of direct access, a network-oriented application has an I2RS client as a library or driver for communication with routing elements 🦋.
In the broker architecture, multiple network-oriented applications communicate in an unspecified fashion with a broker application that contains an I2RS client 🫶. That broker application needs extra functionality for authenticating and authorizing the network-oriented applications. That functionality is out of scope for I2RS, but similar considerations to those described in Section 4.2 do apply. As discussed in Section 4.1, the broker I2RS client should determine distinct opaque identifiers for each network-oriented application that is using it. The broker I2RS client can pass along the appropriate value as a secondary identifier, which can be used for tracking attribution of operations 🔥.
In a third architecture, a routing element or network-oriented application that uses an I2RS client to access services on a different routing element may also contain an I2RS agent, so it can provide services to other network-oriented applications 🌈. However, where the needed information and data models for those services differ from those of a conventional routing element, those models are, at least initially, out of scope for I2RS. The following section describes an example of such a network application 🧚.
5.1. Example Network Application: Topology Manager
A Topology Manager includes an I2RS client that uses the I2RS data models and protocol to collect information about the state of the network by communicating directly with one or more I2RS agents 👑. From these I2RS agents, the Topology Manager collects routing configuration and operational data, such as interface and Label Switched Path (LSP) information. On top of that, the Topology Manager may collect link-state data in several ways: via I2RS models, by peering with BGP-LS [RFC7752], or by listening into the IGP 💜.
The set of functionality and collected information that makes up the Topology Manager may be embedded as a component of a larger application, such as a path computation application 🍓. As a stand-alone application, the Topology Manager could be useful to other network applications by providing a coherent picture of the network state, accessible via another interface. That interface might use the same I2RS protocol and could provide a topology service using extensions to the I2RS data models ✨.
6. I2RS Agent Role and Functionality 🦋
The I2RS agent is part of a routing element. As such, it has relationships with that routing element as a whole and with various components of that routing element 💖.
6.1. Relationship to Its Routing Element
A Routing Element may be implemented with a wide variety of different architectures: an integrated router, a split architecture, a distributed architecture, etc. The architecture does not need to affect the general I2RS agent behavior 🌸.
For scalability and generality, the I2RS agent may be responsible for collecting and delivering large amounts of data from various parts of the routing element. Those parts may or may not actually be part of a single physical device. Thus, for scalability and robustness, it is important that the architecture allow for a distributed set of reporting components providing collected data from the I2RS agent back to the relevant I2RS clients. There may be multiple I2RS agents within the same router. In such a case, they must have non-overlapping sets of information that they manipulate 🙈.
To facilitate operations, deployment, and troubleshooting, it is important that traceability of the requests received by I2RS agent's and actions taken be supported via a common data model 🔍.
6.2. I2RS State Storage
State modification requests are sent to the I2RS agent in a routing element by I2RS clients. The I2RS agent is responsible for applying these changes to the system, subject to the authorization discussed above. The I2RS agent will retain knowledge of the changes it has applied, and of the client on whose behalf it applied them. The I2RS agent will also store active subscriptions. These sets of data form the I2RS datastore. This data is retained by the agent until the state is removed by the client, it is overridden by some other operation such as CLI, or the device reboots. Meaningful logging of the application and removal of changes is recommended. I2RS-applied changes to the routing element state will not be retained across routing element reboot. The I2RS datastore is not preserved across routing element reboots; thus, the I2RS agent will not attempt to reapply such changes after a reboot 💾.
6.2.1. I2RS Agent Failure
It is expected that an I2RS agent may fail independently of the associated routing element. This could happen because I2RS is disabled on the routing element, or because the I2RS agent (which may be a separate process or even running on a separate processor) experiences an unexpected failure. Just as routing state learned from a failed source is removed, the ephemeral I2RS state will usually be removed shortly after the failure is detected or as part of a graceful shutdown process. To handle these two types of failures, the I2RS agent MUST support two different notifications: a notification for the I2RS agent terminating gracefully, and a notification for the I2RS agent starting up after an unexpected failure. The two notifications are described below, followed by a description of their use in unexpected failures and graceful shutdowns 🚨.
NOTIFICATION_I2RS_AGENT_TERMINATING: This notification reports that the associated I2RS agent is shutting down gracefully and that I2RS ephemeral state will be removed. It can optionally include a timestamp indicating when the I2RS agent will shut down. Use of this timestamp assumes that time synchronization has been done, and the timestamp should not have granularity finer than one second, because better accuracy of shutdown time is not guaranteed ⏰.
NOTIFICATION_I2RS_AGENT_STARTING: This notification signals to the I2RS client(s) that the associated I2RS agent has started. It includes an agent-boot-count that indicates how many times the I2RS agent has restarted since the associated routing element restarted. The agent-boot-count allows an I2RS client to determine if the I2RS agent has restarted. (Note: This notification will be sent by the I2RS agent to I2RS clients that are known by the I2RS agent after a reboot. How the I2RS agent retains the knowledge of these I2RS clients is out of scope of this architecture.) 🌟
There are two different failure types that are possible, and each has different behavior 🧐.
Unexpected failure: In this case, the I2RS agent has unexpectedly crashed and thus cannot notify its clients of anything. Since I2RS does not require a persistent connection between the I2RS client and I2RS agent, it is necessary to have a mechanism for the I2RS agent to notify I2RS clients that had subscriptions or written ephemeral state. Such I2RS clients should be cached by the I2RS agent's system in persistent storage. When the I2RS agent starts, it should send a NOTIFICATION_I2RS_AGENT_STARTING to each cached I2RS client 😭.
Graceful shutdowns: In this case, the I2RS agent can do specific limited work as part of the process of being disabled. The I2RS agent must send a NOTIFICATION_I2RS_AGENT_TERMINATING to all its cached I2RS clients. If the I2RS agent restarts after a graceful termination, it will send a NOTIFICATION_I2RS_AGENT_STARTING to each cached I2RS client 🫶.
6.2.2. Starting and Ending
When an I2RS client applies changes via the I2RS protocol, those changes are applied and left in place until they are removed or the routing element reboots. The network application may make decisions about what to request via I2RS based upon a variety of conditions that imply different start times and stop times. That complexity is managed by the network application and is not handled by I2RS 🕰️.
6.2.3. Reversion
An I2RS agent may decide that some state should no longer be applied. An I2RS client may instruct an agent to remove state it has applied. In all such cases, the state will revert to what it would have been without the I2RS client-agent interaction. That state is generally whatever was specified via the CLI, NETCONF, SNMP, etc. I2RS agents will not store multiple alternative states, nor try to determine which one among such a plurality it should fall back to. Thus, the model followed is not like the RIB, where multiple routes are stored at different preferences. (For I2RS state in the presence of two I2RS clients, please see Sections 1.2 and 7.8.) 🔄
An I2RS client may register for notifications, subject to its notification scope, regarding state modification or removal by a particular I2RS client 🔔.
6.3. Interactions with Local Configuration ✨
Okay so changes can come from either Local Configuration or from I2RS 🧚. The stuff I2RS stores and changes is kept separate from the regular device config, BUT when the two clash they have to get resolved in a deterministic way that respects what the operator set up 💅. That deterministic result comes from general I2RS rules, system rules, the knobs the operator tweaks with policy, and the rules tied to the YANG data model (often the "MUST" and "WHEN" clauses for dependencies) 🎀.
The policy knobs decide whether Local Configuration beats a particular I2RS client's request, or the other way around. Usually most devices have an operator-applied policy that puts the I2RS client's ephemeral config changes first, so ephemeral data overrides Local Configuration 🔥.
There are lots of ways to build these knobs. One option is for the routing element to give Local Configuration a priority, and give the I2RS client's write of ephemeral config its own priority. The I2RS mechanism then compares the client's write priority against the one on Local Configuration to figure out who wins 👑.
Here's the default, and it's honestly so smart 🫶. The I2RS data modules have a general rule that, by default, Local Configuration always wins over I2RS ephemeral configuration. That way, the I2RS clients only get their way when the operator actually wants it.
The reason is that if there's no operator policy turning on ephemeral overwrites, then the overwrites should not occur. This lets I2RS agents get installed in routing systems and lets the communication get tested between I2RS clients and I2RS agents, all without the agent overwriting any config state 🙈. For more details, check the examples below.
When ephemeral state always wins for a data model, and there's an ephemeral state value, it gets installed instead of the Local Configuration value. The Local Configuration info still gets stored, so that if or when an I2RS client removes the ephemeral state, the Local Configuration state can be restored 💖.
When Local Configuration always wins, the subsystem and the I2RS agent still have to talk to each other. When an I2RS agent connects to the routing subsystem, it must also communicate with Local Configuration to exchange model information. That way the agent knows the details of each specific device config change it's allowed to modify. Also, when the system decides that a client's I2RS state is preempted, the I2RS agent must notify the affected I2RS clients. How the system figures that out is implementation dependent 🦋.
🚨 It is critical that policy based upon the source is used, because the resolution cannot be time based. If you just let the most recent state prevail, you could get race conditions where the final state is not repeatably deterministic. Nobody wants that chaos bestie 💀.
6.3.1. Examples of Local Configuration vs. I2RS Ephemeral Configuration 🎀
Examples make these architecture principles way easier to see 👀. Picture three routers: Router A, Router B, and Router C. These three routers must have two operator-applied policy knobs about ephemeral state.
- Policy Knob 1: Ephemeral configuration overwrites Local Configuration.
- Policy Knob 2: Update of Local Configuration value supersedes and overwrites the ephemeral configuration.
For Policy Knob 1, a router with an I2RS agent that gets a write for an ephemeral entry in a data model must consider the following:
- Does the operator policy allow the ephemeral configuration changes to have priority over existing Local Configuration?
- Does the YANG data model have any rules associated with the ephemeral configuration (such as the "MUST" or "WHEN" rule)?
For this example, there is no "MUST" or "WHEN" rule in the data being written.
The policy settings are:
Policy Knob 1 Policy Knob 2
=================== ==================
Router A ephemeral has ephemeral has
priority priority
Router B Local Configuration Local Configuration
has priority has priority
Router C ephemeral has Local Configuration
priority has priorityRouter A has the normal operator policy for both Policy Knob 1 and Policy Knob 2, which puts ephemeral configuration ahead of Local Configuration in the I2RS agent 🌸. An I2RS client sends a write to an ephemeral configuration value through the I2RS agent on Router A. The I2RS agent overwrites the configuration value in the intended configuration, then sends back an acknowledgement of the write. If the Local Configuration value changes later, Router A sticks with the ephemeral configuration the I2RS client wrote 🦋.
Router B's operator doesn't want ephemeral writes to overwrite Local Configuration, even though they installed an I2RS agent 🙅. Router B's policy puts Local Configuration ahead of the ephemeral write. When the I2RS agent on Router B gets a write from an I2RS client, it checks operator Policy Knob 1 and sends back a response telling the client that operator policy didn't allow overwriting Local Configuration.
The Router B case shows exactly why the I2RS architecture makes Local Configuration win by default. Since I2RS functionality is new, the operator must enable it. Otherwise, the I2RS ephemeral functionality stays off. That means Router B's operators can install the I2RS code and test the responses without ever turning on the I2RS overwrite function ✨.
Router C's operator sets Policy Knob 1 so I2RS clients can overwrite existing Local Configuration, and sets Policy Knob 2 so Local Configuration changes update ephemeral state. Why would an operator set the knobs this way? Router C is controlled by an operator with a back-end system that rewrites the Local Configuration of all systems at 11 p.m. every night 🌙. Any ephemeral change to the network is only supposed to last until 11 p.m., when the back-end system rolls out the next Local Configuration changes. The I2RS client writes the ephemeral state during the day, and the I2RS agent on Router C updates the value. At 11 p.m., the back-end configuration system updates the Local Configuration via NETCONF, and the I2RS agent gets notified that Local Configuration updated this value. The I2RS agent then tells the I2RS client that the value was overwritten by Local Configuration. In this use case, the I2RS client is part of an application that tracks every ephemeral state change, so all of them get included in the next configuration run 💅.
6.4. Routing Components and Associated I2RS Services 🧚
To keep things simple, each logical protocol or set of functionality that can be compactly described in a separable information and data model is treated as its own I2RS service 💜. A routing element doesn't need to implement every routing component described, or provide the matching I2RS services. I2RS services should include a capability model so that peers can figure out which parts of the service are supported. Each I2RS service requires an information model that describes at least the following: data that can be read, data that can be written, notifications that can be subscribed to, and the capability model mentioned above.
The initial services in the I2RS architecture are shown below 🌈.
*************************** ************** *****************
* I2RS Protocol * * * * Dynamic *
* * * Interfaces * * Data & *
* +--------+ +-------+ * * * * Statistics *
* | Client | | Agent | * ************** *****************
* +--------+ +-------+ *
* * ************** *************
*************************** * * * *
* Policy * * Base QoS *
******************** ******** * Templates * * Templates *
* +--------+ * * * * * *************
* BGP | BGP-LS | * * PIM * **************
* +--------+ * * *
******************** ******** ****************************
* MPLS +---------+ +-----+ *
********************************** * | RSVP-TE | | LDP | *
* IGPs +------+ +------+ * * +---------+ +-----+ *
* +--------+ | OSPF | |IS-IS | * * +--------+ *
* | Common | +------+ +------+ * * | Common | *
* +--------+ * * +--------+ *
********************************** ****************************
**************************************************************
* RIB Manager *
* +-------------------+ +---------------+ +------------+ *
* | Unicast/multicast | | Policy-Based | | RIB Policy | *
* | RIBs & LIBs | | Routing | | Controls | *
* | route instances | | (ACLs, etc) | +------------+ *
* +-------------------+ +---------------+ *
**************************************************************
Figure 2: Anticipated I2RS ServicesServices relate to each other in lots of ways 🔗. The RIB might need to refer to specific interfaces, services might want to refer to common complex types (for example links, nodes, or IP addresses), or they might need to refer to implementation-specific functionality (for example pre-defined templates applied to interfaces, or QoS behaviors that traffic gets directed into). Section 6.4.5 talks about the information modeling constructs and the range of relationship types that apply here 🦋.
6.4.1. Routing and Label Information Bases 🌸
Routing elements may keep one or more information bases 📚. Examples include Routing Information Bases, like IPv4/IPv6 Unicast or IPv4/IPv6 Multicast. Another example is the MPLS Label Information Bases, which can be per platform, per interface, or per context. This functionality gets exposed through an I2RS service, and it must interact smoothly with the same mechanisms the routing element already uses to handle RIB input from multiple sources. Conceptually, this can be done by having the I2RS agent talk to a RIB Manager as a separate routing source 🫶.
The point-to-multipoint state added to the RIB does not need to match well-known multicast protocol installed state. The I2RS agent can create arbitrary replication state in the RIB, subject to the advertised capabilities of the routing element 🍓.
6.4.2. IGPs, BGP, and Multicast Protocols ✨
okay so a separate I2RS service can expose each routing protocol on the device 🦋 and these services can do a bunch of different stuff, bestie 💅
- reading the various internal RIB(s) of the routing protocol is often helpful for understanding the state of the network 👀 but directly writing to these protocol-specific RIBs or databases is out of scope for I2RS 🙅♀️
- reading the various pieces of policy information the particular protocol instance is using to drive its operations 📖
- writing policy information such as interface attributes that are specific to the routing protocol or BGP policy that may indirectly manipulate attributes of routes carried in BGP 🎀
- writing routes or prefixes to be advertised via the protocol 📣
- joining/removing interfaces from the multicast trees 🌈
- subscribing to an information stream of route changes 💜
- receiving notifications about peers coming up or going down 🔔
for example, the interaction with OSPF might include modifying the local routing element's link metrics, announcing a locally attached prefix, or reading some of the OSPF link-state database 🧚 however, direct modification of the link-state database must not be allowed in order to preserve network state consistency 😭 that one is a hard no, bestie 🚫
6.4.3. MPLS 🌸
I2RS services are gonna be needed to expose the protocols that create transport LSPs (e.g., LDP and RSVP-TE) 🚀 as well as protocols (e.g., BGP, LDP) that provide MPLS-based services (e.g., pseudowires, L3VPNs, L2VPNs, etc) 💖 this should include all local information about LSPs originating in, transiting, or terminating in this Routing Element ✨ no skipping, periodt 💅
6.4.4. Policy and QoS Mechanisms 🍓
ngl, many network elements have separate policy and QoS mechanisms 🫶 including knobs that affect local path computation and queue control capabilities 🎛️ these capabilities vary widely across implementations, and I2RS cannot model the full range of information collection or manipulation of these attributes 😵💫 so a core set does need to be included in the I2RS information models and supported in the expected interfaces between the I2RS agent and the network element 💜 this gives you basic capabilities and the hooks for future extensibility ✨ main character energy for future-proofing 👑
by taking advantage of extensibility and subclassing, information models can specify use of a basic model that can be replaced by a more detailed model 🦋 literally so smart 🧠
6.4.5. Information Modeling, Device Variation, and Information Relationships 💅
okay this part is lowkey the core of it 🔥 I2RS depends heavily on information models of the relevant aspects of the Routing Elements to be manipulated 🌈 these models drive the data models and protocol operations for I2RS 💖 it is important that these information models deal well with a wide variety of actual implementations of Routing Elements, as seen between different products and different vendors 🏭 there are three ways that I2RS information models can address these variations: class or type inheritance, optional features, and templating 🎀
6.4.5.1. Managing Variation: Object Classes/Types and Inheritance 🧚
information modeled by I2RS from a Routing Element can be described in terms of classes or types or object 💜 different valid inheritance definitions can apply 🌸 what is appropriate for I2RS to use is not determined in this architecture 🤷♀️ for simplicity, "class" and "subclass" will be used as the example terminology ✨ this I2RS architecture does require the ability to address variation in Routing Elements by allowing information models to define parent or base classes and subclasses 🫶
the base or parent class defines the common aspects that all Routing Elements are expected to support 🍓 individual subclasses can represent variations and additional capabilities 🦋 when applicable, there may be several levels of refinement 🌈 the I2RS protocol can then provide mechanisms to allow an I2RS client to determine which classes a given I2RS agent has available 🔍 I2RS clients that only want basic capabilities can operate purely in terms of base or parent classes 🥰 while a client needing more details or features can work with the supported subclass(es) 💅
as part of I2RS information modeling, clear rules should be specified for how the parent class and subclass can relate 📏 for example, what changes can a subclass make to its parent? 🤔 the description of such rules should be done so that it can apply across data modeling tools until the I2RS data modeling language is selected 🛠️
6.4.5.2. Managing Variation: Optionality 🎀
I2RS information models must be clear about what aspects are optional 📋 for instance, must an instance of a class always contain a particular data field X? 🤨 if so, must the client provide a value for X when creating the object or is there a well-defined default value? 💭 from the Routing Element perspective, in the above example, each information model should provide information regarding the following questions:
- is X required for the data field to be accepted and applied? ✅
- if X is optional, then how does "X" as an optional portion of the data field interact with the required aspects of the data field? 🔗
- does the data field have defaults for the mandatory portion of the field and the optional portions of the field? 🧩
- is X required to be within a particular set of values (e.g., range, length of strings)? 📏
the information model needs to be clear about what read or write values are set by the client and what responses or actions are required by the agent 💌 it is important to indicate what is required or optional in client values and agent responses/actions 🫶
6.4.5.3. Managing Variation: Templating 🌷
a template is a collection of information to address a problem 🧩 it cuts across the notions of class and object instances 🔀 a template provides a set of defined values for a set of information fields and can specify a set of values that must be provided to complete the template 📝 further, a flexible template scheme may allow some of the defined values to be overwritten ✏️
for instance, assigning traffic to a particular service class might be done by specifying a template queueing with a parameter to indicate Gold, Silver, or Best Effort 🥇🥈🥉 the details of how that is carried out are not modeled 🙈 this does assume that the necessary templates are made available on the Routing Element via some mechanism other than I2RS 🗝️ the idea is that by providing suitable templates for tasks that need to be accomplished, with templates implemented differently for different kinds of Routing Elements, the client can easily interact with the Routing Element without concern for the variations that are handled by values included in the template 🥳
if implementation variation can be exposed in other ways, templates may not be needed 🤷♀️ however, templates themselves could be objects referenced in the protocol messages, with Routing Elements being configured with the proper templates to complete the operation 🧚 this is a topic for further discussion 💬
6.4.5.4. Object Relationships 💞
objects (in a Routing Element or otherwise) do not exist in isolation 🫂 they are related to each other 💕 one of the important things a class definition does is represent the relationships between instances of different classes 🏷️ these relationships can be very simple or quite complicated 🌀 the following sections list the information relationships that the information models need to support 📚
6.4.5.4.1. Initialization 🌱
the simplest relationship is that one object instance is initialized by copying another 📄 for example, one may have an object instance that represents the default setup for a tunnel, and all new tunnels have fields copied from there if they are not set as part of establishment 🚇 this is closely related to the templates discussed above, but not identical 👯 since the relationship is only momentary, it is often not formally represented in modeling but only captured in the semantic description of the default object 📝
6.4.5.4.2. Correlation Identification 🔗
often, it suffices to indicate in one object that it is related to a second object, without having a strong binding between the two 🤝 so an identifier is used to represent the relationship 🪪 this can be used to allow for late binding or a weak binding that does not even need to exist 🕸️ a policy name in an object might indicate that if a policy by that name exists, it is to be applied under some circumstance 📛 in modeling, this is often represented by the type of the value 🔤
6.4.5.4.3. Object References 📎
sometimes the relationship between objects is stronger 💪 a valid ARP entry has to point to the active interface over which it was derived 🎯 this is the classic meaning of an object reference in programming 💻 it can be used for relationships like containment or dependence 📦 this is usually represented by an explicit modeling link 🔗
6.4.5.4.4. Active References ⚡
there is an even stronger form of coupling between objects if changes in one of the two objects are always to be reflected in the state of the other 🪞 for example, if a tunnel has an MTU (maximum transmit unit), and link MTU changes need to immediately propagate to the tunnel MTU, then the tunnel is actively coupled to the link interface 🔌 this kind of active state coupling implies some sort of internal bookkeeping to ensure consistency, often conceptualized as a subscription model across objects 📬 this is the mic drop of the whole section, iykyk 🎤
7. I2RS Client Agent Interface 💌
7.1. One Control and Data Exchange Protocol 🌐
this I2RS architecture assumes a data-model-driven protocol where the data models are defined in YANG 1.1 [YANG1.1] and associated YANG based model documents [RFC6991], [RFC7223], [RFC7224], [RFC7277], [RFC7317] 📜 two of the protocols to be expanded to support the I2RS protocol are NETCONF [RFC6241] and RESTCONF [RESTCONF] 🧩 this helps meet the goal of simplicity and thereby enhances deployability 🚀 the I2RS protocol may need to use several underlying transports (TCP, SCTP (Stream Control Transport Protocol), DCCP (Datagram Congestion Control Protocol)), with suitable authentication and integrity-protection mechanisms 🔐 these different transports can support different types of communication (e.g., control, reading, notifications, and information collection) and different sets of data 🎁 whatever transport is used for the data exchange, it must also support suitable congestion-control mechanisms 🚦 the transports chosen should be operator and implementor friendly to ease adoption 🫶
each version of the I2RS protocol will specify the following:
- a) which transports may be used by the I2RS protocol 🚪
- b) which transports are mandatory to implement 💪
- c) which transports are optional to implement 🎈
7.2. Communication Channels 🦋
okay so bestie, we need multiple communication channels, and multiple types of them 💅. There can be a whole range of requirements (like confidentiality and reliability), and to scale, channels might start from several subcomponents of a routing element, and/or head to several parts of an I2RS client 🧚. Every single one of these channels uses the same higher-layer I2RS protocol, the one that combines secure transport and I2RS contextual information 💖. Any extra channels get coordinated between the I2RS client and the I2RS agent using this protocol 🫶.
I2RS protocol communication can be delivered in-band over the routing system's data plane 🌊. It might also come out-of-band over a management interface 🎀. Here's the tea 🫢: depending on which operations get requested, the I2RS protocol communication could make those in-band channels stop working 😭. That could leave the I2RS agent unreachable across that channel 💀.
7.3. Capability Negotiation 💫
The support for different protocol capabilities and I2RS services is gonna vary across I2RS clients and Routing Elements that run I2RS agents 🌸. Since every I2RS service is required to include a capability model (see Section 6.4), negotiation at the protocol level can be kept to protocol specifics and to which I2RS services are supported 🎀.
Capability negotiation, like which transports are supported beyond the minimum required to implement, is clearly going to be necessary 🔥. It's important that these negotiations stay simple and robust, because these mechanisms are so often a source of difficulty in implementation and deployment 😩.
Protocol capability negotiation can be split into two parts: the basic version negotiation (required to make sure basic communication works), and the more complex capability exchange that can happen within the base protocol mechanisms ✨. The more complex protocol and mechanism negotiation can be handled by defining information models for both the I2RS agent and the I2RS client 🧠. These information models can describe the various capability options 📋, and then be used to communicate important information about the agent and its capabilities 💜.
7.4. Scope Policy Specifications 👑
As Sections 4.1 and 4.2 describe, each I2RS client has a unique identity and may have a secondary identity (see Section 2) to help with troubleshooting 🕵️. As Section 4 indicates, all authentication and authorization mechanisms are based on the primary identity, and that identity links to a role with scope policy for reading data, writing data, and limiting the resources that can be consumed 🔐. The specifications for data scope policy (for read, write, or resources consumption) need to say which data the policy is controlling, plus the acceptable ranges of values for that data 🌈.
7.5. Connectivity 🔌
An I2RS client may or may not maintain an active communication channel with an I2RS agent 🫠. So an I2RS agent may need to open a communication channel to the client to deliver information that was requested earlier 📬. Not having an active channel does not mean the I2RS client is non-functional 🙅. When communication is required, the I2RS agent or the I2RS client can open a new communication channel 🙌.
State held by an I2RS agent that's owned by an I2RS client should not be removed or cleaned up just because the client is no longer communicating 🧹, even if the agent can't successfully open a new communication channel to the client 😤.
For many applications, it may be desirable to clean up state if a network application dies before removing the state it created 💀. Typically, this gets dealt with through network application redundancy 🔁. If stronger mechanisms are wanted, mechanisms outside of I2RS may let a supervisory network application monitor I2RS clients and, based on policy known to the supervisor, clean up state when applications die 👀. More complex mechanisms instantiated in the I2RS agent would add complications to the I2RS protocol, so they're left for future work 🚧.
Some examples of such a mechanism include the following 📝:
- Option one: the client could request state cleanup if a particular transport session is terminated.
- Option two: allow state expiration, expressed as a policy associated with the I2RS client's role. The state expiration could occur after there has been no successful communication channel to or from the I2RS client for the policy-specified duration ⏳.
7.6. Notifications 🔔
Like any policy system interacting with the network, the I2RS client needs to be able to receive notifications of changes in network state 💌. Notifications here refer to changes that are unanticipated, represent events outside the control of the systems (like interface failures on controlled devices), or are sufficiently sparse to be anomalous in some fashion 🚨. A notification may also be due to a regular event 📅.
Those events might be of interest to multiple I2RS clients controlling data handled by an I2RS agent, and to multiple other I2RS clients that are just collecting information without exerting control 👯. So the architecture requires that it be practical for I2RS clients to register for a range of notifications, and for I2RS agents to send notifications to a number of clients 📣. The I2RS client should be able to filter the specific notifications it receives 🎯. The specific types of events and filtering operations can vary by information model, and they need to be specified as part of the information model 🧩.
The I2RS information model needs to include representation of these events 🗂️. As discussed earlier, the capability information in the model lets I2RS clients understand which events a given I2RS agent is capable of generating 🧠.
For performance and scaling by the I2RS client, plus general information confidentiality, an I2RS client needs to be able to register for just the events it's interested in 🔒. It's also possible that I2RS might provide a stream of notifications via a publish/subscribe mechanism that doesn't really lend itself to the I2RS agent doing the filtering 🌊.
7.7. Information Collection 📊
One of the other important aspects of I2RS is that it's intended to simplify collecting information about the state of network elements 💅. This includes both getting a snapshot of a large amount of data about the current state of the network element, and subscribing to a feed of the ongoing changes to that set of data (or a subset of it) ✨. It's considered architecturally separate from notifications because of the differences in information rate and total volume 📈.
7.8. Multi-headed Control 🎭
As described earlier, an I2RS agent interacts with multiple I2RS clients who are actively controlling the network element 🤹. From an architecture and design perspective, the assumption is that, by means outside of this system, the data to be manipulated within the network element is appropriately partitioned so that any given piece of information is only being manipulated by a single I2RS client 🧩.
Nonetheless, unexpected interactions happen 😬, and two (or more) I2RS clients may attempt to manipulate the same piece of data 💥. That's considered an error case 🚫. This architecture doesn't try to determine what the right state of the data should be when such a collision happens 🤷. Instead, the architecture requires that there be decidable means by which I2RS agents handle collisions ⚖️. The way it ensures predictability is with a simple priority associated with each I2RS client, and the highest-priority change stays in effect 👑. In the case of priority ties, the first I2RS client whose attribution is associated with the data keeps control 🏆.
For this approach to multi-headed control to be useful for I2RS clients, an I2RS client needs to be able to register to receive notifications about changes made to writeable data whose state is of specific interest to it 🔔. This is included in the I2RS event mechanisms 🎟️. This also needs to apply to changes made by CLI/NETCONF/SNMP within the write scope of the I2RS agent, since the same priority mechanism (even if it's "CLI always wins") applies there 🖥️. The I2RS client can then respond to the situation however it sees fit 💖.
7.9. Transactions 🧾
In the interest of simplicity, the I2RS architecture doesn't include multi-message atomicity and rollback mechanisms 🙅♀️. Instead, it includes a small range of error handling for a set of operations included in a single message ✅. An I2RS client may indicate one of the following three methods of error handling for a given message with multiple operations that it sends to an I2RS agent 💫:
- Perform all or none: This traditional SNMP semantic means the I2RS agent keeps enough state while handling a single message to roll back the operations within that message 🔙. Either all the operations succeed, or none of them get applied, and an error message reports the single failure that caused them not to be applied 💔. This is useful when there are, for example, mutual dependencies across operations in the message 🤝.
- Perform until error: Here the operations in the message are applied in the specified order 🔢. When an error occurs, no further operations are applied, and an error is returned indicating the failure 🛑. This is useful if there are dependencies among the operations and they can be topologically sorted 🗺️.
- Perform all storing errors: Here the I2RS agent attempts to perform all the operations in the message and returns an error indication for each one that fails 📝. This is useful when there's no dependency across the operations, or when the I2RS client would prefer to sort out the effect of errors on its own 🫡.
In the interest of robustness and clarity of protocol state, the protocol will include an explicit reply to modification or write operations even when they fully succeed 🌈✨
8. Operational and Manageability Considerations ✨
okay bestie, let's talk about keeping this running smoothly 🧚 routing elements running I2RS agents should provide a way to show the I2RS state that's been actively provisioned, plus other internal agent info, so you can troubleshoot when things go sideways 🔍 but heads up: this stuff can be super sensitive 🙈 it's subject to the security considerations of whatever data models the agent implements, so it has to be protected under those rules. ngl the best move is a different privileged method rather than just connecting as an I2RS client to peek at the data 🔐 using a separate mechanism makes traceability and failure management way better 💖
manageability is a whole big deal for I2RS 🎀 here are some starter examples:
- Resource Limitations: apps can eat up resources 🍽️ like operations in a time frame, entries in the RIB, stored operations waiting to be triggered, and so on. being able to set resource limits based on authorization is a must-have 👑
- Configuration Interactions: state installed through I2RS and state from a router's configuration need a clearly defined relationship 🧩 per this architecture, a simple configured priority gives you enough policy flexibility, and that's the whole vibe 💅
- Traceability of Interactions: you need to be able to trace the requests the I2RS agent receives and the actions the agents take 🕵️♀️ so operators can monitor agents during deployment and troubleshoot software or network problems. it's giving detective era 🌸
- Notification Subscription Service: instead of the I2RS client constantly polling the agent, the client can subscribe to a notification stream the agent pushes out ✨ that's way more scalable for agent-client interactions. obsessed 😭
9. References 📚
9.1. Normative References
Here's the normative stuff, the must-read list 🫶 it has the key words spec and the problem statement for the interface to the routing system.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC7920] Atlas, A., Ed., Nadeau, T., Ed., and D. Ward, "Problem
Statement for the Interface to the Routing System",
RFC 7920, DOI 10.17487/RFC7920, June 2016,
<http://www.rfc-editor.org/info/rfc7920>.9.2. Informative References
And here's the informative list 🌈 these are the extra reads that give you the full picture, from the I2RS security drafts to the NETCONF, RESTCONF, and YANG family of docs. ngl some are still Work in Progress, so keep that in mind 💜
[I2RS-ENV-SEC]
Migault, D., Ed., Halpern, J., and S. Hares, "I2RS
Environment Security Requirements", Work in Progress,
draft-ietf-i2rs-security-environment-reqs-01, April 2016.
[I2RS-PROT-SEC]
Hares, S., Migault, D., and J. Halpern, "I2RS Security
Related Requirements", Work in Progress, draft-ietf-i2rs-
protocol-security-requirements-06, May 2016.
[RESTCONF] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", Work in Progress, draft-ietf-netconf-
restconf-14, June 2016.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
<http://www.rfc-editor.org/info/rfc6241>.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536,
DOI 10.17487/RFC6536, March 2012,
<http://www.rfc-editor.org/info/rfc6536>.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
RFC 6991, DOI 10.17487/RFC6991, July 2013,
<http://www.rfc-editor.org/info/rfc6991>.
[RFC7223] Bjorklund, M., "A YANG Data Model for Interface
Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
<http://www.rfc-editor.org/info/rfc7223>.
[RFC7224] Bjorklund, M., "IANA Interface Type YANG Module",
RFC 7224, DOI 10.17487/RFC7224, May 2014,
<http://www.rfc-editor.org/info/rfc7224>.
[RFC7277] Bjorklund, M., "A YANG Data Model for IP Management",
RFC 7277, DOI 10.17487/RFC7277, June 2014,
<http://www.rfc-editor.org/info/rfc7277>.
[RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for
System Management", RFC 7317, DOI 10.17487/RFC7317, August
2014, <http://www.rfc-editor.org/info/rfc7317>.
[RFC7752] Gredler, H., Ed., Medved, J., Previdi, S., Farrel, A., and
S. Ray, "North-Bound Distribution of Link-State and
Traffic Engineering (TE) Information Using BGP", RFC 7752,
DOI 10.17487/RFC7752, March 2016,
<http://www.rfc-editor.org/info/rfc7752>.
[YANG1.1] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
Work in Progress, draft-ietf-netmod-rfc6020bis-14, June
2016.Acknowledgements 🫶
okay, big shoutout time 💖 a lot of this doc grew out of two earlier works: "Interface to the Routing System Framework" (February 2013) and "A Policy Framework for the Interface to the Routing System" (February 2013) 🌸
the authors want to thank everyone below for their suggestions and review, and honestly the list is iconic 👑
The authors would like to thank Nitin Bahadur, Shane Amante, Ed
Crabbe, Ken Gray, Carlos Pignataro, Wes George, Ron Bonica, Joe
Clarke, Juergen Schoenwalder, Jeff Haas, Jamal Hadi Salim, Scott
Brim, Thomas Narten, Dean Bogdanovic, Tom Petch, Robert Raszuk,
Sriganesh Kini, John Mattsson, Nancy Cam-Winget, DaCheng Zhang, Qin
Wu, Ahmed Abro, Salman Asadullah, Eric Yu, Deborah Brungard, Russ
Housley, Russ White, Charlie Kaufman, Benoit Claise, Spencer Dawkins,
and Stephen Farrell for their suggestions and review.Authors' Addresses 🦋
and finally, meet the authors! 🎀 here's how to reach each of them.
Alia Atlas
Juniper Networks
10 Technology Park Drive
Westford, MA 01886
United States
Email: akatlas@juniper.net
Joel Halpern
Ericsson
Email: Joel.Halpern@ericsson.com
Susan Hares
Huawei
7453 Hickory Hill
Saline, MI 48176
United States
Phone: +1 734-604-0332
Email: shares@ndzh.com
Dave Ward
Cisco Systems
Tasman Drive
San Jose, CA 95134
United States
Email: wardd@cisco.com
Thomas D. Nadeau
Brocade
Email: tnadeau@lucidvision.comand that's a wrap on RFC 7921! 🌈💅✨
📦 where this page comes from
- ietf: rfc7921 2016-06
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms