1 files changed, 35 insertions, 0 deletions
diff --git a/docs/vpp/configuration/dataplane/l2learn.md b/docs/vpp/configuration/dataplane/l2learn.md
new file mode 100644
index 00000000..2ce572a1
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/l2learn.md
@@ -0,0 +1,35 @@
+---
+lastproofread: '2026-02-26'
+---
+
+(vpp-config-dataplane-l2learn)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP L2LEARN Configuration
+
+When VPP dataplane connects to an L2 domain, it learns MAC addresses of
+devices in the domain. By default, the number of MAC addresses it can
+learn is limited.
+
+You can configure the limit using the following command:
+
+```{cfgcmd} set vpp settings resource-allocation mac-limit \<value\>
+```
+
+This parameter sets the maximum number of MAC addresses that can be
+learned in the L2 domain. If you have many devices, you may need to
+increase this limit to ensure VPP learns all MAC addresses.
+
+## Potential Issues and Troubleshooting
+
+Improper L2LEARN configuration can lead to various issues, including:
+
+- MAC address learning failure in the L2 domain if the limit is set too
+  low
+- Increased packet loss or latency for devices that aren't learned
+- Overall dataplane instability when handling L2 traffic
+
+Consider increasing the L2LEARN limit if you experience issues with MAC
+address learning or if you have many devices in the L2 domain.