/[marcuscom]/IETF/trunk/i2rs-traceability/draft-clarke-i2rs-traceability.txt
ViewVC logotype

Contents of /IETF/trunk/i2rs-traceability/draft-clarke-i2rs-traceability.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 18727 - (show annotations) (download)
Mon Sep 2 00:15:38 2013 UTC (6 years, 7 months ago) by marcus
Original Path: trunk/i2rs-traceability/draft-clarke-i2rs-traceability.txt
File MIME type: text/plain
File size: 21985 byte(s)
Correct some points in the figure raised by Carlos.  Also, clarify that
Op Data and Actor ID are mandatory and should be logged as empty if not
provided.

Provide some more clarification around why UUID is a good choice for the
Client ID.

1
2
3
4 I2RS J. Clarke
5 Internet-Draft G. Salgueiro
6 Intended status: Informational Cisco
7 Expires: March 5, 2014 September 1, 2013
8
9
10 Information Model for Traceability in the Interface to the Routing
11 System (I2RS)
12 draft-clarke-i2rs-traceability-00
13
14 Abstract
15
16 This document specifies requirements and defines an information model
17 for recording interactions between elements implementing the
18 Interface to the Routing System (I2RS) protocol. This framework
19 provides a consistent tracing interface that can be used uniformly by
20 the different I2RS elements to record what was done, by which
21 element, and when. It aims to improve the management of I2RS
22 implementations, and can be used for troubleshooting, auditing,
23 forensics, and accounting purposes.
24
25 Status of this Memo
26
27 This Internet-Draft is submitted in full conformance with the
28 provisions of BCP 78 and BCP 79.
29
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/.
34
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."
39
40 This Internet-Draft will expire on March 5, 2014.
41
42 Copyright Notice
43
44 Copyright (c) 2013 IETF Trust and the persons identified as the
45 document authors. All rights reserved.
46
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
53
54
55 Clarke & Salgueiro Expires March 5, 2014 [Page 1]
56
57 Internet-Draft I2RS Traceability September 2013
58
59
60 to this document. Code Components extracted from this document must
61 include Simplified BSD License text as described in Section 4.e of
62 the Trust Legal Provisions and are provided without warranty as
63 described in the Simplified BSD License.
64
65
66 Table of Contents
67
68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
69 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
70 3. Motivation and Use Cases . . . . . . . . . . . . . . . . . . . 3
71 4. Information Model . . . . . . . . . . . . . . . . . . . . . . 4
72 4.1. I2RS Trace Log Mandatory Fields . . . . . . . . . . . . . 4
73 4.2. I2RS Trace Log Extensibility and Optional Fields . . . . . 6
74 4.3. I2RS Trace Log Syntax . . . . . . . . . . . . . . . . . . 6
75 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
76 6. Operational Guidance . . . . . . . . . . . . . . . . . . . . . 7
77 6.1. Trace Log Storage . . . . . . . . . . . . . . . . . . . . 7
78 6.2. Trace Log Creation . . . . . . . . . . . . . . . . . . . . 8
79 6.3. Trace Log Rotation . . . . . . . . . . . . . . . . . . . . 8
80 6.4. Trace Log Retrieval . . . . . . . . . . . . . . . . . . . 8
81 6.4.1. Retrieval Via Syslog . . . . . . . . . . . . . . . . . 8
82 6.4.2. Retrieval Via I2RS . . . . . . . . . . . . . . . . . . 9
83 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
84 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
85 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9
86 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10
87 10.1. Normative References . . . . . . . . . . . . . . . . . . . 10
88 10.2. Informative References . . . . . . . . . . . . . . . . . . 10
89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111 Clarke & Salgueiro Expires March 5, 2014 [Page 2]
112
113 Internet-Draft I2RS Traceability September 2013
114
115
116 1. Introduction
117
118 The architecture for the Interface to the Routing System
119 ([I-D.ietf-i2rs-architecture]) specifies that I2RS Clients wishing to
120 retrieve or change routing state on a network device MUST
121 authenticate to an I2RS Agent. The I2RS Client will have a unique
122 identity it provides for authentication, and should provide another,
123 opaque identifier for applications communicating through it. All of
124 this is critical information to be used for troubleshooting I2RS
125 interactions.
126
127 This document specifies requirements and describes the information
128 model for traceability attributes that must be collected and logged
129 by I2RS Agents in order to effectively troubleshoot I2RS
130 interactions. In this context, effective troubleshooting means being
131 able to identify what operation was performed by a specific I2RS
132 Client, what was the result of the operation, and when that operation
133 was performed.
134
135
136 2. Terminology
137
138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
140 document are to be interpreted as described in [RFC2119].
141
142 The architecture specification for I2RS [I-D.ietf-i2rs-architecture]
143 defines additional terms used in this document that are specific to
144 the I2RS domain, such as "I2RS Agent", "I2RS Client", etc. The
145 reader is expected to be familiar with the terminology and concepts
146 defined in [I-D.ietf-i2rs-architecture].
147
148
149 3. Motivation and Use Cases
150
151 As networks grow, so too does the scale and complexity of routing
152 systems. I2RS offers a standard, programmatic interface allowing
153 improved automation and more granular control over an increasingly
154 dynamic routing and signaling state. This ability to automate even
155 complex policy-based controls highlights the need for an equally
156 scalable traceability function to provide event-level granularity of
157 the routing system compliant with the requirements of I2RS (Section 5
158 of [I-D.ietf-i2rs-problem-statement].
159
160 An obvious motivation for I2RS traceability is the need to
161 troubleshoot these increasingly complex routing systems. For
162 example, since I2RS is a high-throughput multi-channel, full duplex
163 and highly responsive interface, I2RS Clients may be performing a
164
165
166
167 Clarke & Salgueiro Expires March 5, 2014 [Page 3]
168
169 Internet-Draft I2RS Traceability September 2013
170
171
172 large number of operations on I2RS Agents concurrently or at nearly
173 the same time and quite possibly in very rapid succession. As these
174 many changes are made, the network reacts accordingly. These changes
175 might lead to a race condition, performance issues, data loss, or
176 disruption of services. In order to isolate the root cause of these
177 issues it is critical that a network operator or administrator has
178 visibility into what changes were made via I2RS at a specific time.
179
180 As I2RS becomes increasingly pervasive in networks, a traceability
181 model offers significant advantages and facilitates the following use
182 cases:
183
184 o Automated event correlation, trend analysis, and anomaly
185 detection.
186
187 o Trace log storage for offline (manual or tools) analysis.
188
189 o Improved accounting of routing system transactions.
190
191 o Standardized structured data format for writing common tools.
192
193 o Common reference for automated testing and incident reporting.
194
195 o Real-time monitoring and troubleshooting.
196
197 o Enhanced network audit, management and forensic analysis
198 capabilities.
199
200
201 4. Information Model
202
203 4.1. I2RS Trace Log Mandatory Fields
204
205 In order to ensure that each I2RS interaction can be properly traced
206 back to the Client that made the request at a specific point in time,
207 the following information MUST be collected and stored by the Agent.
208
209 The interaction between the optional northbound actor, I2RS Client,
210 I2RS Agent, the Routing System and the data captured in the I2RS
211 trace log is shown in Figure 1.
212
213
214
215
216
217
218
219
220
221
222
223 Clarke & Salgueiro Expires March 5, 2014 [Page 4]
224
225 Internet-Draft I2RS Traceability September 2013
226
227
228 +-------------+
229 |Actor |
230 |.............|
231 | Actor ID |
232 +-------------+
233 ^
234 :
235 :
236 V
237 +-------------+
238 |I2RS Client |
239 |.............|
240 | Client ID |
241 +-------------+
242 ^
243 |
244 |
245 V
246 +-------------+ +-----------------------------+
247 |I2RS Agent |---------------->|Trace Log |
248 | | |.............................|
249 +-------------+ |Timestamp |
250 ^ |Client ID |
251 | ^ |Actor ID |
252 Operation + | Result Code |Client Address |
253 Op Data | |Operation |
254 V | |Operation Data |
255 V |Result Code |
256 +-------------+ +-----------------------------+
257 |Routing |
258 |System |
259 +-------------+
260
261 Figure 1: I2RS Interaction Trace Log Capture
262
263 The list below describes the fields captured in the I2RS trace log.
264
265 Timestamp: The specific time, adhering to [RFC3339] format, at
266 which the I2RS transaction occurred. Given that many I2RS
267 transactions can occur in rapid succession, the use of fractional
268 seconds MUST be used to provide adequate granularity.
269
270 Client Identifier: The I2RS Client identifier used to authenticate
271 the Client to the I2RS Agent.
272
273
274
275
276
277
278
279 Clarke & Salgueiro Expires March 5, 2014 [Page 5]
280
281 Internet-Draft I2RS Traceability September 2013
282
283
284 Actor Identifier: This is an opaque identifier that may be known to
285 the Client from a northbound controlling application. This is
286 used to trace the northbound actor driving the actions of the
287 Client. The Client may not provide this identifier to the Agent
288 is there is no external actor driving the Client. However, this
289 field MUST be logged. If the Client does not provide an actor ID,
290 then the Agent MUST log an empty field.
291
292 Client Address: This is the network address of the client that
293 connected to the Agent. For example, this may be an IPv4 or IPv6
294 address.
295
296 Operation: This is the I2RS operation performed. For example, this
297 may be an add route operation if a route is being inserted into a
298 routing table.
299
300 Operation Data: This field comprises the data passed to the Agent
301 to complete the desired operation. For example, if the operation
302 is a route add operation, the Operation Data would include the
303 route prefix, prefix length, and next hop information to be
304 inserted as well as the specific routing table to which the route
305 will be added. The operation data can also include interface
306 information. Some operations MAY not provide operation data, and
307 in those cases this field MUST be logged as an empty field.
308
309 Result Code: This field holds the result of the operation. In the
310 case of RIB operations, this MUST be the return code as specified
311 in Section 4 of [I-D.nitinb-i2rs-rib-info-model].
312
313 4.2. I2RS Trace Log Extensibility and Optional Fields
314
315 TBD
316
317 4.3. I2RS Trace Log Syntax
318
319 The following describes the trace log information model using
320 Augmented Backus-Naur Form (ABNF) syntax [RFC5234]:
321 i2rs-trace-log = timestamp client-id actor-id client-addr operation
322 operation-data result-code
323 client-id = uuid
324 actor-id = byte-string
325 byte-string = *( %x01-09 / %x0B-0C / %x0E-FF )
326 ; any byte except NUL, CR or LF
327 client-addr = IP-literal / IPv4address
328 operation = ALPHA *( ALPHA / "_" / "-" / "(" / ")" )
329 operation-data = *VCHAR
330 result-code = 1*( ALPHA / DIGIT / "-" / "_" / "(" / ")" )
331
332
333
334
335 Clarke & Salgueiro Expires March 5, 2014 [Page 6]
336
337 Internet-Draft I2RS Traceability September 2013
338
339
340 The ABNF syntax rules <IP-literal>, <IPv4address>, and <sub-delims>
341 are specified in [RFC3986]. The core rules <DIGIT>, <HEXDIGIT>,
342 <ALPHA> and <VCHAR> are used as described in Appendix B of [RFC5234].
343
344 Here, <uuid> is specified in [RFC4122]. The idea of using a UUID for
345 the Client identifier ensures the ID is unique not just in the scope
346 of the current I2RS Agent, but across Agents as well. This ensures
347 that two clients that are unaware of each other will not allocate the
348 same Client ID. That does not preclude two Clients acting as one for
349 purposes of high availability from sharing the same UUID as generated
350 by one one of the Clients. [[Note: the format of the Client ID has
351 not yet been decided by the I2RS WG. This is subject to change.]]
352
353 The <timestamp> field is defined in [RFC3339]. As stated in
354 Section 4.1 the fractional second format MUST be used to provide
355 proper granularity.
356
357 The values for <operation>, <operation-data> and <result-code> are
358 suggestions as the protocol has not been defined yet. By making
359 these human-readable (as opposed to opcodes) the log becomes more
360 easily consumable by operators and administrators trying to
361 troubleshoot issues relating to I2RS. Even in cases where the
362 operations or codes might appear as opcodes on the wire, their
363 textual translations MUST be included in the log. The opcodes
364 themselves MAY appear in parentheses after the textual
365 representation.
366
367
368 5. Examples
369
370 [NOTE: To put in a name:value pairing of *proposed* values now with a
371 note that this is subject to change and proposed only.]
372
373
374 6. Operational Guidance
375
376 [NOTE: Gonzalo to write some introductory text and the take a pass at
377 the sub-sections.]
378
379 6.1. Trace Log Storage
380
381 The trace information may be stored either in an in-memory buffer or
382 as a file local to the Agent. Care should be given to the number of
383 I2RS transactions expected on a given agent so that the appropriate
384 storage medium is used as to maximize effectiveness of the log while
385 not impacting the performance and health of the Agent. Section 6.3
386 talks about rotating the trace log as to preserve the history without
387 exhausting Agent or network device resources. It is perfectly
388
389
390
391 Clarke & Salgueiro Expires March 5, 2014 [Page 7]
392
393 Internet-Draft I2RS Traceability September 2013
394
395
396 acceptable, therefore, to use both an in-memory buffer for recent
397 transactions while rotating or archiving older transactions to a
398 local file.
399
400 The specific implementation of the trace log is beyond the scope of
401 an information model, however.
402
403 6.2. Trace Log Creation
404
405 The I2RS Agent interacts with the Routing and Signaling functions of
406 the Routing Element. Since the I2RS Agent is responsible for
407 actually making the routing changes on the associated network device,
408 it creates and maintains a log of transactions that can be retrieved
409 to troubleshoot I2RS-related impact to the network.
410
411 6.3. Trace Log Rotation
412
413 In order to prevent the exhaustion of resources on the I2RS Agent or
414 its associated network device, the I2RS trace log implementation MAY
415 choose to implement a configurable rotation schedule. It SHOULD be
416 possible to do rotation based on either time or on size of the
417 current trace log. If rotation is supported, multiple archived log
418 files SHOULD be supported in order to maximize the troubleshooting
419 and accounting benefits of the trace log.
420
421 6.4. Trace Log Retrieval
422
423 Implementors are free to provide their own, proprietary interfaces to
424 retrieve and display the I2RS trace log. These may include the
425 display of the I2RS trace log as Command Line Interface (CLI) output.
426 However, a key intention of defining this information model is to
427 establish an implementor-agnostic way to collect I2RS trace data. As
428 such, retrieval of the data should also be made implementor-agnostic.
429
430 The following two sections describe potential ways by which the trace
431 log can be accessed. At least one of these two MUST be used, with
432 the I2RS mechanism being preferred as it is an implementor-agnostic
433 approach to retrieving the data.
434
435 6.4.1. Retrieval Via Syslog
436
437 The syslog protocol [RFC5424] is a standard way of sending event
438 notification messages from an host to a collector. However, the
439 protocol does not define any standard format for storing the
440 messages, and thus implementors of I2RS tracing would be left to
441 define their own format. So, while the data contained within the
442 syslog message would adhere to this information model, and may be
443 consumable by a human operator, it would not be easily parseable by a
444
445
446
447 Clarke & Salgueiro Expires March 5, 2014 [Page 8]
448
449 Internet-Draft I2RS Traceability September 2013
450
451
452 machine. Therefore, syslog MAY be employed as a means of retrieving
453 or disseminating the I2RS trace log contents.
454
455 6.4.2. Retrieval Via I2RS
456
457 Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture]
458 defines a mechanism for information collection. The information
459 collected includes obtaining a snapshot of a large amount of data
460 from the network element. It is the intent of I2RS to make this data
461 available in an implementor-agnostic fashion. Therefore, the I2RS
462 trace log SHOULD be made available via the I2RS information
463 collection mechanism either as a single snapshot or via a
464 subscription stream.
465
466
467 7. IANA Considerations
468
469 This document makes no request of IANA.
470
471
472 8. Security Considerations
473
474 The I2RS Traceability information model does not directly introduce
475 security issues. However, it defines a set of attributes that may be
476 considered sensitive information for privacy or business reasons.
477
478 Specifically, the data being captured for traceability describes
479 state as well as identifying characteristics of the Clients affecting
480 that state. As such, this data is to be considered private and
481 protected locally on the Agent. While it is outside the scope of
482 this document to specify exactly how to protect the traceability
483 contents, implementors of I2RS SHOULD apply appropriate permissions
484 to control who can view the log regardless of whether or not it is
485 stored in memory or on disk.
486
487 Finally, the elements defined in this information model do not store
488 cryptographic information.
489
490
491 9. Acknowledgments
492
493 The authors would like to thank Carlos Pignataro for his contributed
494 text, review comments, suggested improvements to this document.
495
496
497 10. References
498
499
500
501
502
503 Clarke & Salgueiro Expires March 5, 2014 [Page 9]
504
505 Internet-Draft I2RS Traceability September 2013
506
507
508 10.1. Normative References
509
510 [I-D.ietf-i2rs-architecture]
511 Atlas, A., Halpern, J., Hares, S., Ward, D., and T.
512 Nadeau, "An Architecture for the Interface to the Routing
513 System", draft-ietf-i2rs-architecture-00 (work in
514 progress), August 2013.
515
516 [I-D.ietf-i2rs-problem-statement]
517 Atlas, A., Nadeau, T., and D. Ward, "Interface to the
518 Routing System Problem Statement",
519 draft-ietf-i2rs-problem-statement-00 (work in progress),
520 August 2013.
521
522 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
523 Requirement Levels", BCP 14, RFC 2119, March 1997.
524
525 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
526 Resource Identifier (URI): Generic Syntax", STD 66,
527 RFC 3986, January 2005.
528
529 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
530 Unique IDentifier (UUID) URN Namespace", RFC 4122,
531 July 2005.
532
533 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
534 Specifications: ABNF", STD 68, RFC 5234, January 2008.
535
536 10.2. Informative References
537
538 [I-D.nitinb-i2rs-rib-info-model]
539 Bahadur, N., Folkes, R., Kini, S., and J. Medved, "Routing
540 Information Base Info Model",
541 draft-nitinb-i2rs-rib-info-model-02 (work in progress),
542 August 2013.
543
544 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
545 Internet: Timestamps", RFC 3339, July 2002.
546
547 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, March 2009.
548
549
550
551
552
553
554
555
556
557
558
559 Clarke & Salgueiro Expires March 5, 2014 [Page 10]
560
561 Internet-Draft I2RS Traceability September 2013
562
563
564 Authors' Addresses
565
566 Joe Clarke
567 Cisco Systems, Inc.
568 7200-12 Kit Creek Road
569 Research Triangle Park, NC 27709
570 US
571
572 Phone: +1-919-392-2867
573 Email: jclarke@cisco.com
574
575
576 Gonzalo Salgueiro
577 Cisco Systems
578 7200-12 Kit Creek Road
579 Research Triangle Park, NC 27709
580 US
581
582 Email: gsalguei@cisco.com
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615 Clarke & Salgueiro Expires March 5, 2014 [Page 11]
616

  ViewVC Help
Powered by ViewVC 1.1.27