community.routeros.api module – Ansible module for RouterOS API
Note
This module is part of the community.routeros collection (version 2.20.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
.
Synopsis
Ansible module for RouterOS API with the Python
librouteros
library.This module can add, remove, update, query and execute arbitrary command in RouterOS via API.
Requirements
The below requirements are needed on the host that executes this module.
librouteros
Python >= 3.6 (for librouteros)
Parameters
Parameter |
Comments |
---|---|
Will add selected arguments in selected path to RouterOS config. Example Equivalent in RouterOS CLI |
|
PEM formatted file that contains a CA certificate to be used for certificate validation. See also |
|
Execute any/arbitrary command in selected path, after the command we can add Example path Example path |
|
Use the specified encoding when communicating with the RouterOS device. Default is Default: |
|
Extended query given path for selected query attributes from RouterOS API. Extended query allow conjunctive input. If there is no matching entry, an empty list will be returned. |
|
The list of attributes to return. Every attribute used in a |
|
Allows to restrict the objects returned. The conditions here must all match. An |
|
The attribute to match. Must be part of Either |
|
The operator to use for matching. For equality use Use Either Choices:
|
|
A list of conditions so that at least one of them has to match. Either |
|
The attribute to match. Must be part of |
|
The operator to use for matching. For equality use Use Choices:
|
|
The value to compare to. Must be a list for |
|
The value to compare to. Must be a list for Either |
|
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:
|
|
RouterOS hostname API. |
|
RouterOS user password. |
|
Main path for all other arguments. If other arguments are not set, api will return all items in selected path. Example |
|
RouterOS api port. If Defaults are |
|
Query given path for selected query attributes from RouterOS aip. WHERE is key word which extend query. WHERE format is key operator value - with spaces. WHERE valid operators are Example path Example path Example path Equivalent in RouterOS CLI |
|
Remove config/value from RouterOS by ‘.id’. Example Equivalent in RouterOS CLI Note |
|
Timeout for the request. Default: |
|
If is set TLS will be used for RouterOS API connection. Choices:
|
|
Update config/value in RouterOS by ‘.id’ in selected path. Example Equivalent in RouterOS CLI Note |
|
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 added in community.routeros 2.1.0 |
Use |
|
Support: none |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
|
Platform: RouterOS |
Target OS/families that can be operated against. |
Notes
Note
Use the community.routeros.api_modify and community.routeros.api_find_and_modify modules for more specific modifications, and the community.routeros.api_info module for a more controlled way of returning all entries for a path.
See Also
See also
- How to quote and unquote commands and arguments
How to quote and unquote commands and arguments
- 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.
- community.routeros.api_modify
Modify data at paths with API.
- How to connect to RouterOS devices with the RouterOS API
How to connect to RouterOS devices with the RouterOS API
Examples
- name: Get example - ip address print
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
register: ipaddrd_printout
- name: Dump "Get example" output
ansible.builtin.debug:
msg: '{{ ipaddrd_printout }}'
- name: Add example - ip address
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
add: "address=192.168.255.10/24 interface=ether2"
- name: Query example - ".id, address" in "ip address WHERE address == 192.168.255.10/24"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
query: ".id address WHERE address == {{ ip2 }}"
register: queryout
- name: Dump "Query example" output
ansible.builtin.debug:
msg: '{{ queryout }}'
- name: Extended query example - ".id,address,network" where address is not 192.168.255.10/24 or is 10.20.36.20/24
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
extended_query:
attributes:
- network
- address
- .id
where:
- attribute: "network"
is: "=="
value: "192.168.255.0"
- or:
- attribute: "address"
is: "!="
value: "192.168.255.10/24"
- attribute: "address"
is: "eq"
value: "10.20.36.20/24"
- attribute: "network"
is: "in"
value:
- "10.20.36.0"
- "192.168.255.0"
register: extended_queryout
- name: Dump "Extended query example" output
ansible.builtin.debug:
msg: '{{ extended_queryout }}'
- name: Update example - ether2 ip address with ".id = *14"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
update: >-
.id=*14
address=192.168.255.20/24
comment={{ 'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2' | community.routeros.quote_argument_value }}
- name: Remove example - ether2 ip 192.168.255.20/24 with ".id = *14"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "ip address"
remove: "*14"
- name: Arbitrary command example "/system identity print"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "system identity"
cmd: "print"
register: arbitraryout
- name: Dump "Arbitrary command example" output
ansible.builtin.debug:
msg: '{{ arbitraryout }}'
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
All outputs are in list with dictionary elements returned from RouterOS api. Returned: always Sample: |