idnits 2.17.1 draft-clarke-i2rs-traceability-02.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 == Line 335 has weird spacing: '...on-data ope...' -- The document date (June 7, 2014) is 3610 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 ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) Summary: 1 error (**), 0 flaws (~~), 4 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: December 9, 2014 Cisco 6 June 7, 2014 8 Interface to the Routing System (I2RS) Traceability: Framework and 9 Information Model 10 draft-clarke-i2rs-traceability-02 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 December 9, 2014. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 5. Information Model . . . . . . . . . . . . . . . . . . . . . . 4 64 5.1. I2RS Traceability Framework . . . . . . . . . . . . . . . 5 65 5.2. I2RS Trace Log Mandatory Fields . . . . . . . . . . . . . 6 66 5.3. End of Message Marker . . . . . . . . . . . . . . . . . . 8 67 5.4. I2RS Trace Log Extensibility and Optional Fields . . . . 8 68 5.5. I2RS Trace Log Syntax . . . . . . . . . . . . . . . . . . 8 69 5.5.1. Structure of the I2RS Trace Log . . . . . . . . . . . 8 70 5.5.2. I2RS Trace Log Yang Module . . . . . . . . . . . . . 9 71 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 14 72 7. Operational Guidance . . . . . . . . . . . . . . . . . . . . 15 73 7.1. Trace Log Creation . . . . . . . . . . . . . . . . . . . 15 74 7.2. Trace Log Temporary Storage . . . . . . . . . . . . . . . 15 75 7.3. Trace Log Rotation . . . . . . . . . . . . . . . . . . . 16 76 7.4. Trace Log Retrieval . . . . . . . . . . . . . . . . . . . 16 77 7.4.1. Retrieval Via Syslog . . . . . . . . . . . . . . . . 16 78 7.4.2. Retrieval Via I2RS Information Collection . . . . . . 16 79 7.4.3. Retrieval Via I2RS Pub-Sub . . . . . . . . . . . . . 17 80 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 81 9. Security Considerations . . . . . . . . . . . . . . . . . . . 17 82 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 83 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 84 11.1. Normative References . . . . . . . . . . . . . . . . . . 18 85 11.2. Informative References . . . . . . . . . . . . . . . . . 18 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 88 1. Introduction 90 The architecture for the Interface to the Routing System 91 ([I-D.ietf-i2rs-architecture]) specifies that I2RS Clients wishing to 92 retrieve or change routing state on a routing element MUST 93 authenticate to an I2RS Agent. The I2RS Client will have a unique 94 identity it provides for authentication, and should provide another, 95 opaque identifier for applications (or actors) communicating through 96 it. The programming of routing state will produce a return code 97 containing the results of the specified operation and associated 98 reason(s) for the result. All of this is critical information to be 99 used for understanding the history of I2RS interactions. 101 This document describes use cases for I2RS traceability. Based on 102 these use cases, the document proposes an information model and 103 reporting requirements to provide for effective recording of I2RS 104 interactions. In this context, effective troubleshooting means being 105 able to identify what operation was performed by a specific I2RS 106 Client, what was the result of the operation, and when that operation 107 was performed. 109 Discussions about the retention of the data logged as part of I2RS 110 traceability, while important, are outside of the scope of this 111 document. 113 2. Terminology and Conventions 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 117 document are to be interpreted as described in [RFC2119]. 119 The architecture specification for I2RS [I-D.ietf-i2rs-architecture] 120 defines additional terms used in this document that are specific to 121 the I2RS domain, such as "I2RS Agent", "I2RS Client", etc. The 122 reader is expected to be familiar with the terminology and concepts 123 defined in [I-D.ietf-i2rs-architecture]. 125 The IP addresses used in the example in this document correspond to 126 the documentation address blocks 192.0.2.0/24 (TEST-NET-1), 127 198.51.100.0/24 (TEST-NET-2) and 203.0.113.0/24 (TEST-NET-3) as 128 described in [RFC5737]. 130 3. Motivation 132 As networks scale and policy becomes an increasingly important part 133 of the control plane that creates and maintains the forwarding state, 134 operational complexity increases as well. I2RS offers more granular 135 and coherent control over policy and control plane state, but it also 136 removes or reduces the locality of the policy that has been applied 137 to the control plane at any individual forwarding device. The 138 ability to automate and abstract even complex policy-based controls 139 highlights the need for an equally scalable traceability function to 140 provide event-level granularity of the routing system compliant with 141 the requirements of I2RS (Section 5 of 142 [I-D.ietf-i2rs-problem-statement]). 144 4. Use Cases 146 An obvious motivation for I2RS traceability is the need to 147 troubleshoot and identify root-causes of problems in these 148 increasingly complex routing systems. For example, since I2RS is a 149 high-throughput multi-channel, full duplex and highly responsive 150 interface, I2RS Clients may be performing a large number of 151 operations on I2RS Agents concurrently or at nearly the same time and 152 quite possibly in very rapid succession. As these many changes are 153 made, the network reacts accordingly. These changes might lead to a 154 race condition, performance issues, data loss, or disruption of 155 services. In order to isolate the root cause of these issues it is 156 critical that a network operator or administrator has visibility into 157 what changes were made via I2RS at a specific time. 159 Some network environments have strong auditing requirements for 160 configuration and runtime changes. Other environments have policies 161 that require saving logging information for operational or regulatory 162 compliance considerations. These requirements therefore demand that 163 I2RS provides an account of changes made to network element routing 164 systems. 166 As I2RS becomes increasingly pervasive in routing environments, a 167 traceability model offers significant advantages and facilitates the 168 following use cases: 170 o Automated event correlation, trend analysis, and anomaly 171 detection. 173 o Trace log storage for offline (manual or tools) analysis. 175 o Improved accounting of routing system transactions. 177 o Standardized structured data format for writing common tools. 179 o Common reference for automated testing and incident reporting. 181 o Real-time monitoring and troubleshooting. 183 o Enhanced network audit, management and forensic analysis 184 capabilities. 186 5. Information Model 187 5.1. I2RS Traceability Framework 189 This section describes a framework for I2RS traceability based on the 190 I2RS Architecture. Some notable elements on the architecture are 191 highlighted herein. 193 The interaction between the optional northbound actor, I2RS Client, 194 I2RS Agent, the Routing System and the data captured in the I2RS 195 trace log is shown in Figure 1. 197 +-------------+ 198 |Actor | 199 |.............| 200 | Actor ID | 201 +-------------+ 202 ^ 203 | 0 .. N 204 | 205 V 206 +-------------+ 207 |I2RS Client | 208 |.............| 209 | Client ID | 210 +-------------+ 211 ^ 212 | 1 .. N 213 | 214 V 215 +-------------+ +-----------------------------+ 216 |I2RS Agent |---------------->|Trace Log | 217 | | |.............................| 218 +-------------+ |Log Entry [1 .. N] | 219 ^ |.............................| 220 | |Timestamp | 221 | |Client ID | 222 | ^ |Actor ID | 223 Operation + | Result Code |Client Address | 224 Op Data | |Operation | 225 V | |Operation Data | 226 | |Result Code | 227 V |End Of Message | 228 +-------------+ +-----------------------------+ 229 |Routing | 230 |System | 231 +-------------+ 233 Figure 1: I2RS Interaction Trace Log Capture 235 5.2. I2RS Trace Log Mandatory Fields 237 In order to ensure that each I2RS interaction can be properly traced 238 back to the Client that made the request at a specific point in time, 239 the following information MUST be collected and stored by the Agent. 241 The list below describes the fields captured in the I2RS trace log. 243 Entry ID: This is a unique identifier for each entry in the I2RS 244 trace log. Since multiple operations can occur from the same 245 client at the same time, it is important to have an identifier 246 that can be unambiguously associated to a specific entry. 248 Timestamp: The specific time, adhering to [RFC3339] format, at 249 which the I2RS transaction occurred. Given that many I2RS 250 transactions can occur in rapid succession, the use of fractional 251 seconds MUST be used to provide adequate granularity. 253 Client Identifier: The I2RS Client identifier used to authenticate 254 the Client to the I2RS Agent. 256 Actor Identifier: This is an opaque identifier that may be known to 257 the Client from a northbound controlling application. This is 258 used to trace the northbound actor driving the actions of the 259 Client. The Client may not provide this identifier to the Agent 260 if there is no external actor driving the Client. However, this 261 field MUST be logged. If the Client does not provide an actor ID, 262 then the Agent MUST log an UNAVAILABLE value in the field. 264 Client Address: This is the network address of the client that 265 connected to the Agent. For example, this may be an IPv4 or IPv6 266 address. [Note: will I2RS support interactions that have no 267 network address? If so this field will need to be updated.] 269 Operation: This is the I2RS operation performed. For example, this 270 may be an add route operation if a route is being inserted into a 271 routing table. 273 Operation Data: This field comprises the data passed to the Agent 274 to complete the desired operation. For example, if the operation 275 is a route add operation, the Operation Data would include the 276 route prefix, prefix length, and next hop information to be 277 inserted as well as the specific routing table to which the route 278 will be added. The operation data can also include interface 279 information. Some operations may not provide operation data, and 280 in those cases this field MUST be logged as a NULL string. 282 Result Code: This field holds the result of the operation. In the 283 case of RIB operations, this MUST be the return code as specified 284 in Section 4 of [I-D.nitinb-i2rs-rib-info-model]. The operation 285 may not complete with a result code in the case of a timeout. If 286 the operation fails to complete, it MUST still log the attempted 287 operation with an appropriate result code (e.g., a result code 288 indicating a timeout). 290 End Of Message: Each log entry SHOULD have an appropriate End Of 291 Message (EOM) indicator. See section Section 5.3 below for more 292 details. 294 5.3. End of Message Marker 296 Because of variability within I2RS trace log fields, implementors 297 MUST use a format-appropriate end of message (EOM) indicator in order 298 to signify the end of a particular record. That is, regardless of 299 format, the I2RS trace log MUST provide a distinct way of 300 distinguishing between the end of one record and the beginning of 301 another. For example, in a linear formated log (similar to syslog) 302 the EOM marker may be a newline character. In an XML formated log, 303 the schema would provide for element tags that denote beginning and 304 end of records. In a JSON formated log, the syntax would provide 305 record separation (likely by comma-separated array elements). 307 5.4. I2RS Trace Log Extensibility and Optional Fields 309 [NOTE: This section is TBD based on further development of I2RS WG 310 milestones.] 312 5.5. I2RS Trace Log Syntax 314 The following describes the trace log information model using the 315 YANG modeling language [RFC6020]. 317 5.5.1. Structure of the I2RS Trace Log 319 The structure of the I2RS traceability model, as later defined in the 320 YANG module "i2rs-trace-log", is depicted in the following diagram. 321 This tree representation illustrates the structure of I2RS Trace Log 322 YANG model and does not depict all definitions; it is merely intended 323 to illustrate the overall structure. 325 module: i2rs-trace-log 326 +--rw i2rs-trace-log 327 +--rw log-enable? boolean 328 +--ro log-entry* [log-entry-id] 329 +--ro log-entry-id log-entry-id 330 +--ro timestamp timestamp 331 +--ro client-id client-id 332 +--ro actor-id actor-id 333 +--ro client-addr client-addr 334 +--ro operation operation 335 +--ro operation-data operation-data 336 +--ro result-code result-code 338 The idea of using a UUID for the Client identifier ensures the ID is 339 unique not just in the scope of the current I2RS Agent, but across 340 Agents as well. This ensures that two clients that are unaware of 341 each other will not allocate the same Client ID. That does not 342 preclude two Clients acting as one for purposes of high availability 343 from sharing the same UUID as generated by one one of the Clients. 345 The "timestamp" field is defined in [RFC3339]. As stated in 346 Section 5.2 the fractional second format MUST be used to provide 347 proper granularity. 349 The values for "operation", "operation-data" and "result-code" are 350 suggestions as the protocol has not been defined yet. By making 351 these human-readable (as opposed to opcodes) the log becomes more 352 easily consumable by operators and administrators trying to 353 troubleshoot issues relating to I2RS. Even in cases where the 354 operations or codes might appear as opcodes on the wire, their 355 textual translations MUST be included in the log. The opcodes 356 themselves MAY appear in parentheses after the textual 357 representation. 359 5.5.2. I2RS Trace Log Yang Module 361 The I2RS traceability model is defined in the following YANG module. 363 This YANG module imports typedefs from [RFC6021]. 365 366 file "i2rs-trace-log@2014-06-06.yang" 367 module i2rs-trace-log { 368 yang-version 1; 369 namespace "urn:TBD:params:xml:ns:yang:i2rs:trace-log"; 370 // This namespace should be considered with other I2RS YANG 371 // models. 372 prefix i2rslog; 374 import ietf-yang-types { 375 prefix "yang"; 376 } 378 import ietf-inet-types { 379 prefix "inet"; 380 } 382 organization "TBD"; 384 contact 385 "Joe Clarke jclarke@cisco.com 386 Gonzalo Salgueiro gsalguei@cisco.com 387 Carlos Pignataro cpignata@cisco.com"; 389 description 390 "This module defines the model for I2RS traceability 391 based on the I2RS architecture as defined in 392 draft-ietf-i2rs-architecture. 394 Copyright (c) 2014 IETF Trust and the persons identified as 395 authors of the code. All rights reserved. 397 Redistribution and use in source and binary forms, with or 398 without modification, is permitted pursuant to, and subject 399 to the license terms contained in, the Simplified BSD License 400 set forth in Section 4.c of the IETF Trust's Legal Provisions 401 Relating to IETF Documents 402 (http://trustee.ietf.org/license-info)."; 404 reference 405 "draft-ietf-i2rs-architecture: An Architecture for the 406 Interface to the Routing System"; 408 revision "2014-06-03" { 409 description "Initial revision"; 410 reference "TBD"; 411 } 413 typedef log-entry-id { 414 type uint64; 415 description 416 "A unique identifier for I2RS log entries."; 417 } 419 typedef timestamp { 420 type yang:date-and-time; 421 description 422 "Timestamp for I2RS transactions."; 423 } 425 typedef client-id { 426 type yang:uuid; 427 description 428 "The I2RS Client identifier used to authenticate 429 the Client to the I2RS Agent."; 430 } 432 typedef actor-id { 433 type union { 434 type string { 435 pattern "[^\r\n]+"; 436 } 437 type enumeration { 438 enum UNAVAILABLE { 439 description 440 "The Actor ID was not 441 specified by the Client."; 442 } 443 } 444 } 445 description 446 "Identifier used to trace the northbound actor 447 driving the actions of the Client."; 448 } 450 typedef client-addr { 451 type inet:ip-address; 452 description 453 "IP address of the client that connected to the 454 Agent."; 455 } 457 typedef operation { 458 type string { 459 pattern "[a-zA-Z] [a-zA-Z_\-\(\)]*"; 460 } 461 description 462 "This is the I2RS operation performed."; 463 } 465 typedef operation-data { 466 type union { 467 type string; 468 type enumeration { 469 enum NULL { 470 description 471 "No additional operation 472 data was required."; 473 } 474 } 475 } 476 description 477 "Data passed to the Agent to complete the desired 478 operation."; 479 } 481 typedef result-code { 482 type string { 483 pattern "[a-zA-Z0-9_\-\(\)]+"; 484 } 485 description 486 "Result code for the operation."; 487 } 489 container i2rs-trace-log { 490 description 491 "This is the model for I2RS traceability. An 492 I2RS log is comprised of the following mandatory 493 fields. Each field MUST be identified by a unique 494 log-entry-id."; 495 leaf log-enable { 496 type boolean; 497 default "true"; 498 description 499 "Enable/Disable I2RS logging."; 500 } 501 list log-entry { 502 key "log-entry-id"; 503 config false; 504 description 505 "Each element in an I2RS trace log is 506 discrete and identified by its unique log 507 entry ID."; 508 leaf log-entry-id { 509 type log-entry-id; 510 config false; 511 description 512 "This is a unique identifier for 513 each entry in the I2RS trace log. 514 Since multiple operations can occur 515 from the same client at the same 516 time, it is important to have an 517 identifier that can be unambiguously 518 associated to a specific entry."; 519 } 520 leaf timestamp { 521 type timestamp; 522 config false; 523 mandatory true; 524 description 525 "The specific time, adhering to 526 RFC3339 format, at which the I2RS 527 transaction occurred. Given that 528 many I2RS transactions can occur in 529 rapid succession, the use of 530 fractional seconds MUST be used to 531 provide adequate granularity."; 532 reference 533 "RFC 3339: Date and Time on the 534 Internet: Timestamps"; 535 } 536 leaf client-id { 537 type client-id; 538 config false; 539 mandatory true; 540 description 541 "The I2RS Client identifier used 542 to authenticate the Client to the 543 I2RS Agent."; 544 } 545 leaf actor-id { 546 type actor-id; 547 config false; 548 mandatory true; 549 description 550 "This is an opaque identifier 551 that may be known to the Client 552 from a northbound controlling 553 application. This is used to 554 trace the northbound actor 555 driving the actions of the 556 Client. The Client may not 557 provide this identifier to the 558 Agent if there is no external 559 actor driving the Client. In 560 that case, the special value, 561 UNAVAILABLE is used to denote no 562 Actor ID."; 563 } 564 leaf client-addr { 565 type client-addr; 566 config false; 567 mandatory true; 568 description 569 "This is the IP address of the 570 client that connected to the Agent."; 571 } 572 leaf operation { 573 type operation; 574 config false; 575 mandatory true; 576 description 577 "This is the I2RS operation 578 performed."; 579 } 580 leaf operation-data { 581 type operation-data; 582 config false; 583 mandatory true; 584 description 585 "This field comprises the data 586 passed to the Agent to complete the 587 desired operation. If no additional 588 operation data is required, then this 589 field should be set to the special 590 value, NULL."; 591 } 592 leaf result-code { 593 type result-code; 594 config false; 595 mandatory true; 596 description 597 "This field holds the result of 598 the operation. In the case of RIB 599 operations, this MUST be the return 600 code as specified in Section 4 of 601 draft-nitinb-i2rs-rib-info-model. 602 The operation may not complete with 603 a result code in the case of a 604 timeout. If the operation fails to 605 complete, it MUST still log the 606 attempted operation with an 607 appropriate result code (e.g., a 608 result code indicating a timeout)."; 609 reference 610 "draft-nitinb-i2rs-rib-info-model: 611 Routing Information Base Info Model"; 612 } 613 } 614 } 615 } 616 618 6. Examples 620 Here is a proposed sample of what the fields might look like in an 621 I2RS trace log. This is only an early proposal. These values are 622 subject to change. 624 Entry ID: 1 625 Timestamp: 2013-09-03T12:00:01.21+00:00 626 Client ID: 5CEF1870-0326-11E2-A21F-0800200C9A66 627 Actor ID: com.example.RoutingApp 628 Client Address: 192.0.2.2 629 Operation: ROUTE_ADD 630 Operation Data: PREFIX 203.0.113.0 PREFIX-LEN 24 NEXT-HOP 631 198.51.100.1 632 Result Code: SUCCESS(0) 634 7. Operational Guidance 636 Specific operational procedures regarding temporary log storage, 637 rollover, retrieval, and access of I2RS trace logs is out of scope 638 for this document. Organizations employing I2RS trace logging are 639 responsible for establishing proper operational procedures that are 640 appropriately suited to their specific requirements and operating 641 environment. In this section we only provide fundamental and 642 generalized operational guidelines that are implementation- 643 independent. 645 7.1. Trace Log Creation 647 The I2RS Agent interacts with the Routing and Signaling functions of 648 the Routing Element. Since the I2RS Agent is responsible for 649 actually making the routing changes on the associated network device, 650 it creates and maintains a log of transactions that can be retrieved 651 to troubleshoot I2RS-related impact to the network. 653 7.2. Trace Log Temporary Storage 655 The trace information may be temporarily stored either in an in- 656 memory buffer or as a file local to the Agent. Care should be given 657 to the number of I2RS transactions expected on a given agent so that 658 the appropriate storage medium is used and to maximize the 659 effectiveness of the log while not impacting the performance and 660 health of the Agent. Section 7.3 talks about rotating the trace log 661 in order to preserve the transaction history without exhausting Agent 662 or network device resources. It is perfectly acceptable, therefore, 663 to use both an in-memory buffer for recent transactions while 664 rotating or archiving older transactions to a local file. 666 It is outside the scope of this document to specify the 667 implementation details (i.e., size, throughput, data protection, 668 privacy, etc.) for the physical storage of the I2RS log file. Data 669 retention policies of the I2RS traceability log is also outside the 670 scope of this document. 672 7.3. Trace Log Rotation 674 In order to prevent the exhaustion of resources on the I2RS Agent or 675 its associated network device, it is RECOMMENDED that the I2RS Agent 676 implements trace log rotation. The details on how this is achieved 677 are left to the implementation and outside the scope of this 678 document. However, it should be possible to do file rotation based 679 on either time or size of the current trace log. If file rollover is 680 supported, multiple archived log files should be supported in order 681 to maximize the troubleshooting and accounting benefits of the trace 682 log. 684 7.4. Trace Log Retrieval 686 Implementors are free to provide their own, proprietary interfaces 687 and develop custom tools to retrieve and display the I2RS trace log. 688 These may include the display of the I2RS trace log as Command Line 689 Interface (CLI) output. However, a key intention of defining this 690 information model is to establish an implementor-agnostic and 691 consistent interface to collect I2RS trace data. Correspondingly, 692 retrieval of the data should also be made implementor-agnostic. 694 The following three sections describe potential ways the trace log 695 can be accessed. At least one of these three MUST be used, with the 696 I2RS mechanisms being preferred as they are implementor-independent 697 approaches to retrieving the data. 699 7.4.1. Retrieval Via Syslog 701 The syslog protocol [RFC5424] is a standard way of sending event 702 notification messages from a host to a collector. However, the 703 protocol does not define any standard format for storing the 704 messages, and thus implementors of I2RS tracing would be left to 705 define their own format. So, while the data contained within the 706 syslog message would adhere to this information model, and may be 707 consumable by a human operator, it would not be easily parseable by a 708 machine. Therefore, syslog MAY be employed as a means of retrieving 709 or disseminating the I2RS trace log contents. 711 7.4.2. Retrieval Via I2RS Information Collection 713 Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture] 714 defines a mechanism for information collection. The information 715 collected includes obtaining a snapshot of a large amount of data 716 from the network element. It is the intent of I2RS to make this data 717 available in an implementor-agnostic fashion. Therefore, the I2RS 718 trace log SHOULD be made available via the I2RS information 719 collection mechanism either as a single snapshot or via a 720 subscription stream. 722 7.4.3. Retrieval Via I2RS Pub-Sub 724 Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture] 725 goes on to define a publish-subscribe mechanism for a feed of changes 726 happening within the I2RS layer. I2RS Agents SHOULD support 727 publishing I2RS trace log information to that feed as described in 728 that document. Subscribers would then receive a live stream of I2RS 729 interactions in trace log format and could flexibly choose to do a 730 number of things with the log messages. For example, the subscribers 731 could log the messages to a datastore, aggregate and summarize 732 interactions from a single client, etc. Using pub-sub for the 733 purpose of logging I2RS interactions augments the areas described by 734 [I-D.camwinget-i2rs-pubsub-sec]. The full range of potential 735 activites is virtually limitless and the details of how they are 736 performed are outside the scope of this document, however. 738 8. IANA Considerations 740 The YANG module implies a namespace that will need to be registered 741 with IANA. However, the I2RS WG will likely request such a namespace 742 for other work, so the registration of that namespace may occur in a 743 separate document. This section will be updated as these WG 744 decisions are made. 746 9. Security Considerations 748 The I2RS trace log, like any log file, reveals the state of the 749 entity producing it as well as the identifying information elements 750 and detailed interactions of the system containing it. The 751 information model described in this document does not itself 752 introduce any security issues, but it does define the set of 753 attributes that make up an I2RS log file. These attributes may 754 contain sensitive information and thus should adhere to the security, 755 privacy and permission policies of the organization making use of the 756 I2RS log file. 758 It is outside the scope of this document to specify how to protect 759 the stored log file, but it is expected that adequate precautions and 760 security best practices such as disk encryption, appropriately 761 restrictive file/directory permissions, suitable hardening and 762 physical security of logging entities, mutual authentication, 763 transport encryption, channel confidentiality, and channel integrity 764 if transferring log files. Additionally, the potentially sensitive 765 information contained in a log file SHOULD be adequately anonymized 766 or obfuscated by operators to ensure its privacy. 768 10. Acknowledgments 770 The authors would like to thank Alia Atlas for her initial feedback 771 and overall support for this work. Additionally, the authors 772 acknowledge Alvaro Retana, Russ White, Matt Birkner, Jeff Haas, Joel 773 Halpern and Dean Bogdanovich for their reviews, contributed text, and 774 suggested improvements to this document. 776 11. References 778 11.1. Normative References 780 [I-D.ietf-i2rs-architecture] 781 Atlas, A., Halpern, J., Hares, S., Ward, D., and T. 782 Nadeau, "An Architecture for the Interface to the Routing 783 System", draft-ietf-i2rs-architecture-00 (work in 784 progress), August 2013. 786 [I-D.ietf-i2rs-problem-statement] 787 Atlas, A., Nadeau, T., and D. Ward, "Interface to the 788 Routing System Problem Statement", draft-ietf-i2rs- 789 problem-statement-00 (work in progress), August 2013. 791 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 792 Requirement Levels", BCP 14, RFC 2119, March 1997. 794 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 795 Network Configuration Protocol (NETCONF)", RFC 6020, 796 October 2010. 798 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 799 October 2010. 801 11.2. Informative References 803 [I-D.camwinget-i2rs-pubsub-sec] 804 Beck, K., Cam-Winget, N., and D. McGrew, "Using the 805 Publish-Subscribe Model in the Interface to the Routing 806 System", draft-camwinget-i2rs-pubsub-sec-00 (work in 807 progress), July 2013. 809 [I-D.nitinb-i2rs-rib-info-model] 810 Bahadur, N., Folkes, R., Kini, S., and J. Medved, "Routing 811 Information Base Info Model", draft-nitinb-i2rs-rib-info- 812 model-02 (work in progress), August 2013. 814 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 815 Internet: Timestamps", RFC 3339, July 2002. 817 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, March 2009. 819 [RFC5737] Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks 820 Reserved for Documentation", RFC 5737, January 2010. 822 Authors' Addresses 824 Joe Clarke 825 Cisco Systems, Inc. 826 7200-12 Kit Creek Road 827 Research Triangle Park, NC 27709 828 US 830 Phone: +1-919-392-2867 831 Email: jclarke@cisco.com 833 Gonzalo Salgueiro 834 Cisco Systems, Inc. 835 7200-12 Kit Creek Road 836 Research Triangle Park, NC 27709 837 US 839 Email: gsalguei@cisco.com 841 Carlos Pignataro 842 Cisco Systems, Inc. 843 7200-12 Kit Creek Road 844 Research Triangle Park, NC 27709 845 US 847 Email: cpignata@cisco.com