- About
- NSO 5.7 Getting Started Guide
- NSO 5.7 User Guide
- NSO Installation Guide
- NSO 5.7 Administration Guide
- NSO 5.7 Northbound APIs
- NSO 5.7 Development Guide
- Preface
- The Configuration Database and YANG
- Basic Automation with Python
- Creating a Service
- Applications in NSO
- The NSO Java VM
- The NSO Python VM
- Embedded Erlang applications
- The YANG Data Modeling Language
- Using CDB
- Java API Overview
- Python API Overview
- NSO Packages
- Package Development
- Developing NSO Services
- Templates
- NED Upgrades and Migration
- Developing Alarm Applications
- SNMP Notification Receiver
- The web server
- Kicker
- Scheduler
- Progress Trace
- Nano Services for Staged Provisioning
- Encryption Keys
- External Logging
- NSO 5.7 Web UI
- NSO CDM Migration Guide
- NSO Layered Service Architecture
- NSO 5.7 NED Development
- NSO 5.7 Manual Pages
- SDK API Reference
- NSO on DevNet
- Get Support
North and south of NSO the all references and paths are described using XML namespaces, module names or prefixes (depending on protocol or API). The crunched namespaces are never be used. This to be able to keep service and other code intact at an NSO migration to a CDM release.
Efforts have been made to introduce CDM with as little backward incompatibilities as possible. However since the change to the NSO device schema tree is fundamental there are some changes to APIs and structures.
The device type in the tailf-ncs YANG module is a choice with four cases (netconf, cli, generic and snmp). For all these cases there is a ned-id leaf. With CDM the ned-id leaf has become mandatory, also for netconf, and the default value has been removed. In previous NSO releases the default was the identity 'ned:netconf'. This ned-id value still exists for backward compatible reasons but no NED build for a CDM release should use this value.
The ned-id is required to be globally unique over all other NED versions. In NED Internals a scheme how to construct unique ned-ids are described.
When an existing NSO installation is migrated to CDM, NSO will automatically, as part of the migration process, attempt to fill in the proper ned id for each device. This also includes NETCONF devices. The prerequisite for this ned id replacement is that each NED package are replaced with it unique CDM compiled counterpart. In NSO CDM migration is NSO migration procedure described in detail.
YANG modules that uses e.g. leafrefs, when, must and other xpath expressions need to have a import declaration for the modules that are referred to by the xpath expression.
Now if a device compiled (crunched) namespace is referred to in an xpath expression, this is by itself an possible ambiguity. Here the import statement will identify the used xml namespace. A number of crunched namespace could potentially then have the same XML namespace and be part of the xpath expression. The validation of these expressions are deferred at compile time and performed at load time instead.
Note
When compiling a YANG module containing the above
described situation there need to exist at least one crunched
namespace for the XML namespace in the import statement.
In makefiles or equivalent the crunched namespace should
be referenced. These are normally found under
src/ncsc-out/module/yang
in the package directory of the compiled Ned.
Device templates have changed. The config container in the
template list has moved under a new ned-id list keyed on
ned-id YANG identities. The path
/devices/template[name]/config have become
/devices/template[name]/ned-id[id]/config.
The reason for this is that with CDM ambiguities between the same XML namespace for different ned-ids has been introduced. This new list makes it possible to handle such ambiguities in a template.
When an existing NSO installation is migrated to CDM, NSO will automatically, as part of the migration process, attempt to move existing templates in the configuration into this new form. However, templates stored as XML files will need to be changed manually.
Device group RPCs is the name of the functionality which makes it possible to invoke an RPC on all viable devices in a device group. The viable devices are the ones in the device group that have implemented the RPC.
The same problem with ambiguous XML namespaces occurs here
as for device templates. Namely that the device RPC can
have ambiguities in inputs and output for different ned-ids
on the same XML namespace. Therefore the path in the NSO
YANG model for the device group RPCs has moved from
/devices/device-group[name]/rpc
to /devices/device-group[name]/ned-id[id]/rpc.
As a result, the user will need to list the ned-ids for the RPC that should be invoked for the device-group. Note, that only the devices that have implemented the RPC can be invoked. In addition the ned-ids need also to match the device-type of the devices.
Notification kickers were earlier defined in a submodule to the tailf-ncs YANG module. This had some drawbacks where one major drawback was that it prevented the tailf-ncs module from being device compiled.
The notification kicker YANG module now has a new XML namespace and new prefix. Code that uses notification kickers might need to change.
In general the Java/C/Python APIs are kept intact. Still under the hood they have undergone major changes.
However certain API calls will fail if they internally try
to traverse schema information past a mount-point e.g
/devices/device/config without instance
information so that an internal device-type/ned-id lookup
can be performed.
Some API calls have therefore new variants which typically also passes a transaction and a path as arguments. The reason to pass also the transaction is to handle the possibility that new devices are created in the same transaction that the internal lookup needs to retrieve. If no mount-points are traversed all API calls work as before.
In the Java API, schema node lookups was previously
performed by the
MaapiSchemas.findCSNode(String nsName, String fmt,
Object... arguments) method. This still holds as long
as the path, defined in fmt, does not traverse a
mount-point. To traverse a
mount-point
a new method needs to be used, namely
MaapiSchemas.findCSNode(MountIdInterface mountGetter,
String nsName, String fmt,
Object... arguments). The latter method will hold
for any node and is there for preferred.
The following code snippet shows example of the usage:
// Schema traversal using the com.tailf.maapi.MountIdCb implementation // of the interface MountIdInterface. MaapiSchemas.CSNode node; node = schemas.findCSNode(new MountIdCb(this.maapi, tid), Ncs.uri, path); // If no current transaction id, tid, is available then -1 is allowed node = schemas.findCSNode(new MountIdCb(this.maapi, -1), Ncs.uri, path);
In the Java API the ConfPath object is a primitive that is
extensively used. The ConfPath(String path,
Object... arguments) constructor is
the most common and has the same problem of traversing a
mount-point.
To change all usage of ConfPath with a new constructor
would not be viable so instead the internal implementation
of the ConfPath(String path,
Object... arguments) constructor is changed so
that a String path is deferred until it is used in a Maapi
or Cdb context.
ConfPath p = new ConfPath("/ncs:devices/device{xyz}/config/top");
// At this point the parsing of this path is deferred since the
// moint-point /ncs:devices/device/config is traversed.
// This can be verified using the ConfPath.isParsingDeferred() method.
// In this case p.isParsingDeferred() will return true
// Any usage in Maapi or Cdb will work and resolve the parsing, for instance
boolean res = maapi.exists(tid, p);
// After this call p.isParsingDeferred() will return false.
However the caveat is that ConfPath can be used before parsing is resolved. Some methods are ok to use, but the following for methods will fail.
-
getCSNode() -
getKP() -
toString() -
toXPathString()
If any of these methods are called before parsing is resolved they will throw a Conf.AmbiguousNamespaceException.
Keep in mind that this exception only occurs for ConfPath with deferred parsing because of mount-point traversal. And only before they are used in Maapi or Cdb. If this still is the case there are different ways to resolve it. First the problematic scenario:
ConfPath p = new ConfPath("/ncs:devices/device{xyz}/config/top");
p.toString() // this will throw an AmbiguousNamespaceException.
boolean res = maapi.exists(tid, p);
Resolving by moving:
ConfPath p = new ConfPath("/ncs:devices/device{xyz}/config/top");
boolean res = maapi.exists(tid, p);
p.toString() // now it is ok.
Resolving using new constructor:
// Use an constructor that makes the Maapi transaction available for
// parsing: ConfPath(maapi, th, path).
// There is also an corresponding constructor for Cdb: ConfPath(Cdb, th, path).
ConfPath p = new ConfPath(maapi, th, "/ncs:devices/device{xyz}/config/top");
p.toString() // now this works
boolean res = maapi.exists(tid, p);
Set a MountIdInterface instance to a deferred path:
ConfPath p = new ConfPath("/ncs:devices/device{xyz}/config/top");
if (p.isParsingDeferred()) {
p.setMountIdGetter(new MountIdCb(maapi, tid));
}
p.toString() // now this works
boolean res = maapi.exists(tid, p);
The ncsc tool now have a argument --ncs-ned-id
which is mandatory in conjunction with --ncs-compile-bundle
and --ncs-compile-module.
In NSO 5.1 there are some functionality that has been removed that was earlier deprecated.
In the java api the NavuCdbXXXSubscribers has been removed. How to handle this and do adaptations in the subscription code is covered in Appendix I.
The old prime webui has been removed. See Appendix II.