NETCONF Validate Configuration

Use netconf_validate to check a device configuration datastore for errors without changing the configuration.

Use Cases

Check staged candidate changes before committing them, or check running or startup configuration for errors reported by the device.

How It Works

The task sends a NETCONF validate request for the selected datastore, defaulting to candidate. The device must support the validate capability and the selected datastore. Validation does not commit, discard, or lock configuration, and does not check connectivity or service health.

Output

Each host's validate key contains the XML reply, normally <ok/> on success. Validation errors, unsupported capabilities, and connection errors mark the host as failed. add_details=True includes execution metadata; to_dict=False returns serialized records. XML processors can convert or filter replies.

Examples

CLIPython

nf# nornir netconf validate source candidate FL ceos-leaf-1

from norfab.core.nfapi import NorFab

with NorFab(inventory="inventory.yaml") as nf:
    client = nf.make_client()
    result = client.run_job(
        "nornir", "netconf_validate",
        kwargs={"source": "candidate", "FL": ["ceos-leaf-1"]},
    )
    print(result)

Task Command Shell Reference

nf#man tree nornir.netconf.validate

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

root
└── nornir:    Nornir service
    └── netconf:    Manage devices using NETCONF
        └── validate:    Validate NETCONF configuration
            ├── 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'
            └── source:    Datastore to validate, default 'NetconfConfigSource.candidate'
nf#

Common host filters, job options, XML processors, and serialization options are also available.

Python API Reference

Validate a device configuration datastore without applying changes.

Parameters:

Name	Type	Description	Default
job	Job	NorFab job metadata.	required
source	str	Datastore to validate: candidate (default), running, or startup. Requires device support for the selected datastore.	'candidate'
plugin	str	NETCONF backend: ncclient (default) or scrapli.	'ncclient'
**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 validate key, normally an ok reply on success, or serialized records when to_dict=False. Validation, capability and connection errors mark hosts as failed; unmatched hosts return status no_match. Requires the NETCONF validate capability. Does not edit, lock, commit, or discard configuration. A successful validation does not check connectivity or service health.

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

@Task(
    fastapi={"methods": ["POST"]},
    input=NetconfValidateInput,
    output=NetconfResult,
    mcp={
        "annotations": {
            "title": "NETCONF Validate Configuration",
            "readOnlyHint": True,
            "destructiveHint": False,
            "idempotentHint": True,
            "openWorldHint": True,
        }
    },
)
def netconf_validate(
    self,
    job: Job,
    source: str = "candidate",
    plugin: str = "ncclient",
    **kwargs: Any,
) -> Result:
    """Validate a device configuration datastore without applying changes.

    Args:
        job: NorFab job metadata.
        source: Datastore to validate: candidate (default), running, or
            startup. Requires device support for the selected datastore.
        plugin: NETCONF backend: ncclient (default) or scrapli.
        **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 validate key, normally an
            ok reply on success, or serialized records when to_dict=False.
            Validation, capability and connection errors mark hosts as
            failed; unmatched hosts return status no_match. Requires the
            NETCONF validate capability. Does not edit, lock, commit, or
            discard configuration. A successful validation does not check
            connectivity or service health.
    """
    return self._run_netconf(
        job, call="validate", plugin=plugin, source=source, **kwargs
    )