Home   A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z  

NETCONF Event Notifications :: RFC5277








Network Working Group                                        S. Chisholm
Request for Comments: 5277                                        Nortel
Category: Standards Track                                     H. Trevino
                                                                   Cisco
                                                               July 2008


                      NETCONF Event Notifications

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Abstract

   This document defines mechanisms that provide an asynchronous message
   notification delivery service for the Network Configuration protocol
   (NETCONF).  This is an optional capability built on top of the base
   NETCONF definition.  This document defines the capabilities and
   operations necessary to support this service.



























Chisholm & Trevino          Standards Track                     [Page 1]

RFC 5277              NETCONF Event Notifications              July 2008


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Definition of Terms  . . . . . . . . . . . . . . . . . . .  3
     1.2.  Motivation . . . . . . . . . . . . . . . . . . . . . . . .  4
     1.3.  Event Notifications in NETCONF . . . . . . . . . . . . . .  5
   2.  Notification-Related Operations  . . . . . . . . . . . . . . .  5
     2.1.  Subscribing to Receive Event Notifications . . . . . . . .  5
       2.1.1.    . . . . . . . . . . . . . . . .  6
     2.2.  Sending Event Notifications  . . . . . . . . . . . . . . .  9
       2.2.1.   . . . . . . . . . . . . . . . . . . . .  9
     2.3.  Terminating the Subscription . . . . . . . . . . . . . . .  9
   3.  Supporting Concepts  . . . . . . . . . . . . . . . . . . . . . 10
     3.1.  Capabilities Exchange  . . . . . . . . . . . . . . . . . . 10
       3.1.1.  Capability Identifier  . . . . . . . . . . . . . . . . 10
       3.1.2.  Capability Example . . . . . . . . . . . . . . . . . . 10
     3.2.  Event Streams  . . . . . . . . . . . . . . . . . . . . . . 10
       3.2.1.  Event Stream Definition  . . . . . . . . . . . . . . . 12
       3.2.2.  Event Stream Content Format  . . . . . . . . . . . . . 12
       3.2.3.  Default Event Stream . . . . . . . . . . . . . . . . . 12
       3.2.4.  Event Stream Sources . . . . . . . . . . . . . . . . . 12
       3.2.5.  Event Stream Discovery . . . . . . . . . . . . . . . . 12
     3.3.  Notification Replay  . . . . . . . . . . . . . . . . . . . 15
       3.3.1.  Overview . . . . . . . . . . . . . . . . . . . . . . . 15
       3.3.2.  Creating a Subscription with Replay  . . . . . . . . . 16
     3.4.  Notification Management Schema . . . . . . . . . . . . . . 16
     3.5.  Subscriptions Data . . . . . . . . . . . . . . . . . . . . 20
     3.6.  Filter Mechanics . . . . . . . . . . . . . . . . . . . . . 20
       3.6.1.  Filtering  . . . . . . . . . . . . . . . . . . . . . . 20
     3.7.  Message Flow . . . . . . . . . . . . . . . . . . . . . . . 20
   4.  XML Schema for Event Notifications . . . . . . . . . . . . . . 22
   5.  Filtering Examples . . . . . . . . . . . . . . . . . . . . . . 26
     5.1.  Subtree Filtering  . . . . . . . . . . . . . . . . . . . . 28
     5.2.  XPATH Filters  . . . . . . . . . . . . . . . . . . . . . . 29
   6.  Interleave Capability  . . . . . . . . . . . . . . . . . . . . 30
     6.1.  Description  . . . . . . . . . . . . . . . . . . . . . . . 30
     6.2.  Dependencies . . . . . . . . . . . . . . . . . . . . . . . 30
     6.3.  Capability Identifier  . . . . . . . . . . . . . . . . . . 30
     6.4.  New Operations . . . . . . . . . . . . . . . . . . . . . . 31
     6.5.  Modifications to Existing Operations . . . . . . . . . . . 31
   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 31
   8.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 32
   9.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 33
   10. Normative References . . . . . . . . . . . . . . . . . . . . . 33







Chisholm & Trevino          Standards Track                     [Page 2]

RFC 5277              NETCONF Event Notifications              July 2008


1.  Introduction

   [NETCONF] can be conceptually partitioned into four layers:

        Layer                            Example
    +-------------+      +-------------------------------------------+
    |   Content   |      |     Configuration data                    |
    +-------------+      +-------------------------------------------+
              |                           |
    +-------------+      +-------------------------------------------+
    | Operations  |      |, , |
    +-------------+      +-------------------------------------------+
              |                           |                    |
    +-------------+      +-----------------------------+       |
    |     RPC     |      |    ,        |       |
    +-------------+      +-----------------------------+       |
              |                           |                    |
    +-------------+      +-------------------------------------------+
    |  Transport  |      |   BEEP, SSH, SSL, console                 |
    |  Protocol   |      |                                           |
    +-------------+      +-------------------------------------------+

                                 Figure 1

   This document defines mechanisms that 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 and operations necessary to
   support this service.

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:  An agreement and method to receive event notifications
      over a NETCONF session.  A concept related to the delivery of
      notifications (if there are any to send) involving destination and
      selection of notifications.  It is bound to the lifetime of a
      session.








Chisholm & Trevino          Standards Track                     [Page 3]

RFC 5277              NETCONF Event Notifications              July 2008


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

   Event:  An event is something that happens that 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 to
      interested parties to notify them that this event has occurred.

   Replay:  The ability to send/re-send previously logged notifications
      upon request.  These notifications are sent asynchronously.  This
      feature is implemented by the NETCONF server and invoked by the
      NETCONF client.

   Stream:  An event stream is a set of event notifications matching
      some forwarding criteria and available to NETCONF clients for
      subscription.

   Filter:  A parameter that indicates which subset of all possible
      events are of interest.  A filter is defined as one or more filter
      elements [NETCONF], each of which identifies a portion of the
      overall filter.

1.2.  Motivation

   The motivation for this work is to enable the sending of asynchronous
   messages that are consistent with the data model (content) and
   security model used within a NETCONF implementation.

   The scope of the work aims at meeting the following operational
   needs:

   o  Initial release should ensure it supports notifications in support
      of configuration operations.

   o  It should be possible to use the same data model for notifications
      as for configuration operations.

   o  The solution should support a reasonable message size limit (i.e.,
      not too short).

   o  The notifications should be carried over a connection-oriented
      delivery mechanism.






Chisholm & Trevino          Standards Track                     [Page 4]

RFC 5277              NETCONF Event Notifications              July 2008


   o  A subscription mechanism for notifications should be provided.
      This takes into account that a NETCONF server does not send
      notifications before being asked to do so, and that it is the
      NETCONF client who initiates the flow of notifications.

   o  A filtering mechanism for sending notifications should be put in
      place within the NETCONF server.

   o  The information contained in a notification should be sufficient
      so that it can be analyzed independent of the transport mechanism.
      In other words, the data content fully describes a notification;
      protocol information is not needed to understand a notification.

   o  The server should have the capability to replay locally logged
      notifications.

1.3.  Event Notifications in NETCONF

   This memo 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 the subscription
   terminates for some other reason.  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.  Note that a subscription cannot be
   modified once created.

   The NETCONF server MUST accept and process the 
   operation, even while the notification subscription is active.  The
   NETCONF server MAY accept and process other commands; otherwise, they
   will be rejected and the server MUST send a 'resource-denied' error.
   A NETCONF server advertises support of the ability to process other
   commands via the :interleave capability.

2.  Notification-Related Operations

2.1.  Subscribing to Receive Event Notifications

   The event notification subscription is initiated by the NETCONF
   client and responded to by the NETCONF server.  A subscription is
   bound to a single stream for the lifetime of the subscription.  When
   the event notification subscription is created, the events of
   interest are specified.



Chisholm & Trevino          Standards Track                     [Page 5]

RFC 5277              NETCONF Event Notifications              July 2008


   Content for an event notification subscription can be selected by
   applying user-specified filters.

2.1.1.  

   Description:

      This operation initiates an event notification subscription that
      will send asynchronous event notifications to the initiator of the
      command until the subscription terminates.

   Parameters:

      Stream:

         An optional parameter, , that indicates which stream of
         events is of interest.  If not present, events in the default
         NETCONF stream will be sent.

      Filter:

         An optional parameter, , that indicates which subset of
         all possible events is of interest.  The format of this
         parameter is the same as that of the filter parameter in the
         NETCONF protocol operations.  If not present, all events not
         precluded by other parameters will be sent.  See section 3.6
         for more information on filters.

      Start Time:

         A parameter, , used to trigger the replay feature
         and indicate that the replay should start at the time
         specified.  If  is not present, this is not a replay
         subscription.  It is not valid to specify start times that are
         later than the current time.  If the  specified is
         earlier than the log can support, the replay will begin with
         the earliest available notification.  This parameter is of type
         dateTime and compliant to [RFC3339].  Implementations must
         support time zones.












Chisholm & Trevino          Standards Track                     [Page 6]

RFC 5277              NETCONF Event Notifications              July 2008


      Stop Time:

         An optional parameter, , used with the optional
         replay feature to indicate the newest notifications of
         interest.  If  is not present, the notifications will
         continue until the subscription is terminated.  Must be used
         with and be later than .  Values of  in
         the future are valid.  This parameter is of type dateTime and
         compliant to [RFC3339].  Implementations must support time
         zones.

   Positive Response:

      If the NETCONF server can satisfy the request, the server sends an
       element.

   Negative Response:

      An  element is included within the  if the
      request cannot be completed for any reason.  Subscription requests
      will fail if a filter with invalid syntax is provided or if the
      name of a non-existent stream is provided.

      If a  is specified in a request without having specified
      a , the following error is returned:

         Tag: missing-element

         Error-type: protocol

         Severity: error

         Error-info: : startTime

         Description: An expected element is missing.

      If the optional replay feature is requested but it is not
      supported by the NETCONF server, the following error is returned:

         Tag: operation-failed

         Error-type: protocol

         Severity: error

         Error-info: none





Chisholm & Trevino          Standards Track                     [Page 7]

RFC 5277              NETCONF Event Notifications              July 2008


         Description: Request could not be completed because the
         requested operation failed for some reason not covered by any
         other error condition.

      If a  is requested that is earlier than the specified
      , the following error is returned:

         Tag: bad-element

         Error-type: protocol

         Severity: error

         Error-info: : stopTime

         Description: An element value is not correct; e.g., wrong type,
         out of range, pattern mismatch.

      If a  is requested that is later than the current time,
      the following error is returned:

         Tag: bad-element

         Error-type: protocol

         Severity: error

         Error-info: : startTime

         Description: An element value is not correct; e.g., wrong type,
         out of range, pattern mismatch.

2.1.1.1.  Usage Example

   The following demonstrates creating a simple subscription.  More
   complex examples can be found in section 5.

   
       
       
   








Chisholm & Trevino          Standards Track                     [Page 8]

RFC 5277              NETCONF Event Notifications              July 2008


2.2.  Sending Event Notifications

   Once the subscription has been set up, the NETCONF server sends the
   event notifications asynchronously over the connection.

2.2.1.  

   Description:

      An event notification is sent to the client who initiated a
       command asynchronously when an event of
      interest (i.e., meeting the specified filtering criteria) has
      occurred.  An event notification is a complete and well-formed XML
      document.  Note that  is not a Remote Procedure Call
      (RPC) method but rather the top-level element identifying the one-
      way message as a notification.

   Parameters:

      eventTime

         The time the event was generated by the event source.  This
         parameter is of type dateTime and compliant to [RFC3339].
         Implementations must support time zones.

      Also contains notification-specific tagged content, if any.  With
      the exception of , the content of the notification is
      beyond the scope of this document.

   Response:

      No response.  Not applicable.

2.3.  Terminating the Subscription

   Closing of the event notification subscription can be done by using
   the  operation from the subscriptions session or
   terminating the NETCONF session (  ) or the underlying
   transport session from another session.  If a stop time is provided
   when the subscription is created, the subscription will terminate
   after the stop time is reached.  In this case, the NETCONF session
   will still be an active session.









Chisholm & Trevino          Standards Track                     [Page 9]

RFC 5277              NETCONF Event Notifications              July 2008


3.  Supporting Concepts

3.1.  Capabilities Exchange

   The ability to process and send event notifications is advertised
   during the capability exchange between the NETCONF client and server.

3.1.1.  Capability Identifier

   "urn:ietf:params:netconf:capability:notification:1.0"

3.1.2.  Capability Example

   
     
        
            urn:ietf:params:xml:ns:netconf:base:1.0
          
          
            urn:ietf:params:netconf:capability:startup:1.0
          
          
            urn:ietf:params:netconf:capability:notification:1.0
          
       
     4
   

3.2.  Event Streams

   An event stream is defined as a set of event notifications matching
   some forwarding criteria.

   Figure 2 illustrates the notification flow and concepts identified in
   this document.  It does not mandate and/or preclude an
   implementation.  The following is observed from the diagram below:
   System components (c1..cn) generate event notifications that are
   passed to a central component for classification and distribution.
   The central component inspects each event notification and matches
   the event notification against the set of stream definitions.  When a
   match occurs, the event notification is considered to be a member of
   that event stream (stream 1..stream n).  An event notification may be
   part of multiple event streams.








Chisholm & Trevino          Standards Track                    [Page 10]

RFC 5277              NETCONF Event Notifications              July 2008


   At some point after the NETCONF server receives the internal event
   from a stream, it is converted to an appropriate XML encoding by the
   server, and a  element is ready to send to all NETCONF
   sessions subscribed to that stream.

   After generation of the  element, access control is
   applied by the server.  If a session does not have permission to
   receive the , then it is discarded for that session,
   and processing of the internal event is completed for that session.

   When a NETCONF client subscribes to a given event stream, user-
   defined filter elements, if applicable, are applied to the event
   stream and matching event notifications are forwarded to the NETCONF
   server for distribution to subscribed NETCONF clients.  A filter is
   transferred from the client to the server during the  operation and applied against each 
   element generated by the stream.  For more information on filtering,
   see Section 3.6.

   A notification-logging service may also be available, in which case,
   the central component logs notifications.  The NETCONF server may
   later retrieve logged notifications via the optional replay feature.
   For more information on replay, see section 3.3.

   +----+
   | c1 |----+             available streams
   +----+    |    +---------+
   +----+    |    |central  |-> stream 1
   | c2 |    +--->|event    |-> stream 2     filter  +-------+
   +----+    |    |processor|-> NETCONF stream ----->|NETCONF|
    ...      |    |         |-> stream n             |server |
   System    |    +---------+                        +-------+
   Components|        |                                 /\
    ...      |        |                                 ||
   +----+    |        |       (------------)            ||
   | cn |----+        |       (notification)            ||
   +----+             +-----> (  logging   )            ||
                              (  service   )            ||
                              (------------)            ||
                                                        ||
                                                        ||
                                                        \/
                                                    +-------+
                                                    |NETCONF|
                                                    |client |
                                                    +-------+

                                 Figure 2



Chisholm & Trevino          Standards Track                    [Page 11]

RFC 5277              NETCONF Event Notifications              July 2008


3.2.1.  Event Stream Definition

   Event streams are predefined on the managed device.  The
   configuration of event streams is outside the scope of this document.
   However, it is envisioned that event streams are either pre-
   established by the vendor (pre-configured), user configurable (e.g.,
   part of the device's configuration), or both.  Device vendors may
   allow event stream configuration via the NETCONF protocol (i.e.,
    operation).

3.2.2.  Event Stream Content Format

   The contents of all event streams made available to a NETCONF client
   (i.e., the notification sent by the NETCONF server) MUST be encoded
   in XML.

3.2.3.  Default Event Stream

   A NETCONF server implementation supporting the notification
   capability MUST support the "NETCONF" notification event stream.
   This stream contains all NETCONF XML event notifications supported by
   the NETCONF server.  The exact string "NETCONF" is used during the
   advertisement of stream support during the  operation on
    and during the  operation.  Definition
   of the event notifications and their contents, beyond the inclusion
   of , for this event stream is outside the scope of this
   document.

3.2.4.  Event Stream Sources

   With the exception of the default event stream (NETCONF),
   specification of additional event stream sources (e.g., Simple
   Network Management Protocol (SNMP), syslog) is outside the scope of
   this document.  NETCONF server implementations may leverage any
   desired event stream source in the creation of supported event
   streams.

3.2.5.  Event Stream Discovery

   A NETCONF client retrieves the list of supported event streams from a
   NETCONF server using the  operation.

3.2.5.1.  Name Retrieval Using  Operation

   The list of available event streams is retrieved by requesting the
    subtree via a  operation.  Available event streams for
   the requesting session are returned in the reply containing the
    and  elements, where the  element is



Chisholm & Trevino          Standards Track                    [Page 12]

RFC 5277              NETCONF Event Notifications              July 2008


   mandatory, and its value is unique within the scope of a NETCONF
   server.  An empty reply is returned if there are no available event
   streams, due to user-specified filters on the  operation.

   Additional information available about a stream includes whether
   notification replay is available and, if so, the timestamp of the
   earliest possible notification to replay.

   The following example shows retrieving the list of available event
   stream list using the  operation.

   
     
      
        
           
         
      
     
   






























Chisholm & Trevino          Standards Track                    [Page 13]

RFC 5277              NETCONF Event Notifications              July 2008


   The NETCONF server returns a list of event streams available for
   subscription: NETCONF, SNMP, and syslog-critical in this example.

   
     
       
        
           
              NETCONF
              default NETCONF event stream
              
              true
              
                2007-07-08T00:00:00Z
              
           
           
              SNMP
              SNMP notifications
              false
           
           
             syslog-critical
             Critical and higher severity
             
             true
             
               2007-07-01T00:00:00Z
             
            
           
         
     
   

3.2.5.2.  Event Stream Subscription

   A NETCONF client may request from the NETCONF server the list of
   event streams available to this session and then issue a  request with the desired event stream name.  Omitting
   the event stream name from the  request results
   in subscription to the default NETCONF event stream.








Chisholm & Trevino          Standards Track                    [Page 14]

RFC 5277              NETCONF Event Notifications              July 2008


3.2.5.2.1.  Filtering Event Stream Contents

   The set of event notifications delivered in an event stream may be
   further refined by applying a user-specified filter supplied at
   subscription creation time (  ).  This is a
   transient filter associated with the event notification subscription
   and does not modify the event stream configuration.  The filter
   element is applied against the contents of the  wrapper
   and not the wrapper itself.  See section 5 for examples.  Either
   subtree or XPATH filtering can be used.

   XPATH support for the Notification capability is advertised as part
   of the normal XPATH capability advertisement.  If XPATH support is
   advertised via the XPATH capability, then XPATH is supported for
   notification filtering.  If this capability is not advertised, XPATH
   is not supported for notification filtering.

3.3.   Notification Replay

3.3.1.  Overview

   Replay is the ability to create an event subscription that will
   resend recently generated notifications, or in some cases send them
   for the first time to a particular NETCONF client.  These
   notifications are sent the same way as normal notifications.

   A replay of notifications is specified by including the optional
    parameter to the subscription command, which indicates
   the start time of the replay.  The end time is specified using the
   optional  parameter.  If not present, notifications will
   continue to be sent until the subscription is terminated.

   A notification stream that supports replay is not expected to have an
   unlimited supply of saved notifications available to accommodate any
   replay request.  Clients can query  and
    to learn about the availability of notifications
   for replay.

   The actual number of stored notifications available for retrieval at
   any given time is a NETCONF server implementation-specific matter.
   Control parameters for this aspect of the feature are outside the
   scope of this document.

   Replay is dependent on a notification stream supporting some form of
   notification logging, although it puts no restrictions on the size or
   form of the log, or where it resides within the device.  Whether or
   not a stream supports replay can be discovered by doing a 
   operation on the  element of the Notification Management



Chisholm & Trevino          Standards Track                    [Page 15]

RFC 5277              NETCONF Event Notifications              July 2008


   Schema and looking at the value of the  object.  This
   schema also provides the  element to indicate
   the earliest available logged notification.

3.3.2.  Creating a Subscription with Replay

   This feature uses optional parameters to the 
   command called  and .  identifies the
   earliest date and time of interest for event notifications being
   replayed and also indicates that a subscription will be providing
   replay of notifications.  Events generated before this time are not
   matched.  specifies the latest date and time of interest
   for event notifications being replayed.  If it is not present, then
   notifications will continue to be sent until the subscription is
   terminated.

   Note that  and  are associated with the time an
   event was generated by the event source.

   A  notification is sent to indicate that all of the
   replay notifications have been sent and must not be sent for any
   other reason.  If this subscription has a stop time, then this
   session becomes a normal NETCONF session again.  The NETCONF server
   will then accept  operations even if the server did not
   previously accept such operations due to lack of interleave support.
   In the case of a subscription without a stop time, after the
    notification has been sent, it can be expected that
   any notifications generated since the start of the subscription
   creation will be sent, followed by notifications as they arise
   naturally within the system.

   The  and  notifications cannot
   be filtered out.  They will always be sent on a replay subscription
   that specified a  and , respectively.

3.4.  Notification Management Schema

   This Schema is used to learn about the event streams supported on the
   system.  It also contains the definition of the  and
    notifications, which are sent to indicate that
   an event replay has sent all applicable notifications and that the
   subscription has terminated, respectively.









Chisholm & Trevino          Standards Track                    [Page 16]

RFC 5277              NETCONF Event Notifications              July 2008


 
 
     
         
             A schema that can be used to learn about current
             event streams.  It also contains the replayComplete
             and notificationComplete notification.
         
     

 
 
 

 

 
   
       
         
            
              The list of event streams supported by the
              system.  When a query is issued, the returned
              set of streams is determined based on user
              privileges.
            
          
          
            
              
                 
                   
                     Stream name, description, and other information.
                   
                 
                 
                   



Chisholm & Trevino          Standards Track                    [Page 17]

RFC 5277              NETCONF Event Notifications              July 2008


                     
                        
                          
                            The name of the event stream.  If this is
                            the default NETCONF stream, this must have
                            the value "NETCONF".
                          
                        
                     
                     
                        
                          
                            A description of the event stream, including
                            such information as the type of events that
                            are sent over this stream.
                          
                        
                     
                     
                      
                          
                            An indication of whether or not event replay
                            is available on this stream.
                          
                        
                     
                     
                       
                         
                        The timestamp of the creation of the log
                        used to support the replay function on
                        this stream.
                        Note that this might be earlier then
                        the earliest available
                        notification in the log.  This object
                        is updated if the log resets
                        for some reason.  This
                        object MUST be present if replay is
                        supported.
                          
                        
                      
                      



Chisholm & Trevino          Standards Track                    [Page 18]

RFC 5277              NETCONF Event Notifications              July 2008


                        
                          
                            The timestamp of the last notification
                            aged out of the log. This
                            object MUST be present if replay is
                            supported and any notifications
                            have been aged out of the log.
                          
                        
                      
                    
                  
                
              
            
          
     
     

     
         
             
         
     

     
                 
           
             This notification is sent to signal the end of a replay
             portion of a subscription.
           
         
         

     
         
             
         
     

     
                 
           
             This notification is sent to signal the end of a



Chisholm & Trevino          Standards Track                    [Page 19]

RFC 5277              NETCONF Event Notifications              July 2008


             notification subscription.  It is sent in the case
             that stopTime was specified during the creation of
             the subscription.
           
         
         

 

3.5.  Subscriptions Data

   Subscriptions are non-persistent state information, and their
   lifetime is defined by their session or by the  parameter.

3.6.  Filter Mechanics

   If a filter element is specified to look for data of a particular
   value, and the data item is not present within a particular event
   notification for its value to be checked against, the notification
   will be filtered out.  For example, if one were to check for
   'severity=critical' in a configuration event notification where this
   field was not supported, then the notification would be filtered out.

   For subtree filtering, a non-empty node set means that the filter
   matches.  For XPath filtering, the mechanisms defined in [XPATH]
   should be used to convert the returned value to boolean.

3.6.1.  Filtering

   Filtering is explicitly stated when the event notification
   subscription is created.  This is specified via the 'filter'
   parameter.  A Filter only exists as a parameter to the subscription.

3.7.  Message Flow

   The following figure depicts message flow between a NETCONF client
   (C) and NETCONF server (S) in order to create a subscription and
   begin the flow of notifications.  This subscription specifies a
   , so the server starts by replaying logged notifications.
   It is possible that many rpc/rpc-reply sequences occur before the
   subscription is created, but this is not depicted in the figure.










Chisholm & Trevino          Standards Track                    [Page 20]

RFC 5277              NETCONF Event Notifications              July 2008


                        C                           S
                        |                           |
                        |  capability exchange      |
                        |-------------------------->|
                        |<------------------------->|
                        |                           |
                        |      | (startTime)
                        |-------------------------->|
                        |<--------------------------|
                        |                |
                        |                           |
                        |             |
                        |<--------------------------|
                        |                           |
                        |             |
                        |<--------------------------|
                        |             | (replayComplete)
                        |<--------------------------|
                        |                           |
                        |                           |
                        |                           |
                        |             |
                        |<--------------------------|
                        |                           |
                        |                           |
                        |             |
                        |<--------------------------|
                        |                           |
                        |                           |

                                 Figure 3

   The following figure depicts message flow between a NETCONF client
   (C) and NETCONF server (S) in order to create a subscription and
   begin the flow of notifications.  This subscription specified a
    and  so it starts by replaying logged
   notifications and then returns to be a normal command-response
   NETCONF session after the  and 
   notifications are sent and it is available to process  requests.
   It is possible that many rpc/rpc-reply sequences occur before the
   subscription is created, but this is not depicted in the figure.










Chisholm & Trevino          Standards Track                    [Page 21]

RFC 5277              NETCONF Event Notifications              July 2008


                     C                           S
                     |                           |
                     |  capability exchange      |
                     |-------------------------->|
                     |<------------------------->|
                     |                           |
                     |      | (startTime,
                     |-------------------------->|  stopTime)
                     |<--------------------------|
                     |                |
                     |                           |
                     |             |
                     |<--------------------------|
                     |                           |
                     |             |
                     |<--------------------------|
                     |             | (replayComplete)
                     |<--------------------------|
                     |             |(notificationComplete)
                     |<--------------------------|
                     |                           |
                     |                           |
                     |                           |
                     |                      |
                     |-------------------------->|
                     |<--------------------------|
                     |                |
                     |                           |


                                 Figure 4

4.  XML Schema for Event Notifications

   The following [XMLSchema] defines NETCONF Event Notifications.


  






Chisholm & Trevino          Standards Track                    [Page 22]

RFC 5277              NETCONF Event Notifications              July 2008


    

     
       
         
           This import accesses the xml: attribute groups for the
           xml:lang as declared on the error-message element.
         
       
     

     
     



     

    
        
            
                
                    
                        
                            
                               An optional parameter that indicates
                               which stream of events is of interest.
                               If not present, then events in the
                               default NETCONF stream will be sent.
                            
                        
                    
                        
                            
                                
                                    An optional parameter that indicates
                                    which subset of all possible events
                                    is of interest.  The format of this
                                    parameter is the same as that of the
                                    filter parameter in the NETCONF
                                    protocol operations.  If not
                                    present, all events not precluded
                                    by other parameters will be sent.



Chisholm & Trevino          Standards Track                    [Page 23]

RFC 5277              NETCONF Event Notifications              July 2008


                                
                            
                        
                    
                        
                            
                                A parameter used to trigger the replay
                                feature indicating that the replay
                                should start at the time specified.  If
                                start time is not present, this is not a
                                replay subscription.
                            
                        
                    
                    
                        
                            
                                An optional parameter used with the
                                optional replay feature to indicate the
                                newest notifications of interest.  If
                                stop time is not present, the
                                notifications will continue until the
                                subscription is terminated.  Must be
                                used with startTime.
                            
                        
                    
                
            
        
    
    
        
            
                The name of an event stream.
            
        
        
    










Chisholm & Trevino          Standards Track                    [Page 24]

RFC 5277              NETCONF Event Notifications              July 2008


    
        
            
                The command to create a notification subscription.  It
                takes as argument the name of the notification stream
                and filter.  Both of those options
                limit the content of the subscription.  In addition,
                there are two time-related parameters, startTime and
                stopTime, which can be used to select the time interval
                of interest to the notification replay feature.
            
        
    



     
     

    

    
        
            
              
                
                The time the event was generated by the event source.
                
              
            
            
        
    

    
  












Chisholm & Trevino          Standards Track                    [Page 25]

RFC 5277              NETCONF Event Notifications              July 2008


5.  Filtering Examples

   The following section provides examples to illustrate the various
   methods of filtering content on an event notification subscription.

   In order to illustrate the use of filter expressions, it is necessary
   to assume some of the event notification content.  The examples below
   assume that the event notification schema definition has an 
   element at the top level consisting of the event class (e.g., fault,
   state, config), reporting entity, and either severity or operational
   state.

   Examples in this section are generated from the following fictional
   Schema.

   
   

       

       
           
               
                   
                       
                       
                           
                               
                                   
                               
                           
                       
                       
                           
                           
                       
                   
               
           
       




Chisholm & Trevino          Standards Track                    [Page 26]

RFC 5277              NETCONF Event Notifications              July 2008


       

   

   The above fictional notification definition could result in the
   following sample notification list, which is used in the examples in
   this section.

   
      2007-07-08T00:01:00Z
      
         fault
         
             Ethernet0
         
         major
       
   

   
      2007-07-08T00:02:00Z
      
          fault
          
              Ethernet2
          
          critical
       
   

   
      2007-07-08T00:04:00Z
      
          fault
          
               ATM1
           
           minor
      
   






Chisholm & Trevino          Standards Track                    [Page 27]

RFC 5277              NETCONF Event Notifications              July 2008


   
     2007-07-08T00:10:00Z
     
         state
         
             Ethernet0
         
         enabled
      
   

5.1.  Subtree Filtering

   XML subtree filtering is not well-suited for creating elaborate
   filter definitions given that it only supports equality comparisons
   and application of the logical OR operators (e.g., in an event
   subtree, give me all event notifications that have severity=critical,
   severity=major, or severity=minor).  Nevertheless, it may be used for
   defining simple event notification forwarding filters as shown below.

   The following example illustrates how to select fault events which
   have severities of critical, major, or minor.  The filtering criteria
   evaluation is as follows:

   ((fault & severity=critical) | (fault & severity=major) | (fault &
   severity=minor))

        
          
            
              
                fault
                critical
              
              
                fault
                major
              
              
                fault
                minor
              
            
          
        



Chisholm & Trevino          Standards Track                    [Page 28]

RFC 5277              NETCONF Event Notifications              July 2008


   The following example illustrates how to select state or config
   EventClasses or fault events that are related to card Ethernet0.  The
   filtering criteria evaluation is as follows:

   ( state | config | ( fault & ( card=Ethernet0)))


      
        
          
            state
          
          
            config
          
          
            fault
            
              Ethernet0
            
          
        
      


5.2.  XPATH Filters

   The following [XPATH] example illustrates how to select fault
   EventClass notifications that have severities of critical, major, or
   minor.  The filtering criteria evaluation is as follows:

   ((fault) & ((severity=critical) | (severity=major) | (severity =
   minor)))

      
        
          
        
      




Chisholm & Trevino          Standards Track                    [Page 29]

RFC 5277              NETCONF Event Notifications              July 2008


   The following example illustrates how to select state and config
   EventClasses or fault events of any severity that come from card
   Ethernet0.  The filtering criteria evaluation is as follows:

   ( state | config | (fault & card=Ethernet0))

     
        
             
       
     

6.  Interleave Capability

6.1.  Description

   The :interleave capability indicates that the NETCONF peer supports
   the ability to interleave other NETCONF operations within a
   notification subscription.  This means the NETCONF server MUST
   receive, process, and respond to NETCONF requests on a session with
   an active notification subscription.  This capability helps
   scalability by reducing the total number of NETCONF sessions required
   by a given operator or management application.

6.2.  Dependencies

   This capability is dependent on the notification capability being
   supported.

6.3.  Capability Identifier

   The :interleave capability is identified by the following capability
   string:

   urn:ietf:params:netconf:capability:interleave:1.0










Chisholm & Trevino          Standards Track                    [Page 30]

RFC 5277              NETCONF Event Notifications              July 2008


6.4.  New Operations

   None.

6.5.  Modifications to Existing Operations

   When a  is sent while another subscription is
   active on that session, the following error will be returned:

      Tag: operation-failed

      Error-type: protocol

      Severity: error

      Error-info: none

      Description: Request could not be completed because the requested
      operation failed for some reason not covered by any other error
      condition.

7.  Security Considerations

   The security considerations from the base [NETCONF] document also
   apply to the Notification capability.

   The access control framework and the choice of transport will have a
   major impact on the security of the solution.

   The  elements are never sent before the transport layer
   and the NETCONF layer, including capabilities exchange, have been
   established and the manager has been identified and authenticated.

   It is recommended that care be taken to secure execution:

   o   invocation

   o   on read-only data models

   o   content

   Secure execution means ensuring that a secure transport is used as
   well as ensuring that the user has sufficient authorization to
   perform the function they are requesting against the specific subset
   of NETCONF content involved.  When a  is received that refers to
   the content defined in this memo, clients should only be able to view
   the content for which they have sufficient privileges.  A create
    operation can be considered like a deferred



Chisholm & Trevino          Standards Track                    [Page 31]

RFC 5277              NETCONF Event Notifications              July 2008


   , and the content that different users can access may vary.
   This different access is reflected in the  that
   different users are able to subscribe to.

   One potential security issue is the transport of data from non-
   NETCONF streams, such as syslog and SNMP.  This data may be more
   vulnerable (or less vulnerable) when being transported over NETCONF
   than when being transported using the protocol normally used for
   transporting it, depending on the security credentials of the two
   subsystems.  The NETCONF server is responsible for applying access
   control to stream content.

   The contents of notifications, as well as the names of event streams,
   may contain sensitive information and care should be taken to ensure
   that they are viewed only by authorized users.  The NETCONF server
   MUST NOT include any content in a notification that the user is not
   authorized to view.

   If a subscription is created with a , the NETCONF session
   will return to being a normal command-response NETCONF session when
   the replay is completed.  It is the responsibility of the NETCONF
   client to close this session when it is no longer of use.

   If a malicious or buggy NETCONF client sends a number of  requests, then these subscriptions accumulate and may
   use up system resources.  In such a situation, subscriptions can be
   terminated by terminating the suspect underlying NETCONF sessions
   using the  operation.

8.  IANA Considerations

   This document registers three URIs for the NETCONF XML namespace in
   the IETF XML registry [RFC3688].

   Following the format in RFC 3688, IANA has made the following
   registration.  Note that the capability URNs are also compliant to
   section 10.3 of [NETCONF].

   +--------------------+----------------------------------------------+
   | Index              | Capability Identifier                        |
   +--------------------+----------------------------------------------+
   | :notification      | urn:ietf:params:netconf:capability:          |
   |                    | notification:1.0                             |
   |                    |                                              |
   | :interleave        | urn:ietf:params:netconf:capability:          |
   |                    | interleave:1.0                               |
   +--------------------+----------------------------------------------+




Chisholm & Trevino          Standards Track                    [Page 32]

RFC 5277              NETCONF Event Notifications              July 2008


   URI: urn:ietf:params:xml:ns:netmod:notification

   URI: urn:ietf:params:xml:ns:netconf:notification:1.0

   Registrant Contact: The IESG.

   XML: N/A, the requested URI is an XML namespace.

   In addition, IANA registered the XML Schema defined in Section 4.

9.  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, David Perkins, and the following
   additional people from the Montreal editing session: Balazs Lengyel,
   Phil Shafer, Rob Enns, Andy Bierman, Dan Romascanu, Bert Wijnen,
   Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig,
   Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, and
   William Chow.  We would also like to thank Li Yan for his numerous
   reviews, as well as Suresh Krishnan for his gen-art review of the
   document.

10.  Normative References

   [NETCONF]    Enns, R., Ed., "NETCONF Configuration Protocol",
                RFC 4741, December 2006.

   [RFC2119]    Bradner, S., "Key words for use in RFCs to Indicate
                Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3339]    Klyne, G., Ed. and C. Newman, "Date and Time on the
                Internet: Timestamps", RFC 3339, July 2002.

   [RFC3688]    Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
                January  2004.

   [XML]        World Wide Web Consortium, "Extensible Markup Language
                (XML) 1.0", W3C XML, February 1998,
                .

   [XMLSchema]  Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn,
                "XML Schema Part 1: Structures Second Edition", W3C http
                ://www.w3.org/TR/2004/REC-xmlschema-1-20041028/
                structures.html, October 2004.



Chisholm & Trevino          Standards Track                    [Page 33]

RFC 5277              NETCONF Event Notifications              July 2008


   [XPATH]      Clark, J. and S. DeRose, "XML Path Language (XPath)
                Version 1.0",
                W3C http://www.w3.org/TR/1999/REC-xpath-19991116,
                November 1999.

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          Standards Track                    [Page 34]

RFC 5277              NETCONF Event Notifications              July 2008


Full Copyright Statement

   Copyright (C) The IETF Trust (2008).

   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.












Chisholm & Trevino          Standards Track                    [Page 35]


 

RFC, FYI, BCP