Ansible NETCONF Connection Plugin: Network Configuration Protocol Complete Guide

By Luca Berton · Published 2024-01-01 · Category: installation

Complete guide to the Ansible NETCONF connection plugin for structured XML network management with Junos, IOS-XR, and NX-OS.

The ansible.netcommon.netconf connection plugin provides structured, transactional network device management using the NETCONF protocol (RFC 6241). Unlike CLI-based connections that scrape text output, NETCONF uses XML for machine-readable configuration and state data.

Source: Ansible netconf connection docs

What Is NETCONF?

NETCONF (Network Configuration Protocol) provides:

Structured data — XML-based configuration and state (no screen-scraping)
Transactions — atomic commit/rollback of configuration changes
Validation — candidate configuration validated before applying
Filtering — retrieve only the data you need via XPath or subtree filters
Standard protocol — RFC 6241, supported by all major network vendors

When to Use NETCONF vs CLI

Feature	NETCONF	CLI (network_cli)
Data format	Structured XML	Unstructured text
Parsing	Native XML/XPath	Regex/TextFSM needed
Transactions	Full commit/rollback	Limited (vendor-dependent)
Validation	Pre-commit validation	Run and hope
Performance	Better for bulk reads	Better for simple commands
Vendor support	Juniper, Cisco XR/NX, Nokia, Huawei	Almost all vendors
Best for	Configuration management, auditing	Troubleshooting, show commands

Setup

Install Requirements

# Install the netcommon collection
ansible-galaxy collection install ansible.netcommon

# Install ncclient (NETCONF client library)
pip install ncclient

# Install xmltodict for easier XML handling
pip install xmltodict

Inventory Configuration

[routers]
router01 ansible_host=192.168.1.1

[routers:vars]
ansible_connection=ansible.netcommon.netconf
ansible_network_os=junipernetworks.junos.junos
ansible_user=admin
ansible_password={{ vault_router_password }}
ansible_port=830

Connection Plugin Parameters

Parameter	Default	Description
`host`	inventory hostname	Target device hostname/IP
`port`	830	NETCONF SSH port
`network_os`	—	Required: device platform
`remote_user`	—	SSH username
`password`	—	SSH password
`private_key_file`	—	SSH private key path
`ssh_type`	`auto`	SSH library: `auto`, `paramiko`, `libssh`
`host_key_checking`	True	Verify host keys
`look_for_keys`	True	Search for SSH keys in `~/.ssh/`
`hostkey_verify`	True	Strict host key verification

Examples

Get Configuration (Juniper Junos)

---
- name: Get Junos configuration via NETCONF
  hosts: junos_routers
  connection: ansible.netcommon.netconf
  gather_facts: false
  tasks:
    - name: Get full configuration
      junipernetworks.junos.junos_config:
        backup: true
      register: config_backup

    - name: Get interfaces configuration only
      ansible.netcommon.netconf_get:
        source: running
        filter: |
          <configuration>
            <interfaces/>
          </configuration>
      register: interfaces

    - name: Display interface config
      ansible.builtin.debug:
        var: interfaces.output

Edit Configuration (Cisco IOS-XR)

---
- name: Configure Cisco IOS-XR via NETCONF
  hosts: iosxr_routers
  connection: ansible.netcommon.netconf
  gather_facts: false
  vars:
    ansible_network_os: cisco.iosxr.iosxr
  tasks:
    - name: Configure interface description
      ansible.netcommon.netconf_config:
        content: |
          <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
            <interface-configurations xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg">
              <interface-configuration>
                <active>act</active>
                <interface-name>GigabitEthernet0/0/0/0</interface-name>
                <description>Configured by Ansible NETCONF</description>
              </interface-configuration>
            </interface-configurations>
          </config>
        target: candidate
        default_operation: merge
        commit: true

    - name: Validate and commit
      ansible.netcommon.netconf_rpc:
        rpc: validate
        content: |
          <source><candidate/></source>

RPC Operations

---
- name: Execute NETCONF RPC operations
  hosts: network_devices
  connection: ansible.netcommon.netconf
  gather_facts: false
  tasks:
    - name: Lock candidate configuration
      ansible.netcommon.netconf_rpc:
        rpc: lock
        content: |
          <target><candidate/></target>

    - name: Get device capabilities
      ansible.netcommon.netconf_get:
        display: json
      register: capabilities

    - name: Unlock candidate
      ansible.netcommon.netconf_rpc:
        rpc: unlock
        content: |
          <target><candidate/></target>

Supported Platforms

Vendor	Network OS	Collection
Juniper	Junos	`junipernetworks.junos`
Cisco	IOS-XR	`cisco.iosxr`
Cisco	NX-OS	`cisco.nxos`
Nokia	SR OS	`nokia.sros`
Huawei	CloudEngine	`community.network`
OpenConfig	Any vendor	`ansible.netcommon`

NETCONF Modules Reference

Module	Purpose
`ansible.netcommon.netconf_get`	Retrieve configuration or state data
`ansible.netcommon.netconf_config`	Edit device configuration
`ansible.netcommon.netconf_rpc`	Execute arbitrary NETCONF RPC

FIPS-Compliant NETCONF with libssh

Starting with ansible.netcommon v8.4.0, NETCONF connections support the use_libssh option for FIPS-compliant SSH transport:

# inventory — FIPS-compliant NETCONF
[routers:vars]
ansible_connection=ansible.netcommon.netconf
ansible_netconf_ssh_type=libssh
ansible_network_os=junipernetworks.junos.junos

This is essential for public sector and regulated industries where FIPS mode is mandatory on network devices. See the libssh connection guide for full migration details.

Troubleshooting

Issue	Solution
`ncclient not found`	`pip install ncclient`
Connection refused on port 830	Enable NETCONF on device: `set system services netconf ssh` (Junos)
XML parse error	Validate XML with `xmllint` before sending
`OperationNotSupportedError`	Device doesn't support requested NETCONF operation
Timeout on large configs	Increase `ansible_command_timeout`

Enable NETCONF on Devices

Juniper Junos:

set system services netconf ssh port 830
commit

Cisco IOS-XR:

netconf-yang agent ssh
ssh server netconf port 830
commit

Cisco NX-OS:

feature netconf

FAQ

Do all network devices support NETCONF?

No. NETCONF requires vendor support. Most enterprise-grade devices (Juniper, Cisco XR/NX, Nokia) support it. Older or consumer devices typically don't.

Should I use NETCONF or CLI for network automation?

Use NETCONF when you need structured data, transactional commits, or configuration validation. Use CLI (network_cli) for quick troubleshooting or devices without NETCONF support.

What's the difference between NETCONF and RESTCONF?

NETCONF uses SSH (port 830) with XML. RESTCONF uses HTTPS with JSON or XML. Both access the same YANG data models. RESTCONF is newer and often easier for API integration.

Can I use NETCONF with the new libssh plugin?

Yes. Set ssh_type: libssh in the connection variables to use libssh instead of Paramiko for the underlying SSH transport.

What port does NETCONF use?

The standard NETCONF port is 830 (SSH subsystem). Some devices allow configuration on alternative ports.

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton