Ansible NETCONF Connection Plugin: Network Configuration Protocol Complete Guide

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

See also: Ansible Network Automation: Configure Cisco, Arista, and Juniper at Scale

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

See also: AAP 2.6 Network Automation: Cisco, Arista, Juniper, and Multi-Vendor Management

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>

See also: Ansible libssh Connection Plugin: Replacing Paramiko for Better SSH Performance and Security

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.

Related Articles

• Ansible libssh Connection Plugin • Ansible Network Automation: Cisco, Arista, Juniper at Scale • Red Hat Ansible Automation Platform 2.7: What's New