Subject: [YANG] errors

From: Martin Bjorklund <[email-masked]>
Date: Thu, 24 Jan 2008 15:38:53 +0100 (CET)

Hi,

We have been talking about adding two new statements related to
error generation to YANG.

The first statement is 'error'.  It is used to define a named error.
The second statement is 'raise-error'.

For example:

    error no-matches {
      error-tag operation-failed;
      description
        "Generated if the filters return an empty node set.";
    }       

    rpc partial-lock {
      input { ... }
      output { ... }
      raise-error no-matches;
    }

  XML:

    <rpc-error>
      <error-type>application</error-type>
      <error-tag>operation-failed</error-tag>
      <error-severity>error</error-severity>
      <error-app-tag>no-matches</error-app-tag>
    </rpc-error>

The idea is that the error statement is used to define DM-specfic
error messages.  An error is identified by its error-app-tag.  All
errors are defined on the top-level in the module.

The raise-error statement is used to reference an error, either local
in the same module, or imported from some other module.  It will
replace the current error-app-tag/error-message statements in YANG
(can be specified for must, range, length, and pattern).  It can also
be used in the rpc statement, as shown above.

    error bad-ethernet-mtu {
      error-tag invalid-value;
      error-message "An ethernet MTU must be 1500";
    }

    must "ifType != ethernet or " +
         "(ifType == ethernet and ifMTU == 1500)" {
      raise-error bad-ethernet-mtu;
    }

The errors defined for an rpc would be in addition to the standard
errors defined in rfc4741.

Grammar:

    error-stmt = error-keyword sep error-app-tag-str optsep "{"
      ; error-app-tag-str is an identifier 
      error-tag-stmt stmtsep
      [error-message-stmt stmtsep]
      [error-severity-stmt stmtsep]   ; default is error
      [description-stmt stmtsep]
      [reference-stmt stmtsep]
    "}"

  raise-error error-app-tag-ref-str stmtsep

Comments?

/martin

_______________________________________________
YANG mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/yang

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 24 Jan 2008 16:30:38 +0100

> error generation to YANG.

[...]

> Comments?

I like it.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1, 28759 Bremen, Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Phil Shafer <[email-masked]>
Date: Thu, 24 Jan 2008 11:09:07 -0500

>I like it.

Same here.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Thu, 24 Jan 2008 08:41:49 -0800

Martin Bjorklund wrote:
>....

The phrase 'in addition' concerns me.

I think you mean that an error MUST use one of the existing
error-tag values from RFC 4741, but the other fields specified
in error-stmt will be used in an <rpc-error> generated for the
particular error condition.  IMO, this is too flexible.

There is a balance between multi-vendor interoperability
and single-vendor-flexibility that must be carefully considered
when developing a standard.  IMO, it would drastically harm
interoperability if the <rpc-error> mechanism turned into
just another proprietary hack (I mean 'vendor-specific content' ;-)
within NETCONF.

What does it mean for interoperability if vendors override an error defined
in RFC 4741 or the Notifications RFC, with different error-severity,
or error-message?  What if they ignore some/all of the standard errors,
and use their own proprietary set (because it's better of course ;-)

IMO, the structured error return codes in NETCONF represent an important
advancement away from screen-scraping CLI.  It is important that this
is not compromised.  A vendor is not compliant with RFC 4741
unless all the errors are generated exactly as specified in the spec,
regardless of what the YANG draft says.

I think it needs to be clear in the draft that the fields defined
by standard errors cannot be changed, and <rpc-error> behavior
defined in the standard cannot be changed (e.g., send the
acme-lock-denied error *instead* of the standard lock-denied error,
which uses a different error-tag value, or does not include the
<session-id> error-info).

>   raise-error error-app-tag-ref-str stmtsep

What if the DM writer wants to raise an existing standard error?
Does there need to be a standard module for the NETCONF errors,
added as an appendix?

Notably missing from the error-stmt is definition of any error-info data.
An open issue is whether there is some simple mechanism for defining
error-info, other than full-blown data-def-stmt, to define error leafs.
(E.g., lock-denied has the <session-id> of the current lock owner.)
If not, then I would rather leave it out.

> /martin

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 24 Jan 2008 18:50:12 +0100 (CET)

> The phrase 'in addition' concerns me.

I meant that if an rpc has one raise-error clause, it doesn't mean
that the standard error messages cannot be generated.  It just means
that in addition to the normal error messages (e.g. missing-element),
these DM-specific errors can also occur.

> error-tag values from RFC 4741

Yes that was the idea, although I forgot to mention it.

> but the other fields specified
> or error-message?

You are right.  [checking rfc4741...] Hmm.  An rpc-error MUST include
error-tag.  The list of error-tags is defined in rfc4741.  For each
such tag, the corresponding error-severity is defined.  All tags have
error-severity 'error'.  Conclusion: error-severity 'warning' can
never be generated. !!?!?!

One other thing.  The error-message is not defined by rfc4741, so it
should be ok for a DM to define one.

> What if they ignore some/all of the standard errors,

Agreed.  The idea is to provide more, specific, info, in addition to
the standard messages.  The idea is not to change the standard
messages.

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 24 Jan 2008 20:39:06 +0100

> never be generated. !!?!?!

I mentioned this before. I agree error-severity as it is is useless
and I think we consider to remove it from NETCONF when the specs are
revised. Did I mention that it would be nice to have a NETCONF
maintenance activity? Even if it is just a web page to keep track of
the issues until the IETF gets to it?

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 24 Jan 2008 20:41:43 +0100

> Does there need to be a standard module for the NETCONF errors,

Yes. And I think it would be also nice if standard NETCONF operations
could be defined in YANG itself; would be a nice proof of concept.  (I
know the unfortunate attribute usage in edit-config - so this might be
the only thing we need to handle in the DESCRIPTION clause.)

> If not, then I would rather leave it out.

Correct, this is needed. I think error-info is actually not much
different from in and out parameters where we also use standard YANG
constructs.

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 24 Jan 2008 21:28:22 +0100 (CET)

> > What if the DM writer wants to raise an existing standard error?

That's what I meant when I wrote that the raise-error is in addition
to the standard errors.  I.e. nothing needs to be done in the DM for
this scenario.

> Yes.

No, that's not possible with the way the error statement is done,
since the identifier is error-app-tag.

> > error-info, other than full-blown data-def-stmt, to define error

Why can't the normal data-def stmts be used?  That would be the
obvious choice if we want to do error-info.

> different from in and out parameters where we also use standard YANG

I agree.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 24 Jan 2008 12:40:47 -0800

> to the standard errors.  I.e. nothing needs to be done in the DM for

except there has to be a CLR that no error-app-tag value can be
one of the standard error-tag values.  If the standard error-tag
values grow over time, this creating potential naming conflicts
with previously released error-app-tag values.

> obvious choice if we want to do error-info.

IMO, the document needs lots of work in the area of specifying
how all the data-def-stmt clauses apply to rpc/input, rpc/output,
and notification.  Now add error-info to that list.
The document has to specify exactly what every clause and sub-clause
means for each of these data definition types.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 24 Jan 2008 21:42:32 +0100 (CET)

Andy Bierman <[email-masked]> wrote:
> one of the standard error-tag values. 

Why?

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 24 Jan 2008 13:01:29 -0800

>> one of the standard error-tag values. 

error lock-denied {

  ...
  raise-error lock-denied;

Is this raise-error for the standard lock-denied or for the
vendor error called lock-denied, defined in the same module?

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 24 Jan 2008 22:07:49 +0100 (CET)

> vendor error called lock-denied, defined in the same module?

The idea was (I think it came from you :) that the identifier for the
error clause is error-app-tag.  So the above would be in XML:

  <rpc-error>
    <error-tag>operation-failed</error>
    <error-app-tag>lock-denied</error-app-tag>
  </rpc-error>

Thus, no name clash.

Side note: the error-app-tag is defined as a string in rfc4741, but
IMO is should have been a QName.  If it was, all error-app-tags would
be local per namespace, so the above would be:

    <error-app-tag xmlns:foo="...">foo:lock-denied</error-app-tag>

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 24 Jan 2008 13:35:27 -0800

>     <error-app-tag>lock-denied</error-app-tag>

huh?

then how do you specify a 'raise-error' for the lock-denied in RFC 4741?

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 24 Jan 2008 23:10:36 +0100 (CET)

> then how do you specify a 'raise-error' for the lock-denied in RFC 4741?

You don't.  Unless you also have an error-app-tag:

  error my-extra-lock-denied {
    error-tag lock-denied;
  }

The idea was that really do not want to list all std errors that can
occur:

   rpc my-rpc {
     ...
     raise-error missing-element;
     raise-error bad-namespace;
     ...     
   }

These std errors can always occur.  No need to specify them again.

-----

We also disucssed an alternative way to do this, which is slightly
more flexible.  In this variant, the error is identified with an
identifier, which has no meaning on the wire.  It's just a local
identifier like a typedef or grouping identifier.  Then within the
error, you have the statement 'error-app-tag' in addition to the other
stmts:

   error my-error {
     error-tag invalid-value;
     error-app-tag bad-mtu;
   }

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 24 Jan 2008 16:09:59 -0800

> These std errors can always occur.  No need to specify them again.

okay, that's fine.

> error, you have the statement 'error-app-tag' in addition to the other

I like the current design better because the key into the
error dictionary has meaning, but there is a problem...

There is still at least one open issue, which is that error-app-tag
is defined in RFC 4741 as a string and it should really be a QName.
Each error definition will only be unique within its module, so
error-app-tag is not globally unique as it should be (according
to the RFC).

IMO, this should be solved by calling it a bug in the RFC
(along with the bad-namespace element, which is a QName and MUST
be an Xpath string, not a QName at all), and encoding the
error-app-tag as a QName. The module namespace URI identifies
the prefix in an XML instance document.

Your 'raise-error' examples always show a local identifier reference
(i.e., no prefix), but the real syntax is an identifier-ref-string
(called a node-identifier in -00), so the error does not have to
be in the same module as the raise-error statement.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 25 Jan 2008 10:19:46 +0100

On Thu, Jan 24, 2008 at 08:39:06PM +0100, Juergen Schoenwaelder wrote:

> Did I mention that it would be nice to have a NETCONF maintenance
> activity? Even if it is just a web page to keep track of the issues
> until the IETF gets to it?

I started a wiki page to track NETCONF RFC 4741 issues. 

http://cnds.eecs.jacobs-university.de/wiki/NETCONF

It is currently in its infancy so please send me your favourite bugs
and I will happily add them to the wiki page.

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 25 Jan 2008 11:01:19 +0100 (CET)

Hi Juergen,

> http://cnds.eecs.jacobs-university.de/wiki/NETCONF

There's also:

http://www3.tools.ietf.org/wg/netconf/trac/report/1

Do we need both?

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 25 Jan 2008 11:04:35 +0100

> http://www3.tools.ietf.org/wg/netconf/trac/report/1

No, I did not know that this exists. Who is putting stuff on there? I
am happy to kill my page on favour of this one...

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 25 Jan 2008 11:12:03 +0100 (CET)

Juergen Schoenwaelder <[email-masked]> wrote:
> No, I did not know that this exists. Who is putting stuff on there?

You! Me!  You just have to register.

But as you can see, all tickets were created last summer, and since
then not much has happend.

I just added a ticket for the error-severity problem.

/martin