ansible.netcommon.netconf_config 模块 – Netconf 设备配置

注意

此模块是 ansible.netcommon 集合 (版本 7.1.0) 的一部分。

如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用： ansible-galaxy collection install ansible.netcommon。您需要其他要求才能使用此模块，请参阅 要求 获取详细信息。

要在 playbook 中使用它，请指定： ansible.netcommon.netconf_config。

ansible.netcommon 1.0.0 中的新增功能

概要

• Netconf 是由 IETF 开发和标准化的网络管理协议。它在 RFC 6241 中有记录。

• 此模块允许用户将配置 XML 文件发送到 Netconf 设备，并检测配置是否发生更改。

要求

以下要求是在执行此模块的主机上所需的。

• ncclient

参数

参数	注释
backup 布尔值	此参数将导致模块在进行任何更改之前创建远程设备当前 running-config 的完整备份。如果未给出 backup_options 值，则备份文件将写入 playbook 根目录或角色根目录中的 backup 文件夹（如果 playbook 是 Ansible 角色的一部分）。如果目录不存在，则会创建它。 选项 false ← (默认) true
backup_options 字典	这是一个包含与备份文件路径相关的可配置选项的字典对象。只有当 backup 设置为 *yes* 时，才会读取此选项的值；如果 backup 设置为 *no*，则此选项将被静默忽略。
dir_path 路径	此选项提供以目录名结尾的路径，将在其中存储备份配置文件。如果目录不存在，它将首先被创建，文件名要么是 filename 的值，要么是 filename 选项描述中所述的默认文件名。如果没有给出路径值，则会在当前工作目录中创建一个 *backup* 目录，并将备份配置复制到 *backup* 目录中的 filename。
filename 字符串	用于存储备份配置的文件名。如果没有给出文件名，它将根据主机名、当前时间和日期以 <主机名>_config.<当前日期>@<当前时间> 格式生成。
commit 布尔值	此布尔标志控制在编辑候选数据存储后是否应提交配置更改。此选项仅在远程 Netconf 服务器支持：candidate 功能时才受支持。如果该值设置为 *False*，则在 edit-config 操作后不会发出 commit，用户需要显式处理 commit 或 discard-changes。 选项 false true ← (默认)
confirm 整数	此参数将为提交配置超时值，在自动回滚之前确认提交。如果 confirm_commit 参数设置为 False，则此参数将被静默忽略。如果此参数的值设置为 0，则会立即确认提交。远程主机必须支持：candidate 和：confirmed-commit 功能才能使用此选项。 默认值： 0
confirm_commit 布尔值	此参数将在远程设备上执行提交操作。它可用于确认之前的提交。 选项 false ← (默认) true
content 别名：xml 任意	设备数据模型定义的配置数据，该值可以是 xml 字符串格式、文本格式或 JSON 格式的 Python 字典表示形式。 如果是 json 字符串格式，则在推送到远程主机之前，将使用 xmltodict 库将其转换为相应的 xml 字符串。 如果此选项的值为 *text* 格式，则远程 Netconf 服务器应支持该格式。 如果 content 选项的值为 *xml* 格式，则 xml 值应具有 *config* 作为根标签。
default_operation 字符串	<edit-config> rpc 的默认操作，有效值为 *merge*、*replace* 和 *none*。如果默认值为 merge，则 content 选项中的配置数据将合并到 target 数据存储中的对应级别。如果值为 replace，则 content 选项中的数据将完全替换 target 数据存储中的配置。如果值为 none，则 target 数据存储不受 config 选项中配置的影响，除非传入的配置数据使用 operation 操作请求不同的操作。 选项 "merge" "replace" "none"
delete 布尔值	它指示模块从 target 数据存储中提到的值中删除配置。 选项 false ← (默认) true
error_option 字符串	此选项控制在编辑配置期间发生错误后 netconf 服务器的操作。 如果 *error_option=stop-on-error*，则在第一个错误时中止配置编辑。 如果 *error_option=continue-on-error*，则继续处理配置数据中的错误。如果发生任何错误，则会记录错误并生成负面响应。 如果 *error_option=rollback-on-error*，则如果发生任何错误，则回滚到原始配置。这需要远程 Netconf 服务器支持 *error_option=rollback-on-error* 功能。 选项 "stop-on-error" ← (默认) "continue-on-error" "rollback-on-error"
format 字符串	作为 content 值提供的配置的格式。 如果是 json 字符串格式，则在推送到远程主机之前，将使用 xmltodict 库将其转换为相应的 xml 字符串。 对于配置的 *text* 格式，远程 Netconf 服务器应支持。 如果没有给出 format 选项的值，它会尝试将 content 选项的数据格式猜测为 *xml*、*json* 或 *text* 之一。 如果未识别数据格式，则默认设置为 *xml*。 选项 "xml" "text" "json"
get_filter 任意	此参数指定充当过滤器的 XML 字符串，用于限制从远程设备检索的数据部分，在调用 edit_config 后比较设备的之前和之后状态时使用。如果未指定，则根据 source 选项的值返回整个配置或状态数据以进行比较。get_filter 值可以是 XML 字符串、XPath 或 JSON 字符串或原生 Python 字典，如果过滤器采用 XPath 格式，则远程主机上运行的 NETCONF 服务器应支持 xpath 功能，否则将导致错误。
lock 字符串	指示模块显式锁定指定为 target 的数据存储。通过将选项值设置为 *always*，它将显式锁定 target 选项中提到的数据存储。如果值为 *never*，则不会锁定 target 数据存储。值 *if-supported* 仅当远程 Netconf 服务器支持时才锁定 target 数据存储。 选项 "never" "always" ← (默认) "if-supported"
save 布尔值	save 参数指示模块如果已更改，并且 Netconf 服务器支持 :startup 功能，则将 target 数据存储中的配置保存到 startup-config。 选项 false ← (默认) true
source_datastore 别名：source 字符串	用作源的配置数据存储的名称，用于将配置复制到 target 选项提到的数据存储。值可以是 *running*、*candidate*、*startup* 或远程 URL。
target 别名：datastore 字符串	要编辑的配置数据存储的名称。 - auto，使用 candidate 并回退到 running - candidate，编辑 <candidate/> 数据存储然后提交 - running，直接编辑 <running/> 数据存储。 选项 "auto" ← (默认) "candidate" "running"
validate 布尔值	如果设置此布尔标志，则验证 target 选项中给出的数据存储的内容。要使此选项有效，远程 Netconf 服务器应支持 :validate 功能。 选项 false ← (默认) true

注释

注意

• 此模块要求在要管理的远程设备上启用 netconf 系统服务。

• 此模块支持具有和不具有 candidate 和 confirmed-commit 功能的设备。它将始终使用更安全的功能。

• 此模块支持使用 connection=netconf。

• 此模块在 ansible_network_os 网络平台上受支持。有关详细信息，请参见 :ref:`网络平台选项 <platform_options>`。

示例

- name: use lookup filter to provide xml configuration
  ansible.netcommon.netconf_config:
    content: "{{ lookup('file', './config.xml') }}"

- name: set ntp server in the device
  ansible.netcommon.netconf_config:
    content: |
      <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
          <system xmlns="urn:ietf:params:xml:ns:yang:ietf-system">
              <ntp>
                  <enabled>true</enabled>
                  <server>
                      <name>ntp1</name>
                      <udp><address>127.0.0.1</address></udp>
                  </server>
              </ntp>
          </system>
      </config>

- name: wipe ntp configuration
  ansible.netcommon.netconf_config:
    content: |
      <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
          <system xmlns="urn:ietf:params:xml:ns:yang:ietf-system">
              <ntp>
                  <enabled>false</enabled>
                  <server operation="remove">
                      <name>ntp1</name>
                  </server>
              </ntp>
          </system>
      </config>

- name: configure interface while providing different private key file path (for connection=netconf)
  ansible.netcommon.netconf_config:
    backup: true
  register: backup_junos_location
  vars:
    ansible_private_key_file: /home/admin/.ssh/newprivatekeyfile

- name: configurable backup path
  ansible.netcommon.netconf_config:
    backup: true
    backup_options:
      filename: backup.cfg
      dir_path: /home/user

- name: "configure using direct native format configuration (cisco iosxr)"
  ansible.netcommon.netconf_config:
    format: json
    content:
      {
        "config":
          {
            "interface-configurations":
              {
                "@xmlns": "http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg",
                "interface-configuration":
                  {
                    "active": "act",
                    "description": "test for ansible Loopback999",
                    "interface-name": "Loopback999",
                  },
              },
          },
      }
    get_filter:
      {
        "interface-configurations":
          {
            "@xmlns": "http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg",
            "interface-configuration": null,
          },
      }

- name: "configure using json string format configuration (cisco iosxr)"
  ansible.netcommon.netconf_config:
    format: json
    content: |
      {
          "config": {
              "interface-configurations": {
                  "@xmlns": "http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg",
                  "interface-configuration": {
                      "active": "act",
                      "description": "test for ansible Loopback999",
                      "interface-name": "Loopback999"
                  }
              }
          }
      }
    get_filter: |
      {
            "interface-configurations": {
                "@xmlns": "http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg",
                "interface-configuration": null
            }
        }

# Make a round-trip interface description change, diff the before and after
# this demonstrates the use of the native display format and several utilities
# from the ansible.utils collection

- name: Define the openconfig interface filter
  set_fact:
    filter:
      interfaces:
        "@xmlns": "http://openconfig.net/yang/interfaces"
        interface:
          name: Ethernet2

- name: Get the pre-change config using the filter
  ansible.netcommon.netconf_get:
    source: running
    filter: "{{ filter }}"
    display: native
  register: pre

- name: Update the description
  ansible.utils.update_fact:
    updates:
      - path: pre.output.data.interfaces.interface.config.description
        value: "Configured by ansible {{ 100 | random }}"
  register: updated

- name: Apply the new configuration
  ansible.netcommon.netconf_config:
    content:
      config:
        interfaces: "{{ updated.pre.output.data.interfaces }}"

- name: Get the post-change config using the filter
  ansible.netcommon.netconf_get:
    source: running
    filter: "{{ filter }}"
    display: native
  register: post

- name: Show the differences between the pre and post configurations
  ansible.utils.fact_diff:
    before: "{{ pre.output.data|ansible.utils.to_paths }}"
    after: "{{ post.output.data|ansible.utils.to_paths }}"
# TASK [Show the differences between the pre and post configurations] ********
# --- before
# +++ after
# @@ -1,11 +1,11 @@
#  {
# -    "@time-modified": "2020-10-23T12:27:17.462332477Z",
# +    "@time-modified": "2020-10-23T12:27:21.744541708Z",
#      "@xmlns": "urn:ietf:params:xml:ns:netconf:base:1.0",
#      "interfaces.interface.aggregation.config['fallback-timeout']['#text']": "90",
#      "interfaces.interface.aggregation.config['fallback-timeout']['@xmlns']": "http://arista.com/yang/openconfig/interfaces/augments",
#      "interfaces.interface.aggregation.config['min-links']": "0",
#      "interfaces.interface.aggregation['@xmlns']": "http://openconfig.net/yang/interfaces/aggregate",
# -    "interfaces.interface.config.description": "Configured by ansible 56",
# +    "interfaces.interface.config.description": "Configured by ansible 67",
#      "interfaces.interface.config.enabled": "true",
#      "interfaces.interface.config.mtu": "0",
#      "interfaces.interface.config.name": "Ethernet2",

返回值

常见的返回值已记录在 此处，以下是此模块独有的字段

键	描述
backup_path 字符串	备份文件的完整路径 返回：当备份为 yes 时 示例： "/playbooks/ansible/backup/config.2016-07-16@22:28:34"
diff 字典	如果在运行时启用了 –diff 选项，则之前和之后配置更改将作为 before 和 after 键的一部分返回。 返回：启用 diff 时 示例： {"after": "<rpc-reply> <data> <configuration> <version>17.3R1.10</version>...<--snip-->", "before": "<rpc-reply> <data> <configuration> <version>17.3R1.10</version>...<--snip-->"}
server_capabilities 列表 / 元素=字符串	服务器的功能列表 返回：成功 示例： ["urn:ietf:params:netconf:base:1.1", "urn:ietf:params:netconf:capability:confirmed-commit:1.0", "urn:ietf:params:netconf:capability:candidate:1.0"]

作者

• Leandro Lisboa Penz (@lpenz)

• Ganesh Nalawade (@ganeshrn)

收藏链接

• 问题跟踪器
• 存储库（源代码）