NETCONF Commit Configuration

Use netconf_commit to activate candidate configuration or confirm a pending confirmed commit on selected devices.

Use Cases

• Activate staged configuration after reviewing and validating candidate changes.
• Apply changes with a rollback timer, then confirm them after checking the network.
• Confirm a persistent commit from another NETCONF session using its token.

How It Works

A normal commit copies candidate configuration into running configuration. With confirmed=True, the device rolls back unless a subsequent commit confirms the change before confirm_delay expires. Omit the delay to use the device default. Unlike netconf_transaction, this task does not send the final confirmation automatically.

The device must support candidate configuration and, for confirmed commits, the confirmed-commit capability. All pending candidate changes are committed; this task does not edit, lock, or validate configuration.

Output

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

Examples

Commit candidate configuration

CLIPython

nf# nornir netconf commit FL router-1

from norfab.core.nfapi import NorFab

with NorFab(inventory="inventory.yaml") as nf:
    client = nf.make_client()
    result = client.run_job(
        "nornir", "netconf_commit", kwargs={"FL": ["router-1"]}
    )
    print(result)

Commit with a rollback timer

Use a persistent token to confirm independently of the original connection. After checking connectivity and services, send the final confirmation before the timer expires. If the checks fail, leave the commit unconfirmed to let the device roll back.

CLIPython

nf# nornir netconf commit confirmed True confirm-delay 120 persist change-123 FL router-1
nf# nornir netconf commit persist-id change-123 FL router-1

result = client.run_job(
    "nornir", "netconf_commit",
    kwargs={
        "FL": ["router-1"],
        "confirmed": True,
        "confirm_delay": 120,
        "persist": "change-123",
    },
)
# Check the result, connectivity, and services before confirming.
result = client.run_job(
    "nornir", "netconf_commit",
    kwargs={"FL": ["router-1"], "persist_id": "change-123"},
)

Without a persistent token, confirmation must use the original NETCONF session; target the same worker and backend, and keep its connection open. The confirm-delay controls the device rollback timer; the common timeout option controls how long the client waits for the job. Retries may repeat a commit.

Task Command Shell Reference

nf#man tree nornir.netconf.commit

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

root
└── nornir:    Nornir service
    └── netconf:    Manage devices using NETCONF
        └── commit:    Commit NETCONF candidate 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'
            ├── confirmed:    Start a confirmed commit, default 'False'
            ├── confirm-delay:    Confirmed commit rollback timeout in seconds; omit for device default
            ├── persist:    Token to keep a confirmed commit across sessions
            └── persist-id:    Token identifying the persistent confirmed commit to confirm
nf#

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

Python API Reference

Commit candidate configuration or confirm a pending confirmed commit.

Parameters:

Name	Type	Description	Default
job	Job	NorFab job metadata.	required
plugin	str	NETCONF backend: ncclient (default) or scrapli.	'ncclient'
confirmed	bool	Start a confirmed commit with automatic rollback unless subsequently confirmed. Defaults to false. Requires device support.	False
confirm_delay	int	Rollback timeout in seconds for a confirmed commit. Omit for the device default. Requires confirmed=True. This is separate from the client's job timeout.	None
persist	str	Token allowing a confirmed commit to survive session closure. Requires confirmed=True and NETCONF persistent commit support.	None
persist_id	str	Token from a previous persistent confirmed commit to confirm. Mutually exclusive with confirmed=True and persist.	None
**kwargs	Any	Common host filters, processors, retries, XML processors (xmltodict, xpath, xml_flake), to_dict and add_details options.	{}

Returns:

Name	Type	Description
Result	Result	XML replies under each host's commit key, normally an ok reply, or serialized records when to_dict=False. RPC, capability and connection errors mark hosts failed; unmatched hosts return status no_match. Requires candidate support. Commits all pending candidate changes without editing, locking, or validating them. Confirmed commits are not automatically finalized by this task; call again without confirmed to confirm, supplying persist_id for a persistent commit. Nonpersistent confirmation requires the original NETCONF session. Retries may repeat commits.

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

@Task(
    fastapi={"methods": ["POST"]},
    input=NetconfCommitInput,
    output=NetconfResult,
    mcp={
        "annotations": {
            "title": "NETCONF Commit Configuration",
            "readOnlyHint": False,
            "destructiveHint": True,
            "idempotentHint": False,
            "openWorldHint": True,
        }
    },
)
def netconf_commit(
    self,
    job: Job,
    plugin: str = "ncclient",
    confirmed: bool = False,
    confirm_delay: int = None,
    persist: str = None,
    persist_id: str = None,
    **kwargs: Any,
) -> Result:
    """Commit candidate configuration or confirm a pending confirmed commit.

    Args:
        job: NorFab job metadata.
        plugin: NETCONF backend: ncclient (default) or scrapli.
        confirmed: Start a confirmed commit with automatic rollback unless
            subsequently confirmed. Defaults to false. Requires device support.
        confirm_delay: Rollback timeout in seconds for a confirmed commit.
            Omit for the device default. Requires confirmed=True. This is
            separate from the client's job timeout.
        persist: Token allowing a confirmed commit to survive session closure.
            Requires confirmed=True and NETCONF persistent commit support.
        persist_id: Token from a previous persistent confirmed commit to
            confirm. Mutually exclusive with confirmed=True and persist.
        **kwargs: Common host filters, processors, retries, XML processors
            (xmltodict, xpath, xml_flake), to_dict and add_details options.

    Returns:
        Result: XML replies under each host's commit key, normally an ok
            reply, or serialized records when to_dict=False. RPC, capability
            and connection errors mark hosts failed; unmatched hosts return
            status no_match. Requires candidate support. Commits all pending
            candidate changes without editing, locking, or validating them.
            Confirmed commits are not automatically finalized by this task;
            call again without confirmed to confirm, supplying persist_id
            for a persistent commit. Nonpersistent confirmation requires the
            original NETCONF session. Retries may repeat commits.
    """
    if confirm_delay is not None:
        kwargs["timeout"] = (
            str(confirm_delay) if plugin == "ncclient" else confirm_delay
        )
    return self._run_netconf(
        job,
        call="commit",
        plugin=plugin,
        confirmed=confirmed,
        persist=persist,
        persist_id=persist_id,
        **kwargs,
    )