Skip to content

Commit dcacf55

Browse files
BrennanPaciorekBrennanPaciorek
committed
Feature: Ansible facts with firewalld configuration
OVERVIEW - new module firewall_lib_facts.py - called by calling the firewall system role with either no parameters or with only the `detailed` parameter - fetches and returns ansible fact `firewall_config` - added ansible fact: firewall_config - holds firewalld's default settings, custom settings, and default zone at top level - detailed in README.md, under ansible_fact section - primary use case: make conditional changes based on firewalld's configuration state - new role parameter `detailed` (bool) - makes `default` firewall_config subdictionary mirror `custom` subdictionary structure README.md - details on ansible fact `firewall_config` structure - information on new role parameter `detailed` TESTING tests/tests_firewall_fact.yml - new test file, tests structure and accuracy of ansible fact Fixes #82 add warning for detailed size in readme
1 parent 4125be2 commit dcacf55

File tree

7 files changed

+561
-3
lines changed

7 files changed

+561
-3
lines changed

‎.sanity-ansible-ignore-2.12.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
plugins/modules/firewall_lib.py validate-modules:missing-gplv3-license
2+
plugins/modules/firewall_lib_facts.py validate-modules:missing-gplv3-license
23
plugins/modules/firewall_lib.py validate-modules:missing-examples
34
roles/firewall/files/get_files_checksums.sh shebang!skip

‎.sanity-ansible-ignore-2.9.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
plugins/modules/firewall_lib.py validate-modules:missing-gplv3-license
2+
plugins/modules/firewall_lib_facts.py validate-modules:missing-gplv3-license
23
plugins/modules/firewall_lib.py validate-modules:missing-examples
34
roles/firewall/files/get_files_checksums.sh shebang!skip

‎README.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,172 @@ WARNING: If the configuration failed or if the firewall configuration limits
2727
access to the machine in a bad way, it is most likely be needed to get
2828
physical access to the machine to fix the issue.
2929

30+
Ansible Facts
31+
-------------
32+
33+
## Gathering firewall ansible facts
34+
35+
To gather the firewall system role's ansible facts,
36+
call the system role with no arguments e.g.
37+
```yaml
38+
vars:
39+
firewall:
40+
```
41+
42+
Another option is to gather a more detailed version of the
43+
ansible facts by using the detailed argument e.g.
44+
```yaml
45+
vars:
46+
firewall:
47+
detailed: true
48+
```
49+
50+
```
51+
WARNING: `firewall_config` uses considerably more memory (+ ~165KB) when `detailed=True`.
52+
For reference, by default, `firewall_config` takes ~3KB when converted to a string.
53+
```
54+
55+
## Available ansible facts
56+
57+
### firewall_config
58+
59+
This ansible fact shows the permanent configuration of
60+
of firewalld on the managed node in dictionary format.
61+
The top level of the fact is made up of three keys:
62+
- `default`
63+
- `custom`
64+
- `default_zone`
65+
66+
Each dictionaries custom and default have the keys:
67+
- `zones`
68+
- `services`
69+
- `icmptypes`
70+
- `helpers`
71+
- `ipsets`
72+
- `policies` (if supported by remote host's firewalld installation)
73+
74+
Each of the keys contains a list of elements present in
75+
permanent configuration for each respective option.
76+
77+
`custom` will have a list of subdictionaries for each key,
78+
providing a more detailed description.
79+
80+
`default` will have only the names of each setting,
81+
unless the detailed option is supplied, in which case
82+
it will be structured in the same manner as custom.
83+
84+
`default_zone` contains the configured default zone
85+
for the managed node's firewalld installation. It
86+
is a string value.
87+
88+
JSON representation of the structure of firewall_config fact:
89+
```json
90+
{
91+
"default": {...},
92+
"custom": {...},
93+
"default_zone": "public",
94+
}
95+
```
96+
97+
#### default
98+
99+
The default subdictionary of firewall_config contains the default
100+
configuration for the managed node's firewalld configuration.
101+
This subdictionary only changes with changes to the managed node's
102+
firewalld installation.
103+
104+
default without detailed parameter set to true
105+
```json
106+
"default": {
107+
"zones": ["public",...],
108+
"services": ["amanda_client",...],
109+
"icmptypes": [...],
110+
"helpers": [...],
111+
"ipsets": [...],
112+
"policies": [...],
113+
}
114+
```
115+
116+
default when parameter set to true
117+
```json
118+
"default": {
119+
"zones": {
120+
"public": {
121+
...
122+
},
123+
...
124+
},
125+
"services": {
126+
"amanda_client":{
127+
...
128+
},
129+
...
130+
},
131+
"icmptypes": {
132+
...
133+
},
134+
"helpers": {
135+
...
136+
},
137+
"ipsets": {
138+
...
139+
},
140+
"policies": {
141+
...
142+
},
143+
}
144+
```
145+
146+
#### custom
147+
148+
The custom subdictionary contains any differences from the default
149+
firewalld configuration. This includes a repeat for a default
150+
element if that element has been modified in any way, and any new
151+
elements introduced in addition to the defaults.
152+
153+
This subdictionary will be modified by any changes to the
154+
firewalld installation done locally or remotely via the
155+
firewall system role.
156+
157+
If the managed nodes firewalld settings are not different from the defaults,
158+
the custom key and subdictionary will not be present in firewall_config.
159+
Additionally, if any of firewalld's settings have not changed from the default,
160+
there will not be a key-value pair for that setting in custom.
161+
162+
Below is the state of the custom subdictionary where at least one
163+
permanent change was made to each setting:
164+
```json
165+
"custom": {
166+
"zones": {
167+
"custom_zone": {
168+
...
169+
},
170+
...
171+
},
172+
"services": {
173+
"custom_service": {
174+
...
175+
},
176+
...
177+
},
178+
"icmptypes": {
179+
"custom": {
180+
...
181+
},
182+
...
183+
},
184+
"helpers": {
185+
...
186+
},
187+
"ipsets": {
188+
...
189+
},
190+
"policies": {
191+
...
192+
},
193+
}
194+
```
195+
30196
Variables
31197
---------
32198

0 commit comments

Comments
 (0)