draft-ietf-i2rs-traceability.txt   draft-ietf-i2rs-traceability.txt 
I2RS J. Clarke I2RS J. Clarke
Internet-Draft G. Salgueiro Internet-Draft G. Salgueiro
Intended status: Informational C. Pignataro Intended status: Informational C. Pignataro
Expires: November 2, 2016 Cisco Expires: November 14, 2016 Cisco
May 1, 2016 May 13, 2016
Interface to the Routing System (I2RS) Traceability: Framework and Interface to the Routing System (I2RS) Traceability: Framework and
Information Model Information Model
draft-ietf-i2rs-traceability-09 draft-ietf-i2rs-traceability-10
Abstract Abstract
This document describes a framework for traceability in the Interface This document describes a framework for traceability in the Interface
to the Routing System (I2RS) and information model for that to the Routing System (I2RS) and information model for that
framework. It specifies the motivation, requirements, use cases, and framework. It specifies the motivation, requirements, use cases, and
defines an information model for recording interactions between defines an information model for recording interactions between
elements implementing the I2RS protocol. This framework provides a elements implementing the I2RS protocol. This framework provides a
consistent tracing interface for components implementing the I2RS consistent tracing interface for components implementing the I2RS
architecture to record what was done, by which component, and when. architecture to record what was done, by which component, and when.
skipping to change at page 1, line 41 skipping to change at page 1, line 41
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 2, 2016. This Internet-Draft will expire on November 14, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 20 skipping to change at page 2, line 20
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology and Conventions . . . . . . . . . . . . . . . . . 3 2. Terminology and Conventions . . . . . . . . . . . . . . . . . 3
3. Motivation . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Motivation . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5. Information Model . . . . . . . . . . . . . . . . . . . . . . 4 5. Information Model . . . . . . . . . . . . . . . . . . . . . . 4
5.1. I2RS Traceability Framework . . . . . . . . . . . . . . . 4 5.1. I2RS Traceability Framework . . . . . . . . . . . . . . . 4
5.2. I2RS Trace Log Mandatory Fields . . . . . . . . . . . . . 6 5.2. I2RS Trace Log Fields . . . . . . . . . . . . . . . . . . 6
5.3. End of Message Marker . . . . . . . . . . . . . . . . . . 8 5.3. End of Message Marker . . . . . . . . . . . . . . . . . . 9
6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7. Operational Guidance . . . . . . . . . . . . . . . . . . . . 9 7. Operational Guidance . . . . . . . . . . . . . . . . . . . . 10
7.1. Trace Log Creation . . . . . . . . . . . . . . . . . . . 9 7.1. Trace Log Creation . . . . . . . . . . . . . . . . . . . 10
7.2. Trace Log Temporary Storage . . . . . . . . . . . . . . . 10 7.2. Trace Log Temporary Storage . . . . . . . . . . . . . . . 10
7.3. Trace Log Rotation . . . . . . . . . . . . . . . . . . . 10 7.3. Trace Log Rotation . . . . . . . . . . . . . . . . . . . 11
7.4. Trace Log Retrieval . . . . . . . . . . . . . . . . . . . 10 7.4. Trace Log Retrieval . . . . . . . . . . . . . . . . . . . 11
7.4.1. Retrieval Via Syslog . . . . . . . . . . . . . . . . 11 7.4.1. Retrieval Via Syslog . . . . . . . . . . . . . . . . 12
7.4.2. Retrieval Via I2RS Information Collection . . . . . . 11 7.4.2. Retrieval Via I2RS Information Collection . . . . . . 12
7.4.3. Retrieval Via I2RS Pub-Sub . . . . . . . . . . . . . 11 7.4.3. Retrieval Via I2RS Pub-Sub . . . . . . . . . . . . . 12
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
9. Security Considerations . . . . . . . . . . . . . . . . . . . 12 9. Security Considerations . . . . . . . . . . . . . . . . . . . 13
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 13
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 13
11.1. Normative References . . . . . . . . . . . . . . . . . . 13 11.1. Normative References . . . . . . . . . . . . . . . . . . 14
11.2. Informative References . . . . . . . . . . . . . . . . . 13 11.2. Informative References . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction 1. Introduction
The architecture for the Interface to the Routing System The architecture for the Interface to the Routing System
([I-D.ietf-i2rs-architecture]) specifies that I2RS Clients wishing to ([I-D.ietf-i2rs-architecture]) specifies that I2RS Clients wishing to
retrieve or change routing state on a routing element MUST retrieve or change routing state on a routing element MUST
authenticate to an I2RS Agent. The I2RS Client will have a unique authenticate to an I2RS Agent. The I2RS Client will have a unique
identity it provides for authentication, and should provide another, identity it provides for authentication, and should provide another,
opaque identity for applications communicating through it. The opaque identity for applications communicating through it. The
programming of routing state will produce a return code containing programming of routing state will produce a return code containing
the results of the specified operation and associated reason(s) for the results of the specified operation and associated reason(s) for
the result. All of this is critical information to be used for the result. All of this is critical information to be used for
understanding the history of I2RS interactions. understanding the history of I2RS interactions.
This document describes use cases for I2RS traceability. Based on This document defines the framework necessary to trace those
these use cases, the document proposes an information model and interactions between the I2RS Client and I2RS Agent. It goes on to
reporting requirements to provide for effective recording of I2RS describe use cases for traceability within I2RS. Based on these use
interactions. In this context, effective troubleshooting means being cases, the document proposes an information model and reporting
able to identify what operation was performed by a specific I2RS requirements to provide for effective recording of I2RS interactions.
Client, what was the result of the operation, and when that operation In this context, effective troubleshooting means being able to
was performed. identify what operation was performed by a specific I2RS Client via
the I2RS Agent, what was the result of the operation, and when that
Discussions about the retention of the data logged as part of I2RS operation was performed.
traceability, while important, are outside of the scope of this
document.
2. Terminology and Conventions 2. Terminology and Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
The architecture specification for I2RS [I-D.ietf-i2rs-architecture] The architecture specification for I2RS [I-D.ietf-i2rs-architecture]
defines additional terms used in this document that are specific to defines additional terms used in this document that are specific to
the I2RS domain, such as "I2RS Agent", "I2RS Client", etc. The the I2RS domain, such as "I2RS Agent", "I2RS Client", etc. The
skipping to change at page 3, line 39 skipping to change at page 3, line 37
3. Motivation 3. Motivation
As networks scale and policy becomes an increasingly important part As networks scale and policy becomes an increasingly important part
of the control plane that creates and maintains the forwarding state, of the control plane that creates and maintains the forwarding state,
operational complexity increases as well. I2RS offers more granular operational complexity increases as well. I2RS offers more granular
and coherent control over policy and control plane state, but it also and coherent control over policy and control plane state, but it also
removes or reduces the locality of the policy that has been applied removes or reduces the locality of the policy that has been applied
to the control plane at any individual forwarding device. The to the control plane at any individual forwarding device. The
ability to automate and abstract even complex policy-based controls ability to automate and abstract even complex policy-based controls
highlights the need for an equally scalable traceability function to highlights the need for an equally scalable traceability function to
provide event-level granularity of the routing system compliant with provide recording at event-level granularity of the evolution of the
the requirements of I2RS (Section 5 of routing system compliant with the requirements of I2RS (Section 5 of
[I-D.ietf-i2rs-problem-statement]). [I-D.ietf-i2rs-problem-statement]).
4. Use Cases 4. Use Cases
An obvious motivation for I2RS traceability is the need to An obvious motivation for I2RS traceability is the need to
troubleshoot and identify root-causes of problems in these troubleshoot and identify root-causes of problems in these
increasingly complex routing systems. For example, since I2RS is a increasingly complex routing systems. For example, since I2RS is a
high-throughput multi-channel, full duplex and highly responsive high-throughput multi-channel, full duplex and highly responsive
interface, I2RS Clients may be performing a large number of interface, I2RS Clients may be performing a large number of
operations on I2RS Agents concurrently or at nearly the same time and operations on I2RS Agents concurrently or at nearly the same time and
skipping to change at page 4, line 17 skipping to change at page 4, line 15
what changes were made via I2RS at a specific time. what changes were made via I2RS at a specific time.
Some network environments have strong auditing requirements for Some network environments have strong auditing requirements for
configuration and runtime changes. Other environments have policies configuration and runtime changes. Other environments have policies
that require saving logging information for operational or regulatory that require saving logging information for operational or regulatory
compliance considerations. These requirements therefore demand that compliance considerations. These requirements therefore demand that
I2RS provides an account of changes made to network element routing I2RS provides an account of changes made to network element routing
systems. systems.
As I2RS becomes increasingly pervasive in routing environments, a As I2RS becomes increasingly pervasive in routing environments, a
traceability model offers significant advantages and facilitates the traceability model that supports controllable trace log retention
following use cases: using a standardized structured data format offers significant
advtanges, such as the ability to create common tools supporting
automated testing, and facilitates the following use cases:
o Real-time monitoring and troubleshooting of router events;
o Automated event correlation, trend analysis, and anomaly o Automated event correlation, trend analysis, and anomaly
detection; detection;
o Trace log storage for offline (manual or tools) analysis; o Offline (manual or tools-based) analysis of router state evolution
from the retained trace logs;
o Improved accounting of routing system operations;
o Standardized structured data format for writing common tools;
o Common reference for automated testing and incident reporting; o Enhanced network audit, management and forensic analysis
capabilities;
o Real-time monitoring and troubleshooting; o Improved accounting of routing system operations; and
o Enhanced network audit, management and forensic analysis o Providing a standardized format for incident reporting and test
capabilities. logging.
5. Information Model 5. Information Model
These sections describe the I2RS traceability information model and
the detail corresponding to each of the fields to be logged.
5.1. I2RS Traceability Framework 5.1. I2RS Traceability Framework
This section describes a framework for I2RS traceability based on the This section describes a framework for I2RS traceability based on the
I2RS Architecture. Some notable elements of the architecture are in I2RS Architecture.
this section.
The interaction between the optional northbound application, I2RS The interaction between the optional network application that drives
Client, I2RS Agent, the Routing System and the data captured in the Client activity, I2RS Client, I2RS Agent, the Routing System and the
I2RS trace log is shown in Figure 1. data captured in the I2RS trace log is shown in Figure 1.
+----------------+ +---------------+
|Application | +----------------+ |
|.............. | |Application | |
| Application ID | |.............. | | 0 or more Applications
| Application ID | +
+----------------+ +----------------+
^ ^
| 0 .. N |
| |
v v
+-------------+ +-------------+
|I2RS Client | +-------------+ |
|.............| |I2RS Client | |
| Client ID | |.............| | 1 or more Clients
| Client ID | +
+-------------+ +-------------+
^ ^
| 1 .. N |
| |
v v
+-------------+ +-----------------------------+ +-------------+ +-----------------------------+
|I2RS Agent |---------------->|Trace Log | |I2RS Agent |---------------->|Trace Log |
| | |.............................| | | |.............................|
+-------------+ |Log Entry [1 .. N] | +-------------+ |Log Entry [1 .. N] |
^ |.............................| | ^ |.............................|
| |Starting Timestamp | | | |Event ID |
| |Request State | | | |Starting Timestamp |
| |Client ID | | | |Request State |
| |Client Priority | | | |Client ID |
| ^ |Secondary ID | | | |Client Priority |
Operation + | Result Code |Client Address | | | |Secondary ID |
Op Data | |Requested Operation | Operation + | | Result Code |Client Address |
v | |Applied Operation | Op Data | | |Requested Operation |
| |Operation Data Present | | | |Applied Operation |
| |Requested Operation Data | | | |Operation Data Present |
| |Applied Operation Data | | | |Requested Operation Data |
| |Transaction ID | | | |Applied Operation Data |
| |Result Code | | | |Transaction ID |
| |Ending Timestamp | | | |Result Code |
| |Timeout Occurred | | | |Ending Timestamp |
v |End Of Message | | | |Timeout Occurred |
v | |End Of Message |
+-------------+ +-----------------------------+ +-------------+ +-----------------------------+
|Routing | |Routing |
|System | |System |
+-------------+ +-------------+
Figure 1: I2RS Interaction Trace Log Capture Figure 1: I2RS Interaction Trace Log Capture
5.2. I2RS Trace Log Mandatory Fields 5.2. I2RS Trace Log Fields
In order to ensure that each I2RS interaction can be properly traced The following fields comprise an I2RS Trace Log. These fields ensure
back to the Client that made the request at a specific point in time, that each I2RS interaction can be properly traced back to the Client
the following information MUST be collected and stored by the Agent. that made the request at a specific point in time.
The list below describes the fields captured in the I2RS trace log. The list below describes the fields captured in the I2RS trace log.
Entry ID: This is a unique identifier for each entry in the I2RS Event ID: This is a unique identifier for each event in the I2RS
trace log. Since multiple operations can occur from the same trace log. An event can be a Client authenticating with the
Client at the same time, it is important to have an identifier Agent, a Client to Agent operation, or a Client disconnecting from
that can be unambiguously associated to a specific entry. an Agent. Operation events can either be logged atomically upon
completion (in which case they will have both a Starting and an
Ending Timestamp field) or they can be logged at the beginning of
each Request State transition. Since 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. If each state transition is logged for an operation, the
same ID MUST be used for each of Request State log entries In this
way, the life of a request can be easily followed in the I2RS
trace log. Beyond the requirement that the Event ID MUST be
unique for each event, the specific type and value is left up to
the implementation.
Starting Timestamp: The specific time at which the I2RS operation Starting Timestamp: The specific time at which the I2RS operation
entered the specified Request State within the Agent. The time is enters the specified Request State within the Agent. If the log
passed in the [RFC3339] format. Given that many I2RS operations entry covers the entire duration of the request, then this will be
can occur in rapid succession, the use of fractional seconds MUST time the was first received by the Agent. This field MUST be
be used to provide adequate granularity. Fractional seconds present in all entries that specify the beginning of the state
SHOULD be expressed using human-readable 32-bit second and 32-bit transition, as well as those entries that log the entire duration
microsecond granularity in second.microsecond format. In the case of the request. The time is passed in the full [RFC3339] format
when the trace log entry specifies a Request State of COMPLETED including date and offset from Coordinated Universal Time (UTC).
this time will reflect when the operation was first received by Given that many I2RS operations can occur in rapid succession, the
the I2RS Agent. fractional seconds element of the timestamp MUST be used to
provide adequate granularity. Fractional seconds SHOULD be
expressed with at least three significant digits in
second.microsecond format.
Request State: The state of the given operation within the I2RS Request State: The state of the given operation within the I2RS
Agent state machine between the specified Starting and Ending Agent state machine at the specified Starting or Ending
Timestamps. This can be one of the following values: Timestamps. The I2RS Agent SHOULD generate a log entry at the
moment a request enters and exits a state. Upon entering a new
state, the log entry will have a Starting Timestamp set to the
time of entry and no Ending Timestamp. Upon exiting a state, the
log entry will have an Ending Timestamp set to the time of exit
and no Starting Timestamp. The progression of the request through
its various states and be linked using the Event ID. The states
can be one of the following values:
PENDING: The request has been receieved and queued for PENDING: The request has been received and queued for
processing. processing.
IN PROCESS: The request is currently being handled by the I2RS IN PROCESS: The request is currently being handled by the I2RS
Agent. Agent.
COMPLETED: The request has reached a terminal point. COMPLETED: The request has reached a terminal point.
In the case of the COMPLETED state, the Starting and Ending Every state transition SHOULD be logged unless doing so will put
Timestamps will cover the entire duration of the operation an undue performance burden on the I2RS Agent. However, an entry
including time spent in the PENDING and IN PROCESS states.
Every state transition MAY be logged unless doing so will put an
undue performance burden on the I2RS Agent. However, an entry
with Request State set to COMPLETED MUST be logged for all with Request State set to COMPLETED MUST be logged for all
operations. operations. If the COMPLETED state is the only entry for a given
request, then it MUST have both Starting and Ending Timestamps
that cover the entire duration of the request from ingress to the
Agent until completion.
Client Identity: The I2RS Client identity used to authenticate the Client Identity: The I2RS Client identity used to authenticate the
Client to the I2RS Agent. Client to the I2RS Agent.
Client Priority: The I2RS Client priority assigned by the access Client Priority: The I2RS Client priority assigned by the access
control model that authenticates the Client. For example, this control model that authenticates the Client. For example, this
can be set by the NETCONF Access Control Model (NACM) as described can be set by the NETCONF Access Control Model (NACM) as described
in [RFC6536]. in [RFC6536].
Secondary Identity: This is an opaque identity that may be known to Secondary Identity: This is an opaque identity that may be known to
the Client from a northbound controlling application. This is the Client from a controlling network application. This is used
used to trace the northbound application driving the actions of to trace the network application driving the actions of the
the Client. The Client may not provide this identity to the Agent Client. The Client may not provide this identity to the Agent if
if there is no external application driving the Client. However, there is no external network application driving the Client.
this field MUST be logged even if the Client does not provide a However, this field MUST be logged even if the Client does not
Secondary Identity. In that case, the field will be logged with provide a Secondary Identity. In that case, the field will be
an empty value. logged with an empty value.
Client Address: This is the network address of the Client that Client Address: This is the network address of the Client that
connected to the Agent. For example, this may be an IPv4 or IPv6 connected to the Agent. For example, this may be an IPv4 or IPv6
address. address.
Requested Operation: This is the I2RS operation that was requested Requested Operation: This is the I2RS operation that was requested
to be performed. For example, this may be an add route operation 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 if a route is being inserted into a routing table. This may not
be the operation that was actually applied to the Agent. be the operation that was actually applied to the Agent.
In the case of a Client authenticating to the Agent, the Requested
Operation MUST be "CLIENT AUTHENTICATE". In the case of a Client
disconnecting from the Agent, the Requested Operation MUST be
"CLIENT DISCONNECT".
Applied Operation: This is the I2RS operation that was actually Applied Operation: This is the I2RS operation that was actually
performed. This can differ from the Requested Operation in cases performed. This can differ from the Requested Operation in cases
where the Agent cannot satisfy the Requested Operation. This where the Agent cannot satisfy the Requested Operation. This
field may not be logged unless the Request State is COMPLETED. field may not be logged unless the Request State is COMPLETED.
Operation Data Present: This is a Boolean field that indicates Operation Data Present: This is a Boolean field that indicates
whether or not addition per-Operation Data is present. whether or not addition per-Operation Data is present.
Requested Operation Data: This field comprises the data passed to Requested Operation Data: This field comprises the data passed to
the Agent to complete the desired operation. For example, if the the Agent to complete the desired operation. For example, if the
operation is a route add operation, the Operation Data would operation is a route add operation, the Operation Data would
include the route prefix, prefix length, and next hop information include the route prefix, prefix length, and next hop information
to be inserted as well as the specific routing table to which the to be inserted as well as the specific routing table to which the
route will be added. If Operation Data is provided, then the route will be added. If Operation Data is provided, then the
Operation Data Present field MUST be set to TRUE. Some operations Operation Data Present field MUST be set to TRUE. Some operations
may not provide operation data. In those cases, the Operation may not provide operation data. In those cases, the Operation
Data Present field MUST be set to FALSE, and this field MUST be 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 empty. This may not represent the data that was used for the
operation that was actually applied on the Agent. operation that was actually applied on the Agent.
When a Client authenticates to the Agent, the Requested Operation
Data MUST contain the Client priority. Other attributes such as
credentials used for authentication MAY be logged.
Applied Operation Data: This field comprises the data that was Applied Operation Data: This field comprises the data that was
actually applied as part of the Applied Operation. If the Agent actually applied as part of the Applied Operation. If the Agent
cannot satisfy the Requested Operation with the Requested cannot satisfy the Requested Operation with the Requested
Operation Data, then this field can differ from the Requested Operation Data, then this field can differ from the Requested
Operation Data. This field may not be logged unless the Request Operation Data. This field will be empty unless Requested
State is COMPLETED. Operation Data was specified. This field may not be logged unless
the Request State is COMPLETED.
Transaction ID: The Transaction Identity represents that this Transaction ID: The Transaction Identity represents that this
particular operation is part of a long-running I2RS transaction particular operation is part of a long-running I2RS transaction
that can consist of multiple, related I2RS operations. Using this that can consist of multiple, related I2RS operations. Using this
value, one can relate multiple log entries together as they are value, one can relate multiple log entries together as they are
part of a single, overall I2RS operation. part of a single, overall I2RS operation. This is an optional
field that may not be logged unless the event is part of a long-
running transaction.
Result Code: This field holds the result of the operation once the Result Code: This field holds the result of the operation once the
Request State is COMPLETED. In the case of RIB operations, this Request State is COMPLETED. In the case of Routing Information
MUST be the return code as specified in Section 4 of Base (RIB) operations, this MUST be the return code as specified
[I-D.ietf-i2rs-rib-info-model]. The operation may not complete in Section 4 of [I-D.ietf-i2rs-rib-info-model]. The operation may
with a result code in the case of a timeout. If the operation not complete with a result code in the case of a timeout. If the
fails to complete, it MUST still log the attempted operation with operation fails to complete, it MUST still log the attempted
an appropriate result code. operation with an appropriate result code.
Timeout Occurred: This is a Boolean field that indicates whether or Timeout Occurred: This is a Boolean field that indicates whether or
not a timeout occurred in the operation. When this is true, the not a timeout occurred in the operation. When this is true, the
value of the Ending Timestamp MUST be set to the time the Agent value of the Ending Timestamp MUST be set to the time the Agent
recorded for the timeout occurrence. This field may not be logged recorded for the timeout occurrence. This field may not be logged
unless the Request State is COMPLETED. unless the Request State is COMPLETED.
Ending Timestamp: The specific time at which the I2RS operation Ending Timestamp: The specific time at which the I2RS operation
exited the specified Request State within the I2RS Agent. The exits the specified Request State within the I2RS Agent. If the
time is passed in the [RFC3339] format. Given that many I2RS log entry covers the entire duration of the request, then this
operations can occur in rapid succession, the use of fractional will be time the request reached a terminal point within the
seconds MUST be used to provide adequate granularity. Fractional Agent. This field MUST be present in all entries that specify the
seconds SHOULD be expressed using human-readable 32-bit second and ending of the state transition, as well as those entries that log
32-bit microsecond granularity in second.microsecond format. the entire duration of the request. The time is passed in the
full [RFC3339] format including date and offset from Coordinated
Universal Time (UTC). See the description for Starting Timestamp
above for the proper format of Ending Timestamp.
End Of Message: Each log entry SHOULD have an appropriate End Of End Of Message: Each log entry SHOULD have an appropriate End Of
Message (EOM) indicator. See section Section 5.3 below for more Message (EOM) indicator. See section Section 5.3 below for more
details. details.
5.3. End of Message Marker 5.3. End of Message Marker
Because of variability within I2RS trace log fields, implementors Because of variability within I2RS trace log fields, implementors
MUST use a format-appropriate end of message (EOM) indicator in order MUST use a format-appropriate end of message (EOM) indicator in order
to signify the end of a particular record. That is, regardless of to signify the end of a particular record. That is, regardless of
skipping to change at page 9, line 10 skipping to change at page 10, line 5
the EOM marker may be a newline character. In an XML formated log, the EOM marker may be a newline character. In an XML formated log,
the schema would provide for element tags that denote beginning and the schema would provide for element tags that denote beginning and
end of records. In a JSON formated log, the syntax would provide end of records. In a JSON formated log, the syntax would provide
record separation (likely by comma-separated array elements). record separation (likely by comma-separated array elements).
6. Examples 6. Examples
This section shows a sample of what the fields and values could look This section shows a sample of what the fields and values could look
like. like.
Entry ID: 1 Event ID: 1
Starting Timestamp: 2013-09-03T12:00:01.21+00:00 Starting Timestamp: 2013-09-03T12:00:01.21+00:00
Request State: COMPLETED Request State: COMPLETED
Client ID: 5CEF1870-0326-11E2-A21F-0800200C9A66 Client ID: 5CEF1870-0326-11E2-A21F-0800200C9A66
Client Priority: 100 Client Priority: 100
Secondary ID: com.example.RoutingApp Secondary ID: com.example.RoutingApp
Client Address: 2001:db8:c0c0::2 Client Address: 2001:db8:c0c0::2
Requested Operation: ROUTE_ADD Requested Operation: ROUTE_ADD
Applied Operation: ROUTE_ADD Applied Operation: ROUTE_ADD
Operation Data Present: TRUE Operation Data Present: TRUE
Requested Operation Data: PREFIX 2001:db8:feed:: PREFIX-LEN 64 Requested Operation Data: PREFIX 2001:db8:feed:: PREFIX-LEN 64
skipping to change at page 9, line 46 skipping to change at page 10, line 41
environment. In this section we only provide fundamental and environment. In this section we only provide fundamental and
generalized operational guidelines that are implementation- generalized operational guidelines that are implementation-
independent. independent.
7.1. Trace Log Creation 7.1. Trace Log Creation
The I2RS Agent interacts with the Routing and Signaling functions of The I2RS Agent interacts with the Routing and Signaling functions of
the Routing Element. Since the I2RS Agent is responsible for the Routing Element. Since the I2RS Agent is responsible for
actually making the routing changes on the associated network device, actually making the routing changes on the associated network device,
it creates and maintains a log of operations that can be retrieved to it creates and maintains a log of operations that can be retrieved to
troubleshoot I2RS-related impact to the network. troubleshoot I2RS-related impact to the network. Changes that occur
to the network element's local configuration outside of the I2RS
protocol that preempt I2RS state will only be logged if the network
element notifies the I2RS Agent.
7.2. Trace Log Temporary Storage 7.2. Trace Log Temporary Storage
The trace information may be temporarily stored either in an in- 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 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 to the number of I2RS operations expected on a given Agent so that
the appropriate storage medium is used and to maximize the the appropriate storage medium is used and to maximize the
effectiveness of the log while not impacting the performance and effectiveness of the log while not impacting the performance and
health of the Agent. Client requests may not always be processed health of the Agent. Client requests may not always be processed
synchronously or within a bounded time period. Consequently, to synchronously or within a bounded time period. Consequently, to
skipping to change at page 10, line 27 skipping to change at page 11, line 19
load on the Agent and the network element. load on the Agent and the network element.
Section 7.3 discusses rotating the trace log in order to preserve the Section 7.3 discusses rotating the trace log in order to preserve the
operation history without exhausting Agent or network device operation history without exhausting Agent or network device
resources. It is perfectly acceptable, therefore, to use both an in- resources. It is perfectly acceptable, therefore, to use both an in-
memory buffer for recent operations while rotating or archiving older memory buffer for recent operations while rotating or archiving older
operations to a local file. operations to a local file.
It is outside the scope of this document to specify the It is outside the scope of this document to specify the
implementation details (i.e., size, throughput, data protection, implementation details (i.e., size, throughput, data protection,
privacy, etc.) for the physical storage of the I2RS log file. Data etc.) for the physical storage of the I2RS log file. In terms of
retention policies of the I2RS traceability log is also outside the data retention, attention should be paid the length of time I2RS
scope of this document. trace log data is kept when that data contains security or privacy-
sensitive attributes. The longer this data is retained, the higher
the impact if it were to be leaked. It is also possible that
legislation may impose some additional requirements on the minimum
and/or maximum durations for which some kinds of data may be
retained.
7.3. Trace Log Rotation 7.3. Trace Log Rotation
In order to prevent the exhaustion of resources on the I2RS Agent or In order to prevent the exhaustion of resources on the I2RS Agent or
its associated network device, it is RECOMMENDED that the I2RS Agent its associated network device, it is RECOMMENDED that the I2RS Agent
implements trace log rotation. The details on how this is achieved implements trace log rotation. The details on how this is achieved
are left to the implementation and outside the scope of this are left to the implementation and outside the scope of this
document. However, it should be possible to do file rotation based 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 on either time or size of the current trace log. If file rollover is
supported, multiple archived log files should be supported in order supported, multiple archived log files should be supported in order
skipping to change at page 11, line 11 skipping to change at page 12, line 8
information model is to establish a vendor-agnostic and consistent information model is to establish a vendor-agnostic and consistent
interface to collect I2RS trace data. Correspondingly, retrieval of interface to collect I2RS trace data. Correspondingly, retrieval of
the data should also be made vendor-agnostic. the data should also be made vendor-agnostic.
Despite the fact that export of I2RS trace log information could be Despite the fact that export of I2RS trace log information could be
an invaluable diagnostic tool for off-box analysis, exporting this an invaluable diagnostic tool for off-box analysis, exporting this
information MUST NOT interfere with the ability of the Agent to information MUST NOT interfere with the ability of the Agent to
process new incoming operations. process new incoming operations.
The following three sections describe potential ways the trace log The following three sections describe potential ways the trace log
can be accessed. At least one of these three MUST be used, with the can be accessed. The use of I2RS Pub-Sub for accessing trace log
I2RS mechanisms being preferred as they are vendor-independent data is mandatory-to-implement, while others are optional.
approaches to retrieving the data.
7.4.1. Retrieval Via Syslog 7.4.1. Retrieval Via Syslog
The syslog protocol [RFC5424] is a standard way of sending event The syslog protocol [RFC5424] is a standard way of sending event
notification messages from a host to a collector. However, the notification messages from a host to a collector. However, the
protocol does not define any standard format for storing the protocol does not define any standard format for storing the
messages, and thus implementors of I2RS tracing would be left to messages, and thus implementors of I2RS tracing would be left to
define their own format. So, while the data contained within the define their own format. So, while the data contained within the
syslog message would adhere to this information model, and may be syslog message would adhere to this information model, and may be
consumable by a human operator, it would not be easily parseable by a consumable by a human operator, it would not be easily parseable by a
machine. Syslog MAY be employed as a means of retrieving or machine. Syslog MAY be employed as a means of retrieving or
disseminating the I2RS trace log contents. disseminating the I2RS trace log contents.
If syslog is used for trace log retrieval, then existing logging If syslog is used for trace log retrieval, then existing logging
infrastructure and capabilities of syslog [RFC5424] should be infrastructure and capabilities of syslog [RFC5424] should be
leveraged without the need to define or extend existing formats. For leveraged without the need to define or extend existing formats.
example, the various fields described in Section 5.2 SHOULD be That is, the various fields described in Section 5.2 SHOULD be
modeled and encoded as Structured Data Elements (referred to as "SD- modeled and encoded as Structured Data Elements (referred to as "SD-
ELEMENT"), as described in Section 6.3.1 of [RFC5424]. ELEMENT"), as described in Section 6.3.1 of [RFC5424].
7.4.2. Retrieval Via I2RS Information Collection 7.4.2. Retrieval Via I2RS Information Collection
Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture] Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture]
defines a mechanism for information collection. The information defines a mechanism for information collection. The information
collected includes obtaining a snapshot of a large amount of data 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 from the network element. It is the intent of I2RS to make this data
available in an implementor-agnostic fashion. Therefore, the I2RS available in an implementor-agnostic fashion. Therefore, the I2RS
trace log SHOULD be made available via the I2RS information trace log SHOULD be made available via the I2RS information
collection mechanism either as a single snapshot or via a collection mechanism either as a single snapshot or via a
subscription stream. subscription stream.
7.4.3. Retrieval Via I2RS Pub-Sub 7.4.3. Retrieval Via I2RS Pub-Sub
Section 7.6 of the I2RS architecture [I-D.ietf-i2rs-architecture] Section 7.6 of the I2RS architecture [I-D.ietf-i2rs-architecture]
goes on to describe notification mechanisms for a feed of changes goes on to describe notification mechanisms for a feed of changes
happening within the I2RS layer. Specifically, the requirements for happening within the I2RS layer. Specifically, the requirements for
a publish-subscribe system for I2RS are defined in a publish-subscribe system for I2RS are defined in
[I-D.ietf-i2rs-pub-sub-requirements]. I2RS Agents SHOULD support [I-D.ietf-i2rs-pub-sub-requirements]. I2RS Agents MUST support
publishing I2RS trace log information to that feed as described in publishing I2RS trace log information to that feed as described in
that document. Subscribers would then receive a live stream of I2RS that document. Subscribers would then receive a live stream of I2RS
interactions in trace log format and could flexibly choose to do a interactions in trace log format and could flexibly choose to do a
number of things with the log messages. For example, the subscribers number of things with the log messages. For example, the subscribers
could log the messages to a datastore, aggregate and summarize could log the messages to a datastore, aggregate and summarize
interactions from a single Client, etc. The full range of potential interactions from a single Client, etc. The full range of potential
activites is virtually limitless and the details of how they are activites is virtually limitless and the details of how they are
performed are outside the scope of this document, however. performed are outside the scope of this document, however.
8. IANA Considerations 8. IANA Considerations
skipping to change at page 12, line 44 skipping to change at page 13, line 41
if transferring log files. Additionally, the potentially sensitive if transferring log files. Additionally, the potentially sensitive
information contained in a log file SHOULD be adequately anonymized information contained in a log file SHOULD be adequately anonymized
or obfuscated by operators to ensure its privacy. or obfuscated by operators to ensure its privacy.
10. Acknowledgments 10. Acknowledgments
The authors would like to thank Alia Atlas for her initial feedback The authors would like to thank Alia Atlas for her initial feedback
and overall support for this work. Additionally, the authors and overall support for this work. Additionally, the authors
acknowledge Alvaro Retana, Russ White, Matt Birkner, Jeff Haas, Joel acknowledge Alvaro Retana, Russ White, Matt Birkner, Jeff Haas, Joel
Halpern, Dean Bogdanovich, Ignas Bagdonas, Nobo Akiya, Kwang-koog Halpern, Dean Bogdanovich, Ignas Bagdonas, Nobo Akiya, Kwang-koog
Lee, Sue Hares, Mach Chen, and Alex Clemm for their reviews, Lee, Sue Hares, Mach Chen, Alex Clemm, Stephen Farrell, Benoit
contributed text, and suggested improvements to this document. Claise, Les Ginsberg, Suresh Krishnan, and Elwyn Davies for their
reviews, contributed text, and suggested improvements to this
document.
11. References 11. References
11.1. Normative References 11.1. Normative References
[I-D.ietf-i2rs-architecture] [I-D.ietf-i2rs-architecture]
Atlas, A., Halpern, J., Hares, S., Ward, D., and T. Atlas, A., Halpern, J., Hares, S., Ward, D., and T.
Nadeau, "An Architecture for the Interface to the Routing Nadeau, "An Architecture for the Interface to the Routing
System", draft-ietf-i2rs-architecture-13 (work in System", draft-ietf-i2rs-architecture-15 (work in
progress), February 2016. progress), April 2016.
[I-D.ietf-i2rs-problem-statement]
Atlas, A., Nadeau, T., and D. Ward, "Interface to the
Routing System Problem Statement", draft-ietf-i2rs-
problem-statement-10 (work in progress), February 2016.
[I-D.ietf-i2rs-pub-sub-requirements] [I-D.ietf-i2rs-pub-sub-requirements]
Voit, E., Clemm, A., and A. Prieto, "Requirements for Voit, E., Clemm, A., and A. Prieto, "Requirements for
Subscription to YANG Datastores", draft-ietf-i2rs-pub-sub- Subscription to YANG Datastores", draft-ietf-i2rs-pub-sub-
requirements-06 (work in progress), April 2016. requirements-06 (work in progress), April 2016.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
11.2. Informative References
[I-D.ietf-i2rs-rib-info-model]
Bahadur, N., Kini, S., and J. Medved, "Routing Information
Base Info Model", draft-ietf-i2rs-rib-info-model-08 (work
in progress), October 2015.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<http://www.rfc-editor.org/info/rfc3339>. <http://www.rfc-editor.org/info/rfc3339>.
[RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, [RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424,
DOI 10.17487/RFC5424, March 2009, DOI 10.17487/RFC5424, March 2009,
<http://www.rfc-editor.org/info/rfc5424>. <http://www.rfc-editor.org/info/rfc5424>.
11.2. Informative References
[I-D.ietf-i2rs-problem-statement]
Atlas, A., Nadeau, T., and D. Ward, "Interface to the
Routing System Problem Statement", draft-ietf-i2rs-
problem-statement-10 (work in progress), February 2016.
[I-D.ietf-i2rs-rib-info-model]
Bahadur, N., Kini, S., and J. Medved, "Routing Information
Base Info Model", draft-ietf-i2rs-rib-info-model-08 (work
in progress), October 2015.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536, Protocol (NETCONF) Access Control Model", RFC 6536,
DOI 10.17487/RFC6536, March 2012, DOI 10.17487/RFC6536, March 2012,
<http://www.rfc-editor.org/info/rfc6536>. <http://www.rfc-editor.org/info/rfc6536>.
Authors' Addresses Authors' Addresses
Joe Clarke Joe Clarke
Cisco Systems, Inc. Cisco Systems, Inc.
7200-12 Kit Creek Road 7200-12 Kit Creek Road
Research Triangle Park, NC 27709 Research Triangle Park, NC 27709
 End of changes. 46 change blocks. 
151 lines changed or deleted 200 lines changed or added

This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/