Network Working Group                                        S. Chisholm
Internet-Draft                                                    Nortel
Intended status: Standards Track                              H. Trevino
Expires: June 29, 2007                                             Cisco
                                                       December 26, 2006


                      NETCONF Event Notifications
          draft-trevino-netconf-notification-transport-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 June 29, 2007.

Copyright Notice

   Copyright (C) The IETF Trust (2006).













Chisholm & Trevino        Expires June 29, 2007                 [Page 1]

Internet-Draft         NETCONF Event Notifications         December 2006


Abstract

   This document defines the transport mappings for NETCONF event
   notifications.  This is an optional capability built on top of the
   base NETCONF protocol.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Definition of Terms  . . . . . . . . . . . . . . . . . . .  3
     1.2.  Event Notifications in NETCONF . . . . . . . . . . . . . .  4
   2.  Mapping to Transport Protocols . . . . . . . . . . . . . . . .  5
     2.1.  SSH  . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
     2.2.  BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . .  6
       2.2.1.  One-way Notification Messages in Beep  . . . . . . . .  6
     2.3.  SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . .  7
       2.3.1.  A NETCONF over Soap over HTTP Example  . . . . . . . .  7
   3.  Security Considerations  . . . . . . . . . . . . . . . . . . . 10
   4.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11
   5.  Normative References . . . . . . . . . . . . . . . . . . . . . 12
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13
   Intellectual Property and Copyright Statements . . . . . . . . . . 14




























Chisholm & Trevino        Expires June 29, 2007                 [Page 2]

Internet-Draft         NETCONF Event Notifications         December 2006


1.  Introduction

   [NETCONF] can be conceptually partitioned into four layers:

   Layer                      Example
    +-------------+      +----------------------------------------+
    |   Content   |      |     Configuration data                 |
    +-------------+      +----------------------------------------+
              |                           |
    +-------------+      +-------------------------------------------+
    | Operations  |      | <get-config>, <edit-config> <notification>|
    +-------------+      +-------------------------------------------+
              |                           |                    |
    +-------------+      +-----------------------------+       |
    |     RPC     |      |    <rpc>, <rpc-reply>       |       |
    +-------------+      +-----------------------------+       |
             |                           |                     |
    +-------------+      +------------------------------------------+
    | Transport   |      |   BEEP, SSH, SSL, console                |
    |   Protocol  |      |                                          |
    +-------------+      +------------------------------------------+


   This document defines mechanisms which provide an asynchronous
   message notification delivery service for the [NETCONF] protocol.
   This is an optional capability built on top of the base NETCONF
   definition.  This memo defines the capabilities, operations,
   transport mappings, and data models necessary to support this
   service.  Editor's Note: Inclusion of Notification transport mappings
   into bis versions of the SSH, SOAP and HTTP transport mappings RFCs
   should be considered instead of publishing a Notification-specific
   transport mapping document.

                                 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 [RFC2119].

   Element:  An [XML] Element.

   Subscription:  A concept related to the delivery of notifications (if
      any to send) involving destination and selection of notifications.
      It is bound to the lifetime of a session.





Chisholm & Trevino        Expires June 29, 2007                 [Page 3]

Internet-Draft         NETCONF Event Notifications         December 2006


   Operation:  This term is used to refer to NETCONF protocol
      operations.  Specifically within this document, operation refers
      to NETCONF protocol operations defined in support of NETCONF
      notifications.

1.2.  Event Notifications 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 notification, being sent out to interested
   parties to notify them that this event has occurred.

   The NETCONF notification service defines a mechanism whereby the
   NETCONF client indicates interest in receiving event notifications
   from a NETCONF server by creating a subscription to receive event
   notifications.  The NETCONF server replies to indicate whether the
   subscription request was successful and, if it was successful, begins
   sending the event notifications to the NETCONF client as the events
   occur within the system.  These event notifications will continue to
   be sent until either the NETCONF session is terminated or some event,
   outside the scope of this specification, causes the subscription to
   terminate.  The event notification subscription allows a number of
   options to enable the NETCONF client to specify which events are of
   interest.  These are specified when the subscription is created.

   An NETCONF server is not required to process RPC requests on the
   session associated with the subscription until the notification
   stream is done.  A capability may be advertised to announce that a
   server is able to process RPCs while a notification stream is active
   on a session.



















Chisholm & Trevino        Expires June 29, 2007                 [Page 4]

Internet-Draft         NETCONF Event Notifications         December 2006


2.  Mapping to Transport Protocols

   Currently, the NETCONF family of specification allows for running
   NETCONF over a number of transport protocols, some of which support
   multiple configurations.  Some of these options will be better suited
   for supporting event notifications then others.

2.1.  SSH

   Session establishment and two-way messages are based on the NETCONF
   over SSH transport mapping [NETCONF-SSH]

   One-way event 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 NETCONF client containing
   notification elements.  No response is expected from the NETCONF
   client.

   As the 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 notification of
   an XML syntax or parsing error, allowing resynchronization of the
   NETCONF exchange.

   The NETCONF over SSH session to receive an event notification might
   look like the following.  In the example below the event notification
   contents (delimited by <data> </data> tags) are not defined in this
   document and are provided herein simply for illustration purposes.
   The sample notification shows a configuration change on the running
   configuration as a result of an <edit-config> operation.  It has one
   containment node ( <interfaces> ), with one element <interface> and
   two changed attributes (<name> and <mtu>) (Note that this does not
   refer to XML attributes).  The same example is used in the BEEP and
   SOAP transport mapping sections.















Chisholm & Trevino        Expires June 29, 2007                 [Page 5]

Internet-Draft         NETCONF Event Notifications         December 2006


   <?xml version="1.0" encoding="UTF-8"?>
     <notification
                xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
        <data xmlns="http://example.com/event/1.0">
            <severity>notice</severity>
            <eventClasses><configuration/><audit/></eventClasses>
            <sequenceNumber>2</sequenceNumber>
            <dateAndTime>2000-01-12T12:13:14Z</dateAndTime>
            <user>Fred Flinstone</user>
            <operation>
              <edit-config>
                <target>
                <running/>
                </target>
               <edit-config>
                   <top xmlns="http://example.com/schema/1.2/config">
                     <interfaces>
                       <interface>
                         <name>Ethernet0/0</name>
                         <mtu>1500</mtu>
                       </interface>
                     </interfaces>
                   </top>
                 </config>
              </edit-config>
            </operation>
          </data>
        </event>
        </data>
     </notification>

2.2.  BEEP

   Session establishment and two-way messages are based on the NETCONF
   over BEEP transport mapping [NETCONF-BEEP]

2.2.1.  One-way Notification Messages in Beep

   One-way notification 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.

2.2.1.1.  One-way messages via the One-to-many Construct

   Messages in one-to-many exchanges: "rpc", "notification", "rpc-reply"




Chisholm & Trevino        Expires June 29, 2007                 [Page 6]

Internet-Draft         NETCONF Event Notifications         December 2006


   Messages in positive replies: "rpc-reply"

2.2.1.2.  One-way notification 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' [RFC3080].

   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.

2.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 event notifications

2.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: <?xml version="1.0" encoding="UTF-8"?>
   C: <soapenv:Envelope
   C:   xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   C:   <soapenv:Body>
   C:     <rpc message-id="101"
   C:        xmlns=
              "xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
   C:       <create-subscription>
   C:       </create-subscription>
   C:     </rpc>
   C:   </soapenv:Body>
   C: </soapenv:Envelope>

   The response:




Chisholm & Trevino        Expires June 29, 2007                 [Page 7]

Internet-Draft         NETCONF Event Notifications         December 2006


   S: HTTP/1.1 200 OK
   S: Content-Type: application/soap+xml; charset=utf-8
   S: Content-Length: 917
   S:
   S: <?xml version="1.0" encoding="UTF-8"?>
   S: <soapenv:Envelope
   S:   xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   S:   <soapenv:Body>
   S:     <rpc-reply message-id="101"
   S:        xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
   S:       <data>
   S:         <top xmlns=
                      "http://example.com/schema/1.2/notification">
   S:         </top>
   S:       </data>
   S:     </rpc-reply>
   S:   </soapenv:Body>
   S: </soapenv:Envelope>

   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: <?xml version="1.0" encoding="UTF-8"?>
   S: <soapenv:Envelope
   S:   xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   S:   <soapenv:Body>
   S:     <notification
                xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
   S:       <data>
   S:      <eventClasses><configuration/><audit/></eventClasses>
   S:      <sequenceNumber>2</sequenceNumber>
   S:           <dateAndTime>2000-01-12T12:13:14Z</dateAndTime>
   S:           <user>Fred Flinstone</user>
   S:              <operation>
   S:               <edit-config>
   S:              <target>
   S:               <running/>
   S:              </target>
   S:             <config>
   S:              <top xmlns="http://example.com/schema/1.2/config">
   S:                   <interfaces>
                          <interface>
   S:                       <name>Ethernet0/0</name>
   S:                       <mtu>1500</mtu>
                         </interface>



Chisholm & Trevino        Expires June 29, 2007                 [Page 8]

Internet-Draft         NETCONF Event Notifications         December 2006


   S:                  </interfaces>
   S:               </top>
   S:            </config>
   S:           </edit-config>
   S:         </operation>
   S:       </data>
   S:    </notification>
   S:   </soapenv:Body>
   S: </soapenv:Envelope>










































Chisholm & Trevino        Expires June 29, 2007                 [Page 9]

Internet-Draft         NETCONF Event Notifications         December 2006


3.  Security Considerations

   The security considerations from the base transport mapping documents
   [NETCONF-SSH], [NETCONF-BEEP], and [NETCONF-SOAP] apply to the
   Notification capability.














































Chisholm & Trevino        Expires June 29, 2007                [Page 10]

Internet-Draft         NETCONF Event Notifications         December 2006


4.  Acknowledgements

   Thanks to Gilbert Gagnon, Greg Wilbur and Kim Curran for providing
   their input into the early work on this document.  In addition, the
   editors would like to acknowledge input at the Vancouver editing
   session from the following people: Orly Nicklass, James Balestriere,
   Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington,
   Dave Partain, Ray Atarashi and Dave Perkins and the following
   additional people from the Montreal editing session: Balazs Lengyel,
   Phil Shafer, Rob Ennes, Andy Bierman, Dan Romascanu, Bert Wijnen,
   Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig,
   Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, William
   Chow






































Chisholm & Trevino        Expires June 29, 2007                [Page 11]

Internet-Draft         NETCONF Event Notifications         December 2006


5.  Normative References

   [NETCONF]  Enns, R., "NETCONF Configuration Protocol",
              ID draft-ietf-netconf-prot-12, February 2006.

   [NETCONF-BEEP]
              Lear, E. and K. Crozier, "Using the NETCONF Protocol over
              Blocks Extensible Exchange Protocol (BEEP)",
              ID draft-ietf-netconf-beep-10, March 2006.

   [NETCONF-SOAP]
              Goddard, T., "Using the Network Configuration Protocol
              (NETCONF) Over the Simple Object Access Protocol (SOAP)",
              ID draft-ietf-netconf-soap-08, March 2006.

   [NETCONF-SSH]
              Wasserman, M. and T. Goddard, "Using the NETCONF
              Configuration Protocol over Secure Shell (SSH)",
              ID draft-ietf-netconf-ssh-06.txt, March 2006.

   [RFC2026]  Bradner, S., "The Internet Standards Process -- Revision
              3", RFC 2026, BCP 9, October 1996.

   [RFC2119]  Bradner, s., "Key words for RFCs to Indicate Requirements
              Levels", RFC 2119, March 1997.

   [RFC2223]  Postel, J. and J. Reynolds, "Instructions to RFC Authors",
              RFC 2223, October 1997.

   [RFC3080]  Rose, M., "The Blocks Extensible Exchange Protocol Core",
              RFC 3080, March 2001.

   [XML]      World Wide Web Consortium, "Extensible Markup Language
              (XML) 1.0", W3C XML, February 1998,
              <http://www.w3.org/TR/1998/REC-xml-19980210>.

   [XML-Schema]
              Fallside, D. and P. Walmsley, "XML Schema Part 0: Primer
              Second Edition", W3C XML-Schema, October 2004.












Chisholm & Trevino        Expires June 29, 2007                [Page 12]

Internet-Draft         NETCONF Event Notifications         December 2006


Authors' Addresses

   Sharon Chisholm
   Nortel
   3500 Carling Ave
   Nepean, Ontario  K2H 8E9
   Canada

   Email: schishol@nortel.com


   Hector Trevino
   Cisco
   Suite 400
   9155 E. Nichols Ave
   Englewood, CO  80112
   USA

   Email: htrevino@cisco.com
































Chisholm & Trevino        Expires June 29, 2007                [Page 13]

Internet-Draft         NETCONF Event Notifications         December 2006


Full Copyright Statement

   Copyright (C) The IETF Trust (2006).

   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.

   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, THE IETF TRUST 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.


Intellectual Property

   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.


Acknowledgment

   Funding for the RFC Editor function is provided by the IETF
   Administrative Support Activity (IASA).





Chisholm & Trevino        Expires June 29, 2007                [Page 14]