Page MenuHomeVyOS Platform

VPP dataplane: no NAT64 support (nat64_plugin disabled, Jool is kernel-only)
Open, NormalPublicFEATURE REQUEST

Description

Summary

The VPP dataplane currently provides no NAT64 capability. Customers who enable VPP on interfaces carrying NAT64 traffic lose NAT64 entirely, with no CLI warning and no commit-time error.

Current behaviour

VyOS implements NAT64 via Jool, an out-of-tree netfilter kernel module (T160). Traffic forwarded along the pure VPP path never enters the kernel networking stack, so Jool's hooks are never reached and its counters remain at zero.

VPP's own NAT64 plugin is not loaded. In data/templates/vpp/startup.conf.j2:

plugin nat44_ei_plugin.so { enable }
plugin det44_plugin.so    { enable }
# plugin nat64_plugin.so  { enable }
# plugin nat66_plugin.so  { enable }

Details

Version
1.5.1
Is it a breaking change?
Unspecified (possibly destroys the router)
Issue type
Feature (new functionality)

Related Objects

Event Timeline

Took a look at the current vpp-1.5 code to scope this out.

Good news: there's already a working precedent for exactly this problem. vpp nat nat44 exists today as a fully separate CLI subtree next to the classic kernel-based
nat/nat66 trees. It has its own conf-mode script (src/conf_mode/vpp_nat_nat44.py) and a Python wrapper (python/vyos/vpp/nat/nat44.py) that talks to VPP directly via
vpp_papi, instead of generating nftables rules. Adding vpp nat nat64 would follow the same pattern rather than requiring a new architecture, which keeps this from being a
"from scratch" job.

To close this gap I'd expect roughly the following, mirroring the nat44 implementation:

- interface-definitions/vpp_nat_nat64.xml.in — new vpp nat nat64 CLI subtree
- python/vyos/vpp/nat/nat64.py — wrapper around the VPP nat64 API (nat64_plugin_enable_disable, nat64_add_del_pool_addr_range, nat64_add_del_prefix,
nat64_add_del_static_bib, …)
- src/conf_mode/vpp_nat_nat64.py
- op-mode: show ... nat64 needs to branch between a Jool query and a VPP-API query depending on backend
- verify logic to make an interface's NAT64 backend mutually exclusive (kernel/Jool vs. VPP) — same pattern as the existing verify_vpp_interface_not_a_member check used by
vpp_nat_nat44.py
- smoketests + docs

One implementation detail worth flagging up front: in data/templates/vpp/startup.conf.j2, nat44_ei_plugin.so is unconditionally enabled at VPP startup, while nat44_ed is
toggled purely at runtime via the API. nat64_plugin.so/nat66_plugin.so, by contrast, are currently commented out entirely — meaning they aren't loaded into the running VPP
image at all. A plugin that wasn't loaded at process start can't simply be enabled later via the API; that would require a full VPP process restart, which briefly
disrupts forwarding on all VPP interfaces, not just the ones doing NAT64. The simpler fix is to always enable nat64_plugin.so/nat66_plugin.so unconditionally (same as
nat44_ei_plugin.so today) and gate the actual feature purely through the API — that avoids the restart problem entirely.

The bigger risk isn't code volume, it's feature parity. The existing Jool-based nat64 tree supports EAM64 (stateless 1:1 mapping), per-rule fwmark matching, per-rule
disable, etc. VPP's nat64 plugin, as far as I can tell, only implements stateful RFC 6146 NAT64 plus static BIB entries — there's no EAM64 equivalent. Full 1:1 CLI parity
between the two backends isn't realistic without upstream additions to VPP itself.

Suggested scope: treat this as an MVP — stateful NAT64 (pool + prefix) via the VPP API, following the nat44_ed pattern — rather than aiming for full parity with the 
Jool-based nat64 tree. That's a bounded, medium-sized piece of work given the existing nat44 precedent. Full parity (in particular EAM64) should probably be tracked as a
separate, VPP-upstream-dependent follow-up rather than blocking this one.
Viacheslav triaged this task as Normal priority.Aug 10 2026, 1:39 PM
Viacheslav subscribed.

There are several places that may be affected by VPP
Though it mentioned in the VyOS documentation, it seems we should consider additonal option like warnings, needs to be discussed with maintainers

Data Path Limitations

If a feature exists only in the kernel dataplane, traffic that uses that feature cannot traverse VPP interfaces. Examples include:

Firewall
QoS
When traffic uses the pure VPP path, it does not reach the kernel, where such features are implemented. Plan how traffic flows through your VyOS instance to ensure it reaches the necessary features.

VPP provides native alternatives for some features. For example, VPP native ACLs provide basic firewall functionality.

https://docs.vyos.io/en/1.5/vpp/limitations.html#