mirror.MikroTik/ansible-collections.community.routeros
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.routeros.git synced 2025-06-24 10:48:49 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Reformat documentation with 'andebox yaml-doc' (#335)

Browse source 
* Reformat documentation with 'andebox yaml-doc'.

* Revert unwanted changes.
This commit is contained in:
Felix Fontein 2024-12-28 15:34:20 +01:00 • committed by GitHub
parent 77de6d90bf
commit 539119c57d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 717 additions and 758 deletions
Download patch file Download diff file Expand all files Collapse all files

9
plugins/cliconf/routeros.py
View file

@ -5,15 +5,14 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
author: "Egor Zaitsev (@heuels)" author: "Egor Zaitsev (@heuels)"
name: routeros name: routeros
short_description: Use routeros cliconf to run command on MikroTik RouterOS platform short_description: Use routeros cliconf to run command on MikroTik RouterOS platform
description: description:
- This routeros plugin provides low level abstraction apis for - This routeros plugin provides low level abstraction apis for sending and receiving CLI commands from MikroTik RouterOS
sending and receiving CLI commands from MikroTik RouterOS network devices. network devices.
''' """
import re import re
import json import json

39
plugins/doc_fragments/api.py
View file

@ -10,7 +10,7 @@ __metaclass__ = type
class ModuleDocFragment(object): class ModuleDocFragment(object):
DOCUMENTATION = r''' DOCUMENTATION = r"""
options: options:
hostname: hostname:
description: description:
@ -50,10 +50,9 @@ options:
description: description:
- Set to V(true) to connect without a certificate when O(tls=true). - Set to V(true) to connect without a certificate when O(tls=true).
- See also O(validate_certs). - See also O(validate_certs).
- B(Note:) this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible - B(Note:) this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible to Man-in-the-Middle
to Man-in-the-Middle attacks, because the keys used in the exchange are not authenticated. attacks, because the keys used in the exchange are not authenticated. Instead of simply connecting without a certificate
Instead of simply connecting without a certificate to "make things work" have a look at to "make things work" have a look at O(validate_certs) and O(ca_path).
O(validate_certs) and O(ca_path).
type: bool type: bool
default: false default: false
version_added: 2.4.0 version_added: 2.4.0
@ -61,10 +60,9 @@ options:
description: description:
- Set to V(false) to skip validation of TLS certificates. - Set to V(false) to skip validation of TLS certificates.
- See also O(validate_cert_hostname). Only used when O(tls=true). - See also O(validate_cert_hostname). Only used when O(tls=true).
- B(Note:) instead of simply deactivating certificate validations to "make things work", - B(Note:) instead of simply deactivating certificate validations to "make things work", please consider creating your
please consider creating your own CA certificate and using it to sign certificates used own CA certificate and using it to sign certificates used for your router. You can tell the module about your CA certificate
for your router. You can tell the module about your CA certificate with the O(ca_path) with the O(ca_path) option.
option.
type: bool type: bool
default: true default: true
version_added: 1.2.0 version_added: 1.2.0
@ -93,10 +91,10 @@ requirements:
- Python >= 3.6 (for librouteros) - Python >= 3.6 (for librouteros)
seealso: seealso:
- ref: ansible_collections.community.routeros.docsite.api-guide - ref: ansible_collections.community.routeros.docsite.api-guide
description: How to connect to RouterOS devices with the RouterOS API description: How to connect to RouterOS devices with the RouterOS API.
''' """
RESTRICT = r''' RESTRICT = r"""
options: options:
restrict: restrict:
type: list type: list
@ -115,24 +113,21 @@ options:
values: values:
description: description:
- The values of the field to limit to. - The values of the field to limit to.
- >- - 'Note that the types of the values are important. If you provide a string V("0"), and librouteros converts the
Note that the types of the values are important. If you provide a string V("0"), value returned by the API to the integer V(0), then this will not match. If you are not sure, better include both
and librouteros converts the value returned by the API to the integer V(0), variants: both the string and the integer.'
then this will not match. If you are not sure, better include both variants:
both the string and the integer.
type: list type: list
elements: raw elements: raw
regex: regex:
description: description:
- A regular expression matching values of the field to limit to. - A regular expression matching values of the field to limit to.
- Note that all values will be converted to strings before matching. - Note that all values will be converted to strings before matching.
- It is not possible to match disabled values with regular expressions. - It is not possible to match disabled values with regular expressions. Set O(restrict[].match_disabled=true) if
Set O(restrict[].match_disabled=true) if you also want to match disabled values. you also want to match disabled values.
type: str type: str
invert: invert:
description: description:
- Invert the condition. This affects O(restrict[].match_disabled), O(restrict[].values), - Invert the condition. This affects O(restrict[].match_disabled), O(restrict[].values), and O(restrict[].regex).
and O(restrict[].regex).
type: bool type: bool
default: false default: false
''' """

62
plugins/doc_fragments/attributes.py
View file

@ -11,17 +11,17 @@ __metaclass__ = type
class ModuleDocFragment(object): class ModuleDocFragment(object):
# Standard documentation fragment # Standard documentation fragment
DOCUMENTATION = r''' DOCUMENTATION = r"""
options: {} options: {}
attributes: attributes:
check_mode: check_mode:
description: Can run in C(check_mode) and return changed status prediction without modifying target. description: Can run in C(check_mode) and return changed status prediction without modifying target.
diff_mode: diff_mode:
description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode. description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
platform: platform:
description: Target OS/families that can be operated against. description: Target OS/families that can be operated against.
support: N/A support: N/A
''' """
# Should be used together with the standard fragment # Should be used together with the standard fragment
INFO_MODULE = r''' INFO_MODULE = r'''
@ -47,23 +47,23 @@ attributes:
- community.routeros.api - community.routeros.api
''' '''
CONN = r''' CONN = r"""
options: {} options: {}
attributes: attributes:
become: become:
description: Is usable alongside C(become) keywords. description: Is usable alongside C(become) keywords.
connection: connection:
description: Uses the target's configured connection information to execute code on it. description: Uses the target's configured connection information to execute code on it.
delegation: delegation:
description: Can be used in conjunction with C(delegate_to) and related keywords. description: Can be used in conjunction with C(delegate_to) and related keywords.
''' """
FACTS = r''' FACTS = r"""
options: {} options: {}
attributes: attributes:
facts: facts:
description: Action returns an C(ansible_facts) dictionary that will update existing host facts. description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
''' """
# Should be used together with the standard fragment and the FACTS fragment # Should be used together with the standard fragment and the FACTS fragment
FACTS_MODULE = r''' FACTS_MODULE = r'''
@ -81,18 +81,18 @@ attributes:
support: full support: full
''' '''
FILES = r''' FILES = r"""
options: {} options: {}
attributes: attributes:
safe_file_operations: safe_file_operations:
description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption. description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
''' """
FLOW = r''' FLOW = r"""
options: {} options: {}
attributes: attributes:
action: action:
description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller. description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
async: async:
description: Supports being used with the C(async) keyword. description: Supports being used with the C(async) keyword.
''' """

63
plugins/modules/api.py
View file

@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: api module: api
author: "Nikolay Dachev (@NikolayDachev)" author: "Nikolay Dachev (@NikolayDachev)"
short_description: Ansible module for RouterOS API short_description: Ansible module for RouterOS API
@ -18,9 +17,8 @@ description:
- This module can add, remove, update, query and execute arbitrary command in RouterOS via API. - This module can add, remove, update, query and execute arbitrary command in RouterOS via API.
notes: notes:
- O(add), O(remove), O(update), O(cmd), and O(query) are mutually exclusive. - O(add), O(remove), O(update), O(cmd), and O(query) are mutually exclusive.
- Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules - Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules for more specific modifications,
for more specific modifications, and the M(community.routeros.api_info) module for a more controlled and the M(community.routeros.api_info) module for a more controlled way of returning all entries for a path.
way of returning all entries for a path.
extends_documentation_fragment: extends_documentation_fragment:
- community.routeros.api - community.routeros.api
- community.routeros.attributes - community.routeros.attributes
@ -68,11 +66,12 @@ options:
- Query given path for selected query attributes from RouterOS aip. - 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 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). - 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) will return only C(.id) and C(address) for all items in V(ip address)
- Example path V(ip address) and query V(.id address WHERE address == 1.1.1.3/32). path.
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(ip address) and query V(.id address WHERE address == 1.1.1.3/32). will return only C(.id) and C(address)
- Example path V(interface) and query V(mtu name WHERE mut > 1400) will for items in V(ip address) path, where address is eq to 1.1.1.3/32.
return only interfaces C(mtu,name) where mtu is bigger than 1400. - 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). - Equivalent in RouterOS CLI C(/interface print where mtu > 1400).
type: str type: str
extended_query: extended_query:
@ -91,7 +90,8 @@ options:
where: where:
description: description:
- Allows to restrict the objects returned. - 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. - The conditions here must all match. An O(extended_query.where[].or) condition needs at least one of its conditions
to match.
type: list type: list
elements: dict elements: dict
suboptions: suboptions:
@ -105,7 +105,8 @@ options:
description: description:
- The operator to use for matching. - 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). - 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. - 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), - 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. and O(extended_query.where[].value) have to be specified.
type: str type: str
@ -133,7 +134,8 @@ options:
description: description:
- The operator to use for matching. - 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). - 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. - 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.
type: str type: str
choices: ["==", "!=", ">", "<", "in", "eq", "not", "more", "less"] choices: ["==", "!=", ">", "<", "in", "eq", "not", "more", "less"]
required: true required: true
@ -150,14 +152,14 @@ options:
type: str type: str
seealso: seealso:
- ref: ansible_collections.community.routeros.docsite.quoting - ref: ansible_collections.community.routeros.docsite.quoting
description: How to quote and unquote commands and arguments description: How to quote and unquote commands and arguments.
- module: community.routeros.api_facts - module: community.routeros.api_facts
- module: community.routeros.api_find_and_modify - module: community.routeros.api_find_and_modify
- module: community.routeros.api_info - module: community.routeros.api_info
- module: community.routeros.api_modify - module: community.routeros.api_modify
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Get example - ip address print - name: Get example - ip address print
community.routeros.api: community.routeros.api:
hostname: "{{ hostname }}" hostname: "{{ hostname }}"
@ -216,8 +218,8 @@ EXAMPLES = '''
- attribute: "network" - attribute: "network"
is: "in" is: "in"
value: value:
- "10.20.36.0" - "10.20.36.0"
- "192.168.255.0" - "192.168.255.0"
register: extended_queryout register: extended_queryout
- name: Dump "Extended query example" output - name: Dump "Extended query example" output
@ -231,9 +233,9 @@ EXAMPLES = '''
username: "{{ username }}" username: "{{ username }}"
path: "ip address" path: "ip address"
update: >- update: >-
.id=*14 .id=*14
address=192.168.255.20/24 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 }} 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" - name: Remove example - ether2 ip 192.168.255.20/24 with ".id = *14"
community.routeros.api: community.routeros.api:
@ -255,18 +257,17 @@ EXAMPLES = '''
- name: Dump "Arbitrary command example" output - name: Dump "Arbitrary command example" output
ansible.builtin.debug: ansible.builtin.debug:
msg: '{{ arbitraryout }}' msg: '{{ arbitraryout }}'
''' """
RETURN = ''' RETURN = r"""
---
message: message:
description: All outputs are in list with dictionary elements returned from RouterOS api. description: All outputs are in list with dictionary elements returned from RouterOS api.
sample: sample:
- address: 1.2.3.4 - address: 1.2.3.4
- address: 2.3.4.5 - address: 2.3.4.5
type: list type: list
returned: always returned: always
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_native from ansible.module_utils.common.text.converters import to_native

35
plugins/modules/api_facts.py
View file

@ -9,23 +9,20 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: api_facts module: api_facts
author: author:
- "Egor Zaitsev (@heuels)" - "Egor Zaitsev (@heuels)"
- "Nikolay Dachev (@NikolayDachev)" - "Nikolay Dachev (@NikolayDachev)"
- "Felix Fontein (@felixfontein)" - "Felix Fontein (@felixfontein)"
version_added: 2.1.0 version_added: 2.1.0
short_description: Collect facts from remote devices running MikroTik RouterOS using the API short_description: Collect facts from remote devices running MikroTik RouterOS using the API
description: description:
- Collects a base set of device facts from a remote device that - Collects a base set of device facts from a remote device that is running RouterOS. This module prepends all of the base
is running RouterOS. This module prepends all of the network fact keys with C(ansible_net_<fact>). The facts module will always collect a base set of facts from the device
base network fact keys with C(ansible_net_<fact>). The facts
module will always collect a base set of facts from the device
and can enable or disable collection of additional facts. and can enable or disable collection of additional facts.
- As opposed to the M(community.routeros.facts) module, it uses the - As opposed to the M(community.routeros.facts) module, it uses the RouterOS API, similar to the M(community.routeros.api)
RouterOS API, similar to the M(community.routeros.api) module. module.
extends_documentation_fragment: extends_documentation_fragment:
- community.routeros.api - community.routeros.api
- community.routeros.attributes - community.routeros.attributes
@ -39,12 +36,10 @@ attributes:
options: options:
gather_subset: gather_subset:
description: description:
- When supplied, this argument will restrict the facts collected - When supplied, this argument will restrict the facts collected to a given subset. Possible values for this argument
to a given subset. Possible values for this argument include include V(all), V(hardware), V(interfaces), and V(routing).
V(all), V(hardware), V(interfaces), and V(routing). - Can specify a list of values to include a larger subset. Values can also be used with an initial V(!) to specify that
- Can specify a list of values to include a larger subset. a specific subset should not be collected.
Values can also be used with an initial V(!) to specify that a
specific subset should not be collected.
required: false required: false
default: default:
- all - all
@ -56,9 +51,9 @@ seealso:
- module: community.routeros.api_find_and_modify - module: community.routeros.api_find_and_modify
- module: community.routeros.api_info - module: community.routeros.api_info
- module: community.routeros.api_modify - module: community.routeros.api_modify
''' """
EXAMPLES = """ EXAMPLES = r"""
- name: Collect all facts from the device - name: Collect all facts from the device
community.routeros.api_facts: community.routeros.api_facts:
hostname: 192.168.88.1 hostname: 192.168.88.1
@ -75,7 +70,7 @@ EXAMPLES = """
- "!hardware" - "!hardware"
""" """
RETURN = """ RETURN = r"""
ansible_facts: ansible_facts:
description: "Dictionary of IP geolocation facts for a host's IP address." description: "Dictionary of IP geolocation facts for a host's IP address."
returned: always returned: always

111
plugins/modules/api_find_and_modify.py
View file

@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: api_find_and_modify module: api_find_and_modify
author: author:
- "Felix Fontein (@felixfontein)" - "Felix Fontein (@felixfontein)"
@ -17,13 +16,13 @@ short_description: Find and modify information using the API
version_added: 2.1.0 version_added: 2.1.0
description: description:
- Allows to find entries for a path by conditions and modify the values of these entries. - Allows to find entries for a path by conditions and modify the values of these entries.
- Use the M(community.routeros.api_find_and_modify) module to set all entries of a path to specific values, - Use the M(community.routeros.api_find_and_modify) module to set all entries of a path to specific values, or change multiple
or change multiple entries in different ways in one step. entries in different ways in one step.
notes: notes:
- "If you want to change values based on their old values (like change all comments 'foo' to 'bar') and make sure that - "If you want to change values based on their old values (like change all comments 'foo' to 'bar') and make sure that there
there are at least N such values, you can use O(require_matches_min=N) together with O(allow_no_matches=true). are at least N such values, you can use O(require_matches_min=N) together with O(allow_no_matches=true). This will make
This will make the module fail if there are less than N such entries, but not if there is no match. The latter case the module fail if there are less than N such entries, but not if there is no match. The latter case is needed for idempotency
is needed for idempotency of the task: once the values have been changed, there should be no further match." of the task: once the values have been changed, there should be no further match."
extends_documentation_fragment: extends_documentation_fragment:
- community.routeros.api - community.routeros.api
- community.routeros.attributes - community.routeros.attributes
@ -79,10 +78,9 @@ seealso:
- module: community.routeros.api_facts - module: community.routeros.api_facts
- module: community.routeros.api_modify - module: community.routeros.api_modify
- module: community.routeros.api_info - module: community.routeros.api_info
''' """
EXAMPLES = ''' EXAMPLES = r"""
---
- name: Rename bridge from 'bridge' to 'my-bridge' - name: Rename bridge from 'bridge' to 'my-bridge'
community.routeros.api_find_and_modify: community.routeros.api_find_and_modify:
hostname: "{{ hostname }}" hostname: "{{ hostname }}"
@ -104,59 +102,58 @@ EXAMPLES = '''
interface: bridge interface: bridge
values: values:
address: "192.168.1.1/24" address: "192.168.1.1/24"
# If there are zero entries, or more than one: fail! We expected that # If there are zero entries, or more than one: fail! We expected that
# exactly one is configured. # exactly one is configured.
require_matches_min: 1 require_matches_min: 1
require_matches_max: 1 require_matches_max: 1
''' """
RETURN = ''' RETURN = r"""
---
old_data: old_data:
description: description:
- A list of all elements for the current path before a change was made. - A list of all elements for the current path before a change was made.
sample: sample:
- '.id': '*1' - '.id': '*1'
actual-interface: bridge actual-interface: bridge
address: "192.168.88.1/24" address: "192.168.88.1/24"
comment: defconf comment: defconf
disabled: false disabled: false
dynamic: false dynamic: false
interface: bridge interface: bridge
invalid: false invalid: false
network: 192.168.88.0 network: 192.168.88.0
type: list type: list
elements: dict elements: dict
returned: success returned: success
new_data: new_data:
description: description:
- A list of all elements for the current path after a change was made. - A list of all elements for the current path after a change was made.
sample: sample:
- '.id': '*1' - '.id': '*1'
actual-interface: bridge actual-interface: bridge
address: "192.168.1.1/24" address: "192.168.1.1/24"
comment: awesome comment: awesome
disabled: false disabled: false
dynamic: false dynamic: false
interface: bridge interface: bridge
invalid: false invalid: false
network: 192.168.1.0 network: 192.168.1.0
type: list type: list
elements: dict elements: dict
returned: success returned: success
match_count: match_count:
description: description:
- The number of entries that matched the criteria in O(find). - The number of entries that matched the criteria in O(find).
sample: 1 sample: 1
type: int type: int
returned: success returned: success
modify__count: modify__count:
description: description:
- The number of entries that were modified. - The number of entries that were modified.
sample: 1 sample: 1
type: int type: int
returned: success returned: success
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_native from ansible.module_utils.common.text.converters import to_native

493
plugins/modules/api_info.py
View file

@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: api_info module: api_info
author: author:
- "Felix Fontein (@felixfontein)" - "Felix Fontein (@felixfontein)"
@ -18,12 +17,12 @@ version_added: 2.2.0
description: description:
- Allows to retrieve information for a path using the API. - Allows to retrieve information for a path using the API.
- This can be used to backup a path to restore it with the M(community.routeros.api_modify) module. - This can be used to backup a path to restore it with the M(community.routeros.api_modify) module.
- Entries are normalized, dynamic and builtin entries are not returned. Use the O(handle_disabled) and - Entries are normalized, dynamic and builtin entries are not returned. Use the O(handle_disabled) and O(hide_defaults)
O(hide_defaults) options to control normalization, the O(include_dynamic) and O(include_builtin) options to also return options to control normalization, the O(include_dynamic) and O(include_builtin) options to also return dynamic resp. builtin
dynamic resp. builtin entries, and use O(unfiltered) to return all fields including counters. entries, and use O(unfiltered) to return all fields including counters.
- B(Note) that this module is still heavily in development, and only supports B(some) paths. - B(Note) that this module is still heavily in development, and only supports B(some) paths. If you want to support new
If you want to support new paths, or think you found problems with existing paths, please first paths, or think you found problems with existing paths, please first L(create an issue in the community.routeros Issue
L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/). Tracker,https://github.com/ansible-collections/community.routeros/issues/).
extends_documentation_fragment: extends_documentation_fragment:
- community.routeros.api - community.routeros.api
- community.routeros.api.restrict - community.routeros.api.restrict
@ -43,225 +42,225 @@ options:
type: str type: str
choices: choices:
# BEGIN PATH LIST # BEGIN PATH LIST
- caps-man aaa - caps-man aaa
- caps-man access-list - caps-man access-list
- caps-man channel - caps-man channel
- caps-man configuration - caps-man configuration
- caps-man datapath - caps-man datapath
- caps-man manager - caps-man manager
- caps-man manager interface - caps-man manager interface
- caps-man provisioning - caps-man provisioning
- caps-man security - caps-man security
- certificate settings - certificate settings
- interface bonding - interface bonding
- interface bridge - interface bridge
- interface bridge mlag - interface bridge mlag
- interface bridge port - interface bridge port
- interface bridge port-controller - interface bridge port-controller
- interface bridge port-extender - interface bridge port-extender
- interface bridge settings - interface bridge settings
- interface bridge vlan - interface bridge vlan
- interface detect-internet - interface detect-internet
- interface eoip - interface eoip
- interface ethernet - interface ethernet
- interface ethernet poe - interface ethernet poe
- interface ethernet switch - interface ethernet switch
- interface ethernet switch port - interface ethernet switch port
- interface gre - interface gre
- interface gre6 - interface gre6
- interface l2tp-client - interface l2tp-client
- interface l2tp-server server - interface l2tp-server server
- interface list - interface list
- interface list member - interface list member
- interface ovpn-client - interface ovpn-client
- interface ovpn-server server - interface ovpn-server server
- interface ppp-client - interface ppp-client
- interface pppoe-client - interface pppoe-client
- interface pppoe-server server - interface pppoe-server server
- interface pptp-server server - interface pptp-server server
- interface sstp-server server - interface sstp-server server
- interface vlan - interface vlan
- interface vrrp - interface vrrp
- interface wifi - interface wifi
- interface wifi aaa - interface wifi aaa
- interface wifi access-list - interface wifi access-list
- interface wifi cap - interface wifi cap
- interface wifi capsman - interface wifi capsman
- interface wifi channel - interface wifi channel
- interface wifi configuration - interface wifi configuration
- interface wifi datapath - interface wifi datapath
- interface wifi interworking - interface wifi interworking
- interface wifi provisioning - interface wifi provisioning
- interface wifi security - interface wifi security
- interface wifi steering - interface wifi steering
- interface wifiwave2 - interface wifiwave2
- interface wifiwave2 aaa - interface wifiwave2 aaa
- interface wifiwave2 access-list - interface wifiwave2 access-list
- interface wifiwave2 cap - interface wifiwave2 cap
- interface wifiwave2 capsman - interface wifiwave2 capsman
- interface wifiwave2 channel - interface wifiwave2 channel
- interface wifiwave2 configuration - interface wifiwave2 configuration
- interface wifiwave2 datapath - interface wifiwave2 datapath
- interface wifiwave2 interworking - interface wifiwave2 interworking
- interface wifiwave2 provisioning - interface wifiwave2 provisioning
- interface wifiwave2 security - interface wifiwave2 security
- interface wifiwave2 steering - interface wifiwave2 steering
- interface wireguard - interface wireguard
- interface wireguard peers - interface wireguard peers
- interface wireless - interface wireless
- interface wireless align - interface wireless align
- interface wireless cap - interface wireless cap
- interface wireless security-profiles - interface wireless security-profiles
- interface wireless sniffer - interface wireless sniffer
- interface wireless snooper - interface wireless snooper
- iot modbus - iot modbus
- ip accounting - ip accounting
- ip accounting web-access - ip accounting web-access
- ip address - ip address
- ip arp - ip arp
- ip cloud - ip cloud
- ip cloud advanced - ip cloud advanced
- ip dhcp-client - ip dhcp-client
- ip dhcp-client option - ip dhcp-client option
- ip dhcp-relay - ip dhcp-relay
- ip dhcp-server - ip dhcp-server
- ip dhcp-server config - ip dhcp-server config
- ip dhcp-server lease - ip dhcp-server lease
- ip dhcp-server matcher - ip dhcp-server matcher
- ip dhcp-server network - ip dhcp-server network
- ip dhcp-server option - ip dhcp-server option
- ip dhcp-server option sets - ip dhcp-server option sets
- ip dns - ip dns
- ip dns adlist - ip dns adlist
- ip dns static - ip dns static
- ip firewall address-list - ip firewall address-list
- ip firewall connection tracking - ip firewall connection tracking
- ip firewall filter - ip firewall filter
- ip firewall layer7-protocol - ip firewall layer7-protocol
- ip firewall mangle - ip firewall mangle
- ip firewall nat - ip firewall nat
- ip firewall raw - ip firewall raw
- ip firewall service-port - ip firewall service-port
- ip hotspot service-port - ip hotspot service-port
- ip ipsec identity - ip ipsec identity
- ip ipsec peer - ip ipsec peer
- ip ipsec policy - ip ipsec policy
- ip ipsec profile - ip ipsec profile
- ip ipsec proposal - ip ipsec proposal
- ip ipsec settings - ip ipsec settings
- ip neighbor discovery-settings - ip neighbor discovery-settings
- ip pool - ip pool
- ip proxy - ip proxy
- ip route - ip route
- ip route rule - ip route rule
- ip route vrf - ip route vrf
- ip service - ip service
- ip settings - ip settings
- ip smb - ip smb
- ip socks - ip socks
- ip ssh - ip ssh
- ip tftp settings - ip tftp settings
- ip traffic-flow - ip traffic-flow
- ip traffic-flow ipfix - ip traffic-flow ipfix
- ip traffic-flow target - ip traffic-flow target
- ip upnp - ip upnp
- ip upnp interfaces - ip upnp interfaces
- ip vrf - ip vrf
- ipv6 address - ipv6 address
- ipv6 dhcp-client - ipv6 dhcp-client
- ipv6 dhcp-server - ipv6 dhcp-server
- ipv6 dhcp-server option - ipv6 dhcp-server option
- ipv6 firewall address-list - ipv6 firewall address-list
- ipv6 firewall filter - ipv6 firewall filter
- ipv6 firewall mangle - ipv6 firewall mangle
- ipv6 firewall nat - ipv6 firewall nat
- ipv6 firewall raw - ipv6 firewall raw
- ipv6 nd - ipv6 nd
- ipv6 nd prefix - ipv6 nd prefix
- ipv6 nd prefix default - ipv6 nd prefix default
- ipv6 route - ipv6 route
- ipv6 settings - ipv6 settings
- mpls - mpls
- mpls interface - mpls interface
- mpls ldp - mpls ldp
- mpls ldp accept-filter - mpls ldp accept-filter
- mpls ldp advertise-filter - mpls ldp advertise-filter
- mpls ldp interface - mpls ldp interface
- port firmware - port firmware
- port remote-access - port remote-access
- ppp aaa - ppp aaa
- ppp profile - ppp profile
- ppp secret - ppp secret
- queue interface - queue interface
- queue simple - queue simple
- queue tree - queue tree
- queue type - queue type
- radius - radius
- radius incoming - radius incoming
- routing bgp aggregate - routing bgp aggregate
- routing bgp connection - routing bgp connection
- routing bgp instance - routing bgp instance
- routing bgp network - routing bgp network
- routing bgp peer - routing bgp peer
- routing bgp template - routing bgp template
- routing filter - routing filter
- routing filter community-list - routing filter community-list
- routing filter num-list - routing filter num-list
- routing filter rule - routing filter rule
- routing filter select-rule - routing filter select-rule
- routing id - routing id
- routing igmp-proxy - routing igmp-proxy
- routing igmp-proxy interface - routing igmp-proxy interface
- routing mme - routing mme
- routing ospf area - routing ospf area
- routing ospf area range - routing ospf area range
- routing ospf instance - routing ospf instance
- routing ospf interface-template - routing ospf interface-template
- routing ospf static-neighbor - routing ospf static-neighbor
- routing pimsm instance - routing pimsm instance
- routing pimsm interface-template - routing pimsm interface-template
- routing rip - routing rip
- routing ripng - routing ripng
- routing rule - routing rule
- routing table - routing table
- snmp - snmp
- snmp community - snmp community
- system clock - system clock
- system clock manual - system clock manual
- system health settings - system health settings
- system identity - system identity
- system leds settings - system leds settings
- system logging - system logging
- system logging action - system logging action
- system note - system note
- system ntp client - system ntp client
- system ntp client servers - system ntp client servers
- system ntp server - system ntp server
- system package update - system package update
- system resource irq rps - system resource irq rps
- system routerboard settings - system routerboard settings
- system scheduler - system scheduler
- system script - system script
- system upgrade mirror - system upgrade mirror
- system ups - system ups
- system watchdog - system watchdog
- tool bandwidth-server - tool bandwidth-server
- tool e-mail - tool e-mail
- tool graphing - tool graphing
- tool graphing interface - tool graphing interface
- tool graphing resource - tool graphing resource
- tool mac-server - tool mac-server
- tool mac-server mac-winbox - tool mac-server mac-winbox
- tool mac-server ping - tool mac-server ping
- tool netwatch - tool netwatch
- tool romon - tool romon
- tool sms - tool sms
- tool sniffer - tool sniffer
- tool traffic-generator - tool traffic-generator
- user - user
- user aaa - user aaa
- user group - user group
- user settings - user settings
# END PATH LIST # END PATH LIST
unfiltered: unfiltered:
description: description:
@ -317,10 +316,9 @@ seealso:
- module: community.routeros.api_facts - module: community.routeros.api_facts
- module: community.routeros.api_find_and_modify - module: community.routeros.api_find_and_modify
- module: community.routeros.api_modify - module: community.routeros.api_modify
''' """
EXAMPLES = ''' EXAMPLES = r"""
---
- name: Get IP addresses - name: Get IP addresses
community.routeros.api_info: community.routeros.api_info:
hostname: "{{ hostname }}" hostname: "{{ hostname }}"
@ -344,26 +342,25 @@ EXAMPLES = '''
- name: Print data for IP addresses - name: Print data for IP addresses
ansible.builtin.debug: ansible.builtin.debug:
var: ip_addresses.result var: ip_addresses.result
''' """
RETURN = ''' RETURN = r"""
---
result: result:
description: A list of all elements for the current path. description: A list of all elements for the current path.
sample: sample:
- '.id': '*1' - '.id': '*1'
actual-interface: bridge actual-interface: bridge
address: "192.168.88.1/24" address: "192.168.88.1/24"
comment: defconf comment: defconf
disabled: false disabled: false
dynamic: false dynamic: false
interface: bridge interface: bridge
invalid: false invalid: false
network: 192.168.88.0 network: 192.168.88.0
type: list type: list
elements: dict elements: dict
returned: always returned: always
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_native from ansible.module_utils.common.text.converters import to_native

557
plugins/modules/api_modify.py
View file

@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: api_modify module: api_modify
author: author:
- "Felix Fontein (@felixfontein)" - "Felix Fontein (@felixfontein)"
@ -17,17 +16,17 @@ short_description: Modify data at paths with API
version_added: 2.2.0 version_added: 2.2.0
description: description:
- Allows to modify information for a path using the API. - Allows to modify information for a path using the API.
- Use the M(community.routeros.api_find_and_modify) module to modify one or multiple entries in a controlled way - Use the M(community.routeros.api_find_and_modify) module to modify one or multiple entries in a controlled way depending
depending on some search conditions. on some search conditions.
- To make a backup of a path that can be restored with this module, use the M(community.routeros.api_info) module. - To make a backup of a path that can be restored with this module, use the M(community.routeros.api_info) module.
- The module ignores dynamic and builtin entries. - The module ignores dynamic and builtin entries.
- B(Note) that this module is still heavily in development, and only supports B(some) paths. - B(Note) that this module is still heavily in development, and only supports B(some) paths. If you want to support new
If you want to support new paths, or think you found problems with existing paths, please first paths, or think you found problems with existing paths, please first L(create an issue in the community.routeros Issue
L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/). Tracker,https://github.com/ansible-collections/community.routeros/issues/).
notes: notes:
- If write-only fields are present in the path, the module is B(not idempotent) in a strict sense, - If write-only fields are present in the path, the module is B(not idempotent) in a strict sense, since it is not able
since it is not able to verify the current value of these fields. The behavior the module should to verify the current value of these fields. The behavior the module should assume can be controlled with the O(handle_write_only)
assume can be controlled with the O(handle_write_only) option. option.
requirements: requirements:
- Needs L(ordereddict,https://pypi.org/project/ordereddict) for Python 2.6 - Needs L(ordereddict,https://pypi.org/project/ordereddict) for Python 2.6
extends_documentation_fragment: extends_documentation_fragment:
@ -47,230 +46,231 @@ options:
path: path:
description: description:
- Path to query. - Path to query.
- An example value is V(ip address). This is equivalent to running modification commands in C(/ip address) in the RouterOS CLI. - An example value is V(ip address). This is equivalent to running modification commands in C(/ip address) in the RouterOS
CLI.
required: true required: true
type: str type: str
choices: choices:
# BEGIN PATH LIST # BEGIN PATH LIST
- caps-man aaa - caps-man aaa
- caps-man access-list - caps-man access-list
- caps-man channel - caps-man channel
- caps-man configuration - caps-man configuration
- caps-man datapath - caps-man datapath
- caps-man manager - caps-man manager
- caps-man manager interface - caps-man manager interface
- caps-man provisioning - caps-man provisioning
- caps-man security - caps-man security
- certificate settings - certificate settings
- interface bonding - interface bonding
- interface bridge - interface bridge
- interface bridge mlag - interface bridge mlag
- interface bridge port - interface bridge port
- interface bridge port-controller - interface bridge port-controller
- interface bridge port-extender - interface bridge port-extender
- interface bridge settings - interface bridge settings
- interface bridge vlan - interface bridge vlan
- interface detect-internet - interface detect-internet
- interface eoip - interface eoip
- interface ethernet - interface ethernet
- interface ethernet poe - interface ethernet poe
- interface ethernet switch - interface ethernet switch
- interface ethernet switch port - interface ethernet switch port
- interface gre - interface gre
- interface gre6 - interface gre6
- interface l2tp-client - interface l2tp-client
- interface l2tp-server server - interface l2tp-server server
- interface list - interface list
- interface list member - interface list member
- interface ovpn-client - interface ovpn-client
- interface ovpn-server server - interface ovpn-server server
- interface ppp-client - interface ppp-client
- interface pppoe-client - interface pppoe-client
- interface pppoe-server server - interface pppoe-server server
- interface pptp-server server - interface pptp-server server
- interface sstp-server server - interface sstp-server server
- interface vlan - interface vlan
- interface vrrp - interface vrrp
- interface wifi - interface wifi
- interface wifi aaa - interface wifi aaa
- interface wifi access-list - interface wifi access-list
- interface wifi cap - interface wifi cap
- interface wifi capsman - interface wifi capsman
- interface wifi channel - interface wifi channel
- interface wifi configuration - interface wifi configuration
- interface wifi datapath - interface wifi datapath
- interface wifi interworking - interface wifi interworking
- interface wifi provisioning - interface wifi provisioning
- interface wifi security - interface wifi security
- interface wifi steering - interface wifi steering
- interface wifiwave2 - interface wifiwave2
- interface wifiwave2 aaa - interface wifiwave2 aaa
- interface wifiwave2 access-list - interface wifiwave2 access-list
- interface wifiwave2 cap - interface wifiwave2 cap
- interface wifiwave2 capsman - interface wifiwave2 capsman
- interface wifiwave2 channel - interface wifiwave2 channel
- interface wifiwave2 configuration - interface wifiwave2 configuration
- interface wifiwave2 datapath - interface wifiwave2 datapath
- interface wifiwave2 interworking - interface wifiwave2 interworking
- interface wifiwave2 provisioning - interface wifiwave2 provisioning
- interface wifiwave2 security - interface wifiwave2 security
- interface wifiwave2 steering - interface wifiwave2 steering
- interface wireguard - interface wireguard
- interface wireguard peers - interface wireguard peers
- interface wireless - interface wireless
- interface wireless align - interface wireless align
- interface wireless cap - interface wireless cap
- interface wireless security-profiles - interface wireless security-profiles
- interface wireless sniffer - interface wireless sniffer
- interface wireless snooper - interface wireless snooper
- iot modbus - iot modbus
- ip accounting - ip accounting
- ip accounting web-access - ip accounting web-access
- ip address - ip address
- ip arp - ip arp
- ip cloud - ip cloud
- ip cloud advanced - ip cloud advanced
- ip dhcp-client - ip dhcp-client
- ip dhcp-client option - ip dhcp-client option
- ip dhcp-relay - ip dhcp-relay
- ip dhcp-server - ip dhcp-server
- ip dhcp-server config - ip dhcp-server config
- ip dhcp-server lease - ip dhcp-server lease
- ip dhcp-server matcher - ip dhcp-server matcher
- ip dhcp-server network - ip dhcp-server network
- ip dhcp-server option - ip dhcp-server option
- ip dhcp-server option sets - ip dhcp-server option sets
- ip dns - ip dns
- ip dns adlist - ip dns adlist
- ip dns static - ip dns static
- ip firewall address-list - ip firewall address-list
- ip firewall connection tracking - ip firewall connection tracking
- ip firewall filter - ip firewall filter
- ip firewall layer7-protocol - ip firewall layer7-protocol
- ip firewall mangle - ip firewall mangle
- ip firewall nat - ip firewall nat
- ip firewall raw - ip firewall raw
- ip firewall service-port - ip firewall service-port
- ip hotspot service-port - ip hotspot service-port
- ip ipsec identity - ip ipsec identity
- ip ipsec peer - ip ipsec peer
- ip ipsec policy - ip ipsec policy
- ip ipsec profile - ip ipsec profile
- ip ipsec proposal - ip ipsec proposal
- ip ipsec settings - ip ipsec settings
- ip neighbor discovery-settings - ip neighbor discovery-settings
- ip pool - ip pool
- ip proxy - ip proxy
- ip route - ip route
- ip route rule - ip route rule
- ip route vrf - ip route vrf
- ip service - ip service
- ip settings - ip settings
- ip smb - ip smb
- ip socks - ip socks
- ip ssh - ip ssh
- ip tftp settings - ip tftp settings
- ip traffic-flow - ip traffic-flow
- ip traffic-flow ipfix - ip traffic-flow ipfix
- ip traffic-flow target - ip traffic-flow target
- ip upnp - ip upnp
- ip upnp interfaces - ip upnp interfaces
- ip vrf - ip vrf
- ipv6 address - ipv6 address
- ipv6 dhcp-client - ipv6 dhcp-client
- ipv6 dhcp-server - ipv6 dhcp-server
- ipv6 dhcp-server option - ipv6 dhcp-server option
- ipv6 firewall address-list - ipv6 firewall address-list
- ipv6 firewall filter - ipv6 firewall filter
- ipv6 firewall mangle - ipv6 firewall mangle
- ipv6 firewall nat - ipv6 firewall nat
- ipv6 firewall raw - ipv6 firewall raw
- ipv6 nd - ipv6 nd
- ipv6 nd prefix - ipv6 nd prefix
- ipv6 nd prefix default - ipv6 nd prefix default
- ipv6 route - ipv6 route
- ipv6 settings - ipv6 settings
- mpls - mpls
- mpls interface - mpls interface
- mpls ldp - mpls ldp
- mpls ldp accept-filter - mpls ldp accept-filter
- mpls ldp advertise-filter - mpls ldp advertise-filter
- mpls ldp interface - mpls ldp interface
- port firmware - port firmware
- port remote-access - port remote-access
- ppp aaa - ppp aaa
- ppp profile - ppp profile
- ppp secret - ppp secret
- queue interface - queue interface
- queue simple - queue simple
- queue tree - queue tree
- queue type - queue type
- radius - radius
- radius incoming - radius incoming
- routing bgp aggregate - routing bgp aggregate
- routing bgp connection - routing bgp connection
- routing bgp instance - routing bgp instance
- routing bgp network - routing bgp network
- routing bgp peer - routing bgp peer
- routing bgp template - routing bgp template
- routing filter - routing filter
- routing filter community-list - routing filter community-list
- routing filter num-list - routing filter num-list
- routing filter rule - routing filter rule
- routing filter select-rule - routing filter select-rule
- routing id - routing id
- routing igmp-proxy - routing igmp-proxy
- routing igmp-proxy interface - routing igmp-proxy interface
- routing mme - routing mme
- routing ospf area - routing ospf area
- routing ospf area range - routing ospf area range
- routing ospf instance - routing ospf instance
- routing ospf interface-template - routing ospf interface-template
- routing ospf static-neighbor - routing ospf static-neighbor
- routing pimsm instance - routing pimsm instance
- routing pimsm interface-template - routing pimsm interface-template
- routing rip - routing rip
- routing ripng - routing ripng
- routing rule - routing rule
- routing table - routing table
- snmp - snmp
- snmp community - snmp community
- system clock - system clock
- system clock manual - system clock manual
- system health settings - system health settings
- system identity - system identity
- system leds settings - system leds settings
- system logging - system logging
- system logging action - system logging action
- system note - system note
- system ntp client - system ntp client
- system ntp client servers - system ntp client servers
- system ntp server - system ntp server
- system package update - system package update
- system resource irq rps - system resource irq rps
- system routerboard settings - system routerboard settings
- system scheduler - system scheduler
- system script - system script
- system upgrade mirror - system upgrade mirror
- system ups - system ups
- system watchdog - system watchdog
- tool bandwidth-server - tool bandwidth-server
- tool e-mail - tool e-mail
- tool graphing - tool graphing
- tool graphing interface - tool graphing interface
- tool graphing resource - tool graphing resource
- tool mac-server - tool mac-server
- tool mac-server mac-winbox - tool mac-server mac-winbox
- tool mac-server ping - tool mac-server ping
- tool netwatch - tool netwatch
- tool romon - tool romon
- tool sms - tool sms
- tool sniffer - tool sniffer
- tool traffic-generator - tool traffic-generator
- user - user
- user aaa - user aaa
- user group - user group
- user settings - user settings
# END PATH LIST # END PATH LIST
data: data:
description: description:
@ -298,12 +298,12 @@ options:
default: ignore default: ignore
handle_entries_content: handle_entries_content:
description: description:
- For a single entry in O(data), this describes how to handle fields that are not mentioned - For a single entry in O(data), this describes how to handle fields that are not mentioned in that entry, but appear
in that entry, but appear in the actual config. in the actual config.
- If V(ignore), they are not modified. - If V(ignore), they are not modified.
- If V(remove), they are removed. If at least one cannot be removed, the module will fail. - If V(remove), they are removed. If at least one cannot be removed, the module will fail.
- If V(remove_as_much_as_possible), all that can be removed will be removed. The ones that - If V(remove_as_much_as_possible), all that can be removed will be removed. The ones that cannot be removed will be
cannot be removed will be kept. kept.
- Note that V(remove) and V(remove_as_much_as_possible) do not apply to write-only fields. - Note that V(remove) and V(remove_as_much_as_possible) do not apply to write-only fields.
type: str type: str
choices: choices:
@ -315,8 +315,8 @@ options:
description: description:
- How to handle values passed in for read-only fields. - How to handle values passed in for read-only fields.
- If V(ignore), they are not passed to the API. - If V(ignore), they are not passed to the API.
- If V(validate), the values are not passed for creation, and for updating they are compared to the value returned for the object. - If V(validate), the values are not passed for creation, and for updating they are compared to the value returned for
If they differ, the module fails. the object. If they differ, the module fails.
- If V(error), the module will fail if read-only fields are provided. - If V(error), the module will fail if read-only fields are provided.
type: str type: str
choices: choices:
@ -329,9 +329,8 @@ options:
description: description:
- How to handle values passed in for write-only fields. - How to handle values passed in for write-only fields.
- If V(create_only), they are passed on creation, and ignored for updating. - If V(create_only), they are passed on creation, and ignored for updating.
- If V(always_update), they are always passed to the API. This means that if such a value is present, - If V(always_update), they are always passed to the API. This means that if such a value is present, the module will
the module will always result in C(changed) since there is no way to validate whether the value always result in C(changed) since there is no way to validate whether the value actually changed.
actually changed.
- If V(error), the module will fail if write-only fields are provided. - If V(error), the module will fail if write-only fields are provided.
type: str type: str
choices: choices:
@ -343,21 +342,18 @@ options:
restrict: restrict:
description: description:
- Restrict operation to entries matching the following criteria. - Restrict operation to entries matching the following criteria.
- This can be useful together with O(handle_absent_entries=remove) to operate on a subset of - This can be useful together with O(handle_absent_entries=remove) to operate on a subset of the values.
the values. - For example, for O(path=ip firewall filter), you can set O(restrict[].field=chain) and O(restrict[].values=input)
- For example, for O(path=ip firewall filter), you can set O(restrict[].field=chain) and to restrict operation to the input chain, and ignore the forward and output chains.
O(restrict[].values=input) to restrict operation to the input chain, and ignore the
forward and output chains.
version_added: 2.18.0 version_added: 2.18.0
seealso: seealso:
- module: community.routeros.api - module: community.routeros.api
- module: community.routeros.api_facts - module: community.routeros.api_facts
- module: community.routeros.api_find_and_modify - module: community.routeros.api_find_and_modify
- module: community.routeros.api_info - module: community.routeros.api_info
''' """
EXAMPLES = ''' EXAMPLES = r"""
---
- name: Setup DHCP server networks - name: Setup DHCP server networks
# Ensures that we have exactly two DHCP server networks (in the specified order) # Ensures that we have exactly two DHCP server networks (in the specified order)
community.routeros.api_modify: community.routeros.api_modify:
@ -411,43 +407,42 @@ EXAMPLES = '''
data: data:
- action: drop - action: drop
chain: input chain: input
''' """
RETURN = ''' RETURN = r"""
---
old_data: old_data:
description: description:
- A list of all elements for the current path before a change was made. - A list of all elements for the current path before a change was made.
sample: sample:
- '.id': '*1' - '.id': '*1'
actual-interface: bridge actual-interface: bridge
address: "192.168.88.1/24" address: "192.168.88.1/24"
comment: defconf comment: defconf
disabled: false disabled: false
dynamic: false dynamic: false
interface: bridge interface: bridge
invalid: false invalid: false
network: 192.168.88.0 network: 192.168.88.0
type: list type: list
elements: dict elements: dict
returned: always returned: always
new_data: new_data:
description: description:
- A list of all elements for the current path after a change was made. - A list of all elements for the current path after a change was made.
sample: sample:
- '.id': '*1' - '.id': '*1'
actual-interface: bridge actual-interface: bridge
address: "192.168.1.1/24" address: "192.168.1.1/24"
comment: awesome comment: awesome
disabled: false disabled: false
dynamic: false dynamic: false
interface: bridge interface: bridge
invalid: false invalid: false
network: 192.168.1.0 network: 192.168.1.0
type: list type: list
elements: dict elements: dict
returned: always returned: always
''' """
from collections import defaultdict from collections import defaultdict

71
plugins/modules/command.py
View file

@ -7,27 +7,23 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: command module: command
author: "Egor Zaitsev (@heuels)" author: "Egor Zaitsev (@heuels)"
short_description: Run commands on remote devices running MikroTik RouterOS short_description: Run commands on remote devices running MikroTik RouterOS
description: description:
- Sends arbitrary commands to an RouterOS node and returns the results - Sends arbitrary commands to an RouterOS node and returns the results read from the device. This module includes an argument
read from the device. This module includes an that will cause the module to wait for a specific condition before returning or timing out if the condition is not met.
argument that will cause the module to wait for a specific condition - The module always indicates a (changed) status. You can use R(the changed_when task property,override_the_changed_result)
before returning or timing out if the condition is not met. to determine whether a command task actually resulted in a change or not.
- The module always indicates a (changed) status. You can use
R(the changed_when task property,override_the_changed_result) to determine
whether a command task actually resulted in a change or not.
extends_documentation_fragment: extends_documentation_fragment:
- community.routeros.attributes - community.routeros.attributes
attributes: attributes:
check_mode: check_mode:
support: none support: none
details: details:
- Before community.routeros 3.0.0, the module claimed to support check mode. - Before community.routeros 3.0.0, the module claimed to support check mode. It simply executed the command in check
It simply executed the command in check mode. mode.
diff_mode: diff_mode:
support: none support: none
platform: platform:
@ -36,58 +32,47 @@ attributes:
options: options:
commands: commands:
description: description:
- List of commands to send to the remote RouterOS device over the - List of commands to send to the remote RouterOS device over the configured provider. The resulting output from the
configured provider. The resulting output from the command command is returned. If the O(wait_for) argument is provided, the module is not returned until the condition is satisfied
is returned. If the O(wait_for) argument is provided, the or the number of retries has expired.
module is not returned until the condition is satisfied or
the number of retries has expired.
required: true required: true
type: list type: list
elements: str elements: str
wait_for: wait_for:
description: description:
- List of conditions to evaluate against the output of the - List of conditions to evaluate against the output of the command. The task will wait for each condition to be true
command. The task will wait for each condition to be true before moving forward. If the conditional is not true within the configured number of retries, the task fails. See
before moving forward. If the conditional is not true examples.
within the configured number of retries, the task fails.
See examples.
type: list type: list
elements: str elements: str
match: match:
description: description:
- The O(match) argument is used in conjunction with the - The O(match) argument is used in conjunction with the O(wait_for) argument to specify the match policy. Valid values
O(wait_for) argument to specify the match policy. Valid are V(all) or V(any). If the value is set to V(all) then all conditionals in the wait_for must be satisfied. If the
values are V(all) or V(any). If the value is set to V(all) value is set to V(any) then only one of the values must be satisfied.
then all conditionals in the wait_for must be satisfied. If
the value is set to V(any) then only one of the values must be
satisfied.
default: all default: all
choices: ['any', 'all'] choices: ['any', 'all']
type: str type: str
retries: retries:
description: description:
- Specifies the number of retries a command should by tried - Specifies the number of retries a command should by tried before it is considered failed. The command is run on the
before it is considered failed. The command is run on the target device every retry and evaluated against the O(wait_for) conditions.
target device every retry and evaluated against the
O(wait_for) conditions.
default: 10 default: 10
type: int type: int
interval: interval:
description: description:
- Configures the interval in seconds to wait between retries - Configures the interval in seconds to wait between retries of the command. If the command does not pass the specified
of the command. If the command does not pass the specified conditions, the interval indicates how long to wait before trying the command again.
conditions, the interval indicates how long to wait before
trying the command again.
default: 1 default: 1
type: int type: int
seealso: seealso:
- ref: ansible_collections.community.routeros.docsite.ssh-guide - ref: ansible_collections.community.routeros.docsite.ssh-guide
description: How to connect to RouterOS devices with SSH description: How to connect to RouterOS devices with SSH.
- ref: ansible_collections.community.routeros.docsite.quoting - ref: ansible_collections.community.routeros.docsite.quoting
description: How to quote and unquote commands and arguments description: How to quote and unquote commands and arguments.
''' """
EXAMPLES = """ EXAMPLES = r"""
- name: Run command on remote devices - name: Run command on remote devices
community.routeros.command: community.routeros.command:
commands: /system routerboard print commands: /system routerboard print
@ -113,19 +98,19 @@ EXAMPLES = """
- result[1] contains ether1 - result[1] contains ether1
""" """
RETURN = """ RETURN = r"""
stdout: stdout:
description: The set of responses from the commands description: The set of responses from the commands.
returned: always apart from low level errors (such as action plugin) returned: always apart from low level errors (such as action plugin)
type: list type: list
sample: ['...', '...'] sample: ['...', '...']
stdout_lines: stdout_lines:
description: The value of stdout split into a list description: The value of stdout split into a list.
returned: always apart from low level errors (such as action plugin) returned: always apart from low level errors (such as action plugin)
type: list type: list
sample: [['...', '...'], ['...'], ['...']] sample: [['...', '...'], ['...'], ['...']]
failed_conditions: failed_conditions:
description: The list of conditionals that have failed description: The list of conditionals that have failed.
returned: failed returned: failed
type: list type: list
sample: ['...', '...'] sample: ['...', '...']

33
plugins/modules/facts.py
View file

@ -7,16 +7,13 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: facts module: facts
author: "Egor Zaitsev (@heuels)" author: "Egor Zaitsev (@heuels)"
short_description: Collect facts from remote devices running MikroTik RouterOS short_description: Collect facts from remote devices running MikroTik RouterOS
description: description:
- Collects a base set of device facts from a remote device that - Collects a base set of device facts from a remote device that is running RouterOS. This module prepends all of the base
is running RouterOS. This module prepends all of the network fact keys with C(ansible_net_<fact>). The facts module will always collect a base set of facts from the device
base network fact keys with C(ansible_net_<fact>). The facts
module will always collect a base set of facts from the device
and can enable or disable collection of additional facts. and can enable or disable collection of additional facts.
extends_documentation_fragment: extends_documentation_fragment:
- community.routeros.attributes - community.routeros.attributes
@ -29,12 +26,10 @@ attributes:
options: options:
gather_subset: gather_subset:
description: description:
- When supplied, this argument will restrict the facts collected - When supplied, this argument will restrict the facts collected to a given subset. Possible values for this argument
to a given subset. Possible values for this argument include include V(all), V(hardware), V(config), V(interfaces), and V(routing).
V(all), V(hardware), V(config), V(interfaces), and V(routing). - Can specify a list of values to include a larger subset. Values can also be used with an initial V(!) to specify that
- Can specify a list of values to include a larger subset. a specific subset should not be collected.
Values can also be used with an initial V(!) to specify that a
specific subset should not be collected.
required: false required: false
default: default:
- '!config' - '!config'
@ -42,10 +37,10 @@ options:
elements: str elements: str
seealso: seealso:
- ref: ansible_collections.community.routeros.docsite.ssh-guide - ref: ansible_collections.community.routeros.docsite.ssh-guide
description: How to connect to RouterOS devices with SSH description: How to connect to RouterOS devices with SSH.
''' """
EXAMPLES = """ EXAMPLES = r"""
- name: Collect all facts from the device - name: Collect all facts from the device
community.routeros.facts: community.routeros.facts:
gather_subset: all gather_subset: all
@ -61,7 +56,7 @@ EXAMPLES = """
- "!hardware" - "!hardware"
""" """
RETURN = """ RETURN = r"""
ansible_facts: ansible_facts:
description: "Dictionary of IP geolocation facts for a host's IP address." description: "Dictionary of IP geolocation facts for a host's IP address."
returned: always returned: always
@ -129,9 +124,9 @@ ansible_facts:
ansible_net_config_nonverbose: ansible_net_config_nonverbose:
description: description:
- The current active config from the device in minimal form. - The current active config from the device in minimal form.
- This value is idempotent in the sense that if the facts module is run twice and the device's config - This value is idempotent in the sense that if the facts module is run twice and the device's config was not changed
was not changed between the runs, the value is identical. This is achieved by running C(/export) between the runs, the value is identical. This is achieved by running C(/export) and stripping the timestamp from
and stripping the timestamp from the comment in the first line. the comment in the first line.
returned: O(gather_subset) contains V(config) returned: O(gather_subset) contains V(config)
type: str type: str
version_added: 1.2.0 version_added: 1.2.0

2
update-docs.py
View file

@ -42,7 +42,7 @@ def main():
path_choices = sorted([join_path(path) for path, path_info in PATHS.items() if path_info.fully_understood]) path_choices = sorted([join_path(path) for path, path_info in PATHS.items() if path_info.fully_understood])
for file in MODULES: for file in MODULES:
update_file(file, ' # BEGIN PATH LIST', ' # END PATH LIST', ' - {choice}', path_choices) update_file(file, ' # BEGIN PATH LIST', ' # END PATH LIST', ' - {choice}', path_choices)
if __name__ == '__main__': if __name__ == '__main__':