Merge pull request #1679 from zdc/vpp-current

VPP: Add comprehensive VPP documentation
2025-10-26 01:31:44 +02:00 · 2025-09-04 21:32:29 +02:00 · 2025-09-04 19:02:26 +03:00
34 changed files with 3709 additions and 0 deletions
--- a/docs/_static/images/vpp/vyos_vpp_integration.svg
+++ b/docs/_static/images/vpp/vyos_vpp_integration.svg
--- a/docs/index.rst
+++ b/docs/index.rst
@ -79,6 +79,7 @@ VyOS User Guide
   automation/index
   troubleshooting/index
   configexamples/index
+   vpp/index


 .. toctree::
--- a/docs/vpp/configuration/acl.rst
+++ b/docs/vpp/configuration/acl.rst
@ -0,0 +1,633 @@
+: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)
+* **MACIP 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**: MACIP 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:
+
+.. code-block:: none
+
+   set vpp acl ip tag-name <tag-name>
+   set vpp acl ip tag-name <tag-name> description '<description>'
+
+Example:
+
+.. code-block:: 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:
+
+.. code-block:: 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:
+
+.. code-block:: 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:
+
+.. code-block:: 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:
+
+.. code-block:: none
+
+   # Match packets with specific flags set
+   set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags ack
+   set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags fin
+   set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags psh
+   set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags rst
+   set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags syn
+   set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags urg
+
+   # Match packets without specific flags set
+   set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags not ack
+   set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags not syn
+
+IP ACL Configuration Examples
+-----------------------------
+
+Example 1: Basic Web Server ACL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: 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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: 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
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: 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:
+
+.. code-block:: 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:
+
+.. code-block:: 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**: MACIP 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 MACIP ACL Tags
+-----------------------
+
+MACIP ACL tags are created under the ``vpp acl macip`` configuration node:
+
+.. code-block:: none
+
+   set vpp acl macip tag-name <tag-name>
+   set vpp acl macip tag-name <tag-name> description '<description>'
+
+Example:
+
+.. code-block:: none
+
+   set vpp acl macip tag-name 'MAC-FILTER'
+   set vpp acl macip tag-name 'MAC-FILTER' description 'Layer 2 MAC address filtering'
+
+Adding Rules to MACIP ACL Tags
+------------------------------
+
+Rules are added to MACIP ACL tags with specific rule numbers:
+
+.. code-block:: none
+
+   set vpp acl macip tag-name <tag-name> rule <rule-number>
+
+Basic MAC ACL Rule Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each rule requires an action and matching criteria:
+
+.. code-block:: none
+
+   set vpp acl macip tag-name <tag-name> rule <rule-number> action <permit|deny>
+   set vpp acl macip tag-name <tag-name> rule <rule-number> description '<description>'
+
+**Actions:**
+
+- ``permit`` - Allow matching traffic
+- ``deny`` - Block matching traffic
+
+Note: MACIP ACLs do not support the ``permit-reflect`` action available in IP ACLs.
+
+MAC Address Matching
+^^^^^^^^^^^^^^^^^^^^
+
+Configure MAC address matching criteria:
+
+.. code-block:: none
+
+   set vpp acl macip tag-name <tag-name> rule <rule-number> mac-address <mac-address>
+   set vpp acl macip 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:
+
+.. code-block:: none
+
+   set vpp acl macip 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``
+
+MACIP ACL Configuration Examples
+--------------------------------
+
+Example 1: Device Whitelist
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Create MACIP ACL for device whitelisting
+   set vpp acl macip tag-name 'DEVICE-WHITELIST'
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' description 'Allow only approved devices'
+   
+   # Allow specific workstation
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 10 action permit
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 10 mac-address '00:1b:21:12:34:56'
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 10 prefix '192.168.1.100/32'
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 10 description 'Admin workstation'
+   
+   # Allow specific server
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 20 action permit
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 20 mac-address '00:1b:21:78:90:ab'
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 20 prefix '192.168.1.10/32'
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 20 description 'Web server'
+   
+   # Deny everything else
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 999 action deny
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 999 mac-address '00:00:00:00:00:00'
+   set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 999 mac-mask '00:00:00:00:00:00'
+
+Example 2: Vendor-Based Filtering
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Create MACIP ACL for vendor-based filtering
+   set vpp acl macip tag-name 'VENDOR-FILTER'
+   set vpp acl macip tag-name 'VENDOR-FILTER' description 'Filter by MAC vendor OUI'
+   
+   # Deny Realtek devices (OUI: 00:e0:4c)
+   set vpp acl macip tag-name 'VENDOR-FILTER' rule 10 action deny
+   set vpp acl macip tag-name 'VENDOR-FILTER' rule 10 mac-address '00:e0:4c:00:00:00'
+   set vpp acl macip tag-name 'VENDOR-FILTER' rule 10 mac-mask 'ff:ff:ff:00:00:00'
+   set vpp acl macip tag-name 'VENDOR-FILTER' rule 10 description 'Block Realtek devices'
+   
+   # Allow all other devices
+   set vpp acl macip tag-name 'VENDOR-FILTER' rule 100 action permit
+   set vpp acl macip tag-name 'VENDOR-FILTER' rule 100 mac-address '00:00:00:00:00:00'
+   set vpp acl macip tag-name 'VENDOR-FILTER' rule 100 mac-mask '00:00:00:00:00:00'
+   set vpp acl macip tag-name 'VENDOR-FILTER' rule 100 description 'Allow all other vendors'
+
+Example 3: Network Segmentation by MAC
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Create MACIP ACL for network segmentation
+   set vpp acl macip tag-name 'SEGMENT-FILTER'
+   set vpp acl macip tag-name 'SEGMENT-FILTER' description 'Segment networks by MAC/IP binding'
+   
+   # Allow management VLAN devices
+   set vpp acl macip tag-name 'SEGMENT-FILTER' rule 10 action permit
+   set vpp acl macip tag-name 'SEGMENT-FILTER' rule 10 mac-address '02:01:00:00:00:00'
+   set vpp acl macip tag-name 'SEGMENT-FILTER' rule 10 mac-mask 'ff:ff:00:00:00:00'
+   set vpp acl macip tag-name 'SEGMENT-FILTER' rule 10 prefix '10.1.0.0/16'
+   set vpp acl macip tag-name 'SEGMENT-FILTER' rule 10 description 'Management VLAN'
+   
+   # Allow user VLAN devices
+   set vpp acl macip tag-name 'SEGMENT-FILTER' rule 20 action permit
+   set vpp acl macip tag-name 'SEGMENT-FILTER' rule 20 mac-address '02:02:00:00:00:00'
+   set vpp acl macip tag-name 'SEGMENT-FILTER' rule 20 mac-mask 'ff:ff:00:00:00:00'
+   set vpp acl macip tag-name 'SEGMENT-FILTER' rule 20 prefix '10.2.0.0/16'
+   set vpp acl macip tag-name 'SEGMENT-FILTER' rule 20 description 'User VLAN'
+
+Applying MACIP ACL Tags to Interfaces
+-------------------------------------
+
+MACIP ACL tags can only be applied to the input direction of interfaces:
+
+.. code-block:: none
+
+   set vpp acl macip interface <interface> tag-name <tag-name>
+
+.. note::
+   **Syntax Difference**: Unlike IP ACLs, MACIP ACL interface application does not use the ``acl-tag <number>`` structure since only single MACIP ACLs can be applied.
+
+.. warning::
+   Unlike IP ACLs, MACIP ACLs do **not** support output direction filtering. There is no ``output`` option available for MACIP ACL interface application.
+
+Example:
+
+.. code-block:: none
+
+   # Apply MAC filtering to interface input
+   set vpp acl macip interface eth0 tag-name 'MAC-FILTER'
+   set vpp acl macip 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 MACIP ACLs for Layer 2/3 filtering, IP ACLs for Layer 3/4 filtering
+- **Consider direction limitations**: Remember that MACIP 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:
+
+.. code-block:: 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 MACIP):
+
+.. opcmd:: show vpp acl
+
+This command shows a summary of all configured ACL tags with their rules, displaying both IP ACLs and MACIP ACLs in a tabular format.
+
+Example output:
+
+.. code-block:: 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
+
+   show vpp acl ip interface
+
+Example output:
+
+.. code-block:: 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:
+
+.. code-block:: 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
+
+MACIP ACL Commands
+------------------
+
+View all MACIP ACLs:
+
+.. opcmd:: show vpp acl macip
+
+View MACIP ACL interface assignments:
+
+.. opcmd:: show vpp acl macip interface
+
+Example output:
+
+.. code-block:: none
+
+   Interface    ACL
+   -----------  -----
+   eth0         VENDOR-FILTER
+
+View specific MACIP ACL by tag name:
+
+.. opcmd:: show vpp acl macip tag-name <tag-name>
+
+Example:
+
+.. code-block:: none
+
+    vyos@vyos:~$ show vpp acl macip 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)
+
+**MACIP 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**: MACIP ACL tag applied to interface (input only)
--- a/docs/vpp/configuration/dataplane/buffers.rst
+++ b/docs/vpp/configuration/dataplane/buffers.rst
@ -0,0 +1,78 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_dataplane_buffers:
+
+.. include:: /_include/need_improvement.txt
+
+###################################
+VPP Dataplane Buffers Configuration
+###################################
+
+Buffers are essential for handling network packets efficiently, and proper configuration can enhance performance, reliability and is mandatory for VPP work.
+
+Buffers are used to temporarily store packets during processing, therefore their configuration should be in sync with NIC configuration, CPU threads, and overall system resources.
+
+Buffer Configuration Parameters
+===============================
+
+The following parameters can be configured for VPP buffers:
+
+buffers-per-numa
+^^^^^^^^^^^^^^^^
+
+Number of buffers allocated per NUMA node. This setting helps in optimizing memory access patterns for multi-CPU systems.
+Usually it needs to be tuned if:
+- there are a lot of interfaces in the system
+- there are a lot of queues in NICs
+- there are big descriptors size configured for NICs
+The value should be set responsibly, overprovisioning can lead to issues with NICs configured with XDP driver.
+
+.. cfgcmd:: set vpp settings buffers buffers-per-numa <value>
+
+The common approach for the calculation is to use the formula:
+
+.. code-block:: none
+
+    buffers-per-numa = (num-rx-queues * num-rx-desc) + (num-tx-queues * num-tx-desc)
+
+This should be done for each NIC, and then sum the results for all NICs in the system needs to be multiplied by 2.5 and the result will be the minimum value for `buffers-per-numa`.
+
+Try to avoid setting this value too low to avoid packet drops.
+
+data-size
+^^^^^^^^^
+
+This value sets how much payload data can be stored in a single buffer allocated by VPP.
+Making it larger can reduce buffer chains for big packets, while a smaller value can save memory for environments handling mostly small packets.
+
+.. cfgcmd:: set vpp settings buffers data-size <value>
+
+Optimal size depends on the typical packet size in your network. If you are not sure, use the value of biggest MTU in your network plus some overhead (e.g., 128 bytes).
+
+page-size
+^^^^^^^^^
+
+A memory pages type used for buffer allocation. Common values are 4K, 2M, or 1G.
+
+Use pages that are configured in system settings.
+
+.. cfgcmd:: set vpp settings buffers page-size <value>
+
+Potential Issues and Troubleshooting
+------------------------------------
+
+Improper buffer configuration can lead to various issues, including:
+
+- Increased latency and packet loss
+- Inefficient CPU utilization
+- Interfaces 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 any errors related to buffer allocation (often the message may contains error `-5`).
+- Tune available buffers by adjusting the `buffers-per-numa` and `data-size` parameters.
--- a/docs/vpp/configuration/dataplane/cpu.rst
+++ b/docs/vpp/configuration/dataplane/cpu.rst
@ -0,0 +1,68 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_dataplane_cpu:
+
+.. include:: /_include/need_improvement.txt
+
+###############################
+VPP Dataplane CPU Configuration
+###############################
+
+VPP can utilize multiple CPU cores to enhance packet processing performance. Proper CPU configuration is crucial for achieving optimal throughput and low latency.
+
+There are several parameters that can be configured to optimize CPU usage for VPP.
+
+CPU Configuration Parameters
+============================
+
+main-core
+^^^^^^^^^
+
+The main core is responsible for handling control plane operations and managing worker threads. It should be set to a core that is not heavily utilized by other processes. If not set, VPP will automatically select a core `1`.
+
+.. cfgcmd:: set vpp settings cpu main-core <core-number>
+
+corelist-workers
+^^^^^^^^^^^^^^^^
+
+This parameter specifies the list of CPU cores that will be used as worker threads for packet processing.
+
+.. cfgcmd:: set vpp settings cpu corelist-workers <core-list>
+
+The core list can be specified in various formats, such as a comma-separated list (e.g., 2,3,4) or a range (e.g., 2-4). It is advisable to select cores that are on the same NUMA node as the network interfaces to minimize latency.
+
+Automatic cores selection
+-------------------------
+
+There is a possibility to let VPP select CPU cores automatically. This can be done by configuring the following two parameters:
+
+skip-cores
+^^^^^^^^^^
+
+This parameter allows you to specify number of first CPU cores that should be excluded from being used for main or worker threads. The main thread will be assigned to the first available core after the skipped ones, and worker threads will be assigned to subsequent cores.
+
+.. cfgcmd:: set vpp settings cpu skip-cores <cores>
+
+Exclude cores that are reserved for other critical system processes to ensure that VPP does not interfere with their operation.
+
+workers
+^^^^^^^
+
+This parameter allows you to specify the number of worker threads that should be created. Each worker thread will be assigned to a separate CPU core after the skipped and main ones.
+
+.. cfgcmd:: set vpp settings cpu workers <number>
+
+The number of worker threads should be chosen based on the available CPU resources and the expected network load. A common approach is to set the number of workers to the number of available CPU cores minus the skipped and main cores.
+
+Potential Issues and Troubleshooting
+====================================
+
+Improper CPU configuration can lead to various issues, including:
+
+- Underperformance for both VPP (not enough cores were assigned) and kernel (too many cores were assigned to VPP)
+- Resource conflicts with other processes and services
+
+Indicators of such issues are:
+
+- VPP or kernel forwarding performance is lower than expected
+- Slower work of system components or services, including DNS, DHCP, dynamic routing, etc.
--- a/docs/vpp/configuration/dataplane/index.rst
+++ b/docs/vpp/configuration/dataplane/index.rst
@ -0,0 +1,30 @@
+:lastproofread: 2025-09-04
+
+.. _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::
+   :maxdepth: 1
+   :includehidden:
+
+   system
+   buffers
+   cpu
+   interface
+   ipsec
+   ipv6
+   l2learn
+   lcp
+   logging
+   memory
+   unix
+   
--- a/docs/vpp/configuration/dataplane/interface.rst
+++ b/docs/vpp/configuration/dataplane/interface.rst
@ -0,0 +1,85 @@
+:lastproofread: 2025-09-04
+
+.. _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 packets into the network.
+
+
+Interface Configuration Parameters
+==================================
+
+driver
+^^^^^^
+The driver parameter specifies the type of driver used for the network interface. VPP supports two types of drivers that can be used for this: DPDK and XDP. The choice of driver depends on the specific use case, hardware capabilities, and performance requirements. Some NICs may support only one of these drivers.
+
+.. cfgcmd:: set vpp settings interface <interface-name> driver <driver-type>
+
+The DPDK driver is generally preferred for high-performance scenarios, while the XDP driver may be suitable for NICs that do not support DPDK.
+
+.. _vpp_config_dataplane_interface_rx_mode:
+
+rx-mode
+^^^^^^^
+
+The rx-mode parameter defines how VPP handles incoming packets on the interface. 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 is suitable for low to moderate traffic loads and can help reduce CPU usage during idle periods. It is not recommended if low-latency processing is required. May not be supported by some NICs.
+- ``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 the time packets spend waiting to be processed. However, it can lead to higher CPU usage, especially during periods of low traffic, because the polling process is always active.
+- ``adaptive``: Adaptive mode combines the benefits of both interrupt and polling modes. VPP starts in interrupt mode and switches to polling mode when the traffic load increases.
+
+.. cfgcmd:: set vpp settings interface <interface-name> rx-mode <mode>
+
+The choice of rx-mode should be based on the expected traffic patterns and performance requirements of the network environment.
+
+dpdk-options
+^^^^^^^^^^^^
+
+The dpdk-options section allows for the configuration of various DPDK-specific settings for the interface.
+
+.. cfgcmd:: set vpp settings interface <interface-name> dpdk-options <option> <value>
+
+DPDK options you can configure are:
+
+- ``num-rx-queues``: Specifies the number of receive queues for the interface. More queues can improve performance on multi-core systems by allowing parallel processing of incoming packets. Each queue will be assigned to a separate CPU core.
+
+.. seealso:: :doc:`cpu`
+
+- ``num-tx-queues``: Specifies the number of transmit queues for the interface. Similar to receive queues, more transmit queues can enhance performance by enabling parallel processing of outgoing packets.
+- ``num-rx-desc``: Defines the size of each receive queue. Larger queue sizes can help accommodate bursts of incoming traffic, reducing the likelihood of packet drops during high traffic periods.
+- ``num-tx-desc``: Defines the size of each transmit queue. Larger sizes can help manage bursts of outgoing traffic more effectively.
+- ``promisc``: Enables or disables promiscuous mode on the interface. When promiscuous mode is enabled, the interface will receive all packets on the network, regardless of type and destination of the packets. Some NICs need this feature to be enabled to avoid filtering out packets (for example to pass VLAN tagged packets).
+
+xdp-options
+^^^^^^^^^^^
+
+The xdp-options section allows for the configuration of various XDP-specific settings for the interface.
+
+.. cfgcmd:: set vpp settings interface <interface-name> xdp-options <option> <value>
+
+XDP options you can configure are:
+
+- ``no-syscall-lock``: Disables the syscall lock for the XDP interface. This can improve performance by allowing multiple threads to access the interface concurrently.
+- ``num-rx-queues``: Specifies the number of receive queues for the XDP interface. More queues can improve performance on multi-core systems by allowing parallel processing of incoming packets. Each queue will be assigned to a separate CPU core.
+- ``promisc``: Enables or disables promiscuous mode on the interface. When promiscuous mode is enabled, the interface will receive all packets on the network, regardless of type and destination of the packets. Some NICs need this feature to be enabled to avoid filtering out packets (for example to pass VLAN tagged packets).
+- ``rx-queue-size``: Defines the size of each receive queue. Larger queue sizes can help accommodate bursts of incoming traffic, reducing the likelihood of packet drops during high traffic periods.
+- ``tx-queue-size``: Defines the size of each transmit queue. Larger sizes can help manage bursts of outgoing traffic more effectively.
+- ``zero-copy``: Enables zero-copy mode for the XDP interface. This mode allows packets to be processed without copying them between kernel and user space, reducing latency and CPU usage.
+
+Potential Issues and Troubleshooting
+====================================
+
+Improper interface configuration can lead to various issues, including:
+
+- Failure to initialize the interface
+- Poor performance due to suboptimal driver selection or driver settings
+
+Indicators of such issues are:
+
+- Failed commits after adding or modifying an interface settings
+- Low throughput or high latency on the interface
--- a/docs/vpp/configuration/dataplane/ipsec.rst
+++ b/docs/vpp/configuration/dataplane/ipsec.rst
@ -0,0 +1,56 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_dataplane_ipsec:
+
+.. include:: /_include/need_improvement.txt
+
+#######################
+VPP IPsec Configuration
+#######################
+
+VPP supports IPsec (Internet Protocol Security) offloading from kernel, allowing to speed-up cryptographic operations by leveraging VPP's high-performance packet processing capabilities.
+
+IPSec does not require any specific configuration on VPP side. If both source and destinations of the IPsec traffic are reachable via VPP interfaces, VPP will automatically offload the IPsec processing from kernel. IPSec tunnels are configured in the VPN configuration section, see :ref:`ipsec_general`.
+
+IPSec Configuration Parameters
+==============================
+
+interface-type
+^^^^^^^^^^^^^^
+
+When VPP is used for offloading IPsec, it creates a virtual interface of a specific type to connect to a peer. The type of the interface can be configured using the following command:
+
+.. cfgcmd:: set vpp settings ipsec interface-type <interface-type>
+
+The available interface types are:
+
+- ``ipsec``: This is the default interface type used for IPsec tunnels.
+- ``ipip``: This interface type encapsulates IPsec traffic within IP-in-IP packets.
+
+Select the interface type based on peers settings. In most cases, you need to use the ``ipsec`` type.
+
+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 ipsec netlink batch-delay-ms <milliseconds>
+
+This parameter specifies the delay in milliseconds between processing batch netlink messages.
+
+.. cfgcmd:: set vpp settings ipsec netlink batch-size <number>
+
+This parameter specifies the maximum number of netlink messages to process in a single batch.
+
+.. cfgcmd:: set vpp settings ipsec netlink rx-buffer-size <number>
+
+This parameter specifies the size of the receive buffer for netlink socket. If you expect to offload a lot of IPsec tunnels or get frequent and intensive rekeying, you may need to increase this value.
+
+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
--- a/docs/vpp/configuration/dataplane/ipv6.rst
+++ b/docs/vpp/configuration/dataplane/ipv6.rst
@ -0,0 +1,32 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_dataplane_ipv6:
+
+.. include:: /_include/need_improvement.txt
+
+######################
+VPP IPv6 Configuration
+######################
+
+VPP allows to configure resources allocated for IPv6 traffic processing independently from IPv4. This allows to ensure that in networks without IPv6 traffic, the resources are not wasted on IPv6. But if IPv6 traffic is present - especially big routing tables - you need to allocate more resources for IPv6 processing to make dataplane stable.
+
+There are two main resources that can be configured for IPv6 traffic processing:
+
+.. cfgcmd:: set vpp settings ipv6 hash-buckets <value>
+
+This parameter configures the number of hash buckets used for IPv6 routing table. If you have a big IPv6 routing table, you may need to increase this value to ensure that the routing table is efficient and lookups are fast.
+
+.. cfgcmd:: set vpp settings ipv6 heap-size <value>
+
+This parameter configures the size of the heap used for IPv6 forwarding table. If you have a big IPv6 routing table, you may need to increase this value to ensure that 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
+- Crashes or instability of the dataplane due to insufficient heap size if there are a lot of IPv6 routes
+- Overall instability of the dataplane 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.
--- a/docs/vpp/configuration/dataplane/l2learn.rst
+++ b/docs/vpp/configuration/dataplane/l2learn.rst
@ -0,0 +1,28 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_dataplane_l2learn:
+
+.. include:: /_include/need_improvement.txt
+
+#########################
+VPP L2LEARN Configuration
+#########################
+
+When VPP dataplane is connected to a L2 domain, it needs to learn MAC addresses of devices connected to the domain. And the amount of MAC addresses that can be learned is limited by default.
+
+The limit can be configured using the following command:
+
+.. cfgcmd:: set vpp settings l2learn limit <value>
+
+This parameter configures the maximum number of MAC addresses that can be learned in the L2 domain. If you have a large number of devices, you may need to increase this limit to ensure all MAC addresses can be learned.
+
+Potential Issues and Troubleshooting
+====================================
+
+Improper L2LEARN configuration can lead to various issues, including:
+
+- Inability to learn all MAC addresses in the L2 domain if the limit is set too low
+- Increased packet loss or latency for devices that are not learned
+- Overall instability of the dataplane when handling L2 traffic
+
+Consider increasing the L2LEARN limit if you experience issues with MAC address learning or if you have a large number of devices in the L2 domain.
--- a/docs/vpp/configuration/dataplane/lcp.rst
+++ b/docs/vpp/configuration/dataplane/lcp.rst
@ -0,0 +1,50 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_dataplane_lcp:
+
+.. include:: /_include/need_improvement.txt
+
+#####################
+VPP LCP Configuration
+#####################
+
+Linux Control Plane (LCP) is one of core components of VPP that allows to offload various control plane functions to the Linux kernel. LCP provides seamless integration with other components of VyOS, allowing usage of other system components, like DHCP client, routing daemons, etc. together with VPP dataplane.
+
+VPP integration in VyOS relies heavily on LCP, building the relationship where almost all control plane functions are handled by other daemons and services and VPP is used exclusively for high-performance packet forwarding. This also reduces VPP management processing load, improving overall performance and stability of the dataplane.
+
+LCP can be configured using the following command:
+
+VyOS contains unique integration between kernel and VPP routing tables. By default, all the routes, even if they are not directly connected to VPP interfaces, are imported from kernel routing table to VPP routing table, pointing to the kernel. This allows to forward traffic to any destination known to the kernel, even if VPP itself does not have a route to that destination.
+
+However, in some scenarios, this behavior may not be desired. For example, if you have a large number of routes in the kernel routing table that are not directly connected to VPP interfaces, and you do not need forwarding between such destinations and destinations reachable via VPP, you can disable this behavior. This can be done using the following command:
+
+.. _vpp_config_dataplane_lcp_ignore-kernel-routes:
+
+.. cfgcmd:: set vpp settings lcp 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.
+
+Other configuration section crucial for integration between VPP and Kernel is netlink settings. It allows to configure how VPP management listen to netlink events and how it processes them.
+
+.. cfgcmd:: set vpp settings lcp batch-delay-ms <value>
+
+This parameter specifies the delay in milliseconds between processing batch netlink messages. If you expect to get frequent and intensive netlink events, you may need to decrease this value to ensure that VPP processes netlink events in a timely manner.
+
+.. cfgcmd:: set vpp settings lcp batch-size <value>
+
+This parameter specifies the maximum number of netlink messages to process in a single batch. If you have a high volume of netlink events, increasing this value can improve throughput by allowing more messages to be processed at once. However, setting it too high may increase latency for individual messages.
+
+.. cfgcmd:: set vpp settings lcp rx-buffer-size <value>
+
+This parameter specifies the size of the receive buffer for netlink messages. Increasing this value can help accommodate bursts of netlink messages, but setting it too high may lead to increased memory usage.
+
+Potential Issues and Troubleshooting
+====================================
+
+Improper LCP configuration can lead to various issues, including:
+
+- Loss of connectivity to certain destinations if kernel routes are ignored
+- Delays in synchronization between kernel and VPP routing tables
+- Desynchronization between kernel and VPP routing tables if netlink settings are not optimal
+
+Consider adjusting LCP settings if you experience issues with routing or connectivity, especially in scenarios involving dynamic route changes or a large number of routes.
--- a/docs/vpp/configuration/dataplane/logging.rst
+++ b/docs/vpp/configuration/dataplane/logging.rst
@ -0,0 +1,42 @@
+:lastproofread: 2025-09-04
+
+.. _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 logs are stored in the ``/var/log/vpp.log`` file. Additionally daemon logs can be found in the system journal.
+
+Logging detalization can be configured via the next command:
+
+.. cfgcmd:: set vpp settings logging default-log-level <level>
+
+Where ``<level>`` can be one of the following:
+
+- ``emerg`` (Emergency) - System is unusable.
+- ``alert`` (Alert) - Immediate action required.
+- ``crit`` (Critical) - Critical conditions.
+- ``err`` (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.
+
+Potential Issues and Troubleshooting
+====================================
+
+Improper logging configuration can lead to various issues, including:
+
+- Excessive log file sizes if the logging level is set too high (e.g., ``debug``)
+- Missing critical information if the logging level is set too low (e.g., ``alert``)
+- Performance degradation due to excessive logging overhead
+
+Consider adjusting the logging level if you experience issues mentioned above.
--- a/docs/vpp/configuration/dataplane/memory.rst
+++ b/docs/vpp/configuration/dataplane/memory.rst
@ -0,0 +1,49 @@
+:lastproofread: 2025-09-04
+
+.. _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:
+
+.. cfgcmd:: set vpp settings memory default-hugepage-size <size>
+
+Sets the default hugepage size for VPP.
+
+VPP uses a main heap as a central memory pool for FIB data structures entries 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 memory main-heap-page-size <size>
+
+Sets the main heap page size for VPP. 
+
+.. cfgcmd:: set vpp settings memory main-heap-size <size>
+
+Sets the main heap size for VPP.
+
+
+Potential Issues and 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 populating (e.g., 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 - same amount of routes with a single next-hop and with multiple next-hops will consume different amounts of memory.
--- a/docs/vpp/configuration/dataplane/system.rst
+++ b/docs/vpp/configuration/dataplane/system.rst
@ -0,0 +1,54 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_system:
+
+.. include:: /_include/need_improvement.txt
+
+##########################
+VyOS Configuration for VPP
+##########################
+
+.. _vpp_config_hugepages:
+
+Hugepages
+=========
+VPP utilizes hugepages for efficient 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.
+
+Hugepages can be configured in VyOS using the following commands:
+
+.. warning::
+
+   Changes to hugepage settings require a system reboot to take effect.
+
+   Hugepages must be enabled before VPP configuration is applied.
+
+To enable hugepages:
+
+.. cfgcmd:: set system option kernel memory hugepage-size <size> hugepage-count '<count>'
+
+Enables hugepages with the specified size and count. The size can be either 2MB or 1GB, and the count specifies the number of hugepages to allocate.
+
+If your system has multiple NUMA nodes, the total amount of hugepages will be divided equally among them.
+
+Resources Limits
+================
+
+.. note::
+
+   By default, system will calculate and set the recommended values for resource limits. Avoid tuning these values if you are not sure what you are doing.
+
+During operations VPP utilizes a significant amount of system resources, especially memory. There are two main settings that may to be adjusted to ensure VPP runs smoothly:
+
+Maximum number of memory map areas a process may have:
+
+.. cfgcmd:: set system option resource-limits max-map-count <value>
+
+Maximum shared memory segment size:
+
+.. cfgcmd:: set system option resource-limits shmmax <value>
+
+Both settings are automatically calculated based on configured hugepages.
+
+Kernel Tuning
+=============
+
--- a/docs/vpp/configuration/dataplane/unix.rst
+++ b/docs/vpp/configuration/dataplane/unix.rst
@ -0,0 +1,36 @@
+:lastproofread: 2025-09-04
+
+.. _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 VM has burstable thresholds and CPU usage limits.
+
+To mitigate this, VPP provides a configurable polling delay that allows to reduce 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 unix 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.
+
+Potential Issues and 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.
--- a/docs/vpp/configuration/index.rst
+++ b/docs/vpp/configuration/index.rst
@ -0,0 +1,46 @@
+: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::
+   :maxdepth: 1
+   :includehidden:
+
+   dataplane/index
+   interfaces/index
+
+Features that can be enabled on VPP Dataplane:
+
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   acl
+   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.
--- a/docs/vpp/configuration/interfaces/bonding.rst
+++ b/docs/vpp/configuration/interfaces/bonding.rst
@ -0,0 +1,182 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_interfaces_bonding:
+
+.. include:: /_include/need_improvement.txt
+
+#########################
+VPP Bonding Configuration
+#########################
+
+VPP bonding interfaces provide link aggregation capabilities, 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 vpp interfaces bonding <bondN>
+
+   Create a bonding interface where ``<bondN>`` follows the naming convention bond0, bond1, etc.
+
+**Example:**
+
+.. code-block:: none
+
+   set vpp interfaces bonding bond0
+
+Interface Description
+^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces bonding <bondN> description <description>
+
+   Set a descriptive name for the bonding interface.
+
+**Example:**
+
+.. code-block:: none
+
+   set vpp interfaces bonding bond0 description "Primary uplink bond"
+
+Administrative Control
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces bonding <bondN> disable
+
+   Administratively disable the bonding interface. By default, interfaces are enabled.
+
+Member Interface Configuration
+------------------------------
+
+Adding Member Interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces bonding <bondN> member interface <interface-name>
+
+   Add physical interfaces as members of the bond. Multiple interfaces can be added to the same bond.
+
+**Example:**
+
+.. code-block:: none
+
+   set vpp interfaces bonding bond0 member interface eth0
+   set vpp interfaces bonding bond0 member interface eth1
+
+.. note::
+
+   Member interfaces should be of the same speed and duplex for optimal performance and already be attached to VPP.
+
+Bonding Modes
+-------------
+
+.. cfgcmd:: set vpp interfaces bonding <bondN> 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:**
+
+.. code-block:: none
+
+   # Use LACP (recommended for switch environments)
+   set vpp interfaces bonding bond0 mode 802.3ad
+   
+   # Use active-backup for simple failover
+   set vpp interfaces bonding bond0 mode active-backup
+
+Hash Policies
+-------------
+
+For load balancing modes, configure how traffic is distributed across member interfaces:
+
+.. cfgcmd:: set vpp interfaces bonding <bondN> 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:**
+
+.. code-block:: none
+
+   # Layer 2 hashing (default)
+   set vpp interfaces bonding bond0 hash-policy layer2
+   
+   # Layer 3+4 for better distribution with multiple flows
+   set vpp interfaces bonding bond0 hash-policy layer3+4
+
+MAC Address Configuration
+-------------------------
+
+.. cfgcmd:: set vpp interfaces bonding <bondN> mac <mac-address>
+
+   Set a specific MAC address for the bonding interface.
+
+**Example:**
+
+.. code-block:: none
+
+   set vpp interfaces bonding bond0 mac 00:11:22:33:44:55
+
+Kernel Interface Integration
+----------------------------
+
+.. cfgcmd:: set vpp interfaces bonding <bondN> kernel-interface <interface-name>
+
+   Create a kernel interface bound to the VPP bonding interface. This allows standard Linux networking tools and services to interact with the VPP bond.
+
+For detailed information about kernel interface integration, see :doc:`kernel`.
+
+**Example:**
+
+.. code-block:: none
+
+   set vpp interfaces bonding bond0 kernel-interface vpptap0
+
+.. important::
+
+   When using kernel interface binding, you can configure IP addresses and other network settings on the kernel interface.
+
+   A kernel-interface must be created beforehand.
+
+Complete Configuration Example
+------------------------------
+
+Here's a complete example configuring a bonding interface with LACP:
+
+.. code-block:: none
+
+   # Create bonding interface
+   set vpp interfaces bonding bond0
+   set vpp interfaces bonding bond0 description "Server uplink bond"
+   
+   # Configure bonding parameters
+   set vpp interfaces bonding bond0 mode 802.3ad
+   set vpp interfaces bonding bond0 hash-policy layer3+4
+   
+   # Add member interfaces
+   set vpp interfaces bonding bond0 member interface eth0
+   set vpp interfaces bonding bond0 member interface eth1
+   
+   # Create kernel interface for OS integration
+   set vpp interfaces bonding bond0 kernel-interface vpptap0
+   
+   # Configure IP on kernel interface
+   set vpp kernel-interfaces vpptap0 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 capabilities (speed, duplex, MTU)
--- a/docs/vpp/configuration/interfaces/bridge.rst
+++ b/docs/vpp/configuration/interfaces/bridge.rst
@ -0,0 +1,200 @@
+:lastproofread: 2025-09-04
+
+.. _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 vpp interfaces bridge <brN>
+
+   Create a bridge interface where ``<brN>`` follows the naming convention br1, br2, etc.
+
+.. note::
+
+   Bridge domain br0 is reserved by VPP and cannot be configured through VyOS. Start with br1 for your bridge configurations.
+
+**Example:**
+
+.. code-block:: none
+
+   set vpp interfaces bridge br1
+
+
+Interface Description
+^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces bridge <brN> description <description>
+
+   Set a descriptive name for the bridge interface.
+
+**Example:**
+
+.. code-block:: none
+
+   set vpp interfaces bridge br1 description "Main campus bridge"
+
+Administrative Control
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces bridge <brN> disable
+
+   Administratively disable the bridge interface. By default, bridge interfaces are enabled when created.
+
+Member Interface Configuration
+------------------------------
+
+Adding Member Interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces bridge <brN> member interface <interface-name>
+
+   Add an interface as a member of the bridge.
+
+**Examples:**
+
+.. code-block:: none
+
+   # Add physical interfaces
+   set vpp interfaces bridge br1 member interface eth0
+   set vpp interfaces bridge br1 member interface eth1
+   
+   # Add other VPP interfaces
+   set vpp interfaces bridge br1 member interface bond0
+   set vpp interfaces bridge br1 member interface gre1
+
+.. important::
+
+   Bridge members can include various interface types such as:
+   
+   * Physical Ethernet interfaces (eth0, eth1, etc.)
+   * :doc:`bonding` - VPP bonding interfaces (bond0, bond1, 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 vpp interfaces bridge <brN> member interface <loopback-interface> bvi
+
+   Designate a loopback interface as the Bridge Virtual Interface for the bridge domain.
+
+**Example:**
+
+.. code-block:: none
+
+   # Create a loopback interface first
+   set vpp interfaces loopback lo1
+   
+   # Add it to the bridge as BVI
+   set vpp interfaces bridge br1 member interface lo1 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
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Create bridge interface
+   set vpp interfaces bridge br1
+   set vpp interfaces bridge br1 description "Office network bridge"
+   
+   # Add member interfaces
+   set vpp interfaces bridge br1 member interface eth0
+   set vpp interfaces bridge br1 member interface eth1
+   set vpp interfaces bridge br1 member interface eth2
+
+Bridge with BVI
+^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Create bridge and loopback for BVI
+   set vpp interfaces bridge br2
+   set vpp interfaces bridge br2 description "Server segment with gateway"
+   set vpp interfaces loopback lo1
+   
+   # Configure bridge members
+   set vpp interfaces bridge br2 member interface eth3
+   set vpp interfaces bridge br2 member interface eth4
+   set vpp interfaces bridge br2 member interface lo1 bvi
+
+Multi-Technology Bridge
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Create bridge combining different interface types
+   set vpp interfaces bridge br3
+   set vpp interfaces bridge br3 description "Hybrid network bridge"
+   
+   # Add various interface types
+   set vpp interfaces bridge br3 member interface bond1
+   set vpp interfaces bridge br3 member interface gre1
+   set vpp interfaces bridge br3 member interface vxlan1
+   set vpp interfaces bridge br3 member interface lo2 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).
+
+For detailed information about kernel interface integration, see :doc:`kernel`.
+
+**Example Integration:**
+
+.. code-block:: none
+
+   # Create VPP bridge with member interfaces
+   set vpp interfaces bridge br1
+   set vpp interfaces bridge br1 member interface eth1
+   set vpp interfaces bridge br1 member interface eth2
+   
+   # Create loopback interface and configure as BVI
+   set vpp interfaces loopback lo1
+   set vpp interfaces bridge br1 member interface lo1 bvi
+   
+   # Bind kernel interface to the BVI loopback
+   set vpp interfaces loopback lo1 kernel-interface 'vpptun1'
+   set vpp kernel-interfaces vpptun1 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.
--- a/docs/vpp/configuration/interfaces/gre.rst
+++ b/docs/vpp/configuration/interfaces/gre.rst
@ -0,0 +1,157 @@
+:lastproofread: 2025-09-04
+
+.. _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 vpp interfaces gre <greN>
+
+   Create a GRE interface where ``<greN>`` follows the naming convention gre1, gre2, etc.
+
+.. cfgcmd:: set vpp interfaces gre <greN> remote <address>
+
+   Set the tunnel remote endpoint address. Supports both IPv4 and IPv6 addresses.
+
+.. cfgcmd:: set vpp interfaces gre <greN> source-address <address>
+
+   Set the tunnel source address. Must match an address configured on the local system.
+
+**Basic Example:**
+
+.. code-block:: none
+
+   set vpp interfaces gre gre1
+   set vpp interfaces gre gre1 remote 203.0.113.2
+   set vpp interfaces gre gre1 source-address 192.168.1.1
+
+Interface Configuration
+-----------------------
+
+Description and Administrative Control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces gre <greN> description <description>
+
+   Set a descriptive name for the GRE interface.
+
+.. cfgcmd:: set vpp interfaces gre <greN> disable
+
+   Administratively disable the GRE interface.
+
+Tunnel Mode
+^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces gre <greN> mode <mode>
+
+   Configure the GRE tunnel operating mode:
+
+   * ``point-to-point`` - Default mode for direct tunnel between two endpoints
+   * ``point-to-multipoint`` - Allows multiple remote endpoints
+
+Tunnel Type
+^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces gre <greN> 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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces gre <greN> kernel-interface <interface-name>
+
+   Bind a kernel interface to the GRE tunnel for management and application compatibility.
+
+For detailed information about kernel interface integration, see :doc:`kernel`.
+
+Configuration Examples
+----------------------
+
+Layer 3 GRE Tunnel
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # IPv4 GRE tunnel
+   set vpp interfaces gre gre1
+   set vpp interfaces gre gre1 description "Site-to-site tunnel"
+   set vpp interfaces gre gre1 remote 203.0.113.10
+   set vpp interfaces gre gre1 source-address 192.168.1.1
+   set vpp interfaces gre gre1 tunnel-type l3
+
+Layer 2 GRE Tunnel (TEB)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Transparent Ethernet Bridge
+   set vpp interfaces gre gre2
+   set vpp interfaces gre gre2 description "L2 extension tunnel"
+   set vpp interfaces gre gre2 remote 203.0.113.20
+   set vpp interfaces gre gre2 source-address 192.168.1.1
+   set vpp interfaces gre gre2 tunnel-type teb
+
+IPv6 GRE Tunnel
+^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # IPv6 endpoints
+   set vpp interfaces gre gre3
+   set vpp interfaces gre gre3 remote 2001:db8::2
+   set vpp interfaces gre gre3 source-address 2001:db8::1
+
+Point-to-Multipoint Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Hub configuration for multiple spokes
+   set vpp interfaces gre gre4
+   set vpp interfaces gre gre4 mode point-to-multipoint
+   set vpp interfaces gre gre4 remote 0.0.0.0
+   set vpp interfaces gre gre4 source-address 192.168.1.1
+
+.. note::
+
+   For point-to-multipoint mode, the remote address must be set to 0.0.0.0 to allow multiple remote endpoints.
+
+GRE with Kernel Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # GRE tunnel with management interface
+   set vpp interfaces gre gre5
+   set vpp interfaces gre gre5 remote 203.0.113.30
+   set vpp interfaces gre gre5 source-address 192.168.1.1
+   set vpp interfaces gre gre5 kernel-interface vpptun5
+   set vpp kernel-interfaces vpptun5 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.
+
+.. code-block:: none
+
+   # Add TEB GRE tunnel to bridge
+   set vpp interfaces bridge br1
+   set vpp interfaces bridge br1 member interface gre2
+   set vpp interfaces bridge br1 member interface eth1
--- a/docs/vpp/configuration/interfaces/index.rst
+++ b/docs/vpp/configuration/interfaces/index.rst
@ -0,0 +1,40 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_interfaces_index:
+
+.. include:: /_include/need_improvement.txt
+
+############################
+VPP Interfaces Configuration
+############################
+
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   bonding
+   bridge
+   gre
+   ipip
+   kernel
+   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
+^^^^^^^^^^^^^^^^^^^^^^^
+
+However, if needed, VyOS provides seamless integration between VPP and kernel networking. For detailed information about kernel interface integration, see :doc:`kernel`.
+
+This allows you to leverage the strengths of both approaches - create interfaces inside VPP, but still have them accessible from the Linux kernel and other services side.
--- a/docs/vpp/configuration/interfaces/ipip.rst
+++ b/docs/vpp/configuration/interfaces/ipip.rst
@ -0,0 +1,96 @@
+:lastproofread: 2025-09-04
+
+.. _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 vpp interfaces ipip <ipipN>
+
+   Create an IPIP interface where ``<ipipN>`` follows the naming convention ipip1, ipip2, etc.
+
+.. cfgcmd:: set vpp interfaces ipip <ipipN> remote <address>
+
+   Set the tunnel remote endpoint address. Supports both IPv4 and IPv6 addresses.
+
+.. cfgcmd:: set vpp interfaces ipip <ipipN> source-address <address>
+
+   Set the tunnel source address. Must match an address configured on the local system.
+
+**Basic Example:**
+
+.. code-block:: none
+
+   set vpp interfaces ipip ipip1
+   set vpp interfaces ipip ipip1 remote 203.0.113.2
+   set vpp interfaces ipip ipip1 source-address 192.168.1.1
+
+Interface Configuration
+-----------------------
+
+Description and Administrative Control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces ipip <ipipN> description <description>
+
+   Set a descriptive name for the IPIP interface.
+
+.. cfgcmd:: set vpp interfaces ipip <ipipN> disable
+
+   Administratively disable the IPIP interface.
+
+Kernel Interface Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces ipip <ipipN> kernel-interface <interface-name>
+
+   Bind a kernel interface to the IPIP tunnel for management and application compatibility.
+
+For detailed information about kernel interface integration, see :doc:`kernel`.
+
+Configuration Examples
+----------------------
+
+IPv4 IPIP Tunnel
+^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Basic IPv4 IPIP tunnel
+   set vpp interfaces ipip ipip1
+   set vpp interfaces ipip ipip1 description "Site-to-site IPIP tunnel"
+   set vpp interfaces ipip ipip1 remote 203.0.113.10
+   set vpp interfaces ipip ipip1 source-address 192.168.1.1
+
+IPv6 IPIP Tunnel
+^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # IPv6 endpoints
+   set vpp interfaces ipip ipip2
+   set vpp interfaces ipip ipip2 remote 2001:db8::2
+   set vpp interfaces ipip ipip2 source-address 2001:db8::1
+
+IPIP with Kernel Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # IPIP tunnel with management interface
+   set vpp interfaces ipip ipip3
+   set vpp interfaces ipip ipip3 remote 203.0.113.30
+   set vpp interfaces ipip ipip3 source-address 192.168.1.1
+   set vpp interfaces ipip ipip3 kernel-interface vpptun3
+   set vpp kernel-interfaces vpptun3 address 10.0.2.1/30
--- a/docs/vpp/configuration/interfaces/kernel.rst
+++ b/docs/vpp/configuration/interfaces/kernel.rst
@ -0,0 +1,258 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_interfaces_kernel:
+
+.. include:: /_include/need_improvement.txt
+
+###################################
+VPP Kernel Interfaces Configuration
+###################################
+
+VPP kernel interfaces provide a bridge between the high-performance VPP data plane and the Linux kernel networking stack. These interfaces appear as standard network interfaces in the kernel while being transparently connected to VPP interfaces, enabling seamless integration between VPP processing and kernel-based applications.
+
+**How Kernel Interfaces Work:**
+
+* Traffic sent to the kernel interface by any application or kernel is forwarded to the connected VPP interface
+* Traffic processed within VPP is sent to the kernel interface only if VPP cannot handle it (e.g., no matching route)
+* Standard Linux networking tools and daemons can interact with VPP interfaces
+
+**Use Cases:**
+
+* Integrating VPP interfaces with routing daemons (FRR, BIRD)
+* Providing management access to VPP-processed networks
+* Running standard network services on VPP interfaces
+
+Interface Types: TUN vs TAP
+---------------------------
+
+VPP kernel interfaces support two types of virtual network interfaces that differ in how they handle network traffic.
+
+**TAP Interfaces (vpptapN)**
+
+TAP interfaces operate at Layer 2 (Data Link Layer) and work with complete Ethernet frames. They process full Ethernet packets including MAC addresses and headers, making them suitable for scenarios where you need complete Layer 2 functionality. TAP interfaces can participate in bridging and switching operations, and they provide native support for VLAN tagging and sub-interfaces. This makes them ideal for Layer 2 connectivity, bridging setups, and VLAN segmentation.
+
+**TUN Interfaces (vpptunN)**
+
+TUN interfaces operate at Layer 3 (Network Layer) and handle raw IP packets without Ethernet headers. They are optimized for Layer 3 routing operations and have lower processing overhead due to their simpler packet structure. TUN interfaces are typically used for VPN tunnels, point-to-point links, and routing applications where Layer 2 functionality is not required.
+
+**Choosing the Right Interface Type**
+
+The choice between TUN and TAP depends on your specific networking requirements. Use TAP interfaces when you need Layer 2 functionality such as bridging, VLANs, or full Ethernet compatibility. Choose TUN interfaces when you only need Layer 3 functionality for routing or VPN scenarios. While TAP interfaces are more versatile, they have slightly higher overhead compared to TUN interfaces, which are more efficient for pure routing scenarios.
+
+.. note::
+
+   The interface type is determined by the naming convention: ``vpptapN`` creates TAP interfaces, while ``vpptunN`` creates TUN interfaces. Both support the same configuration commands but behave differently at the packet processing level.
+
+Basic Configuration
+-------------------
+
+Creating a Kernel Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp kernel-interfaces <interface-name>
+
+   Create a kernel interface. The interface name follows the convention ``vpptapN`` or ``vpptunN``.
+
+**Example:**
+
+.. code-block:: none
+
+   set vpp kernel-interfaces vpptap1
+
+Interface Description
+^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp kernel-interfaces <interface-name> description <description>
+
+   Set a descriptive name for the kernel interface.
+
+**Example:**
+
+.. code-block:: none
+
+   set vpp kernel-interfaces vpptap1 description "Management interface for VPP bond"
+
+Administrative Control
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp kernel-interfaces <interface-name> disable
+
+   Administratively disable the kernel interface. By default, interfaces are enabled.
+
+IP Address Configuration
+------------------------
+
+.. cfgcmd:: set vpp kernel-interfaces <interface-name> address <ip-address/prefix>
+
+   Configure IPv4 or IPv6 addresses on the kernel interface. Multiple addresses can be assigned.
+
+**Examples:**
+
+.. code-block:: none
+
+   # IPv4 address
+   set vpp kernel-interfaces vpptap1 address 192.168.1.10/24
+   
+   # IPv6 address
+   set vpp kernel-interfaces vpptap1 address 2001:db8::10/64
+   
+   # Multiple addresses
+   set vpp kernel-interfaces vpptap1 address 192.168.1.10/24
+   set vpp kernel-interfaces vpptap1 address 10.0.0.10/8
+
+MTU Configuration
+-----------------
+
+.. cfgcmd:: set vpp kernel-interfaces <interface-name> mtu <size>
+
+   Set the Maximum Transmission Unit (MTU) for the kernel interface. The MTU must be compatible with the connected VPP interface.
+
+**Example:**
+
+.. code-block:: none
+
+   set vpp kernel-interfaces vpptap1 mtu 9000
+
+.. note::
+
+   Ensure the MTU setting matches or is smaller than the MTU supported by the associated VPP interface to avoid issues.
+
+Receive Processing Mode
+-----------------------
+
+.. cfgcmd:: set vpp kernel-interfaces <interface-name> rx-mode <mode>
+
+   Configure how the interface processes received packets:
+
+   * **polling**: Constantly check for new data (highest performance, higher CPU usage)
+   * **interrupt**: Interrupt-driven processing (balanced performance and CPU usage)
+   * **adaptive**: Automatically switch between polling and interrupt based on traffic load
+
+**Examples:**
+
+.. code-block:: none
+
+   # High-performance mode (default)
+   set vpp kernel-interfaces vpptap1 rx-mode polling
+   
+   # Balanced mode
+   set vpp kernel-interfaces vpptap1 rx-mode interrupt
+   
+   # Adaptive mode
+   set vpp kernel-interfaces vpptap1 rx-mode adaptive
+
+VLAN Configuration
+------------------
+
+VPP kernel interfaces support VLAN (Virtual LAN) sub-interfaces for network segmentation.
+
+Creating VLAN Sub-interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp kernel-interfaces <interface-name> vif <vlan-id>
+
+   Create a VLAN sub-interface with the specified VLAN ID (0-4094).
+
+**Example:**
+
+.. code-block:: none
+
+   set vpp kernel-interfaces vpptap1 vif 100
+
+VLAN Sub-interface Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+VLAN sub-interfaces support the same configuration options as the parent interface:
+
+.. cfgcmd:: set vpp kernel-interfaces <interface-name> vif <vlan-id> address <ip-address/prefix>
+
+.. cfgcmd:: set vpp kernel-interfaces <interface-name> vif <vlan-id> description <description>
+
+.. cfgcmd:: set vpp kernel-interfaces <interface-name> vif <vlan-id> disable
+
+.. cfgcmd:: set vpp kernel-interfaces <interface-name> vif <vlan-id> mtu <size>
+
+**Examples:**
+
+.. code-block:: none
+
+   # Configure VLAN 100
+   set vpp kernel-interfaces vpptap1 vif 100 address 192.168.100.1/24
+   set vpp kernel-interfaces vpptap1 vif 100 description "Management VLAN"
+   set vpp kernel-interfaces vpptap1 vif 100 mtu 1500
+   
+   # Configure VLAN 200
+   set vpp kernel-interfaces vpptap1 vif 200 address 192.168.200.1/24
+   set vpp kernel-interfaces vpptap1 vif 200 description "Guest VLAN"
+
+Configuration Examples
+----------------------
+
+Basic Kernel Interface
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Create basic kernel interface
+   set vpp kernel-interfaces vpptap1
+   set vpp kernel-interfaces vpptap1 description "VPP-Kernel bridge"
+   set vpp kernel-interfaces vpptap1 address 192.168.1.10/24
+   set vpp kernel-interfaces vpptap1 mtu 1500
+   set vpp kernel-interfaces vpptap1 rx-mode adaptive
+
+High-Performance Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # High-throughput configuration
+   set vpp kernel-interfaces vpptap2
+   set vpp kernel-interfaces vpptap2 description "High-performance bridge"
+   set vpp kernel-interfaces vpptap2 address 10.0.0.10/8
+   set vpp kernel-interfaces vpptap2 mtu 9000
+   set vpp kernel-interfaces vpptap2 rx-mode polling
+
+Multi-VLAN Setup
+^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Parent interface
+   set vpp kernel-interfaces vpptap3
+   set vpp kernel-interfaces vpptap3 description "Multi-VLAN trunk"
+   
+   # Management VLAN
+   set vpp kernel-interfaces vpptap3 vif 10
+   set vpp kernel-interfaces vpptap3 vif 10 address 192.168.10.1/24
+   set vpp kernel-interfaces vpptap3 vif 10 description "Management network"
+   
+   # Production VLAN
+   set vpp kernel-interfaces vpptap3 vif 20
+   set vpp kernel-interfaces vpptap3 vif 20 address 192.168.20.1/24
+   set vpp kernel-interfaces vpptap3 vif 20 description "Production network"
+   
+   # Guest VLAN
+   set vpp kernel-interfaces vpptap3 vif 30
+   set vpp kernel-interfaces vpptap3 vif 30 address 192.168.30.1/24
+   set vpp kernel-interfaces vpptap3 vif 30 description "Guest network"
+
+Bonding Integration
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Create VPP bonding interface
+   set vpp interfaces bonding bond0
+   set vpp interfaces bonding bond0 member interface eth0
+   set vpp interfaces bonding bond0 member interface eth1
+   set vpp interfaces bonding bond0 kernel-interface vpptap1
+   
+   # Configure the kernel interface for the bond
+   set vpp kernel-interfaces vpptap1 address 192.168.1.10/24
+   set vpp kernel-interfaces vpptap1 description "Bond management interface"
+
+Best Practices
+--------------
+
+* Use kernel interfaces selectively - not every VPP interface needs kernel exposure and also not all VPP interface types support kernel interfaces
+* Consider the performance impact of copying traffic between VPP and kernel
--- a/docs/vpp/configuration/interfaces/loopback.rst
+++ b/docs/vpp/configuration/interfaces/loopback.rst
@ -0,0 +1,86 @@
+:lastproofread: 2025-09-04
+
+.. _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 vpp interfaces loopback <loN>
+
+   Create a loopback interface where ``<loN>`` follows the naming convention lo1, lo2, etc.
+
+**Basic Example:**
+
+.. code-block:: none
+
+   set vpp interfaces loopback lo1
+
+Interface Configuration
+-----------------------
+
+Description and Administrative Control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces loopback <loN> description <description>
+
+   Set a descriptive name for the loopback interface.
+
+.. cfgcmd:: set vpp interfaces loopback <loN> disable
+
+   Administratively disable the loopback interface.
+
+Kernel Interface Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces loopback <loN> kernel-interface <interface-name>
+
+   Bind a kernel interface to the loopback interface for management and application compatibility.
+
+For detailed information about kernel interface integration, see :doc:`kernel`.
+
+Configuration Examples
+----------------------
+
+Basic Loopback Interface
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Create simple loopback
+   set vpp interfaces loopback lo1
+   set vpp interfaces loopback lo1 description "Router ID interface"
+
+Loopback with Kernel Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Loopback with management access
+   set vpp interfaces loopback lo2
+   set vpp interfaces loopback lo2 description "Management loopback"
+   set vpp interfaces loopback lo2 kernel-interface vpptun2
+   set vpp kernel-interfaces vpptun2 address 10.255.255.1/32
+
+Bridge Virtual Interface (BVI)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Loopback as BVI for bridge
+   set vpp interfaces loopback lo3
+   set vpp interfaces loopback lo3 description "Bridge gateway interface"
+   set vpp interfaces bridge br1
+   set vpp interfaces bridge br1 member interface lo3 bvi
+   set vpp interfaces loopback lo3 kernel-interface vpptun3
+   set vpp kernel-interfaces vpptun3 address 192.168.100.1/24
--- a/docs/vpp/configuration/interfaces/vxlan.rst
+++ b/docs/vpp/configuration/interfaces/vxlan.rst
@ -0,0 +1,135 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_interfaces_vxlan:
+
+.. include:: /_include/need_improvement.txt
+
+#######################
+VPP VXLAN Configuration
+#######################
+
+VPP VXLAN interfaces provide Virtual eXtensible Local Area Network 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 vpp interfaces vxlan <vxlanN>
+
+   Create a VXLAN interface where ``<vxlanN>`` follows the naming convention vxlan1, vxlan2, etc.
+
+.. cfgcmd:: set vpp interfaces vxlan <vxlanN> vni <vni>
+
+   Set the Virtual Network Identifier (VNI) for the VXLAN tunnel. Valid range is 0-16777214.
+
+.. cfgcmd:: set vpp interfaces vxlan <vxlanN> remote <address>
+
+   Set the tunnel remote endpoint address. Supports both IPv4 and IPv6 addresses.
+
+.. cfgcmd:: set vpp interfaces vxlan <vxlanN> source-address <address>
+
+   Set the tunnel source address. Must match an address configured on the local system.
+
+**Basic Example:**
+
+.. code-block:: none
+
+   set vpp interfaces vxlan vxlan1
+   set vpp interfaces vxlan vxlan1 vni 100
+   set vpp interfaces vxlan vxlan1 remote 203.0.113.2
+   set vpp interfaces vxlan vxlan1 source-address 192.168.1.1
+
+Interface Configuration
+-----------------------
+
+Description and Administrative Control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces vxlan <vxlanN> description <description>
+
+   Set a descriptive name for the VXLAN interface.
+
+.. cfgcmd:: set vpp interfaces vxlan <vxlanN> disable
+
+   Administratively disable the VXLAN interface.
+
+Kernel Interface Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces vxlan <vxlanN> kernel-interface <interface-name>
+
+   Bind a kernel interface to the VXLAN tunnel for management and application compatibility.
+
+For detailed information about kernel interface integration, see :doc:`kernel`.
+
+Configuration Examples
+----------------------
+
+Basic VXLAN Tunnel
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # IPv4 VXLAN tunnel
+   set vpp interfaces vxlan vxlan1
+   set vpp interfaces vxlan vxlan1 description "Tenant A network extension"
+   set vpp interfaces vxlan vxlan1 vni 1000
+   set vpp interfaces vxlan vxlan1 remote 203.0.113.10
+   set vpp interfaces vxlan vxlan1 source-address 192.168.1.1
+
+IPv6 VXLAN Tunnel
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # IPv6 endpoints
+   set vpp interfaces vxlan vxlan2
+   set vpp interfaces vxlan vxlan2 vni 2000
+   set vpp interfaces vxlan vxlan2 remote 2001:db8::2
+   set vpp interfaces vxlan vxlan2 source-address 2001:db8::1
+
+VXLAN with Kernel Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # VXLAN tunnel with management interface
+   set vpp interfaces vxlan vxlan3
+   set vpp interfaces vxlan vxlan3 vni 3000
+   set vpp interfaces vxlan vxlan3 remote 203.0.113.30
+   set vpp interfaces vxlan vxlan3 source-address 192.168.1.1
+   set vpp interfaces vxlan vxlan3 kernel-interface vpptun3
+   set vpp kernel-interfaces vpptun3 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 detailed bridge configuration.
+
+.. code-block:: none
+
+   # Add VXLAN tunnel to bridge
+   set vpp interfaces bridge br1
+   set vpp interfaces bridge br1 member interface vxlan1
+   set vpp interfaces bridge br1 member interface eth1
+   set vpp interfaces bridge br1 member interface lo1 bvi
+
+Multi-Tenant Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Multiple VNIs for tenant separation
+   set vpp interfaces vxlan vxlan10
+   set vpp interfaces vxlan vxlan10 description "Tenant A - Production"
+   set vpp interfaces vxlan vxlan10 vni 1001
+   set vpp interfaces vxlan vxlan10 remote 203.0.113.20
+   set vpp interfaces vxlan vxlan10 source-address 192.168.1.1
+   
+   set vpp interfaces vxlan vxlan11
+   set vpp interfaces vxlan vxlan11 description "Tenant A - Development"
+   set vpp interfaces vxlan vxlan11 vni 1002
+   set vpp interfaces vxlan vxlan11 remote 203.0.113.21
+   set vpp interfaces vxlan vxlan11 source-address 192.168.1.1
--- a/docs/vpp/configuration/interfaces/xconnect.rst
+++ b/docs/vpp/configuration/interfaces/xconnect.rst
@ -0,0 +1,101 @@
+:lastproofread: 2025-09-04
+
+.. _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 vpp interfaces xconnect <xconN>
+
+   Create an XConnect interface where ``<xconN>`` follows the naming convention xcon1, xcon2, etc.
+
+.. cfgcmd:: set vpp interfaces xconnect <xconN> 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:**
+
+.. code-block:: none
+
+   set vpp interfaces xconnect xcon1
+   set vpp interfaces xconnect xcon1 member interface eth0
+   set vpp interfaces xconnect xcon1 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
+-----------------------
+
+Description and Administrative Control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cfgcmd:: set vpp interfaces xconnect <xconN> description <description>
+
+   Set a descriptive name for the XConnect interface.
+
+.. cfgcmd:: set vpp interfaces xconnect <xconN> disable
+
+   Administratively disable the XConnect interface.
+
+Configuration Examples
+----------------------
+
+Physical Interface XConnect
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Connect two physical interfaces
+   set vpp interfaces xconnect xcon1
+   set vpp interfaces xconnect xcon1 description "Transparent wire between ports"
+   set vpp interfaces xconnect xcon1 member interface eth0
+   set vpp interfaces xconnect xcon1 member interface eth1
+
+This creates a transparent wire between two physical ports, effectively making them function as a single cable.
+
+Tunnel to Physical XConnect
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Connect tunnel to physical interface
+   set vpp interfaces xconnect xcon2
+   set vpp interfaces xconnect xcon2 description "GRE tunnel to physical bridge"
+   set vpp interfaces xconnect xcon2 member interface gre1
+   set vpp interfaces xconnect xcon2 member interface eth2
+
+This forwards all traffic from a GRE tunnel directly to a physical interface and vice versa.
+
+Mixed Interface Types
+^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+   # Connect different interface types
+   set vpp interfaces xconnect xcon3
+   set vpp interfaces xconnect xcon3 description "VXLAN to bonding bridge"
+   set vpp interfaces xconnect xcon3 member interface vxlan1
+   set vpp interfaces xconnect xcon3 member interface bond0
+
+This demonstrates XConnect's flexibility in connecting various VPP interface types.
--- a/docs/vpp/configuration/ipsec.rst
+++ b/docs/vpp/configuration/ipsec.rst
@ -0,0 +1,199 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_ipsec:
+
+.. include:: /_include/need_improvement.txt
+
+#######################
+VPP IPsec Configuration
+#######################
+
+VPP Dataplane in VyOS can offload IPSec processing from kernel. This allows to speed-up IPSec traffic handling significantly, when necessary conditions are met.
+
+.. note::
+   VPP IPsec implementation is not as feature rich as Linux kernel IPsec. It supports only a subset of algorithms and modes.
+
+Requirements
+============
+
+To make IPSec offloading work, following requirements must be met:
+
+* VPP dataplane must be configured.
+* VPP :doc:`IPsec settings </vpp/configuration/dataplane/ipsec>` should be configured as needed.
+* IPSec should be configured in the VPN configuration section, see :doc:`/configuration/vpn/ipsec/index`.
+* Both source and destination of the IPSec traffic must be reachable via VPP interfaces, so it can perform both encryption and decryption of the traffic.
+
+Integration Details
+===================
+
+VPP Dataplane offloads IPSec processing from kernel, but does not handle IPSec configuration itself. IPSec configuration management and control-plane operation, like IKE negotiation, is still done by the kernel and other daemons.
+
+After an IPSec tunnel is configured in the kernel, VPP receives the necessary information via netlink messages and creates a corresponding SAs and policies to be able to offload the traffic.
+
+When VPP is used for offloading IPsec, it creates a virtual interface of a specific type to connect to a peer. The type of the interface can be configured using the ``interface-type`` parameter in the dataplane settings.
+
+Supported IPsec Modes
+=====================
+
+VPP supports offloading IPsec connections in the following IPsec modes:
+
+* Tunnel mode
+* Transport mode
+
+Supported Encryption and Integrity Algorithms
+=============================================
+
+.. warning::
+
+    Since VPP dataplane is used only to offload IPsec traffic processing, algorithms mentioned below are applicable to ESP profiles in the IPsec configuration. IKE profiles are not affected by these limitations and can use any algorithms supported by the kernel.
+
+VPP **supports** only the following **encryption algorithms**:
+
+* AES-CBC
+
+VPP **does not** support the following **encryption algorithms**:
+
+* Null encryption
+* AES-CTR
+* AES-CCM with ICV
+* AES-GCM with ICV
+* Null encryption with AES-GMAC
+* 3DES-EDE-CBC
+* Blowfish-CBC
+* Camellia-CBC
+* Camellia-COUNTER
+* Camellia-CCM with ICV
+* Serpent-CBC
+* Twofish-CBC
+* CAST-CBC
+* ChaCha20/Poly1305 with ICV
+
+VPP **supports** the following **integrity algorithms**:
+
+* MD5 HMAC
+* SHA1 HMAC
+* SHA2_256_128 HMAC
+* SHA2_384_192 HMAC
+* SHA2_512_256 HMAC
+
+VPP **does not** support the following **integrity algorithms**:
+
+* MD5_128 HMAC
+* SHA1_160 HMAC
+* SHA2_256_96 HMAC
+* AES XCBC
+* AES CMAC
+* AES-GMAC
+
+If you have configured ESP profiles with algorithms not supported by VPP and the traffic for such peers flows trough VPP interfaces, such traffic will be dropped.
+
+Configuration Examples
+======================
+
+**ACL for VPP IPsec Traffic**
+
+When using VPP for offloading IPsec traffic, you may need to adjust your firewall rules to allow the necessary protocols and ports. Below is an example of how to configure ACLs for VPP IPsec traffic:
+
+.. code-block:: none
+
+    set vpp acl ip interface <interface-name> input acl-tag 10 tag-name 'IPSEC'
+    set vpp acl ip tag-name IPSEC description 'Allow IPsec traffic'
+    set vpp acl ip tag-name IPSEC rule 10 action 'permit'
+    set vpp acl ip tag-name IPSEC rule 10 destination port '500'
+    set vpp acl ip tag-name IPSEC rule 10 protocol 'tcp'
+    set vpp acl ip tag-name IPSEC rule 20 action 'permit'
+    set vpp acl ip tag-name IPSEC rule 20 destination port '500'
+    set vpp acl ip tag-name IPSEC rule 20 protocol 'udp'
+    set vpp acl ip tag-name IPSEC rule 30 action 'permit'
+    set vpp acl ip tag-name IPSEC rule 30 destination port '4500'
+    set vpp acl ip tag-name IPSEC rule 30 protocol 'tcp'
+    set vpp acl ip tag-name IPSEC rule 40 action 'permit'
+    set vpp acl ip tag-name IPSEC rule 40 destination port '4500'
+    set vpp acl ip tag-name IPSEC rule 40 protocol 'udp'
+    set vpp acl ip tag-name IPSEC rule 50 action 'permit'
+    set vpp acl ip tag-name IPSEC rule 50 protocol 'esp'
+
+Pay attention to the order of the rules, as they are processed sequentially. Make sure to place IPsec-related rules before any other rules that might deny traffic to ensure that IPsec traffic is allowed.
+
+**Simple VTI-based IPsec Tunnel**
+
+On the VPP host:
+
+.. code-block:: none
+
+    set interfaces ethernet eth1 address '192.168.1.1/24'
+    set interfaces ethernet eth2 address '192.168.100.1/24'
+
+    set interfaces vti vti1
+    set protocols static route 192.168.200.0/24 interface vti1
+
+    set vpn ipsec authentication psk psk1 id 'peerA'
+    set vpn ipsec authentication psk psk1 id 'peerB'
+    set vpn ipsec authentication psk psk1 secret 'AB'
+
+    set vpn ipsec esp-group esp1 mode 'tunnel'
+    set vpn ipsec esp-group esp1 pfs 'disable'
+    set vpn ipsec esp-group esp1 proposal 10 encryption 'aes256'
+    set vpn ipsec esp-group esp1 proposal 10 hash 'sha256'
+    set vpn ipsec ike-group ike1 close-action 'none'
+    set vpn ipsec ike-group ike1 dead-peer-detection action 'clear'
+    set vpn ipsec ike-group ike1 proposal 10 encryption 'aes256'
+    set vpn ipsec ike-group ike1 proposal 10 hash 'sha256'
+
+    set vpn ipsec interface 'eth1'
+
+    set vpn ipsec site-to-site peer peerB authentication local-id 'peerA'
+    set vpn ipsec site-to-site peer peerB authentication mode 'pre-shared-secret'
+    set vpn ipsec site-to-site peer peerB authentication remote-id 'peerB'
+    set vpn ipsec site-to-site peer peerB connection-type 'none'
+    set vpn ipsec site-to-site peer peerB default-esp-group 'esp1'
+    set vpn ipsec site-to-site peer peerB ike-group 'ike1'
+    set vpn ipsec site-to-site peer peerB local-address '192.168.1.1'
+    set vpn ipsec site-to-site peer peerB remote-address '192.168.1.3'
+    set vpn ipsec site-to-site peer peerB vti bind 'vti1'
+    set vpn ipsec site-to-site peer peerB vti traffic-selector remote prefix '192.168.200.0/24'
+
+    set vpp settings interface eth1 driver 'dpdk'
+    set vpp settings interface eth2 driver 'dpdk'
+    set vpp settings ipsec netlink rx-buffer-size '32000'
+    set vpp settings lcp ignore-kernel-routes
+
+Where:
+
+- ``eth1`` is the interface connected to the IPsec peer.
+- ``eth2`` is the interface connected to the local subnet, where unencrypted traffic is expected.
+- ``192.168.100.0/24`` is the local subnet that will be accessible through the IPsec tunnel.
+- ``192.168.200.0/24`` is the remote subnet that will be accessible through the IPsec tunnel.
+- ``vti1`` is the VTI interface created by VPP for the IPsec tunnel.
+- ``peerA`` and ``peerB`` are the identifiers for the local side and remote peer, respectively.
+
+.. note::
+
+    **What is important in this configuration**
+
+    VPP uses only remote traffic-selector to determine what traffic should be offloaded to the IPsec tunnel. 
+
+    Adding additional routes via VTI interface does not affect actual VPP IPsec operation.
+
+Potential Issues and Troubleshooting
+====================================
+
+Improper IPsec configuration can lead to various issues, including:
+
+* **Unidirectional traffic flow or acceleration**
+
+  If kernel has a conflicting route for the remote subnet, such route may take precedence over the policy route created for the IPsec tunnel in VPP. This may lead to unidirectional traffic flow or acceleration only in one direction. This has no security impact because traffic will still be encrypted by the kernel, but it may lead to performance degradation. To avoid this, ensure that no conflicting routes exist in the kernel routing table.
+
+* **Conflicting with kernel routes**
+
+  If the kernel routes synchronization option is enabled, VPP will install all the routes from kernel. If you have there routes configured via VTI interfaces to the IPsec peer, they will conflict with the policy routes created for the IPsec tunnel in VPP. Consider using policy-based IPSec configuration to avoid this or :ref:`disable the kernel routes synchronization <vpp_config_dataplane_lcp_ignore-kernel-routes>`.
+
+* **Unsupported algorithms**
+
+  If you have configured ESP profiles with algorithms not supported by VPP and the traffic for such peers flows through VPP interfaces, such traffic will be dropped. You can check system logs for messages from VPP with ``linux-cp/ipsec: Invalid/Unsupported crypto algo`` or ``linux-cp/ipsec: Invalid/Unsupported integ algo`` line to identify such cases.
+
+* **Connection is established but no traffic flows**
+
+  Even if you use compatible algorithms, there can be other reasons why traffic is not flowing. One of most frequent is blocking traffic between peers - that is especially common in public clouds. Make sure that TCP/UDP ports 500 and 4500 and ESP protocol are allowed between the peers. Alternatively, consider enforcing UDP encapsulation on both sides of the tunnel:
+
+  .. cfgcmd:: set vpn ipsec site-to-site peer <peer-name> force-udp-encapsulation
--- a/docs/vpp/configuration/nat/cgnat.rst
+++ b/docs/vpp/configuration/nat/cgnat.rst
@ -0,0 +1,141 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_nat_cgnat:
+
+.. include:: /_include/need_improvement.txt
+
+#######################
+VPP CGNAT Configuration
+#######################
+
+The Carrier-grade NAT (CGNAT) is a special type of NAT mainly targeted for usage by Internet Service Providers (ISPs) to manage the limited pool of public IP addresses. It solves two main problems:
+
+* allows to fairly share a limited number of public IP addresses between multiple customers, ensuring they all have access to the internet and cannot interfere with each other.
+* allows to track and log the usage of public IP addresses by different customers, which is often a regulatory requirement.
+
+The CGNAT configuration is a straightforward process. It involves defining the inside and outside interfaces and creating the necessary rules to manage the translation of private IP addresses to public IP addresses.
+
+.. warning::
+
+   **Enabling CGNAT** on an interface (both inside and outside) **disables normal routing** on these interfaces, **also as an management access** to VyOS router itself.
+   
+   Ensure you have an alternative management path to the router before applying CGNAT configuration!
+
+Interface Configuration
+-----------------------
+
+First, you need to define the inside and outside interfaces. The inside interface is connected to the private network, while the outside interface is connected to the public network.
+
+.. cfgcmd::
+
+   set vpp nat cgnat interface inside <inside-interface>
+
+.. cfgcmd::
+
+   set vpp nat cgnat interface outside <outside-interface>
+
+This is a mandatory step, as the CGNAT needs to know on which interfaces it needs to apply rules and operate.
+
+NAT Rules Configuration
+-----------------------
+
+Next, you need to create the NAT rules.
+
+.. cfgcmd::
+
+   set vpp nat cgnat rule <rule-number> description <description>
+
+Allows you to describe the rule for easier identification.
+
+.. cfgcmd::
+
+   set vpp nat cgnat rule <rule-number> inside-prefix <inside-prefix>
+
+Sets the inside prefix (private IP range) that will be translated.
+
+.. cfgcmd::
+
+   set vpp nat cgnat rule <rule-number> outside-prefix <outside-prefix>
+
+Sets the outside prefix (public IP range) that will be used for translation.
+
+Timeouts Configuration
+----------------------
+
+In some cases, you might want to adjust the timers for the NAT sessions. This can help to optimize the address space usage by controlling how long a session remains active, and how long it occupies an IP address and port combination.
+
+This setting can be adjusted for different protocols individually:
+
+.. code-block::
+
+    set vpp nat cgnat timeout icmp <timeout-value>
+    set vpp nat cgnat timeout tcp-established <timeout-value>
+    set vpp nat cgnat timeout tcp-transitory <timeout-value>
+    set vpp nat cgnat timeout udp <timeout-value>
+
+Example Configuration
+---------------------
+
+Here is an example configuration for a CGNAT setup, assuming:
+
+* Inside interface: ``eth2``
+* Outside interface: ``eth1``
+* Inside prefix: ``100.64.0.0/16``
+* Outside prefix: ``203.0.113.0/24``
+
+.. code-block::
+
+   set vpp nat cgnat interface inside eth2
+   set vpp nat cgnat interface outside eth1
+   set vpp nat cgnat rule 1 description "CGNAT Rule 1"
+   set vpp nat cgnat rule 1 inside-prefix 100.64.0.0/16
+   set vpp nat cgnat rule 1 outside-prefix 203.0.113.0/24
+
+Operational Commands
+====================
+
+Once the CGNAT is configured, you can use the following commands to monitor its status and operation:
+
+.. opcmd::
+
+   show vpp nat cgnat interfaces
+
+Displays the configured inside and outside interfaces.
+
+.. code-block::
+
+    vyos@vyos:~$ show vpp nat cgnat interfaces 
+    CGNAT interfaces:
+      eth2 in
+      eth1 out
+
+.. opcmd::
+
+    show vpp nat cgnat sessions
+
+Displays the active NAT sessions. Be aware that this command can produce a large amount of output if there are many active sessions.
+
+.. opcmd::
+
+   show vpp nat cgnat mappings
+
+Displays the current NAT mappings, including inside and outside address prefixes.
+
+.. code-block::
+
+    vyos@vyos:~$ show vpp nat cgnat mappings 
+    Inside         Outside           Sharing ratio    Ports per host    Sessions
+    -------------  --------------  ---------------  ----------------  ----------
+    100.64.0.0/16  203.0.113.0/24              256               252           0
+
+
+Potential Issues and Troubleshooting
+====================================
+
+Configuration is failed to apply with error similar to:
+
+.. code-block::
+    
+    vpp_papi.vpp_papi.VPPIOError: [Errno 2] VPP API client: read failed``
+
+CGNAT utilizes main heap memory and if you are trying to configure big prefixes or a large number of NAT sessions, you may run into memory allocation issues. Try to :ref:`increase the main heap size in VPP configuration <vpp_config_dataplane_memory>`.
--- a/docs/vpp/configuration/nat/index.rst
+++ b/docs/vpp/configuration/nat/index.rst
@ -0,0 +1,34 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_config_nat_index:
+
+.. include:: /_include/need_improvement.txt
+
+
+#####################
+VPP NAT Configuration
+#####################
+
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   cgnat
+   nat44
+
+VPP Dataplane in VyOS supports two types of NAT:
+
+NAT44
+=====
+
+This type is a classical NAT implementation where you can configure static and
+dynamic NAT rules. It supports both source and destination NAT - while the configuration may looks a bit unusual in comparison to traditional NAT implementations.
+
+CGNAT
+=====
+
+CGNAT is a special type of NAT44, which is highly useful for use cases where you have multiple local customers with a limited number of public IP addresses, and want to share public IP address space fairly between them. It uses a combination of IP address and port number to distinguish between different customers.
+
+This type of NAT is often used by ISPs to provide internet access to their customers.
+
+It supports only source NAT.
--- a/docs/vpp/configuration/nat/nat44.rst
+++ b/docs/vpp/configuration/nat/nat44.rst
@ -0,0 +1,552 @@
+:lastproofread: 2025-09-04
+
+.. _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.
+
+Configuration of NAT44 involves few steps:
+
+1. Define the inside and outside interfaces.
+2. Create NAT rules for SNAT and/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 more suitable for scenarios where you need to provide consistent and predictable mappings between private and public IP addresses, also they are the only way to configure DNAT.
+
+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 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 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 we commonly use "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:
+
+.. code-block:: none
+
+   # Multiple inside interfaces (different private networks)
+   set vpp nat44 interface inside eth0
+   set vpp nat44 interface inside eth2
+   
+   # Multiple outside interfaces (redundancy or load balancing)  
+   set vpp nat44 interface outside eth1
+   set vpp 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 nat44 address-pool translation address <ip-address | ip-address-range>
+
+.. cfgcmd::
+
+   set vpp nat44 address-pool translation interface <interface-name>
+
+**Examples:**
+
+.. code-block:: none
+
+   # Single address pool
+   set vpp nat44 address-pool translation address 203.0.113.10
+
+   # Address range pool  
+   set vpp 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 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 nat44 address-pool twice-nat address <ip-address | ip-address-range>
+
+.. cfgcmd::
+
+   set vpp nat44 address-pool twice-nat interface <interface-name>
+
+**Examples:**
+
+.. code-block:: none
+
+   # Twice-NAT pool for advanced scenarios
+   set vpp nat44 address-pool twice-nat address 192.168.100.1-192.168.100.10
+
+   # Interface-based twice-nat pool
+   set vpp 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
+   * All external IP addresses used in static rules must belong to one of the configured pools
+   * 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 nat44 static rule <rule-number> local address <internal-ip>
+
+.. cfgcmd::
+
+   set vpp 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 nat44 static rule <rule-number> local address <internal-ip>
+
+.. cfgcmd::
+
+   set vpp nat44 static rule <rule-number> local port <internal-port>
+
+.. cfgcmd::
+
+   set vpp nat44 static rule <rule-number> external address <external-ip>
+
+.. cfgcmd::
+
+   set vpp nat44 static rule <rule-number> external port <external-port>
+
+.. cfgcmd::
+
+   set vpp 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) - if not specified, the rule applies to all protocols
+
+Advanced Static Rule Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+VyOS NAT44 supports several advanced options for static rules:
+
+Twice-NAT
+~~~~~~~~~
+
+Twice-NAT performs both source and destination NAT. So when an external host accesses an internal service, a source IP of such connection is translated to an address from the twice-NAT address pool.
+
+This is practical in scenarios where internal services cannot connect public networks, so they may see such traffic as internal.
+
+The twice-NAT option can be enabled with the following command:
+
+.. cfgcmd::
+
+   set vpp 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 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 to set interface connected to the local network as both inside and outside interface, because both source and destination NAT need to be applied.
+
+Out-to-In Only
+~~~~~~~~~~~~~~
+
+Restricts the rule to only apply to traffic from outside to inside interfaces:
+
+.. cfgcmd::
+
+   set vpp nat44 static rule <rule-number> options out-to-in-only
+
+This prevents the creation of sessions from the inside interface, making it purely a 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 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 nat44 static rule <rule-number> description <description>
+
+Configuration Examples
+^^^^^^^^^^^^^^^^^^^^^^
+
+**Full one-to-one NAT mapping:**
+
+.. code-block:: none
+
+   set vpp nat44 static rule 100 local address 192.168.1.10
+   set vpp nat44 static rule 100 external address 203.0.113.10
+   set vpp nat44 static rule 100 description "One-to-one mapping"
+
+**Port-specific SSH access:**
+
+.. code-block:: none
+
+   set vpp nat44 static rule 200 local address 192.168.1.20
+   set vpp nat44 static rule 200 local port 22
+   set vpp nat44 static rule 200 external address 203.0.113.10
+   set vpp nat44 static rule 200 external port 2222
+   set vpp nat44 static rule 200 protocol tcp
+   set vpp nat44 static rule 200 description "SSH access to server"
+
+**Twice-NAT for local service access:**
+
+.. code-block:: none
+
+   set vpp nat44 static rule 300 local address 192.168.1.30
+   set vpp nat44 static rule 300 local port 80
+   set vpp nat44 static rule 300 external address 203.0.113.10
+   set vpp nat44 static rule 300 external port 80
+   set vpp nat44 static rule 300 protocol tcp
+   set vpp nat44 static rule 300 options twice-nat
+   set vpp 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:
+   
+   ``set vpp nat44 address-pool twice-nat address <twice-nat-ip-range>``
+
+Advanced NAT44 Settings
+-----------------------
+
+VyOS provides additional NAT44 settings for fine-tuning performance and behavior. These settings are configured under the VPP settings hierarchy.
+
+Session Timeouts
+^^^^^^^^^^^^^^^^
+
+NAT44 maintains translation sessions with configurable timeout values for different protocols:
+
+.. cfgcmd:: set vpp settings nat44 timeout icmp <seconds>
+
+   Set the timeout for ICMP sessions. Default: 60 seconds.
+
+.. cfgcmd:: set vpp settings nat44 timeout tcp-established <seconds>
+
+   Set the timeout for established TCP connections. Default: 7440 seconds (2 hours 4 minutes).
+
+.. cfgcmd:: set vpp settings nat44 timeout tcp-transitory <seconds>
+
+   Set the timeout for transitory TCP connections (connection setup/teardown). Default: 240 seconds (4 minutes).
+
+.. cfgcmd:: set vpp settings nat44 timeout udp <seconds>
+
+   Set the timeout for UDP sessions. Default: 300 seconds (5 minutes).
+
+**Example:**
+
+.. code-block:: none
+
+   # Customize timeouts for high-traffic environment
+   set vpp settings nat44 timeout tcp-established 3600
+   set vpp settings nat44 timeout udp 600
+   set vpp settings nat44 timeout icmp 30
+
+Session Limits
+^^^^^^^^^^^^^^
+
+Control the maximum number of concurrent NAT sessions:
+
+.. cfgcmd:: set vpp settings 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:**
+
+.. code-block:: none
+
+   # Increase session limit for high-capacity deployment
+   set vpp settings nat44 session-limit 100000
+
+Forwarding Behavior
+^^^^^^^^^^^^^^^^^^^
+
+By default, VyOS NAT44 forwards packets that don't match any NAT rules according to the routing table. This behavior can be controlled:
+
+.. cfgcmd:: set vpp settings nat44 no-forwarding
+
+   Disable forwarding of packets that don't match existing NAT translations. When enabled, only packets that match static or dynamic NAT rules will be processed; all other traffic will be dropped.
+
+.. important::
+
+   This is a significant difference from traditional NAT solutions. By default, VyOS NAT44 allows non-NAT traffic to be forwarded normally. Using ``no-forwarding`` creates a pure NAT-only device that drops any traffic not covered by NAT rules.
+
+**Use cases for no-forwarding:**
+
+* **Pure NAT gateway**: When the router should only handle NAT traffic and drop everything else
+* **Security isolation**: Preventing any non-NAT traffic from traversing the device
+
+Worker Assignment
+^^^^^^^^^^^^^^^^^
+
+For advanced performance tuning, you can assign NAT44 processing to specific worker threads:
+
+.. cfgcmd:: set vpp settings nat44 workers <worker-id>
+
+.. cfgcmd:: set vpp settings nat44 workers <worker-range>
+
+   Assign NAT44 processing to specific VPP worker threads. You can specify individual worker IDs or ranges using the format ``<start>-<end>``.
+
+**Examples:**
+
+.. code-block:: none
+
+   # Assign NAT44 to specific workers
+   set vpp settings nat44 workers 0
+   set vpp settings nat44 workers 2-4
+
+.. note::
+
+   Worker assignment is an advanced feature typically used in high-performance deployments where you want to dedicate specific CPU cores to NAT processing. Most deployments don't require this configuration.
+
+Complete Configuration Example
+------------------------------
+
+Here's a complete example showing how to configure VyOS NAT44 for a typical network setup:
+
+**Network Topology:**
+
+.. code-block:: 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:**
+
+.. code-block:: none
+
+   # Configure interfaces
+   set vpp nat44 interface inside eth0
+   set vpp nat44 interface outside eth1
+
+   # Configure address pools
+   set vpp nat44 address-pool translation address 203.0.113.10-203.0.113.50
+   set vpp nat44 address-pool twice-nat address 203.0.113.100-203.0.113.110
+
+   # Static rule for web server (HTTP)
+   set vpp nat44 static rule 100 local address 192.168.1.10
+   set vpp nat44 static rule 100 local port 80
+   set vpp nat44 static rule 100 external address 203.0.113.10
+   set vpp nat44 static rule 100 external port 80
+   set vpp nat44 static rule 100 protocol tcp
+   set vpp nat44 static rule 100 description "Public web server"
+
+   # Static rule for web server (HTTPS)
+   set vpp nat44 static rule 101 local address 192.168.1.10
+   set vpp nat44 static rule 101 local port 443
+   set vpp nat44 static rule 101 external address 203.0.113.10
+   set vpp nat44 static rule 101 external port 443
+   set vpp nat44 static rule 101 protocol tcp
+   set vpp nat44 static rule 101 description "Public web server HTTPS"
+
+   # Static rule for SSH server with custom port
+   set vpp nat44 static rule 200 local address 192.168.1.20
+   set vpp nat44 static rule 200 local port 22
+   set vpp nat44 static rule 200 external address 203.0.113.11
+   set vpp nat44 static rule 200 external port 2222
+   set vpp nat44 static rule 200 protocol tcp
+   set vpp nat44 static rule 200 description "SSH access"
+
+   # Static rule for API service (out-to-in only for security)
+   set vpp nat44 static rule 300 local address 192.168.1.30
+   set vpp nat44 static rule 300 local port 8080
+   set vpp nat44 static rule 300 external address 203.0.113.12
+   set vpp nat44 static rule 300 external port 8080
+   set vpp nat44 static rule 300 protocol tcp
+   set vpp nat44 static rule 300 options out-to-in-only
+   set vpp nat44 static rule 300 description "API service (No Internet access for it)"
+
+Best Practices and Troubleshooting
+----------------------------------
+
+Recommendations
+^^^^^^^^^^^^^^^
+
+* **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/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
+
+Operational Commands
+^^^^^^^^^^^^^^^^^^^^
+
+Monitor NAT44 status and active connections using VyOS operational commands:
+
+.. opcmd:: show vpp nat44 addresses
+
+   Display configured NAT44 address pools.
+
+.. opcmd:: show vpp nat44 interfaces
+
+   Show which interfaces are configured as inside/outside for NAT44.
+
+.. opcmd:: show vpp nat44 sessions
+
+   Display active NAT44 translation sessions.
+
+.. opcmd:: show vpp nat44 static
+
+   Show all configured static NAT mappings.
+
+.. opcmd:: show vpp nat44 summary
+
+   Display a summary of NAT44 and statistics.
--- a/docs/vpp/configuration/sflow.rst
+++ b/docs/vpp/configuration/sflow.rst
@ -0,0 +1,43 @@
+: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 sampling rate for the interface using the following command:
+
+.. cfgcmd::
+
+   set vpp sflow sample-rate <rate>
+
+This will set the sampling rate for the specified interface. The default sampling rate is 1, which means that every packet is sampled. A higher sampling rate means that fewer packets are sampled, which can reduce the amount of data sent to the sFlow collector. This can be useful in high-traffic environments to reduce the load on the collector.
+
+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.
--- a/docs/vpp/description.rst
+++ b/docs/vpp/description.rst
@ -0,0 +1,82 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_description:
+
+.. include:: /_include/need_improvement.txt
+
+#########################
+VPP Dataplane Description
+#########################
+
+What is VPP in VyOS?
+====================
+
+VyOS supports two packet forwarding dataplanes: the traditional Linux kernel dataplane and the optional Vector Packet Processor (VPP) dataplane. VPP is a high-performance userspace packet processing engine that can significantly improve throughput for demanding network workloads.
+
+Key Benefits
+============
+
+**Performance Improvement**
+
+VPP processes packets in a special way, using vectors, rather than one-by-one, delivering:
+
+- **Much higher throughput** compared to kernel forwarding
+- **Lower and more consistent latency** for time-sensitive applications
+- **Linear scaling** with additional CPU cores
+
+**VyOS Hybrid Integration**
+
+VyOS provides unique flexibility by supporting both dataplanes simultaneously:
+
+- **Cross-dataplane forwarding**: Traffic can flow between VPP and kernel interfaces seamlessly
+- **Transparent configuration**: Same CLI commands and most services work regardless of dataplane
+- **Gradual migration**: Enable VPP on high-traffic interfaces while keeping others on kernel
+
+When to Use VPP
+===============
+
+**Consider VPP if you have:**
+
+- High-throughput requirements
+- Latency-sensitive applications requiring consistent performance
+
+**Stay with kernel dataplane if you have:**
+
+- Low to moderate traffic volumes
+- No latency-sensitive workloads
+- Applications requiring specific features not supported by VPP Dataplane
+
+Packets Processing Integration Details
+======================================
+
+VPP Dataplane integration is done in the way that minimizes configuration changes. Features that exist in kernel dataplane are not removed but continue to operate in kernel dataplane. VPP Dataplane only takes over packet forwarding for interfaces explicitly assigned to it.
+
+Examples of traffic flow between interfaces connected to VPP and kernel dataplanes:
+
+.. image:: /_static/images/vpp/vyos_vpp_integration.svg
+   :align: center
+
+Green path
+""""""""""
+
+Traffic between two VPP interfaces is processed entirely within VPP for maximum performance. Packets that follow this path can use only features available inside VPP dataplane.
+
+Blue path
+"""""""""
+
+Traffic between a VPP interface and a kernel interface is processed by both dataplanes, with VPP handling the VPP side and the kernel handling the kernel side. Packets that follow this path can use features available in both VPP and kernel dataplanes, at the same time.
+
+**Note:** Because packets must follow both dataplanes, performance will be slower than with pure VPP or pure kernel forwarding.
+
+Red path
+""""""""
+
+Traffic between two kernel interfaces is processed entirely within the kernel dataplane. Packets that follow this path can use only features available inside kernel dataplane, and lack VPP acceleration.
+
+This is the traditional VyOS dataplane operation.
+
+
+CLI Integration
+===============
+
+VyOS CLI commands are designed to work seamlessly with both dataplanes. When configuring interfaces, routing, and other features, the same commands can be used regardless of the underlying dataplane.
--- a/docs/vpp/index.rst
+++ b/docs/vpp/index.rst
@ -0,0 +1,22 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_index:
+
+.. include:: /_include/need_improvement.txt
+
+#############
+VPP Dataplane
+#############
+
+VPP (Vector Packet Processing) is a high performance, packet processing stack
+that runs in user space. VyOS can use VPP as an alternative dataplane to
+the Linux kernel networking stack.
+
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   description
+   requirements
+   limitations
+   configuration/index
--- a/docs/vpp/limitations.rst
+++ b/docs/vpp/limitations.rst
@ -0,0 +1,33 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_limitations:
+
+.. include:: /_include/need_improvement.txt
+
+#########################
+VPP Dataplane Limitations
+#########################
+
+
+While VPP Dataplane offers significant performance advantages, there are some limitations and considerations to be aware of.
+
+* **Feature Parity**
+
+  Not all features available in the Linux kernel dataplane are supported in VPP. Some networking features, specific protocols, or services may not be available.
+
+  VPP supports various interface types that have parity with kernel, but their capabilities may differ.
+
+* **NIC and Drivers Compatibility**
+
+  Some NICs may work with DPDK drivers but not with XDP, or vice versa.
+
+* **Data Path Limitations**
+
+  If a feature exists only in kernel dataplane, traffic using that feature will not be able to traverse VPP interfaces. Examples of such features are:
+
+  - Firewall
+  - QoS
+
+  When traffic uses pure VPP path, it simply never reaches the kernel where such features are implemented. Therefore, you need to carefully plan how traffic flows through VyOS router to ensure that it can reach expected features.
+
+  VPP has native replacements for some of these features, for example VPP native ACLs can satisfy basic firewalling needs. 
--- a/docs/vpp/requirements.rst
+++ b/docs/vpp/requirements.rst
@ -0,0 +1,57 @@
+:lastproofread: 2025-09-04
+
+.. _vpp_requirements:
+
+.. include:: /_include/need_improvement.txt
+
+##########################
+VPP Dataplane Requirements
+##########################
+
+VPP Dataplane usage in VyOS has very strict hardware requirements. Please ensure your system meets the following prerequisites before enabling VPP:
+
+* **Deployment Platform**
+
+  VPP Dataplane is available on both bare-metal, on-premise virtualized, and cloud deployment platforms.
+
+* **CPU Requirements**
+
+  Regardless of the platform, VPP Dataplane requires a CPU with the following features:
+
+  - SSE4.2 support (most modern Intel and AMD CPUs)
+  - At least 4 **physical** CPU cores for the minimum configuration. More cores are recommended for higher throughput.
+
+  .. important:: **Physical Cores vs Logical Cores**
+
+     VPP Dataplane requires 4 **physical** CPU cores, not logical cores. Many systems use Simultaneous Multithreading (SMT) or Hyper-Threading (HT), which presents each physical core as 2 logical cores.
+
+     **Cloud Provider Considerations:**
+
+     Some cloud providers display logical cores in their UI as "cores" or "vCPUs", which can be misleading. For example:
+
+     - A cloud instance showing "4 cores" may actually have only 2 physical cores with SMT/HT enabled
+     - Always verify the actual physical core count, not the logical core count
+     - Check your cloud provider's documentation to understand their core counting methodology
+
+  **Note:** If you are using VyOS in a virtualized environment, ensure that CPU features are properly passed through to the VM and that you have allocated sufficient physical cores.
+
+* **Memory Requirements**
+
+  Memory is one of the biggest factors affecting VPP stability, therefore it is critical to ensure that your system has sufficient RAM.
+
+  - Minimum: 8 GB RAM
+  - Recommended: 16 GB or more, if you have high throughput requirements, many interfaces, or big routing tables.
+
+  VyOS contains safeguards that prevent VPP from starting if there is insufficient memory for the initial configuration, but it does not protect from memory exhaustion during operation.
+
+* **Network Interface Cards (NICs)**
+
+  .. warning:: VyOS allows using VPP Dataplane only with NICs that are known to be compatible. Using unsupported NICs may lead to inability to activate the dataplane, initialize a NIC, crashes during operations, and degraded performance.
+
+  Validated NICs include:
+
+  - Intel® Ethernet Network Adapter E810-2CQDA2
+  - NVIDIA/Mellanox ConnectX-5
+  - VirtIO
+
+  Other NICs may work, but are not officially supported.