NETCONF and RESTCONF
NETCONF and RESTCONF are two doors to the same datastore, both using YANG models. NETCONF runs over SSH on port 830, with operations such as get-config, get, edit-config and lock on datastores like running and candidate. RESTCONF, RFC 8040, uses HTTP verbs over HTTPS, and on a device that also runs NETCONF it edits the same configuration.
By Arif, founder of Daveth · Updated
The full 9 min walkthrough is in Daveth Pro (Network). See what the plan opens
What this page answers
What is the difference between NETCONF and RESTCONF?
Both carry YANG-modelled data to the same datastore. NETCONF runs over SSH on port 830 with RPC operations such as get-config and edit-config; RESTCONF, RFC 8040, uses HTTP verbs and URLs. Read it in “4.1 Two doors to one datastore”
What are the NETCONF operations?
get-config requests configuration from a datastore; get requests running configuration and state; edit-config changes a datastore; copy-config and delete-config copy or delete a whole datastore; lock and unlock reserve one. Read it in the lesson
4.1 Two doors to one datastore
A script PATCHes an interface's speed over RESTCONF and gets an error back. The same change sent as a NETCONF merge succeeds. Which one is broken? Keep it for section 4.3.
09-5 wrote the contract, the YANG model. These two protocols carry the data. NETCONF, "defined in RFC 4741 and RFC 6241, is an IETF standard protocol that uses the YANG data models to communicate with the various devices on the network". RESTCONF, defined in RFC 8040, works "with data defined in YANG models while also using the datastore concepts defined in NETCONF". It works like a building with two staff entrances, each with its own house rules: you need a badge for both, and both lead to the same archive.
That's literal, not just a picture. When a RESTCONF server sits on a device that also runs NETCONF, RFC 8040 has it edit the same running configuration, or the candidate, committed straight away, if running isn't writable. The course's two servers are built the same way: a RESTCONF write reads back over NETCONF. And the guide is firm that it's not a contest: "There is a common misconception that RESTCONF is meant to replace NETCONF, but this is not the case". If you've ever used both a bank's app and its branch counter, you'll know the account is the same; only the forms differ.
The guide calls "RESTCONF will replace NETCONF" a common misconception, which in networking is the polite way of saying people have been confidently wrong about it in meetings.
NETCONF runs over SSH; every implementation must support it, on port 830. The session opens with a <hello> from each side listing its capabilities, and both must share a base version. "Capabilities tell the client what the device it's connected to can do". It's like exchanging business cards before a meeting: you learn who does what before anyone asks for anything. The course's server offered base 1.0, base 1.1 and its one model, and both sides then used 1.1's chunked framing.
After that, everything is an RPC in XML: an <rpc> goes out, an <rpc-reply> comes back. NETCONF is XML-only, and it keeps configuration in datastores. <running> is "the complete configuration currently active on the network device" and always exists; <candidate> and <startup> exist only when the server advertises them. The operations from Table 28-7, plus the lock:
| Operation | Does |
|---|---|
<get-config> | "Requests some or all of the configuration from a datastore": configuration only |
<get> | "Requests running configuration and state information" |
<edit-config> | changes a datastore |
<copy-config>, <delete-config> | copy or delete a whole datastore; <running> "cannot be deleted" |
<lock>, <unlock> | reserve a datastore so no other session can change it, then release it; a lock is also freed when its session ends |
<edit-config> carries an operation on each piece of data, and the default is merge:
| Operation | Existing entry | Missing entry |
|---|---|---|
| merge | combined with what's there: send only the name and the speed stays | created |
| replace | replaced: send only the name and the speed is gone | created |
| create | <rpc-error> data-exists | created |
| delete | deleted | <rpc-error> data-missing |
| remove | deleted | nothing happens, and no error |
It's the difference between correcting one box on a form and handing in a fresh form: anything you left blank on the fresh one is blank now. A refused request comes back as an <rpc-error> with a type, a tag and a severity; in the experiments a single-entry edit carrying data the model rejects, like speed 1g or a write to state, was refused and left the datastore as it was.
Two more habits of a careful client. Lock the datastore before a change so nobody else edits it underneath you: while you hold it, "the server MUST prevent any changes to the locked resource other than those requested by this session". A second <lock> request gets lock-denied, naming the holder, and a RESTCONF write against a NETCONF lock gets 409 with error-tag in-use. It works like a work-in-progress sign on a desk: anyone can look at the papers, only the person working there moves them, and the sign goes when they do: <unlock>, the session ending, or clear netconf-yang session for a stuck one. And don't assume all-or-nothing everywhere: the guide says "Transactions are all or nothing", but an <edit-config> on running stops at the first error by default, and rolling back the whole edit needs the :rollback-on-error capability. The candidate route is the all-or-nothing one: if a <commit> can't apply every change, "the running configuration MUST remain unchanged".
Remove on an entry that doesn't exist replies with a cheerful <ok/>, which is the most relaxed thing a network protocol has ever said about your mistakes.
RESTCONF is HTTP with the YANG model deciding the URLs, and it must run over TLS: it "MUST NOT be used over HTTP without using the TLS protocol". (The course's local server speaks plain HTTP on the loopback address only, for the experiments; a device serves HTTPS.) A client finds the API root at /.well-known/host-meta, and data lives under {root}/data. A URL works like a street address: the module-qualified node first, then the path down the tree, and a list entry named by its key after =, with any / in the key written %2F, so course-demo:interface=GigabitEthernet1%2F0%2F1.
"The RESTCONF requests and responses can use either JSON or XML", labelled application/yang-data+json or application/yang-data+xml. A GET returns configuration and state together unless you ask with ?content=config or ?content=nonconfig. Each method maps onto a NETCONF operation:
| Method | NETCONF equivalent | Success | Typical failure |
|---|---|---|---|
| GET | <get-config>, <get> | 200 with data | 404 for an entry that doesn't exist; 401 if you may not read it |
| POST | <edit-config> create | 201 Created and a Location | 409 Conflict, resource-denied, if it exists |
| PUT | <edit-config> create or replace | 201 if it created, 204 if it replaced | 400 for data the model rejects |
| PATCH | <edit-config> merge, but never creating | 204, or 200 with a body | the target must exist |
| DELETE | <edit-config> delete | 204 | the target must exist; 403 on any write you're not authorized for |
The guide lists GET, POST, PUT, DELETE and OPTIONS; RFC 8040 and the Cisco 17.9 chapter add PATCH and HEAD. Two cells above leave a choice open: RFC 8040 says a PATCH on a missing entry "MUST NOT create it" but not which code to send, and doesn't fix the code for DELETE on a missing entry either. RFC 8040 allows 404 with invalid-value for both; the course's servers answer 409 with data-missing, the mapping RFC 8040 §7 gives that error-tag. A real device may answer either way.
Predict before D1, from the table: set the change to merge, the interface to GigabitEthernet1/0/2 (not configured), and the data to speed 10m. Will the two doors agree?
D1

They don't. That answers section 4.1: the interface didn't exist. NETCONF's merge created it; PATCH is forbidden to. Neither door is broken; they have different house rules. The RESTCONF side refuses and leaves the datastore alone. With replace, the two agree again: PUT creates a missing entry with 201. Try create on the configured interface: data-exists against 409 resource-denied. And try remove: RESTCONF has no method for it at all. Think of it as two shops selling the same goods with different return policies: the stock is identical, and the rules at the counter are what change.
PATCH refusing to create a missing interface is the RESTCONF equivalent of a tailor who'll gladly shorten your trousers but won't make you a pair.
NETCONF needs a privilege 15 user and, with aaa new-model, AAA authentication and authorization; then one command turns it on. RESTCONF needs the same user and AAA: "NETCONF and RESTCONF connections must be authenticated using authentication, authorization, and accounting (AAA)".
username netadmin privilege 15 secret <password> aaa new-model aaa authentication login default local aaa authorization exec default local netconf-yang
(The chapter's own example uses password; secret stores the password hashed, as 08-1 showed.) RESTCONF adds an HTTPS server:
restconf ip http secure-server
Both work over either IP version: "External facing interfaces will provide dual-stack support; both IPv4 and IPv6". Give it time: "The complete activation of model-based interface processes may require up to 90 seconds". It's like a restaurant that opens its doors on time but needs a minute or so before the kitchen takes orders. Optionally, netconf-yang feature candidate-datastore adds a candidate; then "the running data store is not writable through NETCONF sessions" and changes go in only by commit.
| Command or output | Proves | Doesn't prove |
|---|---|---|
show platform software yang-management process lists confd, ncsshd and the rest as Running | the programmability processes are up | that a client can log in: AAA and privilege 15 decide that |
| the same output shows nginx Running | the HTTPS front end RESTCONF needs is up; nginx runs once ip http secure-server is configured | that RESTCONF is enabled or that you're authorized: check restconf and the user |
show netconf-yang sessions shows a session | a NETCONF client is connected, with its transport and user | that its edits succeeded |
show netconf-yang statistics with in-bad-rpcs rising | the device has refused RPCs | why: read the <rpc-error> the client received |
show netconf-yang datastores shows a lock | a session holds that datastore | which change it's making |
a client's <hello> from the device | NETCONF is answering and which capabilities it offers | that a given model is writable |
a RESTCONF 204 No Content | the change was accepted into the datastore | that it's saved for the next reload: RFC 8040 saves it automatically only if the device advertises :startup; whether IOS XE 17.9 does is unconfirmed, and the guide's Example 28-10 saves with a separate RPC, cisco-ia:save-config |
A pattern is emerging: most rows prove the door is open, not what you did inside. Like a hotel keycard that opens the door, a successful login says nothing about whether housekeeping moved your things; only a read after the change does.
The 90-second start-up is the only part of network programmability that's still done at human speed.
The guide's Example 28-11 is a RESTCONF GET for the logging severity, and its answer shows the whole pattern:
200
{
"Cisco-IOS-XE-native:severity": "critical"
}Read it the 09-5 way. The key carries its module, Cisco-IOS-XE-native, because it's the top-level member of the reply body, and RFC 7951 names top-level members module:name; the value is the leaf's value; 200 says the read worked and the body is the answer. The Cisco chapter's same request returned "informational" on its device. NETCONF's version of a read is an <rpc-reply> with a <data> element, like the guide's OSPF configuration in Example 28-9, whose native element carries the namespace http://cisco.com/ns/yang/ned/ios, Cisco's own model. It works like reading a delivery note: first check which supplier it's from (the module), then read what's in the box.
Continue the lesson
The whole lesson, with its drawings and its questions. The rest of this section and 9 more after it.


