Skip to content
Log in Sign up My account

4.6 NETCONF and RESTCONF

Blueprint 4.6: Configure and verify NETCONF and RESTCONF

  • Model-driven programmability: YANG models, datastores, encodings
  • NETCONF: transport, message layers, operations, datastores, capabilities exchange
  • RESTCONF: URI structure, HTTP methods, headers, response codes
  • Enabling and verifying both on IOS XE
  • Making a NETCONF request with SSH or Python and a RESTCONF request with curl

The verb is configure and verify. You must know the IOS XE commands that turn each protocol on, what each needs to work (AAA, a privilege 15 user, HTTPS), how to prove it is running, and what a correct request looks like.

Why model-driven programmability

CLI output is written for humans. A script that screen-scrapes show output breaks when the format changes between releases. YANG (RFC 7950) is a data modelling language that describes configuration and operational data as a structured tree. NETCONF and RESTCONF are protocols that read and write data that follows those models, so a client gets predictable, structured XML or JSON.

Model family Example module Notes
IETF standard ietf-interfaces, ietf-ip, ietf-routing Vendor-neutral, limited coverage
OpenConfig openconfig-interfaces Operator-driven, vendor-neutral
Cisco native Cisco-IOS-XE-native Covers almost the entire IOS XE configuration tree
Cisco operational Cisco-IOS-XE-interfaces-oper Read-only operational state

YANG itself is covered under 6.3 in Automation and AI. For 4.6, what matters is that both protocols carry the same YANG-modelled data.

NETCONF

NETCONF (RFC 6241) runs over SSH on TCP port 830 (RFC 6242) and encodes everything in XML.

graph TB
  C["Content: YANG-modelled data in XML"] --- O["Operations: get, get-config, edit-config, lock, commit"]
  O --- M["Messages: rpc, rpc-reply, notification"]
  M --- T["Secure transport: SSH, TCP 830"]

The session

  1. The client opens an SSH connection to port 830 and requests the netconf SSH subsystem.
  2. Both sides send a <hello> message listing their capabilities: the NETCONF base versions they support (base:1.0, base:1.1), optional features such as :candidate or :validate, and every YANG module the server supports.
  3. The client sends <rpc> messages, each with a message-id. The server answers each with an <rpc-reply> carrying the same message-id, containing <data>, <ok/> or <rpc-error>.
  4. The client ends with <close-session>.

Operations

Operation Purpose
<get> Retrieve configuration and operational state
<get-config> Retrieve configuration from a named datastore
<edit-config> Change configuration in a datastore. Each element can carry an operation attribute: merge (default), replace, create, delete, remove.
<copy-config> Replace a whole datastore with another
<delete-config> Delete a datastore (not running)
<lock> / <unlock> Prevent other sessions from changing a datastore while you work
<commit> Copy the candidate datastore to running (needs the :candidate capability)
<validate> Check a datastore's contents before committing
<close-session> / <kill-session> End your own or another session

Datastores

Datastore Meaning On IOS XE
running The active configuration Always present
startup Loaded at boot Not exposed by default; save with a cisco-ia:save-config RPC or copy run start
candidate A scratch copy you edit, validate and then commit Off by default; enable with netconf-yang feature candidate-datastore

Exam trap

NETCONF is XML only. JSON is a RESTCONF option. Any answer that says NETCONF uses JSON, HTTP or port 443 is wrong. The default port is 830, not 22.

RESTCONF

RESTCONF (RFC 8040) exposes the same YANG data as HTTP resources over HTTPS. Each node in the YANG tree has a URI, and the HTTP method says what to do with it.

URI structure

https://10.255.255.1/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1
       |  device   ||  root  ||api||   module:container      || list key value  |
  • /restconf is the API root. A client can discover it with GET /.well-known/host-meta.
  • /restconf/data is the combined configuration and operational datastore.
  • /restconf/operations lists RPCs the device supports.
  • The first node after data is qualified with its module name (module:node).
  • A list entry is selected with = and the key value. Characters such as / in a key must be URL-encoded (interface=GigabitEthernet1%2F0%2F1).

Methods and response codes

Method Action NETCONF equivalent Success code
GET Read <get> / <get-config> 200 OK
POST Create a child resource (fails if it exists) <edit-config> create 201 Created
PUT Create or replace the resource <edit-config> replace 201 Created or 204 No Content
PATCH Merge into the resource <edit-config> merge 204 No Content
DELETE Delete <edit-config> delete 204 No Content
Error code Typical RESTCONF cause
400 Bad Request Malformed JSON or XML, or the payload does not match the model
401 Unauthorized Missing or wrong credentials
403 Forbidden Authenticated, but not authorized (for example, not privilege 15)
404 Not Found The URI names a node or list entry that does not exist
405 Method Not Allowed The method is not allowed on that resource
409 Conflict POST of a resource that already exists

Headers

Header Value
Accept application/yang-data+json or application/yang-data+xml
Content-Type Same values, for requests with a body
Authorization HTTP Basic with a local or AAA username and password

Exam trap

PUT replaces the target. A PUT to an interface with only a description in the body removes the interface's other configuration that the body does not include (such as its IP address). PATCH merges, so it changes only what you send. If a question says "after the call, the interface lost its IP address", the method was PUT.

NETCONF compared with RESTCONF

NETCONF RESTCONF
Standard RFC 6241 RFC 8040
Transport SSH HTTPS
Default port TCP 830 TCP 443
Encoding XML XML or JSON
Operations RPCs (get, edit-config...) HTTP methods (GET, POST, PUT, PATCH, DELETE)
Candidate datastore, locking, commit Yes No (works on the combined datastore)
Transactions across many changes Yes, with candidate and commit Each request is its own change
IOS XE enable command netconf-yang restconf plus ip http secure-server
Typical client Python ncclient, Ansible curl, Postman, Python requests

Enabling them on IOS XE

aaa new-model
aaa authentication login default local
aaa authorization exec default local
username automation privilege 15 secret Aut0mation!
!
netconf-yang
!
ip http secure-server
ip http authentication local
restconf

What each line is for:

Line Why
aaa new-model and the AAA lists The programmable interfaces authenticate through AAA. Without aaa authorization exec, the user may log in but not be authorized to read or change data.
privilege 15 user NETCONF and RESTCONF require a privilege 15 user (or AAA authorization that grants it)
netconf-yang Starts the NETCONF server on TCP 830 and the data model processes
ip http secure-server RESTCONF rides on the HTTPS server; without it there is nothing listening on 443
ip http authentication local Lets the HTTPS server use local usernames
restconf Enables the RESTCONF API on the HTTPS server

Optional settings: netconf-yang ssh port <n> changes the port; netconf-yang feature candidate-datastore enables the candidate datastore. Use an ACL on the management plane in production.

Exam trap

restconf alone does nothing visible if the HTTPS server is off. A configuration exhibit with restconf and ip http server (HTTP, not HTTPS) but no ip http secure-server will not answer RESTCONF requests on 443.

Verification

R1# show platform software yang-management process
confd            : Running
nesd             : Running
syncfd           : Running
ncsshd           : Running
dmiauthd         : Running
nginx            : Running
ndbmand          : Running
pubd             : Running

ncsshd is the NETCONF SSH daemon. nginx is the web server that terminates RESTCONF. confd holds the data model. The processes take a minute or two to reach Running after you enter netconf-yang the first time; until then requests fail.

R1# show netconf-yang status
netconf-yang: enabled
netconf-yang candidate-datastore: disabled
netconf-yang ssh port: 830

R1# show netconf-yang sessions
R: Global-lock on running datastore
C: Global-lock on candidate datastore
S: Global-lock on startup datastore

Number of sessions : 1

session-id  transport     username             source-host           global-lock
-------------------------------------------------------------------------------
22          netconf-ssh   automation           192.168.100.50        None

Making requests

$ ssh -p 830 [email protected] -s netconf
<?xml version="1.0" encoding="UTF-8"?>
<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:base:1.1</capability>
<capability>urn:ietf:params:netconf:capability:writable-running:1.0</capability>
...
<capability>http://cisco.com/ns/yang/Cisco-IOS-XE-native?module=Cisco-IOS-XE-native&amp;revision=...</capability>
...
</capabilities>
<session-id>22</session-id></hello>]]>]]>

The -s netconf option requests the NETCONF subsystem. The ]]>]]> sequence is the NETCONF 1.0 end-of-message marker. You must send your own <hello> before any <rpc>.

from ncclient import manager

FILTER = """
<filter>
  <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
    <interface><name>GigabitEthernet1</name></interface>
  </interfaces>
</filter>
"""

with manager.connect(host="192.168.100.1", port=830,
                     username="automation", password="Aut0mation!",
                     hostkey_verify=False) as m:
    reply = m.get_config(source="running", filter=FILTER)
    print(reply.xml)

$ curl -sk -u automation:'Aut0mation!' \
    -H "Accept: application/yang-data+json" \
    https://192.168.100.1/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1
{
  "ietf-interfaces:interface": {
    "name": "GigabitEthernet1",
    "description": "MGMT",
    "type": "iana-if-type:ethernetCsmacd",
    "enabled": true,
    "ietf-ip:ipv4": {
      "address": [
        {
          "ip": "192.168.100.1",
          "netmask": "255.255.255.0"
        }
      ]
    },
    "ietf-ip:ipv6": {
    }
  }
}

$ curl -sk -u automation:'Aut0mation!' -X PATCH \
    -H "Content-Type: application/yang-data+json" \
    -H "Accept: application/yang-data+json" \
    -d '{"ietf-interfaces:interface": {"name": "Loopback100", "description": "Set by RESTCONF"}}' \
    -w "%{http_code}\n" \
    https://192.168.100.1/restconf/data/ietf-interfaces:interfaces/interface=Loopback100
204

An <edit-config> that creates a loopback through NETCONF looks like this:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <target><running/></target>
    <config>
      <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
        <interface>
          <name>Loopback100</name>
          <description>Created by NETCONF</description>
          <type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:softwareLoopback</type>
          <enabled>true</enabled>
        </interface>
      </interfaces>
    </config>
  </edit-config>
</rpc>

A successful reply is <rpc-reply message-id="101"><ok/></rpc-reply>.

Troubleshooting

Symptom Check
SSH to port 830 refused netconf-yang missing, processes not yet Running, or a management ACL
NETCONF login works, then <rpc-error> access denied User is not privilege 15, or aaa authorization exec is missing
RESTCONF connection refused on 443 ip http secure-server missing
RESTCONF 401 Wrong credentials, or the HTTPS server is not using local authentication
RESTCONF 404 Wrong module prefix, misspelled node, list key not URL-encoded, or the entry does not exist
RESTCONF 400 JSON syntax error, or wrong value type for the YANG leaf
Change made, but gone after reload NETCONF and RESTCONF write running-config; save it

Lab: NETCONF and RESTCONF on a Catalyst 8000v

Topology: R1 (Catalyst 8000v) with Gi1 at 192.168.100.1/24, and an Ubuntu host at 192.168.100.50 with curl, python3 and the ncclient Python package available.

graph LR
  H["Ubuntu 192.168.100.50<br/>curl, ncclient"] -- "Gi1 192.168.100.1/24" --- R1["R1 C8000v"]
  1. Configure the AAA, user, netconf-yang, ip http secure-server, ip http authentication local and restconf lines shown above.
  2. Wait until show platform software yang-management process shows everything Running.
  3. From the host, ssh -p 830 [email protected] -s netconf. Find the Cisco-IOS-XE-native capability in the hello. Close with Ctrl-C.
  4. Run the ncclient script and confirm it prints Gi1's configuration in XML. Check show netconf-yang sessions on R1 while it runs (add a time.sleep(30) before the print to catch it).
  5. Run the RESTCONF GET with curl for Gi1 and compare the JSON with show running-config interface GigabitEthernet1.
  6. Create Loopback100 with a PUT to .../interface=Loopback100 using a body with name, type iana-if-type:softwareLoopback, enabled true and an IPv4 address. Note the status code (201).
  7. PATCH only the description (from the tab above). Confirm 204 and that the IP address is still there with show run interface Loopback100.
  8. Now PUT a body with only the name, type and a description. Check the loopback again: the IP address is gone. That is PUT replace semantics.
  9. Remove ip http secure-server and repeat the GET. Note the error, then put it back.
  10. DELETE Loopback100 and confirm 204.

Expected verification:

R1# show running-config interface Loopback100
interface Loopback100
 description Set by RESTCONF
 ip address 10.100.100.1 255.255.255.255
end

For a timed version combined with EEM, do Sim 12.

Quick check

Which three IOS XE commands, beyond a privilege 15 user and AAA, are needed for RESTCONF?

ip http secure-server, ip http authentication local (when using local users) and restconf.

What does each side send first in a NETCONF session?

A <hello> listing its capabilities. The server's hello also includes the session ID and the YANG modules it supports.

A RESTCONF PATCH that only changes a description returns which code on success?

204 No Content. The change is merged and no body is returned.

References