ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 18726 - (hide annotations) (download) (as text)
Mon Sep 2 00:06:46 2013 UTC (6 years, 7 months ago) by marcus
Original Path: trunk/i2rs-traceability/draft-clarke-i2rs-traceability.xml
File MIME type: text/xml
File size: 20449 byte(s)
Revert some of Gonzalo's changes to fix missing references.

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 marcus 18726 <!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
7 marcus 18720 <!ENTITY RFC4122 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4122.xml">
8     <!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">
9 marcus 18717 <!ENTITY RFC5424 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5424.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     ]>
14     <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
15     <?rfc toc="yes"?>
16 marcus 18725 <?rfc tocompact="yes"?>
17 marcus 18717 <?rfc tocdepth="4"?>
18 marcus 18725 <?rfc tocindent="yes"?>
19 marcus 18717 <?rfc symrefs="yes"?>
20 marcus 18725 <?rfc sortrefs="yes"?>
21     <?rfc comments="yes"?>
22     <?rfc inline="yes"?>
23     <?rfc compact="yes"?>
24     <?rfc subcompact="no"?>
25 marcus 18717 <rfc category="info" docName="draft-clarke-i2rs-traceability-00" ipr="trust200902">
26     <front>
27 marcus 18725 <title abbrev="I2RS Traceability">Information Model for
28     Traceability in the Interface to the Routing System (I2RS)</title>
29 marcus 18717 <author fullname="Joe Clarke" initials="J." surname="Clarke">
30 marcus 18718 <organization abbrev="Cisco">Cisco Systems, Inc.</organization>
31 marcus 18717 <address>
32     <postal>
33     <street>7200-12 Kit Creek Road</street>
34     <city>Research Triangle Park</city>
35     <region>NC</region>
36     <code>27709</code>
37     <country>US</country>
38     </postal>
39     <phone>+1-919-392-2867</phone>
40     <email>jclarke@cisco.com</email>
41     </address>
42     </author>
43 marcus 18725 <author fullname="Gonzalo Salgueiro" initials="G." surname="Salgueiro">
44     <organization abbrev="Cisco">Cisco Systems</organization>
45     <address>
46     <postal>
47     <street>7200-12 Kit Creek Road</street>
48     <city>Research Triangle Park</city>
49     <region>NC</region>
50     <code>27709</code>
51     <country>US</country>
52     </postal>
53     <email>gsalguei@cisco.com</email>
54     </address>
55     </author>
56 marcus 18718 <date/>
57 marcus 18717 <area>Routing</area>
58     <workgroup>I2RS</workgroup>
59     <keyword>I2RS</keyword>
60 marcus 18725 <keyword>I2RS Traceability</keyword>
61 marcus 18717 <keyword>Traceability</keyword>
62     <abstract>
63 marcus 18725 <t>This document specifies requirements and defines an
64     information model for recording interactions between elements
65     implementing the Interface to the Routing System (I2RS)
66     protocol. This framework provides a consistent tracing interface
67     that can be used uniformly by the different I2RS elements to
68     record what was done, by which element, and when. It aims to
69     improve the management of I2RS implementations, and can be used
70     for troubleshooting, auditing, forensics, and accounting
71     purposes.</t>
72 marcus 18717 </abstract>
73     </front>
74     <middle>
75 marcus 18725 <section anchor="intro" title="Introduction">
76 marcus 18717 <t>The architecture for the Interface to the Routing System
77 marcus 18725 (<xref target="I-D.ietf-i2rs-architecture"/>) specifies that
78     I2RS Clients wishing to retrieve or change routing state on a
79     network device MUST authenticate to an I2RS Agent. The I2RS
80     Client will have a unique identity it provides for
81     authentication, and should provide another, opaque identifier
82     for applications communicating through it. All of this is
83     critical information to be used for troubleshooting I2RS
84     interactions.</t>
85     <t>This document specifies requirements and describes the
86     information model for traceability attributes that must be
87     collected and logged by I2RS Agents in order to effectively
88     troubleshoot I2RS interactions. In this context, effective
89     troubleshooting means being able to identify what operation was
90     performed by a specific I2RS Client, what was the result of the
91     operation, and when that operation was performed.</t>
92 marcus 18717 </section>
93 marcus 18725 <section anchor="terminology" title="Terminology">
94     <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
96     "OPTIONAL" in this document are to be interpreted as described
97     in <xref target="RFC2119"/>.</t>
98     <t>The architecture specification for I2RS <xref target="I-D.ietf-i2rs-architecture"/> defines additional terms
99     used in this document that are specific to the I2RS domain, such
100     as "I2RS Agent", "I2RS Client", etc. The reader is expected to
101     be familiar with the terminology and concepts defined in <xref target="I-D.ietf-i2rs-architecture"/>.</t>
102 marcus 18718 </section>
103 marcus 18725 <section anchor="motivation" title="Motivation and Use Cases">
104     <t>As networks grow, so too does the scale and complexity of
105     routing systems. I2RS offers a standard, programmatic interface
106     allowing improved automation and more granular control over an
107     increasingly dynamic routing and signaling state. This ability
108     to automate even complex policy-based controls highlights the
109     need for an equally scalable traceability function to provide
110     event-level granularity of the routing system compliant with the
111     requirements of I2RS (Section 5 of <xref target="I-D.ietf-i2rs-problem-statement"/>.</t>
112     <t>An obvious motivation for I2RS traceability is the need to
113     troubleshoot these increasingly complex routing systems. For
114     example, since I2RS is a high-throughput multi-channel, full
115     duplex and highly responsive interface, I2RS Clients may be
116     performing a large number of operations on I2RS Agents
117     concurrently or at nearly the same time and quite possibly in
118     very rapid succession. As these many changes are made, the
119     network reacts accordingly. These changes might lead to a race
120     condition, performance issues, data loss, or disruption of
121     services. In order to isolate the root cause of these issues it
122     is critical that a network operator or administrator has
123     visibility into what changes were made via I2RS at a specific
124     time.</t>
125     <t>As I2RS becomes increasingly pervasive in networks, a
126     traceability model offers significant advantages and facilitates
127     the following use cases:</t>
128     <t>
129     <list style="symbols">
130     <t>Automated event correlation, trend analysis, and anomaly
131     detection.</t>
132     <t>Trace log storage for offline (manual or tools)
133     analysis.</t>
134     <t>Improved accounting of routing system transactions.</t>
135     <t>Standardized structured data format for writing common
136     tools.</t>
137     <t>Common reference for automated testing and incident
138     reporting.</t>
139     <t>Real-time monitoring and troubleshooting.</t>
140     <t>Enhanced network audit, management and forensic analysis
141     capabilities.</t>
142     </list>
143     </t>
144     </section>
145     <section anchor="information_model" title="Information Model">
146     <section anchor="info_required" title="I2RS Trace Log Mandatory Fields">
147     <t>In order to ensure that each I2RS interaction can be
148     properly traced back to the Client that made the request at a
149     specific point in time, the following information MUST be
150     collected and stored by the Agent.</t>
151     <t>The interaction between the optional northbound actor, I2RS
152     Client, I2RS Agent, the Routing System and the data captured
153     in the I2RS trace log is shown in <xref target="i2rs_interaction_trace"/>.</t>
154 marcus 18719 <figure align="center" anchor="i2rs_interaction_trace" title="I2RS Interaction Trace Log Capture">
155 marcus 18725 <artwork align="center"><![CDATA[
156 marcus 18718 +-------------+
157     |Actor |
158     |.............|
159     | Actor ID |
160     +-------------+
161 marcus 18719 :
162     :
163 marcus 18718 V
164     +-------------+
165     |I2RS Client |
166     |.............|
167     | Client ID |
168     | [Actor ID] |
169     +-------------+
170     |
171     |
172     V
173     +-------------+ +-----------------------------+
174     |I2RS Agent |---------------->|Trace Log |
175     | | |.............................|
176     +-------------+ |Timestamp |
177     ^ |Client ID |
178     | ^ |[Actor ID] |
179 marcus 18719 Operation + | Result Code |Client Address |
180     [Op Data] | |Operation |
181     V | |Operation Data |
182     V |Result Code |
183     +-------------+ +-----------------------------+
184     |Routing |
185 marcus 18718 |System |
186     +-------------+
187 marcus 18725 ]]></artwork>
188 marcus 18718 </figure>
189 marcus 18725 <t>The list below describes the fields captured in the I2RS
190     trace log.</t>
191 marcus 18718 <t>
192     <list style="hanging">
193     <t hangText="Timestamp: ">The specific time, adhering to
194 marcus 18725 <xref target="RFC3339"/> format, at which the I2RS
195     transaction occurred. Given that many I2RS transactions
196     can occur in rapid succession, the use of fractional
197     seconds MUST be used to provide adequate granularity.</t>
198     <t hangText="Client Identifier: ">The I2RS Client
199     identifier used to authenticate the Client to the I2RS
200     Agent.</t>
201     <t hangText="Actor Identifier: ">This is an optional
202     opaque identifier that may be known to the Client from a
203     northbound controlling application. This, if provided, is
204     used to trace the northbound actor driving the actions of
205     the Client. If provided by the Client, this identifier
206     MUST be included as part of the trace log.</t>
207     <t hangText="Client Address: ">This is the network address
208     of the client that connected to the Agent. For example,
209     this may be an IPv4 or IPv6 address.</t>
210     <t hangText="Operation: ">This is the I2RS operation
211     performed. For example, this may be an add route operation
212     if a route is being inserted into a routing table.</t>
213     <t hangText="Operation Data: ">This field comprises the
214     data passed to the Agent to complete the desired
215     operation. For example, if the operation is a route add
216     operation, the Operation Data would include the route
217     prefix, prefix length, and next hop information to be
218     inserted as well as the specific routing table to which
219     the route will be added. The operation data can also
220 marcus 18718 include interface information.</t>
221 marcus 18725 <t hangText="Result Code: ">This field holds the result of
222     the operation. In the case of RIB operations, this MUST be
223     the return code as specified in Section 4 of <xref target="I-D.nitinb-i2rs-rib-info-model"/>.</t>
224 marcus 18718 </list>
225     </t>
226 marcus 18725 </section>
227     <section anchor="info_optional" title="I2RS Trace Log Extensibility and Optional Fields">
228     <t>TBD</t>
229     </section>
230     <section anchor="syntax" title="I2RS Trace Log Syntax">
231     <t>The following describes the trace log information model
232     using Augmented Backus-Naur Form (ABNF) syntax <xref target="RFC5234"/>:</t>
233     <figure>
234     <artwork type="abnf"><![CDATA[i2rs-trace-log = timestamp client-id [actor-id] client-addr operation
235 marcus 18721 [operation-data] result-code
236     client-id = uuid
237     actor-id = byte-string
238 marcus 18725 byte-string = 1*( %x01-09 / %x0B-0C / %x0E-FF )
239     ; any byte except NUL, CR or LF
240 marcus 18721 client-addr = IP-literal / IPv4address
241     operation = ALPHA *( ALPHA / "_" / "-" / "(" / ")" )
242     operation-data = *VCHAR
243 marcus 18725 result-code = 1*( ALPHA / DIGIT / "-" / "_" / "(" / ")" ) ]]></artwork>
244     </figure>
245     <t>The ABNF syntax rules &lt;IP-literal&gt;,
246     &lt;IPv4address&gt;, and &lt;sub-delims&gt; are specified in
247     <xref target="RFC3986"/>. The core rules &lt;DIGIT&gt;,
248     &lt;HEXDIGIT&gt;, &lt;ALPHA&gt; and &lt;VCHAR&gt; are used as
249     described in Appendix B of <xref target="RFC5234"/>.</t>
250     <t>Here, &lt;uuid&gt; is specified in <xref target="RFC4122"/>. The idea of using a UUID for the Client
251     identifier ensures the ID is unique. That does not preclude
252     two Clients acting as one for purposes of high availability
253     from sharing the same UUID as generated by one one of the
254     Clients. [[Note: the format of the Client ID has not yet been
255     decided by the I2RS WG. This is subject to change.]]</t>
256     <t>The &lt;timestamp&gt; field is defined in <xref target="RFC3339"/>. As stated in <xref target="info_required"/> the fractional second format MUST be
257     used to provide proper granularity.</t>
258     <t>The values for &lt;operation&gt;, &lt;operation-data&gt;
259     and &lt;result-code&gt; are suggestions as the protocol has
260     not been defined yet. By making these human-readable (as
261     opposed to opcodes) the log becomes more easily consumable by
262     operators and administrators trying to troubleshoot issues
263     relating to I2RS. Even in cases where the operations or codes
264     might appear as opcodes on the wire, their textual
265     translations MUST be included in the log. The opcodes
266     themselves MAY appear in parentheses after the textual
267     representation.</t>
268 marcus 18718 </section>
269 marcus 18725 </section>
270     <section title="Examples">
271     <t/>
272     <t>[NOTE: To put in a name:value pairing of *proposed* values
273     now with a note that this is subject to change and proposed
274     only.]</t>
275     <t/>
276     </section>
277     <section anchor="operational_guidance" title="Operational Guidance">
278     <t/>
279     <t>[NOTE: Gonzalo to write some introductory text and the take a
280     pass at the sub-sections.]</t>
281     <t/>
282     <section anchor="trace_storage" title="Trace Log Storage">
283 marcus 18717 <t>The trace information may be stored either in an in-memory
284 marcus 18725 buffer or as a file local to the Agent. Care should be given
285     to the number of I2RS transactions expected on a given agent
286     so that the appropriate storage medium is used as to maximize
287     effectiveness of the log while not impacting the performance
288     and health of the Agent. <xref target="log_rotation"/> talks
289     about rotating the trace log as to preserve the history
290     without exhausting Agent or network device resources. It is
291     perfectly acceptable, therefore, to use both an in-memory
292     buffer for recent transactions while rotating or archiving
293     older transactions to a local file.</t>
294 marcus 18717 <t>The specific implementation of the trace log is beyond the
295 marcus 18725 scope of an information model, however.</t>
296 marcus 18717 </section>
297 marcus 18725 <section anchor="responsibilities" title="Trace Log Creation">
298     <t>The I2RS Agent interacts with the Routing and Signaling
299     functions of the Routing Element. Since the I2RS Agent is
300     responsible for actually making the routing changes on the
301     associated network device, it creates and maintains a log of
302     transactions that can be retrieved to troubleshoot
303     I2RS-related impact to the network.</t>
304 marcus 18717 </section>
305 marcus 18725 <section anchor="log_rotation" title="Trace Log Rotation">
306     <t>In order to prevent the exhaustion of resources on the I2RS
307     Agent or its associated network device, the I2RS trace log
308     implementation MAY choose to implement a configurable rotation
309     schedule. It SHOULD be possible to do rotation based on either
310     time or on size of the current trace log. If rotation is
311     supported, multiple archived log files SHOULD be supported in
312     order to maximize the troubleshooting and accounting benefits
313     of the trace log.</t>
314 marcus 18717 </section>
315 marcus 18725 <section anchor="log_retrieval" title="Trace Log Retrieval">
316     <t>Implementors are free to provide their own, proprietary
317     interfaces to retrieve and display the I2RS trace log. These
318     may include the display of the I2RS trace log as Command Line
319     Interface (CLI) output. However, a key intention of defining
320     this information model is to establish an implementor-agnostic
321     way to collect I2RS trace data. As such, retrieval of the data
322     should also be made implementor-agnostic.</t>
323     <t>The following two sections describe potential ways by which
324     the trace log can be accessed. At least one of these two MUST
325     be used, with the I2RS mechanism being preferred as it is an
326     implementor-agnostic approach to retrieving the data.</t>
327     <section anchor="trace_syslog" title="Retrieval Via Syslog">
328     <t>The syslog protocol <xref target="RFC5424"/> is a
329     standard way of sending event notification messages from an
330     host to a collector. However, the protocol does not define
331     any standard format for storing the messages, and thus
332     implementors of I2RS tracing would be left to define their
333     own format. So, while the data contained within the syslog
334     message would adhere to this information model, and may be
335     consumable by a human operator, it would not be easily
336     parseable by a machine. Therefore, syslog MAY be employed as
337     a means of retrieving or disseminating the I2RS trace log
338     contents.</t>
339     </section>
340     <section anchor="i2rs_retrieval" title="Retrieval Via I2RS">
341     <t>Section 6.7 of the I2RS architecture <xref target="I-D.ietf-i2rs-architecture"/> defines a mechanism
342     for information collection. The information collected
343     includes obtaining a snapshot of a large amount of data from
344     the network element. It is the intent of I2RS to make this
345     data available in an implementor-agnostic fashion.
346     Therefore, the I2RS trace log SHOULD be made available via
347     the I2RS information collection mechanism either as a single
348     snapshot or via a subscription stream.</t>
349     </section>
350     </section>
351 marcus 18717 </section>
352     <section anchor="IANA" title="IANA Considerations">
353 marcus 18725 <t>This document makes no request of IANA.</t>
354 marcus 18717 </section>
355     <section anchor="Security" title="Security Considerations">
356 marcus 18725 <t>The I2RS Traceability information model does not directly
357     introduce security issues. However, it defines a set of
358     attributes that may be considered sensitive information for
359     privacy or business reasons.</t>
360     <t>Specifically, the data being captured for traceability
361     describes state as well as identifying characteristics of the
362     Clients affecting that state. As such, this data is to be
363     considered private and protected locally on the Agent. While it
364     is outside the scope of this document to specify exactly how to
365     protect the traceability contents, implementors of I2RS SHOULD
366     apply appropriate permissions to control who can view the log
367     regardless of whether or not it is stored in memory or on
368     disk.</t>
369     <t>Finally, the elements defined in this information model do
370     not store cryptographic information.</t>
371 marcus 18717 </section>
372 marcus 18725 <section anchor="acknowledgements" title="Acknowledgments">
373     <t>The authors would like to thank Carlos Pignataro for his
374     contributed text, review comments, suggested improvements to
375     this document.</t>
376 marcus 18718 </section>
377 marcus 18717 </middle>
378     <back>
379     <references title="Normative References">
380 marcus 18726 &RFC2119;
383     &RFC3986;
384     &RFC4122;
385     &RFC5234;
386 marcus 18717 </references>
387     <references title="Informative References">
388 marcus 18726 &I2RS-RIB-INFO-MODEL;
389     &RFC3339;
390     &RFC5424;
391 marcus 18717 </references>
392     </back>
393     </rfc>

  ViewVC Help
Powered by ViewVC 1.1.27