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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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

  ViewVC Help
Powered by ViewVC 1.1.27