-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-gonzalez-netconf-5277bis-02.txt
3584 lines (2588 loc) · 113 KB
/
draft-gonzalez-netconf-5277bis-02.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
NETCONF A. Gonzalez Prieto
Internet-Draft A. Clemm
Intended status: Standards Track E. Voit
Expires: December 16, 2016 E. Nilsen-Nygaard
A. Tripathy
Cisco Systems
S. Chisholm
Ciena
H. Trevino
Cisco Systems
June 14, 2016
Subscribing to YANG-Defined Event Notifications
draft-gonzalez-netconf-5277bis-02
Abstract
DISCLAIMER: WHILE THIS DOCUMENT HAS BEEN FORMATTED TO APPEAR AS AN
INTERNET DRAFT, THIS VERSION CONSTITUTES WORK-IN-PROGRESS AND HAS NOT
BEEN SUBMITTED TO THE IETF INTERNET DRAFT REPOSITORY.
This document defines capabilities and operations for providing
asynchronous message notification delivery for notifications defined
using YANG. Notification delivery can occur over a variety of
protocols used commonly in conjunction with YANG, such as NETCONF and
Restconf. The capabilities and operations defined in this document
along with their mapping onto NETCONF transport (to be specified in a
separate document, but still included in the current document
version) are intended to obsolete RFC 5277.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 16, 2016.
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 1]
Internet-Draft 5277 bis June 2016
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
1.3. Solution Overview . . . . . . . . . . . . . . . . . . . . 6
2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 7
2.2. Event Stream Discovery . . . . . . . . . . . . . . . . . 7
2.3. Default Event Stream . . . . . . . . . . . . . . . . . . 8
2.4. Filters . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.5. Subscription State Model at the Publisher . . . . . . . . 8
2.6. Data Model Trees for Event Notifications . . . . . . . . 9
2.7. Creating a Subscription . . . . . . . . . . . . . . . . . 13
2.8. Establishing a Subscription . . . . . . . . . . . . . . . 16
2.9. Modifying a Subscription . . . . . . . . . . . . . . . . 19
2.10. Deleting a Subscription . . . . . . . . . . . . . . . . . 23
2.11. Configured Subscriptions . . . . . . . . . . . . . . . . 25
2.12. Event (Data Plane) Notifications . . . . . . . . . . . . 29
2.13. Control Plane Notifications . . . . . . . . . . . . . . . 31
2.14. Subscription Management . . . . . . . . . . . . . . . . . 33
3. Data Models for Event Notifications . . . . . . . . . . . . . 34
3.1. Data Model for RFC5277 (netmod namespace) . . . . . . . . 34
3.2. Data Model for RFC5277 (netconf namespace) . . . . . . . 37
3.3. Data Model for RFC5277-bis Extensions . . . . . . . . . . 41
4. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 59
5. Security Considerations . . . . . . . . . . . . . . . . . . . 60
6. Issues that are currently being worked and resolved . . . . . 61
6.1. Unresolved and yet-to-be addressed issues . . . . . . . . 61
6.2. Agreement in principal . . . . . . . . . . . . . . . . . 61
6.3. Resolved Issues . . . . . . . . . . . . . . . . . . . . . 62
6.4. Editorial To-Dos . . . . . . . . . . . . . . . . . . . . 62
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 62
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 2]
Internet-Draft 5277 bis June 2016
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 62
8.1. Normative References . . . . . . . . . . . . . . . . . . 63
8.2. Informative References . . . . . . . . . . . . . . . . . 63
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 63
1. Introduction
[RFC6241] can be conceptually partitioned into four layers:
Layer Example
+-------------+ +-------------------------------------------+
| Content | | Configuration data |
+-------------+ +-------------------------------------------+
| |
+-------------+ +-------------------------------------------+
| Operations | |<get-config>, <edit-config>, <notification>|
+-------------+ +-------------------------------------------+
| | |
+-------------+ +-----------------------------+ |
| RPC | | <rpc>, <rpc-reply> | |
+-------------+ +-----------------------------+ |
| | |
+-------------+ +-------------------------------------------+
| Transport | | BEEP, SSH, SSL, console |
| Protocol | | |
+-------------+ +-------------------------------------------+
This document defines mechanisms that provide an asynchronous message
notification delivery service for the NETCONF protocol [RFC6241].
This is an optional capability built on top of the base NETCONF
definition. This document also defines the capabilities and
operations necessary to establish, monitor, and support subscriptions
into this notification delivery service.
Editor's note: The current version of this document specifies both
capabilities and operations for providing asynchronous notification
delivery, as well as mapping of those capabilities and operations
onto NETCONF. The transport mapping to NETCONF will be moved into a
separate document and will be removed in future revisions of this
document.
1.1. Motivation
The motivation for this work is to enable the sending of asynchronous
notification messages that are consistent with the data model
(content) and security model used within a NETCONF implementation.
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 3]
Internet-Draft 5277 bis June 2016
[RFC5277] defines a notification mechanism for NETCONF. However,
there are various limitations:
o Each subscription requires a separate NETCONF connection, which is
wasteful.
o The only mechanism to terminate a subscription is terminating the
underlying NETCONF connection.
o No ability to modify subscriptions once they have been created.
o No ability to notify the receiver of a subscription if the server
is dropping events.
o No mechanism to monitor subscriptions.
o No alternative mechanism to create subscriptions via RPCs. Thus
the lifetime of the subscription is limited by that of the
underlaying NETCONF session.
o Predates YANG and defines RPCs, notifications, and data nodes
outside of the YANG framework.
The scope of the work aims at meeting the following operational
needs:
o Ability to dynamically or statically subscribe to event
notifications available on a NETCONF agent.
o Ability to negotiate acceptable dynamic subscription parameters.
o Ability to support multiple subscriptions over a single NETCONF
session.
o Ability to filter the subset of notifications to be pushed with
stream-specific semantics.
o Ability for the notification payload to be interpreted
independently of the NETCONF transport protocol. (In other words,
the encoded notification fully describes itself.)
o Mechanism to communicate the notifications.
o Ability to replay locally logged notifications.
o Backwards compatible with RFC 5277 implementations.
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 4]
Internet-Draft 5277 bis June 2016
o Define in YANG, the RPCs, notifications, and data nodes in RFC
5277.
1.2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
Event: Something that happens that may be of interest. (e.g., a
configuration change, a fault, a change in status, crossing a
threshold, or an external input to the system.)
Event notification: A message sent by a server to a receiver
indicating that an event (of interest to the subscriber) has
occurred. Events can trigger notifications if an interested party
has subscribed to the stream(s) it belongs to.
Stream (also referred to as "event stream"): A continuous flow of
event, status, state, or other information.
Subscriber: An entity able to request and negotiate a contract for
the receipt of event notifications from a NETCONF server.
Receiver: A target to which a NETCONF server pushes event
notifications. In many deployments, the receiver and subscriber will
be the same entity.
Subscription: A contract between a subscriber and a NETCONF server,
stipulating which information the receiver wishes to have pushed from
the server without the need for further solicitation.
Filter: Evaluation criteria, which may be applied against a targeted
set of objects/events in a subscription. Information traverses the
filter only if specified filter criteria are met.
Dynamic subscription: A subscription agreed between subscriber and
NETCONF server via create, establish, modify, and delete RPC control
plane signaling messages.
Configured subscription: A subscription installed via a configuration
interface.
Operation: In this document, this term refers to NETCONF protocol
operations [RFC6241] defined in support of NETCONF notifications.
NACM: NETCONF Access Control Model.
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 5]
Internet-Draft 5277 bis June 2016
RPC: Remote Procedure Call.
1.3. Solution Overview
This document describes mechanisms for subscribing and receiving
event notifications from a NETCONF server. This document enhances
the capabilities of RFC 5277 while maintaining backwards capability
with existing implementations. It is intended that a final version
of this document might obsolete RFC 5277.
The enhancements over [RFC5277] include the ability to terminate
subscriptions without terminating the client session, to modify
existing subscriptions, and to have multiple subscriptions on a
NETCONF session.
These enhancements do not affect [RFC5277] clients that do not
support these particular subscription requirements.
The solution supports subscribing to event notifications using two
mechanisms.
1. Dynamic subscriptions, where a NETCONF client initiates a
subscription negotiation with a NETCONF server. Here a client
initiates a negotiation by issuing a subscription request. If
the agent wants to serve this request, it will accept it, and
then start pushing event notifications as negotiated. If the
agent does not wish to serve it as requested, it may respond with
subscription parameters, which it would have accepted.
2. Configured subscriptions, which is an optional mechanism that
enables managing subscriptions via a configuration interface so
that a NETCONF agent sends event notifications to given
receiver(s).
Some key characteristics of configured and dynamic subscriptions
include:
o The lifetime of a dynamic subscription is limited by the lifetime
of the subscriber session used to establish it. Typically loss of
the transport session tears down any dependent dynamic
subscriptions.
o The lifetime of a configured subscription is driven by
configuration being present on the running configuration. This
implies configured subscriptions persist across reboots, and
persists even when transport is unavailable. This also means
configured subscriptions do not support negotiation.
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 6]
Internet-Draft 5277 bis June 2016
o Subscriptions can be modified or terminated at any point of their
lifetime. configured subscriptions can be modified by any
configuration client with write rights on the configuration of the
subscription.
o A NETCONF agent can support multiple dynamic subscriptions
simultaneously in the context of a single NETCONF session. (This
requires supporting interleaving.) The termination of any of
those subscriptions does not imply the termination of NETCONF
transport session.
Note that there is no mixing-and-matching of RPC and configuration
operations. Specifically, a configured subscription cannot be
modified or deleted using RPC. Similarly, a subscription created via
RPC cannot be modified through configuration operations.
The NETCONF agent may decide to terminate a dynamic subscription at
any time. Similarly the NETCONF agent may decide to temporarily
suspend the sending of event notifications for either configured or
dynamic subscriptions. Such termination or suspension may be driven
by the agent running out of resources to serve the subscription, or
by internal errors on the server.
2. Solution
2.1. Event Streams
An event stream is a set of events available for subscription from a
server. It is out of the scope of this document to identify a) how
streams are defined, b) how events are defined/generated, and c) how
events are assigned to streams.
The following is a high-level description of the flow of a
notification. Note that it does not mandate and/or preclude an
implementation. As events are raised, they are assigned to streams.
An event may be assigned to multiple streams. The event is
distributed to subscribers and receivers based on the current
subscriptions and access control. Access control is needed because
if any receiver of that subscription does not have permission to
receive an event, then it never makes it into a notification, and
processing of the event is completed for that subscription.
2.2. Event Stream Discovery
A server maintains a list of available event streams as operational
data. A client can retrieve this list like any other YANG-defined
data, for example using the <get> operation when using NETCONF.
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 7]
Internet-Draft 5277 bis June 2016
2.3. Default Event Stream
A NETCONF server implementation supporting the notification
capability MUST support the "NETCONF" notification event stream.
This stream contains all NETCONF XML event notifications supported by
the NETCONF server, except for those belonging only to streams that
explicitly indicate that they must be excluded from the NETCONF
stream. The exact string "NETCONF" is used during the advertisement
of stream support during the <get> operation on <streams> and during
the <create-subscription> and <establish-subscription> operations.
2.4. Filters
A NETCONF Server implementation SHOULD support the ability to perform
filtering of notification records per RFC 5277.
2.5. Subscription State Model at the Publisher
Below is the state machine of a subscription for the publisher. It
is important to note that a subscription doesn't exist at the
publisher until it is accepted and made active. The mere request by
a subscriber to establish a subscription is insufficient for that
asserted subscription to be externally visible via this state
machine.
.-------.
| start |
'-------'
|
establish
|
| .----------modify-------------.lex
v v '
.-----------. .-----------.
.--------. | |------>suspend------->| |
modify '| active | | suspended |
'--------->| |<----resume----<------| |
'-----------' '-----------'
| |
delete delete
| |
v |
.-------. |
| end |<-----------------------------'
'-------'
Figure 1: Subscription states at publisher
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 8]
Internet-Draft 5277 bis June 2016
Of interest in this state machine are the following:
o Successful <establish-subscription> or <modify-subscription>
requests put the subscription into an active state.
o Failed <modify-subscription> requests will leave the subscription
in its previous state, with no visible change to any streaming
updates.
o A <delete-subscription> request will delete the entire
subscription.
2.6. Data Model Trees for Event Notifications
The YANG data models for event notifications are depicted in the
following sections.
2.6.1. Data Model Tree for RFC5277 (netconf namespace)
module: ietf-5277-netconf
rpcs:
+---x create-subscription
+--ro input
+--ro stream? string
+--ro (filter-type)?
| +--:(rfc5277)
| +--ro filter
+--ro startTime? yang:date-and-time
+--ro stopTime? yang:date-and-time
2.6.2. Data Model Tree for RFC5277 (netmod namespace)
module: ietf-5277-netmod
+--rw netconf
+--rw streams
+--rw stream* [name]
+--rw name string
+--rw description string
+--rw replaySupport boolean
+--rw replayLogCreationTime yang:date-and-time
+--rw replayLogAgedTime yang:date-and-time
notifications:
+---n replayComplete
+---n notificationComplete
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 9]
Internet-Draft 5277 bis June 2016
2.6.3. Data Model for RFC5277-bis Extensions
module: ietf-event-notifications
+--ro streams
| +--ro stream* notif:stream
+--rw filters
| +--rw filter* [filter-id]
| +--rw filter-id filter-id
| +--rw (filter-type)?
| +--:(rfc5277)
| +--rw filter
+--rw subscription-config {configured-subscriptions}?
| +--rw subscription* [subscription-id]
| +--rw subscription-id subscription-id
| +--rw stream? stream
| +--rw (filter-type)?
| | +--:(rfc5277)
| | | +--rw filter
| | +--:(by-reference)
| | +--rw filter-ref? filter-ref
| +--rw startTime? yang:date-and-time
| +--rw stopTime? yang:date-and-time
| +--rw encoding? encoding
| +--rw receivers
| | +--rw receiver* [address]
| | +--rw address inet:host
| | +--rw port inet:port-number
| | +--rw protocol? transport-protocol
| +--rw (push-source)?
| +--:(interface-originated)
| | +--rw source-interface? if:interface-ref
| +--:(address-originated)
| +--rw source-vrf? uint32
| +--rw source-address inet:ip-address-no-zone
+--ro subscriptions
+--ro subscription* [subscription-id]
+--ro subscription-id subscription-id
+--ro configured-subscription? empty {configured-subscriptions}?
+--ro subscription-status? subscription-status
+--ro stream? stream
+--ro (filter-type)?
| +--:(rfc5277)
| | +--ro filter
| +--:(by-reference)
| +--ro filter-ref? filter-ref
+--ro startTime? yang:date-and-time
+--ro stopTime? yang:date-and-time
+--ro encoding? encoding
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 10]
Internet-Draft 5277 bis June 2016
+--ro receivers
| +--ro receiver* [address]
| +--ro address inet:host
| +--ro port inet:port-number
| +--ro protocol? transport-protocol
+--ro (push-source)?
+--:(interface-originated)
| +--ro source-interface? if:interface-ref
+--:(address-originated)
+--ro source-vrf? uint32
+--ro source-address inet:ip-address-no-zone
augment /netmod-notif:replayComplete:
+---- subscription-id? subscription-id
augment /netmod-notif:notificationComplete:
+---- subscription-id? subscription-id
augment /netmod-notif:netconf/netmod-notif:streams:
+--rw exclude-from-NETCONF-stream? empty
rpcs:
+---x establish-subscription
| +---w input
| | +---w stream? stream
| | +---w (filter-type)?
| | | +--:(rfc5277)
| | | | +---w filter
| | | +--:(by-reference)
| | | +---w filter-ref? filter-ref
| | +---w startTime? yang:date-and-time
| | +---w stopTime? yang:date-and-time
| | +---w encoding? encoding
| +--ro output
| +--ro subscription-result subscription-result
| +--ro (result)?
| +--:(success)
| | +--ro subscription-id subscription-id
| +--:(no-success)
| +--ro stream? stream
| +--ro (filter-type)?
| | +--:(rfc5277)
| | | +--ro filter
| | +--:(by-reference)
| | +--ro filter-ref? filter-ref
| +--ro startTime? yang:date-and-time
| +--ro stopTime? yang:date-and-time
| +--ro encoding? encoding
+---x modify-subscription
| +---w input
| | +---w subscription-id? subscription-id
| | +---w stream? stream
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 11]
Internet-Draft 5277 bis June 2016
| | +---w (filter-type)?
| | | +--:(rfc5277)
| | | | +---w filter
| | | +--:(by-reference)
| | | +---w filter-ref? filter-ref
| | +---w startTime? yang:date-and-time
| | +---w stopTime? yang:date-and-time
| | +---w encoding? encoding
| +--ro output
| +--ro subscription-result subscription-result
| +--ro (result)?
| +--:(success)
| | +--ro subscription-id subscription-id
| +--:(no-success)
| +--ro stream? stream
| +--ro (filter-type)?
| | +--:(rfc5277)
| | | +--ro filter
| | +--:(by-reference)
| | +--ro filter-ref? filter-ref
| +--ro startTime? yang:date-and-time
| +--ro stopTime? yang:date-and-time
| +--ro encoding? encoding
+---x delete-subscription
+---w input
| +---w subscription-id subscription-id
+--ro output
+--ro subscription-result subscription-result
notifications:
+---n subscription-started
| +--ro subscription-id subscription-id
| +--ro stream? stream
| +--ro (filter-type)?
| | +--:(rfc5277)
| | | +--ro filter
| | +--:(by-reference)
| | +--ro filter-ref? filter-ref
| +--ro startTime? yang:date-and-time
| +--ro stopTime? yang:date-and-time
| +--ro encoding? encoding
+---n subscription-suspended
| +--ro subscription-id subscription-id
| +--ro reason? subscription-susp-reason
+---n subscription-resumed
| +--ro subscription-id subscription-id
+---n subscription-modified
| +--ro subscription-id subscription-id
| +--ro stream? stream
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 12]
Internet-Draft 5277 bis June 2016
| +--ro (filter-type)?
| | +--:(rfc5277)
| | | +--ro filter
| | +--:(by-reference)
| | +--ro filter-ref? filter-ref
| +--ro startTime? yang:date-and-time
| +--ro stopTime? yang:date-and-time
| +--ro encoding? encoding
+---n subscription-terminated
| +--ro subscription-id subscription-id
| +--ro reason? subscription-term-reason
+---n added-to-subscription
| +--ro subscription-id subscription-id
| +--ro stream? stream
| +--ro (filter-type)?
| | +--:(rfc5277)
| | | +--ro filter
| | +--:(by-reference)
| | +--ro filter-ref? filter-ref
| +--ro startTime? yang:date-and-time
| +--ro stopTime? yang:date-and-time
| +--ro encoding? encoding
+---n removed-from-subscription
+--ro subscription-id subscription-id
2.7. Creating a Subscription
This operation is fully defined in [RFC5277]. It allows a subscriber
to request the creation of a dynamic subscription. If successful,
the subscription remains in effect for the duration of the NETCONF
session.
This operation is included in the document for supporting backwards
compatibility with [RFC5277] clients. New clients are expected not
to use this operation, but establish subscriptions as defined in
Section 2.8
2.7.1. Parameters
The input parameters of the operation are:
stream: An optional parameter that indicates which stream of events
is of interest. If not present, events in the default NETCONF stream
will be sent.
filter: An optional parameter that indicates which subset of all
possible events is of interest. The format of this parameter is the
same as that of the filter parameter in the NETCONF protocol
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 13]
Internet-Draft 5277 bis June 2016
operations. If not present, all events not precluded by other
parameters will be sent.
startTime: An optional parameter used to trigger the replay feature
and indicate that the replay should start at the time specified. If
startTime is not present, this is not a replay subscription. It is
not valid to specify start times that are later than the current
time. If the startTime specified is earlier than the log can
support, the replay will begin with the earliest available
notification. Implementations must support time zones.
stopTime: An optional parameter used with the optional replay feature
to indicate the newest notifications of interest. If stopTime is not
present, the notifications will continue until the subscription is
terminated. Must be used with and be later than startTime.
Implementations must support time zones.
2.7.2. Usage Example
The following demonstrates dynamically creating a simple
subscription.
<netconf:rpc message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<create-subscription
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
</create-subscription>
</netconf:rpc>
Figure 2: Create subscription
2.7.3. Positive Response
If the NETCONF server can satisfy the request, the server sends an
<ok> element.
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 14]
Internet-Draft 5277 bis June 2016
<netconf:rpc netconf:message-id="102"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<create-subscription
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<filter netconf:type="xpath"
xmlns:ex="http://example.com/event/1.0"
select="/ex:event[ex:eventClass='fault' and
(ex:severity='minor' or ex:severity='major'
or ex:severity='critical')]"/>
</create-subscription>
</netconf:rpc>
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
Figure 3: Successful create subscription
2.7.4. Negative Response
If the request cannot be completed for any reason, an <rpc-error>
element is included within the <rpc-reply>. Subscription requests
can fail for several reasons including if a filter with invalid
syntax is provided or if the name of a non-existent stream is
provided.
If a stopTime is specified in a request without having specified a
startTime, the following error is returned:
Tag: missing-element
Error-type: protocol
Severity: error
Error-info: <bad-element>: startTime
Description: An expected element is missing.
If the optional replay feature is requested but the NETCONF server
does not support it, the following error is returned:
Tag: operation-failed
Error-type: protocol
Severity: error
Error-info: none
Description: Request could not be completed because the
requested operation failed for some reason
not covered by any other error condition.
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 15]
Internet-Draft 5277 bis June 2016
If a stopTime is requested that is earlier than the specified
startTime, the following error is returned:
Tag: bad-element
Error-type: protocol
Severity: error
Error-info: <bad-element>: stopTime
Description: An element value is not correct;
e.g., wrong type, out of range, pattern mismatch.
If a startTime is requested that is later than the current time, the
following error is returned:
Tag: bad-element
Error-type: protocol
Severity: error
Error-info: <bad-element>: startTime
Description: An element value is not correct;
e.g., wrong type, out of range, pattern mismatch.
2.8. Establishing a Subscription
This operation is an evolution of the create subscription operation.
It allows a subscriber to request the creation of a subscription both
via RPC and configuration operations. When invoking the RPC,
establish-subscription permits negotiating the subscription terms,
changing them dynamically and enabling multiple subscriptions overs a
single NETCONF session (if interleaving [RFC6241] is supported), and
canceling subscriptions without terminating the NETCONF session.
2.8.1. Parameters
The input parameters of the operation are those of create
subscription plus:
filter-ref: filters that have been previously (and separately)
configured can be referenced by a subscription. This mechanism
enables the reuse of filters.
encoding: by default, updates are encoded using XML. Other encodings
may be supported, such as JSON.
2.8.2. Usage Example
The following demonstrates establishing a simple subscription.
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 16]
Internet-Draft 5277 bis June 2016
<netconf:rpc message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.1">
</establish-subscription>
</netconf:rpc>
Figure 4: Establish subscription
2.8.3. Positive Response
If the NETCONF server can satisfy the request, the server sends a
positive <subscription-result> element, and the subscription-id of
the accepted subscription.
<netconf:rpc netconf:message-id="102"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.1">
<filter netconf:type="xpath"
xmlns:ex="http://example.com/event/1.0"
select="/ex:event[ex:eventClass='fault' and
(ex:severity='minor' or ex:severity='major'
or ex:severity='critical')]"/>
</establish-subscription>
</netconf:rpc>
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<subscription-result
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.1">
ok
</subscription-result>
<subscription-id
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.1">
52
</subscription-id>
</rpc-reply>
Figure 5: Successful establish subscription
2.8.4. Negative Response
If the NETCONF server cannot satisfy the request, the server sends a
negative <subscription-result> element.
Gonzalez Prieto, et al. Expires December 16, 2016 [Page 17]
Internet-Draft 5277 bis June 2016
If the client has no authorization to establish the subscription, the
<subscription-result> indicates an authorization error. For
instance:
<netconf:rpc netconf:message-id="103"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.1">
<stream>foo</stream>
</establish-subscription>
</netconf:rpc>
<rpc-reply message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<subscription-result
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.1">
error-data-not-authorized
</subscription-result>
</rpc-reply>
Figure 6: Unsuccessful establish subscription
If the request is rejected because the server is not able to serve
it, the server SHOULD include in the returned error what subscription
parameters would have been accepted for the request when it was
processed. However, they are no guarantee that subsequent requests
with those parameters for this client or others will be accepted.
For instance, consider a subscription from [netconf-yang-push], which
augments the establish-subscription with some additional parameters,
including "period". If the client requests a period the NETCONF
server cannot serve, the exchange may be: