Using RESTCONF for Network Automation

These days, the concept of network automation and orchestration is all the rage. Finding ways to simplify and automate network configuration processes saves a lot of time and money and, as a network administrator, puts your mind at ease.  

There are many different ways to apply automation. For Cisco devices and networks, some involve preprogrammed administration and management systems such as Cisco DNA Center or software-defined networking (SDN) solutions involving SD-WAN controllers. Depending upon your requirements, there is a multitude of different implementation methods.

In our “Scripting for Network Audit on a Cisco Device” article, we took a look at using a Python script to perform a simple network audit. In this article, we’ll look at RESTCONF and see how we can use it to apply network automation.

Remember that both the Python article and this one are geared toward those network professionals who are starting with these tools. It’s an opportunity for you to have your first experience with them, which can then be further modified and developed for the particular needs of your network.

What is RESTCONF?

To understand what RESTCONF is, let’s take a step back and define other necessary entities involved in network automation.

Dealing with the CLI

The command-line interface is excellent for us humans, but it can be a pain for computers. When we use commands, we see the results and interpret what must happen next, but network automation devices don’t have this intuitive capability. That’s why we need predefined data formats and structures for automation devices to interface correctly with the CLI. There is a variety of such data structures, including what is known as YANG.

Defining terms

YANG stands for Yet Another Next Generation, a data modelling language for defining data sent over network management protocols. It is essentially a modular language that represents data structures in an XML tree format. The current YANG standard is defined in RFC 7950.

Network Management Protocols are used to communicate between a network automation client (your PC, for example) to a network device (your Cisco router). There are various options to use here, one called Network Configuration Protocol, or NETCONF, published in late 2006. A more recent development is RESTCONF, published in RFC 8040 in 2017.

So, what is RESTCONF? Having that background information will help you understand the following important statement:

RESTCONF is an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG and using the datastore concepts defined in NETCONF.

How does RESTCONF work?

The following diagram describes how RESTCONF operates:

The network device, say a Cisco router, is enabled to run a RESTCONF server. That server communicates with the RESTCONF client—say the administrator’s PC or a computer—on the network dedicated to performing network management. 

RESTCONF commands are sent to the network device—and by exploiting the predefined datastore based on the YANG data model, the network device can be controlled and configured.

Some details about RESTCONF

Why use RESTCONF? Well, one of the reasons is that it is simple. It uses HTTP-based REST APIs, which are currently the most popular protocols used in the modern era of automation. REST stands for representational state transfer, a software architectural style created to guide the design and development of the WWW. So that’s where RESTCONF gets its name, but it also explains why it is HTTP-based.

Practically speaking, this means that the operations applied by RESTCONF are the normal operations used by HTTP, such as GET, POST, PUT, PATCH, and DELETE.

RESTCONF Operations

Because RESTCONF is based on HTTP, its operations are executed via URLs. A RESTCONF URL is composed of several components. Here’s an example of a RESTCONF URL:

https://address/root/data/yang-module:container/leaf?options

Now, what does each section do?

• Address – this is the IP address of the RESTCONF server, that is, the network device.
• Root – this is the main entry point for the RESTCONF requests. You can consider it the root directory in the sense of the RESTCONF process.
• Data – this defines the resource type as data for the RESTCONF API.
• Yang-module:container – this is the YANG data model and the container that will be used. It defines the type of command that is being implemented.
• Leaf – this is an individual element that is found within the container.
• ?options – these are optional parameters that are added and can affect the results that are returned.

All of these will become clearer when we take a look at an example. But enough background and theory, let’s get to the practical part of all of this.

How about automating a configuration process?

Network Automation using RESTCONF

So what are we going to automate? First, let’s take a look at our network topology, as well as our task list.

Network topology

For our example, we’ll be connecting to a Cisco IOS router running XE 16.6.1. This router will be connected to a Linux device that will function as the RESTCONF client. Here’s our topology diagram. Simple, eh?

In our example, we’ll be using a Linux device; however, if you want to achieve the same thing on Windows, you can always use the Windows Subsystem for Linux.

Task list

Well, let’s make a task list of what we want to achieve:

1. Enable RESTCONF on a Cisco router. Remember, this will make the router a RESTCONF server.
2. Configure the Linux device to operate as a RESTCONF client.
3. Use RESTCONF to:
   1. Retrieve interface information from the router.
   2. Configure a loopback interface on the router.

From this task list, we can see that we’ll be implementing a command to determine the current status of an entity on the device, and we’ll also be applying a change to the device by creating and configuring a loopback interface.

Configuring the router

Verify IOS version

The first thing we’ll do is go into the router and verify the IOS version being used.

My_Router#show version | include RELEASE

Cisco IOS Software [Everest], Virtual XE Software (X86_64_LINUX_IOSD-UNIVERSALK9-M), Version 16.6.1, RELEASE SOFTWARE (fc2)

We can see that we’re using IOS XE 16.6.1. We’ll need that information for configuring the RESTCONF client shortly, so we’ll make a note of that.

Enable RESTCONF

Next, we’ll need to enable RESTCONF on the device, enable the HTTPS server, and create a user with a privilege level of 15. This is done in the following commands:

My_Router#configure terminal
My_Router(config)#restconf
My_Router(config)#ip http secure-server
My_Router(config)#username routerfreak privilege 15 secret routerfreak

And that’s it for the router. Easy, wasn’t it?

Configuring the client

Now, this is where most of the magic takes place. Let’s go into our Linux device and configure the appropriate parameters.

Obtain YANG data models

We first need to obtain the YANG data modules that correspond to your version of IOS. You can find these at the YANG git repository. Next, you’ll have to find the Cisco vendor-specific folder and the appropriate platform and OS that you’re using. In that folder, you’ll find a myriad of YANG models, each one corresponding to a particular set of CLI commands.

For our purposes, we’ll be taking the IETF Interfaces YANG model for our IOS version, which contains everything we need. For viewing, this file should be downloaded and placed in local storage on the Linux device.

View the module capabilities

To view the capabilities of the module we’ve downloaded, we can use the pyang command. This is a utility that parses the YANG module and displays the capabilities in an easy-to-read format. Using the following command, we see what this module can do:

$ pyang -f tree ietf-interfaces.yang --tree-path interfaces
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}?

With this information, we can construct the URL operation that will achieve what we want.

Constructing the RESTCONF URL to retrieve interface information

For sending these commands, we’ll use a Linux utility called curl, a utility that transfers data. The command we’ll use is:

$ curl --insecure -u “routerfreak:routerfreak” https://172.16.1.1/restconf/data/ietf-interfaces:interfaces

The router will return the following:

<?xml version="1.0" encoding="UTF-8"?>
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces" xmlns:if="urn:ietf:params:xml:ns:yang:ietf-interfaces">
  <interface>
    <name>GigabitEthernet0/0</name>
    <type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
    <enabled>true</enabled>
    <ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
  	<address>
    	<ip>10.255.1.209</ip>
        <netmask>255.255.0.0</netmask>
  	</address>
    </ipv4>
    <ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip" />
  </interface>
  <interface>
    <name>GigabitEthernet0/1</name>
    <type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
    <enabled>true</enabled>
    <ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
  	<address>
    	<ip>172.16.1.1</ip>
        <netmask>255.255.255.0</netmask>
  	</address>
    </ipv4>
    <ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip" />
  </interface>
</interfaces>

This returns a list of interfaces, their names, descriptions, types, statuses, and IP address and netmask. Notice that the response format is XML style, which means that it is easily machine-readable. These are predefined formats that RESTCONF devices can read, parse, and interpret.

Let’s add some parameters:

$ curl --insecure -u “routerfreak:routerfreak” https://172.16.1.1/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet0/1

We now get the following output:

<?xml version="1.0" encoding="UTF-8"?>
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces" xmlns:if="urn:ietf:params:xml:ns:yang:ietf-interfaces">
  <interface>
    <name>GigabitEthernet0/1</name>
    <type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
    <enabled>true</enabled>
    <ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
  	<address>
    	<ip>172.16.1.1</ip>
        <netmask>255.255.255.0</netmask>
  	</address>
    </ipv4>
    <ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip" />
  </interface>
</interfaces>

In this case, only the information for the GigabitEthernet0/1 interface was returned. You can add more options to specify further what you want to be returned:

$ curl --insecure -u “routerfreak:routerfreak” https://172.16.1.1/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet0/1?fields=enabled

We now get the following output:

<?xml version="1.0" encoding="UTF-8"?>
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces" xmlns:if="urn:ietf:params:xml:ns:yang:ietf-interfaces">
  <interface>
    <enabled>true</enabled>
  </interface>
</interfaces>

Using Postman for more complex configurations

Using utilities like curl is excellent for testing out commands but not so good for actually automating tasks. It’s a good idea to use a tool like Postman, a free API development platform from Google, for this purpose. We’ll be using this to perform our last task, creating and configuring a loopback interface on the router.

Initial Postman configuration parameters

To get this working, you’ll have to adjust the following parameters on Postman:

• In the Global Settings, disable SSL certificate verification. We’ll do this just for our lab, but you should ensure that this is up and running in a production environment.

• Next, create a new HTTP Request. Go to “Create New à” and then choose “HTTP Request”.

• To connect to the router, you must configure authorization. In the Authorization tab, we’ll choose “Basic Auth” and then configure the username and password of routerfreak and routerfreak.

• Make the HTTP request a POST request.

• In the URL field, enter https://172.16.1.1/restconf/data/ietf-interfaces:interfaces
• Under the Headers tab, enter Content-Type in the key field and application/yang-data+json in the Value field.

Finally, click on the Body tab, choose the raw option, and select text, and then paste the following template:

{
  	"ietf-interfaces:interface": {
      	"name": "Loopback1",
      	"description": "CREATE_L1_RESTCONF",
      	"type": "iana-if-type:softwareLoopback",
      	"enabled": true,
      	"ietf-ip:ipv4": {
          	"address": [
              	{
                  	"ip": "7.7.7.7",
                  	"netmask": "255.255.255.0"
              	}
          	]
      	}
  	}
  }

Once all of this is done, you should be ready to click the Send button. After doing that, you should see “Status: 201 Created”. This indicates that the command was successfully sent.

Let’s verify our work by taking a look at the router:

My_Router#show running-config interface Loopback1
Building configuration...
 
Current configuration : 96 bytes
!
interface Loopback1
 description CREATE_L1_RESTCONF
 ip address 7.7.7.7 255.255.255.0
end

The loopback was successfully created.

Conclusion

This was just an introduction to how you can create processes and configurations to return information about the status of an IOS device and make changes to such a device.

Taking advantage of an HTTP URL to make these changes is indeed powerful. You can easily save your command URLs and your scripts in tools like Postman and, over time, develop an arsenal of tools, code, scripts, and URLs that will make your day-to-day network administration tasks easier and more automated.