community.routeros.api_find_and_modify module – Find and modify information using the API

Note

This module is part of the community.routeros collection (version 2.3.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_find_and_modify.

New in community.routeros 2.1.0

Synopsis

  • Allows to find entries for a path by conditions and modify the values of these entries.

  • Use the community.routeros.api_find_and_modify module to set all entries of a path to specific values, or change multiple entries in different ways in one step.

Requirements

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

  • librouteros

  • Python >= 3.6 (for librouteros)

Parameters

Parameter

Comments

allow_no_matches

boolean

Whether to allow that no match is found.

If not specified, this value is induced from whether require_matches_min is 0 or larger.

Choices:

  • false

  • true

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.

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"

find

dictionary / required

Fields to search for.

The module will only consider entries in the given path that match all fields provided here.

Use YAML ~, or prepend keys with !, to specify an unset value.

Note that if the dictionary specified here is empty, every entry in the path will be matched.

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 /ip address in the RouterOS CLI.

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.

require_matches_max

integer

Make sure that there are no more matches than this number.

If there are more matches, fail instead of modifying anything.

If not specified, there is no upper limit.

require_matches_min

integer

Make sure that there are no less matches than this number.

If there are less matches, fail instead of modifying anything.

Default: 0

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)

values

dictionary / required

On all entries matching the conditions in find, set the keys of this option to the values specified here.

Use YAML ~, or prepend keys with !, to specify to unset a value.

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.

platform

Platform: RouterOS

Target OS/families that can be operated against.

Notes

Note

  • If you want to change values based on their old values (like change all comments ‘foo’ to ‘bar’) and make sure that there are at least N such values, you can use require_matches_min=N together with allow_no_matches=true. This will make the module fail if there are less than N such entries, but not if there is no match. The latter case is needed for idempotency of the task: once the values have been changed, there should be no further match.

See Also

See also

community.routeros.api

The official documentation on the community.routeros.api module.

community.routeros.api_facts

The official documentation on the community.routeros.api_facts module.

community.routeros.api_modify

The official documentation on the community.routeros.api_modify module.

community.routeros.api_info

The official documentation on the community.routeros.api_info module.

How to connect to RouterOS devices with the RouterOS API

How to connect to RouterOS devices with the RouterOS API

Examples

---
- name: Rename bridge from 'bridge' to 'my-bridge'
  community.routeros.api_find_and_modify:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: interface bridge
    find:
      name: bridge
    values:
      name: my-bridge

- name: Change IP address to 192.168.1.1 for interface bridge - assuming there is only one
  community.routeros.api_find_and_modify:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: ip address
    find:
      interface: bridge
    values:
      address: "192.168.1.1/24"
    # If there are zero entries, or more than one: fail! We expected that
    # exactly one is configured.
    require_matches_min: 1
    require_matches_max: 1

Return Values

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

Key

Description

match_count

integer

The number of entries that matched the criteria in find.

Returned: success

Sample: 1

modify__count

integer

The number of entries that were modified.

Returned: success

Sample: 1

new_data

list / elements=dictionary

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

Returned: success

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

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)