NETCONF and RESTCONF

The CLI was built for people: every vendor spells it differently and answers come back as text laid out for eyes. NETCONF and RESTCONF give programs an interface, and both go through AAA and want privilege level 15. NETCONF is XML over an SSH session on port 830 by default. Its candidate datastore stages changes that are not live, then commits them to running at once.

In Daveth Pro (Network)12 min video · lab: Operations

By , founder of Daveth · Updated

Opening frame of the video walkthrough of NETCONF and RESTCONF

Watch this lesson

12 min · Video walkthrough

In Daveth Pro (Network)

The full 12 min walkthrough is in Daveth Pro (Network). See what the plan opens

Upcoming practical lab

Lab C14: Operations

What the lab covers

What this page answers

What port does NETCONF use?

830 by default: NETCONF runs XML over an SSH session, and the port is configurable. Read it in “NETCONF: a session and a port”

What is the NETCONF candidate datastore?

A scratch copy of the running configuration. Changes written to it are not live until a commit pushes them all into running at once, so a multi-part change has no half-applied window. Read it in “The candidate datastore”

What privilege do NETCONF and RESTCONF need on IOS XE?

Both authenticate through AAA and require privilege level 15. There is no separate API login. Read it in “What they share”

The CLI was never an API

A concert arena sets up ARENA-SW1 for show night. Tonight's change has three parts that only work together: a VLAN for the broadcast trucks and two ports in it. The team's automation server, AUTO-1, makes the change; the operations dashboard, DASH-1, watches the switch. They already have SSH and a CLI. Why would a program want anything else?

Because the CLI was built for you, not for a program. Every vendor spells it differently, and every answer comes back as text laid out for a human to look at. A program has to guess where the columns are, and a program that guesses is a program that breaks the day somebody adds a column. The CLI has no contract. It has a habit.

Plain words first. An API is a way for one program to ask another for something in a fixed, agreed shape. YANG is a language for writing that shape down: which settings exist, what type each one is, and what it is allowed to hold. A datastore is a named copy of the configuration, such as running.

Put those two together and you have the thing the CLI never was. YANG says what the data looks like, and NETCONF carries it. Now a program knows the shape before it asks, and nobody is parsing text at three in the morning.

What they share

Before either protocol does anything: who is allowed to use it?

Both of them go through AAA, and both want privilege level 15. There is no separate API login, no key file, no side door. A RADIUS or TACACS+ user at level 15 gets in, and everybody else does not. The API is not a way around your AAA. It is another thing standing behind it. AAA itself is 4.1.b's lesson; here it is a prerequisite, no more.

If touching your AAA configuration to enable this makes you nervous, you do not have to. A named method list lets you point these three interfaces at their own list, and leave the device's existing AAA exactly where it is.

They also listen on both address families. The external-facing interfaces are dual-stack, so AUTO-1 can come in over IPv6 while DASH-1 comes in over IPv4, at the same time, against the same switch.

One bridge from the CLI you already know: add | format netconf-xml or | format restconf-json to show running-config, and the switch hands the configuration back in the structured shape instead of the human one. The switch will translate its own configuration into XML or JSON for you, which is a very polite way of admitting nobody was going to write it by hand.

One catch, and it is the kind that wastes an afternoon. That translation is off until you ask for it, and asking for it is not enough on its own: NETCONF-YANG has to be configured first and its processes have to have finished starting. Type the format option on a switch that is not running the model-driven interfaces yet and nothing translates.

NETCONF: a session and a port

NETCONF is XML over an SSH session, on port 830 by default. A client opens it, and then calls procedures on the far end: fetch me this, change me that. It is not a web service, and it does not reconnect for every question. It sits there, and while it sits there the switch remembers who it is.

That port is configurable, and the transport is plain SSH, which means it goes wherever your management access already goes.

Configured on ARENA-SW1: NETCONF-YANG turned on; AAA and the privilege 15 users are already configured (4.1.b)

ARENA-SW1# configure terminal
ARENA-SW1(config)# netconf-yang
ARENA-SW1(config)# end

One command, and quite a lot happens. NETCONF uses the device's primary trustpoint, and if the device has not got one it makes itself a self-signed one on the spot. Then it takes its time. The model-driven processes can need a minute and a half to finish coming up, so a client that connects immediately and fails has not necessarily found a fault.

And one thing that will stop it dead. If the older, pre-standard NETCONF is still enabled on the box, the standards-compliant one does not work at all. Not degraded, not slower: it does not work. Two NETCONFs on one switch is one too many.

So did that one command actually start anything?

ARENA-SW1: show platform software yang-management process

ARENA-SW1# show platform software yang-management process
confd            : Running
nesd             : Running
syncfd           : Running
ncsshd           : Running
dmiauthd         : Running
vtyserverutild   : Running
opdatamgrd       : Running
nginx            : Not Running
ndbmand          : Running

Read the list: ncsshd is running, nginx is not. NETCONF brought its own SSH daemon and never needed a web server. Remember that line, because the RESTCONF section turns it exactly around.

And is AUTO-1 actually connected?

ARENA-SW1: show netconf-yang sessions

ARENA-SW1# 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
-------------------------------------------------------------
21         netconf-ssh auto     2001:db8:40::10   None

That is the whole idea of NETCONF in one output. A session id, a username, an address, and a lock column. The switch is holding on to something. Nothing in RESTCONF will ever print a table like this.

Proves: show netconf-yang sessions proves which NETCONF sessions exist, over which transport, for which user, from which address, and whether each holds a global lock. Does not prove: that the session's requests will succeed, or that the configuration it wrote is what is running now. None of this output's columns records a commit or its rollback.

One place NETCONF is simply not available: a device running dual IOSd or software redundancy does not support it.

The candidate datastore

Have you ever wanted to stage three CLI changes and land them as one? You cannot. Every CLI command takes effect the moment you press Enter, which means every multi-part change has a window in the middle where half of it is live. Tonight that window is a VLAN with no ports in it.

The candidate datastore is a scratch copy of the running configuration. You write into it as much as you like, and nothing you write is live. Then one commit pushes the whole lot into running at once. Three changes go in. One change comes out.

Configured on ARENA-SW1: the candidate datastore, turned on

ARENA-SW1# configure terminal
ARENA-SW1(config)# netconf-yang feature candidate-datastore
ARENA-SW1(config)# end

Turning it on has two consequences worth knowing before you type it. The first: NETCONF and RESTCONF restart, and any session in progress is lost. Do this at four on a Friday and you will find out who was connected.

Is AUTO-1 still connected after that restart?

ARENA-SW1: show netconf-yang sessions

ARENA-SW1# 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
-------------------------------------------------------------
23         netconf-ssh auto     2001:db8:40::10   None

Look at the session id: it changed. AUTO-1 did not survive the restart, it reconnected. A session id that has moved is the switch telling you it was restarted underneath somebody.

The second consequence is bigger. Once the candidate is on, running is no longer writable through NETCONF at all. Every configuration change now goes in through the candidate and arrives by commit. There is no longer a fast path, and that is the point.

Computed from the state: what NETCONF may write now. No command prints it in this form.

datastore  NETCONF writes  locked by  tonight's change
running    no              -          none of it
candidate  yes             -          none of it

Now the part that catches people. The candidate is shared. It is not your private workspace: several NETCONF sessions can be editing the same candidate at the same time, and a commit pushes whatever is in there, including somebody else's half-finished work. You can commit a change you have never seen.

Which is why the order of operations matters more than the commands do. Lock running. Lock the candidate. Edit the candidate. Commit. Take both locks before you write anything, and nobody can put their change in your commit.

Computed from the state: after AUTO-1 locks both and edits the candidate. No command prints it in this form.

datastore  NETCONF writes  locked by  tonight's change
running    no              23         none of it
candidate  yes             23         all three parts

Read the running row: none of tonight's change. All three parts are sitting in the candidate, and while AUTO-1 holds both locks nobody else can touch either datastore.

How would you see who is holding those locks?

ARENA-SW1: show netconf-yang sessions

ARENA-SW1# 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
-------------------------------------------------------------
23         netconf-ssh auto     2001:db8:40::10   R, C

Look at the global-lock column: R, C. The legend above it reads R as running and C as candidate. The lock is not a setting, it is a property of a session, which is why it shows up here and nowhere else.

Computed from the state: after the commit, with both locks released. No command prints it in this form.

datastore  NETCONF writes  locked by  tonight's change
running    no              -          all three parts
candidate  yes             -          all three parts

All three parts, applied by one commit, and the locks let go. The broadcast trucks never saw a VLAN without ports.

And if you decide against the change before committing it, there is nothing to undo. Discard the candidate and it goes back to matching running. Nothing you staged was ever live, so there is no rollback to perform.