From bf75633052db67e0bfb7900d05e380c3d64cd493 Mon Sep 17 00:00:00 2001 From: Quill <69414602+teslazonda@users.noreply.github.com> Date: Mon, 2 Mar 2026 18:42:37 +0900 Subject: Proofread files in /vpp directory (#1770) * Proofread description.rst and requirements.rst * Fixes indentation in aws.rst * Update need_improvement.txt * Edit limitations.rst * Prooofread vpp/troubleshooting.rst * Fix line length lint errors * Fix additional line length errors * Fix final line length errors --- docs/_include/need_improvement.txt | 4 +- docs/installation/cloud/aws.rst | 2 +- docs/vpp/description.rst | 57 ++++++++++------ docs/vpp/index.rst | 2 +- docs/vpp/limitations.rst | 27 +++++--- docs/vpp/requirements.rst | 54 ++++++++------- docs/vpp/troubleshooting.rst | 136 ++++++++++++++++++++++--------------- 7 files changed, 171 insertions(+), 111 deletions(-) (limited to 'docs') diff --git a/docs/_include/need_improvement.txt b/docs/_include/need_improvement.txt index 1ce50685..e368ee95 100644 --- a/docs/_include/need_improvement.txt +++ b/docs/_include/need_improvement.txt @@ -8,9 +8,9 @@

Call for Contributions

-This section needs improvements, examples and explanations. +Help improve this section with additional content, examples, and explanations. -Please take a look at the Contributing Guide for our :ref:`documentation`. +For contribution guidelines, see :ref:`documentation`. .. raw:: html diff --git a/docs/installation/cloud/aws.rst b/docs/installation/cloud/aws.rst index 5d1e9050..2901b6d1 100644 --- a/docs/installation/cloud/aws.rst +++ b/docs/installation/cloud/aws.rst @@ -100,7 +100,7 @@ Creating the Amazon Cloudwatch Agent Configuration in Amazon 1. Create an :abbr:`IAM (Identity and Access Management)` role for your :abbr:`EC2 (Elastic Compute Cloud)` instance to access the CloudWatch service. Name it ``CloudWatchAgentAdminRole``. The role must contain at - least two policies: ``CloudWatchAgentAdminPolicy`` and + least two policies: ``CloudWatchAgentAdminPolicy`` and ``AmazonSSMManagedInstanceCore``. .. note:: CloudWatchAgentServerRole is too permissive and should be used only diff --git a/docs/vpp/description.rst b/docs/vpp/description.rst index fbbb6403..8481bfe9 100644 --- a/docs/vpp/description.rst +++ b/docs/vpp/description.rst @@ -1,4 +1,4 @@ -:lastproofread: 2025-09-04 +:lastproofread: 2026-02-16 .. _vpp_description: @@ -11,26 +11,36 @@ VPP Dataplane Description What is VPP in VyOS? ==================== -VyOS supports two packet forwarding dataplanes: the traditional Linux kernel dataplane and the optional Vector Packet Processor (VPP) dataplane. VPP is a high-performance userspace packet processing engine that can significantly improve throughput for demanding network workloads. +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 processes packets in a special way, using vectors, rather than one-by-one, delivering: +VPP uses vector-based packet processing instead of one-by-one handling, +delivering: -- **Much higher throughput** compared to kernel forwarding -- **Lower and more consistent latency** for time-sensitive applications -- **Linear scaling** with additional CPU cores +- **Higher throughput** compared to kernel forwarding. +- **Lower and more consistent latency** for time-sensitive applications. +- **Linear scaling** with additional CPU cores. **VyOS Hybrid Integration** -VyOS provides unique flexibility by supporting both dataplanes simultaneously: +VyOS supports both dataplanes simultaneously, providing: -- **Cross-dataplane forwarding**: Traffic can flow between VPP and kernel interfaces seamlessly -- **Transparent configuration**: Same CLI commands and most services work regardless of dataplane -- **Gradual migration**: Enable VPP on high-traffic interfaces while keeping others on kernel +- **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 =============== @@ -46,12 +56,14 @@ When to Use VPP - No latency-sensitive workloads - Applications requiring specific features not supported by VPP Dataplane -Packets Processing Integration Details -====================================== +Packet Processing Integration +============================= -VPP Dataplane integration is done in the way that minimizes configuration changes. Features that exist in kernel dataplane are not removed but continue to operate in kernel dataplane. VPP Dataplane only takes over packet forwarding for interfaces explicitly assigned to it. +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. -Examples of traffic flow between interfaces connected to VPP and kernel dataplanes: +Traffic flow examples between VPP and kernel dataplane interfaces: .. image:: /_static/images/vpp/vyos_vpp_integration.svg :align: center @@ -59,24 +71,27 @@ Examples of traffic flow between interfaces connected to VPP and kernel dataplan Green path """""""""" -Traffic between two VPP interfaces is processed entirely within VPP for maximum performance. Packets that follow this path can use only features available inside VPP dataplane. +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, with VPP handling the VPP side and the kernel handling the kernel side. Packets that follow this path can use features available in both VPP and kernel dataplanes, at the same time. +Traffic between a VPP interface and a kernel interface is processed by both +dataplanes and can use features from both. -**Note:** Because packets must follow both dataplanes, performance will be slower than with pure VPP or pure kernel forwarding. +**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 is processed entirely within the kernel dataplane. Packets that follow this path can use only features available inside kernel dataplane, and lack VPP acceleration. - -This is the traditional VyOS dataplane operation. +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 are designed to work seamlessly with both dataplanes. When configuring interfaces, routing, and other features, the same commands can be used regardless of the underlying dataplane. +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/index.rst b/docs/vpp/index.rst index 520459e7..e483cb98 100644 --- a/docs/vpp/index.rst +++ b/docs/vpp/index.rst @@ -8,7 +8,7 @@ VPP Dataplane ############# -VPP (Vector Packet Processing) is a high performance, packet processing stack +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. diff --git a/docs/vpp/limitations.rst b/docs/vpp/limitations.rst index 1becb86e..58360ccc 100644 --- a/docs/vpp/limitations.rst +++ b/docs/vpp/limitations.rst @@ -1,4 +1,4 @@ -:lastproofread: 2025-09-04 +:lastproofread: 2026-02-17 .. _vpp_limitations: @@ -9,25 +9,34 @@ VPP Dataplane Limitations ######################### -While VPP Dataplane offers significant performance advantages, there are some limitations and considerations to be aware of. +VPP Dataplane provides significant performance advantages, but has some +limitations you should consider. * **Feature Parity** - Not all features available in the Linux kernel dataplane are supported in VPP. Some networking features, specific protocols, or services may not be available. + VPP does not support all features available in the Linux kernel dataplane. + Some networking features, specific protocols, or services may not be + available. - VPP supports various interface types that have parity with kernel, but their capabilities may differ. + While VPP supports various interface types similar to the kernel, their + capabilities may differ. -* **NIC and Drivers Compatibility** +* **NIC and Driver Compatibility** - VyOS currently supports only DPDK drivers for network interfaces. Not all NICs are compatible with DPDK drivers. + 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 kernel dataplane, traffic using that feature will not be able to traverse VPP interfaces. Examples of such features are: + 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 pure VPP path, it simply never reaches the kernel where such features are implemented. Therefore, you need to carefully plan how traffic flows through VyOS router to ensure that it can reach expected features. + 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 has native replacements for some of these features, for example VPP native ACLs can satisfy basic firewalling needs. \ No newline at end of file + VPP provides native alternatives for some features. For example, VPP + native ACLs provide basic firewall functionality. diff --git a/docs/vpp/requirements.rst b/docs/vpp/requirements.rst index 63004aff..77d494e1 100644 --- a/docs/vpp/requirements.rst +++ b/docs/vpp/requirements.rst @@ -1,4 +1,4 @@ -:lastproofread: 2025-09-04 +:lastproofread: 2026-02-16 .. _vpp_requirements: @@ -8,50 +8,58 @@ VPP Dataplane Requirements ########################## -VPP Dataplane usage in VyOS has very strict hardware requirements. Please ensure your system meets the following prerequisites before enabling VPP: +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. + VPP Dataplane is available on both bare-metal, on-premise virtualized, and + cloud deployment platforms. * **CPU Requirements** - Regardless of the platform, VPP Dataplane requires a CPU with the following features: + Regardless of the platform, VPP Dataplane requires a CPU with: - - SSE4.2 support (most modern Intel and AMD CPUs) - - At least 4 **physical** CPU cores for the minimum configuration. More cores are recommended for higher throughput. + - 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. Many systems use Simultaneous Multithreading (SMT) or Hyper-Threading (HT), which presents each physical core as 2 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 Provider Considerations:** + 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. - Some cloud providers display logical cores in their UI as "cores" or "vCPUs", which can be misleading. For example: - - - A cloud instance showing "4 cores" may actually have only 2 physical cores with SMT/HT enabled - - Always verify the actual physical core count, not the logical core count - - Check your cloud provider's documentation to understand their core counting methodology - - **Note:** If you are using VyOS in a virtualized environment, ensure that CPU features are properly passed through to the VM and that you have allocated sufficient physical cores. + For virtualized environments, ensure CPU features are passed through to the + VM and that sufficient physical cores are allocated. * **Memory Requirements** - Memory is one of the biggest factors affecting VPP stability, therefore it is critical to ensure that your system has sufficient RAM. + Memory significantly affects VPP stability. Insufficient RAM can cause + initialization failures or prevent the dataplane from starting. - - Minimum: 8 GB RAM - - Recommended: 16 GB or more, if you have high throughput requirements, many interfaces, or big routing tables. - - VyOS contains safeguards that prevent VPP from starting if there is insufficient memory for the initial configuration, but it does not protect from memory exhaustion during operation. + - 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 allows using VPP Dataplane only with NICs that are known to be compatible. Using unsupported NICs may lead to inability to activate the dataplane, initialize a NIC, crashes during operations, and degraded performance. + .. warning:: + + VyOS supports only specific NICs for VPP Dataplane. Unsupported NICs may + cause activation failures, initialization errors, crashes, or + degraded performance. - Validated NICs include: + Supported NICs: - Intel® Ethernet Network Adapter E810-2CQDA2 - NVIDIA/Mellanox ConnectX-5 - VirtIO - Other NICs may work, but are not officially supported. + Other NICs may work but are not officially supported. diff --git a/docs/vpp/troubleshooting.rst b/docs/vpp/troubleshooting.rst index 3661f44b..747f9772 100644 --- a/docs/vpp/troubleshooting.rst +++ b/docs/vpp/troubleshooting.rst @@ -1,4 +1,4 @@ -:lastproofread: 2025-09-23 +:lastproofread: 2026-02-18 .. _vpp_troubleshooting: @@ -8,35 +8,46 @@ VPP Dataplane Troubleshooting ############################# -This page provides essential troubleshooting information for VPP dataplane issues. It covers data collection techniques that are useful both for self-assistance and for providing comprehensive information to support teams when seeking help. +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. -When experiencing VPP issues, collecting the right diagnostic information is crucial for effective troubleshooting. The following sections describe the most important data collection methods. +Collecting the right diagnostic data is crucial for effective troubleshooting. Packet Capture (PCAP) ===================== -Packet capture is one of the most valuable debugging tools for analyzing network traffic and identifying issues with packet processing, routing, or filtering. +Packet capture is a valuable debugging tool for analyzing network traffic and +identifying issues with packet processing, routing, and filtering. -VPP's pcap trace functionality captures packets at various points: received (rx), transmitted (tx), and dropped (drop) packets. +``pcap trace`` in VPP captures packets at different states: received (rx), +transmitted (tx), and dropped (drop). Starting Packet Capture ----------------------- **Command syntax:** +.. stop_vyoslinter .. opcmd:: sudo vppctl pcap trace [rx] [tx] [drop] [max ] [intfc ] [file ] [max-bytes-per-pkt ] +.. start_vyoslinter -**Key parameters:** +**Parameters:** - ``rx`` - Capture received packets - ``tx`` - Capture transmitted packets - ``drop`` - Capture dropped packets -- ``max `` - Depth of local buffer. Once ``n`` packets are received, buffer is flushed to file. Once next ``n`` packets are received the file is overwritten with new data. (default: 100) -- ``intfc `` - Specify interface or use ``any`` for all interfaces (default: any) -- ``file `` - Output filename. The PCAP file with this name is stored in ``/tmp/`` directory. -- ``max-bytes-per-pkt `` - Maximum bytes to capture per packet (must be >= 32, <= 9000) +- ``max `` - 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 `` - Specify an interface or use ``any`` for + all interfaces (default: any) +- ``file `` - Output filename. The PCAP file is stored in the ``/tmp/`` + directory. +- ``max-bytes-per-pkt `` - Maximum bytes to capture per packet + (must be >= 32, <= 9000) **Examples:** @@ -51,17 +62,17 @@ Starting Packet Capture Monitoring Capture Status ------------------------- -To check the current capture status: +To check the capture status: .. opcmd:: sudo vppctl pcap trace status -This command shows: +This command displays: - Whether capture is active - Capture parameters -- Number of packets captured so far +- Number of packets captured - Output file location Stopping Packet Capture @@ -69,7 +80,9 @@ Stopping Packet Capture .. warning:: - VPP does not automatically stop packet captures. If left running, captures will continue indefinitely, consuming resources. Always remember to stop captures when they are no longer needed. + 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: @@ -83,22 +96,25 @@ Example output when stopping: Write 35 packets to /tmp/vpp_eth1.pcap, and stop capture... -**Important notes:** +**Notes:** -- PCAP files are stored in ``/tmp/`` directory -- Files will be overwritten if they already exist -- If no filename is provided, default names are used: ``/tmp/rx.pcap``, ``/tmp/tx.pcap``, ``/tmp/rxandtx.pcap`` -- Large captures can consume significant disk space - monitor available space -- Stop captures promptly to avoid filling up storage +- 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 provides detailed information about how packets flow through the VPP processing graph, showing exactly which nodes process each packet and any transformations applied. Packet tracing is essential for understanding VPP's internal packet processing flow. +VPP packet tracing shows how packets flow through the VPP processing graph, +including which nodes process each packet and what transformations occur. .. warning:: - Tracing can generate a large amount of data, especially on high-traffic systems. Use it judiciously and limit the number of packets traced to avoid overwhelming the system. + 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 ----------------------------- @@ -112,9 +128,11 @@ To start tracing packets at a specific graph node: sudo vppctl trace add [verbose] -- ```` - Name of the graph node to start tracing from (e.g., ``dpdk-input``, ``ethernet-input``, ``ip4-input``) -- ```` - Number of packets to trace (e.g., 100) -- ``[verbose]`` - Optional flag to include detailed buffer information in the trace output +- ```` - Graph node name where tracing starts + (for example, ``dpdk-input``, ``ethernet-input``, or ``ip4-input``). +- ```` - 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:** @@ -128,13 +146,14 @@ To start tracing packets at a specific graph node: View traces ^^^^^^^^^^^ -When packets have been traced, view the results with: +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) +- ``[max COUNT]`` - Optional limit on number of packets to display + (default: all) Clear traces ^^^^^^^^^^^^ @@ -162,7 +181,7 @@ Example Workflow Understanding Trace Output -------------------------- -Trace output shows the packet's journey through VPP processing nodes: +Trace output shows how packets flow through VPP processing nodes: .. code-block:: none @@ -231,23 +250,25 @@ Trace output shows the packet's journey through VPP processing nodes: ICMP echo_request checksum 0x64e id 3024 -In this case, the trace shows: +In this example, the trace shows: -- The packet was received on ``eth2`` interface (``dpdk-input`` node) -- It was processed by the ``ethernet-input`` and ``ip4-input`` nodes -- NAT translation occurred at the ``nat44-ed-in2out`` node, changing the source IP -- The packet was routed via ``ip4-lookup`` and ``ip4-rewrite`` nodes -- Finally, it was transmitted out of ``eth1`` interface (``eth1-tx`` node) +- 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, you may need to collect additional diagnostic information. +When reporting issues to support teams or performing advanced troubleshooting, +collect additional diagnostic information. Before/After Traffic Analysis ----------------------------- -Before sending traffic: +Before you send traffic: .. code-block:: none @@ -256,7 +277,7 @@ Before sending traffic: sudo vppctl clear error sudo vppctl clear runtime -After sending traffic: +After you send traffic: .. code-block:: none @@ -291,28 +312,28 @@ Core System Information Protocol-Specific Information ----------------------------- -**Layer 2 information (if configured):** +**Layer 2 data (if configured):** .. code-block:: none sudo vppctl show l2fib sudo vppctl show bridge-domain -**IPv4 information (if configured):** +**IPv4 data (if configured):** .. code-block:: none sudo vppctl show ip fib sudo vppctl show ip neighbors -**IPv6 information (if configured):** +**IPv6 data (if configured):** .. code-block:: none sudo vppctl show ip6 fib sudo vppctl show ip6 neighbors -**MPLS information (if configured):** +**MPLS data (if configured):** .. code-block:: none @@ -322,7 +343,8 @@ Protocol-Specific Information Creating Support Packages ========================= -When contacting support or reporting issues, use the automated diagnostic collection script to create a comprehensive package. This ensures all relevant VPP troubleshooting information is collected systematically. +Use the automated diagnostic collection script to gather comprehensive VPP +troubleshooting information when contacting support or reporting issues. VPP Diagnostic Collection Script -------------------------------- @@ -451,7 +473,8 @@ Installation and Usage **2. Run VPP diagnostic collection** -The script will automatically collect all VPP diagnostics and store it in your home directory. +The script automatically collects all diagnostics and stores them in your home +directory. .. opcmd:: @@ -459,7 +482,7 @@ The script will automatically collect all VPP diagnostics and store it in your h **3. Generate VyOS tech-support archive separately** -Additionally, you can generate a VyOS tech-support archive that includes system-wide diagnostics: +You can also generate a tech-support archive with system-wide diagnostics: .. opcmd:: @@ -468,13 +491,18 @@ Additionally, you can generate a VyOS tech-support archive that includes system- What the Script Collects ------------------------ -- **System Information**: Version details, build information, command line parameters -- **Interface Data**: Hardware interfaces, interface addresses, interface 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), buffer information, physical memory details -- **Layer 2 Data**: L2 forwarding table (L2FIB), bridge domain configurations -- **IPv4 Information**: IPv4 forwarding table (FIB), IPv4 neighbor table -- **IPv6 Information**: IPv6 forwarding table (FIB), IPv6 neighbor table -- **MPLS Data**: MPLS forwarding table (FIB), MPLS tunnel information -- **Packet Traces**: Captured packet traces VPP (if available) -- **Packet Dumps**: PCAP files from ``/tmp`` directory (if available) +- **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). -- cgit v1.2.3