community.routeros.api – Ansible module for RouterOS API
Note
This plugin is part of the community.routeros collection (version 1.2.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.
Synopsis
Ansible module for RouterOS API with python librouteros.
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 validate_cert_hostname. Only used when tls=true and validate_certs=true. |
|
Execute any/arbitrary command in selected path, after the command we can add Example path Example path |
|
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 tls is set, port will apply to TLS/SSL connection. Defaults are |
|
Query given path for selected query attributes from RouterOS aip and return ‘.id’. 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 |
|
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 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:
|
Examples
---
- name: Use RouterOS API
hosts: localhost
gather_facts: no
vars:
hostname: "ros_api_hostname/ip"
username: "admin"
password: "secret_password"
path: "ip address"
nic: "ether2"
ip1: "1.1.1.1/32"
ip2: "2.2.2.2/32"
ip3: "3.3.3.3/32"
tasks:
- name: Get "{{ path }} print"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "{{ path }}"
register: print_path
- name: Dump "{{ path }} print" output
ansible.builtin.debug:
msg: '{{ print_path }}'
- name: Add ip address "{{ ip1 }}" and "{{ ip2 }}"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "{{ path }}"
add: "{{ item }}"
loop:
- "address={{ ip1 }} interface={{ nic }}"
- "address={{ ip2 }} interface={{ nic }}"
register: addout
- name: Dump "Add ip address" output - ".id" for new added items
ansible.builtin.debug:
msg: '{{ addout }}'
- name: Query for ".id" in "{{ path }} WHERE address == {{ ip2 }}"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "{{ path }}"
query: ".id address WHERE address == {{ ip2 }}"
register: queryout
- name: Dump "Query for" output and set fact with ".id" for "{{ ip2 }}"
ansible.builtin.debug:
msg: '{{ queryout }}'
- name: Store query_id for later usage
ansible.builtin.set_fact:
query_id: "{{ queryout['msg'][0]['.id'] }}"
- name: Update ".id = {{ query_id }}" taken with custom fact "fquery_id"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "{{ path }}"
update: ".id={{ query_id }} address={{ ip3 }}"
register: updateout
- name: Dump "Update" output
ansible.builtin.debug:
msg: '{{ updateout }}'
- name: Remove ips - stage 1 - query ".id" for "{{ ip2 }}" and "{{ ip3 }}"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "{{ path }}"
query: ".id address WHERE address == {{ item }}"
register: id_to_remove
loop:
- "{{ ip2 }}"
- "{{ ip3 }}"
- name: Set fact for ".id" from "Remove ips - stage 1 - query"
ansible.builtin.set_fact:
to_be_remove: "{{ to_be_remove |default([]) + [item['msg'][0]['.id']] }}"
loop: "{{ id_to_remove.results }}"
- name: Dump "Remove ips - stage 1 - query" output
ansible.builtin.debug:
msg: '{{ to_be_remove }}'
# Remove "{{ rmips }}" with ".id" by "to_be_remove" from query
- name: Remove ips - stage 2 - remove "{{ ip2 }}" and "{{ ip3 }}" by '.id'
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "{{ path }}"
remove: "{{ item }}"
register: remove
loop: "{{ to_be_remove }}"
- name: Dump "Remove ips - stage 2 - remove" output
ansible.builtin.debug:
msg: '{{ remove }}'
- name: Arbitrary command example "/system identity print"
community.routeros.api:
hostname: "{{ hostname }}"
password: "{{ password }}"
username: "{{ username }}"
path: "system identity"
cmd: "print"
register: cmdout
- name: Dump "Arbitrary command example" output
ansible.builtin.debug:
msg: "{{ cmdout }}"
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: “C([{…},{…}])” |
Authors
Nikolay Dachev (@NikolayDachev)