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.1.0).
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.
To use it in a playbook, specify: community.routeros.api_find_and_modify.
New in version 2.1.0: of community.routeros
Requirements
The below requirements are needed on the host that executes this module.
librouteros
Python >= 3.6 (for librouteros)
Parameters
Parameter |
Comments |
|---|---|
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:
|
|
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. |
|
Use the specified encoding when communicating with the RouterOS device. Default is Default: “ASCII” |
|
Fields to search for. The module will only consider entries in the given path that match all fields provided here. Use YAML Note that if the dictionary specified here is empty, every entry in the path will be matched. |
|
RouterOS hostname API. |
|
RouterOS user password. |
|
Path to query. An example value is |
|
RouterOS api port. If tls is set, port will apply to TLS/SSL connection. Defaults are |
|
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. |
|
Make sure that there are no less matches than this number. If there are less matches, fail instead of modifying anything. Default: 0 |
|
If is set TLS will be used for RouterOS API connection. Choices:
|
|
RouterOS login user. |
|
Set to See also validate_certs. Only used when tls=true and validate_certs=true. Choices:
|
|
Set to 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:
|
|
On all entries matching the conditions in find, set the keys of this option to the values specified here. Use YAML |
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.
Supports check_mode.
See Also
See also
- community.routeros.api
The official documentation on the community.routeros.api 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 |
|---|---|
The number of entries that matched the criteria in find. Returned: success Sample: 1 |
|
The number of entries that were modified. Returned: success Sample: 1 |
|
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”}] |
|
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