community.routeros.api_modify module – Modify data at paths with API
Note
This module is part of the community.routeros collection (version 2.19.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
.
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
Allows to modify information for a path using the API.
Use the community.routeros.api_find_and_modify module to modify one or multiple entries in a controlled way depending on some search conditions.
To make a backup of a path that can be restored with this module, use the community.routeros.api_info module.
The module ignores dynamic and builtin entries.
Note that this module is still heavily in development, and only supports some paths. If you want to support new paths, or think you found problems with existing paths, please first create an issue in the community.routeros Issue Tracker.
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 |
---|---|
PEM formatted file that contains a CA certificate to be used for certificate validation. See also |
|
Data to ensure that is present for this path. Fields not provided will not be modified. If |
|
Use the specified encoding when communicating with the RouterOS device. Default is Default: |
|
Whether to ensure the same order of the config as present in Requires Choices:
|
|
Set to See also 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 Choices:
|
|
How to handle entries that are present in the current config, but not in
Choices:
|
|
For a single entry in If If If Note that Choices:
|
|
How to handle values passed in for read-only fields. If If If Choices:
|
|
How to handle values passed in for write-only fields. If If If Choices:
|
|
RouterOS hostname API. |
|
RouterOS user password. |
|
Path to query. An example value is Choices:
|
|
RouterOS api port. If Defaults are |
|
Restrict operation to entries matching the following criteria. This can be useful together with For example, for |
|
The field whose values to restrict. |
|
Invert the condition. This affects Choices:
|
|
Whether disabled or not provided values should match. Choices:
|
|
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 |
|
The values of the field to limit to. Note that the types of the values are important. If you provide a string |
|
Timeout for the request. Default: |
|
If is set TLS will be used for RouterOS API connection. Choices:
|
|
RouterOS login user. |
|
Set to See also Choices:
|
|
Set to See also 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 Choices:
|
Attributes
Attribute |
Support |
Description |
---|---|---|
Action group: community.routeros.api |
Use |
|
Support: full |
Can run in |
|
Support: full |
Will return details on what has changed (or possibly needs changing in |
|
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 |
---|---|
A list of all elements for the current path after a change was made. Returned: always Sample: |
|
A list of all elements for the current path before a change was made. Returned: always Sample: |