community.routeros.api_modify module – Modify data at paths with API

Note

This module is part of the community.routeros collection (version 3.12.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.routeros. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.routeros.api_modify.

New in community.routeros 2.2.0

Synopsis

Requirements

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

  • Needs ordereddict for Python 2.6

  • Python >= 3.6 (for librouteros)

  • librouteros

Parameters

Parameter

Comments

ca_path

path

added in community.routeros 1.2.0

PEM formatted file that contains a CA certificate to be used for certificate validation.

See also validate_cert_hostname. Only used when tls=true and validate_certs=true.

data

list / elements=dictionary / required

Data to ensure that is present for this path.

Fields not provided will not be modified.

If .id appears in an entry, it will be ignored.

encoding

string

added in community.routeros 2.1.0

Use the specified encoding when communicating with the RouterOS device.

Default is ASCII. Note that UTF-8 requires librouteros 3.2.1 or newer.

Default: "ASCII"

ensure_order

boolean

Whether to ensure the same order of the config as present in data.

Requires handle_absent_entries=remove.

Choices:

  • false ← (default)

  • true

force_no_cert

boolean

added in community.routeros 2.4.0

Set to true to connect without a certificate when tls=true.

See also validate_certs.

Note: this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible to Man-in-the-Middle attacks, because the keys used in the exchange are not authenticated. Instead of simply connecting without a certificate to “make things work” have a look at validate_certs and ca_path.

Choices:

  • false ← (default)

  • true

handle_absent_entries

string

How to handle entries that are present in the current config, but not in data.

ignore ignores them.

remove removes them.

Choices:

  • "ignore" ← (default)

  • "remove"

handle_entries_content

string

For a single entry in data, this describes how to handle fields that are not mentioned in that entry, but appear in the actual config.

If ignore, they are not modified.

If remove, they are removed. If at least one cannot be removed, the module will fail.

If remove_as_much_as_possible, all that can be removed will be removed. The ones that cannot be removed will be kept.

Note that remove and remove_as_much_as_possible do not apply to write-only fields.

Choices:

  • "ignore" ← (default)

  • "remove"

  • "remove_as_much_as_possible"

handle_read_only

string

added in community.routeros 2.10.0

How to handle values passed in for read-only fields.

If ignore, they are not passed to the API.

If validate, the values are not passed for creation, and for updating they are compared to the value returned for the object. If they differ, the module fails.

If error, the module will fail if read-only fields are provided.

Choices:

  • "ignore"

  • "validate"

  • "error" ← (default)

handle_write_only

string

added in community.routeros 2.10.0

How to handle values passed in for write-only fields.

If create_only, they are passed on creation, and ignored for updating.

If always_update, they are always passed to the API. This means that if such a value is present, the module will always result in changed since there is no way to validate whether the value actually changed.

If error, the module will fail if write-only fields are provided.

Choices:

  • "create_only" ← (default)

  • "always_update"

  • "error"

hostname

string / required

RouterOS hostname API.

password

string / required

RouterOS user password.

path

string / required

Path to query.

An example value is ip address. This is equivalent to running modification commands in /ip address in the RouterOS CLI.

Choices:

  • "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 6to4"

  • "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 ethernet switch port-isolation"

  • "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 access-list"

  • "interface wireless align"

  • "interface wireless cap"

  • "interface wireless connect-list"

  • "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 forwarders"

  • "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 mode-config"

  • "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 firewall raw"

  • "ipv6 nd"

  • "ipv6 nd prefix"

  • "ipv6 nd prefix default"

  • "ipv6 route"

  • "ipv6 settings"

  • "mpls"

  • "mpls interface"

  • "mpls ldp"

  • "mpls ldp accept-filter"

  • "mpls ldp advertise-filter"

  • "mpls ldp interface"

  • "port firmware"

  • "port remote-access"

  • "ppp aaa"

  • "ppp profile"

  • "ppp secret"

  • "queue interface"

  • "queue simple"

  • "queue tree"

  • "queue type"

  • "radius"

  • "radius incoming"

  • "routing bfd configuration"

  • "routing bgp aggregate"

  • "routing bgp connection"

  • "routing bgp instance"

  • "routing bgp network"

  • "routing bgp peer"

  • "routing bgp template"

  • "routing filter"

  • "routing filter community-list"

  • "routing filter num-list"

  • "routing filter rule"

  • "routing filter select-rule"

  • "routing id"

  • "routing igmp-proxy"

  • "routing igmp-proxy interface"

  • "routing mme"

  • "routing ospf area"

  • "routing ospf area range"

  • "routing ospf instance"

  • "routing ospf interface-template"

  • "routing ospf static-neighbor"

  • "routing pimsm instance"

  • "routing pimsm interface-template"

  • "routing rip"

  • "routing ripng"

  • "routing rule"

  • "routing table"

  • "snmp"

  • "snmp community"

  • "system clock"

  • "system clock manual"

  • "system health settings"

  • "system identity"

  • "system leds settings"

  • "system logging"

  • "system logging action"

  • "system note"

  • "system ntp client"

  • "system ntp client servers"

  • "system ntp server"

  • "system package update"

  • "system resource irq rps"

  • "system routerboard settings"

  • "system scheduler"

  • "system script"

  • "system upgrade mirror"

  • "system ups"

  • "system watchdog"

  • "tool bandwidth-server"

  • "tool e-mail"

  • "tool graphing"

  • "tool graphing interface"

  • "tool graphing resource"

  • "tool mac-server"

  • "tool mac-server mac-winbox"

  • "tool mac-server ping"

  • "tool netwatch"

  • "tool romon"

  • "tool sms"

  • "tool sniffer"

  • "tool traffic-generator"

  • "user"

  • "user aaa"

  • "user group"

  • "user settings"

port

integer

RouterOS API port. If tls is set, port will apply to TLS/SSL connection.

Defaults are 8728 for the HTTP API, and 8729 for the HTTPS API.

restrict

list / elements=dictionary

added in community.routeros 2.18.0

Restrict operation to entries matching the following criteria.

This can be useful together with handle_absent_entries=remove to operate on a subset of the values.

For example, for path=ip firewall filter, you can set restrict[].field=chain and restrict[].values=input to restrict operation to the input chain, and ignore the forward and output chains.

field

string / required

The field whose values to restrict.

invert

boolean

Invert the condition. This affects restrict[].match_disabled, restrict[].values, and restrict[].regex.

Choices:

  • false ← (default)

  • true

match_disabled

boolean

Whether disabled or not provided values should match.

Choices:

  • false ← (default)

  • true

regex

string

A regular expression matching values of the field to limit to.

Note that all values will be converted to strings before matching.

It is not possible to match disabled values with regular expressions. Set restrict[].match_disabled=true if you also want to match disabled values.

values

list / elements=any

The values of the field to limit to.

Note that the types of the values are important. If you provide a string "0", and librouteros converts the value returned by the API to the integer 0, then this will not match. If you are not sure, better include both variants: both the string and the integer.

timeout

integer

added in community.routeros 2.3.0

Timeout for the request.

Default: 10

tls

aliases: ssl

boolean

If is set TLS will be used for RouterOS API connection.

Choices:

  • false ← (default)

  • true

username

string / required

RouterOS login user.

validate_cert_hostname

boolean

added in community.routeros 1.2.0

Set to true to validate hostnames in certificates.

See also validate_certs. Only used when tls=true and validate_certs=true.

Choices:

  • false ← (default)

  • true

validate_certs

boolean

added in community.routeros 1.2.0

Set to false to skip validation of TLS certificates.

See also validate_cert_hostname. Only used when tls=true.

Note: instead of simply deactivating certificate validations to “make things work”, please consider creating your own CA certificate and using it to sign certificates used for your router. You can tell the module about your CA certificate with the ca_path option.

Choices:

  • false

  • true ← (default)

Attributes

Attribute

Support

Description

action_group

Action group: community.routeros.api

Use group/community.routeros.api in module_defaults to set defaults for this module.

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: full

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

idempotent

Support: full

When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.

This assumes that the system controlled/queried by the module has not changed in a relevant way.

platform

Platform: RouterOS

Target OS/families that can be operated against.

Notes

Note

  • If write-only fields are present in the path, the module is not idempotent in a strict sense, since it is not able to verify the current value of these fields. The behavior the module should assume can be controlled with the handle_write_only option.

See Also

See also

community.routeros.api

Ansible module for RouterOS API.

community.routeros.api_facts

Collect facts from remote devices running MikroTik RouterOS using the API.

community.routeros.api_find_and_modify

Find and modify information using the API.

community.routeros.api_info

Retrieve information from API.

How to connect to RouterOS devices with the RouterOS API

How to connect to RouterOS devices with the RouterOS API.

Examples

---
- 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

Return Values

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

Key

Description

new_data

list / elements=dictionary

A list of all elements for the current path after a change was made.

Returned: always

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

list / elements=dictionary

A list of all elements for the current path before a change was made.

Returned: always

Sample: [{".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"}]

Authors

  • Felix Fontein (@felixfontein)