1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
|
---
lastproofread: '2026-03-03'
---
(vpp_config_nat_cgnat)=
```{include} /_include/need_improvement.txt
```
# 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.
```{cfgcmd} set vpp nat cgnat interface inside \<inside-interface\>
```
```{cfgcmd} 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.
## NAT Rules Configuration
Next, you need to create the NAT rules.
```{cfgcmd} set vpp nat cgnat rule \<rule-number\> description \<description\>
```
Add a description to the rule for easier identification.
```{cfgcmd} set vpp nat cgnat rule \<rule-number\> inside-prefix \<inside-prefix\>
```
Specify the inside prefix (private IP range) to translate.
```{cfgcmd} set vpp nat cgnat rule \<rule-number\> outside-prefix \<outside-prefix\>
```
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.
```{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 maintains
customer-to-port mappings and session state information.
Configure your VPP main heap size 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 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: `eth2`
- Outside interface: `eth1`
- Inside prefix: `100.64.0.0/16`
- Outside 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:
```{opcmd} show vpp nat cgnat interfaces
```
Displays the configured inside and outside interfaces.
```
vyos@vyos:~$ show vpp nat cgnat interfaces
CGNAT interfaces:
eth2 in
eth1 out
```
```{opcmd} show vpp nat cgnat sessions
```
Display active NAT sessions. This command may produce extensive output if
many sessions are active.
```{opcmd} show vpp nat cgnat mappings
```
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
```
```{opcmd} show vpp nat cgnat exclude-rules
```
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 {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.
```
set vpp nat cgnat exclude rule 100 local-address <router-ip>
```
Then verify:
```
show vpp nat cgnat exclude-rules
```
|
