feat: support includes for services

Feature: Allow for includes to be specified for services.
Includes are described at https://firewalld.org/documentation/man-pages/firewalld.service.html

Reason: This makes firewalld services more explicit and easier / quicker
to read when there are many non-standard ports.

Result: Users can specify other services to include when creating
and setting services.

Signed-off-by: Rich Megginson <[email protected]>

Fixes #255

Author: richm

README.md

@@ -698,6 +698,19 @@ helper_module: ftp
 helper_module: nf_conntrack_ftp
 ```
 
+### includes
+
+Name of one or more services to specify in an `include` in a
+service definition.  The `include` directive is described in the
+[service manpage](https://firewalld.org/documentation/man-pages/firewalld.service.html)
+This can only be used when managing service definitions.
+
+```yaml
+includes:
+  - https
+  - ldaps
+```
+
 ### timeout
 
 The amount of time in seconds a setting is in effect. The timeout is usable if

library/firewall_lib.py

@@ -250,6 +250,13 @@
     type: list
     elements: str
     default: []
+  includes:
+    description:
+      Services to include in this one.
+    required: false
+    type: list
+    elements: str
+    default: []
   __report_changed:
     description:
       If false, do not report changed true even if changed.
@@ -691,6 +698,7 @@ def main():
             protocol=dict(required=False, type="list", elements="str", default=[]),
             helper_module=dict(required=False, type="list", elements="str", default=[]),
             destination=dict(required=False, type="list", elements="str", default=[]),
+            includes=dict(required=False, type="list", elements="str", default=[]),
             __report_changed=dict(required=False, type="bool", default=True),
         ),
         supports_check_mode=True,
@@ -771,6 +779,7 @@ def main():
     permanent = module.params["permanent"]
     runtime = module.params["runtime"]
     state = module.params["state"]
+    includes = module.params["includes"]
 
     # All options that require state to be set
     state_required = any(
@@ -1146,6 +1155,11 @@ def exception_handler(exception_message):
                     if not module.check_mode:
                         fw_service_settings.setDestination("ipv6", destination_ipv6)
                     changed = True
+            for _include in includes:
+                if not fw_service_settings.queryInclude(_include):
+                    if not module.check_mode:
+                        fw_service_settings.addInclude(_include)
+                    changed = True
         if state == "absent" and service_exists:
             if port:
                 for _port, _protocol in port:
@@ -1181,6 +1195,11 @@ def exception_handler(exception_message):
                     if not module.check_mode:
                         fw_service_settings.removeDestination("ipv6", destination_ipv6)
                     changed = True
+            for _include in includes:
+                if fw_service_settings.queryInclude(_include):
+                    if not module.check_mode:
+                        fw_service_settings.removeInclude(_include)
+                    changed = True
             if not any(
                 (
                     port,

tasks/main.yml

@@ -111,6 +111,7 @@
     permanent: "{{ item.permanent | default(True) }}"
     runtime: "{{ item.runtime | default(True) }}"
     state: "{{ item.state | default(omit) }}"
+    includes: "{{ item.includes | default(omit) }}"
     __report_changed: "{{ __firewall_report_changed }}"
   loop: "{{ firewall is mapping | ternary([firewall], firewall) |
     map('dict2items') | map('difference', __previous) |

tests/tests_ansible.yml

@@ -536,6 +536,28 @@
           register: result
           failed_when: result is failed or result is not changed
 
+        - name: Add includes
+          firewall_lib:
+            service: customservice
+            includes:
+              - https
+              - ldaps
+            state: present
+            permanent: true
+          register: result
+          failed_when: result is failed or result is not changed
+
+        - name: Add includes again to check idempotence
+          firewall_lib:
+            service: customservice
+            includes:
+              - https
+              - ldaps
+            state: present
+            permanent: true
+          register: result
+          failed_when: result is failed or result is changed
+
         - name: Delete custom service
           firewall_lib:
             service: customservice
@@ -564,6 +586,9 @@
             destination:
               - 123.45.6.78
               - "aaaa:aaaa:aaaa:aaa:aaaa:aaaa:aaaa::"
+            includes:
+              - https
+              - ldaps
             permanent: true
             state: present
           register: result

tests/tests_service.yml

@@ -69,6 +69,9 @@
                 destination:
                   - 1.1.1.1
                   - 1::1
+                includes:
+                  - ssh
+                  - ldaps
                 permanent: true
                 state: present
 
@@ -88,6 +91,9 @@
                 destination:
                   - 1.1.1.1
                   - 1::1
+                includes:
+                  - ssh
+                  - ldaps
                 permanent: true
                 state: present
 
@@ -118,6 +124,9 @@
                   - 1::1
                 helper_module: ftp
                 protocol: icmp
+                includes:
+                  - ssh
+                  - ldaps
                 permanent: true
                 state: present
 
@@ -158,6 +167,9 @@
                   - 1::1
                 helper_module: ftp
                 protocol: icmp
+                includes:
+                  - ssh
+                  - ldaps
                 permanent: true
                 state: present
 
@@ -233,6 +245,9 @@
                   - 1::1
                 helper_module: ftp
                 protocol: icmp
+                includes:
+                  - ssh
+                  - ldaps
                 permanent: true
                 state: absent
 
@@ -256,6 +271,9 @@
                   - 1::1
                 helper_module: ftp
                 protocol: icmp
+                includes:
+                  - ssh
+                  - ldaps
                 permanent: true
                 state: absent