Documentation of translation units in FRINX ODL
Switch branches/tags
Clone or download
Latest commit 708f602 Dec 12, 2018

README.md

Translation Units for the FRINX ODL CLI service module

This repository contains documentation for all available translation units for the FRINX ODL CLI service module. A translation unit is a piece of code that includes handlers to read from or write to a specific device (e.g. Cisco IOS classic router) and facilitates the translation in OpenConfig models. The purpose of this documentation is to see which commands can be read and set and how they map to the respective YANG models. Every section has a README file that provides an overview of all show and configuration commands that are supported. Multiple translation units are finally packaged together and made available as a karaf feature that can be installed at runtime.

Table of Contents

URL

Each URL has a base format:

http://localhost:8181/restconf/operational/network-topology:network-topology/topology/<topo-name>/node/<node-id>/yang-ext:mount/
  • <topo-name> can be either cli or unified
  • <node-id> mountpoint name

The URL will always point to either operational or config datastore and to the node we want to get the information from. You can always check if the particular device is registered by issuing GET on :

http://localhost:8181/restconf/operational/network-topology:network-topology

// TODO: sample output

URLs are modular. By changing the URL you can move along the YANG data tree.

Example:

http://localhost:8181/restconf/operational/network-topology:network-topology/topology/cli/node/<node-id>/yang-ext:mount/frinx-openconfig-network-instance:network-instances/network-instance/<VRF-id>/protocols/protocol/frinx-openconfig-policy-types:OSPF/<OSPF-process-id>/ospfv2/areas/area/<area-id>/interfaces
  • very specific URL listing interfaces under one specific area in OSPF under specific VRF

Let's say you want to list all areas in a specific OSPF. To obtain this data, you can trim the part: '/area/<area-id>/interfaces' from the URL.

Let's say you want to be even more specific and list details just about one particular interface. You can view the data by adding 'interface/<interface-id>' to the URL.

The general steps in creating the URL are following:

  1. for each container or list in YANG model, there MUST be an argument in the URL
  2. each list item argument MUST be followed by list key. Usually the key is mapped to just one leaf (identifier, name, etc.), but in some cases, the key is created using more leafs. In this case, in the URL, the keys follow each other in order specified by YANG.
  3. the top level argument must contain the name of the model. The name of the model must also be specified for YANG identities.
  4. if the URL is tied with a body, the top-level element in the body must be the last element in the URL

Example:

http://localhost:8181/restconf/operational/network-topology:network-topology/topology/cli/node/<node-id>/yang-ext:mount/frinx-openconfig-network-instance:network-instances/network-instance/<VRF-id>/protocols/protocol/frinx-openconfig-policy-types:OSPF/<OSPF-process-id>/ospfv2/areas/area/<area-id>/interfaces
  • top-level argument contains also YANG model name: ‘frinx-openconfig-network-instance’
  • network-instances argument is a list. We want to specify one item from that list (specific network instance), therefore the URL continues with ‘network-instance'. The key in network-instance is the identifier '' (e.g. vrf1) which follows the list item argument. Complex key is needed for protocol argument. The key is protocol-type followed by process-id. (frinx-openconfig-policy-types:OSPF/ )
  • same for 'area/'
  • the URL contains an identity which is a part of a key for protocol list. This identity is prefixed by model name: ‘frinx-openconfig-policy-types:OSPF’

You can create a minimalistic YANG tree out of the URL:

frinx-openconfig-network-instances: {                 // top-level container
    network-instance: [                         // list
        {                                       // list-item start
            key: <VRF-id>                     // list key
            protocols: {
                protocol: [
                    {
                        key: "frinx-openconfig-policy-types:OSPF <OSPF-process-id>"
                        ospfv2: {
                            areas: {
                                area: [
                                    {
                                        key: <area-id>
                                        interfaces {
                                           ...
                                        }
                                    }
                                ]
                            }
                        }
                    }                           // list-item end
                ]
            }
        }
    ]
}

URL Operations

Each show command supports only one http operation: GET .

GET

GET operation can be issued on both config/operational datastore. Config datastore reflects how the device is configured. Operational datastore reflects the state of the device. In most cases the information is the same.

(// TODO: example where it's not, static routes? )

Configuration commands support PUT for create/replace data. This operation requires HTTP body, which contains openconfig YANG model of the configuration you want to send to the router. Another operation supported by configuration commands is DELETE, which removes data from the device. Both operations need to be issued on config datastore.

// TODO: try-out merge https://frinxhelpdesk.atlassian.net/browse/SBHD2-21?jql=text%20~%20%22patch%22 if it works, describe it here.

Example:

We want to create a new BGP neighbor:

The IOS command is:

router bgp <as>
 neighbor <neighbor-address>
   no shutdown

PUT

http://localhost:8181/restconf/config/network-topology:network-topology/topology/cli/node/<node-id>/yang-ext:mount/frinx-openconfig-network-instance:network-instances/network-instance/<ni-name>/protocols/protocol/frinx-openconfig-bgp:bgp

BODY:

{
    "bgp": {
        "global": {
            "config": {
                "as": <as>
            }
        }
        "neighbors": {
            "neighbor": [
                {
                    "config": {
                        "neighbor-address": <neighbor-address>
                        "enabled": true
                    }
                }
            ]
        }
    }
}

// TODO: delete if merge operation is working

WARNING: PUT operation does not merge data. In this example if you have already configured some BGP neighbors, this request will REMOVE all of them and create just the one described in the PUT body. The solution is to first issue GET, copy existing configuration and add/change items there.

If we want to DELETE a BGP neighbor, the body is not needed, the URL needs to be specific to the neighbor we want to delete:

DELETE

http://localhost:8181/restconf/config/network-topology:network-topology/topology/cli/node/<node-id>/yang-ext:mount/frinx-openconfig-network-instance:network-instances/network-instance/<ni-name>/protocols/protocol/frinx-openconfig-bgp:bgp/neighbors/neighbor/<neighbor-address>

This operation will issue following command:

router bgp <as>
 no neighbor <neighbor-address>

DELETE operation always removes the last argument of the URL.

OPERATIONAL datasets

go to operational datasets

Show commands are commands that usually on Cisco device start with 'show'. The aim is to obtain data from the router.

URL

GET operation issued on operational datastore

OPENCONFIG YANG

In case of show commands this section is a sample output of a particular show command.

OS COMMANDS

In this section we list the actual router commands with sample outputs, where the data obtained and transformed into Openconfig YANG is marked as bold. We list show commands and outputs for each supported device OS.

IOS XR | IOS Classic/XE | Junos

DEVICE YANG

In case of CLI units, the unit parses the output of the CLI command directly into OC YANG. In case of Netconf units, the output is mapped to OC YANG through Device YANG (YANG model supported by the device). In case of Netconf units, the YANG is also written in documentation. This section is a link to XML unit test input testing this operation.

UNIT

Link to github code where this show commmand is implemented along with unit version range.

CONFIGURATION datasets

go to configuration datasets

URL

PUT operation with given URL will result in creating of data in config datastore DELETE operation with given URL will result in removing data in config datastore

OPENCONFIG YANG

In case of configuration commands, this section represents the HTTP body in PUT operation

OS COMMANDS

In this section we list the actual router commands that are mapped to the Openconfig YANG model. Data transformed into Openconfig YANG is marked as bold. We list commands for each supported device OS.

IOS XR | IOS Classic/XE | Junos

DEVICE YANG

In case od Netconf units, the device yang represents command sent to the device in device YANG model. This section is a link to XML unit test input testing this configuration.

UNIT

Link to github code where this config commmand is implemented along with unit version range.