Juniper NETWORKS NETCONF & YANG API Software User Guide

June 16, 2024
JUNIPER NETWORKS

JUNIPER NETWORKS Logo 1 NETCONF & YANG API Orchestration
GuideJuniper NETWORKS NETCONF & YANG API Software Published
2023-07-07
RELEASE 4.2

Introduction

Purpose of This Document
This documentation describes how to integrate Paragon Active Assurance with a network service orchestrator via the Control Center NETCONF & YANG API. Hands- on examples are given of the principal tasks involved, including: creating and deploying Virtual Test Agents, running tests and monitors, and retrieving results from these activities.
In this document, the freely available Python NETCONF client ncclient is used in the role of orchestrator.

Conventions
The following abbreviations are used in this document:

Abbreviation Meaning
CLI Command Line Interface
EM Element Manager
ES Errored Second
MEP MEG (Maintenance Entity Group) End Point (ITU-T Y.1731 definition) or

Maintenance End Point (Cisco definition)
NFV| Network Function Virtualization
NFVO| Network Function Virtualization Orchestrator
NSD| Network Service Descriptor
RPC| Remote Procedure Call
SIP| Session Initiation Protocol
SLA| Service Level Agreement
S-VNFM| Special VNF Manager
VNF| Virtual Network Function
vTA| Virtual Test Agent

Notes on Backward Compatibility

In versions 2.35.4/2.36.0 of the NETCONF & YANG API, the validation of certain requests was made more stringent to adhere to the NETCONF standard. This means that client code based on older versions of this guide might now be rejected.
For example, in previous Python example code, no namespace attribute was provided. The namespace now needs to be supplied in the request XML whenever you want to modify a ConfD resource.

Prerequisites and Preparations

ConfD Installation
ConfD (a product from Tail-f) is used as an intermediary between the Paragon Active Assurance system and NETCONF. ConfD connects Paragon Active Assurance configuration and operational data to the NETCONF & YANG API.
ConfD should have been installed along with the Control Center software, as described in the Installation Guide.

Verifying That ConfD Is Running
To verify that the ConfD is up and running, run the command
ssh -s @localhost -p 830 netconf
to check that ConfD responds on port 830. In the command, is as defined by the netconf user create
command in the Installation Guide, section Installing ConfD. Give the password defined by the same command.
In the output, verify that the Control Center module is included. The output should contain a line like the following:

http://ncc.netrounds.com?module=netrounds- ncc&revision=2017-06-15

Synchronizing the Configuration Database with Control Center

Finally, we need to update the configuration database through NETCONF. We will do so here by means of a Python library called ncclient (NETCONF Client). However, the task could also be accomplished in a different programming language as long as it uses the NETCONF/YANG protocol.
The role of ncclient is to act as a client towards the ConfD server that hosts the NETCONF/YANG API.

Juniper NETWORKS NETCONF & YANG API Software -Control
Center

It is worth pointing out that ncclient is not related in any way to Control Center (previously “Netrounds Control Center”), although the name happens to begin with “ncc”.
Here is how to install ncclient:

We can now perform the synchronization as follows. Note carefully that this needs to be done on a separate computer, and not on the Control Center server itself:

#
# NOTE:
# This script acts as a client towards ConfD running on the NCC server.
# It will use the NETCONF/YANG API for communication.

Juniper NETWORKS NETCONF & YANG API Software -Control Center
1

NOTE : This procedure is also required whenever Test Agents have been installed and registered independently of NETCONF. See the note in the section “Overview of Test Agent Orchestration” on page 17 for more information.

Setting Up Multiple NETCONF-controlled Paragon Active Assurance Accounts

The steps below are required only if you wish to set up further Paragon Active Assurance accounts to be controlled by NETCONF, in addition to the account configured in this way in the Installation Guide, section “Installing ConfD”.
For each such account, proceed as follows:

  • In Control Center, log in to the account and navigate to Account > Permissions.Juniper NETWORKS NETCONF & YANG API Software -Account
  • Add the user “confd@netrounds.com“, and grant this ConfD user admin permission in the GUI by clicking the Invite button.Juniper NETWORKS NETCONF & YANG API Software -Account 1
  • Synchronize the configuration database with Control Center as described in the section “Synchronizing the Configuration Database with Control Center” on page 4.
    You should now be able to control multiple Paragon Active Assurance accounts with the same ConfD user.

NOTE : Once you start controlling a Paragon Active Assurance account via ConfD, you must NOT make changes to this account through the web GUI with respect to any Paragon Active Assurance features that are “config” (see the chapter “Supported Features in Paragon Active Assurance” on page 9). If you do, loss of sync will result.

Introduction to NETCONF Orchestration API

Overview

A third-party NFVO or service orchestrator is typically the component which initiates test and monitoring sessions using the Control Center API. This orchestrator also retrieves the aggregated measurement results from the Test Agent activities. Performance KPIs may be retrieved by third-party Performance Management Systems, while events – once triggered by threshold violations set in the Control Center – can be sent to third-party Fault Management systems.
To summarize, the figure below shows how Paragon Active Assurance interacts with other third-party systems in the OSS landscape.

Juniper NETWORKS NETCONF & YANG API Software -Overview

  • NFVO/Service Orchestrator: Instructs the VNF Manager to deploy the vTAs and configure Paragon Active Assurance into the service chain. Once the service has been activated, the orchestrator uses the API towards Control Center to trigger service activation tests and retrieve pass/fail results. If the tests are passed, the orchestrator will use the API towards Control Center to start active monitoring of the service. KPIs from the monitoring are retrieved continuously either by the orchestrator or by a separate Performance Management platform.
  • Control Center: Deploys, scales, and terminates the vTA as instructed by the NFVO or service orchestrator.
  • Performance Management system or Service Quality Management system: Reads KPIs from active monitoring via the Control Center API.
  • Fault Management system: Receives NETCONF, SNMP, or email notifications from Control Center if SLAs are violated.

Definitions of Concepts in Paragon Active Assurance

  • Test Agents: The components that perform measurements (for tests as well as monitors) in a Paragon Active Assurance system. Test Agents consist of software with the ability to generate, receive, and analyze real network traffic.
  • The kind of Test Agent discussed in this document is the Virtual Test Agent (vTA), a virtual network function (VNF) deployed on a hypervisor. Other types of Test Agent also exist.
  • There are two basic types of measurement in Paragon Active Assurance, tests and monitors.
  • Test: A test consists of one or several steps, each of which has a specified, finite duration. Steps are executed sequentially. Each step may entail running multiple tasks concurrently.
  • Monitor: A monitor does not have a specified duration but executes indefinitely. Like a step in a test, a monitor may execute multiple concurrent tasks.
  • Template: When Paragon Active Assurance is controlled by an orchestrator, tests and monitors are always executed by means of templates in which the test or monitor is defined. Parameter settings can be passed as inputs to the template at runtime.

Workflow for Automation
Design Time

At design time, you prepare measurements by creating templates for tests and monitors in Paragon Active Assurance. How to do that is covered in the chapter “Test and Monitor Templates” on page 15.

Runtime
At runtime, you set up your devices and perform the actual measurements.

  • An overview of all examples given is found in the chapter “Examples of Controlling Paragon Active Assurance via NETCONF & YANG API” on page 15.
  • How to deploy and configure Test Agents is gone through in the chapter “Examples: Test Agents” on page 16.
  • How to import inventory items such as TWAMP reflectors and IPTV channels is gone through in the chapter “Examples: Inventory Items” on page 29.
  • How to configure alarms is explained in the chapter “Examples: Alarms” on page 35.
  • How to run tests and monitors by executing Paragon Active Assurance templates through NETCONF is described in the chapters “Examples: Tests” on page 43 and “Examples: Monitors” on page 54.

Supported Features in Paragon Active Assurance

All test and monitor types in Paragon Active Assurance can be created and executed through the use of templates. How to do this is covered in the in-app help under “Tests and monitors” > “Creating templates”.

Creation of Paragon Active Assurance accounts is currently not supported; however, one or several predefined accounts will have been set up for the user.
The tables below detail what features in Paragon Active Assurance are available in this release, and how these features are represented in YANG.

Explanation of YANG Constructs

For convenience, definitions are given here of the YANG constructs referred to in the feature table.

  • Config (config=true): Configuration data, required to transform a system from one state to another.
  • State (config=false): State data: additional data on a system that is not configuration data, such as read-only status information and collected statistics.
  • RPC: A Remote Procedure Call, as used within the NETCONF protocol.
  • Notification: Event notifications sent from a NETCONF server to a NETCONF client.

Tables of Paragon Active Assurance Features Available for Orchestration
Resource: Monitoring
YANG path:/accounts/account/monitors

Feature Subfeature YANG construct
Create/modify/delete monitor Based on monitor template Config
Start/stop monitor Config
Monitor templates List existing monitor templates with inputs State
NETCONF notifications Alarm state changed Notification
Monitor results SLA/ES counter for top level (%)
SLA/ES counter for task level (%) State

Unlike tests (compare Resource: Tests below), monitors are not started with an RPC but rather by committing the monitor configuration.
Resource: Tests
YANG path: /accounts/account/tests

Feature Subfeature YANG construct
Start test Based on test template RPC
Manage tests List tests with status State
Test templates List existing test templates with inputs State
NETCONF notifications Test status changed Notification
Test results Get test step status (pass, fail, error, …) State

Resource: Test Agents
YANG paths:

  • /accounts/account/test-agents (Config)
  • /accounts/account/registered-test-agents (State)

Test Agents under /accounts/account/test-agents are the ones that are config in an account. Only these Test Agents can be configured and used in tests and monitors via NETCONF by the orchestrator.
After you have configured a Test Agent and it has registered to the account, the Test Agent will appear under /accounts/account/registered-test-agents. You can find all registered Test Agents using a “get” command in NETCONF (compare the chapter Examples: Test Agents).
Under /accounts/account/registered-test-agents you may also find Test Agents that have not yet been configured. Any such Test Agents must be configured before they can be used.
In an orchestration scenario, it is generally recommended that you do all configuration of your Paragon Active Assurance account through NETCONF. This ensures that test-agents and registered-test-agents do not diverge.

Feature Subfeature YANG construct
Pre-create Test Agent on server Config
Configure offline Test Agent (Control Center pushes config to Test Agent
when it comes online) Config
Use existing/externally configured Test Agents Use in test/monitor Config
Configure interfaces Config
Get status State
Configure Test Agent (Test Appliance only) Configure NTP Config
Configure bridges Config
Configure VLAN interfaces Config
Configure SSH keys Config
IPv6 Config
Utils Reboot RPC
Update RPC
NETCONF notifications Online status changed Notification
Status Get system status (uptime, memory usage,
load average, version) State

Resource: Inventory
YANG path: /accounts/account/twamp-reflectors

Juniper NETWORKS NETCONF & YANG API Software -Overview
1Juniper NETWORKS NETCONF & YANG API
Software -Overview 2Juniper NETWORKS NETCONF &
YANG API Software -Overview 3

Supported NETCONF Capabilities

The table below points to the IETF RFCs describing the NETCONF capabilities used for the purpose of Paragon Active Assurance orchestration.

Test and Monitor Templates
Templates for test and monitor types need to be set up manually through the Paragon Active Assurance front-end user interface. How to do this is covered in the in-app help under “Tests and monitors” > “Creating templates”.

Examples of Controlling Paragon Active Assurance via NETCONF & YANG API

In the chapters that follow, it is assumed that suitable test and monitor templates have been defined according to the instructions given in the chapter “Test and Monitor Templates” on page 15.

Tools Used in Examples
All the examples in the subsequent chapters have been constructed using the following freely available tools:

  • Pang: Used to visualize and browse the YANG models.
  • Available at https://github.com/mbj4668/pyang (clone from git and run python setup.py install).
  • Python NETCONF client “ncclient”: Used to communicate with Control Center using NETCONF.
  • Available at https://github.com/ncclient/ncclient (run pip install ncclient).
    The netrounds-ncc.yang data model is found in /opt/netrounds-confd once ConfD has been installed according to the Installation Guide).

Overview of Key Tasks Performed

(Some further tasks are also exemplified in what follows.)

  • “Creating and deploying a new Test Agent” on page 16
  • “Creating inventory items (e.g. reflectors)” on page 29
  • “Setting up alarm templates and where to send alarms” on page 35
  • “Creating and running a test” on page 45
  • “Retrieving test results” on page 50
  • “Starting a monitor (includes setup of alarms)” on page 60
  • “Retrieving SLA status for a monitor” on page 67
  • “Working with tags” on page 71

Examples: Test Agents

Overview of Test Agent Orchestration
Test Agents in Paragon Active Assurance are considered as “configuration” in the context of orchestration. This means that creation, control, and deletion of Test Agents should be done via the orchestrator and NETCONF rather than via the Paragon Active Assurance GUI.
IMPORTANT: If a Test Agent is installed by a technician and registered to Control Center without first being created via the NETCONF & YANG API, the Test Agent will not exist in the configuration database, and the system will get out of sync. For ConfD to become aware of the Test Agent in this case, it will be necessary to perform a new synchronization with Control Center, as detailed in the section “Synchronizing the Configuration Database with Control Center” on page 4.

Orchestration of Virtual Test Agents (vTAs) should therefore rather be done in the following steps:

  1. Create the Virtual Test Agent, including its interface configuration, using the NETCONF & YANG interface to Control Center. The name of the Test Agent will be its unique key.

  2. Deploy the vTA on a virtualization platform. Follow the instructions in the online help under Test Agents > Installation. The basic interface configuration that allows the vTA to connect to Control Center, as well as credentials for authentication, is provided into the vTA using cloud-init user data.
    Once the vTA has booted, it will automatically connect to Control Center using an encrypted OpenVPN connection. A NETCONF notification is sent since the value of the vTA’s test-agent-statuschange parameter has now changed to “online”.
    NOTE : Since the name of the vTA is its identifier in Control Center, this name must be the same as that defined in Control Center in “step 1” on page 17.

  3. Once the vTA has connected and authenticated to Control Center, the interface configuration is pushed to the vTA. This is the interface configuration provided in “step 1” on page 17 when the vTA was created in Control Center.

  4. After the vTA has served its purpose, delete the vTA.

Creating and Deploying a New Test Agent

We first need to create a Test Agent using the NETCONF & YANG interface to Control Center. When a Test Agent is created in this way, no synchronization with Control Center is needed.
The YANG model for a Test Agent is as depicted below. It is obtained as output from the command
pyang -f tree netrounds-ncc.yang
The full YANG model is given in “Appendix: Tree Structure of Full YANG Model” on page 81, which also contains a legend explaining the conventions used in this and other YANG model illustrations in the present document.

Juniper NETWORKS NETCONF & YANG API Software -agentsJuniper NETWORKS NETCONF & YANG API Software -agents
1Juniper NETWORKS NETCONF & YANG API Software
-agents 2

We proceed in the following steps, which are detailed in the following:

  1. At the outset, the Paragon Active Assurance account “demo” has no Test Agents in its inventory.
  2.  A Test Agent called “vta1” is created using ncclient. At this stage, no real Test Agent exists yet (that is, it has not yet been started).
  3. The Test Agent is deployed in OpenStack. (Deployment on that platform is chosen here as one possibility among others.)
  4. The Test Agent connects to the Control Center account “demo” and is now ready for use.
    Step 1: At the outset, there are no Test Agents in the account “demo”. See the screenshot below from the Control Center GUI.Juniper NETWORKS NETCONF & YANG
API Software -agents 3Step 2: A Test Agent is created in Control Center using the Python NETCONF client “ncclient”. Below is ncclient code for creating a Test Agent having one physical interface with a DHCP address:

import argparse
from ncclient import manager
parser = argparse.ArgumentParser(description=’Test creating Test Agent’)
parser.add_argument(‘–host’, help=’The hostname where ConfD is found’, required=True)
parser.add_argument(‘–port’, help=’The port to connect to ConfD’, required=True)
parser.add_argument(‘–username’, help=’The username to connect to ConfD’, required=True)
parser.add_argument(‘–password’, help=’Password to the ConfD account’, required=True)
parser.add_argument(‘–netrounds-account’, help=’The NCC account short name’, required=True)
parser.add_argument(‘–test-agent-name’, help=’Name of Test Agent’, required=True)
args = parser.parse_args()
with manager.connect(host=args.host, port=args.port, username=args.username,
password=args.password, hostkey_verify=False) as m:

Create Test Agent in Control Center

xml = “””

Juniper NETWORKS NETCONF & YANG API Software -agents 4)print m.edit_config(target=’running’, config=xml)

NOTE : The code preceding with manager.connect(…) is omitted from subsequent example code snippets.
An NTP server is configured on eth0, and eth0 is also the management interface (that is, the interface that connects to Control Center).
A Test Agent Application does not currently allow configuring interfaces. For this reason, from version 2.34.0 onward, it is possible to omit the interface configuration in the YANG schema. The corresponding XML is therefore radically simplified in this case:Juniper NETWORKS NETCONF & YANG API Software -agents
5Once the Test Agent has been created, it exists in the configuration database and in Control Center. See the screenshot below of the Test Agent inventory, showing the Test Agent “vta1”:

Juniper NETWORKS NETCONF & YANG API Software -agents 6Step 3: It is now time to deploy the Test Agent “vta1” in OpenStack.
The Test Agent will use cloud-init user data to retrieve the information on how to connect to Control Center. Specifically, the user data text file has the following contents (Note that the #cloud-config and netrounds_test_agent lines must be present, and that the remaining lines must be indented):

Juniper NETWORKS NETCONF & YANG API Software - ColdFor further information, please refer to the document How to Deploy Virtual Test Agents in OpenStack.
Once the Test Agent has been deployed and has connected to Control Center, the configuration will be pushed from Control Center to the Test Agent.

Juniper NETWORKS NETCONF & YANG API Software - Cold 1

Step 4: The Test Agent is now online in Control Center and has obtained its configuration. The Test Agent is ready for use in tests and monitoring. See these sections:

  • “Starting a Test” on page 45
  •  “Starting a Monitor” on page 60

Listing the Test Agents in Your Paragon Active Assurance Account
Below is example ncclient Python code for listing the Test Agents in a Paragon Active Assurance account:

Juniper NETWORKS NETCONF & YANG API Software - Cold 2Juniper NETWORKS NETCONF & YANG API Software - Cold
3Running this code gives output like that below:

Juniper NETWORKS NETCONF & YANG API Software - Cold 4Juniper NETWORKS NETCONF & YANG API Software - Cold
5

Deleting a Test Agent
After a test has completed, it might be relevant in some use cases to delete the Test Agent.
Below is a code snippet showing how to do this with ncclient:

Juniper NETWORKS NETCONF & YANG API Software - Agent

NETCONF Notifications
Below, we present a simple example script for listening to all incoming NETCONF notifications from Control Center. These notifications are sent whenever certain events take place, such as a Test Agent going offline or a user-initiated test being completed. Based on the information carried in the notifications, users can assign automated follow-up actions in the orchestrator.

Juniper NETWORKS NETCONF & YANG API Software - NETCONFWhen the above script is executed, NC client will present the received notification in structured XML. See the example output below, which shows a Test Agent going offline unexpectedly.
<ncclient.operations.notify.Notification object at 0x7f30242b6f10>
<?xml version=”1.0″ encoding=”UTF-8″?>
<notification xmlns=”urn:ietf:params:xml:ns:netconf:notification:1.0″>
2017-02-03T15:09:55.939156+00:00

<test-agent-status-change xmlns=’http://ncc.netrounds.com‘>

demo HW1 offline

Examples: Inventory Items

Creating (importing) and managing inventory items such as TWAMP reflectors and Y.1731 MEPs is done in a similar way as for Test Agents. Below is XML and NETCONF code for defining such entities in Paragon Active Assurance through the NETCONF & YANG API and for retrieving lists of the items defined.

Creating a TWAMP Reflector

Juniper NETWORKS NETCONF & YANG API Software - TWAMPJuniper NETWORKS NETCONF & YANG API Software - TWAMP
1

Creating a Y.1731 MEP

Juniper NETWORKS NETCONF & YANG API Software - Figure Creating an IPTV Channel

Juniper NETWORKS NETCONF & YANG API Software -TWAMP 3

Creating a Ping Host

Juniper NETWORKS NETCONF & YANG API Software -HostJuniper NETWORKS NETCONF & YANG API Software -Host
1

Creating a SIP Account

Juniper NETWORKS NETCONF & YANG API Software -Accoun Juniper NETWORKS NETCONF & YANG API Software -Accoun
1

Retrieving Inventory Items
Below is Python code for retrieving all inventory items defined in an account. (All types of inventory items are fetched in one go here in order to avoid some repetition in the document. Naturally, any subset of inventory items can be  fetched by leaving out some of the lines under account below.)

Juniper NETWORKS NETCONF & YANG API Software -Items

Running this code gives output like that below:Juniper NETWORKS NETCONF &
YANG API Software -Items 1Juniper NETWORKS
NETCONF & YANG API Software -Items 2

Examples: Alarms

Alarm templates and associated items (SNMP managers, alarm email lists) are created and managed in a similar way as inventory items. This chapter contains XML and NETCONF code for defining such entities in Paragon Active  Assurance through the NETCONF & YANG API and for retrieving lists of the items defined.
Alarm Email Lists
Creating an Alarm Email ListJuniper NETWORKS NETCONF & YANG API
Software -Items 3Juniper NETWORKS NETCONF &
YANG API Software -Items 4

Retrieving All Alarm Email ListsJuniper NETWORKS NETCONF & YANG API
Software -Items 5

SNMP Managers
Creating an SNMP ManagerJuniper NETWORKS NETCONF & YANG API Software
-Items 6Juniper NETWORKS NETCONF & YANG API
Software -Items 7

Retrieving All SNMP ManagersJuniper NETWORKS NETCONF & YANG API
Software - SNMPJuniper NETWORKS NETCONF & YANG
API Software - SNMP 1

Alarm Templates
Creating an Alarm Template![Juniper NETWORKS NETCONF & YANG API Software

Retrieving All Alarm TemplatesJuniper NETWORKS NETCONF & YANG API
Software - Templates 2Juniper NETWORKS
NETCONF & YANG API Software - Templates 3

Examples: SSH Keys

You can add SSH public keys to a Test Agent via the NETCONF & YANG API. Using the corresponding private key you can then log in to the Test Agent via SSH.
The full list of available operations on SSH keys is as follows:

  • Add an SSH key
  • Modify an SSH key
  • Inspect an SSH key
  • List SSH keys
  • Delete an SSH key.
    Below, the add and delete operations are exemplified.

Adding an SSH Key

Here is how to create a new SSH key.Juniper NETWORKS NETCONF & YANG API
Software - Key

Deleting an SSH Key
If you want to delete an SSH key, use the following command:Juniper NETWORKS
NETCONF & YANG API Software - Key 1

Examples: Tests

It is assumed here that Test Agents (as many as are required for the tests) have been created according to the section “Creating and Deploying a New Test Agent” on page 17.
YANG Model Paths for Tests

Item YANG model path: /accounts/account/tests …
tests /.
test[id] /test
id /test/id
name /test/name
status /test/status
start-time /test/start-time
end-time /test/end-time
report-url /test/report-url
steps /test/steps
step[id] /test/steps/step
name /test/steps/step/name
id /test/steps/step/id
start-time /test/steps/step/start-time
end-time /test/steps/step/end-time
status /test/steps/step/status
status-message /test/steps/step/status-message
templates /templates
template[name] /templates/template
name /templates/template/name
description /templates/template/description
parameters /templates/template/parameters
parameter[key] /templates/template/parameters/parameter
key /templates/template/parameters/parameter/key
type /templates/template/parameters/parameter/type

Prerequisites for Test Orchestration

  •  In order to start a test through NETCONF using NC client, it is required to first build a test template using the Control Center GUI as detailed in the in-app help under “Tests and monitors” > “Creating templates”. All fields specified in that template as “Template input” will be required as parameters in the XML when orchestrating the initiation of the test template.
  • Running tests in Paragon Active Assurance is considered as “state” in the context of orchestration. State data is non-writable data that is not stored in the configuration database, as opposed to the configuration data mentioned in  the section “Overview of Test Agent Orchestration” on page 17. This basically means that changes to tests or templates in the Control Center GUI will not cause any sync-related issues between Control Center and the configuration  database.
  • To get report-URL right in test reports, you need to make sure the Control Center URL is correctly configured. This is done in the file /opt/netrounds-confd/settings.py. By default the Control Center host name is retrieved using  socket.gethostname(): see below. If this does not yield the correct result, you need to set the host name (or the entire URL) manually in this file.

URL of Control Center without trailing slash.

This is for example used in test report-url.

HOSTNAME = socket.gethostname()
NETROUNDS_URL = ‘https://%s’ % HOSTNAME
Starting a Test
As described in the section “Creating and Deploying a New Test Agent” on page 17, run the command pang -f tree netrounds-ncc.yang
from the directory /opt/netrounds-confd/ in order to output the YANG model. In this model, the RPC for starting a test using NC client looks as follows:Juniper NETWORKS NETCONF & YANG API Software - Key
2Juniper NETWORKS NETCONF & YANG API Software -
Key 3

For explanations, see the section “Legend” on page 81 in the Appendix.

The following steps are shown below:

  1. Test Agents have been registered to the Paragon Active Assurance account, but no tests have yet been started.
  2. The required input parameters are identified in the test template that will be run.
  3.  A 60 second HTTP test is started using ncclient.

Step 1: At the outset, no tests have been initiated in the Paragon Active Assurance account. See the screenshot below from the Control Center GUI.Juniper NETWORKS NETCONF & YANG API Software - Key
4
Step 2: The template we will use to initiate the test in this example is an HTTP test template. It has two mandatory input fields ( Clients and URL) which we have specified as such when building the template in the Control Center GUI.Juniper NETWORKS NETCONF & YANG API Software - Key
5

We will define these parameters (among others) in the XML configuration communicated to the configuration database by our NETCONF manager (ncclient).
Step 3: The HTTP test is initiated using ncclient.
Below is example code where the required configuration information and parameters are specified for the HTTP test template. Depending on how the template has been built, the details here may vary.
For each parameter, the attribute needs to be supplied. The key is identical to the parameter’s
Variable name in Control Center. You can inspect variable names as follows:

  • Click Tests on the side bar and select New Test Sequence.
  • Click My Templates.
  • Click the Edit link below the template of interest.
  • Click the Edit input button in the top right corner.

In our example, and by default, the variable names are simply lowercase versions of the display names seen in Control Center (“url” vs. “URL”, etc.). However, in the Control Center GUI, you can rename the variables to whatever you like.
Besides the key, each parameter needs to have its type specified: for example,

for the URL. Please note that you need to review the complete YANG model in order to obtain full information on types. For Test Agent interfaces the type has a more complex structure, as evidenced under in the code below.![Juniper NETWORKS NETCONF & YANG API Software - Key to](https://manuals.plus/wp- content/uploads/2024/01/Juniper-NETWORKS-NETCONF-YANG-API-Software-Key-to.png)

We can now run the script using ncclient. Assuming all is correct, the test will be initiated and its execution displayed in Control Center:Juniper
NETWORKS NETCONF & YANG API Software - ControlIf the test is successfully started, Control Center will respond with the test ID. In this example, the test ID is 3:Juniper NETWORKS NETCONF
& YANG API Software - Control 1The test ID can also be found in the URL for the test in the Control Center GUI. In this example, that URL is https://host/demo/testing/3/.
Retrieving Test Results
The most straightforward way to retrieve test results is by pointing to the test ID.
Below is Python code for getting the results from the above HTTP test with ID = 3:
with manager. Connect(host=args.host, port=args.port, username=args.username,password=args.password, hostkey_verify=False) as m:Juniper NETWORKS NETCONF & YANG API Software - Control
2

The output will look something like this:Juniper NETWORKS NETCONF & YANG API
Software - Control 3 Juniper NETWORKS NETCONF &
YANG API Software - Control 4

Exporting and Importing Test Templates
Test templates can be exported in JSON format and reimported in that format into Control Center. This is useful if you want to use test templates in a different installation of Control Center. (The initial creation of the templates is best  handled through the Control Center GUI.)
Below is code for performing the export and import.
Exporting Test Templates

Juniper NETWORKS NETCONF & YANG API Software - Control
5

Get json config from response

root = ET.fromstring(response._raw)
json_config = root[0].text
print json_config
The template is contained in the json_config object.
Importing Test Templates
A JSON config object holding test templates can be reimported into Control Center as follows.Juniper NETWORKS NETCONF & YANG API Software
-TemplatesJuniper NETWORKS NETCONF & YANG
API Software -Templates 1

Examples: Monitors

This section assumes that Test Agents (as many as are required by the monitors) have been created according to the section “Creating and Deploying a New Test Agent” on page 17.
YANG Model Paths for Monitors

Item YANG model path: /accounts/account/monitors …
monitors /.
monitor[name] /monitor
name /monitor/name
description /monitor/description
started /monitor/started
template /monitor/template
alarm-configs /monitor/alarm-configs
Item **YANG model path: /accounts/account/monitors/monitor/alarm-

configs …
alarm-config[identifier]| /alarm-config
identifier| /alarm-config/identifier
template| /alarm-config/template
email| /alarm-config/email
snmp| /alarm-config/snmp
thr-es-critical| /alarm-config/thr-es-critical
thr-es-critical-clear| /alarm-config/thr-es-critical-clear
thr-es-major| /alarm-config/thr-es-major
thr-es-major-clear| /alarm-config/thr-es-major-clear
thr-es-minor| /alarm-config/thr-es-minor
thr-es-minor-clear| /alarm-config/thr-es-minor-clear
thr-es-warning| /alarm-config/thr-es-warning
thr-es-warning-clear| /alarm-config/thr-es-warning-clear
no-data-severity| /alarm-config/no-data-severity
no-data-timeout| /alarm-config/no-data-timeout
action| /alarm-config/action
window-size| /alarm-config/window-size
interval| /alarm-config/interval
send-only-once| /alarm-config/send-only-once
snmp-trap-per-stream| /alarm-config/snmp-trap-per-stream
Item| YANG model path: /accounts/account/monitors …
parameters| /monitor/parameters
Item| YANG model path: /accounts/account/monitors/monitor/parameters …
parameter[key]| /parameter
key| /parameter/key
(value-type)| /parameter
:(integer)| /parameter
integer| /parameter/integer
:(float)| /parameter
float| /parameter/float
:(string)| /parameter
Item| YANG model path: /accounts/account/monitors/monitor/parameters …**
string| /parameter/string
:(test-agent-interfaces)| /parameter
test-agent-interfaces| /parameter/test-agent-interfaces
test-agent-interface[“1” on page 58| /parameter/test-agent-interfaces/
account| /parameter/test-agent-interfaces/test-agent-interface/account
test-agent| /parameter/test-agent-interfaces/test-agent-interface/test-agent
interface| /parameter/test-agent-interfaces/test-agent-interface/interface
ip-version| /parameter/test-agent-interfaces/test-agent-interface/ip-version
:(twamp-reflectors)| /parameter
twamp-reflectors| /parameter/twamp-reflectors
twamp-reflector[name]| /parameter/twamp-reflectors/twamp-reflector
name| /parameter/twamp-reflectors/twamp-reflector/name
:(y1731-meps)| /parameter
y1731-meps| /parameter/y1731-meps
y1731-mep[name]| /parameter/y1731-meps/y1731-mep
name| /parameter/y1731-meps/y1731-mep/name
:(sip-accounts)| /parameter
sip-accounts| /parameter/sip-accounts
sip-account[“2” on page 58]| /parameter/sip-accounts/sip-account
account| /parameter/sip-accounts/sip-account/account
test-agent| /parameter/sip-accounts/sip-account/test-agent
interface| /parameter/sip-accounts/sip-account/interface
sip-address| /parameter/sip-accounts/sip-account/sip-address
:(iptv-channels)| /parameter
iptv-channels| /parameter/iptv-channels
iptv-channel[name]| /parameter/iptv-channels/iptv-channel
name| /parameter/iptv-channels/iptv-channel/name

  1. account test-agent interface
  2. account test-agent interface sip-address
Item YANG model path: /accounts/account/monitors …
status /monitor/status
last-15-minutes /monitor/status/last-15-minutes
status /monitor/status/last-15-minutes/status
status-value /monitor/status/last-15-minutes/status-value
last-hour /monitor/status/last-hour
status /monitor/status/last-hour/status
status-value /monitor/status/last-hour/status-value
last-24-hours /monitor/status/last-24-hours
status /monitor/status/last-24-hours/status
status-value /monitor/status/last-24-hours/status-value
templates /templates
template[name] /templates/template
name /templates/template/name
description /templates/template/description
parameters /templates/template/parameters
parameter[key] /templates/template/parameters/parameter
key /templates/template/parameters/parameter/key
type /templates/template/parameters/parameter/type

Prerequisites for Monitor Orchestration
Before you can start a monitor through NETCONF using ncclient, you need to build a monitor template in the Control Center GUI as explained in the in-app help under “Tests and monitors” > “Creating templates”. All fields specified as “Template input” in that template will be required as parameters in the XML when orchestrating the initiation of the template.
Getting Input Parameters from Monitor Templates
Below, two templates are shown. The first is for UDP monitoring between two Test Agent interfaces, and the second is for HTTP using a single Test Agent interface.
To find out the input parameters of a template, click the box representing the template. For the HTTP template, the parameters may look like this:

Juniper NETWORKS NETCONF & YANG API Software -Templates
2

We need to define these parameters in the next step when starting a monitor.
Starting a Monitor
Using the Test Agents that we defined and deployed in the section “Creating and Deploying a New Test Agent” on page 17, we can start a monitor from the template “HTTP” as shown below.
For each parameter, the attribute needs to be supplied. The key is identical to the parameter’s Variable name in Control Center. You can inspect variable names as follows:

  • Click Monitoring on the side bar and select New Monitor.
  • Click My Templates.
  • Click the Edit link below the template of interest.
  • Click the Edit input button in the top right corner.

In our example, and by default, the variable names are simply lowercase versions of the display names seen in Control Center (“url” vs. “URL”, etc.). However, in the Control Center GUI, you can rename the variables to whatever you like.
Besides the key, each parameter needs to have its type specified: for example,

for the URL. Please note that full information on the parameter type is found in the YANG model. For Test Agent interfaces the type has a more complex structure, as evidenced in the code below. In the example that follows, no alarm is associated with the monitor. For examples involving alarms, go to the section “Starting a Monitor with an Alarm” on page 62.

Juniper NETWORKS NETCONF & YANG API Software -Templates
3

Juniper NETWORKS NETCONF & YANG API Software -Templates
4

Starting a Monitor with an Alarm
To associate an alarm with a monitor, you can either point to an alarm template that has been defined, or you can supply the entire alarm configuration when creating the monitor. We will give one example of each approach below.
Setting Up a Monitor Alarm by Pointing to an Alarm Template
In order to make use of an alarm template, you must know its ID. To this end, first retrieve all your alarm templates as described in the section “Retrieving All Alarm Templates” on page 39 and note the name of the relevant template. You can then refer to that template as follows:

Juniper NETWORKS NETCONF & YANG API Software -Templates
5

Juniper NETWORKS NETCONF & YANG API Software -Templates
6

Setting Up a Monitor Alarm by Configuring It Directl y
Alternatively, you can set up an alarm for a monitor by supplying its entire configuration when creating the monitor, without referring to an alarm template. This is done as shown in the following example.

Juniper NETWORKS NETCONF & YANG API Software -Templates
7

Juniper NETWORKS NETCONF & YANG API Software -Templates
8

Juniper NETWORKS NETCONF & YANG API Software -Templates
9

Retrieving Running Monitors
To retrieve all monitors that are currently executing, run this script:
with manager. connect(host=args.host, port=args.port, username=args. user name, password=args.password, hostkey_verify=False) as m:

Juniper NETWORKS NETCONF & YANG API Software -Templates
in

The output is a list of all running monitors as shown below:

Juniper NETWORKS NETCONF & YANG API Software -Templates in
1

Juniper NETWORKS NETCONF & YANG API Software -Templates in
2

Retrieving SLA Status for a Monitor
Here is how to retrieve the SLA status for a monitor. In this example, we are retrieving the SLA status for the monitor “Network Quality” for three intervals of time: the last 15 minutes, the last hour, and the last 24 hours.

Juniper NETWORKS NETCONF & YANG API Software -Monitor

Juniper NETWORKS NETCONF & YANG API Software -Monitor
1

The output will look something like this:

Juniper NETWORKS NETCONF & YANG API Software -Monitor
2

**NETCONF Notifications** NETCONF notifications for monitors are triggered by SLA violations. These occur when the SLA for the monitor drops below an SLA threshold (“Good” or “Acceptable”) within a given time window, by default the last 15 minutes. It should be noted that SLA violation notifications are quick to appear after a service is impacted by an issue, while the SLA status will revert to “Good” only after 15 minutes, and only if no further violations occur. The time window can be changed by editing the setting SLA_STATUS_WINDOW (value in seconds) in [/etc/netrounds/netrounds.conf](/etc/netrounds/netrounds.conf). **Exporting and Importing Monitor Templates** This is done in exactly the same way as for test templates; compare the section “Exporting and Importing Test Templates” on page 52. The code snippets below illustrate how to export and import templates for monitors. **Exporting Monitor Templates**

Juniper NETWORKS NETCONF & YANG API Software -Monitor
Templates

Juniper NETWORKS NETCONF & YANG API Software -Monitor Templates
1

Importing Monitor Templates

Juniper NETWORKS NETCONF & YANG API Software -Monitor Templates
3

Juniper NETWORKS NETCONF & YANG API Software -Monitor Templates
4

Using Tags

Tags defined in Paragon Active Assurance can be applied to:

  • monitors
  • monitor templates
  • Test Agents
  • TWAMP reflectors
  • Ping hosts.
    For example, you can tag a monitor with the same tag as a subset of Test Agents that are going to run the monitor. This feature is particularly helpful if you have a large number of monitors and templates defined.

If you have set up an alarm with SNMP traps for a monitor, then the SNMP traps will be assigned the same tags as the monitor, if any.
Creating Tags
Below we show how to create a tag with name and color as defined by the XML

substructure.

Juniper NETWORKS NETCONF & YANG API Software -Tags

Assigning a Tag
To assign a tag to a resource, you add it as a new element under the

element for that resource. Here is how to assign a tag to a Test Agent:

Juniper NETWORKS NETCONF & YANG API Software -Tags 1

To assign a tag to a TWAMP reflector, do the following:

Juniper NETWORKS NETCONF & YANG API Software -Tags 2

Juniper NETWORKS NETCONF & YANG API Software -Tags 3

Assigning a tag to a monitor is handled similarly:

Juniper NETWORKS NETCONF & YANG API Software -Tags 4

Juniper NETWORKS NETCONF & YANG API Software -Tags 5

Alternatively, you can assign an existing tag to any of these resource types when creating the resource, by including the element containing the tag in question.
Updating a Tag
Updating an existing tag with new attributes is analogous to creating a tag:

Juniper NETWORKS NETCONF & YANG API Software -Tags
manage

Unassigning a Tag
To unassign a tag from a resource, add the attribute nc:operation=”delete” to the element belonging to the resource. Below, we unassign a tag from a monitor.

Juniper NETWORKS NETCONF & YANG API Software -Tags manage
1

Deleting a Tag
In order to delete a tag altogether from Control Center, the attribute nc:operation=”delete” is again used, but this time applied to the tag itself, defined under .

Juniper NETWORKS NETCONF & YANG API Software -Tags manage
2

Troubleshooting

Problem: Orchestrator and Paragon Active Assurance Out of Sync
The orchestrator and Paragon Active Assurance can end up out of sync for example if configuration changes have been made in the Control Center GUI, or if applying a configuration was not successful and rolling back to the previous state failed.
In case of a failed rollback, the NETCONF server will no longer accept configuration changes; it will reply with an error message stating that configuration is locked until back in sync. To get back in sync and unlock configuration changes, you need to run the command rpc sync-from-ncc which synchronizes all configuration from Control Center to the configuration database.
NOTE: The confd@netrounds.com user (or whatever has been configured) must have superuser privileges for everything to be synced successfully. This can be achieved with the command ncc user-update confd@netrounds.com –is-superuser If the user is not a superuser, a warning will appear saying that not everything could be synced, but that all that could be handled has been.
NOTE: If your orchestrator also stores the configuration, you will need to re-synchronize that as well since the requested configuration (the configuration which the orchestrator expects Control Center to have) will not have been applied.
Problem: Initial Sync (sync-from-ncc) Failed Due to Unsupported Resources
If you try to run rpc sync-from-ncc on an account that has its configuration created in the Control Center GUI, you might run into problems if the account contains unsupported resources. It is recommended that you start with an empty account and do all configuration of it through NETCONF. Otherwise, if you encounter issues with resource conflicts, you will have to remove the conflicting resources from the account.
Problem: NETCONF commands fail with ncclient.operations.rpc.RPCError: application communication failure
The NETCONF server does not restore connectivity to the Control Center server automatically if Control Center is restarted. To restore the connection to Control Center, restart the NETCONF process: sudo systemctl restart netrounds- confd

Notes on Test Agent Applications and Test Agent Appliances

Test Agent Applications in ConfD
Among Test Agents, the (newer) Test Agent Application works a bit differently from the (older) Test Agent Appliance.
Test Agent Applications do not currently support interface configuration. Therefore, the YANG schema allows specifying an empty interface configuration for such Test Agents. See “this passage” on page 23 for an example.
When synchronizing the ConfD database with Control Center using the sync-from- ncc command, you want the interface configuration to remain empty and not to be overwritten with what is found in Control Center. Therefore you need to use a special flag –without_interface_config with that command when working with Test Agent Applications.
Empty Interface Configuration for Test Agent Appliance
As noted above, Test Agent Application does not support interface configuration, and it is therefore possible to omit interfaces in the YANG schema.
But there are also use cases where you might want to omit the interface configuration from a Test Agent Appliance. An example of this could be an orchestration scenario where you are spinning up a Test Agent using cloud- init, and you want the interface configuration from there to be used, instead of letting ConfD overwrite it as the Test Agent comes online.
YANG Schema Changes Regarding Undefined Interfaces
Since an empty interface configuration is now allowed (from version 2.34.0 onward), it is possible to specify any interface name as input to a task running as part of a test or monitor.
This is required to be able to use a Test Agent Application, since for these no interface names are defined in ConfD. Note, however, that this also means you can run into problems if by accident you configure a test or monitor to use a non-existing interface. So please be mindful of this.
Limitations When Registering a Test Agent Created in ConfD
When creating a Test Agent via the REST or NETCONF/YANG API, we cannot know beforehand which type it is: Test Agent Appliance or Test Agent Application. This becomes clear only after the Test Agent has registered.
Once the Test Agent has been registered and has turned into one of these concrete types, you are not allowed to re-register it as a different type of Test Agent. This means you are not allowed to first register it as a Test Agent Appliance, then re-register it as a Test Agent Application, or vice versa. If you need a Test Agent of a different type, you will need to create a new Test Agent.

Appendix: Tree Structure of Full YANG Model

In this appendix, the section “Legend” on page 81 explains the syntax of the YANG model tree structure generated with the command pyang -f tree.
The section “YANG Model Tree Structure” on page 82 gives the output from that command applied to netrounds-ncc.yang. Parts of this output are reproduced elsewhere in the document.
Legend

Juniper NETWORKS NETCONF & YANG API Software -Legend

Juniper NETWORKS NETCONF & YANG API Software -Legend 1

YANG Model Tree Structure

Juniper NETWORKS NETCONF & YANG API Software - Model
Tree

Juniper NETWORKS NETCONF & YANG API Software - Model Tree
1

Juniper NETWORKS NETCONF & YANG API Software - Model Tree
2

Juniper NETWORKS NETCONF & YANG API Software - Model Tree
3

Juniper NETWORKS NETCONF & YANG API Software - Model Tree 3 NETWORKS NETCONF
& YANG API Software - Model Tree 4

Juniper NETWORKS NETCONF & YANG API Software - Model Tree
5

Juniper NETWORKS NETCONF & YANG API Software - Model Tree
6

Juniper NETWORKS NETCONF & YANG API Software - Model Tree
7

Juniper NETWORKS NETCONF & YANG API Software - Model Tree
8Juniper NETWORKS NETCONF & YANG API
Software - Model Tree Full

Juniper NETWORKS NETCONF & YANG API Software - Model Tree Full
1Juniper NETWORKS NETCONF & YANG API
Software - Model Tree Full 2

Juniper NETWORKS NETCONF & YANG API Software - Model Tree Full
3

Juniper NETWORKS NETCONF & YANG API Software - Model Tree Full
4

Juniper NETWORKS NETCONF & YANG API Software - Model Tree Full
5

Juniper NETWORKS NETCONF & YANG API Software - Model Tree Full
6

Juniper NETWORKS NETCONF & YANG API Software - Model Tree Full
7

Juniper Networks, the Juniper Networks logo, Juniper, and Junos are registered trademarks of Juniper Networks, Inc. in the United States and other countries. All other trademarks, service marks, registered marks, or registered service marks are the property of their respective owners. Juniper Networks assumes no responsibility for any inaccuracies in this document. Juniper Networks reserves the right to change, modify, transfer, or otherwise revise this publication without notice. Copyright © 2023 Juniper Networks, Inc. All rights reserved.

References

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>

JUNIPER NETWORKS User Manuals

Related Manuals