diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-02 17:54:19 +0300 |
|---|---|---|
| committer | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-06 16:18:03 +0300 |
| commit | f7bab3007a9e0d0fef3ec551a677380a00b12d6a (patch) | |
| tree | f46b904bd00ad186308fbd3c9bedcdadf3b2aa05 /docs/vpp | |
| parent | fa54a080fac977157454beb0853daf0ac0e6af66 (diff) | |
| download | vyos-documentation-f7bab3007a9e0d0fef3ec551a677380a00b12d6a.tar.gz vyos-documentation-f7bab3007a9e0d0fef3ec551a677380a00b12d6a.zip | |
chore(swap): remove canary md-*.md files and docs/superpowers
- Remove 115 canary md-*.md files (incremental swap helpers no longer needed)
- Remove 8 files under docs/superpowers (project planning/design docs that
shouldn't ship in the documentation tree)
π€ Generated by [robots](https://vyos.io)
Diffstat (limited to 'docs/vpp')
30 files changed, 0 insertions, 3697 deletions
diff --git a/docs/vpp/configuration/dataplane/md-buffers.md b/docs/vpp/configuration/dataplane/md-buffers.md deleted file mode 100644 index e9bddec9..00000000 --- a/docs/vpp/configuration/dataplane/md-buffers.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -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 deleted file mode 100644 index 9b798631..00000000 --- a/docs/vpp/configuration/dataplane/md-cpu.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -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 deleted file mode 100644 index f147ebe8..00000000 --- a/docs/vpp/configuration/dataplane/md-index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -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 deleted file mode 100644 index 231a49a9..00000000 --- a/docs/vpp/configuration/dataplane/md-interface.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -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 deleted file mode 100644 index 17e16f8e..00000000 --- a/docs/vpp/configuration/dataplane/md-ipsec.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -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 deleted file mode 100644 index a72dbbfa..00000000 --- a/docs/vpp/configuration/dataplane/md-ipv6.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -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 deleted file mode 100644 index fe5deb55..00000000 --- a/docs/vpp/configuration/dataplane/md-l2learn.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -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 deleted file mode 100644 index 82dc014e..00000000 --- a/docs/vpp/configuration/dataplane/md-lcp.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -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)= -(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 deleted file mode 100644 index e7fcf455..00000000 --- a/docs/vpp/configuration/dataplane/md-logging.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -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 deleted file mode 100644 index 1c588e7c..00000000 --- a/docs/vpp/configuration/dataplane/md-memory.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -lastproofread: '2026-02-27' ---- - -(vpp-config-dataplane-memory)= -(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 deleted file mode 100644 index 9832b86d..00000000 --- a/docs/vpp/configuration/dataplane/md-unix.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -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 deleted file mode 100644 index 24868166..00000000 --- a/docs/vpp/configuration/interfaces/md-bonding.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -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 deleted file mode 100644 index f7b24b1d..00000000 --- a/docs/vpp/configuration/interfaces/md-bridge.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -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 deleted file mode 100644 index fa91caae..00000000 --- a/docs/vpp/configuration/interfaces/md-gre.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -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 deleted file mode 100644 index 662f37c5..00000000 --- a/docs/vpp/configuration/interfaces/md-index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -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 deleted file mode 100644 index 8a847e48..00000000 --- a/docs/vpp/configuration/interfaces/md-ipip.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -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 deleted file mode 100644 index bc65338b..00000000 --- a/docs/vpp/configuration/interfaces/md-loopback.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -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 deleted file mode 100644 index 6fa1322a..00000000 --- a/docs/vpp/configuration/interfaces/md-vxlan.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -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 deleted file mode 100644 index 0ee052d2..00000000 --- a/docs/vpp/configuration/interfaces/md-xconnect.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -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 deleted file mode 100644 index 59b96070..00000000 --- a/docs/vpp/configuration/md-acl.md +++ /dev/null @@ -1,485 +0,0 @@ ---- -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 deleted file mode 100644 index 7e02ae74..00000000 --- a/docs/vpp/configuration/md-index.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -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 deleted file mode 100644 index 7ed2aee3..00000000 --- a/docs/vpp/configuration/md-ipfix.md +++ /dev/null @@ -1,50 +0,0 @@ -# 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 deleted file mode 100644 index 752b8377..00000000 --- a/docs/vpp/configuration/md-sflow.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -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 deleted file mode 100644 index 4d5c01d1..00000000 --- a/docs/vpp/configuration/nat/md-index.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -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 deleted file mode 100644 index a0805ed3..00000000 --- a/docs/vpp/configuration/nat/md-nat44.md +++ /dev/null @@ -1,653 +0,0 @@ ---- -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 deleted file mode 100644 index 03ade42c..00000000 --- a/docs/vpp/md-description.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -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 deleted file mode 100644 index 06b48792..00000000 --- a/docs/vpp/md-index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -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 deleted file mode 100644 index e6d43b85..00000000 --- a/docs/vpp/md-limitations.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -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 deleted file mode 100644 index 7758cabd..00000000 --- a/docs/vpp/md-requirements.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -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 deleted file mode 100644 index 8e3f977c..00000000 --- a/docs/vpp/md-troubleshooting.md +++ /dev/null @@ -1,412 +0,0 @@ ---- -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). |
