ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 18727 - (show annotations) (download) (as text)
Mon Sep 2 00:15:38 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: 20855 byte(s)
Correct some points in the figure raised by Carlos.  Also, clarify that
Op Data and Actor ID are mandatory and should be logged as empty if not

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

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 RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
7 <!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 <!ENTITY RFC5424 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5424.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 ]>
14 <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
15 <?rfc toc="yes"?>
16 <?rfc tocompact="yes"?>
17 <?rfc tocdepth="4"?>
18 <?rfc tocindent="yes"?>
19 <?rfc symrefs="yes"?>
20 <?rfc sortrefs="yes"?>
21 <?rfc comments="yes"?>
22 <?rfc inline="yes"?>
23 <?rfc compact="yes"?>
24 <?rfc subcompact="no"?>
25 <rfc category="info" docName="draft-clarke-i2rs-traceability-00" ipr="trust200902">
26 <front>
27 <title abbrev="I2RS Traceability">Information Model for
28 Traceability in the Interface to the Routing System (I2RS)</title>
29 <author fullname="Joe Clarke" initials="J." surname="Clarke">
30 <organization abbrev="Cisco">Cisco Systems, Inc.</organization>
31 <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 <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 <date/>
57 <area>Routing</area>
58 <workgroup>I2RS</workgroup>
59 <keyword>I2RS</keyword>
60 <keyword>I2RS Traceability</keyword>
61 <keyword>Traceability</keyword>
62 <abstract>
63 <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 </abstract>
73 </front>
74 <middle>
75 <section anchor="intro" title="Introduction">
76 <t>The architecture for the Interface to the Routing System
77 (<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 </section>
93 <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 </section>
103 <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 <figure align="center" anchor="i2rs_interaction_trace" title="I2RS Interaction Trace Log Capture">
155 <artwork align="center"><![CDATA[
156 +-------------+
157 |Actor |
158 |.............|
159 | Actor ID |
160 +-------------+
161 ^
162 :
163 :
164 V
165 +-------------+
166 |I2RS Client |
167 |.............|
168 | Client ID |
169 +-------------+
170 ^
171 |
172 |
173 V
174 +-------------+ +-----------------------------+
175 |I2RS Agent |---------------->|Trace Log |
176 | | |.............................|
177 +-------------+ |Timestamp |
178 ^ |Client ID |
179 | ^ |Actor ID |
180 Operation + | Result Code |Client Address |
181 Op Data | |Operation |
182 V | |Operation Data |
183 V |Result Code |
184 +-------------+ +-----------------------------+
185 |Routing |
186 |System |
187 +-------------+
188 ]]></artwork>
189 </figure>
190 <t>The list below describes the fields captured in the I2RS
191 trace log.</t>
192 <t>
193 <list style="hanging">
194 <t hangText="Timestamp: ">The specific time, adhering to
195 <xref target="RFC3339"/> format, at which the I2RS
196 transaction occurred. Given that many I2RS transactions
197 can occur in rapid succession, the use of fractional
198 seconds MUST be used to provide adequate granularity.</t>
199 <t hangText="Client Identifier: ">The I2RS Client
200 identifier used to authenticate the Client to the I2RS
201 Agent.</t>
202 <t hangText="Actor Identifier: ">This is an
203 opaque identifier that may be known to the Client from a
204 northbound controlling application. This is
205 used to trace the northbound actor driving the actions of
206 the Client. The Client may not provide this identifier to the
207 Agent is there is no external actor driving the Client. However,
208 this field MUST be logged. If the Client does not provide
209 an actor ID, then the Agent MUST log an empty field.</t>
210 <t hangText="Client Address: ">This is the network address
211 of the client that connected to the Agent. For example,
212 this may be an IPv4 or IPv6 address.</t>
213 <t hangText="Operation: ">This is the I2RS operation
214 performed. For example, this may be an add route operation
215 if a route is being inserted into a routing table.</t>
216 <t hangText="Operation Data: ">This field comprises the
217 data passed to the Agent to complete the desired
218 operation. For example, if the operation is a route add
219 operation, the Operation Data would include the route
220 prefix, prefix length, and next hop information to be
221 inserted as well as the specific routing table to which
222 the route will be added. The operation data can also
223 include interface information. Some operations MAY not
224 provide operation data, and in those cases this field
225 MUST be logged as an empty field.</t>
226 <t hangText="Result Code: ">This field holds the result of
227 the operation. In the case of RIB operations, this MUST be
228 the return code as specified in Section 4 of <xref target="I-D.nitinb-i2rs-rib-info-model"/>.</t>
229 </list>
230 </t>
231 </section>
232 <section anchor="info_optional" title="I2RS Trace Log Extensibility and Optional Fields">
233 <t>TBD</t>
234 </section>
235 <section anchor="syntax" title="I2RS Trace Log Syntax">
236 <t>The following describes the trace log information model
237 using Augmented Backus-Naur Form (ABNF) syntax <xref target="RFC5234"/>:</t>
238 <figure>
239 <artwork type="abnf"><![CDATA[i2rs-trace-log = timestamp client-id actor-id client-addr operation
240 operation-data result-code
241 client-id = uuid
242 actor-id = byte-string
243 byte-string = *( %x01-09 / %x0B-0C / %x0E-FF )
244 ; any byte except NUL, CR or LF
245 client-addr = IP-literal / IPv4address
246 operation = ALPHA *( ALPHA / "_" / "-" / "(" / ")" )
247 operation-data = *VCHAR
248 result-code = 1*( ALPHA / DIGIT / "-" / "_" / "(" / ")" ) ]]></artwork>
249 </figure>
250 <t>The ABNF syntax rules &lt;IP-literal&gt;,
251 &lt;IPv4address&gt;, and &lt;sub-delims&gt; are specified in
252 <xref target="RFC3986"/>. The core rules &lt;DIGIT&gt;,
253 &lt;HEXDIGIT&gt;, &lt;ALPHA&gt; and &lt;VCHAR&gt; are used as
254 described in Appendix B of <xref target="RFC5234"/>.</t>
255 <t>Here, &lt;uuid&gt; is specified in <xref target="RFC4122"/>. The idea of using a UUID for the Client
256 identifier ensures the ID is unique not just in the scope of the
257 current I2RS Agent, but across Agents as well. This ensures that
258 two clients that are unaware of each other will not allocate the
259 same Client ID. That does not preclude
260 two Clients acting as one for purposes of high availability
261 from sharing the same UUID as generated by one one of the
262 Clients. [[Note: the format of the Client ID has not yet been
263 decided by the I2RS WG. This is subject to change.]]</t>
264 <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
265 used to provide proper granularity.</t>
266 <t>The values for &lt;operation&gt;, &lt;operation-data&gt;
267 and &lt;result-code&gt; are suggestions as the protocol has
268 not been defined yet. By making these human-readable (as
269 opposed to opcodes) the log becomes more easily consumable by
270 operators and administrators trying to troubleshoot issues
271 relating to I2RS. Even in cases where the operations or codes
272 might appear as opcodes on the wire, their textual
273 translations MUST be included in the log. The opcodes
274 themselves MAY appear in parentheses after the textual
275 representation.</t>
276 </section>
277 </section>
278 <section title="Examples">
279 <t/>
280 <t>[NOTE: To put in a name:value pairing of *proposed* values
281 now with a note that this is subject to change and proposed
282 only.]</t>
283 <t/>
284 </section>
285 <section anchor="operational_guidance" title="Operational Guidance">
286 <t/>
287 <t>[NOTE: Gonzalo to write some introductory text and the take a
288 pass at the sub-sections.]</t>
289 <t/>
290 <section anchor="trace_storage" title="Trace Log Storage">
291 <t>The trace information may be stored either in an in-memory
292 buffer or as a file local to the Agent. Care should be given
293 to the number of I2RS transactions expected on a given agent
294 so that the appropriate storage medium is used as to maximize
295 effectiveness of the log while not impacting the performance
296 and health of the Agent. <xref target="log_rotation"/> talks
297 about rotating the trace log as to preserve the history
298 without exhausting Agent or network device resources. It is
299 perfectly acceptable, therefore, to use both an in-memory
300 buffer for recent transactions while rotating or archiving
301 older transactions to a local file.</t>
302 <t>The specific implementation of the trace log is beyond the
303 scope of an information model, however.</t>
304 </section>
305 <section anchor="responsibilities" title="Trace Log Creation">
306 <t>The I2RS Agent interacts with the Routing and Signaling
307 functions of the Routing Element. Since the I2RS Agent is
308 responsible for actually making the routing changes on the
309 associated network device, it creates and maintains a log of
310 transactions that can be retrieved to troubleshoot
311 I2RS-related impact to the network.</t>
312 </section>
313 <section anchor="log_rotation" title="Trace Log Rotation">
314 <t>In order to prevent the exhaustion of resources on the I2RS
315 Agent or its associated network device, the I2RS trace log
316 implementation MAY choose to implement a configurable rotation
317 schedule. It SHOULD be possible to do rotation based on either
318 time or on size of the current trace log. If rotation is
319 supported, multiple archived log files SHOULD be supported in
320 order to maximize the troubleshooting and accounting benefits
321 of the trace log.</t>
322 </section>
323 <section anchor="log_retrieval" title="Trace Log Retrieval">
324 <t>Implementors are free to provide their own, proprietary
325 interfaces to retrieve and display the I2RS trace log. These
326 may include the display of the I2RS trace log as Command Line
327 Interface (CLI) output. However, a key intention of defining
328 this information model is to establish an implementor-agnostic
329 way to collect I2RS trace data. As such, retrieval of the data
330 should also be made implementor-agnostic.</t>
331 <t>The following two sections describe potential ways by which
332 the trace log can be accessed. At least one of these two MUST
333 be used, with the I2RS mechanism being preferred as it is an
334 implementor-agnostic approach to retrieving the data.</t>
335 <section anchor="trace_syslog" title="Retrieval Via Syslog">
336 <t>The syslog protocol <xref target="RFC5424"/> is a
337 standard way of sending event notification messages from an
338 host to a collector. However, the protocol does not define
339 any standard format for storing the messages, and thus
340 implementors of I2RS tracing would be left to define their
341 own format. So, while the data contained within the syslog
342 message would adhere to this information model, and may be
343 consumable by a human operator, it would not be easily
344 parseable by a machine. Therefore, syslog MAY be employed as
345 a means of retrieving or disseminating the I2RS trace log
346 contents.</t>
347 </section>
348 <section anchor="i2rs_retrieval" title="Retrieval Via I2RS">
349 <t>Section 6.7 of the I2RS architecture <xref target="I-D.ietf-i2rs-architecture"/> defines a mechanism
350 for information collection. The information collected
351 includes obtaining a snapshot of a large amount of data from
352 the network element. It is the intent of I2RS to make this
353 data available in an implementor-agnostic fashion.
354 Therefore, the I2RS trace log SHOULD be made available via
355 the I2RS information collection mechanism either as a single
356 snapshot or via a subscription stream.</t>
357 </section>
358 </section>
359 </section>
360 <section anchor="IANA" title="IANA Considerations">
361 <t>This document makes no request of IANA.</t>
362 </section>
363 <section anchor="Security" title="Security Considerations">
364 <t>The I2RS Traceability information model does not directly
365 introduce security issues. However, it defines a set of
366 attributes that may be considered sensitive information for
367 privacy or business reasons.</t>
368 <t>Specifically, the data being captured for traceability
369 describes state as well as identifying characteristics of the
370 Clients affecting that state. As such, this data is to be
371 considered private and protected locally on the Agent. While it
372 is outside the scope of this document to specify exactly how to
373 protect the traceability contents, implementors of I2RS SHOULD
374 apply appropriate permissions to control who can view the log
375 regardless of whether or not it is stored in memory or on
376 disk.</t>
377 <t>Finally, the elements defined in this information model do
378 not store cryptographic information.</t>
379 </section>
380 <section anchor="acknowledgements" title="Acknowledgments">
381 <t>The authors would like to thank Carlos Pignataro for his
382 contributed text, review comments, suggested improvements to
383 this document.</t>
384 </section>
385 </middle>
386 <back>
387 <references title="Normative References">
388 &RFC2119;
391 &RFC3986;
392 &RFC4122;
393 &RFC5234;
394 </references>
395 <references title="Informative References">
397 &RFC3339;
398 &RFC5424;
399 </references>
400 </back>
401 </rfc>

  ViewVC Help
Powered by ViewVC 1.1.27