From 00faafed96d86a970bf566c79f1bfd304630ccaa Mon Sep 17 00:00:00 2001 From: zdc Date: Fri, 29 Aug 2025 19:53:13 +0300 Subject: [PATCH] VPP: Add comprehensive VPP documentation This commit introduces extensive documentation for VyOS VPP (Vector Packet Processing) Dataplane interfaces and features, including examples. Features documented: * VPP integration description, base requirements and limitations * VPP dataplane core settings * Features enabled in the dataplane: ACL, IPsec, NAT, sFlow * VPP interface types: bonding, bridge, GRE, IPIP, kernel, loopback, VXLAN, XConnect Note: This is an initial documentation version that will require ongoing improvements based on user feedback and questions, real-world deployment testing and validation, additional use cases and configuration scenarios discovered in production. Therefore, all pages are marked as "need improvement". --- .../images/vpp/vyos_vpp_integration.svg | 3 + docs/index.rst | 1 + docs/vpp/configuration/acl.rst | 633 ++++++++++++++++++ docs/vpp/configuration/dataplane/buffers.rst | 78 +++ docs/vpp/configuration/dataplane/cpu.rst | 68 ++ docs/vpp/configuration/dataplane/index.rst | 30 + .../vpp/configuration/dataplane/interface.rst | 85 +++ docs/vpp/configuration/dataplane/ipsec.rst | 56 ++ docs/vpp/configuration/dataplane/ipv6.rst | 32 + docs/vpp/configuration/dataplane/l2learn.rst | 28 + docs/vpp/configuration/dataplane/lcp.rst | 50 ++ docs/vpp/configuration/dataplane/logging.rst | 42 ++ docs/vpp/configuration/dataplane/memory.rst | 49 ++ docs/vpp/configuration/dataplane/system.rst | 54 ++ docs/vpp/configuration/dataplane/unix.rst | 36 + docs/vpp/configuration/index.rst | 46 ++ docs/vpp/configuration/interfaces/bonding.rst | 182 +++++ docs/vpp/configuration/interfaces/bridge.rst | 200 ++++++ docs/vpp/configuration/interfaces/gre.rst | 157 +++++ docs/vpp/configuration/interfaces/index.rst | 40 ++ docs/vpp/configuration/interfaces/ipip.rst | 96 +++ docs/vpp/configuration/interfaces/kernel.rst | 258 +++++++ .../vpp/configuration/interfaces/loopback.rst | 86 +++ docs/vpp/configuration/interfaces/vxlan.rst | 135 ++++ .../vpp/configuration/interfaces/xconnect.rst | 101 +++ docs/vpp/configuration/ipsec.rst | 199 ++++++ docs/vpp/configuration/nat/cgnat.rst | 141 ++++ docs/vpp/configuration/nat/index.rst | 34 + docs/vpp/configuration/nat/nat44.rst | 552 +++++++++++++++ docs/vpp/configuration/sflow.rst | 43 ++ docs/vpp/description.rst | 82 +++ docs/vpp/index.rst | 22 + docs/vpp/limitations.rst | 33 + docs/vpp/requirements.rst | 57 ++ 34 files changed, 3709 insertions(+) create mode 100644 docs/_static/images/vpp/vyos_vpp_integration.svg create mode 100644 docs/vpp/configuration/acl.rst create mode 100644 docs/vpp/configuration/dataplane/buffers.rst create mode 100644 docs/vpp/configuration/dataplane/cpu.rst create mode 100644 docs/vpp/configuration/dataplane/index.rst create mode 100644 docs/vpp/configuration/dataplane/interface.rst create mode 100644 docs/vpp/configuration/dataplane/ipsec.rst create mode 100644 docs/vpp/configuration/dataplane/ipv6.rst create mode 100644 docs/vpp/configuration/dataplane/l2learn.rst create mode 100644 docs/vpp/configuration/dataplane/lcp.rst create mode 100644 docs/vpp/configuration/dataplane/logging.rst create mode 100644 docs/vpp/configuration/dataplane/memory.rst create mode 100644 docs/vpp/configuration/dataplane/system.rst create mode 100644 docs/vpp/configuration/dataplane/unix.rst create mode 100644 docs/vpp/configuration/index.rst create mode 100644 docs/vpp/configuration/interfaces/bonding.rst create mode 100644 docs/vpp/configuration/interfaces/bridge.rst create mode 100644 docs/vpp/configuration/interfaces/gre.rst create mode 100644 docs/vpp/configuration/interfaces/index.rst create mode 100644 docs/vpp/configuration/interfaces/ipip.rst create mode 100644 docs/vpp/configuration/interfaces/kernel.rst create mode 100644 docs/vpp/configuration/interfaces/loopback.rst create mode 100644 docs/vpp/configuration/interfaces/vxlan.rst create mode 100644 docs/vpp/configuration/interfaces/xconnect.rst create mode 100644 docs/vpp/configuration/ipsec.rst create mode 100644 docs/vpp/configuration/nat/cgnat.rst create mode 100644 docs/vpp/configuration/nat/index.rst create mode 100644 docs/vpp/configuration/nat/nat44.rst create mode 100644 docs/vpp/configuration/sflow.rst create mode 100644 docs/vpp/description.rst create mode 100644 docs/vpp/index.rst create mode 100644 docs/vpp/limitations.rst create mode 100644 docs/vpp/requirements.rst diff --git a/docs/_static/images/vpp/vyos_vpp_integration.svg b/docs/_static/images/vpp/vyos_vpp_integration.svg new file mode 100644 index 00000000..3a16a9bd --- /dev/null +++ b/docs/_static/images/vpp/vyos_vpp_integration.svg @@ -0,0 +1,3 @@ + + +
Kernel
VPP
NIC
NIC
NIC
NIC
 \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 69768eb8..3cdf8684 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -79,6 +79,7 @@ VyOS User Guide automation/index troubleshooting/index configexamples/index + vpp/index .. toctree:: diff --git a/docs/vpp/configuration/acl.rst b/docs/vpp/configuration/acl.rst new file mode 100644 index 00000000..00a24163 --- /dev/null +++ b/docs/vpp/configuration/acl.rst @@ -0,0 +1,633 @@ +: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) +* **MACIP 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**: MACIP 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: + +.. code-block:: none + + set vpp acl ip tag-name + set vpp acl ip tag-name description '' + +Example: + +.. code-block:: 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: + +.. code-block:: none + + set vpp acl ip tag-name rule + +Basic IP ACL Rule Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each rule requires an action and matching criteria: + +.. code-block:: none + + set vpp acl ip tag-name rule action + set vpp acl ip tag-name rule description '' + set vpp acl ip tag-name rule 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: + +.. code-block:: none + + # Source configuration + set vpp acl ip tag-name rule source prefix + set vpp acl ip tag-name rule source port + + # Destination configuration + set vpp acl ip tag-name rule destination prefix + set vpp acl ip tag-name rule destination port + +**Prefix Specification:** + +- ```` - IPv4 prefix in CIDR notation +- ```` - IPv6 prefix in CIDR notation + +**Port Specification:** + +- ``<1-65535>`` - Single port number +- ``-`` - Port range (e.g., 1001-1005) + +TCP Flags Matching +^^^^^^^^^^^^^^^^^^ + +For TCP protocol rules, you can match specific TCP flags: + +.. code-block:: none + + # Match packets with specific flags set + set vpp acl ip tag-name rule tcp-flags ack + set vpp acl ip tag-name rule tcp-flags fin + set vpp acl ip tag-name rule tcp-flags psh + set vpp acl ip tag-name rule tcp-flags rst + set vpp acl ip tag-name rule tcp-flags syn + set vpp acl ip tag-name rule tcp-flags urg + + # Match packets without specific flags set + set vpp acl ip tag-name rule tcp-flags not ack + set vpp acl ip tag-name rule tcp-flags not syn + +IP ACL Configuration Examples +----------------------------- + +Example 1: Basic Web Server ACL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: 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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: 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 +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: 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: + +.. code-block:: none + + # Apply to input direction + set vpp acl ip interface input acl-tag tag-name + + # Apply to output direction + set vpp acl ip interface output acl-tag tag-name + +Where: + +- ```` - Interface name (e.g., eth0, eth1) +- ```` - ACL rule number (0-4294967295) for ordering multiple ACL tags +- ```` - 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: + +.. code-block:: 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**: MACIP 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 MACIP ACL Tags +----------------------- + +MACIP ACL tags are created under the ``vpp acl macip`` configuration node: + +.. code-block:: none + + set vpp acl macip tag-name + set vpp acl macip tag-name description '' + +Example: + +.. code-block:: none + + set vpp acl macip tag-name 'MAC-FILTER' + set vpp acl macip tag-name 'MAC-FILTER' description 'Layer 2 MAC address filtering' + +Adding Rules to MACIP ACL Tags +------------------------------ + +Rules are added to MACIP ACL tags with specific rule numbers: + +.. code-block:: none + + set vpp acl macip tag-name rule + +Basic MAC ACL Rule Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each rule requires an action and matching criteria: + +.. code-block:: none + + set vpp acl macip tag-name rule action + set vpp acl macip tag-name rule description '' + +**Actions:** + +- ``permit`` - Allow matching traffic +- ``deny`` - Block matching traffic + +Note: MACIP ACLs do not support the ``permit-reflect`` action available in IP ACLs. + +MAC Address Matching +^^^^^^^^^^^^^^^^^^^^ + +Configure MAC address matching criteria: + +.. code-block:: none + + set vpp acl macip tag-name rule mac-address + set vpp acl macip tag-name rule 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: + +.. code-block:: none + + set vpp acl macip tag-name rule 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`` + +MACIP ACL Configuration Examples +-------------------------------- + +Example 1: Device Whitelist +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + # Create MACIP ACL for device whitelisting + set vpp acl macip tag-name 'DEVICE-WHITELIST' + set vpp acl macip tag-name 'DEVICE-WHITELIST' description 'Allow only approved devices' + + # Allow specific workstation + set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 10 action permit + set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 10 mac-address '00:1b:21:12:34:56' + set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 10 prefix '192.168.1.100/32' + set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 10 description 'Admin workstation' + + # Allow specific server + set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 20 action permit + set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 20 mac-address '00:1b:21:78:90:ab' + set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 20 prefix '192.168.1.10/32' + set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 20 description 'Web server' + + # Deny everything else + set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 999 action deny + set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 999 mac-address '00:00:00:00:00:00' + set vpp acl macip tag-name 'DEVICE-WHITELIST' rule 999 mac-mask '00:00:00:00:00:00' + +Example 2: Vendor-Based Filtering +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + # Create MACIP ACL for vendor-based filtering + set vpp acl macip tag-name 'VENDOR-FILTER' + set vpp acl macip tag-name 'VENDOR-FILTER' description 'Filter by MAC vendor OUI' + + # Deny Realtek devices (OUI: 00:e0:4c) + set vpp acl macip tag-name 'VENDOR-FILTER' rule 10 action deny + set vpp acl macip tag-name 'VENDOR-FILTER' rule 10 mac-address '00:e0:4c:00:00:00' + set vpp acl macip tag-name 'VENDOR-FILTER' rule 10 mac-mask 'ff:ff:ff:00:00:00' + set vpp acl macip tag-name 'VENDOR-FILTER' rule 10 description 'Block Realtek devices' + + # Allow all other devices + set vpp acl macip tag-name 'VENDOR-FILTER' rule 100 action permit + set vpp acl macip tag-name 'VENDOR-FILTER' rule 100 mac-address '00:00:00:00:00:00' + set vpp acl macip tag-name 'VENDOR-FILTER' rule 100 mac-mask '00:00:00:00:00:00' + set vpp acl macip tag-name 'VENDOR-FILTER' rule 100 description 'Allow all other vendors' + +Example 3: Network Segmentation by MAC +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + # Create MACIP ACL for network segmentation + set vpp acl macip tag-name 'SEGMENT-FILTER' + set vpp acl macip tag-name 'SEGMENT-FILTER' description 'Segment networks by MAC/IP binding' + + # Allow management VLAN devices + set vpp acl macip tag-name 'SEGMENT-FILTER' rule 10 action permit + set vpp acl macip tag-name 'SEGMENT-FILTER' rule 10 mac-address '02:01:00:00:00:00' + set vpp acl macip tag-name 'SEGMENT-FILTER' rule 10 mac-mask 'ff:ff:00:00:00:00' + set vpp acl macip tag-name 'SEGMENT-FILTER' rule 10 prefix '10.1.0.0/16' + set vpp acl macip tag-name 'SEGMENT-FILTER' rule 10 description 'Management VLAN' + + # Allow user VLAN devices + set vpp acl macip tag-name 'SEGMENT-FILTER' rule 20 action permit + set vpp acl macip tag-name 'SEGMENT-FILTER' rule 20 mac-address '02:02:00:00:00:00' + set vpp acl macip tag-name 'SEGMENT-FILTER' rule 20 mac-mask 'ff:ff:00:00:00:00' + set vpp acl macip tag-name 'SEGMENT-FILTER' rule 20 prefix '10.2.0.0/16' + set vpp acl macip tag-name 'SEGMENT-FILTER' rule 20 description 'User VLAN' + +Applying MACIP ACL Tags to Interfaces +------------------------------------- + +MACIP ACL tags can only be applied to the input direction of interfaces: + +.. code-block:: none + + set vpp acl macip interface tag-name + +.. note:: + **Syntax Difference**: Unlike IP ACLs, MACIP ACL interface application does not use the ``acl-tag `` structure since only single MACIP ACLs can be applied. + +.. warning:: + Unlike IP ACLs, MACIP ACLs do **not** support output direction filtering. There is no ``output`` option available for MACIP ACL interface application. + +Example: + +.. code-block:: none + + # Apply MAC filtering to interface input + set vpp acl macip interface eth0 tag-name 'MAC-FILTER' + set vpp acl macip 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 MACIP ACLs for Layer 2/3 filtering, IP ACLs for Layer 3/4 filtering +- **Consider direction limitations**: Remember that MACIP 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: + +.. code-block:: 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 MACIP): + +.. opcmd:: show vpp acl + +This command shows a summary of all configured ACL tags with their rules, displaying both IP ACLs and MACIP ACLs in a tabular format. + +Example output: + +.. code-block:: 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 + + show vpp acl ip interface + +Example output: + +.. code-block:: none + + Interface Input ACLs Output ACLs + ----------- ------------ ------------- + eth1 WEB-SERVER + +View specific IP ACL by tag name: + +.. opcmd:: show vpp acl ip tag-name + +Example: + +.. code-block:: 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 + +MACIP ACL Commands +------------------ + +View all MACIP ACLs: + +.. opcmd:: show vpp acl macip + +View MACIP ACL interface assignments: + +.. opcmd:: show vpp acl macip interface + +Example output: + +.. code-block:: none + + Interface ACL + ----------- ----- + eth0 VENDOR-FILTER + +View specific MACIP ACL by tag name: + +.. opcmd:: show vpp acl macip tag-name + +Example: + +.. code-block:: none + + vyos@vyos:~$ show vpp acl macip 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) + +**MACIP 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**: MACIP ACL tag applied to interface (input only) 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 + +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 + +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 + +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 + +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 + +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 + +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 + +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 driver + +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 rx-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 dpdk-options