Call for Contributions
Help improve this section with additional content, examples, and explanations.
For contribution guidelines, see Write Documentation.
VPP CGNAT Configuration
Carrier-grade NAT (CGNAT) is a NAT type designed for Internet Service Providers (ISPs) to manage limited pools of public IP addresses. It solves two main problems:
Enables fair sharing of a limited number of public IP addresses among multiple customers, ensuring all have internet access without interfering with each other.
Enables tracking and logging of public IP address usage by different customers, which is often a regulatory requirement.
CGNAT configuration is straightforward. Define the inside and outside interfaces, then create 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 and blocks management access to the VyOS router itself.
Ensure you have an alternative management path to the router before applying your CGNAT configuration.
Interface Configuration
Define the inside and outside interfaces. The inside interface connects to the private network, while the outside interface connects to the public network.
This is a mandatory step, as the CGNAT needs to know on which interfaces it needs to apply rules and operate.
NAT Rules Configuration
Next, you need to create the NAT rules.
Add a description to the rule for easier identification.
Specify the inside prefix (private IP range) to translate.
Specify the outside prefix (public IP range) to use 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.
Adds a description (stored as VPP identity-mapping tag) for easier identification.
Sets the local IPv4 address that should be excluded from translation. This option is mandatory for each exclude rule.
Matches a specific protocol. Default is all.
Matches a specific local port (or ICMP identifier in case of ICMP protocol).
Important
Exclude-rule validation rules:
local-addressmust be specified.protocolandlocal-portmust either both be specified or both beomitted.
- 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 maintains customer-to-port mappings and session state information.
Configure your VPP main heap size appropriately based on your expected customer count. See 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 session types (TCP, UDP, ICMP).
Timeouts Configuration
You can adjust NAT session timers to optimize address space usage by controlling how long sessions remain active and how long they occupy IP address and port combinations.
Adjust these settings for different protocols individually:
set vpp nat cgnat timeout icmp <timeout-value>
set vpp nat cgnat timeout tcp-established <timeout-value>
set vpp nat cgnat timeout tcp-transitory <timeout-value>
set vpp nat cgnat timeout udp <timeout-value>
Example Configuration
Here is an example CGNAT configuration with these assumptions:
Inside interface:
eth2Outside interface:
eth1Inside prefix:
100.64.0.0/16Outside prefix:
203.0.113.0/24
set vpp nat cgnat interface inside eth2
set vpp nat cgnat interface outside eth1
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:
Displays the configured inside and outside interfaces.
vyos@vyos:~$ show vpp nat cgnat interfaces
CGNAT interfaces:
eth2 in
eth1 out
Display active NAT sessions. This command may produce extensive output if many sessions are active.
Display current NAT mappings, including inside and outside address prefixes.
vyos@vyos:~$ show vpp nat cgnat mappings
Inside Outside Sharing ratio Ports per host Sessions
------------- -------------- --------------- ---------------- ----------
100.64.0.0/16 203.0.113.0/24 256 252 0
Displays configured CGNAT exclude rules (identity mappings).
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
Configuration fails to apply with an error similar to:
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 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.
set vpp nat cgnat exclude rule 100 local-address <router-ip>
Then verify:
show vpp nat cgnat exclude-rules