One document matched: draft-ietf-i2rs-traceability-06.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
<!ENTITY RFC3339 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml">
<!ENTITY RFC5424 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5424.xml">
<!ENTITY RFC5737 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5737.xml">
<!ENTITY RFC6536 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6536.xml">
<!ENTITY I2RS-ARCHITECTURE SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-i2rs-architecture.xml">
<!ENTITY I2RS-PROBLEM-STATEMENT SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-i2rs-problem-statement.xml">
<!ENTITY I2RS-RIB-INFO-MODEL SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-i2rs-rib-info-model.xml">
<!ENTITY I2RS-PUB-SUB-REQ SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-i2rs-pub-sub-requirements.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="4"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-ietf-i2rs-traceability-06"
ipr="trust200902">
<front>
<title abbrev="I2RS Traceability">Interface to the Routing System
(I2RS) Traceability: Framework and Information Model</title>
<author fullname="Joe Clarke" initials="J." surname="Clarke">
<organization abbrev="Cisco">Cisco Systems, Inc.</organization>
<address>
<postal>
<street>7200-12 Kit Creek Road</street>
<city>Research Triangle Park</city>
<region>NC</region>
<code>27709</code>
<country>US</country>
</postal>
<phone>+1-919-392-2867</phone>
<email>jclarke@cisco.com</email>
</address>
</author>
<author fullname="Gonzalo Salgueiro" initials="G."
surname="Salgueiro">
<organization abbrev="Cisco">Cisco Systems, Inc.</organization>
<address>
<postal>
<street>7200-12 Kit Creek Road</street>
<city>Research Triangle Park</city>
<region>NC</region>
<code>27709</code>
<country>US</country>
</postal>
<email>gsalguei@cisco.com</email>
</address>
</author>
<author fullname="Carlos Pignataro" initials="C."
surname="Pignataro">
<organization abbrev="Cisco">Cisco Systems, Inc.</organization>
<address>
<postal>
<street>7200-12 Kit Creek Road</street>
<city>Research Triangle Park</city>
<region>NC</region>
<code>27709</code>
<country>US</country>
</postal>
<email>cpignata@cisco.com</email>
</address>
</author>
<date/>
<area>Routing</area>
<workgroup>I2RS</workgroup>
<keyword>I2RS</keyword>
<keyword>I2RS Traceability</keyword>
<keyword>Traceability</keyword>
<abstract>
<t>This document describes a framework for traceability in the
Interface to the Routing System (I2RS) and information model for
that framework. It specifies the motivation, requirements, use
cases, and defines an information model for recording
interactions between elements implementing the I2RS protocol.
This framework provides a consistent tracing interface for
components implementing the I2RS architecture to record what was
done, by which component, and when. It aims to improve the
management of I2RS implementations, and can be used for
troubleshooting, auditing, forensics, and accounting
purposes.</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction">
<t>The architecture for the Interface to the Routing System
(<xref target="I-D.ietf-i2rs-architecture"/>) specifies that
I2RS Clients wishing to retrieve or change routing state on a
routing element MUST authenticate to an I2RS Agent. The I2RS
Client will have a unique identity it provides for
authentication, and should provide another, opaque identity
for applications communicating through it. The
programming of routing state will produce a return code
containing the results of the specified operation and associated
reason(s) for the result. All of this is critical information to
be used for understanding the history of I2RS interactions.</t>
<t>This document describes use cases for I2RS traceability.
Based on these use cases, the document proposes an information
model and reporting requirements to provide for effective
recording of I2RS interactions. In this context, effective
troubleshooting means being able to identify what operation was
performed by a specific I2RS Client, what was the result of the
operation, and when that operation was performed.</t>
<t>Discussions about the retention of the data logged as part of
I2RS traceability, while important, are outside of the scope of
this document.</t>
</section>
<section anchor="terminology" title="Terminology and Conventions">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described
in <xref target="RFC2119"/>.</t>
<t>The architecture specification for I2RS <xref
target="I-D.ietf-i2rs-architecture"/> defines additional terms
used in this document that are specific to the I2RS domain, such
as "I2RS Agent", "I2RS Client", etc. The reader is expected to
be familiar with the terminology and concepts defined in <xref
target="I-D.ietf-i2rs-architecture"/>.</t>
<t>The IP addresses used in the example in this document
correspond to the documentation address blocks 192.0.2.0/24
(TEST-NET-1), 198.51.100.0/24 (TEST-NET-2) and 203.0.113.0/24
(TEST-NET-3) as described in <xref target="RFC5737"/>.</t>
</section>
<section anchor="motivation" title="Motivation">
<t>As networks scale and policy becomes an increasingly
important part of the control plane that creates and maintains
the forwarding state, operational complexity increases as well.
I2RS offers more granular and coherent control over policy and
control plane state, but it also removes or reduces the locality
of the policy that has been applied to the control plane at any
individual forwarding device. The ability to automate and
abstract even complex policy-based controls highlights the need
for an equally scalable traceability function to provide
event-level granularity of the routing system compliant with the
requirements of I2RS (Section 5 of <xref
target="I-D.ietf-i2rs-problem-statement"/>).</t>
</section>
<section anchor="use_cases" title="Use Cases">
<t>An obvious motivation for I2RS traceability is the need to
troubleshoot and identify root-causes of problems in these
increasingly complex routing systems. For example, since I2RS is
a high-throughput multi-channel, full duplex and highly
responsive interface, I2RS Clients may be performing a large
number of operations on I2RS Agents concurrently or at nearly
the same time and quite possibly in very rapid succession. As
these many changes are made, the network reacts accordingly.
These changes might lead to a race condition, performance
issues, data loss, or disruption of services. In order to
isolate the root cause of these issues it is critical that a
network operator or administrator has visibility into what
changes were made via I2RS at a specific time.</t>
<t>Some network environments have strong auditing requirements
for configuration and runtime changes. Other environments have
policies that require saving logging information for operational
or regulatory compliance considerations. These requirements
therefore demand that I2RS provides an account of changes made
to network element routing systems.</t>
<t>As I2RS becomes increasingly pervasive in routing
environments, a traceability model offers significant advantages
and facilitates the following use cases:</t>
<t><list style="symbols">
<t>Automated event correlation, trend analysis, and anomaly
detection;</t>
<t>Trace log storage for offline (manual or tools)
analysis;</t>
<t>Improved accounting of routing system operations;</t>
<t>Standardized structured data format for writing common
tools;</t>
<t>Common reference for automated testing and incident
reporting;</t>
<t>Real-time monitoring and troubleshooting;</t>
<t>Enhanced network audit, management and forensic analysis
capabilities.</t>
</list></t>
</section>
<section anchor="information_model" title="Information Model">
<section anchor="info_framework"
title="I2RS Traceability Framework">
<t>This section describes a framework for I2RS traceability
based on the I2RS Architecture. Some notable elements on the
architecture are in this section.</t>
<t>The interaction between the optional northbound application, I2RS
Client, I2RS Agent, the Routing System and the data captured
in the I2RS trace log is shown in <xref
target="i2rs_interaction_trace"/>.<vspace
blankLines="35"/></t>
<figure align="center" anchor="i2rs_interaction_trace"
title="I2RS Interaction Trace Log Capture">
<artwork align="center"><![CDATA[
+----------------+
|Application |
|.............. |
| Application ID |
+----------------+
^
| 0 .. N
|
V
+-------------+
|I2RS Client |
|.............|
| Client ID |
+-------------+
^
| 1 .. N
|
V
+-------------+ +-----------------------------+
|I2RS Agent |---------------->|Trace Log |
| | |.............................|
+-------------+ |Log Entry [1 .. N] |
^ |.............................|
| |Request Timestamp |
| |Client ID |
| |Client Priority |
| ^ |Secondary ID |
Operation + | Result Code |Client Address |
Op Data | |Requested Operation |
V | |Applied Operation |
| |Operation Data Present |
| |Requested Operation Data |
| |Applied Operation Data |
| |Transaction ID |
| |Result Code |
| |Result Timestamp |
V |End Of Message |
+-------------+ +-----------------------------+
|Routing |
|System |
+-------------+
]]></artwork>
</figure>
</section>
<section anchor="info_required"
title="I2RS Trace Log Mandatory Fields">
<t>In order to ensure that each I2RS interaction can be
properly traced back to the Client that made the request at a
specific point in time, the following information MUST be
collected and stored by the Agent.</t>
<t>The list below describes the fields captured in the I2RS
trace log.</t>
<t><list style="hanging">
<t hangText="Entry ID: ">This is a unique identifier for
each entry in the I2RS trace log. Since multiple
operations can occur from the same Client at the same
time, it is important to have an identifier that can be
unambiguously associated to a specific entry.</t>
<t hangText="Request Timestamp: ">The specific time
at which the I2RS operation was received by the Agent.
The time is passed in the <xref target="RFC3339"/> format.
Given that many I2RS operations
can occur in rapid succession, the use of fractional
seconds MUST be used to provide adequate granularity.
Fractional seconds SHOULD be expressed using human-readable
32-bit second and 32-bit microsecond granularity in
second.microsecond format.</t>
<t hangText="Client Identity: ">The I2RS Client
identity used to authenticate the Client to the I2RS
Agent.</t>
<t hangText="Client Priority: ">The I2RS Client priority
assigned by the access control model that authenticates the
Client. For example, this can be set by the NETCONF Access
Control Model (NACM) as described in <xref target="RFC6536"/>.</t>
<t hangText="Secondary Identity: ">This is an opaque
identity that may be known to the Client from a
northbound controlling application. This is used to trace
the northbound application driving the actions of the Client.
The Client may not provide this identity to the Agent if
there is no external application driving the Client. However,
this field MUST be logged. If the Client does not provide
an application ID, then the Agent MUST log an UNAVAILABLE value
in the field.</t>
<t hangText="Client Address: ">This is the network address
of the Client that connected to the Agent. For example,
this may be an IPv4 or IPv6 address. [Note: will I2RS
support interactions that have no network address? If so
this field will need to be updated.]</t>
<t hangText="Requested Operation: ">This is the I2RS operation
that was requested to be performed. For example, this may be an
add route operation if a route is being inserted into a routing
table. This may not be the operation that was actually applied
to the Agent.</t>
<t hangText="Applied Operation: ">This is the I2RS operation
that was actually performed. This can differ from the Requested
Operation in cases where the Agent cannot satisfy the Requested
Operation.</t>
<t hangText="Operation Data Present: ">This is a Boolean
field that indicates whether or not addition per-Operation
Data is present.</t>
<t hangText="Requested Operation Data: ">This field comprises the
data passed to the Agent to complete the desired
operation. For example, if the operation is a route add
operation, the Operation Data would include the route
prefix, prefix length, and next hop information to be
inserted as well as the specific routing table to which
the route will be added. The operation data can also
include interface information. If Operation Data is
provided, then the Operation Data Present field MUST
be set to TRUE. Some operations may not
provide operation data. In those cases, the
Operation Data Present field MUST be set to FALSE, and
this field MUST be empty. This may not represent the
data that was used for the operation that was actually
applied on the Agent.</t>
<t hangText="Applied Operation Data: ">This field comprises the
data that was actually applied as part of the Applied Operation.
If the Agent cannot satisfy the Requested Operation with the
Requested Operation Data, then this field can differ from the
Requested Operation Data.</t>
<t hangText="Transaction ID: ">The Transaction Identity is
an opaque string that represents this particular operation
is part of a long-running I2RS transaction that can consist
of multiple, related I2RS operations. Using this value,
one can relate multiple log entries together as they are
part of a single, overall I2RS operation. [NOTE:
The requirements for transactions and long-running requests
are being discussed in the NETCONF working group, and this
text will follow the requirements set forth there.]</t>
<t hangText="Result Code: ">This field holds the result of
the operation. In the case of RIB operations, this MUST be
the return code as specified in Section 4 of <xref
target="I-D.ietf-i2rs-rib-info-model"/>. The operation
may not complete with a result code in the case of a
timeout. If the operation fails to complete, it MUST still
log the attempted operation with an appropriate result
code (e.g., a result code indicating a timeout).</t>
<t hangText="Result Timestamp: ">The specific time
at which the I2RS operation was completed by the Agent.
The time is passed in the <xref target="RFC3339"/> format.
If the operation timed
out, then this field will contain an all-zeroes value of
"0000-00-00T00:00:00.00". Given that many I2RS operations
can occur in rapid succession, the use of fractional
seconds MUST be used to provide adequate granularity.
Fractional seconds SHOULD be expressed using human-readable
32-bit second and 32-bit microsecond granularity in
second.microsecond format.</t>
<t hangText="End Of Message: ">Each log entry SHOULD have
an appropriate End Of Message (EOM) indicator. See section
<xref target="eom"/> below for more details.</t>
</list></t>
</section>
<section anchor="eom" title="End of Message Marker">
<t>Because of variability within I2RS trace log fields,
implementors MUST use a format-appropriate end of message
(EOM) indicator in order to signify the end of a particular
record. That is, regardless of format, the I2RS trace log MUST
provide a distinct way of distinguishing between the end of
one record and the beginning of another. For example, in a
linear formated log (similar to syslog) the EOM marker may be
a newline character. In an XML formated log, the schema would
provide for element tags that denote beginning and end of
records. In a JSON formated log, the syntax would provide
record separation (likely by comma-separated array
elements).</t>
</section>
<!-- <section anchor="info_optional"
title="I2RS Trace Log Extensibility and Optional Fields">
<t/>
<t>[NOTE: This section is TBD based on further development of
I2RS WG milestones.]</t>
<t/>
</section>-->
</section>
<section title="Examples">
<t>Here is a proposed sample of what the fields might look like
in an I2RS trace log. This is only an early proposal. These
values are subject to change. <vspace blankLines="1"/></t>
<figure>
<artwork><![CDATA[
Entry ID: 1
Request Timestamp: 2013-09-03T12:00:01.21+00:00
Client ID: 5CEF1870-0326-11E2-A21F-0800200C9A66
Client Priority: 100
Secondary ID com.example.RoutingApp
Client Address: 192.0.2.2
Requested Operation: ROUTE_ADD
Applied Operation: ROUTE_ADD
Operation Data Present: TRUE
Requested Operation Data: PREFIX 203.0.113.0 PREFIX-LEN 24 NEXT-HOP
198.51.100.1
Applied Operation Data: PREFIX 203.0.113.0 PREFIX-LEN 24 NEXT-HOP
198.51.100.1
Transaction ID: 2763461
Result Code: SUCCESS(0)
Result Timestamp: 2013-09-03T12:00:01.23+00:00
]]></artwork>
</figure>
</section>
<section anchor="operational_guidance"
title="Operational Guidance">
<t/>
<t>Specific operational procedures regarding temporary log
storage, rollover, retrieval, and access of I2RS trace logs is
out of scope for this document. Organizations employing I2RS
trace logging are responsible for establishing proper
operational procedures that are appropriately suited to their
specific requirements and operating environment. In this section
we only provide fundamental and generalized operational
guidelines that are implementation-independent.</t>
<t/>
<section anchor="responsibilities" title="Trace Log Creation">
<t>The I2RS Agent interacts with the Routing and Signaling
functions of the Routing Element. Since the I2RS Agent is
responsible for actually making the routing changes on the
associated network device, it creates and maintains a log of
operations that can be retrieved to troubleshoot
I2RS-related impact to the network.</t>
</section>
<section anchor="trace_storage"
title="Trace Log Temporary Storage">
<t>The trace information may be temporarily stored either in
an in-memory buffer or as a file local to the Agent. Care
should be given to the number of I2RS operations expected on
a given Agent so that the appropriate storage medium is used
and to maximize the effectiveness of the log while not
impacting the performance and health of the Agent.
Client requests may not always be processed synchronously or within
a bounded time period.
Consequently, to ensure that trace log fields, such as "Operation"
and "Result Code", are part of the same trace log record it may
require buffering of the trace log entries. This buffering may
result in additional resource load on the Agent and the network
element.</t>
<t><xref
target="log_rotation"/> discusses rotating the trace log in
order to preserve the operation history without exhausting
Agent or network device resources. It is perfectly acceptable,
therefore, to use both an in-memory buffer for recent
operations while rotating or archiving older operations to
a local file.</t>
<t>It is outside the scope of this document to specify the
implementation details (i.e., size, throughput, data
protection, privacy, etc.) for the physical storage of the
I2RS log file. Data retention policies of the I2RS
traceability log is also outside the scope of this
document.</t>
</section>
<section anchor="log_rotation" title="Trace Log Rotation">
<t>In order to prevent the exhaustion of resources on the I2RS
Agent or its associated network device, it is RECOMMENDED that
the I2RS Agent implements trace log rotation. The details on
how this is achieved are left to the implementation and
outside the scope of this document. However, it should be
possible to do file rotation based on either time or size of
the current trace log. If file rollover is supported, multiple
archived log files should be supported in order to maximize
the troubleshooting and accounting benefits of the trace
log.</t>
</section>
<section anchor="log_retrieval" title="Trace Log Retrieval">
<t>Implementors are free to provide their own, proprietary
interfaces and develop custom tools to retrieve and display
the I2RS trace log. These may include the display of the I2RS
trace log as Command Line Interface (CLI) output. However, a
key intention of defining this information model is to
establish an vendor-agnostic and consistent interface to
collect I2RS trace data. Correspondingly, retrieval of the
data should also be made vendor-agnostic.</t>
<t>Despite the fact that export of I2RS trace log
information could be an invaluable diagnostic tool for
off-box analysis, exporting this information MUST NOT interfere
with the ability of the Agent to process new incoming operations.</t>
<t>The following three sections describe potential ways the
trace log can be accessed. At least one of these three MUST be
used, with the I2RS mechanisms being preferred as they are
vendor-independent approaches to retrieving the data.</t>
<section anchor="trace_syslog" title="Retrieval Via Syslog">
<t>The syslog protocol <xref target="RFC5424"/> is a
standard way of sending event notification messages from a
host to a collector. However, the protocol does not define
any standard format for storing the messages, and thus
implementors of I2RS tracing would be left to define their
own format. So, while the data contained within the syslog
message would adhere to this information model, and may be
consumable by a human operator, it would not be easily
parseable by a machine. Therefore, syslog MAY be employed as
a means of retrieving or disseminating the I2RS trace log
contents.</t>
<t>If syslog is used for trace log retrieval, then existing
logging infrastructure and capabilities of syslog
<xref target="RFC5424"/> should be leveraged without the need
to define or extend existing formats. For example, the various
fields described in <xref target="info_required"/> SHOULD be
modeled and encoded as Structured Data Elements (referred to
as "SD-ELEMENT"), as described in Section 6.3.1 of
<xref target="RFC5424"/>.</t>
</section>
<section anchor="i2rs_info_retrieval"
title="Retrieval Via I2RS Information Collection">
<t>Section 6.7 of the I2RS architecture <xref
target="I-D.ietf-i2rs-architecture"/> defines a mechanism
for information collection. The information collected
includes obtaining a snapshot of a large amount of data from
the network element. It is the intent of I2RS to make this
data available in an implementor-agnostic fashion.
Therefore, the I2RS trace log SHOULD be made available via
the I2RS information collection mechanism either as a single
snapshot or via a subscription stream.</t>
</section>
<section anchor="pub_sub_retrieval"
title="Retrieval Via I2RS Pub-Sub">
<t>Section 7.6 of the I2RS architecture <xref
target="I-D.ietf-i2rs-architecture"/> goes on to describe
notification mechanisms for a feed of changes happening
within the I2RS layer. Specifically, the requirements for
a publish-subscribe system for I2RS are defined in
<xref target="I-D.ietf-i2rs-pub-sub-requirements"/>.
I2RS Agents SHOULD support publishing
I2RS trace log information to that feed as described in that
document. Subscribers would then receive a live stream of
I2RS interactions in trace log format and could flexibly
choose to do a number of things with the log messages. For
example, the subscribers could log the messages to a
datastore, aggregate and summarize interactions from a
single Client, etc. The full range of
potential activites is virtually limitless and the details
of how they are performed are outside the scope of this
document, however.</t>
</section>
</section>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>This document makes no request of IANA.</t>
</section>
<section anchor="Security" title="Security Considerations">
<t>The I2RS trace log, like any log file, reveals the state of
the entity producing it as well as the identifying information
elements and detailed interactions of the system containing it.
The information model described in this document does not itself
introduce any security issues, but it does define the set of
attributes that make up an I2RS log file. These attributes may
contain sensitive information and thus should adhere to the
security, privacy and permission policies of the organization
making use of the I2RS log file.</t>
<t>It is outside the scope of this document to specify how to
protect the stored log file, but it is expected that adequate
precautions and security best practices such as disk encryption,
appropriately restrictive file/directory permissions, suitable
hardening and physical security of logging entities, mutual
authentication, transport encryption, channel confidentiality,
and channel integrity if transferring log files. Additionally,
the potentially sensitive information contained in a log file
SHOULD be adequately anonymized or obfuscated by operators to
ensure its privacy.</t>
</section>
<section anchor="acknowledgements" title="Acknowledgments">
<t>The authors would like to thank Alia Atlas for her initial
feedback and overall support for this work. Additionally, the
authors acknowledge Alvaro Retana, Russ White, Matt Birkner,
Jeff Haas, Joel Halpern, Dean Bogdanovich, Ignas Bagdonas, Nobo Akiya,
Kwang-koog Lee, and Alex Clemm for their reviews,
contributed text, and suggested improvements to this
document.</t>
</section>
</middle>
<back>
<references title="Normative References">
&I2RS-ARCHITECTURE;
&I2RS-PUB-SUB-REQ;
&I2RS-PROBLEM-STATEMENT;
&RFC2119;
</references>
<references title="Informative References">
&I2RS-RIB-INFO-MODEL;
&RFC3339;
&RFC5424;
&RFC5737;
&RFC6536;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 19:32:35 |