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/>
--
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/>