idnits 2.17.1 draft-clarke-i2rs-traceability-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 has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 28, 2013) is 3856 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-15) exists of draft-ietf-i2rs-architecture-00 == Outdated reference: A later version (-11) exists of draft-ietf-i2rs-problem-statement-00 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 I2RS J. Clarke 3 Internet-Draft G. Salgueiro 4 Intended status: Informational C. Pignataro 5 Expires: April 01, 2014 Cisco 6 September 28, 2013 8 Interface to the Routing System (I2RS) Traceability: Framework and 9 Information Model 10 draft-clarke-i2rs-traceability-00 12 Abstract 14 This document describes a framework for traceability in the Interface 15 to the Routing System (I2RS) and information model for that 16 framework. It specifies the motivation, requirements, use cases, and 17 defines an information model for recording interactions between 18 elements implementing the I2RS protocol. This framework provides a 19 consistent tracing interface for components implementing the I2RS 20 architecture to record what was done, by which component, and when. 21 It aims to improve the management of I2RS implementations, and can be 22 used for troubleshooting, auditing, forensics, and accounting 23 purposes. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on April 01, 2014. 42 Copyright Notice 44 Copyright (c) 2013 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 3 61 3. Motivation and Use Cases . . . . . . . . . . . . . . . . . . 3 62 4. Information Model . . . . . . . . . . . . . . . . . . . . . . 4 63 4.1. I2RS Traceability Framework . . . . . . . . . . . . . . . 4 64 4.2. I2RS Trace Log Mandatory Fields . . . . . . . . . . . . . 5 65 4.3. I2RS Trace Log Extensibility and Optional Fields . . . . 6 66 4.4. I2RS Trace Log Syntax . . . . . . . . . . . . . . . . . . 6 67 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 6. Operational Guidance . . . . . . . . . . . . . . . . . . . . 8 69 6.1. Trace Log Creation . . . . . . . . . . . . . . . . . . . 8 70 6.2. Trace Log Temporary Storage . . . . . . . . . . . . . . . 8 71 6.3. Trace Log Rotation . . . . . . . . . . . . . . . . . . . 9 72 6.4. Trace Log Retrieval . . . . . . . . . . . . . . . . . . . 9 73 6.4.1. Retrieval Via Syslog . . . . . . . . . . . . . . . . 9 74 6.4.2. Retrieval Via I2RS Information Collection . . . . . . 9 75 6.4.3. Retrieval Via I2RS Pub-Sub . . . . . . . . . . . . . 10 76 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 77 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 78 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 79 9.1. Normative References . . . . . . . . . . . . . . . . . . 10 80 9.2. Informative References . . . . . . . . . . . . . . . . . 11 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 83 1. Introduction 85 The architecture for the Interface to the Routing System 86 ([I-D.ietf-i2rs-architecture]) specifies that I2RS Clients wishing to 87 retrieve or change routing state on a routing element MUST 88 authenticate to an I2RS Agent. The I2RS Client will have a unique 89 identity it provides for authentication, and should provide another, 90 opaque identifier for applications (or actors) communicating through 91 it. The programming of routing state will produce in a return code 92 containing the results of the specified operation and associated 93 reason(s) for the result. All of this is critical information to be 94 used for understanding the history of I2RS interactions. 96 This document specifies requirements, use cases, and describes the 97 information model for traceability attributes that must be collected 98 and logged by I2RS Agents in order to effectively record I2RS 99 interactions. In this context, effective troubleshooting means being 100 able to identify what operation was performed by a specific I2RS 101 Client, what was the result of the operation, and when that operation 102 was performed. 104 Discussions about the retention of the data logged as part of I2RS 105 traceability, while important, are outside of the scope of this 106 document. 108 2. Terminology and Conventions 110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 112 document are to be interpreted as described in [RFC2119]. 114 The architecture specification for I2RS [I-D.ietf-i2rs-architecture] 115 defines additional terms used in this document that are specific to 116 the I2RS domain, such as "I2RS Agent", "I2RS Client", etc. The 117 reader is expected to be familiar with the terminology and concepts 118 defined in [I-D.ietf-i2rs-architecture]. 120 The IP addresses used in the example in this document correspond to 121 the documentation address blocks 192.0.2.0/24 (TEST-NET-1), 122 198.51.100.0/24 (TEST-NET-2) and 203.0.113.0/24 (TEST-NET-3) as 123 described in [RFC5737]. 125 3. Motivation and Use Cases 127 As networks grow, so too does the scale and complexity of routing 128 systems. I2RS offers a standard, programmatic interface allowing 129 improved automation and more granular control over an increasingly 130 dynamic routing and signaling state. This ability to automate even 131 complex policy-based controls highlights the need for an equally 132 scalable traceability function to provide event-level granularity of 133 the routing system compliant with the requirements of I2RS (Section 5 134 of [I-D.ietf-i2rs-problem-statement]). 136 An obvious motivation for I2RS traceability is the need to 137 troubleshoot and identify root-causes of problems in these 138 increasingly complex routing systems. For example, since I2RS is a 139 high-throughput multi-channel, full duplex and highly responsive 140 interface, I2RS Clients may be performing a large number of 141 operations on I2RS Agents concurrently or at nearly the same time and 142 quite possibly in very rapid succession. As these many changes are 143 made, the network reacts accordingly. These changes might lead to a 144 race condition, performance issues, data loss, or disruption of 145 services. In order to isolate the root cause of these issues it is 146 critical that a network operator or administrator has visibility into 147 what changes were made via I2RS at a specific time. 149 Some network environments have strong auditing requirements for 150 configuration and runtime changes. Other environments have internal 151 policies to save logging information for operational considerations. 152 These requirements therefore demand that I2RS provides an account of 153 changes made to network element routing systems. 155 As I2RS becomes increasingly pervasive in routing environments, a 156 traceability model offers significant advantages and facilitates the 157 following use cases: 159 o Automated event correlation, trend analysis, and anomaly 160 detection. 162 o Trace log storage for offline (manual or tools) analysis. 164 o Improved accounting of routing system transactions. 166 o Standardized structured data format for writing common tools. 168 o Common reference for automated testing and incident reporting. 170 o Real-time monitoring and troubleshooting. 172 o Enhanced network audit, management and forensic analysis 173 capabilities. 175 4. Information Model 177 4.1. I2RS Traceability Framework 179 This section describes a framework for I2RS traceability based on the 180 I2RS Architecture. Some notable elements on the architecture are 181 highlighted herein. 183 The interaction between the optional northbound actor, I2RS Client, 184 I2RS Agent, the Routing System and the data captured in the I2RS 185 trace log is shown in Figure 1. 187 +-------------+ 188 |Actor | 189 |.............| 190 | Actor ID | 191 +-------------+ 192 ^ 193 : 194 : 195 V 196 +-------------+ 197 |I2RS Client | 198 |.............| 199 | Client ID | 200 +-------------+ 201 ^ 202 | 203 | 204 V 205 +-------------+ +-----------------------------+ 206 |I2RS Agent |---------------->|Trace Log | 207 | | |.............................| 208 +-------------+ |Timestamp | 209 ^ |Client ID | 210 | ^ |Actor ID | 211 Operation + | Result Code |Client Address | 212 Op Data | |Operation | 213 V | |Operation Data | 214 V |Result Code | 215 +-------------+ +-----------------------------+ 216 |Routing | 217 |System | 218 +-------------+ 220 Figure 1: I2RS Interaction Trace Log Capture 222 4.2. I2RS Trace Log Mandatory Fields 224 In order to ensure that each I2RS interaction can be properly traced 225 back to the Client that made the request at a specific point in time, 226 the following information MUST be collected and stored by the Agent. 228 The list below describes the fields captured in the I2RS trace log. 230 Timestamp: The specific time, adhering to [RFC3339] format, at 231 which the I2RS transaction occurred. Given that many I2RS 232 transactions can occur in rapid succession, the use of fractional 233 seconds MUST be used to provide adequate granularity. 235 Client Identifier: The I2RS Client identifier used to authenticate 236 the Client to the I2RS Agent. 238 Actor Identifier: This is an opaque identifier that may be known to 239 the Client from a northbound controlling application. This is 240 used to trace the northbound actor driving the actions of the 241 Client. The Client may not provide this identifier to the Agent 242 if there is no external actor driving the Client. However, this 243 field MUST be logged. If the Client does not provide an actor ID, 244 then the Agent MUST log an empty field. 246 Client Address: This is the network address of the client that 247 connected to the Agent. For example, this may be an IPv4 or IPv6 248 address. [Note: will I2RS support interactions that have no 249 network address? If so this field will need to be updated.] 251 Operation: This is the I2RS operation performed. For example, this 252 may be an add route operation if a route is being inserted into a 253 routing table. 255 Operation Data: This field comprises the data passed to the Agent 256 to complete the desired operation. For example, if the operation 257 is a route add operation, the Operation Data would include the 258 route prefix, prefix length, and next hop information to be 259 inserted as well as the specific routing table to which the route 260 will be added. The operation data can also include interface 261 information. Some operations MAY not provide operation data, and 262 in those cases this field MUST be logged as a NULL string. 264 Result Code: This field holds the result of the operation. In the 265 case of RIB operations, this MUST be the return code as specified 266 in Section 4 of [I-D.nitinb-i2rs-rib-info-model]. The operation 267 may not complete with a result code in the case of a timeout. If 268 the operation fails to complete, it MUST still log the attempted 269 operation with an appropriate result code (e.g., a result code 270 indicating a timeout). 272 4.3. I2RS Trace Log Extensibility and Optional Fields 274 [NOTE: This section is TBD based on further development of I2RS WG 275 milestones.] 277 4.4. I2RS Trace Log Syntax 279 The following describes the trace log information model using 280 Augmented Backus-Naur Form (ABNF) syntax [RFC5234]: 282 i2rs-trace-log = timestamp client-id actor-id client-addr operation 283 operation-data result-code 284 client-id = uuid 285 actor-id = byte-string 286 byte-string = *( %x01-09 / %x0B-0C / %x0E-FF ) 287 ; any byte except NUL, CR or LF 288 client-addr = IP-literal / IPv4address 289 operation = ALPHA *( ALPHA / "_" / "-" / "(" / ")" ) 290 operation-data = *VCHAR 291 result-code = 1*( ALPHA / DIGIT / "-" / "_" / "(" / ")" ) 293 The ABNF syntax rules , , and 294 are specified in [RFC3986]. The core rules , and 295 are used as described in Appendix B of [RFC5234]. 297 Here, is specified in [RFC4122]. The idea of using a UUID for 298 the Client identifier ensures the ID is unique not just in the scope 299 of the current I2RS Agent, but across Agents as well. This ensures 300 that two clients that are unaware of each other will not allocate the 301 same Client ID. That does not preclude two Clients acting as one for 302 purposes of high availability from sharing the same UUID as generated 303 by one one of the Clients. [Note: the format of the Client ID has 304 not yet been decided by the I2RS WG. This is subject to change.] 306 The field is defined in [RFC3339]. As stated in 307 Section 4.2 the fractional second format MUST be used to provide 308 proper granularity. 310 The values for , and are 311 suggestions as the protocol has not been defined yet. By making 312 these human-readable (as opposed to opcodes) the log becomes more 313 easily consumable by operators and administrators trying to 314 troubleshoot issues relating to I2RS. Even in cases where the 315 operations or codes might appear as opcodes on the wire, their 316 textual translations MUST be included in the log. The opcodes 317 themselves MAY appear in parentheses after the textual 318 representation. 320 5. Examples 322 Here is a proposed sample of what the fields might look like in an 323 I2RS trace log. This is only an early proposal. These values are 324 subject to change. 326 Timestamp: 2013-09-03T12:00:01.21+00:00 327 Client ID: 5CEF1870-0326-11E2-A21F-0800200C9A66 328 Actor ID: com.example.RoutingApp 329 Client Address: 192.0.2.2 330 Operation: ROUTE_ADD 331 Operation Data: PREFIX 203.0.113.0 PREFIX-LEN 24 NEXT-HOP 332 198.51.100.1 333 Result Code: SUCCESS(0) 335 6. Operational Guidance 337 Specific operational procedures regarding temporary log storage, 338 rollover, retrieval, and access of I2RS trace logs is out of scope 339 for this document. Organizations employing I2RS trace logging are 340 responsible for establishing proper operational procedures that are 341 appropriately suited to their specific requirements and operating 342 environment. In this section we only provide fundamental and 343 generalized operational guidelines that are implementation- 344 independent. 346 6.1. Trace Log Creation 348 The I2RS Agent interacts with the Routing and Signaling functions of 349 the Routing Element. Since the I2RS Agent is responsible for 350 actually making the routing changes on the associated network device, 351 it creates and maintains a log of transactions that can be retrieved 352 to troubleshoot I2RS-related impact to the network. 354 6.2. Trace Log Temporary Storage 356 The trace information may be temporarily stored either in an in- 357 memory buffer or as a file local to the Agent. Care should be given 358 to the number of I2RS transactions expected on a given agent so that 359 the appropriate storage medium is used and to maximize the 360 effectiveness of the log while not impacting the performance and 361 health of the Agent. Section 6.3 talks about rotating the trace log 362 in order to preserve the transaction history without exhausting Agent 363 or network device resources. It is perfectly acceptable, therefore, 364 to use both an in-memory buffer for recent transactions while 365 rotating or archiving older transactions to a local file. 367 It is outside the scope of this document to specify the 368 implementation details (i.e., size, throughput, data protection, 369 privacy, etc.) for the physical storage of the I2RS log file. Data 370 retention policies of the I2RS traceability log is also outside the 371 scope of this document. 373 6.3. Trace Log Rotation 375 In order to prevent the exhaustion of resources on the I2RS Agent or 376 its associated network device, the I2RS trace log implementation MAY 377 choose to implement a configurable rotation schedule. It SHOULD be 378 possible to do file rotation based on either time or size of the 379 current trace log. If file rollover is supported, multiple archived 380 log files SHOULD be supported in order to maximize the 381 troubleshooting and accounting benefits of the trace log. 383 6.4. Trace Log Retrieval 385 Implementors are free to provide their own, proprietary interfaces 386 and develop custom tools to retrieve and display the I2RS trace log. 387 These may include the display of the I2RS trace log as Command Line 388 Interface (CLI) output. However, a key intention of defining this 389 information model is to establish an implementor-agnostic and 390 consistent interface to collect I2RS trace data. Correspondingly, 391 retrieval of the data should also be made implementor-agnostic. 393 The following three sections describe potential ways the trace log 394 can be accessed. At least one of these three MUST be used, with the 395 I2RS mechanisms being preferred as they are implementor-independent 396 approaches to retrieving the data. 398 6.4.1. Retrieval Via Syslog 400 The syslog protocol [RFC5424] is a standard way of sending event 401 notification messages from a host to a collector. However, the 402 protocol does not define any standard format for storing the 403 messages, and thus implementors of I2RS tracing would be left to 404 define their own format. So, while the data contained within the 405 syslog message would adhere to this information model, and may be 406 consumable by a human operator, it would not be easily parseable by a 407 machine. Therefore, syslog MAY be employed as a means of retrieving 408 or disseminating the I2RS trace log contents. 410 6.4.2. Retrieval Via I2RS Information Collection 412 Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture] 413 defines a mechanism for information collection. The information 414 collected includes obtaining a snapshot of a large amount of data 415 from the network element. It is the intent of I2RS to make this data 416 available in an implementor-agnostic fashion. Therefore, the I2RS 417 trace log SHOULD be made available via the I2RS information 418 collection mechanism either as a single snapshot or via a 419 subscription stream. 421 6.4.3. Retrieval Via I2RS Pub-Sub 423 Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture] 424 goes on to define a publish-subscribe mechanism for a feed of changes 425 happening within the I2RS layer. I2RS Agents SHOULD support 426 publishing I2RS trace log information to that feed as described in 427 that document. Subscribers would then receive a live stream of I2RS 428 interactions in trace log format and could flexibly choose to do a 429 number of things with the log messages. For example, the subscribers 430 could log the messages to a datastore, aggregate and summarize 431 interactions from a single client, etc. Using pub-sub for the 432 purpose of logging I2RS interactions augments the areas described by 433 [I-D.camwinget-i2rs-pubsub-sec]. The full range of potential 434 activites is virtually limitless and the details of how they are 435 performed are outside the scope of this document, however. 437 7. IANA Considerations 439 This document makes no request of IANA. 441 8. Security Considerations 443 The I2RS trace log, like any log file, reveals the state of the 444 entity producing it as well as the identifying information elements 445 and detailed interactions of the system containing it. The 446 information model described in this document does not itself 447 introduce any security issues, but it does define the set of 448 attributes that make up an I2RS log file. These attributes may 449 contain sensitive information and thus should adhere to the security, 450 privacy and permission policies of the organization making use of the 451 I2RS log file. 453 It is outside the scope of this document to specify how to protect 454 the stored log file, but it is expected that adequate precautions and 455 security best practices such as disk encryption, appropriately 456 restrictive file/directory permissions, suitable hardening and 457 physical security of logging entities, mutual authentication, 458 transport encryption, channel confidentiality, and channel integrity 459 if transferring log files. Additionally, the potentially sensitive 460 information contained in a log file SHOULD be adequately anonymized 461 or obfuscated by operators to ensure its privacy. 463 9. References 465 9.1. Normative References 467 [I-D.ietf-i2rs-architecture] 468 Atlas, A., Halpern, J., Hares, S., Ward, D., and T. 469 Nadeau, "An Architecture for the Interface to the Routing 470 System", draft-ietf-i2rs-architecture-00 (work in 471 progress), August 2013. 473 [I-D.ietf-i2rs-problem-statement] 474 Atlas, A., Nadeau, T., and D. Ward, "Interface to the 475 Routing System Problem Statement", draft-ietf-i2rs- 476 problem-statement-00 (work in progress), August 2013. 478 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 479 Requirement Levels", BCP 14, RFC 2119, March 1997. 481 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 482 Resource Identifier (URI): Generic Syntax", STD 66, RFC 483 3986, January 2005. 485 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 486 Unique IDentifier (UUID) URN Namespace", RFC 4122, July 487 2005. 489 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 490 Specifications: ABNF", STD 68, RFC 5234, January 2008. 492 9.2. Informative References 494 [I-D.camwinget-i2rs-pubsub-sec] 495 Beck, K., Cam-Winget, N., and D. McGrew, "Using the 496 Publish-Subscribe Model in the Interface to the Routing 497 System", draft-camwinget-i2rs-pubsub-sec-00 (work in 498 progress), July 2013. 500 [I-D.nitinb-i2rs-rib-info-model] 501 Bahadur, N., Folkes, R., Kini, S., and J. Medved, "Routing 502 Information Base Info Model", draft-nitinb-i2rs-rib-info- 503 model-02 (work in progress), August 2013. 505 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 506 Internet: Timestamps", RFC 3339, July 2002. 508 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, March 2009. 510 [RFC5737] Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks 511 Reserved for Documentation", RFC 5737, January 2010. 513 Authors' Addresses 514 Joe Clarke 515 Cisco Systems, Inc. 516 7200-12 Kit Creek Road 517 Research Triangle Park, NC 27709 518 US 520 Phone: +1-919-392-2867 521 Email: jclarke@cisco.com 523 Gonzalo Salgueiro 524 Cisco Systems, Inc. 525 7200-12 Kit Creek Road 526 Research Triangle Park, NC 27709 527 US 529 Email: gsalguei@cisco.com 531 Carlos Pignataro 532 Cisco Systems, Inc. 533 7200-12 Kit Creek Road 534 Research Triangle Park, NC 27709 535 US 537 Email: cpignata@cisco.com