Add identifier option to apache2_module (#33748)

* Add identifier option to apache2_module

There is a convention connecting the name passed to a2enmod and the one
appearing in apache2ctl -M. Not all modules follow this convention and
we have added a growing list of implicit conversions.
As a better long-term solution this adds an "identifier" option to be
able to set both strings explicitly.

* Run debian-specific tests only there

* Improve cleanup after apache2 tests

This is a follow-up/extension of https://github.com/ansible/ansible/pull/33630

* Add example for the new identifier option

* Put all debian tests in a block

lib/ansible/modules/web_infrastructure/apache2_module.py

@@ -21,24 +21,31 @@ author:
     - Christian Berendt (@berendt)
     - Ralf Hertel (@n0trax)
     - Robin Roth (@robinro)
-short_description: enables/disables a module of the Apache2 webserver
+short_description: Enables/disables a module of the Apache2 webserver.
 description:
    - Enables or disables a specified module of the Apache2 webserver.
 options:
    name:
      description:
-        - name of the module to enable/disable
+        - Name of the module to enable/disable as given to C(a2enmod/a2dismod).
      required: true
+   identifier:
+     description:
+         - Identifier of the module as listed by C(apache2ctl -M).
+           This is optional and usually determined automatically by the common convention of
+           appending C(_module) to I(name) as well as custom exception for popular modules.
+     required: False
+     version_added: "2.5"
    force:
      description:
-        - force disabling of default modules and override Debian warnings
+        - Force disabling of default modules and override Debian warnings.
      required: false
      choices: ['True', 'False']
      default: False
      version_added: "2.1"
    state:
      description:
-        - indicate the desired state of the resource
+        - Desired state of the module.
      choices: ['present', 'absent']
      default: present
    ignore_configcheck:
@@ -69,6 +76,11 @@ EXAMPLES = '''
     state: absent
     name: mpm_worker
     ignore_configcheck: True
+# enable dump_io module, which is identified as dumpio_module inside apache2
+- apache2_module:
+    state: present
+    name: dump_io
+    identifier: dumpio_module
 '''
 
 RETURN = '''
@@ -119,15 +131,12 @@ def _get_ctl_binary(module):
 
 def _module_is_enabled(module):
     control_binary = _get_ctl_binary(module)
-    name = module.params['name']
-    ignore_configcheck = module.params['ignore_configcheck']
-
     result, stdout, stderr = module.run_command("%s -M" % control_binary)
 
     if result != 0:
         error_msg = "Error executing %s: %s" % (control_binary, stderr)
-        if ignore_configcheck:
-            if 'AH00534' in stderr and 'mpm_' in name:
+        if module.params['ignore_configcheck']:
+            if 'AH00534' in stderr and 'mpm_' in module.params['name']:
                 module.warnings.append(
                     "No MPM module loaded! apache2 reload AND other module actions"
                     " will fail if no MPM module is loaded immediately."
@@ -138,7 +147,7 @@ def _module_is_enabled(module):
         else:
             module.fail_json(msg=error_msg)
 
-    searchstring = ' ' + create_apache_identifier(name)
+    searchstring = ' ' + module.params['identifier']
     return searchstring in stdout
 
 
@@ -205,7 +214,18 @@ def _set_state(module, state):
                              result=success_msg,
                              warnings=module.warnings)
         else:
-            module.fail_json(msg="Failed to set module %s to %s: %s" % (name, state_string, stdout),
+            msg = (
+                'Failed to set module {name} to {state}:\n'
+                '{stdout}\n'
+                'Maybe the module identifier ({identifier}) was guessed incorrectly.'
+                'Consider setting the "identifier" option.'
+            ).format(
+                name=name,
+                state=state_string,
+                stdout=stdout,
+                identifier=module.params['identifier']
+            )
+            module.fail_json(msg=msg,
                              rc=result,
                              stdout=stdout,
                              stderr=stderr)
@@ -219,6 +239,7 @@ def main():
     module = AnsibleModule(
         argument_spec=dict(
             name=dict(required=True),
+            identifier=dict(required=False, type='str'),
             force=dict(required=False, type='bool', default=False),
             state=dict(default='present', choices=['absent', 'present']),
             ignore_configcheck=dict(required=False, type='bool', default=False),
@@ -232,6 +253,9 @@ def main():
     if name == 'cgi' and _run_threaded(module):
         module.fail_json(msg="Your MPM seems to be threaded. No automatic actions on module %s possible." % name)
 
+    if not module.params['identifier']:
+        module.params['identifier'] = create_apache_identifier(module.params['name'])
+
     if module.params['state'] in ['present', 'absent']:
         _set_state(module, module.params['state'])