community.network.routeros_api (1.3.7) — module

Ansible module for RouterOS API

| "added in version" 1.1.0 of community.network"

Authors: Nikolay Dachev (@NikolayDachev)

Install collection

Install with ansible-galaxy collection install community.network:==1.3.7


Add to requirements.yml

  collections:
    - name: community.network
      version: 1.3.7

Description

Ansible module for RouterOS API with python librouteros.

This module can add, remove, update, query and execute arbitrary command in routeros via API.


Requirements

Usage examples

  • Success
    Steampunk Spotter scan finished with no errors, warnings or hints.
---
- 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 }}"

Inputs

    
add:
    description:
    - Will add selected arguments in selected path to RouterOS config.
    - Example C(address=1.1.1.1/32 interface=ether1).
    - Equivalent in RouterOS CLI C(/ip address add address=1.1.1.1/32 interface=ether1).
    type: str

cmd:
    description:
    - Execute any/arbitrary command in selected path, after the command we can add C(.id).
    - Example path C(system script) and cmd C(run .id=*03) is equivalent in RouterOS CLI
      C(/system script run number=0).
    - Example path C(ip address) and cmd C(print) is equivalent in RouterOS CLI C(/ip
      address print).
    type: str

ssl:
    default: false
    description:
    - If is set TLS will be used for RouterOS API connection.
    required: false
    type: bool

path:
    description:
    - Main path for all other arguments.
    - If other arguments are not set, api will return all items in selected path.
    - Example C(ip address). Equivalent of RouterOS CLI C(/ip address print).
    required: true
    type: str

port:
    description:
    - RouterOS api port. If ssl is set, port will apply to ssl connection.
    - Defaults are C(8728) for the HTTP API, and C(8729) for the HTTPS API.
    type: int

query:
    description:
    - 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 C(==), C(!=), C(>), C(<).
    - Example path C(ip address) and query C(.id address) will return only C(.id) and
      C(address) for all items in C(ip address) path.
    - Example path C(ip address) and query C(.id address WHERE address == 1.1.1.3/32).
      will return only C(.id) and C(address) for items in C(ip address) path, where address
      is eq to 1.1.1.3/32.
    - Example path C(interface) and query C(mtu name WHERE mut > 1400) will return only
      interfaces C(mtu,name) where mtu is bigger than 1400.
    - Equivalent in RouterOS CLI C(/interface print where mtu > 1400).
    type: str

remove:
    description:
    - Remove config/value from RouterOS by '.id'.
    - Example C(*03) will remove config/value with C(id=*03) in selected path.
    - Equivalent in RouterOS CLI C(/ip address remove numbers=1).
    - Note C(number) in RouterOS CLI is different from C(.id).
    type: str

update:
    description:
    - Update config/value in RouterOS by '.id' in selected path.
    - Example C(.id=*03 address=1.1.1.3/32) and path C(ip address) will replace existing
      ip address with C(.id=*03).
    - Equivalent in RouterOS CLI C(/ip address set address=1.1.1.3/32 numbers=1).
    - Note C(number) in RouterOS CLI is different from C(.id).
    type: str

hostname:
    description:
    - RouterOS hostname API.
    required: true
    type: str

password:
    description:
    - RouterOS user password.
    required: true
    type: str

username:
    description:
    - RouterOS login user.
    required: true
    type: str

Outputs

message:
  description: All outputs are in list with dictionary elements returned from RouterOS
    api.
  returned: always
  sample: C([{...},{...}])
  type: list