Merge pull request #1088 from Nephiaust/2023-FirewallUpdates

Updates to the firewall pages

4 files changed, 98 insertions, 44 deletions

diff --git a/docs/configuration/firewall/general-legacy.rst b/docs/configuration/firewall/general-legacy.rst
index 041dd8aa..5d235eb8 100644
--- a/docs/configuration/firewall/general-legacy.rst
+++ b/docs/configuration/firewall/general-legacy.rst
@@ -1,10 +1,10 @@
 :lastproofread: 2021-06-29
 
-.. _firewall-legacy:
+.. _legacy-firewall:
 
-###############
-Firewall-Legacy
-###############
+###################################
+Firewall Configuration (Deprecated)
+###################################
 
 .. note:: **Important note:**
    This documentation is valid only for VyOS Sagitta prior to
diff --git a/docs/configuration/firewall/general.rst b/docs/configuration/firewall/general.rst
index d2bc1435..3fe876f2 100644
--- a/docs/configuration/firewall/general.rst
+++ b/docs/configuration/firewall/general.rst
@@ -1,10 +1,10 @@
-:lastproofread: 2021-06-29
+:lastproofread: 2023-09-17
 
-.. _firewall:
+.. _firewall-configuration:
 
-########
-Firewall
-########
+######################
+Firewall Configuration
+######################
 
 ********
 Overview
@@ -17,48 +17,41 @@ The firewall supports the creation of groups for addresses, domains,
 interfaces, mac-addresses, networks and port groups. This groups can be used
 later in firewall ruleset as desired.
 
-.. note:: **Important note on usage of terms:**
-   The firewall makes use of the terms `forward`, `input`, and `output`
-   for firewall policy. More information of Netfilter hooks and Linux
-   networking packet flows can be found in `Netfilter-Hooks
-   <https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks>`_
-
-
 Main structure is shown next:
 
 .. code-block:: none
 
    - set firewall
        * global-options
-           + all-ping
-           + broadcast-ping
-           + ...
+            + all-ping
+            + broadcast-ping
+            + ...
        * group
-           - address-group
-           - ipv6-address-group
-           - network-group
-           - ipv6-network-group
-           - interface-group
-           - mac-group
-           - port-group
-           - domain-group
+            - address-group
+            - ipv6-address-group
+            - network-group
+            - ipv6-network-group
+            - interface-group
+            - mac-group
+            - port-group
+            - domain-group
        * ipv4
-           - forward
+            - forward
                + filter
-           - input
+            - input
                + filter
-           - output
+            - output
                + filter
-           - name
+            - name
                + custom_name
        * ipv6
-           - forward
+            - forward
                + filter
-           - input
+            - input
                + filter
-           - output
+            - output
                + filter
-           - ipv6-name
+            - ipv6-name
                + custom_name
 
 Where, main key words and configuration paths that needs to be understood:
diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst
index 567e48a0..4b923143 100644
--- a/docs/configuration/firewall/index.rst
+++ b/docs/configuration/firewall/index.rst
@@ -1,24 +1,85 @@
+:lastproofread: 2023-09-17
+
 ########
 Firewall
 ########
 
-Starting from VyOS 1.4-rolling-202308040557, a new firewall structure
-can be found on all vyos installations. Documentation for most new firewall
-cli can be found here:
+.. attention:: 
+   Starting from VyOS 1.4-rolling-202308040557, a new firewall structure
+   can be found on all vyos installations.
+
+.. note:: 
+   The legacy and zone-based firewall configuration options is not longer
+   supported. They are here for reference purposes only.
 
+Netfilter based
+^^^^^^^^^^^^^^^
 .. toctree::
    :maxdepth: 1
    :includehidden:
 
    general
 
-Also, for those who haven't updated to newer version, legacy documentation is
-still present and valid for all sagitta version prior to VyOS
-1.4-rolling-202308040557:
+With VyOS being based on top of Linux and its kernel, the Netfilter project created
+the iptables and now the successor nftables for the Linux kernel to work directly
+on the data flows. This now extends the concept of zone-based security to allow
+for manipulating the data at multiple stages once accepted by the network interface
+and the driver before being handed off to the destination (e.g. a web server OR
+another device).
+
+To configure VyOS with the new :doc:`firewall configuration </configuration/firewall/general>`
+
+The only stages VyOS will process as part of the firewall configuration is the 
+`forward` (F4 stage), `input` (L4 stage), and `output` (L5 stage). All the other
+stages and steps are for reference and cant be manipulated through VyOS.
+
+In this example image, a simplifed traffic flow is shown to help provide context
+to the terms of `forward`, `input`, and `output` for the new firewall CLI format.
 
+.. figure:: /_static/images/firewall-netfilter.png
+
+.. note:: **For more information**
+   of Netfilter hooks and Linux networking packet flows can be
+   found in `Netfilter-Hooks
+   <https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks>`_
+
+Legacy Firewall
+^^^^^^^^^^^^^^^
 .. toctree::
    :maxdepth: 1
    :includehidden:
 
    general-legacy
+
+Traditionally firewalls weere configured with the concept of data going in and
+out of an interface. The router just listened to the data flowing through and
+responding as required if it was directed at the router itself.
+
+To configure VyOS with the :doc:`legacy firewall configuration </configuration/firewall/general-legacy>`
+
+As the example image below shows, the device was configured with rules blocking
+inbound or outbound traffic on each interface.
+
+.. figure:: /_static/images/firewall-traditional.png
+
+Zone-based firewall
+^^^^^^^^^^^^^^^^^^^
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
    zone
+
+With zone-based firewalls a new concept was implemented, in addtion to the standard
+in and out traffic flows, a local flow was added. This local was for traffic
+originating and destined to the router itself. Which means additional rules were 
+required to secure the firewall itself from the network, in addition to the existing
+inbound and outbound rules from the traditional concept above.
+
+To configure VyOS with the :doc:`zone-based firewall configuration </configuration/firewall/zone>`
+
+As the example image below shows, the device now needs rules to allow/block traffic
+to or from the services running on the device that have open connections on that
+interface.
+
+.. figure:: /_static/images/firewall-zonebased.png
diff --git a/docs/configuration/firewall/zone.rst b/docs/configuration/firewall/zone.rst
index a2069e0d..38869c32 100644
--- a/docs/configuration/firewall/zone.rst
+++ b/docs/configuration/firewall/zone.rst
@@ -2,9 +2,9 @@
 
 .. _firewall-zone:
 
-###################
-Zone Based Firewall
-###################
+################################
+Zone Based Firewall (Deprecated)
+################################
 
 .. note:: Starting from VyOS 1.4-rolling-202308040557, a new firewall
    structure can be found on all vyos instalations, and zone based firewall is