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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 19728 - (hide annotations) (download)
Fri Jun 6 20:16:02 2014 UTC (5 years, 9 months ago) by marcus
File MIME type: text/plain
File size: 41277 byte(s)
Fix a typo.

1 marcus 18717
2    
3    
4 marcus 18729
5 marcus 18717 I2RS J. Clarke
6 marcus 18726 Internet-Draft G. Salgueiro
7 marcus 18746 Intended status: Informational C. Pignataro
8 marcus 19723 Expires: December 8, 2014 Cisco
9     June 6, 2014
10 marcus 18717
11    
12 marcus 18746 Interface to the Routing System (I2RS) Traceability: Framework and
13     Information Model
14 marcus 19726 draft-clarke-i2rs-traceability-02
15 marcus 18717
16     Abstract
17    
18 marcus 18741 This document describes a framework for traceability in the Interface
19 marcus 18746 to the Routing System (I2RS) and information model for that
20     framework. It specifies the motivation, requirements, use cases, and
21     defines an information model for recording interactions between
22     elements implementing the I2RS protocol. This framework provides a
23     consistent tracing interface for components implementing the I2RS
24     architecture to record what was done, by which component, and when.
25     It aims to improve the management of I2RS implementations, and can be
26     used for troubleshooting, auditing, forensics, and accounting
27     purposes.
28 marcus 18717
29 marcus 18729 Status of This Memo
30 marcus 18717
31     This Internet-Draft is submitted in full conformance with the
32     provisions of BCP 78 and BCP 79.
33    
34     Internet-Drafts are working documents of the Internet Engineering
35     Task Force (IETF). Note that other groups may also distribute
36     working documents as Internet-Drafts. The list of current Internet-
37     Drafts is at http://datatracker.ietf.org/drafts/current/.
38    
39     Internet-Drafts are draft documents valid for a maximum of six months
40     and may be updated, replaced, or obsoleted by other documents at any
41     time. It is inappropriate to use Internet-Drafts as reference
42     material or to cite them other than as "work in progress."
43    
44 marcus 19723 This Internet-Draft will expire on December 8, 2014.
45 marcus 18717
46     Copyright Notice
47    
48 marcus 19723 Copyright (c) 2014 IETF Trust and the persons identified as the
49 marcus 18717 document authors. All rights reserved.
50    
51     This document is subject to BCP 78 and the IETF Trust's Legal
52     Provisions Relating to IETF Documents
53    
54    
55    
56 marcus 19723 Clarke, et al. Expires December 8, 2014 [Page 1]
57 marcus 18717
58 marcus 19723 Internet-Draft I2RS Traceability June 2014
59 marcus 18717
60    
61 marcus 18746 (http://trustee.ietf.org/license-info) in effect on the date of
62     publication of this document. Please review these documents
63 marcus 18741 carefully, as they describe your rights and restrictions with respect
64 marcus 18726 to this document. Code Components extracted from this document must
65     include Simplified BSD License text as described in Section 4.e of
66 marcus 18718 the Trust Legal Provisions and are provided without warranty as
67     described in the Simplified BSD License.
68    
69 marcus 18717 Table of Contents
70    
71 marcus 18729 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
72 marcus 18746 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 3
73 marcus 18931 3. Motivation . . . . . . . . . . . . . . . . . . . . . . . . . 3
74     4. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 4
75 marcus 19723 5. Information Model . . . . . . . . . . . . . . . . . . . . . . 4
76 marcus 18932 5.1. I2RS Traceability Framework . . . . . . . . . . . . . . . 5
77 marcus 18931 5.2. I2RS Trace Log Mandatory Fields . . . . . . . . . . . . . 6
78 marcus 19723 5.3. End of Message Marker . . . . . . . . . . . . . . . . . . 8
79 marcus 18931 5.4. I2RS Trace Log Extensibility and Optional Fields . . . . 8
80     5.5. I2RS Trace Log Syntax . . . . . . . . . . . . . . . . . . 8
81 marcus 19726 5.5.1. Structure of the I2RS Trace Log . . . . . . . . . . . 8
82     5.5.2. I2RS Trace Log Yang Module . . . . . . . . . . . . . 9
83 marcus 19723 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 14
84 marcus 19726 7. Operational Guidance . . . . . . . . . . . . . . . . . . . . 15
85     7.1. Trace Log Creation . . . . . . . . . . . . . . . . . . . 15
86 marcus 19723 7.2. Trace Log Temporary Storage . . . . . . . . . . . . . . . 15
87     7.3. Trace Log Rotation . . . . . . . . . . . . . . . . . . . 15
88 marcus 19726 7.4. Trace Log Retrieval . . . . . . . . . . . . . . . . . . . 16
89 marcus 19723 7.4.1. Retrieval Via Syslog . . . . . . . . . . . . . . . . 16
90     7.4.2. Retrieval Via I2RS Information Collection . . . . . . 16
91     7.4.3. Retrieval Via I2RS Pub-Sub . . . . . . . . . . . . . 16
92 marcus 19726 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
93 marcus 19723 9. Security Considerations . . . . . . . . . . . . . . . . . . . 17
94     10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17
95 marcus 19726 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 18
96     11.1. Normative References . . . . . . . . . . . . . . . . . . 18
97 marcus 19723 11.2. Informative References . . . . . . . . . . . . . . . . . 18
98 marcus 19726 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19
99 marcus 18717
100     1. Introduction
101    
102     The architecture for the Interface to the Routing System
103 marcus 18726 ([I-D.ietf-i2rs-architecture]) specifies that I2RS Clients wishing to
104 marcus 18741 retrieve or change routing state on a routing element MUST
105 marcus 18726 authenticate to an I2RS Agent. The I2RS Client will have a unique
106 marcus 18718 identity it provides for authentication, and should provide another,
107 marcus 18741 opaque identifier for applications (or actors) communicating through
108 marcus 18931 it. The programming of routing state will produce a return code
109 marcus 19723
110    
111    
112     Clarke, et al. Expires December 8, 2014 [Page 2]
113    
114     Internet-Draft I2RS Traceability June 2014
115    
116    
117 marcus 19726 containing the results of the specified operation and associated
118 marcus 18741 reason(s) for the result. All of this is critical information to be
119     used for understanding the history of I2RS interactions.
120 marcus 18717
121 marcus 18931 This document describes use cases for I2RS traceability. Based on
122     these use cases, the document proposes an information model and
123     reporting requirements to provide for effective recording of I2RS
124 marcus 18718 interactions. In this context, effective troubleshooting means being
125     able to identify what operation was performed by a specific I2RS
126     Client, what was the result of the operation, and when that operation
127 marcus 18717 was performed.
128    
129 marcus 18741 Discussions about the retention of the data logged as part of I2RS
130     traceability, while important, are outside of the scope of this
131     document.
132    
133 marcus 18746 2. Terminology and Conventions
134 marcus 18726
135 marcus 18717 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
136     "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
137     document are to be interpreted as described in [RFC2119].
138    
139 marcus 18726 The architecture specification for I2RS [I-D.ietf-i2rs-architecture]
140     defines additional terms used in this document that are specific to
141     the I2RS domain, such as "I2RS Agent", "I2RS Client", etc. The
142     reader is expected to be familiar with the terminology and concepts
143     defined in [I-D.ietf-i2rs-architecture].
144 marcus 18717
145 marcus 18746 The IP addresses used in the example in this document correspond to
146     the documentation address blocks 192.0.2.0/24 (TEST-NET-1),
147     198.51.100.0/24 (TEST-NET-2) and 203.0.113.0/24 (TEST-NET-3) as
148     described in [RFC5737].
149    
150 marcus 18931 3. Motivation
151 marcus 18717
152 marcus 18931 As networks scale and policy becomes an increasingly important part
153     of the control plane that creates and maintains the forwarding state,
154     operational complexity increases as well. I2RS offers more granular
155     and coherent control over policy and control plane state, but it also
156     removes or reduces the locality of the policy that has been applied
157     to the control plane at any individual forwarding device. The
158 marcus 19723 ability to automate and abstract even complex policy-based controls
159     highlights the need for an equally scalable traceability function to
160     provide event-level granularity of the routing system compliant with
161     the requirements of I2RS (Section 5 of
162     [I-D.ietf-i2rs-problem-statement]).
163 marcus 18717
164 marcus 18931
165    
166 marcus 19723
167    
168     Clarke, et al. Expires December 8, 2014 [Page 3]
169 marcus 18931
170 marcus 19723 Internet-Draft I2RS Traceability June 2014
171 marcus 18931
172    
173     4. Use Cases
174    
175 marcus 18726 An obvious motivation for I2RS traceability is the need to
176 marcus 18741 troubleshoot and identify root-causes of problems in these
177     increasingly complex routing systems. For example, since I2RS is a
178     high-throughput multi-channel, full duplex and highly responsive
179     interface, I2RS Clients may be performing a large number of
180     operations on I2RS Agents concurrently or at nearly the same time and
181     quite possibly in very rapid succession. As these many changes are
182     made, the network reacts accordingly. These changes might lead to a
183     race condition, performance issues, data loss, or disruption of
184     services. In order to isolate the root cause of these issues it is
185     critical that a network operator or administrator has visibility into
186     what changes were made via I2RS at a specific time.
187 marcus 18718
188 marcus 18749 Some network environments have strong auditing requirements for
189 marcus 18931 configuration and runtime changes. Other environments have policies
190     that require saving logging information for operational or regulatory
191     compliance considerations. These requirements therefore demand that
192     I2RS provides an account of changes made to network element routing
193     systems.
194 marcus 18749
195 marcus 18741 As I2RS becomes increasingly pervasive in routing environments, a
196     traceability model offers significant advantages and facilitates the
197     following use cases:
198 marcus 18718
199 marcus 18726 o Automated event correlation, trend analysis, and anomaly
200     detection.
201 marcus 18718
202 marcus 18726 o Trace log storage for offline (manual or tools) analysis.
203 marcus 18718
204 marcus 18726 o Improved accounting of routing system transactions.
205 marcus 18718
206 marcus 18726 o Standardized structured data format for writing common tools.
207    
208     o Common reference for automated testing and incident reporting.
209    
210     o Real-time monitoring and troubleshooting.
211    
212     o Enhanced network audit, management and forensic analysis
213     capabilities.
214    
215 marcus 19723 5. Information Model
216 marcus 18726
217    
218 marcus 18931
219 marcus 19723
220    
221    
222    
223    
224     Clarke, et al. Expires December 8, 2014 [Page 4]
225 marcus 18931
226 marcus 19723 Internet-Draft I2RS Traceability June 2014
227 marcus 18931
228    
229 marcus 18932 5.1. I2RS Traceability Framework
230    
231 marcus 18741 This section describes a framework for I2RS traceability based on the
232     I2RS Architecture. Some notable elements on the architecture are
233     highlighted herein.
234 marcus 18717
235 marcus 18718 The interaction between the optional northbound actor, I2RS Client,
236     I2RS Agent, the Routing System and the data captured in the I2RS
237     trace log is shown in Figure 1.
238 marcus 18717
239 marcus 18734
240    
241    
242    
243    
244    
245    
246    
247    
248    
249 marcus 18931
250    
251    
252    
253    
254    
255    
256    
257    
258    
259    
260    
261    
262    
263    
264    
265    
266    
267    
268    
269    
270    
271    
272 marcus 18948
273    
274    
275    
276    
277    
278 marcus 19723
279    
280     Clarke, et al. Expires December 8, 2014 [Page 5]
281 marcus 18931
282 marcus 19723 Internet-Draft I2RS Traceability June 2014
283 marcus 18931
284    
285 marcus 18948 +-------------+
286     |Actor |
287     |.............|
288     | Actor ID |
289     +-------------+
290     ^
291 marcus 19727 | 0 .. N
292     |
293 marcus 18932 V
294     +-------------+
295 marcus 18718 |I2RS Client |
296     |.............|
297     | Client ID |
298     +-------------+
299 marcus 18727 ^
300 marcus 19723 | 1 .. N
301 marcus 18718 |
302     V
303     +-------------+ +-----------------------------+
304     |I2RS Agent |---------------->|Trace Log |
305     | | |.............................|
306 marcus 19727 +-------------+ |Log Entry [1 .. N] |
307     ^ |.............................|
308     | |Timestamp |
309     | |Client ID |
310 marcus 18727 | ^ |Actor ID |
311 marcus 18720 Operation + | Result Code |Client Address |
312 marcus 18727 Op Data | |Operation |
313 marcus 18720 V | |Operation Data |
314 marcus 18931 | |Result Code |
315     V |End Of Message |
316 marcus 18720 +-------------+ +-----------------------------+
317     |Routing |
318 marcus 18718 |System |
319     +-------------+
320 marcus 18717
321 marcus 18718 Figure 1: I2RS Interaction Trace Log Capture
322 marcus 18717
323 marcus 18931 5.2. I2RS Trace Log Mandatory Fields
324 marcus 18741
325     In order to ensure that each I2RS interaction can be properly traced
326     back to the Client that made the request at a specific point in time,
327     the following information MUST be collected and stored by the Agent.
328    
329 marcus 18718 The list below describes the fields captured in the I2RS trace log.
330 marcus 18717
331 marcus 19723 Entry ID: This is a unique identifier for each entry in the I2RS
332     trace log. Since multiple operations can occur from the same
333 marcus 18717
334    
335 marcus 18734
336 marcus 19723 Clarke, et al. Expires December 8, 2014 [Page 6]
337 marcus 18734
338 marcus 19723 Internet-Draft I2RS Traceability June 2014
339 marcus 18734
340    
341 marcus 19723 client at the same time, it is important to have an identifier
342     that can be unambiguously associated to a specific entry.
343    
344     Timestamp: The specific time, adhering to [RFC3339] format, at
345     which the I2RS transaction occurred. Given that many I2RS
346     transactions can occur in rapid succession, the use of fractional
347     seconds MUST be used to provide adequate granularity.
348    
349 marcus 18948 Client Identifier: The I2RS Client identifier used to authenticate
350     the Client to the I2RS Agent.
351    
352     Actor Identifier: This is an opaque identifier that may be known to
353     the Client from a northbound controlling application. This is
354 marcus 18741 used to trace the northbound actor driving the actions of the
355 marcus 18727 Client. The Client may not provide this identifier to the Agent
356 marcus 18734 if there is no external actor driving the Client. However, this
357 marcus 18727 field MUST be logged. If the Client does not provide an actor ID,
358 marcus 19723 then the Agent MUST log an UNAVAILABLE value in the field.
359 marcus 18717
360     Client Address: This is the network address of the client that
361     connected to the Agent. For example, this may be an IPv4 or IPv6
362 marcus 18728 address. [Note: will I2RS support interactions that have no
363     network address? If so this field will need to be updated.]
364 marcus 18717
365     Operation: This is the I2RS operation performed. For example, this
366     may be an add route operation if a route is being inserted into a
367     routing table.
368    
369     Operation Data: This field comprises the data passed to the Agent
370     to complete the desired operation. For example, if the operation
371     is a route add operation, the Operation Data would include the
372     route prefix, prefix length, and next hop information to be
373     inserted as well as the specific routing table to which the route
374 marcus 18718 will be added. The operation data can also include interface
375 marcus 18931 information. Some operations may not provide operation data, and
376 marcus 18741 in those cases this field MUST be logged as a NULL string.
377 marcus 18717
378     Result Code: This field holds the result of the operation. In the
379     case of RIB operations, this MUST be the return code as specified
380 marcus 18728 in Section 4 of [I-D.nitinb-i2rs-rib-info-model]. The operation
381     may not complete with a result code in the case of a timeout. If
382     the operation fails to complete, it MUST still log the attempted
383     operation with an appropriate result code (e.g., a result code
384     indicating a timeout).
385 marcus 18717
386 marcus 18931 End Of Message: Each log entry SHOULD have an appropriate End Of
387     Message (EOM) indicator. See section Section 5.3 below for more
388     details.
389 marcus 18720
390 marcus 19723
391    
392     Clarke, et al. Expires December 8, 2014 [Page 7]
393    
394     Internet-Draft I2RS Traceability June 2014
395    
396    
397 marcus 18931 5.3. End of Message Marker
398 marcus 18720
399 marcus 18760 Because of variability within I2RS trace log fields, implementors
400 marcus 18762 MUST use a format-appropriate end of message (EOM) indicator in order
401     to signify the end of a particular record. That is, regardless of
402 marcus 18760 format, the I2RS trace log MUST provide a distinct way of
403     distinguishing between the end of one record and the beginning of
404 marcus 18948 another. For example, in a linear formated log (similar to syslog)
405     the EOM marker may be a newline character. In an XML formated log,
406     the schema would provide for element tags that denote beginning and
407     end of records. In a JSON formated log, the syntax would provide
408     record separation (likely by comma-separated array elements).
409    
410 marcus 18931 5.4. I2RS Trace Log Extensibility and Optional Fields
411 marcus 18760
412     [NOTE: This section is TBD based on further development of I2RS WG
413     milestones.]
414    
415 marcus 18931 5.5. I2RS Trace Log Syntax
416 marcus 18760
417 marcus 19726 The following describes the trace log information model using the
418     YANG modeling language [RFC6020].
419 marcus 18760
420 marcus 19726 5.5.1. Structure of the I2RS Trace Log
421    
422     The structure of the I2RS traceability model, as later defined in the
423     YANG module "i2rs-trace-log", is depicted in the following diagram.
424     This tree representation illustrates the structure of I2RS Trace Log
425     YANG model and does not depict all definitions; it is merely intended
426     to illustrate the overall structure.
427    
428 marcus 19723 module: i2rs-trace-log
429     +--rw i2rs-trace-log
430     +--rw log-enable? boolean
431     +--ro log-entry* [log-entry-id]
432     +--ro log-entry-id log-entry-id
433     +--ro timestamp timestamp
434     +--ro client-id client-id
435     +--ro actor-id actor-id
436     +--ro client-addr client-addr
437     +--ro operation operation
438     +--ro operation-data operation-data
439     +--ro result-code result-code
440 marcus 18720
441 marcus 19726
442 marcus 19723 The idea of using a UUID for the Client identifier ensures the ID is
443     unique not just in the scope of the current I2RS Agent, but across
444     Agents as well. This ensures that two clients that are unaware of
445 marcus 18729
446 marcus 18720
447 marcus 18931
448 marcus 19723 Clarke, et al. Expires December 8, 2014 [Page 8]
449 marcus 18931
450 marcus 19723 Internet-Draft I2RS Traceability June 2014
451 marcus 18931
452    
453 marcus 19726 each other will not allocate the same Client ID. That does not
454     preclude two Clients acting as one for purposes of high availability
455     from sharing the same UUID as generated by one one of the Clients.
456    
457     The "timestamp" field is defined in [RFC3339]. As stated in
458     Section 5.2 the fractional second format MUST be used to provide
459     proper granularity.
460    
461     The values for "operation", "operation-data" and "result-code" are
462 marcus 19723 suggestions as the protocol has not been defined yet. By making
463     these human-readable (as opposed to opcodes) the log becomes more
464 marcus 18948 easily consumable by operators and administrators trying to
465     troubleshoot issues relating to I2RS. Even in cases where the
466     operations or codes might appear as opcodes on the wire, their
467     textual translations MUST be included in the log. The opcodes
468     themselves MAY appear in parentheses after the textual
469     representation.
470    
471 marcus 19726 5.5.2. I2RS Trace Log Yang Module
472 marcus 19723
473 marcus 19726 The I2RS traceability model is defined in the following YANG module.
474    
475 marcus 19728 This YANG module imports typedefs from [RFC6021].
476 marcus 19726
477 marcus 19723 <CODE BEGINS>
478     file "i2rs-trace-log@2014-06-06.yang"
479     module i2rs-trace-log {
480     yang-version 1;
481     namespace "urn:TBD:params:xml:ns:yang:i2rs:trace-log";
482     // This namespace should be considered with other I2RS YANG
483     // models.
484     prefix i2rslog;
485    
486     import ietf-yang-types {
487     prefix "yang";
488     }
489    
490     import ietf-inet-types {
491     prefix "inet";
492     }
493    
494     organization "TBD";
495    
496     contact
497     "Joe Clarke jclarke@cisco.com
498     Gonzalo Salgueiro gsalguei@cisco.com
499     Carlos Pignataro cpignata@cisco.com";
500    
501 marcus 19726
502    
503    
504     Clarke, et al. Expires December 8, 2014 [Page 9]
505    
506     Internet-Draft I2RS Traceability June 2014
507    
508    
509 marcus 19723 description
510     "This module defines the model for I2RS traceability
511     based on the I2RS architecture as defined in
512     draft-ietf-i2rs-architecture.";
513    
514     reference
515     "draft-ietf-i2rs-architecture: An Architecture for the
516     Interface to the Routing System";
517    
518     revision "2014-06-03" {
519     description "Initial revision";
520     reference "TBD";
521     }
522    
523     typedef log-entry-id {
524     type uint64;
525     description
526     "A unique identifier for I2RS log entries.";
527     }
528    
529     typedef timestamp {
530     type yang:date-and-time;
531     description
532     "Timestamp for I2RS transactions.";
533     }
534    
535     typedef client-id {
536     type yang:uuid;
537     description
538     "The I2RS Client identifier used to authenticate
539     the Client to the I2RS Agent.";
540     }
541    
542     typedef actor-id {
543     type union {
544     type string {
545     pattern "[^\r\n]+";
546     }
547     type enumeration {
548     enum UNAVAILABLE {
549     description
550     "The Actor ID was not
551     specified by the Client.";
552     }
553     }
554     }
555     description
556     "Identifier used to trace the northbound actor
557 marcus 19726
558    
559    
560     Clarke, et al. Expires December 8, 2014 [Page 10]
561    
562     Internet-Draft I2RS Traceability June 2014
563    
564    
565 marcus 19723 driving the actions of the Client.";
566     }
567    
568     typedef client-addr {
569     type inet:ip-address;
570     description
571     "IP address of the client that connected to the
572     Agent.";
573     }
574    
575     typedef operation {
576     type string {
577     pattern "[a-zA-Z] [a-zA-Z_\-\(\)]*";
578     }
579     description
580     "This is the I2RS operation performed.";
581     }
582    
583     typedef operation-data {
584     type union {
585     type string;
586     type enumeration {
587     enum NULL {
588     description
589     "No additional operation
590     data was required.";
591     }
592     }
593     }
594     description
595     "Data passed to the Agent to complete the desired
596     operation.";
597     }
598    
599     typedef result-code {
600     type string {
601     pattern "[a-zA-Z0-9_\-\(\)]+";
602     }
603     description
604     "Result code for the operation.";
605     }
606    
607     container i2rs-trace-log {
608     description
609     "This is the model for I2RS traceability. An
610     I2RS log is comprised of the following mandatory
611     fields. Each field MUST be identified by a unique
612     log-entry-id.";
613 marcus 19726
614    
615    
616     Clarke, et al. Expires December 8, 2014 [Page 11]
617    
618     Internet-Draft I2RS Traceability June 2014
619    
620    
621 marcus 19723 leaf log-enable {
622     type boolean;
623     default "true";
624     description
625     "Enable/Disable I2RS logging.";
626     }
627     list log-entry {
628     key "log-entry-id";
629 marcus 19726 config false;
630 marcus 19723 description
631     "Each element in an I2RS trace log is
632     discrete and identified by its unique log
633     entry ID.";
634     leaf log-entry-id {
635     type log-entry-id;
636 marcus 19726 config false;
637 marcus 19723 description
638     "This is a unique identifier for
639     each entry in the I2RS trace log.
640     Since multiple operations can occur
641     from the same client at the same
642     time, it is important to have an
643     identifier that can be unambiguously
644     associated to a specific entry.";
645     }
646     leaf timestamp {
647     type timestamp;
648     config false;
649     mandatory true;
650     description
651     "The specific time, adhering to
652     RFC3339 format, at which the I2RS
653     transaction occurred. Given that
654     many I2RS transactions can occur in
655     rapid succession, the use of
656     fractional seconds MUST be used to
657     provide adequate granularity.";
658     reference
659     "RFC 3339: Date and Time on the
660     Internet: Timestamps";
661     }
662     leaf client-id {
663     type client-id;
664     config false;
665     mandatory true;
666     description
667     "The I2RS Client identifier used
668     to authenticate the Client to the
669 marcus 19726
670    
671    
672     Clarke, et al. Expires December 8, 2014 [Page 12]
673    
674     Internet-Draft I2RS Traceability June 2014
675    
676    
677 marcus 19723 I2RS Agent.";
678     }
679     leaf actor-id {
680     type actor-id;
681     config false;
682     mandatory true;
683     description
684     "This is an opaque identifier
685     that may be known to the Client
686     from a northbound controlling
687     application. This is used to
688     trace the northbound actor
689     driving the actions of the
690     Client. The Client may not
691     provide this identifier to the
692     Agent if there is no external
693     actor driving the Client. In
694     that case, the special value,
695     UNAVAILABLE is used to denote no
696     Actor ID.";
697     }
698     leaf client-addr {
699     type client-addr;
700     config false;
701     mandatory true;
702     description
703     "This is the IP address of the
704     client that connected to the Agent.";
705     }
706     leaf operation {
707     type operation;
708     config false;
709     mandatory true;
710     description
711     "This is the I2RS operation
712     performed.";
713     }
714     leaf operation-data {
715     type operation-data;
716     config false;
717     mandatory true;
718     description
719     "This field comprises the data
720     passed to the Agent to complete the
721     desired operation. If no additional
722     operation data is required, then this
723     field should be set to the special
724     value, NULL.";
725 marcus 19726
726    
727    
728     Clarke, et al. Expires December 8, 2014 [Page 13]
729    
730     Internet-Draft I2RS Traceability June 2014
731    
732    
733 marcus 19723 }
734     leaf result-code {
735     type result-code;
736     config false;
737     mandatory true;
738     description
739     "This field holds the result of
740     the operation. In the case of RIB
741     operations, this MUST be the return
742     code as specified in Section 4 of
743     draft-nitinb-i2rs-rib-info-model.
744     The operation may not complete with
745     a result code in the case of a
746     timeout. If the operation fails to
747     complete, it MUST still log the
748     attempted operation with an
749     appropriate result code (e.g., a
750     result code indicating a timeout).";
751     reference
752     "draft-nitinb-i2rs-rib-info-model:
753     Routing Information Base Info Model";
754     }
755     }
756     }
757     }
758     <CODE ENDS>
759    
760 marcus 18931 6. Examples
761 marcus 18720
762 marcus 18730 Here is a proposed sample of what the fields might look like in an
763     I2RS trace log. This is only an early proposal. These values are
764     subject to change.
765 marcus 18720
766 marcus 18730
767 marcus 19723 Entry ID: 1
768 marcus 18747 Timestamp: 2013-09-03T12:00:01.21+00:00
769     Client ID: 5CEF1870-0326-11E2-A21F-0800200C9A66
770     Actor ID: com.example.RoutingApp
771 marcus 18741 Client Address: 192.0.2.2
772     Operation: ROUTE_ADD
773     Operation Data: PREFIX 203.0.113.0 PREFIX-LEN 24 NEXT-HOP
774     198.51.100.1
775     Result Code: SUCCESS(0)
776 marcus 18730
777 marcus 19726
778    
779    
780    
781    
782    
783    
784     Clarke, et al. Expires December 8, 2014 [Page 14]
785    
786     Internet-Draft I2RS Traceability June 2014
787    
788    
789 marcus 18931 7. Operational Guidance
790 marcus 18717
791 marcus 18741 Specific operational procedures regarding temporary log storage,
792     rollover, retrieval, and access of I2RS trace logs is out of scope
793     for this document. Organizations employing I2RS trace logging are
794     responsible for establishing proper operational procedures that are
795     appropriately suited to their specific requirements and operating
796     environment. In this section we only provide fundamental and
797     generalized operational guidelines that are implementation-
798     independent.
799 marcus 18726
800 marcus 18931 7.1. Trace Log Creation
801 marcus 18726
802 marcus 18734 The I2RS Agent interacts with the Routing and Signaling functions of
803     the Routing Element. Since the I2RS Agent is responsible for
804     actually making the routing changes on the associated network device,
805 marcus 19723 it creates and maintains a log of transactions that can be retrieved
806     to troubleshoot I2RS-related impact to the network.
807 marcus 18948
808 marcus 18931 7.2. Trace Log Temporary Storage
809 marcus 18734
810 marcus 18741 The trace information may be temporarily stored either in an in-
811     memory buffer or as a file local to the Agent. Care should be given
812     to the number of I2RS transactions expected on a given agent so that
813     the appropriate storage medium is used and to maximize the
814     effectiveness of the log while not impacting the performance and
815 marcus 18931 health of the Agent. Section 7.3 talks about rotating the trace log
816 marcus 18741 in order to preserve the transaction history without exhausting Agent
817     or network device resources. It is perfectly acceptable, therefore,
818     to use both an in-memory buffer for recent transactions while
819     rotating or archiving older transactions to a local file.
820 marcus 18727
821 marcus 18734 It is outside the scope of this document to specify the
822     implementation details (i.e., size, throughput, data protection,
823 marcus 18741 privacy, etc.) for the physical storage of the I2RS log file. Data
824     retention policies of the I2RS traceability log is also outside the
825     scope of this document.
826 marcus 18730
827 marcus 18931 7.3. Trace Log Rotation
828 marcus 18747
829 marcus 18718 In order to prevent the exhaustion of resources on the I2RS Agent or
830 marcus 18931 its associated network device, it is RECOMMENDED that the I2RS Agent
831     implements trace log rotation. The details on how this is achieved
832     are left to the implementation and outside the scope of this
833     document. However, it should be possible to do file rotation based
834     on either time or size of the current trace log. If file rollover is
835     supported, multiple archived log files should be supported in order
836 marcus 19726
837    
838    
839    
840     Clarke, et al. Expires December 8, 2014 [Page 15]
841    
842     Internet-Draft I2RS Traceability June 2014
843    
844    
845 marcus 18931 to maximize the troubleshooting and accounting benefits of the trace
846     log.
847 marcus 18717
848 marcus 18931 7.4. Trace Log Retrieval
849 marcus 18717
850 marcus 18734 Implementors are free to provide their own, proprietary interfaces
851     and develop custom tools to retrieve and display the I2RS trace log.
852     These may include the display of the I2RS trace log as Command Line
853     Interface (CLI) output. However, a key intention of defining this
854     information model is to establish an implementor-agnostic and
855     consistent interface to collect I2RS trace data. Correspondingly,
856     retrieval of the data should also be made implementor-agnostic.
857 marcus 18717
858 marcus 18739 The following three sections describe potential ways the trace log
859     can be accessed. At least one of these three MUST be used, with the
860     I2RS mechanisms being preferred as they are implementor-independent
861     approaches to retrieving the data.
862 marcus 18718
863 marcus 19723 7.4.1. Retrieval Via Syslog
864 marcus 18948
865 marcus 18717 The syslog protocol [RFC5424] is a standard way of sending event
866 marcus 18734 notification messages from a host to a collector. However, the
867 marcus 18717 protocol does not define any standard format for storing the
868     messages, and thus implementors of I2RS tracing would be left to
869     define their own format. So, while the data contained within the
870     syslog message would adhere to this information model, and may be
871 marcus 18718 consumable by a human operator, it would not be easily parseable by a
872 marcus 18727 machine. Therefore, syslog MAY be employed as a means of retrieving
873     or disseminating the I2RS trace log contents.
874    
875 marcus 18931 7.4.2. Retrieval Via I2RS Information Collection
876 marcus 18727
877     Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture]
878     defines a mechanism for information collection. The information
879 marcus 18717 collected includes obtaining a snapshot of a large amount of data
880     from the network element. It is the intent of I2RS to make this data
881     available in an implementor-agnostic fashion. Therefore, the I2RS
882 marcus 18718 trace log SHOULD be made available via the I2RS information
883     collection mechanism either as a single snapshot or via a
884     subscription stream.
885 marcus 18717
886 marcus 18931 7.4.3. Retrieval Via I2RS Pub-Sub
887 marcus 18717
888 marcus 18735 Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture]
889     goes on to define a publish-subscribe mechanism for a feed of changes
890     happening within the I2RS layer. I2RS Agents SHOULD support
891 marcus 18739 publishing I2RS trace log information to that feed as described in
892     that document. Subscribers would then receive a live stream of I2RS
893 marcus 19726
894    
895    
896     Clarke, et al. Expires December 8, 2014 [Page 16]
897    
898     Internet-Draft I2RS Traceability June 2014
899    
900    
901 marcus 18739 interactions in trace log format and could flexibly choose to do a
902     number of things with the log messages. For example, the subscribers
903     could log the messages to a datastore, aggregate and summarize
904 marcus 18741 interactions from a single client, etc. Using pub-sub for the
905     purpose of logging I2RS interactions augments the areas described by
906     [I-D.camwinget-i2rs-pubsub-sec]. The full range of potential
907 marcus 18739 activites is virtually limitless and the details of how they are
908     performed are outside the scope of this document, however.
909 marcus 18735
910 marcus 18931 8. IANA Considerations
911 marcus 18735
912 marcus 19723 The YANG module implies a namespace that will need to be registered
913     with IANA. However, the I2RS WG will likely request such a namespace
914 marcus 19726 for other work, so the registration of that namespace may occur in a
915     separate document. This section will be updated as these WG
916     decisions are made.
917 marcus 18717
918 marcus 18931 9. Security Considerations
919 marcus 18717
920 marcus 18734 The I2RS trace log, like any log file, reveals the state of the
921     entity producing it as well as the identifying information elements
922     and detailed interactions of the system containing it. The
923     information model described in this document does not itself
924     introduce any security issues, but it does define the set of
925     attributes that make up an I2RS log file. These attributes may
926     contain sensitive information and thus should adhere to the security,
927     privacy and permission policies of the organization making use of the
928     I2RS log file.
929 marcus 18717
930 marcus 18734 It is outside the scope of this document to specify how to protect
931     the stored log file, but it is expected that adequate precautions and
932     security best practices such as disk encryption, appropriately
933     restrictive file/directory permissions, suitable hardening and
934     physical security of logging entities, mutual authentication,
935     transport encryption, channel confidentiality, and channel integrity
936     if transferring log files. Additionally, the potentially sensitive
937 marcus 18932 information contained in a log file SHOULD be adequately anonymized
938     or obfuscated by operators to ensure its privacy.
939 marcus 18717
940 marcus 18932 10. Acknowledgments
941 marcus 18717
942 marcus 18935 The authors would like to thank Alia Atlas for her initial feedback
943     and overall support for this work. Additionally, the authors
944 marcus 19726 acknowledge Alvaro Retana, Russ White, Matt Birkner, Jeff Haas, Joel
945     Halpern and Dean Bogdanovich for their reviews, contributed text, and
946     suggested improvements to this document.
947 marcus 18717
948 marcus 19726
949    
950    
951    
952     Clarke, et al. Expires December 8, 2014 [Page 17]
953    
954     Internet-Draft I2RS Traceability June 2014
955    
956    
957 marcus 18932 11. References
958 marcus 18735
959 marcus 18932 11.1. Normative References
960 marcus 18735
961 marcus 18931 [I-D.ietf-i2rs-architecture]
962 marcus 18935 Atlas, A., Halpern, J., Hares, S., Ward, D., and T.
963     Nadeau, "An Architecture for the Interface to the Routing
964     System", draft-ietf-i2rs-architecture-00 (work in
965     progress), August 2013.
966    
967 marcus 18726 [I-D.ietf-i2rs-problem-statement]
968     Atlas, A., Nadeau, T., and D. Ward, "Interface to the
969 marcus 18729 Routing System Problem Statement", draft-ietf-i2rs-
970     problem-statement-00 (work in progress), August 2013.
971 marcus 18726
972 marcus 18718 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
973     Requirement Levels", BCP 14, RFC 2119, March 1997.
974 marcus 18717
975 marcus 19723 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
976     Network Configuration Protocol (NETCONF)", RFC 6020,
977     October 2010.
978 marcus 18717
979 marcus 19726 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021,
980     October 2010.
981    
982 marcus 18932 11.2. Informative References
983 marcus 18717
984 marcus 18741 [I-D.camwinget-i2rs-pubsub-sec]
985     Beck, K., Cam-Winget, N., and D. McGrew, "Using the
986     Publish-Subscribe Model in the Interface to the Routing
987     System", draft-camwinget-i2rs-pubsub-sec-00 (work in
988     progress), July 2013.
989    
990 marcus 18718 [I-D.nitinb-i2rs-rib-info-model]
991     Bahadur, N., Folkes, R., Kini, S., and J. Medved, "Routing
992 marcus 18729 Information Base Info Model", draft-nitinb-i2rs-rib-info-
993     model-02 (work in progress), August 2013.
994 marcus 18717
995 marcus 18728 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
996     Internet: Timestamps", RFC 3339, July 2002.
997 marcus 18717
998 marcus 18932 [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, March 2009.
999 marcus 18717
1000 marcus 18932 [RFC5737] Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks
1001     Reserved for Documentation", RFC 5737, January 2010.
1002 marcus 18746
1003 marcus 19726
1004    
1005    
1006    
1007    
1008     Clarke, et al. Expires December 8, 2014 [Page 18]
1009    
1010     Internet-Draft I2RS Traceability June 2014
1011    
1012    
1013 marcus 18932 Authors' Addresses
1014 marcus 18727
1015     Joe Clarke
1016     Cisco Systems, Inc.
1017     7200-12 Kit Creek Road
1018     Research Triangle Park, NC 27709
1019     US
1020    
1021     Phone: +1-919-392-2867
1022     Email: jclarke@cisco.com
1023    
1024    
1025 marcus 18726 Gonzalo Salgueiro
1026 marcus 18741 Cisco Systems, Inc.
1027 marcus 18726 7200-12 Kit Creek Road
1028     Research Triangle Park, NC 27709
1029     US
1030    
1031     Email: gsalguei@cisco.com
1032    
1033    
1034 marcus 18741 Carlos Pignataro
1035     Cisco Systems, Inc.
1036     7200-12 Kit Creek Road
1037     Research Triangle Park, NC 27709
1038     US
1039 marcus 18726
1040 marcus 18741 Email: cpignata@cisco.com
1041 marcus 18726
1042    
1043    
1044 marcus 18735
1045    
1046    
1047    
1048    
1049    
1050    
1051    
1052    
1053    
1054    
1055    
1056    
1057    
1058    
1059 marcus 18932
1060    
1061    
1062    
1063    
1064 marcus 19723 Clarke, et al. Expires December 8, 2014 [Page 19]

  ViewVC Help
Powered by ViewVC 1.1.27