ProVision Plus 2 - 4 - 0 NBI System Integration Guide - May2019

ProVision Plus
Northbound Interface System Integration Guide
Version: 2.4.0
260-668283-001
Copyright & Terms of Use
Copyright & Terms of Use

10 May 2019
This documentation incorporates features and functions provided with ProVision Plus 2.4.0.
Copyright © 2019 by Aviat Networks, Inc.

All rights reserved.
No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system,
or translated into any language or computer language, in any form or by any means, electronic,
magnetic, optical, chemical, manual, or otherwise, without the prior written permission of Aviat
Networks Inc.
To request permission, contact Aviat via [email protected]
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.
Aviat Networks 10 May 2019 iii

Contents
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
Aviat Networks 10 May 2019 v

Contents
General API Comments............................................................................................................ 41

Resource Requests .................................................................................................................. 41
Caching Support....................................................................................................................... 42
Invoking Operations (RPCs & Actions) ..................................................................................... 42
Notifications / Event Streams.................................................................................................... 42
Authentication and Authorisation .............................................................................................. 42
Chapter 6. SDN Use Case Examples ...................................................................................... 43
Retrieving Managed Network Elements .................................................................................... 43
Retrieving the Configuration of a Managed Network Element ................................................... 44
Monitoring Alarms on Services and Managed Network Elements ............................................. 46
Alarm Analysis.......................................................................................................................... 50
Retrieving Logical Termination Points ...................................................................................... 51
Retrieving Logical Topological Links......................................................................................... 54
Querying ProVision Plus System Connectivity .......................................................................... 57
Appendix A: RFC Reference List ............................................................................................ 59
Appendix B: Supported YANG Modules................................................................................. 61
Appendix C: User Account NACM Rules................................................................................ 63
vi 10 May 2019 Aviat Networks

Contents
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
• Getting started with ProVision Plus RESTCONF northbound interface
• Information on the RESTCONF NBI License
• How to access the ProVision Plus RESTCONF northbound interface
• Background information on:

o Client authentication
o Schema-mount
o YANG library
o The managed-device mount point
o NMDA datastores
o The ietf-network topology node-id
o NETCONF Access Control Model (NACM)
• Practical examples of SDN use case examples for:

o Retrieving managed network elements
o Retrieving managed network element configuration
o Retrieving logical termination points
o Retrieving topological links
o Querying system connectivity
o Monitoring the alarms on services and managed network elements
Aviat Networks 10 May 2019 vii

Contents
Additional Reading Resources

The ProVision Plus User Guide (PN 260-668271-001) describes the features and capabilities
provided by ProVision Plus through the user interface.
The ProVision Plus Installation and Administration Guide (PN 260-668272) describes the procedures
and features associated with installing and administering the product.
The ProVision Installation and Administration Guide (PN 614-330053-001) describes how to
configure ProVision which is used to provide network mediation to SNMP-based devices for ProVision
Plus.
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.
viii 10 May 2019 Aviat Networks

Chapter 2. Getting Started
This section provides information on getting started with the ProVision Plus RESTCONF NBI.
Installing and Running ProVision Plus

Please refer to the separate ‘ProVision Plus Installation and Administration Guide’ document for
instructions on installing and running the product. The document guide includes the following
information:
• System requirements, including minimum hardware, supported operating systems and web-
browsers.
• ProVision Plus server application installation procedures.
• Requesting and loading product licenses.
• Configuration of the server and networking.
• Network ports usage for establishing communication with a ProVision network mediation server
and connecting ProVision Plus client sessions.
NBI Product Module License

Access to the ProVision Plus RESTCONF northbound interface is controlled through the ProVision
Plus NBI Module Technology License. You must have the ProVision Plus NBI Module Technology
License for ProVision Plus to process RESTCONF NBI requests.
Please see the ‘License Management’ section in the ‘ProVision Plus Installation and Administration
Guide’ for a description of the available licensed product modules and how to install a new license.
Module Technology Licenses and YANG Data Model Availability

The scope of data and operations that are accessible via the ProVision Plus northbound interface is
strictly controlled through the set of ProVision Plus Module Technology Licenses that has been
enabled. It is important to note that even though ProVision Plus may make data available via the
RESTCONF NBI, it is not guaranteed to be current or useful if a valid Module Technology License
responsible for managing that data/operation has not been installed.
To determine the ProVision Plus Module Technology Licenses that are associated with a YANG
module, please refer to the list of YANG modules provided in Appendix B of this guide.
Aviat Networks 10 May 2019 9

RESTCONF Client Examples
This section provides information on some tools to allow an integrator to quickly begin experiencing
the RESTCONF northbound interface.
The tools covered in this section specifically include examples that allow the integrator to immediately
perform requests against the API providing that valid user account credentials are available. The tools
have pre-set requests defined that are set up to target the northbound interface and provide practical
examples of how to use the API for a variety of SDN-related use cases. Bear in mind that the
ProVision Plus NBI is a general-purpose API, and so it is not restricted to only being useful for just
SDN use cases.
Finally, as the RESTCONF protocol utilises HTTP, any standard HTTP-client application should be
acceptable to access the ProVision Plus NBI (provided it supports Basic Authentication).
Note that the ProVision Plus NBI Module Technology Licence must be installed in order to
use these tools with the RESTCONF NBI.
ProVision Plus Northbound Interface API Documentation

Overview
When a ProVision Plus instance is deployed it makes available an API document that describes a
series of NBI requests that comprise some common SDN use cases. As well as defining the URLs,
parameters and response formatting for each of the requests, this (Swagger-based) API document
allows the integrator to send a specific request straight from the pages of the rendered
documentation.
The rendered API documentation is accessible at the following location via a web browser:
https://<restconf-host>/doc/restconf/index.html
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.
10 10 May 2019 Aviat Networks

The restconf_api.yaml excerpt below indicates the field to modify to change the target host URL and port
used for NBI requests generated by the ProVision Plus NBI Swagger API documentation:
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
Figure 1. The ProVision Plus Northbound Interface API documentation.

Using the ProVision Plus Swagger-based API Documentation
This section describes the process of using the Swagger-based API documentation to initiate
requests against the RESTCONF NBI.
1. Using a web browser, navigate to the URL:
https://<ProVision Plus Server domain>:<port>/doc/restconf/index.html
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:
<ProVision Plus install directory>\public\doc\restconf\restconf_api.yaml
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.

3. Select a use case request by clicking on the title box (row) for the desired request (e.g. click
on the banner of the first row under ‘Query System Connectivity’, to send a request that
checks for ProVision Plus system connectivity).
The box will expand to show the full information regarding that RESTCONF request.
4. You can invoke a request against the RESTCONF NBI by clicking the ‘Try It Out’ button.
If the request has any query parameters additional text boxes will be displayed that allow you
to enter the query parameter values.
5. Click the ‘Execute’ button to send the request once you’re happy with the request parameters
values (if applicable).
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).
ProVision Plus RESTCONF NBI Postman Collection Export

Overview
ProVision Plus is also deployed with a collection of pre-set example requests that can be imported
into the Postman HTTP client. The Postman HTTP client is a tool that can be used by a system
integrator to generate example requests against the ProVision Plus northbound interface for the
purpose of experiencing the RESTCONF API and independently testing any requests.
The Postman collection contains examples that satisfy a range of common SDN use cases. These
use cases are the same set covered in the Swagger API document (discussed in the previous section
of this guide).
The user can specify their valid ProVision Plus user account credentials inside the Postman client by
setting the ‘Authorisation’ credentials in the top-level folder-properties dialog. These credentials are
used for all requests to the RESTCONF NBI. Postman has the advantage of automatically generating
the necessary headers required to successfully authenticate the user account using the Basic
Authentication scheme.
The Postman example requests collection is designed to be utilised in conjunction with an
environment configuration. The environment configuration defines a series of environment variables
which are referenced within the example requests.
The Postman Collection resources can be found at the locations in the following table.
Table 1. Postman resource file URLs.
Pre-set requests https://<restconf-host>/doc/restconf/sdn_usecases_postman_examples.json
Environment import https://<restconf-host>/doc/restconf/sdn_usecases_postman_environment.json

Developer Note:
The Postman environment file imports an environment variable RESTCONF_HOST which

specifies the URL to send Postman HTTPS requests to. The correct ProVision Plus
RESTCONF northbound interface domain should be set in the RESTCONF_HOST environment
variable so that requests are sent to the right URL. This variable can be configured using
Postman’s ‘Manage Environments’ dialog box.
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.
Figure 2. Postman HTTP client.
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.

Importing the RESTCONF NBI Request Examples into the Postman HTTP Client and
Sending 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.
1. In a web browser, navigate to:

https://<restconf-host>/doc/restconf/sdn_usecases_postman_environment.json
Save the Postman environment json to a file on your workstation. This step is browser-specific,
but for Chrome (for example), right-click the whitespace of the page, and click ‘save-as’ and save
the Postman environment file (e.g. sdn_usecases_postman_environment.json).
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}}).
2. In a web browser, navigate to:

https://<restconf-host>/doc/restconf/sdn_usecases_postman_examples.json
Save the Postman collection json to a file on your workstation. This step is browser-specific,
but say for Chrome, right-click the whitespace of the page, and click ‘save-as’ and press
enter to save the Postman environment file (e.g. sdn_usecases_postman_examples.json).
The Postman collection file defines the RESTCONF NBI requests themselves, grouped into
folders/containers for each SDN Use case.
3. Start the Postman application.

4. Import the Postman environment by:
• clicking the gear (cog) button in the top-right corner of the app
• clicking on the new entry for ‘ProVision+ RESTCONF NBI on localhost’, to edit the
variables. change the following:
Environment Name: ProVision Plus RESTCONF NBI
RESTCONF_HOST: <ProVision Plus NBI Domain>
RESTCONF_PORT: <ProVision Plus NBI Port>
NODE_ID: Set this to the node-id of a managed-device. Discover these
values from the topology tree in SDN Use case ’Retrieve
Managed Elements’.
5. Select the Postman environment (make it active) by clicking the environments dropdown-list
next to the ‘eye’ button in the top-right corner and selecting ‘ProVision Plus RESTCONF
NBI’.
6. Import the Postman request examples collection:
• click the ‘Import’ button in the top-left corner of the Postman application.
• click ‘choose files’ and select the Postman collection file

(e.g. sdn_usecases_postman_examples.json).
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.
Figure 3. Postman's settings dialog box.
8. Execute a Postman request:

• expand the collection of requests under ‘SDN Usecase Examples’ on the leftmost
side of the Postman application (under the ‘Collections’ tab).
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.
• click the ‘send’ button to send the request.
After sending the example request, the response will be shown in the Response pane of the
Postman application.

Chapter 3. Background Concepts
This section provides information on concepts where system integrator familiarity is needed for clients to
integrate with the ProVision Plus NBI. This section provides information that supplements the various
RFCs and covers aspects that are unique to the ProVision Plus RESTCONF server implementation.
Network Orchestration Architecture Overview

The ProVision Plus RESTCONF API is a northbound RESTful API that provides an interface for web
clients that can be used for many purposes, including:
• 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 Consumer Application
RESTCONF NBI
Network Domain Controller A
Network Domain Controller B
(ProVision Plus)
Network Domain A Network Domain B
Figure 4 Network orchestration architecture.
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.

The Role of the Network Services Orchestrator
RESTCONF consumer application software can integrate with the ProVision Plus network domain
controller (NDC) using the open RESTCONF northbound interface in order to manage devices within the
ProVision Plus network management domain. The NBI consumer application software sits above the
ProVision Plus NMS and uses the NDC to collect and coordinate configuration information for managed
devices, and network services across the managed network domains. The NMS therefore can build up a
complete real-time picture of the aggregated information on device and service telemetry, alarm
information and network events. This information can therefore be used for a variety of software defined
networking (SDN) use cases, such as the automated profiling of network traffic and automated
reconfiguration and provisioning of additional network services/capacity as necessary. The orchestrator
can also use this information for device/service fault reconciliation and Service Level Agreement (SLA)
reporting purposes.
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.

The resources that are exposed by RESTCONF consist of YANG modules that model the network
topology at all logical layers (and their hierarchy), individual network services, configuration of managed
network elements, alarms and other elements necessary for network management. Additional simplified
interface (additional to NETCONF) that follows REST-like principles and is compatible with a resource-
oriented device abstraction (configuration and state instance data).
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.
RESTCONF also incorporates mechanisms to access individual elements of a collection of resources by

specifying a list key, composite list key support and filtering responses to provide optimised, minimal
payload selection.
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.
The key tenets of the RESTCONF protocol:

• Extensible, stateless, secure, resource-oriented request protocol based on HTTP
• Simpler than NETCONF
• Cacheable responses
• Light weight
• Human-readable
• Closely follows the capabilities of the NETCONF protocol.
For more information on the RESTCONF protocol please see the RESTCONF standard, RFC 8040.
Schema-Mount and the RESTCONF NBI

The ProVision Plus network management server implements YANG schema-mount RFC 8528.
Schema-mount provides a mechanism that allows a set of YANG modules to be ‘mounted’ beneath
other YANG modules (in a similar fashion to how individual disk partitions are mounted within a Unix
filesystem).
Mount points are defined using an extension to the YANG standard that is added by the schema
mount RFC. RESTCONF servers utilising schema-mount advertise a series of mount-points at which
other YANGS are mounted. By querying the YANG library at a given mount point, an NBI client can
discover the YANG modules that can exist at that mount point and construct requests for module
instance data that exists below the mount point.
This mechanism is necessary to allow multiple copies of YANG instance data to co-exist on a network
management server. Without it, all YANG modules are effectively ‘mounted’ at the top-level of the
instance data tree and copies from disparate devices would conflict with each other.

The ProVision Plus NBI uses the schema-mount mechanism to allow device-specific YANG instance
data for individual managed-devices to be represented within an overall list. List elements exist for
each managed-device known to the system, with the ‘managed-device’ mount-point added as a child
of the list. Under this mount-point instances of the device-specific YANGs are mounted so they do
not conflict with each other. Specific to ProVision Plus, the avnm-device-mount YANG module
defines this structure as follows in the excerpt below.
module: avnm-device-mount
+--rw managed-devices
+--rw managed-device* [managed-device-id]
+--rw managed-device-id nw:node-id
+--rw name? string
+--rw admin-state? avnm-types:admin-state
+--ro oper-state? avnm-types:oper-state
** managed-device mount point **
For more information on schema-mount please see RFC 8528.
Types of YANG modules

As with any RESTCONF server implementation, the hierarchy of YANG modules almost exclusively
defines the endpoints and data schema through which all NBI requests are conducted. These YANG
modules form the API contract with the RESCONF client.
Broadly, the YANG modules that are exposed and define the RESTCONF NBI can be divided into
three main types:
• Network topology modules
• Service modules
• Device modules
Table 2. YANG Module types.
YANG Module Type Description Module Example

Network Topology Modules used to describe and discover the ietf-networks
topology graph at each layer of the network ietf-network-topology
in terms of network nodes, links and link ietf-te-topology
termination points.
Service Modules describing the traits of a given ietf-l2vpn-svc
instance of a network service type. ietf-l3vpn-svc
Parameters described by these models do
not relate to the topology, but instead relate
to representing the parameters of an
instance of a service.
Device Modules pertaining to the context of a single ietf-system
device instance. ietf-hardware
The ProVision Plus RESTCONF ietf-interfaces
implementation supports schema-mount,
thus allowing multiple instances of these
models to exist concurrently at the same
level in the schema hierarchy. See the
schema-mount section below.

Obtaining the ProVision Plus YANG Modules
The Provision Plus server makes a copy of the externally visible YANG modules that it uses for all
NBI access available to RESTCONF clients to download so that the client can parse the schema of
the northbound interface models.
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
The ProVision Plus YANG Library Implementation

The YANG library provides a mechanism for RESTCONF clients to discover information about the
modules, datastores and schemas that are used by a network management server. ProVision Plus
implements RFC 8525 for its YANG library schema. This newer version is necessary to support
Network Management Datastore Architecture (NMDA) datastores and schema-mount.
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.

A client can query both the top-level (root) YANG library instance (to discover the modules available
at the top-level ‘/data’ endpoint), and, the YANG library at the schema-mount mount-point level (to
discover the YANG modules that are exposed below the managed-device mount-point). The latter of
these two YANG library instances dictates the schema that models an individual managed-device.
Note: Event notifications are not currently supported by the ProVision Plus RESTCONF NBI.
For more information on the YANG library please see RFC 8525.
Network Management Datastore Architecture (NMDA) and Datastores

ProVision Plus implements RFC 8342, the Network Management Datastore Architecture (NMDA).
This standard defines individual datastores which can be used to model ‘snapshots’ of configuration
and state data representing services and managed elements within the network domain.
ProVision Plus models its network domain through two independent NMDA-datastores. These are
the ‘running’ and ‘operational’ datastores respectively.
The running datastore represents ‘design-time’ service and managed element configuration values
that are initially configured by a user (or network application). This view of the network maps to the
concept of the ‘baseline’ view within the ProVision Plus user interface. As the running datastore
represents a design-time view of the network, it only contains configuration data; not non-
configuration (state) data.
The operational datastore represents state and configuration data modelling the “last-known”
configuration and state of managed elements and services (i.e. after network changes have
converged). As the operational datastore represents most-recently discovered information, it contains
both configuration data and non-configuration (state) data and maps to the “live” view of the network
domain within the ProVision Plus user interface.
Although each datastore’s data represents a different view of the network domain, both datastores
use the same set of YANG modules (same schema) to model their data.
The table below summarises the mapping between the ProVision Plus graphical user interface
domain view, and its associated NMDA datastore.:
Table 3. ProVision Plus network view mapping to NMDA Datastores.
ProVision Plus View NMDA Datastore Description

baseline ietf-datastores:running Represents the network configuration at design-time.
Contains purely configuration data (no non-config).
live ietf-datastores:operational Represents the most-recently discovered

configuration and state data of the services and
managed network elements. Contains configuration
and non-configuration (state) data.
For more information on NMDA please read ‘Network Management Datastore Architecture (NMDA)’
RFC 8342.

Client Authentication
The ProVision Plus network management server NBI must authenticate every client request that it
receives. RESTCONF in general supports Basic Authentication, RFC 7617 (over an HTTPS
connection) as a minimum but allows for support for additional authentication mechanisms to be
added.
The ProVision Plus NBI currently only supports the basic authentication mechanism. Additional
schemes may be supported in future.
NETCONF Access Control Model (NACM)

The NETCONF Access Control Model (NACM) permissions mechanism defines a way for network
management servers to define and implement security and permissions models for policing access
to resources exposed via the RESTCONF NBI. This permissions model is defined in the standard
RFC 8341.
Core to NACM is the convention of defined user account groups (roles) that are assigned to user
accounts. These user account roles are used to group sets of rules that govern the levels of access
to resources made available by a network management protocol such as NETCONF or RESTCONF.
Conceptually, the entire NMS datastore schema made accessible via the RESTCONF NBI can be
modelled as a tree with multiple root nodes. The top-level lists, containers, and operations of the
YANG modules that are mounted at the top-level of the hierarchy make up the set of root nodes of
the tree. The children of these top-level nodes then reside at the next level down the tree and so on.
In the interests of addressing nodes within this tree structure, RFC 8040 specifies how to construct a
canonical request URL that can access a given data node within the schema. These canonical URLs,
or paths, uniquely identify a given schema node within the schema tree. In the same fashion, the
paths can be used to address the instance data resources exposed by the network management
protocol.
Access to resources within the NBI datastore via ProVision Plus is controlled through a series of rules
that target a schema node (and its descendants). Rules are grouped and applied according to their
parent rule-list’s group (the set of roles the rule-list applies to). Each rule of a rule-list specifies the
path to the schema node of interest, a permit/deny action and what protocol operations the
permit/deny action applies to.
Finally, the NACM rules that are implemented by a network management server are themselves
discoverable using the network management protocol itself. The rules are essentially resources and
their schema are defined in the ietf-netconf-acm YANG module. A client can query the root-level
ietf-netconf-acm:nacm resource and discover the ruleset for a given network management
server.

Chapter 4. Accessing the ProVision Plus NBI
This section describes the steps a developer should take to access the ProVision Plus RESTCONF NBI.
Verify the ProVision Plus Server is Running

You can check the ProVision Plus server instance is running by navigating to the following URL in a
web browser:
https://<restconf-host>/login
If the server is running, you will see the ProVision Plus login page. If no login page is shown, consult
the ProVision Plus user guide for information on diagnosing any issues.
Accessing the RESTCONF NBI

Once the ProVision Plus server is running (and assuming the instance has NBI access activated in
the server license), you can use an HTTP client such as curl, wget or Postman to access the API
endpoints.
The RESTCONF RFC (RFC 8040) mandates that all NBI access occurs over HTTPS. By default, the
ProVision Plus RESTCONF NBI is accessible on the default HTTPS port, 443.
The RESTCONF NBI port is made configurable for deployment cases where port 443 is not free for
use. Please refer to the ProVision Plus Installation and Administration Guide (PN 260-668272) for
information on reconfiguring the RESTCONF northbound interface’s assigned HTTPS port. Ensure
that any examples from this document are altered to use the correct port assignment for your
deployed configuration.
API Entry Point Discovery

An NBI client can request the well-known host meta data endpoint to discover the RESTCONF API
entry points supported by the NBI as follows
https://<restconf-host>/.well-known/host-meta
Below is an example host-meta request & response:
GET https://127.0.0.1/.well-known/host-meta
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"
}
]
}

The response to the .well-known/host-meta request contains a list of RESTCONF API entry
points. The links list contains an entry for every supported version of the RESTCONF API with a
rel attribute suffixed with the API version number. In addition to the versioned list entries, there is
also an entry that specifies the default entry point to use for clients that are agnostic to the API version.
Specifically, the default entry point URL omits the version identifier in the URL.
A client can follow the URL specified in a link’s href field to reach the root end point of the
RESTCONF API.
For more information on using the .well-known/host-meta endpoint, please read the ‘Web Host
Metadata RFC’ (RFC 6415).
Root API Resource Retrieval

All RESTCONF NBI requests (except for the .well-known/host-meta endpoint) require that the
client provide its identity by authenticating with the server for every request. The ProVision Plus NBI
supports Basic Authentication over HTTPS (see RFC 7617) and therefore the client must provide an
authorization header derived from valid user account credentials to authenticate successfully.
The authorization header is composed of the user’s credentials (username and password separated
by a colon and encoded using Base64) prepended with the string "Basic: ". Note for NBI access
the user account’s email is used as the value for the login username field.
As an example, say a client wished to authenticate using the credentials below:

Username: alice
Password: quickBrownFox123
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.

Discovering the RESTCONF Server YANG library
As the ProVision Plus network management server’s NBI data structure is inherently described by
the set of implemented YANG modules, a RESTCONF client should discover the set of YANG
libraries that define the NBI data schema. As discussed in Section 3 of this document, the ProVision
Plus NBI implements RFC 8525 for its YANG library. The RESTCONF client can query the following
URL to retrieve the top-most (root) level of the YANG library.
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": [
{
"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"
}
}

Discovering the RESTCONF Server Capabilities
Another important NBI endpoint that a RESTCONF client should query is the RESTCONF server’s
capabilities list. This resource specifies the non-mandatory elements of RFC 8040 that are currently
supported by ProVision Plus. A client can use this resource to check for and confirm that the
RESTCONF server can understand the optional parts of the RESTCONF protocol (for instance
certain query parameters and whether the network management server supports event notifications).
All optional capabilities that the RESTCONF server can support are designated their own capability
URI. By checking the server’s ietf-restconf-monitoring:restconf-state resource, the
server’s capabilities can be discovered.
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.

Accessing the Supported NMDA Datastores via RESTCONF
Chapter 3 of this guide covers the concept of the NMDA datastore (as defined in RFC 8342) and how each
datastore maps to a view of the network domain provided by ProVision Plus. The mapping of user interface
view (baseline/live) to datastore is summarised again in the table from Chapter 3Chapter 4 here for
reference.
Table 4. ProVision Plus network view mapping to NMDA Datastores (recreated from Table 3).
ProVision Plus View NMDA Datastore mapping Description

baseline ietf-datastores:running Represents the network configuration at design-time.
Contains purely configuration data (no non-config).
live ietf-datastores:operational Represents the most-recently discovered configuration

and state data of the services and managed network
elements. Contains configuration and non-configuration
(state) data.
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:
Baseline view (<running> datastore)

GET https://<restconf-host>/restconf/restconf/ds/ietf-datastores:running/avnm-
device-mount:managed-devices/managed-device=<device-id>/ietf-hardware:hardware
200, OK
{
"ietf-hardware:hardware": {
"last-change": "2019-02-25T13:40:03+00:00",
"component": [
{
"name": "Carrier1/1",
"class": "ianaent:container",
"description": "Radio Carrier",
"parent": "RFModule1/1",
"parent-rel-pos": 1,
"is-fru": "false",
"contains-child": [ ... ],
"uri": [],
"state": {
"state-last-changed": "2019-02-25T13:39:28+00:00",
"admin-state": "unlocked",
"oper-state": "enabled",
"usage-state": "active",
"alarm-state": "indeterminate",
"standby-state": "providing-service"
},
},
...
]
}
}
Live view (<operational> datastore)

GET https://<restconf-host>/restconf/restconf/ds/ietf-datastores:operational/avnm-
device-mount:managed-devices/managed-device=<device-id>/ietf-hardware:hardware
200, OK
{
"last-change": "2019-02-25T13:40:03+00:00",
"component": [
{
"name": "Carrier1/1",
"class": "ianaent:container",
"description": "Radio Carrier",
"parent": "RFModule1/1",
"is-fru": "false",
"contains-child": ["BEREstimation1/1", "RSL1/1", "RemoteFadeMargin1/1",
"RemoteRSL1/1", "RemoteSNR1/1", "SNR1/1", "XPD1/1"],
"uri": [],
"state": {
}
},
...
]
}
}

NETCONF Access Control Model (NACM) permissions
The ProVision Plus network management server implements the security and permissions models
defined in the NETCONF Access Control Model (NACM) standard for policing access to resources
exposed via the RESTCONF NBI.
ProVision Plus defines user account roles that can be assigned to each user account. These user
account roles are engineer & operator. The user account roles are not mutually exclusive, and a
given user account may be assigned zero or more roles as necessary.
The ProVision Plus NBI implements equivalent role-based access control to that permitted by the
user interface and a subset of the functionality that the user interface provides. The table below
describes the capabilities afforded to user accounts with the following roles:
Table 5. User account roles.
Role Brief Description

Network Operator Provides read-only access to all network topology and configuration data including
the configuration details of devices and services, together with full access to all
event/alarm and configuration views to support proactive network health analysis and
troubleshooting.
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.
Each rule of a rule-list specifies the following:

Table 6. Rule properties.
name Arbitrary name assigned to rule.
action Access control action associated with the rule (permit/deny).
comment Textual description of the access rule.
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.

access-operations Access operations associated with this rule. The type associated with this field is
a MSb-first ordered bit-field (5 bits) corresponding to the possible NACM access-
operations types defined in the order of:
create (bit-4), read, update, delete, execute (bit-0)
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.
Policing YANG Data Availability by Technology Module Licenses

In addition to implementing rules defined by the NETCONF Access Control Model for policing access to resources
on the RESTCONF server, ProVision Plus also controls access to NBI instance data resources through policing
access to its Product modules (based on Technology Module License).
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.

Network Topology Discovery
RESTCONF clients can use the ProVision Plus NBI to discover the overall network topology (nodes, links
and termination points) of the network being managed. The topology graph (modelled by the ietf-
networks YANG) presents a hierarchy of layered network graphs that effectively represent individual
cross-sections of the overall network topology as seen at a given layer (physical, layer-1, SyncE, VLAN,
pseudowire, tunnel, VPN etc).
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 graph nodes: one for each respective managed device.
• 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:
• a ‘supporting nodes’ list for each node
• a ‘supporting links’ list for each link
• a ‘supporting termination-points’ list for each termination point
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):

GET https://<restconf-host>/restconf/restconf/ds/ietf-datastores:operational/ietf-
network:networks
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": []
}
]
},
{
"supporting-node": [],
{
"tp-id": "avnm-tp:GigabitEthernet0/1",
}
]
}
],
"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.

The Managed-device Mount Point
The ProVision Plus NBI features a special YANG module that is presented at the root of the YANG schema
hierarchy, whose function is to provide a point in the hierarchy where multiple instances of the same
device-specific data models can be present. The avnm-device-mount YANG module contains the
‘managed-device’ mount point that achieves this function. The module contains a list whose entries
correspond to the physical managed-devices that are deployed within the physical layer-1 network
topology. The node-id in the topology layer has the same value as that of the managed-device-id
field. For each device, multiple YANG schemas are used to define the configuration and non-configuration
data as reported by the device. In the same fashion YANG operations (RPCs and actions) can also be
defined underneath this mount point, allowing those operations to be executed by an NBI client with a
specific managed-device as the context of the operation.
The core elements of the avnm-device-mount YANG are presented below:
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.

Also, within the managed-device list above, is an extension (yangmnt:mount-point) defined in the
schema-mount standard (RFC 8528), that specifies a mount point within the YANG hierarchy. Using the
mount-points label ‘device-yang-root’ the NBI client can query the YANG library to determine the
schema for a specific instance at the mount point by performing the following request, and passing in the
managed-device-id value as the node-id:
GET https://<restconf-host>/restconf/restconf/ds/ietf-
datastores:operational/avnm-device-mount:managed-devices/managed-
device=<managed-device-id>/ietf-yang-library:yang-library
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.
datastores:operational/avnm-device-mount:managed-devices/managed-device=avnm-
node:0:1/ietf-hardware:hardware
200, OK
{
"last-change": "2019-02-28T15:05:45+00:00",
{
"name": "GigabitEthernet1/1",
"class": "ianaent:port",
"description": "GigabitEthernetPort 1",
"parent": "Terminal1",
"is-fru": "false",
"contains-child": [],
"uri": [],
"state": {
},
"sensor-data": { ... }
},
...
]
}
}

Managed-device Mounted YANG Modules
As covered in the previous section, the managed-device mount point in the avnm-device-mount.yang
is used as anchor point for mounting YANG module instance data schema that pertain to an individual
managed device. This section lists the YANG modules that are implemented for a device instance below
the ‘managed-device’ mount point. Please note that this list can also be discovered programmatically by
a RESTCONF client at runtime by querying the mount-point YANG library, i.e.
datastores:operational/avnm-device-mount:managed-devices/managed-
device={node-id}/ietf-yang-library:yang-library
Below is a list of the core YANG modules that can be queried at the mount-point, organised by author.
IETF YANG modules:
• ietf-hardware
• ietf-interfaces
• ietf-system
Aviat Networks proprietary YANG modules:
• avnm-device

Chapter 5. ProVision Plus NBI Details
This section describes some of the implementation details specific to the ProVision Plus RESTCONF
NBI. The section consists of a list of considerations that system integration engineers should review
when integrating with the ProVision Plus RESTCONF NBI. The section also describes some areas
where the RESTCONF NBI implementation deviates from (or omits a non-mandatory part of) the
complete specification defined in RFC 8040.
General API Comments

1. All RESTCONF access requires the ‘NBI’ license module to be activated within ProVision Plus.
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
5. Client-originated request URLs should use URL-escaping where necessary.
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).
3. The ‘content’ query parameter IS SUPPORTED
4. The ‘depth’ query parameter IS SUPPORTED
5. The ‘fields’ query parameter IS SUPPORTED
6. The ‘with-defaults’ query parameter IS NOT SUPPORTED.
7. The ‘insert’ query parameter IS NOT SUPPORTED.
8. The ‘point’ query parameter IS NOT SUPPORTED.
9. The ProVision Plus NBI’s default’s handling mode is ‘explicit’.
10. Datastore ‘last-modified’ timestamps are not currently supported.
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.

Caching Support
1. Currently the ProVision Plus network management server does not implement caching of NBI
responses. At present, all NBI responses return a cache-control header value of:
'no-store, no-cache, must-revalidate, proxy-revalidate'
2. In addition, the ProVision Plus NBI does not currently support the "If-None-Match" or "If-
Modified-Since" headers.
Invoking Operations (RPCs & Actions)

1. Operations are queued by the ProVision Plus network management server. This means that a request
can timeout before it completes.
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.
Notifications / Event Streams

1. The ProVision Plus RESTCONF NBI does not currently support notifications or event streams.
2. The ‘filter’ query parameter IS NOT SUPPORTED.
3. The ‘start-time’ query parameter IS NOT SUPPORTED.
4. The ‘stop-time’ query parameter IS NOT SUPPORTED.
Authentication and Authorisation

1. The ProVision Plus RESTCONF NBI only supports the Basic Authentication scheme. The NBI may
support other authentication mechanisms in future.
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.

Chapter 6. SDN Use Case Examples
This chapter addresses how the supported ProVision Plus RESTCONF NBI endpoints can be used to
satisfy the common SDN use cases identified below:
• retrieving managed network elements

• retrieving the configuration of a managed network element
• monitoring the alarms on the managed network elements (and alarm analysis)
• retrieving topology logical termination points
• retrieving topology logical topological links
• querying ProVision Plus system connectivity
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.
Retrieving Managed Network Elements

The process of retrieving instance data for managed network elements involves discovering the node IDs
of the network elements that are present, determining the YANG modules that are available for the
managed device nodes and then querying the instance data of the device-specific modules.
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:
network:networks/network=avnm-network:network_layer1?fields=network-id;node(node-
id)
200, OK
{
"ietf-network:network": [
{
"node": [
{
"node-id": "avnm-node:0:1"
},
{
"node-id": "avnm-node:0:2"
}
]
}
]
}

The response above contains a list of the node-ids for the topology nodes residing in topology layer-1.
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
GET https://<restconf-host>/restconf/restconf/ ds/ietf-datastores:operational/avnm-

device-mount:managed-devices/managed-device={node-id}/ietf-
system:system?fields=contact
Retrieving the Configuration of a Managed Network Element

The process of discovering the configuration of a manged network element involves querying the ietf-
hardware and ietf-interfaces model instances for a managed network element. These models are
made available as mounted modules beneath the avnm-managed-device mount point via the schema-
mount mechanism. Please see Chapter 3 for information on schema-mount.
The example requests below retrieves the configuration of a network node:
Querying hardware components:

device-mount:managed-devices/managed-device={node-id}/ietf-hardware:hardware
200, OK
{
"last-change": "2018-04-29T05:03:42.945Z",
"component": [
{
"name": "CTR8540 1",
"class": "ianaent:chassis",
"description": "CTR8540 Chassis",
"parent": 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,
"is-fru": "true"
},
...
{
"name": "RAC3",
"class": "ianaent:module",
"description": "RACx1 plug in module",
"parent": 335544320,
"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.
Querying managed element network interfaces:

device-mount:managed-devices/managed-device={node-id}/ietf-interfaces:interfaces
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",
"type": 6,
"if-index": 10,
"phys-address": "'00:E0:E2:95:20:8B'",
"speed": 1000000000
},
...
{
"name": "Slot0/11",
"type": 6,
"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.
Monitoring Alarms on Services and Managed Network Elements

The process of monitoring the alarms on services and managed network elements involves initially
retrieving the active alarms as a snapshot together with periodically polling the changes in the alarms.
This mechanism allows the discovery of changes in the alarms or any new alarms that have been raised.
Alarms can be filtered by passing a filter object as the request body, allowing for the client to query for
alarms since a given point in time). The example requests in this section detail the processes of retrieving
alarms for services and managed network elements.
Performing a ‘sync’ to retrieve all active alarms.
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",

"resource-text": "ProVision",
"event-id": "pv:256304",
"event-type": "security-service-or-mechanism-violation",
"event-text": "Failed to Authenticate ProVision Plus NBI",
"event-type-id": "platform-mplsManageAuthenticationFailure",
"probable-cause-string": "ProVision Plus NBI credentials are incorrect.",
"severity": "warning",
"is-active": false,
"time-raised": "2019-02-08T06:23:52.859Z",
"time-cleared": "2019-02-08T06:23:55.878Z",
"time-source": "system",
"operator-state": {
"ack-state": false
}
},
{
"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-02-08T07:01:32.292Z",
"operator-state": {
"ack-state": false
}
},
... <list contents omitted for brevity>
]
}
}
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 2:
POST https://<restconf-host>/restconf/restconf/ds/ietf-datastores:operational/avnm-
events:query
Request Payload:
{
"time-raised": "2019-02-08T07:01:32.292Z "
}
}
Response:
200, OK
{
"event": [
{
"event-id": 181087,
"event-text": "Severely Error Seconds (SES) Ratio Threshold Exceeded",
"event-type-id": "g826-severely-errored-seconds-ratio:Radio1",
"probable-cause-string": "Signal degraded",
"is-active": true,
"time-raised": "2019-05-03T05:01:32.292Z",
"operator-state": {
"ack-state": false
}
},
{
"event-id": 181088,
"event-text": "Ethernet port link down",
"event-type-id": "ethernet-port-link-down:Radio1",
"probable-cause-string": "Loss of signal on interface.",
"is-active": true,
"time-raised": "2019-05-03T05:01:32.293Z",
"operator-state": {
"ack-state": false
}
},
...
]
}
}
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.

Alarm Analysis
An SDN controller dashboard could conceivably include a stacked bar chart showing the counts of ‘active’
raised alarms that are outstanding, on a per-day basis. This intention being to illustrate the historical
stability of the entire network controller domain over a period of the last few days (in terms of the number
of uncleared alarms for each type). The figure below shows a hypothetical example of this ‘dashboard’
alarm view.
Figure 5 Recent alarm history summary dashboard chart.
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.
The request below shows an example of the request.
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:
{
"state": "not-cleared",
"time-raised": {
"start-time": "2019-03-01T00:00:00.000Z"
}
}
}

Response:
{
"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.
Retrieving Logical Termination Points

The process of discovering the network topology logical termination points involves querying the
termination points of the nodes within a given network layer. The example below illustrates a request for
the layer-1 termination points of a simple example topology consisting of two connected nodes.
datastores:operational/ietf-network:networks/network=avnm-
network:network_layer1/node?fields=node-id;ietf-network-topology:termination-
point
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
The full request and response are given below:

GET https://<restconf-host>/restconf/restconf/ ds/ietf-datastores:operational/ietf-
network:networks/network=avnm-network:network_layer1/node?fields=node-id;ietf-
network-topology:termination-point(tp-id;supporting-termination-point)
200, OK
{
"ietf-network:node": [
{

{
"tp-id": "avnm-tp:Radio1",
}
]
},
{
{
}
]
}
]
}
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):
network:networks/network?fields=network-id;node(node-id;ietf-network-
topology:termination-point)
200, OK
{
{
"network-id": "avnm-network:network_l2vpn",
"node": []
},
{
"node": []
},
{
"node": [
{
{
}
]
},
{
{
}
]
}
]
},
{
"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.

Retrieving Logical Topological Links
The process of discovering the network topology links of a given network layer involves a similar series of
steps described in the above section ‘Retrieving Logical Termination Points’. Specifically, the client can
select a layer of interest and query the topology links that comprise that network layer. The example below
illustrates a request for the layer-1 topological links for a simple, example topology of two connected nodes.
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)
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
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
{
{
{
"link-id": "avnm-link:0:1:Radio1,0:2:Radio1",
"source": {
"source-tp": "avnm-tp:Radio1",
},
"destination": {
"dest-tp": "avnm-tp:Radio1",
}
},
{
"source": {
},
"destination": {
}
}
]
}
]
}

As the example RESTCONF response object shows, layer-1 contains two unidirectional links terminating at a
pair of termination points:
• Termination point “avnm-tp:Radio1” on node with ID “avnm-node:0:1”, and
• Termination point “avnm-tp:Radio1” on node with ID “avnm-node:0:2”
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):
network:networks/network?fields=network-id;ietf-network-topology:link
200, OK
{
{
"ietf-network-topology:link": []
},
{
},
{
{
"source": {
},
"destination": {
},
},
{
"source": {
},
"destination": {

},
}
]
},
{
"network-id": "avnm-network:network_ptp",
},
{
"network-id": "avnm-network:network_pw",
},
{
"network-id": "avnm-network:network_synce",
},
{
"network-id": "avnm-network:network_te_link",
},
{
"network-id": "avnm-network:network_te_tunnel",
},
{
"network-id": "avnm-network:network_vlan",
},
{
"network-id": "avnm-network:network_vlan_link",
},
{
"network-id": "avnm-network:network_vrf",
}
]
}
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.
Modelling Bidirectional Links
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).

Querying ProVision Plus System Connectivity
Checking for system connectivity involves simply checking for a valid response from an arbitrary
RESTCONF NBI endpoint. Any endpoint can be used in this manner, but a typical example is the ietf-
system YANG module’s system top-level container. This module reports information about the network
management server (or, in the case of querying these modules for a managed device; provides information
about the managed device).
A client can query system connectivity to the ProVision Plus network management server using the
following request:
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).

RFC Reference List
Appendix A: RFC Reference List

This section includes a list of RFC documents that provide good background reading on RESTCONF
and its affiliated standards as implemented by ProVision Plus network management server. The
RFCs are grouped according to functional domain.
Table 7. RFC Reference list.

Domain RFC Designation Document Title
RESTCONF RFC 8040 RESTCONF Protocol
YANG 1.1 RFC 7950 The YANG 1.1 Data Modelling Language
RFC 7951 JSON Encoding of Data Modelled with YANG
Schema-mount RFC 8528 YANG Schema mount
YANG library RFC 8525 YANG Library
NMDA RFC 8342 Network Management Datastore Architecture (NMDA)
RESTCONF Extensions to support the Network

RFC 8527 Management Datastore Architecture
NACM RFC 8341 Network Configuration Access Control Model
Basic RFC 7617 The ‘Basic’ HTTP Authentication Scheme

Authentication
Server Metadata RFC 6415 Web Host Metadata
Network Topology RFC 8345 A YANG Data Model for Network Topologies
Modelling

Supported YANG Modules
Appendix B: Supported YANG Modules

This section includes a list of the supported YANG modules (and their revisions) for the current
release of the ProVision Plus RESTCONF northbound interface. In addition, the Module Technology
Licenses required to access data for each module is given. The list is split based on module scope
(whether it be device-centric, service-topology-centric or general purpose).
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.
Table 8. Service Topology Modules.

Service Topology Modules
Module Revision Status Module Technology Licence
avnm-l2vpn-topology 17/01/2019 subject to change IP/MPLS Fault
avnm-l3vpn-topology 17/01/2019 subject to change IP/MPLS Fault
avnm-lsp-link-topology 17/01/2019 subject to change IP/MPLS Fault
avnm-lsp-topology 17/01/2019 subject to change IP/MPLS Fault
avnm-network-topology 1/05/2019 stable
avnm-physical-topology 30/01/2019 stable
avnm-ptp-link-topology 12/02/2019 subject to change CE Fault & Performance
avnm-pw-topology 17/01/2019 subject to change IP/MPLS Fault
avnm-rt-link-topology 17/01/2019 subject to change IP/MPLS Fault
avnm-synce-link-topology 12/02/2019 subject to change CE Fault & Performance
avnm-te-link-topology 17/01/2019 subject to change IP/MPLS Fault
avnm-te-tunnel-topology 17/01/2019 subject to change IP/MPLS Fault
avnm-topology 30/01/2019 stable
avnm-vlan-link-topology 30/01/2019 subject to change CE Fault & Performance
avnm-vlan-topology 30/01/2019 subject to change CE Fault & Performance
ietf-l2vpn-svc 9/10/2018 stable IP/MPLS Fault
ietf-l3vpn-svc 19/01/2018 stable IP/MPLS Fault
ietf-network 26/02/2018 stable
ietf-network-topology 26/02/2018 stable
ietf-te-topology 5/06/2016 subject to change IP/MPLS Fault

Contents
Table 9. Device Modules.

Device Modules
avnm-device 7/02/2019 stable
avnm-microwave-radio-link 30/01/2019 stable
avnm-physical-device 7/02/2019 stable
iana-hardware 13/03/2018 stable
ietf-alarms 22/11/2018 stable
ietf-alarms-x733 22/11/2018 stable
ietf-hardware 13/03/2018 stable
ietf-interface-protection 28/11/2018 stable
ietf-interfaces 20/02/2018 stable
ietf-ip 22/02/2018 stable
ietf-microwave-radio-link 28/11/2018 stable
ietf-system 6/08/2014 stable
Table 10. Other Modules.

Other Modules
avnm-device-mount 1/11/2018 stable
avnm-events 22/02/2019 stable
avnm-performance 12/12/2018 subject to change
avnm-types 28/09/2018 stable
iana-if-type 19/01/2017 stable
ietf-datastores 14/02/2018 stable
ietf-inet-types 11/03/2019 stable
ietf-interfaces-common 5/03/2019 stable
ietf-microwave-types 28/11/2018 stable
ietf-netconf-acm 14/02/2018 stable
ietf-restconf 26/01/2017 stable
ietf-restconf-monitoring 26/01/2017 stable
ietf-routing-types 4/12/2017 stable
ietf-te-mpls-types 20/03/2016 subject to change IP/MPLS Fault
ietf-te-types 20/03/2016 subject to change IP/MPLS Fault
ietf-yang-library 4/01/2019 stable
ietf-yang-schema-mount 14/01/2019 stable
ietf-yang-types 11/03/2019 stable

User Account NACM Rules
Appendix C: User Account NACM Rules

This section provides a list of the NACM rules that are provisioned for a given user account role. This
table is presented here for reference in conjunction with this guide, and reflects the rules enforced by
ProVision Plus when allowing client applications access to its northbound interface via RESTCONF.
These rules are also defined and can be discovered directly from the ProVision Plus RESTCONF NBI
itself by requesting the ietf-netconf-acm:nacm resource at the root-level of the datastore.
Note, as discussed in Chapter 4, NACM rules for a YANG data node are inherited from the node’s
ancestors. This means that if a rule is not defined for a node specifically, it may be allowed by virtue
of its ancestor node. If no rules provide coverage of a specific data node then access is denied by
default. Finally, rules are applied in an ‘upward direction’, meaning that if a node has a deny rule
applied to it, then even if an ancestor would normally permit access; access is actually denied based
on the more-specific rule that applies to the node itself.
Table 11. NACM rules – all user accounts.

Role: All (*)
Resource Path Resource Permissions
(Module XPath expression) Module
CREATE READ UPDATE DELETE EXECUTE
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
Table 12. NACM rules – role ‘admin’.

Role: admin
Permit
{None exposed via NBI}

Contents
Table 13. NACM rules – role ‘operator’.

Role: operator
Permit
/managed-devices avnm-device-mount X
/query avnm-performance X
/l2vpn-svc ietf-l2vpn-svc X
/networks ietf-network X
Deny
/device/device-credentials avnm-device X X X X X
Table 14. NACM rules – role ‘engineer’.

Role: engineer
Permit
/managed-devices avnm-device-mount X
/query-constraints avnm-performance X X
/metadata avnm-performance X X
/query avnm-performance X
/networks ietf-network X

260-668283-001
WWW.AVIATNETWORKS.COM

ProVision Plus 2 - 4 - 0 NBI System Integration Guide - May2019

Uploaded by

Copyright:

Available Formats

ProVision Plus 2 - 4 - 0 NBI System Integration Guide - May2019

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ProVision Plus 2 - 4 - 0 NBI System Integration Guide - May2019

Uploaded by

Copyright:

Available Formats

ProVision Plus

Northbound Interface System Integration Guide

Copyright & Terms of Use

Copyright © 2019 by Aviat Networks, Inc.

Aviat Networks 10 May 2019 iii

Aviat Networks 10 May 2019 v

General API Comments............................................................................................................ 41

vi 10 May 2019 Aviat Networks

• Getting started with ProVision Plus RESTCONF northbound interface

• Information on the RESTCONF NBI License

• How to access the ProVision Plus RESTCONF northbound interface

• Background information on:

• Practical examples of SDN use case examples for:

Aviat Networks 10 May 2019 vii

Additional Reading Resources

viii 10 May 2019 Aviat Networks

Installing and Running ProVision Plus

NBI Product Module License

Module Technology Licenses and YANG Data Model Availability

Aviat Networks 10 May 2019 9

ProVision Plus Northbound Interface API Documentation

10 10 May 2019 Aviat Networks

Figure 1. The ProVision Plus Northbound Interface API documentation.

Aviat Networks 10 May 2019 11

<ProVision Plus install directory>\public\doc\restconf\restconf_api.yaml

12 10 May 2019 Aviat Networks

ProVision Plus RESTCONF NBI Postman Collection Export

Pre-set requests https://<restconf-host>/doc/restconf/sdn_usecases_postman_examples.json

Environment import https://<restconf-host>/doc/restconf/sdn_usecases_postman_environment.json

Aviat Networks 10 May 2019 13

The Postman environment file imports an environment variable RESTCONF_HOST which

Figure 2. Postman HTTP client.

14 10 May 2019 Aviat Networks

1. In a web browser, navigate to:

2. In a web browser, navigate to:

3. Start the Postman application.

6. Import the Postman request examples collection:

• click ‘choose files’ and select the Postman collection file

Figure 3. Postman's settings dialog box.

8. Execute a Postman request:

• click the ‘send’ button to send the request.

16 10 May 2019 Aviat Networks

Network Orchestration Architecture Overview

RESTCONF NBI Consumer Application

Network Domain A Network Domain B

Figure 4 Network orchestration architecture.

Aviat Networks 10 May 2019 17

18 10 May 2019 Aviat Networks

RESTCONF also incorporates mechanisms to access individual elements of a collection of resources by

The key tenets of the RESTCONF protocol:

Schema-Mount and the RESTCONF NBI

Aviat Networks 10 May 2019 19

Types of YANG modules

Table 2. YANG Module types.

YANG Module Type Description Module Example

20 10 May 2019 Aviat Networks

The ProVision Plus YANG Library Implementation

Aviat Networks 10 May 2019 21

Network Management Datastore Architecture (NMDA) and Datastores