idnits 2.17.1 draft-mm-netconf-time-capability-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 400 has weird spacing: '...ax-past sched...' -- The document date (October 15, 2015) is 3108 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group T. Mizrahi 2 Internet Draft Y. Moses 3 Intended status: Experimental Technion, Israel Institute of Technology 4 Expires: April 2016 October 15, 2015 6 Time Capability in NETCONF 7 draft-mm-netconf-time-capability-09.txt 9 Abstract 11 This document defines a capability-based extension to the Network 12 Configuration Protocol (NETCONF) that allows time-triggered 13 configuration and management operations. This extension allows 14 NETCONF clients to invoke configuration updates according to 15 scheduled times, and allows NETCONF servers to attach timestamps to 16 the data they send to NETCONF clients. 18 Status of this Memo 20 This Internet-Draft is submitted to IETF in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF), its areas, and its working groups. Note that 25 other groups may also distribute working documents as Internet- 26 Drafts. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 The list of current Internet-Drafts can be accessed at 34 http://www.ietf.org/ietf/1id-abstracts.txt. 36 The list of Internet-Draft Shadow Directories can be accessed at 37 http://www.ietf.org/shadow.html. 39 This Internet-Draft will expire on April 15, 2016. 41 Copyright Notice 43 Copyright (c) 2015 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction...................................................3 59 2. Conventions used in this document..............................3 60 2.1. Key words.................................................3 61 2.2. Abbreviations.............................................4 62 2.3. Terminology...............................................4 63 3. Using Time in NETCONF..........................................4 64 3.1. The Time Capability in a Nutshell.........................4 65 3.2. Notifications and Cancellation Messages...................6 66 3.3. Synchronization Aspects...................................8 67 3.4. Scheduled Time Format.....................................9 68 3.5. Scheduling Tolerance......................................9 69 3.6. Near Future Scheduling vs. Far Future Scheduling.........10 70 3.7. Time Interval Format.....................................12 71 4. Time Capability...............................................13 72 4.1. Overview.................................................13 73 4.2. Dependencies.............................................13 74 4.3. Capability Identifier....................................13 75 4.4. New Operations...........................................13 76 4.5. Modifications to Existing Operations.....................14 77 4.5.1. Affected Operations.................................14 78 4.5.2. Processing Scheduled Operations.....................15 79 4.6. Interactions with Other Capabilities.....................15 80 5. sched-max-futures.............................................16 81 5.1. Example.................................16 82 5.2. Example.......................................17 83 5.3. Error Example............................................17 84 6. Security Considerations.......................................18 85 6.1. General Security Considerations..........................18 86 6.2. YANG Module Security Considerations......................19 87 7. IANA Considerations...........................................20 88 8. Acknowledgments...............................................20 89 9. References....................................................21 90 9.1. Normative References.....................................21 91 9.2. Informative References...................................21 92 Appendix A. YANG Module for the Time Capability..................22 94 1. Introduction 96 The Network Configuration Protocol (NETCONF) defined in [RFC6241] 97 provides mechanisms to install, manipulate, and delete the 98 configuration of network devices. NETCONF allows clients to configure 99 and monitor NETCONF servers using remote procedure calls (RPC). 101 NETCONF, as defined in [RFC6241], is asynchronous; when a client 102 invokes an RPC, it has no control over the time at which the RPC is 103 executed, nor does it have any feedback from the server about the 104 execution time. 106 Time-based configuration ([HotSDN], [TimeTR]) can be a useful tool 107 that enables an entire class of coordinated and scheduled 108 configuration procedures. Time-triggered configuration allows 109 coordinated network updates in multiple devices; a client can invoke 110 a coordinated configuration change by sending RPCs to multiple 111 servers with the same scheduled execution time. A client can also 112 invoke a time-based sequence of updates by sending n RPCs with n 113 different update times, T1, T2, ..., Tn, determining the order in 114 which the RPCs are executed. 116 This memo defines the :time capability in NETCONF. This extension 117 allows clients to determine the scheduled execution time of RPCs they 118 send. It also allows a server that receives an RPC to report its 119 actual execution time to the client. 121 The NETCONF time capability is intended for scheduling RPCs that 122 should be performed in the near future, allowing to coordinate 123 simultaneous configuration changes, or to specify an order of 124 configuration updates. Time-of-day-based policies and far-future 125 scheduling, e.g., [Cond], are outside the scope of this memo. 127 This memo is defined for experimental purposes, and will allow the 128 community to experiment with the NETCONF time capability. It is 129 expected that based on the lessons learned from this experience the 130 NETCONF working group will be able to consider whether to adopt the 131 time capability. 133 2. Conventions used in this document 135 2.1. Key words 137 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 138 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 139 document are to be interpreted as described in [RFC2119]. 141 2.2. Abbreviations 143 NETCONF Network Configuration Protocol 145 RPC Remote Procedure Call 147 2.3. Terminology 149 o Capability [RFC6241]: A functionality that supplements the base 150 NETCONF specification. 152 o Client [RFC6241]: Invokes protocol operations on a server. In 153 addition, a client can subscribe to receive notifications from a 154 server. 156 o Execution time: The execution time of an RPC is defined as the 157 time at which a server completes the execution of an RPC. 159 o Scheduled RPC: an RPC that is scheduled to be performed at a 160 predetermined time, which is included in the message. 162 o Scheduled time: The scheduled time of an RPC is the time at which 163 the RPC should be invoked. The scheduled time is determined by the 164 client, and enforced by the server. 166 o Server [RFC6241]: Executes protocol operations invoked by a 167 client. In addition, a server can send notifications to a client. 169 3. Using Time in NETCONF 171 3.1. The Time Capability in a Nutshell 173 The :time capability provides two main functions: 175 o Scheduling: 176 When a client sends an RPC to a server, the RPC message MAY 177 include the scheduled-time element, denoted by Ts in Figure 1. The 178 server then executes the RPC at the scheduled time Ts, and once 179 completed the server can respond with an RPC reply message. 181 o Reporting: 182 When a client sends an RPC to a server, the RPC message MAY 183 include a get-time element (see Figure 2), requesting the server 184 to return the execution time of the RPC. In this case, after the 185 server performs the RPC it responds with an RPC reply that 186 includes the execution time, Te. 188 RPC _________ 189 executed \ 190 \/ 191 Ts 192 server ---------------+------------- ----> time 193 /\ \ 194 rpc / \ rpc-reply 195 (Ts)/ \ 196 / \/ 197 client ----------------------------- 199 Figure 1 Scheduled RPC 201 RPC _________ 202 executed \ 203 \/ 204 Te 205 server ------------+---------------- ----> time 206 /\ \ 207 rpc / \ rpc-reply 208 (get-time)/ \ (Te) 209 / \/ 210 client ----------------------------- 212 Figure 2 Reporting the Execution Time of an RPC 214 Example 1. A client needs to trigger a commit at n servers, so that 215 the n servers perform the commit as close as possible to 216 simultaneously. Without the time capability, the client sends a 217 sequence of n commit messages, and thus each server performs the 218 commit at a different time. By using the time capability, the client 219 can send commit messages that are scheduled to take place at a chosen 220 time Ts, for example 5 seconds in the future, causing the servers to 221 invoke the commit as close as possible to time Ts. 223 Example 2. In many applications it is desirable to monitor events or 224 collect statistics regarding a common time reference. A client can 225 send a set of get-config messages that is scheduled to be executed at 226 multiple servers at the same time, providing a simultaneous system- 227 wide view of the state of the servers. Moreover, a client can use the 228 get-time element in its get-config messages, providing a time 229 reference to the sampled element. 231 The scenarios of Figure 1 and Figure 2 imply that a third scenario 232 can also be supported (Figure 3), where the client invokes an RPC 233 that includes a scheduled time, Ts, as well as the get-time element. 234 This allows the client to receive feedback about the actual execution 235 time, Te. Ideally, Ts=Te. However, the server may execute the RPC at 236 a slightly different time than Ts, for example if the server is tied 237 up with other tasks at Ts. 239 RPC _________ 240 executed \ 241 \/ 242 Ts Te 243 server -------------+-+------------- ----> time 244 /\ \ 245 rpc / \ rpc-reply 246 (Ts + get-time)/ \ (Te) 247 / \/ 248 client ----------------------------- 250 Figure 3 Scheduling and Reporting 252 3.2. Notifications and Cancellation Messages 254 Notifications 256 As illustrated in Figure 1, after a scheduled RPC is executed the 257 server sends an rpc-reply. The rpc-reply may arrive a long period of 258 time after the RPC was sent by the client, leaving the client without 259 a clear indication of whether the RPC was received. 261 This document defines a new notification, the netconf-scheduled- 262 message notification, which provides an immediate acknowledgement of 263 the scheduled RPC. 265 The is sent to the client if it is 266 subscribed to the NETCONF notifications [RFC6470]; as illustrated in 267 Figure 4, when the server receives a scheduled RPC it sends a 268 notification to the client. 270 The notification includes a 271 element. The is a unique identifier that the server 272 assigns to every scheduled RPC it receives. Thus, a client can keep 273 track of all the pending scheduled RPCs; a client can uniquely 274 identify a scheduled RPC by the tuple {server, schedule-id}. 276 RPC ____________ 277 executed \ 278 \/ 279 Ts 280 server -------------------+--------- ----> time 281 /\ \ \ 282 rpc / \notifi- \ rpc-reply 283 (Ts)/ \cation \ 284 / \/ \/ 285 client ----------------------------- 287 Figure 4 Scheduled RPC with Notification 289 Cancellation Messages 291 A client can cancel a scheduled RPC by sending a 292 RPC. The RPC includes the of the 293 scheduled RPC that needs to be cancelled. 295 The RPC, defined in this document, can be used to 296 perform a coordinated all-or-none procedure, where either all the 297 servers perform the operation on schedule, or the operation is 298 aborted. 300 Example 3. A client sends scheduled RPC messages to server 1 and 301 server 2, both scheduled to be performed at time Ts. Server 1 sends a 302 notification indicating that it has successfully scheduled the RPC, 303 while server 2 replies with an unknown-element error [RFC6241] that 304 indicates that it does not support the time capability. The client 305 sends a RPC to server 1, and receives an rpc-reply. 306 The message exchange between the client and server 1 in this example 307 is illustrated in Figure 5. 309 RPC not __________ 310 executed \ 311 \/ 312 Ts 313 server --------------------------------+--- ----> time 314 /\ \ /\ \ 315 rpc / \notifi- /cancel- \ rpc-reply 316 (Ts)/ \cation /schedule \ 317 / \/ / \/ 318 client ------------------------------------ 320 Figure 5 Cancellation Message 322 A cancel-schedule message MUST NOT include the scheduled-time 323 parameter. A server that receives a cancel-schedule should try to 324 cancel the schedule as soon as possible. If the server is unable to 325 cancel the scheduled RPC, for example because it has already been 326 executed, it should respond with an rpc-error [RFC6241], in which the 327 error-type is 'protocol', and the error-tag is 'operation-failed'. 329 3.3. Synchronization Aspects 331 The time capability defined in this document requires clients and 332 servers to maintain clocks. It is assumed that clocks are 333 synchronized by a method that is outside the scope of this document, 334 e.g., [NTP] or [IEEE1588]. 336 This document does not define any requirements pertaining to the 337 degree of accuracy of performing scheduled RPCs. Note that two 338 factors affect how accurately the server can perform a scheduled RPC; 339 one factor is the accuracy of the clock synchronization method used 340 to synchronize the clients and servers, and the second factor is the 341 server's ability to execute real-time configuration changes, which 342 greatly depends on how it is implemented. Typical networking devices 343 are implemented by a combination of hardware and software. While the 344 execution time of a hardware module can typically be predicted with a 345 high level of accuracy, the execution time of a software module may 346 be variable and hard to predict. A configuration update would 347 typically require the server's software to be involved, thus 348 affecting how accurately the RPC can be scheduled. 350 Another important aspect of synchronization, is monitoring; a client 351 should be able to check whether a server is synchronized to a 352 reference time source. Typical synchronization protocols, such as the 353 Network Time Protocol [NTP] provide the means ([RFC5907], [RFC7317]) 354 to verify that a clock is synchronized to a time reference by 355 querying its Management Information Base (MIB). The get-time feature 356 defined in this document (see Figure 2) allows a client to obtain a 357 rough estimate of the time offset between the client's clock and the 358 server's clock. 360 Since servers do not perform configuration changes instantaneously, 361 the processing time of an RPC should not be overlooked. The scheduled 362 time always refers to the start time of the RPC, and the execution 363 time always refers to its completion time. 365 3.4. Scheduled Time Format 367 The scheduled time and execution time fields in RPC messages use a 368 common time format field. 370 The time format used in this document is the date-and-time format, 371 that is defined in Section 5.6 of [RFC3339] and in Section 3 of 372 [RFC6991]. 374 leaf scheduled-time { 375 type yang:date-and-time; 376 description 377 "The time at which the RPC is scheduled to be performed."; 378 } 380 leaf execution-time { 381 type yang:date-and-time; 382 description 383 "The time at which the RPC was executed."; 384 } 386 3.5. Scheduling Tolerance 388 When a client sends an RPC that is scheduled to Ts, the server MUST 389 verify that the value Ts is not too far in the past or in the future. 390 As illustrated in Figure 6, the server verifies that Ts is within the 391 scheduling tolerance range. 393 RPC _________ 394 received \ 395 \/ 396 Ts 397 -----+--------------+-----+------------+-------> time 399 <------------> <----------------> 400 sched-max-past sched-max-future 402 <-------------------------------> 403 scheduling tolerance 405 Figure 6 Scheduling Tolerance 407 The scheduling tolerance is determined by two parameters, 408 sched-max-future and sched-max-past. These two parameters use the 409 time-interval format (Section 3.7.), and their default value is 15 410 seconds. 412 If the scheduled time, Ts is within the scheduling tolerance range, 413 the scheduled RPC is performed; if Ts occurs in the past and within 414 the scheduling tolerance, the server performs the RPC as soon as 415 possible, whereas if Ts is a future time, the server performs the RPC 416 at Ts. 418 If Ts is not within the scheduling tolerance range, the scheduled RPC 419 is discarded, and the server responds with an error message [RFC6241] 420 with a bad-element error-tag. An example is provided in Section 5.3. 422 3.6. Near Future Scheduling vs. Far Future Scheduling 424 The scheduling bound defined by sched-max-future guarantees that 425 every scheduled RPC is restricted to a near future scheduling time. 427 The scheduling mechanism defined in this document is intended for 428 near future scheduling, on the order of seconds. Far future 429 scheduling is outside the scope of this document. 431 Example 1 is a typical example of using near future scheduling; the 432 goal in the example is to perform the RPC at multiple servers at the 433 same time, and therefore it is best to schedule the RPC to be 434 performed a few seconds in the future. 436 The Challenges of Far Future Scheduling 438 When an RPC is scheduled to be performed at a far-future time, during 439 the long period between the time at which the RPC is sent and the 440 time at which it is scheduled to be executed the following erroneous 441 events may occur: 443 o The server may restart. 445 o The client's authorization level may be changed. 447 o The client may restart and send a conflicting RPC. 449 o A different client may send a conflicting RPC. 451 In these cases if the server performs the scheduled operation it may 452 perform an action that is inconsistent with the current network 453 policy, or inconsistent with the currently active clients. 455 Near future scheduling guarantees that external events such as the 456 examples above have a low probability of occurring during the sched- 457 max-future period, and even when they do, the period of inconsistency 458 is limited to sched-max-future, which is a short period of time. 460 The Tradeoff in Setting the sched-max-future Value 462 The sched-max-future parameter should be configured to a value that 463 is high enough to allow the client to: 465 1. Send the scheduled RPC, potentially to multiple servers. 467 2. Receive notifications or rpc-error messages from the server(s), or 468 wait for a timeout and decide that if no response has arrived then 469 something is wrong. 471 3. If necessary, send a cancellation message, potentially to multiple 472 servers. 474 On the other hand, sched-max-future should be configured to a value 475 that is low enough to allow a low probability of the erroneous events 476 above, typically on the order of a few seconds. Note that even if 477 sched-max-future is configured to a low value, it is still possible 478 (with a low probability) that an erroneous event will occur. However, 479 this short potentially hazardous period is not significantly worse 480 than in conventional (unscheduled) RPCs, as even a conventional RPC 481 may in some cases be executed a few seconds after it was sent by the 482 client. 484 The Default Value of sched-max-future 486 The default value of sched-max-future is defined to be 15 seconds. 487 This duration is long enough to allow the scheduled RPC to be sent by 488 the client, potentially to multiple servers, and in some cases to 489 send a cancellation message, as described in Section 3.2. On the 490 other hand, the 15 second duration yields a very low probability of a 491 reboot or a permission change. 493 3.7. Time Interval Format 495 The time-interval format is used for representing the length of a 496 time interval, and is based on the date-and-time format. It is used 497 for representing the scheduling tolerance parameters, as described in 498 the previous section. 500 While the date-and-time type uniquely represents a specific point in 501 time, the time-interval type defined below can be used to represent 502 the length of a time interval without specifying a specific date. 504 The time-interval type is defined as follows: 506 typedef time-interval { 507 type string { 508 pattern '\d{2}:\d{2}:\d{2}(\.\d+)?'; 509 } 510 description 511 "Defines a time interval, up to 24 hours. 512 The format is specified as HH:mm:ss.f, 513 consisting of two digits for hours, 514 two digits for minutes, two digits 515 for seconds, and zero or more digits 516 representing second fractions."; 517 } 519 Example 521 The sched-max-future parameter is defined (Appendix A) as a 522 time-interval, as follows: 524 leaf sched-max-future { 525 type time-interval; 526 default 00:00:15.0; 527 } 529 The default value specified for sched-max-future is 0 hours, 0 530 minutes, and 15 seconds. 532 4. Time Capability 534 The structure of this section is as defined in Appendix D of 535 [RFC6241]. 537 4.1. Overview 539 A server that supports the time capability can perform time-triggered 540 operations as defined in this document. 542 A server implementing the :time capability: 544 o MUST support the ability to receive messages that include a 545 time element, and perform a time-triggered operation accordingly. 547 o MUST support the ability to include a time element in the messages that it transmits. 550 4.2. Dependencies 552 With-defaults Capability 554 The time capability YANG module (Appendix A.) uses default values, 555 and thus it is assumed that the with-defaults capability [RFC6243] is 556 supported. 558 4.3. Capability Identifier 560 The :time capability is identified by the following capability string 561 (to be assigned by IANA - see Section 0): 563 urn:ietf:params:netconf:capability:time:1.0 565 4.4. New Operations 567 569 The cancel-schedule RPC is used for cancelling an RPC that was 570 previously scheduled. 572 A cancel-schedule RPC MUST include the 573 element, which specifies the message ID of the scheduled RPC that 574 needs to be cancelled. 576 A cancel-schedule RPC MAY include the element. In this 577 case the rpc-reply includes the element, specifying 578 the time at which the scheduled RPC was cancelled. 580 4.5. Modifications to Existing Operations 582 4.5.1. Affected Operations 584 The :time capability defined in this memo can be applied to any of 585 the following operations: 587 o get-config 589 o get 591 o copy-config 593 o edit-config 595 o delete-config 597 o lock 599 o unlock 601 o commit 603 Three new elements are added to each of these operations: 605 o 606 This element is added to the input of each operation, indicating 607 the time at which the server is scheduled to invoke the operation. 608 Every message MAY include the element. A 609 server that supports the :time capability and receives an 610 message with a element MUST perform the operation 611 as close as possible to the scheduled time. 613 The element uses the date-and-time format 614 (Section 3.4.). 616 o 617 This element is added to the input of each operation. An 618 message MAY include a element, indicating that the 619 server MUST include an in its corresponding . 622 o 623 This element is added to the output of each operation, indicating 624 the time at which the server completed the operation. An MAY include the element. A server that 626 supports the :time capability and receives an operation with the 627 element MUST include the execution time in its 628 response. 630 The execution-time element uses the date-and-time format 631 (Section 3.4.). 633 4.5.2. Processing Scheduled Operations 635 A server that receives a scheduled RPC MUST start executing the RPC 636 as close as possible to its scheduled execution time. 638 If a session between a client and a server is terminated, the server 639 MUST cancel all pending scheduled RPCs that were received in this 640 session. 642 Scheduled RPCs are processed serially, in an order that is defined by 643 their scheduled times. Thus, the server sends messages to 644 scheduled RPCs according to the order of their corresponding 645 schedules. Note that this is a modification to the behavior defined 646 in [RFC6241], which states that replies are sent in the order the 647 requests were received. Interoperability with [RFC6241] is guaranteed 648 by the NETCONF capability exchange; a server that does not support 649 the :time capability responds to RPCs in the order the requestes were 650 received. A server that supports the :time capability replies to 651 conventional (non-scheduled) RPCs in the order they were received, 652 and replies to scheduled RPCs in the order of their scheduled times. 654 If a server receives two or more RPCs that are scheduled to be 655 performed at the same time, the server executes the RPCs serially in 656 an arbitrary order. 658 4.6. Interactions with Other Capabilities 660 Confirmed Commit Capability 661 The confirmed commit capability is defined in Section 8.4 of 662 [RFC6241]. According to [RFC6241], a confirmed operation 663 MUST be reverted if a confirming commit is not issued within the 664 timeout period (which by default is 600 seconds). 666 When the time capability is supported, and a confirmed 667 operation is used with the element, the confirmation 668 timeout MUST be counted from the scheduled time, i.e., the client 669 begins the timeout measurement starting at the scheduled time. 671 5. Examples 673 5.1. Example 675 The following example extends the example presented in Section 7.2 of 676 [RFC6241] by adding the time capability. In this example, the 677 element is used to specify the scheduled execution 678 time of the configuration update (as shown in Figure 1). 680 682 683 684 685 686 688 2015-10-21T04:29:00.235Z 689 690 691 692 693 Ethernet0/0 694 1500 695 696 697 698 699 701 703 705 707 5.2. Example 709 The following example is similar to the one presented in Section 5.1. 710 , except that in this example the client includes a 711 element in its RPC, and the server consequently responds with an 712 element (as shown in Figure 2). 714 716 717 718 719 720 722 723 724 725 726 Ethernet0/0 727 1500 728 729 730 731 732 734 736 737 738 2015-10-21T04:29:00.235Z 739 740 742 5.3. Error Example 744 The following example presents a scenario in which the scheduled-time 745 is not within the scheduling tolerance, i.e., it is too far in the 746 past, and therefore an rpc-error is returned. 748 750 751 752 753 754 756 2010-10-21T04:29:00.235Z 757 758 759 760 761 Ethernet0/0 762 1500 763 764 765 766 767 769 771 772 application 773 bad-element 774 error 775 776 scheduled-time 777 778 779 781 6. Security Considerations 783 6.1. General Security Considerations 785 The security considerations of the NETCONF protocol in general are 786 discussed in [RFC6241]. 788 The usage of the time capability defined in this document can assist 789 an attacker in gathering information about the system, such as the 790 exact time of future configuration changes. Moreover, the time 791 elements can potentially allow an attacker to learn information about 792 the system's performance. Furthermore, an attacker that sends 793 malicious RPC messages can use the time capability to amplify her 794 attack; for example, by sending multiple RPC messages with the same 795 scheduled time. It is important to note that the security measures 796 described in [RFC6241] can prevent these vulnerabilities. 798 The time capability relies on an underlying time synchronization 799 protocol. Thus, by attacking the time protocol an attack can 800 potentially compromise NETCONF when using the time capability. A 801 detailed discussion about the threats against time protocols and how 802 to mitigate them is presented in [TimeSec]. 804 The time capability can allow an attacker to attack a NETCONF server 805 by sending malicious RPCs that are scheduled to take place in the 806 future. For example, an attacker can send multiple scheduled RPCs 807 that are scheduled to be performed at the same time. Another possible 808 attack is to send a large number of scheduled RPCs to a NETCONF 809 server, potentially causing the server's buffers to overflow. These 810 attacks can be mitigated by a carefully designed NETCONF server; when 811 a server receives a scheduled RPC that exceeds its currently 812 available resources, it should reply with an rpc-error, and discard 813 the scheduled RPC. 815 Note that if an attacker has been detected and revoked, its future 816 scheduled RPCs are not executed; as defined in Section 4.5.2. , once 817 the session with the attacker has been terminated, the corresponding 818 scheduled RPCs are discarded. 820 6.2. YANG Module Security Considerations 822 This memo defines a new YANG module, as specified in Appendix A. 824 The YANG module defined in this memo is designed to be accessed via 825 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 826 secure transport layer and the mandatory to implement secure 827 transport is SSH [RFC6242]. The NETCONF access control model 828 [RFC6536] provides the means to restrict access for particular 829 NETCONF users to a pre-configured subset of all available NETCONF 830 protocol operations and content. 832 This YANG module defines and , 833 which are writable/creatable/deletable. These data nodes may be 834 considered sensitive or vulnerable in some network environments. An 835 attacker may attempt to maliciously configure these parameters to a 836 low value, thereby causing all scheduled RPCs to be discarded. For 837 instance, if a client expects to be 15 seconds, 838 but in practice it is maliciously configured to 1 second, then a 839 legitimate scheduled RPC that is scheduled to be performed 5 seconds 840 in the future will be discarded by the server. 842 This YANG module defines the RPC. This RPC may be 843 considered sensitive or vulnerable in some network environments. 844 Since the value of the is known to all the clients that 845 are subscribed to notifications from the server, the RPC may be used maliciously to attack servers by canceling 847 their pending RPCs. This attack is addressed in two layers: (i) 848 security at the transport layer, limiting the attack only to clients 849 that have successfully initiated a secure session with the server, 850 and (ii) the authorization level required to cancel an RPC should be 851 the same as the level required to schedule it, limiting the attack 852 only to attackers with an authorization level that is equal to or 853 higher than that of the client that initiated the scheduled RPC. 855 7. IANA Considerations 857 This document proposes to register the following capability 858 identifier URN in the 'Network Configuration Protocol (NETCONF) 859 Capability URNs' registry: 861 urn:ietf:params:netconf:capability:time:1.0 863 This document proposes to register the following XML namespace URN 864 in the 'IETF XML registry', following the format defined in 865 [RFC3688]: 867 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-time 869 This document proposes to register a module name in the 'YANG Module 870 Names' registry, defined in [RFC6020]. 872 name: ietf-netconf-time 874 prefix: nct 876 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-time 878 RFC: TBD 880 8. Acknowledgments 882 The authors gratefully acknowledge Joe Marcus Clarke, Andy Bierman, 883 Balazs Lengyel, Jonathan Hansford, John Heasley, Robert Sparks, Al 884 Morton, Olafur Gudmundsson, Juergen Schoenwaelder, Joel Jaeggli, 885 Alon Schneider and Eylon Egozi for their insightful comments. 887 This work was supported in part by Israel Science Foundation grant 888 ISF 1520/11. 890 This document was prepared using 2-Word-v2.0.template.dot. 892 9. References 894 9.1. Normative References 896 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 897 Requirement Levels", BCP 14, RFC 2119, March 1997. 899 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 900 Internet: Timestamps", RFC 3339, July 2002. 902 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 903 3688, January 2004. 905 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 906 July 2013. 908 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., 909 Ed., Bierman, A., Ed., "Network Configuration Protocol 910 (NETCONF)", RFC 6241, June 2011. 912 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 913 Base Notifications", RFC 6470, February 2012. 915 9.2. Informative References 917 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for 918 the Network Configuration Protocol (NETCONF)", RFC 919 6020, October 2010. 921 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 922 Shell (SSH)", RFC 6242, June 2011. 924 [RFC6243] Bierman, A., Lengyel, B., "With-defaults Capability 925 for NETCONF", RFC 6243, June 2011. 927 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 928 Protocol (NETCONF) Access Control Model", RFC 6536, 929 March 2012. 931 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 932 System Management", RFC 7317, August 2014. 934 [Cond] Watsen, K., "Conditional Enablement of Configuration 935 Nodes", draft-kwatsen-conditional-enablement-00 936 (expired), 2013. 938 [HotSDN] Mizrahi, T., Moses, Y., "Time-based Updates in 939 Software Defined Networks", the second workshop on hot 940 topics in software defined networks (HotSDN), 2013. 942 [IEEE1588] IEEE TC 9 Instrumentation and Measurement Society, 943 "1588 IEEE Standard for a Precision Clock 944 Synchronization Protocol for Networked Measurement and 945 Control Systems Version 2", IEEE Standard, 2008. 947 [NTP] Mills, D., Martin, J., Burbank, J., Kasch, W., 948 "Network Time Protocol Version 4: Protocol and 949 Algorithms Specification", RFC 5905, June 2010. 951 [RFC5907] Gerstung, H., Elliott, C., Haberman, B., "Definitions 952 of Managed Objects for Network Time Protocol Version 4 953 (NTPv4", RFC 5907, June 2010. 955 [TimeSec] Mizrahi, T., "Security Requirements of Time Protocols 956 in Packet Switched Networks", RFC 7384, October 2014. 958 [TimeTR] Mizrahi, T., Moses, Y., "Time-based Updates in 959 OpenFlow: A Proposed Extension to the OpenFlow 960 Protocol", Technion - Israel Institute of Technology, 961 technical report, CCIT Report #835, EE Pub No. 1792, 962 2013. 963 http://tx.technion.ac.il/~dew/OFTimeTR.pdf 965 Appendix A. YANG Module for the Time Capability 967 This section is normative. 969 file "ietf-netconf-time@2015-09-01.yang" 971 module ietf-netconf-time { 973 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-time"; 975 prefix nct; 976 import ietf-netconf { prefix nc; } 978 import ietf-yang-types { prefix yang; } 980 import ietf-netconf-monitoring { prefix ncm; } 982 organization 983 "IETF"; 985 contact 986 "Editor: Tal Mizrahi 987 988 Editor: Yoram Moses 989 "; 991 description 992 "This module defines a capability-based extension to the 993 Network Configuration Protocol (NETCONF) that allows 994 time-triggered configuration and management operations. 995 This extension allows NETCONF clients to invoke configuration 996 updates according to scheduled times, and allows NETCONF 997 servers to attach timestamps to the data they send to NETCONF 998 clients. 1000 Copyright (c) 2015 IETF Trust and the persons identified as 1001 the document authors. All rights reserved. 1003 Redistribution and use in source and binary forms, with or 1004 without modification, is permitted pursuant to, and subject 1005 to the license terms contained in, the Simplified BSD License 1006 set forth in Section 4.c of the IETF Trust's Legal Provisions 1007 Relating to IETF Documents 1008 (http://trustee.ietf.org/license-info)."; 1010 revision 2015-09-01 { 1011 description 1012 "Initial version."; 1013 reference 1014 "draft-mm-netconf-time-capability: 1015 Time Capability in NETCONF"; 1016 } 1018 typedef time-interval { 1019 type string { 1020 pattern '\d{2}:\d{2}:\d{2}(\.\d+)?'; 1021 } 1022 description 1023 "Defines a time interval, up to 24 hours. 1024 The format is specified as HH:mm:ss.f, 1025 consisting of two digits for hours, 1026 two digits for minutes, two digits 1027 for seconds, and zero or more digits 1028 representing second fractions."; 1029 } 1031 grouping scheduling-tolerance-parameters { 1032 leaf sched-max-future { 1033 type time-interval; 1034 default 00:00:15.0; 1035 description 1036 "When the scheduled time is in the future, i.e., greater 1037 than the present time, this leaf defines the maximal 1038 difference between the scheduled time 1039 and the present time that the server is willing to 1040 accept. If the difference exceeds this number, the 1041 server responds with an error."; 1042 } 1044 leaf sched-max-past { 1045 type time-interval; 1046 default 00:00:15.0; 1047 description 1048 "When the scheduled time is in the past, i.e., less 1049 than the present time, this leaf defines the maximal 1050 difference between the present time 1051 and the scheduled time that the server is willing to 1052 accept. If the difference exceeds this number, the 1053 server responds with an error."; 1054 } 1056 description 1057 "Contains the parameters of the scheduling tolerance."; 1058 } 1059 // extending the get-config operation 1060 augment /nc:get-config/nc:input { 1061 leaf scheduled-time { 1062 type yang:date-and-time; 1063 description 1064 "The time at which the RPC is scheduled to be performed."; 1065 } 1067 leaf get-time { 1068 type empty; 1069 description 1070 "Indicates that the rpc-reply should include the 1071 execution-time."; 1072 } 1074 description 1075 "Adds the time element to ."; 1076 } 1078 augment /nc:get-config/nc:output { 1079 leaf execution-time { 1080 type yang:date-and-time; 1081 description 1082 "The time at which the RPC was executed."; 1083 } 1085 description 1086 "Adds the time element to ."; 1087 } 1089 augment /nc:get/nc:input { 1090 leaf scheduled-time { 1091 type yang:date-and-time; 1092 description 1093 "The time at which the RPC is scheduled to be performed."; 1094 } 1096 leaf get-time { 1097 type empty; 1098 description 1099 "Indicates that the rpc-reply should include the 1100 execution-time."; 1101 } 1103 description 1104 "Adds the time element to ."; 1105 } 1107 augment /nc:get/nc:output { 1108 leaf execution-time { 1109 type yang:date-and-time; 1110 description 1111 "The time at which the RPC was executed."; 1112 } 1114 description 1115 "Adds the time element to ."; 1116 } 1118 augment /nc:copy-config/nc:input { 1119 leaf scheduled-time { 1120 type yang:date-and-time; 1121 description 1122 "The time at which the RPC is scheduled to be performed."; 1123 } 1125 leaf get-time { 1126 type empty; 1127 description 1128 "Indicates that the rpc-reply should include the 1129 execution-time."; 1130 } 1132 description 1133 "Adds the time element to ."; 1134 } 1136 augment /nc:copy-config/nc:output { 1137 leaf execution-time { 1138 type yang:date-and-time; 1139 description 1140 "The time at which the RPC was executed."; 1141 } 1143 description 1144 "Adds the time element to ."; 1145 } 1147 augment /nc:edit-config/nc:input { 1148 leaf scheduled-time { 1149 type yang:date-and-time; 1150 description 1151 "The time at which the RPC is scheduled to be performed."; 1152 } 1154 leaf get-time { 1155 type empty; 1156 description 1157 "Indicates that the rpc-reply should include the 1158 execution-time."; 1159 } 1161 description 1162 "Adds the time element to ."; 1163 } 1165 augment /nc:edit-config/nc:output { 1166 leaf execution-time { 1167 type yang:date-and-time; 1168 description 1169 "The time at which the RPC was executed."; 1170 } 1172 description 1173 "Adds the time element to ."; 1174 } 1176 augment /nc:delete-config/nc:input { 1177 leaf scheduled-time { 1178 type yang:date-and-time; 1179 description 1180 "The time at which the RPC is scheduled to be performed."; 1181 } 1183 leaf get-time { 1184 type empty; 1185 description 1186 "Indicates that the rpc-reply should include the 1187 execution-time."; 1188 } 1190 description 1191 "Adds the time element to ."; 1192 } 1194 augment /nc:delete-config/nc:output { 1195 leaf execution-time { 1196 type yang:date-and-time; 1197 description 1198 "The time at which the RPC was executed."; 1199 } 1200 description 1201 "Adds the time element to ."; 1202 } 1204 augment /nc:lock/nc:input { 1205 leaf scheduled-time { 1206 type yang:date-and-time; 1207 description 1208 "The time at which the RPC is scheduled to be performed."; 1209 } 1211 leaf get-time { 1212 type empty; 1213 description 1214 "Indicates that the rpc-reply should include the 1215 execution-time."; 1216 } 1218 description 1219 "Adds the time element to ."; 1220 } 1221 augment /nc:lock/nc:output { 1222 leaf execution-time { 1223 type yang:date-and-time; 1224 description 1225 "The time at which the RPC was executed."; 1226 } 1228 description 1229 "Adds the time element to ."; 1230 } 1232 augment /nc:unlock/nc:input { 1233 leaf scheduled-time { 1234 type yang:date-and-time; 1235 description 1236 "The time at which the RPC is scheduled to be performed."; 1237 } 1239 leaf get-time { 1240 type empty; 1241 description 1242 "Indicates that the rpc-reply should include the 1243 execution-time."; 1244 } 1246 description 1247 "Adds the time element to ."; 1248 } 1250 augment /nc:unlock/nc:output { 1251 leaf execution-time { 1252 type yang:date-and-time; 1253 description 1254 "The time at which the RPC was executed."; 1255 } 1257 description 1258 "Adds the time element to ."; 1259 } 1260 augment /nc:commit/nc:input { 1261 leaf scheduled-time { 1262 type yang:date-and-time; 1263 description 1264 "The time at which the RPC is scheduled to be performed."; 1265 } 1267 leaf get-time { 1268 type empty; 1269 description 1270 "Indicates that the rpc-reply should include the 1271 execution-time."; 1272 } 1274 description 1275 "Adds the time element to ."; 1276 } 1278 augment /nc:commit/nc:output { 1279 leaf execution-time { 1280 type yang:date-and-time; 1281 description 1282 "The time at which the RPC was executed."; 1283 } 1285 description 1286 "Adds the time element to ."; 1287 } 1289 augment /ncm:netconf-state { 1290 container scheduling-tolerance { 1291 uses scheduling-tolerance-parameters; 1292 description 1293 "The scheduling tolerance when the time capability 1294 is enabled."; 1295 } 1296 description 1297 "The scheduling tolerance of the server."; 1298 } 1300 rpc cancel-schedule { 1301 description 1302 "Cancels a scheduled message."; 1303 reference 1304 "draft-mm-netconf-time-capability: 1305 Time Capability in NETCONF"; 1307 input { 1308 leaf cancelled-message-id { 1309 type string; 1310 description 1311 "The ID of the message to be cancelled."; 1312 } 1313 leaf get-time { 1314 type empty; 1315 description 1316 "Indicates that the rpc-reply should include 1317 the execution-time."; 1318 } 1319 } 1320 output { 1321 leaf execution-time { 1322 type yang:date-and-time; 1323 description 1324 "The time at which the RPC was executed."; 1325 } 1326 } 1327 } 1329 notification netconf-scheduled-message { 1330 leaf schedule-id { 1331 type string; 1332 description 1333 "The ID of the scheduled message."; 1334 } 1336 leaf scheduled-time { 1337 type yang:date-and-time; 1338 description 1339 "The time at which the RPC is scheduled to be performed."; 1340 } 1341 description 1342 "Indicates that a scheduled message was received."; 1343 reference 1344 "draft-mm-netconf-time-capability: 1345 Time Capability in NETCONF"; 1346 } 1348 } 1349 1351 Authors' Addresses 1353 Tal Mizrahi 1354 Department of Electrical Engineering 1355 Technion - Israel Institute of Technology 1356 Technion City, Haifa, 32000, Israel 1358 Email: dew@tx.technion.ac.il 1360 Yoram Moses 1361 Department of Electrical Engineering 1362 Technion - Israel Institute of Technology 1363 Technion City, Haifa, 32000, Israel 1365 Email: moses@ee.technion.ac.il