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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

1 <?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 <!ENTITY RFC5737 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5737.xml">
8 <!ENTITY RFC6020 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6020.xml">
9 <!ENTITY RFC6021 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6021.xml">
10 <!ENTITY I2RS-ARCHITECTURE SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-i2rs-architecture.xml">
11 <!ENTITY I2RS-PROBLEM-STATEMENT SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-i2rs-problem-statement.xml">
12 <!ENTITY I2RS-RIB-INFO-MODEL SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.nitinb-i2rs-rib-info-model.xml">
13 <!ENTITY I2RS-PUBSUB-SEC SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.camwinget-i2rs-pubsub-sec.xml">
14 ]>
15 <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
16 <?rfc toc="yes"?>
17 <?rfc tocompact="yes"?>
18 <?rfc tocdepth="4"?>
19 <?rfc tocindent="yes"?>
20 <?rfc symrefs="yes"?>
21 <?rfc sortrefs="yes"?>
22 <?rfc comments="yes"?>
23 <?rfc inline="yes"?>
24 <?rfc compact="yes"?>
25 <?rfc subcompact="no"?>
26 <rfc category="info" docName="draft-clarke-i2rs-traceability-02"
27 ipr="trust200902">
28 <front>
29 <title abbrev="I2RS Traceability">Interface to the Routing System
30 (I2RS) Traceability: Framework and Information Model</title>
31
32 <author fullname="Joe Clarke" initials="J." surname="Clarke">
33 <organization abbrev="Cisco">Cisco Systems, Inc.</organization>
34
35 <address>
36 <postal>
37 <street>7200-12 Kit Creek Road</street>
38
39 <city>Research Triangle Park</city>
40
41 <region>NC</region>
42
43 <code>27709</code>
44
45 <country>US</country>
46 </postal>
47
48 <phone>+1-919-392-2867</phone>
49
50 <email>jclarke@cisco.com</email>
51 </address>
52 </author>
53
54 <author fullname="Gonzalo Salgueiro" initials="G."
55 surname="Salgueiro">
56 <organization abbrev="Cisco">Cisco Systems, Inc.</organization>
57
58 <address>
59 <postal>
60 <street>7200-12 Kit Creek Road</street>
61
62 <city>Research Triangle Park</city>
63
64 <region>NC</region>
65
66 <code>27709</code>
67
68 <country>US</country>
69 </postal>
70
71 <email>gsalguei@cisco.com</email>
72 </address>
73 </author>
74
75 <author fullname="Carlos Pignataro" initials="C."
76 surname="Pignataro">
77 <organization abbrev="Cisco">Cisco Systems, Inc.</organization>
78
79 <address>
80 <postal>
81 <street>7200-12 Kit Creek Road</street>
82
83 <city>Research Triangle Park</city>
84
85 <region>NC</region>
86
87 <code>27709</code>
88
89 <country>US</country>
90 </postal>
91
92 <email>cpignata@cisco.com</email>
93 </address>
94 </author>
95
96 <date/>
97
98 <area>Routing</area>
99
100 <workgroup>I2RS</workgroup>
101
102 <keyword>I2RS</keyword>
103
104 <keyword>I2RS Traceability</keyword>
105
106 <keyword>Traceability</keyword>
107
108 <abstract>
109 <t>This document describes a framework for traceability in the
110 Interface to the Routing System (I2RS) and information model for
111 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 purposes.</t>
120 </abstract>
121 </front>
122
123 <middle>
124 <section anchor="intro" title="Introduction">
125 <t>The architecture for the Interface to the Routing System
126 (<xref target="I-D.ietf-i2rs-architecture"/>) specifies that
127 I2RS Clients wishing to retrieve or change routing state on a
128 routing element MUST authenticate to an I2RS Agent. The I2RS
129 Client will have a unique identity it provides for
130 authentication, and should provide another, opaque identifier
131 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 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
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 </section>
149
150 <section anchor="terminology" title="Terminology and Conventions">
151 <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
156 <t>The architecture specification for I2RS <xref
157 target="I-D.ietf-i2rs-architecture"/> defines additional terms
158 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 be familiar with the terminology and concepts defined in <xref
161 target="I-D.ietf-i2rs-architecture"/>.</t>
162
163 <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 </section>
168
169 <section anchor="motivation" title="Motivation">
170 <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 event-level granularity of the routing system compliant with the
180 requirements of I2RS (Section 5 of <xref
181 target="I-D.ietf-i2rs-problem-statement"/>).</t>
182 </section>
183
184 <section anchor="use_cases" title="Use Cases">
185 <t>An obvious motivation for I2RS traceability is the need to
186 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 <t>Automated event correlation, trend analysis, and anomaly
212 detection.</t>
213
214 <t>Trace log storage for offline (manual or tools)
215 analysis.</t>
216
217 <t>Improved accounting of routing system transactions.</t>
218
219 <t>Standardized structured data format for writing common
220 tools.</t>
221
222 <t>Common reference for automated testing and incident
223 reporting.</t>
224
225 <t>Real-time monitoring and troubleshooting.</t>
226
227 <t>Enhanced network audit, management and forensic analysis
228 capabilities.</t>
229 </list></t>
230 </section>
231
232 <section anchor="information_model" title="Information Model">
233 <section anchor="info_framework"
234 title="I2RS Traceability Framework">
235 <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
239 <t>The interaction between the optional northbound actor, I2RS
240 Client, I2RS Agent, the Routing System and the data captured
241 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 <artwork align="center"><![CDATA[
248 +-------------+
249 |Actor |
250 |.............|
251 | Actor ID |
252 +-------------+
253 ^
254 | 0 .. N
255 |
256 V
257 +-------------+
258 |I2RS Client |
259 |.............|
260 | Client ID |
261 +-------------+
262 ^
263 | 1 .. N
264 |
265 V
266 +-------------+ +-----------------------------+
267 |I2RS Agent |---------------->|Trace Log |
268 | | |.............................|
269 +-------------+ |Log Entry [1 .. N] |
270 ^ |.............................|
271 | |Timestamp |
272 | |Client ID |
273 | ^ |Actor ID |
274 Operation + | Result Code |Client Address |
275 Op Data | |Operation |
276 V | |Operation Data |
277 | |Result Code |
278 V |End Of Message |
279 +-------------+ +-----------------------------+
280 |Routing |
281 |System |
282 +-------------+
283 ]]></artwork>
284 </figure>
285 </section>
286
287 <section anchor="info_required"
288 title="I2RS Trace Log Mandatory Fields">
289 <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
294 <t>The list below describes the fields captured in the I2RS
295 trace log.</t>
296
297 <t><list style="hanging">
298 <t hangText="Entry ID: ">This is a unique identifier for
299 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 <t hangText="Timestamp: ">The specific time, adhering to
305 <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
310 <t hangText="Client Identifier: ">The I2RS Client
311 identifier used to authenticate the Client to the I2RS
312 Agent.</t>
313
314 <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 The Client may not provide this identifier to the Agent if
319 there is no external actor driving the Client. However,
320 this field MUST be logged. If the Client does not provide
321 an actor ID, then the Agent MUST log an UNAVAILABLE value
322 in the field.</t>
323
324 <t hangText="Client Address: ">This is the network address
325 of the client that connected to the Agent. For example,
326 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
330 <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
334 <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 include interface information. Some operations may not
342 provide operation data, and in those cases this field MUST
343 be logged as a NULL string.</t>
344
345 <t hangText="Result Code: ">This field holds the result of
346 the operation. In the case of RIB operations, this MUST be
347 the return code as specified in Section 4 of <xref
348 target="I-D.nitinb-i2rs-rib-info-model"/>. The operation
349 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
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 </section>
359
360 <section anchor="eom" title="End of Message Marker">
361 <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 </section>
374
375 <section anchor="info_optional"
376 title="I2RS Trace Log Extensibility and Optional Fields">
377 <t/>
378
379 <t>[NOTE: This section is TBD based on further development of
380 I2RS WG milestones.]</t>
381
382 <t/>
383 </section>
384
385 <section title="I2RS Trace Log Syntax">
386 <t>The following describes the trace log information model
387 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 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
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 <section title="I2RS Trace Log Yang Module">
442 <t>The I2RS traceability model is defined in the following
443 YANG module.</t>
444
445 <t>This YANG module imports typedefs from <xref
446 target="RFC6021"/>.<figure>
447 <artwork><![CDATA[
448 <CODE BEGINS>
449 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 config false;
577 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 config false;
584 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 <CODE ENDS>
690 ]]></artwork>
691 </figure></t>
692 </section>
693 </section>
694 </section>
695
696 <section title="Examples">
697 <t>Here is a proposed sample of what the fields might look like
698 in an I2RS trace log. This is only an early proposal. These
699 values are subject to change. <vspace blankLines="1"/></t>
700
701 <figure>
702 <artwork><![CDATA[
703 Entry ID: 1
704 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 ]]></artwork>
713 </figure>
714 </section>
715
716 <section anchor="operational_guidance"
717 title="Operational Guidance">
718 <t/>
719
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 <t/>
730
731 <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 </section>
739
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 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
755 <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 I2RS log file. Data retention policies of the I2RS
759 traceability log is also outside the scope of this
760 document.</t>
761 </section>
762
763 <section anchor="log_rotation" title="Trace Log Rotation">
764 <t>In order to prevent the exhaustion of resources on the I2RS
765 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 </section>
775
776 <section anchor="log_retrieval" title="Trace Log Retrieval">
777 <t>Implementors are free to provide their own, proprietary
778 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
786 <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
791 <section anchor="trace_syslog" title="Retrieval Via Syslog">
792 <t>The syslog protocol <xref target="RFC5424"/> is a
793 standard way of sending event notification messages from a
794 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
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 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
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 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 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 </section>
837 </section>
838 </section>
839
840 <section anchor="IANA" title="IANA Considerations">
841 <t>The YANG module implies a namespace that will need to be
842 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 </section>
847
848 <section anchor="Security" title="Security Considerations">
849 <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 making use of the I2RS log file.</t>
858
859 <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 </section>
870
871 <section anchor="acknowledgements" title="Acknowledgments">
872 <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 </section>
879 </middle>
880
881 <back>
882 <references title="Normative References">
883 &I2RS-ARCHITECTURE;
884
885 &I2RS-PROBLEM-STATEMENT;
886
887 &RFC2119;
888
889 &RFC6020;
890
891 &RFC6021;
892 </references>
893
894 <references title="Informative References">
895 &I2RS-RIB-INFO-MODEL;
896
897 &I2RS-PUBSUB-SEC;
898
899 &RFC3339;
900
901 &RFC5424;
902
903 &RFC5737;
904 </references>
905 </back>
906 </rfc>

  ViewVC Help
Powered by ViewVC 1.1.27