Network Working Group S. Chisholm Internet-Draft K. Curran Expires: January 11, 2006 Nortel July 10, 2005 Netconf Event Messages draft-chisholm-netconf-event-00.txt Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on January 11, 2006. Copyright Notice Copyright (C) The Internet Society (2005). Abstract This memo defines a framework for sending asynchronous messages, or event messages in Netconf. It defines both the operations necessary to support this concept, and also discusses implications for the mapping to application protocols. Chisholm & Curran Expires January 11, 2006 [Page 1] Internet-Draft Netconf Event Messages July 2005 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Definition of Terms . . . . . . . . . . . . . . . . . . . 3 1.2 Event Messages in Netconf . . . . . . . . . . . . . . . . 4 2. Event-Related Operations . . . . . . . . . . . . . . . . . . . 5 2.1 Subscribing to receive Events . . . . . . . . . . . . . . 5 2.1.1 create-subscription . . . . . . . . . . . . . . . . . 6 2.2 Sending Events . . . . . . . . . . . . . . . . . . . . . . 6 2.2.1 EVENTS . . . . . . . . . . . . . . . . . . . . . . . . 7 2.3 Changing the Subscription . . . . . . . . . . . . . . . . 7 2.3.1 modify-subscription . . . . . . . . . . . . . . . . . 8 2.4 Terminating the Subscription . . . . . . . . . . . . . . . 8 2.4.1 cancel-subscription . . . . . . . . . . . . . . . . . 9 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 10 3.1 RPC One-way Messages . . . . . . . . . . . . . . . . . . . 10 3.2 User-Specified Filters . . . . . . . . . . . . . . . . . . 10 3.2.1 Named Profiles . . . . . . . . . . . . . . . . . . . . 10 3.2.2 Just-in-time Filtering . . . . . . . . . . . . . . . . 10 3.3 Event Classes . . . . . . . . . . . . . . . . . . . . . . 10 3.4 Defining Event Messages . . . . . . . . . . . . . . . . . 11 3.5 Interleaving Messages . . . . . . . . . . . . . . . . . . 11 4. XML Schema for Event Messages . . . . . . . . . . . . . . . . 13 5. Mapping to Application Protocols . . . . . . . . . . . . . . . 17 5.1 SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.2 BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.2.1 One-way Messages in Beep . . . . . . . . . . . . . . . 18 5.3 SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.3.1 A Netconf over Soap over HTTP Example . . . . . . . . 19 6. Security Considerations . . . . . . . . . . . . . . . . . . . 22 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 23 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 24 Intellectual Property and Copyright Statements . . . . . . . . 25 Chisholm & Curran Expires January 11, 2006 [Page 2] Internet-Draft Netconf Event Messages July 2005 1. Introduction NETCONF [NETCONF-PROTO] can be conceptually partitioned into four layers: Layer Example +-------------+ +-----------------------------+ | Content | | Configuration data | +-------------+ +-----------------------------+ | | +-------------+ +-----------------------------+ | Operations | | , | +-------------+ +-----------------------------+ | | +-------------+ +-----------------------------+ | RPC | | , | +-------------+ +-----------------------------+ | | +-------------+ +-----------------------------+ | Application | | BEEP, SSH, SSL, console | | Protocol | | | +-------------+ +-----------------------------+ This document defines a framework for sending asynchronous messages, or event messages in Netconf. It defines both the operations necessary to support this concept, and also discusses implications for the mapping to application protocols. Figure 1 1.1 Definition of Terms The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [3]. Element: An XML Element[XML]. Managed Entity: A node, which supports netconf[NETCONF] and has access to management instrumentation. Managed Object: A collection of one of more Elements that define an abstract thing of interest. Chisholm & Curran Expires January 11, 2006 [Page 3] Internet-Draft Netconf Event Messages July 2005 1.2 Event Messages in Netconf An event is something that happens which may be of interest. A configuration change, a fault, a change in status, crossing a threshold, or an external input to the system, for example. Often this results in an asynchronous message, sometimes referred to as a notification or event message, being sent out to interested parties to notify them that this event has occurred. This memo defines a mechanism whereby the manager, or client, indicates interest in receiving event messages from a managed entity, or server by creating a subscription to receive events. The managed entity, or client, replies to indicate whether the subscription request was successful and, if it was successful, begins sending the event messages to the manager, or client, as the events occur within the system. These event messages will continue to be sent until either the netconf session is terminated or an explicit command to cancel the subscription is sent. The event subscription allows a number of options to enable the manager, or client, to specify which events are of interest. These are specified when the subscription is created, but can be modified later using a modify subscription command. Chisholm & Curran Expires January 11, 2006 [Page 4] Internet-Draft Netconf Event Messages July 2005 2. Event-Related Operations 2.1 Subscribing to receive Events The event subscription is initiated by the management application or operator script and responded to by the managed entity. When the event subscription is created, the events of interest are specified. It is possible to create more than one event subscription on a single underlying connection. Each event subscription therefore has its own unique identifier. Content for an event subscription can be selected by specifying which event classes are of interest and /or by applying user-specified filters. Chisholm & Curran Expires January 11, 2006 [Page 5] Internet-Draft Netconf Event Messages July 2005 2.1.1 create-subscription Description: This command initiates an events subscription which will send asynchronous event messages to the initiator of the command until the command is sent Parameters: Event Classes: An optional parameter that indices which event classes are of interest. If not present, all events will be sent. Filter: An optional parameter that indicates which subset of all possible events you are interested in. Format is the same filter used for other netconf commands. If not present, no filtering will be applied Positive Response: If the device can satisfy the request, the server sends an element containing a element containing the subscription ID. Negative Response: An element is included within the if the request cannot be completed for any reason. 2.2 Sending Events Once the subscription has been set up, the managed entity sends the events asynchronously along the connection. Message are tagged using with an event class, subscription ID and sequence number. Chisholm & Curran Expires January 11, 2006 [Page 6] Internet-Draft Netconf Event Messages July 2005 2.2.1 EVENTS Events Description: A event messages sent to the initiator of an command asynchronously when an event of interest to them has occurred. An event is a complete document. Parameters: Event Classes: The event class or classes associated with this event . Subscription Id: A unique identifier for this event stream . Sequence Number: A sequentially increasing number to uniquely identify event messages for this netconf session. Positive Response: No response. Negative Response: No response. 2.3 Changing the Subscription After an event subscription has been established, the management application or operator script can initiate a request to change properties of the event subscription. This prevents loss of events that might otherwise occur during a tear down and recreation of the event subscription. This command is responded to by the managed entity Chisholm & Curran Expires January 11, 2006 [Page 7] Internet-Draft Netconf Event Messages July 2005 2.3.1 modify-subscription Description: Change properties of the event subscription. Parameters: Subscription Id: A unique identifier for this even subscription.. Event Classes: An optional parameter that indices which Event Classes are of interest. If not present, all events will be sent. Filter: An optional parameter that indicates which subset of all possible events you are interested in. Format is the same filter used for other commands. If not present, all no filtering will applied Positive Response: If the device was able to satisfy the request, an is sent that includes an element. Negative Response: An element is included within the if the request cannot be completed for any reason. 2.4 Terminating the Subscription The closing of the event subscription is initiated by the management application or operator script. The specific subscription to be to be closed is specified using a subscription ID. The managed entity responds. Note that the netconf session may also be torn down for other reasons and this will also result in the subscription being cancelled, but is not subjected to the behaviour of this command. Chisholm & Curran Expires January 11, 2006 [Page 8] Internet-Draft Netconf Event Messages July 2005 2.4.1 cancel-subscription Description: Tear down the event subscription. Parameters: Subscription Id: A unique identifier for this even subscription. Positive Response: If the device was able to satisfy the request, an is sent that includes an element. Negative Response: An element is included within the if the request cannot be completed for any reason. Chisholm & Curran Expires January 11, 2006 [Page 9] Internet-Draft Netconf Event Messages July 2005 3. Supporting Concepts 3.1 RPC One-way Messages In order to support the concept that each individual event message is a well-defined XML-document that can be processed without waiting for all events to come in, it makes sense to define events, not as an endless reply to a subscription command, but as independent messages that originate from the managed entity. In order to support this model, this memo introduces the concept of a one-way RPC message. The one-way RPC message is similar to the two-way RPC message, except that no response is expected to the commend. In the case of events, this RPC will originate from the managed entity, and not the manager. 3.2 User-Specified Filters 3.2.1 Named Profiles A named profile is a filter that is created ahead of time and applied at the time an event stream is created or modified. Note that changes to the profile after the stream has been created alter the events received. 3.2.2 Just-in-time Filtering Just-in-time filtering is explicitly stated when the event stream is created. It can only be changed using the modify stream command. 3.3 Event Classes Events can be broadly classified into one more event classes. The initial set of event classes is fault, information, state, audit, configuration, data, maintenance, metrics, security and heartbeat. A fault event message is generated when a fault condition (error or warning) occurs. An Information event is something that happens of interest which is within the expected operational behaviour and not otherwise covered by another class. A state event indicates a change from one state to another, where a state is a condition or stage in the existence of a managed entity. Audit events provide notification of very specific actions within a managed device. In isolation an audit event provides very limited data. A collection of audit information forms an audit trail. A configuration event, alternatively known as an inventory event, is used to notify that hardware, software, or a service has been added/changed/removed. A data dump event is an asynchronous event containing information about a system, its configuration, state, etc. A maintenance event signals Chisholm & Curran Expires January 11, 2006 [Page 10] Internet-Draft Netconf Event Messages July 2005 the beginning, process or end of an action either generated by a manual or automated maintenance action. A metrics event contains a metric or a collection of metrics. This includes performance metrics. A heart beat event is sent periodically to enable testing that the communications channel is still functional. 3.4 Defining Event Messages Event Messages are defined ahead of time by defining an XML element and assigning it to particular event classes. This will be done using an "eventClasses" attribute. See 'Framework for Netconf Data Models' [Netconf-Datamodels] for more information. 3.5 Interleaving Messages While each netconf message must be a complete XML document, the design of the event system allows for the interleaving of complete asynchronous event messages with complete command or response messages. It is possible to still send command-response type messages such as while events are being generated. The only restraint is that each message must be complete The following sequence diagram demonstrates a netconf session where after basic session establishment and capability exchange, the manager, or client (C), subscribes to receive events. The managed entity, or server (S), starts sending event messages as events of interest happen within the system. The manager, or client decides to change the characteristics of their event subscription so sends a command. Before the managed entity, or server, receives this command, another event is generated and the managed entity starts to send the event message. The managed entity finishes sending this event message before processing the command and sending the reply. Chisholm & Curran Expires January 11, 2006 [Page 11] Internet-Draft Netconf Event Messages July 2005 C S | | | capability exchange | --------------------------->| <-------------------------->| | | | | |-------------------------->| |<--------------------------| | | | | |<--------------------------| | | | | |<--------------------------| | | | | |-------------------------->| (buffered) | | |<--------------------------| | | |<--------------------------| Chisholm & Curran Expires January 11, 2006 [Page 12] Internet-Draft Netconf Event Messages July 2005 4. XML Schema for Event Messages This import accesses the xml: attribute groups for the xml:lang as declared on the error-message element. The unique identifier for this particular subscription within the session. A monotonically increasing integer. Starts at 0. Always increases by just one. Roll back to 0 after maximum value is reached. Chisholm & Curran Expires January 11, 2006 [Page 13] Internet-Draft Netconf Event Messages July 2005 Chisholm & Curran Expires January 11, 2006 [Page 15] Internet-Draft Netconf Event Messages July 2005 Chisholm & Curran Expires January 11, 2006 [Page 16] Internet-Draft Netconf Event Messages July 2005 5. Mapping to Application Protocols Currently, the Netconf family of specification allows for running netconf over a number of application protocols, some of which support multiple configurations. Some of these options will be better suited for supporting events then others. 5.1 SSH Session establishment and two-way messages are based on the Netconf over SSH transport mapping [NETCONF-SSH] One-way messages are supported as follows: Once the session has been established and capabilities have been exchanged, the server may send complete XML documents to the manager containing rpc-one-way elements. No response is expected from the manager. As in the other examples in [NETCONF-SSH] illustrate, a special character sequence, MUST be sent by both the client and the server after each XML document in the NETCONF exchange. This character sequence cannot legally appear in an XML document, so it can be unambiguously used to identify the end of the current document in the event of an XML syntax or parsing error, allowing resynchronization of the NETCONF exchange. The NETCONF over SSH session to receive an event might look like this: Chisholm & Curran Expires January 11, 2006 [Page 17] Internet-Draft Netconf Event Messages July 2005 123456 2 Fred Flinstone Ethernet0/0 1500 ]]> ]]> 5.2 BEEP Session establishment and two-way messages are based on the Netconf over BEEP transport mapping NETCONF-BEEP 5.2.1 One-way Messages in Beep One-way messages can be supported either by mapping to the existing one-to-many BEEP construct or by creating a new one-to-none construct. This area is for future study. 5.2.1.1 One-way messages via the One-to-many Construct Messages in one-to-many exchanges: "rcp", "rpc-one-way", "rpc-reply" Chisholm & Curran Expires January 11, 2006 [Page 18] Internet-Draft Netconf Event Messages July 2005 Messages in positive replies: "rpc-reply", "rpc-one-way" 5.2.1.2 One-way messages via the One-to-none Construct Note that this construct would need to be added to an extension or update to 'The Blocks Extensible Exchange Protocol Core' RFC 3080. MSG/NoANS: the client sends a "MSG" message, the server, sends no reply. In one-to-none exchanges, no reply to the "MSG" message is expected. 5.3 SOAP Session management and message exchange are based on the Netconf over SOAP transport mapping NETCONF-SOAP Note that the use of "persistent connections" "chunked transfer- coding" when using HTTP becomes even more important in the supporting of events 5.3.1 A Netconf over Soap over HTTP Example C: POST /netconf HTTP/1.1 C: Host: netconfdevice C: Content-Type: text/xml; charset=utf-8 C: Accept: application/soap+xml, text/* C: Cache-Control: no-cache C: Pragma: no-cache C: Content-Length: 465 C: C: C: C: C: C: C: C: C: C: The response: S: HTTP/1.1 200 OK S: Content-Type: application/soap+xml; charset=utf-8 S: Content-Length: 917 Chisholm & Curran Expires January 11, 2006 [Page 19] Internet-Draft Netconf Event Messages July 2005 S: S: S: S: S: S: S: S: 123456 S: S: S: S: And then some time later S: HTTP/1.1 200 OK S: Content-Type: application/soap+xml; charset=utf-8 S: Content-Length: 917 S: S: S: S: S: S: S: S: 123456 S: S: 2 S: S: Fred Flinstone S: S: S: S: S: S: S: S: S: Ethernet0/0 S: 1500 S: S: S: Chisholm & Curran Expires January 11, 2006 [Page 20] Internet-Draft Netconf Event Messages July 2005 S: S: S: S: S: S: S: S: Chisholm & Curran Expires January 11, 2006 [Page 21] Internet-Draft Netconf Event Messages July 2005 6. Security Considerations To be determined once specific aspects of this solution are better understood. In particular, the access control framework and the choice of transport will have a major impact on the security of the solution Chisholm & Curran Expires January 11, 2006 [Page 22] Internet-Draft Netconf Event Messages July 2005 7. Acknowledgements Thanks to Gilbert Gagnon and Greg Wilbur for providing their input into this document 8. References [NETCONF] Enns, R., "NETCONF Configuration Protocol", ID draft-ietf-netconf-prot-06, April 2005. [NETCONF BEEP] Lear, E. and K. Crozier, "Using the NETCONF Protocol over Blocks Extensible Exchange Protocol (BEEP)", ID draft-ietf-netconf-beep-05, March 2005. [NETCONF Datamodel] Chisholm, S. and S. Adwankar, "Framework for Netconf Data Models", ID draft-chisholm-netconf-model-03.txt, June 2005. [NETCONF SOAP] Goddard, T., "Using the Network Configuration Protocol (NETCONF) Over the Simple Object Access Protocol (SOAP)", ID draft-ietf-netconf-soap-05, April 2005. [NETCONF SSH] Wasserman, M. and T. Goddard, "Using the NETCONF Configuration Protocol over Secure Shell (SSH)", ID draft-ietf-netconf-ssh-04.txt, April 2005. [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. [XML] World Wide Web Consortium, "Extensible Markup Language (XML) 1.0", W3C XML, February 1998, . [refs.RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", RFC 2026, BCP 9, October 1996. [refs.RFC2119] Bradner, s., "Key words for RFCs to Indicate Requirements Levels", RFC 2119, March 1997. [refs.RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", Chisholm & Curran Expires January 11, 2006 [Page 23] Internet-Draft Netconf Event Messages July 2005 RFC 2223, October 1997. [refs.RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC 3080, March 2001. Authors' Addresses Sharon Chisholm Nortel PO Box 3511 Station C Ottawa, Ontario K1Y 4H7 Canada Email: schishol@nortel.com Kim Curran Nortel PO Box 3511 Station C Ottawa, Ontario K1Y 4H7 Canada Email: kicurran@nortel.com Chisholm & Curran Expires January 11, 2006 [Page 24] Internet-Draft Netconf Event Messages July 2005 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. The IETF has been notified of intellectual property rights claimed in regard to some or all of the specification contained in this document. For more information consult the online list of claimed rights. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2005). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Chisholm & Curran Expires January 11, 2006 [Page 25] Internet-Draft Netconf Event Messages July 2005 Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Chisholm & Curran Expires January 11, 2006 [Page 26]