NETCONF

NETCONF is a network management protocol developed by the IETF (Internet Engineering Task Force) to install, update, and delete the configuration of network devices. The operations are realized on top of a simple Remote Procedure Call (RPC) layer. The NETCONF protocol uses an Extensible Markup Language (XML) based data encoding for the configuration data as well as the protocol messages. The protocol messages are exchanged on top of a secure transport protocol which is usually SSH.

For more information on NETCONF, see RFC 6241.

Itential Automation Gateway (IAG) contains a NETCONF Execution Engine that supports updating a device's configuration, retrieving a device's full or partial configuration, and executing proprietary RPC commands that are made available by the NETCONF server running on the device. The engine implements the client side of the NETCONF protocol over SSH using the Python library ncclient. Sessions between the client and the server running on the remote device are created and closed automatically by the execution engine.

Capabilities

Capabilities augment the base operations of the device, describing both additional operations and the content allowed inside operations. As part of opening a NETCONF session, the client and server exchange capabilities which allows the client to know which additional operations are supported by the device. Any request made by the NETCONF Execution Engine that is not supported by the NETCONF server running on a device will be flagged and returned as an error back to the end user.

The capabilities of the NETCONF client can also affect the availability of operations that can be sent to the server running on a device. The APIs provided by the NETCONF Execution Engine are designed to prevent the end user from attempting to execute a NETCONF operation that is not supported by the client.

NETCONF Execution Engine Capabilities

urn:ietf:params:netconf:base:1.0
urn:ietf:params:netconf:base:1.1
urn:ietf:params:netconf:capability:writable-running:1.0
urn:ietf:params:netconf:capability:candidate:1.0
urn:ietf:params:netconf:capability:confirmed-commit:1.0
urn:ietf:params:netconf:capability:rollback-on-error:1.0
urn:ietf:params:netconf:capability:startup:1.0
urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file,https,sftp
urn:ietf:params:netconf:capability:validate:1.0
urn:ietf:params:netconf:capability:xpath:1.0
urn:ietf:params:netconf:capability:notification:1.0
urn:liberouter:params:netconf:capability:power-control:1.0
urn:ietf:params:netconf:capability:interleave:1.0
urn:ietf:params:netconf:capability:with-defaults:1.0

Inventory

The NETCONF Execution Engine is integrated with IAG's Inventory Service. The Inventory Service contains a complete set of APIs that perform CRUD operations to manage devices. Each execution engine within IAG has its own separate device inventory. In a future release, multiple named instances of inventories will be allowed per execution engine. Currently, only a single instance of a NETCONF inventory is supported and is assigned the name default by the IAG server.

Note: NETCONF operations are only permitted on devices found in the NETCONF default inventory.

Devices are added to the NETCONF inventory by issuing a POST /api/v2.0/ inventories/netconf/default/devices request with the name of the device along with set of connection variables in the request body.

NETCONF Device Create Request

{

  "name": "junos_host",
  "variables": {
    "host": "192.168.32.30",
    "password": "admin123",
    "platform": "junos",
    "port": 830,
    "username": "root"
  }
}

The host, password, platform, port, and username connection parameters are all required when creating a device. The value of the platform string parameter is a "device handler" that is recognized by ncclient. The API validates the platform parameter against an enumerated list of supported device handlers.

Device Handlers

alu
csr
erricsson
h3c
huawei
huaweiyang
iosxe
iosxr
junos
nexus
sros

Note: If there is no match for the device being added to the NETCONF inventory found in the device handlers list, set the platform parameter to the value default.

See the API Documentation section within the Automation Gateway UI for more details on the APIs contained in the IAG Inventory Service.

Execution

NETCONF APIs are executed by issuing a POST request with the appropriate endpoint, i.e., /api/v2.0/netconf/get_config. Executing an endpoint can be done using the Automation Gateway UI or by a separate application via the Automation Gateway API.

Endpoints

NETCONF endpoints are available to edit a device's configuration, retrieve a device's configuration, and execute proprietary actions or RPCs on a device.

/api/v2.0/netconf/set_config/execute
/api/v2.0/netconf/get_config/execute
/api/v2.0/netconf/exec_rpc/execute

Each NETCONF API contains a host parameter along with additional parameters that are specific to the operation being performed. The host parameter is a string that matches a single device name found in the NETCONF inventory. The APIs validate that the device is present in the NETCONF inventory before proceeding with the operation.

See the API Documentation section within the Automation Gateway UI for details on the parameters for each NETCONF endpoint.

Setting the Configuration

The /netconf/set_config/execute API is used to update the configuration of a device. The NETCONF Execution Engine utilizes the ncclient library to send a NETCONF edit RPC request to the server running on the device. In addition to the host parameter, there are several other parameters used by the API. Two worth noting are config_content and target_datastore.

The config_content parameter is the configuration data in XML string format. The configuration data supported by a device is defined by its data models. A device defines its data models using the YANG modeling language. The XML data sent to a device in the config_content parameter must be supported by a device's model or it will be returned as an error. Any syntax errors within the XML string will also be reported as errors.

The target_datastore parameter is the name of the configuration datastore to be updated. The user can choose between the NETCONF datastores candidate and running. If the candidate datastore is chosen, the NETCONF Execution Engine will write the changes to that datastore and then automatically commit them to the running datastore. The urn:ietf:params:netconf:capability:candidate:1.0 capability must be available on the device's NETCONF server for this option to be allowed. If target_datastore is set to running, that datastore is updated directly. Note that the urn:ietf:params:netconf:capability:writable-running:1.0 capability must be available on the device's NETCONF server for this option to be allowed. The default for the target_datastore parameter is the candidate datastore.

Sample Set Config Request

{"host": "junos_host",
 "config_content": "<nc:config xmlns:nc=\"urn:ietf:params:xml:ns:netconf:base:1.0\"><nc:configuration><nc:snmp><nc:community>itential</nc:community></nc:snmp></nc:configuration></nc:config>"
}

Sample Set Config Response

{
    "host": "junos_host",
    "status": "SUCCESS",
    "results": {
        "config_content": "<nc:config xmlns:nc=\"urn:ietf:params:xml:ns:netconf:base:1.0\"><nc:configuration><nc:snmp><nc:community>itential</nc:community></nc:snmp></nc:configuration></nc:config>"
    }
}

Retrieving the Configuration

The /netconf/get_config/execute API is used to retrieve the configuration of a device. The target_datastore parameter indicates which datastore from which to retrieve the configuration and can be set to either running, candidate, or startup. The default is to retrieve the configuration from the running datastore. The filter parameter is an XML string which acts as a filter to restrict the data retrieved from the device.

Sample Get Config Filter Request

{"host": "junos_host",
 "filter": "<configuration><interfaces/></configuration>"
}

Sample Get Config Filter Response

{
    "host": "junos_host",
    "status": "SUCCESS",
    "results": {
        "config_data": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><configuration commit-seconds=\"1620195008\" commit-localtime=\"2021-05-05 06:10:08 UTC\" commit-user=\"root\"><interfaces><interface><name>ge-1/2/0</name><unit><name>0</name><family><inet><address><name>10.2.3.4/24</name></address></inet></family></unit></interface><interface><name>ge-1/3/0</name><unit><name>0</name></unit></interface><interface><name>em0</name><unit><name>0</name><family><inet><address><name>192.168.32.30/24</name></address></inet></family></unit></interface></interfaces></configuration>",
        "filter": "<configuration><interfaces/></configuration>"
    }
}