1 Overview

This chapter provides an overview of the Oracle Communications Network Integrity RESTCONF Network Discovery and UIM Integration cartridge.

About the RESTCONF Network Discovery Cartridge

The Representational State Transfer Configuration (RESTCONF) Network Discovery cartridge supports network discovery of devices using the RESTCONF protocol. It generates a representation of the network infrastructure that comprises both logical and physical device hierarchies. The logical hierarchy includes logical devices, child interfaces, sub-interfaces, and device interface configurations. The physical hierarchy includes physical devices, equipment, holders, and ports. This cartridge also creates associations between these hierarchies at the device level (between physical and logical devices) and at the interface level (between physical ports and interfaces).

Note:

Before using the RESTCONF Network Discovery cartridge, make sure your network devices support the RESTCONF protocol and Yet Another Next Generation (YANG) models. Network Integrity relies on standard RESTCONF/YANG interfaces for communication and does not offer tools to activate these protocols. To enable this support, contact the device manufacturer or vendor.

About the RESTCONF Protocol

The RESTCONF protocol, standardized by the Internet Engineering Task Force (IETF), allows users to install, modify, and delete the configuration of network devices. RESTCONF uses JSON-based encoding for both configuration data and protocol messages. It performs its operations through HTTP or HTTPS Representational State Transfer Configuration (REST) calls. The table below describes the main HTTP methods RESTCONF uses and their purposes.

Table 1-1 Main HTTP Methods of RESTCONF Protocol

HTTP Method	RESTCONF Purpose	Description
OPTIONS	Discover supported methods	Returns allowed HTTP methods for a resource
GET	Retrieve data or metadata	Fetches resource state/config; supports query parameters like content, depth, fields, filter, etc.
HEAD	Retrieve header-only metadata	Same as GET but without message body
POST	Create resources or invoke a Remote Procedure Call (RPC) or action	Creates list entries or triggers actions and returns 201 Created; and returns conflicts if the object already exists.
PUT	Create or replace a resource	Replaces the entire target with the configuration in the message.
PATCH	Merge updates into existing resource	Partial update (merge); supports both plain and YANG patches; returns 200 OK (with body) or 204 No Content.
DELETE	Remove a resource	Deletes target, returns a 204 No Content on success, or fails if the resource doesn't exist.

Note:

NI supports GET operation only with the query parameter fields.

The following examples show sample RESTCONF Request and responses.

Example 1: Sample RESTCONF Request to retrieve all operational data for interfaces.

http://100.76.169.40:1443/restconf/data/ietf-interfaces:interfaces

Example 2: Sample RESTCONF Response.

{
    "ietf-interfaces:interfaces": {
        "interface": [
            {
                "name": "Ethernet0/0",
                "type": "iana-if-type:ethernetCsmacd",
                "enabled": true,
                "ietf-ip:ipv4": {
                    "address": [
                        {
                            "ip": "192.0.2.105",
                            "netmask": "255.255.255.0"
                        }
                    ]
                },
                "ietf-ip:ipv6": {}
            },
            {
                "name": "Ethernet0/1",
                "type": "iana-if-type:ethernetCsmacd",
                "enabled": true,
                "ietf-ip:ipv4": {
                    "address": [
                        {
                            "ip": "192.0.2.102",
                            "netmask": "255.255.255.0"
                        },
                        {
                            "ip": "192.0.2.100",
                            "netmask": "255.255.255.0"
                        }
                    ]
                },
                "ietf-ip:ipv6": {}
            },
            {
                "name": "Ethernet0/2",
                "type": "iana-if-type:ethernetCsmacd",
                "enabled": true,
                "ietf-ip:ipv4": {
                    "address": [
                        {
                            "ip": "192.0.2.100",
                            "netmask": "255.255.255.0"
                        }
                    ]
                },
                "ietf-ip:ipv6": {}
            },
            {
                "name": "Ethernet0/3",
                "type": "iana-if-type:ethernetCsmacd",
                "enabled": true,
                "ietf-ip:ipv4": {
                    "address": [
                        {
                            "ip": "192.0.2.100",
                            "netmask": "255.255.255.0"
                        }
                    ]
                },
                "ietf-ip:ipv6": {
                    "address": [
                        {
                            "ip": "2001:db8:0:1::1",
                            "prefix-length": 64
                        },
                        {
                            "ip": "2001:db8:5eff:fe00:5301",
                            "prefix-length": 64
                        }
                    ]
                }
            },
            {
                "name": "Null0",
                "type": "iana-if-type:other",
                "enabled": true,
                "ietf-ip:ipv4": {},
                "ietf-ip:ipv6": {}
            }
        ]
    }
}

About YANG Models

YANG is a data modeling language standardized by the IETF. It defines how to represent configuration data, state data, RPCs, and notifications for network management protocols. YANG is an API contract language, which defines how clients and servers interact through an API.

A YANG specification is called a YANG module, and a group of modules is often referred to as a YANG model. A YANG model serves as the schema of a network device, similar to a database schema or blueprint. This schema outlines the structure and types of data the system can exchange—such as possible configuration settings, monitoring data, notifications, and available actions. This is different from instance data, which shows the actual configuration and real-time monitoring values in use. While the YANG model defines what is possible, the instance data reflects the current state of the system.

Architecture for Network Management Using RESTCONF and YANG

Figure 1-1 shows the architecture for network management made using RESTCONF and YANG models.

Note:

In order to use YANG for network management, YANG modules must be defined to model the target domain. These modules must be then loaded, compiled, or coded into the server.

Figure 1-1 Architecture for Network Management using RESTCONF and YANG Models

Description of "Figure 1-1 Architecture for Network Management using RESTCONF and YANG Models"

The sequence of events for the typical client server interaction is as follows:

• The client builds and sends an operation defined in the YANG module, as HTTP call with appropriate method and payload.

• The server receives and parses the payload and verifies the contents of the request against the data model defined in the YANG module.

• The server performs the requested operation, and builds the response, containing the response, any requested data, and any errors.

• The server sends the response, encoded in XML/JSON.

• The client receives and parses the JSON element.

• The client inspects the response and processes it as needed.

RESTCONF Communication Between Network Integrity and Devices

When using RESTCONF protocol to discover network devices, Network Integrity acts as a RESTCONF client. This allows Network Integrity to communicate with the devices in the network and retrieve device details and status and also configure the device.

When Network Integrity interacts with the devices using RESTCONF protocol, it does the following:

1. The client builds and sends a request using the YANG container selected in the YANG processor as an HTTP REST call.

2. The client receives the response from the device and decodes it.

About Supported Routing Protocols

This section provides information about the different routing protocol details that the RESTCONF Network Discovery and UIM Integration cartridge can discover, as listed below:

• Open Shortest Path First (OSPF)
• Link Layer Discovery Protocol (LLDP)
• Routing Information Protocol (RIP)
• Internet Protocol (IP)
• Border Gateway Protocol (BGP)
• Layer 2 Virtual Private Network (L2VPN)

Open Shortest Path First (OSPF)

OSPF is a link-state Interior Gateway Protocol (IGP) used for routing within an autonomous system. Each router running OSPF exchanges link-state advertisements (LSAs) with its neighbors and builds a complete map of the network topology.

Network Integrity uses the ietf-ospf.yang file (subset of the ietf-routing.yang model) to discover OSPF details. The attributes dr-ip-addr, neighbor-router-id and address discovered from this YANG model can be used to create A-end and Z-end information.

Link Layer Discovery Protocol (LLDP)

LLDP operates as a Layer 2 discovery protocol that provides a standardized method to encapsulate information about device capabilities, management address, device ID, and interface ID into LLDP frames. This protocol allows Network Integrity to discover the topology of connected network devices, and display paths between clients, switches, routers, application servers, and network servers.

Network Integrity uses the openconfig-lldp.yang file to discover LLDP information. The attributes interface name and management-address discovered from this YANG file serve to create A-end and Z-end information. The IP Assimilation cartridge uses this protocol to create topological links.

Routing Information Protocol (RIP)

RIP functions as a dynamic routing protocol based on the distance-vector algorithm. Routers using RIP exchange routing tables periodically with neighbors, using hop count as the exclusive metric for route selection. The protocol limits the maximum hop count to 15, defining the reachable network scope. Periodic updates maintain routing information, while convergence occurs over time according to the protocol’s timing mechanisms. RIP remains configured primarily in small or legacy network environments.

Network Integrity uses the ietf-rip.yang file to discover RIP information. The attributes discovered include IPv4 and IPv6 information: address and prefix. The next-hop address contained in the YANG model is used to identify the Z-end interface address.

Internet Protocol (IP)

The Internet Protocol (IP) is the core protocol at the network layer that provides addressing and routing for communication across networks. Every device connected to an IP network is assigned a unique IP address (IPv4 or IPv6), which allows packets to be delivered from a source host to a destination host, even across multiple intermediate routers.

Network Integrity uses the ietf-ip.yang file (a subset of the ietf-interfaces.yang model) to discover IPV4 or IPV6 address, sub-netmask and prefix for the A-end Device Interface. This information is used in the IP Assimilation cartridge to create A-end device and interface information for links.

Border Gateway Protocol (BGP)

BGP operates as an Exterior Gateway Protocol that exchanges routing information between distinct autonomous systems. Unlike IGPs which function within a single asynchronous system, BGP uses a path-vector mechanism and associates routes with attributes such as AS-path to enable policy-based routing, control traffic flow, and prevent routing loops. BGP supports scalable and policy-driven route management across complex network environments.

Network Integrity discovers neighbor-address and local-address attributes from the openconfig-bgp.yang file, which is used for routing details.

BGP supports the two operation types described below:

• External BGP (eBGP): Exchanges routing information between routers in different autonomous systems, typically at edge or border routers.
• Internal BGP (iBGP): Distributes routing information between routers within the same autonomous system to ensure consistent routing policies across the network.

Layer 2 Virtual Private Network (L2VPN)

L2VPN extends Layer 2 networks across wide-area backbones by enabling geographically dispersed sites to operate as part of the same Ethernet segment or LAN. It is implemented using Multiprotocol Label Switching (MPLS) pseudowires or IP-based tunneling techniques to encapsulate Layer 2 frames and transport them across the underlying infrastructure. This remains transparent to Layer 3 protocols, allowing independent routing configurations within the extended Layer 2 domain.

L2VPN supports network connectivity by delivering Layer 2 transport services without altering internal routing operations.

About Cartridge Dependencies

This section provides information on dependencies that the RESTCONF Network Discovery cartridge has on other cartridges.

Run-Time Dependencies

This cartridge requires that the following cartridges be deployed to Network Integrity:

• Address_Handlers
• UIM_Integration_Cartridge

Design-Time Dependencies

The RESTCONF Network Discovery cartridge has the following dependencies:

• Address_Handlers
• NetworkIntegritySDK
• ora_ni_uim_yang_model
• ora_uim_model
• UIM_Integration_Cartridge
• yang-generic-model-generator-8.0.0.jar
• yang-vendor-model-generator-8.0.0.jar

About the RESTCONF YANG Model

The RESTCONF YANG model used in the RESTCONF Network Discovery and UIM Intgeration cartridge is provided along with the cartridge. This model is generated from the YANG files used in the cartridge.

This RESTCONF YANG model is generated from the Apache Maven project yang_sources_generator. This project can also be used to generate Java classes from YANG files of discovered devices. It is provided along with the RESTCONF YANG model in the cartridge.

The project hierarchy is as shown below:

yang_sources_generator
    yangs-restconf
      src/main/Restconf-yang
      pom.xml
   yangs-restconf
        generic
            pom.xml
        vendor
            pom.xml
     pom.xml
pom.xml

To generate Java classes for other YANG files:

1. Provide the required YANG files from the discovered devices along with all the dependent YANG files in yang_sources_generator/yangs-restconf/generic/genric_yangs folder (for vendor, use the appropriate vendor folder).
2. Run the command mvn clean install in the yang_sources_generator/yangs-restconf/generic directory.

   Running this command generates the updated yang-generic-model-generator-8.0.0.jar file in the yang_sources_generator/yangs-restconf/generic/target directory. In the case of other vendor devices, an updated vendor JAR file is generated in the yang_sources_generator/yangs-restconf/vendor/target directory.

Opening Cartridge Files in Design Studio

To use the RESTCONF Network Discovery and UIM Integration cartridge, you must first download the Oracle Communications RESTCONF Network Discovery and UIM Integration cartridge software from the Oracle software delivery web site:

https://edelivery.oracle.com

The software contains the cartridge ZIP file, which contains the following:

• UIM_Cartridge_Projects

• Network_Integrity_Cartridge_Projects

• Address_Handlers.iar

• Restconf_Network_Discovery_Cartridge.iar

For more information about opening files in Design Studio, see Design Studio Modeling Network Integrity in and Network Integrity Developer's Guide.

Building and Deploying the Cartridge

See Design Studio Modeling Network Integrity for information about building and deploying cartridges.