Skip to main content

Dedicated Edge — DPDK Mode

DPDK mode provides the highest throughput by giving VPP direct access to network interfaces, bypassing the Linux kernel. This is the recommended mode for production hardware deployments requiring 10 Gbps or higher line-rate performance.

Prerequisites​

Before deploying a dedicated edge in DPDK mode, ensure the following:

  • Server or appliance with Intel NICs supporting SR-IOV
  • VT-d enabled in BIOS/UEFI settings
  • Ubuntu 22.04+ or compatible Linux distribution
  • Docker installed and running
  • SSH access configured (key-based authentication recommended)
  • Minimum hardware: 4 CPU cores, 8 GB RAM, 2 NICs (WAN + LAN)

Hardware Setup​

Enable VT-d​

VT-d (Intel Virtualization Technology for Directed I/O) must be enabled in your server's BIOS/UEFI settings. The exact location varies by manufacturer, but it is typically found under:

  • Advanced > Processor Configuration > Intel VT for Directed I/O (VT-d)
  • Or Advanced > Chipset Configuration > VT-d

After enabling VT-d, save and reboot the server.

Hugepages and VFIO​

The build script handles these automatically:

  • Hugepages: 1024 x 2 MB pages are allocated for VPP's memory buffers
  • VFIO: The vfio-pci kernel module is loaded to allow userspace access to NICs

No manual configuration is required — the deploy process sets these up on the target machine.

DPDK takes exclusive control of NICs

When DPDK binds to a NIC, that interface is removed from the Linux kernel and is no longer available to the host OS. Ensure your management/SSH access uses a separate interface that is not assigned to VPP.

Build and Deploy​

From the testing/ directory on your build machine, run:

./scripts/build-production-edge-image.sh --deploy <EDGE_IP> --bootstrap

This single command performs the entire deployment:

  1. Builds the agent Docker image locally
  2. Transfers the image to the edge via SSH (docker save | ssh | docker load)
  3. Creates the /opt/netlinkz directory structure on the edge
  4. Sets up hugepages and VFIO kernel modules
  5. Generates the docker-compose.yml for the edge stack
  6. Starts the VPP agent and supporting containers
  7. Runs the bootstrap process (if --bootstrap is specified)

Build Script Flags​

FlagDescription
--deploy <IP>Target edge IP address for SSH deployment
--bootstrapRun the bootstrap process after deployment
--skip-buildSkip the Docker image build (use a previously built image)
--overwrite-composeRegenerate the compose file (overwrites existing)
warning

Never run the build script with --overwrite-compose on a running edge unless you intend to reset its compose configuration. The default behavior preserves the existing compose file to avoid disrupting a production deployment.

Verification​

After deployment, verify that VPP is running and the DPDK interfaces are detected:

ssh edge@<EDGE_IP> "sudo docker exec vpp-agent vppctl show interface"

You should see DPDK interfaces listed as GigabitEthernet (e.g., G0, G1) or similar DPDK-bound device names. Example output:

              Name               Idx    State  MTU (L3/IP4/IP6/MPLS)
GigabitEthernet0/0/0              1      up          9000/0/0/0
GigabitEthernet0/0/1              2      up          9000/0/0/0
local0                            0     down          0/0/0/0

To check that the containers are running:

ssh edge@<EDGE_IP> "sudo docker ps"

Troubleshooting​

VPP fails to start​

  • Verify VT-d is enabled in BIOS
  • Check that hugepages are allocated: cat /proc/meminfo | grep HugePages
  • Ensure the VFIO module is loaded: lsmod | grep vfio
  • Review VPP logs: ssh edge@<EDGE_IP> "sudo docker logs vpp-agent"

Interfaces not detected​

  • Confirm the NICs support SR-IOV (check with lspci | grep Ethernet)
  • Verify the NIC PCI addresses match what VPP expects in vpp.conf

Next Steps​

After the edge is running, proceed to Bootstrap & Provisioning if you did not use the --bootstrap flag during deployment.