community.network.routeros_api – Ansible module for RouterOS API¶
Note
This plugin is part of the community.network collection (version 1.3.2).
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¶
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)