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

列表 / 元素=字典 / 必需

确保此路径存在的数据。

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

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

encoding

字符串

在 community.routeros 2.1.0 中添加

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

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

默认值： "ASCII"

ensure_order

布尔值

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

需要 handle_absent_entries=remove。

选项

  • false ← (默认)

  • true

force_no_cert

布尔值

在 community.routeros 2.4.0 中添加

当 tls=true 时，设置为 true 以在没有证书的情况下连接。

另请参阅 validate_certs。

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

选项

  • false ← (默认)

  • true

handle_absent_entries

字符串

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

ignore 忽略它们。

remove 删除它们。

选项

  • "ignore" ← (默认)

  • "remove"

handle_entries_content

字符串

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

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

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

如果为 remove_as_much_as_possible，则会删除所有可以删除的内容。无法删除的内容将保留。

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

选项

  • "ignore" ← (默认)

  • "remove"

  • "remove_as_much_as_possible"

handle_read_only

字符串

在 community.routeros 2.10.0 中添加

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

如果为 ignore，则不会将其传递给 API。

如果为 validate，则不会传递这些值用于创建，并且对于更新，会将这些值与为对象返回的值进行比较。如果它们不同，则模块将失败。

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

选项

  • "ignore"

  • "validate"

  • "error" ← (默认)

handle_write_only

字符串

在 community.routeros 2.10.0 中添加

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

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

如果为 always_update，则始终将它们传递给 API。这意味着，如果存在这样的值，则模块将始终导致 changed，因为无法验证该值是否实际已更改。

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

选项

  • "create_only" ← (默认)

  • "always_update"

  • "error"

hostname

string / required

RouterOS 主机名 API。

password

string / required

RouterOS 用户密码。

路径

string / required

要查询的路径。

一个示例值是 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 DHCP 服务器选项集”

  • "ip dns"

  • “IP DNS”

  • "ip dns adlist"

  • “IP DNS 广告列表”

  • "ip dns static"

  • “IP DNS 静态”

  • "ip firewall address-list"

  • “IP 防火墙地址列表”

  • "ip firewall connection tracking"

  • “IP 防火墙连接跟踪”

  • "ip firewall filter"

  • “IP 防火墙过滤器”

  • "ip firewall layer7-protocol"

  • “IP 防火墙七层协议”

  • "ip firewall mangle"

  • “IP 防火墙 Mangle”

  • "ip firewall nat"

  • “IP 防火墙 NAT”

  • "ip firewall raw"

  • “IP 防火墙 Raw”

  • "ip firewall service-port"

  • “IP 防火墙服务端口”

  • "ip hotspot service-port"

  • “IP 热点服务端口”

  • "ip ipsec identity"

  • “IP IPsec 身份”

  • "ip ipsec peer"

  • “IP IPsec 对等体”

  • "ip ipsec policy"

  • “IP IPsec 策略”

  • "ip ipsec profile"

  • “IP IPsec 配置文件”

  • "ip ipsec proposal"

  • “IP IPsec 提议”

  • "ip ipsec settings"

  • “IP IPsec 设置”

  • "ip neighbor discovery-settings"

  • “IP 邻居发现设置”

  • "ip pool"

  • “IP 池”

  • "ip proxy"

  • “IP 代理”

  • "ip route"

  • “IP 路由”

  • "ip route rule"

  • “IP 路由规则”

  • "ip route vrf"

  • “IP 路由 VRF”

  • "ip service"

  • “IP 服务”

  • "ip settings"

  • “IP 设置”

  • "ip smb"

  • “IP SMB”

  • "ip socks"

  • “IP SOCKS”

  • "ip ssh"

  • “IP SSH”

  • "ip tftp settings"

  • “IP TFTP 设置”

  • "ip traffic-flow"

  • “IP 流量流”

  • "ip traffic-flow ipfix"

  • “IP 流量流 IPFIX”

  • "ip traffic-flow target"

  • “IP 流量流目标”

  • "ip upnp"

  • “IP UPnP”

  • "ip upnp interfaces"

  • “IP UPnP 接口”

  • "ip vrf"

  • “IP VRF”

  • "ipv6 address"

  • “IPv6 地址”

  • "ipv6 dhcp-client"

  • “IPv6 DHCP 客户端”

  • "ipv6 dhcp-server"

  • “IPv6 DHCP 服务器”

  • "ipv6 dhcp-server option"

  • “IPv6 DHCP 服务器选项”

  • "ipv6 firewall address-list"

  • “IPv6 防火墙地址列表”

  • "ipv6 firewall filter"

  • “IPv6 防火墙过滤器”

  • "ipv6 firewall mangle"

  • “IPv6 防火墙 Mangle”

  • "ipv6 firewall nat"

  • “IPv6 防火墙 NAT”

  • "ipv6 firewall raw"

  • “IPv6 防火墙 Raw”

  • "ipv6 nd"

  • “IPv6 ND”

  • "ipv6 nd prefix"

  • “IPv6 ND 前缀”

  • "ipv6 nd prefix default"

  • “IPv6 ND 前缀默认”

  • "ipv6 route"

  • “IPv6 路由”

  • "ipv6 settings"

  • “IPv6 设置”

  • "mpls"

  • “MPLS”

  • "mpls interface"

  • “MPLS 接口”

  • "mpls ldp"

  • “MPLS LDP”

  • "mpls ldp accept-filter"

  • “MPLS LDP 接受过滤器”

  • "mpls ldp advertise-filter"

  • “MPLS LDP 广播过滤器”

  • "mpls ldp interface"

  • “MPLS LDP 接口”

  • "port firmware"

  • “端口固件”

  • "port remote-access"

  • “端口远程访问”

  • "ppp aaa"

  • “PPP AAA”

  • "ppp profile"

  • “PPP 配置文件”

  • "ppp secret"

  • “PPP 密钥”

  • "queue interface"

  • “队列接口”

  • "queue simple"

  • “简单队列”

  • "queue tree"

  • “队列树”

  • "queue type"

“队列类型”

"radius"

“RADIUS”

"radius incoming"

“RADIUS 入站”

"routing bgp aggregate"

“路由 BGP 聚合”

"routing bgp connection"

“路由 BGP 连接”

"routing bgp instance"

“路由 BGP 实例”

string / required

"routing bgp network"

“路由 BGP 网络”

布尔值

"routing bgp peer"

选项

  • false ← (默认)

  • true

“路由 BGP 对等体”

布尔值

"routing bgp template"

选项

  • false ← (默认)

  • true

“路由 BGP 模板”

字符串

"routing filter"

“路由过滤器”

"routing filter num-list"

“路由过滤器数字列表”

"routing filter rule"

“路由过滤器规则”

"routing filter select-rule"

“路由过滤器选择规则”

"radius"

"routing id"

“路由 ID”

默认值: 10

tls

别名: ssl

布尔值

如果设置此项，将使用 TLS 进行 RouterOS API 连接。

选项

  • false ← (默认)

  • true

username

string / required

RouterOS 登录用户名。

validate_cert_hostname

布尔值

在 community.routeros 1.2.0 中添加

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

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

选项

  • false ← (默认)

  • true

validate_certs

布尔值

在 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

"routing bgp aggregate"

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

返回: 始终

示例: [{".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

"routing bgp aggregate"

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

返回: 始终

示例: [{".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)