community.routeros.api module – Ansible module for RouterOS API

Note

This module is part of the community.routeros collection (version 2.3.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 the Python librouteros library.

  • 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

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.

ca_path

path

added in 1.2.0 of community.routeros

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.

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.

encoding

string

added in 2.1.0 of community.routeros

Use the specified encoding when communicating with the RouterOS device.

Default is ASCII. Note that UTF-8 requires librouteros 3.2.1 or newer.

Default: “ASCII”

extended_query

dictionary

Extended query given path for selected query attributes from RouterOS API.

Extended query allow conjunctive input. If there is no matching entry, an empty list will be returned.

attributes

list / elements=string / required

The list of attributes to return.

Every attribute used in a where clause need to be listed here.

where

list / elements=dictionary

Allows to restrict the objects returned.

The conditions here must all match. An or condition needs at least one of its conditions to match.

attribute

string

The attribute to match. Must be part of attributes.

Either or or all of attribute, is, and value have to be specified.

is

string

The operator to use for matching.

For equality use == or eq. For less use < or less. For more use > or more.

Use in to check whether the value is part of a list. In that case, value must be a list.

Either or or all of attribute, is, and value have to be specified.

Choices:

  • ==

  • !=

  • >

  • <

  • in

  • eq

  • not

  • more

  • less

or

list / elements=dictionary

A list of conditions so that at least one of them has to match.

Either or or all of attribute, is, and value have to be specified.

attribute

string / required

The attribute to match. Must be part of attributes.

is

string / required

The operator to use for matching.

For equality use == or eq. For less use < or less. For more use > or more.

Use in to check whether the value is part of a list. In that case, value must be a list.

Choices:

  • ==

  • !=

  • >

  • <

  • in

  • eq

  • not

  • more

  • less

value

raw / required

The value to compare to. Must be a list for is=in.

value

raw

The value to compare to. Must be a list for is=in.

Either or or all of attribute, is, and value have to be specified.

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 tls is set, port will apply to TLS/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.

WHERE is key word which extend query. WHERE format is key operator value - with spaces.

WHERE valid operators are == or eq, != or not, > or more, < or less.

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.

timeout

integer

added in 2.3.0 of community.routeros

Timeout for the request.

Default: 10

tls

aliases: ssl

boolean

If is set TLS will be used for RouterOS API connection.

Choices:

  • no ← (default)

  • yes

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.

validate_cert_hostname

boolean

added in 1.2.0 of community.routeros

Set to true to validate hostnames in certificates.

See also validate_certs. Only used when tls=true and validate_certs=true.

Choices:

  • no ← (default)

  • yes

validate_certs

boolean

added in 1.2.0 of community.routeros

Set to false to skip validation of TLS certificates.

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:

  • no

  • yes ← (default)

Notes

Note

See Also

See also

How to quote and unquote commands and arguments

How to quote and unquote commands and arguments

community.routeros.api_facts

The official documentation on the community.routeros.api_facts module.

community.routeros.api_find_and_modify

The official documentation on the community.routeros.api_find_and_modify module.

community.routeros.api_info

The official documentation on the community.routeros.api_info module.

community.routeros.api_modify

The official documentation on the community.routeros.api_modify module.

How to connect to RouterOS devices with the RouterOS API

How to connect to RouterOS devices with the RouterOS API

Examples

- name: Get example - ip address print
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
  register: ipaddrd_printout

- name: Dump "Get example" output
  ansible.builtin.debug:
    msg: '{{ ipaddrd_printout }}'

- name: Add example - ip address
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
    add: "address=192.168.255.10/24 interface=ether2"

- name: Query example - ".id, address" in "ip address WHERE address == 192.168.255.10/24"
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
    query: ".id address WHERE address == {{ ip2 }}"
  register: queryout

- name: Dump "Query example" output
  ansible.builtin.debug:
    msg: '{{ queryout }}'

- name: Extended query example - ".id,address,network" where address is not 192.168.255.10/24 or is 10.20.36.20/24
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
    extended_query:
      attributes:
        - network
        - address
        - .id
      where:
        - attribute: "network"
          is: "=="
          value: "192.168.255.0"
        - or:
            - attribute: "address"
              is: "!="
              value: "192.168.255.10/24"
            - attribute: "address"
              is: "eq"
              value: "10.20.36.20/24"
        - attribute: "network"
          is: "in"
          value:
             - "10.20.36.0"
             - "192.168.255.0"
  register: extended_queryout

- name: Dump "Extended query example" output
  ansible.builtin.debug:
    msg: '{{ extended_queryout }}'

- name: Update example - ether2 ip addres with ".id = *14"
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
    update: >-
        .id=*14
        address=192.168.255.20/24
        comment={{ 'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2' | community.routeros.quote_argument_value }}

- name: Remove example - ether2 ip 192.168.255.20/24 with ".id = *14"
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
    remove: "*14"

- name: Arbitrary command example "/system identity print"
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "system identity"
    cmd: "print"
  register: arbitraryout

- name: Dump "Arbitrary command example" output
  ansible.builtin.debug:
    msg: '{{ arbitraryout }}'

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

message

list / elements=string

All outputs are in list with dictionary elements returned from RouterOS api.

Returned: always

Sample: [{“address”: “1.2.3.4”}, {“address”: “2.3.4.5”}]

Authors

  • Nikolay Dachev (@NikolayDachev)