diff options
Diffstat (limited to 'docs/vpp/configuration/dataplane')
| -rw-r--r-- | docs/vpp/configuration/dataplane/buffers.rst | 78 | ||||
| -rw-r--r-- | docs/vpp/configuration/dataplane/cpu.rst | 68 | ||||
| -rw-r--r-- | docs/vpp/configuration/dataplane/index.rst | 30 | ||||
| -rw-r--r-- | docs/vpp/configuration/dataplane/interface.rst | 85 | ||||
| -rw-r--r-- | docs/vpp/configuration/dataplane/ipsec.rst | 56 | ||||
| -rw-r--r-- | docs/vpp/configuration/dataplane/ipv6.rst | 32 | ||||
| -rw-r--r-- | docs/vpp/configuration/dataplane/l2learn.rst | 28 | ||||
| -rw-r--r-- | docs/vpp/configuration/dataplane/lcp.rst | 50 | ||||
| -rw-r--r-- | docs/vpp/configuration/dataplane/logging.rst | 42 | ||||
| -rw-r--r-- | docs/vpp/configuration/dataplane/memory.rst | 49 | ||||
| -rw-r--r-- | docs/vpp/configuration/dataplane/system.rst | 54 | ||||
| -rw-r--r-- | docs/vpp/configuration/dataplane/unix.rst | 36 |
12 files changed, 608 insertions, 0 deletions
diff --git a/docs/vpp/configuration/dataplane/buffers.rst b/docs/vpp/configuration/dataplane/buffers.rst new file mode 100644 index 00000000..b702ae69 --- /dev/null +++ b/docs/vpp/configuration/dataplane/buffers.rst @@ -0,0 +1,78 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_dataplane_buffers: + +.. include:: /_include/need_improvement.txt + +################################### +VPP Dataplane Buffers Configuration +################################### + +Buffers are essential for handling network packets efficiently, and proper configuration can enhance performance, reliability and is mandatory for VPP work. + +Buffers are used to temporarily store packets during processing, therefore their configuration should be in sync with NIC configuration, CPU threads, and overall system resources. + +Buffer Configuration Parameters +=============================== + +The following parameters can be configured for VPP buffers: + +buffers-per-numa +^^^^^^^^^^^^^^^^ + +Number of buffers allocated per NUMA node. This setting helps in optimizing memory access patterns for multi-CPU systems. +Usually it needs to be tuned if: +- there are a lot of interfaces in the system +- there are a lot of queues in NICs +- there are big descriptors size configured for NICs +The value should be set responsibly, overprovisioning can lead to issues with NICs configured with XDP driver. + +.. cfgcmd:: set vpp settings buffers buffers-per-numa <value> + +The common approach for the calculation is to use the formula: + +.. code-block:: none + + buffers-per-numa = (num-rx-queues * num-rx-desc) + (num-tx-queues * num-tx-desc) + +This should be done for each NIC, and then sum the results for all NICs in the system needs to be multiplied by 2.5 and the result will be the minimum value for `buffers-per-numa`. + +Try to avoid setting this value too low to avoid packet drops. + +data-size +^^^^^^^^^ + +This value sets how much payload data can be stored in a single buffer allocated by VPP. +Making it larger can reduce buffer chains for big packets, while a smaller value can save memory for environments handling mostly small packets. + +.. cfgcmd:: set vpp settings buffers data-size <value> + +Optimal size depends on the typical packet size in your network. If you are not sure, use the value of biggest MTU in your network plus some overhead (e.g., 128 bytes). + +page-size +^^^^^^^^^ + +A memory pages type used for buffer allocation. Common values are 4K, 2M, or 1G. + +Use pages that are configured in system settings. + +.. cfgcmd:: set vpp settings buffers page-size <value> + +Potential Issues and Troubleshooting +------------------------------------ + +Improper buffer configuration can lead to various issues, including: + +- Increased latency and packet loss +- Inefficient CPU utilization +- Interfaces initialization failures + +Indicators of such issues are: + +- Errors during interfaces initialization in VPP logs +- Packet drops observed in VPP statistics + +To troubleshoot buffer-related issues, consider the following steps: + +- Review VPP logs for any errors related to buffer allocation (often the message may contains error `-5`). +- Tune available buffers by adjusting the `buffers-per-numa` and `data-size` parameters. diff --git a/docs/vpp/configuration/dataplane/cpu.rst b/docs/vpp/configuration/dataplane/cpu.rst new file mode 100644 index 00000000..97e0fd93 --- /dev/null +++ b/docs/vpp/configuration/dataplane/cpu.rst @@ -0,0 +1,68 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_dataplane_cpu: + +.. include:: /_include/need_improvement.txt + +############################### +VPP Dataplane CPU Configuration +############################### + +VPP can utilize multiple CPU cores to enhance packet processing performance. Proper CPU configuration is crucial for achieving optimal throughput and low latency. + +There are several parameters that can be configured to optimize CPU usage for VPP. + +CPU Configuration Parameters +============================ + +main-core +^^^^^^^^^ + +The main core is responsible for handling control plane operations and managing worker threads. It should be set to a core that is not heavily utilized by other processes. If not set, VPP will automatically select a core `1`. + +.. cfgcmd:: set vpp settings cpu main-core <core-number> + +corelist-workers +^^^^^^^^^^^^^^^^ + +This parameter specifies the list of CPU cores that will be used as worker threads for packet processing. + +.. cfgcmd:: set vpp settings cpu corelist-workers <core-list> + +The core list can be specified in various formats, such as a comma-separated list (e.g., 2,3,4) or a range (e.g., 2-4). It is advisable to select cores that are on the same NUMA node as the network interfaces to minimize latency. + +Automatic cores selection +------------------------- + +There is a possibility to let VPP select CPU cores automatically. This can be done by configuring the following two parameters: + +skip-cores +^^^^^^^^^^ + +This parameter allows you to specify number of first CPU cores that should be excluded from being used for main or worker threads. The main thread will be assigned to the first available core after the skipped ones, and worker threads will be assigned to subsequent cores. + +.. cfgcmd:: set vpp settings cpu skip-cores <cores> + +Exclude cores that are reserved for other critical system processes to ensure that VPP does not interfere with their operation. + +workers +^^^^^^^ + +This parameter allows you to specify the number of worker threads that should be created. Each worker thread will be assigned to a separate CPU core after the skipped and main ones. + +.. cfgcmd:: set vpp settings cpu workers <number> + +The number of worker threads should be chosen based on the available CPU resources and the expected network load. A common approach is to set the number of workers to the number of available CPU cores minus the skipped and main cores. + +Potential Issues and Troubleshooting +==================================== + +Improper CPU configuration can lead to various issues, including: + +- Underperformance for both VPP (not enough cores were assigned) and kernel (too many cores were assigned to VPP) +- Resource conflicts with other processes and services + +Indicators of such issues are: + +- VPP or kernel forwarding performance is lower than expected +- Slower work of system components or services, including DNS, DHCP, dynamic routing, etc. diff --git a/docs/vpp/configuration/dataplane/index.rst b/docs/vpp/configuration/dataplane/index.rst new file mode 100644 index 00000000..90ecc6f6 --- /dev/null +++ b/docs/vpp/configuration/dataplane/index.rst @@ -0,0 +1,30 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_dataplane_index: + +.. include:: /_include/need_improvement.txt + +################################ +VPP Dataplane Core Configuration +################################ + +This section covers the core configuration options for the VPP dataplane in VyOS. It includes settings for memory management, CPU allocation, hugepages, and other essential parameters that influence the performance and behavior of the VPP dataplane. + +Please review the general system configuration, before starting to configure VPP. Without proper VyOS preconditions, VPP will not start or its efficiency will be significantly degraded. + +.. toctree:: + :maxdepth: 1 + :includehidden: + + system + buffers + cpu + interface + ipsec + ipv6 + l2learn + lcp + logging + memory + unix +
\ No newline at end of file diff --git a/docs/vpp/configuration/dataplane/interface.rst b/docs/vpp/configuration/dataplane/interface.rst new file mode 100644 index 00000000..e8ab8e58 --- /dev/null +++ b/docs/vpp/configuration/dataplane/interface.rst @@ -0,0 +1,85 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_dataplane_interface: + +.. include:: /_include/need_improvement.txt + +###################################### +VPP Dataplane Interfaces Configuration +###################################### + +Only Ethernet interfaces (physical or virtual) can be connected to the VPP dataplane. Interfaces configured here act as a bridge between VPP and the outside world, allowing VPP to send and receive packets into the network. + + +Interface Configuration Parameters +================================== + +driver +^^^^^^ +The driver parameter specifies the type of driver used for the network interface. VPP supports two types of drivers that can be used for this: DPDK and XDP. The choice of driver depends on the specific use case, hardware capabilities, and performance requirements. Some NICs may support only one of these drivers. + +.. cfgcmd:: set vpp settings interface <interface-name> driver <driver-type> + +The DPDK driver is generally preferred for high-performance scenarios, while the XDP driver may be suitable for NICs that do not support DPDK. + +.. _vpp_config_dataplane_interface_rx_mode: + +rx-mode +^^^^^^^ + +The rx-mode parameter defines how VPP handles incoming packets on the interface. There are several modes available, each with its own advantages and use cases: + +- ``interrupt``: In this mode, VPP relies on hardware interrupts to notify it of incoming packets. This mode is suitable for low to moderate traffic loads and can help reduce CPU usage during idle periods. It is not recommended if low-latency processing is required. May not be supported by some NICs. +- ``polling``: In polling mode, VPP continuously checks the interface for incoming packets. This mode is ideal for high-throughput scenarios where low latency is critical, as it minimizes the time packets spend waiting to be processed. However, it can lead to higher CPU usage, especially during periods of low traffic, because the polling process is always active. +- ``adaptive``: Adaptive mode combines the benefits of both interrupt and polling modes. VPP starts in interrupt mode and switches to polling mode when the traffic load increases. + +.. cfgcmd:: set vpp settings interface <interface-name> rx-mode <mode> + +The choice of rx-mode should be based on the expected traffic patterns and performance requirements of the network environment. + +dpdk-options +^^^^^^^^^^^^ + +The dpdk-options section allows for the configuration of various DPDK-specific settings for the interface. + +.. cfgcmd:: set vpp settings interface <interface-name> dpdk-options <option> <value> + +DPDK options you can configure are: + +- ``num-rx-queues``: Specifies the number of receive queues for the interface. More queues can improve performance on multi-core systems by allowing parallel processing of incoming packets. Each queue will be assigned to a separate CPU core. + +.. seealso:: :doc:`cpu` + +- ``num-tx-queues``: Specifies the number of transmit queues for the interface. Similar to receive queues, more transmit queues can enhance performance by enabling parallel processing of outgoing packets. +- ``num-rx-desc``: Defines the size of each receive queue. Larger queue sizes can help accommodate bursts of incoming traffic, reducing the likelihood of packet drops during high traffic periods. +- ``num-tx-desc``: Defines the size of each transmit queue. Larger sizes can help manage bursts of outgoing traffic more effectively. +- ``promisc``: Enables or disables promiscuous mode on the interface. When promiscuous mode is enabled, the interface will receive all packets on the network, regardless of type and destination of the packets. Some NICs need this feature to be enabled to avoid filtering out packets (for example to pass VLAN tagged packets). + +xdp-options +^^^^^^^^^^^ + +The xdp-options section allows for the configuration of various XDP-specific settings for the interface. + +.. cfgcmd:: set vpp settings interface <interface-name> xdp-options <option> <value> + +XDP options you can configure are: + +- ``no-syscall-lock``: Disables the syscall lock for the XDP interface. This can improve performance by allowing multiple threads to access the interface concurrently. +- ``num-rx-queues``: Specifies the number of receive queues for the XDP interface. More queues can improve performance on multi-core systems by allowing parallel processing of incoming packets. Each queue will be assigned to a separate CPU core. +- ``promisc``: Enables or disables promiscuous mode on the interface. When promiscuous mode is enabled, the interface will receive all packets on the network, regardless of type and destination of the packets. Some NICs need this feature to be enabled to avoid filtering out packets (for example to pass VLAN tagged packets). +- ``rx-queue-size``: Defines the size of each receive queue. Larger queue sizes can help accommodate bursts of incoming traffic, reducing the likelihood of packet drops during high traffic periods. +- ``tx-queue-size``: Defines the size of each transmit queue. Larger sizes can help manage bursts of outgoing traffic more effectively. +- ``zero-copy``: Enables zero-copy mode for the XDP interface. This mode allows packets to be processed without copying them between kernel and user space, reducing latency and CPU usage. + +Potential Issues and Troubleshooting +==================================== + +Improper interface configuration can lead to various issues, including: + +- Failure to initialize the interface +- Poor performance due to suboptimal driver selection or driver settings + +Indicators of such issues are: + +- Failed commits after adding or modifying an interface settings +- Low throughput or high latency on the interface
\ No newline at end of file diff --git a/docs/vpp/configuration/dataplane/ipsec.rst b/docs/vpp/configuration/dataplane/ipsec.rst new file mode 100644 index 00000000..b93b1d3d --- /dev/null +++ b/docs/vpp/configuration/dataplane/ipsec.rst @@ -0,0 +1,56 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_dataplane_ipsec: + +.. include:: /_include/need_improvement.txt + +####################### +VPP IPsec Configuration +####################### + +VPP supports IPsec (Internet Protocol Security) offloading from kernel, allowing to speed-up cryptographic operations by leveraging VPP's high-performance packet processing capabilities. + +IPSec does not require any specific configuration on VPP side. If both source and destinations of the IPsec traffic are reachable via VPP interfaces, VPP will automatically offload the IPsec processing from kernel. IPSec tunnels are configured in the VPN configuration section, see :ref:`ipsec_general`. + +IPSec Configuration Parameters +============================== + +interface-type +^^^^^^^^^^^^^^ + +When VPP is used for offloading IPsec, it creates a virtual interface of a specific type to connect to a peer. The type of the interface can be configured using the following command: + +.. cfgcmd:: set vpp settings ipsec interface-type <interface-type> + +The available interface types are: + +- ``ipsec``: This is the default interface type used for IPsec tunnels. +- ``ipip``: This interface type encapsulates IPsec traffic within IP-in-IP packets. + +Select the interface type based on peers settings. In most cases, you need to use the ``ipsec`` type. + +netlink +^^^^^^^ + +VPP uses netlink to receive IPSec event messages from the kernel. Proper settings of the following parameters are crucial for ensuring that VPP can process all such messages: + +.. cfgcmd:: set vpp settings ipsec netlink batch-delay-ms <milliseconds> + +This parameter specifies the delay in milliseconds between processing batch netlink messages. + +.. cfgcmd:: set vpp settings ipsec netlink batch-size <number> + +This parameter specifies the maximum number of netlink messages to process in a single batch. + +.. cfgcmd:: set vpp settings ipsec netlink rx-buffer-size <number> + +This parameter specifies the size of the receive buffer for netlink socket. If you expect to offload a lot of IPsec tunnels or get frequent and intensive rekeying, you may need to increase this value. + +Potential Issues and Troubleshooting +==================================== + +Improper IPsec configuration can lead to various issues, including: + +- Failure to offload IPsec tunnels to VPP +- Lost IPsec event messages due to insufficient netlink buffer size or batch settings +- IPSec states or SAs are not synchronized between kernel and VPP diff --git a/docs/vpp/configuration/dataplane/ipv6.rst b/docs/vpp/configuration/dataplane/ipv6.rst new file mode 100644 index 00000000..eb8cfcd8 --- /dev/null +++ b/docs/vpp/configuration/dataplane/ipv6.rst @@ -0,0 +1,32 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_dataplane_ipv6: + +.. include:: /_include/need_improvement.txt + +###################### +VPP IPv6 Configuration +###################### + +VPP allows to configure resources allocated for IPv6 traffic processing independently from IPv4. This allows to ensure that in networks without IPv6 traffic, the resources are not wasted on IPv6. But if IPv6 traffic is present - especially big routing tables - you need to allocate more resources for IPv6 processing to make dataplane stable. + +There are two main resources that can be configured for IPv6 traffic processing: + +.. cfgcmd:: set vpp settings ipv6 hash-buckets <value> + +This parameter configures the number of hash buckets used for IPv6 routing table. If you have a big IPv6 routing table, you may need to increase this value to ensure that the routing table is efficient and lookups are fast. + +.. cfgcmd:: set vpp settings ipv6 heap-size <value> + +This parameter configures the size of the heap used for IPv6 forwarding table. If you have a big IPv6 routing table, you may need to increase this value to ensure that the routing table can accommodate all routes. + +Potential Issues and Troubleshooting +==================================== + +Improper IPv6 configuration can lead to various issues, including: + +- Inefficient, slow routing table lookups and traffic processing due to insufficient hash buckets +- Crashes or instability of the dataplane due to insufficient heap size if there are a lot of IPv6 routes +- Overall instability of the dataplane when handling IPv6 traffic + +Consider increasing configuration values if you experience issues with IPv6 traffic processing or if you have a large IPv6 routing table. diff --git a/docs/vpp/configuration/dataplane/l2learn.rst b/docs/vpp/configuration/dataplane/l2learn.rst new file mode 100644 index 00000000..9812edc4 --- /dev/null +++ b/docs/vpp/configuration/dataplane/l2learn.rst @@ -0,0 +1,28 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_dataplane_l2learn: + +.. include:: /_include/need_improvement.txt + +######################### +VPP L2LEARN Configuration +######################### + +When VPP dataplane is connected to a L2 domain, it needs to learn MAC addresses of devices connected to the domain. And the amount of MAC addresses that can be learned is limited by default. + +The limit can be configured using the following command: + +.. cfgcmd:: set vpp settings l2learn limit <value> + +This parameter configures the maximum number of MAC addresses that can be learned in the L2 domain. If you have a large number of devices, you may need to increase this limit to ensure all MAC addresses can be learned. + +Potential Issues and Troubleshooting +==================================== + +Improper L2LEARN configuration can lead to various issues, including: + +- Inability to learn all MAC addresses in the L2 domain if the limit is set too low +- Increased packet loss or latency for devices that are not learned +- Overall instability of the dataplane when handling L2 traffic + +Consider increasing the L2LEARN limit if you experience issues with MAC address learning or if you have a large number of devices in the L2 domain. diff --git a/docs/vpp/configuration/dataplane/lcp.rst b/docs/vpp/configuration/dataplane/lcp.rst new file mode 100644 index 00000000..eacf1045 --- /dev/null +++ b/docs/vpp/configuration/dataplane/lcp.rst @@ -0,0 +1,50 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_dataplane_lcp: + +.. include:: /_include/need_improvement.txt + +##################### +VPP LCP Configuration +##################### + +Linux Control Plane (LCP) is one of core components of VPP that allows to offload various control plane functions to the Linux kernel. LCP provides seamless integration with other components of VyOS, allowing usage of other system components, like DHCP client, routing daemons, etc. together with VPP dataplane. + +VPP integration in VyOS relies heavily on LCP, building the relationship where almost all control plane functions are handled by other daemons and services and VPP is used exclusively for high-performance packet forwarding. This also reduces VPP management processing load, improving overall performance and stability of the dataplane. + +LCP can be configured using the following command: + +VyOS contains unique integration between kernel and VPP routing tables. By default, all the routes, even if they are not directly connected to VPP interfaces, are imported from kernel routing table to VPP routing table, pointing to the kernel. This allows to forward traffic to any destination known to the kernel, even if VPP itself does not have a route to that destination. + +However, in some scenarios, this behavior may not be desired. For example, if you have a large number of routes in the kernel routing table that are not directly connected to VPP interfaces, and you do not need forwarding between such destinations and destinations reachable via VPP, you can disable this behavior. This can be done using the following command: + +.. _vpp_config_dataplane_lcp_ignore-kernel-routes: + +.. cfgcmd:: set vpp settings lcp ignore-kernel-routes + +Pay attention that disabling this option leads to loss of connectivity to destinations if there are no direct routes in VPP routing table. + +Other configuration section crucial for integration between VPP and Kernel is netlink settings. It allows to configure how VPP management listen to netlink events and how it processes them. + +.. cfgcmd:: set vpp settings lcp batch-delay-ms <value> + +This parameter specifies the delay in milliseconds between processing batch netlink messages. If you expect to get frequent and intensive netlink events, you may need to decrease this value to ensure that VPP processes netlink events in a timely manner. + +.. cfgcmd:: set vpp settings lcp batch-size <value> + +This parameter specifies the maximum number of netlink messages to process in a single batch. If you have a high volume of netlink events, increasing this value can improve throughput by allowing more messages to be processed at once. However, setting it too high may increase latency for individual messages. + +.. cfgcmd:: set vpp settings lcp rx-buffer-size <value> + +This parameter specifies the size of the receive buffer for netlink messages. Increasing this value can help accommodate bursts of netlink messages, but setting it too high may lead to increased memory usage. + +Potential Issues and Troubleshooting +==================================== + +Improper LCP configuration can lead to various issues, including: + +- Loss of connectivity to certain destinations if kernel routes are ignored +- Delays in synchronization between kernel and VPP routing tables +- Desynchronization between kernel and VPP routing tables if netlink settings are not optimal + +Consider adjusting LCP settings if you experience issues with routing or connectivity, especially in scenarios involving dynamic route changes or a large number of routes. diff --git a/docs/vpp/configuration/dataplane/logging.rst b/docs/vpp/configuration/dataplane/logging.rst new file mode 100644 index 00000000..41da367a --- /dev/null +++ b/docs/vpp/configuration/dataplane/logging.rst @@ -0,0 +1,42 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_dataplane_logging: + +.. include:: /_include/need_improvement.txt + +######################### +VPP Logging Configuration +######################### + +VPP logging is an important part of monitoring and troubleshooting the performance and behavior of the VPP dataplane. + +VPP logs are stored in the ``/var/log/vpp.log`` file. Additionally daemon logs can be found in the system journal. + +Logging detalization can be configured via the next command: + +.. cfgcmd:: set vpp settings logging default-log-level <level> + +Where ``<level>`` can be one of the following: + +- ``emerg`` (Emergency) - System is unusable. +- ``alert`` (Alert) - Immediate action required. +- ``crit`` (Critical) - Critical conditions. +- ``err`` (Error) - Error conditions. +- ``warn`` (Warning) - Warning conditions. +- ``notice`` (Notice) - Normal but significant. +- ``info`` (Informational) - Routine informational messages. +- ``debug`` (Debug) - Detailed debugging messages. +- ``disabled`` (Disabled) - Logging disabled. + +It is recommended to set logging level to ``debug`` only for troubleshooting purposes, as it can generate a large volume of log data. For regular operation, a level of ``info`` or ``warn`` is usually sufficient. + +Potential Issues and Troubleshooting +==================================== + +Improper logging configuration can lead to various issues, including: + +- Excessive log file sizes if the logging level is set too high (e.g., ``debug``) +- Missing critical information if the logging level is set too low (e.g., ``alert``) +- Performance degradation due to excessive logging overhead + +Consider adjusting the logging level if you experience issues mentioned above. diff --git a/docs/vpp/configuration/dataplane/memory.rst b/docs/vpp/configuration/dataplane/memory.rst new file mode 100644 index 00000000..77543c2e --- /dev/null +++ b/docs/vpp/configuration/dataplane/memory.rst @@ -0,0 +1,49 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_dataplane_memory: + +.. include:: /_include/need_improvement.txt + +######################## +VPP Memory Configuration +######################## + +VPP heavily relies on hugepages for its memory management. Hugepages are larger memory pages that reduce the overhead of page management and improve performance for applications that require large amounts of memory, such as VPP. + +VPP supports both 2MB and 1GB hugepages, but the default and most commonly used size is 2MB. The choice of hugepage size can impact performance, with larger pages generally providing better performance for memory-intensive applications. + +Before configuring memory in VPP dataplane settings, you need to ensure that hugepages are enabled and properly configured on your system. + +.. seealso:: :ref:`Hugepages in VyOS Configuration for VPP <vpp_config_hugepages>` + +To configure memory settings for VPP, you can use the following commands in the VPP CLI: + +.. cfgcmd:: set vpp settings memory default-hugepage-size <size> + +Sets the default hugepage size for VPP. + +VPP uses a main heap as a central memory pool for FIB data structures entries allocations. + +Efficient memory management is crucial for VPP's performance, and the main heap plays a significant role in this. + +It can be configured using the following command: + +.. cfgcmd:: set vpp settings memory main-heap-page-size <size> + +Sets the main heap page size for VPP. + +.. cfgcmd:: set vpp settings memory main-heap-size <size> + +Sets the main heap size for VPP. + + +Potential Issues and Troubleshooting +==================================== + +Improper configuration of main heap size can lead to performance degradation or even system instability. If VPP runs out of memory in the main heap, it may crash or exhibit erratic behavior. Symptoms you may observe include: + +- Increased latency or packet loss +- Crashes or restarts of VPP processes, especially during routing table populating (e.g., BGP session establishment) +- Error messages related to memory allocation failures + +You need to tune the main heap size based on expected FIB entries. Pay attention - same amount of routes with a single next-hop and with multiple next-hops will consume different amounts of memory. diff --git a/docs/vpp/configuration/dataplane/system.rst b/docs/vpp/configuration/dataplane/system.rst new file mode 100644 index 00000000..ff8bfb61 --- /dev/null +++ b/docs/vpp/configuration/dataplane/system.rst @@ -0,0 +1,54 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_system: + +.. include:: /_include/need_improvement.txt + +########################## +VyOS Configuration for VPP +########################## + +.. _vpp_config_hugepages: + +Hugepages +========= +VPP utilizes hugepages for efficient memory management. Hugepages are larger memory pages that reduce the overhead of page management and improve performance for applications that require large amounts of memory. + +Hugepages can be configured in VyOS using the following commands: + +.. warning:: + + Changes to hugepage settings require a system reboot to take effect. + + Hugepages must be enabled before VPP configuration is applied. + +To enable hugepages: + +.. cfgcmd:: set system option kernel memory hugepage-size <size> hugepage-count '<count>' + +Enables hugepages with the specified size and count. The size can be either 2MB or 1GB, and the count specifies the number of hugepages to allocate. + +If your system has multiple NUMA nodes, the total amount of hugepages will be divided equally among them. + +Resources Limits +================ + +.. note:: + + By default, system will calculate and set the recommended values for resource limits. Avoid tuning these values if you are not sure what you are doing. + +During operations VPP utilizes a significant amount of system resources, especially memory. There are two main settings that may to be adjusted to ensure VPP runs smoothly: + +Maximum number of memory map areas a process may have: + +.. cfgcmd:: set system option resource-limits max-map-count <value> + +Maximum shared memory segment size: + +.. cfgcmd:: set system option resource-limits shmmax <value> + +Both settings are automatically calculated based on configured hugepages. + +Kernel Tuning +============= + diff --git a/docs/vpp/configuration/dataplane/unix.rst b/docs/vpp/configuration/dataplane/unix.rst new file mode 100644 index 00000000..3551d692 --- /dev/null +++ b/docs/vpp/configuration/dataplane/unix.rst @@ -0,0 +1,36 @@ +:lastproofread: 2025-09-04 + +.. _vpp_config_dataplane_unix: + +.. include:: /_include/need_improvement.txt + +################################ +VPP Unix Dataplane Configuration +################################ + +The UNIX configuration section is used to control VPP's interaction with the underlying operating system, including operations scheduling. + +VPP relies on the polling mechanism to efficiently manage I/O operations and system events. By default VPP continuously polls for events, which leads to permanent 100% CPU usage by all cores assigned to VPP dataplane. This is optimal for performance, but may not be desirable in all environments, especially where power consumption is a concern or where VPP is running inside a hypervisor, especially if VM has burstable thresholds and CPU usage limits. + +To mitigate this, VPP provides a configurable polling delay that allows to reduce CPU usage by introducing a delay between polling cycles. This introduces a trade-off between CPU usage and latency, as longer delays can lead to increased latency in processing events. + +You can configure the polling delay using the following command in the VyOS CLI: + +.. cfgcmd:: set vpp settings unix poll-sleep-usec <delay> + +Sets the polling delay in microseconds. A value of 0 means no delay (default), while higher values introduce a delay between polling cycles. + +Potential Issues and Troubleshooting +==================================== + +Setting the polling delay too high can lead to increased latency and reduced performance, as VPP may not respond to events as quickly. Conversely, setting it too low may result in high CPU usage, which can be problematic in resource-constrained environments. + +Symptoms of improper configuration may include: + +- Increased latency in packet processing +- Higher CPU usage than expected +- Packets lost due to buffer overruns + +If you do not need to reduce CPU usage, it is recommended to leave the polling delay at its default value of 0 for optimal performance. + +If you need to reduce CPU usage, you may also consider using ``interrupt`` or ``adaptive`` :ref:`DPDK driver modes <vpp_config_dataplane_interface_rx_mode>`, which can provide a balance between performance and resource utilization without affecting polling behavior.
\ No newline at end of file |