gerrit.o-ran-sc Code Review - scp/oam/modeling.git/blob - data-model/yang/published/ietf/ietf-subscribed-notifications@2019-09-09.yang

1 module ietf-subscribed-notifications {

2 yang-version 1.1;

3 namespace "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications";

4 prefix sn;

6 import ietf-inet-types {

7 prefix inet;

8 reference

9 "RFC 6991: Common YANG Data Types";

10 }

11 import ietf-interfaces {

12 prefix if;

13 reference

14 "RFC 8343: A YANG Data Model for Interface Management";

15 }

16 import ietf-netconf-acm {

17 prefix nacm;

18 reference

19 "RFC 8341: Network Configuration Access Control Model";

20 }

21 import ietf-network-instance {

22 prefix ni;

23 reference

24 "RFC 8529: YANG Data Model for Network Instances";

25 }

26 import ietf-restconf {

27 prefix rc;

28 reference

29 "RFC 8040: RESTCONF Protocol";

30 }

31 import ietf-yang-types {

32 prefix yang;

33 reference

34 "RFC 6991: Common YANG Data Types";

35 }

37 organization

38 "IETF NETCONF (Network Configuration) Working Group";

39 contact

40 "WG Web: <https:/datatracker.ietf.org/wg/netconf/>

41 WG List: <mailto:netconf@ietf.org>

42 Author: Alexander Clemm

43 <mailto:ludwig@clemm.org>

44 Author: Eric Voit

45 <mailto:evoit@cisco.com>

46 Author: Alberto Gonzalez Prieto

47 <mailto:alberto.gonzalez@microsoft.com>

48 Author: Einar Nilsen-Nygaard

49 <mailto:einarnn@cisco.com>

50 Author: Ambika Prasad Tripathy

51 <mailto:ambtripa@cisco.com>";

52 description

53 "This module defines a YANG data model for subscribing to event

54 records and receiving matching content in notification messages.

55 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL

56 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',

57 'MAY', and 'OPTIONAL' in this document are to be interpreted as

58 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,

59 they appear in all capitals, as shown here.

62 Redistribution and use in source and binary forms, with or

63 without modification, is permitted pursuant to, and subject to

64 the license terms contained in, the Simplified BSD License set

65 forth in Section 4.c of the IETF Trust's Legal Provisions

66 Relating to IETF Documents

67 (https://trustee.ietf.org/license-info).

68 This version of this YANG module is part of RFC 8639; see the

69 RFC itself for full legal notices.";

71 revision 2019-09-09 {

72 description

73 "Initial version.";

74 reference

75 "RFC 8639: A YANG Data Model for Subscriptions to

76 Event Notifications";

77 }

79 /*

80 * FEATURES

81 */

83 feature configured {

84 description

85 "This feature indicates that configuration of subscriptions is

86 supported.";

87 }

89 feature dscp {

90 description

91 "This feature indicates that a publisher supports the ability

92 to set the Differentiated Services Code Point (DSCP) value in

93 outgoing packets.";

94 }

96 feature encode-json {

97 description

98 "This feature indicates that JSON encoding of notification

99 messages is supported.";

100 }

101

102 feature encode-xml {

103 description

104 "This feature indicates that XML encoding of notification

105 messages is supported.";

106 }

107

108 feature interface-designation {

109 description

110 "This feature indicates that a publisher supports sourcing all

111 receiver interactions for a configured subscription from a

112 single designated egress interface.";

113 }

114

115 feature qos {

116 description

117 "This feature indicates that a publisher supports absolute

118 dependencies of one subscription's traffic over another

119 as well as weighted bandwidth sharing between subscriptions.

120 Both of these are Quality of Service (QoS) features that allow

121 differentiated treatment of notification messages between a

122 publisher and a specific receiver.";

123 }

124

125 feature replay {

126 description

127 "This feature indicates that historical event record replay is

128 supported. With replay, it is possible for past event records

129 to be streamed in chronological order.";

130 }

131

132 feature subtree {

133 description

134 "This feature indicates support for YANG subtree filtering.";

135 reference

136 "RFC 6241: Network Configuration Protocol (NETCONF),

137 Section 6";

138 }

139

140 feature supports-vrf {

141 description

142 "This feature indicates that a publisher supports VRF

143 configuration for configured subscriptions. VRF support for

144 dynamic subscriptions does not require this feature.";

145 reference

146 "RFC 8529: YANG Data Model for Network Instances,

147 Section 6";

148 }

149

150 feature xpath {

151 description

152 "This feature indicates support for XPath filtering.";

153 reference

154 "XML Path Language (XPath) Version 1.0

155 (https://www.w3.org/TR/1999/REC-xpath-19991116)";

156 }

157

158 /*

159 * EXTENSIONS

160 */

161

162 extension subscription-state-notification {

163 description

164 "This statement applies only to notifications. It indicates

165 that the notification is a subscription state change

166 notification. Therefore, it does not participate in a regular

167 event stream and does not need to be specifically subscribed

168 to in order to be received. This statement can only occur as

169 a substatement of the YANG 'notification' statement. This

170 statement is not for use outside of this YANG module.";

171 }

172

173 /*

174 * IDENTITIES

175 */

176 /* Identities for RPC and notification errors */

177

178 identity delete-subscription-error {

179 description

180 "Base identity for the problem found while attempting to

181 fulfill either a 'delete-subscription' RPC request or a

182 'kill-subscription' RPC request.";

183 }

184

185 identity establish-subscription-error {

186 description

187 "Base identity for the problem found while attempting to

188 fulfill an 'establish-subscription' RPC request.";

189 }

190

191 identity modify-subscription-error {

192 description

193 "Base identity for the problem found while attempting to

194 fulfill a 'modify-subscription' RPC request.";

195 }

196

197 identity subscription-suspended-reason {

198 description

199 "Base identity for the problem condition communicated to a

200 receiver as part of a 'subscription-suspended'

201 notification.";

202 }

203

204 identity subscription-terminated-reason {

205 description

206 "Base identity for the problem condition communicated to a

207 receiver as part of a 'subscription-terminated'

208 notification.";

209 }

210

211 identity dscp-unavailable {

212 base establish-subscription-error;

213 if-feature "dscp";

214 description

215 "The publisher is unable to mark notification messages with

216 prioritization information in a way that will be respected

217 during network transit.";

218 }

219

220 identity encoding-unsupported {

221 base establish-subscription-error;

222 description

223 "Unable to encode notification messages in the desired

224 format.";

225 }

226

227 identity filter-unavailable {

228 base subscription-terminated-reason;

229 description

230 "Referenced filter does not exist. This means a receiver is

231 referencing a filter that doesn't exist or to which it

232 does not have access permissions.";

233 }

234

235 identity filter-unsupported {

236 base establish-subscription-error;

237 base modify-subscription-error;

238 description

239 "Cannot parse syntax in the filter. This failure can be from

240 a syntax error or a syntax too complex to be processed by the

241 publisher.";

242 }

243

244 identity insufficient-resources {

245 base establish-subscription-error;

246 base modify-subscription-error;

247 base subscription-suspended-reason;

248 description

249 "The publisher does not have sufficient resources to support

250 the requested subscription. An example might be that

251 allocated CPU is too limited to generate the desired set of

252 notification messages.";

253 }

254

255 identity no-such-subscription {

256 base modify-subscription-error;

257 base delete-subscription-error;

258 base subscription-terminated-reason;

259 description

260 "Referenced subscription doesn't exist. This may be as a

261 result of a nonexistent subscription ID, an ID that belongs to

262 another subscriber, or an ID for a configured subscription.";

263 }

264

265 identity replay-unsupported {

266 base establish-subscription-error;

267 if-feature "replay";

268 description

269 "Replay cannot be performed for this subscription. This means

270 the publisher will not provide the requested historic

271 information from the event stream via replay to this

272 receiver.";

273 }

274

275 identity stream-unavailable {

276 base subscription-terminated-reason;

277 description

278 "Not a subscribable event stream. This means the referenced

279 event stream is not available for subscription by the

280 receiver.";

281 }

282

283 identity suspension-timeout {

284 base subscription-terminated-reason;

285 description

286 "Termination of a previously suspended subscription. The

287 publisher has eliminated the subscription, as it exceeded a

288 time limit for suspension.";

289 }

290

291 identity unsupportable-volume {

292 base subscription-suspended-reason;

293 description

294 "The publisher does not have the network bandwidth needed to

295 get the volume of generated information intended for a

296 receiver.";

297 }

298

299 /* Identities for encodings */

300

301 identity configurable-encoding {

302 description

303 "If a transport identity derives from this identity, it means

304 that it supports configurable encodings. An example of a

305 configurable encoding might be a new identity such as

306 'encode-cbor'. Such an identity could use

307 'configurable-encoding' as its base. This would allow a

308 dynamic subscription encoded in JSON (RFC 8259) to request

309 that notification messages be encoded via the Concise Binary

310 Object Representation (CBOR) (RFC 7049). Further details for

311 any specific configurable encoding would be explored in a

312 transport document based on this specification.";

313 reference

314 "RFC 8259: The JavaScript Object Notation (JSON) Data

315 Interchange Format

316 RFC 7049: Concise Binary Object Representation (CBOR)";

317 }

318

319 identity encoding {

320 description

321 "Base identity to represent data encodings.";

322 }

323

324 identity encode-xml {

325 base encoding;

326 if-feature "encode-xml";

327 description

328 "Encode data using XML as described in RFC 7950.";

329 reference

330 "RFC 7950: The YANG 1.1 Data Modeling Language";

331 }

332

333 identity encode-json {

334 base encoding;

335 if-feature "encode-json";

336 description

337 "Encode data using JSON as described in RFC 7951.";

338 reference

339 "RFC 7951: JSON Encoding of Data Modeled with YANG";

340 }

341

342 /* Identities for transports */

343

344 identity transport {

345 description

346 "An identity that represents the underlying mechanism for

347 passing notification messages.";

348 }

349

350 /*

351 * TYPEDEFs

352 */

353

354 typedef encoding {

355 type identityref {

356 base encoding;

357 }

358 description

359 "Specifies a data encoding, e.g., for a data subscription.";

360 }

361

362 typedef stream-filter-ref {

363 type leafref {

364 path "/sn:filters/sn:stream-filter/sn:name";

365 }

366 description

367 "This type is used to reference an event stream filter.";

368 }

369

370 typedef stream-ref {

371 type leafref {

372 path "/sn:streams/sn:stream/sn:name";

373 }

374 description

375 "This type is used to reference a system-provided

376 event stream.";

377 }

378

379 typedef subscription-id {

380 type uint32;

381 description

382 "A type for subscription identifiers.";

383 }

384

385 typedef transport {

386 type identityref {

387 base transport;

388 }

389 description

390 "Specifies the transport used to send notification messages

391 to a receiver.";

392 }

393

394 /*

395 * GROUPINGS

396 */

397

398 grouping stream-filter-elements {

399 description

400 "This grouping defines the base for filters applied to event

401 streams.";

402 choice filter-spec {

403 description

404 "The content filter specification for this request.";

405 anydata stream-subtree-filter {

406 if-feature "subtree";

407 description

408 "Event stream evaluation criteria encoded in the syntax of

409 a subtree filter as defined in RFC 6241, Section 6.

410 The subtree filter is applied to the representation of

411 individual, delineated event records as contained in the

412 event stream.

413 If the subtree filter returns a non-empty node set, the

414 filter matches the event record, and the event record is

415 included in the notification message sent to the

416 receivers.";

417 reference

418 "RFC 6241: Network Configuration Protocol (NETCONF),

419 Section 6";

420 }

421 leaf stream-xpath-filter {

422 if-feature "xpath";

423 type yang:xpath1.0;

424 description

425 "Event stream evaluation criteria encoded in the syntax of

426 an XPath 1.0 expression.

427 The XPath expression is evaluated on the representation of

428 individual, delineated event records as contained in

429 the event stream.

430 The result of the XPath expression is converted to a

431 boolean value using the standard XPath 1.0 rules. If the

432 boolean value is 'true', the filter matches the event

433 record, and the event record is included in the

434 notification message sent to the receivers.

435 The expression is evaluated in the following XPath

436 context:

437 o The set of namespace declarations is the set of

438 prefix and namespace pairs for all YANG modules

439 implemented by the server, where the prefix is the

440 YANG module name and the namespace is as defined by

441 the 'namespace' statement in the YANG module.

442 If the leaf is encoded in XML, all namespace

443 declarations in scope on the 'stream-xpath-filter'

444 leaf element are added to the set of namespace

445 declarations. If a prefix found in the XML is

446 already present in the set of namespace

447 declarations, the namespace in the XML is used.

448 o The set of variable bindings is empty.

449 o The function library is comprised of the core

450 function library and the XPath functions defined in

451 Section 10 in RFC 7950.

452 o The context node is the root node.";

453 reference

454 "XML Path Language (XPath) Version 1.0

455 (https://www.w3.org/TR/1999/REC-xpath-19991116)

456 RFC 7950: The YANG 1.1 Data Modeling Language,

457 Section 10";

458 }

459 }

460 }

461

462 grouping update-qos {

463 description

464 "This grouping describes QoS information concerning a

465 subscription. This information is passed to lower layers

466 for transport prioritization and treatment.";

467 leaf dscp {

468 if-feature "dscp";

469 type inet:dscp;

470 default "0";

471 description

472 "The desired network transport priority level. This is the

473 priority set on notification messages encapsulating the

474 results of the subscription. This transport priority is

475 shared for all receivers of a given subscription.";

476 }

477 leaf weighting {

478 if-feature "qos";

479 type uint8 {

480 range "0 .. 255";

481 }

482 description

483 "Relative weighting for a subscription. Larger weights get

484 more resources. Allows an underlying transport layer to

485 perform informed load-balance allocations between various

486 subscriptions.";

487 reference

488 "RFC 7540: Hypertext Transfer Protocol Version 2 (HTTP/2),

489 Section 5.3.2";

490 }

491 leaf dependency {

492 if-feature "qos";

493 type subscription-id;

494 description

495 "Provides the 'subscription-id' of a parent subscription.

496 The parent subscription has absolute precedence should

497 that parent have push updates ready to egress the publisher.

498 In other words, there should be no streaming of objects from

499 the current subscription if the parent has something ready

500 to push.

501 If a dependency is asserted via configuration or via an RPC

502 but the referenced 'subscription-id' does not exist, the

503 dependency is silently discarded. If a referenced

504 subscription is deleted, this dependency is removed.";

505 reference

506 "RFC 7540: Hypertext Transfer Protocol Version 2 (HTTP/2),

507 Section 5.3.1";

508 }

509 }

510

511 grouping subscription-policy-modifiable {

512 description

513 "This grouping describes all objects that may be changed

514 in a subscription.";

515 choice target {

516 mandatory true;

517 description

518 "Identifies the source of information against which a

519 subscription is being applied as well as specifics on the

520 subset of information desired from that source.";

521 case stream {

522 choice stream-filter {

523 description

524 "An event stream filter can be applied to a subscription.

525 That filter will either come referenced from a global

526 list or be provided in the subscription itself.";

527 case by-reference {

528 description

529 "Apply a filter that has been configured separately.";

530 leaf stream-filter-name {

531 type stream-filter-ref;

532 mandatory true;

533 description

534 "References an existing event stream filter that is

535 to be applied to an event stream for the

536 subscription.";

537 }

538 }

539 case within-subscription {

540 description

541 "A local definition allows a filter to have the same

542 lifecycle as the subscription.";

543 uses stream-filter-elements;

544 }

545 }

546 }

547 }

548 leaf stop-time {

549 type yang:date-and-time;

550 description

551 "Identifies a time after which notification messages for a

552 subscription should not be sent. If 'stop-time' is not

553 present, the notification messages will continue until the

554 subscription is terminated. If 'replay-start-time' exists,

555 'stop-time' must be for a subsequent time. If

556 'replay-start-time' doesn't exist, 'stop-time', when

557 established, must be for a future time.";

558 }

559 }

560

561 grouping subscription-policy-dynamic {

562 description

563 "This grouping describes the only information concerning a

564 subscription that can be passed over the RPCs defined in this

565 data model.";

566 uses subscription-policy-modifiable {

567 augment "target/stream" {

568 description

569 "Adds additional objects that can be modified by an RPC.";

570 leaf stream {

571 type stream-ref {

572 require-instance false;

573 }

574 mandatory true;

575 description

576 "Indicates the event stream to be considered for

577 this subscription.";

578 }

579 leaf replay-start-time {

580 if-feature "replay";

581 type yang:date-and-time;

582 config false;

583 description

584 "Used to trigger the 'replay' feature for a dynamic

585 subscription, where event records that are selected

586 need to be at or after the specified starting time. If

587 'replay-start-time' is not present, this is not a replay

588 subscription and event record push should start

589 immediately. It is never valid to specify start times

590 that are later than or equal to the current time.";

591 }

592 }

593 }

594 uses update-qos;

595 }

596

597 grouping subscription-policy {

598 description

599 "This grouping describes the full set of policy information

600 concerning both dynamic and configured subscriptions, with the

601 exclusion of both receivers and networking information

602 specific to the publisher, such as what interface should be

603 used to transmit notification messages.";

604 uses subscription-policy-dynamic;

605 leaf transport {

606 if-feature "configured";

607 type transport;

608 description

609 "For a configured subscription, this leaf specifies the

610 transport used to deliver messages destined for all

611 receivers of that subscription.";

612 }

613 leaf encoding {

614 when 'not(../transport) or derived-from(../transport,

615 "sn:configurable-encoding")';

616 type encoding;

617 description

618 "The type of encoding for notification messages. For a

619 dynamic subscription, if not included as part of an

620 'establish-subscription' RPC, the encoding will be populated

621 with the encoding used by that RPC. For a configured

622 subscription, if not explicitly configured, the encoding

623 will be the default encoding for an underlying transport.";

624 }

625 leaf purpose {

626 if-feature "configured";

627 type string;

628 description

629 "Open text allowing a configuring entity to embed the

630 originator or other specifics of this subscription.";

631 }

632 }

633

634 /*

635 * RPCs

636 */

637

638 rpc establish-subscription {

639 description

640 "This RPC allows a subscriber to create (and possibly

641 negotiate) a subscription on its own behalf. If successful,

642 the subscription remains in effect for the duration of the

643 subscriber's association with the publisher or until the

644 subscription is terminated. If an error occurs or the

645 publisher cannot meet the terms of a subscription, an RPC

646 error is returned, and the subscription is not created.

647 In that case, the RPC reply's 'error-info' MAY include

648 suggested parameter settings that would have a higher

649 likelihood of succeeding in a subsequent

650 'establish-subscription' request.";

651 input {

652 uses subscription-policy-dynamic;

653 leaf encoding {

654 type encoding;

655 description

656 "The type of encoding for the subscribed data. If not

657 included as part of the RPC, the encoding MUST be set by

658 the publisher to be the encoding used by this RPC.";

659 }

660 }

661 output {

662 leaf id {

663 type subscription-id;

664 mandatory true;

665 description

666 "Identifier used for this subscription.";

667 }

668 leaf replay-start-time-revision {

669 if-feature "replay";

670 type yang:date-and-time;

671 description

672 "If a replay has been requested, this object represents

673 the earliest time covered by the event buffer for the

674 requested event stream. The value of this object is the

675 'replay-log-aged-time' if it exists. Otherwise, it is

676 the 'replay-log-creation-time'. All buffered event

677 records after this time will be replayed to a receiver.

678 This object will only be sent if the starting time has

679 been revised to be later than the time requested by the

680 subscriber.";

681 }

682 }

683 }

684

685 rc:yang-data establish-subscription-stream-error-info {

686 container establish-subscription-stream-error-info {

687 description

688 "If any 'establish-subscription' RPC parameters are

689 unsupportable against the event stream, a subscription

690 is not created and the RPC error response MUST indicate the

691 reason why the subscription failed to be created. This

692 yang-data MAY be inserted as structured data in a

693 subscription's RPC error response to indicate the reason for

694 the failure. This yang-data MUST be inserted if hints are

695 to be provided back to the subscriber.";

696 leaf reason {

697 type identityref {

698 base establish-subscription-error;

699 }

700 description

701 "Indicates the reason why the subscription has failed to

702 be created to a targeted event stream.";

703 }

704 leaf filter-failure-hint {

705 type string;

706 description

707 "Information describing where and/or why a provided

708 filter was unsupportable for a subscription. The

709 syntax and semantics of this hint are

710 implementation specific.";

711 }

712 }

713 }

714

715 rpc modify-subscription {

716 description

717 "This RPC allows a subscriber to modify a dynamic

718 subscription's parameters. If successful, the changed

719 subscription parameters remain in effect for the duration of

720 the subscription, until the subscription is again modified, or

721 until the subscription is terminated. In the case of an error

722 or an inability to meet the modified parameters, the

723 subscription is not modified and the original subscription

724 parameters remain in effect. In that case, the RPC error MAY

725 include 'error-info' suggested parameter hints that would have

726 a high likelihood of succeeding in a subsequent

727 'modify-subscription' request. A successful

728 'modify-subscription' will return a suspended subscription to

729 the 'active' state.";

730 input {

731 leaf id {

732 type subscription-id;

733 mandatory true;

734 description

735 "Identifier to use for this subscription.";

736 }

737 uses subscription-policy-modifiable;

738 }

739 }

740

741 rc:yang-data modify-subscription-stream-error-info {

742 container modify-subscription-stream-error-info {

743 description

744 "This yang-data MAY be provided as part of a subscription's

745 RPC error response when there is a failure of a

746 'modify-subscription' RPC that has been made against an

747 event stream. This yang-data MUST be used if hints are to

748 be provided back to the subscriber.";

749 leaf reason {

750 type identityref {

751 base modify-subscription-error;

752 }

753 description

754 "Information in a 'modify-subscription' RPC error response

755 that indicates the reason why the subscription to an event

756 stream has failed to be modified.";

757 }

758 leaf filter-failure-hint {

759 type string;

760 description

761 "Information describing where and/or why a provided

762 filter was unsupportable for a subscription. The syntax

763 and semantics of this hint are

764 implementation specific.";

765 }

766 }

767 }

768

769 rpc delete-subscription {

770 description

771 "This RPC allows a subscriber to delete a subscription that

772 was previously created by that same subscriber using the

773 'establish-subscription' RPC.

774 If an error occurs, the server replies with an 'rpc-error'

775 where the 'error-info' field MAY contain a

776 'delete-subscription-error-info' structure.";

777 input {

778 leaf id {

779 type subscription-id;

780 mandatory true;

781 description

782 "Identifier of the subscription that is to be deleted.

783 Only subscriptions that were created using

784 'establish-subscription' from the same origin as this RPC

785 can be deleted via this RPC.";

786 }

787 }

788 }

789

790 rpc kill-subscription {

791 nacm:default-deny-all;

792 description

793 "This RPC allows an operator to delete a dynamic subscription

794 without restrictions on the originating subscriber or

795 underlying transport session.

796 If an error occurs, the server replies with an 'rpc-error'

797 where the 'error-info' field MAY contain a

798 'delete-subscription-error-info' structure.";

799 input {

800 leaf id {

801 type subscription-id;

802 mandatory true;

803 description

804 "Identifier of the subscription that is to be deleted.

805 Only subscriptions that were created using

806 'establish-subscription' can be deleted via this RPC.";

807 }

808 }

809 }

810

811 rc:yang-data delete-subscription-error-info {

812 container delete-subscription-error-info {

813 description

814 "If a 'delete-subscription' RPC or a 'kill-subscription' RPC

815 fails, the subscription is not deleted and the RPC error

816 response MUST indicate the reason for this failure. This

817 yang-data MAY be inserted as structured data in a

818 subscription's RPC error response to indicate the reason

819 for the failure.";

820 leaf reason {

821 type identityref {

822 base delete-subscription-error;

823 }

824 mandatory true;

825 description

826 "Indicates the reason why the subscription has failed to be

827 deleted.";

828 }

829 }

830 }

831

832 /*

833 * NOTIFICATIONS

834 */

835

836 notification replay-completed {

837 sn:subscription-state-notification;

838 if-feature "replay";

839 description

840 "This notification is sent to indicate that all of the replay

841 notifications have been sent.";

842 leaf id {

843 type subscription-id;

844 mandatory true;

845 description

846 "This references the affected subscription.";

847 }

848 }

849

850 notification subscription-completed {

851 sn:subscription-state-notification;

852 if-feature "configured";

853 description

854 "This notification is sent to indicate that a subscription has

855 finished passing event records, as the 'stop-time' has been

856 reached.";

857 leaf id {

858 type subscription-id;

859 mandatory true;

860 description

861 "This references the gracefully completed subscription.";

862 }

863 }

864

865 notification subscription-modified {

866 sn:subscription-state-notification;

867 description

868 "This notification indicates that a subscription has been

869 modified. Notification messages sent from this point on will

870 conform to the modified terms of the subscription. For

871 completeness, this subscription state change notification

872 includes both modified and unmodified aspects of a

873 subscription.";

874 leaf id {

875 type subscription-id;

876 mandatory true;

877 description

878 "This references the affected subscription.";

879 }

880 uses subscription-policy {

881 refine "target/stream/stream-filter/within-subscription" {

882 description

883 "Filter applied to the subscription. If the

884 'stream-filter-name' is populated, the filter in the

885 subscription came from the 'filters' container.

886 Otherwise, it is populated in-line as part of the

887 subscription.";

888 }

889 }

890 }

891

892 notification subscription-resumed {

893 sn:subscription-state-notification;

894 description

895 "This notification indicates that a subscription that had

896 previously been suspended has resumed. Notifications will

897 once again be sent. In addition, a 'subscription-resumed'

898 indicates that no modification of parameters has occurred

899 since the last time event records have been sent.";

900 leaf id {

901 type subscription-id;

902 mandatory true;

903 description

904 "This references the affected subscription.";

905 }

906 }

907

908 notification subscription-started {

909 sn:subscription-state-notification;

910 if-feature "configured";

911 description

912 "This notification indicates that a subscription has started

913 and notifications will now be sent.";

914 leaf id {

915 type subscription-id;

916 mandatory true;

917 description

918 "This references the affected subscription.";

919 }

920 uses subscription-policy {

921 refine "target/stream/replay-start-time" {

922 description

923 "Indicates the time that a replay is using for the

924 streaming of buffered event records. This will be

925 populated with the most recent of the following:

926 the event time of the previous event record sent to a

927 receiver, the 'replay-log-creation-time', the

928 'replay-log-aged-time', or the most recent publisher

929 boot time.";

930 }

931 refine "target/stream/stream-filter/within-subscription" {

932 description

933 "Filter applied to the subscription. If the

934 'stream-filter-name' is populated, the filter in the

935 subscription came from the 'filters' container.

936 Otherwise, it is populated in-line as part of the

937 subscription.";

938 }

939 augment "target/stream" {

940 description

941 "This augmentation adds additional parameters specific to a

942 'subscription-started' notification.";

943 leaf replay-previous-event-time {

944 when '../replay-start-time';

945 if-feature "replay";

946 type yang:date-and-time;

947 description

948 "If there is at least one event in the replay buffer

949 prior to 'replay-start-time', this gives the time of

950 the event generated immediately prior to the

951 'replay-start-time'.

952 If a receiver previously received event records for

953 this configured subscription, it can compare this time

954 to the last event record previously received. If the

955 two are not the same (perhaps due to a reboot), then a

956 dynamic replay can be initiated to acquire any missing

957 event records.";

958 }

959 }

960 }

961 }

962

963 notification subscription-suspended {

964 sn:subscription-state-notification;

965 description

966 "This notification indicates that a suspension of the

967 subscription by the publisher has occurred. No further

968 notifications will be sent until the subscription resumes.

969 This notification shall only be sent to receivers of a

970 subscription; it does not constitute a general-purpose

971 notification.";

972 leaf id {

973 type subscription-id;

974 mandatory true;

975 description

976 "This references the affected subscription.";

977 }

978 leaf reason {

979 type identityref {

980 base subscription-suspended-reason;

981 }

982 mandatory true;

983 description

984 "Identifies the condition that resulted in the suspension.";

985 }

986 }

987

988 notification subscription-terminated {

989 sn:subscription-state-notification;

990 description

991 "This notification indicates that a subscription has been

992 terminated.";

993 leaf id {

994 type subscription-id;

995 mandatory true;

996 description

997 "This references the affected subscription.";

998 }

999 leaf reason {

1000 type identityref {

1001 base subscription-terminated-reason;

1002 }

1003 mandatory true;

1004 description

1005 "Identifies the condition that resulted in the termination.";

1006 }

1007 }

1008

1009 /*

1010 * DATA NODES

1011 */

1012

1013 container streams {

1014 config false;

1015 description

1016 "Contains information on the built-in event streams provided by

1017 the publisher.";

1018 list stream {

1019 key "name";

1020 description

1021 "Identifies the built-in event streams that are supported by

1022 the publisher.";

1023 leaf name {

1024 type string;

1025 description

1026 "A handle for a system-provided event stream made up of a

1027 sequential set of event records, each of which is

1028 characterized by its own domain and semantics.";

1029 }

1030 leaf description {

1031 type string;

1032 description

1033 "A description of the event stream, including such

1034 information as the type of event records that are

1035 available in this event stream.";

1036 }

1037 leaf replay-support {

1038 if-feature "replay";

1039 type empty;

1040 description

1041 "Indicates that event record replay is available on this

1042 event stream.";

1043 }

1044 leaf replay-log-creation-time {

1045 when '../replay-support';

1046 if-feature "replay";

1047 type yang:date-and-time;

1048 mandatory true;

1049 description

1050 "The timestamp of the creation of the log used to support

1051 the replay function on this event stream. This time

1052 might be earlier than the earliest available information

1053 contained in the log. This object is updated if the log

1054 resets for some reason.";

1055 }

1056 leaf replay-log-aged-time {

1057 when '../replay-support';

1058 if-feature "replay";

1059 type yang:date-and-time;

1060 description

1061 "The timestamp associated with the last event record that

1062 has been aged out of the log. This timestamp identifies

1063 how far back in history this replay log extends, if it

1064 doesn't extend back to the 'replay-log-creation-time'.

1065 This object MUST be present if replay is supported and any

1066 event records have been aged out of the log.";

1067 }

1068 }

1069 }

1070 container filters {

1071 description

1072 "Contains a list of configurable filters that can be applied to

1073 subscriptions. This facilitates the reuse of complex filters

1074 once defined.";

1075 list stream-filter {

1076 key "name";

1077 description

1078 "A list of preconfigured filters that can be applied to

1079 subscriptions.";

1080 leaf name {

1081 type string;

1082 description

1083 "A name to differentiate between filters.";

1084 }

1085 uses stream-filter-elements;

1086 }

1087 }

1088 container subscriptions {

1089 description

1090 "Contains the list of currently active subscriptions, i.e.,

1091 subscriptions that are currently in effect, used for

1092 subscription management and monitoring purposes. This

1093 includes subscriptions that have been set up via

1094 RPC primitives as well as subscriptions that have been

1095 established via configuration.";

1096 list subscription {

1097 key "id";

1098 description

1099 "The identity and specific parameters of a subscription.

1100 Subscriptions in this list can be created using a control

1101 channel or RPC or can be established through configuration.

1102 If the 'kill-subscription' RPC or configuration operations

1103 are used to delete a subscription, a

1104 'subscription-terminated' message is sent to any active or

1105 suspended receivers.";

1106 leaf id {

1107 type subscription-id;

1108 description

1109 "Identifier of a subscription; unique in a given

1110 publisher.";

1111 }

1112 uses subscription-policy {

1113 refine "target/stream/stream" {

1114 description

1115 "Indicates the event stream to be considered for this

1116 subscription. If an event stream has been removed

1117 and can no longer be referenced by an active

1118 subscription, send a 'subscription-terminated'

1119 notification with 'stream-unavailable' as the reason.

1120 If a configured subscription refers to a nonexistent

1121 event stream, move that subscription to the

1122 'invalid' state.";

1123 }

1124 refine "transport" {

1125 description

1126 "For a configured subscription, this leaf specifies the

1127 transport used to deliver messages destined for all

1128 receivers of that subscription. This object is

1129 mandatory for subscriptions in the configuration

1130 datastore. This object (1) is not mandatory for dynamic

1131 subscriptions in the operational state datastore and

1132 (2) should not be present for other types of dynamic

1133 subscriptions.";

1134 }

1135 augment "target/stream" {

1136 description

1137 "Enables objects to be added to a configured stream

1138 subscription.";

1139 leaf configured-replay {

1140 if-feature "configured";

1141 if-feature "replay";

1142 type empty;

1143 description

1144 "The presence of this leaf indicates that replay for

1145 the configured subscription should start at the

1146 earliest time in the event log or at the publisher

1147 boot time, whichever is later.";

1148 }

1149 }

1150 }

1151 choice notification-message-origin {

1152 if-feature "configured";

1153 description

1154 "Identifies the egress interface on the publisher

1155 from which notification messages are to be sent.";

1156 case interface-originated {

1157 description

1158 "When notification messages are to egress a specific,

1159 designated interface on the publisher.";

1160 leaf source-interface {

1161 if-feature "interface-designation";

1162 type if:interface-ref;

1163 description

1164 "References the interface for notification messages.";

1165 }

1166 }

1167 case address-originated {

1168 description

1169 "When notification messages are to depart from a

1170 publisher using a specific originating address and/or

1171 routing context information.";

1172 leaf source-vrf {

1173 if-feature "supports-vrf";

1174 type leafref {

1175 path "/ni:network-instances/ni:network-instance/ni:name";

1176 }

1177 description

1178 "VRF from which notification messages should egress a

1179 publisher.";

1180 }

1181 leaf source-address {

1182 type inet:ip-address-no-zone;

1183 description

1184 "The source address for the notification messages.

1185 If a source VRF exists but this object doesn't, a

1186 publisher's default address for that VRF must

1187 be used.";

1188 }

1189 }

1190 }

1191 leaf configured-subscription-state {

1192 if-feature "configured";

1193 type enumeration {

1194 enum valid {

1195 value 1;

1196 description

1197 "The subscription is supportable with its current

1198 parameters.";

1199 }

1200 enum invalid {

1201 value 2;

1202 description

1203 "The subscription as a whole is unsupportable with its

1204 current parameters.";

1205 }

1206 enum concluded {

1207 value 3;

1208 description

1209 "A subscription is inactive, as it has hit a

1210 stop time. It no longer has receivers in the

1211 'active' or 'suspended' state, but the subscription

1212 has not yet been removed from configuration.";

1213 }

1214 }

1215 config false;

1216 description

1217 "The presence of this leaf indicates that the subscription

1218 originated from configuration, not through a control

1219 channel or RPC. The value indicates the state of the

1220 subscription as established by the publisher.";

1221 }

1222 container receivers {

1223 description

1224 "Set of receivers in a subscription.";

1225 list receiver {

1226 key "name";

1227 min-elements 1;

1228 description

1229 "A host intended as a recipient for the notification

1230 messages of a subscription. For configured

1231 subscriptions, transport-specific network parameters

1232 (or a leafref to those parameters) may be augmented to a

1233 specific receiver in this list.";

1234 leaf name {

1235 type string;

1236 description

1237 "Identifies a unique receiver for a subscription.";

1238 }

1239 leaf sent-event-records {

1240 type yang:zero-based-counter64;

1241 config false;

1242 description

1243 "The number of event records sent to the receiver. The

1244 count is initialized when a dynamic subscription is

1245 established or when a configured receiver

1246 transitions to the 'valid' state.";

1247 }

1248 leaf excluded-event-records {

1249 type yang:zero-based-counter64;

1250 config false;

1251 description

1252 "The number of event records explicitly removed via

1253 either an event stream filter or an access control

1254 filter so that they are not passed to a receiver.

1255 This count is set to zero each time

1256 'sent-event-records' is initialized.";

1257 }

1258 leaf state {

1259 type enumeration {

1260 enum active {

1261 value 1;

1262 description

1263 "The receiver is currently being sent any

1264 applicable notification messages for the

1265 subscription.";

1266 }

1267 enum suspended {

1268 value 2;

1269 description

1270 "The receiver state is 'suspended', so the

1271 publisher is currently unable to provide

1272 notification messages for the subscription.";

1273 }

1274 enum connecting {

1275 value 3;

1276 if-feature "configured";

1277 description

1278 "A subscription has been configured, but a

1279 'subscription-started' subscription state change

1280 notification needs to be successfully received

1281 before notification messages are sent.

1282 If the 'reset' action is invoked for a receiver of

1283 an active configured subscription, the state

1284 must be moved to 'connecting'.";

1285 }

1286 enum disconnected {

1287 value 4;

1288 if-feature "configured";

1289 description

1290 "A subscription has failed to send a

1291 'subscription-started' state change to the

1292 receiver. Additional connection attempts are not

1293 currently being made.";

1294 }

1295 }

1296 config false;

1297 mandatory true;

1298 description

1299 "Specifies the state of a subscription from the

1300 perspective of a particular receiver. With this

1301 information, it is possible to determine whether a

1302 publisher is currently generating notification

1303 messages intended for that receiver.";

1304 }

1305 action reset {

1306 if-feature "configured";

1307 description

1308 "Allows the reset of this configured subscription's

1309 receiver to the 'connecting' state. This enables the

1310 connection process to be reinitiated.";

1311 output {

1312 leaf time {

1313 type yang:date-and-time;

1314 mandatory true;

1315 description

1316 "Time at which a publisher returned the receiver to

1317 the 'connecting' state.";

1318 }

1319 }

1320 }

1321 }

1322 }

1323 }

1324 }

1325 }