firewalld - Manage arbitrary ports/services with firewalld¶

New in version 1.4.

Synopsis
- Requirements
Parameters
Notes
Examples
Status
Maintenance
- Author

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 below requirements are needed on the host that executes this module.

firewalld >= 0.2.11

Parameters ¶

Parameter	Choices/Defaults	Comments
immediate bool (added in 1.9)	Choices: no ← yes	Should this configuration be applied immediately, if set as permanent
interface (added in 2.1)		The interface you would like to add/remove to/from a zone in firewalld
masquerade (added in 2.1)		The masquerade setting you would like to enable/disable to/from zones within firewalld
permanent		Should this configuration be in the running firewalld configuration or persist across reboots. As of Ansible version 2.3, permanent operations can operate on firewalld configs when it's not running (requires firewalld >= 3.0.9). (NOTE: If this is false, immediate is assumed true.)
port		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.
rich_rule		Rich rule to add/remove to/from firewalld.
service		Name of a service to add/remove to/from firewalld - service must be listed in output of firewall-cmd --get-services.
source (added in 2.0)		The source/network you would like to add/remove to/from firewalld
state required	Choices: enabled disabled present absent	Enable or disable a setting. For ports: Should this port accept(enabled) or reject(disabled) connections. The states "present" and "absent" can only be used in zone level operations (i.e. when no other parameters but zone and state are set).
timeout	Default: 0	The amount of time the rule should be in effect for when non-permanent.
zone	Choices: work drop internal external trusted home dmz public block Default: "system-default(public)"	The firewalld zone to add/remove to/from (NOTE: default zone can be configured per system but "public" is default from upstream. Available choices can be extended based on per-system configs, listed here are "out of the box" defaults).

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. Therefor, 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.

Examples ¶

- firewalld:
    service: https
    permanent: true
    state: enabled

- firewalld:
    port: 8081/tcp
    permanent: true
    state: disabled

- firewalld:
    port: 161-162/udp
    permanent: true
    state: enabled

- firewalld:
    zone: dmz
    service: http
    permanent: true
    state: enabled

- firewalld:
    rich_rule: 'rule service name="ftp" audit limit value="1/m" accept'
    permanent: true
    state: enabled

- firewalld:
    source: 192.0.2.0/24
    zone: internal
    state: enabled

- firewalld:
    zone: trusted
    interface: eth2
    permanent: true
    state: enabled

- firewalld:
    masquerade: yes
    state: enabled
    permanent: true
    zone: dmz

- firewalld:
    zone: custom
    state: present
    permanent: true

- name: Redirect port 443 to 8443 with Rich Rule
  firewalld:
    rich_rule: rule family={{ item }} forward-port port=443 protocol=tcp to-port=8443
    zone:      public
    permanent: true
    immediate: true
    state:     enabled
  with_items:
    - ipv4
    - ipv6

Status ¶

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance ¶

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author ¶

Adam Miller (@maxamillion)

Hint

If you notice any issues in this documentation you can edit this document to improve it.