diff --git a/plugins/cliconf/routeros.py b/plugins/cliconf/routeros.py index 412627b8..1c3288f4 100644 --- a/plugins/cliconf/routeros.py +++ b/plugins/cliconf/routeros.py @@ -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 diff --git a/plugins/doc_fragments/api.py b/plugins/doc_fragments/api.py index b0ad9799..edef5f09 100644 --- a/plugins/doc_fragments/api.py +++ b/plugins/doc_fragments/api.py @@ -10,7 +10,7 @@ class ModuleDocFragment(object): - DOCUMENTATION = r''' + DOCUMENTATION = r""" options: hostname: description: @@ -50,10 +50,9 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): - 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 @@ class ModuleDocFragment(object): 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 -''' +""" diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py index e18a48ff..8c5c1458 100644 --- a/plugins/doc_fragments/attributes.py +++ b/plugins/doc_fragments/attributes.py @@ -11,17 +11,17 @@ class ModuleDocFragment(object): # Standard documentation fragment - DOCUMENTATION = r''' + DOCUMENTATION = r""" options: {} attributes: - check_mode: - description: Can run in C(check_mode) and return changed status prediction without modifying target. - diff_mode: - description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode. - platform: - description: Target OS/families that can be operated against. - support: N/A -''' + check_mode: + description: Can run in C(check_mode) and return changed status prediction without modifying target. + diff_mode: + description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode. + 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,23 +47,23 @@ class ModuleDocFragment(object): - community.routeros.api ''' - CONN = r''' + CONN = r""" options: {} attributes: - become: - description: Is usable alongside C(become) keywords. - connection: - 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. -''' + become: + description: Is usable alongside C(become) keywords. + connection: + 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. -''' + 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 @@ class ModuleDocFragment(object): 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. -''' + 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. -''' + 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. +""" diff --git a/plugins/modules/api.py b/plugins/modules/api.py index 4857a3cd..ecd99e01 100644 --- a/plugins/modules/api.py +++ b/plugins/modules/api.py @@ -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 @@ - 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 @@ - 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 @@ 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 @@ 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 @@ 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 @@ 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 }}" @@ -216,8 +218,8 @@ - attribute: "network" is: "in" value: - - "10.20.36.0" - - "192.168.255.0" + - "10.20.36.0" + - "192.168.255.0" register: extended_queryout - name: Dump "Extended query example" output @@ -231,9 +233,9 @@ username: "{{ username }}" path: "ip address" update: >- - .id=*14 - address=192.168.255.20/24 - comment={{ 'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2' | community.routeros.quote_argument_value }} + .id=*14 + address=192.168.255.20/24 + comment={{ 'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2' | community.routeros.quote_argument_value }} - name: Remove example - ether2 ip 192.168.255.20/24 with ".id = *14" community.routeros.api: @@ -255,18 +257,17 @@ - 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: - - address: 1.2.3.4 - - address: 2.3.4.5 - type: list - returned: always -''' + description: All outputs are in list with dictionary elements returned from RouterOS api. + sample: + - address: 1.2.3.4 + - 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 diff --git a/plugins/modules/api_facts.py b/plugins/modules/api_facts.py index 296621ea..e1fb70a3 100644 --- a/plugins/modules/api_facts.py +++ b/plugins/modules/api_facts.py @@ -9,23 +9,20 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: api_facts author: - - "Egor Zaitsev (@heuels)" - - "Nikolay Dachev (@NikolayDachev)" - - "Felix Fontein (@felixfontein)" + - "Egor Zaitsev (@heuels)" + - "Nikolay Dachev (@NikolayDachev)" + - "Felix Fontein (@felixfontein)" 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_). 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_). 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 @@ 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 @@ - 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 @@ - "!hardware" """ -RETURN = """ +RETURN = r""" ansible_facts: description: "Dictionary of IP geolocation facts for a host's IP address." returned: always diff --git a/plugins/modules/api_find_and_modify.py b/plugins/modules/api_find_and_modify.py index 176c9437..f6aab9ff 100644 --- a/plugins/modules/api_find_and_modify.py +++ b/plugins/modules/api_find_and_modify.py @@ -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 @@ 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 @@ - 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 }}" @@ -104,59 +102,58 @@ interface: bridge values: address: "192.168.1.1/24" - # If there are zero entries, or more than one: fail! We expected that - # exactly one is configured. + # If there are zero entries, or more than one: fail! We expected that + # 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. - sample: - - '.id': '*1' - actual-interface: bridge - address: "192.168.88.1/24" - comment: defconf - disabled: false - dynamic: false - interface: bridge - invalid: false - network: 192.168.88.0 - type: list - elements: dict - returned: success + description: + - A list of all elements for the current path before a change was made. + sample: + - '.id': '*1' + actual-interface: bridge + address: "192.168.88.1/24" + comment: defconf + disabled: false + dynamic: false + interface: bridge + invalid: false + network: 192.168.88.0 + type: list + elements: dict + returned: success new_data: - description: - - A list of all elements for the current path after a change was made. - sample: - - '.id': '*1' - actual-interface: bridge - address: "192.168.1.1/24" - comment: awesome - disabled: false - dynamic: false - interface: bridge - invalid: false - network: 192.168.1.0 - type: list - elements: dict - returned: success + description: + - A list of all elements for the current path after a change was made. + sample: + - '.id': '*1' + actual-interface: bridge + address: "192.168.1.1/24" + comment: awesome + disabled: false + dynamic: false + interface: bridge + invalid: false + network: 192.168.1.0 + type: list + elements: dict + returned: success match_count: - description: - - The number of entries that matched the criteria in O(find). - sample: 1 - type: int - returned: success + description: + - The number of entries that matched the criteria in O(find). + sample: 1 + type: int + returned: success modify__count: - description: - - The number of entries that were modified. - sample: 1 - type: int - returned: success -''' + description: + - The number of entries that were modified. + sample: 1 + type: int + returned: success +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.common.text.converters import to_native diff --git a/plugins/modules/api_info.py b/plugins/modules/api_info.py index 5b344630..f6965480 100644 --- a/plugins/modules/api_info.py +++ b/plugins/modules/api_info.py @@ -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 @@ 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 @@ -43,225 +42,225 @@ type: str choices: # BEGIN PATH LIST - - caps-man aaa - - caps-man access-list - - caps-man channel - - caps-man configuration - - caps-man datapath - - caps-man manager - - caps-man manager interface - - caps-man provisioning - - caps-man security - - certificate settings - - interface bonding - - interface bridge - - interface bridge mlag - - interface bridge port - - interface bridge port-controller - - interface bridge port-extender - - interface bridge settings - - interface bridge vlan - - interface detect-internet - - interface eoip - - interface ethernet - - interface ethernet poe - - interface ethernet switch - - interface ethernet switch port - - interface gre - - interface gre6 - - interface l2tp-client - - interface l2tp-server server - - interface list - - interface list member - - interface ovpn-client - - interface ovpn-server server - - interface ppp-client - - interface pppoe-client - - interface pppoe-server server - - interface pptp-server server - - interface sstp-server server - - interface vlan - - interface vrrp - - interface wifi - - interface wifi aaa - - interface wifi access-list - - interface wifi cap - - interface wifi capsman - - interface wifi channel - - interface wifi configuration - - interface wifi datapath - - interface wifi interworking - - interface wifi provisioning - - interface wifi security - - interface wifi steering - - interface wifiwave2 - - interface wifiwave2 aaa - - interface wifiwave2 access-list - - interface wifiwave2 cap - - interface wifiwave2 capsman - - interface wifiwave2 channel - - interface wifiwave2 configuration - - interface wifiwave2 datapath - - interface wifiwave2 interworking - - interface wifiwave2 provisioning - - interface wifiwave2 security - - interface wifiwave2 steering - - interface wireguard - - interface wireguard peers - - interface wireless - - interface wireless align - - interface wireless cap - - interface wireless security-profiles - - interface wireless sniffer - - interface wireless snooper - - iot modbus - - ip accounting - - ip accounting web-access - - ip address - - ip arp - - ip cloud - - ip cloud advanced - - ip dhcp-client - - ip dhcp-client option - - ip dhcp-relay - - ip dhcp-server - - ip dhcp-server config - - ip dhcp-server lease - - ip dhcp-server matcher - - ip dhcp-server network - - ip dhcp-server option - - ip dhcp-server option sets - - ip dns - - ip dns adlist - - ip dns static - - ip firewall address-list - - ip firewall connection tracking - - ip firewall filter - - ip firewall layer7-protocol - - ip firewall mangle - - ip firewall nat - - ip firewall raw - - ip firewall service-port - - ip hotspot service-port - - ip ipsec identity - - ip ipsec peer - - ip ipsec policy - - ip ipsec profile - - ip ipsec proposal - - ip ipsec settings - - ip neighbor discovery-settings - - ip pool - - ip proxy - - ip route - - ip route rule - - ip route vrf - - ip service - - ip settings - - ip smb - - ip socks - - ip ssh - - ip tftp settings - - ip traffic-flow - - ip traffic-flow ipfix - - ip traffic-flow target - - ip upnp - - ip upnp interfaces - - ip vrf - - ipv6 address - - ipv6 dhcp-client - - ipv6 dhcp-server - - ipv6 dhcp-server option - - ipv6 firewall address-list - - ipv6 firewall filter - - ipv6 firewall mangle - - ipv6 firewall nat - - ipv6 firewall raw - - ipv6 nd - - ipv6 nd prefix - - ipv6 nd prefix default - - ipv6 route - - ipv6 settings - - mpls - - mpls interface - - mpls ldp - - mpls ldp accept-filter - - mpls ldp advertise-filter - - mpls ldp interface - - port firmware - - port remote-access - - ppp aaa - - ppp profile - - ppp secret - - queue interface - - queue simple - - queue tree - - queue type - - radius - - radius incoming - - routing bgp aggregate - - routing bgp connection - - routing bgp instance - - routing bgp network - - routing bgp peer - - routing bgp template - - routing filter - - routing filter community-list - - routing filter num-list - - routing filter rule - - routing filter select-rule - - routing id - - routing igmp-proxy - - routing igmp-proxy interface - - routing mme - - routing ospf area - - routing ospf area range - - routing ospf instance - - routing ospf interface-template - - routing ospf static-neighbor - - routing pimsm instance - - routing pimsm interface-template - - routing rip - - routing ripng - - routing rule - - routing table - - snmp - - snmp community - - system clock - - system clock manual - - system health settings - - system identity - - system leds settings - - system logging - - system logging action - - system note - - system ntp client - - system ntp client servers - - system ntp server - - system package update - - system resource irq rps - - system routerboard settings - - system scheduler - - system script - - system upgrade mirror - - system ups - - system watchdog - - tool bandwidth-server - - tool e-mail - - tool graphing - - tool graphing interface - - tool graphing resource - - tool mac-server - - tool mac-server mac-winbox - - tool mac-server ping - - tool netwatch - - tool romon - - tool sms - - tool sniffer - - tool traffic-generator - - user - - user aaa - - user group - - user settings + - caps-man aaa + - caps-man access-list + - caps-man channel + - caps-man configuration + - caps-man datapath + - caps-man manager + - caps-man manager interface + - caps-man provisioning + - caps-man security + - certificate settings + - interface bonding + - interface bridge + - interface bridge mlag + - interface bridge port + - interface bridge port-controller + - interface bridge port-extender + - interface bridge settings + - interface bridge vlan + - interface detect-internet + - interface eoip + - interface ethernet + - interface ethernet poe + - interface ethernet switch + - interface ethernet switch port + - interface gre + - interface gre6 + - interface l2tp-client + - interface l2tp-server server + - interface list + - interface list member + - interface ovpn-client + - interface ovpn-server server + - interface ppp-client + - interface pppoe-client + - interface pppoe-server server + - interface pptp-server server + - interface sstp-server server + - interface vlan + - interface vrrp + - interface wifi + - interface wifi aaa + - interface wifi access-list + - interface wifi cap + - interface wifi capsman + - interface wifi channel + - interface wifi configuration + - interface wifi datapath + - interface wifi interworking + - interface wifi provisioning + - interface wifi security + - interface wifi steering + - interface wifiwave2 + - interface wifiwave2 aaa + - interface wifiwave2 access-list + - interface wifiwave2 cap + - interface wifiwave2 capsman + - interface wifiwave2 channel + - interface wifiwave2 configuration + - interface wifiwave2 datapath + - interface wifiwave2 interworking + - interface wifiwave2 provisioning + - interface wifiwave2 security + - interface wifiwave2 steering + - interface wireguard + - interface wireguard peers + - interface wireless + - interface wireless align + - interface wireless cap + - interface wireless security-profiles + - interface wireless sniffer + - interface wireless snooper + - iot modbus + - ip accounting + - ip accounting web-access + - ip address + - ip arp + - ip cloud + - ip cloud advanced + - ip dhcp-client + - ip dhcp-client option + - ip dhcp-relay + - ip dhcp-server + - ip dhcp-server config + - ip dhcp-server lease + - ip dhcp-server matcher + - ip dhcp-server network + - ip dhcp-server option + - ip dhcp-server option sets + - ip dns + - ip dns adlist + - ip dns static + - ip firewall address-list + - ip firewall connection tracking + - ip firewall filter + - ip firewall layer7-protocol + - ip firewall mangle + - ip firewall nat + - ip firewall raw + - ip firewall service-port + - ip hotspot service-port + - ip ipsec identity + - ip ipsec peer + - ip ipsec policy + - ip ipsec profile + - ip ipsec proposal + - ip ipsec settings + - ip neighbor discovery-settings + - ip pool + - ip proxy + - ip route + - ip route rule + - ip route vrf + - ip service + - ip settings + - ip smb + - ip socks + - ip ssh + - ip tftp settings + - ip traffic-flow + - ip traffic-flow ipfix + - ip traffic-flow target + - ip upnp + - ip upnp interfaces + - ip vrf + - ipv6 address + - ipv6 dhcp-client + - ipv6 dhcp-server + - ipv6 dhcp-server option + - ipv6 firewall address-list + - ipv6 firewall filter + - ipv6 firewall mangle + - ipv6 firewall nat + - ipv6 firewall raw + - ipv6 nd + - ipv6 nd prefix + - ipv6 nd prefix default + - ipv6 route + - ipv6 settings + - mpls + - mpls interface + - mpls ldp + - mpls ldp accept-filter + - mpls ldp advertise-filter + - mpls ldp interface + - port firmware + - port remote-access + - ppp aaa + - ppp profile + - ppp secret + - queue interface + - queue simple + - queue tree + - queue type + - radius + - radius incoming + - routing bgp aggregate + - routing bgp connection + - routing bgp instance + - routing bgp network + - routing bgp peer + - routing bgp template + - routing filter + - routing filter community-list + - routing filter num-list + - routing filter rule + - routing filter select-rule + - routing id + - routing igmp-proxy + - routing igmp-proxy interface + - routing mme + - routing ospf area + - routing ospf area range + - routing ospf instance + - routing ospf interface-template + - routing ospf static-neighbor + - routing pimsm instance + - routing pimsm interface-template + - routing rip + - routing ripng + - routing rule + - routing table + - snmp + - snmp community + - system clock + - system clock manual + - system health settings + - system identity + - system leds settings + - system logging + - system logging action + - system note + - system ntp client + - system ntp client servers + - system ntp server + - system package update + - system resource irq rps + - system routerboard settings + - system scheduler + - system script + - system upgrade mirror + - system ups + - system watchdog + - tool bandwidth-server + - tool e-mail + - tool graphing + - tool graphing interface + - tool graphing resource + - tool mac-server + - tool mac-server mac-winbox + - tool mac-server ping + - tool netwatch + - tool romon + - tool sms + - tool sniffer + - tool traffic-generator + - user + - user aaa + - user group + - user settings # END PATH LIST unfiltered: description: @@ -317,10 +316,9 @@ - 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,26 +342,25 @@ - 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: - - '.id': '*1' - actual-interface: bridge - address: "192.168.88.1/24" - comment: defconf - disabled: false - dynamic: false - interface: bridge - invalid: false - network: 192.168.88.0 - type: list - elements: dict - returned: always -''' + description: A list of all elements for the current path. + sample: + - '.id': '*1' + actual-interface: bridge + address: "192.168.88.1/24" + comment: defconf + disabled: false + dynamic: false + interface: bridge + invalid: false + network: 192.168.88.0 + type: list + elements: dict + returned: always +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.common.text.converters import to_native diff --git a/plugins/modules/api_modify.py b/plugins/modules/api_modify.py index 9ab34d91..2f59c856 100644 --- a/plugins/modules/api_modify.py +++ b/plugins/modules/api_modify.py @@ -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 @@ 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,230 +46,231 @@ 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: # BEGIN PATH LIST - - caps-man aaa - - caps-man access-list - - caps-man channel - - caps-man configuration - - caps-man datapath - - caps-man manager - - caps-man manager interface - - caps-man provisioning - - caps-man security - - certificate settings - - interface bonding - - interface bridge - - interface bridge mlag - - interface bridge port - - interface bridge port-controller - - interface bridge port-extender - - interface bridge settings - - interface bridge vlan - - interface detect-internet - - interface eoip - - interface ethernet - - interface ethernet poe - - interface ethernet switch - - interface ethernet switch port - - interface gre - - interface gre6 - - interface l2tp-client - - interface l2tp-server server - - interface list - - interface list member - - interface ovpn-client - - interface ovpn-server server - - interface ppp-client - - interface pppoe-client - - interface pppoe-server server - - interface pptp-server server - - interface sstp-server server - - interface vlan - - interface vrrp - - interface wifi - - interface wifi aaa - - interface wifi access-list - - interface wifi cap - - interface wifi capsman - - interface wifi channel - - interface wifi configuration - - interface wifi datapath - - interface wifi interworking - - interface wifi provisioning - - interface wifi security - - interface wifi steering - - interface wifiwave2 - - interface wifiwave2 aaa - - interface wifiwave2 access-list - - interface wifiwave2 cap - - interface wifiwave2 capsman - - interface wifiwave2 channel - - interface wifiwave2 configuration - - interface wifiwave2 datapath - - interface wifiwave2 interworking - - interface wifiwave2 provisioning - - interface wifiwave2 security - - interface wifiwave2 steering - - interface wireguard - - interface wireguard peers - - interface wireless - - interface wireless align - - interface wireless cap - - interface wireless security-profiles - - interface wireless sniffer - - interface wireless snooper - - iot modbus - - ip accounting - - ip accounting web-access - - ip address - - ip arp - - ip cloud - - ip cloud advanced - - ip dhcp-client - - ip dhcp-client option - - ip dhcp-relay - - ip dhcp-server - - ip dhcp-server config - - ip dhcp-server lease - - ip dhcp-server matcher - - ip dhcp-server network - - ip dhcp-server option - - ip dhcp-server option sets - - ip dns - - ip dns adlist - - ip dns static - - ip firewall address-list - - ip firewall connection tracking - - ip firewall filter - - ip firewall layer7-protocol - - ip firewall mangle - - ip firewall nat - - ip firewall raw - - ip firewall service-port - - ip hotspot service-port - - ip ipsec identity - - ip ipsec peer - - ip ipsec policy - - ip ipsec profile - - ip ipsec proposal - - ip ipsec settings - - ip neighbor discovery-settings - - ip pool - - ip proxy - - ip route - - ip route rule - - ip route vrf - - ip service - - ip settings - - ip smb - - ip socks - - ip ssh - - ip tftp settings - - ip traffic-flow - - ip traffic-flow ipfix - - ip traffic-flow target - - ip upnp - - ip upnp interfaces - - ip vrf - - ipv6 address - - ipv6 dhcp-client - - ipv6 dhcp-server - - ipv6 dhcp-server option - - ipv6 firewall address-list - - ipv6 firewall filter - - ipv6 firewall mangle - - ipv6 firewall nat - - ipv6 firewall raw - - ipv6 nd - - ipv6 nd prefix - - ipv6 nd prefix default - - ipv6 route - - ipv6 settings - - mpls - - mpls interface - - mpls ldp - - mpls ldp accept-filter - - mpls ldp advertise-filter - - mpls ldp interface - - port firmware - - port remote-access - - ppp aaa - - ppp profile - - ppp secret - - queue interface - - queue simple - - queue tree - - queue type - - radius - - radius incoming - - routing bgp aggregate - - routing bgp connection - - routing bgp instance - - routing bgp network - - routing bgp peer - - routing bgp template - - routing filter - - routing filter community-list - - routing filter num-list - - routing filter rule - - routing filter select-rule - - routing id - - routing igmp-proxy - - routing igmp-proxy interface - - routing mme - - routing ospf area - - routing ospf area range - - routing ospf instance - - routing ospf interface-template - - routing ospf static-neighbor - - routing pimsm instance - - routing pimsm interface-template - - routing rip - - routing ripng - - routing rule - - routing table - - snmp - - snmp community - - system clock - - system clock manual - - system health settings - - system identity - - system leds settings - - system logging - - system logging action - - system note - - system ntp client - - system ntp client servers - - system ntp server - - system package update - - system resource irq rps - - system routerboard settings - - system scheduler - - system script - - system upgrade mirror - - system ups - - system watchdog - - tool bandwidth-server - - tool e-mail - - tool graphing - - tool graphing interface - - tool graphing resource - - tool mac-server - - tool mac-server mac-winbox - - tool mac-server ping - - tool netwatch - - tool romon - - tool sms - - tool sniffer - - tool traffic-generator - - user - - user aaa - - user group - - user settings + - caps-man aaa + - caps-man access-list + - caps-man channel + - caps-man configuration + - caps-man datapath + - caps-man manager + - caps-man manager interface + - caps-man provisioning + - caps-man security + - certificate settings + - interface bonding + - interface bridge + - interface bridge mlag + - interface bridge port + - interface bridge port-controller + - interface bridge port-extender + - interface bridge settings + - interface bridge vlan + - interface detect-internet + - interface eoip + - interface ethernet + - interface ethernet poe + - interface ethernet switch + - interface ethernet switch port + - interface gre + - interface gre6 + - interface l2tp-client + - interface l2tp-server server + - interface list + - interface list member + - interface ovpn-client + - interface ovpn-server server + - interface ppp-client + - interface pppoe-client + - interface pppoe-server server + - interface pptp-server server + - interface sstp-server server + - interface vlan + - interface vrrp + - interface wifi + - interface wifi aaa + - interface wifi access-list + - interface wifi cap + - interface wifi capsman + - interface wifi channel + - interface wifi configuration + - interface wifi datapath + - interface wifi interworking + - interface wifi provisioning + - interface wifi security + - interface wifi steering + - interface wifiwave2 + - interface wifiwave2 aaa + - interface wifiwave2 access-list + - interface wifiwave2 cap + - interface wifiwave2 capsman + - interface wifiwave2 channel + - interface wifiwave2 configuration + - interface wifiwave2 datapath + - interface wifiwave2 interworking + - interface wifiwave2 provisioning + - interface wifiwave2 security + - interface wifiwave2 steering + - interface wireguard + - interface wireguard peers + - interface wireless + - interface wireless align + - interface wireless cap + - interface wireless security-profiles + - interface wireless sniffer + - interface wireless snooper + - iot modbus + - ip accounting + - ip accounting web-access + - ip address + - ip arp + - ip cloud + - ip cloud advanced + - ip dhcp-client + - ip dhcp-client option + - ip dhcp-relay + - ip dhcp-server + - ip dhcp-server config + - ip dhcp-server lease + - ip dhcp-server matcher + - ip dhcp-server network + - ip dhcp-server option + - ip dhcp-server option sets + - ip dns + - ip dns adlist + - ip dns static + - ip firewall address-list + - ip firewall connection tracking + - ip firewall filter + - ip firewall layer7-protocol + - ip firewall mangle + - ip firewall nat + - ip firewall raw + - ip firewall service-port + - ip hotspot service-port + - ip ipsec identity + - ip ipsec peer + - ip ipsec policy + - ip ipsec profile + - ip ipsec proposal + - ip ipsec settings + - ip neighbor discovery-settings + - ip pool + - ip proxy + - ip route + - ip route rule + - ip route vrf + - ip service + - ip settings + - ip smb + - ip socks + - ip ssh + - ip tftp settings + - ip traffic-flow + - ip traffic-flow ipfix + - ip traffic-flow target + - ip upnp + - ip upnp interfaces + - ip vrf + - ipv6 address + - ipv6 dhcp-client + - ipv6 dhcp-server + - ipv6 dhcp-server option + - ipv6 firewall address-list + - ipv6 firewall filter + - ipv6 firewall mangle + - ipv6 firewall nat + - ipv6 firewall raw + - ipv6 nd + - ipv6 nd prefix + - ipv6 nd prefix default + - ipv6 route + - ipv6 settings + - mpls + - mpls interface + - mpls ldp + - mpls ldp accept-filter + - mpls ldp advertise-filter + - mpls ldp interface + - port firmware + - port remote-access + - ppp aaa + - ppp profile + - ppp secret + - queue interface + - queue simple + - queue tree + - queue type + - radius + - radius incoming + - routing bgp aggregate + - routing bgp connection + - routing bgp instance + - routing bgp network + - routing bgp peer + - routing bgp template + - routing filter + - routing filter community-list + - routing filter num-list + - routing filter rule + - routing filter select-rule + - routing id + - routing igmp-proxy + - routing igmp-proxy interface + - routing mme + - routing ospf area + - routing ospf area range + - routing ospf instance + - routing ospf interface-template + - routing ospf static-neighbor + - routing pimsm instance + - routing pimsm interface-template + - routing rip + - routing ripng + - routing rule + - routing table + - snmp + - snmp community + - system clock + - system clock manual + - system health settings + - system identity + - system leds settings + - system logging + - system logging action + - system note + - system ntp client + - system ntp client servers + - system ntp server + - system package update + - system resource irq rps + - system routerboard settings + - system scheduler + - system script + - system upgrade mirror + - system ups + - system watchdog + - tool bandwidth-server + - tool e-mail + - tool graphing + - tool graphing interface + - tool graphing resource + - tool mac-server + - tool mac-server mac-winbox + - tool mac-server ping + - tool netwatch + - tool romon + - tool sms + - tool sniffer + - tool traffic-generator + - user + - user aaa + - user group + - user settings # END PATH LIST data: description: @@ -298,12 +298,12 @@ 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 @@ 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 @@ 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,23 +342,20 @@ 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) +# Ensures that we have exactly two DHCP server networks (in the specified order) community.routeros.api_modify: path: ip dhcp-server network handle_absent_entries: remove @@ -387,12 +383,12 @@ chain: srcnat comment: NAT to WAN out-interface-list: WAN - # Three ways to unset values: - # - nothing after `:` - # - "empty" value (null/~/None) - # - prepend '!' + # Three ways to unset values: + # - nothing after `:` + # - "empty" value (null/~/None) + # - prepend '!' out-interface: - to-addresses: ~ + to-addresses: '!to-ports': - name: Block all incoming connections @@ -404,50 +400,49 @@ handle_absent_entries: remove handle_entries_content: remove_as_much_as_possible restrict: - # Do not touch any chain except the input chain + # Do not touch any chain except the input chain - field: chain values: - input 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. - sample: - - '.id': '*1' - actual-interface: bridge - address: "192.168.88.1/24" - comment: defconf - disabled: false - dynamic: false - interface: bridge - invalid: false - network: 192.168.88.0 - type: list - elements: dict - returned: always + description: + - A list of all elements for the current path before a change was made. + sample: + - '.id': '*1' + actual-interface: bridge + address: "192.168.88.1/24" + comment: defconf + disabled: false + dynamic: false + interface: bridge + invalid: false + network: 192.168.88.0 + type: list + elements: dict + returned: always new_data: - description: - - A list of all elements for the current path after a change was made. - sample: - - '.id': '*1' - actual-interface: bridge - address: "192.168.1.1/24" - comment: awesome - disabled: false - dynamic: false - interface: bridge - invalid: false - network: 192.168.1.0 - type: list - elements: dict - returned: always -''' + description: + - A list of all elements for the current path after a change was made. + sample: + - '.id': '*1' + actual-interface: bridge + address: "192.168.1.1/24" + comment: awesome + disabled: false + dynamic: false + interface: bridge + invalid: false + network: 192.168.1.0 + type: list + elements: dict + returned: always +""" from collections import defaultdict diff --git a/plugins/modules/command.py b/plugins/modules/command.py index bf74d474..306f6482 100644 --- a/plugins/modules/command.py +++ b/plugins/modules/command.py @@ -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 @@ 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 @@ - 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: ['...', '...'] diff --git a/plugins/modules/facts.py b/plugins/modules/facts.py index 50f9a21f..21013aa0 100644 --- a/plugins/modules/facts.py +++ b/plugins/modules/facts.py @@ -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_). 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_). 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 @@ 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 @@ 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 @@ - "!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_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 diff --git a/update-docs.py b/update-docs.py index 05a9ee74..4f164c85 100755 --- a/update-docs.py +++ b/update-docs.py @@ -42,7 +42,7 @@ def main(): path_choices = sorted([join_path(path) for path, path_info in PATHS.items() if path_info.fully_understood]) 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__':