firewalld module

FirewalldDefaultZone

The zone connections and interfaces without an explicit binding land in.

Commands:

firewall-cmd --get-default-zone 2> /dev/null || sudo -n firewall-cmd --get-default-zone 2> /dev/null || true

Returns:

str

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_firewalld_default_zone.py.

FirewalldIpSet

Attributes:

Name	Type	Description
type		The ipset type (hash:ip, hash:net, hash:ip,port, ...), "" when the info block carried none.
options		The set options keyed by name ({"maxelem": "65536", "family": "inet"}); the family (inet/inet6) is an option on modern daemons, {} when none are set.
entries		The member addresses/networks, exactly as firewall-cmd prints them.

FirewalldIpSets

Every firewalld ipset container, its options and its member entries.

Commands:

sh -c 'for s in $(firewall-cmd <permanent>--get-ipsets 2> /dev/null || sudo -n firewall-cmd <permanent>--get-ipsets 2> /dev/null || true); do echo "ipset: $s"; firewall-cmd <permanent>--info-ipset "$s" 2> /dev/null || sudo -n firewall-cmd <permanent>--info-ipset "$s" 2> /dev/null || true; done'

Returns:

dict[str, FirewalldIpSet]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_firewalld_ipsets.py.

FirewalldPolicies

Every firewalld policy and its ingress/egress zone pairing.

Commands:

sh -c 'for s in $(firewall-cmd <permanent>--get-policies 2> /dev/null || sudo -n firewall-cmd <permanent>--get-policies 2> /dev/null || true); do echo "policy: $s"; firewall-cmd <permanent>--info-policy "$s" 2> /dev/null || sudo -n firewall-cmd <permanent>--info-policy "$s" 2> /dev/null || true; done'

Returns:

dict[str, FirewalldPolicy]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_firewalld_policies.py.

FirewalldPolicy

Attributes:

Name	Type	Description
target		The policy's default verdict (CONTINUE, ACCEPT, DROP or REJECT); CONTINUE when unset.
ingress_zones		The zones traffic enters the policy from (ANY/HOST are the special catch-alls).
egress_zones		The zones traffic leaves the policy toward.
services		The service names allowed by the policy.
ports		The port openings the policy allows.
protocols		The protocols the policy allows outright.
forward_ports		The policy's port-forwarding rules.
masquerade		Whether the policy masquerades matching traffic.
rich_rules		The policy's rich-language rule strings.

FirewalldService

Attributes:

Name	Type	Description
short		The service's short display name (e.g. WWW (HTTP)), "" when unset.
description		The service's description text, "" when unset.
ports		The destination port openings the service bundles (80/tcp).
source_ports		The source port openings the service bundles.
protocols		The protocols the service allows outright.
modules		The netfilter connection-tracking helper modules the service loads (e.g. nf_conntrack_ftp).
destination		The destination address limits keyed by family ({"ipv4": "192.168.1.0/24", "ipv6": "::1"}), {} when the service is not destination-limited.

FirewalldServices

Every firewalld service definition and the ports/protocols it bundles.

Commands:

sh -c 'for s in $(firewall-cmd --permanent --get-services 2> /dev/null || sudo -n firewall-cmd --permanent --get-services 2> /dev/null || true); do echo "service: $s"; firewall-cmd --permanent --info-service "$s" 2> /dev/null || sudo -n firewall-cmd --permanent --info-service "$s" 2> /dev/null || true; done'

Returns:

dict[str, FirewalldService]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_firewalld_services.py.

FirewalldStatus

Whether the firewalld daemon is running, and its version.

Commands:

sh -c 'echo "state: $(firewall-cmd --state 2> /dev/null || sudo -n firewall-cmd --state 2> /dev/null || true)"; echo "version: $(firewall-cmd --version 2> /dev/null || sudo -n firewall-cmd --version 2> /dev/null || true)"'

Returns:

FirewalldStatusInfo

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_firewalld_status.py.

FirewalldStatusInfo

Attributes:

Name	Type	Description
running		Whether the daemon answered running to firewall-cmd --state; False for a stopped daemon, a missing binary or an unprivileged read.
version		The daemon release string (e.g. 2.1.1), "" when firewall-cmd --version printed nothing.

FirewalldZone

Attributes:

Name	Type	Description
active		Whether the runtime listing marked the zone (active) (it has interfaces or sources bound); always False in a permanent listing, which carries no activity marker.
target		The zone's default verdict (default, ACCEPT, DROP or REJECT); default when unset.
short		The zone's short display name, "" when unset.
description		The zone's description text, "" when unset.
icmp_block_inversion		Whether the icmp-blocks list is inverted (block everything except the listed types).
interfaces		The interfaces bound to the zone.
sources		The source addresses/CIDRs/MACs/ipset references bound to the zone.
services		The service names enabled in the zone.
ports		The port openings (80/tcp, 5000-5100/udp).
protocols		The protocols allowed outright (ah, esp, ...).
forward		Whether intra-zone forwarding is enabled.
masquerade		Whether source NAT (masquerading) is enabled.
forward_ports		The port-forwarding rules (port=80:proto=tcp:toport=8080:toaddr=10.0.0.5).
source_ports		The source-port openings.
icmp_blocks		The blocked ICMP type names.
rich_rules		The rich-language rule strings, one per entry, exactly as firewall-cmd prints them.

FirewalldZones

Every firewalld zone and its complete configuration.

Commands:

firewall-cmd <permanent>--list-all-zones 2> /dev/null || sudo -n firewall-cmd <permanent>--list-all-zones 2> /dev/null || true

Returns:

dict[str, FirewalldZone]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_firewalld_zones.py.

default_zone async

default_zone(
    ctx: OpContext, zone: str, **kwargs: Any
) -> AsyncGenerator[Command]

Set the global default firewalld zone.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
zone	str	The zone unbound connections and interfaces should land in. It must already exist -- firewall-cmd rejects an unknown zone at apply time.	required
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld default zone commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_default_zone.py.

forward_port async

forward_port(
    ctx: OpContext,
    zone: str,
    port: str,
    protocol: str,
    to_port: str | None = None,
    to_addr: str | None = None,
    present: bool = True,
    permanent: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Forward a port to another port and/or address in a firewalld zone.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
zone	str	The zone to manage the forwarding rule in.	required
port	str	The source port to forward (80).	required
protocol	str	The transport protocol (tcp, udp, sctp or dccp).	required
to_port	str | None	The destination port (8080); None forwards to the same port. Defaults to None.	None
to_addr	str | None	The destination address; None forwards to the local machine. Defaults to None.	None
present	bool	Whether the rule should exist. Defaults to True.	True
permanent	bool	Whether the change also applies to the permanent configuration (False is runtime-only). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld forward port commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_forward_port.py.

icmp_block async

icmp_block(
    ctx: OpContext,
    zone: str,
    icmp_type: str,
    present: bool = True,
    permanent: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Block or unblock an ICMP type in a firewalld zone.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
zone	str	The zone to manage the ICMP block in.	required
icmp_type	str	The ICMP type name (echo-request, router-advertisement, ... -- firewall-cmd --get-icmptypes lists them).	required
present	bool	Whether the type should be blocked. Defaults to True.	True
permanent	bool	Whether the change also applies to the permanent configuration (False is runtime-only). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld ICMP block commands.

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_icmp_block.py.

interface async

interface(
    ctx: OpContext,
    zone: str,
    interface: str,
    present: bool = True,
    permanent: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Bind or unbind a network interface to/from a firewalld zone.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
zone	str	The zone to bind the interface to.	required
interface	str	The interface name (eth0, enp3s0, ...).	required
present	bool	Whether the interface should be bound to the zone. Defaults to True.	True
permanent	bool	Whether the change also applies to the permanent configuration (False is runtime-only). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld interface commands.

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_interface.py.

ipset async

ipset(
    ctx: OpContext,
    ipset_name: str,
    present: bool = True,
    ipset_type: str = "hash:ip",
    entries: tuple[str, ...] = (),
    options: tuple[str, ...] = (),
    permanent: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Manage a firewalld ipset container and its member entries.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
ipset_name	str	The name of the ipset to manage (referenced from zone sources as ipset:<name>).	required
present	bool	Whether the ipset (and the listed entries) should exist. Defaults to True.	True
ipset_type	str	The set type used when creating it (hash:ip, hash:net, hash:ip,port, ...). An existing set of a different type raises ValueError rather than silently recreating it. Defaults to "hash:ip".	'hash:ip'
entries	tuple[str, ...]	The member addresses or networks to add (present=True) or remove (present=False); with present=False and no entries the whole definition is deleted. Membership is additive -- entries not listed are left alone. Defaults to ().	()
options	tuple[str, ...]	key=value creation options (family=inet, maxelem=65536, ...), applied at creation only -- changing an existing set's options needs a destroy/recreate. Defaults to ().	()
permanent	bool	Whether the entry changes also apply to the permanent configuration (False is runtime-only; existence is always permanent -- firewall-cmd has no runtime ipset create/delete verb). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld ipset commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_ipset.py.

lockdown async

lockdown(
    ctx: OpContext, enabled: bool = True, **kwargs: Any
) -> AsyncGenerator[Command]

Enable or disable firewalld lockdown mode.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
enabled	bool	Whether lockdown should be enabled. Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld lockdown commands.

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_lockdown.py.

masquerade async

masquerade(
    ctx: OpContext,
    zone: str,
    enabled: bool = True,
    permanent: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Enable or disable masquerading (source NAT) on a firewalld zone.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
zone	str	The zone to manage masquerading on.	required
enabled	bool	Whether masquerading should be enabled. Defaults to True.	True
permanent	bool	Whether the change also applies to the permanent configuration (False is runtime-only). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld masquerade commands.

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_masquerade.py.

panic async

panic(
    ctx: OpContext, enabled: bool = True, **kwargs: Any
) -> AsyncGenerator[Command]

Enable or disable firewalld panic mode (drop ALL network traffic).

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
enabled	bool	Whether panic mode should be enabled. Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld panic commands.

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_panic.py.

port async

port(
    ctx: OpContext,
    zone: str,
    port: str,
    present: bool = True,
    permanent: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Open or close a port (or port range) in a firewalld zone.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
zone	str	The zone to manage the port in.	required
port	str	The port opening, <port>/<protocol> or <start>-<end>/<protocol> (8080/tcp, 5000-5100/udp); the protocol is tcp, udp, sctp or dccp.	required
present	bool	Whether the port should be open. Defaults to True.	True
permanent	bool	Whether the change also applies to the permanent configuration (False is runtime-only). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld port commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_port.py.

protocol async

protocol(
    ctx: OpContext,
    zone: str,
    protocol: str,
    present: bool = True,
    permanent: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Allow or disallow an IP protocol outright in a firewalld zone.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
zone	str	The zone to manage the protocol in.	required
protocol	str	The protocol name (ah, esp, gre, ... -- anything in /etc/protocols).	required
present	bool	Whether the protocol should be allowed. Defaults to True.	True
permanent	bool	Whether the change also applies to the permanent configuration (False is runtime-only). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld protocol commands.

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_protocol.py.

reload async

reload(
    ctx: OpContext, mode: str = "reload", **kwargs: Any
) -> AsyncGenerator[Command]

Reload the firewall, or save the runtime configuration to permanent.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
mode	str	reload applies the permanent configuration to runtime (keeping connection state), complete_reload does the same dropping all state, runtime_to_permanent saves the runtime configuration to disk. Defaults to "reload".	'reload'
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	The firewall-cmd reload command, always (the operation
	AsyncGenerator[Command]	is stateless).

Raises:

ValueError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_reload.py.

rich_rule async

rich_rule(
    ctx: OpContext,
    zone: str,
    rule: str,
    present: bool = True,
    permanent: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Ensure a rich-language rule is present or absent in a zone.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
zone	str	The zone to manage the rule in.	required
rule	str	The complete rich rule string (rule family="ipv4" source address="10.0.0.5/32" port port="5432" protocol="tcp" accept), exactly as firewall-cmd prints it.	required
present	bool	Whether the rule should exist in the zone. Defaults to True.	True
permanent	bool	Whether the change also applies to the permanent configuration (False is runtime-only). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld rich rule commands.

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_rich_rule.py.

service async

service(
    ctx: OpContext,
    service: str,
    present: bool = True,
    ports: tuple[str, ...] = (),
    source_ports: tuple[str, ...] = (),
    protocols: tuple[str, ...] = (),
    modules: tuple[str, ...] = (),
    short: str | None = None,
    description: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Manage a custom firewalld service definition (a port/protocol bundle).

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
service	str	The name of the service definition to manage (my-app); attach it to zones with zone_service.	required
present	bool	Whether the definition should exist. Defaults to True.	True
ports	tuple[str, ...]	The destination port openings the definition bundles (8080/tcp). Membership is additive -- entries not listed are left alone. Defaults to ().	()
source_ports	tuple[str, ...]	The source port openings to bundle, additive. Defaults to ().	()
protocols	tuple[str, ...]	The protocols to allow outright, additive. Defaults to ().	()
modules	tuple[str, ...]	The connection-tracking helper modules to load (nf_conntrack_ftp), additive. Defaults to ().	()
short	str | None	The definition's short display name; None leaves it alone. Defaults to None.	None
description	str | None	The definition's description text; None leaves it alone. Defaults to None.	None
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld service definition commands.

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_service.py.

source async

source(
    ctx: OpContext,
    zone: str,
    source: str,
    present: bool = True,
    permanent: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Bind or unbind a source address to/from a firewalld zone.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
zone	str	The zone to bind the source to.	required
source	str	The source to bind: an IP, a CIDR subnet, a MAC address or an ipset:<name> reference.	required
present	bool	Whether the source should be bound to the zone. Defaults to True.	True
permanent	bool	Whether the change also applies to the permanent configuration (False is runtime-only). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld source commands.

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_source.py.

zone async

zone(
    ctx: OpContext,
    zone: str,
    present: bool = True,
    target: str | None = None,
    short: str | None = None,
    description: str | None = None,
    permanent: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Create, delete or update a firewalld zone.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
zone	str	The name of the zone to manage.	required
present	bool	Whether the zone should exist. Defaults to True.	True
target	str | None	The zone's default verdict (default, ACCEPT, DROP or REJECT); None leaves the current target alone. Defaults to None.	None
short	str | None	The zone's short display name; None leaves it alone. Defaults to None.	None
description	str | None	The zone's description text; None leaves it alone. Defaults to None.	None
permanent	bool	Whether to manage the zone's properties in the permanent configuration. Existence and properties are both permanent-only -- firewall-cmd has no runtime zone create/delete verb and rejects a runtime --set-target/--set-short/--set-description -- so permanent=False leaves the properties unmanaged (the runtime copy inherits them on the next firewalld.reload). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld zone commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_zone.py.

zone_service async

zone_service(
    ctx: OpContext,
    zone: str,
    service: str,
    present: bool = True,
    permanent: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Enable or disable a service in a firewalld zone.

Parameters:

Name	Type	Description	Default
ctx	OpContext	Execution context for the operation.	required
zone	str	The zone to manage the service in.	required
service	str	The service name (http, ssh, a custom definition from firewalld.service, ...).	required
present	bool	Whether the service should be enabled in the zone. Defaults to True.	True
permanent	bool	Whether the change also applies to the permanent configuration (False is runtime-only). Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Yields:

Name	Type	Description
Command	AsyncGenerator[Command]	Generated firewalld zone service commands.

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/firewalld/firewalld_zone_service.py.