diff options
Diffstat (limited to 'docs/vpp/configuration/interfaces')
| -rw-r--r-- | docs/vpp/configuration/interfaces/bonding.rst | 182 | ||||
| -rw-r--r-- | docs/vpp/configuration/interfaces/bridge.rst | 200 | ||||
| -rw-r--r-- | docs/vpp/configuration/interfaces/gre.rst | 157 | ||||
| -rw-r--r-- | docs/vpp/configuration/interfaces/index.rst | 40 | ||||
| -rw-r--r-- | docs/vpp/configuration/interfaces/ipip.rst | 96 | ||||
| -rw-r--r-- | docs/vpp/configuration/interfaces/kernel.rst | 258 | ||||
| -rw-r--r-- | docs/vpp/configuration/interfaces/loopback.rst | 86 | ||||
| -rw-r--r-- | docs/vpp/configuration/interfaces/vxlan.rst | 135 | ||||
| -rw-r--r-- | docs/vpp/configuration/interfaces/xconnect.rst | 101 |
9 files changed, 1255 insertions, 0 deletions
diff --git a/docs/vpp/configuration/interfaces/bonding.rst b/docs/vpp/configuration/interfaces/bonding.rst new file mode 100644 index 00000000..1f287c4e --- /dev/null +++ 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) diff --git a/docs/vpp/configuration/interfaces/bridge.rst b/docs/vpp/configuration/interfaces/bridge.rst new file mode 100644 index 00000000..15608433 --- /dev/null +++ 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. diff --git a/docs/vpp/configuration/interfaces/gre.rst b/docs/vpp/configuration/interfaces/gre.rst new file mode 100644 index 00000000..464734b6 --- /dev/null +++ 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 diff --git a/docs/vpp/configuration/interfaces/index.rst b/docs/vpp/configuration/interfaces/index.rst new file mode 100644 index 00000000..ebbf577e --- /dev/null +++ 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. diff --git a/docs/vpp/configuration/interfaces/ipip.rst b/docs/vpp/configuration/interfaces/ipip.rst new file mode 100644 index 00000000..92ceba91 --- /dev/null +++ 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 diff --git a/docs/vpp/configuration/interfaces/kernel.rst b/docs/vpp/configuration/interfaces/kernel.rst new file mode 100644 index 00000000..8963f010 --- /dev/null +++ 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 diff --git a/docs/vpp/configuration/interfaces/loopback.rst b/docs/vpp/configuration/interfaces/loopback.rst new file mode 100644 index 00000000..082124d2 --- /dev/null +++ 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 diff --git a/docs/vpp/configuration/interfaces/vxlan.rst b/docs/vpp/configuration/interfaces/vxlan.rst new file mode 100644 index 00000000..3bd03cc6 --- /dev/null +++ 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 diff --git a/docs/vpp/configuration/interfaces/xconnect.rst b/docs/vpp/configuration/interfaces/xconnect.rst new file mode 100644 index 00000000..822a6536 --- /dev/null +++ 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. |