Try SpotterAnsible module for RouterOS API
Authors: Nikolay Dachev (@NikolayDachev)
Install with ansible-galaxy collection install community.routeros:==2.14.0
collections:
- name: community.routeros
version: 2.14.0Ansible module for RouterOS API with the Python C(librouteros) library.
This module can add, remove, update, query and execute arbitrary command in RouterOS via API.
- 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 address 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 }}'
add:
description:
- Will add selected arguments in selected path to RouterOS config.
- Example V(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 V(system script) and cmd V(run .id=*03) is equivalent in RouterOS CLI
C(/system script run number=0).
- Example path V(ip address) and cmd V(print) is equivalent in RouterOS CLI C(/ip
address print).
type: str
tls:
aliases:
- 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 V(ip address). Equivalent of RouterOS CLI C(/ip address print).
required: true
type: str
port:
description:
- RouterOS api port. If O(tls) is set, port will apply to TLS/SSL connection.
- Defaults are V(8728) for the HTTP API, and V(8729) for the HTTPS API.
type: int
query:
description:
- 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 V(==) or V(eq), V(!=) or V(not), V(>) or V(more), V(<)
or V(less).
- Example path V(ip address) and query V(.id address) will return only C(.id) and
C(address) for all items in V(ip address) path.
- Example path V(ip address) and query V(.id address WHERE address == 1.1.1.3/32).
will return only C(.id) and C(address) for items in V(ip address) path, where address
is eq to 1.1.1.3/32.
- Example path V(interface) and query V(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 V(*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 V(.id=*03 address=1.1.1.3/32) and path V(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
ca_path:
description:
- PEM formatted file that contains a CA certificate to be used for certificate validation.
- See also O(validate_cert_hostname). Only used when O(tls=true) and O(validate_certs=true).
type: path
version_added: 1.2.0
version_added_collection: community.routeros
timeout:
default: 10
description:
- Timeout for the request.
type: int
version_added: 2.3.0
version_added_collection: community.routeros
encoding:
default: ASCII
description:
- Use the specified encoding when communicating with the RouterOS device.
- Default is V(ASCII). Note that V(UTF-8) requires librouteros 3.2.1 or newer.
type: str
version_added: 2.1.0
version_added_collection: community.routeros
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
force_no_cert:
default: false
description:
- Set to V(true) to connect without a certificate when O(tls=true).
- See also O(validate_certs).
- B(Note:) this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol
is susceptible to Man-in-the-Middle attacks, because the keys used in the exchange
are not authenticated. Instead of simply connecting without a certificate to "make
things work" have a look at O(validate_certs) and O(ca_path).
type: bool
version_added: 2.4.0
version_added_collection: community.routeros
extended_query:
description:
- 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.
suboptions:
attributes:
description:
- The list of attributes to return.
- Every attribute used in a O(extended_query.where[]) clause need to be listed
here.
elements: str
required: true
type: list
where:
description:
- Allows to restrict the objects returned.
- The conditions here must all match. An O(extended_query.where[].or) condition
needs at least one of its conditions to match.
elements: dict
suboptions:
attribute:
description:
- The attribute to match. Must be part of O(extended_query.attributes).
- Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute),
O(extended_query.where[].is), and O(extended_query.where[].value) have to
be specified.
type: str
is:
choices:
- ==
- '!='
- '>'
- <
- in
- eq
- not
- more
- less
description:
- The operator to use for matching.
- For equality use V(==) or V(eq). For less use V(<) or V(less). For more
use V(>) or V(more).
- Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].value)
must be a list.
- Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute),
O(extended_query.where[].is), and O(extended_query.where[].value) have to
be specified.
type: str
or:
description:
- A list of conditions so that at least one of them has to match.
- Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute),
O(extended_query.where[].is), and O(extended_query.where[].value) have to
be specified.
elements: dict
suboptions:
attribute:
description:
- The attribute to match. Must be part of O(extended_query.attributes).
required: true
type: str
is:
choices:
- ==
- '!='
- '>'
- <
- in
- eq
- not
- more
- less
description:
- The operator to use for matching.
- For equality use V(==) or V(eq). For less use V(<) or V(less). For more
use V(>) or V(more).
- Use V(in) to check whether the value is part of a list. In that case,
O(extended_query.where[].or[].value) must be a list.
required: true
type: str
value:
description:
- The value to compare to. Must be a list for O(extended_query.where[].or[].is=in).
required: true
type: raw
type: list
value:
description:
- The value to compare to. Must be a list for O(extended_query.where[].is=in).
- Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute),
O(extended_query.where[].is), and O(extended_query.where[].value) have to
be specified.
type: raw
type: list
type: dict
validate_certs:
default: true
description:
- Set to V(false) to skip validation of TLS certificates.
- See also O(validate_cert_hostname). Only used when O(tls=true).
- B(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
O(ca_path) option.
type: bool
version_added: 1.2.0
version_added_collection: community.routeros
validate_cert_hostname:
default: false
description:
- Set to V(true) to validate hostnames in certificates.
- See also O(validate_certs). Only used when O(tls=true) and O(validate_certs=true).
type: bool
version_added: 1.2.0
version_added_collection: community.routeros
message:
description: 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
type: list