T7513: DOC: VPP CGNAT Exclude Rule (#1786)

* T7513: DOC: VPP CGNAT Exclude Rule

* T7513: Doc CGNAT Exclude rule - fix linter errors

2 files changed, 149 insertions, 21 deletions

diff --git a/docs/vpp/configuration/nat/cgnat.rst b/docs/vpp/configuration/nat/cgnat.rst
index d941f8ba..2f1e2e1a 100644
--- a/docs/vpp/configuration/nat/cgnat.rst
+++ b/docs/vpp/configuration/nat/cgnat.rst
@@ -8,23 +8,37 @@
 VPP CGNAT Configuration
 #######################
 
-The Carrier-grade NAT (CGNAT) is a special type of NAT mainly targeted for usage by Internet Service Providers (ISPs) to manage the limited pool of public IP addresses. It solves two main problems:
+The Carrier-grade NAT (CGNAT) is a special type of NAT mainly targeted for
+usage by Internet Service Providers (ISPs) to manage the limited pool of
+public IP addresses. It solves two main problems:
 
-* allows to fairly share a limited number of public IP addresses between multiple customers, ensuring they all have access to the internet and cannot interfere with each other.
-* allows to track and log the usage of public IP addresses by different customers, which is often a regulatory requirement.
+* allows to fairly share a limited number of public IP addresses between
+   multiple customers, ensuring they all have access to the internet and cannot
+   interfere with each other.
+* allows to track and log the usage of public IP addresses by different
+   customers, which is often a regulatory requirement.
 
-The CGNAT configuration is a straightforward process. It involves defining the inside and outside interfaces and creating the necessary rules to manage the translation of private IP addresses to public IP addresses.
+The CGNAT configuration is a straightforward process. It involves defining the
+inside and outside interfaces and creating the necessary rules to manage the
+translation of private IP addresses to public IP addresses.
 
 .. warning::
 
-   **Enabling CGNAT** on an interface (both inside and outside) **disables normal routing** on these interfaces, **also as an management access** to VyOS router itself.
-   
-   Ensure you have an alternative management path to the router before applying CGNAT configuration!
+   **Enabling CGNAT** on an interface (both inside and outside) **disables
+   normal routing** on these interfaces, **also as an management access** to
+   VyOS router itself.
+
+   Ensure you have an alternative management path to the router before applying
+   CGNAT configuration! If router-local traffic (for example SSH or DNS) must
+   remain reachable on a CGNAT interface, configure appropriate CGNAT exclude
+   rules.
 
 Interface Configuration
 -----------------------
 
-First, you need to define the inside and outside interfaces. The inside interface is connected to the private network, while the outside interface is connected to the public network.
+First, you need to define the inside and outside interfaces. The inside
+interface is connected to the private network, while the outside interface is
+connected to the public network.
 
 .. cfgcmd::
 
@@ -34,7 +48,8 @@ First, you need to define the inside and outside interfaces. The inside interfac
 
    set vpp nat cgnat interface outside <outside-interface>
 
-This is a mandatory step, as the CGNAT needs to know on which interfaces it needs to apply rules and operate.
+This is a mandatory step, as the CGNAT needs to know on which interfaces it
+needs to apply rules and operate.
 
 NAT Rules Configuration
 -----------------------
@@ -59,27 +74,84 @@ Sets the inside prefix (private IP range) that will be translated.
 
 Sets the outside prefix (public IP range) that will be used for translation.
 
+Exclude Rules Configuration
+---------------------------
+
+CGNAT exclude rules are implemented as DET44 identity mappings. Matching
+traffic is excluded from CGNAT translation and keeps its original
+address/port tuple.
+
+.. cfgcmd::
+
+   set vpp nat cgnat exclude rule <rule-number> description <description>
+
+Adds a description (stored as VPP identity-mapping tag) for easier
+identification.
+
+.. cfgcmd::
+
+   set vpp nat cgnat exclude rule <rule-number> local-address <local-address>
+
+Sets the local IPv4 address that should be excluded from translation. This
+option is mandatory for each exclude rule.
+
+.. cfgcmd::
+
+   set vpp nat cgnat exclude rule <rule-number> protocol <tcp|udp|icmp|all>
+
+Matches a specific protocol. Default is ``all``.
+
+.. cfgcmd::
+
+   set vpp nat cgnat exclude rule <rule-number> local-port <1-65535>
+
+Matches a specific local port (or ICMP identifier in case of ICMP protocol).
+
+.. important::
+
+   Exclude-rule validation rules:
+
+   * ``local-address`` must be specified.
+    * ``protocol`` and ``local-port`` must either both be specified or both be
+       omitted.
+    * Duplicate identity mappings are not allowed (same local-address,
+       protocol, local-port tuple).
+
+.. note::
+
+   A common use case for exclude rules is preserving management-plane access to
+   the router itself (for example SSH) and local-originated services (for
+   example DNS queries) when CGNAT is enabled.
+
 .. important::
 
    **Memory Requirements**
    
    CGNAT memory usage scales with the number of internal customers.
 
-   **Each 256 customers** (equivalent to a /24 subnet) requires approximately **4 MB of main heap memory**. This memory is used for maintaining customer-to-port mappings and session state information.
+   **Each 256 customers** (equivalent to a /24 subnet) requires approximately
+   **4 MB of main heap memory**. This memory is used for maintaining
+   customer-to-port mappings and session state information.
 
-   Ensure your VPP main heap size is configured appropriately based on your expected customer count. See :ref:`VPP Memory Configuration <vpp_config_dataplane_memory>` for details on adjusting main heap size.
+   Ensure your VPP main heap size is configured appropriately based on your
+   expected customer count. See :ref:`VPP Memory Configuration
+   <vpp_config_dataplane_memory>` for details on adjusting main heap size.
 
 Session Limitations
 -------------------
 
 CGNAT has built-in session limitations to ensure fair resource allocation:
 
-**Each customer (internal IP address) is limited to a maximum of 1000 simultaneous sessions**, even if more than 1000 ports are allocated to that customer. This limitation applies to all types of sessions (TCP, UDP, ICMP).
+**Each customer (internal IP address) is limited to a maximum of 1000
+simultaneous sessions**, even if more than 1000 ports are allocated to that
+customer. This limitation applies to all types of sessions (TCP, UDP, ICMP).
 
 Timeouts Configuration
 ----------------------
 
-In some cases, you might want to adjust the timers for the NAT sessions. This can help to optimize the address space usage by controlling how long a session remains active, and how long it occupies an IP address and port combination.
+In some cases, you might want to adjust the timers for the NAT sessions. This
+can help to optimize the address space usage by controlling how long a session
+remains active, and how long it occupies an IP address and port combination.
 
 This setting can be adjusted for different protocols individually:
 
@@ -107,11 +179,18 @@ Here is an example configuration for a CGNAT setup, assuming:
    set vpp nat cgnat rule 1 description "CGNAT Rule 1"
    set vpp nat cgnat rule 1 inside-prefix 100.64.0.0/16
    set vpp nat cgnat rule 1 outside-prefix 203.0.113.0/24
+   set vpp nat cgnat exclude rule 10 description "Bypass management host"
+   set vpp nat cgnat exclude rule 10 local-address 100.64.0.10
+   set vpp nat cgnat exclude rule 20 description "Bypass subscriber DNS"
+   set vpp nat cgnat exclude rule 20 local-address 100.64.0.20
+   set vpp nat cgnat exclude rule 20 protocol udp
+   set vpp nat cgnat exclude rule 20 local-port 53
 
 Operational Commands
 ====================
 
-Once the CGNAT is configured, you can use the following commands to monitor its status and operation:
+Once the CGNAT is configured, you can use the following commands to monitor
+its status and operation:
 
 .. opcmd::
 
@@ -130,13 +209,15 @@ Displays the configured inside and outside interfaces.
 
     show vpp nat cgnat sessions
 
-Displays the active NAT sessions. Be aware that this command can produce a large amount of output if there are many active sessions.
+Displays the active NAT sessions. Be aware that this command can produce a
+large amount of output if there are many active sessions.
 
 .. opcmd::
 
    show vpp nat cgnat mappings
 
-Displays the current NAT mappings, including inside and outside address prefixes.
+Displays the current NAT mappings, including inside and outside address
+prefixes.
 
 .. code-block::
 
@@ -145,6 +226,20 @@ Displays the current NAT mappings, including inside and outside address prefixes
     -------------  --------------  ---------------  ----------------  ----------
     100.64.0.0/16  203.0.113.0/24              256               252           0
 
+.. opcmd::
+
+   show vpp nat cgnat exclude-rules
+
+Displays configured CGNAT exclude rules (identity mappings).
+
+.. code-block::
+
+    vyos@vyos:~$ show vpp nat cgnat exclude-rules
+    Address      Protocol    Port    VRF  Description
+    -----------  ----------  ------  -----  ---------------------
+    100.64.0.10  all         any       0    Bypass management host
+    100.64.0.20  udp         53        0    Bypass subscriber DNS
+
 
 Potential Issues and Troubleshooting
 ====================================
@@ -153,6 +248,29 @@ Configuration is failed to apply with error similar to:
 
 .. code-block::
     
-    vpp_papi.vpp_papi.VPPIOError: [Errno 2] VPP API client: read failed``
+   vpp_papi.vpp_papi.VPPIOError: [Errno 2] VPP API client: read failed
+
+CGNAT utilizes main heap memory and if you are trying to configure big
+prefixes or a large number of NAT sessions, you may run into memory allocation
+issues. Try to :ref:`increase the main heap size in VPP configuration
+<vpp_config_dataplane_memory>`.
+
+SSH/DNS Reachability After Enabling CGNAT
+-----------------------------------------
+
+If SSH access to the router (or local-originated DNS queries) stops working
+after enabling CGNAT, traffic may be dropped by DET44 when it does not match a
+translation mapping.
+
+In this case, add an exclude rule for the router local address that must
+bypass CGNAT translation.
+
+.. code-block::
+
+   set vpp nat cgnat exclude rule 100 local-address <router-ip>
+
+Then verify:
+
+.. code-block::
 
-CGNAT utilizes main heap memory and if you are trying to configure big prefixes or a large number of NAT sessions, you may run into memory allocation issues. Try to :ref:`increase the main heap size in VPP configuration <vpp_config_dataplane_memory>`.
+   show vpp nat cgnat exclude-rules
diff --git a/docs/vpp/configuration/nat/index.rst b/docs/vpp/configuration/nat/index.rst
index fad3b4af..34110651 100644
--- a/docs/vpp/configuration/nat/index.rst
+++ b/docs/vpp/configuration/nat/index.rst
@@ -22,13 +22,23 @@ NAT44
 =====
 
 This type is a classical NAT implementation where you can configure static and
-dynamic NAT rules. It supports both source and destination NAT - while the configuration may looks a bit unusual in comparison to traditional NAT implementations.
+dynamic NAT rules. It supports both source and destination NAT - while the
+configuration may looks a bit unusual in comparison to traditional NAT
+implementations.
 
 CGNAT
 =====
 
-CGNAT is a special type of NAT44, which is highly useful for use cases where you have multiple local customers with a limited number of public IP addresses, and want to share public IP address space fairly between them. It uses a combination of IP address and port number to distinguish between different customers.
+CGNAT is a special type of NAT44, which is highly useful for use cases where
+you have multiple local customers with a limited number of public IP
+addresses, and want to share public IP address space fairly between them. It
+uses a combination of IP address and port number to distinguish between
+different customers.
 
-This type of NAT is often used by ISPs to provide internet access to their customers.
+This type of NAT is often used by ISPs to provide internet access to their
+customers.
 
 It supports only source NAT.
+
+CGNAT also supports exclude rules (identity mappings) to bypass translation
+for selected local addresses or protocol/port tuples.