idnits 2.17.00 (12 Aug 2021) /tmp/idnits55736/draft-rfernando-i2rs-protocol-requirements-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: API-5: The framework SHOULD define a set of base API methods for manipulating state. These SHOULD be generic and SHOULD not be service specific. -- The document date (October 20, 2013) is 3128 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC1776' is defined on line 940, but no explicit reference was found in the text == Unused Reference: 'RFC1925' is defined on line 943, but no explicit reference was found in the text == Outdated reference: draft-ietf-i2rs-architecture has been published as RFC 7921 == Outdated reference: draft-ietf-i2rs-problem-statement has been published as RFC 7920 Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Fernando 3 Internet-Draft J. Medved 4 Intended status: Standards Track Cisco Systems 5 Expires: April 23, 2014 E. Crabbe 6 Google 7 K. Patel 8 Cisco Systems 9 October 20, 2013 11 I2RS Protocol Requirements 12 draft-rfernando-i2rs-protocol-requirements-00 14 Abstract 16 The Interface to Routing System (I2RS) allows an application to 17 programmatically query and modify the state of the network. This 18 document defines requirements for an I2RS protocol between 19 applications (clients) and network elements (servers). 21 Requirements Language 23 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 24 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 25 document are to be interpreted as described in [RFC2119]. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on April 23, 2014. 44 Copyright Notice 46 Copyright (c) 2013 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 3. I2RS Protocol High Level Design Objectives . . . . . . . . . 5 64 4. I2RS Protocol Requirements . . . . . . . . . . . . . . . . . 7 65 4.1. General Assumptions . . . . . . . . . . . . . . . . . . . 7 66 4.2. Transport Requirements . . . . . . . . . . . . . . . . . 8 67 4.3. Identity Requirements . . . . . . . . . . . . . . . . . . 10 68 4.4. Message Encoding Requirements . . . . . . . . . . . . . . 11 69 4.5. Message Exchange Pattern Requirements . . . . . . . . . . 11 70 4.6. API Method Requirements . . . . . . . . . . . . . . . . . 13 71 4.7. Service and SDM Requirements . . . . . . . . . . . . . . 14 72 4.8. Security Requirements . . . . . . . . . . . . . . . . . . 16 73 4.9. Performance and Scale Requirements . . . . . . . . . . . 17 74 4.10. High Availability Requirements . . . . . . . . . . . . . 18 75 4.11. Application Programmability Requirements . . . . . . . . 19 76 4.12. Operational Requirements . . . . . . . . . . . . . . . . 19 77 5. Contributing Authors . . . . . . . . . . . . . . . . . . . . 20 78 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 79 6.1. Normative References . . . . . . . . . . . . . . . . . . 20 80 6.2. Informative References . . . . . . . . . . . . . . . . . 20 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 83 1. Introduction 84 I2RS defines a standard, programmatic interface for state transfer in 85 and out of the Internet's routing system. I2RS is intended to 86 automate network operations - it will allow applications to quickly 87 interact with routing systems and to implement more complex 88 operations, such as policy-based controls. 89 [I-D.ietf-i2rs-problem-statement] gives detailed problem statement 90 for I2RS, while [I-D.ietf-i2rs-architecture] defines its high-level 91 architecture. 93 This document expands on the required aspects of a protocol for I2RS, 94 described in Section 5 of [I-D.ietf-i2rs-problem-statement], and 95 refines I2RS protocol requirements formulated in Section 6 of 96 [I-D.ietf-i2rs-architecture]. The purpose of this document is as 97 follows: 99 1. To help stakeholders (equipment vendors, operators, application 100 programmers or interested IETF participants), to arrive at a 101 common understanding of the critical characteristics of the I2RS 102 protocol(s). 104 2. To provide requirements to designers of the I2RS framework and 105 protocols on aspects of the framework that warrant significant 106 consideration during the design process. 108 3. To allow the stakeholders to evaluate technology choices that are 109 suitable for I2RS, to identify gaps in these technologies and to 110 help evolve them to suite I2RS's needs. 112 2. Terminology 114 This document uses the following terminology definitions. 116 Service: For the purposes of I2RS, a service refers to a set of 117 related state access functions together with the policies that 118 control it's usage. For example, the 'RIB service' is a service 119 that provides access to state held in a device's RIB. 121 Server: Is a system that implements one or more services that can be 122 accessed by client systems via well defined interfaces (APIs). A 123 server can export multiple services. A server is typically a 124 network device. [ed: as an aside, I still find this usage to be 125 completely counterintuitive] 127 Client: A system that uses a service implemented by a server through 128 a well defined interface. A client can make use of multiple 129 services from multiple servers. 131 Participants: The server and client are collectively referred to as 132 the participants of a service. 134 Transport: Any end-to-end mode of communication between a server and 135 a client that allows exchange data the exchange of data. In 136 principle, the transport hides the topology and other network 137 properties from the participants of a service. 139 Messages: Messages are logical units of data that are exchanged 140 between service participants. 142 Message Exchange Pattern: A categorization of a way in which 143 messages could be exchanged between service participants. MEPs 144 specify the sequence, order, direction and cardinality of messages 145 exchanged. Request-response and asynchronous notifications are 146 examples of MEPs. 148 Message Data Model: The schema representing the structure of 149 messages being exchanged between the service participants. The 150 MDMs can specify certain constraints such as data type, length, 151 format and valid values of fields in messages. 153 Message Encoding: The "wire" representation of messages exchanged 154 between service participants. 156 API Method: Is an application level procedure or a function that is 157 invoked by the client to query or modify the state held in the 158 server. 160 Service Scope: Is the functional scope of a service. The service 161 scope is established during the service definition phase. 162 [definition needs work] 164 Service Data Model: The schema representing the conceptual structure 165 of the state held in the server for a given service. The SDMs can 166 specify certain constraints such as the data type, length, format 167 and allowed values for fields representing the state. They also 168 describe the relationship between various state elements that 169 constitute the state. 171 Modeling Language: A language that defines schema for Message Data 172 Models and Service Data Models. 174 Namespaces: A method for uniquely identifying and scoping of schemas 175 declared for messages and services. Namespace is an important 176 consideration when defining services and messages. 178 Service State or State: Is the general data held by the server for a 179 given service. 181 State Element: A readable or writable state present in the server. 182 The term 'State Element' may refer to states at different levels 183 of granularity. 185 State Identifier: A unique identity for the state element. The 186 identifier is derived from the SDM and uses the same naming 187 convention as the SDM. State Identifiers may be viewed as the 188 'key' for the state. 190 State Value or 'value': A value that is assigned to a particular 191 state identifier (key). The state is referred to using the State 192 Identifier or 'key' in operations that sets or transfers the value 193 of the state. 195 State Owner: Identity of the client that was the source of a state 196 held in the server. 198 State lifetime: The duration which the state is maintained in the 199 server. 201 Datastore: The physical mechanism used to store a service's state. 203 Capabilities: Capabilities represents the functionality supported 204 by a server including the services supported and exported to 205 clients. 207 Authentication: A mechanism that allows a server to recognize the 208 identity of a client. 210 Authorization: A mechanism that allows determination of what an 211 authenticated client is allowed to do. 213 Confidentiality: Specifies if data remains confidential while in 214 transit between service participants. 216 Policy: For the purposes of this document, a policy is an explicit 217 user configurable modification to the default behavior of the 218 system. The enforcement could be conditional; a given policy 219 could potentially become active only when certain conditions are 220 met. 222 3. I2RS Protocol High Level Design Objectives 224 The core guiding principles and objectives that should be used in 225 defining the specifics of the I2RS protocol(s) are as follows: 227 HLO-1. Design for Scale and Performance: is a key criteria for 228 making design choices. The design should meet current and future 229 performance and scale needs. Design patterns that allow us to 230 compose a scalable, high performing system are well understood and 231 should be utilized where possible. 233 HLO-2. Extensible: I2RS will be deployed in environments that will 234 evolve over time. Hence the system should be designed with 235 provisions that will allow significant modifications/extensions to 236 be added to existing mechanisms. An extensible and future-proof 237 design will drive better adoption as it is a promise against 238 future technology churn. 240 HLO-3. Promote Reuse: Reuse in this context refers to using existing 241 tools, technologies and mechanisms instead of inventing them from 242 scratch. It also refers to reusing a network device's current set 243 of capabilities that applications could harness without 244 reinventing them from scratch. 246 HLO-4. Promote Portability: Portability refers to the ease with 247 which software written for one device or environment can be moved 248 to work seamlessly with another device or environment to achieve 249 similar functionality. A fundamental requirement for I2RS is to 250 achieve predictive and consistent behavior when applications are 251 migrated from one platform or environment to another. 253 HLO-5. Security: I2RS may be deployed in environments where it might 254 be subjected to threats and denial-of-service attacks that might 255 cause intentional damage to the functioning of a network. This 256 could be in the form of loss of service, degradation of 257 performance, loss of confidentiality, etc. Therefore, the I2RS 258 protocol must provide basic security mechanisms including but not 259 limited to authentication, authorization, confidentiality along 260 with sufficiently expressive policy requirements for each. 262 HLO-6. Separation of concerns: The components of the system should 263 be decoupled from each other as much as possible to achieve clear 264 separation of concerns. This modularity would allow for 265 interchangeable design and implementation choices that address the 266 individual components requirements. 268 HLO-7. Robustness: Robustness is the ability of a system to operate 269 in the face of failures and errors. It is also its ability to 270 correctly and predictably recover from such errors and to settle 271 to a known state. Since applications that use the I2RS framework 272 are remote and would be controlling the entire network, ensuring 273 fault tolerance is an important consideration. 275 Most of these requirements cut across all the components of the 276 system and hence should be kept in mind while designing each 277 component and the system as a whole. 279 4. I2RS Protocol Requirements 281 This section is divided into multiple sub-sections, each dealing with 282 a specific consideration of I2RS protocol design. As we list the 283 requirements under each subsection, we'll annotate each requirement 284 with what high level objectives they meet. Additional reasoning is 285 additionally provided where appropriate. 287 4.1. General Assumptions 289 This section captures the general, high level assumptions of the I2RS 290 framework. The context for defining protocol requirements is shown 291 in the following figure. 293 +--------+ +--------+ +--------+ 294 | Client | ... | Client | .... .... | Client | 295 +--------+ +--------+ +--------+ 296 ^ ^ ^ 297 | | | 298 | | | 299 | | | 300 | | | 301 | | | 302 | | I2RS | 303 | +----+-------------+ | 304 | | | | 305 | I2RS | | I2RS | 306 +-----------|--------------+ | +-------+ 307 | | | | | 308 V V V V V 309 +-----------+ +-----------+ 310 | Server | | Server | 311 +-----------+ +-----------+ 313 Figure 1: Protocol requirements context 315 Since the design choices for the I2RS framework are many, some 316 simplifying assumptions could make the framework requirements more 317 tangible and useful. 319 GEN-1: Programmatic access to the state held in a network device is 320 provided to an application by exposing a set of API's from the 321 device to the application. Due to this characteristic, I2RS is a 322 client-server protocol/framework. I2RS must provide mechanisms 323 for the client to discover services that a server provides. 325 GEN-2: The client can use the APIs provided by the server to 326 programmatically add, modify, delete and query state held in the 327 server. Additionally clients can register for certain events and 328 be notified when those events occur. 330 GEN-3: The client and the server communicate using a simple 331 transport connection. The client initiates the transport 332 connection to the server. The server does not know the number and 333 timing of the connections from its clients. 335 GEN-4: A service provides access to the state held in the server 336 structured according to the SDM of that service. A service allows 337 a client the ability to manipulate the service state. 339 GEN-5: The I2RS MUST define a data model to describe the SDMs 340 supported in the server and MUST define a data modeling language 341 to formally describe that data model. I2RS MUST specify the 342 mapping from the service data model to the message data model and 343 subsequently to the client API. 345 4.2. Transport Requirements 347 The transport layer provides connectivity between the client and the 348 server. This section details the transport requirements. 350 TR-1: There should exist a default transport connection between the 351 client and the server for communication. This control connection 352 is point-to-point and should provide in-order and reliable 353 delivery of data in both directions. The simplest I2RS setup 354 would only have a single transport session between the 355 participants. 357 TR-2: Depending on the data being exchanged, there may be 358 additional transport connections between the client and server 359 defined in future. The characteristics of these additional 360 transport connections will be dictated by the requirements that 361 create them. 363 TR-3: The transport connection between the client and server MUST 364 have mechanisms to support authentication, authorization and to 365 optionally provide confidentiality of data exchanged between the 366 client and the server. See Section 4.8 for more details. 368 TR-4: A client could connect to multiple servers. Similarly, a 369 server could accept connections from multiple clients. Any 370 participant may initiate the transport connection. 372 TR-5: The exact technology used for the transport layer should be 373 replaceable. There should be a single mandatory transport that 374 must be supported by all participants. This requirement will 375 ensure that there is always an interoperable transport mechanism 376 between any client and any server. 378 TR-6: Clients and servers by default communicate using a point-to- 379 point transport connection. 381 TR-7: Point-to-multipoint transports are mainly used to scale the 382 system by avoiding ingress replication when the same message has 383 to be delivered to multiple receivers. P2MP transport would work 384 hand-in-hand with a P2MP MEP. The subject of P2MP transport and 385 P2MP MEP is for future work. 387 TR-8: Once the transport connection is established, it is desirable 388 to reuse it to perform multiple operations. This requirement 389 ensures that the system scales by amortizing the session setup 390 cost across multiple operations. Session down events may not have 391 an impact on the state maintained by the server. 393 TR-9: After the transport is established, the participants exchange 394 capabilities and other session parameters before exchanging 395 service related messages. 397 TR-10: Messages pertaining to multiple services could be exchanged 398 over a single transport connection. 400 TR-11: The "default" transport connection between a client and a 401 server is purely for control plane message exchanges. Data plane 402 packets are not expected to be sent over this "default" 403 connection. When required, packets to be extracted from or 404 injected to the data plane could be designed as a service in 405 itself that sets up a separate packet injection/extraction channel 406 that provides the correct characteristics. 408 TR-12: For operational reasons, a participant MUST be able to detect 409 a transport connection failure. To satisfy this requirement, 410 transport level keep-alives could be used. If the underlying 411 transport connection does not provide a keep-alive mechanism, it 412 should be provided at the I2RS protocol level. For example, if 413 TCP is used as a transport, TCP keep-alives could be used to 414 detect transport session failures. 416 4.3. Identity Requirements 418 I2RS could be used in a multi-domain distributed environment. 419 Therefore a fool-proof way to ascertain the identity of clients is of 420 utmost importance. Identity provides authenticated access to clients 421 to state held by the server. 423 ID-1: Each client should have a unique identity that can be verified 424 by the server. The authentication could be direct or through an 425 identity broker. 427 ID-2: The server should use the client's identity to track state 428 provided by the client. State ownership enables multiple clients 429 to edit their shared state. This is useful for troubleshooting 430 and during client death or disconnection when the client's state 431 may have to be purged or delegated to another client that shares 432 the same identity. 434 ID-3: The client's I2RS identity should be independent of the 435 location or the network address of the physical node in which it 436 is hosted. This allows the client to move between physical nodes. 437 It also allows a standby client to take over when the primary 438 fails and allows shared state editing by multiple clients as 439 discussed in I.2. 441 ID-4: A client that reboots or reconnects after a disconnection MUST 442 have the same I2RS identity if it wishes to continue to operate on 443 the state that it previously injected. 445 ID-5: A clients ability to operate on a state held by the server is 446 expressed at the granularity of a service. A service could be 447 read-only or read-write by a client possessing a particular 448 identity. 450 ID-6: A policy on the server could dictate the services that could 451 be exposed to clients. Upon identity verification, the authorized 452 services are exported to the client by capability announcement. 454 ID-7: A client can edit (write, delete) only the state that was 455 injected by it or other clients with the same shared identity. 456 Therefore, two conditions must be met for a client to edit a state 457 through a session. First, the client should receive capability 458 from the server that it has 'edit' permissions for the service in 459 question, and, secondly, the state that it edits should be its own 460 state. 462 ID-8: The server retains the client's identity till all of that 463 client's state is purged from the server. 465 4.4. Message Encoding Requirements 467 Clients and servers communicate by exchanging messages between them. 468 Message encoding is the process of converting information content in 469 a message to a form that can be transferred between them. 471 ME-1: Every message between the client and the server is encoded in 472 a transport-independent frame format. 474 ME-2: Each message is serialized on the sender's side and de- 475 serialized on the receiver's side. The technology used for 476 encoding and decoding messages could be negotiated between the 477 client and the server. 479 ME-3: A mandatory default encoding standard should be specified and 480 implemented by all I2RS participants. This ensures that there is 481 an interoperable default encoding mechanism between any client and 482 any server. 484 ME-4: The mandatory encoding technology chosen should be well 485 supported by a developer community and should be standards based. 486 Availability of tools and language bindings should be one of the 487 criteria used in selecting the mandatory encoding technology. 489 ME-5: If multiple message encoding is supported in the framework, 490 the encoding used for the current session should be configured 491 using a policy on the server side and negotiated using 492 capabilities. Note that currently there is no requirement to 493 support multiple encoding schemes. 495 ME-6: The message encoding standard should be language and platform 496 neutral. It should provide tools to express individual fields in 497 a message in a platform independent IDL-based language. 499 ME-7: The encoding/decoding mechanism should be fast and efficient. 500 It should allow for operation on legacy equipment. 502 ME-8: The encoding scheme should allow for optional fields and 503 backward compatibility. It should be independent of the transport 504 and the message exchange pattern used. 506 ME-9: Human readability of messages exchanged on the wire might be a 507 goal but it is secondary to efficiency concerns. 509 4.5. Message Exchange Pattern Requirements 511 Message exchange patterns form the basis for all service level 512 activities. MEPs create a pattern of message exchanges that any task 513 can be mapped to whether initiated by a client or the server. This 514 section provides the requirements for MEPS. 516 MEP-1: I2RS defines three types of messages between the client and 517 the server. First, capabilities need to be exchanged on session 518 establishment. Second, API commands are sent from a client to a 519 server to add, delete, modify and query state. And third, 520 asynchronous notifications are sent from a server to a client when 521 interesting state changes occur. 523 MEP-2: The above message exchanges can be satisfied by two message 524 exchange patterns. Capabilities and asynchronous notifications 525 can be satisfied by one-way unsolicited fire and forget message. 526 API commands can be satisfied using a request-response message 527 exchange. The base I2RS framework should thus support at least 528 these two MEPs. 530 MEP-3: For a request-response MEP, the server SHOULD acknowledge 531 every request message from the client with a response message. 533 MEP-4: The response message in a request-response MEP SHOULD 534 indicate that the server has received the message, done some basic 535 sanity checking on its contents and has accepted the message. The 536 arrival of a response does not mean all post processing of the 537 message has completed. 539 MEP-5: If an error occurs with an API command, The response message 540 MUST indicate an error and carry error information if there was a 541 failure to process the request. The error code SHOULD be 542 accompanied by a descriptive reason for the failure. 544 MEP-6: Error codes SHOULD indicate to the client which layer 545 generated that error (transport, message parsing, schema 546 validation, application level failure, etc). The I2RS framework 547 should specify a standard set of error codes. 549 MEP-7: The request-response messages SHOULD be asynchronous. That 550 is, the client should not be required to stop-and-wait for one 551 message to be acknowledged before it transmits the next request. 552 [ed: there must be a method for dependency tracking in the 553 protocol. possibly negotiate as an optional capability?] 555 MEP-8: To satisfy asynchronous operations, a mechanism MUST exist 556 to correlate response messages to their respective original 557 requests. For example, a message-id could be carried in the 558 response that would help the sender to correlate the response 559 message to its original request. 561 MEP-9: The response messages need not arrive in the order in which 562 the request was transmitted. [ed: again, there must be a method 563 for providing an order of operations, and for receiving positive 564 ack on completion] 566 MEP-10: The request message SHOULD carry an application cookie that 567 should be returned back to it in the corresponding response. [ed: 568 provide further justification] 570 MEP-11: Besides the request-response MEP, there is a need for a fire 571 and forget MEP. Asynchronous notifications from the server to the 572 client could be carried using this MEP. Fire and forget MEPs can 573 be used in both client-to-server and server-to-client directions. 575 MEP-12: Fire-and-forget messages MAY optionally be acknowledged. 577 MEP-13: The fire-and-forget MEP does not carry a message-id but it 578 SHOULD carry a cookie that can be set by the sender and processed 579 by the receiver. The cookie could help the receiver of the 580 message to use the message for its intended purpose. 582 4.6. API Method Requirements 584 API methods specify the exact operation that one participant intends 585 to perform. This section outlines the requirements for API methods. 587 API-1: The I2RS framework SHOULD provide for a simple set of API 588 methods, invoked from the client to the server. These methods 589 should allow to add, modify, query and delete of state that the 590 server maintains. 592 API-2: The I2RS framework should provide for three query methods, 593 subscribe, unsubscribe, and one-time-query, that the client can 594 use to express an interest or collect specific state changes or 595 state from the server. 597 API-3: The API methods discussed in API-1 and API-2 should be 598 transported in a request-response MEP from the client to the 599 server. 601 API-4: The API framework SHOULD provide for a single notify method 602 from the server to the client when interested state changes occur. 603 The notification method SHOULD be transported in a fire-and-forget 604 MEP from the server to the client. 606 API-5: The framework SHOULD define a set of base API methods for 607 manipulating state. These SHOULD be generic and SHOULD not be 608 service specific. 610 API-6: All API methods that affect the state in the server SHOULD 611 be idempotent. That is, the final state on the server should be 612 independent of the number of times a state change method with the 613 same parameters was invoked by the client. 615 API-7: All API methods SHOULD support a batched mode for efficiency 616 purposes. In this mode multiple state entries are transmitted in 617 a single message with a single operation such as add, delete, etc. 618 For methods described in A.1 and A.2 which elicit a response, the 619 failure mechanism that is specific to a subset of state in the 620 batch should be devised. The Notify method SHOULD also support a 621 batched mode. 623 API-8: Since the API methods are primarily oriented towards state 624 transfer between the client and server, there SHOULD be a 625 identifier (or a key) to uniquely identify the state being 626 addressed. 628 API-9: API methods that refer to value of a particular state SHOULD 629 carry the state identifier (key) as well as the its value. For 630 instance, during a state add operation, both the identifier (key) 631 and the value SHOULD be passed down from the client to the server. 633 API-10: Besides basic API methods common to all services, a server 634 could support proprietary methods or service specific methods. 635 The framework SHOULD specify a mechanism to express these methods 636 and their semantics through a modeling language or otherwise. The 637 ability to support additional API methods SHOULD be conveyed to 638 the client through capability negotiation. 640 API-11: Transactions allow a set of operations to be completed 641 atomically (all or nothing) and that the end result is consistent. 642 Transactions MAY be required for some network applications. [ed: 643 i'd like to remove this for the the first version. it's a bit of 644 a canard'] 646 4.7. Service and SDM Requirements 648 SVC-1: Each service is associated with a service data model that 649 defines the type and structure of the state (data) pertaining to 650 that service. I2RS MUST provide mechanisms to manage the state 651 held in the server in accordance to the SDM. 653 SVC-2: The base I2RS API methods MUST allow a client to add, 654 modify, query and delete state information. 656 SVC-3: Neither the transport or the MEP SHOULD have any bearing on 657 the structure of the state being transferred. Each service module 658 in the server would be responsible for interpreting the structure 659 of the state being transferred corresponding to the SDM. 661 SVC-4: A client, after proper identification, could operate on 662 multiple 'services' that are exported to it. A client could have 663 read-only or read-write access to a given service. The 664 availability of the service, valid entities and parameter ranges 665 associated with same are expressed via the exchange of capability 666 information with the client. 668 SVC-5: The arrangement and structure of state (SDM) SHOULD be 669 expressed in a network friendly data modeling language. [ed: I 670 have no idea what this means] 672 SVC-6: The data modeling language SHOULD have the ability to 673 express one-to-one, one-to-many and hierarchical relationships 674 between modelled entities. 676 SVC-7: The data modeling language MUST allow for a service data 677 model to be extended beyond its initial definition. The language 678 MUST be able to express mandatory and optional elements in SDMs. 679 It SHOULD also have the ability to express exceptions for 680 unsupported elements in the model. 682 SVC-8: For every service that it wishes to expose to a client, the 683 server SHOULD send capabilities that indicate the existence and 684 identity of the service data model, as well as valid states and 685 parameter ranges, any exceptions to it and the optional features 686 of the data model that it supports. 688 SVC-9: The data modeling language MUST be able to express a 689 dependence of service data model on another SDM. It SHOULD also 690 have the ability to express references to state elements in 691 another service data model. 693 SVC-10: The modeling language MUST have the ability to express read/ 694 write and read-only constraints for state elements in an SDM. 695 Readable state elements are populated and managed by the server 696 and clients don't have the ability to write their value. Routing 697 next-hops added by a client is an example of read-write state. 698 Statistics associated with that next-hop is an example of read- 699 only state. 701 SVC-11: Query and notification APsI MUST be able to carry both read- 702 only as well as read-write state. 704 SVC-12: Besides specifying a SDM, a service SHOULD also specify the 705 interesting state changes that clients can subscribe to for 706 notifications. The absence of such a specification SHOULD be 707 interpreted as an implicit unavailability of any subscribable 708 entities. [ed: terminology to be worked out here] 710 SVC-13: A client which is authenticated to access a service (either 711 read-only or read-write) MAY subscribe to any subscribable state 712 change events. 714 SVC-14: A subscribe method SHOULD optionally have a filter 715 associated. This increases the efficiency by filtering out events 716 that the client is not interested in. The notification filter 717 should have the ability to express state identifiers and wildcards 718 for values. 720 SVC-15: The base API operations MUST be generic and allow a client 721 to operate on multiple services with the same set of methods. 722 Each service dictates its one schema or SDM. 724 SVC-16: I2RS protocol SHOULD allow a server to export standard 725 services as well as vendor proprietary services. A namespace 726 scheme should be devised to recognize standard and proprietary 727 services. 729 SVC-17: The server SHOULD indicate to the client the availability of 730 infrastructure to manage the state that it maintains. This 731 includes but is not limited to the availability of persistent 732 store, the availability of timer to clean up state after a 733 specified timeout, the ability to clean up state on the occurrence 734 of an event, etc. Equipped with this information, the client is 735 responsible for the lifetime of the state. 737 SVC-18: Each state SHOULD have a set of meta data associated with 738 it. This includes the state's owner, the state's lifetime 739 attributes, a creation and modification timestamp, etc. This 740 information would aid in the debugging of the system. An 741 authenticated client that is exposed to a service SHOULD also have 742 access to the meta data associated with that service's state. 744 4.8. Security Requirements 746 This section lists security requirements for the I2RS protocol. 748 SEC-1: Every client MUST be authenticated and associated with an 749 identity. A secure mechanism to uniquely identify a client such 750 as certificates MUST be adopted. 752 SEC-2: Every client MUST have an authorized role whereby only 753 certain state can be accessed and only certain operations can be 754 performed by that client. To keep the model simple and 755 applications portable, authorization MUST be at a per service 756 level and not on individual state element level. 758 SEC-3: The framework MUST provide for information confidentiality 759 and information integrity as options. 761 SEC-4: Every state maintained by the server SHOULD be tagged with 762 the client's identity as well as meta-data to indicate last access 763 and last modifications time-stamps. This ensures accountability 764 and helps auditing the system. 766 SEC-5: Mechanisms to "hook" into third-party security infrastructure 767 whenever possible SHOULD be provided in order to achieve security 768 goals. Applications programmers SHOULD be kept free of security 769 concerns and yet given a flexible, configurable and well 770 integrated security model. 772 4.9. Performance and Scale Requirements 774 Performance requirements are usually woven in with the functional 775 requirements of a system. They feature in every decision made to 776 fulfill the systems requirements. Performance and scale are a 777 complex function of many things. Hence performance requirements 778 cannot be precisely quantified by a single number. This section lays 779 out some common sense guidelines that should be kept in mind while 780 designing the system from a scale and performance standpoint. 782 PS-1: The request-response MEP SHOULD be asynchronous. This 783 ensures that a system is not stuck waiting for a response and 784 makes the entire system more responsive and enables concurrency 785 between operations. 787 PS-2: When applicable, messages SHOULD carry application level 788 cookies that enable an application to quickly lookup the context 789 necessary to process a message. Management of cookies is the 790 applications responsibility. 792 PS-3: The framework SHOULD allow for bulk operations which 793 amortizes the communication and messaging costs. 795 PS-4: The transport protocol SHOULD provide for a binary encoding 796 option for messages between the participants. 798 PS-5: The transport protocol MUST provide for both encrypted and 799 non-encrypted transport between participants. 801 PS-6: The transport protocol MUST provide for message 802 prioritization. 804 PS-7: Multiple operations should be completed using a single 805 transport session whenever possible. 807 PS-8: The server MUST be kept stateless with respect to the number 808 and location of each client. 810 PS-9: Filtered subscription MUST be supported for notifications. 812 PS-10: An efficient synchronization mechanism between a client and a 813 server SHOULD be provided that avoids transferring all the state 814 between them. 816 PS-11: Allow clients that perform infrequent operations to 817 disconnect their transport connection without cleaning up their 818 state. 820 PS-12: Create the basic necessary mechanisms in the framework and 821 build everything else as a service if possible. 823 4.10. High Availability Requirements 825 The ability of the system to withstand operational failures and 826 function in a predictable manner is called availability. A few 827 guidelines that are important are, 829 HA-1: A 'superuser' identity SHOULD be provided that is capable of 830 changing security policies, clearing state and perform actions 831 that override client initiated actions in the system. 833 HA-2: Session disconnection and client deaths MUST be handled 834 gracefully. They should have the least impact on the server 835 system. 837 HA-3: Client connections and disconnections MUST be logged and 838 provided as a well-known service to authenticated users. 840 HA-4: Clients MUST be notified of message processing and other 841 errors through error codes in messages. 843 HA-5: A mechanism to gracefully terminate the session between the 844 client and the server MUST be provided. 846 HA-6: A mechanism for authenticated clients to query the load 847 attributes of the system, both instantaneous and running average 848 MUST be provided as a service. 850 4.11. Application Programmability Requirements 852 The framework should pay particular attention the requirements of 853 application programmers. A well written framework should improve the 854 productivity of programmers and shorten the time to make an 855 application. This section has some issues to consider when devising 856 the framework from an applications standpoint. 858 PGM-1: A client programming framework SHOULD allow applications 859 writers to focus on the app functionality rather than mechanisms 860 required to communicate with the server. 862 PGM-2: The application once written to certain requirements should 863 be portable to other identical environments. The framework should 864 not have fine grained data access controls as this would lead to a 865 poorly written application with portability issues. 867 PGM-3: The framework should be devised in a manner that it is 868 possible to automate code generation and constraint checking in 869 popular programming languages. Generated code can then be used 870 readily by application programmers instead of dealing with the 871 nitty-gritties of the system. 873 PGM-4: Define a common repository for SDMs from which clients can 874 obtain the SDMs they are interested in and automatically generate 875 most of the boilerplate code. 877 PGM-5: Provisions SHOULD be made for debugging and troubleshooting 878 tools that includes message trace, call traces, access to relevant 879 server traces and logs, packet decode tools to trace and decode 880 messages on the wire, consistency checkers of state inserted into 881 a server. 883 PGM-6: The toolset should have a general portion (for common 884 functions, such as session management) and SDM-specific portions 885 (for example, a flag to control generation of debug code in code 886 generated for a particular SDM). 888 PGM-7: The framework SHOULD define SDMs and MDMs in a language 889 neutral format so as to enable code generation in multiple 890 programming languages. 892 4.12. Operational Requirements 894 OP-1: There is a need to identify operational performance parameters 895 of the system and provide mechanisms to retrieve them from a 896 running system. 898 OP-2: Provide a way to upgrade a service independently of the other 899 services. This modularity allows uninterrupted operation of the 900 all but one service which is being upgraded. 902 OP-3: Provide a detailed workflow for bringing about a new service. 903 This workflow will start with the need to introduce a new service 904 and address the following: How SDMs defined? Where are they 905 standardized? How are new entities (MEPs, transport, encoding) 906 introduced? What are the tools and workflow involved to develop 907 and operationalize a service. The intent is to introduce a level 908 of understanding about stakeholders responsibilities. 910 OP-4: Provide mechanisms and methodologies to test a new service 911 before deployment. 913 5. Contributing Authors 915 Thanks to the following people for reviewing and providing meaningful 916 contributions: Alia Atlas, Palani Chinnakannan, Alexander Clemm, 917 Muthumayan Mahdhayyan, John McDowell and Bruno Rijsman and David 918 Ward. 920 6. References 922 6.1. Normative References 924 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 925 Requirement Levels", BCP 14, RFC 2119, March 1997. 927 6.2. Informative References 929 [I-D.ietf-i2rs-architecture] 930 Atlas, A., Halpern, J., Hares, S., Ward, D., and T. 931 Nadeau, "An Architecture for the Interface to the Routing 932 System", draft-ietf-i2rs-architecture-00 (work in 933 progress), August 2013. 935 [I-D.ietf-i2rs-problem-statement] 936 Atlas, A., Nadeau, T., and D. Ward, "Interface to the 937 Routing System Problem Statement", draft-ietf-i2rs- 938 problem-statement-00 (work in progress), August 2013. 940 [RFC1776] Crocker, S., "The Address is the Message", RFC 1776, April 941 1995. 943 [RFC1925] Callon, R., "The Twelve Networking Truths", RFC 1925, 944 April 1996. 946 Authors' Addresses 948 Rex Fernando 949 Cisco Systems 950 170 W Tasman Dr, 951 San Jose, CA 95134 952 US 954 Email: rex@cisco.com 956 Jan Medved 957 Cisco Systems 958 170 W Tasman Dr, 959 San Jose, CA 95134 960 US 962 Email: jmedved@cisco.com 964 Edward Crabbe 965 Google 966 1600 Amphitheater Parkway 967 Mountain View, CA 94043 968 US 970 Email: edward.crabbe@gmail.com 972 Keyur Patel 973 Cisco Systems 974 170 W Tasman Dr, 975 San Jose, CA 95134 976 US 978 Email: keyur@cisco.com