Cisco NSO RESTCONF: Devices and Services

Mental model

Cisco objective 3.9.a also includes NSO. NSO (Network Services Orchestrator) manages a fleet of multi-vendor devices and lets you abstract services (MPLS L3VPN, QoS profile, firewall rule set) above them.

Two things NSO exposes you need to know:

• Device layer: every device NSO manages, their state, their config.
• Service layer: service models you define (or Cisco provides) that render into per-device config.

Both are reachable over RESTCONF (JSON over HTTPS) and NETCONF (XML over SSH). This topic shows RESTCONF — simplest with curl.

Base URL and auth

curl -u admin:admin https://nso.example.com/restconf/data/tailf-ncs:devices

• HTTP Basic auth with NSO user credentials.
• Base path: /restconf/data/ (standard RESTCONF).
• Accept header application/yang-data+json is standard; NSO defaults to JSON when the URL ends in .json is not needed (unlike ACI).

3.9.a — List devices

curl -u admin:admin \
     -H "Accept: application/yang-data+json" \
     https://nso.example.com/restconf/data/tailf-ncs:devices/device

Response (abbreviated):

{
  "tailf-ncs:device": [
    {
      "name": "sw-core-1",
      "address": "10.0.0.1",
      "port": 22,
      "device-type": {"cli": {"ned-id": "cisco-ios-cli-6.86:cisco-ios-cli-6.86"}},
      "state": {"oper-state": "enabled", "admin-state": "unlocked"}
    },
    {
      "name": "jnpr-core-1",
      "address": "10.0.0.2",
      "device-type": {"netconf": {"ned-id": "juniper-junos-nc-5.4:juniper-junos-nc-5.4"}}
    }
  ]
}

Fields:

• name — unique NSO handle.
• address + port — how NSO reaches it.
• device-type — which NED (Network Element Driver) NSO uses to talk to it. CLI, NETCONF, or REST.
• state — operational and admin state.

Trigger sync-from (pull live config)

curl -u admin:admin -X POST \
     https://nso.example.com/restconf/operations/tailf-ncs:devices/device=sw-core-1/sync-from

• Operation (RPC) under /restconf/operations/, not /restconf/data/.
• Pulls the device’s current running-config into NSO’s CDB (Configuration DataBase).

Push a service (write)

NSO shines when you POST a service that NSO renders into per-device config:

curl -u admin:admin -X POST \
     -H "Content-Type: application/yang-data+json" \
     -d '{"l3vpn:l3vpn": [{"name": "ACME-VPN", "customer": "ACME", "endpoints": [{"device": "pe-01", "iface": "Gi0/1", "ip-prefix": "10.0.0.1/30"}]}]}' \
     https://nso.example.com/restconf/data

NSO:

1. Validates the service against its YANG model.
2. Renders per-device config (Cisco IOS lines for pe-01, Juniper statements if the next endpoint is Junos).
3. Commits atomically across ALL involved devices; rolls back if any one fails.

That transactional, cross-vendor commit is NSO’s main value.

Dry-run (commit —dry-run)

curl -u admin:admin -X POST \
     -H "Content-Type: application/yang-data+json" \
     -d '{"input":{"outformat":"native","reverse":false}}' \
     https://nso.example.com/restconf/data?dry-run=native

Shows the exact per-device CLI NSO WOULD push, without committing.

Python with requests

import requests
from requests.auth import HTTPBasicAuth

BASE = "https://nso.example.com"
auth = HTTPBasicAuth("admin", "admin")
HDR = {"Accept": "application/yang-data+json",
       "Content-Type": "application/yang-data+json"}

r = requests.get(f"{BASE}/restconf/data/tailf-ncs:devices/device",
                 auth=auth, headers=HDR, verify=False)
r.raise_for_status()
for d in r.json()["tailf-ncs:device"]:
    print(f"{d['name']:20} {d.get('address','?'):16} {d['state']['oper-state']}")

Common NSO RESTCONF paths

Common gotchas

• URL encoding. Device names and keys often contain special characters; curl --data-urlencode or Python’s requests.utils.quote saves you.
• Dry-run first. Any service push to prod should be preceded by ?dry-run=native.
• CDB vs device. NSO’s internal view (CDB) can drift from device reality. sync-from reconciles.
• Transaction rollback. If a 10-device push fails on device 7, NSO rolls back on 1-7. All or nothing. This is NSO’s superpower.

FAQ

Is NSO on the exam? Yes. 3.9.a names NSO as one of five device sources (Meraki, Catalyst Center, ACI, Catalyst SD-WAN, NSO) you should know how to query. 5.6 also names NSO as an automation tool.

Can I run NSO on my laptop? NSO has a free Learning Edition and a trial of the full product. developer.cisco.com → NSO Sandbox for always-on.

Is NSO a controller like Catalyst Center? Related but different. Catalyst Center is a controller for Catalyst Cisco gear with assurance baked in. NSO is a service orchestrator across any vendor speaking NETCONF/CLI/REST — more general, less turnkey.

Why is the module name tailf-ncs? Tail-f was the Swedish company that built NSO. Cisco acquired them in 2014. The internal module names kept the tailf- prefix.