From dfce431e2d3af56416e1f823aa98cf54e4a22e2f Mon Sep 17 00:00:00 2001 From: RC Date: Thu, 5 Mar 2026 02:36:05 -0700 Subject: T7513: DOC: VPP CGNAT Exclude Rule (#1786) * T7513: DOC: VPP CGNAT Exclude Rule * T7513: Doc CGNAT Exclude rule - fix linter errors --- docs/vpp/configuration/nat/cgnat.rst | 154 +++++++++++++++++++++++++++++++---- docs/vpp/configuration/nat/index.rst | 16 +++- 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 -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 description + +Adds a description (stored as VPP identity-mapping tag) for easier +identification. + +.. cfgcmd:: + + set vpp nat cgnat exclude rule 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 protocol + +Matches a specific protocol. Default is ``all``. + +.. cfgcmd:: + + set vpp nat cgnat exclude rule 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 ` 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 + ` 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 +`. + +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 + +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 `. + 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. -- cgit v1.2.3