Merge branch 'current' of github.com:vyos/vyos-documentation into current

1 files changed, 112 insertions, 84 deletions

diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst
index f7f98dc7..abae31a5 100644
--- a/docs/configuration/firewall/ipv4.rst
+++ b/docs/configuration/firewall/ipv4.rst
@@ -1,4 +1,4 @@
-:lastproofread: 2023-11-08
+:lastproofread: 2024-07-03
 
 .. _firewall-ipv4-configuration:
 
@@ -10,13 +10,13 @@ IPv4 Firewall Configuration
 Overview
 ********
 
-In this section there's useful information of all firewall configuration that
+In this section there's useful information on all firewall configuration that
 can be done regarding IPv4, and appropriate op-mode commands.
 Configuration commands covered in this section:
 
 .. cfgcmd:: set firewall ipv4 ...
 
-From main structure defined in
+From the main structure defined in
 :doc:`Firewall Overview</configuration/firewall/index>`
 in this section you can find detailed information only for the next part
 of the general structure:
@@ -31,37 +31,60 @@ of the general structure:
                + filter
             - output
                + filter
+               + raw
+            - prerouting
+               + raw
             - name
                + custom_name
 
-For transit traffic, which is received by the router and forwarded, base chain
-is **forward**. A simplified packet flow diagram for transit traffic is shown
-next:
+First, all traffic is received by the router, and it is processed in the
+**prerouting** section.
+
+This stage includes:
+
+   * **Firewall Prerouting**: commands found under ``set firewall ipv4
+     prerouting raw ...``
+   * :doc:`Conntrack Ignore</configuration/system/conntrack>`: ``set system
+     conntrack ignore ipv4...``
+   * :doc:`Policy Route</configuration/policy/route>`: commands found under
+     ``set policy route ...``
+   * :doc:`Destination NAT</configuration/nat/nat44>`: commands found under
+     ``set nat destination ...``
+
+For transit traffic, which is received by the router and forwarded, the base
+chain is **forward**. A simplified packet flow diagram for transit traffic is
+shown next:
 
 .. figure:: /_static/images/firewall-fwd-packet-flow.png
 
-Where firewall base chain to configure firewall filtering rules for transit
-traffic is ``set firewall ipv4 forward filter ...``, which happens in stage 5,
-highlighted with red color.
+The base firewall chain to configure filtering rules for transit traffic
+is ``set firewall ipv4 forward filter ...``, which happens in stage 5,
+highlighted in the color red.
 
-For traffic towards the router itself, base chain is **input**, while traffic
-originated by the router, base chain is **output**.
+For traffic towards the router itself, the base chain is **input**, while
+traffic originated by the router has the base chain **output**.
 A new simplified packet flow diagram is shown next, which shows the path
 for traffic destined to the router itself, and traffic generated by the
 router (starting from circle number 6):
 
 .. figure:: /_static/images/firewall-input-packet-flow.png
 
-Base chain is for traffic toward the router is ``set firewall ipv4 input
+The base chain for traffic towards the router is ``set firewall ipv4 input
 filter ...``
 
-And base chain for traffic generated by the router is ``set firewall ipv4
-output filter ...``
+And the base chain for traffic generated by the router is ``set firewall ipv4
+output ...``, where two sub-chains are available: **filter** and **raw**:
+
+* **Output Prerouting**: ``set firewall ipv4 output raw ...``.
+  As described in **Prerouting**, rules defined in this section are
+  processed before connection tracking subsystem.
+* **Output Filter**: ``set firewall ipv4 output filter ...``. Rules defined
+  in this section are processed after connection tracking subsystem.
 
 .. note:: **Important note about default-actions:**
-   If default action for any base chain is not defined, then the default
-   action is set to **accept** for that chain. For custom chains, if default
-   action is not defined, then the default-action is set to **drop**
+   If a default action for any base chain is not defined, then the default
+   action is set to **accept** for that chain. For custom chains, if the 
+   default action is not defined, then the default-action is set to **drop**
 
 Custom firewall chains can be created, with commands
 ``set firewall ipv4 name <name> ...``. In order to use
@@ -72,9 +95,9 @@ should be defined in a base chain.
 Firewall - IPv4 Rules
 *********************
 
-For firewall filtering, firewall rules needs to be created. Each rule is
+For firewall filtering, firewall rules need to be created. Each rule is
 numbered, has an action to apply if the rule is matched, and the ability
-to specify multiple criteria matchers. Data packets go through the rules
+to specify multiple matching criteria. Data packets go through the rules
 from 1 - 999999, so order is crucial. At the first match the action of the
 rule will be executed.
 
@@ -82,7 +105,7 @@ Actions
 =======
 
 If a rule is defined, then an action must be defined for it. This tells the
-firewall what to do if all criteria matchers defined for such rule do match.
+firewall what to do if all of the criteria defined for that rule match.
 
 The action can be :
 
@@ -112,8 +135,8 @@ The action can be :
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> action
    [accept | continue | drop | jump | queue | reject | return]
 
-   This required setting defines the action of the current rule. If action is
-   set to jump, then jump-target is also needed.
+   This required setting defines the action of the current rule. If the action
+   is set to jump, then a jump-target is also needed.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    jump-target <text>
@@ -125,7 +148,7 @@ The action can be :
    jump-target <text>
 
    To be used only when action is set to ``jump``. Use this command to specify
-   jump target.
+   the jump target.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    queue <0-65535>
@@ -137,7 +160,7 @@ The action can be :
    queue <0-65535>
 
    To be used only when action is set to ``queue``. Use this command to specify
-   queue target to use. Queue range is also supported.
+   the queue target to use. Queue range is also supported.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    queue-options bypass
@@ -148,7 +171,7 @@ The action can be :
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    queue-options bypass
 
-   To be used only when action is set to ``queue``. Use this command to let
+   To be used only when action is set to ``queue``. Use this command to let the
    packet go through firewall when no userspace software is connected to the
    queue.
 
@@ -177,21 +200,21 @@ not match any rule in it's chain. For base chains, possible options for
 .. cfgcmd:: set firewall ipv4 name <name> default-action
    [accept | drop | jump | queue | reject | return]
 
-   This set the default action of the rule-set if no rule matched a packet
-   criteria. If default-action is set to ``jump``, then
-   ``default-jump-target`` is also needed. Note that for base chains, default
-   action can only be set to ``accept`` or ``drop``, while on custom chain,
-   more actions are available.
+   This sets the default action of the rule-set if a packet does not match the
+   criteria of any rule. If default-action is set to ``jump``, then
+   ``default-jump-target`` is also needed. Note that for base chains, the
+   default action can only be set to ``accept`` or ``drop``, while on custom 
+   chains, more actions are available.
 
 .. cfgcmd:: set firewall ipv4 name <name> default-jump-target <text>
 
    To be used only when ``default-action`` is set to ``jump``. Use this
-   command to specify jump target for default rule.
+   command to specify the jump target for the default rule.
 
 .. note:: **Important note about default-actions:**
-   If default action for any base chain is not defined, then the default
-   action is set to **accept** for that chain. For custom chains, if default
-   action is not defined, then the default-action is set to **drop**.
+   If the default action for any base chain is not defined, then the default
+   action is set to **accept** for that chain. For custom chains if a default
+   action is not defined then the default-action is set to **drop**.
 
 Firewall Logs
 =============
@@ -205,7 +228,7 @@ log options can be defined.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> log
 
    Enable logging for the matched packet. If this configuration command is not
-   present, then log is not enabled.
+   present, then the log is not enabled.
 
 .. cfgcmd:: set firewall ipv4 forward filter default-log
 .. cfgcmd:: set firewall ipv4 input filter default-log
@@ -228,7 +251,7 @@ log options can be defined.
    log-options level [emerg | alert | crit | err | warn | notice
    | info | debug]
 
-   Define log-level. Only applicable if rule log is enable.
+   Define log-level. Only applicable if rule log is enabled.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    log-options group <0-65535>
@@ -239,7 +262,8 @@ log options can be defined.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    log-options group <0-65535>
 
-   Define log group to send message to. Only applicable if rule log is enable.
+   Define the log group to send messages to. Only applicable if rule log is
+   enabled.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    log-options snapshot-length <0-9000>
@@ -250,8 +274,8 @@ log options can be defined.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    log-options snapshot-length <0-9000>
 
-   Define length of packet payload to include in netlink message. Only
-   applicable if rule log is enable and log group is defined.
+   Define the length of packet payload to include in a netlink message. Only
+   applicable if rule log is enabled and log group is defined.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    log-options queue-threshold <0-65535>
@@ -262,8 +286,8 @@ log options can be defined.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    log-options queue-threshold <0-65535>
 
-   Define number of packets to queue inside the kernel before sending them to
-   userspace. Only applicable if rule log is enable and log group is defined.
+   Define the number of packets to queue inside the kernel before sending them
+   to userspace. Only applicable if rule log is enabled and log group is defined.
 
 Firewall Description
 ====================
@@ -288,7 +312,7 @@ every defined custom chain.
 Rule Status
 ===========
 
-When defining a rule, it is enable by default. In some cases, it is useful to
+When defining a rule, it is enabled by default. In some cases, it is useful to
 just disable the rule, rather than removing it.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> disable
@@ -312,7 +336,7 @@ There are a lot of matching criteria against which the packet can be tested.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    connection-status nat [destination | source]
 
-   Match criteria based on nat connection status.
+   Match based on nat connection status.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    connection-mark <1-2147483647>
@@ -323,7 +347,7 @@ There are a lot of matching criteria against which the packet can be tested.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    connection-mark <1-2147483647>
 
-   Match criteria based on connection mark.
+   Match based on connection mark.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    conntrack-helper <module>
@@ -422,8 +446,8 @@ There are a lot of matching criteria against which the packet can be tested.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    destination fqdn <fqdn>
 
-   Specify a Fully Qualified Domain Name as source/destination matcher. Ensure
-   router is able to resolve such dns query.
+   Specify a Fully Qualified Domain Name as source/destination to match. Ensure
+   that the router is able to resolve this dns query.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    source geoip country-code <country>
@@ -480,14 +504,13 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    source mac-address <mac-address>
 
-   Only in the source criteria, you can specify a mac-address.
+   You can only specify a source mac-address to match.
 
    .. code-block:: none
 
       set firewall ipv4 input filter rule 100 source mac-address 00:53:00:11:22:33
       set firewall ipv4 input filter rule 101 source mac-address !00:53:00:aa:12:34
 
-
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    source port [1-65535 | portname | start-end]
 .. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
@@ -506,8 +529,7 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    destination port [1-65535 | portname | start-end]
 
-   A port can be set with a port number or a name which is here
-   defined: ``/etc/services``.
+   A port can be set by number or name as defined in ``/etc/services``.
 
    .. code-block:: none
 
@@ -536,8 +558,8 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    destination group address-group <name | !name>
 
-   Use a specific address-group. Prepend character ``!`` for inverted matching
-   criteria.
+   Use a specific address-group. Prepending the character ``!`` to invert the
+   criteria to match is also supported.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    source group dynamic-address-group <name | !name>
@@ -557,8 +579,8 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    destination group dynamic-address-group <name | !name>
 
-   Use a specific dynamic-address-group. Prepend character ``!`` for inverted
-   matching criteria.
+   Use a specific dynamic-address-group. Prepending the character ``!`` to
+   invert the criteria to match is also supported.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    source group network-group <name | !name>
@@ -578,8 +600,8 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    destination group network-group <name | !name>
 
-   Use a specific network-group. Prepend character ``!`` for inverted matching
-   criteria.
+   Use a specific network-group. Prepending the character ``!`` to invert the
+   criteria to match is also supported.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    source group port-group <name | !name>
@@ -599,8 +621,8 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    destination group port-group <name | !name>
 
-   Use a specific port-group. Prepend character ``!`` for inverted matching
-   criteria.
+   Use a specific port-group. Prepending the character ``!`` to invert the
+   criteria to match is also supported.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    source group domain-group <name | !name>
@@ -620,8 +642,8 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    destination group domain-group <name | !name>
 
-   Use a specific domain-group. Prepend character ``!`` for inverted matching
-   criteria.
+   Use a specific domain-group. Prepending the character ``!`` to invert the
+   criteria to match is also supported.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    source group mac-group <name | !name>
@@ -641,8 +663,8 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    destination group mac-group <name | !name>
 
-   Use a specific mac-group. Prepend character ``!`` for inverted matching
-   criteria.
+   Use a specific mac-group. Prepending the character ``!`` to invert the
+   criteria to match is also supported.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    dscp [0-63 | start-end]
@@ -673,7 +695,7 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    fragment [match-frag | match-non-frag]
 
-   Match based on fragment criteria.
+   Match based on fragmentation.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    icmp [code | type] <0-255>
@@ -695,7 +717,7 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    icmp type-name <text>
 
-   Match based on icmp type-name criteria. Use tab for information
+   Match based on icmp type-name. Use tab for information
    about what **type-name** criteria are supported.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
@@ -706,8 +728,12 @@ geoip) to keep database and rules updated.
    inbound-interface name <iface>
 
    Match based on inbound interface. Wildcard ``*`` can be used.
-   For example: ``eth2*``. Prepending character ``!`` for inverted matching
-   criteria is also supported. For example ``!eth2``
+   For example: ``eth2*``. Prepending the character ``!`` to invert the
+   criteria to match is also supported. For example ``!eth2``
+
+.. note:: If an interface is attached to a non-default vrf, when using
+   **inbound-interface**, the 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>
@@ -716,8 +742,8 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    inbound-interface group <iface_group>
 
-   Match based on inbound interface group. Prepending character ``!`` for
-   inverted matching criteria is also supported. For example ``!IFACE_GROUP``
+   Match based on the inbound interface group. Prepending the character ``!`` 
+   to invert the criteria to match is also supported. For example ``!IFACE_GROUP``
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    outbound-interface name <iface>
@@ -727,8 +753,12 @@ geoip) to keep database and rules updated.
    outbound-interface name <iface>
 
    Match based on outbound interface. Wildcard ``*`` can be used.
-   For example: ``eth2*``. Prepending character ``!`` for inverted matching
-   criteria is also supported. For example ``!eth2``
+   For example: ``eth2*``. Prepending the character ``!`` to invert the
+   criteria to match is also supported. For example ``!eth2``
+
+.. note:: If an interface is attached to a non-default vrf, when using
+   **outbound-interface**, the 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>
@@ -737,8 +767,8 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    outbound-interface group <iface_group>
 
-   Match based on outbound interface group. Prepending character ``!`` for
-   inverted matching criteria is also supported. For example ``!IFACE_GROUP``
+   Match based on outbound interface group. Prepending the character ``!`` to
+   invert the criteria to match is also supported. For example ``!IFACE_GROUP``
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    ipsec [match-ipsec | match-none]
@@ -749,7 +779,7 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    ipsec [match-ipsec | match-none]
 
-   Match based on ipsec criteria.
+   Match based on ipsec.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    limit burst <0-4294967295>
@@ -792,7 +822,7 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    packet-length-exclude <text>
 
-   Match based on packet length criteria. Multiple values from 1 to 65535
+   Match based on the packet length. Multiple values from 1 to 65535
    and ranges are supported.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
@@ -804,7 +834,7 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    packet-type [broadcast | host | multicast | other]
 
-   Match based on packet type criteria.
+   Match based on the packet type.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    protocol [<text> | <0-255> | all | tcp_udp]
@@ -815,10 +845,9 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    protocol [<text> | <0-255> | all | tcp_udp]
 
-   Match a protocol criteria. A protocol number or a name which is here
-   defined: ``/etc/protocols``.
+   Match based on protocol number or name as defined in ``/etc/protocols``.
    Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and udp
-   based packets. The ``!`` negate the selected protocol.
+   based packets. The ``!`` negates the selected protocol.
 
    .. code-block:: none
 
@@ -843,7 +872,7 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    recent time [second | minute | hour]
 
-   Match bases on recently seen sources.
+   Match based on recently seen sources.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    tcp flags [not] <text>
@@ -927,8 +956,8 @@ geoip) to keep database and rules updated.
 .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
    ttl <eq | gt | lt> <0-255>
 
-   Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for
-   'greater than', and 'lt' stands for 'less than'.
+   Match the time to live parameter, where 'eq' stands for 'equal'; 'gt' stands
+   for 'greater than', and 'lt' stands for 'less than'.
 
 .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
    recent count <1-255>
@@ -963,7 +992,7 @@ Synproxy connections
 .. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999>
    synproxy tcp mss <501-65535>
 
-    Set TCP-MSS (maximum segment size) for the connection
+    Set the TCP-MSS (maximum segment size) for the connection
 
 .. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999>
    synproxy tcp window-scale <1-14>
@@ -997,7 +1026,6 @@ Requirements to enable synproxy:
   set firewall ipv4 input filter rule 1000 action 'drop'
   set firewall ipv4 input filter rule 1000 state invalid
 
-
 ***********************
 Operation-mode Firewall
 ***********************
@@ -1007,7 +1035,7 @@ Rule-set overview
 
 .. opcmd:: show firewall
 
-   This will show you a basic firewall overview, for all ruleset, and not
+   This will show you a basic firewall overview, for all rule-sets, and not
    only for ipv4
 
    .. code-block:: none