7 files changed, 151 insertions, 13 deletions
diff --git a/docs/_static/images/firewall-and-vrf-blueprints.png b/docs/_static/images/firewall-and-vrf-blueprints.png
new file mode 100644
index 00000000..8c3bf9f2
--- /dev/null
+++ b/docs/_static/images/firewall-and-vrf-blueprints.png
diff --git a/docs/configexamples/firewall.rst b/docs/configexamples/firewall.rst
new file mode 100644
index 00000000..e0a4ca55
--- /dev/null
+++ b/docs/configexamples/firewall.rst
@@ -0,0 +1,12 @@
+:lastproofread: 2024-06-14
+
+Firewall Examples
+=================
+
+This section contains examples of firewall configurations for various deployments.
+
+.. toctree::
+   :maxdepth: 2
+
+   fwall-and-vrf
+   zone-policy
diff --git a/docs/configexamples/fwall-and-vrf.rst b/docs/configexamples/fwall-and-vrf.rst
new file mode 100644
index 00000000..38663a18
--- /dev/null
+++ b/docs/configexamples/fwall-and-vrf.rst
@@ -0,0 +1,121 @@
+VRF and firewall example
+------------------------
+
+Scenario and requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example shows how to configure a VyOS router with VRFs and firewall rules.
+
+Diagram used in this example:
+
+.. image:: /_static/images/firewall-and-vrf-blueprints.png
+    :width: 80%
+    :align: center
+    :alt: Network Topology Diagram
+
+As exposed in the diagram, there are four VRFs. These VRFs are ``MGMT``,
+``WAN``, ``LAN`` and ``PROD``, and their requirements are:
+
+* VRF MGMT:
+   * Allow connections to LAN and PROD.
+   * Deny connections to internet(WAN).
+   * Allow connections to the router.
+* VRF LAN:
+   * Allow connections to PROD.
+   * Allow connections to internet(WAN).
+* VRF PROD:
+   * Only accepts connections.
+* VRF WAN:
+   * Allow connection to PROD.
+
+Configuration
+^^^^^^^^^^^^^
+
+First, we need to configure the interfaces and VRFs:
+
+.. code-block:: none
+
+  set interfaces ethernet eth1 address '10.100.100.1/24'
+  set interfaces ethernet eth1 vrf 'MGMT'
+  set interfaces ethernet eth2 vif 150 address '10.150.150.1/24'
+  set interfaces ethernet eth2 vif 150 vrf 'LAN'
+  set interfaces ethernet eth2 vif 160 address '10.160.160.1/24'
+  set interfaces ethernet eth2 vif 160 vrf 'LAN'
+  set interfaces ethernet eth2 vif 3500 address '172.16.20.1/24'
+  set interfaces ethernet eth2 vif 3500 vrf 'PROD'
+  set interfaces loopback lo
+  set interfaces pppoe pppoe0 authentication password 'p4ssw0rd'
+  set interfaces pppoe pppoe0 authentication username 'vyos'
+  set interfaces pppoe pppoe0 source-interface 'eth0'
+  set interfaces pppoe pppoe0 vrf 'WAN'
+  set vrf bind-to-all
+  set vrf name LAN protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN'
+  set vrf name LAN protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT'
+  set vrf name LAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD'
+  set vrf name LAN table '103'
+  set vrf name MGMT protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN'
+  set vrf name MGMT protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN'
+  set vrf name MGMT protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD'
+  set vrf name MGMT table '102'
+  set vrf name PROD protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN'
+  set vrf name PROD protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT'
+  set vrf name PROD protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN'
+  set vrf name PROD protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN'
+  set vrf name PROD table '104'
+  set vrf name WAN protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN'
+  set vrf name WAN protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN'
+  set vrf name WAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD'
+  set vrf name WAN table '101'
+
+And before firewall rules are shown, we need to pay attention how to configure
+and match interfaces and VRFs. In case where an interface is assigned to a
+non-default VRF, if we want to use inbound-interface or outbound-interface in
+firewall rules, we need to:
+
+* For **inbound-interface**: use the interface name with the VRF name, like
+  ``MGMT`` or ``LAN``.
+* For **outbound-interface**: use the interface name, like ``eth0``, ``vtun0``,
+  ``eth2*`` or similar. 
+
+Next, we need to configure the firewall rules. First we will define all rules
+for transit traffic between VRFs.
+
+.. code-block:: none
+
+  set firewall ipv4 forward filter default-action 'drop'
+  set firewall ipv4 forward filter default-log
+  set firewall ipv4 forward filter rule 10 action 'accept'
+  set firewall ipv4 forward filter rule 10 description 'MGMT - Allow to LAN and PROD'
+  set firewall ipv4 forward filter rule 10 inbound-interface name 'MGMT'
+  set firewall ipv4 forward filter rule 10 outbound-interface name 'eth2*'
+  set firewall ipv4 forward filter rule 99 action 'drop'
+  set firewall ipv4 forward filter rule 99 description 'MGMT - Drop all going to mgmt'
+  set firewall ipv4 forward filter rule 99 outbound-interface name 'eth1'
+  set firewall ipv4 forward filter rule 120 action 'accept'
+  set firewall ipv4 forward filter rule 120 description 'LAN - Allow to PROD'
+  set firewall ipv4 forward filter rule 120 inbound-interface name 'LAN'
+  set firewall ipv4 forward filter rule 120 outbound-interface name 'eth2.3500'
+  set firewall ipv4 forward filter rule 130 action 'accept'
+  set firewall ipv4 forward filter rule 130 description 'LAN - Allow internet'
+  set firewall ipv4 forward filter rule 130 inbound-interface name 'LAN'
+  set firewall ipv4 forward filter rule 130 outbound-interface name 'pppoe0'
+
+Also, we are adding global state policies, in order to allow established and
+related traffic, in order not to drop valid responses:
+
+.. code-block:: none
+
+  set firewall global-options state-policy established action 'accept'
+  set firewall global-options state-policy invalid action 'drop'
+  set firewall global-options state-policy related action 'accept'
+
+And finally, we need to allow input connections to the router itself only from
+vrf MGMT:
+
+.. code-block:: none
+
+  set firewall ipv4 input filter default-action 'drop'
+  set firewall ipv4 input filter default-log
+  set firewall ipv4 input filter rule 10 action 'accept'
+  set firewall ipv4 input filter rule 10 description 'MGMT - Allow input'
+  set firewall ipv4 input filter rule 10 inbound-interface name 'MGMT'
+\ No newline at end of file
diff --git a/docs/configexamples/index.rst b/docs/configexamples/index.rst
index d5973eb2..11dee806 100644
--- a/docs/configexamples/index.rst
+++ b/docs/configexamples/index.rst
@@ -8,7 +8,7 @@ This chapter contains various configuration examples:
 .. toctree::
    :maxdepth: 2
 
-   zone-policy
+   firewall
    bgp-ipv6-unnumbered
    ospf-unnumbered
    azure-vpn-bgp
diff --git a/docs/configexamples/zone-policy.rst b/docs/configexamples/zone-policy.rst
index 95648e7a..d0101ebf 100644
--- a/docs/configexamples/zone-policy.rst
+++ b/docs/configexamples/zone-policy.rst
@@ -1,20 +1,10 @@
-:lastproofread: 2021-06-29
+:lastproofread: 2024-06-14
 
 .. _examples-zone-policy:
 
 Zone-Policy example
 -------------------
 
-.. note:: Starting from VyOS 1.4-rolling-202308040557, a new firewall
-   structure can be found on all vyos installations, and zone based firewall is
-   no longer supported. Documentation for most of the new firewall CLI can be
-   found in the `firewall
-   <https://docs.vyos.io/en/latest/configuration/firewall/general.html>`_
-   chapter. The legacy firewall is still available for versions before
-   1.4-rolling-202308040557 and can be found in the :ref:`firewall-legacy`
-   chapter. The examples in this section use the legacy firewall configuration
-   commands, since this feature has been removed in earlier releases.
-
 .. note:: In :vytask:`T2199` the syntax of the zone configuration was changed.
    The zone configuration moved from ``zone-policy zone <name>`` to ``firewall
    zone <name>``.
@@ -428,4 +418,3 @@ Something like:
       address ip.of.tunnel.broker
     }
   }
-
diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst
index e53f2480..39370c86 100644
--- a/docs/configuration/firewall/ipv4.rst
+++ b/docs/configuration/firewall/ipv4.rst
@@ -732,6 +732,10 @@ geoip) to keep database and rules updated.
    For example: ``eth2*``. Prepending character ``!`` for inverted matching
    criteria is also supported. For example ``!eth2``
 
+.. note:: If an interface is attached to a non-default vrf, when using
+   **inbound-interface**, vrf name must be used. For example ``set firewall
+   ipv4 forward filter rule 10 inbound-interface name MGMT``
+
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    inbound-interface group <iface_group>
 .. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
@@ -753,6 +757,10 @@ geoip) to keep database and rules updated.
    For example: ``eth2*``. Prepending character ``!`` for inverted matching
    criteria is also supported. For example ``!eth2``
 
+.. note:: If an interface is attached to a non-default vrf, when using
+   **outbound-interface**, real interface name must be used. For example
+   ``set firewall ipv4 forward filter rule 10 outbound-interface name eth0``
+
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    outbound-interface group <iface_group>
 .. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst
index 423f3e09..511fd51f 100644
--- a/docs/configuration/firewall/ipv6.rst
+++ b/docs/configuration/firewall/ipv6.rst
@@ -723,6 +723,10 @@ geoip) to keep database and rules updated.
    For example: ``eth2*``. Prepending character ``!`` for inverted matching
    criteria is also supported. For example ``!eth2``
 
+.. note:: If an interface is attached to a non-default vrf, when using
+   **inbound-interface**, vrf name must be used. For example ``set firewall
+   ipv6 forward filter rule 10 inbound-interface name MGMT``
+
 .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
    inbound-interface group <iface_group>
 .. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
@@ -744,6 +748,10 @@ geoip) to keep database and rules updated.
    For example: ``eth2*``. Prepending character ``!`` for inverted matching
    criteria is also supported. For example ``!eth2``
 
+.. note:: If an interface is attached to a non-default vrf, when using
+   **outbound-interface**, real interface name must be used. For example
+   ``set firewall ipv6 forward filter rule 10 outbound-interface name eth0``
+
 .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
    outbound-interface group <iface_group>
 .. cfgcmd:: set firewall ipv6 output filter rule <1-999999>