community.routeros.api_modify 模块 – 使用 API 修改路径数据

注意

此模块是 community.routeros 集合（版本 3.1.0）的一部分。

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

要安装它，请使用： ansible-galaxy collection install community.routeros。 您需要进一步的要求才能使用此模块，请参阅 要求 了解详细信息。

要在 playbook 中使用它，请指定： community.routeros.api_modify。

community.routeros 2.2.0 中的新增功能

概要

要求

执行此模块的主机需要以下要求。

  • Python 2.6 需要 ordereddict

  • Python >= 3.6（适用于 librouteros）

  • librouteros

参数

参数

注释

ca_path

路径

在 community.routeros 1.2.0 中添加

PEM 格式的文件，其中包含用于证书验证的 CA 证书。

另请参阅 validate_cert_hostname。 仅当 tls=true 且 validate_certs=true 时使用。

data

list / elements=dictionary / required

要确保此路径存在的数据。

未提供的字段将不会被修改。

如果 .id 出现在条目中，它将被忽略。

encoding

string

在 community.routeros 2.1.0 中添加

在与 RouterOS 设备通信时使用指定的编码。

默认值为 ASCII。 请注意，UTF-8 需要 librouteros 3.2.1 或更新版本。

默认值： "ASCII"

ensure_order

boolean

是否确保配置的顺序与 data 中存在的顺序相同。

需要 handle_absent_entries=remove。

选择

  • false ←（默认）

  • true

force_no_cert

boolean

在 community.routeros 2.4.0 中添加

设置为 true 以在 tls=true 时无需证书连接。

另请参阅 validate_certs。

注意：这强制使用匿名 Diffie-Hellman (ADH) 密码。 该协议容易受到中间人攻击，因为交换中使用的密钥未经过身份验证。 不要只是在没有证书的情况下连接以“使事情正常工作”，请查看 validate_certs 和 ca_path。

选择

  • false ←（默认）

  • true

handle_absent_entries

string

如何处理当前配置中存在，但 data 中不存在的条目。

ignore 忽略它们。

remove 删除它们。

选择

  • "ignore" ←（默认）

  • "remove"

handle_entries_content

string

对于 data 中的单个条目，这描述了如何处理该条目中未提及但在实际配置中出现的字段。

如果 ignore，则不会修改它们。

如果 remove，它们将被删除。如果至少有一个无法删除，模块将会失败。

如果 remove_as_much_as_possible，所有可以删除的都将被删除。无法删除的将被保留。

请注意，remove 和 remove_as_much_as_possible 不适用于只写字段。

选择

  • "ignore" ←（默认）

  • "remove"

  • "remove_as_much_as_possible"

handle_read_only

string

在 community.routeros 2.10.0 中添加。

如何处理为只读字段传入的值。

如果 ignore，它们不会传递给 API。

如果 validate，这些值不会在创建时传递，而在更新时，它们会与对象返回的值进行比较。如果它们不同，模块将会失败。

如果 error，如果提供了只读字段，模块将会失败。

选择

  • "ignore"

  • "validate"

  • "error" ← (默认)

handle_write_only

string

在 community.routeros 2.10.0 中添加。

如何处理为只写字段传入的值。

如果 create_only，它们在创建时传递，并在更新时被忽略。

如果 always_update，它们总是传递给 API。这意味着，如果存在这样的值，模块将总是导致 changed，因为没有办法验证该值是否真的发生了变化。

如果 error，如果提供了只写字段，模块将会失败。

选择

  • "create_only" ← (默认)

  • "always_update"

  • "error"

hostname

字符串 / 必需

RouterOS 主机名 API。

password

字符串 / 必需

RouterOS 用户密码。

路径

字符串 / 必需

要查询的路径。

一个示例值是 ip address。这相当于在 RouterOS CLI 中运行 /ip address 中的修改命令。

选择

  • "caps-man aaa"

  • "caps-man access-list"

  • "caps-man channel"

  • "caps-man configuration"

  • "caps-man datapath"

  • "caps-man manager"

  • "caps-man manager interface"

  • "caps-man provisioning"

  • "caps-man security"

  • "certificate settings"

  • "interface bonding"

  • "interface bridge"

  • "interface bridge mlag"

  • "interface bridge port"

  • "interface bridge port-controller"

  • "interface bridge port-extender"

  • "interface bridge settings"

  • "interface bridge vlan"

  • "interface detect-internet"

  • "interface eoip"

  • "interface ethernet"

  • "interface ethernet poe"

  • "interface ethernet switch"

  • "interface ethernet switch port"

  • "interface gre"

  • "interface gre6"

  • "interface l2tp-client"

  • "interface l2tp-server server"

  • "interface list"

  • "interface list member"

  • "interface ovpn-client"

  • "interface ovpn-server server"

  • "interface ppp-client"

  • "interface pppoe-client"

  • "interface pppoe-server server"

  • "interface pptp-server server"

  • "interface sstp-server server"

  • "interface vlan"

  • "interface vrrp"

  • "interface wifi"

  • "interface wifi aaa"

  • "interface wifi access-list"

  • "interface wifi cap"

  • "interface wifi capsman"

  • "interface wifi channel"

  • "interface wifi configuration"

  • "interface wifi datapath"

  • "interface wifi interworking"

  • "interface wifi provisioning"

  • "interface wifi security"

  • "interface wifi steering"

  • "interface wifiwave2"

  • "interface wifiwave2 aaa"

  • "interface wifiwave2 access-list"

  • "interface wifiwave2 cap"

  • "interface wifiwave2 capsman"

  • "interface wifiwave2 channel"

  • "interface wifiwave2 configuration"

  • "interface wifiwave2 datapath"

  • "interface wifiwave2 interworking"

  • "interface wifiwave2 provisioning"

  • "interface wifiwave2 security"

  • "interface wifiwave2 steering"

  • "interface wireguard"

  • "interface wireguard peers"

  • "interface wireless"

  • "interface wireless align"

  • "interface wireless cap"

  • "interface wireless security-profiles"

  • "interface wireless sniffer"

  • "interface wireless snooper"

  • "iot modbus"

  • "ip accounting"

  • "ip accounting web-access"

  • "ip address"

  • "ip arp"

  • "ip cloud"

  • "ip cloud advanced"

  • "ip dhcp-client"

  • "ip dhcp-client option"

  • "ip dhcp-relay"

  • "ip dhcp-server"

  • "ip dhcp-server config"

  • "ip dhcp-server lease"

  • "ip dhcp-server matcher"

  • "ip dhcp-server network"

  • "ip dhcp-server option"

  • "ip dhcp-server option sets"

  • "ip dns"

  • "ip dns adlist"

  • "ip dns static"

  • "ip firewall address-list"

  • "ip firewall connection tracking"

  • "ip firewall filter"

  • "ip firewall layer7-protocol"

  • "ip firewall mangle"

  • "ip firewall nat"

  • "ip firewall raw"

  • "ip firewall service-port"

  • "ip hotspot service-port"

  • "ip ipsec identity"

  • "ip ipsec peer"

  • "ip ipsec policy"

  • "ip ipsec profile"

  • "ip ipsec proposal"

  • "ip ipsec settings"

  • "ip neighbor discovery-settings"

  • "ip pool"

  • "ip proxy"

  • "ip route"

  • "ip route rule"

  • "ip route vrf"

  • "ip service"

  • "ip settings"

  • "ip smb"

  • "ip socks"

  • "ip ssh"

  • "ip tftp settings"

  • "ip traffic-flow"

  • "ip traffic-flow ipfix"

  • "ip traffic-flow target"

  • "ip upnp"

  • "ip upnp interfaces"

  • "ip vrf"

  • "ipv6 address"

  • "ipv6 dhcp-client"

  • "ipv6 dhcp-server"

  • "ipv6 dhcp-server option"

  • "ipv6 firewall address-list"

  • "ipv6 firewall filter"

  • "ipv6 firewall mangle"

  • "ipv6 firewall nat"

  • "ipv6 防火墙 原始"

  • "ipv6 邻居发现"

  • "ipv6 邻居发现 前缀"

  • "ipv6 邻居发现 前缀 默认"

  • "ipv6 路由"

  • "ipv6 设置"

  • "mpls"

  • "mpls 接口"

  • "mpls ldp"

  • "mpls ldp 接受过滤器"

  • "mpls ldp 通告过滤器"

  • "mpls ldp 接口"

  • "端口 固件"

  • "端口 远程访问"

  • "ppp aaa"

  • "ppp 配置文件"

  • "ppp 密钥"

  • "队列 接口"

  • "队列 简单"

  • "队列 树"

  • "队列 类型"

  • "radius"

  • "radius 传入"

  • "路由 bgp 聚合"

  • "路由 bgp 连接"

  • "路由 bgp 实例"

  • "路由 bgp 网络"

  • "路由 bgp 对等体"

  • "路由 bgp 模板"

  • "路由 过滤器"

  • "路由 过滤器 数字列表"

  • "路由 过滤器 规则"

  • "路由 过滤器 选择规则"

  • "路由 id"

  • "路由 igmp-代理"

  • "路由 igmp-代理 接口"

  • "路由 mme"

  • "路由 ospf 区域"

  • "路由 ospf 区域 范围"

  • "路由 ospf 实例"

  • "路由 ospf 接口模板"

  • "路由 ospf 静态邻居"

  • "路由 pimsm 实例"

  • "路由 pimsm 接口模板"

  • "路由 rip"

  • "路由 ripng"

  • "路由 规则"

  • "路由 表"

  • "snmp"

  • "snmp 团体"

  • "系统 时钟"

  • "系统 时钟 手动"

  • "系统 健康 设置"

  • "系统 标识"

  • "系统 led 设置"

  • "系统 日志"

  • "系统 日志 动作"

  • "系统 备注"

  • "系统 ntp 客户端"

  • "系统 ntp 客户端 服务器"

  • "系统 ntp 服务器"

  • "系统 包 更新"

  • "系统 资源 irq rps"

  • "系统 路由器板 设置"

  • "系统 调度器"

  • "系统 脚本"

  • "系统 升级 镜像"

  • "系统 ups"

  • "系统 看门狗"

  • "工具 带宽服务器"

  • "工具 电子邮件"

  • "工具 图形"

  • "工具 图形 接口"

  • "工具 图形 资源"

  • "工具 mac服务器"

  • "工具 mac服务器 mac-winbox"

  • "工具 mac服务器 ping"

  • "工具 网络监视"

  • "工具 romon"

  • "工具 短信"

  • "工具 嗅探器"

  • "工具 流量生成器"

  • "用户"

  • "用户 aaa"

  • "用户 组"

  • "用户 设置"

端口

整数

RouterOS API端口。如果 tls 设置，端口将应用于 TLS/SSL 连接。

HTTP API 的默认值为 8728，HTTPS API 的默认值为 8729。

限制

列表 / 元素=字典

在 community.routeros 2.18.0 中添加

将操作限制为与以下条件匹配的条目。

这与 handle_absent_entries=remove 一起使用，以操作值的子集。

例如，对于 path=ip firewall filter，您可以设置 restrict[].field=chain 和 restrict[].values=input 以将操作限制为输入链，并忽略转发和输出链。

字段

字符串 / 必需

要限制其值的字段。

反转

boolean

反转条件。这会影响 restrict[].match_disabled、restrict[].values 和 restrict[].regex。

选择

  • false ←（默认）

  • true

match_disabled

boolean

是否应匹配禁用或未提供的值。

选择

  • false ←（默认）

  • true

正则表达式

string

匹配要限制的字段值的正则表达式。

请注意，所有值在匹配之前都将转换为字符串。

无法使用正则表达式匹配禁用的值。如果您还想匹配禁用的值，请设置 restrict[].match_disabled=true。

值

列表 / 元素=任何

要限制的字段值。

请注意，值的类型很重要。如果提供字符串 "0"，并且 librouteros 将 API 返回的值转换为整数 0，则这将不匹配。如果您不确定，最好同时包含这两种变体：字符串和整数。

超时

整数

在 community.routeros 2.3.0 中添加

请求的超时时间。

默认值： 10

tls

别名：ssl

boolean

如果设置了，则 TLS 将用于 RouterOS API 连接。

选择

  • false ←（默认）

  • true

用户名

字符串 / 必需

RouterOS 登录用户。

validate_cert_hostname

boolean

在 community.routeros 1.2.0 中添加

设置为 true 以验证证书中的主机名。

另请参阅 validate_certs。仅当 tls=true 和 validate_certs=true 时使用。

选择

  • false ←（默认）

  • true

validate_certs

boolean

在 community.routeros 1.2.0 中添加

设置为 false 以跳过 TLS 证书的验证。

另请参阅 validate_cert_hostname。仅当 tls=true 时使用。

注意：与其简单地停用证书验证来“使事情正常工作”，请考虑创建您自己的 CA 证书并使用它来签署用于您的路由器的证书。您可以使用 ca_path 选项告诉模块您的 CA 证书。

选择

  • false

  • true ← (默认)

属性

属性

支持

描述

action_group

操作组： community.routeros.api

在 module_defaults 中使用 group/community.routeros.api 来设置此模块的默认值。

check_mode

支持: 完全

可以在 check_mode 中运行，并返回更改状态预测，而不会修改目标。

diff_mode

支持: 完全

当处于 diff 模式时，将返回已更改的详细信息（或可能需要在 check_mode 中进行更改的详细信息）。

platform

平台: RouterOS

可以操作的目标操作系统/系列。

说明

注意

  • 如果路径中存在只写字段，则该模块在严格意义上是非幂等的，因为它无法验证这些字段的当前值。该模块应假定的行为可以通过 handle_write_only 选项进行控制。

另请参阅

另请参阅

community.routeros.api

用于 RouterOS API 的 Ansible 模块。

community.routeros.api_facts

使用 API 从运行 MikroTik RouterOS 的远程设备收集事实。

community.routeros.api_find_and_modify

使用 API 查找和修改信息。

community.routeros.api_info

从 API 检索信息。

如何使用 RouterOS API 连接到 RouterOS 设备

如何使用 RouterOS API 连接到 RouterOS 设备

示例

---
- name: Setup DHCP server networks
  # Ensures that we have exactly two DHCP server networks (in the specified order)
  community.routeros.api_modify:
    path: ip dhcp-server network
    handle_absent_entries: remove
    handle_entries_content: remove_as_much_as_possible
    ensure_order: true
    data:
      - address: 192.168.88.0/24
        comment: admin network
        dns-server: 192.168.88.1
        gateway: 192.168.88.1
      - address: 192.168.1.0/24
        comment: customer network 1
        dns-server: 192.168.1.1
        gateway: 192.168.1.1
        netmask: 24

- name: Adjust NAT
  community.routeros.api_modify:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: ip firewall nat
    data:
      - action: masquerade
        chain: srcnat
        comment: NAT to WAN
        out-interface-list: WAN
        # Three ways to unset values:
        #   - nothing after `:`
        #   - "empty" value (null/~/None)
        #   - prepend '!'
        out-interface:
        to-addresses: ~
        '!to-ports':

- name: Block all incoming connections
  community.routeros.api_modify:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: ip firewall filter
    handle_absent_entries: remove
    handle_entries_content: remove_as_much_as_possible
    restrict:
      # Do not touch any chain except the input chain
      - field: chain
        values:
          - input
    data:
      - action: drop
        chain: input

返回值

常用返回值记录在此处，以下是此模块特有的字段

键

描述

new_data

列表 / 元素=字典

更改后当前路径的所有元素的列表。

返回: 始终

示例: [{".id": "*1", "actual-interface": "bridge", "address": "192.168.1.1/24", "comment": "awesome", "disabled": false, "dynamic": false, "interface": "bridge", "invalid": false, "network": "192.168.1.0"}]

old_data

列表 / 元素=字典

更改前当前路径的所有元素的列表。

返回: 始终

示例: [{".id": "*1", "actual-interface": "bridge", "address": "192.168.88.1/24", "comment": "defconf", "disabled": false, "dynamic": false, "interface": "bridge", "invalid": false, "network": "192.168.88.0"}]

作者

  • Felix Fontein (@felixfontein)