firewalld
firewalld manages the services, ports, and rich rules of one firewalld
zone, through the node's firewall-cmd. firewalld is the usual
firewall on the Red Hat family. It groups network interfaces into zones,
and each zone admits named services (such as ssh, which stands for port
22), ports, and sources.
Two other modules handle the rest of firewalld:
firewalld_zone_membership chooses which
interfaces and source networks use a zone, and
firewalld_zone creates or removes a zone. On Debian
and Ubuntu, the usual firewall is ufw; use ufw there.
Set up
Install firewalld and start it:
- dnf_package:
packages:
- {name: firewalld, version: newest_when_first_installed}
- systemd_service:
name: firewalld
start_at_boot: true
state: running
Whether firewalld runs is a systemd_service task, because firewalld is an
ordinary systemd service. If firewalld is not installed or not running,
dryrun reports the firewalld node task not checked, because an earlier
node task may install or start it, and a run fails.
Inputs
zone(string; required): the zone, such as public; MMX never guesses it; whether firewalld runs is a systemd_service taskrules(list of mappings; required): each {action: allow|reject|drop, firewalld_service: a service name firewalld knows, such as ssh, or port: number or first:last with protocol: tcp|udp, from: address or network}; a rule needs firewalld_service, port, or from, and one with only from admits everything from there; from_inventory_group: {group, address_var} in place of from, as on ufw; an allow rule with only firewalld_service or port becomes that service or port of the zone, every other rule a rich rule; identity is firewalld_service or port, protocol, and fromrules_not_listed(removeorkeep; required): remove makes rules the complete set of services, ports, and rich rules; the zone target is unchanged and may admit additional traffic, such as with ACCEPT; the SSH safeguard refuses a change to rules: [] on every zone, including one without SSH traffic; keep adds what is missing; interfaces, sources, and other zones stay unchanged; omit with absentstate(presentorabsent; defaultpresent): absent removes the listed rules whatever their action; accepts only zone and rules
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangevalue.addedvalue.removed
What a dryrun reports
Supported; lists rules to add or remove in firewalld's own syntax; refuses a change after which the zone no longer admits sshd's port through a port or firewalld_service rule, or rejects or drops it for every source.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Allow SSH, MMX's HTTPS port, HTTPS, and a database port
- firewalld:
zone: public
rules:
- {action: allow, firewalld_service: ssh}
- {action: allow, port: 7443, protocol: tcp}
- {action: allow, firewalld_service: https}
- {action: allow, port: 5432, protocol: tcp, from: 10.0.0.0/8}
rules_not_listed: remove
zone is required; MMX never guesses the zone. Allow the node HTTPS API
port (7443 by default): a fresh Red Hat family server blocks it, and MMX
then continues over SSH and says so. MMX never opens that port itself.
The first three rules become services and a port of zone public. The
fourth has a source, so MMX writes it as a rich rule:
rule family="ipv4" source address="10.0.0.0/8" port port="5432" protocol="tcp" accept
One rule for each node of an inventory group
from_inventory_group in place of from stands for one rule for each node
of an inventory group, as on ufw. The ufw page's example
One rule for each node of an inventory group
shows the inventory, and its section
Rules for an inventory group says
what MMX checks. With rules_not_listed: remove, the task holds the whole
rule set, so a node that leaves the group loses its rule on the next run,
and a node that joins gets one.
How it works
Rules
Each rule has action (allow, reject, or drop); exactly one of
firewalld_service or port with a required protocol (tcp or udp),
or neither when the rule has only a source; and an optional from or
from_inventory_group. firewalld_service is a service name firewalld
knows, such as ssh: firewalld's own list of ports, not a systemd service.
zone, firewalld_service, port, and from may be references.
MMX writes each rule in firewalld's own form. An allow rule with only a
service or a port becomes that service or port of the zone. Every other rule
becomes a rich rule, firewalld's name for a rule with a source or an action
other than accept.
A rule's identity is its service or port, protocol, and source; listing it
with another action replaces it. rules_not_listed is required: remove
makes the listed rules the complete set of services, ports, and rich rules,
and keep adds what is missing. The list is not everything the zone admits:
for example, a zone with target ACCEPT also admits traffic outside the
listed rules. The zone's interfaces and
sources, its target, and other zones are left alone. state: absent takes
zone and rules and removes those rules whatever their action.
Both layers, without a reload
firewalld keeps two layers: the running firewall and the stored
configuration that it loads on a restart or reload. Each change goes to the
running firewall and to the stored configuration together, one rule at a
time, so nothing is lost at a reboot, and firewalld is never reloaded as a
whole. A rule found in only one of the two is written to the other. MMX
then inspects the zone again and fails the node task if a difference
remains. Dryrun and results list the rules to add or remove in
.this_node_task.value.added and .removed, as service ssh,
port 7443/tcp, or the rich rule's text. A run that fails lists only the
rules that a firewall-cmd call added or removed before the failure, so a
node task in on_failure can read what happened.
The SSH safeguard
The safeguard applies to every zone, including a zone without SSH traffic.
In particular, a change to rules: [] with rules_not_listed: remove is
refused on every zone. An already empty zone is unchanged and needs no
safeguard check. Before a change, MMX checks that the zone, running and stored, still admits
a TCP port sshd listens on (from sshd -T), through a port rule or through
a firewalld service whose definition holds that port, also when the rule
admits only one network. A rule that admits a source on every port does not
count, so list the SSH port. firewalld applies reject and drop rules
before services and ports, so a reject or drop rule for that port or
service without from would block SSH whatever allows it; one limited to
an address with from blocks only that address and is allowed. Otherwise
the node task fails before changing anything, in dryrun too.
Errors and what they mean
| What fails | What it means, and what to do |
|---|---|
The node task fails before any change, in dryrun too, because the zone would no longer admit sshd's TCP port, such as no longer admit sshd's TCP port 22 |
After the change, no port or firewalld_service rule of the zone would admit SSH, or a reject or drop rule without from would block it. List the SSH port or the ssh service; see The SSH safeguard. |
| The node task fails after its changes | The zone, inspected again in both layers, still differs from the task. |
| A run fails, or a dryrun reports the node task not checked, because firewalld is missing or stopped | Install and start firewalld in earlier node tasks; see Set up. |
A run reports connection_used: ssh_fallback and names the firewall |
The zone blocks port 7443. Add a rule for it; MMX never adds one itself. |
Tested on
Distributions: Rocky Linux 9, AlmaLinux 10, Fedora 45.
The suite tests/integration/firewalld_and_selinux.py tests the module on
the Red Hat family: Rocky Linux 9, AlmaLinux 10, and Fedora 45. It works in a zone of
its own that no network interface or source uses, so no rule it writes can
reach the test harness's SSH connection. The
validation record gives the latest results; the
firewalld versions it records for the zone modules are 1.3.4 on Rocky
Linux 9 and 2.4.3 on AlmaLinux 10.
Why it works this way
-
The rule list leaves the zone target alone. A zone's target is a separate firewalld setting. Owning services, ports, and rich rules does not replace it.
-
One rule at a time in both layers, never a reload. A reload of firewalld as a whole would drop every rule for a moment. Creating and removing zones, which needs a reload, is the separate module
firewalld_zone, so this module keeps its promise never to reload firewalld. -
The field is
firewalld_service, notservice. In MMX a bare "service" is a systemd service. -
The rule fields are ufw's wherever firewalld has the same thing. The module carries no ufw syntax, and
ufwcarries no fields for firewalld. Why there are two modules, and not one for both firewalls, is on theufwpage. -
MMX never opens port 7443 by itself. A firewall change the project did not write is a surprise; the run says which rule to add, as A blocked port 7443 is reported, never opened describes.
-
A rule for each node of a group is
from_inventory_groupinside a task withrules_not_listed: remove, not a loop that adds one rule per node. A loop cannot remove the rule of a node that left the inventory; a task that holds the whole set can.
This page is docs/reference/modules/firewalld.md in the MMX repository.