updated 'retries' and 'timeout' parameter name, added description to …

…default module-parameters
ansibleguy · Jan 1, 2024 · db9cbe6 · db9cbe6
1 parent 01cbd5b
commit db9cbe6
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 29 deletions.
diff --git a/docs/source/modules/1_basic.rst b/docs/source/modules/1_basic.rst
@@ -10,27 +10,27 @@ All modules
 ***********
 
 ..  csv-table:: Definition
-    :header: "Parameter", "Type", "Required", "Default", "Comment"
+    :header: "Parameter", "Type", "Required", "Default", "Aliases", "Comment"
     :widths: 15 10 10 10 55
 
-    firewall, string, true, \- , "IP-Address or DNS hostname of the target firewall. Must be included as 'common name' in the firewalls web-certificate to use 'ssl_verify=true'"
-    api_port, integer, false, 443, "Port the target firewall uses for its web-interface"
-    api_key, string, "false, true if 'api_credential_file' is not used", \- , "API key used to authenticate, alternative to 'api_credential_file'"
-    api_secret, string, "false, true if 'api_credential_file' is not used", \- , "API secret used to authenticate, alternative to 'api_credential_file'. Is set as 'no_log' parameter."
-    api_credential_file, path, "false, true if 'api_key' and 'api_secret' are not used", \- , "Path to the api-credential file as downloaded through the web-interface. Alternative to 'api_key' and 'api_secret'."
-    ssl_verify, bool, false, true, "If the certificate of the target firewall should be validated. RECOMMENDED FOR PRODUCTION USAGE!"
-    ssl_ca_file, path, false, \- , "If you use an internal certificate-authority to create the certificate of the target firewall, provide the path to its public key for validation."
-    debug, boolean, false, false, "Used to en-/disable the debug mode. All API requests and responses will be shown as Ansible warnings at runtime. Will be hidden if the tasks 'no_log' parameter is set to 'true'."
-    profiling, boolean, false, false, "Used to en-/disable the profiling mode. Time consumption of the module will be logged to '/tmp/ansibleguy.opnsense'."
-    timeout, float, false, \- , "Manually override the modules default API-request timeout. Mind that every request retry might consume this amount of time!"
-    retries, integer, false, 1, "Number of retries on API requests, in case there is a connection error or timeout."
+    firewall, string, true, "\-", "\-", "IP-Address or DNS hostname of the target firewall. Must be included as 'common name' or 'subject alternative name' in the firewalls web-certificate to use 'ssl_verify=true'"
+    api_port, integer, false, 443, "\-", "Port the target firewall uses for its web-interface"
+    api_key, string, "false, true if 'api_credential_file' is not used", "\-", "\-", "API key used to authenticate, alternative to 'api_credential_file'"
+    api_secret, string, "false, true if 'api_credential_file' is not used", "\-", "\-", "API secret used to authenticate, alternative to 'api_credential_file'. Is set as 'no_log' parameter"
+    api_credential_file, path, "false, true if 'api_key' and 'api_secret' are not used", "\-", "\-", "Path to the api-credential file as downloaded through the web-interface. Alternative to 'api_key' and 'api_secret'"
+    ssl_verify, bool, false, true, "\-", "If the certificate of the target firewall should be validated. RECOMMENDED FOR PRODUCTION USAGE!"
+    ssl_ca_file, path, false, "\-", "\-", "If you use an internal certificate-authority to create the certificate of the target firewall, provide the path to its public key for validation"
+    debug, boolean, false, false, "\-", "Used to en-/disable the debug mode. All API requests and responses will be shown as Ansible warnings at runtime. Will be hidden if the tasks 'no_log' parameter is set to 'true'"
+    profiling, boolean, false, false, "\-", "Used to en-/disable the profiling mode. Time consumption of the module will be logged to '/tmp/ansibleguy.opnsense'"
+    api_timeout, float, false, "\-", "timeout", "Manually override the modules default API-request timeout"
+    api_retries, integer, false, "0", "connect_retries", "Number of retries on API requests, in case there is an error when ESTABLISHING the connection. This does not handle errors returned by the OPNSense system"
 
 Modules managing multiple entries
 *********************************
 
 ..  csv-table:: Definition
-    :header: "Parameter", "Type", "Required", "Default", "Comment"
+    :header: "Parameter", "Type", "Required", "Default", "Aliases", "Comment"
     :widths: 15 10 10 10 55
 
-    "enabled","boolean","false","true","En- or disable the entry"
-    "state","string","false","present","One of 'present', 'absent'. Add or remove the entry"
+    "enabled","boolean","false","true","\-","En- or disable the entry"
+    "state","string","false","present","\-","One of 'present', 'absent'. Add or remove the entry"
diff --git a/plugins/module_utils/base/api.py b/plugins/module_utils/base/api.py
@@ -24,8 +24,8 @@ def _start(self, timeout: float) -> httpx.Client:
         check_host(module=self.m)
         check_or_load_credentials(module=self.m)
 
-        if 'timeout' in self.m.params and self.m.params['timeout'] is not None:
-            timeout = self.m.params['timeout']
+        if 'api_timeout' in self.m.params and self.m.params['api_timeout'] is not None:
+            timeout = self.m.params['api_timeout']
 
         setdefaulttimeout(timeout)
 
@@ -35,7 +35,7 @@ def _start(self, timeout: float) -> httpx.Client:
             timeout=httpx.Timeout(timeout=timeout),
             transport=httpx.HTTPTransport(
                 verify=ssl_verification(module=self.m),
-                retries=self.m.params['retries'],
+                retries=self.m.params['api_retries'],
             ),
         )
 

diff --git a/plugins/module_utils/defaults/main.py b/plugins/module_utils/defaults/main.py
@@ -1,16 +1,58 @@
 OPN_MOD_ARGS = dict(
-    firewall=dict(type='str', required=True),
-    api_port=dict(type=int, required=False, default=443),
-    api_key=dict(type='str', required=False, no_log=True),
-    api_secret=dict(type='str', required=False, no_log=True),
-    api_credential_file=dict(type='path', required=False),
-    ssl_verify=dict(type='bool', required=False, default=True),
-    ssl_ca_file=dict(type='path', required=False),
-    debug=dict(type='bool', required=False, default=False),
-    profiling=dict(type='bool', required=False, default=False),
-    timeout=dict(type='float', required=False),
-    retries=dict(type='int', required=False, default=1),
+    firewall=dict(
+        type='str', required=True,
+        description="IP-Address or DNS hostname of the target firewall. "
+                    "Must be included as 'common name' or 'subject alternative name' in the firewalls web-certificate "
+                    "to use 'ssl_verify=true'"
+    ),
+    api_port=dict(
+        type=int, required=False, default=443,
+        description='Port the target firewall uses for its web-interface'
+    ),
+    api_key=dict(
+        type='str', required=False, no_log=True,
+        description="API key used to authenticate, alternative to 'api_credential_file'"
+    ),
+    api_secret=dict(
+        type='str', required=False, no_log=True,
+        description="API secret used to authenticate, alternative to 'api_credential_file'. "
+                    "Is set as 'no_log' parameter"
+    ),
+    api_credential_file=dict(
+        type='path', required=False,
+        description="Path to the api-credential file as downloaded through the web-interface. "
+                    "Alternative to 'api_key' and 'api_secret'"
+    ),
+    ssl_verify=dict(
+        type='bool', required=False, default=True,
+        description='If the certificate of the target firewall should be validated. RECOMMENDED FOR PRODUCTION USAGE!'
+    ),
+    ssl_ca_file=dict(
+        type='path', required=False,
+        description='If you use an internal certificate-authority to create the certificate of the target firewall, '
+                    'provide the path to its public key for validation'
+    ),
+    debug=dict(
+        type='bool', required=False, default=False,
+        description="Used to en-/disable the debug mode. All API requests and responses will be shown "
+                    "as Ansible warnings at runtime. Will be hidden if the tasks 'no_log' parameter is set to 'true'"
+    ),
+    profiling=dict(
+        type='bool', required=False, default=False,
+        description="Used to en-/disable the profiling mode. "
+                    "Time consumption of the module will be logged to '/tmp/ansibleguy.opnsense'"
+    ),
+    api_timeout=dict(
+        type='float', required=False, aliases=['timeout'],
+        description='Manually override the modules default API-request timeout'
+    ),
+    api_retries=dict(
+        type='int', required=False, default=0, aliases=['connect_retries'],
+        description='Number of retries on API requests, in case there is an error when establishing the connection. '
+                    'This does not handle errors returned by the OPNSense system'
+    ),
 )
+
 BUILTIN_ALIASES = [
     'bogons', 'bogonsv6', 'sshlockout', 'virusprot',
 ]