Documentation

netconf_rpc - Execute operations on NETCONF enabled network devices.

New in version 2.6.

Synopsis

  • NETCONF is a network management protocol developed and standardized by the IETF. It is documented in RFC 6241.
  • This module allows the user to execute NETCONF RPC requests as defined by IETF RFC standards as well as proprietary requests.

Requirements

The below requirements are needed on the host that executes this module.

  • ncclient (>=v0.5.2)
  • jxmlease

Parameters

Parameter Choices/Defaults Comments
content
This argument specifies the optional request content (all RPC attributes). The content value can either be provided as XML formatted string or as dictionary.
display
    Choices:
  • json
  • pretty
  • xml
Encoding scheme to use when serializing output from the device. The option json will serialize the output as JSON data. If the option value is json it requires jxmlease to be installed on control node. The option pretty is similar to received XML response but is using human readable format (spaces, new lines). The option value xml is similar to received XML response but removes all XML namespaces.
rpc
This argument specifies the request (name of the operation) to be executed on the remote NETCONF enabled device.
xmlns
NETCONF operations not defined in rfc6241 typically require the appropriate XML namespace to be set. In the case the request option is not already provided in XML format, the namespace can be defined by the xmlns option.

Notes

Note

  • This module requires the NETCONF system service be enabled on the remote device being managed.
  • This module supports the use of connection=netconf
  • To execute get-config, get or edit-config requests it is recommended to use the Ansible netconf_get and netconf_config modules.

Examples

- name: lock candidate
  netconf_rpc:
    rpc: lock
    content:
      target:
        candidate:

- name: unlock candidate
  netconf_rpc:
    rpc: unlock
    xmlns: "urn:ietf:params:xml:ns:netconf:base:1.0"
    content: "{'target': {'candidate': None}}"

- name: discard changes
  netconf_rpc:
    rpc: discard-changes

- name: get-schema
  netconf_rpc:
    rpc: get-schema
    xmlns: urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring
    content:
      identifier: ietf-netconf
      version: "2011-06-01"

- name: copy running to startup
  netconf_rpc:
    rpc: copy-config
    content:
      source:
        running:
      target:
        startup:

- name: get schema list with JSON output
  netconf_rpc:
    rpc: get
    content: |
      <filter>
        <netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
          <schemas/>
        </netconf-state>
      </filter>
    display: json

- name: get schema using XML request
  netconf_rpc:
    rpc: "get-schema"
    xmlns: "urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring"
    content: |
      <identifier>ietf-netconf-monitoring</identifier>
      <version>2010-10-04</version>
    display: json

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
output
complex
when the display format is selected as JSON it is returned as dict type, if the display format is xml or pretty pretty it is retured as a string apart from low-level errors (such as action plugin).
Based on the value of display option will return either the set of transformed XML to JSON format from the RPC response with type dict or pretty XML string response (human-readable) or response with namespace removed from XML string.

  formatted_output

stdout
string
always apart from low-level errors (such as action plugin)
The raw XML string containing configuration or state data received from the underlying ncclient library.

Sample:
...
stdout_lines
list
always apart from low-level errors (such as action plugin)
The value of stdout split into a list

Sample:
['...', '...']


Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as network which means that it is maintained by the Ansible Network Team. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Network Team, see here.

Support

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

Author

  • Ganesh Nalawade (@ganeshrn)
  • Sven Wisotzky (@wisotzky)

Hint

If you notice any issues in this documentation you can edit this document to improve it.