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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 18731 by marcus, Sun Sep 8 14:22:32 2013 UTC revision 18732 by marcus, Sun Sep 8 14:24:03 2013 UTC
# Line 151  Line 151 
151          collected and stored by the Agent.</t>          collected and stored by the Agent.</t>
152          <t>The interaction between the optional northbound actor, I2RS          <t>The interaction between the optional northbound actor, I2RS
153          Client, I2RS Agent, the Routing System and the data captured          Client, I2RS Agent, the Routing System and the data captured
154          in the I2RS trace log is shown in <xref target="i2rs_interaction_trace"/>.</t>          in the I2RS trace log is shown in <xref target="i2rs_interaction_trace"/>.<vspace blankLines="30"/></t>
155          <figure align="center" anchor="i2rs_interaction_trace" title="I2RS Interaction Trace Log Capture">          <figure align="center" anchor="i2rs_interaction_trace" title="I2RS Interaction Trace Log Capture">
156            <artwork align="center"><![CDATA[            <artwork align="center"><![CDATA[
157        +-------------+        +-------------+
# Line 200  Line 200 
200              <t hangText="Client Identifier: ">The I2RS Client              <t hangText="Client Identifier: ">The I2RS Client
201              identifier used to authenticate the Client to the I2RS              identifier used to authenticate the Client to the I2RS
202              Agent.</t>              Agent.</t>
203              <t hangText="Actor Identifier: ">This is an              <t hangText="Actor Identifier: ">This is an opaque
204              opaque identifier that may be known to the Client from a              identifier that may be known to the Client from a
205              northbound controlling application. This is              northbound controlling application. This is used to trace
206              used to trace the northbound actor driving the actions of              the northbound actor driving the actions of the Client.
207              the Client.  The Client may not provide this identifier to the              The Client may not provide this identifier to the Agent is
208              Agent is there is no external actor driving the Client.  However,              there is no external actor driving the Client. However,
209              this field MUST be logged.  If the Client does not provide              this field MUST be logged. If the Client does not provide
210              an actor ID, then the Agent MUST log an empty field.</t>              an actor ID, then the Agent MUST log an empty field.</t>
211              <t hangText="Client Address: ">This is the network address              <t hangText="Client Address: ">This is the network address
212              of the client that connected to the Agent. For example,              of the client that connected to the Agent. For example,
213              this may be an IPv4 or IPv6 address.  [Note: will I2RS              this may be an IPv4 or IPv6 address. [Note: will I2RS
214              support interactions that have no network address?  If so              support interactions that have no network address? If so
215              this field will need to be updated.]</t>              this field will need to be updated.]</t>
216              <t hangText="Operation: ">This is the I2RS operation              <t hangText="Operation: ">This is the I2RS operation
217              performed. For example, this may be an add route operation              performed. For example, this may be an add route operation
218              if a route is being inserted into a routing table.</t>              if a route is being inserted into a routing table.</t>
# Line 223  Line 223 
223              prefix, prefix length, and next hop information to be              prefix, prefix length, and next hop information to be
224              inserted as well as the specific routing table to which              inserted as well as the specific routing table to which
225              the route will be added. The operation data can also              the route will be added. The operation data can also
226              include interface information.  Some operations MAY not              include interface information. Some operations MAY not
227              provide operation data, and in those cases this field              provide operation data, and in those cases this field MUST
228              MUST be logged as an empty field.</t>              be logged as an empty field.</t>
229              <t hangText="Result Code: ">This field holds the result of              <t hangText="Result Code: ">This field holds the result of
230              the operation. In the case of RIB operations, this MUST be              the operation. In the case of RIB operations, this MUST be
231              the return code as specified in Section 4 of <xref target="I-D.nitinb-i2rs-rib-info-model"/>.  The operation may not complete with a result code              the return code as specified in Section 4 of <xref target="I-D.nitinb-i2rs-rib-info-model"/>. The operation
232              in the case of a timeout.  If the operation fails to complete,              may not complete with a result code in the case of a
233              it MUST still log the attempted operation with an appropriate              timeout. If the operation fails to complete, it MUST still
234              result code (e.g., a result code indicating a timeout).</t>              log the attempted operation with an appropriate result
235                code (e.g., a result code indicating a timeout).</t>
236            </list>            </list>
237          </t>          </t>
238        </section>        </section>
239        <section anchor="info_optional" title="I2RS Trace Log Extensibility and Optional Fields">        <section anchor="info_optional" title="I2RS Trace Log Extensibility and Optional Fields">
240          <t>TBD</t>          <t/>
241            <t>[NOTE: This section is TBD based on further development of
242            I2RS WG milestones.]</t>
243            <t> </t>
244        </section>        </section>
245        <section anchor="syntax" title="I2RS Trace Log Syntax">        <section anchor="syntax" title="I2RS Trace Log Syntax">
246          <t>The following describes the trace log information model          <t>The following describes the trace log information model
# Line 259  result-code    = 1*( ALPHA / DIGIT / "-" Line 263  result-code    = 1*( ALPHA / DIGIT / "-"
263          &lt;HEXDIGIT&gt;, &lt;ALPHA&gt; and &lt;VCHAR&gt; are used as          &lt;HEXDIGIT&gt;, &lt;ALPHA&gt; and &lt;VCHAR&gt; are used as
264          described in Appendix B of <xref target="RFC5234"/>.</t>          described in Appendix B of <xref target="RFC5234"/>.</t>
265          <t>Here, &lt;uuid&gt; is specified in <xref target="RFC4122"/>. The idea of using a UUID for the Client          <t>Here, &lt;uuid&gt; is specified in <xref target="RFC4122"/>. The idea of using a UUID for the Client
266          identifier ensures the ID is unique not just in the scope of the          identifier ensures the ID is unique not just in the scope of
267          current I2RS Agent, but across Agents as well.  This ensures that          the current I2RS Agent, but across Agents as well. This
268          two clients that are unaware of each other will not allocate the          ensures that two clients that are unaware of each other will
269          same Client ID. That does not preclude          not allocate the same Client ID. That does not preclude two
270          two Clients acting as one for purposes of high availability          Clients acting as one for purposes of high availability from
271          from sharing the same UUID as generated by one one of the          sharing the same UUID as generated by one one of the Clients.
272          Clients. [Note: the format of the Client ID has not yet been          [Note: the format of the Client ID has not yet been decided by
273          decided by the I2RS WG. This is subject to change.]</t>          the I2RS WG. This is subject to change.]</t>
274          <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          <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
275          used to provide proper granularity.</t>          used to provide proper granularity.</t>
276          <t>The values for &lt;operation&gt;, &lt;operation-data&gt;          <t>The values for &lt;operation&gt;, &lt;operation-data&gt;
# Line 283  result-code    = 1*( ALPHA / DIGIT / "-" Line 287  result-code    = 1*( ALPHA / DIGIT / "-"
287      </section>      </section>
288      <section title="Examples">      <section title="Examples">
289        <t>Here is a proposed sample of what the fields might look like        <t>Here is a proposed sample of what the fields might look like
290              in an I2RS trace log.  This is only an early proposal.  These        in an I2RS trace log. This is only an early proposal. These
291              values are subject to change.</t>        values are subject to change.</t>
292        <figure>        <figure>
293          <artwork><![CDATA[          <artwork><![CDATA[
294  Timestamp:      2013-09-03T12:00:01.21+00:00  Timestamp:      2013-09-03T12:00:01.21+00:00
# Line 297  Operation Data: PREFIX 203.0.113.0 PREFI Line 301  Operation Data: PREFIX 203.0.113.0 PREFI
301  Result Code:    SUCCESS(0)  Result Code:    SUCCESS(0)
302          ]]></artwork>          ]]></artwork>
303        </figure>        </figure>
304        <t>The IP addresses used in the examples in this document correspond        <t>The IP addresses used in the examples in this document
305              to the documentation address blocks 192.0.2.0/24 (TEST-NET-1),        correspond to the documentation address blocks 192.0.2.0/24
306              198.51.100.0/24 (TEST-NET-2) and 203.0.113.0/24 (TEST-NET-3)        (TEST-NET-1), 198.51.100.0/24 (TEST-NET-2) and 203.0.113.0/24
307              as described in <xref target="RFC5737"/>.</t>        (TEST-NET-3) as described in <xref target="RFC5737"/>.</t>
308      </section>      </section>
309      <section anchor="operational_guidance" title="Operational Guidance">      <section anchor="operational_guidance" title="Operational Guidance">
310        <t/>        <t/>
311        <t>[NOTE: Gonzalo to write some introductory text and the take a        <t>Specific operational procedures regarding file storage,
312        pass at the sub-sections.]</t>        rollover, retrieval, and access of I2RS trace logs is out of
313          scope for this document. Organizations employing I2RS trace
314          logging are responsible for establishing proper operational
315          procedures that are appropriately suited to their specific
316          requirements and operating environment. In this section we only
317          provide fundamental and generalized operational guidelines that
318          are implementation-independent.</t>
319        <t/>        <t/>
       <section anchor="trace_storage" title="Trace Log Storage">  
         <t>The trace information may be stored either in an in-memory  
         buffer or as a file local to the Agent. Care should be given  
         to the number of I2RS transactions expected on a given agent  
         so that the appropriate storage medium is used as to maximize  
         effectiveness of the log while not impacting the performance  
         and health of the Agent. <xref target="log_rotation"/> talks  
         about rotating the trace log as to preserve the history  
         without exhausting Agent or network device resources. It is  
         perfectly acceptable, therefore, to use both an in-memory  
         buffer for recent transactions while rotating or archiving  
         older transactions to a local file.</t>  
         <t>The specific implementation of the trace log is beyond the  
         scope of an information model, however.</t>  
       </section>  
320        <section anchor="responsibilities" title="Trace Log Creation">        <section anchor="responsibilities" title="Trace Log Creation">
321          <t>The I2RS Agent interacts with the Routing and Signaling          <t>The I2RS Agent interacts with the Routing and Signaling
322          functions of the Routing Element. Since the I2RS Agent is          functions of the Routing Element. Since the I2RS Agent is
# Line 330  Result Code:    SUCCESS(0) Line 325  Result Code:    SUCCESS(0)
325          transactions that can be retrieved to troubleshoot          transactions that can be retrieved to troubleshoot
326          I2RS-related impact to the network.</t>          I2RS-related impact to the network.</t>
327        </section>        </section>
328          <section anchor="trace_storage" title="Trace Log Storage">
329            <t>The trace information may be stored either in an in-memory
330            buffer or as a file local to the Agent. Care should be given
331            to the number of I2RS transactions expected on a given agent
332            so that the appropriate storage medium is used and to maximize
333            the effectiveness of the log while not impacting the
334            performance and health of the Agent. <xref target="log_rotation"/> talks about rotating the trace log in
335            order to preserve the transaction history without exhausting
336            Agent or network device resources. It is perfectly acceptable,
337            therefore, to use both an in-memory buffer for recent
338            transactions while rotating or archiving older transactions to
339            a local file.</t>
340            <t>It is outside the scope of this document to specify the
341            implementation details (i.e., size, throughput, data
342            protection, privacy, etc.) for the physical storage of the
343            I2RS log file.</t>
344          </section>
345        <section anchor="log_rotation" title="Trace Log Rotation">        <section anchor="log_rotation" title="Trace Log Rotation">
346          <t>In order to prevent the exhaustion of resources on the I2RS          <t>In order to prevent the exhaustion of resources on the I2RS
347          Agent or its associated network device, the I2RS trace log          Agent or its associated network device, the I2RS trace log
348          implementation MAY choose to implement a configurable rotation          implementation MAY choose to implement a configurable rotation
349          schedule. It SHOULD be possible to do rotation based on either          schedule. It SHOULD be possible to do file rotation based on
350          time or on size of the current trace log. If rotation is          either time or size of the current trace log. If file rollover
351          supported, multiple archived log files SHOULD be supported in          is supported, multiple archived log files SHOULD be supported
352          order to maximize the troubleshooting and accounting benefits          in order to maximize the troubleshooting and accounting
353          of the trace log.</t>          benefits of the trace log.</t>
354        </section>        </section>
355        <section anchor="log_retrieval" title="Trace Log Retrieval">        <section anchor="log_retrieval" title="Trace Log Retrieval">
356          <t>Implementors are free to provide their own, proprietary          <t>Implementors are free to provide their own, proprietary
357          interfaces to retrieve and display the I2RS trace log. These          interfaces and develop custom tools to retrieve and display
358          may include the display of the I2RS trace log as Command Line          the I2RS trace log. These may include the display of the I2RS
359          Interface (CLI) output. However, a key intention of defining          trace log as Command Line Interface (CLI) output. However, a
360          this information model is to establish an implementor-agnostic          key intention of defining this information model is to
361          way to collect I2RS trace data. As such, retrieval of the data          establish an implementor-agnostic and consistent interface to
362          should also be made implementor-agnostic.</t>          collect I2RS trace data. Correspondingly, retrieval of the
363          <t>The following two sections describe potential ways by which          data should also be made implementor-agnostic.</t>
364          the trace log can be accessed. At least one of these two MUST          <t>The following two sections describe potential ways the
365          be used, with the I2RS mechanism being preferred as it is an          trace log can be accessed. At least one of these two MUST be
366          implementor-agnostic approach to retrieving the data.</t>          used, with the I2RS mechanism being preferred as it is an
367            implementor-independent approach to retrieving the data.</t>
368          <section anchor="trace_syslog" title="Retrieval Via Syslog">          <section anchor="trace_syslog" title="Retrieval Via Syslog">
369            <t>The syslog protocol <xref target="RFC5424"/> is a            <t>The syslog protocol <xref target="RFC5424"/> is a
370            standard way of sending event notification messages from an            standard way of sending event notification messages from a
371            host to a collector. However, the protocol does not define            host to a collector. However, the protocol does not define
372            any standard format for storing the messages, and thus            any standard format for storing the messages, and thus
373            implementors of I2RS tracing would be left to define their            implementors of I2RS tracing would be left to define their
# Line 381  Result Code:    SUCCESS(0) Line 394  Result Code:    SUCCESS(0)
394        <t>This document makes no request of IANA.</t>        <t>This document makes no request of IANA.</t>
395      </section>      </section>
396      <section anchor="Security" title="Security Considerations">      <section anchor="Security" title="Security Considerations">
397        <t>The I2RS Traceability information model does not directly        <t>The I2RS trace log, like any log file, reveals the state of
398        introduce security issues. However, it defines a set of        the entity producing it as well as the identifying information
399        attributes that may be considered sensitive information for        elements and detailed interactions of the system containing it.
400        privacy or business reasons.</t>        The information model described in this document does not itself
401        <t>Specifically, the data being captured for traceability        introduce any security issues, but it does define the set of
402        describes state as well as identifying characteristics of the        attributes that make up an I2RS log file. These attributes may
403        Clients affecting that state. As such, this data is to be        contain sensitive information and thus should adhere to the
404        considered private and protected locally on the Agent. While it        security, privacy and permission policies of the organization
405        is outside the scope of this document to specify exactly how to        making use of the I2RS log file. </t>
406        protect the traceability contents, implementors of I2RS SHOULD        <t>It is outside the scope of this document to specify how to
407        apply appropriate permissions to control who can view the log        protect the stored log file, but it is expected that adequate
408        regardless of whether or not it is stored in memory or on        precautions and security best practices such as disk encryption,
409        disk.</t>        appropriately restrictive file/directory permissions, suitable
410        <t>Finally, the elements defined in this information model do        hardening and physical security of logging entities, mutual
411        not store cryptographic information.</t>        authentication, transport encryption, channel confidentiality,
412          and channel integrity if transferring log files. Additionally,
413          the potentially sensitive information contained in a log file
414          SHOULD be adequately anonymized or obfuscated by operators to
415          ensure its privacy.</t>
416      </section>      </section>
417      <section anchor="acknowledgements" title="Acknowledgments">      <section anchor="acknowledgements" title="Acknowledgments">
418        <t>The authors would like to thank Carlos Pignataro for his        <t>The authors would like to thank Carlos Pignataro for his
# Line 405  Result Code:    SUCCESS(0) Line 422  Result Code:    SUCCESS(0)
422    </middle>    </middle>
423    <back>    <back>
424      <references title="Normative References">      <references title="Normative References">
425          &RFC2119;        &RFC2119;
426          &I2RS-ARCHITECTURE;  
427          &I2RS-PROBLEM-STATEMENT;        &I2RS-ARCHITECTURE;
428          &RFC3986;  
429          &RFC4122;        &I2RS-PROBLEM-STATEMENT;
430          &RFC5234;  
431          &RFC3986;
432    
433          &RFC4122;
434    
435          &RFC5234;
436      </references>      </references>
437      <references title="Informative References">      <references title="Informative References">
438          &I2RS-RIB-INFO-MODEL;        &I2RS-RIB-INFO-MODEL;
439          &RFC3339;  
440          &RFC5424;        &RFC3339;
441          &RFC5737;  
442          &RFC5424;
443    
444          &RFC5737;
445      </references>      </references>
446    </back>    </back>
447  </rfc>  </rfc>

Legend:
Removed from v.18731  
changed lines
  Added in v.18732

  ViewVC Help
Powered by ViewVC 1.1.27