idnits 2.17.1 draft-ietf-netconf-notification-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 2038. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2010. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2017. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2023. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 660 has weird spacing: '...tomated maint...' == Line 768 has weird spacing: '...nically incre...' == Line 1792 has weird spacing: '...ses and filte...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 8, 2006) is 6654 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'NETCONF-PROTO' is mentioned on line 131, but not defined -- Looks like a reference, but probably isn't: '3' on line 164 == Missing Reference: 'Entity-State-MIB' is mentioned on line 650, but not defined == Missing Reference: 'NETCONF-SSH' is mentioned on line 940, but not defined == Missing Reference: 'RFC3877' is mentioned on line 1397, but not defined == Unused Reference: 'NETCONF BEEP' is defined on line 1280, but no explicit reference was found in the text == Unused Reference: 'NETCONF SOAP' is defined on line 1290, but no explicit reference was found in the text == Unused Reference: 'NETCONF SSH' is defined on line 1295, but no explicit reference was found in the text == Unused Reference: 'URI' is defined on line 1300, but no explicit reference was found in the text == Outdated reference: A later version (-12) exists of draft-ietf-netconf-prot-06 == Outdated reference: A later version (-10) exists of draft-ietf-netconf-beep-05 ** Downref: Normative reference to an Historic draft: draft-ietf-netconf-beep (ref. 'NETCONF BEEP') == Outdated reference: A later version (-08) exists of draft-ietf-netconf-soap-05 ** Downref: Normative reference to an Historic draft: draft-ietf-netconf-soap (ref. 'NETCONF SOAP') == Outdated reference: A later version (-06) exists of draft-ietf-netconf-ssh-04 ** Obsolete normative reference: RFC 2396 (ref. 'URI') (Obsoleted by RFC 3986) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' Summary: 7 errors (**), 0 flaws (~~), 17 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group S. Chisholm 2 Internet-Draft K. Curran 3 Expires: July 12, 2006 Nortel 4 H. Trevino 5 Cisco 6 January 8, 2006 8 NETCONF Event Notifications 9 draft-ietf-netconf-notification-00.txt 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on July 12, 2006. 36 Copyright Notice 38 Copyright (C) The Internet Society (2006). 40 Abstract 42 This memo defines a framework for sending asynchronous messages, or 43 event notifications in NETCONF. It defines both the operations 44 necessary to support this concept, and also discusses implications 45 for the mapping to application protocols. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 50 1.1 Definition of Terms . . . . . . . . . . . . . . . . . . . 4 51 1.2 Event Notifications in NETCONF . . . . . . . . . . . . . . 5 52 2. Event-Related Operations . . . . . . . . . . . . . . . . . . . 6 53 2.1 Subscribing to receive Events . . . . . . . . . . . . . . 6 54 2.1.1 create-subscription . . . . . . . . . . . . . . . . . 6 55 2.2 Sending Event Notifications . . . . . . . . . . . . . . . 7 56 2.2.1 Events . . . . . . . . . . . . . . . . . . . . . . . . 7 57 2.3 Changing the Subscription . . . . . . . . . . . . . . . . 8 58 2.3.1 modify-subscription . . . . . . . . . . . . . . . . . 9 59 2.4 Terminating the Subscription . . . . . . . . . . . . . . . 10 60 2.4.1 cancel-subscription . . . . . . . . . . . . . . . . . 10 61 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 11 62 3.1 Capabilities Exchange . . . . . . . . . . . . . . . . . . 11 63 3.2 Querying Subscription Properties . . . . . . . . . . . . . 11 64 3.3 RPC One-way Messages . . . . . . . . . . . . . . . . . . . 14 65 3.4 User-Specified Filters . . . . . . . . . . . . . . . . . . 14 66 3.4.1 Named Profiles . . . . . . . . . . . . . . . . . . . . 15 67 3.4.2 Filtering . . . . . . . . . . . . . . . . . . . . . . 15 68 3.5 Event Classes . . . . . . . . . . . . . . . . . . . . . . 15 69 3.6 Defining Event Notifications . . . . . . . . . . . . . . . 16 70 3.7 Interleaving Messages . . . . . . . . . . . . . . . . . . 16 71 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 18 72 5. Mapping to Application Protocols . . . . . . . . . . . . . . . 23 73 5.1 SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 74 5.2 BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 75 5.2.1 One-way Messages in Beep . . . . . . . . . . . . . . . 24 76 5.3 SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 77 5.3.1 A NETCONF over Soap over HTTP Example . . . . . . . . 25 78 6. Filtering examples . . . . . . . . . . . . . . . . . . . . . . 28 79 6.1 Event Classes . . . . . . . . . . . . . . . . . . . . . . 28 80 6.2 Subtree Filtering . . . . . . . . . . . . . . . . . . . . 28 81 6.3 XPATH filters . . . . . . . . . . . . . . . . . . . . . . 30 82 7. Security Considerations . . . . . . . . . . . . . . . . . . . 32 83 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 84 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 34 85 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 35 87 A. Potential Event Content . . . . . . . . . . . . . . . . . . . 36 88 A.1 Event Identifier . . . . . . . . . . . . . . . . . . . . . 36 89 A.2 Resource Instance . . . . . . . . . . . . . . . . . . . . 36 90 A.3 Event Time . . . . . . . . . . . . . . . . . . . . . . . . 36 91 A.4 Perceived Severity . . . . . . . . . . . . . . . . . . . . 36 92 A.5 Probable Cause . . . . . . . . . . . . . . . . . . . . . . 37 93 A.6 Specific Problem . . . . . . . . . . . . . . . . . . . . . 37 94 A.7 Trend Indication . . . . . . . . . . . . . . . . . . . . . 37 95 A.8 Additional Alarm Text . . . . . . . . . . . . . . . . . . 37 96 A.9 Threshold Identifier . . . . . . . . . . . . . . . . . . . 37 97 A.10 Threshold Type . . . . . . . . . . . . . . . . . . . . . . 38 98 A.11 Observed Value . . . . . . . . . . . . . . . . . . . . . . 38 99 A.12 State Change Information . . . . . . . . . . . . . . . . . 38 100 B. Configuration Event Class Notifications . . . . . . . . . . . 39 101 B.1 Types of Configuration Events . . . . . . . . . . . . . . 39 102 B.2 Config Event Notification Structure . . . . . . . . . . . 40 103 B.3 Configuration Event Content . . . . . . . . . . . . . . . 42 104 B.3.1 Target Datastore . . . . . . . . . . . . . . . . . . . 42 105 B.3.2 User Info . . . . . . . . . . . . . . . . . . . . . . 42 106 B.3.3 Data Source . . . . . . . . . . . . . . . . . . . . . 42 107 B.3.4 Operation . . . . . . . . . . . . . . . . . . . . . . 42 108 B.3.5 Context . . . . . . . . . . . . . . . . . . . . . . . 42 109 B.3.6 Entered Command . . . . . . . . . . . . . . . . . . . 43 110 B.3.7 New Config . . . . . . . . . . . . . . . . . . . . . . 43 111 B.3.8 Old Config . . . . . . . . . . . . . . . . . . . . . . 43 112 B.3.9 Non-netconf commands in configuration notifications . 43 113 B.4 Design Alternative . . . . . . . . . . . . . . . . . . . . 43 114 B.4.1 Server Session Initiation . . . . . . . . . . . . . . 43 115 B.4.2 Establishment . . . . . . . . . . . . . . . . . . . . 44 116 B.4.3 Teardown . . . . . . . . . . . . . . . . . . . . . . . 44 117 B.4.4 Suspend And Resume . . . . . . . . . . . . . . . . . . 45 118 B.4.5 Lifecycle . . . . . . . . . . . . . . . . . . . . . . 45 119 C. NETCONF Event Notifications and Syslog . . . . . . . . . . . . 46 120 C.1 Leveraging Syslog Field Definitions . . . . . . . . . . . 46 121 C.1.1 Field Mapping . . . . . . . . . . . . . . . . . . . . 47 122 C.1.2 Severity Mapping . . . . . . . . . . . . . . . . . . . 48 123 C.2 Syslog within NETCONF Events . . . . . . . . . . . . . . . 48 124 C.2.1 Motivation . . . . . . . . . . . . . . . . . . . . . . 48 125 C.2.2 Embedding syslog messages in a NETCONF Event . . . . . 48 126 C.2.3 Supported Forwarding Options . . . . . . . . . . . . . 49 127 Intellectual Property and Copyright Statements . . . . . . . . 51 129 1. Introduction 131 NETCONF [NETCONF-PROTO] can be conceptually partitioned into four 132 layers: 134 Layer Example 135 +-------------+ +-----------------------------+ 136 | Content | | Configuration data | 137 +-------------+ +-----------------------------+ 138 | | 139 +-------------+ +-----------------------------+ 140 | Operations | | , | 141 +-------------+ +-----------------------------+ 142 | | 143 +-------------+ +-----------------------------+ 144 | RPC | | , | 145 +-------------+ +-----------------------------+ 146 | | 147 +-------------+ +-----------------------------+ 148 | Application | | BEEP, SSH, SSL, console | 149 | Protocol | | | 150 +-------------+ +-----------------------------+ 152 This document defines a framework for sending asynchronous messages, 153 or event notifications in NETCONF. It defines both the operations 154 necessary to support this concept, and also discusses implications 155 for the mapping to application protocols. 157 Figure 1 159 1.1 Definition of Terms 161 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 162 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 163 document are to be interpreted as described in RFC 2119 [3]. 165 Element: An XML Element[XML]. 167 Managed Entity: A node, which supports NETCONF[NETCONF] and has 168 access to management instrumentation. This is also known as the 169 NETCONF server. 171 Managed Object: A collection of one of more Elements that define an 172 abstract thing of interest. 174 1.2 Event Notifications in NETCONF 176 An event is something that happens which may be of interest - a 177 configuration change, a fault, a change in status, crossing a 178 threshold, or an external input to the system, for example. Often 179 this results in an asynchronous message, sometimes referred to as a 180 notification or event notification, being sent out to interested 181 parties to notify them that this event has occurred. 183 This memo defines a mechanism whereby the NETCONF client indicates 184 interest in receiving event notifications from a NETCONF server by 185 creating a subscription to receive event notifications. The NETCONF 186 server replies to indicate whether the subscription request was 187 successful and, if it was successful, begins sending the event 188 notifications to the NETCONF client as the events occur within the 189 system. These event notifications will continue to be sent until 190 either the NETCONF session is terminated or an explicit command to 191 cancel the subscription is sent. The event notification subscription 192 allows a number of options to enable the NETCONF client to specify 193 which events are of interest. These are specified when the 194 subscription is created, but can be modified later using a modify 195 subscription command. 197 2. Event-Related Operations 199 2.1 Subscribing to receive Events 201 The event notification subscription is initiated by the NETCONF 202 client and responded to by the NETCONF server. When the event 203 notification subscription is created, the events of interest are 204 specified. 206 It is possible to create more than one event notification 207 subscription on a single underlying connection. Each event 208 notification subscription therefore has its own unique identifier. 210 Content for an event notification subscription can be selected by 211 specifying which event classes are of interest and /or by applying 212 user-specified filters. 214 2.1.1 create-subscription 216 218 Description: 220 This command initiates an event notification subscription which 221 will send asynchronous event notifications to the initiator of the 222 command until the command is sent. 224 Parameters: 226 Event Classes: 228 An optional parameter that indicates which event classes are of 229 interest. If not present, events of all classes will be sent. 231 Filter: 233 An optional parameter that indicates which subset of all 234 possible events are of interest. The format of this parameter 235 is the same as that of the filter parameter in the NETCONF 236 protocol operations. If not present, all events not precluded 237 by other parameters will be sent. These filter parameters can 238 only be modified using the modify-subscription command. 240 Named Profile 241 An optional parameter that points to a separately defined 242 filter profile. If not present, no additional filtering will 243 be applied. If the separate definition of these filters is 244 updated, then these changes will be reflected in the filtered 245 events on this subscription. 247 Positive Response: 249 If the NETCONF server can satisfy the request, the server sends an 250 element containing a element containing the 251 subscription ID. 253 Negative Response: 255 An element is included within the if the 256 request cannot be completed for any reason. 258 2.2 Sending Event Notifications 260 Once the subscription has been set up, the NETCONF server sends the 261 event notifications asynchronously along the connection. 262 Notifications are tagged with event classes, subscription ID, 263 sequence number, and date and time. 265 2.2.1 Events 267 Events 269 271 Description: 273 An event notification is sent to the initiator of an command asynchronously when an event of interest to 275 them has occurred. An event notification is a complete XML 276 document. 278 Parameters: 280 Event Classes: 282 The event class or classes associated with this event 283 notification 285 Subscription Id: 287 A unique identifier for this event subscription 289 Sequence Number: 291 A sequentially increasing number to uniquely identify event 292 notifications for this subscription. It starts at 0, always 293 increases by just one and rolls back to 0 after its maximum 294 value is reached. 296 Date and Time: 298 The date and time that the event notification was sent by the 299 NETCONF server. 301 Positive Response: 303 No response. 305 Negative Response: 307 No response. 309 2.2.1.1 Event Notification 311 The NETCONF Event notification structure is shown in the following 312 figure. 314 _____________ 315 |RPC-Header|| 316 |__________|| 317 |message-id|| 318 |__________|| 319 ____________________________________________________________________ 320 || Event Header || Data | 321 ||__________________________________________________________||______| 322 || subscriptionId| eventClasses| sequenceNumber| dataAndTime|| | 323 ||_______________|_____________|_______________|____________||______| 325 2.3 Changing the Subscription 327 After an event notification subscription has been established, the 328 NETCONF client can initiate a request to change properties of the 329 event notification subscription. This prevents loss of event 330 notifications that might otherwise occur during a tear down and 331 recreation of the event notification subscription. This command is 332 responded to by the NETCONF server 334 2.3.1 modify-subscription 336 338 Description: 340 Change properties of the event notification subscription. 342 Parameters: 344 Subscription Id: 346 A unique identifier for this event subscription. 348 Event Classes: 350 An optional parameter that indicates which Event Classes are of 351 interest. If not present, events of all classes will be sent. 353 Filter: 355 An optional parameter that indicates which subset of all 356 possible events that are of interest. The format is the same 357 filter used for other NETCONF commands. If not present, all 358 events not precluded by other parameters will be sent. These 359 filter parameters can only be modified using the modify- 360 subscription command. 362 Named Profile: 364 An optional parameter that points to separately defined filter 365 profile. If not present, no additional filtering will be 366 applied. If the separate definition of these filters is 367 updated, then these changes will be reflected in the events 368 seen on this subscription. 370 Positive Response: 372 If the NETCONF server was able to satisfy the request, an is sent that includes an element. 375 Negative Response: 377 An element is included within the if the 378 request cannot be completed for any reason. 380 2.4 Terminating the Subscription 382 Closing of the event notification subscription is initiated by the 383 NETCONF client. The specific subscription to be closed is specified 384 using a subscription ID. The NETCONF server responds. Note that the 385 NETCONF session may also be torn down for other reasons and this will 386 also result in the subscription being cancelled, but is not subjected 387 to the behaviour of this command. 389 2.4.1 cancel-subscription 391 393 Description: 395 Tear down the event notification subscription. 397 Parameters: 399 Subscription Id: 401 A unique identifier for this event notification subscription. 403 Positive Response: 405 If the NETCONF server was able to satisfy the request, an is sent that includes an element. 408 Negative Response: 410 An element is included within the if the 411 request cannot be completed for any reason. 413 3. Supporting Concepts 415 3.1 Capabilities Exchange 417 The ability to process and send event notifications is advertised 418 during the capability exchange between the NETCONF client and server. 420 "urn:ietf:params:xml:ns:netconf:notification:1.0" 422 For Example 424 425 426 427 urn:ietf:params:xml:ns:netconf:base:1.0 428 429 430 urn:ietf:params:xml:ns:netconf:capability:startup:1.0 431 432 433 urn:ietf:params:xml:ns:netconf:notification:1.0 434 435 436 4 437 439 3.2 Querying Subscription Properties 441 The following Schema can be used to retrieve information about active 442 event notification subscriptions 444 456 457 458 Schema for reporting on Event Subscriptions 459 460 461 463 NetConf State Schema 464 2005-11-30T09:30:47-05:00 465 466 IETF 467 468 A schema that can be used to learn about current 469 NetConf Event Subscriptions 470 471 472 473 475 477 480 483 484 485 487 489 490 491 The session id associated with this subscription. 492 493 494 496 498 499 500 The subscription id associated with this subscription. 501 502 503 504 505 506 507 The event classes associated with this subscription. 508 509 510 511 512 513 514 515 517 519 520 521 The filters associated with this subscription. 522 523 524 526 528 529 530 The named profile associated with this subscription. 531 Note that the contents of the named profile may have 532 changed since it was last applied 533 534 535 537 539 540 541 The last time this subscription was modified. If it has 542 not been modified since creation, this is the time of 543 subscription creation. 544 545 546 548 550 551 552 A count of event notifications sent along this connection 553 since the subscription was created. 554 555 556 558 560 561 562 The sequence number of the last event notification sent to 563 this subscription 564 565 566 568 569 570 571 572 574 575 576 578 580 3.3 RPC One-way Messages 582 In order to support the concept that each individual event 583 notification is a well-defined XML-document that can be processed 584 without waiting for all events to come in, it makes sense to define 585 events, not as an endless reply to a subscription command, but as 586 independent messages that originate from the NETCONF server. In 587 order to support this model, this memo introduces the concept of a 588 one-way RPC message. 590 The one-way RPC message is similar to the two-way RPC message, except 591 that no response is expected to the command. In the case of event 592 notification, this RPC will originate from the NETCONF server, and 593 not the NETCONF client. 595 3.4 User-Specified Filters 597 Note that when multiple filters are specified, they are applied 598 collectively, so event notifications needs to pass all specified 599 filters in order to be sent to the subscriber. If a filter is 600 specified to look for data of a particular value, and the data item 601 is not present within a particular event for its value to be checked, 602 it will be filtered out. For example, if one were to check for 603 'severity=critical' in a configuration event notification where this 604 field was not supported, then the notification would be filtered out. 606 3.4.1 Named Profiles 608 A named profile is a filter that is created ahead of time and applied 609 at the time an event notification subscription is created or 610 modified. Note that changes to the profile after the subscription 611 has been created will have no effect unless a modify subscription 612 command is issued. Since named profiles exist outside of the 613 subscription, they persist after the subscription has been cancelled. 615 3.4.2 Filtering 617 Just-in-time filtering is explicitly stated when the event 618 notification subscription is created. It can only be changed using 619 the modify subscription command. This is specified via the Filter 620 parameter. Filters only exist as parameters to the subscription. 622 3.5 Event Classes 624 Events can be broadly classified into one more event classes. Each 625 event class identifies a set of event notifications which share 626 important characteristics, such being generated from similar events 627 or sharing much of the same content. 629 The initial set of event classes is fault, configuration, state, 630 audit, data, maintenance, metrics, security, information and 631 heartbeat. 633 A fault event notification is generated when a fault condition (error 634 or warning) occurs. A fault event may result in an alarm. Examples 635 of fault events could be a communications alarm, environmental alarm, 636 equipment alarm, processing error alarm, quality of service alarm, or 637 a threshold crossing event. See RFC3877 and RFC2819 for more 638 information. 640 A configuration event, alternatively known as an inventory event, is 641 used to notify that hardware, software, or a service has been added/ 642 changed/removed. In keeping aligned with NETCONF protocol 643 operations, configuration events may included copy configuration 644 event, delete configuration event, or the edit configuration event 645 (create, delete, merge, replace). 647 A state event indicates a change from one state to another, where a 648 state is a condition or stage in the existence of a managed entity. 649 State change events are seen in many specifications. For Entity 650 state changes, see [Entity-State-MIB] for more information. 652 Audit events provide event of very specific actions within a managed 653 device. In isolation an audit events provides very limited data. A 654 collection of audit information forms an audit trail. 656 A data dump event is an asynchronous event containing information 657 about a system, its configuration, state, etc. 659 A maintenance event signals the beginning, process or end of an 660 action either generated by a manual or automated maintenance action. 662 A metrics event contains a metric or a collection of metrics. This 663 includes performance metrics. 665 A heart beat event is sent periodically to enable testing that the 666 communications channel is still functional. It behaves much like the 667 other event classes, with the exception that implementations may not 668 want to include an event log, if supported. Although widely used 669 throughout the industry, no current corresponding work within the 670 IETF. However, other standards bodies such as the TeleManagement 671 Forum have similar definitions. 673 An Information event is something that happens of interest which is 674 within the expected operational behaviour and not otherwise covered 675 by another class. 677 3.6 Defining Event Notifications 679 Event Notifications are defined ahead of time by defining an XML 680 element and assigning it to particular event classes. This will be 681 done using an "eventClasses" attribute. 683 3.7 Interleaving Messages 685 While each NETCONF message must be a complete XML document, the 686 design of the event system allows for the interleaving of complete 687 asynchronous event notifications with complete synchronous messages. 688 It is possible to still send command-response type messages such as 689 while events are being generated. The only 690 restriction is that each message must be complete 691 The following sequence diagram demonstrates an example NETCONF 692 session where after basic session establishment and capability 693 exchange, NETCONF client (C), subscribes to receive event 694 notifications. The NETCONF server (S), starts sending event 695 notifications as events of interest happen within the system. The 696 NETCONF client decides to change the characteristics of their event 697 subscription so sends a command. Before the 698 NETCONF server, receives this command, another event is generated and 699 the NETCONF server starts to send the event notification. The 700 NETCONF server finishes sending this event notification before 701 processing the command and sending the reply. 703 C S 704 | | 705 | capability exchange | 706 |-------------------------->| 707 |<------------------------->| 708 | | 709 | | 710 |-------------------------->| 711 |<--------------------------| 712 | | 713 | | 714 |<--------------------------| 715 | | 716 | | 717 |<--------------------------| 718 | | 719 | | 720 |-------------------------->| (buffered) 721 | | 722 |<--------------------------| 723 | | 724 |<--------------------------| 726 4. XML Schema for Event Notifications 728 729 736 739 741 742 743 This import accesses the xml: attribute groups for the 744 xml:lang as declared on the error-message element. 745 746 747 749 750 753 755 756 757 758 The unique identifier for this particular subscription within 759 the session. 760 761 762 763 765 766 767 768 A monotonically increasing integer. Starts at 0. 769 Always increases by just one. Roll back to 0 after maximum 770 value is reached. 771 772 773 774 776 777 779 781 783 785 787 789 791 793 795 798 799 800 801 802 804 806 809 810 811 812 813 815 816 817 818 819 820 821 823 825 826 827 828 829 833 836 837 838 839 840 842 844 845 846 847 848 849 850 853 855 856 857 858 859 863 866 867 868 869 870 872 873 874 875 876 880 882 883 884 886 887 888 889 891 892 894 897 898 899 900 901 903 904 906 907 908 909 The date and time that the event notification was 910 sent by the netconf server. 911 913 914 915 916 917 918 919 921 923 5. Mapping to Application Protocols 925 Currently, the NETCONF family of specification allows for running 926 NETCONF over a number of application protocols, some of which support 927 multiple configurations. Some of these options will be better suited 928 for supporting event notifications then others. 930 5.1 SSH 932 Session establishment and two-way messages are based on the NETCONF 933 over SSH transport mapping [NETCONF-SSH] 935 One-way messages are supported as follows: Once the session has been 936 established and capabilities have been exchanged, the server may send 937 complete XML documents to the NETCONF client containing rpc-one-way 938 elements. No response is expected from the NETCONF client. 940 As the other examples in [NETCONF-SSH] illustrate, a special 941 character sequence, MUST be sent by both the client and the server 942 after each XML document in the NETCONF exchange. This character 943 sequence cannot legally appear in an XML document, so it can be 944 unambiguously used to identify the end of the current document in the 945 event notification of an XML syntax or parsing error, allowing 946 resynchronization of the NETCONF exchange. 948 The NETCONF over SSH session to receive an event notification might 949 look like this: 951 952 954 955 123456 956 957 2 958 2000-01-12T12:13:14Z 959 960 Fred Flinstone 961 962 963 964 965 966 967 968 969 Ethernet0/0 970 1500 971 972 973 974 975 976 977 978 979 ]]> 980 ]]> 982 5.2 BEEP 984 Session establishment and two-way messages are based on the NETCONF 985 over BEEP transport mapping NETCONF-BEEP 987 5.2.1 One-way Messages in Beep 989 One-way messages can be supported either by mapping to the existing 990 one-to-many BEEP construct or by creating a new one-to-none 991 construct. 993 This area is for future study. 995 5.2.1.1 One-way messages via the One-to-many Construct 997 Messages in one-to-many exchanges: "rcp", "rpc-one-way", "rpc-reply" 998 Messages in positive replies: "rpc-reply", "rpc-one-way" 1000 5.2.1.2 One-way messages via the One-to-none Construct 1002 Note that this construct would need to be added to an extension or 1003 update to 'The Blocks Extensible Exchange Protocol Core' RFC 3080. 1005 MSG/NoANS: the client sends a "MSG" message, the server, sends no 1006 reply. 1008 In one-to-none exchanges, no reply to the "MSG" message is expected. 1010 5.3 SOAP 1012 Session management and message exchange are based on the NETCONF over 1013 SOAP transport mapping NETCONF-SOAP 1015 Note that the use of "persistent connections" "chunked transfer- 1016 coding" when using HTTP becomes even more important in the supporting 1017 of event notifications 1019 5.3.1 A NETCONF over Soap over HTTP Example 1021 C: POST /netconf HTTP/1.1 1022 C: Host: netconfdevice 1023 C: Content-Type: text/xml; charset=utf-8 1024 C: Accept: application/soap+xml, text/* 1025 C: Cache-Control: no-cache 1026 C: Pragma: no-cache 1027 C: Content-Length: 465 1028 C: 1029 C: 1030 C: 1032 C: 1033 C: 1036 C: 1037 C: 1038 C: 1039 C: 1040 C: 1042 The response: 1044 S: HTTP/1.1 200 OK 1045 S: Content-Type: application/soap+xml; charset=utf-8 1046 S: Content-Length: 917 1047 S: 1048 S: 1049 S: 1051 S: 1052 S: 1054 S: 1055 S: 1057 S: 123456 1058 S: 1059 S: 1060 S: 1061 S: 1062 S: 1064 And then some time later 1066 S: HTTP/1.1 200 OK 1067 S: Content-Type: application/soap+xml; charset=utf-8 1068 S: Content-Length: 917 1069 S: 1070 S: 1071 S: 1073 S: 1074 S: 1076 S: 1077 S: 1078 S: 123456 1079 S: 1080 S: 2 1081 S: 2000-01-12T12:13:14Z 1082 S: 1083 S: Fred Flinstone 1084 S: 1085 S: 1086 S: 1087 S: 1088 S: 1089 S: 1090 S: 1091 S: 1092 S: Ethernet0/0 1093 S: 1500 1094 S: 1095 S: 1096 S: 1097 S: 1098 S: 1099 S: 1100 S: 1101 S: 1102 S: 1103 S: 1104 S: 1106 6. Filtering examples 1108 The following section provides examples to illustrate the various 1109 methods of filtering content on an event notification subscription. 1111 6.1 Event Classes 1113 The following example illustrates selecting all event notifications 1114 for EventClasses fault, state or config 1116 1118 1119 1120 1121 1122 1123 1124 1125 1127 6.2 Subtree Filtering 1129 XML subtree filtering is not well suited for creating elaborate 1130 filter definitions given that it only supports equality comparisons 1131 (e.g. in the event subtree give me all event notifications which have 1132 severity=critical or severity=major or severity=minor). 1133 Nevertheless, it may be used for defining simple notification 1134 forwarding filters as shown below. 1136 The following example illustrates selecting fault EventClass which 1137 have severities of critical, major, or minor. The filtering criteria 1138 evaluation is as follows: 1140 ((fault) & ((severity=critical) | (severity=major) | (severity = 1141 minor))) 1142 1144 1145 1146 1147 1148 1149 1150 1151 critical 1152 1153 1154 major 1155 1156 1157 minor 1158 1159 1160 1161 1162 1164 The following example illustrates selecting fault, state, config 1165 EventClasses which have severities of critical, major, or minor and 1166 come from card Ethernet0. The filtering criteria evaluation is as 1167 follows: 1169 ((fault | state | config) & ((fault & severity=critical) | (fault & 1170 severity=major) | (fault & severity = minor) | (card=Ethernet0))) 1171 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 fault 1183 critical 1184 1185 1186 fault 1187 major 1188 1189 1190 fault 1191 minor 1192 1193 1194 Ethernet0 1195 1196 1197 1198 1199 1201 6.3 XPATH filters 1203 The following example illustrates selecting fault EventClass which 1204 have severities of critical, major, or minor. The filtering criteria 1205 evaluation is as follows: 1207 ((fault) & ((severity=critical) | (severity=major) | (severity = 1208 minor))) 1209 1211 1212 1213 1214 1215 1216 (/event[eventClasses/fault] and 1217 (/event[severity="critical"] or 1218 /event[severity="major"] or /event[severity="minor"])) 1219 1220 1221 1223 The following example illustrates selecting fault, state, config 1224 EventClasses which have severities of critical, major, or minor and 1225 come from card Ethernet0. The filtering criteria evaluation is as 1226 follows: 1228 ((fault | state | config) & ((fault & severity=critical) | (fault & 1229 severity=major) | (fault & severity = minor) | (card=Ethernet0))) 1231 1233 1234 1235 1236 1237 1238 1239 1240 ((/event[eventClasses/fault] or 1241 /event[eventClasses/state] or 1242 /event[eventClasses/config]) and 1243 ( (/event[eventClasses/fault] and 1244 /event[severity="critical"]) or 1245 (/event[eventClasses/fault] and 1246 /event[severity="major"]) or 1247 (/event[eventClasses/fault] and 1248 /event[severity="minor"]) or 1249 /event[card="Ethernet0"])) 1250 1251 1252 1254 7. Security Considerations 1256 To be determined once specific aspects of this solution are better 1257 understood. In particular, the access control framework and the 1258 choice of transport will have a major impact on the security of the 1259 solution 1261 8. IANA Considerations 1263 Event Classes will likely be an IANA-managed resource. The initial 1264 set of values is defined in this specification. 1266 9. Acknowledgements 1268 Thanks to Gilbert Gagnon and Greg Wilbur for providing their input 1269 into the early work on this document. In addition, the editors would 1270 like to acknowledge input at the Vancouver editing session from the 1271 following people: Orly Nicklass, James Bakstrieve, Yoshifumi 1272 Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, Dave 1273 Partain, Ray Atarashi and Dave Perkins. 1275 10. References 1277 [NETCONF] Enns, R., "NETCONF Configuration Protocol", 1278 ID draft-ietf-netconf-prot-06, April 2005. 1280 [NETCONF BEEP] 1281 Lear, E. and K. Crozier, "Using the NETCONF Protocol over 1282 Blocks Extensible Exchange Protocol (BEEP)", 1283 ID draft-ietf-netconf-beep-05, March 2005. 1285 [NETCONF Datamodel] 1286 Chisholm, S. and S. Adwankar, "Framework for NETCONF 1287 Content", ID draft-chisholm-netconf-model-04.txt, 1288 October 2005. 1290 [NETCONF SOAP] 1291 Goddard, T., "Using the Network Configuration Protocol 1292 (NETCONF) Over the Simple Object Access Protocol (SOAP)", 1293 ID draft-ietf-netconf-soap-05, April 2005. 1295 [NETCONF SSH] 1296 Wasserman, M. and T. Goddard, "Using the NETCONF 1297 Configuration Protocol over Secure Shell (SSH)", 1298 ID draft-ietf-netconf-ssh-04.txt, April 2005. 1300 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1301 Resource Identifiers (URI): Generic Syntax", RFC 2396, 1302 August 1998. 1304 [XML] World Wide Web Consortium, "Extensible Markup Language 1305 (XML) 1.0", W3C XML, February 1998, 1306 . 1308 [refs.RFC2026] 1309 Bradner, S., "The Internet Standards Process -- Revision 1310 3", RFC 2026, BCP 9, October 1996. 1312 [refs.RFC2119] 1313 Bradner, s., "Key words for RFCs to Indicate Requirements 1314 Levels", RFC 2119, March 1997. 1316 [refs.RFC2223] 1317 Postel, J. and J. Reynolds, "Instructions to RFC Authors", 1318 RFC 2223, October 1997. 1320 [refs.RFC3080] 1321 Rose, M., "The Blocks Extensible Exchange Protocol Core", 1322 RFC 3080, March 2001. 1324 Authors' Addresses 1326 Sharon Chisholm 1327 Nortel 1328 3500 Carling Ave 1329 Nepean, Ontario K2H 8E9 1330 Canada 1332 Email: schishol@nortel.com 1334 Kim Curran 1335 Nortel 1336 3500 Carling Ave 1337 Nepean, Ontario K2H 8E9 1338 Canada 1340 Email: kicurran@nortel.com 1342 Hector Trevino 1343 Cisco 1344 Suite 400 1345 9155 E. Nichols Ave 1346 Englewood, CO 80112 1347 USA 1349 Email: htrevino@cisco.com 1351 Appendix A. Potential Event Content 1353 This non-normative appendix explores possible content of event 1354 notifications. It provides field descriptions and indicates their 1355 applicability for the various event classes. Fields specific to 1356 configuration events (configuration event class) are provided in 1357 Appendix B. 1359 A.1 Event Identifier 1361 A unique event identifier provided for event correlation purposes. 1362 This field is used by management applications to identify events 1363 which are generated for a single event occurrence via different 1364 mechanisms (e.g. syslog, NETCONF). Ie, this event identifier could 1365 be included as content in a syslog or SNMP message to indicate that 1366 all the messages were generated from the same source event. Event Id 1367 values may be re-used across re-boots. 1369 Applicable event classes: All 1371 A.2 Resource Instance 1373 This field identifies the element/entity/object for which the event 1374 is applicable. 1376 Applicable event classes: All 1378 A.3 Event Time 1380 This field represents the time at which the action causing the 1381 generation of the event has taken place. Event time field is 1382 composed of two parts: event generation time and event sysUpTime. 1384 Event generation time follows the syslog TIMESTAMP format defined in 1385 draft-ietf-syslog-protocol-14.txt (derived from RFC3339 but with 1386 additional restrictions). Event sysUpTime is of XML type integer 1387 (0..4294967295) and it follows the same definition as sysUpTime 1388 (TimeTicks) defined in RFC3418 - "The time (in hundredths of a 1389 second) since the network management portion of the system was last 1390 re-initialized). 1392 Applicable event classes: All 1394 A.4 Perceived Severity 1396 The severity of the alarm as determined by the alarm detection point 1397 using the information it has available [RFC3877]. The values are 1398 cleared, indeterminate, critical, major, minor and warning. 1400 Applicable event classes: fault 1402 A.5 Probable Cause 1404 This field provides further information describing the cause of the 1405 alarm . Allowed values for this field are the same as those listed 1406 in RFC3877 and are derived from ITU X.733 and ITU M.3100. 1408 Note that this concept is being evolved to be less linear, within the 1409 ITU-T, in X.733.1, a protocol-neutral version of X.733. It may make 1410 sense to consider alignment with this update on the concept of 1411 probable cause, instead of the one in RFC3877 and X.733. 1413 Applicable event classes: fault 1415 A.6 Specific Problem 1417 This parameter is optional. When present, it identifies further 1418 refinements to the Probable cause of the alarm. This definition 1419 follows ITU X.733 1421 Applicable event classes: fault 1423 A.7 Trend Indication 1425 This parameter indicates the trend of the alarm against the managed 1426 resource Allowed values for this field are as specified in RFC3877 1427 and follow the ITU X.733 value definitions 1429 Applicable event classes: fault 1431 A.8 Additional Alarm Text 1433 This parameter is provided to allow implementation to include a 1434 textual description of the alarm 1436 Applicable event classes: fault 1438 A.9 Threshold Identifier 1440 This field holds the identifier of the monitored variable for which 1441 the threshold was set. This is analogous to the alarmVariable 1442 OBJECT-TYPE in RFC2819. 1444 Applicable event classes: fault (useful for threshold crossing 1445 alarms) 1447 A.10 Threshold Type 1449 This parameter is used to indicate the direction of the threshold 1450 crossing: rising, falling, or clear. 1452 Rising threshold type: This indicates that the value of a monitored 1453 variable has crossed the set threshold in the upwards direction. 1454 Only sent to indicate a problem 1456 Falling threshold type: This indicates that the value of a monitored 1457 variable has crossed the set threshold in the downwards direction. 1458 Only sent to indicate a problem. 1460 Clear threshold type: This indicates that the value of the monitored 1461 variable for which a threshold alarm had been previously issued as a 1462 result of crossing the set value either in the upwards or downwards 1463 direction has been restored to a value within an acceptable range 1464 (i.e. does not exceed the set threshold). Note that this differs 1465 from RFC2819. 1467 Applicable event classes: fault (useful in the case threshold 1468 crossing alarms) 1470 A.11 Observed Value 1472 The value of the monitored parameter (Threshold Identifier) for the 1473 last sampling period. This parameter follows the alarmValue 1474 definition in RFC2819. This field is in two parts - the value and 1475 the units of measure. 1477 Applicable event classes: fault (useful in the case threshold 1478 crossing alarms) 1480 A.12 State Change Information 1482 This parameter holds the name and values of the state attributes 1483 whose values have changed and are being reported. 1485 This is a parameter composed of three fields: Attribute Name, Old 1486 Value, and New Value. The definitions given in RFC4268 for state 1487 attributes and values are being followed. 1489 Applicable event classes: state 1491 Appendix B. Configuration Event Class Notifications 1493 This non-normative appendix provides a detailed description of a 1494 configuration change event notification definition in support of the 1495 configuration operations, particularly those defined by the NETCONF 1496 protocol. 1498 B.1 Types of Configuration Events 1500 Configuration event notifications include: 1502 o All-triggered Configuration Events 1504 o NETCONF-triggered Configuration Events 1506 All-triggered Configuration events report on changes from the 1507 perspective of the managed resource, rather than the commands which 1508 created the configuration change. They are reported regardless of 1509 what specific method was used to initiate the change. They indicate 1510 that a change has occurred around hardware, software, services or 1511 other managed resources within a system. Specific events includes 1513 o Resource Added 1515 o Resource Removed 1517 o Resource Modified 1519 NETCONF-triggered events are those which correspond to the execution 1520 of explicit NETCONF operations. These include: 1522 o copy-config event 1524 * This is a data store level event generated following the 1525 successful completion of a copy-config operation. This 1526 represents the creation of a new configuration file or 1527 replacement of an existing one. 1529 o delete-config event 1531 * This is a data store level event generated following the 1532 successful completion of a delete-config operation. This 1533 represents the deletion of a configuration file. 1535 o edit-config event 1537 * This is an event generated following a change in configuration 1538 due to an edit-config operation, e.g., due to the completion of 1539 an edit-config operation which successfully changed some part 1540 of the configuration. See edit-config error-options (stop-on- 1541 error, ignore-error, rollback-on-error) The contents of this 1542 event are dependent on the type of operation performed: edit- 1543 config (merge, replace, delete, create). This event is not 1544 intended to report completely unsuccessful configuration 1545 operations. 1547 o lock-config event 1549 * This is a data store level event generated following the 1550 successful locking of a configuration data store. 1552 o unlock-config event 1554 * This is a data store level event generated following the 1555 successful release of a lock previously held on a configuration 1556 data store. 1558 B.2 Config Event Notification Structure 1560 The table below lists the EventInfo parameters for a config event 1561 notification. 1563 Nomenclature: 1565 O - This is marked optional field because it is implementation/ 1566 notification category dependent. In some cases this may be user 1567 configurable. 1569 M - This is a mandatory field that must be included. Dependency on 1570 event class may exist as noted below 1571 ----------------------------------------------------- 1572 Parameter Name Restrictions 1573 ----------------------------------------------------- 1574 EventInfo 1575 ----------------------------------------------------- 1576 EventID O 1577 ----------------------------------------------------- 1578 ResourceInstance M 1579 ----------------------------------------------------- 1580 ConfigChangeType M 1581 ----------------------------------------------------- 1582 TargetDataStore M 1583 ----------------------------------------------------- 1584 UserInfo O 1585 ----------------------------------------------------- 1586 UserName 1587 ----------------------------------------------------- 1588 SourceIndicator 1589 ----------------------------------------------------- 1590 TransactionId 1591 ----------------------------------------------------- 1592 CopyConfigInfo -- copy-config only 1593 ----------------------------------------------------- 1594 DataSource M 1595 ----------------------------------------------------- 1596 EditConfigInfo -- edit-config only 1597 ----------------------------------------------------- 1598 EventTime M 1599 ----------------------------------------------------- 1600 Context O 1601 ----------------------------------------------------- 1602 EnteredCommand M 1603 ----------------------------------------------------- 1604 NewConfig M 1605 ----------------------------------------------------- 1606 MergeReplaceInfo 1607 ----------------------------------------------------- 1608 OldConfig O 1609 ----------------------------------------------------- 1610 EventTime M 1611 ----------------------------------------------------- 1612 EventGenerationTime 1613 ----------------------------------------------------- 1614 EventSysUpTime 1615 ----------------------------------------------------- 1617 B.3 Configuration Event Content 1619 The applicability of these fields to other event classes is for 1620 further study. 1622 B.3.1 Target Datastore 1624 Target datastore refers to the data store (startup, candidate, 1625 running) which was modified by the management operation. 1627 B.3.2 User Info 1629 This is used to convey information describing who originated the 1630 configuration event and the means for submitting the request. The 1631 user info field contains the following information: 1633 user Name: User id which was authorized to execute the associated 1634 management operation causing the generation of this event. 1636 source Indicator: Indicates the method employed to initiate the 1637 management operation telnet, NETCONF, console, etc. 1639 transaction Id: If available, this field contains a unique 1640 identifier for the associated management operation. This is 1641 implementation dependent and may require additional information to 1642 be communicated between server and client. A possible option is 1643 to make use of the message-id in the NETCONF rpc header 1645 B.3.3 Data Source 1647 The data source is used, for example, in the copy configuration 1648 command to indicated the source of information used in the copy 1649 operation 1651 Applicable Event Classes: configuration (useful for copy-config) 1653 B.3.4 Operation 1655 Operation is used, for example, in the edit configuration command to 1656 indicated the specific operation that has taken place - create, 1657 delete, merge, replace. 1659 Applicable Event Classes: configuration (useful for edit-config) 1661 B.3.5 Context 1663 The configuration sub-mode under which the command was executed. 1665 Applicable Event Classes: configuration 1667 B.3.6 Entered Command 1669 The command entered and executed on the device. 1671 B.3.7 New Config 1673 The device's configuration following the successful execution of the 1674 entered command. 1676 Applicable Event Classes: configuration 1678 B.3.8 Old Config 1680 The configuration prior to the execution of the entered command. 1682 Applicable Event Classes: configuration 1684 B.3.9 Non-netconf commands in configuration notifications 1686 To support legacy implementations and for better integration with 1687 other deployed solutions on the box, sending information via netconf 1688 about configuration changes that were originated via other solutions, 1689 such as command line interfaces is necessary. In order to do this, 1690 the information in the message needs to be clearly tagged so that the 1691 consumer of the information knows what to expect. In addition, the 1692 creation of the subscription needs allow for the client to indicate 1693 whether this non-XML formatted information is of interest 1695 The latter is done by identifying the XML namespace under which the 1696 data syntax/schema is defined. A NETCONF client requests the format 1697 in which it wants the NETCONF server to issue the event notifications 1698 at subscription time by specifying the appropriate namespace under 1699 the Filter parameter in the operation. An 1700 example is provided below: 1702 1703 1705 1707 B.4 Design Alternative 1709 B.4.1 Server Session Initiation 1711 Currently the NETCONF protocol requires session establishment to be 1712 initiated by the NETCONF client. With the introduction of event 1713 notifications in NETCONF as well deployments which might require the 1714 "call-home" feature to get around firewall and/or NAT issues, the 1715 ability for a NETCONF server to initiate sessions becomes important. 1717 Other potential uses of this feature includes the following 1718 deployment scenario: NE registration/auto-configuration. The device 1719 is pre-configured with a target destination address (the management 1720 station's address) where it needs to register and download its 1721 configuration. When managing large numbers of devices (e.g. CPEs) 1722 this also allows for increased scalability since the management 1723 station does not need to maintain established sessions to all managed 1724 devices. 1726 This appendix proposes extensions to the event subscription session 1727 establishment procedures and related operations to allow for server 1728 session initiation. 1730 Note that the security implications of this approach, compared with 1731 more traditional, well understood models, is for further study. 1733 The subscription information as described in the body of this 1734 document indicates that it is transient in nature (i.e. it is not 1735 persisted and it is only applicable through the life of the session). 1736 This section describes additional functionality for persisting event 1737 subscription information and allowing the NETCONF server (e.g. 1738 network element) to initiate the event subscription session. 1740 QUICK SUMMARY: The , , 1741 operations would be used in same manner as 1742 described in doc. It may use useful to allow a client and server to 1743 re-establish an events subscription. This would result in another 1744 capability to allow session initiation by the server. 1746 B.4.2 Establishment 1748 In order to establish an event subscription, a client must issue a 1749 message request. Upon a successful response 1750 from the server (e.g. network element) the event subscription is 1751 established. With this modified persistent version of the 1752 subscription, the NETCONF server would maintain the subscription 1753 information as part of its configuration. 1755 B.4.3 Teardown 1757 A event subscription is torn down when a) the client issues a 1758 message and it is successfully processed by 1759 the server (i.e. the server issues a positive response) or b) the 1760 NETCONF session carrying the event subscription goes down for any 1761 reason. 1763 If the subscription is not persistent, the user must create a new 1764 subscription with the exact same parameters as the original session. 1765 If instead, subscriptions were persistent, as part of the network 1766 element's configuration, the client simply needs to re-establish the 1767 session by specifying the subscription Id. 1769 B.4.4 Suspend And Resume 1771 Since the purpose of the operation is to stop 1772 event notification forwarding and due to its transient nature removes 1773 all subscription configuration; a different mechanism might be needed 1774 for shutting down the session but preserving the subscription 1775 information thus allowing the NETCONF server to re-establish the 1776 parameters and reproduce the subscription. 1778 The suspend and resume commands would allows a NETCONF client to 1779 suspend event notification forwarding without removing the existing 1780 subscription information. Operations and 1781 > are proposed for this purpose. 1783 Since event subscription information is now persistent, unsolicited 1784 session termination (i.e. other than command was issued. Event 1786 forwarding is resumed by sending a to the 1787 NETCONF server on a new connection. 1789 B.4.5 Lifecycle 1791 Configuration information associated with the event subscription 1792 (event classes and filters) could persist beyond the life of the 1793 event subscription session. (i.e. it is maintained by the network 1794 element as part of its configuration). This configuration 1795 information is subject to the behaviour of the datastore it resides 1796 in and may or may not persist across re-boots (e.g. it could be part 1797 of the running configuration but not the startup configuration). 1799 Appendix C. NETCONF Event Notifications and Syslog 1801 This appendix describes the mapping between syslog message fields and 1802 NETCONF event notification fields. The purpose of this mapping is to 1803 provide an unambiguous mapping to enable consistent multi-protocol 1804 implementations as well as to enable future migration. 1806 The second part of the appendix describes an optional capability to 1807 embed an entire syslog message (hereafter referred to as syslog 1808 message(s) to avoid confusion with the message field in syslog) 1809 within a NETCONF event notification. 1811 C.1 Leveraging Syslog Field Definitions 1813 This section provides a semantic mapping between NETCONF event fields 1814 and syslog message fields. 1816 ------------------------------------------------------------------- 1817 | PRI | HEADER | MESSAGE | 1818 ------------------------------------------------------------------- 1819 | FACILITY | SEVERITY | TIMESTAMP | HOSTNAME | TAG CONTENT | 1820 ------------------------------------------------------------------- 1821 Figure 2 - syslog message (RFC3164) 1823 ------------------------------------------------------------------- 1824 | HEADER | STRUCTURED DATA | MESSAGE | 1825 ------------------------------------------------------------------- 1826 Figure 3 - syslog message (draft-ietf-syslog-protocol-14.txt) 1828 HEADER (Version, Facility, Severity, Truncate, Flag, TimeStamp, 1829 HostName, AppName, ProcId, MsgId) 1831 STRUCTURED DATA (Zero or more Structured Data Elements - SDEs) 1833 MESSAGE ( Text message ) 1835 C.1.1 Field Mapping 1837 ------------------------------------------------------ 1838 RFC3164 Syslog ID NETCONF Event 1839 ------------------------------------------------------ 1840 VERSION 1841 ------------------------------------------------------ 1842 FACILITY FACILITY 1843 ------------------------------------------------------ 1844 SEVERITY SEVERITY PerceivedSeverity 1845 ------------------------------------------------------ 1846 TRUNCATE FLAG 1847 ------------------------------------------------------ 1848 TIMESTAMP TIMESTAMP EventTime 1849 ------------------------------------------------------ 1850 HOSTNAME HOSTNAME EventOrigin 1851 ------------------------------------------------------ 1852 TAG APP-NAME EventOrigin 1853 ------------------------------------------------------ 1854 PROC-ID 1855 ------------------------------------------------------ 1856 MSG-ID 1857 ------------------------------------------------------ 1858 CONTENT CONTENT AdditionalText 1859 ------------------------------------------------------ 1861 Figure 4 - syslog to NETCONF Event field mapping 1863 Notes: 1865 VERSION: Schema version is found in XML Schema namespace. However, 1866 no correspondence to syslog. 1868 FACILITY: No well defined semantics for this field. Therefore not 1869 used at this time. 1871 TRUNCATE: Not applicable. NETCONF events must be complete XML 1872 documents therefore cannot be truncated. 1874 TIME: TIMESTAMP in syslog ID is derived from RFC3339 but with 1875 additional restrictions 1877 PROC-ID: No equivalent field 1879 CONTENT: This is a free form text field with not defined semantics. 1880 The contents of this field may be included in the AdditionalText 1881 field. 1883 C.1.2 Severity Mapping 1885 The severity value mappings stated in (draft-ietf-syslog-protocol-14) 1886 are used: 1888 ITU Perceived Severity syslog SEVERITY 1889 Critical Alert 1890 Major Critical 1891 Minor Error 1892 Warning Warning 1893 Indeterminate Notice 1894 Cleared Notice 1896 Figure 5. ITU PerceivedSeverity to syslog SEVERITY mapping. 1898 C.2 Syslog within NETCONF Events 1900 C.2.1 Motivation 1902 The syslog protocol (RFC3164) is widely used by equipment vendors as 1903 a means to deliver event messages. Due to the widespread use of 1904 syslog as well as a potential phased availability and coverage of 1905 NETCONF events by equipment vendors, it is envisioned that users will 1906 also follow a phased migration. As a way to facilitate migration and 1907 at the same time allow equipment vendors to provide comprehensive 1908 event coverage over a NETCONF event subscription session, syslog 1909 messages could be embedded in their entirety within the body of a 1910 NETCONF event notification. 1912 The information provided in this appendix describes a mechanism to 1913 leverage syslog messages for the purpose of complementing the 1914 available NETCONF event notification set. The intent is to promote 1915 the use of the NETCONF interface and not to simply provide a wrapper 1916 and additional delivery mechanism for syslog messages. NETCONF 1917 events are intended to be well defined and structured, therefore 1918 providing an advantage over the unstructured and often times 1919 arbitrarily defined syslog messages (i.e. the message field). 1921 Covered herein is the syslog protocol as defined in RFC3164 and 1922 draft-ietf-syslog-protocol-14.txt. 1924 C.2.2 Embedding syslog messages in a NETCONF Event 1926 When event notifications are supported, the default behaviour for a 1927 NETCONF server is to send NETCONF event notifications over an 1928 established event subscription. As an option, the NETCONF server may 1929 embed a syslog message in its entirety (e.g. RFC3164 - PRI, Header, 1930 and Message fields), placing it within the Event Info field 1931 (SyslogInfo sub-field) - see Figure 1. 1933 _____________________________________________________ 1934 | NETCONF Event Header | Data | 1935 |________________________|___________________________| 1936 | | Event Info | 1937 |________________________|___________________________| 1938 | | 1939 v v 1940 ____________________________ 1941 | Event Fields | SyslogInfo | 1942 |___________________________| 1944 Figure 1 - Embedding syslog in a NETCONF Event Notifications 1946 C.2.3 Supported Forwarding Options 1948 Three event forwarding options may be supported by the NETCONF 1949 server: a) XML only (mandatory if NETCONF events capability is 1950 supported) b) XML and syslog (Optional) c) syslog only (optional) 1952 Note to the reader: Option "a" above refers to event notification 1953 messages defined for use over the NETCONF protocol. While their use 1954 is not necessarily limited to NETCONF protocol, they are referred to 1955 as "NETCONF XML-event" in the remainder of this section simply to 1956 avoid ambiguity. 1958 C.2.3.1 XML and Syslog option - Forwarding Behaviour 1960 It is possible, due to coverage, for a given NETCONF implementation 1961 to not support a comprehensive set of NETCONF event notifications. 1962 Therefore, it is possible for a given event to trigger the generation 1963 of a syslog message without a NETCONF-aware counterpart. In such 1964 situations, the NETCONF server could form a NETCONF event 1965 notification, embed the syslog message in the SyslogInfo field and 1966 forward the NETCONF event notifications to all subscribed 1967 destinations. Otherwise, both NETCONF event and syslog messages must 1968 be included in the Event Info field. 1970 C.2.3.2 Event Class Identification 1972 The event class field is found in the NETCONF event header 1973 information as described in the main body of this document. It 1974 conveys information describing that type of event for which the event 1975 notification is generated and lets the consumer of the message know 1976 what to expect. NETCONF event notifications which only contain a 1977 syslog message (Options b or c) must have the EventClass field set to 1978 "information". [Editor's Note: This needs to be thought through. It 1979 may not be the best option.] The NETCONF client parses the message 1980 in the same manner as any other message, finds the normal fields 1981 empty [Editor's Note: or not present?] and either proceeds to parse 1982 the SyslogInfo field or hands the syslog message to the entity 1983 responsible for processing syslog messages. 1985 C.2.3.3 Event Subscription Options 1987 A NETCONF client may request subscription to options b) XML and 1988 syslog or c) syslog only listed in "Supported Forwarding Options" at 1989 subscription time via the user-specified filter. The FILTER or NAMED 1990 FILTER parameter in . As previously indicated, 1991 the default behaviour is to forward NETCONF XML only event 1992 notifications. 1994 C.2.3.4 Supported Forwarding Option Discovery 1996 A potential means for a NETCONF server to convey its feature set 1997 support is via capabilities. However, in this particular case, the 1998 event content is not a protocol feature therefore other means are 1999 needed. A future version of this document will address this issue. 2001 Intellectual Property Statement 2003 The IETF takes no position regarding the validity or scope of any 2004 Intellectual Property Rights or other rights that might be claimed to 2005 pertain to the implementation or use of the technology described in 2006 this document or the extent to which any license under such rights 2007 might or might not be available; nor does it represent that it has 2008 made any independent effort to identify any such rights. Information 2009 on the procedures with respect to rights in RFC documents can be 2010 found in BCP 78 and BCP 79. 2012 Copies of IPR disclosures made to the IETF Secretariat and any 2013 assurances of licenses to be made available, or the result of an 2014 attempt made to obtain a general license or permission for the use of 2015 such proprietary rights by implementers or users of this 2016 specification can be obtained from the IETF on-line IPR repository at 2017 http://www.ietf.org/ipr. 2019 The IETF invites any interested party to bring to its attention any 2020 copyrights, patents or patent applications, or other proprietary 2021 rights that may cover technology that may be required to implement 2022 this standard. Please address the information to the IETF at 2023 ietf-ipr@ietf.org. 2025 The IETF has been notified of intellectual property rights claimed in 2026 regard to some or all of the specification contained in this 2027 document. For more information consult the online list of claimed 2028 rights. 2030 Disclaimer of Validity 2032 This document and the information contained herein are provided on an 2033 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2034 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2035 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2036 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2037 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2038 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2040 Copyright Statement 2042 Copyright (C) The Internet Society (2006). This document is subject 2043 to the rights, licenses and restrictions contained in BCP 78, and 2044 except as set forth therein, the authors retain all their rights. 2046 Acknowledgment 2048 Funding for the RFC Editor function is currently provided by the 2049 Internet Society.