Introduction to NETCONF and Juniper YANG Models

(UPDATE: Part two is out now! Click here to navigate to part two)

WHAT IS NETCONF?

We'll start this post off with a quick crash course. What is NETCONF and how does it work under the hood?

NETCONF is a protocol that was developed to provide a standardized interface to Network Devices to retrieve and manipulate configuration data.

If you're familiar with the CLI (Command Line Interface) then this definition will strike you as nothing new. And you wouldn't be wrong - the ultimate objective of both NETCONF and CLI is to provide an interface for configuration. The primary difference between the two interfaces is that they are both designed and optimised for very different applications and purposes.

The CLI aims to provide humans with a very user-friendly means for interacting with a device. Commands are very readable, easy to remember and have no painful syntactic requirements.

NETCONF, on the other hand, was designed for automation applications. It uses a clearly defined XML API that computer programs may interface to with ease. The NETCONF protocol may be broken down into four distinct layers as illustrated in the diagram below.

Figure 1: NETCONF Protocol Layers

Let's take a brief look at each of the layers from the ground-up.

• Secure Transport - The Secure Transport layer provides, as the name suggests, the means of transport for NETCONF transactions between peers. The core conformity requirements for the transport layer is that it provides a persistent connection, replay protection, authentication and encryption. Two protocols commonly used to carry NETCONF messages are SSH and TLS.

  We'll be using NETCONF-over-SSH later in this post.

• Messages - The Messages layer provides a well-defined, transport-independent framing mechanism for encoding NETCONF messages. The element name in the Messages layer will describe the message type and will be one of the values shown below.

  • <rpc> - An RPC is a Remote Procedure Call.
  • <rpc-reply>
  • <notification> - This blog post will not discuss the Notification message type. To learn about this message type feel free to check out RFC5277

• Operations - The Operations layer describes the protocol operation invoked and is encapsulated inside the XML message element. A set of base protocol operations exist. Furthermore, clients and servers may extend the base set of protocol operations to allow for a high-level of customization. All operations supported by a client and server are reported to each other at the establishment of a NETCONF session via a capability exchange. The set of base protocol operations is provided below.

  • <get>
  • <get-config>
  • <edit-config>
  • <copy-config>
  • <delete-config>
  • <lock>
  • <unlock>
  • <close-session>
  • <kill-session>

• Content - The Content layer consists of XML data encapsulated inside the protocol operation element.

  The NETCONF protocol does not standardize the data inside the Content layer. Instead, NETCONF data models may be designed by anyone using the YANG Data Modeling Language which standardizes the model structure.

  Network device manufacturers implementing the NETCONF interface on their hardware will need to embed YANG data models into their software. These YANG data models may be developed by the manufacturer themselves or they may conform to an open-source specification such as OpenConfig.

ENABLE THE NETCONF INTERFACE

With the NETCONF crash course now out of the way let's get started and enable NETCONF on a junos router. All examples shown in this tutorial series will use a virtual SRX but any junos based device will exhibit close to identical behaviour.

Enabling NETCONF on a junos device is straightforward and only requires one line of configuration. The command below will enable NETCONF-over-SSH on port 830.

set system services netconf ssh

To add this line of configuration to your device simply connect to a CLI session with your device, enter configuration mode and commit this line of configuration. An example output is shown below.

user@vSRX> configure
Entering configuration mode

[edit]
user@vSRX# set system services netconf ssh

[edit]
user@vSRX# commit and-quit
commit complete
Exiting configuration mode

ESTABLISH A NETCONF SESSION

With NETCONF now enabled we may establish a NETCONF-over-SSH session with our device. To do so log on to a terminal with an SSH client and run the command below.

ssh <YOUR-USERNAME>@<IP-ADDRESS-OF-DEVICE> -p 830 -s netconf

If you are unable to login successfully ensure that:

• Security zones are configured correctly (if applicable)
• There are no firewalls between you and your device blocking port 830

A successful connection establishment is shown below.

[user@centos-server ~]# ssh user@192.168.1.94 -p 830 -s netconf
Password:
<!-- No zombies were killed during the creation of this user interface -->
<!-- user root, class super-user -->
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <capabilities>
    <capability>urn:ietf:params:netconf:base:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:candidate:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:confirmed-commit:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:validate:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file</capability>
    <capability>urn:ietf:params:xml:ns:netconf:base:1.0</capability>
    <capability>urn:ietf:params:xml:ns:netconf:capability:candidate:1.0</capability>
    <capability>urn:ietf:params:xml:ns:netconf:capability:confirmed-commit:1.0</capability>
    <capability>urn:ietf:params:xml:ns:netconf:capability:validate:1.0</capability>
    <capability>urn:ietf:params:xml:ns:netconf:capability:url:1.0?protocol=http,ftp,file</capability>
    <capability>http://xml.juniper.net/netconf/junos/1.0</capability>
    <capability>http://xml.juniper.net/dmi/system/1.0</capability>
  </capabilities>
  <session-id>3275</session-id>
</hello>
]]>]]>

Upon connection, a <hello> element is immediately received. This element conforms to RFC6241 and describes the NETCONF capabilities of the device.

Notice the base 1.0 capability included which was discussed earlier in the Operation layer overview of NETCONF. We can also see other interesting capabilities such as the devices ability to accept a configuration file and capabilities written by Juniper themselves.

JUNIPER OPERATIONAL YANG MODELS

The majority of Juniper YANG models fall into two categories - models for junos operational commands and models for the junos configuration hierarchy.

Let's take a look at the junos operational command show arp. We'll use this command as an example for getting started with Juniper YANG models. First, let's remind ourselves of a CLI example of this command.

user@vSRX> show arp
MAC Address       Address         Name                      Interface               Flags
fe:00:00:00:00:04 128.0.0.16      128.0.0.16                em0.0                   none
aa:bb:cc:dd:ee:ff 192.168.1.1     192.168.1.1               em1.32768               none
4c:cc:6a:d7:3d:f8 192.168.1.23    192.168.1.23              ge-0/0/0.0              none
Total entries: 3

To execute this command via NETCONF we'll first need to locate the Juniper YANG model for operational ARP commands. This can be done in a few different ways.

One method would be to type in show system schema module ? via the CLI and identify the relevant YANG module. Junos operational commands will be defined in YANG models including "rpc" in the filename while the junos configuration hierarchy will be defined in YANG models which include "conf" in the filename.

For this tutorial, we'll locate the relevant model via the Juniper YANG repository. The YANG model of interest to us is called junos-es-rpc-arp.yang

The specific area of interest in the YANG model is provided below.

rpc get-arp-table-information {
     description "Show system Address Resolution Protocol table entries";
     input {
       uses command-forwarding;
       leaf hostname {
         description "Name of host";
         type string;
       }
       leaf interface {
         description "Name of the interface";
         type string;
       }
       ...

We can see from the YANG model that the name of the RPC method we would like to invoke in the operational layer of our NETCONF request is called get-arp-table-information.

How to send an operational command using NETCONF

We'll now proceed to invoke the NETCONF request by wrapping the operational command in an RPC message as shown below. You will also notice that the message is immediately followed by the string "]]>]]>" which is the NETCONF message separator sequence. All NETCONF messages will end in this sequence.

<rpc>
   <get-arp-table-information/>
</rpc>
]]>]]>

After pasting the code block above to our NETCONF session we received the response below. Notice that all of the information from our CLI output is present in the RPC response.

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/15.1X49/junos">
  <arp-table-information xmlns="http://xml.juniper.net/junos/15.1X49/junos-arp" junos:style="normal">
    <arp-table-entry>
      <mac-address>fe:00:00:00:00:04</mac-address>
      <ip-address>128.0.0.16</ip-address>
      <hostname>128.0.0.16</hostname>
      <interface-name>em0.0</interface-name>
      <arp-table-entry-flags>
        <none />
      </arp-table-entry-flags>
    </arp-table-entry>
    <arp-table-entry>
      <mac-address>aa:bb:cc:dd:ee:ff</mac-address>
      <ip-address>192.168.1.1</ip-address>
      <hostname>192.168.1.1</hostname>
      <interface-name>em1.32768</interface-name>
      <arp-table-entry-flags>
        <none />
      </arp-table-entry-flags>
    </arp-table-entry>
    <arp-table-entry>
      <mac-address>4c:cc:6a:d7:3d:f8</mac-address>
      <ip-address>192.168.1.23</ip-address>
      <hostname>192.168.1.23</hostname>
      <interface-name>ge-0/0/0.0</interface-name>
      <arp-table-entry-flags>
        <none />
      </arp-table-entry-flags>
    </arp-table-entry>
    <arp-entry-count>3</arp-entry-count>
  </arp-table-information>
</rpc-reply>

Let us now return our attention to the ARP YANG model.

There is a leaf named "interface" inside the RPC method. We may use this leaf as a parameter in our RPC request to limit the returned results to ARP entries with a specific interface only. This parameter shows the use of the content layer in the NETCONF protocol stack.

<rpc>
   <get-arp-table-information>
      <interface>ge-0/0/0.0</interface>
   </get-arp-table-information>
</rpc>
]]>]]>

We'll now receive a subset of the original ARP entry list returned. The RPC reply to our device is shown below.

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/15.1X49/junos">
  <arp-table-information xmlns="http://xml.juniper.net/junos/15.1X49/junos-arp" junos:style="normal">
    <arp-table-entry>
      <mac-address>4c:cc:6a:d7:3d:f8</mac-address>
      <ip-address>192.168.1.23</ip-address>
      <hostname>192.168.1.23</hostname>
      <interface-name>ge-0/0/0.0</interface-name>
      <arp-table-entry-flags>
        <none />
      </arp-table-entry-flags>
    </arp-table-entry>
  </arp-table-information>
</rpc-reply>
]]>]]>

Hopefully, these examples have been a good introduction to the NETCONF protocol and given you enough direction to get started using Juniper operational YANG models with NETCONF.

(UPDATE: Part two is out now! Click here to navigate to part two)

If you have any questions, feel free to leave a comment beneath the post and we'll do our best to help.

Ultra Config Generator

If you work for a business in the telecommunications industry, I would highly recommend you check out Ultra Config Generator. We designed the product to allow network engineers to generate and automate network configuration in a highly flexible, efficient and elegant manner.

Our users love the application and I hope that you will too.

WHAT'S NEXT?

Now that we have introduced NETCONF and YANG models we can delve deeper in our next post. The attention of our next post will focus on how to configure Juniper devices via NETCONF as opposed to only operational commands.

Take care until next time!

Ultra Config