firewalld.direct

package: firewalld

title: firewalld.direct(5)

summary: firewalld direct configuration file

text:
# firewalld.direct(5)

## NAME
firewalld.direct - firewalld direct configuration file

## SYNOPSIS

```
/etc/firewalld/direct.xml

```

## DEPRECATED
The direct interface has been deprecated. It will be removed in a future release. It is superseded by policies, see firewalld.policies(5).

## DESCRIPTION
Direct configuration gives a more direct access to the firewall. It requires user to know basic ip(6)tables/ebtables concepts, i.e. table (filter/mangle/nat/...), chain (INPUT/OUTPUT/FORWARD/...), commands (-A/-D/-I/...), parameters (-p/-s/-d/-j/...) and targets (ACCEPT/DROP/REJECT/...). Direct configuration should be used only as a last resort when it's not possible to use firewalld.zone(5). See also Direct Options in firewall-cmd(1).

A firewalld direct configuration file contains information about permanent direct chains, rules and passthrough ...

This is the structure of a direct configuration file:

```
<?xml version="1.0" encoding="utf-8"?>
<direct>

  [ <chain ipv="ipv4|ipv6|eb" table="table" chain="chain"/> ]

  [ <rule ipv="ipv4|ipv6|eb" table="table" chain="chain" priority="priority"> args </rule> ]

  [ <passthrough ipv="ipv4|ipv6|eb"> args </passthrough> ]
</direct>

```

### direct
The mandatory direct start and end tag defines the direct. This tag can only be used once in a direct configuration file. There are no attributes for direct.

### chain
Is an optional empty-element tag and can be used several times. It can be used to define names for additional chains. A chain entry has exactly three attributes:

ipv="ipv4|ipv6|eb"

The IP family where the chain will be created. This can be either ipv4, ipv6 or eb.

table="table"

The table name where the chain will be created. This can be one of the tables that can be used for iptables, ip6tables or ebtables. For the possible values, see TABLES section in the iptables, ip6tables or ebtables man pages.

chain="chain"

The name of the chain, that will be created. Please make sure that there is no other chain with this name already.

Please remember to add a rule or passthrough rule with an --jump or --goto option to connect the chain to another one.

### rule
Is an optional element tag and can be used several times. It can be used to add rules to a built-in or added chain. A rule entry has exactly four attributes:

ipv="ipv4|ipv6|eb"

The IP family where the rule will be added. This can be either ipv4, ipv6 or eb.

table="table"

The table name where the rule will be added. This can be one of the tables that can be used for iptables, ip6tables or ebtables. For the possible values, see TABLES section in the iptables, ip6tables or ebtables man pages.

chain="chain"

The name of the chain where the rule will be added. This can be either a built-in chain or a chain that has been created with the chain tag. If the chain name is a built-in chain, then the rule will be added to chain_direct, else the supplied chain name is used. chain_direct is created internally for all built-in chains to make sure that the added rules do not conflict with the rules created by firewalld.

priority="priority"

The priority is used to order rules. Priority 0 means add rule on top of the chain, with a higher priority the rule will be added further down. Rules with the same priority are on the same level and the order of these rules is not fixed and may change. If you want to make sure that a rule will be added after another one, use a low priority for the first and a higher for the following.

The args can be any arguments of iptables or ip6tables, that do not conflict with the table or chain attributes.

### passthrough
Is an optional element tag and can be used several times. It can be used to add rules to a built-in or added chain. A rule entry has exactly one attribute:

ipv="ipv4|ipv6|eb"

The IP family where the passthrough rule will be added. This can be either ipv4, ipv6 or eb.

The args can be any arguments of iptables or ip6tables.

The passthrough rule will be added to the chain directly. There is no mechanism like for the direct rule above. The user of the passthrough rule has to make sure that there will be no conflict with the rules created by firewalld.

## CAVEATS
Depending on the value of FirewallBackend (see firewalld.conf(5)) direct rules behave differently in some scenarios.

### Packet accept/drop precedence
Due to implementation details of netfilter inside the kernel, if FirewallBackend=nftables is used direct rules that ACCEPT packets don't actually cause the packets to be immediately accepted by the system. Those packets are still be subject to firewalld's nftables ruleset. This basically means there are two independent firewalls and packets must be accepted by both (iptables and nftables). As an aside, this scenario also occurs inside of nftables (again due to netfilter) if there are multiple chains attached to the same hook - it's not as simple as iptables vs nftables.

There are a handful of options to workaround the ACCEPT issue:

1.Rich Rules If a rich rule can be used, then they should always be preferred over direct rules. Rich Rules will be converted to the enabled FirewallBackend. See firewalld.richlanguage(5).

2.Blanket Accept Users can add an explicit accept to the nftables ruleset. This can be done by adding the interface or source to the trusted zone.

This strategy is often employed by things that perform their own filtering such as: libvirt, podman, docker.

Warning: This means firewalld will do no filtering on these packets. It must all be done via direct rules or out-of-band iptables rules.

3.Selective Accept Alternatively, enable only the relevant service, port, address, or otherwise in the appropriate zone.

4.Revert to the iptables backend A last resort is to revert to the iptables backend by setting FirewallBackend=iptables. Users should be aware that firewalld development focuses on the nftables backend.

For direct rules that DROP packets the packets are immediately dropped regardless of the value of FirewallBackend. As such, there is no special consideration needed.

Firewalld guarantees the above ACCEPT/DROP behavior by registering nftables hooks with a lower precedence than iptables hooks.

### Direct interface precedence
With FirewallBackend=iptables firewalld's top-level internal rules apply before direct rules are executed. This includes rules to accept existing connections. In the past this has surprised users. As an example, if a user adds a direct rule to drop traffic on destination port 22 existing SSH sessions would continue to function, but new connections would be denied.

With FirewallBackend=nftables direct rules were deliberately given a higher precedence than all other firewalld rules. This includes rules to accept existing connections.

## EXAMPLE
Denylisting of the networks 192.168.1.0/24 and 192.168.5.0/24 with logging and dropping early in the raw table:

```
<?xml version="1.0" encoding="utf-8"?>
<direct>

  <chain ipv="ipv4" table="raw" chain="denylist"/>

  <rule ipv="ipv4" table="raw" chain="PREROUTING" priority="0">-s 192.168.1.0/24 -j denylist</rule>

  <rule ipv="ipv4" table="raw" chain="PREROUTING" priority="1">-s 192.168.5.0/24 -j denylist</rule>

  <rule ipv="ipv4" table="raw" chain="denylist" priority="0">-m limit --limit 1/min -j LOG --log-prefix "denylisted: "</rule>

  <rule ipv="ipv4" table="raw" chain="denylist" priority="1">-j DROP</rule>
</direct>

```

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


firewalld.helper

title: firewalld.helper(5)

summary: firewalld helper configuration files

text:
# firewalld.helper(5)

## NAME
firewalld.helper - firewalld helper configuration files

## SYNOPSIS

```
/etc/firewalld/helpers/helper.xml
/usr/lib/firewalld/helpers/helper.xml

```

## DESCRIPTION
A firewalld helper configuration file provides the information of a helper entry for firewalld. The most important configuration options are ports, family and module.

This example configuration file shows the structure of a helper configuration file:

```
<?xml version="1.0" encoding="utf-8"?>
<helper module="nf_conntrack_module" [family="ipv4|ipv6"]>

  <short>short</short>

  <description>description</description>

  <port port="portid[-portid]" protocol="tcp|udp|sctp|dccp"/>
</helper>

```

## OPTIONS
The config can contain these tags and attributes. Some of them are mandatory, others optional.

### helper
The mandatory helper start and end tag defines the helper. This tag can only be used once in a helper configuration file. There is one mandatory and also optional attributes for helper:

module="string"

The mandatory module of the helper. This is one of the netfilter conntrack helper modules. The name starts with nf_conntrack_.

family="ipv4|ipv6"

The optional family of the helper. This can be one of these ipv types: ipv4 or ipv6. If the family is not specified, then the helper is usable for IPv4 and IPv6.

version="string"

To give the helper a version.

### short
Is an optional start and end tag and is used to give a helper a more readable name.

### description
Is an optional start and end tag to have a description for a helper.

### port
Is an mandatory empty-element tag and can be used several times to have more than one port entry. All attributes of a port entry are mandatory:

port="string"

The port string can be a single port number or a port range portid-portid or also empty to match a protocol only.

protocol="string"

The protocol value can either be tcp, udp, sctp or dccp.

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


firewalld.icmptype

title: firewalld.icmptype(5)

summary: firewalld icmptype configuration files

text:
# firewalld.icmptype(5)

## NAME
firewalld.icmptype - firewalld icmptype configuration files

## SYNOPSIS

```
/etc/firewalld/icmptypes/icmptype.xml
/usr/lib/firewalld/icmptypes/icmptype.xml

```

## DESCRIPTION
A firewalld icmptype configuration file provides the information for an Internet Control Message Protocol (ICMP) type for firewalld.

This example configuration file shows the structure of an icmptype configuration file:

```
<?xml version="1.0" encoding="utf-8"?>
<icmptype>

  <short>My Icmptype</short>

  <description>description</description>

  <destination ipv4="yes" ipv6="yes"/>
</icmptype>

```

## OPTIONS
The config can contain these tags and attributes. Some of them are mandatory, others optional.

### icmptype
The mandatory icmptype start and end tag defines the icmptype. This tag can only be used once in an icmptype configuration file. This tag has optional attributes:

version="string"

To give the icmptype a version.

### short
Is an optional start and end tag and is used to give an icmptype a more readable name.

### description
Is an optional start and end tag to have a description for a icmptype.

### destination
Is an optional empty-element tag and can be used only once. The destination tag specifies if an icmptype entry is available for IPv4 and/or IPv6. The default is IPv4 and IPv6, where this tag can be missing.

ipv4="bool"

Describes if the icmptype is available for IPv4.

ipv6="bool"

Describes if the icmptype is available for IPv6.

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


firewalld.ipset

title: firewalld.ipset(5)

summary: firewalld ipset configuration files

text:
# firewalld.ipset(5)

## NAME
firewalld.ipset - firewalld ipset configuration files

## SYNOPSIS

```
/etc/firewalld/ipsets/ipset.xml
/usr/lib/firewalld/ipsets/ipset.xml

```

## DESCRIPTION
A firewalld ipset configuration file provides the information of an ip set for firewalld. The most important configuration options are type, option and entry.

This example configuration file shows the structure of an ipset configuration file:

```
<?xml version="1.0" encoding="utf-8"?>
<ipset type="hash:ip">

  <short>My Ipset</short>

  <description>description</description>

  <entry>1.2.3.4</entry>

  <entry>1.2.3.5</entry>

  <entry>1.2.3.6</entry>
</ipset>

```

## OPTIONS
The config can contain these tags and attributes. Some of them are mandatory, others optional.

### ipset
The mandatory ipset start and end tag defines the ipset. This tag can only be used once in a ipset configuration file. There is one mandatory and also optional attributes for ipsets:

type="string"

The mandatory type of the ipset. To get the list of supported types, use firewall-cmd --get-ipset-types.

version="string"

To give the ipset a version.

### short
Is an optional start and end tag and is used to give an ipset a more readable name.

### description
Is an optional start and end tag to have a description for a ipset.

### option
Is an optional empty-element tag and can be used several times to have more than one option. Mostly all attributes of an option entry are mandatory:

name="string"

The mandatory option name string.

value="string"

The optional value of the option.

The supported options are: family: "inet"|"inet6", timeout: integer, hashsize: integer, maxelem: integer. For more information on these options, please have a look at the ipset documentation.

### entry
Is an optional start and end tag and can be used several times to have more than one entry entry. An entry entry does not have attributes.

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


firewalld.policies

title: firewalld.policies(5)

summary: firewalld policies

text:
# firewalld.policies(5)

## NAME
firewalld.policies - firewalld policies

## DESCRIPTION

### What is a policy?
A policy applies a set of rules to traffic flowing between zones (see zones (see firewalld.zones(5)). The policy affects traffic in a stateful unidirectional manner, e.g. zoneA to zoneB. This allows asymmetric filtering policies.

A policy's relationship to zones is defined by assigning a set of ingress zones and a set of egress zones. For example, if the set of ingress zones contains "internal" and the set of egress zones contains "external" then the policy will affect all traffic flowing from the "internal" zone to the "external" zone. However, since policies are unidirectional it will not apply to traffic flowing from "external" to "internal". The ingress set and egress set may contain multiple zones.

Below as a visual representation of policy foobar followed by the CLI commands to create it. This policy would affect traffic flowing from the internal zone to the external zone. Initially, the target is set to ACCEPT to allow all traffic. This is common if the internal network is trusted.

```
                +----------+           +----------+

                |          |  policy   |          |

                | internal | --------> | external |

                |   zone   |  foobar   |   zone   |

                |          |           |          |

                +----------+           +----------+

```

```
                # firewall-cmd --permanent --new-policy foobar

                # firewall-cmd --permanent --policy foobar --add-ingress-zone internal

                # firewall-cmd --permanent --policy foobar --add-egress-zone external

                # firewall-cmd --permanent --policy foobar --set-target ACCEPT

                # firewall-cmd --reload

```

Perhaps it makes sense to be more restrictive. This example changes foobar so that it only allows: dns, http, and https traffic. Everything else is blocked. Clients would only be allowed to surf the web.

```
                # firewall-cmd --permanent --policy foobar --set-target REJECT

                # firewall-cmd --permanent --policy foobar --add-service dns

                # firewall-cmd --permanent --policy foobar --add-service http

                # firewall-cmd --permanent --policy foobar --add-service https

                # firewall-cmd --reload

```

### Active Policies
Policies only become active if all of the following are true.

•The policy is not disabled.

•The ingress zones list contain at least one regular zone or a single symbolic zone.

•The egress zones list contain at least one regular zone or a single symbolic zone.

•For non symbolic zones, the zone must be active. That is, it must have interfaces or sources assigned to it.

If the policy is not active then the policy has no effect.

### Symbolic Zones
Regular zones are not enough to express every form of packet filtering. For example there is no zone to represent traffic flowing to or from the host running firewalld. As such, there are some symbolic zones to fill these gaps. However, symbolic zones are unique in that they're the only zone allowed in the ingress or egress zone sets. For example, you cannot use "public" and "HOST" in the ingress zones.

Symbolic zones:

1.HOST This symbolic zone is for traffic flowing to or from the host running firewalld. This corresponds to netfilter (iptables/nftables) chains INPUT and OUTPUT.

•If used in the egress zones list it will apply to traffic on the INPUT chain.

•If used in the ingress zones list it will apply to traffic on the OUTPUT chain.

2.ANY This symbolic zone behaves like a wildcard for the ingress and egress zones. With the exception that it does not include "HOST". It's useful if you want a policy to apply to every zone.

•If used in the ingress zones list it will apply for traffic originating from any zone.

•If used in the egress zones list it will apply for traffic destined to any zone.

### Predefined Policies
firewalld ships with some predefined policies. These may or may not be active by default. For details see the description of each policy.

•allow-host-ipv6

### Similarity to Zones
Policies are similar to zones in that they are an attachment point for firewalld's primitives: services, ports, forward ports, etc. This is not a coincidence. Policies are a generalization of how zones have traditionally achieved filtering. In fact, in modern firewalld zones are internally implemented as a set of policies.

The main difference between policies and zones is that policies allow filtering in all directions: input, output, and forwarding. With a couple of exceptions zones only allow input filtering which is sufficient for an end station firewalling. However, for network level filtering or filtering on behalf of virtual machines and containers something more flexible, i.e. policies, are needed.

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


firewalld.policy

title: firewalld.policy(5)

summary: firewalld policy configuration files

text:
# firewalld.policy(5)

## NAME
firewalld.policy - firewalld policy configuration files

## SYNOPSIS
/etc/firewalld/policies/policy.xml

/usr/lib/firewalld/policies/policy.xml

## DESCRIPTION
A firewalld policy configuration file contains the information for a policy. These are the policy descriptions, services, ports, protocols, icmp-blocks, masquerade, forward-ports and rich language rules in an XML file format. The file name has to be policy_name.xml where length of policy_name is currently limited to 17 chars.

This is the structure of a policy configuration file:

```
<?xml version="1.0" encoding="utf-8"?>
<policy [version="versionstring"] [target="CONTINUE|ACCEPT|REJECT|DROP"] [priority="priority"]>

    [ <disable/> ]

    [ <ingress-zone name="zone"/> ]

    [ <egress-zone name="zone"/> ]

    [ <short>short description</short> ]

    [ <description>description</description> ]

    [ <service name="string"/> ]

    [ <port port="portid[-portid]" protocol="tcp|udp|sctp|dccp"/> ]

    [ <protocol value="protocol"/> ]

    [ <icmp-block name="string"/> ]

    [ <masquerade/> ]

    [ <forward-port port="portid[-portid]" protocol="tcp|udp|sctp|dccp" [to-port="portid[-portid]"] [to-addr="IP address"]/> ]

    [ <source-port port="portid[-portid]" protocol="tcp|udp|sctp|dccp"/> ]

    [

        <rule [family="ipv4|ipv6"] [priority="priority"]>

            [ <source address="address[/mask]"|mac="MAC"|ipset="ipset" [invert="True"]/> ]

            [ <destination address="address[/mask]"|ipset="ipset" [invert="True"]/> ]

            [

                <service name="string"/> |

                <port port="portid[-portid]" protocol="tcp|udp|sctp|dccp"/> |

                <protocol value="protocol"/> |

                <icmp-block name="icmptype"/> |

                <icmp-type name="icmptype"/> |

                <masquerade/> |

                <forward-port port="portid[-portid]" protocol="tcp|udp|sctp|dccp" [to-port="portid[-portid]"] [to-addr="address"]/>

            ]

            [

                <log [prefix="prefix text"] [level="emerg|alert|crit|err|warn|notice|info|debug"]> [<limit value="rate/duration"/>] </log> |

                <nflog [group="group id"] [prefix="prefix text"] [queue-size="threshold"]> [<limit value="rate/duration"/>] </nflog>

            ]

            [ <audit> [<limit value="rate/duration"/>] </audit> ]

            [

                <accept> [<limit value="rate/duration"/>] </accept> |

                <reject [type="rejecttype"]> [<limit value="rate/duration"/>] </reject> |

                <drop> [<limit value="rate/duration"/>] </drop> |

                <mark set="mark[/mask]"> [<limit value="rate/duration"/>] </mark>

            ]

        </rule>

    ]
</policy>

```

The config can contain these tags and attributes. Some of them are mandatory, others optional.

### policy
The mandatory policy start and end tag defines the policy. This tag can only be used once in a policy configuration file. There are optional attributes for policy:

version="string"

To give the policy a version.

target="CONTINUE|ACCEPT|REJECT|DROP"

Can be used to accept, reject or drop every packet that doesn't match any rule (port, service, etc.). The CONTINUE is the default and used for policies that are non-terminal.

### disable
Is an optional empty-element tag. It can be used only once. If it's present the policy is disabled and will not activate.

### ingress-zone
An optional element that can be used several times. It can be the name of a firewalld zone or one of the symbolic zones: HOST, ANY. See firewalld.policies(5) for information about symbolic zones.

### egress-zone
An optional element that can be used several times. It can be the name of a firewalld zone or one of the symbolic zones: HOST, ANY. See firewalld.policies(5) for information about symbolic zones.

### short
Is an optional start and end tag and is used to give a more readable name.

### description
Is an optional start and end tag to have a description.

### service
Is an optional empty-element tag and can be used several times to have more than one service entry enabled. A service entry has exactly one attribute:

name="string"

The name of the service to be enabled. To get a list of valid service names firewall-cmd --get-services can be used.

### port
Is an optional empty-element tag and can be used several times to have more than one port entry. All attributes of a port entry are mandatory:

port="portid[-portid]"

The port can either be a single port number portid or a port range portid-portid.

protocol="tcp|udp|sctp|dccp"

The protocol can either be tcp, udp, sctp or dccp.

### protocol
Is an optional empty-element tag and can be used several times to have more than one protocol entry. All protocol has exactly one attribute:

value="string"

The protocol can be any protocol supported by the system. Please have a look at /etc/protocols for supported protocols.

### icmp-block
Is an optional empty-element tag and can be used several times to have more than one icmp-block entry. Each icmp-block tag has exactly one mandatory attribute:

name="string"

The name of the Internet Control Message Protocol (ICMP) type to be blocked. To get a list of valid ICMP types firewall-cmd --get-icmptypes can be used.

### masquerade
Is an optional empty-element tag. It can be used only once. If it's present masquerading is enabled.

### forward-port
Is an optional empty-element tag and can be used several times to have more than one port or packet forward entry. There are mandatory and also optional attributes for forward ports:

Mandatory attributes:

The local port and protocol to be forwarded.

port="portid[-portid]"

The port can either be a single port number portid or a port range portid-portid.

protocol="tcp|udp|sctp|dccp"

The protocol can either be tcp, udp, sctp or dccp.

Optional attributes:

The destination of the forward. For local forwarding add to-port only. For remote forwarding add to-addr and use to-port optionally if the destination port on the destination machine should be different.

to-port="portid[-portid]"

The destination port or port range to forward to. If omitted, the value of the port= attribute will be used altogether with the to-addr attribute.

to-addr="address"

The destination IP address either for IPv4 or IPv6.

### source-port
Is an optional empty-element tag and can be used several times to have more than one source port entry. All attributes of a source port entry are mandatory:

port="portid[-portid]"

The port can either be a single port number portid or a port range portid-portid.

protocol="tcp|udp|sctp|dccp"

The protocol can either be tcp, udp, sctp or dccp.

### rule
Is an optional element tag and can be used several times to have more than one rich language rule entry.

The general rule structure:

```
<rule [family="ipv4|ipv6"] [priority="priority"]>

    [ <source address="address[/mask]"|mac="MAC"|ipset="ipset" [invert="True"]/> ]

    [ <destination address="address[/mask]"|ipset="ipset" [invert="True"]/> ]

    [

        <service name="string"/> |

        <port port="portid[-portid]" protocol="tcp|udp|sctp|dccp"/> |

        <protocol value="protocol"/> |

        <icmp-block name="icmptype"/> |

        <icmp-type name="icmptype"/> |

        <masquerade/> |

        <forward-port port="portid[-portid]" protocol="tcp|udp|sctp|dccp" [to-port="portid[-portid]"] [to-addr="address"]/> |

        <source-port port="portid[-portid]" protocol="tcp|udp|sctp|dccp"/> |

    ]

    [

        <log [prefix="prefix text"] [level="emerg|alert|crit|err|warn|notice|info|debug"]> [<limit value="rate/duration"/>] </log> |

        <nflog [group="group id"] [prefix="prefix text"] [queue-size="threshold"]> [<limit value="rate/duration"/>] </nflog>

    ]

    [ <audit> [<limit value="rate/duration"/>] </audit> ]

    [

        <accept> [<limit value="rate/duration"/>] </accept> |

        <reject [type="rejecttype"]> [<limit value="rate/duration"/>] </reject> |

        <drop> [<limit value="rate/duration"/>] </drop> |

        <mark set="mark[/mask]"> [<limit value="rate/duration"/>] </mark>

    ]
</rule>

```

Rule structure for source black or white listing:

```
<rule [family="ipv4|ipv6"] [priority="priority"]>

    <source address="address[/mask]"|mac="MAC"|ipset="ipset" [invert="True"]/>

    [

        <log [prefix="prefix text"] [level="emerg|alert|crit|err|warn|notice|info|debug"]> [<limit value="rate/duration"/>] </log> |

        <nflog [group="group id"] [prefix="prefix text"] [queue-size="threshold"]> [<limit value="rate/duration"/>] </nflog>

    ]

    [ <audit> [<limit value="rate/duration"/>] </audit> ]

    <accept> [<limit value="rate/duration"/>] </accept> |

    <reject [type="rejecttype"]> [<limit value="rate/duration"/>] </reject> |

    <drop> [<limit value="rate/duration"/>] </drop>
</rule>

```

For a full description on rich language rules, please have a look at firewalld.richlanguage(5).

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


firewalld.policy-set-gateway

title: firewalld.policy-set-gateway(5)

summary: Firewalld Policy Set Gateway

text:
# firewalld.policy-set-gateway(5)

## NAME
firewalld.policy-set-gateway - Firewalld Policy Set Gateway

## DESCRIPTION

### Policy Set: Gateway
The Gateway policy set is a useful starting point for a home router. It enables masquerading, conntrack helpers, and forwarding between zones.

Zones used by this set are logically grouped. These groups name are used by the predefined policies.

```
            +-----------+                  +-----------+

            |    LAN    |                  |   WORLD   |

            |-----------|                  |-----------|

            | zones:    |                  | zones:    |

            |  internal |                  |  external |

            |  home     |                  |  public   |

            |  trusted  |                  |           |

            +-----------+                  +-----------+

                  |                              |

                  |                              |

                  |         +-----------+        |

                  +---------|   HOST    |--------+

                            |-----------|

                            | zones:    |

                  +---------|  HOST     |--------+

                  |         +-----------+        |

                  |                              |

                  |                              |

            +-----------+                  +-----------+

            |   WORK    |                  |    DMZ    |

            |-----------|                  |-----------|

            | zones:    |                  | zones:    |

            |  work     |                  |  dmz      |

            +-----------+                  +-----------+

```

### Policies in the Gateway set
gateway-dmz-to-HOST

Enables services commonly needed for a gateway, e.g. dns, dhcp. File location: /usr/lib/firewalld/policies/gateway-dmz-to-HOST.xml

gateway-lan-to-work

Allows all traffic from LAN to work. Enables masquerading and common connection tracking helpers. File location: /usr/lib/firewalld/policies/gateway-lan-to-work.xml

gateway-lan-to-world

Allows all traffic from LAN to world. If an interface is added to the "external" zone then the traffic will be masqueraded. Also enables connection tracking helpers for common services, e.g. ftp. File location: /usr/lib/firewalld/policies/gateway-lan-to-world.xml

gateway-lan-to-HOST

Enables services commonly needed for a gateway, e.g. dns, dhcp. File location: /usr/lib/firewalld/policies/gateway-lan-to-HOST.xml

gateway-world-to-HOST

May be used to expose internal/dmz services to the world by adding a forward port to this policy. Here is an example for adding a forward port. It forward port 8080 to 10.1.1.42:80.

```
# firewall-cmd --permanent --policy gateway-world-to-HOST \

               --add-forward-port=port=8080:proto=tcp:toport=80:toaddr=10.1.1.42
# firewall-cmd --reload

```

File location: /usr/lib/firewalld/policies/gateway-world-to-HOST.xml

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


firewalld.policy-sets

title: firewalld.policy-sets(5)

summary: Policy Sets

text:
# firewalld.policy-sets(5)

## NAME
firewalld.policy-sets - Policy Sets

## DESCRIPTION

### What Are Policy Sets?
Policy sets are collections of policies that serve as starting configuration for specific use cases, e.g. a home router. They provide an easy way to get started. Users may then fine tune the configuration for their environment. Every policy set has a dedicated man page to explain its use case.

All policy sets shipped by firewalld are administratively disabled by default. Using them is a matter of adding your interfaces to zones and removing the disable.

### Enabling a Policy Set
Below is a complete example for using the gateway policy set. In this example: eth0 is the LAN interface, and eth1 is the uplink to the internet.

```
	      # firewall-cmd --permanent --zone internal eth0
	      # firewall-cmd --permanent --zone external eth1
	      # firewall-cmd --permanent --policy-set gateway --remove-disable
	      # firewall-cmd --reload

```

### Enabling Multiple Policy Sets
Policy sets are guaranteed to interoperate. Multiple policy sets may be enabled simultaneously.

### Existing Policy Sets
gateway

Provides basic functionality for a gateway, e.g. a home router. See firewalld.policy-set-gateway(5).

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


firewalld.richlanguage

title: firewalld.richlanguage(5)

summary: Rich Language Documentation

text:
# firewalld.richlanguage(5)

## NAME
firewalld.richlanguage - Rich Language Documentation

## DESCRIPTION
With the rich language more complex firewall rules can be created in an easy to understand way. The language uses keywords with values and is an abstract representation of ip*tables rules.

The rich language extends the current zone elements (service, port, icmp-block, icmp-type, masquerade, forward-port and source-port) with additional source and destination addresses, logging, actions and limits for logs and actions.

This page describes the rich language used in the command line client and D-Bus interface. For information about the rich language representation used in the zone configuration files, please have a look at firewalld.zone(5).

A rule is part of a zone. One zone can contain several rules. If some rules interact/contradict, the first rule that matches "wins".

General rule structure

```
rule

  [source]

  [destination]

  service|port|protocol|icmp-block|icmp-type|masquerade|forward-port|source-port

  [log|nflog]

  [audit]

  [accept|reject|drop|mark]

```

The complete rule is provided as a single line string. A destination is allowed here as long as it does not conflict with the destination of a service.

Rule structure for source black or white listing

```
rule

  source

  [log|nflog]

  [audit]

  accept|reject|drop|mark

```

This is used to grant or limit access from a source to this machine or machines that are reachable by this machine. A destination is not allowed here.

Important information about element options: Options for elements in a rule need to be added exactly after the element. If the option is placed somewhere else it might be used for another element as far as it matches the options of the other element or will result in a rule error.

### Rule

```
rule [family="ipv4|ipv6"] [priority="priority"]

```

If the rule family is provided, it can be either "ipv4" or "ipv6", which limits the rule to IPv4 or IPv6. If the rule family is not provided, the rule will be added for IPv4 and IPv6. If source or destination addresses are used in a rule, then the rule family need to be provided. This is also the case for port/packet forwarding.

If the rule priority is provided, it can be in the range of -32768 to 32767 where lower values have higher precedence. Rich rules are sorted by priority. Ordering for rules with the same priority value is undefined. A negative priority value will be executed before other firewalld primitives. A positive priority value will be executed after other firewalld primitives. A priority value of 0 will place the rule in a chain based on the action as per the "Information about logging and actions" below.

### Source

```
source [not] address="address[/mask]"|mac="mac-address"|ipset="ipset"

```

With the source address the origin of a connection attempt can be limited to the source address. An address is either a single IP address, or a network IP address, a MAC address or an IPSet. The address has to match the rule family (IPv4/IPv6). Subnet mask is expressed in either dot-decimal (/x.x.x.x) or prefix (/x) notations for IPv4, and in prefix notation (/x) for IPv6 network addresses. It is possible to invert the sense of an address by adding not before address. All but the specified address will match then.

### Destination

```
destination [not] address="address[/mask]"|ipset="ipset"

```

With the destination address the target can be limited to the destination address. The destination address is using the same syntax as the source address.

The use of source and destination addresses is optional and the use of a destination addresses is not possible with all elements. This depends on the use of destination addresses for example in service entries.

### Service

```
service name="service name"

```

The service service name will be added to the rule. The service name is one of the firewalld provided services. To get a list of the supported services, use firewall-cmd --get-services.

If a service provides a destination address, it will conflict with a destination address in the rule and will result in an error. The services using destination addresses internally are mostly services using multicast.

### Port

```
port port="port value" protocol="tcp|udp|sctp|dccp"

```

The port port value can either be a single port number portid or a port range portid-portid. The protocol can either be tcp, udp, sctp or dccp.

### Protocol

```
protocol value="protocol value"

```

The protocol value can be either a protocol id number or a protocol name. For allowed protocol entries, please have a look at /etc/protocols.

### Tcp-Mss-Clamp

```
tcp-mss-clamp="value=pmtu|value=number >= 536|None"

```

The tcp-mss-clamp sets the maximum segment size in the rule.

The tcp-mss-clamp has an optional attribute value can be either be set to "pmtu" or a number greater than or equal to 536. If attribute value is not present then the maximum segment size is automatically set to "pmtu".

### ICMP-Block

```
icmp-block name="icmptype name"

```

The icmptype is the one of the icmp types firewalld supports. To get a listing of supported icmp types: firewall-cmd --get-icmptypes

It is not allowed to specify an action here. icmp-block uses the action reject internally.

### Masquerade

```
masquerade

```

Turn on masquerading in the rule. A source and also a destination address can be provided to limit masquerading to this area.

It is not allowed to specify an action here.

Note: IP forwarding will be implicitly enabled.

### ICMP-Type

```
icmp-type name="icmptype name"

```

The icmptype is the one of the icmp types firewalld supports. To get a listing of supported icmp types: firewall-cmd --get-icmptypes

### Forward-Port

```
forward-port port="port value" protocol="tcp|udp|sctp|dccp" to-port="port value" to-addr="address"

```

Forward port/packets from local port value with protocol "tcp" or "udp" to either another port locally or to another machine or to another port on another machine.

The port value can either be a single port number or a port range portid-portid. The to-addr is an IP address. The protocol can either be tcp, udp, sctp or dccp.

It is not allowed to specify an action here. forward-port uses the action accept internally.

Note: IP forwarding will be implicitly enabled if to-addr is specified.

### Source-Port

```
source-port port="port value" protocol="tcp|udp|sctp|dccp"

```

The source-port port value can either be a single port number portid or a port range portid-portid. The protocol can either be tcp, udp, sctp or dccp.

### Log

```
log [prefix="prefix text"] [level="log level"] [limit value="rate/duration"]

```

Log new connection attempts to the rule with kernel logging for example in syslog. You can define a prefix text with a maximum length of 127 characters that will be added to the log message as a prefix. Log level can be one of "emerg", "alert", "crit", "error", "warning", "notice", "info" or "debug", where default (i.e. if there's no one specified) is "warning". See syslog(3) for description of levels. See Limit section for description of limit tag.

Note: The iptables backend truncates prefix to 29 characters.

### NFLog

```
nflog [group="group id"] [prefix="prefix text"] [queue-size="threshold"] [limit value="rate/duration"]

```

Log new connection attempts to the rule using kernel logging to pass the packets through a 'netlink' socket to users or applications monitoring the multicast group. The minimum and default value for group is 0, maximum value is 65535. See NETLINK_NETFILTER in netlink(7) man page and NFLOG in both iptables-extensions(8) and nft(8) man pages for a more detailed description.

You can define a prefix text with a maximum length of 127 characters that will be added to the log message as a prefix. The queue-size option can be set to increase the queue threshold which can help limit context switching. The default value for queue-size is 1, maximum value is 65535. See iptables-extensions(8) and nft(8) for more details.

See Limit section for description of limit tag.

Note: The iptables backend truncates prefix to 63 characters.

### Audit

```
audit [limit value="rate/duration"]

```

Audit provides an alternative way for logging using audit records sent to the service auditd. Audit type will be discovered from the rule action automatically. Use of audit is optional. See Limit section for description of limit tag.

### Action
An action can be one of accept, reject, drop or mark.

The rule can either contain an element or also a source only. If the rule contains an element, then new connection matching the element will be handled with the action. If the rule does not contain an element, then everything from the source address will be handled with the action.

```
accept [limit value="rate/duration"]

```

```
reject [type="reject type"] [limit value="rate/duration"]

```

```
drop [limit value="rate/duration"]

```

```
mark set="mark[/mask]" [limit value="rate/duration"]

```

With accept all new connection attempts will be granted. With reject they will not be accepted and their source will get a reject ICMP(v6) message. The reject type can be set to specify appropriate ICMP(v6) error message. For valid reject types see --reject-with type in iptables-extensions(8) man page. Because reject types are different for IPv4 and IPv6 you have to specify rule family when using reject type. With drop all packets will be dropped immediately, there is no information sent to the source. With mark all packets will be marked in the PREROUTING chain in the mangle table with the mark and mask combination. See Limit section for description of limit tag.

### Limit

```
limit value="rate/duration"

```

It is possible to limit Log, NFLog, Audit and Action. A rule using this tag will match until this limit is reached. The rate is a natural positive number [1, ..] The duration is of "s", "m", "h", "d". "s" means seconds, "m" minutes, "h" hours and "d" days. Maximum limit value is "2/d", which means at maximum two matches per day.

### Information about logging and actions
Logging can be done with the log, nflog and audit actions. A new chain is added to all zones: zone_log. This will be jumped into before the deny chain to be able to have a proper ordering.

The rules or parts of them are placed in separate chains according to the priority and action of the rule:

```
zone_pre
zone_log
zone_deny
zone_allow
zone_post

```

When priority < 0, the rich rule will be placed in the zone_pre chain.

When priority == 0 Then all logging rules will be placed in the zone_log chain. All reject and drop rules will be placed in the zone_deny chain, which will be walked after the log chain. All accept rules will be placed in the zone_allow chain, which will be walked after the deny chain. If a rule contains log and also deny or allow actions, the parts are placed in the matching chains.

When priority > 0, the rich rule will be placed in the zone_post chain.

## EXAMPLES
These are examples of how to specify rich language rules. This format (i.e. one string that specifies whole rule) uses for example firewall-cmd --add-rich-rule (see firewall-cmd(1)) as well as D-Bus interface.

### Example 1
Enable new IPv4 and IPv6 connections for protocol 'ah'

```
rule protocol value="ah" accept

```

### Example 2
Allow new IPv4 and IPv6 connections for service ftp and log 1 per minute using audit

```
rule service name="ftp" log limit value="1/m" audit accept

```

### Example 3
Allow new IPv4 connections from address 192.168.0.0/24 for service tftp and log 1 per minutes using syslog

```
rule family="ipv4" source address="192.168.0.0/24" service name="tftp" log prefix="tftp" level="info" limit value="1/m" accept

```

### Example 4
New IPv6 connections from 1:2:3:4:6:: to service radius are all rejected and logged at a rate of 3 per minute. New IPv6 connections from other sources are accepted.

```
rule family="ipv6" source address="1:2:3:4:6::" service name="radius" log prefix="dns" level="info" limit value="3/m" reject
rule family="ipv6" service name="radius" accept

```

### Example 5
Forward IPv6 port/packets receiving from 1:2:3:4:6:: on port 4011 with protocol tcp to 1::2:3:4:7 on port 4012

```
rule family="ipv6" source address="1:2:3:4:6::" forward-port to-addr="1::2:3:4:7" to-port="4012" protocol="tcp" port="4011"

```

### Example 6
White-list source address to allow all connections from 192.168.2.2

```
rule family="ipv4" source address="192.168.2.2" accept

```

### Example 7
Black-list source address to reject all connections from 192.168.2.3

```
rule family="ipv4" source address="192.168.2.3" reject type="icmp-admin-prohibited"

```

### Example 8
Black-list source address to drop all connections from 192.168.2.4

```
rule family="ipv4" source address="192.168.2.4" drop

```

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


firewalld.service

title: firewalld.service(5)

summary: firewalld service configuration files

text:
# firewalld.service(5)

## NAME
firewalld.service - firewalld service configuration files

## SYNOPSIS

```
/etc/firewalld/services/service.xml
/usr/lib/firewalld/services/service.xml

```

## DESCRIPTION
A firewalld service configuration file provides the information of a service entry for firewalld. The most important configuration options are ports, modules and destination addresses.

This example configuration file shows the structure of a service configuration file:

```
<?xml version="1.0" encoding="utf-8"?>
<service>

  <short>My Service</short>

  <description>description</description>

  <port port="137" protocol="tcp"/>

  <protocol value="igmp"/>

  <module name="nf_conntrack_netbios_ns"/>

  <destination ipv4="224.0.0.251" ipv6="ff02::fb"/>

  <include service="ssdp"/>

  <helper name="ftp"/>
</service>

```

## OPTIONS
The config can contain these tags and attributes. Some of them are mandatory, others optional.

### service
The mandatory service start and end tag defines the service. This tag can only be used once in a service configuration file. There are optional attributes for services:

version="string"

To give the service a version.

### short
Is an optional start and end tag and is used to give an service a more readable name.

### description
Is an optional start and end tag to have a description for a service.

### port
Is an optional empty-element tag and can be used several times to have more than one port entry. All attributes of a port entry are mandatory:

port="string"

The port string can be a single port number or a port range portid-portid or also empty to match a protocol only.

protocol="string"

The protocol value can either be tcp, udp, sctp or dccp.

For compatibility with older firewalld versions, it is possible to add protocols with the port option where the port is empty. With the addition of native protocol support in the service, this it not needed anymore. These entries will automatically be converted to protocols. With the next modification of the service file, the enries will be listed as protocols.

### protocol
Is an optional empty-element tag and can be used several times to have more than one protocol entry. A protocol entry has exactly one attribute:

value="string"

The protocol can be any protocol supported by the system. Please have a look at /etc/protocols for supported protocols.

### source-port
Is an optional empty-element tag and can be used several times to have more than one source port entry. All attributes of a source port entry are mandatory:

port="string"

The port string can be a single port number or a port range portid-portid.

protocol="string"

The protocol value can either be tcp, udp, sctp or dccp.

### module
This element is deprecated. Please use helper described below in the section called “helper”.

### destination
Is an optional empty-element tag and can be used only once. The destination specifies the destination network as a network IP address (optional with /mask), or a plain IP address. The use of hostnames is not recommended, because these will only be resolved at service activation and transmitted to the kernel. For more information in this element, please have a look at --destination in iptables(8) and ip6tables(8).

ipv4="address[/mask]"

The IPv4 destination address with optional mask.

ipv6="address[/mask]"

The IPv6 destination address with optional mask.

### include
Is an optional empty-element tag and can be used several times to have more than one include entry. An include entry has exactly one attribute:

service="string"

The include can be any service supported by firewalld. Warning:Firewalld will only check that the included service is a valid service if it's applied to a zone.

### helper
Is an optional empty-element tag and can be used several times to have more than one helper entry. An helper entry has exactly one attribute:

name="string"

The helper can be any helper supported by firewalld.

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


firewalld.zone

title: firewalld.zone(5)

summary: firewalld zone configuration files

text:
# firewalld.zone(5)

## NAME
firewalld.zone - firewalld zone configuration files

## SYNOPSIS
/etc/firewalld/zones/zone.xml

/usr/lib/firewalld/zones/zone.xml

## DESCRIPTION
A firewalld zone configuration file contains the information for a zone. These are the zone description, services, ports, protocols, icmp-blocks, masquerade, forward-ports, intra-zone forwarding and rich language rules in an XML file format. The file name has to be zone_name.xml where length of zone_name is currently limited to 17 chars.

This is the structure of a zone configuration file:

```
<?xml version="1.0" encoding="utf-8"?>
<zone [version="versionstring"] [target="ACCEPT|%%REJECT%%|DROP"] [ingress-priority="priority"] [egress-priority="priority"]>

    [ <interface name="string"/> ]

    [ <source address="address[/mask]"|mac="MAC"|ipset="ipset"/> ]

    [ <icmp-block-inversion/> ]

    [ <forward/> ]

    [ <short>short description</short> ]

    [ <description>description</description> ]

    [ <service name="string"/> ]

    [ <port port="portid[-portid]" protocol="tcp|udp|sctp|dccp"/> ]

    [ <protocol value="protocol"/> ]

    [ <icmp-block name="string"/> ]

    [ <masquerade/> ]

    [ <forward-port port="portid[-portid]" protocol="tcp|udp|sctp|dccp" [to-port="portid[-portid]"] [to-addr="IP address"]/> ]

    [ <source-port port="portid[-portid]" protocol="tcp|udp|sctp|dccp"/> ]

    [

        <rule [family="ipv4|ipv6"] [priority="priority"]>

            [ <source address="address[/mask]"|mac="MAC"|ipset="ipset" [invert="True"]/> ]

            [ <destination address="address[/mask]"|ipset="ipset" [invert="True"]/> ]

            [

                <service name="string"/> |

                <port port="portid[-portid]" protocol="tcp|udp|sctp|dccp"/> |

                <protocol value="protocol"/> |

                <icmp-block name="icmptype"/> |

                <icmp-type name="icmptype"/> |

                <masquerade/> |

                <forward-port port="portid[-portid]" protocol="tcp|udp|sctp|dccp" [to-port="portid[-portid]"] [to-addr="address"]/>

            ]

            [

                <log [prefix="prefix text"] [level="emerg|alert|crit|err|warn|notice|info|debug"]> [<limit value="rate/duration"/>] </log> |

                <nflog [group="group id"] [prefix="prefix text"] [queue-size="threshold"]> [<limit value="rate/duration"/>] </nflog>

            ]

            [ <audit> [<limit value="rate/duration"/>] </audit> ]

            [

                <accept> [<limit value="rate/duration"/>] </accept> |

                <reject [type="rejecttype"]> [<limit value="rate/duration"/>] </reject> |

                <drop> [<limit value="rate/duration"/>] </drop> |

                <mark set="mark[/mask]"> [<limit value="rate/duration"/>] </mark>

            ]

        </rule>

    ]
</zone>

```

The config can contain these tags and attributes. Some of them are mandatory, others optional.

### zone
The mandatory zone start and end tag defines the zone. This tag can only be used once in a zone configuration file. There are optional attributes for zones:

version="string"

To give the zone a version.

target="ACCEPT|%%REJECT%%|DROP"

Can be used to accept, reject or drop every packet that doesn't match any rule (port, service, etc.). ACCEPT is special: packets which are not addressed to the host will be forwarded to their destination regardless of the zone's forward setting, or any policies attached to the zone.

If unspecified, the default behavior applies: ICMP will be accepted and everything else will be rejected.

ingress-priority="priority"

Ingress priority for classifying traffic into a zone. A zone with a lower priority value will be considered before a zone with a higher priority value. This allows custom ordering of zone dispatch.

egress-priority="priority"

Same as ingress-priority, but for egress classification.

### interface
Is an optional empty-element tag and can be used several times. It can be used to bind an interface to a zone. You don't need this for NetworkManager-managed interfaces, because NetworkManager binds interfaces to zones automatically. See also 'How to set or change a zone for a connection?' in firewalld.zones(5). You can use it as a fallback mechanism for interfaces that can't be managed via NetworkManager. An interface entry has exactly one attribute:

name="string"

The name of the interface to be bound to the zone.

### source
Is an optional empty-element tag and can be used several times. It can be used to bind a source address, address range, a MAC address or an ipset to a zone. A source entry has exactly one of these attributes:

address="address[/mask]"

The source is either an IP address or a network IP address with a mask for IPv4 or IPv6. The network family (IPv4/IPv6) will be automatically discovered. For IPv4, the mask can be a network mask or a plain number. For IPv6 the mask is a plain number. The use of host names is not supported.

mac="MAC"

The source is a MAC address. It must be of the form XX:XX:XX:XX:XX:XX.

ipset="ipset"

The source is an ipset.

### icmp-block-inversion
Is an optional empty-element tag and can be used only once in a zone configuration. This flag inverts the icmp block handling. Only enabled ICMP types are accepted and all others are rejected in the zone.

### forward
Is an optional empty-element tag and can be used only once in a zone configuration. This flag enables intra-zone forwarding. When enabled, packets will be forwarded between interfaces or sources within a zone, even if the zone's target is not set to ACCEPT.

### short
Is an optional start and end tag and is used to give a more readable name.

### description
Is an optional start and end tag to have a description.

### service
Is an optional empty-element tag and can be used several times to have more than one service entry enabled. A service entry has exactly one attribute:

name="string"

The name of the service to be enabled. To get a list of valid service names firewall-cmd --get-services can be used.

### port
Is an optional empty-element tag and can be used several times to have more than one port entry. All attributes of a port entry are mandatory:

port="portid[-portid]"

The port can either be a single port number portid or a port range portid-portid.

protocol="tcp|udp|sctp|dccp"

The protocol can either be tcp, udp, sctp or dccp.

### protocol
Is an optional empty-element tag and can be used several times to have more than one protocol entry. All protocol has exactly one attribute:

value="string"

The protocol can be any protocol supported by the system. Please have a look at /etc/protocols for supported protocols.

### icmp-block
Is an optional empty-element tag and can be used several times to have more than one icmp-block entry. Each icmp-block tag has exactly one mandatory attribute:

name="string"

The name of the Internet Control Message Protocol (ICMP) type to be blocked. To get a list of valid ICMP types firewall-cmd --get-icmptypes can be used.

### masquerade
Is an optional empty-element tag. It can be used only once. If it's present masquerading is enabled.

### forward-port
Is an optional empty-element tag and can be used several times to have more than one port or packet forward entry. There are mandatory and also optional attributes for forward ports:

Mandatory attributes:

The local port and protocol to be forwarded.

port="portid[-portid]"

The port can either be a single port number portid or a port range portid-portid.

protocol="tcp|udp|sctp|dccp"

The protocol can either be tcp, udp, sctp or dccp.

Optional attributes:

The destination of the forward. For local forwarding add to-port only. For remote forwarding add to-addr and use to-port optionally if the destination port on the destination machine should be different.

to-port="portid[-portid]"

The destination port or port range to forward to. If omitted, the value of the port= attribute will be used altogether with the to-addr attribute.

to-addr="address"

The destination IP address either for IPv4 or IPv6.

### source-port
Is an optional empty-element tag and can be used several times to have more than one source port entry. All attributes of a source port entry are mandatory:

port="portid[-portid]"

The port can either be a single port number portid or a port range portid-portid.

protocol="tcp|udp|sctp|dccp"

The protocol can either be tcp, udp, sctp or dccp.

### rule
Is an optional element tag and can be used several times to have more than one rich language rule entry.

The general rule structure:

```
<rule [family="ipv4|ipv6"] [priority="priority"]>

    [ <source address="address[/mask]"|mac="MAC"|ipset="ipset" [invert="True"]/> ]

    [ <destination address="address[/mask]"|ipset="ipset" [invert="True"]/> ]

    [

        <service name="string"/> |

        <port port="portid[-portid]" protocol="tcp|udp|sctp|dccp"/> |

        <protocol value="protocol"/> |

        <icmp-block name="icmptype"/> |

        <icmp-type name="icmptype"/> |

        <masquerade/> |

        <forward-port port="portid[-portid]" protocol="tcp|udp|sctp|dccp" [to-port="portid[-portid]"] [to-addr="address"]/> |

        <source-port port="portid[-portid]" protocol="tcp|udp|sctp|dccp"/> |

    ]

    [

        <log [prefix="prefix text"] [level="emerg|alert|crit|err|warn|notice|info|debug"]> [<limit value="rate/duration"/>] </log> |

        <nflog [group="group id"] [prefix="prefix text"] [queue-size="threshold"]> [<limit value="rate/duration"/>] </nflog>

    ]

    [ <audit> [<limit value="rate/duration"/>] </audit> ]

    [

        <accept> [<limit value="rate/duration"/>] </accept> |

        <reject [type="rejecttype"]> [<limit value="rate/duration"/>] </reject> |

        <drop> [<limit value="rate/duration"/>] </drop> |

        <mark set="mark[/mask]"> [<limit value="rate/duration"/>] </mark>

    ]
</rule>

```

Rule structure for source black or white listing:

```
<rule [family="ipv4|ipv6"] [priority="priority"]>

    <source address="address[/mask]"|mac="MAC"|ipset="ipset" [invert="True"]/>

    [

        <log [prefix="prefix text"] [level="emerg|alert|crit|err|warn|notice|info|debug"]> [<limit value="rate/duration"/>] </log> |

        <nflog [group="group id"] [prefix="prefix text"] [queue-size="threshold"]> [<limit value="rate/duration"/>] </nflog>

    ]

    [ <audit> [<limit value="rate/duration"/>] </audit> ]

    <accept> [<limit value="rate/duration"/>] </accept> |

    <reject [type="rejecttype"]> [<limit value="rate/duration"/>] </reject> |

    <drop> [<limit value="rate/duration"/>] </drop>
</rule>

```

For a full description on rich language rules, please have a look at firewalld.richlanguage(5).

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


firewalld.zones

title: firewalld.zones(5)

summary: firewalld zones

text:
# firewalld.zones(5)

## NAME
firewalld.zones - firewalld zones

## DESCRIPTION

### What is a zone?
A network zone defines the level of trust for network connections. This is a one to many relation, which means that a connection can only be part of one zone, but a zone can be used for many network connections.

The zone defines the firewall features that are enabled in this zone:

Intra Zone Forwarding

Allows packets received by a zone to be forwarded to other interfaces or sources within the same zone, even if the zone's target is not ACCEPT.

Predefined services

A service is a combination of port and/or protocol entries. Optionally netfilter helper modules can be added and also a IPv4 and IPv6 destination address.

Ports and protocols

Definition of tcp, udp, sctp or dccp ports, where ports can be a single port or a port range.

ICMP blocks

Blocks selected Internet Control Message Protocol (ICMP) messages. These messages are either information requests or created as a reply to information requests or in error conditions.

ICMP block inversion

Changes how ICMP messages are handled. When enabled, all ICMP message types are blocked, except for those in the ICMP block list.

Masquerading

The addresses of a private network are mapped to and hidden behind a public IP address. This is a form of address translation.

Forward ports

A forward port is either mapped to the same port on another host or to another port on the same host or to another port on another host.

Rich language rules

The rich language extends the elements (service, port, icmp-block, masquerade, forward-port and source-port) with additional source and destination addresses, logging, actions and limits for logs and actions. It can also be used for host or network white and black listing (for more information, please have a look at firewalld.richlanguage(5)).

For more information on the zone file format, please have a look at firewalld.zone(5).

### Which zones are available?
Here are the zones provided by firewalld sorted according to the default trust level of the zones from untrusted to trusted:

drop

Any incoming network packets are dropped, there is no reply. Only outgoing network connections are possible.

block

Any incoming network connections are rejected with an icmp-host-prohibited message for IPv4 and icmp6-adm-prohibited for IPv6. Only network connections initiated within this system are possible.

public

For use in public areas. You do not trust the other computers on networks to not harm your computer. Only selected incoming connections are accepted.

external

For use on external networks with masquerading enabled especially for routers. You do not trust the other computers on networks to not harm your computer. Only selected incoming connections are accepted.

dmz

For computers in your demilitarized zone that are publicly-accessible with limited access to your internal network. Only selected incoming connections are accepted.

work

For use in work areas. You mostly trust the other computers on networks to not harm your computer. Only selected incoming connections are accepted.

home

For use in home areas. You mostly trust the other computers on networks to not harm your computer. Only selected incoming connections are accepted.

internal

For use on internal networks. You mostly trust the other computers on the networks to not harm your computer. Only selected incoming connections are accepted.

trusted

All network connections are accepted. Packets not addressed to this host will be forwarded.

### Which zone should be used?
A public WIFI network connection for example should be mainly untrusted, a wired home network connection should be fairly trusted. Select the zone that best matches the network you are using.

### How to configure or add zones?
To configure or add zones you can either use one of the firewalld interfaces to handle and change the configuration: These are the graphical configuration tool firewall-config, the command line tool firewall-cmd or the D-Bus interface. Or you can create or copy a zone file in one of the configuration directories. /usr/lib/firewalld/zones is used for default and fallback configurations and /etc/firewalld/zones is used for user created and customized configuration files.

### How to set or change a zone for a connection?
The zone is stored into the ifcfg of the connection with ZONE= option. If the option is missing or empty, the default zone set in firewalld is used.

If the connection is controlled by NetworkManager, you can also use nm-connection-editor to change the zone.

For the addition or change of interfaces that are not under control of NetworkManager: firewalld tries to change the ZONE setting in the ifcfg file, if an ifcfg file exists that is using the interface.

Only for the removal of interfaces that are not under control of NetworkManager: firewalld is not trying to change the ZONE setting in the ifcfg file. This is needed to make sure that an ifdown of the interface will not result in a reset of the zone setting to the default zone. Only the zone binding is then removed in firewalld then.

## SEE ALSO
firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

## NOTES
firewalld home page:

http://firewalld.org

## AUTHORS
Thomas Woerner <twoerner@redhat.com>

Developer

Jiri Popelka <jpopelka@redhat.com>

Developer

Eric Garver <eric@garver.life>

Developer


flatpak-installation

package: flatpak

title: flatpak-installation(5)

text:
# flatpak-installation(5)

## NAME
flatpak-installation - Configuration for an installation location

## DESCRIPTION
flatpak can operate in system-wide or per-user mode. The system-wide data is located in $prefix/var/lib/flatpak/, and the per-user data is in $HOME/.local/share/flatpak/.

In addition to the default installation locations, more system-wide installations can be defined via configuration files /etc/flatpak/installations.d/, which must have the .conf extension and follow the format described below.

## FILE FORMAT
The installation config file format is using the same .ini file format that is used for systemd unit files or application .desktop files.

### [Installation ...]
All the configuration for the the installation location with name NAME is contained in the [Installation "NAME"] group.

The following keys are recognized:

Path (string)

The path for this installation. This key is mandatory.

DisplayName (string)

The name to use when showing this installation in the UI.

Priority (integer)

A priority for this installation.

StorageType (string)

The type of storage used for this installation. Possible values include: network, mmc, sdcard, harddisk.

## EXAMPLES

```
[Installation "extra"]
Path=/location/of/sdcard
DisplayName=Extra Installation
StorageType=sdcard
```


flatpak-metadata

title: flatpak-metadata(5)

text:
# flatpak-metadata(5)

## NAME
flatpak-metadata - Information about an application or runtime

## DESCRIPTION
Flatpak uses metadata files to describe applications and runtimes. The metadata file for a deployed application or runtime is placed in the toplevel deploy directory. For example, the metadata for the locally installed application org.gnome.Calculator is in ~/.local/share/flatpak/app/org.gnome.Calculator/current/active/metadata.

Most aspects of the metadata configuration can be overridden when launching applications, either temporarily via options of the flatpak run command, or permanently with the flatpak override command.

A metadata file describing the effective configuration is available inside the running sandbox at /.flatpak-info. For compatibility with older Flatpak versions, /run/user/$UID/flatpak-info is a symbolic link to the same file.

## FILE FORMAT
The metadata file is using the same .ini file format that is used for systemd unit files or application .desktop files.

### [Application] or [Runtime]
Metadata for applications starts with an [Application] group, metadata for runtimes with a [Runtime] group.

The following keys can be present in these groups:

name (string)

The name of the application or runtime. This key is mandatory.

runtime (string)

The fully qualified name of the runtime that is used by the application. This key is mandatory for applications.

sdk (string)

The fully qualified name of the sdk that matches the runtime. Available since 0.1.

command (string)

The command to run. Only relevant for applications. Available since 0.1.

required-flatpak (string list)

The required version of Flatpak to run this application or runtime. For applications, this was available since 0.8.0. For runtimes, this was available since 0.9.1, and backported to 0.8.3 for the 0.8.x branch. Flatpak after version 1.4.3 and 1.2.5 support multiple versions here. This can be useful if you need to support features that are backported to a previous stable series. For example if you want to use a feature added in 1.6.0 that was also backported to 1.4.4 you would use 1.6.0;1.4.4;. Note that older versions of flatpak will just use the first element in the list, so make that the largest version.

tags (string list)

Tags to include in AppStream XML. Typical values in use on Flathub include beta, stable, proprietary and upstream-maintained. Available since 0.4.12.

### [Context]
This group determines various system resources that may be shared with the application when it is run in a flatpak sandbox.

All keys in this group (and the group itself) are optional.

shared (list)

List of subsystems to share with the host system. Possible subsystems: network, ipc. Available since 0.3.

sockets (list)

List of well-known sockets to make available in the sandbox. Possible sockets: x11, wayland, fallback-x11, pulseaudio, session-bus, system-bus, ssh-auth, pcsc, cups, gpg-agent, inherit-wayland-socket. When making a socket available, flatpak also sets well-known environment variables like DISPLAY or DBUS_SYSTEM_BUS_ADDRESS to let the application find sockets that are not in a fixed location. Available since 0.3.

devices (list)

List of devices to make available in the sandbox. This just expose the devices nodes, it doesn't grant any permission that the user doesn't already have. Possible values: dri

Graphics direct rendering (/dev/dri). Available since 0.3.

input

Input devices (/dev/input). Available since 1.15.6.

usb

USB device bus (all device nodes below /dev/bus/usb). Available since 1.15.11.

kvm

Virtualization (/dev/kvm). Available since 0.6.12.

all

All device nodes in /dev, but not /dev/shm (which is separately specified). Available since 0.6.6.

shm

Access to the host /dev/shm (/dev/shm). Available since 1.6.1.

filesystems (list)

List of filesystem subsets to make available to the application. Possible values: home

The entire home directory. Available since 0.3.

home/path

Alias for ~/path Available since 1.10. For better compatibility with older Flatpak versions, prefer to write this as ~/path.

host

The entire host file system, except for directories that are handled specially by Flatpak. In particular, this shares /home, /media, /opt, /run/media and /srv if they exist. /dev is not shared: use devices=all; instead.

Parts of /sys are always shared. This option does not make additional files in /sys available.

Additionally, this keyword provides all of the same directories in /run/host as the host-os and host-etc keywords. If this keyword is used in conjunction with one of the host- keywords, whichever access level is higher (more permissive) will be used for the directories in /run/host: for example, host:rw;host-os:ro; is equivalent to host:rw;.

These other reserved directories are currently excluded: /app, /bin, /boot, /efi, /etc, /lib, /lib32, /lib64, /proc, /root, /run, /sbin, /tmp, /usr, /var.

Available since 0.3.

host-os

The host operating system's libraries, executables and static data from /usr and the related directories /bin, /lib, /lib32, /lib64, /sbin. Additionally, this keyword provides access to a subset of /etc that is associated with packaged libraries and executables, even if the host-etc keyword was not used: /etc/ld.so.cache, (used by the dynamic linker) and /etc/alternatives (on operating systems that use it, such as Debian). To avoid conflicting with the Flatpak runtime, these are mounted in the sandbox at /run/host/usr, /run/host/etc/ld.so.cache and so on.

Available since 1.7.

host-etc

The host operating system's configuration from /etc. To avoid conflicting with the Flatpak runtime, this is mounted in the sandbox at /run/host/etc.

Available since 1.7.

xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures, xdg-public-share, xdg-videos, xdg-templates

freedesktop.org special directories[1]. Available since 0.3.

xdg-desktop/path, xdg-documents/path, etc.

Subdirectories of freedesktop.org special directories. Available since 0.4.13.

xdg-cache, xdg-config, xdg-data

Directories defined by the freedesktop.org Base Directory Specification[2]. Available since 0.6.14.

xdg-cache/path, xdg-config/path, xdg-data/path

Subdirectories of directories defined by the freedesktop.org Base Directory Specification. Available since 0.6.14.

xdg-run/path

Subdirectories of the XDG_RUNTIME_DIR defined by the freedesktop.org Base Directory Specification. Note that xdg-run on its own is not supported. Available since 0.4.13.

/path

An arbitrary absolute path. Available since 0.3.

~/path

An arbitrary path relative to the home directory. Available since 0.3.

~

The same as home. Available since 1.10. For better compatibility with older Flatpak versions, prefer to write this as home.

One of the above followed by :ro

Make the given directory available read-only.

One of the above followed by :rw

Make the given directory available read/write. This is the default.

One of the above followed by :create

Make the given directory available read/write, and create it if it does not already exist.

persistent (list)

List of homedir-relative paths to make available at the corresponding path in the per-application home directory, allowing the locations to be used for persistent data when the application does not have access to the real homedir. For instance making ".myapp" persistent would make "~/.myapp" in the sandbox a bind mount to "~/.var/app/org.my.App/.myapp", thus allowing an unmodified application to save data in the per-application location. Available since 0.3.

features (list)

List of features available or unavailable to the application, currently from the following list: devel

Allow system calls used by development-oriented tools such as perf, strace and gdb. Available since 0.6.10.

multiarch

Allow running multilib/multiarch binaries, for example i386 binaries in an x86_64 environment. Available since 0.6.12.

bluetooth

Allow the application to use bluetooth (AF_BLUETOOTH) sockets. Note, for bluetooth to fully work you must also have network access. Available since 0.11.8.

canbus

Allow the application to use canbus (AF_CAN) sockets. Note, for this work you must also have network access. Available since 1.0.3.

per-app-dev-shm

Share a single instance of /dev/shm between all instances of this application run by the same user ID, including sub-sandboxes. If the application has the shm device permission in its devices list, then this feature flag is ignored. Available since 1.12.0.

A feature can be prefixed with ! to indicate the absence of that feature, for example !devel if development and debugging are not allowed.

unset-environment (list)

A list of names of environment variables to unset. Note that environment variables to set to a value (possibly empty) appear in the [Environment] group instead.

### [Instance]
This group only appears in /.flatpak-info for a running app, and not in the metadata files written by application authors. It is filled in by Flatpak itself.

instance-id (string)

The ID of the running instance. This number is used as the name of the directory in XDG_RUNTIME_DIR/.flatpak where Flatpak stores information about this instance.

instance-path (string)

The absolute path on the host system of the app's persistent storage area in $HOME/.var.

app-path (string)

The absolute path on the host system of the app's app files, as mounted at /app inside the container. Available since 0.6.10. Since 1.12.0, if flatpak run was run with the --app-path option, this key gives the absolute path of whatever files were mounted on /app, even if that differs from the app's normal app files.

If flatpak run was run with --app-path= (resulting in an empty directory being mounted on /app), the value is set to the empty string.

original-app-path (string)

If flatpak run was run with the --app-path option, this key gives the absolute path of the app's original files, as mounted at /run/parent/app inside the container. Available since 1.12.0. If this key is missing, the app files are given by app-path.

app-commit (string)

The commit ID of the application that is running. The filename of a deployment of this commit can be found in original-app-path if present, or app-path otherwise.

app-extensions (list of strings)

A list of app extensions that are mounted into the running instance. The format for each list item is EXTENSION_ID=COMMIT. If original-app-path is present, the extensions are mounted below /run/parent/app; otherwise, they are mounted below /app.

branch (string)

The branch of the app, for example stable. Available since 0.6.10.

arch (string)

The architecture of the running instance.

flatpak-version (string)

The version number of the Flatpak version that ran this app. Available since 0.6.11.

runtime-path (string)

The absolute path on the host system of the app's runtime files, as mounted at /usr inside the container. Available since 0.6.10. Since 1.12.0, if flatpak run was run with the --usr-path option, this key gives the absolute path of whatever files were mounted on /usr, even if that differs from the app's normal runtime files.

original-runtime-path (string)

If flatpak run was run with the --runtime-path option, this key gives the absolute path of the app's original runtime, as mounted at /run/parent/usr inside the container. Available since 1.12.0. If this key is missing, the runtime files are given by runtime-path.

runtime-commit (string)

The commit ID of the runtime that is used. The filename of a deployment of this commit can be found in original-runtime-path if present, or runtime-path otherwise.

runtime-extensions (list of strings)

A list of runtime extensions that are mounted into the running instance. The format for each list item is EXTENSION_ID=COMMIT. If original-app-path is present, the extensions are mounted below /run/parent/usr; otherwise, they are mounted below /usr.

extra-args (string)

Extra arguments that were passed to flatpak run.

sandbox (boolean)

Whether the --sandbox option was passed to flatpak run.

build (boolean)

Whether this instance was created by flatpak build.

session-bus-proxy (boolean)

True if this app cannot access the D-Bus session bus directly (either it goes via a proxy, or it cannot access the session bus at all). Available since 0.8.0.

system-bus-proxy (boolean)

True if this app cannot access the D-Bus system bus directly (either it goes via a proxy, or it cannot access the system bus at all). Available since 0.8.0.

### [Session Bus Policy]
If the sockets key is not allowing full access to the D-Bus session bus, then flatpak provides filtered access.

The default policy for the session bus only allows the application to own its own application ID, its subnames and its own application ID as a subname of org.mpris.MediaPlayer2. For instance if the app is called org.my.App, it can only own org.my.App, org.my.App.* and org.mpris.MediaPlayer2.org.my.App. It is only allowed to talk to names matching those patterns, plus the bus itself (org.freedesktop.DBus) and the portal APIs (bus names of the form org.freedesktop.portal.*).

Additionally the app is always allowed to reply to messages sent to it, and emit broadcast signals (but these will not reach other sandboxed apps unless they are allowed to talk to your app.

If the [Session Bus Policy] group is present, it provides policy for session bus access.

Each key in this group has the form of a D-Bus bus name or prefix thereof, for example org.gnome.SessionManager or org.freedesktop.portal.*.

The possible values for an entry are the following, in increasing order of access. Each value implies all the access from any lower values:

none

The bus name is invisible to the application. Available since 0.2.

see

The bus name can be enumerated by the application. Available since 0.2.

talk

The application can send messages to, and receive replies and signals from, the bus name. Available since 0.2.

own

The application can own the bus name. Available since 0.2.

### [System Bus Policy]
If the sockets key is not allowing full access to the D-Bus system bus, then flatpak does not make the system bus available unless the [System Bus Policy] group is present and provides a policy for filtered access. Available since 0.2.

Entries in this group have the same form as for the [Session Bus Policy] group. However, the app has no permissions by default.

### [Environment]
The [Environment] group specifies environment variables to set when running the application. Available since 0.3.

Entries in this group have the form VAR=VALUE where VAR is the name of an environment variable to set.

Note that environment variables can also be unset (removed from the environment) by listing them in the unset-environment entry of the [Context] group.

### [Extension NAME]
Runtimes and applications can define extension points, which allow optional, additional runtimes to be mounted at a specified location inside the sandbox when they are present on the system. Typical uses for extension points include translations for applications, or debuginfo for sdks. The name of the extension point is specified as part of the group heading. Since 0.11.4, the name may optionally include a tag in the NAME in the name@tag ref syntax if you wish to use different configurations (eg, versions) of the same extension concurrently. The "tag" is effectively ignored, but is necessary in order to allow the same extension name to be specified more than once.

directory (string)

The relative path at which the extension will be mounted in the sandbox. If the extension point is for an application, the path is relative to /app, otherwise it is relative to /usr. This key is mandatory. Available since 0.1.

version (string)

The branch to use when looking for the extension. If this is not specified, it defaults to the branch of the application or runtime that the extension point is for. Available since 0.4.1.

versions (string)

The branches to use when looking for the extension. If this is not specified, it defaults to the branch of the application or runtime that the extension point is for. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.4.

add-ld-path (string)

A path relative to the extension point directory that will be appended to LD_LIBRARY_PATH. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.3.

merge-dirs (string)

A list of relative paths of directories below the extension point directory that will be merged. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.3.

download-if (string)

A condition that must be true for the extension to be auto-downloaded. As of 1.1.1 this supports multiple conditions separated by semi-colons. These are the supported conditions:

active-gl-driver

Is true if the name of the active GL driver matches the extension point basename. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.3.

active-gtk-theme

Is true if the name of the current GTK theme (via org.gnome.desktop.interface GSetting) matches the extension point basename. Added 0.10.1.

have-intel-gpu

Is true if the i915 kernel module is loaded. Added 0.10.1.

have-kernel-module-*

Is true if the suffix (case-sensitive) is found in /proc/modules. For example have-kernel-module-nvidia. Added 1.13.1.

on-xdg-desktop-*

Is true if the suffix (case-insensitively) is in the XDG_CURRENT_DESKTOP env var. For example on-xdg-desktop-GNOME-classic. Added 1.1.1.

autoprune-unless (string)

A condition that must be false for the extension to be considered unused when pruning. For example, flatpak uninstall --unused and flatpak update use this information. The only currently recognized value is active-gl-driver, which is true if the name of the active GL driver matches the extension point basename. Available since 0.11.8.

enable-if (string)

A condition that must be true for the extension to be enabled. As of 1.1.1 this supports multiple conditions separated by semi-colons. See download-if for available conditions.

subdirectory-suffix (string)

A suffix that gets appended to the directory name. This is very useful when the extension point naming scheme is "reversed". For example, an extension point for GTK+ themes would be /usr/share/themes/$NAME/gtk-3.0, which could be achieved using subdirectory-suffix=gtk-3.0. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.3.

subdirectories (boolean)

If this key is set to true, then flatpak will look for extensions whose name is a prefix of the extension point name, and mount them at the corresponding name below the subdirectory. Available since 0.1.

no-autodownload (boolean)

Whether to automatically download extensions matching this extension point when updating or installing a 'related' application or runtime. Available since 0.6.7.

locale-subset (boolean)

If set, then the extensions are partially downloaded by default, based on the currently configured locales. This means that the extension contents should be a set of directories with the language code as name. Available since 0.9.13 (and 0.6.6 for any extensions called *.Locale)

autodelete (boolean)

Whether to automatically delete extensions matching this extension point when deleting a 'related' application or runtime. Available since 0.6.7.

collection-id (string)

The ID of the collection that this extension point belongs to. If this is unspecified, it defaults to the collection ID of the application or runtime that the extension point is for. Currently, extension points must be in the same collection as the application or runtime that they are for. Available since 0.99.1.

### [ExtensionOf]
This optional group may be present if the runtime is an extension.

ref (string)

The ref of the runtime or application that this extension belongs to. Available since 0.9.1.

runtime (string)

The runtime this extension will be inside of. If it is an app extension, this is the app's runtime; otherwise, this is identical to ref, without the runtime/ prefix. Available since 1.5.0.

priority (integer)

The priority to give this extension when looking for the best match. Default is 0. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.3.

tag (string)

The tag name to use when searching for this extension's mount point in the parent flatpak. Available since 0.11.4.

### [Extra Data]
This optional group may be present if the runtime or application uses extra data that gets downloaded separately. The data in this group gets merged into the repository summary, with the xa.extra-data-sources key.

If multiple extra data sources are present, their uri, size and checksum keys are grouped together by using the same suffix. If only one extra data source is present, the suffix can be omitted.

NoRuntime (boolean)

Whether to mount the runtime while running the /app/bin/apply_extra script. Defaults to true, i.e. not mounting the runtime. Available since 0.9.1, and backported to the 0.8.x branch in 0.8.4.

uriX (string)

The uri for extra data source X. The only supported uri schemes are http and https. Available since 0.6.13.

sizeX (integer)

The size for extra data source X. Available since 0.6.13.

checksumX (string)

The sha256 sum for extra data source X. Available since 0.6.13.

### [Policy SUBSYSTEM]
Subsystems can define their own policies to be placed in a group whose name has this form. Their values are treated as lists, in which items can have their meaning negated by prepending ! to the value. They are not otherwise parsed by Flatpak. Available since 0.6.13.

### [USB Devices]
USB devices can be enumerable or hidden by the USB portal as specified by the keys in this group. The vendor and product ids are validated by Flatpak, but aren't otherwise used or parsed. This merely grant the permission to enumerate USB device for use by the portal. This does give access to the devices. Available since 1.15.11.

enumerable-devices (string list)

List of enumerable USB devices. Each element is the same syntax the arguments to `--usb`. Available since 1.15.11.

hidden-devices (string list)

List of hidden USB devices, i.e. to remove the enumarable devices list. Each element is the same syntax the arguments to `--nousb`. Hidden devices take precedence over enumerable devices. Available since 1.15.11.

## EXAMPLE

```
[Application]
name=org.gnome.Calculator
runtime=org.gnome.Platform/x86_64/3.20
sdk=org.gnome.Sdk/x86_64/3.20
command=gnome-calculator
[Context]
shared=network;ipc;
sockets=x11;wayland;
filesystems=xdg-run/dconf;~/.config/dconf:ro;
[Session Bus Policy]
ca.desrt.dconf=talk
[Environment]
DCONF_USER_CONFIG_DIR=.config/dconf
[USB Devices]
enumerable-devices=0fd9:*;
hidden-devices=0fd9:0063;
[Extension org.gnome.Calculator.Locale]
directory=share/runtime/locale
subdirectories=true
[Extension org.gnome.Calculator.Debug]
directory=lib/debug
```

## SEE ALSO
flatpak(1), flatpak-run(1), flatpak-override(1)

## NOTES
1.

freedesktop.org special directories

https://www.freedesktop.org/wiki/Software/xdg-user-dirs/

2.

freedesktop.org Base Directory Specification

https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html