notification-08 comments

[Andy Bierman <ietf@andybierman.com>]

Hi,

I am leaving out bugs already identified in other comments...

[I am getting as picky as I know the IESG will be when they review it.]

-----------------------------------------------

1.1 Terms:

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

5.1, para 1:

   XML subtree filtering is not well suited for creating elaborate
   filter definitions given that it only supports equality comparisons
   and logical OR operations (e.g., in an event subtree give me all
                  ^^^^^^^^^^



6, para 4:

   It is recommended that care be taken to ensure the secure operation
   of the following commands:                                ^^^^^^^^^

The second sentence in the operation is not true, since it is
used differently in sec. 5.1 and 6.

-------------------------------------------------

1.3, para 2:

 A NETCONF server is will not read
                  ^^

extra word

-------------------------------------------------

1.4, bullet 1:

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

Reword to something less mangled, but I'm not even sure what
this means. perhaps remove, since the contents of a stream
are internal to the agent implementation.

---------------------------------------------------

1.4, bullet 2:

  o  Data content must not preclude the use of the same data model as
      used in configuration

I have no idea what this means, please elaborate.

--------------------------------------------------

1.4, bullet 3:

   o  Solution should support a reasonable message size limit (ie, not
      too short)

NETCONF has no message size limits (except the message-id attribute),
so I'm not sure why this needs to be here.  There are no size limits
in this document either.

s/ie,/i.e.,/ (BTW)

----------------------------------------------------

1.4, all bullets:

Add period and make all bullets complete sentences.

---------------------------------------------------

2.1:

This section should clearly state that a subscription is bound
to a single stream for the lifetime of the subscription.

----------------------------------------------------

2.1.1, Negative Response:

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

Previously, 'startTime' and 'stopTime' were single-quoted.
Be consistent throughout the draft one way or the other.

----------------------------------------------------

2.1.1, Negative Response:

      In each sub-section, clearly state which child element in the
      <create-subscription> element is associated with the parameter.

----------------------------------------------------

2.1.1, Negative Response:

       Error-info: <badElement>: startTime
                   ^^^^^^^^^^^^

Change to <bad-element>

-----------------------------------------------------

2.1.1.1:


   <netconf:rpc message-id="101"
         xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
       <create-subscription
           xmlns="urn:ietf:params:netconf:capability:notification:1.0">
       </create-subscription>
   </netconf:rpc>

This section needs some explanatory text, and filled in with
most or all of the parameters.

Also the 2nd namespace URI is wrong (already mentioned in a previous email).

-----------------------------------------------------

2.2.1, para 1:

   An event notification is sent to the client who initiated a
      <create-subscription> command asynchronously when an event of
      interest (i.e., meeting the specified filtering criteria) to them
                                                                ^^^^^^^
      has occurred.

Remove extra text.

------------------------------------------------------

2.2.1, para 2:


         Contains notification-specific tagged content.  The content of
         the data tag is beyond the scope of this document.

This section (on parameters) is insufficient.
This document needs to clearly explain how the child node
of the <notification> node is defined, similar to RFC 4741, sec 4.1.

-------------------------------------------------------

3.2:

Much improved text and diagram, but needs a little more text.
It should be clear that the 'central event processor' generates
events and transfers them to the correct stream(s) in an
inaccessible, internal format.

Suggest:

At some point after the 'netconf server'
receives the internal event from a stream, it is converted to XML
encoding by the agent, and a <notification> element is
ready to send to all NETCONF sessions subscribed to that stream.

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

If the session has permission to receive the <notification> element,
then the filter associated with its subscription is applied (if any),
except if this is a <replayComplete> notification.

-------------------------------------------------------

3.2, para 3:


   When a NETCONF client subscribes to a given event stream, user-
   defined filters, if applicable, are applied to the event stream and
   matching event notifications are forwarded to the NETCONF server for
   distribution to subscribed NETCONF clients.  For more information on
   filters, see section 3.6.


The end of the first sentence, especially 'forwarded to the NETCONF server',
is confusing.  It sounds like the 'forwarder' is the client, not
the central event processor.

This para should state somehow:

Filters are transferred from the client to the agent during
the <create-subscription> operation and applied against each <notification>
element generated by the stream.

----------------------------------------------------------

3.2.1, para 1:

  may allow event stream configuration via NETCONF protocol (i.e.,

s/via NETCONF/via the NETCONF/

-----------------------------------------------------------

3.2.1, para 1:

   established by the vendor (pre-configured) or user configurable
                                             ^ missing comma
   (e.g., part of the device's configuration) or both.
                                             ^ missing comma

Add missing commas.

-------------------------------------------------------------

3.2.2:

   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.

This is a round-about way to state the obvious -- the contents
of the <notification> element must be encoded in XML.

--------------------------------------------------------------

3.2.3:

   A NETCONF server implementation supporting the notification
   capability must support the "NETCONF" notification event stream.

Clearly state that the exact string "NETCONF" must match the
contents of the <stream> element in the <create-subscription> RPC.
Also, an <eventStream> element will be present in the agent, with
a <name> value that matches this string.

---------------------------------------------------------------

3.2.4:

   (e.g., SNMP, syslog, etc.) is outside the scope of this document.
                      ^^^^^^

Remove redundant text (use e.g., or etc, but never both).

---------------------------------------------------------------


3.2.5:

  NETCONF server using the <get> RPC request.
                                 ^^^^^^^^^^^

Use 'operation' instead to be consistent.

----------------------------------------------------------------

3.2.5.1:

This section should list each child element of the <stream> element
and explain its purpose and implementation requirements, instead
of burying these important details in the XSD.

------------------------------------------------------------------

3.2.5.1:

Element naming is inconsistent.  Plural form is <eventStreams>
and single form is <stream>.  Suggest changing <stream> to <eventStream>.

------------------------------------------------------------------

3.2.5.1, para 1:

   The returned list must only include the names of
   those event streams for which the NETCONF session has sufficient
   privileges.  The NETCONF session privileges are determined via access
   control mechanisms which are beyond the scope of this document.  An
   empty reply is returned if there are no available event streams.

This portion of the paragraph should be removed.
Access control should only be conceptually inserted after
<notification> generation by the 'netconf server',
and before any filters are applied.

------------------------------------------------------------------

Figure 5:


 <rpc message-id="101"
    xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

   <get>
    <filter type="subtree">
      <eventStreams xmlns="urn:ietf:params:xml:ns:netmod:notification"/>
    </filter>
   </get>
 </rpc>

Remove extra line before <get>

The <netconf> element is missing.
The 'xmlns' should be in that element instead.

----------------------------------------------------------------------

Figure 6:

  <rpc-reply message-id="101"
                 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <data>
   <eventStreams xmlns="urn:ietf:params:xml:ns:netmod:notification">


The <netconf> element is also missing from the <rpc-reply>.

-----------------------------------------------------------------

3.2.5.2.1, para 1:


   The set of event notifications delivered in an event stream may be
   further refined by applying a user-specified filter at subscription
   creation time

s/filter at/filter supplied at/

------------------------------------------------------------------

3.3.1, para 2:

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

Use single quotes for 'startTime' and 'stopTime'.

-------------------------------------------------------------------

3.3.1, para 4:

   Control parameters for this aspect of the feature are outside the
   scope of the current document.
                ^^^^^^^

s/current/this/

--------------------------------------------------------------------

3.3.1, para 5:

 This schema also provides the replayLogStartTime element to
 indicate the earliest available logged notification.

Add < > to replayLogStartTime.

This sentence shows why the parameter needs to be clearly defined
in sec 3.2.5.1.

Is this parameter the time the agent started collecting or
the time the first notification was added, sometime after
the agent started collecting?  The spec must be clear on which one.
(IMO, the former is the intuitive choice.)

--------------------------------------------------------------------

3.3.2, para 2:

   Note that startTime and stopTime are associated with the time an
   event was generated by the system.

Add single quotes to 'startTime' and 'stopTime'.
The phrase 'by the system' is vague.  Which component in fig. 4
is the system?

----------------------------------------------------------------------

3.3.2, para 3:

   A replayComplete notification is sent to indicate that all of the
   replay notifications have been sent.

Use 'replayComplete' or <replayComplete>.

   becomes a normal NETCONF session again.

Indicate that the agent will now accept <rpc> operations.
Any requests which have been received but not processed by
the agent will now be processed in the order they were received.

  creation will be sent followed by notifications as they arise
                       ^ missing comma

-----------------------------------------------------------------------

3.3.3, para 1:

  The replayComplete notification is the last notification sent over a
  replay subscription.

Single quote or element form of replayComplete

Sentence is confusing, since more notifications can be sent after <replayComplete>.
You mean this special notification is sent after all replayed notifications
have been sent.

------------------------------------------------------------------------

3.3.3, para 2:

   The replayComplete can not be filtered out.  It will always be sent
   on a relay subscription that specified a stop time.

s/can not/cannot/

s/relay/replay/

-------------------------------------------------------------------------

3.4, para 1:

  This Schema is used to learn about the event streams supported on the

s/Schema/schema/

  It also contains the definition of the replayComplete

s/replayComplete/<replayComplete> element/

   which
   is sent to indicate that an event replay has sent all applicable
   notifications."

Suggest removing or make the terminology consistent.

------------------------------------------------------------------------

3.4: XSD:

much improved.
Need to update some namespace URIs (use xml:ns form, not netconf:capability form).

Should also add comment above the 2nd <import> that the
"http://www.iana.org/assignments/xml-registry/schema/notification.xsd";
value is a placeholder and the actual value will be assigned by IANA.

-------------------------------------------------------------------------

3.5:

   While it may be possible to retrieve information about subscriptions
   via a get operation, subscriptions are not stored configuration.
   They are non-persistent state information and their lifetime is
   defined by their session.

This whole section is confusing, since there is no schema in the
document related to this section.  This document should only focus
on the standard, and the standard has no mechanism to retrieve
this information.

Suggest removing this section.

-----------------------------------------------------------------

3.6, para 1:

   When multiple filter elements are specified, they are applied
   collectively, so event notifications need to pass all specified
   filters in order to be sent to the subscriber.

Need to remove this sentence. There is at most one conceptual <filter>
element associated with a subscription.

   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.

This is not precise enough.
For starters, subtree and Xpath filters return a subset of
conceptual 'input node set', not a boolean expression.
The output node set is returned in the <get> or <get-config> response.

What does it mean to convert this mechanism to a boolean filter?

Does it mean that any output at all from the filter means
it 'passes', and an empty output node set means the filter 'failed'?


----------------------------------------------------------------

3.6, para 2:

   The order that filter elements are applied does not matter since the
   resulting set of notifications is the intersection of the set of
   notifications that pass each filtering criteria.

This sentence is confusing and should be removed.
This document has no business discussing how filters defined in RFC 4741
are implemented within an agent.  Also, there is only one conceptual
filter per subscription.

------------------------------------------------------------------

3.6.1:

   Filters only exist as parameters to the subscription.

Remove or change to indicate there is only one filter element.

------------------------------------------------------------------

figure 8:

This figure (or another one) should support the replay mode,
and show the replayComplete notification, followed by another
<rpc>/<rpc-reply> sequence.

This section should show the conceptual 'normal mode' and 'notification mode'
transitions as well.

-------------------------------------------------------------------

3.7, para 1:

  stopTime in a replay subscription

s/stopTime/'stopTime'/

---------------------------------------------------------------

4.:

targetNamespace URI form should be 'ns' not 'capability'.

---------------------------------------------------------------

4.<filter>:

                                 <xs:documentation>
                                    An optional parameter that indicates
                                    which subset of all possible events
                                    are 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.
                                </xs:documentation>


See comment above on 3.6, para 1.
The precise nature of notification filtering must not
contradict, and should not duplicate, sec. 3.6.

This definition of a filter output is not at all how filtering
works for the <get> and <get-config> operations.
The WG agreed at the start we are not creating a new type
of filtering, just reusing the existing filtering.

----------------------------------------------------------------

4. (and 3.4).<schema>:

This XSD assigns the default namespace to the target namespace:

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

However, the XSD in 3.4 does not use a default namespace at all:

   xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"

It uses the prefix 'manageEvent' instead.

IMO, the XSD in sec. 3.4 should be changed to match sec 4.
XSD is hard enough to read as it is without electing to make
it even more verbose.  It is also customary to use short
prefixes (like 2 or 3 chars max).


------------------------------------------------------------------

4. (and 3.4).<schema>:

There are two missing attributes in this element in both schemas:

     xml:lang="en"

     version="1.0"

------------------------------------------------------------------

4.<stream>:


Only the 'replayLogStartTime' element has a <documentation> node.
All the elements in this sequence should have them.

-------------------------------------------------------------------

5.

IMO, this section needs to be moved to Appendix A, and
not be included in the normative part of the document.

Also, the description of the assumed data model needs to be
moved from 5.1 to this section, since it is used in 5.2 as well.
This data model should probably have an XSD as well.

---------------------------------------------------------------------

5.1: para 2:

 (e.g., fault,
   state, config, etc.)

s/config, etc.)/config)

 elements <eventEntry> consisting of the event class (e.g., fault,

s/<eventEntry>/<event>/

--------------------------------------------------------------------


5.2, para 1:

Should mention that the same notification data model as 5.1 is assumed.

----------------------------------------------------------------------

6., para 2:

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

What impact would that be exactly?

------------------------------------------------------------------------

6., para 4:

  It is recommended that care be taken to ensure the secure operation
   of the following commands:

   o  <create-subscription> invocation

   o  read-only data models

   o  read-write data models

   o  notification content

Bullets 2 - 4 are not commands.
NETCONF has operations, not commands, BTW.

------------------------------------------------------------------------

6., para 5:

   One issue related to the notifications draft is the transport of data
   from non-netconf streams,

s/One issue related to the notifications draft is/One issue is/

s/non-netconf/non-NETCONF/


   over netconf than when being transported using the protocol normally

s/netconf/NETCONF/

   The NETCONF server is responsible for providing
   access control to stream content.

s/providing/applying/

-------------------------------------------------------------------------

6., para 6:

   If a user does not have permission to view content via other NETCONF
   operations it does not have permission to access that content via
   Notifications.  If a user is not permitted to view one element in the
   content of the notification, the notification is not sent to that
   user.

The first sentence is way out of scope and needs to be removed.
The access model in use is not defined in this document.
That model may not couple the configuration in this manner.

---------------------------------------------------------

7.:

There are 3 registrations, not 2.

1) Capability for notification support, used in <hello>

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

2) Namespace URI for the XSD in 3.4:

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

3) Namespace URI for the XSD in 4.:

   "urn:ietf:params:xml:ns:netconf:notification"


The 'targetNamespace' value currently in use in 4. is wrong:

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


------------------------------------------------------------


















--
to unsubscribe send a message to netconf-request@ops.ietf.org with
the word 'unsubscribe' in a single line as the message text body.
archive: <http://ops.ietf.org/lists/netconf/>