From 8d899360b8cd33962fa0b73cc17d2b8bb7710252 Mon Sep 17 00:00:00 2001
From: Eric Garver <eric@garver.life>
Date: Wed, 19 Feb 2020 09:48:01 -0500
Subject: [PATCH] doc: direct: add CAVEATS section
This basically covers issues/questions users have been asking about
direct rules and the nftables backend.
Fixes: #555
Fixes: rhbz 1692964
(cherry picked from commit dbcba0433b9986b6da2172bc9a826836af2be9b0)
(cherry picked from commit 0e826f0681da9917f29f26cfdd881f490a210f31)
---
doc/xml/firewall-cmd.xml.in | 3 ++
doc/xml/firewall-offline-cmd.xml | 3 ++
doc/xml/firewalld.direct.xml | 63 ++++++++++++++++++++++++++++++++
3 files changed, 69 insertions(+)
diff --git a/doc/xml/firewall-cmd.xml.in b/doc/xml/firewall-cmd.xml.in
index 3562b4cc7fdc..be65d61166c2 100644
--- a/doc/xml/firewall-cmd.xml.in
+++ b/doc/xml/firewall-cmd.xml.in
@@ -1810,6 +1810,9 @@ For interfaces that are not under control of NetworkManager, firewalld tries to
<para>
Direct options should be used only as a last resort when it's not possible to use for example <option>--add-service</option>=<replaceable>service</replaceable> or <option>--add-rich-rule</option>='<replaceable>rule</replaceable>'.
</para>
+ <para>
+ <emphasis role="bold">Warning</emphasis>: Direct rules behavior is different depending on the value of <literal>FirewallBackend</literal>. See <literal>CAVEATS</literal> in <citerefentry><refentrytitle>firewalld.direct</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ </para>
<para>
The first argument of each option has to be <literal>ipv4</literal> or <literal>ipv6</literal> or <literal>eb</literal>. With <literal>ipv4</literal> it will be for IPv4 (<citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>), with <literal>ipv6</literal> for IPv6 (<citerefentry><refentrytitle>ip6tables</refentrytitle><manvolnum>8</manvolnum></citerefentry>) and with <literal>eb</literal> for ethernet bridges (<citerefentry><refentrytitle>ebtables</refentrytitle><manvolnum>8</manvolnum></citerefentry>).
</para>
diff --git a/doc/xml/firewall-offline-cmd.xml b/doc/xml/firewall-offline-cmd.xml
index eb2fd75e231c..16159748aea0 100644
--- a/doc/xml/firewall-offline-cmd.xml
+++ b/doc/xml/firewall-offline-cmd.xml
@@ -1784,6 +1784,9 @@
<para>
Direct options should be used only as a last resort when it's not possible to use for example <option>--add-service</option>=<replaceable>service</replaceable> or <option>--add-rich-rule</option>='<replaceable>rule</replaceable>'.
</para>
+ <para>
+ <emphasis role="bold">Warning</emphasis>: Direct rules behavior is different depending on the value of <literal>FirewallBackend</literal>. See <literal>CAVEATS</literal> in <citerefentry><refentrytitle>firewalld.direct</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ </para>
<para>
The first argument of each option has to be <literal>ipv4</literal> or <literal>ipv6</literal> or <literal>eb</literal>. With <literal>ipv4</literal> it will be for IPv4 (<citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>), with <literal>ipv6</literal> for IPv6 (<citerefentry><refentrytitle>ip6tables</refentrytitle><manvolnum>8</manvolnum></citerefentry>) and with <literal>eb</literal> for ethernet bridges (<citerefentry><refentrytitle>ebtables</refentrytitle><manvolnum>8</manvolnum></citerefentry>).
</para>
diff --git a/doc/xml/firewalld.direct.xml b/doc/xml/firewalld.direct.xml
index d4e5cd74d590..de7b5973dd7f 100644
--- a/doc/xml/firewalld.direct.xml
+++ b/doc/xml/firewalld.direct.xml
@@ -206,6 +206,69 @@
</refsect1>
+ <refsect1 id="caveats">
+ <title>Caveats</title>
+
+ <para>
+ Depending on the value of <literal>FirewallBackend</literal> (see <citerefentry><refentrytitle>firewalld.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) direct rules behave differently in some scenarios.
+ </para>
+ <refsect2 id="Packet accept/drop precedence">
+ <title>Packet accept/drop precedence</title>
+ <para>
+ Due to implementation details of netfilter inside the kernel, if <literal>FirewallBackend=nftables</literal> is used direct rules that <literal>ACCEPT</literal> 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.
+ </para>
+ <para>
+ There are a handful of options to workaround the <literal>ACCEPT</literal> issue:
+ </para>
+ <orderedlist>
+ <listitem><para>Rich Rules</para>
+ <para>
+ If a rich rule can be used, then they should always be preferred over direct rules. Rich Rules will be converted to the enabled <literal>FirewallBackend</literal>. See <citerefentry><refentrytitle>firewalld.richlanguage</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ </para>
+ </listitem>
+ <listitem><para>Blanket Accept</para>
+ <para>
+ Users can add an explicit accept to the nftables ruleset. This can be done by adding the interface or source to the <literal>trusted</literal> zone.
+ </para>
+ <para>
+ This strategy is often employed by things that perform their own filtering such as: libvirt, podman, docker.
+ </para>
+ <para>
+ <emphasis role="bold">Warning</emphasis>: This means firewalld will do no filtering on these packets. It must all be done via direct rules or out-of-band iptables rules.
+ </para>
+ </listitem>
+ <listitem><para>Selective Accept</para>
+ <para>
+ Alternatively, enable only the relevant service, port, address, or otherwise in the appropriate zone.
+ </para>
+ </listitem>
+ <listitem><para>Revert to the iptables backend</para>
+ <para>
+ A last resort is to revert to the iptables backend by setting <literal>FirewallBackend=iptables</literal>. Users should be aware that firewalld development focuses on the nftables backend.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ For direct rules that <literal>DROP</literal> packets the packets are immediately dropped regardless of the value of <literal>FirewallBackend</literal>. As such, there is no special consideration needed.
+ </para>
+
+ <para>
+ Firewalld guarantees the above ACCEPT/DROP behavior by registering nftables hooks with a lower precedence than iptables hooks.
+ </para>
+ </refsect2>
+
+ <refsect2 id="Direct interface precedence">
+ <title>Direct interface precedence</title>
+ <para>
+ With <literal>FirewallBackend=iptables</literal> 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.
+ </para>
+ <para>
+ With <literal>FirewallBackend=nftables</literal> direct rules were deliberately given a higher precedence than all other firewalld rules. This includes rules to accept existing connections.
+ </para>
+ </refsect2>
+ </refsect1>
+
<refsect1 id="example">
<title>Example</title>
--
2.23.0