Subject: Re: NETCONF modelled in UML

From: Andy Bierman <[email-masked]>
Date: Tue, 01 Jun 2004 13:08:33 -0700

At 01:46 AM 5/24/2004, Nathan Sowatskey wrote:
>All
>
>This email details an attempt by me to model the NETCONF specification in UML in preparation for implementing the specification. My basic conclusion was that the specification can not be implemented as it currently stands. I welcome challenges to that conclusion.
>
>Viewing the project and using Together
>--------------------------------------
>
>This is the first step in modelling NETCONF, which is to represent the
>entities and their relationships in UML. For those who want to play with
>the Together project itself, I have attached the whole thing zipped.
>
>If you want to edit the project, you will need to get Together 6.1 from Borland.com (just fill in the
>evaluation form and download it) an apply for an evaluation licence if you need it.
>
>You don't need Together to view the diagrams, which are gifs, or the code, all of which are in the attached zip file.
>
>Once you have done that, open the attached file somewhere convenient,
>windows or Linux/Unix. Open the NETCONF.tpr file, and you will be away!
>
>If you just want to look at the diagrams, then they are in the diagrams
>directory of the attached file. There are two diagrams, netconf.gif and
>rpc.gif. There are also many notes in the source files also, which are
>under src, which you can look at with the aid of a normal editor.
>
>Discussion of the model - Operations and arguments
>--------------------------------------------------
>
>Whilst this is a UML *model*, and is thus distinct from any specific
>implementation, implementation concerns always play a role in modelling,
>much as normalization does in data base modelling. I have thus
>approached this modelling exercise as though I were going to implement
>the specification, as indeed I am, from a top down perspective, rather
>than the bottom up approach that the specification takes.

IMO, although interesting, development of a UML model is out
of scope for the NETCONF v1.0 document set.  We will focus on
the document clarity issues you are raising instead.

>One of the first challenges that I encountered with reverse engineering
>a model from the specification was separating the RPC implementation
>from the operations. 
>
>Having the rpc-reply element as part of the signature of the operations,
>the fact that some arguments are parameters, whilst others are
>attributes, and the use of '<>'s everywhere couples the operations to
>the underlying XML implementation. This coupling is probably not the
>intention of the specification writers, but it is there nevertheless.

Not sure what this comment means.  If it means we are putting
a stake in the ground wrt/ XML syntax and XSD representation
(at a minimum) of protocol messages data models, then it is
intentional.  That's in the charter, and IMO it's important
that we try to stay within that scope.

>Another challenge was the inconsistent declaration of "format" argument.
>It is implied in the text descriptions, so I have included a Format
>object as an operation parameter which is an enumeration of two types:
>XML and Text. I suspect that there may be more types, and using an
>enumeration is intrinsically extensible.

format is gone in -03.  We will use namespaces to identify
content format.  We may also want to create some conventions
for <text> elements at some point (not coupled to v1.0 work).

>The next challenge was to decide what the Configuration type should look
>like. I have used a nested structure. This is a common design idiom
>where a top level container contains a collection of something - 
>ConfigurationElement - that is a  name/value pair, or a collection of
>more of itself. Again, this is intrinsically extensible.

Do you mean the data model structure or a model of the NETCONF
protocol operations?  The data model work is out of scope.
The <rpc> and <rpc-reply> elements are the the top-level containers.

>I then needed to think about what the naming and types of the parameters
>should be. I wasn't sure what the notation used in the specification was
>meant to convey. An example being "source: @config-name". I took this to
>mean that there was a parameter called source, which is the name of a
>configuration, though the explanation refers to this being the name of a
>configuration datastore.

We need to fix this in the document.
That shorthand I made up on the fly should be replaced with
something else, like an ABNF.

>In general I took the first part of the parameter name for the arguments
>for the operations where that made sense. I also used String types by
>default, except where the type was more specifically defined, either
>because my modelling interpretation introduced it, or because it was
>later specified by the Capabilities.

The data types are (or should be) defined in the accompanying XSD, 
not in this text, and the document says that somewhere.  

>With the "config: @element-subtree" parameter, I made the decision that
>this was actually the scope of the operation, that being the implication
>of the explanation. In any case, I was able to use the same
>Configuration type as the argument and the value of the configuration in
>the reply, which was a useful modelling outcome, and may be what the
>specification writers intended.

This is the data model specific XML representation of the desired
configuration changes.

>The RPCreply type is a common pattern for RPCs where the encoding and/or
>the implementation don't support exceptions. In this case we have a
>container for the configuration, state and rpc-error elements. This can
>be used over any RPC encoding scheme, which I believe was the intention of the specification writers.
>
>The State type posed a problem as it clearly exists in the
>specification, but there is no indication of what it consists of. For
>now I have included the type as a place holder, but I am unable to give
>it any structure.

Do you mean the netconf-state XSD in the draft?
Not sure what State is in the protocol operations.

>The RPCError type probably has more members than it needs. A minimum for
>such a type would normally be the error code, non internationalised
>error text, and a namespace to define the resource bundle that the
>internationalised text would come from. The specification writers might
>want to consider whether all of the other elements are really needed.

The -03 version will have the updated <rpc-error> section I sent
to the mailing list a couple weeks ago.  We will refine it from there.
The -02 version has some problems that have hopefully been addressed.

>The edit-config operation specifies attributes as well as parameters.
>This is XML specific. I have modelled the "operation" attribute as a
>parameter to the operation and created an enumerated type,
>EditOperation. This also illustrates that having a parameter to an
>operation called "operation" is not a good thing. It might have been
>better to have three separate edit operations instead, which is another 
>modelling option that I considered, but have left out for now.

We know it's XML-specific and that's not a concern of the WG.
I'm more concerned that we document guidelines for writing XSDs
that account for the operation attribute.

>The copy-config operation has a source parameter which could be a name
>of a configuration or a configuration itself. Since these are two
>different types, I have had to create two arguments in the operation for
>both cases. This is also the only operation where the format parameter
>is explicitly specified, but it is also suggested that the format be
>omitted for this operation. I wasn't sure what to make of that, so I
>included format as a parameter anyway.

The XSD is still kind of rough.  We are still finalizing the semantics
and the syntax hasn't caught up yet.  The copy-config <source>
parameter is supposed to take on of:
  std config: <candidate>, <running>, <startup>
  local config example: <url>file://foo-config.xml</url>
  remote config example: 
        <url>ftp://example.com/configs/v1.1/foo-config.xml</url>

>The get-all operation specifies a state parameter which could be an
>element-subtree (which I have modelled as a Configuration type
>specifying the scope of the operation) or text. This led me to conclude
>that the specification writers intended for there to be a format
>parameter, so I have created one for this operation.

text is out in -03 -- see above -- the config has to be valid XML

>The kill-session operation specified the type of session-id to be an
>integer. This is the first type definition in the specification. I can
>see that the session-id is elsewhere specified as an int, but it might
>better be a float, or a BIGINT. There is no guarantee on how big an int can be, but at least we can decide on an IEEE defined float as a number with a well specified range. Further, a positive integer means that we can't use -1 as a session-id which can sometimes be useful.

this is more clarified in the -03 version.
IMO, we don't need to make the SessionID a float.
Billions of session IDs seems pretty sufficient to me.

>Discussion of the model - Capabilities etc.
>-------------------------------------------
>
>The next step in the modelling exercise is to decide how to model
>Capabilities and the different operations associated with devices that
>have them. 
>
>The first point of difficulty is that the capabilities of a device are
>determined during the transport set up when the session is first
>established as part of the "hello" handshake. This is not a good thing.

why not? They can also be read later from the netconf-state data model.

>I have added an operation to the Device type (more on that later) which
>supports the explicit discovery of capabilities after the transport has been established.

This should be just more data available via the <get> operation,
not a special operation.  The capabilities exchange is very
important at session startup.  If the capabilities don't meet
application needs, then it's better to shut down the session
and report the incompatibility problem to the user.

>The Device type could have been called Server as the specification uses
>both interchangeably. This is not a good idea. Typically the "server"
>would, for most people, be the management software managing the device.
>Since this is a peer-to-peer model, moreover, neither is really a server
>in the client-server sense. The specification writers seem to have taken
>the stance that the entity implementing the operations is the server. I
>have chosen "Device" as that is much clearer. I'd suggest that the
>specification writers do the same.

We are trying to stick to manager and agent.
We need to clean up this text.  There is text that
says we use client and server to mean manager and agent.
This should be removed and the terminology cleaned up.

>The Capability type is modelled with a namespace and a type which is
>modelled as an enumeration. A Device has a collection of Capability(s).
>
>Each capability has associated with it a set of operations which are
>additive in that a device can have the base operations, and the extra
>operations associated with the additional capabilities. 
>
>A problem arises in that some base operations are overloaded, i.e.
>redefined, in a device that has a capability. Normally this would be
>modelled by inheritance which would allow an operation in an inherited
>type to redefine what the base operation does.

Some capabilities represent the reality of massive quantities 
of deployed network devices with specific characteristics.
Our prime directive is to create something vendors can implement
and operators can use. 

Some capabilities represent a trade-off between complexity and scale.  
Certain features like rollback or XPath are expensive enough to be optional
(at least for now).  Tiny SOHO boxes may not have the resources
to provide complex features like this.

>In this case, as the capabilities are additive, but not mutually
>exclusive, it is not clear how this would work. What happens, for
>example, if a device has both the URL capability and the Candidate
>capability? Both these capabilities define different versions of
>edit-config. Which would apply?

both -- I'm concerned that the spec describes the functionality,
but not particular implementation strategies.  Lots of capabilities
work independently.  This is no different than the current
situation for developers.  We are just trying to provide a
mechanism to expose the operational capabilities in a standard
protocol exchange.

>For the time being I have chosen to model the operations as a collection
>in the Device conceptually keyed by the capability that the operations
>are associated with. This really makes the notion of a capability more
>like that of a role. If that were the case, then one could decide what
>role the device was fulfilling, and then choose the set of operations
>that matched that role/capability.
>
>As things stand I am not sure if the model is correct or not, or whether
>the specification writers have simply left this aspect unspecified.
>
>The specification defines an Agent capability, but all this seems to
>indicate is that a peer is willing to be managed, which makes it a
>Device. I think that the Manager and Agent capabilities are not
>capabilities at all, but roles. It is also not clear what difference
>they make in an implementation, except perhaps at the transport security
>level.
>
>Where the capabilities modify existing operations, this is typically in a way that defines what the values of the arguments should be. In these cases this is not a modification of the operation, it is an implementation detail of how the operation should work. The edit-config and copy-config operations for the Writeable-Running capability are examples of this.

I disagree.  The XML syntax is not an implementation detail.
We are defining an XML API, not an abstract information model.
There is clear WG consensus that the use of XML syntax and XSD
data modelling capabilities, as stated in the charter, is the
right decision for the NETCONF protocol.

>A slightly different case is the modification to the copy-config
>operation for the Distinct Startup capability, which appears to specify
>a completely different behaviour from the base operations.

Yes, as documenting in the draft. 
This is the first type of capability -- aligning the protocol
with reality instead of the other way around.

>I have tried to capture the new and modified operations by redefining
>the operations on a specific derived Operations type for the associated
>capability. The diagram only reveals part of the story, so the notes in
>the code will help to see what I have done here.
>
>The discard-changes operation for the Candidate Configuration capability
>doesn't appear to have a return value, but I have added one as it is
>clearly required.

It should be <ok> or <rpc-error>. What else is needed?

>The get-config and edit-config modified operations for the Candidate
>capability are specified to have a default target of the candidate
>configuration. This should probably be the only value allowed. 

We discussed this and though we should keep the #candidate
and #writable-running capabilities independent.  I agree
that it would be bad for an implementation to actually do
this, so maybe we should make these capabilities mutually
exclusive.

>For it to
>be described as "default" implies that there is a choice of some other
>configuration, which wouldn't make sense for this capability. Also,
>"target" probably means source for get-config, and target for
>edit-config only.

I think we discussed this and decided we can't really have a default
in the XSD because XSD doesn't support it and the dual-target
issue above.  IMO, we should make this parameter mandatory because
there's no way to keep implementations consistent on the default.
I think Wes already brought this issue up and we agreed the
default attribute in the XSD and this default text in the 
description should be removed.

>As per the modelling question above, it is not clear whether a device
>can have the Validate and Candidate capabilities at the same time. On a
>point of consistency, the section for the Validate capability doesn't
>mention any modifications to existing operations at all.

Sure -- validate is independent of candidate.  We do not have
a database-like transaction model.  We understand that edit-config
operations can succeed on the <candidate> and the <commit> can
still fail because <edit-config> didn't check everything that
can possibly go wrong during actual application of the desired config
changes to the running state.

>Summary
>-------
>
>This review has highlighted some shortcomings in the specification from
>an implementation perspective, and also from a system model perspective.
>Ideally these would be addressed so that a definitive model could be
>produced.

thanks for your comments -- we will try to clarify the documents
in the areas that are still rough or broken.  Here's my list of
issues your email has generated in this area:

>That's all for now. I'd appreciate some feedback on this discussion.
>
>Many thanks
>
>Nathan 

Andy

> 
>-- 
>Nathan Sowatskey - Technical Leader, NMTG CTO Engineering - Desk
>+44-208-824-4259/+1-408-527-2595 - Mobile +44-7740-449794 - AIM id NathanCisco -
>[email-masked]

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

---

From: Andy Bierman <[email-masked]>
Date: Tue, 01 Jun 2004 13:28:30 -0700

At 01:08 PM 6/1/2004, Andy Bierman wrote:

oops -- fat-fingered 'send' before adding the summary of
action items at the end:
  - replace ad-hoc parameter syntax in the operation descriptions
    like '@config-name' to something more precise, like ABNF
  - need to add new <rpc-error> and error code text to -03 and
    review/refine it from there
  - document guidelines for writing XSDs that account for the 
    operation attribute
  - cleanup XSDs in the protocol draft to align with the related
    text about the protocol operation syntax elsewhere in the draft
  - cleanup terminology related to manager/agent vs. client/server;
    don't use client/server terminology at all
  - decide if #candidate and #writable-running should be mutually
    exclusive capabilities instead of independent of each other
  - remove defaults for edit-config (and other) target parameter

Hope I got them all.

thanks,
Andy

---

From: Nathan Sowatskey <[email-masked]>
Date: Wed, 02 Jun 2004 18:26:20 +0200

All

Andy's replies to my original UML model email are below. Andy replied to
his own email as well, so the nesting is slightly strange. To avoid more
nesting, my replies are not nested.

Why a UML Model?
---------------

The point of creating a model from the specification was not the model
itself, but to see whether a complete and well-formed model *could* be
derived from the specification. This is always a good way to identify
the strengths and weaknesses of a written specification.

Secondly, the model, using Together, is a development artefact which I
use to derive Java code (the binding from UML to Java is a well defined
standard). From the Java code I use a tool from Axis (java2WSDL) to
define WSDL descriptors for the Java interfaces (another well defined
standard), and JAX-RPC (http://java.sun.com/xml/jaxrpc/) for the XML RPC
encoding.

The point is that I an use standard tools and specifications to produce
the XML RPCs for the operations once I have successfully modelled them.
I have argued that this approach should be used to define the RPC
encoding for NETCONF as it is well specified, and well supported by
tools, already.

Mixing interface and encoding
-----------------------------

I noted that the definition of the operations was mixed with the
encoding style. This appeared to be contrary to the intention of the
specification which declared a layered approach to be its goal. If that
were the case, then the definition of the operations should not expose
the encoding style.

This will probably be a moot point if the interface is declared in a
well formed language like BNF, though more on that later.

Format, Configuration and State data types
-----------------------------------

I have removed the Format data type.

I noted that there were two data types, Configuration and State, that
were important in the RPCs. I used one XML example to infer that the
Configuration data type was nested, and modelled it like that. In fact,
both data types should be explicitly undefined, i.e. they are opaque to
the specification. The model has been changed to reflect this.

Interface declarations
----------------------

Andy suggested using BNF to declare the interfaces. I suggest IDL. This
is what it could look like (generated from the model by Together and
slightly tidied up):

interface BaseOperations : Operations{
	RPCReply getConfig( string source,  
		Object configScope);

	RPCReply editConfig( EditOperation operation,  
		string target,  
		string testOption,  
		string errorOption,  
		Object configScope);

	RPCReply copyConfig( string sourceName,  
		Object sourceConfig,  
		string target);

	RPCReply deleteConfig( string target);

	RPCReply lock( string target);

	RPCReply unlock( string target);

	RPCReply getAll( Object configScope);

	RPCReply killSession( long sessionId);

interface RPCReply {
	Object getConfigResults();
	Object getStateResults();
	RPCError getError();
	long getMessageId();
	boolean isOK();
	};

interface RPCError {
	string getDetails();
	string getTag();
	long getErrorCode();
	string getSeverity();
	Object getEditPath();
	string getStatement();
	string getMessage();
	string getAction();
	};

Note that the data types are defined here, as are the interfaces for the
RPCReply and RPCError types. This is clearly independent of encoding.
Further, the mapping from these types to XSD types is well defined by
the JAX-RPC specification.

Scope?
------

I suggested that the desired configuration changes might be termed the
"scope" of the operation. It is not clear if that was understood.

RPCReply and RPCError types
-----------------------------

I suggested the structures indicated above for the RPCReply and RPCError
types. It is not clear if that was understood.

The RPCError type will change, but I have left it alone in the model for
now.

The edit-config and copy-config operations
------------------------------------------

I suggested that the use of the XML specific attribute type be hidden.
As before, if the language used to declare the interfaces changes, that
is moot.

I further suggested that it might be better to have separate edit-config
operations so that the meaning was clear in the name of the operation.
It is not clear if that was understood.

The copy-config operation is still in flux.

Determining capabilities
------------------------

I argued that determining capabilities should be done at the application
layer, not the transport layer. The application layer is where the
capabilities matter.

I don't think that this changes the ability of the peers to negotiate on
capabilities, bit it does make for a cleaner separation of layers.

Device, manager, agent etc.
---------------------------

I am not clear on which is which yet, though agent makes me think of an
SNMP agent for a managed element, which is not, I believe, the
impression we want to convey if NETCONF is supposed to be implemented
natively.

Capabilities and mutual exclusivity
-----------------------------------

I argued that having capabilities that were additive but not mutually
exclusive would not work. I don't believe that specific capabilities can
be simply declared exclusive of each other since there is no way to know
which future capabilities might also need to be exclusive.

I think that a general property of a capability that lists the
capabilities that must be excluded if the capability is active must be
supported.

Agent and Roles
---------------

I made a detailed point here which I don't believe was understood.

The discard-changes operation
-----------------------------

Doesn't have a return type defined. Whilst it is clear what it should
be, the specification doesn't say that.

Summary
-------

This is progress :-)

- replace ad-hoc parameter syntax in the operation descriptions like
'@config-name' to something more precise, like ABNF

NS - I suggested IDL and gave an example above.

NS - OK

- document guidelines for writing XSDs that account for the operation
attribute

NS - I suggested different operation names

- cleanup XSDs in the protocol draft to align with the related text
about the protocol operation syntax elsewhere in the draft

- cleanup terminology related to manager/agent vs. client/server; don't
use client/server terminology at all

NS - I don't like agent, too SNMP like.

NS - I suggested treating exclusivity as a property of a capability.

NS - OK

The remaining points are still outstanding from my understanding:

- Why invent an XML RPC encoding when there are standards available?

- Keep interface declaration and encoding scheme completely separate.

- Scope?

- I don't think capabilities should be determined at the transport
layer.

- Agents and roles.

I'll work on some example encodings now with the Axis and JAX-RPC tools
and some sample data to see what that will look like.

Many thanks

Nathan

---

From: Andy Bierman <[email-masked]>
Date: Wed, 02 Jun 2004 10:14:56 -0700

>All

replies inline

>nesting, my replies are not nested.

These remind me of the ASI stuff in the SNMPv3 documents.
We should focus only on the semantics and syntax of messages
on the wire, and stay away from implementation interfaces

>"scope" of the operation. It is not clear if that was understood.

I think scope is an overloaded term, and it doesn't seem to fit here.

>RPCReply and RPCError types

We have an XSD for that in the document.  The WG consensus
is that XSD representation of NETCONF syntax is sufficient.

>The edit-config and copy-config operations

Not sure what you're talking about here.  The syntax of NETCONF
messages is encoded in XML.  This is not going to change.

>It is not clear if that was understood.

This was discussed at length on the mailing list and WG consensus
is that separate edit commands for create, modify, delete, etc.
make the protocol operations harder to use for operators.

>The copy-config operation is still in flux.

I have to check the text -- maybe its still unclear or wrong --
the protocol document should describe the capabilities exchange
in a transport-independent manner.  The concern is that the
NETCONF peers should exchange capabilities before they start
sending protocol messages.  This was a more significant concern
when we had notifications, optional channels, etc.

I agree that it is not desirable to have a potentially different
capabilities exchange for each transport mapping.

>Device, manager, agent etc.

The manager sends <rpc> messages and listens for <rpc-reply> messages.
The agent listens for <rpc> messages and sends <rpc-reply> messages.
What do you mean, implemented natively?  The manager/agent model is
what we want here.

>Capabilities and mutual exclusivity

Future capabilities will explain how they interact with existing ones.

>capabilities that must be excluded if the capability is active must be

This can be in documentation. I don't think it needs to be
retrieved from the agent at runtime.

thanks,
Andy

---

From: "Randy Presuhn" <[email-masked]>
Date: Tue, 1 Jun 2004 10:59:38 -0700

Hi -

> From: "Andy Bierman" <[email-masked]>
> To: "Nathan Sowatskey" <[email-masked]>
> Cc: <[email-masked]>
> Sent: Wednesday, June 02, 2004 10:14 AM
> Subject: Re: NETCONF modelled in UML
...
> on the wire, and stay away from implementation interfaces
...

Although this is a tangential issue, this statement
is too easily read in a way leading to serious
misconceptions.

The ASIs are *NOT* implementation interfaces.
RFC 3411 is abundantly clear on this point:

  The abstract service interfaces are intended to help clarify
   the externally observable behavior of SNMP entities, and are not
   intended to constrain the structure or organization of
   implementations in any way.  Most specifically, they should not be
   interpreted as APIs or as requirements statements for APIs.

Randy

---

From: Nathan Sowatskey <[email-masked]>
Date: Thu, 03 Jun 2004 17:02:34 +0200

Indeed, and not tangential, this is equally true of CORBA IDL. 

More to the point though, I believe that the specification should focus on the semantics and syntax of the operations. The focus on the wire format is where I feel the specification is weakest.  

The software industry is not short of well defined XML RPC encodings
with readily available tool support, why invent another?

Regards

Nathan

---

From: "David Harrington" <[email-masked]>
Date: Thu, 3 Jun 2004 11:39:05 -0400

Hi,

> -----Original Message-----
> [mailto:[email-masked]] On Behalf Of Nathan Sowatskey
> The focus on the wire format is where I feel the 
> specification is weakest.  
> 
I'm having a bit of trouble parsing this sentence unambiguously. Are you
saying the specification is weak BECAUSE it is focused on the wire format
rather than the operations, or are you saying the focus on the wire format
is too weak?

Thanks,
Dave Harrington
[email-masked]

---

From: Nathan Sowatskey <[email-masked]>
Date: Thu, 03 Jun 2004 18:02:08 +0200

Because it is focused on the wire format. You don't need to do that I
feel. It is the operations that are important, wire encodings for XML
RPC are already well defined. You don't need to define another one.

Regards

Nathan