C9800 NETCONF and RESTCONF: Automation and Programmability

C9800 NETCONF and RESTCONF: Automation and Programmability

The Catalyst 9800 wireless LAN controller represents a shift toward model-driven programmability, moving beyond traditional CLI-based management. This article explores how you can leverage NETCONF and RESTCONF protocols to automate configuration, retrieve operational data, and build scalable network solutions. Whether you're preparing for CCNP or CCIE certification or seeking to modernize your wireless infrastructure, understanding these protocols is essential.

Why Network Programmability Matters

Modern wireless networks demand flexibility and speed (you can deploy hundreds of access points across multiple sites in hours, not days). Manual configuration at scale introduces errors, increases operational overhead, and makes change tracking difficult. Network programmability addresses this by allowing you to define the desired network state in code, which the controller then enforces automatically.

The C9800 uses a model-driven approach based on YANG data models. This means you define what state you want, and the controller implements the necessary changes to reach that state. This declarative model differs from imperative approaches (where you issue sequential commands and hope the result is correct).

The C9800 Programmability Architecture

The C9800 controller provides access to both configuration and operational data through multiple protocols and encoding formats. Here's how the pieces fit together:

Not all combinations are valid. NETCONF always uses XML encoding and SSH transport. RESTCONF uses HTTP and supports both XML and JSON. Your programmability strategy depends on which protocols and encodings your environment supports.

YANG Data Models on the C9800

YANG (RFC 6020, RFC 7950) is a human-readable language for defining configuration and operational data. It organizes data hierarchically using modules, containers, leaves, and lists. The C9800 supports both vendor-specific Cisco models and OpenConfig-defined models for vendor independence.

Cisco YANG models contain the richest detail but are specific to Cisco devices and may change between software releases. OpenConfig models prioritize vendor independence and consistency across platforms, making them ideal for multi-vendor environments.

You can find YANG models for your C9800 software release on GitHub (github.com/YangModels/yang). Browse the vendor/cisco/xe directory to discover models for IOS-XE devices (the C9800 runs IOS-XE operating system).

Understanding NETCONF

NETCONF (RFC 6241) is a standardized network management protocol designed with programmability in mind. It uses XML encoding, mandatory SSH transport, and a request-reply message pattern. The protocol is transaction-aware, supporting atomic commit semantics (all changes succeed or all fail together).

NETCONF Capabilities

When a NETCONF client connects to the C9800, both sides exchange capabilities. The controller advertises which YANG models it supports, whether notifications are enabled, and which base functionality is available. This handshake ensures the client knows what operations are possible.

NETCONF Operations

NETCONF defines a base set of operations for managing device configuration:

NETCONF operations are encoded as XML-RPC style requests and responses. The protocol supports filtering using XPath or subtree specifications, so you can request only the data you need.

RESTCONF Fundamentals

RESTCONF (RFC 8040) brings HTTP semantics to YANG data model access. Instead of XML-RPC and SSH, you send standard HTTP verbs (GET, POST, PUT, PATCH, DELETE) over HTTPS to REST endpoints. RESTCONF supports both XML and JSON encoding, making it ideal for modern web-based tooling and JavaScript-heavy environments.

HTTP Methods and Operations

RESTCONF is stateless (unlike NETCONF), meaning each request is independent. You cannot use RESTCONF to lock resources across multiple requests in the way you would with NETCONF's lock operation.

RESTCONF URI Structure

RESTCONF URIs follow a predictable pattern based on the YANG module structure. The general form is:

https://<controller-ip>:<port>/restconf/data/<yang-module>:<top-level-container>/<nested-path>

For example, to access WLAN configuration on a C9800 at 10.51.65.200, you would query:

https://10.51.65.200/restconf/data/Cisco-IOS-XE-wireless-wlan-cfg:wlan-cfgData

The root RESTCONF endpoint is always:

https://<controller-ip>/.well-known/host-meta

This endpoint returns a link to the base RESTCONF endpoint, which typically resolves to /restconf.

Enabling NETCONF and RESTCONF on the C9800

Before you can use these protocols, enable them on your controller. Both protocols use the YANG model for configuration, and both are subject to AAA authentication (users must have appropriate privilege levels).

NETCONF Configuration

Enable NETCONF with the following CLI command (the controller will negotiate SSH automatically):

WLC(config)# netconf-yang

NETCONF uses SSH as mandatory transport and authenticates using the default AAA method. Ensure your AAA configuration is correct:

WLC(config)# aaa authorization exec default local
WLC(config)# aaa authentication login default local

RESTCONF Configuration

RESTCONF requires HTTP/HTTPS server support on the controller. Enable it under IP HTTP settings:

WLC(config)# ip http secure-server
WLC(config)# ip http authentication aaa login-authentication default

RESTCONF also respects AAA authentication; use basic auth (username:password in the Authorization header) for initial requests.

Practical Example: Querying WLANs Using RESTCONF

Let's retrieve the list of configured WLANs using RESTCONF and JSON encoding. The YANG model for WLANs is part of the Cisco IOS-XE wireless configuration module.

First, determine the correct URI by examining the YANG model hierarchy. The top-level container is wlan-cfgData, and WLANs are stored in a list called wlan-cfgEntry. Build the URI as:

https://10.51.65.200/restconf/data/Cisco-IOS-XE-wireless-wlan-cfg:wlan-cfgData/wlan-cfgEntry

Send a GET request with JSON encoding using curl:

curl -k -u admin:password \\
  -H 'Accept: application/yang-data+json' \\
  https://10.51.65.200/restconf/data/Cisco-IOS-XE-wireless-wlan-cfg:wlan-cfgData/wlan-cfgEntry

The response is a JSON-formatted list of WLAN configuration entries, including profile names, SSIDs, security settings, and more.

Creating a New WLAN Using RESTCONF

To create a new WLAN, POST a JSON object to the same URI. The request body must follow the YANG schema exactly:

curl -k -u admin:password \\
  -H 'Content-Type: application/yang-data+json' \\
  -X POST \\
  -d '{
    "Cisco-IOS-XE-wireless-wlan-cfg:wlan-cfgEntry": [
      {
        "profile-name": "guest_wlan",
        "wlan-id": 5,
        "security-wpa2": true,
        "psk": "your-preshared-key"
      }
    ]
  }' \\
  https://10.51.65.200/restconf/data/Cisco-IOS-XE-wireless-wlan-cfg:wlan-cfgData/wlan-cfgEntry

A successful POST returns HTTP 201 (Created) and includes the Location header pointing to the new resource.

Updating Configuration with RESTCONF PATCH

To modify an existing WLAN without replacing the entire entry, use PATCH:

curl -k -u admin:password \\
  -H 'Content-Type: application/yang-data+json' \\
  -X PATCH \\
  -d '{
    "Cisco-IOS-XE-wireless-wlan-cfg:wlan-cfgEntry": {
      "profile-name": "guest_wlan",
      "shutdown": "enabled"
    }
  }' \\
  https://10.51.65.200/restconf/data/Cisco-IOS-XE-wireless-wlan-cfg:wlan-cfgData/wlan-cfgEntry

PATCH only modifies the fields you specify; unspecified fields remain unchanged.

Tools for Exploring YANG Models

Working with YANG models requires tools to browse the model structure and understand valid values. Two popular open-source tools simplify this process.

pyang

pyang is a Python utility for validating and transforming YANG models. You can use it to visualize model structure, validate custom modules, and generate documentation. Download it from github.com/mbj4668/pyang and install it locally or via pip. The command below displays the structure of a WLAN configuration model:

pyang -f tree Cisco-IOS-XE-wireless-ap-cfg.yang

The output shows the hierarchical structure with data types, configuration availability, and constraints.

YANG Suite

YANG Suite is a graphical web-based tool for exploring YANG models, building NETCONF/RESTCONF requests, and executing them against live devices. It includes Docker containers for easy deployment and is ideal for learning or testing without writing custom code.

To run YANG Suite in Docker:

git clone https://github.com/CiscoDevNet/yangsuite.git
cd yangsuite/docker
./start_yang_suite.sh

Access YANG Suite via your browser (typically http://localhost:8443), load YANG models into a repository, and use the graphical interface to construct RPC calls and inspect responses.

Comparing NETCONF and RESTCONF

Authentication and Authorization

Both NETCONF and RESTCONF enforce authentication and authorization using the controller's AAA configuration. Users must have appropriate privilege levels to perform operations. The C9800 maps NETCONF/RESTCONF requests to CLI equivalent privilege levels.

For NETCONF over SSH, use standard SSH username/password or key-based authentication. The aaa authentication and aaa authorization commands determine which operations a user can perform.

For RESTCONF over HTTPS, send basic authentication in the HTTP Authorization header (base64-encoded username:password). Ensure your HTTP server has AAA login-authentication configured:

WLC(config)# ip http authentication aaa login-authentication default

Real-World Use Case: Python Automation Script

Here's a simple Python example using the requests library to retrieve access point information via RESTCONF:

import requests
import json
import urllib3

# Disable SSL warnings for lab environments
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

controller_ip = '10.51.65.200'
username = 'admin'
password = 'admin_password'
base_url = f'https://{controller_ip}/restconf/data'

# Headers for JSON requests
headers = {
    'Accept': 'application/yang-data+json',
    'Content-Type': 'application/yang-data+json'
}

# Retrieve all APs
url = f"{base_url}/Cisco-IOS-XE-wireless-access-point-oper:access-point-oper-data/capwap-data"

try:
    response = requests.get(url, auth=(username, password),
                           headers=headers, verify=False)
    if response.status_code == 200:
        data = response.json()
        print(json.dumps(data, indent=2))
    else:
        print(f"Error: {response.status_code}")
        print(response.text)
except Exception as e:
    print(f"Exception: {e}")

This script connects to the C9800, retrieves operational data about connected access points, and prints the JSON response. You can extend it to parse the response, filter specific APs, or trigger configuration changes.

Key Takeaways

• NETCONF and RESTCONF enable model-driven programmability. Both protocols use YANG data models to define configuration and operational data structure, allowing you to automate complex tasks without manual CLI configuration (a significant advantage when you need to push changes to hundreds of devices).
• Choose the right protocol for your use case. NETCONF excels at transactional, atomic changes where all-or-nothing semantics matter. RESTCONF suits DevOps workflows, web integration, and scenarios where HTTP tooling is already in place.
• YANG models are the foundation. Invest time understanding your controller's YANG models using tools like pyang and YANG Suite. Knowing the model hierarchy directly translates to building correct URIs and request payloads.
• Authentication and authorization apply to all protocols. NETCONF uses SSH authentication; RESTCONF uses HTTP basic auth or other mechanisms. Both respect your AAA configuration, so privilege levels control what operations users can perform.
• Start with RESTCONF and curl for learning. RESTCONF's HTTP-based approach is more familiar to modern engineers. Tools like curl and Postman make it easy to test queries before writing production automation.
• Plan for idempotency. Whether you use NETCONF's declarative model or RESTCONF's HTTP operations, design your scripts to handle repeated execution safely. Idempotent operations allow you to retry without unintended side effects.

Network programmability on the C9800 puts powerful automation capabilities in your hands. By mastering NETCONF and RESTCONF, you'll be equipped to build scalable, repeatable solutions for modern wireless networks.