Merge pull request #2 from vyos/master

import 2024-03

4 files changed, 240 insertions, 35 deletions

diff --git a/docs/configuration/firewall/flowtables.rst b/docs/configuration/firewall/flowtables.rst
index 8b44a9b9..bc7b9212 100644
--- a/docs/configuration/firewall/flowtables.rst
+++ b/docs/configuration/firewall/flowtables.rst
@@ -1,4 +1,4 @@
-:lastproofread: 2023-11-08
+:lastproofread: 2023-12-26
 
 .. _firewall-flowtables-configuration:
 
@@ -13,7 +13,7 @@ Overview
 ********
 
 In this section there's useful information of all firewall configuration that
-can be done regarding flowtables
+can be done regarding flowtables.
 
 .. cfgcmd:: set firewall flowtables ...
 
@@ -50,3 +50,139 @@ flowtable (flowtable miss), the packet follows the classic IP forwarding path.
 
 .. note:: **Flowtable Reference:**
    https://docs.kernel.org/networking/nf_flowtable.html
+
+
+***********************
+Flowtable Configuration
+***********************
+
+In order to use flowtables, the minimal configuration needed includes:
+
+   * Create flowtable: create flowtable, which includes the interfaces
+     that are going to be used by the flowtable.
+
+   * Create firewall rule: create a firewall rule, setting action to
+     ``offload`` and using desired flowtable for ``offload-target``.
+
+Creating a flow table:
+
+.. cfgcmd:: set firewall flowtable <flow_table_name> interface <iface>
+
+   Define interfaces to be used in the flowtable.
+
+.. cfgcmd:: set firewall flowtable <flow_table_name> description <text>
+
+Provide a description to the flow table.
+
+.. cfgcmd:: set firewall flowtable <flow_table_name> offload
+   <hardware | software>
+
+   Define type of offload to be used by the flowtable: ``hardware`` or
+   ``software``. By default, ``software`` offload is used.
+
+.. note:: **Hardware offload:** should be supported by the NICs used.
+
+Creating rules for using flow tables:
+
+.. cfgcmd:: set firewall [ipv4 | ipv4] forward filter rule <1-999999>
+   action offload
+
+   Create firewall rule in forward chain, and set action to ``offload``.
+
+.. cfgcmd:: set firewall [ipv4 | ipv4] forward filter rule <1-999999>
+   offload-target <flowtable>
+
+   Create firewall rule in forward chain, and define which flowtbale
+   should be used. Only applicable if action is ``offload``.
+
+*********************
+Configuration Example
+*********************
+
+Things to be considred in this setup:
+
+   * Two interfaces are going to be used in the flowtables: eth0 and eth1
+
+   * Minumum firewall ruleset is provided, which includes some filtering rules,
+     and appropiate rules for using flowtable offload capabilities.
+
+As described, first packet will be evaluated by all the firewall path, so
+desired connection should be explicitely accepted. Same thing should be taken
+into account for traffic in reverse order. In most cases state policies are
+used in order to accept connection in reverse patch.
+
+We will only accept traffic comming from interface eth0, protocol tcp and
+destination port 1122. All other traffic traspassing the router should be
+blocked.
+
+Commands
+--------
+
+.. code-block:: none
+
+      set firewall flowtable FT01 interface 'eth0'
+      set firewall flowtable FT01 interface 'eth1'
+      set firewall ipv4 forward filter default-action 'drop'
+      set firewall ipv4 forward filter rule 10 action 'offload'
+      set firewall ipv4 forward filter rule 10 offload-target 'FT01'
+      set firewall ipv4 forward filter rule 10 state 'established'
+      set firewall ipv4 forward filter rule 10 state 'related'
+      set firewall ipv4 forward filter rule 20 action 'accept'
+      set firewall ipv4 forward filter rule 20 state 'established'
+      set firewall ipv4 forward filter rule 20 state 'related'
+      set firewall ipv4 forward filter rule 110 action 'accept'
+      set firewall ipv4 forward filter rule 110 destination address '192.0.2.100'
+      set firewall ipv4 forward filter rule 110 destination port '1122'
+      set firewall ipv4 forward filter rule 110 inbound-interface name 'eth0'
+      set firewall ipv4 forward filter rule 110 protocol 'tcp'
+
+Explanation
+-----------
+
+Analysis on what happens for desired connection:
+
+   1. First packet is received on eht0, with destination address 192.0.2.100,
+   protocol tcp and destination port 1122. Assume such destination address is
+   reachable through interface eth1.
+
+   2. Since this is the first packet, connection status of this connection,
+   so far is **new**. So neither rule 10 nor 20 are valid.
+
+   3. Rule 110 is hit, so connection is accepted.
+
+   4. Once answer from server 192.0.2.100 is seen in opposite direction,
+   connection state will be triggered to **established**, so this reply is
+   accepted in rule 10.
+
+   5. Second packet for this connection is received by the router. Since
+   connection state is **established**, then rule 10 is hit, and a new entry
+   in the flowtable FT01 is added for this connection.
+
+   6. All subsecuent packets will skip traditional path, and will be offloaded
+   and will use the **Fast Path**.
+
+Checks
+------
+
+It's time to check conntrack table, to see if any connection was accepted,
+and if was properly offloaded
+
+.. code-block:: none
+
+      vyos@FlowTables:~$ show firewall ipv4 forward filter
+      Ruleset Information
+      
+      ---------------------------------
+      ipv4 Firewall "forward filter"
+      
+      Rule     Action    Protocol      Packets    Bytes  Conditions
+      -------  --------  ----------  ---------  -------  ----------------------------------------------------------------
+      10       offload   all                 8      468  ct state { established, related }  flow add @VYOS_FLOWTABLE_FT01
+      20       accept    all                 8      468  ct state { established, related }  accept
+      110      accept    tcp                 2      120  ip daddr 192.0.2.100 tcp dport 1122 iifname "eth0"  accept
+      default  drop      all                 7      420
+      
+      vyos@FlowTables:~$ sudo conntrack -L | grep tcp
+      conntrack v1.4.6 (conntrack-tools): 5 flow entries have been shown.
+      tcp      6 src=198.51.100.100 dst=192.0.2.100 sport=41676 dport=1122 src=192.0.2.100 dst=198.51.100.100 sport=1122 dport=41676 [OFFLOAD] mark=0 use=2
+      vyos@FlowTables:~$
diff --git a/docs/configuration/firewall/global-options.rst b/docs/configuration/firewall/global-options.rst
index 316e0802..b3f311aa 100644
--- a/docs/configuration/firewall/global-options.rst
+++ b/docs/configuration/firewall/global-options.rst
@@ -1,4 +1,4 @@
-:lastproofread: 2023-11-07
+:lastproofread: 2023-12-26
 
 .. _firewall-global-options-configuration:
 
@@ -114,4 +114,34 @@ Configuration
    Enable or Disable VyOS to be :rfc:`1337` conform.
    The following system parameter will be altered:
 
-   * ``net.ipv4.tcp_rfc1337``
\ No newline at end of file
+   * ``net.ipv4.tcp_rfc1337``
+
+.. cfgcmd:: set firewall global-options state-policy established action
+   [accept | drop | reject]
+
+.. cfgcmd:: set firewall global-options state-policy established log
+
+.. cfgcmd:: set firewall global-options state-policy established log-level
+   [emerg | alert | crit | err | warn | notice | info | debug]
+
+   Set the global setting for an established connection.
+
+.. cfgcmd:: set firewall global-options state-policy invalid action
+   [accept | drop | reject]
+
+.. cfgcmd:: set firewall global-options state-policy invalid log
+
+.. cfgcmd:: set firewall global-options state-policy invalid log-level
+   [emerg | alert | crit | err | warn | notice | info | debug]
+
+   Set the global setting for invalid packets.
+
+.. cfgcmd:: set firewall global-options state-policy related action
+   [accept | drop | reject]
+
+.. cfgcmd:: set firewall global-options state-policy related log
+
+.. cfgcmd:: set firewall global-options state-policy related log-level
+   [emerg | alert | crit | err | warn | notice | info | debug]
+
+   Set the global setting for related connections.
diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst
index 3887e26a..5d9190d6 100644
--- a/docs/configuration/firewall/index.rst
+++ b/docs/configuration/firewall/index.rst
@@ -4,31 +4,32 @@
 Firewall
 ########
 
-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).
+As VyOS is based on Linux it leverages its firewall. The Netfilter project
+created iptables and its successor nftables for the Linux kernel to
+work directly on packet 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).
 
-A simplified traffic flow, based on Netfilter packet flow, is shown next, in
-order to have a full view and understanding of how packets are processed, and
-what possible paths can take.
+A simplified traffic flow diagram, based on Netfilter packet flow, is shown 
+next, in order to have a full view and understanding of how packets are 
+processed, and what possible paths traffic can take.
 
 .. figure:: /_static/images/firewall-gral-packet-flow.png
 
-Main notes regarding this packet flow and terminology used in VyOS firewall:
+The main points regarding this packet flow and terminology used in VyOS 
+firewall are covered below:
 
-   * **Bridge Port?**: choose appropiate path based on if interface were the
-     packet was received is part of a bridge, or not.
+   * **Bridge Port?**: choose appropriate path based on whether interface 
+     where the packet was received is part of a bridge, or not.
 
-If interface were the packet was received isn't part of a bridge, then packet
-is processed at the **IP Layer**:
+If the interface where the packet was received isn't part of a bridge, then 
+packetis processed at the **IP Layer**:
 
    * **Prerouting**: several actions can be done in this stage, and currently
-     these actions are defined in different parts in vyos configuration. Order
+     these actions are defined in different parts in VyOS configuration. Order
      is important, and all these actions are performed before any actions
-     define under ``firewall`` section. Relevant configuration that acts in
+     defined under ``firewall`` section. Relevant configuration that acts in
      this stage are:
 
       * **Conntrack Ignore**: rules defined under ``set system conntrack ignore
@@ -40,12 +41,12 @@ is processed at the **IP Layer**:
       * **Destination NAT**: rules defined under ``set [nat | nat66]
         destination...``.
 
-   * **Destination is the router?**: choose appropiate path based on
-     destination IP address. Transit forward continunes to **forward**,
+   * **Destination is the router?**: choose appropriate path based on
+     destination IP address. Transit forward continues to **forward**,
      while traffic that destination IP address is configured on the router
      continues to **input**.
 
-   * **Input**: stage where traffic destinated to the router itself can be
+   * **Input**: stage where traffic destined for the router itself can be
      filtered and controlled. This is where all rules for securing the router
      should take place. This includes ipv4 and ipv6 filtering rules, defined
      in:
@@ -61,14 +62,14 @@ is processed at the **IP Layer**:
 
      * ``set firewall ipv6 forward filter ...``.
 
-   * **Output**: stage where traffic that is originated by the router itself
-     can be filtered and controlled. Bare in mind that this traffic can be a
-     new connection originted by a internal process running on VyOS router,
-     such as NTP, or can be a response to traffic received externaly through
-     **inputt** (for example response to an ssh login attempt to the router).
+   * **Output**: stage where traffic that originates from the router itself
+     can be filtered and controlled. Bear in mind that this traffic can be a
+     new connection originated by a internal process running on VyOS router,
+     such as NTP, or a response to traffic received externaly through
+     **input** (for example response to an ssh login attempt to the router).
      This includes ipv4 and ipv6 filtering rules, defined in:
 
-     * ``set firewall ipv4 input filter ...``.
+     * ``set firewall ipv4 output filter ...``.
 
      * ``set firewall ipv6 output filter ...``.
 
@@ -79,16 +80,16 @@ is processed at the **IP Layer**:
      * **Source NAT**: rules defined under ``set [nat | nat66]
        destination...``.
 
-If interface were the packet was received is part of a bridge, then packet
-is processed at the **Bridge Layer**, which contains a ver basic setup where
-for bridge filtering:
+If the interface where the packet was received is part of a bridge, then 
+the packet is processed at the **Bridge Layer**, which contains a basic setup for
+bridge filtering:
 
-   * **Forward (Bridge)**: stage where traffic that is trasspasing through the
+   * **Forward (Bridge)**: stage where traffic that is trespasing through the
      bridge is filtered and controlled:
 
      * ``set firewall bridge forward filter ...``.
 
-Main structure VyOS firewall cli is shown next:
+The main structure of the VyOS firewall CLI is shown next:
 
 .. code-block:: none
 
@@ -134,7 +135,7 @@ Main structure VyOS firewall cli is shown next:
             - custom_zone_name
                + ...
 
-Please, refer to appropiate section for more information about firewall
+Please, refer to appropriate section for more information about firewall
 configuration:
 
 .. toctree::
diff --git a/docs/configuration/firewall/zone.rst b/docs/configuration/firewall/zone.rst
index 1ab9c630..059b029d 100644
--- a/docs/configuration/firewall/zone.rst
+++ b/docs/configuration/firewall/zone.rst
@@ -123,3 +123,41 @@ written from the perspective of: *Source Zone*-to->*Destination Zone*
       set firewall zone DMZ from LAN firewall name LANv4-to-DMZv4
       set firewall zone LAN from DMZ firewall name DMZv4-to-LANv4
 
+**************
+Operation-mode
+**************
+
+.. opcmd:: show firewall zone-policy
+
+   This will show you a basic summary of zones configuration.
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show firewall zone-policy
+      Zone    Interfaces    From Zone    Firewall IPv4    Firewall IPv6
+      ------  ------------  -----------  ---------------  ---------------
+      LAN     eth1          WAN          WAN_to_LAN
+              eth2
+      LOCAL   LOCAL         LAN          LAN_to_LOCAL
+                            WAN          WAN_to_LOCAL     WAN_to_LOCAL_v6
+      WAN     eth3          LAN          LAN_to_WAN
+              eth0          LOCAL        LOCAL_to_WAN
+      vyos@vyos:~$
+
+.. opcmd:: show firewall zone-policy zone <zone>
+
+   This will show you a basic summary of a particular zone.
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show firewall zone-policy zone WAN
+      Zone    Interfaces    From Zone    Firewall IPv4    Firewall IPv6
+      ------  ------------  -----------  ---------------  ---------------
+      WAN     eth3          LAN          LAN_to_WAN
+              eth0          LOCAL        LOCAL_to_WAN
+      vyos@vyos:~$ show firewall zone-policy zone LOCAL
+      Zone    Interfaces    From Zone    Firewall IPv4    Firewall IPv6
+      ------  ------------  -----------  ---------------  ---------------
+      LOCAL   LOCAL         LAN          LAN_to_LOCAL
+                            WAN          WAN_to_LOCAL     WAN_to_LOCAL_v6
+      vyos@vyos:~$