Juniper NETWORKS NETCONF & YANG API Software User Guide
- June 16, 2024
- JUNIPER NETWORKS
Table of Contents
- Introduction
- Prerequisites and Preparations
- Introduction to NETCONF Orchestration API
- Supported Features in Paragon Active Assurance
- Examples of Controlling Paragon Active Assurance via NETCONF & YANG API
- Examples: Test Agents
- Create Test Agent in Control Center
- Examples: Inventory Items
- Examples: Alarms
- Examples: SSH Keys
- Examples: Tests
- URL of Control Center without trailing slash.
- This is for example used in test report-url.
- Get json config from response
- Examples: Monitors
- Using Tags
- Troubleshooting
- Notes on Test Agent Applications and Test Agent Appliances
- Appendix: Tree Structure of Full YANG Model
- References
- Read User Manual Online (PDF format)
- Download This Manual (PDF format)
NETCONF & YANG API Orchestration
Guide
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
to check that ConfD responds on port 830. In the command,
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:
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.
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:
- Download the software from https://github.com/ncclient/ncclient.
- Run this command: pip 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.
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.
- Add the user “confd@netrounds.com“, and grant this ConfD user admin permission in the GUI by clicking the Invite button.
- 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.
- 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
Supported NETCONF Capabilities
The table below points to the IETF RFCs describing the NETCONF capabilities used for the purpose of Paragon Active Assurance orchestration.
- ietf-netconf.yang
- IETF RFC 6241, Network Configuration Protocol (NETCONF), https://tools.ietf.org/html/rfc6241
- The only supported error handling method is rollback-on-error.
- The only supported data store is writable-running.
- ietf-netconf-notifications.yang
- IETF RFC 5277, NETCONF Event Notifications, https://tools.ietf.org/html/rfc5277
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:
-
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.
-
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. -
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.
-
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.
We proceed in the following steps, which are detailed in the following:
- At the outset, the Paragon Active Assurance account “demo” has no Test Agents in its inventory.
- 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).
- The Test Agent is deployed in OpenStack. (Deployment on that platform is chosen here as one possibility among others.)
- 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.Step 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 = “””
)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:Once 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”:
Step 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):
For 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.
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:
Running this code gives output like that below:
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:
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.
When 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‘>
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
Creating a Y.1731 MEP
Creating an IPTV Channel
Creating a Ping Host
Creating a SIP Account
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.)
Running this code gives output like that below:
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 List
Retrieving All Alarm Email Lists
SNMP Managers
Creating an SNMP Manager
Retrieving All SNMP Managers
Alarm Templates
Creating an Alarm Template![Juniper NETWORKS NETCONF & YANG API Software
- Templates](https://manuals.plus/wp-content/uploads/2024/01/Juniper-NETWORKS- NETCONF-YANG-API-Software-Templates.png)
Retrieving All Alarm Templates
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.
Deleting an SSH Key
If you want to delete an SSH key, use the following command:
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:
For explanations, see the section “Legend” on page 81 in the Appendix.
The following steps are shown below:
- Test Agents have been registered to the Paragon Active Assurance account, but no tests have yet been started.
- The required input parameters are identified in the test template that will be run.
- 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.
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.
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
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,
We can now run the script using ncclient. Assuming all is correct, the test
will be initiated and its execution displayed in Control Center:If the test is successfully started, Control Center will respond
with the test ID. In this example, the test ID is 3:The 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:
The output will look something like this:
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
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.
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
- account test-agent interface
- 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:
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
- 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,
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:
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.
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:
The output is a list of all running monitors as shown below:
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.
The output will look something like this:
**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**Importing Monitor Templates
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
Assigning a Tag
To assign a tag to a resource, you add it as a new
To assign a tag to a TWAMP reflector, do the following:
Assigning a tag to a monitor is handled similarly:
Alternatively, you can assign an existing tag to any of these resource types
when creating the resource, by including the
Updating a Tag
Updating an existing tag with new attributes is analogous to creating a tag:
Unassigning a Tag
To unassign a tag from a resource, add the attribute nc:operation=”delete” to
the
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
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
YANG Model Tree Structure
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
- Example Domain
- GitHub - mbj4668/pyang: An extensible YANG validator and converter in python
- GitHub - ncclient/ncclient: Python library for NETCONF clients
Read User Manual Online (PDF format)
Read User Manual Online (PDF format) >>