Huawei Network Device Management with YANG, NETCONF and RESTCONF

Modern Huawei switches and routers can be managed through model-driven interfaces instead of the CLI. This article walks through one simple use case - creating a VLAN - and shows how the three building blocks YANG, NETCONF and RESTCONF fit together.

Introduction

For decades, network devices were configured manually via the CLI or with scripts that send CLI commands and parse text output. This approach is fragile: output formats change between software versions, errors are hard to detect, and there is no guarantee that a change is applied completely or not at all. Model-driven management solves this with three complementary standards.

YANG - the data model

YANG (Yet Another Next Generation, RFC 7950) is a language for describing configuration and state data of a network device. A YANG module defines the structure (containers, lists, leaves), the data types and the rules (e.g. value ranges, mandatory fields, dependencies). YANG itself does not transport anything - it is the contract between client and device that defines what can be configured and what is valid. Vendors publish their own models (e.g. Huawei huawei-*), alongside standard models from the IETF (ietf-*) and OpenConfig (openconfig-*).

NETCONF - the configuration protocol

NETCONF (Network Configuration Protocol, RFC 6241) is the protocol that carries YANG-modelled data between a management client and the device. It runs over SSH (default port 830) and encodes all messages in XML as remote procedure calls (RPCs) such as <get>, <get-config>, <edit-config>, <commit> and <lock>. Key features are:

• Separate datastores such as running, candidate and startup.
• Transactions: a change is validated and applied completely or rejected completely.
• Locking, so that several clients cannot change the configuration at the same time.
• Structured errors (<rpc-error>) instead of free-text CLI messages.

RESTCONF - the web-style alternative

RESTCONF (RFC 8040) provides access to the same YANG data over HTTPS using a REST-like interface. Each node of the YANG tree is reachable through a URL, and standard HTTP methods (GET, POST, PUT, PATCH, DELETE) are used to read and change data. Payloads can be encoded in JSON or XML. RESTCONF is simpler to use from web applications and common tools like curl or Postman, but it offers fewer advanced features than NETCONF (e.g. no explicit locking or candidate datastore handling).

How they fit together

	YANG	NETCONF	RESTCONF
Role	Data model	Protocol	Protocol
Transport	-	SSH (port 830)	HTTPS (port 443)
Encoding	-	XML	JSON or XML
Typical use	Defines structure and rules	Robutst automation, transactions	Simple integrations, web tool

In short: YANG describes the data, NETCONF and RESTCONF move it. Both protocols use the same YANG models, so the examples below look very similar - only the transport and encoding differ.

1. YANG example: the VLAN model

YANG is a data modelling language (RFC 7950). A YANG module defines containers, lists and leaves, including data types and value ranges. The device validates every request against this model.

A simplified excerpt of huawei-vlan.yang:

module huawei-vlan {
  yang-version 1;
  namespace "urn:huawei:yang:huawei-vlan";
  prefix vlan;

  typedef vlan-id {
    type uint16 {
      range "1..4094";
    }
    description "VLAN ID.";
  }

  container vlan {
    container vlans {
      list vlan {
        key "id";
        max-elements 4094;
        description "Configure VLAN information.";

        leaf id {
          type vlan-id;
        }
        leaf name {
          type string { length "1..31"; }
        }
        leaf description {
          type string { length "1..80"; }
        }
      }
    }
  }
}

Key points:

• list vlan with key "id" means every VLAN is uniquely identified by its ID.
• The typedef vlan-id restricts the ID to 1-4094. This is exactly why VLAN 5000 will be rejected later.
• The resulting data tree is /vlan/vlans/vlan[id].

You can visualise the tree with pyang:

pyang -f tree huawei-vlan.yang

module: huawei-vlan
  +--rw vlan
     +--rw vlans
        +--rw vlan* [id]
           +--rw id             vlan-id
           +--rw name?          string
           +--rw description?   string

2. Preparing the device for NETCONF

A minimal configuration to enable NETCONF over SSH on a VRP device (commands may vary slightly per platform):

stelnet server enable
ssh user netcamp authentication-type password
ssh user netcamp service-type snetconf
#
netconf
 protocol inbound ssh port 830
#
snetconf server enable

The user netcamp must also exist in the AAA configuration with sufficient privileges.

3. Creating a VLAN with NETCONF

NETCONF uses RPCs encoded in XML. To create a VLAN, the client sends an <edit-config> RPC to the running (or candidate) datastore.

3.1 Request: create VLAN 100

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <target>
      <running/>
    </target>
    <config>
      <vlan xmlns="urn:huawei:yang:huawei-vlan">
        <vlans>
          <vlan>
            <id>100</id>
            <name>USERS</name>
            <description>User VLAN Floor 1</description>
          </vlan>
        </vlans>
      </vlan>
    </config>
  </edit-config>
</rpc>

3.2 Response when it works

If the data is valid, the device answers with a simple <ok/>:

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

On the CLI, display vlan 100 now shows the new VLAN.

3.3 Request: create VLAN 5000 (invalid)

<rpc message-id="102" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <target>
      <running/>
    </target>
    <config>
      <vlan xmlns="urn:huawei:yang:huawei-vlan">
        <vlans>
          <vlan>
            <id>5000</id>
            <name>INVALID</name>
          </vlan>
        </vlans>
      </vlan>
    </config>
  </edit-config>
</rpc>

3.4 Response when it fails

Because 5000 is outside the YANG range 1..4094, the device rejects the request with an <rpc-error>. Nothing is configured. A typical reply looks like this (the exact error-message text depends on the software version):

<rpc-reply message-id="102" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <rpc-error>
    <error-type>application</error-type>
    <error-tag>invalid-value</error-tag>
    <error-severity>error</error-severity>
    <error-path xmlns:vlan="urn:huawei:yang:huawei-vlan">/vlan:vlan/vlan:vlans/vlan:vlan/vlan:id</error-path>
    <error-message xml:lang="en">The value 5000 is out of range. Valid range: 1..4094.</error-message>
  </rpc-error>
</rpc-reply>

The important fields:

Field	Meaning
error-type	Layer where the error occurred (transport, rpc, protocol, application)
error-tag	Standardised error code from RFC 6241, here invalid-value
error-severity	error or warning
error-path	XPath to the element that caused the error
error-message	Human-readable explanation from the device

4. Tool for NETCONF requests: ncclient

The most common tool for NETCONF is the Python library ncclient. It handles the SSH session, capability exchange and RPC framing.

pip install ncclient

Example script that creates VLAN 100 and shows the error handling for VLAN 5000:

from ncclient import manager
from ncclient.operations import RPCError

VLAN_TEMPLATE = """
<config>
  <vlan xmlns="urn:huawei:yang:huawei-vlan">
    <vlans>
      <vlan>
        <id>{vlan_id}</id>
        <name>{name}</name>
      </vlan>
    </vlans>
  </vlan>
</config>
"""

with manager.connect(
    host="192.0.2.10",
    port=830,
    username="netcamp",
    password="secret",
    hostkey_verify=False,
    device_params={"name": "huaweiyang"},
) as m:

    for vlan_id, name in [(100, "USERS"), (5000, "INVALID")]:
        try:
            reply = m.edit_config(
                target="running",
                config=VLAN_TEMPLATE.format(vlan_id=vlan_id, name=name),
            )
            print(f"VLAN {vlan_id}: OK -> {reply.ok}")
        except RPCError as e:
            print(f"VLAN {vlan_id}: FAILED -> {e.tag}: {e.message}")

    # Read back the VLAN configuration
    vlan_filter = '<vlan xmlns="urn:huawei:yang:huawei-vlan"><vlans/></vlan>'
    print(m.get_config(source="running", filter=("subtree", vlan_filter)))

Expected output:

VLAN 100: OK -> True
VLAN 5000: FAILED -> invalid-value: The value 5000 is out of range. Valid range: 1..4094.

Other useful tools:

• netconf-console2 - command-line NETCONF client, good for quick tests.
• YANG Suite - web GUI to browse YANG models and build NETCONF/RESTCONF requests.
• pyang - validates YANG modules and renders tree views.
• Ansible (ansible.netcommon.netconf_config) - for automation at scale.

5. The same example with RESTCONF

RESTCONF (RFC 8040) maps the YANG data tree to URLs and uses standard HTTP methods. The same huawei-vlan model is used, so the data is identical - only the transport and encoding change.

NETCONF	RESTCONF
<get-config>	GET
<edit-config> (merge)	POST / PATCH
<edit-config> (replace)	PUT
<edit-config> (delete)	DELETE

The URL is built as: https://<device>/restconf/data/<module>:<container>/...

RESTCONF must be enabled on the device and runs over HTTPS. Check the product documentation for the exact commands on your platform.

5.1 Request: create VLAN 100

curl -k -u netcamp:secret \
  -X POST "https://192.0.2.10/restconf/data/huawei-vlan:vlan/vlans" \
  -H "Content-Type: application/yang-data+json" \
  -H "Accept: application/yang-data+json" \
  -d '{
        "huawei-vlan:vlan": [
          {
            "id": 100,
            "name": "USERS",
            "description": "User VLAN Floor 1"
          }
        ]
      }'

5.2 Response when it works

HTTP/1.1 201 Created
Location: https://192.0.2.10/restconf/data/huawei-vlan:vlan/vlans/vlan=100

The VLAN can be read back with:

curl -k -u netcamp:secret \
  "https://192.0.2.10/restconf/data/huawei-vlan:vlan/vlans/vlan=100" \
  -H "Accept: application/yang-data+json"

{
  "huawei-vlan:vlan": [
    {
      "id": 100,
      "name": "USERS",
      "description": "User VLAN Floor 1"
    }
  ]
}

5.3 Request: create VLAN 5000 (invalid)

curl -k -u netcamp:secret \
  -X POST "https://192.0.2.10/restconf/data/huawei-vlan:vlan/vlans" \
  -H "Content-Type: application/yang-data+json" \
  -H "Accept: application/yang-data+json" \
  -d '{ "huawei-vlan:vlan": [ { "id": 5000, "name": "INVALID" } ] }'

5.4 Response when it fails

RESTCONF returns an HTTP error code plus an error body with the same structure as NETCONF's <rpc-error>:

HTTP/1.1 400 Bad Request
Content-Type: application/yang-data+json

{
  "ietf-restconf:errors": {
    "error": [
      {
        "error-type": "application",
        "error-tag": "invalid-value",
        "error-path": "/huawei-vlan:vlan/vlans/vlan/id",
        "error-message": "The value 5000 is out of range. Valid range: 1..4094."
      }
    ]
  }
}

Tools for RESTCONF: curl, Postman, YANG Suite, or Python with the requests library.

6. Summary

• The YANG model defines the structure and rules - here, a VLAN ID must be between 1 and 4094.
• NETCONF sends the configuration as XML over SSH; success returns <ok/>, failure returns <rpc-error>.
• RESTCONF sends the same data as JSON over HTTPS; success returns 201 Created, failure returns 400 Bad Request with an error body.
• Because the device validates against the YANG model, invalid input like VLAN 5000 is rejected before any change is applied - one of the main advantages over CLI scripting.