diff options
Diffstat (limited to 'docs/vpp')
30 files changed, 3695 insertions, 0 deletions
diff --git a/docs/vpp/configuration/dataplane/md-buffers.md b/docs/vpp/configuration/dataplane/md-buffers.md new file mode 100644 index 00000000..80f2f23c --- /dev/null +++ b/docs/vpp/configuration/dataplane/md-buffers.md @@ -0,0 +1,90 @@ +--- +lastproofread: '2026-02-23' +--- + +(vpp-config-dataplane-buffers)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Dataplane Buffers Configuration + +Buffers are essential for handling network packets efficiently. Proper +configuration enhances performance and reliability, and is mandatory for +VPP to work. Buffers temporarily store packets during processing. Therefore, +their configuration must be in sync with NIC configuration, CPU threads, and +overall system resources. + +:::{important} +VPP buffers are allocated from the physical memory pool (`physmem`). The +total amount of memory available for buffer allocation is controlled by the +`physmem-max-size` setting, while the buffer configuration parameters +below control how that memory is used for buffer allocation. + +See {ref}`VPP Physical Memory Configuration <vpp_config_dataplane_physmem>` +for details on configuring `physmem`. +::: + +## Buffer Configuration Parameters + +The following parameters can be configured for VPP buffers: + +### buffers-per-numa +Number of buffers allocated per NUMA node. This setting optimizes +memory access patterns for multi-CPU systems. + +Typically, you need to tune this value if: +- The system has many interfaces +- NICs have many queues +- NICs have large descriptor sizes + +Set this value carefully to balance memory usage and performance. +```{cfgcmd} set vpp settings resource-allocation buffers buffers-per-numa \<value\> +``` +The common approach for the calculation is to use the formula: +```none +buffers-per-numa = (num-rx-queues * num-rx-desc) + (num-tx-queues * num-tx-desc) +``` +Calculate this formula for each NIC and sum the results. Multiply the +total by 2.5 to get the minimum recommended value for +`buffers-per-numa`. + +Avoid setting this value too low to prevent packet drops. + +### data-size +This value sets how much payload data can be stored in a single buffer +allocated by VPP. Larger values reduce buffer chains for large packets, +while smaller values conserve memory for environments handling mostly +small packets. +```{cfgcmd} set vpp settings resource-allocation buffers data-size \<value\> +``` +Optimal size depends on the typical packet size in your network. If +unsure, use the largest MTU in your network plus overhead (for example, +128 bytes). + +### page-size +A memory pages type used for buffer allocation. Common values are 4K, 2M, or 1G. + +Use page sizes configured in your system settings. +```{cfgcmd} set vpp settings resource-allocation buffers page-size \<value\> +``` + +## Potential Issues and Troubleshooting + +Improper buffer configuration can lead to issues such as: + +- Increased latency and packet loss +- Inefficient CPU utilization +- Interface initialization failures + +Indicators of such issues are: + +- Errors during interfaces initialization in VPP logs +- Packet drops observed in VPP statistics + +To troubleshoot buffer-related issues, consider the following steps: + +- Review VPP logs for errors related to buffer allocation. Look for + error `-5` messages. +- Tune available buffers by adjusting the `buffers-per-numa` and + `data-size` parameters. diff --git a/docs/vpp/configuration/dataplane/md-cpu.md b/docs/vpp/configuration/dataplane/md-cpu.md new file mode 100644 index 00000000..9b798631 --- /dev/null +++ b/docs/vpp/configuration/dataplane/md-cpu.md @@ -0,0 +1,66 @@ +--- +lastproofread: '2026-02-23' +--- + +(vpp-config-dataplane-cpu)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Dataplane CPU Configuration +VPP can utilize multiple CPU cores for better packet processing +performance. Proper CPU configuration is essential for optimal +throughput and low latency. + +VPP CPU assignment is handled automatically. You specify how many CPU +cores VPP may use, and the system distributes them between the main +thread and worker threads. + +:::{important} +Review the system configuration settings page before changing CPU +settings: {doc}`system`. +::: +If you don't configure CPU settings, VPP uses a single core for the +main thread and doesn't create worker threads. + +## CPU Configuration Parameters + +### `cpu-cores` +This parameter defines the total number of CPU cores allocated to VPP. +```{cfgcmd} set vpp settings resource-allocation cpu-cores \<core-number\> +``` + +The system automatically assigns cores using the following rules: + +> - The first two CPU cores are always reserved for the operating system and +> other services. +> - The main VPP thread is assigned to the first available core after the +> reserved ones. +> - The remaining allocated cores are used for worker threads. + +For example: + +> - If cpu-cores is set to 1, VPP runs only a main thread. +> +> - If cpu-cores is set to 4, VPP uses: +> +> > - 1 core for the main thread +> > - 3 cores for worker threads + +Choose a value based on available hardware resources and expected +traffic load. Too few cores may limit performance, while too many can +negatively impact other system services. + +## Potential Issues and Troubleshooting + +Improper CPU configuration can lead to issues such as: + +- VPP underperformance when not enough cores are assigned, or kernel + underperformance when too many cores are assigned to VPP. +- Resource conflicts with other processes and services. + +Indicators of such issues are: + +- VPP or kernel forwarding performance is lower than expected +- Degraded performance of system components or services, such as DNS, + DHCP, and dynamic routing diff --git a/docs/vpp/configuration/dataplane/md-index.md b/docs/vpp/configuration/dataplane/md-index.md new file mode 100644 index 00000000..f147ebe8 --- /dev/null +++ b/docs/vpp/configuration/dataplane/md-index.md @@ -0,0 +1,32 @@ +--- +lastproofread: '2026-02-23' +--- + +(vpp-config-dataplane-index)= + +```{include} /_include/need_improvement.txt +``` +# VPP Dataplane Core Configuration +This section covers the core configuration options for the VPP dataplane in +VyOS. It includes settings for memory management, CPU allocation, hugepages, +and other essential parameters that influence the performance and behavior +of the VPP dataplane. +Please review the general system configuration, before starting to configure +VPP. Without proper VyOS preconditions, VPP will not start or its efficiency +will be significantly degraded. +```{toctree} +:includehidden: true +:maxdepth: 1 + +system +buffers +cpu +interface +ipsec +ipv6 +l2learn +lcp +logging +memory +unix +``` diff --git a/docs/vpp/configuration/dataplane/md-interface.md b/docs/vpp/configuration/dataplane/md-interface.md new file mode 100644 index 00000000..231a49a9 --- /dev/null +++ b/docs/vpp/configuration/dataplane/md-interface.md @@ -0,0 +1,88 @@ +--- +lastproofread: '2026-02-23' +--- + +(vpp-config-dataplane-interface)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Dataplane Interfaces Configuration +Only Ethernet interfaces (physical or virtual) can be connected to the +VPP dataplane. Interfaces configured here act as a bridge between VPP +and the outside world, allowing VPP to send and receive network +packets. + +## Interface Configuration Parameters +Interfaces connected to the VPP dataplane use the DPDK driver by default, +providing high performance and low latency. +```{cfgcmd} set vpp settings interface \<interface-name\> +``` +Some network interface cards (NICs) may not be compatible with the DPDK driver. + +### DPDK interface options +This section shows how to configures DPDK-specific settings for an interface. +```{cfgcmd} set vpp settings interface \<interface-name\> num-rx-queues \<value\> +``` +Specifies the number of receive queues for the interface. More queues +improve performance on multi-core systems by allowing parallel +processing of incoming packets. Each queue is assigned to a separate +CPU core. +```{cfgcmd} set vpp settings interface \<interface-name\> num-tx-queues \<value\> +``` +Specifies the number of transmit queues for the interface. Similar to +receive queues, more transmit queues improve performance by enabling +parallel processing of outgoing packets. By default, the VPP Dataplane +has one TX queue per enabled CPU worker, or a single queue if no +workers are configured. + +:::{seealso} +{doc}`cpu` +::: +```{cfgcmd} set vpp settings interface \<interface-name\> num-rx-desc \<value\> +``` +Defines the size of each receive queue. Larger queue sizes accommodate +bursts of incoming traffic and reduce the likelihood of packet drops +during high traffic periods. +```{cfgcmd} set vpp settings interface \<interface-name\> num-tx-desc \<value\> +``` +Defines the size of each transmit queue. Larger sizes help manage +bursts of outgoing traffic more effectively. + +## Global Interface Parameters +(vpp-config-dataplane-interface-rx-mode)= + +### interface-rx-mode +The `interface-rx-mode` parameter defines how VPP handles incoming +packets on interfaces. There are several modes available, each with its +own advantages and use cases: +- `interrupt`: In this mode, VPP relies on hardware interrupts to + notify it of incoming packets. This mode suits low to moderate + traffic loads and reduces CPU usage during idle periods. It is not + recommended for low-latency processing. Some NICs may not support + this mode. +- `polling`: In polling mode, VPP continuously checks the interface + for incoming packets. This mode is ideal for high-throughput + scenarios where low latency is critical, as it minimizes packet + waiting time. However, it can increase CPU usage, especially during + low traffic periods, as the polling process is always active. +- `adaptive`: Adaptive mode combines the benefits of interrupt and + polling modes. VPP starts in interrupt mode and switches to polling + mode when traffic load increases. +```{cfgcmd} set vpp settings interface-rx-mode \<mode\> +``` + +Choose an rx-mode based on expected traffic patterns and performance +requirements of your network. + +## Potential Issues and Troubleshooting + +Improper interface configuration can lead to issues such as: + +- Failure to initialize the interface +- Poor performance due to suboptimal driver selection or settings + +Indicators of such issues are: + +- Failed commits after adding or modifying an interface settings +- Low throughput or high latency on the interface diff --git a/docs/vpp/configuration/dataplane/md-ipsec.md b/docs/vpp/configuration/dataplane/md-ipsec.md new file mode 100644 index 00000000..17e16f8e --- /dev/null +++ b/docs/vpp/configuration/dataplane/md-ipsec.md @@ -0,0 +1,63 @@ +--- +lastproofread: '2026-02-23' +--- + +(vpp-config-dataplane-ipsec)= + +```{include} /_include/need_improvement.txt +``` + +# VPP IPsec Configuration +VPP supports IPsec (Internet Protocol Security) offloading from the +kernel, which speeds up cryptographic operations by leveraging VPP's +high-performance packet processing capabilities. + +IPsec does not require any specific configuration on VPP side. If both +sources and destinations of the IPsec traffic are reachable via VPP +interfaces, VPP will automatically offload the IPsec processing from +the kernel. IPsec tunnels are configured in the VPN configuration +section, see {ref}`ipsec_general`. + +## IPsec Configuration Parameters + +### enable IPsec acceleration +When VPP is used for offloading IPsec, it creates a virtual interface to +connect to peers. The interface type is always 'ipsec', which is used for +IPsec tunnels. +```{cfgcmd} set vpp settings ipsec-acceleration +``` +Enabling this option allows VPP to handle IPsec traffic more efficiently by +offloading processing from the kernel. + +### netlink +VPP uses netlink to receive IPsec event messages from the kernel. Proper +settings of the following parameters are crucial for ensuring that VPP can +process all such messages: +```{cfgcmd} set vpp settings lcp netlink batch-delay-ms \<milliseconds\> +``` +This parameter specifies the delay in milliseconds between processing +batch netlink messages. +```{cfgcmd} set vpp settings lcp netlink batch-size \<number\> +``` +This parameter specifies the maximum number of netlink messages to +process in a single batch. +```{cfgcmd} set vpp settings lcp netlink rx-buffer-size \<number\> +``` + +This parameter specifies the size of the receive buffer for netlink +socket. If you expect to offload many IPsec tunnels or get frequent and +intensive rekeying, you may need to increase this value. + +:::{note} +IPsec uses the same netlink parameters as LCP, so tuning them +affects both LCP and IPsec processing. +::: + +## Potential Issues and Troubleshooting + +Improper IPsec configuration can lead to various issues, including: + +- Failure to offload IPsec tunnels to VPP +- Lost IPsec event messages due to insufficient netlink buffer size or + batch settings +- IPsec states or SAs are not synchronized between kernel and VPP diff --git a/docs/vpp/configuration/dataplane/md-ipv6.md b/docs/vpp/configuration/dataplane/md-ipv6.md new file mode 100644 index 00000000..a72dbbfa --- /dev/null +++ b/docs/vpp/configuration/dataplane/md-ipv6.md @@ -0,0 +1,41 @@ +--- +lastproofread: '2026-02-26' +--- + +(vpp-config-dataplane-ipv6)= + +```{include} /_include/need_improvement.txt +``` + +# VPP IPv6 Configuration +VPP lets you configure resources allocated for IPv6 traffic processing +independently from IPv4. This helps ensure that in networks without IPv6 +traffic, resources are not wasted. If IPv6 traffic is present, especially +with large routing tables, you must allocate additional resources for IPv6 +processing to keep the dataplane stable. + +You can configure two main resources for IPv6 traffic processing: +```{cfgcmd} set vpp settings resource-allocation ipv6 hash-buckets \<value\> +``` +This parameter configures the number of hash buckets used for IPv6 +routing. If you have a large IPv6 routing table, you may need to increase +this value to ensure efficient routing table performance and fast lookups. +```{cfgcmd} set vpp settings resource-allocation ipv6 heap-size \<value\> +``` + +This parameter configures the heap size used for IPv6 forwarding. If you +have a large IPv6 routing table, you may need to increase this value to +ensure the routing table can accommodate all routes. + +## Potential Issues and Troubleshooting + +Improper IPv6 configuration can lead to various issues, including: + +- Inefficient, slow routing table lookups and traffic processing due to + insufficient hash buckets +- Dataplane crashes or instability due to insufficient heap size when + handling a large number of IPv6 routes +- Overall dataplane instability when handling IPv6 traffic + +Consider increasing configuration values if you experience issues with +IPv6 traffic processing or if you have a large IPv6 routing table. diff --git a/docs/vpp/configuration/dataplane/md-l2learn.md b/docs/vpp/configuration/dataplane/md-l2learn.md new file mode 100644 index 00000000..fe5deb55 --- /dev/null +++ b/docs/vpp/configuration/dataplane/md-l2learn.md @@ -0,0 +1,32 @@ +--- +lastproofread: '2026-02-26' +--- + +(vpp-config-dataplane-l2learn)= + +```{include} /_include/need_improvement.txt +``` +# VPP L2LEARN Configuration + +When VPP dataplane connects to an L2 domain, it learns MAC addresses of +devices in the domain. By default, the number of MAC addresses it can +learn is limited. + +You can configure the limit using the following command: +```{cfgcmd} set vpp settings resource-allocation mac-limit \<value\> +``` +This parameter sets the maximum number of MAC addresses that can be +learned in the L2 domain. If you have many devices, you may need to +increase this limit to ensure VPP learns all MAC addresses. + +## Potential Issues and Troubleshooting + +Improper L2LEARN configuration can lead to various issues, including: + +- MAC address learning failure in the L2 domain if the limit is set too + low +- Increased packet loss or latency for devices that aren't learned +- Overall dataplane instability when handling L2 traffic + +Consider increasing the L2LEARN limit if you experience issues with MAC +address learning or if you have many devices in the L2 domain. diff --git a/docs/vpp/configuration/dataplane/md-lcp.md b/docs/vpp/configuration/dataplane/md-lcp.md new file mode 100644 index 00000000..8ffdb7fb --- /dev/null +++ b/docs/vpp/configuration/dataplane/md-lcp.md @@ -0,0 +1,46 @@ +--- +lastproofread: '2026-02-26' +--- + +(vpp-config-dataplane-lcp)= + +```{include} /_include/need_improvement.txt +``` + +# VPP LCP Configuration +Linux Control Plane (LCP) is a core component of VPP that lets you +offload various control plane functions to the Linux kernel. LCP provides +seamless integration with other VyOS components, letting you use system +components like DHCP clients and routing daemons together with the VPP +dataplane. + +VPP integration in VyOS relies heavily on LCP. Almost all control plane +functions are handled by other daemons and services, while VPP handles +high-performance packet forwarding exclusively. This approach also reduces +VPP management processing load, improving overall dataplane performance and +stability. + +VyOS integrates the kernel and VPP routing tables uniquely. By default, +all routes, even those not directly connected to VPP interfaces, are +imported from the kernel routing table to the VPP routing table, pointing +to the kernel. This lets you forward traffic to any destination known to +the kernel, even if VPP doesn't have a route to that destination. + +However, in some scenarios this behavior may not be desired. For example, +if you have many routes in the kernel routing table not directly connected +to VPP interfaces, and you don't need forwarding between those +destinations and destinations reachable via VPP, you can disable this +behavior using the following command: +(vpp-config-dataplane-lcp-ignore-kernel-routes)= +```{cfgcmd} set vpp settings ignore-kernel-routes +``` + +Pay attention that disabling this option leads to loss of connectivity to +destinations if there are no direct routes in VPP routing table. + +## Potential Issues and Troubleshooting + +Disabling kernel route import can result in: + +- Loss of connectivity to certain destinations if kernel routes are ignored +- Incomplete route synchronization between the kernel and VPP diff --git a/docs/vpp/configuration/dataplane/md-logging.md b/docs/vpp/configuration/dataplane/md-logging.md new file mode 100644 index 00000000..e7fcf455 --- /dev/null +++ b/docs/vpp/configuration/dataplane/md-logging.md @@ -0,0 +1,56 @@ +--- +lastproofread: '2026-02-27' +--- + +(vpp-config-dataplane-logging)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Logging Configuration +VPP logging is an important part of monitoring and troubleshooting +the performance and behavior of the VPP dataplane. + +VPP stores logs in two places: +- `/var/log/vpp.log` — This file contains logs related to daemon + startup and logs of commands executed directly via VPP CLI. Pay + attention: VyOS does not use VPP CLI for configuration, so this log + will not contain any configuration changes made via VyOS CLI and will + not be informative in most cases. +- System journal — contains logs related to the VPP daemon work, + including errors, warnings, and informational messages. It is the + main destination of logs generated by VPP. + +Logging detail level can be configured via the next command: +```{cfgcmd} set vpp settings logging default-level \<level\> +``` + +Where `<level>` can be one of the following: + +- `emerg` (Emergency) - System is unusable. +- `alert` (Alert) - Immediate action required. +- `crit` (Critical) - Critical conditions. +- `error` (Error) - Error conditions. +- `warn` (Warning) - Warning conditions. +- `notice` (Notice) - Normal but significant. +- `info` (Informational) - Routine informational messages. +- `debug` (Debug) - Detailed debugging messages. +- `disabled` (Disabled) - Logging disabled. + +It is recommended to set logging level to `debug` only for +troubleshooting purposes, as it can generate a large volume of log +data. For regular operation, a level of `info` or `warn` is usually +sufficient. + +## Troubleshooting + +Improper logging configuration can lead to various issues, including: + +- Excessive log file sizes if the logging level is set too high + (for example, `debug`). +- Missing critical information if the logging level is set too low + (for example, `alert`). +- Performance degradation due to excessive logging overhead + +Consider adjusting the logging level if you experience issues mentioned +above. diff --git a/docs/vpp/configuration/dataplane/md-memory.md b/docs/vpp/configuration/dataplane/md-memory.md new file mode 100644 index 00000000..4e9d653d --- /dev/null +++ b/docs/vpp/configuration/dataplane/md-memory.md @@ -0,0 +1,127 @@ +--- +lastproofread: '2026-02-27' +--- + +(vpp-config-dataplane-memory)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Memory Configuration +VPP heavily relies on hugepages for its memory management. Hugepages +are larger memory pages that reduce the overhead of page management and +improve performance for applications that require large amounts of +memory, such as VPP. + +VPP supports both 2MB and 1GB hugepages, but the default and most +commonly used size is 2MB. The choice of hugepage size can impact +performance, with larger pages generally providing better performance +for memory-intensive applications. + +Before configuring memory in VPP dataplane settings, you need to +ensure that hugepages are enabled and properly configured on your +system. + +:::{seealso} +{ref}`Hugepages in VyOS Configuration for VPP <vpp-config-hugepages>` +::: +To configure memory settings for VPP, you can use the following +commands in the VPP CLI: + +VPP uses a main heap as a central memory pool for FIB data structures +entry allocations. + +Efficient memory management is crucial for VPP's performance, and the +main heap plays a significant role in this. + +It can be configured using the following command: +```{cfgcmd} set vpp settings resource-allocation memory main-heap-page-size \<size\> +``` +Sets the main heap page size for VPP. +```{cfgcmd} set vpp settings resource-allocation memory main-heap-size \<size\> +``` +Sets the main heap size for VPP. +(vpp-config-dataplane-physmem)= + +## Physical Memory Configuration +VPP uses physical memory for packet buffers and interface operations. +The `physmem` setting controls how much memory VPP can allocate for +these operations. +```{cfgcmd} set vpp settings resource-allocation memory physmem-max-size \<size\> +``` +Sets the maximum amount of physical memory VPP can use for packet +processing and interface buffers. + +**Default**: 16GB (usually sufficient for most deployments) + +You may need to modify the value for high-throughput environments with +many interfaces, large packet buffers, very high packet rates, or +memory-constrained systems where you need to limit VPP's memory usage. + +**Physmem independent of main heap size** — physmem is for packet +buffers, main heap is for routing tables. + +:::{seealso} +- {ref}`Hugepages in VyOS Configuration for VPP <vpp-config-hugepages>` +- {ref}`VPP Buffer Configuration <vpp-config-dataplane-buffers>` - for + controlling buffer allocation within physmem +::: + +### Common configurations +```none +# Reduce for memory-constrained systems +set vpp settings physmem max-size 4G + +# Increase for high-throughput environments +set vpp settings physmem max-size 32G +``` +## Stats Memory Configuration +VPP uses a dedicated statistics memory segment to store runtime +counters and telemetry data. This segment is used by the VPP CLI and +monitoring tools to access performance and status information. + +The statistics segment is allocated from hugepage memory and can be +configured independently from the main heap and physmem settings. + +You can configure statistics memory using the following commands: +```{cfgcmd} set vpp settings resource-allocation memory stats page-size \<size\> +``` +Sets the hugepage page size used for the statistics memory segment. +```{cfgcmd} set vpp settings resource-allocation memory stats size \<size\> +``` + +Sets the total size of the statistics memory segment. + +Increasing this value may be required in large deployments with many +interfaces or enabled features that generate a high number of counters. + +Statistics memory is used only for telemetry and monitoring. It does +not affect packet buffer allocation or routing table memory. + +## Troubleshooting + +Improper configuration of main heap size can lead to performance +degradation or even system instability. If VPP runs out of memory in the +main heap, it may crash or exhibit erratic behavior. Symptoms you may +observe include: + +- Increased latency or packet loss +- Crashes or restarts of VPP processes, especially during routing table + population (for example, BGP session establishment) +- Error messages related to memory allocation failures + +You need to tune the main heap size based on expected FIB entries. Pay +attention: the same amount of routes with a single next-hop and with +multiple next-hops will consume different amounts of memory. + +For physmem, insufficient allocation can lead to packet drops, interface +initialization failures, and overall degraded performance. Symptoms +include: + +- Packet drops or failures to allocate buffers +- Increased latency or jitter in packet processing +- Crashes or restarts of VPP processes under heavy load + +You need to tune the physmem settings based on expected traffic patterns +and interface usage. Monitor memory usage closely and adjust the +configuration as needed to ensure optimal performance. diff --git a/docs/vpp/configuration/dataplane/md-unix.md b/docs/vpp/configuration/dataplane/md-unix.md new file mode 100644 index 00000000..ba89d650 --- /dev/null +++ b/docs/vpp/configuration/dataplane/md-unix.md @@ -0,0 +1,54 @@ +--- +lastproofread: '2026-02-27' +--- + +(vpp-config-dataplane-unix)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Unix Dataplane Configuration +The UNIX configuration section is used to control VPP's interaction +with the underlying operating system, including operations scheduling. + +VPP relies on the polling mechanism to efficiently manage I/O operations +and system events. By default VPP continuously polls for events, which +leads to permanent 100% CPU usage by all cores assigned to VPP dataplane. +This is optimal for performance, but may not be desirable in all +environments, especially where power consumption is a concern or where VPP +is running inside a hypervisor, especially if the VM has burstable +thresholds and CPU usage limits. + +To mitigate this, VPP provides a configurable polling delay that allows +reducing CPU usage by introducing a delay between polling cycles. This +introduces a trade-off between CPU usage and latency, as longer delays +can lead to increased latency in processing events. + +You can configure the polling delay using the following command in the +VyOS CLI: +```{cfgcmd} set vpp settings poll-sleep-usec \<delay\> +``` + +Sets the polling delay in microseconds. A value of 0 means no delay +(default), while higher values introduce a delay between polling cycles. + +## Troubleshooting + +Setting the polling delay too high can lead to increased latency and +reduced performance, as VPP may not respond to events as quickly. +Conversely, setting it too low may result in high CPU usage, which can be +problematic in resource-constrained environments. + +Symptoms of improper configuration may include: + +- Increased latency in packet processing +- Higher CPU usage than expected +- Packets lost due to buffer overruns + +If you do not need to reduce CPU usage, it is recommended to leave the +polling delay at its default value of 0 for optimal performance. + +If you need to reduce CPU usage, you may also consider using `interrupt` or +`adaptive` {ref}`DPDK driver modes <vpp_config_dataplane_interface_rx_mode>`, +which can provide a balance between performance and resource utilization +without affecting polling behavior. diff --git a/docs/vpp/configuration/interfaces/md-bonding.md b/docs/vpp/configuration/interfaces/md-bonding.md new file mode 100644 index 00000000..24868166 --- /dev/null +++ b/docs/vpp/configuration/interfaces/md-bonding.md @@ -0,0 +1,206 @@ +--- +lastproofread: '2026-03-09' +--- + +(vpp-config-interfaces-bonding)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Bonding Configuration +VPP bonding interfaces provide link aggregation capabilities by combining +multiple physical interfaces into a single logical interface for increased +bandwidth and redundancy. VPP bonding offers high-performance packet +processing compared to traditional Linux bonding. + +## Basic Configuration + +### Creating a Bonding Interface +To create a VPP bonding interface: +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> + +Create a bonding interface where ``<vppbondN>`` follows the naming +convention ``vppbond0``, ``vppbond1``, and so on. A kernel pair interface is +automatically created for the VPP bonding interface. This allows +standard Linux networking tools and services to interact with the VPP +bond. +``` +**Example:** +```none +set interfaces vpp bonding vppbond0 +``` +### Interface Description +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> description \<description\> + +Set a descriptive name for the bonding interface. +``` +**Example:** +```none +set interfaces vpp bonding vppbond0 description "Primary uplink bond" +``` +### Administrative Control +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> disable + +Administratively disable the bonding interface. By default, interfaces +are enabled. +``` +## Member Interface Configuration +### Adding Member Interfaces +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> member interface \<interface-name\> + +Add physical interfaces as members of the bond. You can add multiple +interfaces to the same bond. +``` +**Example:** +```none +set interfaces vpp bonding vppbond0 member interface eth0 +set interfaces vpp bonding vppbond0 member interface eth1 +``` +:::{note} +Member interfaces must have the same speed and duplex for optimal +performance. They must already be attached to VPP. +::: + +## Bonding Modes +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> mode \<mode\> + +Configure the bonding mode. Available modes: +* **802.3ad**: IEEE 802.3ad Dynamic Link Aggregation (LACP) - Default +* **active-backup**: Fault tolerant, only one slave interface active +* **broadcast**: Transmits everything on all slave interfaces +* **round-robin**: Load balance by transmitting packets in sequential order +* **xor-hash**: Distribute based on hash policy +``` +**Examples:** +```none +# Use LACP (recommended for switch environments) +set interfaces vpp bonding vppbond0 mode 802.3ad + +# Use active-backup for simple failover +set interfaces vpp bonding vppbond0 mode active-backup +``` +## Hash Policies +For load balancing modes, configure how the system distributes traffic +across member interfaces: +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> hash-policy \<policy\> + +Set the transmit hash policy: +* **layer2**: Use MAC addresses to generate hash (default) +* **layer2+3**: Combine MAC addresses and IP addresses +* **layer3+4**: Combine IP addresses and port numbers +``` +**Examples:** +```none +# Layer 2 hashing (default) +set interfaces vpp bonding vppbond0 hash-policy layer2 + +# Layer 3+4 for better distribution with multiple flows +set interfaces vpp bonding vppbond0 hash-policy layer3+4 +``` +## MAC Address Configuration +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> mac \<mac-address\> + +Set a specific MAC address for the bonding interface. +``` +**Example:** +```none +set interfaces vpp bonding vppbond0 mac 00:11:22:33:44:55 +``` +## IP Address Configuration +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> address \<ip-address/prefix\> + +Configure IPv4 or IPv6 addresses on the kernel interface. You can +assign multiple addresses. +``` +**Examples:** +```none +# IPv4 address +set interfaces vpp bonding vppbond0 address 192.168.1.10/24 + +# IPv6 address +set interfaces vpp bonding vppbond0 address 2001:db8::10/64 + +# Multiple addresses +set interfaces vpp bonding vppbond0 address 192.168.1.10/24 +set interfaces vpp bonding vppbond0 address 10.0.0.10/8 +``` +## MTU Configuration +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> mtu \<size\> + +Set the Maximum Transmission Unit (MTU) for the kernel interface. The +MTU must be compatible with the connected VPP interface. +``` +**Example:** +```none +set interfaces vpp bonding vppbond0 mtu 9000 +``` +:::{note} +The MTU setting must match or be smaller than the MTU supported by the +associated VPP interface. +::: + +## VLAN Configuration +VPP kernel interfaces support VLAN (Virtual LAN) sub-interfaces for +network segmentation. + +### Creating VLAN Sub-interfaces +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> + +Create a VLAN sub-interface with the specified VLAN ID (0-4094). +``` +**Example:** +```none +set interfaces vpp bonding vppbond0 vif 100 +``` +### VLAN Sub-interface Configuration +VLAN sub-interfaces support the same configuration options as the parent +interface: +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> address \<ip-address/prefix\> +``` + +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> description \<description\> +``` + +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> disable +``` + +```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> mtu \<size\> +``` +**Examples:** +```none +# Configure VLAN 100 +set interfaces vpp bonding vppbond0 vif 100 address 192.168.100.1/24 +set interfaces vpp bonding vppbond0 vif 100 description "Management VLAN" +set interfaces vpp bonding vppbond0 vif 100 mtu 1500 + +# Configure VLAN 200 +set interfaces vpp bonding vppbond0 vif 200 address 192.168.200.1/24 +set interfaces vpp bonding vppbond0 vif 200 description "Guest VLAN" +``` +## Complete Configuration Example +Here's a complete example configuring a bonding interface with LACP: +```none +# Create bonding interface +set interfaces vpp bonding vppbond0 +set interfaces vpp bonding vppbond0 description "Server uplink bond" + +# Configure bonding parameters +set interfaces vpp bonding vppbond0 mode 802.3ad +set interfaces vpp bonding vppbond0 hash-policy layer3+4 + +# Add member interfaces +set interfaces vpp bonding vppbond0 member interface eth0 +set interfaces vpp bonding vppbond0 member interface eth1 + +# Configure IP on kernel interface +set interfaces vpp bonding vppbond0 address 192.168.1.10/24 +``` + +## Best Practices + +- Use **802.3ad mode** with LACP-capable switches for best performance + and standards compliance. +- Configure **layer3+4 hash policy** for environments with multiple + traffic flows. +- Ensure member interfaces have identical settings (speed, duplex, + MTU). diff --git a/docs/vpp/configuration/interfaces/md-bridge.md b/docs/vpp/configuration/interfaces/md-bridge.md new file mode 100644 index 00000000..f7b24b1d --- /dev/null +++ b/docs/vpp/configuration/interfaces/md-bridge.md @@ -0,0 +1,169 @@ +--- +lastproofread: '2026-03-10' +--- + +(vpp-config-interfaces-bridge)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Bridge Configuration +VPP bridge interfaces provide Layer 2 switching functionality, allowing +multiple interfaces to be connected at the data link layer. + +VPP bridges operate as learning bridges, automatically discovering MAC +addresses and building forwarding tables to efficiently switch traffic +between member interfaces. This provides transparent connectivity between +different network segments while maintaining the performance benefits of +VPP's optimized data plane. + +**Supported Member Interface Types:** + +VPP bridges support various interface types as members: +- Physical Ethernet interfaces (managed through linux-cp) +- {doc}`bonding` - VPP bonding interfaces +- {doc}`gre` - GRE tunnel interfaces +- {doc}`loopback` - Loopback interfaces (required for BVI) +- {doc}`vxlan` - VXLAN tunnel interfaces + +This flexibility allows you to create complex Layer 2 topologies +combining different networking technologies. + +## Basic Configuration + +### Creating a Bridge Interface +```{cfgcmd} set interfaces vpp bridge \<vppbrN\> + +Create a bridge interface where ``<vppbrN>`` follows the naming +convention ``vppbr1``, ``vppbr2``, etc. +``` +:::{note} +Bridge domain `vppbr0` is reserved by VPP and cannot be +configured through VyOS. Start with `vppbr1` for your bridge +configurations. +::: +**Example:** +```none +set interfaces vpp bridge vppbr1 +``` +### Interface Description +```{cfgcmd} set interfaces vpp bridge \<vppbrN\> description \<description\> + +Set a descriptive name for the bridge interface. +``` +**Example:** +```none +set interfaces vpp bridge vppbr1 description "Main campus bridge" +``` +## Member Interface Configuration +### Adding Member Interfaces +```{cfgcmd} set interfaces vpp bridge \<vppbrN\> member interface \<interface-name\> + +Add an interface as a member of the bridge. +``` +**Examples:** +```none +# Add physical interfaces +set interfaces vpp bridge vppbr1 member interface eth0 +set interfaces vpp bridge vppbr1 member interface eth1 + +# Add other VPP interfaces +set interfaces vpp bridge vppbr1 member interface vppbond0 +set interfaces vpp bridge vppbr1 member interface vppgre1 +``` +:::{important} +Bridge members can include various interface types such as: +- Physical Ethernet interfaces (eth0, eth1, etc.) +- {doc}`bonding` - VPP bonding interfaces (vppbond0, vppbond1, etc.) +- {doc}`gre` - GRE tunnel interfaces +- {doc}`loopback` - Loopback interfaces +- {doc}`vxlan` - VXLAN tunnel interfaces +::: + +## Bridge Virtual Interface (BVI) +A Bridge Virtual Interface (BVI) provides Layer 3 connectivity to a +bridge domain, allowing the bridge to have an IP address and participate +in routing. + +### Configuring BVI +```{cfgcmd} set interfaces vpp bridge \<vppbrN\> member interface \<loopback-interface\> bvi + +Designate a loopback interface as the Bridge Virtual Interface for +the bridge domain. +``` +**Example:** +```none +# Create a loopback interface first +set interfaces vpp loopback vpplo1 + +# Add it to the bridge as BVI +set interfaces vpp bridge vppbr1 member interface vpplo1 bvi +``` +:::{important} +**BVI Restrictions:** +- Only loopback interfaces can be configured as BVI +- Each bridge domain can have only one BVI interface +::: + +## Configuration Examples + +### Basic Bridge Setup +```none +# Create bridge interface +set interfaces vpp bridge vppbr1 +set interfaces vpp bridge vppbr1 description "Office network bridge" + +# Add member interfaces +set interfaces vpp bridge vppbr1 member interface eth0 +set interfaces vpp bridge vppbr1 member interface eth1 +set interfaces vpp bridge vppbr1 member interface eth2 +``` +### Bridge with BVI +```none +# Create bridge and loopback for BVI +set interfaces vpp bridge vppbr2 +set interfaces vpp bridge vppbr2 description "Server segment with gateway" +set interfaces vpp loopback vpplo1 + +# Configure bridge members +set interfaces vpp bridge vppbr2 member interface eth3 +set interfaces vpp bridge vppbr2 member interface eth4 +set interfaces vpp bridge vppbr2 member interface vpplo1 bvi +``` +### Multi-Technology Bridge +```none +# Create bridge combining different interface types +set interfaces vpp bridge vppbr3 +set interfaces vpp bridge vppbr3 description "Hybrid network bridge" + +# Add various interface types +set interfaces vpp bridge vppbr3 member interface vppbond1 +set interfaces vpp bridge vppbr3 member interface vppgre1 +set interfaces vpp bridge vppbr3 member interface vppvxlan1 +set interfaces vpp bridge vppbr3 member interface vpplo2 bvi +``` +## Integration with Kernel Interfaces +Bridge interfaces can be integrated with kernel interfaces for +management and compatibility with standard Linux networking services. +This is accomplished by binding a kernel interface to the Bridge +Virtual Interface (BVI). + +**Example Integration:** +```none +# Create VPP bridge with member interfaces +set interfaces vpp bridge vppbr1 +set interfaces vpp bridge vppbr1 member interface eth1 +set interfaces vpp bridge vppbr1 member interface eth2 + +# Create loopback interface and configure as BVI +set interfaces vpp loopback vpplo1 +set interfaces vpp bridge vppbr1 member interface vpplo1 bvi + +# Bind LCP kernel interface to the BVI loopback +set interfaces vpp loopback vpplo1 address '192.0.2.1/24' +``` + +This configuration creates a kernel interface bound to the BVI, +allowing standard Linux applications and routing daemons to interact +with the VPP bridge. The kernel interface provides Layer 3 access to +the bridge domain. diff --git a/docs/vpp/configuration/interfaces/md-gre.md b/docs/vpp/configuration/interfaces/md-gre.md new file mode 100644 index 00000000..fa91caae --- /dev/null +++ b/docs/vpp/configuration/interfaces/md-gre.md @@ -0,0 +1,140 @@ +--- +lastproofread: '2026-03-13' +--- + +(vpp-config-interfaces-gre)= + +```{include} /_include/need_improvement.txt +``` + +# VPP GRE Configuration +VPP GRE interfaces provide Generic Routing Encapsulation tunneling with +high-performance packet processing. GRE tunnels encapsulate various +protocols within IP packets, enabling connectivity across Layer 3 +networks while maintaining the performance benefits of VPP's optimized +data plane. + +## Basic Configuration + +### Creating a GRE Interface +```{cfgcmd} set interfaces vpp gre \<vppgreN\> + +Create a GRE interface where ``<vppgreN>`` follows the naming convention +``vppgre1``, ``vppgre2``, etc. +``` + +```{cfgcmd} set interfaces vpp gre \<vppgreN\> remote \<address\> + +Set the tunnel remote endpoint address. Supports both IPv4 and IPv6 +addresses. +``` + +```{cfgcmd} set interfaces vpp gre \<vppgreN\> source-address \<address\> + +Set the tunnel source address. Must match an address configured on +the local system. +``` +**Basic Example:** +```none +set interfaces vpp gre vppgre1 +set interfaces vpp gre vppgre1 remote 203.0.113.2 +set interfaces vpp gre vppgre1 source-address 192.168.1.1 +``` +## Interface Configuration +### Description and Administrative Control +```{cfgcmd} set interfaces vpp gre \<vppgreN\> description \<description\> + +Set a descriptive name for the GRE interface. +``` + +```{cfgcmd} set interfaces vpp gre \<vppgreN\> disable + +Administratively disable the GRE interface. +``` +### Tunnel Type +```{cfgcmd} set interfaces vpp gre \<vppgreN\> tunnel-type \<type\> + +Set the GRE tunnel encapsulation type: +* ``l3`` - Generic Routing Encapsulation for network layer traffic (default). +* ``teb`` - Transparent Ethernet Bridge for Layer 2 frame transport. +* ``erspan`` - Encapsulated Remote Switched Port Analyzer for traffic + mirroring. +``` +### Kernel Interface Integration +LCP kernel pair interface bound to the VPP GRE interface is created +automatically. This allows standard Linux networking tools and +services to interact with the VPP GRE. + +## IP Address Configuration +```{cfgcmd} set interfaces vpp gre \<vppgreN\> address \<ip-address/prefix\> + +Configure IPv4 or IPv6 addresses on the kernel interface. Multiple +addresses can be assigned. +``` +**Examples:** +```none +# IPv4 address +set interfaces vpp gre vppgre0 address 192.168.1.10/24 + +# IPv6 address +set interfaces vpp gre vppgre0 address 2001:db8::10/64 +``` +## MTU Configuration +```{cfgcmd} set interfaces vpp gre \<vppgreN\> mtu \<size\> + +Set the Maximum Transmission Unit (MTU) for the kernel interface. +The MTU must be compatible with the connected VPP interface. +``` +**Example:** +```none +set interfaces vpp gre vppgre0 mtu 9000 +``` +:::{note} +The MTU size must not exceed the MTU size +supported by the associated VPP interface. +::: + +## Configuration Examples + +### Layer 3 GRE Tunnel +```none +# IPv4 GRE tunnel +set interfaces vpp gre vppgre1 +set interfaces vpp gre vppgre1 description "Site-to-site tunnel" +set interfaces vpp gre vppgre1 remote 203.0.113.10 +set interfaces vpp gre vppgre1 source-address 192.168.1.1 +set interfaces vpp gre vppgre1 tunnel-type l3 +``` +### Layer 2 GRE Tunnel (TEB) +```none +# Transparent Ethernet Bridge +set interfaces vpp gre vppgre2 +set interfaces vpp gre vppgre2 description "L2 extension tunnel" +set interfaces vpp gre vppgre2 remote 203.0.113.20 +set interfaces vpp gre vppgre2 source-address 192.168.1.1 +set interfaces vpp gre vppgre2 tunnel-type teb +``` +### IPv6 GRE Tunnel +```none +# IPv6 endpoints +set interfaces vpp gre vppgre3 +set interfaces vpp gre vppgre3 remote 2001:db8::2 +set interfaces vpp gre vppgre3 source-address 2001:db8::1 +``` +### GRE with Kernel Interface +```none +# GRE tunnel with management interface +set interfaces vpp gre vppgre4 +set interfaces vpp gre vppgre4 remote 203.0.113.30 +set interfaces vpp gre vppgre4 source-address 192.168.1.1 +set interfaces vpp gre vppgre4 address 10.0.1.1/30 +``` +## Bridge Integration +GRE interfaces can be added as members to VPP bridges for Layer 2 +switching. See {doc}`bridge` for detailed bridge configuration. +```none +# Add TEB GRE tunnel to bridge +set interfaces vpp bridge vppbr1 +set interfaces vpp bridge vppbr1 member interface vppgre2 +set interfaces vpp bridge vppbr1 member interface eth1 +``` diff --git a/docs/vpp/configuration/interfaces/md-index.md b/docs/vpp/configuration/interfaces/md-index.md new file mode 100644 index 00000000..662f37c5 --- /dev/null +++ b/docs/vpp/configuration/interfaces/md-index.md @@ -0,0 +1,47 @@ +--- +lastproofread: '2026-03-13' +--- + +(vpp-config-interfaces-index)= + +```{include} /_include/need_improvement.txt +``` +# VPP Interfaces Configuration +```{toctree} +:includehidden: true +:maxdepth: 1 + +bonding +bridge +gre +ipip +loopback +vxlan +xconnect +``` + +VyOS utilizes VPP (Vector Packet Processor) to provide high-performance data +plane processing. While physical interfaces are typically managed through the +Linux kernel using `linux-cp` (Linux Control Plane) integration, VyOS also +supports creating dedicated VPP interfaces for enhanced flexibility and +performance. + +## Why VPP Interfaces? + +VPP interfaces offer several advantages: + +- **Total Isolation**: VPP interfaces operate entirely within the VPP data + plane, providing isolation from the Linux kernel when needed. +- **Advanced Features**: Access to VPP-specific functionality not available + in standard Linux interfaces. +- **Flexible Deployment**: Some interface types are only available as VPP + interfaces or may not be supported by the kernel. +- **Specific scenarios**: Not all use cases require integration with the + Linux Kernel. + +### Integration with Kernel + +VyOS provides seamless integration between VPP and kernel networking. +This allows you to leverage the strengths of both approaches: +create interfaces inside VPP, and access them from the Linux kernel and other +services. diff --git a/docs/vpp/configuration/interfaces/md-ipip.md b/docs/vpp/configuration/interfaces/md-ipip.md new file mode 100644 index 00000000..8a847e48 --- /dev/null +++ b/docs/vpp/configuration/interfaces/md-ipip.md @@ -0,0 +1,99 @@ +--- +lastproofread: '2026-03-13' +--- + +(vpp-config-interfaces-ipip)= + +```{include} /_include/need_improvement.txt +``` + +# VPP IPIP Configuration +VPP IPIP interfaces provide IP-in-IP tunneling with high-performance +packet processing. IPIP tunnels encapsulate IP packets within IP +packets, creating point-to-point connections across Layer 3 networks. + +## Basic Configuration + +### Creating an IPIP Interface +```{cfgcmd} set interfaces vpp ipip \<vppipipN\> + +Create an IPIP interface where ``<vppipipN>`` follows the naming +convention ``vppipip1``, ``vppipip2``, etc. +``` + +```{cfgcmd} set interfaces vpp ipip \<vppipipN\> remote \<address\> + +Set the tunnel remote endpoint address. Supports both IPv4 and IPv6 +addresses. +``` + +```{cfgcmd} set interfaces vpp ipip \<vppipipN\> source-address \<address\> + +Set the tunnel source address. The source address must match an address +configured on the local system. +``` +**Basic Example:** +```none +set interfaces vpp ipip vppipip1 +set interfaces vpp ipip vppipip1 remote 203.0.113.2 +set interfaces vpp ipip vppipip1 source-address 192.168.1.1 +``` +## Interface Configuration +### Description and Administrative Control +```{cfgcmd} set interfaces vpp ipip \<vppipipN\> description \<description\> + +Set a descriptive name for the IPIP interface. +``` + +```{cfgcmd} set interfaces vpp ipip \<vppipipN\> disable + +Administratively disable the IPIP interface. +``` +### Kernel Interface Integration +Kernel interface is bound to the VPP IPIP interface for management and +application compatibility. + +## IP Address Configuration +```{cfgcmd} set interfaces vpp ipip \<vppipipN\> address \<ip-address/prefix\> + +Configure IPv4 or IPv6 addresses on the kernel interface. Multiple +addresses can be assigned. +``` +**Examples:** +```none +# IPv4 address +set interfaces vpp ipip vppipip0 address 192.168.1.10/24 + +# IPv6 address +set interfaces vpp ipip vppipip0 address 2001:db8::10/64 +``` +## MTU Configuration +```{cfgcmd} set interfaces vpp ipip \<vppipipN\> mtu \<size\> + +Set the Maximum Transmission Unit (MTU) for the kernel interface. +The MTU must be compatible with the connected VPP interface. +``` +## Configuration Examples +### IPv4 IPIP Tunnel +```none +# Basic IPv4 IPIP tunnel +set interfaces vpp ipip vppipip1 +set interfaces vpp ipip vppipip1 description "Site-to-site IPIP tunnel" +set interfaces vpp ipip vppipip1 remote 203.0.113.10 +set interfaces vpp ipip vppipip1 source-address 192.168.1.1 +``` +### IPv6 IPIP Tunnel +```none +# IPv6 endpoints +set interfaces vpp ipip vppipip2 +set interfaces vpp ipip vppipip2 remote 2001:db8::2 +set interfaces vpp ipip vppipip2 source-address 2001:db8::1 +``` +### IPIP with Kernel Interface +```none +# IPIP tunnel with management interface +set interfaces vpp ipip vppipip3 +set interfaces vpp ipip vppipip3 remote 203.0.113.30 +set interfaces vpp ipip vppipip3 source-address 192.168.1.1 +set interfaces vpp ipip vppipip3 address 10.0.2.1/30 +``` diff --git a/docs/vpp/configuration/interfaces/md-loopback.md b/docs/vpp/configuration/interfaces/md-loopback.md new file mode 100644 index 00000000..bc65338b --- /dev/null +++ b/docs/vpp/configuration/interfaces/md-loopback.md @@ -0,0 +1,120 @@ +--- +lastproofread: '2026-03-13' +--- + +(vpp-config-interfaces-loopback)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Loopback Interface Configuration +VPP loopback interfaces provide virtual interfaces that remain +administratively up and are commonly used for stable addressing, +routing protocols, and as Bridge Virtual Interfaces (BVI). Loopback +interfaces in VPP offer high-performance virtual connectivity with optimized +packet processing. + +## Basic Configuration + +### Creating a Loopback Interface +```{cfgcmd} set interfaces vpp loopback \<vpploN\> + +Create a loopback interface where ``<vpploN>`` follows the naming +convention ``vpplo1``, ``vpplo2``, etc. +``` +**Basic Example:** +```none +set interfaces vpp loopback vpplo1 +``` +## Interface Configuration +### Description and Administrative Control +```{cfgcmd} set interfaces vpp loopback \<vpploN\> description \<description\> + +Set a descriptive name for the loopback interface. +``` + +```{cfgcmd} set interfaces vpp loopback \<vpploN\> disable + +Administratively disable the loopback interface. +``` +### Kernel Interface Integration +Kernel interface is bounded to the VPP loopback interface for management +and application compatibility. + +## IP Address Configuration +```{cfgcmd} set interfaces vpp loopback \<vpploN\> address \<ip-address/prefix\> + +Configure IPv4 or IPv6 addresses on the kernel interface. Multiple +addresses can be assigned. +``` +**Examples:** +```none +# IPv4 address +set interfaces vpp loopback vpplo1 address 192.168.1.10/24 + +# IPv6 address +set interfaces vpp loopback vpplo1 address 2001:db8::10/64 +``` +## MTU Configuration +```{cfgcmd} set interfaces vpp loopback \<vpploN\> mtu \<size\> + +Set the Maximum Transmission Unit (MTU) for the kernel interface. +The MTU must be compatible with the connected VPP interface. +``` +## VLAN Configuration +VPP kernel interfaces support VLAN (Virtual LAN) sub-interfaces for network +segmentation. + +### Creating VLAN Sub-interfaces +```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> + +Create a VLAN sub-interface with the specified VLAN ID (0-4094). +``` +### VLAN Sub-interface Configuration +VLAN sub-interfaces support the same configuration options as the parent +interface: +```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> address \<ip-address/prefix\> +``` + +```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> description \<description\> +``` + +```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> disable +``` + +```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> mtu \<size\> +``` +**Examples:** +```none +# Configure VLAN 100 +set interfaces vpp loopback vpplo1 vif 100 address 192.168.100.1/24 +set interfaces vpp loopback vpplo1 vif 100 description "Management VLAN" +set interfaces vpp loopback vpplo1 vif 100 mtu 1500 + +# Configure VLAN 200 +set interfaces vpp loopback vpplo1 vif 200 address 192.168.200.1/24 +set interfaces vpp loopback vpplo1 vif 200 description "Guest VLAN" +``` +## Configuration Examples +### Basic Loopback Interface +```none +# Create simple loopback +set interfaces vpp loopback vpplo1 +set interfaces vpp loopback vpplo1 description "Router ID interface" +``` +### Loopback with Kernel Interface +```none +# Loopback with management access +set interfaces vpp loopback vpplo2 +set interfaces vpp loopback vpplo2 description "Management loopback" +set interfaces vpp loopback vpplo2 address 10.255.255.1/32 +``` +### Bridge Virtual Interface (BVI) +```none +# Loopback as BVI for bridge +set interfaces vpp loopback vpplo3 +set interfaces vpp loopback vpplo3 description "Bridge gateway interface" +set interfaces vpp bridge vppbr1 +set interfaces vpp bridge vppbr1 member interface vpplo3 bvi +set interfaces vpp loopback vpplo3 address 192.168.100.1/24 +``` diff --git a/docs/vpp/configuration/interfaces/md-vxlan.md b/docs/vpp/configuration/interfaces/md-vxlan.md new file mode 100644 index 00000000..6fa1322a --- /dev/null +++ b/docs/vpp/configuration/interfaces/md-vxlan.md @@ -0,0 +1,132 @@ +--- +lastproofread: '2026-03-13' +--- + +(vpp-config-interfaces-vxlan)= + +```{include} /_include/need_improvement.txt +``` + +# VPP VXLAN Configuration +VPP VXLAN interfaces provide virtual extensible local area network (VXLAN) +tunneling with high-performance packet processing. VXLAN extends Layer 2 +domains across Layer 3 networks using UDP encapsulation, enabling scalable +multi-tenant networking while leveraging VPP's optimized data plane. + +## Basic Configuration + +### Creating a VXLAN Interface +```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> + +Create a VXLAN interface where ``<vppvxlanN>`` follows the naming +convention ``vppvxlan1``, ``vppvxlan2``, etc. +``` + +```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> vni \<vni\> + +Set the Virtual Network Identifier (VNI) for the VXLAN tunnel. Valid range +is 0-16777214. +``` + +```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> remote \<address\> + +Set the tunnel remote endpoint address. Supports both IPv4 and IPv6 +addresses. +``` + +```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> source-address \<address\> + +Set the tunnel source address. Must match an address configured on the +local system. +``` +**Basic Example:** +```none +set interfaces vpp vxlan vppvxlan1 +set interfaces vpp vxlan vppvxlan1 vni 100 +set interfaces vpp vxlan vppvxlan1 remote 203.0.113.2 +set interfaces vpp vxlan vppvxlan1 source-address 192.168.1.1 +``` +## Interface Configuration +### Description and Administrative Control +```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> description \<description\> + +Set a descriptive name for the VXLAN interface. +``` + +```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> disable + +Administratively disable the VXLAN interface. +``` +### Kernel Interface Integration +The kernel interface is bound to the VXLAN tunnel for management and +application compatibility. + +## IP Address Configuration +```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> address \<ip-address/prefix\> + +Configure IPv4 or IPv6 addresses on the kernel interface. Multiple +addresses can be assigned. +``` +**Examples:** +```none +set interfaces vpp vxlan vppvxlan1 address 192.168.1.10/24 +set interfaces vpp vxlan vppvxlan1 address 2001:db8::10/64 +``` +## MTU Configuration +```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> mtu \<size\> + +Set the Maximum Transmission Unit (MTU) for the kernel interface. The MTU +must be compatible with the connected VPP interface. +``` +## Configuration Examples +### Basic VXLAN Tunnel +```none +# IPv4 VXLAN tunnel +set interfaces vpp vxlan vppvxlan1 +set interfaces vpp vxlan vppvxlan1 description "Tenant A network extension" +set interfaces vpp vxlan vppvxlan1 vni 1000 +set interfaces vpp vxlan vppvxlan1 remote 203.0.113.10 +set interfaces vpp vxlan vppvxlan1 source-address 192.168.1.1 +``` +### IPv6 VXLAN Tunnel +```none +# IPv6 endpoints +set interfaces vpp vxlan vppvxlan2 +set interfaces vpp vxlan vppvxlan2 vni 2000 +set interfaces vpp vxlan vppvxlan2 remote 2001:db8::2 +set interfaces vpp vxlan vppvxlan2 source-address 2001:db8::1 +``` +### VXLAN with Kernel Interface +```none +# VXLAN tunnel with management interface +set interfaces vpp vxlan vppvxlan3 +set interfaces vpp vxlan vppvxlan3 vni 3000 +set interfaces vpp vxlan vppvxlan3 remote 203.0.113.30 +set interfaces vpp vxlan vppvxlan3 source-address 192.168.1.1 +set interfaces vpp vxlan vppvxlan3 address 10.0.3.1/24 +``` +## Bridge Integration +VXLAN interfaces are commonly used as members in VPP bridges for Layer 2 +extension. See {doc}`bridge` for more information. +```none +# Add VXLAN tunnel to bridge +set interfaces vpp bridge vppbr1 +set interfaces vpp bridge vppbr1 member interface vppvxlan1 +set interfaces vpp bridge vppbr1 member interface eth1 +set interfaces vpp bridge vppbr1 member interface vpplo1 bvi +``` +### Multi-Tenant Configuration +```none +# Multiple VNIs for tenant separation +set interfaces vpp vxlan vppvxlan10 +set interfaces vpp vxlan vppvxlan10 description "Tenant A - Production" +set interfaces vpp vxlan vppvxlan10 vni 1001 +set interfaces vpp vxlan vppvxlan10 remote 203.0.113.20 +set interfaces vpp vxlan vppvxlan10 source-address 192.168.1.1 + +set interfaces vpp vxlan vppvxlan11 +set interfaces vpp vxlan vppvxlan11 description "Tenant A - Development" +set interfaces vpp vxlan vppvxlan11 vni 1002 +set interfaces vpp vxlan vppvxlan11 remote 203.0.113.21 +set interfaces vpp vxlan vppvxlan11 source-address 192.168.1.1 +``` diff --git a/docs/vpp/configuration/interfaces/md-xconnect.md b/docs/vpp/configuration/interfaces/md-xconnect.md new file mode 100644 index 00000000..0ee052d2 --- /dev/null +++ b/docs/vpp/configuration/interfaces/md-xconnect.md @@ -0,0 +1,94 @@ +--- +lastproofread: '2026-03-13' +--- + +(vpp-config-interfaces-xconnect)= + +```{include} /_include/need_improvement.txt +``` + +# VPP XConnect Configuration +VPP XConnect provides direct Layer 2 packet forwarding between two +interfaces with maximum transparency and minimal overhead. XConnect +creates a simple point-to-point bridge that forwards all Layer 2 packets +bidirectionally without MAC learning or flooding, making it ideal for +transparent connectivity scenarios. + +XConnect operates as a super-transparent bridge, forwarding all frames +between the connected interfaces without any packet inspection or +modification. This provides the simplest possible Layer 2 forwarding with +VPP's high-performance packet processing. + +## Comparison with Bridges +- **XConnect**: Point-to-point only, no MAC learning, maximum + transparency, minimal overhead +- **Bridge**: Multi-port, MAC learning, broadcast handling, more + features but higher overhead + +Choose XConnect when you need simple point-to-point Layer 2 forwarding +with maximum performance and transparency. Use bridges when you need +multi-port switching with MAC learning and broadcast handling. + +## Basic Configuration + +### Creating an XConnect Interface +```{cfgcmd} set interfaces vpp xconnect \<vppxconN\> + +Create an XConnect interface where ``<vppxconN>`` follows the naming +convention ``vppxcon1``, ``vppxcon2``, etc. +``` + +```{cfgcmd} set interfaces vpp xconnect \<vppxconN\> member interface \<interface-name\> + +Add an interface as a member of the XConnect. Exactly two member +interfaces must be configured to create bidirectional forwarding. +``` +**Basic Example:** +```none +set interfaces vpp xconnect vppxcon1 +set interfaces vpp xconnect vppxcon1 member interface eth0 +set interfaces vpp xconnect vppxcon1 member interface eth1 +``` +This configuration creates transparent forwarding between `eth0` and `eth1`, +where any packet received on either interface is immediately forwarded to +the other without any processing. + +## Interface Configuration +```{cfgcmd} set interfaces vpp xconnect \<vppxconN\> description \<description\> + +Set a descriptive name for the XConnect interface. +``` +## Configuration Examples +### Physical Interface XConnect +```none +# Connect two physical interfaces +set interfaces vpp xconnect vppxcon1 +set interfaces vpp xconnect vppxcon1 description "Transparent wire between ports" +set interfaces vpp xconnect vppxcon1 member interface eth0 +set interfaces vpp xconnect vppxcon1 member interface eth1 +``` +This creates a transparent wire between two physical ports, effectively +making them function as a single cable. + +### Tunnel to Physical XConnect +```none +# Connect tunnel to physical interface +set interfaces vpp xconnect vppxcon2 +set interfaces vpp xconnect vppxcon2 description "GRE tunnel to physical bridge" +set interfaces vpp xconnect vppxcon2 member interface vppgre1 +set interfaces vpp xconnect vppxcon2 member interface eth2 +``` +This forwards all traffic from a GRE tunnel directly to a physical +interface and vice versa. + +### Mixed Interface Types +```none +# Connect different interface types +set interfaces vpp xconnect vppxcon3 +set interfaces vpp xconnect vppxcon3 description "VXLAN to bonding bridge" +set interfaces vpp xconnect vppxcon3 member interface vppvxlan1 +set interfaces vpp xconnect vppxcon3 member interface vppbond0 +``` + +This demonstrates XConnect's flexibility in connecting various VPP interface +types. diff --git a/docs/vpp/configuration/md-acl.md b/docs/vpp/configuration/md-acl.md new file mode 100644 index 00000000..59b96070 --- /dev/null +++ b/docs/vpp/configuration/md-acl.md @@ -0,0 +1,485 @@ +--- +lastproofread: '2025-09-04' +--- + +(vpp-config-acl)= + +```{include} /_include/need_improvement.txt +``` + +# VPP ACL Configuration +VPP ACLs (Access Control Lists) provide a way to filter traffic passing through VPP interfaces. They offer a high-performance packet filtering solution that can be used as a fast firewall alternative. + +VyOS VPP ACL implementation supports two main types of access control lists: +- **IP ACLs** - Layer 3 filtering based on IPv4/IPv6 addresses, ports, and protocols (can be applied to both input and output directions) +- **MAC ACLs** - Layer 2 filtering based on MAC addresses and IP prefixes (can only be applied to input direction) + +## Structure and Components + +### Tags +ACL tags are named rule sets that contain one or more access control entries (ACEs). Tags provide a way to group related rules and apply them consistently across different interfaces. +- Tag names are user-defined text strings +- Each tag can contain multiple numbered rules +- Tags can be applied to interfaces in input or output direction +- Multiple tags can be applied to a single interface + +### Interface Application +ACL tags are applied to interfaces to control traffic flow: +- **Input direction**: Filters traffic entering the interface +- **Output direction**: Filters traffic leaving the interface + +:::{note} +**Important Limitation**: MAC ACLs can only be applied to the input direction of interfaces. They cannot filter outbound traffic. Use IP ACLs if you need to filter traffic in both directions. +::: + +### Rule Processing +Rules within an ACL are processed in numerical order (lowest to highest). The first matching rule determines the action taken on the packet. + +Available actions: +- `permit` - Allow the packet to continue +- `deny` - Drop the packet +- `permit-reflect` - Allow traffic and automatically permit return traffic + +## L3/IP ACLs +IP ACLs provide Layer 3 filtering capabilities based on IPv4 and IPv6 addresses, port numbers, and protocols. They support both stateless and stateful (reflexive) filtering. + +### Creating IP ACL Tags +IP ACL tags are created under the `vpp acl ip` configuration node: +```none +set vpp acl ip tag-name <tag-name> +set vpp acl ip tag-name <tag-name> description '<description>' +``` +Example: +```none +set vpp acl ip tag-name 'WEB-FILTER' +set vpp acl ip tag-name 'WEB-FILTER' description 'Web server access control' +``` +### Adding Rules to IP ACL Tags +Rules are added to IP ACL tags with specific rule numbers: +```none +set vpp acl ip tag-name <tag-name> rule <rule-number> +``` +#### Basic IP ACL Rule Configuration +Each rule requires an action and matching criteria: +```none +set vpp acl ip tag-name <tag-name> rule <rule-number> action <permit|deny|permit-reflect> +set vpp acl ip tag-name <tag-name> rule <rule-number> description '<description>' +set vpp acl ip tag-name <tag-name> rule <rule-number> protocol <protocol> +``` +**Actions:** +- `permit` - Allow matching traffic +- `deny` - Block matching traffic +- `permit-reflect` - Allow outbound traffic and automatically permit return traffic + +**Protocols:** +- `all` - Match all IP protocols (default) +- Or specific protocol by name, e.g. `tcp`, `udp`, `icmp` + +#### Source and Destination Matching +Configure source and destination parameters: +```none +# Source configuration +set vpp acl ip tag-name <tag-name> rule <rule-number> source prefix <ip-prefix> +set vpp acl ip tag-name <tag-name> rule <rule-number> source port <port-spec> + +# Destination configuration +set vpp acl ip tag-name <tag-name> rule <rule-number> destination prefix <ip-prefix> +set vpp acl ip tag-name <tag-name> rule <rule-number> destination port <port-spec> +``` +**Prefix Specification:** +- `<x.x.x.x/x>` - IPv4 prefix in CIDR notation +- `<h:h:h:h:h:h:h:h/x>` - IPv6 prefix in CIDR notation + +**Port Specification:** +- `<1-65535>` - Single port number +- `<start>-<end>` - Port range (e.g., 1001-1005) + +#### TCP Flags Matching +For TCP protocol rules, you can match specific TCP flags: +```none +# Match packets with specific flags set +set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags is-set <ack|cwr|ecn|fin|psh|rst|syn|urg> + +# Match packets without specific flags set +set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags is-not-set <ack|cwr|ecn|fin|psh|rst|syn|urg> +``` +### IP ACL Configuration Examples +#### Example 1: Basic Web Server ACL +```none +# Create ACL for web server access +set vpp acl ip tag-name 'WEB-SERVER' +set vpp acl ip tag-name 'WEB-SERVER' description 'Web server access control' + +# Allow HTTP traffic +set vpp acl ip tag-name 'WEB-SERVER' rule 10 action permit +set vpp acl ip tag-name 'WEB-SERVER' rule 10 protocol tcp +set vpp acl ip tag-name 'WEB-SERVER' rule 10 destination port 80 + +# Allow HTTPS traffic +set vpp acl ip tag-name 'WEB-SERVER' rule 20 action permit +set vpp acl ip tag-name 'WEB-SERVER' rule 20 protocol tcp +set vpp acl ip tag-name 'WEB-SERVER' rule 20 destination port 443 + +# Deny all other traffic +set vpp acl ip tag-name 'WEB-SERVER' rule 999 action deny +set vpp acl ip tag-name 'WEB-SERVER' rule 999 protocol all +``` +#### Example 2: Network Segmentation ACL +```none +# Create ACL for network segmentation +set vpp acl ip tag-name 'DMZ-FILTER' +set vpp acl ip tag-name 'DMZ-FILTER' description 'DMZ to internal network filter' + +# Allow specific internal subnet access +set vpp acl ip tag-name 'DMZ-FILTER' rule 10 action permit +set vpp acl ip tag-name 'DMZ-FILTER' rule 10 destination prefix '192.168.100.0/24' +set vpp acl ip tag-name 'DMZ-FILTER' rule 10 protocol tcp +set vpp acl ip tag-name 'DMZ-FILTER' rule 10 destination port 443 + +# Allow DNS queries +set vpp acl ip tag-name 'DMZ-FILTER' rule 20 action permit +set vpp acl ip tag-name 'DMZ-FILTER' rule 20 destination prefix '192.168.1.10/32' +set vpp acl ip tag-name 'DMZ-FILTER' rule 20 protocol udp +set vpp acl ip tag-name 'DMZ-FILTER' rule 20 destination port 53 + +# Block everything else to internal networks +set vpp acl ip tag-name 'DMZ-FILTER' rule 100 action deny +set vpp acl ip tag-name 'DMZ-FILTER' rule 100 destination prefix '192.168.0.0/16' +``` +#### Example 3: Reflexive ACL +```none +# Create reflexive ACL for outbound connections +set vpp acl ip tag-name 'OUTBOUND-REFLECT' +set vpp acl ip tag-name 'OUTBOUND-REFLECT' description 'Allow outbound with return traffic' + +# Allow outbound HTTP/HTTPS with return traffic +set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 10 action permit-reflect +set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 10 protocol tcp +set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 10 destination port 80 + +set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 20 action permit-reflect +set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 20 protocol tcp +set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 20 destination port 443 +``` +### Applying IP ACL Tags to Interfaces +IP ACL tags are applied to interfaces using the interface configuration: +```none +# Apply to input direction +set vpp acl ip interface <interface> input acl-tag <number> tag-name <tag-name> + +# Apply to output direction +set vpp acl ip interface <interface> output acl-tag <number> tag-name <tag-name> +``` +Where: +- `<interface>` - Interface name (e.g., eth0, eth1) +- `<number>` - ACL rule number (0-4294967295) for ordering multiple ACL tags +- `<tag-name>` - Name of the ACL tag to apply + +Multiple tags can be applied to the same interface and direction by using different ACL rule numbers. + +Example: +```none +# Apply web server ACL to input direction +set vpp acl ip interface eth0 input acl-tag 10 tag-name 'WEB-SERVER' + +# Apply outbound reflexive ACL to output direction +set vpp acl ip interface eth1 output acl-tag 10 tag-name 'OUTBOUND-REFLECT' + +# Apply multiple ACLs to the same interface and direction +set vpp acl ip interface eth0 input acl-tag 20 tag-name 'FIREWALL' +``` +## L2/MAC ACLs +MAC ACLs provide Layer 2 filtering capabilities based on MAC addresses and IP prefixes. They are particularly useful for controlling access at the data link layer. + +:::{important} +**Direction Limitation**: MAC ACLs can **only** be applied to the **input direction** of interfaces. They cannot filter outbound/output traffic. If you need bidirectional filtering, use IP ACLs instead. +::: + +### Creating MAC ACL Tags +MAC ACL tags are created under the `vpp acl mac` configuration node: +```none +set vpp acl mac tag-name <tag-name> +set vpp acl mac tag-name <tag-name> description '<description>' +``` +Example: +```none +set vpp acl mac tag-name 'MAC-FILTER' +set vpp acl mac tag-name 'MAC-FILTER' description 'Layer 2 MAC address filtering' +``` +### Adding Rules to MAC ACL Tags +Rules are added to MAC ACL tags with specific rule numbers: +```none +set vpp acl mac tag-name <tag-name> rule <rule-number> +``` +#### Basic MAC ACL Rule Configuration +Each rule requires an action and matching criteria: +```none +set vpp acl mac tag-name <tag-name> rule <rule-number> action <permit|deny> +set vpp acl mac tag-name <tag-name> rule <rule-number> description '<description>' +``` +**Actions:** +- `permit` - Allow matching traffic +- `deny` - Block matching traffic + +Note: MAC ACLs do not support the `permit-reflect` action available in IP ACLs. + +#### MAC Address Matching +Configure MAC address matching criteria: +```none +set vpp acl mac tag-name <tag-name> rule <rule-number> mac-address <mac-address> +set vpp acl mac tag-name <tag-name> rule <rule-number> mac-mask <mac-mask> +``` +**MAC Address Specification:** +- `mac-address` - Source MAC address to match (format: xx:xx:xx:xx:xx:xx) +- `mac-mask` - MAC address mask (default: ff:ff:ff:ff:ff:ff for exact match) + +The MAC mask allows for partial MAC address matching. For example: +\- `ff:ff:ff:00:00:00` matches the first 3 octets (OUI) +\- `ff:ff:ff:ff:ff:ff` matches the complete MAC address (default) + +#### IP Prefix Matching +Configure IP prefix matching for the source: +```none +set vpp acl mac tag-name <tag-name> rule <rule-number> prefix <ip-prefix> +``` +**Prefix Specification:** +- Supports both IPv4 and IPv6 prefixes in CIDR notation +- Examples: `192.168.1.0/24`, `10.0.0.0/8`, `2001:db8::/32` + +### MAC ACL Configuration Examples + +#### Example 1: Device Whitelist +```none +# Create MAC ACL for device whitelisting +set vpp acl mac tag-name 'DEVICE-WHITELIST' +set vpp acl mac tag-name 'DEVICE-WHITELIST' description 'Allow only approved devices' + +# Allow specific workstation +set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 action permit +set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 mac-address '00:1b:21:12:34:56' +set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 prefix '192.168.1.100/32' +set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 description 'Admin workstation' + +# Allow specific server +set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 action permit +set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 mac-address '00:1b:21:78:90:ab' +set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 prefix '192.168.1.10/32' +set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 description 'Web server' + +# Deny everything else +set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 999 action deny +set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 999 mac-address '00:00:00:00:00:00' +set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 999 mac-mask '00:00:00:00:00:00' +``` +#### Example 2: Vendor-Based Filtering +```none +# Create MAC ACL for vendor-based filtering +set vpp acl mac tag-name 'VENDOR-FILTER' +set vpp acl mac tag-name 'VENDOR-FILTER' description 'Filter by MAC vendor OUI' + +# Deny Realtek devices (OUI: 00:e0:4c) +set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 action deny +set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 mac-address '00:e0:4c:00:00:00' +set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 mac-mask 'ff:ff:ff:00:00:00' +set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 description 'Block Realtek devices' + +# Allow all other devices +set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 action permit +set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 mac-address '00:00:00:00:00:00' +set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 mac-mask '00:00:00:00:00:00' +set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 description 'Allow all other vendors' +``` +#### Example 3: Network Segmentation by MAC +```none +# Create MAC ACL for network segmentation +set vpp acl mac tag-name 'SEGMENT-FILTER' +set vpp acl mac tag-name 'SEGMENT-FILTER' description 'Segment networks by MAC/IP binding' + +# Allow management VLAN devices +set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 action permit +set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 mac-address '02:01:00:00:00:00' +set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 mac-mask 'ff:ff:00:00:00:00' +set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 prefix '10.1.0.0/16' +set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 description 'Management VLAN' + +# Allow user VLAN devices +set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 action permit +set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 mac-address '02:02:00:00:00:00' +set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 mac-mask 'ff:ff:00:00:00:00' +set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 prefix '10.2.0.0/16' +set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 description 'User VLAN' +``` +### Applying MAC ACL Tags to Interfaces +MAC ACL tags can only be applied to the input direction of interfaces: +```none +set vpp acl mac interface <interface> tag-name <tag-name> +``` +:::{note} +**Syntax Difference**: Unlike IP ACLs, MAC ACL interface application does not use the `acl-tag <number>` structure since only single MAC ACLs can be applied. +::: + +:::{warning} +Unlike IP ACLs, MAC ACLs do **not** support output direction filtering. There is no `output` option available for MAC ACL interface application. +::: +Example: +```none +# Apply MAC filtering to interface input +set vpp acl mac interface eth0 tag-name 'MAC-FILTER' +set vpp acl mac interface eth1 tag-name 'DEVICE-WHITELIST' +``` +## Configuration Best Practices + +### Rule Ordering +- **Number rules strategically**: Use gaps between rule numbers (10, 20, 30) to allow for future insertions +- **Place specific rules first**: More specific matches should have lower rule numbers +- **End with catch-all**: Always include a final rule that matches all traffic with explicit action +- **Document rules**: Use descriptions for complex rules to aid troubleshooting + +### Performance Considerations +- **Minimize rule count**: Fewer rules generally mean better performance +- **Use appropriate ACL type**: Use MAC ACLs for Layer 2/3 filtering, IP ACLs for Layer 3/4 filtering +- **Consider direction limitations**: Remember that MAC ACLs only work on input traffic; use IP ACLs for filtering in both directions +- **Combine related rules**: Group similar filtering requirements into single ACL tags +- **Apply strategically**: Apply ACLs at ingress points where possible to minimize processing + +## Troubleshooting + +### Common Issues +- **ACL not taking effect:** + - Verify ACL is applied to correct interface and direction + - Check rule numbering and order + - Ensure interface is properly configured in VPP +- **Performance degradation:** + - Review ACL complexity and rule count + - Consider consolidating rules + - Check for unnecessary broad matches +- **Traffic blocked unexpectedly:** + - Review rule order (first match wins) + - Check for overly restrictive rules + - Verify protocol and port specifications + +### Verification Commands +Use these commands to verify ACL configuration and operation: +```none +# Show VPP ACL configuration +show configuration commands | grep "vpp acl" + +# Show VPP interface configuration +show configuration commands | grep "vpp acl.*interface" + +# View commit history for ACL changes +show configuration commit-revisions | grep -A5 -B5 "vpp acl" +``` +## Operational Commands +VyOS provides several operational commands to monitor and troubleshoot VPP ACL configurations and their status. + +### Viewing All ACLs +Display all configured ACLs (both IP and MAC): +```{opcmd} show vpp acl +``` +This command shows a summary of all configured ACL tags with their rules, displaying both IP ACLs and MAC ACLs in a tabular format. +Example output: +```none +--------------------------------- +IP ACL "tag-name WEB-SERVER" acl_index 0 + +Rule Action Src prefix Src port Dst prefix Dst port Proto TCP flags set TCP flags not set +------ -------- ------------ ---------- ------------ ---------- ------- --------------- ------------------- + 10 permit 0.0.0.0/0 0-65535 0.0.0.0/0 80 6 + 20 permit 0.0.0.0/0 0-65535 0.0.0.0/0 443 6 + 999 deny 0.0.0.0/0 0-65535 0.0.0.0/0 0-65535 0 + +--------------------------------- +MACIP ACL "tag-name VENDOR-FILTER" acl_index 0 + +Rule Action IP prefix MAC address MAC mask +------ -------- ----------- ----------------- ----------------- + 10 deny 0.0.0.0/0 00:e0:4c:00:00:00 ff:ff:ff:00:00:00 + 100 permit 0.0.0.0/0 00:00:00:00:00:00 00:00:00:00:00:00 +``` +### IP ACL Commands +View all IP ACLs: +```{opcmd} show vpp acl ip +``` +View IP ACL interface assignments: +```{opcmd} show vpp acl ip interface +``` +Example output: +```none +Interface Input ACLs Output ACLs +----------- ------------ ------------- +eth1 WEB-SERVER +``` +View specific IP ACL by tag name: +```{opcmd} show vpp acl ip tag-name \<tag-name\> +``` +Example: +```none +vyos@vyos:~$ show vpp acl ip tag-name WEB-SERVER + +--------------------------------- +IP ACL "tag-name WEB-SERVER" acl_index 0 + + Rule Action Src prefix Src port Dst prefix Dst port Proto TCP flags set TCP flags not set +------ -------- ------------ ---------- ------------ ---------- ------- --------------- ------------------- + 10 permit 0.0.0.0/0 0-65535 0.0.0.0/0 80 6 + 20 permit 0.0.0.0/0 0-65535 0.0.0.0/0 443 6 + 999 deny 0.0.0.0/0 0-65535 0.0.0.0/0 0-65535 0 +``` +### MAC ACL Commands +View all MAC ACLs: +```{opcmd} show vpp acl mac +``` +View MAC ACL interface assignments: +```{opcmd} show vpp acl mac interface +``` +Example output: +```none +Interface ACL +----------- ----- +eth0 VENDOR-FILTER +``` +View specific MAC ACL by tag name: +```{opcmd} show vpp acl mac tag-name \<tag-name\> +``` +Example: +```none +vyos@vyos:~$ show vpp acl mac tag-name VENDOR-FILTER + +--------------------------------- +MACIP ACL "tag-name VENDOR-FILTER" acl_index 0 + + Rule Action IP prefix MAC address MAC mask +------ -------- ----------- ----------------- ----------------- + 10 deny 0.0.0.0/0 00:e0:4c:00:00:00 ff:ff:ff:00:00:00 + 100 permit 0.0.0.0/0 00:00:00:00:00:00 00:00:00:00:00:00 +``` + +### Understanding Command Output + +**IP ACL Output Fields:** + +- **Rule**: Rule number within the ACL +- **Action**: permit, deny, or permit-reflect +- **Src prefix**: Source IP prefix (0.0.0.0/0 = any source) +- **Src port**: Source port range (0-65535 = any port) +- **Dst prefix**: Destination IP prefix +- **Dst port**: Destination port or port range +- **Proto**: IP protocol number (6=TCP, 17=UDP, 1=ICMP, 0=any) +- **TCP flags set**: Required TCP flags (for TCP protocol) +- **TCP flags not set**: Prohibited TCP flags (for TCP protocol) + +**MAC ACL Output Fields:** + +- **Rule**: Rule number within the ACL +- **Action**: permit or deny +- **IP prefix**: Source IP prefix constraint +- **MAC address**: Source MAC address to match +- **MAC mask**: MAC address mask for partial matching + +**Interface Assignment Output:** + +- Shows which interfaces have ACLs applied +- **Input ACLs**: ACL tags applied to incoming traffic +- **Output ACLs**: ACL tags applied to outgoing traffic (IP ACLs only) +- **ACL**: MAC ACL tag applied to interface (input only) diff --git a/docs/vpp/configuration/md-index.md b/docs/vpp/configuration/md-index.md new file mode 100644 index 00000000..7e02ae74 --- /dev/null +++ b/docs/vpp/configuration/md-index.md @@ -0,0 +1,41 @@ +--- +lastproofread: '2025-09-04' +--- + +(vpp-dconfig-index)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Configuration +VPP settings consist of several main sections. + +Main Dataplane settings and internal VPP interfaces: +```{toctree} +:includehidden: true +:maxdepth: 1 + +dataplane/index +interfaces/index +``` +Features that can be enabled on VPP Dataplane: +```{toctree} +:includehidden: true +:maxdepth: 1 + +acl +ipfix +ipsec +nat/index +sflow +``` + +## VPP Initialization + +When VPP Dataplane is configured and the configuration is committed, VyOS will attempt to start VPP and initialize all interfaces assigned to it. During this process the following steps occur: + +1. VyOS checks that the system meets all requirements for VPP operation. If any requirement is not met, VPP will not start and an error message will be displayed. +2. VPP is started and its initial configuration is applied. +3. All interfaces assigned to VPP are initialized and brought up. +4. A special virtual interfaces are reinstalled to the kernel with the same names as interfaces that were attached to VPP to maintain compatibility with the configuration. +5. VyOS configuration initializes those virtual interfaces, so that features that exist only in kernel dataplane continue to operate. diff --git a/docs/vpp/configuration/md-ipfix.md b/docs/vpp/configuration/md-ipfix.md new file mode 100644 index 00000000..7ed2aee3 --- /dev/null +++ b/docs/vpp/configuration/md-ipfix.md @@ -0,0 +1,50 @@ +# VPP IPFIX Configuration + +VPP IPFIX in VyOS allows monitoring and exporting network traffic flows +for analytics, security, and accounting. IPFIX works with the VPP +(Vector Packet Processing) backend to provide high-performance flow tracking. + +## Overview + +VyOS integrates VPP for high-performance packet processing. IPFIX +configuration controls how flows are monitored, exported, and which +interfaces are included. + +## Key IPFIX Concepts + +- **Active timeout**: Maximum time a flow is kept active before export. +- **Inactive timeout**: Maximum time an idle flow is kept before export. +- **Collector**: The remote host and port to which flow records are sent. +- **Flow layers**: Determines which layer information is included + (`l2`, `l3`, `l4`). +- **Interfaces**: Physical or virtual interfaces to monitor. +- **Direction**: Which traffic to monitor (`rx`, `tx`, `both`). +- **Flow variant**: Optional filter for IPv4 or IPv6 flows. + +## Configuration Options + +- **active-timeout**: Duration (in seconds) after which active flows + are exported. +- **inactive-timeout**: Duration (in seconds) after which idle flows + are exported. +- **collector \`\<ip>\` port \`\<port>\`**: IP and UDP port of the IPFIX collector. +- **collector \`\<ip>\` source-address \`\<ip>\`**: Source address for flow export. +- **flowprobe-record \`\<l2|l3|l4>\`**: Layers to include in flow records. +- **interface** `<interface>` **\[direction** `<rx|tx|both>`**\]** + **\[flow-variant** `<ipv4|ipv6>`**\]**: Interfaces to monitor, + direction of traffic, and optional flow variant filter. + +## Example Configuration + +```none +set vpp ipfix active-timeout '15' +set vpp ipfix inactive-timeout '120' +set vpp ipfix collector 192.0.2.2 port '4739' +set vpp ipfix collector 192.0.2.2 source-address '192.0.2.1' +set vpp ipfix flowprobe-record 'l2' +set vpp ipfix flowprobe-record 'l3' +set vpp ipfix flowprobe-record 'l4' +set vpp ipfix interface eth0 +set vpp ipfix interface eth1 direction 'both' +set vpp ipfix interface eth1 flow-variant 'ipv4' +``` diff --git a/docs/vpp/configuration/md-sflow.md b/docs/vpp/configuration/md-sflow.md new file mode 100644 index 00000000..752b8377 --- /dev/null +++ b/docs/vpp/configuration/md-sflow.md @@ -0,0 +1,37 @@ +--- +lastproofread: '2025-09-04' +--- + +(vpp-config-sflow)= + +```{include} /_include/need_improvement.txt +``` + +# VPP sFlow Configuration +VPP Dataplane in VyOS support sFlow for traffic monitoring and analysis. + +The VPP Dataplane integration works hand-in-hand with normal kernel sFlow agent, which is responsible for collecting and exporting sFlow samples. VPP itself is responsible for generating the samples. + +To enable sFlow in VPP, you first need to configure the service using the same steps as for normal kernel sFlow agent, as described in {doc}`/configuration/system/sflow`. Then you can enable sFlow on VPP interfaces. + +Then, you need to enable sFlow on the VPP interfaces you want to monitor. This is done using the following commands: +```{cfgcmd} set vpp sflow interface \<interface-name\> +``` +This will enable sFlow on the specified interface. You can repeat this command for each interface you want to monitor. + +:::{note} +sFlow collects statistics only for traffic *received* on the interface. If you want to monitor traffic *sent* on the interface, you need to enable sFlow on the corresponding interface in the opposite direction. +::: +Optionally, you can specify the number of bytes from each packet that should be included in the sFlow sample using the following command: +```{cfgcmd} set vpp sflow header-bytes \<bytes\> +``` +This defines the size of the packet header (in bytes) captured for each sFlow sample. + +The sampling rate is configured globally under the `system sflow` section and automatically applied to VPP sFlow. +This ensures consistent sampling behavior between the system and VPP, and prevents configuration conflicts. + +Finally, you need to enable integration between VPP and the kernel sFlow agent using the following command: +```{cfgcmd} set system sflow vpp +``` + +After this, collecting and exporting sFlow samples will be handled by the kernel sFlow agent, while VPP will generate the samples. diff --git a/docs/vpp/configuration/nat/md-index.md b/docs/vpp/configuration/nat/md-index.md new file mode 100644 index 00000000..4d5c01d1 --- /dev/null +++ b/docs/vpp/configuration/nat/md-index.md @@ -0,0 +1,41 @@ +--- +lastproofread: '2026-03-05' +--- + +(vpp-config-nat-index)= + +```{include} /_include/need_improvement.txt + +``` +# VPP NAT Configuration + +```{toctree} +:includehidden: true +:maxdepth: 1 + +cgnat +nat44 +``` + +VPP Dataplane in VyOS supports two types of NAT: + +## NAT44 + +This type is a classic NAT implementation where you can configure static +and dynamic NAT rules. It supports both source and destination NAT. While the +configuration may look a bit unusual compared to traditional NAT +implementations, it provides flexibility in network configurations. + +## CGNAT + +CGNAT is a special type of NAT44, which is highly useful when you have +multiple local customers and a limited number of public IP addresses. It +shares the public IP address space fairly between customers by using a +combination of IP address and port number to distinguish between them. + +ISPs often use this NAT type to provide internet access to customers. + +It supports only source NAT. + +CGNAT also supports exclude rules (identity mappings) to bypass translation +for selected local addresses or protocol/port tuples. diff --git a/docs/vpp/configuration/nat/md-nat44.md b/docs/vpp/configuration/nat/md-nat44.md new file mode 100644 index 00000000..a0805ed3 --- /dev/null +++ b/docs/vpp/configuration/nat/md-nat44.md @@ -0,0 +1,653 @@ +--- +lastproofread: '2026-03-05' +--- + +(vpp-config-nat-nat44)= + +```{include} /_include/need_improvement.txt +``` + +# VPP NAT44 Configuration +NAT44 has two main use cases: +- **Source NAT (SNAT)**: Enabling internet access for hosts in private + networks using dynamic or static address translation. +- **Destination NAT (DNAT)**: Providing external access to internal services + through static port forwarding rules. + +VyOS supports both dynamic translation using address pools and static +mappings for predictable address translation requirements. + +Configuring NAT44 involves a few steps: +1. Define the inside and outside interfaces. +2. Create NAT rules for SNAT or DNAT. + +## Dynamic and Static Operations +NAT44 configuration can be done in one of two ways or in both ways +simultaneously: +1. Dynamically performing NAT using a pool of public IP addresses. +2. Statically mapping private IP addresses to public IP addresses. + +To configure dynamic NAT, you need to define a pool of public IP +addresses that will be used for translation. This offers an easy way to +provide internet access to internal users. + +Static rules are suitable for scenarios where you need consistent and +predictable mappings between private and public IP addresses. They are also +the only way to configure DNAT. + +### NAT Rule Processing and Traffic Flow +This section explains how different combinations of NAT rules affect +traffic handling on a router. There are three possible combinations of NAT +rule configurations: +1. **Dynamic NAT Only** + - **All** traffic received on the "in" interface is processed by + dynamic NAT rules without exceptions. +2. **Dynamic + Static NAT** + - **All** traffic received on the "in" interface is first matched + against static NAT rules. + - If no match is found, it is then processed against dynamic NAT rules. +3. **Static NAT Only** + - **All** traffic on the "in" interface is checked against static NAT + rules. + - If no match is found, the traffic is routed **without NAT**. + +:::{important} +- If **dynamic NAT rules** are present, **all** traffic received on + "in" interfaces is subject to NAT processing. +- If **only static NAT rules** are configured, traffic that does not + match any static rule is routed unchanged. +::: + +## Interfaces Configuration +The first step in configuring NAT44 is defining which interfaces handle +inside (private) and outside (public) traffic. VyOS uses these interface +designations to determine the direction of translation. + +### Inside Interfaces +Inside interfaces connect to private networks where hosts need source NAT +to access external networks. +```{cfgcmd} set vpp nat nat44 interface inside \<inside-interface\> +``` +Traffic flowing **from** inside interfaces gets source NAT applied, +translating private source addresses to public addresses from the +translation pool. + +### Outside Interfaces +Outside interfaces connect to public networks where external hosts may +need to access internal services. +```{cfgcmd} set vpp nat nat44 interface outside \<outside-interface\> +``` +Traffic flowing **to** outside interfaces can trigger destination NAT +based on static rules, allowing external access to internal services. + +### Interface Roles and Traffic Flow + +:::{note} +While VyOS uses "inside" and "outside" as established conventions, +the technical definitions are: +- **Inside interface**: Interface where traffic originates that needs + source NAT (SNAT) +- **Outside interface**: Interface where traffic originates that needs + destination NAT (DNAT) + +In complex network topologies, the same physical interface can be +configured as both inside and outside to handle bidirectional NAT +scenarios. +::: +**Traffic Processing:** +1. **Inside → Outside** (SNAT): Private hosts accessing external networks +2. **Outside → Inside** (DNAT): External hosts accessing internal services + via static rules +3. **Dynamic NAT**: Created automatically for inside→outside traffic +4. **Static NAT**: Requires explicit configuration for outside→inside + traffic + +### Multiple Interface Support +You can configure multiple interfaces as inside or outside to support +complex network topologies: +```none +# Multiple inside interfaces (different private networks) +set vpp nat nat44 interface inside eth0 +set vpp nat nat44 interface inside eth2 + +# Multiple outside interfaces (redundancy or load balancing) +set vpp nat nat44 interface outside eth1 +set vpp nat nat44 interface outside eth3 +``` +## Address Pool Configuration +Address pools define ranges of IP addresses that can be used for NAT +translations. VyOS NAT44 supports two types of address pools, each serving +different purposes. + +### Translation Pools +Translation pools are used for dynamic source NAT (SNAT). They provide a +range of public IP addresses that can be dynamically assigned to private +hosts when they access external networks. +```{cfgcmd} set vpp nat nat44 address-pool translation address \<ip-address | ip-address-range\> +``` + +```{cfgcmd} set vpp nat nat44 address-pool translation interface \<interface-name\> +``` +**Examples:** +```none +# Single address pool +set vpp nat nat44 address-pool translation address 203.0.113.10 + +# Address range pool +set vpp nat nat44 address-pool translation address 203.0.113.10-203.0.113.20 + +# Interface-based pool (use a first IP assigned to the interface) +set vpp nat nat44 address-pool translation interface eth1 +``` +### Twice-NAT Pools +Twice-NAT pools are used when performing both source and destination NAT on +the same traffic flow. This is particularly useful in scenarios where you +need to: +- Translate both source and destination addresses +- Provide access between networks with overlapping IP ranges +- Implement advanced NAT scenarios like self-twice-nat +```{cfgcmd} set vpp nat nat44 address-pool twice-nat address \<ip-address | ip-address-range\> +``` + +```{cfgcmd} set vpp nat nat44 address-pool twice-nat interface \<interface-name\> +``` +**Examples:** +```none +# Twice-NAT pool for advanced scenarios +set vpp nat nat44 address-pool twice-nat address 192.168.100.1-192.168.100.10 + +# Interface-based twice-nat pool +set vpp nat nat44 address-pool twice-nat interface eth2 +``` +### Pool Requirements + +:::{important} +- For dynamic NAT to work, you must configure at least one + **translation** pool. +- For static rules with twice-nat options, you must configure a + **twice-nat** pool. +- Interface-based pools automatically include main (first) IP address + assigned to the specified interface. +::: + +### Pool Selection Priority +When multiple pools are configured, VyOS uses the following selection +priority: +1. **Static mappings**: Always use the specific external address defined in + the rule. +2. **Dynamic NAT**: Use available addresses from translation pools in the + order they were configured. +3. **Twice-NAT**: Use addresses from twice-nat pools for secondary + translation. + +:::{note} +As soon as you have configured interfaces and pool, the NAT44 is +operational. +::: + +## Static Rules Configuration +Static NAT rules provide predictable and consistent mappings between private +and public IP addresses. They are essential for: +- **Destination NAT (DNAT)**: Allowing external hosts to access services in + the private network. +- **Server publishing**: Making internal services available from the + Internet. +- **Consistent mappings**: Ensuring the same private IP always maps to the + same public IP. + +Unlike dynamic NAT that uses a pool of addresses, static rules create +one-to-one mappings that persist until explicitly removed. + +### Basic Static Rule Configuration +To create a static NAT rule, you need to define the local (internal) and +external (public) address mappings: +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> local address \<internal-ip\> +``` + +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> external address \<external-ip\> +``` +Where: +- `<rule-number>` is a unique identifier for the rule +- `<internal-ip>` is the private IP address in your local network +- `<external-ip>` is the public IP address that external hosts will use + +This basic configuration creates a static one-to-one mapping. Traffic from +outside to the external IP will be translated to the internal IP, and vice +versa. + +### Port-based Static Rules +For more granular control, you can create port-specific static rules. This +is useful when you want to publish specific services: +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> local address \<internal-ip\> +``` + +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> local port \<internal-port\> +``` + +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> external address \<external-ip\> +``` + +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> external port \<external-port\> +``` + +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> protocol \<protocol\> +``` +Where: +- `<internal-port>` and `<external-port>` are the port numbers used by + the connection. +- `<protocol>` specifies the protocol (tcp, udp, icmp). + +:::{important} +If you do not specify ports and protocol, the rule will apply to *all* +traffic between the specified internal and external addresses. + +Rules must contain either both ports and protocol, or neither. +::: + +### Advanced Static Rule Options +VyOS NAT44 supports several advanced options for static rules: + +#### Twice-NAT +Twice-NAT performs both source and destination NAT. When an external host +accesses an internal service, the source IP of such a connection is +translated to an address from the twice-NAT address pool. + +This is practical in scenarios where internal services cannot connect to +public networks, so they see such traffic as internal. + +The twice-NAT option can be enabled with the following command: +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options twice-nat +``` +#### Self Twice-NAT +Self Twice-NAT is used when a local host needs to access itself via the +external address: +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options self-twice-nat +``` +This option rewrites source IP addresses on packets sent only from a local +address to an external address configured in a rule. + +:::{important} +- Using `self-twice-nat` option requires you to set the interface + connected to the local network as both inside and outside, because + both source and destination NAT need to be applied. +- External IP address used in static rules must belong to one of the + configured translation pools. +::: + +#### Out-to-In Only +Restricts the rule to only apply to traffic from outside to inside +interfaces: +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options out-to-in-only +``` +This prevents the creation of sessions from the inside interface, making it +a purely DNAT rule. + +#### Force Twice-NAT Address +When using twice-nat, you can force the use of a specific IP address from +the twice-nat address pool: +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options twice-nat-address \<ip-address\> +``` +#### Rule Description +To document your rules, you can add a description: +```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> description \<description\> +``` +### Static Rules Configuration Examples +**Full one-to-one NAT mapping:** +```none +set vpp nat nat44 static rule 100 local address 192.168.1.10 +set vpp nat nat44 static rule 100 external address 203.0.113.10 +set vpp nat nat44 static rule 100 description "One-to-one mapping" +``` +**Port-specific SSH access:** +```none +set vpp nat nat44 static rule 200 local address 192.168.1.20 +set vpp nat nat44 static rule 200 local port 22 +set vpp nat nat44 static rule 200 external address 203.0.113.10 +set vpp nat nat44 static rule 200 external port 2222 +set vpp nat nat44 static rule 200 protocol tcp +set vpp nat nat44 static rule 200 description "SSH access to server" +``` +**Twice-NAT for local service access:** +```none +set vpp nat nat44 static rule 300 local address 192.168.1.30 +set vpp nat nat44 static rule 300 local port 80 +set vpp nat nat44 static rule 300 external address 203.0.113.10 +set vpp nat nat44 static rule 300 external port 80 +set vpp nat nat44 static rule 300 protocol tcp +set vpp nat nat44 static rule 300 options twice-nat +set vpp nat nat44 static rule 300 description "Web service with twice-nat" +``` +:::{note} +When using twice-nat or self-twice-nat options, ensure you have +configured a twice-nat address pool using: +```none +set vpp nat nat44 address-pool twice-nat address <twice-nat-ip-range> +``` +::: + +## Exclude Rules Configuration +Exclude rules allow you to prevent specific traffic from undergoing NAT +translation. This is particularly useful for: +- **Router management**: Allowing SSH access to the router itself from + external networks. +- **Service bypass**: Excluding specific services from NAT processing +- **Traffic forwarding**: Allowing forwarded traffic to bypass NAT with 1-to-1 + mapping. + +Exclude rules take precedence over both dynamic and static NAT rules, +ensuring that matching traffic bypasses NAT processing. For forwarded +traffic, exclude rules create invisible 1-to-1 mappings that allow packets +to pass through without NAT modifications. + +### Basic Exclude Rule Configuration +To create an exclude rule, you need to specify the traffic characteristics +that should bypass NAT. You can configure exclude rules in two ways: + +**Option 1: Using local address** +```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-address \<internal-ip\> +``` +**Option 2: Using external interface** +```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> external-interface \<interface-name\> +``` +Where: +- `<rule-number>` is a unique identifier for the exclude rule. +- `<internal-ip>` is the local IP address that should be excluded from + : NAT. +- `<interface-name>` is the external interface where the traffic + : originates. + +:::{important} +You must use either `local-address` OR `external-interface` in an +exclude rule, but not both simultaneously. These options are mutually +exclusive. +::: + +### Port-specific Exclude Rules +For more granular control, you can exclude only specific ports and protocols. +You can combine port and protocol specifications with either `local-address` or +`external-interface`: + +**With local address:** +```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-address \<internal-ip\> +``` + +```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-port \<port-number\> +``` + +```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> protocol \<protocol\> +``` +**With external interface:** +```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> external-interface \<interface-name\> +``` + +```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-port \<port-number\> +``` + +```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> protocol \<protocol\> +``` +Where: +- `<port-number>` is the specific port to exclude (1-65535) +- `<protocol>` can be `tcp`, `udp`, `icmp`, or `all` (default) + +### Rule Documentation +Add descriptions to your exclude rules for better management: +```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> description \<description\> +``` +### Exclude Rules Configuration Examples +**Exclude SSH access to router:** +```none +# Allow external SSH access to router without NAT +set vpp nat nat44 exclude rule 10 local-address 192.168.1.1 +set vpp nat nat44 exclude rule 10 local-port 22 +set vpp nat nat44 exclude rule 10 protocol tcp +set vpp nat nat44 exclude rule 10 description "SSH access to router" +``` +**Exclude SNMP monitoring:** +```none +# Allow SNMP monitoring without NAT translation +set vpp nat nat44 exclude rule 20 local-port 161 +set vpp nat nat44 exclude rule 20 protocol udp +set vpp nat nat44 exclude rule 20 external-interface eth1 +set vpp nat nat44 exclude rule 20 description "SNMP monitoring" +``` +**Exclude all traffic to router management interface:** +```none +# Exclude all traffic to router's management IP +set vpp nat nat44 exclude rule 30 local-address 192.168.100.1 +set vpp nat nat44 exclude rule 30 description "Management interface bypass" +``` +**Exclude all traffic from external interface:** +```none +# Exclude all traffic from external interface (alternative approach) +set vpp nat nat44 exclude rule 31 external-interface eth1 +set vpp nat nat44 exclude rule 31 description "External interface bypass" +``` +**Exclude forwarded traffic for specific service:** +```none +# Allow external access to internal server without NAT translation +set vpp nat nat44 exclude rule 40 local-address 192.168.1.50 +set vpp nat nat44 exclude rule 40 local-port 8080 +set vpp nat nat44 exclude rule 40 protocol tcp +set vpp nat nat44 exclude rule 40 description "Direct access to internal service" +``` +### Common Use Cases +**Router Administration:** + +Exclude rules are essential when you need to manage the router from external +networks. Without exclude rules, NAT would attempt to translate the router's +own traffic, potentially breaking management connections. + +**Service Monitoring:** + +Network monitoring systems often need direct access to router services. +Exclude rules ensure that monitoring traffic bypasses NAT translation. + +**Routing Protocols:** + +Some routing protocols or network services may require direct communication +without NAT interference. + +**Traffic Forwarding:** + +Exclude rules also work for forwarded traffic between networks. Without +exclude rules, traffic from external to local networks must either match a +static rule or be dropped. With exclude rules, traffic can bypass NAT +processing with invisible 1-to-1 mappings. + +:::{important} +Exclude rules affect both traffic destined for the router itself and +forwarded traffic flowing through the router. For forwarded traffic, exclude +rules create transparent 1-to-1 mappings that allow packets to pass without +NAT modifications, while from the outside perspective, the traffic appears to +bypass NAT entirely. +::: + +## Advanced NAT44 Settings +VyOS provides additional NAT44 settings for fine-tuning performance and +behavior. + +### Session Timeouts +NAT44 maintains translation sessions with configurable timeout values for +different protocols: +```{cfgcmd} set vpp nat nat44 timeout icmp \<seconds\> + +Set the timeout for ICMP sessions (Default: 60 seconds). +``` + +```{cfgcmd} set vpp nat nat44 timeout tcp-established \<seconds\> + +Set the timeout for established TCP connections (Default: 7440 seconds +or 2 hours 4 minutes). +``` + +```{cfgcmd} set vpp nat nat44 timeout tcp-transitory \<seconds\> + +Set the timeout for transitory TCP connections (setup/teardown) (Default: +240 seconds or 4 minutes). +``` + +```{cfgcmd} set vpp nat nat44 timeout udp \<seconds\> + +Set the timeout for UDP sessions (Default: 300 seconds or 5 minutes). +``` +**Example:** +```none +# Customize timeouts for high-traffic environment +set vpp nat nat44 timeout tcp-established 3600 +set vpp nat nat44 timeout udp 600 +set vpp nat nat44 timeout icmp 30 +``` +### Session Limits +Control the maximum number of concurrent NAT sessions: +```{cfgcmd} set vpp nat nat44 session-limit \<number\> + +Set the maximum number of NAT sessions per worker thread (Default: +64512). +``` +This setting helps prevent memory exhaustion and ensures predictable +performance under high load. + +**Example:** +```none +# Increase session limit for high-capacity deployment +set vpp nat nat44 session-limit 100000 +``` +## Complete Configuration Example +Here's a complete example showing how to configure VyOS NAT44 for a typical +network setup: + +**Network Topology:** +```none +Internet (203.0.113.0/24) + | +┌───────────────────┐ +│ eth1 (outside) │ 203.0.113.1/24 +│ VyOS Router │ +│ eth0 (inside) │ 192.168.1.1/24 +└───────────────────┘ + | +Internal Network (192.168.1.0/24) +├── 192.168.1.10 (Web Server) +├── 192.168.1.20 (SSH Server) +└── 192.168.1.30 (API Service) +``` +**Configuration:** +```none +# Configure interfaces +set vpp nat nat44 interface inside eth0 +set vpp nat nat44 interface outside eth1 + +# Configure address pools +set vpp nat nat44 address-pool translation address 203.0.113.10-203.0.113.50 +set vpp nat nat44 address-pool twice-nat address 203.0.113.100-203.0.113.110 + +# Exclude rules for router management +set vpp nat nat44 exclude rule 10 local-address 203.0.113.1 +set vpp nat nat44 exclude rule 10 local-port 22 +set vpp nat nat44 exclude rule 10 protocol tcp +set vpp nat nat44 exclude rule 10 description "SSH access to router" + +set vpp nat nat44 exclude rule 11 local-address 203.0.113.1 +set vpp nat nat44 exclude rule 11 local-port 443 +set vpp nat nat44 exclude rule 11 protocol tcp +set vpp nat nat44 exclude rule 11 description "HTTPS access to router web interface" + +# Static rule for web server (HTTP) +set vpp nat nat44 static rule 100 local address 192.168.1.10 +set vpp nat nat44 static rule 100 local port 80 +set vpp nat nat44 static rule 100 external address 203.0.113.10 +set vpp nat nat44 static rule 100 external port 80 +set vpp nat nat44 static rule 100 protocol tcp +set vpp nat nat44 static rule 100 description "Public web server" + +# Static rule for web server (HTTPS) +set vpp nat nat44 static rule 101 local address 192.168.1.10 +set vpp nat nat44 static rule 101 local port 443 +set vpp nat nat44 static rule 101 external address 203.0.113.10 +set vpp nat nat44 static rule 101 external port 443 +set vpp nat nat44 static rule 101 protocol tcp +set vpp nat nat44 static rule 101 description "Public web server HTTPS" + +# Static rule for SSH server with custom port +set vpp nat nat44 static rule 200 local address 192.168.1.20 +set vpp nat nat44 static rule 200 local port 22 +set vpp nat nat44 static rule 200 external address 203.0.113.11 +set vpp nat nat44 static rule 200 external port 2222 +set vpp nat nat44 static rule 200 protocol tcp +set vpp nat nat44 static rule 200 description "SSH access" + +# Static rule for API service (out-to-in only for security) +set vpp nat nat44 static rule 300 local address 192.168.1.30 +set vpp nat nat44 static rule 300 local port 8080 +set vpp nat nat44 static rule 300 external address 203.0.113.12 +set vpp nat nat44 static rule 300 external port 8080 +set vpp nat nat44 static rule 300 protocol tcp +set vpp nat nat44 static rule 300 options out-to-in-only +set vpp nat nat44 static rule 300 description "API service (No Internet access for it)" +``` +## Best Practices and Troubleshooting + +### Recommendations +- **Use exclude rules** for router management services like SSH +- **Use out-to-in-only** for services that do not need access to external + : networks. +- **Limit port ranges** in static rules to only necessary ports. +- **Document all rules** using descriptions for easier management. +- **Use non-standard ports** for publishing SSH and other administrative + : services. +- **Configure appropriate pool sizes** based on expected concurrent + : connections in your network. + +### Common Configuration Issues +**Static rules not working:** + +1. Verify that the external IP address is included in an address pool +2. Check that interfaces are correctly configured as inside or outside +3. Ensure firewall rules allow the traffic + +**Twice-NAT not functioning:** + +1. Confirm twice-nat pool is configured +2. Verify static rules have the correct twice-nat option +3. Check that both translation and twice-nat pools are properly defined + +**Router management access issues:** + +1. Verify exclude rules are configured for management services +2. Check that local-address matches the router's interface IP +3. Ensure external-interface is correctly specified + +**Forwarded traffic from external networks not bypassing NAT:** + +1. Verify exclude rules are configured for the specific traffic flow +2. Check that local-address matches the destination IP in the internal + network +3. Ensure protocol and port specifications match the traffic requirements + +## Operational Commands +Monitor NAT44 status and active connections using VyOS operational +commands: +```{opcmd} show vpp nat nat44 addresses + +Display configured NAT44 address pools. +``` + +```{opcmd} show vpp nat nat44 interfaces + +Show which interfaces are configured as inside or outside for NAT44. +``` + +```{opcmd} show vpp nat nat44 sessions + +Display active NAT44 translation sessions. +``` + +```{opcmd} show vpp nat nat44 static + +Show all configured static NAT mappings. +``` + +```{opcmd} show vpp nat nat44 summary + +Display a summary of NAT44 and statistics. +```
\ No newline at end of file diff --git a/docs/vpp/md-description.md b/docs/vpp/md-description.md new file mode 100644 index 00000000..03ade42c --- /dev/null +++ b/docs/vpp/md-description.md @@ -0,0 +1,81 @@ +--- +lastproofread: '2026-02-16' +--- + +(vpp-description)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Dataplane Description + +## What is VPP in VyOS? +VyOS supports two packet forwarding dataplanes: +- **Linux kernel dataplane** (traditional) +- **Vector Packet Processor (VPP) dataplane** (optional) + +VPP is a high-performance user space packet processor that improves +throughput for demanding network workloads. + +## Key Benefits + +**Performance Improvement** + +VPP uses vector-based packet processing instead of one-by-one handling, +delivering: +- **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 supports both dataplanes simultaneously, providing: +- **Cross-dataplane forwarding**: Traffic can flow between the VPP dataplane + 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 + +## Packet Processing Integration +VPP Dataplane integration minimizes configuration changes. Features in the +kernel dataplane continue to operate there. VPP Dataplane only handles packet +forwarding for interfaces explicitly assigned to it. + +Traffic flow examples between VPP and kernel dataplane interfaces: +```{image} /_static/images/vpp/vyos_vpp_integration.svg +:align: center +``` + +### Green path + +Traffic between two VPP interfaces stays within VPP for maximum performance +and can use only VPP dataplane features. + +### Blue path + +Traffic between a VPP interface and a kernel interface is processed by both +dataplanes and can use features from both. + +**Note:** This path has slower performance than pure VPP or pure kernel +forwarding because packets traverse both dataplanes. + +### Red path + +Traffic between two kernel interfaces stays within the kernel dataplane without +VPP acceleration. This is the traditional VyOS dataplane operation. + +## CLI Integration + +VyOS CLI commands work with both dataplanes. Use the same commands to +configure interfaces, routing, and other features regardless of the dataplane. diff --git a/docs/vpp/md-index.md b/docs/vpp/md-index.md new file mode 100644 index 00000000..06b48792 --- /dev/null +++ b/docs/vpp/md-index.md @@ -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} +:includehidden: true +:maxdepth: 1 + +description +requirements +limitations +configuration/index +troubleshooting +``` diff --git a/docs/vpp/md-limitations.md b/docs/vpp/md-limitations.md new file mode 100644 index 00000000..e6d43b85 --- /dev/null +++ b/docs/vpp/md-limitations.md @@ -0,0 +1,41 @@ +--- +lastproofread: '2026-02-17' +--- + +(vpp-limitations)= + +```{include} /_include/need_improvement.txt +``` +# VPP Dataplane Limitations + +VPP Dataplane provides significant performance advantages, but has some +limitations you should consider. + +- **Feature Parity** + + VPP does not support all features available in the Linux kernel dataplane. + Some networking features, specific protocols, or services may not be + available. + + While VPP supports various interface types similar to the kernel, their + capabilities may differ. + +- **NIC and Driver Compatibility** + + VyOS currently supports only DPDK drivers for network interfaces. + Not all network interface cards are compatible with DPDK drivers. + +- **Data Path Limitations** + + If a feature exists only in the kernel dataplane, traffic that uses that + feature cannot traverse VPP interfaces. Examples include: + + - Firewall + - QoS + + When traffic uses the pure VPP path, it does not reach the kernel, where + such features are implemented. Plan how traffic flows through your VyOS + instance to ensure it reaches the necessary features. + + VPP provides native alternatives for some features. For example, VPP + native ACLs provide basic firewall functionality. diff --git a/docs/vpp/md-requirements.md b/docs/vpp/md-requirements.md new file mode 100644 index 00000000..7758cabd --- /dev/null +++ b/docs/vpp/md-requirements.md @@ -0,0 +1,130 @@ +--- +lastproofread: '2026-02-16' +--- + +(vpp-requirements)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Dataplane Requirements + +VPP Dataplane requires specific hardware. Ensure your system meets these +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: + + - SSE4.2 support (available on most modern Intel and AMD CPUs). + - At least 4 physical CPU cores for a minimum configuration (more cores + recommended for higher throughput). + + :::{important} + **Physical Cores vs Logical Cores** + + VPP Dataplane requires 4 *physical* CPU cores, not logical cores. + Systems with Simultaneous Multithreading (SMT) or Hyper-Threading (HT) + present each physical core as 2 logical cores. + + Cloud providers often display logical cores as "cores" or "vCPUs". + For example, a cloud instance showing "4 cores" may have only 2 physical + cores with SMT/HT enabled. Always verify the actual physical core count + in your cloud provider's documentation. + ::: + + For virtualized environments, ensure CPU features are passed through to the + VM and that sufficient physical cores are allocated. + +- **Memory Requirements** + + Memory significantly affects VPP stability. Insufficient RAM can cause + initialization failures or prevent the dataplane from starting. + + - Minimum: 8 GB RAM. VyOS will not start the VPP Dataplane if less than 8 GB + is available. + - Recommended: 16 GB or more (especially for high throughput, many interfaces, + or large routing tables). + +- **Network Interface Cards (NICs)** + + :::{warning} + VyOS supports only specific NICs for the VPP dataplane. Using unsupported + hardware may cause activation failures, initialization errors, crashes, + or degraded performance. + ::: + + When enabling VPP, VyOS checks detected network interfaces against a list + of validated NICs. Validation is based on the **PCI ID** of the device or + the **kernel driver** used by the interface. + + Supported NICs: + + :::{list-table} + :widths: 15 18 40 35 + :header-rows: 1 + + * - **Filter Type** + - **Filter Value** + - **NIC Name/Description** + - **Platform Where NIC Can Be Found** + * - PCI ID + - 15b3:1019 + - Mellanox Technologies MT28800 Family + [ConnectX-5 Ex] + - Bare-metal + * - PCI ID + - 15b3:101d + - Mellanox Technologies MT2892 Family + [ConnectX-6 Dx] + - Bare-metal + * - PCI ID + - 15b3:101e + - Mellanox Technologies ConnectX Family + mlx5Gen Virtual Function + - Oracle Cloud + * - PCI ID + - 8086:1592 + - Intel Corporation Ethernet Controller + E810-C for QSFP + - Bare-metal + * - PCI ID + - 1ae0:0042 + - Google, Inc. Compute Engine Virtual + Ethernet [gVNIC] + - Google Cloud + * - PCI ID + - 1af4:1000 + - Red Hat, Inc. Virtio network device + - KVM-based hypervisors, including with + Open vSwitch; Google Cloud + * - PCI ID + - 1d0f:ec20 + - Amazon.com, Inc. Elastic Network + Adapter (ENA) + - AWS + * - Kernel Driver + - hv_netvsc + - Microsoft Hyper-V network interface + card + - Microsoft Azure + ::: + + If no supported NIC is detected, VPP activation will be rejected. + + In testing or advanced deployments, unsupported hardware can be explicitly + allowed in the configuration: + + ```{cfgcmd} set vpp settings allow-unsupported-nics + ``` + + :::{note} + This option bypass the hardware validation checks for the specified + devices. Stability and performance are not guaranteed when using + unsupported NICs or drivers. + ::: diff --git a/docs/vpp/md-troubleshooting.md b/docs/vpp/md-troubleshooting.md new file mode 100644 index 00000000..8e3f977c --- /dev/null +++ b/docs/vpp/md-troubleshooting.md @@ -0,0 +1,412 @@ +--- +lastproofread: '2026-02-18' +--- + +(vpp-troubleshooting)= + +```{include} /_include/need_improvement.txt +``` + +# VPP Dataplane Troubleshooting +This page shows you how to collect diagnostic information to troubleshoot VPP +dataplane issues. These techniques help you resolve problems yourself and +provide support teams with the information they need. + +Collecting the right diagnostic data is crucial for effective troubleshooting. + +## Packet Capture (PCAP) +Packet capture is a valuable debugging tool for analyzing network traffic and +identifying issues with packet processing, routing, and filtering. + +`pcap trace` in VPP captures packets at different states: received (rx), +transmitted (tx), and dropped (drop). + +### Starting Packet Capture +**Command syntax:** +```{opcmd} sudo vppctl pcap trace [rx] [tx] [drop] [max \<n\>] [intfc \<interface-name|any\>] [file \<name\>] [max-bytes-per-pkt \<n\>] +``` +**Parameters:** +- `rx` - Capture received packets +- `tx` - Capture transmitted packets +- `drop` - Capture dropped packets +- `max <n>` - Depth of the local buffer. After `n` packets arrive, the + buffer flushes to file. When the next `n` packets arrive, the file + overwrites with new data. (default: 100) +- `intfc <interface-name|any>` - Specify an interface or use `any` for + all interfaces (default: any) +- `file <name>` - Output filename. The PCAP file is stored in the `/tmp/` + directory. +- `max-bytes-per-pkt <n>` - Maximum bytes to capture per packet + (must be >= 32, \<= 9000) + +**Examples:** +```none +# Start capturing tx packets with specific parameters +sudo vppctl pcap trace tx max 35 intfc eth1 file vpp_eth1.pcap + +# Capture all packet types from any interface +sudo vppctl pcap trace rx tx drop max 1000 intfc any file vpp_capture.pcap max-bytes-per-pkt 128 +``` +### Monitoring Capture Status +To check the capture status: +```{opcmd} sudo vppctl pcap trace status +``` +This command displays: +- Whether capture is active +- Capture parameters +- Number of packets captured +- Output file location + +### Stopping Packet Capture + +:::{warning} +VPP does not automatically stop packet captures. If left running, captures +consume resources indefinitely. Always stop captures when you're done +with them. +::: +To stop the active packet capture: +```{opcmd} sudo vppctl pcap trace off +``` +Example output when stopping: +```none +Write 35 packets to /tmp/vpp_eth1.pcap, and stop capture... +``` +**Notes:** +- PCAP files are stored in the `/tmp/` directory. +- Existing files are overwritten. +- If you don't specify a filename, default names are used: `/tmp/rx.pcap`, + `/tmp/tx.pcap`, and `/tmp/rxandtx.pcap`. +- Large captures consume significant disk space—monitor available space. +- Stop captures promptly to avoid filling storage. + +## Packet Tracing +VPP packet tracing shows how packets flow through the VPP processing graph, +including which nodes process each packet and what transformations occur. + +:::{warning} +Tracing generates large amounts of data, especially on high-traffic +systems. Limit the number of traced packets to avoid overwhelming the system. +::: + +### Basic Packet Tracing Commands + +#### Start tracing +To start tracing packets at a specific graph node: +```{opcmd} sudo vppctl trace add \<input-graph-node\> \<pkts\> [verbose] +``` +- `<input-graph-node>` - Graph node name where tracing starts + (for example, `dpdk-input`, `ethernet-input`, or `ip4-input`). +- `<pkts>` - Number of packets to trace (for example, 100). +- `[verbose]` - Optional flag to include detailed buffer information in the + trace output. + +**Common node names for tracing:** +- `dpdk-input`: Packets received from DPDK interfaces +- `ethernet-input`: Ethernet frame processing +- `ip4-input`: IPv4 packet processing +- `ip6-input`: IPv6 packet processing +- `ip4-lookup`: IPv4 routing table lookup +- `ip6-lookup`: IPv6 routing table lookup + +#### View traces +After packets are traced, view the results: +```{opcmd} sudo vppctl show trace [max COUNT] +``` +- `[max COUNT]` - Optional limit on number of packets to display + (default: all) + +#### Clear traces +After reviewing traces, clear them to free up resources: +```{opcmd} sudo vppctl clear trace +``` +#### Example Workflow +```none +# Add traces for 100 packets on dpdk-input node +sudo vppctl trace add dpdk-input 100 + +# Send some traffic, then view results +sudo vppctl show trace + +# Clear traces for next test +sudo vppctl clear trace +``` +### Understanding Trace Output +Trace output shows how packets flow through VPP processing nodes: +```none +Packet 1 + +01:00:09:508438: dpdk-input + eth2 rx queue 0 + buffer 0x8533: current data 0, length 98, buffer-pool 0, ref-count 1, trace handle 0x1000000 + ext-hdr-valid + PKT MBUF: port 1, nb_segs 1, pkt_len 98 + buf_len 1828, data_len 98, ol_flags 0x0, data_off 128, phys_addr 0x78814d40 + packet_type 0x0 l2_len 0 l3_len 0 outer_l2_len 0 outer_l3_len 0 + rss 0x0 fdir.hi 0x0 fdir.lo 0x0 + IP4: 0c:87:6c:4e:00:01 -> 0c:de:0d:e2:00:02 + ICMP: 192.168.102.2 -> 192.168.99.3 + tos 0x00, ttl 64, length 84, checksum 0xb88d dscp CS0 ecn NON_ECN + fragment id 0x37c5, flags DONT_FRAGMENT + ICMP echo_request checksum 0x64e id 3024 +01:00:09:508449: ethernet-input + frame: flags 0x1, hw-if-index 2, sw-if-index 2 + IP4: 0c:87:6c:4e:00:01 -> 0c:de:0d:e2:00:02 +01:00:09:508455: ip4-input + ICMP: 192.168.102.2 -> 192.168.99.3 + tos 0x00, ttl 64, length 84, checksum 0xb88d dscp CS0 ecn NON_ECN + fragment id 0x37c5, flags DONT_FRAGMENT + ICMP echo_request checksum 0x64e id 3024 +01:00:09:508458: ip4-sv-reassembly-feature + [not-fragmented] +01:00:09:508460: nat-pre-in2out + in2out next_index 2 arc_next_index 10 +01:00:09:508462: nat44-ed-in2out + NAT44_IN2OUT_ED_FAST_PATH: sw_if_index 2, next index 10, session 0, translation result 'success' via i2of + i2of match: saddr 192.168.102.2 sport 3024 daddr 192.168.99.3 dport 3024 proto ICMP fib_idx 0 rewrite: saddr 192.168.99.1 daddr 192.168.99.3 icmp-id 3024 txfib 0 + o2if match: saddr 192.168.99.3 sport 3024 daddr 192.168.99.1 dport 3024 proto ICMP fib_idx 0 rewrite: saddr 192.168.99.3 daddr 192.168.102.2 icmp-id 3024 txfib 0 + search key local 192.168.102.2:3024 remote 192.168.99.3:3024 proto ICMP fib 0 thread-index 0 session-index 0 +01:00:09:508469: ip4-lookup + fib 0 dpo-idx 10 flow hash: 0x00000000 + ICMP: 192.168.99.1 -> 192.168.99.3 + tos 0x00, ttl 64, length 84, checksum 0xbb8e dscp CS0 ecn NON_ECN + fragment id 0x37c5, flags DONT_FRAGMENT + ICMP echo_request checksum 0x64e id 3024 +01:00:09:508472: ip4-rewrite + tx_sw_if_index 1 dpo-idx 10 : ipv4 via 192.168.99.3 eth1: mtu:1500 next:5 flags:[] 0ccea70400010cde0de200010800 flow hash: 0x00000000 + 00000000: 0ccea70400010cde0de2000108004500005437c540003f01bc8ec0a86301c0a8 + 00000020: 63030800064e0bd00d9a52c2d26800000000f4490000000000001011 +01:00:09:508474: eth1-output + eth1 flags 0x0038000d + IP4: 0c:de:0d:e2:00:01 -> 0c:ce:a7:04:00:01 + ICMP: 192.168.99.1 -> 192.168.99.3 + tos 0x00, ttl 63, length 84, checksum 0xbc8e dscp CS0 ecn NON_ECN + fragment id 0x37c5, flags DONT_FRAGMENT + ICMP echo_request checksum 0x64e id 3024 +01:00:09:508477: eth1-tx + eth1 tx queue 0 + buffer 0x8533: current data 0, length 98, buffer-pool 0, ref-count 1, trace handle 0x1000000 + ext-hdr-valid + natted l2-hdr-offset 0 l3-hdr-offset 14 + PKT MBUF: port 1, nb_segs 1, pkt_len 98 + buf_len 1828, data_len 98, ol_flags 0x0, data_off 128, phys_addr 0x78814d40 + packet_type 0x0 l2_len 0 l3_len 0 outer_l2_len 0 outer_l3_len 0 + rss 0x0 fdir.hi 0x0 fdir.lo 0x0 + IP4: 0c:de:0d:e2:00:01 -> 0c:ce:a7:04:00:01 + ICMP: 192.168.99.1 -> 192.168.99.3 + tos 0x00, ttl 63, length 84, checksum 0xbc8e dscp CS0 ecn NON_ECN + fragment id 0x37c5, flags DONT_FRAGMENT + ICMP echo_request checksum 0x64e id 3024 +``` +In this example, the trace shows: +- The packet is received on `eth2` interface at the `dpdk-input` node. +- It flows through `ethernet-input` and `ip4-input` nodes. +- NAT translation occurs at the `nat44-ed-in2out` node, changing the source + IP. +- The packet is routed through `ip4-lookup` and `ip4-rewrite` nodes. +- It transmits out of `eth1` interface at the `eth1-tx` node. + +## Additional Diagnostic Information +When reporting issues to support teams or performing advanced troubleshooting, +collect additional diagnostic information. + +### Before/After Traffic Analysis +Before you send traffic: +```none +sudo vppctl clear hardware-interfaces +sudo vppctl clear interfaces +sudo vppctl clear error +sudo vppctl clear runtime +``` +After you send traffic: +```none +sudo vppctl show version verbose +sudo vppctl show hardware-interfaces +sudo vppctl show interface address +sudo vppctl show interface +sudo vppctl show runtime +sudo vppctl show error +``` +### Core System Information +**Memory and buffer information:** +```none +sudo vppctl show memory api-segment stats-segment numa-heaps main-heap map verbose +sudo vppctl show buffers +sudo vppctl show physmem detail +sudo vppctl show physmem map +``` +**Runtime and performance data:** +```none +sudo vppctl show cpu +sudo vppctl show threads +sudo vppctl show runtime +sudo vppctl show node counters +``` +### Protocol-Specific Information +**Layer 2 data (if configured):** +```none +sudo vppctl show l2fib +sudo vppctl show bridge-domain +``` +**IPv4 data (if configured):** +```none +sudo vppctl show ip fib +sudo vppctl show ip neighbors +``` +**IPv6 data (if configured):** +```none +sudo vppctl show ip6 fib +sudo vppctl show ip6 neighbors +``` +**MPLS data (if configured):** +```none +sudo vppctl show mpls fib +sudo vppctl show mpls tunnel +``` +## Creating Support Packages +Use the automated diagnostic collection script to gather comprehensive VPP +troubleshooting information when contacting support or reporting issues. + +### VPP Diagnostic Collection Script +Create the diagnostic collection script: +```python +#!/usr/bin/env python3 +"""VyOS VPP Diagnostic Collection Script""" + +import datetime +import shutil +import subprocess +import tarfile +from pathlib import Path + + +def run_cmd(cmd, output_file, diag_dir): + """Run command and save output to file.""" + try: + result = subprocess.run( + cmd, shell=True, capture_output=True, text=True, timeout=30 + ) + content = f"Command: {cmd}\nExit code: {result.returncode}\nTimestamp: {datetime.datetime.now()}\n{'-' * 50}\n" + if result.stdout: + content += f"\nSTDOUT:\n{result.stdout}" + if result.stderr: + content += f"\nSTDERR:\n{result.stderr}" + (diag_dir / output_file).write_text(content) + except Exception as e: + (diag_dir / output_file).write_text(f"Command: {cmd}\nERROR: {e}") + + +def collect_diagnostics(): + """Collect all VPP diagnostics and create archive.""" + timestamp = datetime.datetime.now().strftime("%Y%m%d-%H%M%S") + diag_dir = Path.home() / f"vpp-diagnostics-{timestamp}" + + # VPP commands to collect + commands = [ + ("sudo vppctl show version verbose cmdline", "vpp-version.txt"), + ("sudo vppctl show hardware-interfaces", "hardware-interfaces.txt"), + ("sudo vppctl show interface address", "interface-addresses.txt"), + ("sudo vppctl show interface", "interfaces.txt"), + ("sudo vppctl show errors", "errors.txt"), + ("sudo vppctl show runtime", "runtime.txt"), + ( + "sudo vppctl show memory api-segment stats-segment numa-heaps main-heap map verbose", + "memory.txt", + ), + ("sudo vppctl show buffers", "buffers.txt"), + ("sudo vppctl show physmem detail", "physmem.txt"), + ("sudo vppctl show physmem map", "physmem-map.txt"), + ("sudo vppctl show cpu", "cpu.txt"), + ("sudo vppctl show threads", "threads.txt"), + ("sudo vppctl show node counters", "node-counters.txt"), + ("sudo vppctl show l2fib", "l2fib.txt"), + ("sudo vppctl show bridge-domain", "bridge-domains.txt"), + ("sudo vppctl show ip fib", "ip4-fib.txt"), + ("sudo vppctl show ip neighbors", "ip4-neighbors.txt"), + ("sudo vppctl show ip6 fib", "ip6-fib.txt"), + ("sudo vppctl show ip6 neighbors", "ip6-neighbors.txt"), + ("sudo vppctl show mpls fib", "mpls-fib.txt"), + ("sudo vppctl show mpls tunnel", "mpls-tunnels.txt"), + ("sudo vppctl show trace", "packet-traces.txt"), + ] + + try: + # Create diagnostics directory + diag_dir.mkdir(parents=True, exist_ok=True) + + # Collect VPP data + for cmd, output_file in commands: + run_cmd(cmd, output_file, diag_dir) + + # Collect PCAP files + pcap_files = list(Path("/tmp").glob("*.pcap")) + if pcap_files: + pcap_dir = diag_dir / "pcap-files" + pcap_dir.mkdir(exist_ok=True) + for pcap_file in pcap_files: + try: + shutil.copy2(pcap_file, pcap_dir) + except (PermissionError, OSError): + pass + + # Create archive + archive_name = f"vpp-diagnostics-{timestamp}.tar.gz" + archive_path = Path.home() / archive_name + + with tarfile.open(archive_path, "w:gz") as tar: + tar.add(diag_dir, arcname=diag_dir.name) + + # Cleanup + shutil.rmtree(diag_dir) + + print(f"VPP diagnostics collected: {archive_path}") + return archive_path + + except Exception as e: + if diag_dir.exists(): + shutil.rmtree(diag_dir) + print(f"Collection failed: {e}") + return None + + +def main(): + """Main function.""" + collect_diagnostics() + + +if __name__ == "__main__": + main() +``` +Save this script as `/config/scripts/vpp-collect-diagnostics` + +### Installation and Usage +**1. Make the script executable** +```{opcmd} sudo chmod +x /config/scripts/vpp-collect-diagnostics +``` +**2. Run VPP diagnostic collection** + +The script automatically collects all diagnostics and stores them in your home +directory. +```{opcmd} /config/scripts/vpp-collect-diagnostics +``` +**3. Generate VyOS tech-support archive separately** +You can also generate a tech-support archive with system-wide diagnostics: +```{opcmd} generate tech-support archive +``` + +### What the Script Collects + +- **System information**: Version details, build information, command-line + parameters. +- **Interface data**: Hardware interfaces, interface addresses, statistics, + and configurations. +- **Performance metrics**: Runtime statistics, error counters, node counters, + CPU, and thread information. +- **Memory analysis**: Memory usage (API segment, stats segment, NUMA heaps, + main heap), buffers, and physical memory. +- **Layer 2 data**: L2 forwarding table (L2FIB) and bridge domain + configurations. +- **IPv4 data**: IPv4 forwarding table (FIB) and IPv4 neighbor table. +- **IPv6 data**: IPv6 forwarding table (FIB) and IPv6 neighbor table. +- **MPLS data**: MPLS forwarding table (FIB) and MPLS tunnel information. +- **Packet traces**: Captured packet traces (if available). +- **Packet captures**: PCAP files from the `/tmp` directory (if available). |