firewalld¶

Collection Note

This module is part of the ansible.posix collection. To install the collection, use:

ansible-galaxy collection install ansible.posix

You need further requirements to be able to use this module, see the Requirements section for details.

Synopsis¶

This module allows for addition or deletion of services and ports (either TCP or UDP) in either running or permanent firewalld rules.

Requirements¶

The following Python packages are needed on the host that executes this module:

Parameters¶

Parameter	Defaults / Choices	Comments
forward bool		The forward setting you would like to enable/disable to/from zones within firewalld. This option only is supported by firewalld v0.9.0 or later. Note that the option type is changed to bool in ansible.posix version 2.0.0 and later.
icmp_block str		The ICMP block you would like to add/remove to/from a zone in firewalld.
icmp_block_inversion bool		Enable/Disable inversion of ICMP blocks for a zone in firewalld. Note that the option type is changed to bool in ansible.posix version 2.0.0 and later.
immediate bool		Whether to apply this change to the runtime firewalld configuration. Defaults to V(true) if O(permanent=false).
interface str		The interface you would like to add/remove to/from a zone in firewalld.
masquerade bool		The masquerade setting you would like to enable/disable to/from zones within firewalld. Note that the option type is changed to bool in ansible.posix version 2.0.0 and later.
offline bool		Ignores O(immediate) if O(permanent=true) and firewalld is not running.
permanent bool		Whether to apply this change to the permanent firewalld configuration. As of Ansible 2.3, permanent operations can operate on firewalld configs when it is not running (requires firewalld >= 0.3.9). Note that if this is V(false), O(immediate=true) by default.
port str		Name of a port or port range to add/remove to/from firewalld. Must be in the form PORT/PROTOCOL or PORT-PORT/PROTOCOL for port ranges.
port_forward list / elements=dict		Port and protocol to forward using firewalld.
port_forward.port		Source port to forward from.
port_forward.proto	Choices: udp, tcp	protocol to forward.
port_forward.toaddr		Optional address to forward to.
port_forward.toport		destination port.
protocol str		Name of a protocol to add/remove to/from firewalld.
rich_rule str		Rich rule to add/remove to/from firewalld. See L(Syntax for firewalld rich language rules,https://firewalld.org/documentation/man-pages/firewalld.richlanguage.html).
service str		Name of a service to add/remove to/from firewalld. The service must be listed in output of C(firewall-cmd --get-services).
source str		The source/network you would like to add/remove to/from firewalld.
state str required	Choices: absent, disabled, enabled, present	Enable or disable a setting. For ports: Should this port accept (V(enabled)) or reject (V(disabled)) connections. The states V(present) and V(absent) can only be used in zone level operations (i.e. when no other parameters but zone and state are set).
target str	Choices: default, ACCEPT, DROP, %%REJECT%%	firewalld Zone target. If O(state=absent), this will reset the target to default. Version Added: 1.2.0
timeout int		The amount of time in seconds the rule should be in effect for when non-permanent.
zone str		The firewalld zone to add/remove to/from. Note that the default zone can be configured per system but V(public) is default from upstream. Available choices can be extended based on per-system configs, listed here are "out of the box" defaults. Possible values include V(block), V(dmz), V(drop), V(external), V(home), V(internal), V(public), V(trusted), V(work).

Notes¶

Note

Not tested on any Debian based system.
Requires the python2 bindings of firewalld, which may not be installed by default.
For distributions where the python2 firewalld bindings are unavailable (e.g Fedora 28 and later) you will have to set the ansible_python_interpreter for these hosts to the python3 interpreter path and install the python3 bindings.
Zone transactions (creating, deleting) can be performed by using only the zone and state parameters "present" or "absent". Note that zone transactions must explicitly be permanent. This is a limitation in firewalld. This also means that you will have to reload firewalld after adding a zone that you wish to perform immediate actions on. The module will not take care of this for you implicitly because that would undo any previously performed immediate actions which were not permanent. Therefore, if you require immediate access to a newly created zone it is recommended you reload firewalld immediately after the zone creation returns with a changed state and before you perform any other immediate, non-permanent actions on that zone.
This module needs C(python-firewall) or C(python3-firewall) on managed nodes. It is usually provided as a subset with C(firewalld) from the OS distributor for the OS default Python interpreter.

Examples¶

- name: Permanently enable https service, also enable it immediately if possible
  ansible.posix.firewalld:
    service: https
    state: enabled
    permanent: true
    immediate: true
    offline: true

- name: Permit traffic in default zone for https service
  ansible.posix.firewalld:
    service: https
    permanent: true
    state: enabled

- name: Permit ospf traffic
  ansible.posix.firewalld:
    protocol: ospf
    permanent: true
    state: enabled

- name: Do not permit traffic in default zone on port 8081/tcp
  ansible.posix.firewalld:
    port: 8081/tcp
    permanent: true
    state: disabled

- name: Permit traffic in default zone on port 161-162/ucp
  ansible.posix.firewalld:
    port: 161-162/udp
    permanent: true
    state: enabled

- name: Permit traffic in dmz zone on http service
  ansible.posix.firewalld:
    zone: dmz
    service: http
    permanent: true
    state: enabled

- 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: Assign eth2 interface to trusted zone
  ansible.posix.firewalld:
    zone: trusted
    interface: eth2
    permanent: true
    state: enabled

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

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

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

- name: Enable ICMP block inversion in drop zone
  ansible.posix.firewalld:
    zone: drop
    state: enabled
    permanent: true
    icmp_block_inversion: true

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

- name: Set internal zone target to ACCEPT
  ansible.posix.firewalld:
    zone: internal
    state: present
    permanent: true
    target: ACCEPT

- 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

Authors¶

Adam Miller (@maxamillion)