Subject: [Netconf] rpc-error details

From: Andy Bierman <[email-masked]>
Date: Wed, 19 May 2010 15:22:59 -0700

Hi,

I want to check consensus on 4 little details for <rpc-error>
in 4741bis.  Note that these would only apply if the client and server
both request base:1.1 in their <hello> message:

  1) rpc-warning error-tag

     Does the WG want to add a new error-tag that would allow
     new NETCONF capabilities and YANG data models to utilize the
     error-severity=warning mode. The next chance to add warnings
     may not be for 3-5 years.  Just because there are no protocol
     warnings is irrelevant.  This error could only be allowed for
     error-type=application, although I think the 'validate'
     operation should be able to issue implementation-specific warnings.

     [Default: do not add]

  2) capability-changed error-tag

    Does the WG want to add a new error-tag to indicate that the
    operation did not have a specific error, but rather the
    session capabilities have changed and no further operations
    will be accepted. (TBD: operation to clear this state.)

    [Default: add (consensus from Anaheim)]

  3) Change 'error-app-tag' from maxOccurs=1 to maxOccurs=unbounded

   Sometimes the standard modules require a particular error-app-tag.
   Sometimes the YANG module has an error-app-tag specified by the
   YANG author.  Sometimes vendors hardwire their own error-app-tag
   to support their own applications.

   [Default: do not change]

  4) Change 'error-message' from maxOccurs=1 to maxOccurs=unbounded

   Sometimes the standard modules require a particular error-message.
   Sometimes the YANG module has an error-message specified by the
   YANG author.  Sometimes vendors hardwire their own error-message
   to support their own applications.  Some servers may want to
   support multiple languages at once, but the current spec does
   not allow it.

   [Default: do not change]

Andy

---

From: Kent Watsen <[email-masked]>
Date: Thu, 20 May 2010 13:40:22 -0700

>      operation should be able to issue implementation-specific warnings.

Is the idea to allow a server to return an <rpc-warning> instead of a <rpc-error> with error-severity=warning?   I think that this would be nice to have as currently we have to document that clients must not assume <rpc-error> means there was an error - it's a bit confusing...

BTW, our only use for warnings may interest the group.  Essentially, we allow a <commit> RPC to return a warning to identify any implicit-changes the device made (e.g. hashing a clear-text password) that warrant the application to <get-config> the new value from the device.  Specifically, we have:

  * for each implicit-change, the <rpc-reply> contains one <rpc-error>
  * each <rpc-error> is filled in as follows:

    error-type       "application"
    error-tag        "partial-operation"
    error-severity   "warning"
    error-app-tag    "implicit-change"
    error-path       The XPath to the node(s) that changed
    error-message    A human-readable string indicating the reason for 
                     the implicit-change.  If no reason can be provided, 
                     the string "The specified nodes have been implicitly
                     changed" should be used

Thanks,
Kent

---

From: Andy Bierman <[email-masked]>
Date: Thu, 20 May 2010 13:51:25 -0700

Kent Watsen wrote:
>> 1) rpc-warning error-tag
>>
>> Does the WG want to add a new error-tag that would allow new
>> NETCONF capabilities and YANG data models to utilize the
>> error-severity=warning mode. The next chance to add warnings may
>> not be for 3-5 years.  Just because there are no protocol warnings
>> is irrelevant.  This error could only be allowed for
>> error-type=application, although I think the 'validate' operation
>> should be able to issue implementation-specific warnings.
>>
>> [Default: do not add]
>
>
>
> Is the idea to allow a server to return an <rpc-warning> instead of a
> <rpc-error> with error-severity=warning?   I think that this would be
> nice to have as currently we have to document that clients must not
> assume <rpc-error> means there was an error - it's a bit confusing...
>

No.

The element is still <rpc-error>.
We currently have no error-tag that uses
an errorseverity value of 'warning'.
Since error-tag values are hardwired,
that means nobody can use error-severity=warning.

>
> BTW, our only use for warnings may interest the group.  Essentially,
> we allow a <commit> RPC to return a warning to identify any
> implicit-changes the device made (e.g. hashing a clear-text password)
> that warrant the application to <get-config> the new value from the
> device.  Specifically, we have:
>
> error-type       "application" error-tag        "partial-operation"
> error-severity   "warning" error-app-tag    "implicit-change"
> error-path       The XPath to the node(s) that changed error-message

This does not follow the rules in RFC 4741 for
a partial-operation error-tag.  Technically,
a server MUST encode <rpc-error> according
to the specification.

> A human-readable string indicating the reason for the
> implicit-change.  If no reason can be provided, the string "The
> specified nodes have been implicitly changed" should be used
>

I am not trying to standardize particular warnings.
I am trying to make it legal to use any sort of
error-severity=warning.

> Thanks, Kent

Andy

---

From: Andy Bierman <[email-masked]>
Date: Thu, 20 May 2010 14:15:01 -0700

Kent Watsen wrote:
>> ...

FYI,

the partial-operation error-tag is going away in 4741bis.

The full proposal for warnings has been posted,
but I will try to rewrite it here:

   error-type:  application
   error-tag: rpc-warning
   error-severity: warning
   error-app-tag: [set by application]
   error-path: [set by application]
   error-message: [human readable warning message]
   error-info:  [set by application]

Andy

---

From: Andy Bierman <[email-masked]>
Date: Fri, 21 May 2010 04:49:33 -0700

Martin Bjorklund wrote:
> Andy Bierman <[email-masked]> wrote:
>   
>> Hi,
>>
> +1 to the default
> If we want to add warnings, we need to describe how they are supposed
> to work.  For example, it must be clear that clients cannot just check
> for <ok/> if they want to know if something succeeded or not.  They
> also must check all <rpc-error> elements for warnings.
>
>   

Of course the client would have to check the error-severity
field to see if the response is an error or a warning.
That is what the WG intended when it was written,
Other than that, why is this a problem?
Only a base:1.1 session would be allowed to use it.

By definition, warnings are fuzzy and even implementation-specific.
Maybe we should remove error-severity since it is just
wasting space in the PDU.

> +1 to the default
-1 for me.
The procedures for this complicated mess are not written down,
and the WG doesn't agree on the, or even the need for this
entire 'solution'.  For example, a simple notification would
be good enough, for sessions that actually cared about this condition.

> +1 to the default
> I am not sure it would be correct to use error-app-tags in this way.
>
>
>   

IMO, error-app-tag is kind of useless because an application
is never sure if its error-app-tag will be present,
or if some standard has required an arbitrary string
be used instead.  If applications could look for 1 of N
error-app-tags (e.g., 1 is an alias for another) then
the original intent of error-app-tag would not be lost,
like it is now.

> I would not mind this change.  It _can_ be achieved by sending
> multiple rpc-errors, but if you want to support mulitple langauges,
> this change would be a better solution, since it is clear that each
> error-message describes the same error.
>
>   
> /martin
>
>   
Andy

---

From: Andy Bierman <[email-masked]>
Date: Fri, 21 May 2010 08:19:41 -0700

> also must check all <rpc-error> elements for warnings.

You are right -- it is clear that changing the <ok> or <rpc-error>
logic in applications would be a major change.
So if we ever do add warnings, it would probably need to
be in a new <rpc-warning> element that was allowed
to be sent along with <ok>.

It doesn't seem like we will ever set the error-severity
field to 'warning'.

>>     [Default: add (consensus from Anaheim)]

My new concern:  I would like to see the entire solution package
in more detail, especially the mechanism to clear this error
condition.

It is not that clear to me that a client developer would
want to set the 'on-capability-change=error' parameter
in the <hello> without a way to clear the error.
Otherwise, the server should just drop the session
since that's all the client can do anyway.

Also, resending the <hello> requires that
the client save each <hello>.  A notification that provided
patches to the the current capabilities seems easier to use
for the client.  A capability-changed event seems to be the exact
sort of intended use for RFC 5277.  I don't understand
why we don't use it.

....
Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 21 May 2010 13:12:10 +0200 (CEST)

+1 to the default

+1 to the default

+1 to the default

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 21 May 2010 13:27:49 +0200 (CEST)

Hi Kent,

Kent Watsen <[email-masked]> wrote:
> BTW, our only use for warnings may interest the group.  Essentially, we allow
> a <commit> RPC to return a warning to identify any implicit-changes the device
> made (e.g. hashing a clear-text password) that warrant the application to
> <get-config> the new value from the device.  Specifically, we have:
> 

This is not compliant with 4741, but you are probably aware of that.
partial-operation is listed as an "error" (i.e. not warning) with the
description:

  Some part of the requested operation failed or was not attempted for
  some reason.

It also specifies that the ok-element, err-element, noop-element
elements should be sent in error-info.

As Andy wrote, this error will be removed in 4741bis.

/martin

---

From: Kent Watsen <[email-masked]>
Date: Fri, 21 May 2010 11:39:38 -0700

> wasting space in the PDU.

Please don't drop it, unless there is another way for a server to notify the client about implicit-changes - maybe allow app-specific fields with an <ok>?

> be good enough, for sessions that actually cared about this condition.

-1 for me too; I agree with Andy's assessment

> >>    to support their own applications.

I'm for sticking with the default. I don't see a good use case for needing more than one error-app-tag per <rpc-error> element...

> > error-message describes the same error.

Do you have another example?  I'm not comfortable with this example as I believe there are better ways to support internationalization

Thanks,
Kent

---

From: Kent Watsen <[email-masked]>
Date: Fri, 21 May 2010 13:50:51 -0700

>   Some part of the requested operation failed or was not attempted for

Right, but we had to pick something, as no other error-tag allowed us to use warning.  "partial operation" was the closest to describing our situation

> elements should be sent in error-info.

True - we fudged this to make it "work"

> As Andy wrote, this error will be removed in 4741bis.

Then can we find another way to enable implicit-changes to be communicated in an <rpc-reply>?

Thanks,
Kent

---

From: Kent Watsen <[email-masked]>
Date: Fri, 21 May 2010 14:58:50 -0700

> I do not like that approach.
> I would rather see a structured warning
> rather than unspecified vendor-add-ons.

A structured response would be best

The thing about reporting implicit-changes is:
  1) it must be in the <rpc-reply>
       - notifications didn't work for us
  2) it's only applicable to <edit-config>, <commit>, and <copy-config>
       - it's not applicable to most RPCs

The structure provided in the existing <rpc-error> is pretty close to our needs.  There either of the following two choices would work:

1) define a new <error-tag> called "implicit-change" having
   error-severity=warning.  We'd have to define that not all
   <rpc-error>s are actually errors and, of course, we couldn't
   drop the <error-severity> field

2) define a new <rpc-warning> type with processing semantics similar
   <ok/>.  This strategy would allow of to drop the <error-severity>
   field.  The schema could be something like:

     <xs:complexType name="rpcWarningType">
       <xs:sequence>
         <xs:element name="warning-type" type="WarningType"/>
         <xs:element name="warning-tag" type="WarningTag"/>
         <!-- dropped error-severity -->
         <!-- dropped error-app-tag (not sure if needed) -->
         <xs:element name="warning-path" type="xs:string" minOccurs="0"/>
         <xs:element name="warning-message" minOccurs="0">
           <xs:complexType>
             <xs:simpleContent>
               <xs:extension base="xs:string">
                 <xs:attribute ref="xml:lang" use="optional"/>
               </xs:extension>
             </xs:simpleContent>
           </xs:complexType>
         </xs:element>
         <!-- dropped error-info (not sure if needed) -->
       </xs:sequence>
     </xs:complexType>

    <xs:simpleType name="WarningType">
       <xs:restriction base="xs:string">
         <xs:enumeration value="transport"/>
         <xs:enumeration value="rpc"/>
         <xs:enumeration value="protocol"/>
         <xs:enumeration value="application"/>
       </xs:restriction>
     </xs:simpleType>

     <xs:simpleType name="WarningTag">
       <xs:restriction base="xs:string">
         <xs:enumeration value="implicit-change"/>
         <!-- future enumerations here -->
       </xs:restriction>
     </xs:simpleType>

Thanks,
Kent

---

From: Andy Bierman <[email-masked]>
Date: Fri, 21 May 2010 15:28:38 -0700

>        - notifications didn't work for us

why not?

>        - it's not applicable to most RPCs

it's up to the RPC.  It certainly applies to validate.
Maybe delete-config as well.

I think Martin changed my mind.
I don't think 'implicit-change' is really needed
in the standard.  It seems very specific to
1 implementation.

Another solution completely is the '-Werror' approach.
Add a flag to edit-config and to validate
to elevate warnings to errors.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Fri, 21 May 2010 11:59:44 -0700

> -1 for me too; I agree with Andy's assessment

IMO, the notification solution was dismissed
too early.  "What if the client is
not listening for system events?" 

Then the client doesn't care about system events.
A capability change is simply a system event.
It cannot classified as dangerous or irrelevant
without considering the application context.
Only the application can decide that.
The server's job is simply to notify the client.

> Do you have another example?  I'm not comfortable with this example as I believe there are better ways to support internationalization

yes -- we can push the entire problem onto the
application.  that is a reasonable solution.

---

From: Kent Watsen <[email-masked]>
Date: Mon, 24 May 2010 12:02:07 -0700

> >        - notifications didn't work for us

For one, notifications may get dropped - logging is a best-effort service on most devices.  But, more importantly, because the logic the client needs to implements is something:

  <lock>
  <edit-config>/<commit>
  if <implicit-changes> then <get-config> changes
  <unlock>

It needs to be in the <lock> as it's critical we associate any implicit-changes with the application-level operation that caused them.  If we don't import implicit-changes, then the application won't be in sync.  We could always do a full import (i.e. <get-config> with no filters) after every update, but that is a very expensive operation just to test if there were any implicit-changes.  Besides, it's intuitive to us that implicit-change notification would be in the rpc-reply; it really seems a natural fit for the protocol.  It doesn't seem to be as intuitive for it to be notification/syslog; how many APIs return warnings out-of-band?

> Maybe delete-config as well.

I don't think <validate> or <delete-config> could generate an implicit-change.  <validate> is read-only and <delete-config> is on the entire datastore.  But where implicit-changes are applicable is not too important, so long as we agree that reporting them in them in <rpc-reply> is the right thing to do  ;)

> I think Martin changed my mind

I searched Martin's responses, but I can't locate what it is he may have said to change your mind.  He mentioned that how to process warnings would have to be documented - I thought you correctly responded "why is this a problem?"

> in the standard.  It seems very specific to

I may be the only ones mentioning it on the WG list, but the real question is if the WG can/should define a mechanism for warnings.  I've already identified one use-case, maybe there are others yet to be identified?  How about letting a "trim" server warning that it trimmed some defaults values from the datastore?

> to elevate warnings to errors.

I don't understand this suggestion.  We don't want implicit-changes to generate an error.  They occur under normal operation, we just need to be notified when they do...

Thanks,
Kent

---

From: Andy Bierman <[email-masked]>
Date: Mon, 24 May 2010 12:30:49 -0700

> For one, notifications may get dropped - logging is a best-effort service on most devices.  But, more importantly, because the logic the client needs to implements is something:

We use TCP.
It is an implementation detail as to how the application
treats a NETCONF message once it is delivered.

> It needs to be in the <lock> as it's critical we associate any implicit-changes with the application-level operation that caused them.  If we don't import implicit-changes, then the application won…

I still do not understand what an implicit change is within
the NETCONF standard.  That has not been explained.
I am not going to discuss the solution details when I do not
agree there is a problem to be solved.

The client is 100% responsible for what it puts in
a NETCONF message.  Period.
There are several ways for a client to validate input.
Everything the client does is explicit.

Phil once argued that we don't need warnings because
we cannot rely on them.  If the problem is that important,
make it an error.  Use -Werror if you care about warnings.
I agree with this POV, especially for proprietary warnings.

> I searched Martin's responses, but I can't locate what it is he may have said to change your mind.  He mentioned that how to process warnings would have to be documented - I thought you correctly r…

We have entrenched logic in NETCONF:
    "<ok> or <rpc-error>", but not both.
I do not see a compelling reason to
change that in the standard.  I forgot about that
aspect of the NETCONF XSD.

So my original proposal is broken.  It would only
work for operations that return data, because
data and <rpc-error> can be combined in the rpc-reply.

> I don't understand this suggestion.  We don't want implicit-changes to generate an error.  They occur under normal operation, we just need to be notified when they do...

If they are normal, then why are they warnings?

Andy

---

From: Andy Bierman <[email-masked]>
Date: Mon, 24 May 2010 12:46:55 -0700

Kent Watsen wrote:

If you want proprietary warnings for edit-config,
commit, etc., you can use YANG legally to do it:

module my-warnings {

   ...
   import ietf-netconf { prefix nc; }

   grouping warning-group {
      list warning { ... // clone rpc-error info }
   }

   augment /nc:edit-config/nc:output {
      uses warning-group;
   }

   augment /nc:commit/nc:output {
      uses warning-group;
   }

   augment /nc:copy-config/nc:output {
      uses warning-group;
   }
}

This is legal NETCONF and YANG so all clients
MUST accept it.

Andy