idnits 2.17.1 draft-rfernando-irs-framework-requirement-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 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 == Line 94 has weird spacing: '...APIs to acce...' == Line 169 has weird spacing: '...defined inte...' == Line 170 has weird spacing: '...rver is typi...' == Line 193 has weird spacing: '...d to as the...' == Line 233 has weird spacing: '...for the stat...' == (6 more instances...) -- The document date (October 11, 2012) is 4209 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '2' on line 110 == Missing Reference: 'RFC2119' is mentioned on line 134, but not defined Summary: 1 error (**), 0 flaws (~~), 8 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT R. Fernando 3 Intended Status: Informational J. Medved 4 Expires: April 11, 2013 D. Ward 5 Cisco 7 A. Atlas 8 B. Rijsman 9 Juniper Networks 10 October 11, 2012 12 IRS Framework Requirements 13 draft-rfernando-irs-framework-requirement-00 15 Abstract 17 The Interface to Routing System (IRS) allows an application to 18 programmatically query and modify the state of the network. This 19 document defines the requirements for IRS with appropriate 20 reasoning where required. 22 Status of this Memo 24 This Internet-Draft is submitted to IETF in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF), its areas, and its working groups. Note that 29 other groups may also distribute working documents as 30 Internet-Drafts. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 The list of current Internet-Drafts can be accessed at 38 http://www.ietf.org/1id-abstracts.html 40 The list of Internet-Draft Shadow Directories can be accessed at 41 http://www.ietf.org/shadow.html 43 Copyright and License Notice 45 Copyright (c) 2012 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. IRS Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. IRS Framework Terminology . . . . . . . . . . . . . . . . . . . 4 64 4. IRS Framework Design Objectives . . . . . . . . . . . . . . . . 7 65 5. IRS Framework Requirements . . . . . . . . . . . . . . . . . . 9 66 5.1 General Assumptions . . . . . . . . . . . . . . . . . . . . 9 67 5.2 Transport Requirements . . . . . . . . . . . . . . . . . . . 10 68 5.3 Identity Requirements . . . . . . . . . . . . . . . . . . . 11 69 5.4 Message Encoding Requirements . . . . . . . . . . . . . . . 12 70 5.5 Message Exchange Pattern Requirements . . . . . . . . . . . 13 71 5.6 API Method Requirements . . . . . . . . . . . . . . . . . . 15 72 5.7 Service and SDM Requirements . . . . . . . . . . . . . . . . 16 73 5.7 Security Requirements . . . . . . . . . . . . . . . . . . . 18 74 5.8 Performance and Scale Requirements . . . . . . . . . . . . . 19 75 5.9 Availability Requirements . . . . . . . . . . . . . . . . . 20 76 5.10 Application Programmability Requirements . . . . . . . . . 20 77 5.11 Operational Requirements . . . . . . . . . . . . . . . . . 21 78 6 Security Considerations . . . . . . . . . . . . . . . . . . . . 21 79 7 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 22 80 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 81 8.1 Normative References . . . . . . . . . . . . . . . . . . . 22 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22 84 1 Introduction 86 Routers, switches and network appliances that form today's network 87 infrastructure maintain state at various layers of detail and 88 function. For example, each router has a Routing Information Base 89 (RIB), and the routing protocols (OSPF, ISIS, BGP, etc.) each 90 maintain protocol state and information about the state of the 91 network. 93 IRS [IRS-FRMWK] defines a standard interface through well defined 94 APIs to access this information. The information collected by an 95 application could be used to influence the routing system in 96 conjunction with user defined policies in a feedback loop. 98 IRS enables this feedback loop so that applications can not only 99 collect information but also use them to influence the network. The 100 goal is to facilitate control and diagnosis of the routing 101 infrastructure, as well as enable sophisticated applications to be 102 built on top of today's network infrastructure. 104 Over time applications would evolve and with it their requirements 105 too. IRS MUST be extensible so that future requirements can be 106 easily factored in. IRS should be modular and extensible. It should 107 be simple to understand and friendly to application developers. 109 This document describes some of these requirements in detail taking 110 into consideration the use cases described in [2]. Particular 111 attention is paid to API and the application consumption model so 112 that it is developer friendly. 114 This document's scope is purely to collect and document requirements 115 for the IRS framework. This could serve three purposes: 117 a. To help the stakeholders (equipment vendors, application 118 programmers or interested IETF participants), to arrive at a common 119 understanding of the important elements of IRS. 121 b. To provide requirements to the designers of IRS framework on the 122 different aspects of the framework that needs consideration in the 123 design process. 125 c. To allow the stakeholders to evaluate technology choices that are 126 suitable for IRS, to identify gaps in them and to help evolve them to 127 suite IRS's needs. 129 1.1 Terminology 131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 132 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 133 document are to be interpreted as described in RFC 2119 [RFC2119]. 135 2. IRS Overview 137 IRS provides a standard interface for applications to read and 138 write state in a network device. Since the application and the 139 network device could reside in different physical nodes, IRS could 140 be viewed as a distributed client-server system. 142 IRS can also be viewed as a "framework" that helps reduce the 143 "start up" cost in developing network based applications. A 144 framework codifies a set of principles, patterns and software 145 artifacts that allow application developers to quickly develop new 146 applications. 148 Instead of designing each application from scratch, the IRS 149 framework provides a set of infrastructure that abstracts the 150 application indepedent mechanisms. This approach enhances software 151 agility, reusability and portability. 153 This document aims at making sure that the requirements of the IRS 154 framework are well articulated by describing its high level 155 objectives, the concepts and components involved, how they are 156 related and what their requirements are. 158 3. IRS Framework Terminology 160 Before we delve into the details of the IRS framework, it might 161 help to establish some basic terminology. 163 Service: For the purposes of IRS, a service refers to a set of 164 related state access functions together with the policies that 165 control its usage. For instance, 'RIB service' could be an example 166 of a service that gives access to state held in a device's RIB. 168 Server: Is a system that implements one or more services so that 169 other client systems can call them through well defined interfaces. 170 A server can export multiple services. A server is typically a 171 network device. 173 Client: Is a system that calls a service implemented by a server 174 through the well defined interface. A client can make use of 175 multiple services from many servers. A client is typically a 176 network application. 178 Participants: The server and client are collectively called the 179 participants of a service. 181 Transport: Is any mode of communication on an end-to-end basis 182 between the server and client that allows them to exchange data. In 183 principle, the transport hides the topology and other network 184 properties from the participants of a service. 186 Messages: Messages are logical chunks of data that are exchanged 187 between service participants. 189 Message Exchange Pattern: Is a categorization of different ways in 190 which messages could be exchanged between service participants. 191 MEPs specify the sequence, order, direction and cardinality of 192 messages exchanged. Request-response and asynchronous notifications 193 are examples of MEPs. MEPs are also sometimes referred to as the 194 session protocol. 196 Message Data Model: The schema representing the structure of 197 messages being exchanged between the service participants. The MDMs 198 can specify certain constraints such as the data type, length, 199 format and allowed values of fields in messages. 201 Message Encoding: The "wire" representation of messages exchanged 202 between service participants. 204 API Method: Is an application level procedure or a function that is 205 invoked by the client to query or modify the state held in the 206 server. 208 Service Scope: Is the functional scope of a service. The service 209 scope is established during the service definition phase. 211 Service Data Model: The schema representing the conceptual 212 structure of the state held in the server for a given service. The 213 SDMs can specify certain constraints such as the data type, length, 214 format and allowed values for fields representing the state. They 215 also describe the relationship between the state. 217 Modeling Language: Is a language that defines schema for Message 218 Data Models and Service Data Models. 220 Namespaces: Allows a method for uniquely identifying and scoping of 221 schemas declared for messages and services. Namespace is an 222 important consideration when defining services and messages. 224 Service State or State: Is the general data held by the server for 225 a given service. 227 State Element: A programmable state present in the server. State 228 Element could vary in granularity. 230 State Identifier: A unique identity for the state element. The 231 identifier is derived from the SDM and uses the same naming 232 convention as the SDM. State Identifier can be viewed as the 'key' 233 for the state. 235 State Value or 'value: This is a value that is assigned to a 236 particular state identifier (key). The state is referred using the 237 State Identifier or 'key' in operations that sets or transfers the 238 value of the state. 240 State Owner: Identity of the client that was the source of a state 241 held in the server. 243 State lifetime: The duration up to which the state is maintained in 244 the server. 246 Datastore: This is the physical mechanism used to store a service's 247 state. 249 Capabilities: Capabilities represents the functionality supported 250 by a server including the services supported and exported to 251 clients. 253 Authentication: Mechanism that allows a server to recognize the 254 identity of a client. 256 Authorization: Determination of what an authenticated client is 257 allowed to do. 259 Confidentiality: Specifies if data remains confidential while in 260 transit between service participants. 262 Policy: For the purposes of this document, a policy is an explicit 263 user configurable modification to the default behavior of the 264 system. The enforcement could be conditional; they could become 265 effective only when certain conditions are met. 267 As can be seen, there are many aspects to be considered in designing 268 the IRS framework. The next section decribes the broad objectives of 269 the framework and breaks down the concerns so that each's 270 requirements can be individually examined. 272 4. IRS Framework Design Objectives 274 The goal is to provide a framework with the infrastructural 275 components needed to develop intelligent applications that control 276 the network. These are some of the core guiding principles and 277 objectives that should be kept in mind when designing that 278 framework. 280 a. Requirements Driven: The design of the framework should be 281 pragmatic and requirements driven. Having adequate provisions to 282 meet the needs of current applications yet making key aspects 283 extensible to meet future needs should be the goal. 285 b. Simple to Program: The success of any architectural framework 286 depends on the how simple it is to understand and implement 287 against. When presented with multiple choices to perform a 288 function, choosing one of them instead of supporting all of them 289 might lead to simpler design. In doing so, the design should 290 consider the most important requirements and the most common 291 deployment scenarios. 293 c. Standards Based: The need for a standards-based approach to 294 network programmability has been recognized by many standardization 295 groups including IETF. All aspects of IRS should be open standards 296 based. However, IRS should specify mechanisms to extend it in vendor 297 specific manner. The aspects of IRS that could be extended should 298 be identified in this document and should be supported by an 299 implementation. 301 d. Design for Scale and Performance: The design should meet current 302 and future performance and scale needs. It goes without saying that 303 scale and performance should be key criteria for making design 304 choices. There are well understood design patterns that allow us to 305 compose a scalable, high performing system. 307 e. Extensible: IRS will be deployed in environments whose 308 requirements evolve over time. Hence the system should be designed 309 with provisions that will allow significant enhancements to be added 310 to meet specified future goals and requirements. An extensible and 311 future-proof design will drive better adoption as it is a promise 312 against future technology churn. 314 f. Promote Reuse: Reuse in this context refers to using existing 315 tools, technologies and mechanisms instead of inventing them from 316 scratch. It also refers to reusing a network device's current set 317 of capabilities that applications could harness without reinventing 318 them from scratch. 320 g. Promote Portability: Portability refers to the ease with which 321 software written for one device or environment can be moved to work 322 seamlessly with another device or environment to achieve similar 323 functionality. A fundamental requirement for IRS is to achieve 324 predictive and consistent behavior when applications are migrated 325 from one platform or environment to another. 327 h. Security: IRS could be deployed in environments where it might be 328 subjected to threats and denial-of-service attacks that might cause 329 intentional damage to the functioning of a network. This could be 330 in the form of loss of service, degradation of performance, loss of 331 confidentiality, etc. Therefore, the security aspects should be 332 carefully thought through when designing IRS. 334 i. Separation of concerns: The components of the system should be 335 decoupled from each other as much as possible to achieve clear 336 separation of concerns. This modularity would allow for 337 interchangeable design and implementation choices that address the 338 individual components requirements. 340 j. Robustness: Robustness is the ability of a system to operate in 341 the face of failures and errors. It is also its ability to correctly 342 and predictably recover from such errors and to settle to a known 343 state. Since applications that use the IRS framework are remote and 344 would be controlling the entire network, ensuring fault tolerance 345 is an important consideration. 347 Most of these requirements cut across all the components of the 348 system and hence should be kept in mind while designing each 349 component and the system as a whole. 351 5. IRS Framework Requirements 353 This section is divided into multiple sub-sections, each dealing with 354 a specific consideration of IRS framework design. As we list the 355 requirements under each subsection, we'll annotate each requirement 356 with what high level objectives they meet. A reason for creating the 357 requirement is additionally provided where appropriate. 359 5.1 General Assumptions 361 This section captures the general, high level assumptions of the IRS 362 framework. Since the design choices for the IRS framework are many, 363 some simplifying assumptions could make the framework requirements 364 more tangible and useful. 366 +--------+ +--------+ +-----------+ 367 | Client | ... | Client | .... .... | Client | 368 +--------+ +--------+ +-----------+ 369 ^ ^ ^ ^ 370 | | | | 371 | | | | 372 | | | IRS | 373 | | +-------------+ | 374 | | | | 375 | | IRS | | 376 | +---+ | | IRS 377 | | | | 378 | IRS | | | 379 +------------------+ | | | 380 | | | | 381 V V V V 382 +-----------+ +-----------+ 383 | Server | | Server | 384 +-----------+ +-----------+ 386 G.1 Programmatic access to the state held in a network device is 387 provided to an application by exposing a set of API's from the 388 device to the application. Due to this characteristic, IRS is a 389 client-server protocol/framework. IRS must provide mechanisms for the 390 client to discover services that a server provides. 392 G.2 The client can use the API's provided by the server to 393 programmatically add, modify, delete and query state held in the 394 server. Additionally clients can register for certain events and be 395 notified when those events occur. 397 G.3 The client and the server communicate using a simple transport 398 connection. The client initiates the transport connection to the 399 server. The server does not know the number and timing of the 400 connections from its clients. 402 G.4 A service provides access to the state held in the server 403 structured according to the SDM of that service. A service allows 404 a client the ability to manipulate the service state. 406 G.5 The IRS MUST define a data model to describe the SDMs supported 407 in the server and MUST define a data modeling language to formally 408 describe that data model. IRS MUST specify the mapping from the 409 service data model to the message data model and subsequently to the 410 client API. 412 5.2 Transport Requirements 414 The transport layer provides connectivity between the client and the 415 server. This section details the transport requirements. 417 T.1 There should exist a default transport connection between the 418 client and the server for communication. This control connection is 419 point-to-point and should provide in-order and reliable delivery of 420 data in both directions. The simplest IRS setup will only have a 421 single transport session between the participants. 423 T.2 Depending on the data being exchanged, there could be additional 424 transport connections between the client and server defined in 425 future. The characteristics of these additional transport 426 connections will be dictated by the requirements that create them. 428 T.3 The transport connection between the client and server should 429 have mechanisms to support authentication, authorization and 430 optionally provide confidentiality of data exchanged between the 431 client and the server. See 'Security Requirements' for more details. 433 T.4 A client could connect to multiple servers. Similarly, a server 434 could accept connections from multiple clients. 436 T.5 The exact technology used for the transport layer should be 437 replaceable. There should be a single mandatory transport that 438 should be supported by all participants. This requirement will 439 ensure that there is always an interoperable transport mechanism 440 between any client and any server. 442 T.6 Clients and servers by default communicate using a point-to-point 443 transport connection. 445 T.7 Point-to-multipoint transport are mainly used to scale the system 446 by avoiding ingress replication when the same message has to be 447 delivered to multiple receivers. P2MP transport would work hand-in- 448 hand with a P2MP MEP. The subject of P2MP transport and P2MP MEP is 449 for future work. 451 T.8 Once the transport connection is up, it is desirable to keep it 452 up and use it to perform multiple operations. This requirement 453 ensures that the system scales by amortizing the session setup 454 cost across multiple operations. Session down events do not have 455 an impact on the state maintained by the server. 457 T.9 After the transport connection comes up, the participants 458 exchange capabilities and other session parameters before exchanging 459 service related messages. 461 T.10 Messages pertaining to multiple services could be exchanged over 462 a single transport connection. 464 T.11 The "default" transport connection between the client and server 465 is purely for control plane message exchanges. Data plane packets 466 are not expected to be sent over this "default" connection. When 467 required, data plane 'punt' and 'inject' packets between 468 participants could be designed as a service in itself that sets 469 up a 'punt-inject-transport' that processes the right 470 characteristics. 472 T.12 For operational reasons, there MUST be a need to identify a 473 transport connection failure. To satisfy this requirement, transport 474 level keep-alives could be used. If the underlying transport 475 connection does not provide a keep-alive mechanism, it should be 476 provided at the IRS protocol level. For example, if TCP is used as a 477 transport, TCP keep-alives could be used to detect transport 478 session failures. 480 5.3 Identity Requirements 482 IRS could be used in a multi-domain distributed environment. 483 Therefore a fool-proof way to ascertain the identity of clients is of 484 utmost importance. Identity provides authenticated access to clients 485 to state held by the server. 487 I.1 Each client should have a unique identity that can be verified by 488 the server. The authentication could be direct or through an 489 identity broker. 491 I.2 The server should use the client's identity to track state 492 provided by the client. State ownership enables the multiple 493 clients to edit their shared state. This is useful during client 494 death or disconnection when state owned by one client might be 495 delegated to another client that shares the same identity. 497 I.3 The client's identity should be independent of the location or 498 the network address of the physical node in which it is hosted. This 499 allows the client to move between physical nodes. It also allows a 500 standby client to take over when the primary fails and allows shared 501 state editing by multiple clients as discussed in I.2. 503 I.4 A client that reboots or reconnects after a disconnection MUST 504 have the same identity if it wishes to continue to operate on the 505 state that it previously injected. 507 I.5 A clients ability to operate on a state held by the server is 508 expressed at the granularity of a service. A service could be 509 read-only or read-write by a client possessing a particular 510 identity. 512 I.6 A policy on the server could dictate the services that could be 513 exposed to clients. Upon identity verification, the authorized 514 services are exported to the client by capability announcement. 516 I.7 A client can edit (write, delete) only the state that was 517 injected by it or other clients with the same shared identity. 518 Therefore, two conditions must be met for a client to edit a state 519 through a session. First, the client should receive capability from 520 the server that it has 'edit' permissions for the service in 521 question, and, secondly, the state that it edits should be its 522 own state. 524 I.8 When there is a single client and it dies, operational provisions 525 should be made to garbage collect its state by a client that 526 shares the original clients identity. 528 I.9 The server retains the client's identity till all of its state is 529 purged from the server. 531 5.4 Message Encoding Requirements 533 Clients and servers communicate by exchanging messages between them. 534 Message encoding is the process of converting information content in 535 a message to a form that can be transferred between them. 537 ME.1 Every message between the client and the server is encoded in a 538 transport independent frame format. 540 ME.2 Each message is serialized on the senders side and de-serialized 541 on the receivers side. The technology used for encoding and 542 decoding messages could be negotiated between the client and the 543 server. 545 ME.3 A mandatory default encoding standard should be specified and 546 implemented by all IRS participants. This ensures that there is 547 an interoperable default encoding mechanism between any client 548 and any server. 550 ME.4 The mandatory encoding technology chosen should be well 551 supported by a developer community and should be standards based. 552 Availability of tools and language bindings should be one of the 553 criteria in selecting the mandatory encoding technology. 555 ME.5 If multiple message encoding is supported in the framework, the 556 encoding used for the current session should be configured using 557 a policy on the server side and negotiated using capabilities. Note 558 that currently there is no requirement to support multiple encoding 559 schemes. 561 ME.6 The message encoding standard should be language and platform 562 neutral. It should provide tools to express fields in messages 563 platform independent IDL based language. 565 ME.7 The encoding/decoding mechanism should be fast and efficient. It 566 should allow for operation on legacy equipment. 568 ME.8 The encoding scheme should allow for optional fields and 569 backward compatibility. It should be independent of the transport and 570 the message exchange pattern used. 572 ME.9 Human readability of messages exchanged on the wire might be a 573 goal but it is secondary to efficiency needs. 575 5.5 Message Exchange Pattern Requirements 577 Message exchange patterns form the basis for all service level 578 activities. MEPs create a pattern of message exchanges that any task 579 can be mapped to whether initiated by a client or the server. This 580 section provides the requirements for MEPS. 582 MEP.1 IRS defines three types of messages between the client and the 583 server. First, capabilities need to be exchanged on session 584 establishment. Second, API commands send down from client to server 585 to add, delete, modify and query state. And third, asynchronous 586 notifications from server to client when interesting state 587 changes occur. 589 MEP.2 The above message exchanges can be satisfied by two message 590 exchange patterns. Capabilities and asynchronous notifications can be 591 satisfied by one-way unsolicited fire and forget message. API 592 commands can be satisfied using a request-response message exchange. 593 The base IRS framework should thus support at least these two MEPs. 595 MEP.3 For a request-response MEP, the server should acknowledge every 596 request message from the client with a response message. 598 MEP.4 The response message in a request-response MEP should indicate 599 that the server has received the message, done some basic sanity 600 checking on its contents and has accepted the message. The 601 arrival of a response does not mean all post processing of the 602 message has completed. 604 MEP.5 The response message should indicate an error and carry error 605 information if there was a failure to process the request. The 606 error code should be accompanied by a descriptive reason for 607 the failure. 609 MEP.6 Error codes should indicate to the client which layer generated 610 that error (transport, message parsing, schema validation, 611 application level failure, etc). IRS framework should specify a 612 standard set of error codes. 614 MEP.7 The request-response messages should be asynchronous. That is, 615 the client should not stop-and-wait for one message to be 616 acknowledged before it transmits the next request. 618 MEP.8 To satisfy MEP.5, there needs to be a mechanism such as a 619 message-id, carried in the response that helps the sender correlate 620 the response message to its original request. 622 MEP.9 The response messages need not arrive in the order in which the 623 request was transmitted. 625 MEP.10 The request message should carry an application cookie that 626 should be returned back to it in the corresponding response. 628 MEP.11 Besides the request-response MEP, there is a need for a fire 629 and forget MEP. Asynchronous notifications from the server to the 630 client could be carried using this MEP. Fire and forget MEPs can be 631 used in both client-to-server and server-to-client directions. 633 MEP.12 The fire-and-forget MEP does not carry a message-id but it 634 should carry a cookie that can be set by the sender and 635 processed by the receiver. The cookie could help the receiver 636 of the message to use the message for its intended purpose. 638 5.6 API Method Requirements 640 API methods specify the exact operation that one participant intends 641 to perform. This section outlines the requirements for API methods. 643 A.1 The IRS framework should provide for a simple set of API methods, 644 invoked from the client to the server. These methods should allow 645 to add, modify, query and delete of state that the server maintains. 647 A.2 The IRS framework should provide for two methods, subscribe and 648 unsubscribe, that the client can use to express its interest in 649 specific state changes in the server. 651 A.3 The API methods discussed in A.1 and A.2 should be transported 652 in a request-response MEP from the client to the server. 654 A.4 The API framework should provide for a single notify method from 655 the server to the client when interested state changes occur. The 656 notification method should be transported in a fire-and-forget MEP 657 from the server to the client. 659 A.5 The framework should define a set of base API methods for 660 manipulating state. These should be generic and should not service 661 specific. 663 A.6 All API methods that affect the state in the server should be 664 idempotent. That is, the final state on the server should be 665 independent of the number of times a state change method with the 666 same parameters was invoked by the client. 668 A.7 All API methods should support a batched mode for efficiency 669 purposes. In this mode multiple state entries are transmitted in a 670 single message with a single operation such as add, delete, etc. For 671 methods described in A.1 and A.2 which elicit a response, the failure 672 mechanism that is specific to a subset of state in the batch should 673 be devised. Notify method should also support a batched mode. 675 A.8 Since the API methods are primarily oriented towards state 676 transfer between the client and server, there should be a 677 identifier (or a key) to uniquely identify the state being 678 addressed. 680 A.9 API methods that refer to value of a particular state should 681 carry the state identifier (key) as well as the its value. For 682 instance, during a state add operation, both the identifier (key) and 683 the value should be passed down from the client to the server. 685 A.10 Besides the basic API methods that are common to all services, 686 a server could support proprietary methods or service specific 687 methods. The framework should devise a mechanism to express 688 these methods and their semantics through a modelling language 689 or otherwise. The ability to support additional API methods 690 should be conveyed to the client through the capability message. 692 A.11 Transactions allow a set of operations to be completed atom(all 693 or nothing) and that the end result is consistent. This might be a 694 requirement for some network applications and the framework designers 695 should keep this requirement in mind during the design phase. 697 5.7 Service and SDM Requirements 699 S.1 Each service is associated with a service data model that defines 700 the type and structure of the state pertaining to that service. IRS 701 should provide mechanisms to manage the state held in the server in 702 accordance to the SDM. 704 S.2 The data model should have the ability to express one-to-one, 705 one-to-many and hierarchical relationships between entities. 707 S.3 The base IRS API methods should allow a client to add, modify, 708 query and delete state information. 710 S.4 Neither the transport or the MEP should have any bearing on the 711 structure of the state being transferred. Each service module in 712 the server would be responsible for interpreting the structure of 713 the state being transferred corresponding to the SDM. 715 S.5 A client, after proper identification, could operate on multiple 716 'services' that are exported to it. A client could have read-only 717 or read-write access to a service. This is expressed by exchanging 718 capability information with the client. 720 S.6 The arrangement and structure of state (SDM) should be expressed 721 in a network friendly data modelling language. 723 S.7 Service data model once defined should be able to be extended. 724 Service data models should be able to express mandatory and optional 725 elements. If should also have the ability to express exceptions 726 for unsupported elements in the model. These are requirements for 727 the modelling language. 729 S.8 For every service that it wishes to expose to a client, the 730 server should send capabilities that indicate the service data model, 731 any exceptions to it and the optional features of the data model 732 that it supports. 734 S.9 A service data model could be dependent on another SDM and 735 should have the ability to refer to state elements in another 736 service data model. 738 S.10 A state element expressed in a data model could be writeable by 739 a client or purely readable. Readable state elements are populated 740 and managed by the server and clients don't have the ability to 741 write their value. Routing next-hops added by a client is an 742 example of read-write state. Statistics associated with that 743 next-hop is an example of read-only state. The modelling language 744 should have the ability to express this constraint. 746 S.11 Query and notification API should be able to carry both read- 747 only as well as read-write state. 749 S.12 Besides specifying a SDM, a service should also specify the 750 interesting state changes that clients can subscribe to for 751 notifications. 753 S.13 A client which is authenticated to access a service (either 754 read-only or read-write) can subscribe to state change events. 756 S.14 A subscribe method should optionally have a filter associated. 757 This increases the efficiency by filtering out events that the 758 client is not interested in. The notification filter should have 759 the ability to express state identifiers and wildcards for 760 values. 762 S.15 The base API operations should be generic and allow a client to 763 operate on multiple services with the same set of methods. Each 764 service dictates its one schema or SDM. 766 S.16 IRS protocol should allow a server to export standard services 767 as well as vendor proprietary services. A namespace scheme should be 768 devised to recognize standard and proprietary services. 770 S.17 The server should indicate to the client the availability of 771 infrastructure to manage the state that it maintains. This 772 includes but not limited to the availability of persistent store, 773 the availability of timer to clean up state after a specified 774 timeout, the ability to clean up state on the occurrence of an 775 event, etc. Equipped with this information, the client is 776 responsible for the lifetime of the state. 778 S.18 Each state should have a set of meta data associated with 779 it. This includes the state's owner, the state's lifetime 780 attributes, a creation and modification timestamp, etc. This 781 information would aid in the debugging of the system. An 782 authenticated client that is exposed to a service should also 783 have access to the meta data associated with that service's 784 state. 786 5.7 Security Requirements 788 Security requirements should be thought through up front to avoid 789 expensive rework to the framework. Adding security requirements once 790 the system is designed could be an expensive and painful process. 791 This section calls out some security concerns to be kept in mind 792 while designing the framework. 794 SEC.1 Every client should be authenticated and associated with an 795 identity. A secure mechanism to uniquely identify a client such 796 as certificates should be adopted. 798 SEC.2 Every client should have an authorized role whereby only 799 certain state can be accessed and only certain operations can be 800 performed by that client. To keep the model simple and 801 applications portable, authorization should be at a per service 802 level and not on individual state element level. 804 SEC.3 The framework should provide for information confidentiality 805 and information integrity as options. 807 SEC.4 Every state maintained by the server should be tagged with the 808 client's identity as well as meta-data to indicate last access 809 and last modifications time-stamps. This ensures accountability 810 and helps auditing the system. 812 SEC.5 The framework designers are strongly encouraged to provide 813 mechanisms to "hook" into third-party security infrastructure to 814 achieve these security goals whenever possible. This keeps 815 applications programmers free of security concerns and yet 816 provides a flexible, configurable and well integrated security 817 model. 819 5.8 Performance and Scale Requirements 821 Performance requirements are usually weaved in with the functional 822 requirements of a system. They feature in every decision made to 823 fulfill the systems requirements. Performance and scale are a complex 824 function of many things. Hence performance requirements cannot be 825 precisely quantified by a single number. This section lays out some 826 common sense guidelines that should be kept in mind while designing 827 the system from a scale and performance standpoint. 829 PS.1 The request-response MEP should be asynchronous. This ensures 830 that a system is not stuck waiting for a response and makes the 831 entire system more responsive and increases concurrency between 832 operations. 834 PS.2 When applicable, messages should carry application level cookies 835 that enable an application to quickly lookup the context 836 necessary to process a message. The management of the cookie is 837 the applications responsibility. 839 PS.3 The framework should allow for bulk operations which amortizes 840 the communication and messaging costs. 842 PS.4 Provide for a binary encoding option for messages between the 843 participants. 845 PS.5 Provide for a non-encrypted transport between the service 846 participants. 848 PS.6 Provide for message prioritization. 850 PS.7 Multiple operations could be completed with one transport 851 session. 853 PS.8 Keep the server as stateless with respect to the number and 854 location of each client. 856 PS.9 For notifications, support filtered subscription. 858 PS.10 If a client requires to re-synchronize state with the server, 859 device a mechanism to do this efficiently without transferring 860 all the state between them. 862 PS.11 Allow clients that perform infrequent operations to disconnect 863 their transport connection without cleaning up their state. 865 PS.12 Create the basic necessary mechanisms in the framework and 866 build everything else as a service if possible. 868 5.9 Availability Requirements 870 The ability of the system to withstand operational failures and 871 function in a predictable manner is called availability. A few 872 guidelines that are important are, 874 A.1 Provide a 'superuser' identity that is capable of changing 875 security policies, clearing state and perform other actions that 876 override client initiated actions in the system. 878 A.2 Handle session disconnection and client deaths gracefully. These 879 should have the least impact on the system. 881 A.3 Log client connections and disconnections and provide this as a 882 well known service to authenticated users. 884 A.4 Notify clients of message processing and other errors through 885 error codes in messages. 887 A.5 Have a mechanism to gracefully terminate the session between the 888 client and the server. 890 A.6 Provide a mechanism for authenticated clients to query the load 891 attributes of the system, both instantaneous and running average. 892 Provide this as a service. 894 5.10 Application Programmability Requirements 896 The framework should pay particular attention the the requirements of 897 application programmers. A well written framework should improve the 898 productivity of programmers and shorten the time to make an 899 application. This section has some issues to consider when devising 900 the framework from an applications standpoint. 902 AP.1 A client programming framework should allow applications writers 903 to focus on the app functionality rather than mechanisms required to 904 communicate with the server. 906 AP.2 The application once written to certain requirements should be 907 portable to other identical environments. The framework should 908 not have fine grained data access controls as this would lead to 909 a poorly written application with portability issues. 911 AP.3 The framework should be devised in a manner that it is possible 912 to automate code generation and constraint checking in popular 913 programming languages. Generated code can then be used readily by 914 application programmers instead of dealing with the nitty-gritties of 915 the system. 917 AP.4 Define a common repository for SDMs from which clients can 918 obtain the SDMs they are interested in and automatically generate 919 most of the boilerplate code. 921 AP.5 Provisions should be made for debugging & troubleshooting tools 922 that includes message trace, call traces, access to relevant 923 server traces and logs, packet decode tools to trace & decode 924 messages on the wire, consistency checkers of state inserted into 925 a server. 927 AP.6 The toolset should have a general portion (for common functions, 928 such as session management) and SDM-specific portions (for 929 example, a flag to control generation of debug code in code 930 generated for a particular SDM). 932 AP.7 The framework should define SDMs and MDMs in a language neutral 933 format so as to enable code generation in multiple programming 934 languages. 936 5.11 Operational Requirements 938 O.1 There is a need to identify operational performance parameters of 939 the system and provide mechanisms to retrieve them from a running 940 system. 942 O.2 Provide a way to upgrade a service independently of the other 943 services. This modularity allows uninterrupted operation of the 944 all but one service which is being upgraded. 946 O.3 Provide a detailed workflow for bringing about a new service. 947 This workflow will start with the need to introduce a new service and 948 address the following: How SDMs defined? Where are they 949 standardized? How are new entities (MEPs, transport, encoding) 950 introduced? What are the tools and workflow involved to develop and 951 operationalize a service. The intent is to introduce a level of 952 understanding about stakeholders responsibilities. 954 O.4 Provide mechanisms and methodologies to test a new service before 955 deployment. 957 6 Security Considerations 959 See "Security Requirements", section 5.7 above. 961 7 Acknowledgements 963 Thanks to the following people for reviewing and providing feedback: 964 Alexander Clemm, John McDowell. 966 8. References 968 8.1 Normative References 970 [IRS-FRMWK] A. Atlas, T. Nadeau, D. Ward, "Interface to the Routing 971 System Framework", draft-ward-irs-framework-00 973 Authors' Addresses 975 Rex Fernando, Ed. 976 170 W Tasman Dr, 977 San Jose, CA 95134 979 EMail: rex@cisco.com 981 Jan Medved 982 Cisco Systems 983 170 W Tasman Dr, 984 San Jose, CA 95134 986 Email: jmedved@cisco.com 988 David Ward 989 Cisco Systems 990 170 W Tasman Dr, 991 San Jose, CA 95134 993 Email: wardd@cisco.com 995 Alia Atlas 996 Juniper Networks 997 10 Technology park Drive 998 Westford, MA 01886 1000 Email: akatlas@juniper.net 1002 Bruno Rijsman 1003 Juniper Networks 1004 10 Technology Park Drive 1005 Westford, MA 01886 1007 Email: brijsman@juniper.net