NETCONF

Collect XML/YANG data from NETCONF-capable devices with Prelude Collector — connection settings, authentication, and example records.

NETCONF (Network Configuration Protocol, RFC 6241) is an XML-based protocol for retrieving and modifying network device configuration and state. Prelude Collector uses NETCONF in a polling mode: it periodically issues <get> RPCs with subtree filters and parses the XML response into structured data. After the first mention, this page refers to Prelude Collector as "the collector".

When to use

Pick NETCONF when you need configuration-shaped data from a device that exposes a YANG tree over NETCONF — Juniper Junos historically has the richest NETCONF interface, and Cisco IOS-XR, Nokia SR OS, and modern Cisco IOS-XE all ship NETCONF alongside gNMI. Use it when the data is structured intent (interfaces, policies, route maps, ACLs) rather than fast-moving counters.

Connection settings

A NETCONF Protocol record carries the device-side transport settings:

Field	Type	Default	Description
`type`	string	`"netconf"`	Protocol type identifier.
`address`	string	-	Device address as `host:port`. The default NETCONF over SSH port is 830.
`username`	string	-	SSH username.
`password`	string	-	SSH password. Stored encrypted in the database.

The collector-wide NETCONF timeout applies to every NETCONF Protocol record and is set via COLLECTOR_NETCONF_* environment variables (see the Configuration reference):

Field	Default	Description
`timeout`	`30`	Seconds applied to both the SSH connect and individual RPC calls.

For the exact field names accepted by the API, see the API reference for Protocols.

Authentication options

SSH password

The default and only currently supported authentication mode. Set username and password on the Protocol record. The password is stored encrypted at rest and decrypted at connect time.

Host key verification is not enforced in the current release. Run NETCONF on a trusted management VLAN and rotate device passwords regularly.

Subtree filters

NETCONF requests are scoped by subtree filter expressions in the Model's collection config. Each filter path matches a YANG-defined subtree, for example /interfaces/interface or /network-instances/network-instance. The collector iterates the configured filter paths on every poll, parses the XML response, and emits one Snapshot row per list entry — so an interface list with 24 ports yields 24 rows, each labeled by its YANG list key.

The collector does not validate device responses against a YANG schema at collection time; it parses the raw XML and leaves schema work to the YANG browser in the web UI.

Examples

Device + Protocol record

export BASE="https://collector.example.com"
export TOKEN="<your-api-token>"

curl -s -X POST "$BASE/api/v1/devices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "junos-edge-02",
    "ip": "192.0.2.20",
    "active": true
  }'

curl -s -X POST "$BASE/api/v1/protocols" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 2,
    "type": "netconf",
    "address": "192.0.2.20:830",
    "username": "prelude",
    "password": "<your-device-password>"
  }'

Bruno: 02 Devices / Create device, 03 Protocols / Create gNMI protocol

Subscription

device_id: 2
model: openconfig-interfaces
interval: 60
enabled: true

interval is the poll interval in seconds. Keep NETCONF intervals coarse — 60 seconds or longer — because every poll opens a fresh RPC exchange.

Limitations

Authentication is SSH password only in this release. Public-key and certificate-based auth are not yet supported.
Host key verification is not enforced. Run NETCONF only on trusted management networks.
NETCONF notification streaming (RFC 5277) is not implemented. All collection is poll-based using <get> RPCs.
Filters are subtree-only. The collector emits <filter type="subtree">…</filter> on every request; XPath filters (type="xpath") are not supported.
The collector calls <get>, which returns operational state merged with configuration. Datastore-scoped reads (<get-config> against running, candidate, or startup) are not implemented.
Each Protocol record holds one NETCONF SSH session. All Models attached to that Protocol share the session, so very fast intervals on many models will queue.
Configuration writes (edit-config, candidate / commit) are out of scope for the collector — it only reads.

Troubleshooting

Test Connection from the device UI

Open the device's Protocols tab in the web UI and click Test Connection on the NETCONF Protocol row. The collector opens an SSH session, exchanges <hello> capabilities with the device, and reports success, failure, or the exact NETCONF error. Use this first whenever a Subscription stops producing Snapshots — a green Test Connection proves auth, port 830, and capability negotiation are healthy and narrows the problem to the subtree filters.

One-shot filter test

The test-path endpoint runs a one-shot <get> against an existing Device without needing a Model or Mapping, and returns the raw XML updates the device sends back:

curl -s -X POST "$BASE/api/v1/protocols/test-path" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device-id": 2,
    "protocol": "netconf",
    "paths": ["/interfaces/interface"]
  }'

Bruno: 03 Protocols / Test path (gNMI)

paths for NETCONF is a list of subtree filter expressions. Use it to confirm a filter actually returns data on the target before wiring it into a Model.