-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-wang-netconf-adaptive-subscription-00.xml
597 lines (507 loc) · 21.8 KB
/
draft-wang-netconf-adaptive-subscription-00.xml
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
<?xml version="1.0" encoding="US-ASCII"?>
<!-- This template is for creating an Internet Draft using xml2rfc,
which is available here: http://xml.resource.org. -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
There has to be one entity for each item to be referenced.
An alternate method (rfc include) is described in the references. -->
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2697 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2697.xml">
<!ENTITY RFC2698 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2698.xml">
<!ENTITY RFC6020 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6020.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes" ?>
<?rfc tocompact="yes"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-wang-netconf-adaptive-subscription-00"
ipr="trust200902">
<front>
<title abbrev="Adaptive Subscription">Adaptive Subscription to YANG
Notification</title>
<author fullname="Michael Wang" initials="Z." surname="Wang">
<organization>Huawei</organization>
<address>
<postal>
<street>101 Software Avenue, Yuhua District</street>
<city>Nanjing</city>
<region>Jiangsu</region>
<code>210012</code>
<country>China</country>
</postal>
<email>wangzitao@huawei.com</email>
</address>
</author>
<author fullname="Qin Wu" initials="Q." surname="Wu">
<organization>Huawei</organization>
<address>
<postal>
<street>101 Software Avenue, Yuhua District</street>
<city>Nanjing</city>
<region>Jiangsu</region>
<code>210012</code>
<country>China</country>
</postal>
<email>bill.wu@huawei.com</email>
</address>
</author>
<author fullname="Wei Song" initials="W." surname="Song">
<organization>Huawei</organization>
<address>
<postal>
<street>101 Software Avenue, Yuhua District</street>
<city>Nanjing</city>
<region>Jiangsu</region>
<code>210012</code>
<country>China</country>
</postal>
<email>songwei80@huawei.com</email>
</address>
</author>
<author fullname="Liang Geng" initials="L." surname="Geng">
<organization>China Mobile</organization>
<address>
<postal>
<street>32 Xuanwumen West St, Xicheng District</street>
<city>Beijing</city>
<code>10053</code>
</postal>
<email>gengliang@chinamobile.com</email>
</address>
</author>
<author fullname="Peng Liu" initials="P." surname="Liu">
<organization>China Mobile</organization>
<address>
<postal>
<street>32 Xuanwumen West St, Xicheng District</street>
<city>Beijing</city>
<code>10053</code>
</postal>
<email>liupengyjy@chinamobile.com</email>
</address>
</author>
<date year="2020"/>
<area>OPS Area</area>
<workgroup>NETCONF Working Group</workgroup>
<abstract>
<t>This document defines a YANG data model and associated mechanism
enabling subscriber's adaptive subscriptions to a publisher's event
streams. Applying these elements allows a subscriber to automatically
adjust the volume of telemetry traffic sent from publisher to the
receivers.</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction">
<t>YANG-Push subscriptions [RFC8641] allow client applications to
subscribe to continuous datastore updates without needing to poll. It
defines a mechanism (i.e.,update trigger) to determine when an update
record needs to be generated. Two type of subscriptions are introduced
in [RFC8641], distinguished by how updates are triggered: periodic and
on-change.<list style="symbols">
<t>Periodic subscription allows subscribed data to be streamed to
the destination at a configured fixed periodic interval</t>
<t>On-change subscription allows update to be triggered when
whenever a change in the subscribed information is detected. The
periodic interval is set to zero value in the on-change subscription
case.</t>
</list></t>
<t>However in some cases (e.g., wireless channel contention and
interference causes the WLAN throughput and per-packet delays to vary
over time), both collectors and publishers are configured with multiple
periodic intervals and the subscribed data set can be streamed out to
the destination at adaptive sampling or export rate, e.g., when wireless
signal strength drops below a certain threshold, more data should be
collected at high frequency.</t>
<t>This document defines a YANG data model and associated mechanism
enabling subscriber's adaptive subscriptions to a publisher's event
streams. Applying these elements allows a subscriber to automatically
adjust the volume of telemetry traffic sent from publisher to the
receivers.</t>
<section title="Terminology">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.</t>
<t>This document uses the following terms:<list style="hanging">
<t hangText="Event:">Something that happens which may be of
interest or trigger the invocation of the rule. A fault, an alarm,
a change in network state, network security threat, hardware
malfunction, buffer untilization crossing a threshold, network
connection setup, an external input to the system, for example
[RFC3877].</t>
<t hangText="Client:">Defined in [RFC8342].</t>
<t hangText="Configuration: ">Defined in [RFC8342].</t>
<t hangText="Configured subscription:">Defined in [RFC8639]</t>
<t hangText="Configuration datastore: ">Defined in [RFC8342].</t>
<t hangText="Notification message: ">Information intended for a
receiver indicating that one or more events have occurred
[RFC8639].</t>
<t hangText="Publisher:">An entity responsible for streaming
notification messages per the terms of a subscription
[RFC8639].</t>
<t hangText="Receiver:">A target to which a publisher pushes
subscribed event records. For dynamic subscriptions, the receiver
and subscriber are the same entity [RFC8639].</t>
<t hangText="Subscriber: ">A client able to request and negotiate
a contract for the generation and push of event records from a
publisher. For dynamic subscriptions, the receiver and subscriber
are the same entity [RFC8639].</t>
<t hangText="Subscription:">A contract with a publisher,
stipulating the information that one or more receivers wish to
have pushed from the publisher without the need for further
solicitation [RFC8639].</t>
<t hangText="On-change subscription:">A datastore subscription
with updates that are triggered when changes in subscribed
datastore nodes are detected.</t>
<t hangText="Periodic subscription:">A datastore subscription with
updates that are triggered periodically according to some time
interval.</t>
</list></t>
</section>
</section>
<!-- intro -->
<section title="Model Overview">
<t>The YANG data model for the "Adaptive Subscription to YANG
Notification" augments the "update-trigger" in the YANG Push model to
add a "adaptive-period" case. Under the "adaptive-period" case, a
"adaptive-period" list is defined. The "adaptive-period" list uses the
key "id" for indexing. Within the "adaptive-period" list, an "interval"
leaf and the corresponding trigger conditions are defined. When the
trigger condition is satisfied, e.g., "op-field" exceeds the "op-value"
and the change of "op-field" is monotonically increasing, the update
interval will be changed into the value of "interval" leaf and the
objects being filtered will be exported every interval specified by the
value of "interval" leaf. The "anchor-time" is used to indciate at which
points in time periodic updates need to be assembled and sent. </t>
<t>The following tree diagrams [RFC8340] provide an overview of the data
model for "ietf-adaptive-subscription.yang" module.</t>
<figure>
<artwork>module: ietf-adaptive-subscription
augment /sn:subscriptions/sn:subscription/yp:update-trigger:
+--:(adaptive-subscription)
+--rw adaptive-subsciptions
+--rw adaptive-period* [id]
| +--rw id string
| +--rw op-field? yang:xpath1.0
| +--rw op-value? string
| +--rw operator? operator
| +--rw interval centiseconds
| +--rw anchor-time yang:date-time</artwork>
</figure>
</section>
<section title="Bulk Subscription YANG Module">
<figure>
<artwork><CODE BEGINS> file "ietf-adaptive-subscription@2020-02-14.yang"
module ietf-adaptive-subscription {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription";
prefix as;
import ietf-subscribed-notifications {
prefix sn;
}
import ietf-yang-push {
prefix yp;
}
import ietf-yang-types {
prefix yang;
}
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"";
description
"NETCONF Protocol Data Types and Protocol Operations.
Copyright (c) 2020 IETF Trust and the persons identified as
the document authors. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC xxxx; see
the RFC itself for full legal notices.";
revision 2019-12-15 {
description
"Initial revision";
reference
"RFCxxx Adaptive subscription to YANG notification.";
}
typedef centiseconds {
type uint32;
description
"A period of time, measured in units of 0.01 seconds.";
}
typedef operator {
type enumeration {
enum unequal {
description
"Indicates that the comparision type is unequal to.";
}
enum equal {
description
"Indicates that the comparision type is equal to.";
}
enum less {
description
"Indicates that the comparision type is less than.";
}
enum less-or-equal {
description
"Indicates that the comparision type is less than
or equal to.";
}
enum greater {
description
"Indicates that the comparision type is greater than.";
}
enum greater-or-equal {
description
"Indicates that the comparision type is greater than
or equal to.";
}
}
description
"definition of the operator";
}
augment "/sn:subscriptions/sn:subscription/yp:update-trigger" {
description
"This augmentation adds additional subscription parameters
that apply specifically to adaptive subscription.";
case adaptive-period {
container adaptive-periods {
list adaptive-period {
key "id";
leaf id {
type string;
description
"identifier";
}
leaf op-field {
type yang:xpath1.0;
description
"targeted objects";
}
leaf op-value {
type string;
description
"Compartion value which is static threshold value.";
}
leaf operator {
type operator;
description
"Comparison type.";
}
leaf interval {
type centiseconds;
mandatory true;
description
"Duration of time that should occur between periodic
push updates, in units of 0.01 seconds.";
}
leaf anchor-time {
type yang:date-and-time;
description
"Designates a timestamp before or after which a series
of periodic push updates are determined. The next
update will take place at a point in time that is a
multiple of a period from the 'anchor-time'.
If an anchor-time is not provided, then the anchor-time
MUST be set with the creation time of the initial
update record. ";
}
description
"List for adaptive periods";
}
description
"Container for adaptive periods.";
}
}
}
}
<CODE ENDS></artwork>
</figure>
</section>
<section title="IANA Considerations">
<section anchor="xml" title="Updates to the IETF XML Registry">
<t>This document registers two URIs in the IETF XML registry
[RFC3688]. Following the format in [RFC3688], the following
registrations are requested to be made:</t>
<figure>
<artwork> ---------------------------------------------------------------------
URI: urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
---------------------------------------------------------------------</artwork>
</figure>
</section>
<section anchor="module"
title="Updates to the YANG Module Names Registry">
<t>This document registers two YANG modules in the YANG Module Names
registry [RFC7950]. . Following the format in [RFC6020], the following
registration has been made:</t>
<figure>
<artwork> ---------------------------------------------------------------------
Name: ietf-adaptive-subscription
Namespace: urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription
Prefix: as
Reference: RFC xxxx
---------------------------------------------------------------------</artwork>
</figure>
</section>
</section>
<section anchor="security" title="Security Considerations">
<t>The YANG module specified in this document defines a schema for data
that is designed to be accessed via network management protocols such as
NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the
secure transport layer, and the mandatory-to-implement secure transport
is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and
the mandatory-to-implement secure transport is TLS [RFC8446].</t>
<t>The NETCONF Configuration Access Control Model (NACM) [RFC8341]
provides the means to restrict access for particular NETCONF or RESTCONF
users to a preconfigured subset of all available NETCONF or RESTCONF
protocol operations and content.</t>
<t>There are a number of data nodes defined in this YANG module that are
writable/creatable/deletable (i.e., config true, which is the default).
These data nodes may be considered sensitive in some network
environments. Write operations (e.g., edit-config) to these data nodes
without proper protection can have a negative effect on network
operations. These are the subtrees and data nodes and their
sensitivity/vulnerability:<list style="symbols">
<t>/sn:subscriptions/sn:subscription/yp:update-trigger/adaptive-periods/adaptive-period/id</t>
<t>/sn:subscriptions/sn:subscription/yp:update-trigger/adaptive-periods/adaptive-period/interval</t>
</list></t>
</section>
<!---->
</middle>
<back>
<references title="Normative References">
<?rfc include="reference.RFC.2119.xml"?>
<?rfc include="reference.RFC.8174.xml"?>
<?rfc include="reference.RFC.7950.xml"?>
<?rfc include="reference.RFC.8342.xml"?>
<?rfc include="reference.RFC.8407.xml"?>
<?rfc include="reference.RFC.8126.xml"?>
<?rfc include="reference.RFC.8040.xml"?>
<?rfc include="reference.RFC.6241.xml"?>
<?rfc include="reference.RFC.6242.xml"?>
<?rfc include="reference.RFC.8341.xml"?>
<?rfc include="reference.RFC.8446.xml"?>
<?rfc include="reference.RFC.8641.xml"?>
</references>
<references title="Informative References">
<?rfc include="reference.RFC.3688.xml"?>
<?rfc include="reference.RFC.6020.xml"?>
<?rfc include="reference.RFC.8340.xml"?>
</references>
<section title="Adaptive Subscription Example">
<t>The example YANG module used in this document represents performance
data telemetry on a simple optical device. The collector can control the
rate of telemtry data to be streamed to the destination by switching to
different time interval for the update to be sent.</t>
<t>YANG tree diagram for the "example-opticalbox-telemetry"
module:<figure>
<artwork> module example-opticalbox-telemetry {
namespace "tag:ietf:example:opticalbox";
prefix "optibox";
container opticalstat {
leaf transmit-power {
description "Transmit optical power reading";
type int;
config false;
}
leaf receiving-power {
description " Receiving optical power reading";
type int;
config false;
}
leaf power-threhold {
description "Optical Power Threshold";
type int;
}
leaf high-voltage {
description "High voltage threshold";
type int;
}
leaf low-voltage {
description "Low voltage threshold";
type int;
}
leaf voltage {
description "current voltage reading";
type int;
config false;
}
leaf current-temperature {
description "Current temperature reading";
type int;
config false;
}
leaf cup-usage {
type uint32;
config false;
}
}
}</artwork>
</figure></t>
<t>The adaptive subscription model can be used to keep track of
performance data change such as temperature, voltage, power,cup usage.
In addition, it can adjust update period based on performance data
change, e.g., when the current receiving power is higher than the
pre-configured threshold, the notification for the optical performance
data from publisher can be sent at a low frequency. When the current
receiving power is lower than the pre-configured threshold, the
notification for the optical performance data can be sent at a high
frequency.</t>
<figure>
<artwork><netconf:rpc message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"
xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<yp:datastore
xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">
ds:operational
</yp:datastore>
<yp:datastore-xpath-filter
xmlns:ex="https://example.com/sample-data/1.0">
/ex:foo
</yp:datastore-xpath-filter>
<as:adaptive-periods>
<as:adaptive-period>
<as:id>01</as:id>
<as:op-field>/opticalstat/current-voltage</as:op-field>
<as:op-value>60</as:op-value>
<as:operator>greater</as:operator>
<as:period>500</as:period>
</as:adaptive-period>
<as:adaptive-period>
<as:id>02</as:id>
<as:op-field>/opticalstat/current-voltage</as:op-field>
<as:op-value>60</as:op-value>
<as:operator>less-or-equal</as:operator>
<as:period>100</as:period>
</as:adaptive-period>
</yp:adaptive-periods>
</establish-subscription>
</netconf:rpc></artwork>
</figure>
<t>In another example, when the time interval for update to be sent is
set to 5 seconds and specific performance data,e.g., 5 receiving power
values (0.48dB、0.57dB、0.61dB、0.69dB、0.70dB)
can be sampled per second and collected during this time interval
changes. When power changes exceed the preconfigured threhold
(e.g.,0.20dB), all these 5 receiving power values falling within
detection time window or update time interval should be published to the
destinations for data analysis.</t>
</section>
</back>
</rfc>