> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/4/netconf-integration/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# NETCONF integration

> Overview of the NETCONF execution engine in Itential Gateway, including capabilities, inventory management, and API endpoints.

**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](https://datatracker.ietf.org/doc/html/rfc6241#section-7.7).

Itential Gateway 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

```bash
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 Gateway's Inventory Service. The Inventory Service contains a complete set of APIs that perform CRUD operations to manage devices. Each execution engine within Gateway 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 Gateway 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 a set of connection variables in the request body.

#### NETCONF device create request

```json
{
  "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

```bash
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 Gateway UI for more details on the APIs contained in the Gateway 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 Gateway UI or by a separate application via the 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.

```bash
/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 Gateway UI for details on the parameters for each NETCONF endpoint.

### Set 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. You 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

```json
{
  "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

```json
{
    "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>"
    }
}
```

### Retrieve 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

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

#### Sample get config filter response

```json
{
    "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>"
    }
}
```

> Overview of the NETCONF execution engine in Itential Gateway, including capabilities, inventory management, and API endpoints.