added information-output to system-upgrade & -reboot, updated info re…

…garding version-support

README.md

@@ -35,7 +35,6 @@ ansible-galaxy collection install ansibleguy.opnsense
 
 See: [Docs](https://opnsense.ansibleguy.net)
 
-
 ----
 
 ## Contribute
@@ -46,6 +45,17 @@ See also: [Contributing](https://github.com/ansibleguy/collection_opnsense/blob/
 
 ----
 
+## Version Support
+
+The `ansibleguy.opnsense` modules always support the latest version of OPNSense.
+
+If an API changed, the current module-implementation might fail for firewalls running an older firmware.
+
+See also: [Firmware-Upgrade using ansibleguy.opnsense.system](https://opnsense.ansibleguy.net/en/latest/modules/system.html#examples)
+
+----
+
+
 ## Modules
 
 **Development States**:

docs/source/usage/4_develop.rst

@@ -173,6 +173,8 @@ Verbose output
 
 If you want to output something to ansible's runtime - use 'module.warn':
 
+NOTE: This output is buffered by Ansible until the task has finished.
+
 .. code-block:: python3
 
     module.warn(f"{before} != {after}")

plugins/module_utils/helper/system.py

@@ -1,35 +1,50 @@
-from socket import socket, AF_INET, SOCK_STREAM
+from socket import socket, AF_INET, AF_INET6, SOCK_STREAM, gaierror
 from time import time, sleep
+from datetime import datetime
 
 from ansible.module_utils.basic import AnsibleModule
 
 from ansible_collections.ansibleguy.opnsense.plugins.module_utils.defaults.main import CONNECTION_TEST_TIMEOUT
 
 
-def opn_reachable(module: AnsibleModule) -> bool:
-    with socket(AF_INET, SOCK_STREAM) as s:
+def _opn_reachable_ipv(module: AnsibleModule, address_family: int) -> bool:
+    with socket(address_family, SOCK_STREAM) as s:
         s.settimeout(CONNECTION_TEST_TIMEOUT)
         return s.connect_ex((
             module.params['firewall'],
             module.params['api_port']
         )) == 0
 
 
+def _opn_reachable(module: AnsibleModule) -> bool:
+    try:
+        return _opn_reachable_ipv(module, AF_INET)
+
+    except gaierror:
+        return _opn_reachable_ipv(module, AF_INET6)
+
+
+def _wait_msg(module: AnsibleModule, msg: str):
+    module.warn(f"{datetime.now().strftime('%Y-%m-%d %H:%M:%S')} | {msg}")
+
+
 def wait_for_response(module: AnsibleModule) -> bool:
     timeout = time() + module.params['wait_timeout']
 
     if module.params['action'] == 'upgrade':
-        # waiting longer for download/install to finish
+        _wait_msg(module, 'Waiting download & upgrade to finish..')
         sleep(int(module.params['wait_timeout'] / 2))
 
     else:
-        # waiting for services to stop
+        _wait_msg(module, 'Waiting for service to stop..')
         sleep(10)
 
     while time() < timeout:
-        if opn_reachable(module=module):
+        if _opn_reachable(module=module):
+            _wait_msg(module, 'Got response!')
             return True
 
+        _wait_msg(module, 'Waiting for response..')
         sleep(module.params['poll_interval'])
 
     return False

plugins/modules/system.py

@@ -59,6 +59,7 @@ def run_module():
             if module.params['debug']:
                 module.warn(f"Waiting for firewall to complete '{module.params['action']}'!")
 
+            # todo: cleaner way of handling if no upgrade is needed
             result['failed'] = not wait_for_response(module=module)
 
             if result['failed']:

tests/README.md

@@ -31,9 +31,9 @@ You need to add a `opt1` dummy-interface named `TEST`. The assigned IPs do not m
 
 ### Internet access
 
-To perform some tests (package/firmware, ids) the test firewall needs to reach some public service:
+To perform some tests (system, ids) the test firewall needs to reach some public service:
 
-* package/firmware - `pkg.opnsense.org`
+* system - `pkg.opnsense.org`
 * ids - `rules.emergingthreats.net`
 
 ----