firewalld_zone
firewalld_zone creates or removes one firewalld zone on a node, through
the node's firewall-cmd. A firewalld zone is a set of firewall rules; its
members are the network interfaces and source networks whose traffic uses
those rules. This module manages the zone itself. The
firewalld module manages the rules of a zone, and
firewalld_zone_membership manages its
members.
Firewalld keeps two layers: the running firewall and the stored configuration that it loads on a restart or reload. Firewalld has no command that creates a running zone without reloading, so this module reloads firewalld when the running firewall lacks the zone. A reload replaces every zone's running configuration with its stored configuration. Settings that existed only in the running firewall are dropped. Stored settings that were not running become active.
Set up
Install firewalld with dnf_package and start it with systemd_service, as
the firewalld page shows.
Inputs
zone(string; required): The name of the firewalld zone.state(presentorabsent; defaultpresent): Present creates the zone in stored configuration if missing. The task reloads firewalld if the running zone is missing. Absent refuses a zone with members in the running firewall or stored configuration. Otherwise, it deletes the stored zone and reloads firewalld. Firewalld can refuse deletion of a built-in zone.
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.
statuschangereason
What a dryrun reports
Report the proposed creation or removal and whether firewalld would reload. A reload would replace running settings with stored settings in every zone.
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
Create a zone
fleet_stages:
- id: create_application_firewall_zone
nodes: web01
node_tasks:
- firewalld_zone:
zone: appzone
state: present
If the stored configuration lacks the zone, MMX creates it there. If the running firewall lacks it, MMX reloads firewalld. The result explains when a reload happened. Dryrun explains when one would happen. Review the differences between the two layers before running the task. An unchanged task does not reload.
Remove a zone
- firewalld_zone:
zone: appzone
state: absent
The module refuses while the zone has any interface or source in either
layer, naming the members. Remove IP sources and interfaces with
firewalld_zone_membership first. Remove unsupported MAC address or ipset
sources with firewalld. Then MMX deletes the stored zone and reloads.
How it works
zone is required, and state is present (the default) or absent.
For present, MMX creates missing stored configuration with
firewall-cmd --permanent --new-zone=<name>. When the running zone is
missing, it runs firewall-cmd --reload, then checks both layers. If only
the stored zone was missing, no reload is needed. An unchanged task does
nothing.
For absent, MMX refuses any interface or source in either layer, naming
the members and firewalld_zone_membership. Source kinds that
firewalld_zone_membership does not support need firewalld's own commands.
With no members, MMX deletes an existing stored zone with
firewall-cmd --permanent --delete-zone=<name> and reloads if either layer
had the zone.
Zone creation and removal use no reachability confirmation. An empty zone handles no traffic. The global reload still has the effects above.
While a membership restore or cleanup of
firewalld_zone_membership
remains owed on the node, this module refuses: its reload could disturb
that recovery.
Errors and what they mean
| What fails | What it means, and what to do |
|---|---|
Removal is refused, naming the zone's members and firewalld_zone_membership |
The zone still has an interface or a source in the running firewall or the stored configuration. Remove IP sources and interfaces with firewalld_zone_membership, and MAC address or ipset sources with firewalld, then run again. |
| firewalld's own message about a built-in zone | firewalld refuses to delete a built-in zone. MMX reports firewalld's own words. |
| The task is refused while a membership restore is owed | A firewalld_zone_membership change on this node still owes a restore or cleanup. Resolve it first, as that page says. |
Tested on
Distributions: Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/firewalld_zone_memberships.py also covers
this module: dryrun, creation in the stored configuration and in the
running firewall, the reload (a port that another zone had at runtime only
is gone), an unchanged rerun, the refusal to remove a zone that has a
member, and removal. It passes on Rocky Linux 9 (firewalld 1.3.4) and
AlmaLinux 10 (2.4.3). The
validation record gives
the latest results.
Why it works this way
-
zonenames the zone in all three firewalld modules. One spelling makes the target clear when tasks create a zone, set its rules, and add members. -
A separate module for zones. Creating a running zone needs a reload, and keeping that in its own module preserves the promise of the
firewalldrules module never to reload firewalld. -
No reachability confirmation. An empty zone has no traffic assigned, although the global reload can change other zones. The module description, the result reason, and dryrun all explain that effect.
-
No reload while a membership restore is owed. The reload could disturb that recovery.
This page is docs/reference/modules/firewalld_zone.md in the MMX repository.