community / community.routeros / 2.14.0 / module / api Ansible module for RouterOS API Authors: Nikolay Dachev (@NikolayDachev)community.routeros.api (2.14.0) — module
Install with ansible-galaxy collection install community.routeros:==2.14.0
collections: - name: community.routeros version: 2.14.0
Ansible 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