From 78060c945be591b4fe8a1b0d3f206585d3948676 Mon Sep 17 00:00:00 2001
From: Eric Garver <eric@garver.life>
Date: Fri, 2 Jul 2021 11:19:18 -0400
Subject: [PATCH 37/50] docs(firewall-*cmd): client conntrack helpers must use
 a policy

Fixes: rhbz 1899933
Fixes: rhbz 1975484
(cherry picked from commit adb4ccd88e6c1fd460c9c674d89fdf89299c3970)
(cherry picked from commit 8cd0da7032080ada6b80b7f97faec6a30a8d45f5)
---
 doc/xml/firewall-cmd.xml.in      | 17 +++++++++++++++++
 doc/xml/firewall-offline-cmd.xml | 17 +++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/doc/xml/firewall-cmd.xml.in b/doc/xml/firewall-cmd.xml.in
index 691117f3dbff..8cd67e388ef5 100644
--- a/doc/xml/firewall-cmd.xml.in
+++ b/doc/xml/firewall-cmd.xml.in
@@ -634,6 +634,23 @@
 	    <para>
 	      The <option>--timeout</option> option is not combinable with the <option>--permanent</option> option.
 	    </para>
+            <para>
+              <emphasis role="bold">Note</emphasis>: Some services define connection tracking helpers.
+              Helpers that may operate in client mode (e.g. tftp) must be added to an
+              outbound policy instead of a zone to take effect for clients. Otherwise
+              the helper will not be applied to the outbound traffic. The related
+              traffic, as defined by the connection tracking helper, on the return
+              path (ingress) will be allowed by the stateful firewall rules.
+            </para>
+            <para>
+              An example of an outbound policy for connection tracking helpers:
+              <programlisting>
+# firewall-cmd --permanent --new-policy clientConntrack
+# firewall-cmd --permanent --policy clientConntrack --add-ingress-zone HOST
+# firewall-cmd --permanent --policy clientConntrack --add-egress-zone ANY
+# firewall-cmd --permanent --policy clientConntrack --add-service tftp
+              </programlisting>
+            </para>
 	  </listitem>
 	</varlistentry>
 
diff --git a/doc/xml/firewall-offline-cmd.xml b/doc/xml/firewall-offline-cmd.xml
index 92ec55be4623..8e2dd7989956 100644
--- a/doc/xml/firewall-offline-cmd.xml
+++ b/doc/xml/firewall-offline-cmd.xml
@@ -722,6 +722,23 @@
 	    <para>
 	      The service is one of the firewalld provided services. To get a list of the supported services, use <command>firewall-cmd --get-services</command>.
 	    </para>
+            <para>
+              <emphasis role="bold">Note</emphasis>: Some services define connection tracking helpers.
+              Helpers that may operate in client mode (e.g. tftp) must be added to an
+              outbound policy instead of a zone to take effect for clients. Otherwise
+              the helper will not be applied to the outbound traffic. The related
+              traffic, as defined by the connection tracking helper, on the return
+              path (ingress) will be allowed by the stateful firewall rules.
+            </para>
+            <para>
+              An example of an outbound policy for connection tracking helpers:
+              <programlisting>
+# firewall-cmd --new-policy clientConntrack
+# firewall-cmd --policy clientConntrack --add-ingress-zone HOST
+# firewall-cmd --policy clientConntrack --add-egress-zone ANY
+# firewall-cmd --policy clientConntrack --add-service tftp
+              </programlisting>
+            </para>
 	  </listitem>
 	</varlistentry>
 
-- 
2.27.0