Hello,
If you allow me, I'd like to open this up just a little bit.
I've had problems with the <rpc-error> block since I first saw its
description. Not as much as with the contents of it (which is to be addressed
with the items below) but with its overall use.
First, it seemed crucial to me that the <rpc-error> block could be repeated
within a reply though the draft, as I read it, was silent about that.
I see many cases where a single command may result in many distinct error/warning
messages. Second, these errors may well occur at different time of the processing
which makes it difficult to know where the rpc-error block can be introduced.
With, say "linear", command output (e.g. operational dump of interfaces), then
one can assume that the error block can be inserted between "top" (below rpc-reply)
level entities and still make sense schema/usage wise. With deeply
embedded/hierarchical output like show-config, it is not as obvious...
A clarification of where the block can occur and if it can occur multiple times
therefore seems necessary (I believe it has to be so).
The second problem I have is with determining the success/failure of a command.
What one deduces from the draft is that if <ok/> is there, then it succeeds
but if it is not, than it fails. This mish mashes with the presence of <rpc-error>
blocks some of them may not indicate failures (warning or notice type
of messages). Deducing the success/failure of the command from the possible presence
of an rpc-error block somewhere in the middle of the reply does not sound nice to
me in any case. I suggest that it would be better to have a formal indication
of the execution status of a request with an explicit/terminal element.
Both success and failure should be explicitely identified. Further more,
I suggest that that indication needs more than just an indication of success/failure
but also other related information, most notably the termination time (I can imagine
other possibilities with status, modes, ...). The current specification of <ok/>
seems to be to blocking for this. An alternative would be to have either
<ok/> or <failed/> (one or the other) as the last element. Making these elements
container of other elements like time-stamp (or as tag attributes) solves
the related information issue. Probably more clean would be to have a <rpc-reply-
status> element with the success/failure indication and other information in it (as sub-
elements or tag attributes). For cases where time-stamps cannot be provided,
the element could be defaulted but in that case, it would see more logical to me
to default to success, not failure.
All in all, one gets the feeling from the draft that <rpc-error> and <ok> are
mirrors of each other but I don't think that this is true. Both provide information
on the execution of the command but the first one may be repeated and is not
a good representation of the final status of the command and the other only indicates
one of the possible final status and prevents the addition of related information.
For the clear implementation of a state-machine on the client side, a clear
indication of command success is pretty much necessary in the protocol.
I hope I've not made it sound so much more complex than it actually is...
Thanks
-----Original Message-----
From: Andy Bierman [mailto:abierman@cisco.com]
Sent: Saturday, February 21, 2004 1:10 PM
To: netconf@ops.ietf.org
Subject: Issue 12.6) <rpc-error>
We need to make progress on the error handling details.
This is mandatory for v1.0, and cannot be punted to a
later release.
[Functional Requirements]
- need a set of well-defined error responses
- applications should be able to process error responses using
mostly common code
- data model specific error responses should be avoided, but
may be needed for referential integrity or resource errors
- each <rpc-error> sub-element must have either a constrained
set of standard values in order to be useful and interoperable
- it must be possible to return multiple <rpc-error> elements
in response to a single request
- need to differentiate between errors and warnings
- need to allow for application errors as well as protocol errors
[Current Text, sec. 3.4]
The <rpc-error> element is sent in <rpc-reply> messages if an error
occurs during the processing of an <rpc> request.
The <rpc-error> element includes the following information:
o tag: String identifying the error condition.
o error-code: Integer identifying the error condition.
o severity: String identifying the error severity, as determined by
the device.
o edit-path: Configuration data that provides the context for the
command that caused the error. This can be the empty string if
the command causing the error is located at the top level of the
command hierarchy.
o statement: Configuration or command that caused the error.
o message: String describing the error condition.
o action: Action taken by the device in response to this error.
[ed: A list of standard error codes is TBD. Both protocol error and
application error codes will be supported by <rpc-error>.]
<rpc-error message-id="102" xmlns="http://ietf.org/netconf/base/1.0">
<tag>EXAMPLE_MTU_RANGE</tag>
<error-code>128</error-code>
<severity>error</severity>
<statement>mtu 21050;</statement>
<message>MTU 21050 on Ethernet/1 is outside range 256..9192</message>
</rpc-error>
[XSD Fragment]
<xsd:complexType name="rpc-errorType">
<xsd:sequence>
<xsd:element name="tag" type="xsd:string" minOccurs="0"/>
<xsd:element name="error-code" type="xsd:integer" minOccurs="0"/>
<xsd:element name="severity" type="xsd:string" minOccurs="0"/>
<xsd:element name="edit-path" type="xsd:string" minOccurs="0"/>
<xsd:element name="statement" type="xsd:string" minOccurs="0"/>
<xsd:element name="message" type="xsd:string" minOccurs="0"/>
<xsd:element name="action" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
Notes:
- the minOccurs attribute should not be zero for all these fields
- currently there is no support for multiple <rpc-error> elements
because maxOccurs is (defaulted to) 1.
[Issue List Fragment]
12.6) <rpc-error>
Open: Need to finalize all fields in the <rpc-error> element
and improve documentation
12.6.1) Error codes
Open: need to define <rpc-error> content for standard errors
- 5 layers
- application mapping
- netconf protocol
- RPC layer
- protocol operation
- data model specific
The WG needs to document all but the data model specific
error responses. All the rest, except application mapping
errors should be documented in the netconf protocol I-D.
[Proposal]
- tag:
- need a standard set of these strings
- the prefix string NETCONF_ is reserved for WG defined errors
- error-code:
- need a standard set of these integers
- the value zero is reserved to indicate NO_ERROR
- the integer range 1 .. 1000 is reserved for WG defined errors
- severity:
- this should be an enum, not a free-form string
- the standard values 'error' and 'warning' are defined
- no other values are allowed in this field
- edit-path:
- this seems like a very CLI-centric and cumbersome way to
identify the specific part of the supplied data model
that contained an error.
- would be easier to include enough of the config hierarchy
in the response, and let the location of the <rpc-error>
in the <config> element sub-tree identify the edit-path.
- remove this sub-element
- statement:
- would be easier to include enough of the config hierarchy
in the response, and let the location of the <rpc-error>
in the <config> element sub-tree identify the edit-path.
- remove this sub-element
- message:
- message strings for standard errors should be defined
- vendor-specific edit-path and statement info can put
placed in this field, if needed
- limit length of string to N bytes (N=1024?)
- action:
- this field is redundant does not seem very useful
- define a set of standard enum values or this field
should be removed
--
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/>