Architecting Network Security with ansible.posix.firewalld: An Exhaustive Guide to Declarative Firewall Management

Published by TechMarmot Editorail Staff on | Category Ansible

The management of network security in enterprise Linux environments requires a transition from manual, error-prone command-line interventions to a declarative, version-controlled infrastructure. Within the Red Hat ecosystem—specifically Red Hat Enterprise Linux (RHEL), CentOS, and Fedora—firewalld serves as the primary dynamic firewall manager. Unlike the simpler, rule-based logic found in tools like UFW (Uncomplicated Firewall), firewalld employs a sophisticated zone-based architecture. To automate this complexity at scale, the ansible.posix.firewalld module provides a robust interface for managing zones, services, ports, and rich rules. By treating firewall configurations as code, organizations can ensure consistency across thousands of nodes, facilitate peer-reviewed security changes, and implement rapid recovery through automated rollbacks.

The Architecture of firewalld and the Role of Zones

The fundamental design philosophy of firewalld centers on the concept of zones. A zone is a predefined set of rules that determine the trust level of a network connection. Every network interface or source IP address is assigned to a specific zone, and the rules associated with that zone dictate whether traffic is permitted or denied.

The following table outlines the standard trust levels provided by firewalld:

Zone Trust Level Common Use Case Default Behavior
public Low Untrusted networks (Internet) Default zone; restricts most traffic
internal Medium Trusted internal LANs Higher trust for internal communication
dmz Medium-Low Demilitarized Zones (Public facing servers) Isolated from internal network
trusted High Fully trusted environments Accepts all incoming traffic
drop Zero High-security/Untrusted zones Silently drops all incoming packets

From a technical perspective, the ansible.posix.firewalld module interacts with these zones to define the security perimeter. For a user, this means they no longer need to manually track which interface (e.g., eth0 or eth1) corresponds to which security policy. Instead, they can assign an interface to a zone and then apply a set of services to that zone. This abstraction prevents the common mistake of applying a broad "allow all" rule to a public interface when only a specific internal interface required such access.

Prerequisites and Environmental Requirements

Before deploying the ansible.posix.firewalld module, specific system and software dependencies must be met to ensure the module can communicate with the system's firewall daemon.

  • Ansible Version: The environment must run Ansible 2.9 or higher.
  • Collection: The ansible.posix collection must be installed on the control node.
  • Target OS: The managed nodes must be RHEL, CentOS, Fedora, or other derivatives that utilize firewalld.
  • Privileges: Root or sudo access is mandatory on target machines, as modifying firewall rules requires administrative privileges.
  • Software Dependencies: The module requires the Python bindings for firewalld. Specifically, python-firewall or python3-firewall (version 0.9.0 or higher) must be installed. These are typically provided as part of the standard firewalld package from the OS distributor.
  • Daemon Version: firewalld version 0.9.0 or higher is required on the managed node.

The requirement for python-firewall is critical because the Ansible module does not simply wrap shell commands; it utilizes these Python libraries to interact directly with the firewalld API, ensuring a more reliable and predictable state management process.

Comprehensive Module Parameter Analysis

The ansible.posix.firewalld module is designed to be declarative. Rather than telling the system to "add a rule," the developer defines the "desired state" of the firewall.

State and Persistence Management

One of the most critical aspects of firewalld is the distinction between the running configuration and the permanent configuration.

  • state: This parameter defines the desired condition of the rule. Possible values include enabled, disabled, or present (specifically for zones). For example, setting state: enabled for a service ensures that the service is allowed through the firewall.
  • permanent: When set to true, the rule is written to the permanent configuration file on disk. This ensures that the rule survives a system reboot or a firewall reload.
  • immediate: When set to true, the rule is applied to the currently running firewall configuration instantly.

The operational impact of these flags is significant. If a user sets permanent: true but omits immediate: true, the rule is written to disk but will not take effect until the firewall is manually reloaded or the system is rebooted. Conversely, setting immediate: true without permanent: true results in a rule that works now but vanishes after a reboot. Therefore, the expert recommendation is to always use both permanent: true and immediate: true together to ensure consistency between the active session and the persistent storage.

Service and Port Control

The module allows for the opening of traffic based on either pre-defined services or specific port numbers.

  • service: This allows the use of named services (e.g., http, https, ssh). These services are defined in XML files on the system and map to specific ports and protocols.
  • port: This allows for the specification of a custom port and protocol, formatted as port/protocol (e.g., 8080/tcp or 161-162/udp).

Using services is generally preferred for standard applications because it enhances readability and leverages the OS's built-in service definitions. However, for proprietary applications or non-standard ports, the port parameter provides the necessary granularity.

Advanced Zone and Interface Configuration

Beyond simple port opening, the module can manage the very structure of the firewall's zones and how hardware interfaces are mapped to them.

  • zone: Specifies the zone to which the rule applies. If omitted, the default zone is used.
  • interface: Used to assign a specific network interface (e.g., eth2) to a zone.
  • target: Sets the default action for a zone, such as ACCEPT or REJECT.
  • masquerade: A boolean value that enables IP masquerading (NAT) within a specific zone, which is essential for gateways or DMZ servers.
  • forward: A boolean value that enables packet forwarding within a zone.

For example, assigning eth2 to the trusted zone ensures that all traffic arriving on that physical interface is treated with maximum trust. This is a powerful architectural tool for separating management traffic from public-facing application traffic.

Rich Rules and Complex Logic

When simple service or port declarations are insufficient, the rich_rule parameter allows for the implementation of complex logic, including source-based filtering, rate limiting, and port redirection.

Rich rules provide the ability to specify:
- Source IP addresses or networks (e.g., 192.0.2.0/24).
- Action based on the source (e.g., accept, reject, drop).
- Rate limiting using the audit limit parameter.
- Port forwarding and redirection.

The technical impact of rich rules is that they allow for "exception-based" security. For instance, while a zone might generally block all traffic, a rich rule can permit access specifically for one trusted administrative subnet.

Implementation Patterns and Code Examples

The following examples demonstrate the practical application of the ansible.posix.firewalld module across various scenarios.

Basic Web Server Configuration

This pattern ensures the firewall is installed and configured for standard web traffic.

```yaml
- name: Configure firewalld for web server
hosts: webservers
become: true
tasks:
- name: Ensure firewalld is installed and running
ansible.builtin.yum:
name: firewalld
state: present

- name: Start and enable firewalld
  ansible.builtin.service:
    name: firewalld
    state: started
    enabled: true

- name: Allow HTTP service permanently
  ansible.posix.firewalld:
    service: http
    permanent: true
    immediate: true
    state: enabled

- name: Allow HTTPS service permanently
  ansible.posix.firewalld:
    service: https
    permanent: true
    immediate: true
    state: enabled

- name: Allow custom application port
  ansible.posix.firewalld:
    port: 8080/tcp
    permanent: true
    immediate: true
    state: enabled

```

Advanced Zone and Interface Management

This configuration demonstrates how to isolate interfaces and manage zone-specific behaviors like masquerading.

```yaml
- name: Assign eth2 interface to trusted zone
ansible.posix.firewalld:
zone: trusted
interface: eth2
permanent: true
state: enabled

  • name: Enable masquerade in dmz zone
    ansible.posix.firewalld:
    masquerade: true
    state: enabled
    permanent: true
    zone: dmz

  • name: Enable forwarding in internal zone
    ansible.posix.firewalld:
    forward: true
    state: enabled
    permanent: true
    zone: internal

  • name: Create custom zone if not already present
    ansible.posix.firewalld:
    zone: custom
    state: present
    permanent: true
    ```

Complex Traffic Control with Rich Rules

Rich rules allow for granular control over who can access specific services and how they do so.

```yaml
- name: Enable FTP service with rate limiting using firewalld rich rule
ansible.posix.firewalld:
rich_rule: 'rule service name="ftp" audit limit value="1/m" accept'
permanent: true
state: enabled

  • name: Allow traffic from 192.0.2.0/24 in internal zone
    ansible.posix.firewalld:
    source: 192.0.2.0/24
    zone: internal
    state: enabled

  • name: Redirect port 443 to 8443 with Rich Rule
    ansible.posix.firewalld:
    rich_rule: 'rule family=ipv4 forward-port port=443 protocol=tcp to-port=8443'
    zone: public
    permanent: true
    immediate: true
    state: enabled
    ```

ICMP Management and Security Hardening

For high-security environments, managing ICMP (ping) traffic is essential to prevent network discovery and certain types of DoS attacks.

```yaml
- name: Block ICMP echo requests in drop zone
ansible.posix.firewalld:
zone: drop
state: enabled
permanent: true
icmp_block: echo-request

  • name: Enable ICMP block inversion in drop zone
    ansible.posix.firewalld:
    zone: drop
    state: enabled
    permanent: true
    icmpblockinversion: true
    ```

Dynamic Configuration with Loops and Variables

In production environments, hard-coding rules is discouraged. Instead, administrators should use variables to map interfaces and services to zones.

```yaml
- name: Assign interfaces to zones
ansible.posix.firewalld:
zone: "{{ item.zone }}"
interface: "{{ item.interface }}"
permanent: yes
immediate: yes
state: enabled
loop: "{{ firewalldinterfacezones | default([]) }}"
when: item.interface in ansible_interfaces

  • name: Configure zone services
    ansible.posix.firewalld:
    service: "{{ item.1 }}"
    zone: "{{ item.0.name }}"
    permanent: yes
    immediate: yes
    state: enabled
    loop: "{{ firewalldzones | subelements('services', skipmissing=True) }}"
    when: item.1 is defined

  • name: Configure zone ports
    ansible.posix.firewalld:
    port: "{{ item.1.port }}/{{ item.1.protocol }}"
    zone: "{{ item.0.name }}"
    permanent: yes
    immediate: yes
    state: enabled
    loop: "{{ firewalldzones | subelements('ports', skipmissing=True) }}"
    when: item.1 is defined
    ```

This approach creates a flexible system where the security policy is decoupled from the playbook logic. By modifying a simple YAML variable file, an administrator can change the security posture of an entire data center without altering the underlying Ansible code.

Technical Deep Dive: The Python Interaction Layer

The ansible.posix.firewalld module relies on a structured transaction system to ensure that changes are applied atomically. Internally, the module uses a FirewallTransaction class to handle the state of the firewall.

For example, when managing ICMP blocks, the module employs an IcmpBlockTransaction class. This class handles the logic of checking whether a block is currently enabled in the immediate runtime (get_enabled_immediate) versus the permanent configuration (get_enabled_permanent). If a discrepancy is found, the module executes the necessary addIcmpBlock or remove commands via the firewall.client library to align the system with the desired state defined in the Ansible task.

This level of abstraction is what prevents "flapping" in configuration management—where a tool constantly tries to change a setting that is being overwritten by another process. The module first queries the current state and only performs an action if the state differs from the target.

Operational Considerations and Best Practices

When implementing firewalld via Ansible, several operational nuances must be considered to avoid accidental lockouts or configuration drift.

  • Immediate Access to New Zones: If a new zone is created, it is recommended to reload firewalld immediately after the zone creation returns a "changed" state. This ensures that any subsequent immediate actions performed on that zone are recognized by the daemon.
  • Offline Mode: The offline parameter can be used to modify the permanent configuration without affecting the running firewall. This is useful for staging changes that will be applied during a scheduled maintenance window.
  • Order of Operations: Always ensure the firewalld service is started and enabled before attempting to apply rules. Applying rules to a stopped daemon may result in errors or inconsistent states.
  • Validation: Use the register keyword in Ansible to capture the result of firewall changes and use changed_when logic to identify when a configuration has actually shifted, rather than just being reapplied.

Conclusion

The ansible.posix.firewalld module transforms firewall management from a manual, error-prone task into a precise engineering discipline. By utilizing the zone-based architecture of firewalld, administrators can implement a tiered security model that separates public, internal, and DMZ traffic with absolute clarity. The ability to combine permanent and immediate flags ensures that security policies are both instantly effective and persistent across reboots. Furthermore, the integration of rich rules allows for complex requirements—such as rate-limiting and port redirection—to be codified and versioned. When coupled with dynamic loops and variable-driven configurations, ansible.posix.firewalld provides a scalable framework for maintaining a rigorous security posture across any number of RHEL-based systems, ensuring that the network perimeter is always defined by the desired state of the code.

Sources

  1. OneUptime: Ansible Configure Firewall Rules firewalld
  2. GitHub: ansible.posix firewalld module source
  3. OneUptime: Ansible Configure firewalld

Related Posts