Yang Data Model, Netconf, Restconf

Yang Data Model

- Yang Fundamentals

Restconf

RESTCONF according to RFC 8040 section 4:
- GET: Retrieve existing configuration
- POST: Create new configuration
- PATCH: Merge configuration
- PUT: Replace existing configuration
- DELETE: Remove configuration
For PUT and PATCH operations, the last URL path segment (the string after the very last slash) must match to the top-level item key.
For POST operations, the last URL path segment (the string after the very last slash) must correspond to the parent of the top-level item.
For example, if you want to retrieve the configuration of interfaces in a Cisco device using a simple HTTP GET request, the request will be performed with a GET request on the following URI:

GET https://<device-ip>/restconf/data/ietf-interfaces:interfaces

If you want to modify an interface configuration, the request will be performed with a PATCH request:

PATCH https://<device-ip>/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1
Content-Type: application/yang-data+json

{
  "ietf-interfaces:interface": {
    "description": "Updated by RESTCONF"
  }
}

Using Restconf with python

import requests
from requests.auth import HTTPBasicAuth

# Device and API details
url = "https://<device-ip>/restconf/data/ietf-interfaces:interfaces"
headers = {
    "Accept": "application/yang-data+json",
    "Content-Type": "application/yang-data+json"
}
# Authentication credentials
auth = HTTPBasicAuth('admin', 'password')

# Sending a GET request to retrieve interface data
response = requests.get(url, headers=headers, auth=auth, verify=False)

# Print the response in JSON format
print(response.json())

Restconf list element operations

NETCONF

Defined by the original RFC 6241
The key features of NETCONF are the following:
- Transactional Configuration: Ensures that configuration changes are atomic (all or nothing) and rollback is possible if something goes wrong.
- Retrieve and Set Configurations: Can retrieve and modify configuration data from devices using a standard structure.
- Extensibility with YANG Models: NETCONF operates alongside YANG, a data modeling language, to describe device configurations and state data.
- Secure Communication: Operates over SSH, ensuring encrypted communication with devices.
The NETCONF protocol operates on four distinct layers. In the most common cases, all four layers are present in every session.
Layer 1, Transport: provides a communication path between the client (your automation platform) and server (the network device). For Cisco devices this is always - an SSH connection on TCP port 830
Layer 2, Message: An XML document with an element of the type , , or .
Layer 3, Operations: One or more XML elements that specifies the desired operation like , or
Layer 4, Content: The configuration or operational data expressed as XML. Examples could be a new IP address to be configured or the interface byte counters to be - read. For each vendor and device type there are different data models to chose from. These are called YANG models, and describes the available configuration features for the specific platform.
Using Python ncclient module

# pip install ncclient
from ncclient import manager

# Connect to the NETCONF server on a Cisco device
with manager.connect(host="192.168.1.1", port=830, username="admin", password="cisco", hostkey_verify=False) as m:
    # Retrieve and print the running configuration
    config = m.get_config(source="running").data_xml
    print(config)

To modify configuration

from ncclient import manager

# Define the XML configuration to be applied
config_data = """
<config>
  <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
    <interfaces>
      <interface>
        <GigabitEthernet>
          <name>1</name>
          <description>Updated by NETCONF</description>
          <address>10.0.0.21</address>
          <enabled>true</enabled>
        </GigabitEthernet>
      </interface>
    </interfaces>
  </native>
</config>
"""

with manager.connect(host="192.168.1.1", port=830, username="admin", password="cisco", hostkey_verify=False) as m:
    # Apply the configuration change
    m.edit_config(target="running", config=config_data)
    print("Configuration updated.")

# If device support candidate configuration such as IOS XR, sumibt configuration by

# Edit candidate configuration first
m.edit_config(target="candidate", config=config_data)

# Commit the candidate configuration
m.commit()

Netconf Anatomy

Pyang

Some commands

pyang -f tree $path-to-yang-file
pyang -f tree $path-to-yang-file $path-to-yang-file
pyang -f sampleyang -f sample-xml-skeleton --sample-xml-skeleton-defaults -o output.xml 'ietf-inerfaces.yang' 'ietf-ip.yang': build payload with xml format, save output to output.xml

How to get the path for restconf request

Checking Yang model for IETF interface

pyang -f tree yang-main/vendor/cisco/xe/16121/ietf-interfaces.yang

yang-main/vendor/cisco/xe/16121/ietf-interfaces.yang:6: error: module "ietf-yang-types" not found in search path
module: ietf-interfaces
  +--rw interfaces
  |  +--rw interface* [name]
  |     +--rw name                        string
  |     +--rw description?                string
  |     +--rw type                        identityref
  |     +--rw enabled?                    boolean
  |     +--rw link-up-down-trap-enable?   enumeration {if-mib}?
  +--ro interfaces-state
     +--ro interface* [name]
        +--ro name               string
        +--ro type               identityref
        +--ro admin-status       enumeration {if-mib}?
        +--ro oper-status        enumeration
        +--ro last-change?       yang:date-and-time
        +--ro if-index           int32 {if-mib}?
        +--ro phys-address?      yang:phys-address
        +--ro higher-layer-if*   interface-state-ref
        +--ro lower-layer-if*    interface-state-ref
        +--ro speed?             yang:gauge64
        +--ro statistics
           +--ro discontinuity-time    yang:date-and-time
           +--ro in-octets?            yang:counter64
           +--ro in-unicast-pkts?      yang:counter64
           +--ro in-broadcast-pkts?    yang:counter64
           +--ro in-multicast-pkts?    yang:counter64
           +--ro in-discards?          yang:counter32
           +--ro in-errors?            yang:counter32
           +--ro in-unknown-protos?    yang:counter32
           +--ro out-octets?           yang:counter64
           +--ro out-unicast-pkts?     yang:counter64
           +--ro out-broadcast-pkts?   yang:counter64
           +--ro out-multicast-pkts?   yang:counter64
           +--ro out-discards?         yang:counter32
           +--ro out-errors?           yang:counter32

Checking interface

According to above model, the url is: - https://10.10.10.10/restconf/data/ietf-interfaces:interfaces
Response:

{
  "ietf-interfaces:interface": [
    {
      "name": "GigabitEthernet0",
      "type": "iana-if-type:ethernetCsmacd",
      "enabled": true,
      "ietf-ip:ipv4": {
        "address": [
          {
            "ip": "10.10.10.10",
            "netmask": "255.255.255.240"
          }
        ]
      },
      "ietf-ip:ipv6": {
      }
    }
  ]
}

Specific interface: https://10.10.10.10/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet0
Response:

{
  "ietf-ip:ipv4": {
    "address": [
      {
        "ip": "10.10.10.10",
        "netmask": "255.255.255.240"
      }
    ]
  }
}

Get address only: https://10.10.10.10/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet0/ietf-ip:ipv4/address
Response:

{
  "ietf-ip:address": [
    {
      "ip": "10.10.10.10",
      "netmask": "255.255.255.240"
    }
  ]
}

Checking interfaces-state

https://10.10.10.10/restconf/data/ietf-interfaces:interfaces-state
https://10.10.10.10/restconf/data/ietf-interfaces:interfaces-state/interface=GigabitEthernet0 (Yang model: +--ro interface* [name])
https://10.10.10.10/restconf/data/ietf-interfaces:interfaces-state/interface=GigabitEthernet0/admin-status

Checking Yang Model for Native interface

pyang -f tree yang-main/vendor/cisco/xe/16121/Cisco-IOS-XE-interfaces-oper.yang

yang-main/vendor/cisco/xe/16121/Cisco-IOS-XE-interfaces-oper.yang:6: error: module "ietf-inet-types" not found in search path
yang-main/vendor/cisco/xe/16121/Cisco-IOS-XE-interfaces-oper.yang:9: error: module "ietf-yang-types" not found in search path
yang-main/vendor/cisco/xe/16121/Cisco-IOS-XE-interfaces-oper.yang:12: error: module "cisco-semver" not found in search path
module: Cisco-IOS-XE-interfaces-oper
  +--ro interfaces
     +--ro interface* [name]
        +--ro name                            string
        +--ro interface-type?                 interfaces-ios-xe-oper:ietf-intf-type
        +--ro admin-status?                   interfaces-ios-xe-oper:intf-state
        +--ro oper-status?                    interfaces-ios-xe-oper:oper-state
        +--ro last-change?                    yang:date-and-time
        +--ro if-index?                       int32
        +--ro phys-address?                   yang:mac-address
        +--ro higher-layer-if*                string
        +--ro lower-layer-if*                 string
        +--ro speed?                          uint64
        +--ro statistics
        |  +--ro discontinuity-time?   yang:date-and-time
        |  +--ro in-octets?            uint64
        |  +--ro in-unicast-pkts?      uint64
        |  +--ro in-broadcast-pkts?    uint64
        |  +--ro in-multicast-pkts?    uint64
        |  +--ro in-discards?          uint32
<removed>

Checking specific interface

https://10.10.10.10/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet
Response:

{
  "Cisco-IOS-XE-native:GigabitEthernet": [
    {
      "name": "0",
      "switchport": {
        "Cisco-IOS-XE-switch:trunk": {
          "native": {
            "vlan-config": {
              "tag": true
            }
          }
        }
      },
      "vrf": {
        "forwarding": "Mgmt-intf"
      },
      "ip": {
        "address": {
          "primary": {
            "address": "10.10.10.10",
            "mask": "255.255.255.240"
          }
        }
      },
      "logging": {
        "event": {
          "link-status": [null]
        }
      },
      "access-session": {
        "host-mode": "multi-auth"
      },
      "Cisco-IOS-XE-cdp:cdp": {
        "tlv": {
          "app-config": {
            "app": true
          },
          "app": {
          },
          "server-location": [null],
          "location": [null]
        }
      },
      "Cisco-IOS-XE-ethernet:negotiation": {
        "auto": true
      }
    },
    {
      "name": "0/0/0",
      "switchport": {
        "Cisco-IOS-XE-switch:trunk": {
          "native": {
            "vlan-config": {
              "tag": true
            }
          }
        }
      },
      "ip": {
        "address": {
          "primary": {
            "address": "3.3.3.4",
            "mask": "255.255.255.0"
          }
        }
      },
      "logging": {
        "event": {
          "link-status": [null]
        }
      },
      "access-session": {
        "host-mode": "multi-auth"
      },
      "Cisco-IOS-XE-cdp:cdp": {
        "tlv": {
          "app-config": {
            "app": true
          },
          "app": {
          },
          "server-location": [null],
          "location": [null]
        }
      },
      "Cisco-IOS-XE-ethernet:negotiation": {
        "auto": true
      }
    },
    {
      "name": "0/0/1",
      "switchport": {
        "Cisco-IOS-XE-switch:trunk": {
          "native": {
            "vlan-config": {
              "tag": true
            }
          }
        }
      },
      "ip": {
        "address": {
          "primary": {
            "address": "8.8.8.9",
            "mask": "255.255.255.0"
          }
        }
      },
      "logging": {
        "event": {
          "link-status": [null]
        }
      },
      "access-session": {
        "host-mode": "multi-auth"
      },
      "Cisco-IOS-XE-cdp:cdp": {
        "tlv": {
          "app-config": {
            "app": true
          },
          "app": {
          },
          "server-location": [null],
          "location": [null]
        }
      },
      "Cisco-IOS-XE-ethernet:negotiation": {
        "auto": true
      }
    },
    {
      "name": "0/0/2",
      "switchport": {
        "Cisco-IOS-XE-switch:trunk": {
          "native": {
            "vlan-config": {
              "tag": true
            }
          }
        }
      },
      "shutdown": [null],
      "logging": {
        "event": {
          "link-status": [null]
        }
      },
      "access-session": {
        "host-mode": "multi-auth"
      },
      "Cisco-IOS-XE-cdp:cdp": {
        "tlv": {
          "app-config": {
            "app": true
          },
          "app": {
          },
          "server-location": [null],
          "location": [null]
        }
      },
      "Cisco-IOS-XE-ethernet:negotiation": {
        "auto": true
      }
    }
  ]
}

Checking IETF Routing Model

pyang -f tree yang-main/vendor/cisco/xe/16121/ietf-routing.yang

module: ietf-routing
  +--ro routing-state
  |  +--ro routing-instance* [name]
  |     +--ro name                 string
  |     +--ro type?                identityref
  |     +--ro router-id?           yang:dotted-quad
  |     +--ro interfaces
  |     |  +--ro interface*   if:interface-state-ref
  |     +--ro routing-protocols
  |     |  +--ro routing-protocol* [type name]
  |     |     +--ro type    identityref
  |     |     +--ro name    string
  |     +--ro ribs
  |        +--ro rib* [name]
  |           +--ro name              string
  |           +--ro address-family    identityref
  |           +--ro default-rib?      boolean {multiple-ribs}?
  |           +--ro routes
  |              +--ro route* [destination-prefix]
  |                 +--ro route-preference?     route-preference
  |                 +--ro destination-prefix    string
  |                 +--ro metric?               uint32
  |                 +--ro next-hop
  |                 |  +--ro (next-hop-options)
  |                 |     +--:(simple-next-hop)
  |                 |     |  +--ro outgoing-interface?   string
  |                 |     |  +--ro next-hop-address?     string
  |                 |     +--:(special-next-hop)
  |                 |        +--ro special-next-hop?     enumeration
  |                 +--ro source-protocol       identityref
  |                 +--ro active?               empty
  |                 +--ro last-updated?         yang:date-and-time
  |                 +--ro update-source?        string
  +--rw routing
     +--rw routing-instance* [name]
        +--rw name                 string
        +--rw type?                identityref
        +--rw enabled?             boolean
        +--rw router-id?           yang:dotted-quad {router-id}?
        +--rw description?         string
        +--rw interfaces
        |  +--rw interface*   if:interface-ref
        +--rw routing-protocols
        |  +--rw routing-protocol* [type name]
        |     +--rw type             identityref
        |     +--rw name             string
        |     +--rw description?     string
        |     +--rw static-routes
        +--rw ribs
           +--rw rib* [name]
              +--rw name              string
              +--rw address-family?   identityref
              +--rw description?      string

  rpcs:
    +---x fib-route
       +---w input
       |  +---w routing-instance-name    string
       |  +---w destination-address
       |     +---w address-family    identityref
       +--ro output
          +--ro route
             +--ro address-family     identityref
             +--ro next-hop
             |  +--ro (next-hop-options)
             |     +--:(simple-next-hop)
             |     |  +--ro outgoing-interface?   string
             |     |  +--ro next-hop-address?     string
             |     +--:(special-next-hop)
             |        +--ro special-next-hop?     enumeration
             +--ro source-protocol    identityref
             +--ro active?            empty

Some URL

https://10.10.10.10/restconf/data/ietf-routing:routing
https://10.10.10.10/restconf/data/ietf-routing:routing/routing-instance=Mgmt-intf
https://10.10.10.10/restconf/data/ietf-routing:routing/routing-instance=Mgmt-intf/routing-protocols
https://10.10.10.10/restconf/data/ietf-routing:routing/routing-instance=Mgmt-intf/routing-protocols/routing-protocol
https://10.10.10.10/restconf/data/ietf-routing:routing/routing-instance=default
https://10.10.10.10/restconf/data/ietf-routing:routing-state/routing-instance=default/routing-protocols/routing-protocol
Response

{
  "ietf-routing:routing-protocol": [
    {
      "type": "ietf-routing:direct",
      "name": "0"
    },
    {
      "type": "ietf-routing:static",
      "name": "0"
    }
  ]
}

https://10.10.10.10/restconf/data/ietf-routing:routing-state/routing-instance=default/routing-protocols/routing-protocol=ietf-routing:static,0
Response

{
  "ietf-routing:routing-protocol": [
    {
      "type": "ietf-routing:static",
      "name": "0"
    }
  ]
}

https://10.10.10.10/restconf/data/ietf-routing:routing-state/routing-instance=default/ribs
Response:

{
  "ietf-routing:ribs": {
    "rib": [
      {
        "name": "ipv4-default",
        "address-family": "ietf-routing:ipv4",
        "default-rib": false,
        "routes": {
          "route": [
            {
              "destination-prefix": "3.3.3.0/24",
              "route-preference": 0,
              "metric": 0,
              "next-hop": {
                "outgoing-interface": "GigabitEthernet0/0/0",
                "next-hop-address": "0.0.0.0"
              },
              "source-protocol": "ietf-routing:direct",
              "active": [null]
            },
            {
              "destination-prefix": "3.3.3.4/32",
              "route-preference": 0,
              "metric": 0,
              "next-hop": {
                "outgoing-interface": "GigabitEthernet0/0/0",
                "next-hop-address": "0.0.0.0"
              },
              "source-protocol": "ietf-routing:direct",
              "active": [null]
            },
            {
              "destination-prefix": "8.8.8.0/24",
              "route-preference": 0,
              "metric": 0,
              "next-hop": {
                "outgoing-interface": "GigabitEthernet0/0/1",
                "next-hop-address": "0.0.0.0"
              },
              "source-protocol": "ietf-routing:direct",
              "active": [null]
            },
            {
              "destination-prefix": "8.8.8.9/32",
              "route-preference": 0,
              "metric": 0,
              "next-hop": {
                "outgoing-interface": "GigabitEthernet0/0/1",
                "next-hop-address": "0.0.0.0"
              },
              "source-protocol": "ietf-routing:direct",
              "active": [null]
            },
            {
              "destination-prefix": "10.1.1.0/24",
              "route-preference": 0,
              "metric": 0,
              "next-hop": {
                "outgoing-interface": "Loopback0",
                "next-hop-address": "0.0.0.0"
              },
              "source-protocol": "ietf-routing:direct",
              "active": [null]
            },
            {
              "destination-prefix": "10.1.1.1/32",
              "route-preference": 0,
              "metric": 0,
              "next-hop": {
                "outgoing-interface": "Loopback0",
                "next-hop-address": "0.0.0.0"
              },
              "source-protocol": "ietf-routing:direct",
              "active": [null]
            }
          ]
        }
      },
      {
        "name": "ipv6-default",
        "address-family": "ietf-routing:ipv6",
        "default-rib": false,
        "routes": {
          "route": [
            {
              "destination-prefix": "ff00::/8",
              "route-preference": 0,
              "metric": 0,
              "next-hop": {
                "outgoing-interface": "Null0",
                "next-hop-address": "::"
              },
              "source-protocol": "ietf-routing:direct",
              "active": [null]
            }
          ]
        }
      }
    ]
  }
}

Yangsuite

pip install yangsuite[core]
yangsuite: run to serve at http://localhost:8480

Configuration

Build Device Profiles
Create Yang Module Repository: Setup > Repository
- Define protocol
- Define device
- Then Get Schema list, Then select modules and download
Create Yang Set: Setup > Yang set
- Select Yang model to use
- May need to add dependent modules

Reference

Headaches from YANG Models? Using YANG Suite to Automate and Validate your Journey to Programmability - DEVNET-2628
https://www.pluralsight.com/courses/managing-cisco-networks-infrastructure-as-code
https://developer.cisco.com/learning/modules/intro-device-level-interfaces/
IOSXE on CSR Recommended Code: https://devnetsandbox.cisco.com/RM/Diagram/Index/27d9747a-db48-4565-8d44-df318fce37ad?diagramType=Topology
Deploying a Telemetry Collector on-box: https://developer.cisco.com/learning/labs/03-iosxr-05-telemetry-onbox/enabling-model-driven-telemetry-on-the-router/
gRPC grpc.io
GitHub YANG repository: https://github.com/YangModels/yang
Openconfig: https://github.com/openconfig/public
Pyang: https://github.com/mbj4668/pyang
https://www.youtube.com/playlist?list=PLOocymQm7YWaJX5l5SgfkAvHQYUS-Xr1Q
Understanding RESTCONF: https://lihaifeng.net/?p=922#Enabling_RESTCONF_on_IOS-XE
https://community.cisco.com/t5/networking-blogs/getting-started-with-netconf-yang-part-1/ba-p/3661241
https://community.cisco.com/t5/networking-blogs/getting-started-with-netconf-yang-part-2/ba-p/3660522
Getting Started with Yangsuite
https://developer.cisco.com/video/net-prog-basics/02-network_device_apis
NPB 3.2 - Goodbye SNMP hello NETCONF: https://www.youtube.com/watch?v=oywCLkoKI-k
NPB 3.3 - Learn to CRUD with GET, POST and DELETE using RESTCONF: https://www.youtube.com/watch?v=EPy4F6R9el8
NPB 3.4 - NX-API Part 1: Get started with the Native Nexus API: https://www.youtube.com/watch?v=orJ0zE7KWY0
NPB 3.5 - NX-API Part 2: Dive into the Nexus Object Model: https://www.youtube.com/watch?v=TEke1l0XhGI
Dear Hank… Help Me with RESTCONF URL Creation (cisco.com): https://blogs.cisco.com/developer/restconf-url-creation
RESTCONF operations (devnetexperttraining.com): https://www.devnetexperttraining.com/articles/restconf-operations
RESTCONF with Python - Technology Blog Wim (wimwauters.com): https://blog.wimwauters.com/networkprogrammability/2020-04-04_restconf_python/
Security Comparison Between NETCONF, RESTCONF, and SNMP - Cisco Community: https://community.cisco.com/t5/security-knowledge-base/security-comparison-between-netconf-restconf-and-snmp/ta-p/4805483
Code:
- The OpenConfig Models supported by Open NX-OS can be downloaded from Cisco DevHub: https://devhub.cisco.com/ui/native/open-nxos-agents/
- https://github.com/DevNetSandbox/sbx_iosxe/tree/master/yang
- https://github.com/CiscoDevNet/yang-explorer
- https://github.com/wiwa1978/blog-hugo-netlify-code/blob/main/RestConf_Python/change_interfaces_cisco.py
Lab on Cisco:
- Code: https://github.com/CiscoDevNet/nxos-code
- https://github.com/CiscoDevNet/netprog_basics
- https://developer.cisco.com/learning/labs/yang_devnet-format_part1/introduction/
- https://developer.cisco.com/learning/labs/yang_devnet-format_part2/introduction/
- https://developer.cisco.com/learning/labs/yang_devnet-format_part3/introduction/

PreviousResources NextNSO

Last updated 4 months ago