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/ |