mirror of
https://github.com/ansible-collections/community.routeros.git
synced 2025-06-24 10:48:49 +02:00
Reformat documentation with 'andebox yaml-doc' (#335)
* Reformat documentation with 'andebox yaml-doc'. * Revert unwanted changes.
This commit is contained in:
Felix Fontein
GitHub
parent
77de6d90bf
commit
539119c57d
11 changed files with 717 additions and 758 deletions
|
|
@ -5,15 +5,14 @@
|
|||
from __future__ import (absolute_import, division, print_function)
|
||||
__metaclass__ = type
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
author: "Egor Zaitsev (@heuels)"
|
||||
name: routeros
|
||||
short_description: Use routeros cliconf to run command on MikroTik RouterOS platform
|
||||
description:
|
||||
- This routeros plugin provides low level abstraction apis for
|
||||
sending and receiving CLI commands from MikroTik RouterOS network devices.
|
||||
'''
|
||||
- This routeros plugin provides low level abstraction apis for sending and receiving CLI commands from MikroTik RouterOS
|
||||
network devices.
|
||||
"""
|
||||
|
||||
import re
|
||||
import json
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ __metaclass__ = type
|
|||
|
||||
class ModuleDocFragment(object):
|
||||
|
||||
DOCUMENTATION = r'''
|
||||
DOCUMENTATION = r"""
|
||||
options:
|
||||
hostname:
|
||||
description:
|
||||
|
|
@ -50,10 +50,9 @@ options:
|
|||
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).
|
||||
- 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
|
||||
default: false
|
||||
version_added: 2.4.0
|
||||
|
|
@ -61,10 +60,9 @@ options:
|
|||
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.
|
||||
- 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
|
||||
default: true
|
||||
version_added: 1.2.0
|
||||
|
|
@ -93,10 +91,10 @@ requirements:
|
|||
- Python >= 3.6 (for librouteros)
|
||||
seealso:
|
||||
- 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:
|
||||
restrict:
|
||||
type: list
|
||||
|
|
@ -115,24 +113,21 @@ options:
|
|||
values:
|
||||
description:
|
||||
- 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 value returned by the API to the integer V(0),
|
||||
then this will not match. If you are not sure, better include both variants:
|
||||
both the string and the integer.
|
||||
- 'Note that the types of the values are important. If you provide a string V("0"), and librouteros converts the
|
||||
value returned by the API to the integer V(0), then this will not match. If you are not sure, better include both
|
||||
variants: both the string and the integer.'
|
||||
type: list
|
||||
elements: raw
|
||||
regex:
|
||||
description:
|
||||
- A regular expression matching values of the field to limit to.
|
||||
- Note that all values will be converted to strings before matching.
|
||||
- It is not possible to match disabled values with regular expressions.
|
||||
Set O(restrict[].match_disabled=true) if you also want to match disabled values.
|
||||
- It is not possible to match disabled values with regular expressions. Set O(restrict[].match_disabled=true) if
|
||||
you also want to match disabled values.
|
||||
type: str
|
||||
invert:
|
||||
description:
|
||||
- Invert the condition. This affects O(restrict[].match_disabled), O(restrict[].values),
|
||||
and O(restrict[].regex).
|
||||
- Invert the condition. This affects O(restrict[].match_disabled), O(restrict[].values), and O(restrict[].regex).
|
||||
type: bool
|
||||
default: false
|
||||
'''
|
||||
"""
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ __metaclass__ = type
|
|||
class ModuleDocFragment(object):
|
||||
|
||||
# Standard documentation fragment
|
||||
DOCUMENTATION = r'''
|
||||
DOCUMENTATION = r"""
|
||||
options: {}
|
||||
attributes:
|
||||
check_mode:
|
||||
|
|
@ -21,7 +21,7 @@ attributes:
|
|||
platform:
|
||||
description: Target OS/families that can be operated against.
|
||||
support: N/A
|
||||
'''
|
||||
"""
|
||||
|
||||
# Should be used together with the standard fragment
|
||||
INFO_MODULE = r'''
|
||||
|
|
@ -47,7 +47,7 @@ attributes:
|
|||
- community.routeros.api
|
||||
'''
|
||||
|
||||
CONN = r'''
|
||||
CONN = r"""
|
||||
options: {}
|
||||
attributes:
|
||||
become:
|
||||
|
|
@ -56,14 +56,14 @@ attributes:
|
|||
description: Uses the target's configured connection information to execute code on it.
|
||||
delegation:
|
||||
description: Can be used in conjunction with C(delegate_to) and related keywords.
|
||||
'''
|
||||
"""
|
||||
|
||||
FACTS = r'''
|
||||
FACTS = r"""
|
||||
options: {}
|
||||
attributes:
|
||||
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
|
||||
FACTS_MODULE = r'''
|
||||
|
|
@ -81,18 +81,18 @@ attributes:
|
|||
support: full
|
||||
'''
|
||||
|
||||
FILES = r'''
|
||||
FILES = r"""
|
||||
options: {}
|
||||
attributes:
|
||||
safe_file_operations:
|
||||
description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
|
||||
'''
|
||||
"""
|
||||
|
||||
FLOW = r'''
|
||||
FLOW = r"""
|
||||
options: {}
|
||||
attributes:
|
||||
action:
|
||||
description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
|
||||
async:
|
||||
description: Supports being used with the C(async) keyword.
|
||||
'''
|
||||
"""
|
||||
|
|
|
|||
|
|
@ -8,8 +8,7 @@
|
|||
from __future__ import (absolute_import, division, print_function)
|
||||
__metaclass__ = type
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: api
|
||||
author: "Nikolay Dachev (@NikolayDachev)"
|
||||
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.
|
||||
notes:
|
||||
- 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
|
||||
for more specific modifications, and the M(community.routeros.api_info) module for a more controlled
|
||||
way of returning all entries for a path.
|
||||
- Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules for more specific modifications,
|
||||
and the M(community.routeros.api_info) module for a more controlled way of returning all entries for a path.
|
||||
extends_documentation_fragment:
|
||||
- community.routeros.api
|
||||
- community.routeros.attributes
|
||||
|
|
@ -68,11 +66,12 @@ options:
|
|||
- 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.
|
||||
- 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
|
||||
extended_query:
|
||||
|
|
@ -91,7 +90,8 @@ options:
|
|||
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.
|
||||
- The conditions here must all match. An O(extended_query.where[].or) condition needs at least one of its conditions
|
||||
to match.
|
||||
type: list
|
||||
elements: dict
|
||||
suboptions:
|
||||
|
|
@ -105,7 +105,8 @@ options:
|
|||
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.
|
||||
- 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
|
||||
|
|
@ -133,7 +134,8 @@ options:
|
|||
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.
|
||||
- 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
|
||||
choices: ["==", "!=", ">", "<", "in", "eq", "not", "more", "less"]
|
||||
required: true
|
||||
|
|
@ -150,14 +152,14 @@ options:
|
|||
type: str
|
||||
seealso:
|
||||
- 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_find_and_modify
|
||||
- module: community.routeros.api_info
|
||||
- module: community.routeros.api_modify
|
||||
'''
|
||||
"""
|
||||
|
||||
EXAMPLES = '''
|
||||
EXAMPLES = r"""
|
||||
- name: Get example - ip address print
|
||||
community.routeros.api:
|
||||
hostname: "{{ hostname }}"
|
||||
|
|
@ -255,10 +257,9 @@ EXAMPLES = '''
|
|||
- name: Dump "Arbitrary command example" output
|
||||
ansible.builtin.debug:
|
||||
msg: '{{ arbitraryout }}'
|
||||
'''
|
||||
"""
|
||||
|
||||
RETURN = '''
|
||||
---
|
||||
RETURN = r"""
|
||||
message:
|
||||
description: All outputs are in list with dictionary elements returned from RouterOS api.
|
||||
sample:
|
||||
|
|
@ -266,7 +267,7 @@ message:
|
|||
- address: 2.3.4.5
|
||||
type: list
|
||||
returned: always
|
||||
'''
|
||||
"""
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
from ansible.module_utils.common.text.converters import to_native
|
||||
|
|
|
|||
|
|
@ -9,8 +9,7 @@
|
|||
from __future__ import (absolute_import, division, print_function)
|
||||
__metaclass__ = type
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: api_facts
|
||||
author:
|
||||
- "Egor Zaitsev (@heuels)"
|
||||
|
|
@ -19,13 +18,11 @@ author:
|
|||
version_added: 2.1.0
|
||||
short_description: Collect facts from remote devices running MikroTik RouterOS using the API
|
||||
description:
|
||||
- Collects a base set of device facts from a remote device that
|
||||
is running RouterOS. This module prepends all of the
|
||||
base network fact keys with C(ansible_net_<fact>). The facts
|
||||
module will always collect a base set of facts from the device
|
||||
- Collects a base set of device facts from a remote device that is running RouterOS. This module prepends all of the 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.
|
||||
- As opposed to the M(community.routeros.facts) module, it uses the
|
||||
RouterOS API, similar to the M(community.routeros.api) module.
|
||||
- As opposed to the M(community.routeros.facts) module, it uses the RouterOS API, similar to the M(community.routeros.api)
|
||||
module.
|
||||
extends_documentation_fragment:
|
||||
- community.routeros.api
|
||||
- community.routeros.attributes
|
||||
|
|
@ -39,12 +36,10 @@ attributes:
|
|||
options:
|
||||
gather_subset:
|
||||
description:
|
||||
- When supplied, this argument will restrict the facts collected
|
||||
to a given subset. Possible values for this argument include
|
||||
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 a
|
||||
specific subset should not be collected.
|
||||
- When supplied, this argument will restrict the facts collected to a given subset. Possible values for this argument
|
||||
include 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
|
||||
a specific subset should not be collected.
|
||||
required: false
|
||||
default:
|
||||
- all
|
||||
|
|
@ -56,9 +51,9 @@ seealso:
|
|||
- module: community.routeros.api_find_and_modify
|
||||
- module: community.routeros.api_info
|
||||
- module: community.routeros.api_modify
|
||||
'''
|
||||
"""
|
||||
|
||||
EXAMPLES = """
|
||||
EXAMPLES = r"""
|
||||
- name: Collect all facts from the device
|
||||
community.routeros.api_facts:
|
||||
hostname: 192.168.88.1
|
||||
|
|
@ -75,7 +70,7 @@ EXAMPLES = """
|
|||
- "!hardware"
|
||||
"""
|
||||
|
||||
RETURN = """
|
||||
RETURN = r"""
|
||||
ansible_facts:
|
||||
description: "Dictionary of IP geolocation facts for a host's IP address."
|
||||
returned: always
|
||||
|
|
|
|||
|
|
@ -8,8 +8,7 @@
|
|||
from __future__ import (absolute_import, division, print_function)
|
||||
__metaclass__ = type
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: api_find_and_modify
|
||||
author:
|
||||
- "Felix Fontein (@felixfontein)"
|
||||
|
|
@ -17,13 +16,13 @@ short_description: Find and modify information using the API
|
|||
version_added: 2.1.0
|
||||
description:
|
||||
- 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,
|
||||
or change multiple entries in different ways in one step.
|
||||
- Use the M(community.routeros.api_find_and_modify) module to set all entries of a path to specific values, or change multiple
|
||||
entries in different ways in one step.
|
||||
notes:
|
||||
- "If you want to change values based on their old values (like change all comments 'foo' to 'bar') and make sure that
|
||||
there are at least N such values, you can use O(require_matches_min=N) together with O(allow_no_matches=true).
|
||||
This will make 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 of the task: once the values have been changed, there should be no further match."
|
||||
- "If you want to change values based on their old values (like change all comments 'foo' to 'bar') and make sure that there
|
||||
are at least N such values, you can use O(require_matches_min=N) together with O(allow_no_matches=true). This will make
|
||||
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
|
||||
of the task: once the values have been changed, there should be no further match."
|
||||
extends_documentation_fragment:
|
||||
- community.routeros.api
|
||||
- community.routeros.attributes
|
||||
|
|
@ -79,10 +78,9 @@ seealso:
|
|||
- module: community.routeros.api_facts
|
||||
- module: community.routeros.api_modify
|
||||
- module: community.routeros.api_info
|
||||
'''
|
||||
"""
|
||||
|
||||
EXAMPLES = '''
|
||||
---
|
||||
EXAMPLES = r"""
|
||||
- name: Rename bridge from 'bridge' to 'my-bridge'
|
||||
community.routeros.api_find_and_modify:
|
||||
hostname: "{{ hostname }}"
|
||||
|
|
@ -108,10 +106,9 @@ EXAMPLES = '''
|
|||
# exactly one is configured.
|
||||
require_matches_min: 1
|
||||
require_matches_max: 1
|
||||
'''
|
||||
"""
|
||||
|
||||
RETURN = '''
|
||||
---
|
||||
RETURN = r"""
|
||||
old_data:
|
||||
description:
|
||||
- A list of all elements for the current path before a change was made.
|
||||
|
|
@ -156,7 +153,7 @@ modify__count:
|
|||
sample: 1
|
||||
type: int
|
||||
returned: success
|
||||
'''
|
||||
"""
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
from ansible.module_utils.common.text.converters import to_native
|
||||
|
|
|
|||
|
|
@ -8,8 +8,7 @@
|
|||
from __future__ import (absolute_import, division, print_function)
|
||||
__metaclass__ = type
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: api_info
|
||||
author:
|
||||
- "Felix Fontein (@felixfontein)"
|
||||
|
|
@ -18,12 +17,12 @@ version_added: 2.2.0
|
|||
description:
|
||||
- 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.
|
||||
- Entries are normalized, dynamic and builtin entries are not returned. Use the O(handle_disabled) and
|
||||
O(hide_defaults) options to control normalization, the O(include_dynamic) and O(include_builtin) options to also return
|
||||
dynamic resp. builtin 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.
|
||||
If you want to support new paths, or think you found problems with existing paths, please first
|
||||
L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/).
|
||||
- Entries are normalized, dynamic and builtin entries are not returned. Use the O(handle_disabled) and O(hide_defaults)
|
||||
options to control normalization, the O(include_dynamic) and O(include_builtin) options to also return dynamic resp. builtin
|
||||
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. If you want to support new
|
||||
paths, or think you found problems with existing paths, please first L(create an issue in the community.routeros Issue
|
||||
Tracker,https://github.com/ansible-collections/community.routeros/issues/).
|
||||
extends_documentation_fragment:
|
||||
- community.routeros.api
|
||||
- community.routeros.api.restrict
|
||||
|
|
@ -317,10 +316,9 @@ seealso:
|
|||
- module: community.routeros.api_facts
|
||||
- module: community.routeros.api_find_and_modify
|
||||
- module: community.routeros.api_modify
|
||||
'''
|
||||
"""
|
||||
|
||||
EXAMPLES = '''
|
||||
---
|
||||
EXAMPLES = r"""
|
||||
- name: Get IP addresses
|
||||
community.routeros.api_info:
|
||||
hostname: "{{ hostname }}"
|
||||
|
|
@ -344,10 +342,9 @@ EXAMPLES = '''
|
|||
- name: Print data for IP addresses
|
||||
ansible.builtin.debug:
|
||||
var: ip_addresses.result
|
||||
'''
|
||||
"""
|
||||
|
||||
RETURN = '''
|
||||
---
|
||||
RETURN = r"""
|
||||
result:
|
||||
description: A list of all elements for the current path.
|
||||
sample:
|
||||
|
|
@ -363,7 +360,7 @@ result:
|
|||
type: list
|
||||
elements: dict
|
||||
returned: always
|
||||
'''
|
||||
"""
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
from ansible.module_utils.common.text.converters import to_native
|
||||
|
|
|
|||
|
|
@ -8,8 +8,7 @@
|
|||
from __future__ import (absolute_import, division, print_function)
|
||||
__metaclass__ = type
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: api_modify
|
||||
author:
|
||||
- "Felix Fontein (@felixfontein)"
|
||||
|
|
@ -17,17 +16,17 @@ short_description: Modify data at paths with API
|
|||
version_added: 2.2.0
|
||||
description:
|
||||
- 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
|
||||
depending on some search conditions.
|
||||
- Use the M(community.routeros.api_find_and_modify) module to modify one or multiple entries in a controlled way depending
|
||||
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.
|
||||
- The module ignores dynamic and builtin entries.
|
||||
- B(Note) that this module is still heavily in development, and only supports B(some) paths.
|
||||
If you want to support new paths, or think you found problems with existing paths, please first
|
||||
L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/).
|
||||
- B(Note) that this module is still heavily in development, and only supports B(some) paths. If you want to support new
|
||||
paths, or think you found problems with existing paths, please first L(create an issue in the community.routeros Issue
|
||||
Tracker,https://github.com/ansible-collections/community.routeros/issues/).
|
||||
notes:
|
||||
- If write-only fields are present in the path, the module is B(not idempotent) in a strict sense,
|
||||
since it is not able to verify the current value of these fields. The behavior the module should
|
||||
assume can be controlled with the O(handle_write_only) option.
|
||||
- If write-only fields are present in the path, the module is B(not idempotent) in a strict sense, since it is not able
|
||||
to verify the current value of these fields. The behavior the module should assume can be controlled with the O(handle_write_only)
|
||||
option.
|
||||
requirements:
|
||||
- Needs L(ordereddict,https://pypi.org/project/ordereddict) for Python 2.6
|
||||
extends_documentation_fragment:
|
||||
|
|
@ -47,7 +46,8 @@ options:
|
|||
path:
|
||||
description:
|
||||
- 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
|
||||
type: str
|
||||
choices:
|
||||
|
|
@ -298,12 +298,12 @@ options:
|
|||
default: ignore
|
||||
handle_entries_content:
|
||||
description:
|
||||
- For a single entry in O(data), this describes how to handle fields that are not mentioned
|
||||
in that entry, but appear in the actual config.
|
||||
- For a single entry in O(data), this describes how to handle fields that are not mentioned in that entry, but appear
|
||||
in the actual config.
|
||||
- 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_as_much_as_possible), all that can be removed will be removed. The ones that
|
||||
cannot be removed will be kept.
|
||||
- If V(remove_as_much_as_possible), all that can be removed will be removed. The ones that cannot be removed will be
|
||||
kept.
|
||||
- Note that V(remove) and V(remove_as_much_as_possible) do not apply to write-only fields.
|
||||
type: str
|
||||
choices:
|
||||
|
|
@ -315,8 +315,8 @@ options:
|
|||
description:
|
||||
- How to handle values passed in for read-only fields.
|
||||
- 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 they differ, the module fails.
|
||||
- If V(validate), the values are not passed for creation, and for updating they are compared to the value returned for
|
||||
the object. If they differ, the module fails.
|
||||
- If V(error), the module will fail if read-only fields are provided.
|
||||
type: str
|
||||
choices:
|
||||
|
|
@ -329,9 +329,8 @@ options:
|
|||
description:
|
||||
- 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(always_update), they are always passed to the API. This means that if such a value is present,
|
||||
the module will always result in C(changed) since there is no way to validate whether the value
|
||||
actually changed.
|
||||
- If V(always_update), they are always passed to the API. This means that if such a value is present, the module will
|
||||
always result in C(changed) since there is no way to validate whether the value actually changed.
|
||||
- If V(error), the module will fail if write-only fields are provided.
|
||||
type: str
|
||||
choices:
|
||||
|
|
@ -343,21 +342,18 @@ options:
|
|||
restrict:
|
||||
description:
|
||||
- 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
|
||||
the values.
|
||||
- For example, for O(path=ip firewall filter), you can set O(restrict[].field=chain) and
|
||||
O(restrict[].values=input) to restrict operation to the input chain, and ignore the
|
||||
forward and output chains.
|
||||
- This can be useful together with O(handle_absent_entries=remove) to operate on a subset of the values.
|
||||
- For example, for O(path=ip firewall filter), you can set O(restrict[].field=chain) and O(restrict[].values=input)
|
||||
to restrict operation to the input chain, and ignore the forward and output chains.
|
||||
version_added: 2.18.0
|
||||
seealso:
|
||||
- module: community.routeros.api
|
||||
- module: community.routeros.api_facts
|
||||
- module: community.routeros.api_find_and_modify
|
||||
- module: community.routeros.api_info
|
||||
'''
|
||||
"""
|
||||
|
||||
EXAMPLES = '''
|
||||
---
|
||||
EXAMPLES = r"""
|
||||
- name: Setup DHCP server networks
|
||||
# Ensures that we have exactly two DHCP server networks (in the specified order)
|
||||
community.routeros.api_modify:
|
||||
|
|
@ -411,10 +407,9 @@ EXAMPLES = '''
|
|||
data:
|
||||
- action: drop
|
||||
chain: input
|
||||
'''
|
||||
"""
|
||||
|
||||
RETURN = '''
|
||||
---
|
||||
RETURN = r"""
|
||||
old_data:
|
||||
description:
|
||||
- A list of all elements for the current path before a change was made.
|
||||
|
|
@ -447,7 +442,7 @@ new_data:
|
|||
type: list
|
||||
elements: dict
|
||||
returned: always
|
||||
'''
|
||||
"""
|
||||
|
||||
from collections import defaultdict
|
||||
|
||||
|
|
|
|||
|
|
@ -7,27 +7,23 @@
|
|||
from __future__ import (absolute_import, division, print_function)
|
||||
__metaclass__ = type
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: command
|
||||
author: "Egor Zaitsev (@heuels)"
|
||||
short_description: Run commands on remote devices running MikroTik RouterOS
|
||||
description:
|
||||
- Sends arbitrary commands to an RouterOS node and returns the results
|
||||
read from the device. This module includes an
|
||||
argument that will cause the module to wait for a specific condition
|
||||
before returning or timing out if the condition is not met.
|
||||
- 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.
|
||||
- Sends arbitrary commands to an RouterOS node and returns the results read from the device. This module includes an argument
|
||||
that will cause the module to wait for a specific condition before returning or timing out if the condition is not met.
|
||||
- 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:
|
||||
- community.routeros.attributes
|
||||
attributes:
|
||||
check_mode:
|
||||
support: none
|
||||
details:
|
||||
- Before community.routeros 3.0.0, the module claimed to support check mode.
|
||||
It simply executed the command in check mode.
|
||||
- Before community.routeros 3.0.0, the module claimed to support check mode. It simply executed the command in check
|
||||
mode.
|
||||
diff_mode:
|
||||
support: none
|
||||
platform:
|
||||
|
|
@ -36,58 +32,47 @@ attributes:
|
|||
options:
|
||||
commands:
|
||||
description:
|
||||
- List of commands to send to the remote RouterOS device over the
|
||||
configured provider. The resulting output from the command
|
||||
is returned. If the O(wait_for) argument is provided, the
|
||||
module is not returned until the condition is satisfied or
|
||||
the number of retries has expired.
|
||||
- List of commands to send to the remote RouterOS device over the configured provider. The resulting output from the
|
||||
command is returned. If the O(wait_for) argument is provided, the module is not returned until the condition is satisfied
|
||||
or the number of retries has expired.
|
||||
required: true
|
||||
type: list
|
||||
elements: str
|
||||
wait_for:
|
||||
description:
|
||||
- List of conditions to evaluate against the output of the
|
||||
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 examples.
|
||||
- List of conditions to evaluate against the output of the 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
|
||||
examples.
|
||||
type: list
|
||||
elements: str
|
||||
match:
|
||||
description:
|
||||
- The O(match) argument is used in conjunction with the
|
||||
O(wait_for) argument to specify the match policy. Valid
|
||||
values 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 value is set to V(any) then only one of the values must be
|
||||
satisfied.
|
||||
- The O(match) argument is used in conjunction with the O(wait_for) argument to specify the match policy. Valid values
|
||||
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
|
||||
value is set to V(any) then only one of the values must be satisfied.
|
||||
default: all
|
||||
choices: ['any', 'all']
|
||||
type: str
|
||||
retries:
|
||||
description:
|
||||
- Specifies the number of retries a command should by tried
|
||||
before it is considered failed. The command is run on the
|
||||
target device every retry and evaluated against the
|
||||
O(wait_for) conditions.
|
||||
- Specifies the number of retries a command should by tried before it is considered failed. The command is run on the
|
||||
target device every retry and evaluated against the O(wait_for) conditions.
|
||||
default: 10
|
||||
type: int
|
||||
interval:
|
||||
description:
|
||||
- Configures the interval in seconds to wait between retries
|
||||
of the command. If the command does not pass the specified
|
||||
conditions, the interval indicates how long to wait before
|
||||
trying the command again.
|
||||
- Configures the interval in seconds to wait between retries of the command. If the command does not pass the specified
|
||||
conditions, the interval indicates how long to wait before trying the command again.
|
||||
default: 1
|
||||
type: int
|
||||
seealso:
|
||||
- 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
|
||||
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
|
||||
community.routeros.command:
|
||||
commands: /system routerboard print
|
||||
|
|
@ -113,19 +98,19 @@ EXAMPLES = """
|
|||
- result[1] contains ether1
|
||||
"""
|
||||
|
||||
RETURN = """
|
||||
RETURN = r"""
|
||||
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)
|
||||
type: list
|
||||
sample: ['...', '...']
|
||||
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)
|
||||
type: list
|
||||
sample: [['...', '...'], ['...'], ['...']]
|
||||
failed_conditions:
|
||||
description: The list of conditionals that have failed
|
||||
description: The list of conditionals that have failed.
|
||||
returned: failed
|
||||
type: list
|
||||
sample: ['...', '...']
|
||||
|
|
|
|||
|
|
@ -7,16 +7,13 @@
|
|||
from __future__ import (absolute_import, division, print_function)
|
||||
__metaclass__ = type
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: facts
|
||||
author: "Egor Zaitsev (@heuels)"
|
||||
short_description: Collect facts from remote devices running MikroTik RouterOS
|
||||
description:
|
||||
- Collects a base set of device facts from a remote device that
|
||||
is running RouterOS. This module prepends all of the
|
||||
base network fact keys with C(ansible_net_<fact>). The facts
|
||||
module will always collect a base set of facts from the device
|
||||
- Collects a base set of device facts from a remote device that is running RouterOS. This module prepends all of the 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.
|
||||
extends_documentation_fragment:
|
||||
- community.routeros.attributes
|
||||
|
|
@ -29,12 +26,10 @@ attributes:
|
|||
options:
|
||||
gather_subset:
|
||||
description:
|
||||
- When supplied, this argument will restrict the facts collected
|
||||
to a given subset. Possible values for this argument include
|
||||
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 a
|
||||
specific subset should not be collected.
|
||||
- When supplied, this argument will restrict the facts collected to a given subset. Possible values for this argument
|
||||
include 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
|
||||
a specific subset should not be collected.
|
||||
required: false
|
||||
default:
|
||||
- '!config'
|
||||
|
|
@ -42,10 +37,10 @@ options:
|
|||
elements: str
|
||||
seealso:
|
||||
- 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
|
||||
community.routeros.facts:
|
||||
gather_subset: all
|
||||
|
|
@ -61,7 +56,7 @@ EXAMPLES = """
|
|||
- "!hardware"
|
||||
"""
|
||||
|
||||
RETURN = """
|
||||
RETURN = r"""
|
||||
ansible_facts:
|
||||
description: "Dictionary of IP geolocation facts for a host's IP address."
|
||||
returned: always
|
||||
|
|
@ -129,9 +124,9 @@ ansible_facts:
|
|||
ansible_net_config_nonverbose:
|
||||
description:
|
||||
- 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
|
||||
was not changed between the runs, the value is identical. This is achieved by running C(/export)
|
||||
and stripping the timestamp from the comment in the first line.
|
||||
- This value is idempotent in the sense that if the facts module is run twice and the device's config was not changed
|
||||
between the runs, the value is identical. This is achieved by running C(/export) and stripping the timestamp from
|
||||
the comment in the first line.
|
||||
returned: O(gather_subset) contains V(config)
|
||||
type: str
|
||||
version_added: 1.2.0
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue