One document matched: draft-clarke-i2rs-traceability-00.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 RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC4122 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4122.xml">
<!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.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 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.nitinb-i2rs-rib-info-model.xml">
<!ENTITY I2RS-PUBSUB-SEC SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.camwinget-i2rs-pubsub-sec.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="info" docName="draft-clarke-i2rs-traceability-00" 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 identifier
for applications (or actors) communicating through it. The programming of
routing state will produce in 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 specifies requirements, use cases, and describes the
information model for traceability attributes that must be
collected and logged by I2RS Agents in order to effectively
record 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 and Use Cases">
<t>As networks grow, so too does the scale and complexity of
routing systems. I2RS offers a standard, programmatic interface
allowing improved automation and more granular control over an
increasingly dynamic routing and signaling state. This ability
to automate 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>
<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 internal policies to save logging information for
operational 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 transactions.</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 highlighted herein.</t>
<t>The interaction between the optional northbound actor, 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="30"/></t>
<figure align="center" anchor="i2rs_interaction_trace" title="I2RS Interaction Trace Log Capture">
<artwork align="center"><![CDATA[
+-------------+
|Actor |
|.............|
| Actor ID |
+-------------+
^
:
:
V
+-------------+
|I2RS Client |
|.............|
| Client ID |
+-------------+
^
|
|
V
+-------------+ +-----------------------------+
|I2RS Agent |---------------->|Trace Log |
| | |.............................|
+-------------+ |Timestamp |
^ |Client ID |
| ^ |Actor ID |
Operation + | Result Code |Client Address |
Op Data | |Operation |
V | |Operation Data |
V |Result Code |
+-------------+ +-----------------------------+
|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="Timestamp: ">The specific time, adhering to
<xref target="RFC3339"/> format, at which the I2RS
transaction occurred. Given that many I2RS transactions
can occur in rapid succession, the use of fractional
seconds MUST be used to provide adequate granularity.</t>
<t hangText="Client Identifier: ">The I2RS Client
identifier used to authenticate the Client to the I2RS
Agent.</t>
<t hangText="Actor Identifier: ">This is an opaque
identifier that may be known to the Client from a
northbound controlling application. This is used to trace
the northbound actor driving the actions of the Client.
The Client may not provide this identifier to the Agent if
there is no external actor driving the Client. However,
this field MUST be logged. If the Client does not provide
an actor ID, then the Agent MUST log an empty 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="Operation: ">This is the I2RS operation
performed. For example, this may be an add route operation
if a route is being inserted into a routing table.</t>
<t hangText="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. Some operations MAY not
provide operation data, and in those cases this field MUST
be logged as a NULL string.</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.nitinb-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>
</list>
</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 anchor="syntax" title="I2RS Trace Log Syntax">
<t>The following describes the trace log information model
using Augmented Backus-Naur Form (ABNF) syntax <xref target="RFC5234"/>:</t>
<figure>
<artwork type="abnf"><![CDATA[i2rs-trace-log = timestamp client-id actor-id client-addr operation
operation-data result-code
client-id = uuid
actor-id = byte-string
byte-string = *( %x01-09 / %x0B-0C / %x0E-FF )
; any byte except NUL, CR or LF
client-addr = IP-literal / IPv4address
operation = ALPHA *( ALPHA / "_" / "-" / "(" / ")" )
operation-data = *VCHAR
result-code = 1*( ALPHA / DIGIT / "-" / "_" / "(" / ")" ) ]]></artwork>
</figure>
<t>The ABNF syntax rules <IP-literal>,
<IPv4address>, and <sub-delims> are specified in
<xref target="RFC3986"/>. The core rules <DIGIT>,
<ALPHA> and <VCHAR> are used as described in
Appendix B of <xref target="RFC5234"/>.</t>
<t>Here, <uuid> is specified in <xref target="RFC4122"/>. The idea of using a UUID for the Client
identifier ensures the ID is unique not just in the scope of
the current I2RS Agent, but across Agents as well. This
ensures that two clients that are unaware of each other will
not allocate the same Client ID. That does not preclude two
Clients acting as one for purposes of high availability from
sharing the same UUID as generated by one one of the Clients.
[Note: the format of the Client ID has not yet been decided by
the I2RS WG. This is subject to change.]</t>
<t>The <timestamp> field is defined in <xref target="RFC3339"/>. As stated in <xref target="info_required"/> the fractional second format MUST be
used to provide proper granularity.</t>
<t>The values for <operation>, <operation-data>
and <result-code> are suggestions as the protocol has
not been defined yet. By making these human-readable (as
opposed to opcodes) the log becomes more easily consumable by
operators and administrators trying to troubleshoot issues
relating to I2RS. Even in cases where the operations or codes
might appear as opcodes on the wire, their textual
translations MUST be included in the log. The opcodes
themselves MAY appear in parentheses after the textual
representation.</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="30"/></t>
<figure>
<artwork><![CDATA[
Timestamp: 2013-09-03T12:00:01.21+00:00
Client ID: 5CEF1870-0326-11E2-A21F-0800200C9A66
Actor ID: com.example.RoutingApp
Client Address: 192.0.2.2
Operation: ROUTE_ADD
Operation Data: PREFIX 203.0.113.0 PREFIX-LEN 24 NEXT-HOP
198.51.100.1
Result Code: SUCCESS(0)
]]></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
transactions 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 transactions 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. <xref target="log_rotation"/> talks about rotating the trace log in
order to preserve the transaction 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>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, the I2RS trace log
implementation MAY choose to implement a configurable rotation
schedule. 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 implementor-agnostic and consistent interface to
collect I2RS trace data. Correspondingly, retrieval of the
data should also be made implementor-agnostic.</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
implementor-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>
</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 6.7 of the I2RS architecture <xref target="I-D.ietf-i2rs-architecture"/> goes on to define a
publish-subscribe mechanism for a feed of changes happening
within the I2RS layer. 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. Using pub-sub for the purpose
of logging I2RS interactions augments the areas described
by <xref target="I-D.camwinget-i2rs-pubsub-sec"/>.
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>
</middle>
<back>
<references title="Normative References">
&RFC2119;
&I2RS-ARCHITECTURE;
&I2RS-PROBLEM-STATEMENT;
&RFC3986;
&RFC4122;
&RFC5234;
</references>
<references title="Informative References">
&I2RS-RIB-INFO-MODEL;
&RFC3339;
&RFC5424;
&I2RS-PUBSUB-SEC;
&RFC5737;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 05:28:17 |