idnits 2.17.1 draft-ietf-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 (December 11, 2014) is 3417 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-06 == Outdated reference: A later version (-11) exists of draft-ietf-i2rs-problem-statement-04 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: June 14, 2015 Cisco 6 December 11, 2014 8 Interface to the Routing System (I2RS) Traceability: Framework and 9 Information Model 10 draft-ietf-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 June 14, 2015. 42 Copyright Notice 44 Copyright (c) 2014 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 4. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 5. Information Model . . . . . . . . . . . . . . . . . . . . . . 4 64 5.1. I2RS Traceability Framework . . . . . . . . . . . . . . . 4 65 5.2. I2RS Trace Log Mandatory Fields . . . . . . . . . . . . . 5 66 5.3. End of Message Marker . . . . . . . . . . . . . . . . . . 7 67 5.4. I2RS Trace Log Extensibility and Optional Fields . . . . 7 68 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7 69 7. Operational Guidance . . . . . . . . . . . . . . . . . . . . 7 70 7.1. Trace Log Creation . . . . . . . . . . . . . . . . . . . 8 71 7.2. Trace Log Temporary Storage . . . . . . . . . . . . . . . 8 72 7.3. Trace Log Rotation . . . . . . . . . . . . . . . . . . . 8 73 7.4. Trace Log Retrieval . . . . . . . . . . . . . . . . . . . 8 74 7.4.1. Retrieval Via Syslog . . . . . . . . . . . . . . . . 9 75 7.4.2. Retrieval Via I2RS Information Collection . . . . . . 9 76 7.4.3. Retrieval Via I2RS Pub-Sub . . . . . . . . . . . . . 9 77 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 78 9. Security Considerations . . . . . . . . . . . . . . . . . . . 10 79 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 80 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 81 11.1. Normative References . . . . . . . . . . . . . . . . . . 10 82 11.2. Informative References . . . . . . . . . . . . . . . . . 11 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 85 1. Introduction 87 The architecture for the Interface to the Routing System 88 ([I-D.ietf-i2rs-architecture]) specifies that I2RS Clients wishing to 89 retrieve or change routing state on a routing element MUST 90 authenticate to an I2RS Agent. The I2RS Client will have a unique 91 identity it provides for authentication, and should provide another, 92 opaque identifier for applications (or actors) communicating through 93 it. The programming of routing state will produce a return code 94 containing the results of the specified operation and associated 95 reason(s) for the result. All of this is critical information to be 96 used for understanding the history of I2RS interactions. 98 This document describes use cases for I2RS traceability. Based on 99 these use cases, the document proposes an information model and 100 reporting requirements to provide for effective recording of I2RS 101 interactions. In this context, effective troubleshooting means being 102 able to identify what operation was performed by a specific I2RS 103 Client, what was the result of the operation, and when that operation 104 was performed. 106 Discussions about the retention of the data logged as part of I2RS 107 traceability, while important, are outside of the scope of this 108 document. 110 2. Terminology and Conventions 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 114 document are to be interpreted as described in [RFC2119]. 116 The architecture specification for I2RS [I-D.ietf-i2rs-architecture] 117 defines additional terms used in this document that are specific to 118 the I2RS domain, such as "I2RS Agent", "I2RS Client", etc. The 119 reader is expected to be familiar with the terminology and concepts 120 defined in [I-D.ietf-i2rs-architecture]. 122 The IP addresses used in the example in this document correspond to 123 the documentation address blocks 192.0.2.0/24 (TEST-NET-1), 124 198.51.100.0/24 (TEST-NET-2) and 203.0.113.0/24 (TEST-NET-3) as 125 described in [RFC5737]. 127 3. Motivation 129 As networks scale and policy becomes an increasingly important part 130 of the control plane that creates and maintains the forwarding state, 131 operational complexity increases as well. I2RS offers more granular 132 and coherent control over policy and control plane state, but it also 133 removes or reduces the locality of the policy that has been applied 134 to the control plane at any individual forwarding device. The 135 ability to automate and abstract even complex policy-based controls 136 highlights the need for an equally scalable traceability function to 137 provide event-level granularity of the routing system compliant with 138 the requirements of I2RS (Section 5 of 139 [I-D.ietf-i2rs-problem-statement]). 141 4. Use Cases 143 An obvious motivation for I2RS traceability is the need to 144 troubleshoot and identify root-causes of problems in these 145 increasingly complex routing systems. For example, since I2RS is a 146 high-throughput multi-channel, full duplex and highly responsive 147 interface, I2RS Clients may be performing a large number of 148 operations on I2RS Agents concurrently or at nearly the same time and 149 quite possibly in very rapid succession. As these many changes are 150 made, the network reacts accordingly. These changes might lead to a 151 race condition, performance issues, data loss, or disruption of 152 services. In order to isolate the root cause of these issues it is 153 critical that a network operator or administrator has visibility into 154 what changes were made via I2RS at a specific time. 156 Some network environments have strong auditing requirements for 157 configuration and runtime changes. Other environments have policies 158 that require saving logging information for operational or regulatory 159 compliance considerations. These requirements therefore demand that 160 I2RS provides an account of changes made to network element routing 161 systems. 163 As I2RS becomes increasingly pervasive in routing environments, a 164 traceability model offers significant advantages and facilitates the 165 following use cases: 167 o Automated event correlation, trend analysis, and anomaly 168 detection. 170 o Trace log storage for offline (manual or tools) analysis. 172 o Improved accounting of routing system transactions. 174 o Standardized structured data format for writing common tools. 176 o Common reference for automated testing and incident reporting. 178 o Real-time monitoring and troubleshooting. 180 o Enhanced network audit, management and forensic analysis 181 capabilities. 183 5. Information Model 185 5.1. I2RS Traceability Framework 187 This section describes a framework for I2RS traceability based on the 188 I2RS Architecture. Some notable elements on the architecture are 189 highlighted herein. 191 The interaction between the optional northbound actor, I2RS Client, 192 I2RS Agent, the Routing System and the data captured in the I2RS 193 trace log is shown in Figure 1. 195 +-------------+ 196 |Actor | 197 |.............| 198 | Actor ID | 199 +-------------+ 200 ^ 201 | 0 .. N 202 | 203 V 204 +-------------+ 205 |I2RS Client | 206 |.............| 207 | Client ID | 208 +-------------+ 209 ^ 210 | 1 .. N 211 | 212 V 213 +-------------+ +-----------------------------+ 214 |I2RS Agent |---------------->|Trace Log | 215 | | |.............................| 216 +-------------+ |Log Entry [1 .. N] | 217 ^ |.............................| 218 | |Timestamp | 219 | |Client ID | 220 | ^ |Actor ID | 221 Operation + | Result Code |Client Address | 222 Op Data | |Operation | 223 V | |Operation Data | 224 | |Result Code | 225 V |End Of Message | 226 +-------------+ +-----------------------------+ 227 |Routing | 228 |System | 229 +-------------+ 231 Figure 1: I2RS Interaction Trace Log Capture 233 5.2. I2RS Trace Log Mandatory Fields 235 In order to ensure that each I2RS interaction can be properly traced 236 back to the Client that made the request at a specific point in time, 237 the following information MUST be collected and stored by the Agent. 239 The list below describes the fields captured in the I2RS trace log. 241 Entry ID: This is a unique identifier for each entry in the I2RS 242 trace log. Since multiple operations can occur from the same 243 client at the same time, it is important to have an identifier 244 that can be unambiguously associated to a specific entry. 246 Timestamp: The specific time, adhering to [RFC3339] format, at 247 which the I2RS transaction occurred. Given that many I2RS 248 transactions can occur in rapid succession, the use of fractional 249 seconds MUST be used to provide adequate granularity. 251 Client Identifier: The I2RS Client identifier used to authenticate 252 the Client to the I2RS Agent. 254 Actor Identifier: This is an opaque identifier that may be known to 255 the Client from a northbound controlling application. This is 256 used to trace the northbound actor driving the actions of the 257 Client. The Client may not provide this identifier to the Agent 258 if there is no external actor driving the Client. However, this 259 field MUST be logged. If the Client does not provide an actor ID, 260 then the Agent MUST log an UNAVAILABLE value in the field. 262 Client Address: This is the network address of the client that 263 connected to the Agent. For example, this may be an IPv4 or IPv6 264 address. [Note: will I2RS support interactions that have no 265 network address? If so this field will need to be updated.] 267 Operation: This is the I2RS operation performed. For example, this 268 may be an add route operation if a route is being inserted into a 269 routing table. 271 Operation Data: This field comprises the data passed to the Agent 272 to complete the desired operation. For example, if the operation 273 is a route add operation, the Operation Data would include the 274 route prefix, prefix length, and next hop information to be 275 inserted as well as the specific routing table to which the route 276 will be added. The operation data can also include interface 277 information. Some operations may not provide operation data, and 278 in those cases this field MUST be logged as a NULL string. 280 Result Code: This field holds the result of the operation. In the 281 case of RIB operations, this MUST be the return code as specified 282 in Section 4 of [I-D.nitinb-i2rs-rib-info-model]. The operation 283 may not complete with a result code in the case of a timeout. If 284 the operation fails to complete, it MUST still log the attempted 285 operation with an appropriate result code (e.g., a result code 286 indicating a timeout). 288 End Of Message: Each log entry SHOULD have an appropriate End Of 289 Message (EOM) indicator. See section Section 5.3 below for more 290 details. 292 5.3. End of Message Marker 294 Because of variability within I2RS trace log fields, implementors 295 MUST use a format-appropriate end of message (EOM) indicator in order 296 to signify the end of a particular record. That is, regardless of 297 format, the I2RS trace log MUST provide a distinct way of 298 distinguishing between the end of one record and the beginning of 299 another. For example, in a linear formated log (similar to syslog) 300 the EOM marker may be a newline character. In an XML formated log, 301 the schema would provide for element tags that denote beginning and 302 end of records. In a JSON formated log, the syntax would provide 303 record separation (likely by comma-separated array elements). 305 5.4. I2RS Trace Log Extensibility and Optional Fields 307 [NOTE: This section is TBD based on further development of I2RS WG 308 milestones.] 310 6. Examples 312 Here is a proposed sample of what the fields might look like in an 313 I2RS trace log. This is only an early proposal. These values are 314 subject to change. 316 Entry ID: 1 317 Timestamp: 2013-09-03T12:00:01.21+00:00 318 Client ID: 5CEF1870-0326-11E2-A21F-0800200C9A66 319 Actor ID: com.example.RoutingApp 320 Client Address: 192.0.2.2 321 Operation: ROUTE_ADD 322 Operation Data: PREFIX 203.0.113.0 PREFIX-LEN 24 NEXT-HOP 323 198.51.100.1 324 Result Code: SUCCESS(0) 326 7. Operational Guidance 328 Specific operational procedures regarding temporary log storage, 329 rollover, retrieval, and access of I2RS trace logs is out of scope 330 for this document. Organizations employing I2RS trace logging are 331 responsible for establishing proper operational procedures that are 332 appropriately suited to their specific requirements and operating 333 environment. In this section we only provide fundamental and 334 generalized operational guidelines that are implementation- 335 independent. 337 7.1. Trace Log Creation 339 The I2RS Agent interacts with the Routing and Signaling functions of 340 the Routing Element. Since the I2RS Agent is responsible for 341 actually making the routing changes on the associated network device, 342 it creates and maintains a log of transactions that can be retrieved 343 to troubleshoot I2RS-related impact to the network. 345 7.2. Trace Log Temporary Storage 347 The trace information may be temporarily stored either in an in- 348 memory buffer or as a file local to the Agent. Care should be given 349 to the number of I2RS transactions expected on a given agent so that 350 the appropriate storage medium is used and to maximize the 351 effectiveness of the log while not impacting the performance and 352 health of the Agent. Section 7.3 talks about rotating the trace log 353 in order to preserve the transaction history without exhausting Agent 354 or network device resources. It is perfectly acceptable, therefore, 355 to use both an in-memory buffer for recent transactions while 356 rotating or archiving older transactions to a local file. 358 It is outside the scope of this document to specify the 359 implementation details (i.e., size, throughput, data protection, 360 privacy, etc.) for the physical storage of the I2RS log file. Data 361 retention policies of the I2RS traceability log is also outside the 362 scope of this document. 364 7.3. Trace Log Rotation 366 In order to prevent the exhaustion of resources on the I2RS Agent or 367 its associated network device, it is RECOMMENDED that the I2RS Agent 368 implements trace log rotation. The details on how this is achieved 369 are left to the implementation and outside the scope of this 370 document. However, it should be possible to do file rotation based 371 on either time or size of the current trace log. If file rollover is 372 supported, multiple archived log files should be supported in order 373 to maximize the troubleshooting and accounting benefits of the trace 374 log. 376 7.4. Trace Log Retrieval 378 Implementors are free to provide their own, proprietary interfaces 379 and develop custom tools to retrieve and display the I2RS trace log. 380 These may include the display of the I2RS trace log as Command Line 381 Interface (CLI) output. However, a key intention of defining this 382 information model is to establish an implementor-agnostic and 383 consistent interface to collect I2RS trace data. Correspondingly, 384 retrieval of the data should also be made implementor-agnostic. 386 The following three sections describe potential ways the trace log 387 can be accessed. At least one of these three MUST be used, with the 388 I2RS mechanisms being preferred as they are implementor-independent 389 approaches to retrieving the data. 391 7.4.1. Retrieval Via Syslog 393 The syslog protocol [RFC5424] is a standard way of sending event 394 notification messages from a host to a collector. However, the 395 protocol does not define any standard format for storing the 396 messages, and thus implementors of I2RS tracing would be left to 397 define their own format. So, while the data contained within the 398 syslog message would adhere to this information model, and may be 399 consumable by a human operator, it would not be easily parseable by a 400 machine. Therefore, syslog MAY be employed as a means of retrieving 401 or disseminating the I2RS trace log contents. 403 7.4.2. Retrieval Via I2RS Information Collection 405 Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture] 406 defines a mechanism for information collection. The information 407 collected includes obtaining a snapshot of a large amount of data 408 from the network element. It is the intent of I2RS to make this data 409 available in an implementor-agnostic fashion. Therefore, the I2RS 410 trace log SHOULD be made available via the I2RS information 411 collection mechanism either as a single snapshot or via a 412 subscription stream. 414 7.4.3. Retrieval Via I2RS Pub-Sub 416 Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture] 417 goes on to define a publish-subscribe mechanism for a feed of changes 418 happening within the I2RS layer. I2RS Agents SHOULD support 419 publishing I2RS trace log information to that feed as described in 420 that document. Subscribers would then receive a live stream of I2RS 421 interactions in trace log format and could flexibly choose to do a 422 number of things with the log messages. For example, the subscribers 423 could log the messages to a datastore, aggregate and summarize 424 interactions from a single client, etc. Using pub-sub for the 425 purpose of logging I2RS interactions augments the areas described by 426 [I-D.camwinget-i2rs-pubsub-sec]. The full range of potential 427 activites is virtually limitless and the details of how they are 428 performed are outside the scope of this document, however. 430 8. IANA Considerations 432 This document makes no request of IANA. 434 9. Security Considerations 436 The I2RS trace log, like any log file, reveals the state of the 437 entity producing it as well as the identifying information elements 438 and detailed interactions of the system containing it. The 439 information model described in this document does not itself 440 introduce any security issues, but it does define the set of 441 attributes that make up an I2RS log file. These attributes may 442 contain sensitive information and thus should adhere to the security, 443 privacy and permission policies of the organization making use of the 444 I2RS log file. 446 It is outside the scope of this document to specify how to protect 447 the stored log file, but it is expected that adequate precautions and 448 security best practices such as disk encryption, appropriately 449 restrictive file/directory permissions, suitable hardening and 450 physical security of logging entities, mutual authentication, 451 transport encryption, channel confidentiality, and channel integrity 452 if transferring log files. Additionally, the potentially sensitive 453 information contained in a log file SHOULD be adequately anonymized 454 or obfuscated by operators to ensure its privacy. 456 10. Acknowledgments 458 The authors would like to thank Alia Atlas for her initial feedback 459 and overall support for this work. Additionally, the authors 460 acknowledge Alvaro Retana, Russ White, Matt Birkner, Jeff Haas, Joel 461 Halpern and Dean Bogdanovich for their reviews, contributed text, and 462 suggested improvements to this document. 464 11. References 466 11.1. Normative References 468 [I-D.ietf-i2rs-architecture] 469 Atlas, A., Halpern, J., Hares, S., Ward, D., and T. 470 Nadeau, "An Architecture for the Interface to the Routing 471 System", draft-ietf-i2rs-architecture-06 (work in 472 progress), December 2014. 474 [I-D.ietf-i2rs-problem-statement] 475 Atlas, A., Nadeau, T., and D. Ward, "Interface to the 476 Routing System Problem Statement", draft-ietf-i2rs- 477 problem-statement-04 (work in progress), June 2014. 479 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 480 Requirement Levels", BCP 14, RFC 2119, March 1997. 482 11.2. Informative References 484 [I-D.camwinget-i2rs-pubsub-sec] 485 Beck, K., Cam-Winget, N., and D. McGrew, "Using the 486 Publish-Subscribe Model in the Interface to the Routing 487 System", draft-camwinget-i2rs-pubsub-sec-00 (work in 488 progress), July 2013. 490 [I-D.nitinb-i2rs-rib-info-model] 491 Bahadur, N., Folkes, R., Kini, S., and J. Medved, "Routing 492 Information Base Info Model", draft-nitinb-i2rs-rib-info- 493 model-02 (work in progress), August 2013. 495 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 496 Internet: Timestamps", RFC 3339, July 2002. 498 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, March 2009. 500 [RFC5737] Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks 501 Reserved for Documentation", RFC 5737, January 2010. 503 Authors' Addresses 505 Joe Clarke 506 Cisco Systems, Inc. 507 7200-12 Kit Creek Road 508 Research Triangle Park, NC 27709 509 US 511 Phone: +1-919-392-2867 512 Email: jclarke@cisco.com 514 Gonzalo Salgueiro 515 Cisco Systems, Inc. 516 7200-12 Kit Creek Road 517 Research Triangle Park, NC 27709 518 US 520 Email: gsalguei@cisco.com 521 Carlos Pignataro 522 Cisco Systems, Inc. 523 7200-12 Kit Creek Road 524 Research Triangle Park, NC 27709 525 US 527 Email: cpignata@cisco.com