community.network.routeros_api – Ansible module for RouterOS API
community.network.routeros_api – Ansible module for RouterOS API
Note
This plugin is part of the community.network collection (version 1.3.0).
To install it use: ansible-galaxy collection install community.network
.
To use it in a playbook, specify: community.network.routeros_api
.
New in version 1.1.0: of community.network
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 | Choices/Defaults | Comments |
---|---|---|
add string |
Will add selected arguments in selected path to RouterOS config. Example Equivalent in RouterOS CLI | |
cmd string |
Execute any/arbitrary command in selected path, after the command we can add Example path Example path | |
hostname string / required |
RouterOS hostname API. | |
password string / required |
RouterOS user password. | |
path string / required |
Main path for all other arguments. If other arguments are not set, api will return all items in selected path. Example | |
port integer |
RouterOS api port. If ssl is set, port will apply to ssl connection. Defaults are | |
query string |
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 string |
Remove config/value from RouterOS by '.id'. Example Equivalent in RouterOS CLI Note | |
ssl boolean |
|
If is set TLS will be used for RouterOS API connection. |
update string |
Update config/value in RouterOS by '.id' in selected path. Example Equivalent in RouterOS CLI Note | |
username string / required |
RouterOS login user. |
Notes
Note
- add, remove, update, cmd and query are mutually exclusive.
- check_mode is not supported.
Examples
---
- name: Test 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.network.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.network.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.network.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 }}'
- ansible.builtin.set_fact:
query_id : "{{ queryout['msg'][0]['.id'] }}"
- name: Update ".id = {{ query_id }}" taken with custom fact "fquery_id"
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 }}"
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'
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"
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 | Returned | Description |
---|---|---|
message list / elements=string |
always |
All outputs are in list with dictionary elements returned from RouterOS api.
Sample:
|
Authors
- Nikolay Dachev (@NikolayDachev)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/community/network/routeros_api_module.html