[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: NETCONF modelled in UML
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.
- need to add new <rpc-error> and error code text to -03 and
review/refine it from there
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.
- decide if #candidate and #writable-running should be mutually
exclusive capabilities instead of independent of each other
NS - I suggested treating exclusivity as a property of a capability.
- remove defaults for edit-config (and other) target parameter
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
On Tue, 2004-06-01 at 22:28, Andy Bierman wrote:
> 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
>
>
>
>
> >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 -
> >>nsowatsk@cisco.com
> >
> >
> >--
> >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/>
--
Nathan Sowatskey - Technical Leader, NMTG CTO Engineering - Desk
+44-208-824-4259/+1-408-527-2595 - Mobile +44-7740-449794 - AIM id NathanCisco -
nsowatsk@cisco.com
--
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/>