NETCONF Get Data¤

Retrieve configuration and operational state with netconf_get using ncclient (default) or scrapli. The task is available through Python, NFCLI, generated FastAPI endpoints, and MCP tools.

Output¤

Use XML processors to convert replies to dictionaries (xmltodict), select XML elements (xpath), or extract flat values (xml-flake).

Default results contain an XML reply under each host's get key. Unfiltered Scrapli requests use <get/> through its RPC method and return under rpc. add_details=True includes execution metadata; to_dict=False returns serialized records. Connection and RPC failures appear in per-host results.

Supported Getters¤

Getters are predefined subtree filter shortcuts. The selected device must support the corresponding YANG data model; a shortcut does not translate between vendor models.

Getter	Description
`ietf-interfaces`	Retrieve the `/interfaces` subtree in the `urn:ietf:params:xml:ns:yang:ietf-interfaces` namespace, including configuration and state exposed there.
`openconfig-interfaces`	Interface configuration, state, and counters under `/interfaces` in the OpenConfig interfaces namespace.
`openconfig-lldp`	LLDP configuration and neighbor state under `/lldp`.
`openconfig-bgp`	The BGP subtree under `/network-instances/network-instance/protocols/protocol/bgp` across network instances. Includes available configuration and session state; may also include large BGP RIB data.
`openconfig-system`	System configuration and operational state under `/system` in the OpenConfig system namespace.
`ietf-routing`	Routing configuration and available RIB data under `/routing`. Does not select the legacy `/routing-state` subtree; replies can be large.
`ietf-hardware`	Hardware components and available state under `/hardware`. Does not select the legacy `/hardware-state` subtree.

Select only one getter or explicit filter per request. False flags do not count. Unsupported models may produce empty data or a device RPC error; no automatic vendor fallback is performed.

Subtrees follow the OpenConfig models, IETF routing model, and IETF hardware model.

Examples¤

CLIPython

nf# nornir netconf get plugin ncclient FC spine
nf# nornir netconf get plugin scrapli FC leaf
nf# nornir netconf get plugin scrapli filter-xpath "/*[local-name()='system']" FC leaf

from norfab.core.nfapi import NorFab

with NorFab(inventory="inventory.yaml") as nf:
    client = nf.make_client()
    result = client.run_job(
        "nornir", "netconf_get",
        kwargs={
            "plugin": "scrapli",
            "FC": "leaf",
            "filter_subtree": '<system xmlns="http://openconfig.net/yang/system"/>',
        },
    )
    print(result)

Filter by subtree¤

Retrieve the OpenConfig system hostname. Both backends accept either filter type.

CLIPython

nf# nornir netconf get plugin ncclient filter-subtree '<system xmlns="http://openconfig.net/yang/system"><config><hostname/></config></system>' FL ceos-spine-1

result = client.run_job(
    "nornir", "netconf_get",
    kwargs={
        "plugin": "ncclient",
        "FL": ["ceos-spine-1"],
        "filter_subtree": (
            '<system xmlns="http://openconfig.net/yang/system">'
            '<config><hostname/></config></system>'
        ),
    },
)

Filter by XPath¤

Requires device XPath support. This expression matches local element names regardless of namespace; adapt it to the device's YANG models.

CLIPython

nf# nornir netconf get plugin scrapli filter-xpath "/*[local-name()='system']/*[local-name()='config']/*[local-name()='hostname']" FC leaf

result = client.run_job(
    "nornir", "netconf_get",
    kwargs={
        "plugin": "scrapli",
        "FC": "leaf",
        "filter_xpath": (
            "/*[local-name()='system']"
            "/*[local-name()='config']"
            "/*[local-name()='hostname']"
        ),
    },
)

Use a filter template¤

Either filter accepts a NorFab file URL. File content can use per-host Jinja2 context, for example {{ host.name }}.

CLIPython

nf# nornir netconf get filter-subtree nf://netconf/get_system.xml FC spine
nf# nornir netconf get filter-xpath nf://netconf/get_hostname.xpath FC leaf

result = client.run_job(
    "nornir", "netconf_get",
    kwargs={"FC": "spine", "filter_subtree": "nf://netconf/get_system.xml"},
)

Configure the selected backend using the NETCONF connection inventory.

Retrieve IETF interfaces¤

The ietf-interfaces flag selects the standard /interfaces subtree, including configuration and state exposed there by the device. It requires device support; an empty successful reply remains successful. The legacy /interfaces-state subtree is not selected.

CLIPython

nf# nornir netconf get ietf-interfaces FL router1,router2

result = client.run_job(
    "nornir", "netconf_get",
    kwargs={"ietf_interfaces": True, "FL": ["router1", "router2"]},
)

Only one getter or explicit filter may be selected. Getter flags set to true cannot be combined with each other, filter_subtree, or filter_xpath. False leaves the existing filter selection unchanged.

Retrieve LLDP Neighbors or BGP Sessions¤

CLIPython

nf# nornir netconf get openconfig-lldp FL router1
nf# nornir netconf get openconfig-bgp xmltodict FL router1

result = client.run_job(
    "nornir", "netconf_get",
    kwargs={"FL": ["router1"], "openconfig_bgp": True, "xmltodict": True},
)

Notes¤

NETCONF get reads configuration and operational state. Use Get Configuration to read a specific configuration datastore. Omit both filters to retrieve all available data; large replies can require longer timeouts.
filter_subtree accepts inline XML or a NorFab template URL such as nf://netconf/system.xml. Templates render per host with host, job_data, norfab, and netbox context. job_data accepts data or a YAML file URL.
Filters use device-specific YANG namespaces. Use filter_xpath for server-side XPath filtering; the device must advertise the XPath capability.
filter_subtree and filter_xpath are mutually exclusive. Both support per-host templates and NorFab file URLs. Explicit XPath namespace mappings are not exposed; use namespace-independent expressions where appropriate.
The common xpath processor filters replies locally after retrieval.
Common Nornir filters, processors, retry settings, and serialization options apply.

Troubleshooting¤

Verify the NETCONF SSH port and credentials for connection errors. For RPC errors, check supported YANG models and XML namespaces. XPath filters require the server capability urn:ietf:params:netconf:capability:xpath:1.0; the current cEOS integration image does not advertise it and rejects XPath requests. Empty filtered data can indicate that the selected YANG model is absent on the device.

Task Command Shell Reference¤

nf# man tree nornir.netconf.get

R - required field, M - supports multiline input, D - dynamic key

root
└── nornir:    Nornir service
    └── netconf:    Manage devices using NETCONF
        └── get:    Retrieve configuration and operational state
            ├── timeout:    Job timeout
            ├── workers:    Filter workers to target, default 'all'
            ├── verbose-result:    Control output details, default 'False'
            ├── nowait:    Do not wait for job to complete, default 'False'
            ├── FO:    Filter hosts using a Nornir-Salt Filter Object
            ├── FB:    Filter hosts by name using glob patterns
            ├── FH:    Filter hosts by hostname
            ├── FC:    Filter hosts by name containment pattern
            ├── FR:    Filter hosts by name using regular expressions
            ├── FG:    Filter hosts by group
            ├── FP:    Filter hosts by hostname using IP prefix
            ├── FL:    Filter hosts by names list
            ├── FM:    Filter hosts by platform
            ├── FX:    Exclude hosts by name
            ├── FN:    Negate the host filter match
            ├── on-failed:    Run task on hosts currently marked as failed by Nornir, default 'False'
            ├── to-dict:    Return task results as a dictionary keyed by host, default 'True'
            ├── add-details:    Add Nornir task execution details to results, default 'False'
            ├── progress:    Emit progress events during task execution, default 'True'
            ├── num-workers:    RetryRunner number of threads for task execution
            ├── num-connectors:    RetryRunner number of threads for device connections
            ├── connect-retry:    RetryRunner number of connection attempts
            ├── task-retry:    RetryRunner number of attempts to run each task
            ├── reconnect-on-fail:    RetryRunner reconnects to a host after task failure
            ├── connect-check:    RetryRunner tests TCP connectivity before opening connection
            ├── connect-timeout:    RetryRunner TCP connection check timeout in seconds
            ├── creds-retry:    RetryRunner connection credentials and parameters to retry
            ├── tf:    File group name to save task results on the worker
            ├── tf-skip-failed:    Skip failed task results when saving to file
            ├── diff:    File group name to diff task results against
            ├── diff-last:    Previous saved file version to diff against
            ├── xmltodict:    Convert XML replies to dictionaries with DataProcessor, default 'False'
            ├── xpath:    XPath expression to run with DataProcessor
            ├── xml-flake:    XML flake pattern for DataProcessor
            ├── plugin:    NETCONF backend, default 'NetconfPlugin.ncclient'
            ├── ietf-interfaces:    Retrieve the IETF interfaces subtree, default 'False'
            ├── openconfig-interfaces:    Retrieve the openconfig interfaces subtree, default 'False'
            ├── openconfig-lldp:    Retrieve the openconfig lldp subtree, default 'False'
            ├── openconfig-bgp:    Retrieve the openconfig bgp subtree, default 'False'
            ├── openconfig-system:    Retrieve the openconfig system subtree, default 'False'
            ├── ietf-routing:    Retrieve the ietf routing subtree, default 'False'
            ├── ietf-hardware:    Retrieve the ietf hardware subtree, default 'False'
            ├── filter-subtree:    XML subtree filter or template URL, examples: <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>
            ├── filter-xpath:    XPath filter or template URL, examples: /*
            └── job-data:    Template data or YAML file URL
nf#

Common host filters and job options are also available.

Python API Reference¤

Retrieve device configuration and operational state using NETCONF get.

Parameters:

Name	Type	Description	Default
`job`	`Job`	NorFab job metadata.	required
`plugin`	`str`	NETCONF backend: ncclient (default) or scrapli.	`'ncclient'`
`filter_subtree`	`str`	Optional XML subtree or NorFab template URL. Rendered per host with host, job_data, norfab and netbox context variables. Mutually exclusive with filter_xpath and predefined getters. Omit all selections to retrieve available configuration and state data.	`None`
`filter_xpath`	`str`	XPath expression or NorFab template URL, rendered with the same context as filter_subtree. Requires the device XPath capability. Explicit namespace mappings are not exposed. This filters on the server; the common xpath processor instead filters replies locally after retrieval.	`None`
`job_data`	`Any`	Optional template context data or URL to a YAML data file.	`None`
`ietf_interfaces`	`bool`	Retrieve the standard IETF interfaces subtree. Defaults to false. Mutually exclusive with filter_subtree and filter_xpath. Requires device support for ietf-interfaces; empty replies remain successful. Does not select the legacy interfaces-state subtree. Only one getter or explicit filter may be selected. All getters require device model support; empty replies remain successful.	`False`
`openconfig_interfaces`	`bool`	Retrieve the OpenConfig interfaces subtree. Defaults to false.	`False`
`openconfig_lldp`	`bool`	Retrieve the OpenConfig LLDP subtree. Defaults to false.	`False`
`openconfig_bgp`	`bool`	Retrieve OpenConfig BGP configuration and state across network instances. Defaults to false. May include large RIB data.	`False`
`openconfig_system`	`bool`	Retrieve the OpenConfig system subtree. Defaults to false.	`False`
`ietf_routing`	`bool`	Retrieve the IETF routing subtree. Defaults to false.	`False`
`ietf_hardware`	`bool`	Retrieve the IETF hardware subtree. Defaults to false.	`False`
`**kwargs`	`Any`	Common Nornir host filters, processors, retry options, XML processors (xmltodict, xpath, xml_flake), to_dict and add_details serialization options.	`{}`

Returns:

Name	Type	Description
`Result`	`Result`	XML replies under each host's get key (rpc for unfiltered Scrapli requests), or serialized records when to_dict is false. RPC and connection errors mark host results as failed; unmatched hosts return status no_match.

Raises:

Type	Description
`FileNotFoundError`	If a referenced template cannot be fetched.

Source code in norfab\workers\nornir_worker\netconf_task.py

@Task(
    fastapi={"methods": ["POST"]},
    input=NetconfGetInput,
    output=NetconfResult,
    mcp={
        "annotations": {
            "title": "NETCONF Get Data",
            "readOnlyHint": True,
            "destructiveHint": False,
            "idempotentHint": True,
            "openWorldHint": True,
        }
    },
)
def netconf_get(
    self,
    job: Job,
    plugin: str = "ncclient",
    filter_subtree: str = None,
    filter_xpath: str = None,
    job_data: Any = None,
    ietf_interfaces: bool = False,
    openconfig_interfaces: bool = False,
    openconfig_lldp: bool = False,
    openconfig_bgp: bool = False,
    openconfig_system: bool = False,
    ietf_routing: bool = False,
    ietf_hardware: bool = False,
    **kwargs: Any,
) -> Result:
    """Retrieve device configuration and operational state using NETCONF get.

    Args:
        job: NorFab job metadata.
        plugin: NETCONF backend: ncclient (default) or scrapli.
        filter_subtree: Optional XML subtree or NorFab template URL. Rendered
            per host with host, job_data, norfab and netbox context variables.
            Mutually exclusive with filter_xpath and predefined getters. Omit
            all selections to retrieve available configuration and state data.
        filter_xpath: XPath expression or NorFab template URL, rendered with
            the same context as filter_subtree. Requires the device XPath
            capability. Explicit namespace mappings are not exposed. This
            filters on the server; the common xpath processor instead
            filters replies locally after retrieval.
        job_data: Optional template context data or URL to a YAML data file.
        ietf_interfaces: Retrieve the standard IETF interfaces subtree.
            Defaults to false. Mutually exclusive with filter_subtree and
            filter_xpath. Requires device support for ietf-interfaces;
            empty replies remain successful. Does not select the legacy
            interfaces-state subtree. Only one getter or explicit filter
            may be selected. All getters require device model support;
            empty replies remain successful.
        openconfig_interfaces: Retrieve the OpenConfig interfaces subtree. Defaults to false.
        openconfig_lldp: Retrieve the OpenConfig LLDP subtree. Defaults to false.
        openconfig_bgp: Retrieve OpenConfig BGP configuration and state across
            network instances. Defaults to false. May include large RIB data.
        openconfig_system: Retrieve the OpenConfig system subtree. Defaults to false.
        ietf_routing: Retrieve the IETF routing subtree. Defaults to false.
        ietf_hardware: Retrieve the IETF hardware subtree. Defaults to false.
        **kwargs: Common Nornir host filters, processors, retry options,
            XML processors (xmltodict, xpath, xml_flake), to_dict and
            add_details serialization options.

    Returns:
        Result: XML replies under each host's get key (rpc for unfiltered
            Scrapli requests), or serialized
            records when to_dict is false. RPC and connection errors mark
            host results as failed; unmatched hosts return status no_match.

    Raises:
        FileNotFoundError: If a referenced template cannot be fetched.

    """
    for getter, selected in {
        "ietf_interfaces": ietf_interfaces,
        "openconfig_interfaces": openconfig_interfaces,
        "openconfig_lldp": openconfig_lldp,
        "openconfig_bgp": openconfig_bgp,
        "openconfig_system": openconfig_system,
        "ietf_routing": ietf_routing,
        "ietf_hardware": ietf_hardware,
    }.items():
        if selected:
            filter_subtree = NETCONF_GETTERS[getter]
    # Scrapli get requires a filter; use an unfiltered RPC when omitted.
    if plugin == "scrapli" and filter_subtree is None and filter_xpath is None:
        return self._run_netconf(
            job, call="rpc", plugin=plugin, filter_="<get/>", **kwargs
        )
    template = None
    filter_type = None
    if filter_subtree is not None:
        template = filter_subtree
        filter_type = "subtree"
    if filter_xpath is not None:
        template = filter_xpath
        filter_type = "xpath"
    render = None
    if template is not None:
        if plugin == "ncclient":
            render = {"filter": template}
            kwargs["ftype"] = filter_type
        else:
            render = {"filter_": template}
            kwargs["filter_type"] = filter_type
    return self._run_netconf(
        job,
        call="get",
        plugin=plugin,
        render=render,
        job_data=job_data,
        **kwargs,
    )