community.routeros.api – Ansible module for RouterOS API

Note

This plugin is part of the community.routeros collection (version 1.2.0).

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 Choices/Defaults Comments
add
string
Will add selected arguments in selected path to RouterOS config.
Example address=1.1.1.1/32 interface=ether1.
Equivalent in RouterOS CLI /ip address add address=1.1.1.1/32 interface=ether1.
cmd
string
Execute any/arbitrary command in selected path, after the command we can add .id.
Example path system script and cmd run .id=*03 is equivalent in RouterOS CLI /system script run number=0.
Example path ip address and cmd print is equivalent in RouterOS CLI /ip address print.
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 ip address. Equivalent of RouterOS CLI /ip address print.
port
integer
RouterOS api port. If ssl is set, port will apply to ssl connection.
Defaults are 8728 for the HTTP API, and 8729 for the HTTPS API.
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 ip address and query .id address will return only .id and address for all items in ip address path.
Example path ip address and query .id address WHERE address == 1.1.1.3/32. will return only .id and address for items in ip address path, where address is eq to 1.1.1.3/32.
Example path interface and query mtu name WHERE mut > 1400 will return only interfaces mtu,name where mtu is bigger than 1400.
Equivalent in RouterOS CLI /interface print where mtu > 1400.
remove
string
Remove config/value from RouterOS by '.id'.
Example *03 will remove config/value with id=*03 in selected path.
Equivalent in RouterOS CLI /ip address remove numbers=1.
Note number in RouterOS CLI is different from .id.
ssl
boolean
    Choices:
  • no ←
  • yes
If is set TLS will be used for RouterOS API connection.
update
string
Update config/value in RouterOS by '.id' in selected path.
Example .id=*03 address=1.1.1.3/32 and path ip address will replace existing ip address with .id=*03.
Equivalent in RouterOS CLI /ip address set address=1.1.1.3/32 numbers=1.
Note number in RouterOS CLI is different from .id.
username
string / required
RouterOS login user.

Notes

Note

  • add, remove, update, cmd and query are mutually exclusive.

  • check_mode is not supported.

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 Returned Description
message
list / elements=string
always
All outputs are in list with dictionary elements returned from RouterOS api.

Sample:
[{...},{...}]


Authors

  • Nikolay Dachev (@NikolayDachev)