ProVision Plus 2 - 4 - 0 NBI System Integration Guide - May2019
ProVision Plus 2 - 4 - 0 NBI System Integration Guide - May2019
ProVision Plus 2 - 4 - 0 NBI System Integration Guide - May2019
Version: 2.4.0
260-668283-001
Copyright & Terms of Use
Warranty
Aviat Networks makes no representation or warranties with respect to the contents hereof and
specifically disclaims any implied warranties or merchantability or fitness for any particular purpose.
Further, Aviat Networks reserves the right to revise this publication and to make changes from time
to time in the content hereof without obligation of Aviat Networks to notify any person of such
revision or changes.
Trademarks
All trademarks are the property of their respective owners.
Contents
Copyright & Terms of Use .......................................................................................................... iii
Contents ..................................................................................................................................... v
Chapter 1. Introduction............................................................................................................ vii
Preface ...................................................................................................................................... vii
Additional Reading Resources ................................................................................................. viii
Intended Audience ................................................................................................................... viii
Chapter 2. Getting Started ......................................................................................................... 9
Installing and Running ProVision Plus ........................................................................................ 9
NBI Product Module License ...................................................................................................... 9
Module Technology Licenses and YANG Data Model Availability ............................................... 9
RESTCONF Client Examples ................................................................................................... 10
ProVision Plus Northbound Interface API Documentation .................................................... 10
ProVision Plus RESTCONF NBI Postman Collection Export................................................ 13
Chapter 3. Background Concepts........................................................................................... 17
Network Orchestration Architecture Overview .......................................................................... 17
The Role of the Network Services Orchestrator ........................................................................ 18
Introduction to YANG................................................................................................................ 18
Introduction to RESTCONF ...................................................................................................... 18
Schema-Mount and the RESTCONF NBI ................................................................................. 19
Types of YANG modules .......................................................................................................... 20
Obtaining the ProVision Plus YANG Modules ........................................................................... 21
The ProVision Plus YANG Library Implementation ................................................................... 21
Network Management Datastore Architecture (NMDA) and Datastores .................................... 22
Client Authentication ................................................................................................................ 23
NETCONF Access Control Model (NACM) ............................................................................... 23
Chapter 4. Accessing the ProVision Plus NBI ....................................................................... 25
Verify the ProVision Plus Server is Running ............................................................................. 25
Accessing the RESTCONF NBI ................................................................................................ 25
Discovering the RESTCONF Server YANG library ................................................................... 27
Discovering the RESTCONF Server Capabilities ...................................................................... 29
Accessing the Supported NMDA Datastores via RESTCONF .................................................. 30
NETCONF Access Control Model (NACM) permissions ........................................................... 32
Policing YANG Data Availability by Technology Module Licenses ............................................ 34
Network Topology Discovery .................................................................................................... 35
The Managed-device Mount Point ............................................................................................ 37
Managed-device Mounted YANG Modules ............................................................................... 39
Chapter 5. ProVision Plus NBI Details .................................................................................... 41
Chapter 1. Introduction
Preface
This document has been prepared by Aviat Networks in the interests of aiding the integration of SDN
network service orchestration (NSO) applications with the ProVision Plus northbound interface (NBI)
for the purposes of network topology discovery and managed element configuration discovery. In
order to facilitate monitoring of the network domain the NBI also exposes models to facilitate
discovering and managing device and service alarms as well as facilitate a myriad of other network
management functions (including fault reconciliation).
The ProVision Plus RESTCONF NBI consists of an interface using extensible and open standards
for NSO clients to integrate with the ProVision Plus server. The interface utilises a suite of openly
available data schema models (described using YANG (RFC 7950), an easily accessible and
widespread schema description language) and implements a stand-alone network management
sever geared toward RESTCONF protocol (RFC 8040) compliance.
This system integration guide is intended to introduce developers to the ProVision Plus RESTCONF
NBI. It discusses aspects of the API that are unique to ProVision Plus compared to the RESTCONF
interfaces of 3rd-party network management servers and provides functional API request examples.
This document also covers:
• RESTCONF NBI key concepts
Intended Audience
The information in this guide is intended for system integration engineers tasked with integrating the
capabilities provided through the ProVision Plus RESTCONF-based northbound interface (NBI) into
a customer’s operation support system (OSS), network orchestrator, SDN super controller, or custom
SDN applications.
Note that the ProVision Plus NBI Module Technology Licence must be installed in order to
use these tools with the RESTCONF NBI.
The Swagger API documentation is rendered from the file restconf_api.yaml which is
itself hosted by the ProVision Plus server as a static resource. This file contains a ‘host’
parameter for specifying the RESTCONF domain and port for the Swagger client target its
requests. The correct ProVision Plus RESTCONF northbound interface domain should be set
in the ‘host’ field so that requests are sent to the right URL.
In instances where the RESTCONF NBI HTTPS port has been modified from the default of
443, the port section of the ‘host’ field in restconf_api.yaml should be changed to match
the ProVision Plus server’s NBI port configuration.
swagger: "2.0"
info:
version: "1.0"
...
title: "ProVision Plus Northbound Interface"
host: "localhost:443" <-------
The source file can be found and edited at the following location on the ProVision Plus server:
<ProVision Plus install directory>\public\doc\restconf\restconf_api.yaml
Note: The ProVision Plus northbound Interface defaults to the standard of HTTPS Port-443.
This setting can be overridden, so check with your ProVision Plus system administrator to
determine the correct port for accessing the ProVision Plus northbound interface.
Once the page has loaded, the ProVision Plus API description document should be presented on the
screen. The document consists of a series of sections describing ProVision Plus RESTCONF NBI
request examples that map to an array of SDN Use cases, including those for:
• Retrieval of managed network elements
• Retrieval of managed network element configuration
• Retrieval of logical termination points
• Retrieval of logical topology links
• Retrieval of alarms for alarm monitoring
• Querying ProVision Plus system connectivity
Each section of the API document contains a series of request examples that can be used to
demonstrate the corresponding SDN use case. For each request, the document gives a brief
explanation of the request, describes any applicable request parameters, expected HTTP status
codes and provides a range of example responses.
In addition to the information about each request, the user can also exercise the pre-set requests
against a PV+ RESTCONF server by using the ‘Try It Out’ button.
Note: the RESTCONF server’s base-URL is shown at the top of the API description document. This is
configured in the ‘host’ section of restconf_api.yaml on the ProVision Plus server:
RESTCONF NBI requests require user authentication using Basic Authentication, therefore the next
step is to provide valid ProVision Plus user account credentials.
2. Click the ‘Authorize’ button. The authorization dialog box should appear.
In the ‘Username’ field, enter your ProVision Plus user account’s email address.
In the ‘Password’ field, enter the ProVision Plus user account’s password.
Click ‘Authorize’ to save the new NBI user account credentials.
The authorization credentials should remain effective until the API description document
page is reloaded within the web browser, at which point they will need to be re-entered.
The request will be sent to the RESTCONF server instance and the response will be shown in the
section below the request (as well as additional information about the request itself, e.g. headers and
a sample curl command).
The Postman Collection resources can be found at the locations in the following table.
Table 1. Postman resource file URLs.
The Postman environment file also contains a variable definition for RESTCONF_PORT which
specifies the HTTPS port for sending requests to the ProVision Plus RESTCONF northbound
interface. In cases where the ProVision Plus server has been configured to use an HTTPS port
other than the default of 443, the value of the RESTCONF_PORT environment variable must be
modified accordingly.
For more information on the Postman HTTP client please visit: https://www.getpostman.com
Please see the Postman user documentation for detailed information on importing the above
collection and environment files into the Postman client and executing requests.
Note, these steps require you to have installed the HTTP client Postman (available from
https://www.getpostman.com). Postman is available for the Windows, macOS and Linux
platforms.
The steps detail the process of importing the ProVision Plus request examples into Postman so that
they can be exercised against the RESTCONF NBI.
The Postman environment file is used to specify values for common variables that are used within
the Postman examples (these are referenced using ‘{{‘ and ‘}}’ delimiters in the requests, e.g.
{{RESTCONF_HOST}}).
• click the ‘Import’ button in the top-left corner of the Postman application.
7. Disable SSL certificate validation (to allow self-signed certificates to be used with the
ProVision Plus RESTCONF NBI):
• In Postman, click ‘File’ and click ‘Settings’ to open the settings dialog box.
• Click “SSL certificate validation” to set it to OFF.
• Close the settings dialog box.
The collection of requests mirrors the SDN Use case examples given in the
ProVision Plus Northbound Interface API document (described above).
• click a request to select it. The request will be shown in the main tab.
After sending the example request, the response will be shown in the Response pane of the
Postman application.
• Automation
• Dev-ops
• Operations Support System (OSS) Integration
• Software Defined Networking (SDN)
Whilst the ProVision Plus network management server is responsible for managing the devices within its
own domain, it provides an interface to consumers that provide the glue required to orchestrate
independent administrative network controller domains. The figure below illustrates the hierarchical
architecture.
RESTCONF NBI
Network Domain Controller A
Network Domain Controller B
(ProVision Plus)
The use of open standards (such as RESTCONF and YANG models) means that applications can be
written to interoperate with a range of Network Domain Controller (NDC) systems, with little-to-no
customisation required to provide successful integration with new systems. Standardised data models and
common operation mechanisms provide for an extensible architecture. Given the dependence on
openness and data model standardisation, an NDC’s northbound interface fills a particularly important role
in enabling the above architecture.
Introduction to YANG
YANG is a modular, extensible data-modelling language used to describe the schema of configuration
and state data exchanged via the NETCONF and RESTCONF network configuration protocols. YANG
modules define schema constructs that describe the tree-like hierarchy of instance data, types,
notifications and the input/output parameters of operations that can act on resources modelled by the
YANG schema. Using XPATH expressions YANG modules can also define the relationships between
YANG schema nodes, allowing the author to define relationships between and constraints on the parts of
a module, or between different modules within the entire schema space. The YANG language is protocol
independent (although heavily coupled to NETCONF) and can be encoded into any encoding format
(typically as XML or JSON).
In summary, it is these properties and suitability that makes YANG the language of choice for defining the
schema that ProVision Plus uses to model the resources made accessible via its RESTCONF NBI.
For more information on the YANG modelling language please see the YANG 1.1 standard, RFC 7950.
Introduction to RESTCONF
RESTCONF is a RESTful network management protocol (running over the secure HTTPS transport). It is
ideal for web-based applications that are intended to interact with a network management controller.
As RESTCONF is based on HTTP, the protocol is ideally suited for the existing request routing
infrastructure that makes up the bulk of the world-wide web. RESTCONF piggybacks on to the HTTP
standard and allows the employment of concepts such as resource caching, standardised authentication
schemes, error response reporting and protocol operations.
A RESTCONF API exposes resources that provide a resource-oriented abstraction of device and services
within the networking domain. These resources are made accessible using a predefined series of CRUDX-
style operations that map to the main methods defined by the HTTP protocol. These operations can be
used to interrogate the state of the resources within the network management controller, or to effect
change by writing new information to those resources, or to invoke remote procedure calls to indirectly
affect the configuration or state of the managed network entities. Using extensions such as NACM, security
and access permissions are baked into the protocol, allowing the enforcement of access control rules.
Finally, RESTCONF also incorporates a notification dispatch mechanism whereby clients can subscribe
to receive published notifications and be notified upon changes in the configuration or state data of a
resource.
As part of the standard, RESTCONF defines conventions to map a YANG schema specification to a unique
resource location for resource retrieval and management. RESTCONF does this by providing rules for
constructing unique resource locations (URL) for addressing network configuration instance data
described by the YANG hierarchy. If the YANG hierarchy is represented as a hierarchical tree of data
nodes, then RESTCONF describes how to access the nodes in the tree. As the YANG effectively describes
the API contract between the server and client in terms of constructing requests, there is no need for
HATEOAS-style hypermedia constructs that other APIs rely on to allow an API to be discovered by a
client.
Appendix B of this document includes a list of the YANG models that are implemented and supported by
the ProVision Plus RESTCONF northbound interface.
Being RESTful in nature (and not requiring the network management server to track state between client
requests) means RESTCONF servers can be written with scalability in mind.
For more information on the RESTCONF protocol please see the RESTCONF standard, RFC 8040.
Specifically, the set of YANGs exists as a set of “derived” YANGs, whereby the content of each YANG
module only includes the portions of the YANG that are implemented by the RESTCONF sever.
A RESTCONF northbound interface client can retrieve the package of derived YANG modules by
navigating to the following URL in a web browser:
https://<restconf-host>/doc/restconf/derived-yang-package.zip
At its highest level the YANG library response object is structured as per the following YANG
fragment:
module: ietf-yang-library
+--ro yang-library
+--ro module-set* [name]
| +--ro name string
| +--ro module* [name]
| +--ro import-only-module* [name revision]
| +--ro name yang:yang-identifier
| +--ro revision union
| +--ro namespace inet:uri
| +--ro location* inet:uri
| +--ro submodule* [name]
| +--ro name yang:yang-identifier
| +--ro revision? revision-identifier
| +--ro location* inet:uri
+--ro schema* [name]
| +--ro name string
| +--ro module-set* -> ../../module-set/name
+--ro datastore* [name]
| +--ro name ds:datastore-ref
| +--ro schema -> ../../schema/name
+--ro content-id string
A RESTCONF client can use instances of the above object type to discover:
• the name, revision and hierarchy of modules that comprise a module set.
• the sets of schemas (comprised of the module-sets) defined above.
• the NMDA datastores that are supported by the network management server and the schema
that define them.
• the YANG library ‘content-id’, which can be used by the client to confirm whether the YANG
library content has changed.
For more information on NMDA please read ‘Network Management Datastore Architecture (NMDA)’
RFC 8342.
200, OK
{
"expires": "2019-02-24T22:28:03Z",
"links": [
{
"rel": "restconf",
"type": "application/yang-data+json",
"href": "https://127.0.0.1/restconf/restconf"
},
{
"rel": "restconf_1.0",
"type": "application/yang-data+json",
"href": "https://127.0.0.1/restconf/1.0/restconf"
}
]
}
then the client request should send the following authorization header
Authorization: Basic YWxpY2U6cXVpY2tCcm93bkZveDEyMw==
Querying one of the API version entry point URLs should give a response like the one shown below:
GET https://<restconf-host>/restconf/restconf
200, OK
{
"ietf-restconf:restconf": {
"data": { ... },
"operations": { ... },
"yang-library-version": "2018-10-16"
}
}
Having retrieved the RESTCONF API root resource response, the client can now query the ‘/data’
tree as described in the RESTCONF specification, RFC 8040.
The YANG library resource is comprised of a list of module-sets where each module-set specifies a
set of modules and the meta information about the revision and namespace of each module. The
YANG library resource also presents a content-id field that the client can use to determine whether
the set of YANG modules representing the data schema of the top-level resource has changed.
A RESTCONF client can query the root YANG library by requesting the top-level ‘yang-library’
resource of the ietf-yang-library module, i.e.
GET https://<restconf-host>/restconf/restconf/data/ietf-yang-library:yang-
library
200, OK
{
"ietf-yang-library:yang-library": {
"module-set": [
{
"name": "root-modules",
"module": [
{
"name": "ietf-yang-library",
"revision": "2018-10-16",
"namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-library"
},
{
"name": "ietf-yang-types",
"revision": "2013-07-15",
"namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types"
},
...
{
"name": "ietf-yang-schema-mount",
"revision": "2018-10-16",
"namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount"
}
],
"import-only-module": []
}
],
"datastore": [
{
"name": "ietf-datastores:operational",
"schema": "root-modules-schema"
},
{
"name": "ietf-datastores:running",
"schema": "root-modules-schema"
}
],
"schema": [
{
Aviat Networks 10 May 2019 27
"name": "root-modules-schema",
"module-set": [
"root-modules"
]
}
],
"content-id": "49678023c0c609eeb4164549d405f4db"
}
}
In addition to the root YANG library resource, the client should also retrieve the YANG library resource
underneath any mount-points that have been defined within the YANG hierarchy. In the same fashion as
above, YANG libraries defined under a mount point define the list of modules that are accessible below
the mount point. Below is an example of a YANG library request showing the schema that exists below
the managed-devices mount-point of the avnm-device-mount YANG module. Note, that in the case
of this request example, a ‘device-id’ parameter is specified for the specific instance of the managed-
device.
GET https://<restconf-host>/restconf/restconf/data/avnm-device-mount:managed-
devices/managed-device=<device-id>/ietf-yang-library:yang-library
200, OK
{
"ietf-yang-library:yang-library": {
"module-set": [
{
"name": "avnmDeviceMountManagedDevicesManagedDevice",
"module": [
{
"name": "ietf-yang-library",
"revision": "2018-10-16",
"namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-library"
},
{
"name": "ietf-yang-types",
"revision": "2013-07-15",
"namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types"
},
...
{
"name": "ietf-system",
"revision": "2014-08-06",
"namespace": "urn:ietf:params:xml:ns:yang:ietf-system"
},
],
"import-only-module": []
}
],
"content-id": "3b1da58d1b6e6faab46370d297c6db23"
}
}
GET https://<restconf-host>/restconf/restconf/data/ietf-restconf-
monitoring:restconf-state/capabilities
200, OK
{
"ietf-restconf-monitoring:capabilities": {
"capability": [
"urn:ietf:params:restconf:capability::defaults:1.0?basic-mode=explicit",
"urn:ietf:params:restconf:capability::depth:1.0",
"urn:ietf:params:restconf:capability::fields:1.0"
]
}
}
The ‘RESTCONF Capability URNs’ register defines the set of capabilities identifiers that can be used
in the RESTCONF server’s capability list. The base list of RESTCONF capability URNs is available
in RFC 8040. Other RFC documents may define additional capabilities that extend the base set
defined in RFC 8040.
Table 4. ProVision Plus network view mapping to NMDA Datastores (recreated from Table 3).
These datastores are individually accessible via the RESTCONF instance-data tree using the request URI
conventions described in the document “RESTCONF Extensions to Support the Network Management
Datastore Architecture” (RFC 8527). The RFC defines the correct mechanism to structure URLs for
accessing the top-level datastore resources as follows:
{+restconf}/ds/<fully-qualified datastore name>
whereby the {+restconf} portion specifies the URL prefix (API root entry point), and the <fully-
qualified datastore name> portion specifies the datastore’s full designation as defined in the
‘NMDA Datastore’ column of Table 4. The root of the instance data trees for the operational and
running datastores respectively are:
{+restconf}/ds/ietf-datastores:operational
and
{+restconf}/ds/ietf-datastores:running
Note that as specified in RFC 8527, the URL ‘{+restconf}/data’ is an alias for the operational
datastore, {+restconf}/ds/ietf-datastores:operational.
As a final example, the following requests could be used to retrieve the baseline (running) and live
(operational) hardware configurations for a managed-device:
Network Engineer In addition to the capabilities provided to the Network Operator role, the Network
Engineer role provides additional capabilities to discover managed device
credentials.
The permissions afforded to each user account role in the table above are enforced through a
collection of access rules that are defined according to the NETCONF Access Control Model (NACM)
standard, RFC 8341. The role permissions mirror those allowed by the ProVision Plus user interface
and the roles apply to all data resources modelled by the ProVision Plus RESTCONF NBI.
Access to resources within the NBI datastore via ProVision Plus is controlled through a series of rules
that target a YANG schema node (and its descendants). Rules are grouped by the roles that they
apply to and can be discovered at runtime from the NBI itself. This is covered in the examples below.
Note that the set of access rules is defined statically and cannot be modified by a user.
module-name Name of the module associated with this rule (or the wildcard value ‘*’ ).
path Data node instance-identifier associated with the data node, action, or notification
controlled by this rule.
rpc-name For RPC-based rules, this field matches if it has the value '*' or if its value matches
the requested operation name.
By default, with no ‘encompassing’ rules specified, permissions to access a schema node are denied
unless a matching rule is present that specifies that access should be allowed for a given operation
on that data node. If a client makes a request to perform an operation on a data node that is not
permitted by a rule, the RESTCONF server will return a ‘401, Unauthorized’ response.
Rules for a given data node are also inherited by the descendants of that node. This means a rule
permitting access to the top of the schema tree allows access to the nodes below it, unless there is
a preceding rule that denies access to the operation on the descendant nodes. Rules are processed
in the order presented in the rule list.
Some user accounts may be assigned multiple user account roles. If an operation on a node is
permitted by any of the user account roles, then the operation is permitted for the user on that specific
node.
Rules are discoverable by querying the root-level ietf-netconf-acm:nacm endpoint resource, as
shown in this example below:
GET https://<restconf-host>/restconf/restconf/data/ietf-netconf-acm:nacm
200, OK
{
"ietf-netconf-acm:nacm": {
"rule-list": [ {
"name": "operator",
"group": [ "operator" ],
"rule": [
{
"name": "operator /ietf-network:networks",
"action": "permit",
"module-name": "ietf-network",
"path": "/ietf-network:networks",
"access-operations": "01000"
},
...
]
},
...
],
"groups": {
"group": [
{
"name": "admin",
"user-name": []
},
{
"name": "engineer",
"user-name": []
},
{
"name": "oper",
"user-name": []
}
]
}
For more information on the NACM rules mechanism, please see RFC 8341.
Specifically, each Product Module supported by ProVision Plus has an associated set of YANG modules that
model the data associated with that Product Module. Those YANG modules are constituted by configuration and
non-configuration data, but also operations (RPCs and Actions). Please see Appendix B of this guide for details
on the Technology Module Licenses that apply to each YANG module.
Taken as an example, the ‘CE Fault’ product module explicitly allows access to the YANG modules associated
with the modelling of VLAN, SyncE and PTP data. Therefore, in ProVision deployments where a given license has
not been installed, ProVision will not provide access to data resources or operations that fall under the umbrella
of any unlicensed Product Modules.
Whilst a Product Module is unlicensed, the YANG model data exposed by the ProVision Plus
NBI for that Product Module cannot be relied-upon to be accurate or current in any capacity.
Likewise, it should be noted that just because a YANG module is indicated as being supported by the ProVision
Plus northbound interface, it does not necessarily mean that the YANG data model is populated, current (or even
useable) if the appropriate Product Module license has not been activated.
Each network layer is represented by topology nodes corresponding to the representations of individual
services and physical managed-devices that make up the network. The edges of a topology graph
represent the service connections or membership-relationships that exist between individual nodes.
Finally, each graph-edge is terminated at the pair of nodes by a pair of termination points (representing
the head and tail end of that connection respectively). As an example, two managed devices connected
via an ethernet link both on interface GigabitEthernet0/1 will be represented in the following way:
• Two edges between the two nodes: each representing a unidirectional physical layer-1 link
between the managed devices.
• One termination point on each node: representing the logical termination point that terminates an
end of a physical link.
The hierarchy of network layers is described by the supporting-network list entries for each network
in the list. The layers referenced in the supporting-networks lists define the network graphs that support
the topology graph, and from this relationship, the entire network layer hierarchy can be discovered. In
addition to the supporting-networks relationship, the topology also includes:
In the same fashion as the supporting-networks relationship hierarchy described above, the other
supporting-node/links/termination-points fields provide hierarchical topology information in the same way.
As defined in the ietf-networks YANG, each topology node has a node-id field that is used to
uniquely identify the network node. These IDs are the same as those used in the avnm-device-mount
‘managed-device’ list, and so this common identifier can be used to relate the network topology graph
nodes to the managed-device network elements themselves.
The complete network topology can be discovered by querying the ietf-networks module at the root
of the operational datastore. The example below shows a hypothetical topology for two nodes connected
by a layer-1 gigabit ethernet link (and only shows the layer-1 nodes, links and termination-point resources
in the interests of brevity):
200, OK
{
"ietf-network:networks": {
"network": [
{
"network-id": "avnm-network:network_layer1",
"node": [
{
"node-id": "avnm-node:0:1",
"supporting-node": [],
"ietf-network-topology:termination-point": [
{
"tp-id": "avnm-tp:GigabitEthernet0/1",
"supporting-termination-point": []
}
]
},
{
"node-id": "avnm-node:0:2",
"supporting-node": [],
"ietf-network-topology:termination-point": [
{
"tp-id": "avnm-tp:GigabitEthernet0/1",
"supporting-termination-point": []
}
]
}
],
"ietf-network-topology:link": [
{
"link-id": "avnm-link:0:1:GigabitEthernet0/1,0:2:GigabitEthernet0/1",
"supporting-link": [],
"source": {
"source-node": "avnm-node:0:1",
"source-tp": "avnm-tp:GigabitEthernet0/1"
},
"destination": {
"dest-node": "avnm-node:0:2",
"dest-tp": "avnm-tp:GigabitEthernet0/1"
},
}
]
}
]
}
}
For more information on using the ietf-networks model to discovery the network topology, please see RFC
8345.
container managed-devices {
list managed-device {
key "managed-device-id";
leaf managed-device-id { <-- matches the ietf-network topology ‘node-id’
type nw:node-id;
description
"The unique ID of the managed device. If the network management system
implements ietf-network-topology for
L1 topology, this node-id should match the node-id in L1 topology.";
}
leaf name {
type string;
description "Human readable name of the managed device. Name should be
unique but this may not be enforced.";
}
leaf admin-state {
type avnm-types:admin-state
description "The administrative state for this managed device.”
}
leaf oper-state {
type avnm-types:oper-state;
config false;
description
"The operational state for this managed device.”
}
yangmnt:mount-point "device-yang-root" {
description
"Root for mounting device-centric YANG models.";
}
}
}
}
As per the above module excerpt, the managed-device list elements contain leaves that allow the client
to uniquely identify a managed-device in the list. The managed-device-id, name, admin-state and
oper-state properties convey the core device details and management configuration/state.
Having discovered the YANG modules supported by the device, the client can next query the device-
specific YANGs for the required instance data. The example below illustrates a request for the ietf-
hardware instance for managed-device with ID avnm-node:0:1.
GET https://<restconf-host>/restconf/restconf/ds/ietf-
datastores:operational/avnm-device-mount:managed-devices/managed-device=avnm-
node:0:1/ietf-hardware:hardware
200, OK
{
"ietf-hardware:hardware": {
"last-change": "2019-02-28T15:05:45+00:00",
{
"name": "GigabitEthernet1/1",
"class": "ianaent:port",
"description": "GigabitEthernetPort 1",
"parent": "Terminal1",
"parent-rel-pos": 1,
"is-fru": "false",
"contains-child": [],
"uri": [],
"state": {
"state-last-changed": "2019-02-28T15:05:16+00:00",
"admin-state": "unlocked",
"oper-state": "enabled",
"usage-state": "active",
"alarm-state": "indeterminate",
"standby-state": "providing-service"
},
"sensor-data": { ... }
},
...
]
}
}
Below is a list of the core YANG modules that can be queried at the mount-point, organised by author.
• ietf-hardware
• ietf-interfaces
• ietf-system
• avnm-device
2. All API access by the client must be performed using a secure HTTPS connection. Insecure HTTP
connection is not supported.
3. The RESTCONF API only supports the application/yang-data+json MIME type. All
content returned by the NBI uses this Content-Type. All POST requests to the NBI are required
to have this Content-Type header value. XML payload Content-Types are not supported.
4. API errors are reported back to the client using the standard RESTCONF error response codes
and response objects described in Section 7 of RFC 8040
Resource Requests
1. The YANG library modules-state container tree (providing backward-compatibility support for
the legacy YANG library module for non-NMDA clients) is not implemented.
2. The NBI provides READ-ONLY access to instance data resources. There is currently no support
for writing to instance data resources using POST, PUT or PATCH requests. Any changes to the
instance data must be indirectly invoked via an appropriate RESTCONF operation (RPC or
action).
11. Resource-level ETags are supported and reported in the ETag response header.
12. Response list element ordering is as per the ‘system-defined’ order. User-ordering of response
list elements is not currently supported.
2. When an operation is queued but has not completed at the point of a response timeout occurring, the
RESTCONF server will return a ‘202, Accepted’ HTTP response status code.
2. The ProVision Plus network management server does not perform any client certificate validation
upon receiving a request.
3. The RESTCONF client must perform server-certificate validation. If a self-signed certificate is installed
to be used by the ProVision Plus RESTCONF NBI, the client must be able to support self-signed
certificate validation.
4. The ProVision Plus network management server is pre-packaged with a self-signed certificate that
can be overridden by an installer when the server instance is deployed. Please see the ProVision Plus
Installation and Administration Guide (PN 260-668272) for more information on how to install a custom
certificate for use with the RESTCONF NBI.
The chapter is organised into separate sections, each discussing the request flow used to exercise the
respective SDN use case. Each section provides a discussion of the topics as well as providing example
requests.
The client can use the network topology tree to discover the layer-1 topology nodes that comprise the
network-layer1 layer in the topology tree. From these nodes, the set of managed-device IDs is known, and
the IDs can be used to index individual managed devices that are mounted within the managed-device list
of the avnm-device-mount YANG.
Discovery begins by the client first querying the topology tree’s layer-1 network nodes using the following
request:
GET https://<restconf-host>/restconf/restconf/ds/ietf-datastores:operational/ietf-
network:networks/network=avnm-network:network_layer1?fields=network-id;node(node-
id)
200, OK
{
"ietf-network:network": [
{
"network-id": "avnm-network:network_layer1",
"node": [
{
"node-id": "avnm-node:0:1"
},
{
"node-id": "avnm-node:0:2"
}
]
}
]
}
From the response, the client can query the appropriate NMDA datastore for YANG instance data that it is
interested in and make queries to the mounted modules accordingly on a per-‘managed-device’ basis.
e.g.
GET https://<restconf-host>/restconf/restconf/ ds/ietf-datastores:operational/avnm-
device-mount:managed-devices/managed-device={node-id}/avnm-
device:device?fields=name;class-name;class-display-name
200, OK
{
"ietf-hardware:hardware": {
"last-change": "2018-04-29T05:03:42.945Z",
"component": [
{
"name": "CTR8540 1",
"class": "ianaent:chassis",
"description": "CTR8540 Chassis",
"parent": 1,
"parent-rel-pos": 1,
"serial-num": "EBT1551E220",
"model-name": "CTE-002-001",
"is-fru": "true"
},
{
"name": "Module Fan Tray 1",
"class": "ianaent:module",
"description": "Fan tray",
"parent": 285212672,
"parent-rel-pos": 1,
"is-fru": "true"
},
...
44 10 May 2019 Aviat Networks
{
"name": "RAC3",
"class": "ianaent:module",
"description": "RACx1 plug in module",
"parent": 335544320,
"parent-rel-pos": 1,
"hardware-rev": "7",
"software-rev": "3.9.0.44.6014",
"serial-num": "EBT1553AA3A",
"model-name": "CTX-800-001",
"is-fru": "true"
},
...
]
}
}
The response above contains a list of components (defined in the ietf-hardware module) that comprise
the managed network element. Each list element describes the respective component.
200, OK
{
"ietf-interfaces:interfaces": {
"interface": [
{
"name": "Slot0/1",
"description": "Ethernet Interface",
"type": 6,
"admin-status": "up",
"oper-status": "up",
"if-index": 1,
"phys-address": "'00:E0:E2:95:20:82'",
"speed": 1000000000
},
{
"name": "Slot0/2",
"description": "Ethernet Interface",
"type": 6,
"admin-status": "up",
"oper-status": "up",
"if-index": 10,
"phys-address": "'00:E0:E2:95:20:8B'",
"speed": 1000000000
},
...
{
"name": "Slot0/11",
"description": "Ethernet Interface",
"type": 6,
Aviat Networks 10 May 2019 45
"admin-status": "up",
"oper-status": "up",
"if-index": 11,
"phys-address": "'00:E0:E2:95:20:8C'",
"speed": 1000000000
}
]
}
}
The response above contains a list of interfaces currently components (defined in the ietf-interfaces
module) available on the managed network element. Each list element describes the respective interface’s
configuration.
To perform a ‘sync’ operation and request all alarms, a RESTCONF client can invoke the query RPC from
the avnm-events module. The RPC body specifies the filter used when selecting alarms to return within
the RPC response. All query filter fields are optional, with the default behaviour being to limit the number
of alarms returned in the list to a maximum of 1000 items.
Request 1:
POST https://<restconf-host>/restconf/restconf/ds/ietf-datastores:operational/avnm-
events:query
Request Payload:
{
"avnm-events:input": {
"severity": ["critical", "major", "minor", "warning"],
"is-active": true
}
}
Response:
200, OK
{
"avnm-events:output": {
"event": [
{
"resource": "avnm-node:0:0",
If desired, the client can add the ‘state’ field to the filter to limit the response to only those alarms that
have the value of ‘cleared’ or ‘not-cleared‘. The response payload contains a list of alarms that match
the filter specified in the RPC request body.
Optionally, the client can specify a larger or smaller page size to set the number of items to return. If the
number of alarms returned matches the limit specified in the response, the client should retrieve the next
page of alarms. This can be achieved by adding a start date/time filter field to specify the point in time to
retrieve all alarms from. Using the ‘time-raised’ field from the final alarm in the list, means the alarms
in the returned response should immediately follow the last-returned list item.
Request Payload:
{
"avnm-events:input": {
"severity": ["critical", "major", "minor", "warning"],
"time-raised": "2019-02-08T07:01:32.292Z "
}
}
Response:
200, OK
{
"avnm-events:output": {
"event": [
{
"resource": "avnm-node:100:2",
"resource-text": "Radio1",
"event-id": 181087,
"event-type": "communications-alarm",
"event-text": "Severely Error Seconds (SES) Ratio Threshold Exceeded",
"event-type-id": "g826-severely-errored-seconds-ratio:Radio1",
"probable-cause-string": "Signal degraded",
"severity": "major",
"is-active": true,
"time-raised": "2019-05-03T05:01:32.292Z",
"time-source": "system",
"operator-state": {
"ack-state": false
}
},
{
"resource": "avnm-node:100:2",
"resource-text": "Radio1",
"event-id": 181088,
"event-type": "communications-alarm",
"event-text": "Ethernet port link down",
"event-type-id": "ethernet-port-link-down:Radio1",
"probable-cause-string": "Loss of signal on interface.",
"severity": "major",
"is-active": true,
"time-raised": "2019-05-03T05:01:32.293Z",
"time-source": "system",
"operator-state": {
"ack-state": false
}
},
...
]
}
}
48 10 May 2019 Aviat Networks
Note: the start-time field is used as a filter to match against alarms with raised-timestamps ‘greater-
than-or-equal-to’ the filter value. This means alarms with the same timestamp used in the start-time
field that were present in the previous request will also be returned in the second response. The event-
id field within an alarm can be used to uniquely identify alarm instances and discount any alarm list items.
Having retrieved the set of alarms, the client can periodically poll the RESTCONF server to discover any
subsequent new alarms that have been raised.
To implement this function, the client should query the RESTCONF NBI for active alarms raised within the
time interval spanning the period of interest. The client calculates the timestamp at the point in time at the
start of the day at the beginning of the 14-day period and uses this in the filter query to the ‘query’ RPC in
avnm-events.
As the chart is purely a summary of the type of alarms (and the total count of each alarm type), the
RESTCONF client can use the fields RESTCONF query parameter to limit the fields that are returned for
each object type. Specifically, we could conceivably limit the returned fields to the alarm event-id,
severity, and is-active.
POST https://<restconf-host>/restconf/restconf/ds/ietf-
datastores:operational/avnm-events:query?fields=avnm-events:output/event(event-
id;severity;is-active)
Request Payload:
{
"avnm-events:input": {
"severity": ["critical", "major", "minor", "warning"],
"state": "not-cleared",
"time-raised": {
"start-time": "2019-03-01T00:00:00.000Z"
}
}
}
{
"avnm-events:output": {
"event": [
{
"event-id": "pv:281087",
"severity": "warning",
"is-active": true
},
...
{
"event-id": "pv:281101",
"severity": "critical",
"is-active": true
}
]
}
}
The response above contains the summarised list of alarms with each list entry limited to the event-id,
severity and is-active fields. This information can then be used to populate the alarm summary
dashboard graph.
The request URL specifies the network layer of interest in the following list-element selector notation path
segment, using the network ID discovered in the previous request:
network=avnm-network:network_layer1
200, OK
{
"ietf-network:node": [
{
"node-id": "avnm-node:0:1",
As the example RESTCONF response object shows, layer-1 contains two L1 logical termination points,
both named ‘Radio1’ for nodes with ID “avnm-node:0:1” and “avnm-node:0:2” respectively.
As an alternative to only querying the termination points for a single network layer, the client could also
query the termination points for all layers at once. To achieve this, the client can send the following request
(targeting the network list and using the fields query parameter to select the branch of interest in the
response object):
GET https://<restconf-host>/restconf/restconf/ds/ietf-datastores:operational/ietf-
network:networks/network?fields=network-id;node(node-id;ietf-network-
topology:termination-point)
200, OK
{
"ietf-network:network": [
{
"network-id": "avnm-network:network_l2vpn",
"node": []
},
{
"network-id": "avnm-network:network_l3vpn",
"node": []
},
{
"network-id": "avnm-network:network_layer1",
"node": [
{
"node-id": "avnm-node:0:1",
"ietf-network-topology:termination-point": [
{
"tp-id": "avnm-tp:Radio1",
"supporting-termination-point": []
}
]
},
52 10 May 2019 Aviat Networks
{
"node-id": "avnm-node:0:2",
"ietf-network-topology:termination-point": [
{
"tp-id": "avnm-tp:Radio1",
"supporting-termination-point": []
}
]
}
]
},
{
"network-id": "avnm-network:network_ptp",
"node": []
},
{
"network-id": "avnm-network:network_pw",
"node": []
},
{
"network-id": "avnm-network:network_synce",
"node": []
},
{
"network-id": "avnm-network:network_te_link",
"node": []
},
{
"network-id": "avnm-network:network_te_tunnel",
"node": []
},
{
"network-id": "avnm-network:network_vlan",
"node": []
},
{
"network-id": "avnm-network:network_vlan_link",
"node": []
},
{
"network-id": "avnm-network:network_vrf",
"node": []
}
]
}
Although the above example specifically deals with the discovery of the layer-1 topology termination
points, the process of discovering the logical termination points for other network service layers works in
the same way.
The request URL specifies the network layer of interest in the following list-element selector notation path
segment, using the network ID discovered in the previous request:
network=avnm-network:network_layer1
GET https://<restconf-host>/restconf/restconf/ds/ietf-datastores:operational/ietf-
network:networks/network=avnm-network:network_layer1?fields=network-id;ietf-network-
topology:link(supporting-link;source/source-node;source/source-tp;destination/dest-
node;destination/dest-tp)
200, OK
{
"ietf-network:network": [
{
"network-id": "avnm-network:network_layer1",
"ietf-network-topology:link": [
{
"link-id": "avnm-link:0:1:Radio1,0:2:Radio1",
"supporting-link": [],
"source": {
"source-node": "avnm-node:0:1",
"source-tp": "avnm-tp:Radio1",
},
"destination": {
"dest-node": "avnm-node:0:2",
"dest-tp": "avnm-tp:Radio1",
}
},
{
"link-id": "avnm-link:0:2:Radio1,0:1:Radio1",
"supporting-link": [],
"source": {
"source-node": "avnm-node:0:2",
"source-tp": "avnm-tp:Radio1",
},
"destination": {
"dest-node": "avnm-node:0:1",
"dest-tp": "avnm-tp:Radio1",
}
}
]
}
]
}
Note that in the case of the second link, the source and destination termination points are reversed. The
response also shows that the topology link does not have any supporting links.
When processing the list of topology links for a layer, the client must interpret the source and destination
termination points for the series of links in the response to determine which links are part of a pair (if any).
Where these pairs exist, the pairs form the two directional components of a single bidirectional link. The client
should list links by their source and destination node and their respective termination point IDs. Links that have
the same ‘node-id’ (source-node, dest-node) and termination point tuple (but reversed in terms of source
and destination) are part of a bidirectional link. Links that are not part of a pair remain as unidirectional links.
Finally, as an alternative to only querying the logical links for a single network layer, the client could also query
the termination points for all layers at once. To achieve this, the client can send the following request (targeting
the network list and using the fields query parameter to select the branch of interest in the response
object):
GET https://<restconf-host>/restconf/restconf/ds/ietf-datastores:operational/ietf-
network:networks/network?fields=network-id;ietf-network-topology:link
200, OK
{
"ietf-network:network": [
{
"network-id": "avnm-network:network_l2vpn",
"ietf-network-topology:link": []
},
{
"network-id": "avnm-network:network_l3vpn",
"ietf-network-topology:link": []
},
{
"network-id": "avnm-network:network_layer1",
"ietf-network-topology:link": [
{
"link-id": "avnm-link:0:1:Radio1,0:2:Radio1",
"supporting-link": [],
"source": {
"source-node": "avnm-node:0:1",
"source-tp": "avnm-tp:Radio1",
},
"destination": {
"dest-node": "avnm-node:0:2",
"dest-tp": "avnm-tp:Radio1",
},
},
{
"link-id": "avnm-link:0:2:Radio1,0:1:Radio1",
"supporting-link": [],
"source": {
"source-node": "avnm-node:0:2",
"source-tp": "avnm-tp:Radio1",
},
"destination": {
"dest-node": "avnm-node:0:1",
Although the above example specifically deals with the discovery of the layer-1 topology links, the process
of discovering the logical topological links for other network service layers is identical in practice.
When modelling bidirectional links, the client can identify the individual unidirectional links that comprise
the bidirectional link by grouping links according to tuples consisting of their source and destination node-
id and termination port. Each directional link mirrors its counterpart by reversing the details in the source
and destination objects. Links that have the same pairs of nodes referenced in their destination and
source fields (and terminated by a common pair of termination-points are deemed to be part of the same
unidirectional link).
A client can query system connectivity to the ProVision Plus network management server using the
following request:
GET https://<restconf-host>/restconf/restconf/ds/ietf-datastores:operational/ietf-
system:system
200, OK
{
"ietf-system:system": {
"contact": "Aviat Networks",
"clock": {
"timezone": {
"timezone-utc-offset": -780
}
}
}
}
In the example above, the ‘200, OK’ success HTTP response code indicates that connectivity to the
server has been established. In addition, the client can ascertain the RESTCONF server’s internal time’s
time zone UTC-offset configuration (as an example).
YANG 1.1 RFC 7950 The YANG 1.1 Data Modelling Language
Network Topology RFC 8345 A YANG Data Model for Network Topologies
Modelling
In the tables below, the status field is used to indicate the suitability of the current revision of a YANG
module to being used for new integration work by client applications. The status is defined as:
stable – the YANG module definition is deemed stable and unlikely to change in
the near future. It can be used for new development.
subject to change – the YANG module is in a state where it may change at any point in the
future. Using this YANG module definition for development integration is
at the integrator’s own risk.
Permit
/ -- X X
/restconf-state ietf-restconf-monitoring X X
/schema-mounts ietf-yang-schema-mount X
/yang-library ietf-yang-library X
/query avnm-events X
/set-operator-state avnm-events X
/nacm ietf-netconf-acm X
/system ietf-system X
/system-state ietf-system X
Permit
{None exposed via NBI}
Permit
/managed-devices avnm-device-mount X
/query avnm-performance X
/l2vpn-svc ietf-l2vpn-svc X
/l3vpn-svc ietf-l3vpn-svc X
/networks ietf-network X
Deny
/device/device-credentials avnm-device X X X X X
Permit
/managed-devices avnm-device-mount X
/query-constraints avnm-performance X X
/metadata avnm-performance X X
/query avnm-performance X
/l2vpn-svc ietf-l2vpn-svc X
/l3vpn-svc ietf-l3vpn-svc X
/networks ietf-network X
WWW.AVIATNETWORKS.COM