From afbff86eea47810f6c3fd962263847115f4f8ba5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Kundr=C3=A1t?= <jkt@jankundrat.com>
Date: Thu, 9 Mar 2023 23:16:19 +0100
Subject: [PATCH] docs: firewalld: use both `permanent` and `immediate`

While the docs quite clearly say what each of these options is doing,
defaults matter. I'm only using Ansible every now and then (and most of
the time it's for writing my CI playbooks for Zuul-CI, not for
configuring system services). I took a shortcut by looking at the
examples at the bottom of the doc page, and I almost wrote a loop with a
dictionary for enabling both HTTP and HTTPS services and making that
change immediate *and* permanent at the same time, while cursing about
those ****** who wrote a crappy module which -- apparently -- has to be
executed twice to do the sensible thing because everything is controlled
by a single boolean. Then I discovered the `immediate` parameter, and
realized that it is in fact controlled by a pair of booleans. Then I
consulted my other playbook which configures a system, not a CI job, and
discovered that I knew about these booleans back in 2019 when I used the
firewalld module for the last time. Maybe I am the ***** after all.

Since it's perfectly OK to set both variables to true, and since people
tend to want to use both in sync anyway (idempotent configurations and
what not), let's use that in the examples. Examples matter.
---
 docs/ansible.posix.firewalld_module.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/ansible.posix.firewalld_module.rst b/docs/ansible.posix.firewalld_module.rst
index ea58ff2..efc12d4 100644
--- a/docs/ansible.posix.firewalld_module.rst
+++ b/docs/ansible.posix.firewalld_module.rst
@@ -415,28 +415,33 @@ Examples
       ansible.posix.firewalld:
         service: https
         permanent: yes
+        immediate: yes
         state: enabled
 
     - name: do not permit traffic in default zone on port 8081/tcp
       ansible.posix.firewalld:
         port: 8081/tcp
         permanent: yes
+        immediate: yes
         state: disabled
 
     - ansible.posix.firewalld:
         port: 161-162/udp
         permanent: yes
+        immediate: yes
         state: enabled
 
     - ansible.posix.firewalld:
         zone: dmz
         service: http
         permanent: yes
+        immediate: yes
         state: enabled
 
     - ansible.posix.firewalld:
         rich_rule: rule service name="ftp" audit limit value="1/m" accept
         permanent: yes
+        immediate: yes
         state: enabled
 
     - ansible.posix.firewalld:
@@ -448,35 +453,41 @@ Examples
         zone: trusted
         interface: eth2
         permanent: yes
+        immediate: yes
         state: enabled
 
     - ansible.posix.firewalld:
         masquerade: yes
         state: enabled
         permanent: yes
+        immediate: yes
         zone: dmz
 
     - ansible.posix.firewalld:
         zone: custom
         state: present
         permanent: yes
+        immediate: yes
 
     - ansible.posix.firewalld:
         zone: drop
         state: enabled
         permanent: yes
+        immediate: yes
         icmp_block_inversion: yes
 
     - ansible.posix.firewalld:
         zone: drop
         state: enabled
         permanent: yes
+        immediate: yes
         icmp_block: echo-request
 
     - ansible.posix.firewalld:
         zone: internal
         state: present
         permanent: yes
+        immediate: yes
         target: ACCEPT
 
     - name: Redirect port 443 to 8443 with Rich Rule