feat: activate 106 visual-validated canaries via swap

Imports 105 MD files (plus quick-start already present) from
origin/myst/current and adds them to docs/_swap.txt. The selection
is the BackstopJS visual-passers cohort: pages with <5% rendered
diff vs the live RST docs at docs.vyos.io/en/latest/, filtered to
those with an RST counterpart on current and no cmdincludemd usage
(template-format reconciliation pending).

Local sphinx-build with all 106 swapped: succeeded with 100
warnings (vs 95 baseline). The 5 new warnings are all undefined
cross-reference labels, not build failures:
- contributing/development.md (missing 'coding-guidelines')
- operation/upgrade-recovery.md (3 missing 'how_it_works' /
  'cancelling_recovery')
- vpp/configuration/dataplane/{buffers,memory,unix}.md (missing
  'vpp_config_dataplane_*' labels)

Source list: ~/.claude/projects/-Users-vybot-GitHub-vyos-documentation/docs/2026-04-29-myst-conversion-audit/visual-passers-under-5pct.txt
BackstopJS report: claude/gifted-hertz-74b9f9 worktree
(visual-compare/), 2026-04-23 vs vyos--1838.org.readthedocs.build.

🤖 Generated by [robots](https://vyos.io)

25 files changed, 3009 insertions, 0 deletions

diff --git a/docs/vpp/configuration/dataplane/md-buffers.md b/docs/vpp/configuration/dataplane/md-buffers.md
new file mode 100644
index 00000000..80f2f23c
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-buffers.md
@@ -0,0 +1,90 @@
+---
+lastproofread: '2026-02-23'
+---
+
+(vpp-config-dataplane-buffers)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Dataplane Buffers Configuration
+
+Buffers are essential for handling network packets efficiently. Proper
+configuration enhances performance and reliability, and is mandatory for
+VPP to work. Buffers temporarily store packets during processing. Therefore,
+their configuration must be in sync with NIC configuration, CPU threads, and
+overall system resources.
+
+:::{important}
+VPP buffers are allocated from the physical memory pool (`physmem`). The
+total amount of memory available for buffer allocation is controlled by the
+`physmem-max-size` setting, while the buffer configuration parameters
+below control how that memory is used for buffer allocation.
+
+See {ref}`VPP Physical Memory Configuration <vpp_config_dataplane_physmem>`
+for details on configuring `physmem`.
+:::
+
+## Buffer Configuration Parameters
+
+The following parameters can be configured for VPP buffers:
+
+### buffers-per-numa
+Number of buffers allocated per NUMA node. This setting optimizes
+memory access patterns for multi-CPU systems.
+
+Typically, you need to tune this value if:
+- The system has many interfaces
+- NICs have many queues
+- NICs have large descriptor sizes
+
+Set this value carefully to balance memory usage and performance.
+```{cfgcmd} set vpp settings resource-allocation buffers buffers-per-numa \<value\>
+```
+The common approach for the calculation is to use the formula:
+```none
+buffers-per-numa = (num-rx-queues * num-rx-desc) + (num-tx-queues * num-tx-desc)
+```
+Calculate this formula for each NIC and sum the results. Multiply the
+total by 2.5 to get the minimum recommended value for
+`buffers-per-numa`.
+
+Avoid setting this value too low to prevent packet drops.
+
+### data-size
+This value sets how much payload data can be stored in a single buffer
+allocated by VPP. Larger values reduce buffer chains for large packets,
+while smaller values conserve memory for environments handling mostly
+small packets.
+```{cfgcmd} set vpp settings resource-allocation buffers data-size \<value\>
+```
+Optimal size depends on the typical packet size in your network. If
+unsure, use the largest MTU in your network plus overhead (for example,
+128 bytes).
+
+### page-size
+A memory pages type used for buffer allocation. Common values are 4K, 2M, or 1G.
+
+Use page sizes configured in your system settings.
+```{cfgcmd} set vpp settings resource-allocation buffers page-size \<value\>
+```
+
+## Potential Issues and Troubleshooting
+
+Improper buffer configuration can lead to issues such as:
+
+- Increased latency and packet loss
+- Inefficient CPU utilization
+- Interface initialization failures
+
+Indicators of such issues are:
+
+- Errors during interfaces initialization in VPP logs
+- Packet drops observed in VPP statistics
+
+To troubleshoot buffer-related issues, consider the following steps:
+
+- Review VPP logs for errors related to buffer allocation. Look for
+  error `-5` messages.
+- Tune available buffers by adjusting the `buffers-per-numa` and
+  `data-size` parameters.
diff --git a/docs/vpp/configuration/dataplane/md-cpu.md b/docs/vpp/configuration/dataplane/md-cpu.md
new file mode 100644
index 00000000..9b798631
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-cpu.md
@@ -0,0 +1,66 @@
+---
+lastproofread: '2026-02-23'
+---
+
+(vpp-config-dataplane-cpu)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Dataplane CPU Configuration
+VPP can utilize multiple CPU cores for better packet processing
+performance. Proper CPU configuration is essential for optimal
+throughput and low latency.
+
+VPP CPU assignment is handled automatically. You specify how many CPU
+cores VPP may use, and the system distributes them between the main
+thread and worker threads.
+
+:::{important}
+Review the system configuration settings page before changing CPU
+settings: {doc}`system`.
+:::
+If you don't configure CPU settings, VPP uses a single core for the
+main thread and doesn't create worker threads.
+
+## CPU Configuration Parameters
+
+### `cpu-cores`
+This parameter defines the total number of CPU cores allocated to VPP.
+```{cfgcmd} set vpp settings resource-allocation cpu-cores \<core-number\>
+```
+
+The system automatically assigns cores using the following rules:
+
+> - The first two CPU cores are always reserved for the operating system and
+>   other services.
+> - The main VPP thread is assigned to the first available core after the
+>   reserved ones.
+> - The remaining allocated cores are used for worker threads.
+
+For example:
+
+> - If cpu-cores is set to 1, VPP runs only a main thread.
+>
+> - If cpu-cores is set to 4, VPP uses:
+>
+>   > - 1 core for the main thread
+>   > - 3 cores for worker threads
+
+Choose a value based on available hardware resources and expected
+traffic load. Too few cores may limit performance, while too many can
+negatively impact other system services.
+
+## Potential Issues and Troubleshooting
+
+Improper CPU configuration can lead to issues such as:
+
+- VPP underperformance when not enough cores are assigned, or kernel
+  underperformance when too many cores are assigned to VPP.
+- Resource conflicts with other processes and services.
+
+Indicators of such issues are:
+
+- VPP or kernel forwarding performance is lower than expected
+- Degraded performance of system components or services, such as DNS,
+  DHCP, and dynamic routing
diff --git a/docs/vpp/configuration/dataplane/md-index.md b/docs/vpp/configuration/dataplane/md-index.md
new file mode 100644
index 00000000..f147ebe8
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-index.md
@@ -0,0 +1,32 @@
+---
+lastproofread: '2026-02-23'
+---
+
+(vpp-config-dataplane-index)=
+
+```{include} /_include/need_improvement.txt
+```
+# VPP Dataplane Core Configuration
+This section covers the core configuration options for the VPP dataplane in
+VyOS. It includes settings for memory management, CPU allocation, hugepages,
+and other essential parameters that influence the performance and behavior
+of the VPP dataplane.
+Please review the general system configuration, before starting to configure
+VPP. Without proper VyOS preconditions, VPP will not start or its efficiency
+will be significantly degraded.
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+system
+buffers
+cpu
+interface
+ipsec
+ipv6
+l2learn
+lcp
+logging
+memory
+unix
+```
diff --git a/docs/vpp/configuration/dataplane/md-interface.md b/docs/vpp/configuration/dataplane/md-interface.md
new file mode 100644
index 00000000..231a49a9
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-interface.md
@@ -0,0 +1,88 @@
+---
+lastproofread: '2026-02-23'
+---
+
+(vpp-config-dataplane-interface)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Dataplane Interfaces Configuration
+Only Ethernet interfaces (physical or virtual) can be connected to the
+VPP dataplane. Interfaces configured here act as a bridge between VPP
+and the outside world, allowing VPP to send and receive network
+packets.
+
+## Interface Configuration Parameters
+Interfaces connected to the VPP dataplane use the DPDK driver by default,
+providing high performance and low latency.
+```{cfgcmd} set vpp settings interface \<interface-name\>
+```
+Some network interface cards (NICs) may not be compatible with the DPDK driver.
+
+### DPDK interface options
+This section shows how to configures DPDK-specific settings for an interface.
+```{cfgcmd} set vpp settings interface \<interface-name\> num-rx-queues \<value\>
+```
+Specifies the number of receive queues for the interface. More queues
+improve performance on multi-core systems by allowing parallel
+processing of incoming packets. Each queue is assigned to a separate
+CPU core.
+```{cfgcmd} set vpp settings interface \<interface-name\> num-tx-queues \<value\>
+```
+Specifies the number of transmit queues for the interface. Similar to
+receive queues, more transmit queues improve performance by enabling
+parallel processing of outgoing packets. By default, the VPP Dataplane
+has one TX queue per enabled CPU worker, or a single queue if no
+workers are configured.
+
+:::{seealso}
+{doc}`cpu`
+:::
+```{cfgcmd} set vpp settings interface \<interface-name\> num-rx-desc \<value\>
+```
+Defines the size of each receive queue. Larger queue sizes accommodate
+bursts of incoming traffic and reduce the likelihood of packet drops
+during high traffic periods.
+```{cfgcmd} set vpp settings interface \<interface-name\> num-tx-desc \<value\>
+```
+Defines the size of each transmit queue. Larger sizes help manage
+bursts of outgoing traffic more effectively.
+
+## Global Interface Parameters
+(vpp-config-dataplane-interface-rx-mode)=
+
+### interface-rx-mode
+The `interface-rx-mode` parameter defines how VPP handles incoming
+packets on interfaces. There are several modes available, each with its
+own advantages and use cases:
+- `interrupt`: In this mode, VPP relies on hardware interrupts to
+  notify it of incoming packets. This mode suits low to moderate
+  traffic loads and reduces CPU usage during idle periods. It is not
+  recommended for low-latency processing. Some NICs may not support
+  this mode.
+- `polling`: In polling mode, VPP continuously checks the interface
+  for incoming packets. This mode is ideal for high-throughput
+  scenarios where low latency is critical, as it minimizes packet
+  waiting time. However, it can increase CPU usage, especially during
+  low traffic periods, as the polling process is always active.
+- `adaptive`: Adaptive mode combines the benefits of interrupt and
+  polling modes. VPP starts in interrupt mode and switches to polling
+  mode when traffic load increases.
+```{cfgcmd} set vpp settings interface-rx-mode \<mode\>
+```
+
+Choose an rx-mode based on expected traffic patterns and performance
+requirements of your network.
+
+## Potential Issues and Troubleshooting
+
+Improper interface configuration can lead to issues such as:
+
+- Failure to initialize the interface
+- Poor performance due to suboptimal driver selection or settings
+
+Indicators of such issues are:
+
+- Failed commits after adding or modifying an interface settings
+- Low throughput or high latency on the interface
diff --git a/docs/vpp/configuration/dataplane/md-ipsec.md b/docs/vpp/configuration/dataplane/md-ipsec.md
new file mode 100644
index 00000000..17e16f8e
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-ipsec.md
@@ -0,0 +1,63 @@
+---
+lastproofread: '2026-02-23'
+---
+
+(vpp-config-dataplane-ipsec)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP IPsec Configuration
+VPP supports IPsec (Internet Protocol Security) offloading from the
+kernel, which speeds up cryptographic operations by leveraging VPP's
+high-performance packet processing capabilities.
+
+IPsec does not require any specific configuration on VPP side. If both
+sources and destinations of the IPsec traffic are reachable via VPP
+interfaces, VPP will automatically offload the IPsec processing from
+the kernel. IPsec tunnels are configured in the VPN configuration
+section, see {ref}`ipsec_general`.
+
+## IPsec Configuration Parameters
+
+### enable IPsec acceleration
+When VPP is used for offloading IPsec, it creates a virtual interface to
+connect to peers. The interface type is always 'ipsec', which is used for
+IPsec tunnels.
+```{cfgcmd} set vpp settings ipsec-acceleration
+```
+Enabling this option allows VPP to handle IPsec traffic more efficiently by
+offloading processing from the kernel.
+
+### netlink
+VPP uses netlink to receive IPsec event messages from the kernel. Proper
+settings of the following parameters are crucial for ensuring that VPP can
+process all such messages:
+```{cfgcmd} set vpp settings lcp netlink batch-delay-ms \<milliseconds\>
+```
+This parameter specifies the delay in milliseconds between processing
+batch netlink messages.
+```{cfgcmd} set vpp settings lcp netlink batch-size \<number\>
+```
+This parameter specifies the maximum number of netlink messages to
+process in a single batch.
+```{cfgcmd} set vpp settings lcp netlink rx-buffer-size \<number\>
+```
+
+This parameter specifies the size of the receive buffer for netlink
+socket. If you expect to offload many IPsec tunnels or get frequent and
+intensive rekeying, you may need to increase this value.
+
+:::{note}
+IPsec uses the same netlink parameters as LCP, so tuning them
+affects both LCP and IPsec processing.
+:::
+
+## Potential Issues and Troubleshooting
+
+Improper IPsec configuration can lead to various issues, including:
+
+- Failure to offload IPsec tunnels to VPP
+- Lost IPsec event messages due to insufficient netlink buffer size or
+  batch settings
+- IPsec states or SAs are not synchronized between kernel and VPP
diff --git a/docs/vpp/configuration/dataplane/md-ipv6.md b/docs/vpp/configuration/dataplane/md-ipv6.md
new file mode 100644
index 00000000..a72dbbfa
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-ipv6.md
@@ -0,0 +1,41 @@
+---
+lastproofread: '2026-02-26'
+---
+
+(vpp-config-dataplane-ipv6)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP IPv6 Configuration
+VPP lets you configure resources allocated for IPv6 traffic processing
+independently from IPv4. This helps ensure that in networks without IPv6
+traffic, resources are not wasted. If IPv6 traffic is present, especially
+with large routing tables, you must allocate additional resources for IPv6
+processing to keep the dataplane stable.
+
+You can configure two main resources for IPv6 traffic processing:
+```{cfgcmd} set vpp settings resource-allocation ipv6 hash-buckets \<value\>
+```
+This parameter configures the number of hash buckets used for IPv6
+routing. If you have a large IPv6 routing table, you may need to increase
+this value to ensure efficient routing table performance and fast lookups.
+```{cfgcmd} set vpp settings resource-allocation ipv6 heap-size \<value\>
+```
+
+This parameter configures the heap size used for IPv6 forwarding. If you
+have a large IPv6 routing table, you may need to increase this value to
+ensure the routing table can accommodate all routes.
+
+## Potential Issues and Troubleshooting
+
+Improper IPv6 configuration can lead to various issues, including:
+
+- Inefficient, slow routing table lookups and traffic processing due to
+  insufficient hash buckets
+- Dataplane crashes or instability due to insufficient heap size when
+  handling a large number of IPv6 routes
+- Overall dataplane instability when handling IPv6 traffic
+
+Consider increasing configuration values if you experience issues with
+IPv6 traffic processing or if you have a large IPv6 routing table.
diff --git a/docs/vpp/configuration/dataplane/md-l2learn.md b/docs/vpp/configuration/dataplane/md-l2learn.md
new file mode 100644
index 00000000..fe5deb55
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-l2learn.md
@@ -0,0 +1,32 @@
+---
+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.
diff --git a/docs/vpp/configuration/dataplane/md-lcp.md b/docs/vpp/configuration/dataplane/md-lcp.md
new file mode 100644
index 00000000..8ffdb7fb
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-lcp.md
@@ -0,0 +1,46 @@
+---
+lastproofread: '2026-02-26'
+---
+
+(vpp-config-dataplane-lcp)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP LCP Configuration
+Linux Control Plane (LCP) is a core component of VPP that lets you
+offload various control plane functions to the Linux kernel. LCP provides
+seamless integration with other VyOS components, letting you use system
+components like DHCP clients and routing daemons together with the VPP
+dataplane.
+
+VPP integration in VyOS relies heavily on LCP. Almost all control plane
+functions are handled by other daemons and services, while VPP handles
+high-performance packet forwarding exclusively. This approach also reduces
+VPP management processing load, improving overall dataplane performance and
+stability.
+
+VyOS integrates the kernel and VPP routing tables uniquely. By default,
+all routes, even those not directly connected to VPP interfaces, are
+imported from the kernel routing table to the VPP routing table, pointing
+to the kernel. This lets you forward traffic to any destination known to
+the kernel, even if VPP doesn't have a route to that destination.
+
+However, in some scenarios this behavior may not be desired. For example,
+if you have many routes in the kernel routing table not directly connected
+to VPP interfaces, and you don't need forwarding between those
+destinations and destinations reachable via VPP, you can disable this
+behavior using the following command:
+(vpp-config-dataplane-lcp-ignore-kernel-routes)=
+```{cfgcmd} set vpp settings ignore-kernel-routes
+```
+
+Pay attention that disabling this option leads to loss of connectivity to
+destinations if there are no direct routes in VPP routing table.
+
+## Potential Issues and Troubleshooting
+
+Disabling kernel route import can result in:
+
+- Loss of connectivity to certain destinations if kernel routes are ignored
+- Incomplete route synchronization between the kernel and VPP
diff --git a/docs/vpp/configuration/dataplane/md-logging.md b/docs/vpp/configuration/dataplane/md-logging.md
new file mode 100644
index 00000000..e7fcf455
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-logging.md
@@ -0,0 +1,56 @@
+---
+lastproofread: '2026-02-27'
+---
+
+(vpp-config-dataplane-logging)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Logging Configuration
+VPP logging is an important part of monitoring and troubleshooting
+the performance and behavior of the VPP dataplane.
+
+VPP stores logs in two places:
+- `/var/log/vpp.log` — This file contains logs related to daemon
+  startup and logs of commands executed directly via VPP CLI. Pay
+  attention: VyOS does not use VPP CLI for configuration, so this log
+  will not contain any configuration changes made via VyOS CLI and will
+  not be informative in most cases.
+- System journal — contains logs related to the VPP daemon work,
+  including errors, warnings, and informational messages. It is the
+  main destination of logs generated by VPP.
+
+Logging detail level can be configured via the next command:
+```{cfgcmd} set vpp settings logging default-level \<level\>
+```
+
+Where `<level>` can be one of the following:
+
+- `emerg` (Emergency) - System is unusable.
+- `alert` (Alert) - Immediate action required.
+- `crit` (Critical) - Critical conditions.
+- `error` (Error) - Error conditions.
+- `warn` (Warning) - Warning conditions.
+- `notice` (Notice) - Normal but significant.
+- `info` (Informational) - Routine informational messages.
+- `debug` (Debug) - Detailed debugging messages.
+- `disabled` (Disabled) - Logging disabled.
+
+It is recommended to set logging level to `debug` only for
+troubleshooting purposes, as it can generate a large volume of log
+data. For regular operation, a level of `info` or `warn` is usually
+sufficient.
+
+## Troubleshooting
+
+Improper logging configuration can lead to various issues, including:
+
+- Excessive log file sizes if the logging level is set too high
+  (for example, `debug`).
+- Missing critical information if the logging level is set too low
+  (for example, `alert`).
+- Performance degradation due to excessive logging overhead
+
+Consider adjusting the logging level if you experience issues mentioned
+above.
diff --git a/docs/vpp/configuration/dataplane/md-memory.md b/docs/vpp/configuration/dataplane/md-memory.md
new file mode 100644
index 00000000..4e9d653d
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-memory.md
@@ -0,0 +1,127 @@
+---
+lastproofread: '2026-02-27'
+---
+
+(vpp-config-dataplane-memory)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Memory Configuration
+VPP heavily relies on hugepages for its memory management. Hugepages
+are larger memory pages that reduce the overhead of page management and
+improve performance for applications that require large amounts of
+memory, such as VPP.
+
+VPP supports both 2MB and 1GB hugepages, but the default and most
+commonly used size is 2MB. The choice of hugepage size can impact
+performance, with larger pages generally providing better performance
+for memory-intensive applications.
+
+Before configuring memory in VPP dataplane settings, you need to
+ensure that hugepages are enabled and properly configured on your
+system.
+
+:::{seealso}
+{ref}`Hugepages in VyOS Configuration for VPP <vpp-config-hugepages>`
+:::
+To configure memory settings for VPP, you can use the following
+commands in the VPP CLI:
+
+VPP uses a main heap as a central memory pool for FIB data structures
+entry allocations.
+
+Efficient memory management is crucial for VPP's performance, and the
+main heap plays a significant role in this.
+
+It can be configured using the following command:
+```{cfgcmd} set vpp settings resource-allocation memory main-heap-page-size \<size\>
+```
+Sets the main heap page size for VPP.
+```{cfgcmd} set vpp settings resource-allocation memory main-heap-size \<size\>
+```
+Sets the main heap size for VPP.
+(vpp-config-dataplane-physmem)=
+
+## Physical Memory Configuration
+VPP uses physical memory for packet buffers and interface operations.
+The `physmem` setting controls how much memory VPP can allocate for
+these operations.
+```{cfgcmd} set vpp settings resource-allocation memory physmem-max-size \<size\>
+```
+Sets the maximum amount of physical memory VPP can use for packet
+processing and interface buffers.
+
+**Default**: 16GB (usually sufficient for most deployments)
+
+You may need to modify the value for high-throughput environments with
+many interfaces, large packet buffers, very high packet rates, or
+memory-constrained systems where you need to limit VPP's memory usage.
+
+**Physmem independent of main heap size** — physmem is for packet
+buffers, main heap is for routing tables.
+
+:::{seealso}
+- {ref}`Hugepages in VyOS Configuration for VPP <vpp-config-hugepages>`
+- {ref}`VPP Buffer Configuration <vpp-config-dataplane-buffers>` - for
+  controlling buffer allocation within physmem
+:::
+
+### Common configurations
+```none
+# Reduce for memory-constrained systems
+set vpp settings physmem max-size 4G
+
+# Increase for high-throughput environments
+set vpp settings physmem max-size 32G
+```
+## Stats Memory Configuration
+VPP uses a dedicated statistics memory segment to store runtime
+counters and telemetry data. This segment is used by the VPP CLI and
+monitoring tools to access performance and status information.
+
+The statistics segment is allocated from hugepage memory and can be
+configured independently from the main heap and physmem settings.
+
+You can configure statistics memory using the following commands:
+```{cfgcmd} set vpp settings resource-allocation memory stats page-size \<size\>
+```
+Sets the hugepage page size used for the statistics memory segment.
+```{cfgcmd} set vpp settings resource-allocation memory stats size \<size\>
+```
+
+Sets the total size of the statistics memory segment.
+
+Increasing this value may be required in large deployments with many
+interfaces or enabled features that generate a high number of counters.
+
+Statistics memory is used only for telemetry and monitoring. It does
+not affect packet buffer allocation or routing table memory.
+
+## Troubleshooting
+
+Improper configuration of main heap size can lead to performance
+degradation or even system instability. If VPP runs out of memory in the
+main heap, it may crash or exhibit erratic behavior. Symptoms you may
+observe include:
+
+- Increased latency or packet loss
+- Crashes or restarts of VPP processes, especially during routing table
+  population (for example, BGP session establishment)
+- Error messages related to memory allocation failures
+
+You need to tune the main heap size based on expected FIB entries. Pay
+attention: the same amount of routes with a single next-hop and with
+multiple next-hops will consume different amounts of memory.
+
+For physmem, insufficient allocation can lead to packet drops, interface
+initialization failures, and overall degraded performance. Symptoms
+include:
+
+- Packet drops or failures to allocate buffers
+- Increased latency or jitter in packet processing
+- Crashes or restarts of VPP processes under heavy load
+
+You need to tune the physmem settings based on expected traffic patterns
+and interface usage. Monitor memory usage closely and adjust the
+configuration as needed to ensure optimal performance.
diff --git a/docs/vpp/configuration/dataplane/md-unix.md b/docs/vpp/configuration/dataplane/md-unix.md
new file mode 100644
index 00000000..ba89d650
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-unix.md
@@ -0,0 +1,54 @@
+---
+lastproofread: '2026-02-27'
+---
+
+(vpp-config-dataplane-unix)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Unix Dataplane Configuration
+The UNIX configuration section is used to control VPP's interaction
+with the underlying operating system, including operations scheduling.
+
+VPP relies on the polling mechanism to efficiently manage I/O operations
+and system events. By default VPP continuously polls for events, which
+leads to permanent 100% CPU usage by all cores assigned to VPP dataplane.
+This is optimal for performance, but may not be desirable in all
+environments, especially where power consumption is a concern or where VPP
+is running inside a hypervisor, especially if the VM has burstable
+thresholds and CPU usage limits.
+
+To mitigate this, VPP provides a configurable polling delay that allows
+reducing CPU usage by introducing a delay between polling cycles. This
+introduces a trade-off between CPU usage and latency, as longer delays
+can lead to increased latency in processing events.
+
+You can configure the polling delay using the following command in the
+VyOS CLI:
+```{cfgcmd} set vpp settings poll-sleep-usec \<delay\>
+```
+
+Sets the polling delay in microseconds. A value of 0 means no delay
+(default), while higher values introduce a delay between polling cycles.
+
+## Troubleshooting
+
+Setting the polling delay too high can lead to increased latency and
+reduced performance, as VPP may not respond to events as quickly.
+Conversely, setting it too low may result in high CPU usage, which can be
+problematic in resource-constrained environments.
+
+Symptoms of improper configuration may include:
+
+- Increased latency in packet processing
+- Higher CPU usage than expected
+- Packets lost due to buffer overruns
+
+If you do not need to reduce CPU usage, it is recommended to leave the
+polling delay at its default value of 0 for optimal performance.
+
+If you need to reduce CPU usage, you may also consider using `interrupt` or
+`adaptive` {ref}`DPDK driver modes <vpp_config_dataplane_interface_rx_mode>`,
+which can provide a balance between performance and resource utilization
+without affecting polling behavior.
diff --git a/docs/vpp/configuration/interfaces/md-bonding.md b/docs/vpp/configuration/interfaces/md-bonding.md
new file mode 100644
index 00000000..24868166
--- /dev/null
+++ b/docs/vpp/configuration/interfaces/md-bonding.md
@@ -0,0 +1,206 @@
+---
+lastproofread: '2026-03-09'
+---
+
+(vpp-config-interfaces-bonding)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Bonding Configuration
+VPP bonding interfaces provide link aggregation capabilities by combining
+multiple physical interfaces into a single logical interface for increased
+bandwidth and redundancy. VPP bonding offers high-performance packet
+processing compared to traditional Linux bonding.
+
+## Basic Configuration
+
+### Creating a Bonding Interface
+To create a VPP bonding interface:
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\>
+
+Create a bonding interface where ``<vppbondN>`` follows the naming
+convention ``vppbond0``, ``vppbond1``, and so on. A kernel pair interface is
+automatically created for the VPP bonding interface. This allows
+standard Linux networking tools and services to interact with the VPP
+bond.
+```
+**Example:**
+```none
+set interfaces vpp bonding vppbond0
+```
+### Interface Description
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> description \<description\>
+
+Set a descriptive name for the bonding interface.
+```
+**Example:**
+```none
+set interfaces vpp bonding vppbond0 description "Primary uplink bond"
+```
+### Administrative Control
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> disable
+
+Administratively disable the bonding interface. By default, interfaces
+are enabled.
+```
+## Member Interface Configuration
+### Adding Member Interfaces
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> member interface \<interface-name\>
+
+Add physical interfaces as members of the bond. You can add multiple
+interfaces to the same bond.
+```
+**Example:**
+```none
+set interfaces vpp bonding vppbond0 member interface eth0
+set interfaces vpp bonding vppbond0 member interface eth1
+```
+:::{note}
+Member interfaces must have the same speed and duplex for optimal
+performance. They must already be attached to VPP.
+:::
+
+## Bonding Modes
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> mode \<mode\>
+
+Configure the bonding mode. Available modes:
+* **802.3ad**: IEEE 802.3ad Dynamic Link Aggregation (LACP) - Default
+* **active-backup**: Fault tolerant, only one slave interface active
+* **broadcast**: Transmits everything on all slave interfaces
+* **round-robin**: Load balance by transmitting packets in sequential order
+* **xor-hash**: Distribute based on hash policy
+```
+**Examples:**
+```none
+# Use LACP (recommended for switch environments)
+set interfaces vpp bonding vppbond0 mode 802.3ad
+
+# Use active-backup for simple failover
+set interfaces vpp bonding vppbond0 mode active-backup
+```
+## Hash Policies
+For load balancing modes, configure how the system distributes traffic
+across member interfaces:
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> hash-policy \<policy\>
+
+Set the transmit hash policy:
+* **layer2**: Use MAC addresses to generate hash (default)
+* **layer2+3**: Combine MAC addresses and IP addresses
+* **layer3+4**: Combine IP addresses and port numbers
+```
+**Examples:**
+```none
+# Layer 2 hashing (default)
+set interfaces vpp bonding vppbond0 hash-policy layer2
+
+# Layer 3+4 for better distribution with multiple flows
+set interfaces vpp bonding vppbond0 hash-policy layer3+4
+```
+## MAC Address Configuration
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> mac \<mac-address\>
+
+Set a specific MAC address for the bonding interface.
+```
+**Example:**
+```none
+set interfaces vpp bonding vppbond0 mac 00:11:22:33:44:55
+```
+## IP Address Configuration
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> address \<ip-address/prefix\>
+
+Configure IPv4 or IPv6 addresses on the kernel interface. You can
+assign multiple addresses.
+```
+**Examples:**
+```none
+# IPv4 address
+set interfaces vpp bonding vppbond0 address 192.168.1.10/24
+
+# IPv6 address
+set interfaces vpp bonding vppbond0 address 2001:db8::10/64
+
+# Multiple addresses
+set interfaces vpp bonding vppbond0 address 192.168.1.10/24
+set interfaces vpp bonding vppbond0 address 10.0.0.10/8
+```
+## MTU Configuration
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> mtu \<size\>
+
+Set the Maximum Transmission Unit (MTU) for the kernel interface. The
+MTU must be compatible with the connected VPP interface.
+```
+**Example:**
+```none
+set interfaces vpp bonding vppbond0 mtu 9000
+```
+:::{note}
+The MTU setting must match or be smaller than the MTU supported by the
+associated VPP interface.
+:::
+
+## VLAN Configuration
+VPP kernel interfaces support VLAN (Virtual LAN) sub-interfaces for
+network segmentation.
+
+### Creating VLAN Sub-interfaces
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\>
+
+Create a VLAN sub-interface with the specified VLAN ID (0-4094).
+```
+**Example:**
+```none
+set interfaces vpp bonding vppbond0 vif 100
+```
+### VLAN Sub-interface Configuration
+VLAN sub-interfaces support the same configuration options as the parent
+interface:
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> address \<ip-address/prefix\>
+```
+
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> description \<description\>
+```
+
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> disable
+```
+
+```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> mtu \<size\>
+```
+**Examples:**
+```none
+# Configure VLAN 100
+set interfaces vpp bonding vppbond0 vif 100 address 192.168.100.1/24
+set interfaces vpp bonding vppbond0 vif 100 description "Management VLAN"
+set interfaces vpp bonding vppbond0 vif 100 mtu 1500
+
+# Configure VLAN 200
+set interfaces vpp bonding vppbond0 vif 200 address 192.168.200.1/24
+set interfaces vpp bonding vppbond0 vif 200 description "Guest VLAN"
+```
+## Complete Configuration Example
+Here's a complete example configuring a bonding interface with LACP:
+```none
+# Create bonding interface
+set interfaces vpp bonding vppbond0
+set interfaces vpp bonding vppbond0 description "Server uplink bond"
+
+# Configure bonding parameters
+set interfaces vpp bonding vppbond0 mode 802.3ad
+set interfaces vpp bonding vppbond0 hash-policy layer3+4
+
+# Add member interfaces
+set interfaces vpp bonding vppbond0 member interface eth0
+set interfaces vpp bonding vppbond0 member interface eth1
+
+# Configure IP on kernel interface
+set interfaces vpp bonding vppbond0 address 192.168.1.10/24
+```
+
+## Best Practices
+
+- Use **802.3ad mode** with LACP-capable switches for best performance
+  and standards compliance.
+- Configure **layer3+4 hash policy** for environments with multiple
+  traffic flows.
+- Ensure member interfaces have identical settings (speed, duplex,
+  MTU).
diff --git a/docs/vpp/configuration/interfaces/md-bridge.md b/docs/vpp/configuration/interfaces/md-bridge.md
new file mode 100644
index 00000000..f7b24b1d
--- /dev/null
+++ b/docs/vpp/configuration/interfaces/md-bridge.md
@@ -0,0 +1,169 @@
+---
+lastproofread: '2026-03-10'
+---
+
+(vpp-config-interfaces-bridge)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Bridge Configuration
+VPP bridge interfaces provide Layer 2 switching functionality, allowing
+multiple interfaces to be connected at the data link layer.
+
+VPP bridges operate as learning bridges, automatically discovering MAC
+addresses and building forwarding tables to efficiently switch traffic
+between member interfaces. This provides transparent connectivity between
+different network segments while maintaining the performance benefits of
+VPP's optimized data plane.
+
+**Supported Member Interface Types:**
+
+VPP bridges support various interface types as members:
+- Physical Ethernet interfaces (managed through linux-cp)
+- {doc}`bonding` - VPP bonding interfaces
+- {doc}`gre` - GRE tunnel interfaces
+- {doc}`loopback` - Loopback interfaces (required for BVI)
+- {doc}`vxlan` - VXLAN tunnel interfaces
+
+This flexibility allows you to create complex Layer 2 topologies
+combining different networking technologies.
+
+## Basic Configuration
+
+### Creating a Bridge Interface
+```{cfgcmd} set interfaces vpp bridge \<vppbrN\>
+
+Create a bridge interface where ``<vppbrN>`` follows the naming
+convention ``vppbr1``, ``vppbr2``, etc.
+```
+:::{note}
+Bridge domain `vppbr0` is reserved by VPP and cannot be
+configured through VyOS. Start with `vppbr1` for your bridge
+configurations.
+:::
+**Example:**
+```none
+set interfaces vpp bridge vppbr1
+```
+### Interface Description
+```{cfgcmd} set interfaces vpp bridge \<vppbrN\> description \<description\>
+
+Set a descriptive name for the bridge interface.
+```
+**Example:**
+```none
+set interfaces vpp bridge vppbr1 description "Main campus bridge"
+```
+## Member Interface Configuration
+### Adding Member Interfaces
+```{cfgcmd} set interfaces vpp bridge \<vppbrN\> member interface \<interface-name\>
+
+Add an interface as a member of the bridge.
+```
+**Examples:**
+```none
+# Add physical interfaces
+set interfaces vpp bridge vppbr1 member interface eth0
+set interfaces vpp bridge vppbr1 member interface eth1
+
+# Add other VPP interfaces
+set interfaces vpp bridge vppbr1 member interface vppbond0
+set interfaces vpp bridge vppbr1 member interface vppgre1
+```
+:::{important}
+Bridge members can include various interface types such as:
+- Physical Ethernet interfaces (eth0, eth1, etc.)
+- {doc}`bonding` - VPP bonding interfaces (vppbond0, vppbond1, etc.)
+- {doc}`gre` - GRE tunnel interfaces
+- {doc}`loopback` - Loopback interfaces
+- {doc}`vxlan` - VXLAN tunnel interfaces
+:::
+
+## Bridge Virtual Interface (BVI)
+A Bridge Virtual Interface (BVI) provides Layer 3 connectivity to a
+bridge domain, allowing the bridge to have an IP address and participate
+in routing.
+
+### Configuring BVI
+```{cfgcmd} set interfaces vpp bridge \<vppbrN\> member interface \<loopback-interface\> bvi
+
+Designate a loopback interface as the Bridge Virtual Interface for
+the bridge domain.
+```
+**Example:**
+```none
+# Create a loopback interface first
+set interfaces vpp loopback vpplo1
+
+# Add it to the bridge as BVI
+set interfaces vpp bridge vppbr1 member interface vpplo1 bvi
+```
+:::{important}
+**BVI Restrictions:**
+- Only loopback interfaces can be configured as BVI
+- Each bridge domain can have only one BVI interface
+:::
+
+## Configuration Examples
+
+### Basic Bridge Setup
+```none
+# Create bridge interface
+set interfaces vpp bridge vppbr1
+set interfaces vpp bridge vppbr1 description "Office network bridge"
+
+# Add member interfaces
+set interfaces vpp bridge vppbr1 member interface eth0
+set interfaces vpp bridge vppbr1 member interface eth1
+set interfaces vpp bridge vppbr1 member interface eth2
+```
+### Bridge with BVI
+```none
+# Create bridge and loopback for BVI
+set interfaces vpp bridge vppbr2
+set interfaces vpp bridge vppbr2 description "Server segment with gateway"
+set interfaces vpp loopback vpplo1
+
+# Configure bridge members
+set interfaces vpp bridge vppbr2 member interface eth3
+set interfaces vpp bridge vppbr2 member interface eth4
+set interfaces vpp bridge vppbr2 member interface vpplo1 bvi
+```
+### Multi-Technology Bridge
+```none
+# Create bridge combining different interface types
+set interfaces vpp bridge vppbr3
+set interfaces vpp bridge vppbr3 description "Hybrid network bridge"
+
+# Add various interface types
+set interfaces vpp bridge vppbr3 member interface vppbond1
+set interfaces vpp bridge vppbr3 member interface vppgre1
+set interfaces vpp bridge vppbr3 member interface vppvxlan1
+set interfaces vpp bridge vppbr3 member interface vpplo2 bvi
+```
+## Integration with Kernel Interfaces
+Bridge interfaces can be integrated with kernel interfaces for
+management and compatibility with standard Linux networking services.
+This is accomplished by binding a kernel interface to the Bridge
+Virtual Interface (BVI).
+
+**Example Integration:**
+```none
+# Create VPP bridge with member interfaces
+set interfaces vpp bridge vppbr1
+set interfaces vpp bridge vppbr1 member interface eth1
+set interfaces vpp bridge vppbr1 member interface eth2
+
+# Create loopback interface and configure as BVI
+set interfaces vpp loopback vpplo1
+set interfaces vpp bridge vppbr1 member interface vpplo1 bvi
+
+# Bind LCP kernel interface to the BVI loopback
+set interfaces vpp loopback vpplo1 address '192.0.2.1/24'
+```
+
+This configuration creates a kernel interface bound to the BVI,
+allowing standard Linux applications and routing daemons to interact
+with the VPP bridge. The kernel interface provides Layer 3 access to
+the bridge domain.
diff --git a/docs/vpp/configuration/interfaces/md-gre.md b/docs/vpp/configuration/interfaces/md-gre.md
new file mode 100644
index 00000000..fa91caae
--- /dev/null
+++ b/docs/vpp/configuration/interfaces/md-gre.md
@@ -0,0 +1,140 @@
+---
+lastproofread: '2026-03-13'
+---
+
+(vpp-config-interfaces-gre)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP GRE Configuration
+VPP GRE interfaces provide Generic Routing Encapsulation tunneling with
+high-performance packet processing. GRE tunnels encapsulate various
+protocols within IP packets, enabling connectivity across Layer 3
+networks while maintaining the performance benefits of VPP's optimized
+data plane.
+
+## Basic Configuration
+
+### Creating a GRE Interface
+```{cfgcmd} set interfaces vpp gre \<vppgreN\>
+
+Create a GRE interface where ``<vppgreN>`` follows the naming convention
+``vppgre1``, ``vppgre2``, etc.
+```
+
+```{cfgcmd} set interfaces vpp gre \<vppgreN\> remote \<address\>
+
+Set the tunnel remote endpoint address. Supports both IPv4 and IPv6
+addresses.
+```
+
+```{cfgcmd} set interfaces vpp gre \<vppgreN\> source-address \<address\>
+
+Set the tunnel source address. Must match an address configured on
+the local system.
+```
+**Basic Example:**
+```none
+set interfaces vpp gre vppgre1
+set interfaces vpp gre vppgre1 remote 203.0.113.2
+set interfaces vpp gre vppgre1 source-address 192.168.1.1
+```
+## Interface Configuration
+### Description and Administrative Control
+```{cfgcmd} set interfaces vpp gre \<vppgreN\> description \<description\>
+
+Set a descriptive name for the GRE interface.
+```
+
+```{cfgcmd} set interfaces vpp gre \<vppgreN\> disable
+
+Administratively disable the GRE interface.
+```
+### Tunnel Type
+```{cfgcmd} set interfaces vpp gre \<vppgreN\> tunnel-type \<type\>
+
+Set the GRE tunnel encapsulation type:
+* ``l3`` - Generic Routing Encapsulation for network layer traffic (default).
+* ``teb`` - Transparent Ethernet Bridge for Layer 2 frame transport.
+* ``erspan`` - Encapsulated Remote Switched Port Analyzer for traffic
+  mirroring.
+```
+### Kernel Interface Integration
+LCP kernel pair interface bound to the VPP GRE interface is created
+automatically. This allows standard Linux networking tools and
+services to interact with the VPP GRE.
+
+## IP Address Configuration
+```{cfgcmd} set interfaces vpp gre \<vppgreN\> address \<ip-address/prefix\>
+
+Configure IPv4 or IPv6 addresses on the kernel interface. Multiple
+addresses can be assigned.
+```
+**Examples:**
+```none
+# IPv4 address
+set interfaces vpp gre vppgre0 address 192.168.1.10/24
+
+# IPv6 address
+set interfaces vpp gre vppgre0 address 2001:db8::10/64
+```
+## MTU Configuration
+```{cfgcmd} set interfaces vpp gre \<vppgreN\> mtu \<size\>
+
+Set the Maximum Transmission Unit (MTU) for the kernel interface.
+The MTU must be compatible with the connected VPP interface.
+```
+**Example:**
+```none
+set interfaces vpp gre vppgre0 mtu 9000
+```
+:::{note}
+The MTU size must not exceed the MTU size
+supported by the associated VPP interface.
+:::
+
+## Configuration Examples
+
+### Layer 3 GRE Tunnel
+```none
+# IPv4 GRE tunnel
+set interfaces vpp gre vppgre1
+set interfaces vpp gre vppgre1 description "Site-to-site tunnel"
+set interfaces vpp gre vppgre1 remote 203.0.113.10
+set interfaces vpp gre vppgre1 source-address 192.168.1.1
+set interfaces vpp gre vppgre1 tunnel-type l3
+```
+### Layer 2 GRE Tunnel (TEB)
+```none
+# Transparent Ethernet Bridge
+set interfaces vpp gre vppgre2
+set interfaces vpp gre vppgre2 description "L2 extension tunnel"
+set interfaces vpp gre vppgre2 remote 203.0.113.20
+set interfaces vpp gre vppgre2 source-address 192.168.1.1
+set interfaces vpp gre vppgre2 tunnel-type teb
+```
+### IPv6 GRE Tunnel
+```none
+# IPv6 endpoints
+set interfaces vpp gre vppgre3
+set interfaces vpp gre vppgre3 remote 2001:db8::2
+set interfaces vpp gre vppgre3 source-address 2001:db8::1
+```
+### GRE with Kernel Interface
+```none
+# GRE tunnel with management interface
+set interfaces vpp gre vppgre4
+set interfaces vpp gre vppgre4 remote 203.0.113.30
+set interfaces vpp gre vppgre4 source-address 192.168.1.1
+set interfaces vpp gre vppgre4 address 10.0.1.1/30
+```
+## Bridge Integration
+GRE interfaces can be added as members to VPP bridges for Layer 2
+switching. See {doc}`bridge` for detailed bridge configuration.
+```none
+# Add TEB GRE tunnel to bridge
+set interfaces vpp bridge vppbr1
+set interfaces vpp bridge vppbr1 member interface vppgre2
+set interfaces vpp bridge vppbr1 member interface eth1
+```
diff --git a/docs/vpp/configuration/interfaces/md-index.md b/docs/vpp/configuration/interfaces/md-index.md
new file mode 100644
index 00000000..662f37c5
--- /dev/null
+++ b/docs/vpp/configuration/interfaces/md-index.md
@@ -0,0 +1,47 @@
+---
+lastproofread: '2026-03-13'
+---
+
+(vpp-config-interfaces-index)=
+
+```{include} /_include/need_improvement.txt
+```
+# VPP Interfaces Configuration
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+bonding
+bridge
+gre
+ipip
+loopback
+vxlan
+xconnect
+```
+
+VyOS utilizes VPP (Vector Packet Processor) to provide high-performance data
+plane processing. While physical interfaces are typically managed through the
+Linux kernel using `linux-cp` (Linux Control Plane) integration, VyOS also
+supports creating dedicated VPP interfaces for enhanced flexibility and
+performance.
+
+## Why VPP Interfaces?
+
+VPP interfaces offer several advantages:
+
+- **Total Isolation**: VPP interfaces operate entirely within the VPP data
+  plane, providing isolation from the Linux kernel when needed.
+- **Advanced Features**: Access to VPP-specific functionality not available
+  in standard Linux interfaces.
+- **Flexible Deployment**: Some interface types are only available as VPP
+  interfaces or may not be supported by the kernel.
+- **Specific scenarios**: Not all use cases require integration with the
+  Linux Kernel.
+
+### Integration with Kernel
+
+VyOS provides seamless integration between VPP and kernel networking.
+This allows you to leverage the strengths of both approaches:
+create interfaces inside VPP, and access them from the Linux kernel and other
+services.
diff --git a/docs/vpp/configuration/interfaces/md-ipip.md b/docs/vpp/configuration/interfaces/md-ipip.md
new file mode 100644
index 00000000..8a847e48
--- /dev/null
+++ b/docs/vpp/configuration/interfaces/md-ipip.md
@@ -0,0 +1,99 @@
+---
+lastproofread: '2026-03-13'
+---
+
+(vpp-config-interfaces-ipip)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP IPIP Configuration
+VPP IPIP interfaces provide IP-in-IP tunneling with high-performance
+packet processing. IPIP tunnels encapsulate IP packets within IP
+packets, creating point-to-point connections across Layer 3 networks.
+
+## Basic Configuration
+
+### Creating an IPIP Interface
+```{cfgcmd} set interfaces vpp ipip \<vppipipN\>
+
+Create an IPIP interface where ``<vppipipN>`` follows the naming
+convention ``vppipip1``, ``vppipip2``, etc.
+```
+
+```{cfgcmd} set interfaces vpp ipip \<vppipipN\> remote \<address\>
+
+Set the tunnel remote endpoint address. Supports both IPv4 and IPv6
+addresses.
+```
+
+```{cfgcmd} set interfaces vpp ipip \<vppipipN\> source-address \<address\>
+
+Set the tunnel source address. The source address must match an address
+configured on the local system.
+```
+**Basic Example:**
+```none
+set interfaces vpp ipip vppipip1
+set interfaces vpp ipip vppipip1 remote 203.0.113.2
+set interfaces vpp ipip vppipip1 source-address 192.168.1.1
+```
+## Interface Configuration
+### Description and Administrative Control
+```{cfgcmd} set interfaces vpp ipip \<vppipipN\> description \<description\>
+
+Set a descriptive name for the IPIP interface.
+```
+
+```{cfgcmd} set interfaces vpp ipip \<vppipipN\> disable
+
+Administratively disable the IPIP interface.
+```
+### Kernel Interface Integration
+Kernel interface is bound to the VPP IPIP interface for management and
+application compatibility.
+
+## IP Address Configuration
+```{cfgcmd} set interfaces vpp ipip \<vppipipN\> address \<ip-address/prefix\>
+
+Configure IPv4 or IPv6 addresses on the kernel interface. Multiple
+addresses can be assigned.
+```
+**Examples:**
+```none
+# IPv4 address
+set interfaces vpp ipip vppipip0 address 192.168.1.10/24
+
+# IPv6 address
+set interfaces vpp ipip vppipip0 address 2001:db8::10/64
+```
+## MTU Configuration
+```{cfgcmd} set interfaces vpp ipip \<vppipipN\> mtu \<size\>
+
+Set the Maximum Transmission Unit (MTU) for the kernel interface.
+The MTU must be compatible with the connected VPP interface.
+```
+## Configuration Examples
+### IPv4 IPIP Tunnel
+```none
+# Basic IPv4 IPIP tunnel
+set interfaces vpp ipip vppipip1
+set interfaces vpp ipip vppipip1 description "Site-to-site IPIP tunnel"
+set interfaces vpp ipip vppipip1 remote 203.0.113.10
+set interfaces vpp ipip vppipip1 source-address 192.168.1.1
+```
+### IPv6 IPIP Tunnel
+```none
+# IPv6 endpoints
+set interfaces vpp ipip vppipip2
+set interfaces vpp ipip vppipip2 remote 2001:db8::2
+set interfaces vpp ipip vppipip2 source-address 2001:db8::1
+```
+### IPIP with Kernel Interface
+```none
+# IPIP tunnel with management interface
+set interfaces vpp ipip vppipip3
+set interfaces vpp ipip vppipip3 remote 203.0.113.30
+set interfaces vpp ipip vppipip3 source-address 192.168.1.1
+set interfaces vpp ipip vppipip3 address 10.0.2.1/30
+```
diff --git a/docs/vpp/configuration/interfaces/md-loopback.md b/docs/vpp/configuration/interfaces/md-loopback.md
new file mode 100644
index 00000000..bc65338b
--- /dev/null
+++ b/docs/vpp/configuration/interfaces/md-loopback.md
@@ -0,0 +1,120 @@
+---
+lastproofread: '2026-03-13'
+---
+
+(vpp-config-interfaces-loopback)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Loopback Interface Configuration
+VPP loopback interfaces provide virtual interfaces that remain
+administratively up and are commonly used for stable addressing,
+routing protocols, and as Bridge Virtual Interfaces (BVI). Loopback
+interfaces in VPP offer high-performance virtual connectivity with optimized
+packet processing.
+
+## Basic Configuration
+
+### Creating a Loopback Interface
+```{cfgcmd} set interfaces vpp loopback \<vpploN\>
+
+Create a loopback interface where ``<vpploN>`` follows the naming
+convention ``vpplo1``, ``vpplo2``, etc.
+```
+**Basic Example:**
+```none
+set interfaces vpp loopback vpplo1
+```
+## Interface Configuration
+### Description and Administrative Control
+```{cfgcmd} set interfaces vpp loopback \<vpploN\> description \<description\>
+
+Set a descriptive name for the loopback interface.
+```
+
+```{cfgcmd} set interfaces vpp loopback \<vpploN\> disable
+
+Administratively disable the loopback interface.
+```
+### Kernel Interface Integration
+Kernel interface is bounded to the VPP loopback interface for management
+and application compatibility.
+
+## IP Address Configuration
+```{cfgcmd} set interfaces vpp loopback \<vpploN\> address \<ip-address/prefix\>
+
+Configure IPv4 or IPv6 addresses on the kernel interface. Multiple
+addresses can be assigned.
+```
+**Examples:**
+```none
+# IPv4 address
+set interfaces vpp loopback vpplo1 address 192.168.1.10/24
+
+# IPv6 address
+set interfaces vpp loopback vpplo1 address 2001:db8::10/64
+```
+## MTU Configuration
+```{cfgcmd} set interfaces vpp loopback \<vpploN\> mtu \<size\>
+
+Set the Maximum Transmission Unit (MTU) for the kernel interface.
+The MTU must be compatible with the connected VPP interface.
+```
+## VLAN Configuration
+VPP kernel interfaces support VLAN (Virtual LAN) sub-interfaces for network
+segmentation.
+
+### Creating VLAN Sub-interfaces
+```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\>
+
+Create a VLAN sub-interface with the specified VLAN ID (0-4094).
+```
+### VLAN Sub-interface Configuration
+VLAN sub-interfaces support the same configuration options as the parent
+interface:
+```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> address \<ip-address/prefix\>
+```
+
+```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> description \<description\>
+```
+
+```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> disable
+```
+
+```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> mtu \<size\>
+```
+**Examples:**
+```none
+# Configure VLAN 100
+set interfaces vpp loopback vpplo1 vif 100 address 192.168.100.1/24
+set interfaces vpp loopback vpplo1 vif 100 description "Management VLAN"
+set interfaces vpp loopback vpplo1 vif 100 mtu 1500
+
+# Configure VLAN 200
+set interfaces vpp loopback vpplo1 vif 200 address 192.168.200.1/24
+set interfaces vpp loopback vpplo1 vif 200 description "Guest VLAN"
+```
+## Configuration Examples
+### Basic Loopback Interface
+```none
+# Create simple loopback
+set interfaces vpp loopback vpplo1
+set interfaces vpp loopback vpplo1 description "Router ID interface"
+```
+### Loopback with Kernel Interface
+```none
+# Loopback with management access
+set interfaces vpp loopback vpplo2
+set interfaces vpp loopback vpplo2 description "Management loopback"
+set interfaces vpp loopback vpplo2 address 10.255.255.1/32
+```
+### Bridge Virtual Interface (BVI)
+```none
+# Loopback as BVI for bridge
+set interfaces vpp loopback vpplo3
+set interfaces vpp loopback vpplo3 description "Bridge gateway interface"
+set interfaces vpp bridge vppbr1
+set interfaces vpp bridge vppbr1 member interface vpplo3 bvi
+set interfaces vpp loopback vpplo3 address 192.168.100.1/24
+```
diff --git a/docs/vpp/configuration/interfaces/md-vxlan.md b/docs/vpp/configuration/interfaces/md-vxlan.md
new file mode 100644
index 00000000..6fa1322a
--- /dev/null
+++ b/docs/vpp/configuration/interfaces/md-vxlan.md
@@ -0,0 +1,132 @@
+---
+lastproofread: '2026-03-13'
+---
+
+(vpp-config-interfaces-vxlan)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP VXLAN Configuration
+VPP VXLAN interfaces provide virtual extensible local area network (VXLAN)
+tunneling with high-performance packet processing. VXLAN extends Layer 2
+domains across Layer 3 networks using UDP encapsulation, enabling scalable
+multi-tenant networking while leveraging VPP's optimized data plane.
+
+## Basic Configuration
+
+### Creating a VXLAN Interface
+```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\>
+
+Create a VXLAN interface where ``<vppvxlanN>`` follows the naming
+convention ``vppvxlan1``, ``vppvxlan2``, etc.
+```
+
+```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> vni \<vni\>
+
+Set the Virtual Network Identifier (VNI) for the VXLAN tunnel. Valid range
+is 0-16777214.
+```
+
+```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> remote \<address\>
+
+Set the tunnel remote endpoint address. Supports both IPv4 and IPv6
+addresses.
+```
+
+```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> source-address \<address\>
+
+Set the tunnel source address. Must match an address configured on the
+local system.
+```
+**Basic Example:**
+```none
+set interfaces vpp vxlan vppvxlan1
+set interfaces vpp vxlan vppvxlan1 vni 100
+set interfaces vpp vxlan vppvxlan1 remote 203.0.113.2
+set interfaces vpp vxlan vppvxlan1 source-address 192.168.1.1
+```
+## Interface Configuration
+### Description and Administrative Control
+```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> description \<description\>
+
+Set a descriptive name for the VXLAN interface.
+```
+
+```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> disable
+
+Administratively disable the VXLAN interface.
+```
+### Kernel Interface Integration
+The kernel interface is bound to the VXLAN tunnel for management and
+application compatibility.
+
+## IP Address Configuration
+```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> address \<ip-address/prefix\>
+
+Configure IPv4 or IPv6 addresses on the kernel interface. Multiple
+addresses can be assigned.
+```
+**Examples:**
+```none
+set interfaces vpp vxlan vppvxlan1 address 192.168.1.10/24
+set interfaces vpp vxlan vppvxlan1 address 2001:db8::10/64
+```
+## MTU Configuration
+```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> mtu \<size\>
+
+Set the Maximum Transmission Unit (MTU) for the kernel interface. The MTU
+must be compatible with the connected VPP interface.
+```
+## Configuration Examples
+### Basic VXLAN Tunnel
+```none
+# IPv4 VXLAN tunnel
+set interfaces vpp vxlan vppvxlan1
+set interfaces vpp vxlan vppvxlan1 description "Tenant A network extension"
+set interfaces vpp vxlan vppvxlan1 vni 1000
+set interfaces vpp vxlan vppvxlan1 remote 203.0.113.10
+set interfaces vpp vxlan vppvxlan1 source-address 192.168.1.1
+```
+### IPv6 VXLAN Tunnel
+```none
+# IPv6 endpoints
+set interfaces vpp vxlan vppvxlan2
+set interfaces vpp vxlan vppvxlan2 vni 2000
+set interfaces vpp vxlan vppvxlan2 remote 2001:db8::2
+set interfaces vpp vxlan vppvxlan2 source-address 2001:db8::1
+```
+### VXLAN with Kernel Interface
+```none
+# VXLAN tunnel with management interface
+set interfaces vpp vxlan vppvxlan3
+set interfaces vpp vxlan vppvxlan3 vni 3000
+set interfaces vpp vxlan vppvxlan3 remote 203.0.113.30
+set interfaces vpp vxlan vppvxlan3 source-address 192.168.1.1
+set interfaces vpp vxlan vppvxlan3 address 10.0.3.1/24
+```
+## Bridge Integration
+VXLAN interfaces are commonly used as members in VPP bridges for Layer 2
+extension. See {doc}`bridge` for more information.
+```none
+# Add VXLAN tunnel to bridge
+set interfaces vpp bridge vppbr1
+set interfaces vpp bridge vppbr1 member interface vppvxlan1
+set interfaces vpp bridge vppbr1 member interface eth1
+set interfaces vpp bridge vppbr1 member interface vpplo1 bvi
+```
+### Multi-Tenant Configuration
+```none
+# Multiple VNIs for tenant separation
+set interfaces vpp vxlan vppvxlan10
+set interfaces vpp vxlan vppvxlan10 description "Tenant A - Production"
+set interfaces vpp vxlan vppvxlan10 vni 1001
+set interfaces vpp vxlan vppvxlan10 remote 203.0.113.20
+set interfaces vpp vxlan vppvxlan10 source-address 192.168.1.1
+
+set interfaces vpp vxlan vppvxlan11
+set interfaces vpp vxlan vppvxlan11 description "Tenant A - Development"
+set interfaces vpp vxlan vppvxlan11 vni 1002
+set interfaces vpp vxlan vppvxlan11 remote 203.0.113.21
+set interfaces vpp vxlan vppvxlan11 source-address 192.168.1.1
+```
diff --git a/docs/vpp/configuration/interfaces/md-xconnect.md b/docs/vpp/configuration/interfaces/md-xconnect.md
new file mode 100644
index 00000000..0ee052d2
--- /dev/null
+++ b/docs/vpp/configuration/interfaces/md-xconnect.md
@@ -0,0 +1,94 @@
+---
+lastproofread: '2026-03-13'
+---
+
+(vpp-config-interfaces-xconnect)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP XConnect Configuration
+VPP XConnect provides direct Layer 2 packet forwarding between two
+interfaces with maximum transparency and minimal overhead. XConnect
+creates a simple point-to-point bridge that forwards all Layer 2 packets
+bidirectionally without MAC learning or flooding, making it ideal for
+transparent connectivity scenarios.
+
+XConnect operates as a super-transparent bridge, forwarding all frames
+between the connected interfaces without any packet inspection or
+modification. This provides the simplest possible Layer 2 forwarding with
+VPP's high-performance packet processing.
+
+## Comparison with Bridges
+- **XConnect**: Point-to-point only, no MAC learning, maximum
+  transparency, minimal overhead
+- **Bridge**: Multi-port, MAC learning, broadcast handling, more
+  features but higher overhead
+
+Choose XConnect when you need simple point-to-point Layer 2 forwarding
+with maximum performance and transparency. Use bridges when you need
+multi-port switching with MAC learning and broadcast handling.
+
+## Basic Configuration
+
+### Creating an XConnect Interface
+```{cfgcmd} set interfaces vpp xconnect \<vppxconN\>
+
+Create an XConnect interface where ``<vppxconN>`` follows the naming
+convention ``vppxcon1``, ``vppxcon2``, etc.
+```
+
+```{cfgcmd} set interfaces vpp xconnect \<vppxconN\> member interface \<interface-name\>
+
+Add an interface as a member of the XConnect. Exactly two member
+interfaces must be configured to create bidirectional forwarding.
+```
+**Basic Example:**
+```none
+set interfaces vpp xconnect vppxcon1
+set interfaces vpp xconnect vppxcon1 member interface eth0
+set interfaces vpp xconnect vppxcon1 member interface eth1
+```
+This configuration creates transparent forwarding between `eth0` and `eth1`,
+where any packet received on either interface is immediately forwarded to
+the other without any processing.
+
+## Interface Configuration
+```{cfgcmd} set interfaces vpp xconnect \<vppxconN\> description \<description\>
+
+Set a descriptive name for the XConnect interface.
+```
+## Configuration Examples
+### Physical Interface XConnect
+```none
+# Connect two physical interfaces
+set interfaces vpp xconnect vppxcon1
+set interfaces vpp xconnect vppxcon1 description "Transparent wire between ports"
+set interfaces vpp xconnect vppxcon1 member interface eth0
+set interfaces vpp xconnect vppxcon1 member interface eth1
+```
+This creates a transparent wire between two physical ports, effectively
+making them function as a single cable.
+
+### Tunnel to Physical XConnect
+```none
+# Connect tunnel to physical interface
+set interfaces vpp xconnect vppxcon2
+set interfaces vpp xconnect vppxcon2 description "GRE tunnel to physical bridge"
+set interfaces vpp xconnect vppxcon2 member interface vppgre1
+set interfaces vpp xconnect vppxcon2 member interface eth2
+```
+This forwards all traffic from a GRE tunnel directly to a physical
+interface and vice versa.
+
+### Mixed Interface Types
+```none
+# Connect different interface types
+set interfaces vpp xconnect vppxcon3
+set interfaces vpp xconnect vppxcon3 description "VXLAN to bonding bridge"
+set interfaces vpp xconnect vppxcon3 member interface vppvxlan1
+set interfaces vpp xconnect vppxcon3 member interface vppbond0
+```
+
+This demonstrates XConnect's flexibility in connecting various VPP interface
+types.
diff --git a/docs/vpp/configuration/md-acl.md b/docs/vpp/configuration/md-acl.md
new file mode 100644
index 00000000..59b96070
--- /dev/null
+++ b/docs/vpp/configuration/md-acl.md
@@ -0,0 +1,485 @@
+---
+lastproofread: '2025-09-04'
+---
+
+(vpp-config-acl)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP ACL Configuration
+VPP ACLs (Access Control Lists) provide a way to filter traffic passing through VPP interfaces. They offer a high-performance packet filtering solution that can be used as a fast firewall alternative.
+
+VyOS VPP ACL implementation supports two main types of access control lists:
+- **IP ACLs** - Layer 3 filtering based on IPv4/IPv6 addresses, ports, and protocols (can be applied to both input and output directions)
+- **MAC ACLs** - Layer 2 filtering based on MAC addresses and IP prefixes (can only be applied to input direction)
+
+## Structure and Components
+
+### Tags
+ACL tags are named rule sets that contain one or more access control entries (ACEs). Tags provide a way to group related rules and apply them consistently across different interfaces.
+- Tag names are user-defined text strings
+- Each tag can contain multiple numbered rules
+- Tags can be applied to interfaces in input or output direction
+- Multiple tags can be applied to a single interface
+
+### Interface Application
+ACL tags are applied to interfaces to control traffic flow:
+- **Input direction**: Filters traffic entering the interface
+- **Output direction**: Filters traffic leaving the interface
+
+:::{note}
+**Important Limitation**: MAC ACLs can only be applied to the input direction of interfaces. They cannot filter outbound traffic. Use IP ACLs if you need to filter traffic in both directions.
+:::
+
+### Rule Processing
+Rules within an ACL are processed in numerical order (lowest to highest). The first matching rule determines the action taken on the packet.
+
+Available actions:
+- `permit` - Allow the packet to continue
+- `deny` - Drop the packet
+- `permit-reflect` - Allow traffic and automatically permit return traffic
+
+## L3/IP ACLs
+IP ACLs provide Layer 3 filtering capabilities based on IPv4 and IPv6 addresses, port numbers, and protocols. They support both stateless and stateful (reflexive) filtering.
+
+### Creating IP ACL Tags
+IP ACL tags are created under the `vpp acl ip` configuration node:
+```none
+set vpp acl ip tag-name <tag-name>
+set vpp acl ip tag-name <tag-name> description '<description>'
+```
+Example:
+```none
+set vpp acl ip tag-name 'WEB-FILTER'
+set vpp acl ip tag-name 'WEB-FILTER' description 'Web server access control'
+```
+### Adding Rules to IP ACL Tags
+Rules are added to IP ACL tags with specific rule numbers:
+```none
+set vpp acl ip tag-name <tag-name> rule <rule-number>
+```
+#### Basic IP ACL Rule Configuration
+Each rule requires an action and matching criteria:
+```none
+set vpp acl ip tag-name <tag-name> rule <rule-number> action <permit|deny|permit-reflect>
+set vpp acl ip tag-name <tag-name> rule <rule-number> description '<description>'
+set vpp acl ip tag-name <tag-name> rule <rule-number> protocol <protocol>
+```
+**Actions:**
+- `permit` - Allow matching traffic
+- `deny` - Block matching traffic
+- `permit-reflect` - Allow outbound traffic and automatically permit return traffic
+
+**Protocols:**
+- `all` - Match all IP protocols (default)
+- Or specific protocol by name, e.g. `tcp`, `udp`, `icmp`
+
+#### Source and Destination Matching
+Configure source and destination parameters:
+```none
+# Source configuration
+set vpp acl ip tag-name <tag-name> rule <rule-number> source prefix <ip-prefix>
+set vpp acl ip tag-name <tag-name> rule <rule-number> source port <port-spec>
+
+# Destination configuration  
+set vpp acl ip tag-name <tag-name> rule <rule-number> destination prefix <ip-prefix>
+set vpp acl ip tag-name <tag-name> rule <rule-number> destination port <port-spec>
+```
+**Prefix Specification:**
+- `<x.x.x.x/x>` - IPv4 prefix in CIDR notation
+- `<h:h:h:h:h:h:h:h/x>` - IPv6 prefix in CIDR notation
+
+**Port Specification:**
+- `<1-65535>` - Single port number
+- `<start>-<end>` - Port range (e.g., 1001-1005)
+
+#### TCP Flags Matching
+For TCP protocol rules, you can match specific TCP flags:
+```none
+# Match packets with specific flags set
+set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags is-set <ack|cwr|ecn|fin|psh|rst|syn|urg>
+
+# Match packets without specific flags set
+set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags is-not-set <ack|cwr|ecn|fin|psh|rst|syn|urg>
+```
+### IP ACL Configuration Examples
+#### Example 1: Basic Web Server ACL
+```none
+# Create ACL for web server access
+set vpp acl ip tag-name 'WEB-SERVER'
+set vpp acl ip tag-name 'WEB-SERVER' description 'Web server access control'
+
+# Allow HTTP traffic
+set vpp acl ip tag-name 'WEB-SERVER' rule 10 action permit
+set vpp acl ip tag-name 'WEB-SERVER' rule 10 protocol tcp
+set vpp acl ip tag-name 'WEB-SERVER' rule 10 destination port 80
+
+# Allow HTTPS traffic
+set vpp acl ip tag-name 'WEB-SERVER' rule 20 action permit
+set vpp acl ip tag-name 'WEB-SERVER' rule 20 protocol tcp
+set vpp acl ip tag-name 'WEB-SERVER' rule 20 destination port 443
+
+# Deny all other traffic
+set vpp acl ip tag-name 'WEB-SERVER' rule 999 action deny
+set vpp acl ip tag-name 'WEB-SERVER' rule 999 protocol all
+```
+#### Example 2: Network Segmentation ACL
+```none
+# Create ACL for network segmentation
+set vpp acl ip tag-name 'DMZ-FILTER'
+set vpp acl ip tag-name 'DMZ-FILTER' description 'DMZ to internal network filter'
+
+# Allow specific internal subnet access
+set vpp acl ip tag-name 'DMZ-FILTER' rule 10 action permit
+set vpp acl ip tag-name 'DMZ-FILTER' rule 10 destination prefix '192.168.100.0/24'
+set vpp acl ip tag-name 'DMZ-FILTER' rule 10 protocol tcp
+set vpp acl ip tag-name 'DMZ-FILTER' rule 10 destination port 443
+
+# Allow DNS queries
+set vpp acl ip tag-name 'DMZ-FILTER' rule 20 action permit
+set vpp acl ip tag-name 'DMZ-FILTER' rule 20 destination prefix '192.168.1.10/32'
+set vpp acl ip tag-name 'DMZ-FILTER' rule 20 protocol udp
+set vpp acl ip tag-name 'DMZ-FILTER' rule 20 destination port 53
+
+# Block everything else to internal networks
+set vpp acl ip tag-name 'DMZ-FILTER' rule 100 action deny
+set vpp acl ip tag-name 'DMZ-FILTER' rule 100 destination prefix '192.168.0.0/16'
+```
+#### Example 3: Reflexive ACL
+```none
+# Create reflexive ACL for outbound connections
+set vpp acl ip tag-name 'OUTBOUND-REFLECT'
+set vpp acl ip tag-name 'OUTBOUND-REFLECT' description 'Allow outbound with return traffic'
+
+# Allow outbound HTTP/HTTPS with return traffic
+set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 10 action permit-reflect
+set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 10 protocol tcp
+set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 10 destination port 80
+
+set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 20 action permit-reflect
+set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 20 protocol tcp
+set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 20 destination port 443
+```
+### Applying IP ACL Tags to Interfaces
+IP ACL tags are applied to interfaces using the interface configuration:
+```none
+# Apply to input direction
+set vpp acl ip interface <interface> input acl-tag <number> tag-name <tag-name>
+
+# Apply to output direction  
+set vpp acl ip interface <interface> output acl-tag <number> tag-name <tag-name>
+```
+Where:
+- `<interface>` - Interface name (e.g., eth0, eth1)
+- `<number>` - ACL rule number (0-4294967295) for ordering multiple ACL tags
+- `<tag-name>` - Name of the ACL tag to apply
+
+Multiple tags can be applied to the same interface and direction by using different ACL rule numbers.
+
+Example:
+```none
+# Apply web server ACL to input direction
+set vpp acl ip interface eth0 input acl-tag 10 tag-name 'WEB-SERVER'
+
+# Apply outbound reflexive ACL to output direction
+set vpp acl ip interface eth1 output acl-tag 10 tag-name 'OUTBOUND-REFLECT'
+
+# Apply multiple ACLs to the same interface and direction
+set vpp acl ip interface eth0 input acl-tag 20 tag-name 'FIREWALL'
+```
+## L2/MAC ACLs
+MAC ACLs provide Layer 2 filtering capabilities based on MAC addresses and IP prefixes. They are particularly useful for controlling access at the data link layer.
+
+:::{important}
+**Direction Limitation**: MAC ACLs can **only** be applied to the **input direction** of interfaces. They cannot filter outbound/output traffic. If you need bidirectional filtering, use IP ACLs instead.
+:::
+
+### Creating MAC ACL Tags
+MAC ACL tags are created under the `vpp acl mac` configuration node:
+```none
+set vpp acl mac tag-name <tag-name>
+set vpp acl mac tag-name <tag-name> description '<description>'
+```
+Example:
+```none
+set vpp acl mac tag-name 'MAC-FILTER'
+set vpp acl mac tag-name 'MAC-FILTER' description 'Layer 2 MAC address filtering'
+```
+### Adding Rules to MAC ACL Tags
+Rules are added to MAC ACL tags with specific rule numbers:
+```none
+set vpp acl mac tag-name <tag-name> rule <rule-number>
+```
+#### Basic MAC ACL Rule Configuration
+Each rule requires an action and matching criteria:
+```none
+set vpp acl mac tag-name <tag-name> rule <rule-number> action <permit|deny>
+set vpp acl mac tag-name <tag-name> rule <rule-number> description '<description>'
+```
+**Actions:**
+- `permit` - Allow matching traffic
+- `deny` - Block matching traffic
+
+Note: MAC ACLs do not support the `permit-reflect` action available in IP ACLs.
+
+#### MAC Address Matching
+Configure MAC address matching criteria:
+```none
+set vpp acl mac tag-name <tag-name> rule <rule-number> mac-address <mac-address>
+set vpp acl mac tag-name <tag-name> rule <rule-number> mac-mask <mac-mask>
+```
+**MAC Address Specification:**
+- `mac-address` - Source MAC address to match (format: xx:xx:xx:xx:xx:xx)
+- `mac-mask` - MAC address mask (default: ff:ff:ff:ff:ff:ff for exact match)
+
+The MAC mask allows for partial MAC address matching. For example:
+\- `ff:ff:ff:00:00:00` matches the first 3 octets (OUI)
+\- `ff:ff:ff:ff:ff:ff` matches the complete MAC address (default)
+
+#### IP Prefix Matching
+Configure IP prefix matching for the source:
+```none
+set vpp acl mac tag-name <tag-name> rule <rule-number> prefix <ip-prefix>
+```
+**Prefix Specification:**
+- Supports both IPv4 and IPv6 prefixes in CIDR notation
+- Examples: `192.168.1.0/24`, `10.0.0.0/8`, `2001:db8::/32`
+
+### MAC ACL Configuration Examples
+
+#### Example 1: Device Whitelist
+```none
+# Create MAC ACL for device whitelisting
+set vpp acl mac tag-name 'DEVICE-WHITELIST'
+set vpp acl mac tag-name 'DEVICE-WHITELIST' description 'Allow only approved devices'
+
+# Allow specific workstation
+set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 action permit
+set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 mac-address '00:1b:21:12:34:56'
+set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 prefix '192.168.1.100/32'
+set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 description 'Admin workstation'
+
+# Allow specific server
+set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 action permit
+set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 mac-address '00:1b:21:78:90:ab'
+set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 prefix '192.168.1.10/32'
+set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 description 'Web server'
+
+# Deny everything else
+set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 999 action deny
+set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 999 mac-address '00:00:00:00:00:00'
+set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 999 mac-mask '00:00:00:00:00:00'
+```
+#### Example 2: Vendor-Based Filtering
+```none
+# Create MAC ACL for vendor-based filtering
+set vpp acl mac tag-name 'VENDOR-FILTER'
+set vpp acl mac tag-name 'VENDOR-FILTER' description 'Filter by MAC vendor OUI'
+
+# Deny Realtek devices (OUI: 00:e0:4c)
+set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 action deny
+set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 mac-address '00:e0:4c:00:00:00'
+set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 mac-mask 'ff:ff:ff:00:00:00'
+set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 description 'Block Realtek devices'
+
+# Allow all other devices
+set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 action permit
+set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 mac-address '00:00:00:00:00:00'
+set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 mac-mask '00:00:00:00:00:00'
+set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 description 'Allow all other vendors'
+```
+#### Example 3: Network Segmentation by MAC
+```none
+# Create MAC ACL for network segmentation
+set vpp acl mac tag-name 'SEGMENT-FILTER'
+set vpp acl mac tag-name 'SEGMENT-FILTER' description 'Segment networks by MAC/IP binding'
+
+# Allow management VLAN devices
+set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 action permit
+set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 mac-address '02:01:00:00:00:00'
+set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 mac-mask 'ff:ff:00:00:00:00'
+set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 prefix '10.1.0.0/16'
+set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 description 'Management VLAN'
+
+# Allow user VLAN devices
+set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 action permit
+set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 mac-address '02:02:00:00:00:00'
+set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 mac-mask 'ff:ff:00:00:00:00'
+set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 prefix '10.2.0.0/16'
+set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 description 'User VLAN'
+```
+### Applying MAC ACL Tags to Interfaces
+MAC ACL tags can only be applied to the input direction of interfaces:
+```none
+set vpp acl mac interface <interface> tag-name <tag-name>
+```
+:::{note}
+**Syntax Difference**: Unlike IP ACLs, MAC ACL interface application does not use the `acl-tag <number>` structure since only single MAC ACLs can be applied.
+:::
+
+:::{warning}
+Unlike IP ACLs, MAC ACLs do **not** support output direction filtering. There is no `output` option available for MAC ACL interface application.
+:::
+Example:
+```none
+# Apply MAC filtering to interface input
+set vpp acl mac interface eth0 tag-name 'MAC-FILTER'
+set vpp acl mac interface eth1 tag-name 'DEVICE-WHITELIST'
+```
+## Configuration Best Practices
+
+### Rule Ordering
+- **Number rules strategically**: Use gaps between rule numbers (10, 20, 30) to allow for future insertions
+- **Place specific rules first**: More specific matches should have lower rule numbers
+- **End with catch-all**: Always include a final rule that matches all traffic with explicit action
+- **Document rules**: Use descriptions for complex rules to aid troubleshooting
+
+### Performance Considerations
+- **Minimize rule count**: Fewer rules generally mean better performance
+- **Use appropriate ACL type**: Use MAC ACLs for Layer 2/3 filtering, IP ACLs for Layer 3/4 filtering
+- **Consider direction limitations**: Remember that MAC ACLs only work on input traffic; use IP ACLs for filtering in both directions
+- **Combine related rules**: Group similar filtering requirements into single ACL tags
+- **Apply strategically**: Apply ACLs at ingress points where possible to minimize processing
+
+## Troubleshooting
+
+### Common Issues
+- **ACL not taking effect:**
+  - Verify ACL is applied to correct interface and direction
+  - Check rule numbering and order
+  - Ensure interface is properly configured in VPP
+- **Performance degradation:**
+  - Review ACL complexity and rule count
+  - Consider consolidating rules
+  - Check for unnecessary broad matches
+- **Traffic blocked unexpectedly:**
+  - Review rule order (first match wins)
+  - Check for overly restrictive rules
+  - Verify protocol and port specifications
+
+### Verification Commands
+Use these commands to verify ACL configuration and operation:
+```none
+# Show VPP ACL configuration
+show configuration commands | grep "vpp acl"
+
+# Show VPP interface configuration
+show configuration commands | grep "vpp acl.*interface"
+
+# View commit history for ACL changes
+show configuration commit-revisions | grep -A5 -B5 "vpp acl"
+```
+## Operational Commands
+VyOS provides several operational commands to monitor and troubleshoot VPP ACL configurations and their status.
+
+### Viewing All ACLs
+Display all configured ACLs (both IP and MAC):
+```{opcmd} show vpp acl
+```
+This command shows a summary of all configured ACL tags with their rules, displaying both IP ACLs and MAC ACLs in a tabular format.
+Example output:
+```none
+---------------------------------
+IP ACL "tag-name WEB-SERVER" acl_index 0
+
+Rule  Action    Src prefix    Src port    Dst prefix    Dst port      Proto  TCP flags set    TCP flags not set
+------  --------  ------------  ----------  ------------  ----------  -------  ---------------  -------------------
+    10  permit    0.0.0.0/0     0-65535     0.0.0.0/0     80                6
+    20  permit    0.0.0.0/0     0-65535     0.0.0.0/0     443               6
+    999  deny     0.0.0.0/0     0-65535     0.0.0.0/0     0-65535           0
+
+---------------------------------
+MACIP ACL "tag-name VENDOR-FILTER" acl_index 0
+
+Rule  Action    IP prefix    MAC address        MAC mask
+------  --------  -----------  -----------------  -----------------
+    10  deny      0.0.0.0/0    00:e0:4c:00:00:00  ff:ff:ff:00:00:00
+    100  permit   0.0.0.0/0    00:00:00:00:00:00  00:00:00:00:00:00
+```
+### IP ACL Commands
+View all IP ACLs:
+```{opcmd} show vpp acl ip
+```
+View IP ACL interface assignments:
+```{opcmd} show vpp acl ip interface
+```
+Example output:
+```none
+Interface    Input ACLs    Output ACLs
+-----------  ------------  -------------
+eth1         WEB-SERVER
+```
+View specific IP ACL by tag name:
+```{opcmd} show vpp acl ip tag-name \<tag-name\>
+```
+Example:
+```none
+vyos@vyos:~$ show vpp acl ip tag-name WEB-SERVER 
+
+---------------------------------
+IP ACL "tag-name WEB-SERVER" acl_index 0
+
+  Rule  Action    Src prefix    Src port    Dst prefix    Dst port      Proto  TCP flags set    TCP flags not set
+------  --------  ------------  ----------  ------------  ----------  -------  ---------------  -------------------
+    10  permit    0.0.0.0/0     0-65535     0.0.0.0/0     80                6
+    20  permit    0.0.0.0/0     0-65535     0.0.0.0/0     443               6
+   999  deny      0.0.0.0/0     0-65535     0.0.0.0/0     0-65535           0
+```
+### MAC ACL Commands
+View all MAC ACLs:
+```{opcmd} show vpp acl mac
+```
+View MAC ACL interface assignments:
+```{opcmd} show vpp acl mac interface
+```
+Example output:
+```none
+Interface    ACL
+-----------  -----
+eth0         VENDOR-FILTER
+```
+View specific MAC ACL by tag name:
+```{opcmd} show vpp acl mac tag-name \<tag-name\>
+```
+Example:
+```none
+vyos@vyos:~$ show vpp acl mac tag-name VENDOR-FILTER
+
+---------------------------------
+MACIP ACL "tag-name VENDOR-FILTER" acl_index 0
+
+  Rule  Action    IP prefix    MAC address        MAC mask
+------  --------  -----------  -----------------  -----------------
+    10  deny      0.0.0.0/0    00:e0:4c:00:00:00  ff:ff:ff:00:00:00
+   100  permit    0.0.0.0/0    00:00:00:00:00:00  00:00:00:00:00:00
+```
+
+### Understanding Command Output
+
+**IP ACL Output Fields:**
+
+- **Rule**: Rule number within the ACL
+- **Action**: permit, deny, or permit-reflect
+- **Src prefix**: Source IP prefix (0.0.0.0/0 = any source)
+- **Src port**: Source port range (0-65535 = any port)
+- **Dst prefix**: Destination IP prefix
+- **Dst port**: Destination port or port range
+- **Proto**: IP protocol number (6=TCP, 17=UDP, 1=ICMP, 0=any)
+- **TCP flags set**: Required TCP flags (for TCP protocol)
+- **TCP flags not set**: Prohibited TCP flags (for TCP protocol)
+
+**MAC ACL Output Fields:**
+
+- **Rule**: Rule number within the ACL
+- **Action**: permit or deny
+- **IP prefix**: Source IP prefix constraint
+- **MAC address**: Source MAC address to match
+- **MAC mask**: MAC address mask for partial matching
+
+**Interface Assignment Output:**
+
+- Shows which interfaces have ACLs applied
+- **Input ACLs**: ACL tags applied to incoming traffic
+- **Output ACLs**: ACL tags applied to outgoing traffic (IP ACLs only)
+- **ACL**: MAC ACL tag applied to interface (input only)
diff --git a/docs/vpp/configuration/md-index.md b/docs/vpp/configuration/md-index.md
new file mode 100644
index 00000000..7e02ae74
--- /dev/null
+++ b/docs/vpp/configuration/md-index.md
@@ -0,0 +1,41 @@
+---
+lastproofread: '2025-09-04'
+---
+
+(vpp-dconfig-index)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Configuration
+VPP settings consist of several main sections.
+
+Main Dataplane settings and internal VPP interfaces:
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+dataplane/index
+interfaces/index
+```
+Features that can be enabled on VPP Dataplane:
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+acl
+ipfix
+ipsec
+nat/index
+sflow
+```
+
+## VPP Initialization
+
+When VPP Dataplane is configured and the configuration is committed, VyOS will attempt to start VPP and initialize all interfaces assigned to it. During this process the following steps occur:
+
+1. VyOS checks that the system meets all requirements for VPP operation. If any requirement is not met, VPP will not start and an error message will be displayed.
+2. VPP is started and its initial configuration is applied.
+3. All interfaces assigned to VPP are initialized and brought up.
+4. A special virtual interfaces are reinstalled to the kernel with the same names as interfaces that were attached to VPP to maintain compatibility with the configuration.
+5. VyOS configuration initializes those virtual interfaces, so that features that exist only in kernel dataplane continue to operate.
diff --git a/docs/vpp/configuration/md-ipfix.md b/docs/vpp/configuration/md-ipfix.md
new file mode 100644
index 00000000..7ed2aee3
--- /dev/null
+++ b/docs/vpp/configuration/md-ipfix.md
@@ -0,0 +1,50 @@
+# VPP IPFIX Configuration
+
+VPP IPFIX in VyOS allows monitoring and exporting network traffic flows
+for analytics, security, and accounting. IPFIX works with the VPP
+(Vector Packet Processing) backend to provide high-performance flow tracking.
+
+## Overview
+
+VyOS integrates VPP for high-performance packet processing. IPFIX
+configuration controls how flows are monitored, exported, and which
+interfaces are included.
+
+## Key IPFIX Concepts
+
+- **Active timeout**: Maximum time a flow is kept active before export.
+- **Inactive timeout**: Maximum time an idle flow is kept before export.
+- **Collector**: The remote host and port to which flow records are sent.
+- **Flow layers**: Determines which layer information is included
+  (`l2`, `l3`, `l4`).
+- **Interfaces**: Physical or virtual interfaces to monitor.
+- **Direction**: Which traffic to monitor (`rx`, `tx`, `both`).
+- **Flow variant**: Optional filter for IPv4 or IPv6 flows.
+
+## Configuration Options
+
+- **active-timeout**: Duration (in seconds) after which active flows
+  are exported.
+- **inactive-timeout**: Duration (in seconds) after which idle flows
+  are exported.
+- **collector \`\<ip>\` port \`\<port>\`**: IP and UDP port of the IPFIX collector.
+- **collector \`\<ip>\` source-address \`\<ip>\`**: Source address for flow export.
+- **flowprobe-record \`\<l2|l3|l4>\`**: Layers to include in flow records.
+- **interface** `<interface>` **\[direction** `<rx|tx|both>`**\]**
+  **\[flow-variant** `<ipv4|ipv6>`**\]**: Interfaces to monitor,
+  direction of traffic, and optional flow variant filter.
+
+## Example Configuration
+
+```none
+set vpp ipfix active-timeout '15'
+set vpp ipfix inactive-timeout '120'
+set vpp ipfix collector 192.0.2.2 port '4739'
+set vpp ipfix collector 192.0.2.2 source-address '192.0.2.1'
+set vpp ipfix flowprobe-record 'l2'
+set vpp ipfix flowprobe-record 'l3'
+set vpp ipfix flowprobe-record 'l4'
+set vpp ipfix interface eth0
+set vpp ipfix interface eth1 direction 'both'
+set vpp ipfix interface eth1 flow-variant 'ipv4'
+```
diff --git a/docs/vpp/configuration/md-sflow.md b/docs/vpp/configuration/md-sflow.md
new file mode 100644
index 00000000..752b8377
--- /dev/null
+++ b/docs/vpp/configuration/md-sflow.md
@@ -0,0 +1,37 @@
+---
+lastproofread: '2025-09-04'
+---
+
+(vpp-config-sflow)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP sFlow Configuration
+VPP Dataplane in VyOS support sFlow for traffic monitoring and analysis.
+
+The VPP Dataplane integration works hand-in-hand with normal kernel sFlow agent, which is responsible for collecting and exporting sFlow samples. VPP itself is responsible for generating the samples.
+
+To enable sFlow in VPP, you first need to configure the service using the same steps as for normal kernel sFlow agent, as described in {doc}`/configuration/system/sflow`. Then you can enable sFlow on VPP interfaces.
+
+Then, you need to enable sFlow on the VPP interfaces you want to monitor. This is done using the following commands:
+```{cfgcmd} set vpp sflow interface \<interface-name\>
+```
+This will enable sFlow on the specified interface. You can repeat this command for each interface you want to monitor.
+
+:::{note}
+sFlow collects statistics only for traffic *received* on the interface. If you want to monitor traffic *sent* on the interface, you need to enable sFlow on the corresponding interface in the opposite direction.
+:::
+Optionally, you can specify the number of bytes from each packet that should be included in the sFlow sample using the following command:
+```{cfgcmd} set vpp sflow header-bytes \<bytes\>
+```
+This defines the size of the packet header (in bytes) captured for each sFlow sample.
+
+The sampling rate is configured globally under the `system sflow` section and automatically applied to VPP sFlow.
+This ensures consistent sampling behavior between the system and VPP, and prevents configuration conflicts.
+
+Finally, you need to enable integration between VPP and the kernel sFlow agent using the following command:
+```{cfgcmd} set system sflow vpp
+```
+
+After this, collecting and exporting sFlow samples will be handled by the kernel sFlow agent, while VPP will generate the samples.
diff --git a/docs/vpp/configuration/nat/md-index.md b/docs/vpp/configuration/nat/md-index.md
new file mode 100644
index 00000000..4d5c01d1
--- /dev/null
+++ b/docs/vpp/configuration/nat/md-index.md
@@ -0,0 +1,41 @@
+---
+lastproofread: '2026-03-05'
+---
+
+(vpp-config-nat-index)=
+
+```{include} /_include/need_improvement.txt
+
+```
+# VPP NAT Configuration
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+cgnat
+nat44
+```
+
+VPP Dataplane in VyOS supports two types of NAT:
+
+## NAT44
+
+This type is a classic NAT implementation where you can configure static
+and dynamic NAT rules. It supports both source and destination NAT. While the
+configuration may look a bit unusual compared to traditional NAT
+implementations, it provides flexibility in network configurations.
+
+## CGNAT
+
+CGNAT is a special type of NAT44, which is highly useful when you have
+multiple local customers and a limited number of public IP addresses. It
+shares the public IP address space fairly between customers by using a
+combination of IP address and port number to distinguish between them.
+
+ISPs often use this NAT type to provide internet access to customers.
+
+It supports only source NAT.
+
+CGNAT also supports exclude rules (identity mappings) to bypass translation
+for selected local addresses or protocol/port tuples.
diff --git a/docs/vpp/configuration/nat/md-nat44.md b/docs/vpp/configuration/nat/md-nat44.md
new file mode 100644
index 00000000..a0805ed3
--- /dev/null
+++ b/docs/vpp/configuration/nat/md-nat44.md
@@ -0,0 +1,653 @@
+---
+lastproofread: '2026-03-05'
+---
+
+(vpp-config-nat-nat44)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP NAT44 Configuration
+NAT44 has two main use cases:
+- **Source NAT (SNAT)**: Enabling internet access for hosts in private
+  networks using dynamic or static address translation.
+- **Destination NAT (DNAT)**: Providing external access to internal services
+  through static port forwarding rules.
+
+VyOS supports both dynamic translation using address pools and static
+mappings for predictable address translation requirements.
+
+Configuring NAT44 involves a few steps:
+1. Define the inside and outside interfaces.
+2. Create NAT rules for SNAT or DNAT.
+
+## Dynamic and Static Operations
+NAT44 configuration can be done in one of two ways or in both ways
+simultaneously:
+1. Dynamically performing NAT using a pool of public IP addresses.
+2. Statically mapping private IP addresses to public IP addresses.
+
+To configure dynamic NAT, you need to define a pool of public IP
+addresses that will be used for translation. This offers an easy way to
+provide internet access to internal users.
+
+Static rules are suitable for scenarios where you need consistent and
+predictable mappings between private and public IP addresses. They are also
+the only way to configure DNAT.
+
+### NAT Rule Processing and Traffic Flow
+This section explains how different combinations of NAT rules affect
+traffic handling on a router. There are three possible combinations of NAT
+rule configurations:
+1. **Dynamic NAT Only**
+   - **All** traffic received on the "in" interface is processed by
+     dynamic NAT rules without exceptions.
+2. **Dynamic + Static NAT**
+   - **All** traffic received on the "in" interface is first matched
+     against static NAT rules.
+   - If no match is found, it is then processed against dynamic NAT rules.
+3. **Static NAT Only**
+   - **All** traffic on the "in" interface is checked against static NAT
+     rules.
+   - If no match is found, the traffic is routed **without NAT**.
+
+:::{important}
+- If **dynamic NAT rules** are present, **all** traffic received on
+  "in" interfaces is subject to NAT processing.
+- If **only static NAT rules** are configured, traffic that does not
+  match any static rule is routed unchanged.
+:::
+
+## Interfaces Configuration
+The first step in configuring NAT44 is defining which interfaces handle
+inside (private) and outside (public) traffic. VyOS uses these interface
+designations to determine the direction of translation.
+
+### Inside Interfaces
+Inside interfaces connect to private networks where hosts need source NAT
+to access external networks.
+```{cfgcmd} set vpp nat nat44 interface inside \<inside-interface\>
+```
+Traffic flowing **from** inside interfaces gets source NAT applied,
+translating private source addresses to public addresses from the
+translation pool.
+
+### Outside Interfaces
+Outside interfaces connect to public networks where external hosts may
+need to access internal services.
+```{cfgcmd} set vpp nat nat44 interface outside \<outside-interface\>
+```
+Traffic flowing **to** outside interfaces can trigger destination NAT
+based on static rules, allowing external access to internal services.
+
+### Interface Roles and Traffic Flow
+
+:::{note}
+While VyOS uses "inside" and "outside" as established conventions,
+the technical definitions are:
+- **Inside interface**: Interface where traffic originates that needs
+  source NAT (SNAT)
+- **Outside interface**: Interface where traffic originates that needs
+  destination NAT (DNAT)
+
+In complex network topologies, the same physical interface can be
+configured as both inside and outside to handle bidirectional NAT
+scenarios.
+:::
+**Traffic Processing:**
+1. **Inside → Outside** (SNAT): Private hosts accessing external networks
+2. **Outside → Inside** (DNAT): External hosts accessing internal services
+   via static rules
+3. **Dynamic NAT**: Created automatically for inside→outside traffic
+4. **Static NAT**: Requires explicit configuration for outside→inside
+   traffic
+
+### Multiple Interface Support
+You can configure multiple interfaces as inside or outside to support
+complex network topologies:
+```none
+# Multiple inside interfaces (different private networks)
+set vpp nat nat44 interface inside eth0
+set vpp nat nat44 interface inside eth2
+
+# Multiple outside interfaces (redundancy or load balancing)  
+set vpp nat nat44 interface outside eth1
+set vpp nat nat44 interface outside eth3
+```
+## Address Pool Configuration
+Address pools define ranges of IP addresses that can be used for NAT
+translations. VyOS NAT44 supports two types of address pools, each serving
+different purposes.
+
+### Translation Pools
+Translation pools are used for dynamic source NAT (SNAT). They provide a
+range of public IP addresses that can be dynamically assigned to private
+hosts when they access external networks.
+```{cfgcmd} set vpp nat nat44 address-pool translation address \<ip-address | ip-address-range\>
+```
+
+```{cfgcmd} set vpp nat nat44 address-pool translation interface \<interface-name\>
+```
+**Examples:**
+```none
+# Single address pool
+set vpp nat nat44 address-pool translation address 203.0.113.10
+
+# Address range pool  
+set vpp nat nat44 address-pool translation address 203.0.113.10-203.0.113.20
+
+# Interface-based pool (use a first IP assigned to the interface)
+set vpp nat nat44 address-pool translation interface eth1
+```
+### Twice-NAT Pools
+Twice-NAT pools are used when performing both source and destination NAT on
+the same traffic flow. This is particularly useful in scenarios where you
+need to:
+- Translate both source and destination addresses
+- Provide access between networks with overlapping IP ranges
+- Implement advanced NAT scenarios like self-twice-nat
+```{cfgcmd} set vpp nat nat44 address-pool twice-nat address \<ip-address | ip-address-range\>
+```
+
+```{cfgcmd} set vpp nat nat44 address-pool twice-nat interface \<interface-name\>
+```
+**Examples:**
+```none
+# Twice-NAT pool for advanced scenarios
+set vpp nat nat44 address-pool twice-nat address 192.168.100.1-192.168.100.10
+
+# Interface-based twice-nat pool
+set vpp nat nat44 address-pool twice-nat interface eth2
+```
+### Pool Requirements
+
+:::{important}
+- For dynamic NAT to work, you must configure at least one
+  **translation** pool.
+- For static rules with twice-nat options, you must configure a
+  **twice-nat** pool.
+- Interface-based pools automatically include main (first) IP address
+  assigned to the specified interface.
+:::
+
+### Pool Selection Priority
+When multiple pools are configured, VyOS uses the following selection
+priority:
+1. **Static mappings**: Always use the specific external address defined in
+   the rule.
+2. **Dynamic NAT**: Use available addresses from translation pools in the
+   order they were configured.
+3. **Twice-NAT**: Use addresses from twice-nat pools for secondary
+   translation.
+
+:::{note}
+As soon as you have configured interfaces and pool, the NAT44 is
+operational.
+:::
+
+## Static Rules Configuration
+Static NAT rules provide predictable and consistent mappings between private
+and public IP addresses. They are essential for:
+- **Destination NAT (DNAT)**: Allowing external hosts to access services in
+  the private network.
+- **Server publishing**: Making internal services available from the
+  Internet.
+- **Consistent mappings**: Ensuring the same private IP always maps to the
+  same public IP.
+
+Unlike dynamic NAT that uses a pool of addresses, static rules create
+one-to-one mappings that persist until explicitly removed.
+
+### Basic Static Rule Configuration
+To create a static NAT rule, you need to define the local (internal) and
+external (public) address mappings:
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> local address \<internal-ip\>
+```
+
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> external address \<external-ip\>
+```
+Where:
+- `<rule-number>` is a unique identifier for the rule
+- `<internal-ip>` is the private IP address in your local network
+- `<external-ip>` is the public IP address that external hosts will use
+
+This basic configuration creates a static one-to-one mapping. Traffic from
+outside to the external IP will be translated to the internal IP, and vice
+versa.
+
+### Port-based Static Rules
+For more granular control, you can create port-specific static rules. This
+is useful when you want to publish specific services:
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> local address \<internal-ip\>
+```
+
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> local port \<internal-port\>
+```
+
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> external address \<external-ip\>
+```
+
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> external port \<external-port\>
+```
+
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> protocol \<protocol\>
+```
+Where:
+- `<internal-port>` and `<external-port>` are the port numbers used by
+  the connection.
+- `<protocol>` specifies the protocol (tcp, udp, icmp).
+
+:::{important}
+If you do not specify ports and protocol, the rule will apply to *all*
+traffic between the specified internal and external addresses.
+
+Rules must contain either both ports and protocol, or neither.
+:::
+
+### Advanced Static Rule Options
+VyOS NAT44 supports several advanced options for static rules:
+
+#### Twice-NAT
+Twice-NAT performs both source and destination NAT. When an external host
+accesses an internal service, the source IP of such a connection is
+translated to an address from the twice-NAT address pool.
+
+This is practical in scenarios where internal services cannot connect to
+public networks, so they see such traffic as internal.
+
+The twice-NAT option can be enabled with the following command:
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options twice-nat
+```
+#### Self Twice-NAT
+Self Twice-NAT is used when a local host needs to access itself via the
+external address:
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options self-twice-nat
+```
+This option rewrites source IP addresses on packets sent only from a local
+address to an external address configured in a rule.
+
+:::{important}
+- Using `self-twice-nat` option requires you to set the interface
+  connected to the local network as both inside and outside, because
+  both source and destination NAT need to be applied.
+- External IP address used in static rules must belong to one of the
+  configured translation pools.
+:::
+
+#### Out-to-In Only
+Restricts the rule to only apply to traffic from outside to inside
+interfaces:
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options out-to-in-only
+```
+This prevents the creation of sessions from the inside interface, making it
+a purely DNAT rule.
+
+#### Force Twice-NAT Address
+When using twice-nat, you can force the use of a specific IP address from
+the twice-nat address pool:
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options twice-nat-address \<ip-address\>
+```
+#### Rule Description
+To document your rules, you can add a description:
+```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> description \<description\>
+```
+### Static Rules Configuration Examples
+**Full one-to-one NAT mapping:**
+```none
+set vpp nat nat44 static rule 100 local address 192.168.1.10
+set vpp nat nat44 static rule 100 external address 203.0.113.10
+set vpp nat nat44 static rule 100 description "One-to-one mapping"
+```
+**Port-specific SSH access:**
+```none
+set vpp nat nat44 static rule 200 local address 192.168.1.20
+set vpp nat nat44 static rule 200 local port 22
+set vpp nat nat44 static rule 200 external address 203.0.113.10
+set vpp nat nat44 static rule 200 external port 2222
+set vpp nat nat44 static rule 200 protocol tcp
+set vpp nat nat44 static rule 200 description "SSH access to server"
+```
+**Twice-NAT for local service access:**
+```none
+set vpp nat nat44 static rule 300 local address 192.168.1.30
+set vpp nat nat44 static rule 300 local port 80
+set vpp nat nat44 static rule 300 external address 203.0.113.10
+set vpp nat nat44 static rule 300 external port 80
+set vpp nat nat44 static rule 300 protocol tcp
+set vpp nat nat44 static rule 300 options twice-nat
+set vpp nat nat44 static rule 300 description "Web service with twice-nat"
+```
+:::{note}
+When using twice-nat or self-twice-nat options, ensure you have
+configured a twice-nat address pool using:
+```none
+set vpp nat nat44 address-pool twice-nat address <twice-nat-ip-range>
+```
+:::
+
+## Exclude Rules Configuration
+Exclude rules allow you to prevent specific traffic from undergoing NAT
+translation. This is particularly useful for:
+- **Router management**: Allowing SSH access to the router itself from
+  external networks.
+- **Service bypass**: Excluding specific services from NAT processing
+- **Traffic forwarding**: Allowing forwarded traffic to bypass NAT with 1-to-1
+  mapping.
+
+Exclude rules take precedence over both dynamic and static NAT rules,
+ensuring that matching traffic bypasses NAT processing. For forwarded
+traffic, exclude rules create invisible 1-to-1 mappings that allow packets
+to pass through without NAT modifications.
+
+### Basic Exclude Rule Configuration
+To create an exclude rule, you need to specify the traffic characteristics
+that should bypass NAT. You can configure exclude rules in two ways:
+
+**Option 1: Using local address**
+```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-address \<internal-ip\>
+```
+**Option 2: Using external interface**
+```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> external-interface \<interface-name\>
+```
+Where:
+- `<rule-number>` is a unique identifier for the exclude rule.
+- `<internal-ip>` is the local IP address that should be excluded from
+  : NAT.
+- `<interface-name>` is the external interface where the traffic
+  : originates.
+
+:::{important}
+You must use either `local-address` OR `external-interface` in an
+exclude rule, but not both simultaneously. These options are mutually
+exclusive.
+:::
+
+### Port-specific Exclude Rules
+For more granular control, you can exclude only specific ports and protocols.
+You can combine port and protocol specifications with either `local-address` or
+`external-interface`:
+
+**With local address:**
+```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-address \<internal-ip\>
+```
+
+```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-port \<port-number\>
+```
+
+```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> protocol \<protocol\>
+```
+**With external interface:**
+```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> external-interface \<interface-name\>
+```
+
+```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-port \<port-number\>
+```
+
+```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> protocol \<protocol\>
+```
+Where:
+- `<port-number>` is the specific port to exclude (1-65535)
+- `<protocol>` can be `tcp`, `udp`, `icmp`, or `all` (default)
+
+### Rule Documentation
+Add descriptions to your exclude rules for better management:
+```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> description \<description\>
+```
+### Exclude Rules Configuration Examples
+**Exclude SSH access to router:**
+```none
+# Allow external SSH access to router without NAT
+set vpp nat nat44 exclude rule 10 local-address 192.168.1.1
+set vpp nat nat44 exclude rule 10 local-port 22
+set vpp nat nat44 exclude rule 10 protocol tcp
+set vpp nat nat44 exclude rule 10 description "SSH access to router"
+```
+**Exclude SNMP monitoring:**
+```none
+# Allow SNMP monitoring without NAT translation
+set vpp nat nat44 exclude rule 20 local-port 161
+set vpp nat nat44 exclude rule 20 protocol udp
+set vpp nat nat44 exclude rule 20 external-interface eth1
+set vpp nat nat44 exclude rule 20 description "SNMP monitoring"
+```
+**Exclude all traffic to router management interface:**
+```none
+# Exclude all traffic to router's management IP
+set vpp nat nat44 exclude rule 30 local-address 192.168.100.1
+set vpp nat nat44 exclude rule 30 description "Management interface bypass"
+```
+**Exclude all traffic from external interface:**
+```none
+# Exclude all traffic from external interface (alternative approach)
+set vpp nat nat44 exclude rule 31 external-interface eth1
+set vpp nat nat44 exclude rule 31 description "External interface bypass"
+```
+**Exclude forwarded traffic for specific service:**
+```none
+# Allow external access to internal server without NAT translation
+set vpp nat nat44 exclude rule 40 local-address 192.168.1.50
+set vpp nat nat44 exclude rule 40 local-port 8080
+set vpp nat nat44 exclude rule 40 protocol tcp
+set vpp nat nat44 exclude rule 40 description "Direct access to internal service"
+```
+### Common Use Cases
+**Router Administration:**
+
+Exclude rules are essential when you need to manage the router from external
+networks. Without exclude rules, NAT would attempt to translate the router's
+own traffic, potentially breaking management connections.
+
+**Service Monitoring:**
+
+Network monitoring systems often need direct access to router services.
+Exclude rules ensure that monitoring traffic bypasses NAT translation.
+
+**Routing Protocols:**
+
+Some routing protocols or network services may require direct communication
+without NAT interference.
+
+**Traffic Forwarding:**
+
+Exclude rules also work for forwarded traffic between networks. Without
+exclude rules, traffic from external to local networks must either match a
+static rule or be dropped. With exclude rules, traffic can bypass NAT
+processing with invisible 1-to-1 mappings.
+
+:::{important}
+Exclude rules affect both traffic destined for the router itself and
+forwarded traffic flowing through the router. For forwarded traffic, exclude
+rules create transparent 1-to-1 mappings that allow packets to pass without
+NAT modifications, while from the outside perspective, the traffic appears to
+bypass NAT entirely.
+:::
+
+## Advanced NAT44 Settings
+VyOS provides additional NAT44 settings for fine-tuning performance and
+behavior.
+
+### Session Timeouts
+NAT44 maintains translation sessions with configurable timeout values for
+different protocols:
+```{cfgcmd} set vpp nat nat44 timeout icmp \<seconds\>
+
+Set the timeout for ICMP sessions (Default: 60 seconds).
+```
+
+```{cfgcmd} set vpp nat nat44 timeout tcp-established \<seconds\>
+
+Set the timeout for established TCP connections (Default: 7440 seconds
+or 2 hours 4 minutes).
+```
+
+```{cfgcmd} set vpp nat nat44 timeout tcp-transitory \<seconds\>
+
+Set the timeout for transitory TCP connections (setup/teardown) (Default:
+240 seconds or 4 minutes).
+```
+
+```{cfgcmd} set vpp nat nat44 timeout udp \<seconds\>
+
+Set the timeout for UDP sessions (Default: 300 seconds or 5 minutes).
+```
+**Example:**
+```none
+# Customize timeouts for high-traffic environment
+set vpp nat nat44 timeout tcp-established 3600
+set vpp nat nat44 timeout udp 600
+set vpp nat nat44 timeout icmp 30
+```
+### Session Limits
+Control the maximum number of concurrent NAT sessions:
+```{cfgcmd} set vpp nat nat44 session-limit \<number\>
+
+Set the maximum number of NAT sessions per worker thread (Default:
+64512).
+```
+This setting helps prevent memory exhaustion and ensures predictable
+performance under high load.
+
+**Example:**
+```none
+# Increase session limit for high-capacity deployment
+set vpp nat nat44 session-limit 100000
+```
+## Complete Configuration Example
+Here's a complete example showing how to configure VyOS NAT44 for a typical
+network setup:
+
+**Network Topology:**
+```none
+Internet (203.0.113.0/24)
+        |
+┌───────────────────┐
+│   eth1 (outside)  │ 203.0.113.1/24
+│     VyOS Router   │
+│   eth0 (inside)   │ 192.168.1.1/24  
+└───────────────────┘
+        |
+Internal Network (192.168.1.0/24)
+├── 192.168.1.10 (Web Server)
+├── 192.168.1.20 (SSH Server)  
+└── 192.168.1.30 (API Service)
+```
+**Configuration:**
+```none
+# Configure interfaces
+set vpp nat nat44 interface inside eth0
+set vpp nat nat44 interface outside eth1
+
+# Configure address pools
+set vpp nat nat44 address-pool translation address 203.0.113.10-203.0.113.50
+set vpp nat nat44 address-pool twice-nat address 203.0.113.100-203.0.113.110
+
+# Exclude rules for router management
+set vpp nat nat44 exclude rule 10 local-address 203.0.113.1
+set vpp nat nat44 exclude rule 10 local-port 22
+set vpp nat nat44 exclude rule 10 protocol tcp
+set vpp nat nat44 exclude rule 10 description "SSH access to router"
+
+set vpp nat nat44 exclude rule 11 local-address 203.0.113.1
+set vpp nat nat44 exclude rule 11 local-port 443
+set vpp nat nat44 exclude rule 11 protocol tcp
+set vpp nat nat44 exclude rule 11 description "HTTPS access to router web interface"
+
+# Static rule for web server (HTTP)
+set vpp nat nat44 static rule 100 local address 192.168.1.10
+set vpp nat nat44 static rule 100 local port 80
+set vpp nat nat44 static rule 100 external address 203.0.113.10
+set vpp nat nat44 static rule 100 external port 80
+set vpp nat nat44 static rule 100 protocol tcp
+set vpp nat nat44 static rule 100 description "Public web server"
+
+# Static rule for web server (HTTPS)
+set vpp nat nat44 static rule 101 local address 192.168.1.10
+set vpp nat nat44 static rule 101 local port 443
+set vpp nat nat44 static rule 101 external address 203.0.113.10
+set vpp nat nat44 static rule 101 external port 443
+set vpp nat nat44 static rule 101 protocol tcp
+set vpp nat nat44 static rule 101 description "Public web server HTTPS"
+
+# Static rule for SSH server with custom port
+set vpp nat nat44 static rule 200 local address 192.168.1.20
+set vpp nat nat44 static rule 200 local port 22
+set vpp nat nat44 static rule 200 external address 203.0.113.11
+set vpp nat nat44 static rule 200 external port 2222
+set vpp nat nat44 static rule 200 protocol tcp
+set vpp nat nat44 static rule 200 description "SSH access"
+
+# Static rule for API service (out-to-in only for security)
+set vpp nat nat44 static rule 300 local address 192.168.1.30
+set vpp nat nat44 static rule 300 local port 8080
+set vpp nat nat44 static rule 300 external address 203.0.113.12
+set vpp nat nat44 static rule 300 external port 8080
+set vpp nat nat44 static rule 300 protocol tcp
+set vpp nat nat44 static rule 300 options out-to-in-only
+set vpp nat nat44 static rule 300 description "API service (No Internet access for it)"
+```
+## Best Practices and Troubleshooting
+
+### Recommendations
+- **Use exclude rules** for router management services like SSH
+- **Use out-to-in-only** for services that do not need access to external
+  : networks.
+- **Limit port ranges** in static rules to only necessary ports.
+- **Document all rules** using descriptions for easier management.
+- **Use non-standard ports** for publishing SSH and other administrative
+  : services.
+- **Configure appropriate pool sizes** based on expected concurrent
+  : connections in your network.
+
+### Common Configuration Issues
+**Static rules not working:**
+
+1. Verify that the external IP address is included in an address pool
+2. Check that interfaces are correctly configured as inside or outside
+3. Ensure firewall rules allow the traffic
+
+**Twice-NAT not functioning:**
+
+1. Confirm twice-nat pool is configured
+2. Verify static rules have the correct twice-nat option
+3. Check that both translation and twice-nat pools are properly defined
+
+**Router management access issues:**
+
+1. Verify exclude rules are configured for management services
+2. Check that local-address matches the router's interface IP
+3. Ensure external-interface is correctly specified
+
+**Forwarded traffic from external networks not bypassing NAT:**
+
+1. Verify exclude rules are configured for the specific traffic flow
+2. Check that local-address matches the destination IP in the internal
+   network
+3. Ensure protocol and port specifications match the traffic requirements
+
+## Operational Commands
+Monitor NAT44 status and active connections using VyOS operational
+commands:
+```{opcmd} show vpp nat nat44 addresses
+
+Display configured NAT44 address pools.
+```
+
+```{opcmd} show vpp nat nat44 interfaces
+
+Show which interfaces are configured as inside or outside for NAT44.
+```
+
+```{opcmd} show vpp nat nat44 sessions
+
+Display active NAT44 translation sessions.
+```
+
+```{opcmd} show vpp nat nat44 static
+
+Show all configured static NAT mappings.
+```
+
+```{opcmd} show vpp nat nat44 summary
+
+Display a summary of NAT44 and statistics.
+```
\ No newline at end of file