← Back to top page

sdplane Releases

Last updated: 2026-10-10

Download

Debian packages for Ubuntu 24.04. Both libsdplane and sdplane are required.

  • 2026-10-09: libsdplane 0.3.37-121 deb, sdplane 0.1.3-943 deb

Development Projects

Prerequisites

  • CPU: x86-64-v2 or later (amd64)
  • OS: Ubuntu 24.04 LTS
  • NIC: A DPDK-capable NIC. Most NICs are supported, including Intel and NVIDIA (Mellanox) NICs. For other NICs, check the DPDK supported NICs list. sdplane takes over the NICs specified in the configuration, so do not specify the Linux interface used for management.
  • Memory: 16GB or more

Installation and Setup

  1. Download the libsdplane and sdplane debs and install them. sdplane.service is enabled automatically.

    wget https://www.yasuhironet.net/dist/ubuntu24.04/libsdplane_0.3.37-121~ubuntu24.04_amd64.deb https://www.yasuhironet.net/dist/ubuntu24.04/sdplane_0.1.3-943~ubuntu24.04_amd64.deb
    sudo apt install ./libsdplane_*_amd64.deb ./sdplane_*_amd64.deb

    The DPDK 23.11 libraries (librte-*), liburcu and libpcap are installed automatically as dependencies, along with the recommended dpdk package (NIC drivers and tools such as dpdk-devbind.py).

  2. Configure hugepages. Add the following to /etc/default/grub and update grub.

    GRUB_CMDLINE_LINUX="default_hugepagesz=1G hugepagesz=1G hugepages=8"
    sudo update-grub

  3. Load the vfio-pci driver at boot.

    sudo cp /etc/sdplane/vfio-pci.conf /etc/modules-load.d/

    Note: If vfio-pci does not work, try uio_pci_generic. Run the following commands after step 4. vfio-pci uses the IOMMU, so it does not work where the IOMMU is unavailable, for example when VT-d / AMD-Vi is disabled in the BIOS.

    sudo cp /etc/sdplane/uio_pci_generic.conf /etc/modules-load.d/
    sudo sed -i 's/vfio-pci/uio_pci_generic/' /etc/sdplane/sdplane.conf

  4. Download sdplane-switch.conf, the minimal configuration for a switch, and place it as /etc/sdplane/sdplane.conf. Then edit the PCI addresses in the set device lines to match your system. Use lspci to find the PCI addresses.

    wget https://www.yasuhironet.net/dist/sdplane-switch.conf
    sudo mv sdplane-switch.conf /etc/sdplane/sdplane.conf
    lspci
    sudo vi /etc/sdplane/sdplane.conf

    ⚠️ If you specify the PCI address of an NVMe SSD by mistake, the system will fail to boot. Double-check the PCI addresses.

  5. Reboot, and sdplane starts. Connect to the CLI with telnet.

    sudo reboot
    telnet localhost 9882

    ⚠️ The CLI has no authentication. Allow connections to 9882/tcp only from localhost.

Starting, Stopping and Disabling

sdplane runs as a systemd service (sdplane.service).

sudo systemctl start sdplane
Starts sdplane.
sudo systemctl stop sdplane
Stops sdplane.
sudo systemctl restart sdplane
Restarts sdplane. Use this after changing the configuration file.
systemctl status sdplane
Shows the status of sdplane.
sudo systemctl enable sdplane
Starts sdplane automatically at boot. This is enabled at installation.
sudo systemctl disable sdplane
Stops sdplane from starting automatically at boot.

Minimal Switch Configuration

sdplane-switch.conf is a minimal configuration that runs sdplane as a 4-port switch.

Note: The router worker thread supports both L2 switching and L3 forwarding, so the switch configuration below is an example of building a switch with the router worker.

Diagram of the sdplane-switch.conf configuration

The four NICs at PCI addresses 01:00.0, 01:00.1, 02:00.0 and 03:00.0 are connected to vswitch 10, which operates as a 4-port switch.

vswitch 10 also has two tap interfaces, port-1-00-0 and capture-1-00-0. From Linux, you can obtain an address with DHCP on port-1-00-0 and provide ssh, and run tcpdump on capture-1-00-0 to monitor packets.

Common Commands

Run these after connecting to the CLI with telnet.

telnet localhost 9882
show port
Lists each port's device (PCI address), link status, speed, driver and uptime.
show port statistics pps
Shows received and transmitted packets per second and error counts for each port.
show thread
Shows the lcore, type (lthread / dpdk), function and loops per second of each thread.
show vswitch
Shows each vswitch's VLAN, attached ports, and the router-if and capture-if tap interfaces.

Router Configuration

sdplane-router.conf is an example configuration that runs sdplane as a 2-port router.

Diagram of the sdplane-router.conf configuration

Port 0 (01:00.0) is connected to vswitch 10, and port 3 (03:00.0) to vswitch 20. Ports 1 (01:00.1) and 2 (02:00.0) are also bound to sdplane but are not connected to any vswitch.

Each vswitch has a router-if and a capture-if, so Linux sees two router-ifs, port-1-00-0 and port-3-00-0. Configure addresses and routes on Linux with iproute2 or FRR so that it routes between these two interfaces. sdplane reads the Linux routing configuration and offloads packet forwarding, forwarding packets cut-through without going through Linux.

To use this configuration, place sdplane-router.conf instead of sdplane-switch.conf in step 4.

wget https://www.yasuhironet.net/dist/sdplane-router.conf
sudo mv sdplane-router.conf /etc/sdplane/sdplane.conf
sudo vi /etc/sdplane/sdplane.conf

An example with iproute2. Change the addresses to match your network.

sudo ip addr add 192.168.10.1/24 dev port-1-00-0
sudo ip addr add 192.168.20.1/24 dev port-3-00-0

Checking the Router Configuration

Check the routes configured on Linux on Linux itself.

ip route
Shows the Linux routing table. Check that routes to the router-ifs (port-1-00-0, port-3-00-0) are present.

Use the sdplane CLI to check that sdplane has picked up the Linux configuration.

show rib router-if
Shows the tap name, MAC address and IPv4 / IPv6 addresses of each router-if.
show rib ipv4 route
Shows the IPv4 routes sdplane has learned from Linux (destination, next hop, interface).
show fib ipv4 route
Shows the IPv4 routing table the router worker actually uses for forwarding.
show neighbor ipv4
Shows the ARP table (MAC addresses of next hops).

Documentation

English | 日本語 | Français | 中文 | Deutsch | Italiano | 한국어 | ไทย | Español

Contact

sdplane [at] nwlab.org