# 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.6.0).

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

- Requirements

- Parameters

- Attributes

- Notes

- See Also

- Examples

- Return Values

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

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`

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

  Ansible module for RouterOS API.

community.routeros.api_facts

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

community.routeros.api_modify

  Modify data at paths with 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: 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)

### Collection links

Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication