< draft-mm-netconf-time-capability-05.txt   draft-mm-netconf-time-capability-09.txt >
Network Working Group T. Mizrahi Network Working Group T. Mizrahi
Internet Draft Y. Moses Internet Draft Y. Moses
Intended status: Experimental Technion, Israel Institute of Technology Intended status: Experimental Technion, Israel Institute of Technology
Expires: November 2015 May 7, 2015 Expires: April 2016 October 15, 2015
Time Capability in NETCONF Time Capability in NETCONF
draft-mm-netconf-time-capability-05.txt draft-mm-netconf-time-capability-09.txt
Abstract Abstract
This document defines a capability-based extension to the Network This document defines a capability-based extension to the Network
Configuration Protocol (NETCONF) that allows time-triggered Configuration Protocol (NETCONF) that allows time-triggered
configuration and management operations. This extension allows configuration and management operations. This extension allows
NETCONF clients to invoke configuration updates according to NETCONF clients to invoke configuration updates according to
scheduled times, and allows NETCONF servers to attach timestamps to scheduled times, and allows NETCONF servers to attach timestamps to
the data they send to NETCONF clients. the data they send to NETCONF clients.
skipping to change at page 1, line 40 skipping to change at page 1, line 40
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."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on November 7, 2015. This Internet-Draft will expire on April 15, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction ................................................. 3 1. Introduction...................................................3
2. Conventions used in this document ............................ 3 2. Conventions used in this document..............................3
2.1. Keywords ................................................ 3 2.1. Key words.................................................3
2.2. Abbreviations ........................................... 3 2.2. Abbreviations.............................................4
2.3. Terminology ............................................. 3 2.3. Terminology...............................................4
3. Using Time in NETCONF ........................................ 4 3. Using Time in NETCONF..........................................4
3.1. The Time Capability in a Nutshell ....................... 4 3.1. The Time Capability in a Nutshell.........................4
3.2. Notifications and Cancellation Messages ................. 6 3.2. Notifications and Cancellation Messages...................6
3.3. Synchronization Aspects ................................. 8 3.3. Synchronization Aspects...................................8
3.4. Scheduled Time Format ................................... 9 3.4. Scheduled Time Format.....................................9
3.5. Scheduling Tolerance .................................... 9 3.5. Scheduling Tolerance......................................9
3.6. Near Future Scheduling vs. Far Future Scheduling ....... 10 3.6. Near Future Scheduling vs. Far Future Scheduling.........10
3.7. Time Interval Format ................................... 11 3.7. Time Interval Format.....................................12
4. Time Capability ............................................. 11 4. Time Capability...............................................13
4.1. Overview ............................................... 11 4.1. Overview.................................................13
4.2. Dependencies ........................................... 12 4.2. Dependencies.............................................13
4.3. Capability Identifier .................................. 12 4.3. Capability Identifier....................................13
4.4. New Operations ......................................... 12 4.4. New Operations...........................................13
4.5. Modifications to Existing Operations ................... 12 4.5. Modifications to Existing Operations.....................14
4.6. Interactions with Other Capabilities ................... 13 4.5.1. Affected Operations.................................14
5. Examples .................................................... 13 4.5.2. Processing Scheduled Operations.....................15
5.1. <scheduled-time> Example ............................... 13 4.6. Interactions with Other Capabilities.....................15
5.2. <get-time> Example ..................................... 14 5. sched-max-futures.............................................16
5.3. Error Example .......................................... 15 5.1. <scheduled-time> Example.................................16
6. Security Considerations ..................................... 16 5.2. <get-time> Example.......................................17
6.1. General Security Considerations ........................ 16 5.3. Error Example............................................17
6.2. YANG Module Security Considerations .................... 16 6. Security Considerations.......................................18
7. IANA Considerations ......................................... 17 6.1. General Security Considerations..........................18
8. Acknowledgments ............................................. 17 6.2. YANG Module Security Considerations......................19
9. References .................................................. 18 7. IANA Considerations...........................................20
9.1. Normative References ................................... 18 8. Acknowledgments...............................................20
9.2. Informative References ................................. 18 9. References....................................................21
Appendix A. YANG Module for the Time Capability ................ 19 9.1. Normative References.....................................21
9.2. Informative References...................................21
Appendix A. YANG Module for the Time Capability..................22
1. Introduction 1. Introduction
The Network Configuration Protocol (NETCONF) defined in [RFC6241] The Network Configuration Protocol (NETCONF) defined in [RFC6241]
provides mechanisms to install, manipulate, and delete the provides mechanisms to install, manipulate, and delete the
configuration of network devices. NETCONF allows clients to configure configuration of network devices. NETCONF allows clients to configure
and monitor NETCONF servers using remote procedure calls (RPC). and monitor NETCONF servers using remote procedure calls (RPC).
NETCONF, as defined in [RFC6241], is asynchronous; when a client NETCONF, as defined in [RFC6241], is asynchronous; when a client
invokes an RPC, it has no control over the time at which the RPC is invokes an RPC, it has no control over the time at which the RPC is
skipping to change at page 3, line 27 skipping to change at page 3, line 27
Time-based configuration ([HotSDN], [TimeTR]) can be a useful tool Time-based configuration ([HotSDN], [TimeTR]) can be a useful tool
that enables an entire class of coordinated and scheduled that enables an entire class of coordinated and scheduled
configuration procedures. Time-triggered configuration allows configuration procedures. Time-triggered configuration allows
coordinated network updates in multiple devices; a client can invoke coordinated network updates in multiple devices; a client can invoke
a coordinated configuration change by sending RPCs to multiple a coordinated configuration change by sending RPCs to multiple
servers with the same scheduled execution time. A client can also servers with the same scheduled execution time. A client can also
invoke a time-based sequence of updates by sending n RPCs with n invoke a time-based sequence of updates by sending n RPCs with n
different update times, T1, T2, ..., Tn, determining the order in different update times, T1, T2, ..., Tn, determining the order in
which the RPCs are executed. which the RPCs are executed.
This memo defines the time capability in NETCONF. This extension This memo defines the :time capability in NETCONF. This extension
allows clients to determine the scheduled execution time of RPCs they allows clients to determine the scheduled execution time of RPCs they
send. It also allows a server that receives an RPC to report its send. It also allows a server that receives an RPC to report its
actual execution time to the client. actual execution time to the client.
The NETCONF time capability is intended for scheduling RPCs that
should be performed in the near future, allowing to coordinate
simultaneous configuration changes, or to specify an order of
configuration updates. Time-of-day-based policies and far-future
scheduling, e.g., [Cond], are outside the scope of this memo.
This memo is defined for experimental purposes, and will allow the
community to experiment with the NETCONF time capability. It is
expected that based on the lessons learned from this experience the
NETCONF working group will be able to consider whether to adopt the
time capability.
2. Conventions used in this document 2. Conventions used in this document
2.1. Keywords 2.1. Key words
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 [RFC2199]. document are to be interpreted as described in [RFC2119].
2.2. Abbreviations 2.2. Abbreviations
NETCONF Network Configuration Protocol NETCONF Network Configuration Protocol
RPC Remote Procedure Call RPC Remote Procedure Call
2.3. Terminology 2.3. Terminology
o Capability [RFC6142]: A functionality that supplements the base o Capability [RFC6241]: A functionality that supplements the base
NETCONF specification. NETCONF specification.
o Client [RFC6142]: Invokes protocol operations on a server. In o Client [RFC6241]: Invokes protocol operations on a server. In
addition, a client can subscribe to receive notifications from a addition, a client can subscribe to receive notifications from a
server. server.
o Execution time: The execution time of an RPC is defined as the o Execution time: The execution time of an RPC is defined as the
time at which a server completes the execution of an RPC. time at which a server completes the execution of an RPC.
o Scheduled time: The scheduled time of an RPC is the time at which o Scheduled RPC: an RPC that is scheduled to be performed at a
predetermined time, which is included in the <rpc> message.
o Scheduled time: The scheduled time of an RPC is the time at which
the RPC should be invoked. The scheduled time is determined by the the RPC should be invoked. The scheduled time is determined by the
client, and enforced by the server. client, and enforced by the server.
o Server [RFC6142]: Executes protocol operations invoked by a o Server [RFC6241]: Executes protocol operations invoked by a
client. In addition, a server can send notifications to a client. client. In addition, a server can send notifications to a client.
3. Using Time in NETCONF 3. Using Time in NETCONF
3.1. The Time Capability in a Nutshell 3.1. The Time Capability in a Nutshell
The :time capability provides two main functions: The :time capability provides two main functions:
o Scheduling: o Scheduling:
When a client sends an RPC to a server, the RPC message MAY When a client sends an RPC to a server, the RPC message MAY
include a scheduled time, Ts (see Figure 1). The server then include the scheduled-time element, denoted by Ts in Figure 1. The
executes the RPC at the scheduled time Ts, and once completed the server then executes the RPC at the scheduled time Ts, and once
server can respond with an RPC reply message. completed the server can respond with an RPC reply message.
o Reporting: o Reporting:
When a client sends an RPC to a server, the RPC message MAY When a client sends an RPC to a server, the RPC message MAY
include a get-time element (see Figure 2), requesting the server include a get-time element (see Figure 2), requesting the server
to return the execution time of the RPC. In this case, after the to return the execution time of the RPC. In this case, after the
server performs the RPC it responds with an RPC reply that server performs the RPC it responds with an RPC reply that
includes the execution time, Te. includes the execution time, Te.
RPC _________ RPC _________
executed \ executed \
\/ \/
Ts Ts
skipping to change at page 5, line 31 skipping to change at page 5, line 31
Te Te
server ------------+---------------- ----> time server ------------+---------------- ----> time
/\ \ /\ \
rpc / \ rpc-reply rpc / \ rpc-reply
(get-time)/ \ (Te) (get-time)/ \ (Te)
/ \/ / \/
client ----------------------------- client -----------------------------
Figure 2 Reporting the Execution Time of an RPC Figure 2 Reporting the Execution Time of an RPC
The two scenarios discussed above imply that a third scenario can Example 1. A client needs to trigger a commit at n servers, so that
also be supported (Figure 3), where the client invokes an RPC that the n servers perform the commit as close as possible to
includes a scheduled time, Ts, as well as the get-time element. This simultaneously. Without the time capability, the client sends a
allows the client to receive feedback about the actual execution sequence of n commit messages, and thus each server performs the
commit at a different time. By using the time capability, the client
can send commit messages that are scheduled to take place at a chosen
time Ts, for example 5 seconds in the future, causing the servers to
invoke the commit as close as possible to time Ts.
Example 2. In many applications it is desirable to monitor events or
collect statistics regarding a common time reference. A client can
send a set of get-config messages that is scheduled to be executed at
multiple servers at the same time, providing a simultaneous system-
wide view of the state of the servers. Moreover, a client can use the
get-time element in its get-config messages, providing a time
reference to the sampled element.
The scenarios of Figure 1 and Figure 2 imply that a third scenario
can also be supported (Figure 3), where the client invokes an RPC
that includes a scheduled time, Ts, as well as the get-time element.
This allows the client to receive feedback about the actual execution
time, Te. Ideally, Ts=Te. However, the server may execute the RPC at time, Te. Ideally, Ts=Te. However, the server may execute the RPC at
a slightly different time than Ts, for example if the server is tied a slightly different time than Ts, for example if the server is tied
up with other tasks at Ts. up with other tasks at Ts.
RPC _________ RPC _________
executed \ executed \
\/ \/
Ts Te Ts Te
server -------------+-+------------- ----> time server -------------+-+------------- ----> time
/\ \ /\ \
skipping to change at page 7, line 29 skipping to change at page 7, line 29
A client can cancel a scheduled RPC by sending a <cancel-schedule> A client can cancel a scheduled RPC by sending a <cancel-schedule>
RPC. The <cancel-schedule> RPC includes the <schedule-id> of the RPC. The <cancel-schedule> RPC includes the <schedule-id> of the
scheduled RPC that needs to be cancelled. scheduled RPC that needs to be cancelled.
The <cancel-schedule> RPC, defined in this document, can be used to The <cancel-schedule> RPC, defined in this document, can be used to
perform a coordinated all-or-none procedure, where either all the perform a coordinated all-or-none procedure, where either all the
servers perform the operation on schedule, or the operation is servers perform the operation on schedule, or the operation is
aborted. aborted.
Example. The client sends scheduled RPC messages to server 1 and Example 3. A client sends scheduled RPC messages to server 1 and
server 2, both scheduled to Ts. Server 1 sends a notification that server 2, both scheduled to be performed at time Ts. Server 1 sends a
indicates it has successfully schedled the RPC, while server 2 notification indicating that it has successfully scheduled the RPC,
replies with an unknown-element error [RFC6241] that indicates that while server 2 replies with an unknown-element error [RFC6241] that
it does not support the time capability. The client sends a <cancel- indicates that it does not support the time capability. The client
schedule> RPC to server 1, and receives an rpc-reply. The message sends a <cancel-schedule> RPC to server 1, and receives an rpc-reply.
exchange between the client and server 1 in this example is The message exchange between the client and server 1 in this example
illustrated in Figure 5. is illustrated in Figure 5.
RPC not __________ RPC not __________
executed \ executed \
\/ \/
Ts Ts
server --------------------------------+--- ----> time server --------------------------------+--- ----> time
/\ \ /\ \ /\ \ /\ \
rpc / \notifi- /cancel- \ rpc-reply rpc / \notifi- /cancel- \ rpc-reply
(Ts)/ \cation /schedule \ (Ts)/ \cation /schedule \
/ \/ / \/ / \/ / \/
client ------------------------------------ client ------------------------------------
Figure 5 Cancellation Message Figure 5 Cancellation Message
A cancel-schedule message MUST NOT include the scheduled-time
parameter. A server that receives a cancel-schedule should try to
cancel the schedule as soon as possible. If the server is unable to
cancel the scheduled RPC, for example because it has already been
executed, it should respond with an rpc-error [RFC6241], in which the
error-type is 'protocol', and the error-tag is 'operation-failed'.
3.3. Synchronization Aspects 3.3. Synchronization Aspects
The time capability defined in this document requires clients and The time capability defined in this document requires clients and
servers to maintain clocks. It is assumed that clocks are servers to maintain clocks. It is assumed that clocks are
synchronized by a method that is outside the scope of this document, synchronized by a method that is outside the scope of this document,
e.g., [NTP] or [IEEE1588]. e.g., [NTP] or [IEEE1588].
This document does not define any requirements pertaining to the This document does not define any requirements pertaining to the
degree of accuracy of performing scheduled RPCs. Note that two degree of accuracy of performing scheduled RPCs. Note that two
factors affect how accurately the server can perform a scheduled RPC; factors affect how accurately the server can perform a scheduled RPC;
skipping to change at page 8, line 42 skipping to change at page 8, line 49
are implemented by a combination of hardware and software. While the are implemented by a combination of hardware and software. While the
execution time of a hardware module can typically be predicted with a execution time of a hardware module can typically be predicted with a
high level of accuracy, the execution time of a software module may high level of accuracy, the execution time of a software module may
be variable and hard to predict. A configuration update would be variable and hard to predict. A configuration update would
typically require the server's software to be involved, thus typically require the server's software to be involved, thus
affecting how accurately the RPC can be scheduled. affecting how accurately the RPC can be scheduled.
Another important aspect of synchronization, is monitoring; a client Another important aspect of synchronization, is monitoring; a client
should be able to check whether a server is synchronized to a should be able to check whether a server is synchronized to a
reference time source. Typical synchronization protocols, such as the reference time source. Typical synchronization protocols, such as the
Network Time Protocol ([NTP], [RFC5907]) provide the means to verify Network Time Protocol [NTP] provide the means ([RFC5907], [RFC7317])
that a clock is synchronized to a time reference by querying its to verify that a clock is synchronized to a time reference by
Management Information Base (MIB). The get-time feature defined in querying its Management Information Base (MIB). The get-time feature
this document (see Figure 2) allows a client to obtain a rough defined in this document (see Figure 2) allows a client to obtain a
estimate of the time offset between the client's clock and the rough estimate of the time offset between the client's clock and the
server's clock. server's clock.
Since servers do not perform configuration changes instantaneously, Since servers do not perform configuration changes instantaneously,
the processing time of an RPC should not be overlooked. The scheduled the processing time of an RPC should not be overlooked. The scheduled
time always refers to the start time of the RPC, and the execution time always refers to the start time of the RPC, and the execution
time always refers to its completion time. time always refers to its completion time.
3.4. Scheduled Time Format 3.4. Scheduled Time Format
The scheduled time and execution time fields in RPC messages use a The scheduled time and execution time fields in RPC messages use a
common time format field. common time format field.
The time format used in this document is the date-and-time format, The time format used in this document is the date-and-time format,
that is defined in Section 5.6 of [RFC3339] and in Section 3 of that is defined in Section 5.6 of [RFC3339] and in Section 3 of
[RFC6021]. [RFC6991].
leaf scheduled-time { leaf scheduled-time {
type yang:date-and-time; type yang:date-and-time;
description description
"The time at which the RPC is scheduled to be performed."; "The time at which the RPC is scheduled to be performed.";
} }
leaf execution-time { leaf execution-time {
type yang:date-and-time; type yang:date-and-time;
description description
skipping to change at page 10, line 31 skipping to change at page 10, line 31
time-interval format (Section 3.7.), and their default value is 15 time-interval format (Section 3.7.), and their default value is 15
seconds. seconds.
If the scheduled time, Ts is within the scheduling tolerance range, If the scheduled time, Ts is within the scheduling tolerance range,
the scheduled RPC is performed; if Ts occurs in the past and within the scheduled RPC is performed; if Ts occurs in the past and within
the scheduling tolerance, the server performs the RPC as soon as the scheduling tolerance, the server performs the RPC as soon as
possible, whereas if Ts is a future time, the server performs the RPC possible, whereas if Ts is a future time, the server performs the RPC
at Ts. at Ts.
If Ts is not within the scheduling tolerance range, the scheduled RPC If Ts is not within the scheduling tolerance range, the scheduled RPC
is discarded, and the server responds with an error message [RPC6241] is discarded, and the server responds with an error message [RFC6241]
with a bad-element error-tag. An example is provided in Section 5.3. with a bad-element error-tag. An example is provided in Section 5.3.
3.6. Near Future Scheduling vs. Far Future Scheduling 3.6. Near Future Scheduling vs. Far Future Scheduling
The scheduling bound defined by sched-max-future guarantees that The scheduling bound defined by sched-max-future guarantees that
every scheduled RPCs is restricted to a near future scheduling time. every scheduled RPC is restricted to a near future scheduling time.
The scheduling mechanism defined in this document is intended for The scheduling mechanism defined in this document is intended for
near future scheduling, on the order of seconds. Far future near future scheduling, on the order of seconds. Far future
scheduling is outside the scope of this document. scheduling is outside the scope of this document.
The challenge in far future scheduling is that during the long period Example 1 is a typical example of using near future scheduling; the
between the time at which the RPC is sent and the time at which it is goal in the example is to perform the RPC at multiple servers at the
scheduled to be executed various external events may occur, e.g., the same time, and therefore it is best to schedule the RPC to be
client may fail or reboot, or the client access permissions may be performed a few seconds in the future.
changed. In these cases if the server performs the scheduled
operation it may perform an action that is inconsistent with the The Challenges of Far Future Scheduling
current network policy, or inconsistent with the currently active
clients. When an RPC is scheduled to be performed at a far-future time, during
the long period between the time at which the RPC is sent and the
time at which it is scheduled to be executed the following erroneous
events may occur:
o The server may restart.
o The client's authorization level may be changed.
o The client may restart and send a conflicting RPC.
o A different client may send a conflicting RPC.
In these cases if the server performs the scheduled operation it may
perform an action that is inconsistent with the current network
policy, or inconsistent with the currently active clients.
Near future scheduling guarantees that external events such as the Near future scheduling guarantees that external events such as the
examples above have a low probability of occurring during the sched- examples above have a low probability of occurring during the sched-
max-future period, and even when they do, the period of inconsistency max-future period, and even when they do, the period of inconsistency
is limited to sched-max-future, which is a short period of time. is limited to sched-max-future, which is a short period of time.
The Tradeoff in Setting the sched-max-future Value
The sched-max-future parameter should be configured to a value that
is high enough to allow the client to:
1. Send the scheduled RPC, potentially to multiple servers.
2. Receive notifications or rpc-error messages from the server(s), or
wait for a timeout and decide that if no response has arrived then
something is wrong.
3. If necessary, send a cancellation message, potentially to multiple
servers.
On the other hand, sched-max-future should be configured to a value
that is low enough to allow a low probability of the erroneous events
above, typically on the order of a few seconds. Note that even if
sched-max-future is configured to a low value, it is still possible
(with a low probability) that an erroneous event will occur. However,
this short potentially hazardous period is not significantly worse
than in conventional (unscheduled) RPCs, as even a conventional RPC
may in some cases be executed a few seconds after it was sent by the
client.
The Default Value of sched-max-future
The default value of sched-max-future is defined to be 15 seconds.
This duration is long enough to allow the scheduled RPC to be sent by
the client, potentially to multiple servers, and in some cases to
send a cancellation message, as described in Section 3.2. On the
other hand, the 15 second duration yields a very low probability of a
reboot or a permission change.
3.7. Time Interval Format 3.7. Time Interval Format
The time-interval format is used for representing the length of a The time-interval format is used for representing the length of a
time interval, and is based on the date-and-time format. It is used time interval, and is based on the date-and-time format. It is used
for representing the scheduling tolerance parameters, as described in for representing the scheduling tolerance parameters, as described in
the previous section. the previous section.
While the date-and-time type uniquely represents a specific point in While the date-and-time type uniquely represents a specific point in
time, the time-interval type defined below can be used to represent time, the time-interval type defined below can be used to represent
the length of a time interval without specifying a specific date. the length of a time interval without specifying a specific date.
The time-interval type is defined as follows: The time-interval type is defined as follows:
typedef time-interval { typedef time-interval {
type string { type string {
pattern '\d{2}:\d{2}:\d{2}(\.\d+)?'; pattern '\d{2}:\d{2}:\d{2}(\.\d+)?';
} }
description
"Defines a time interval, up to 24 hours.
The format is specified as HH:mm:ss.f,
consisting of two digits for hours,
two digits for minutes, two digits
for seconds, and zero or more digits
representing second fractions.";
} }
Example
The sched-max-future parameter is defined (Appendix A) as a
time-interval, as follows:
leaf sched-max-future {
type time-interval;
default 00:00:15.0;
}
The default value specified for sched-max-future is 0 hours, 0
minutes, and 15 seconds.
4. Time Capability 4. Time Capability
The structure of this section is as defined in Appendix D of The structure of this section is as defined in Appendix D of
[RFC6241]. [RFC6241].
4.1. Overview 4.1. Overview
A server that supports the time capability can perform time-triggered A server that supports the time capability can perform time-triggered
operations as defined in this document. operations as defined in this document.
A server implementing the :time capability: A server implementing the :time capability:
o MUST support the ability to receive <rpc> messages that include a o MUST support the ability to receive <rpc> messages that include a
time element, and perform a time-triggered operation accordingly. time element, and perform a time-triggered operation accordingly.
o MUST support the ability to include a time element in the <rpc- o MUST support the ability to include a time element in the <rpc-
reply> messages that it transmits. reply> messages that it transmits.
4.2. Dependencies 4.2. Dependencies
With-defaults Capability With-defaults Capability
The time capability YANG module (Appendix A.) uses default values, The time capability YANG module (Appendix A.) uses default values,
and thus it is assumed that the with-defaults capability [RFC6243] is and thus it is assumed that the with-defaults capability [RFC6243] is
supported. supported.
skipping to change at page 12, line 37 skipping to change at page 14, line 15
A cancel-schedule RPC MUST include the <cancelled-message-id> A cancel-schedule RPC MUST include the <cancelled-message-id>
element, which specifies the message ID of the scheduled RPC that element, which specifies the message ID of the scheduled RPC that
needs to be cancelled. needs to be cancelled.
A cancel-schedule RPC MAY include the <get-time> element. In this A cancel-schedule RPC MAY include the <get-time> element. In this
case the rpc-reply includes the <execution-time> element, specifying case the rpc-reply includes the <execution-time> element, specifying
the time at which the scheduled RPC was cancelled. the time at which the scheduled RPC was cancelled.
4.5. Modifications to Existing Operations 4.5. Modifications to Existing Operations
Three new elements are added to all existing operations: 4.5.1. Affected Operations
o <scheduled-time> The :time capability defined in this memo can be applied to any of
the following operations:
o get-config
o get
o copy-config
o edit-config
o delete-config
o lock
o unlock
o commit
Three new elements are added to each of these operations:
o <scheduled-time>
This element is added to the input of each operation, indicating This element is added to the input of each operation, indicating
the time at which the server is scheduled to invoke the operation. the time at which the server is scheduled to invoke the operation.
Every <rpc> message MAY include the <scheduled-time> element. A Every <rpc> message MAY include the <scheduled-time> element. A
server that supports the :time capability and receives an <rpc> server that supports the :time capability and receives an <rpc>
message with a <scheduled-time> element MUST perform the operation message with a <scheduled-time> element MUST perform the operation
as close as possible to the scheduled time. as close as possible to the scheduled time.
The <scheduled-time> element uses the date-and-time format The <scheduled-time> element uses the date-and-time format
(Section 3.4.). (Section 3.4.).
o <get-time> o <get-time>
This element is added to the input of each operation. An <rpc> This element is added to the input of each operation. An <rpc>
message MAY include a <get-time> element, indicating that the message MAY include a <get-time> element, indicating that the
server MUST include an <execution-time> in its corresponding <rpc- server MUST include an <execution-time> in its corresponding <rpc-
reply>. reply>.
o <execution-time> o <execution-time>
This element is added to the output of each operation, indicating This element is added to the output of each operation, indicating
the time at which the server completed the operation. An <rpc- the time at which the server completed the operation. An <rpc-
reply> MAY include the <execution-time> element. A server that reply> MAY include the <execution-time> element. A server that
supports the :time capability and receives an operation with the supports the :time capability and receives an operation with the
<get-time> element MUST include the execution time in its <get-time> element MUST include the execution time in its
response. response.
The execution-time element uses the date-and-time format The execution-time element uses the date-and-time format
(Section 3.4.). (Section 3.4.).
4.5.2. Processing Scheduled Operations
A server that receives a scheduled RPC MUST start executing the RPC
as close as possible to its scheduled execution time.
If a session between a client and a server is terminated, the server
MUST cancel all pending scheduled RPCs that were received in this
session.
Scheduled RPCs are processed serially, in an order that is defined by
their scheduled times. Thus, the server sends <rpc-reply> messages to
scheduled RPCs according to the order of their corresponding
schedules. Note that this is a modification to the behavior defined
in [RFC6241], which states that replies are sent in the order the
requests were received. Interoperability with [RFC6241] is guaranteed
by the NETCONF capability exchange; a server that does not support
the :time capability responds to RPCs in the order the requestes were
received. A server that supports the :time capability replies to
conventional (non-scheduled) RPCs in the order they were received,
and replies to scheduled RPCs in the order of their scheduled times.
If a server receives two or more RPCs that are scheduled to be
performed at the same time, the server executes the RPCs serially in
an arbitrary order.
4.6. Interactions with Other Capabilities 4.6. Interactions with Other Capabilities
Confirmed Commit Capability Confirmed Commit Capability
The confirmed commit capability is defined in Section 8.4 of The confirmed commit capability is defined in Section 8.4 of
[RFC6241]. According to [RFC6241], a confirmed <commit> operation [RFC6241]. According to [RFC6241], a confirmed <commit> operation
MUST be reverted if a confirming commit is not issued within the MUST be reverted if a confirming commit is not issued within the
timeout period (which by default is 600 seconds). timeout period (which by default is 600 seconds).
When the time capability is supported, and a confirmed <commit> When the time capability is supported, and a confirmed <commit>
operation is used with the <scheduled-time> element, the confirmation operation is used with the <scheduled-time> element, the confirmation
timeout MUST be counted from the scheduled time, i.e., the client timeout MUST be counted from the scheduled time, i.e., the client
begins the timeout measurement starting at the scheduled time. begins the timeout measurement starting at the scheduled time.
skipping to change at page 16, line 33 skipping to change at page 19, line 13
an attacker in gathering information about the system, such as the an attacker in gathering information about the system, such as the
exact time of future configuration changes. Moreover, the time exact time of future configuration changes. Moreover, the time
elements can potentially allow an attacker to learn information about elements can potentially allow an attacker to learn information about
the system's performance. Furthermore, an attacker that sends the system's performance. Furthermore, an attacker that sends
malicious RPC messages can use the time capability to amplify her malicious RPC messages can use the time capability to amplify her
attack; for example, by sending multiple RPC messages with the same attack; for example, by sending multiple RPC messages with the same
scheduled time. It is important to note that the security measures scheduled time. It is important to note that the security measures
described in [RFC6241] can prevent these vulnerabilities. described in [RFC6241] can prevent these vulnerabilities.
The time capability relies on an underlying time synchronization The time capability relies on an underlying time synchronization
protocol. Thus, an attack against the time protocol can potentially protocol. Thus, by attacking the time protocol an attack can
compromise NETCONF when using the time capability. A detailed potentially compromise NETCONF when using the time capability. A
discussion about the threats against time protocols and how to detailed discussion about the threats against time protocols and how
mitigate them is presented in [TimeSec]. to mitigate them is presented in [TimeSec].
The time capability can allow an attacker to attack a NETCONF server
by sending malicious RPCs that are scheduled to take place in the
future. For example, an attacker can send multiple scheduled RPCs
that are scheduled to be performed at the same time. Another possible
attack is to send a large number of scheduled RPCs to a NETCONF
server, potentially causing the server's buffers to overflow. These
attacks can be mitigated by a carefully designed NETCONF server; when
a server receives a scheduled RPC that exceeds its currently
available resources, it should reply with an rpc-error, and discard
the scheduled RPC.
Note that if an attacker has been detected and revoked, its future
scheduled RPCs are not executed; as defined in Section 4.5.2. , once
the session with the attacker has been terminated, the corresponding
scheduled RPCs are discarded.
6.2. YANG Module Security Considerations 6.2. YANG Module Security Considerations
This memo defines a new YANG module, as specified in Appendix A. This memo defines a new YANG module, as specified in Appendix A.
The YANG module defined in this memo is designed to be accessed via The YANG module defined in this memo is designed to be accessed via
the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the
secure transport layer and the mandatory to implement secure secure transport layer and the mandatory to implement secure
transport is SSH [RFC6242]. The NETCONF access control model transport is SSH [RFC6242]. The NETCONF access control model
[RFC6536] provides the means to restrict access for particular [RFC6536] provides the means to restrict access for particular
NETCONF users to a pre-configured subset of all available NETCONF NETCONF users to a pre-configured subset of all available NETCONF
protocol operations and content. protocol operations and content.
This YANG module defines <sched-max-future> and <sched-max-past>, This YANG module defines <sched-max-future> and <sched-max-past>,
which are writable/creatable/deletable. These data nodes may be which are writable/creatable/deletable. These data nodes may be
considered sensitive or vulnerable in some network environments. For considered sensitive or vulnerable in some network environments. An
instance, an attacker may attempt to maliciously configure these attacker may attempt to maliciously configure these parameters to a
parameters to a small value, thereby causing all scheduled RPCs to be low value, thereby causing all scheduled RPCs to be discarded. For
discarded. instance, if a client expects <sched-max-future> to be 15 seconds,
but in practice it is maliciously configured to 1 second, then a
legitimate scheduled RPC that is scheduled to be performed 5 seconds
in the future will be discarded by the server.
This YANG module defines the <cancel-schedule> RPC. This RPC may be This YANG module defines the <cancel-schedule> RPC. This RPC may be
considered sensitive or vulnerable in some network environments; it considered sensitive or vulnerable in some network environments.
may be used maliciously to attack servers by canceling their pending Since the value of the <schedule-id> is known to all the clients that
RPCs. It is thus important to control access to this operations; the are subscribed to notifications from the server, the <cancel-
authorisation level required to cancel an RPC should be the same as schedule> RPC may be used maliciously to attack servers by canceling
the level required to schedule it. their pending RPCs. This attack is addressed in two layers: (i)
security at the transport layer, limiting the attack only to clients
that have successfully initiated a secure session with the server,
and (ii) the authorization level required to cancel an RPC should be
the same as the level required to schedule it, limiting the attack
only to attackers with an authorization level that is equal to or
higher than that of the client that initiated the scheduled RPC.
7. IANA Considerations 7. IANA Considerations
This document proposes to register the following capability This document proposes to register the following capability
identifier URN in the 'Network Configuration Protocol (NETCONF) identifier URN in the 'Network Configuration Protocol (NETCONF)
Capability URNs' registry: Capability URNs' registry:
urn:ietf:params:netconf:capability:time:1.0 urn:ietf:params:netconf:capability:time:1.0
This document proposes to register the following XML namespace URN This document proposes to register the following XML namespace URN
skipping to change at page 17, line 47 skipping to change at page 20, line 50
prefix: nct prefix: nct
namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-time namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-time
RFC: TBD RFC: TBD
8. Acknowledgments 8. Acknowledgments
The authors gratefully acknowledge Joe Marcus Clarke, Andy Bierman, The authors gratefully acknowledge Joe Marcus Clarke, Andy Bierman,
Balazs Lengyel, Jonathan Hansford, John Heasley, Alon Schneider and Balazs Lengyel, Jonathan Hansford, John Heasley, Robert Sparks, Al
Eylon Egozi for their insightful comments. Morton, Olafur Gudmundsson, Juergen Schoenwaelder, Joel Jaeggli,
Alon Schneider and Eylon Egozi for their insightful comments.
This work was supported in part by Israel Science Foundation grant This work was supported in part by Israel Science Foundation grant
ISF 1520/11. ISF 1520/11.
This document was prepared using 2-Word-v2.0.template.dot. This document was prepared using 2-Word-v2.0.template.dot.
9. References 9. References
9.1. Normative References 9.1. Normative References
[RFC2199] 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, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002. Internet: Timestamps", RFC 3339, July 2002.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC
3688, January 2004. 3688, January 2004.
[RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991,
October 2010. July 2013.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J.,
Ed., Bierman, A., Ed., "Network Configuration Protocol Ed., Bierman, A., Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, June 2011. (NETCONF)", RFC 6241, June 2011.
[RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF)
Base Notifications", RFC 6470, February 2012. Base Notifications", RFC 6470, February 2012.
9.2. Informative References 9.2. Informative References
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC
6020, October 2010.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, June 2011. Shell (SSH)", RFC 6242, June 2011.
[RFC6243] Bierman, A., Lengyel, B., "With-defaults Capability [RFC6243] Bierman, A., Lengyel, B., "With-defaults Capability
for NETCONF", RFC 6243, June 2011. for NETCONF", RFC 6243, June 2011.
[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,
March 2012. March 2012.
[RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for
System Management", RFC 7317, August 2014.
[Cond] Watsen, K., "Conditional Enablement of Configuration
Nodes", draft-kwatsen-conditional-enablement-00
(expired), 2013.
[HotSDN] Mizrahi, T., Moses, Y., "Time-based Updates in [HotSDN] Mizrahi, T., Moses, Y., "Time-based Updates in
Software Defined Networks", the second workshop on hot Software Defined Networks", the second workshop on hot
topics in software defined networks (HotSDN), 2013. topics in software defined networks (HotSDN), 2013.
[IEEE1588] IEEE TC 9 Instrumentation and Measurement Society, [IEEE1588] IEEE TC 9 Instrumentation and Measurement Society,
"1588 IEEE Standard for a Precision Clock "1588 IEEE Standard for a Precision Clock
Synchronization Protocol for Networked Measurement and Synchronization Protocol for Networked Measurement and
Control Systems Version 2", IEEE Standard, 2008. Control Systems Version 2", IEEE Standard, 2008.
[NTP] Mills, D., Martin, J., Burbank, J., Kasch, W., [NTP] Mills, D., Martin, J., Burbank, J., Kasch, W.,
"Network Time Protocol Version 4: Protocol and "Network Time Protocol Version 4: Protocol and
Algorithms Specification", RFC 5905, June 2010. Algorithms Specification", RFC 5905, June 2010.
[RFC5907] Gerstung, H., Elliott, C., Haberman, B., "Definitions [RFC5907] Gerstung, H., Elliott, C., Haberman, B., "Definitions
of Managed Objects for Network Time Protocol Version 4 of Managed Objects for Network Time Protocol Version 4
(NTPv4", RFC 5907, June 2010. (NTPv4", RFC 5907, June 2010.
[TimeSec] Mizrahi, T., "Security Requirements of Time Protocols [TimeSec] Mizrahi, T., "Security Requirements of Time Protocols
in Packet Switched Networks", RFC 7384, October 2014. in Packet Switched Networks", RFC 7384, October 2014.
skipping to change at page 19, line 27 skipping to change at page 22, line 43
OpenFlow: A Proposed Extension to the OpenFlow OpenFlow: A Proposed Extension to the OpenFlow
Protocol", Technion - Israel Institute of Technology, Protocol", Technion - Israel Institute of Technology,
technical report, CCIT Report #835, EE Pub No. 1792, technical report, CCIT Report #835, EE Pub No. 1792,
2013. 2013.
http://tx.technion.ac.il/~dew/OFTimeTR.pdf http://tx.technion.ac.il/~dew/OFTimeTR.pdf
Appendix A. YANG Module for the Time Capability Appendix A. YANG Module for the Time Capability
This section is normative. This section is normative.
<CODE BEGINS> file "ietf-netconf-time@2015-05-07.yang" <CODE BEGINS> file "ietf-netconf-time@2015-09-01.yang"
module ietf-netconf-time { module ietf-netconf-time {
namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-time"; namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-time";
prefix nct; prefix nct;
import ietf-netconf { prefix nc; } import ietf-netconf { prefix nc; }
import ietf-yang-types { prefix yang; } import ietf-yang-types { prefix yang; }
import ietf-netconf-monitoring { prefix ncm; } import ietf-netconf-monitoring { prefix ncm; }
organization organization
"IETF"; "IETF";
contact contact
skipping to change at page 20, line 24 skipping to change at page 23, line 38
Copyright (c) 2015 IETF Trust and the persons identified as Copyright (c) 2015 IETF Trust and the persons identified as
the document authors. All rights reserved. the document authors. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info)."; (http://trustee.ietf.org/license-info).";
revision 2015-05-07 { revision 2015-09-01 {
description description
"Initial version."; "Initial version.";
reference reference
"draft-mm-netconf-time-capability: "draft-mm-netconf-time-capability:
Time Capability in NETCONF"; Time Capability in NETCONF";
} }
typedef time-interval { typedef time-interval {
type string { type string {
pattern '\d{2}:\d{2}:\d{2}(\.\d+)?'; pattern '\d{2}:\d{2}:\d{2}(\.\d+)?';
} }
description description
"Defines a time interval, up to 24 hours."; "Defines a time interval, up to 24 hours.
The format is specified as HH:mm:ss.f,
consisting of two digits for hours,
two digits for minutes, two digits
for seconds, and zero or more digits
representing second fractions.";
} }
grouping scheduling-tolerance-parameters { grouping scheduling-tolerance-parameters {
leaf sched-max-future { leaf sched-max-future {
type time-interval; type time-interval;
default 00:00:15.0; default 00:00:15.0;
description description
"When the scheduled time is in the future, i.e., greater "When the scheduled time is in the future, i.e., greater
than the present time, this leaf defines the maximal than the present time, this leaf defines the maximal
difference between the scheduled time difference between the scheduled time
skipping to change at page 26, line 25 skipping to change at page 30, line 4
augment /nc:unlock/nc:output { augment /nc:unlock/nc:output {
leaf execution-time { leaf execution-time {
type yang:date-and-time; type yang:date-and-time;
description description
"The time at which the RPC was executed."; "The time at which the RPC was executed.";
} }
description description
"Adds the time element to <unlock>."; "Adds the time element to <unlock>.";
} }
augment /nc:close-session/nc:input {
leaf scheduled-time {
type yang:date-and-time;
description
"The time at which the RPC is scheduled to be performed.";
}
leaf get-time {
type empty;
description
"Indicates that the rpc-reply should include the
execution-time.";
}
description
"Adds the time element to <close-session>.";
}
augment /nc:close-session/nc:output {
leaf execution-time {
type yang:date-and-time;
description
"The time at which the RPC was executed.";
}
description
"Adds the time element to <close-session>.";
}
augment /nc:kill-session/nc:input {
leaf scheduled-time {
type yang:date-and-time;
description
"The time at which the RPC is scheduled to be performed.";
}
leaf get-time {
type empty;
description
"Indicates that the rpc-reply should include the
execution-time.";
}
description
"Adds the time element to <kill-session>.";
}
augment /nc:kill-session/nc:output {
leaf execution-time {
type yang:date-and-time;
description
"The time at which the RPC was executed.";
}
description
"Adds the time element to <kill-session>.";
}
augment /nc:commit/nc:input { augment /nc:commit/nc:input {
leaf scheduled-time { leaf scheduled-time {
type yang:date-and-time; type yang:date-and-time;
description description
"The time at which the RPC is scheduled to be performed."; "The time at which the RPC is scheduled to be performed.";
} }
leaf get-time { leaf get-time {
type empty; type empty;
description description
 End of changes. 53 change blocks. 
171 lines changed or deleted 308 lines changed or added

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